docs(architecture): ADR-007 — two kv engines (sqlite + postgres) behind one trait

Dissolve OQ-10's circular "standing offer" framing and record the
engine decision the POC evidence already supported:

- ADR-007 (new): kv tier ships sqlite (default) + postgres (feature
  `postgres`, default-off), constructor-selected per node; records the
  deployment economics (classical kv+fs+relational downstream stack
  collapses to one relational engine + fs), the pg impl contract
  (POC #5 B5 posture deltas), the CI sweep-safety gate under
  --all-features, redb ruled out (POC #6), and posture defaults as
  deferred cost in the ADR-006 pattern
- ADR-003: amended status (engine pin widened by ADR-007); kv entry
  notes the widened engine set
- ADR-004: reconciliation note — the "two backends" count is tiers,
  not engines
- backends-and-dispatch.md: tier≠engine distinction, pg engine
  section, co-tenancy note (same-file consumer writes share sqlite's
  single-writer ceiling), substitution-door precedent
- open-questions.md: OQ-10 resolved-by-ADR-007, with the
  why-this-is-not-Schrödinger's-code record (a deployment running
  alkblobs cannot pre-exist the pg engine — OQ-09 precedent); parked
  index narrowed to OQ-07/OQ-08
- overview.md: layer map + dependency posture reflect the `postgres`
  feature; README.md: ADR-007 in tables + corollary applications
- phase-0.md / pg+redb findings: promotion + supersession notes

Trigger framing survives only as deployment guidance (which engine a
node chooses — topology, not throughput), not as a gate on the crate's
own work.

Verified: cargo test, clippy --all-targets -D warnings, fmt --check.
Docs-only change (Phase 1 architecture); no implementation yet.
This commit is contained in:
glm-5.3-flash committed 2026-10-02 19:29:42 +00:00
1 parent 1af9399900
commit 395d58cf3f
10 files changed
+369 -100

No files matched your search

+12
View File
@@ -617,6 +617,18 @@ self-contained POC runs as a standalone crate in the global workspace
with findings written into `docs/research/` here. Findings always land
in `docs/research/` regardless of where the code lives.
Post-convergence promotion (2026-10-02, Phase 1): #5's pg engine case
and #6's redb guardrail became an accepted decision — ADR-007 (two kv
engines: sqlite default + postgres feature-gated, behind one trait,
constructor-selected; "two backends" counts tiers, not engines). An
interim framing recorded in OQ-10 (postgres as an externally-owned
"standing offer" opening on a first multi-tenant replicator
deployment) was caught at review as circular hedging — the trigger
was a fact only this crate could create — and dissolved on the same
reasoning as the Schrödinger's-code rule's README corollary (the
OQ-09 precedent). The POC evidence needed no strengthening; only the
decision's recording did.
## Convergence
Phase 0's final step per `docs/sdd_process.md`: *converge on a
+33 -12
View File
@@ -238,12 +238,14 @@ a deployment running the *fs tier anyway* has none of either cost.
differences (synchronous_commit posture, pooling discipline,
autovacuum surface, ~40× storage floor) are the ADR content any
postgres Backend impl would carry.
- **No ADR action recommended from a single POC.** The decision is
Phase 1's when a replicator-shaped consumer exists to measure against;
this POC's register entry is the evidence input, not a recommendation.
SQLite stays the pinned shipped engine (single-node economics, no
daemon to run, zero-ops); postgres is the *named future ADR* if the
multi-client replicator shape materializes.
- **Decision status (as originally recorded): no ADR action from a
single POC at the time of writing** — sqlite stayed the pinned
engine, postgres the named candidate. *Amended 2026-10-02:* the
decision has since been made on the accumulated evidence of this
POC + POC #6 (with POC #3's A4 sqlite baseline) — ADR-007 ships
postgres as the kv tier's second engine (feature-gated,
constructor-selected); this section's measured content above stands
as the ADR's evidence base.
- **OQ-BL-02 residuals**: unchanged in substance. The one new residual:
if a postgres Backend were adopted, its GC-sweep implementation is
`TRUNCATE`-friendly (whole-table dead-set rebuilds) but the
@@ -253,7 +255,8 @@ a deployment running the *fs tier anyway* has none of either cost.
## Engine deployment posture (recorded 2026-10-02 — the two-engine story, post-POC #4/#6)
The three alkblobs-relevant git/vfs use cases, mapped onto the measured
curves; this is the conclusion OQ-10 carries:
curves; this was the conclusion OQ-10 carried before its resolution
in ADR-007):
| Engine | Covers | Evidence |
|---|---|---|
@@ -278,11 +281,29 @@ that are engine-blind. Work-above-the-trait (store core, GC mechanism,
ops, consumers) is written once; engine work parallelizes against the
fixed contract (two engines, one trait, same sweep-safety proof shape).
Sequencing (recorded in OQ-10): sqlite stays Phase 1's mainline; the pg
ADR opens on the deployment trigger, not before — building it earlier
would leave an impl with no first consumer to keep the sweep-safety
proof honest. The evidence base (this doc + POC #6's redb guardrail) is
complete and waiting.
The deployment economics paragraph this table encodes, now stated
outright (recorded in ADR-007): the classical downstream stack — a git
server, a vfs node — needs three storage systems (kv + fs + relational);
this design collapses the kv into the relational engine, so a node
provisions **one relational engine + fs**, and which relational engine
is the operator's per-node choice among the shipped engines.
Sequencing (amended 2026-10-02 by ADR-007): postgres **ships** as the
kv tier's second engine (feature `postgres`, default-off),
constructor-selected per node — sqlite stays the default and Phase 1's
mainline; the pg impl is normal Phase 1 implementation work,
parallelizable against the fixed contract (two engines, one trait,
same sweep-safety proof shape, CI-gated via `--all-features`). The
earlier framing here and in OQ-10 — a "standing offer" whose ADR
opens on a first multi-tenant replicator deployment — was caught at
review as circular hedging: such a deployment runs alkblobs, so it
cannot cross the trigger until the pg engine ships, which the trigger
then forbids shipping. Superseded by
[ADR-007](../architecture/decisions/007-two-kv-engines-sqlite-and-postgres.md),
which records the decision this POC's evidence supports; the
deployment-trigger rule survives in corrected form as deployment
guidance (which engine a *node* chooses — ADR-007's decision rule),
not as a gate on the crate's own work.
## POC quality notes
+7 -5
View File
@@ -205,11 +205,13 @@ go up.
- **Reads: no case for redb on merit** — page-cache reads are what any
of these give the large tier for free; sqlite's 19 µs probe was
already fine.
- **ADR action: none.** SQLite's pin now has four-way triangulated
evidence (POC #3 fs, POC #4 pg, POC #6 redb, plus the lineage
citation). If a future consumer wanted redb-shaped durability
trade-offs (ephemeral cache tier), that's a *different* tier than
the kv engine slot.
- **Anti-recommendation adopted (ADR-007, 2026-10-02): redb stays
ruled out** — recorded in the decision so the question does not
reopen implicitly. SQLite's engine pin now has four-way triangulated
evidence (POC #3 fs, POC #4/#5 pg, POC #6 redb, plus the lineage
citation), and ADR-007 ships the kv tier as sqlite + postgres. If a
future consumer wanted redb-shaped durability trade-offs (ephemeral
cache tier), that's a *different* tier than the kv engine slot.
## POC quality notes