@gentleduck/upload 0.2.6 → 0.3.0

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

@@ -1,34 +1,86 @@
-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,
+  }
+}
+
+/**
+ * Default boundary between inline and incremental hashing when
+ * `config.checksumMaxSize` is unset (`null`) or `0`: 64 MiB.
+ */
+export const DEFAULT_CHECKSUM_MAX_SIZE = 64 * 1024 * 1024
 
-/** SHA-256 checksum of `file` for deduplication. */
-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('')
+/**
+ * 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.
+ *
+ * Pass `maxSize = 0` or omit it to use {@link DEFAULT_CHECKSUM_MAX_SIZE}.
+ *
+ * @returns lowercase hex SHA-256 digest.
+ */
+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 IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase>(
-  opts: StoreOptions<M, C, P, R>,
-  purpose: P,
-): boolean {
+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
 }
 
@@ -40,51 +92,142 @@ export function isAutoStart<M extends IntentMap, C extends CursorMap<M>, P exten
 export { computeFingerprint, fingerprintMatches }
 
 /**
- * Normalize a thrown value into an {@link UploadError}. Override via
+ * When `findByChecksum` matches, complete the item without creating an intent or
+ * uploading bytes. Returns `true` when dedupe succeeded.
+ */
+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) => UploadError): UploadError {
+export function normalizeError(err: unknown, customNormalizer?: (err: unknown) => Contracts.Errors.Error): UploadError {
   if (customNormalizer) return customNormalizer(err)
 
+  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'
 
-  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 })
   }
 
-  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 })
 }
 
 /** Item has 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] }> {
+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
 }
 
 /** Item has a bound `File`. Persisted items may lack it until the UI re-binds. */
-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 }> {
+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
 }
 
 /** Item variant carries a cursor field (depends on phase/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> }> {
+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
 }
 
@@ -94,14 +237,14 @@ export function isMultipartIntent(
 ): 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'
   )
 }
 
 export function isAbortError(err: unknown): err is { code: 'aborted'; reason?: unknown } {
-  return isRecord(err) && err.code === 'aborted'
+  return isRecord(err) && err['code'] === 'aborted'
 }
 
 /**
@@ -110,7 +253,7 @@ export function isAbortError(err: unknown): err is { code: 'aborted'; reason?: u
  * 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)

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

@@ -1,27 +1,26 @@
-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'
 
 /**
  * Build the store runtime: state, emitter, reducer, and effect queue.
- * Reducers stay pure — async work goes through {@link StoreRuntime.enqueueEffect}.
+ * 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
 
@@ -43,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)
       }
     }
@@ -59,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>(),
 
@@ -91,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
@@ -107,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
@@ -135,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,
@@ -149,14 +148,14 @@ export function createStoreRuntime<
       rt.processingEffects = false
     },
 
-    // Replaced by createUploadStore — runtime breaks the cycle.
+    // 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>
 
   // Async adapters (IndexedDB) resolve after construction; only hydrate when no
-  // initialState was provided. Merge into an empty store only — never clobber
+  // 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 {
@@ -195,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),
@@ -205,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) {
@@ -298,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)

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

@@ -1,10 +1,10 @@
-import type { CursorMap, IntentMap, UploadResultBase } from '../../contracts'
-import type { UploadItem } from '../internal-events.types'
+import type { Contracts } from '../../contracts'
+import type { Engine } from '../engine.types'
 import { createIntent } from './handlers/create-intent'
 import { finalizeUpload } from './handlers/finalize'
 import { runUpload } from './handlers/run-upload'
 import { isAutoStart } from './store.libs'
-import type { StoreRuntime } from './store.types'
+import type { Store } from './store.types'
 
 /**
  * Central scheduler that ensures the system is always making progress towards a consistent state.
@@ -15,9 +15,12 @@ import type { StoreRuntime } from './store.types'
  *
  * This function is idempotent and safe to call multiple times.
  */
-export function scheduleWork<M extends IntentMap, C extends CursorMap<M>, P extends string, R extends UploadResultBase>(
-  rt: StoreRuntime<M, C, P, R>,
-) {
+export function scheduleWork<
+  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>) {
   if (rt.scheduling) return
   rt.scheduling = true
   try {
@@ -36,11 +39,11 @@ export function scheduleWork<M extends IntentMap, C extends CursorMap<M>, P exte
  * {@link StoreRuntime.inflightIntents}.
  */
 export function scheduleIntentCreations<
-  M extends IntentMap,
-  C extends CursorMap<M>,
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
   P extends string,
-  R extends UploadResultBase,
->(rt: StoreRuntime<M, C, P, R>) {
+  R extends Contracts.Result.Base,
+>(rt: Store.Runtime<M, C, P, R>) {
   for (const item of rt.state.items.values()) {
     if (item.phase !== 'creating_intent') continue
     if (rt.inflightIntents.has(item.localId)) continue
@@ -54,11 +57,11 @@ export function scheduleIntentCreations<
  * Finalization runs as an async effect and is guarded by {@link StoreRuntime.inflightCompletes}.
  */
 export function scheduleCompletes<
-  M extends IntentMap,
-  C extends CursorMap<M>,
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
   P extends string,
-  R extends UploadResultBase,
->(rt: StoreRuntime<M, C, P, R>) {
+  R extends Contracts.Result.Base,
+>(rt: Store.Runtime<M, C, P, R>) {
   for (const item of rt.state.items.values()) {
     if (item.phase !== 'completing') continue
     if (rt.inflightCompletes.has(item.localId)) continue
@@ -71,11 +74,11 @@ export function scheduleCompletes<
  * Respects `maxConcurrentUploads` from config.
  */
 export function scheduleUploads<
-  M extends IntentMap,
-  C extends CursorMap<M>,
+  M extends Contracts.Intent.Map,
+  C extends Contracts.Cursor.Map<M>,
   P extends string,
-  R extends UploadResultBase,
->(rt: StoreRuntime<M, C, P, R>) {
+  R extends Contracts.Result.Base,
+>(rt: Store.Runtime<M, C, P, R>) {
   const maxConcurrent = Math.max(1, rt.opts.config.maxConcurrentUploads)
   const active = rt.inflightUploads.size
 
@@ -109,8 +112,11 @@ export function scheduleUploads<
   }
 }
 
-function isQueuedItem<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>, { phase: 'queued' }> {
+function isQueuedItem<
+  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>, { phase: 'queued' }> {
   return item.phase === 'queued'
 }