Repository navigation
Open
Labels
P2SoonSooncompilerParser, IR, CASParser, IR, CASenhancementNew feature or requestNew feature or request
Description
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 siblingValidatorRefunits 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-offValidatorList.
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 composableValueType:List(T);Call(kind);Ref(EnumOf(E) | Decl(kind) | Field);- the existing scalars.
- Validators become an ordinary annotation:
@validatorsisList(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
Propertygaining 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_unitsininterpreter/incremental.rsstill turns every@key = [X(...)]intoValidatorRefunits and drops the key), references (Ref(...)),@validatorsas an ordinary annotation, a structured value onPropertyfor lists, calls and references, and grammar support for annotations on enums and enum variants (@phases,@initial).
Metadata
Metadata
Assignees
Labels
P2SoonSooncompilerParser, IR, CASParser, IR, CASenhancementNew feature or requestNew feature or request
Type
Projects
- StatusShow more project fieldsTodo
Activity
Kinflou commentedon Oct 19, 2026
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.Kinflou commentedon Oct 20, 2026
Decided 2026-10-20:
@x(k = v)form. Every annotation keeps@name = value; typed values gain a block value{ k = v }(theconfig.idp/settings syntax), checked against the annotation's spec. E.g.@rate_limit = { count = 100, per_ms = 1000 }.Propertygains 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).Kinflou commentedon Nov 9, 2026
#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.Kinflou commentedon Nov 15, 2026
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.