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 finished ML data
fetch in `status().mlDataErrors` and the `fetchMLData` "done" event.
`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

test/library/mldata.test.ts

@@ -12,9 +12,11 @@
  *
  *   2. `Library` wiring: after each refresh the library fetches ML data through
  *      the metadata pool for every known file not yet cached, is incremental on
- *      later refreshes, and refetches a file whose `updationTime` advanced.
- *      Opening a cache directory written by another account starts empty,
- *      its ML data included (issue #104).
+ *      later refreshes, and refetches a file whose `updationTime` advanced. A
+ *      file whose ML data did not decode is reported with the reason, which
+ *      stays listed until the next pass ends, and asked for again. Opening a
+ *      cache directory written by another account starts empty, its ML data
+ *      included (issue #104).
  *
  * Embedding values are chosen to be exactly representable as float32 so the
  * round-trip through `clip.f32` compares equal.
@@ -26,7 +28,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 import { MLDataStore } from "../../src/library/mldata.js";
-import { Library } from "../../src/library/index.js";
+import { Library, type RefreshEvent } from "../../src/library/index.js";
 import type { CollectionsPage, FilesPage } from "../../src/client.js";
 import type { MLData } from "../../src/mldata-fetch.js";
 import type { Collection, EnteFile } from "../../src/model/types.js";
@@ -256,12 +258,14 @@ const file = (
 
 // A mock client that serves scripted collection/file pages and per-file ML
 // payloads, recording every ML fetch request so incremental behaviour is
-// provable.
+// provable. A file in `mlErrorByFile` has ML data that did not decode, for
+// the reason given there.
 class MLMockClient {
     userID = USER_ID;
     collectionsQueue: CollectionsPage[] = [];
     filesByCollection = new Map<number, FilesPage[]>();
     mlByFile = new Map<number, MLData>();
+    mlErrorByFile = new Map<number, Error>();
     mlFetchCalls: number[][] = [];
 
     whoami(): { email: string; userID: number } {
@@ -298,14 +302,20 @@ class MLMockClient {
     async fetchMLData(args: {
         fileIDs: number[];
         fileKeys: Map<number, Uint8Array>;
-    }): Promise<Map<number, MLData>> {
+    }): Promise<{
+        payloads: Map<number, MLData>;
+        errors: Map<number, unknown>;
+    }> {
         this.mlFetchCalls.push([...args.fileIDs]);
-        const result = new Map<number, MLData>();
+        const payloads = new Map<number, MLData>();
+        const errors = new Map<number, unknown>();
         for (const id of args.fileIDs) {
             const p = this.mlByFile.get(id);
-            if (p) result.set(id, p);
+            if (p) payloads.set(id, p);
+            const error = this.mlErrorByFile.get(id);
+            if (error) errors.set(id, error);
         }
-        return result;
+        return { payloads, errors };
     }
 
     filesFor(collectionID: number, ...pages: FilesPage[]): void {
@@ -449,6 +459,137 @@ describe("Library ML-data fetch on refresh", () => {
         }
     });
 
+    it("reports a file whose ML data did not decode through status() and onProgress, and asks for it again", async () => {
+        const client = new MLMockClient();
+        client.collectionsQueue.push({
+            collections: [collection(1, 100)],
+            deleted: [],
+            cursor: 100,
+        });
+        client.filesFor(1, {
+            files: [file(1001, 1, 90), file(1002, 1, 95)],
+            deleted: [],
+            cursor: 95,
+        });
+        client.mlByFile.set(1001, payload([0.5, 0.25, 0.75]));
+        client.mlErrorByFile.set(
+            1002,
+            new Error("secretstream chunk authentication failed"),
+        );
+        const events: RefreshEvent[] = [];
+
+        const lib = await Library.open({
+            client,
+            cacheDirectory,
+            refreshIntervalSeconds: Infinity,
+            onProgress: (event) => events.push(event),
+        });
+        try {
+            await vi.waitFor(
+                () => expect(lib.status().lastMLFetchAt).toBeGreaterThan(0),
+                { timeout: 2000, interval: 5 },
+            );
+            const reasons = [
+                {
+                    fileID: 1002,
+                    error: "secretstream chunk authentication failed",
+                },
+            ];
+            expect(lib.status().mlDataErrors).toEqual(reasons);
+            expect(lib.status().mlStored).toBe(1);
+            expect(events.filter((e) => e.operation === "fetchMLData")).toEqual(
+                [
+                    { operation: "fetchMLData", status: "started" },
+                    {
+                        operation: "fetchMLData",
+                        status: "done",
+                        fetched: 1,
+                        mlDataErrors: reasons,
+                    },
+                ],
+            );
+
+            // Nothing was cached for 1002, so the pass a refresh starts asks
+            // for it again, and once its ML data decodes the reason is gone.
+            client.mlErrorByFile.clear();
+            client.mlByFile.set(1002, payload([1, -2, 0.5]));
+            await lib.fresh();
+            await vi.waitFor(
+                () => {
+                    expect(lib.status().mlStored).toBe(2);
+                    expect(lib.status().mlDataErrors).toEqual([]);
+                },
+                { timeout: 2000, interval: 5 },
+            );
+            expect(client.mlFetchCalls.at(-1)).toEqual([1002]);
+        } finally {
+            await lib.close();
+        }
+    });
+
+    it("still lists the last pass's reasons while the next pass runs", async () => {
+        const client = new MLMockClient();
+        client.collectionsQueue.push({
+            collections: [collection(1, 100)],
+            deleted: [],
+            cursor: 100,
+        });
+        client.filesFor(1, {
+            files: [file(1002, 1, 95)],
+            deleted: [],
+            cursor: 95,
+        });
+        client.mlErrorByFile.set(
+            1002,
+            new Error("secretstream chunk authentication failed"),
+        );
+        const reasons = [
+            { fileID: 1002, error: "secretstream chunk authentication failed" },
+        ];
+        let release!: () => void;
+        const held = new Promise<void>((r) => (release = r));
+
+        const lib = await Library.open({
+            client,
+            cacheDirectory,
+            refreshIntervalSeconds: Infinity,
+        });
+        try {
+            await vi.waitFor(
+                () => expect(lib.status().lastMLFetchAt).toBeGreaterThan(0),
+                { timeout: 2000, interval: 5 },
+            );
+            expect(lib.status().mlDataErrors).toEqual(reasons);
+
+            // Hold the next ML data fetch open until the test releases it.
+            let fetchStarted!: () => void;
+            const started = new Promise<void>((r) => (fetchStarted = r));
+            const realFetch = client.fetchMLData.bind(client);
+            client.fetchMLData = async (args) => {
+                fetchStarted();
+                await held;
+                return realFetch(args);
+            };
+            client.mlErrorByFile.clear();
+            client.mlByFile.set(1002, payload([1, -2, 0.5]));
+
+            // The pass a refresh starts asks for 1002 again. While it is
+            // held, the reason from the pass before is still listed; once it
+            // ends, its own empty list takes the place of that one.
+            await lib.fresh();
+            await started;
+            expect(lib.status().mlDataErrors).toEqual(reasons);
+            release();
+            await vi.waitFor(
+                () => expect(lib.status().mlDataErrors).toEqual([]),
+                { timeout: 2000, interval: 5 },
+            );
+        } finally {
+            release();
+            await lib.close();
+        }
+    });
+
     it("close() resolves only after a running ML data fetch has stored its payloads", async () => {
         const client = new MLMockClient();
         client.collectionsQueue.push({