Substrate Views — Dynamic Context Provisioning by Composing Levels, Verified Under Partial Knowledge, Tuned From the Interaction Trace

Context

ADR-032 consolidated the project layout under .ontoref/ and ADR-035 added the positioning layer, so a project's knowledge now spans many heterogeneous levels (ontology, adrs, reflection, positioning, catalog, assets, private strategy, diffusion). Holding all of it at once is not workable for a working session — 'todo junto no es gestionable'. Three prior facts shape the resolution. (1) Cross-project work has repeatedly failed in agent sessions: the failure mode was the agent NAVIGATING into a foreign repository, losing its thread and mutating where it should not. (2) The project chose persona/discipline as a first-class axis ORTHOGONAL to the trust actor of api-catalog.ncl — the work AREA a session operates in. (3) ADR-045 generalized levels to relative parent chains and added domain co-tenancy resolved BY WITNESS, never by clone (ADR-028), reusing host_entry_type (chain, mount, digest). What was missing is a single primitive that, given a discipline, provisions only the slice of levels that area needs — intra-project AND cross-project — presents it as one coherent working context, routes every mutation back to the authoritative home of the level it belongs to, and is consumed identically by CLI sessions, agent sessions, and the daemon interfaces (UI / MCP / API / GraphQL). The governing analogy is jj over git: a content-addressed truth store (the levels — ADR-023/025) with an operation-centric working layer above it (the view + engine) that records every operation in an op log (the interaction trace — ADR-037, and the oplog — ADR-036), composes and recomposes on demand, and colocates without forcing migration (ADR-029 tier coexistence). Two further requirements were stated explicitly. First, a mounted level must provide usable knowledge AND a means of verification that, in many cases, works WITHOUT complete knowledge of the level's content — the cross-project case cannot hold the whole foreign substance. Second, the engine must learn from the generated interaction — use the loop FROM THE START and adjust as it consumes real data, not prepare a seam for later.

Decision

Establish the substrate view (schema .ontoref/reflection/schemas/substrate-view.ncl) as the unit of dynamic context provisioning, via five mechanisms. (1) DISCIPLINE-SCOPED COMPOSITION — a view is f(discipline, context, actor): the discipline (the work AREA; area equals discipline) selects which levels mount, the actor filters what is visible and mutable. A view composes only the slice the area needs, never the whole project, and is decomposed on exit. (2) PERSISTENCE ROUTING — each mounted level declares persistence ('Inline / 'LiftedOut / 'Remote) and the engine routes every mutation back to that level's authoritative home. 'Inline composes from local files with no daemon (ADR-029 local fallback); 'LiftedOut and 'Remote resolve by witness through catalog discovery (ADR-028/030/045), NEVER cloned. Cross-project knowledge enters as a 'Remote level — the agent never leaves its repo. (3) VERIFICATION UNDER PARTIAL KNOWLEDGE — each level declares a verify means ('Local / 'Digest / 'Validator / 'Commitment). An out-of-repo level MUST use a partial-knowledge means: a content-addressed digest (ADR-045 source.digest), a declared validator answering consistency queries without exposing full content (ADR-026), or a cryptographic commitment proving a claim against committed-but-unrevealed content (ADR-023 G5 witness). Verification by holding the complete foreign substance is forbidden. (4) LEARNED TUNING FROM THE INTERACTION TRACE — a view's declared levels and actions are its AUTHORITY ENVELOPE. Elements marked 'Learned are tuned LIVE (selection, order, salience) by the engine as it consumes the interaction-trace stream named in learns_from (ADR-037), starting from the declared prior. The active recipe is the declared prior composed with a chain of witnessed adjustments — prior plus ops, exactly as a VCS working state is base plus operations. (5) INTERFACE PARITY — the same primitive backs CLI sessions, agent sessions, and the daemon interfaces: a UI panel or an MCP tool IS a mounted substrate view, declared by the surfaces field, not bespoke code. The learning loop is constitutive and used from the start; a view that declares no learns_from is its declared prior verbatim, so the adoption floor pays nothing.

Constraints

• Hard The engine composes only levels and authorizes only mutations the substrate view declared; 'Learned tunes selection, order and salience strictly within the declared envelope and never adds a level or a mutation route
• Hard Every learned adjustment to a view's active recipe is recorded as a witnessed operation in the interaction trace and is reversible; no silent mutation of the recipe in effect
• Hard The active recipe at any time equals the declared prior composed with the witnessed adjustment chain, and must be reconstructable and replayable from the declaration plus the interaction trace; declared salience is never overwritten by learned deltas
• Soft With no interaction data or no daemon, a view mounts its declared prior verbatim; learning is the accelerated path, not a precondition for composition
• Hard Every level with persistence 'LiftedOut or 'Remote must declare a witness source and a partial-knowledge verify means ('Digest, 'Validator or 'Commitment); it is never verified by holding complete content

Alternatives considered

• Prepare the seam for learning but defer the engine (D2 deferred) — rejected: The decision is to use the loop from the start and adjust in consumption of real data. Deferring freezes the reflection axis and discards the prior-to-posterior loop, collapsing ontology-vs-reflection toward static ontology — the very Yang freeze ondaod exists to prevent. The prior-as-declared-view framing makes 'from the start' safe, so there is no risk-based reason to defer.
• Let the engine learn freely, composing levels beyond the declared envelope — rejected: Collapses ontology-vs-reflection toward reflection-dominates: the engine deciding authority bypasses ADR-024 internal-coherence-enforced, because a level or mutation route the view never declared would enter without a declared, witnessed path. C1 forbids it — authority is declared, only sintonia is learned.
• Require human acceptance of every learned adjustment — rejected: Kills 'adjust in consumption' with prohibitive friction. Safety does not require pre-acceptance: the jj op-log property — every adjustment is a witnessed, reversible operation (C2) and the recipe is reconstructable from prior plus ops (C3) — gives auditability and undo without a human in every loop.
• Verify remote levels by cloning the foreign project — rejected: Reintroduces the cross-project-in-sessions failure and does not scale across the ecosystem. ADR-028 verify-by-witness-not-clone exists precisely to avoid this; C5 makes partial-knowledge verification mandatory for out-of-repo levels.
• A flat view recipe with no envelope/tuning distinction — rejected: Makes C1 inexpressible: if declaration and learning are indistinguishable, the authority boundary cannot be protected and the engine can silently widen it. The eligibility ('Always/'Learned) split is the minimal addition that makes the authority line a typed, checkable fact.

Anti-patterns

• Engine expands authority — The engine composes a level or authorizes a mutation the substrate view never declared, on the grounds that the interaction data suggested it. Learning is allowed to widen what is authoritative, not merely to tune within a declared envelope.
• Silent recipe drift — The engine mutates the active recipe without recording a witnessed, reversible operation, so the recipe in effect cannot be reconstructed or undone and diverges from the declared prior without a trace.
• Engine decides truth — The learned recipe is treated as authoritative ontology and the declared prior is discarded as stale, inverting the prior-to-posterior relationship so that reflection becomes the source of truth.
• Clone to verify — A remote or lifted-out level is verified by materializing its complete content rather than by digest, validator or commitment — reintroducing the navigational cross-project failure and forfeiting partial-knowledge verification.
• Learning as a gate — Composition is blocked until enough interaction data exists or the daemon is running; cold start fails instead of falling back to the declared prior, turning the engine into a hard dependency at the adoption floor.

Related ADRs

ADR-045 · ADR-028 · ADR-024 · ADR-023 · ADR-026 · ADR-037 · ADR-036 · ADR-029 · ADR-013 · ADR-031 · ADR-035 · ADR-018