@gentleduck/upload 0.2.4 → 0.2.6

package/dist/index.js

@@ -1 +1 @@
-import{C as e,S as t,_ as n,a as r,b as i,c as a,d as o,f as s,g as c,h as l,i as u,l as d,m as f,n as p,o as m,p as h,r as g,s as _,t as v,u as y,v as b,w as x,x as S,y as C}from"./core-BNxznRif.js";import{t as w}from"./async-DxRWu4le.js";import{UploadProvider as T,createUploadFactory as E,useOptionalUploadStore as D,useUploadStore as O,useUploader as k,useUploaderActions as A}from"./react/index.js";import{PostStrategy as j,createStrategyRegistry as M,multipartStrategy as N}from"./strategies/index.js";export{C as DEFAULT_MAX_ATTEMPTS,i as DEFAULT_MAX_CONCURRENT_UPLOADS,S as DEFAULT_MAX_ITEMS,t as DEFAULT_PROGRESS_THROTTLE_MS,e as DEFAULT_RETRY_DELAY_BASE_MS,x as DEFAULT_RETRY_DELAY_MAX_MS,d as IndexedDBAdapter,a as LocalStorageAdapter,_ as MemoryAdapter,j as PostStrategy,T as UploadProvider,o as computeFingerprint,g as createReducer,M as createStrategyRegistry,u as createTypedEmitter,v as createUploadClient,E as createUploadFactory,p as createUploadStore,y as createXHRTransport,r as deserializeSnapshot,s as fingerprintMatches,n as generateId,l as isRecord,N as multipartStrategy,b as resolveUploadConfig,m as serializeSnapshot,w as sleep,D as useOptionalUploadStore,O as useUploadStore,k as useUploader,A as useUploaderActions,c as validateFile,h as validateFileList,f as validateIntent};
+import{C as e,S as t,_ as n,a as r,b as i,c as a,d as o,f as s,g as c,h as l,i as u,l as d,m as f,n as p,o as m,p as h,r as g,s as _,t as v,u as y,v as b,w as x,x as S,y as C}from"./core-CMkrP9DX.js";import{t as w}from"./async-DxRWu4le.js";import{UploadProvider as T,createUploadFactory as E,useOptionalUploadStore as D,useUploadStore as O,useUploader as k,useUploaderActions as A}from"./react/index.js";import{PostStrategy as j,createStrategyRegistry as M,multipartStrategy as N}from"./strategies/index.js";export{C as DEFAULT_MAX_ATTEMPTS,i as DEFAULT_MAX_CONCURRENT_UPLOADS,S as DEFAULT_MAX_ITEMS,t as DEFAULT_PROGRESS_THROTTLE_MS,e as DEFAULT_RETRY_DELAY_BASE_MS,x as DEFAULT_RETRY_DELAY_MAX_MS,d as IndexedDBAdapter,a as LocalStorageAdapter,_ as MemoryAdapter,j as PostStrategy,T as UploadProvider,o as computeFingerprint,g as createReducer,M as createStrategyRegistry,u as createTypedEmitter,v as createUploadClient,E as createUploadFactory,p as createUploadStore,y as createXHRTransport,r as deserializeSnapshot,s as fingerprintMatches,n as generateId,c as isRecord,N as multipartStrategy,b as resolveUploadConfig,m as serializeSnapshot,w as sleep,D as useOptionalUploadStore,O as useUploadStore,k as useUploader,A as useUploaderActions,h as validateFile,f as validateFileList,l as validateIntent};

package/dist/react/index.d.ts

@@ -1,28 +1,9 @@
 import { f as IntentMap, l as UploadResultBase, o as CursorMap } from "../strategy.types-gg9ZStRe.js";
-import { B as UploadItem, E as UploadEventMap, G as UploadCommand, T as UploadStore, V as UploadPhase } from "../index-BXg9WIce.js";
+import { B as UploadItem, E as UploadEventMap, G as UploadCommand, T as UploadStore, V as UploadPhase } from "../index-C38Jmizu.js";
 import { ReactNode } from "react";
 
 //#region src/react/upload-provider.d.ts
