Skip to content

Typed annotation values: lists, calls and references for any annotation #124

Open

Description

@Kinflou

Proposed (from the packet-dispatch discussion, #123, 2026-10-20). Partly built, see Status below.

Problem

Annotation values have a fixed set of shapes, and lists are special-cased:

  • Any list annotation becomes validator calls. annotation_units (interpreter/incremental.rs) turns @key = [X(...)] into sibling ValidatorRef units and drops the key. So @foo = [X()] is indistinguishable from @validators = [X()], and no other annotation can take a list.
  • ValueType (config_value.rs), shared by annotations and settings keys, is a flat set: Marker, Bool, Integer, Str, StrEnum, Keyword, Name, BoolOrStr, plus a one-off ValidatorList.

Upcoming annotations need more:

  • @phase = [Login, Play] (a list of enum variants);
  • @reply = PlayClientbound.pong (a reference to a declaration);
  • @match = nonce (a reference to a field);
  • possibly keyed values.

Annotations generally use similar types, restricted by context.

Proposal

  • One value model, parsed generically and typed by the annotation's spec. The parser produces a value tree: scalar, list, call Name(k = v, …), path/reference, possibly keyed. The known annotation's spec then checks it against a composable ValueType:
    • List(T);
    • Call(kind);
    • Ref(EnumOf(E) | Decl(kind) | Field);
    • the existing scalars.
  • Validators become an ordinary annotation: @validators is List(Call(Validator)). The list special case and the dropped key go away.
  • Context restriction stays where it is: the spec's scopes (where the annotation may appear) and, for references, what they may point at (an enum's variants, a protocol's functions, a function's fields).
  • Settings share it. Settings keys already use ValueType. Both get the richer types, so a settings default can carry any annotation's value (Settings blocks supply annotation defaults #125).
  • Unknown annotations (the open namespace) keep their value tree untyped, still frozen, so nothing is lost.

Open

  • Whether keyed values (@x(k = v)) are needed once lists and references exist.
  • How the frozen IR represents typed values (a new unit, or Property gaining a structured value) and its format stamp.

Status (2026-11-16)

  • Built: a block value @k = { a = 1 } (core a5d6f85, with the framing dictionary form), checked against the annotation's spec (ValueType::Dict); and the keyed form @k(a = 1), which freezes to the same dictionary (core#265, 66feecb).
  • The 2026-10-20 decision "no @x(k = v) form" no longer holds. The accepted shared-vocabulary proposal (docs#162) uses the keyed @unverified(guarantee = "reason"), so the keyed form exists and means exactly @k = { ... }; writing both is an error (annotations::both-forms).
  • Not built: lists of anything but validators (annotation_units in interpreter/incremental.rs still turns every @key = [X(...)] into ValidatorRef units and drops the key), references (Ref(...)), @validators as an ordinary annotation, a structured value on Property for lists, calls and references, and grammar support for annotations on enums and enum variants (@phases, @initial).

Activity

  1. Kinflou commented on Oct 19, 2026

    @Kinflou
    MemberAuthor

    Two more uses from the phase-syntax decision (ComlineProject/docs#56): @phases (a marker on an enum) and @initial (a marker on an enum variant). Today the grammar allows annotations on neither enums nor enum variants.

  2. Kinflou commented on Oct 20, 2026

    @Kinflou
    MemberAuthor

    Decided 2026-10-20:

    • No @x(k = v) form. Every annotation keeps @name = value; typed values gain a block value { k = v } (the config.idp/settings syntax), checked against the annotation's spec. E.g. @rate_limit = { count = 100, per_ms = 1000 }.
    • IR: Property gains a structured value (scalar, list, block, call, reference) rather than a new unit kind; unknown annotations keep their untyped tree there. References are stored resolved, as full paths, so renames are detected. The IR format stamp is bumped (CBOR is name-keyed, so older stored values still read).
  3. Kinflou commented on Nov 9, 2026

    @Kinflou
    MemberAuthor

    #222 (granular @unverified) needs keyed annotation values: @unverified(encoding_conformance = "…", bounded_size = "…"), with keys checked against a vocabulary of guarantees (#219, ComlineProject/docs#162). That's one more concrete user of this.

  4. Kinflou commented on Nov 15, 2026

    @Kinflou
    MemberAuthor

    Audit 2026-11-16: added a Status section (original saved in the audit notes). Built: the block value and the keyed form @k(a = 1), which freezes to the same dictionary (core#265). The decision 'no @x(k = v) form' was reversed by the accepted shared-vocabulary proposal (docs#162). Not built: lists other than validators, references, @Validators as an ordinary annotation, a structured IR value, and annotations on enums and variants.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions