Architecture
Protocol + Runtime · v0.1.0
Ontoref — Self-Describing Ontology and Reflection Protocol

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 (12 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

01

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
02

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
03

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
04

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
05

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
06

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
07

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 (12 pages), MCP server (19 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): 12 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.

stratumiopsMaster orchestration repo
vaporaAI agent orchestration
kogralKnowledge graph + MCP
syntaxisProject orchestration
provisioningDeclarative IaC
your-projectAny codebase
# Onboard a new project (idempotent; kind: Service by default)
ontorefsetup
ontorefsetup --kind Library
ontorefsetup --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 12 UI pages, exposes 19 MCP tools, maintains an actor registry, stores notifications, indexes everything for search, and optionally persists to SurrealDB. 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}/
DashboardGraphSearchSessionsNotifBacklogQ&AActionsModesCompose
/Dashboardproject overview, actor count, cache stats, notification count, backlog summary
/graphGraphCytoscape.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
/searchSearchfull-text search across nodes, ADRs, reflection modes — returns kind/id/title/snippet/score
/sessionsSessionslive actor registry — actor type, mode, last_seen; auth sessions (id, role, key_label, expires) for authed deployments
/notificationsNotificationsnotification feed — pre_commit / drift / ontology_drift; ack/dismiss; emit custom; action buttons
/backlogBacklogitems with priority (Critical/High/Medium/Low) and status (Open/InProgress/Done/Cancelled); add/update
/qaQ&Aserver-hydrated from reflection/qa.ncl; add/edit/delete; persisted as typed NCL
/actionsActionsquick actions catalog from .ontoref/config.ncl; execute via POST /actions/run
/modesModesreflection mode list from reflection/modes/ — name, description, DAG contract
/composeComposeagent 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 2021NickelNushell 0.111+axumTera TemplatesDashMapnotifyMCP ProtocolD3.jsServer-Sent EventsSurrealDBNATS JetStreamSHA-256 SealsDAG ContractsshellcheckPOSIX Advisory Locks

Protocol Metrics

3 Rust Cratesontology · reflection · daemon
19 MCP ToolsAI agent integration · stdio + HTTP
1 Web UI · 12 Pagesdashboard · graph · search · sessions · notifications · backlog · Q&A · actions · modes · compose
6 Protocol LayersDeclarative → Adoption
1 Search Enginenodes · ADRs · reflection modes
16 Nu ModulesStructured data pipelines
8+ Reflection ModesDAG workflow contracts
3 Actor Typesdeveloper / agent / CI
0 EnforcementVoluntary 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