feat(tests): the conformance suite's pg-lo column — the LO-medium SKIP-posture column green (wave 5)

- tests/conformance/pg_lo_column.rs (new): the two pair-gated factories
  (DualTierMemPgLoFactory on all(mem, pg-lo) — the one-window-host rule's
  named test topology; DualTierPostgresPgLoFactory on
  all(postgres, pg-lo) — the consolidation posture, two schemas per open,
  carrying the dormancy row), a fresh dedicated database per open with
  the engine-owned schemas minted inside, teardown reaping tracked LOIDs
  (lo_unlink) then dropping the minted schemas then the database
  (WITH (FORCE)) with per-open drop-guard janitors for the abandoned
  paths, and the rows: the verbatim form-independent mirror (INV-1, INV-6,
  the two no-op abort shapes), the schedule-relative INV-2/3, the
  two-sweep exact counts over the full protection set across each
  factory's observed window host, the window-delay race, the
  holder-stages-only lease, INV-5's durable row, the three dispatch rows
  over the LO-medium placement oracle, the INV-1 extension (window-edge
  ranged reads + the planted-overclaim beyond-length clean failure), the
  virgin-store rows, and the dormancy row; structural isolation +
  panicking-row tests probing zero orphan residue (no kv-only rejection
  row — recorded; pg-lo is a large engine)
- the LO-isolation corollary carried in the engine task's recorded
  per-test-database shape (the C7 lesson): zero LO residue on the shared
  harness database is structural, so the engine suite's
  shared_harness_db_holds_zero_lo_residue gate stays green alongside the
  column under --all-features
- main.rs: the pg_lo_column gate (feature pg-lo, default-off) + the
  columns' doc paragraph
- README: the pg-lo rows table in §Columns beyond the reference set, the
  SKIP-posture note naming the second landed column and the per-factory
  feature-pair gating, current state = five columns
- store.rs: one mechanical gate fix — the PgOpts import was unused in the
  sqlite+pg-lo config (tripping clippy --features pg-lo -D warnings);
  the gate now names the configs that consume it

Verification (harness server live 2026-10-12): --all-features against the
server fully green (188 lib + 106 conformance + 4 git-interop; zero
LO/schema/database residue after the run); default test green (69/19/3);
--features "pg-lo,mem" and "postgres,pg-lo" green server-less
(skipping cleanly) and --features pg-lo alone; clippy -D warnings green
on default, pg-lo, pg-lo+mem, postgres+pg-lo, all-features; fmt --check
green; cargo doc --no-deps clean.
This commit is contained in:
glm-5.3-flash committed 2026-10-12 08:47:55 +00:00
1 parent cddcea3cfa
commit aa96f8b981
5 files changed
+5457 -14

No files matched your search

