97 lines
7.0 KiB
XML
97 lines
7.0 KiB
XML
let d = import "defaults.ncl" in
|
|
|
|
d.make_adr {
|
|
id = "adr-001",
|
|
title = "Ontoref is a Standalone Protocol Project, Not Part of Stratumiops",
|
|
status = 'Accepted,
|
|
date = "2026-03-12",
|
|
|
|
context = "The ontology/reflection patterns originated inside stratumiops as self-description tooling (stratum-ontology-core, stratum-reflection-core, stratum-daemon). Consumer projects (typedialog, vapora, kogral) needed the same patterns but had no path to adoption that did not entangle them with stratumiops' pipeline-specific crates (stratum-graph, stratum-state, stratum-orchestrator). Protocol evolution (schema changes, ADR lifecycle, daemon features) was blocked behind stratumiops release cycles. The three crates were logically a specification layer that happened to live in the wrong repo.",
|
|
|
|
decision = "Ontoref is extracted as a standalone protocol project with independent versioning, CI, and crates: ontoref-ontology (Rust types for the ontology graph), ontoref-reflection (mode runner and schema validation), ontoref-daemon (NCL export cache, file watcher, actor registry). Consumer projects adopt the protocol via a thin `scripts/ontoref` bash wrapper and a `.ontoref/config.ncl` declaration. The ontoref project itself is allowed to use stratum-db and platform-nats as optional peer dependencies via workspace path references, since those crates are infrastructural rather than domain-specific.",
|
|
|
|
rationale = [
|
|
{
|
|
claim = "Protocol concerns are orthogonal to pipeline concerns",
|
|
detail = "Stratumiops' primary value is the action graph execution engine (stratum-orchestrator) and its pipeline crates. The ontology/ADR/reflection protocol serves any project — not just stratumiops consumers. Coupling forces every protocol adopter to also accept stratumiops' dependency tree.",
|
|
},
|
|
{
|
|
claim = "Independent versioning enables protocol stability",
|
|
detail = "Protocol schema changes (new ADR fields, new ontology edge kinds, new reflection mode types) should not require a stratumiops release. Ontoref's version contract is between ontoref and its consumers; stratumiops is one consumer, not the owner.",
|
|
},
|
|
{
|
|
claim = "ONTOREF_PROJECT_ROOT decouples protocol tooling from project location",
|
|
detail = "The ontoref entry point accepts ONTOREF_PROJECT_ROOT as an env var, defaulting to its own SCRIPT_DIR only if unset. Consumer wrappers (scripts/ontoref) set ONTOREF_PROJECT_ROOT to their own root before exec-ing the ontoref entry. This design allows one ontoref checkout to serve multiple projects.",
|
|
},
|
|
{
|
|
claim = "stratum-db and platform-nats as peer deps, not bundled deps",
|
|
detail = "ontoref-daemon uses stratum-db (for optional SurrealDB persistence) and platform-nats (for NATS events) as optional features via path dependencies. These crates are infrastructural and re-usable. Bundling them into ontoref would duplicate the crates; referencing them as peers preserves the single canonical implementation.",
|
|
},
|
|
],
|
|
|
|
consequences = {
|
|
positive = [
|
|
"Consumer projects (typedialog, vapora, kogral) can adopt the protocol with a single wrapper + config file",
|
|
"Protocol schema evolution is independent of stratumiops pipeline releases",
|
|
"One ontoref checkout serves all projects via ONTOREF_PROJECT_ROOT env var",
|
|
"Stratumiops becomes a first-class protocol consumer, not the protocol owner — eats its own dogfood",
|
|
"ontoref-daemon is protocol-agnostic: any project can use it for NCL caching regardless of whether it uses stratumiops",
|
|
],
|
|
negative = [
|
|
"ontoref-daemon has path dependencies on stratumiops/crates — requires both repos to be checked out locally for builds",
|
|
"Two entry points per project: scripts/stratumiops (pipeline) and scripts/ontoref (protocol) — dual maintenance surface",
|
|
"ONTOREF_ROOT must be set or defaulted correctly in every consumer wrapper",
|
|
],
|
|
},
|
|
|
|
alternatives_considered = [
|
|
{
|
|
option = "Keep all tooling in stratumiops, consumers depend on it as a git subtree or submodule",
|
|
why_rejected = "Submodule/subtree patterns create update friction and do not solve the versioning coupling. Every consumer needs stratumiops' full dependency tree even for protocol-only use.",
|
|
},
|
|
{
|
|
option = "Publish ontoref crates to crates.io and consume via version pins",
|
|
why_rejected = "Rapid iteration on protocol schemas makes published crate semantics too rigid at this stage. Path dependencies allow simultaneous development of protocol and consumers without publication ceremony.",
|
|
},
|
|
{
|
|
option = "Inline protocol tooling into each consumer project separately",
|
|
why_rejected = "Schema drift across projects would immediately arise. The protocol's value is precisely its shared contract — decentralizing it defeats the purpose.",
|
|
},
|
|
],
|
|
|
|
constraints = [
|
|
{
|
|
id = "no-stratumiops-domain-deps",
|
|
claim = "ontoref crates must not import stratumiops domain crates: stratum-graph, stratum-state, stratum-orchestrator, stratum-llm, stratum-embeddings",
|
|
scope = "crates/ontoref-ontology/Cargo.toml, crates/ontoref-reflection/Cargo.toml, crates/ontoref-daemon/Cargo.toml",
|
|
severity = 'Hard,
|
|
check_hint = "rg 'stratum-graph|stratum-state|stratum-orchestrator|stratum-llm|stratum-embeddings' crates/*/Cargo.toml",
|
|
rationale = "Domain crates from stratumiops encode pipeline-specific types. Importing them would re-couple the protocol to the pipeline and prevent independent adoption.",
|
|
},
|
|
{
|
|
id = "ontoref-project-root-consumer-set",
|
|
claim = "The ontoref entry point must not unconditionally overwrite ONTOREF_PROJECT_ROOT — it must default only when unset",
|
|
scope = "ontoref (bash entry point)",
|
|
severity = 'Hard,
|
|
check_hint = "grep 'ONTOREF_PROJECT_ROOT' ontoref | grep -v ':-'",
|
|
rationale = "Consumer wrappers (scripts/ontoref) set ONTOREF_PROJECT_ROOT to their own root before calling the ontoref entry. If the entry overwrites it, the daemon and ADR queries target ontoref's own repo instead of the consumer project.",
|
|
},
|
|
{
|
|
id = "ontoref-config-only-required-artifact",
|
|
claim = "A consumer project must only need .ontoref/config.ncl and scripts/ontoref to adopt the protocol — no other files copied into the consumer",
|
|
scope = "consumer project onboarding",
|
|
severity = 'Soft,
|
|
check_hint = "ls .ontoref/ scripts/ontoref",
|
|
rationale = "Minimizing the consumer adoption surface ensures the protocol is adopted voluntarily and fully, not partially via file copies that drift from the source.",
|
|
},
|
|
],
|
|
|
|
related_adrs = ["adr-002-daemon-for-caching-and-notification-barrier"],
|
|
|
|
ontology_check = {
|
|
decision_string = "ontoref is a standalone project providing protocol tooling; consumers adopt via wrapper + config; stratum-db and platform-nats are optional peer deps",
|
|
invariants_at_risk = ["protocol-not-runtime"],
|
|
verdict = 'Safe,
|
|
},
|
|
}
|