085607130a
feat: API catalog surface, protocol v2 tooling, MCP expansion, on+re update
## Summary
Session 2026-03-23. Closes the loop between handler code and discoverability
across all three surfaces (browser, CLI, MCP agent) via compile-time inventory
registration. Adds protocol v2 update tooling, extends MCP from 21 to 29 tools,
and brings the self-description up to date.
## API Catalog Surface (#[onto_api] proc-macro)
- crates/ontoref-derive: new proc-macro crate; `#[onto_api(method, path,
description, auth, actors, params, tags)]` emits `inventory::submit!(ApiRouteEntry{...})`
at link time
- crates/ontoref-daemon/src/api_catalog.rs: `catalog()` — pure fn over
`inventory::iter::<ApiRouteEntry>()`, zero runtime allocation
- GET /api/catalog: returns full annotated HTTP surface as JSON
- templates/pages/api_catalog.html: new page with client-side filtering by
method, auth, path/description; detail panel per route (params table,
feature flag); linked from dashboard card and nav
- UI nav: "API" link (</> icon) added to mobile dropdown and desktop bar
- inventory = "0.3" added to workspace.dependencies (MIT, zero transitive deps)
## Protocol Update Mode
- reflection/modes/update_ontoref.ncl: 9-step DAG (5 detect parallel, 2 update
idempotent, 2 validate, 1 report) — brings any project from protocol v1 to v2
by adding manifest.ncl and connections.ncl if absent, scanning ADRs for
deprecated check_hint, validating with nickel export
- reflection/templates/update-ontology-prompt.md: 8-phase reusable prompt for
agent-driven ontology enrichment (infrastructure → audit → core.ncl →
state.ncl → manifest.ncl → connections.ncl → ADR migration → validation)
## CLI — describe group extensions
- reflection/bin/ontoref.nu: `describe diff [--fmt] [--file]` and
`describe api [--actor] [--tag] [--auth] [--fmt]` registered as canonical
subcommands with log-action; aliases `df` and `da` added; QUICK REFERENCE
and ALIASES sections updated
## MCP — two new tools (21 → 29 total)
- ontoref_api_catalog: filters catalog() output by actor/tag/auth; returns
{ routes, total } — no HTTP roundtrip, calls inventory directly
- ontoref_file_versions: reads ProjectContext.file_versions DashMap per slug;
returns BTreeMap<filename, u64> reload counters
- insert_mcp_ctx: audited and updated from 15 to 28 entries in 6 groups
- HelpTool JSON: 8 new entries (validate_adrs, validate, impact, guides,
bookmark_list, bookmark_add, api_catalog, file_versions)
- ServerHandler::get_info instructions updated to mention new tools
## Web UI — dashboard additions
- Dashboard: "API Catalog" card (9th); "Ontology File Versions" section showing
per-file reload counters from file_versions DashMap
- dashboard_mp: builds BTreeMap<String, u64> from ctx.file_versions and injects
into Tera context
## on+re update
- .ontology/core.ncl: describe-query-layer and adopt-ontoref-tooling descriptions
updated; ontoref-daemon updated ("11 pages", "29 tools", API catalog,
per-file versioning, #[onto_api]); new node api-catalog-surface (Yang/Practice)
with 3 edges; artifact_paths extended across 3 nodes
- .ontology/state.ncl: protocol-maturity blocker updated (protocol v2 complete);
self-description-coverage catalyst updated with session 2026-03-23 additions
- ADR-007: "API Surface Discoverability via #[onto_api] Proc-Macro" — Accepted
## Documentation
- README.md: crates table updated (11 pages, 29 MCP tools, ontoref-derive row);
MCP representative table expanded; API Catalog, Semantic Diff, Per-File
Versioning paragraphs added; update_ontoref onboarding section added
- CHANGELOG.md: [Unreleased] section with 4 change groups
- assets/web/src/index.html: tool counts 19→29 (EN+ES), page counts 12→11
(EN+ES), daemon description paragraph updated with API catalog + #[onto_api]
134 lines
6.6 KiB
Plaintext
134 lines
6.6 KiB
Plaintext
let d = import "../ontology/defaults/state.ncl" in
|
||
|
||
{
|
||
dimensions = [
|
||
|
||
d.make_dimension {
|
||
id = "protocol-maturity",
|
||
name = "Protocol Maturity",
|
||
description = "Completeness of the ontoref protocol specification — schemas, ADRs, modes, Rust crates, daemon, and adoption tooling.",
|
||
current_state = "adoption-tooling-complete",
|
||
desired_state = "protocol-stable",
|
||
horizon = 'Months,
|
||
states = [],
|
||
transitions = [
|
||
d.make_transition {
|
||
from = "tooling-migrated",
|
||
to = "adoption-tooling-complete",
|
||
condition = "adopt_ontoref mode, templates, daemon crate, landing page all present and validated.",
|
||
catalyst = "Daemon extracted from stratumiops; adoption templates created.",
|
||
blocker = "none",
|
||
horizon = 'Months,
|
||
},
|
||
d.make_transition {
|
||
from = "adoption-tooling-complete",
|
||
to = "protocol-stable",
|
||
condition = "ADR-001 accepted, ontoref.dev published, at least two external projects consuming the protocol.",
|
||
catalyst = "First external adoption.",
|
||
blocker = "ontoref.dev not yet published; no external consumers yet. Auth model complete. Install pipeline complete. Personal/career schema layer present; content modes operational. Nu 0.111 compat fixed (ADR-006). Protocol v2 complete: manifest.ncl + connections.ncl templates, update_ontoref mode, API catalog via #[onto_api], describe diff, describe api, per-file versioning. Syntaxis syntaxis-ontology crate has pending ES→EN migration errors.",
|
||
horizon = 'Months,
|
||
},
|
||
],
|
||
},
|
||
|
||
d.make_dimension {
|
||
id = "self-description-coverage",
|
||
name = "Self-Description Coverage",
|
||
description = "How completely ontoref describes itself using its own protocol.",
|
||
current_state = "fully-self-described",
|
||
desired_state = "fully-self-described",
|
||
horizon = 'Weeks,
|
||
states = [],
|
||
transitions = [
|
||
d.make_transition {
|
||
from = ".ontology-bootstrapped",
|
||
to = "modes-and-web-present",
|
||
condition = "adopt_ontoref mode, landing page, and all core.ncl nodes reflect current artifact set.",
|
||
catalyst = "Web presence and adoption tooling added in session 2026-03-12.",
|
||
blocker = "none",
|
||
horizon = 'Weeks,
|
||
},
|
||
d.make_transition {
|
||
from = "modes-and-web-present",
|
||
to = "fully-self-described",
|
||
condition = "At least 3 ADRs accepted, reflection/backlog.ncl present, describe project returns complete picture.",
|
||
catalyst = "ADR-001–ADR-006 authored (6 ADRs present). Auth model, project onboarding, and session management nodes added in 2026-03-13. Personal/career/project-card schemas, 5 content modes, search bookmarks, and ADR-006 (Nu 0.111 compat) added in session 2026-03-15. Session 2026-03-23: api-catalog-surface node added (#[onto_api] proc-macro + inventory catalog), describe-query-layer updated (diff + api subcommands), adopt-ontoref-tooling updated (update_ontoref mode + manifest/connections templates + enrichment prompt), ontoref-daemon updated (11 pages, 29 MCP tools, per-file versioning, API catalog endpoint).",
|
||
blocker = "none",
|
||
horizon = 'Weeks,
|
||
},
|
||
],
|
||
},
|
||
|
||
d.make_dimension {
|
||
id = "ecosystem-integration",
|
||
name = "Ecosystem Integration",
|
||
description = "Degree to which other ecosystem projects (stratumiops, syntaxis, vapora, kogral) consume the ontoref protocol.",
|
||
current_state = "stratumiops-integrated",
|
||
desired_state = "multi-project",
|
||
horizon = 'Months,
|
||
coupled_with = ["protocol-maturity"],
|
||
states = [],
|
||
transitions = [
|
||
d.make_transition {
|
||
from = "source-only",
|
||
to = "stratumiops-integrated",
|
||
condition = "stratumiops has .ontoref/config.ncl and scripts/ontoref wrapper functional; ADR-007 marked Superseded pointing to ontoref:adr-002.",
|
||
catalyst = "Ontoref extraction and stratumiops migration session 2026-03-12.",
|
||
blocker = "none",
|
||
horizon = 'Months,
|
||
},
|
||
d.make_transition {
|
||
from = "stratumiops-integrated",
|
||
to = "multi-project",
|
||
condition = "At least one additional project (vapora, kogral, or syntaxis) has .ontoref/config.ncl and scripts/ontoref. Syntaxis parses ontoref Core type.",
|
||
catalyst = "Syntaxis integration spike or vapora/kogral onboarding.",
|
||
blocker = "Syntaxis syntaxis-ontology crate has ES→EN migration errors pending. vapora/kogral not yet initialized with .ontoref/.",
|
||
horizon = 'Months,
|
||
},
|
||
],
|
||
},
|
||
|
||
d.make_dimension {
|
||
id = "operational-mode",
|
||
name = "Operational Mode",
|
||
description = "Runtime connectivity mode: local (files only) or daemon (push-based DB projection). Auto-detected on each command; transitions trigger hook updates and sync. Daemon launched via ADR-004 NCL pipe bootstrap (ontoref-daemon-boot); NATS topology resolved from NATS_STREAMS_CONFIG env var (global ~/.config/ontoref/streams.json) or project-local nats/streams.json.",
|
||
current_state = "local",
|
||
desired_state = "daemon",
|
||
horizon = 'Continuous,
|
||
states = [
|
||
d.make_state {
|
||
id = "local",
|
||
name = "Local",
|
||
description = "No daemon. All operations read from files. Hooks are no-ops. Safe for offline or repo-only work.",
|
||
tension = 'Low,
|
||
},
|
||
d.make_state {
|
||
id = "daemon",
|
||
name = "Daemon",
|
||
description = "Daemon reachable. Ontology projected into DB on each sync. Hooks push on git merge/checkout. NATS events available.",
|
||
tension = 'Low,
|
||
},
|
||
],
|
||
transitions = [
|
||
d.make_transition {
|
||
from = "local",
|
||
to = "daemon",
|
||
condition = "Daemon reachable at ONTOREF_DAEMON_URL and DB available (if db feature enabled).",
|
||
catalyst = "Daemon started, network restored, or first onboarding after install.",
|
||
blocker = "Daemon not running or DB not configured.",
|
||
horizon = 'Continuous,
|
||
},
|
||
d.make_transition {
|
||
from = "daemon",
|
||
to = "local",
|
||
condition = "Daemon unreachable or DB unavailable.",
|
||
catalyst = "Network loss, daemon stopped, or offline work.",
|
||
blocker = "none",
|
||
horizon = 'Continuous,
|
||
},
|
||
],
|
||
},
|
||
|
||
],
|
||
}
|