Protocol + Runtime · v0.1.0

Structure that remembers why.

Self-Describing Protocol for
Evolving Codebases

Ontology + Reflection + Daemon + MCP — encode what your codebase IS (invariants, tensions, constraints) and what it DOES (operational modes, actor flows, config seals) in machine-queryable directed acyclic graphs. First-class web UI (10 pages), MCP server (19 tools), and live session sharing for AI agents. One protocol for developers, agents, and CI.
Protocol + Runtime. Zero enforcement.

The 6 Problems It Solves

Decisions Without Memory

Architectural choices made in chat, forgotten after rotation
No machine-queryable source of why something exists
ADRs as typed Nickel: invariants, constraints, supersession chain
Hard constraints enforced at every operation

Invisible Configuration Drift

Configs change outside any review cycle
No audit trail linking change to PR or ADR
Rollback requires manual file archaeology
Sealed profiles: sha256 hash, full history, verified rollback

Agents Without Context

LLMs start each session with zero project knowledge
Same mistakes, same questions, no accumulation across operations
Actor registry tracks each session token, type, current mode, last seen — persisted to disk
MCP tools give agents direct DAG read/write: nodes, ADRs, backlog, Q&A
Composed tasks shared via daemon — multiple actors see the same operational context live

Scattered Project Knowledge

Guidelines in wikis, patterns in docs, decisions in Slack
No single source queryable by humans, agents, and CI equally
.ontology/ as DAG: nodes, edges, invariants, tensions, gates
Same graph serves developer context, agent initialization, CI validation

Protocol Fragmentation

Each project re-invents its own conventions
No shared contract for how operations are defined and executed
Reflection modes: typed DAG contracts for any workflow
One protocol adopted per-project, without enforcing uniformity

Knowledge Lost Between Sessions

Q&A answered in one session forgotten by the next
Agent re-asks questions already answered in previous sessions
Q&A Knowledge Store: typed NCL, git-versioned, persists across browser resets
Notification barrier surfaces drift to agents proactively — pre_commit, drift, ontology_drift signals block until acknowledged

Ontology & Reflection — Yin and Yang

Yin — The Ontology Layer

What must be true

Invariants — axioms that cannot change without a new ADR
Tensions — structural conflicts the project navigates, never resolves
Practices — confirmed patterns with artifact paths to real files
Gates — membranes controlling readiness thresholds
Dimensions — current vs desired state, with transition conditions
Q&A Knowledge Store — accumulated Q&A persisted to NCL, git-versioned, queryable by any actor

Yang — The Reflection Layer

How things move and change

Modes — typed DAG workflow contracts (preconditions, steps, postconditions)
Forms — parameter collection driving modes
ADR lifecycle — Proposed → Accepted → Superseded, with constraint history
Actors — developer / agent / CI, same protocol, different capabilities
Config seals — sha256-sealed profiles, drift detection, rollback
Quick Actions — runnable shortcuts over modes; configured in .ontoref/config.ncl
Passive Drift Observer — watches code changes, emits ontology_drift notifications with missing/stale/drift/broken counts

Ontology without Reflection = correct but static. Perfect invariants with no operations = dead documentation.
Reflection without Ontology = fluid but unanchored. Workflows that forget what they protect.

The protocol lives in coexistence.

DECLARATIVE LAYER · Nickel

.ontology/ · adrs/ · reflection/schemas/

Strong types, contracts, enums. Fails at definition time, not at runtime.

OPERATIONAL LAYER · Nushell

adr · register · config · backlog · forms · describe

Typed pipelines over structured data. No text streams.

ENTRY POINT · Bash → Nu

ontoref · actor detection · advisory locking · ONTOREF_IMPORT_PATH

Single entry point per project. Detects actor (developer/agent/CI), acquires lock, dispatches to correct Nu module.

KNOWLEDGE GRAPH · .ontology/

nodes · invariants · tensions · gates · dimensions · states

The project knows what it knows. Actor-agnostic. Machine-queryable via nickel export.

RUNTIME LAYER · Rust + axum

ontoref-daemon · ontoref-ontology · ontoref-reflection · search engine · notification barrier · SurrealDB (optional)

Optional persistent daemon. NCL export cache, HTTP UI (10 pages), MCP server (19 tools), actor registry, notification store, search engine, SurrealDB persistence. Never a protocol requirement.

ADOPTION LAYER · Per-project

.ontoref/config.ncl · scripts/ontoref · adopt_ontoref mode

Each project maintains its own .ontology/ data. Ontoref provides the schemas, modules, and migration scripts. Zero lock-in.

