docs(tasks): decompose wave 6 — the fleet GC mechanism, the architecture's most intricate state machine under concurrency

- store-fleet-construction: the fleet: true declaration slotting into
  the fleet-capable constructors (the recorded non-event), the
  composite fleet-validity predicate enforced at the constructor
  (kv=postgres AND pg-lo-same-instance OR local-on-declared-shared-
  media OR kv-only re-routing), the TTL/owner-id fleet state, the
  same-instance probe design point
- engine-pg-lo-joint: the pg-lo joint contribution — staged-put
  mechanics (512 KiB knee, CAS, transactional LO creation) into the
  store-held PgJointTx, the wave-5 deferred API-shape design point
- store-fleet-put: the joint entry+pin tx driver (amendment A1's
  drop discipline lands here — its recorded owner), the pin guard's
  TTL/3 renewal form, the dedup upsert-renewal, pin-first/
  publish-second for large=local, the consolidation one-tx put
- store-fleet-sweep: the SQL sweep lease (ADR-013 §2 semantics),
  SQL-level delete arbitration on the direct + window-execution
  paths, the expired-pin reaping clause (the seam as the named home
  for fleet-clause growth), the fleet liveness registration verb,
  the two-domain arbitration composition
- suite-column-fleet: the fleet column — two-instance factories over
  one schema, the exact-count fleet sweep rows (the wave's gate),
  lease contention, cross-instance arbitration, TTL/renewal rows,
  the fleet-validity predicate rows
- review-wave-6: the fleet gate per the plan, plus a standing
  code-smell/hygiene block — cargo doc --no-deps asserted clean
  (the twice-bitten PGLO-1 rustdoc private-link class), the
  allow(dead_code) scope notes audited against their remainder,
  stale wave-6 forward references, and task-Summary-vs-diff
  correctness

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.

Dependency graph validated: two parallel roots (construction, pg-lo
joint), put merging them, sweep parallel to put, the fleet column
merging, the review gate last; no cycles.

tasks/engine-pg-lo-joint.md

@@ -0,0 +1,145 @@
+---
+id: engine-pg-lo-joint
+name: the pg-lo joint contribution — staged-put mechanics into the store-held tx
+status: pending
+depends_on: []
+scope: moderate
+risk: high
+impact: component
+level: implementation
+tags: [wave-6, engines, pg-lo, gc]
+---
+
+## Description
+
+Land the **pg-lo engine's joint contribution** — the wave-5 deferred
+design point, recorded in `src/pg_lo.rs`'s scope boundary ("the *fleet*
+joint form (wave 6's store-held tx, ADR-012 §4/§5's ruling that pg-lo
+contributes LO writes + companion-row insert into it) is a wave-6
+design point") and in `src/gc.rs`'s `EngineFleetState::joint_put`
+clause doc ("an engine-task contribution against this `JointTx`
+type"). Under the fleet consolidation posture (kv = postgres +
+large = pg-lo, same pg instance — admitted by
+`store-fleet-construction`'s predicate), a large entry's content
+reaches the **same store-held transaction** the pin row commits in:
+one tx over the shared instance — the pg-lo engine contributes its
+staged-put mechanics (chunked `lowrite` + companion-row insert) into
+it; the pin-row insert and the commit stay the store's (`pin_commit`,
+the postgres host's clause — landed wave 4, unchanged here).
+
+- **The one-tx ruling** (ADR-012 §4): the store core holds one
+  transaction over the shared instance; the pg-lo engine contributes
+  LO writes + companion-row insert; the pin-row insert is the store's.
+  The engine sees pins only as rows; never as semantics (ADR-010 §2's
+  correction of ADR-009's ownership statement — nothing of
+  `EngineFleetState` lands on pg-lo itself; the contribution is
+  mechanics the store core drives).
+- **The contribution's API shape** — the named design point wave 5
+  deferred. The engine's existing staged put holds its own tx (the
+  held-tx posture: the staging cursor owns a pool checkout with an
+  explicit session-level `BEGIN`); the joint form inverts the
+  ownership — the store core's `PgJointTx` (the postgres engine's
+  held checkout, wave 4's recorded shape) is the tx the LO writes
+  ride. **Named design point — the contribution's API home**: decide
+  the shape consistent with the seam's ownership rule (the store
+  holds the tx; the engine contributes mechanics into it) — the
+  natural shapes are a crate-internal pg-lo method taking
+  `&mut PgJointTx` (the engine writes `lo_create`/`lowrite` +
+  the companion-row insert through the held checkout) or a joint
+  staging-cursor variant handed out against the held tx; decide,
+  record, and keep the public trait surface untouched (the
+  contribution is crate-internal, like every seam clause). The
+  `JointTx` type is the postgres engine's `PgJointTx` — the
+  consolidation posture's one shared instance is what makes the
+  type shareable (ADR-012 §4's checkable clause;
+  `store-fleet-construction` enforces it).
+- **The staged-put mechanics, re-shaped not re-written**: the 512 KiB
+  `lowrite` knee (`LOWRITE_CHUNK`, the C2 citation), the CAS
+  existence check first (a re-put commits an empty contribution,
+  never `lo_create`), the companion-row insert, transactional LO
+  creation (zero crash orphans — C6, structurally: the LO lives and
+  dies with the store-held tx) — the engine's landed bodies carry;
+  what changes is whose tx they run in. The engine-level held-tx
+  staging cursor is **unchanged** (the non-fleet put path keeps its
+  own tx; the wave-5 hygiene tests stay green untouched).
+- **Failure discipline**: every failure path inside the contribution
+  leaves the store-held tx in a state the driver can terminate — the
+  contribution never commits, never rolls back the store's tx
+  unilaterally (the driver owns termination; amendment A1's
+  discipline — the driver task owns the catch-propagate-terminate
+  design; this task's duty is that the contribution's error paths
+  compose with it: no partial LO state that outlives the tx's
+  rollback, which transactional LO creation already guarantees).
+- **Contract tests** (engine-level, in `src/pg_lo.rs`'s test module,
+  the established env-driven convention): the contribution writes LO
+  content + the companion row into a `begin_joint_tx`-held tx and
+  `pin_commit` publishes entry + pin row in one step (byte-exact
+  round-trip after commit); a forced failure mid-contribution aborts
+  the whole tx with zero residue (no LO pages, no companion row, no
+  pin row, no kv row — the stage-hygiene invariant's tx form, the
+  wave-4 joint-atomicity test's pg-lo edition); the CAS re-put form
+  (a second contribution of the same key commits an empty
+  contribution; the pin row upsert-renews); the 512 KiB knee rides
+  (a multi-chunk contribution). **Tests need a live server** — the
+  alkstore harness convention: env-driven (`ALKBLOBS_PG_*`), skip
+  cleanly server-less, acceptance requires green against the harness
+  server (`pglo-poc`, :15432, db `blobs`, `postgres`/`poc` — verified
+  live 2026-10-12). Adopt the `SchemaJanitor`/per-test-database
+  isolation posture from the start (amendment A2's lesson — the
+  wave-4 leak is not re-learned).
+- **Scope boundary**: the store-core driver that calls this
+  contribution on the fleet put path is `store-fleet-put`; this task
+  ships the engine-side mechanics and their contract tests. The
+  non-fleet pg-lo put path is untouched.
+
+## Acceptance Criteria
+
+- [ ] The pg-lo joint contribution exists behind the crate-internal
+      seam (the public trait surface untouched; nothing of
+      `EngineFleetState` implemented on pg-lo itself)
+- [ ] The contribution's API shape decided and recorded (the
+      store-held `PgJointTx` is the tx the LO writes ride; the
+      ownership rule honored — the engine contributes, never owns)
+- [ ] One-tx publish: LO content + companion row + pin row + kv row
+      commit in one step; byte-exact round-trip after `pin_commit`
+      (contract-tested)
+- [ ] Zero residue on any failure path (no LO pages, no companion
+      row, no pin row, no kv row — contract-tested with a forced
+      failure); the contribution's error paths compose with the
+      driver's termination discipline (A1)
+- [ ] The CAS re-put form (empty contribution, upsert-renewal) and
+      the 512 KiB knee contract-tested
+- [ ] The non-fleet held-tx staging path and its wave-5 hygiene tests
+      unchanged and green
+- [ ] `cargo test --features "pg-lo,postgres"` green server-less
+      (skipping) and against the harness server at acceptance;
+      `cargo clippy --all-targets -- -D warnings` and
+      `cargo fmt --check` green (default + the pg-lo variants);
+      `cargo doc --no-deps` clean
+
+## References
+
+- src/pg_lo.rs (the scope boundary recording this task; the held-tx
+  staging bodies this re-shapes; `LOWRITE_CHUNK`)
+- src/gc.rs (`EngineFleetState::joint_put`'s clause doc — the
+  contribution's seam home; `JointTx`'s ownership rule)
+- src/postgres.rs (`PgJointTx` — the held-checkout tx type; the
+  wave-4 recorded design points)
+- docs/architecture/decisions/012-pre-decomposition-consistency-rulings.md
+  §4 (the one-tx ruling; the same-instance clause)
+- docs/architecture/decisions/010-backend-io-seams-and-fleet-state-home.md
+  §2 (the ownership rule; the pg-lo correction)
+- docs/architecture/decisions/009-pg-lo-large-tier-engine.md (the
+  engine shape the mechanics carry)
+- docs/research/poc-pglo-findings.md (C2 the knee, C6 zero orphans)
+- tasks/engine-pg-lo.md (the staged-put bodies this extends)
+- tasks/review-wave-4.md (amendment A1 — the drop discipline the
+  contribution composes with)
+
+## Notes
+
+> To be filled by implementation agent
+
+## Summary
+
+> To be filled on completion