cursedbelt-core 2.13.2 → 2.14.0

package/src/core/analytics/range.ts

@@ -158,8 +158,8 @@ export const startOfBucket = (t: number, unit: BucketUnit): number =>
  * duplicated or missing bar exactly once every spring and autumn — the kind of
  * bug nobody reproduces.
  *
- * The time-of-day is carried through rather than normalised to midnight: every
- * caller here passes an already-aligned value, so normalising would be
+ * The time-of-day is carried through rather than normalized to midnight: every
+ * caller here passes an already-aligned value, so normalizing would be
  * invisible in this file and a trap for the first caller that does not.
  */
 export const addDays = (t: number, n: number): number => {

package/src/core/analytics/schedule.spec.ts

@@ -25,7 +25,7 @@ describe('simulateSchedule', () => {
     expect(simulateSchedule(items, { workers: 1 }).makespanMs).toBe(40 * MIN);
     expect(simulateSchedule(items, { workers: 2 }).makespanMs).toBe(20 * MIN);
     expect(simulateSchedule(items, { workers: 4 }).makespanMs).toBe(10 * MIN);
-    // Nothing left to parallelise — the fifth worker is inert.
+    // Nothing left to parallelize — the fifth worker is inert.
     expect(simulateSchedule(items, { workers: 5 }).makespanMs).toBe(10 * MIN);
   });
 
@@ -50,12 +50,12 @@ describe('simulateSchedule', () => {
     expect(simulateSchedule(items, { workers: 2 }).makespanMs).toBe(10 * MIN);
   });
 
-  it('serialises a named group without needing a shared resource', () => {
+  it('serializes a named group without needing a shared resource', () => {
     const items = [item('a', 5, { group: 'gpu' }), item('b', 5, { group: 'gpu' })];
     expect(simulateSchedule(items, { workers: 4 }).makespanMs).toBe(10 * MIN);
   });
 
-  it('honours dependencies', () => {
+  it('honors dependencies', () => {
     const items = [item('second', 10, { dependsOn: ['first'] }), item('first', 10)];
     const r = simulateSchedule(items, { workers: 4 });
     expect(r.makespanMs).toBe(20 * MIN);

package/src/core/analytics/schedule.ts

@@ -11,7 +11,7 @@
  * Three separate claims hide in that, and a `remaining / rate` division answers
  * none of them:
  *
- * 1. **Work does not parallelise freely.** Two tasks that write the same files
+ * 1. **Work does not parallelize freely.** Two tasks that write the same files
  *    may not run together whatever the fleet size — that is the orchestrator's
  *    own scope rule, and it is why a queue of ten tasks all scoped to one app
  *    drains at exactly the same speed with eight workers as with one.
@@ -312,10 +312,10 @@ function blocks(candidate: ScheduleItem, other: ScheduleItem): boolean {
 /**
  * A best-effort reason an item started late — for the table behind the chart.
  *
- * Deliberately approximate and labelled as such: the precise answer would need
+ * Deliberately approximate and labeled as such: the precise answer would need
  * the admission loop to record every refusal at every event, which is a lot of
  * bookkeeping for a column. "Was it waiting on a dependency, on a conflicting
- * neighbour, or simply for a free worker" is the distinction a reader acts on,
+ * neighbor, or simply for a free worker" is the distinction a reader acts on,
  * and that is decidable from the item alone.
  */
 function whyWaited(

package/src/core/duplicates/index.ts

@@ -17,7 +17,7 @@
  *
  * ── What is NOT here, deliberately ──────────────────────────────────────────────────────
  * Anything that needs a database, a filesystem, a fetch or a picture decoder. This module is
- * pure so both consumers can prove their behaviour with `bun test` instead of against a live
+ * pure so both consumers can prove their behavior with `bun test` instead of against a live
  * store, and so a browser bundle may import it (music renders the pair side by side).
  */
 
@@ -158,7 +158,7 @@ export function durationsClose(
 /** One file, reduced to what this module can reason about. Units are the caller's — pass
  *  both durations in the same unit or not at all. */
 export interface NamedFileFacts {
-	/** The name a person would recognise: a display title, else the last path segment. */
+	/** The name a person would recognize: a display title, else the last path segment. */
 	name: string | null | undefined;
 	sizeBytes: number;
 	/** Playing time, in whatever unit the caller uses consistently. Null = never measured. */

package/src/core/file-tree/fileTreeModel.ts

@@ -24,7 +24,7 @@
 export type FileTreeNodeKind = 'folder' | 'file';
 
 /**
- * How visible a node is, generalised from collections' private/locked folders.
+ * How visible a node is, generalized from collections' private/locked folders.
  *
  * 🔴 It is a LABEL, never an enforcement. The server decides what a session may see, and a
  * tree that hides a row the server sent (or shows one it did not) is a second, weaker
@@ -117,7 +117,7 @@ export interface FileTreeNode {
    *
    * For a consumer that narrows the tree itself (by content, not only by name) and keeps
    * the folders on the way to each hit: the hits are what the eye is scanning for, and the
-   * folders kept around them are context. Omit it and nothing is emphasised.
+   * folders kept around them are context. Omit it and nothing is emphasized.
    */
   matched?: boolean;
   /**
@@ -230,7 +230,7 @@ export function flattenFileTree(
        * "A row that claims to open onto nothing is its own small lie" was the old reasoning
        * and it is answered by what VS Code does: the chevron says *folder*, not *occupied*,
        * and opening an empty one onto nothing is the honest answer, not a broken promise.
-       * `node.expandable === false` is still honoured for a row that can never hold anything.
+       * `node.expandable === false` is still honored for a row that can never hold anything.
        */
       const expandable = node.kind === 'folder' && (node.expandable ?? true);
       const expanded = expandable && !shut.has(node.id);
@@ -447,7 +447,7 @@ export interface KeyboardMoveOptions {
  * without asking which of several folders was meant — and **← promotes out to the folder its
  * own folder is in**, which is `root` at depth 1.
  *
- * 🔴 Every refusal the DRAG honours is honoured here, from the same fields: `acceptsDrop`,
+ * 🔴 Every refusal the DRAG honors is honored here, from the same fields: `acceptsDrop`,
  * the consumer's `canDrop`, and the descendant rule. A keyboard route that can reach a
  * destination the pointer refuses is a second, weaker opinion about what is legal — and it
  * is the one nobody looks at, because the pointer is what gets tested by hand.

package/src/core/folder-tree/actions.ts

@@ -25,7 +25,7 @@
  * applies, with nothing destroyed. Deleting the CONTENTS destroys items, and this module
  * has never seen an item; it only ever sees the paths they carry. So `purge` is a mode the
  * menu offers and the CONSUMER implements against its own store, which is also the only
- * place that can count what is about to be lost or refuse the operation. Modelling it here
+ * place that can count what is about to be lost or refuse the operation. Modeling it here
  * would mean inventing an item, and an item this model cannot see is one it cannot protect.
  */
 

package/src/core/master-lock/kdf.ts

@@ -89,7 +89,7 @@ export async function deriveMasterLockVerifier(
 	}
 	const salt = unb64u(params.salt);
 	const kek = await pbkdf2(utf8(masterPassword), salt, params.iter);
-	// Same salt as the KEK, by design: it individualises the verifier without a second
+	// Same salt as the KEK, by design: it individualizes the verifier without a second
 	// stored value. One round, over KEK ‖ password.
 	const verifier = await pbkdf2(concat(kek, utf8(masterPassword)), salt, 1);
 	return b64u(verifier);

package/src/core/master-lock/presence.ts

@@ -23,7 +23,7 @@
  * ── 🔴 Why a decorative loop is NOT presence ────────────────────────────────
  * The failure mode that would make this a security hole is an ambient background clip
  * — muted, looping, autoplaying, running forever with nobody in the building. That is
- * a recognisable signature (`muted` AND `loop`) and it is refused. A film the owner is
+ * a recognizable signature (`muted` AND `loop`) and it is refused. A film the owner is
  * actually watching is not both at once; a muted film that loops is not something this
  * fleet renders. Where a component knows better than the heuristic, it says so:
  * `data-master-lock-presence="watch"` counts unconditionally, `"ignore"` never does.

package/src/core/master-lock/wire.ts

@@ -123,7 +123,7 @@ export const MASTER_LOCK_STATE_HEADER = "x-master-lock-state";
  *  nothing in the fleet constructs one. So adding a required field to it is
  *  additive, and without this annotation it is the residual false MAJOR that
  *  Phase −1's M-B measured and had no cheap fix for (F4). `release/surface.ts`
- *  records the annotation; `release/classify.ts` honours it. */
+ *  records the annotation; `release/classify.ts` honors it. */
 export interface MasterLockStatus {
 	/** Is a master password set at all? False only on an app that was never seeded,
 	 *  or — in per-person mode — for a person who has not chosen one yet. */

package/src/core/media/mediaItem.ts

@@ -1,5 +1,5 @@
 // Pure MediaItem helpers — kind predicates + dimension/aspect resolution. The React
-// catalogue maps items to layout photos through these, so the "what size is this
+// catalog maps items to layout photos through these, so the "what size is this
 // thumbnail" logic is tested here, not buried in a component.
 
 import type { MediaItem } from './types.js';

package/src/core/media/types.ts

@@ -66,11 +66,11 @@ export type VideoProgressEvent = {
   error?: string;
 };
 
-/** The three media kinds the catalogue + lightbox understand. */
+/** The three media kinds the catalog + lightbox understand. */
 export type MediaKind = 'image' | 'video' | 'audio';
 
 /**
- * A URL-only catalogue item — the unit the `<MediaCatalogueViewer>` renders. It
+ * A URL-only catalog item — the unit the `<MediaCatalogueViewer>` renders. It
  * holds NO storage identity (no FsNode, no binary id): the app maps its own records
  * to this and pre-resolves `url`/`thumbnailUrl` (signing private files as needed).
  */
@@ -92,7 +92,7 @@ export type MediaItem = {
 };
 
 /**
- * A gallery photo — a {@link MediaItem} specialized to images, plus the catalogue affordances a
+ * A gallery photo — a {@link MediaItem} specialized to images, plus the catalog affordances a
  * photo grid renders (tags for the filter strip, createdAt for ordering, favorite for the ♥).
  * Like every media-core unit it carries only resolved URLs — no storage identity.
  */
@@ -123,7 +123,7 @@ export type ProcessingStatus = 'pending' | 'processing' | 'ready' | 'failed';
 /**
  * A surface-agnostic description of a playable video with every URL already resolved —
  * the unit the `<VideoPlayer>` primitive consumes (distinct from {@link MediaItem}, which
- * is the lightbox catalogue unit). It carries NO storage identity: a source pre-resolves
+ * is the lightbox catalog unit). It carries NO storage identity: a source pre-resolves
  * the streaming URLs (signing/tokenising private ones), so the player couples to nothing.
  * Richer than `MediaItem`: an HLS master + scrub-preview track for a real player HUD.
  */

package/src/core/media/videoCuts.ts

@@ -74,7 +74,7 @@ export interface VideoCut {
  * The shortest span worth cutting, in seconds.
  *
  * 🔴 Not zero, and not "whatever the person dragged". Below roughly a frame the request is
- * indistinguishable from a mis-click, and it is a request ffmpeg cannot honour anyway — a
+ * indistinguishable from a mis-click, and it is a request ffmpeg cannot honor anyway — a
  * cut has to land on a frame boundary, so a 4 ms span asks the encoder to remove nothing and
  * charges a full re-encode of the file for it. 40 ms is one frame at 25fps, the slowest rate
  * anything in this library was shot at.
@@ -320,7 +320,7 @@ export function toggleSegment(plan: CutPlan, segment: VideoCut, duration: number
       splits: plan.splits,
       // Drop every removal this segment sits inside, then put back the parts of a WIDER
       // removal that are still meant to go — un-marking one piece of a span that was marked
-      // before it was split must not resurrect its neighbours.
+      // before it was split must not resurrect its neighbors.
       removed: plan.removed.flatMap((cut) => {
         if (!(cut.start <= current.start + 1e-6 && cut.end >= current.end - 1e-6)) return [cut];
         const rest: VideoCut[] = [];

package/src/core/navigation/index.ts

@@ -1,6 +1,6 @@
 // `cursedbelt-core/navigation` — the navigation contract + pure selectors. React-free and
 // routing-free: the single source of truth (the IA tree) plus every derivation off
-// it (side nav, hub tiles, breadcrumbs, search catalogue, coverage test, prefs
+// it (side nav, hub tiles, breadcrumbs, search catalog, coverage test, prefs
 // migration). The React components in `cursedbelt/react` consume exactly this.
 
 export {

package/src/core/navigation/navigation.spec.ts

@@ -245,7 +245,7 @@ describe('deriveBreadcrumbTrail', () => {
 describe('deriveSearchCatalogue + rankCatalogue', () => {
   const catalogue = deriveSearchCatalogue(model, allowAll);
 
-  test('every visible domain + item is catalogued; deepLinkOnly is excluded', () => {
+  test('every visible domain + item is cataloged; deepLinkOnly is excluded', () => {
     const ids = catalogue.map((e) => e.id);
     expect(ids).toContain('fractal');
     expect(ids).toContain('env-sets');
@@ -280,7 +280,7 @@ describe('deriveSearchCatalogue + rankCatalogue', () => {
     expect(userCat.map((e) => e.id)).not.toContain('admin-users');
   });
 
-  test("a DOMAIN's description + keywords reach the catalogue, so a leaf-shaped rail is findable by synonym", () => {
+  test("a DOMAIN's description + keywords reach the catalog, so a leaf-shaped rail is findable by synonym", () => {
     // The asymmetry this closes: an app whose places are leaf domains (no
     // sub-items) used to be searchable by exact label only, while an identical
     // rail expressed as items matched synonyms — a data-model gap, not a ranking one.
@@ -305,7 +305,7 @@ describe('deriveSearchCatalogue + rankCatalogue', () => {
     expect(rankCatalogue(leafRail, 'review')[0]?.id).toBe('changes');
   });
 
-  test('a domain without them still catalogues cleanly (both stay optional)', () => {
+  test('a domain without them still catalogs cleanly (both stay optional)', () => {
     const bare = deriveSearchCatalogue(
       { domains: [{ id: 'x', label: 'X', icon: 'a', path: '/x', groups: [] }] },
       allowAll,

package/src/core/navigation/navigationModel.ts

@@ -1,6 +1,6 @@
 // The single navigation source of truth — a declarative Information-Architecture
 // tree (Domain → Group → Item) every nav surface derives from: the side nav, hub
-// landing tiles, breadcrumbs, the universal-search catalogue, and the command
+// landing tiles, breadcrumbs, the universal-search catalog, and the command
 // palette. Authoring a feature into the model is the *only* way to surface it, so
 // the historical "four hand-maintained lists drift out of sync → features get
 // buried" bug is structurally impossible (the coverage test enforces it in CI).
@@ -135,7 +135,7 @@ export interface NavDomain {
    * again the same as on a {@link NavItem}.
    *
    * Both of these exist because a domain IS a destination: `deriveSearchCatalogue`
-   * emits one catalogue entry per domain, so a rail of leaf-shaped domains (an app
+   * emits one catalog entry per domain, so a rail of leaf-shaped domains (an app
    * whose places have no sub-items) had no way to be found by synonym while an
    * otherwise identical rail of items did. That asymmetry was in the data model,
    * not in the ranker.

package/src/core/navigation/navigationSelectors.ts

@@ -1,5 +1,5 @@
 // Pure derivations off the {@link NavigationModel}. Every nav surface (side nav,
-// hub tiles, breadcrumbs, search catalogue, palette, the coverage test) reads the
+// hub tiles, breadcrumbs, search catalog, palette, the coverage test) reads the
 // model exclusively through these — there is no second list to keep in sync. They
 // import nothing from React, so they run identically in the client, in a server
 // test, and in the CI coverage check.
@@ -38,7 +38,7 @@ export function normalizeNavPath(path: string): string {
   return p || '/';
 }
 
-/** A flattened, gated catalogue entry — a leaf plus where it lives (for grouping). */
+/** A flattened, gated catalog entry — a leaf plus where it lives (for grouping). */
 export interface SearchCatalogueEntry extends NavItem {
   /** Owning domain id (absent for ungrouped items). */
   domainId?: string;
@@ -160,7 +160,7 @@ export function deriveBreadcrumbTrail(
  * The flat list of searchable destinations — every visible (gated,
  * non-`deepLinkOnly`) domain landing + item, `searchOnly` ones included, each tagged with its domain/group so
  * results can be grouped. Drives HeaderSearch's instant pages layer *and* the
- * command palette; replaces every hand-listed search catalogue (so a feature is
+ * command palette; replaces every hand-listed search catalog (so a feature is
  * findable the moment it's registered).
  */
 export function deriveSearchCatalogue(

package/src/core/navigation/searchCatalogue.ts

@@ -1,5 +1,5 @@
 // Pure matcher + grouper for the instant client-side "pages" search layer. Ranks a
-// derived catalogue ({@link deriveSearchCatalogue}) against a query and buckets the
+// derived catalog ({@link deriveSearchCatalogue}) against a query and buckets the
 // hits by their owning domain. Kept pure + framework-free so it's unit-testable and
 // shared by HeaderSearch and (task 14) the command palette. The palette upgrades the
 // *ranking* to uFuzzy; this is the dependency-free baseline both can fall back to.
@@ -49,8 +49,8 @@ function scoreEntry(entry: SearchCatalogueEntry, q: string): number {
 }
 
 /**
- * Filter + rank a catalogue by `query`. Empty/blank query → `[]` (the instant layer
- * shows nothing until the user types). Stable: equal scores keep catalogue order.
+ * Filter + rank a catalog by `query`. Empty/blank query → `[]` (the instant layer
+ * shows nothing until the user types). Stable: equal scores keep catalog order.
  */
 export function rankCatalogue(catalogue: SearchCatalogueEntry[], query: string): CatalogueHit[] {
   const q = norm(query);
@@ -61,7 +61,7 @@ export function rankCatalogue(catalogue: SearchCatalogueEntry[], query: string):
     if (score > 0) scored.push({ ...entry, score });
   }
   // Stable sort by score desc — Array.prototype.sort is stable in modern engines, so
-  // equal scores retain catalogue (authoring) order.
+  // equal scores retain catalog (authoring) order.
   return scored.sort((a, b) => b.score - a.score);
 }
 

package/src/core/palette/fuzzyRank.ts

@@ -1,4 +1,4 @@
-// The command-palette ranking layer — uFuzzy over the nav catalogue. This is the
+// The command-palette ranking layer — uFuzzy over the nav catalog. This is the
 // *upgrade* HeaderSearch's `rankCatalogue` (a substring scorer) cannot match: uFuzzy
 // scores by contiguous-match proximity, so abbreviated/typeahead input ranks the
 // right page first. Pure + synchronous + React-free (uFuzzy is regex-based, no DOM),
@@ -48,7 +48,7 @@ function haystackFor(item: NavItem): string {
 
 /**
  * The SECOND tier: what a destination holds rather than what it is called — its description,
- * and the group and place it sits under when the entry carries them (catalogue entries do).
+ * and the group and place it sits under when the entry carries them (catalog entries do).
  * Owner, 2026-10-09: *"I may not know where to go but typing something like 'api' brings up the
  * relevant page links quickly"* — a page found only by its exact name is not found by someone
  * who does not know the name.
@@ -70,7 +70,7 @@ function rankedIndexes(haystack: string[], q: string): number[] {
 
 /**
  * Rank `items` against `query`, best match first; non-matches dropped. Generic over the
- * item type (so callers can pass plain {@link NavItem}s *or* richer catalogue entries
+ * item type (so callers can pass plain {@link NavItem}s *or* richer catalog entries
  * that carry domain/group tags for grouping — the extra fields ride straight through).
  * An empty/blank query returns `[]` (the palette shows its cold state instead).
  *

package/src/core/tokens/registry.ts

@@ -40,7 +40,7 @@ export interface TokenDef<S extends z.ZodType = z.ZodType> {
   subtypeOf?: string;
   /** Canonical payload injected by the V7.4 wire smoke probe. Must satisfy `schema`. */
   sample: z.infer<S>;
-  /** True when this token receives third-party traffic — triggers the V3 marshaller gates. */
+  /** True when this token receives third-party traffic — triggers the V3 marshaler gates. */
   external?: boolean;
   deprecated?: TokenDeprecation;
   description: string;
@@ -493,7 +493,7 @@ export const BASE_TOKENS: readonly TokenDef[] = [
     id: 'knowledge:records',
     mode: 'value',
     external: true,
-    description: 'Imported record rows (CSV/sheet/webhook) — external traffic, marshaller-gated (02 §7.1).',
+    description: 'Imported record rows (CSV/sheet/webhook) — external traffic, marshaler-gated (02 §7.1).',
     schema: z.object({ rows: z.array(z.record(z.string(), z.unknown())) }),
     sample: { rows: [{ id: '1' }] },
   },

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

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

@@ -0,0 +1,46 @@
+/**
+ * `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";