feat(recovery): bind deterministic PITR stop targets

[seonghobae]

Summary

Add a bounded, deterministic PostgreSQL PITR recovery-target binding seam without configuring a cluster, creating recovery.signal, supplying restore_command, replaying WAL, promoting a target, or claiming RPO/RTO.

Exact stack boundary

• Protected main: b84f0c94154043a3473939c01bb6471de5a129ae
• Base branch: fix/recovery-evidence-weakref-coverage-b84f0c9
• Exact base SHA: 5951b7a4d779903b8924abaef2a387cae50b7f54
• Head branch: feat/postgres-pitr-target-b84f0c9
• Exact head SHA: 09430638a20c66e1f9d7e76da808df8f1f2e3a01
• Ancestry: 6 commits ahead / 0 behind the exact predecessor
• Relative diff remains exactly:
  • pg_llm_batch/postgres_pitr_target.py
  • tests/test_postgres_pitr_target.py
  • tests/test_postgres_pitr_target_hardening.py

0943063... is a non-destructive merge commit retaining the original PITR-target history and exact #233 head 5951b7a... as parents. It includes #233's focused weak-reference coverage regression only as predecessor history; that test 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-pitr-target-b84f0c9 on this exact source surface. Fresh formal-review inventory remains empty; absence of review is not approval.

RED → GREEN lineage

• c550f0d7cc75d6de5ae8d6e98f06afcc05d5f26c — initial failing contract; the production module did not yet exist.
• 5e34dfc4613969aec94523f5269699f86bfdf89a — initial bounded implementation.
• dc7e3e3640d360a243184878199250db34418fdb — focused hardening coverage for non-string time-target rejection.

Exact validation state

Pre-stack exact head dc7e3e3... produced terminal-success Security Scan 32045584627, SAST Semgrep 32045584633, Release Acceptance 32045584686, Python 3.10/3.12/3.14 unit lanes, PostgreSQL/container smokes, compile, Ruff, and 100% public-docstring coverage. CI 32045584656 failed only at repository aggregate coverage: the PITR-target module was exact 100%, 1379 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 09430638a20c66e1f9d7e76da808df8f1f2e3a01, repository-local workflows concluded terminal-success:

• CI 32208888484: success;
• Security Scan 32208888474: success;
• SAST Semgrep 32208888490: success; and
• Release Acceptance 32208888488: 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.

Bounded contract

bind_postgres_pitr_recovery_target(...) consumes the exact protected PostgresPhysicalRecoveryProfile type and requires backup_method="pitr" with a WAL archive. The profile's reviewed recovery_target_kind remains authoritative.

The binder normalizes timezone-explicit time targets to UTC; bounds and canonicalizes normal 32-bit transaction IDs; canonicalizes non-zero LSN targets; bounds restore-point names and rejects control characters; requires an exact-boolean inclusive edge for time/XID/LSN and forbids it for name/immediate; permits only latest, current, or an exact positive uint32 timeline; and emits recovery_target_action=pause so isolated acceptance precedes any separate promotion decision.

The result is structured server-setting authority only. It contains no shell command, filesystem path, credential, target-promotion authority, or deployment capability claim.

Explicit non-guarantees

This branch does not provide restore_command, create or mutate PostgreSQL configuration, create recovery.signal, verify WAL continuity, copy a base backup, start PostgreSQL, execute WAL replay, prove that a requested target is present in the archive, promote a cluster, prove catalog/RLS/application readiness, recover external Fernet/TLS/provider/host configuration, or establish RPO/RTO/HA/DR.

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, not 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 three PITR-target files above and does not mutate adjacent WAL receive, WAL filename-continuity, WAL-byte binding, timeline-history, 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 three PITR-target 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

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