cursedbelt-core 2.13.3 → 2.14.0

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

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

@@ -0,0 +1,27 @@
+/**
+ * An INCREMENTAL SHA-256 — fed chunk by chunk, for a Blob too big to hold in one buffer.
+ *
+ * 🔴 Why not `crypto.subtle.digest`: it takes the whole message in one buffer, and a PS2 disc is
+ * up to 8.5 GB, a camera video several. Born in roms (`src/ps2/sha256.ts`, the disc download's
+ * verifier) and moved here so every app's upload pre-check hashes with the same code
+ * (forge task 3579). `sha256.spec.ts` pins it against WebCrypto across every chunk boundary that
+ * matters (55/56/64 bytes, and a 1 MB split at an odd offset).
+ *
+ * Measured on this Mac under Bun, 256 MiB in 8 MiB slices: 184 MiB/s here, 195 MiB/s for
+ * `@noble/hashes`, 1,960 MiB/s for `crypto.subtle` — which is why {@link sha256OfBlob} only falls
+ * back to this past the size it is willing to read into memory at once.
+ */
+export declare class Sha256 {
+    private readonly h;
+    /** Back to the empty message — a download that has to start over. */
+    reset(): this;
+    private readonly w;
+    private readonly tail;
+    private tailLength;
+    /** Total bytes fed, as a double — exact to 2^53, far past any disc. */
+    private length;
+    update(data: Uint8Array): this;
+    /** The digest as lowercase hex. The hasher is spent afterwards. */
+    hex(): string;
+    private block;
+}

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