+133 -9
View File
@@ -1,7 +1,7 @@
---
id: suite-column-pg-lo
name: Conformance suite — the pg-lo column (the LO-medium SKIP-posture column)
status: pending
status: completed
depends_on: [store-pg-lo-construction]
scope: moderate
risk: medium
@@ -94,24 +94,24 @@ feature = "pg-lo")`; the column's full run (acceptance) is
## Acceptance Criteria
- [ ] The pg-lo column green **against the harness server** (`pglo-poc`,
- [x] 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
- [x] 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
- [x] 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
- [x] 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
- [x] README amendments recorded (the pg-lo rows table; the
feature-pair gating note; current state)
- [ ] `cargo test` (default) green — the column compiles out;
- [x] `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`
@@ -139,8 +139,132 @@ feature = "pg-lo")`; the column's full run (acceptance) is
## Notes
> To be filled by implementation agent
> Implemented in `tests/conformance/pg_lo_column.rs` (the two
> pair-gated factories, the shared harness/oracle/janitor parent, the
> row bodies over both factories, and the structural tests),
> `tests/conformance/main.rs` (the module gate + the columns' doc
> paragraph), `tests/conformance/README.md` (the amendments), and one
> mechanical line in `src/store.rs` (see below). Recorded design
> points, as resolved:
>
> - **The LO-isolation corollary carried in the engine task's recorded
> shape — per-open dedicated databases.** The column first followed
> the postgres column's shared-db schema pattern with tracked-LOID
> `lo_unlink` teardown, and the wave-5 engine-suite gate
> (`pg_lo::tests::shared_harness_db_holds_zero_lo_residue`) broke at
> acceptance: its permanent probe (zero `pg_largeobject` pages in the
> shared `blobs` database) runs concurrently with the suite and the
> column's LOs legitimately existed mid-run there. The task's
> alternative clause ("or the per-test-database shape if that is what
> the engine task recorded") resolved the fork: the engine task
> **did** record the per-test dedicated database shape, so the column
> carries it — `open()` mints a fresh dedicated database (unique per
> call), the engine-owned schemas are minted inside it (the alkstore
> pg-factory pattern's registry, housed on its own database), and
> teardown reaps the instance's LOs (`SELECT loid FROM
> lo_entries` → `lo_unlink`), drops exactly the minted schemas
> (`DROP SCHEMA IF EXISTS … CASCADE`), and drops the database
> (`WITH (FORCE)`), with a per-open drop-guard janitor (the crate's
> `DatabaseJanitor` pattern re-implemented in the column file — the
> crate's janitor is `#[cfg(test)]`-internal) backing the abandoned
> paths. The structural tests probe **zero orphan residue inside the
> dedicated database before it goes** (the companion table and the
> LO catalog agree exactly — the C1 shape), assert the recorded
> reaped LOIDs match the pre-captured set, and observe the database
> gone afterward; zero residue on the shared database is structural
> (no pg-lo pool ever opens against `blobs`).
> - **The consolidation factory mints two schemas** (the kv half and
> the pg-lo half, both inside the dedicated database) so the dormancy
> row observes genuine absence; the corollary's one-schema mint
> remains the engine tests' recorded alternative.
> - **The mem-pglo kv half is facade-observed** (the mem column's
> introspection shape: served reads and `has()` against the LO
> medium's genuine absence); the postgres-pglo kv half counts the kv
> schema's `blobs` rows (the postgres column's oracle shape).
> - **The INV-1 extension row** asserts ranged reads across the
> shipped window edge (`READ_CHUNK`'s 512 KiB, duplicated in the
> column file since the constant is engine-internal), the EOF
> clamping family (tail, at-EOF empty, `u64::MAX` offset clamp,
> zero-length, over-read), the ADR-006 range digests, and the
> **beyond-length clean failure** against a **planted overclaiming
> companion row** (`lo_create`/`lo_open`/`lowrite` + `lo_entries`
> insert through the oracle — the corrupted half-state healthy
> stores never hold): the read trusts the row (metadata-only) and
> fails with the unexpected-EOF-shaped `Error::Io`, and the
> executing sweep's delete reaps the planted LO. The identical-
> content legs dedup into one entry (CAS across the paths), so the
> cleanup stages exactly two.
> - **Row inventory** (both factories; the factory dimension is the
> run): the form-independent mirror (INV-1, INV-6, the two no-op
> abort shapes — verbatim from rows.rs) + INV-2/INV-3 (schedule-
> relative, both tiers' legs) + the two-sweep exact-count row, the
> window-delay race row, the holder-stages-only lease row, INV-5's
> durable row, the three dispatch rows, the INV-1 extension, the
> virgin-store row, the postgres-pglo-only dormancy row; **no
> kv-only rejection row** (no kv-only pg-lo constructor exists;
> recorded). The mem-pglo virgin row asserts the window on the
> pg-lo host (`gc_window` present-and-empty, `gc_pins` never).
> - **One mechanical `src/` fix** (out of scope but required by the
> gate): `src/store.rs`'s `use crate::pg_common::PgOpts` was gated
> `any(postgres, pg-lo)` and sat unused in the `sqlite`+`pg-lo`
> config (pg-lo alone over default features), tripping
> `cargo clippy --features pg-lo -D warnings`; the gate now names
> the configs that consume the import
> (`any(postgres, all(pg-lo, mem))` — no semantic change).
> - **Two harness-server residue cleanups** — found + removed (same
> discipline as the d69d9a3 finding): the shared `blobs` db carried
> the pre-rework runs' schemas (`abpglo_*`/the over-long first
> mints) + their orphaned LO pages (1032 catalog pages; the
> schema-pattern teardown dropped schemas, stranding LOs — exactly
> the C7 lesson motivating the dedicated-database shape); cleanup
> verified zero (`pg_largeobject`, schemas, and suites' databases).
> The first shared-db schema mints also grazed postgres' 63-char
> identifier limit (E42622) — the dedicated-db mint
> (`abpglosuite_…`/`abpglo_…`) stays well under it.
> - **The first rework run's failure was a miscount, not a bug**: the
> INV-1 extension row's two identical-content legs dedup into one
> entry, so the cleanup sweep stages two (one real + the planted),
> not three — fixed in the row's expectations and recorded here.
## Summary
> To be filled on completion
> Completed 2026-10-12 (wave 5). The pg-lo column — the suite's
> second SKIP-posture column — landed in
> `tests/conformance/pg_lo_column.rs`: `DualTierMemPgLoFactory` (kv =
> mem + large = pg-lo, the one-window-host rule's named test
> topology, `all(mem, pg-lo)`) and `DualTierPostgresPgLoFactory` (the
> consolidation posture on one pg instance, `all(postgres, pg-lo)`;
> two schemas inside each open's dedicated database; the dormancy
> row asserting no `gc_window` in the pg-lo schema and the window on
> the kv host), each factory vending a fresh dedicated database per
> open with engine-owned schemas minted inside, teardown reaping
> tracked LOIDs → dropping the minted schemas → dropping the
> database `WITH (FORCE)`, plus per-open drop-guard janitors for the
> abandoned paths — zero LO residue on the shared `blobs` database
> structural (the engine suite's gate holds green alongside the
> column). Fifteen rows on the mem-pglo factory, sixteen on the
> postgres-pglo factory (its extra one being the dormancy row): the
> verbatim form-independent
> mirror (INV-1, INV-6, the no-op abort shapes), the
> schedule-relative INV-2/3, the two-sweep exact counts over the
> full protection set across the observed window host, the
> window-delay race, the holder-stages-only lease, INV-5's durable
> row, the three dispatch rows over the LO-medium oracle, the INV-1
> extension (window-edge ranged reads + the planted-overclaim
> beyond-length clean failure), and the virgin-store row (the
> mem-pglo one asserting the window on the pg-lo host) — the
> dormancy row being the postgres-pglo factory's extra — plus the
> structural isolation/panicking-row tests probing zero orphan
> residue. No kv-only rejection row (recorded; pg-lo is a large
> engine). README recorded (the pg-lo rows table in §Columns beyond
> the reference set, the SKIP-posture note naming the second landed
> column and the per-factory feature-pair gating, current state =
> five columns). Verified (harness server live 2026-10-12): acceptance
> `cargo test --all-features` against the server fully green (188 lib
> + 106 conformance + 4 git-interop; zero LO/schema/database residue
> after the run); `cargo test` (default) green (69/19/3 — the column
> compiles out); `--features "pg-lo,mem"` and `--features
> "postgres,pg-lo"` green server-less (skipping cleanly) and under
> `--features pg-lo` alone; clippy `-D warnings` green on default,
> pg-lo, pg-lo+mem, postgres+pg-lo, and all-features; `cargo fmt
> --check` green; `cargo doc --no-deps` clean.