Adoption of the Verifiable Substrate: Op Log + Content-Addressed Blobs + Bitemporal Triples + Merkle Commitments + JetStream Fabric, Replacing the NCL/Filesystem/Git Substrate
Accepted
Context
Ontoref's current substrate is plana: NCL files on disk (.ontology/, adrs/, reflection/) + git history + filesystem watching + Nushell automation + Rust crates loading NCL into typed structs. Verification of any claim about a project requires running ontoref against the full SST: there is no way to attest 'this project's ontology has property X at time T' without re-evaluating the whole tree. The Self-Describing and DAG-Formalized Knowledge axioms are therefore aspirational — they describe what the protocol promises, not what an external verifier can confirm. Multi-actor concurrency is unaddressed: who wrote which assertion, when, with what authority, is implicit in git history rather than in the protocol. The recent commits 82a358f (#[onto_mcp_tool] catalog, OCI vault, ADR-018 mode hierarchy validation), 6721daf (NCL-first workflow generator), and ADRs 021 and 022 each surfaced the same structural deficit: every layer that needs typed contracts, signed operations, or external attestations reimplements them ad hoc. The verifiable substrate, prototyped in .coder/2026-05-24-verifiable-substrate-prototype.plan.md and consolidated in .coder/2026-05-25-implementation-final.plan.md, addresses this by replacing the substrate itself: every assertion about a project becomes a typed, signed, content-addressed operation in an append-only log; the materialized state (triples) and the cryptographic commitment (Merkle state root) are derivable from the log; JetStream carries operations to validators, materializers, and agents as a fabric, not as a runtime dependency. The change is structural, not incremental.
Decision
Adopt the verifiable substrate as the canonical substrate for ontoref, following the gates G1 through G12 of .coder/2026-05-25-implementation-final.plan.md. Construct the substrate in an isolated branch (ontoref-kernel) on top of the existing main. The substrate consists of seven layered crates (ontoref-types, ontoref-blobs, ontoref-oplog, ontoref-triples, ontoref-commit, ontoref-query, ontoref-fabric) composed by ontoref-core, plus ontoref-modes, ontoref-cli, ontoref-secrets (extracted pre-G1 from the daemon), and an internally rewritten ontoref-daemon that preserves auth and operator surface (ADR-021 carried verbatim). NCL/Nushell layers (.ontology/, adrs/*.ncl, reflection/) are removed at G12 after the kernel demo passes; their content is optionally migrated via tools/ncl-import. Two named tensions in .ontology/core.ncl are explicitly engaged by this decision (ondaod): ontology-vs-reflection and formalization-vs-adoption. The synthesis state and direction of motion for each are recorded in .coder/2026-05-25-implementation-final.plan.md §1.bis and MUST be read in conjunction with this ADR; collapsing either Spiral (e.g. by treating the substrate as 'reflection only' or by enforcing universal formalization without tier-1 fallback) constitutes a forbidden pattern. Activation tier for the prototype is Tier 2 (kernel + fabric); Wasm components, ZK proving, and Radicle p2p replication are deferred to post-G12 work and do not block this decision.
Constraints
- Hard New kernel crates (ontoref-types, ontoref-blobs, ontoref-oplog, ontoref-triples, ontoref-commit, ontoref-query, ontoref-fabric, ontoref-core, ontoref-modes, ontoref-cli) MUST NOT depend on stratumiops crates (stratum-graph, stratum-state, stratum-db, platform-nats)
- Hard Every operation MUST round-trip through canonical CBOR encoding with byte-stable output: encode(op) == encode(op) for all op; OpId(op) == blake3(encode(op))
- Hard Substrate crates MUST NOT contain todo!(), unimplemented!(), or panic!() with not-implemented messages
- Hard Plan §1.bis MUST exist and name both engaged tensions (ontology-vs-reflection, formalization-vs-adoption) with direction-of-motion and synthesis state; this ADR cites it
- Soft At G12 completion, crates/legacy/ MUST NOT exist; crates/ontoref-ontology/, crates/ontoref-reflection/ MUST NOT exist; reflection/, .ontology/, adrs/*.ncl, templates/ MUST NOT exist
Alternatives considered
- Continue evolving on the NCL+filesystem+git substrate; incrementally add typed contracts where pain emerges — rejected: Each new typed surface (#[onto_mcp_tool] catalog, OCI vault, ADR-021 TokenIssuer) has been bolted onto a substrate that does not natively support typed signed operations. The result is increasing surface area implementing the same primitives in isolation. The decision is not 'should we add typed signed operations', it is 'should one substrate-level layer own them'. Incrementalism preserves the substrate but pays the integration cost N times.
- Adopt an off-the-shelf knowledge graph database (Datomic, XTDB, TerminusDB, Neo4j) — rejected: These systems target operational knowledge bases, not protocols that projects implement. Bitemporality (Datomic, XTDB) covers a subset of the substrate's properties but not multi-actor signed operations or external attestation via state-root commitments. Wrapping one of them would make ontoref a runtime dependency (violating Invariant #1: Protocol Not Runtime). The substrate is a protocol specification with reference implementation; an off-the-shelf KG DB is a runtime product.
- Implement only the op-log layer (L0–L2) and skip triples/commit/query/fabric — rejected: Without the commitment layer (L4), external verification is impossible. Without the fabric (Tier 2), multi-actor demonstrations cannot run. Without the query layer (L5), the substrate's discoverability is worse than the current describe.nu surface. The substrate's value is the combination; partial adoption defers the verification property to indefinite future work.
- Build the substrate as a new project (substrate-* crates), keep ontoref consuming it — rejected: This was the predecessor plan's framing (.coder/2026-05-24-verifiable-substrate-implementation.plan.md naming). D9 reverses it: ontoref-* prefix preserved because the substrate is ontoref realising its own axioms, not a new product line. A separate substrate-* project would create two protocols where one suffices, splitting the contributor community and forcing every consumer to track two projects.