@lostgradient/weft 0.2.0 → 0.3.0

package/dist/core/context/run-operation.js

@@ -1,8 +1,15 @@
 import { calculateBackoff } from "../scheduler.js";
-import { DEFAULT_RETRY_POLICY } from "../types.js";
-import { getInternals } from "./internals.js";
+import {
+  DEFAULT_RETRY_POLICY
+} from "../types.js";
+import { getInternals, hasContextInternals } from "./internals.js";
 import { isActivityCallOptions } from "./session-state.js";
 import { captureCallerStack } from "./validation.js";
+export function asConcreteContext(context) {
+  if (!hasContextInternals(context))
+    throw Error("Step-based workflows (compileStepWorkflow / ctx.step) require workflowExecutionMode: 'inline'. The worker execution strategy runs workflows with a different context that has no durable step machinery. Use the generator workflow API for worker execution mode.");
+  return context;
+}
 const ACTIVITY_RETRY_STATE_LOCAL_KEY = "__weftActivityRetryState", ACTIVITY_RETRY_STATE_VERSION = 1, MAX_CHECKPOINTED_RETRY_ATTEMPT = 1e4;
 function acceptsNoActivityInput(fn) {
   if (typeof fn !== "function")
@@ -104,7 +111,9 @@ function completeActivityRetryAttempt(internals, step, completedRetrySleepCount)
     }
   };
 }
