feat(recovery): bind bounded PostgreSQL restore command

[seonghobae]

Bounded archive-recovery configuration slice — ACTIVE DRAFT / EXPLICIT #233 CHILD

This work originated from exact protected main@b84f0c94154043a3473939c01bb6471de5a129ae on explicit non-default branch feat/postgres-restore-command-b84f0c9. To validate the already-proven restore-command repair with the exact inherited coverage fix instead of duplicating that fix, it is now an explicit Draft child of #233.

Exact stack boundary

• current base branch: fix/recovery-evidence-weakref-coverage-b84f0c9
• exact base SHA: 5951b7a4d779903b8924abaef2a387cae50b7f54
• exact head SHA: e75da8678c5834164333e3a33821c08f7fc2ac68
• compare from exact base to exact head: ahead 7 / behind 0
• relative PR diff remains exactly pg_llm_batch/postgres_restore_command.py plus tests/test_postgres_restore_command.py.

The stack commit is a non-destructive merge retaining both histories. It did not mutate #233, protected main, canonical docs, or adjacent recovery branches.

Product contract

This Draft closes one narrow #204 configuration gap without claiming physical PITR completion: bind one reviewed absolute helper executable token to PostgreSQL's required restore_command placeholders as a deterministic server setting. The package does not accept caller-supplied shell command text, archive paths, credentials, arbitrary arguments, or alternate placeholder ordering.

The current source accepts only an exact built-in str helper path; requires a bounded canonical absolute POSIX executable token; rejects relative/dot segments, duplicate/trailing separators, whitespace, control/non-ASCII bytes, percent placeholders, quotes, backslashes and shell-active metacharacters; revalidates stored helper authority immediately before export; fixes %f then %p ordering and shell-quotes both server-supplied placeholders; and uses one content-free validation diagnostic.

Actual helper deployment/ownership/integrity, WAL archive custody, segment validation/copy semantics, PostgreSQL startup/replay, recovery-target binding, promotion, application acceptance, and achieved RPO/RTO remain outside this seam. This branch is not complete physical PITR.

RED → narrow repair

Prior exact test-only head ba1dcaa6a491434541e1e69a1d637ef33bf6d26f proved the shell-token defect on hosted CI run 32125096577: Python 3.10, 3.12 and 3.14 all failed the same realistic assertions, showing <helper> %f %p instead of required shell-safe <helper> "%f" "%p".

Pre-stack GREEN head ebf4c6611cec1172cf61c1e9181483becc3820c5 applied the narrow production fix: server_setting() renders fixed %f then %p placeholders as <helper> "%f" "%p" without widening accepted helper authority.

CI 32127282546 checked out that exact head with persisted credentials disabled. Python 3.10/3.12/3.14 unit jobs and PostgreSQL/container smokes succeeded; compile, Ruff and exact 100% public-docstring coverage succeeded; 1361 passed, 5 deselected; and postgres_restore_command.py was exact 100% statement/branch covered. Its sole aggregate failure was protected-main 99.96% coverage from the two weakref arcs owned by #233. Security Scan 32127282527, SAST Semgrep 32127282609, and Release Acceptance 32127282559 were terminal-success.

That pre-stack evidence proves the causal repair but is not transferred as current-head gate evidence.

Fresh writer/review safety

Fresh targeted branch inventory still finds this as the only postgres-restore-command branch. Fresh formal-review and inline-thread inventories are empty. Draft #229 remains the separate canonical-documentation writer and was untouched. Exact head/base, protected main and writer evidence were re-read immediately before this metadata refresh; no competing actor moved this lane.

Current exact-head validation

The genuinely new repository-local validation set on exact stacked head e75da8678c5834164333e3a33821c08f7fc2ac68 is now terminal-success:

• Release Acceptance 32200407730: success;
• Security Scan 32200407739: success;
• CI 32200407876: success; and
• SAST Semgrep 32200407903: success.

CI independently checked out and verified exact e75da8678c5834164333e3a33821c08f7fc2ac68 with persisted checkout credentials disabled. Python 3.10/3.12/3.14 unit jobs and PostgreSQL/container smokes succeeded; compile and Ruff succeeded; public-docstring coverage was exactly 100%; repository production statement/branch coverage was exactly 100.00% (3665 statements, 1014 branches, zero misses/partials); lock freshness succeeded; and uv build --no-sources produced both sdist and wheel. The Python 3.14.7 coverage run completed 1363 passed, 5 deselected, 5 warnings.

Those five warnings are inherited test-harness hygiene defects outside this restore-command diff: four schema-evidence finalizer warnings owned by Draft #251 and one compose/runpy warning owned by Draft #252. They are not suppressed here. #251 and #252 separately prove their bounded fixes on exact stacked heads, but their evidence does not transfer to this PR.

Fresh formal-review and inline-thread inventories remain empty; absence of review is not approval. Keep this PR Draft because #233 must integrate first and final review/revalidation must be reacquired after retargeting.

Integration boundary

#233 is the exact predecessor and must integrate first through current governance. Its pg-local quality/security/release evidence is terminal-success, but its current-head independent review remains non-passing because the review-evidence control plane is owned by read-only central .github. This child neither duplicates nor bypasses that blocker.

After #233 integrates, retarget this PR to then-current protected main, prove the reconciled descendant diff remains only this restore-command slice, and reacquire every exact-final-head quality/security/coverage/package/SBOM/provenance/release/review gate. No predecessor, pre-stack, infrastructure-failed, status-only, author-only, or other-branch evidence transfers.

Refs #204, #233, #244, #250, #251, #252.

[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: ecef1940-2afd-4e65-ae29-81d3c4817ba3

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