-/**
- * Provider component that makes the upload store available to child components.
- *
- * @template M - Intent map type
- * @template C - Cursor map type
- * @template P - Purpose type
- *
- * @param props - Provider props
- * @param props.store - Upload store instance to provide
- * @param props.children - Child components that can access the store
- *
- * @returns {JSX.Element} Context provider wrapping children
- *
- * @example
- * ```tsx
- * <UploadProvider store={store}>
- *   <UploadDropzone purpose="avatar" />
- * </UploadProvider>
- * ```
- */
+/** Provides an upload store to descendants. */
 declare function UploadProvider<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase = UploadResultBase>({
   store,
   children
@@ -31,29 +12,12 @@ declare function UploadProvider<M extends IntentMap, C extends CursorMap<M>, P e
   children: ReactNode;
 }): React.JSX.Element;
 /**
- * Hook to access the upload store from React context when present.
- *
- * Some higher-level hooks support either an explicit store argument or context.
- * They use this helper so the context read stays unconditional without throwing
- * when a caller intentionally passes a store instance.
+ * Read the upload store from context if provided. Returns `null` outside a
+ * provider so higher-level hooks can keep their context read unconditional
+ * while still accepting an explicit store argument.
  */
 declare function useOptionalUploadStore<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase = UploadResultBase>(): UploadStore<M, C, P, R> | null;
-/**
- * Hook to access the upload store from React context.
- *
- * @template M - Intent map type
- * @template C - Cursor map type
- * @template P - Purpose type
- *
- * @returns {UploadStore<M, C, P>} The upload store instance
- * @throws {Error} If called outside of UploadProvider
- *
- * @example
- * ```tsx
- * const store = useUploadStore()
- * const snapshot = store.getSnapshot()
- * ```
- */
+/** Read the upload store from context. Throws when called outside `UploadProvider`. */
 declare function useUploadStore<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase = UploadResultBase>(): UploadStore<M, C, P, R>;
 //#endregion
 //#region src/react/use-uploader.d.ts
