cursedbelt-core 2.13.2 → 2.14.0

package/dist/core/upload-precheck/hash.js

@@ -0,0 +1,46 @@
+import { Sha256 } from "./sha256.js";
+/**
+ * The largest file hashed in ONE native `crypto.subtle.digest` call — read whole into memory.
+ *
+ * Native hashing ran 1,960 MiB/s on this Mac against 184 MiB/s for the incremental one, so a
+ * file is read whole whenever that is safe. 256 MiB is far under what a phone tab survives, and
+ * covers every photo, every song and most clips; past it the incremental hasher streams in
+ * {@link STREAM_SLICE_BYTES} slices at roughly the speed an external drive reads anyway.
+ */
+export const NATIVE_HASH_MAX_BYTES = 256 * 1024 * 1024;
+/**
+ * One read while streaming. Small enough that the incremental hasher returns to the event loop
+ * every ~10 ms (a 2 MiB slice at ~190 MiB/s), so a tab hashing an 8 GB disc stays responsive.
+ */
+export const STREAM_SLICE_BYTES = 2 * 1024 * 1024;
+function hex(digest) {
+    const view = new Uint8Array(digest);
+    let out = "";
+    for (let i = 0; i < view.length; i++)
+        out += view[i].toString(16).padStart(2, "0");
+    return out;
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw signal.reason ?? new DOMException("The upload was canceled.", "AbortError");
+}
+/**
+ * The whole-file SHA-256 of a Blob (a browser `File`, a `Bun.file`) of any size, as lowercase hex
+ * — the same digest binary-server records in `file_index.checksum` for the same bytes.
+ */
+export async function sha256OfBlob(blob, options = {}) {
+    const { onProgress, signal, nativeMaxBytes = NATIVE_HASH_MAX_BYTES } = options;
+    throwIfAborted(signal);
+    if (blob.size <= nativeMaxBytes) {
+        const digest = await crypto.subtle.digest("SHA-256", await blob.arrayBuffer());
+        onProgress?.(1);
+        return hex(digest);
+    }
+    const hasher = new Sha256();
+    for (let offset = 0; offset < blob.size; offset += STREAM_SLICE_BYTES) {
+        throwIfAborted(signal);
+        hasher.update(new Uint8Array(await blob.slice(offset, offset + STREAM_SLICE_BYTES).arrayBuffer()));
+        onProgress?.(Math.min(1, (offset + STREAM_SLICE_BYTES) / blob.size));
+    }
+    return hasher.hex();
+}

package/dist/core/upload-precheck/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `cursedbelt-core/upload-precheck` — skip a duplicate upload by its hash BEFORE sending it
+ * (forge task 3579). Every app's dropzone, uploader and Mac ingest uses this one module, so the
+ * order of the work (sizes → memo → hash → ask) and the route's contract are the same everywhere.
+ *
+ * - `planUploads` — the client side: decide which files to send.
+ * - `parsePrecheckRequest`, `jsonList` — the server side: each app's route parses with the first
+ *   and binds its lists with the second.
+ * - `sha256OfBlob` — the whole-file SHA-256 binary-server records, of a Blob of any size.
+ * - `indexedDbHashMemo`, `memoryHashMemo` — the memo that makes a re-import of the same folder
+ *   read nothing.
+ *
+ * Pure of any framework; a browser bundle and a Bun script may both import it. Its sibling
+ * `cursedbelt-core/duplicates` answers the other question — two files that are LIKELY the same
+ * (a re-encode, a copy under another name) — which is never enough to skip an upload on.
+ */
+export { isSha256Hex, jsonList, PRECHECK_MAX_HASHES, PRECHECK_MAX_SIZES, type ParsedPrecheck, type PrecheckHit, type PrecheckReason, type PrecheckRequest, type PrecheckResponse, parsePrecheckRequest, } from "./contract.js";
+export { type HashOptions, NATIVE_HASH_MAX_BYTES, STREAM_SLICE_BYTES, sha256OfBlob } from "./hash.js";
+export { BROWSER_MEMO_MAX_ENTRIES, type HashMemo, indexedDbHashMemo, memoKey, memoryHashMemo, statIdentity, } from "./memo.js";
+export { type PlanOptions, type PlanResult, type PlanStats, type PrecheckAsk, planUploads, type Verdict, } from "./plan.js";
+export { Sha256 } from "./sha256.js";

