gnomonlearn
Docs/RFC-0003/Reference catalog

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.

← Read the authored RFC

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

TermMeaning
ClaimFieldPropsReserved built-in composite widget prop type for Claim fields, exposing value, confidence, status, source, and asserted_by.
Extension PointNamed 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.
LayoutLayer 3 — structural region arrangement.
PageLayer 2 — data orchestration and binding specification.
RouteLayer 1 — navigation identity and policy envelope.
ViewLayer 0 — semantic authoring declaration in an .gnm file (entity or scope syntax) that the compiler transforms into execution-layer composition elements.
WidgetLayer 4 — smallest renderable unit with typed props.

Diagnostics

CodeSeverityDescription
M03200ErrorRoute failed to resolve to exactly one page
M03201ErrorPage failed to resolve to exactly one layout
M03202ErrorLayout region binding unresolved widget reference
M03203WarningComposition fallback invoked
M03210ErrorTwo aspect contributions have identical priority for the same extension point
M03211WarningAspect contribution targets extension point not declared on view/layout (contribution discarded)
M03212ErrorExtension point name conflicts with reserved layout property name
M03213ErrorLayout nesting exceeds maximum depth of 3
M03214ErrorLayout nesting cycle detected
M03215ErrorNested layout policy envelope less restrictive than parent
M03216ErrorRoute when predicate references undeclared field or role
M03217ErrorRoute when predicate contains non-deterministic expression
M03218ErrorRoute fallback target does not resolve to declared route
M03219ErrorClaim field widget override does not accept ClaimFieldProps in props schema
M03220WarningView declared but not reachable from any app bundle route
M03221WarningView contains business logic or validation rule (belongs in policy)
M03222ErrorView references undeclared command or query
M03223WarningView exposes Sensitive field — runtime visibility enforcement required
M03224ErrorView compilation produced non-deterministic identity path
M03225WarningView field has no applicable default widget kind — generic text fallback used

Invariants

  1. A nested layout MUST NOT declare a policy envelope less restrictive than its parent’s. (enforced by: compile-time)
  2. 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)
  3. A page MUST resolve to exactly one layout definition. (enforced by: compile-time)
  4. A route MUST resolve to exactly one page definition. (enforced by: compile-time)
  5. A route fallback target MUST resolve to a declared route. (enforced by: compile-time)
  6. A route’s when predicate MUST be a deterministic constraint expression with no arbitrary code. (enforced by: compile-time)
  7. A route’s when predicate is evaluated after the policy-envelope authorization check and MUST NOT be used to bypass it. (enforced by: runtime)
  8. A view MAY reference only commands and queries declared in the same module or its imports. (enforced by: compile-time)
  9. A widget overriding the default Claim renderer MUST accept ClaimFieldProps in its props schema. (enforced by: compile-time)
  10. Each view declaration MUST compile to exactly one layout element wrapping its page. (enforced by: compile-time)
  11. Each view declaration MUST compile to exactly one page element. (enforced by: compile-time)
  12. Layout nesting MUST NOT exceed three levels (root, sublayout, sub-sublayout). (enforced by: compile-time)
  13. Layout nesting cycles MUST be detected and rejected at compile time. (enforced by: compile-time)
  14. 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)
  15. Missing composition targets MUST produce explicit non-silent diagnostics and fallback usage MUST be telemetry-visible. (enforced by: runtime)
  16. Modules migrating from direct composition authoring to view declarations MUST produce functionally equivalent compiled bundles. (enforced by: compile-time)
  17. Policy envelopes from a view’s actions block MUST be compiled into the route/page policy envelope and not silently dropped. (enforced by: compile-time)
  18. Resolution MUST NOT use unrestricted network sources on resolve-on-miss paths. (enforced by: runtime)
  19. Route and page policy envelopes MUST be preserved through resolution and MUST NOT be bypassed by composition. (enforced by: runtime)
  20. View declarations MUST NOT contain business logic, validation rules, or authorization predicates beyond actor-to-action bindings. (enforced by: compile-time)
  21. Widget resolution MUST use canonical identity lookups. (enforced by: runtime)
  22. 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

  1. 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)
  2. MUST — The composition contract MUST represent the four execution layers explicitly.
  3. MUST — route.page, page.layout, and layout.regions[*] MUST resolve to declared identifiers. (proof citation: rfc0003_b23_grounded; verification pending)

Compatibility and Migration

  1. MUST — Compatibility adapters MUST include deprecation and sunset criteria.
  2. MAY — Legacy mapping layers MAY exist only behind explicit compatibility adapters.
  3. MUST — Modules migrating from direct composition authoring to view declarations MUST produce functionally equivalent compiled bundles.

Composition Layers

  1. MUST_NOT — A nested layout MUST NOT declare a policy envelope less restrictive than its parent.
  2. 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)
  3. MUST_NOT — Aspects MUST NOT contribute widgets to positions that are not declared extension points.
  4. 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.
  5. MUST — If a route’s when predicate evaluates false, the runtime MUST redirect without exposing route content.
  6. 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)
  7. 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)
  8. 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

  1. MUST — Fallback usage MUST be telemetry-visible.
  2. MUST — Missing composition targets MUST produce explicit non-silent diagnostics. (proof citation: rfc0003_b44_grounded; verification pending)
  3. SHOULD — Non-dev mode SHOULD render controlled warning placeholders, not hard crashes.

Invariants

  1. MUST — Layout MUST resolve all extension point widget bindings deterministically with a unique total ordering; ties are a compile error.
  2. MUST — Page MUST resolve to exactly one layout definition.
  3. MUST — Route MUST resolve to exactly one page definition.
  4. MUST — Widget resolution MUST use canonical identity lookups. (proof citation: rfc0003_widget_resolution_canonical_id; verification pending)

Resolution Order

  1. MUST_NOT — No unrestricted network source is allowed in resolve-on-miss paths.
  2. MUST — Resolution MUST follow the order: in-memory registry, trusted local compiled cache, explicit placeholder/failure surface with telemetry.

Scope

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

  1. 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)
  2. MUST_NOT — Composition MUST NOT bypass operation/policy checks. (proof citation: rfc0003_b42_grounded; verification pending)
  3. MUST — Composition-level policy failures MUST be diagnosable. (proof citation: rfc0003_composition_policy_failures_diagnosable; verification pending)
  4. MUST — Route and page policy envelopes MUST be preserved through resolution. (proof citation: rfc0003_policy_envelope_preserved; verification pending)

View-to-Composition Compilation Path

  1. MUST — Compiled composition elements MUST use identity paths derived from the view’s canonical namespace path. (proof citation: rfc0003_canonical_namespace_paths; verification pending)
  2. 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)
  3. MUST — Each view declaration MUST compile to exactly one page element and exactly one layout element wrapping the page.
  4. MUST_NOT — The compiler MUST NOT silently drop action-level authorization from view declarations. (proof citation: rfc0003_b31_grounded; verification pending)
  5. 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)
  6. 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)