| title | Architecture Decision Records (ADRs) |
|---|---|
| description | Themed index of every VisionClaw ADR, with title and status drawn from each record's own header. |
VisionClaw Docs · Architecture Decision Records (ADRs)
This directory holds the architecture decision records for VisionClaw. Each ADR
captures one significant choice — the context that forced it, the options weighed,
the decision taken, and its consequences. Records are append-only: a decision is
revised by writing a new ADR that supersedes the old one, never by rewriting
history in place. Superseded records move to superseded/ and keep
a forward pointer to whatever replaced them.
The numbering runs ADR-011 through ADR-129 with gaps (early consolidation records
ADR-001..010 and ADR-015..026 were folded into later ones). Sections below group the
records by theme; within a theme they are ordered by number. Status is read from
each record's own ## Status block, so it reflects the decision's real lifecycle
state — Proposed, Accepted, Ratified, Implementing, Implemented, or
Superseded.
Two ADR numbers are reused by two distinct records each. These are genuine collisions in the corpus, not aliases — read both files:
| Number | Files |
|---|---|
| ADR-074 | Cross-System DID:Nostr Canonicalisation · §D2′ did:nostr Multikey convergence |
ADR-074 §D2/§D3/§D4/§D13 are superseded by ADR-125; the remainder of ADR-074 still stands. One fully superseded record lives outside the main set:
| Record | Superseded by |
|---|---|
superseded/ADR-037 — Binary Protocol Consolidation |
ADR-061 — Binary Protocol Unification |
Authentication enforcement, decentralised identity (DID:Nostr), key custody and delegation. See Security model.
| ADR | Title | Status |
|---|---|---|
| 011 | Universal Authentication Enforcement | Accepted |
| 028 | NIP-98 as Enterprise Auth — Optional-Auth Extension | Ratified |
| 040 | Enterprise Identity Strategy | Accepted |
| 048 | Dual-Tier Identity Model — KG Notes and Ontology Classes | Implemented |
| 074 | Cross-System DID:Nostr Canonicalisation & NIP-26 Trust Pivot | Accepted (§D2–D4/D13 superseded by 125) |
| 074-D2 | did:nostr Multikey convergence (canonical DID-document form) | Accepted |
| 081 | Federation Key Custody & Rotation Protocol | Deferred (frozen 2026-07-03) |
| 088 | Auth Service Extraction | Proposed |
| 094 | Admin-Pubkey Permission Model and NIP-26 Phone Delegation | Deferred (frozen 2026-07-03) |
| 125 | DID:Nostr Multikey Convergence (supersedes ADR-074 §D2–D4/D13) | Accepted |
The position wire format, WebSocket transport and store decomposition. See the Binary protocol reference and WebSocket protocol.
| ADR | Title | Status |
|---|---|---|
| 012 | WebSocket Store Decomposition | Accepted |
| 038 | Position Data Flow Consolidation | Implemented |
| 060 | Owner-pubkey-filtered Binary Position Encoder | Proposed |
| 061 | Binary Protocol Unification — Single Wire, No Versioning | Accepted |
037 |
Binary Protocol Consolidation | Superseded by 061 |
CUDA force compute, analytics correctness, layout modes and the zero-allocation render loop. See Physics & GPU engine.
| ADR | Title | Status |
|---|---|---|
| 013 | Zero-Allocation Render Loop | Accepted |
| 031 | GPU Analytics Correctness and Wiring | Partial |
| 039 | Settings/Physics Object Consolidation | Implemented |
| 069 | Force-Preset System & Per-Edge-Category Forces | Implementing |
| 070 | CUDA Integration Hardening | Implementing |
| 098 | Semantic Constraint Path — Reuse ConstraintData Buffer | Accepted |
| 104 | Shared Math Utilities Extraction | Proposed |
| 108 | Layout Mode System for Knowledge Graph Discovery | Accepted |
The semantic pipeline, typed graph schema, reasoner posture, triple-store and the governed ontology writeback loop. See Ontology pipeline.
| ADR | Title | Status |
|---|---|---|
| 014 | Semantic Pipeline Unification | Accepted |
| 036 | Node Type System Consolidation | Accepted |
| 041 | Judgment Broker Workbench Architecture | Implemented |
| 042 | Workflow Proposal Object Model | Implemented |
| 043 | KPI Lineage Model | Accepted |
| 045 | Policy Engine Approach | Accepted |
| 049 | Insight Migration Broker Workflow | Implemented |
| 064 | Typed Graph Schema (UA-Aligned, URN-Bound) | Implementing |
| 067 | Ontobricks MCP Bridge & Reasoning Federation | Deferred (frozen 2026-07-03) |
| 072 | AutoRDF2GML-Inspired Feature Engineering Pipeline | Partial (1 of 6 components) |
| 099 | Reasoner Posture — Whelk-rs EL Primary, DL Deep-Check Offline | Accepted |
| 100 | Canonical IRI Scheme, rdf:type Classification, Vocabulary Alignment | Accepted |
| 101 | Triple-Store Migration Framework for Oxigraph | Accepted |
| 106 | SPARQL PATCH for Ontology Mutations | Accepted |
| 112 | Ontology Augmentation — Shared-Library Retrieval Spine | Implemented |
| 114 | Memory Substrate for the Ontology Class-Summary Index | Proposed |
| 121 | Self-Improving Ontology via Governed Writeback | Deferred (frozen 2026-07-03) |
| 122 | Two-Speed Writeback — Governance Routing by Epistemic Class | Deferred (frozen 2026-07-03) |
| 123 | Voice-Mediated Governance — Conversational Sign-Off | Deferred (frozen 2026-07-03) |
| 127 | Semantic Trust Layer — SHACL in Oxigraph, PROV-O, SPARQL Federation | Accepted |
Pod-backed graph storage, WAC visibility, the embedded solid-pod-rs library and
per-user sovereignty. See Solid sidecar architecture.
| ADR | Title | Status |
|---|---|---|
| 027 | Pod-backed Graph Views | Implemented |
| 029 | Type Index for Agent and View Discovery | Implemented |
| 030 | Agent Memory in Solid Pods | Accepted |
| 032 | Embed solid-pod-rs as Rust Library (replace JSS sidecar) | Implemented |
| 044 | Connector Governance and Privacy Boundaries | Accepted |
| 050 | Pod-backed KGNode Schema — Sovereign Private Nodes | Ratified |
| 051 | Visibility Transitions — Publish / Unpublish Saga | Ratified |
| 052 | Pod Default WAC + Public Container Model | Ratified |
| 053 | solid-pod-rs Crate Extraction | Implemented |
| 054 | URN-Solid + solid-schema + Solid-Apps Ecosystem Alignment | Ratified |
| 055 | Sovereign Debt Payoff + Phase 2 Sprint | Ratified |
| 056 | JSS Parity Migration Architecture | Ratified |
| 066 | Pod-Federated Graph Storage with Anti-Replay Signing | Proposed |
| 096 | Solid Pod Persistence Boundary for the Mobile Bridge | Deferred (frozen 2026-07-03) |
| 107 | GitHub Credentials in Pod — Sovereign Per-User Auth | Ratified |
The Godot/OpenXR native client, WASM visualisation components, the XR transport handshake and removal of the legacy enterprise dashboard. See XR architecture.
| ADR | Title | Status |
|---|---|---|
| 046 | Enterprise UI Architecture | Accepted |
| 047 | WASM Visualization Components | Implemented |
| 071 | Godot 4 + godot-rust + OpenXR Native APK as the XR Client | Accepted |
| 102 | XR Client ↔ Backend Transport Completion (Graph V3 + Presence) | Accepted |
| 103 | Enterprise Dashboard Removal — Migration to Nostr Forum | Accepted |
| 126 | XR/MR Interface — OMB Adoption Posture | Proposed |
| 129 | Control Center Re-imagination — glass overlay replaces the docked settings panel | Accepted |
Bead provenance, the agent activity channel, the private Nostr relay mesh, the mobile bridge and ACSP control surfaces. See Subsystems and the agentbox subsystem docs.
| ADR | Title | Status |
|---|---|---|
| 033 | Git-as-Bead-Provenance for VisionClaw Governance Events | Proposed |
| 034 | Adopt NEEDLE Patterns for Bead Provenance System | Accepted |
| 058 | Deprecate multi-agent-docker in Favour of agentbox | Accepted |
| 059 | Bi-directional URI-keyed Agent Activity Channel | Accepted |
| 073 | Private Nostr Relay Mesh Topology & NIP-42 AUTH | Deferred (frozen 2026-07-03) |
| 075 | Inter-System Message Envelope (IS-Envelope v1) | Proposed |
| 076 | Absorb Forum nostr-core into Upstream nostr Crate | Proposed |
| 092 | Android Nostr Client and Signer for the Mobile Bridge | Deferred (frozen 2026-07-03) |
| 093 | Mobile Bridge Messaging Substrate (NIP-17 / NIP-44 / NIP-59) | Deferred (frozen 2026-07-03) |
| 095 | Session-as-Summary Event Scheme (kind-30840) | Deferred (frozen 2026-07-03) |
| 097 | Mobile Bridge Relay Topology and Phased Federation | Deferred (frozen 2026-07-03) |
| 110 | Agentic Actors Project Control Surfaces (ACSP) | Accepted |
Cross-substrate convergence, the hexagonal crate split, CQRS removal, URN naming cutover, QE policy, secrets management, infographics and contracts. See Backend architecture and Bounded contexts.
| ADR | Title | Status |
|---|---|---|
| 057 | Contributor Enablement Platform | Deferred (frozen 2026-07-03) |
| 062 | QE Graph Scaffolding — PRD / ADR / DDD Traceability via URN | Accepted |
| 063 | URN-Traced Operations Across All Subsystems | Accepted |
| 065 | Rust-Native Code Analysis Pipeline | Deferred (frozen 2026-07-03) |
| 068 | Logseq Block-Level Fidelity (Matryca-Heritage Parser) | Implementing |
| 077 | Ecosystem Quality Engineering Policy | Proposed |
| 078 | Cross-Substrate Library Convergence | Deferred (frozen 2026-07-03) |
| 079 | Forum-Setup Skill Provider Abstraction | Deferred (frozen 2026-07-03) |
| 080 | Forum Kit Deployment Topology Patterns | Deferred (frozen 2026-07-03) |
| 082 | Cross-Substrate Test Fixture Sharing Protocol | Deferred (frozen 2026-07-03) |
| 083 | dreamlab-ai-website Cutover Migration Pattern | Deferred (frozen 2026-07-03) |
| 084 | Cloud Infrastructure Mapping for Kit Consumers | Deferred (frozen 2026-07-03) |
| 085 | forum-config/ Package Architecture & Branding Extension Points | Deferred (frozen 2026-07-03) |
| 086 | Git-Over-HTTP Ingest Unification | Implemented |
| 087 | Rate Limit Consolidation | Proposed |
| 089 | CQRS Dead Bus Removal | Accepted |
| 090 | Hexagonal Crate Modularisation | Accepted |
| 091 | Cross-Substrate Fixture Sync Enforcement | Proposed |
| 105 | urn:visionclaw Convergence and urn:ngm Cutover | Accepted |
| 109 | SOPS + age for Ecosystem Secrets Management | Accepted |
| 111 | Ecosystem Infographic Modernisation — diagram-as-code | Proposed |
| 124 | Smart-Contract Features — Web-Contracts on a Single-Use-Seal Through-Line | Implemented |
| 128 | Build-Out — Adopt gitmark/blocktrails as the Web-Contract Substrate | Accepted |
The RuVector Format integration is captured as a three-document set rather than a numbered ADR:
| Document | Title | Status |
|---|---|---|
| PRD | RVF (RuVector Format) Integration into VisionClaw | Draft |
| AFD | RVF Integration Architecture Fitness Document | Draft |
| DDD | RVF Integration Domain-Driven Design | Draft |
- PRD index — product requirements that motivate these decisions
- DDD index — domain models the decisions implement
- Reference index — wire formats, schemas, and config the ADRs govern
- Explanation index — the conceptual architecture these records shape
- agentbox ADRs — decisions owned by the agentbox subsystem, federated into VisionClaw