Decision records for Codexa. Reference docs (architecture.md, llm.md, …) describe what the system is; ADRs record why it is that way, what was rejected, and what would trigger a revisit. ADRs 0003–0013 are retroactive: they document decisions already shipped, extracted from the codebase and its pinned docs.
| # | title | scope |
|---|---|---|
| 0001 | SD-12: split ingest (write) and serve (read) storage paths | storage isolation, generation publish |
| 0002 | Discovery and validation basis | product bets, assumption tests |
| 0003 | Chat pipeline / RAG orchestration: serial staged pipeline, not an agent loop | turn flow, stage composition, plugin anchors |
| 0004 | Offline-first: no default egress, enforced as an executable invariant | egress, telemetry, retention |
| 0005 | Strategy-registry dispatch over plain dict cfg | registries, cfg accessors, seam modules |
| 0006 | Two-process model: detached indexer + UI, advisory file lock | process topology, writer lock |
| 0007 | Indexer concurrency: parallel chunk lanes, one serial embed consumer | index-run concurrency, phases A/B/C |
| 0008 | LLM access: provider registry + fallback chain + deterministic local decoding | provider dispatch, probes, determinism |
| 0009 | Plugin system: entry-point discovery, deny-by-default loading, sandboxed dispatch | extensibility, supply-chain posture |
| 0010 | AppContext central lifecycle + six-point cache contract | caches, reset, invalidation |
| 0011 | Robustness posture: atomic writes, manifest-first recovery, soft-fail boundaries | crash-safety, degradation rules |
| 0012 | UI: Streamlit rerun model, background threads that never touch st |
UI framework, UI concurrency |
| 0013 | Saved sessions: repository port, JSON/SQLite backends, forward-compatible envelope | session storage, pending-save WAL |
| 0014 | Model fetch on first run is allowed by default (amends 0004) | model-download default, first-run UX |
| 0015 | SD-12b: serve staging when nothing is published; veto publishes on regressions only (amends 0001) | read resolution, publish gate |
| 0016 | Run the search turn on a worker, drive results from a polling fragment (amends 0012) | UI responsiveness during a turn |
| 0017 | Vector write path: measured cost model, shard sizing by population, and what a future backend must beat | dense write cost, shard layout, backend-change criteria |
| 0018 | Query snapshots and generation reclamation (amends 0001/0006) | whole-turn isolation, reader leases, generation GC |
| 0019 | Index scheduler: preserve two lanes and admit by measured resources (refines 0007) | chunk scheduling, worker admission, benchmark gates |
Which reference doc is the what for each decision's why. Every doc below links back here or to its ADRs directly.
| reference doc | governing ADRs |
|---|---|
| architecture.md | all (storage read/publish/lease rules → 0001/0015/0018) — per-section back-links: pipeline internals → 0003, two-lane indexing → 0006/0007, store backend → 0001/0018, LLM dispatch → 0008, UI execution → 0012/0013/0016, conventions → 0004/0005/0010/0011, plugins → 0009 |
| llm.md | 0008 (providers, fallback, determinism), 0003 (prompt contracts' place in the turn flow) |
| ui.md | 0012 (execution model), 0013 (sessions), 0003 (faith surfaces), 0006 (Index tab spawn/lock) |
| performance.md | 0007/0019 (indexer shape, scheduler admission), 0017 (dense write cost model, shard sizing), 0010 (cache contract), 0003 (intra-stage search parallelism) |
| semantics.md | 0003 (rerank stages, history compression) |
| wikipedia.md | 0004 (opt-in online tier) |
| privacy.md | 0004 (no-egress + retention), 0014 (model-fetch qualifier) |
| strategy.md | 0002 (validation basis), 0004 (durable advantage) |
| testing.md | 0004 (offline suite), 0005 (seam patching), 0010 (reset fixtures) |
| troubleshooting.md | 0011 (degradation entries), 0006 (indexer lock entries), 0018 (busy generation retention), 0010 (reset), 0012 (stall watcher), 0004/0014 (model-cache miss) |
| governance.md | 0004 (privacy posture context) |
| examples/plugins/word_counter | 0009 (deny-by-default enable step) |
- One decision per ADR; supersede rather than edit a decision that changed.
- Ground every claim in a code path or a doc section pinned by a drift test (DOC-7) — no aspirational architecture.
- New enrichment bets register their riskiest assumption + cheapest test in ADR 0002 before implementation.
- Change chains: when an ADR's subject has a defined edit ripple (e.g. pipeline stages in ADR 0003 §6), follow it — CI enforces the pinned links.