gnomonlearn

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 facet declarations — named, reusable sets of metadata keys (pull model)
  • annotation aspect declarations — governance-driven metadata pushed onto matching declarations (push model)
  • The annotations { } inline block — declaration-local key-value overrides
  • The @FacetName decorator sugar — shorthand for attaching an annotation facet
  • The normative annotation resolution model — precedence, conflict rules, completeness checks

2. Goals

  1. Provide a typed, queryable metadata layer without polluting the semantic type model with non-runtime concerns
  2. Reuse the existing facet/aspect kernel; annotation facets and annotation aspects mirror the pull/push distinction of FacetType and aspect
  3. Keep annotation metadata strictly compile-time; the compiler enforces the boundary at schema emission
  4. Define a single, normative resolution order so annotation values are predictable regardless of how many sources contribute
  5. 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

  1. Annotation facet fields MUST NOT appear in runtime entity instance storage or field schemas. The compiler MUST enforce this at schema emission time.
  2. Annotation aspect fields MUST NOT contribute runtime structure. The compiler MUST enforce this.
  3. The @FacetName form MUST reference a declared annotation facet; it MUST NOT reference a semantic facet. Violations produce error M08770.
  4. Two @ decorators on the same declaration MUST NOT define overlapping annotation keys unless an inline annotations { } block provides an explicit resolution. Violations produce error M08773.
  5. The annotation resolution model in §5 is normative and MUST be implemented exactly as specified. Implementations MUST NOT define alternative resolution orders.
  6. Annotation values MUST NOT be passed to the runtime kernel (RFC-0010). Presence of annotation values in kernel input is a compiler violation (M08776).
  7. When an annotation facet declares a targets constraint, it MUST only be applied to declaration kinds listed in that constraint. Violations produce error M08779.
  8. When an annotation facet declares a requires constraint, 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.
  9. Circular requires chains among annotation facets MUST be detected and rejected at facet declaration time (M11802). They MUST NOT be detected only at use sites.
  10. conflicts-with constraints 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 @FacetName or annotations {}) to a declaration whose kind is not in the list MUST produce error M08779.
  • When targets is 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 or annotations {}), 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-with is symmetric by convention but is not automatically bidirectional. If A conflicts-with [B] but B does not list A, only A’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 aspect satisfies the requirement.
  • Circular requires chains (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):

  1. Inline annotations { } block — values defined directly in the declaration body
  2. @ decorators — values from named annotation facets, in alphabetical order by facet name (canonical order enforced by gnomon fmt)
  3. Annotation aspects — values pushed by matching annotation aspect declarations, in source definition order within the compiled bundle

5.1 Conflict Rules

SituationRuleDiagnostic
Two facets in the same @[...] group (or applied via multiple decorators) define the same keyError: must resolve with inline annotations { } overrideM08773
Decorator-applied facet and annotation aspect define the same keyDecorator wins silently; this is intentional overrideM08774 (informational)
Two annotation aspects push the same keyFirst-defined aspect wins; authors SHOULD resolve by adding an explicit inline annotations { } override on the declarationM08775 (warning)
Inline annotations { } overrides any sourceInline 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

  1. Annotation values MUST NOT be used in authorization decisions at runtime. They are metadata, not policy. Policy logic belongs in policy declarations (RFC-0008 §6.6).
  2. annotation aspect declarations in governance modules MUST be subject to the same install-plan review and approval process as policy declarations (RFC-0005 §8).
  3. Annotation facet schemas in annotation schema declarations are not access control mechanisms; they are governance documentation aids.

10. Compatibility and Migration

  1. Adding a new field with a default value to an existing annotation facet is a non-breaking change.
  2. Adding a new required field (no default) to an existing annotation facet is a breaking change; all use sites must be updated.
  3. Adding a new annotation aspect is a non-breaking change for declarations that do not conflict with existing annotations.
  4. Removing an annotation facet is a breaking change if any declaration uses it.
  5. 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, and annotation-block syntax 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.