package/dist/core/upload-precheck/index.js

@@ -0,0 +1,21 @@
+/**
+ * `cursedbelt-core/upload-precheck` — skip a duplicate upload by its hash BEFORE sending it
+ * (forge task 3579). Every app's dropzone, uploader and Mac ingest uses this one module, so the
+ * order of the work (sizes → memo → hash → ask) and the route's contract are the same everywhere.
+ *
+ * - `planUploads` — the client side: decide which files to send.
+ * - `parsePrecheckRequest`, `jsonList` — the server side: each app's route parses with the first
+ *   and binds its lists with the second.
+ * - `sha256OfBlob` — the whole-file SHA-256 binary-server records, of a Blob of any size.
+ * - `indexedDbHashMemo`, `memoryHashMemo` — the memo that makes a re-import of the same folder
+ *   read nothing.
+ *
+ * Pure of any framework; a browser bundle and a Bun script may both import it. Its sibling
+ * `cursedbelt-core/duplicates` answers the other question — two files that are LIKELY the same
+ * (a re-encode, a copy under another name) — which is never enough to skip an upload on.
+ */
+export { isSha256Hex, jsonList, PRECHECK_MAX_HASHES, PRECHECK_MAX_SIZES, parsePrecheckRequest, } from "./contract.js";
+export { NATIVE_HASH_MAX_BYTES, STREAM_SLICE_BYTES, sha256OfBlob } from "./hash.js";
+export { BROWSER_MEMO_MAX_ENTRIES, indexedDbHashMemo, memoKey, memoryHashMemo, statIdentity, } from "./memo.js";
+export { planUploads, } from "./plan.js";
+export { Sha256 } from "./sha256.js";

package/dist/core/upload-precheck/memo.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The memory that makes a RE-IMPORT cheap: a file's hash, remembered by where it was, how big and
+ * how old — so a second drop of the same huge folder hashes nothing it already hashed.
+ *
+ * Collections' Mac sweeper keeps the same key for its linked folders (`apps/collections/scripts/ingestLinked.ts`:
+ * path, size, mtime) and has re-walked `tod` every sweep on it since forge task 3508. A file whose
+ * path, size AND modification time all match a remembered one is the same file unless something
+ * rewrote it and set its clock back; anything else misses, and is hashed again.
+ *
+ * A memo only ever saves work: a miss, a broken store or a private window means "hash it", never a
+ * wrong answer, because the hash it returns is still checked against the library.
+ */
+/** The batch interface — one transaction per batch, not one per file. */
+export interface HashMemo {
+    get(keys: readonly string[]): Promise<Map<string, string>>;
+    set(entries: readonly (readonly [key: string, sha256: string])[]): Promise<void>;
+}
+/**
+ * The key a file is remembered under. `path` is its path inside the drop when known, else its name.
+ *
+ * `identity` is what a Mac script can add for free from the `stat` it already took —
+ * {@link statIdentity}. It closes the one gap path+size+date leave: a file DELETED and replaced by a
+ * different one with the same name, the same size and the same modification time to the
+ * millisecond (`cp -p`, or a tool that copies dates). The replacement is a new inode, and any write
+ * moves the change time, which no tool can set back. A browser `File` exposes neither, so the
+ * browser's key is path+size+date alone — two different files agreeing on all three is the case
+ * left, and it takes a deliberately copied date.
+ */
+export declare function memoKey(path: string, size: number, lastModified: number | undefined, identity?: string): string;
+/**
+ * A file's identity beyond its path, size and date: its inode and its change time (`ctime`), both
+ * in the `stat` a script already has. Measured on the linked `tod` folder (APFS, 2026-10-22): files
+ * ingested that day still carried change times from months before — reading, hashing and filing a
+ * file never moves it — so this costs a re-hash only when something really touched the file.
+ */
+export declare function statIdentity(stat: {
+    ino: number | bigint;
+    ctimeMs: number;
+}): string;
+/** A memo held in memory — the Mac scripts' and the specs'. */
+export declare function memoryHashMemo(): HashMemo & {
+    readonly size: number;
+};
+/** How many files a browser memo remembers before it forgets the oldest quarter. ~150 bytes each. */
+export declare const BROWSER_MEMO_MAX_ENTRIES = 200000;
+/**
+ * A memo kept in this origin's IndexedDB, so it survives a reload and a re-import next week. Each
+ * app is its own origin, so each keeps its own. Where IndexedDB is missing or refuses (a private
+ * window, a test DOM), every call quietly answers "not remembered" — the upload still works, it
+ * just hashes.
+ */
+export declare function indexedDbHashMemo(name?: string, maxEntries?: number): HashMemo;

