@lostgradient/weft 0.2.1 → 0.3.0

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

@@ -9,19 +9,28 @@ import type { PayloadSizePolicy } from './payload-size-policy.ts';
 import type { Duration, RetentionPolicy } from './retry-retention.ts';
 import type { SearchAttributeHandle, SearchAttributeValue } from './search-attributes.ts';
 import type { Serializer } from './serializer.ts';
+import type { WorkflowServicesResolution, WorkflowServicesResolverInfo } from './services-resolution.ts';
 /**
  * Options accepted by `engine.start(type, input, options?)`.
  *
  * Every field is optional. `id` lets you specify your own workflow ID;
- * `idempotencyKey` enforces single-execution semantics within a window;
- * `executionTimeout` caps wall-clock time; `startAt`/`startAfter` defer
+ * `idempotencyKey` enforces at-most-once starts (a repeated key returns the
+ * existing run instead of starting a second, even after it reaches a terminal
+ * state); `executionTimeout` caps wall-clock time; `startAt`/`startAfter` defer
  * execution; `tags` and `searchAttributes` make the workflow discoverable
- * via filters.
+ * via filters. `id` and `idempotencyKey` are mutually exclusive — idempotency
+ * assigns its own generated id and dedups through the key.
  *
- * `HttpClient.start` forwards `searchAttributes` to the server. It rejects
- * `idempotencyKey` until the HTTP start protocol exposes matching
- * single-execution semantics, so callers do not accidentally rely on a
- * silently dropped option.
+ * The `idempotencyKey` mapping is durable and permanent: it survives the run
+ * reaching a terminal state, so repeat calls keep returning the same handle. When
+ * the workflow record is purged or swept by retention the mapping itself survives
+ * (purge does not touch the `start-idem:` keyspace) but now points at a gone run;
+ * a call with that spent key throws {@link IdempotencyKeyPurgedError} (mapped to
+ * HTTP 409 over REST/JSON-RPC) rather than silently starting a new run.
+ *
+ * Both `LocalClient.start` and `HttpClient.start` forward `idempotencyKey` and
+ * `searchAttributes` to the server, so single-execution semantics hold across
+ * transports. Idempotent start requires a storage backend with `conditionalBatch`.
  *
  * @example Start a delayed workflow with tags and search attributes
  * ```ts
@@ -64,53 +73,19 @@ export interface StartOptions {
      * non-serializable value cannot cross to a Worker.
      */
     services?: unknown;
