gnomonlearn
Docs/Composition/RFC-0003

RFC-0003 · Composition Model

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

1. Scope

Defines composition boundaries and resolution semantics for route, page, layout, and widget surfaces. Also defines the compilation path from semantic view declarations (RFC-0008 entity-syntax view declarations and scope-syntax view blocks in .gnm files) into the route/page/layout/widget execution model.

The composition model has two layers:

  • Semantic authoring layer: view declarations authored in .gnm files using entity syntax or scope syntax (RFC-0008). This is what authors write.
  • Execution layer: route/page/layout/widget elements resolved at runtime. This is what the compiler produces from view declarations.

Authors MUST use the semantic authoring layer (view declarations in .gnm files per RFC-0008 §8.13) unless the module explicitly requires direct execution-layer control. The execution layer is the compiler’s output contract, consumed by the runtime and install pipeline. Fine-grained sub-block authoring within a view declaration is valid but considered the lower-level interface.

2. Goals

  1. Unambiguous composition boundaries
  2. Deterministic resolution order
  3. Explicit fallback and diagnostics 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. Invariants

  1. Route MUST resolve to exactly one page definition.
  2. Page MUST resolve to exactly one layout definition.
  3. Layout MUST resolve all extension point widget bindings deterministically. When multiple aspects contribute widgets to the same extension point, priority order MUST produce a unique total ordering (ties are a compile error).
  4. Widget resolution MUST use canonical identity lookups.

4. Composition Layers

The execution model has four layers. An additional semantic authoring layer (Layer 0) sits above them and compiles into Layers 1–4.

  • Layer 0 — View (semantic authoring, compiled): A view declaration authored in an .gnm file using entity syntax or scope syntax (RFC-0008). A view is the semantic specification of what an author wants to show. The compiler transforms it into one or more execution-layer elements (Layers 1–4). This is the preferred authoring surface.
  • Layer 1 — Route: navigation identity and policy envelope
  • Layer 2 — Page: data orchestration and binding specification
  • Layer 3 — Layout: structural region arrangement
  • Layer 4 — Widget: smallest renderable unit with typed props

Layers 1–4 MAY be authored directly via a view declaration’s layout, page, and route sub-blocks for modules that require fine-grained control over execution-layer structure. Both paths — high-level view declarations and granular sub-block authoring within a view — produce equivalent execution-layer artifacts; the runtime does not distinguish the origin.

4.1 Extension Points

Layouts declare extension points — named positions where aspects or other modules may contribute additional widgets. Extension points are the only mechanism by which cross-cutting UI structure may be injected; aspects MUST NOT contribute widgets to positions that are not declared extension points.

Authoring syntax (in a view’s layout section or a direct layout declaration):

view BundlesComparison for Bundles {
  layout {
    extensionPoints [headerActions, comparisonSidebar, footerBanner]

    show [name, monthlyPremium, deductible, outOfPocketMax]
    actions [selectBundle, comparePlans]
  }
}

Aspect contribution targeting a named extension point:

aspect RecommendationBadge on any write(Plan) {
  contribute to comparisonSidebar {
    widget RecommendationScoreBadge {
      priority: 10
      data:     context.recommendationScore
    }
  }
}

Conflict resolution rules:

  1. Each aspect contribution MUST have an effective priority: Int. The source priority field MAY be omitted. If supplied, its value MUST be an integer; if omitted, the compiler MUST assign 0 as the effective priority before ordering contributions or checking priority ties.
  2. When multiple contributions target the same extension point, they are rendered in descending effective priority order (highest first).
  3. Two contributions targeting the same extension point with the same effective priority value MUST produce compile error M03210 — tie-breaking is explicit, not implicit.
  4. An aspect contribution targeting an extension point not declared on the view/layout produces warning M03211. The contribution is silently discarded; it does not block compilation.

Extension point diagnostics:

  • M03210: Two aspect contributions have identical priority for the same extension point (error)
  • M03211: Aspect contribution targets extension point not declared on view/layout (warning; contribution discarded)
  • M03212: Extension point name conflicts with a reserved layout property name (error)

4.2 Nested Layouts

A layout region’s widget list MAY include a sublayout reference, allowing layout nesting. This enables complex structural arrangements (e.g., a master-detail layout within a sidebar region) without requiring a full page-level split.

Rules:

  1. A sublayout entry in a region’s widget list MUST reference a declared layout identifier in the same module or its imports.
  2. Maximum nesting depth is 3 levels (root layout → sublayout → sub-sublayout). Exceeding this MUST produce error M03213.
  3. Layout nesting cycles MUST be detected at compile time and MUST produce error M03214.
  4. A nested layout inherits the parent’s policy context. It MUST NOT declare a policy envelope that is less restrictive than the parent’s. Violations MUST produce error M03215.
  5. Each nested layout’s extension points are scoped to that layout and MUST NOT be addressable by aspects targeting the parent layout’s extension points.

Syntax (in a direct layout declaration or view layout block):

