feat(recovery): observe paused WAL replay progress

[seonghobae]

Bounded PostgreSQL recovery replay observation — Draft

Refs #204, #233, #244. This remains a focused child of #233.

Protected main is exact 5913c4bad79d6bc29d7cc1c624abb7db2ea6a77c. The current dependency root is #233 01d231fde23b82e2ced258d7bfcb4721ed75706d. This branch owns only:

• pg_llm_batch/postgres_recovery_replay_observation.py
• tests/test_postgres_recovery_replay_observation.py
• tests/test_postgres_recovery_replay_serialization_snapshot.py

Contract and evidence boundary

observe_postgres_recovery_replay(...) performs one fixed, catalog-qualified read-only query through a caller-owned already-connected isolated restore target and accepts evidence only when the same row shows recovery still active, pg_get_wal_replay_pause_state() exactly paused, and pg_last_wal_replay_lsn() at or beyond the bounded normalized target LSN. The observed evidence object is bound to the exact live object plus an immutable registry snapshot so public construction, copying, or post-construction field mutation cannot fabricate package-observed provenance; serialization reads that snapshot rather than re-reading mutable caller-visible fields.

This is only a bounded replay-progress observation. It does not start or configure PostgreSQL, create recovery.signal, install restore_command, validate WAL bytes/archive continuity/timeline ancestry, prove exact stop-target semantics, resume or promote recovery, prove application readiness, recover external secrets/configuration, or establish RPO/RTO, HA/DR, CSAP, SOC 2, or certification claims.

RED -> GREEN lineage

• fb04977925743f0130baf7f991cae2642e237537: initial missing replay-observation acceptance RED.
• e16ddb11e51573ff794b937c491d7c62088194b8: fixed-query caller-owned observation seam.
• b2b8bce912a7d4d2614cec97a3d4388cd507f368 -> eac027f738970614b500313f22d8c52064a38764: exact-object + observed-snapshot provenance binding.
• 00c876773161009922beeb56b4c47d3ead021825 -> 897515a023c2fd5499ff3ad7aea965f157c471b5: ordinary one-to-eight-hex-digit PostgreSQL LSN segment support while retaining bounded/fail-closed rules.
• 559b7d600f0fbd34ecc435bc35bbae109f3defb8 -> 80742ec0265e2cd0d708ca1dcb52d3d7ac95c4b2: serialization TOCTOU RED/GREEN; immutable registry snapshot becomes serialization authority.
• CI 32478052170 on 80742ec... exposed the final owned-coverage gap at the fail-closed registry-disappearance guard; test-only 16a03699d069ae424b9bacf16ddd9ba0db5b1c9f made that concurrent-eviction path deterministic without changing production source.
• Historical restack c327443fd29eca1514ad687c34124a1e872dcdf9 still carried stale test(recovery): cover stale evidence registry cleanup #233 32469711... as second parent. Fresh compare against current test(recovery): cover stale evidence registry cleanup #233 was diverged, 11 ahead / 2 behind.
• Current ordinary reconciliation aff61297bf734015f8ac1e0ad5576083eb60cd11 preserves c327443... as first parent and exact current test(recovery): cover stale evidence registry cleanup #233 01d231fde... as second parent. The branch ref was advanced fast-forward with force=false; no destructive rebase or force push was used.

Exact current topology

• protected main: 5913c4bad79d6bc29d7cc1c624abb7db2ea6a77c;
• test(recovery): cover stale evidence registry cleanup #233: 01d231fde23b82e2ced258d7bfcb4721ed75706d;
• feat(recovery): observe paused WAL replay progress #293: aff61297bf734015f8ac1e0ad5576083eb60cd11;
• merge base with test(recovery): cover stale evidence registry cleanup #233: exact 01d231fde...;
• ancestry relative to test(recovery): cover stale evidence registry cleanup #233: 12 ahead / 0 behind;
• effective relative delta: exactly the three owned files listed above;
• open child PRs based on this branch: none;
• formal reviews: none;
• inline review threads: none; and
• qualifying independent approval: absent.

The reconciliation tree is exact current #233 plus only those three #293-owned blobs. Stale parent/control-plane material outside this bounded context was not carried forward.

Exact-head validation

Fresh validation for exact aff61297bf734015f8ac1e0ad5576083eb60cd11 is terminal GREEN:

• CI 34464458865: SUCCESS;
• Release Acceptance 34464458879: SUCCESS;
• exact source-head verification: SUCCESS;
• Python 3.10 / 3.12 / 3.14 unit lanes: SUCCESS;
• compile, lint, enforced public-docstring coverage, enforced production line coverage, lock freshness, and distribution build: SUCCESS;
• component/PostgreSQL container builds, PostgreSQL log-routing verification, and legacy-SQL cleanup integration smoke: SUCCESS.

These are exact-branch-head results, not protected-main or release truth. Absence of review is not approval.

Integration boundary

#233 must integrate first. It remains Ready/open on exact 01d231fde...; repository-local deterministic lanes are green, but required central review/compatibility and qualifying approval remain unsatisfied.

Mutable central workflow/review/ruleset state is owned by #244 and live .github owners; do not copy transient central SHAs, run attempts, or historical-base descriptions into this source lane. Historical .github#2040@6706c231... is lineage only.

Do not compensate here with empty pushes, synthetic compatibility status, copied central workflows, self-approval, gate weakening, destructive history edits, or routine administrator bypass. After #233 reaches protected main, reconcile this Draft non-destructively onto then-current protected ancestry and reacquire every exact-final-head/current-base test, coverage, security, package/SBOM/provenance, review/thread, and release gate required by live governance. Canonical recovery/product documentation remains separately owned; this focused source lane does not create competing README/CHANGELOG/ADR authority.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}