Crates & Tooling

🧩

ontoref-ontology

Load and query .ontology/ NCL files as typed Rust structs
Node, Edge, Dimension, Gate, Membrane types
Graph traversal: callers, callees, impact queries
Invariant extraction and constraint validation
Zero stratumiops dependencies — minimal adoption surface (ADR-001)

🔄

ontoref-reflection

Execute reflection modes as typed NCL DAG contracts
Step execution with dependency resolution
ADR lifecycle: Proposed → Accepted → Superseded
Config seal and rollback operations
stratum-graph + stratum-state required; platform-nats feature-gated

📜

Nushell Modules

store.nu — SurrealDB-backed cache with NCL export
sync.nu — ontology code synchronization
describe.nu — actor-aware project self-knowledge
coder.nu — structured session records
16 modules total — one per operational domain

⚙️

Nickel Schemas

Core ontology types: Node, Edge, Pole, AbstractionLevel
State machine types: Dimension, Transition, Gate, Membrane
ADR schema: Constraint, Severity, Status, supersession
Reflection schema: Mode, Step, OnError, Dependency

🖥️

ontoref-daemon · HTTP & UI

HTTP UI (axum + Tera): 10 pages — dashboard, D3 graph, search, sessions, notifications, backlog, Q&A, actions, modes, compose
Actor registry (DashMap): token, type (developer / agent / CI), registered_at, last_seen, current_mode — serializable snapshot
Notification barrier: pre_commit · drift · ontology_drift — pre-commit hook polls & blocks on ack
Compose / live sharing: mode forms rendered interactively, ./ontoref dispatched server-side, shared across actors
File watcher (notify): passive drift observer, no polling

⚡

ontoref-daemon · MCP & Data

MCP server: stdio + streamable-HTTP, 19 tools — nodes, ADRs, modes, backlog, Q&A, sessions, search, notifications
Search engine: full-text across nodes / ADRs / reflection modes — returns kind · id · title · snippet · score
SurrealDB persistence (optional --db): actor sessions, seeded ontology tables, search index, notification history — fail-open
NCL export cache: avoids repeated nickel export on unchanged files
db + nats feature flags — builds standalone with --no-default-features

Adopt in Any Project

The adopt_ontoref mode wires up any existing project in one command.

stratumiops Master orchestration repo

vapora AI agent orchestration

kogral Knowledge graph + MCP

syntaxis Project orchestration

provisioning Declarative IaC

your-project Any codebase

          # Onboard an existing project

          ./ontoref adopt --project-dir /path/to/my-project --project-name my-project

          # Query the project self-knowledge

          ./scripts/ontoref describe project

          ./scripts/ontoref describe constraints

          ./scripts/ontoref describe impact ontology-node-id

          # ADR lifecycle

          ./scripts/ontoref adr new --title "Adopt Nickel for configuration"

          ./scripts/ontoref adr list --status Accepted

Daemon & MCP — Runtime Intelligence Layer

ontoref-daemon is an optional persistent process. It caches NCL exports, serves 10 UI pages, exposes 19 MCP tools, maintains an actor registry, stores notifications, indexes everything for search, and optionally persists to SurrealDB. It never changes the protocol — it accelerates and shares access to it.

The Web UI — 10 Pages

localhost:7421/ui/{slug}/

Dashboard Graph Search Sessions Notif Backlog Q&A Actions Modes Compose

/ Dashboard project overview, actor count, cache stats, notification count, backlog summary

/graph Graph D3 force-directed ontology graph — nodes colored by pole (Yang=orange, Yin=blue, Spiral=purple), clickable with detail panel, edge labels

/search Search full-text search across nodes, ADRs, reflection modes — returns kind/id/title/snippet/score

/sessions Sessions live actor registry — token, type (developer/agent/CI), registered_at, last_seen, current mode

/notifications Notifications notification feed — pre_commit / drift / ontology_drift; ack/dismiss; emit custom; action buttons

/backlog Backlog items with priority (Critical/High/Medium/Low) and status (Open/InProgress/Done/Cancelled); add/update

/qa Q&A server-hydrated from reflection/qa.ncl; add/edit/delete; persisted as typed NCL

/actions Actions quick actions catalog from .ontoref/config.ncl; execute via POST /actions/run

/modes Modes reflection mode list from reflection/modes/ — name, description, DAG contract

/compose Compose agent task composer — renders mode forms interactively; POST /compose/send dispatches to ./ontoref; live sharing for AI actors

The MCP Server — 19 Tools