@@ -0,0 +1,124 @@
+/**
+ * An INCREMENTAL SHA-256 — fed chunk by chunk, for a Blob too big to hold in one buffer.
+ *
+ * 🔴 Why not `crypto.subtle.digest`: it takes the whole message in one buffer, and a PS2 disc is
+ * up to 8.5 GB, a camera video several. Born in roms (`src/ps2/sha256.ts`, the disc download's
+ * verifier) and moved here so every app's upload pre-check hashes with the same code
+ * (forge task 3579). `sha256.spec.ts` pins it against WebCrypto across every chunk boundary that
+ * matters (55/56/64 bytes, and a 1 MB split at an odd offset).
+ *
+ * Measured on this Mac under Bun, 256 MiB in 8 MiB slices: 184 MiB/s here, 195 MiB/s for
+ * `@noble/hashes`, 1,960 MiB/s for `crypto.subtle` — which is why {@link sha256OfBlob} only falls
+ * back to this past the size it is willing to read into memory at once.
+ */
+const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5, 0xd807aa98,
+    0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786,
+    0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d, 0xb00327c8,
+    0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+    0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819,
+    0xd6990624, 0xf40e3585, 0x106aa070, 0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a,
+    0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7,
+    0xc67178f2,
+]);
+const INITIAL = [0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19];
+export class Sha256 {
+    h = new Uint32Array(INITIAL);
+    /** Back to the empty message — a download that has to start over. */
+    reset() {
+        this.h.set(INITIAL);
+        this.tailLength = 0;
+        this.length = 0;
+        return this;
+    }
+    w = new Uint32Array(64);
+    tail = new Uint8Array(64);
+    tailLength = 0;
+    /** Total bytes fed, as a double — exact to 2^53, far past any disc. */
+    length = 0;
+    update(data) {
+        this.length += data.length;
+        let offset = 0;
+        if (this.tailLength > 0) {
+            const take = Math.min(64 - this.tailLength, data.length);
+            this.tail.set(data.subarray(0, take), this.tailLength);
+            this.tailLength += take;
+            offset = take;
+            if (this.tailLength < 64)
+                return this;
+            this.block(this.tail, 0);
+            this.tailLength = 0;
+        }
+        const whole = data.length - ((data.length - offset) % 64);
+        for (; offset < whole; offset += 64)
+            this.block(data, offset);
+        if (offset < data.length) {
+            this.tail.set(data.subarray(offset), 0);
+            this.tailLength = data.length - offset;
+        }
+        return this;
+    }
+    /** The digest as lowercase hex. The hasher is spent afterwards. */
+    hex() {
+        const bits = this.length * 8;
+        const pad = new Uint8Array(this.tailLength < 56 ? 64 : 128);
+        pad.set(this.tail.subarray(0, this.tailLength));
+        pad[this.tailLength] = 0x80;
+        const view = new DataView(pad.buffer);
+        view.setUint32(pad.length - 8, Math.floor(bits / 2 ** 32));
+        view.setUint32(pad.length - 4, bits >>> 0);
+        for (let offset = 0; offset < pad.length; offset += 64)
+            this.block(pad, offset);
+        let out = "";
+        for (const word of this.h)
+            out += word.toString(16).padStart(8, "0");
+        return out;
+    }
+    block(data, offset) {
+        const w = this.w;
+        for (let i = 0; i < 16; i++) {
+            const j = offset + i * 4;
+            w[i] = (data[j] << 24) | (data[j + 1] << 16) | (data[j + 2] << 8) | data[j + 3];
+        }
+        for (let i = 16; i < 64; i++) {
+            const a = w[i - 15];
+            const b = w[i - 2];
+            const s0 = ((a >>> 7) | (a << 25)) ^ ((a >>> 18) | (a << 14)) ^ (a >>> 3);
+            const s1 = ((b >>> 17) | (b << 15)) ^ ((b >>> 19) | (b << 13)) ^ (b >>> 10);
+            w[i] = (w[i - 16] + s0 + w[i - 7] + s1) | 0;
+        }
+        const h = this.h;
+        let a = h[0];
+        let b = h[1];
+        let c = h[2];
+        let d = h[3];
+        let e = h[4];
+        let f = h[5];
+        let g = h[6];
+        let hh = h[7];
+        for (let i = 0; i < 64; i++) {
+            const S1 = ((e >>> 6) | (e << 26)) ^ ((e >>> 11) | (e << 21)) ^ ((e >>> 25) | (e << 7));
+            const ch = (e & f) ^ (~e & g);
+            const t1 = (hh + S1 + ch + K[i] + w[i]) | 0;
+            const S0 = ((a >>> 2) | (a << 30)) ^ ((a >>> 13) | (a << 19)) ^ ((a >>> 22) | (a << 10));
+            const maj = (a & b) ^ (a & c) ^ (b & c);
+            const t2 = (S0 + maj) | 0;
+            hh = g;
+            g = f;
+            f = e;
+            e = (d + t1) | 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) | 0;
+        }
+        h[0] = (h[0] + a) | 0;
+        h[1] = (h[1] + b) | 0;
+        h[2] = (h[2] + c) | 0;
+        h[3] = (h[3] + d) | 0;
+        h[4] = (h[4] + e) | 0;
+        h[5] = (h[5] + f) | 0;
+        h[6] = (h[6] + g) | 0;
+        h[7] = (h[7] + hh) | 0;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-core",
-	"version": "2.13.3",
+	"version": "2.14.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "Framework-agnostic core of the cursedbelt split — isomorphic domain logic. cwip below it, cursedbelt-server and cursedbelt (react) above it.",
@@ -133,6 +133,12 @@
 			"source": "./src/core/duplicates/index.ts",
 			"import": "./dist/core/duplicates/index.js"
 		},
