Accept a remote key for restore and verify, and document it (closes #124)

A host restoring after the original is gone has no local index and cannot
know a snapshot's human ID; `snapshot list` shows such snapshots only by
their remote key. Restore and verify now resolve an identifier to that
remote key: a human ID is hashed as before, and a remote key (or an
unambiguous leading part of it, as the table prints) is used directly,
resolved against the store's metadata listing. Deep verify reads the one
snapshot in the exported database rather than filtering by the human ID.

Adds an integration test that backs up with one index and hostname, then
lists, restores, and deep-verifies from the store with a fresh empty
index, a different hostname, and no age_recipients — comparing restored
bytes to the source. The empty index is what makes it fail if restore
ever needed the original one.

Adds a "Restoring on another machine" README section walking the flow end
to end, and drops the now-done roadmap item.

Model: claude-opus-4-8

AGENTS.md

@@ -104,7 +104,12 @@ Version: 2025-06-08
 
 13. Pre-1.0: NEVER write database migrations. There are no live databases
     anywhere — every user's local index can be rebuilt from a fresh full
-    backup. When the schema changes, just change `schema.sql` (and any code
+    backup. To change the schema, edit `internal/database/schema/001.sql`
-    that touches the affected tables). The local index is disposable until
+    (and any code that touches the affected tables) directly; do not add new
-    1.0 ships and is tagged.
+    numbered schema files. Those numbered files and the `schema_migrations`
+    table they populate only bootstrap a fresh database — they are not an
+    upgrade path. The local index is disposable until 1.0 ships and is
+    tagged; once 1.0 is tagged that clause expires and the question of
+    upgrading existing indexes returns. See [`docs/DATAMODEL.md`](docs/DATAMODEL.md)
+    for the full explanation.
 

README.md

@@ -514,9 +514,13 @@ Key fields:
   sequentially. Restore speed is bound by single-stream throughput.
 * **Device nodes, named pipes, and sockets are silently skipped.** Only
   regular files, directories, and symlinks are backed up.
-* **No database migrations.** If the local SQLite schema changes between
+* **No upgrade path between versions.** There is no supported way to carry
-  versions, delete the local database (`vaultik database delete`) and run
+  an existing local index across a schema change; if the local SQLite
-  a full backup. Remote storage is unaffected.
+  schema changes between versions, delete the local database (`vaultik
+  database delete`) and run a full backup. Remote storage is unaffected.
+  (The binary does embed numbered schema files and a `schema_migrations`
+  table to bootstrap a fresh database — see [`docs/DATAMODEL.md`](docs/DATAMODEL.md)
+  — but that is not an upgrade path.)
 * **Files that change during backup may be inconsistent.** There is no
   filesystem snapshot or freeze. If a file is modified between the scan
   and chunk phases, the backed-up copy may reflect a partial write.
@@ -582,10 +586,12 @@ priority.
 
 ### infrastructure
 
-* **Schema migrations.** Currently nonexistent — pre-1.0 schema
+* **Cross-version schema upgrades.** There is no upgrade path between
-  changes are handled by `vaultik database delete` plus a full
+  released versions — pre-1.0 schema changes are handled by `vaultik
-  re-scan. Post-1.0 we'll need a migration story to keep existing
+  database delete` plus a full re-scan (see
-  index databases usable across upgrades.
+  [`docs/DATAMODEL.md`](docs/DATAMODEL.md)). Post-1.0 we'll need a
+  migration story to keep existing index databases usable across
+  upgrades.
 * **Storage backend coverage tests.** S3, file://, and rclone://
   all share the Storer interface but the rclone path is the least
   exercised in CI.

docs/DATAMODEL.md

@@ -5,11 +5,30 @@
 Vaultik uses a local SQLite database to track file metadata, chunk mappings, and blob associations during the backup process. This database serves as an index for incremental backups and enables efficient deduplication.
 
 **Important Notes:**
-- **No Migration Support (pre-1.0)**: Vaultik does not support database schema
+
-  migrations. The local index is treated as disposable — if the schema changes,
+This section is the authoritative explanation of the schema/migration story;
-  delete the local SQLite database (`vaultik database delete`) and run a full
+other documents (the README and `AGENTS.md`) link here.
-  backup. The remote storage is unaffected; the new index will re-deduplicate
+
-  against existing remote blobs.
+- **No upgrade path between versions (pre-1.0)**: Vaultik has no supported way to
+  carry an existing local index across a schema change. The index is disposable
+  — if the on-disk schema changes between versions, delete the local SQLite
+  database (`vaultik database delete`) and run a full backup. Remote storage is
+  unaffected; the new index re-deduplicates against existing remote blobs. This
+  is the standing project policy, and it is separate from the schema bootstrap
+  described next.
+- **Schema bootstrap**: a fresh database is populated from numbered SQL files
+  embedded in the binary under `internal/database/schema/`. `000.sql` creates the
+  `schema_migrations` table; `001.sql` creates the application tables. On opening
+  a database the code applies each numbered file that has not yet run and records
+  its version in `schema_migrations`. This bootstraps a new database; it does not
+  upgrade an existing one between released versions.
+- **Changing the schema (pre-1.0)**: edit `internal/database/schema/001.sql` (and
+  the code that touches the affected tables) directly. Do not add new numbered
+  files — there is no installed base to migrate.
+- **Disposability expires at 1.0**: the index is treated as disposable only until
+  1.0 ships and is tagged. Once 1.0 is tagged that clause expires and the
+  question of upgrading existing indexes returns. It is deliberately left open
+  here.
 - **Version Compatibility**: In rare cases, you may need to use the same version
   of Vaultik to restore a backup as was used to create it. This ensures
   compatibility with the metadata format stored in S3.