@gentleduck/upload 0.2.6 → 0.3.0

package/src/core/engine/engine.types.ts

@@ -1,19 +1,114 @@
-import type { Contracts } from '../contracts'
+import type { Contracts } from '../contracts/contracts.types'
+import type { UploadError } from '../errors'
+import type { Store } from './store'
 
 /**
- * Engine-level type surface.
- *
+ * Engine-level type surface containing runtime state models, commands, progress,
+ * and configuration options.
  * @author wildduck2 <https://github.com/wildduck2>
  */
 export namespace Engine {
-  // -------------------- Progress --------------------
+  /**
+   * Return value from a retry policy determining if and when a task should be re-scheduled.
+   */
+  export type RetryDecision =
+    | {
+        /** The task has failed terminal or cannot recover. */
+        retryable: false
+      }
+    | {
+        /** The task is recoverable and should retry. */
+        retryable: true
+        /** Delay duration in milliseconds before invoking the next attempt. */
+        delayMs: number
+      }
 
   /**
-   * Upload progress snapshot with `pct` clamped to 0..100.
+   * Global upload engine configuration.
+   *
+   * Coordinates concurrency limits, retry strategies, constraints, and validation.
    *
-   * @author wildduck2 <https://github.com/wildduck2>
+   * @typeParam P - Union of allowed `purpose` strings for your app (e.g. `"avatar" | "attachment"`).
+   */
+  export type Config<P extends string> = {
+    /**
+     * Maximum number of parallel uploads active at any time.
+     * Queued items wait until active uploads complete or fail.
+     */
+    maxConcurrentUploads: number
+
+    /**
+     * Auto-start uploads for specific purposes.
+     * - Array form: only files with these purposes automatically begin uploading on registration.
+     * - Function form: dynamic callback determining whether to auto-start.
+     */
+    autoStart?: (readonly P[] | ((purpose: P) => boolean)) | undefined
+
+    /**
+     * Throttle delay in milliseconds for progress events.
+     * Limits rendering updates and state changes under busy progress flows.
+     */
+    progressThrottleMs: number
+
+    /**
+     * Validation rules keyed by purpose.
+     */
+    validation: Partial<Record<P, Contracts.ValidationRules>>
+
+    /**
+     * Maximum number of retry attempts permitted for upload/intent actions.
+     */
+    maxAttempts: number
+
+    /**
+     * Custom retry policy handler.
+     * Overrides default exponential backoff calculation.
+     */
+    retryPolicy?:
+      | ((ctx: {
+          /** The active execution phase. */
+          phase: 'intent' | 'upload' | 'complete'
+          /** Current attempt number (starting at 1). */
+          attempt: number
+          /** The normalized error structure. */
+          error: UploadError
+        }) => RetryDecision)
+      | undefined
+
+    /**
+     * Maximum number of items to keep in memory/state.
+     * When exceeded, oldest completed/canceled items are evicted automatically.
+     *
+     * Set to `undefined` for no limit (not recommended for long-running single-page apps).
+     */
+    maxItems: number
+
+    /**
+     * Duration in milliseconds after which completed items are evicted from the store.
+     * Set to `undefined` to preserve completed items indefinitely.
+     */
+    completedItemTTL?: number | undefined
+
+    /**
+     * Set to `true` to validate files by sniffing magic bytes/mime signature
+     * and rejecting files whose suffix does not match structural magic numbers.
+     */
+    strictMimeMatch?: boolean | undefined
+
+    /**
+     * File-size boundary in bytes between the two checksum paths. At or below
+     * it, files hash inline with native Web Crypto (fastest). Above it, files
+     * hash incrementally in bounded slices — off the main thread via a Web
+     * Worker when available — so large files no longer freeze the UI and are
+     * still deduplicated. Set to `null` or `undefined` for the default (64 MiB).
+     */
+    checksumMaxSize?: number | null | undefined
+  }
+
+  /**
+   * Upload progress snapshot.
    */
-  export interface IUploadProgress {
+  export type Progress = {
     /** Bytes uploaded so far. */
     uploadedBytes: number
     /** Total bytes to upload. */
@@ -22,255 +117,269 @@ export namespace Engine {
     pct: number
   }
 
-  // -------------------- Outcome --------------------
-
   /**
-   * How a `completed` item finished.
-   *
-   * @author wildduck2 <https://github.com/wildduck2>
+   * Describes how a `completed` upload item resolved.
+   * - `'upload'`: standard byte transfer.
+   * - `'dedupe'`: server matched existing file checksum, skipping byte transfer.
    */
   export type CompletionKind = 'upload' | 'dedupe'
 
   /**
-   * Terminal outcome returned by `Store.IUploadStore.waitFor`.
+   * Terminal outcome returned by `waitFor`.
    *
    * @template R Result type carried on successful completion.
-   * @author wildduck2 <https://github.com/wildduck2>
    */
-  export type Outcome<R extends Contracts.IResultBase> =
-    | { localId: string; status: 'completed'; completedBy: CompletionKind; result: R }
-    | { localId: string; status: 'error'; error: Contracts.Error }
-    | { localId: string; status: 'canceled' }
+  export type Outcome<R extends Contracts.Result.Base> =
+    | {
+        localId: string
+        status: 'completed'
+        completedBy: CompletionKind
+        result: R
+      }
+    | {
+        localId: string
+        status: 'error'
+        error: UploadError
+      }
+    | {
+        localId: string
+        status: 'canceled'
+      }
     | {
         localId: string
         status: 'missing'
         /**
-         * Why the id is missing. Required so consumers exhaustively
-         * handle every cause via switch.
-         * - `'removed'`: explicit `dispatch({ type: 'remove' })`.
-         * - `'evicted'`: cleanup pass (`maxItems` / `completedItemTTL`).
-         * - `'never-existed'`: the id was never registered in this store.
-         * - `'destroyed'`: `store.destroy()` ran while the wait was pending.
+         * Why the id is missing.
+         * - `'removed'`: explicit user removal.
+         * - `'evicted'`: automatically removed (maxItems/TTL rules).
+         * - `'never-existed'`: id was never registered.
+         * - `'destroyed'`: store was destroyed.
          */
         reason: 'removed' | 'evicted' | 'never-existed' | 'destroyed'
       }
 
-  // -------------------- Commands --------------------
-
   /**
-   * Public commands accepted by `store.dispatch`.
+   * Public commands dispatched to the upload store.
    *
    * @template P Purpose discriminator string.
-   * @author wildduck2 <https://github.com/wildduck2>
    */
   export type Command<P extends string> =
-    | { type: 'addFiles'; files: File[]; purpose: P }
-    | { type: 'start'; localId: string }
-    | { type: 'startAll'; purpose?: P }
-    | { type: 'pause'; localId: string }
-    | { type: 'pauseAll'; purpose?: P }
-    | { type: 'resume'; localId: string }
-    | { type: 'cancel'; localId: string }
-    | { type: 'cancelAll'; purpose?: P }
-    | { type: 'retry'; localId: string }
-    | { type: 'rebind'; localId: string; file: File }
-    | { type: 'remove'; localId: string }
-
-  // -------------------- Phases / Items --------------------
-
-  /**
-   * Every upload phase; the `phase` discriminator of {@link Engine.Item}.
-   *
-   * @author wildduck2 <https://github.com/wildduck2>
-   */
-  export type Phase =
-    | 'validating'
-    | 'creating_intent'
-    | 'ready'
-    | 'queued'
-    | 'uploading'
-    | 'paused'
-    | 'completing'
-    | 'completed'
-    | 'error'
-    | 'canceled'
-
-  /**
-   * Enum-style const map of every {@link Phase} value.
-   *
-   * Reading `Phases.completing` matches the string literal at compile time
-   * AND gives consumers a single import point instead of N magic-string
-   * checks. Use whichever style fits the call site.
-   *
-   * @author wildduck2 <https://github.com/wildduck2>
-   */
-  export const Phases = {
-    validating: 'validating',
-    creating_intent: 'creating_intent',
-    ready: 'ready',
-    queued: 'queued',
-    uploading: 'uploading',
-    paused: 'paused',
-    completing: 'completing',
-    completed: 'completed',
-    error: 'error',
-    canceled: 'canceled',
-  } as const satisfies Record<Phase, Phase>
-
-  /**
-   * Discriminated union on `phase` describing a single upload's state.
-   *
-   * @template M Intent map keyed by strategy id.
-   * @template C Cursor map keyed by strategy id.
-   * @template P Purpose discriminator string.
-   * @template R Backend result payload.
-   * @author wildduck2 <https://github.com/wildduck2>
-   */
-  export type Item<
-    M extends Contracts.IntentMap,
-    C extends Contracts.CursorMap<M>,
-    P extends string,
-    R extends Contracts.IResultBase = Contracts.IResultBase,
-  > =
     | {
-        phase: 'validating'
-        localId: string
+        /** Register files into the upload store for a specific purpose. */
+        type: 'addFiles'
+        files: File[]
         purpose: P
-        fingerprint: Contracts.IFileFingerprint
-        file: File
-        createdAt: number
+        /** Optional caller metadata forwarded to every backend API call for this file. */
+        meta?: Record<string, unknown> | undefined
       }
     | {
-        phase: 'creating_intent'
+        /** Start uploading a specific file. */
+        type: 'start'
         localId: string
-        purpose: P
-        fingerprint: Contracts.IFileFingerprint
-        file: File
-        attempt: number
-        createdAt: number
       }
     | {
-        phase: 'ready'
-        localId: string
-        purpose: P
-        fingerprint: Contracts.IFileFingerprint
-        file: File
-        intent: Contracts.AnyIntent<M>
-        createdAt: number
-        cursor?: Contracts.AnyCursor<C>
-        progress?: IUploadProgress
-        attempt?: number
+        /** Start all queued files, optionally filtering by purpose. */
+        type: 'startAll'
+        purpose?: P
       }
     | {
-        phase: 'queued'
+        /** Pause an active upload. */
+        type: 'pause'
         localId: string
-        purpose: P
-        fingerprint: Contracts.IFileFingerprint
-        file: File
-        intent: Contracts.AnyIntent<M>
-        requestedAt: number
-        createdAt: number
-        cursor?: Contracts.AnyCursor<C>
-        progress?: IUploadProgress
-        attempt?: number
       }
     | {
-        phase: 'uploading'
-        localId: string
-        purpose: P
-        fingerprint: Contracts.IFileFingerprint
-        file: File
-        intent: Contracts.AnyIntent<M>
-        startedAt: number
-        progress: IUploadProgress
-        createdAt: number
-        cursor?: Contracts.AnyCursor<C>
-        attempt?: number
+        /** Pause all active uploads, optionally filtering by purpose. */
+        type: 'pauseAll'
+        purpose?: P
       }
     | {
-        phase: 'paused'
+        /** Resume a paused upload. */
+        type: 'resume'
         localId: string
-        purpose: P
-        fingerprint: Contracts.IFileFingerprint
-        intent: Contracts.AnyIntent<M>
-        cursor: Contracts.AnyCursor<C>
-        progress: IUploadProgress
-        pausedAt: number
-        createdAt: number
-        file?: File
-        attempt?: number
       }
     | {
-        phase: 'completing'
+        /** Cancel a pending or active upload. */
+        type: 'cancel'
         localId: string
-        purpose: P
-        fingerprint: Contracts.IFileFingerprint
-        file: File
-        intent: Contracts.AnyIntent<M>
-        progress: IUploadProgress
-        completingAt: number
-        createdAt: number
-        attempt?: number
       }
     | {
-        phase: 'completed'
+        /** Cancel all pending and active uploads, optionally filtering by purpose. */
+        type: 'cancelAll'
+        purpose?: P
+      }
+    | {
+        /** Retry a failed upload item. */
+        type: 'retry'
         localId: string
-        file?: File
-        purpose: P
-        fingerprint: Contracts.IFileFingerprint
-        intent?: Contracts.AnyIntent<M>
-        completedBy: CompletionKind
-        result: R
-        completedAt: number
-        createdAt: number
-        attempt?: number
       }
     | {
-        phase: 'error'
+        /** Re-bind a new browser `File` object to a resumed/paused item missing a file reference. */
+        type: 'rebind'
         localId: string
-        purpose: P
-        fingerprint: Contracts.IFileFingerprint
-        error: Contracts.Error
-        retryable: boolean
-        attempt: number
-        failedAt: number
-        createdAt: number
-        file?: File
-        intent?: Contracts.AnyIntent<M>
-        cursor?: Contracts.AnyCursor<C>
-        progress?: IUploadProgress
+        file: File
       }
     | {
-        phase: 'canceled'
+        /** Remove an item from the store state entirely. */
+        type: 'remove'
         localId: string
-        purpose: P
-        fingerprint: Contracts.IFileFingerprint
-        canceledAt: number
-        createdAt: number
-        file?: File
-        intent?: Contracts.AnyIntent<M>
-        cursor?: Contracts.AnyCursor<C>
-        progress?: IUploadProgress
-        attempt?: number
       }
 
-  // -------------------- Internal events --------------------
+  /**
+   * Const mapping of upload stages.
+   */
+  export const Phases = {
+    /** Initial validation checks are running. */
+    validating: 'validating',
+    /** Fetching signed URLs and strategies from backend. */
+    creating_intent: 'creating_intent',
+    /** Ready to start uploading bytes. */
+    ready: 'ready',
+    /** Waiting in queue (concurrency cap reached). */
+    queued: 'queued',
+    /** Actively transferring bytes. */
+    uploading: 'uploading',
+    /** Upload paused; resumable state preserved. */
+    paused: 'paused',
+    /** Triggering backend finalization. */
+    completing: 'completing',
+    /** File is fully completed and registered on backend. */
+    completed: 'completed',
+    /** Execution hit a terminal error or maximum retry cap. */
+    error: 'error',
+    /** Upload was canceled by the user. */
+    canceled: 'canceled',
+  } as const
+
+  /** Every upload phase; the `phase` discriminator of {@link Item}. */
+  export type Phase = keyof typeof Phases
+
+  interface BaseItem<P extends string> {
+    /** Unique client-side identifier for this file item. */
+    localId: string
+    /** Target upload purpose. */
+    purpose: P
+    /** Metadata properties identifying the file. */
+    fingerprint: Contracts.FingerprintFile
+    /** Epoch timestamp in ms when the item was registered. */
+    createdAt: number
+    attempt?: number | undefined
+    file?: File | undefined
+    /** Full phase history. Each entry records when a phase was entered/left and any stripped error. */
+    steps: Contracts.UploadStep[]
+    /** Arbitrary caller-supplied metadata from the addFiles command. Never persisted. */
+    meta: Record<string, unknown>
+  }
 
   /**
-   * Events emitted by effects and consumed by the reducer. Distinct from the
-   * public event surface -- these drive state transitions.
-   *
-   * @template M Intent map keyed by strategy id.
-   * @template C Cursor map keyed by strategy id.
-   * @template P Purpose discriminator string.
-   * @template R Backend result payload.
-   * @author wildduck2 <https://github.com/wildduck2>
+   * Representational union of upload items in their respective lifecycle phases.
+   */
+  export type Item<
+    M extends Contracts.Intent.Map,
+    C extends Contracts.Cursor.Map<M>,
+    P extends string,
+    R extends Contracts.Result.Base = Contracts.Result.Base,
+  > = BaseItem<P> &
+    (
+      | { phase: 'validating'; file: File }
+      | { phase: 'creating_intent'; file: File; attempt: number }
+      | {
+          phase: 'ready'
+          file: File
+          intent: Contracts.Intent.Any<M>
+          cursor?: Contracts.Cursor.Any<C> | undefined
+          progress?: Progress | undefined
+        }
+      | {
+          phase: 'queued'
+          file: File
+          intent: Contracts.Intent.Any<M>
+          requestedAt: number
+          cursor?: Contracts.Cursor.Any<C> | undefined
+          progress?: Progress | undefined
+        }
+      | {
+          phase: 'uploading'
+          file: File
+          intent: Contracts.Intent.Any<M>
+          startedAt: number
+          progress: Progress
+          cursor?: Contracts.Cursor.Any<C> | undefined
+        }
+      | {
+          phase: 'paused'
+          intent: Contracts.Intent.Any<M>
+          cursor: Contracts.Cursor.Any<C>
+          progress: Progress
+          pausedAt: number
+          file?: File | undefined
+        }
+      | { phase: 'completing'; file: File; intent: Contracts.Intent.Any<M>; progress: Progress; completingAt: number }
+      | {
+          phase: 'completed'
+          completedBy: CompletionKind
+          result: R
+          completedAt: number
+          intent?: Contracts.Intent.Any<M> | undefined
+          file?: File | undefined
+        }
+      | {
+          phase: 'error'
+          error: UploadError
+          retryable: boolean
+          attempt: number
+          failedAt: number
+          file?: File | undefined
+          intent?: Contracts.Intent.Any<M> | undefined
+          cursor?: Contracts.Cursor.Any<C> | undefined
+          progress?: Progress | undefined
+        }
+      | {
+          phase: 'canceled'
+          canceledAt: number
+          file?: File | undefined
+          intent?: Contracts.Intent.Any<M> | undefined
+          cursor?: Contracts.Cursor.Any<C> | undefined
+          progress?: Progress | undefined
+          attempt?: number | undefined
+        }
+    )
+
+  /**
+   * Immutable state shape of the upload engine store.
+   */
+  export type State<
+    M extends Contracts.Intent.Map,
+    C extends Contracts.Cursor.Map<M>,
+    P extends string,
+    R extends Contracts.Result.Base = Contracts.Result.Base,
+  > = {
+    /** Map of active and historical upload items. */
+    items: Map<string, Item<M, C, P, R>>
+  }
+
+  /**
+   * Interface for registering lifecycle plugins.
+   */
+  export type Plugin<
+    M extends Contracts.Intent.Map,
+    C extends Contracts.Cursor.Map<M>,
+    P extends string,
+    R extends Contracts.Result.Base = Contracts.Result.Base,
+  > = {
+    /** Name of the plugin (for diagnostics). */
+    name: string
+    /** Sets up subscription listener binds on the store core proxy. */
+    setup(store: Pick<Store.UploadStore<M, C, P, R>, 'on' | 'off' | 'dispatch' | 'getSnapshot'>): void
+  }
+
+  /**
+   * Events emitted by effects and consumed by the reducer to transition item states.
    */
-  export type InternalEvent<
-    M extends Contracts.IntentMap,
-    C extends Contracts.CursorMap<M>,
+  export type Event<
+    M extends Contracts.Intent.Map,
+    C extends Contracts.Cursor.Map<M>,
     P extends string,
-    R extends Contracts.IResultBase = Contracts.IResultBase,
+    R extends Contracts.Result.Base = Contracts.Result.Base,
   > =
     | {
         type: 'files.added'
@@ -278,87 +387,104 @@ export namespace Engine {
           localId: string
           purpose: P
           file: File
-          fingerprint: Contracts.IFileFingerprint
+          fingerprint: Contracts.FingerprintFile
           createdAt: number
+          meta: Record<string, unknown>
         }>
       }
-    | { type: 'fingerprint.updated'; localId: string; fingerprint: Contracts.IFileFingerprint }
+    | { type: 'fingerprint.updated'; localId: string; fingerprint: Contracts.FingerprintFile }
     | { type: 'validation.ok'; localId: string }
-    | { type: 'validation.failed'; localId: string; reason: Contracts.RejectReason }
-    | { type: 'intent.ok'; localId: string; intent: Contracts.AnyIntent<M> }
-    | { type: 'intent.failed'; localId: string; error: Contracts.Error; retryable: boolean }
+    | { type: 'validation.failed'; localId: string; reason: Contracts.Validation.Rejection }
+    | { type: 'intent.ok'; localId: string; intent: Contracts.Intent.Any<M> }
+    | { type: 'intent.failed'; localId: string; error: UploadError; retryable: boolean }
     | { type: 'upload.begin'; localId: string; startedAt: number }
     | { type: 'upload.progress'; localId: string; uploadedBytes: number; totalBytes: number }
-    | { type: 'cursor.updated'; localId: string; cursor: Contracts.AnyCursor<C> }
+    | { type: 'cursor.updated'; localId: string; cursor: Contracts.Cursor.Any<C> }
     | { type: 'upload.ok'; localId: string }
-    | { type: 'upload.failed'; localId: string; error: Contracts.Error; retryable: boolean }
+    | { type: 'upload.failed'; localId: string; error: UploadError; retryable: boolean }
     | { type: 'dedupe.ok'; localId: string; result: R }
     | { type: 'complete.ok'; localId: string; result: R }
-    | { type: 'complete.failed'; localId: string; error: Contracts.Error; retryable: boolean }
-    | { type: 'paused'; localId: string; cursor: Contracts.AnyCursor<C>; pausedAt: number }
+    | { type: 'complete.failed'; localId: string; error: UploadError; retryable: boolean }
+    | { type: 'paused'; localId: string; cursor: Contracts.Cursor.Any<C>; pausedAt: number }
     | { type: 'canceled'; localId: string; canceledAt: number }
 
-  // -------------------- Public event map --------------------
-
   /**
-   * Public event map emitted to consumers via `store.on(type, cb)`.
-   *
-   * @template M Intent map keyed by strategy id.
-   * @template C Cursor map keyed by strategy id.
-   * @template P Purpose discriminator string.
-   * @template R Backend result payload.
-   * @author wildduck2 <https://github.com/wildduck2>
+   * Public event registry mapping event names to payloads emitted via `store.on()`.
    */
   export type EventMap<
-    M extends Contracts.IntentMap,
-    C extends Contracts.CursorMap<M>,
+    M extends Contracts.Intent.Map,
+    C extends Contracts.Cursor.Map<M>,
     P extends string,
-    R extends Contracts.IResultBase = Contracts.IResultBase,
+    R extends Contracts.Result.Base = Contracts.Result.Base,
   > = {
-    'file.added': { localId: string; purpose: P; file: File; fingerprint: Contracts.IFileFingerprint }
-    'file.rejected': { file: File; reason: Contracts.RejectReason }
+    /** Emitted when a file is validated and successfully registered in state. */
+    'file.added': { localId: string; purpose: P; file: File; fingerprint: Contracts.FingerprintFile }
+    /** Emitted when a file fails client-side validation rules. */
+    'file.rejected': { file: File; reason: Contracts.Validation.Rejection }
 
+    /** Emitted when validation succeeds. */
     'validation.ok': { localId: string }
-    'validation.failed': { localId: string; reason: Contracts.RejectReason }
+    /** Emitted when validation fails. */
+    'validation.failed': { localId: string; reason: Contracts.Validation.Rejection }
 
+    /** Emitted when intent lookup/creation is requested. */
     'intent.creating': { localId: string }
+    /** Emitted when upload intent is successfully created. */
     'intent.created': { localId: string; intent: M[keyof M] }
-    'intent.failed': { localId: string; error: Contracts.Error; retryable: boolean }
+    /** Emitted when intent creation fails. */
+    'intent.failed': { localId: string; error: UploadError; retryable: boolean }
 
+    /** Emitted when an item is queued waiting for concurrency slots. */
     'upload.queued': { localId: string }
+    /** Emitted when a paused upload is resumed. */
     'upload.resumed': { localId: string }
+    /** Emitted when data transfer starts. */
     'upload.started': { localId: string }
+    /** Periodic progress event. */
     'upload.progress': { localId: string; pct: number; uploadedBytes: number; totalBytes: number }
-    'upload.cursor': { localId: string; cursor: Contracts.AnyCursor<C> }
-    'upload.paused': { localId: string; cursor: Contracts.AnyCursor<C> }
+    /** Emitted when strategy cursor state is updated. */
+    'upload.cursor': { localId: string; cursor: Contracts.Cursor.Any<C> }
+    /** Emitted when upload is paused. */
+    'upload.paused': { localId: string; cursor: Contracts.Cursor.Any<C> }
+    /** Emitted when upload is canceled. */
     'upload.canceled': { localId: string }
 
+    /** Emitted when final completing steps (like completeMultipart or final verification) begin. */
     'upload.completing': { localId: string }
+    /** Emitted when a file is completely uploaded and finalized. */
     'upload.completed': { localId: string; result: R; completedBy: CompletionKind }
 
-    'upload.error': { localId: string; error: Contracts.Error; retryable: boolean }
+    /** Emitted when transfer hits a retryable or terminal error. */
+    'upload.error': { localId: string; error: UploadError; retryable: boolean }
 
-    /**
-     * Emitted whenever an item leaves state. `reason: 'user'` for an
-     * explicit `dispatch({ type: 'remove' })`; `reason: 'cleanup'` for
-     * an automatic eviction by `completedItemTTL` / `maxItems`. Lets
-     * consumers (waitFor, UI listeners, telemetry) react without polling
-     * the snapshot.
-     */
+    /** Emitted when an item is removed from the store state. */
     'upload.removed': { localId: string; reason: 'user' | 'cleanup' }
 
+    /** Emitted when a file rebind operation succeeds. */
     'rebind.ok': { localId: string }
+    /** Emitted when a file rebind fails. */
     'rebind.failed': { localId: string; reason: RebindReason }
   }
 
   /**
-   * Why a `rebind` command did not bind a file.
-   *
-   * @author wildduck2 <https://github.com/wildduck2>
+   * Rebind failure classifications.
    */
   export type RebindReason =
     | { code: 'no_item' }
     | { code: 'wrong_phase'; phase: string }
     | { code: 'already_bound' }
-    | { code: 'fingerprint_mismatch'; expected: Contracts.IFileFingerprint; got: Contracts.IFileFingerprint }
+    | { code: 'fingerprint_mismatch'; expected: Contracts.FingerprintFile; got: Contracts.FingerprintFile }
+
+  /**
+   * Diagnostic hooks for observing engine updates.
+   */
+  export type Hooks<
+    M extends Contracts.Intent.Map,
+    C extends Contracts.Cursor.Map<M>,
+    P extends string,
+    R extends Contracts.Result.Base = Contracts.Result.Base,
+  > = {
+    /** Callback invoked on every state-reducing internal event. */
+    onInternalEvent?: (event: Event<M, C, P, R>, state: State<M, C, P, R>) => void
+  }
 }