gnomonlearn
Docs/RFC-0011 annotation authoring and bundle proposal

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

  1. Decide unsupported-parser behavior, M08774 emission, and annotation map bundle placement. Decide whether @Governance is first-release standard library or a deferred proposal. Record the choices in RFC-0011’s Q&A.
  2. 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.
  3. 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.
  4. 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.