RFC-0011 · Reference catalog
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.
Generated reference catalog. This page renders structured Lean data for RFC-0011: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in
RFC-0011.This page is generated from the
lean/Gnomon/Spec/module for RFC-0011. Edit that source and regenerate this catalog.
Title: Annotation System
Status: draft
Owners: Compiler, DX, Governance
Proof citations in source: 11 / 11. Standalone proof verification is pending.
Definitions
| Term | Meaning |
|---|---|
| @ decorator | Syntactic sugar (@FacetName or @[FacetA, FacetB]) that desugars to annotation facet applications; arguments are forbidden. |
| annotation aspect | A governance-driven declaration that pushes annotation metadata onto declarations matching a selector (push model); the targeted declaration does not opt in. |
| annotation facet | A named, reusable set of declaration-level metadata keys (pull model); a restricted form of FacetType where the declaration opts in via @FacetName or annotations { }. |
| annotation schema | An opt-in module-level governance declaration listing the annotation facets recognized and validated within the module. |
| annotations block | An inline { } block inside a declaration body providing or overriding annotation key-value pairs; highest-precedence source in resolution. |
Diagnostics
| Code | Severity | Description |
|---|---|---|
M08770 | Error | @ decorator references a semantic facet rather than an annotation facet. |
M08771 | Error | Required annotation facet field has no value after merge — no default declared and not supplied at use site. |
M08772 | Error | annotation facet declares a field whose name conflicts with a reserved annotation key. |
M08773 | Error | Two @ decorators on the same declaration define the same annotation key — must be resolved with inline override. |
M08774 | Info | @ decorator and annotation aspect define the same key; @ decorator wins. |
M08775 | Warning | Two annotation aspects push the same key onto the same declaration; first-defined wins. |
M08776 | Defect | Annotation value present in runtime storage schema or kernel input (compile-time boundary violation). |
M08777 | Error | annotation aspect produces non-annotation structure; annotation aspects MUST NOT contribute runtime fields. |
M08778 | Warning | Declaration references an annotation facet not listed in the active annotation schema. |
M08779 | Error | @ decorator or inline annotation reference applies a facet to a declaration kind not listed in the facet’s targets constraint. |
M11800 | Warning | Declaration applies two annotation facets mutually listed in each other’s conflicts-with constraints; merge proceeds but values may conflict. |
M11801 | Error | Annotation facet applied without a co-required facet listed in its requires constraint. |
M11802 | Error | Circular requires dependency detected in annotation facet declarations; declared at facet definition time. |
M11803 | Error | Annotation syntax requires an RFC-0011-aware compiler; unsupported syntax is rejected before compilation or install. |
Invariants
- Annotation aspect fields MUST NOT contribute runtime structure. (enforced by: compile-time)
- Annotation facet fields MUST NOT appear in runtime entity instance storage or field schemas. (enforced by: compile-time)
- Annotation values MUST NOT be passed to the runtime kernel. (enforced by: compile-time)
- Circular requires chains among annotation facets MUST be detected and rejected at facet declaration time, not at use sites. (enforced by: compile-time)
- The @FacetName form MUST reference a declared annotation facet, never a semantic facet. (enforced by: compile-time)
- The annotation resolution model in section 5 is normative and MUST be implemented exactly without alternative orders. (enforced by: compile-time)
- Two @ decorators on the same declaration MUST NOT define overlapping annotation keys without an inline annotations block resolution. (enforced by: compile-time)
- When an annotation facet declares a requires constraint, every co-required facet MUST be present on the same declaration after merge. (enforced by: compile-time)
- When an annotation facet declares a targets constraint, it MUST only be applied to declaration kinds in that list. (enforced by: compile-time)
- conflicts-with constraints are advisory: the compiler MUST warn but MUST NOT reject the annotation combination. (enforced by: compile-time)
Normative Statements
Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.
Annotation Resolution Model (Normative)
- SHOULD — Authors SHOULD resolve aspect-vs-aspect key conflicts via an explicit inline annotations override.
- MUST — Every annotation facet field lacking a default MUST be supplied by the use site or M08771 is produced. (proof citation:
rfc0011_b0_grounded; verification pending) - MUST — The compiler MUST resolve annotations in a deterministic merge pass with precedence: inline annotations block, @ decorators (alphabetical), then annotation aspects (definition order).
- MUST_NOT — The merged annotation map MUST NOT appear in runtime storage, be passed to the kernel reducer, or influence runtime authorization. (proof citation:
rfc0011_b3_grounded; verification pending)
Annotation Schema Declaration
- MAY — Modules MAY declare an annotation schema listing the facets recognized within the module.
Compatibility and Migration
- MUST — Parsers that do not implement RFC-0011 MUST reject annotation-facet-decl, annotation-aspect-decl, decorated-decl, and annotation-block syntax with M11803 before compilation or install, naming the required compiler version or feature.
Grammar Extensions to RFC-0008
- MUST — A required annotation facet field (no default) MUST be supplied at every use site; absence produces M08771. (proof citation:
rfc0011_b17_grounded; verification pending) - MUST — Applying a facet to a declaration kind not in its targets list MUST produce M08779. (proof citation:
rfc0011_b21_grounded; verification pending) - MUST — Applying a facet without a co-required facet listed in requires MUST produce M11801. (proof citation:
rfc0011_b27_grounded; verification pending) - MUST — Circular requires chains among annotation facets MUST produce M11802 at facet declaration time. (proof citation:
rfc0011_b23_grounded; verification pending) - MUST — Conflicts-with violations MUST produce warning M11800 but MUST NOT reject the combination.
Invariants
- MUST — An annotation facet with a targets constraint MUST only be applied to listed declaration kinds.
- MUST_NOT — Annotation aspect fields MUST NOT contribute runtime structure; the compiler MUST enforce this. (proof citation:
rfc0011_b19_grounded; verification pending) - MUST_NOT — Annotation facet fields MUST NOT appear in runtime entity instance storage or field schemas; the compiler MUST enforce this at schema emission. (proof citation:
rfc0011_b5_grounded; verification pending) - MUST_NOT — Annotation values MUST NOT be passed to the runtime kernel.
- MUST — The @FacetName form MUST reference a declared annotation facet and MUST NOT reference a semantic facet.
- MUST — The annotation resolution model in §5 MUST be implemented exactly as specified; alternative resolution orders are forbidden. (proof citation:
rfc0011_b30_grounded; verification pending) - MUST_NOT — Two @ decorators on the same declaration MUST NOT define overlapping annotation keys without an inline annotations { } resolution.
- MUST — When a facet declares requires, every co-required facet MUST be present on the same declaration from any source.
Security and Authorization
- MUST — Annotation aspect declarations in governance modules MUST undergo the same install-plan review and approval as policy declarations. (proof citation:
rfc0011_b25_grounded; verification pending) - MUST_NOT — Annotation values MUST NOT be used in runtime authorization decisions; policy logic belongs in policy declarations. (proof citation:
rfc0011_b8_grounded; verification pending)
Linked References
(no cross-RFC dependencies)