ML data that does not decrypt is recorded with its reason (closes #198)

`fetchMLDataBatch` dropped an entry that did not decrypt, gunzip or parse,
so the file looked like one with no ML data and the run exited 0. It now
returns the reason beside the payloads, also for ML data that is not a
JSON object. The library gives the reasons from its last ML data fetch
that succeeded in `status().mlDataErrors` and the `fetchMLData` "done"
event; a fetch that fails leaves them as they were. `quak backup` writes
the reason as `mlDataError` for a file with no ML data cached and records
the file in `failures.json`. `backup-metadata` writes `mlDataError` for it
and exits 1; `runMetadataBackup` returns `filesWithMLDataError`.

Judgement call: a file whose ML data is cached keeps it in its JSON when a
newer copy does not decode, as when the fetch fails.

Model: opus-5-5

src/library/index.ts

@@ -89,6 +89,7 @@ export {
 } from "./content.js";
 export { type MLDataAPI, type SimilarResult } from "./mlsearch.js";
 import type { CollectionsPage, FilesPage } from "../client.js";
+import { describeError } from "../errors.js";
 import { MLDATA_BATCH_SIZE, type MLData } from "../mldata-fetch.js";
 import type { Collection, EnteFile } from "../model/types.js";
 import { runBackup, type BackupOptions, type BackupResult } from "../backup.js";
@@ -138,12 +139,16 @@ export interface LibraryClient {
         sinceTime: number;
     }): Promise<FilesPage>;
     // Fetch ML data (face detections + CLIP embeddings) for up to a batch of
-    // files. Optional: a client without it simply disables ML fetching, leaving
-    // the metadata refresh untouched.
+    // files, and for each file whose ML data did not decrypt, gunzip or parse,
+    // why not. Optional: a client without it simply disables ML fetching,
+    // leaving the metadata refresh untouched.
     fetchMLData?(args: {
         fileIDs: number[];
         fileKeys: Map<number, Uint8Array>;
-    }): Promise<Map<number, MLData>>;
+    }): Promise<{
+        payloads: Map<number, MLData>;
+        errors: Map<number, unknown>;
+    }>;
     // The byte source for the on-disk content cache. Optional so a mock client
     // that only serves metadata still satisfies the interface; when absent (and
     // no explicit `contentSource` is passed to `open`) the content cache is