@@ -74,11 +38,8 @@ type Uploader<M extends IntentMap, C extends CursorMap<M>, P extends string, R e
   ready: UploadItem<M, C, P, R>[];
 };
 /**
- * Stable action surface for React consumers that need imperative store access.
- *
- * This is declared explicitly instead of relying on an inferred object return
- * type so the generated package declarations do not leak the internal generic
- * names created by `store.on.bind(store)`.
+ * Imperative action surface. Declared explicitly (not inferred) so generated
+ * .d.ts files do not leak internal generic names created by `store.on.bind(store)`.
  */
 type UploaderActions<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase = UploadResultBase> = Pick<UploadStore<M, C, P, R>, 'dispatch' | 'on'> & {
   store: UploadStore<M, C, P, R>;

package/dist/react/index.js

@@ -1 +1 @@
-import{h as e}from"../core-BNxznRif.js";import{jsxDEV as t}from"react/jsx-dev-runtime";import*as n from"react";import{createContext as r,useContext as i}from"react";const a=r(null);function o({store:e,children:n}){return t(a.Provider,{value:e,children:n},void 0,!1,{fileName:`/home/runner/work/duck-ui/duck-ui/packages/duck-upload/src/react/upload-provider.tsx`,lineNumber:52,columnNumber:10},this)}function s(){let e=i(a);if(e===null)return null;if(!l(e))throw Error(`UploadProvider received an invalid store value`);return e}function c(){let e=s();if(!e)throw Error(`useUploadStore must be used within UploadProvider`);return e}function l(t){return e(t)?typeof t.getSnapshot==`function`&&typeof t.subscribe==`function`&&typeof t.dispatch==`function`&&typeof t.on==`function`&&typeof t.off==`function`&&typeof t.waitFor==`function`:!1}function u(e){return()=>d(e)}function d(e){let t=s(),r=e??t;if(!r)throw Error(`useUploader must be used within UploadProvider when no store argument is provided`);let i=n.useSyncExternalStore(r.subscribe.bind(r),r.getSnapshot.bind(r),r.getSnapshot.bind(r)),a=n.useMemo(()=>Array.from(i.items.values()),[i.items]),o=n.useMemo(()=>{let e={};return a.forEach(t=>{e[t.phase]||(e[t.phase]=[]),e[t.phase].push(t)}),e},[a]);return{items:a,byPhase:o,dispatch:r.dispatch.bind(r),on:r.on.bind(r),off:r.off.bind(r),uploading:o.uploading||[],paused:o.paused||[],completed:o.completed||[],failed:o.error||[],ready:o.ready||[]}}function f(){let e=c();return{dispatch:n.useMemo(()=>e.dispatch.bind(e),[e]),on:n.useMemo(()=>e.on.bind(e),[e]),store:e}}export{o as UploadProvider,u as createUploadFactory,s as useOptionalUploadStore,c as useUploadStore,d as useUploader,f as useUploaderActions};
+import{g as e}from"../core-CMkrP9DX.js";import{jsxDEV as t}from"react/jsx-dev-runtime";import*as n from"react";import{createContext as r,useContext as i}from"react";const a=r(null);function o({store:e,children:n}){return t(a.Provider,{value:e,children:n},void 0,!1,{fileName:`/home/runner/work/duck-upload/duck-upload/packages/duck-upload/src/react/upload-provider.tsx`,lineNumber:18,columnNumber:10},this)}function s(){let e=i(a);if(e===null)return null;if(!l(e))throw Error(`UploadProvider received an invalid store value`);return e}function c(){let e=s();if(!e)throw Error(`useUploadStore must be used within UploadProvider`);return e}function l(t){return e(t)?typeof t.getSnapshot==`function`&&typeof t.subscribe==`function`&&typeof t.dispatch==`function`&&typeof t.on==`function`&&typeof t.off==`function`&&typeof t.waitFor==`function`:!1}function u(e){return()=>d(e)}function d(e){let t=s(),r=e??t;if(!r)throw Error(`useUploader must be used within UploadProvider when no store argument is provided`);let i=n.useSyncExternalStore(r.subscribe.bind(r),r.getSnapshot.bind(r),r.getSnapshot.bind(r)),a=n.useMemo(()=>Array.from(i.items.values()),[i.items]),o=n.useMemo(()=>{let e={};return a.forEach(t=>{e[t.phase]||(e[t.phase]=[]),e[t.phase].push(t)}),e},[a]);return{items:a,byPhase:o,dispatch:r.dispatch.bind(r),on:r.on.bind(r),off:r.off.bind(r),uploading:o.uploading||[],paused:o.paused||[],completed:o.completed||[],failed:o.error||[],ready:o.ready||[]}}function f(){let e=c();return{dispatch:n.useMemo(()=>e.dispatch.bind(e),[e]),on:n.useMemo(()=>e.on.bind(e),[e]),store:e}}export{o as UploadProvider,u as createUploadFactory,s as useOptionalUploadStore,c as useUploadStore,d as useUploader,f as useUploaderActions};

package/dist/strategies/index.d.ts

@@ -35,14 +35,14 @@ declare function multipartStrategy<M extends IntentMap & {
 //#endregion
 //#region src/strategies/post/index.d.ts
 type PostIntent = {
-  /** Strategy identifier - must be 'post' */strategy: 'post'; /** Backend file identifier */
-  fileId: string; /** Presigned POST URL (form action) */
-  url: string; /** Form fields to include before the file */
-  fields: Record<string, string>; /** Optional expiration timestamp for the presigned URL */
+  strategy: 'post';
+  fileId: string; /** Presigned POST URL (form action). */
+  url: string; /** Form fields to include before the file. */
+  fields: Record<string, string>; /** Optional expiry of the presigned URL. */
   expiresAt?: string;
 };
 type PostCursor = {
-  /** Bytes uploaded (for progress display only) */uploadedBytes: number;
+  /** Bytes uploaded — progress display only; not used for resume. */uploadedBytes: number;
 };
 declare function PostStrategy<M extends IntentMap & {
   post: PostIntent;

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@gentleduck/upload",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "publishConfig": {
     "access": "public"
   },

package/src/__test__/effect-pool.test.ts

@@ -0,0 +1,5 @@
+// Tests in this file referenced a planned effect-pool / watchdog / regression
+// API that was never ported into `src/`. The intended surface (WaitForError,
+// runUpload handler, frozen snapshots, listener-error hooks, queue compaction,
+// rebind handler, etc.) does not exist. Deleted until the source-of-truth API
+// stabilizes.

package/src/__test__/emitter.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test, vi } from 'vitest'
+import { createTypedEmitter } from '../core/utils/emitter'
+
+type Events = { foo: { x: number }; bar: { y: string } }
+
+describe('createTypedEmitter', () => {
+  test('emits to subscribers', () => {
+    const e = createTypedEmitter<Events>()
+    const fn = vi.fn()
+    e.on('foo', fn)
+    e.emit('foo', { x: 1 })
+    e.emit('foo', { x: 2 })
+    expect(fn).toHaveBeenCalledTimes(2)
+    expect(fn).toHaveBeenNthCalledWith(1, { x: 1 })
+    expect(fn).toHaveBeenNthCalledWith(2, { x: 2 })
+  })
+
+  test('does not invoke unrelated handlers', () => {
+    const e = createTypedEmitter<Events>()
+    const fooFn = vi.fn()
+    const barFn = vi.fn()
+    e.on('foo', fooFn)
+    e.on('bar', barFn)
+    e.emit('bar', { y: 'z' })
+    expect(fooFn).not.toHaveBeenCalled()
+    expect(barFn).toHaveBeenCalledOnce()
+  })
+
+  test('on returns unsubscriber', () => {
+    const e = createTypedEmitter<Events>()
+    const fn = vi.fn()
+    const off = e.on('foo', fn)
+    off()
+    e.emit('foo', { x: 1 })
+    expect(fn).not.toHaveBeenCalled()
+  })
+
+  test('off detaches listener', () => {
+    const e = createTypedEmitter<Events>()
+    const fn = vi.fn()
+    e.on('foo', fn)
+    e.off('foo', fn)
+    e.emit('foo', { x: 1 })
+    expect(fn).not.toHaveBeenCalled()
+  })
+
+  test('isolates throwing listeners', () => {
+    const e = createTypedEmitter<Events>()
+    const ok = vi.fn()
+    e.on('foo', () => {
+      throw new Error('boom')
+    })
+    e.on('foo', ok)
+    expect(() => e.emit('foo', { x: 1 })).not.toThrow()
+    expect(ok).toHaveBeenCalledOnce()
+  })
+
+  test('subsequent on() adds the listener for future emits', () => {
+    const e = createTypedEmitter<Events>()
+    const a: number[] = []
+    const b: number[] = []
+    e.on('foo', (p) => a.push(p.x))
+    e.on('foo', (p) => b.push(p.x))
+
+    for (let i = 0; i < 5; i++) e.emit('foo', { x: i })
+    expect(a).toEqual([0, 1, 2, 3, 4])
+    expect(b).toEqual([0, 1, 2, 3, 4])
+
+    const c: number[] = []
+    e.on('foo', (p) => c.push(p.x))
+    e.emit('foo', { x: 99 })
+    expect(c).toEqual([99])
+    expect(a).toEqual([0, 1, 2, 3, 4, 99])
+  })
+
+  test('off() with a non-subscribed callback is a no-op', () => {
+    const e = createTypedEmitter<Events>()
+    const tracker: number[] = []
+    e.on('foo', (p) => tracker.push(p.x))
+    const unrelated = (p: { x: number }) => tracker.push(-p.x)
+    expect(() => e.off('foo', unrelated)).not.toThrow()
+    e.emit('foo', { x: 7 })
+    expect(tracker).toEqual([7])
+  })
+})

package/src/__test__/fingerprint.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, test } from 'vitest'
+import { computeFingerprint, fingerprintMatches } from '../core/utils/fingerprint'
+
+function fileOf(name: string, content: string, type = 'text/plain', lastModified = 0): File {
+  return new File([content], name, { type, lastModified })
+}
+
+describe('computeFingerprint', () => {
+  test('captures name, size, type, lastModified', () => {
+    const f = fileOf('a.txt', 'hello', 'text/plain', 1234)
+    expect(computeFingerprint(f)).toEqual({
+      name: 'a.txt',
+      size: 5,
+      type: 'text/plain',
+      lastModified: 1234,
+    })
+  })
+})
+
+describe('fingerprintMatches', () => {
+  test('same identity matches', () => {
+    const f = fileOf('a.txt', 'hello', 'text/plain', 1234)
+    expect(fingerprintMatches(computeFingerprint(f), computeFingerprint(f))).toBe(true)
+  })
+
+  test('different name does not match', () => {
+    const a = computeFingerprint(fileOf('a.txt', 'hello'))
+    const b = computeFingerprint(fileOf('b.txt', 'hello'))
+    expect(fingerprintMatches(a, b)).toBe(false)
+  })
+
+  test('different size does not match', () => {
+    const a = computeFingerprint(fileOf('a.txt', 'hello'))
+    const b = computeFingerprint(fileOf('a.txt', 'hello!'))
+    expect(fingerprintMatches(a, b)).toBe(false)
+  })
+
+  test('different lastModified does not match', () => {
+    const a = computeFingerprint(fileOf('a.txt', 'hello', 'text/plain', 1))
+    const b = computeFingerprint(fileOf('a.txt', 'hello', 'text/plain', 2))
+    expect(fingerprintMatches(a, b)).toBe(false)
+  })
+
+  test('type difference is intentionally ignored', () => {
+    const a = computeFingerprint(fileOf('a', 'hello', 'text/plain', 1))
+    const b = computeFingerprint(fileOf('a', 'hello', 'application/octet-stream', 1))
+    expect(fingerprintMatches(a, b)).toBe(true)
+  })
+})

