Document PostgreSQL backup recovery path

[nicho1ab]

Pull Request Evidence

Governing issue and intended outcome

• Governing issue: Closes Document safe pre-backup recovery when PostgreSQL connections are exhausted #675
• Intended outcome: Document the narrowly bounded human-operated recovery path required when verified application-owned PostgreSQL client saturation prevents the mandatory pre-activation database dump.

Implementation scope

• Major files or components changed: docs/developer/qnap-release-deployment-runbook.md and tests/unit/test_qnap_docker_runtime_config.py.
• Important behavior intentionally left unchanged or out of scope: The normal deployment sequence remains the default; no application code, schema, migration, Compose configuration, PostgreSQL configuration, production data, or deployed infrastructure changed.
• Reviewer UI regression contracts: Not applicable - no reviewer UI behavior, reviewer route, presentation, or reviewer interaction changed.

Acceptance-criteria evidence

Acceptance criterion	Evidence and result
Normal deployment remains default	PASS - the existing numbered deployment sequence remains authoritative and preferred outside the explicitly bounded exception.
Exceptional recovery is narrowly gated	PASS - the exception requires failed backup connectivity caused by exhausted PostgreSQL client slots, healthy PostgreSQL, verified application ownership of excessive sessions, and the known or equivalently verified application lifecycle defect.
Recovery stops only the application	PASS - only the app service may be stopped; postgres remains running and must immediately be reverified healthy.
PostgreSQL protections remain intact	PASS - restart, recreation, replacement, volume replacement, max_connections changes, routine pg_terminate_backend use, and PostgreSQL restore as recovery remain prohibited.
Backup gate remains fail-closed	PASS - failed, missing, or empty dump stops deployment, and no extraction, rename, promotion, rebuild/recreation, marker update, or activation may occur before the verified non-empty dump succeeds.
Resume point is bounded	PASS - after successful backup, already verified safe backup artifacts may be retained and deployment resumes at step 8; the later app-stop step is not repeated when app remains stopped.
Focused governance coverage	PASS - a focused test now protects the exceptional path and its placement within the authoritative runbook.

Validation and failure classification

Validation	Result	Failure classification, if applicable
Shared-runtime documentation checker	Pass	none
New focused exceptional-recovery governance test	Pass	none
Existing QNAP runbook governance test	Pass	none
git diff --check	Pass	none

• Implementation-caused failures: None.
• Pre-existing failures: None relied upon for passage.
• Environmental failures: None reported.
• Tests intentionally not run and why: The complete pytest suite was not rerun locally because this is a narrowly bounded documentation/governance change with one focused executable regression test; required GitHub checks provide the clean remote validation gate.

UI and accessibility evidence (when applicable)

Not applicable - no UI or accessibility behavior changed.

Reviewer-facing redesign artifact classification (when applicable)

Not applicable - no reviewer-facing redesign occurred.

Documentation, assumptions, and remaining risks

• Documentation impact: The authoritative QNAP release deployment runbook now documents an exceptional pre-backup recovery path for verified application-owned PostgreSQL connection saturation.
• Assumptions and limitations: The exception applies only after all documented preconditions are established; it does not replace or reorder the normal deployment sequence.
• Remaining risks or follow-up: Epic: Bring hosted Compare Facilities to stakeholder-review readiness #640 remains blocked until this change is merged and the human operator successfully performs the corrected deployment, proves the mandatory PostgreSQL backup succeeds, and completes hosted owner acceptance.

Governed-boundary review

Governed boundary	Status	Specific explanation or evidence
Schemas and migrations	No change	No schema or migration changed.
Ingestion and source-connector contracts	No change	No ingestion or source-connector behavior changed.
Security and privacy	No change	No authentication, authorization, secret, privacy, or user-data handling changed.
Production data and correction behavior	No change	No production data or correction behavior changed.
Deployment and infrastructure	Authorized change	The authoritative human-operated deployment procedure now documents one narrowly gated recovery sequence; no runtime infrastructure or configuration was modified.
Repository governance	No change	No general repository governance mechanism or workflow changed.
Required GitHub workflows and checks	No change	No required workflow or check was changed or weakened.
Tests or checks weakened to obtain passage	Authorized change	tests/unit/test_qnap_docker_runtime_config.py adds focused assertions protecting the exceptional recovery path; no existing test or required check was removed, relaxed, skipped, renamed, or weakened.

Required GitHub checks

• validate
• docs-check
• fixtures
• security