+		"./upload-precheck": {
+			"types": "./dist/core/upload-precheck/index.d.ts",
+			"bun": "./src/core/upload-precheck/index.ts",
+			"source": "./src/core/upload-precheck/index.ts",
+			"import": "./dist/core/upload-precheck/index.js"
+		},
 		"./errors": {
 			"types": "./dist/shared/errors.d.ts",
 			"bun": "./src/shared/errors.ts",

package/src/core/upload-precheck/contract.spec.ts

@@ -0,0 +1,67 @@
+import { Database } from "bun:sqlite";
+import { describe, expect, test } from "bun:test";
+import { jsonList, PRECHECK_MAX_HASHES, PRECHECK_MAX_SIZES, parsePrecheckRequest } from "./contract.js";
+import { NATIVE_HASH_MAX_BYTES, sha256OfBlob } from "./hash.js";
+
+const sha = (n: number) => n.toString(16).padStart(64, "0");
+
+describe("parsePrecheckRequest", () => {
+	test("both lists, deduplicated, hashes lower-cased", () => {
+		const parsed = parsePrecheckRequest({ sizes: [3, 3, 0], sha256: [sha(1).toUpperCase(), sha(1)] });
+		expect(parsed).toEqual({ ok: true, sizes: [3, 0], sha256: [sha(1)] });
+	});
+
+	test("either list may be absent", () => {
+		expect(parsePrecheckRequest({})).toEqual({ ok: true, sizes: [], sha256: [] });
+	});
+
+	test.each([
+		[null],
+		[[1, 2]],
+		[{ sizes: "3" }],
+		[{ sizes: [-1] }],
+		[{ sizes: [1.5] }],
+		[{ sha256: ["abc"] }],
+		[{ sha256: [42] }],
+		[{ sizes: Array.from({ length: PRECHECK_MAX_SIZES + 1 }, (_, i) => i) }],
+		[{ sha256: Array.from({ length: PRECHECK_MAX_HASHES + 1 }, (_, i) => sha(i)) }],
+	])("refuses %j", (body) => {
+		expect(parsePrecheckRequest(body).ok).toBe(false);
+	});
+});
+
+describe("jsonList — one bound parameter for a whole batch", () => {
+	test("🔴 a full batch of hashes in ONE statement, answered from the index", () => {
+		// D1 refuses more than 100 bound parameters; this is the shape that never needs more than one.
+		const db = new Database(":memory:");
+		db.run("CREATE TABLE items (id INTEGER PRIMARY KEY, owner TEXT, checksum TEXT, size INTEGER)");
+		db.run("CREATE INDEX items_owner_checksum ON items(owner, checksum)");
+		const insert = db.prepare("INSERT INTO items (owner, checksum, size) VALUES (?, ?, ?)");
+		for (let i = 0; i < 5000; i++) insert.run(i % 2 ? "me" : "you", sha(i), i);
+		const asked = Array.from({ length: PRECHECK_MAX_HASHES }, (_, i) => sha(i * 3));
+		const sql = "SELECT checksum FROM items WHERE owner = ? AND checksum IN (SELECT value FROM json_each(?))";
+		const rows = db.prepare(sql).all("me", jsonList(asked)) as { checksum: string }[];
+		expect(rows.length).toBe(asked.filter((_, i) => (i * 3) % 2 === 1).length);
+		const plan = (db.prepare(`EXPLAIN QUERY PLAN ${sql}`).all("me", jsonList(asked)) as { detail: string }[])
+			.map((r) => r.detail)
+			.join(" | ");
+		expect(plan).toContain("USING COVERING INDEX items_owner_checksum");
+	});
+});
+
+describe("sha256OfBlob", () => {
+	test("the native road and the streaming road give the same digest", async () => {
+		const bytes = new Uint8Array(5 * 1024 * 1024 + 13).map((_, i) => (i * 31) & 0xff);
+		const blob = new Blob([bytes]);
+		const native = await sha256OfBlob(blob);
+		let last = 0;
+		const streamed = await sha256OfBlob(blob, { nativeMaxBytes: 1024, onProgress: (f) => (last = f) });
+		expect(streamed).toBe(native);
+		expect(last).toBe(1);
+		expect(NATIVE_HASH_MAX_BYTES).toBeGreaterThan(64 * 1024 * 1024);
+	});
+
+	test("the empty file", async () => {
+		expect(await sha256OfBlob(new Blob([]))).toBe("e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855");
+	});
+});

package/src/core/upload-precheck/contract.ts

@@ -0,0 +1,107 @@
+/**
+ * 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;
+
+/** 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>;
+}
+
+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: unknown): value is string {
+	return typeof value === "string" && SHA256_HEX.test(value);
+}
+
+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 function parsePrecheckRequest(body: unknown): ParsedPrecheck {
+	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 as Record<string, unknown>;
+	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<number>();
+	for (const size of rawSizes ?? []) {
+		if (!Number.isSafeInteger(size) || (size as number) < 0) {
+			return { ok: false, error: "every size must be a whole number of bytes" };
+		}
+		sizes.add(size as number);
+	}
+	const hashes = new Set<string>();
+	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: readonly (string | number)[]): string {
+	return JSON.stringify(values);
+}

package/src/core/upload-precheck/hash.ts

@@ -0,0 +1,57 @@
+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;
+
+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;
+}
+
+function hex(digest: ArrayBuffer): string {
+	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: AbortSignal | undefined): void {
+	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: Blob, options: HashOptions = {}): Promise<string> {
+	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();
+}