-}
-/**
- * Result of {@link EngineOptions.resolveWorkflowServices}. An explicit union
- * rather than a nullable return: `'unavailable'` is a deliberate, named outcome
- * (the run's dependencies cannot be rebuilt in this process) that fails just
- * that recovered run — it does not overload the resolved value with a lifecycle
- * signal.
- *
- * @example
- * ```ts
- * import { type WorkflowServicesResolution } from '@lostgradient/weft';
- *
- * const ok: WorkflowServicesResolution = {
- *   status: 'available',
- *   services: { db: { query: () => [] } },
- * };
- * const no: WorkflowServicesResolution = { status: 'unavailable', reason: 'no config' };
- * void ok;
- * void no;
- * ```
- */
-export type WorkflowServicesResolution = {
-    status: 'available';
-    services: unknown;
-} | {
-    status: 'unavailable';
-    reason: string;
-};
-/**
- * Information passed to {@link EngineOptions.resolveWorkflowServices} for each
- * recovered workflow. `input` is the original durable launch input, available
- * at resume time — typically enough to rebuild the run's dependencies (tenant,
- * model, tool registry) without a side table.
- *
- * @example
- * ```ts
- * import { type WorkflowServicesResolverInfo } from '@lostgradient/weft';
- *
- * function describe(info: WorkflowServicesResolverInfo): string {
- *   return `${info.workflowType}/${info.workflowId}`;
- * }
- * ```
- */
-export interface WorkflowServicesResolverInfo {
-    workflowId: string;
-    workflowType: string;
-    input: unknown;
+    /**
+     * When `false`, `engine.start()` resolves only after the workflow has begun
+     * executing (its generator has been driven its first turn), not merely after
+     * the initial state is persisted. The default (`true`) returns a handle as
+     * soon as state is written and queues execution onto a macrotask, so a caller
+     * cannot assume the run is live without a round-trip. Use `defer: false` when a
+     * caller — or a test — must rely on the run being live immediately after
+     * `await engine.start(...)`. If the body throws on its first turn, `start()`
+     * still resolves; observe the failure via `handle.result()`. Inline mode only;
+     * throws at `engine.start()` under `workflowExecutionMode: 'worker'` or with a
+     * delayed start (`startAt`/`startAfter`), neither of which has liveness to await.
+     */
+    defer?: boolean;
 }
 /**
  * Options for {@link Engine.fork}. Controls which checkpoint step to fork
@@ -162,6 +137,25 @@ export interface EngineOptions {
     retention?: RetentionPolicy;
     retentionSweepInterval?: Duration;
     retentionSweepBatchSize?: number;
+    /**
+     * Enable a best-effort, warn-only detector for a SECOND engine instance writing
+     * to the same durable store — a smoke alarm for singleton misconfiguration (an
+     * autoscaler above one replica, or overlapping rolling deploys). Default `false`.
+     * This is **liveness, not fencing**: it never blocks boot, gates recovery, or
+     * prevents duplicate execution — enforce one instance at the infrastructure layer
+     * (one replica + a `Recreate` deploy, or a single systemd unit). When enabled,
+     * each engine writes a periodic heartbeat and warns (`process.emitWarning`) when
+     * it sees another instance's heartbeat advancing while it runs. The periodic
+     * writes are an ongoing cost, so leave it off unless you want the backstop.
+     */
+    detectSecondInstance?: boolean;
+    /**
+     * Heartbeat interval for {@link EngineOptions.detectSecondInstance} (default
+     * `15s`). A foreign heartbeat must advance across two intervals before warning,
+     * so this also sets how long a deploy overlap must last before it warns — keep it
+     * well above your deploy drain window. Ignored when detection is disabled.
+     */
+    secondInstanceHeartbeatInterval?: Duration;
     /**
      * History circuit-breaker thresholds. When `history.maxEvents` is set, a
      * workflow whose event-log record count would exceed it is forced to a

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

@@ -54,7 +54,8 @@ export type ReviewStatus = 'pending' | 'completed';
  * Filter accepted by `engine.listReviews(filter?)` and the `/v1/reviews`
  * transport surfaces.
  *
- * Omitting `status` preserves the legacy pending-only behavior.
+ * Omitting `status` lists pending reviews; pass `status: 'completed'` to list
+ * completed reviews instead.
  *
  * @example
  * ```ts

package/dist/core/types/services-resolution.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Result of {@link EngineOptions.resolveWorkflowServices}. An explicit union
+ * rather than a nullable return: `'unavailable'` is a deliberate, named outcome
+ * (the run's dependencies cannot be rebuilt in this process) that fails just
+ * that recovered run — it does not overload the resolved value with a lifecycle
+ * signal.
+ *
+ * @example
+ * ```ts
+ * import { type WorkflowServicesResolution } from '@lostgradient/weft';
+ *
+ * const ok: WorkflowServicesResolution = {
+ *   status: 'available',
+ *   services: { db: { query: () => [] } },
+ * };
+ * const no: WorkflowServicesResolution = { status: 'unavailable', reason: 'no config' };
+ * void ok;
+ * void no;
+ * ```
+ */
+export type WorkflowServicesResolution = {
+    status: 'available';
+    services: unknown;
+} | {
+    status: 'unavailable';
+    reason: string;
+};
+/**
+ * Information passed to {@link EngineOptions.resolveWorkflowServices} for each
+ * recovered workflow. `input` is the original durable launch input, available
+ * at resume time — typically enough to rebuild the run's dependencies (tenant,
+ * model, tool registry) without a side table.
+ *
+ * @example
+ * ```ts
+ * import { type WorkflowServicesResolverInfo } from '@lostgradient/weft';
+ *
+ * function describe(info: WorkflowServicesResolverInfo): string {
+ *   return `${info.workflowType}/${info.workflowId}`;
+ * }
+ * ```
+ */
+export interface WorkflowServicesResolverInfo {
+    workflowId: string;
+    workflowType: string;
+    input: unknown;
+}

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

@@ -42,7 +42,17 @@ export interface WorkflowState {
      * leaves this `undefined`).
      */
     terminationReason?: TerminationReason;
-    version: string;
+    /**
+     * The `(workflowVersion, agentVersion?, toolVersions?)` tuple captured for
+     * this workflow. This is the single canonical representation of version
+     * metadata on the state: it shares the {@link WorkflowVersionTuple} shape the
+     * event log records, so the two cannot drift, and it is rewritten on every
+     * versioned persist. `workflowVersion` is always present;
+     * `agentVersion`/`toolVersions` are present only when the workflow declares
+     * them. Resuming compares this against the currently registered definition to
+     * detect version drift.
+     */
+    versionTuple: WorkflowVersionTuple;
     /**
      * Owner identifier for execution-scoped durable state. Top-level workflows
      * own their own execution state; durable child workflows inherit the
@@ -50,16 +60,6 @@ export interface WorkflowState {
      * tree.
      */
     executionStateOwnerId?: string;
-    /**
-     * Legacy version tuple metadata retained so existing persisted workflow
-     * states can still be decoded and compared during recovery.
-     */
-    agentVersion?: string;
-    /**
-     * Legacy version tuple metadata retained so existing persisted workflow
-     * states can still be decoded and compared during recovery.
-     */
-    toolVersions?: string[];
     createdAt: number;
     startedAt?: number;
     updatedAt: number;

package/dist/core/types/workflow-builder.d.ts

@@ -47,10 +47,11 @@ export type WorkflowGenerator<TInput, TOutput, TActivities extends ActivityMap,
  * `TSearchAttributes`), and the builder threads its normalised maps through
  * this alias so `.execute(fn)` sees the right `ctx` shape inside `fn`.
  *
