82a358f18d
ontoref-derive: #[onto_mcp_tool] attribute macro registers MCP tool unit-structs in
the catalog at link time via inventory::submit!; annotated item is emitted unchanged,
ToolBase/AsyncTool impls stay on the struct. All 34 tools migrated from manual wiring
(net +5: ontoref_list_projects, ontoref_search, ontoref_describe,
ontoref_list_ontology_extensions, ontoref_get_ontology_extension).
validate modes (ADR-018): reads level_hierarchy from workflow.ncl and checks every
.ncl mode for level declared, strategy declared, delegate chain coherent, compose
extends valid. mode resolve <id> shows which hierarchy level handles a mode and why.
--self-test generates synthetic fixtures in a temp dir for CI smoke-testing.
validate run-cargo: two-step Cargo.toml resolution — workspace layout first
(crates/<check.crate>/Cargo.toml), single-crate fallback by package name or repo
basename. Lets the same ADR constraint shape apply to workspace and single-crate repos.
ontology/schemas/manifest.ncl: registry_topology_type contract — multi-registry
coordination, push targets, participant scopes, per-namespace capability.
reflection/requirements/base.ncl: oras ≥1.2.0, cosign ≥2.0.0, sops ≥3.9.0, age
≥1.1.0, restic declared as Hard/Soft requirements with version_min, check_cmd, and
install_hint (ADR-017 toolchain surface).
ADR-019: per-file recipient routing for tenant isolation without multi-vault. Schema
additions: sops.recipient_groups + sops.recipient_rules in ontoref-project.ncl.
secrets-bootstrap generates .sops.yaml from project.ncl in declarative mode. Three
new secrets-audit checks: recipient-routing-coherent, recipient-routing-coverage,
no-multi-vault. Adoption templates: single-team/, multi-tenant/, agent-first/.
Integration templates: domain-producer/, mode-producer/, mode-consumer/.
UI: project_picker surfaces registry badge (⟳ participant) and vault badge
(⛁ vault_id · N, green=declarative / amber=legacy) per project card. Expanded panel
adds collapsible Registry section with namespace, endpoint, and push/pull capability.
manage.html gains Runtime Services card — MCP and GraphQL toggleable without restart
via HTMX POST /ui/manage/services/{service}/toggle.
describe.nu: capabilities JSON includes registry_topology and vault_state per project.
sync.nu: drift check extended to detect //! absence on newly registered crates.
qa.ncl: six entries — credential-vault-best-practice (layered data-flow diagram),
credential-vault-templates (paths A/B/C), credential-vault-troubleshooting (15 named
errors), integration-what-and-why (ADR-042 OCI federation), integration-how-to-implement,
integration-troubleshooting.
on+re: core.ncl + manifest.ncl updated to reflect OCI, MCP, and mode-hierarchy nodes.
Deleted stale presentation assets (2026-02 slides + voice notes).
6.8 KiB
| id | title | slug | subtitle | excerpt | author | date | published | featured | category | tags | read_time | sort_order | css_class | category_description | category_published | |||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| one-protocol-three-subjects | One Protocol, Three Subjects | one-protocol-three-subjects | The same question applies to your project, your infrastructure, and yourself | Ontoref started as a protocol for software project self-knowledge. The same architecture — ontological DAG for what IS, reflection DAG for what BECOMES — applies without modification to infrastructure environments and to individuals. The subject changes. The question is identical: what are you, what tensions define you, where are you versus where you intend to be? | Jesús Pérez | 2026-05-10 | false | false | ontoref |
|
7 min read | 3 | category-ontoref | Ontoref — protocol and tooling for structured self-knowledge in software projects | true |
One Protocol, Three Subjects
The question ontoref asks of a software project is precise: What are you? What principles define you? What tensions are you actively managing? What decisions have you made with lasting consequences? Where are you versus where you intend to be?
This turns out to be the same question that infrastructure environments need answered. And individuals.
The subject changes. The question is identical.
What All Three Have in Common
Any system with identity and intent shares the same structural problem:
- Identity — what it is, what principles define it
- Active tensions — trade-offs that don't resolve, they're managed
- Durable decisions — choices with lasting consequences that constrain the future
- Observable state — where it is versus where it intends to be
- Drift — the distance between intention and reality, growing silently with time
- Operations — the actions that reduce that drift
Software projects have all of these. So do infrastructure environments. So do people.
And they all benefit from the same architecture: an ontological layer that captures what IS, and a reflection layer that captures what BECOMES and operates to keep those two aligned.
Infrastructure
Infrastructure already uses DAGs — Terraform, Pulumi, Ansible. All of them describe how the system is provisioned. None of them capture why it exists as it does.
The why is where knowledge lives:
Service "auth" --tension--> Principle "stateless"
reason: needs session state, but the principle forbids it
Constraint "zero-downtime" --enforces--> Practice "blue-green"
reason: ADR-infra-003, after the 2025 deploy incident
This information is not in the Terraform plan. It's in the memory of the engineer who was there, in a Slack thread from eight months ago, or nowhere at all. When that engineer leaves, the infrastructure loses its own history — it knows what it is, not why.
Infrastructure ontoref captures the architectural decisions of the infrastructure itself, with the same ADR formalism as software projects. It tracks state dimensions — which environments are stable, which are in active migration, what's blocked and why. The FSM doesn't track deployment status; it tracks epistemic status — how well the infrastructure understands itself.
Federation via NATS means each environment (dev, staging, prod) describes itself and can be queried from the projects that depend on it. Sovereign GitOps: the infrastructure knowledge lives with the infrastructure code, not in a vendor's database.
Personal
This is the most radical application. But it follows directly from the same logic.
A person with values, roles, and long-term intentions faces exactly the same structural problem as a software project:
Value "depth" --tension--> Role "parent"
reason: time is finite and both demand it fully
Decision "left company X" --constraint--> Future career choices
with the same architectural weight as ADR-001
State "learning Rust" --blocker--> "contribute to ontoref-core"
a personal FSM dimension, not a task list item
The knowledge graph here is not a productivity system. It's not a second brain of notes. It's a graph of commitments — typed, provenanced, with active tensions named rather than suppressed.
The drift problem is identical: who you are becoming versus who you intended to be. Reflection modes for a person might be weekly reviews, annual state assessments, or triggered reviews when a major decision introduces new constraints. The operational loop is the same — observe, detect drift, execute, record.
The Same Stack, Different Subject
All three domains run on the same infrastructure:
Sovereign storage: Knowledge lives alongside its subject — in the project repo, in the infrastructure code, in a personal vault. No vendor holds it. No platform dependency. NCL files versioned with the same discipline as code.
Multi-surface access:
| Surface | Consumer |
|---|---|
| CLI (Nushell) | Developer, scripts, CI |
| UI (axum) | Visual review, onboarding |
| MCP | AI agents |
| GraphQL | External tools, dashboards |
VCS alignment: jj's model — where the working copy is always a commit — aligns naturally with ontoref's approach to continuous state capture. There is no "dirty state"; every moment is capturable. Radicle as transport makes the whole stack sovereign and P2P — code collaboration without a central platform.
Federation: Projects querying each other's knowledge graphs without a central broker. Infrastructure environments exposing their self-knowledge to the projects that depend on them. Individuals whose personal knowledge graph informs their contributions to the projects they work on.
Why Scale Matters
The smallest unit that can adopt ontoref is a person. One developer, one project, one infrastructure environment. No team required. No budget conversation.
The largest unit is an ecosystem of federated, self-describing projects that can query each other's knowledge without any of them being the authoritative central source.
That range — individual to ecosystem — is possible because the protocol is the same at every scale. The ontological DAG and the reflection DAG don't change shape based on the size of the subject. They change in density and depth, not in structure.
The organizations that Talisman argues should invest in knowledge infrastructure are trying to build this top-down, with dedicated teams and multi-year programs. Ontoref makes it available bottom-up — starting with a single project, a single environment, a single person, each describing themselves in the same language.
Ontoref is open source. The protocol specification, Nushell automation, and Rust crates are at github.com/jesusperezlorenzo/ontoref.