@gentleduck/upload 0.2.5 → 0.3.0

package/src/core/engine/store/store.libs.ts

@@ -1,159 +1,263 @@
-import type { UploadConfig } from '../../client'
-import type { AnyCursor, CursorMap, IntentMap, UploadError, UploadResultBase } from '../../contracts'
+import type { Contracts } from '../../contracts'
+import type { UploadError } from '../../errors'
 import { DEFAULT_RETRY_DELAY_BASE_MS, DEFAULT_RETRY_DELAY_MAX_MS } from '../../utils/constants'
 import { computeFingerprint, fingerprintMatches } from '../../utils/fingerprint'
-import { isRecord } from '../../utils/guards'
-import type { UploadItem } from '../internal-events.types'
+import { isDevEnv, isRecord } from '../../utils/guards'
+import { hashBlob } from '../../utils/hash'
+import type { Engine } from '../engine.types'
+import type { Store } from './store.types'
 
 export { sleep } from '../../utils/async'
 
-import type { StoreOptions } from './store.types'
+/** Build enriched API context from a live item for passing to any backend API method. */
+export function buildApiContext<
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
+  P extends string,
+  R extends Contracts.Result.Base,
+>(item: Engine.Item<M, C, P, R>, overrides: Partial<Contracts.Api.Context<P, M>> = {}): Contracts.Api.Context<P, M> {
+  const lastErrorStep = [...item.steps].reverse().find((s) => s.error !== undefined)
+  return {
+    localId: item.localId,
+    purpose: item.purpose,
+    fingerprint: item.fingerprint,
+    attempt: item.attempt ?? 1,
+    createdAt: item.createdAt,
+    steps: item.steps,
+    meta: item.meta,
+    lastError: lastErrorStep?.error,
+    file: 'file' in item ? item.file : undefined,
+    intent: 'intent' in item ? (item as { intent?: Contracts.Intent.Any<M> }).intent : undefined,
+    ...overrides,
+  }
+}
 
 /**
- * Calculates SHA256 checksum of a file for deduplication.
- * Uses Web Crypto API for efficient hashing.
+ * Default boundary between inline and incremental hashing when
+ * `config.checksumMaxSize` is unset (`null`) or `0`: 64 MiB.
  */
-export async function calculateFileChecksum(file: File): Promise<string> {
-  const buffer = await file.arrayBuffer()
-  const hashBuffer = await crypto.subtle.digest('SHA-256', buffer)
-  const hashArray = Array.from(new Uint8Array(hashBuffer))
-  return hashArray.map((b) => b.toString(16).padStart(2, '0')).join('')
-}
+export const DEFAULT_CHECKSUM_MAX_SIZE = 64 * 1024 * 1024
 
 /**
- * Determines whether items for a given purpose should auto-start.
+ * SHA-256 checksum of `file` for deduplication.
+ *
+ * `maxSize` is the inline/incremental boundary, not a skip: files at or below
+ * it are hashed with native Web Crypto (fastest), while larger files are hashed
+ * incrementally in bounded slices — off the main thread via a Web Worker when
+ * available, otherwise inline-incremental. Memory stays flat either way, so
+ * dedupe now covers files of any size.
  *
- * Supports three configuration shapes:
- * - `false | undefined`: never auto-start
- * - `P[]`: auto-start for purposes included in the list
- * - `(purpose: P) => boolean`: custom predicate
+ * Pass `maxSize = 0` or omit it to use {@link DEFAULT_CHECKSUM_MAX_SIZE}.
+ *
+ * @returns lowercase hex SHA-256 digest.
  */
