feat(recovery): observe paused WAL replay progress

[seonghobae]

Bounded PostgreSQL recovery replay observation — Draft

Refs #204. Explicit child of #233.

Protected main is freshly verified at exact b84f0c94154043a3473939c01bb6471de5a129ae. Branch feat/postgres-recovery-replay-observation-b84f0c9 remains the sole targeted replay-observation lane. Its exact current head is 16a03699d069ae424b9bacf16ddd9ba0db5b1c9f, based on dependency root #233@5951b7a4d779903b8924abaef2a387cae50b7f54. Relative changes remain limited to:

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

No source or documentation was written directly to protected main. #233 remains independently blocked by its live review/control-plane state and must integrate first.

RED → narrow GREEN lineage

Test-first fb04977925743f0130baf7f991cae2642e237537 defined the initial missing replay-observation acceptance contract. Production e16ddb11e51573ff794b937c491d7c62088194b8 added the caller-owned read-only observation seam. Regression/fix b2b8bce912a7d4d2614cec97a3d4388cd507f368 → eac027f738970614b500313f22d8c52064a38764 bound evidence to the exact live object plus observed field snapshot so public construction, copying, or prior mutation cannot fabricate package-observed provenance.

LSN-width RED 00c876773161009922beeb56b4c47d3ead021825 then exposed that ordinary PostgreSQL hexadecimal segment widths such as 0/16B1970 were rejected before database I/O. GREEN 897515a023c2fd5499ff3ad7aea965f157c471b5 narrowly accepts one through eight uppercase hexadecimal digits per LSN component while retaining the high-component leading-zero rule, nonzero requirement, fixed catalog-qualified query, bounded diagnostics, and provenance checks.

A serialization review then found a TOCTOU boundary: as_dict() successfully validated exact-object provenance and then re-read caller-visible frozen-dataclass fields. frozen=True is not an authority boundary against object.__setattr__(). RED 559b7d600f0fbd34ecc435bc35bbae109f3defb8 made that deterministic and GREEN 80742ec0265e2cd0d708ca1dcb52d3d7ac95c4b2 bound serialization to the immutable registry snapshot.

Exact-head CI 32478052170 on 80742ec... then exposed a genuine owned-coverage defect: all Python 3.10/3.12/3.14 unit jobs and the container/PostgreSQL smoke passed, Ruff passed, public-docstring coverage was 100%, but exact production coverage was 99.96%. The sole uncovered path was postgres_recovery_replay_observation.py:105, the fail-closed guard for provenance-registry disappearance between the predicate read and immutable-snapshot read.

Current test-only 16a03699d069ae424b9bacf16ddd9ba0db5b1c9f adds deterministic concurrent-eviction modeling for that exact guard. It requires fail-closed provenance rejection if registry authority disappears between those two guarded reads. Production source is unchanged by this coverage repair.

Claim boundary

The package executes one fixed pg_catalog-qualified read-only query on a caller-owned already-connected isolated recovery target and accepts bounded evidence only when the same returned row shows recovery still active, pg_get_wal_replay_pause_state() exactly paused, and pg_last_wal_replay_lsn() at or beyond the requested target.

It does not start/configure PostgreSQL, create recovery.signal, install restore_command, validate WAL bytes or timeline ancestry, prove exact stop-target semantics, resume/promote recovery, prove application readiness, recover external secrets/configuration, or establish deployment RPO/RTO, HA/DR, CSAP, SOC 2, or certification claims. Existing recovery execution/configuration/evidence Drafts remain separate authority and are not protected-main truth.

Exact-head validation / governance — refreshed after hosted completion

Fresh commit-scoped workflow inventory for exact unchanged current head 16a03699d069ae424b9bacf16ddd9ba0db5b1c9f now shows:

• CI 32488881547: completed / success;
• Release Acceptance 32488881637: completed / success;
• exact-head Security Scan / SAST Semgrep: not materialized in the returned commit-scoped pull-request workflow inventory;
• formal reviews: none; and
• inline review threads: none.

The CI/Release successes prove only their own exact checkout. Absent Security/SAST evidence and absent formal review remain non-passing. The failed 80742ec... coverage run is predecessor RED evidence and does not transfer. Keep this Draft stable; do not manufacture source churn merely to create workflow or review events.

This PR remains Draft because #233 is not integrated, the current exact head lacks a complete terminal-success gate set, and qualifying final review/current-base governance is absent. After #233 reaches protected main, reconcile/retarget this Draft against then-current protected main and reacquire every exact-final-head/current-base quality gate, including supported Python through 3.14, exact 100% owned production statement/branch coverage, public-docstring coverage, security/SAST, package/SBOM/provenance/release acceptance, zero valid unresolved findings, and any formal independent approval actually required by live governance.

Queued, pending, cancelled, skipped-required, absent, neutral, stale, predecessor, status-only, synthetic, author-only, rate-limited, infrastructure-failed, dismissed, or conclusion-null evidence is non-passing.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 1b25bcdf-3077-4efa-a7c3-635a922ba77b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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.}