feat(tests): the conformance suite's fleet column — the exact-count fleet sweep outcomes under concurrency, green against the harness server (wave 6)

- tests/conformance/fleet_column.rs (cfg feature = "postgres"; the
  consolidation pieces cfg the postgres+pg-lo pair): the fleet-validity
  rows, the joint entry+pin tx rows (both-or-neither over an
  independent connection; the dedup re-put's upsert-renew; the second
  instance's re-put composing a second row — protection by row; the
  pg-lo consolidation round-trip byte-exact over the shared instance),
  the TTL/renewal rows (the guard's TTL/3 cadence through the short
  test TTL; the never-resurrect semantics through the facade; the
  paused holder's expiry boundary with the delete-then-recover
  backstop), and the exact-count fleet sweep rows — the wave's gate,
  INV-4's engine-gated fleet form: the two-instance exact-count shape,
  the lease contention row (SweeperLock as report data, nothing
  deleted), the cross-instance arbitration row (GcRefuse until the
  foreign row's expiry), the race across the window delay closed by
  the row, the maintenance step's exact reap, and the fleet liveness
  verb row (the schema-ownership rule asserted; the deregistration
  correction flow); the kv-only rejection row mirrored verbatim
  against the fleet kv-only factory
- three fleet factories after the postgres column's registry pattern
  extended to the fleet shape — one minted schema, two Store
  instances over it, each its own owner id (the pin rows compose by
  owner); the dual-tier instances carry private local roots riding
  FleetSharedMedia::asserted; the consolidation factory follows the
  pg-lo column's LO-isolation corollary (a TrackedDb::new constructor
  added to pg_lo_column.rs for the private janitor field); teardown
  drops exactly the minted schemas — idempotent, owned,
  panicking-row-safe, structurally exercised
