alkblobs/tasks/engine-pg-lo-joint.md

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

id	name	status	depends_on	scope	risk	impact	level	tags
engine-pg-lo-joint	the pg-lo joint contribution — staged-put mechanics into the store-held tx	pending		moderate	high	component	implementation	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