docs(architecture): ADR-010/011 — I/O seams, GC-state home, vocabulary; pre-decomposition consistency round
ADR-010 (new): the Backend trait's I/O seams pinned before any code — 'get' returns a crate-internal read cursor (kv engines materialize; 'local' pread loop; pg-lo lo_get windows), 'put' has two named forms (whole-value kv / staged-put large); GC state is store-core-owned via a crate-internal contract-tested engine-state seam on the SQL-backed engines (backends never learn liveness — ADR-005 verbatim); the store core holds the joint entry+pin transaction (corrects ADR-009 §2's ownership statement); kv-tier fleet-validity rule added (mirror of ADR-008 §3); ops pin-token TTL race resolved (the token IS the pin; renewal rides have/re-put; pause-past-TTL falls to delete-then-recover); feature graph pinned (pg-lo does not imply postgres). ADR-011 (new): vocabulary pinned — tier (contract, exactly two) vs engine (concrete impl, exactly five); store instance / node / fleet split (fleet = pool-sharing, not node count — fixes requirements.md's self-contradiction with REQ-2); mem demoted from 'backend'/'testing tier' to the kv tier's third engine (contract-reference engine); fs tier renamed 'large' including the feature name (last free moment before code exists); constructor modes pinned (dual-tier default, kv-only, mem-only) plus the composite fleet-validity predicate. Consistency round across all specs and ADR-003/004/007/008/009: stale pg-lo passages resolved per ADR-009's supersession; ADR-008 owner 'node id' → store-instance id; threshold wording corrected (conservative edge, not midpoint, of the 128-256 KiB crossover zone); SweepReport shape specced; mem classification unified; 008/009 ADR files renamed to match the tier rename; README deferral-policy recap aligned (third category = decided-but-sequenced work, not a parking kind); POC crate list completed. Verification: two independent architecture review rounds (the first found 4 criticals — unpinned trait I/O shapes, missing fleet-state seam, node/fleet self-contradiction, pin-token/TTL conflict — all resolved; final round: zero criticals); all markdown links resolve; ADR tables complete (11 ADRs).
This commit is contained in:
1 parent
9bbe6f3ad9
commit
abf8c5ae9c
18 files changed
+1137
-336
No files matched your search
@@ -2,7 +2,9 @@
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
Accepted (the engine story's I/O seams and GC-state home are ruled by
|
||||
ADR-010; the vocabulary — tier/engine, and mem joining the kv tier as
|
||||
its third engine — is pinned by ADR-011)
|
||||
|
||||
## Context
|
||||
|
||||
@@ -57,9 +59,9 @@ in OQ-09.
|
||||
**The kv tier ships two engines — sqlite (default) and postgres —
|
||||
behind one `Backend` trait; engine selection is a constructor
|
||||
parameter on the backend's configuration.** A node provisions one
|
||||
relational engine plus the fs tier; the kv tier rides whichever
|
||||
relational engine plus the large tier; the kv tier rides whichever
|
||||
engine the operator chose. This collapses the classical three-engine
|
||||
downstream stack (kv + fs + relational) to two, and makes which
|
||||
downstream stack (kv + large content + relational) to two, and makes which
|
||||
relational engine a per-node choice rather than a crate fork.
|
||||
|
||||
1. **sqlite stays the default engine**: zero-ops, no daemon, solo
|
||||
@@ -83,7 +85,7 @@ relational engine a per-node choice rather than a crate fork.
|
||||
(`INSERT ... ON CONFLICT DO NOTHING` maps sqlite's
|
||||
`INSERT OR IGNORE`), complete `list()`, GC-participating `delete`,
|
||||
virgin-store no-op reads, namespace-blindness. The dispatch layer
|
||||
(size threshold, kv↔fs routing, fall-through) is engine-blind and
|
||||
(size threshold, kv↔large routing, fall-through) is engine-blind and
|
||||
unchanged.
|
||||
4. **The pg engine's impl contract carries POC #5 finding B5's deltas
|
||||
as requirements** (they are the difference between a port and an
|
||||
@@ -127,7 +129,7 @@ collapses to its own deployment choice among shipped engines.
|
||||
**Positive**
|
||||
|
||||
- The classical downstream stack lands at two engines per node (one
|
||||
relational + fs), eliminating the "sqlite *beside* the real
|
||||
relational engine + large tier), eliminating the "sqlite *beside* the real
|
||||
database" duplication this crate's consumers would otherwise carry
|
||||
forever.
|
||||
- Per-node engine choice (constructor parameter, per ADR-003/004)
|
||||
|
||||
Reference in new issue
Block a user