gnomonlearn
Docs/RFC-0004/Reference catalog

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.

← Read the authored RFC

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

TermMeaning
AspectPushes structure or behavior into target kinds via declared selectors and merge modes; cross-cutting — one aspect can affect many kinds.
Presentation facetA 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 facetA 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

CodeSeverityDescription
M04301ErrorMerge mode omitted or invalid
M04302ErrorAspect target kind unresolved
M04303ErrorAspect references non-existent field
M04310ErrorFacet kind not found
M04311WarningFacet section references missing field
M04312ErrorFacet inheritance cycle detected
M04313InfoAdditive contribution silently discarded due to field overlap
M04314ErrorOverride conflict — two override aspects at equal specificity target the same field; halts compilation
M04315ErrorGuard condition references runtime state; must be compile-time evaluable
M04316InfoGuarded aspect skipped (condition false) — emitted only with —verbose-aspects
M04800ErrorCircular extend chain detected
M04801Errorextend statement references an entity not imported in the current file
M04802ErrorTwo extend facets targeting the same entity declare conflicting field names
M04803Errorextend facet redeclares a field already present on the base entity
M04810Warningextend targets an entity without a declared extension-points list
M04811ErrorCross-module aspect precedence conflict — two modules declare conflicting priorities for the same aspect

Invariants

  1. A facet contributed via extend must not redeclare fields already present on the base entity. (enforced by: compile-time)
  2. 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)
  3. Aspect merge order must be deterministic and explainable across runs. (enforced by: compile-time)
  4. Aspects and facets must not be used to circumvent policy checks; policy-relevant changes must be auditable.
  5. Aspects and presentation facets must be orthogonal: aspects add structure, presentation facets only group it.
  6. Aspects may add structure on top of semantic-facet-composed entities but must not circumvent the semantic facet’s declared rules.
  7. Aspects must target entity types or semantic-facet inclusions, never presentation facets. (enforced by: compile-time)
  8. 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)
  9. Conflicts must produce diagnostics with a clear precedence outcome. (enforced by: compile-time)
  10. Extend chains must not be circular; circular extend chains produce error M04800. (enforced by: compile-time)
  11. Extend declarations must appear only in Schema-class files; otherwise error M08704 fires. (enforced by: compile-time)
  12. Extend is valid only in a file that imports the entity being extended. (enforced by: compile-time)
  13. Presentation facets must not declare AI permissions, domain rules, or policy constraints. (enforced by: compile-time)
  14. Presentation facets must not mutate source structure. (enforced by: compile-time)
  15. 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

  1. MUST — Aspects and facets MUST be authored using the specified YAML structure. (proof citation: rfc0004_yaml_structure_at_boundary; verification pending)
  2. MUST — Each target MUST specify exactly one selector type (kind, path, or trait). (proof citation: rfc0004_one_selector_per_target; verification pending)
  3. MUST — Facet appliesToKind MUST reference a declared object kind (else M04310). (proof citation: rfc0004_applies_to_kind_resolves; verification pending)
  4. MUST — mergeMode MUST be one of additive, override, or guarded; omission is M04301. (proof citation: rfc0004_merge_mode_at_boundary; verification pending)

Compatibility and Migration

  1. MUST — Cross-module aspect precedence MUST remain deterministic.
  2. SHOULD — Legacy projection/facet schemas SHOULD map to a single normalized contract. (proof citation: rfc0004_legacy_normalizes_to_one_contract; verification pending)
  3. MUST — Transitional compatibility MUST include sunset criteria.

Conflict Rules

  1. MUST — Aspect conflicts MUST declare winning source and loser source in diagnostics. (proof citation: rfc0004_aspect_conflict_at_boundary; verification pending)
  2. MUST — Facet conflicts MUST produce warning M04311; first declaration in source order wins. (proof citation: rfc0004_facet_conflict_diagnostic; verification pending)
  3. MUST — Unresolvable override conflicts MUST produce error M04314 and halt compilation. (proof citation: rfc0004_unresolvable_override_diagnostic; verification pending)

Cross-Module Facet Contribution

  1. MUST_NOT — A facet contributed via extend MUST NOT redeclare fields already present on the base entity. (proof citation: rfc0004_extend_no_redeclare; verification pending)
  2. MUST — An extend statement MUST appear in a file that imports the entity being extended. (proof citation: rfc0004_extend_requires_import; verification pending)
  3. 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)
  4. MUST — Circular extend chains MUST produce error M04800. (proof citation: rfc0004_circular_extend_diagnostic; verification pending)
  5. MUST — Cross-module field name collisions between two extending facets MUST produce error M04802. (proof citation: rfc0004_cross_module_collision_diagnostic; verification pending)
  6. MUST — The contributing module MUST be declared as a dependency or satisfy a declared extension-point.
  7. MUST — extend MUST appear in a Schema-class file; otherwise error M08704. (proof citation: rfc0004_extend_in_schema_file; verification pending)

Definitions

  1. MAY — An aspect MAY target an entity type that includes a given semantic facet.
  2. MUST_NOT — An aspect MUST NOT target a presentation facet directly. (proof citation: rfc0004_aspect_no_direct_presentation_target; verification pending)

Invariants

  1. MUST — Aspect merge order MUST be deterministic and explainable.
  2. MUST_NOT — Aspects MUST NOT circumvent a semantic facet’s declared rules. (proof citation: rfc0004_aspect_no_semantic_circumvention; verification pending)
  3. MUST — Aspects MUST target entity types or semantic facet inclusions, not presentation facets.
  4. MUST — Aspects and presentation facets MUST be orthogonal: aspects add structure, presentation facets only group it.
  5. MUST — Conflicts MUST produce diagnostics with clear precedence outcome. (proof citation: rfc0004_b32_grounded; verification pending)
  6. MUST_NOT — Presentation facets MUST NOT mutate source structure. (proof citation: rfc0004_presentation_no_source_mutation; verification pending)

Phase Boundary

  1. MUST_NOT — Additive aspects MUST NOT produce errors when their contribution overlaps an existing field.
  2. 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)
  3. MUST — On override conflict at equal specificity, the compiler MUST halt rather than arbitrarily pick one.

Presentation Facet Semantics

  1. MAY — A presentation facet MAY reference fields contributed by semantic facets.
  2. SHOULD — Missing referenced fields SHOULD be diagnosable (M04311). (proof citation: rfc0004_b53_grounded; verification pending)
  3. MUST_NOT — Presentation facets MUST NOT declare AI permissions, domain rules, or policy constraints. (proof citation: rfc0004_presentation_no_other_classes; verification pending)
  4. 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

  1. MUST_NOT — Aspects MUST NOT operate over presentation facets. (proof citation: rfc0004_aspect_not_over_presentation; verification pending)

Security and Authorization

  1. MUST_NOT — Aspects/facets MUST NOT be used to circumvent policy checks. (proof citation: rfc0004_no_policy_circumvention_via_facets; verification pending)
  2. 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)