- requirements.md (new): the three use cases pinned as REQ-1..4 with
the node/pool/fleet/engine vocabulary defined once — ends per-session
re-derivation of consumer facts. REQ-2 (replicator fleet over one
shared pg pool, incl. large-blob serving) is recorded as a planning
fact predating all POCs, on the operator's authority.
- ADR-008: Backend trait gains size(key) length probe (before any
backend ships data — ADR-002 one-way-door discipline); fleet GC
mechanism (DB-backed pin rows committed atomically with entries,
TTL+renewal semantics, liveness = embedder-owned table, protect
callback is single-node-only, advisory-locked single sweeper,
staged re-arbitrated delete window on both engines); fs tier becomes
engine-selectable (local default; pg-lo named candidate) with the
fleet locality contract (shared media or re-routing; mixed tiers are
a documented deployment invariant, not a constructor-provable one).
- poc-pglo-spec.md (new): POC #7 spec — pg Large Objects as the fs
tier's pg-lo engine; instruments, decision gate, registered in
phase-0.md OQ-BL-06.
- ADR-003/005 status amendments point to ADR-008's extensions; specs
ripple (backends/store-api/gc/ops/overview/README).
- open-questions.md: deferral-policy header gains the decisions-vs-
sequenced-work distinction; pg-lo's why-not-parked audit trail
recorded.
- research fixes: postgres POC renumbered #4->#5 to the canonical
register (phase-0 OQ-BL-06), redb cross-refs fixed, thinking-
artifact sentence in B1 replaced with the honest reading.
Verification: docs-only change; reference-integrity sweep across the
tree (ADR/REQ/POC refs resolve); architecture-reviewer pass on the
delta — original 3 criticals addressed, its follow-up (fleet liveness
form, pin TTL, staged-delete semantics, enforceability, shared-media
caveats) fixed in this commit.
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.
Records the two-engine story the POC #5/#6 round established, in the
terms this crate's boundary uses (engine, not backend; trait contract
as the admission gate):
- OQ-10 (externally-owned standing offer): open the postgres-kv ADR
when a multi-tenant replicator deployment materializes. Trigger is
topology, not throughput — cross-machine write access to one pool
(throughput pressure / sqlite's flatline is the early warning).
Names the trigger-time work: PgKv impl + engine-posture deltas
(synchronous_commit, pooling/prepared-statement discipline,
autovacuum, ~40x storage overhead) + the sweep-safety proof
(vacuum-stable list() cursor, exact-count sweep tests). Sequenced:
sqlite stays Phase 1 mainline; evidence base is done and waiting.
- poc-postgres-kv-findings.md: engine deployment posture section —
the three use cases (self-hosted git serving, p2p replicator nodes,
agent-workspace pools) mapped onto the measured curves; per-node
choice as the form of the fork; honker parity stack named for the
pg side (LISTEN/NOTIFY + pgboss-rs, deployment layer).
No code changes; engine work parallelizes against the fixed contract.
Post-convergence engine studies against the ADR-003 kv pin, using
POC #3's harness unchanged (sqlite/fs arms byte-identical) plus the
concurrency axis POC #3 never measured:
- #5 postgres (B1-B6): solo pg floor ~1 ms (fsync-dominated, strace-
decomposed), ~40x storage overhead; decisive scale-out — pg PUTs ~12x
at 12 conns / ~37k ops/s while sqlite flatlines at its ~1.2k WAL
single-writer ceiling. Viable future ADR for the multi-client
replicator shape; durability/ops posture change, not a drop-in.
- #6 redb (C1-C6): the "2-7x over sqlite" folklore inverted — sqlite
~430x over redb at crash-consistent puts (redb Immediate = 1
fdatasync/commit, 8-30 ms on this disk; its None tier is not
crash-consistent). Reads ~530k/s but irrelevant. Ruled out at a
durability-tier mismatch: WAL-NORMAL's shipped tier is not
expressible in redb 4.x's two-level API.
- Net: sqlite's pin now has four-way triangulated evidence (fs vs
sqlite #3, pg #5, redb #6, lineage citation); batched commits proven
as the universal lever across all three engines.
Code: /workspace/alkblobs-postgres-poc, /workspace/alkblobs-redb-poc
(standalone crates per the POC placement convention; 14 inherited
tests passing in each, clippy -D warnings + fmt clean).
Verification: no src/ changes — docs only; both POC crates verified
(test/clippy/fmt) with findings recorded above.
glm-5.3-flash