fix(doctor): report every migration history serve would refuse

[TusanHomichi]

Primary Issue

Closes #138

Problem And Outcome

doctor compared migrations by version only. A database whose stored checksum had changed, or whose migration was recorded as unsuccessful, read ok, while serve refused to start on it: migration 16 was previously applied but has been modified. The reverse mismatch also existed: doctor reported fail on pending migrations, which serve applies by itself, so running doctor between installing a new version and restarting looked like a failure.

After merge, doctor's migration verdict matches serve in both directions:

• A refusal is a fail. That covers a version this build does not know, a row recorded as unsuccessful, or a checksum that differs from this build's. The finding names the version and says what to do.
• Pending migrations, and a database with no history yet, are a warn that says what the service will do on its next start.

Changes

• storage.rs: one owning judgment of an applied history, RefusedHistory with Newer, Unfinished and Changed, plus migration_history(). The refusal list was derived from sqlx-core 0.9's Migrator::run_direct and validate_applied_migrations. Startup's existing newer-database check reads through it, with byte-identical wording.
• doctor.rs: check_migrations reports each refusal as a fail, and pending or no-history as a warn. It runs SELECTs only, on the existing read-only connection, as ADR 0016 requires. Warnings do not change the exit status; only a fail does.
• Docs: README, docs/operations.md (only named-migration lines mean the service refuses), docs/install.md, and a CHANGELOG Fixed entry.

Scope

• In scope: doctor's diagnosis.
• Out of scope: startup: refuse a bad migration history before backing up or migrating anything #142. Startup can apply a pending migration, or take a pre-migration snapshot, before sqlx refuses a bad history. The implementation surfaced it, and it is filed separately.

Verification

• Candidate revision: cab75e787f1a4c9d2559dd011756f1272568d5a4 (tree 71bf58df).
• Local full proof (verifier role): scripts/proof.py passed all 7 gates in 501 s.
  • 302 Rust tests passed, 0 failed.
  • Browser: 62 expected, 0 unexpected, 0 flaky, 0 skipped, on system Chrome 155.
  • Receipt sha256 99d8216b…, archived on the maintainer machine.
• New tests/doctor_migrations.rs runs the real binary for both doctor and serve on each case. Every case failed against the pre-change code.
  • Refusals, where doctor fails and serve refuses the same database:
    • changed checksum;
    • success = 0;
    • unknown version;
    • two problems at once.
  • Warnings, where doctor warns and exits 0 and serve starts:
    • one migration behind: serve also takes the pre-migration backup, after which doctor reports ok;
    • no history.
  • Positive control: an intact database.
  • A settings pin covers the sqlx assumptions this diagnosis relies on.
• tests/doctor_read_only.rs: with a changed checksum in a live writer's WAL, the database and WAL stay byte-identical. That test caught a deliberately injected doctor write in review. A separate test covers diagnosis in a read-only directory.
• Listed the exact verification commands run below
• Added or updated tests when behavior changed
• Added or updated an ADR when a durable decision changed (ADR 0016's contract unchanged)
• All fixtures and examples are invented; no real agency data

- scripts/check-guidance-names.sh
- web/: npm ci, npm run check, npm run build
- cargo fmt --check
- cargo clippy --workspace --all-targets -- -D warnings
- cargo test --workspace
- cargo build -p consolebook-server
- web/: npm run e2e (system Google Chrome 155)

Review And Merge Notes

• Independent review (reviewer role, frozen worktree at 249b2a3): 0 blocking.
  • It confirmed against the sqlx source that no history makes doctor say ok while serve refuses.
  • It confirmed startup decisions and wording are unchanged.
  • Its should-fix was the inverse mismatch: pending and no-history reported as fail. The integrator decided on parity in both directions, implemented in cab75e7 with parity tests, along with the nits: message wording, a test's stated claim, an ordering comment, a zombie process, and a README wrap.
• Delta 249b2a3..cab75e7: self-reviewed by the integrator.
• Authority: the maintainer selected doctor: compare stored migration checksums, not just versions #138 on 2026-10-15; standing PR permission.
• Operator impact:
  • doctor now catches a database serve would refuse.
  • Pending migrations warn instead of failing, so the exit code is 0.

🤖 Generated with Claude Code

[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-10-15T22:34:08.742366Z	8d403e5	New commits

ℹ️ 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.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cab75e787f

ℹ️ 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".

[TusanHomichi]

Rebased onto main 1dfb945 (#145). Codex P1: ADR 0029. Codex P2: MissingHistory refusal. Both are in 8d403e5.

Local full proof on 8d403e5c3f9298a21baf0cc00628c5511d7a857f (tree 6a642bc8):

• 7/7 gates passed;
• 309 Rust tests passed, 0 failed;
• browser suite: 62 expected, 0 unexpected, 0 flaky, 0 skipped, on system Chrome 155;
• receipt sha256 4916711e….

The earlier receipt for cab75e7 covers the pre-rebase head only.