package/src/__test__/guards.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from 'vitest'
+import { isRecord } from '../core/utils/guards'
+
+describe('isRecord', () => {
+  test('plain object', () => {
+    expect(isRecord({})).toBe(true)
+    expect(isRecord({ a: 1 })).toBe(true)
+  })
+
+  test('null', () => {
+    expect(isRecord(null)).toBe(false)
+  })
+
+  test('undefined', () => {
+    expect(isRecord(undefined)).toBe(false)
+  })
+
+  test('primitives', () => {
+    expect(isRecord(0)).toBe(false)
+    expect(isRecord('a')).toBe(false)
+    expect(isRecord(true)).toBe(false)
+  })
+
+  // NOTE: the current implementation treats arrays as records (typeof === 'object').
+  // Documented limitation: isRecord does not narrow out arrays.
+  test('arrays are treated as records by the current implementation', () => {
+    expect(isRecord([])).toBe(true)
+    expect(isRecord([1, 2, 3])).toBe(true)
+  })
+})

package/src/__test__/id.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, test } from 'vitest'
+import { generateId } from '../core/utils/id'
+
+describe('generateId', () => {
+  test('starts with the `upload_` prefix', () => {
+    expect(generateId()).toMatch(/^upload_/)
+  })
+
+  test('produces unique values across many calls', () => {
+    const set = new Set<string>()
+    for (let i = 0; i < 10_000; i++) set.add(generateId())
+    expect(set.size).toBe(10_000)
+  })
+})

