docs(recovery): name the live canonical overlay without Draft instructions

[cursor]

Canonical recovery/documentation overlay — lane remains Draft pending current-main repair

PRs #214 and #226 remain closed/superseded predecessors. Their source, checks, reviews, and status claims do not transfer. This Draft is the open canonical-documentation PR.

Fresh retained-ref ancestry removes one previously asserted writer conflict without authorizing a documentation commit by itself. docs/canonical-documentation-authority@229f8d37833071ae8d6e84374f4007c44ac2fe59 is an exact ancestor of this PR head: comparing that retained ref to 93b76d2a06c4ce858738eebca278e1dbdbb5eb1d is ahead 7 / behind 0. The other retained docs/canonical-documentation-current-main, docs/canonical-documentation-current-main2, docs/canonical-documentation-current-main-anchor, and docs/canonical-documentation-current-main-final refs all resolve to historical protected-main commit d0a4b30be1f46536e352443309f3a35533156767, which is itself an ancestor of current protected main. These named retained refs therefore do not constitute independent competing canonical-documentation writers at their freshly observed heads.

That bounded ancestry result is not a global declaration that the docs lane is free. Before any source/docs commit here, refetch the complete non-default branch inventory and compare every documentation-affecting no-PR/open-PR head against the exact intended canonical paths/blobs; freeze if any independent live or ambiguous overlap appears. Do not create another documentation branch, delete/force-update retained refs merely to free the lane, or mutate protected-main documentation directly.

Fresh protected-main truth

Protected main is exact b84f0c94154043a3473939c01bb6471de5a129ae.

The current branch source remains unchanged at exact 93b76d2a06c4ce858738eebca278e1dbdbb5eb1d, authored before multiple later integrations. Canonical source/tests on this head are stale and the current formal review state remains blocking until a fresh review supersedes it.

The protected recovery/reconciliation graph now includes, with bounded non-guarantees preserved:

• feat(reconcile): add tenant-qualified single-flight lock #191 tenant-qualified PostgreSQL advisory-lock single-flight: transient coordination only, not a durable lease, scheduler, result-application transaction, or distributed exactly-once guarantee;
• fix(recovery): accept custom-format restore seek positions #212 bounded logical pg_restore: no backup creation, target-isolation/catalog/PITR/RPO-RTO proof;
• fix(recovery): fail-closed physical profile parse and WAL wording #219 physical/WAL/PITR profile semantics only: no pg_basebackup, WAL archiving/replay, cluster restore, or RPO/RTO proof;
• fix(recovery): prove restore catalog index decoys #223 restore-catalog index acceptance and fix(recovery): require cluster identity for restore-target isolation #228 cluster-system-identifier target isolation, each only within their explicit bounds;
• feat(reconcile): apply streamed results atomically with checkpoints #194 caller-owned PostgreSQL result application plus checkpoint advancement in one local transaction, not distributed exactly-once delivery;
• feat(recovery): verify receipts by re-inspecting current bytes #221 recovery-receipt verification by re-inspecting current packaged schema and backup-artifact bytes; and
• feat(recovery): require inspect provenance on binder evidence #227 inspection-provenance-bound receipt composition at current protected main.

#221 and #227 are no longer ACTIVE-PR truth. Closed/superseded landing vehicles such as #224/#225 must not be presented as current active authority. Every still-open implementation gap remains ACTIVE-PR/PARTIAL/PLANNED only to the extent proven by its exact current branch.

Required repair on this existing branch, only after a complete fresh writer survey

After a fresh protected-main and documentation-path writer inventory, update PRD/TRD/DOCUMENTATION_FITNESS/TRACEABILITY/architecture/status-contract tests consistently so that:

• only exact protected behavior is IMPLEMENTED-ON-PROTECTED-MAIN;
• feat(reconcile): add tenant-qualified single-flight lock #191, feat(reconcile): apply streamed results atomically with checkpoints #194, fix(recovery): accept custom-format restore seek positions #212, fix(recovery): fail-closed physical profile parse and WAL wording #219, feat(recovery): verify receipts by re-inspecting current bytes #221, fix(recovery): prove restore catalog index decoys #223, feat(recovery): require inspect provenance on binder evidence #227, and fix(recovery): require cluster identity for restore-target isolation #228 are represented by their actual bounded protected contracts and explicit non-guarantees;
• open reconciliation/recovery/product gaps remain ACTIVE-PR/PARTIAL/PLANNED as appropriate;
• feat(recovery): verify receipts by re-inspecting current bytes #221/feat(recovery): require inspect provenance on binder evidence #227 are removed from active overlays;
• closed/superseded predecessor vehicles are not treated as live authority;
• status tests prefer durable capability assertions rather than freezing transient PR states or obsolete protected SHAs except where lineage itself is material;
• protected secret storage is described accurately as PostgreSQL-backed storage with optional Fernet plus the current base64 compatibility mode; mandatory encryption, historical-row migration, rotation, and external key custody remain at their actual ACTIVE-PR/PARTIAL/PLANNED state; and
• no runtime/schema/workflow/package source is changed from this documentation lane unless a separate fresh writer-safe source boundary is independently established.

