gnomonlearn
Docs/Composition/RFC-0004

RFC-0004 · Aspects and Facets

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: Module Architecture, UI Composition

1. Scope

Defines the formal semantics of aspects and facets as orthogonal composition mechanisms.

This RFC covers two related but distinct uses of the term “facet,” which RFC-0000 §2 now distinguishes explicitly:

  • Semantic facets (RFC-0006 §4.2): reusable meaning modules composed additively into entity types, carrying domain rules and AI permission constraints. These are authored in .gnm files with top-level facet declarations (RFC-0008 §6.2) and constitute the primary composition mechanism for the semantic type model.
  • Presentation facets (this RFC, §6): UI grouping mechanisms that organize already-composed fields into named sections for rendering. These are authored using the syntax defined in RFC-0004 §11 (Authoring Shape).

Aspects operate over semantic facets as their targets — they push structure and behavior into entity types that include those facets. Aspects do not operate over presentation facets.

When this RFC uses the term “facet” without qualification, it refers to presentation facets unless the context makes clear that semantic facets are intended.

2. Goals

  1. Keep cross-cutting structure and presentation concerns separate
  2. Ensure deterministic merge and precedence behavior
  3. Prevent semantic drift between declaration and runtime behavior

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

  • Aspect: pushes structure or behavior into target kinds via declared selectors and merge modes. Aspects are cross-cutting — one aspect can affect many kinds.
  • Semantic facet (RFC-0006 §4.2): 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. This is the primary composition primitive for the semantic model.
  • Presentation facet (this RFC): a UI grouping declaration authored using the syntax defined in RFC-0004 §11 (Authoring Shape). Groups fields from an already-composed entity into named sections for rendering. Does not add structure; only organizes what already exists.

Relationship between them: semantic facets add fields and rules to entity types via includes. Presentation facets then group those fields for display. An aspect MAY target an entity type that includes a given semantic facet. An aspect MUST NOT target a presentation facet directly.

When “facet” appears in this RFC without qualification, it means presentation facet. When “semantic facet” is intended, it is spelled out or references RFC-0006.

4. Invariants

  1. Aspects and presentation facets MUST be orthogonal in intent: aspects add structure, presentation facets only group it.
  2. Aspect merge order MUST be deterministic and explainable.
  3. Presentation facets MUST NOT mutate source structure.
  4. Conflicts MUST produce diagnostics with clear precedence outcome.
  5. Aspects MUST target entity types (via applies to selector) or semantic facet inclusions (via where includes selector), not presentation facets.
  6. Semantic facet composition (includes) is additive and governed by RFC-0006 §6. Aspects MAY add further structure on top of semantic-facet-composed entities but MUST NOT circumvent the semantic facet’s declared rules.

5. Phase Boundary

All aspect and facet resolution is a compile-time operation. No aspect application, merge, or conflict resolution occurs at runtime.

PhaseWhat happens
Parseaspect and facet declarations are parsed into the AST
ResolveTarget selectors are matched against the symbol table; unresolved targets produce error M04302
MergeStructural contributions are merged into target declarations using the merge mode algorithm (§5.1)
ValidatePost-merge declarations are validated as if the merged structure were authored directly
EmitThe compiled bundle (RFC-0002) reflects the fully merged structure; no aspect/facet metadata survives into the bundle unless explicitly preserved for tooling

The runtime receives only the fully merged, compiled declarations. It has no knowledge of which fields or rules were contributed by aspects versus authored inline.

5.1 Merge Mode Semantics

Each aspect declares one of three merge modes that governs how its contribution is applied to each matched target.

Additive

The aspect contribution is unioned with the existing target structure. Fields in the contribution that do not exist in the target are added. Fields that already exist in the target are not modified — the existing value is preserved and the aspect contribution for that field is silently discarded.

  • A target field is “existing” if it is present in the target’s own declaration or was contributed by a previously applied aspect.
  • Additive aspects MUST NOT produce errors when their contribution overlaps an existing field.
  • M04313 is emitted as an informational diagnostic when an additive contribution is silently discarded due to overlap.

Override

The aspect contribution is applied with priority. Fields in the contribution that already exist in the target are replaced with the aspect’s value. Fields that do not exist are added.

  • Override aspects produce error M04314 when two or more override aspects targeting the same declaration both provide a value for the same field. This is an unresolvable conflict; the compiler MUST halt rather than arbitrarily pick one.
  • Override takes precedence over additive: if an override aspect and an additive aspect both contribute a value for the same field, the override value wins and no M04313 is emitted.

Guarded

The aspect contribution is applied only when the guard.condition evaluates to true at compile time against the target’s existing properties. Guard conditions are evaluated over the target’s declared property values (not runtime state). If the condition is false, the aspect contribution is entirely skipped for that target.

  • Guard conditions MUST be evaluable at compile time using the target’s declared property values. Conditions that reference runtime state are an error (M04315).
  • A guarded aspect that evaluates to false produces no diagnostic unless --verbose-aspects is set (informational M04316).
  • If two guarded aspects target the same field and both guards evaluate to true, this is treated as an override conflict and produces error M04314.