package/dist/core/upload-precheck/memo.js

@@ -0,0 +1,160 @@
+/**
+ * The memory that makes a RE-IMPORT cheap: a file's hash, remembered by where it was, how big and
+ * how old — so a second drop of the same huge folder hashes nothing it already hashed.
+ *
+ * Collections' Mac sweeper keeps the same key for its linked folders (`apps/collections/scripts/ingestLinked.ts`:
+ * path, size, mtime) and has re-walked `tod` every sweep on it since forge task 3508. A file whose
+ * path, size AND modification time all match a remembered one is the same file unless something
+ * rewrote it and set its clock back; anything else misses, and is hashed again.
+ *
+ * A memo only ever saves work: a miss, a broken store or a private window means "hash it", never a
+ * wrong answer, because the hash it returns is still checked against the library.
+ */
+/**
+ * The key a file is remembered under. `path` is its path inside the drop when known, else its name.
+ *
+ * `identity` is what a Mac script can add for free from the `stat` it already took —
+ * {@link statIdentity}. It closes the one gap path+size+date leave: a file DELETED and replaced by a
+ * different one with the same name, the same size and the same modification time to the
+ * millisecond (`cp -p`, or a tool that copies dates). The replacement is a new inode, and any write
+ * moves the change time, which no tool can set back. A browser `File` exposes neither, so the
+ * browser's key is path+size+date alone — two different files agreeing on all three is the case
+ * left, and it takes a deliberately copied date.
+ */
+export function memoKey(path, size, lastModified, identity) {
+    const key = `${path}\u0000${size}\u0000${lastModified ?? ""}`;
+    return identity ? `${key}\u0000${identity}` : key;
+}
+/**
+ * A file's identity beyond its path, size and date: its inode and its change time (`ctime`), both
+ * in the `stat` a script already has. Measured on the linked `tod` folder (APFS, 2026-10-22): files
+ * ingested that day still carried change times from months before — reading, hashing and filing a
+ * file never moves it — so this costs a re-hash only when something really touched the file.
+ */
+export function statIdentity(stat) {
+    return `${stat.ino}:${Math.trunc(stat.ctimeMs)}`;
+}
+/** A memo held in memory — the Mac scripts' and the specs'. */
+export function memoryHashMemo() {
+    const map = new Map();
+    return {
+        get size() {
+            return map.size;
+        },
+        async get(keys) {
+            const out = new Map();
+            for (const key of keys) {
+                const hit = map.get(key);
+                if (hit)
+                    out.set(key, hit);
+            }
+            return out;
+        },
+        async set(entries) {
+            for (const [key, sha] of entries)
+                map.set(key, sha);
+        },
+    };
+}
+/** How many files a browser memo remembers before it forgets the oldest quarter. ~150 bytes each. */
+export const BROWSER_MEMO_MAX_ENTRIES = 200_000;
+const STORE = "hashes";
+function request(req) {
+    return new Promise((resolve, reject) => {
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error);
+    });
+}
+function done(tx) {
+    return new Promise((resolve, reject) => {
+        tx.oncomplete = () => resolve();
+        tx.onerror = () => reject(tx.error);
+        tx.onabort = () => reject(tx.error);
+    });
+}
+/**
+ * A memo kept in this origin's IndexedDB, so it survives a reload and a re-import next week. Each
+ * app is its own origin, so each keeps its own. Where IndexedDB is missing or refuses (a private
+ * window, a test DOM), every call quietly answers "not remembered" — the upload still works, it
+ * just hashes.
+ */
+export function indexedDbHashMemo(name = "upload-precheck", maxEntries = BROWSER_MEMO_MAX_ENTRIES) {
+    let opened;
+    const open = () => {
+        opened ??= new Promise((resolve) => {
+            try {
+                if (typeof indexedDB === "undefined")
+                    return resolve(null);
+                const req = indexedDB.open(name, 1);
+                req.onupgradeneeded = () => {
+                    const store = req.result.createObjectStore(STORE, { keyPath: "k" });
+                    store.createIndex("at", "at");
+                };
+                req.onsuccess = () => resolve(req.result);
+                req.onerror = () => resolve(null);
+                req.onblocked = () => resolve(null);
+            }
+            catch {
+                resolve(null);
+            }
+        });
+        return opened;
+    };
+    const prune = async (db) => {
+        const tx = db.transaction(STORE, "readwrite");
+        const store = tx.objectStore(STORE);
+        const count = await request(store.count());
+        if (count > maxEntries) {
+            let drop = Math.ceil(count / 4);
+            const cursor = store.index("at").openCursor();
+            await new Promise((resolve, reject) => {
+                cursor.onerror = () => reject(cursor.error);
+                cursor.onsuccess = () => {
+                    const at = cursor.result;
+                    if (!at || drop-- <= 0)
+                        return resolve();
+                    at.delete();
+                    at.continue();
+                };
+            });
+        }
+        await done(tx);
+    };
+    return {
+        async get(keys) {
+            const out = new Map();
+            try {
+                const db = await open();
+                if (!db || keys.length === 0)
+                    return out;
+                const tx = db.transaction(STORE, "readonly");
+                const store = tx.objectStore(STORE);
+                const rows = await Promise.all(keys.map((key) => request(store.get(key))));
+                for (const row of rows)
+                    if (row)
+                        out.set(row.k, row.sha);
+            }
+            catch {
+                // a refused read is a miss
+            }
+            return out;
+        },
+        async set(entries) {
+            try {
+                const db = await open();
+                if (!db || entries.length === 0)
+                    return;
+                const tx = db.transaction(STORE, "readwrite");
+                const store = tx.objectStore(STORE);
+                const at = Date.now();
+                for (const [k, sha] of entries)
+                    store.put({ k, sha, at });
+                await done(tx);
+                await prune(db);
+            }
+            catch {
+                // a refused write only costs the next re-import a hash
+            }
+        },
+    };
+}

