RFC-0004 · 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-0004: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in
RFC-0004.This page is generated from the
lean/Gnomon/Spec/module for RFC-0004. Edit that source and regenerate this catalog.
Title: Aspects and Facets
Status: draft
Owners: Module Architecture, UI Composition
Proof citations in source: 25 / 25. Standalone proof verification is pending.
Definitions
| Term | Meaning |
|---|---|
| Aspect | Pushes structure or behavior into target kinds via declared selectors and merge modes; cross-cutting — one aspect can affect many kinds. |
| Presentation facet | A UI grouping declaration that groups fields from an already-composed entity into named sections for rendering; does not add structure, only organizes existing fields. |
| Semantic facet | A reusable meaning module declared in an .gnm file with a top-level facet declaration; composed additively into entity types via includes; carries domain rules and AI permission constraints. |
Diagnostics
| Code | Severity | Description |
|---|---|---|
M04301 | Error | Merge mode omitted or invalid |
M04302 | Error | Aspect target kind unresolved |
M04303 | Error | Aspect references non-existent field |
M04310 | Error | Facet kind not found |
M04311 | Warning | Facet section references missing field |
M04312 | Error | Facet inheritance cycle detected |
M04313 | Info | Additive contribution silently discarded due to field overlap |
M04314 | Error | Override conflict — two override aspects at equal specificity target the same field; halts compilation |
M04315 | Error | Guard condition references runtime state; must be compile-time evaluable |
M04316 | Info | Guarded aspect skipped (condition false) — emitted only with —verbose-aspects |
M04800 | Error | Circular extend chain detected |
M04801 | Error | extend statement references an entity not imported in the current file |
M04802 | Error | Two extend facets targeting the same entity declare conflicting field names |
M04803 | Error | extend facet redeclares a field already present on the base entity |
M04810 | Warning | extend targets an entity without a declared extension-points list |
M04811 | Error | Cross-module aspect precedence conflict — two modules declare conflicting priorities for the same aspect |
Invariants
- A facet contributed via extend must not redeclare fields already present on the base entity. (enforced by: compile-time)
- An extending module must be declared as a dependency, or the base entity must declare a matching extension-points slot, otherwise warning M04810. (enforced by: compile-time)
- Aspect merge order must be deterministic and explainable across runs. (enforced by: compile-time)
- Aspects and facets must not be used to circumvent policy checks; policy-relevant changes must be auditable.
- Aspects and presentation facets must be orthogonal: aspects add structure, presentation facets only group it.
- Aspects may add structure on top of semantic-facet-composed entities but must not circumvent the semantic facet’s declared rules.
- Aspects must target entity types or semantic-facet inclusions, never presentation facets. (enforced by: compile-time)
- Compilers MUST apply the deterministic aspect/facet merge algorithm (selector specificity, lexicographic identity, declared mode semantics, lexicographic key canonicalization) before serialization. (enforced by: compile-time)
- Conflicts must produce diagnostics with a clear precedence outcome. (enforced by: compile-time)
- Extend chains must not be circular; circular extend chains produce error M04800. (enforced by: compile-time)
- Extend declarations must appear only in Schema-class files; otherwise error M08704 fires. (enforced by: compile-time)
- Extend is valid only in a file that imports the entity being extended. (enforced by: compile-time)
- Presentation facets must not declare AI permissions, domain rules, or policy constraints. (enforced by: compile-time)
- Presentation facets must not mutate source structure. (enforced by: compile-time)
- Two facets extending the same entity must not declare duplicate field names. (enforced by: compile-time)
Normative Statements
Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.
Authoring Shape
- MUST — Aspects and facets MUST be authored using the specified YAML structure. (proof citation:
rfc0004_yaml_structure_at_boundary; verification pending) - MUST — Each target MUST specify exactly one selector type (kind, path, or trait). (proof citation:
rfc0004_one_selector_per_target; verification pending) - MUST — Facet
appliesToKindMUST reference a declared object kind (else M04310). (proof citation:rfc0004_applies_to_kind_resolves; verification pending) - MUST —
mergeModeMUST be one of additive, override, or guarded; omission is M04301. (proof citation:rfc0004_merge_mode_at_boundary; verification pending)
Compatibility and Migration
- MUST — Cross-module aspect precedence MUST remain deterministic.
- SHOULD — Legacy projection/facet schemas SHOULD map to a single normalized contract. (proof citation:
rfc0004_legacy_normalizes_to_one_contract; verification pending) - MUST — Transitional compatibility MUST include sunset criteria.
Conflict Rules
- MUST — Aspect conflicts MUST declare winning source and loser source in diagnostics. (proof citation:
rfc0004_aspect_conflict_at_boundary; verification pending) - MUST — Facet conflicts MUST produce warning M04311; first declaration in source order wins. (proof citation:
rfc0004_facet_conflict_diagnostic; verification pending) - MUST — Unresolvable override conflicts MUST produce error M04314 and halt compilation. (proof citation:
rfc0004_unresolvable_override_diagnostic; verification pending)
Cross-Module Facet Contribution
- MUST_NOT — A facet contributed via
extendMUST NOT redeclare fields already present on the base entity. (proof citation:rfc0004_extend_no_redeclare; verification pending) - MUST — An
extendstatement MUST appear in a file that imports the entity being extended. (proof citation:rfc0004_extend_requires_import; verification pending) - MUST — Authors MUST use cross-module facet contribution instead of redeclaring a shared entity in another module. (proof citation:
rfc0004_cross_module_via_extend; verification pending) - MUST — Circular
extendchains MUST produce error M04800. (proof citation:rfc0004_circular_extend_diagnostic; verification pending) - MUST — Cross-module field name collisions between two extending facets MUST produce error M04802. (proof citation:
rfc0004_cross_module_collision_diagnostic; verification pending) - MUST — The contributing module MUST be declared as a dependency or satisfy a declared extension-point.
- MUST —
extendMUST appear in a Schema-class file; otherwise error M08704. (proof citation:rfc0004_extend_in_schema_file; verification pending)
Definitions
- MAY — An aspect MAY target an entity type that includes a given semantic facet.
- MUST_NOT — An aspect MUST NOT target a presentation facet directly. (proof citation:
rfc0004_aspect_no_direct_presentation_target; verification pending)
Invariants
- MUST — Aspect merge order MUST be deterministic and explainable.
- MUST_NOT — Aspects MUST NOT circumvent a semantic facet’s declared rules. (proof citation:
rfc0004_aspect_no_semantic_circumvention; verification pending) - MUST — Aspects MUST target entity types or semantic facet inclusions, not presentation facets.
- MUST — Aspects and presentation facets MUST be orthogonal: aspects add structure, presentation facets only group it.
- MUST — Conflicts MUST produce diagnostics with clear precedence outcome. (proof citation:
rfc0004_b32_grounded; verification pending) - MUST_NOT — Presentation facets MUST NOT mutate source structure. (proof citation:
rfc0004_presentation_no_source_mutation; verification pending)
Phase Boundary
- MUST_NOT — Additive aspects MUST NOT produce errors when their contribution overlaps an existing field.
- MUST — Guard conditions MUST be evaluable at compile time using the target’s declared property values. (proof citation:
rfc0004_guards_evaluable_at_compile; verification pending) - MUST — On override conflict at equal specificity, the compiler MUST halt rather than arbitrarily pick one.
Presentation Facet Semantics
- MAY — A presentation facet MAY reference fields contributed by semantic facets.
- SHOULD — Missing referenced fields SHOULD be diagnosable (M04311). (proof citation:
rfc0004_b53_grounded; verification pending) - MUST_NOT — Presentation facets MUST NOT declare AI permissions, domain rules, or policy constraints. (proof citation:
rfc0004_presentation_no_other_classes; verification pending) - MUST — Presentation facets MUST remain view-specific and not authoritative for schema or domain rules. (proof citation:
rfc0004_presentation_view_specific_only; verification pending)
Scope
- MUST_NOT — Aspects MUST NOT operate over presentation facets. (proof citation:
rfc0004_aspect_not_over_presentation; verification pending)
Security and Authorization
- MUST_NOT — Aspects/facets MUST NOT be used to circumvent policy checks. (proof citation:
rfc0004_no_policy_circumvention_via_facets; verification pending) - MUST — Policy-relevant structure changes introduced by aspects MUST be auditable. (proof citation:
rfc0004_policy_structure_change_auditable; verification pending)
Linked References
(no cross-RFC dependencies)