Protocol + Runtime · v0.1.0

Structure that remembers why

Self-Describing Protocol for
Evolving Systems

Ontology + Reflection + Daemon + MCP — encode what a system IS (invariants, tensions, constraints) and where it IS GOING (state dimensions, transition conditions, membranes) in machine-queryable directed acyclic graphs. Software projects, personal operational systems, agent contexts — same three files, same protocol. First-class web UI (11 pages), MCP server (19 tools), live session sharing. One protocol for developers, agents, CI, and individuals.
Protocol + Runtime. Zero enforcement.

The 7 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/ separates three orthogonal concerns: core.ncl (what IS) · state.ncl (where we ARE vs want to BE) · gate.ncl (when READY to cross a boundary)
reflection/ reads all three and answers self-knowledge queries — an agent understands the project without reading code, only by consulting the declarative graph

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

Decisions Without a Map

Personal and professional decisions made against implicit, unverifiable assumptions
No queryable model of what you never compromise
No structured way to ask: does this opportunity violate who I am?
ontoref as personal operational ontology — same core/state/gate files applied to life, career, and ecosystem dimensions
jpl validate "accept offer" → invariants_at_risk, relevant edges, verdict

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 and declared ADR validators
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 (11 pages), MCP server (29 tools), actor registry, notification store, search engine, SurrealDB persistence. Never a protocol requirement.

ADOPTION LAYER · Per-project

.ontoref/config.ncl · ontoref CLI · 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 — Node carries artifact_paths and adrs, both serde(default)
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): 11 pages — dashboard, graph, search, sessions, notifications, backlog, Q&A, actions, modes, compose, manage/login, manage/logout
Graph node detail panel: artifacts, connections, and ADR validators — each ADR is a clickable link that opens the full record via GET /api/adr/{id}
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

ontoref setup wires up any new or existing project — idempotent scaffold with optional auth key bootstrap.

stratumiops Master orchestration repo

vapora AI agent orchestration

kogral Knowledge graph + MCP

syntaxis Project orchestration

provisioning Declarative IaC

your-project Any codebase

          # Onboard a new project (idempotent; kind: Service by
            default)

          ontoref setup

          ontoref setup --kind
          Library

          ontoref
          setup --gen-keys
          ["admin:dev" "viewer:ci"]
          # bootstrap auth keys once

          # Query the project self-knowledge

          ontoref describe project

          ontoref describe constraints

          ontoref describe impact ontology-node-id

          # ADR lifecycle

          ontoref adr new --title
          "Adopt Nickel for configuration"

          ontoref adr list --status Accepted

Daemon & MCP — Runtime Intelligence Layer

ontoref-daemon is an optional persistent process. It caches NCL exports, serves 11 UI pages, exposes 29 MCP tools, maintains an actor registry, stores notifications, indexes everything for search, and optionally persists to SurrealDB. The annotated API surface is discoverable at GET /api/catalog (populated at link time via #[onto_api] proc-macro). Auth is opt-in: all surfaces (CLI, UI, MCP) exchange a project key for a UUID v4 session token via POST /sessions; CLI injects ONTOREF_TOKEN as Bearer automatically. It never changes the protocol — it accelerates and shares access to it. Configured via ~/.config/ontoref/config.ncl (Nickel, type-checked); edit interactively with ontoref config-edit. Started via NCL pipe bootstrap: ontoref-daemon-boot.

The Web UI — 12 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 Cytoscape.js ontology graph — nodes colored by pole (Yang=orange, Yin=blue, Spiral=purple), clickable detail panel with artifacts, connections, and ADR links that open the full record in a modal

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

/sessions Sessions live actor registry — actor type, mode, last_seen; auth sessions (id, role, key_label, expires) for authed deployments

/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

          # Configure and start the daemon (optional — protocol works without
            it)

          ontoref config-edit
            # browser form → ~/.config/ontoref/config.ncl

          ontoref-daemon-boot
            # NCL pipe bootstrap: nickel export config.ncl | daemon
            --config-stdin

          ontoref-daemon-boot --dry-run
            # preview composed JSON without starting

          # With SOPS-encrypted secrets merged at boot

          ontoref-daemon-boot --sops
          secrets.enc.json

          # 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 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 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 Cytoscape.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 · 12 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 ontoref setup. 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