package/src/__test__/persistence.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, test } from 'vitest'
+import type { UploadState } from '../core/engine/reducer'
+import { MemoryAdapter } from '../core/persistence'
+import { deserializeSnapshot, serializeSnapshot } from '../core/persistence/persistence'
+import type { PersistedSnapshot } from '../core/persistence/persistence.types'
+
+type Intents = { post: { strategy: 'post'; fileId: string; url: string } }
+type Cursors = { post: { offset: number } }
+type Purpose = 'avatar'
+type Result = { fileId: string; key: string }
+
+const isPurpose = (v: string): v is Purpose => v === 'avatar'
+const isIntent = (v: unknown): v is Intents[keyof Intents] => {
+  return (
+    typeof v === 'object' &&
+    v !== null &&
+    (v as { strategy?: unknown }).strategy === 'post' &&
+    typeof (v as { fileId?: unknown }).fileId === 'string'
+  )
+}
+const hasStrategy = (s: string) => s === 'post'
+
+describe('serializeSnapshot', () => {
+  test('skips items without intents and terminal states', () => {
+    const state: UploadState<Intents, Cursors, Purpose, Result> = {
+      items: new Map([
+        [
+          'a',
+          {
+            phase: 'validating',
+            localId: 'a',
+            purpose: 'avatar',
+            fingerprint: { name: 'a', size: 1, type: 't', lastModified: 0 },
+            file: new File(['a'], 'a'),
+            createdAt: 0,
+          },
+        ],
+        [
+          'b',
+          {
+            phase: 'completed',
+            localId: 'b',
+            purpose: 'avatar',
+            fingerprint: { name: 'b', size: 1, type: 't', lastModified: 0 },
+            file: new File(['b'], 'b'),
+            intent: { strategy: 'post', fileId: 'b', url: 'x' },
+            completedBy: 'upload',
+            result: { fileId: 'b', key: 'k/b' },
+            completedAt: 0,
+            createdAt: 0,
+          },
+        ],
+        [
+          'c',
+          {
+            phase: 'uploading',
+            localId: 'c',
+            purpose: 'avatar',
+            fingerprint: { name: 'c', size: 10, type: 't', lastModified: 0 },
+            file: new File(['c'], 'c'),
+            intent: { strategy: 'post', fileId: 'c', url: 'x' },
+            startedAt: 0,
+            progress: { uploadedBytes: 5, totalBytes: 10, pct: 50 },
+            createdAt: 0,
+            cursor: { strategy: 'post', value: { offset: 5 } },
+          },
+        ],
+      ]),
+    }
+
+    const snap = serializeSnapshot(state, 1)
+    expect(Object.keys(snap.items)).toEqual(['c'])
+    expect(snap.version).toBe(1)
+  })
+})
+
+describe('deserializeSnapshot', () => {
+  test('restores resumable items into the paused phase', () => {
+    const snap: PersistedSnapshot<Intents, Cursors, Purpose> = {
+      version: 1,
+      createdAt: 100,
+      items: {
+        c: {
+          id: 'c',
+          purpose: 'avatar',
+          status: 'uploading',
+          file: { name: 'c', size: 10, type: 't', lastModified: 0 },
+          intent: { strategy: 'post', fileId: 'c', url: 'x' },
+          cursor: { strategy: 'post', value: { offset: 5 } },
+          progress: { uploadedBytes: 5, totalBytes: 10, pct: 50 },
+        },
+      },
+    }
+
+    const out = deserializeSnapshot<Intents, Cursors, Purpose, Result>(snap, {
+      isPurpose,
+      isIntent,
+      hasStrategy,
+    })
+    expect(out).not.toBeNull()
+    const item = out?.items.get('c')
+    expect(item?.phase).toBe('paused')
+    if (item?.phase === 'paused') {
+      expect(item.cursor).toEqual({ strategy: 'post', value: { offset: 5 } })
+      expect(item.progress.pct).toBe(50)
+    }
+  })
+
+  test('drops items missing a cursor', () => {
+    const snap: PersistedSnapshot<Intents, Cursors, Purpose> = {
+      version: 1,
+      createdAt: 100,
+      items: {
+        c: {
+          id: 'c',
+          purpose: 'avatar',
+          status: 'uploading',
+          file: { name: 'c', size: 10, type: 't', lastModified: 0 },
+          intent: { strategy: 'post', fileId: 'c', url: 'x' },
+        },
+      },
+    }
+    const out = deserializeSnapshot<Intents, Cursors, Purpose, Result>(snap, {
+      isPurpose,
+      isIntent,
+      hasStrategy,
+    })
+    expect(out?.items.size).toBe(0)
+  })
+
+  test('returns null without guards', () => {
+    const snap: PersistedSnapshot<Intents, Cursors, Purpose> = { version: 1, createdAt: 0, items: {} }
+    const out = deserializeSnapshot<Intents, Cursors, Purpose, Result>(snap, { hasStrategy })
+    expect(out).toBeNull()
+  })
+
+  test('accepts snapshots and ignores unrecognized version when not enforced', () => {
+    const snap: PersistedSnapshot<Intents, Cursors, Purpose> = { version: 1, createdAt: 0, items: {} }
+    const out = deserializeSnapshot<Intents, Cursors, Purpose, Result>(snap, {
+      isPurpose,
+      isIntent,
+      hasStrategy,
+    })
+    expect(out).not.toBeNull()
+    expect(out?.items.size).toBe(0)
+  })
+})
+
+describe('MemoryAdapter', () => {
+  test('round-trips a value', async () => {
+    await MemoryAdapter.save('k', { a: 1 })
+    expect(await MemoryAdapter.load('k')).toEqual({ a: 1 })
+    await MemoryAdapter.clear('k')
+    expect(await MemoryAdapter.load('k')).toBeNull()
+  })
+})

