Operations Layer — Domain Operations as the Agent's Only Project-Touching Path

Context

After extensive interactive diagnosis across the session of 2026-05-25 (see .coder/2026-05-25-substrate-utility-audit.info.md and the dialogue that produced it .coder/2026-05-25-implementation-final-stop-review_done.md), the recurring pain experienced across all 19 ontoref-onboarded projects (provisioning, mina, lian-build, forge-fleet, libre-{daoshi,wuji,forge}, stratumiops, rustelo, vapora, kogral, secretumvault, typedialog, jpl-website, personal-ontoref, jpl-ontoref, cloudatasave, build-in-layers, mirador, DD7pasos, librosys, ontoref itself) is located at a layer that is neither the ontology layer (rich, declarative, mature) nor the verifiable substrate (G1-G10 of the ontoref-kernel work is green and works).

The pain lives at the acoplamiento entre acción y consumo — agents have generic primitives (Bash, Edit, Read, Write) plus optional ontology access (34 query-only MCP tools listed in crates/ontoref-daemon/src/mcp/mod.rs), and the ontology consumption is never required before action. Evidence from this repository:

- MCP surface is 34 tools, all queries: list_projects, search, describe, list_adrs, get_adr, get_node, validate, impact, status, guides, etc. Mutations are limited to qa_add, action_add, bookmark_add, set_project, config_update — META operations on ontoref itself, not DOMAIN operations on the project being worked on. - crates/ontoref-daemon/src/federation.rs (419 lines) implements cross-project BFS impact graph with depth 5 and HTTP for push-only remotes. It is unused: install/resources/remote-projects.ncl is the empty list. The infrastructure exists; the use case for it has not been activated. - ADR-012 explicitly bypasses the NCL canon (repo_kinds.txt as grep-readable side channel) because nickel export was too slow for hot-path dispatch (200-400ms per invocation). The NCL canon is aspirational; the operative path goes around it whenever performance demands it. - The three-layer model of ADR-020 declares an integration surface (Layer 2) but its Layer-2 contract is type-shape (schemas, catalog data), not operation-shape — consumers bind to data structures, not to verbs.

The consequence: agents consume the ontology only when nudged; otherwise they operate through Bash/Edit on raw filesystem, producing outcomes that may or may not respect declared constraints. Validation runs post-mortem (pre-commit hooks, CI checks) rather than constitutively. Cross-project coordination requires the human to remember what lives where. The interactive session that produced this ADR consumed many hours of dialogue precisely because the human had to refill context the agent failed to fetch — and this dialogue cannot be relied on to persist across sessions or to survive context compaction.

The verifiable substrate (ADR-023, Proposed) provides storage and witness mechanisms (canonical encoding, bitemporal triples, content-addressed blobs, state-root commitments) but does not on its own resolve why agents bypass the declared content. The substrate is necessary infrastructure for receipts and witnesses; it is not the mechanism that forces consumption.

Decision

Every ontoref-onboarded project carries — or progressively gains — a catalog of domain operations exposed exclusively to agents as their tool surface. The agent's configuration on a project DOES NOT include generic primitives (Bash, Edit, Read, Write) over project paths. The only path by which an agent may query, mutate, or affect the project is through operations in the catalog.

Each domain operation declares:

1. Required ontological precondition slice — which nodes, ADRs, state dimensions, constraints, or external project entities must be loaded and validated for this operation to proceed. 2. Input contract — typed inputs, satisfied or rejected at invocation time. 3. Effects — what the operation may change (file paths, state dimensions, downstream entities, cross-project signals). 4. Witness shape — what receipt is emitted upon successful completion.

The operation runtime:

1. Loads the declared precondition slice before invoking the operation body. Loading is constitutive of the invocation, not a courtesy of the agent. 2. Validates the precondition slice against the operation's declared constraints. Failure produces a structured block message naming the unmet precondition, not a generic error. 3. Executes the operation body in a confined context that has access only to the loaded slice and the declared effect scope. 4. Emits a signed receipt: operation_id, actor, timestamp, state_root, effect summary, downstream project signals if any.

Cross-project operations are routed through the existing federation.rs infrastructure: an operation in project A that declares a dependency on or effect in project B resolves the B-side via the federated query mechanism. Operation receipts are first-class entities in the substrate (operations as entities, per the audit's H7 finding), queryable cross-project.

Runtime placement is shared: the operations runtime is built once and lives in ontoref-daemon (or a new ontoref-ops crate, decided at implementation time). The operation catalog is per-project: each project owns its domain verbs under a new declared path (catalog/operations/), with each operation contract written in NCL using the ontoref-derive macros to surface to the MCP/API layer.

Agent configuration discipline: agents launched into an ontoref-onboarded project receive an MCP server whose tool list is exactly the project's operations catalog (plus the existing META operations like describe). Raw filesystem tools over the project root are disabled at the agent-launch boundary. The launcher is responsible for enforcing this; ontoref provides the catalog and the runtime.

Constraints

• Hard Agent-facing mutations on a project's authoritative state must go through catalogued operations (dispatch_op), not raw filesystem primitives (Bash/Edit). Direct file edits bypass typed preconditions and the witness-seam.
• Hard Every catalogued operation must declare at least one typed precondition. Ops with no preconditions provide no validation plane and defeat the purpose of the operations layer.

Alternatives considered

• Keep generic agent tools, improve ontology documentation and the MCP query surface — rejected: Years of evidence across 19 projects demonstrate that better declarative content does not lead to consumption when consumption is optional. The optionality IS the failure mode; adding more documentation reinforces the same pattern at greater cost.
• Build the full G1-G12 substrate plan as written, defer operations layer indefinitely — rejected: The substrate without an operations layer is verifiable storage that no agent uses operationally. G1-G10 is already green; G11-G12 (multi-actor daemon, demo) would extend storage without addressing why agents bypass the storage. The recurring pain persists across all of G11-G12's work.
• Per-project ad-hoc solutions (custom CLI wrappers, project-specific guardrails, per-project skills) — rejected: Combinatorial cost across 19 projects. No shared infrastructure means each project re-derives the constrained-action pattern. Cross-project federation impossible by construction. This is the current state and the source of the recurring pain.
• Revert ontoref to pre-substrate state and restart the design — rejected: The substrate G1-G10 provides exactly the receipt/witness mechanism this ADR's operations layer requires. Reverting throws away material that becomes load-bearing under this decision. The substrate was not wrong; it was incomplete on its own. ADR-023 and ADR-024 together close the gap.
• Enforce ontology consumption via stricter pre-action hooks instead of constraining the tool surface — rejected: Hooks fire on commit, not on action. An agent can perform many actions before commit; by then the cost of bad action is already paid. Constraining the tool surface is the only mechanism that intervenes before the action exists.

Related ADRs

ADR-001 · ADR-005 · ADR-012 · ADR-018 · ADR-020 · ADR-022 · ADR-023