alkblobs/tasks/suite-column-pg-lo.md

id, name, status, depends_on, scope, risk, impact, level, tags

id	name	status	depends_on	scope	risk	impact	level	tags
suite-column-pg-lo	Conformance suite — the pg-lo column (the LO-medium SKIP-posture column)	pending	store-pg-lo-construction	moderate	medium	phase	implementation	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