-function getActivityName(activity) {
+function getActivityName(activity, explicitName) {
+  if (explicitName !== void 0)
+    return explicitName;
   return typeof activity === "string" ? activity : activity.name || "anonymous";
 }
 function getActivityFunction(activity) {
@@ -190,8 +199,8 @@ function prepareActivityRetryRequest(request, attempt) {
     attempt
   };
 }
-export function createRunActivityRequest(context, activity, rest) {
-  const { input, options } = parseRunArguments(activity, rest), activityName = getActivityName(activity), activityFunction = getActivityFunction(activity), internals = getInternals(context), step = internals.stepIndex++, cachedRequest = getCachedRunActivityRequest(internals, step, activityName, input);
+export function createRunActivityRequest(context, activity, rest, explicitName) {
+  const { input, options } = parseRunArguments(activity, rest), activityName = getActivityName(activity, explicitName), activityFunction = getActivityFunction(activity), internals = getInternals(context), step = internals.stepIndex++, cachedRequest = getCachedRunActivityRequest(internals, step, activityName, input);
   if (cachedRequest.hasCachedResult)
     return cachedRequest;
   const retryPolicy = resolveActivityRetryPolicy(activity, options);
@@ -203,8 +212,8 @@ export function createRunActivityRequest(context, activity, rest) {
     ...retryPolicy === void 0 ? {} : { retryPolicy }
   };
 }
-export function* runActivityWithRetry(context, activity, rest) {
-  const { request, step, hasCachedResult, cachedResult, retryAttempt, retryPolicy } = createRunActivityRequest(context, activity, rest);
+export function* runActivityWithRetry(context, activity, rest, explicitName) {
+  const { request, step, hasCachedResult, cachedResult, retryAttempt, retryPolicy } = createRunActivityRequest(context, activity, rest, explicitName);
   if (hasCachedResult)
     return cachedResult;
   const internals = getInternals(context);

package/dist/core/context/speculative-child.js

@@ -16,6 +16,8 @@ function assignOptionalContextOptions(options, internals) {
     options.sleepReferenceTime = internals.sleepReferenceTime;
   if (internals.resolveWorkflowType !== void 0)
     options.resolveWorkflowType = internals.resolveWorkflowType;
+  if (internals.services !== void 0)
+    options.services = internals.services;
 }
 function createSpeculativeChildOptions(parent, internals) {
   const options = {

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

@@ -178,4 +178,10 @@ export interface ContextOptions {
      * it is not persisted or restored after engine restart.
      */
     registerCancelHandler?: (handler: () => Promise<void> | void) => () => void;
+    /**
+     * Host-supplied, per-run capabilities exposed as `ctx.services`. Never
+     * checkpointed; held only for this run and re-provided on recovery via the
+     * engine's `resolveWorkflowServices` resolver.
+     */
+    services?: unknown;
 }

package/dist/core/engine/bulk-operations-purge.js

@@ -178,6 +178,7 @@ function buildBaseWorkflowDeleteKeys(state) {
     KEYS.checkpoint(state.id),
     KEYS.workflowHeaders(state.id),
     KEYS.terminalCleanupNeeded(state.id),
+    KEYS.workflowHasServices(state.id),
     KEYS.attribute(state.id),
     KEYS.terminalWorkflow(state.updatedAt, state.id)
   ]);

package/dist/core/engine/bulk-operations.js

@@ -17,7 +17,7 @@ import { BULK_OPERATION_BATCH_SIZE } from "./listing.js";
 import { loadWorkflowState } from "./storage-io.js";
 import { isTerminalWorkflowStatus } from "./validation.js";
 export { purgeInternal, TERMINAL_CLEANUP_DELAY_MS } from "./bulk-operations-purge.js";
-const ACTIVE_WORKFLOW_STATUSES = ["pending", "running"];
+const ACTIVE_WORKFLOW_STATUSES = ["pending", "running", "suspended"];
 export async function purge(internals, filter, cleanupWaiters) {
   return purgeInternal(internals, filter, { expiredOnly: !1, now: internals.options.getNow() }, cleanupWaiters);
 }

package/dist/core/engine/callback-creators-bundles.js

@@ -102,7 +102,8 @@ export function createTimeOperationCallbacks(engine) {
     parseStartOptionDuration: (value, fieldName) => parseStartOptionDuration(getInternals(engine), value, fieldName, createLifecycleCallbacks(engine)),
     runDeferredTerminalCleanup: (workflowId, timerId) => runDeferredTerminalCleanup(getInternals(engine), workflowId, timerId, createTerminationCallbacks(engine)),
     handleScheduleTimer: (entry) => handleScheduleTimerForEngine(engine, entry),
-    timeout: (workflowId) => engine.timeout(workflowId)
+    timeout: (workflowId) => engine.timeout(workflowId),
+    handleCleanupError: (source, error, workflowId) => createTerminationCallbacks(engine).handleCleanupError(source, error, workflowId)
   };
 }
 export function createUpdateCallbacks(engine) {

package/dist/core/engine/callback-creators-core.js

@@ -74,7 +74,8 @@ export function createLifecycleCallbacks(engine) {
     hasLocalCheckpointOwnership: (workflowId, workflowStatus) => hasLocalCheckpointOwnership(getInternals(engine), workflowId, workflowStatus),
     handleCleanupError: (source, error, workflowId) => createTerminationCallbacks(engine).handleCleanupError(source, error, workflowId),
     swallowPromiseRejection: (promise) => swallowPromiseRejection(promise),
-    enforceHistoryCircuitBreaker: (workflowId) => terminateWorkflow(getInternals(engine), workflowId, "timed-out", createTerminationCallbacks(engine), HISTORY_CIRCUIT_BREAKER_REASON)
+    enforceHistoryCircuitBreaker: (workflowId) => terminateWorkflow(getInternals(engine), workflowId, "timed-out", createTerminationCallbacks(engine), HISTORY_CIRCUIT_BREAKER_REASON),
+    failWorkflowForUnavailableServices: (workflowId, error) => failWorkflow(getInternals(engine), workflowId, error, createTerminationCallbacks(engine), "system")
   };
 }
 export function createTerminationCallbacksWith(engine, handleScheduledWorkflowTerminal) {

package/dist/core/engine/construction.d.ts

@@ -18,7 +18,6 @@ export type EngineCreateRuntimeOptions = EngineConstructorOptions & {
     workflows?: Record<string, AnyWorkflowDefinition> | undefined;
     recover?: boolean | undefined;
     acknowledgeUnknownWorkflowTypes?: boolean | undefined;
-    allowLegacyData?: boolean | undefined;
 };
 export type NormalizedWorkerExecutionConfiguration = {
     mode: 'inline';
@@ -54,6 +53,7 @@ export declare function createExecutionStrategyBundle(parameters: {
     getComposedWorkflowInterceptor?: () => ComposedWorkflowInterceptor | null;
     resolveWorkflowType: (target: string | Function) => string;
     registerCancelHandler?: (workflowId: string, handler: () => Promise<void> | void) => () => void;
+    getWorkflowServices?: (workflowId: string) => unknown;
 }): ExecutionStrategyBundle;
 export declare function createActivityWorkerDispatcher(activityExecution: EngineConstructorOptions['activityExecution']): ActivityWorkerDispatcher | null;
 export declare function createAlertManagerForEngine(engine: EventTarget, alerts: EngineOptions['alerts'] | undefined, getNow: () => number): AlertManager | null;

package/dist/core/engine/construction.js

@@ -103,14 +103,24 @@ function resolveHistoryFields(options) {
     payloadSizePolicy: normalizePayloadSizePolicy(options?.payloadSize, "options.payloadSize")
   };
 }
+const DEFAULT_SECOND_INSTANCE_HEARTBEAT_INTERVAL_MS = 15000;
+function resolveSecondInstanceFields(options) {
+  const enabled = defaultTo(options?.detectSecondInstance, !1), intervalMs = enabled ? normalizeRetentionDuration(options?.secondInstanceHeartbeatInterval, "options.secondInstanceHeartbeatInterval") ?? DEFAULT_SECOND_INSTANCE_HEARTBEAT_INTERVAL_MS : DEFAULT_SECOND_INSTANCE_HEARTBEAT_INTERVAL_MS;
+  return {
+    secondInstanceDetectionEnabled: enabled,
+    secondInstanceHeartbeatIntervalMs: intervalMs
+  };
+}
 export function resolveEngineOptions(storage, options, getNow) {
   return {
     storage,
     getNow,
+    resolveWorkflowServices: options?.resolveWorkflowServices ?? null,
     ...resolveBooleanDefaults(options),
     ...resolveNumericDefaults(options),
     ...resolveRetentionFields(options),
-    ...resolveHistoryFields(options)
+    ...resolveHistoryFields(options),
+    ...resolveSecondInstanceFields(options)
   };
 }
 export function normalizeWorkerExecutionConfiguration(options) {
@@ -169,7 +179,8 @@ export function createExecutionStrategyBundle(parameters) {
     getRegistration,
     getComposedWorkflowInterceptor,
     resolveWorkflowType,
-    registerCancelHandler
+    registerCancelHandler,
+    getWorkflowServices
   } = parameters, workerExecutionConfiguration = normalizeWorkerExecutionConfiguration(options);
   if (workerExecutionConfiguration.mode === "worker") {
     const pool = new WorkerPool({
@@ -195,7 +206,8 @@ export function createExecutionStrategyBundle(parameters) {
     maxNestingDepth,
     development,
     resolveWorkflowType,
-    ...registerCancelHandler !== void 0 && { registerCancelHandler }
+    ...registerCancelHandler !== void 0 && { registerCancelHandler },
+    ...getWorkflowServices !== void 0 && { getWorkflowServices }
   });
   return { strategy: inlineStrategy, inlineStrategy };
 }

package/dist/core/engine/disposal.js

@@ -22,6 +22,7 @@ export function disposeEngine(internals) {
     internals.retentionSweepInterval = null;
   }
   internals.nextRetentionSweepAt = null;
+  disposeSecondInstanceDetection(internals);
   internals.handleCache.clear();
   for (const waiter of internals.resultResolvers.values())
     waiter.reject(new EngineDisposedError);
@@ -43,6 +44,7 @@ export function disposeEngine(internals) {
   internals.checkpoints.clear();
   internals.pendingExecutionStateOwnerId = void 0;
   internals.workflowNestingDepths.clear();
+  internals.workflowServices.clear();
   internals.workflowHeaders.clear();
   internals.pendingStarts.clear();
   internals.pendingScheduleCreations.clear();
@@ -56,3 +58,13 @@ export function disposeEngine(internals) {
   internals.broadcastChannel?.close();
   internals.broadcastChannel = null;
 }
+function disposeSecondInstanceDetection(internals) {
+  if (internals.secondInstanceDetectionInterval !== null) {
+    clearInterval(internals.secondInstanceDetectionInterval ?? void 0);
+    internals.secondInstanceDetectionInterval = null;
+  }
+  if (internals.secondInstanceDetector !== null) {
+    internals.secondInstanceDetector.stop();
+    internals.secondInstanceDetector = null;
+  }
+}

package/dist/core/engine/engine-create-types.d.ts

@@ -29,20 +29,6 @@ export type EngineCreateOptions<TWorkflowDefinitions extends Record<string, AnyW
     workflows?: TWorkflowDefinitions;
     /** Activity definitions to register before workflows. */
     activities?: TActivityDefinitions;
-    /**
-     * Opt out of the persisted-data schema-version gate when opening a storage
-     * that contains workflow data written by `new Engine({ storage })` before
-     * the schema-version sentinel existed.
-     *
-     * The gate normally rejects any storage that already holds workflow records
-     * but lacks the sentinel — a safety check against silently classifying
-     * pre-sentinel data as schema-current. Set `allowLegacyData: true` only when
-     * you knowingly opened the same storage with the legacy constructor path and
-     * are intentionally recovering it via `Engine.create`. On success, the
-     * current schema-version sentinel is written. Remove the opt-in once the
-     * data has been migrated.
-     */
-    allowLegacyData?: boolean;
 } & ({
     /**
      * Recover stored running workflows after registration. Defaults to

package/dist/core/engine/engine-internal-types.d.ts

@@ -29,7 +29,16 @@ export interface ResolvedOptions {
     /** Operator-supplied sink for compacted event-log ranges; `null` when none. */
     archiveAdapter: ArchiveAdapter | null;
     payloadSizePolicy: NormalizedPayloadSizePolicy;
+    /** Whether the best-effort second-instance liveness detector is enabled. */
+    secondInstanceDetectionEnabled: boolean;
+    /** Heartbeat interval (ms) for the second-instance detector when enabled. */
+    secondInstanceHeartbeatIntervalMs: number;
     getNow: () => number;
+    /**
+     * Re-provides the non-serialized per-run `services` value on recovery; `null`
+     * when the engine was created without `resolveWorkflowServices`.
+     */
+    resolveWorkflowServices: EngineOptions['resolveWorkflowServices'] | null;
 }
 export interface WorkflowResultWaiter {
     promise: Promise<unknown>;
@@ -56,4 +65,12 @@ export type QueuedInlineWorkflowExecutionStart = {
     nestingDepth: number;
     executionDeadline: number | undefined;
     executionStateOwnerId: string;
+    /**
+     * Liveness callback invoked once this queued start has actually begun
+     * executing (its generator has been driven). Set only for `defer: false`
+     * launches, which await it before `engine.start()` resolves. Fired exactly
+     * once; a discarded start (engine disposed without draining) settles it via
+     * the dispose path so the `defer: false` awaiter never hangs.
+     */
+    onStarted?: () => void;
 };

package/dist/core/engine/engine-leak-warnings.d.ts

@@ -6,6 +6,12 @@
 export type EngineCleanupIntervalDisposalTracker = {
     disposed: boolean;
     cleanupInterval: ReturnType<typeof setInterval> | null;
+    /**
+     * The optional second-instance detector interval, tracked alongside the
+     * cleanup interval so the same finalizer clears it when an engine is
+     * garbage-collected without `[Symbol.dispose]()`. Null when detection is off.
+     */
+    secondInstanceDetectionInterval: ReturnType<typeof setInterval> | null;
     testToken: symbol | undefined;
 };
 export declare const engineCleanupIntervalFinalizer: FinalizationRegistry<EngineCleanupIntervalDisposalTracker>;

package/dist/core/engine/engine-leak-warnings.js

@@ -6,6 +6,10 @@ export const engineCleanupIntervalFinalizer = new FinalizationRegistry((tracker)
     clearInterval(tracker.cleanupInterval);
     tracker.cleanupInterval = null;
   }
+  if (tracker.secondInstanceDetectionInterval !== null) {
+    clearInterval(tracker.secondInstanceDetectionInterval);
+    tracker.secondInstanceDetectionInterval = null;
+  }
   if (!tracker.disposed && shouldEmitEngineLeakWarning()) {
     if (tracker.testToken !== void 0)
       engineLeakWarningTokensForTesting.add(tracker.testToken);

package/dist/core/engine/engine-runtime-helpers.d.ts

@@ -2,7 +2,24 @@ import type { AnyActivityDefinition } from '../types.ts';
 import { type EngineCleanupIntervalDisposalTracker } from './engine-leak-warnings.ts';
 import type { Engine } from './index.ts';
 import { type EngineInternals } from './internals.ts';
+import type { SecondInstanceDetector } from './second-instance-detector.ts';
 export declare function isActivityDefinition(value: unknown): value is AnyActivityDefinition;
 export declare function createQueuedInlineWorkflowStartHandler<TWorkflows extends object, TActivities extends object>(weakEngine: WeakRef<Engine<TWorkflows, TActivities>>, channel: MessageChannel): () => void;
+/**
+ * Drain pending inline launches for `engine` before teardown. Built with the
+ * same inline-launch-queue callbacks as the scheduled flush handler so a drained
+ * start advances identically to a normally-flushed one. Called from
+ * `[Symbol.asyncDispose]` ahead of synchronous disposal (which aborts the signal
+ * and would otherwise discard the queue).
+ */
+export declare function drainQueuedInlineWorkflowStartsForEngine<TWorkflows extends object, TActivities extends object>(engine: Engine<TWorkflows, TActivities>): Promise<void>;
 export declare function createCleanupIntervalTick<TWorkflows extends object, TActivities extends object>(weakEngine: WeakRef<Engine<TWorkflows, TActivities>>, tracker: EngineCleanupIntervalDisposalTracker): () => void;
+/**
+ * Build the resolver the second-instance detection interval uses to find its live
+ * detector. Returns `null` when the engine has been garbage-collected or disposed
+ * (so the tick is skipped), otherwise the engine's current detector. Extracted
+ * here — like {@link createCleanupIntervalTick} — so the deref/disposed guard is
+ * directly testable without driving a real interval.
+ */
+export declare function createSecondInstanceDetectorResolver<TWorkflows extends object, TActivities extends object>(weakEngine: WeakRef<Engine<TWorkflows, TActivities>>): () => SecondInstanceDetector | null;
 export declare function disposeEngineCleanupInterval(internals: EngineInternals): void;

package/dist/core/engine/engine-runtime-helpers.js

@@ -3,12 +3,22 @@ import { createLifecycleCallbacks, createTerminationCallbacks } from "./callback
 import {
   engineCleanupIntervalFinalizer
 } from "./engine-leak-warnings.js";
-import { flushQueuedInlineWorkflowStarts } from "./inline-launch-queue.js";
+import {
+  drainQueuedInlineWorkflowStarts,
+  flushQueuedInlineWorkflowStarts
+} from "./inline-launch-queue.js";
 import { getInternals } from "./internals.js";
 import { swallowPromiseRejection } from "./strategy-helpers.js";
 export function isActivityDefinition(value) {
   return typeof value === "function" && typeof value.name === "string" && "execute" in value && typeof value.execute === "function";
 }
+function inlineLaunchQueueCallbacksForEngine(engine) {
+  const lifecycleCallbacks = createLifecycleCallbacks(engine);
+  return {
+    processPendingUpdatesAfterInlineAdvance: (workflowId) => lifecycleCallbacks.processPendingUpdatesAfterInlineAdvance(workflowId),
+    swallowPromiseRejection: (promise) => swallowPromiseRejection(promise)
+  };
+}
 export function createQueuedInlineWorkflowStartHandler(weakEngine, channel) {
   return function handleQueuedInlineWorkflowStart() {
     const engine = weakEngine.deref();
@@ -18,12 +28,12 @@ export function createQueuedInlineWorkflowStartHandler(weakEngine, channel) {
       return;
     }
     getInternals(engine).queuedInlineWorkflowStartFlushScheduled = !1;
-    swallowPromiseRejection(flushQueuedInlineWorkflowStarts(getInternals(engine), {
-      processPendingUpdatesAfterInlineAdvance: (workflowId) => createLifecycleCallbacks(engine).processPendingUpdatesAfterInlineAdvance(workflowId),
-      swallowPromiseRejection: (promise) => swallowPromiseRejection(promise)
-    }));
+    swallowPromiseRejection(flushQueuedInlineWorkflowStarts(getInternals(engine), inlineLaunchQueueCallbacksForEngine(engine)));
   };
 }
+export async function drainQueuedInlineWorkflowStartsForEngine(engine) {
+  await drainQueuedInlineWorkflowStarts(getInternals(engine), inlineLaunchQueueCallbacksForEngine(engine));
+}
 export function createCleanupIntervalTick(weakEngine, tracker) {
   return function cleanupExpiredResponsesForLiveEngine() {
     const engine = weakEngine.deref();
@@ -38,6 +48,17 @@ export function createCleanupIntervalTick(weakEngine, tracker) {
     createExpiredResponseCleanupTick(internals.updateCoordinator, (source, error) => createTerminationCallbacks(engine).handleCleanupError(source, error))();
   };
 }
+export function createSecondInstanceDetectorResolver(weakEngine) {
+  return function resolveLiveSecondInstanceDetector() {
+    const engine = weakEngine.deref();
+    if (engine === void 0)
+      return null;
+    const internals = getInternals(engine);
+    if (internals.disposed)
+      return null;
+    return internals.secondInstanceDetector;
+  };
+}
 export function disposeEngineCleanupInterval(internals) {
   if (internals.cleanupInterval !== null) {
     clearInterval(internals.cleanupInterval ?? void 0);

package/dist/core/engine/errors.d.ts

@@ -1,3 +1,4 @@
+import type { WorkflowStatus } from '../types/identity.ts';
 import { WeftError } from '../weft-error.ts';
 /**
  * Thrown by {@link Engine.start} when a workflow with the requested ID already
@@ -186,6 +187,32 @@ export declare class WorkflowNotRegisteredError extends WeftError<'WorkflowNotRe
     readonly workflowType: string;
     constructor(workflowType: string);
 }
+/**
+ * Thrown by {@link Engine.suspend} when invoked on an engine running in worker
+ * execution mode. Suspension parks the live run without aborting it, which the
+ * inline strategy supports directly; a worker run cannot be paused without
+ * sending it a cancellation, so the engine refuses rather than silently
+ * aborting. Suspend/resume in worker mode is a scoped follow-up.
+ *
+ * @example
+ * ```ts
+ * import { Engine, WorkflowSuspendNotSupportedError } from '@lostgradient/weft';
+ *
+ * async function trySuspend(engine: Engine, id: string) {
+ *   try {
+ *     await engine.suspend(id);
+ *   } catch (err) {
+ *     if (err instanceof WorkflowSuspendNotSupportedError) {
+ *       // worker-mode engine: cancel instead, or run inline
+ *     }
+ *   }
+ * }
+ * void trySuspend;
+ * ```
+ */
+export declare class WorkflowSuspendNotSupportedError extends WeftError<'WorkflowSuspendNotSupportedError'> {
+    constructor(message: string);
+}
 /**
  * Thrown when the engine cannot resolve an activity name to a registered
  * function during dispatch. The per-workflow {@link ActivityRegistry} (built
@@ -212,4 +239,51 @@ export declare class ActivityResolutionError extends WeftError<'ActivityResoluti
     readonly activityName: string;
     constructor(workflowType: string, activityName: string);
 }
+/**
+ * Thrown by {@link Engine.startOrSignal} when the target workflow already exists
+ * and is in a terminal state (completed, failed, cancelled, or timed out). A
+ * terminal run cannot accept a signal and must not be silently replaced, so
+ * `startOrSignal` surfaces this conflict instead of starting a fresh run under
+ * the same id or dropping the signal.
+ *
+ * Inspect `workflowId` to identify the conflicting run and `status` to see why
+ * it was rejected. To deliberately start a new run, choose a different id (or
+ * idempotency key); to deliver to a fresh run, terminal-state reuse is not a
+ * supported policy.
+ *
+ * @example
+ * ```ts
+ * import { StartOrSignalConflictError } from '@lostgradient/weft';
+ *
+ * function isTerminalStartOrSignalConflict(error: unknown): boolean {
+ *   return error instanceof StartOrSignalConflictError;
+ * }
+ * ```
+ */
+export declare class StartOrSignalConflictError extends WeftError<'StartOrSignalConflictError'> {
+    readonly workflowId: string;
+    readonly status: WorkflowStatus;
+    constructor(workflowId: string, status: WorkflowStatus);
+}
+/**
+ * Thrown by {@link Engine.start} / {@link Engine.startOrSignal} when an
+ * `idempotencyKey` resolves to a workflow that no longer exists — its run was
+ * purged or bulk-deleted while the durable `start-idem:` mapping (intentionally
+ * not swept on cleanup) lived on. The key is "spent": it can neither return the
+ * gone run nor safely start a fresh one under the same key (a concurrent caller
+ * may still hold the mapping). Use a different idempotency key to start anew.
+ *
+ * @example
+ * ```ts
+ * import { IdempotencyKeyPurgedError } from '@lostgradient/weft';
+ *
+ * function isPurgedIdempotencyKey(error: unknown): boolean {
+ *   return error instanceof IdempotencyKeyPurgedError;
+ * }
+ * ```
+ */
+export declare class IdempotencyKeyPurgedError extends WeftError<'IdempotencyKeyPurgedError'> {
+    readonly workflowId: string;
+    constructor(workflowId: string);
+}
 export { PersistedDataIncompatibleError } from '../persisted-data-incompatible-error.ts';

package/dist/core/engine/errors.js

@@ -78,13 +78,37 @@ export class WorkflowNotRegisteredError extends WeftError {
   }
 }
 
+export class WorkflowSuspendNotSupportedError extends WeftError {
+  constructor(message) {
+    super("WorkflowSuspendNotSupportedError", message);
+  }
+}
+
 export class ActivityResolutionError extends WeftError {
   workflowType;
   activityName;
   constructor(workflowType, activityName) {
-    super("ActivityResolutionError", `No activity registered with name "${activityName}" for workflow type "${workflowType}". Register the activity via \`workflow({ name }).activities({ ... })\` on the workflow that runs it, or via \`engine.register(activityDefinition)\` for the legacy global registry.`);
+    super("ActivityResolutionError", `No activity registered with name "${activityName}" for workflow type "${workflowType}". Register the activity via \`workflow({ name }).activities({ ... })\` on the workflow that runs it, or via \`engine.register(activityDefinition)\` to make it available to every workflow on that engine instance.`);
     this.workflowType = workflowType;
     this.activityName = activityName;
   }
 }
+
+export class StartOrSignalConflictError extends WeftError {
+  workflowId;
+  status;
+  constructor(workflowId, status) {
+    super("StartOrSignalConflictError", `Workflow "${workflowId}" is already in terminal state "${status}" and cannot accept a startOrSignal: a terminal run cannot be signalled and is not replaced. Use a different id or idempotency key to start a new run.`);
+    this.workflowId = workflowId;
+    this.status = status;
+  }
+}
+
+export class IdempotencyKeyPurgedError extends WeftError {
+  workflowId;
+  constructor(workflowId) {
+    super("IdempotencyKeyPurgedError", `The idempotency key maps to workflow "${workflowId}", which no longer exists (it was purged or deleted). Use a different idempotency key to start a new run.`);
+    this.workflowId = workflowId;
+  }
+}
 export { PersistedDataIncompatibleError } from "../persisted-data-incompatible-error.js";

package/dist/core/engine/handle-result.js

@@ -35,7 +35,7 @@ export async function bootstrapWorkflowResultResolver(internals, workflowId, wai
       waiter.reject(Error(`Workflow "${workflowId}" not found in storage`));
       return;
     }
-    if (state.status === "running" || state.status === "pending")
+    if (state.status === "running" || state.status === "pending" || state.status === "suspended")
       return;
     try {
       const result = await loadWorkflowResult(internals, workflowId);