ontoref/adrs/adr-001-protocol-as-standalone-project.ncl

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    = {
        tag          = 'Grep,
        pattern      = "stratum-graph|stratum-state|stratum-orchestrator|stratum-llm|stratum-embeddings",
        paths        = ["crates/ontoref-ontology/Cargo.toml", "crates/ontoref-reflection/Cargo.toml", "crates/ontoref-daemon/Cargo.toml"],
        must_be_empty = true,
      },
      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    = {
        tag          = 'Grep,
        pattern      = "ONTOREF_PROJECT_ROOT",
        paths        = ["ontoref"],
        must_be_empty = false,
      },
      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    = { tag = 'FileExists, path = ".ontoref/config.ncl", present = true },
      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,
  },
}