diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b5ede6b..81022a9 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -91,6 +91,50 @@ jobs:
       - name: The workflow files themselves (actionlint)
         run: go run github.com/rhysd/actionlint/cmd/actionlint@v1.7.12 -shellcheck= .github/workflows/*.yml
 
+  upgrade:
+    # PRD-016: the latest release, built from its tag, and this commit on the same database. This commit
+    # upgrades what the release wrote, and the release then refuses the upgraded file instead of misreading
+    # it. Upgrades from every release's real data are TestUpgradeFromEveryRelease, in the test job.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
+        with:
+          go-version-file: go.mod
+          check-latest: true
+      - name: Build this commit and the latest release
+        run: |
+          # the newest release in this commit's history, other than this commit itself (a release run)
+          here="$(git tag --points-at HEAD | head -1)"
+          prev="$(git tag -l 'v*' --sort=-v:refname --merged HEAD | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | grep -vxF -e "${here:-none}" | head -1)"
+          test -n "$prev" || { echo "no earlier release tag"; exit 1; }
+          echo "latest release: $prev"
+          CGO_ENABLED=0 go build -o /tmp/ch-new ./cmd/cipherhorizon
+          git worktree add -q --detach /tmp/prev-src "$prev"
+          (cd /tmp/prev-src && CGO_ENABLED=0 go build -o /tmp/ch-old ./cmd/cipherhorizon)
+      - name: Upgrade a database the release made, then hand it back to the release
+        run: |
+          set -x
+          /tmp/ch-old db stats --db /tmp/u.db >/dev/null       # the release creates its database
+          before="$(/tmp/ch-new db status --json --db /tmp/u.db | jq '.pending | length')"
+          /tmp/ch-new db migrate --db /tmp/u.db
+          /tmp/ch-new db check --db /tmp/u.db
+          if [ "$before" -gt 0 ]; then
+            if /tmp/ch-old db stats --db /tmp/u.db > /tmp/old.out 2>&1; then
+              echo "the release opened a database this commit upgraded"; cat /tmp/old.out; exit 1
+            fi
+            grep -q "newer than this program" /tmp/old.out || { cat /tmp/old.out; exit 1; }
+            # and the backup taken before the upgrade gets it back
+            bak="$(/tmp/ch-new db status --json --db /tmp/u.db | jq -r '.backups[0].path')"
+            /tmp/ch-new db restore --db /tmp/u.db "$bak"
+            /tmp/ch-old db stats --db /tmp/u.db >/dev/null
+          else
+            /tmp/ch-old db stats --db /tmp/u.db >/dev/null       # same schema: both read it
+          fi
+
   vuln:
     # Known vulnerabilities in the dependencies and the standard library, limited to code that is reachable.
     runs-on: ubuntu-latest
diff --git a/.gitignore b/.gitignore
index 90b438c..91b388f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -24,6 +24,9 @@ Thumbs.db
 *.db
 *.db-shm
 *.db-wal
+*.db.lock
+# except the databases released versions wrote, kept for the upgrade tests (PRD-016 U-02)
+!/internal/store/testdata/upgrade/v*.db
 
 # release build output and local release scratch
 /RELEASE_NOTES.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0aebe1a..d79ded9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,32 @@ the CBOM/report/eval schema versions, the database) can change in a minor releas
 
 ## [Unreleased]
 
+### Added
+
+- **Safer upgrades** ([PRD-016](docs/product/PRD-016-upgrades-and-updates.md) Phase 0). The server still upgrades
+  its database at launch, from any earlier version, after a backup; now it also:
+  - refuses to run two servers on one database, and refuses to upgrade a database another CipherHorizon process
+    is using (a `<database>.lock` file next to it; the OS releases the lock if the process dies);
+  - checks there is room for the backup first, and changes nothing if there is not;
+  - checks the database after upgrading it, and if a step or the check fails, puts the file back exactly as it
+    was, keeps the failed copy for diagnosis, and refuses to start;
+  - records each upgrade (from which schema to which, by which version, and the backup) in the database.
+- `cipherhorizon db status` (schema, what an upgrade would do, backups, upgrade history, whether a server is
+  using it), `db check` (SQLite integrity check, references, structure; exit 2 on a problem), `db migrate`
+  (`--dry-run` to rehearse) and `db restore BACKUP-FILE` (the server must be stopped; the replaced database
+  is kept beside it).
+- `serve --migrate refuse`: for change-controlled sites, stop instead of upgrading an older database, so the
+  upgrade is run as its own step with `db migrate`.
+
+### Upgrade notes
+
+- Schema 15 → 16: adds the `upgrade_log` table. Nothing existing is changed; the upgrade takes under a second.
+- From this version on, a second `serve` on the same database exits with a message naming the process using
+  it. If you ran two servers on one file before, give each its own `--db`.
+- A database upgraded by this version is refused by 0.4.0 and earlier ("newer than this program
+  understands"). To go back, restore the backup made before the upgrade with `cipherhorizon db restore`
+  (this version) and then run the older one.
+
 ## [0.4.0] - 2026-10-22
 
 ### Security
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b77bf51..ce0193d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -47,6 +47,31 @@ rest. `go vet ./...` and `gofmt -l .` (expect no output) should be clean before
    `go test ./internal/app -update` and read the diff.
 5. **Run the checks** in "Development setup" above.
 
+## Changing the database
+
+Every install upgrades its own database when a new version starts, from whatever version it ran before,
+however many releases it skipped. That only works if these rules hold (the tests enforce most of them; see
+[PRD-016](docs/product/PRD-016-upgrades-and-updates.md) §5.2):
+
+- **Add a new step to `migrations` in `internal/store/store.go`; never edit, reorder or remove one that has
+  shipped.** Shipped steps are listed in `internal/store/migrations.lock` (`TestMigrationsLock`). Fix a
+  shipped mistake with a new step.
+- **Additive in a minor release:** new tables, nullable columns or columns with a default, new indexes.
+  Dropping or renaming a column, or changing what one means, goes in two releases: add the new one and write
+  both; then, a release later, stop using and drop the old one.
+- **A step's Go back-fill (`postMigrations`) uses only frozen code:** SQL, the standard library and helpers
+  named `…V<step>` that are copied for it. No `Store` methods, no other package of this module, no shared
+  package variables (`TestPostMigrationsUseOnlyFrozenCode`). `recordConfirmedLinkV6` is an example.
+- **Stored evidence is never rewritten.** Scan reports (`report_json`) and host inventories stay as observed;
+  a new report shape gets a new `schemaVersion` and readers keep reading the old ones.
+- **Regenerate the schema description** and review its diff:
+  `go test ./internal/store -run TestSchemaFingerprint -update-schema` (writes `schema_fingerprint.go` and
+  `internal/store/testdata/schema.txt`).
+- **Write upgrade notes:** while a step is unreleased, `CHANGELOG.md` `[Unreleased]` needs a
+  `### Upgrade notes` section saying what the upgrade does and roughly how long it takes on a large database.
+- `TestUpgradeFromEveryRelease` upgrades a database written by every past release (`internal/store/testdata/upgrade`)
+  and checks nothing was lost and the result matches a fresh install.
+
 ## Evidence and citations
 
 This is the one rule the codebase enforces in tests, not just in review: **every PQC verdict, every TLS
diff --git a/docs/deploy.md b/docs/deploy.md
index 34d8968..0801b3a 100644
--- a/docs/deploy.md
+++ b/docs/deploy.md
@@ -89,11 +89,13 @@ docker compose exec cipherhorizon /cipherhorizon db backup --db /data/cipherhori
 ```
 
 A backup is a consistent copy taken while the server runs, readable by its owner only. It holds
-password and session hashes: protect it like the database. To restore, stop the server, put the copy
-in place of the database file and start it again (`serve --db` also opens a copy directly).
+password and session hashes: protect it like the database. To restore, stop the server, run
+`cipherhorizon db restore --db FILE BACKUP` (it keeps the database it replaces) and start it again
+(`serve --db` also opens a copy directly).
 
-Upgrades migrate the database on start, after keeping a copy next to it; the newest three such
-copies are kept.
+Upgrades migrate the database on start, after keeping a copy next to it (the newest three are kept); a failed
+upgrade puts the file back as it was. `cipherhorizon db status` shows the schema, the backups and the upgrade
+history. Details: [INSTALL.md](engineering/INSTALL.md#upgrading).
 
 ## Checking the inventory scripts
 
diff --git a/docs/engineering/INSTALL.md b/docs/engineering/INSTALL.md
index 1d114c1..41f5dd9 100644
--- a/docs/engineering/INSTALL.md
+++ b/docs/engineering/INSTALL.md
@@ -184,13 +184,17 @@ docker exec cipherhorizon /cipherhorizon db backup --db /data/cipherhorizon.db /
 
 On Windows (administrator): `cipherhorizon db backup --db C:\ProgramData\CipherHorizon\cipherhorizon.db D:\backup\ch.db`.
 
-To restore:
-1. Stop the server.
-2. Put the backup in place of `cipherhorizon.db`.
-3. Delete the stale `cipherhorizon.db-wal` and `cipherhorizon.db-shm` files next to it.
-4. Start the server.
+To restore, stop the server, then:
 
-A backup opens like any database (`cipherhorizon serve --db backup.db`), so you can check it first.
+```sh
+cipherhorizon db restore --db /var/lib/cipherhorizon/cipherhorizon.db /root/cipherhorizon-2026-10-24.db
+docker run --rm -v cipherhorizon-data:/data ghcr.io/offsetsecurity/cipherhorizon:<version> db restore --db /data/cipherhorizon.db /data/backup.db
+```
+
+It checks the backup is a sound CipherHorizon database first, refuses while a server is using the database,
+and keeps the database it replaces beside it (`cipherhorizon.db.replaced-<time>`, with its `-wal` and `-shm`)
+rather than deleting it. Then start the server. `cipherhorizon db check --db FILE` examines any database,
+backup or live, without changing it.
 
 ## Upgrading
 
@@ -201,9 +205,36 @@ A backup opens like any database (`cipherhorizon serve --db backup.db`), so you
 | container | pulling the new tag, then recreating the container; the volume keeps the data |
 | binary | replacing the file |
 
-On start, the server migrates the database forward. Before each migration it saves a consistent copy
-next to the file, `cipherhorizon.db.bak-v<schema>-<time>`, and keeps the newest three. 0.x releases do
-not promise a downgrade path: to go back, restore that copy (as above) and run the older version.
+You can skip versions: any release upgrades straight from any earlier one. Every release is tested
+upgrading databases written by each earlier release.
+
+**What happens at start.** The new version upgrades the database itself, the first time it opens it (as
+`serve`, or any `db` or `user` command):
+
+1. It takes the database's lock (`cipherhorizon.db.lock`), so it never changes a file another CipherHorizon
+   process is using. A second server on the same database is refused, naming the one that holds it. Stop the
+   old version before starting the new one; Compose, Quadlet and the packages already do.
+2. It checks there is room for a backup, then saves a consistent copy next to the file,
+   `cipherhorizon.db.bak-v<schema>-<time>`, keeping the newest three.
+3. It applies each change the database lacks, in order, then checks the result.
+4. If anything fails, it puts the file back exactly as it was, keeps the failed copy as
+   `cipherhorizon.db.failed-upgrade-<time>` and refuses to start, saying why. Your data is never left
+   half-upgraded.
+
+**Seeing it before it happens.**
+
+```sh
+cipherhorizon db status --db FILE           # schema, what this version would do, backups, history
+cipherhorizon db migrate --dry-run --db FILE
+```
+
+Run the new version's binary against the file before replacing the old one, or in a throwaway container with the
+volume mounted. **Change-controlled sites** can start the server with `--migrate refuse`: it then stops instead of
+upgrading, and the upgrade is its own step, `cipherhorizon db migrate --db FILE`.
+
+**Going back.** An older version refuses a database a newer one has upgraded. To go back, stop the server,
+restore the backup made before the upgrade (`cipherhorizon db status` lists them) with `cipherhorizon db restore`,
+and run the older version. Scans made since the upgrade are not in that backup.
 
 ## Removing it
 
diff --git a/docs/engineering/RELEASING.md b/docs/engineering/RELEASING.md
index 516281f..207f8e9 100644
--- a/docs/engineering/RELEASING.md
+++ b/docs/engineering/RELEASING.md
@@ -77,11 +77,13 @@ Prerequisites: you are a maintainer; `main` is green; Actions are enabled; you h
 2. **Prepare the changelog** on a branch:
    ```sh
    git switch main && git pull && git switch -c chore/release-0.1.0
-   scripts/prepare-release.sh 0.1.0        # turns [Unreleased] into [0.1.0] - <today>, fixes compare links
+   scripts/prepare-release.sh 0.1.0        # turns [Unreleased] into [0.1.0] - <today>, fixes compare links,
+                                           # and locks the database migrations it ships (migrations.lock)
    ```
    Read the section critically: users read it, and it becomes the release notes. Every user-visible change,
-   every changed default, every new flag; **Security** and **Breaking** items first. Also confirm `SECURITY.md`
-   "Supported versions" is right.
+   every changed default, every new flag; **Security** and **Breaking** items first. If the release changes
+   the database, its **Upgrade notes** say what the upgrade does (CI refuses unreleased migrations without
+   them). Also confirm `SECURITY.md` "Supported versions" is right.
 3. **Open a PR** titled `chore(release): 0.1.0`. CI runs (including the GoReleaser and container dry run).
    Merge (squash).
 4. **Rehearse locally** (optional, needs `goreleaser`): `make snapshot` builds all six archives into `dist/`
@@ -105,6 +107,14 @@ Prerequisites: you are a maintainer; `main` is green; Actions are enabled; you h
 7. **Verify** the published release exactly as a user would (commands in [DISTRIBUTION.md](DISTRIBUTION.md#verifying-a-download)),
    and start the binary: `cipherhorizon version` shows the tag, the commit, and the build date.
 8. **Announce**: nothing to do for 0.1.0 beyond the release page; for later releases, link the changelog.
+9. **Record the release's database for the upgrade tests** (PRD-016 U-02). From `main`, after the tag exists:
+   ```sh
+   git fetch --tags && git switch -c test/upgrade-fixture-0.5.0
+   testing/upgrade/make-fixture.sh v0.5.0   # builds the tag, seeds it through its own API, writes
+                                            # internal/store/testdata/upgrade/v0.5.0.db
+   ```
+   Commit the file and open a PR. From then on every change is tested against what installs of this version
+   hold (`TestUpgradeFromEveryRelease`). A release that shipped a migration *must* have one; CI says so.
 
 ### If the workflow fails
 
@@ -154,12 +164,14 @@ patch, and if it is a vulnerability publish a GitHub Security Advisory.
 - [ ] `main` is green, no open PR I intend to include is waiting
 - [ ] Version chosen by the rules above: `___`
 - [ ] `scripts/prepare-release.sh` run; CHANGELOG section read and complete, Breaking/Security first
+- [ ] Database changed? Upgrade notes present; `migrations.lock` updated by the script and committed
 - [ ] `SECURITY.md` supported-versions text is current
 - [ ] README install instructions match reality for this version
 - [ ] Merged; tag created on the merge commit and pushed
 - [ ] `release.yml` green through `publish`
 - [ ] Downloaded an archive from the release page, verified checksum + signature + attestation, ran `version`
 - [ ] Pulled the container image, verified the signature, ran it
+- [ ] Upgrade fixture made with `testing/upgrade/make-fixture.sh` and its PR opened
 - [ ] Any follow-up issues opened for things found while releasing
 
 ## What can go wrong here, and why the pipeline is shaped this way
diff --git a/docs/product/PRD-016-upgrades-and-updates.md b/docs/product/PRD-016-upgrades-and-updates.md
new file mode 100644
index 0000000..15742e5
--- /dev/null
+++ b/docs/product/PRD-016-upgrades-and-updates.md
@@ -0,0 +1,463 @@
+# PRD-016: Upgrades and updates
+
+**Status:** Phase 0 built 2026-10-24 (branch `feat/upgrade-safety`, see §10 "As built"); Phases 1–3 and
+decisions D1–D7 open
+**Roles:** architect, product, build and release engineering
+**Scope:** how a CipherHorizon install learns about, gets, and safely applies a new version, on every
+channel (Docker/Podman, Linux packages, Windows service, macOS, bare binary) and from any older version.
+
+---
+
+## 1. The problem in one paragraph
+
+We ship often (0.1.0 → 0.4.0 in nine days). Every install is self-hosted and holds an organisation's only
+copy of its scan history in one SQLite file. Today an operator must notice a release on their own, upgrade
+by hand with a different procedure per platform, and trust that the database migrates. Nothing tests that a
+database made by a *released* version upgrades cleanly, nothing stops two versions touching one file, and
+there is no tested way back. As the user base grows, people will skip versions, run old collectors against
+new servers, and upgrade unattended. This PRD makes all of that boring and safe.
+
+## 2. What already exists (audited 2026-10-24)
+
+Good foundations; the plan builds on them rather than replacing them.
+
+| Area | Today | Where |
+|---|---|---|
+| Schema migrations | Ordered list of SQL steps, one transaction each, optional Go back-fill in the same transaction; version recorded in `schema_migrations` | `internal/store/store.go` `migrations`, `postMigrations`, `migrate()` |
+| Skipping versions | Already works in principle: the binary runs every missing step in order, so 0.1.0 → 0.4.0 runs step 15 only; an older file runs all it lacks | same |
+| Newer database | Refused with a clear error ("schema version N is newer than this program understands") | `migrate()` |
+| Pre-migration backup | `VACUUM INTO <db>.bak-v<schema>-<time>`, owner-only, newest 3 kept; if the backup fails nothing is changed | `internal/store/systems.go` `backup`, `pruneBackups` |
+| Frozen migrations | A test pins the SHA-256 of migrations **1–3 only** | `internal/store/graph_test.go` `TestFrozenMigrationsAreUnchanged` |
+| Legacy data tests | Hand-built legacy databases, failed migration leaves the file intact | `graph_test.go`, `migrate_test.go`, `bands_test.go` |
+| Stored report formats | Versioned (`tls-report/1`, `tls-report/2`, `ssh-report/1`); old shapes are still read | `internal/tlsprobe/report.go`, `internal/server/ssh.go` |
+| Release | Tag → GoReleaser archives, deb/rpm, SBOMs, cosign-signed checksums, provenance; GHCR image signed by digest | `.goreleaser.yaml`, `.github/workflows/release.yml` |
+| Upgrade docs | One table per channel; "0.x releases do not promise a downgrade path" | `docs/engineering/INSTALL.md#upgrading` |
+| Update awareness | Deliberately none: "No telemetry, no update check, no external requests at runtime" | `docs/engineering/DISTRIBUTION.md` |
+
+Schema version shipped per release (counted from each tag):
+
+| Release | Schema |
+|---|---|
+| v0.1.0, v0.1.1, v0.2.0, v0.3.0 | 14 |
+| v0.4.0 | 15 |
+
+### Gaps found
+
+| # | Gap | Risk |
+|---|---|---|
+| G1 | Frozen-migration test pins 1–3, but 0.1.0 shipped 14 and 0.4.0 ships 15. Steps 4–15 can be edited silently. | An edited released step never re-runs on existing installs: fresh and upgraded databases drift apart. |
+| G2 | No test opens a database **produced by a real released binary**. Legacy fixtures are hand-made. | A back-fill that works on synthetic data fails on real data at a customer. |
+| G3 | No check that "fresh install at HEAD" and "upgraded from vX" give the same schema. | Silent drift (a missing index, a column default) shows up months later. |
+| G4 | No guard against two processes on one database (old container still running, `serve` in a terminal while the service runs, two pods on one volume). | Two versions migrating or writing at once. |
+| G5 | Backup does not check free disk space first; `VACUUM INTO` needs about the database's size again. | Upgrade fails at start on a full disk, service flaps. (The file is safe: nothing is changed.) |
+| G6 | Restore is four manual steps (stop, copy, delete `-wal`/`-shm`, start). | The step people get wrong under pressure. |
+| G7 | Windows `service install` refuses when the service exists; upgrade is "stop, copy exe, start", and the service's flags are only changed by uninstall/install. | Error-prone, not scriptable, flags lost. |
+| G8 | Containers: only immutable `X.Y.Z` tags, no "latest" before 1.0, nothing wired for unattended updates. | Container users never upgrade, or use `:latest` from somewhere unofficial. |
+| G9 | No APT/YUM repository, Homebrew tap, Scoop bucket or winget manifest: every platform upgrade is a manual download. | Low uptake of security fixes. |
+| G10 | No way for a running server to tell the operator a newer or security release exists. | Old, vulnerable installs in the field. |
+| G11 | Bundled reference data (root stores, CT logs, distrusted keys) only refreshes with a release; there is no scheduled refresh. | Results go stale even when nobody changes code. |
+| G12 | No written skew policy between server and collector, or for `/api/v1` clients and CLI flags. | Fleets break silently when the server moves ahead of collectors. |
+| G13 | UI assets are served at fixed URLs (`/style.css`, `/js/app.js`) with no versioned path or cache policy. | After an upgrade a browser can combine old JavaScript with the new API (to verify; low risk today). |
+
+## 3. How mature open-source projects do it (what we take, what we skip)
+
+| Project | Practice | Take for us? |
+|---|---|---|
+| **GitLab** | "Required upgrade stops": certain versions must be installed before later ones so background migrations finish; stops announced two milestones ahead; the project actively works to *avoid* adding stops ([upgrade docs](https://archives.docs.gitlab.com/17.2/ee/update/index.html), [avoiding required stops](https://docs.GitLab.com/ee/development/avoiding_required_stops.html)) | Take the *discipline* (stops are a cost; announce them early). We avoid stops entirely before 2.0 because our migrations are small and synchronous. |
+| **Mattermost** | Migrations backwards-compatible only to the last ESR; skip-upgrades go ESR → ESR ([release policy](https://docs.mattermost.com/product-overview/release-policy.html), [common ESR upgrade](https://docs.mattermost.com/product-overview/common-esr-support-upgrade.html)) | Take "the tested path is what we promise", and test it in CI. No ESRs yet. |
+| **Forgejo / Gitea** | Single binary migrates on start; `doctor check --all` after upgrade; backup first ([Forgejo upgrade guide](https://forgejo.org/docs/latest/admin/upgrade/)) | Take: a `db check` / doctor command, run automatically after migrating. |
+| **Syncthing** | Opt-out auto-upgrade; each binary has a signature made with a release key whose public half is compiled in; mismatch aborts and deletes temp files; disabled in distro packages ([release signing](https://docs.syncthing.net/dev/release-signing.html)) | Take the model for self-update of bare/Windows/macOS installs, and "packages and containers never self-update". |
+| **Grafana, Home Assistant** | SQLite + migration log table, automatic backup before upgrade, refuse newer schema | Already matched. |
+| **Tailscale, Caddy** | `tailscale update` / `caddy upgrade` command that knows how it was installed and does the right thing per channel | Take: one `cipherhorizon upgrade` that dispatches by install channel. |
+| **Podman Quadlet** | `AutoUpdate=registry` + `podman-auto-update.timer`; rolls the container back if the new one fails to start | Take: the most robust unattended path we can offer for free. |
+| **Watchtower / Diun / Renovate** | Container users pick their own update agent, keyed on tags | Support by publishing sensible floating tags; document, don't build. |
+| **Kubernetes** | Explicit version-skew policy (components N-1/N-2) | Take for server ↔ collector and for API clients. |
+| **Rails / Django / expand-contract** | Additive change first, destructive change only after the code stopped using it | Take as the migration rule set (§5.2). |
+| **SQLite itself** | File format carries a write-version / read-version so old readers know if they may write | Take for the downgrade window (§5.5). |
+
+## 4. Principles
+
+1. **Any released version upgrades straight to the latest, in one step, on every channel.** No required
+   stops before 2.0. This is a promise, so it is tested in CI from every released version (§6).
+2. **The binary is the migrator.** No separate migration tool, no SQL scripts for operators. Starting the new
+   version is the upgrade; `db migrate` exists only for people who want the step explicit.
+3. **Never lose data, never half-migrate.** Back up first, one transaction per step, verify afterwards, refuse
+   to start rather than run on a doubtful file.
+4. **The package manager or orchestrator owns the binary when there is one.** `apt`, `dnf`, `brew`, `scoop`,
+   `winget`, the container runtime. CipherHorizon self-updates only where nothing else does (bare archive,
+   Windows service from the zip, macOS launchd from the tarball).
+5. **Notify by default, apply only when asked.** A scanner in a security team's estate must not change itself
+   without consent. Unattended updates are opt-in per channel.
+6. **Privacy stays.** Any update check is a single anonymous GET of a public signed file, can be turned off,
+   and works offline by importing the file. No telemetry, no install ID.
+7. **One procedure, one vocabulary, every platform.** The same five steps (§7) and the same commands; only the
+   tool that swaps the binary differs.
+
+## 5. Database: schema changes that cannot break an upgrade
+
+### 5.1 Mechanics (mostly in place, tightened)
+
+At start, `store.Open`:
+
+1. Takes the **instance lock** (new, G4): an OS file lock on `<db>.lock` (`flock` on Unix, `LockFileEx` on
+   Windows, both available without cgo). A second process gets "another CipherHorizon (pid N, version X) is
+   using this database" and exits non-zero. This also covers a container recreated before the old one stopped.
+2. Reads `schema_migrations`. Newer than known → refuse (exists). Equal → continue.
+3. **Checks free space** (new, G5): needs at least `1.2 × database size` free in the backup folder, or refuses
+   with the number of bytes needed. Nothing changed.
+4. Backs up with `VACUUM INTO` (exists), records the backup in a new `upgrade_log` table row (from-version,
+   to-version, from-schema, to-schema, backup path, started, finished, result).
+5. Runs each missing step in its own transaction (exists).
+6. **Verifies** (new): `PRAGMA integrity_check`, `PRAGMA foreign_key_check`, and the schema fingerprint check
+   (§5.4). Failure → restore the backup automatically, log why, refuse to start. The operator sees one
+   message with the backup path and the command to report it.
+7. Writes the finished row in `upgrade_log`; the About page shows "Upgraded from 0.3.0 to 0.5.0 on …".
+
+### 5.2 Rules every migration follows (enforced in review and CI)
+
+| Rule | Why | Enforced by |
+|---|---|---|
+| A released migration is never edited, reordered or removed. Fix forward with a new step. | Existing installs never re-run an edited step. | `migrations.lock` (§6.1) checked in CI |
+| Additive changes only in a minor release: new table, new nullable column or column with a default, new index. | An older binary can still read the file (enables §5.5). | Review checklist; `compat` flag per step |
+| Destructive changes (drop/rename column, change meaning) follow **expand → migrate → contract** across at least two releases: add the new column and write both; back-fill; stop reading the old one; drop it in a later release. | Rollback stays possible for one release. | Review; the step is marked `breaksOlder: true` |
+| Go back-fills (`postMigrations`) use only code frozen with them: local SQL, local copies of any helper. Never call today's store or evaluation code. | Today's code changes; a back-fill must behave the same in 2028 as it did on release day. | Lint rule: a `postMigrations` func may not import `internal/eval`, `internal/server` etc. (archtest) |
+| A back-fill that touches every row of a large table runs in batches inside its transaction and logs progress. | Big estates; visible progress instead of a "hung" start. | Review |
+| Stored report JSON is never rewritten by a migration. New report shapes get a new `schemaVersion`; readers keep reading old ones (as `tls-report/1` today). | Evidence stays as observed; scoring changes are re-evaluation, not data rewrite. | Existing pattern, now written down |
+| Every schema change adds an **Upgrade notes** entry to `CHANGELOG.md`. | Operators see what will happen before they upgrade. | CI: if `migrations` changed, `## [Unreleased]` must contain `### Upgrade notes` |
+| SQLite feature use stays within the bundled `modernc.org/sqlite` version; bumping it is a release-notes item. | `RENAME COLUMN`, `DROP COLUMN` etc. depend on the engine version. | Dependency review |
+
+### 5.3 Skipping versions
+
+Because every step is ordered and self-contained, 0.1.0 → 1.4.0 simply runs every step between them in order,
+with one backup at the start. We guarantee this until 2.0. If one day a migration genuinely needs an
+intermediate release (for example a long background job), we follow GitLab's rule: announce the required stop
+at least two minor releases ahead, and the newer binary refuses older schemas with "upgrade to 1.9 first" and a
+link, never a cryptic SQL error. At 2.0 we may **squash** steps 1..N into one baseline; from then on 2.x opens
+databases from the last 1.x and later only. That decision is recorded in the release manifest as
+`minUpgradeFrom` (§8.2) so the update check can warn before anyone downloads.
+
+### 5.4 Fresh equals upgraded
+
+New test (G3): for every released schema `S`, open the fixture from §6.2, migrate to HEAD, dump
+`sqlite_master` (tables, columns, indexes, triggers, normalised) and compare with a fresh HEAD database. Any
+difference fails CI. The fingerprint of HEAD's schema is compiled into the binary and checked at step 6 of
+§5.1, so a hand-edited database in the field is caught too.
+
+### 5.5 Going back (downgrade window)
+
+Today: restore the pre-migration backup. Plan:
+
+- **`cipherhorizon db restore <backup>`** (G6): stops nothing on its own, refuses if the instance lock is held,
+  checks the backup's integrity, moves the current file aside (`.replaced-<time>`), puts the backup in place and
+  removes stale `-wal`/`-shm`. Works the same on every OS and inside a container (`docker run --rm -v
+  data:/data image db restore …`).
+- **Compatibility floor** (P2, before 1.0): the database records `compat_floor`, the oldest schema whose binary
+  may still open it. Additive steps leave it alone; a `breaksOlder` step raises it. An older binary may open a
+  newer file when its own schema ≥ `compat_floor`, ignoring tables and columns it does not know. Result: a patch
+  or a purely additive minor can be rolled back by just running the old binary, no restore, no lost scans. This
+  is SQLite's own read/write-version idea applied to our schema.
+- After 1.0 the promise is: **rollback by binary to the previous minor works unless the release notes say
+  otherwise; rollback by backup always works.**
+
+### 5.6 Operator commands (all platforms, same words)
+
+| Command | Does |
+|---|---|
+| `cipherhorizon db status` | Schema version, what this binary would run, compat floor, backups present, last upgrade |
+| `cipherhorizon db migrate [--dry-run]` | Runs (or lists) pending steps explicitly, with the same backup and checks |
+| `cipherhorizon db check` | Integrity, foreign keys, schema fingerprint (Forgejo `doctor` equivalent) |
+| `cipherhorizon db backup <file>` | Exists |
+| `cipherhorizon db restore <file>` | New, §5.5 |
+| `serve --migrate=auto\|refuse` | `auto` (default) migrates at start; `refuse` exits with "run `db migrate`" for change-controlled shops |
+
+## 6. Release engineering: proving every upgrade path before release
+
+### 6.1 Lock the migrations (G1)
+
+Replace the 1–3 hash map with `internal/store/migrations.lock`: one line per released step, `N sha256`.
+`scripts/prepare-release.sh` appends the new steps when cutting a release. CI fails if a locked step's hash
+changes or a locked step disappears. Unreleased steps (above the last release) may still be edited freely.
+
+### 6.2 Golden databases from real releases (G2)
+
+For each release, the release workflow runs the **released binary** against the hermetic demo targets
+(`demo-targets`) and a scripted scenario — TLS and SSH scans, an imported inventory, a system, a triaged
+finding, an account with sign-in on, settings changed — then `db backup`s the result into
+`testdata/upgrade/v<version>.db` (small, synthetic, no secrets beyond test hashes). A bot PR commits it. Seed
+the set now by running v0.1.0, v0.2.0, v0.3.0 and v0.4.0 from their published archives.
+
+### 6.3 The upgrade matrix (release gate)
+
+A CI job, required on `main` and on every release PR:
+
+| Check | From | To |
+|---|---|---|
+| Direct upgrade opens, migrates, passes `db check`, row counts and key values preserved | every `testdata/upgrade/*.db` | HEAD |
+| Fresh equals upgraded (§5.4) | every fixture | HEAD |
+| Chained equals direct: v0.1 → v0.2 → … → HEAD gives the same schema and data as v0.1 → HEAD | oldest fixture | HEAD |
+| Newer schema refused cleanly | HEAD-migrated file | previous release binary |
+| Compat-floor rollback (once §5.5 lands) | HEAD-migrated file | previous release binary, opens and serves |
+| Failed step leaves the file intact (exists) | fixture + injected failure | HEAD |
+| Server UI and API smoke on the upgraded file (journey checks) | newest fixture | HEAD |
+
+The last released binary for each OS is downloaded once per CI run from GitHub Releases and its checksum
+verified, so the "old binary" rows run the real thing.
+
+### 6.4 Per-channel upgrade smoke (nightly, and before each release)
+
+| Channel | Test |
+|---|---|
+| deb | Debian container: install previous `.deb`, enable service, seed, `apt install ./new.deb`, assert service restarted, schema migrated, data present, `/etc/cipherhorizon/env` kept |
+| rpm | Same on Rocky/Fedora with `dnf` |
+| Container | `docker run` previous tag on a volume, seed, recreate with new tag, health check passes, data present; same with Podman Quadlet `AutoUpdate` |
+| Windows service | `windows-latest` runner: `service install` previous zip, seed, `cipherhorizon upgrade --from-file new.zip` (§7.3), service running, data present, flags kept |
+| macOS | `macos-latest` runner: launchd agent with previous tarball, upgrade, agent running, data present |
+| Self-update | Each runner: point the update check at a local signed test manifest; corrupt signature → refused; broken new binary → rolled back |
+
+### 6.5 Release artefacts added
+
+- `releases.json` manifest (§8.2), signed like `checksums.txt`.
+- `UPGRADING.md` section generated from the changelog's **Upgrade notes**, included in release notes.
+- Floating container tags (§7.1).
+- Brew formula, Scoop manifest, winget manifest, APT/YUM repository update (§7.2).
+
+### 6.6 Scheduled data refresh (G11)
+
+A monthly scheduled workflow regenerates `internal/refdata` from CCADB, the CT log list and the distrust
+list, runs the tests, and opens a PR. Merging it is a patch release (`0.4.1`: "reference data refreshed"). This
+turns stale-data risk into a routine, low-risk upgrade and keeps people in the habit of upgrading.
+
+## 7. Per-platform: one procedure, each channel's own tool
+
+Every channel follows the same five steps: **learn → fetch → verify → swap → check** (and roll back if the
+check fails). The table says who does each step.
+
+| Channel | Learn of a release | Upgrade (manual) | Unattended (opt-in) | Verify | Roll back |
+|---|---|---|---|---|---|
+| **Docker / Compose** | UI banner (§8); Diun/Renovate on tags | `docker compose pull && docker compose up -d` | Watchtower or Renovate on the `0.4` / `0` tag | `cosign verify` by digest (documented); image signed | Re-run the previous tag; DB rollback by compat floor or `db restore` |
+| **Podman Quadlet** | UI banner | change tag, `systemctl restart` | `AutoUpdate=registry` + `podman-auto-update.timer` (ships commented in `deploy/cipherhorizon.container`) | registry signature policy (`policy.json` sigstore) documented | **Automatic**: Podman rolls back when the new unit fails health |
+| **Debian / Ubuntu** | `apt list --upgradable`; UI banner | `sudo apt update && sudo apt upgrade` | `unattended-upgrades` with our origin allowed | repo signed (GPG key published; packages also listed in signed `checksums.txt`) | `apt install cipherhorizon=<old>`; DB as above |
+| **RHEL / Fedora / SUSE** | `dnf check-update`; UI banner | `sudo dnf upgrade cipherhorizon` | `dnf-automatic` | repo `gpgcheck=1` | `dnf downgrade`; DB as above |
+| **Windows (service)** | UI banner; `winget upgrade` list | `winget upgrade OffsetSecurity.CipherHorizon` / `scoop update cipherhorizon`, or `cipherhorizon upgrade` | `cipherhorizon upgrade --schedule` registers a weekly task, off by default | checksum + signature verified by the binary itself (§8.3); Authenticode signing later | automatic on failed health (§7.3); `cipherhorizon upgrade --rollback` |
+| **macOS** | UI banner; `brew outdated` | `brew upgrade cipherhorizon` (tap), or `cipherhorizon upgrade` for the tarball install | `brew autoupdate` (user's choice) or `cipherhorizon upgrade --schedule` (launchd) | as Windows; notarisation later | as Windows |
+| **Bare binary** (any OS) | UI banner; `cipherhorizon version --check` | `cipherhorizon upgrade` | none (it is someone's terminal) | as Windows | keeps `cipherhorizon.old` next to it |
+| **Collector on endpoints** | server shows "N collectors older than the supported window" | fleet tooling (Intune, SCCM, Ansible, Jamf) using the server's own `/api/v1/collector/binaries` | fleet tooling | SHA-256 listed by the server and in `checksums.txt` | fleet tooling |
+
+### 7.1 Containers
+
+- Publish `X.Y.Z` (immutable, what docs pin), **`X.Y`** (patch releases, safe to follow) and, from 1.0, `X` and
+  `latest`. Before 1.0 publish `0.4` style tags only; that keeps "no latest before 1.0" while letting
+  Watchtower/Quadlet follow patch fixes.
+- Never two containers on one volume: the instance lock (§5.1) makes this an error instead of corruption; the
+  docs say `Recreate`, not rolling update, for any orchestrator (and a future Helm chart sets
+  `strategy: Recreate`, one replica).
+- Migration runs inside the container at start; the backup lands in the volume, so it survives the container.
+- Pre-migration backups count against volume size; `db status` shows it.
+
+### 7.2 Package channels to add (G9)
+
+| Channel | How | Cost |
+|---|---|---|
+| Homebrew tap `offsetsecurity/homebrew-tap` | GoReleaser `brews` (or `homebrew_casks`) | one repo + token |
+| Scoop bucket `offsetsecurity/scoop-bucket` | GoReleaser `scoops` | one repo + token |
+| winget | GoReleaser `winget` (opens PR to `microsoft/winget-pkgs`) | review latency; fine before 1.0 if marked pre-release-free versions only — **owner decision** |
+| APT + YUM repository | Option A: Cloudsmith OSS (free for open source, signed, hosted). Option B: self-host on GitHub Pages, signed by a repo key, built in `release.yml` with `aptly`/`createrepo_c`. | A: none; B: a GPG key to guard — **owner decision** |
+| Chocolatey | later | moderation queue |
+
+### 7.3 Windows service and the bare binary: `cipherhorizon upgrade` (G7)
+
+- `service install` on an existing service becomes **upgrade in place**: stops it, replaces
+  `C:\Program Files\CipherHorizon\cipherhorizon.exe`, keeps the recorded flags unless new ones are given, starts,
+  health-checks. `service reconfigure <flags>` changes flags without reinstalling.
+- `cipherhorizon upgrade [--to X.Y.Z] [--from-file archive]`:
+  1. reads the install channel stamped at build time (`-X version.Channel=archive|deb|rpm|container|brew|scoop|winget`)
+     and, for anything but `archive`, prints the right command for that channel and exits (Tailscale/Caddy model);
+  2. fetches the manifest and the archive for this OS/arch, verifies (§8.3);
+  3. `db backup` to the data folder;
+  4. Windows: stops the service, renames the running exe to `cipherhorizon.old.exe` (a running exe can be renamed,
+     not overwritten), puts the new one in place, starts; Unix: atomic rename, restart the launchd agent /
+     systemd unit if it runs;
+  5. waits up to 60 s for `/api/v1/health`; on failure puts the old binary back, restores the backup **only if a
+     migration ran**, starts the old one, and reports what happened;
+  6. records the result in `upgrade_log`.
+- Requires administrator on Windows (service) and write access to the binary elsewhere; says so up front.
+
+## 8. Knowing an update exists (G10)
+
+### 8.1 Behaviour
+
+- **Owner decision:** default **on with disclosure** (recommended; Syncthing, Grafana, Gitea do this) or **off**.
+  Either way: Settings → Updates shows the state, a `--update-check=off` flag and `CIPHERHORIZON_UPDATE_CHECK=off`
+  turn it off, and air-gapped sites can import a downloaded `releases.json`.
+- Once a day the server GETs one static file (`https://offsetsecurity.github.io/cipherhorizon/releases.json`, or
+  the release asset), with no cookies, no identifiers, a fixed `User-Agent: CipherHorizon` (no version, so the
+  request carries nothing about the install).
+- The UI shows a quiet banner to administrators: "0.5.0 is available" — and a red one for "security fix", with
+  the one command for *this* install's channel (from §7.3 step 1) and a link to the upgrade notes.
+- `cipherhorizon version --check` does the same from the command line, for scripts and monitoring (exit code 10
+  when an update exists, 11 when a security update exists).
+
+### 8.2 `releases.json` (signed)
+
+```json
+{
+  "schema": "cipherhorizon-releases/1",
+  "latest": "0.5.0",
+  "releases": [
+    {
+      "version": "0.5.0",
+      "date": "2026-11-05",
+      "security": false,
+      "dbSchema": 17,
+      "minUpgradeFrom": "0.1.0",
+      "compatFloor": 15,
+      "collectorMin": "0.3.0",
+      "notes": "https://github.com/offsetsecurity/cipherhorizon/releases/tag/v0.5.0",
+      "upgradeNotes": ["Adds an index on scans(asset_id, started); first start takes a few seconds on large databases."]
+    }
+  ]
+}
+```
+
+Generated by `release.yml` from the tag, the migration lock and the changelog, never by hand.
+
+### 8.3 Verifying what we download
+
+Two options, **owner decision**:
+
+- **A. Sigstore keyless (recommended):** verify `checksums.txt.sigstore.json` with `sigstore-go`, pinned to the
+  identity `https://github.com/offsetsecurity/cipherhorizon/.github/workflows/release.yml@refs/tags/v*` and the
+  GitHub OIDC issuer. Same trust as today's manual verification; no key to keep. Cost: a sizeable dependency and
+  a trusted-root file that must be refreshed (ship it in the binary, refresh in the monthly data PR).
+- **B. Release key (Syncthing model):** an Ed25519 key held as a GitHub Actions secret signs `checksums.txt` and
+  `releases.json`; its public half is compiled in. Small and offline-friendly. Cost: a long-lived secret and a
+  rotation plan (ship next key's public half one release ahead).
+
+Either way: verify the manifest signature, then the archive's SHA-256 from the signed checksums, then refuse a
+version lower than the running one (downgrade attack) unless `--allow-downgrade`.
+
+## 9. Everything else an upgrade touches
+
+| Area | Policy |
+|---|---|
+| **Server ↔ collector skew** (G12) | Server accepts inventories from collectors up to **two minor releases older** and any newer patch; ADR-0017 schema validation already rejects unknown shapes clearly. The server lists collectors outside the window on the estate page and serves its own matching collector binaries. Collector never self-updates (fleet tooling owns it). |
+| **`/api/v1` clients** | No breaking change within v1 after 1.0. Removals are announced with `Deprecation` and `Sunset` response headers (RFC 9745 / RFC 8594) for at least two minor releases; OpenAPI marks them `deprecated`. |
+| **CLI flags and env** | A renamed flag keeps the old name as an alias for two minor releases, printing one warning line. Removed flags fail with "use --new-name". Same for `CIPHERHORIZON_*` variables. |
+| **Config files** (`/etc/cipherhorizon/env`, `config.yaml`) | Package installs mark them `config|noreplace` (exists). Today `config.yaml` rejects unknown keys, which is right for typos but means a config written for a newer version stops an older one: keep the error for keys never known, and make keys from a *newer* release a warning (needs a small list of known-future keys in the manifest, or a `version:` key). A future breaking config change carries a `version:` key and an automatic in-memory translation for one major. |
+| **Settings stored in the database** | Changed by migrations like any schema change; defaults for new settings come from code, so upgrades never need a settings step. |
+| **Accounts and sessions** | Sessions survive an upgrade unless the release notes say otherwise. If the password hashing parameters change, a hash is upgraded at the user's next sign-in, never forced. |
+| **Stored scan results vs. new scoring** | Results keep the version that evaluated them. After an upgrade that changes scoring, the UI says "evaluated by 0.4.0; re-evaluate with 0.5.0" (re-evaluation is from stored evidence, no rescan). Changelog lists scoring changes under "Changed" (exists). |
+| **Report and CBOM formats** | `schemaVersion` on every stored and exported document (exists). Readers read every old version forever; exporters may emit only the newest. A CBOM consumer change is a release-notes item. |
+| **Browser cache** (G13) | Serve UI assets under `/assets/<version>/…` with `Cache-Control: immutable` and `index.html` with `no-cache`, so a browser never mixes old JavaScript with a new API. |
+| **Embedded inventory scripts** | Already versioned and hashed per release; the server marks inventories produced by an older script version. |
+| **Reference data** | Monthly refresh release (§6.6). |
+| **Go toolchain and dependencies** | Patch releases for Go security fixes and `govulncheck` findings; Dependabot already in place. |
+| **Signing continuity** | Keyless identity stays the workflow path; renaming the repo or org (RENAME.md) changes it, so a rename ships a release that trusts both identities first. |
+| **Data growth** | Backups count against disk: `keepBackups = 3` plus the live file. `db status` and the About page show the total. |
+| **Very large or slow migrations** | Progress logged per step; a step expected to exceed a minute is listed in Upgrade notes with an estimate per 100k scans. |
+| **Support window** | Before 1.0: latest release only. After 1.0: latest minor, plus security fixes for the previous minor for 6 months. Upgrade-from window: every release since 0.1.0 until 2.0. |
+
+## 10. Phased plan
+
+Each phase is shippable alone. Effort is rough engineering days.
+
+### Phase 0 — make upgrades provably safe (next release; ~5 days)
+
+| ID | Item | Gap |
+|---|---|---|
+| U-01 | `migrations.lock` for all released steps (1–15); CI check | G1 |
+| U-02 | Golden databases from v0.1.0, v0.2.0, v0.3.0, v0.4.0 made by the real binaries; generator script | G2 |
+| U-03 | Upgrade matrix job (§6.3) as a required check | G2, G3 |
+| U-04 | Fresh-equals-upgraded schema test + compiled-in fingerprint check at start | G3 |
+| U-05 | Instance lock on `<db>.lock` | G4 |
+| U-06 | Free-space check before backup | G5 |
+| U-07 | `db status`, `db check`, `db restore`, `db migrate --dry-run`; post-migration verify + automatic restore on failure; `upgrade_log` table | G6 |
+| U-08 | CI rule: migration change requires `### Upgrade notes` in the changelog | — |
+| U-09 | archtest: `postMigrations` may not import live evaluation/server code | — |
+| U-10 | Write the migration rules (§5.2) into `CONTRIBUTING.md` | — |
+
+**As built (2026-10-24).** All ten items, with these differences from the plan above:
+
+- **Structure mismatch warns, does not refuse.** After an upgrade the schema fingerprint is compared with the
+  compiled-in one; a difference is logged and shown by `db status` / `db check`, not refused. A database from a
+  pre-0.1.0 build or a hand edit has worked with every release so far, and refusing would lock its owner out.
+  Integrity and new foreign-key violations *do* refuse and restore. The CI matrix is the real gate for structure.
+- **Foreign keys:** violations already in a file do not block its upgrade; only violations the upgrade adds do.
+- **A failed upgrade restores the pre-upgrade backup** (not just "the last good step"), keeps one
+  `<db>.failed-upgrade-<time>` copy, and prunes older ones so a service restart loop cannot fill the disk.
+- **Locking needs the database lock only to change the file:** `serve` holds it for its life; other commands
+  take it only when they would upgrade, so `db backup` still works while a server runs.
+- **New platform layer `internal/osfile`** (flock / LockFileEx, free space): the architecture test allows only
+  platform layers to import `x/sys/windows`, so `store` stays OS-free.
+- **U-09 found a real case:** migration 6's back-fill called the live `recordManualLinkTx`, which uses
+  `internal/estate` types. It now calls `recordConfirmedLinkV6`, a frozen copy that writes byte-identical rows
+  (checked against the live helper before freezing). Migration 10's column list became `timestampColumnsV10`:
+  adding a later table to the shared map would have broken upgrades from before step 10.
+- **U-08 is a Go test**, not a workflow rule: `TestUnreleasedMigrationsHaveUpgradeNotes` fails while a step is
+  missing from `migrations.lock` and `[Unreleased]` has no `### Upgrade notes`.
+- **U-03:** `TestUpgradeFromEveryRelease` runs in the existing test job on Linux, Windows and macOS; a new
+  `upgrade` CI job builds the latest release from its tag and checks it refuses, then (after `db restore`)
+  reads, a database this commit upgraded.
+- **Fixtures:** `testing/upgrade/make-fixture.sh vX.Y.Z` builds the tag, runs it against the demo targets
+  (TLS, PQ certificate, SSH, STARTTLS, a dead port; two scans each), triages a finding, links two endpoints,
+  uploads a host inventory and adds an admin account, all through that release's own API and CLI. About 0.7–0.9 MB
+  per release.
+
+### Phase 1 — every platform upgrades with its own tool (~6 days)
+
+| ID | Item | Gap |
+|---|---|---|
+| U-11 | Floating `X.Y` container tags; Quadlet `AutoUpdate=registry` documented and shipped commented-in | G8 |
+| U-12 | Homebrew tap, Scoop bucket (GoReleaser) | G9 |
+| U-13 | APT/YUM repository (option per owner decision) | G9 |
+| U-14 | Windows `service install` upgrades in place; `service reconfigure` | G7 |
+| U-15 | Install channel stamped at build; `cipherhorizon upgrade` prints the right command per channel | — |
+| U-16 | Per-channel upgrade smoke tests (§6.4), nightly + pre-release | — |
+| U-17 | Versioned UI asset paths and cache headers | G13 |
+| U-18 | Monthly reference-data refresh workflow | G11 |
+
+### Phase 2 — the server tells you, and can do it for you (~7 days)
+
+| ID | Item | Gap |
+|---|---|---|
+| U-19 | Signed `releases.json` generated in `release.yml` | G10 |
+| U-20 | Update check (default per owner decision), Settings → Updates, offline import, banner, `version --check` | G10 |
+| U-21 | Self-update for archive / Windows service / macOS launchd with verify, backup, health-gated rollback | G10 |
+| U-22 | Collector skew window: shown on the estate page, enforced on import with a clear message | G12 |
+| U-23 | winget manifest (owner decision on timing) | G9 |
+
+### Phase 3 — 1.0 promises (~5 days, part of the 1.0 checklist)
+
+| ID | Item |
+|---|---|
+| U-24 | Compatibility floor: rollback by running the previous minor's binary |
+| U-25 | API deprecation headers + OpenAPI `deprecated`; flag aliases with warnings |
+| U-26 | Re-evaluate stored results after a scoring change, from the UI |
+| U-27 | Published support and upgrade policy page (UPGRADING.md), linked from every release |
+
+`RELEASING.md` criterion 2 for 1.0 ("the database migration path is tested from every released version") is met
+by U-02 and U-03.
+
+## 11. Decisions for the owner
+
+| # | Decision | Recommendation |
+|---|---|---|
+| D1 | Update check default: on with disclosure, or off | **On, with disclosure** and a one-switch off; offline import for air-gapped sites. Security-fix uptake matters more for a security tool. |
+| D2 | Self-update signature: Sigstore keyless (A) or release Ed25519 key (B) | **A**, matching how users already verify; B if the binary-size cost is unacceptable. A needs a new dependency, so an ADR first (ADR-0014 rule). B needs none (`crypto/ed25519`). |
+| D3 | APT/YUM hosting: Cloudsmith OSS or self-hosted on Pages | **Cloudsmith** (no key to guard); revisit if terms change. |
+| D4 | Floating `0.Y` container tags before 1.0 | **Yes**, `0.Y` only; still no `latest` before 1.0. |
+| D5 | winget/Chocolatey before 1.0 | winget **yes** (stable versions only), Chocolatey after 1.0. |
+| D6 | Unattended self-update for Windows/macOS | **Offer, off by default** (`upgrade --schedule`). |
+| D7 | Upgrade-from window guarantee | **Every release since 0.1.0 until 2.0**; no required stops before 2.0. |
+
+## 12. Acceptance
+
+- CI proves direct upgrade from every released version to HEAD, fresh-equals-upgraded, and clean refusal of a
+  newer file, on every PR.
+- On each channel, a scripted upgrade from the previous release keeps all data and settings and comes back
+  healthy; a deliberately broken new version leaves the install running the old one with its data.
+- Two processes on one database: the second refuses with a clear message on Linux, Windows and macOS, and in
+  containers sharing a volume.
+- An operator on any channel can answer "am I up to date, and how do I upgrade?" from the UI or one command,
+  without reading docs.
+- No request leaves an install when the update check is off; with it on, exactly one anonymous GET a day.
diff --git a/internal/app/db.go b/internal/app/db.go
index 4c260ee..2096917 100644
--- a/internal/app/db.go
+++ b/internal/app/db.go
@@ -2,41 +2,77 @@ package app
 
 import (
 	"encoding/json"
+	"errors"
 	"flag"
 	"fmt"
 	"io"
 	"os"
+	"strings"
 
 	"github.com/offsetsecurity/cipherhorizon/internal/store"
 )
 
-// dbCmd runs maintenance on the database file. The estate graph is a projection of
-// the stored documents (PRD-003 REQ-MOD-1), so it can always be dropped and rebuilt.
+// dbCmd runs maintenance on the database file: upgrading it, checking it, backing it up and
+// restoring it (PRD-016), and rebuilding the estate graph, which is a projection of the stored
+// documents (PRD-003 REQ-MOD-1) and so can always be dropped and rebuilt.
 func dbCmd(args []string, env Env) int {
 	if len(args) == 0 {
 		dbUsage(env.Stderr)
 		return ExitFatal
 	}
-	fl := flag.NewFlagSet("db "+args[0], flag.ContinueOnError)
+	sub := args[0]
+	fl := flag.NewFlagSet("db "+sub, flag.ContinueOnError)
 	fl.SetOutput(io.Discard)
 	dbPath := fl.String("db", "", dbFlagHelp())
-	if err := fl.Parse(args[1:]); err != nil || (fl.NArg() != 0) != (args[0] == "backup") || fl.NArg() > 1 {
+	asJSON := fl.Bool("json", false, "print JSON (status, check)")
+	dryRun := fl.Bool("dry-run", false, "say what migrate would do, and change nothing")
+	takesFile := sub == "backup" || sub == "restore"
+	if err := fl.Parse(args[1:]); err != nil || (fl.NArg() != 0) != takesFile || fl.NArg() > 1 {
 		dbUsage(env.Stderr)
 		return ExitFatal
 	}
-	switch args[0] {
-	case "rebuild-graph", "stats", "backup":
+	switch sub {
+	case "rebuild-graph", "stats", "backup", "status", "check", "migrate", "restore":
 	default:
 		dbUsage(env.Stderr)
 		return ExitFatal
 	}
+	if *asJSON && sub != "status" && sub != "check" {
+		dbUsage(env.Stderr)
+		return ExitFatal
+	}
+	if *dryRun && sub != "migrate" {
+		dbUsage(env.Stderr)
+		return ExitFatal
+	}
 	var err error
 	if *dbPath, err = resolveDB(*dbPath, env); err != nil {
 		return fatalf(env, "choosing the database: %v", err)
 	}
-	if args[0] == "backup" {
+
+	// These read or replace the file without opening it the usual way, so they never upgrade it.
+	switch sub {
+	case "status":
+		return dbStatus(*dbPath, *asJSON, env)
+	case "check":
+		return dbCheck(*dbPath, *asJSON, env)
+	case "restore":
+		return dbRestore(*dbPath, fl.Arg(0), env)
+	case "migrate":
+		if *dryRun {
+			return dbMigrateDryRun(*dbPath, env)
+		}
+	}
+
+	if sub == "backup" || sub == "migrate" {
 		if _, err := os.Stat(*dbPath); err != nil {
-			return fatalf(env, "no database at %s (name it with --db, before the backup file)", *dbPath)
+			return fatalf(env, "no database at %s (name it with --db)", *dbPath)
+		}
+	}
+	var before store.Status
+	if sub == "migrate" {
+		if before, err = store.Inspect(*dbPath); err != nil {
+			return fatalf(env, "reading %s: %v", *dbPath, err)
 		}
 	}
 	st, err := store.Open(*dbPath)
@@ -44,7 +80,23 @@ func dbCmd(args []string, env Env) int {
 		return fatalf(env, "opening the database: %v", err)
 	}
 	defer st.Close() //nolint:errcheck // exiting
-	switch args[0] {
+	switch sub {
+	case "migrate":
+		// Open did the work (backup, steps, checks); this reports it.
+		if len(before.Pending) == 0 {
+			_, _ = fmt.Fprintf(env.Stdout, "%s is already at schema %d, this version's; nothing to do\n", *dbPath, before.Schema)
+			break
+		}
+		_ = st.Close()
+		after, err := store.Inspect(*dbPath)
+		if err != nil {
+			return fatalf(env, "reading the database: %v", err)
+		}
+		backup := ""
+		if len(after.Upgrades) > 0 {
+			backup = after.Upgrades[0].Backup
+		}
+		_, _ = fmt.Fprintf(env.Stdout, "upgraded %s from schema %d to %d and checked it; the backup made first is %s\n", *dbPath, before.Schema, after.Schema, backup)
 	case "rebuild-graph":
 		c, err := st.RebuildGraph()
 		if err != nil {
@@ -68,15 +120,190 @@ func dbCmd(args []string, env Env) int {
 	return ExitOK
 }
 
+func dbStatus(path string, asJSON bool, env Env) int {
+	s, err := store.Inspect(path)
+	if err != nil {
+		return fatalf(env, "reading %s: %v", path, err)
+	}
+	if asJSON {
+		b, _ := json.MarshalIndent(s, "", "  ")
+		_, _ = fmt.Fprintln(env.Stdout, string(b))
+		return ExitOK
+	}
+	w := env.Stdout
+	if !s.Exists {
+		_, _ = fmt.Fprintf(w, "database:  %s (not created yet; the server creates it at its first start)\n", path)
+		return ExitOK
+	}
+	_, _ = fmt.Fprintf(w, "database:  %s (%s)\n", path, sizeText(s.Size))
+	switch {
+	case s.Newer:
+		_, _ = fmt.Fprintf(w, "schema:    %d, made by a newer version; this one (schema %d) will not open it\n", s.Schema, s.ProgramSchema)
+	case len(s.Pending) > 0:
+		_, _ = fmt.Fprintf(w, "schema:    %d; this version upgrades it to %d at its next start (migrations %s), after a backup\n",
+			s.Schema, s.ProgramSchema, stepsText(s.Pending))
+	default:
+		_, _ = fmt.Fprintf(w, "schema:    %d, this version's\n", s.Schema)
+	}
+	if s.StructureOK != nil && !*s.StructureOK {
+		_, _ = fmt.Fprintln(w, "structure: differs from what this version builds; run cipherhorizon db check for details")
+	}
+	if s.InUse {
+		who := s.InUseBy
+		if who == "" {
+			who = "another process"
+		}
+		_, _ = fmt.Fprintf(w, "in use:    yes, by %s\n", who)
+	} else {
+		_, _ = fmt.Fprintln(w, "in use:    no")
+	}
+	if len(s.Backups) == 0 {
+		_, _ = fmt.Fprintln(w, "backups:   none made before an upgrade")
+	} else {
+		_, _ = fmt.Fprintln(w, "backups made before an upgrade (restore one with cipherhorizon db restore):")
+		for _, b := range s.Backups {
+			_, _ = fmt.Fprintf(w, "  %s  schema %d  %s  %s\n", b.Modified.UTC().Format("2006-01-02 15:04Z"), b.Schema, sizeText(b.Size), b.Path)
+		}
+	}
+	if len(s.Upgrades) > 0 {
+		_, _ = fmt.Fprintln(w, "history:")
+		for _, u := range s.Upgrades {
+			what := fmt.Sprintf("upgraded from schema %d to %d", u.FromSchema, u.ToSchema)
+			if u.FromSchema == 0 {
+				what = fmt.Sprintf("created at schema %d", u.ToSchema)
+			}
+			_, _ = fmt.Fprintf(w, "  %s  %s by version %s\n", u.At.UTC().Format("2006-01-02 15:04Z"), what, u.AppVersion)
+		}
+	}
+	return ExitOK
+}
+
+func dbCheck(path string, asJSON bool, env Env) int {
+	if _, err := os.Stat(path); err != nil {
+		return fatalf(env, "no database at %s (name it with --db)", path)
+	}
+	res, err := store.Check(path)
+	if err != nil {
+		return fatalf(env, "checking %s: %v", path, err)
+	}
+	if asJSON {
+		b, _ := json.MarshalIndent(struct {
+			store.CheckResult
+			OK bool `json:"ok"`
+		}{res, res.OK()}, "", "  ")
+		_, _ = fmt.Fprintln(env.Stdout, string(b))
+	} else {
+		w := env.Stdout
+		mark := func(ok bool) string {
+			if ok {
+				return "ok  "
+			}
+			return "FAIL"
+		}
+		_, _ = fmt.Fprintf(w, "%s consistency (SQLite integrity_check)\n", mark(len(res.Integrity) == 0))
+		for _, m := range res.Integrity {
+			_, _ = fmt.Fprintf(w, "       %s\n", m)
+		}
+		_, _ = fmt.Fprintf(w, "%s references between rows (%d pointing at rows that do not exist)\n", mark(res.FKViolations == 0), res.FKViolations)
+		switch {
+		case res.Schema > res.ProgramSchema:
+			_, _ = fmt.Fprintf(w, "FAIL schema %d is newer than this version's (%d): check it with the version that made it\n", res.Schema, res.ProgramSchema)
+		case res.StructureOK == nil:
+			_, _ = fmt.Fprintf(w, "-    structure not compared: schema %d is older than this version's %d (it is upgraded at the next start)\n", res.Schema, res.ProgramSchema)
+		default:
+			_, _ = fmt.Fprintf(w, "%s structure matches what this version builds (schema %d)\n", mark(*res.StructureOK), res.Schema)
+			for _, d := range res.Differences {
+				_, _ = fmt.Fprintf(w, "       %s\n", d)
+			}
+		}
+	}
+	if !res.OK() {
+		return ExitIncomplete
+	}
+	return ExitOK
+}
+
+func dbMigrateDryRun(path string, env Env) int {
+	s, err := store.Inspect(path)
+	if err != nil {
+		return fatalf(env, "reading %s: %v", path, err)
+	}
+	switch {
+	case !s.Exists:
+		return fatalf(env, "no database at %s (name it with --db)", path)
+	case s.Newer:
+		return fatalf(env, "%s is at schema %d, newer than this version's %d: it cannot be migrated by this version", path, s.Schema, s.ProgramSchema)
+	case len(s.Pending) == 0:
+		_, _ = fmt.Fprintf(env.Stdout, "%s is already at schema %d, this version's; nothing to do\n", path, s.Schema)
+	default:
+		_, _ = fmt.Fprintf(env.Stdout, "would back up %s (%s) next to it, then upgrade it from schema %d to %d (migrations %s) and check it; nothing was changed\n",
+			path, sizeText(s.Size), s.Schema, s.ProgramSchema, stepsText(s.Pending))
+		if s.InUse {
+			_, _ = fmt.Fprintf(env.Stdout, "it is in use (%s): stop that first\n", s.InUseBy)
+		}
+	}
+	return ExitOK
+}
+
+func dbRestore(path, backup string, env Env) int {
+	res, err := store.Restore(path, backup)
+	if errors.Is(err, store.ErrLocked) {
+		return fatalf(env, "%v", err)
+	}
+	if err != nil {
+		return fatalf(env, "restoring %s: %v", backup, err)
+	}
+	_, _ = fmt.Fprintf(env.Stdout, "restored %s from %s (schema %d)", path, backup, res.Schema)
+	if res.MovedTo != "" {
+		_, _ = fmt.Fprintf(env.Stdout, "; the database it replaced was kept as %s", res.MovedTo)
+	}
+	_, _ = fmt.Fprintln(env.Stdout)
+	if res.Schema < store.SchemaVersion() {
+		_, _ = fmt.Fprintf(env.Stdout, "it is at schema %d: this version upgrades it again at its next start; to stay on it, run the version that made it\n", res.Schema)
+	}
+	return ExitOK
+}
+
+func stepsText(steps []int) string {
+	if len(steps) == 1 {
+		return fmt.Sprint(steps[0])
+	}
+	return fmt.Sprintf("%d-%d", steps[0], steps[len(steps)-1])
+}
+
+func sizeText(n int64) string {
+	switch {
+	case n >= 1<<30:
+		return fmt.Sprintf("%.1f GiB", float64(n)/(1<<30))
+	case n >= 1<<20:
+		return fmt.Sprintf("%.1f MiB", float64(n)/(1<<20))
+	default:
+		return fmt.Sprintf("%d KiB", (n+1023)/1024)
+	}
+}
+
 func dbUsage(w io.Writer) {
-	_, _ = fmt.Fprint(w, `usage: cipherhorizon db rebuild-graph|stats [--db FILE]
+	_, _ = fmt.Fprint(w, strings.TrimLeft(`
+usage: cipherhorizon db status|check [--db FILE] [--json]
+       cipherhorizon db migrate [--db FILE] [--dry-run]
        cipherhorizon db backup [--db FILE] BACKUP-FILE
+       cipherhorizon db restore [--db FILE] BACKUP-FILE
+       cipherhorizon db rebuild-graph|stats [--db FILE]
 
-  rebuild-graph  drop the estate graph and rebuild it from the stored scan reports and
-                 host uploads (the documents themselves are never changed)
-  stats          print what the graph holds
+  status         the database's schema, whether this version would upgrade it, the backups made
+                 before upgrades, its upgrade history and whether a server is using it. Changes nothing
+  check          a thorough check, changing nothing: SQLite's integrity check, references between
+                 rows, and the structure against this version's. Exit 2 if it finds a problem
+  migrate        upgrade the database to this version now (the server otherwise does it at start,
+                 unless run with --migrate refuse). A backup is made first, the result is checked,
+                 and a failed upgrade is put back. --dry-run says what it would do
   backup         write a consistent copy of the database to BACKUP-FILE, safe while the
                  server runs; BACKUP-FILE must not exist. The copy holds password and
                  session hashes: keep it as carefully as the database
-`)
+  restore        put BACKUP-FILE in place of the database. The server must be stopped. The
+                 database it replaces is kept beside it, never deleted
+  rebuild-graph  drop the estate graph and rebuild it from the stored scan reports and
+                 host uploads (the documents themselves are never changed)
+  stats          print what the graph holds
+`, "\n"))
 }
diff --git a/internal/app/serve.go b/internal/app/serve.go
index 13d3359..965afa8 100644
--- a/internal/app/serve.go
+++ b/internal/app/serve.go
@@ -171,6 +171,8 @@ func serveCmd(ctx context.Context, args []string, env Env) int {
 	addr := fl.String("addr", "", "address to listen on: host:port, or a host alone with --port (default 127.0.0.1:8080, or "+addrEnv+" and "+portEnv+")")
 	port := fl.Int("port", -1, "port to listen on, keeping the host of --addr (or set "+portEnv+"); 0 picks any free port")
 	dbPath := fl.String("db", "", dbFlagHelp())
+	migrateMode := fl.String("migrate", "auto", "what to do with a database made by an older version: auto (upgrade it at start, after a backup) "+
+		"or refuse (stop and say so; upgrade it yourself with cipherhorizon db migrate)")
 	token := fl.String("token", "", "an automation token: scripts and tools may call the API with it as a bearer token, acting as an analyst (or set "+tokenEnv+")")
 	signInMode := fl.String("sign-in", "auto", "require sign-in: auto (off until turned on in Settings; on if accounts already exist), "+
 		"on (always; the first start prints a setup code for the administrator) or off (never)")
@@ -282,7 +284,16 @@ func serveCmd(ctx context.Context, args []string, env Env) int {
 	if *dbPath, err = resolveDB(*dbPath, env); err != nil {
 		return fatalf(env, "choosing the database: %v", err)
 	}
-	st, err := store.Open(*dbPath)
+	// Exclusive: one server per database, and no other version upgrading it underneath this one.
+	opts := store.OpenOptions{Exclusive: true}
+	switch *migrateMode {
+	case "auto":
+	case "refuse":
+		opts.Migrate = store.MigrateRefuse
+	default:
+		return fatalf(env, "--migrate must be auto or refuse")
+	}
+	st, err := store.OpenWith(*dbPath, opts)
 	if err != nil {
 		return fatalf(env, "opening the database: %v", err)
 	}
diff --git a/internal/app/upgrade_test.go b/internal/app/upgrade_test.go
new file mode 100644
index 0000000..255db7d
--- /dev/null
+++ b/internal/app/upgrade_test.go
@@ -0,0 +1,173 @@
+package app_test
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"io"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/offsetsecurity/cipherhorizon/internal/app"
+	"github.com/offsetsecurity/cipherhorizon/internal/store"
+)
+
+// oldDB copies the database written by the real 0.1.0 release (internal/store/testdata/upgrade).
+func oldDB(t *testing.T) string {
+	t.Helper()
+	b, err := os.ReadFile("../store/testdata/upgrade/v0.1.0.db")
+	if err != nil {
+		t.Fatal(err)
+	}
+	p := filepath.Join(t.TempDir(), "cipherhorizon.db")
+	if err := os.WriteFile(p, b, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	return p
+}
+
+// PRD-016 U-07: an operator can see, rehearse, run and check an upgrade, and go back, with the same
+// commands on every platform.
+func TestDBUpgradeCommands(t *testing.T) {
+	db := oldDB(t)
+	want := store.SchemaVersion()
+
+	code, out, errOut := run(t, "db", "status", "--db", db)
+	if code != 0 || !strings.Contains(out, "schema:    14; this version upgrades it to") || !strings.Contains(out, "in use:    no") {
+		t.Fatalf("status of a 0.1.0 database: %d %q %q", code, out, errOut)
+	}
+	code, out, _ = run(t, "db", "migrate", "--dry-run", "--db", db)
+	if code != 0 || !strings.Contains(out, "would back up") || !strings.Contains(out, "nothing was changed") {
+		t.Fatalf("migrate --dry-run: %d %q", code, out)
+	}
+	if st, _ := store.Inspect(db); st.Schema != 14 {
+		t.Fatalf("--dry-run changed the schema to %d", st.Schema)
+	}
+
+	code, out, errOut = run(t, "db", "migrate", "--db", db)
+	if code != 0 || !strings.Contains(out, "upgraded") || !strings.Contains(out, ".bak-v14-") {
+		t.Fatalf("migrate: %d %q %q", code, out, errOut)
+	}
+	code, out, _ = run(t, "db", "migrate", "--db", db)
+	if code != 0 || !strings.Contains(out, "nothing to do") {
+		t.Errorf("second migrate: %d %q", code, out)
+	}
+
+	code, out, _ = run(t, "db", "status", "--db", db, "--json")
+	var st store.Status
+	if code != 0 || json.Unmarshal([]byte(out), &st) != nil || st.Schema != want || len(st.Upgrades) != 1 || st.Upgrades[0].FromSchema != 14 || len(st.Backups) != 1 {
+		t.Fatalf("status --json after the upgrade: %d %q", code, out)
+	}
+
+	code, out, _ = run(t, "db", "check", "--db", db)
+	if code != 0 || strings.Contains(out, "FAIL") || !strings.Contains(out, "structure matches") {
+		t.Fatalf("check: %d %q", code, out)
+	}
+
+	// Back to the copy made before the upgrade: the server would then upgrade it again at its
+	// next start, and the restore says so.
+	code, out, errOut = run(t, "db", "restore", "--db", db, st.Backups[0].Path)
+	if code != 0 || !strings.Contains(out, "restored") || !strings.Contains(out, "kept as") || !strings.Contains(out, "schema 14") {
+		t.Fatalf("restore: %d %q %q", code, out, errOut)
+	}
+	if s, _ := store.Inspect(db); s.Schema != 14 {
+		t.Errorf("after restore: schema %d, want 14", s.Schema)
+	}
+
+	for _, args := range [][]string{
+		{"db", "restore", "--db", db},                     // no file
+		{"db", "status", "--db", db, "extra"},             // stray argument
+		{"db", "migrate", "--json", "--db", db},           // --json is for status and check
+		{"db", "check", "--dry-run", "--db", db},          // --dry-run is for migrate
+		{"db", "migrate", "--db", db + ".does-not-exist"}, // nothing to migrate
+	} {
+		if code, _, _ := run(t, args...); code != app.ExitFatal {
+			t.Errorf("%v: exit %d, want %d", args, code, app.ExitFatal)
+		}
+	}
+}
+
+func TestDBCheckReportsAProblem(t *testing.T) {
+	db := filepath.Join(t.TempDir(), "x.db")
+	if code, _, _ := run(t, "db", "stats", "--db", db); code != 0 {
+		t.Fatal("creating the database failed")
+	}
+	sqldb, err := sql.Open("sqlite", "file:"+db)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := sqldb.Exec(`CREATE INDEX hand_made ON assets(host)`); err != nil {
+		t.Fatal(err)
+	}
+	_ = sqldb.Close()
+	code, out, _ := run(t, "db", "check", "--db", db)
+	if code != app.ExitIncomplete || !strings.Contains(out, "FAIL structure") || !strings.Contains(out, "hand_made") {
+		t.Errorf("check of a hand-edited database: %d %q", code, out)
+	}
+}
+
+func TestServeMigrateRefuse(t *testing.T) {
+	db := oldDB(t)
+	code, _, errOut := run(t, "serve", "--addr", "127.0.0.1:0", "--db", db, "--migrate", "refuse")
+	if code != app.ExitFatal || !strings.Contains(errOut, "cipherhorizon db migrate") {
+		t.Fatalf("serve --migrate refuse on a 0.1.0 database: %d %q", code, errOut)
+	}
+	if st, _ := store.Inspect(db); st.Schema != 14 || len(st.Backups) != 0 {
+		t.Errorf("refuse changed the database: schema %d, %d backups", st.Schema, len(st.Backups))
+	}
+	if code, _, errOut := run(t, "serve", "--addr", "127.0.0.1:0", "--db", db, "--migrate", "sometimes"); code != app.ExitFatal || !strings.Contains(errOut, "--migrate must be") {
+		t.Errorf("bad --migrate: %d %q", code, errOut)
+	}
+}
+
+// The user's question, answered by test: point serve at an old database and it upgrades it at
+// launch, then serves; a second server on the same file is refused while the first runs.
+func TestServeUpgradesAtLaunchAndHoldsTheDatabase(t *testing.T) {
+	t.Setenv("CIPHERHORIZON_TOKEN", "")
+	db := oldDB(t)
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	errb := &lockedBuf{}
+	done := make(chan int, 1)
+	go func() {
+		done <- app.Main(ctx, []string{"serve", "--addr", "127.0.0.1:0", "--db", db}, app.Env{Stdout: io.Discard, Stderr: errb})
+	}()
+	re := regexp.MustCompile(`on http://127\.0\.0\.1:\d+`)
+	deadline := time.Now().Add(15 * time.Second)
+	for time.Now().Before(deadline) && !re.MatchString(errb.String()) {
+		time.Sleep(20 * time.Millisecond)
+	}
+	if !re.MatchString(errb.String()) {
+		t.Fatalf("server never started; stderr:\n%s", errb.String())
+	}
+	if !strings.Contains(errb.String(), "upgraded the database") || !strings.Contains(errb.String(), "backed up the database") {
+		t.Errorf("the upgrade at launch was not logged:\n%s", errb.String())
+	}
+
+	code, _, errOut := run(t, "serve", "--addr", "127.0.0.1:0", "--db", db)
+	if code != app.ExitFatal || !strings.Contains(errOut, "another CipherHorizon process") || !strings.Contains(errOut, "pid ") {
+		t.Errorf("second server on the same database: %d %q", code, errOut)
+	}
+	code, out, _ := run(t, "db", "status", "--db", db)
+	if code != 0 || !strings.Contains(out, "in use:    yes, by pid") {
+		t.Errorf("status while serving: %d %q", code, out)
+	}
+	// A backup while it serves still works (no upgrade needed, so no lock).
+	if code, _, errOut := run(t, "db", "backup", "--db", db, filepath.Join(t.TempDir(), "live.db")); code != 0 {
+		t.Errorf("backup while serving: %d %q", code, errOut)
+	}
+
+	cancel()
+	select {
+	case code := <-done:
+		if code != app.ExitOK {
+			t.Errorf("exit %d; stderr:\n%s", code, errb.String())
+		}
+	case <-time.After(15 * time.Second):
+		t.Fatal("server did not shut down")
+	}
+}
diff --git a/internal/archtest/arch_test.go b/internal/archtest/arch_test.go
index 2436c3b..678164a 100644
--- a/internal/archtest/arch_test.go
+++ b/internal/archtest/arch_test.go
@@ -89,17 +89,19 @@ func TestDiscoverDoesNotTouchTheOSDirectly(t *testing.T) {
 	forbid(t, "../discover", append(append(append([]string{}, noProcessOrNetwork...), noPlatform...), noCycloneDX...)...)
 }
 
-// The only packages allowed a Windows or unsafe import are the three platform layers:
-// hostinfo (who and what this machine is), winapi (what Windows cryptography says) and
-// winsvc (running as a Windows service), each behind build tags. None may run subprocesses or
-// use the network, and winapi and winsvc may import nothing else from this module, so they stay
-// pure platform layers that know nothing of evidence, CBOMs or the server.
+// The only packages allowed a Windows or unsafe import are the four platform layers:
+// hostinfo (who and what this machine is), winapi (what Windows cryptography says),
+// winsvc (running as a Windows service) and osfile (file locks and free space, for the
+// database), each behind build tags. None may run subprocesses or use the network, and winapi,
+// winsvc and osfile may import nothing else from this module, so they stay pure platform layers
+// that know nothing of evidence, CBOMs or the server.
 func TestOnlyPlatformLayersTouchTheOS(t *testing.T) {
 	forbid(t, "../hostinfo", "os/exec", "net", "net/http")
 	forbid(t, "../winapi", "os/exec", "net", "net/http", "net/rpc", module+"/internal")
 	forbid(t, "../winsvc", "os/exec", "net", "net/http", "net/rpc", module+"/internal")
+	forbid(t, "../osfile", "os/exec", "net", "net/http", "net/rpc", "unsafe", module+"/internal")
 
-	platform := map[string]bool{"hostinfo": true, "winapi": true, "winsvc": true}
+	platform := map[string]bool{"hostinfo": true, "winapi": true, "winsvc": true, "osfile": true}
 	entries, err := os.ReadDir("..")
 	if err != nil {
 		t.Fatal(err)
@@ -110,7 +112,7 @@ func TestOnlyPlatformLayersTouchTheOS(t *testing.T) {
 		}
 		for imp, files := range importsOf(t, filepath.Join("..", e.Name())) {
 			if imp == "golang.org/x/sys/windows" || strings.HasPrefix(imp, "golang.org/x/sys/windows/") || imp == "unsafe" {
-				t.Errorf("only internal/hostinfo, internal/winapi and internal/winsvc may import %s (used in %s)", imp, strings.Join(files, ", "))
+				t.Errorf("only internal/hostinfo, internal/winapi, internal/winsvc and internal/osfile may import %s (used in %s)", imp, strings.Join(files, ", "))
 			}
 		}
 	}
diff --git a/internal/osfile/osfile.go b/internal/osfile/osfile.go
new file mode 100644
index 0000000..07db9f6
--- /dev/null
+++ b/internal/osfile/osfile.go
@@ -0,0 +1,14 @@
+// Package osfile is the platform layer for two things the database needs from the operating system
+// and the standard library does not offer: an exclusive lock on a file that the OS releases when the
+// process ends, and the free space in a folder. Like internal/hostinfo, internal/winapi and
+// internal/winsvc it is where operating-system code lives, so nothing else has to import
+// x/sys/windows (enforced by internal/archtest). It imports nothing else from this module.
+package osfile
+
+import "errors"
+
+// ErrLocked is returned by TryLock when another open of the file (in any process) holds the lock.
+var ErrLocked = errors.New("the file is locked by another process")
+
+// ErrUnsupported is returned where an operation does not exist on this operating system.
+var ErrUnsupported = errors.New("not supported on this operating system")
diff --git a/internal/osfile/osfile_other.go b/internal/osfile/osfile_other.go
new file mode 100644
index 0000000..2a0b098
--- /dev/null
+++ b/internal/osfile/osfile_other.go
@@ -0,0 +1,14 @@
+//go:build !unix && !windows
+
+package osfile
+
+import "os"
+
+// TryLock always succeeds: there is no OS file lock here (every release target is unix or windows).
+func TryLock(*os.File) error { return nil }
+
+// Unlock does nothing.
+func Unlock(*os.File) error { return nil }
+
+// FreeBytes is not known here.
+func FreeBytes(string) (uint64, error) { return 0, ErrUnsupported }
diff --git a/internal/osfile/osfile_test.go b/internal/osfile/osfile_test.go
new file mode 100644
index 0000000..e1834b0
--- /dev/null
+++ b/internal/osfile/osfile_test.go
@@ -0,0 +1,54 @@
+package osfile_test
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/offsetsecurity/cipherhorizon/internal/osfile"
+)
+
+func TestTryLockIsExclusiveAndReleased(t *testing.T) {
+	p := filepath.Join(t.TempDir(), "x.lock")
+	a, err := os.OpenFile(p, os.O_RDWR|os.O_CREATE, 0o600)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := osfile.TryLock(a); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := a.WriteAt([]byte("pid 1\n"), 0); err != nil {
+		t.Fatal(err)
+	}
+	b, err := os.OpenFile(p, os.O_RDWR, 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer b.Close() //nolint:errcheck // test
+	if err := osfile.TryLock(b); !errors.Is(err, osfile.ErrLocked) {
+		t.Fatalf("second lock = %v, want ErrLocked", err)
+	}
+	// The holder's note stays readable while the lock is held.
+	if note, err := os.ReadFile(p); err != nil || !strings.HasPrefix(string(note), "pid 1") {
+		t.Errorf("reading the note while locked: %q, %v", note, err)
+	}
+	if err := osfile.Unlock(a); err != nil {
+		t.Fatal(err)
+	}
+	_ = a.Close()
+	if err := osfile.TryLock(b); err != nil {
+		t.Fatalf("after release: %v", err)
+	}
+}
+
+func TestFreeBytes(t *testing.T) {
+	n, err := osfile.FreeBytes(t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if n == 0 {
+		t.Error("no free space reported in a writable folder")
+	}
+}
diff --git a/internal/osfile/osfile_unix.go b/internal/osfile/osfile_unix.go
new file mode 100644
index 0000000..c39040e
--- /dev/null
+++ b/internal/osfile/osfile_unix.go
@@ -0,0 +1,34 @@
+//go:build unix
+
+package osfile
+
+import (
+	"errors"
+	"os"
+
+	"golang.org/x/sys/unix"
+)
+
+// TryLock takes an exclusive flock on f without waiting. flock belongs to the open file, so a second
+// open of the same file, in this process or another, is refused too.
+func TryLock(f *os.File) error {
+	err := unix.Flock(int(f.Fd()), unix.LOCK_EX|unix.LOCK_NB)
+	if errors.Is(err, unix.EWOULDBLOCK) {
+		return ErrLocked
+	}
+	return err
+}
+
+// Unlock gives the lock back (closing f does too).
+func Unlock(f *os.File) error {
+	return unix.Flock(int(f.Fd()), unix.LOCK_UN)
+}
+
+// FreeBytes is how much space an unprivileged process may still write in dir.
+func FreeBytes(dir string) (uint64, error) {
+	var st unix.Statfs_t
+	if err := unix.Statfs(dir, &st); err != nil {
+		return 0, err
+	}
+	return uint64(st.Bavail) * uint64(st.Bsize), nil //nolint:gosec,unconvert // never negative; field types differ by OS
+}
diff --git a/internal/osfile/osfile_windows.go b/internal/osfile/osfile_windows.go
new file mode 100644
index 0000000..bb734a4
--- /dev/null
+++ b/internal/osfile/osfile_windows.go
@@ -0,0 +1,47 @@
+//go:build windows
+
+package osfile
+
+import (
+	"errors"
+	"os"
+
+	"golang.org/x/sys/windows"
+)
+
+// The lock covers one byte far past anything written, so a note at the start of the file stays
+// readable by a process that was refused (a locked range cannot be read on Windows).
+const (
+	lockOffsetLow  = 0
+	lockOffsetHigh = 0x7fff
+)
+
+// TryLock takes an exclusive LockFileEx lock on f without waiting. Windows locks belong to the handle,
+// so a second open of the same file, in this process or another, is refused too.
+func TryLock(f *os.File) error {
+	ol := &windows.Overlapped{Offset: lockOffsetLow, OffsetHigh: lockOffsetHigh}
+	err := windows.LockFileEx(windows.Handle(f.Fd()), windows.LOCKFILE_EXCLUSIVE_LOCK|windows.LOCKFILE_FAIL_IMMEDIATELY, 0, 1, 0, ol)
+	if errors.Is(err, windows.ERROR_LOCK_VIOLATION) || errors.Is(err, windows.ERROR_IO_PENDING) {
+		return ErrLocked
+	}
+	return err
+}
+
+// Unlock gives the lock back (closing f does too).
+func Unlock(f *os.File) error {
+	ol := &windows.Overlapped{Offset: lockOffsetLow, OffsetHigh: lockOffsetHigh}
+	return windows.UnlockFileEx(windows.Handle(f.Fd()), 0, 1, 0, ol)
+}
+
+// FreeBytes is how much space the calling user may still write on dir's volume.
+func FreeBytes(dir string) (uint64, error) {
+	p, err := windows.UTF16PtrFromString(dir)
+	if err != nil {
+		return 0, err
+	}
+	var avail, total, free uint64
+	if err := windows.GetDiskFreeSpaceEx(p, &avail, &total, &free); err != nil {
+		return 0, err
+	}
+	return avail, nil
+}
diff --git a/internal/store/export_test.go b/internal/store/export_test.go
index 0c43d30..e98ac30 100644
--- a/internal/store/export_test.go
+++ b/internal/store/export_test.go
@@ -66,3 +66,12 @@ func (s *Store) QueryIntForTest(q string, args ...any) (int, error) {
 func (s *Store) QueryStringForTest(q string, dest *string, args ...any) error {
 	return s.db.QueryRow(q, args...).Scan(dest)
 }
+
+// HoldLockForTest takes path's lock as a running server would, until release is called.
+func HoldLockForTest(path string) (release func(), err error) {
+	l, err := acquireLock(path)
+	if err != nil {
+		return nil, err
+	}
+	return l.release, nil
+}
diff --git a/internal/store/links.go b/internal/store/links.go
index c2d57a0..4489c93 100644
--- a/internal/store/links.go
+++ b/internal/store/links.go
@@ -256,7 +256,7 @@ func backfillLinks(tx *sql.Tx, now time.Time) error {
 		if err := tx.QueryRow(`SELECT system_id FROM assets WHERE id = ?`, p.a).Scan(&sys); err != nil || !sys.Valid {
 			continue
 		}
-		if err := recordManualLinkTx(tx, p.at, "operator", p.a, sys.Int64, LinkConfirmed); err != nil {
+		if err := recordConfirmedLinkV6(tx, p.at, p.a, sys.Int64); err != nil {
 			return err
 		}
 	}
@@ -264,6 +264,21 @@ func backfillLinks(tx *sql.Tx, now time.Time) error {
 	return nil
 }
 
+// recordConfirmedLinkV6 is recordManualLinkTx as migration 6 shipped it in 0.1.0, frozen with the step
+// (PRD-016 §5.2): the live function and the estate package's rule types may change, and a database
+// upgraded from before step 6 must end up exactly like one that ran it on release day.
+func recordConfirmedLinkV6(tx *sql.Tx, now string, assetID, systemID int64) error {
+	const (
+		rulesJSON    = `[{"id":"manual","detail":"linked by a person (operator)"}]`
+		evidenceJSON = `{"ambiguous":false}`
+	)
+	_, err := tx.Exec(`INSERT INTO links (asset_id, system_id, state, strength, rules_json, evidence_json, stale, decided_by, decided_at, created_at, updated_at)
+		VALUES (?, ?, 'confirmed', 'strong', ?, ?, 0, 'operator', ?, ?, ?)
+		ON CONFLICT(asset_id, system_id) DO UPDATE SET state = excluded.state, stale = 0, decided_by = excluded.decided_by, decided_at = excluded.decided_at, updated_at = excluded.updated_at`,
+		assetID, systemID, rulesJSON, evidenceJSON, now, now, now)
+	return err
+}
+
 // ---- correlating ------------------------------------------------------------------------------
 
 // correlateQuietly recomputes links after evidence changes, and returns once a correlation that
diff --git a/internal/store/lockfile.go b/internal/store/lockfile.go
new file mode 100644
index 0000000..4d099af
--- /dev/null
+++ b/internal/store/lockfile.go
@@ -0,0 +1,113 @@
+package store
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/offsetsecurity/cipherhorizon/internal/osfile"
+	"github.com/offsetsecurity/cipherhorizon/internal/version"
+)
+
+// ErrLocked means another process holds the database's lock: a running server, or another
+// command in the middle of migrating it.
+var ErrLocked = errors.New("another CipherHorizon process is using this database")
+
+// LockedError says who holds the lock, as far as the lock file tells.
+type LockedError struct {
+	Path   string
+	Holder string // "pid 123, version 0.5.0, since …", or "" when the file could not be read
+}
+
+func (e *LockedError) Error() string {
+	who := ""
+	if e.Holder != "" {
+		who = " (" + e.Holder + ")"
+	}
+	return fmt.Sprintf("another CipherHorizon process%s is using %s; stop it first, or point this one at another database with --db", who, strings.TrimSuffix(e.Path, ".lock"))
+}
+
+func (e *LockedError) Unwrap() error { return ErrLocked }
+
+// fileLock is an OS lock on "<database>.lock". The OS releases it when the process ends, however
+// it ends, so a crash never leaves the database locked; the file itself stays (deleting it would
+// race with the next process taking it) and is harmless.
+type fileLock struct {
+	f *os.File
+}
+
+// lockPath is where a database's lock lives.
+func lockPath(dbPath string) string { return dbPath + ".lock" }
+
+// lockable reports whether a path names a file this package can lock (not memory, not a URI).
+func lockable(dbPath string) bool {
+	return dbPath != "" && dbPath != ":memory:" && !strings.HasPrefix(dbPath, "file:")
+}
+
+// acquireLock takes the database's lock without waiting. It fails with a *LockedError when another
+// process (or another Store in this process) holds it.
+func acquireLock(dbPath string) (*fileLock, error) {
+	p := lockPath(dbPath)
+	if err := restrictFile(p); err != nil {
+		return nil, err
+	}
+	f, err := os.OpenFile(p, os.O_RDWR|os.O_CREATE, 0o600)
+	if err != nil {
+		return nil, fmt.Errorf("store: opening the lock %s: %w", p, err)
+	}
+	if err := osfile.TryLock(f); err != nil {
+		_ = f.Close()
+		if errors.Is(err, osfile.ErrLocked) {
+			return nil, &LockedError{Path: p, Holder: readHolder(p)}
+		}
+		return nil, fmt.Errorf("store: locking %s: %w", p, err)
+	}
+	// Say who holds it, for the next process's message. Best effort: the lock is what matters.
+	if err := f.Truncate(0); err == nil {
+		_, _ = f.WriteAt([]byte(fmt.Sprintf("pid %d, version %s, since %s\n", os.Getpid(), version.Version, time.Now().UTC().Format(time.RFC3339))), 0)
+	}
+	return &fileLock{f: f}, nil
+}
+
+// release gives the lock back. Safe on nil.
+func (l *fileLock) release() {
+	if l == nil || l.f == nil {
+		return
+	}
+	_ = osfile.Unlock(l.f)
+	_ = l.f.Close()
+	l.f = nil
+}
+
+// readHolder reads what the holder wrote into the lock file.
+func readHolder(p string) string {
+	b, err := os.ReadFile(p)
+	if err != nil {
+		return ""
+	}
+	s := strings.TrimSpace(string(b))
+	if len(s) > 200 || strings.ContainsAny(s, "\r\n") {
+		return ""
+	}
+	return s
+}
+
+// LockHolder reports whether another process holds the database's lock and, if so, who. It takes
+// the lock for a moment to find out, so it must not be called while this process holds it.
+func LockHolder(dbPath string) (held bool, holder string, err error) {
+	if !lockable(dbPath) {
+		return false, "", nil
+	}
+	l, err := acquireLock(dbPath)
+	var le *LockedError
+	if errors.As(err, &le) {
+		return true, le.Holder, nil
+	}
+	if err != nil {
+		return false, "", err
+	}
+	l.release()
+	return false, "", nil
+}
diff --git a/internal/store/migrations.lock b/internal/store/migrations.lock
new file mode 100644
index 0000000..e14c40d
--- /dev/null
+++ b/internal/store/migrations.lock
@@ -0,0 +1,20 @@
+# Released database migrations: "<step> <sha256 of its SQL> <first release that shipped it>".
+#
+# A step listed here has run on real installs. It is never edited, reordered or removed: fix forward
+# with a new step. TestMigrationsLock enforces this. scripts/prepare-release.sh appends the steps a
+# release ships; nothing else writes this file.
+1 322ac65ad005a250ae183424c9cd2cbc554a298b64ef9fc3bcfaf239e93a7c1a v0.1.0
+2 e508e5434edde4d2fbb59c8d0b6903ddf105258b8958d793dfd84c1006790fb0 v0.1.0
+3 890f9fbeee7148eaab374f896d7aa1238d8499fb630994ca99cf2b813e88074e v0.1.0
+4 78d661812e2538582b26a42911aeea3a10511d82f4c3ebec508dd369812d52d6 v0.1.0
+5 5d9688b6cf093133ef5b5a07ec1839d4e3f7ee6330c7a88dbff305c7b1af0bc5 v0.1.0
+6 cbba55f2acb67c7c3c621d5de5f64435a82a49cb6be1cddbd8e4895eccd644f5 v0.1.0
+7 6af9bebe6be1ef55b278162f75421ccd065062e6b5401ed11febfdb267d9ecfe v0.1.0
+8 5ef2c57241aefe716519a505bb1f929ed573e644ddfa4c25aa6f9aa997a38095 v0.1.0
+9 ee861d922261dbc1e2beca7047d456a679a0070c1c7923a24f2080cfd5d078d9 v0.1.0
+10 63b5b6760d4a0fea11a2bea60e37f9396d38fb090fb1e300b4b934b9095f0f33 v0.1.0
+11 997421c1a765d5905500f31820d980c6dc42dd469d277a688ef9391dc8dce177 v0.1.0
+12 3e1fe670af68ba2a449d08f51888bec37b1eaf78b16d60a3de8317517f496f0e v0.1.0
+13 5c670283cdc831273fa37f4613babea271a060a4b1989f188e14e3d4832f7147 v0.1.0
+14 a70dabf873dff7fb49d117ffef8ea84e8c3760c2ed38006b2173b92a8b1b4e75 v0.1.0
+15 ea1c22bba46ed3abd4044664b4266ee194438125b191e02121c94aa3d2c95f04 v0.4.0
diff --git a/internal/store/migrations_lock_test.go b/internal/store/migrations_lock_test.go
new file mode 100644
index 0000000..8943a87
--- /dev/null
+++ b/internal/store/migrations_lock_test.go
@@ -0,0 +1,115 @@
+package store
+
+import (
+	"bufio"
+	"crypto/sha256"
+	"flag"
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+	"testing"
+)
+
+// lockRelease, when set, appends every migration not yet in migrations.lock to it as shipped by that
+// release. scripts/prepare-release.sh runs it; nothing else should.
+var lockRelease = flag.String("lock-release", "", "append unlocked migrations to migrations.lock as shipped by this version")
+
+const migrationsLockFile = "migrations.lock"
+
+type lockedStep struct {
+	version int
+	sum     string
+	release string
+}
+
+func readMigrationsLock(t *testing.T) []lockedStep {
+	t.Helper()
+	f, err := os.Open(migrationsLockFile)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer f.Close() //nolint:errcheck // read-only
+	var out []lockedStep
+	sc := bufio.NewScanner(f)
+	for n := 1; sc.Scan(); n++ {
+		line := strings.TrimSpace(sc.Text())
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		fs := strings.Fields(line)
+		if len(fs) != 3 {
+			t.Fatalf("%s:%d: want \"<step> <sha256> <release>\", got %q", migrationsLockFile, n, line)
+		}
+		v, err := strconv.Atoi(fs[0])
+		if err != nil {
+			t.Fatalf("%s:%d: step %q is not a number", migrationsLockFile, n, fs[0])
+		}
+		out = append(out, lockedStep{v, fs[1], fs[2]})
+	}
+	if err := sc.Err(); err != nil {
+		t.Fatal(err)
+	}
+	return out
+}
+
+func migrationSum(v int) string { return fmt.Sprintf("%x", sha256.Sum256([]byte(migrations[v-1]))) }
+
+// TestMigrationsLock is the rule that makes skipping versions safe: a migration that has shipped is
+// history. An install that already ran it never runs it again, so editing it would make that install
+// and a fresh one disagree for ever. Fix forward with a new step instead.
+func TestMigrationsLock(t *testing.T) {
+	locked := readMigrationsLock(t)
+	for i, l := range locked {
+		if l.version != i+1 {
+			t.Fatalf("%s: entry %d is step %d; steps must be listed in order from 1 with none missing", migrationsLockFile, i+1, l.version)
+		}
+		if l.version > len(migrations) {
+			t.Fatalf("step %d (shipped in %s) is missing from migrations: a released step is never removed", l.version, l.release)
+		}
+		if got := migrationSum(l.version); got != l.sum {
+			t.Errorf("step %d shipped in %s and has been edited (sha256 %s, locked %s). Released migrations are never edited: undo the change and add a new step", l.version, l.release, got, l.sum)
+		}
+	}
+	if *lockRelease == "" {
+		return
+	}
+	rel := "v" + strings.TrimPrefix(*lockRelease, "v")
+	f, err := os.OpenFile(migrationsLockFile, os.O_APPEND|os.O_WRONLY, 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer f.Close() //nolint:errcheck // checked below via the writes
+	for v := len(locked) + 1; v <= len(migrations); v++ {
+		if _, err := fmt.Fprintf(f, "%d %s %s\n", v, migrationSum(v), rel); err != nil {
+			t.Fatal(err)
+		}
+		t.Logf("locked step %d as shipped in %s", v, rel)
+	}
+}
+
+// TestUnreleasedMigrationsHaveUpgradeNotes: a release that changes the database tells operators what
+// the upgrade does before they run it (PRD-016 §5.2). While a migration is not yet in migrations.lock,
+// CHANGELOG.md's [Unreleased] section must hold an "### Upgrade notes" heading.
+func TestUnreleasedMigrationsHaveUpgradeNotes(t *testing.T) {
+	locked := len(readMigrationsLock(t))
+	if locked >= len(migrations) {
+		return
+	}
+	b, err := os.ReadFile("../../CHANGELOG.md")
+	if err != nil {
+		t.Fatal(err)
+	}
+	text := strings.ReplaceAll(string(b), "\r\n", "\n")
+	start := strings.Index(text, "## [Unreleased]")
+	if start < 0 {
+		t.Fatal("CHANGELOG.md has no [Unreleased] section")
+	}
+	section := text[start+len("## [Unreleased]"):]
+	if end := strings.Index(section, "\n## ["); end >= 0 {
+		section = section[:end]
+	}
+	if !strings.Contains(section, "\n### Upgrade notes") {
+		t.Errorf("migrations %d-%d are not released yet, and CHANGELOG.md [Unreleased] has no \"### Upgrade notes\": say what the upgrade does to the database (new tables, rewritten values, how long it may take)", locked+1, len(migrations))
+	}
+}
diff --git a/internal/store/postmigrations_test.go b/internal/store/postmigrations_test.go
new file mode 100644
index 0000000..13ad7d8
--- /dev/null
+++ b/internal/store/postmigrations_test.go
@@ -0,0 +1,216 @@
+package store
+
+import (
+	"go/ast"
+	"go/parser"
+	"go/token"
+	"os"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+	"testing"
+)
+
+// frozenVar is how a package variable a migration's Go step reads says it is frozen with that step.
+var frozenVar = regexp.MustCompile(`V\d+$`)
+
+// TestPostMigrationsUseOnlyFrozenCode enforces PRD-016 §5.2: a migration's Go step must do in 2028
+// what it did on release day, or a database upgraded late ends up different from one upgraded on
+// time. So the steps, and every function they reach in this package, may not:
+//   - be methods (today's Store behaviour changes);
+//   - use another package of this module (today's evaluation, server or model code changes);
+//   - read a package variable unless its name ends in V<step> (frozen with the step, like
+//     timestampColumnsV10).
+//
+// Constants and the standard library are allowed.
+func TestPostMigrationsUseOnlyFrozenCode(t *testing.T) {
+	fset := token.NewFileSet()
+	entries, err := os.ReadDir(".")
+	if err != nil {
+		t.Fatal(err)
+	}
+	funcs := map[string]*ast.FuncDecl{}
+	fileOf := map[string]*ast.File{}
+	vars := map[string]bool{}
+	var post *ast.CompositeLit
+	for _, e := range entries {
+		n := e.Name()
+		if !strings.HasSuffix(n, ".go") || strings.HasSuffix(n, "_test.go") {
+			continue
+		}
+		f, err := parser.ParseFile(fset, n, nil, parser.SkipObjectResolution)
+		if err != nil {
+			t.Fatal(err)
+		}
+		for _, d := range f.Decls {
+			switch d := d.(type) {
+			case *ast.FuncDecl:
+				if d.Recv == nil {
+					funcs[d.Name.Name] = d
+					fileOf[d.Name.Name] = f
+				}
+			case *ast.GenDecl:
+				if d.Tok != token.VAR {
+					continue
+				}
+				for _, sp := range d.Specs {
+					vs := sp.(*ast.ValueSpec)
+					for i, name := range vs.Names {
+						vars[name.Name] = true
+						if name.Name == "postMigrations" && i < len(vs.Values) {
+							post, _ = vs.Values[i].(*ast.CompositeLit)
+						}
+					}
+				}
+			}
+		}
+	}
+	if post == nil {
+		t.Fatal("postMigrations not found")
+	}
+
+	var queue []string
+	for _, el := range post.Elts {
+		kv, ok := el.(*ast.KeyValueExpr)
+		if !ok {
+			t.Fatalf("postMigrations entry is not key: value")
+		}
+		id, ok := kv.Value.(*ast.Ident)
+		if !ok {
+			t.Errorf("postMigrations[%s] must name a top-level function, not an expression", exprText(kv.Key))
+			continue
+		}
+		queue = append(queue, id.Name)
+	}
+
+	seen := map[string]bool{}
+	var problems []string
+	for len(queue) > 0 {
+		name := queue[0]
+		queue = queue[1:]
+		if seen[name] {
+			continue
+		}
+		seen[name] = true
+		fd, ok := funcs[name]
+		if !ok {
+			problems = append(problems, name+": not a top-level function of this package (a method or a closure?)")
+			continue
+		}
+		imports := map[string]string{}
+		for _, im := range fileOf[name].Imports {
+			p, _ := strconv.Unquote(im.Path.Value)
+			local := p[strings.LastIndex(p, "/")+1:]
+			if im.Name != nil {
+				local = im.Name.Name
+			}
+			imports[local] = p
+		}
+		local := localNames(fd)
+		var visit func(n ast.Node) bool
+		visit = func(n ast.Node) bool {
+			switch n := n.(type) {
+			case *ast.SelectorExpr:
+				if x, ok := n.X.(*ast.Ident); ok {
+					if p, isPkg := imports[x.Name]; isPkg && !local[x.Name] {
+						if strings.Contains(strings.SplitN(p, "/", 2)[0], ".") {
+							problems = append(problems, name+": uses "+p+"."+n.Sel.Name+" (only the standard library is frozen)")
+						}
+						return false
+					}
+				}
+				ast.Inspect(n.X, visit) // n.Sel is a field or method name, not a package-level name
+				return false
+			case *ast.Ident:
+				if local[n.Name] {
+					return true
+				}
+				if _, isFunc := funcs[n.Name]; isFunc {
+					queue = append(queue, n.Name)
+				}
+				if vars[n.Name] && !frozenVar.MatchString(n.Name) {
+					problems = append(problems, name+": reads package variable "+n.Name+" (copy it into a variable named …V<step> frozen with the migration)")
+				}
+			}
+			return true
+		}
+		ast.Inspect(fd.Body, visit)
+	}
+	sort.Strings(problems)
+	for _, p := range dedupe(problems) {
+		t.Error(p)
+	}
+}
+
+// localNames lists every name a function declares itself (parameters, results, := and var, range
+// variables, closure parameters), so they are not mistaken for package-level names. Scoping is
+// ignored: a local that shadows a package name hides it everywhere in the function, which only
+// errs towards allowing.
+func localNames(fd *ast.FuncDecl) map[string]bool {
+	local := map[string]bool{}
+	addFields := func(fl *ast.FieldList) {
+		if fl == nil {
+			return
+		}
+		for _, f := range fl.List {
+			for _, n := range f.Names {
+				local[n.Name] = true
+			}
+		}
+	}
+	addFields(fd.Type.Params)
+	addFields(fd.Type.Results)
+	ast.Inspect(fd.Body, func(n ast.Node) bool {
+		switch n := n.(type) {
+		case *ast.AssignStmt:
+			if n.Tok == token.DEFINE {
+				for _, l := range n.Lhs {
+					if id, ok := l.(*ast.Ident); ok {
+						local[id.Name] = true
+					}
+				}
+			}
+		case *ast.ValueSpec:
+			for _, id := range n.Names {
+				local[id.Name] = true
+			}
+		case *ast.TypeSpec:
+			local[n.Name.Name] = true
+		case *ast.RangeStmt:
+			if n.Tok == token.DEFINE {
+				for _, e := range []ast.Expr{n.Key, n.Value} {
+					if id, ok := e.(*ast.Ident); ok {
+						local[id.Name] = true
+					}
+				}
+			}
+		case *ast.FuncLit:
+			addFields(n.Type.Params)
+			addFields(n.Type.Results)
+		case *ast.KeyValueExpr:
+			if id, ok := n.Key.(*ast.Ident); ok {
+				local[id.Name] = true // a struct field name in a literal
+			}
+		}
+		return true
+	})
+	return local
+}
+
+func dedupe(xs []string) []string {
+	var out []string
+	for i, x := range xs {
+		if i == 0 || x != xs[i-1] {
+			out = append(out, x)
+		}
+	}
+	return out
+}
+
+func exprText(e ast.Expr) string {
+	if b, ok := e.(*ast.BasicLit); ok {
+		return b.Value
+	}
+	return "?"
+}
diff --git a/internal/store/schema_fingerprint.go b/internal/store/schema_fingerprint.go
new file mode 100644
index 0000000..a45d752
--- /dev/null
+++ b/internal/store/schema_fingerprint.go
@@ -0,0 +1,7 @@
+// Code generated by "go test ./internal/store -run TestSchemaFingerprint -update-schema"; DO NOT EDIT.
+
+package store
+
+// schemaFingerprintWant is the fingerprint of the schema this program's migrations build (see
+// schemaFingerprint). testdata/schema.txt is the same schema, readable.
+const schemaFingerprintWant = "0ff1d2424e6723510aaa3f0ed00cc5767d022f432167cb057d5101859c50154d"
diff --git a/internal/store/schema_fingerprint_test.go b/internal/store/schema_fingerprint_test.go
new file mode 100644
index 0000000..050fb39
--- /dev/null
+++ b/internal/store/schema_fingerprint_test.go
@@ -0,0 +1,106 @@
+package store
+
+import (
+	"database/sql"
+	"flag"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+var updateSchema = flag.Bool("update-schema", false, "rewrite schema_fingerprint.go and testdata/schema.txt from the current migrations")
+
+const schemaDump = "testdata/schema.txt"
+
+// TestSchemaFingerprint keeps the compiled-in fingerprint, and the readable dump reviewers diff, in
+// step with the migrations. After adding a migration: go test ./internal/store -run TestSchemaFingerprint -update-schema
+func TestSchemaFingerprint(t *testing.T) {
+	s, err := Open(filepath.Join(t.TempDir(), "fresh.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer s.Close() //nolint:errcheck // test
+	sum, lines, err := schemaFingerprint(s.db)
+	if err != nil {
+		t.Fatal(err)
+	}
+	dump := strings.Join(lines, "\n") + "\n"
+	if *updateSchema {
+		src := fmt.Sprintf(`// Code generated by "go test ./internal/store -run TestSchemaFingerprint -update-schema"; DO NOT EDIT.
+
+package store
+
+// schemaFingerprintWant is the fingerprint of the schema this program's migrations build (see
+// schemaFingerprint). testdata/schema.txt is the same schema, readable.
+const schemaFingerprintWant = %q
+`, sum)
+		if err := os.WriteFile("schema_fingerprint.go", []byte(src), 0o644); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.MkdirAll("testdata", 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(schemaDump, []byte(dump), 0o644); err != nil {
+			t.Fatal(err)
+		}
+		return
+	}
+	if sum != schemaFingerprintWant {
+		t.Errorf("the schema changed (fingerprint %s, compiled in %q). Run: go test ./internal/store -run TestSchemaFingerprint -update-schema, and review the diff of %s", sum, schemaFingerprintWant, schemaDump)
+	}
+	want, err := os.ReadFile(schemaDump)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.ReplaceAll(string(want), "\r\n", "\n") != dump {
+		t.Errorf("%s is out of date; regenerate it with -update-schema", schemaDump)
+	}
+}
+
+// The fingerprint sees the changes that matter and ignores the spelling of the SQL.
+func TestSchemaFingerprintSeesStructure(t *testing.T) {
+	base, _, err := fingerprintOf(t, `CREATE TABLE t (a INTEGER PRIMARY KEY, b TEXT NOT NULL DEFAULT '')`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	same, _, _ := fingerprintOf(t, "CREATE TABLE t (\n\ta INTEGER PRIMARY KEY,\n\tb TEXT NOT NULL DEFAULT ''\n)")
+	if same != base {
+		t.Error("whitespace in the SQL changed the fingerprint")
+	}
+	for name, ddl := range map[string]string{
+		"a new column":       `CREATE TABLE t (a INTEGER PRIMARY KEY, b TEXT NOT NULL DEFAULT '', c INTEGER)`,
+		"another default":    `CREATE TABLE t (a INTEGER PRIMARY KEY, b TEXT NOT NULL DEFAULT 'x')`,
+		"nullable":           `CREATE TABLE t (a INTEGER PRIMARY KEY, b TEXT DEFAULT '')`,
+		"an index":           `CREATE TABLE t (a INTEGER PRIMARY KEY, b TEXT NOT NULL DEFAULT ''); CREATE INDEX t_b ON t(b)`,
+		"a partial index":    `CREATE TABLE t (a INTEGER PRIMARY KEY, b TEXT NOT NULL DEFAULT ''); CREATE INDEX t_b ON t(b) WHERE b <> ''`,
+		"a trigger":          `CREATE TABLE t (a INTEGER PRIMARY KEY, b TEXT NOT NULL DEFAULT ''); CREATE TRIGGER t_no BEFORE DELETE ON t BEGIN SELECT RAISE(ABORT, 'no'); END`,
+		"another table name": `CREATE TABLE u (a INTEGER PRIMARY KEY, b TEXT NOT NULL DEFAULT '')`,
+	} {
+		got, _, err := fingerprintOf(t, ddl)
+		if err != nil {
+			t.Fatalf("%s: %v", name, err)
+		}
+		if got == base {
+			t.Errorf("%s did not change the fingerprint", name)
+		}
+	}
+}
+
+func fingerprintOf(t *testing.T, ddl string) (string, []string, error) {
+	t.Helper()
+	db, err := openReadWriteForTest(filepath.Join(t.TempDir(), "x.db"))
+	if err != nil {
+		return "", nil, err
+	}
+	defer db.Close() //nolint:errcheck // test
+	if _, err := db.Exec(ddl); err != nil {
+		return "", nil, err
+	}
+	return schemaFingerprint(db)
+}
+
+func openReadWriteForTest(path string) (*sql.DB, error) {
+	return sql.Open("sqlite", "file:"+path)
+}
diff --git a/internal/store/store.go b/internal/store/store.go
index 7c7e046..d977185 100644
--- a/internal/store/store.go
+++ b/internal/store/store.go
@@ -54,6 +54,7 @@ type Store struct {
 	path string
 	now  func() time.Time
 	log  *slog.Logger
+	lock *fileLock // held for the Store's life when opened Exclusive
 
 	// opened holds what Open did on its own (a backup, a deleted old backup) until SetLogger
 	// gives it somewhere to go: Open runs before the caller has set a logger.
@@ -69,7 +70,8 @@ type Store struct {
 	corrDone    uint64 // requests covered by a finished run
 }
 
-// Open opens (creating if needed) the database at path and applies migrations.
+// Open opens (creating if needed) the database at path and upgrades it if it is older than this
+// program (see upgrade.go for the steps and what happens when one fails).
 //
 // The file holds an organisation's scan results and host inventories, so it is
 // created owner-only (0600) and an existing one is tightened. SQLite gives its
@@ -78,30 +80,57 @@ type Store struct {
 // Every transaction is opened IMMEDIATE: a write transaction takes the write lock when it begins,
 // so two of them queue behind the busy timeout instead of one failing at its first write with
 // "database is locked" (a deferred transaction that read first cannot be upgraded under WAL).
-func Open(path string) (*Store, error) {
+func Open(path string) (*Store, error) { return OpenWith(path, OpenOptions{}) }
+
+// OpenWith is Open with options: a server opens Exclusive, and may refuse to upgrade.
+func OpenWith(path string, o OpenOptions) (*Store, error) {
+	var lk *fileLock
+	if o.Exclusive && lockable(path) {
+		// Taken before the file is touched, so a second server never even creates it.
+		var err error
+		if lk, err = acquireLock(path); err != nil {
+			return nil, err
+		}
+	}
 	if err := restrictFile(path); err != nil {
+		lk.release()
 		return nil, fmt.Errorf("store: securing %s: %w", path, err)
 	}
 	db, err := sql.Open("sqlite", dsnFor(path))
 	if err != nil {
+		lk.release()
 		return nil, err
 	}
 	db.SetMaxOpenConns(8)
 	if err := db.Ping(); err != nil {
 		_ = db.Close()
+		lk.release()
 		return nil, fmt.Errorf("store: opening %s: %w", path, err)
 	}
-	s := &Store{db: db, path: path, now: time.Now, log: slog.New(slog.DiscardHandler), holding: true}
+	s := &Store{db: db, path: path, now: time.Now, log: slog.New(slog.DiscardHandler), holding: true, lock: lk}
 	s.corrCond = sync.NewCond(&s.corrMu)
-	if err := s.migrate(); err != nil {
+	res, err := s.migrate(o)
+	if err != nil {
 		_ = db.Close()
+		if res.restoreFrom != "" {
+			// The upgrade failed part-way or failed its checks: put the file back as it was.
+			if kept, rerr := restoreAfterFailedUpgrade(path, res.restoreFrom); rerr != nil {
+				err = fmt.Errorf("%w; putting the backup back also failed (%w): restore it by hand with cipherhorizon db restore --db %s %s", err, rerr, path, res.restoreFrom)
+			} else {
+				err = fmt.Errorf("%w. The database was put back exactly as it was before the upgrade (from %s), and the failed copy kept as %s for diagnosis; this version will not run on it until the problem is fixed", err, res.restoreFrom, kept)
+			}
+		}
+		res.lock.release()
+		lk.release()
 		return nil, err
 	}
+	res.lock.release()
 	s.noticeMu.Lock()
 	s.holding = false
 	s.noticeMu.Unlock()
 	if err := s.ensureProjection(); err != nil {
 		_ = db.Close()
+		lk.release()
 		return nil, err
 	}
 	return s, nil
@@ -157,8 +186,12 @@ func (s *Store) notice(msg string, args ...any) {
 // SetClock replaces the time source (tests).
 func (s *Store) SetClock(now func() time.Time) { s.now = now }
 
-// Close closes the database.
-func (s *Store) Close() error { return s.db.Close() }
+// Close closes the database and gives back its lock.
+func (s *Store) Close() error {
+	err := s.db.Close()
+	s.lock.release()
+	return err
+}
 
 var migrations = []string{
 	// 1: initial schema
@@ -453,6 +486,16 @@ var migrations = []string{
 	// strength alone. Every stored scan's band is carried over to its new name; the score is unchanged.
 	`UPDATE scans SET band = CASE band WHEN 'Strong' THEN 'Excellent' WHEN 'Sound' THEN 'Good'
 		WHEN 'Weak' THEN 'Poor' WHEN 'Broken' THEN 'Failing' ELSE band END;`,
+	// 16: every upgrade (and the first creation) is recorded: from which schema to which, by which
+	// version, and the backup made first (PRD-016 U-07). cipherhorizon db status lists them.
+	`CREATE TABLE upgrade_log (
+		id INTEGER PRIMARY KEY AUTOINCREMENT,
+		at TEXT NOT NULL,
+		from_schema INTEGER NOT NULL,
+		to_schema INTEGER NOT NULL,
+		app_version TEXT NOT NULL DEFAULT '',
+		backup TEXT NOT NULL DEFAULT ''
+	);`,
 }
 
 // postMigrations are steps that need Go rather than SQL. They run inside the same
@@ -474,50 +517,6 @@ const (
 	FindingAcceptedRisk = "accepted-risk"
 )
 
-func (s *Store) migrate() error {
-	if _, err := s.db.Exec(`CREATE TABLE IF NOT EXISTS schema_migrations (version INTEGER PRIMARY KEY, applied_at TEXT NOT NULL)`); err != nil {
-		return err
-	}
-	var have int
-	if err := s.db.QueryRow(`SELECT COALESCE(MAX(version), 0) FROM schema_migrations`).Scan(&have); err != nil {
-		return err
-	}
-	if have > len(migrations) {
-		return fmt.Errorf("store: database schema version %d is newer than this program understands (%d)", have, len(migrations))
-	}
-	if have > 0 && have < len(migrations) {
-		// An existing database is about to change shape: keep a copy first (SR-10). If the
-		// copy cannot be made, nothing is changed.
-		if err := s.backup(have); err != nil {
-			return fmt.Errorf("store: cannot back up %s before migrating from version %d, so it was not changed: %w", s.path, have, err)
-		}
-	}
-	for v := have + 1; v <= len(migrations); v++ {
-		tx, err := s.db.Begin()
-		if err != nil {
-			return err
-		}
-		if _, err := tx.Exec(migrations[v-1]); err != nil {
-			_ = tx.Rollback()
-			return fmt.Errorf("store: migration %d: %w", v, err)
-		}
-		if post := postMigrations[v]; post != nil {
-			if err := post(tx, s.now()); err != nil {
-				_ = tx.Rollback()
-				return fmt.Errorf("store: migration %d: %w", v, err)
-			}
-		}
-		if _, err := tx.Exec(`INSERT INTO schema_migrations (version, applied_at) VALUES (?, ?)`, v, ts(s.now())); err != nil {
-			_ = tx.Rollback()
-			return err
-		}
-		if err := tx.Commit(); err != nil {
-			return err
-		}
-	}
-	return nil
-}
-
 // ---- time helpers --------------------------------------------------------------------
 
 // tsLayout is how every time is stored: UTC, always nine fractional digits, so that comparing
@@ -526,8 +525,10 @@ const tsLayout = "2006-01-02T15:04:05.000000000Z07:00"
 
 func ts(t time.Time) string { return t.UTC().Format(tsLayout) }
 
-// timestampColumns are every column holding a time written by ts (migration 10 rewrites them).
-var timestampColumns = map[string][]string{
+// timestampColumnsV10 are the columns migration 10 rewrites: every column holding a time as the
+// schema stood at step 10. Frozen with that step, like its SQL: a table added later must never be
+// listed here, because a database upgraded from before step 10 does not have it yet at step 10.
+var timestampColumnsV10 = map[string][]string{
 	"asset_links":       {"created_at"},
 	"assets":            {"created_at", "next_scan_at", "updated_at"},
 	"audit_log":         {"at"},
@@ -556,7 +557,7 @@ func backfillTimestamps(tx *sql.Tx, _ time.Time) error {
 	if _, err := tx.Exec(`DROP TRIGGER audit_log_no_update`); err != nil {
 		return err
 	}
-	for table, cols := range timestampColumns {
+	for table, cols := range timestampColumnsV10 {
 		for _, col := range cols {
 			if err := reformatColumnTx(tx, table, col); err != nil {
 				return fmt.Errorf("%s.%s: %w", table, col, err)
@@ -568,7 +569,7 @@ func backfillTimestamps(tx *sql.Tx, _ time.Time) error {
 }
 
 func reformatColumnTx(tx *sql.Tx, table, col string) error {
-	// table and col come from timestampColumns, a constant list, never from input.
+	// table and col come from timestampColumnsV10, a constant list, never from input.
 	rows, err := tx.Query(`SELECT rowid, ` + col + ` FROM ` + table + ` WHERE ` + col + ` IS NOT NULL AND ` + col + ` <> ''`) //nolint:gosec // constant identifiers
 	if err != nil {
 		return err
diff --git a/internal/store/systems.go b/internal/store/systems.go
index f4dd3e1..a3bc1ab 100644
--- a/internal/store/systems.go
+++ b/internal/store/systems.go
@@ -703,9 +703,10 @@ func backfillSystems(tx *sql.Tx, now time.Time) error {
 }
 
 // backup writes a consistent copy of the database next to it before a migration.
-func (s *Store) backup(version int) error {
+// It returns the backup's path ("" for a database that is not a plain file, which gets none).
+func (s *Store) backup(version int) (string, error) {
 	if s.path == "" || s.path == ":memory:" || strings.HasPrefix(s.path, "file:") {
-		return nil
+		return "", nil
 	}
 	base := fmt.Sprintf("%s.bak-v%d-%s", s.path, version, s.now().UTC().Format("20060102T150405Z"))
 	dst := base
@@ -714,23 +715,23 @@ func (s *Store) backup(version int) error {
 			break
 		}
 		if n > 99 {
-			return fmt.Errorf("%s and its numbered variants already exist", base)
+			return "", fmt.Errorf("%s and its numbered variants already exist", base)
 		}
 		dst = fmt.Sprintf("%s-%d", base, n)
 	}
 	if err := restrictFile(dst); err != nil {
-		return err
+		return "", err
 	}
 	if _, err := s.db.Exec(`VACUUM INTO ?`, dst); err != nil {
 		_ = os.Remove(dst)
-		return err
+		return "", err
 	}
 	if err := restrictFile(dst); err != nil {
-		return err
+		return "", err
 	}
 	s.notice("backed up the database before migrating it", "backup", dst)
-	s.pruneBackups()
-	return nil
+	s.pruneBackups(dst)
+	return dst, nil
 }
 
 // BackupTo writes a consistent copy of the database to dst, owner-only, while it stays in use
@@ -754,8 +755,9 @@ func (s *Store) BackupTo(dst string) error {
 const keepBackups = 3
 
 // pruneBackups deletes all but the newest keepBackups pre-migration backups and reports each one
-// it deletes. A backup it cannot delete is reported and left; the migration goes on.
-func (s *Store) pruneBackups() {
+// it deletes. A backup it cannot delete is reported and left; the migration goes on. keep (the
+// backup just made, which a failed upgrade restores from) is never deleted, whatever the clock says.
+func (s *Store) pruneBackups(keep string) {
 	names, err := filepath.Glob(s.path + ".bak-v*")
 	if err != nil || len(names) <= keepBackups {
 		return
@@ -777,6 +779,9 @@ func (s *Store) pruneBackups() {
 		return baks[i].name > baks[j].name
 	})
 	for _, b := range baks[min(keepBackups, len(baks)):] {
+		if b.name == keep {
+			continue
+		}
 		if err := os.Remove(b.name); err != nil {
 			s.notice("could not delete an old backup", "backup", b.name, "err", err.Error())
 			continue
diff --git a/internal/store/testdata/schema.txt b/internal/store/testdata/schema.txt
new file mode 100644
index 0000000..02854ee
--- /dev/null
+++ b/internal/store/testdata/schema.txt
@@ -0,0 +1,253 @@
+index-sql one_active_scan on scans: CREATE UNIQUE INDEX one_active_scan ON scans(asset_id) WHERE status IN ('queued','running')
+table asset_links
+  column asset_id INTEGER 1 NULL 1 0
+  column linked_asset_id INTEGER 1 NULL 2 0
+  column created_at TEXT 1 NULL 0 0
+  foreign-key assets linked_asset_id id NO ACTION CASCADE
+  foreign-key assets asset_id id NO ACTION CASCADE
+  index sqlite_autoindex_asset_links_1 1 pk 0 (asset_id:0:BINARY, linked_asset_id:0:BINARY)
+table assets
+  column id INTEGER 0 NULL 1 0
+  column kind TEXT 1 NULL 0 0
+  column name TEXT 1 NULL 0 0
+  column host TEXT 1 NULL 0 0
+  column port INTEGER 1 0 0 0
+  column tags TEXT 1 '[]' 0 0
+  column notes TEXT 1 '' 0 0
+  column interval_seconds INTEGER 1 0 0 0
+  column next_scan_at TEXT 0 NULL 0 0
+  column created_at TEXT 1 NULL 0 0
+  column updated_at TEXT 1 NULL 0 0
+  column system_id INTEGER 0 NULL 0 0
+  column starttls TEXT 1 'auto' 0 0
+  foreign-key systems system_id id NO ACTION NO ACTION
+  index assets_system 0 c 0 (system_id:0:BINARY)
+  index sqlite_autoindex_assets_1 1 u 0 (kind:0:BINARY, host:0:BINARY, port:0:BINARY)
+table audit_log
+  column id INTEGER 0 NULL 1 0
+  column at TEXT 1 NULL 0 0
+  column actor TEXT 1 NULL 0 0
+  column object_kind TEXT 1 NULL 0 0
+  column object_id INTEGER 1 NULL 0 0
+  column action TEXT 1 NULL 0 0
+  column before_json TEXT 1 '{}' 0 0
+  column after_json TEXT 1 '{}' 0 0
+  column reason TEXT 1 '' 0 0
+  index audit_log_at 0 c 0 (at:0:BINARY)
+  index audit_object 0 c 0 (object_kind:0:BINARY, object_id:0:BINARY, id:0:BINARY)
+table auth_events
+  column id INTEGER 0 NULL 1 0
+  column at TEXT 1 NULL 0 0
+  column kind TEXT 1 NULL 0 0
+  column username TEXT 1 '' 0 0
+  column actor TEXT 1 '' 0 0
+  column client TEXT 1 '' 0 0
+  column detail TEXT 1 '' 0 0
+  index auth_events_at 0 c 0 (at:0:BINARY)
+table entities
+  column id INTEGER 0 NULL 1 0
+  column kind TEXT 1 NULL 0 0
+  column key TEXT 1 NULL 0 0
+  column name TEXT 1 '' 0 0
+  column attrs_json TEXT 1 '{}' 0 0
+  index sqlite_autoindex_entities_1 1 u 0 (kind:0:BINARY, key:0:BINARY)
+table finding_status
+  column asset_id INTEGER 1 NULL 1 0
+  column finding_key TEXT 1 NULL 2 0
+  column status TEXT 1 NULL 0 0
+  column note TEXT 1 '' 0 0
+  column set_at TEXT 1 NULL 0 0
+  foreign-key assets asset_id id NO ACTION CASCADE
+  index sqlite_autoindex_finding_status_1 1 pk 0 (asset_id:0:BINARY, finding_key:0:BINARY)
+table host_snapshots
+  column id INTEGER 0 NULL 1 0
+  column asset_id INTEGER 1 NULL 0 0
+  column at TEXT 1 NULL 0 0
+  column cbom_json BLOB 1 NULL 0 0
+  column summary_json BLOB 1 NULL 0 0
+  column source_class TEXT 1 'imported' 0 0
+  column submitted_by TEXT 1 '' 0 0
+  foreign-key assets asset_id id NO ACTION CASCADE
+  index host_snapshots_asset 0 c 0 (asset_id:0:BINARY, id:1:BINARY)
+table imports
+  column id INTEGER 0 NULL 1 0
+  column sha256 TEXT 1 NULL 0 0
+  column spec_version TEXT 1 NULL 0 0
+  column profile TEXT 1 NULL 0 0
+  column kind TEXT 1 NULL 0 0
+  column cbom_json BLOB 1 NULL 0 0
+  column created_at TEXT 1 NULL 0 0
+  index sqlite_autoindex_imports_1 1 u 0 (sha256:0:BINARY)
+table links
+  column id INTEGER 0 NULL 1 0
+  column asset_id INTEGER 1 NULL 0 0
+  column system_id INTEGER 1 NULL 0 0
+  column state TEXT 1 NULL 0 0
+  column strength TEXT 1 NULL 0 0
+  column rules_json TEXT 1 '[]' 0 0
+  column evidence_json TEXT 1 '{}' 0 0
+  column stale INTEGER 1 0 0 0
+  column decided_by TEXT 1 '' 0 0
+  column decided_at TEXT 0 NULL 0 0
+  column created_at TEXT 1 NULL 0 0
+  column updated_at TEXT 1 NULL 0 0
+  foreign-key systems system_id id NO ACTION CASCADE
+  foreign-key assets asset_id id NO ACTION CASCADE
+  index links_state 0 c 0 (state:0:BINARY)
+  index sqlite_autoindex_links_1 1 u 0 (asset_id:0:BINARY, system_id:0:BINARY)
+table observations
+  column id INTEGER 0 NULL 1 0
+  column source_id INTEGER 1 NULL 0 0
+  column entity_id INTEGER 1 NULL 0 0
+  column relation TEXT 1 NULL 0 0
+  column via TEXT 1 '' 0 0
+  column rung TEXT 1 NULL 0 0
+  column class INTEGER 1 NULL 0 0
+  column method TEXT 1 NULL 0 0
+  column quality TEXT 1 NULL 0 0
+  column observed_at TEXT 1 NULL 0 0
+  column attrs_json TEXT 1 '{}' 0 0
+  foreign-key entities entity_id id NO ACTION NO ACTION
+  foreign-key sources source_id id NO ACTION CASCADE
+  index observations_entity 0 c 0 (entity_id:0:BINARY)
+  index observations_source 0 c 0 (source_id:0:BINARY)
+table projection_state
+  column id INTEGER 0 NULL 1 0
+  column version INTEGER 1 NULL 0 0
+  column built_at TEXT 1 NULL 0 0
+  column stale INTEGER 1 0 0 0
+table scan_events
+  column id INTEGER 0 NULL 1 0
+  column scan_id INTEGER 1 NULL 0 0
+  column at TEXT 1 NULL 0 0
+  column message TEXT 1 NULL 0 0
+  foreign-key scans scan_id id NO ACTION CASCADE
+  index scan_events_scan 0 c 0 (scan_id:0:BINARY, id:0:BINARY)
+table scans
+  column id INTEGER 0 NULL 1 0
+  column asset_id INTEGER 1 NULL 0 0
+  column status TEXT 1 NULL 0 0
+  column trigger TEXT 1 NULL 0 0
+  column stage TEXT 1 '' 0 0
+  column progress_pct INTEGER 1 0 0 0
+  column connections INTEGER 1 0 0 0
+  column queued_at TEXT 1 NULL 0 0
+  column started_at TEXT 0 NULL 0 0
+  column finished_at TEXT 0 NULL 0 0
+  column error TEXT 1 '' 0 0
+  column report_json BLOB 0 NULL 0 0
+  column eval_json BLOB 0 NULL 0 0
+  column band TEXT 1 '' 0 0
+  column readiness_level INTEGER 0 NULL 0 0
+  column hndl_exposed INTEGER 1 0 0 0
+  column crit INTEGER 1 0 0 0
+  column high INTEGER 1 0 0 0
+  column medium INTEGER 1 0 0 0
+  column cert_not_after TEXT 0 NULL 0 0
+  column incomplete INTEGER 1 0 0 0
+  column score INTEGER 1 -1 0 0
+  column low INTEGER 1 0 0 0
+  column info INTEGER 1 0 0 0
+  column started_by TEXT 1 '' 0 0
+  column service TEXT 1 '' 0 0
+  column host_key TEXT 1 '' 0 0
+  column baseline TEXT 1 '' 0 0
+  column baseline_meets INTEGER 0 NULL 0 0
+  column baseline_changes INTEGER 1 0 0 0
+  foreign-key assets asset_id id NO ACTION CASCADE
+  index one_active_scan 1 c 1 (asset_id:0:BINARY)
+  index scans_asset 0 c 0 (asset_id:0:BINARY, id:1:BINARY)
+  index scans_status 0 c 0 (status:0:BINARY, id:0:BINARY)
+table schema_migrations
+  column version INTEGER 0 NULL 1 0
+  column applied_at TEXT 1 NULL 0 0
+table sessions
+  column id INTEGER 0 NULL 1 0
+  column token_hash TEXT 1 NULL 0 0
+  column user_id INTEGER 1 NULL 0 0
+  column created_at TEXT 1 NULL 0 0
+  column last_seen_at TEXT 1 NULL 0 0
+  column expires_at TEXT 1 NULL 0 0
+  column client TEXT 1 '' 0 0
+  column user_agent TEXT 1 '' 0 0
+  foreign-key users user_id id NO ACTION CASCADE
+  index sessions_user 0 c 0 (user_id:0:BINARY)
+  index sqlite_autoindex_sessions_1 1 u 0 (token_hash:0:BINARY)
+table settings
+  column key TEXT 0 NULL 1 0
+  column value TEXT 1 NULL 0 0
+  index sqlite_autoindex_settings_1 1 pk 0 (key:0:BINARY)
+table sources
+  column id INTEGER 0 NULL 1 0
+  column class TEXT 1 NULL 0 0
+  column stream TEXT 1 NULL 0 0
+  column ref_kind TEXT 1 NULL 0 0
+  column ref_id INTEGER 1 NULL 0 0
+  column asset_id INTEGER 0 NULL 0 0
+  column system_id INTEGER 0 NULL 0 0
+  column tool_name TEXT 1 '' 0 0
+  column tool_version TEXT 1 '' 0 0
+  column sha256 TEXT 1 '' 0 0
+  column size INTEGER 1 0 0 0
+  column received_at TEXT 1 NULL 0 0
+  column observed_at TEXT 1 NULL 0 0
+  column submitted_by TEXT 1 '' 0 0
+  column subject_claim TEXT 1 '' 0 0
+  column status TEXT 1 'active' 0 0
+  column is_current INTEGER 1 1 0 0
+  column not_interpreted_json TEXT 1 '{}' 0 0
+  foreign-key systems system_id id NO ACTION CASCADE
+  foreign-key assets asset_id id NO ACTION CASCADE
+  index sources_asset 0 c 0 (asset_id:0:BINARY, is_current:0:BINARY)
+  index sqlite_autoindex_sources_1 1 u 0 (ref_kind:0:BINARY, ref_id:0:BINARY)
+table systems
+  column id INTEGER 0 NULL 1 0
+  column name TEXT 1 NULL 0 0
+  column owner TEXT 1 '' 0 0
+  column environment TEXT 1 '' 0 0
+  column criticality TEXT 1 '' 0 0
+  column exposure TEXT 1 '' 0 0
+  column data_lifetime_years INTEGER 0 NULL 0 0
+  column fisma_id TEXT 1 '' 0 0
+  column fips199 TEXT 1 '' 0 0
+  column hva_id TEXT 1 '' 0 0
+  column hosting TEXT 1 '' 0 0
+  column hosting_provider TEXT 1 '' 0 0
+  column notes TEXT 1 '' 0 0
+  column created_at TEXT 1 NULL 0 0
+  column updated_at TEXT 1 NULL 0 0
+table trust_anchors
+  column id INTEGER 0 NULL 1 0
+  column system_id INTEGER 1 NULL 0 0
+  column sha256 TEXT 1 NULL 0 0
+  column subject TEXT 1 NULL 0 0
+  column not_after TEXT 1 NULL 0 0
+  column pem TEXT 1 NULL 0 0
+  column added_at TEXT 1 NULL 0 0
+  column added_by TEXT 1 NULL 0 0
+  foreign-key systems system_id id NO ACTION CASCADE
+  index sqlite_autoindex_trust_anchors_1 1 u 0 (system_id:0:BINARY, sha256:0:BINARY)
+table upgrade_log
+  column id INTEGER 0 NULL 1 0
+  column at TEXT 1 NULL 0 0
+  column from_schema INTEGER 1 NULL 0 0
+  column to_schema INTEGER 1 NULL 0 0
+  column app_version TEXT 1 '' 0 0
+  column backup TEXT 1 '' 0 0
+table users
+  column id INTEGER 0 NULL 1 0
+  column username TEXT 1 NULL 0 0
+  column display_name TEXT 1 '' 0 0
+  column role TEXT 1 NULL 0 0
+  column password_hash TEXT 1 NULL 0 0
+  column disabled INTEGER 1 0 0 0
+  column must_change INTEGER 1 0 0 0
+  column failed_count INTEGER 1 0 0 0
+  column locked_until TEXT 0 NULL 0 0
+  column created_at TEXT 1 NULL 0 0
+  column created_by TEXT 1 '' 0 0
+  column password_changed_at TEXT 1 NULL 0 0
+  column last_login_at TEXT 0 NULL 0 0
+  index sqlite_autoindex_users_1 1 u 0 (username:0:NOCASE)
+trigger audit_log_no_delete on audit_log: CREATE TRIGGER audit_log_no_delete BEFORE DELETE ON audit_log BEGIN SELECT RAISE(ABORT, 'audit_log is append-only'); END
+trigger audit_log_no_update on audit_log: CREATE TRIGGER audit_log_no_update BEFORE UPDATE ON audit_log BEGIN SELECT RAISE(ABORT, 'audit_log is append-only'); END
diff --git a/internal/store/testdata/upgrade/v0.1.0.db b/internal/store/testdata/upgrade/v0.1.0.db
new file mode 100644
index 0000000..c5ef830
Binary files /dev/null and b/internal/store/testdata/upgrade/v0.1.0.db differ
diff --git a/internal/store/testdata/upgrade/v0.2.0.db b/internal/store/testdata/upgrade/v0.2.0.db
new file mode 100644
index 0000000..dfae483
Binary files /dev/null and b/internal/store/testdata/upgrade/v0.2.0.db differ
diff --git a/internal/store/testdata/upgrade/v0.3.0.db b/internal/store/testdata/upgrade/v0.3.0.db
new file mode 100644
index 0000000..cfbd953
Binary files /dev/null and b/internal/store/testdata/upgrade/v0.3.0.db differ
diff --git a/internal/store/testdata/upgrade/v0.4.0.db b/internal/store/testdata/upgrade/v0.4.0.db
new file mode 100644
index 0000000..71c11d6
Binary files /dev/null and b/internal/store/testdata/upgrade/v0.4.0.db differ
diff --git a/internal/store/upgrade.go b/internal/store/upgrade.go
new file mode 100644
index 0000000..6aa8ce3
--- /dev/null
+++ b/internal/store/upgrade.go
@@ -0,0 +1,706 @@
+package store
+
+import (
+	"crypto/sha256"
+	"database/sql"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/offsetsecurity/cipherhorizon/internal/osfile"
+	"github.com/offsetsecurity/cipherhorizon/internal/version"
+)
+
+// Upgrading a database (PRD-016 §5). Every command that opens the database upgrades it when it is
+// older than this program: serve at launch, and the user and db commands. The steps, in order:
+//
+//  1. take the database's lock, so no other CipherHorizon process uses it while it changes;
+//  2. check there is room for a backup;
+//  3. back it up (VACUUM INTO, next to it);
+//  4. run each missing migration, one transaction each;
+//  5. verify: SQLite's own consistency check, no new foreign-key violations, and the schema's
+//     fingerprint against the one this program was built with;
+//  6. record the upgrade in upgrade_log.
+//
+// If step 4 or 5 fails, the database is put back exactly as it was (from the step-3 backup) and the
+// program refuses to start, saying why. Nothing is ever left half-upgraded.
+
+// MigrateMode says what Open does with an older database.
+type MigrateMode int
+
+const (
+	// MigrateAuto upgrades it (the default).
+	MigrateAuto MigrateMode = iota
+	// MigrateRefuse leaves it alone and fails with *MigrationNeededError, for sites whose change
+	// control wants the upgrade run as its own step (cipherhorizon db migrate).
+	MigrateRefuse
+)
+
+// OpenOptions changes how OpenWith opens a database. The zero value is what Open does.
+type OpenOptions struct {
+	// Exclusive holds the database's lock for as long as the Store is open: a server takes it, so
+	// a second server (or an upgrade by another version) on the same file is refused.
+	Exclusive bool
+	// Migrate says whether an older database is upgraded.
+	Migrate MigrateMode
+}
+
+// MigrationNeededError is returned under MigrateRefuse when the database is older than this program.
+type MigrationNeededError struct {
+	Path       string
+	Have, Want int
+}
+
+func (e *MigrationNeededError) Error() string {
+	return fmt.Sprintf("store: %s is at schema %d and this program needs %d; it was not changed. Upgrade it with: cipherhorizon db migrate --db %s", e.Path, e.Have, e.Want, e.Path)
+}
+
+// SchemaVersion is the database schema this program reads and writes.
+func SchemaVersion() int { return len(migrations) }
+
+// backupHeadroom is the space a backup needs beyond the database's own size: VACUUM INTO writes a
+// compacted copy, never larger than the original, plus its journal while it works.
+const backupHeadroom = 16 << 20
+
+// upgradeResult is what migrate leaves for OpenWith to finish.
+type upgradeResult struct {
+	restoreFrom string    // a backup to put back because the upgrade failed
+	lock        *fileLock // taken for the upgrade alone; OpenWith releases it when done
+}
+
+func (s *Store) migrate(o OpenOptions) (res upgradeResult, err error) {
+	if _, err := s.db.Exec(`CREATE TABLE IF NOT EXISTS schema_migrations (version INTEGER PRIMARY KEY, applied_at TEXT NOT NULL)`); err != nil {
+		return res, err
+	}
+	have, err := schemaOf(s.db)
+	if err != nil {
+		return res, err
+	}
+	want := len(migrations)
+	if have > want {
+		return res, fmt.Errorf("store: database schema version %d is newer than this program understands (%d); run the newer version, or restore a backup made before the upgrade (cipherhorizon db restore)", have, want)
+	}
+	if have == want {
+		return res, nil
+	}
+	if have > 0 && o.Migrate == MigrateRefuse {
+		return res, &MigrationNeededError{Path: s.path, Have: have, Want: want}
+	}
+	if s.lock == nil && lockable(s.path) {
+		l, err := acquireLock(s.path)
+		if err != nil {
+			return res, fmt.Errorf("store: not upgrading the database from schema %d to %d: %w", have, want, err)
+		}
+		res.lock = l
+	}
+
+	var fkBefore int
+	if have > 0 {
+		// An existing database is about to change shape: keep a copy first (SR-10). If the copy
+		// cannot be made, nothing is changed.
+		if err := s.checkBackupSpace(); err != nil {
+			return res, fmt.Errorf("store: cannot back up %s before upgrading it from schema %d, so it was not changed: %w", s.path, have, err)
+		}
+		dst, err := s.backup(have)
+		if err != nil {
+			return res, fmt.Errorf("store: cannot back up %s before migrating from version %d, so it was not changed: %w", s.path, have, err)
+		}
+		// Violations already in the file are not this upgrade's doing and must not block it; new ones are.
+		if fkBefore, err = countFKViolations(s.db); err != nil {
+			return res, err
+		}
+		res.restoreFrom = dst // until the upgrade has succeeded
+	}
+
+	for v := have + 1; v <= want; v++ {
+		if err := s.applyStep(v); err != nil {
+			return res, err
+		}
+	}
+
+	if have > 0 {
+		if err := s.verifyUpgrade(fkBefore); err != nil {
+			return res, fmt.Errorf("store: the upgrade from schema %d to %d failed its checks: %w", have, want, err)
+		}
+	}
+	backup := res.restoreFrom
+	res.restoreFrom = ""
+	s.checkFingerprint(have)
+	if _, err := s.db.Exec(`INSERT INTO upgrade_log (at, from_schema, to_schema, app_version, backup) VALUES (?, ?, ?, ?, ?)`,
+		ts(s.now()), have, want, version.Version, backup); err != nil {
+		s.notice("could not record the upgrade in upgrade_log", "err", err.Error())
+	}
+	if have > 0 {
+		s.notice("upgraded the database", "from_schema", have, "to_schema", want, "version", version.Version, "backup", backup)
+	}
+	return res, nil
+}
+
+// applyStep runs migration v and its Go step, if any, in one transaction.
+func (s *Store) applyStep(v int) error {
+	tx, err := s.db.Begin()
+	if err != nil {
+		return err
+	}
+	if _, err := tx.Exec(migrations[v-1]); err != nil {
+		_ = tx.Rollback()
+		return fmt.Errorf("store: migration %d: %w", v, err)
+	}
+	if post := postMigrations[v]; post != nil {
+		if err := post(tx, s.now()); err != nil {
+			_ = tx.Rollback()
+			return fmt.Errorf("store: migration %d: %w", v, err)
+		}
+	}
+	if _, err := tx.Exec(`INSERT INTO schema_migrations (version, applied_at) VALUES (?, ?)`, v, ts(s.now())); err != nil {
+		_ = tx.Rollback()
+		return err
+	}
+	return tx.Commit()
+}
+
+// verifyUpgrade runs after the last step: the file is consistent and the upgrade added no
+// foreign-key violations.
+func (s *Store) verifyUpgrade(fkBefore int) error {
+	msgs, err := integrity(s.db, "quick_check")
+	if err != nil {
+		return err
+	}
+	if len(msgs) > 0 {
+		return fmt.Errorf("SQLite reports the file inconsistent: %s", strings.Join(msgs, "; "))
+	}
+	after, err := countFKViolations(s.db)
+	if err != nil {
+		return err
+	}
+	if after > fkBefore {
+		return fmt.Errorf("%d rows now point at rows that do not exist (%d before)", after, fkBefore)
+	}
+	return nil
+}
+
+// checkFingerprint compares the schema with the one this program was built with. A difference after
+// an upgrade means the file did not come only from released migrations (an early pre-release build, or
+// a hand edit). It is reported, not refused: such a file has worked with every release so far, and
+// refusing would lock its owner out. cipherhorizon db check reports it too.
+func (s *Store) checkFingerprint(from int) {
+	sum, _, err := schemaFingerprint(s.db)
+	if err != nil {
+		s.notice("could not read the schema to check it", "err", err.Error())
+		return
+	}
+	if sum != schemaFingerprintWant {
+		s.notice("the database's structure differs from what this version expects; it still works, but run cipherhorizon db check and report the output",
+			"from_schema", from, "fingerprint", sum, "expected", schemaFingerprintWant)
+	}
+}
+
+// checkBackupSpace refuses when the backup would not fit next to the database.
+func (s *Store) checkBackupSpace() error {
+	need := int64(backupHeadroom)
+	for _, p := range []string{s.path, s.path + "-wal"} {
+		if fi, err := os.Stat(p); err == nil {
+			need += fi.Size()
+		}
+	}
+	free, err := osfile.FreeBytes(filepath.Dir(s.path))
+	if err != nil {
+		return nil //nolint:nilerr // unknown free space: try, and let VACUUM INTO fail if it must
+	}
+	if free < uint64(need) {
+		return fmt.Errorf("the backup needs about %s free next to it and only %s is left; free some space and start again", humanBytes(uint64(need)), humanBytes(free))
+	}
+	return nil
+}
+
+func humanBytes(n uint64) string {
+	const mib = 1 << 20
+	if n < 10*mib {
+		return fmt.Sprintf("%.1f MiB", float64(n)/mib)
+	}
+	return fmt.Sprintf("%d MiB", n/mib)
+}
+
+// ---- reading a database without changing it ------------------------------------------------------
+
+type queryer interface {
+	Query(query string, args ...any) (*sql.Rows, error)
+	QueryRow(query string, args ...any) *sql.Row
+}
+
+// schemaOf reads the schema version (0 for a database with no migrations table).
+func schemaOf(q queryer) (int, error) {
+	var have int
+	err := q.QueryRow(`SELECT COALESCE(MAX(version), 0) FROM schema_migrations`).Scan(&have)
+	if err != nil && strings.Contains(err.Error(), "no such table") {
+		return 0, nil
+	}
+	return have, err
+}
+
+// integrity runs PRAGMA quick_check or integrity_check and returns its complaints (none when "ok").
+func integrity(q queryer, pragma string) ([]string, error) {
+	rows, err := q.Query(`PRAGMA ` + pragma + `(20)`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close() //nolint:errcheck // read-only
+	var out []string
+	for rows.Next() {
+		var m string
+		if err := rows.Scan(&m); err != nil {
+			return nil, err
+		}
+		if m != "ok" {
+			out = append(out, m)
+		}
+	}
+	return out, rows.Err()
+}
+
+func countFKViolations(q queryer) (int, error) {
+	rows, err := q.Query(`PRAGMA foreign_key_check`)
+	if err != nil {
+		return 0, err
+	}
+	defer rows.Close() //nolint:errcheck // read-only
+	n := 0
+	for rows.Next() {
+		n++
+	}
+	return n, rows.Err()
+}
+
+// schemaFingerprint describes the schema structurally — every table's columns, keys and indexes,
+// every trigger and view — one line each, and hashes the lines. Two databases with the same
+// fingerprint have the same shape however they got there.
+func schemaFingerprint(q queryer) (string, []string, error) {
+	var lines []string
+	objs, err := collect(q, `SELECT type, name, tbl_name, COALESCE(sql, '') FROM sqlite_master
+		WHERE name NOT LIKE 'sqlite\_%' ESCAPE '\' ORDER BY type, name`, 4)
+	if err != nil {
+		return "", nil, err
+	}
+	for _, o := range objs {
+		typ, name, tbl, text := o[0], o[1], o[2], strings.Join(strings.Fields(o[3]), " ")
+		switch typ {
+		case "table":
+			lines = append(lines, "table "+name)
+			cols, err := collect(q, `SELECT name, type, "notnull", COALESCE(dflt_value, 'NULL'), pk, hidden FROM pragma_table_xinfo(?) ORDER BY cid`, 6, name)
+			if err != nil {
+				return "", nil, err
+			}
+			for _, c := range cols {
+				lines = append(lines, "  column "+strings.Join(c, " "))
+			}
+			fks, err := collect(q, `SELECT "table", "from", COALESCE("to", ''), on_update, on_delete FROM pragma_foreign_key_list(?) ORDER BY id, seq`, 5, name)
+			if err != nil {
+				return "", nil, err
+			}
+			for _, f := range fks {
+				lines = append(lines, "  foreign-key "+strings.Join(f, " "))
+			}
+			idx, err := collect(q, `SELECT name, "unique", origin, partial FROM pragma_index_list(?) ORDER BY name`, 4, name)
+			if err != nil {
+				return "", nil, err
+			}
+			for _, ix := range idx {
+				cs, err := collect(q, `SELECT COALESCE(name, '<expr>'), "desc", COALESCE(coll, '') FROM pragma_index_xinfo(?) WHERE key = 1 ORDER BY seqno`, 3, ix[0])
+				if err != nil {
+					return "", nil, err
+				}
+				parts := make([]string, 0, len(cs))
+				for _, c := range cs {
+					parts = append(parts, strings.Join(c, ":"))
+				}
+				lines = append(lines, "  index "+strings.Join(ix, " ")+" ("+strings.Join(parts, ", ")+")")
+			}
+		case "index":
+			// Columns are covered under the table; a partial index's condition and an expression
+			// index's expression are only in its SQL.
+			if text != "" && (strings.Contains(strings.ToUpper(text), " WHERE ") || strings.Contains(text, "(") && strings.Count(text, "(") > 1) {
+				lines = append(lines, "index-sql "+name+" on "+tbl+": "+text)
+			}
+		default: // trigger, view
+			lines = append(lines, typ+" "+name+" on "+tbl+": "+text)
+		}
+	}
+	h := sha256.Sum256([]byte(strings.Join(lines, "\n")))
+	return fmt.Sprintf("%x", h), lines, nil
+}
+
+// collect runs a query whose columns are all read as text.
+func collect(q queryer, query string, n int, args ...any) ([][]string, error) {
+	rows, err := q.Query(query, args...)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close() //nolint:errcheck // read-only
+	var out [][]string
+	for rows.Next() {
+		vals := make([]sql.NullString, n)
+		ptrs := make([]any, n)
+		for i := range vals {
+			ptrs[i] = &vals[i]
+		}
+		if err := rows.Scan(ptrs...); err != nil {
+			return nil, err
+		}
+		row := make([]string, n)
+		for i, v := range vals {
+			row[i] = v.String
+		}
+		out = append(out, row)
+	}
+	return out, rows.Err()
+}
+
+// openReadOnly opens a database file for reading only: nothing is created, migrated or locked.
+func openReadOnly(path string) (*sql.DB, error) {
+	if _, err := os.Stat(path); err != nil {
+		return nil, err
+	}
+	esc := strings.NewReplacer("%", "%25", "?", "%3f", "#", "%23").Replace(path)
+	db, err := sql.Open("sqlite", "file:"+esc+"?mode=ro&_pragma=busy_timeout(5000)")
+	if err != nil {
+		return nil, err
+	}
+	db.SetMaxOpenConns(1)
+	if err := db.Ping(); err != nil {
+		_ = db.Close()
+		return nil, err
+	}
+	return db, nil
+}
+
+// ---- status, check, restore -----------------------------------------------------------------------
+
+// BackupFile is a pre-migration backup next to the database.
+type BackupFile struct {
+	Path     string    `json:"path"`
+	Schema   int       `json:"schema"` // the schema it holds, from its name
+	Size     int64     `json:"size"`
+	Modified time.Time `json:"modified"`
+}
+
+// UpgradeRecord is one row of upgrade_log.
+type UpgradeRecord struct {
+	At         time.Time `json:"at"`
+	FromSchema int       `json:"fromSchema"`
+	ToSchema   int       `json:"toSchema"`
+	AppVersion string    `json:"appVersion"`
+	Backup     string    `json:"backup,omitempty"`
+}
+
+// Status describes a database without changing it.
+type Status struct {
+	Path          string          `json:"path"`
+	Exists        bool            `json:"exists"`
+	Size          int64           `json:"size"`
+	Schema        int             `json:"schema"`
+	ProgramSchema int             `json:"programSchema"`
+	Pending       []int           `json:"pending,omitempty"` // migrations this program would run
+	Newer         bool            `json:"newer"`             // made by a newer version: this one refuses it
+	StructureOK   *bool           `json:"structureOk,omitempty"`
+	Backups       []BackupFile    `json:"backups"`
+	Upgrades      []UpgradeRecord `json:"upgrades"`
+	InUse         bool            `json:"inUse"`
+	InUseBy       string          `json:"inUseBy,omitempty"`
+}
+
+// Inspect reports a database's state: its schema, what an upgrade would do, its backups and
+// upgrade history, and whether a process is using it. It changes nothing and creates nothing.
+func Inspect(path string) (Status, error) {
+	st := Status{Path: path, ProgramSchema: len(migrations), Backups: []BackupFile{}, Upgrades: []UpgradeRecord{}}
+	fi, err := os.Stat(path)
+	if errors.Is(err, os.ErrNotExist) {
+		return st, nil
+	}
+	if err != nil {
+		return st, err
+	}
+	st.Exists, st.Size = true, fi.Size()
+	if st.InUse, st.InUseBy, err = LockHolder(path); err != nil {
+		return st, err
+	}
+	st.Backups = listBackups(path)
+	db, err := openReadOnly(path)
+	if err != nil {
+		return st, err
+	}
+	defer db.Close() //nolint:errcheck // read-only
+	if st.Schema, err = schemaOf(db); err != nil {
+		return st, fmt.Errorf("%s does not look like a CipherHorizon database: %w", path, err)
+	}
+	st.Newer = st.Schema > st.ProgramSchema
+	for v := st.Schema + 1; v <= st.ProgramSchema; v++ {
+		st.Pending = append(st.Pending, v)
+	}
+	if st.Schema == st.ProgramSchema {
+		sum, _, err := schemaFingerprint(db)
+		if err != nil {
+			return st, err
+		}
+		ok := sum == schemaFingerprintWant
+		st.StructureOK = &ok
+	}
+	rows, err := db.Query(`SELECT at, from_schema, to_schema, app_version, backup FROM upgrade_log ORDER BY id DESC LIMIT 10`)
+	if err == nil {
+		defer rows.Close() //nolint:errcheck // read-only
+		for rows.Next() {
+			var r UpgradeRecord
+			var at string
+			if err := rows.Scan(&at, &r.FromSchema, &r.ToSchema, &r.AppVersion, &r.Backup); err != nil {
+				return st, err
+			}
+			if t := parseTS(sql.NullString{String: at, Valid: true}); t != nil {
+				r.At = *t
+			}
+			st.Upgrades = append(st.Upgrades, r)
+		}
+	}
+	return st, nil
+}
+
+// listBackups finds the pre-migration backups next to a database, newest first.
+func listBackups(path string) []BackupFile {
+	names, _ := filepath.Glob(path + ".bak-v*")
+	out := []BackupFile{}
+	for _, n := range names {
+		fi, err := os.Stat(n)
+		if err != nil || !fi.Mode().IsRegular() {
+			continue
+		}
+		b := BackupFile{Path: n, Size: fi.Size(), Modified: fi.ModTime()}
+		rest := strings.TrimPrefix(n, path+".bak-v")
+		if i := strings.IndexByte(rest, '-'); i > 0 {
+			b.Schema, _ = strconv.Atoi(rest[:i])
+		}
+		out = append(out, b)
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Modified.After(out[j].Modified) })
+	return out
+}
+
+// CheckResult is what Check found.
+type CheckResult struct {
+	Schema        int      `json:"schema"`
+	ProgramSchema int      `json:"programSchema"`
+	Integrity     []string `json:"integrity"`             // SQLite's complaints; empty is good
+	FKViolations  int      `json:"foreignKeyViolations"`  // rows pointing at rows that do not exist
+	StructureOK   *bool    `json:"structureOk,omitempty"` // only judged when the schema is this program's
+	Fingerprint   string   `json:"fingerprint,omitempty"`
+	Differences   []string `json:"differences,omitempty"` // structure lines that differ from this program's
+}
+
+// OK reports whether the check found nothing wrong.
+func (c CheckResult) OK() bool {
+	return len(c.Integrity) == 0 && c.FKViolations == 0 && (c.StructureOK == nil || *c.StructureOK) && c.Schema <= c.ProgramSchema
+}
+
+// Check examines a database thoroughly without changing it: SQLite's full integrity check, foreign
+// keys, and, when it is at this program's schema, its structure against this program's.
+func Check(path string) (CheckResult, error) {
+	res := CheckResult{ProgramSchema: len(migrations), Integrity: []string{}}
+	db, err := openReadOnly(path)
+	if err != nil {
+		return res, err
+	}
+	defer db.Close() //nolint:errcheck // read-only
+	if res.Schema, err = schemaOf(db); err != nil {
+		return res, err
+	}
+	if res.Integrity, err = integrity(db, "integrity_check"); err != nil {
+		return res, err
+	}
+	if res.FKViolations, err = countFKViolations(db); err != nil {
+		return res, err
+	}
+	if res.Schema == res.ProgramSchema {
+		sum, lines, err := schemaFingerprint(db)
+		if err != nil {
+			return res, err
+		}
+		ok := sum == schemaFingerprintWant
+		res.StructureOK, res.Fingerprint = &ok, sum
+		if !ok {
+			res.Differences = diffLines(lines, freshSchemaLines())
+		}
+	}
+	return res, nil
+}
+
+// freshSchemaLines builds this program's schema in memory and describes it.
+func freshSchemaLines() []string {
+	s, err := Open("file:fresh-schema?mode=memory")
+	if err != nil {
+		return nil
+	}
+	defer s.Close() //nolint:errcheck // in memory
+	_, lines, _ := schemaFingerprint(s.db)
+	return lines
+}
+
+// diffLines lists lines only in have ("+") or only in want ("-").
+func diffLines(have, want []string) []string {
+	in := func(xs []string) map[string]bool {
+		m := make(map[string]bool, len(xs))
+		for _, x := range xs {
+			m[x] = true
+		}
+		return m
+	}
+	h, w := in(have), in(want)
+	var out []string
+	for _, x := range have {
+		if !w[x] {
+			out = append(out, "+ "+strings.TrimSpace(x))
+		}
+	}
+	for _, x := range want {
+		if !h[x] {
+			out = append(out, "- "+strings.TrimSpace(x))
+		}
+	}
+	return out
+}
+
+// RestoreResult says what Restore did.
+type RestoreResult struct {
+	Schema   int    // the schema the restored file holds; the next start upgrades it if older
+	MovedTo  string // where the database it replaced was moved ("" if there was none)
+	Restored string
+}
+
+// Restore puts a backup in place of the database at path. It refuses while any CipherHorizon
+// process uses the database, refuses a file that is not a sound CipherHorizon database or that
+// is newer than this program, and never deletes anything: the database it replaces is moved aside
+// (with its -wal and -shm, so that copy stays complete).
+func Restore(path, backup string) (RestoreResult, error) {
+	var res RestoreResult
+	if !lockable(path) {
+		return res, fmt.Errorf("cannot restore into %q: name a database file", path)
+	}
+	if abs1, err1 := filepath.Abs(path); err1 == nil {
+		if abs2, err2 := filepath.Abs(backup); err2 == nil && abs1 == abs2 {
+			return res, errors.New("the backup and the database are the same file")
+		}
+	}
+	db, err := openReadOnly(backup)
+	if err != nil {
+		return res, fmt.Errorf("reading the backup: %w", err)
+	}
+	msgs, ierr := integrity(db, "quick_check")
+	v, verr := schemaOf(db)
+	_ = db.Close()
+	switch {
+	case ierr != nil:
+		return res, fmt.Errorf("the backup cannot be read as a database: %w", ierr)
+	case len(msgs) > 0:
+		return res, fmt.Errorf("the backup is damaged (%s); it was not restored", strings.Join(msgs, "; "))
+	case verr != nil || v == 0:
+		return res, errors.New("the file is not a CipherHorizon database (it has no schema version)")
+	case v > len(migrations):
+		return res, fmt.Errorf("the backup is at schema %d, newer than this program understands (%d); restore it with the version that made it", v, len(migrations))
+	}
+	l, err := acquireLock(path)
+	if err != nil {
+		return res, err
+	}
+	defer l.release()
+	moved, err := replaceWith(path, backup, "replaced")
+	if err != nil {
+		return res, err
+	}
+	return RestoreResult{Schema: v, MovedTo: moved, Restored: path}, nil
+}
+
+// replaceWith copies src over path. A database already at path is first renamed to
+// "<path>.<why>-<time>" together with its -wal and -shm files; that name is returned.
+func replaceWith(path, src, why string) (string, error) {
+	moved := ""
+	if _, err := os.Stat(path); err == nil {
+		moved = fmt.Sprintf("%s.%s-%s", path, why, time.Now().UTC().Format("20060102T150405Z"))
+		for n := 2; ; n++ {
+			if _, err := os.Stat(moved); err != nil {
+				break
+			}
+			moved = fmt.Sprintf("%s.%s-%s-%d", path, why, time.Now().UTC().Format("20060102T150405Z"), n)
+		}
+		if err := os.Rename(path, moved); err != nil {
+			return "", fmt.Errorf("moving the current database aside: %w", err)
+		}
+		for _, sfx := range []string{"-wal", "-shm"} {
+			if _, err := os.Stat(path + sfx); err == nil {
+				if err := os.Rename(path+sfx, moved+sfx); err != nil {
+					return moved, fmt.Errorf("moving %s aside: %w", path+sfx, err)
+				}
+			}
+		}
+	}
+	tmp := path + ".restoring"
+	if err := copyFile(src, tmp); err != nil {
+		_ = os.Remove(tmp)
+		return moved, err
+	}
+	if err := os.Rename(tmp, path); err != nil {
+		_ = os.Remove(tmp)
+		return moved, err
+	}
+	return moved, restrictFile(path)
+}
+
+// copyFile copies src to dst (created owner-only) and syncs it to disk.
+func copyFile(src, dst string) error {
+	in, err := os.Open(src)
+	if err != nil {
+		return err
+	}
+	defer in.Close() //nolint:errcheck // read-only
+	out, err := os.OpenFile(dst, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0o600)
+	if err != nil {
+		return err
+	}
+	if _, err := io.Copy(out, in); err != nil {
+		_ = out.Close()
+		return err
+	}
+	if err := out.Sync(); err != nil {
+		_ = out.Close()
+		return err
+	}
+	return out.Close()
+}
+
+// keepFailedUpgrades is how many copies of a database whose upgrade failed are kept for diagnosis.
+// A service that restarts after each failure would otherwise leave one per attempt.
+const keepFailedUpgrades = 1
+
+// restoreAfterFailedUpgrade puts the pre-upgrade backup back after an upgrade failed. The failed file
+// is kept (owner-only) as "<db>.failed-upgrade-<time>" for diagnosis; older ones are deleted.
+func restoreAfterFailedUpgrade(path, backup string) (string, error) {
+	moved, err := replaceWith(path, backup, "failed-upgrade")
+	if err != nil {
+		return moved, err
+	}
+	names, _ := filepath.Glob(path + ".failed-upgrade-*")
+	var dbs []string
+	for _, n := range names {
+		if !strings.HasSuffix(n, "-wal") && !strings.HasSuffix(n, "-shm") {
+			dbs = append(dbs, n)
+		}
+	}
+	sort.Sort(sort.Reverse(sort.StringSlice(dbs))) // the name holds the time: newest first
+	for _, n := range dbs[min(keepFailedUpgrades, len(dbs)):] {
+		_ = os.Remove(n)
+		_ = os.Remove(n + "-wal")
+		_ = os.Remove(n + "-shm")
+	}
+	return moved, nil
+}
diff --git a/internal/store/upgrade_matrix_test.go b/internal/store/upgrade_matrix_test.go
new file mode 100644
index 0000000..394d63d
--- /dev/null
+++ b/internal/store/upgrade_matrix_test.go
@@ -0,0 +1,274 @@
+package store_test
+
+import (
+	"bufio"
+	"crypto/sha256"
+	"database/sql"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+	"testing"
+
+	"github.com/offsetsecurity/cipherhorizon/internal/store"
+)
+
+// The upgrade promise (PRD-016 §4): any released version upgrades straight to this one. Each file in
+// testdata/upgrade was written by a released binary (testing/upgrade/make-fixture.sh), so this is the
+// data real installs of that version hold, not a reconstruction.
+
+const fixtureDir = "testdata/upgrade"
+
+var fixtureName = regexp.MustCompile(`^v\d+\.\d+\.\d+\.db$`)
+
+func fixtures(t *testing.T) []string {
+	t.Helper()
+	names, err := filepath.Glob(filepath.Join(fixtureDir, "*.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	sort.Strings(names)
+	for _, n := range names {
+		if !fixtureName.MatchString(filepath.Base(n)) {
+			t.Errorf("%s: fixtures are named after the release that wrote them (vX.Y.Z.db)", n)
+		}
+	}
+	return names
+}
+
+// Every release that shipped a migration has a fixture: those are the files whose upgrade differs.
+func TestEveryReleaseWithAMigrationHasAFixture(t *testing.T) {
+	have := map[string]bool{}
+	for _, f := range fixtures(t) {
+		have[strings.TrimSuffix(filepath.Base(f), ".db")] = true
+	}
+	lock, err := os.Open("migrations.lock")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer lock.Close() //nolint:errcheck // read-only
+	sc := bufio.NewScanner(lock)
+	for sc.Scan() {
+		fs := strings.Fields(sc.Text())
+		if len(fs) == 3 && !strings.HasPrefix(fs[0], "#") && !have[fs[2]] {
+			t.Errorf("no fixture for %s, which shipped migration %s: run testing/upgrade/make-fixture.sh %s", fs[2], fs[0], fs[2])
+		}
+	}
+}
+
+func TestUpgradeFromEveryRelease(t *testing.T) {
+	for _, fx := range fixtures(t) {
+		t.Run(filepath.Base(fx), func(t *testing.T) {
+			path := filepath.Join(t.TempDir(), "cipherhorizon.db")
+			copyFixture(t, fx, path)
+			before := snapshot(t, path)
+			if before.schema == 0 || before.counts["assets"] == 0 || before.counts["scans"] == 0 {
+				t.Fatalf("fixture holds too little to test: %+v", before.counts)
+			}
+
+			s, err := store.Open(path)
+			if err != nil {
+				t.Fatalf("upgrade from %s: %v", filepath.Base(fx), err)
+			}
+			// What the product reads still reads.
+			as, err := s.ListAssets("")
+			if err != nil || len(as) != before.counts["assets"] {
+				t.Errorf("ListAssets after the upgrade: %d, %v; want %d", len(as), err, before.counts["assets"])
+			}
+			us, err := s.ListUsers()
+			if err != nil || len(us) != before.counts["users"] {
+				t.Errorf("ListUsers after the upgrade: %d, %v; want %d", len(us), err, before.counts["users"])
+			}
+			_ = s.Close()
+
+			after := snapshot(t, path)
+			if after.schema != store.SchemaVersion() {
+				t.Fatalf("schema after the upgrade = %d, want %d", after.schema, store.SchemaVersion())
+			}
+			// Nothing is lost: every table keeps its rows. The estate graph (sources, entities,
+			// observations) is a projection rebuilt from the documents, so only its presence is compared.
+			for table, n := range before.counts {
+				if projection[table] {
+					if n > 0 && after.counts[table] == 0 {
+						t.Errorf("%s: emptied by the upgrade (%d rows before)", table, n)
+					}
+					continue
+				}
+				if table == "schema_migrations" {
+					continue
+				}
+				if after.counts[table] != n {
+					t.Errorf("%s: %d rows before the upgrade, %d after", table, n, after.counts[table])
+				}
+			}
+			// Evidence is never rewritten (PRD-016 §5.2), and neither are accounts or decisions.
+			for what, sum := range before.content {
+				if after.content[what] != sum {
+					t.Errorf("%s changed in the upgrade", what)
+				}
+			}
+
+			// The upgraded file is sound and has exactly the structure a fresh install has.
+			res, err := store.Check(path)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if !res.OK() {
+				t.Errorf("check after the upgrade: %+v", res)
+			}
+			st, err := store.Inspect(path)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if before.schema < store.SchemaVersion() {
+				if len(st.Upgrades) == 0 || st.Upgrades[0].FromSchema != before.schema || st.Upgrades[0].Backup == "" {
+					t.Errorf("the upgrade is not recorded with its backup: %+v", st.Upgrades)
+				} else if _, err := os.Stat(st.Upgrades[0].Backup); err != nil {
+					t.Errorf("the recorded backup is missing: %v", err)
+				}
+			}
+
+			// Opening again changes nothing: no second backup, no second record.
+			s, err = store.Open(path)
+			if err != nil {
+				t.Fatal(err)
+			}
+			_ = s.Close()
+			st2, _ := store.Inspect(path)
+			if len(st2.Upgrades) != len(st.Upgrades) || len(st2.Backups) != len(st.Backups) {
+				t.Errorf("a second open upgraded again: %d -> %d records, %d -> %d backups", len(st.Upgrades), len(st2.Upgrades), len(st.Backups), len(st2.Backups))
+			}
+		})
+	}
+}
+
+// A database from a newer version is refused, and left exactly as it was.
+func TestNewerDatabaseIsRefusedUnchanged(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "cipherhorizon.db")
+	s, err := store.Open(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	_ = s.Close()
+	if err := store.ForceSchemaVersion(path, store.SchemaVersion()+1); err != nil {
+		t.Fatal(err)
+	}
+	before := fileSum(t, path)
+	_, err = store.Open(path)
+	if err == nil || !strings.Contains(err.Error(), "newer than this program") {
+		t.Fatalf("Open(newer) = %v", err)
+	}
+	if fileSum(t, path) != before {
+		t.Error("the newer database was changed")
+	}
+	if bs, _ := filepath.Glob(path + ".bak-v*"); len(bs) != 0 {
+		t.Errorf("backups made of a database that was refused: %v", bs)
+	}
+}
+
+// ---- helpers -------------------------------------------------------------------------------------
+
+var projection = map[string]bool{"sources": true, "entities": true, "observations": true, "projection_state": true}
+
+type dbSnapshot struct {
+	schema  int
+	counts  map[string]int
+	content map[string]string // what must survive an upgrade unchanged -> hash
+}
+
+func snapshot(t *testing.T, path string) dbSnapshot {
+	t.Helper()
+	db, err := sql.Open("sqlite", "file:"+path+"?mode=ro")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer db.Close() //nolint:errcheck // test
+	snap := dbSnapshot{counts: map[string]int{}, content: map[string]string{}}
+	_ = db.QueryRow(`SELECT COALESCE(MAX(version), 0) FROM schema_migrations`).Scan(&snap.schema)
+	rows, err := db.Query(`SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite\_%' ESCAPE '\'`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var tables []string
+	for rows.Next() {
+		var n string
+		_ = rows.Scan(&n)
+		tables = append(tables, n)
+	}
+	_ = rows.Close()
+	for _, tb := range tables {
+		var n int
+		if err := db.QueryRow(`SELECT COUNT(*) FROM "` + tb + `"`).Scan(&n); err != nil {
+			t.Fatal(err)
+		}
+		snap.counts[tb] = n
+	}
+	for what, q := range map[string]string{
+		"scan evidence (report_json)": `SELECT id, report_json FROM scans ORDER BY id`,
+		"scan results (eval_json)":    `SELECT id, eval_json FROM scans ORDER BY id`,
+		"assets":                      `SELECT id, kind, name, host, port, tags, notes FROM assets ORDER BY id`,
+		"accounts":                    `SELECT id, username, role, password_hash, disabled FROM users ORDER BY id`,
+		"triage decisions":            `SELECT asset_id, finding_key, status, note FROM finding_status ORDER BY asset_id, finding_key`,
+		"host inventories":            `SELECT id, asset_id, cbom_json FROM host_snapshots ORDER BY id`,
+	} {
+		snap.content[what] = hashQuery(t, db, q)
+	}
+	return snap
+}
+
+func hashQuery(t *testing.T, db *sql.DB, q string) string {
+	t.Helper()
+	rows, err := db.Query(q)
+	if err != nil {
+		t.Fatalf("%s: %v", q, err)
+	}
+	defer rows.Close() //nolint:errcheck // test
+	cols, _ := rows.Columns()
+	h := sha256.New()
+	for rows.Next() {
+		vals := make([]any, len(cols))
+		ptrs := make([]any, len(cols))
+		for i := range vals {
+			ptrs[i] = &vals[i]
+		}
+		if err := rows.Scan(ptrs...); err != nil {
+			t.Fatal(err)
+		}
+		for _, v := range vals {
+			_, _ = fmt.Fprintf(h, "%v\x00", v)
+		}
+		_, _ = h.Write([]byte{'\n'})
+	}
+	return fmt.Sprintf("%x", h.Sum(nil))
+}
+
+func copyFixture(t *testing.T, src, dst string) {
+	t.Helper()
+	in, err := os.Open(src)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer in.Close() //nolint:errcheck // read-only
+	out, err := os.OpenFile(dst, os.O_CREATE|os.O_WRONLY|os.O_EXCL, 0o600)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := io.Copy(out, in); err != nil {
+		t.Fatal(err)
+	}
+	if err := out.Close(); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func fileSum(t *testing.T, path string) string {
+	t.Helper()
+	b, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return fmt.Sprintf("%x", sha256.Sum256(b))
+}
diff --git a/internal/store/upgrade_test.go b/internal/store/upgrade_test.go
new file mode 100644
index 0000000..1ec033b
--- /dev/null
+++ b/internal/store/upgrade_test.go
@@ -0,0 +1,304 @@
+package store_test
+
+import (
+	"database/sql"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/offsetsecurity/cipherhorizon/internal/store"
+)
+
+// One server per database: a second exclusive open is refused with who holds it, and an upgrade
+// by another version waits for the server to stop rather than changing the file under it.
+func TestExclusiveOpenLocksTheDatabase(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "ch.db")
+	s, err := store.OpenWith(path, store.OpenOptions{Exclusive: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	_, err = store.OpenWith(path, store.OpenOptions{Exclusive: true})
+	var le *store.LockedError
+	if !errors.As(err, &le) || !errors.Is(err, store.ErrLocked) {
+		t.Fatalf("second exclusive open = %v, want a LockedError", err)
+	}
+	if !strings.Contains(le.Holder, "pid ") {
+		t.Errorf("holder %q does not say who holds it", le.Holder)
+	}
+	if held, _, err := store.LockHolder(path); err != nil || !held {
+		t.Errorf("LockHolder = %v, %v; want held", held, err)
+	}
+	// A plain open of an up-to-date database needs no lock (db backup while the server runs).
+	plain, err := store.Open(path)
+	if err != nil {
+		t.Fatalf("plain open while a server holds the lock: %v", err)
+	}
+	_ = plain.Close()
+	if err := s.Close(); err != nil {
+		t.Fatal(err)
+	}
+	again, err := store.OpenWith(path, store.OpenOptions{Exclusive: true})
+	if err != nil {
+		t.Fatalf("after the first closed: %v", err)
+	}
+	_ = again.Close()
+}
+
+func TestUpgradeWaitsForTheServer(t *testing.T) {
+	path, _ := legacy(t)
+	// A server of the old version holds the lock: the upgrade must not start.
+	release, err := store.HoldLockForTest(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer release()
+	if _, err := store.Open(path); !errors.Is(err, store.ErrLocked) {
+		t.Fatalf("upgrade while locked = %v, want ErrLocked", err)
+	}
+	if v := schemaOn(t, path); v != 3 {
+		t.Errorf("schema after a refused upgrade = %d, want 3 (unchanged)", v)
+	}
+	if bs, _ := filepath.Glob(path + ".bak-v*"); len(bs) != 0 {
+		t.Errorf("a refused upgrade made backups: %v", bs)
+	}
+}
+
+func TestRefuseModeLeavesAnOldDatabaseAlone(t *testing.T) {
+	path, _ := legacy(t)
+	_, err := store.OpenWith(path, store.OpenOptions{Migrate: store.MigrateRefuse})
+	var me *store.MigrationNeededError
+	if !errors.As(err, &me) || me.Have != 3 || me.Want != store.SchemaVersion() {
+		t.Fatalf("OpenWith(refuse) = %v, want MigrationNeededError 3 -> %d", err, store.SchemaVersion())
+	}
+	if !strings.Contains(err.Error(), "cipherhorizon db migrate") {
+		t.Errorf("the error does not say how to upgrade: %v", err)
+	}
+	if v := schemaOn(t, path); v != 3 {
+		t.Errorf("schema = %d, want 3", v)
+	}
+	// A new database is created whatever the mode: there is nothing to protect.
+	s, err := store.OpenWith(filepath.Join(t.TempDir(), "new.db"), store.OpenOptions{Migrate: store.MigrateRefuse})
+	if err != nil {
+		t.Fatalf("new database under refuse: %v", err)
+	}
+	_ = s.Close()
+}
+
+// A step that fails part-way through a multi-step upgrade puts the file back as it was before the
+// upgrade began, not at the last step that worked; the failed copy is kept for diagnosis.
+func TestFailedUpgradeIsPutBack(t *testing.T) {
+	path, _ := legacy(t) // at schema 3, with data
+	before := schemaDumpOf(t, path)
+	restore := store.SetPostMigration(8, func(*sql.Tx, time.Time) error { return errors.New("injected failure at 8") })
+	defer restore()
+	_, err := store.Open(path)
+	if err == nil || !strings.Contains(err.Error(), "injected failure at 8") || !strings.Contains(err.Error(), "put back exactly as it was") {
+		t.Fatalf("Open = %v, want the failure and that the file was put back", err)
+	}
+	if v := schemaOn(t, path); v != 3 {
+		t.Fatalf("schema after the failed upgrade = %d, want 3 (as before), not a half-upgraded 7", v)
+	}
+	if after := schemaDumpOf(t, path); after != before {
+		t.Error("the restored file differs from the original")
+	}
+	failed, _ := filepath.Glob(path + ".failed-upgrade-*")
+	if len(failed) != 1 {
+		t.Errorf("failed copies kept: %v, want one", failed)
+	}
+	restore()
+	s, err := store.Open(path)
+	if err != nil {
+		t.Fatalf("retry after the fix: %v", err)
+	}
+	_ = s.Close()
+}
+
+func TestUpgradeIsRecorded(t *testing.T) {
+	path, _ := legacy(t)
+	s, err := store.Open(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	_ = s.Close()
+	st, err := store.Inspect(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if st.Schema != store.SchemaVersion() || len(st.Pending) != 0 || st.Newer || st.InUse {
+		t.Errorf("status = %+v", st)
+	}
+	if st.StructureOK == nil || !*st.StructureOK {
+		t.Error("an upgraded database does not match the structure this version builds")
+	}
+	if len(st.Upgrades) != 1 || st.Upgrades[0].FromSchema != 3 || st.Upgrades[0].ToSchema != store.SchemaVersion() || st.Upgrades[0].Backup == "" {
+		t.Fatalf("upgrade history = %+v", st.Upgrades)
+	}
+	if len(st.Backups) != 1 || st.Backups[0].Schema != 3 || st.Backups[0].Path != st.Upgrades[0].Backup {
+		t.Errorf("backups = %+v", st.Backups)
+	}
+}
+
+func TestInspectDoesNotChangeAnything(t *testing.T) {
+	path, _ := legacy(t)
+	st, err := store.Inspect(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if st.Schema != 3 || len(st.Pending) != store.SchemaVersion()-3 || st.Pending[0] != 4 || st.StructureOK != nil {
+		t.Errorf("status of an old database = %+v", st)
+	}
+	if v := schemaOn(t, path); v != 3 {
+		t.Errorf("Inspect changed the schema to %d", v)
+	}
+	missing := filepath.Join(t.TempDir(), "nothing.db")
+	if st, err := store.Inspect(missing); err != nil || st.Exists {
+		t.Errorf("Inspect(missing) = %+v, %v", st, err)
+	}
+	if _, err := os.Stat(missing); err == nil {
+		t.Error("Inspect created a database")
+	}
+}
+
+func TestCheckFindsAHandEditedSchema(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "ch.db")
+	s, err := store.Open(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	_ = s.Close()
+	res, err := store.Check(path)
+	if err != nil || !res.OK() {
+		t.Fatalf("fresh database: %+v, %v", res, err)
+	}
+	db, _ := sql.Open("sqlite", "file:"+path)
+	if _, err := db.Exec(`CREATE INDEX hand_made ON assets(name)`); err != nil {
+		t.Fatal(err)
+	}
+	_ = db.Close()
+	res, err = store.Check(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.OK() || res.StructureOK == nil || *res.StructureOK {
+		t.Fatalf("hand-edited database passed: %+v", res)
+	}
+	if !strings.Contains(strings.Join(res.Differences, "\n"), "+   index hand_made") && !strings.Contains(strings.Join(res.Differences, "\n"), "hand_made") {
+		t.Errorf("differences do not name the extra index: %v", res.Differences)
+	}
+}
+
+func TestRestore(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "ch.db")
+	s, err := store.Open(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := s.CreateAsset(store.Asset{Kind: store.KindTLS, Name: "kept", Host: "kept.test", Port: 443}); err != nil {
+		t.Fatal(err)
+	}
+	bak := filepath.Join(dir, "backup.db")
+	if err := s.BackupTo(bak); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := s.CreateAsset(store.Asset{Kind: store.KindTLS, Name: "later", Host: "later.test", Port: 443}); err != nil {
+		t.Fatal(err)
+	}
+
+	// Refused while the database is in use.
+	_ = s.Close()
+	srv, err := store.OpenWith(path, store.OpenOptions{Exclusive: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := store.Restore(path, bak); !errors.Is(err, store.ErrLocked) {
+		t.Errorf("Restore while a server runs = %v, want ErrLocked", err)
+	}
+	_ = srv.Close()
+
+	// Refuses what is not a sound CipherHorizon database.
+	junk := filepath.Join(dir, "junk.db")
+	_ = os.WriteFile(junk, []byte("not a database"), 0o600)
+	if _, err := store.Restore(path, junk); err == nil {
+		t.Error("restored a file that is not a database")
+	}
+	empty := filepath.Join(dir, "empty.db")
+	edb, _ := sql.Open("sqlite", "file:"+empty)
+	_, _ = edb.Exec(`CREATE TABLE x (a)`)
+	_ = edb.Close()
+	if _, err := store.Restore(path, empty); err == nil || !strings.Contains(err.Error(), "not a CipherHorizon database") {
+		t.Errorf("Restore(non-CipherHorizon) = %v", err)
+	}
+	if _, err := store.Restore(path, path); err == nil {
+		t.Error("restored a database onto itself")
+	}
+
+	res, err := store.Restore(path, bak)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.Schema != store.SchemaVersion() || res.MovedTo == "" {
+		t.Errorf("result = %+v", res)
+	}
+	if _, err := os.Stat(res.MovedTo); err != nil {
+		t.Errorf("the replaced database was not kept: %v", err)
+	}
+	if _, err := os.Stat(bak); err != nil {
+		t.Errorf("the backup itself is gone: %v", err)
+	}
+	s, err = store.Open(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer s.Close() //nolint:errcheck // test
+	as, err := s.ListAssets("")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(as) != 1 || as[0].Name != "kept" {
+		t.Errorf("after restore: %d assets (%v), want only the one in the backup", len(as), as)
+	}
+}
+
+// ---- helpers -------------------------------------------------------------------------------------
+
+func schemaOn(t *testing.T, path string) int {
+	t.Helper()
+	db, err := sql.Open("sqlite", "file:"+path+"?mode=ro")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer db.Close() //nolint:errcheck // test
+	var v int
+	if err := db.QueryRow(`SELECT COALESCE(MAX(version), 0) FROM schema_migrations`).Scan(&v); err != nil {
+		t.Fatal(err)
+	}
+	return v
+}
+
+func schemaDumpOf(t *testing.T, path string) string {
+	t.Helper()
+	db, err := sql.Open("sqlite", "file:"+path+"?mode=ro")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer db.Close() //nolint:errcheck // test
+	rows, err := db.Query(`SELECT type || ' ' || name || ' ' || COALESCE(sql, '') FROM sqlite_master ORDER BY type, name`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer rows.Close() //nolint:errcheck // test
+	var b strings.Builder
+	for rows.Next() {
+		var s string
+		_ = rows.Scan(&s)
+		b.WriteString(s + "\n")
+	}
+	var n int
+	_ = db.QueryRow(`SELECT COUNT(*) FROM assets`).Scan(&n)
+	b.WriteString("assets " + string(rune('0'+n)))
+	return b.String()
+}
diff --git a/scripts/prepare-release.sh b/scripts/prepare-release.sh
index 11602c3..764b6e1 100755
--- a/scripts/prepare-release.sh
+++ b/scripts/prepare-release.sh
@@ -1,7 +1,8 @@
 #!/usr/bin/env bash
 # Cut the changelog for a release: turns "## [Unreleased]" into "## [X.Y.Z] - DATE", opens a fresh
-# Unreleased section and updates the compare links. It changes CHANGELOG.md only; you review the diff,
-# commit it on a release-prep branch, open a PR, and tag after it merges (docs/engineering/RELEASING.md).
+# Unreleased section and updates the compare links. It also locks the database migrations the release
+# ships (internal/store/migrations.lock). It changes those two files only; you review the diff, commit
+# it on a release-prep branch, open a PR, and tag after it merges (docs/engineering/RELEASING.md).
 #   scripts/prepare-release.sh 0.1.0
 set -euo pipefail
 
@@ -41,3 +42,15 @@ if [ -n "$url" ]; then
 fi
 mv "$tmp" "$f"
 echo "CHANGELOG.md: Unreleased is now $version ($date). Review it, then commit."
+
+# Database migrations this release ships become history: lock them, so no later change can edit what
+# installs of this version have already run (PRD-016 U-01).
+lock=internal/store/migrations.lock
+before="$(grep -c '^[0-9]' "$lock" || true)"
+go test ./internal/store -run '^TestMigrationsLock$' -count=1 -args -lock-release="$version" >/dev/null
+after="$(grep -c '^[0-9]' "$lock" || true)"
+if [ "$after" -gt "$before" ]; then
+  echo "$lock: locked migrations $((before + 1))-$after as shipped in v$version. Commit it with the changelog."
+else
+  echo "$lock: this release ships no new migration."
+fi
diff --git a/testing/upgrade/make-fixture.sh b/testing/upgrade/make-fixture.sh
new file mode 100755
index 0000000..8a519eb
--- /dev/null
+++ b/testing/upgrade/make-fixture.sh
@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# Makes the upgrade-test database for a released version (PRD-016 U-02): builds that release from its
+# tag, runs it against the demo targets, seeds it through its own API (seed.mjs), adds an account
+# with its own CLI, and writes a compact copy to internal/store/testdata/upgrade/<tag>.db.
+#
+#   testing/upgrade/make-fixture.sh v0.4.0
+#
+# The database is written by the release itself, so TestUpgradeFromEveryRelease upgrades what real
+# installs of that version hold. Run it once per release (RELEASING.md) and commit the file. Needs Go,
+# Node 22+ and git; the tag must exist locally.
+set -euo pipefail
+
+tag="${1:-}"
+[[ "$tag" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] || { echo "usage: $0 vX.Y.Z" >&2; exit 2; }
+root="$(cd "$(dirname "$0")/../.." && pwd)"
+out="$root/internal/store/testdata/upgrade/$tag.db"
+[ -e "$out" ] && { echo "$out already exists; a fixture is made once, from the release" >&2; exit 1; }
+git -C "$root" rev-parse -q --verify "refs/tags/$tag" >/dev/null || { echo "no tag $tag (git fetch --tags)" >&2; exit 1; }
+
+work="$(mktemp -d)"
+src="$work/src"
+pids=()
+cleanup() {
+  for p in "${pids[@]}"; do kill "$p" 2>/dev/null || true; done
+  wait 2>/dev/null || true
+  git -C "$root" worktree remove --force "$src" 2>/dev/null || true
+  rm -rf "$work"
+}
+trap cleanup EXIT
+
+exe=""
+case "$(uname -s)" in MINGW*|MSYS*|CYGWIN*) exe=".exe" ;; esac
+
+git -C "$root" worktree add -q --detach "$src" "$tag"
+module="$(cd "$src" && go list -m)"
+version="${tag#v}"
+(
+  cd "$src"
+  CGO_ENABLED=0 go build -trimpath -ldflags "-X $module/internal/version.Version=$version" -o "$work/cipherhorizon$exe" ./cmd/cipherhorizon
+  go build -o "$work/demo-targets$exe" ./cmd/demo-targets
+)
+
+# Ports away from the defaults, so a server or demo already running on this machine is not disturbed.
+demo_base=19440
+port=18090
+token="fixture-token-$(date +%s)-0123456789abcdef"
+db="$work/fixture.db"
+
+"$work/demo-targets$exe" -base-port "$demo_base" > "$work/demo.log" 2>&1 &
+pids+=($!)
+"$work/cipherhorizon$exe" serve --allow-loopback --token "$token" --db "$db" --addr "127.0.0.1:$port" > "$work/serve.log" 2>&1 &
+serve_pid=$!
+pids+=($serve_pid)
+for _ in $(seq 1 100); do
+  curl -sf "http://127.0.0.1:$port/api/v1/health" >/dev/null && break
+  sleep 0.2
+done
+curl -sf "http://127.0.0.1:$port/api/v1/health" >/dev/null || { cat "$work/serve.log" >&2; exit 1; }
+
+node "$root/testing/upgrade/seed.mjs" --base "http://127.0.0.1:$port" --token "$token" --demo-base "$demo_base"
+
+# A host inventory, uploaded as the collector would: the release's own sample (testing/golden), to this
+# local server only.
+curl -sf -o /dev/null -X POST "http://127.0.0.1:$port/api/v1/hosts/ingest" \
+  -H "Authorization: Bearer $token" -H "X-Requested-With: cipherhorizon" -H "Content-Type: application/json" \
+  --data-binary "@$src/testing/golden/debian-13.cbom.json" || { echo "uploading the host inventory failed" >&2; exit 1; }
+
+kill "$serve_pid"
+wait "$serve_pid" 2>/dev/null || true
+
+# An account, made the way an administrator makes one at the console (the password is a test value).
+printf 'fixture-password-0123456789\n' | "$work/cipherhorizon$exe" user add --db "$db" --role admin fixture-admin
+
+mkdir -p "$(dirname "$out")"
+"$work/cipherhorizon$exe" db backup --db "$db" "$out"
+echo "wrote $out ($(wc -c < "$out") bytes) with $("$work/cipherhorizon$exe" version | head -1)"
diff --git a/testing/upgrade/seed.mjs b/testing/upgrade/seed.mjs
new file mode 100644
index 0000000..e05beaa
--- /dev/null
+++ b/testing/upgrade/seed.mjs
@@ -0,0 +1,100 @@
+// Seeds a CipherHorizon server with the kinds of data a real install holds, through the HTTP API
+// every release since 0.1.0 serves. make-fixture.sh runs it against a *released* version so the
+// database it leaves is exactly what that release writes (PRD-016 U-02).
+//
+//   node testing/upgrade/seed.mjs --base http://127.0.0.1:18090 --token T --demo-base 19440
+//
+// Every step must succeed: a fixture missing a kind of data would test less than it claims.
+// It talks only to a server on this machine (the throwaway one make-fixture.sh starts), and reads
+// no files: the host inventory is uploaded by make-fixture.sh itself.
+
+const args = Object.fromEntries(
+  process.argv.slice(2).reduce((acc, a, i, all) => (a.startsWith("--") ? [...acc, [a.slice(2), all[i + 1]]] : acc), []),
+);
+const token = args.token;
+const demo = Number(args["demo-base"] || 19440);
+if (!args.base || !token) {
+  console.error("usage: seed.mjs --base http://127.0.0.1:PORT --token TOKEN --demo-base PORT");
+  process.exit(2);
+}
+// Loopback only: this script exists to fill a local test server, never to send anything elsewhere.
+const baseURL = new URL(args.base);
+if (baseURL.protocol !== "http:" || !["127.0.0.1", "localhost", "[::1]"].includes(baseURL.hostname)) {
+  console.error(`seed.mjs: --base must be http:// on loopback (127.0.0.1, localhost or [::1]), not ${baseURL.origin}`);
+  process.exit(2);
+}
+const base = baseURL.origin;
+
+async function api(method, path, body, type = "application/json") {
+  const res = await fetch(base + path, {
+    method,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "X-Requested-With": "cipherhorizon",
+      ...(body !== undefined ? { "Content-Type": type } : {}),
+    },
+    body: body === undefined ? undefined : type === "application/json" ? JSON.stringify(body) : body,
+  });
+  const text = await res.text();
+  if (!res.ok) throw new Error(`${method} ${path}: ${res.status} ${text.slice(0, 300)}`);
+  return text ? JSON.parse(text) : null;
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const at = (n) => `127.0.0.1:${demo + n}`;
+
+// What a real estate looks like: a range of TLS quality, a post-quantum certificate, SSH, STARTTLS,
+// and an endpoint that never answers (a failed scan).
+const targets = [
+  { target: at(0), name: "modern-hybrid", tags: ["prod", "web"], notes: "fixture: hybrid PQ key exchange" },
+  { target: at(1), name: "classical-tls13", tags: ["prod"] },
+  { target: at(2), name: "legacy-tls12", tags: ["legacy"] },
+  { target: at(3), name: "terrible-legacy", tags: ["legacy"], notes: "fixture: <b>markup</b> stays text" },
+  { target: at(4), name: "dead-port" },
+  { target: at(18), name: "mldsa-only", tags: ["pq"] },
+  { target: `ssh://${at(20)}`, name: "ssh-modern", tags: ["ssh"] },
+  { target: `smtp://${at(11)}`, name: "mail-starttls", tags: ["mail"] },
+];
+
+async function scanAndWait(id) {
+  const sc = await api("POST", `/api/v1/assets/${id}/scan`);
+  const scanId = sc?.id ?? sc?.scan?.id;
+  if (!scanId) throw new Error(`scan of asset ${id}: no scan id in ${JSON.stringify(sc).slice(0, 200)}`);
+  for (let i = 0; i < 240; i++) {
+    const s = await api("GET", `/api/v1/scans/${scanId}`);
+    const status = s?.status ?? s?.scan?.status;
+    if (["done", "failed", "canceled"].includes(status)) return status;
+    await sleep(500);
+  }
+  throw new Error(`scan ${scanId} did not finish`);
+}
+
+const ids = {};
+for (const t of targets) {
+  const a = await api("POST", "/api/v1/assets", t);
+  ids[t.name] = a.id ?? a.asset?.id;
+  if (!ids[t.name]) throw new Error(`asset ${t.name}: no id`);
+}
+// Scan each twice, so there is history (and a diff) to keep.
+for (const round of [1, 2]) {
+  for (const t of targets) {
+    const status = await scanAndWait(ids[t.name]);
+    console.log(`round ${round}: ${t.name} -> ${status}`);
+  }
+}
+
+// A triage decision on a real finding.
+const findings = await api("GET", `/api/v1/assets/${ids["legacy-tls12"]}/findings`);
+const list = Array.isArray(findings) ? findings : findings?.findings ?? [];
+const key = list.map((f) => f.key).find(Boolean);
+if (!key) throw new Error("legacy-tls12 has no finding to triage");
+await api("PUT", `/api/v1/assets/${ids["legacy-tls12"]}/findings/${encodeURIComponent(key)}/status`, {
+  status: "accepted-risk",
+  note: "fixture: decommissioning in Q3",
+});
+
+// A link between two endpoints (the same service behind two names).
+await api("PUT", `/api/v1/assets/${ids["modern-hybrid"]}/links/${ids["classical-tls13"]}`);
+
+const summary = await api("GET", "/api/v1/summary");
+console.log("seeded:", JSON.stringify(summary).slice(0, 300));