RFC-0011 · Annotation System
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.
| Status | Draft corpus. Reference catalogs and RDF projections have generation drift checks; Gnomon proofs and projection semantics remain unverified for release. |
|---|
View the generated reference catalog →
Read design questions and decisions →
Status: Draft Owners: DX, Compiler, Governance
1. Scope
Defines the annotation system for Gnomon: the mechanism by which declaration-level metadata is attached to, composed across, and resolved on .gnm declarations. This RFC extends the base grammar defined in RFC-0008 §8.
The annotation system provides a typed, queryable metadata layer on top of the semantic type model. Annotation values exist only at compile time — they are emitted into the compiled bundle as declaration metadata and are never present in runtime entity instances or storage schemas.
This RFC covers:
annotation facetdeclarations — named, reusable sets of metadata keys (pull model)annotation aspectdeclarations — governance-driven metadata pushed onto matching declarations (push model)- The
annotations { }inline block — declaration-local key-value overrides - The
@FacetNamedecorator sugar — shorthand for attaching an annotation facet - The normative annotation resolution model — precedence, conflict rules, completeness checks
2. Goals
- Provide a typed, queryable metadata layer without polluting the semantic type model with non-runtime concerns
- Reuse the existing facet/aspect kernel; annotation facets and annotation aspects mirror the pull/push distinction of FacetType and aspect
- Keep annotation metadata strictly compile-time; the compiler enforces the boundary at schema emission
- Define a single, normative resolution order so annotation values are predictable regardless of how many sources contribute
- Enable governance-driven annotation via annotation aspects so compliance metadata is not dependent on author diligence
Linked References
The cross-RFC dependency graph is rendered in reference catalog § Linked References. Out-of-KG pointers to legacy code or external resources, when present, remain in this document under “Source-tree references” below.
3. Invariants
- Annotation facet fields MUST NOT appear in runtime entity instance storage or field schemas. The compiler MUST enforce this at schema emission time.
- Annotation aspect fields MUST NOT contribute runtime structure. The compiler MUST enforce this.
- The
@FacetNameform MUST reference a declaredannotation facet; it MUST NOT reference a semanticfacet. Violations produce error M08770. - Two
@decorators on the same declaration MUST NOT define overlapping annotation keys unless an inlineannotations { }block provides an explicit resolution. Violations produce error M08773. - The annotation resolution model in §5 is normative and MUST be implemented exactly as specified. Implementations MUST NOT define alternative resolution orders.
- Annotation values MUST NOT be passed to the runtime kernel (RFC-0010). Presence of annotation values in kernel input is a compiler violation (M08776).
- When an annotation facet declares a
targetsconstraint, it MUST only be applied to declaration kinds listed in that constraint. Violations produce error M08779. - When an annotation facet declares a
requiresconstraint, every listed co-required facet MUST be present on the same declaration (contributed by any source:@decorator,annotation aspect, or inline block). Violations produce error M11801. - Circular
requireschains among annotation facets MUST be detected and rejected at facet declaration time (M11802). They MUST NOT be detected only at use sites. conflicts-withconstraints are advisory. The compiler MUST warn (M11800) but MUST NOT reject the annotation combination.
4. Grammar Extensions to RFC-0008
This section defines the grammar productions that extend RFC-0008 §8. All terminal tokens and shared productions from RFC-0008 §8.1 and §8.22 apply.
4.1 Extension Points
RFC-0008 §8.2 owns the integrated top-level-decl and
bare-top-level-decl productions. The latter includes the annotation facet
and aspect declarations defined below. A decorated declaration contains one
or more decorators followed by a bare declaration, so an undecorated
declaration cannot match decorated-decl and decorators cannot nest through
top-level-decl. RFC-0008 includes annotation-block in the property
productions for its open-body declaration kinds; this RFC includes it in
annotation facet bodies and uses it as the body of an annotation aspect.
The grammar owns each placement explicitly.
4.2 Annotation Facet Declaration
An annotation facet is a named, reusable set of declaration-level metadata keys. It is a restricted form of FacetType (RFC-0006 §4.2): the pull model applies — a declaration opts in by applying @FacetName or including the facet in its annotations { } block. The entity controls inclusion.
annotation-facet-decl ::= [ visibility-modifier ] "annotation" "facet" IDENT
"{" annotation-facet-body "}"
annotation-facet-body ::= { annotation-facet-prop }
annotation-facet-prop ::= "meaning" ":" STRING NEWLINE
| targets-constraint
| conflicts-with-constraint
| requires-constraint
| annotation-field-decl
| annotation-block
annotation-field-decl ::= IDENT ":" annotation-type [ "=" annotation-value ] NEWLINE
annotation-type ::= "String" | "Boolean" | "Number" | IDENT
annotation-value ::= STRING | NUMBER | "true" | "false" | IDENT
targets-constraint ::= "targets" "[" kind-name { "," kind-name } "]"
conflicts-with-constraint ::= "conflicts-with" ident-set (* ident-set from RFC-0008 §8.22 *)
requires-constraint ::= "requires" ident-set (* ident-set from RFC-0008 §8.22 *)
kind-name ::= "entity" | "facet" | "relation" | "action" | "query" | "procedure"
| "mutation" | "task" | "workflow" | "saga" | "agent" | "policy"
| "api" | "serve" | "event" | "variant" | "compute" | "integration"
An annotation facet MUST declare exactly one meaning. Its targets,
conflicts-with, and requires constraints are optional singleton
properties; duplicate occurrences are errors. Fields and the inline
annotation block may appear in any order.
A field with a default (= value) provides that value at any use site that does not explicitly override it. A field without a default is required at every use site; absence produces error M08771.
4.2.1 targets Constraint
targets is an optional list of declaration kinds that this annotation facet is permitted to be applied to. When declared:
- Applying this facet (via
@FacetNameorannotations {}) to a declaration whose kind is not in the list MUST produce error M08779. - When
targetsis absent the facet may be applied to any declaration kind.
The check is enforced at the use site after decorator desugaring. This is the mechanism for facets that are structurally meaningful only on certain declaration classes (e.g., a RetentionPolicy facet that only makes sense on entity and relation declarations).
4.2.2 conflicts-with Constraint
conflicts-with is an optional list of other annotation facet names that this facet is declared to be semantically incompatible with. When declared:
- If a declaration applies both this facet and a listed facet (via
@decorators orannotations {}), the compiler MUST produce warning M11800. - This is advisory — the merge still proceeds (highest-precedence source wins per §5). Authors SHOULD resolve the conflict with an explicit inline
annotations {}override. conflicts-withis symmetric by convention but is not automatically bidirectional. IfA conflicts-with [B]butBdoes not listA, onlyA’s constraint is checked.
Advisory rather than error: annotation facets may be composed in ways that are locally valid even when their defaults conflict. The warning ensures authors audit the combination rather than silently inheriting conflicting values.
4.2.3 requires Constraint
requires is an optional list of other annotation facet names that must be co-applied wherever this facet is applied. When declared:
- If a declaration applies this facet but does not also apply every facet listed in
requires, the compiler MUST produce error M11801. - The co-presence check is applied after all decorator and aspect sources are merged (post-desugar, pre-semantic-analysis), so a facet contributed by an
annotation aspectsatisfies the requirement. - Circular
requireschains (A requires B, B requires A) MUST produce error M11802 at annotation facet declaration time, not at use sites.
Example:
annotation facet SensitiveData {
meaning: "Marks a declaration as containing PII-level sensitive data."
targets [entity, relation]
conflicts-with [PublicData]
requires [DomainOwnership]
domain: String
sensitivity: String = "PII"
requiresEncryption: Boolean = true
}
annotation facet SOXGoverned {
meaning: "Marks a declaration as subject to SOX compliance tracking."
targets [entity]
requires [DomainOwnership]
auditRetentionYears: Number = 7
approvedBy: String
}
annotation facet DomainOwnership {
meaning: "Records the owning team for a declaration."
owner: String
oncall: String = "platform-eng"
}
annotation facet PublicData {
meaning: "Marks a declaration as safe for public disclosure."
conflicts-with [SensitiveData]
classification: String = "public"
}
4.3 Annotation Aspect Declaration
An annotation aspect pushes annotation metadata onto declarations matching a selector. It is a restricted form of aspect (RFC-0004): the push model applies — the aspect controls targeting. The targeted declaration does not opt in.
annotation-aspect-decl ::= [ visibility-modifier ] "annotation" "aspect" IDENT
"on" annotation-target
"{" annotation-block "}"
annotation-target ::= "entity" "where" annotation-predicate
| "facet" "where" annotation-predicate
| "action" "where" annotation-predicate
| QUALIFIED
annotation-predicate ::= annotation-predicate-atom { "and" annotation-predicate-atom }
annotation-predicate-atom ::= "includes" IDENT
| "fields" "contains" type-expr
Example:
annotation aspect AutoAIInteractable on entity where includes AIDraftable {
annotations {
aiInteractable: true
requiresEvidenceAudit: true
}
}
annotation aspect FinancialCompliance on entity where includes FinancialRecord {
annotations {
auditRetentionYears: 7
regulatoryScope: "SOX"
}
}
4.4 Inline Annotation Block
The annotations { } block provides or overrides individual annotation
key-value pairs. It is the highest-precedence source in the resolution model
(§5). It is valid inside the braced open-body declaration kinds named in
RFC-0008 §6.0: entity, type, action, policy, agent, claim, query,
view, model, annotation facet, and annotation aspect. It is not an
inline property of an unbraced import or apply, an expression-only
invariant, or another declaration body without an explicit
annotation-block alternative. Each eligible body has at most one inline
annotation block; duplicate blocks are errors.
annotation-block ::= "annotations" "{" { inline-annotation } "}"
inline-annotation ::= IDENT ":" ( STRING | NUMBER | "true" | "false" | IDENT ) NEWLINE
4.5 @ Decorator Sugar
@FacetName applies a single annotation facet. @[FacetA, FacetB, ...] applies multiple facets in one grouped decorator. Both forms are syntactic sugar — they desugar to annotation facet applications and are semantically identical. Arguments are forbidden on the @ form; use annotations { } for parameterized values.
decorated-decl ::= decorator NEWLINE { decorator NEWLINE } bare-top-level-decl
decorator ::= "@" IDENT
| "@" ident-set (* ident-set defined in RFC-0008 §8.22 *)
gnomon fmt (RFC-0012) canonical form: when multiple facets are applied, they are normalized to a single @[...] group with facet names sorted alphabetically, immediately preceding the declaration keyword with no blank line between the decorator and the keyword. A single @FacetName is preserved as-is.
Desugar: Both forms desugar in the desugar pass (RFC-0008 §8.17) to individual annotation facet applications. The inline annotations { } block desugars to direct annotation field assignments. The desugar pass merges all annotation sources; the resolution model in §5 governs conflicts.
Example — single facet:
@SOXGoverned
entity AuditLog {
annotations { approvedBy: "compliance-team" }
meaning: "An immutable audit event record."
}
Example — multiple facets:
@[DomainOwnership, SOXGoverned]
entity FinancialRecord {
annotations {
domain: "finance"
approvedBy: "compliance-team"
}
meaning: "A financial ledger entry subject to SOX retention policy."
...
}
5. Annotation Resolution Model (Normative)
The compiler resolves the final annotation map for a declaration in a single merge pass, executed after the desugar pass and before semantic analysis. The merge is deterministic and follows this precedence order (highest to lowest):
- Inline
annotations { }block — values defined directly in the declaration body @decorators — values from named annotation facets, in alphabetical order by facet name (canonical order enforced bygnomon fmt)- Annotation aspects — values pushed by matching
annotation aspectdeclarations, in source definition order within the compiled bundle
5.1 Conflict Rules
| Situation | Rule | Diagnostic |
|---|---|---|
Two facets in the same @[...] group (or applied via multiple decorators) define the same key | Error: must resolve with inline annotations { } override | M08773 |
| Decorator-applied facet and annotation aspect define the same key | Decorator wins silently; this is intentional override | M08774 (informational) |
| Two annotation aspects push the same key | First-defined aspect wins; authors SHOULD resolve by adding an explicit inline annotations { } override on the declaration | M08775 (warning) |
Inline annotations { } overrides any source | Inline always wins; no diagnostic | — |
5.2 Completeness Check
After merging, the compiler checks that every annotation facet field that lacks a default value (= value) has been supplied by the use site. Any missing required field produces error M08771. This check applies to fields contributed by both @ decorators and inline annotation facet references.
5.3 Compile-Time Boundary
The merged annotation map is written into the compiled bundle’s declaration metadata section (RFC-0002). It MUST NOT:
- Appear in the runtime storage schema for entity instances
- Be passed to the kernel reducer (RFC-0010)
- Influence field-level type checking or runtime authorization
Any violation of this boundary is a compiler defect and produces M08776.
6. Annotation Schema Declaration
Modules MAY declare an annotation schema — the set of annotation facets that are recognized and validated within the module. This is an opt-in governance mechanism; the absence of a schema does not prevent annotation use.
// In project.gnm or a governance/.gnm file
annotation schema ModuleAnnotations {
includes [SensitiveData, SOXGoverned, DomainOwnership]
}
Declarations that reference annotation facets not listed in the active schema produce warning M08778.
7. Examples
Attaching governance metadata
@[DomainOwnership, SensitiveData, SOXGoverned]
entity FinancialRecord {
annotations {
domain: "finance"
owner: "finance-eng"
approvedBy: "compliance-team"
}
meaning: "A financial ledger entry subject to SOX retention policy."
fields {
recordId: Identifier required
amount: Money required
effectiveAt: Instant required
}
}
Governance-driven annotation via annotation aspect
annotation aspect RequireAuditForClaims on entity where fields contains Claim<*> {
annotations {
requiresEvidenceAudit: true
auditGranularity: "per-field"
}
}
All entities with any Claim<T> field automatically receive these annotation values without author intervention.
Resolving a conflict
// ERROR: both @SensitiveData and @DomainOwnership define the "owner" key
// Fix: override with inline annotations {} block
@[DomainOwnership, SensitiveData]
entity Patient {
annotations {
owner: "clinical-eng" // explicit resolution wins
}
meaning: "A person receiving clinical care."
}
Facet constraints in action
// M08779 — targets constraint violated: SensitiveData only targets [entity, relation]
@SensitiveData
action sendWelcomeEmail { ... }
// M11801 — requires constraint violated: SensitiveData requires [DomainOwnership]
@SensitiveData
entity BillingRecord {
annotations { domain: "finance" }
meaning: "A billing record."
}
// Valid: all constraints satisfied (DomainOwnership co-applied, targets entity)
@[DomainOwnership, SensitiveData]
entity BillingRecord {
annotations { domain: "finance", owner: "billing-eng" }
meaning: "A billing record."
}
// M11800 (warning) — conflicts-with: SensitiveData conflicts-with [PublicData]
// Merge proceeds; inline block provides explicit resolution
@[PublicData, SensitiveData]
entity ExchangeRate {
annotations {
classification: "internal" // explicit inline resolution — wins over PublicData default
}
meaning: "A currency exchange rate observable externally but classified internally."
}
Diagnostics
The diagnostic catalog for this RFC is authored in the structured Lean module and
rendered in reference catalog § Diagnostics. Inline mentions in
the prose above (e.g., “rejected with MNNxxx”) cross-link to the catalog
at render time.
9. Security and Authorization
- Annotation values MUST NOT be used in authorization decisions at runtime. They are metadata, not policy. Policy logic belongs in
policydeclarations (RFC-0008 §6.6). annotation aspectdeclarations in governance modules MUST be subject to the same install-plan review and approval process as policy declarations (RFC-0005 §8).- Annotation facet schemas in
annotation schemadeclarations are not access control mechanisms; they are governance documentation aids.
10. Compatibility and Migration
- Adding a new field with a default value to an existing
annotation facetis a non-breaking change. - Adding a new required field (no default) to an existing
annotation facetis a breaking change; all use sites must be updated. - Adding a new
annotation aspectis a non-breaking change for declarations that do not conflict with existing annotations. - Removing an
annotation facetis a breaking change if any declaration uses it. - The annotation system is an additive extension to RFC-0008. A parser that does not implement RFC-0011 MUST reject
annotation-facet-decl,annotation-aspect-decl,decorated-decl, andannotation-blocksyntax with error M11803 before compilation or install. The diagnostic MUST identify the unsupported annotation feature and the minimum required compiler version or feature. It MUST NOT silently discard annotation syntax or its target declaration.