docs(release): scope legacy rollback guidance to its migration baseline

2026-11-11 07:32:04 +01:00
parent 55431b5ad0
commit 3cca441874
3 changed files with 14 additions and 3 deletions
@@ -1,5 +1,11 @@
 # First production deployment runbook

+> Historical July 2026 baseline. Current release preparation follows
+> [the release qualification matrix](../docs/release-readiness/14_RELEASE_ACCEPTANCE_MATRIX.md) and
+> [recovery specification](../docs/release-readiness/11_BACKUP_RESTORE_ROLLBACK.md).
+> Reconcile the examples below with the exact candidate, migration history and isolated rehearsal
+> before operational use. Current rollback health checks are source-tested offline.
+
 > Written 2026-07-19 against the actual implementation, not against the other docs. Every command and
 > failure mode below was exercised locally against MariaDB 11 containers. No production data was used.
 >
@@ -220,9 +226,11 @@ everything written since the dump — including anything users did during and af
 **Restore the database only if the data itself is wrong.** If the backend simply will not start, the
 code rollback is almost certainly the whole fix.

-Why a code rollback is safe here: every Phase 4/5 migration is a no-op — the reconciler owns those
-tables — so reverting code never leaves migration history ahead of the schema. The reconciler is
-additive and never drops a table holding rows, so the older code simply ignores the newer tables.
+The July 2026 baseline used no-op Phase 4/5 migrations around reconciler-owned tables. Current
+migrations also perform schema changes, including `AddJobRevision` adding the application Version
+column and `AddUserOperationEvents` creating its table and indexes. Qualify the exact old/new image
+pair against the current migration history and representative post-upgrade writes. The recovery
+specification above includes ownership, revision, document and restore checks for that rehearsal.

 ## Procedure

@@ -17,5 +17,6 @@ Discovery only, 2026-11-02. These are qualification gaps unless a concrete defec
 | RR-11 | Backup host parsing rejected supported `Host=` alias and uppercase spelling | FIXED AND OFFLINE-TESTED. See [bounded remediation](RR-11_IMPLEMENTATION.md). Real dump/restore qualification remains open |
 | RR-12 | Previous handler omitted post-rollback health checks; schema/data/AI recovery remains separate | Health probes FIXED in `a39ac847` and six offline handler methods passed, including failed endpoints and diagnostics. See [health follow-up](11_BACKUP_RESTORE_ROLLBACK.md#rr-12-post-rollback-core-health-checks). Actual image identity, startup timing and recovery after migration/writes still require isolated rehearsal |
 | RR-13 | Off-host encryption and recovery-set consistency need independent proof. Failed transfer and partial monthly copy previously let deployment continue | Transfer and monthly marker failure gates FIXED AND OFFLINE-TESTED. Actual encryption, retrieval/decryption and database/files/key/tombstone consistency require approved isolation |
+| RR-14 | July first-deploy runbook inferred rollback safety from its no-op migration baseline, while current migration Up methods add schema | Historical scope and current qualification links clarified. `AddJobRevision` adds Version and `AddUserOperationEvents` creates a table/indexes. Exact old/new image compatibility after migration/writes remains an isolated rehearsal gate |

 Continue evidence work against the [source endpoint and environment census](03_ENDPOINT_ENVIRONMENT_CENSUS.md). Actual qualification requires an accepted candidate and isolated environment. Every fix needs minimal scope, targeted verification and the applicable stage approval.
@@ -2,6 +2,8 @@

 11 November. Branch `codex/release-rollback-health`, baseline `24a62997`, source `a39ac847` adds bounded post-rollback frontend/liveness/readiness probes and failing-diagnostics coverage while preserving the original exit status. Six extracted-handler tests, twelve backup tests and shell syntax validation passed. Full deploy, Docker, network, models and real restore were not executed. [Evidence and remaining qualification](11_BACKUP_RESTORE_ROLLBACK.md#rr-12-post-rollback-core-health-checks).

+RR-14 clarifies that the first-production runbook is a July baseline. Current Up migrations add the Version column and operation-event schema. Its old no-op argument cannot qualify a current old/new image pair. Current candidate, migration/write and recovery rehearsal requirements are now linked from that runbook. This was source/document review only.
+
 RR-12 offline failure injection passed 5/5 against the unchanged deploy exit handler. The evidence covers synthetic prior-image recreation, failed rollback diagnostics, original exit status and conditions that skip rollback. [Recovery report](11_BACKUP_RESTORE_ROLLBACK.md#rr-12-offline-failure-injection) distinguishes this from a real post-migration/post-write rehearsal. RR-13 off-host retrieval/decryption and consistent restore remain open. No production qualification.

 RR-13 transfer guard [reproduced and fixed offline](11_BACKUP_RESTORE_ROLLBACK.md#rr-13-off-host-upload-failure-handling). Daily and monthly copy errors stop deployment, and the success log makes no encryption claim. Actual remote encryption and restore remain open.