RFC-0003 · 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-0003: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in
RFC-0003.This page is generated from the
lean/Gnomon/Spec/module for RFC-0003. Edit that source and regenerate this catalog.
Title: Composition Model
Status: draft
Owners: Module Runtime, UI Runtime
Diagnostic range: M03200-M03299
Proof citations in source: 18 / 18. Standalone proof verification is pending.
Definitions
| Term | Meaning |
|---|---|
| ClaimFieldProps | Reserved built-in composite widget prop type for Claim |
| Extension Point | Named position declared by a layout where aspects or other modules may contribute additional widgets; the only mechanism by which cross-cutting UI structure may be injected. |
| Layout | Layer 3 — structural region arrangement. |
| Page | Layer 2 — data orchestration and binding specification. |
| Route | Layer 1 — navigation identity and policy envelope. |
| View | Layer 0 — semantic authoring declaration in an .gnm file (entity or scope syntax) that the compiler transforms into execution-layer composition elements. |
| Widget | Layer 4 — smallest renderable unit with typed props. |
Diagnostics
| Code | Severity | Description |
|---|---|---|
M03200 | Error | Route failed to resolve to exactly one page |
M03201 | Error | Page failed to resolve to exactly one layout |
M03202 | Error | Layout region binding unresolved widget reference |
M03203 | Warning | Composition fallback invoked |
M03210 | Error | Two aspect contributions have identical priority for the same extension point |
M03211 | Warning | Aspect contribution targets extension point not declared on view/layout (contribution discarded) |
M03212 | Error | Extension point name conflicts with reserved layout property name |
M03213 | Error | Layout nesting exceeds maximum depth of 3 |
M03214 | Error | Layout nesting cycle detected |
M03215 | Error | Nested layout policy envelope less restrictive than parent |
M03216 | Error | Route when predicate references undeclared field or role |
M03217 | Error | Route when predicate contains non-deterministic expression |
M03218 | Error | Route fallback target does not resolve to declared route |
M03219 | Error | Claim field widget override does not accept ClaimFieldProps in props schema |
M03220 | Warning | View declared but not reachable from any app bundle route |
M03221 | Warning | View contains business logic or validation rule (belongs in policy) |
M03222 | Error | View references undeclared command or query |
M03223 | Warning | View exposes Sensitive field — runtime visibility enforcement required |
M03224 | Error | View compilation produced non-deterministic identity path |
M03225 | Warning | View field has no applicable default widget kind — generic text fallback used |
Invariants
- A nested layout MUST NOT declare a policy envelope less restrictive than its parent’s. (enforced by: compile-time)
- A nested layout’s extension points are scoped to that layout and MUST NOT be addressable by aspects targeting the parent’s extension points. (enforced by: compile-time)
- A page MUST resolve to exactly one layout definition. (enforced by: compile-time)
- A route MUST resolve to exactly one page definition. (enforced by: compile-time)
- A route
fallbacktarget MUST resolve to a declared route. (enforced by: compile-time) - A route’s
whenpredicate MUST be a deterministic constraint expression with no arbitrary code. (enforced by: compile-time) - A route’s
whenpredicate is evaluated after the policy-envelope authorization check and MUST NOT be used to bypass it. (enforced by: runtime) - A view MAY reference only commands and queries declared in the same module or its imports. (enforced by: compile-time)
- A widget overriding the default Claim
renderer MUST accept ClaimFieldProps in its props schema. (enforced by: compile-time) - Each view declaration MUST compile to exactly one layout element wrapping its page. (enforced by: compile-time)
- Each view declaration MUST compile to exactly one page element. (enforced by: compile-time)
- Layout nesting MUST NOT exceed three levels (root, sublayout, sub-sublayout). (enforced by: compile-time)
- Layout nesting cycles MUST be detected and rejected at compile time. (enforced by: compile-time)
- Layouts MUST resolve all extension-point widget bindings deterministically; aspect contributions MUST yield a unique total ordering by priority, with ties as compile errors. (enforced by: compile-time)
- Missing composition targets MUST produce explicit non-silent diagnostics and fallback usage MUST be telemetry-visible. (enforced by: runtime)
- Modules migrating from direct composition authoring to view declarations MUST produce functionally equivalent compiled bundles. (enforced by: compile-time)
- Policy envelopes from a view’s
actionsblock MUST be compiled into the route/page policy envelope and not silently dropped. (enforced by: compile-time) - Resolution MUST NOT use unrestricted network sources on resolve-on-miss paths. (enforced by: runtime)
- Route and page policy envelopes MUST be preserved through resolution and MUST NOT be bypassed by composition. (enforced by: runtime)
- View declarations MUST NOT contain business logic, validation rules, or authorization predicates beyond actor-to-action bindings. (enforced by: compile-time)
- Widget resolution MUST use canonical identity lookups. (enforced by: runtime)
- Writes to Claim
fields MUST go through a declared ActionType command; widget interactions not backed by a declared action MUST be rejected. (enforced by: runtime)
Normative Statements
Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.
Authoring Contract for Composition Layers
- SHOULD — Each declared composition layer element SHOULD export canonical identity metadata to the compiled bundle identity envelope. (proof citation:
rfc0003_composition_layer_exports_identity; verification pending) - MUST — The composition contract MUST represent the four execution layers explicitly.
- MUST — route.page, page.layout, and layout.regions[*] MUST resolve to declared identifiers. (proof citation:
rfc0003_b23_grounded; verification pending)
Compatibility and Migration
- MUST — Compatibility adapters MUST include deprecation and sunset criteria.
- MAY — Legacy mapping layers MAY exist only behind explicit compatibility adapters.
- MUST — Modules migrating from direct composition authoring to view declarations MUST produce functionally equivalent compiled bundles.
Composition Layers
- MUST_NOT — A nested layout MUST NOT declare a policy envelope less restrictive than its parent.
- MUST — A widget overriding a Claim
field MUST accept ClaimFieldProps in its props schema or compile error M03219 is produced. (proof citation: rfc0003_widget_claim_props_required; verification pending) - MUST_NOT — Aspects MUST NOT contribute widgets to positions that are not declared extension points.
- MUST — Each aspect contribution MUST have an effective integer priority; a supplied source priority MUST be an integer, and an omitted source priority MUST default to 0 before ordering and tie detection.
- MUST — If a route’s when predicate evaluates false, the runtime MUST redirect without exposing route content.
- MUST — Layout nesting cycles and depths exceeding 3 levels MUST be detected and produce errors M03213/M03214. (proof citation:
rfc0003_layout_cycles_or_depth; verification pending) - MUST — The runtime MUST reject attempts to write a Claim
field through widget interaction not backed by a declared action. (proof citation: rfc0003_widget_claim_writes_via_action; verification pending) - MUST — Two contributions to the same extension point with identical priority MUST produce compile error M03210. (proof citation:
rfc0003_extension_priority_collision; verification pending)
Fallback Semantics
- MUST — Fallback usage MUST be telemetry-visible.
- MUST — Missing composition targets MUST produce explicit non-silent diagnostics. (proof citation:
rfc0003_b44_grounded; verification pending) - SHOULD — Non-dev mode SHOULD render controlled warning placeholders, not hard crashes.
Invariants
- MUST — Layout MUST resolve all extension point widget bindings deterministically with a unique total ordering; ties are a compile error.
- MUST — Page MUST resolve to exactly one layout definition.
- MUST — Route MUST resolve to exactly one page definition.
- MUST — Widget resolution MUST use canonical identity lookups. (proof citation:
rfc0003_widget_resolution_canonical_id; verification pending)
Resolution Order
- MUST_NOT — No unrestricted network source is allowed in resolve-on-miss paths.
- MUST — Resolution MUST follow the order: in-memory registry, trusted local compiled cache, explicit placeholder/failure surface with telemetry.
Scope
- MUST — Authors MUST use the semantic authoring layer (view declarations) unless the module explicitly requires direct execution-layer control. (proof citation:
rfc0003_use_semantic_authoring_layer; verification pending)
Security and Authorization
- MUST — Authorization bindings compiled from view actions blocks MUST receive the same enforcement weight as directly authored policy envelopes. (proof citation:
rfc0003_action_bindings_uniform_enforcement; verification pending) - MUST_NOT — Composition MUST NOT bypass operation/policy checks. (proof citation:
rfc0003_b42_grounded; verification pending) - MUST — Composition-level policy failures MUST be diagnosable. (proof citation:
rfc0003_composition_policy_failures_diagnosable; verification pending) - MUST — Route and page policy envelopes MUST be preserved through resolution. (proof citation:
rfc0003_policy_envelope_preserved; verification pending)
View-to-Composition Compilation Path
- MUST — Compiled composition elements MUST use identity paths derived from the view’s canonical namespace path. (proof citation:
rfc0003_canonical_namespace_paths; verification pending) - MUST — Each field in a show or section block MUST compile to a typed widget based on its declared semantic type. (proof citation:
rfc0003_show_field_typed_widget; verification pending) - MUST — Each view declaration MUST compile to exactly one page element and exactly one layout element wrapping the page.
- MUST_NOT — The compiler MUST NOT silently drop action-level authorization from view declarations. (proof citation:
rfc0003_b31_grounded; verification pending) - MUST_NOT — View declarations MUST NOT contain business logic, validation rules, or authorization predicates beyond actor-to-action bindings. (proof citation:
rfc0003_b14_grounded; verification pending) - MUST — Views not referenced by any app bundle MUST NOT produce route elements (warning M03220). (proof citation:
rfc0003_b40_grounded; verification pending)
Linked References
(no cross-RFC dependencies)