cursedbelt-core 2.13.3 → 2.14.0

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

@@ -0,0 +1,71 @@
+/**
+ * The wire contract of an upload PRE-CHECK — "which of these do you already have?", asked before
+ * a single byte of the files is sent (forge task 3579).
+ *
+ * The owner, 2026-10-22: *"They should find and skip dups efficiently without wasting bandwidth or
+ * processing power … They need to know dups based on the hashes rather than a long check such as
+ * copying the file first … I will sometimes reimport from huge directories just in case they have a
+ * new file that was missed on previous uploads and I want it to be fast."*
+ *
+ * ── Two questions, one route ───────────────────────────────────────────────────────────────
+ * 1. **`sizes`** — which of these byte sizes does the library hold at all? A file whose size
+ *    matches nothing stored CANNOT be a byte-identical copy, so it is uploaded without being hashed
+ *    first (binary-server hashes what it receives, as it always has). On a folder of mostly new
+ *    videos that is nearly every file, and nearly all of the hashing.
+ * 2. **`sha256`** — which of these whole-file SHA-256s does the library hold? Asked only for the
+ *    files whose size DID match, so the proof (the hash) is paid exactly where it can decide
+ *    something. A hit is never sent.
+ *
+ * A route answers both in one body, so a client may ask either or both. Every app's library is
+ * scoped by the app's own rules (an account, an owner) — the route answers for the CALLER only,
+ * which is also what keeps the answer from saying anything about anyone else's files.
+ *
+ * ── SQL: one bound parameter, any length ───────────────────────────────────────────────────
+ * D1 refuses a statement with more than 100 bound parameters, so `IN (?, ?, …)` over a batch of
+ * 1,000 hashes cannot be written. Bind the list ONCE as JSON instead —
+ * `WHERE checksum IN (SELECT value FROM json_each(?))` with {@link jsonList} — which D1 and
+ * `bun:sqlite` both run against the column's index.
+ */
+/** The most sizes one pre-check may ask about. A drop of 5,000 files asks once. */
+export declare const PRECHECK_MAX_SIZES = 5000;
+/** The most hashes one pre-check may ask about — a client sends them in batches this size or less. */
+export declare const PRECHECK_MAX_HASHES = 1000;
+/** What the client sends. Either list may be absent or empty. */
+export interface PrecheckRequest {
+    sizes?: number[];
+    sha256?: string[];
+}
+/** Why a hash is refused: the library holds it, or once held it and its owner deleted it. */
+export type PrecheckReason = "exists" | "deleted";
+/** One hash the library already answers for. */
+export interface PrecheckHit {
+    reason: PrecheckReason;
+    /** What the library calls it — shown to the person beside the skipped file. */
+    name?: string;
+    /** The app's own id for the item, when it has one worth linking to. */
+    id?: string;
+}
+/** What the route answers. */
+export interface PrecheckResponse {
+    /** The asked sizes that the library holds at least one file of. */
+    sizes: number[];
+    /** The asked hashes the library already answers for; any hash absent here is new. */
+    have: Record<string, PrecheckHit>;
+}
+/** Is this a lowercase hex SHA-256 — the only spelling every store in the fleet records? */
+export declare function isSha256Hex(value: unknown): value is string;
+export type ParsedPrecheck = {
+    ok: true;
+    sizes: number[];
+    sha256: string[];
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Validate a pre-check body — the ONE parser every app's route calls, so the limits and the
+ * spelling are the same everywhere. Duplicates collapse; order is not kept.
+ */
+export declare function parsePrecheckRequest(body: unknown): ParsedPrecheck;
+/** A list bound as ONE SQL parameter, for `IN (SELECT value FROM json_each(?))`. */
+export declare function jsonList(values: readonly (string | number)[]): string;

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

@@ -0,0 +1,76 @@
+/**
+ * The wire contract of an upload PRE-CHECK — "which of these do you already have?", asked before
+ * a single byte of the files is sent (forge task 3579).
+ *
+ * The owner, 2026-10-22: *"They should find and skip dups efficiently without wasting bandwidth or
+ * processing power … They need to know dups based on the hashes rather than a long check such as
+ * copying the file first … I will sometimes reimport from huge directories just in case they have a
+ * new file that was missed on previous uploads and I want it to be fast."*
+ *
+ * ── Two questions, one route ───────────────────────────────────────────────────────────────
+ * 1. **`sizes`** — which of these byte sizes does the library hold at all? A file whose size
+ *    matches nothing stored CANNOT be a byte-identical copy, so it is uploaded without being hashed
+ *    first (binary-server hashes what it receives, as it always has). On a folder of mostly new
+ *    videos that is nearly every file, and nearly all of the hashing.
+ * 2. **`sha256`** — which of these whole-file SHA-256s does the library hold? Asked only for the
+ *    files whose size DID match, so the proof (the hash) is paid exactly where it can decide
+ *    something. A hit is never sent.
+ *
+ * A route answers both in one body, so a client may ask either or both. Every app's library is
+ * scoped by the app's own rules (an account, an owner) — the route answers for the CALLER only,
+ * which is also what keeps the answer from saying anything about anyone else's files.
+ *
+ * ── SQL: one bound parameter, any length ───────────────────────────────────────────────────
+ * D1 refuses a statement with more than 100 bound parameters, so `IN (?, ?, …)` over a batch of
+ * 1,000 hashes cannot be written. Bind the list ONCE as JSON instead —
+ * `WHERE checksum IN (SELECT value FROM json_each(?))` with {@link jsonList} — which D1 and
+ * `bun:sqlite` both run against the column's index.
+ */
+/** The most sizes one pre-check may ask about. A drop of 5,000 files asks once. */
+export const PRECHECK_MAX_SIZES = 5000;
+/** The most hashes one pre-check may ask about — a client sends them in batches this size or less. */
+export const PRECHECK_MAX_HASHES = 1000;
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+/** Is this a lowercase hex SHA-256 — the only spelling every store in the fleet records? */
+export function isSha256Hex(value) {
+    return typeof value === "string" && SHA256_HEX.test(value);
+}
+/**
+ * Validate a pre-check body — the ONE parser every app's route calls, so the limits and the
+ * spelling are the same everywhere. Duplicates collapse; order is not kept.
+ */
+export function parsePrecheckRequest(body) {
+    if (typeof body !== "object" || body === null || Array.isArray(body)) {
+        return { ok: false, error: "expected a JSON object with `sizes` and/or `sha256`" };
+    }
+    const { sizes: rawSizes, sha256: rawHashes } = body;
+    if (rawSizes !== undefined && !Array.isArray(rawSizes))
+        return { ok: false, error: "`sizes` must be an array" };
+    if (rawHashes !== undefined && !Array.isArray(rawHashes))
+        return { ok: false, error: "`sha256` must be an array" };
+    const sizes = new Set();
+    for (const size of rawSizes ?? []) {
+        if (!Number.isSafeInteger(size) || size < 0) {
+            return { ok: false, error: "every size must be a whole number of bytes" };
+        }
+        sizes.add(size);
+    }
+    const hashes = new Set();
+    for (const hash of rawHashes ?? []) {
+        const spelled = typeof hash === "string" ? hash.toLowerCase() : hash;
+        if (!isSha256Hex(spelled))
+            return { ok: false, error: "every sha256 must be 64 hex characters" };
+        hashes.add(spelled);
+    }
+    if (sizes.size > PRECHECK_MAX_SIZES) {
+        return { ok: false, error: `at most ${PRECHECK_MAX_SIZES} sizes per pre-check` };
+    }
+    if (hashes.size > PRECHECK_MAX_HASHES) {
+        return { ok: false, error: `at most ${PRECHECK_MAX_HASHES} hashes per pre-check` };
+    }
+    return { ok: true, sizes: [...sizes], sha256: [...hashes] };
+}
+/** A list bound as ONE SQL parameter, for `IN (SELECT value FROM json_each(?))`. */
+export function jsonList(values) {
+    return JSON.stringify(values);
+}

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

@@ -0,0 +1,26 @@
+/**
+ * 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 declare const NATIVE_HASH_MAX_BYTES: number;
+/**
+ * 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 declare const STREAM_SLICE_BYTES: number;
+export interface HashOptions {
+    /** 0..1 as the bytes are read. */
+    onProgress?: (fraction: number) => void;
+    signal?: AbortSignal;
+    /** Override {@link NATIVE_HASH_MAX_BYTES} — the specs force the streaming road with it. */
+    nativeMaxBytes?: number;
+}
+/**
+ * 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 declare function sha256OfBlob(blob: Blob, options?: HashOptions): Promise<string>;

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>>;