docs(architecture): ADR-009 — pg-lo admitted as the fs tier's second engine on POC #7

- ADR-009 (new): postgres Large Objects ship as the fs tier's second
  engine (feature pg-lo, default-off), admitted on POC #7's passed
  gate (contract 10/10, durable put ~= fs at >=1 MiB, lo_get window
  gets, transactional LO lifecycle = zero crash orphans). Engine
  shape: companion table (lo_entries) is the contract authority; put =
  one tx (lo_create + lowrite + row + pin); get = descriptorless
  lo_get windows (lo_*64 discipline); named operator deltas (catalog
  space never returned / autovacuum inherited / sweep for the legacy
  bypass class only) and named performance deltas (cached-get 20-50x
  behind page-cache fs single-stream, ~700 MB/s aggregate at 16
  readers = the fleet serving picture).
- Ripple: backends-and-dispatch (pg-lo shipped; fleet locality
  contract gains the whole-fleet-pg-lo option), overview (layer map,
  feature table + pg-lo row, OQ -> shipped pointer), requirements
  (engine def + REQ-2 note updated), README (current-state + ADR
  table), store-api (invariant 1/6 engine lists), ADR-008 Status
  amendment (pg-lo posture superseded by ADR-009), open-questions
  (audit trail completed: decided -> sequenced -> completed).

Verification: docs-only; all cross-references resolve (ADR/REQ/POC);
register, findings, spec, and both engine-ADR status lines agree.
This commit is contained in:
glm-5.3-flash committed 2026-10-03 04:30:31 +00:00
1 parent cee97defba
commit 9bbe6f3ad9
8 files changed
+226 -39

No files matched your search

+7 -5
View File
@@ -70,7 +70,8 @@ or three times.
│ │ ADR-007: kv = 2 engines;
│ ▼ ADR-008: fs engines too)
│ engine per node: sqlite (default) | postgres (feature "postgres")
│ fs engine per node: local (default) | pg-lo (candidate, POC #7)
│ fs engine per node: local (default) | pg-lo (feature "pg-lo",
│ default-off; ADR-009)
transport: none, anywhere. alkgit/alkfs or the embedder dials;
an alkcall Connection is handed in at the ops boundary.
@@ -82,6 +83,7 @@ or three times.
|---|---|---|
| base crate (store core + backends) | `tokio`, `thiserror`, `parking_lot`, plus `rusqlite` behind the `kv` feature and nothing behind `fs`/`mem` | no alkcall, no serialization frameworks |
| `postgres` feature (ADR-007) | adds `tokio-postgres` + `deadpool-postgres` behind the kv tier's second engine, default-off | depends on `kv`'s contract surface (the `Backend` trait definition is base-crate code); the engine's *impl* is additive. Same `Backend` contract, own sweep-safety CI gate under `--all-features` |
| `pg-lo` feature (ADR-009) | Large Objects as the fs tier's second engine, default-off | rides the same `tokio-postgres`/`deadpool-postgres` stack as the `postgres` kv engine (SQL `lo_*` functions, no new dependency); same admission/test-gate shape |
| `ops` feature | adds `alkcall` (feature-gated, default-off) | JSON op specs + binary channels + `AccessControl`; ADR-001 |
| consumer crates | depend on alkblobs (and on alkcall directly when they speak ops) | alkgit, alkfs |
@@ -126,6 +128,7 @@ wasm-clean), never an in-process embedder (ADR-001 §Consequences).
| [006](decisions/006-verification-posture-and-transfer-encoding.md) | Verification posture | whole-blob verification; chunk trees excluded by scoping |
| [007](decisions/007-two-kv-engines-sqlite-and-postgres.md) | Two kv engines | sqlite default + postgres behind one trait; one relational engine + fs per node |
| [008](decisions/008-trait-size-probe-fleet-gc-and-fs-engines.md) | `size` probe + fleet GC + fs engines | trait length probe; fleet pins/sweeps engine-backed; fs tier engine-selectable |
| [009](decisions/009-pg-lo-fs-tier-engine.md) | pg-lo fs engine | postgres Large Objects as the fs tier's second engine, admitted on POC #7; a fleet node can run postgres-only |
## Open Questions
@@ -140,10 +143,9 @@ crate level:
open-read requirement)
- **OQ-10**: second kv engine — resolved by ADR-007 (sqlite + postgres
shipped behind one trait; per-node constructor choice)
- **POC #7** (`docs/research/poc-pglo-spec.md`): pg Large Objects as
the fs tier's `pg-lo` engine — spec'd **sequenced work** (not a
parked question; open-questions.md's policy header distinguishes the
two): admission evidence for ADR-008's named candidate (REQ-2)
- **POC #7** (`docs/research/poc-pglo-findings.md`): pg Large Objects
as the fs tier's `pg-lo` engine — **passed** 2026-10-03; admitted as
a shipped engine by ADR-009 (REQ-2's consolidation option)
## References