@@ -154,9 +159,11 @@ export interface LibraryClient {
 // A progress event for one unit of background work. A metadata "refresh" or an
 // ML "fetchMLData" pass each fire "started" before their network work and then
 // exactly one of "done" or "failed"; "failed" carries the error message and
-// an ML "done" reports how many payloads it stored. The precache fills
-// ("precacheThumbnails"/"precacheOriginals", #48) fire "started"/"done" around
-// each sweep that has work, "done" reporting the count newly cached.
+// an ML "done" reports how many payloads it stored and, in `mlDataErrors`,
+// each file whose ML data did not decrypt, gunzip or parse, with the reason.
+// The precache fills ("precacheThumbnails"/"precacheOriginals", #48) fire
+// "started"/"done" around each sweep that has work, "done" reporting the count
+// newly cached.
 export interface RefreshEvent {
     operation:
         | "refresh"
@@ -166,6 +173,7 @@ export interface RefreshEvent {
     status: "started" | "done" | "failed";
     error?: string;
     fetched?: number;
+    mlDataErrors?: { fileID: number; error: string }[];
 }
 
 export type RefreshProgressCallback = (event: RefreshEvent) => void;
@@ -225,6 +233,11 @@ export interface LibraryStatus {
     lastMLFetchAt?: number;
     // The most recent ML fetch pass's error, set only while it failed.
     lastMLError?: string;
+    // Each file whose ML data the last ML fetch pass that succeeded got but
+    // could not decrypt, gunzip or parse, with the reason. A pass still
+    // running leaves it as it is. A pass that fails leaves it as it was. Such
+    // ML data is not cached, so the next pass asks for it again.
+    mlDataErrors: { fileID: number; error: string }[];
     // ML payloads stored on disk and CLIP embeddings in the index; undefined
     // when ML fetching is disabled.
     mlStored?: number;
@@ -292,6 +305,12 @@ export class Library {
     private lastError?: string;
     private lastMLFetchAt?: number;
     private lastMLError?: string;
+    // For each file whose ML data the last ML fetch pass that succeeded got
+    // but could not decrypt, gunzip or parse, why not, by fileID. A pass
+    // gathers its own and puts them here when it ends without failing, so
+    // `status()` and `backup()` never see the list of a pass that is still
+    // running or that failed. Kept in RAM only, never in the cache.
+    private mlDataErrors = new Map<number, unknown>();
     // The plain-record projection as of the last refresh, and the GUI change
     // subscribers. A refresh that alters the projection notifies each with the
     // delta; `lastRecords` is kept current every refresh so a subscriber that
@@ -542,6 +561,7 @@ export class Library {
             lastError: this.lastError,
             lastMLFetchAt: this.lastMLFetchAt,
             lastMLError: this.lastMLError,
+            mlDataErrors: this.describeMLDataErrors(),
             mlStored: ml?.stored,
             mlIndexed: ml?.indexed,
             originalsUsedBytes: originals?.usedBytes,
@@ -612,6 +632,7 @@ export class Library {
                 contentConcurrency: this.pools.content.concurrency,
                 fetchMLData: () => this.fetchMLDataNow(),
                 mlData: (fileID) => this.mldata.forFile({ fileID }),
+                mlDataError: (fileID) => this.mlDataErrors.get(fileID),
             },
             { ...opts, downloadDirectory },
         );
@@ -838,8 +859,11 @@ export class Library {
 
     // One ML fetch pass: fetch, decrypt and store the ML data for every file
     // the store knows about that is not cached (or whose `updationTime` has
-    // advanced), through the metadata pool, and update the CLIP index. A
-    // failure is reported through `status()` and `onProgress`, then thrown.
+    // advanced), through the metadata pool, and update the CLIP index. For a
+    // file whose ML data does not decrypt, gunzip or parse, it gathers the
+    // reason instead, and puts the reasons it gathered in `mlDataErrors` when
+    // it ends without failing. A failure leaves `mlDataErrors` as it was and
+    // is reported through `status()` and `onProgress`, then thrown.
     private async runMLFetch(): Promise<void> {
         const mldata = this.mlStore;
         // Bind so the call keeps the client as its receiver when invoked
@@ -849,7 +873,14 @@ export class Library {
 
         const files = this.uniqueFiles();
         const needed = mldata.neededFor(files);
-        if (needed.length === 0) return;
+        // This pass's reasons, put in `this.mlDataErrors` when it ends without
+        // failing. A file whose ML data did not decode in the pass before is
+        // still among `needed`, so this pass gives its reason anew.
+        const mlDataErrors = new Map<number, unknown>();
+        if (needed.length === 0) {
+            this.mlDataErrors = mlDataErrors;
+            return;
+        }
 
         this.emit({ operation: "fetchMLData", status: "started" });
         try {
@@ -864,20 +895,25 @@ export class Library {
             for (let i = 0; i < needed.length; i += MLDATA_BATCH_SIZE) {
                 if (this.closed) break;
                 const batch = needed.slice(i, i + MLDATA_BATCH_SIZE);
-                const payloads = await this.pools.metadata.run(
+                const { payloads, errors } = await this.pools.metadata.run(
                     () => fetchMLData({ fileIDs: batch, fileKeys }),
                     { priority: "background" },
                 );
+                for (const [id, error] of errors) {
+                    mlDataErrors.set(id, error);
+                }
                 stored += (await mldata.storeFetched(payloads, updation))
                     .stored;
             }
 
+            this.mlDataErrors = mlDataErrors;
             this.lastMLFetchAt = Date.now();
             this.lastMLError = undefined;
             this.emit({
                 operation: "fetchMLData",
                 status: "done",
                 fetched: stored,
+                mlDataErrors: this.describeMLDataErrors(),
             });
         } catch (err) {
             const error = err instanceof Error ? err.message : String(err);
@@ -887,6 +923,14 @@ export class Library {
         }
     }
 
+    // `mlDataErrors` as `status()` and the ML "done" event give it.
+    private describeMLDataErrors(): { fileID: number; error: string }[] {
+        return [...this.mlDataErrors].map(([fileID, err]) => ({
+            fileID,
+            error: describeError(err),
+        }));
+    }
+
     // The distinct files the store holds, one entry per fileID (a file in
     // several collections shares its ML data), each carrying the key and the
     // newest `updationTime` seen across its memberships.