docs(architecture): OQ-10 — postgres as the second shipped kv engine, a standing offer on a deployment trigger
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.
This commit is contained in:
1 parent
5eea656295
commit
1af9399900
2 files changed
+87
-2
No files matched your search
@@ -31,8 +31,8 @@ make before shipping. Phase 0's residual list was swept under this
|
||||
rule: every residual either resolved into an ADR (the evidence was
|
||||
already in hand) or re-owned as below.
|
||||
|
||||
**Index of active OQs:** OQ-07, OQ-08 (externally-owned, carried for
|
||||
visibility). OQ-09 is resolved (recorded below). Promoted Phase 0
|
||||
**Index of active OQs:** OQ-07, OQ-08, OQ-10 (externally-owned, carried
|
||||
for visibility). OQ-09 is resolved (recorded below). Promoted Phase 0
|
||||
questions OQ-BL-01..06 are recorded here with their resolutions for
|
||||
traceability.
|
||||
|
||||
@@ -77,6 +77,56 @@ traceability.
|
||||
liveness seams (ADR-003/004/005) without baking an alkfs shape in.
|
||||
- **Cross-references**: OQ-07, ADR-004
|
||||
|
||||
### OQ-10: Postgres as the second shipped kv engine
|
||||
|
||||
- **Origin**: `docs/research/poc-postgres-kv-findings.md`,
|
||||
`poc-redb-kv-findings.md`, [backends-and-dispatch.md](backends-and-dispatch.md)
|
||||
- **Status**: externally-owned (the deployment trigger) — carried here
|
||||
as a standing offer, not a blocker
|
||||
- **Priority**: medium-high (the evidence base is done; only the
|
||||
deployment trigger is outstanding)
|
||||
- **Owner**: whichever consumer deployment crosses the trigger
|
||||
(per OQ-07: alkgit's replicator is the named candidate)
|
||||
- **Question**: when a replicator-shaped deployment materializes
|
||||
(multi-tenant public node: many users pushing, gossip catch-up, bulk
|
||||
ingest), open the postgres-kv ADR. The measured case for it:
|
||||
sqlite's WAL single-writer ceiling is ~1.2k objects/s under
|
||||
contention and *flatlines* (latency climbs without bound under
|
||||
overload) while postgres scales out to ~28-37k puts/s across
|
||||
workers with group-commit amortization (POC #5 findings B3/B4);
|
||||
single-user/private/small-replicator nodes stay sqlite by
|
||||
measurement (POC #5 A4/B1). Also settled by the same POCs: redb is
|
||||
ruled out (POC #6 — its durability API cannot express the shipped
|
||||
WAL-NORMAL-tier: crash-consistent without per-commit fsync), and
|
||||
the trigger is **topology, not throughput** — cross-MACHINE write
|
||||
access to one pool is the condition that makes postgres mandatory
|
||||
rather than merely faster.
|
||||
- **Shape of the work when triggered** (per-node choice is a
|
||||
constructor parameter, per ADR-003/004; the impl is parallelizable
|
||||
against the fixed contract — two engines, one trait):
|
||||
1. `PgKv` backend impl (~180 lines, POC #5 scaffold exists)
|
||||
with the engine-posture deltas POC #5 finding B5 named:
|
||||
per-pool `synchronous_commit` posture, pooled-connection +
|
||||
prepared-statement discipline (prepared statements die with
|
||||
sessions), autovacuum tuning for a churning CAS table,
|
||||
fillfactor, ~40× storage overhead accepted as the small-tier
|
||||
cost;
|
||||
2. the sweep-safety proof ADR-003's admission gate requires:
|
||||
`list()` as a stable `SELECT key` cursor over a vacuuming table
|
||||
(MVCC-ghost stability across a long sweep), batch-delete via
|
||||
`key = ANY($1)`, exact-count sweep-outcome tests (the POC #1
|
||||
finding-2 gate applied to pg);
|
||||
3. consumer-layer note: honker's notify/queue/stream features ride
|
||||
sqlite's file; the pg deployment's parity stack is
|
||||
`LISTEN`/`NOTIFY` + pgboss-rs (honker's own README points
|
||||
postgres users that direction) — a deployment concern, not a
|
||||
store-crate one.
|
||||
- **Resolution**: none — waiting on the deployment trigger. The ADR
|
||||
opens the day a real replicator consumer exists to keep its
|
||||
sweep-safety proof honest; building it earlier would leave an impl
|
||||
with no first consumer.
|
||||
- **Cross-references**: OQ-07, ADR-003, ADR-004, POC #5, POC #6
|
||||
|
||||
---
|
||||
|
||||
## Theme: ops surface
|
||||
@@ -186,6 +236,7 @@ traceability.
|
||||
|---|---|---|
|
||||
| OQ-07 | externally-owned | alkgit's architecture process (answerable on paper anytime; gates nothing here) |
|
||||
| OQ-08 | externally-owned | alkfs Phase 0 intake |
|
||||
| OQ-10 | externally-owned (standing offer) | the first multi-tenant replicator deployment (POC #5 is the ready evidence base; the ADR opens on the trigger) |
|
||||
|
||||
OQ-09 was `deferred(scope)` on the first embedded ops deployment — a
|
||||
deciding fact that could only exist once the ops module ships, i.e. a
|
||||
|
||||
Reference in new issue
Block a user