view EmployeeDetail for Employee {
  layout {
    extensionPoints [sidebarExtension]
    show [name, email, startDate]

    region sidebar {
      sublayout ActivityTimeline   // nested layout
      widget ContactCard
    }
  }
}

Diagnostics:

  • M03213: Layout nesting exceeds maximum depth of 3
  • M03214: Layout nesting cycle detected
  • M03215: Nested layout policy envelope is less restrictive than parent

4.3 Conditional Routing

A route MAY declare a when predicate that is evaluated against the current actor’s authorization context at navigation time. If the predicate evaluates false, the route is inaccessible to that actor and the runtime MUST redirect without exposing route content.

Syntax:

view EnrollmentAdminDashboard for Enrollment {
  route {
    path: "/admin/enrollment"
    when: actor.hasRole(BenefitsAdmin) && actor.org == context.org
    fallback: "/dashboard"   // redirect target when 'when' evaluates false
  }
}

Rules:

  1. The when predicate MUST use only the Gnomon constraint expression language (RFC-0008 §8.19). Arbitrary code is not permitted.
  2. The when predicate MAY reference: actor (the current principal), context (route context including org and session), and fields of the entity the view is for.
  3. fallback is OPTIONAL. When absent and when evaluates false, the runtime MUST redirect to the nearest ancestor accessible route. If no accessible ancestor exists, the runtime MUST redirect to the app’s declared root route.
  4. The when predicate is evaluated AFTER the route’s policy envelope authorization check. A route that fails authorization is NOT accessible regardless of when. when is an additional narrowing predicate, not an authorization bypass.
  5. The compiled route element MUST include the when predicate as a compiled authorization predicate in the route’s policy envelope (RFC-0010 §5.3).

Diagnostics:

  • M03216: Route when predicate references undeclared field or role
  • M03217: Route when predicate contains a non-deterministic expression (forbidden — routing must be reproducible)
  • M03218: Route fallback target does not resolve to a declared route

4.4 Claim Widget Mapping

When a view’s show block lists a field whose type is Claim<T>, the default compiled widget is the built-in claim-field composite widget. This widget renders:

  • The field value (typed as T)
  • A confidence indicator (visual representation of the confidence field)
  • A provenance link (source + asserted_by, expandable on interaction)
  • An epistemic status badge (derived from ClaimStatus flow state)

Default behavior: The claim-field composite widget is always read-only in display mode. Writes to Claim<T> fields are never done via direct field widget interaction; they require an explicit ActionType command with declared effects (per RFC-0006 §4.4). The runtime MUST reject any attempt to write a Claim<T> field through a widget interaction that is not backed by a declared action.

Override: Module authors MAY override the default composite widget by specifying claimWidget on the field entry in the view:

view PlanRecommendationCard for PlanRecommendation {
  layout {
    show [
      recommendedPlan { claimWidget: CompactClaimBadge }  // custom widget
      rationale                                            // default claim-field
    ]
  }
}

The override widget MUST declare claimProps: ClaimFieldProps in its props schema. ClaimFieldProps is a reserved built-in props type.

ClaimFieldProps — built-in composite widget prop type for Claim<T> fields:

  • value: T — the claim’s asserted value
  • confidence: Decimal — confidence score in [0,1]; may be null
  • status: Text — ClaimStatus flow state (pending/confirmed/disputed/superseded/retracted)
  • source: Text — provenance identifier; may be null
  • asserted_by: Principal — the principal that asserted the claim

These fields map directly to the ClaimStatus flow defined in RFC-0006 §4.5.

A widget that declares override for a Claim<T> field but does not accept ClaimFieldProps MUST produce compile error M03219.

Diagnostics:

  • M03219: Claim field widget override does not accept required ClaimFieldProps in its props schema

4.5 Layout Hints

A view declaration MAY include layout hints in its layout block. Hints are advisory: the runtime theme layer MAY use them to influence rendering but MUST NOT be required to honor them. The compiler MUST NOT reject a view for including hints that a given theme does not support.

view BenefitsSummary for Enrollment {
  layout {
    columns: 2                           // suggested column count
    sectionOrder: [coverage, costs, dates]  // suggested section display order
    show [planName, monthlyPremium, deductible]
  }
}

Hints that conflict with the runtime’s layout constraints (e.g., columns: 5 on a single-column mobile theme) are silently ignored; no diagnostic is emitted. Authors who require precise layout control MUST target a specific theme or use a custom widget.

5. Authoring Contract for Composition Layers

The composition contract MUST represent these layers explicitly. When authoring via view declarations, the compiler generates these elements. When authoring granular sub-blocks directly within a view, the author supplies them explicitly. Both paths MUST satisfy the same layer constraints.

Authoring references MUST satisfy:

  1. route.page resolves to a declared page identifier.
  2. page.layout resolves to a declared layout identifier.
  3. layout.regions[*] entries resolve to declared widget identifiers.
  4. Widgets carry stable identity ids and typed prop references.

Each declared composition layer element SHOULD export canonical identity metadata to the compiled bundle identity envelope.

5a. View-to-Composition Compilation Path

