Leave remote info orphan figures unknown when a manifest is unreadable (closes #228)

When a manifest could not be read, remote info skipped it, counted that
snapshot's blobs as orphaned and advised running prune. The orphan
figures are now unknown in that case, with no prune advice; --json gives
them as null and lists the unreadable remote keys in
unreadable_manifests. Only a listed manifest.json.zst is read, so a
directory without one, as an interrupted backup leaves, keeps the
figures known.

Names under metadata/ were used unchecked and printed raw. A name that
is not a remote key is now skipped with a warning. A manifest under it
is not read either, so it also leaves the figures unknown; --json counts
such manifests in skipped_manifests.

The closing log line carries the unreadable manifest count in place of
the orphan count.

Model: opus-5-5

README.md

@@ -391,11 +391,12 @@ recipients, and local database statistics.
 **`remote info`**: Show storage backend type and location plus detailed
 remote storage inventory: per-snapshot metadata sizes, blob counts, and
 orphaned blob detection. A name under `metadata/` that is not a remote
-key is skipped with a warning and is not printed. If a manifest cannot be
-read, or a name was skipped, the orphaned blob figures are reported as
-unknown; `--json` gives them as `null`, lists the remote key of each
-unreadable manifest in `unreadable_manifests` and counts the skipped
-names in `skipped_metadata_names`.
+key is skipped with a warning and is not printed. If a listed
+`manifest.json.zst` cannot be read, or sits under a skipped name, the
+orphaned blob figures are reported as unknown; `--json` gives them as
+`null`, lists the remote key of each unreadable manifest in
+`unreadable_manifests` and counts the manifests under skipped names in
+`skipped_manifests`.
 * `--json`: Output as JSON
 
 **`remote nuke`**: Delete every snapshot's metadata and every blob from the

TODO.md

@@ -32,9 +32,11 @@ the tag exists and is exercised; what is left is merging `next` to
   advice, and `--json` gives them as `null` with the unreadable remote
   keys in `unreadable_manifests`. A name under `metadata/` that is not
   64 lowercase hex characters is now skipped with a warning instead of
-  being printed, control characters included. Its manifest is then not
-  read either, so a skipped name also leaves the orphan figures unknown,
-  and `--json` counts such names in `skipped_metadata_names`.
+  being printed, control characters included. A manifest under a
+  skipped name is then not read either, so it also leaves the orphan
+  figures unknown, and `--json` counts such manifests in
+  `skipped_manifests`. A directory with no manifest in it, as left by an
+  interrupted backup, leaves the figures known.
 
 - 2026-10-07: Made a backup notice a file rewritten with its size
   unchanged and a new mtime in the same second as the one in the index

internal/vaultik/info.go

@@ -183,6 +183,11 @@ type SnapshotMetadataInfo struct {
 	TotalSize    int64  `json:"total_size"`
 	BlobCount    int    `json:"blob_count"`
 	BlobsSize    int64  `json:"blobs_size"`
+
+	// Set when the listing holds this snapshot's manifest.json.zst. A
+	// backup interrupted before its manifest upload leaves a directory
+	// without one, which prune does not treat as a snapshot.
+	hasManifest bool
 }
 
 // RemoteInfoResult contains all remote storage information
@@ -207,18 +212,19 @@ type RemoteInfoResult struct {
 	ReferencedBlobSize  int64 `json:"referenced_blob_size"`
 
 	// Orphaned blobs. Both stay nil (null in the JSON) when a manifest
-	// could not be read or a name under metadata/ was skipped, since
-	// that snapshot's blobs would be counted as orphaned.
+	// was listed but not read, since that snapshot's blobs would be
+	// counted as orphaned.
 	OrphanedBlobCount *int   `json:"orphaned_blob_count"`
 	OrphanedBlobSize  *int64 `json:"orphaned_blob_size"`
 
 	// Remote key of each snapshot whose manifest could not be read
 	UnreadableManifests []string `json:"unreadable_manifests,omitempty"`
 
-	// Number of names under metadata/ skipped because they are not
-	// remote keys. The names themselves are not reported: they come
-	// from the destination store and may hold control characters.
-	SkippedMetadataNames int `json:"skipped_metadata_names,omitempty"`
+	// Number of manifests not read because the name above them under
+	// metadata/ is not a remote key. The names themselves are not
+	// reported: they come from the destination store and may hold
+	// control characters.
+	SkippedManifests int `json:"skipped_manifests,omitempty"`
 }
 
 // RemoteInfo displays information about remote storage
@@ -244,12 +250,12 @@ func (v *Vaultik) RemoteInfo(jsonOutput bool) error {
 		v.stdoutf("Scanning snapshot metadata...\n")
 	}
 
-	snapshotMetadata, snapshotIDs, skippedNames, err := v.collectSnapshotMetadata()
+	snapshotMetadata, snapshotIDs, skippedManifests, err := v.collectSnapshotMetadata()
 	if err != nil {
 		return err
 	}
 
-	result.SkippedMetadataNames = skippedNames
+	result.SkippedManifests = skippedManifests
 
 	if showText {
 		v.stdoutf("Downloading %d manifest(s)...\n", len(snapshotIDs))
@@ -287,13 +293,13 @@ func (v *Vaultik) RemoteInfo(jsonOutput bool) error {
 }
 
 // collectSnapshotMetadata scans remote metadata and returns
-// per-snapshot info, sorted IDs and the number of names it skipped
-// because they are not remote keys.
+// per-snapshot info, sorted IDs and the number of manifests it skipped
+// because the name above them is not a remote key.
 func (v *Vaultik) collectSnapshotMetadata() (
 	map[string]*SnapshotMetadataInfo, []string, int, error,
 ) {
 	snapshotMetadata := make(map[string]*SnapshotMetadataInfo)
-	skippedNames := make(map[string]bool)
+	skippedManifests := 0
 
 	metadataCh := v.Storage.ListStream(v.ctx, "metadata/")
 	for obj := range metadataCh {
@@ -307,6 +313,8 @@ func (v *Vaultik) collectSnapshotMetadata() (
 		}
 
 		snapshotID := parts[1]
+		filename := parts[2]
+		isManifest := filename == "manifest.json.zst"
 
 		// The name comes from the destination store, which is not
 		// trusted, and is printed in the report. Accept it only in the
@@ -315,7 +323,9 @@ func (v *Vaultik) collectSnapshotMetadata() (
 			log.Warn("Skipping non-conforming key under metadata/",
 				"key", obj.Key)
 
-			skippedNames[snapshotID] = true
+			if isManifest {
+				skippedManifests++
+			}
 
 			continue
 		}
@@ -326,7 +336,10 @@ func (v *Vaultik) collectSnapshotMetadata() (
 
 		info := snapshotMetadata[snapshotID]
 
-		filename := parts[2]
+		if isManifest {
+			info.hasManifest = true
+		}
+
 		if strings.HasPrefix(filename, "manifest") {
 			info.ManifestSize = obj.Size
 		} else if strings.HasPrefix(filename, "db") {
@@ -343,12 +356,12 @@ func (v *Vaultik) collectSnapshotMetadata() (
 
 	sort.Strings(snapshotIDs)
 
-	return snapshotMetadata, snapshotIDs, len(skippedNames), nil
+	return snapshotMetadata, snapshotIDs, skippedManifests, nil
 }
 
-// collectReferencedBlobsFromManifests downloads manifests and returns
-// referenced blob hashes with sizes, and the remote keys of the
-// manifests it could not read.
+// collectReferencedBlobsFromManifests downloads the listed manifests
+// and returns referenced blob hashes with sizes, and the remote keys
+// of the manifests it could not read.
 func (v *Vaultik) collectReferencedBlobsFromManifests(
 	snapshotIDs []string, snapshotMetadata map[string]*SnapshotMetadataInfo,
 ) (map[string]int64, []string) {
@@ -357,6 +370,11 @@ func (v *Vaultik) collectReferencedBlobsFromManifests(
 	var unreadable []string
 
 	for _, snapshotID := range snapshotIDs {
+		info := snapshotMetadata[snapshotID]
+		if !info.hasManifest {
+			continue
+		}
+
 		// snapshotIDs here are remote keys, taken straight from the
 		// metadata/ listing. downloadManifestByKey is the single reader
 		// for remote manifests; see its doc comment.
@@ -369,7 +387,6 @@ func (v *Vaultik) collectReferencedBlobsFromManifests(
 			continue
 		}
 
-		info := snapshotMetadata[snapshotID]
 		info.BlobCount = manifest.BlobCount
 
 		var blobsSize int64
@@ -411,9 +428,9 @@ func (v *Vaultik) populateRemoteInfoResult(
 }
 
 // scanRemoteBlobStorage lists all blobs on remote and computes orphan
-// stats when every manifest was read and no name under metadata/ was
-// skipped. showText is true only when the human report is being
-// printed (not --json, not --quiet), gating the progress line.
+// stats when every listed manifest was read. showText is true only
+// when the human report is being printed (not --json, not --quiet),
+// gating the progress line.
 func (v *Vaultik) scanRemoteBlobStorage(
 	result *RemoteInfoResult, referencedBlobs map[string]int64, showText bool,
 ) error {
@@ -443,7 +460,7 @@ func (v *Vaultik) scanRemoteBlobStorage(
 	// A blob named only by a manifest that could not be read, or by one
 	// under a skipped name, would be counted as orphaned, so the orphan
 	// figures stay unknown.
-	if len(result.UnreadableManifests) > 0 || result.SkippedMetadataNames > 0 {
+	if len(result.UnreadableManifests) > 0 || result.SkippedManifests > 0 {
 		return nil
 	}
 
@@ -518,8 +535,8 @@ func (v *Vaultik) printRemoteInfoTable(result *RemoteInfoResult) {
 	if result.OrphanedBlobCount == nil {
 		v.stdoutf("Orphaned (unreferenced):    unknown "+
 			"(%d manifest(s) could not be read, "+
-			"%d name(s) under metadata/ skipped)\n",
-			len(result.UnreadableManifests), result.SkippedMetadataNames)
+			"%d manifest(s) under a non-conforming name skipped)\n",
+			len(result.UnreadableManifests), result.SkippedManifests)
 
 		return
 	}

internal/vaultik/remote_info_test.go

@@ -53,7 +53,8 @@ func TestRemoteInfo_UnreadableManifestLeavesOrphansUnknown(t *testing.T) {
 
 	text := env.stdout.String()
 	assert.Contains(t, text, "Orphaned (unreferenced):    unknown "+
-		"(1 manifest(s) could not be read, 0 name(s) under metadata/ skipped)")
+		"(1 manifest(s) could not be read, "+
+		"0 manifest(s) under a non-conforming name skipped)")
 	assert.NotContains(t, text, "vaultik prune")
 
 	env.stdout.Reset()
@@ -70,10 +71,11 @@ func TestRemoteInfo_UnreadableManifestLeavesOrphansUnknown(t *testing.T) {
 
 // TestRemoteInfo_SkipsNonConformingMetadataName checks that a directory
 // under metadata/ whose name is not a remote key is left out of the
-// report, and that the orphan figures are then unknown. The name comes
-// from the destination store; printed raw, its control characters would
-// reach the terminal. Its manifest is not read, so a blob only it
-// references would otherwise be counted as orphaned.
+// report, and that the orphan figures are unknown when it holds a
+// manifest. The name comes from the destination store; printed raw, its
+// control characters would reach the terminal. Its manifest is not
+// read, so a blob only it references would otherwise be counted as
+// orphaned.
 func TestRemoteInfo_SkipsNonConformingMetadataName(t *testing.T) {
 	log.Initialize(log.Config{})
 	t.Parallel()
@@ -93,7 +95,8 @@ func TestRemoteInfo_SkipsNonConformingMetadataName(t *testing.T) {
 	assert.NotContains(t, text, "31mred")
 	assert.Contains(t, text, "Total (1 snapshots)")
 	assert.Contains(t, text, "Orphaned (unreferenced):    unknown "+
-		"(0 manifest(s) could not be read, 1 name(s) under metadata/ skipped)")
+		"(0 manifest(s) could not be read, "+
+		"1 manifest(s) under a non-conforming name skipped)")
 	assert.NotContains(t, text, "vaultik prune")
 
 	env.stdout.Reset()
@@ -109,6 +112,47 @@ func TestRemoteInfo_SkipsNonConformingMetadataName(t *testing.T) {
 	assert.Nil(t, doc["orphaned_blob_count"])
 	assert.Contains(t, doc, "orphaned_blob_size")
 	assert.Nil(t, doc["orphaned_blob_size"])
-	assert.InDelta(t, 1, doc["skipped_metadata_names"], 0)
+	assert.InDelta(t, 1, doc["skipped_manifests"], 0)
 	assert.NotContains(t, doc, "unreadable_manifests")
 }
+
+// TestRemoteInfo_DirectoryWithoutManifestLeavesOrphansKnown checks that
+// a directory under metadata/ holding no manifest.json.zst, such as one
+// left by a backup interrupted before its manifest upload, leaves the
+// orphan figures known. prune does not treat such a directory as a
+// snapshot and deletes the blobs the report lists as orphaned.
+func TestRemoteInfo_DirectoryWithoutManifestLeavesOrphansKnown(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))
+	addBlob(t, env.store.testStorer, testBlobHashA)
+	addBlob(t, env.store.testStorer, testBlobHashB)
+
+	// One directory under a remote key and one under a non-conforming
+	// name, each holding only a database.
+	names := []string{snapshot.RemoteSnapshotKey(listLocalID), "\x1b[31mred"}
+	for _, name := range names {
+		require.NoError(t, env.store.Put(context.Background(),
+			"metadata/"+name+"/db.zst.age",
+			bytes.NewReader([]byte("not a valid database"))))
+	}
+
+	require.NoError(t, env.v.RemoteInfo(false))
+
+	text := env.stdout.String()
+	assert.NotContains(t, text, "\x1b")
+	assert.Contains(t, text, "Orphaned (unreferenced):    1 (")
+	assert.Contains(t, text, "Run 'vaultik prune' to remove orphaned blobs.")
+
+	env.stdout.Reset()
+	require.NoError(t, env.v.RemoteInfo(true))
+
+	var doc map[string]any
+
+	require.NoError(t, json.Unmarshal(env.stdout.Bytes(), &doc))
+	assert.InDelta(t, 1, doc["orphaned_blob_count"], 0)
+	assert.NotContains(t, doc, "unreadable_manifests")
+	assert.NotContains(t, doc, "skipped_manifests")
+}