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 — refreshed 2026-09-10

• Protected main: 5913c4bad79d6bc29d7cc1c624abb7db2ea6a77c.
• Direct base: fix/recovery-evidence-weakref-coverage-b84f0c9@01d231fde23b82e2ced258d7bfcb4721ed75706d (test(recovery): cover stale evidence registry cleanup #233).
• Head: feat/postgres-pitr-target-b84f0c9@a6a6076853eef15b8d839f3cbca006289bc4abb1.
• Relative diff remains exactly:
  • pg_llm_batch/postgres_pitr_target.py
  • tests/test_postgres_pitr_target.py
  • tests/test_postgres_pitr_target_hardening.py

a6a6076... is the ordinary non-destructive reconciliation of the PITR-target history onto current #233. The inherited workflow/history changes are predecessor ancestry only and are not part of this PR's relative diff. No protected-main, canonical-documentation, or central .github source was mutated by this lane.

RED → GREEN lineage

• RED c550f0d7cc75d6de5ae8d6e98f06afcc05d5f26c: focused contract failed because the production PITR-target module did not yet exist.
• GREEN 5e34dfc4613969aec94523f5269699f86bfdf89a: bounded implementation.
• Hardening dc7e3e3640d360a243184878199250db34418fdb: non-string time-target rejection coverage.
• Stack reconciliation a6a6076853eef15b8d839f3cbca006289bc4abb1: preserves the same three-file semantic delta on current test(recovery): cover stale evidence registry cleanup #233.

Exact validation state

For exact current head a6a6076853eef15b8d839f3cbca006289bc4abb1:

• CI 33894120771: completed / success.
• Release Acceptance 33894120782: completed / success.
• Formal review inventory: empty.
• Inline review-thread inventory: empty.
• Qualifying independent APPROVED: absent.

These checks are branch evidence only; they do not transfer across another reconciliation and do not authorize protected integration by themselves.

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

#233 remains the exact predecessor and must integrate first under live protected-branch governance. This PR remains Draft because it has no qualifying independent approval. Do not transfer predecessor checks/reviews, manufacture head churn, self-approve, bypass required gates, or mutate read-only central owner source from this lane.

Direct child #299 has been non-destructively reconciled onto this exact head; its own source/test/review evidence remains independently gated.

After #233 integrates, reconcile this PR non-destructively to then-current protected main, prove that the relative diff remains exactly the three PITR-target files, and reacquire every exact-final-head/current-base required check/review gate. Merge only through the normal protected workflow.

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, #299.

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