cursedbelt-core 2.13.2 → 2.14.0

package/dist/core/analytics/range.d.ts

@@ -94,8 +94,8 @@ export declare 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 declare const addDays: (t: number, n: number) => number;

package/dist/core/analytics/range.js

@@ -102,8 +102,8 @@ export const startOfBucket = (t, unit) => unit === 'hour' ? startOfHour(t) : sta
  * 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, n) => {

package/dist/core/analytics/schedule.d.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.

package/dist/core/analytics/schedule.js

@@ -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.
@@ -179,10 +179,10 @@ function blocks(candidate, other) {
 /**
  * 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(item, _timeline, known) {

package/dist/core/duplicates/index.d.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).
  */
 /**
@@ -93,7 +93,7 @@ export declare function durationsClose(a: number | null | undefined, b: number |
 /** 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/dist/core/duplicates/index.js

@@ -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).
  */
 /**

package/dist/core/file-tree/fileTreeModel.d.ts

@@ -22,7 +22,7 @@
 /** What a row IS. `folder` may hold children and accept drops; `file` is a leaf. */
 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
@@ -114,7 +114,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;
     /**
@@ -280,7 +280,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/dist/core/file-tree/fileTreeModel.js

@@ -68,7 +68,7 @@ export function flattenFileTree(nodes, collapsed) {
              * "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);
@@ -210,7 +210,7 @@ export function resolveDrop({ nodes, row, offsetRatio, dragId, allowReorder = fa
  * 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/dist/core/folder-tree/actions.d.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.
  */
 import type { FolderNode, FolderRemap } from "./tree.js";

package/dist/core/folder-tree/actions.js

@@ -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.
  */
 import { folderPathKey, isFolderPathUnder, parseFolderPath, serializeFolderPath, } from "./path.js";

package/dist/core/master-lock/kdf.js

@@ -70,7 +70,7 @@ export async function deriveMasterLockVerifier(masterPassword, params) {
     }
     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/dist/core/master-lock/presence.d.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/dist/core/master-lock/presence.js

@@ -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/dist/core/master-lock/wire.d.ts

@@ -112,7 +112,7 @@ export declare 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/dist/core/media/mediaItem.js

@@ -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.
 export const isImageItem = (item) => item.type === 'image';
 export const isVideoItem = (item) => item.type === 'video';

package/dist/core/media/types.d.ts

@@ -71,10 +71,10 @@ export type VideoProgressEvent = {
     progressPercent?: number;
     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).
  */
@@ -95,7 +95,7 @@ export type MediaItem = {
     durationSeconds?: number;
 };
 /**
- * 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.
  */
@@ -124,7 +124,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/dist/core/media/videoCuts.d.ts

@@ -43,7 +43,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.

package/dist/core/media/videoCuts.js

@@ -38,7 +38,7 @@
  * 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.
@@ -252,7 +252,7 @@ export function toggleSegment(plan, segment, duration) {
             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];

package/dist/core/navigation/index.js

@@ -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 { buildBreadcrumbTrail, } from './breadcrumbCompat.js';
 export { createCoverageTest, findCoverageGaps, } from './coverageTest.js';

package/dist/core/navigation/navigationModel.d.ts

@@ -118,7 +118,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/dist/core/navigation/navigationModel.js

@@ -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).

package/dist/core/navigation/navigationSelectors.d.ts

@@ -12,7 +12,7 @@ import { type GateFn, type NavDomain, type NavGroup, type NavItem, type Navigati
  * stands before it and it starts with `/` — `/tools#tab=curl` is still `/tools`.
  */
 export declare function normalizeNavPath(path: string): string;
-/** 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;
@@ -57,7 +57,7 @@ export declare function deriveBreadcrumbTrail(model: NavigationModel, path: stri
  * 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 declare function deriveSearchCatalogue(model: NavigationModel, gate?: GateFn): SearchCatalogueEntry[];

package/dist/core/navigation/navigationSelectors.js

@@ -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.
@@ -118,7 +118,7 @@ export function deriveBreadcrumbTrail(model, path, gate = allowAllGate) {
  * 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(model, gate = allowAllGate) {

package/dist/core/navigation/searchCatalogue.d.ts

@@ -12,8 +12,8 @@ export interface CatalogueResultGroup {
     items: CatalogueHit[];
 }
 /**
- * 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 declare function rankCatalogue(catalogue: SearchCatalogueEntry[], query: string): CatalogueHit[];
 /**

package/dist/core/navigation/searchCatalogue.js

@@ -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.
@@ -39,8 +39,8 @@ function scoreEntry(entry, q) {
     return 0;
 }
 /**
- * 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, query) {
     const q = norm(query);
@@ -53,7 +53,7 @@ export function rankCatalogue(catalogue, query) {
             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/dist/core/palette/fuzzyRank.d.ts

@@ -7,7 +7,7 @@ import type { NavItem } from '../navigation/index.js';
 export declare function searchInitials(label: string): string;
 /**
  * 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/dist/core/palette/fuzzyRank.js

@@ -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),
@@ -42,7 +42,7 @@ function haystackFor(item) {
 }
 /**
  * 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.
@@ -63,7 +63,7 @@ function rankedIndexes(haystack, q) {
 }
 /**
  * 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/dist/core/tokens/registry.d.ts

@@ -36,7 +36,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;

package/dist/core/tokens/registry.js

@@ -405,7 +405,7 @@ export const BASE_TOKENS = [
         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/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>;