Tool	Description
ontoref_help	List available tools and usage
ontoref_list_projects	Enumerate all registered projects
ontoref_set_project	Set session default project context
ontoref_project_status	Full project dashboard — health, drift, actors
ontoref_describe	Architecture overview and self-description
ontoref_search	Free-text search across nodes, ADRs, modes
ontoref_get	Fetch ontology node by id
ontoref_get_node	Full ontology node with edges and constraints
ontoref_list_adrs	List ADRs filtered by status
ontoref_get_adr	Full ADR content with constraints
ontoref_list_modes	List all reflection modes
ontoref_get_mode	Mode DAG contract — steps, preconditions, postconditions
ontoref_get_backlog	Backlog items filtered by status
ontoref_backlog	Add or update_status on a backlog item
ontoref_constraints	All hard + soft architectural constraints
ontoref_qa_list	List Q&A knowledge store with optional filter
ontoref_qa_add	Persist new Q&A entry to reflection/qa.ncl
ontoref_action_list	Quick actions catalog from .ontoref/config.ncl
ontoref_action_add	Create reflection mode + register as quick action

SurrealDB Persistence — Optional

Enabled with --db feature flag and --db-url ws://...
Connects via WebSocket at startup — 5s timeout, fail-open (daemon runs without it)
Seeds ontology tables from local NCL files on startup and on file changes
Persists: actor sessions, seeded ontology tables, search index, notification history
Without --db: DashMap-backed in-memory, process-lifetime only
Namespace configurable via --db-namespace; credentials via --db-username/--db-password

Notification Barrier

pre_commit — pre-commit hook polls GET /notifications/pending?token=X&project=Y; blocks git commit until all acked
drift — schema drift detected between codebase and ontology
ontology_drift — emitted by passive observer with missing/stale/drift/broken counts after 15s debounce
Fail-open: if daemon is unreachable, pre-commit hook passes — commits are never blocked by daemon downtime
Ack via UI or POST /notifications/ack; custom notifications via POST /{slug}/notifications/emit
Action buttons in notifications can link to any dashboard page

          # Start the daemon (optional — protocol works without it)

          cargo run -p ontoref-daemon -- --config .ontoref/config.ncl

          # With SurrealDB persistence

          cargo run -p ontoref-daemon -- --db-url ws://localhost:8000 --db-namespace ontoref

          # Connect Claude Code via MCP (add to .claude/mcp.json)

          {

            "mcpServers": {

              "ontoref": { "type": "http", "url": "http://localhost:7421/mcp" }

            }

          }

          # Search across ontology nodes, ADRs, and reflection modes

          ontoref_search({ q: "notification drift", project: "my-project" })

          # Persist a Q&A entry (written to reflection/qa.ncl, git-versioned)

          ontoref_qa_add({

            question: "Why does ontoref-ontology have zero stratumiops deps?",

            answer: "ADR-001: minimal adoption surface. Ontology crate must build standalone.",

            tags: ["adr-001", "architecture"]

          })

          # Check live actor sessions

          curl http://localhost:7421/actors

          # {"sessions": [{"token": "abc123", "actor_type": "agent", "current_mode": "describe", ...}]}

The UI in Action · Graph View

Force-directed D3 graph of the live ontology. Nodes are typed (Axiom · Tension · Practice) and polarized (Yang · Yin · Spiral). Click any node to open its detail panel — artifacts, connections, NCL source.

Ontoref Graph View — force-directed D3 ontology graph, dark mode

Yang · Axiom

Yin · Tension

Spiral · Practice

Filter buttons · Edge labels · Node detail panel

Technology Stack

Rust Edition 2021 Nickel Nushell 0.111+ axum Tera Templates DashMap notify MCP Protocol D3.js Server-Sent Events SurrealDB NATS JetStream SHA-256 Seals DAG Contracts shellcheck POSIX Advisory Locks

Protocol Metrics

3 Rust Crates ontology · reflection · daemon

19 MCP Tools AI agent integration · stdio + HTTP

1 Web UI · 10 Pages dashboard · graph · search · sessions · notifications · backlog · Q&A · actions · modes · compose

6 Protocol Layers Declarative → Adoption

1 Search Engine nodes · ADRs · reflection modes

16 Nu Modules Structured data pipelines

8+ Reflection Modes DAG workflow contracts

3 Actor Types developer / agent / CI

0 Enforcement Voluntary adoption

Structure That Remembers Why.

Start with adopt_ontoref. Your project gains machine-queryable invariants, living ADRs, actor-aware operational modes, and a daemon that shares context across every actor in real time.

Explore the Protocol