feat(database): back up SQLite before startup migrations

[mforce]

Summary

• create a verified SQLite snapshot before applying pending startup migrations
• capture committed WAL content through SQLite's backup API, verify with PRAGMA quick_check, then publish atomically
• retain the newest configured number of completed snapshots only after migration succeeds
• keep PostgreSQL's existing provision-then-migrate lifecycle unchanged
• document retention and digest-pinned manual recovery

Refs #39

Deliberate exclusions

• PostgreSQL backup/restore automation
• scheduled or continuous backups
• automatic rollback
• Alpine runtime changes
• generated graphify-out/ artifacts

The committed graph was validated against this feature head with uvx --from graphifyy graphify update .: the new coordinator, backup, and verifier types were present and GRAPH_REPORT.md named input c8ee805b. Per the project rule that generated graph artifacts stay out of feature PRs, those changes were reverted. After this feature merges, a separate graph-only PR from updated main will refresh the committed graph and use Closes #39.

Verification — driver-verified on 16d6dd8bd2dde14b8b694b3c97cdc96ab498b43c

• ./scripts/ci-local.sh all
  • server build: passed with the three known baseline warnings and no new warnings
  • Collectify.Tests: 783 passed (baseline 761; +22)
  • Collectify.PostgresTests: 15 passed (baseline 14; +1)
  • client: 248 passed
  • enum parity: passed
  • npm/NuGet vulnerability gates: passed
  • Docker entrypoint tests: passed
• Graphify code update validation: passed; generated files intentionally reverted
• mutation verification: 12/12 behavior mutants reddened the named test for the predicted mechanism; known-green log-literal control stayed green; every restore reran green

Kyoder implemented the initial three increments. Codex CLI gpt-5.6-terra applied the review-fix commit 16d6dd8; Kyoder independently reran its M11/M12 mutations and the full local CI equivalent on the resulting head.

Test plan

• snapshot preserves old migration history and seeded data
• uncheckpointed WAL sentinel is absent from a raw primary-file copy and present in the SQLite snapshot
• malformed snapshot fails integrity verification
• backup/verification failures prevent migration
• failed migration does not prune older recovery points
• cleanup deletion failure does not fail an otherwise successful startup
• retention parses timestamps across migration prefixes and ignores near-miss files
• retention always preserves the snapshot created for the current migration despite future-dated older files
• impossible timestamps in matching filenames are ignored without aborting startup cleanup
• missing, current, and in-memory SQLite paths do not create unnecessary snapshots
• invalid retention fails before SQLite startup work
• missing PostgreSQL target is provisioned and migrated without invoking SQLite backup
• full local CI equivalent passes
• mutation matrix and known-green control pass

Recovery contract

A restore stops the container, copies the selected snapshot over collectify.db, removes stale WAL/SHM files, and starts the previous known-good image by immutable digest from that release's image.json. Mutable tags such as latest are explicitly excluded.

[chatgpt-codex-connector]

You have reached your Codex usage limits for security reviews. Please try again later.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-08-29T02:33:33.840352Z	16d6dd8	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[mforce]

@codex Please review current head c8ee805b43166f255203d2f21da6a8f2e87d9a35.

Focus on SQLite snapshot integrity, WAL correctness, migration/retention ordering, PostgreSQL non-regression, recovery documentation, and tests that could pass for the wrong reason. For each finding, return MERGE-BLOCKING or FOLLOW-UP; both are legitimate, so do not inflate a follow-up into a blocker.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c8ee805b43

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[mforce]

@codex Please re-review current head 16d6dd8bd2dde14b8b694b3c97cdc96ab498b43c. The previous retention findings were fixed and independently verified; the inline thread contains the exact disposition and evidence.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. What shall we delve into next?

Reviewed commit: 16d6dd8bd2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[mforce]

Review follow-up disposition on current head 16d6dd8bd2dde14b8b694b3c97cdc96ab498b43c:

• Filed Make post-migration SQLite backup discovery failures non-fatal #187 for pre-existing post-migration backup-discovery/ranking failures that can still fail startup after the migration committed.
• This is not introduced by the retention fix. Current hosted/local gates exercise deletion failure but do not exercise inaccessible-directory or enumeration-I/O failure, so no current merge gate depends on the deferred path.
• Pre-migration snapshot creation and integrity-verification failures remain intentionally blocking and are outside Make post-migration SQLite backup discovery failures non-fatal #187.

[mforce]

@codex review

Please run the second unchanged-head review of 16d6dd8bd2dde14b8b694b3c97cdc96ab498b43c. Re-check SQLite snapshot integrity, WAL completeness, migration/retention ordering, current-snapshot protection, malformed backup filenames, PostgreSQL non-regression, recovery documentation, and false-green tests. Return merge-blocking versus follow-up disposition for any finding.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Another round soon, please!

Reviewed commit: 16d6dd8bd2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[mforce]

Review loop complete on unchanged head 16d6dd8bd2dde14b8b694b3c97cdc96ab498b43c.

Two consecutive complete rounds found no product-code defect. Each round received current-head verdicts from GitHub Codex, Codex CLI, Claude Code, and the repository-rules reviewer. The original inline retention thread is fixed, replied to, re-reviewed, resolved, and no review thread remains open.

Driver verification on this head: ./scripts/ci-local.sh all passed with 783 server tests, 15 PostgreSQL tests, and 248 client tests; M1–M12 failed for their predicted mechanisms and restored green. Hosted Server, Client, Docker entrypoint, image/Trivy, CodeQL, dependency-review, and GitGuardian checks are green.

Non-blocking follow-ups are filed as #187 and #188. Generated graph artifacts remain intentionally deferred to a graph-only closeout PR, so #39 stays open after this feature PR. The review stop rule is now satisfied; merge remains an explicit owner decision.