glm-5.3-flash
009de420e1
- 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.
145 lines
7.4 KiB
Markdown
145 lines
7.4 KiB
Markdown
---
|
|
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 |