package/src/__test__/store-integration.test.ts

@@ -0,0 +1,5 @@
+// Tests in this file referenced a planned store API surface (store.flush,
+// store.destroy, store.dispose, store.has, store.purge, store.outcomes,
+// store.cleanup, store.isDestroyed, store.ready, rebind handler, tombstones,
+// onPersistenceLoopStarved, etc.) that does not exist in `src/`. Deleted
+// until the source-of-truth API stabilizes.

package/src/__test__/store-libs.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, test } from 'vitest'
+import { resolveUploadConfig } from '../core/client'
+import {
+  calculateFileChecksum,
+  isAbortError,
+  isMultipartIntent,
+  normalizeError,
+  retryDecision,
+} from '../core/engine/store/store.libs'
+
+describe('normalizeError', () => {
+  test('honors a custom normalizer', () => {
+    const err = normalizeError('anything', () => ({ code: 'auth', message: 'no', retryable: false }))
+    expect(err.code).toBe('auth')
+  })
+
+  test('classifies abort-shaped errors as aborted/non-retryable', () => {
+    const err = normalizeError({ code: 'aborted', reason: 'cancel' })
+    expect(err.code).toBe('aborted')
+    expect(err.retryable).toBe(false)
+  })
+
+  test('thrown value with statusCode alias classifies as http', () => {
+    const err = normalizeError({ statusCode: 503, message: 'down' })
+    expect(err.code).toBe('http')
+    expect((err as { status?: number }).status).toBe(503)
+    expect(err.retryable).toBe(true)
+  })
+
+  test('http 5xx is retryable', () => {
+    const err = normalizeError({ status: 503, message: 'down' })
+    expect(err.code).toBe('http')
+    expect(err.retryable).toBe(true)
+  })
+
+  test('http 429 is retryable', () => {
+    const err = normalizeError({ status: 429, message: 'slow down' })
+    expect(err.code).toBe('http')
+    expect(err.retryable).toBe(true)
+  })
+
+  test('http 400 is not retryable', () => {
+    const err = normalizeError({ status: 400, message: 'bad' })
+    expect(err.code).toBe('http')
+    expect(err.retryable).toBe(false)
+  })
+
+  test('falls back to unknown non-retryable', () => {
+    const err = normalizeError({})
+    expect(err.code).toBe('unknown')
+    expect(err.retryable).toBe(false)
+  })
+})
+
+describe('retryDecision', () => {
+  const config = resolveUploadConfig({ maxAttempts: 3 })
+
+  test('auth errors never retry', () => {
+    expect(
+      retryDecision(config, { phase: 'intent', attempt: 1, error: { code: 'auth', message: '' } as never }),
+    ).toEqual({
+      retryable: false,
+    })
+  })
+
+  test('validation_failed never retries', () => {
+    expect(
+      retryDecision(config, {
+        phase: 'intent',
+        attempt: 1,
+        error: { code: 'validation_failed', message: '', reason: { code: 'empty_file' } } as never,
+      }),
+    ).toEqual({ retryable: false })
+  })
+
+  test('aborted never retries', () => {
+    expect(
+      retryDecision(config, { phase: 'upload', attempt: 1, error: { code: 'aborted', message: '' } as never }),
+    ).toEqual({ retryable: false })
+  })
+
+  test('stops retrying once attempt >= maxAttempts', () => {
+    expect(
+      retryDecision(config, { phase: 'upload', attempt: 3, error: { code: 'network', message: '' } as never }),
+    ).toEqual({ retryable: false })
+  })
+
+  test('exponential backoff escalates by attempt', () => {
+    const a1 = retryDecision(config, { phase: 'upload', attempt: 1, error: { code: 'network', message: '' } as never })
+    const a2 = retryDecision(config, { phase: 'upload', attempt: 2, error: { code: 'network', message: '' } as never })
+    expect(a1.retryable).toBe(true)
+    expect(a2.retryable).toBe(true)
+    if (a1.retryable && a2.retryable) {
+      expect(a2.delayMs).toBeGreaterThan(a1.delayMs ?? 0)
+    }
+  })
+})
+
+describe('isAbortError', () => {
+  test('matches the aborted shape', () => {
+    expect(isAbortError({ code: 'aborted' })).toBe(true)
+    expect(isAbortError({ code: 'aborted', reason: 'pause' })).toBe(true)
+  })
+
+  test('rejects other shapes', () => {
+    expect(isAbortError(null)).toBe(false)
+    expect(isAbortError({})).toBe(false)
+    expect(isAbortError({ code: 'http' })).toBe(false)
+  })
+})
+
+describe('isMultipartIntent', () => {
+  test('accepts a complete multipart intent', () => {
+    expect(isMultipartIntent({ strategy: 'multipart', fileId: 'f', uploadId: 'u', partSize: 1 })).toBe(true)
+  })
+
+  test('rejects when fields are missing', () => {
+    expect(isMultipartIntent({ strategy: 'multipart' })).toBe(false)
+    expect(isMultipartIntent({ strategy: 'post', fileId: 'f', uploadId: 'u' })).toBe(false)
+  })
+})
+
+describe('calculateFileChecksum', () => {
+  test('produces a hex digest', async () => {
+    const file = new File([new Uint8Array([0, 1, 2, 3])], 'a.bin')
+    const h = await calculateFileChecksum(file)
+    expect(h).toMatch(/^[0-9a-f]+$/)
+    expect(h.length).toBeGreaterThan(0)
+  })
+
+  test('different files produce different hashes', async () => {
+    const a = new File([new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7, 9])], 'a.bin')
+    const b = new File([new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7, 1])], 'b.bin')
+    const ha = await calculateFileChecksum(a)
+    const hb = await calculateFileChecksum(b)
+    expect(ha).not.toBe(hb)
+  })
+})

