d59644b96f
The full scope across this batch: POST /sessions key→token exchange, SessionStore dual-index with revoke_by_id, CLI Bearer injection (ONTOREF_TOKEN), ontoref setup --gen-keys, install scripts, daemon config form roundtrip, ADR-004/005, on+re self-description update (fully-self-described), and landing page refresh.
153 lines
7.0 KiB
Markdown
153 lines
7.0 KiB
Markdown
<p align="center">
|
|
<img src="assets/ontoref-logo.svg" alt="ontoref" width="320" />
|
|
</p>
|
|
|
|
<br>
|
|
|
|
**ontoref** is a protocol specification and tooling layer for structured self-knowledge in
|
|
software projects. It provides schemas, Nushell automation, and Rust crates so that projects
|
|
can describe what they are, record architectural decisions, track operational state, and
|
|
execute formalized procedures — all as typed, queryable artifacts.
|
|
|
|
---
|
|
|
|
## Axioms
|
|
|
|
| Axiom | Meaning |
|
|
| --- | --- |
|
|
| **Protocol, Not Runtime** | Never a runtime dependency. Projects adopt the protocol; ontoref provides the schemas and modules to do so. |
|
|
| **Self-Describing** | Consumes its own protocol: `.ontology/`, `adrs/`, `reflection/` in this repo ARE ontoref running against itself. |
|
|
| **No Enforcement** | ontoref defines contracts. There is no enforcement mechanism. Coherence is voluntary and emerges from justified adoption. |
|
|
| **DAG-Formalized Knowledge** | Concepts, tensions, decisions, state — encoded as DAGs. Enables transversal queries and impact analysis. |
|
|
|
|
## Layers
|
|
|
|
```text
|
|
ontology/ Protocol specification — Nickel schemas for nodes, edges, ADRs, state, gates
|
|
adrs/ Architecture Decision Records — typed NCL with constraints and ontology checks
|
|
reflection/ Operational tooling — Nushell modules, DAG modes, forms, and schemas
|
|
crates/ Rust implementation — typed struct loaders and mode executors
|
|
.ontology/ Self-description — ontoref's own ontology, state, gate, and manifest
|
|
```
|
|
|
|
## Crates
|
|
|
|
| Crate | Purpose |
|
|
| --- | --- |
|
|
| `ontoref-ontology` | `.ontology/` NCL → typed Rust structs: Node, Edge, Dimension, Gate, Membrane. Graph traversal, invariant queries. Zero deps. |
|
|
| `ontoref-reflection` | NCL DAG contract executor: ADR lifecycle, step dep resolution, config seal. `stratum-graph` + `stratum-state` required. |
|
|
| `ontoref-daemon` | HTTP UI (10 pages), actor registry, notification barrier, MCP (19 tools), search engine, SurrealDB, NCL export cache. |
|
|
|
|
`ontoref-daemon` caches `nickel export` results (keyed by path + mtime), reducing full sync
|
|
scans from ~2m42s to <30s. The daemon is always optional — every module falls back to direct
|
|
subprocess when unavailable.
|
|
|
|
### Daemon Capabilities
|
|
|
|
**Unified Auth Model** — all surfaces (CLI, UI, MCP) exchange a key for a UUID v4 session token
|
|
via `POST /sessions`. Token lifetime: 30 days, O(1) lookup. Project keys carry `role`
|
|
(admin|viewer) and `label` for audit trail. Daemon-level admin via `ONTOREF_ADMIN_TOKEN_FILE`.
|
|
`GET /sessions` and `DELETE /sessions/{id}` for session visibility and revocation. Key rotation
|
|
invalidates all sessions for the rotated project. CLI injects `ONTOREF_TOKEN` as Bearer
|
|
automatically.
|
|
|
|
**Q&A Knowledge Store** — accumulated Q&A entries persist to `reflection/qa.ncl` (typed NCL,
|
|
git-versioned). Not localStorage. Any actor — developer, agent, CI — reads the same store.
|
|
|
|
**MCP Server** — 19 tools over stdio and streamable-HTTP. Categories: nodes, ADRs, modes,
|
|
backlog, Q&A, sessions, search, notifications. Representative subset:
|
|
|
|
| Tool | What it does |
|
|
| --- | --- |
|
|
| `ontoref_qa_list` | List Q&A entries with optional filter |
|
|
| `ontoref_qa_add` | Append a new Q&A entry to `reflection/qa.ncl` |
|
|
| `ontoref_action_list` | List all quick actions from `.ontoref/config.ncl` |
|
|
| `ontoref_action_add` | Create a reflection mode + register it as a quick action |
|
|
| `ontoref_backlog_list` | List backlog items |
|
|
| `ontoref_backlog_add` | Add a backlog item |
|
|
| `ontoref_describe` | Describe project ontology and constraints |
|
|
| `ontoref_sync_scan` | Scan for ontology drift |
|
|
|
|
**Passive Drift Observation** — background file watcher that detects divergence between Yang
|
|
code artifacts and Yin ontology. Watches `crates/`, `.ontology/`, `adrs/`, `reflection/modes/`.
|
|
After a 15s debounce runs `sync scan + sync diff`; emits an `ontology_drift` notification when
|
|
MISSING/STALE/DRIFT/BROKEN items are found. Never applies changes — `apply` is always deliberate.
|
|
|
|
**Quick Actions** — runnable shortcuts over reflection modes, configured as `quick_actions` in
|
|
`.ontoref/config.ncl`. Accessible from HTTP (`/actions`), CLI (`ontoref`), and MCP
|
|
(`ontoref_action_list/add`).
|
|
|
|
## Install
|
|
|
|
```sh
|
|
just install-daemon # build + install binary, bootstrapper, CLI, UI assets, config skeleton
|
|
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
|
|
```
|
|
|
|
Installed layout (`~/.local/bin/`):
|
|
|
|
| Binary | Role |
|
|
| --- | --- |
|
|
| `ontoref` | Global CLI dispatcher — all reflection modes, ADR lifecycle, daemon control |
|
|
| `ontoref-daemon` | Bootstrapper (public entrypoint) — validates config via Nickel, pipes JSON to binary |
|
|
| `ontoref-daemon.bin` | Compiled Rust binary — never called directly |
|
|
|
|
Global config at `~/.config/ontoref/config.ncl` (type-checked Nickel). Global NATS stream topology at
|
|
`~/.config/ontoref/streams.json`. Project-local topology override via `nats/streams.json` +
|
|
`nats_events.streams_config` in `.ontoref/config.ncl`.
|
|
|
|
## Onboarding a project
|
|
|
|
```sh
|
|
cd /path/to/my-project
|
|
ontoref setup # idempotent; kind: Service by default
|
|
ontoref setup --kind Library # Library | DevWorkspace | PublishedCrate | AgentResource | Mixed
|
|
ontoref setup --parent /path/to/fw # implementation child: adds framework layer + browse mode
|
|
ontoref setup --gen-keys ["admin:dev" "viewer:ci"] # bootstrap auth keys (no-op if keys already exist)
|
|
```
|
|
|
|
`ontoref setup` creates `.ontoref/project.ncl`, `.ontoref/config.ncl` (with logo auto-detection),
|
|
`.ontology/` scaffold, `adrs/`, `reflection/modes/`, `backlog.ncl`, `qa.ncl`, git hooks, and
|
|
registers the project in `~/.config/ontoref/projects.ncl`.
|
|
|
|
For existing projects that predate `setup`, the adoption mode is still available:
|
|
|
|
```sh
|
|
ontoref --actor developer adopt_ontoref
|
|
```
|
|
|
|
`ONTOREF_PROJECT_ROOT` is set by the consumer wrapper — one ontoref checkout serves multiple projects.
|
|
|
|
## Prerequisites
|
|
|
|
- [Nushell](https://www.nushell.sh/) >= 0.110.0
|
|
- [Nickel](https://nickel-lang.org/) (for schema evaluation)
|
|
- Rust toolchain (for building crates)
|
|
- [Just](https://just.systems/) (for CI recipes)
|
|
|
|
To build `ontoref-daemon` and `ontoref-reflection` with NATS/SurrealDB support, the
|
|
stratumiops repo must be checked out at `../../../stratumiops`. Without it, build without
|
|
default features:
|
|
|
|
```sh
|
|
cargo build -p ontoref-daemon --no-default-features
|
|
cargo build -p ontoref-ontology # always standalone
|
|
```
|
|
|
|
## Development
|
|
|
|
```sh
|
|
cargo check-all # check all targets + features
|
|
cargo test-all # run full test suite
|
|
just ci-lint # clippy + TOML + Nickel + Markdown
|
|
just ci-full # all CI checks
|
|
nu --ide-check 50 reflection/modules/<file>.nu # validate a Nushell module
|
|
./ontoref --actor developer <mode> # run a reflection mode
|
|
```
|
|
|
|
## License
|
|
|
|
MIT OR Apache-2.0
|