5.2 Conflict Resolution Algorithm

When multiple aspects target the same declaration, the merge is applied in the following deterministic order:

  1. Collect all aspects whose target selectors match the declaration. Selector specificity determines collection order: explicit path > trait > kind-prefix.
  2. Evaluate guards: guarded aspects whose condition is false are removed from the working set.
  3. Apply additive aspects in selector-specificity order (most specific first). Discard overlapping fields silently (M04313).
  4. Apply override aspects in selector-specificity order (most specific first). If two override aspects at the same specificity level conflict on the same field, halt with M04314.
  5. Apply guarded aspects whose guard evaluated to true, in selector-specificity order, following override semantics for conflicts.

Within a single specificity tier, aspects from the same module are ordered alphabetically by aspect name. Aspects from different modules are ordered by module canonical name (RFC-0000 §2 naming, lexicographic). This ordering is stable and reproducible across compiler runs.

If the algorithm produces a conflict (M04314), the build MUST fail. There is no silent winner-picking.

5.3 Aspect Semantics

  1. Target selection MAY be by trait, kind prefix, or explicit path.
  2. Merge mode MUST be explicit (override, additive, or guarded).
  3. Precedence MUST be deterministic and stable across runs; the algorithm in §5.2 is normative.

Selector guidance (normative ordering for correctness and determinism):

  1. Prefer explicit path selectors for narrow, high-confidence targeting.
  2. Use trait selectors for cross-cutting domain semantics.
  3. Use kind-prefix selectors for broad policy-aligned defaults.
  4. Mixed selector usage SHOULD be accompanied by clear precedence expectations.

6. Presentation Facet Semantics

Presentation facets group fields and composition elements for rendering. They do not add, remove, or modify fields.

  1. Presentation facets group fields and composition elements for rendering into named sections.
  2. Presentation facets MUST remain view-specific and MUST NOT be authoritative for underlying schema or domain rules.
  3. Missing referenced fields SHOULD be diagnosable (M04311).
  4. A presentation facet MAY reference fields contributed by semantic facets — the two layers are complementary.
  5. Presentation facets MUST NOT declare AI permissions, domain rules, or policy constraints. Such declarations belong in semantic facets (RFC-0006 §4.2) or .gnm files with top-level policy declarations (RFC-0008 §6.6).

7. Conflict Rules

  1. Aspect conflicts MUST declare winning source and loser source in diagnostics. The conflict resolution algorithm (§5.2) is normative; there is no implementation-defined behavior.
  2. An unresolvable conflict (two override aspects at the same specificity targeting the same field) MUST produce error M04314 and MUST halt compilation.
  3. Facet conflicts (two presentation facets grouping the same field into different sections of the same view) MUST produce warning M04311 and the first declaration in source order wins.
  4. Cross-module conflicts follow the same algorithm as same-module conflicts; module canonical name provides the tiebreaker within a specificity tier.

8. Security and Authorization

  1. Aspects/facets MUST NOT be used to circumvent policy checks.
  2. Policy-relevant structure changes introduced by aspects MUST be auditable.

9. Compatibility and Migration

  1. Legacy projection/facet schemas SHOULD map to a single normalized contract.
  2. Transitional compatibility MUST include sunset criteria.

Cross-module precedence expectation:

When aspects from multiple modules target the same node, precedence MUST remain deterministic and SHOULD be resolved using a stable ordering strategy that can be aligned with RFC-0002 canonical serialization rules.

10. Cross-Module Facet Contribution (Normative)

Cross-module facet contribution is the normative pattern for adding product-context fields to a shared entity declared in another module. Authors MUST use this pattern instead of redeclaring the entity in the contributing module.

Pattern

  1. Declare a facet in the contributing module containing the additional fields.
  2. In a Schema-class file that imports the base entity, apply the facet to the entity using the extend keyword.
// modules/selectsmart/household/schema.gnm

import "household.Household"

facet SelectSmartContext {
  meaning: "Employer-sponsored benefits guidance context for a household enrolled in SelectSmart."

  fields {
    employerId: Identifier
    hireDate: Date
    terminationDate: Date
    eligibilityClass: Text
    guidanceMode: GuidanceMode
    planYear: Integer
  }
}

extend Household includes [SelectSmartContext]

The extend statement instructs the compiler to add the named facets to the target entity’s includes list at the module boundary. The extended entity remains a single entity in the graph; only its declared field set grows.

extend Syntax

extend <EntityName> includes [<FacetName>, ...]

extend is a top-level statement. It is only valid in Schema-class files (RFC-0001 §4.1). Placing an extend statement in an Operations, Relations, Governance, Surface, or Tests file is error M08704.