package/dist/core/upload-precheck/plan.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Decide, for a drop of files, which ones to SEND — before sending any (forge task 3579).
+ *
+ * The order of the work is the whole design, cheapest question first:
+ *
+ * 1. **Sizes, one request.** A file whose byte size the library holds nothing of — and that no
+ *    other file in this drop shares — cannot be a copy of anything. It is uploaded at once, never
+ *    hashed here (binary-server hashes what it receives anyway). A folder of new videos is decided
+ *    almost entirely by this step.
+ * 2. **The memo.** A file this browser (or script) hashed before, at the same path with the same
+ *    size and date, takes its remembered hash — a second import of the same huge folder reads none
+ *    of its bytes.
+ * 3. **Hash the rest**, a few at a time and within a memory budget, and ask the library about the
+ *    hashes AS they finish: one request in flight, each carrying every hash completed since the
+ *    last. Uploads of the first new files begin while later ones are still being hashed.
+ * 4. **A repeat inside the drop** (the same bytes under two names) is caught by its hash without
+ *    asking anybody, and only the first is sent.
+ *
+ * A pre-check that FAILS never blocks an upload: the sizes question failing sends everything as
+ * it would have before the pre-check existed (each app's own after-the-fact check still stands),
+ * and is reported as `degraded`. It costs bandwidth, never a file.
+ */
+import { type PrecheckHit, type PrecheckRequest, type PrecheckResponse } from "./contract.js";
+import { type HashOptions } from "./hash.js";
+import { type HashMemo } from "./memo.js";
+/** Asks the app's pre-check route. Each app supplies its own fetch. */
+export type PrecheckAsk = (request: PrecheckRequest) => Promise<PrecheckResponse>;
+export type Verdict<T> = 
+/** Send it. `sha256` is set when it was hashed on the way (an app may pass it on). */
+{
+    kind: "upload";
+    item: T;
+    sha256?: string;
+}
+/** The library already answers for these bytes. Do not send. */
+ | {
+    kind: "duplicate";
+    item: T;
+    sha256: string;
+    hit: PrecheckHit;
+}
+/** Another file in this same drop has these bytes; only that one is sent. */
+ | {
+    kind: "repeat";
+    item: T;
+    sha256: string;
+    of: T;
+};
+export interface PlanStats {
+    files: number;
+    bytes: number;
+    /** Files sent without being hashed, because their size matched nothing. */
+    sizeOnly: number;
+    /** Files whose hash came from the memo — no bytes read. */
+    memoHits: number;
+    /** Files hashed here, and how many bytes that read. */
+    hashedFiles: number;
+    hashedBytes: number;
+    /** Requests made to the pre-check route. */
+    asks: number;
+    /** Bytes the plan kept from being sent. */
+    savedBytes: number;
+    /** Files whose hash failed (an unreadable file) — sent unhashed rather than ending the plan. */
+    hashErrors: number;
+    /** Set when the pre-check could not be asked; the plan then sent what it could not rule out. */
+    degraded?: string;
+}
+export interface PlanResult<T> {
+    upload: Extract<Verdict<T>, {
+        kind: "upload";
+    }>[];
+    duplicates: Extract<Verdict<T>, {
+        kind: "duplicate";
+    }>[];
+    repeats: Extract<Verdict<T>, {
+        kind: "repeat";
+    }>[];
+    stats: PlanStats;
+}
+export interface PlanOptions<T> {
+    items: readonly T[];
+    /** The bytes of an item. Its `size` is the size asked about. */
+    blobOf: (item: T) => Blob;
+    /** The item's path inside the drop (or its name) — the memo's key. Without it there is no memo. */
+    pathOf?: (item: T) => string;
+    /** Modification time in ms (a `File`'s `lastModified`). Part of the memo's key. */
+    lastModifiedOf?: (item: T) => number | undefined;
+    /** A script's {@link statIdentity} of the item — part of the memo's key where it is known. */
+    identityOf?: (item: T) => string | undefined;
+    ask: PrecheckAsk;
+    memo?: HashMemo;
+    /** Defaults to {@link sha256OfBlob}. The specs count calls through it. */
+    hash?: (blob: Blob, options: HashOptions) => Promise<string>;
+    /** Files hashed at once. Default 3 — a disk is the bottleneck past that. */
+    concurrency?: number;
+    /** Bytes held in memory by hashes in flight. Default 320 MiB; one file is always allowed. */
+    maxInFlightBytes?: number;
+    /**
+     * How long a finished hash waits for company before it is asked about (default 250 ms), unless
+     * {@link batchSize} are already waiting or the hashing is over. Bounds a drop of 10,000 small
+     * files to about one request per batch rather than one per file, at a quarter-second's delay.
+     */
+    lingerMs?: number;
+    /** Hashes that are asked about at once without waiting out the linger. Default 200. */
+    batchSize?: number;
+    signal?: AbortSignal;
+    /** Each verdict as it is reached — start uploading on the first `upload`, not at the end. */
+    onVerdict?: (verdict: Verdict<T>) => void;
+    /** Hashing progress of one item, 0..1. */
+    onHashProgress?: (item: T, fraction: number) => void;
+}
+export declare function planUploads<T>(options: PlanOptions<T>): Promise<PlanResult<T>>;

package/dist/core/upload-precheck/plan.js

@@ -0,0 +1,242 @@
+/**
+ * Decide, for a drop of files, which ones to SEND — before sending any (forge task 3579).
+ *
+ * The order of the work is the whole design, cheapest question first:
+ *
+ * 1. **Sizes, one request.** A file whose byte size the library holds nothing of — and that no
+ *    other file in this drop shares — cannot be a copy of anything. It is uploaded at once, never
+ *    hashed here (binary-server hashes what it receives anyway). A folder of new videos is decided
+ *    almost entirely by this step.
+ * 2. **The memo.** A file this browser (or script) hashed before, at the same path with the same
+ *    size and date, takes its remembered hash — a second import of the same huge folder reads none
+ *    of its bytes.
+ * 3. **Hash the rest**, a few at a time and within a memory budget, and ask the library about the
+ *    hashes AS they finish: one request in flight, each carrying every hash completed since the
+ *    last. Uploads of the first new files begin while later ones are still being hashed.
+ * 4. **A repeat inside the drop** (the same bytes under two names) is caught by its hash without
+ *    asking anybody, and only the first is sent.
+ *
+ * A pre-check that FAILS never blocks an upload: the sizes question failing sends everything as
+ * it would have before the pre-check existed (each app's own after-the-fact check still stands),
+ * and is reported as `degraded`. It costs bandwidth, never a file.
+ */
+import { PRECHECK_MAX_HASHES, PRECHECK_MAX_SIZES } from "./contract.js";
+import { NATIVE_HASH_MAX_BYTES, STREAM_SLICE_BYTES, sha256OfBlob } from "./hash.js";
+import { memoKey } from "./memo.js";
+function chunks(values, size) {
+    const out = [];
+    for (let i = 0; i < values.length; i += size)
+        out.push(values.slice(i, i + size));
+    return out;
+}
+const message = (error) => (error instanceof Error ? error.message : String(error));
+export async function planUploads(options) {
+    const { items, blobOf, pathOf, lastModifiedOf, identityOf, ask, memo, hash = sha256OfBlob, concurrency = 3, maxInFlightBytes = 320 * 1024 * 1024, lingerMs = 250, batchSize = 200, signal, onVerdict, onHashProgress, } = options;
+    const result = {
+        upload: [],
+        duplicates: [],
+        repeats: [],
+        stats: {
+            files: items.length,
+            bytes: 0,
+            sizeOnly: 0,
+            memoHits: 0,
+            hashedFiles: 0,
+            hashedBytes: 0,
+            asks: 0,
+            savedBytes: 0,
+            hashErrors: 0,
+        },
+    };
+    const decide = (verdict) => {
+        if (verdict.kind === "upload")
+            result.upload.push(verdict);
+        else {
+            result.stats.savedBytes += blobOf(verdict.item).size;
+            if (verdict.kind === "duplicate")
+                result.duplicates.push(verdict);
+            else
+                result.repeats.push(verdict);
+        }
+        onVerdict?.(verdict);
+    };
+    const sizeOf = (item) => blobOf(item).size;
+    const inDrop = new Map();
+    for (const item of items) {
+        const size = sizeOf(item);
+        result.stats.bytes += size;
+        inDrop.set(size, (inDrop.get(size) ?? 0) + 1);
+    }
+    if (items.length === 0)
+        return result;
+    // 1 — sizes
+    const held = new Set();
+    try {
+        for (const batch of chunks([...inDrop.keys()], PRECHECK_MAX_SIZES)) {
+            result.stats.asks++;
+            for (const size of (await ask({ sizes: batch })).sizes)
+                held.add(size);
+        }
+    }
+    catch (error) {
+        if (signal?.aborted)
+            throw error;
+        result.stats.degraded = `pre-check unavailable (${message(error)}) — sending without it`;
+        for (const item of items)
+            decide({ kind: "upload", item });
+        return result;
+    }
+    const candidates = [];
+    for (const item of items) {
+        const size = sizeOf(item);
+        if (held.has(size) || (inDrop.get(size) ?? 0) > 1)
+            candidates.push(item);
+        else {
+            result.stats.sizeOnly++;
+            decide({ kind: "upload", item });
+        }
+    }
+    if (candidates.length === 0)
+        return result;
+    // 2 — the memo
+    const keyOf = pathOf
+        ? (item) => memoKey(pathOf(item), sizeOf(item), lastModifiedOf?.(item), identityOf?.(item))
+        : undefined;
+    const remembered = memo && keyOf ? await memo.get(candidates.map(keyOf)) : new Map();
+    // 3 + 4 — hash, and ask as hashes finish
+    const firstWith = new Map();
+    let pending = [];
+    let toRemember = [];
+    let asking;
+    let askFailed;
+    let hashingDone = false;
+    let linger;
+    const flush = async () => {
+        while (pending.length > 0) {
+            const batch = pending.splice(0, PRECHECK_MAX_HASHES);
+            const remember = toRemember;
+            toRemember = [];
+            if (askFailed) {
+                for (const { item, sha256 } of batch)
+                    decide({ kind: "upload", item, sha256 });
+                continue;
+            }
+            let have = {};
+            try {
+                result.stats.asks++;
+                have = (await ask({ sha256: [...new Set(batch.map((b) => b.sha256))] })).have;
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    throw error;
+                askFailed = message(error);
+                result.stats.degraded = `pre-check failed mid-drop (${askFailed}) — sent the rest without it`;
+            }
+            for (const { item, sha256 } of batch) {
+                const hit = have[sha256];
+                decide(hit ? { kind: "duplicate", item, sha256, hit } : { kind: "upload", item, sha256 });
+            }
+            if (memo && remember.length > 0)
+                await memo.set(remember);
+        }
+    };
+    const kick = () => {
+        if (linger !== undefined) {
+            clearTimeout(linger);
+            linger = undefined;
+        }
+        if (asking)
+            return;
+        asking = flush().finally(() => {
+            asking = undefined;
+            if (pending.length > 0)
+                kick();
+        });
+        // Awaited at the end; this keeps an abort mid-hashing from surfacing as unhandled first.
+        asking.catch(() => { });
+    };
+    const settle = (item, sha256) => {
+        const first = firstWith.get(sha256);
+        if (first !== undefined) {
+            decide({ kind: "repeat", item, sha256, of: first });
+            return;
+        }
+        firstWith.set(sha256, item);
+        pending.push({ item, sha256 });
+        if (hashingDone || pending.length >= batchSize)
+            kick();
+        else
+            linger ??= setTimeout(kick, lingerMs);
+    };
+    const toHash = [];
+    for (const item of candidates) {
+        const known = keyOf ? remembered.get(keyOf(item)) : undefined;
+        if (known) {
+            result.stats.memoHits++;
+            settle(item, known);
+        }
+        else
+            toHash.push(item);
+    }
+    let next = 0;
+    let inFlightBytes = 0;
+    let running = 0;
+    const footprint = (size) => size <= NATIVE_HASH_MAX_BYTES ? size : STREAM_SLICE_BYTES;
+    await new Promise((resolve, reject) => {
+        let failed = false;
+        const pump = () => {
+            if (failed)
+                return;
+            if (next >= toHash.length && running === 0) {
+                resolve();
+                return;
+            }
+            while (next < toHash.length && running < concurrency) {
+                const item = toHash[next];
+                const blob = blobOf(item);
+                const cost = footprint(blob.size);
+                if (running > 0 && inFlightBytes + cost > maxInFlightBytes)
+                    break;
+                next++;
+                running++;
+                inFlightBytes += cost;
+                hash(blob, { signal, onProgress: onHashProgress ? (f) => onHashProgress(item, f) : undefined })
+                    .then((sha256) => {
+                    result.stats.hashedFiles++;
+                    result.stats.hashedBytes += blob.size;
+                    if (keyOf)
+                        toRemember.push([keyOf(item), sha256]);
+                    settle(item, sha256);
+                })
+                    .catch((error) => {
+                    // An abort ends the plan. One file that cannot be READ does not: it is sent
+                    // unhashed like any file the pre-check cannot rule out, and its own upload is
+                    // where the person learns it is unreadable (roms, forge task 3579).
+                    if (signal?.aborted) {
+                        failed = true;
+                        reject(error);
+                        return;
+                    }
+                    result.stats.hashErrors++;
+                    decide({ kind: "upload", item });
+                })
+                    .finally(() => {
+                    running--;
+                    inFlightBytes -= cost;
+                    pump();
+                });
+            }
+        };
+        pump();
+    }).catch((error) => {
+        if (linger !== undefined)
+            clearTimeout(linger);
+        throw error;
+    });
+    hashingDone = true;
+    if (pending.length > 0)
+        kick();
+    while (asking)
+        await asking;
+    return result;
+}