Additional protected-main documentation-fitness defect — refreshed 2026-08-30

Fresh protected-tree review found a second class of status drift outside the recovery overlay itself: docs/doctoring/batch-request-representation-confidentiality.md on protected main@b84f0c9 still opens by saying the representation-confidentiality change is carried by ACTIVE-PR #104 and is not a protected-main guarantee. PR #104 is in fact closed and merged (merged_at=2026-08-11T23:54:35Z, merge commit df75ea3d9b4509781ce414f180a21ee6dcdf720c). This protected-main doctoring statement is therefore stale authority metadata even though the document's bounded confidentiality/non-goal semantics remain useful.

The same fresh contract sweep confirms that protected main still has no PRD, TRD, DOCUMENTATION_FITNESS.md, TRACEABILITY.md, THREAT_MODEL.md, DATA_GOVERNANCE.md, ADR index, or obvious UML/ERD canonical artifact; those remain unintegrated overlay/gap surfaces and must not be described as protected-main authority. Existing protected ADR/doctoring records remain authoritative only within their individual status and capability bounds.

Repair the merged-#104 status statement on this existing canonical lane together with the other status vocabulary repairs after the required complete docs-path writer survey. Do not widen the repair into BatchRequest runtime behavior: protected #104 implementation already landed, and this new finding is documentation-status drift, not a newly discovered source/privacy defect.

Current formal-review boundary — refreshed 2026-08-30

Exact docs head 93b76d2a06c4ce858738eebca278e1dbdbb5eb1d still has three formal CHANGES_REQUESTED reviews:

1. protected feat(reconcile): add tenant-qualified single-flight lock #191 single-flight and related recovery lineage are stale in the canonical status graph;
2. protected fix(recovery): accept custom-format restore seek positions #212 logical restore and later recovery integrations are stale in the canonical status graph; and
3. protected optional-Fernet behavior is incorrectly promoted into a mandatory encrypted-at-rest guarantee; that review also contained a writer-lease concern about retained docs/canonical-documentation-authority.

The first two content findings and the optional-Fernet content finding remain substantively valid on this unchanged head. The third review's specific retained-ref premise is now bounded by newer ancestry evidence: docs/canonical-documentation-authority@229f8d3... is already an ancestor of this PR head and the four docs/canonical-documentation-current-main* refs resolve to historical protected-main ancestry, so those named refs are not independent competing writers. This newer evidence does not dismiss or rewrite the formal review; only a fresh reviewer disposition on a repaired exact head can supersede its formal state, and a complete documentation-path writer inventory is still required before any docs mutation.

No approval or predecessor evidence transfers. Review-thread count alone cannot supersede formal review state.

Governance / merge boundary — refreshed 2026-08-30

This PR remains Draft. Before any source/doc mutation or merge attempt, refetch the exact contributor head, independently resolved protected-main tip, ancestry/mergeability, every documentation-affecting PR/no-PR writer, affected canonical blobs, every available live protection/ruleset surface, exact-head required workflows/checks and material checkout identity, formal reviews, and threads. If another actor moves this branch or an overlapping canonical ref/blob during an invocation, freeze this lane rather than racing it.

Fresh live organization ruleset 18156473 requires 1 approving review, dismisses stale approvals after push, does not require approval of the most recent reviewable push, requires review-thread resolution, and requires an extra approval for unattributed changes. require_code_owner_review=false remains explicit. Merge/squash are allowed; deletion and non-fast-forward updates are protected. Required central workflows include close-empty PR, OpenCode review, PR review/merge scheduler, Security Scan, Strix, SAST Semgrep, and Noema review. Administrative bypass is not documentation/acquisition evidence and must not be used to manufacture readiness.

The earlier 2-approval/latest-push snapshot is stale. Mutable live governance truth is centralized in #244 and must be refetched again before any integration decision. The policy relaxation and retained-ref ancestry correction do not cure this Draft's stale canonical content or formal CHANGES_REQUESTED state.

Queued, pending, cancelled, skipped-required, absent, neutral, stale, predecessor, status-only, synthetic, author-only, no-write-reviewer, rate-limited, infrastructure-failed, dismissed, or conclusion-null evidence does not transfer.

Refs #104, #195, #196, #197, #198, #204, #244, #316.

[seonghobae]

Additional must-fix canonical-truth defects remain on unchanged exact head 93b76d2a06c4ce858738eebca278e1dbdbb5eb1d, against protected main@b84f0c94154043a3473939c01bb6471de5a129ae.

1. HIGH — Optional secret encryption is still promoted into a shipped guarantee

Protected pg_llm_batch/config.py does not require encryption by default: SecretStore(..., require_encryption=False) accepts no Fernet key and writes base64-obfuscated rows with is_encrypted = FALSE. This branch's own docs/DATA_GOVERNANCE.md correctly records optional Fernet and protected compatibility rows, but docs/product/TRD.md classifies config.py as "encrypted secret storage" and says standalone encrypted secrets are PostgreSQL-backed. The unchanged protected ARCHITECTURE.md similarly says PostgreSQL owns "encrypted secrets". Those statements collapse an optional mechanism into IMPLEMENTED-ON-PROTECTED-MAIN confidentiality behavior that the exact protected source does not guarantee.

