Architecture Decision Records for Refarm.
The full table below is chronological; this guide is thematic. Each cluster names the story its ADRs tell together and points at the entry to read first. Saga-index ADRs (089-092) are front doors that don't add a decision — they map a cluster.
- Storage / CRDT / sync — offline-first (002) over a CRDT (Yjs 003 → Loro 045, the current engine) + SQLite (015) as a materialized view of the op-log (028 → realized by Loro; 031 opens pluggable engines), OPFS (009), schema evolution by lenses (010), storage bootstrap boundary (082).
- Micro-kernel & plugin governance — "core minimal, everything a plugin" (017 → pure IoC in 025) + capability contracts (018); the citizenship mechanisms (versioning, self-healing, policies, conflicts, locks) are indexed by 089.
- Plugin vocabulary / WIT / dispatch — WASI multi-version host (061), the canonical WIT contract 083, async-default dispatch (084), and "One Verb, N Natures" (086, which superseded 027's providesApi/DSL).
- Composition / distribution / namespace — the axiom is Blocks vs Distros 046; host boundary (056), package/leaf ownership (072/073), release handoff (080), namespace (019 → 069, 071), brand-agnostic packages (087).
- Tractor runtime — indexed by 091: browser load → native host → graduate → Rust authoritative 059 → sidecar protocol 060.
- Agent / streaming / memory / surfaces — streaming indexed by 090; memory contracts (057), context injection (058), and the "talk to the agent from any surface" arc: control plane (074) → Pears reference (075) → transport seam (088).
- Identity / security / credentials / Silo — sovereign identity indexed by 092; offline revocation (051), CLI OAuth (063), the Silo pair (076/077), credential verification (079), and surface-neutral model-account resolution (095).
- Infra / CI / bootloader / environments — sovereign bootloader (036) + infra escalation (037); farmhand lifecycle (065), build boundary (066), environment ceilings (078).
- Foundations — monorepo (001), testing (013), tech boundary (008), open surface projection (085).
| ADR | Title | Status | Date |
|---|---|---|---|
| 001 | Monorepo Structure and Workspace Boundaries | Accepted | 2026-03-06 |
| 002 | Offline-First Architecture | Accepted | 2026-03-06 |
| 003 | CRDT Choice (Yjs) | Superseded | 2026-03-06 |
| 005 | Network Abstraction Layer | Accepted | 2026-03-06 |
| 006 | Guest Mode and Collaborative Sessions | Accepted | 2026-03-06 |
| 007 | Observability & Introspection Primitives | Draft | 2026-03-05 |
| 008 | Ecosystem Technology Boundary (Go vs TypeScript) | Accepted | 2026-03-05 |
| 009 | OPFS Persistence Strategy | Accepted | 2026-03-06 |
| 010 | JSON-LD Schema Evolution (Lenses & Upcasting) | Accepted | 2026-03-06 |
| 012 | Hybrid Model Routing Strategy for Agent Harness | Proposed (revised: router in agent, not host — 2026-07-13) | 2026-04-22 |
| 013 | Testing Strategy (Vitest + Playwright) | Accepted | 2026-03-06 |
| 015 | SQLite Engine Decision | Accepted | 2026-03-06 |
| 016 | Headless UI Contract and Token Strategy | Proposed | 2026-03-07 |
| 017 | Studio Micro-Kernel and Plugin Boundary | Accepted | 2026-03-07 |
| 018 | Capability Contracts and Observability Gates (+ Transitive Escalation Prevention) | Accepted | 2026-03-07 |
| 019 | npm Scope and Namespace Strategy (@refarm.dev) | Accepted | 2026-03-07 |
| 025 | Pure Microkernel Architecture for Tractor | Proposed | 2026-03-07 |
| 026 | Externalized Storage Migrations | Proposed | 2026-03-08 |
| 027 | Compositional Plugin Architecture | Superseded | 2026-03-08 |
| 028 | CRDT-SQLite Convergence Strategy | Superseded | 2026-03-08 |
| 029 | Native Browser Permissions as Capabilities | Proposed | 2026-03-08 |
| 030 | DevOps in Grand Style | Proposed | 2026-03-08 |
| 031 | Pluggable Relational Storage | Proposed | 2026-03-09 |
| 032 | Proton Security - Mandatory Signing | Proposed | 2026-03-09 |
| 033 | Command Governance | Accepted | 2026-03-09 |
| 034 | Identity Adoption Conversion | Proposed | 2026-03-10 |
| 035 | Device Verification & Cross-Signing | Proposed | 2026-03-10 |
| 036 | Sovereign Bootloader and Strict SSG | Accepted | 2026-03-11 |
| 037 | Infrastructure Escalation Strategy | Accepted | 2026-03-12 |
| 040 | Sovereign Infrastructure as a Graph | Proposed | 2026-03-13 |
| 041 | Sovereign Environments Isolation | Superseded | 2026-03-13 |
| 042 | Homestead Modularization | Proposed | 2026-03-14 |
| 043 | Radical Dogfooding & Everything as Config (EaC) | Accepted | 2026-03-14 |
| 044 | WASM Plugin Loading Browser Strategy | Accepted | 2026-03-15 |
| 045 | Loro CRDT Adoption | Accepted | 2026-03-17 |
| 046 | Refarm Composition Model (Blocks and Distros) | Accepted | 2026-03-17 |
| 047 | tractor-native — Native Rust Plugin Host | Accepted | 2026-03-19 |
| 048 | Tractor Graduation (tractor-native becomes canonical tractor) | Accepted | 2026-03-19 |
| 049 | Post-Graduation Horizon (tractor Rust roadmap) | Accepted | 2026-03-20 |
| 050 | Exploração de Host Zig + Guest ClojureWasm para Ferramentas do Agente Pi | Superseded | 2026-04-17 |
| 051 | External-Signed Revocation Offline Policy Profiles | Accepted | 2026-04-24 |
| 052 | CRDT-native agent rendezvous with A2A-compatible edges | Proposed | 2026-04-24 |
| 053 | Host-Proxied Model Streaming Boundary | Accepted | 2026-05-02 |
| 054 | Generic Stream Observations and AgentResponse Projection | Accepted | 2026-05-02 |
| 055 | stream-contract-v1 as Separate Transport Package Family | Accepted | 2026-05-02 |
| 056 | Unified refarm Host Boundary (Distro-Owned Host, Block-Owned Primitives) |
Accepted | 2026-05-02 |
| 057 | task-contract-v1 + session-contract-v1 as Memory Layer Contracts |
Accepted | 2026-05-03 |
| 058 | Context Injection Doctrine for Refarm Agents | Accepted | 2026-05-03 |
| 059 | Tractor Rust as Authoritative Runtime | Accepted | 2026-05-04 |
| 060 | Tractor HTTP Sidecar Protocol | Accepted | 2026-05-04 |
| 061 | WASI Multi-Version Plugin Host | Accepted | 2026-05-04 |
| 062 | Cloudflare Provider Package (packages/infra-cloudflare) |
Proposed | 2026-05-08 |
| 063 | Estratégia de autenticação OAuth para a CLI | Accepted | 2026-05-11 |
| 064 | Credential Error Enrichment Contract | Accepted | 2026-05-12 |
| 065 | Farmhand Transparent Lifecycle & Single Entry Point | Accepted | 2026-05-12 |
| 066 | TypeScript/Turbo Build Boundary and Package Scaffold Invariants | Accepted | 2026-05-17 |
| 067 | Capability-Driven Plugin Observer Routing | Accepted | 2026-06-01 |
| 068 | Artifact Contract Naming | Accepted | 2026-06-12 |
| 069 | npm Scope Canonicalization | Accepted | 2026-06-25 |
| 070 | WASM Surface Substrate, Ecosystem Dependency Depth, and Tractor Distribution | Proposed | 2026-06-25 |
| 071 | Workspace Namespace Policy | Accepted | 2026-06-28 |
| 072 | Consumer Leaf Distribution Policy | Accepted | 2026-06-29 |
| 073 | Capability Index Incubation Boundary | Accepted | 2026-06-30 |
| 074 | Remote Workspace Control Plane | Accepted | 2026-06-30 |
| 075 | Pears as Distributed Runtime Reference | Accepted | 2026-06-30 |
| 076 | Silo Storage Surface Free of the Identity Closure | Accepted | 2026-06-29 |
| 077 | Silo Protected Secret Envelope | Accepted | 2026-06-30 |
| 078 | Agent-Commons Environment Ceilings | Accepted | 2026-06-30 |
| 079 | Credentials Verification Policy | Accepted | 2026-07-01 |
| 080 | The vault-seed-ready Handoff Pipeline as Pre-Publication Release Vehicle |
Accepted | 2026-07-03 |
| 081 | Local Surface Boundary | Proposed | 2026-07-03 |
| 082 | Storage Provider Bootstrap Boundary | Proposed | 2026-07-03 |
| 083 | Canonical Plugin WIT Contract | Accepted | 2026-07-03 |
| 084 | Plugin Dispatch Model — Async-Default, Sync-Negotiated | Accepted | 2026-07-05 |
| 085 | Open Surface Projection Axis — Surfaces as Data, Projectors as Plugins | Proposed | 2026-07-09 |
| 086 | Plugin Vocabulary Convergence — One Verb, N Natures | Accepted | 2026-07-10 |
| 087 | Brand-Agnostic Packages — Only the App Owns Its Name | Accepted | 2026-07-10 |
| 088 | Agent Surface Transport Seam — Telegram / PWA / P2P around the user:prompt seam |
Proposed | 2026-07-12 |
| 089 | Plugin Citizenship & Governance (umbrella index over 020-024) | Proposed | 2026-07-12 |
| 090 | Streaming & Stream Transport (saga index over 053-055) | Accepted | 2026-07-12 |
| 091 | Tractor Runtime (saga index over 047/048/059/060) | Accepted | 2026-07-12 |
| 092 | Sovereign Identity Continuity (saga index over 032/034/035) | Proposed | 2026-07-12 |
| 094 | Node Context, Workspace Hatch, and Sovereign Home Resolution | Proposed | 2026-08-04 |
| 095 | Surface-Neutral Model Account Resolution | Proposed | 2026-08-06 |
These ADRs define architecture direction but are NOT executable contracts yet. Sprint 2+ implementation required.
Plugin-governance cluster (020-024): read ADR-089 — the umbrella index that names each mechanism (versioning, self-healing, policies, conflict detection, locks) and points at its owning ADR + blocker.
| ADR | Title | Status | Target | Blockers |
|---|---|---|---|---|
| 020 | Sovereign Graph Versioning (commit/branch/checkout/revert) | Proposed | v0.2.0-0.3.0 | 30+ invariant tests + kernel implementation |
| 021 | Self-Healing & Plugin Citizenship Monitoring | Proposed | v0.3.0+ | 40+ integration tests + kernel implementation |
| 022 | Policy Declarations in Plugin Manifests (+ Performance Budgets) | Proposed | v0.3.0+ | Manifest schema + PolicyManager + PerformanceMonitor implementation |
| 023 | Plugin Conflict Detection and Resolution | Proposed | v0.2.0-0.3.0 | ConflictDetector + GraphMonitor + UI implementation |
| 024 | Pessimistic Editing Modes (Locks via Private Branches) | Proposed | v0.3.0+ | LockManager + UI patterns + merge strategies implementation |
| ADR | Title | Target | Status |
|---|---|---|---|
| 004 | Identity Provider Choice (Nostr) | v0.2.0 | Planned |
| 011 | Plugin Marketplace (NIP-89/94) | v0.4.0 | Planned |
| 014 | Model Selection Criteria (size, performance, licensing) | v0.3.0 | Planned |
| 038 | Number reserved — scope TBD | — | Reserved |
| 039 | Number reserved — scope TBD | — | Reserved |
Note: Planned ADRs are reserved numbers for upcoming decisions. They will be created when their milestone begins.
Priority: Keep planned ADRs aligned with milestones and avoid duplicating accepted ADR numbers.
| ADR | Title | Superseded By | Reason |
|---|---|---|---|
| 003 | CRDT Choice (Yjs) | 045 | Adoption of Loro CRDT for better cycle-safe tracking, snapshot support, and a unified Rust-core. |
| 027 | Compositional Plugin Architecture & Headless DSL | 086 | providesApi/requiresApi replaced by the "One Verb, N Natures" model (086) + surface projection (085); Headless DSL absorbed by 016. |
| 028 | CRDT-SQLite Convergence Strategy | 045 | Loro realizes the same op-log/materialized-view target natively; the manual HLC/materializer design is historical (031 lists it "Strategy A legacy"). |
| 041 | Sovereign Environments & Workspace Isolation | 071 | Workspace Namespace Policy is the shipped realization of workspace isolation (Vault-Based Namespacing superseded). |
| 050 | Zig Host + ClojureWasm Guest (exploration) | 059 | Runtime direction settled on Rust tractor as authoritative host (059) + WASM surface substrate (070); exploration not pursued. |
Refined (still binding, but read the newer ADR for the current form): 017 → 025 (boot model); 019 → 069 (scope canonicalization); 048 → 059 (Rust becomes authoritative).
- Copy template.md
- Rename to
ADR-XXX-brief-title.md - Fill in all sections
- Submit for review
- Update this index when accepted