Architecture Decision Records
Registry of non-obvious architectural decisions made in synapse.
| ADR | Title | Status |
|---|---|---|
| 001 | Rust 1.85 + edition 2024 as floor | Accepted |
| 002 | MCP via official rmcp 1.7 | Accepted |
| 003 | rusqlite 0.39 with bundled feature | Accepted |
| 004 | YAML via serde_yaml_ng (serde_yaml/serde_yml banned) | Accepted |
| 005 | Git hooks via core.hooksPath | Accepted |
| 006 | MSRV policy: piso 1.85, subida via ADR | Superseded by 009 |
| 007 | Release pipeline: git-cliff + dist + cargo-release | Accepted |
| 008 | Embedding backend (fastembed-rs + BGE-M3 default) + vector storage (sqlite-vec) + NER backend (GLiNER-multi) for v0.5: supersedes the tentative release-pipeline reservation from ADR-007 §Consequences | Accepted |
| 009 | Subir MSRV para 1.88 (ecosystem floor real) | Accepted |
| 010 | Workspace federation: leve, opt-in, registry-based | Accepted |
| 011 | Workspace freshness: advisory git remote drift detection | Accepted |
| 012 | Provenance frontmatter (x-ai-*) on AI-authored entities | Accepted |
| 013 | .synapse/audit.ndjson format + retention policy | Accepted |
| 014 | Portable identity bundle (me.synapse) | Accepted (prototype) |
| 015 | File-size threshold + modular split policy (yellow 500-800 / red 800+) | Accepted |
| 016 | Portable identity v2: mandatory ed25519 + revocation | Accepted (supersedes ADR-014 §v0.3 non-goals) |
| 017 | Curriculum schema: attested_involvement + skills + CV format | Accepted |
| 018 | LSP companion via tower-lsp-server 0.23 (active fork) | Accepted |
| 019 | Terminal styling via anstream + anstyle; rich-by-default, --plain opt-out | Accepted |
| 020 | Self-identity: capture once globally, seed the self person per workspace | Accepted |
| 021 | TTY progress via indicatif, gated by is_rich() (stderr, hidden off-TTY) | Accepted |
| 022 | Evolve the propose/accept gate (BR-12.3) into a confidence-tiered write policy | Accepted |
| 023 | Read-only query tool: structured aggregation, no raw SQL (injection/exfiltration-proof) | Accepted |
| 024 | SYN-185: batch approval over syn pending (accept/reject --all), not a syn agent runner | Accepted |
| 025 | SYN-220 syn capture --from-git: harvest people+project (not decisions) as proposals; bot-filtered, idempotent | Accepted |
| 026 | SYN-239 two-tier tamper-evident audit: git-versioned per-author segments → Merkle DAG; unversioned → self-chained + ed25519 signed checkpoint | Accepted |
| 027 | SYN-223 bitemporal: store valid-time only (x-valid-* + x-supersedes); transaction-time from git; supersession = invalidation | Accepted |
| 028 | SYN-234 open entity types via .synapse/types.toml validation registry (closed-world, ADR-023-safe); EAV for indexed fields | Accepted |
| 029 | SYN-241/245 deterministic per-fact trust (WPM: Confidence × Freshness × Supersession × Provenance); mutual-kNN edge weight | Accepted |
| 030 | SYN-249 git as integrity substrate + ed25519 identity bound to SSH-format git commit signing; recommend-and-verify default | Accepted |
| 031 | SYN-223 belief-time axis (x-recorded-at/x-invalidated-at): third axis distinct from git transaction-time; deterministic supersession (invalidation-not-deletion). Amends ADR-027 | Accepted |
| 032 | SYN-254 per-type identity fields → deterministic duplicate detection routed to the gate (detect-don’t-merge); never derives the id from the hash; identity ⊆ indexed. Extends ADR-028 | Accepted |
| 033 | SYN-248 per-type policy reshaped to the profile-vs-log decay axis ([policy.<kind>] decay); advisory only, never bypasses the gate. Extends ADR-029/028 | Accepted |
| 034 | SYN-249C scope: doctor reports HEAD commit signature posture (dep-free); cryptographic SSHSIG verification (ssh-key dep) deferred to multi-user/Commercial, not smoke-testable here. Scopes ADR-030 | Accepted |
| 035 | SYN-262 syn verify foundation: canonical logical dump (hash the reproducible logical manifest, not the non-deterministic .db; exclude FTS/pending/ledger/vectors/mentions:* enrichment) + signed synapse.verify-report/1 in-toto schema (reuses SYN-247 ed25519). Companion to ADR-026/027/030 | Accepted |
| 036 | SYN-266 verify-first: audit-log replay-to-store is unsound (hash-only log, non-journaled wall-clock, state-based editable-Markdown store). Reframe INV-4 to replay determinism (provable; clock seam via pin_clock) + reconstruction is INV-1/INV-7, not replay. verify --deep = bounded journal-integrity check, not store reconstruction. Amends ADR-027 | Accepted |
| 037 | SYN-270 syn audit witness (signed synapse.audit-witness/1: git HEAD + per-author segment prefixes) + verify --since INV-12: prove history is an append-only extension (git ancestry + prefix stability), offline, dep-free. Closes the force-push/rewrite gap ADR-026/030 left to a remote. Tamper-evident, not tamper-proof | Accepted |
| 038 | SYN-276: ship v1.0 on ort = 2.0.0-rc.12 (transitively forced by fastembed + the gliner fork) with a tracked exit to ort 2.0.0 final once upstream supports it; the “stable” promise scopes the Synapse surface (schema/CLI/MCP), not the transitive ML runtime. Scopes ADR-008 | Accepted |
| 039 | SYN-287 syn undo: Phase 1 reverses a capture_fact create by removing the entity (payload-derived, works uncommitted); state-mutating kinds refuse until Phase 2 (git-restore / pre-image). Never replays the audit log (ADR-036); CLI-only (human corrective, not an agent self-undo tool); atomic + audited + conflict-guarded | Accepted |
| 040 | SYN-290 benchmark methodology contract (checksummed corpus, median/p95/p99, machine stamp, stub=latency / real=quality, publish raw + reproduce) + charts via a hand-rolled deterministic SVG writer (no charting dep; only sha2 added); poloto/vl-convert/hyperfine documented alternatives. Extends synapse-bench | Accepted |
| 041 | SYN-298 agent-in-the-loop benchmark driver: drive with raw claude -p headless (stream-json trajectory + total_cost_usd, SYN-297 three-gate recipe, zero new dep) now; adopt the Claude Agent SDK later (a non-Rust sidecar) when a fully-unattended fleet / programmatic connect-status is needed. Owner-run; reliability via N≥5 runs → pass@1 + pass^k keyed on the syn verify dump digest. Companion to ADR-040 | Accepted |
| 042 | SYN-301 retrieval quality: attack the measured recall@1 ~0.78 with (1) deterministic structure-aware chunked embeddings (passage-granular vectors, best-chunk pooling; no ML segmenter) and (2) a cross-encoder reranker (bge-reranker-v2-m3 on the shared ort/fastembed copy, no new backend) over the RRF shortlist. Ranking-only (never trust/gate/supersession); disposable-index; benchmark-gated (ship only on a persona-bench --features real recall@1 win). Rejects TF-IDF/LSA (redundant), TextTiling/semantic-chunk (non-deterministic), external rerank API (local-first), K-Means (opaque). Extends ADR-008, composes ADR-029 | Accepted |
| 043 | SYN-303 governed capture from agent-supplied context: Synapse composes the MCP ecosystem, it does not build calendar/Slack/ticket connectors. Steer the agent (via tool descriptions + instructions, not auto-firing prompts; no server sampling: deprecated/SYN-219) to enrich proposals from context it already has, and govern the enriched write with hard invariants: enriched ⇒ never auto_apply=safe/accept --all (closes the auto-linked-mislink hole), structured-field whitelist, no raw external data persisted, provenance = agent-asserted source-class only, redactable, verify-honest. Reframes SYN-206 as compose-not-integrate; complementary/defensive, sequence after SYN-271/SYN-254; v1.3 or fold into SYN-284. Composes ADR-025/022/012 | Accepted (MVP) |
| 044 | SYN-306 composite/parallel search + deterministic relevance calibration: independent legs (FTS, vector) run concurrently on their own connections (deterministic fusion), the SYN-304 per-hit signal becomes a bounded [0,1] compatibility score (leg agreement + rank position). persona-bench --features real k-sweep {20,40,60} showed recall@1 identical at every k (0.85 final) → kept the canonical k=60; weighted-RRF stays equal (no per-leg bias). Rejects RSF/DBSF, global title>body field weighting, FTS5 k1/b tuning, learned LTR. Extends ADR-042, composes the SYN-86 RRF | Accepted |
| 045 | SYN-307 on-device retrieval-model policy: add models only behind a permissive-licence gate + ort/fastembed substrate gate + a persona-bench win. E5-class needs an asymmetric query:/passage: embed seam (fastembed does not auto-prefix); EmbeddingGemma-300M is opt-in-only (Gemma licence + gated repo); Qwen3-Embedding deferred (no ONNX); MRL truncation is per-model, BGE-M3 exempt; the discarded BGE-M3 sparse output is a separate spike. Rejects SPLADE (non-commercial) and a second native backend. Disposable-index only. Extends ADR-008/042 | Proposed |
| 047 | #288 multi-project brain: the catalog (federation registry, syn ws) + syn mcp --workspace (#287) + attributed federated reads ship today (phases 1–3). The always-on resident daemon (OS auto-start, persistent process, catalog-driven discovery) is deferred behind its own future ADR: large OS-specific infra + a new security/IPC model (composes SYN-235), not a v1.x code drop. Follow-up SYN-317 | Accepted |
| 048 | #160 (SYN-194) keep enrichment synchronous (BR-13 enrich-before-commit). Async / eventual-consistency stays trigger-gated: build only on a measured p95 write regression past the budget. Disposability backfill (reindex --relink + embed --all, ADR-046) lowered the pressure. No async scheduler ships now | Accepted |
| 046 | SYN-315 (#289) bitemporal field corrections: an update_status in-place edit records valid-time at the field level (x-field-history frontmatter → entity_field_history table), so --as-of <before> reconstructs the prior value while the entity stays visible on both sides. Rejects stamping x-valid-until on the corrected entity (breaks post-correction visibility), a shadow-entity snapshot (id-namespace pollution), and reframe-only. Disposable (reindex rebuilds it from Markdown), verify-honest. Extends ADR-027/031 | Accepted |
| 049 | Composable knowledge framework and source revision adapters | Accepted (design) | | 050 | Typed probabilistic diagnostics with abstention | Accepted (design) | | 051 | Sealed transitions, source drift and independent witnessing | Accepted (design) | | 052 | Persisted receipts and explicit verification profiles | Accepted (design) | | 053 | OIDC subject/key binding and scoped authority | Accepted (design) |
New ADR? Copy template.md, name NNN-kebab-case-title.md,
keep one decision per file, link it in this index.
| 054 | Maintained YAML backend and compatible security patches (SYN-330) | Accepted |
| 055 | Cryptographic Git signatures and pinned local trust | Accepted | | 056 | Durable workspace prepare/commit and bounded recovery | Accepted | | 057 | Governed Markdown suffix and independently retained witnesses | Accepted |
| 058 | Recoverable native receipts and explicit local assurance; team authority stays pending | Accepted |
| 059 | Shared pure scoped device evidence and explicit offline identity verification | Accepted (binding component) |
| 060 | Current event-bound shared admission and expected heads | Accepted (protocol component) |
| 061 | Pinned Memory CI policy and separate proof dimensions | Accepted |
| 062 | Scoped exact diagnostics and unambiguous supersession | Accepted |
| 063 | Versioned bounded knowledge process contract | Accepted |
| 064 | Independently pinned commit roster revisions | Accepted |
| 065 | Native shared source sealing through an authenticated host | Accepted (native component) |
| 066 | Historical team assurance and original seal witnesses | Accepted (verifier component) |
| 067 | Frozen native source candidates before shared review | Accepted (native component) | | 068 | Scoped read-only provider execution and failed initial model default gates | Accepted (experimental adapters) | | 069 | Explicit current Git/Markdown and GitHub revision acquisition with access boundaries | Accepted | | 070 | Access-filtered source lineage, explicit review candidates and guarded local native annotation acceptance | Accepted (shared reads/local acceptance) | | 071 | Guarded retained pending rejection and exact operator review | Accepted |
| 072 | Bundled pinned Mermaid preprocessing and local runtime for documentation diagrams | Accepted (browser acceptance pending) |