- * Legacy bare-`WorkflowContext` callers continue to typecheck because the
- * interface's generics all default to empty/permissive shapes, so the typed
- * overloads de-prioritise to `never` and existing string-name/callable
- * overloads still match.
+ * Bare-`WorkflowContext` callers (no declared activity/signal/etc. maps)
+ * typecheck because the interface's generics all default to permissive shapes:
+ * the typed overloads de-prioritise to `never` and the dynamic string-name /
+ * callable overloads match instead. This permissive path is current API — it is
+ * how untyped, ad-hoc-name authoring is supported, not a compatibility shim.
  */
 export type WorkflowContextOf<TActivities extends ActivityMap = ActivityMap, TSignals extends SignalMap = SignalMap, TUpdates extends UpdateMap = UpdateMap, TQueries extends QueryMap = QueryMap, TSearchAttributes extends SearchAttributeSchema = SearchAttributeSchema> = WorkflowContext<TActivities, TSignals, TUpdates, TQueries, TSearchAttributes>;
 /**

package/dist/core/types/workflow-function.d.ts

@@ -54,6 +54,23 @@ export type WorkflowFunction<TInput = unknown, TOutput = unknown> = (context: Wo
 export interface StepWorkflowContext {
     readonly workflowId: string;
     readonly signal: AbortSignal;
+    /**
+     * Run `fn` as a durable step. Each call routes through the same machinery as
+     * `ctx.run(...)`: the engine assigns a positional replay slot, persists the
+     * result to the checkpoint, and on crash recovery returns the stored result
+     * without re-running `fn`. `name` is the durable activity label (timeline and
+     * diagnostics only) — replay is keyed by position, not by name.
+     *
+     * Because durability is positional, you must `await` each step before
+     * starting the next: steps must be queued in a deterministic order so the
+     * original run and a recovered run agree on which slot is which. Firing steps
+     * concurrently (so a continuation enqueues further steps in completion order)
+     * can return a wrong cached value after a crash. For parallelism, durable
+     * timers, or signals, use the generator API instead.
+     *
+     * Requires `workflowExecutionMode: 'inline'` (the default); the worker
+     * execution strategy has no step machinery and throws an actionable error.
+     */
     step<T>(name: string, fn: () => Promise<T> | T): Promise<T>;
 }
 /**

package/dist/core/types/workflow-snapshot.d.ts

@@ -0,0 +1,29 @@
+import type { WorkflowStatus } from './identity.ts';
+/**
+ * A point-in-time view of a workflow's progress, returned by
+ * {@link WorkflowHandle.snapshot}. Combines the persisted status with the
+ * current checkpoint step (the run's cursor), so a caller — typically after
+ * `engine.recoverAll()` — can rebuild its own progress adapter for a recovered
+ * run and re-register it on a live surface, without awaiting the run's final
+ * result.
+ *
+ * `step` is the run's current checkpoint step: the number of generator turns it
+ * has advanced. For a run live in this engine it reflects the latest in-memory
+ * checkpoint (which may be one step ahead of the last durable commit); for a
+ * run inspected or recovered in a fresh process it reflects the durably
+ * persisted checkpoint. It is `0` for a run that has its initial checkpoint but
+ * has not yet advanced, and increases as the run makes progress.
+ *
+ * @example
+ * ```ts
+ * import { type WorkflowSnapshot } from '@lostgradient/weft';
+ *
+ * function describe(snapshot: WorkflowSnapshot): string {
+ *   return `${snapshot.status} @ step ${snapshot.step}`;
+ * }
+ * ```
+ */
+export interface WorkflowSnapshot {
+    status: WorkflowStatus;
+    step: number;
+}

package/dist/core/types.d.ts

@@ -7,6 +7,7 @@ export * from './types/definition-schema-to-json.ts';
 export * from './types/definition-schema.ts';
 export * from './types/history-policy.ts';
 export * from './types/identity.ts';
+export * from './types/launch-metadata.ts';
 export * from './types/message-handles.ts';
 export * from './types/options.ts';
 export * from './types/payload-size-policy.ts';
@@ -15,6 +16,7 @@ export * from './types/reviews.ts';
 export * from './types/schedules.ts';
 export * from './types/search-attributes.ts';
 export * from './types/serializer.ts';
+export * from './types/services-resolution.ts';
 export * from './types/standard-schema-validate.ts';
 export * from './types/state.ts';
 export * from './types/workflow-builder-helpers.ts';
@@ -24,3 +26,4 @@ export * from './types/workflow-context.ts';
 export * from './types/workflow-function.ts';
 export * from './types/workflow-registries.ts';
 export * from './types/workflow-registry.ts';
+export * from './types/workflow-snapshot.ts';

package/dist/core/types.js

@@ -7,6 +7,7 @@ export * from "./types/definition-schema-to-json.js";
 export * from "./types/definition-schema.js";
 export * from "./types/history-policy.js";
 export * from "./types/identity.js";
+export * from "./types/launch-metadata.js";
 export * from "./types/message-handles.js";
 export * from "./types/options.js";
 export * from "./types/payload-size-policy.js";
@@ -15,6 +16,7 @@ export * from "./types/reviews.js";
 export * from "./types/schedules.js";
 export * from "./types/search-attributes.js";
 export * from "./types/serializer.js";