-export function isAutoStart<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase>(
-  opts: StoreOptions<M, C, P, R>,
-  purpose: P,
-): boolean {
+export async function calculateFileChecksum(file: File, maxSize: number | null = null): Promise<string> {
+  // Use the caller-supplied boundary only when it's a finite positive number.
+  // NaN / Infinity / 0 / negative all fall back to the conservative default.
+  const inlineMaxSize =
+    typeof maxSize === 'number' && Number.isFinite(maxSize) && maxSize > 0 ? maxSize : DEFAULT_CHECKSUM_MAX_SIZE
+  return hashBlob(file, { inlineMaxSize })
+}
+
+/**
+ * Resolve auto-start config: `false | undefined` (never), `P[]` (in list), or
+ * `(purpose) => boolean` predicate.
+ */
+export function isAutoStart<
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
+  P extends string,
+  R extends Contracts.Result.Base,
+>(opts: Store.Options<M, C, P, R>, purpose: P): boolean {
   const v = opts.config?.autoStart
   if (v === undefined) return false
   if (Array.isArray(v)) return v.includes(purpose)
-  if (typeof v === 'function') return v(purpose)
+  if (typeof v === 'function') {
+    // Fail-closed if the user-supplied predicate throws so a buggy
+    // predicate can't stop the entire addFiles flow.
+    try {
+      return v(purpose) === true
+    } catch {
+      return false
+    }
+  }
   return false
 }
 
 /**
- * Builds a lightweight fingerprint from a {@link File}.
- *
- * This fingerprint is used for display and basic identity. If you need stronger identity
- * (e.g. SHA-256), provide a custom {@link StoreOptions.fingerprint} function or let the
- * add-file handler compute a checksum asynchronously.
+ * Lightweight `File` fingerprint for display/identity. For stronger identity
+ * (SHA-256), pass {@link StoreOptions.fingerprint} or let add-file compute a
+ * checksum asynchronously.
  */
 export { computeFingerprint, fingerprintMatches }
 
 /**
- * Normalizes unknown thrown values into the engine's {@link UploadError} shape.
- *
- * You can provide a custom normalizer through {@link StoreOptions.errorNormalizer}.
- * Built-in behavior:
- * - detects abort errors and marks them non-retryable
- * - classifies common network and HTTP errors as retryable where appropriate
+ * When `findByChecksum` matches, complete the item without creating an intent or
+ * uploading bytes. Returns `true` when dedupe succeeded.
  */
-export function normalizeError(err: unknown, customNormalizer?: (err: unknown) => UploadError): UploadError {
+export async function tryDedupeByChecksum<
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
+  P extends string,
+  R extends Contracts.Result.Base,
+>(
+  rt: Store.Runtime<M, C, P, R>,
+  localId: string,
+  checksum: string | undefined,
+  purpose: P,
+  allowedPhases: ReadonlyArray<Engine.Phase>,
+): Promise<boolean> {
+  if (!checksum || !rt.opts.api.findByChecksum) return false
+
+  const item = rt.state.items.get(localId)
+  if (!item || !allowedPhases.includes(item.phase) || !item.file) return false
+
+  try {
+    const existingFile = await rt.opts.api.findByChecksum({ checksum, purpose }, {
+      ...buildApiContext(item),
+      file: item.file,
+    } as Contracts.Api.FindByChecksumContext<P, M>)
+    if (!existingFile) return false
+
+    const current = rt.state.items.get(localId)
+    if (!current || !allowedPhases.includes(current.phase)) return false
+
+    rt.applyInternal({ type: 'dedupe.ok', localId, result: existingFile })
+    return true
+  } catch (err) {
+    if (isDevEnv()) {
+      console.warn('[UploadEngine] Failed to check for existing file:', err)
+    }
+    return false
+  }
+}
+
+/**
+ * Detects when `createIntent` returned an existing file result instead of an
+ * upload intent (e.g. backend matched checksum during plan-upload).
+ */
+export function parseCreateIntentDedupeResult<R extends Contracts.Result.Base>(response: unknown): R | null {
+  if (!isRecord(response)) return null
+
+  const strategy = response['strategy']
+  const markedDedupe =
+    response['dedupe'] === true ||
+    response['existing'] === true ||
+    response['skipUpload'] === true ||
+    strategy === 'dedupe'
+
+  if (!markedDedupe) return null
+
+  const fileId =
+    typeof response['fileId'] === 'string'
+      ? response['fileId']
+      : typeof response['id'] === 'string'
+        ? response['id']
+        : null
+  const key = typeof response['key'] === 'string' ? response['key'] : null
+  if (!fileId || !key) return null
+
+  return { fileId, key } as R
+}
+
+import {
+  UploadAbortError,
+  UploadEngineError,
+  UploadHttpError,
+  UploadNetworkError,
+  UploadUnknownError,
+} from '../../errors'
+
+/**
+ * Normalize a thrown value into an {@link Contracts.Errors.Error}. Override via
+ * {@link StoreOptions.errorNormalizer}. Default: aborts → non-retryable;
+ * network errors → retryable; HTTP 5xx/429 → retryable.
+ */
+export function normalizeError(err: unknown, customNormalizer?: (err: unknown) => Contracts.Errors.Error): UploadError {
   if (customNormalizer) return customNormalizer(err)
 
-  // Transport abort errors can carry {code:'aborted', reason:'pause'|'cancel'}
+  if (err instanceof UploadEngineError) {
+    return err
+  }
+
+  // Transport aborts carry `{ code: 'aborted', reason: 'pause' | 'cancel' }`.
   if (isAbortError(err)) {
-    return { code: 'aborted', message: 'Upload aborted', reason: String(err.reason ?? 'unknown'), retryable: false }
+    const reason = err.reason === 'pause' || err.reason === 'cancel' ? err.reason : 'unknown'
+    return new UploadAbortError(reason, undefined, { cause: err })
   }
 
-  const msg = isRecord(err) && typeof err.message === 'string' ? err.message : 'Unknown error'
+  const msg = isRecord(err) && typeof err['message'] === 'string' ? (err['message'] as string) : 'Unknown error'
 
-  // Network errors
-  if (String(msg).toLowerCase().includes('network') || String(msg).toLowerCase().includes('fetch')) {
-    return { code: 'network', message: String(msg), cause: err, retryable: true }
+  if (msg.toLowerCase().includes('network') || msg.toLowerCase().includes('fetch')) {
+    return new UploadNetworkError(msg, { cause: err })
   }
 
-  // HTTP errors
-  if (isRecord(err) && (typeof err.status === 'number' || typeof err.statusCode === 'number')) {
-    const status = (typeof err.status === 'number' ? err.status : err.statusCode) as number
-    const retryable = status >= 500 || status === 429
-    return { code: 'http', status, message: String(msg), cause: err, retryable }
+  if (isRecord(err) && (typeof err['status'] === 'number' || typeof err['statusCode'] === 'number')) {
+    const status = (typeof err['status'] === 'number' ? err['status'] : err['statusCode']) as number
+    const statusText = typeof err['statusText'] === 'string' ? err['statusText'] : undefined
+    return new UploadHttpError(status, msg, { cause: err, statusText })
   }
 
-  return { code: 'unknown', message: String(msg), cause: err, retryable: false }
+  return new UploadUnknownError(msg, { cause: err })
 }
 
-/**
- * Type guard for items that currently hold a concrete backend intent.
- */
-export function hasIntent<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase>(
-  item: UploadItem<M, C, P, R>,
-): item is Extract<UploadItem<M, C, P, R>, { intent: M[keyof M] }> {
+/** Item has a concrete backend intent. */
+export function hasIntent<
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
+  P extends string,
+  R extends Contracts.Result.Base,
+>(item: Engine.Item<M, C, P, R>): item is Extract<Engine.Item<M, C, P, R>, { intent: M[keyof M] }> {
   return 'intent' in item && !!item.intent
 }
 
-/**
- * Type guard for items that currently have a bound {@link File}.
- *
- * Persisted items restored from storage may lack `file` until the UI re-binds it.
- */
-export function hasFile<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase>(
-  item: UploadItem<M, C, P, R>,
-): item is Extract<UploadItem<M, C, P, R>, { file: File }> {
+/** Item has a bound `File`. Persisted items may lack it until the UI re-binds. */
+export function hasFile<
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
+  P extends string,
+  R extends Contracts.Result.Base,
+>(item: Engine.Item<M, C, P, R>): item is Extract<Engine.Item<M, C, P, R>, { file: File }> {
   return 'file' in item && !!item.file
 }
 
-/**
- * Type guard that narrows to item variants carrying a cursor field.
- *
- * Cursor presence depends on the current phase and the strategy.
- */
-export function hasCursor<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase>(
-  item: UploadItem<M, C, P, R>,
-): item is Extract<UploadItem<M, C, P, R>, { cursor?: AnyCursor<C> }> {
+/** Item variant carries a cursor field (depends on phase/strategy). */
+export function hasCursor<
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
+  P extends string,
+  R extends Contracts.Result.Base,
+>(item: Engine.Item<M, C, P, R>): item is Extract<Engine.Item<M, C, P, R>, { cursor?: Contracts.Cursor.Any<C> }> {
   return 'cursor' in item
 }
 
-/**
- * Runtime guard for multipart intent objects.
- *
- * Used for best-effort abort calls when canceling multipart uploads.
- */
+/** Best-effort guard used to issue multipart-abort calls on cancel. */
 export function isMultipartIntent(
   intent: unknown,
 ): intent is { strategy: 'multipart'; fileId: string; uploadId: string; partSize: number } {
   return (
     isRecord(intent) &&
-    intent.strategy === 'multipart' &&
-    typeof intent.fileId === 'string' &&
-    typeof intent.uploadId === 'string'
+    intent['strategy'] === 'multipart' &&
+    typeof intent['fileId'] === 'string' &&
+    typeof intent['uploadId'] === 'string'
   )
 }
 
-/**
- * Runtime guard for abort errors produced by the transport/strategy layer.
- */
 export function isAbortError(err: unknown): err is { code: 'aborted'; reason?: unknown } {
-  return isRecord(err) && err.code === 'aborted'
+  return isRecord(err) && err['code'] === 'aborted'
 }
 
 /**
- * Small helper to narrow unknown values to objects.
- */
-
-/**
- * Computes whether a failed operation should be retried and, if so, after what delay.
- *
- * If {@link UploadConfig.retryPolicy} is provided it is used as the source of truth.
- * Otherwise the default policy:
- * - never retries auth/validation/strategy_missing/aborted
- * - retries up to `maxAttempts` with exponential backoff and a fixed cap
+ * Decide whether to retry. Defers to `config.retryPolicy` when set.
+ * Default: never retries `auth`/`validation_failed`/`strategy_missing`/`aborted`;
+ * otherwise exponential backoff up to `maxAttempts`, capped at `DEFAULT_RETRY_DELAY_MAX_MS`.
  */
 export function retryDecision<P extends string>(
-  config: UploadConfig<P>,
+  config: Engine.Config<P>,
   ctx: { phase: 'intent' | 'upload' | 'complete'; attempt: number; error: UploadError },
 ) {
   if (config.retryPolicy) return config.retryPolicy(ctx)
 
-  // Default: retry network/server unknown errors, not auth/validation/strategy_missing
   if (ctx.error.code === 'auth') return { retryable: false }
   if (ctx.error.code === 'validation_failed') return { retryable: false }
   if (ctx.error.code === 'strategy_missing') return { retryable: false }
@@ -163,7 +267,6 @@ export function retryDecision<P extends string>(
   const retryable = ctx.attempt < maxAttempts
   if (!retryable) return { retryable: false }
 
-  // Exponential backoff with cap
   const delayMs = Math.min(DEFAULT_RETRY_DELAY_MAX_MS, DEFAULT_RETRY_DELAY_BASE_MS * 2 ** (ctx.attempt - 1))
   return { retryable: true, delayMs }
 }

package/src/core/engine/store/store.runtime.ts

@@ -1,41 +1,31 @@
-import { resolveUploadConfig } from '../../client'
-import type { CursorMap, IntentMap, UploadResultBase } from '../../contracts'
+import type { Contracts } from '../../contracts'
 import { createXHRTransport } from '../../contracts/transport'
 import { deserializeSnapshot, serializeSnapshot } from '../../persistence'
 import { createTypedEmitter } from '../../utils/emitter'
-import type { UploadCommand } from '../commands.types'
-import type { UploadEventMap } from '../event-map.types'
-import type { InternalEvent, UploadItem } from '../internal-events.types'
-import { createReducer, type UploadState } from '../reducer'
+import { isDevEnv } from '../../utils/guards'
+import { resolveUploadConfig } from '../engine.libs'
+import type { Engine } from '../engine.types'
+import { createReducer } from '../reducer'
 import { cleanupOldItems } from './handlers/clean-up'
 import { scheduleWork } from './store.schedule'
-import type { InflightUpload, StoreOptions, StoreRuntime } from './store.types'
+import type { Store } from './store.types'
 
 /**
- * Creates a new runtime instance with initial state, emitter, reducer, and effect queue.
- *
- * Notes:
- * - Reducers remain pure: all async work is enqueued through {@link StoreRuntime.enqueueEffect}.
- * - {@link StoreRuntime.applyInternal} invokes hooks, performs cleanup, and then schedules more work.
- * - {@link StoreRuntime.dispatch} is intentionally assigned later to break import cycles.
- *
- * @template M - Intent map type
- * @template C - Cursor map type
- * @template P - Purpose string union type
- *
- * @param opts - Construction options for the store.
+ * Build the store runtime: state, emitter, reducer, and effect queue.
+ * Reducers stay pure  async work goes through {@link StoreRuntime.enqueueEffect}.
+ * `dispatch` is assigned later by `createUploadStore` to break an import cycle.
  */
 export function createStoreRuntime<
-  M extends IntentMap,
-  C extends CursorMap<M>,
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
   P extends string,
-  R extends UploadResultBase = UploadResultBase,
->(opts: StoreOptions<M, C, P, R>): StoreRuntime<M, C, P, R> {
+  R extends Contracts.Result.Base = Contracts.Result.Base,
+>(opts: Store.Options<M, C, P, R>): Store.Runtime<M, C, P, R> {
   const resolvedOpts = resolveStoreOptions(opts)
   const persistence = resolvedOpts.persistence
 
-  // Debounced persistence flush. Persistence writes a single namespace `key`,
-  // and the adapter can choose how to store multiple item records under it.
+  // Debounced flush. Persistence writes under a single namespace `key`; the
+  // adapter decides how to encode multiple item records under that key.
   let persistTimer: ReturnType<typeof setTimeout> | null = null
   const persistDebounceMs = Math.max(0, persistence?.debounceMs ?? 200)
 
@@ -44,7 +34,7 @@ export function createStoreRuntime<
     try {
       const snap = (persistence.serialize ?? serializeSnapshot)(rt.state, persistence.version)
 
-      // If there's nothing to persist, clear the namespace to keep storage clean.
+      // Nothing to persist → clear the namespace.
       if (!snap.items || Object.keys(snap.items).length === 0) {
         await persistence.adapter.clear(persistence.key)
         return
@@ -52,7 +42,7 @@ export function createStoreRuntime<
 
       await persistence.adapter.save(persistence.key, snap)
     } catch (err) {
-      if (typeof window !== 'undefined' && process.env.NODE_ENV === 'development') {
+      if (isDevEnv()) {
         console.warn('[UploadEngine] persistence flush failed:', err)
       }
     }
@@ -68,21 +58,21 @@ export function createStoreRuntime<
     persistTimer = setTimeout(() => void flushPersistence(), persistDebounceMs)
   }
 
-  const initialState: UploadState<M, C, P, R> = resolvedOpts.initialState ?? {
-    items: new Map<string, UploadItem<M, C, P, R>>(),
+  const initialState: Engine.State<M, C, P, R> = resolvedOpts.initialState ?? {
+    items: new Map<string, Engine.Item<M, C, P, R>>(),
   }
 
   const effectQueue: Array<() => Promise<void>> = []
 
-  const rt: StoreRuntime<M, C, P, R> = {
+  const rt: Store.Runtime<M, C, P, R> = {
     opts: resolvedOpts,
     state: initialState,
 
     listeners: new Set<() => void>(),
-    emitter: createTypedEmitter<UploadEventMap<M, C, P, R>>(),
+    emitter: createTypedEmitter<Engine.EventMap<M, C, P, R>>(),
     reduce: createReducer<M, C, P, R>(),
 
-    inflightUploads: new Map<string, InflightUpload>(),
+    inflightUploads: new Map<string, Store.InflightUpload>(),
     inflightIntents: new Map<string, AbortController>(),
     inflightCompletes: new Map<string, AbortController>(),
 
@@ -100,7 +90,7 @@ export function createStoreRuntime<
       scheduleWork(rt)
     },
 
-    applyInternal(event: InternalEvent<M, C, P, R>) {
+    applyInternal(event: Engine.Event<M, C, P, R>) {
       const prev = rt.state
       const next = rt.reduce(prev, event)
       rt.state = next
@@ -116,7 +106,7 @@ export function createStoreRuntime<
       rt.scheduleWork()
     },
 
-    applyCommand(cmd: UploadCommand<P>) {
+    applyCommand(cmd: Engine.Command<P>) {
       const prev = rt.state
       const next = rt.reduce(prev, cmd)
       rt.state = next
@@ -144,7 +134,7 @@ export function createStoreRuntime<
         try {
           await effect()
         } catch (err) {
-          if (typeof window !== 'undefined' && process.env.NODE_ENV === 'development') {
+          if (isDevEnv()) {
             const error = err instanceof Error ? err : new Error(String(err))
             const context = {
               queueLength: rt.effectQueue.length,
@@ -158,14 +148,15 @@ export function createStoreRuntime<
       rt.processingEffects = false
     },
 
-    // replaced by createUploadStore
+    // Replaced by createUploadStore  runtime breaks the cycle.
     dispatch: () => {
       throw new Error('[UploadEngine] dispatch not initialized')
     },
-  } satisfies StoreRuntime<M, C, P, R>
+  } satisfies Store.Runtime<M, C, P, R>
 
-  // Hydrate from persistence when no initialState was provided.
-  // For async adapters (IndexedDB), this happens after construction.
+  // Async adapters (IndexedDB) resolve after construction; only hydrate when no
+  // initialState was provided. Merge into an empty store only  never clobber
+  // user actions that arrived before the load resolved.
   if (persistence && !resolvedOpts.initialState && typeof window !== 'undefined') {
     try {
       const loaded = persistence.adapter.load(persistence.key)
@@ -178,8 +169,6 @@ export function createStoreRuntime<
         })
         if (!next) return
 
-        // Only merge into an empty store to avoid clobbering user actions
-        // that happened before the async load completed.
         if (rt.state.items.size === 0) {
           rt.state = next
         } else {
@@ -205,9 +194,12 @@ export function createStoreRuntime<
   return rt
 }
 
-function resolveStoreOptions<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase>(
-  opts: StoreOptions<M, C, P, R>,
-): StoreRuntime<M, C, P, R>['opts'] {
+function resolveStoreOptions<
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
+  P extends string,
+  R extends Contracts.Result.Base,
+>(opts: Store.Options<M, C, P, R>): Store.Runtime<M, C, P, R>['opts'] {
   return {
     ...opts,
     config: resolveUploadConfig(opts.config),
@@ -215,10 +207,12 @@ function resolveStoreOptions<M extends IntentMap, C extends CursorMap<M>, P exte
   }
 }
 
-function emitInternalEvent<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase>(
-  rt: StoreRuntime<M, C, P, R>,
-  event: InternalEvent<M, C, P, R>,
-) {
+function emitInternalEvent<
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
+  P extends string,
+  R extends Contracts.Result.Base,
+>(rt: Store.Runtime<M, C, P, R>, event: Engine.Event<M, C, P, R>) {
   switch (event.type) {
     case 'files.added': {
       for (const item of event.items) {
@@ -308,11 +302,16 @@ function emitInternalEvent<M extends IntentMap, C extends CursorMap<M>, P extend
   }
 }
 
-function emitCommandEvents<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase>(
-  rt: StoreRuntime<M, C, P, R>,
-  cmd: UploadCommand<P>,
-  prev: UploadState<M, C, P, R>,
-  next: UploadState<M, C, P, R>,
+function emitCommandEvents<
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
+  P extends string,
+  R extends Contracts.Result.Base,
+>(
+  rt: Store.Runtime<M, C, P, R>,
+  cmd: Engine.Command<P>,
+  prev: Engine.State<M, C, P, R>,
+  next: Engine.State<M, C, P, R>,
 ) {
   if (cmd.type === 'start' || cmd.type === 'resume') {
     const prevItem = prev.items.get(cmd.localId)