docs(tasks): decompose wave 5 — the pg-lo large engine, the window host's large-tier arm, the LO-medium SKIP-posture column
- engine-pg-lo: the Backend impl behind feature pg-lo (default-off) — companion-table authority, one-tx staged put at the 512 KiB knee, descriptorless lo_get windows, the orphan-recovery sweep, the posture deltas recorded; the shared-helper/PgOpts/LO-isolation design points named (LOs are database-level — the C7 lesson cited so it is not rediscovered) - engine-pg-lo-window: the EngineWindowState impl per ADR-012 §5's pg-lo row — gc_window only, no fleet family anywhere - store-pg-lo-construction: LargeEngine::PgLo slotting (the large sub-enum design point), the consolidation + mem-pglo constructors (the fleet-valid set completed, implicitly non-fleet), and the one-window-host rule's store-core completion (dormancy + the large-host sweep arm) - suite-column-pg-lo: the second SKIP-posture column, two factories spanning feature pairs, the dormancy row, zero LO residue in teardown - review-wave-5: the engine-wave gate; amendment A2 (janitor adoption) verified here Harness server cited in every server-touching task: dockerized pglo-poc (postgres:16-alpine) on :15432, db blobs, postgres/poc (verified live 2026-10-12); env-driven ALKBLOBS_PG_* settings, clean server-less skips, acceptance requires green against the server. Verification: cargo test 69/19/3 ok, clippy --all-targets -D warnings green, fmt --check green (docs-only change).
This commit is contained in:
glm-5.3-flash committed
1 parent
f3e8a88e2e
commit
5a217f7bc7
6 files changed
+785
-2
No files matched your search
@@ -0,0 +1,146 @@
|
||||
---
|
||||
id: suite-column-pg-lo
|
||||
name: Conformance suite — the pg-lo column (the LO-medium SKIP-posture column)
|
||||
status: pending
|
||||
depends_on: [store-pg-lo-construction]
|
||||
scope: moderate
|
||||
risk: medium
|
||||
impact: phase
|
||||
level: implementation
|
||||
tags: [wave-5, suite, pg-lo]
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
Grow the **pg-lo column** — the suite's second SKIP-posture column
|
||||
(README §SKIP posture: SQL-attached factories ride a server; when no
|
||||
server is reachable the column **skips cleanly** — a skip is not a
|
||||
failure — and the wave's acceptance requires green **against the
|
||||
server**). The column runs under feature `pg-lo` (default-off); its
|
||||
two factories span feature pairs — **the first column whose factories
|
||||
need different feature sets** (a recorded design point): the mem-pglo
|
||||
factory gates on `all(feature = "mem", feature = "pg-lo")`, the
|
||||
postgres-pglo factory on `all(feature = "postgres",
|
||||
feature = "pg-lo")`; the column's full run (acceptance) is
|
||||
`--all-features` against the server.
|
||||
|
||||
- **Factories** (`tests/conformance/pg_lo_column.rs`):
|
||||
- **`DualTierMemPgLoFactory`** — kv = mem + large = pg-lo: the
|
||||
one-window-host rule's named test topology. The **durable-schedule
|
||||
sweep rows run with the window hosted on the large engine**
|
||||
(`gc_window` in the pg-lo schema) — the shape no earlier column
|
||||
exercises.
|
||||
- **`DualTierPostgresPgLoFactory`** — kv = postgres + large = pg-lo
|
||||
on one pg instance: the consolidation posture. Mirrors the
|
||||
postgres column's inventory with the large medium swapped to LOs,
|
||||
and carries the **dormancy row** (the pg-lo schema carries no
|
||||
`gc_window`; the window lives on the kv schema).
|
||||
Both at column-declared thresholds and the **test tuning of the
|
||||
window delay (`0` — execute-on-next-sweep)**. **The alkstore
|
||||
pg-factory pattern, reused** (the postgres column's landed shape):
|
||||
a fresh engine-owned schema per `open()` — unique per call, tracked
|
||||
per-instance in a registry, teardown `DROP SCHEMA IF EXISTS …
|
||||
CASCADE` over exactly the minted schemas, panicking-row-safe. The
|
||||
**LO-isolation corollary** (the `engine-pg-lo` design point carries):
|
||||
LOs are database-level — teardown must also reap the instance's LOs
|
||||
(tracked LOIDs + `lo_unlink`, or the per-test-database shape if that
|
||||
is what the engine task recorded), and the structural teardown
|
||||
assertions include **zero `pg_largeobject` residue**.
|
||||
- **Connection settings ride the environment** — the harness
|
||||
convention: `ALKBLOBS_PG_HOST/PORT/USER/PASSWORD/DB`, a
|
||||
reachability probe gating the rows (the SKIP posture's
|
||||
factory-owner responsibility). **The harness server**: dockerized
|
||||
`pglo-poc` (`postgres:16-alpine`) on :15432, db `blobs`,
|
||||
user/password `postgres`/`poc` — verified live 2026-10-12; the
|
||||
container is long-running in the dev environment.
|
||||
- **Mirror the form-independent reference rows** (README §The
|
||||
reference row set): INV-1 round-trips (content matrix × both put
|
||||
paths, in-body — the LO medium's ranged reads at window boundaries
|
||||
and the beyond-length clean failure are this column's INV-1
|
||||
extensions), INV-6 stat discipline (the companion-row probe —
|
||||
metadata-only, never LO content), the `NoLivenessSources`/
|
||||
`ProtectFailed` abort shapes. **No kv-only rejection row** — no
|
||||
kv-only pg-lo constructor exists (recorded; the postgres column
|
||||
hosts that row for the SQL kv engines).
|
||||
- **The durable-schedule sweep rows** — the SQL-backed columns' family
|
||||
(README §The schedule-relative reading), run on **both factories**:
|
||||
INV-2 dedup and INV-3 stage hygiene with counts read against the
|
||||
staged schedule, the two-sweep exact-count row over the full
|
||||
protection set (both tiers, the window observed — on the pg-lo host
|
||||
for the mem-pglo factory, on the kv host for the postgres-pglo
|
||||
factory), the sweep-vs-put race across the window delay
|
||||
(execution-time re-arbitration), the holder-stages-only lease shape,
|
||||
and INV-5 list correctness through durable-schedule outcomes.
|
||||
- **The dual-tier dispatch rows** mirror the postgres column's family
|
||||
(pure-function routing, threshold boundaries, fall-through per op)
|
||||
with the placement oracle adapted to the LO medium: large entries
|
||||
are companion rows + LOs (an independent pg connection counting
|
||||
`lo_entries` and probing `pg_largeobject`), kv entries per the
|
||||
factory's kv engine (the mem-pglo factory's kv placement is
|
||||
in-process — the oracle's kv half follows the mem column's
|
||||
introspection shape; recorded design point).
|
||||
- **Virgin-store row**: reads are no-ops on a fresh schema (pool,
|
||||
`lo_entries`, and the window state per the host rule all empty) —
|
||||
the constructor always ensures the host's schema, this row being the
|
||||
facade form.
|
||||
- **Structural factory tests** (the postgres column's pattern):
|
||||
factory isolation (fresh schema per open, nothing shared) and
|
||||
teardown-against-a-panicking-row (schemas really dropped, LOs really
|
||||
unlinked — zero residue probed).
|
||||
- **README amendments** (the convention's normative test-side home):
|
||||
the pg-lo rows table in §Columns beyond the reference set; the
|
||||
column plan's SKIP-posture note naming the second landed column and
|
||||
the per-factory feature-pair gating; current state (five columns).
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] The pg-lo column green **against the harness server** (`pglo-poc`,
|
||||
:15432) under `--all-features`: the mirrored reference rows + the
|
||||
durable-schedule sweep rows on both factories (the pg-lo-host
|
||||
shape and the kv-host/dormancy shape) + the dispatch rows + the
|
||||
virgin-store row, every row ADR-stamped and traceable to the
|
||||
backlog
|
||||
- [ ] The dormancy row asserts the consolidation shape's pg-lo schema
|
||||
carries no `gc_window`; the mem-pglo rows assert the window on
|
||||
the pg-lo host
|
||||
- [ ] Server-less runs skip cleanly (the reachability probe; the
|
||||
default-build gates stay green with the column skipped)
|
||||
- [ ] Factory isolation + idempotent teardown hold (fresh schema per
|
||||
open; schemas dropped, LOs unlinked; **zero `pg_largeobject`
|
||||
residue** probed; teardown safe against a panicking row),
|
||||
structurally exercised
|
||||
- [ ] README amendments recorded (the pg-lo rows table; the
|
||||
feature-pair gating note; current state)
|
||||
- [ ] `cargo test` (default) green — the column compiles out;
|
||||
`cargo test --features pg-lo` (and the mem/postgres pair
|
||||
variants) green server-less (skipping) and green against the
|
||||
server at acceptance; `cargo clippy --all-targets -- -D warnings`
|
||||
and `cargo fmt --check` green (default + the pg-lo variants +
|
||||
`--all-features`)
|
||||
|
||||
## References
|
||||
|
||||
- tests/conformance/README.md (the conventions this grows against;
|
||||
§SKIP posture, §Columns beyond the reference set, §The
|
||||
schedule-relative reading for SQL-backed columns)
|
||||
- tests/conformance/postgres_column.rs (the SKIP-posture column
|
||||
pattern — the factory shape, the medium oracle, the structural
|
||||
tests this mirrors)
|
||||
- tests/conformance/factory.rs (the factory contract this implements)
|
||||
- tests/conformance/rows.rs (the reference row set being mirrored)
|
||||
- docs/architecture/store-api.md (§Invariants — the test gate)
|
||||
- docs/architecture/decisions/009-pg-lo-large-tier-engine.md (the
|
||||
engine ADR the LO-medium rows stamp against)
|
||||
- docs/architecture/decisions/012-pre-decomposition-consistency-rulings.md
|
||||
§5 (the one-window-host rule — the dormancy row's authority), §6.7
|
||||
(the schedule the sweep rows assert against)
|
||||
- tasks/engine-pg-lo.md (the LO-isolation design point this factory
|
||||
inherits)
|
||||
|
||||
## Notes
|
||||
|
||||
> To be filled by implementation agent
|
||||
|
||||
## Summary
|
||||
|
||||
> To be filled on completion
|
||||
Reference in new issue
Block a user