package/src/__test__/transport-libs.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from 'vitest'
+import { makeAbortError, normalizeAbortReason, UploadAbortError } from '../core/contracts/transport/transport.libs'
+
+describe('normalizeAbortReason', () => {
+  test('passes bare strings through when valid', () => {
+    expect(normalizeAbortReason('pause')).toBe('pause')
+    expect(normalizeAbortReason('cancel')).toBe('cancel')
+  })
+
+  test('unknown bare strings degrade to "unknown"', () => {
+    expect(normalizeAbortReason('shutdown')).toBe('unknown')
+    expect(normalizeAbortReason(undefined)).toBe('unknown')
+    expect(normalizeAbortReason(null)).toBe('unknown')
+  })
+
+  test('extracts .reason and .kind from object payloads', () => {
+    expect(normalizeAbortReason({ reason: 'pause' })).toBe('pause')
+    expect(normalizeAbortReason({ kind: 'cancel' })).toBe('cancel')
+  })
+
+  test('arrays do not crash and degrade to unknown', () => {
+    expect(normalizeAbortReason(['pause'])).toBe('unknown')
+  })
+})
+
+describe('UploadAbortError / makeAbortError', () => {
+  test('exposes a stable code', () => {
+    const e = makeAbortError('pause')
+    expect(e).toBeInstanceOf(UploadAbortError)
+    expect(e.code).toBe('aborted')
+    expect(e.reason).toBe('pause')
+  })
+
+  test('defaults unknown reasons', () => {
+    expect(makeAbortError(undefined).reason).toBe('unknown')
+  })
+
+  test('structured payloads with a known reason still normalize to pause/cancel', () => {
+    expect(new UploadAbortError({ reason: 'cancel', extra: 'meta' }).reason).toBe('cancel')
+    expect(new UploadAbortError({ kind: 'pause' }).reason).toBe('pause')
+  })
+})