RFC-0011 annotation authoring and bundle proposal
Versioned draft snapshot
RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.
Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.
This is a trace and gap record from the pinned draft specification. It does not establish proof or implementation conformance.
Status: owner approved integrated grammar and older-parser rejection. Other first-release decisions in this proposal remain open. Owners: Compiler, DX, Governance, and core library. Nothing is deployed, so these are source and artifact contract choices rather than live migrations.
The framework’s older Lean .gnm parser now rejects @ decorators,
annotation declarations, and inline annotations blocks with M11803
(gnomon commit ab97c2462). Top-level @ is retained by its lexer;
field-level @epistemic(...) remains valid. Parser fixtures, the 253-file
parse corpus, semantic unit tests, and emitter unit tests pass. The full
semantic corpus remains red on 12 preexisting AI output errors. This is an
older-parser safety gate; annotation resolution and bundle behavior still
require an RFC-0011-aware compiler.
Evidence and decisions
Older parsers and decorator grammar
RFC-0011 §10 previously required parsers without annotation support to skip
four grammar productions without error. It gave no token-boundary or nested-body
recovery rule. Skipping an annotation aspect could silently discard mandatory
governance metadata, and skipping a decorated declaration could discard its
declaration. RFC-0011 §4.1 defines decorated-decl with @ IDENT, while §4.5
redefines it to include grouped @[...]. Both use zero-or-more repetition,
so they also match an undecorated declaration; both recurse through
top-level-decl, which itself includes decorated-decl. The first-release
grammar must use one-or-more decorators followed by an undecorated target.
The current §4.5 single-facet example has one entity AuditLog { opening
line and needs no repair.
Recommend: an older parser rejects unsupported annotation syntax with a
stable, feature-specific diagnostic before compilation or install. Allocate a
new RFC-0011 diagnostic M11803 (now registered in the Lean catalog)
and include the minimum required compiler version or feature in the message.
Keep one decorated-decl grammar production accepting both single and grouped
decorators. The alternative is to retain
forward-skipping, but then specify balanced-body tokenization, decorator
attachment, nested blocks, and a rule that skipped governance declarations
block publication rather than disappear silently.
Complete grammar composition
RFC-0011 §4.1 previously wrote top-level-decl ::= ... and
entity-prop ::= .... Those were extension sketches, not grammar productions.
The earlier extracted bundle had five structural failures: two literal
placeholders and duplicate top-level-decl, entity-prop, and
decorated-decl definitions. RFC-0008 §8.2/§8.6 now owns the integrated
top-level and entity rules, and the structural gate reports zero problems.
The eleven open-body declaration kinds named by RFC-0008 §6.0 now have
explicit annotation-block placements. The structure gate checks all eleven
bindings and reports zero problems. PEG validation and compiler fixtures
remain open, so this is source integration rather than parser conformance.
Approved direction: keep RFC-0008 as the owner of the integrated top-level and
body-property grammar, and RFC-0011 as the owner of annotation-specific
productions. Define bare-top-level-decl once for all undecorated forms,
including annotation-facet-decl and annotation-aspect-decl;
top-level-decl then selects a bare or decorated form. Define exactly one
decorated-decl as one or more decorator NEWLINE pairs followed by a
bare-top-level-decl, preventing empty matches and recursive nesting.
Expand annotation-block explicitly in each eligible braced declaration
body’s property production. Delete the ::= ... sketches from extracted
EBNF and retain prose cross-references in RFC-0011. A declaration form with
no braced body is not an inline annotation-block target. Record which
declaration kinds can take a decorator; grammar may accept a broader set
only if a deterministic semantic diagnostic rejects disallowed targets.
Before accepting that grammar, compare all extracted EBNF blocks with the compiler surface: currently 42 blocks, comprising RFC-0008’s 38 §8 blocks and RFC-0011’s four §4 blocks. Add positive fixtures for a single decorator, grouped decorators, and an inline block on each supported declaration family; add negative fixtures for empty decorators, nested decorators, unsupported targets, and a missing closing body. Regenerate the EBNF, Lean and RDF catalogs, diagnostic inventory, and source-bound reviews from authored sources. The strict structure gate should then report zero duplicate and placeholder productions; PEG validation and compiler fixtures remain separate release gates.
Decorator-versus-aspect conflict
RFC-0011 §5.1 says decorator values win “silently” when an annotation aspect defines the same key, while the same row names M08774 as an informational diagnostic. The Lean catalog defines M08774 as Info. The winner is clear; the diagnostic behavior is not.
Recommend: the decorator wins and M08774 is emitted at Info severity. Replace “silently” with “without warning or error; emit M08774 for traceability.” The alternative is no diagnostic, which requires retiring or repurposing an already assigned code under RFC-0000’s diagnostic identity rules.
Bundle placement and standard facet
RFC-0011 §5.3 writes the merged annotation map into declaration metadata.
RFC-0002 §4 lists a required declarations section but no explicit annotation
field. RFC-0011’s companion Q&A instead says annotation values live in
composition_envelopes; RFC-0002 reserves those envelopes for route, page,
layout, and widget elements. The Q&A also requires a built-in @Governance
facet from gnomon.core, but neither RFC-0011’s authored grammar/examples nor
RFC-0035 currently define its standard-library identity.
Recommend: add an optional, typed annotation map to each applicable
declaration record in RFC-0002’s declarations section. Its boundary DTO
should be a versioned protobuf message, with deterministic key ordering and
no runtime entity-storage or kernel input projection. Correct the Q&A’s
composition_envelopes answer. Specify @Governance in RFC-0035 with the
four Q&A keys, its import behavior, and an example, or explicitly defer it and
remove the Q&A’s MUST before first publication. Using
composition_envelopes instead would need a contract for non-UI declarations
and runtime exclusion, not an implicit reuse of a UI-specific section.
Acceptance
- Decide unsupported-parser behavior, M08774 emission, and annotation map
bundle placement. Decide whether
@Governanceis first-release standard library or a deferred proposal. Record the choices in RFC-0011’s Q&A. - Align RFC-0011, RFC-0002, RFC-0035, Lean statements and diagnostics, protobuf bundle schema, RDF claims, and generated reference catalogs. Use one decorator grammar production and validate the existing single-facet example.
- Test an older parser against each new production; test single and grouped decorators; test aspect/decorator conflict diagnostics and precedence; round-trip annotation maps through compiled bundles and tooling. Verify annotation values never enter storage schemas, entity instances, kernel input, or runtime authorization decisions.
- Refresh source-bound proof and projection reviews after normative edits. Run corpus, diagnostic, RDF, bundle, site, and first-release integration gates against the same pinned source revision.