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
.gnmfiles with top-levelfacetdeclarations (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
- Keep cross-cutting structure and presentation concerns separate
- Ensure deterministic merge and precedence behavior
- 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
.gnmfile with a top-levelfacetdeclaration. Composed additively into entity types viaincludes. 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
- Aspects and presentation facets MUST be orthogonal in intent: aspects add structure, presentation facets only group it.
- Aspect merge order MUST be deterministic and explainable.
- Presentation facets MUST NOT mutate source structure.
- Conflicts MUST produce diagnostics with clear precedence outcome.
- Aspects MUST target entity types (via
applies toselector) or semantic facet inclusions (viawhere includesselector), not presentation facets. - 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.
| Phase | What happens |
|---|---|
| Parse | aspect and facet declarations are parsed into the AST |
| Resolve | Target selectors are matched against the symbol table; unresolved targets produce error M04302 |
| Merge | Structural contributions are merged into target declarations using the merge mode algorithm (§5.1) |
| Validate | Post-merge declarations are validated as if the merged structure were authored directly |
| Emit | The 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-aspectsis 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:
- Collect all aspects whose target selectors match the declaration. Selector specificity determines collection order: explicit path > trait > kind-prefix.
- Evaluate guards: guarded aspects whose condition is false are removed from the working set.
- Apply additive aspects in selector-specificity order (most specific first). Discard overlapping fields silently (M04313).
- 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.
- 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
- Target selection MAY be by trait, kind prefix, or explicit path.
- Merge mode MUST be explicit (override, additive, or guarded).
- Precedence MUST be deterministic and stable across runs; the algorithm in §5.2 is normative.
Selector guidance (normative ordering for correctness and determinism):
- Prefer explicit path selectors for narrow, high-confidence targeting.
- Use trait selectors for cross-cutting domain semantics.
- Use kind-prefix selectors for broad policy-aligned defaults.
- 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.
- Presentation facets group fields and composition elements for rendering into named sections.
- Presentation facets MUST remain view-specific and MUST NOT be authoritative for underlying schema or domain rules.
- Missing referenced fields SHOULD be diagnosable (M04311).
- A presentation facet MAY reference fields contributed by semantic facets — the two layers are complementary.
- Presentation facets MUST NOT declare AI permissions, domain rules, or policy constraints. Such declarations belong in semantic facets (RFC-0006 §4.2) or
.gnmfiles with top-levelpolicydeclarations (RFC-0008 §6.6).
7. Conflict Rules
- 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.
- An unresolvable conflict (two override aspects at the same specificity targeting the same field) MUST produce error M04314 and MUST halt compilation.
- 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.
- 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
- Aspects/facets MUST NOT be used to circumvent policy checks.
- Policy-relevant structure changes introduced by aspects MUST be auditable.
9. Compatibility and Migration
- Legacy projection/facet schemas SHOULD map to a single normalized contract.
- 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
- Declare a
facetin the contributing module containing the additional fields. - In a Schema-class file that imports the base entity, apply the facet to the entity using the
extendkeyword.
// 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)
-
Import requirement.
extendis only valid in a file that imports the entity being extended. Anextendstatement 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. -
Dependency declaration. The contributing module MUST be listed as a declared dependency in the base module’s
importsblock (module.gnm), OR the base entity MUST declare anextension-pointslist that includes a named slot the contributing facet satisfies. Anextendthat satisfies neither condition MUST produce warning M04810. -
No circular extend chains. An
extendchain is circular when extending entity A causes a dependency on a module that itself extends A. Circularextendchains MUST produce error M04800. -
No field redeclaration. A facet contributed via
extendMUST 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. -
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
extendchain detected - M04801 —
extendstatement references an entity not imported in the current file - M04802 — two
extendfacets targeting the same entity declare conflicting field names - M04803 —
extendfacet redeclares a field already present on the base entity (inline or from a prior facet) - M04810 —
extendtargets an entity without a declaredextension-pointslist (warning) - M08704 —
extenddeclaration 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)
targetsarray MUST be non-empty; each target MUST specify exactly one selector type (kind OR path OR trait)mergeModeMUST be one of the three allowed modes; omission is an error (M04301)- Facet names MUST be non-empty identifiers
- Facet
appliesToKindMUST 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
extendchain detected - M04801:
extendstatement references an entity not imported in the current file (error) - M04802: Two
extendfacets targeting the same entity declare conflicting field names - M04803:
extendfacet redeclares a field already present on the base entity (error) - M04810:
extendtargets an entity without a declaredextension-pointslist (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
extenddeclarations are documented in §10, but RFC-0004 does not own the M087xx code range. See RFC-0008 §12 for the authoritative definition.
- M08704:
extenddeclaration appears in a non-Schema file (error;extendmust be in a Schema class file) — defined in RFC-0008; cross-referenced here