refcount linter

[dozreg-toplud]

This PR contains the refcount linter, comment annotations for the linter as well as some jet fixes that are also PR'd separately in #1058.

The linter itself is fully vibecoded for now and I can't guarantee that it doesn't produce false negatives (it already did on previous iterations). At some point I'll rewrite the abstract interpreter.

What I would like to understand is whether the annotation grammar is uncontroversial. The annotations are placed either on functions, blocks of code (e.g. if we transfer a noun to some persistent structure) or the entire files (e.g. to supress checks for nock.c)

TODO:

• Reread/rewrite the abstract interpreter
• Add checking borrowed reference correctness considering unifying equality

Depends on #1057, #1079, #1080

[dozreg-toplud]

Notes from core blitz:

• Need more clear annotation for "custom" case:
  • functions in a "custom" file are all custom unless they have some @Refcount annotations
  • a "custom" function may only be called by custom functions and functions with asserted (i.e. not checked) refcount protocol

I'll describe refcount annotation syntax here:

• A refcount annotation starts with @Refcount:, followed by a space and a refcount directive.

• A refcount annotation of a function may appear in the header comment of a function definition, the header comment of a function declaration, or the same line as the function declaration if it spans for just one line:

/*  @Refcount: retain
 *  (header comment)
*/
u3_noun
foo(u3_noun a)
{ ... }

u3_noun bar(u3_noun u3_noun); // @Refcount: transfer (same line for declarations is OK)

• A refcount annotation of a code block may appear on the same line as the opening brace:

if ( condition ) {  //  @Refcount: assert transfer (this assignement consumes)
  *ptr_u = u3k(u3h(list));
}

• A refcount annotation of a file may appear in the first 4KB of a file:

//  @Refcount: assert custom file

• Unless there is ambiguity, @Refcount: X, Y, Z is same as:

//  @Refcount: X
//  @Refcount: Y
//  @Refcount: Z

• The function refcount directives are applied in order top to bottom, with each directive changing the refcount protocol of the function. If there are conflicting directives then the last one wins, but a warning about conflicting directives is raised.

• A function must have the same directives across all its declarations and its definition.

• If a function has no directive, and the file is not custom, then its refcount protocol is governed by the rules layed out in u3.md:

  • By default it transfers its arguments and its product;
  • u3r_*, u3x_*: retain arguments and the product;
  • u3q*, u3w*, u3z_*: retain arguments, transfer the product;
  • static functions or _-named functions in jets/[a-f]/: retain args, transfer product

• If a function has no directive, and the file is custom, the function follows "custom" transfer protocol. It can be only called by other custom functions and functions with asserted refcount protocol.

• List of refcount directives for a function:

  • assert: the body of the function is not checked
  • assert custom: marks the function as "custom". No other directives may be present
  • transfers product: the product of the function is owned by the caller
  • transfers `x`, `y`, `z`: the function takes ownership of the listed arguments
  • transfers arguments: the function takes ownership of all arguments
  • transfers: the function takes ownership of all arguments and the product of the function is owned by the caller
  • retains ...: as transfers, mutatis mutandis: the product is an uncounted reference, arguments are borrowed
  • passthrough `x`: identity: the product IS argument x, with unchanged ownership, counts are untouched
  • direct `x`, `y`, `z`: if the function returned, these arguments were direct
  • direct product: the product is a direct atom
  • direct arguments: if the function returned, all arguments were direct

• List of refcount directives for a code block:

  • assert transfer `x`, `y`, `z`: if these variables were assigned, that assignement consumed them. Useful for assignements to persistent data structures or in defcons patterns;
  • assert retain `x`, `y`, `z`: the block has no effect on these variables

• List of refcount directives for a file:

  • assert custom file: marks the file as custom. Can be used in low-level parts of Vere like nock.c to supress checks, especially for tricky protocols like semitransfer.