VisionClaw/docs/adr/README.md at main · DreamLab-AI/VisionClaw · GitHub
Skip to content

Latest commit

 

History

History
175 lines (165 loc) · 34.5 KB

README.md

File metadata and controls

175 lines (165 loc) · 34.5 KB

Architecture Decision Records

How to work against this pack (engineering/build-with-quality agents start here):

The ADR pack for any domain is its living governing document in docs/ plus the ledger records below that amend it. The living docs are normative — their Invariants sections are the compliance surface and their Change process sections say how to amend them:

Domain Governing document
Stores, processes, actors, trust boundaries ../BASELINE-architecture.md
Identity, NIP-98, RBAC, delegation ../IDENTITY-authority-chain.md
Data ownership, dual-writes, erasure, backup ../DATA-authority-erasure.md
Wire frames, endpoints, versioning ../PROTOCOL-registry.md
IRIs, URNs, node ids, DID documents ../IDENTIFIER-taxonomy.md
Security flags, named profiles, illegal combos ../SECURITY-profiles.md
SimParams ABI, force channels, kernels ../GPU-wire-abi.md
Godot XR client, HUD, deploy ../XR-client.md
Authored corpus: vault layout, frontmatter, inclusion gate, converter ../VAULT-corpus-format.md
Codescape: live code-graph visualisation, separate workspace and ports, isolation (ADR-2143) ../BASELINE-architecture.md §Codescape + ../PROTOCOL-registry.md §Second producer

Lookup order: governing doc → its file:line citations into code → the ledger records below → docs/archive/ only for rationale and history — never as authority (the archive is the pre-2026-08-31 corpus, frozen precisely because it drifted from the code; see ../MIGRATION-plan.md for the legacy-number redirect table).

Making a decision: copy TEMPLATE.md to ADR-NNNN-slug.md (next free number), fill the three-axis status honestly, update the affected governing document in the same change, and regenerate this index (node scripts/adr-index-gen.js docs/adr — CI-enforced via .github/workflows/docs-ci.yml: invalid frontmatter, asymmetric supersession edges, and stale verified_commit+verified_paths claims all fail the build).

The historical closeout routing note points each frozen archive record at the estate section-level review and the complete VisionClaw historical map; a lineage mention there does not supersede every section of a predecessor.

The estate status/evidence contract defines the independent decision, implementation and activation axes and distinguishes lineage from supersession (2026-09-07).

129 record(s). Regenerate with node scripts/adr-index-gen.js docs/adr.

