Refuse config keys that no setting has (closes #419)

config.Parse walks the file as written and fails on the first key that
matches no setting, naming its dotted path and line, so a typo in
exclude or prune_grace_period no longer falls back silently. ${...}
references and YAML merge keys still load. config set refuses such a key
before writing. The key-to-field lookup moves from internal/cli to
config.SettingType so both use it.

Model: opus-5-5

.prettierignore

@@ -0,0 +1,2 @@
+node_modules/
+yarn.lock

.prettierrc

@@ -0,0 +1,4 @@
+{
+    "tabWidth": 4,
+    "proseWrap": "always"
+}

AGENTS.md

@@ -4,127 +4,122 @@ Version: 2025-06-08
 
 # Instructions and Contextual Information
 
-* Be direct, robotic, expert, accurate, and professional.
+- Be direct, robotic, expert, accurate, and professional.
 
-* Do not butter me up or kiss my ass.
+- Do not butter me up or kiss my ass.
 
-* Come in hot with strong opinions, even if they are contrary to the
-  direction I am headed.
+- Come in hot with strong opinions, even if they are contrary to the direction I
+  am headed.
 
-* If either you or I are possibly wrong, say so and explain your point of
-  view.
+- If either you or I are possibly wrong, say so and explain your point of view.
 
-* Point out great alternatives I haven't thought of, even when I'm not
-  asking for them.
+- Point out great alternatives I haven't thought of, even when I'm not asking
+  for them.
 
-* Treat me like the world's leading expert in every situation and every
+- Treat me like the world's leading expert in every situation and every
   conversation, and deliver the absolute best recommendations.
 
-* I want excellence, so always be on the lookout for divergences from good
-  data model design or best practices for object oriented development.
+- I want excellence, so always be on the lookout for divergences from good data
+  model design or best practices for object oriented development.
 
-* IMPORTANT: This is production code, not a research or teaching exercise.
+- IMPORTANT: This is production code, not a research or teaching exercise.
   Deliver professional-level results, not prototypes.
 
-* Please read and understand the `README.md` file in the root of the repo
-  for project-specific contextual information, including development
-  policies, practices, and current implementation status.
+- Please read and understand the `README.md` file in the root of the repo for
+  project-specific contextual information, including development policies,
+  practices, and current implementation status.
 
-* Be proactive in suggesting improvements or refactorings in places where we
+- Be proactive in suggesting improvements or refactorings in places where we
   diverge from best practices for clean, modular, maintainable code.
 
 # Policies
 
 1. Before committing, tests must pass (`make test`), linting must pass
-   (`make lint`), and code must be formatted (`make fmt`).  For go, those
+   (`make lint`), and code must be formatted (`make fmt`). For go, those
    makefile targets should use `go fmt` and `go test -v ./...` and
-   `golangci-lint run`.  Each Makefile target does exactly one thing — to
-   run lint + fmt-check + test together (the standard pre-commit gate),
-   use `make check`.
+   `golangci-lint run`. Each Makefile target does exactly one thing — to run
+   lint + fmt-check + test together (the standard pre-commit gate), use
+   `make check`.
 
-2. Always write a `Makefile` with the default target being `test`, and with
-   a `fmt` target that formats the code.  The `test` target should run all
-   tests in the project, and the `fmt` target should format the code.
-   `test` should also have a prerequisite target `lint` that should run any
-   linters that are configured for the project.
+2. Always write a `Makefile` with the default target being `test`, and with a
+   `fmt` target that formats the code. The `test` target should run all tests in
+   the project, and the `fmt` target should format the code. `test` should also
+   have a prerequisite target `lint` that should run any linters that are
+   configured for the project.
 
-3. After each completed bugfix or feature, the code must be committed.  Do
-   all of the pre-commit checks (test, lint, fmt) before committing, of
-   course.
+3. After each completed bugfix or feature, the code must be committed. Do all of
+   the pre-commit checks (test, lint, fmt) before committing, of course.
 
 4. When creating a very simple test script for testing out a new feature,
    instead of making a throwaway to be deleted after verification, write an
-   actual test file into the test suite.  It doesn't need to be very big or
+   actual test file into the test suite. It doesn't need to be very big or
    complex, but it should be a real test that can be run.
 
 5. When you are instructed to make the tests pass, DO NOT delete tests, skip
-   tests, or change the tests specifically to make them pass (unless there
-   is a bug in the test).  This is cheating, and it is bad.  You should only
-   be modifying the test if it is incorrect or if the test is no longer
-   relevant.  In almost all cases, you should be fixing the code that is
-   being tested, or updating the tests to match a refactored implementation.
+   tests, or change the tests specifically to make them pass (unless there is a
+   bug in the test). This is cheating, and it is bad. You should only be
+   modifying the test if it is incorrect or if the test is no longer relevant.
+   In almost all cases, you should be fixing the code that is being tested, or
+   updating the tests to match a refactored implementation.
 
 6. When dealing with dates and times or timestamps, always use, display, and
-   store UTC.  Set the local timezone to UTC on startup.  If the user needs
-   to see the time in a different timezone, store the user's timezone in a
-   separate field and convert the UTC time to the user's timezone when
-   displaying it.  For internal use and internal applications and
-   administrative purposes, always display UTC.
+   store UTC. Set the local timezone to UTC on startup. If the user needs to see
+   the time in a different timezone, store the user's timezone in a separate
+   field and convert the UTC time to the user's timezone when displaying it. For
+   internal use and internal applications and administrative purposes, always
+   display UTC.
 
 7. Always write tests, even if they are extremely simple and just check for
-   correct syntax (ability to compile/import). If you are writing a new
-   feature, write a test for it.  You don't need to target complete
-   coverage, but you should at least test any new functionality you add.  If
-   you are fixing a bug, write a test first that reproduces the bug, and
-   then fix the bug in the code.
+   correct syntax (ability to compile/import). If you are writing a new feature,
+   write a test for it. You don't need to target complete coverage, but you
+   should at least test any new functionality you add. If you are fixing a bug,
+   write a test first that reproduces the bug, and then fix the bug in the code.
 
-8. When implementing new features, be aware of potential side-effects (such
-   as state files on disk, data in the database, etc.) and ensure that it is
+8. When implementing new features, be aware of potential side-effects (such as
+   state files on disk, data in the database, etc.) and ensure that it is
    possible to mock or stub these side-effects in tests.
 
-9. Always use structured logging.  Log any relevant state/context with the
-   messages (but do not log secrets).  If the log stream is not a terminal,
+9. Always use structured logging. Log any relevant state/context with the
+   messages (but do not log secrets). If the log stream is not a terminal,
    output the structured logs in jsonl format.
 
 10. Avoid using bare strings or numbers in code, especially if they appear
-    anywhere more than once.  Always define a constant (usually at the top
-    of the file) and give it a descriptive name, then use that constant in
-    the code instead of the bare string or number.
+    anywhere more than once. Always define a constant (usually at the top of the
+    file) and give it a descriptive name, then use that constant in the code
+    instead of the bare string or number.
 
 11. You do not need to summarize your changes in the chat after making them.
-    Making the changes and committing them is sufficient.  If anything out
-    of the ordinary happened, please explain it, but in the normal case
-    where you found and fixed the bug, or implemented the feature, there is
-    no need for the end-of-change summary.
+    Making the changes and committing them is sufficient. If anything out of the
+    ordinary happened, please explain it, but in the normal case where you found
+    and fixed the bug, or implemented the feature, there is no need for the
+    end-of-change summary.
 
-12. Do not create additional files in the root directory of the project
-    without asking permission first. Configuration files, documentation, and
-    build files are acceptable in the root, but source code and other files
-    should be organized in appropriate subdirectories.
+12. Do not create additional files in the root directory of the project without
+    asking permission first. Configuration files, documentation, and build files
+    are acceptable in the root, but source code and other files should be
+    organized in appropriate subdirectories.
 
 13. Pre-1.0: NEVER add a database migration. Migrations are supported, but
-    nothing is installed anywhere yet, so there is nothing to migrate. To
-    change the schema, edit `internal/database/schema/001.sql` (and any
-    code that touches the affected tables) directly. After 1.0, each schema
-    change is a new numbered file in that directory and a released file is
-    never edited; an existing local database is then migrated when vaultik
-    is updated. Before 1.0, a local database left on an older schema is
-    deleted and re-created by a full backup. See
-    [`docs/DATAMODEL.md`](docs/DATAMODEL.md#schema-migrations).
+    nothing is installed anywhere yet, so there is nothing to migrate. To change
+    the schema, edit `internal/database/schema/001.sql` (and any code that
+    touches the affected tables) directly. After 1.0, each schema change is a
+    new numbered file in that directory and a released file is never edited; an
+    existing local database is then migrated when vaultik is updated. Before
+    1.0, a local database left on an older schema is deleted and re-created by a
+    full backup. See [`docs/DATAMODEL.md`](docs/DATAMODEL.md#schema-migrations).
 
-14. Never use `git add -A`.  Stage only the files you intentionally
-    changed.
+14. Never use `git add -A`. Stage only the files you intentionally changed.
 
-15. Commit messages carry no attribution or advertising trailers for the
-    tool that helped write the code, or for its vendor: the owner is the
-    sole author of code written with a tool.
+15. Commit messages carry no attribution or advertising trailers for the tool
+    that helped write the code, or for its vendor: the owner is the sole author
+    of code written with a tool.
 
 16. Run the whole test suite with `make test` every time, and read its full
-    output.  Never run `go test`, a single test or a single package, and
-    never grep the output.
+    output. Never run `go test`, a single test or a single package, and never
+    grep the output.
 
 17. Do not stop working on a task until the definition of done given in the
     initial instruction is met: all of the work, not part or most of it.
 
-18. For estimates: backing up over 2.5Gbit/s ethernet to an S3 server
-    backed by 2000MB/sec SSD takes about 4 seconds per gigabyte.
+18. For estimates: backing up over 2.5Gbit/s ethernet to an S3 server backed by
+    2000MB/sec SSD takes about 4 seconds per gigabyte.

configs/config.example.yml

@@ -329,14 +329,16 @@ storage_url: "rclone://myremote/path/to/backups"
 # Default: 3
 compression_level: 5
 
-# How old a blob that no snapshot lists must be before prune deletes it
-# A backup uploads its blobs before the manifest that lists them, so on a
+# How old a blob that no snapshot lists must be before prune deletes it, and
+# how old every object in a directory under metadata/ with no manifest must
+# be before prune deletes that directory
+# A backup uploads its blobs and its db.zst.age before its manifest, so on a
 # destination shared between hosts or users this must be longer than the
 # longest backup run
 # It does not protect a blob a backup reuses from an earlier run that stopped
 # before its manifest: that blob keeps the time of its first upload, so a
 # prune can delete it
-# Supports: 36h, 90m, etc.; 0s deletes them at once
+# Supports: 36h, 90m, etc.; 0s deletes such blobs and directories at once
 # Default: 24h
 #prune_grace_period: 24h
 

docs/ARCHITECTURE.md

@@ -1,10 +1,14 @@
 # Vaultik Architecture
 
-This document describes the internal architecture of Vaultik, focusing on the data model, type instantiation, and the relationships between core modules.
+This document describes the internal architecture of Vaultik, focusing on the
+data model, type instantiation, and the relationships between core modules.
 
 ## Overview
 
-Vaultik is a backup system that uses content-defined chunking for deduplication and packs chunks into large, compressed, encrypted blobs for efficient cloud storage. The system is built around dependency injection using [uber-go/fx](https://github.com/uber-go/fx).
+Vaultik is a backup system that uses content-defined chunking for deduplication
+and packs chunks into large, compressed, encrypted blobs for efficient cloud
+storage. The system is built around dependency injection using
+[uber-go/fx](https://github.com/uber-go/fx).
 
 ## Data Flow
 
@@ -53,57 +57,88 @@ The database tracks five primary entities and their relationships:
 ### Entity Descriptions
 
 #### File (`database.File`)
-Represents a file, directory, or symlink in the backup system. Stores metadata needed for restoration:
+
+Represents a file, directory, or symlink in the backup system. Stores metadata
+needed for restoration:
+
 - Path, mtime
 - Size, mode, ownership (uid, gid)
 - Symlink target (if applicable)
 
-It also stores `source_path`, the source directory the scan found it under, made absolute and with symlinks resolved. Restore does not read it.
+It also stores `source_path`, the source directory the scan found it under, made
+absolute and with symlinks resolved. Restore does not read it.
 
 #### Chunk (`database.Chunk`)
-A content-addressed unit of data. Files are split into variable-size chunks using the FastCDC algorithm:
+
+A content-addressed unit of data. Files are split into variable-size chunks
+using the FastCDC algorithm:
+
 - `ChunkHash`: SHA256 hash of chunk content (primary key)
 - `Size`: Chunk size in bytes
 
-Chunk sizes vary between `avgChunkSize/4` and `avgChunkSize*4` (2.5MB-40MB for the 10MB default average).
+Chunk sizes vary between `avgChunkSize/4` and `avgChunkSize*4` (2.5MB-40MB for
+the 10MB default average).
 
 #### FileChunk (`database.FileChunk`)
+
 Maps files to their constituent chunks:
+
 - `FileID`: Reference to the file
 - `Idx`: Position of this chunk within the file (0-indexed)
 - `ChunkHash`: Reference to the chunk
 
 #### Blob (`database.Blob`)
-The final storage unit uploaded to S3. Contains many compressed and encrypted chunks:
+
+The final storage unit uploaded to S3. Contains many compressed and encrypted
+chunks:
+
 - `ID`: UUID assigned at creation
-- `Hash`: `hex(SHA256(SHA256(uncompressed blob contents)))`, computed before compression and encryption (see [docs/REPOSTRUCTURE.md](docs/REPOSTRUCTURE.md#blobs-directory-blobs))
+- `Hash`: `hex(SHA256(SHA256(uncompressed blob contents)))`, computed before
+  compression and encryption (see
+  [docs/REPOSTRUCTURE.md](REPOSTRUCTURE.md#blobs-directory-blobs))
 - `UncompressedSize`: Total raw chunk data before compression
 - `CompressedSize`: Size after zstd compression and age encryption
 - `CreatedTS`, `FinishedTS`, `UploadedTS`: Lifecycle timestamps
 
 Blob creation process:
+
 1. Chunks are accumulated (up to MaxBlobSize, typically 10GB)
 2. As each chunk is added, its uncompressed bytes are fed to a running SHA-256
-3. Concurrently, the same bytes are compressed with zstd, then encrypted with age (recipients configured in config), and written to a temporary file
-4. On finalize, the blob's name is the double SHA-256 of the uncompressed contents — `hex(SHA256(SHA256(...)))` — not a hash of the compressed, encrypted bytes
-5. The finished file is uploaded to `blobs/{hash[0:2]}/{hash[2:4]}/{hash}` and then deleted
+3. Concurrently, the same bytes are compressed with zstd, then encrypted with
+   age (recipients configured in config), and written to a temporary file
+4. On finalize, the blob's name is the double SHA-256 of the uncompressed
+   contents — `hex(SHA256(SHA256(...)))` — not a hash of the compressed,
+   encrypted bytes
+5. The finished file is uploaded to `blobs/{hash[0:2]}/{hash[2:4]}/{hash}` and
+   then deleted
 
-A backup needs free temporary space, because each blob is written whole to a temporary file before it is uploaded (up to about `blob_size_limit`; an rclone destination that cannot stream uploads needs about twice that) and the metadata export writes copies of the local index. Temporary files go to `$TMPDIR` (default `/tmp`); with `TMPDIR` unset, SQLite writes one of those copies to `/var/tmp`.
+A backup needs free temporary space, because each blob is written whole to a
+temporary file before it is uploaded (up to about `blob_size_limit`; an rclone
+destination that cannot stream uploads needs about twice that) and the metadata
+export writes copies of the local index. Temporary files go to `$TMPDIR`
+(default `/tmp`); with `TMPDIR` unset, SQLite writes one of those copies to
+`/var/tmp`.
 
 #### BlobChunk (`database.BlobChunk`)
+
 Maps chunks to their position within blobs:
+
 - `BlobID`: Reference to the blob
 - `ChunkHash`: Reference to the chunk
 - `Offset`: Byte offset within the uncompressed blob
 - `Length`: Chunk size
 
 #### Snapshot (`database.Snapshot`)
+
 Represents a point-in-time backup:
-- `ID`: Format is `{hostname}_{snapshot-name}_{RFC3339}` (e.g. `server1_home_2025-06-01T12:00:00Z`)
+
+- `ID`: Format is `{hostname}_{snapshot-name}_{RFC3339}` (e.g.
+  `server1_home_2025-06-01T12:00:00Z`)
 - Tracks file count, chunk count, blob count, sizes, compression ratio
 - `CompletedAt`: Null until snapshot finishes successfully
 
 #### SnapshotFile / SnapshotBlob
+
 Join tables linking snapshots to their files and blobs.
 
 ### Relationship Summary
@@ -140,21 +175,27 @@ fx.New(
 ### Key Type Instantiation Points
 
 #### 1. Config (`config.Config`)
+
 - **Created by**: `config.Module` via `config.LoadConfig()`
 - **When**: Application startup (fx DI)
-- **Contains**: All configuration from YAML file (S3 credentials, encryption keys, paths, etc.)
+- **Contains**: All configuration from YAML file (S3 credentials, encryption
+  keys, paths, etc.)
 
 #### 2. Database (`database.DB`)
+
 - **Created by**: `database.Module` via `database.New()`
 - **When**: Application startup (fx DI)
 - **Contains**: SQLite connection, path reference
 
 #### 3. Repositories (`database.Repositories`)
+
 - **Created by**: `database.Module` via `database.NewRepositories()`
 - **When**: Application startup (fx DI)
-- **Contains**: All repository interfaces (Files, Chunks, Blobs, Snapshots, etc.)
+- **Contains**: All repository interfaces (Files, Chunks, Blobs, Snapshots,
+  etc.)
 
 #### 4. Vaultik (`vaultik.Vaultik`)
+
 - **Created by**: `vaultik.New(VaultikParams)`
 - **When**: Application startup (fx DI)
 - **Contains**: All dependencies for backup operations
@@ -176,11 +217,13 @@ type Vaultik struct {
 ```
 
 #### 5. SnapshotManager (`snapshot.SnapshotManager`)
+
 - **Created by**: `snapshot.Module` via `snapshot.NewSnapshotManager()`
 - **When**: Application startup (fx DI)
 - **Responsibility**: Creates/completes snapshots, exports metadata to S3
 
 #### 6. Scanner (`snapshot.Scanner`)
+
 - **Created by**: `ScannerFactory(ScannerParams)`
 - **When**: Each `CreateSnapshot()` call
 - **Contains**: Chunker, Packer, progress reporter
@@ -194,20 +237,22 @@ scanner := v.ScannerFactory(snapshot.ScannerParams{
 ```
 
 #### 7. Chunker (`chunker.Chunker`)
+
 - **Created by**: `chunker.NewChunker(avgChunkSize)`
 - **When**: Inside `snapshot.NewScanner()`
 - **Configuration**:
-  - `avgChunkSize`: From config (default 10MB)
-  - `minChunkSize`: avgChunkSize / 4
-  - `maxChunkSize`: avgChunkSize * 4
+    - `avgChunkSize`: From config (default 10MB)
+    - `minChunkSize`: avgChunkSize / 4
+    - `maxChunkSize`: avgChunkSize \* 4
 
 #### 8. Packer (`blob.Packer`)
+
 - **Created by**: `blob.NewPacker(PackerConfig)`
 - **When**: Inside `snapshot.NewScanner()`
 - **Configuration**:
-  - `MaxBlobSize`: Maximum blob size before finalization (typically 10GB)
-  - `CompressionLevel`: zstd level (1-19)
-  - `Recipients`: age public keys for encryption
+    - `MaxBlobSize`: Maximum blob size before finalization (typically 10GB)
+    - `CompressionLevel`: zstd level (1-19)
+    - `Recipients`: age public keys for encryption
 
 ```go
 // snapshot/scanner.go: NewScanner()
@@ -224,17 +269,22 @@ packer, err := blob.NewPacker(packerCfg)
 ## Module Responsibilities
 
 ### `internal/cli`
-Entry point for fx application. Combines all modules and handles signal interrupts.
+
+Entry point for fx application. Combines all modules and handles signal
+interrupts.
 
 Key functions:
+
 - `NewApp(AppOptions)` → Creates fx.App with all modules
 - `RunApp(ctx, app)` → Starts app, handles graceful shutdown
 - `RunWithApp(ctx, opts)` → Convenience wrapper
 
 ### `internal/vaultik`
+
 Main orchestrator containing all dependencies and command implementations.
 
 Key methods:
+
 - `New(VaultikParams)` → Constructor (fx DI)
 - `CreateSnapshot(opts)` → Main backup operation
 - `ListSnapshots(jsonOutput)` → List available snapshots
@@ -242,27 +292,34 @@ Key methods:
 - `PurgeSnapshots(...)` → Remove old snapshots
 
 ### `internal/chunker`
+
 Content-defined chunking using FastCDC algorithm.
 
 Key types:
+
 - `Chunk` → Hash, Data, Offset, Size
 - `Chunker` → avgChunkSize, minChunkSize, maxChunkSize
 
 Key methods:
+
 - `NewChunker(avgChunkSize)` → Constructor
-- `ChunkReaderStreaming(reader, callback)` → Stream chunks with callback (preferred)
+- `ChunkReaderStreaming(reader, callback)` → Stream chunks with callback
+  (preferred)
 - `ChunkReader(reader)` → Return all chunks at once (memory-intensive)
 
 ### `internal/blob`
+
 Blob packing: accumulates chunks, compresses, encrypts, tracks metadata.
 
 Key types:
+
 - `Packer` → Thread-safe blob accumulator
 - `ChunkRef` → Hash + Data for adding to packer
 - `FinishedBlob` → Completed blob ready for upload
 - `BlobWithReader` → FinishedBlob + io.Reader for streaming upload
 
 Key methods:
+
 - `NewPacker(PackerConfig)` → Constructor
 - `AddChunk(ChunkRef)` → Add chunk to current blob
 - `FinalizeBlob()` → Compress, encrypt, hash current blob
@@ -272,35 +329,48 @@ Key methods:
 ### `internal/snapshot`
 
 #### Scanner
+
 Orchestrates the backup process for a directory.
 
 Key methods:
+
 - `NewScanner(ScannerConfig)` → Constructor (creates Chunker + Packer)
 - `Scan(ctx, path, snapshotID)` → Main scan operation
 
 Scan phases:
+
 1. **Phase 1**: Walk directory, identify files needing processing
-2. **Phase 1b**: Count as deleted the files that the previous snapshot of the same name lists, the walk did not find, and are gone from disk; a file that is excluded, or inside an excluded directory, is not counted
+2. **Phase 1b**: Count as deleted the files that the previous snapshot of the
+   same name lists, the walk did not find, and are gone from disk; a file that
+   is excluded, or inside an excluded directory, is not counted
 3. **Phase 2**: Process files (chunk → pack → upload)
 
 #### SnapshotManager
+
 Manages snapshot lifecycle and metadata export.
 
 Key methods:
+
 - `CreateSnapshot(ctx, hostname, version, commit)` → Create snapshot record
-- `PopulateSnapshotBlobs(ctx, snapshotID)` → Record every blob the snapshot references
+- `PopulateSnapshotBlobs(ctx, snapshotID)` → Record every blob the snapshot
+  references
 - `ExportSnapshotMetadata(ctx, dbPath, snapshotID)` → Export to S3
-- `MarkSnapshotComplete(ctx, snapshotID)` → Record completion, only after a successful export
-- `CompleteSnapshot(ctx, snapshotID)` → Convenience: populate blobs, then mark complete (no export between)
+- `MarkSnapshotComplete(ctx, snapshotID)` → Record completion, only after a
+  successful export
+- `CompleteSnapshot(ctx, snapshotID)` → Convenience: populate blobs, then mark
+  complete (no export between)
 
 ### `internal/database`
+
 SQLite database for local index. Single-writer mode for thread safety.
 
 Key types:
+
 - `DB` → Database connection wrapper
 - `Repositories` → Collection of all repository interfaces
 
 Repository interfaces:
+
 - `FilesRepository` → CRUD for File records
 - `ChunksRepository` → CRUD for Chunk records
 - `BlobsRepository` → CRUD for Blob records
@@ -312,7 +382,7 @@ Repository interfaces:
 ```
 CreateSnapshot(opts)
     │
-    ├─► markDestination()   // Refuse a destination without the marker, then write it
+    ├─► markDestination()   // Check the marker (see Storage Layout in S3), then write it
     │
     ├─► PruneDatabase()   // Critical: avoid dedup errors
     │
@@ -359,11 +429,16 @@ CreateSnapshot(opts)
 
 ## Deduplication Strategy
 
-1. **File-level**: Files and symlinks unchanged since last backup are skipped (metadata comparison: size, mtime, mode, uid, gid, and a symlink's target), unless the file lists a chunk that no uploaded blob holds; such a file is re-chunked
+1. **File-level**: Files and symlinks unchanged since last backup are skipped
+   (metadata comparison: size, mtime, mode, uid, gid, and a symlink's target),
+   unless the file lists a chunk that no uploaded blob holds; such a file is
+   re-chunked
 
-2. **Chunk-level**: Chunks are content-addressed by SHA256 hash. If a chunk hash already exists in the database, the chunk data is not re-uploaded.
+2. **Chunk-level**: Chunks are content-addressed by SHA256 hash. If a chunk hash
+   already exists in the database, the chunk data is not re-uploaded.
 
-3. **Blob-level**: Blobs contain only unique chunks. Duplicate chunks within a blob are skipped.
+3. **Blob-level**: Blobs contain only unique chunks. Duplicate chunks within a
+   blob are skipped.
 
 ## Storage Layout in S3
 
@@ -382,25 +457,30 @@ bucket/
         └── manifest.json.zst        # Blob list (for pruning/verification)
 ```
 
-A destination without `vaultik-destination.txt` is treated as not present
-while the local index holds snapshots stored there (`checkDestinationMarker`
-in `internal/vaultik/destination_marker.go`): `snapshot create` refuses to
-write to it, `prune`, `snapshot purge` and `remote nuke` fail, and
-`snapshot list` and `snapshot remove` behave as for a destination that cannot
-be listed. This keeps those commands from taking an unplugged volume's empty
-mount point for a destination whose snapshots are all gone. The `file://`
-backend never creates its destination directory, so a write to a missing one
-fails.
+A destination that answers a look-up of `vaultik-destination.txt` with not found
+is treated as not present while the local index holds snapshots stored there
+(`checkDestinationMarker` in `internal/vaultik/destination_marker.go`):
+`snapshot create` refuses to write to it, `prune`, `snapshot purge` and
+`remote nuke` fail, and `snapshot list` and `snapshot remove` behave as for a
+destination that cannot be listed. This keeps those commands from taking an
+unplugged volume's empty mount point for a destination whose snapshots are all
+gone. When the look-up fails for any reason other than not found, for example
+when S3 refuses it to credentials that allow only PUT, the check is skipped, so
+a host with such credentials does not notice an emptied destination; see
+[docs/REPOSTRUCTURE.md](REPOSTRUCTURE.md#marker-file-vaultik-destinationtxt).
+The `file://` backend never creates its destination directory, so a write to a
+missing one fails.
 
 The `{remote-key}` directory name is a one-way double SHA-256 hash of the human
 snapshot ID, so the human ID (hostname, snapshot name, timestamp) is never
 written to the store as a directory name. See
-[docs/REPOSTRUCTURE.md](docs/REPOSTRUCTURE.md#remote-key-derivation) for the
+[docs/REPOSTRUCTURE.md](REPOSTRUCTURE.md#remote-key-derivation) for the
 derivation and a worked example.
 
 ## Thread Safety
 
 - `Packer`: Thread-safe via mutex. Multiple goroutines can call `AddChunk()`.
 - `Scanner`: Uses `packerMu` mutex to coordinate blob finalization.
-- `Database`: Single-writer mode (`MaxOpenConns=1`) ensures SQLite thread safety.
+- `Database`: Single-writer mode (`MaxOpenConns=1`) ensures SQLite thread
+  safety.
 - `Repositories.WithTx()`: Handles transaction lifecycle automatically.

docs/DATAMODEL.md

@@ -2,7 +2,9 @@
 
 ## Overview
 
-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.
+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:**
 
@@ -25,19 +27,23 @@ recorded `001.sql` as run, so it keeps the old schema and can become unusable;
 `vaultik database delete` followed by a full backup rebuilds it.
 
 **After 1.0** each schema change is a new numbered file, so an existing local
-database is migrated the first time an updated vaultik opens it. A file that
-has shipped in a release is never edited.
+database is migrated the first time an updated vaultik opens it. A file that has
+shipped in a release is never edited.
 
 ## Database Tables
 
 ### 1. `files`
+
 Stores metadata about files in the filesystem being backed up.
 
 **Columns:**
+
 - `id` (TEXT PRIMARY KEY) - UUID for the file record
 - `path` (TEXT NOT NULL UNIQUE) - Absolute file path
-- `mtime` (INTEGER NOT NULL) - Modification time, whole seconds since the Unix epoch
-- `mtime_nsec` (INTEGER NOT NULL) - Nanoseconds within that second, 0 to 999999999
+- `mtime` (INTEGER NOT NULL) - Modification time, whole seconds since the Unix
+  epoch
+- `mtime_nsec` (INTEGER NOT NULL) - Nanoseconds within that second, 0 to
+  999999999
 - `size` (INTEGER NOT NULL) - File size in bytes
 - `mode` (INTEGER NOT NULL) - Unix file permissions and type
 - `uid` (INTEGER NOT NULL) - User ID of file owner
@@ -45,23 +51,30 @@ Stores metadata about files in the filesystem being backed up.
 - `link_target` (TEXT) - Symlink target path (NULL for regular files)
 
 **Indexes:**
+
 - `idx_files_path` on `path` for efficient lookups
 
-**Purpose:** Tracks file metadata to detect changes between backup runs. Used for incremental backup decisions. The UUID primary key provides stable references that don't change if files are moved.
+**Purpose:** Tracks file metadata to detect changes between backup runs. Used
+for incremental backup decisions. The UUID primary key provides stable
+references that don't change if files are moved.
 
 ### 2. `chunks`
+
 Stores information about content-defined chunks created from files.
 
 **Columns:**
+
 - `chunk_hash` (TEXT PRIMARY KEY) - SHA256 hash of chunk content
 - `size` (INTEGER NOT NULL) - Chunk size in bytes
 
 **Purpose:** Enables deduplication by tracking unique chunks across all files.
 
 ### 3. `file_chunks`
+
 Maps files to their constituent chunks in order.
 
 **Columns:**
+
 - `file_id` (TEXT) - File ID (FK to files.id)
 - `idx` (INTEGER) - Chunk index within file (0-based)
 - `chunk_hash` (TEXT) - Chunk hash (FK to chunks.chunk_hash)
@@ -70,35 +83,49 @@ Maps files to their constituent chunks in order.
 **Purpose:** Allows reconstruction of files from chunks during restore.
 
 ### 4. `chunk_files`
+
 Reverse mapping showing which files contain each chunk.
 
 **Columns:**
+
 - `chunk_hash` (TEXT) - Chunk hash (FK to chunks.chunk_hash)
 - `file_id` (TEXT) - File ID (FK to files.id)
 - `file_offset` (INTEGER) - Byte offset of chunk within file
 - `length` (INTEGER) - Length of chunk in bytes
 - PRIMARY KEY (`chunk_hash`, `file_id`)
 
-**Purpose:** Supports efficient queries for chunk usage and deduplication statistics.
+**Purpose:** Supports efficient queries for chunk usage and deduplication
+statistics.
 
 ### 5. `blobs`
+
 Stores information about packed, compressed, and encrypted blob files.
 
 **Columns:**
+
 - `id` (TEXT PRIMARY KEY) - UUID assigned when blob creation starts
-- `blob_hash` (TEXT UNIQUE) - `hex(SHA256(SHA256(uncompressed blob contents)))`, computed before compression and encryption (NULL until finalized); see [REPOSTRUCTURE.md](REPOSTRUCTURE.md#blobs-directory-blobs)
+- `blob_hash` (TEXT UNIQUE) - `hex(SHA256(SHA256(uncompressed blob contents)))`,
+  computed before compression and encryption (NULL until finalized); see
+  [REPOSTRUCTURE.md](REPOSTRUCTURE.md#blobs-directory-blobs)
 - `created_ts` (INTEGER NOT NULL) - Creation timestamp
 - `finished_ts` (INTEGER) - Finalization timestamp (NULL if in progress)
-- `uncompressed_size` (INTEGER NOT NULL DEFAULT 0) - Total size of chunks before compression
-- `compressed_size` (INTEGER NOT NULL DEFAULT 0) - Size after compression and encryption. Once uploaded, the size of the object in storage: when the blob was already stored, under another compression level or other recipients, this can differ from the size of the local copy
+- `uncompressed_size` (INTEGER NOT NULL DEFAULT 0) - Total size of chunks before
+  compression
+- `compressed_size` (INTEGER NOT NULL DEFAULT 0) - Size after compression and
+  encryption. Once uploaded, the size of the object in storage: when the blob
+  was already stored, under another compression level or other recipients, this
+  can differ from the size of the local copy
 - `uploaded_ts` (INTEGER) - Upload completion timestamp (NULL if not uploaded)
 
-**Purpose:** Tracks blob lifecycle from creation through upload. The UUID primary key allows immediate association of chunks with blobs.
+**Purpose:** Tracks blob lifecycle from creation through upload. The UUID
+primary key allows immediate association of chunks with blobs.
 
 ### 6. `blob_chunks`
+
 Maps chunks to the blobs that contain them.
 
 **Columns:**
+
 - `blob_id` (TEXT) - Blob ID (FK to blobs.id)
 - `chunk_hash` (TEXT) - Chunk hash (FK to chunks.chunk_hash)
 - `offset` (INTEGER) - Byte offset of chunk within blob (before compression)
@@ -108,34 +135,46 @@ Maps chunks to the blobs that contain them.
 **Purpose:** Enables chunk retrieval from blobs during restore operations.
 
 ### 7. `snapshots`
+
 Tracks backup snapshots.
 
 **Columns:**
-- `id` (TEXT PRIMARY KEY) - Snapshot ID (format: `hostname_name_timestamp`, e.g. `server1_home_2025-06-01T12:00:00Z`: the hostname up to its first `.`, the snapshot name, and an RFC 3339 UTC timestamp)
+
+- `id` (TEXT PRIMARY KEY) - Snapshot ID (format: `hostname_name_timestamp`, e.g.
+  `server1_home_2025-06-01T12:00:00Z`: the hostname up to its first `.`, the
+  snapshot name, and an RFC 3339 UTC timestamp)
 - `hostname` (TEXT) - Hostname where backup was created
 - `vaultik_version` (TEXT) - Version of Vaultik used
 - `vaultik_git_revision` (TEXT) - Git revision of Vaultik used
 - `started_at` (INTEGER) - Start timestamp
 - `completed_at` (INTEGER) - Completion timestamp (NULL if in progress)
 - `file_count` (INTEGER) - Number of files in snapshot
-- `chunk_count` (INTEGER) - Number of chunks this snapshot stored that were not stored before
-- `new_chunk_size` (INTEGER) - Total size of those chunks before compression; `snapshot list` shows it as NEW CHUNK SIZE
+- `chunk_count` (INTEGER) - Number of chunks this snapshot stored that were not
+  stored before
+- `new_chunk_size` (INTEGER) - Total size of those chunks before compression;
+  `snapshot list` shows it as NEW CHUNK SIZE
 - `blob_count` (INTEGER) - Number of blobs this snapshot created
 - `total_size` (INTEGER) - Total size of all files
-- `uncompressed_chunk_size` (INTEGER) - Total size before compression of the distinct chunks the snapshot's files reference, recorded when its backup ran; `snapshot list` shows it as UNCOMPRESSED SIZE
+- `uncompressed_chunk_size` (INTEGER) - Total size before compression of the
+  distinct chunks the snapshot's files reference, recorded when its backup ran;
+  `snapshot list` shows it as UNCOMPRESSED SIZE
 - `blob_size` (INTEGER) - Total compressed size of all referenced blobs
-- `blob_uncompressed_size` (INTEGER) - Total uncompressed size of all referenced blobs
+- `blob_uncompressed_size` (INTEGER) - Total uncompressed size of all referenced
+  blobs
 - `compression_ratio` (REAL) - Compression ratio achieved
 - `compression_level` (INTEGER) - Compression level used for this snapshot
 - `upload_bytes` (INTEGER) - Total bytes uploaded during this snapshot
 - `upload_duration_ms` (INTEGER) - Total milliseconds spent uploading to S3
 
-**Purpose:** Provides snapshot metadata and statistics including version tracking for compatibility.
+**Purpose:** Provides snapshot metadata and statistics including version
+tracking for compatibility.
 
 ### 8. `snapshot_files`
+
 Maps snapshots to the files they contain.
 
 **Columns:**
+
 - `snapshot_id` (TEXT) - Snapshot ID (FK to snapshots.id)
 - `file_id` (TEXT) - File ID (FK to files.id)
 - PRIMARY KEY (`snapshot_id`, `file_id`)
@@ -143,99 +182,146 @@ Maps snapshots to the files they contain.
 **Purpose:** Records which files are included in each snapshot.
 
 ### 9. `snapshot_blobs`
+
 Maps snapshots to the blobs they reference.
 
 **Columns:**
+
 - `snapshot_id` (TEXT) - Snapshot ID (FK to snapshots.id)
 - `blob_id` (TEXT) - Blob ID (FK to blobs.id)
 - `blob_hash` (TEXT) - Denormalized blob hash for manifest generation
 - PRIMARY KEY (`snapshot_id`, `blob_id`)
 
-**Purpose:** Tracks blob dependencies for snapshots and enables manifest generation.
+**Purpose:** Tracks blob dependencies for snapshots and enables manifest
+generation.
+
+### 10. `snapshot_mount_points`
+
+The directories at or below a configured path, the configured path itself
+included, that a snapshot's backup found an entry in and, once it had listed
+them, found on a different filesystem from their parent directory (a different
+device number), as a mount point is. An automount point whose volume cannot be
+mounted is not recorded, because the backup finds no entry in it.
+
+**Columns:**
+
+- `snapshot_id` (TEXT) - Snapshot ID (FK to snapshots.id)
+- `path` (TEXT) - Absolute path of the directory
+- PRIMARY KEY (`snapshot_id`, `path`)
+
+**Purpose:** Lets `snapshot create --prune` skip the prune when a backup does
+not find a mount point that an earlier snapshot of the same name found, as when
+the volume is not mounted.
+
+### 11. `uploads`
 
-### 10. `uploads`
 Tracks blob upload metrics.
 
 **Columns:**
+
 - `blob_hash` (TEXT PRIMARY KEY) - Hash of uploaded blob
-- `snapshot_id` (TEXT NOT NULL) - The snapshot that triggered this upload (FK to snapshots.id)
+- `snapshot_id` (TEXT NOT NULL) - The snapshot that triggered this upload (FK to
+  snapshots.id)
 - `uploaded_at` (INTEGER) - Upload timestamp
 - `size` (INTEGER) - Size of uploaded blob
 - `duration_ms` (INTEGER) - Upload duration in milliseconds
 
-**Purpose:** Performance monitoring and tracking which blobs were newly created (uploaded) during each snapshot.
+**Purpose:** Performance monitoring and tracking which blobs were newly created
+(uploaded) during each snapshot.
 
 ## Data Flow and Operations
 
 ### 1. Backup Process
 
 1. **File Scanning**
-   - `INSERT OR REPLACE INTO files` - Update file metadata
-   - `SELECT * FROM files WHERE path = ?` - Check if file has changed
-   - `INSERT INTO snapshot_files` - Add file to current snapshot
+    - `INSERT OR REPLACE INTO files` - Update file metadata
+    - `SELECT * FROM files WHERE path = ?` - Check if file has changed
+    - `INSERT INTO snapshot_files` - Add file to current snapshot
+    - `INSERT OR IGNORE INTO snapshot_mount_points` - Record each directory on a
+      different filesystem from its parent that the walk found an entry in
 
 2. **Chunking** (for changed files)
-   - `INSERT OR IGNORE INTO chunks` - Store new chunks
-   - `INSERT INTO file_chunks` - Map chunks to file
-   - `INSERT INTO chunk_files` - Create reverse mapping
+    - `INSERT OR IGNORE INTO chunks` - Store new chunks
+    - `INSERT INTO file_chunks` - Map chunks to file
+    - `INSERT INTO chunk_files` - Create reverse mapping
 
 3. **Blob Packing**
-   - `INSERT INTO blobs` - Create blob record with UUID (blob_hash NULL)
-   - `INSERT INTO blob_chunks` - Associate chunks with blob immediately
-   - `UPDATE blobs SET blob_hash = ?, finished_ts = ?` - Finalize blob after packing
+    - `INSERT INTO blobs` - Create blob record with UUID (blob_hash NULL)
+    - `INSERT INTO blob_chunks` - Associate chunks with blob immediately
+    - `UPDATE blobs SET blob_hash = ?, finished_ts = ?` - Finalize blob after
+      packing
 
 4. **Upload**
-   - `UPDATE blobs SET uploaded_ts = ?, compressed_size = ?` - Mark blob as uploaded, with the size of the object in storage (the upload is skipped when the blob is already stored)
-   - `INSERT INTO uploads` - Record upload metrics with snapshot_id
-   - `INSERT INTO snapshot_blobs` - Associate blob with snapshot
+    - `UPDATE blobs SET uploaded_ts = ?, compressed_size = ?` - Mark blob as
+      uploaded, with the size of the object in storage (the upload is skipped
+      when the blob is already stored)
+    - `INSERT INTO uploads` - Record upload metrics with snapshot_id
+    - `INSERT INTO snapshot_blobs` - Associate blob with snapshot
 
 5. **Snapshot Completion**
-   - `UPDATE snapshots SET completed_at = ?, stats...` - Finalize snapshot
-   - Generate and upload blob manifest from `snapshot_blobs`
+    - `UPDATE snapshots SET completed_at = ?, stats...` - Finalize snapshot
+    - Generate and upload blob manifest from `snapshot_blobs`
 
 ### 2. Incremental Backup
 
 1. **Change Detection**
-   - `SELECT * FROM files WHERE path = ?` - Get previous file metadata
-   - Compare mtime, size, mode to detect changes
-   - Re-chunk a file that lists a chunk no uploaded blob holds, even when its metadata is unchanged
-   - Skip unchanged files but still add to `snapshot_files`
+    - `SELECT * FROM files WHERE path = ?` - Get previous file metadata
+    - Compare mtime, size, mode to detect changes
+    - Re-chunk a file that lists a chunk no uploaded blob holds, even when its
+      metadata is unchanged
+    - Skip unchanged files but still add to `snapshot_files`
 
 2. **Chunk Reuse**
-   - `SELECT * FROM blob_chunks WHERE chunk_hash = ?` - Find existing chunks
-   - `INSERT INTO snapshot_blobs` - Reference existing blobs for unchanged files
+    - `SELECT * FROM blob_chunks WHERE chunk_hash = ?` - Find existing chunks
+    - `INSERT INTO snapshot_blobs` - Reference existing blobs for unchanged
+      files
 
 ### 3. Snapshot Metadata Export
 
 After a snapshot is completed:
+
 1. Copy database to temporary file
 2. Clean temporary database to contain only current snapshot data
 3. VACUUM the trimmed database so deleted rows leave no pages behind
 4. Compress with zstd and encrypt with age
 5. Upload to S3 as `metadata/{remote-key}/db.zst.age`
-6. Generate blob manifest and upload as `metadata/{remote-key}/manifest.json.zst`
+6. Generate blob manifest and upload as
+   `metadata/{remote-key}/manifest.json.zst`
 
-The `{remote-key}` directory name is a one-way hash of the human snapshot ID, so the ID is never written to the store in plaintext. The hash uses no secret, so a guessed hostname and snapshot name can still be confirmed against a listing; see [REPOSTRUCTURE.md](REPOSTRUCTURE.md#remote-key-derivation) and its [Accepted Risks](REPOSTRUCTURE.md#accepted-risks).
+The `{remote-key}` directory name is a one-way hash of the human snapshot ID, so
+the ID is never written to the store in plaintext. The hash uses no secret, so a
+guessed hostname and snapshot name can still be confirmed against a listing; see
+[REPOSTRUCTURE.md](REPOSTRUCTURE.md#remote-key-derivation) and its
+[Accepted Risks](REPOSTRUCTURE.md#accepted-risks).
 
 ### 4. Restore Process
 
 The restore process doesn't use the local database. Instead:
-1. Downloads and decrypts the snapshot's metadata database (`db.zst.age`) from S3
-2. Downloads the blobs holding the chunks of the files being restored, found through that database's `blob_chunks` table; the manifest is not read
+
+1. Downloads and decrypts the snapshot's metadata database (`db.zst.age`) from
+   S3
+2. Downloads the blobs holding the chunks of the files being restored, found
+   through that database's `blob_chunks` table; the manifest is not read
 3. Reconstructs files from decrypted and decompressed chunks
 
 ### 5. Pruning
 
 1. **Identify Unreferenced Blobs**
-   - Query blobs not referenced by any remaining snapshot
-   - Delete from S3, once older than `prune_grace_period`, and from the local
-     database
+    - Query blobs not referenced by any remaining snapshot
+    - Delete from S3, once older than `prune_grace_period`, and from the local
+      database
+2. **Delete Metadata Directories With No Manifest**
+    - Delete each directory under `metadata/` that has no `manifest.json.zst`
+      and no local snapshot record, once every object in it is older than
+      `prune_grace_period`
 
 ### 6. Incomplete Snapshot Cleanup
 
 Before each backup:
+
 1. Query incomplete snapshots (where `completed_at IS NULL`)
-2. Delete each one and all its associations, without checking S3 for its metadata
+2. Delete each one and all its associations, without checking S3 for its
+   metadata
 3. Clean up orphaned files, chunks, and blobs
 
 ## Repository Pattern
@@ -245,18 +331,20 @@ Vaultik uses a repository pattern for database access:
 - `FileRepository` - CRUD operations for files and file metadata
 - `ChunkRepository` - CRUD operations for content chunks
 - `FileChunkRepository` - Manage file-to-chunk mappings
-- `ChunkFileRepository` - Manage chunk-to-file reverse mappings  
+- `ChunkFileRepository` - Manage chunk-to-file reverse mappings
 - `BlobRepository` - Manage blob lifecycle (creation, finalization, upload)
 - `BlobChunkRepository` - Manage blob-to-chunk associations
 - `SnapshotRepository` - Manage snapshots and their relationships
 - `UploadRepository` - Track blob upload metrics
 
 Each repository provides methods like:
+
 - `Create()` - Insert new record
 - `GetByID()` / `GetByPath()` / `GetByHash()` - Retrieve records
 - `Update()` - Update existing records
 - `Delete()` - Remove records
-- Specialized queries for each entity type (e.g., `DeleteOrphaned()`, `GetIncompleteByHostname()`)
+- Specialized queries for each entity type (e.g., `DeleteOrphaned()`,
+  `GetIncompleteByHostname()`)
 
 ## Transaction Management
 
@@ -269,25 +357,33 @@ err := repos.WithTx(ctx, func(ctx context.Context, tx *sql.Tx) error {
 ```
 
 This ensures consistency, especially important for operations like:
+
 - Creating file-chunk mappings
 - Associating chunks with blobs
 - Updating snapshot statistics
 
 ## Performance Considerations
 
-1. **Indexes**: 
-   - Primary keys are automatically indexed
-   - `idx_files_path` on `files(path)` for efficient file lookups
+1. **Indexes**:
+    - Primary keys are automatically indexed
+    - `idx_files_path` on `files(path)` for efficient file lookups
 
-2. **Prepared Statements**: All queries use prepared statements for performance and security
+2. **Prepared Statements**: All queries use prepared statements for performance
+   and security
 
-3. **Batch Operations**: Where possible, operations are batched within transactions
+3. **Batch Operations**: Where possible, operations are batched within
+   transactions
 
-4. **Write-Ahead Logging**: The local index runs in SQLite WAL mode with a 10-second busy timeout, so a read-only command such as `snapshot list` can read it while a backup writes to it. Committed rows can sit in the `-wal` file beside the index until a checkpoint, so the metadata export copies the index through SQLite (`VACUUM INTO`), not as a file
+4. **Write-Ahead Logging**: The local index runs in SQLite WAL mode with a
+   10-second busy timeout, so a read-only command such as `snapshot list` can
+   read it while a backup writes to it. Committed rows can sit in the `-wal`
+   file beside the index until a checkpoint, so the metadata export copies the
+   index through SQLite (`VACUUM INTO`), not as a file
 
 ## Data Integrity
 
-1. **Foreign Keys**: Enforced through CASCADE DELETE and application-level repository methods
+1. **Foreign Keys**: Enforced through CASCADE DELETE and application-level
+   repository methods
 2. **Unique Constraints**: Chunk hashes, file paths, and blob hashes are unique
 3. **Null Handling**: Nullable fields clearly indicate in-progress operations
-4. **Timestamp Tracking**: All major operations record timestamps for auditing
+4. **Timestamp Tracking**: All major operations record timestamps for auditing

docs/REPOSTRUCTURE.md

@@ -1,10 +1,13 @@
 # Vaultik S3 Repository Structure
 
-This document describes the structure and organization of data stored in the S3 bucket by Vaultik.
+This document describes the structure and organization of data stored in the S3
+bucket by Vaultik.
 
 ## Overview
 
-Vaultik stores all backup data in an S3-compatible object store. The repository consists of two main components, plus a marker file:
+Vaultik stores all backup data in an S3-compatible object store. The repository
+consists of two main components, plus a marker file:
+
 1. **Blobs** - The actual backup data (content-addressed, encrypted)
 2. **Metadata** - Snapshot information and manifests (partially encrypted)
 
@@ -23,118 +26,208 @@ Vaultik stores all backup data in an S3-compatible object store. The repository
         └── manifest.json.zst
 ```
 
-The metadata subdirectory is named with the **remote key**, a one-way hash of the snapshot ID, not with the human-readable snapshot ID itself. See [Remote Key Derivation](#remote-key-derivation).
+The metadata subdirectory is named with the **remote key**, a one-way hash of
+the snapshot ID, not with the human-readable snapshot ID itself. See
+[Remote Key Derivation](#remote-key-derivation).
 
 ## Marker File (`vaultik-destination.txt`)
 
-Every backup writes this file at the root before it uploads anything. It holds one fixed line of plain text and names no host, path or time. A destination without it is treated as not present while the local index holds snapshots stored there: `snapshot create` refuses to write to it, and `prune`, `snapshot purge`, `snapshot remove`, `snapshot list` and `remote nuke` behave as for a destination that cannot be listed. An unplugged volume leaves an empty directory at its mount point, and without the marker that directory would read as a destination whose snapshots are all gone. `remote nuke` deletes the marker last.
+Every backup writes this file at the root before it uploads anything. It holds
+one fixed line of plain text and names no host, path or time. While the local
+index holds snapshots stored there, a destination that answers a look-up of the
+marker with not found is treated as not present: `snapshot create` refuses to
+write to it, and `prune`, `snapshot purge`, `snapshot remove`, `snapshot list`
+and `remote nuke` behave as for a destination that cannot be listed. An
+unplugged volume leaves an empty directory at its mount point, and without the
+marker that directory would read as a destination whose snapshots are all gone.
+`remote nuke` deletes the marker last.
+
+When the look-up of the marker fails for any reason other than not found, the
+check is skipped and the command goes on. S3 refuses it on every run to
+credentials that allow only PUT, so a host with such credentials does not notice
+a destination emptied since its last backup, and its next backup would leave out
+the data its local index records as already stored. After the destination is
+emptied, run `vaultik database delete` on such a host before it backs up again.
 
 ## Blobs Directory (`blobs/`)
 
 ### Structure
+
 - **Path format**: `blobs/<first-2-chars>/<next-2-chars>/<full-hash>`
-- **Example**: `blobs/ca/fe/cafebabe1234567890abcdef1234567890abcdef1234567890abcdef12345678`
-- **Sharding**: The two-level directory structure (using the first 4 characters of the hash) prevents any single directory from containing too many objects
+- **Example**:
+  `blobs/ca/fe/cafebabe1234567890abcdef1234567890abcdef1234567890abcdef12345678`
+- **Sharding**: The two-level directory structure (using the first 4 characters
+  of the hash) prevents any single directory from containing too many objects
 
 ### Content
+
 - **What it contains**: Packed collections of content-defined chunks from files
 - **Format**: Zstandard compressed, then Age encrypted
 - **Encryption**: Always encrypted with Age using the configured recipients
-- **Naming**: Content-addressed. The blob's name is `hex(SHA256(SHA256(uncompressed blob contents)))` — the double SHA-256 of the concatenated chunk data, computed before compression and encryption, not a hash of the stored (compressed, encrypted) bytes. One consequence: only a holder of the age private key can check a stored blob's integrity, because matching a blob to its name means decrypting and decompressing it first — which is what `restore` and `verify --deep` do. Implemented in `internal/blobgen` (`DoubleSHA256`). This is the canonical description of blob naming; other documents and comments point here.
+- **Naming**: Content-addressed. The blob's name is
+  `hex(SHA256(SHA256(uncompressed blob contents)))` — the double SHA-256 of the
+  concatenated chunk data, computed before compression and encryption, not a
+  hash of the stored (compressed, encrypted) bytes. One consequence: only a
+  holder of the age private key can check a stored blob's integrity, because
+  matching a blob to its name means decrypting and decompressing it first —
+  which is what `restore` and `verify --deep` do. Implemented in
+  `internal/blobgen` (`DoubleSHA256`). This is the canonical description of blob
+  naming; other documents and comments point here.
 
 ### Why Encrypted
-Blobs contain the actual file data from backups and must be encrypted for security. The content-addressing ensures deduplication while the encryption ensures privacy.
+
+Blobs contain the actual file data from backups and must be encrypted for
+security. The content-addressing ensures deduplication while the encryption
+ensures privacy.
 
 ## Metadata Directory (`metadata/`)
 
-Each snapshot has its own subdirectory. The directory is **not** named with the human-readable snapshot ID; it is named with the remote key — a one-way hash of that ID. The human ID is never written to the destination store as a directory name (see [Remote Key Derivation](#remote-key-derivation)).
+Each snapshot has its own subdirectory. The directory is **not** named with the
+human-readable snapshot ID; it is named with the remote key — a one-way hash of
+that ID. The human ID is never written to the destination store as a directory
+name (see [Remote Key Derivation](#remote-key-derivation)).
 
 ### Snapshot ID Format
 
-The human-readable snapshot ID is used in CLI arguments, log lines, and the local database. It is not written to the destination store.
-- **Format**: `<hostname>_<snapshot-name>_<RFC3339>` (or `<hostname>_<RFC3339>` if no
-  name was specified)
+The human-readable snapshot ID is used in CLI arguments, log lines, and the
+local database. It is not written to the destination store.
+
+- **Format**: `<hostname>_<snapshot-name>_<RFC3339>` (or `<hostname>_<RFC3339>`
+  if no name was specified)
 - **Example**: `laptop_home_2024-01-15T14:30:52Z`
 - **Components**:
-  - Short hostname (everything before the first dot is stripped from the FQDN)
-  - Snapshot name from the configured `snapshots:` map (optional)
-  - RFC3339 UTC timestamp
+    - Short hostname (everything before the first dot is stripped from the FQDN)
+    - Snapshot name from the configured `snapshots:` map (optional)
+    - RFC3339 UTC timestamp
 
-This ID reveals the hostname, the configured snapshot name, and the backup time, so it is never used as the on-disk directory name — the remote key is used instead.
+This ID reveals the hostname, the configured snapshot name, and the backup time,
+so it is never used as the on-disk directory name — the remote key is used
+instead.
 
 ### Remote Key Derivation
 
-The remote key is `hex(SHA256(SHA256("vaultik|" + snapshot-id)))`: a double SHA-256 over the snapshot ID, with a `vaultik|` domain-separation prefix. The result is a 64-character hex string. The hash is not reversible, but it uses no secret: an observer who guesses a candidate hostname and snapshot name can hash it the same way and confirm whether that snapshot is present. The remote key keeps names out of a plain listing; it does not hide them from a guess. Implemented in `internal/snapshot/remotekey.go`.
+The remote key is `hex(SHA256(SHA256("vaultik|" + snapshot-id)))`: a double
+SHA-256 over the snapshot ID, with a `vaultik|` domain-separation prefix. The
+result is a 64-character hex string. The hash is not reversible, but it uses no
+secret: an observer who guesses a candidate hostname and snapshot name can hash
+it the same way and confirm whether that snapshot is present. The remote key
+keeps names out of a plain listing; it does not hide them from a guess.
+Implemented in `internal/snapshot/remotekey.go`.
 
 Worked example:
+
 - Snapshot ID: `server1_home_2025-06-01T12:00:00Z`
 - Remote key: `17f97bcde958748af076b926af59823943db59e80ce7170b40f124dfa28f64aa`
-- Directory: `metadata/17f97bcde958748af076b926af59823943db59e80ce7170b40f124dfa28f64aa/`
+- Directory:
+  `metadata/17f97bcde958748af076b926af59823943db59e80ce7170b40f124dfa28f64aa/`
 
-A plain listing of the destination store therefore shows only these hashes, not the hostname or snapshot name of any backup — but because the hash uses no secret, a guessed hostname and snapshot name can be hashed and confirmed against the listing. The same remote key is stored in the manifest's `snapshot_id` field.
+A plain listing of the destination store therefore shows only these hashes, not
+the hostname or snapshot name of any backup — but because the hash uses no
+secret, a guessed hostname and snapshot name can be hashed and confirmed against
+the listing. The same remote key is stored in the manifest's `snapshot_id`
+field.
 
 ### Files in Each Snapshot Directory
 
 #### `db.zst.age` - Encrypted Database
+
 - **What it contains**: Pruned binary SQLite database for this snapshot
 - **Format**: Binary SQLite → Zstandard compressed → Age encrypted
 - **Encryption**: Encrypted with Age
-- **Purpose**: Contains full file metadata, chunk mappings, and all relationships
-- **Why encrypted**: Contains sensitive metadata like file paths, permissions, and ownership
+- **Purpose**: Contains full file metadata, chunk mappings, and all
+  relationships
+- **Why encrypted**: Contains sensitive metadata like file paths, permissions,
+  and ownership
 
 #### `manifest.json.zst` - Unencrypted Blob Manifest
+
 - **What it contains**: JSON list of all blob hashes referenced by this snapshot
 - **Format**: JSON → Zstandard compressed (NOT encrypted)
 - **Encryption**: NOT encrypted
 - **Purpose**: Enables pruning operations without requiring decryption keys
 - **Structure**:
+
 ```json
 {
-  "snapshot_id": "17f97bcde958748af076b926af59823943db59e80ce7170b40f124dfa28f64aa",
-  "timestamp": "2025-06-01T12:00:00Z",
-  "blob_count": 42,
-  "total_compressed_size": 1048576,
-  "blobs": [
-    { "hash": "cafebabe1234567890abcdef1234567890abcdef1234567890abcdef12345678", "compressed_size": 24576 },
-    { "hash": "deadbeef1234567890abcdef1234567890abcdef1234567890abcdef12345678", "compressed_size": 32768 }
-  ]
+    "snapshot_id": "17f97bcde958748af076b926af59823943db59e80ce7170b40f124dfa28f64aa",
+    "timestamp": "2025-06-01T12:00:00Z",
+    "blob_count": 42,
+    "total_compressed_size": 1048576,
+    "blobs": [
+        {
+            "hash": "cafebabe1234567890abcdef1234567890abcdef1234567890abcdef12345678",
+            "compressed_size": 24576
+        },
+        {
+            "hash": "deadbeef1234567890abcdef1234567890abcdef1234567890abcdef12345678",
+            "compressed_size": 32768
+        }
+    ]
 }
 ```
-`snapshot_id` is the remote key (a hash), not the human ID; `timestamp` is written in the clear.
+
+`snapshot_id` is the remote key (a hash), not the human ID; `timestamp` is
+written in the clear.
 
 ### Why Manifest is Unencrypted
+
 The manifest must be readable without the private key to enable:
+
 1. **Pruning operations** - Identifying unreferenced blobs for deletion
 2. **Storage analysis** - Understanding space usage without decryption
 3. **Verification** - Checking blob existence without decryption
-4. **Cross-snapshot deduplication analysis** - Finding shared blobs between snapshots
+4. **Cross-snapshot deduplication analysis** - Finding shared blobs between
+   snapshots
 
-The manifest contains the remote key, the backup timestamp, the blob count and total compressed size, and each blob's hash and compressed size. It contains no file names, paths, or other decrypted metadata.
+The manifest contains the remote key, the backup timestamp, the blob count and
+total compressed size, and each blob's hash and compressed size. It contains no
+file names, paths, or other decrypted metadata.
 
 ## Security Considerations
 
 ### What's Encrypted
+
 - **All file content** (in blobs)
-- **All file metadata** (paths, permissions, timestamps, ownership in db.zst.age)
+- **All file metadata** (paths, permissions, timestamps, ownership in
+  db.zst.age)
 - **File-to-chunk mappings** (in db.zst.age)
 
 ### What's Not Encrypted
-- **The remote key** — directory names and the manifest `snapshot_id`, a one-way hash of the snapshot ID (see [Remote Key Derivation](#remote-key-derivation))
+
+- **The remote key** — directory names and the manifest `snapshot_id`, a one-way
+  hash of the snapshot ID (see [Remote Key Derivation](#remote-key-derivation))
 - **The backup timestamp** (in manifest.json.zst)
 - **Blob hashes and their compressed sizes** (in manifest.json.zst)
 - **Blob count and total compressed size per snapshot** (in manifest.json.zst)
 
 ### Privacy Implications
-From the unencrypted data, an observer of the destination store can determine:
-- **When each backup was taken** — not from the directory name, which is a one-way hash, but from the plaintext `timestamp` field in manifest.json.zst, which is published in the clear
-- How many blobs each snapshot references, and the total compressed size
-- The compressed size of each blob, and which blobs are shared between snapshots (deduplication patterns)
-- **Whether a guessed hostname and snapshot name are present** — the remote key is an unkeyed hash, so an observer holding candidate names can hash each one and match it against the directory listing. The human ID is never published, so it cannot be read off directly, but it can be confirmed by guessing.
 
-Together these give an observer a timing-and-size profile of every snapshot. This is an accepted, documented property of the format, not a defect: the manifest is unencrypted so that pruning can run without the private key, and the timing channel could not be closed by encrypting it anyway — object creation times and per-object sizes stay visible at the storage layer on both `s3://` and `file://` destinations regardless.
+From the unencrypted data, an observer of the destination store can determine:
+
+- **When each backup was taken** — not from the directory name, which is a
+  one-way hash, but from the plaintext `timestamp` field in manifest.json.zst,
+  which is published in the clear
+- How many blobs each snapshot references, and the total compressed size
+- The compressed size of each blob, and which blobs are shared between snapshots
+  (deduplication patterns)
+- **Whether a guessed hostname and snapshot name are present** — the remote key
+  is an unkeyed hash, so an observer holding candidate names can hash each one
+  and match it against the directory listing. The human ID is never published,
+  so it cannot be read off directly, but it can be confirmed by guessing.
+
+Together these give an observer a timing-and-size profile of every snapshot.
+This is an accepted, documented property of the format, not a defect: the
+manifest is unencrypted so that pruning can run without the private key, and the
+timing channel could not be closed by encrypting it anyway — object creation
+times and per-object sizes stay visible at the storage layer on both `s3://` and
+`file://` destinations regardless.
 
 An observer cannot determine:
-- The hostname or snapshot name of any backup by reading it off the store — the directory name and the manifest `snapshot_id` are unkeyed hashes of the human ID, so the text is never published (though a guessed name can be confirmed, as above)
+
+- The hostname or snapshot name of any backup by reading it off the store — the
+  directory name and the manifest `snapshot_id` are unkeyed hashes of the human
+  ID, so the text is never published (though a guessed name can be confirmed, as
+  above)
 - File names or paths
 - File contents
 - File permissions or ownership
@@ -143,40 +236,119 @@ An observer cannot determine:
 
 ### Accepted Risks
 
-These are known, deliberate properties of the format and the tooling, recorded so an operator can weigh them rather than discover them.
+These are known, deliberate properties of the format and the tooling, recorded
+so an operator can weigh them rather than discover them.
 
-1. **No proof of authorship.** Restore and `verify --deep` prove that data decrypts with the age private key and matches its unkeyed content hashes. They do not prove who wrote it: anyone who knows a recipient public key and can replace objects on the destination can substitute a snapshot they built. The recipient string is not stored at the destination, but a compromised backed-up host has it. Defences live on the destination side — bucket versioning or object lock, credentials for the source host that cannot delete or overwrite existing versions, and pruning from a trusted host. Note that S3 `PutObject` overwrites an existing key, so PUT permission alone is not append-only.
-2. **Compression reveals sizes.** Blobs and `db.zst.age` are zstd-compressed then age-encrypted; the manifest is compressed only. age does not pad, so an object's size is the exact compressed length of its contents. All new chunks packed into one blob share a single zstd stream (8 MiB window, 4 MiB at compression levels 1-2), and a blob is closed at `blob_size_limit` and at the end of each configured path. Because a stored chunk is never packed again, someone who can write into a backed-up file and watch blob sizes learns something only when their controlled data and a secret land in the same chunk of a file that keeps changing. Advice: back up any outsider-writable directory as its own snapshot.
-3. **Chunking uses no secret.** The FastCDC parameters are fixed and public. The default 10 MB average yields chunks between 2.5 MB and 40 MB, and any file of 2.5 MB or less is a single chunk. At the default 10 GB `blob_size_limit` a blob holds hundreds of chunks, so individual chunk lengths are not visible in the blob's size; lowering the limit toward the chunk size begins to expose them.
-4. **Decrypted data on local disk.** Several commands stage plaintext under `$TMPDIR`: `snapshot restore` writes decrypted blobs under `vaultik-blobcache-*/` (no size cap) and the decrypted metadata database at `vaultik-restore-*/snapshot.db`; `verify --deep` writes that database at `vaultik-verify-*/snapshot.db`; `snapshot create` keeps a plaintext copy of the index at `vaultik-snapshot-*/snapshot.db`. These files are created `0600` and removed on success, but a `kill -9` or a power loss leaves them behind — delete any leftover `vaultik-*` directory under `$TMPDIR` by hand. `$TMPDIR` should be trusted to the same degree as the restore target.
-5. **Store permissions differ per command.** The backed-up host needs only PUT to run `snapshot create`: it writes blobs and metadata and neither reads nor deletes them. Other commands need more — `snapshot verify`, `snapshot restore`, and `prune` list and read; `prune`, `snapshot purge`, `snapshot remove`, and `remote nuke` also delete. The recommended cron line uses `--prune`, which runs `prune` on the backed-up host, so granting that host `--prune` gives it credentials that can delete its own backups. To keep the source host to PUT only, prune from a separate trusted host instead.
-6. **Changing recipients does not re-encrypt existing data.** Deduplicated chunks and same-named blobs already on the destination stay encrypted to the recipients in force when they were written. A new snapshot that reuses them cannot be restored with a newly added recipient's key alone, because those reused objects were never encrypted to it. To make everything readable by a new key, run `vaultik database delete` and take a full backup to a fresh destination or prefix.
-7. **X25519 recipients only.** vaultik rejects age ssh and plugin recipients. Long-lived ciphertext held by a third party (the destination operator) has no fallback if X25519 is ever broken: there is no second recipient type and no post-quantum option.
+1. **No proof of authorship.** Restore and `verify --deep` prove that data
+   decrypts with the age private key and matches its unkeyed content hashes.
+   They do not prove who wrote it: anyone who knows a recipient public key and
+   can replace objects on the destination can substitute a snapshot they built.
+   The recipient string is not stored at the destination, but a compromised
+   backed-up host has it. Defences live on the destination side — bucket
+   versioning or object lock, credentials for the source host that cannot delete
+   or overwrite existing versions, and pruning from a trusted host. Note that S3
+   `PutObject` overwrites an existing key, so PUT permission alone is not
+   append-only.
+2. **Compression reveals sizes.** Blobs and `db.zst.age` are zstd-compressed
+   then age-encrypted; the manifest is compressed only. age does not pad, so an
+   object's size is the exact compressed length of its contents. All new chunks
+   packed into one blob share a single zstd stream (8 MiB window, 4 MiB at
+   compression levels 1-2), and a blob is closed at `blob_size_limit` and at the
+   end of each configured path. Because a stored chunk is never packed again,
+   someone who can write into a backed-up file and watch blob sizes learns
+   something only when their controlled data and a secret land in the same chunk
+   of a file that keeps changing. Advice: back up any outsider-writable
+   directory as its own snapshot.
+3. **Chunking uses no secret.** The FastCDC parameters are fixed and public. The
+   default 10 MB average yields chunks between 2.5 MB and 40 MB, and any file of
+   2.5 MB or less is a single chunk. At the default 10 GB `blob_size_limit` a
+   blob holds hundreds of chunks, so individual chunk lengths are not visible in
+   the blob's size; lowering the limit toward the chunk size begins to expose
+   them.
+4. **Decrypted data on local disk.** Several commands stage plaintext under
+   `$TMPDIR`: `snapshot restore` writes decrypted blobs under
+   `vaultik-blobcache-*/` (no size cap) and the decrypted metadata database at
+   `vaultik-restore-*/snapshot.db`; `verify --deep` writes that database at
+   `vaultik-verify-*/snapshot.db`; `snapshot create` keeps a plaintext copy of
+   the index at `vaultik-snapshot-*/snapshot.db`. These files are created `0600`
+   and removed on success, but a `kill -9` or a power loss leaves them behind —
+   delete any leftover `vaultik-*` directory under `$TMPDIR` by hand. `$TMPDIR`
+   should be trusted to the same degree as the restore target.
+5. **Store permissions differ per command.** The backed-up host needs only PUT
+   to run `snapshot create`: it writes blobs and metadata and neither reads nor
+   deletes them. Other commands need more — `snapshot verify`,
+   `snapshot restore`, and `prune` list and read; `prune`, `snapshot purge`,
+   `snapshot remove`, and `remote nuke` also delete. The recommended cron line
+   uses `--prune`, which runs `prune` on the backed-up host, so granting that
+   host `--prune` gives it credentials that can delete its own backups. To keep
+   the source host to PUT only, prune from a separate trusted host instead.
+6. **Changing recipients does not re-encrypt existing data.** Deduplicated
+   chunks and same-named blobs already on the destination stay encrypted to the
+   recipients in force when they were written. A new snapshot that reuses them
+   cannot be restored with a newly added recipient's key alone, because those
+   reused objects were never encrypted to it. To make everything readable by a
+   new key, run `vaultik database delete` and take a full backup to a fresh
+   destination or prefix.
+7. **X25519 recipients only.** vaultik rejects age ssh and plugin recipients.
+   Long-lived ciphertext held by a third party (the destination operator) has no
+   fallback if X25519 is ever broken: there is no second recipient type and no
+   post-quantum option.
 
 ## Consistency Guarantees
 
 1. **Blobs are immutable** - Once written, a blob is never modified
-2. **Blobs are written before metadata** - A snapshot's metadata is only written after all its blobs are successfully uploaded
-3. **Metadata is written atomically** - Both db.zst.age and manifest.json.zst are written as complete files
-4. **A snapshot is marked complete in the local DB only after its metadata is uploaded** - `finalizeSnapshotMetadata` runs `ExportSnapshotMetadata` first and records completion (`MarkSnapshotComplete`) only once the export succeeds (see the backup data flow in [ARCHITECTURE.md](../ARCHITECTURE.md)). A crash during the export therefore leaves the snapshot incomplete, so the next backup's `PruneDatabase` drops it and re-backs-up its data, rather than leaving a completed-looking row in the local index with no matching metadata on the destination store. (A crash in the brief moment after the export succeeds but before completion is recorded leaves a fully-restorable snapshot on the destination that the local index drops as incomplete on the next run; `snapshot list` then reports it honestly as remote-only, which is the safe direction: the destination copy stays restorable.)
+2. **Blobs are written before metadata** - A snapshot's metadata is only written
+   after all its blobs are successfully uploaded
+3. **Metadata is written atomically** - Both db.zst.age and manifest.json.zst
+   are written as complete files
+4. **A snapshot is marked complete in the local DB only after its metadata is
+   uploaded** - `finalizeSnapshotMetadata` runs `ExportSnapshotMetadata` first
+   and records completion (`MarkSnapshotComplete`) only once the export succeeds
+   (see the backup data flow in [ARCHITECTURE.md](ARCHITECTURE.md)). A crash
+   during the export therefore leaves the snapshot incomplete, so the next
+   backup's `PruneDatabase` drops it and re-backs-up its data, rather than
+   leaving a completed-looking row in the local index with no matching metadata
+   on the destination store. (A crash in the brief moment after the export
+   succeeds but before completion is recorded leaves a fully-restorable snapshot
+   on the destination that the local index drops as incomplete on the next run;
+   `snapshot list` then reports it honestly as remote-only, which is the safe
+   direction: the destination copy stays restorable.)
 
 ## Pruning Safety
 
 The prune operation is safe because:
-1. It keeps every blob listed in any snapshot's manifest and deletes only blobs that no manifest references
+
+1. It keeps every blob listed in any snapshot's manifest and deletes only blobs
+   that no manifest references. Under `metadata/` it deletes only a directory
+   that has no `manifest.json.zst`, whose name is a remote key, and that no
+   local snapshot record claims
 2. Manifests are unencrypted and can be read without keys
-3. If any manifest cannot be downloaded or decoded, prune deletes nothing and exits with an error, rather than treating that snapshot's blobs as unreferenced
-4. It deletes an unreferenced blob only once the blob is older than `prune_grace_period` (default `24h`). A backup uploads its blobs before the manifest that lists them, so a prune running meanwhile, on this host or another sharing the destination, leaves them as long as no backup run takes longer than the grace period. The grace period does not protect a blob a backup reuses from an earlier run that stopped before its manifest: the backup skips the upload of a blob already on the destination, so that blob keeps the time of its first upload, and a prune before the backup's manifest is written can delete it; the new snapshot then cannot be restored. `remote nuke` has no such check
+3. If any manifest cannot be downloaded or decoded, prune deletes nothing and
+   exits with an error, rather than treating that snapshot's blobs as
+   unreferenced
+4. It deletes an unreferenced blob only once the blob is older than
+   `prune_grace_period` (default `24h`), and a directory under `metadata/` with
+   no manifest only once every object in it is. A backup uploads its blobs and
+   its `db.zst.age` before its manifest, so a prune running meanwhile, on this
+   host or another sharing the destination, leaves them as long as no backup run
+   takes longer than the grace period. The grace period does not protect a blob
+   a backup reuses from an earlier run that stopped before its manifest: the
+   backup skips the upload of a blob already on the destination, so that blob
+   keeps the time of its first upload, and a prune before the backup's manifest
+   is written can delete it; the new snapshot then cannot be restored.
+   `remote nuke` has no such check
 
 ## Restoration Requirements
 
 To restore from a backup, you need:
+
 1. **The Age private key** - To decrypt blobs and database
 2. **The snapshot metadata** - Both files from the snapshot's metadata directory
 3. **All referenced blobs** - As listed in the manifest
 
 The restoration process:
+
 1. Download and decrypt the database dump to understand file structure
 2. Download and decrypt the required blobs
 3. Reconstruct files from their chunks
-4. Restore file metadata (permissions, timestamps, etc.)
+4. Restore file metadata (permissions, timestamps, etc.)

internal/cli/app.go

@@ -90,7 +90,7 @@ func setupGlobals(
 // blank line. Used both from the fx hook (for subcommand invocations) and
 // from the root cobra Run handler (for `vaultik` with no subcommand).
 func writeStartupBanner(w *ui.Writer, startTime time.Time, shortCommit string) {
-	w.Bannerf("%s %s by %s (commit %s, built on %s) starting up at %s.",
+	w.Bannerf("%s %s by %s (commit %s, commit date %s) starting up at %s.",
 		globals.Appname, globals.Version, globals.Author,
 		shortCommit, globals.CommitDate,
 		startTime.Format(time.RFC3339))

internal/cli/config.go

@@ -8,6 +8,7 @@ import (
 	"os/exec"
 	"path/filepath"
 	"reflect"
+	"runtime"
 	"slices"
 	"strconv"
 	"strings"
@@ -30,7 +31,7 @@ const configSetArgs = 2
 // parent config dirs (e.g. ~/.config) are conventionally traversable.
 const configDirMode = 0o755
 
-// configYAMLIndent matches the 2-space indentation of defaultConfigTemplate,
+// configYAMLIndent matches the 2-space indentation of the default config,
 // so `config set` writes the file back with the same indentation rather than
 // yaml.Marshal's 4-space default.
 const configYAMLIndent = 2
@@ -45,12 +46,28 @@ var (
 	errNeedNumericIndex = errors.New("key is a list; use a numeric index")
 	errIndexOutOfRange  = errors.New("index out of range")
 	errNotMapOrList     = errors.New("key is not a map or list")
+	errNoSuchSetting    = errors.New("no setting has this key")
 	errWouldNotLoad     = errors.New(
 		"vaultik would not load the config after this change, " +
 			"so the file was not changed")
 )
 
-const defaultConfigTemplate = `# vaultik configuration
+// macOS is the value of runtime.GOOS on macOS.
+const macOS = "darwin"
+
+// defaultConfigText returns the file `config init` writes on the operating
+// system goos, named as runtime.GOOS names it. Only macOS gets the apps
+// snapshot, since /Applications exists nowhere else.
+func defaultConfigText(goos string) string {
+	if goos == macOS {
+		return defaultConfigHead + appsSnapshotConfig + defaultConfigTail
+	}
+
+	return defaultConfigHead + defaultConfigTail
+}
+
+// defaultConfigHead is the default config up to the end of the home snapshot.
+const defaultConfigHead = `# vaultik configuration
 # Documentation: https://sneak.berlin/go/vaultik
 
 # ─── REQUIRED ────────────────────────────────────────────────────────────────
@@ -168,7 +185,10 @@ snapshots:
       - "/Movies/ProxyMedia"
       - "/Music/iTunes/Album Artwork"
       - "/Pictures/iPod Photo Cache"
+`
 
+// appsSnapshotConfig is the apps snapshot of the default config.
+const appsSnapshotConfig = `
   # Third-party applications. OS-provided apps live in /System/Applications
   # on modern macOS and are never in /Applications, but Apple-installed
   # App Store apps (Safari, GarageBand, iWork, iMovie) are excluded since
@@ -189,7 +209,10 @@ snapshots:
       - "/Steam.app"
       - "/VirtualBox.app"
       - "/Utilities/Adobe Installers"
+`
 
+// defaultConfigTail is the default config after the snapshots.
+const defaultConfigTail = `
 # Storage backend (pick ONE of the three forms below).
 #
 # S3-compatible:
@@ -239,13 +262,15 @@ storage_url: ""
 # Default: 3
 # compression_level: 3
 
-# How old a blob that no snapshot lists must be before prune deletes it.
-# A backup uploads its blobs before the manifest that lists them, so on a
-# destination shared between hosts or users this must be longer than the
-# longest backup run. It does not protect a blob a backup reuses from an
-# earlier run that stopped before its manifest: that blob keeps the time of
-# its first upload, so a prune can delete it.
-# Accepts: 36h, 90m, etc. 0s deletes them at once.
+# How old a blob that no snapshot lists must be before prune deletes it,
+# and how old every object in a directory under metadata/ with no manifest
+# must be before prune deletes that directory. A backup uploads its blobs
+# and its db.zst.age before its manifest, so on a destination shared
+# between hosts or users this must be longer than the longest backup run.
+# It does not protect a blob a backup reuses from an earlier run that
+# stopped before its manifest: that blob keeps the time of its first
+# upload, so a prune can delete it.
+# Accepts: 36h, 90m, etc. 0s deletes such blobs and directories at once.
 # Default: 24h
 # prune_grace_period: 24h
 
@@ -309,7 +334,8 @@ on macOS, ~/.config/ on Linux, /etc/vaultik/ as root).`,
 				return fmt.Errorf("creating config directory %s: %w", dir, err)
 			}
 
-			err = os.WriteFile(path, []byte(defaultConfigTemplate), configFileMode)
+			err = os.WriteFile(path, []byte(defaultConfigText(runtime.GOOS)),
+				configFileMode)
 			if err != nil {
 				return fmt.Errorf("writing config file: %w", err)
 			}
@@ -414,15 +440,15 @@ func newConfigSetCommand() *cobra.Command {
 		Long: `Sets a scalar config value addressed by dotted YAML path and writes
 the file back, preserving comments and formatting. Missing keys along
 the path are created: as a list when the next path element is a
-number, otherwise as a map.
+number, otherwise as a map. A key that no setting has is refused.
 
 If the config loads, a change after which it would not, such as
 compression_level 99, is refused and the file is left unchanged. A
 config that does not load, such as the one config init writes before
 storage_url is set or one with a ${ENV:...} reference to a variable
-not set here, is checked one setting at a time: only a change after
-which the changed setting cannot be read, such as one giving it the
-wrong type, is refused.
+not set here, is checked one setting at a time: a change after which
+the changed setting cannot be read, such as one giving it the wrong
+type, is refused.
 
 Examples:
   vaultik config set storage_url "file:///mnt/backups"
@@ -459,6 +485,11 @@ func writeConfigSet(out *ui.Writer, path, key, value string) error {
 
 	keys := strings.Split(key, ".")
 
+	_, ok := config.SettingType(keys)
+	if !ok {
+		return fmt.Errorf("%w: %s", errNoSuchSetting, key)
+	}
+
 	err = yamlPathSet(root, keys, value)
 	if err != nil {
 		return err
@@ -558,7 +589,7 @@ func yamlPathOnly(root *yaml.Node, keys []string) (*yaml.Node, error) {
 }
 
 // marshalConfigYAML renders a config document tree with 2-space indentation,
-// matching defaultConfigTemplate. yaml.Marshal defaults to 4 spaces, which
+// matching the default config. yaml.Marshal defaults to 4 spaces, which
 // would reindent the whole file on the first `config set` despite the promise
 // to preserve formatting.
 func marshalConfigYAML(root *yaml.Node) ([]byte, error) {
@@ -714,41 +745,11 @@ func yamlPathSet(root *yaml.Node, keys []string, value string) error {
 }
 
 // configKeyIsString reports whether the dotted key names a string in
-// config.Config, following the fields' yaml tags, as s3.access_key_id and
-// snapshots.home.exclude.0 do.
+// config.Config, as s3.access_key_id and snapshots.home.exclude.0 do.
 func configKeyIsString(keys []string) bool {
-	typ := reflect.TypeFor[config.Config]()
+	typ, ok := config.SettingType(keys)
 
-	for _, key := range keys {
-		switch {
-		case typ.Kind() == reflect.Map || typ.Kind() == reflect.Slice:
-			// The key is a snapshot name or a list index.
-			typ = typ.Elem()
-		case typ.Kind() == reflect.Struct:
-			field, ok := yamlField(typ, key)
-			if !ok {
-				return false
-			}
-
-			typ = field.Type
-		default:
-			return false
-		}
-	}
-
-	return typ.Kind() == reflect.String
-}
-
-// yamlField returns the field of struct type typ whose yaml tag names key.
-func yamlField(typ reflect.Type, key string) (reflect.StructField, bool) {
-	for field := range typ.Fields() {
-		name, _, _ := strings.Cut(field.Tag.Get("yaml"), ",")
-		if name == key {
-			return field, true
-		}
-	}
-
-	return reflect.StructField{}, false
+	return ok && typ.Kind() == reflect.String
 }
 
 // yamlSetInMapping resolves (creating if needed) the value node for the

internal/cli/config_test.go

@@ -13,14 +13,15 @@ import (
 	"sneak.berlin/go/vaultik/internal/ui"
 )
 
-// TestDefaultConfigTemplateParses ensures the init template is valid YAML
-// that unmarshals into the Config struct with the expected snapshots.
-func TestDefaultConfigTemplateParses(t *testing.T) {
+// TestDefaultConfigParsesOnMacOS ensures the config `config init` writes on
+// macOS is valid YAML that unmarshals into the Config struct with the
+// expected snapshots.
+func TestDefaultConfigParsesOnMacOS(t *testing.T) {
 	t.Parallel()
 
 	var cfg config.Config
 
-	err := yaml.Unmarshal([]byte(defaultConfigTemplate), &cfg)
+	err := yaml.Unmarshal([]byte(defaultConfigText("darwin")), &cfg)
 	if err != nil {
 		t.Fatalf("default config template is not valid YAML: %v", err)
 	}
@@ -58,6 +59,39 @@ func TestDefaultConfigTemplateParses(t *testing.T) {
 	}
 }
 
+// TestDefaultConfigOnLinux checks that the config `config init` writes on
+// Linux loads with its home snapshot and without the apps snapshot, whose
+// /Applications exists only on macOS.
+func TestDefaultConfigOnLinux(t *testing.T) {
+	t.Parallel()
+
+	path := filepath.Join(t.TempDir(), "config.yml")
+
+	err := os.WriteFile(path, []byte(defaultConfigText("linux")), configFileMode)
+	if err != nil {
+		t.Fatalf("write config: %v", err)
+	}
+
+	err = writeConfigSet(ui.NewWithColor(&bytes.Buffer{}, false),
+		path, "storage_url", "file:///mnt/backups")
+	if err != nil {
+		t.Fatalf("config set storage_url: %v", err)
+	}
+
+	cfg, err := config.Load(path)
+	if err != nil {
+		t.Fatalf("config.Load: %v", err)
+	}
+
+	if _, ok := cfg.Snapshots["home"]; !ok {
+		t.Error("expected 'home' snapshot in the Linux default config")
+	}
+
+	if _, ok := cfg.Snapshots["apps"]; ok {
+		t.Error("the Linux default config should have no 'apps' snapshot")
+	}
+}
+
 // testRecipient is a valid age public key.
 const testRecipient = "age1278m9q7dp3chsh2dcy82qk27v047zywyvtxwnj4cvt0z65jw6a7q5dqhfj"
 
@@ -71,7 +105,7 @@ func TestConfigSetRecipientOnFreshConfig(t *testing.T) {
 
 	path := filepath.Join(t.TempDir(), "config.yml")
 
-	err := os.WriteFile(path, []byte(defaultConfigTemplate), configFileMode)
+	err := os.WriteFile(path, []byte(defaultConfigText(macOS)), configFileMode)
 	if err != nil {
 		t.Fatalf("write config: %v", err)
 	}
@@ -203,6 +237,14 @@ func TestConfigSetKeepsFileThatWouldNotLoad(t *testing.T) {
 		value  string
 		reason string
 	}{
+		// Keys that no setting has, on a config that loads and on one
+		// that does not.
+		{configWithoutRecipients, "nosuchkey", "1",
+			"no setting has this key: nosuchkey"},
+		{configWithoutRecipients, "snapshots.home.exlude", "/tmp",
+			"no setting has this key: snapshots.home.exlude"},
+		{defaultConfigText(macOS), "compression_lvl", "9",
+			"no setting has this key: compression_lvl"},
 		// Index 1 of the empty list the missing key gives.
 		{configWithoutRecipients, "age_recipients.1", testRecipient,
 			"index out of range"},
@@ -220,7 +262,7 @@ func TestConfigSetKeepsFileThatWouldNotLoad(t *testing.T) {
 		{levelReference, "blob_size_limit", "1MB",
 			"blob_size_limit must be at least"},
 		// The type check on a config that does not load yet.
-		{defaultConfigTemplate, "snapshots.apps.paths", "/srv",
+		{defaultConfigText(macOS), "snapshots.apps.paths", "/srv",
 			"into []string"},
 		// The type check on a config that cannot be read here.
 		{configWithUnsetReference, "snapshots.home.paths", "/x",
@@ -380,7 +422,7 @@ func loadAfterConfigSet(t *testing.T, key, value string) *config.Config {
 
 	path := filepath.Join(t.TempDir(), "config.yml")
 
-	err := os.WriteFile(path, []byte(defaultConfigTemplate), configFileMode)
+	err := os.WriteFile(path, []byte(defaultConfigText(macOS)), configFileMode)
 	if err != nil {
 		t.Fatalf("write config: %v", err)
 	}

internal/cli/entry_banner_test.go

@@ -13,6 +13,7 @@ import (
 	"github.com/adrg/xdg"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+	"sneak.berlin/go/vaultik/internal/globals"
 )
 
 // Command words and flags used to build argument vectors below. They are
@@ -112,6 +113,35 @@ func TestBannerStillPrintedWithoutSuppressingFlag(t *testing.T) {
 	}
 }
 
+// TestBannerLabelsCommitDate checks that the banner prints the commit
+// and the commit date, each after its own label. Commit and CommitDate
+// get different values, so printing the wrong one fails.
+//
+//nolint:paralleltest // sets globals.Commit and globals.CommitDate
+func TestBannerLabelsCommitDate(t *testing.T) {
+	const (
+		commit     = "abc1234"
+		commitDate = "2026-11-09"
+	)
+
+	previousCommit, previousCommitDate := globals.Commit, globals.CommitDate
+
+	t.Cleanup(func() {
+		globals.Commit = previousCommit
+		globals.CommitDate = previousCommitDate
+	})
+
+	globals.Commit = commit
+	globals.CommitDate = commitDate
+
+	var banner bytes.Buffer
+
+	emitStartupBanner(nil, &banner)
+
+	assert.Contains(t, banner.String(),
+		"(commit "+commit+", commit date "+commitDate+")")
+}
+
 // TestBannerSuppressedInArgs covers the suppression scan directly,
 // including the flags that suppressed the banner before --json joined
 // them, so that adding --json cannot regress them.

internal/cli/entry_prune_json_test.go

@@ -134,7 +134,7 @@ func writeHermeticPruneConfig(t *testing.T, seedStale bool) string {
 		seedStaleSnapshotRecord(t, indexPath)
 
 		// While the local index holds a snapshot, prune fails on a
-		// destination without the marker a backup writes.
+		// destination that answers that it has no marker.
 		require.NoError(t, os.WriteFile(
 			filepath.Join(storeDir, "vaultik-destination.txt"), nil, 0o600))
 	}

internal/cli/entry_snapshot_create_prune_test.go

@@ -1,6 +1,7 @@
 package cli //nolint:testpackage // shares runEntry and the hermetic config helpers
 
 import (
+	"context"
 	"os"
 	"path/filepath"
 	"strings"
@@ -8,6 +9,7 @@ import (
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+	"sneak.berlin/go/vaultik/internal/database"
 )
 
 // Flags of `snapshot create` used to build argument vectors below.
@@ -87,6 +89,81 @@ func TestEntrySnapshotCreateReportsPostBackupPruneFailure(t *testing.T) {
 		"the new snapshot is on the store beside the planted one")
 }
 
+// TestEntrySnapshotCreatePruneExitsNonZeroWhenSourceIsEmpty backs up,
+// empties the source directory, as a volume that is not mounted leaves
+// its mount point, and runs `snapshot create --prune`. The command exits
+// non-zero and reports the backup as completed, not as a failed snapshot
+// creation. See https://git.eeqj.de/sneak/vaultik/issues/388.
+//
+//nolint:paralleltest // replaces os.Args, os.Stdout, os.Stderr and the xdg globals
+func TestEntrySnapshotCreatePruneExitsNonZeroWhenSourceIsEmpty(t *testing.T) {
+	configPath, storeDir := writeBackupConfig(t)
+
+	code, _, _ := runEntry(t, flagConfig, configPath, cmdSnapshot, cmdCreate)
+	require.Equal(t, 0, code)
+
+	// writeBackupConfig puts the source directory beside the config file.
+	require.NoError(t, os.Remove(
+		filepath.Join(filepath.Dir(configPath), "source", "file.txt")))
+
+	code, _, stderr := runEntry(t,
+		flagConfig, configPath, cmdSnapshot, cmdCreate, flagPrune)
+
+	assert.Equal(t, 1, code)
+	assert.Contains(t, stderr,
+		"Backup completed, but 1 source path(s) were empty")
+	assert.NotContains(t, stderr, "Snapshot creation failed")
+
+	snapshots, err := os.ReadDir(filepath.Join(storeDir, "metadata"))
+	require.NoError(t, err)
+	assert.Len(t, snapshots, 2, "the older snapshot is kept")
+}
+
+// TestEntrySnapshotCreatePruneExitsNonZeroWhenMountPointIsMissing backs
+// up, records in the local index that this backup found the source
+// directory as a mount point, and runs `snapshot create --prune`, which
+// does not find it as one. The command exits non-zero, reports the
+// backup as completed, not as a failed snapshot creation, and keeps the
+// older snapshot. See https://git.eeqj.de/sneak/vaultik/issues/395.
+//
+//nolint:paralleltest // replaces os.Args, os.Stdout, os.Stderr and the xdg globals
+func TestEntrySnapshotCreatePruneExitsNonZeroWhenMountPointIsMissing(
+	t *testing.T,
+) {
+	configPath, storeDir := writeBackupConfig(t)
+
+	code, _, _ := runEntry(t, flagConfig, configPath, cmdSnapshot, cmdCreate)
+	require.Equal(t, 0, code)
+
+	// writeBackupConfig puts the source directory and the local index
+	// beside the config file.
+	dir := filepath.Dir(configPath)
+	ctx := context.Background()
+
+	db, err := database.New(ctx, filepath.Join(dir, "index.sqlite"))
+	require.NoError(t, err)
+
+	repos := database.NewRepositories(db)
+
+	backedUp, err := repos.Snapshots.GetOnlySnapshot(ctx)
+	require.NoError(t, err)
+	require.NoError(t, repos.Snapshots.AddMountPoint(ctx, nil,
+		backedUp.ID.String(), filepath.Join(dir, "source")))
+	require.NoError(t, db.Close())
+
+	code, _, stderr := runEntry(t,
+		flagConfig, configPath, cmdSnapshot, cmdCreate, flagPrune)
+
+	assert.Equal(t, 1, code)
+	assert.Contains(t, stderr, "Backup completed, but 1 mount point(s) "+
+		"an earlier snapshot recorded were not found")
+	assert.NotContains(t, stderr, "Snapshot creation failed")
+
+	snapshots, err := os.ReadDir(filepath.Join(storeDir, "metadata"))
+	require.NoError(t, err)
+	assert.Len(t, snapshots, 2, "the older snapshot is kept")
+}
+
 // writeBackupConfig builds a hermetic config with one small file in its
 // source directory and an empty destination store directory. Returns the
 // config path and the store directory.

internal/cli/entry_snapshot_purge_test.go

@@ -42,7 +42,7 @@ func TestEntrySnapshotPurgeKeepsMetadataWhenLocalIndexDeleteFails(t *testing.T)
 	seedStaleSnapshotRecord(t, indexPath)
 
 	// While the local index holds a snapshot, purge fails on a
-	// destination without the marker a backup writes.
+	// destination that answers that it has no marker.
 	require.NoError(t, os.WriteFile(
 		filepath.Join(dir, "store", "vaultik-destination.txt"), nil, 0o600))
 

internal/cli/prune.go

@@ -13,8 +13,9 @@ func NewPruneCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "prune",
 		Short: "Tidy local database and remote storage",
-		Long: `Removes orphaned data from both the local index database and
-unreferenced blobs from the backup destination store.
+		Long: `Removes orphaned data from the local index database, and
+unreferenced blobs and directories under metadata/ with no manifest
+from the backup destination store.
 
 Local cleanup drops incomplete snapshots and any files, chunks, or
 blobs no longer referenced by a completed snapshot. Remote cleanup
@@ -26,6 +27,10 @@ another sharing the destination store, that has not yet uploaded its
 manifest. The grace period does not protect a blob such a backup
 reuses from an earlier run that stopped before its manifest: that
 blob keeps the time of its first upload, so it can be deleted.
+Remote cleanup also deletes each directory under metadata/ with no
+manifest, as a backup that stopped before its manifest leaves, once
+all its objects are older than prune_grace_period and its snapshot is
+not in the local index.
 
 Snapshot create --prune runs the same cleanup automatically; this
 command is the manual entry point for the same work (e.g. after a

internal/cli/snapshot.go

@@ -115,8 +115,10 @@ on Linux), then /etc/vaultik/config.yml.`,
 					return
 				}
 
-				if errors.Is(err, vaultik.ErrFilesUnreadable) {
-					log.Error("Backup completed with unreadable files", "error", err)
+				if errors.Is(err, vaultik.ErrFilesUnreadable) ||
+					errors.Is(err, vaultik.ErrSourcePathEmpty) ||
+					errors.Is(err, vaultik.ErrVolumeNotMounted) {
+					log.Error("Backup completed with an error", "error", err)
 					ReportErrorf("Backup completed, but %v", err)
 
 					return
@@ -131,9 +133,13 @@ on Linux), then /etc/vaultik/config.yml.`,
 	cmd.Flags().BoolVar(&opts.Cron, "cron", false,
 		"Run in cron mode (silent unless warning or error)")
 	cmd.Flags().BoolVar(&opts.Prune, "prune", false,
-		"After backup, drop older snapshots of the same name and remove "+
-			"orphaned blobs older than prune_grace_period (not after a "+
-			"backup that skipped unreadable files)")
+		"After backup, drop older snapshots of the same name, remove "+
+			"orphaned blobs older than prune_grace_period, and delete each "+
+			"directory under metadata/ with no manifest once all its "+
+			"objects are older than prune_grace_period and its snapshot is "+
+			"not in the local index (not after a backup that skipped "+
+			"unreadable files, found a configured path empty, or did not "+
+			"find a mount point an earlier snapshot found)")
 	cmd.Flags().StringVar(&opts.KeepNewerThan, "keep-newer-than", "",
 		"With --prune: keep snapshots newer than this duration "+
 			"(e.g. 30d, 4w, 6mo, 1y; m is minutes, mo is months) "+

internal/cli/version.go

@@ -37,13 +37,13 @@ func writeVersion(out *ui.Writer) {
 	w := out.Out()
 
 	_, _ = fmt.Fprintf(w, "vaultik %s\n", globals.Version)
-	_, _ = fmt.Fprintf(w, "  commit:     %s\n", globals.Commit)
-	_, _ = fmt.Fprintf(w, "  build date: %s\n", globals.CommitDate)
-	_, _ = fmt.Fprintf(w, "  go:         %s\n", runtime.Version())
-	_, _ = fmt.Fprintf(w, "  os/arch:    %s/%s\n", runtime.GOOS, runtime.GOARCH)
-	_, _ = fmt.Fprintf(w, "  author:     %s\n", globals.Author)
-	_, _ = fmt.Fprintf(w, "  homepage:   %s\n", globals.Homepage)
-	_, _ = fmt.Fprintf(w, "  license:    %s\n", globals.License)
+	_, _ = fmt.Fprintf(w, "  commit:      %s\n", globals.Commit)
+	_, _ = fmt.Fprintf(w, "  commit date: %s\n", globals.CommitDate)
+	_, _ = fmt.Fprintf(w, "  go:          %s\n", runtime.Version())
+	_, _ = fmt.Fprintf(w, "  os/arch:     %s/%s\n", runtime.GOOS, runtime.GOARCH)
+	_, _ = fmt.Fprintf(w, "  author:      %s\n", globals.Author)
+	_, _ = fmt.Fprintf(w, "  homepage:    %s\n", globals.Homepage)
+	_, _ = fmt.Fprintf(w, "  license:     %s\n", globals.License)
 
 	if globals.IsDevVersion(globals.Version) {
 		_, _ = fmt.Fprintln(w)

internal/cli/version_test.go

@@ -2,6 +2,7 @@ package cli_test
 
 import (
 	"bytes"
+	"runtime"
 	"strings"
 	"testing"
 
@@ -49,6 +50,42 @@ func TestVersionCommandReportsBuildVersion(t *testing.T) {
 	}
 }
 
+// TestVersionCommandReportLines checks the label, padding and value of
+// every line of the report. Commit and CommitDate get different values,
+// so a line that prints the wrong one fails.
+//
+//nolint:paralleltest // sets globals.Commit and globals.CommitDate
+func TestVersionCommandReportLines(t *testing.T) {
+	const (
+		commit     = "abc1234"
+		commitDate = "2026-11-09"
+	)
+
+	previousCommit, previousCommitDate := globals.Commit, globals.CommitDate
+
+	t.Cleanup(func() {
+		globals.Commit = previousCommit
+		globals.CommitDate = previousCommitDate
+	})
+
+	globals.Commit = commit
+	globals.CommitDate = commitDate
+
+	want := "vaultik " + globals.Version + "\n" +
+		"  commit:      " + commit + "\n" +
+		"  commit date: " + commitDate + "\n" +
+		"  go:          " + runtime.Version() + "\n" +
+		"  os/arch:     " + runtime.GOOS + "/" + runtime.GOARCH + "\n" +
+		"  author:      " + globals.Author + "\n" +
+		"  homepage:    " + globals.Homepage + "\n" +
+		"  license:     " + globals.License + "\n"
+
+	out := runVersionCommand(t)
+	if !strings.HasPrefix(out, want) {
+		t.Errorf("report:\n%s\nwant it to start with:\n%s", out, want)
+	}
+}
+
 // TestVersionCommandFlagsDevelopmentBuild is the regression test for
 // the thing this command exists to prevent: a build that is not a
 // release must say so. The notice used to be gated on the version

internal/config/config.go

@@ -9,6 +9,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"reflect"
 	"sort"
 	"strings"
 	"time"
@@ -56,7 +57,7 @@ var (
 	errRecipientNotX25519 = errors.New(
 		"not a valid recipient; only X25519 age1... public keys are supported")
 	errNoSnapshots = errors.New(
-		"at least one snapshot must be configured (see config.example.yml)")
+		"at least one snapshot must be configured (see configs/config.example.yml)")
 	errSnapshotNoPaths   = errors.New("snapshot must have at least one path")
 	errChunkSizeTooSmall = errors.New("chunk_size must be at least 1MB")
 	errBlobSizeTooSmall  = errors.New(
@@ -192,10 +193,12 @@ type Config struct {
 	CompressionLevel int                       `yaml:"compression_level"`
 
 	// PruneGracePeriod is how old a blob no manifest lists must be before
-	// a prune deletes it. A backup lists its blobs in a manifest only
-	// once it has uploaded them all, so a younger one may belong to a
-	// backup still running, on this host or another sharing the
-	// destination store.
+	// a prune deletes it, and how old every object in a directory under
+	// metadata/ with no manifest must be before a prune deletes that
+	// directory. A backup writes its manifest only once it has uploaded
+	// all its blobs and its db.zst.age, so a younger blob or directory may
+	// belong to a backup still running, on this host or another sharing
+	// the destination store.
 	PruneGracePeriod time.Duration `yaml:"prune_grace_period"`
 
 	// StorageURL specifies the storage backend using a URL format.
@@ -284,9 +287,24 @@ func Load(path string) (*Config, error) {
 }
 
 // Parse reads YAML config data as Load does, without validating it. It
-// applies default values for optional fields, fills in ${...} references
-// using smartconfig, and expands ~ in paths.
+// refuses a key that no setting has, applies default values for optional
+// fields, fills in ${...} references using smartconfig, and expands ~ in
+// paths.
 func Parse(data []byte) (*Config, error) {
+	// smartconfig drops line numbers, so keys are checked in the data as
+	// written.
+	var root yaml.Node
+
+	err := yaml.Unmarshal(data, &root)
+	if err != nil {
+		return nil, fmt.Errorf("failed to parse config: %w", err)
+	}
+
+	err = checkKeys(&root, reflect.TypeFor[Config](), "")
+	if err != nil {
+		return nil, err
+	}
+
 	// Load config using smartconfig for interpolation
 	sc, err := smartconfig.NewFromReader(bytes.NewReader(data))
 	if err != nil {

internal/config/config_test.go

@@ -90,12 +90,12 @@ func TestConfigLoad(t *testing.T) {
 }
 
 // TestExampleConfigIsScrubbedAndLoads checks that the shipped
-// config.example.yml carries only neutral placeholders (no real credentials,
-// private addresses, or internal host names) and still parses.
+// configs/config.example.yml carries only neutral placeholders (no real
+// credentials, private addresses, or internal host names) and still parses.
 func TestExampleConfigIsScrubbedAndLoads(t *testing.T) {
 	t.Parallel()
 
-	examplePath := filepath.Join("..", "..", "config.example.yml")
+	examplePath := filepath.Join("..", "..", "configs", "config.example.yml")
 
 	cfg, err := Load(examplePath)
 	if err != nil {
@@ -361,7 +361,7 @@ func TestDocumentedSizeDefaults(t *testing.T) {
 }
 
 // TestDocumentedSizeExamples checks the 1MB minimum chunk_size and that
-// every size the README, config.example.yml and the config init template
+// every size the README, configs/config.example.yml and the config init template
 // list as an example is accepted.
 func TestDocumentedSizeExamples(t *testing.T) {
 	t.Parallel()
@@ -415,7 +415,8 @@ func TestDocumentedSizeExamples(t *testing.T) {
 
 // TestValidatePruneGracePeriod checks that a negative prune_grace_period
 // is refused rather than acting like 0s, which deletes unreferenced blobs
-// at once, and that 0s and the documented examples are accepted.
+// and directories under metadata/ with no manifest at once, and that 0s
+// and the documented examples are accepted.
 func TestValidatePruneGracePeriod(t *testing.T) {
 	t.Parallel()
 

internal/config/keys.go

@@ -0,0 +1,149 @@
+package config
+
+import (
+	"errors"
+	"fmt"
+	"reflect"
+	"strconv"
+	"strings"
+
+	"gopkg.in/yaml.v3"
+)
+
+// yamlMergeTag is the tag YAML gives a merge key (<<), which adds the keys
+// of the map it names to the map it sits in.
+const yamlMergeTag = "!!merge"
+
+var errUnknownKey = errors.New("unknown config key")
+
+// SettingType returns the type of the setting that the dotted key names in
+// Config, following the fields' yaml tags, as for s3.bucket or
+// snapshots.home.exclude.0. A snapshot name or a list index may be any
+// word. It returns false when no setting has that key.
+func SettingType(keys []string) (reflect.Type, bool) {
+	typ := reflect.TypeFor[Config]()
+
+	for _, key := range keys {
+		switch {
+		case typ.Kind() == reflect.Map || typ.Kind() == reflect.Slice:
+			typ = typ.Elem()
+		case typ.Kind() == reflect.Struct:
+			field, ok := yamlField(typ, key)
+			if !ok {
+				return nil, false
+			}
+
+			typ = field.Type
+		default:
+			return nil, false
+		}
+	}
+
+	return typ, true
+}
+
+// yamlField returns the field of struct type typ whose yaml tag names key.
+func yamlField(typ reflect.Type, key string) (reflect.StructField, bool) {
+	for field := range typ.Fields() {
+		name, _, _ := strings.Cut(field.Tag.Get("yaml"), ",")
+		if name == key && name != "-" {
+			return field, true
+		}
+	}
+
+	return reflect.StructField{}, false
+}
+
+// checkKeys returns an error naming the first key in node, a parsed config
+// file or part of one at the dotted path, that no setting in typ has. The
+// error gives the key's line in the file. A value of the wrong type is left
+// for the YAML decoder to report.
+func checkKeys(node *yaml.Node, typ reflect.Type, path string) error {
+	switch node.Kind {
+	case yaml.DocumentNode:
+		for _, child := range node.Content {
+			err := checkKeys(child, typ, path)
+			if err != nil {
+				return err
+			}
+		}
+	case yaml.AliasNode:
+		return checkKeys(node.Alias, typ, path)
+	case yaml.SequenceNode:
+		if typ.Kind() != reflect.Slice {
+			return nil
+		}
+
+		for i, child := range node.Content {
+			err := checkKeys(child, typ.Elem(), joinKey(path, strconv.Itoa(i)))
+			if err != nil {
+				return err
+			}
+		}
+	case yaml.MappingNode:
+		return checkMappingKeys(node, typ, path)
+	case yaml.ScalarNode:
+		// A scalar has no keys.
+	}
+
+	return nil
+}
+
+// checkMappingKeys is checkKeys for a map in the file.
+func checkMappingKeys(node *yaml.Node, typ reflect.Type, path string) error {
+	for i := 0; i+1 < len(node.Content); i += 2 {
+		key, value := node.Content[i], node.Content[i+1]
+
+		if key.Tag == yamlMergeTag {
+			// The value is one map or a list of maps.
+			merged := []*yaml.Node{value}
+			if value.Kind == yaml.SequenceNode {
+				merged = value.Content
+			}
+
+			for _, m := range merged {
+				err := checkKeys(m, typ, path)
+				if err != nil {
+					return err
+				}
+			}
+
+			continue
+		}
+
+		keyPath := joinKey(path, key.Value)
+
+		var valueType reflect.Type
+
+		switch {
+		case typ.Kind() == reflect.Map:
+			valueType = typ.Elem()
+		case typ.Kind() == reflect.Struct:
+			field, ok := yamlField(typ, key.Value)
+			if !ok {
+				return fmt.Errorf("%w %q on line %d",
+					errUnknownKey, keyPath, key.Line)
+			}
+
+			valueType = field.Type
+		default:
+			return nil
+		}
+
+		err := checkKeys(value, valueType, keyPath)
+		if err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+// joinKey appends key to the dotted path.
+func joinKey(path, key string) string {
+	if path == "" {
+		return key
+	}
+
+	return path + "." + key
+}

internal/config/keys_test.go

@@ -0,0 +1,86 @@
+package config //nolint:testpackage // checks the unexported errUnknownKey
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// keysTestConfig loads; each case below adds one line to it.
+const keysTestConfig = "storage_url: file:///tmp/vaultik-test-storage\n" +
+	"s3:\n" +
+	"  region: us-east-1\n" +
+	"snapshots:\n" +
+	"  test:\n" +
+	"    paths: [/tmp/vaultik-test-source]\n"
+
+// TestParseRefusesUnknownKey checks that a key no setting has, at any
+// depth, fails the parse with an error naming the key and its line.
+func TestParseRefusesUnknownKey(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		yaml string
+		want string
+	}{
+		{"top level", keysTestConfig + "compression_lvl: 9\n",
+			`unknown config key "compression_lvl" on line 7`},
+		{"in a snapshot", keysTestConfig + "    exlude: [/tmp/cache]\n",
+			`unknown config key "snapshots.test.exlude" on line 7`},
+		{"in s3", strings.Replace(keysTestConfig, "  region:",
+			"  bukcet: b\n  region:", 1),
+			`unknown config key "s3.bukcet" on line 3`},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			_, err := Parse([]byte(tt.yaml))
+			if !errors.Is(err, errUnknownKey) {
+				t.Fatalf("Parse() error = %v, want errUnknownKey", err)
+			}
+
+			if err.Error() != tt.want {
+				t.Errorf("Parse() error = %q, want %q", err.Error(), tt.want)
+			}
+		})
+	}
+}
+
+// TestParseAcceptsKnownKeys checks that a config with a ${...} reference
+// and a YAML merge key (<<) still parses.
+func TestParseAcceptsKnownKeys(t *testing.T) {
+	t.Parallel()
+
+	levelPath := filepath.Join(t.TempDir(), "level")
+
+	err := os.WriteFile(levelPath, []byte("9"), 0o600)
+	if err != nil {
+		t.Fatalf("write level: %v", err)
+	}
+
+	data := strings.Replace(keysTestConfig, "  test:", "  test: &test", 1) +
+		"  other:\n" +
+		"    <<: *test\n" +
+		"    exclude: [/tmp/vaultik-test-source/cache]\n" +
+		"compression_level: ${FILE:" + levelPath + "}\n"
+
+	cfg, err := Parse([]byte(data))
+	if err != nil {
+		t.Fatalf("Parse() unexpected error: %v", err)
+	}
+
+	if cfg.CompressionLevel != 9 {
+		t.Errorf("compression_level = %d, want 9", cfg.CompressionLevel)
+	}
+
+	other := cfg.Snapshots["other"]
+	if len(other.Paths) != 1 || len(other.Exclude) != 1 {
+		t.Errorf("snapshot other = %+v, want the paths of test and one exclude",
+			other)
+	}
+}

internal/database/schema/001.sql

@@ -123,6 +123,16 @@ CREATE TABLE IF NOT EXISTS snapshot_blobs (
 -- Index for efficient blob lookups (used in orphan detection)
 CREATE INDEX IF NOT EXISTS idx_snapshot_blobs_blob_id ON snapshot_blobs(blob_id);
 
+-- Snapshot mount points table: the directories at or below a configured
+-- path that the snapshot's backup found on a different filesystem from
+-- their parent directory, as a mount point is, and found an entry in
+CREATE TABLE IF NOT EXISTS snapshot_mount_points (
+    snapshot_id TEXT NOT NULL,
+    path TEXT NOT NULL,
+    PRIMARY KEY (snapshot_id, path),
+    FOREIGN KEY (snapshot_id) REFERENCES snapshots(id) ON DELETE CASCADE
+);
+
 -- Uploads table: tracks blob upload metrics
 CREATE TABLE IF NOT EXISTS uploads (
     blob_hash TEXT PRIMARY KEY,

internal/database/snapshots.go

@@ -24,7 +24,8 @@ var (
 )
 
 // SnapshotRepository provides access to the snapshots table and its
-// snapshot_files / snapshot_blobs association tables.
+// snapshot_files / snapshot_blobs association tables, and to the mount
+// points each snapshot's backup found (snapshot_mount_points).
 type SnapshotRepository struct {
 	db *DB
 }
@@ -494,33 +495,63 @@ func (r *SnapshotRepository) GetBlobHashes(
 	ctx context.Context, snapshotID string,
 ) ([]string, error) {
 	query := `
-		SELECT sb.blob_hash 
+		SELECT sb.blob_hash
 		FROM snapshot_blobs sb
 		WHERE sb.snapshot_id = ?
 		ORDER BY sb.blob_hash
 	`
 
-	rows, err := r.db.conn.QueryContext(ctx, query, snapshotID)
+	blobs, err := r.queryStrings(ctx, query, snapshotID)
 	if err != nil {
 		return nil, fmt.Errorf("querying blob hashes: %w", err)
 	}
 
-	defer func() { _ = rows.Close() }()
+	return blobs, nil
+}
 
-	var blobs []string
+// AddMountPoint records dir as a directory that the backup of a snapshot
+// found on a different filesystem from its parent directory, as a mount
+// point is, using tx when non-nil.
+func (r *SnapshotRepository) AddMountPoint(
+	ctx context.Context, tx *sql.Tx, snapshotID string, dir string,
+) error {
+	query := `
+		INSERT OR IGNORE INTO snapshot_mount_points (snapshot_id, path)
+		VALUES (?, ?)
+	`
 
-	for rows.Next() {
-		var blobHash string
-
-		err := rows.Scan(&blobHash)
-		if err != nil {
-			return nil, fmt.Errorf("scanning blob hash: %w", err)
-		}
-
-		blobs = append(blobs, blobHash)
+	var err error
+	if tx != nil {
+		_, err = tx.ExecContext(ctx, query, snapshotID, dir)
+	} else {
+		_, err = r.db.ExecWithLog(ctx, query, snapshotID, dir)
 	}
 
-	return blobs, rows.Err()
+	if err != nil {
+		return fmt.Errorf("adding mount point to snapshot: %w", err)
+	}
+
+	return nil
+}
+
+// GetMountPoints returns the directories AddMountPoint recorded for a
+// snapshot, sorted.
+func (r *SnapshotRepository) GetMountPoints(
+	ctx context.Context, snapshotID string,
+) ([]string, error) {
+	query := `
+		SELECT path
+		FROM snapshot_mount_points
+		WHERE snapshot_id = ?
+		ORDER BY path
+	`
+
+	dirs, err := r.queryStrings(ctx, query, snapshotID)
+	if err != nil {
+		return nil, fmt.Errorf("querying mount points: %w", err)
+	}
+
+	return dirs, nil
 }
 
 // GetSnapshotTotalCompressedSize returns the total compressed size of all
@@ -709,6 +740,34 @@ func (r *SnapshotRepository) DeleteSnapshotUploads(
 	return nil
 }
 
+// queryStrings runs query, which selects one text column, and returns
+// its values in the order of the rows.
+func (r *SnapshotRepository) queryStrings(
+	ctx context.Context, query string, args ...any,
+) ([]string, error) {
+	rows, err := r.db.conn.QueryContext(ctx, query, args...)
+	if err != nil {
+		return nil, err
+	}
+
+	defer func() { _ = rows.Close() }()
+
+	var values []string
+
+	for rows.Next() {
+		var value string
+
+		err := rows.Scan(&value)
+		if err != nil {
+			return nil, err
+		}
+
+		values = append(values, value)
+	}
+
+	return values, rows.Err()
+}
+
 // extendedCompressionRatio computes the compression ratio for a snapshot
 // from its stored blob_size and the given uncompressed size. Returns 1.0
 // when the uncompressed size is zero.

internal/database/snapshots_test.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 	"math"
+	"slices"
 	"testing"
 	"time"
 
@@ -422,3 +423,52 @@ func TestSnapshotRepositoryDuplicate(t *testing.T) {
 		t.Error("expected error for duplicate snapshot")
 	}
 }
+
+// Deleting a snapshot from the local index deletes the mount points its
+// backup recorded, and no other snapshot's. See
+// https://git.eeqj.de/sneak/vaultik/issues/395.
+func TestSnapshotRepositoryDeleteRemovesMountPoints(t *testing.T) {
+	t.Parallel()
+
+	db, cleanup := setupTestDB(t)
+	defer cleanup()
+
+	ctx := context.Background()
+	repo := database.NewSnapshotRepository(db)
+
+	for _, id := range []types.SnapshotID{"kept", "deleted"} {
+		err := repo.Create(ctx, nil, &database.Snapshot{
+			ID:             id,
+			Hostname:       testHostname,
+			VaultikVersion: testVersion,
+			StartedAt:      time.Now().Truncate(time.Second),
+		})
+		if err != nil {
+			t.Fatalf("failed to create snapshot: %v", err)
+		}
+
+		err = repo.AddMountPoint(ctx, nil, id.String(), "/data/nas")
+		if err != nil {
+			t.Fatalf("failed to add mount point: %v", err)
+		}
+	}
+
+	err := repo.Delete(ctx, "deleted")
+	if err != nil {
+		t.Fatalf("failed to delete snapshot: %v", err)
+	}
+
+	for id, want := range map[string][]string{
+		"kept":    {"/data/nas"},
+		"deleted": nil,
+	} {
+		got, err := repo.GetMountPoints(ctx, id)
+		if err != nil {
+			t.Fatalf("failed to read mount points: %v", err)
+		}
+
+		if !slices.Equal(got, want) {
+			t.Errorf("mount points of %s: got %v, want %v", id, got, want)
+		}
+	}
+}

internal/snapshot/device_number_test.go

@@ -0,0 +1,40 @@
+//nolint:testpackage // exercises the unexported deviceNumberFromStat
+package snapshot
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// The device number a real backup reads is the same for a directory and
+// a file in it, and differs between the temp directory and /dev.
+// Without it no mount point is ever found. See
+// https://git.eeqj.de/sneak/vaultik/issues/395.
+func TestDeviceNumberFromStat(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	file := filepath.Join(dir, "file.txt")
+	require.NoError(t, os.WriteFile(file, nil, 0o600))
+
+	deviceOf := func(path string) uint64 {
+		t.Helper()
+
+		info, err := os.Stat(path)
+		require.NoError(t, err)
+
+		device, ok := deviceNumberFromStat(info)
+		require.True(t, ok, "no device number read for %s", path)
+
+		return device
+	}
+
+	assert.Equal(t, deviceOf(dir), deviceOf(file))
+
+	// /dev is a different filesystem from the temp dir on Linux, macOS and in Docker.
+	assert.NotEqual(t, deviceOf(dir), deviceOf("/dev"))
+}

internal/snapshot/module.go

@@ -1,6 +1,8 @@
 package snapshot
 
 import (
+	"os"
+
 	"github.com/spf13/afero"
 	"go.uber.org/fx"
 	"sneak.berlin/go/vaultik/internal/config"
@@ -19,6 +21,9 @@ type ScannerParams struct {
 	// PreviousSnapshotID is the most recent completed snapshot of the
 	// same name, "" for none.
 	PreviousSnapshotID string
+	// DeviceNumber is ScannerConfig.DeviceNumber; nil reads it from the
+	// file's stat.
+	DeviceNumber func(info os.FileInfo) (uint64, bool)
 }
 
 // Module exports backup functionality as an fx module.
@@ -59,6 +64,7 @@ func provideScannerFactory(
 			Exclude:            excludes,
 			SkipErrors:         params.SkipErrors,
 			PreviousSnapshotID: params.PreviousSnapshotID,
+			DeviceNumber:       params.DeviceNumber,
 		})
 	}
 }

internal/snapshot/mount_point_test.go

@@ -0,0 +1,245 @@
+package snapshot_test
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"slices"
+	"strings"
+	"syscall"
+	"testing"
+
+	"github.com/spf13/afero"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"sneak.berlin/go/vaultik/internal/database"
+	"sneak.berlin/go/vaultik/internal/snapshot"
+)
+
+// A scan records with the snapshot each directory on a different device
+// from its parent directory that the walk found an entry in, as a mount
+// point is, the scanned path included. A filesystem that gives no device
+// numbers, as the in-memory one, records none. See
+// https://git.eeqj.de/sneak/vaultik/issues/395.
+func TestScanRecordsMountPoints(t *testing.T) {
+	t.Parallel()
+
+	const (
+		scannedPath = "/data/source"
+		snapshotID  = "mount-points"
+	)
+
+	tests := []struct {
+		name string
+		// onVolume names the directories on the volume's device; every
+		// other directory is on another one. nil leaves the device
+		// numbers to the in-memory filesystem, which has none.
+		onVolume []string
+		want     []string
+	}{
+		{
+			name:     "volume below the scanned path",
+			onVolume: []string{"nas"},
+			want:     []string{scannedPath + "/nas"},
+		},
+		{
+			name:     "volume at the scanned path",
+			onVolume: []string{"source", "nas"},
+			want:     []string{scannedPath},
+		},
+		{name: "no device numbers", want: nil},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			ctx := context.Background()
+			fs := afero.NewMemMapFs()
+
+			for _, path := range []string{
+				scannedPath + "/notes.txt", scannedPath + "/nas/a.txt",
+			} {
+				require.NoError(t, fs.MkdirAll(filepath.Dir(path), 0o755))
+				require.NoError(t, afero.WriteFile(fs, path, []byte(path), 0o644))
+			}
+
+			db, err := database.NewTestDB()
+			require.NoError(t, err)
+			t.Cleanup(func() { _ = db.Close() })
+
+			repos := database.NewRepositories(db)
+			createTestSnapshotRecord(ctx, t, repos, snapshotID)
+
+			cfg := snapshot.ScannerConfig{
+				FS:               fs,
+				ChunkSize:        int64(1024 * 16),
+				Repositories:     repos,
+				MaxBlobSize:      int64(1024 * 1024),
+				CompressionLevel: 3,
+				AgeRecipients:    []string{testAgePublicKey},
+			}
+			if tt.onVolume != nil {
+				cfg.DeviceNumber = func(info os.FileInfo) (uint64, bool) {
+					if slices.Contains(tt.onVolume, info.Name()) {
+						return 2, true
+					}
+
+					return 1, true
+				}
+			}
+
+			_, err = snapshot.NewScanner(cfg).Scan(ctx, scannedPath, snapshotID)
+			require.NoError(t, err)
+
+			got, err := repos.Snapshots.GetMountPoints(ctx, snapshotID)
+			require.NoError(t, err)
+			assert.Equal(t, tt.want, got)
+		})
+	}
+}
+
+// automountFs is an in-memory filesystem with a volume at mountPoint
+// that is mounted on first access: opening mountPoint to list it mounts
+// the volume or, if it cannot be mounted, fails with "no such file or
+// directory", as with the autofs daemon. Stat records the device an
+// entry is on at that moment, as a real stat does: unmountedDevice for
+// mountPoint until the volume is mounted; the volume's, 2, for
+// mountPoint once it is and for everything in it; 1 for everything else.
+type automountFs struct {
+	afero.Fs
+
+	mountPoint      string
+	unmountedDevice uint64
+	canMount        bool
+	mounted         bool
+}
+
+//nolint:ireturn // afero.Fs.Open is defined to return the interface.
+func (fs *automountFs) Open(name string) (afero.File, error) {
+	if name == fs.mountPoint && !fs.canMount {
+		return nil, &os.PathError{Op: "open", Path: name, Err: syscall.ENOENT}
+	}
+
+	if name == fs.mountPoint {
+		fs.mounted = true
+	}
+
+	return fs.Fs.Open(name)
+}
+
+func (fs *automountFs) Stat(name string) (os.FileInfo, error) {
+	info, err := fs.Fs.Stat(name)
+	if err != nil {
+		return nil, err
+	}
+
+	device := uint64(1)
+
+	switch {
+	case name == fs.mountPoint && !fs.mounted:
+		device = fs.unmountedDevice
+	case name == fs.mountPoint || strings.HasPrefix(name, fs.mountPoint+"/"):
+		device = 2
+	}
+
+	return statWithDevice{FileInfo: info, device: device}, nil
+}
+
+// statWithDevice is an entry automountFs.Stat looked up, with the device
+// it was on then.
+type statWithDevice struct {
+	os.FileInfo
+
+	device uint64
+}
+
+// deviceAtLookup returns the device automountFs.Stat recorded for info.
+func deviceAtLookup(info os.FileInfo) (uint64, bool) {
+	stat, ok := info.(statWithDevice)
+
+	return stat.device, ok
+}
+
+// A volume mounted on first access is mounted when the walk lists its
+// mount point. Until then the mount point is on the automounter's own
+// device (a systemd automount) or on its parent's (an autofs map that
+// shows its mount points before mounting them). Either way only the
+// mount point is recorded, by the backup that mounts the volume and by a
+// later one that finds it mounted. Listing an automount point whose
+// volume cannot be mounted fails; it is not recorded, because the walk
+// finds no entry in it. See https://git.eeqj.de/sneak/vaultik/issues/395.
+func TestScanRecordsOnlyTheMountPointOfAnAutomountedVolume(t *testing.T) {
+	t.Parallel()
+
+	const scannedPath = "/data/source"
+
+	mountPoint := scannedPath + "/nas"
+
+	tests := []struct {
+		name            string
+		unmountedDevice uint64
+		canMount        bool
+		want            []string
+	}{
+		{
+			name:            "on the automounter's device until listed",
+			unmountedDevice: 3, canMount: true, want: []string{mountPoint},
+		},
+		{
+			name:            "on its parent's device until listed",
+			unmountedDevice: 1, canMount: true, want: []string{mountPoint},
+		},
+		{
+			name:            "volume that cannot be mounted",
+			unmountedDevice: 1, canMount: false, want: nil,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			ctx := context.Background()
+			fs := &automountFs{
+				Fs: afero.NewMemMapFs(), mountPoint: mountPoint,
+				unmountedDevice: tt.unmountedDevice, canMount: tt.canMount,
+			}
+
+			require.NoError(t, fs.MkdirAll(mountPoint+"/photos", 0o755))
+
+			for _, path := range []string{
+				scannedPath + "/notes.txt", mountPoint + "/photos/a.jpg",
+			} {
+				require.NoError(t, afero.WriteFile(fs, path, []byte(path), 0o644))
+			}
+
+			db, err := database.NewTestDB()
+			require.NoError(t, err)
+			t.Cleanup(func() { _ = db.Close() })
+
+			repos := database.NewRepositories(db)
+
+			for _, snapshotID := range []string{"first", "later"} {
+				createTestSnapshotRecord(ctx, t, repos, snapshotID)
+
+				scanner := snapshot.NewScanner(snapshot.ScannerConfig{
+					FS:               fs,
+					ChunkSize:        int64(1024 * 16),
+					Repositories:     repos,
+					MaxBlobSize:      int64(1024 * 1024),
+					CompressionLevel: 3,
+					AgeRecipients:    []string{testAgePublicKey},
+					DeviceNumber:     deviceAtLookup,
+				})
+
+				_, err = scanner.Scan(ctx, scannedPath, snapshotID)
+				require.NoError(t, err)
+
+				got, err := repos.Snapshots.GetMountPoints(ctx, snapshotID)
+				require.NoError(t, err)
+				assert.Equal(t, tt.want, got, "mount points of the %s backup", snapshotID)
+			}
+		})
+	}
+}

internal/snapshot/scanner.go

@@ -73,6 +73,9 @@ type Scanner struct {
 	skipErrors bool
 	// ui is the user-facing output; never nil (defaults to a discarding writer).
 	ui *ui.Writer
+	// deviceNumber returns the number of the device that holds a file;
+	// never nil (defaults to deviceNumberFromStat).
+	deviceNumber func(info os.FileInfo) (uint64, bool)
 
 	// In-memory cache of known chunk hashes for fast existence checks
 	knownChunks   map[string]struct{}
@@ -136,6 +139,10 @@ type ScannerConfig struct {
 	// PreviousSnapshotID is the most recent completed snapshot of the
 	// same name, "" for none.
 	PreviousSnapshotID string
+	// DeviceNumber returns the number of the device that holds a file,
+	// and false when there is none to read. nil reads it from the file's
+	// stat; tests replace it, since the in-memory test filesystem has none.
+	DeviceNumber func(info os.FileInfo) (uint64, bool)
 }
 
 // ScanResult contains the results of a scan operation. Files and bytes
@@ -168,6 +175,12 @@ type ScanResult struct {
 	// skipped because it could not be read or listed; the rest are files
 	// removed after the walk listed them.
 	FilesUnreadable int
+
+	// EntriesFound counts the entries the walk found and could look up
+	// that no exclude pattern matches, leaving out the scanned path
+	// itself when it is a directory. It is zero for an empty directory,
+	// such as the mount point of a volume that is not mounted.
+	EntriesFound int
 }
 
 // NewScanner creates a new scanner instance
@@ -208,6 +221,11 @@ func NewScanner(cfg ScannerConfig) *Scanner {
 		uiw = ui.NewWithColor(io.Discard, false)
 	}
 
+	deviceNumber := cfg.DeviceNumber
+	if deviceNumber == nil {
+		deviceNumber = deviceNumberFromStat
+	}
+
 	return &Scanner{
 		fs:                 cfg.FS,
 		chunker:            chunker.NewChunker(cfg.ChunkSize),
@@ -223,6 +241,7 @@ func NewScanner(cfg ScannerConfig) *Scanner {
 		skipErrors:         cfg.SkipErrors,
 		previousSnapshotID: cfg.PreviousSnapshotID,
 		ui:                 uiw,
+		deviceNumber:       deviceNumber,
 		pendingChunkHashes: make(map[string]struct{}),
 	}
 }
@@ -291,7 +310,7 @@ func (s *Scanner) Scan(
 		}
 	}
 
-	err = s.recordDirectories(ctx, scanResult.Directories)
+	err = s.recordDirectories(ctx, scanResult)
 	if err != nil {
 		return nil, err
 	}
@@ -869,6 +888,11 @@ type ScanPhaseResult struct {
 	FilesToProcess   []*FileToProcess
 	UnchangedFileIDs []types.FileID   // IDs of unchanged files to associate with snapshot
 	Directories      []*FileToProcess // Every directory found, to record
+	// MountPoints are the directories, the scanned path included, that
+	// the walk found an entry in and, once it had listed them, on a
+	// different device from their parent directory (see
+	// recordIfMountPoint).
+	MountPoints []string
 }
 
 // scanPhase performs the initial directory scan to identify files to process
@@ -888,7 +912,7 @@ func (s *Scanner) scanPhase(
 	// estimate leaves them out.
 	estimatedTotal := countNonDirectories(knownFiles)
 
-	collector := &scanCollector{}
+	collector := &scanCollector{dirsWithEntries: make(map[string]struct{})}
 
 	// Set up periodic status output
 	startTime := time.Now()
@@ -928,6 +952,13 @@ func (s *Scanner) scanPhase(
 		default:
 		}
 
+		// The scanned directory itself is not an entry found in it.
+		if filePath != path || !info.IsDir() {
+			result.EntriesFound++
+		}
+
+		s.recordIfMountPoint(filePath, path, collector)
+
 		// Handle symlinks and directories
 		handled, err := s.recordSpecialEntry(
 			filePath, info, existingFiles, knownFiles, collector, result)
@@ -940,18 +971,8 @@ func (s *Scanner) scanPhase(
 			return nil
 		}
 
-		// Track this file as existing (for deletion detection)
-		existingFiles[filePath] = struct{}{}
-
-		// Check file against in-memory map (no DB query!)
-		file := s.buildRegularFileEntry(filePath, info)
-		needsProcessing := s.checkFileInMemory(file, knownFiles)
-
-		filesScanned, changedCount := collector.recordFile(
-			filePath, info, file, needsProcessing)
-
-		// Update result stats
-		s.updateScanEntryStats(result, needsProcessing, info)
+		filesScanned, changedCount := s.recordRegularFile(
+			filePath, info, existingFiles, knownFiles, collector, result)
 
 		// Output periodic status
 		if time.Since(lastStatusTime) >= scanStatusInterval {
@@ -972,6 +993,7 @@ func (s *Scanner) scanPhase(
 		FilesToProcess:   collector.filesToProcess,
 		UnchangedFileIDs: collector.unchangedFileIDs,
 		Directories:      collector.directories,
+		MountPoints:      collector.mountPoints,
 	}, nil
 }
 
@@ -1027,6 +1049,30 @@ func (s *Scanner) recordSpecialEntry(
 	return false, nil
 }
 
+// recordRegularFile records a regular file as recordSpecialEntry does a
+// symlink and returns the running scanned and changed counts.
+func (s *Scanner) recordRegularFile(
+	filePath string, info os.FileInfo,
+	existingFiles map[string]struct{},
+	knownFiles map[string]*database.File,
+	collector *scanCollector, result *ScanResult,
+) (int64, int) {
+	// Track this file as existing (for deletion detection)
+	existingFiles[filePath] = struct{}{}
+
+	// Check file against in-memory map (no DB query!)
+	file := s.buildRegularFileEntry(filePath, info)
+	needsProcessing := s.checkFileInMemory(file, knownFiles)
+
+	filesScanned, changedCount := collector.recordFile(
+		filePath, info, file, needsProcessing)
+
+	// Update result stats
+	s.updateScanEntryStats(result, needsProcessing, info)
+
+	return filesScanned, changedCount
+}
+
 // countRemovedDuringWalk counts an entry that was in its directory's
 // listing but was gone when the walk looked it up, like a file removed
 // before phase 2 reads it: as examined and failed, and not as an error,
@@ -1074,6 +1120,29 @@ type scanCollector struct {
 	unchangedFileIDs []types.FileID // Just IDs - no new records needed
 	directories      []*FileToProcess
 	filesScanned     int64
+	// dirsWithEntries holds each directory the walk has found an entry in.
+	dirsWithEntries map[string]struct{}
+	mountPoints     []string
+}
+
+// firstEntryIn notes that the walk found an entry in directory dir and
+// reports whether it is the first one.
+func (c *scanCollector) firstEntryIn(dir string) bool {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	_, seen := c.dirsWithEntries[dir]
+	c.dirsWithEntries[dir] = struct{}{}
+
+	return !seen
+}
+
+// addMountPoint sets a mount point aside to be recorded.
+func (c *scanCollector) addMountPoint(dir string) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	c.mountPoints = append(c.mountPoints, dir)
 }
 
 // addDirectory sets a directory aside to be recorded. It is not counted
@@ -1265,20 +1334,100 @@ func (s *Scanner) buildDirectoryEntry(path string, info os.FileInfo) *database.F
 	}
 }
 
-// recordDirectories records every directory the walk found. A directory
-// has no data to back up, so it is not among the files counted and
-// backed up.
+// recordDirectories records every directory the walk found, and its
+// mount points (see recordMountPoints). A directory has no data to back
+// up, so it is not among the files counted and backed up.
 func (s *Scanner) recordDirectories(
-	ctx context.Context, directories []*FileToProcess,
+	ctx context.Context, scanned *ScanPhaseResult,
 ) error {
-	for _, dir := range directories {
+	for _, dir := range scanned.Directories {
 		err := s.recordNonRegularFile(ctx, dir)
 		if err != nil {
 			return fmt.Errorf("recording directory %s: %w", dir.Path, err)
 		}
 	}
 
-	return nil
+	return s.recordMountPoints(ctx, scanned.MountPoints)
+}
+
+// recordMountPoints records with the snapshot the mount points the walk
+// found (see ScanPhaseResult.MountPoints).
+func (s *Scanner) recordMountPoints(
+	ctx context.Context, mountPoints []string,
+) error {
+	return s.repos.WithTx(ctx, func(txCtx context.Context, tx *sql.Tx) error {
+		for _, dir := range mountPoints {
+			log.Info("Found a mount point", "path", dir)
+
+			err := s.repos.Snapshots.AddMountPoint(txCtx, tx, s.snapshotID, dir)
+			if err != nil {
+				return fmt.Errorf("recording mount point %s: %w", dir, err)
+			}
+		}
+
+		return nil
+	})
+}
+
+// recordIfMountPoint sets the directory that holds entry, a path the
+// walk found, aside to be recorded as a mount point if it is on a
+// different device from its parent directory. The walk calls it for each
+// entry it finds, and it decides on the first entry in a directory, so a
+// directory the walk found no entry in is never recorded. By then the
+// walk has listed the directory, which mounts a volume mounted there on
+// first access, so the directory and its parent are looked up again:
+// before the listing, the directory can be on the automounter's own
+// device (a systemd automount) or on its parent's (an autofs map that
+// shows its mount points before mounting them). The scanned path is in
+// no listing the walk made, so it is skipped as an entry. A directory
+// that cannot be looked up then, or whose parent cannot, is not
+// recorded, so this snapshot does not stop the prune of a later backup
+// that misses its volume.
+func (s *Scanner) recordIfMountPoint(
+	entry, scannedPath string, collector *scanCollector,
+) {
+	dir := filepath.Dir(entry)
+
+	if entry == scannedPath || !collector.firstEntryIn(dir) {
+		return
+	}
+
+	dirDevice, ok := s.deviceNumberAt(dir)
+	if !ok {
+		return
+	}
+
+	parentDevice, ok := s.deviceNumberAt(filepath.Dir(dir))
+	if ok && dirDevice != parentDevice {
+		collector.addMountPoint(dir)
+	}
+}
+
+// deviceNumberAt looks path up now and returns the number of the device
+// that holds it, and false when the lookup fails (logged) or gives no
+// device number.
+func (s *Scanner) deviceNumberAt(path string) (uint64, bool) {
+	info, err := s.fs.Stat(path)
+	if err != nil {
+		log.Warn("Could not look up a directory to check for a mount point",
+			"path", path, "error", err)
+
+		return 0, false
+	}
+
+	return s.deviceNumber(info)
+}
+
+// deviceNumberFromStat returns the number of the device that holds the
+// file info describes, and false when info carries no stat, as from the
+// in-memory test filesystem.
+func deviceNumberFromStat(info os.FileInfo) (uint64, bool) {
+	stat, ok := info.Sys().(*syscall.Stat_t)
+	if !ok {
+		return 0, false
+	}
+
+	return uint64(stat.Dev), true //nolint:unconvert // Dev is an int32 on darwin
 }
 
 // recordNonRegularFile writes a symlink or directory entry to the database

internal/snapshot/snapshot.go

@@ -271,16 +271,18 @@ func (sm *SnapshotManager) CompleteSnapshot(
 	return sm.MarkSnapshotComplete(ctx, snapshotID)
 }
 
-// ExportSnapshotMetadata exports snapshot metadata to S3
+// ExportSnapshotMetadata exports snapshot metadata to the backup destination store
 //
 // This method executes the complete snapshot metadata export process:
 // 1. Creates a temporary directory for working files
 // 2. Copies the main database to preserve its state
 // 3. Cleans the copy to contain only current snapshot data
-// 4. Dumps the cleaned database to SQL
-// 5. Compresses the SQL dump with zstd
-// 6. Encrypts the compressed data with age (always; recipients are required)
-// 7. Uploads to S3 at: snapshots/{snapshot-id}.sql.zst[.age]
+// 4. Vacuums the copy to remove the deleted data
+// 5. Compresses the copy with zstd
+// 6. Encrypts the compressed copy with age (always; recipients are required)
+// 7. Builds the blob manifest from the copy, compressed but not encrypted
+// 8. Uploads the database to metadata/{remote-key}/db.zst.age
+// 9. Uploads the manifest to metadata/{remote-key}/manifest.json.zst
 //
 // The only caller (finalizeSnapshotMetadata) does not close the main database
 // before calling this method: the index is copied at dbPath while it is still
@@ -518,8 +520,8 @@ type CleanupStats struct {
 //
 // The cleanup is performed in a specific order to maintain referential integrity:
 //  1. Delete other snapshots
-//  2. Delete orphaned snapshot associations (snapshot_files, snapshot_blobs)
-//     for deleted snapshots
+//  2. Delete orphaned snapshot associations (snapshot_files, snapshot_blobs,
+//     snapshot_mount_points) for deleted snapshots
 //  3. Delete orphaned files (not in the current snapshot)
 //  4. Delete orphaned chunk-to-file mappings (references to deleted files)
 //  5. Delete orphaned blobs (not in the current snapshot)
@@ -948,8 +950,8 @@ func (sm *SnapshotManager) deleteOtherSnapshots(
 	return nil
 }
 
-// deleteOrphanedSnapshotAssociations deletes snapshot_files and
-// snapshot_blobs for deleted snapshots
+// deleteOrphanedSnapshotAssociations deletes snapshot_files,
+// snapshot_blobs and snapshot_mount_points for deleted snapshots
 func (sm *SnapshotManager) deleteOrphanedSnapshotAssociations(
 	ctx context.Context, tx *sql.Tx, currentSnapshotID string,
 ) error {
@@ -983,6 +985,19 @@ func (sm *SnapshotManager) deleteOrphanedSnapshotAssociations(
 	log.Debug("[Temp DB Cleanup] Deleted snapshot_blobs associations",
 		"count", rowsAffected)
 
+	// Delete the mount points other snapshots recorded
+	query := "DELETE FROM snapshot_mount_points WHERE snapshot_id != ?"
+	database.LogSQL("Execute", query, currentSnapshotID)
+
+	result, err = tx.ExecContext(ctx, query, currentSnapshotID)
+	if err != nil {
+		return fmt.Errorf("deleting orphaned snapshot_mount_points: %w", err)
+	}
+
+	rowsAffected, _ = result.RowsAffected()
+	log.Debug("[Temp DB Cleanup] Deleted snapshot_mount_points rows",
+		"count", rowsAffected)
+
 	return nil
 }
 

internal/snapshot/snapshot_test.go

@@ -7,12 +7,14 @@ import (
 	"database/sql"
 	"io"
 	"path/filepath"
+	"slices"
 	"testing"
 
 	"github.com/spf13/afero"
 	"sneak.berlin/go/vaultik/internal/config"
 	"sneak.berlin/go/vaultik/internal/database"
 	"sneak.berlin/go/vaultik/internal/log"
+	"sneak.berlin/go/vaultik/internal/types"
 )
 
 const (
@@ -387,6 +389,77 @@ func TestCleanSnapshotDBNonExistentSnapshot(t *testing.T) {
 	}
 }
 
+// The exported metadata database keeps only the mount points that the
+// exported snapshot recorded. See
+// https://git.eeqj.de/sneak/vaultik/issues/395.
+func TestCleanSnapshotDBKeepsOnlyTheSnapshotsMountPoints(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	ctx := context.Background()
+	dbPath := filepath.Join(t.TempDir(), "export.db")
+
+	db, err := database.New(ctx, dbPath)
+	if err != nil {
+		t.Fatalf("failed to create database: %v", err)
+	}
+
+	repos := database.NewRepositories(db)
+
+	for _, id := range []types.SnapshotID{"exported", "other"} {
+		err = repos.Snapshots.Create(ctx, nil, &database.Snapshot{ID: id})
+		if err != nil {
+			t.Fatalf("failed to create snapshot: %v", err)
+		}
+
+		err = repos.Snapshots.AddMountPoint(ctx, nil, id.String(), "/data/"+id.String())
+		if err != nil {
+			t.Fatalf("failed to add mount point: %v", err)
+		}
+	}
+
+	err = db.Close()
+	if err != nil {
+		t.Fatalf("failed to close database: %v", err)
+	}
+
+	sm := &SnapshotManager{
+		config: &config.Config{
+			CompressionLevel: 3,
+			AgeRecipients:    []string{testAgeRecipient},
+		},
+		fs: afero.NewOsFs(),
+	}
+
+	_, err = sm.cleanSnapshotDB(ctx, dbPath, "exported")
+	if err != nil {
+		t.Fatalf("failed to clean snapshot database: %v", err)
+	}
+
+	cleaned, err := database.New(ctx, dbPath)
+	if err != nil {
+		t.Fatalf("failed to open cleaned database: %v", err)
+	}
+
+	defer func() { _ = cleaned.Close() }()
+
+	cleanedRepos := database.NewRepositories(cleaned)
+
+	for id, want := range map[string][]string{
+		"exported": {"/data/exported"},
+		"other":    nil,
+	} {
+		got, err := cleanedRepos.Snapshots.GetMountPoints(ctx, id)
+		if err != nil {
+			t.Fatalf("failed to read mount points: %v", err)
+		}
+
+		if !slices.Equal(got, want) {
+			t.Errorf("mount points of %s: got %v, want %v", id, got, want)
+		}
+	}
+}
+
 // Two creates of one snapshot name back to back start within one second,
 // the resolution of the timestamp in a snapshot ID. See
 // https://git.eeqj.de/sneak/vaultik/issues/270.

internal/storage/faultstore/faultstore.go

@@ -2,15 +2,17 @@
 // faults on demand, so tests can reproduce the failure modes a real
 // backend exhibits: an upload that fails partway, a backend that reports
 // success while storing nothing, reads that return corrupt or truncated
-// bytes, and a delete the backend refuses. It is the seam called for by
-// the fault-injection tests (sneak/vaultik issue 72) and is meant to be
-// reused by future tests rather than re-implemented per case.
+// bytes, and a delete or a stat the backend refuses. It is the seam
+// called for by the fault-injection tests (sneak/vaultik issue 72) and
+// is meant to be reused by future tests rather than re-implemented per
+// case.
 //
-// The wrapper delegates every method to the inner Storer. Three hooks
+// The wrapper delegates every method to the inner Storer. Four hooks
 // change that: OnPut decides the fate of each write, OnGet decides how
-// each read's bytes are returned, and OnDelete decides whether each
-// delete fails. All are keyed by the object key, so a test can fault
-// only blobs, only metadata, or a single object.
+// each read's bytes are returned, OnDelete decides whether each delete
+// fails, and OnStat whether each stat fails. All are keyed by the object
+// key, so a test can fault only blobs, only metadata, or a single
+// object.
 package faultstore
 
 import (
@@ -30,6 +32,11 @@ var ErrInjectedUpload = errors.New("faultstore: injected upload failure")
 // fail.
 var ErrInjectedDelete = errors.New("faultstore: injected delete failure")
 
+// ErrInjectedStat is returned by a Stat the OnStat hook chose to fail.
+// It is not storage.ErrNotFound: the backend refused the request, as S3
+// refuses a HEAD to credentials that allow only PUT.
+var ErrInjectedStat = errors.New("faultstore: injected stat failure")
+
 // PutAction is the disposition OnPut assigns to a write.
 type PutAction int
 
@@ -76,6 +83,10 @@ type Storer struct {
 	// object key. Returning true fails the delete and leaves the object
 	// in place.
 	OnDelete func(key string) bool
+
+	// OnStat, when set, is consulted before every Stat with the object
+	// key. Returning true fails the stat with ErrInjectedStat.
+	OnStat func(key string) bool
 }
 
 // New wraps inner. inner must be non-nil.
@@ -159,8 +170,12 @@ func damage(fault GetFault, data []byte) []byte {
 	return out
 }
 
-// Stat delegates unchanged.
+// Stat returns the object's info unless OnStat fails the stat.
 func (f *Storer) Stat(ctx context.Context, key string) (*storage.ObjectInfo, error) {
+	if f.OnStat != nil && f.OnStat(key) {
+		return nil, fmt.Errorf("%w for %q", ErrInjectedStat, key)
+	}
+
 	return f.inner.Stat(ctx, key)
 }
 

internal/storage/s3_test.go

@@ -100,8 +100,9 @@ func TestS3StorerMissingKeyMapsToErrNotFound(t *testing.T) {
 // TestS3ListingCutShortIsAnError checks that List and ListStream fail on a
 // listing page marked truncated that carries no continuation token, as a
 // server answering V2 listings V1-style sends it. Taken as the last page,
-// it would hide every later key, and prune would treat the blobs of the
-// snapshots listed there as unreferenced.
+// it would hide every later key: prune would treat the blobs of the
+// snapshots listed there as unreferenced, and a directory under metadata/
+// whose manifest is listed there as one with no manifest.
 func TestS3ListingCutShortIsAnError(t *testing.T) {
 	t.Parallel()
 

internal/vaultik/destination_marker.go

@@ -5,14 +5,16 @@ import (
 	"fmt"
 	"strings"
 
+	"sneak.berlin/go/vaultik/internal/log"
 	"sneak.berlin/go/vaultik/internal/storage"
 )
 
 // destinationMarkerKey is the object every backup writes at the root of
 // the backup destination store. While the local index holds a snapshot
-// stored there, a destination without it is treated as not present: an
-// unplugged volume leaves an empty directory at its mount point, which
-// would otherwise read as a store whose snapshots are all gone.
+// stored there, a destination that answers a look-up of it with not
+// found is treated as not present: an unplugged volume leaves an empty
+// directory at its mount point, which would otherwise read as a store
+// whose snapshots are all gone.
 const destinationMarkerKey = "vaultik-destination.txt"
 
 // destinationMarkerText is the whole content of the marker. It names no
@@ -20,16 +22,24 @@ const destinationMarkerKey = "vaultik-destination.txt"
 const destinationMarkerText = "This is a vaultik backup destination store.\n"
 
 // errDestinationNotPresent is returned when the local index holds a
-// snapshot stored on the backup destination store and the store has no
-// marker.
+// snapshot stored on the backup destination store and the store answers
+// that it has no marker.
 var errDestinationNotPresent = errors.New("backup destination store is not present")
 
 // checkDestinationMarker returns errDestinationNotPresent when the local
 // index holds a snapshot stored on the backup destination store and the
-// store has no marker. With no snapshot in the local index, as on a
-// first backup or on another machine, there is nothing to check; nor
-// when the local index is bound to a different destination than the
-// configured one, since its snapshots are stored there.
+// store answers that it has no marker. With no snapshot in the local
+// index, as on a first backup or on another machine, there is nothing to
+// check; nor when the local index is bound to a different destination
+// than the configured one, since its snapshots are stored there.
+//
+// A look-up of the marker that fails for any other reason than not
+// found is logged and otherwise ignored, because the check could not be
+// made: S3 refuses it to credentials that allow only PUT, which is all
+// a backup needs. The check exists for a file:// volume's empty mount
+// point, which always answers not found, and a destination that cannot
+// be reached fails on the next request made to it, such as the backup's
+// PUT of the marker.
 func (v *Vaultik) checkDestinationMarker() error {
 	ids, err := v.localSnapshotIDs()
 	if err != nil {
@@ -63,8 +73,11 @@ func (v *Vaultik) checkDestinationMarker() error {
 			destinationMarkerKey)
 	}
 
+	// Info, not a warning: --cron must stay silent on a successful
+	// backup from a host whose credentials allow only PUT.
 	if err != nil {
-		return fmt.Errorf("checking for %s: %w", destinationMarkerKey, err)
+		log.Info("Could not check the backup destination store for its marker",
+			"key", destinationMarkerKey, "error", err)
 	}
 
 	return nil

internal/vaultik/destination_marker_test.go

@@ -13,15 +13,16 @@ import (
 	"sneak.berlin/go/vaultik/internal/database"
 	"sneak.berlin/go/vaultik/internal/log"
 	"sneak.berlin/go/vaultik/internal/storage"
+	"sneak.berlin/go/vaultik/internal/storage/faultstore"
 	"sneak.berlin/go/vaultik/internal/vaultik"
 )
 
 // These tests cover https://git.eeqj.de/sneak/vaultik/issues/239: a
 // file:// destination at a volume's mount point leaves an empty directory
 // behind when the volume is unplugged. While the local index holds
-// snapshots, a destination without vaultik-destination.txt is not present,
-// so no command may write to it or conclude from it that the local
-// snapshots are gone.
+// snapshots, a destination that answers that it has no
+// vaultik-destination.txt is not present, so no command may write to it
+// or conclude from it that the local snapshots are gone.
 
 // markerFile is the name of the file a backup writes at the root of the
 // destination.
@@ -93,6 +94,39 @@ func TestBackupRefusesDestinationWithoutMarker(t *testing.T) {
 	assertUntouched(ctx, t, repos, storeDir)
 }
 
+// TestBackupGoesOnWhenMarkerCannotBeChecked checks that a backup goes on
+// and writes the marker when looking it up fails with an error other
+// than not found, as S3 answers credentials that allow only PUT
+// (https://git.eeqj.de/sneak/vaultik/issues/389), and that a marker
+// that is not found still stops it.
+func TestBackupGoesOnWhenMarkerCannotBeChecked(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	ctx := context.Background()
+	storeDir := t.TempDir()
+	v, repos, _ := backUpToFileDestination(ctx, t, storeDir)
+
+	// Removed so the test sees the backup write it again: with the
+	// look-up failing, the backup cannot tell that it is gone.
+	markerPath := filepath.Join(storeDir, markerFile)
+	require.NoError(t, os.Remove(markerPath))
+
+	store := faultstore.New(v.Storage)
+	store.OnStat = func(key string) bool { return key == markerFile }
+	v.Storage = store
+
+	require.NoError(t, backUp(v, "second"))
+	localSnapshotID(ctx, t, repos, "second")
+	assert.FileExists(t, markerPath)
+
+	require.NoError(t, os.Remove(markerPath))
+
+	store.OnStat = nil
+
+	require.ErrorContains(t, backUp(v, "third"), markerFile)
+}
+
 // TestBackupChecksMarkerBeforeDroppingIncompleteSnapshots checks that
 // snapshot create writes nothing when the local index holds only an
 // incomplete snapshot and the destination has no marker. The backup drops

internal/vaultik/fault_injection_test.go

@@ -679,6 +679,7 @@ func faultScannerFactory(
 			Exclude:            params.Exclude,
 			SkipErrors:         params.SkipErrors,
 			PreviousSnapshotID: params.PreviousSnapshotID,
+			DeviceNumber:       params.DeviceNumber,
 		})
 	}
 }

internal/vaultik/info.go

@@ -246,7 +246,7 @@ func (v *Vaultik) RemoteInfo(jsonOutput bool) error {
 		v.stdoutf("Type:     %s\n", storageInfo.Type)
 		v.stdoutf("Location: %s\n", storageInfo.Location)
 		v.printlnStdout()
-		v.stdoutf("Scanning snapshot metadata...\n")
+		v.UI.Beginf("Scanning snapshot metadata...")
 	}
 
 	snapshotMetadata, snapshotIDs, skippedManifestCount, err := v.collectSnapshotMetadata()
@@ -265,7 +265,7 @@ func (v *Vaultik) RemoteInfo(jsonOutput bool) error {
 			}
 		}
 
-		v.stdoutf("Downloading %d manifest(s)...\n", manifestCount)
+		v.UI.Beginf("Downloading %d manifest(s)...", manifestCount)
 	}
 
 	referencedBlobs, unreadableManifests := v.collectReferencedBlobsFromManifests(
@@ -447,7 +447,7 @@ func (v *Vaultik) scanRemoteBlobStorage(
 	result *RemoteInfoResult, referencedBlobs map[string]int64, showText bool,
 ) error {
 	if showText {
-		v.stdoutf("Scanning blobs...\n")
+		v.UI.Beginf("Scanning blobs...")
 	}
 
 	// Use prune's listing, so a file under blobs/ that prune would never

internal/vaultik/nuke_remote_test.go

@@ -76,7 +76,7 @@ func TestNukeRemoteLeavesNoFiles(t *testing.T) {
 // TestNukeRemoteFailsWhenADeleteFails checks that remote nuke returns an
 // error when a snapshot's metadata or a blob cannot be deleted, does not
 // report the store empty, and advises running nuke again: prune deletes
-// no metadata.
+// no snapshot metadata that has its manifest.
 func TestNukeRemoteFailsWhenADeleteFails(t *testing.T) {
 	log.Initialize(log.Config{})
 	t.Parallel()

internal/vaultik/prune.go

@@ -4,10 +4,12 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"sort"
 	"strings"
 	"time"
 
 	"sneak.berlin/go/vaultik/internal/log"
+	"sneak.berlin/go/vaultik/internal/snapshot"
 	"sneak.berlin/go/vaultik/internal/storage"
 )
 
@@ -24,6 +26,11 @@ var errNukeRequiresForce = errors.New(
 // errBlobDeleteFailed reports unreferenced blobs prune could not delete.
 var errBlobDeleteFailed = errors.New("blob(s) could not be deleted")
 
+// errMetadataDirDeleteFailed reports directories under metadata/ with no
+// manifest that prune could not delete.
+var errMetadataDirDeleteFailed = errors.New(
+	"metadata director(ies) with no manifest could not be deleted")
+
 // errObjectsLeft reports objects remote nuke still finds on the backup
 // destination store after deleting.
 var errObjectsLeft = errors.New(
@@ -31,7 +38,8 @@ var errObjectsLeft = errors.New(
 
 // nukeCommandHint is the command suggested when a remote nuke could not
 // delete everything: running it again deletes what is left, which
-// `vaultik prune` does not do for snapshot metadata.
+// `vaultik prune` does not do for snapshot metadata that has its
+// manifest.
 const nukeCommandHint = "vaultik remote nuke --force"
 
 // metadataDirName is the top-level remote directory holding snapshot
@@ -58,8 +66,8 @@ func (v *Vaultik) NukeRemote(force bool) error {
 
 	// Checked before anything is deleted: running nuke again would fail
 	// the same way, so the advice below must not follow these errors.
-	// The listing also fails on a destination without the marker while
-	// the local index holds snapshots.
+	// The listing also fails on a destination that answers that it has
+	// no marker while the local index holds snapshots.
 	err := v.EnsureStorageBinding()
 	if err != nil {
 		return err
@@ -169,14 +177,20 @@ type PruneBlobsResult struct {
 	// newer than the prune grace period, or of unknown age. BlobsFound
 	// does not include them.
 	BlobsTooNew int `json:"blobs_too_new"`
+	// MetadataDirsDeleted counts the directories under metadata/ with no
+	// manifest that prune deleted, and MetadataDirsFailed those it could
+	// not delete.
+	MetadataDirsDeleted int `json:"metadata_dirs_deleted"`
+	MetadataDirsFailed  int `json:"metadata_dirs_failed,omitempty"`
 }
 
-// Prune removes orphaned data from the local index database AND
-// unreferenced blobs from the backup destination store. This is the
-// single user-facing prune entry point — the split between local and
-// remote cleanup is an implementation detail. Calling code should
-// prefer this method over PruneDatabase or PruneBlobs individually
-// unless it specifically wants one half.
+// Prune removes orphaned data from the local index database AND, from the
+// backup destination store, unreferenced blobs and the directories under
+// metadata/ with no manifest. This is the single user-facing prune entry
+// point — the split between local and remote cleanup is an
+// implementation detail. Calling code should prefer this method over
+// PruneDatabase or PruneBlobs individually unless it specifically wants
+// one half.
 func (v *Vaultik) Prune(opts *PruneOptions) error {
 	err := v.EnsureStorageBinding()
 	if err != nil {
@@ -200,11 +214,17 @@ func (v *Vaultik) Prune(opts *PruneOptions) error {
 	return v.PruneBlobs(opts)
 }
 
-// PruneBlobs removes unreferenced blobs from storage
+// PruneBlobs removes unreferenced blobs from storage, and each directory
+// under metadata/ that a backup left with no manifest.
 func (v *Vaultik) PruneBlobs(opts *PruneOptions) error {
 	log.Info("Starting prune operation")
 
-	allBlobsReferenced, err := v.collectReferencedBlobs()
+	metadataObjects, err := v.listMetadataObjects()
+	if err != nil {
+		return err
+	}
+
+	allBlobsReferenced, err := v.collectReferencedBlobs(metadataObjects)
 	if err != nil {
 		return err
 	}
@@ -217,6 +237,11 @@ func (v *Vaultik) PruneBlobs(opts *PruneOptions) error {
 	unreferencedBlobs, totalSize, tooNew := v.findUnreferencedBlobs(
 		allBlobs, allBlobsReferenced)
 
+	dirsWithoutManifest, err := v.findMetadataDirsWithoutManifest(metadataObjects)
+	if err != nil {
+		return err
+	}
+
 	result := &PruneBlobsResult{
 		BlobsFound:  len(unreferencedBlobs),
 		BlobsTooNew: tooNew,
@@ -224,7 +249,7 @@ func (v *Vaultik) PruneBlobs(opts *PruneOptions) error {
 
 	v.reportBlobsTooNew(tooNew, opts)
 
-	if len(unreferencedBlobs) == 0 {
+	if len(unreferencedBlobs) == 0 && len(dirsWithoutManifest) == 0 {
 		log.Info("No unreferenced blobs found")
 
 		if opts.JSON {
@@ -237,38 +262,16 @@ func (v *Vaultik) PruneBlobs(opts *PruneOptions) error {
 	}
 
 	log.Info("Found unreferenced blobs",
-		"count", len(unreferencedBlobs), "total_size", ubytes(totalSize))
+		"count", len(unreferencedBlobs), "total_size", ubytes(totalSize),
+		"metadata_dirs_without_manifest", len(dirsWithoutManifest))
 
-	if opts.Force && !opts.JSON {
-		v.UI.Infof("Found %d unreferenced blob(s) totaling %s.",
-			len(unreferencedBlobs), ubytes(totalSize))
-	}
-
-	if !opts.Force && !opts.JSON {
-		// The count, the prompt and its answer bypass the UI: they are an
-		// interactive exchange the operator must see, so --quiet does not
-		// silence them.
-		v.stdoutf("Found %d unreferenced blob(s) totaling %s.\n",
-			len(unreferencedBlobs), ubytes(totalSize))
-		v.stdoutf("\nDelete %d unreferenced blob(s)? [y/N] ", len(unreferencedBlobs))
-
-		var confirm string
-
-		_, err = v.scanStdin(&confirm)
-		if err != nil {
-			v.printlnStdout("Cancelled")
-
-			return nil //nolint:nilerr // read failure means no confirmation
-		}
-
-		if strings.ToLower(confirm) != "y" {
-			v.printlnStdout("Cancelled")
-
-			return nil
-		}
+	if !v.confirmPrune(opts, len(unreferencedBlobs), totalSize,
+		dirsWithoutManifest) {
+		return nil
 	}
 
 	v.deleteUnreferencedBlobs(unreferencedBlobs, allBlobs, result)
+	v.deleteMetadataDirs(dirsWithoutManifest, result)
 
 	if opts.JSON {
 		err = v.outputPruneBlobsJSON(result)
@@ -276,33 +279,142 @@ func (v *Vaultik) PruneBlobs(opts *PruneOptions) error {
 			return err
 		}
 	} else {
+		v.reportPruneDeletions(result, len(dirsWithoutManifest))
+	}
+
+	var failures []error
+
+	if result.BlobsFailed > 0 {
+		failures = append(failures,
+			fmt.Errorf("%d %w", result.BlobsFailed, errBlobDeleteFailed))
+	}
+
+	if result.MetadataDirsFailed > 0 {
+		failures = append(failures, fmt.Errorf("%d %w",
+			result.MetadataDirsFailed, errMetadataDirDeleteFailed))
+	}
+
+	return errors.Join(failures...)
+}
+
+// confirmPrune states what prune found to delete, unreferenced blobs and
+// directories under metadata/ with no manifest, naming each directory by
+// its remote key, and, unless --force is given, asks the operator to
+// confirm. Under --json it prints nothing and does not ask. It reports
+// whether to go ahead.
+func (v *Vaultik) confirmPrune(
+	opts *PruneOptions, blobCount int, blobsSize int64, dirs []string,
+) bool {
+	if opts.JSON {
+		return true
+	}
+
+	dirCount := len(dirs)
+	blobsFound := fmt.Sprintf("Found %d unreferenced blob(s) totaling %s.",
+		blobCount, ubytes(blobsSize))
+	dirsFound := fmt.Sprintf("Found %d metadata director(ies) left by "+
+		"backups that stopped before their manifest:", dirCount)
+
+	if opts.Force {
+		if blobCount > 0 {
+			v.UI.Infof("%s", blobsFound)
+		}
+
+		if dirCount > 0 {
+			v.UI.Infof("%s", dirsFound)
+
+			for _, remoteKey := range dirs {
+				v.UI.Detailf("metadata/%s/", remoteKey)
+			}
+		}
+
+		return true
+	}
+
+	// The counts, the names, the prompt and its answer bypass the UI:
+	// they are an interactive exchange the operator must see, so --quiet
+	// does not silence them.
+	if blobCount > 0 {
+		v.stdoutf("%s\n", blobsFound)
+	}
+
+	if dirCount > 0 {
+		v.stdoutf("%s\n", dirsFound)
+
+		for _, remoteKey := range dirs {
+			v.stdoutf("  metadata/%s/\n", remoteKey)
+		}
+	}
+
+	switch {
+	case dirCount == 0:
+		v.stdoutf("\nDelete %d unreferenced blob(s)? [y/N] ", blobCount)
+	case blobCount == 0:
+		v.stdoutf("\nDelete %d metadata director(ies)? [y/N] ", dirCount)
+	default:
+		v.stdoutf("\nDelete %d unreferenced blob(s) and %d metadata "+
+			"director(ies)? [y/N] ", blobCount, dirCount)
+	}
+
+	var confirm string
+
+	// A failure to read the answer means no confirmation.
+	_, err := v.scanStdin(&confirm)
+	if err != nil || strings.ToLower(confirm) != "y" {
+		v.printlnStdout("Cancelled")
+
+		return false
+	}
+
+	return true
+}
+
+// reportPruneDeletions says how many blobs and metadata directories
+// prune deleted, naming each kind only when it found some to delete.
+func (v *Vaultik) reportPruneDeletions(result *PruneBlobsResult, dirCount int) {
+	if result.BlobsFound > 0 {
 		v.UI.Infof("Deleted %d blob(s) totaling %s.",
 			result.BlobsDeleted, ubytes(result.BytesFreed))
 	}
 
-	if result.BlobsFailed > 0 {
-		return fmt.Errorf("%d %w", result.BlobsFailed, errBlobDeleteFailed)
+	if dirCount > 0 {
+		v.UI.Infof("Deleted %d metadata director(ies) with no manifest.",
+			result.MetadataDirsDeleted)
 	}
-
-	return nil
 }
 
-// collectReferencedBlobs downloads all manifests and returns the set of
-// referenced blob hashes.
+// listMetadataObjects lists every object under metadata/ on the
+// destination store.
+func (v *Vaultik) listMetadataObjects() ([]storage.ObjectInfo, error) {
+	log.Info("Listing remote snapshots")
+
+	var objects []storage.ObjectInfo
+
+	for object := range v.Storage.ListStream(v.ctx, "metadata/") {
+		if object.Err != nil {
+			return nil, fmt.Errorf("listing metadata objects: %w", object.Err)
+		}
+
+		objects = append(objects, object)
+	}
+
+	return objects, nil
+}
+
+// collectReferencedBlobs downloads every manifest among the listed
+// metadata objects and returns the set of referenced blob hashes.
 //
 // Every manifest must be read successfully. A manifest that cannot be
 // downloaded or decoded means its snapshot's blobs are unknown, so
 // treating them as unreferenced would let prune delete data a snapshot
 // still needs. Rather than risk that silent loss, any failure returns an
 // error naming the remote key and prune deletes nothing.
-func (v *Vaultik) collectReferencedBlobs() (map[string]bool, error) {
-	log.Info("Listing remote snapshots")
-	// IDs returned by listUniqueSnapshotIDs are remote keys (hashed
+func (v *Vaultik) collectReferencedBlobs(
+	metadataObjects []storage.ObjectInfo,
+) (map[string]bool, error) {
+	// IDs returned by uniqueSnapshotIDs are remote keys (hashed
 	// subdirectories under metadata/), not human snapshot IDs.
-	remoteKeys, err := v.listUniqueSnapshotIDs()
-	if err != nil {
-		return nil, fmt.Errorf("listing snapshot keys: %w", err)
-	}
+	remoteKeys := uniqueSnapshotIDs(metadataObjects)
 
 	log.Info("Found manifests in remote storage", "count", len(remoteKeys))
 
@@ -327,18 +439,14 @@ func (v *Vaultik) collectReferencedBlobs() (map[string]bool, error) {
 	return allBlobsReferenced, nil
 }
 
-// listUniqueSnapshotIDs returns deduplicated snapshot IDs from remote metadata
-func (v *Vaultik) listUniqueSnapshotIDs() ([]string, error) {
-	objectCh := v.Storage.ListStream(v.ctx, "metadata/")
+// uniqueSnapshotIDs returns deduplicated snapshot IDs from the listed
+// metadata objects.
+func uniqueSnapshotIDs(metadataObjects []storage.ObjectInfo) []string {
 	seen := make(map[string]bool)
 
 	var snapshotIDs []string
 
-	for object := range objectCh {
-		if object.Err != nil {
-			return nil, fmt.Errorf("listing metadata objects: %w", object.Err)
-		}
-
+	for _, object := range metadataObjects {
 		parts := strings.Split(object.Key, "/")
 		if len(parts) >= minSnapshotIDParts &&
 			parts[0] == metadataDirName && parts[1] != "" {
@@ -353,7 +461,7 @@ func (v *Vaultik) listUniqueSnapshotIDs() ([]string, error) {
 		}
 	}
 
-	return snapshotIDs, nil
+	return snapshotIDs
 }
 
 // listAllRemoteBlobs returns a map of all blob hashes in remote storage
@@ -427,6 +535,82 @@ func (v *Vaultik) findUnreferencedBlobs(
 	return unreferenced, totalSize, tooNew
 }
 
+// findMetadataDirsWithoutManifest returns the remote key of each
+// directory under metadata/ that has no manifest.json.zst, such as one a
+// backup leaves when its manifest upload fails after db.zst.age was
+// uploaded. It leaves out a directory a local snapshot record claims,
+// and one holding an object newer than the prune grace period, or of
+// unknown age because the listing gave no time for it: a backup still
+// running may be writing there. A name that is not a remote key is
+// never returned.
+func (v *Vaultik) findMetadataDirsWithoutManifest(
+	metadataObjects []storage.ObjectInfo,
+) ([]string, error) {
+	localIDs, err := v.localSnapshotIDs()
+	if err != nil {
+		return nil, fmt.Errorf("listing local snapshots: %w", err)
+	}
+
+	keep := make(map[string]bool, len(localIDs))
+	for _, id := range localIDs {
+		keep[snapshot.RemoteSnapshotKey(id)] = true
+	}
+
+	cutoff := time.Now().UTC().Add(-v.Config.PruneGracePeriod)
+	listed := make(map[string]bool)
+
+	for _, object := range metadataObjects {
+		parts := strings.Split(object.Key, "/")
+		if len(parts) < metadataKeyParts || !isBlobHash(parts[1]) {
+			continue
+		}
+
+		remoteKey := parts[1]
+		listed[remoteKey] = true
+
+		if parts[2] == "manifest.json.zst" ||
+			object.ModTime.IsZero() || object.ModTime.After(cutoff) {
+			keep[remoteKey] = true
+		}
+	}
+
+	var remoteKeys []string
+
+	for remoteKey := range listed {
+		if !keep[remoteKey] {
+			remoteKeys = append(remoteKeys, remoteKey)
+		}
+	}
+
+	sort.Strings(remoteKeys)
+
+	return remoteKeys, nil
+}
+
+// deleteMetadataDirs deletes everything in the given directories under
+// metadata/ and counts in the result the directories deleted and those
+// it could not delete.
+func (v *Vaultik) deleteMetadataDirs(
+	remoteKeys []string, result *PruneBlobsResult,
+) {
+	for _, remoteKey := range remoteKeys {
+		_, err := v.deleteRemoteSnapshotByKey(remoteKey)
+		if err != nil {
+			log.Error("Failed to delete metadata directory with no manifest",
+				"remote_key", remoteKey, "error", err)
+
+			result.MetadataDirsFailed++
+
+			continue
+		}
+
+		log.Info("Deleted metadata directory with no manifest",
+			"remote_key", remoteKey)
+
+		result.MetadataDirsDeleted++
+	}
+}
+
 // reportBlobsTooNew says how many unreferenced blobs prune kept for being
 // newer than the grace period or of unknown age. Under --json the
 // document carries the count instead.

internal/vaultik/prune_grace_period_test.go

@@ -24,8 +24,9 @@ import (
 
 // TestPruneDuringBackupKeepsItsBlobs runs a prune from another host
 // sharing the destination store at the moment a backup has uploaded its
-// blobs but not yet its manifest, so no manifest lists those blobs. The
-// prune must leave them, and the backup must then restore.
+// blobs and its db.zst.age but not yet its manifest, so no manifest lists
+// those blobs. The prune must leave the blobs and the db.zst.age, and the
+// backup must then restore.
 func TestPruneDuringBackupKeepsItsBlobs(t *testing.T) {
 	log.Initialize(log.Config{})
 	t.Parallel()
@@ -79,7 +80,8 @@ func TestPruneDuringBackupKeepsItsBlobs(t *testing.T) {
 		SnapshotID: id,
 		TargetDir:  restoreDir,
 		Verify:     true,
-	}), "a prune during the backup must not delete the backup's blobs")
+	}), "a prune during the backup must not delete the backup's blobs "+
+		"or its db.zst.age")
 
 	assertRestoredTree(t, fs, restoreDir, testFiles)
 }

internal/vaultik/prune_metadata_dir_test.go

@@ -0,0 +1,225 @@
+package vaultik_test
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"sneak.berlin/go/vaultik/internal/config"
+	"sneak.berlin/go/vaultik/internal/log"
+	"sneak.berlin/go/vaultik/internal/snapshot"
+	"sneak.berlin/go/vaultik/internal/storage"
+	"sneak.berlin/go/vaultik/internal/storage/faultstore"
+	"sneak.berlin/go/vaultik/internal/ui"
+	"sneak.berlin/go/vaultik/internal/vaultik"
+)
+
+// metadataObjectKey returns the key of the named file in the metadata
+// directory of the snapshot with the given human ID.
+func metadataObjectKey(snapshotID, name string) string {
+	return "metadata/" + snapshot.RemoteSnapshotKey(snapshotID) + "/" + name
+}
+
+// TestPruneDeletesMetadataDirWithoutManifestOlderThanGracePeriod checks
+// that prune deletes a directory under metadata/ holding only
+// db.zst.age, as a backup leaves when its manifest upload fails, once it
+// is older than the grace period, and keeps one newer than that. A
+// directory with a manifest is never deleted, however old.
+func TestPruneDeletesMetadataDirWithoutManifestOlderThanGracePeriod(
+	t *testing.T,
+) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	ctx := context.Background()
+	storeDir := t.TempDir()
+
+	store, err := storage.NewFileStorer(storeDir)
+	require.NoError(t, err)
+
+	const (
+		oldID      = "testhost_home_2026-01-01T00:00:00Z"
+		newID      = "testhost_home_2026-01-02T00:00:00Z"
+		completeID = "testhost_home_2026-01-03T00:00:00Z"
+	)
+
+	oldDB := metadataObjectKey(oldID, "db.zst.age")
+	newDB := metadataObjectKey(newID, "db.zst.age")
+	completeDB := metadataObjectKey(completeID, "db.zst.age")
+	completeManifest := metadataObjectKey(completeID, "manifest.json.zst")
+
+	manifest, err := snapshot.EncodeManifest(&snapshot.Manifest{
+		SnapshotID: snapshot.RemoteSnapshotKey(completeID),
+	}, 3)
+	require.NoError(t, err)
+
+	for _, key := range []string{oldDB, newDB, completeDB} {
+		require.NoError(t, store.Put(ctx, key, strings.NewReader("db")))
+	}
+
+	require.NoError(t, store.Put(ctx, completeManifest,
+		bytes.NewReader(manifest)))
+
+	gracePeriod := time.Hour
+	beforeGracePeriod := time.Now().Add(-gracePeriod - time.Minute)
+
+	for _, key := range []string{oldDB, completeDB, completeManifest} {
+		require.NoError(t, os.Chtimes(filepath.Join(storeDir, key),
+			beforeGracePeriod, beforeGracePeriod))
+	}
+
+	stdout := &bytes.Buffer{}
+	v := &vaultik.Vaultik{
+		Config:  &config.Config{PruneGracePeriod: gracePeriod},
+		Storage: store,
+		Stdout:  stdout,
+		UI:      ui.NewWithColor(stdout, false),
+	}
+	v.SetContext(ctx)
+
+	require.NoError(t, v.PruneBlobs(&vaultik.PruneOptions{JSON: true}))
+
+	_, err = store.Stat(ctx, oldDB)
+	require.ErrorIs(t, err, storage.ErrNotFound,
+		"a directory with no manifest older than the grace period "+
+			"must be deleted")
+
+	for _, key := range []string{newDB, completeDB, completeManifest} {
+		_, err = store.Stat(ctx, key)
+		require.NoError(t, err, "%s must be kept", key)
+	}
+
+	var result vaultik.PruneBlobsResult
+
+	require.NoError(t, json.Unmarshal(stdout.Bytes(), &result))
+	assert.Equal(t, 1, result.MetadataDirsDeleted)
+}
+
+// TestPruneKeepsMetadataDirClaimedUnknownAgeOrNotRemoteKey checks that
+// prune --force keeps a directory under metadata/ with no manifest when a
+// local snapshot record claims it, when the listing gives no time for an
+// object in it, or when its name is not a remote key. A fourth such
+// directory is named, deleted and reported, although there are no
+// unreferenced blobs to delete.
+func TestPruneKeepsMetadataDirClaimedUnknownAgeOrNotRemoteKey(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	ctx := context.Background()
+	env := newListEnv(t)
+
+	const (
+		claimedID = "testhost_home_2026-01-01T00:00:00Z"
+		leftID    = "testhost_home_2026-01-03T00:00:00Z"
+	)
+
+	env.addLocal(t, claimedID, time.Now().Add(-time.Hour))
+
+	claimedDB := metadataObjectKey(claimedID, "db.zst.age")
+	unknownAgeDB := metadataObjectKey("testhost_home_2026-01-02T00:00:00Z",
+		"db.zst.age")
+	leftDB := metadataObjectKey(leftID, "db.zst.age")
+	notRemoteKeyDB := "metadata/not-a-remote-key/db.zst.age"
+
+	for _, key := range []string{claimedDB, leftDB, notRemoteKeyDB} {
+		require.NoError(t, env.store.Put(ctx, key, strings.NewReader("db")))
+	}
+
+	// Written into the mock store's map directly rather than through
+	// Put, so its listing gives no time.
+	env.store.data[unknownAgeDB] = []byte("db")
+
+	require.NoError(t, env.v.PruneBlobs(&vaultik.PruneOptions{Force: true}))
+
+	assert.True(t, env.store.hasKey(claimedDB),
+		"a directory a local snapshot record claims must be kept")
+	assert.True(t, env.store.hasKey(unknownAgeDB),
+		"a directory holding an object of unknown age must be kept")
+	assert.True(t, env.store.hasKey(notRemoteKeyDB),
+		"a directory whose name is not a remote key must be kept")
+	assert.False(t, env.store.hasKey(leftDB),
+		"a directory with no manifest, unclaimed and old, must be deleted")
+
+	output := env.stdout.String()
+
+	assert.Contains(t, output, "Found 1 metadata director(ies) left by "+
+		"backups that stopped before their manifest:")
+	assert.Contains(t, output,
+		"metadata/"+snapshot.RemoteSnapshotKey(leftID)+"/")
+	assert.NotContains(t, output, "not-a-remote-key")
+	assert.Contains(t, output,
+		"Deleted 1 metadata director(ies) with no manifest.")
+	assert.NotContains(t, output, "No unreferenced blobs to remove.")
+}
+
+// TestPruneDeclinedKeepsMetadataDirWithoutManifest checks that the prompt
+// names a directory under metadata/ with no manifest that prune is about
+// to delete, and that answering no keeps it.
+func TestPruneDeclinedKeepsMetadataDirWithoutManifest(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	env := newListEnv(t)
+
+	const leftID = "testhost_home_2026-01-01T00:00:00Z"
+
+	leftDB := metadataObjectKey(leftID, "db.zst.age")
+	require.NoError(t, env.store.Put(context.Background(), leftDB,
+		strings.NewReader("db")))
+
+	env.v.Stdin = strings.NewReader("n\n")
+
+	require.NoError(t, env.v.PruneBlobs(&vaultik.PruneOptions{}))
+
+	assert.True(t, env.store.hasKey(leftDB),
+		"a declined prune must keep the directory")
+
+	output := env.stdout.String()
+
+	assert.Contains(t, output,
+		"  metadata/"+snapshot.RemoteSnapshotKey(leftID)+"/\n")
+	assert.Contains(t, output, "Delete 1 metadata director(ies)? [y/N] ")
+	assert.Contains(t, output, "Cancelled")
+	assert.NotContains(t, output, "Deleted")
+}
+
+// TestPruneFailedMetadataDirDeleteReturnsError checks that prune --json
+// counts a directory under metadata/ with no manifest that it cannot
+// delete, and then returns an error, so the command exits non-zero.
+func TestPruneFailedMetadataDirDeleteReturnsError(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	env := newListEnv(t)
+
+	leftDB := metadataObjectKey("testhost_home_2026-01-01T00:00:00Z",
+		"db.zst.age")
+	require.NoError(t, env.store.Put(context.Background(), leftDB,
+		strings.NewReader("db")))
+
+	store := faultstore.New(env.store)
+	store.OnDelete = func(key string) bool {
+		return strings.HasPrefix(key, "metadata/")
+	}
+	env.v.Storage = store
+
+	err := env.v.PruneBlobs(&vaultik.PruneOptions{JSON: true})
+
+	require.ErrorContains(t, err,
+		"1 metadata director(ies) with no manifest could not be deleted")
+	assert.True(t, env.store.hasKey(leftDB))
+
+	var result vaultik.PruneBlobsResult
+
+	require.NoError(t, json.Unmarshal(env.stdout.Bytes(), &result),
+		"stdout must hold the JSON document, got:\n%s", env.stdout.String())
+	assert.Equal(t, 1, result.MetadataDirsFailed)
+	assert.Equal(t, 0, result.MetadataDirsDeleted)
+}

internal/vaultik/remote_info_test.go

@@ -12,6 +12,7 @@ import (
 	"github.com/stretchr/testify/require"
 	"sneak.berlin/go/vaultik/internal/log"
 	"sneak.berlin/go/vaultik/internal/snapshot"
+	"sneak.berlin/go/vaultik/internal/ui"
 )
 
 // testBlobHashB is a blob that the manifest written by addRemote does
@@ -259,3 +260,24 @@ func TestRemoteInfo_DirectoryWithoutManifestLeavesOrphansKnown(t *testing.T) {
 	assert.NotContains(t, doc, "unreadable_manifests")
 	assert.NotContains(t, doc, "skipped_manifest_count")
 }
+
+// TestRemoteInfo_StatusLineUsesUIMarker checks that the remote info
+// status lines go through internal/ui: marker-prefixed, and silenced by
+// --quiet.
+func TestRemoteInfo_StatusLineUsesUIMarker(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	env := newListEnv(t)
+	env.addRemote(t, listRemoteID, time.Date(2026, 3, 2, 0, 0, 0, 0, time.UTC))
+
+	const statusLine = ui.Marker + " Scanning snapshot metadata...\n"
+
+	require.NoError(t, env.v.RemoteInfo(false))
+	assert.Contains(t, env.stdout.String(), statusLine)
+
+	env.stdout.Reset()
+	env.v.UI.SetQuiet(true)
+	require.NoError(t, env.v.RemoteInfo(false))
+	assert.NotContains(t, env.stdout.String(), "Scanning snapshot metadata")
+}

internal/vaultik/snapshot.go

@@ -7,6 +7,7 @@ import (
 	"os"
 	"path/filepath"
 	"regexp"
+	"slices"
 	"sort"
 	"strconv"
 	"strings"
@@ -44,6 +45,25 @@ var ErrPostBackupPruneFailed = errors.New("post-backup prune failed")
 // kept, so the caller can report it apart from a failed backup.
 var ErrFilesUnreadable = errors.New("file(s) could not be read")
 
+// ErrSourcePathEmpty is returned when --prune skipped the post-backup
+// prune because the scan found nothing in a configured path of a
+// snapshot, as in the mount point of a volume that is not mounted. The
+// snapshots are complete and kept, so the caller can report it apart
+// from a failed backup. A run that also skipped unreadable files
+// returns ErrFilesUnreadable instead.
+var ErrSourcePathEmpty = errors.New("source path(s) were empty")
+
+// ErrVolumeNotMounted is returned when --prune skipped the post-backup
+// prune because a directory that an earlier snapshot of the same name
+// found as a mount point was not found as one in this run: the volume
+// mounted there is not mounted, the run found no entry in it, or the
+// directory is no longer backed up. The snapshots are complete and
+// kept, so the caller can report it apart from a failed backup. A run
+// that also skipped unreadable files or found a configured path empty
+// returns ErrFilesUnreadable or ErrSourcePathEmpty instead.
+var ErrVolumeNotMounted = errors.New(
+	"mount point(s) an earlier snapshot recorded were not found")
+
 // listRecentLimit caps how many snapshot rows are fetched from the
 // local index for listing and purge operations.
 const listRecentLimit = 10000
@@ -134,17 +154,10 @@ func (v *Vaultik) CreateSnapshot(opts *SnapshotCreateOptions) error {
 		return err
 	}
 
-	// Process each named snapshot
-	filesUnreadable := 0
-
-	for snapIdx, snapName := range snapshotNames {
-		unreadable, err := v.createNamedSnapshot(
-			opts, hostname, snapName, snapIdx+1, len(snapshotNames))
-		if err != nil {
-			return err
-		}
-
-		filesUnreadable += unreadable
+	filesUnreadable, emptyPaths, unmountedPaths, err := v.createNamedSnapshots(
+		opts, hostname, snapshotNames)
+	if err != nil {
+		return err
 	}
 
 	// Print overall summary if multiple snapshots
@@ -154,13 +167,10 @@ func (v *Vaultik) CreateSnapshot(opts *SnapshotCreateOptions) error {
 	}
 
 	switch {
-	case opts.Prune && filesUnreadable > 0:
-		// An older snapshot may be the only one that still holds a file
-		// this run could not read.
-		log.Warn("Skipping post-backup prune",
-			"files_unreadable", filesUnreadable)
-		v.UI.Warningf("Skipped the post-backup prune because %d file(s) "+
-			"could not be read; older snapshots are kept.", filesUnreadable)
+	case opts.Prune && (filesUnreadable > 0 || len(emptyPaths) > 0 ||
+		len(unmountedPaths) > 0):
+		return v.skipPostBackupPrune(
+			filesUnreadable, emptyPaths, unmountedPaths)
 	case opts.Prune:
 		err = v.runPostBackupPrune(snapshotNames, opts.KeepNewerThan)
 		if err != nil {
@@ -171,6 +181,84 @@ func (v *Vaultik) CreateSnapshot(opts *SnapshotCreateOptions) error {
 	return v.finishCreateSnapshot(filesUnreadable)
 }
 
+// createNamedSnapshots creates each named snapshot in turn. It returns
+// the number of entries --skip-errors skipped because it could not read
+// or list them, each configured path in which the scan found nothing,
+// and, under --prune, each directory where an earlier snapshot found a
+// volume mounted and this run did not, the paths named with their
+// snapshot.
+func (v *Vaultik) createNamedSnapshots(
+	opts *SnapshotCreateOptions, hostname string, snapshotNames []string,
+) (int, []string, []string, error) {
+	filesUnreadable := 0
+
+	var emptyPaths, unmountedPaths []string
+
+	for snapIdx, snapName := range snapshotNames {
+		stats, err := v.createNamedSnapshot(
+			opts, hostname, snapName, snapIdx+1, len(snapshotNames))
+		if err != nil {
+			return 0, nil, nil, err
+		}
+
+		filesUnreadable += stats.totalFilesUnreadable
+
+		for _, dir := range stats.emptyPaths {
+			emptyPaths = append(emptyPaths, dir+" of snapshot "+snapName)
+		}
+
+		for _, dir := range stats.unmountedPaths {
+			unmountedPaths = append(unmountedPaths,
+				dir+" of snapshot "+snapName)
+		}
+	}
+
+	return filesUnreadable, emptyPaths, unmountedPaths, nil
+}
+
+// skipPostBackupPrune says why the post-backup prune does not run, naming
+// every cause, and returns the error the run ends with. An older snapshot
+// may be the only one that still holds a file this run could not read,
+// or what an empty path or a volume that is not mounted held. The
+// previous snapshot is no guide: after one such run it lacks them too.
+func (v *Vaultik) skipPostBackupPrune(
+	filesUnreadable int, emptyPaths, unmountedPaths []string,
+) error {
+	log.Warn("Skipping post-backup prune",
+		"files_unreadable", filesUnreadable, "empty_paths", emptyPaths,
+		"unmounted_paths", unmountedPaths)
+
+	if len(emptyPaths) > 0 {
+		v.UI.Warningf("Skipped the post-backup prune because nothing was "+
+			"found in %s; older snapshots are kept.",
+			strings.Join(emptyPaths, ", "))
+	}
+
+	if len(unmountedPaths) > 0 {
+		v.UI.Warningf("Skipped the post-backup prune because this backup "+
+			"did not find a mount point at %s, where an earlier snapshot "+
+			"found one: the volume is not mounted, this backup found no "+
+			"entry in it, or the directory is no longer backed up. Older "+
+			"snapshots are kept. Mount the volume again, or, if that is on "+
+			"purpose, remove the older snapshots by hand with "+
+			"'vaultik snapshot purge'.",
+			strings.Join(unmountedPaths, ", "))
+	}
+
+	if filesUnreadable > 0 {
+		v.UI.Warningf("Skipped the post-backup prune because %d file(s) "+
+			"could not be read; older snapshots are kept.", filesUnreadable)
+
+		return fmt.Errorf("%d %w", filesUnreadable, ErrFilesUnreadable)
+	}
+
+	if len(emptyPaths) > 0 {
+		return fmt.Errorf("%d %w", len(emptyPaths), ErrSourcePathEmpty)
+	}
+
+	return fmt.Errorf("%d %w", len(unmountedPaths), ErrVolumeNotMounted)
+}
+
 // finishCreateSnapshot ends a run whose snapshots are all complete and
 // kept. Like finishRestore, it returns an error when --skip-errors
 // skipped anything it could not read or list; otherwise it prints the
@@ -219,9 +307,10 @@ func (v *Vaultik) snapshotNamesToCreate(requested []string) ([]string, error) {
 }
 
 // runPostBackupPrune drops older snapshots of the given names and removes
-// orphan blobs from remote storage. If keepNewerThan is set (e.g. "4w"),
-// snapshots newer than that duration are kept. Otherwise only the latest
-// snapshot of each name is kept.
+// from remote storage the orphan blobs and the directories under
+// metadata/ with no manifest, as PruneBlobs does. If keepNewerThan is set
+// (e.g. "4w"), snapshots newer than that duration are kept. Otherwise only
+// the latest snapshot of each name is kept.
 func (v *Vaultik) runPostBackupPrune(
 	snapshotNames []string, keepNewerThan string,
 ) error {
@@ -248,7 +337,7 @@ func (v *Vaultik) runPostBackupPrune(
 
 	err = v.PruneBlobs(&PruneOptions{Force: true})
 	if err != nil {
-		return fmt.Errorf("pruning orphaned blobs: %w", err)
+		return fmt.Errorf("pruning the destination store: %w", err)
 	}
 
 	return nil
@@ -274,6 +363,13 @@ type snapshotStats struct {
 	// could not be read or listed.
 	totalFilesUnreadable int
 
+	// The configured paths in which the scan found nothing.
+	emptyPaths []string
+
+	// Under --prune, the directories where an earlier snapshot of the
+	// same name found a volume mounted and this one did not.
+	unmountedPaths []string
+
 	// The sizes of all blobs the snapshot references, set by
 	// finalizeSnapshotMetadata once snapshot_blobs is populated.
 	blobSize             int64
@@ -281,11 +377,10 @@ type snapshotStats struct {
 }
 
 // createNamedSnapshot creates a single named snapshot and returns the
-// number of entries --skip-errors skipped because it could not read or
-// list them.
+// statistics of its scan.
 func (v *Vaultik) createNamedSnapshot(
 	opts *SnapshotCreateOptions, hostname, snapName string, idx, total int,
-) (int, error) {
+) (*snapshotStats, error) {
 	snapshotStartTime := time.Now()
 
 	if total > 1 {
@@ -294,12 +389,12 @@ func (v *Vaultik) createNamedSnapshot(
 
 	resolvedDirs, err := v.resolveSnapshotPaths(snapName)
 	if err != nil {
-		return 0, err
+		return nil, err
 	}
 
 	previousSnapshotID, err := v.previousSnapshotID(snapName)
 	if err != nil {
-		return 0, err
+		return nil, err
 	}
 
 	scanner := v.ScannerFactory(snapshot.ScannerParams{
@@ -314,7 +409,7 @@ func (v *Vaultik) createNamedSnapshot(
 	snapshotID, err := v.SnapshotManager.CreateSnapshotWithName(
 		v.ctx, hostname, snapName, v.Globals.Version, v.Globals.Commit)
 	if err != nil {
-		return 0, fmt.Errorf("creating snapshot: %w", err)
+		return nil, fmt.Errorf("creating snapshot: %w", err)
 	}
 
 	log.Info("Beginning snapshot", "snapshot_id", snapshotID, "name", snapName)
@@ -322,12 +417,12 @@ func (v *Vaultik) createNamedSnapshot(
 
 	stats, err := v.scanAllDirectories(scanner, resolvedDirs, snapshotID)
 	if err != nil {
-		return 0, err
+		return nil, err
 	}
 
 	err = v.finalizeSnapshotMetadata(snapshotID, stats)
 	if err != nil {
-		return 0, err
+		return nil, err
 	}
 
 	log.Info("Snapshot complete",
@@ -340,7 +435,55 @@ func (v *Vaultik) createNamedSnapshot(
 
 	v.printSnapshotSummary(snapshotID, snapshotStartTime, stats)
 
-	return stats.totalFilesUnreadable, nil
+	if opts.Prune {
+		stats.unmountedPaths, err = v.findUnmountedPaths(snapName, snapshotID)
+		if err != nil {
+			return nil, err
+		}
+	}
+
+	return stats, nil
+}
+
+// findUnmountedPaths returns each directory that an earlier snapshot
+// named snapName in the local index recorded as a mount point and
+// snapshot snapshotID did not, as when the volume mounted there is not
+// mounted.
+func (v *Vaultik) findUnmountedPaths(
+	snapName, snapshotID string,
+) ([]string, error) {
+	found, err := v.Repositories.Snapshots.GetMountPoints(v.ctx, snapshotID)
+	if err != nil {
+		return nil, err
+	}
+
+	snapshots, err := v.Repositories.Snapshots.ListRecent(v.ctx, listRecentLimit)
+	if err != nil {
+		return nil, fmt.Errorf("listing snapshots: %w", err)
+	}
+
+	var unmounted []string
+
+	for _, s := range snapshots {
+		if s.ID.String() == snapshotID ||
+			parseSnapshotName(s.ID.String(), s.Hostname.String()) != snapName {
+			continue
+		}
+
+		recorded, err := v.Repositories.Snapshots.GetMountPoints(
+			v.ctx, s.ID.String())
+		if err != nil {
+			return nil, err
+		}
+
+		for _, dir := range recorded {
+			if !slices.Contains(found, dir) && !slices.Contains(unmounted, dir) {
+				unmounted = append(unmounted, dir)
+			}
+		}
+	}
+
+	return unmounted, nil
 }
 
 // previousSnapshotID returns the ID of the most recent completed snapshot
@@ -362,7 +505,8 @@ func (v *Vaultik) previousSnapshotID(snapName string) (string, error) {
 }
 
 // resolveSnapshotPaths resolves source directories to absolute paths
-// with symlink resolution.
+// with symlink resolution. A path that is a symlink whose target does
+// not exist is an error.
 func (v *Vaultik) resolveSnapshotPaths(snapName string) ([]string, error) {
 	snapConfig := v.Config.Snapshots[snapName]
 	resolvedDirs := make([]string, 0, len(snapConfig.Paths))
@@ -375,12 +519,18 @@ func (v *Vaultik) resolveSnapshotPaths(snapName string) ([]string, error) {
 
 		resolvedPath, err := filepath.EvalSymlinks(absPath)
 		if err != nil {
-			if os.IsNotExist(err) {
-				resolvedPath = absPath
-			} else {
+			// A path that does not exist is left for the scan to report.
+			// One that exists is a symlink whose target is gone, as one
+			// into a volume that is not mounted: the scan would record
+			// only the link, and --prune would then drop the older
+			// snapshots that hold the files.
+			_, lstatErr := os.Lstat(absPath)
+			if !os.IsNotExist(err) || lstatErr == nil {
 				return nil, fmt.Errorf(
 					"failed to resolve symlinks for %s: %w", absPath, err)
 			}
+
+			resolvedPath = absPath
 		}
 
 		resolvedDirs = append(resolvedDirs, resolvedPath)
@@ -434,6 +584,10 @@ func (v *Vaultik) scanAllDirectories(
 		stats.totalBytesUploaded += result.BytesUploaded
 		stats.uploadDuration += result.UploadDuration
 
+		if result.EntriesFound == 0 {
+			stats.emptyPaths = append(stats.emptyPaths, dir)
+		}
+
 		log.Info("Directory scan complete",
 			"path", dir,
 			"files", result.FilesScanned,
@@ -865,7 +1019,7 @@ func (v *Vaultik) VerifySnapshotWithOptions(
 		v.printlnStdout()
 
 		// Check each blob is present with the size the manifest records.
-		v.stdoutf("Checking blob presence and sizes...\n")
+		v.UI.Beginf("Checking blob presence and sizes...")
 	}
 
 	v.checkSnapshotDatabase(remoteKey, result)
@@ -1301,7 +1455,7 @@ const pruneCommandHint = "vaultik prune"
 // snapshotRemoveCommandHint is the command suggested, with the
 // snapshot's ID, when a remove could not reach the destination store:
 // running it again removes the snapshot's metadata there, which
-// `vaultik prune` never does.
+// `vaultik prune` never does while the manifest is there.
 const snapshotRemoveCommandHint = "vaultik snapshot remove"
 
 // RemoveSnapshot removes a snapshot from the local index database and,
@@ -1504,7 +1658,8 @@ func (v *Vaultik) confirmRemoveSnapshot(snapshotID string, opts *RemoveOptions)
 // the local index, its removal there has already happened, so a failure
 // is only a warning telling the user to run `vaultik snapshot remove`
 // for the snapshot again once the destination store is reachable
-// (`vaultik prune` never removes snapshot metadata).
+// (`vaultik prune` never removes snapshot metadata that has its
+// manifest).
 func (v *Vaultik) removeSnapshotRemote(
 	snapshotID string, inLocalIndex bool, markerErr error,
 	opts *RemoveOptions,

internal/vaultik/snapshot_prune_test.go

@@ -1,8 +1,18 @@
 package vaultik_test
 
 import (
+	"context"
+	"os"
+	"path/filepath"
+	"syscall"
 	"testing"
 
+	"github.com/spf13/afero"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"sneak.berlin/go/vaultik/internal/config"
+	"sneak.berlin/go/vaultik/internal/log"
+	"sneak.berlin/go/vaultik/internal/snapshot"
 	"sneak.berlin/go/vaultik/internal/vaultik"
 )
 
@@ -25,3 +35,379 @@ func TestSnapshotCreateOptions_PruneFlag(t *testing.T) {
 		t.Error("Expected Prune to be false")
 	}
 }
+
+// A backup under --prune that finds nothing in a configured path, as in
+// the mount point of a volume that is not mounted, does not prune: run
+// after run, the snapshot that holds the files is kept with everything
+// it stored, and the run fails. That holds whether the empty path is the
+// snapshot's only path or one of two. See
+// https://git.eeqj.de/sneak/vaultik/issues/388.
+func TestBackupWithEmptySourcePathDoesNotPrune(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	// emptied is the path, relative to the source directory, that is
+	// emptied after the first backup.
+	const (
+		snapshotName = "media"
+		emptied      = "music"
+	)
+
+	tests := []struct {
+		name  string
+		paths []string // relative to the source directory
+	}{
+		{name: "only path", paths: []string{emptied}},
+		{name: "one of two paths", paths: []string{emptied, "docs"}},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			ctx := context.Background()
+			env := newDeletedCountEnv(t, map[string][]byte{
+				emptied + "/a.mp3": []byte("song a"),
+				emptied + "/b.mp3": []byte("song b"),
+				"docs/notes.txt":   []byte("notes"),
+			})
+
+			paths := make([]string, 0, len(tt.paths))
+
+			for _, rel := range tt.paths {
+				paths = append(paths, filepath.Join(env.src, rel))
+			}
+
+			env.v.Config.Snapshots[snapshotName] = config.SnapshotConfig{
+				Paths: paths,
+			}
+			env.backUp(t, snapshotName)
+
+			firstID := localSnapshotID(ctx, t, env.v.Repositories, snapshotName)
+			stored, err := env.v.Storage.List(ctx, "")
+			require.NoError(t, err)
+
+			// A volume that is not mounted leaves its mount point behind
+			// as an empty directory.
+			emptiedDir := filepath.Join(env.src, emptied)
+			require.NoError(t, os.RemoveAll(emptiedDir))
+			require.NoError(t, os.Mkdir(emptiedDir, 0o750))
+
+			for range 2 {
+				env.out.Reset()
+
+				err := env.v.CreateSnapshot(&vaultik.SnapshotCreateOptions{
+					Prune:     true,
+					Snapshots: []string{snapshotName},
+				})
+				require.ErrorIs(t, err, vaultik.ErrSourcePathEmpty)
+				assert.Contains(t, env.out.String(),
+					"Skipped the post-backup prune because nothing was found in ")
+				assert.Contains(t, env.out.String(),
+					emptied+" of snapshot "+snapshotName+";")
+				assert.NotContains(t, env.out.String(), "Running post-backup prune.")
+			}
+
+			snapshots, err := env.v.Repositories.Snapshots.ListRecent(
+				ctx, listRecentTestLimit)
+			require.NoError(t, err)
+			require.Len(t, snapshots, 3)
+			assert.Equal(t, firstID, snapshots[2].ID.String(),
+				"the snapshot that holds the files is kept")
+
+			for _, key := range stored {
+				_, err := env.v.Storage.Stat(ctx, key)
+				require.NoError(t, err, "%s is kept", key)
+			}
+		})
+	}
+}
+
+// A backup under --prune of a configured path that is a symlink whose
+// target is gone, as one into a volume that is not mounted, fails before
+// anything is pruned: the snapshot that holds the files is kept with
+// everything it stored. See https://git.eeqj.de/sneak/vaultik/issues/388.
+func TestBackupThroughSymlinkWhoseTargetIsGoneDoesNotPrune(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	const snapshotName = "photos"
+
+	ctx := context.Background()
+	env := newDeletedCountEnv(t, map[string][]byte{
+		"volume/a.jpg": []byte("photo a"),
+		"volume/b.jpg": []byte("photo b"),
+	})
+
+	target := filepath.Join(env.src, "volume")
+	link := filepath.Join(env.src, "photos")
+	require.NoError(t, os.Symlink(target, link))
+	env.setSnapshot(snapshotName, "photos")
+	env.backUp(t, snapshotName)
+
+	firstID := localSnapshotID(ctx, t, env.v.Repositories, snapshotName)
+	stored, err := env.v.Storage.List(ctx, "")
+	require.NoError(t, err)
+
+	// The volume is not mounted, so the symlink points at nothing.
+	require.NoError(t, os.RemoveAll(target))
+
+	env.out.Reset()
+	err = env.v.CreateSnapshot(&vaultik.SnapshotCreateOptions{
+		Prune:     true,
+		Snapshots: []string{snapshotName},
+	})
+	require.ErrorIs(t, err, os.ErrNotExist)
+	assert.Contains(t, err.Error(), link)
+	assert.NotContains(t, env.out.String(), "Running post-backup prune.")
+
+	snapshots, err := env.v.Repositories.Snapshots.ListRecent(
+		ctx, listRecentTestLimit)
+	require.NoError(t, err)
+	require.Len(t, snapshots, 1)
+	assert.Equal(t, firstID, snapshots[0].ID.String(),
+		"the snapshot that holds the files is kept")
+
+	for _, key := range stored {
+		_, err := env.v.Storage.Stat(ctx, key)
+		require.NoError(t, err, "%s is kept", key)
+	}
+}
+
+// A backup under --skip-errors --prune that both skipped a file it could
+// not read and found nothing in a configured path names the empty path
+// too when it skips the prune. See
+// https://git.eeqj.de/sneak/vaultik/issues/388.
+func TestBackupWithEmptySourcePathAndUnreadableFileNamesBoth(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	const snapshotName = "media"
+
+	env := newDeletedCountEnv(t, map[string][]byte{
+		"docs/notes.txt": []byte("notes"),
+	})
+	require.NoError(t, os.Mkdir(filepath.Join(env.src, "music"), 0o750))
+	env.v.Config.Snapshots[snapshotName] = config.SnapshotConfig{
+		Paths: []string{
+			filepath.Join(env.src, "docs"),
+			filepath.Join(env.src, "music"),
+		},
+	}
+
+	// A mode does not lock out root, who runs the tests, so opening the
+	// file is made to fail instead.
+	env.v.Fs = &openFailFs{
+		path: filepath.Join(env.src, "docs", "notes.txt"),
+		err:  os.ErrPermission,
+	}
+
+	err := env.v.CreateSnapshot(&vaultik.SnapshotCreateOptions{
+		Prune:      true,
+		SkipErrors: true,
+		Snapshots:  []string{snapshotName},
+	})
+	require.ErrorIs(t, err, vaultik.ErrFilesUnreadable)
+	assert.Contains(t, env.out.String(),
+		"Skipped the post-backup prune because 1 file(s) could not be read")
+	assert.Contains(t, env.out.String(),
+		"Skipped the post-backup prune because nothing was found in ")
+	assert.Contains(t, env.out.String(), "music of snapshot "+snapshotName+";")
+	assert.NotContains(t, env.out.String(), "Running post-backup prune.")
+}
+
+// A backup under --prune that finds something in each configured path
+// prunes the previous snapshot, also when a path is a single file. See
+// https://git.eeqj.de/sneak/vaultik/issues/388.
+func TestBackupWithNoEmptySourcePathPrunes(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	const (
+		snapshotName = "album"
+		file         = "pictures/one.jpg" // relative to the source directory
+	)
+
+	tests := []struct {
+		name string
+		path string // relative to the source directory
+	}{
+		{name: "directory", path: filepath.Dir(file)},
+		{name: "single file", path: file},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			ctx := context.Background()
+			env := newDeletedCountEnv(t, map[string][]byte{
+				file: []byte("picture"),
+			})
+			env.setSnapshot(snapshotName, tt.path)
+			env.backUp(t, snapshotName)
+
+			firstID := localSnapshotID(ctx, t, env.v.Repositories, snapshotName)
+
+			require.NoError(t, env.v.CreateSnapshot(&vaultik.SnapshotCreateOptions{
+				Prune:     true,
+				Snapshots: []string{snapshotName},
+			}))
+
+			snapshots, err := env.v.Repositories.Snapshots.ListRecent(
+				ctx, listRecentTestLimit)
+			require.NoError(t, err)
+			require.Len(t, snapshots, 1, "the previous snapshot is pruned")
+			assert.NotEqual(t, firstID, snapshots[0].ID.String())
+		})
+	}
+}
+
+// automountFs is the real filesystem with a volume at volumeDir that is
+// mounted on first access, as by an autofs map that shows its mount
+// points before mounting them: listing volumeDir mounts the volume or,
+// while cannotMount, fails with "no such file or directory".
+type automountFs struct {
+	afero.OsFs
+
+	volumeDir   string
+	cannotMount bool
+	mounted     bool
+}
+
+//nolint:ireturn // afero.Fs.Open is defined to return the interface.
+func (f *automountFs) Open(name string) (afero.File, error) {
+	if name == f.volumeDir && f.cannotMount {
+		return nil, &os.PathError{Op: "open", Path: name, Err: syscall.ENOENT}
+	}
+
+	if name == f.volumeDir {
+		f.mounted = true
+	}
+
+	return f.OsFs.Open(name)
+}
+
+// A backup under --prune in which a volume that an earlier snapshot found
+// mounted below the configured path is missing does not prune: run after
+// run, the snapshot that holds the volume's files is kept with everything
+// it stored, and the run fails. Once the volume is back, the prune runs.
+// The volume is mounted on first access and every backup starts with it
+// not mounted, so its directory is on its parent's device until the walk
+// lists it. While the volume is missing, its directory is left empty, or
+// listing it fails with "no such file or directory", as when an autofs
+// volume cannot be mounted, which the walk counts as a directory removed
+// during the backup. See https://git.eeqj.de/sneak/vaultik/issues/395.
+func TestBackupWithVolumeNotMountedDoesNotPrune(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	tests := []struct {
+		name         string
+		listingFails bool
+	}{
+		{name: "directory left empty", listingFails: false},
+		{name: "listing fails", listingFails: true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			backUpWithVolumeNotMounted(t, tt.listingFails)
+		})
+	}
+}
+
+// backUpWithVolumeNotMounted runs the backups of
+// TestBackupWithVolumeNotMountedDoesNotPrune. While the volume is
+// missing, listing its directory fails if listingFails; otherwise the
+// directory is empty.
+func backUpWithVolumeNotMounted(t *testing.T, listingFails bool) {
+	t.Helper()
+
+	// volume is the directory, below the configured path, where the
+	// volume is mounted.
+	const (
+		snapshotName = "data"
+		volume       = "nas"
+	)
+
+	ctx := context.Background()
+	env := newDeletedCountEnv(t, map[string][]byte{
+		volume + "/a.txt": []byte("file a"),
+		"notes.txt":       []byte("notes"),
+	})
+	env.setSnapshot(snapshotName, "")
+	prune := &vaultik.SnapshotCreateOptions{
+		Prune: true, Snapshots: []string{snapshotName},
+	}
+
+	// The volume's directory is on the volume's device, 2, while the
+	// volume is mounted. Everything else is on device 1.
+	volumeDir := filepath.Join(env.src, volume)
+	fs := &automountFs{volumeDir: volumeDir}
+	newScanner := env.v.ScannerFactory
+	env.v.ScannerFactory = func(params snapshot.ScannerParams) *snapshot.Scanner {
+		fs.mounted = false
+		params.Fs = fs
+		params.DeviceNumber = func(info os.FileInfo) (uint64, bool) {
+			if info.Name() == volume && fs.mounted {
+				return 2, true
+			}
+
+			return 1, true
+		}
+
+		return newScanner(params)
+	}
+
+	env.backUp(t, snapshotName)
+
+	firstID := localSnapshotID(ctx, t, env.v.Repositories, snapshotName)
+	stored, err := env.v.Storage.List(ctx, "")
+	require.NoError(t, err)
+
+	// The volume goes missing.
+	fs.cannotMount = listingFails
+
+	if !listingFails {
+		require.NoError(t, os.RemoveAll(volumeDir))
+		require.NoError(t, os.Mkdir(volumeDir, 0o750))
+	}
+
+	for range 2 {
+		env.out.Reset()
+
+		err := env.v.CreateSnapshot(prune)
+		require.ErrorIs(t, err, vaultik.ErrVolumeNotMounted)
+		assert.Contains(t, env.out.String(),
+			"did not find a mount point at "+volumeDir+" of snapshot "+snapshotName)
+		assert.Contains(t, env.out.String(), "'vaultik snapshot purge'")
+		assert.NotContains(t, env.out.String(), "Running post-backup prune.")
+	}
+
+	snapshots, err := env.v.Repositories.Snapshots.ListRecent(
+		ctx, listRecentTestLimit)
+	require.NoError(t, err)
+	require.Len(t, snapshots, 3)
+	assert.Equal(t, firstID, snapshots[2].ID.String(),
+		"the snapshot that holds the volume's files is kept")
+
+	for _, key := range stored {
+		_, err := env.v.Storage.Stat(ctx, key)
+		require.NoError(t, err, "%s is kept", key)
+	}
+
+	// The volume is back.
+	fs.cannotMount = false
+
+	require.NoError(t, os.WriteFile(
+		filepath.Join(volumeDir, "a.txt"), []byte("file a"), 0o600))
+	require.NoError(t, env.v.CreateSnapshot(prune))
+
+	snapshots, err = env.v.Repositories.Snapshots.ListRecent(
+		ctx, listRecentTestLimit)
+	require.NoError(t, err)
+	require.Len(t, snapshots, 1, "the older snapshots are pruned")
+}

internal/vaultik/storage_bind.go

@@ -30,7 +30,7 @@ var errStorageBindingMismatch = errors.New(
 //     nothing and return nil.
 //   - When the two differ, refuse with an error that tells the user
 //     how to recover (revert the config, or run `vaultik database
-//     purge` to discard the local index and rebuild against the new
+//     delete` to discard the local index and rebuild against the new
 //     destination on the next backup).
 //
 // Read-only inspection commands (remote info, snapshot list, etc.)

internal/vaultik/verify.go

@@ -190,7 +190,7 @@ func (v *Vaultik) loadVerificationData(
 	log.Info("Downloading manifest", "remote_key", remoteKey)
 
 	if !opts.JSON && !v.UI.Quiet() {
-		v.stdoutf("Downloading manifest...\n")
+		v.UI.Beginf("Downloading manifest...")
 	}
 
 	manifest, err := v.downloadManifestByKey(remoteKey)
@@ -205,9 +205,9 @@ func (v *Vaultik) loadVerificationData(
 		"manifest_total_size", ubytes(manifest.TotalCompressedSize))
 
 	if !opts.JSON && !v.UI.Quiet() {
-		v.stdoutf("Manifest loaded: %d blobs (%s)\n",
+		v.UI.Completef("Manifest loaded: %d blobs (%s)",
 			manifest.BlobCount, ubytes(manifest.TotalCompressedSize))
-		v.stdoutf("Downloading and decrypting database...\n")
+		v.UI.Beginf("Downloading and decrypting database...")
 	}
 
 	tdb, err := v.downloadVerifiedSnapshotDB(
@@ -235,7 +235,7 @@ func (v *Vaultik) loadVerificationData(
 		"db_total_size", ubytes(dbTotalSize))
 
 	if !opts.JSON && !v.UI.Quiet() {
-		v.stdoutf("Database loaded: %d blobs (%s)\n",
+		v.UI.Completef("Database loaded: %d blobs (%s)",
 			len(dbBlobs), ubytes(dbTotalSize))
 	}
 
@@ -295,7 +295,7 @@ func (v *Vaultik) runVerificationSteps(
 	identities []age.Identity,
 ) error {
 	if !opts.JSON && !v.UI.Quiet() {
-		v.stdoutf("Verifying manifest against database...\n")
+		v.UI.Beginf("Verifying manifest against database...")
 	}
 
 	err := v.verifyManifestAgainstDatabase(manifest, dbBlobs)
@@ -304,8 +304,8 @@ func (v *Vaultik) runVerificationSteps(
 	}
 
 	if !opts.JSON && !v.UI.Quiet() {
-		v.stdoutf("Manifest verified.\n")
-		v.stdoutf("Checking blob existence in remote storage...\n")
+		v.UI.Completef("Manifest verified.")
+		v.UI.Beginf("Checking blob existence in remote storage...")
 	}
 
 	err = v.verifyBlobExistenceFromDB(dbBlobs, result)
@@ -314,8 +314,8 @@ func (v *Vaultik) runVerificationSteps(
 	}
 
 	if !opts.JSON && !v.UI.Quiet() {
-		v.stdoutf("All blobs exist.\n")
-		v.stdoutf("Downloading and verifying blob contents (%d blobs, %s)...\n",
+		v.UI.Completef("All blobs exist.")
+		v.UI.Beginf("Downloading and verifying blob contents (%d blobs, %s)...",
 			len(dbBlobs), ubytes(totalSize))
 	}
 
@@ -790,7 +790,7 @@ func (v *Vaultik) performDeepVerificationFromDB(
 		)
 
 		if !opts.JSON && !v.UI.Quiet() {
-			v.stdoutf("  Verified %d/%d blobs (%d remaining) - %s/%s - elapsed %s, eta %s\n",
+			v.UI.Progressf("Verified %d/%d blobs (%d remaining) - %s/%s - elapsed %s, eta %s",
 				i+1, len(blobs), remaining,
 				ubytes(bytesProcessed),
 				ubytes(totalBytesExpected),

internal/vaultik/verify_quiet_test.go

@@ -100,3 +100,51 @@ func TestVerify_QuietSuppressesReport(t *testing.T) {
 	require.Empty(t, stdout.String(),
 		"a failed verify must write no report under --quiet")
 }
+
+// TestVerify_DeepStatusLineUsesUIMarker checks that the deep verify
+// status lines go through internal/ui: marker-prefixed, and silenced by
+// --quiet.
+func TestVerify_DeepStatusLineUsesUIMarker(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	fs := afero.NewOsFs()
+	tempDir := t.TempDir()
+
+	dataDir := filepath.Join(tempDir, "source")
+	storeDir := t.TempDir()
+	dbPath := filepath.Join(tempDir, "index.sqlite")
+
+	require.NoError(t, fs.MkdirAll(dataDir, 0o755))
+	require.NoError(t, afero.WriteFile(fs,
+		filepath.Join(dataDir, "data.bin"),
+		bytesPattern("marker-", 64*1024), 0o644))
+
+	ctx := context.Background()
+
+	cfg, storer, snapshotID := runFileStorageBackup(
+		ctx, t, fs, dataDir, storeDir, dbPath, 32*1024, 128*1024)
+
+	var stdout bytes.Buffer
+
+	v := &vaultik.Vaultik{
+		Config:  cfg,
+		Storage: storer,
+		Fs:      fs,
+		Stdout:  &stdout,
+		Stderr:  io.Discard,
+		UI:      ui.NewWithColor(&stdout, false),
+	}
+	v.SetContext(ctx)
+
+	opts := &vaultik.VerifyOptions{Deep: true}
+
+	require.NoError(t, v.VerifySnapshotWithOptions(snapshotID, opts))
+	require.Contains(t, stdout.String(),
+		"\n"+ui.Marker+" Downloading manifest...\n")
+
+	stdout.Reset()
+	v.UI.SetQuiet(true)
+	require.NoError(t, v.VerifySnapshotWithOptions(snapshotID, opts))
+	require.NotContains(t, stdout.String(), "Downloading manifest")
+}

package.json

@@ -0,0 +1,5 @@
+{
+  "devDependencies": {
+    "prettier": "3.8.1"
+  }
+}

script/bootstrap

@@ -3,11 +3,20 @@
 # this repo. Idempotent: every install is guarded by a check so already
 # installed tools are skipped. Base tooling comes from nix, apt, brew,
 # or apk (detected in that order); assumes NOTHING is present (not git,
-# make, or go).
+# make, or go). Node is used directly if installed; otherwise it is
+# installed at a pinned version via nvm (installing nvm itself first,
+# from a hash-verified release archive, never curl | sh).
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
+# Pinned versions, 2026-07-06
+NODE_VERSION="22.17.0"
+NVM_VERSION="0.40.3"
+# sha256 of https://github.com/nvm-sh/nvm/archive/refs/tags/v0.40.3.tar.gz
+NVM_SHA256="5f4d6aaa04a177dc93c985e31dbc411ab6b8c6e1e21d8015dbc1372625fcd1d0"
+YARN_VERSION="1.22.22"
+
 PKGMGR=""
 SUDO=""
 
@@ -48,6 +57,69 @@ missing() {
     ! command -v "$1" >/dev/null 2>&1
 }
 
+# verify_sha256 <file> <expected-hash>
+verify_sha256() {
+    if command -v sha256sum >/dev/null 2>&1; then
+        actual="$(sha256sum "$1" | cut -d' ' -f1)"
+    else
+        actual="$(shasum -a 256 "$1" | cut -d' ' -f1)"
+    fi
+    if [ "$actual" != "$2" ]; then
+        echo "bootstrap: sha256 mismatch for $1" >&2
+        echo "  expected: $2" >&2
+        echo "  actual:   $actual" >&2
+        exit 1
+    fi
+}
+
+# nvm is a bash script; run a command in a bash with nvm loaded
+nvm_sh() {
+    bash -c ". \"\$HOME/.nvm/nvm.sh\" && $*"
+}
+
+ensure_nvm() {
+    [ -s "$HOME/.nvm/nvm.sh" ] && return 0
+    # nvm prerequisites; nvm itself requires bash
+    if missing bash; then pkg_install bash bash bash bash; fi
+    if missing curl; then pkg_install curl curl curl curl; fi
+    if missing git; then pkg_install git git git git; fi
+    tmp="$(mktemp -d)"
+    curl -fsSL -o "$tmp/nvm.tar.gz" \
+        "https://github.com/nvm-sh/nvm/archive/refs/tags/v${NVM_VERSION}.tar.gz"
+    verify_sha256 "$tmp/nvm.tar.gz" "$NVM_SHA256"
+    mkdir -p "$HOME/.nvm"
+    tar -xzf "$tmp/nvm.tar.gz" -C "$HOME/.nvm" --strip-components=1
+    rm -rf "$tmp"
+}
+
+ensure_node() {
+    if ! missing node; then return 0; fi
+    ensure_nvm
+    nvm_sh "nvm install $NODE_VERSION"
+}
+
+ensure_yarn() {
+    if ! missing yarn; then return 0; fi
+    if ! missing corepack; then
+        corepack enable
+        corepack prepare "yarn@$YARN_VERSION" --activate
+    elif [ -s "$HOME/.nvm/nvm.sh" ]; then
+        nvm_sh "nvm use $NODE_VERSION >/dev/null && corepack enable && \
+            corepack prepare yarn@$YARN_VERSION --activate"
+    else
+        npm install -g "yarn@$YARN_VERSION"
+    fi
+}
+
+install_js_deps() {
+    if missing yarn && [ -s "$HOME/.nvm/nvm.sh" ]; then
+        nvm_sh "nvm use $NODE_VERSION >/dev/null && cd \"$ROOT\" && \
+            yarn install --frozen-lockfile"
+    else
+        yarn install --frozen-lockfile
+    fi
+}
+
 # Docker is a hard requirement, not a nice-to-have: script/lint and
 # script/test build the lint and test phases of the Dockerfile, the only
 # place the linter and the tests run, and script/check and
@@ -103,6 +175,8 @@ main() {
     # Base tooling (every repo)
     if missing git; then pkg_install git git git git; fi
     if missing make; then pkg_install gnumake make make make; fi
+    # script/install-go, script/install-goreleaser and nvm download with it.
+    if missing curl; then pkg_install curl curl curl curl; fi
 
     # Go toolchain: the host's own, or else the version go.mod names,
     # hash-verified, in .tool/go. That directory is not on the caller's
@@ -131,6 +205,11 @@ main() {
 
     go mod download
 
+    # prettier, which script/fmt and script/fmt-check run on Markdown.
+    ensure_node
+    ensure_yarn
+    install_js_deps
+
     # Last, so that everything installable is installed before the one
     # thing this script cannot install decides the outcome.
     require_docker

script/fmt

@@ -4,11 +4,31 @@ set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
+# Must match the pin in script/bootstrap.
+NODE_VERSION="22.17.0"
+
+# script/bootstrap installs node and yarn under nvm and leaves neither
+# on the PATH of the shell that called it, so resolve the pinned
+# toolchain here the way bootstrap's own install step does. nvm is a
+# bash script, hence the subshell.
+run_yarn() {
+    if command -v yarn >/dev/null 2>&1; then
+        exec yarn "$@"
+    fi
+    if [ ! -s "$HOME/.nvm/nvm.sh" ]; then
+        echo "fmt: no yarn; run script/bootstrap first" >&2
+        exit 1
+    fi
+    exec bash -c '. "$HOME/.nvm/nvm.sh" && nvm use "$1" >/dev/null &&
+        shift && exec yarn "$@"' bash "$NODE_VERSION" "$@"
+}
+
 main() {
     cd "$ROOT"
     # Where script/bootstrap installs Go when the host has none.
     PATH="$PATH:$ROOT/.tool/go/bin"
     go fmt ./...
+    run_yarn run prettier --write '**/*.md' --tab-width 4 --prose-wrap always
 }
 
 main "$@"

script/fmt-check

@@ -3,11 +3,30 @@
 # writing. It checks every Go file outside .tool, which is more than
 # script/fmt formats: `go fmt ./...` skips `testdata` directories and
 # files and directories whose names start with `.` or `_`. Fix a file
-# only this reports with `gofmt -w`.
+# only this reports with `gofmt -w`. Markdown is checked with prettier.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
+# Must match the pin in script/bootstrap.
+NODE_VERSION="22.17.0"
+
+# script/bootstrap installs node and yarn under nvm and leaves neither
+# on the PATH of the shell that called it, so resolve the pinned
+# toolchain here the way bootstrap's own install step does. nvm is a
+# bash script, hence the subshell.
+run_yarn() {
+    if command -v yarn >/dev/null 2>&1; then
+        exec yarn "$@"
+    fi
+    if [ ! -s "$HOME/.nvm/nvm.sh" ]; then
+        echo "fmt-check: no yarn; run script/bootstrap first" >&2
+        exit 1
+    fi
+    exec bash -c '. "$HOME/.nvm/nvm.sh" && nvm use "$1" >/dev/null &&
+        shift && exec yarn "$@"' bash "$NODE_VERSION" "$@"
+}
+
 main() {
     cd "$ROOT"
     # Where script/bootstrap installs Go when the host has none.
@@ -23,6 +42,7 @@ main() {
         echo "$unformatted" >&2
         exit 1
     fi
+    run_yarn run prettier --check '**/*.md' --tab-width 4 --prose-wrap always
 }
 
 main "$@"

yarn.lock

@@ -0,0 +1,8 @@
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+# yarn lockfile v1
+
+
+prettier@3.8.1:
+  version "3.8.1"
+  resolved "https://registry.yarnpkg.com/prettier/-/prettier-3.8.1.tgz#edf48977cf991558f4fcbd8a3ba6015ba2a3a173"
+  integrity sha512-UOnG6LftzbdaHZcKoPFtOcCKztrQ57WkHDeRD9t/PTQtmT0NHSeWWepj6pS0z/N7+08BHFDQVUrfmfMRcZwbMg==