+export * from "./types/services-resolution.js";
 export * from "./types/standard-schema-validate.js";
 export * from "./types/state.js";
 export * from "./types/workflow-builder-helpers.js";
@@ -24,3 +26,4 @@ export * from "./types/workflow-context.js";
 export * from "./types/workflow-function.js";
 export * from "./types/workflow-registries.js";
 export * from "./types/workflow-registry.js";
+export * from "./types/workflow-snapshot.js";

package/dist/core/weft-error.d.ts

@@ -22,7 +22,7 @@
  * }
  * ```
  */
-export type WeftErrorCode = 'WorkflowAlreadyExistsError' | 'BulkDeleteRequiresTerminalWorkflowsError' | 'BulkOperationConfirmationError' | 'WorkflowTypeNotRegisteredForRecoveryError' | 'EngineCreateNameMismatchError' | 'EngineDisposedError' | 'WorkflowNotFoundError' | 'WorkflowNotRegisteredError' | 'ActivityResolutionError' | 'PersistedDataIncompatibleError' | 'WorkflowTimeoutError' | 'HttpClientError' | 'WorkerProtocolIncompatibleError' | 'UpdateTimeoutError' | 'UpdateValidationError' | 'WorkflowTerminalError' | 'WorkflowBuilderError' | 'VersionMismatchError' | 'EffectReplayConflictError' | 'ReviewTimeoutError' | 'AtomicStateConflictError' | 'StandardSchemaValidationError' | 'ActivityReconciliationCapabilityError' | 'ActivityReconciliationConflictError' | 'ActivityReconciliationIndeterminateError' | 'AsyncActivityTokenNotFoundError' | 'PayloadSizeExceededError';
+export type WeftErrorCode = 'WorkflowAlreadyExistsError' | 'BulkDeleteRequiresTerminalWorkflowsError' | 'BulkOperationConfirmationError' | 'WorkflowTypeNotRegisteredForRecoveryError' | 'EngineCreateNameMismatchError' | 'EngineDisposedError' | 'WorkflowNotFoundError' | 'WorkflowNotRegisteredError' | 'ActivityResolutionError' | 'PersistedDataIncompatibleError' | 'WorkflowTimeoutError' | 'HttpClientError' | 'WorkerProtocolIncompatibleError' | 'UpdateTimeoutError' | 'UpdateValidationError' | 'WorkflowTerminalError' | 'WorkflowBuilderError' | 'VersionMismatchError' | 'EffectReplayConflictError' | 'ReviewTimeoutError' | 'AtomicStateConflictError' | 'StandardSchemaValidationError' | 'ActivityReconciliationCapabilityError' | 'ActivityReconciliationConflictError' | 'ActivityReconciliationIndeterminateError' | 'AsyncActivityTokenNotFoundError' | 'PayloadSizeExceededError' | 'StartOrSignalConflictError' | 'IdempotencyKeyPurgedError';
 /**
  * Generic abstract base for all Weft library errors. The `TCode` parameter
  * makes each subclass's `code` its own literal type; the exported base surface

package/dist/core/weft-error.js

@@ -33,7 +33,9 @@ const publicWeftErrorCodeMap = {
   ActivityReconciliationConflictError: !0,
   ActivityReconciliationIndeterminateError: !0,
   AsyncActivityTokenNotFoundError: !0,
-  PayloadSizeExceededError: !0
+  PayloadSizeExceededError: !0,
+  StartOrSignalConflictError: !0,
+  IdempotencyKeyPurgedError: !0
 }, PUBLIC_WEFT_ERROR_CODES = new Set(Object.keys(publicWeftErrorCodeMap));
 export function isWeftError(value) {
   return value instanceof WeftError;

package/dist/diagnostics/doctor.js

@@ -1,4 +1,6 @@
 import { decode } from "../core/codec.js";
+import { decodeWorkflowState } from "../core/engine/validation.js";
+import { isTopLevelWorkflowStateKey } from "../core/engine/workflow-state-stream.js";
 import { fileSize } from "../runtime/portable.js";
 import { KEYS } from "../storage/interface.js";
 import { generateRecommendations } from "./recommendations.js";
@@ -89,13 +91,14 @@ async function aggregateWorkflowScan(storage, now) {
     completed: 0,
     failed: 0,
     cancelled: 0,
-    timedOut: 0
+    timedOut: 0,
+    suspended: 0
   };
   let total = 0, longestRunning = null, earliestCreatedAt = 1 / 0;
   for await (const [key, value] of storage.scan("wf:")) {
-    if (key.includes(":ckpt"))
+    if (!isTopLevelWorkflowStateKey(key))
       continue;
-    const state = decode(value);
+    const state = decodeWorkflowState(value);
     total++;
     statusCounts[mapStatusKey(state.status)]++;
     if (state.status === "running" && state.createdAt < earliestCreatedAt) {

package/dist/diagnostics/format.js

@@ -47,8 +47,8 @@ function appendWorkflowsSection(lines, workflows) {
     lines.push("  Total: 0 (no workflows)");
     return;
   }
-  const counts = workflows.statusCounts;
-  lines.push(`  Total: ${workflows.total} (${counts.running} running, ${counts.completed} completed, ${counts.failed} failed)`);
+  const counts = workflows.statusCounts, suspendedSummary = counts.suspended > 0 ? `, ${counts.suspended} suspended` : "";
+  lines.push(`  Total: ${workflows.total} (${counts.running} running, ${counts.completed} completed, ${counts.failed} failed${suspendedSummary})`);
   if (workflows.longestRunning) {
     const longest = workflows.longestRunning;
     lines.push(`  Longest running: ${longest.id} (started ${formatDuration(longest.elapsedMilliseconds)} ago, step ${longest.currentStep})`);

package/dist/diagnostics/types.d.ts

@@ -48,6 +48,7 @@ export interface WorkflowStatusCounts {
     failed: number;
     cancelled: number;
     timedOut: number;
+    suspended: number;
 }
 /**
  * Identity and elapsed wall-clock time of the longest-running workflow in

package/dist/diagnostics/version-check.js

@@ -1,20 +1,22 @@
-import { decode } from "../core/codec.js";
+import { decodeWorkflowState } from "../core/engine/validation.js";
+import { isTopLevelWorkflowStateKey } from "../core/engine/workflow-state-stream.js";
 import { DEFAULT_WORKFLOW_VERSION, checkVersionCompatibility } from "../core/versioning.js";
 async function groupActiveWorkflowsByType(storage) {
   const groups = new Map;
   for await (const [key, bytes] of storage.scan("wf:")) {
-    if (key.includes(":ckpt"))
+    if (!isTopLevelWorkflowStateKey(key))
       continue;
-    const state = decode(bytes);
+    const state = decodeWorkflowState(bytes);
     if (state.status !== "running" && state.status !== "pending")
       continue;
+    const storedVersion = state.versionTuple.workflowVersion;
     let group = groups.get(state.type);
     if (!group) {
       group = { count: 0, versionCounts: new Map };
       groups.set(state.type, group);
     }
     group.count++;
-    group.versionCounts.set(state.version, (group.versionCounts.get(state.version) ?? 0) + 1);
+    group.versionCounts.set(storedVersion, (group.versionCounts.get(storedVersion) ?? 0) + 1);
   }
   return groups;
 }

package/dist/index.d.ts

@@ -20,13 +20,13 @@ export { WeftError, isWeftError, isWeftErrorCode, isWeftErrorLike } from './core
 export type { WeftErrorCode } from './core/weft-error.ts';
 export { FAULT_CODE_TO_FAILURE_CATEGORY, failureCategoryForFaultCode, isFaultCode, } from './core/fault-code.ts';
 export type { FaultCode } from './core/fault-code.ts';
-export { ActivityReconciliationCapabilityError, ActivityReconciliationConflictError, ActivityReconciliationIndeterminateError, ActivityResolutionError, AsyncActivityTokenNotFoundError, BulkDeleteRequiresTerminalWorkflowsError, BulkOperationConfirmationError, Engine, EngineCreateNameMismatchError, EngineDisposedError, PersistedDataIncompatibleError, ScheduleHandle, WorkflowAlreadyExistsError, WorkflowHandle, WorkflowNotFoundError, WorkflowNotRegisteredError, WorkflowTypeNotRegisteredForRecoveryError, } from './core/engine';
+export { ActivityReconciliationCapabilityError, ActivityReconciliationConflictError, ActivityReconciliationIndeterminateError, ActivityResolutionError, AsyncActivityTokenNotFoundError, BulkDeleteRequiresTerminalWorkflowsError, BulkOperationConfirmationError, Engine, EngineCreateNameMismatchError, EngineDisposedError, IdempotencyKeyPurgedError, PersistedDataIncompatibleError, ScheduleHandle, StartOrSignalConflictError, WorkflowAlreadyExistsError, WorkflowHandle, WorkflowNotFoundError, WorkflowNotRegisteredError, WorkflowSuspendNotSupportedError, WorkflowTypeNotRegisteredForRecoveryError, } from './core/engine';
 export type { EngineCreateOptions, EngineStateNamespace, RecoverAllOptions } from './core/engine';
 export { DEFAULT_CHECKPOINT_SIZE_WARNING_THRESHOLD, DEFAULT_MAX_NESTING_DEPTH, DEFAULT_RETRY_POLICY, DEFAULT_VISIBILITY_TIMEOUT_MS, HISTORY_CIRCUIT_BREAKER_REASON, WorkflowBuilderError, query, schedule, signal, update, workflow, } from './core/types';
-export type { ActivityArgsFor, ActivityCallOptions, ActivityCallable, ActivityContext, ActivityDefinition, ActivityEntryInput, ActivityFunction, ActivityMap, ActivityMapInput, ActivityObjectInput, ActivityResultFor, ActivityVerificationContext, ActivityVerificationPhase, ActivityVerificationResult, AnyActivityDefinition, AnyWorkflowDefinition, ArchiveAdapter, BuilderState, BuiltWorkflowDefinition, BulkCancelResult, BulkDeleteResult, BulkOperationAction, BulkOperationAuditEvent, BulkOperationCommitOptions, BulkOperationDryRunOptions, BulkOperationDryRunResult, BulkOperationError, BulkOperationFilterSummary, BulkOperationOptions, BulkOperationPrincipal, BulkOperationScopeSummary, BulkSignalAllCommitOptions, BulkSignalAllDryRunOptions, BulkSignalAllOptions, BulkSignalResult, BulkTagResult, Checkpoint, CheckpointState, CheckpointSummary, CompletedReviewEntry, CoordinatedUpdateResult, DefinitionSchema, Duration, EngineOptions, FailureCategory, ForkLineage, ForkOptions, HistoryPolicy, InferActivityEntries, InferActivityEntry, InferWorkflowEntries, InferWorkflowEntry, InitialBuilderState, ListFilter, ListOptions, MarkBuilderState, NormalizeActivities, NormalizedActivityEntry, NormalizedRetentionPolicy, PaginatedResult, PayloadSizePolicy, PendingReviewEntry, PurgeResult, QueryDefinition, QueryMap, QueryShape, RegisteredWorkflowDefinition, RetentionOverview, RetentionPolicy, RetryPolicy, ReviewListEntry, ReviewListFilter, ReviewStatus, ScheduleDefinition, ScheduleFilter, ScheduleOptions, ScheduleOverlapPolicy, ScheduleSpec, ScheduleState, ScheduleStatus, ScheduleSummary, SearchAttributeDefinition, SearchAttributeHandle, SearchAttributeSchema, SearchAttributeValue, Serializer, SignalDefinition, SignalDeliveryOptions, SignalMap, SignalPayload, StartOptions, SubmitReviewOptions, TerminationReason, UpdateDefinition, UpdateMap, UpdatePayload, WorkerReplayOperationFailure, WorkerReplayOperationSignature, WorkflowAlreadyRegistered, WorkflowAtomicState, WorkflowAtomicStateOptions, WorkflowBuilder, WorkflowBuilderOptions, WorkflowContext, WorkflowDefinition, WorkflowEvent, WorkflowFunction, WorkflowGenerator, WorkflowId, WorkflowRegistry, WorkflowReplay, WorkflowServicesResolution, WorkflowServicesResolverInfo, WorkflowSessionState, WorkflowState, WorkflowStateNamespace, WorkflowStatus, WorkflowSummary, WorkflowTimelineEntry, WorkflowTimelineStatus, WorkflowTypeRetentionPolicy, } from './core/types';
+export type { ActivityArgsFor, ActivityCallOptions, ActivityCallable, ActivityContext, ActivityDefinition, ActivityEntryInput, ActivityFunction, ActivityMap, ActivityMapInput, ActivityObjectInput, ActivityResultFor, ActivityVerificationContext, ActivityVerificationPhase, ActivityVerificationResult, AnyActivityDefinition, AnyWorkflowDefinition, ArchiveAdapter, BuilderState, BuiltWorkflowDefinition, BulkCancelResult, BulkDeleteResult, BulkOperationAction, BulkOperationAuditEvent, BulkOperationCommitOptions, BulkOperationDryRunOptions, BulkOperationDryRunResult, BulkOperationError, BulkOperationFilterSummary, BulkOperationOptions, BulkOperationPrincipal, BulkOperationScopeSummary, BulkSignalAllCommitOptions, BulkSignalAllDryRunOptions, BulkSignalAllOptions, BulkSignalResult, BulkTagResult, Checkpoint, CheckpointState, CheckpointSummary, CompletedReviewEntry, CoordinatedUpdateResult, DefinitionSchema, Duration, EngineOptions, FailureCategory, ForkLineage, ForkOptions, HistoryPolicy, InferActivityEntries, InferActivityEntry, InferWorkflowEntries, InferWorkflowEntry, InitialBuilderState, LaunchMetadata, ListFilter, ListOptions, MarkBuilderState, NormalizeActivities, NormalizedActivityEntry, NormalizedRetentionPolicy, PaginatedResult, PayloadSizePolicy, PendingReviewEntry, PurgeResult, QueryDefinition, QueryMap, QueryShape, RegisteredWorkflowDefinition, RetentionOverview, RetentionPolicy, RetryPolicy, ReviewListEntry, ReviewListFilter, ReviewStatus, ScheduleDefinition, ScheduleFilter, ScheduleOptions, ScheduleOverlapPolicy, ScheduleSpec, ScheduleState, ScheduleStatus, ScheduleSummary, SearchAttributeDefinition, SearchAttributeHandle, SearchAttributeSchema, SearchAttributeValue, Serializer, SignalDefinition, SignalDeliveryOptions, SignalMap, SignalPayload, StartOptions, StartOrSignalSignal, SubmitReviewOptions, TerminationReason, UpdateDefinition, UpdateMap, UpdatePayload, WorkerReplayOperationFailure, WorkerReplayOperationSignature, WorkflowAlreadyRegistered, WorkflowAtomicState, WorkflowAtomicStateOptions, WorkflowBuilder, WorkflowBuilderOptions, WorkflowContext, WorkflowDefinition, WorkflowEvent, WorkflowFunction, WorkflowGenerator, WorkflowId, WorkflowRegistry, WorkflowReplay, WorkflowServicesResolution, WorkflowServicesResolverInfo, WorkflowSessionState, WorkflowSnapshot, WorkflowState, WorkflowStateNamespace, WorkflowStatus, WorkflowSummary, WorkflowTimelineEntry, WorkflowTimelineStatus, WorkflowTypeRetentionPolicy, } from './core/types';
 export { AlertManager } from './alerting/index';
 export type { AlertAction, AlertMetric, AlertRule, AlertState, AlertStatus, AlertingOptions, WebhookTarget, } from './alerting/types';
-export { ActivityAsyncPendingEvent, ActivityCompletedEvent, ActivityFailedEvent, ActivityStartedEvent, AlertFiredEvent, AlertResolvedEvent, AttributesChangedEvent, CheckpointSizeWarningEvent, ConstraintViolatedEvent, DevelopmentWarningEvent, SignalDeliveredEvent, SignalReceivedEvent, StorageSizeReportedEvent, UpdateCompletedEvent, UpdateReceivedEvent, WorkflowCancelledEvent, WorkflowCompletedEvent, WorkflowFailedEvent, WorkflowRecoverySkippedEvent, WorkflowResumedEvent, WorkflowStartedEvent, WorkflowTimedOutEvent, } from './core/events';
+export { ActivityAsyncPendingEvent, ActivityCompletedEvent, ActivityFailedEvent, ActivityStartedEvent, AlertFiredEvent, AlertResolvedEvent, AttributesChangedEvent, CheckpointSizeWarningEvent, ConstraintViolatedEvent, DevelopmentWarningEvent, SignalDeliveredEvent, SignalReceivedEvent, StorageSizeReportedEvent, UpdateCompletedEvent, UpdateReceivedEvent, WorkflowCancelledEvent, WorkflowCompletedEvent, WorkflowFailedEvent, WorkflowRecoverySkippedEvent, WorkflowResumedEvent, WorkflowStartedEvent, WorkflowSuspendedEvent, WorkflowTimedOutEvent, } from './core/events';
 export type { TypedEventTarget, WeftEventMap, WorkflowRecoverySkippedReason } from './core/events';
 export { detectRuntime, hashBytes, hashString, sleep } from './runtime/portable';
 export type { RuntimeKind } from './runtime/portable';
@@ -43,7 +43,7 @@ export { copyTextKeyValueRowsToStorage } from './storage/text-value-import';
 export type { CopyTextKeyValueRowsToStorageOptions, CopyTextKeyValueRowsToStorageResult, TextKeyValueRow, } from './storage/text-value-import';
 export { jsonCodec, msgpackCodec, withCodec } from './storage/typed-storage';
 export type { CodecStorageOptions, MessagePackValue, StorageCodec, StorageValueParser, TypedBatchOperation, TypedConditionalBatchCondition, TypedStorage, } from './storage/typed-storage';
-export { decode, encode, validateCloneable } from './core/codec';
+export { decode, encode, registerSerializer, validateCloneable, type SerializerHandlers, } from './core/codec';
 export { PayloadSizeExceededError } from './core/payload-size';
 export { advanceCheckpoint, checkpointSizeBytes, createCheckpoint, deserializeCheckpoint, serializeCheckpoint, } from './core/checkpoint';
 export { Scheduler, calculateBackoff, parseDuration } from './core/scheduler';

package/dist/index.js

@@ -16,12 +16,15 @@ export {
   Engine,
   EngineCreateNameMismatchError,
   EngineDisposedError,
+  IdempotencyKeyPurgedError,
   PersistedDataIncompatibleError,
   ScheduleHandle,
+  StartOrSignalConflictError,
   WorkflowAlreadyExistsError,
   WorkflowHandle,
   WorkflowNotFoundError,
   WorkflowNotRegisteredError,
+  WorkflowSuspendNotSupportedError,
   WorkflowTypeNotRegisteredForRecoveryError
 } from "./core/engine.js";
 export {
@@ -60,6 +63,7 @@ export {
   WorkflowRecoverySkippedEvent,
   WorkflowResumedEvent,
   WorkflowStartedEvent,
+  WorkflowSuspendedEvent,
   WorkflowTimedOutEvent
 } from "./core/events.js";
 export { detectRuntime, hashBytes, hashString, sleep } from "./runtime/portable.js";
@@ -78,7 +82,12 @@ export { MemoryStorage } from "./storage/memory.js";
 export { ScopedStorage, scopedStorage } from "./storage/scoped-storage.js";
 export { copyTextKeyValueRowsToStorage } from "./storage/text-value-import.js";
 export { jsonCodec, msgpackCodec, withCodec } from "./storage/typed-storage.js";
-export { decode, encode, validateCloneable } from "./core/codec.js";
+export {
+  decode,
+  encode,
+  registerSerializer,
+  validateCloneable
+} from "./core/codec.js";
 export { PayloadSizeExceededError } from "./core/payload-size.js";
 export {
   advanceCheckpoint,

package/dist/json-schema.js

@@ -1,4 +1,4 @@
 // @bun
-var w=Object.defineProperty;var y=(j)=>j;function B(j,q){this[j]=y.bind(null,q)}var T=(j,q)=>{for(var z in q)w(j,z,{get:q[z],enumerable:!0,configurable:!0,set:B.bind(q,z)})};var X=(j,q)=>()=>(j&&(q=j(j=0)),q);var K,D,_;var Y=X(()=>{K=class K extends Error{code;constructor(j,q,z){super(q,z);this.code=j,this.name=j}};D={WorkflowAlreadyExistsError:!0,BulkDeleteRequiresTerminalWorkflowsError:!0,BulkOperationConfirmationError:!0,WorkflowTypeNotRegisteredForRecoveryError:!0,EngineCreateNameMismatchError:!0,EngineDisposedError:!0,WorkflowNotFoundError:!0,WorkflowNotRegisteredError:!0,ActivityResolutionError:!0,PersistedDataIncompatibleError:!0,WorkflowTimeoutError:!0,HttpClientError:!0,WorkerProtocolIncompatibleError:!0,UpdateTimeoutError:!0,UpdateValidationError:!0,WorkflowTerminalError:!0,WorkflowBuilderError:!0,VersionMismatchError:!0,EffectReplayConflictError:!0,ReviewTimeoutError:!0,AtomicStateConflictError:!0,StandardSchemaValidationError:!0,ActivityReconciliationCapabilityError:!0,ActivityReconciliationConflictError:!0,ActivityReconciliationIndeterminateError:!0,AsyncActivityTokenNotFoundError:!0,PayloadSizeExceededError:!0},_=new Set(Object.keys(D))});async function Z(j,q,z){let G=j["~standard"];if(!L(G))throw TypeError(`Schema for ${z.fieldName} does not provide runtime validation. Attach a Standard Schema validator (Zod, Valibot, or another vendor) or supply a runtime-validating schema at this boundary.`);let H=await G.validate(q);if(H.issues===void 0)return H.value;throw new A({fieldName:z.fieldName,operation:z.operation,issues:H.issues.map(U)})}function Q(j){return j.map((q)=>q.path===""?q.message:`${q.path}: ${q.message}`).join(`
+var w=Object.defineProperty;var y=(j)=>j;function B(j,q){this[j]=y.bind(null,q)}var T=(j,q)=>{for(var z in q)w(j,z,{get:q[z],enumerable:!0,configurable:!0,set:B.bind(q,z)})};var X=(j,q)=>()=>(j&&(q=j(j=0)),q);var K,D,_;var Y=X(()=>{K=class K extends Error{code;constructor(j,q,z){super(q,z);this.code=j,this.name=j}};D={WorkflowAlreadyExistsError:!0,BulkDeleteRequiresTerminalWorkflowsError:!0,BulkOperationConfirmationError:!0,WorkflowTypeNotRegisteredForRecoveryError:!0,EngineCreateNameMismatchError:!0,EngineDisposedError:!0,WorkflowNotFoundError:!0,WorkflowNotRegisteredError:!0,ActivityResolutionError:!0,PersistedDataIncompatibleError:!0,WorkflowTimeoutError:!0,HttpClientError:!0,WorkerProtocolIncompatibleError:!0,UpdateTimeoutError:!0,UpdateValidationError:!0,WorkflowTerminalError:!0,WorkflowBuilderError:!0,VersionMismatchError:!0,EffectReplayConflictError:!0,ReviewTimeoutError:!0,AtomicStateConflictError:!0,StandardSchemaValidationError:!0,ActivityReconciliationCapabilityError:!0,ActivityReconciliationConflictError:!0,ActivityReconciliationIndeterminateError:!0,AsyncActivityTokenNotFoundError:!0,PayloadSizeExceededError:!0,StartOrSignalConflictError:!0,IdempotencyKeyPurgedError:!0},_=new Set(Object.keys(D))});async function Z(j,q,z){let G=j["~standard"];if(!L(G))throw TypeError(`Schema for ${z.fieldName} does not provide runtime validation. Attach a Standard Schema validator (Zod, Valibot, or another vendor) or supply a runtime-validating schema at this boundary.`);let H=await G.validate(q);if(H.issues===void 0)return H.value;throw new A({fieldName:z.fieldName,operation:z.operation,issues:H.issues.map(U)})}function Q(j){return j.map((q)=>q.path===""?q.message:`${q.path}: ${q.message}`).join(`
 `)}function L(j){return typeof j.validate==="function"}function U(j){return{message:j.message,path:b(j.path)}}function b(j){if(j===void 0||j.length===0)return"";let q="";for(let z of j)q+="/",q+=F(z);return q}function F(j){let q=J(j)?j.key:j;return M(String(q))}function J(j){return j!==null&&typeof j==="object"&&"key"in j}function M(j){return j.replace(/~/g,"~0").replace(/\//g,"~1")}function O(j,q,z){return`Validation failed for ${q===void 0?j:`${q} ${j}`}:
 ${Q(z)}`}var A;var $=X(()=>{Y();A=class A extends K{fieldName;operation;issues;constructor(j){super("StandardSchemaValidationError",O(j.fieldName,j.operation,j.issues));this.fieldName=j.fieldName,this.operation=j.operation,this.issues=j.issues}}});$();var V=Q,P=A,W=Z;export{W as validateStandardSchema,V as formatStandardSchemaIssues,P as StandardSchemaValidationError};