ID Title Domain Date Decision Impl Activation Supersedes Superseded by Owner Repo
ADR-2001 Consolidate the documentation corpus onto a thin living ADR series — 2026-08-31 accepted partial staged — — jjohare visionclaw
ADR-2002 NIP-98 replay protection is a two-layer scheme with a single-use cache — 2026-08-31 accepted complete live — — jjohare visionclaw
ADR-2003 The pubkey visibility filter defaults ON — 2026-08-31 accepted complete live — — jjohare visionclaw
ADR-2004 Embedded Oxigraph plus per-writer SQLite owns canonical graph and local state BASELINE-architecture 2026-08-31 accepted complete live — — jjohare visionclaw
ADR-2005 Hexagonal split of the webxr monolith into a thin root binary plus visionclaw crates BASELINE-architecture 2026-08-31 accepted partial live — — jjohare visionclaw
ADR-2006 Human-approval flows go through the stateless ACSP forum surface BASELINE-architecture 2026-08-31 accepted partial live — — jjohare visionclaw
ADR-2007 GPUManagerActor is a coordinator over four subsystem supervisors on a context bus BASELINE-architecture 2026-08-31 accepted partial live — — jjohare visionclaw
ADR-2008 The development image recompiles the Rust backend on container start BASELINE-architecture 2026-08-31 accepted partial live — — jjohare visionclaw
ADR-2009 Two request-auth realms coexist — NIP-98 signatures and login-derived session bearers IDENTITY-authority-chain 2026-08-31 accepted complete live — — jjohare visionclaw
ADR-2010 Four-tier pubkey-bound RBAC lattice (Editor default, fail-closed to Viewer) with atomic role mutations IDENTITY-authority-chain 2026-08-31 accepted partial live — — jjohare visionclaw
ADR-2011 One central RbacGate covers the whole /api scope; writes gate at WriteGraph, not mere Authenticated IDENTITY-authority-chain 2026-08-31 accepted complete live — — jjohare visionclaw
ADR-2012 Development token and RBAC report mode have distinct activation gates IDENTITY-authority-chain 2026-08-31 accepted partial live — — jjohare visionclaw
ADR-2013 Enterprise federation and delegated-user authority are deferred; public-key identity supports multiple request credentials IDENTITY-authority-chain 2026-08-31 accepted none inactive — — jjohare visionclaw
ADR-2014 GitHub public:: true gates KG inclusion; owl:class:: bypasses it DATA-authority-erasure 2026-08-31 accepted complete live — ADR-2040 jjohare visionclaw
ADR-2015 Derived-writeback fence — only :summary/:observed are writable DATA-authority-erasure 2026-08-31 accepted complete live — — jjohare visionclaw
ADR-2016 GRAPH_PROVENANCE is append-only (INSERT DATA only) DATA-authority-erasure 2026-08-31 accepted partial live — — jjohare visionclaw
ADR-2017 One write-master per data class; disposable derived projections; SQLite-only online backup DATA-authority-erasure 2026-08-31 accepted partial live — — jjohare visionclaw
ADR-2018 The graph frame is a frozen 52-byte inline-analytics V3 record wrapped additively by the V5 sequence envelope PROTOCOL-registry 2026-08-31 accepted complete live — — jjohare visionclaw
ADR-2019 Tag byte 0 is registry-governed — it selects the codec, rejects unknown tags, and is allocated across disjoint per-socket spaces PROTOCOL-registry 2026-08-31 accepted complete live — — jjohare visionclaw
ADR-2020 Agent co-presence is an additive sibling opcode, not an extension of the pose frame PROTOCOL-registry 2026-08-31 accepted complete staged — — jjohare visionclaw
ADR-2021 Durable urn:visionclaw IDs are minted only through typed fail-closed constructors, with mint split from resolve IDENTIFIER-taxonomy 2026-08-31 accepted partial live — — jjohare visionclaw
ADR-2022 Identity is a did:nostr hex pubkey — no agent URN kind, hex x-only canonical, npub display-only IDENTIFIER-taxonomy 2026-08-31 accepted complete live — — jjohare visionclaw
ADR-2023 Content address is sha256-12, byte-identical to the agentbox sha12() contract IDENTIFIER-taxonomy 2026-08-31 accepted complete live — — jjohare visionclaw
ADR-2024 Wire node-ID is an ephemeral 26-bit u32 with reserved type-flag bits, not a URN IDENTIFIER-taxonomy 2026-08-31 accepted complete live — — jjohare visionclaw
ADR-2025 cross_from_agentbox is a closed kind-map that returns None, never a synthetic ID, for unmapped URNs IDENTIFIER-taxonomy 2026-08-31 accepted complete live — — jjohare visionclaw
ADR-2026 Fail-closed security posture — flag absence widens nothing, release aborts on promoted dev-auth SECURITY-profiles 2026-08-31 accepted complete live — — jjohare visionclaw
ADR-2027 Three named deployment profiles, with the shipped compose booting demo-open SECURITY-profiles 2026-08-31 accepted partial live — — jjohare visionclaw
ADR-2028 SimParams is a size-locked 212-byte repr(C) raw-copy ABI, grown tail-append only GPU-wire-abi 2026-08-31 accepted complete live — — jjohare visionclaw
ADR-2029 Force channels map over the flat struct; execution.rs is the flag authority and ENABLE_CONSTRAINTS is residency-owned GPU-wire-abi 2026-08-31 accepted partial live — — jjohare visionclaw
ADR-2030 PTX ISA is text-rewritten to .version 9.0 at build time GPU-wire-abi 2026-08-31 accepted partial live — — jjohare visionclaw
ADR-2031 Withdrawn — number reserved, no decision recorded — 2026-08-31 rejected none inactive — — jjohare visionclaw
ADR-2032 Native Godot 4 + godot-rust + OpenXR client on a forced Compatibility renderer XR-client 2026-08-31 accepted complete live — — jjohare visionclaw
ADR-2033 HUD buttons fire on press, not release XR-client 2026-08-31 accepted partial live — — jjohare visionclaw
ADR-2034 The Rust RenderStore owns per-frame instance math under a server-which/client-where authority split XR-client 2026-08-31 accepted partial live — — jjohare visionclaw
ADR-2035 DAG-rank detection ranks subClassOf provenance, not the collapsed 'hierarchical' label XR-client 2026-08-31 accepted complete live — — jjohare visionclaw
ADR-2036 Defensive OpenXR boot — query eye-gaze capability and degrade, never blind-bind XR-client 2026-08-31 accepted complete live — — jjohare visionclaw
ADR-2037 Production release images are built without the dev-auth cargo feature, asserted in CI SECURITY-profiles 2026-08-31 proposed partial staged — — jjohare visionclaw
ADR-2038 Boot-time deployment-profile assertion with illegal-combination abort SECURITY-profiles 2026-08-31 accepted partial live — — jjohare visionclaw
ADR-2039 VISIONCLAW_DEV_MODE — a peer-agnostic LAN-local full auth bypass for a 100%-local dev headset SECURITY-profiles 2026-09-01 proposed complete inactive — — jjohare visionclaw
ADR-2040 The authored corpus is an Obsidian vault; YAML frontmatter public/owl-class gate KG inclusion with bounded Logseq tolerance VAULT-corpus-format 2026-09-02 superseded partial staged ADR-2014 ADR-2112 jjohare visionclaw
ADR-2041 The knowledge-graph settings key and graph-type value are knowledge; logseq is a read-only alias for one release VAULT-corpus-format 2026-09-02 superseded complete staged — ADR-2115 jjohare visionclaw
ADR-2042 vault-migrate is the sole Logseq→Obsidian converter — deterministic, output-dir by default, preserve-and-report VAULT-corpus-format 2026-09-02 superseded partial live — ADR-2113 jjohare visionclaw
ADR-2043 Reject the full-disclosure flag pair at boot, whether or not a profile is declared SECURITY-profiles 2026-09-05 accepted complete staged — — jjohare visionclaw
ADR-2044 Session credentials fail closed and expire identically on every transport IDENTITY-authority-chain 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2045 Remove the dead ActorLifecycleManager supervision machinery BASELINE-architecture 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2046 Remove the dead SettingsActor and the orphaned src/config/* copies BASELINE-architecture 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2047 Emit settings-change broadcasts from one place, on a contract a client can consume BASELINE-architecture 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2048 Correct the drifted file:line citations in the boot, identity and posture governing docs BASELINE-architecture 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2049 The production image's dependency-warming stage must be able to fail BASELINE-architecture 2026-09-05 accepted complete staged — — jjohare visionclaw
ADR-2053 Make direct context delivery authoritative and give every GPU analytics actor one residency — 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2054 Delete the dead GPU, analytics and WebSocket code paths — 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2055 Retire the frozen physics-v2 layout engines and stop advertising modes the server cannot honour — 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2056 Route every PTX ISA downgrade through the single span-parsed rewrite — 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2057 Lock the V3 record and V5 envelope widths at compile time — 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2058 Accept WebSocket bearer tokens only from the Authorization header — 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2059 Remove the analytics feature flags that gate nothing — 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2060 Correct the GPU and wire governing-doc citations and retire resolved divergence bullets — 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2061 Validate the GPU analytics kernels against the CPU reference oracle — 2026-09-05 accepted complete staged — — jjohare visionclaw
ADR-2063 The natural-language query service emits read-only SPARQL against Oxigraph, not Cypher BASELINE-architecture 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2064 The ontology loader walks the real authored corpus, not a hardcoded sample VAULT-corpus-format 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2065 Remove dead ontology and validation code BASELINE-architecture 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2066 Remove unreachable handler and service surfaces BASELINE-architecture 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2067 The Solid pod feature-off build registers no routes SECURITY-profiles 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2068 Remove superseded vendored assets and dead config BASELINE-architecture 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2069 Ratify the required/optional backup membership contract and refuse incomplete backup sets — 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2070 Correct identifier and vault documentation drift where the code already leads — 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2071 Consolidate inferred-edge materialisation onto the shared set-logic module — 2026-09-05 accepted complete staged — — jjohare visionclaw
ADR-2072 Map bead structurally in cross_from_agentbox; remove dead metrics scaffolding in agent_visualization_processor IDENTIFIER-taxonomy 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2074 One helper computes the browser client's auth headers; no transport carries its own copy IDENTITY-authority-chain 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2075 Authenticate /ws/speech with a post-upgrade NIP-98 frame and drop query-token auth XR-client 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2076 The XR client authenticates the graph socket with NIP-98 only, never a query token XR-client 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2077 Delete the dead browser-client surfaces — interactionApi, message:graph, closeAll, empty feature dirs XR-client 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2078 The TypeScript decoder fails closed on V2 and unknown versions, PROTOCOL_V4 names one thing, and the wire is fixture-pinned PROTOCOL-registry 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2079 Correct the XR closeout narrative — the press-mode and DAG-label items are closed in code XR-client 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2080 The browser client consumes the settingsUpdated broadcast so peers converge without a reload IDENTITY-authority-chain 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2081 Remove the dead browser XR-mode surface; the immersive client is the Godot app XR-client 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2083 Multi-MCP discovery loop honours the configured discovery_interval_ms BASELINE-architecture 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2084 Correct the stale ":9500 deprecated" and "beam+gluon" doc drift; plan the state-snapshot WS cutover PROTOCOL-registry 2026-09-05 accepted complete staged — — jjohare visionclaw
ADR-2085 The briefing workflow client calls agentbox routes that do not exist BASELINE-architecture 2026-09-05 accepted complete staged — — jjohare visionclaw
ADR-2086 CI asserts release/production builds exclude the dev-auth cargo feature SECURITY-profiles 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2087 Correct the deployment-profile documentation to match the code defaults SECURITY-profiles 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2088 BotsClient::get_status reports resolved runtime values, never literals BASELINE-architecture 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2089 Remove the zero-sender MultiMcpVisualizationActor subscriber API BASELINE-architecture 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2090 WebSocket upgrades resolve the token through the session realm and fail closed IDENTITY-authority-chain 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2091 Remove the two multi-MCP REST routes that returned fabricated state BASELINE-architecture 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2093 The service agent key fails closed and is compared in constant time SECURITY-profiles 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2094 Fail closed on the Management API credential and cache the MCP health verdict IDENTITY-authority-chain 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2095 Mint urn:ngm:class through a typed constructor in the domain crate — 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2096 Route local file sync's inclusion gate through the vault parsing entry point VAULT-corpus-format 2026-09-05 accepted complete live — ADR-2114 jjohare visionclaw
ADR-2097 Delete the MetadataActor refresh stub rather than implement it DATA-authority-erasure 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2098 Point SOLID_POD_URL at the in-process pod endpoint, not the removed JSS sidecar BASELINE-architecture 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2099 Delete the unreachable framed-header agent-action decode branch — 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2100 Consolidate the Solid/JSS notification clients onto one socket — 2026-09-05 accepted complete live — — jjohare visionclaw
ADR-2101 Decision-elevation cases have a durable case-state authority BASELINE-architecture 2026-09-05 accepted complete staged — — jjohare visionclaw
ADR-2102 Orchestrate subject erasure across all five stores, and give the append-only provenance graph a redaction mechanism DATA-authority-erasure 2026-09-05 proposed none inactive — — jjohare visionclaw
ADR-2103 Give Oxigraph a point-in-time backup with a declared RPO and RTO DATA-authority-erasure 2026-09-05 proposed none inactive — — jjohare visionclaw
ADR-2104 Execute the SOPS rollout or formally withdraw ADR-109's acceptance — and document plaintext .env as the interim state either way DATA-authority-erasure 2026-09-05 proposed none inactive — — jjohare visionclaw
ADR-2105 Carry one authoring correlation id through validation, PR, approval, merge and served corpus — VisionClaw echoes it IDENTIFIER-taxonomy 2026-09-05 rejected none inactive — — jjohare visionclaw
ADR-2106 The published ontology is pulled into the embedded pod, not pushed from CI BASELINE-architecture 2026-09-06 accepted partial live — — jjohare visionclaw
ADR-2107 A shared XR visual language with reversible comfort and rendering budgets BASELINE-architecture 2026-09-07 accepted partial staged — — jjohare visionclaw
ADR-2108 Dev compose profile arms VISIONCLAW_DEV_MODE by default — 2026-09-08 proposed complete staged — — jjohare visionclaw
ADR-2109 Embody registry agents in XR with a single pose owner; demo mode only via the real ingest path — 2026-09-09 accepted complete live — — jjohare visionclaw
ADR-2110 Instrument the VisionClaw judgment surfaces against the augmentation conditions — 2026-09-14 accepted complete staged — — jjohare visionclaw
ADR-2111 Re-sequence ADR-124/128 for the bridged-asset case only, delete FsPaymentStore and /pay/* in favour of a proxy to agentbox /v1/wallet, implement AnchorConfirmer against sidestr-node, delete the empty extraction/solid-pod-rs mirror, and disambiguate visionclaw-contracts BASELINE-architecture 2026-09-21 proposed none inactive — — jjohare visionclaw
ADR-2112 The corpus is frontmatter-only OKF governed by a versioned ontology/vocabulary.yaml; the json-ld fences and every Logseq construct are deleted, not tolerated VAULT-corpus-format 2026-09-22 accepted partial staged ADR-2040 — jjohare visionclaw
ADR-2113 crates/vault is the single corpus parser and build — 2026-09-22 accepted partial staged ADR-2042 — jjohare visionclaw
ADR-2114 Corpus ingest is a CorpusSource; the local vault directory is the default source VAULT-corpus-format 2026-09-22 accepted partial staged ADR-2096 — jjohare visionclaw
ADR-2115 GitHub sync is optional and off; the logseq settings alias is removed VAULT-corpus-format 2026-09-22 accepted complete live ADR-2041 — jjohare visionclaw
ADR-2116 Ontology proposals are forum ActionRequests, not pull requests — /api/ontology-agent/propose is retired — 2026-09-22 accepted partial staged — — jjohare visionclaw
ADR-2117 Retire the completed corpus format migration — 2026-10-01 accepted complete staged — — jjohare visionclaw
ADR-2118 Append space science and Earth observation domain identities — 2026-10-01 accepted complete staged — — visionGraph corpus maintainer visionclaw
ADR-2119 Production ingress is declared, LAN or tunnel BASELINE-architecture 2026-10-02 accepted complete staged — — jjohare visionclaw
ADR-2124 visionGraph admits a curated set of EL defined classes, and the corpus reasoner saturates restrictions whenever one is emitted VAULT-corpus-format 2026-10-05 accepted complete staged — — jjohare visionclaw
ADR-2125 The Whelk consistency gate must be provably armed — register and wire the existing disjoint-with key for sibling partitions, add end-to-end probes, and a zero-unsatisfiable build gate VAULT-corpus-format 2026-10-05 accepted complete staged — — jjohare visionclaw
ADR-2126 Corpus integrity requirements are closed-world validation rules, never OWL axioms; the emitted OWL stays inside the EL profile VAULT-corpus-format 2026-10-05 accepted complete staged — — jjohare visionclaw
ADR-2127 Ontology agent answers state their basis and never report "not asserted" as "false BASELINE-architecture 2026-10-05 accepted partial staged — — jjohare visionclaw
ADR-2128 The published ontology carries an owl:versionIRI per generation, and property domain/range are scoped per property instead of owl:Thing VAULT-corpus-format 2026-10-05 accepted partial staged — — jjohare visionclaw
ADR-2133 The memory cloud serves a live stratified snapshot of the RuVector sidecar, and query results come from the sidecar's own index PROTOCOL-registry 2026-10-07 accepted partial staged — — jjohare visionclaw
ADR-2134 The graph socket relays the memory explorer's beat clock and route to the same user's other sessions PROTOCOL-registry 2026-10-07 proposed complete staged — — jjohare visionclaw
ADR-2135 Graph Separation opens a ground-plane triangle of knowledge, ontology and memory, with agents drifting at its centre XR-client 2026-10-07 accepted complete staged — — jjohare visionclaw
ADR-2136 The memory-cloud query response carries the query's point in the snapshot's cloud PROTOCOL-registry 2026-10-08 accepted complete staged — — jjohare visionclaw
ADR-2137 Consume shared ontology semantics through explicit native adapters — 2026-10-11 proposed none inactive — — jjohare visionclaw
ADR-2138 Directed cycles are one server analysis that every client consumes — 2026-10-13 proposed none inactive — — jjohare visionclaw
ADR-2139 Position frames are full snapshots of the entitled set — never deltas, never partial — 2026-10-13 accepted complete staged — ADR-2141 jjohare visionclaw
ADR-2140 Physics forces have one stored definition, applied as stored — no scale factors, caps or shadow state — 2026-10-13 accepted partial staged — — jjohare visionclaw
ADR-2141 Positions are streamed to each client in chunks until it has acknowledged them — 2026-10-13 accepted complete staged ADR-2139 — jjohare visionclaw
ADR-2142 The agents demo is one server-side producer that both clients control and both see — 2026-10-14 accepted complete staged — — jjohare visionclaw
ADR-2143 Codescape is a separate section with its own Cargo workspace, its own port and a tested isolation boundary BASELINE-architecture 2026-10-17 accepted partial inactive — — jjohare visionclaw
ADR-2147 Inferences carry a re-checkable derivation certificate and proposals carry a consequence delta — Whelk stays the blocker — 2026-10-20 accepted complete staged — — jjohare visionclaw