alkblobs/tasks/suite-column-postgres.md

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

id	name	status	depends_on	scope	risk	impact	level	tags
suite-column-postgres	Conformance suite — the postgres column (the SKIP-posture column)	pending	store-postgres-construction	moderate	medium	phase	implementation	wave-4 suite postgres

Description

Grow the postgres column — the suite's first 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 --features postgres (feature postgres, default-off).

• Factories (tests/conformance/postgres_column.rs):
  • dual-tier kv = postgres + large = local at a column-declared threshold and the test tuning of the window delay (0 — execute-on-next-sweep);
  • kv-only(postgres) at a column-declared threshold (the rejection row's host; threshold materializable per the README's configuration contract). The alkstore pg-factory pattern, reused (alkstore-postgres tests/contract_suite.rs): a fresh engine-owned schema per open() — unique per call (seeded per tag/pid/time so two factory instances never share a schema name, racing opens included), tracked per-instance in a schema registry, teardown DROP SCHEMA IF EXISTS … CASCADE over exactly the schemas the instance minted (idempotent, owned — never the shared server's other schemas; safe against an abandoned store: CASCADE removes dependents server-side while the store's pooled connections fail closed on next use). Panicking-row-safe — the sqlite column's instance-tracks-its-own-site pattern over schemas instead of temp dirs.
• Connection settings ride the environment — the alkstore harness convention: ALKBLOBS_PG_HOST/PORT/USER/PASSWORD/DB (db defaulting postgres if unset), 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 (the alkstore harness's same server).
• Mirror the form-independent reference rows (README §The reference row set): INV-1 round-trips (content matrix × both put paths, in-body), INV-6 stat discipline, the NoLivenessSources/ ProtectFailed abort shapes (form-independent — abort before staging), and the kv-only rejection row (threshold-agnostic by discovery, unchanged).
• The durable-schedule sweep rows — the sqlite column's family (README §The schedule-relative reading for SQL-backed columns): 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), 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 sqlite column's family (pure-function routing, threshold boundaries, fall-through per op) with the placement oracle adapted by medium: kv entries live as rows in the pg schema's blobs table, large entries under the local root — the oracle distinguishes by medium (an independent connection counting the schema's rows vs the root's committed files).
• Virgin-store row: reads are no-ops on a fresh schema (pool, both GC tables, and committed tree all empty) — the constructor always ensures the schema (the engine's recorded posture), this row being the facade form.
• Structural factory tests (the mem/sqlite columns' pattern): factory isolation (fresh schema per open, nothing shared — two opens never observe one another) and teardown-against-a-panicking-row (schemas really dropped).
• README amendments (the convention's normative test-side home): the postgres rows table in §Columns beyond the reference set; the column plan's SKIP-posture note now naming a landed column; current state (four columns; the first SKIP-posture column, green against the harness server).

Acceptance Criteria

• The postgres column green against the harness server (pglo-poc, :15432): the mirrored form-independent reference rows + the durable-schedule sweep rows + the dispatch rows + the virgin-store row, every row ADR-stamped and traceable to the backlog
• 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; DROP SCHEMA … CASCADE over exactly the minted schemas; teardown safe against a panicking row), structurally exercised
• README amendments recorded (the postgres rows table; current state)
• cargo test (default) green — the column compiles out; cargo test --features postgres green server-less (skipping) and green against the server at acceptance; cargo clippy --all-targets -- -D warnings and cargo fmt --check green (default + --features postgres)

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/factory.rs (the factory contract this implements)
• tests/conformance/rows.rs (the reference row set being mirrored)
• tests/conformance/sqlite_column.rs (the SQL-backed column pattern — the durable-schedule rows' first host)
• /workspace/@alkdev/alkstore/alkstore-postgres/tests/contract_suite.rs (the pg-factory pattern reused: fresh schema per open, the schema registry, the CASCADE teardown, the env-driven DSN)
• docs/architecture/store-api.md (§Invariants — the test gate)
• docs/architecture/decisions/012-pre-decomposition-consistency-rulings.md §6.7 (the schedule the sweep rows assert against)
• docs/architecture/decisions/007-two-kv-engines-sqlite-and-postgres.md §5 (the exact-count sweep-outcome gate against dockerized postgres)

Notes

To be filled by implementation agent

Summary

To be filled on completion