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:
1 parent
1af9399900
commit
395d58cf3f
10 files changed
+369
-100
No files matched your search
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in new issue
Block a user