ontoref/adrs/adr-002-daemon-for-caching-and-notification-barrier.ncl

let d = import "defaults.ncl" in

d.make_adr {
  id        = "adr-002",
  title     = "Ontoref Daemon for NCL Caching, File Watching, and Actor Notification Barrier",
  status    = 'Accepted,
  date      = "2026-03-12",
  supersedes = "stratumiops:adr-007-optional-daemon-for-caching-and-persistence",

  context = "Nushell reflection modules invoke `nickel export` as a subprocess ~39 times per full sync scan, taking 2m42s. Each invocation forks a new process (~100ms). There is no shared state between developers and agents working on the same project, no notification when a peer changes an ontology or ADR file mid-session, and no persistent store for scan results. The protocol-not-runtime axiom forbids required runtime services — any daemon must be optional with full subprocess fallback. This ADR supersedes stratumiops adr-007, which designed this system inside stratumiops before the protocol was extracted to ontoref.",

  decision = "ontoref-daemon is an optional persistent daemon providing: (1) NCL export caching — results keyed by (path, mtime, import_path) served via HTTP, file watcher invalidates on change; (2) actor registry — developers, agents, CI register on startup with deterministic tokens (type:hostname:pid), sweep reaps stale sessions every 30s; (3) notification barrier — file changes in .ontology/, adrs/, reflection/ generate typed notifications stored in a per-project ring buffer; pre-commit hook queries pending notifications and blocks commits until acknowledged (fail-open: daemon down = commit allowed). Consumer projects configure the daemon via `.ontoref/config.ncl` (daemon.enabled, daemon.port, db.enabled, db.url). All Nushell modules fall back to direct `nickel export` subprocess when the daemon is unavailable. stratum-db (optional feature, path dep on stratumiops) handles SurrealDB persistence. platform-nats (optional feature, path dep on stratumiops) handles NATS event publishing.",

  rationale = [
    {
      claim  = "Optional daemon preserves protocol-not-runtime axiom",
      detail = "Every HTTP call to the daemon has a subprocess fallback in store.nu. daemon-export-safe returns null on error; callers substitute with direct nickel export. A project with daemon.enabled = false works identically — just without caching. The daemon is an optimization layer, never a load-bearing dependency.",
    },
    {
      claim  = "NCL export caching eliminates repeated subprocess forks",
      detail = "Daemon caches nickel export results keyed by (path, mtime, NICKEL_IMPORT_PATH). First call ~100ms (subprocess). Subsequent calls <1ms (DashMap lookup). File watcher via notify (FSEvents on macOS, inotify on Linux) invalidates on any change to watched paths. Periodic full invalidation as safety net.",
    },
    {
      claim  = "Actor registry enables multiactor awareness without coordination overhead",
      detail = "Deterministic tokens (type:hostname:pid) require no UUID generation and are stable across restarts of the same process. Stale sessions are swept by kill -0 check (same-machine actors) or last_seen timeout (CI/remote actors). No heartbeat loop required from actors.",
    },
    {
      claim  = "Notification barrier is fail-open, preserving developer autonomy",
      detail = "The pre-commit hook checks /notifications/pending and blocks only when notifications are pending AND the daemon is reachable. Daemon unavailable = commit allowed (warning printed). This matches the no-enforcement axiom: ontoref cannot enforce coordination, only facilitate it.",
    },
    {
      claim  = "stratum-db and platform-nats as optional peer path deps",
      detail = "Both crates are infrastructure utilities with no domain coupling to stratumiops. Using them as optional path deps lets ontoref-daemon avoid duplicating SurrealDB and NATS connection logic. The `db` and `nats` features are enabled by default but can be disabled for protocol-only deployments.",
    },
  ],

  consequences = {
    positive = [
      "sync scan latency drops from ~2m42s to <30s with daemon caching active",
      "Developers and agents see each other's pending ontology/ADR changes before committing",
      "Pre-commit hook prevents silent drift when multiple actors modify shared protocol files",
      "SurrealDB persistence (optional) enables cross-session impact analysis and audit history",
      "Single daemon process serves multiple projects via X-Ontoref-Project header scoping",
    ],
    negative = [
      "ontoref-daemon has path deps on stratumiops/crates — both repos must be co-located for local builds",
      "Daemon process uses memory (~10-50MB) while running; idle timeout mitigates this",
      "Actor notification barrier adds pre-commit latency for the HTTP round-trip (~5ms daemon reachable)",
      "stratum-db pins SurrealDB v3 — major version changes require coordinated update across both repos",
    ],
  },

  alternatives_considered = [
    {
      option       = "In-process Nickel evaluation via nickel-lang-core library",
      why_rejected = "nickel-lang-core has an unstable Rust API and resolves import paths differently from the CLI. The subprocess approach with caching is simpler, more stable, and already <1ms cached.",
    },
    {
      option       = "Required daemon (always running, no fallback)",
      why_rejected = "Violates the protocol-not-runtime axiom. Consumer projects must function without any ontoref process running. The daemon is an optimization and awareness layer, not infrastructure.",
    },
    {
      option       = "Filesystem-based JSON cache without a daemon process",
      why_rejected = "File-based caching requires lock management, cannot serve concurrent requests from multiple actors, and does not provide file watching or the actor registry. A daemon centralizes these concerns cleanly.",
    },
    {
      option       = "Bundle SurrealDB and NATS clients directly in ontoref, not as path deps",
      why_rejected = "Duplicating stratum-db and platform-nats creates divergence. Both crates are general-purpose infrastructure; ontoref consumers already have stratumiops checked out for other reasons. Path deps preserve the single canonical implementation.",
    },
  ],

  constraints = [
    {
      id       = "daemon-never-required",
      claim    = "No Nushell module or bash script may fail when ontoref-daemon is unavailable",
      scope    = "reflection/modules/, reflection/nulib/, scripts/",
      severity = 'Hard,
      check    = {
        tag          = 'Grep,
        pattern      = "daemon-export-safe|subprocess fallback|nickel export",
        paths        = ["reflection/modules", "reflection/nulib"],
        must_be_empty = false,
      },
      rationale = "Every daemon-export call site must have a subprocess fallback. Daemon down = system works identically, just slower.",
    },
    {
      id       = "daemon-binds-localhost-only",
      claim    = "ontoref-daemon must bind to 127.0.0.1, never to 0.0.0.0 or a public interface",
      scope    = "crates/ontoref-daemon/src/main.rs",
      severity = 'Hard,
      check    = {
        tag          = 'Grep,
        pattern      = "0\\.0\\.0\\.0",
        paths        = ["crates/ontoref-daemon/src/main.rs"],
        must_be_empty = true,
      },
      rationale = "The daemon is local IPC only. Binding to a public interface would expose the NCL export API to the network.",
    },
    {
      id       = "notification-barrier-fail-open",
      claim    = "The pre-commit hook must allow commits when ontoref-daemon is unreachable, printing a warning but not blocking",
      scope    = "scripts/hooks/pre-commit-notifications.sh",
      severity = 'Hard,
      check    = {
        tag          = 'Grep,
        pattern      = "daemon down|unreachable|curl.*fail",
        paths        = ["scripts/hooks/pre-commit-notifications.sh"],
        must_be_empty = false,
      },
      rationale = "A pre-commit hook that blocks on daemon unavailability violates the no-enforcement axiom and the developer autonomy principle. Coordination is facilitated, never enforced.",
    },
    {
      id       = "multi-project-header-scoping",
      claim    = "All daemon HTTP requests from consumer wrappers must include X-Ontoref-Project header or equivalent project scoping",
      scope    = "reflection/modules/store.nu, crates/ontoref-daemon/src/api.rs",
      severity = 'Soft,
      check    = {
        tag          = 'Grep,
        pattern      = "X-Ontoref-Project",
        paths        = ["reflection/modules/store.nu", "crates/ontoref-daemon/src/api.rs"],
        must_be_empty = false,
      },
      rationale = "One daemon process serves multiple projects. Without project scoping, notifications and cache entries from different projects would collide.",
    },
  ],

  related_adrs = ["adr-001-protocol-as-standalone-project"],

  ontology_check = {
    decision_string    = "optional persistent daemon for NCL caching, actor registry, and notification barrier — never required, fail-open design throughout",
    invariants_at_risk = ["protocol-not-runtime", "no-enforcement"],
    verdict            = 'Safe,
  },
}