- the SKIP posture rides the postgres column's reachability probe:
  server-less runs skip cleanly, acceptance is green against pglo-poc
  (:15432) under --features postgres with the consolidation rows
  under --all-features; the test tuning is the window delay 0 and the
  short test pin TTL (the fleet constructors' parameter) — ordering
  rides the tunings or the manual-expiry instrument, no sleep-based
  race assertions
- README amended: the fleet rows table (§Columns beyond the reference
  set), §Column plan (the fleet column is the wave-6 gate's host),
  §Current state — six columns
- task suite-column-fleet completed (Notes + Summary recorded,
  including the recorded deviations: the structural predicate shapes
  reach no fleet constructor; the cross-instance mismatch leg is
  unexercisable on the one-instance harness server — the probe's
  errors-closed posture asserted instead)

Verification: cargo test (default) green; cargo test --features
postgres green server-less (skipping) and green against the harness
server; cargo test --all-features green against the server (125
conformance + 226 library tests); cargo clippy --all-targets
-- -D warnings and cargo fmt --check green on the default, postgres,
and all-features variants
This commit is contained in:
glm-5.3-flash committed 2026-10-12 17:17:25 +00:00
1 parent 3a51bb43fc
commit 53b85dd9bb
5 files changed
+2641 -12

No files matched your search

+67 -8
View File
@@ -1,7 +1,7 @@
---
id: suite-column-fleet
name: Conformance suite — the fleet column (exact-count fleet sweep outcomes under concurrency)
status: pending
status: completed
depends_on: [store-fleet-put, store-fleet-sweep]
scope: moderate
risk: medium
@@ -98,21 +98,21 @@ instances over one shared pool**.
## Acceptance Criteria
- [ ] The fleet column green **against the harness server**
- [x] The fleet column green **against the harness server**
(`pglo-poc`, :15432): the fleet-validity rows, the joint-tx
rows, the TTL/renewal rows, the exact-count fleet sweep rows
(two-instance survival, lease contention, cross-instance
arbitration, the race across the delay, the maintenance step,
the fleet liveness row), and the kv-only re-routing row — every
row ADR-stamped and traceable to the backlog
- [ ] The fleet factory contract holds: one schema, two+ instances
- [x] The fleet factory contract holds: one schema, two+ instances
over it (distinct owner ids), teardown drops exactly the minted
schemas, panicking-row-safe — structurally exercised
- [ ] 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)
- [ ] README amendments recorded (the fleet rows table; current
- [x] README amendments recorded (the fleet rows table; current
state)
- [ ] `cargo test` (default) green — the column compiles out;
- [x] `cargo test` (default) green — the column compiles out;
`cargo test --features postgres` green server-less (skipping)
and green against the server at acceptance;
`cargo test --all-features` green (the consolidation factory's
@@ -143,8 +143,67 @@ instances over one shared pool**.
## Notes
> To be filled by implementation agent
Landed as `tests/conformance/fleet_column.rs` (cfg `feature =
"postgres"`; its consolidation pieces cfg the `postgres`+`pg-lo`
pair), wired in `tests/conformance/main.rs`, README amended (§Columns
beyond the reference set's fleet rows table, §Column plan, §Current
state — six columns). Three factories: `FleetDualTierFactory` (one
minted schema, two instances over it — each its own owner id and
private local root riding `FleetSharedMedia::asserted`),
`FleetKvOnlyFactory` (the re-routing client shape; implements
`StoreFactory` so the reference kv-only rejection row mirrors
verbatim), `FleetConsolidationFactory` (a dedicated database, kv + pg-lo
schemas, two fleet instances; the pg-lo column's LO-isolation corollary
— LO reaping, `WITH (FORCE)` drop, drop-guard janitors; a `TrackedDb`
constructor was added to pg_lo_column.rs since the janitor field is
private). The oracle reuses the postgres column's skip probe
(`harness_ready`) and observes the durable state over independent
connections (pool/window/pin-row counts, schema/table existence, the
embedder-table instruments, and the manual-expiry instrument for the
abandonment shape). Column tuning: window delay `0`, TEST_TTL = 900 ms
(TTL/3 ≈ 300 ms), waits are the expiry cadence itself or the manual
instrument — no sleep-based race assertions.
Recorded deviations from the task text, none blocking:
- The composite predicate's *structural* non-fleet-valid shapes (kv ≠
postgres, mem anywhere, `local` undeclared) have no fleet
constructor to reach through (the recorded enforcement map) — the
column asserts the constructor-set shape in prose + the runtime
rejects that do exist (zero TTL, single-connection pool, the
same-instance probe's failure posture). A `TrackedDb::new`
constructor was added rather than widening the field's visibility.
- The pg-lo **cross-instance mismatch** leg is unexercisable against
the one-instance harness server (the probe reads
`pg_control_system()` off one data directory); the row tests the
probe's errors-closed failure posture (an unreachable large
instance rejects at the constructor) and records the mismatch leg —
the same posture the engine suite's tests carry.
- The renewal row's "renewed == at_drop" compare reads at_drop *after*
the drop and asserts `>=` — one TTL/3 tick may legitimately land
between the pre-drop read and the drop; the frozen-after-drop
assertion (EXPIRY_HORIZON, `==`) is the never-leaks proof.
## Summary
> To be filled on completion
The fleet column is green: the wave's gate rows run against the
harness server under `--features postgres` (17 rows + 2 structural
factory tests) and under `--all-features` (the consolidation rows
join) — the fleet-validity rows, the joint-tx rows (both-or-neither,
the upsert-renew, second-row composition, the byte-exact
consolidation round-trip), the TTL/renewal rows (cadence,
never-resurrect, paused-holder + recover), the exact-count fleet sweep
rows (two-instance survival with exact counts, lease contention as
report data, cross-instance arbitration until expiry, the race closed
by the row, the maintenance step's exact reap, the fleet liveness verb
with the schema-ownership rule), and the kv-only re-routing row —
every row ADR-stamped and traced. The fleet factory contract holds
structurally (one schema, two instances, distinct owner ids, owned
idempotent teardown, panicking-row-safe); server-less runs skip
cleanly; the default build compiles the column out. Verification:
`cargo test` (default) green; `cargo test --features postgres` green
server-less (skipping) and green against `pglo-poc` (:15432);
`cargo test --all-features` green against the server (125 conformance
tests + the full library suite, 226 tests); `cargo clippy --all-targets
-- -D warnings` and `cargo fmt --check` green on the default, postgres,
and all-features variants.
+117 -3
View File
@@ -402,6 +402,64 @@ inside the dedicated database before it goes.
| `virgin_store_reads_are_no_ops_on_a_fresh_schema` | store-api.md §Error model (virgin-store semantics); ADR-012 §6.5; ADR-009 §2 (the companion-table bootstrap); ADR-012 §5 (the mem-pglo row asserts the window on the pg-lo host — `gc_window` present-and-empty, `gc_pins` never) |
| `the_window_lives_on_the_kv_schema_and_the_pg_lo_schema_stays_dormant` (postgres-pglo only) | the dormancy row: ADR-012 §5 (the one-window-host rule's kv-host arm — the pg-lo window clauses dormant, no `gc_window` in the pg-lo schema; the schedule observed on the kv host); ADR-008 §2; ADR-012 §6.7 |
**The fleet column's own rows**
(tests/conformance/fleet_column.rs, the suite's third SKIP-posture
column — the **fleet column**, the exact-count fleet sweep outcomes
under concurrency, wave 6's gate, landed wave 6): the column runs
under `--features postgres` (fleet mode requires kv = postgres — the
composite fleet-validity predicate's kv clause, ADR-012 §3), rides the
SKIP posture (it reuses the postgres column's reachability probe;
server-less runs skip cleanly; acceptance is green **against the
harness server**), and extends the factory contract to the **fleet
shape**: a fleet factory mints **one schema** and vends **two `Store`
instances over it**, each `fleet: true`, each with its own
store-instance id (the instances share the pool; the pin rows compose
by owner — the fleet's actual definition, ADR-011/ADR-012 §3).
Teardown drops exactly the minted schemas (`DROP SCHEMA … CASCADE`,
the postgres column's registry pattern — idempotent, owned,
panicking-row-safe), removes every vended temp root, and — the
consolidation shape — reaps the dedicated database's LOs before
dropping it (the pg-lo column's LO-isolation corollary). **The test
tuning** (the column declares its tuning, the constructor parameters'
purpose): window delay `0` (execute-on-next-sweep) and a **short test
pin TTL** (the fleet constructors' `pin_ttl` parameter — the
renewal/expiry rows need observable cadences; the TTL is constructor
configuration, never API). Where a row needs ordering, the window
delay and the TTL tunings provide it, or the independent connection's
**manual-expiry instrument** (the abandonment shape the maintenance
step reaps — the fleet engine suite's recorded shape); no sleep-based
race assertions — the lease/arbitration outcomes are decided by the
server, not by timing.
Three factories: `FleetDualTierFactory` (kv = postgres + large =
local, each instance with its own private root riding the operator's
`FleetSharedMedia` declaration), `FleetKvOnlyFactory` (the re-routing
posture's client shape, ADR-008 §3 — the mirrored kv-only rejection
row's factory form) and — gated on the `postgres` + `pg-lo` feature
pair — `FleetConsolidationFactory` (kv = postgres + large = pg-lo, the
same pg instance; a dedicated database per open, the LO-isolation
corollary's teardown).
| Row (`fleet_column.rs`) | Traces to |
|---|---|
| `every_fleet_valid_configuration_constructs` | the fleet-validity rows: ADR-012 §3 (the composite fleet-validity predicate at the constructor — kv-only, dual-tier declared-shared-media, and two-instances-over-one-pool with distinct owner ids, each exercised); ADR-008 §3 (the declared-shared-media arm; the re-routing arm); ADR-011 §4 (the mode vocabulary); INV-7 facade-contract row |
| `the_consolidation_fleet_constructs_over_one_shared_instance` (postgres+pg-lo only) | the fleet-validity rows' consolidation form: ADR-012 §4 (the same-instance arm — the `system_identifier` probe passing by construction); ADR-009 §2 (the companion table); ADR-012 §3 |
| `the_constructor_entry_guards_reject_the_degenerate_tunings` | the constructor's errors-closed rejects: ADR-008 §2 (a zero pin TTL degenerates the TTL/3 cadence — validated at entry); ADR-013 §2 (the fleet pool-sizing guard: a single-connection pool would self-deadlock the sweep lease); ADR-008 §3 (the sealed `FleetSharedMedia` — `local` undeclared has no constructor to reach it through; the structural clauses carry no fleet constructor) |
| `the_consolidation_same_instance_probe_errors_closed` (postgres+pg-lo only) | the same-instance probe's failure posture: ADR-012 §4 (any probe failure is a constructor error; the mismatching-instances leg needs two servers — recorded unexercisable on the one-instance harness) |
| `the_joint_entry_and_pin_tx_commits_both_or_neither` | the joint-tx rows: store-api.md §Invariants 4 (a visible pool entry is never unprotected — the joint commit is the mechanism) and §Invariants 3 (zero residue on failed puts); ADR-008 §2 (the joint entry+pin tx, pin-before-publish); ADR-010 §2 (the store core holds the tx end to end); ADR-012 §3/§4 |
| `a_dedup_reput_upsert_renews_and_a_fleet_reput_composes_a_second_row` | store-api.md §Invariants 2 (the fleet's cross-instance dedup leg); ADR-003 (CAS first-writer-wins); ADR-005 (the re-put refcounts); ADR-010 §2 (protection composes by row); ADR-008 §2 (the row's `(key, owner)` identity, the upsert-renew) |
| `the_pg_lo_consolidation_round_trip_is_byte_exact_over_the_shared_instance` (postgres+pg-lo only) | the joint-tx rows' consolidation form (one tx over the shared instance, byte-exact large-entry form, read back from the second instance): store-api.md §Invariants 1 and §Invariants 4; ADR-009 §2; ADR-008 §2; ADR-012 §4 |
| `the_pin_guards_ttl_third_renewal_moves_the_rows_expiry` | the TTL/renewal rows: ADR-008 §2 (the guard renews its row every TTL/3; a dropped guard stops its duty — no leaked tasks, the row freezes); ADR-012 §2 (the TTL lives with the store's renewal schedule — this column's declared tuning) |
| `an_expired_row_is_never_renewed_back_to_life` | the never-resurrect semantics through the facade: ADR-008 §2 (an expired row is never revived, even under a live guard whose renewal is still running); ADR-012 §2 |
| `a_paused_holder_loses_protection_at_expiry_and_a_reput_recovers` | the delete-then-recover backstop: ADR-008 §2 (the expiry semantics verbatim — a paused holder's row abandons at expiry, the delete proceeds, a byte-identical re-put recovers); ADR-012 §2 |
| `two_instance_exact_counts_instance_a_pins_instance_b_sweeps` | INV-4's engine-gated fleet form (the wave's gate): store-api.md §Invariants 4 (DB-backed pins + the advisory-locked sweep, the exact-count sweep-outcome shape against dockerized postgres) and §Invariants 5 (list correctness through outcomes); ADR-008 §2 (the SQL arbitration composes behind the in-process domain — a's foreign row cancels b's candidate at the execution-time re-arbitration); ADR-012 §1 (the exact report fields); ADR-012 §6.7 (the executor is the next sweep); ADR-013 §2; ADR-007 §5 |
| `two_instances_sweep_concurrently_one_leases_the_other_aborts_as_data` | INV-4 (the fleet-form `SweeperLock` shape): ADR-013 §2 (the SQL lease — one sweeper per pool across instances; the second aborts as report data with nothing staged, executed, or deleted); ADR-012 §1 (abort is report data); ADR-012 §6.7 (the holder stages only — the executor is the next sweep) |
| `a_foreign_owners_unexpired_pin_row_refuses_the_direct_delete_until_expiry` | INV-4 (the cross-instance arbitration row): ADR-008 §2 (the SQL-level arbitration on the direct delete path folds un-expired pin rows of *any* instance into one answer); ADR-012 §2 (the expiry semantics — the refusal boundary is exactly the row's expiry); ADR-005 (the facade's `GcRefuse`, nothing deleted) |
| `a_put_landing_during_the_fleet_window_survives_the_executing_sweep` | INV-4 (the sweep-vs-put race's fleet form, closed by the row): ADR-008 §2 (pin-before-publish; the window delay separates staging from execution); ADR-012 §6.7 (the execution-time re-arbitration is the executor sweep's posture); ADR-012 §2 |
| `the_maintenance_step_reaps_exactly_the_expired_rows` | INV-4 (the maintenance-step row): ADR-008 §2 (the sweeper's pin-reap — the GC-of-GC cleanup; expired rows exactly, un-expired rows survive; the reap runs before the overdue execution); ADR-012 §6.7; ADR-012 §1 |
| `an_embedder_liveness_table_protects_fleet_wide_and_is_never_owned` | the fleet liveness row: ADR-012 §6.6 (the fleet liveness verb — the same verb with a fleet-shaped argument; idempotent re-registration; malformed references error); ADR-008 §2 (the schema-ownership rule — the table is the embedder's, consulted at arbitration time, never enumerated); ADR-012 §6.4 (the deregistration correction flow) |
| `fleet_kv_only_mode_rejects_over_threshold_puts_at_put_time` (runner) | the kv-only re-routing row: the reference set's row mirrored verbatim against the fleet kv-only factory (threshold-agnostic by discovery, unchanged) — ADR-012 §6.2's machinery, the fleet edition (ADR-008 §3's re-routing posture's client shape; store-api.md §Invariants 7: the mode is constructible, the row runs) |
## Column plan
**mem is the contract-reference engine** (ADR-011 §2): wave 2 lands
@@ -415,12 +473,14 @@ harness server) and the **pg-lo column is the second** (landed wave 5;
its two factories gate on the `mem`+`pg-lo` and `postgres`+`pg-lo`
feature pairs respectively — the first column whose factories need
different feature sets — with the column's full run `--all-features`
against the harness server; the fleet-form rows of INV-4 are
engine-gated to the postgres column and first run in wave 6).
against the harness server). The **fleet column is the third** (wave
6's gate): the engine-gated fleet-form rows of INV-4 run under
`--features postgres` against two store instances over one shared
pool, their consolidation shape gated on the `postgres`+`pg-lo` pair.
## Current state
The harness is green on **five columns** (waves 2–5). The **mem
The harness is green on **six columns** (waves 2–6). The **mem
column** is the contract-reference column: the factory binding is the
concrete `alkblobs::Store` facade (see §The factory contract — the
binding demonstrator remains in `binding.rs`), the reference row set
@@ -542,3 +602,57 @@ structural (the engine suite's
`shared_harness_db_holds_zero_lo_residue` gate measures it) and the
structural teardown assertions probe zero orphan residue inside the
dedicated database before it goes.
The **fleet column** (the suite's **third SKIP-posture column** —
the fleet column, the exact-count fleet sweep outcomes under
concurrency, wave 6's gate, feature `postgres` default-off, its
consolidation factory also gated on the `postgres`+`pg-lo` feature
pair, landed wave 6) grows the **fleet column** of the suite
(README §Columns beyond the reference set — the recorded inventory is
the fleet rows table there): the fleet-validity rows (the composite
fleet-validity predicate at the constructor — every fleet-valid
configuration constructs, the constructor's entry guards reject the
degenerate tunings, and the consolidation shapes gate on the feature
pair), the **joint entry+pin tx rows** (the independent connection
sees both or neither; the dedup re-put upsert-renews the row; a second
instance's re-put composes a second row — protection by row; the pg-lo
consolidation round-trip byte-exact over the shared instance), the
**TTL/renewal rows** (the guard's TTL/3 renewal moves the row's expiry
— the short test TTL makes the cadence observable; the never-resurrect
semantics through the facade; a paused holder loses protection exactly
at expiry with the delete-then-recover backstop), and the **exact-count
fleet sweep rows** — the wave's gate, INV-4's engine-gated fleet form:
the two-instance exact-count shape (instance A pins, instance B
sweeps — the pinned entry survives via a's row at the execution-time
SQL re-arbitration, the unpinned twins delete, counts exact against
the staged schedule), the lease contention row (two instances sweep
concurrently — exactly one sweeps, the other aborts `SweeperLock` as
report data with nothing deleted), the cross-instance arbitration row
(a foreign owner's un-expired pin row refuses a direct delete —
`GcRefuse` — until the row's expiry), the race across the window delay
in its fleet form, the maintenance-step row (expired pin rows reaped
exactly), and the fleet liveness row (a test-owned embedder table
protects through the registration verb — the schema-ownership rule
asserted — with the deregistration correction flow). The kv-only
re-routing row mirrors the reference set's rejection row verbatim
against the fleet kv-only factory (the re-routing posture's client
shape, ADR-008 §3). Its factories follow the postgres column's
registry pattern extended to the fleet shape (one minted schema, two
instances over it, each with its own store-instance id — the pin rows
compose by owner; the dual-tier instances carry private local roots
riding the operator's `FleetSharedMedia` declaration; the
consolidation factory follows the pg-lo column's LO-isolation
corollary: a dedicated database per open, LO reaping, `WITH (FORCE)`
drop, drop-guard janitors). Connection settings ride the environment
(`ALKBLOBS_PG_HOST/PORT/USER/PASSWORD/DB`) and the runners gate behind
the reachability probe (the postgres column's — a skip is never a
failure), and its acceptance is the green run **against the harness
server** (dockerized `pglo-poc`, :15432 — verified live 2026-10-12)
under `--features postgres` and the consolidation rows under
`--all-features`. The test tuning: window delay `0`
(execute-on-next-sweep) and a short test pin TTL (the fleet
constructors' `pin_ttl` parameter — the column declares its tuning);
where a row needs ordering, the window delay and the TTL tunings
provide it, or the independent connection's manual-expiry instrument —
no sleep-based race assertions, the lease/arbitration outcomes being
decided by the server, not by timing.
File diff suppressed because it is too large. Load diff
+9 -1
View File
@@ -38,7 +38,13 @@
//! LO-medium column, feature `pg-lo` default-off, its two factories
//! spanning feature pairs `mem`+`pg-lo` and `postgres`+`pg-lo`), which
//! runs the same sets against the LO medium and skips cleanly
//! server-less.
//! server-less; [`fleet_column`] — the suite's third SKIP-posture
//! column (the fleet column — the exact-count fleet sweep outcomes
//! under concurrency, wave 6's gate, feature `postgres`-gated, its
//! consolidation factory also gated on `pg-lo`), which runs the
//! fleet-validity rows, the joint-tx rows, the TTL/renewal rows, and
//! the engine-gated fleet-form sweep rows against two store instances
//! over one shared pool and skips cleanly server-less.
//!
//! Items beyond the tests below are the later columns' surface, hence
//! the scoped `#![allow(dead_code)]` — it shrinks as columns land.
@@ -49,6 +55,8 @@ mod backlog;
#[cfg(feature = "mem")]
mod binding;
mod factory;
#[cfg(feature = "postgres")]
mod fleet_column;
#[cfg(feature = "mem")]
mod local_column;
#[cfg(feature = "mem")]
+20
View File
@@ -408,6 +408,26 @@ pub(crate) struct TrackedDb {
}
impl TrackedDb {
/// Register one tracked database — the constructor the columns'
/// factories share (the janitor field is private; the factory
/// records the maintenance DSN and the database's name, and the
/// janitor backs every abandoned exit path).
pub(crate) fn new(
name: String,
dsn: String,
schemas: Vec<String>,
lo_schemas: Vec<String>,
maintenance_dsn: &str,
) -> TrackedDb {
TrackedDb {
janitor: Some(DbJanitor::new(maintenance_dsn, &name)),
name,
dsn,
schemas,
lo_schemas,
}
}
/// Disarm the janitor (teardown took over the disposal).
pub(crate) fn disarm(&mut self) {
self.janitor = None;