alkstore/tasks/pg-engine-integration.md

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

id	name	status	depends_on	scope	risk	impact	level	tags
pg-engine-integration	Postgres engine — integration (full-surface wiring, suite adoption, crate docs)	pending	pg-engine-notify-listen pg-engine-streams pg-engine-queues pg-engine-locks pg-engine-scheduler-outbox	moderate	medium	phase	implementation	wave-4 postgres-engine integration

Description

Close the wave's integration gaps once every mechanism is wired — the structural twin of wave 3's integration task (no lint-suppression removal on this side: the pg engine is greenfield, no #![allow] posture ever existed — the sweep below is the same discipline without that step):

• Full-surface sweep: every Store/TxHandle/mechanism trait method implemented (no todo!/unimplemented!/error-stub remaining); the engine crate's lib re-exports its public surface (open, PgOpts, the concrete store type) per the module-per-file convention. Genuinely dead code must be cut, not suppressed — clippy -D warnings green without allows.
• Contract-suite adoption (the plan's "waves 3 and 4 adopt the harness"): implement StoreFactory for the pg engine — a fresh schema per open (the SQLite factory's fresh-temp-file precedent; the POC's shared-server parallel-interference caveat is answered by exactly this isolation — each property's rows live in its own schema, so parallel property runs never observe one another), idempotent teardown (DROP SCHEMA … CASCADE; safe against an abandoned store per the factory contract's teardown posture). Pin the factory's isolation/idempotence contract (the SQLite factory's pin shape). Wire the engine's backlog column — the rows this engine owns now, running against the pg factory:
  • The ADR-023-stamped rows (extent-clamp, duration-refusal, encode_payload round-trip) — already written suite-side, factory-parameterized; they run against pg by this task's factory existing (verify, don't rewrite).
  • The pg arm of the engine-scoped rows: PayloadTooLarge produced (the pg rejection arm — oversized notify/notify_tx rejected client-side with the limit in the variant; the row text the SQLite integration task left for "wave 4's adoption"), drop = rollback no-ghosts, in-tx read-your-own-writes, enqueue-opts resolution, receiver close arms (the pg arm: stays open across reconnects, closes at shutdown — the row's engine-asymmetric legs may need the row split or parameterized per the suite's convention; implementer's choice, documented).
  • The SQLite-scoped rows (plain-path open §3, poll cadence §4) simply don't run against pg — the SQLite integration task's Notes already pinned that disposition.
• Crate docs: the engine crate's lib-level doc comments state the multi-host posture and the listener budget line (ADR-016, deployment.md) — the identity statements this crate owns (the open task drafted them; this task verifies they reflect the finished engine).
• Gates: full workspace build/test/clippy/fmt (the pg tests skip cleanly server-less but must be green against the harness server); coverage spot-check on the engine crate (no large uncovered regions outside error arms — the wave-3 gate's bar).

Acceptance Criteria

• No todo!/unimplemented!/error-stub in the engine crate; full trait surface implemented; clippy -D warnings green without allows
• StoreFactory implemented for pg (fresh schema per open, idempotent CASCADE teardown); the factory's isolation/idempotence contract pinned
• The backlog column runs green against the pg factory: the three ADR-023 rows verified (not rewritten), the pg arm of the five engine-scoped rows present + stamped
• The PayloadTooLarge pg arm row present (the SQLite integration task's deferred adoption discharged)
• Crate lib docs carry the multi-host + listener-budget posture statements, reflecting the finished engine
• Workspace gates green: cargo build, cargo test (incl. against the harness server), clippy -D warnings, fmt clean
• Coverage spot-check: no large uncovered regions outside error arms

References

• docs/plans/implementation.md (Wave 4 section)
• docs/architecture/core-contract.md (§Verification backlog)
• docs/architecture/decisions/022-contract-suite-layout.md
• docs/architecture/decisions/023-fourth-review-round.md (backlog additions)
• docs/architecture/decisions/016-deployment-honesty.md §5
• alkstore-sqlite/tests/contract_suite.rs (the factory precedent)
• alkstore-contract-suite/src/properties.rs (the rows to run/adopt)

Notes

To be filled by implementation agent

Summary

To be filled on completion