feat(recovery): assess bounded WAL manifest continuity

[seonghobae]

Summary

Add a bounded deterministic PostgreSQL WAL filename-continuity assessment for one explicit timeline and exact start/target LSN interval. The implementation validates PostgreSQL WAL filename geometry for reviewed 1 MiB–1 GiB power-of-two segment sizes, rejects malformed or hostile inputs, bounds work to 4096 segments, rejects the reserved first segment containing LSN zero, and emits content-free continuity metadata only.

This seam does not inspect WAL file bytes, prove cluster identity, establish timeline ancestry, execute replay, prove PITR/RPO/RTO, or promote a recovery target. Those remain separately governed under #204.

Exact stack boundary

• Protected main: b84f0c94154043a3473939c01bb6471de5a129ae
• Base branch: fix/recovery-evidence-weakref-coverage-b84f0c9
• Exact base SHA: 5951b7a4d779903b8924abaef2a387cae50b7f54
• Head branch: feat/postgres-wal-continuity-b84f0c9
• Exact head SHA: 24705a7de353c40a11e1172f7485e6ef04e22489
• Ancestry: 9 commits ahead / 0 behind the exact predecessor
• Relative diff remains exactly:
  • pg_llm_batch/postgres_wal_continuity.py
  • tests/test_postgres_wal_continuity.py

24705a7... is a non-destructive merge commit retaining the original WAL-continuity history and exact #233 head 5951b7a... as parents. It includes #233's focused weak-reference coverage regression only as predecessor history; that file is not part of this PR's relative diff. No source or documentation was written directly to protected main.

Fresh targeted writer inventory finds only feat/postgres-wal-continuity-b84f0c9 on this exact source surface. Fresh formal-review inventory remains empty; absence of review is not approval.

RED → narrow canonical-LSN repair

The branch contract requires start_lsn and target_lsn to be canonical PostgreSQL LSN text. PostgreSQL emits pg_lsn text with an unpadded uppercase high component and an exactly eight-digit uppercase low component (%X/%08X). The prior parser accepted equivalent zero-padded high components such as 00000000/01000000, allowing noncanonical textual identities into otherwise deterministic evidence.

• 9b331b378638cf8a95b8b3286abac649f5ec1dd3 — test-first regression rejects a zero-padded high component for both start and target.
• 12fc3f99753b2d045d8369d8671f91b75d1316b3 — narrow source repair parses the values, reconstructs PostgreSQL's canonical %X/%08X form, and rejects textual disagreement without widening accepted authority or diagnostics.
• 72aa141cd7e8b14c1d0de85cad1b8f518ae2112f — updates zero-LSN fixtures to canonical 0/00000000 so invalid-input, reserved-segment, and bounded-work regressions retain their intended causal boundaries.

The repair preserves exact built-in primitive validation, fixed content-free errors, bounded 4096-segment work, canonical uppercase 24-hex segment names, segment-size-dependent filename geometry, target-order validation, and the explicit non-guarantees above.

Exact validation state

Pre-stack exact head 72aa141... produced terminal-success Release Acceptance 32205580414, SAST Semgrep 32205580445, Security Scan 32205580399, Python 3.10/3.12/3.14 unit lanes, PostgreSQL/container smokes, compile, Ruff, and 100% public-docstring coverage. CI 32205580418 failed only at repository aggregate coverage: the WAL-continuity module was exact 100%, 1358 tests passed, and the only uncovered branches were protected-main postgres_backup_evidence.py:65->exit and postgres_schema_evidence.py:49->exit, owned by dependency-root #233. That predecessor evidence is RCA context only and does not transfer.

For unchanged exact stacked head 24705a7de353c40a11e1172f7485e6ef04e22489, repository-local workflows concluded terminal-success:

• CI 32208530970: success;
• Security Scan 32208531078: success;
• SAST Semgrep 32208530972: success; and
• Release Acceptance 32208531005: success.

Those historical conclusions remain branch evidence only. Final integration still requires fresh proof that every then-required scanner actually analyzed the final contributor head under then-protected central semantics. No predecessor, synthetic, or stale evidence transfers.

Contract boundary

assess_postgres_wal_continuity(...) accepts exact primitive values for:

• wal_segment_size_bytes: a reviewed PostgreSQL-supported power-of-two size from 1 MiB through 1 GiB;
• timeline_id: explicit nonzero uint32 timeline;
• canonical PostgreSQL start_lsn and target_lsn, with target not before start; and
• an exact tuple of complete canonical 24-hex WAL segment names in replay order.

The assessment requires the exact ordered segment tuple needed to cover the inclusive target LSN, rejects PostgreSQL's bootstrap-skipped first segment containing invalid LSN zero, and enforces a finite 4096-segment work budget.

Dependency and governance boundary — refreshed 2026-08-30

#233 is the exact predecessor and must integrate first. The former read-only central coverage/review failure is historical RCA rather than the current capability boundary. Unchanged #233 now has fresh exact-contributor-head CI, Release Acceptance, Trivy Security Scan, Semgrep SAST and bounded Strix evidence under protected central semantics. None of that evidence transfers to this child.

#233 remains non-passing because its active same-head OpenCode formal state is still CHANGES_REQUESTED, that disposition has not been superseded by a fresh qualifying semantic review, and no qualifying approval exists under live governance. Central .github remains read-only; mutable control-plane/reviewer/provider truth is centralized in #244. Do not mutate central, copy its workaround, churn pg heads merely to manufacture events, or transfer predecessor evidence.

This branch owns only the two WAL-continuity files above. It does not mutate #236 WAL receive execution, #238 PITR-target binding, #240 WAL-byte binding, #241 timeline-history assessment, canonical-documentation writer #229, or read-only central dependencies.

After #233 integrates, retarget/reconcile this PR non-destructively to then-current protected main, prove the relative diff remains exactly the two WAL-continuity files, and reacquire every exact-final-head/current-base CI, security, coverage, package, SBOM, provenance, release, review, and thread-resolution gate. Merge only with the qualifying independent non-author approval required by then-live policy.

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.

Refs #204, #233, #244.

[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: 71b5942b-0fb8-49a8-9046-9b64e5ab70af

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