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]
101 lines
2.9 KiB
Plaintext
101 lines
2.9 KiB
Plaintext
let c = import "adr-constraints.ncl" in
|
|
|
|
let status_type = [| 'Proposed, 'Accepted, 'Superseded, 'Deprecated |] in
|
|
let severity_type = [| 'Hard, 'Soft |] in
|
|
let verdict_type = [| 'Safe, 'RequiresJustification |] in
|
|
|
|
let rationale_entry_type = {
|
|
claim | String,
|
|
detail | String,
|
|
} in
|
|
|
|
let alternative_type = {
|
|
option | String,
|
|
why_rejected | String,
|
|
} in
|
|
|
|
# Tag discriminant for typed constraint checks.
|
|
# Used by validate.nu to dispatch execution per variant.
|
|
let check_tag_type = [|
|
|
'Cargo,
|
|
'Grep,
|
|
'NuCmd,
|
|
'ApiCall,
|
|
'FileExists,
|
|
|] in
|
|
|
|
# Typed constraint check: a tagged record, JSON-serializable.
|
|
# Required fields per tag (validated by EachCheckWellFormed in adr-constraints.ncl):
|
|
# 'Cargo -> crate : String, forbidden_deps : Array String
|
|
# 'Grep -> pattern : String, paths : Array String, must_be_empty : Bool
|
|
# 'NuCmd -> cmd : String, expect_exit : Number
|
|
# 'ApiCall -> endpoint : String, json_path : String, expected : Dyn
|
|
# 'FileExists-> path : String, present : Bool
|
|
let constraint_check_type = {
|
|
tag | check_tag_type,
|
|
..
|
|
} in
|
|
|
|
let constraint_type = {
|
|
id | String,
|
|
claim | String,
|
|
scope | String,
|
|
severity | severity_type,
|
|
# Transition period: one of check or check_hint must be present.
|
|
# check_hint is deprecated — migrate existing ADRs to typed check variants.
|
|
check_hint | String | optional,
|
|
check | constraint_check_type | optional,
|
|
rationale | String,
|
|
} in
|
|
|
|
let ontology_check_type = {
|
|
decision_string | String,
|
|
invariants_at_risk | Array String,
|
|
verdict | verdict_type,
|
|
} in
|
|
|
|
let invariant_justification_type = {
|
|
invariant | String,
|
|
claim | String,
|
|
mitigation | String,
|
|
} in
|
|
|
|
let consequences_type = {
|
|
positive | Array String,
|
|
negative | Array String,
|
|
} in
|
|
|
|
let adr_type = {
|
|
id | String | c.AdrIdFormat,
|
|
title | String,
|
|
status | status_type,
|
|
date | String,
|
|
|
|
context | String,
|
|
decision | String,
|
|
rationale | Array rationale_entry_type,
|
|
consequences | consequences_type,
|
|
alternatives_considered | Array alternative_type,
|
|
|
|
constraints | Array constraint_type | c.NonEmptyConstraints | c.EachConstraintHasCheck,
|
|
ontology_check | ontology_check_type,
|
|
|
|
related_adrs | Array String | default = [],
|
|
supersedes | String | optional,
|
|
superseded_by | String | optional,
|
|
invariant_justification | invariant_justification_type | optional,
|
|
} in
|
|
|
|
{
|
|
AdrStatus = status_type,
|
|
Severity = severity_type,
|
|
Verdict = verdict_type,
|
|
ConstraintCheck = constraint_check_type,
|
|
Constraint = constraint_type,
|
|
RationaleEntry = rationale_entry_type,
|
|
Alternative = alternative_type,
|
|
OntologyCheck = ontology_check_type,
|
|
InvariantJustification = invariant_justification_type,
|
|
Adr = adr_type,
|
|
}
|