gnomonlearn
Docs/RFC-0011/Reference catalog

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.

← Read the authored RFC

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

TermMeaning
@ decoratorSyntactic sugar (@FacetName or @[FacetA, FacetB]) that desugars to annotation facet applications; arguments are forbidden.
annotation aspectA governance-driven declaration that pushes annotation metadata onto declarations matching a selector (push model); the targeted declaration does not opt in.
annotation facetA 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 schemaAn opt-in module-level governance declaration listing the annotation facets recognized and validated within the module.
annotations blockAn inline { } block inside a declaration body providing or overriding annotation key-value pairs; highest-precedence source in resolution.

Diagnostics

CodeSeverityDescription
M08770Error@ decorator references a semantic facet rather than an annotation facet.
M08771ErrorRequired annotation facet field has no value after merge — no default declared and not supplied at use site.
M08772Errorannotation facet declares a field whose name conflicts with a reserved annotation key.
M08773ErrorTwo @ decorators on the same declaration define the same annotation key — must be resolved with inline override.
M08774Info@ decorator and annotation aspect define the same key; @ decorator wins.
M08775WarningTwo annotation aspects push the same key onto the same declaration; first-defined wins.
M08776DefectAnnotation value present in runtime storage schema or kernel input (compile-time boundary violation).
M08777Errorannotation aspect produces non-annotation structure; annotation aspects MUST NOT contribute runtime fields.
M08778WarningDeclaration references an annotation facet not listed in the active annotation schema.
M08779Error@ decorator or inline annotation reference applies a facet to a declaration kind not listed in the facet’s targets constraint.
M11800WarningDeclaration applies two annotation facets mutually listed in each other’s conflicts-with constraints; merge proceeds but values may conflict.
M11801ErrorAnnotation facet applied without a co-required facet listed in its requires constraint.
M11802ErrorCircular requires dependency detected in annotation facet declarations; declared at facet definition time.
M11803ErrorAnnotation syntax requires an RFC-0011-aware compiler; unsupported syntax is rejected before compilation or install.

Invariants

  1. Annotation aspect fields MUST NOT contribute runtime structure. (enforced by: compile-time)
  2. Annotation facet fields MUST NOT appear in runtime entity instance storage or field schemas. (enforced by: compile-time)
  3. Annotation values MUST NOT be passed to the runtime kernel. (enforced by: compile-time)
  4. Circular requires chains among annotation facets MUST be detected and rejected at facet declaration time, not at use sites. (enforced by: compile-time)
  5. The @FacetName form MUST reference a declared annotation facet, never a semantic facet. (enforced by: compile-time)
  6. The annotation resolution model in section 5 is normative and MUST be implemented exactly without alternative orders. (enforced by: compile-time)
  7. Two @ decorators on the same declaration MUST NOT define overlapping annotation keys without an inline annotations block resolution. (enforced by: compile-time)
  8. 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)
  9. When an annotation facet declares a targets constraint, it MUST only be applied to declaration kinds in that list. (enforced by: compile-time)
  10. 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)

  1. SHOULD — Authors SHOULD resolve aspect-vs-aspect key conflicts via an explicit inline annotations override.
  2. 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)
  3. MUST — The compiler MUST resolve annotations in a deterministic merge pass with precedence: inline annotations block, @ decorators (alphabetical), then annotation aspects (definition order).
  4. 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

  1. MAY — Modules MAY declare an annotation schema listing the facets recognized within the module.

Compatibility and Migration

  1. 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

  1. 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)
  2. MUST — Applying a facet to a declaration kind not in its targets list MUST produce M08779. (proof citation: rfc0011_b21_grounded; verification pending)
  3. MUST — Applying a facet without a co-required facet listed in requires MUST produce M11801. (proof citation: rfc0011_b27_grounded; verification pending)
  4. MUST — Circular requires chains among annotation facets MUST produce M11802 at facet declaration time. (proof citation: rfc0011_b23_grounded; verification pending)
  5. MUST — Conflicts-with violations MUST produce warning M11800 but MUST NOT reject the combination.

Invariants

  1. MUST — An annotation facet with a targets constraint MUST only be applied to listed declaration kinds.
  2. MUST_NOT — Annotation aspect fields MUST NOT contribute runtime structure; the compiler MUST enforce this. (proof citation: rfc0011_b19_grounded; verification pending)
  3. 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)
  4. MUST_NOT — Annotation values MUST NOT be passed to the runtime kernel.
  5. MUST — The @FacetName form MUST reference a declared annotation facet and MUST NOT reference a semantic facet.
  6. 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)
  7. MUST_NOT — Two @ decorators on the same declaration MUST NOT define overlapping annotation keys without an inline annotations { } resolution.
  8. MUST — When a facet declares requires, every co-required facet MUST be present on the same declaration from any source.

Security and Authorization

  1. 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)
  2. 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)