extend Rules (Normative)

  1. Import requirement. extend is only valid in a file that imports the entity being extended. An extend statement that references an entity not imported in the same file MUST produce error M04801 (if the entity is entirely unresolved) or be rejected as an invalid extension context.

  2. Dependency declaration. The contributing module MUST be listed as a declared dependency in the base module’s imports block (module.gnm), OR the base entity MUST declare an extension-points list that includes a named slot the contributing facet satisfies. An extend that satisfies neither condition MUST produce warning M04810.

  3. No circular extend chains. An extend chain is circular when extending entity A causes a dependency on a module that itself extends A. Circular extend chains MUST produce error M04800.

  4. No field redeclaration. A facet contributed via extend MUST NOT redeclare fields already present on the base entity (whether declared inline or contributed by a previously applied facet). Redeclaring an existing field MUST produce error M04803.

  5. No cross-module field conflicts. Two modules MAY both extend the same entity with different facets. However, if any field name declared by one contributing facet duplicates a field name declared by another contributing facet targeting the same entity, this MUST produce error M04802.

extension-points on Entity Declarations

A base entity MAY declare a list of named extension slots to signal that cross-module contribution is expected and sanctioned:

entity Household {
  meaning: "Core household entity shared across all products."

  extension-points [
    ProductContext,
    ComplianceContext,
  ]

  fields {
    id: Identifier required
    ...
  }
}

extension-points is an advisory declaration: it documents that the entity is designed to be extended and names the logical slots available for contribution. It does not restrict which modules may extend the entity, but the compiler uses it as a lint signal: a module that extends an entity without a matching extension point MUST receive warning M04810.

Schema-Class Requirement for extend

extend MUST appear in a Schema-class file (RFC-0001 §4.1). Placing extend in a file that belongs to any other declaration class (Operations, Relations, Governance, Surface, Tests) is error M08704.

Cross-Module Facet Contribution Diagnostic Codes

  • M04800 — circular extend chain detected
  • M04801 — extend statement references an entity not imported in the current file
  • M04802 — two extend facets targeting the same entity declare conflicting field names
  • M04803 — extend facet redeclares a field already present on the base entity (inline or from a prior facet)
  • M04810 — extend targets an entity without a declared extension-points list (warning)
  • M08704 — extend declaration appears in a non-Schema file (defined in RFC-0008; cross-referenced here — see RFC-0001 §4.1 for file class definitions)

11. Authoring Shape (Normative)

Aspects and facets MUST be authored using the following YAML structure:

aspects:
  - name: aspectName                  # required, must be unique within module
    targets:
      - kind: "objectType.*"         # kind-prefix selector (example)
      - path: "core.object.field"    # explicit path selector (example)
      trait: some_trait              # trait selector (example)
    mergeMode: "additive"            # "additive" | "override" | "guarded"
    guard:                           # only valid if mergeMode is "guarded"
      condition: "field == value"
    contribution:                    # structural delta to apply
      properties:
        newField: { type: "string" }
      mutations:
        targetField: { newValue }

facets:
  - name: facetName                  # required, must be unique within module
    appliesToKind: "objectType"     # object kind this facet applies to
    sections:
      - name: sectionName
        fields: [field1, field2, field3]

Validation Rules:

  • Aspect names MUST be non-empty identifiers (RFC-0000 §2 canonical naming)
  • targets array MUST be non-empty; each target MUST specify exactly one selector type (kind OR path OR trait)
  • mergeMode MUST be one of the three allowed modes; omission is an error (M04301)
  • Facet names MUST be non-empty identifiers
  • Facet appliesToKind MUST reference a declared object kind; unresolved kinds MUST produce error M04310
  • Facet sections MUST reference fields that exist in the target object; missing fields produce warning M04311

12. Diagnostic Codes (RFC-0004 Allocation)

M040x: Aspects structure

  • M04301: Merge mode omitted or invalid
  • M04302: Aspect target kind unresolved
  • M04303: Aspect references non-existent field

M041x: Facets structure and merge/conflict

  • M04310: Facet kind not found
  • M04311: Facet section references missing field (warning)
  • M04312: Facet inheritance cycle detected
  • M04313: Additive contribution silently discarded due to field overlap (informational)
  • M04314: Override conflict — two override aspects at equal specificity target the same field (error, halts compilation)
  • M04315: Guard condition references runtime state; must be compile-time evaluable (error)
  • M04316: Guarded aspect skipped (condition false) — emitted only with --verbose-aspects (informational)

M048x: Cross-module facet contribution and precedence

  • M04800: Circular extend chain detected
  • M04801: extend statement references an entity not imported in the current file (error)
  • M04802: Two extend facets targeting the same entity declare conflicting field names
  • M04803: extend facet redeclares a field already present on the base entity (error)
  • M04810: extend targets an entity without a declared extension-points list (warning)
  • M04811: Cross-module aspect precedence conflict — two modules declare conflicting priorities for the same aspect (error; author must resolve explicitly)

M087x: File class enforcement — cross-reference only (owned by RFC-0008)

M08704 is defined and owned by RFC-0008 (Language Authoring Surface), which governs file class enforcement. It is cross-referenced here because extend declarations are documented in §10, but RFC-0004 does not own the M087xx code range. See RFC-0008 §12 for the authoritative definition.

  • M08704: extend declaration appears in a non-Schema file (error; extend must be in a Schema class file) — defined in RFC-0008; cross-referenced here