80 lines
4.8 KiB
Text
80 lines
4.8 KiB
Text
|
let d = import "adr-defaults.ncl" in
|
||
|
|
|
||
|
|
d.make_adr {
|
||
|
|
id = "adr-001",
|
||
|
|
title = "Adopt Ontoref Protocol for Vapora Self-Description",
|
||
|
|
status = 'Accepted,
|
||
|
|
date = "2026-03-14",
|
||
|
|
|
||
|
|
context = "Vapora had reflection modes (reflection/modes/) that imported schema and defaults from stratumiops via relative paths (../../../../stratumiops/reflection/). The ontology/reflection patterns originated in stratumiops as self-description tooling. Stratumiops was subsequently migrated and the protocol extracted into ontoref as a standalone project with independent versioning. Vapora needed to migrate its imports and formally onboard to the ontoref protocol to receive future schema updates, ADR tooling, and daemon-based ontology sync.",
|
||
|
|
|
||
|
|
decision = "Vapora adopts the ontoref protocol as its single on+re tooling reference. All reflection mode imports are updated from stratumiops to ontoref relative paths. Vapora is onboarded via ontoref setup (creates .ontology/, adrs/, .ontoref/config.ncl, reflection support files, git hooks). The ONTOREF_PROJECT_ROOT env var is used to invoke ontoref setup before .ontology/ exists. Ontology defaults are imported via relative paths from ontoref's ontology/defaults/. The ontoref CLI at ~/.local/bin/ontoref is the canonical entry point.",
|
||
|
|
|
||
|
|
rationale = [
|
||
|
|
{
|
||
|
|
claim = "Stratumiops is no longer the protocol owner",
|
||
|
|
detail = "The ontology/reflection protocol was extracted to ontoref (ADR-001 in ontoref). Vapora continuing to import from stratumiops would target a deprecated path and miss all future protocol evolution.",
|
||
|
|
},
|
||
|
|
{
|
||
|
|
claim = "Ontoref setup is idempotent and safe to re-run",
|
||
|
|
detail = "The setup command creates missing artifacts and skips existing ones. Re-running after install-daemon syncs any new templates. This makes the adoption reversible and incrementally completable.",
|
||
|
|
},
|
||
|
|
{
|
||
|
|
claim = "Relative imports from ontoref are stable under single-machine development",
|
||
|
|
detail = "Both vapora and ontoref live under ~/Development/. Relative paths (../../ontoref/...) are consistent across the local checkout structure. The nickel_import_paths in .ontoref/project.ncl can be extended if the layout changes.",
|
||
|
|
},
|
||
|
|
],
|
||
|
|
|
||
|
|
consequences = {
|
||
|
|
positive = [
|
||
|
|
"Vapora receives ontoref protocol updates (schema changes, new defaults, new ADR fields) via repo pull",
|
||
|
|
"Ontoref daemon can sync vapora ontology once NATS is running and ONTOREF_TOKEN is set",
|
||
|
|
"Git hooks (post-commit, post-merge) notify daemon of NCL file changes automatically",
|
||
|
|
"adrs/ directory now follows the ontoref ADR lifecycle schema (Proposed/Accepted/Superseded)",
|
||
|
|
"Reflection modes are schema-validated against ontoref's typed schema.ncl",
|
||
|
|
],
|
||
|
|
negative = [
|
||
|
|
"Relative imports require both repos checked out under the same parent directory",
|
||
|
|
"nickel_import_paths in project.ncl must be updated if the checkout layout changes",
|
||
|
|
],
|
||
|
|
},
|
||
|
|
|
||
|
|
alternatives_considered = [
|
||
|
|
{
|
||
|
|
option = "Keep importing from stratumiops with updated paths after stratumiops migration",
|
||
|
|
why_rejected = "Stratumiops no longer owns the protocol. Importing from it would target stale schemas and miss ontoref-specific features (daemon, ADR lifecycle, gate membranes).",
|
||
|
|
},
|
||
|
|
{
|
||
|
|
option = "Copy ontoref schema files into vapora/adrs/ and vapora/.ontology/",
|
||
|
|
why_rejected = "Creates schema drift. Any ontoref protocol update would require a manual copy to vapora. The relative import approach gives vapora the latest protocol via a single git pull in ontoref.",
|
||
|
|
},
|
||
|
|
],
|
||
|
|
|
||
|
|
constraints = [
|
||
|
|
{
|
||
|
|
id = "no-stratumiops-reflection-imports",
|
||
|
|
claim = "No file in vapora may import from stratumiops/reflection/ paths",
|
||
|
|
scope = "vapora (reflection/modes/, .ontology/)",
|
||
|
|
severity = 'Hard,
|
||
|
|
check = { tag = 'Grep, pattern = "stratumiops/reflection", paths = ["reflection/", ".ontology/"], must_be_empty = true },
|
||
|
|
rationale = "Stratumiops is no longer the protocol owner. All reflection and ontology schemas come from ontoref.",
|
||
|
|
},
|
||
|
|
{
|
||
|
|
id = "ontoref-single-entry-point",
|
||
|
|
claim = "All on+re operations must go through the ontoref CLI (~/.local/bin/ontoref or scripts/ontoref wrapper)",
|
||
|
|
scope = "vapora (all actors)",
|
||
|
|
severity = 'Soft,
|
||
|
|
check = { tag = 'FileExists, path = ".ontoref/config.ncl", present = true },
|
||
|
|
rationale = "Direct nickel invocations bypass the daemon notification, log, and lock mechanisms.",
|
||
|
|
},
|
||
|
|
],
|
||
|
|
|
||
|
|
related_adrs = [],
|
||
|
|
|
||
|
|
ontology_check = {
|
||
|
|
decision_string = "vapora adopts ontoref protocol; reflection imports migrated from stratumiops to ontoref; .ontology/ and adrs/ managed via ontoref CLI",
|
||
|
|
invariants_at_risk = ["ontoref-protocol-adoption"],
|
||
|
|
verdict = 'Safe,
|
||
|
|
},
|
||
|
|
}
|