When a module includes view declarations in .gnm files (entity syntax or scope syntax per RFC-0008), the compiler MUST transform each view declaration into execution-layer composition elements as follows.

Compilation Rules

  1. Each view declaration MUST compile to exactly one page element.

  2. Each view declaration MUST compile to exactly one layout element that wraps the page.

  3. Each section block within a view’s layout or show declaration MUST compile to one or more widget elements.

  4. Each field listed in a show or section block MUST compile to a typed widget of the appropriate kind (text, date, reference selector, etc.) based on the field’s declared type in the semantic model.

    Note: Field type → widget kind mapping follows the default widget table in RFC-0008 §6.8 (the view declaration’s field default widget table). If no default applies, the compiler MUST emit M03225 (unknown widget kind) and use a generic text fallback.

  5. Each entry in the view’s actions block MUST compile to a button widget bound to the corresponding command.

  6. Each view that is reachable via a declared app bundle route (RFC-0008 §6.16) MUST produce a route element. Views not referenced by any app bundle MUST NOT produce route elements (warning M03220).

Identity Derivation

Compiled composition elements derived from a view declaration MUST use identity paths derived from the view’s canonical path:

  • Page: <module-namespace>.ui.page.<view_name>
  • Layout: <module-namespace>.ui.layout.<view_name>
  • Each section widget group: <module-namespace>.ui.widget.<view_name>.<section_name>
  • Route (if app-bound): <module-namespace>.ui.route.<view_name>

These derived identities MUST appear in the compiled bundle identity envelope (RFC-0002 §5) exactly as they would for directly authored composition elements.

Authorization Preservation

Policy envelopes declared in a view’s actions block (e.g., reviewer can mark Reviewed) MUST be compiled into the route/page policy envelope. The compiler MUST NOT silently drop action-level authorization from view declarations.

Constraints

  1. View declarations MUST NOT contain business logic, validation rules, or authorization predicates beyond actor-to-action bindings. Such content MUST be in .gnm files with top-level policy declarations or policy blocks in scope-syntax files. Violations produce warning M03221.
  2. A view MAY reference only commands and queries declared in the same module or its imports. References to undeclared commands produce error M03222.
  3. If a field listed in a view’s show block is marked Sensitive by an active policy, the compiler MUST emit a warning (M03223) and the runtime MUST enforce visibility based on the actor’s authorization.

6. Resolution Order

Canonical order:

  1. In-memory registry
  2. Trusted local compiled cache
  3. Explicit placeholder/failure surface with telemetry

No unrestricted network source is allowed in resolve-on-miss paths.

7. Fallback Semantics

  1. Missing composition targets MUST produce explicit non-silent diagnostics.
  2. Non-dev mode SHOULD render controlled warning placeholders, not hard crashes.
  3. Fallback usage MUST be telemetry-visible.

8. Security and Authorization

  1. Route and page policy envelopes MUST be preserved through resolution.
  2. Composition MUST NOT bypass operation/policy checks.
  3. Composition-level policy failures MUST be diagnosable.
  4. Authorization bindings compiled from view actions blocks MUST be treated with the same enforcement weight as directly authored policy envelopes (see §5a).

9. Compatibility and Migration

  1. Legacy mapping layers MAY exist only behind explicit compatibility adapters.
  2. Compatibility adapters MUST include deprecation and sunset criteria.
  3. Modules that migrate from direct composition: authoring to view declarations MUST produce functionally equivalent compiled bundles. The compiler SHOULD provide a diff tool to verify equivalence.

10. Diagnostic Codes (RFC-0003 Allocation)

M030x: Layer resolution and binding

  • M03200: Route failed to resolve to exactly one page
  • M03201: Page failed to resolve to exactly one layout
  • M03202: Layout region binding unresolved widget reference
  • M03203: Composition fallback invoked

M031x: Composition structure

  • M03210: Two aspect contributions have identical priority for the same extension point (error)
  • M03211: Aspect contribution targets extension point not declared on view/layout (warning; discarded)
  • M03212: Extension point name conflicts with reserved layout property name (error)
  • M03213: Layout nesting exceeds maximum depth of 3 (§4.2)
  • M03214: Layout nesting cycle detected (§4.2)
  • M03215: Nested layout policy envelope less restrictive than parent (§4.2)
  • M03216: Route when predicate references undeclared field or role (§4.3)
  • M03217: Route when predicate contains non-deterministic expression (§4.3)
  • M03218: Route fallback target does not resolve to declared route (§4.3)
  • M03219: Claim field widget override does not accept ClaimFieldProps in props schema (§4.4)

M032x: View-to-composition compilation

  • M03220: View declared but not reachable from any app bundle route (warning)
  • M03221: View contains business logic or validation rule (warning — belongs in policy)
  • M03222: View references undeclared command or query
  • M03223: View exposes Sensitive field — runtime visibility enforcement required (warning)
  • M03224: View compilation produced non-deterministic identity path
  • M03225: View field has no applicable default widget kind — generic text fallback used (warning)