Repair the canonical graph consistently on this existing documentation lane: describe protected main as PostgreSQL-backed secret storage with optional Fernet plus an explicit base64 compatibility mode; classify mandatory encryption, historical-row migration, rotation, and external key custody only at their actual ACTIVE-PR/PARTIAL/PLANNED state; and make root architecture/README, PRD, TRD, DATA_GOVERNANCE, THREAT_MODEL, DOCUMENTATION_FITNESS, and TRACEABILITY agree. Add a deterministic status/contract regression that fails if mandatory encrypted-at-rest language returns while protected construction still permits require_encryption=False. Do not turn repository evidence into a certification or key-custody claim.

2. HIGH — The asserted single-writer lease is not proven

Fresh non-default branch inventory finds retained docs/canonical-documentation-authority diverged from current protected main by 30 commits ahead / 21 behind and changing the same PRD, TRD, DOCUMENTATION_FITNESS, TRACEABILITY, and ADR-index surfaces. Its associated PRs #192/#93 are closed, but under the repository writer-safety contract a source-affecting no-open-PR branch remains active-writer evidence until freshly reconciled or independently proven inert. The current PR body therefore must not call #229 the single active canonical writer without resolving that exact overlap.

Before another documentation mutation, non-destructively reconcile or prove the retained branch inert against the then-current protected tree; do not delete or force-update it merely to free the lane. Then repair the earliest stale authority boundary and reacquire all exact-head/current-base documentation, security/privacy, package/release, review, and thread-resolution evidence.

The two earlier current-head change requests for stale #191/#212 and recovery lineage remain valid and are not superseded by this review. No approval or predecessor evidence transfers.

[seonghobae]

Fresh canonical-drift evidence on unchanged Draft head 93b76d2a06c4ce858738eebca278e1dbdbb5eb1d against protected main@b84f0c94154043a3473939c01bb6471de5a129ae:

• The branch PRD/fitness/traceability still classify the bounded logical restore/fix(recovery): accept custom-format restore seek positions #212 as ACTIVE-PR, and the branch ADR index still says ADR 0016 is not protected-main authority until fix(recovery): accept custom-format restore seek positions #212 integrates.
• Protected main now actually contains docs/adr/0016-postgres-logical-restore-seek.md, 0017-postgres-recovery-evidence-binding.md, and 0018-postgres-restore-catalog-acceptance.md; protected CHANGELOG.md also records the bounded restore_postgres_logical_backup() executor and custom-format seek correction under Unreleased.
• The retained no-PR canonical refs (docs/canonical-documentation-authority, docs/canonical-documentation-current-main, docs/canonical-documentation-current-main2, docs/canonical-documentation-current-main-anchor, docs/canonical-documentation-current-main-final) are still present, so writer exclusivity is still not proven.
• Formal review remains three current CHANGES_REQUESTED submissions and zero inline review threads; no approval transfers.

This is additional evidence for the existing stale-authority finding, not authority to mutate this branch now. Keep the lane frozen until the overlapping retained canonical writer is non-destructively reconciled or independently proven inert. Then refresh PRD/TRD/DOCUMENTATION_FITNESS/TRACEABILITY/ADR index and status-contract tests from the then-exact protected tree, promoting only bounded capabilities that are actually protected and preserving each recovery non-guarantee.

[seonghobae]

Fresh protected-main documentation-fitness finding for the existing canonical-doc lane; do not mutate this Draft until its documented writer-lease conflict is resolved.

At protected main@b84f0c94154043a3473939c01bb6471de5a129ae, pg_llm_batch/result_streaming.py is shipped production source and exposes StreamingBatchAPIClient, BatchResultRecord, BatchResultCheckpoint, CheckpointedBatchResultRecord, strict finite-number parsing and resumable-checkpoint support. Merged protected lineage #172/#177 is the implementation authority for bounded result streaming and resumable checkpoints.

The current protected root contracts are not synchronized to that shipped capability: AGENTS.md currently contains code-owner, tenant-lifecycle and provider-retry invariants but no result-streaming/checkpoint contract; ARCHITECTURE.md covers tenant lifecycle, logical restore and modular interoperability but does not describe the bounded streaming/checkpoint component or its lifecycle/no-replay/resume assurance boundary. README.md documents aggregate provider-file chunk/download limits, but its architecture/module table omits result_streaming.py and it does not present the shipped opt-in resumable streaming/checkpoint API as such.

Treat this as an additional canonical-fitness gap to reconcile on this existing docs lane, not as authority to open a competing docs branch or resurrect stale #58/#59 branch documentation. When writer safety is re-established, distinguish IMPLEMENTED-ON-PROTECTED-MAIN bounded streaming/checkpoint semantics from any still-unshipped checkpoint persistence/audit extensions, preserve the no-replay/explicit-close and prefix-evidence non-guarantees, and keep the public explanation beginner-readable. Re-read protected source and the merged #172/#177 authorities at mutation time; do not copy stale retained-branch prose merely because it is more detailed.