@lostgradient/weft 0.2.1 → 0.3.0

package/dist/client/handle-delegation.d.ts

@@ -4,6 +4,8 @@ import type { WorkflowEventTail } from './event-tail.ts';
 import type { ClientHandle, ClientScheduleHandle } from './interface.ts';
 export interface WorkflowHandleDelegationClient {
     cancel(id: string): Promise<void>;
+    suspend(id: string): Promise<void>;
+    resume(id: string): Promise<ClientHandle>;
     tail(id: string): WorkflowEventTail;
     signal(id: string, name: string, payload?: unknown, options?: SignalDeliveryOptions): Promise<void>;
     update(id: string, name: string, payload?: unknown, options?: {
@@ -21,6 +23,8 @@ export declare abstract class WorkflowHandleDelegation<TClient extends WorkflowH
     constructor(id: string, client: TClient);
     abstract result(): Promise<unknown>;
     cancel(): Promise<void>;
+    suspend(): Promise<void>;
+    resume(): Promise<void>;
     signal(name: SignalDefinition): Promise<void>;
     signal<TInput>(name: SignalDefinition<TInput>, payload: TInput, options?: SignalDeliveryOptions): Promise<void>;
     signal(name: string, payload?: unknown, options?: SignalDeliveryOptions): Promise<void>;

package/dist/client/handle-delegation.js

@@ -10,6 +10,12 @@ export class WorkflowHandleDelegation {
   async cancel() {
     return this.client.cancel(this.id);
   }
+  async suspend() {
+    return this.client.suspend(this.id);
+  }
+  async resume() {
+    await this.client.resume(this.id);
+  }
   async signal(nameOrDefinition, payload, options) {
     if (options === void 0)
       return this.client.signal(this.id, messageName(nameOrDefinition), payload);

package/dist/client/http-client-requests.d.ts

@@ -50,6 +50,8 @@ export declare function getScheduleRequest(context: HttpClientRequestContext, id
 export declare function cancelWorkflowRequest(context: HttpClientRequestContext, id: string): Promise<void>;
 /** Force-timeout a workflow (`POST /v1/workflows/:id/timeout`). */
 export declare function timeoutWorkflowRequest(context: HttpClientRequestContext, id: string): Promise<void>;
+/** Suspend a running workflow (`POST /v1/workflows/:id/suspend`). */
+export declare function suspendWorkflowRequest(context: HttpClientRequestContext, id: string): Promise<void>;
 /** Pause a recurring schedule (`POST /v1/schedules/:id/pause`). */
 export declare function pauseScheduleRequest(context: HttpClientRequestContext, id: string): Promise<void>;
 /** Resume a paused schedule (`POST /v1/schedules/:id/resume`). */

package/dist/client/http-client-requests.js

@@ -155,6 +155,9 @@ export function cancelWorkflowRequest(context, id) {
 export function timeoutWorkflowRequest(context, id) {
   return request(context.baseUrl, `/workflows/${encodeURIComponent(id)}/timeout`, context.headers, { method: "POST" });
 }
+export function suspendWorkflowRequest(context, id) {
+  return request(context.baseUrl, `/workflows/${encodeURIComponent(id)}/suspend`, context.headers, { method: "POST" });
+}
 export function pauseScheduleRequest(context, id) {
   return request(context.baseUrl, `/schedules/${encodeURIComponent(id)}/pause`, context.headers, { method: "POST" });
 }

package/dist/client/http-client.d.ts

@@ -1,6 +1,6 @@
 import { type CatalogOperationName, type CatalogOperationTypes, type WeftClient as CatalogOperations } from '../cli/generated/operation-client.generated.ts';
 import type { StoredStreamChunk } from '../core/context.ts';
-import type { AttributeFilterKey, BulkCancelResult, BulkDeleteResult, BulkSignalResult, BulkTagResult, CoordinatedUpdateResult, ForkOptions, ListFilter, PaginatedResult, PurgeResult, QueryDefinition, RetentionOverview, ReviewListEntry, ReviewListFilter, ScheduleFilter, ScheduleOptions, ScheduleSpec, ScheduleSummary, SearchAttributeValue, SignalDefinition, SignalDeliveryOptions, StartOptions, SubmitReviewOptions, TypedListFilter, UpdateDefinition, WorkflowEvent, WorkflowInput, WorkflowOutput, WorkflowRegistry, WorkflowReplay, WorkflowState, WorkflowSummary, WorkflowTimelineEntry } from '../core/types.ts';
+import type { AttributeFilterKey, BulkCancelResult, BulkDeleteResult, BulkSignalResult, BulkTagResult, CoordinatedUpdateResult, ForkOptions, ListFilter, PaginatedResult, PurgeResult, QueryDefinition, RetentionOverview, ReviewListEntry, ReviewListFilter, ScheduleFilter, ScheduleOptions, ScheduleSpec, ScheduleSummary, SearchAttributeValue, SignalDefinition, SignalDeliveryOptions, StartOptions, StartOrSignalSignal, SubmitReviewOptions, TypedListFilter, UpdateDefinition, WorkflowEvent, WorkflowInput, WorkflowOutput, WorkflowRegistry, WorkflowReplay, WorkflowState, WorkflowSummary, WorkflowTimelineEntry } from '../core/types.ts';
 import { type WorkflowEventSubscription } from './event-stream.ts';
 import type { WorkflowEventTail } from './event-tail.ts';
 import { type HttpClientOptions } from './http-request.ts';
@@ -61,6 +61,8 @@ export declare class HttpClient implements WeftClient {
     call<Name extends CatalogOperationName>(name: Name, input: CatalogOperationTypes[Name]['input']): Promise<CatalogOperationTypes[Name]['output']>;
     start<TName extends KnownWorkflowName>(type: TName, input: WorkflowInput<WorkflowRegistry, TName>, options?: StartOptions): Promise<ClientHandle<WorkflowOutput<WorkflowRegistry, TName>>>;
     start<TName extends string>(type: UnknownNameWhenRegistryEmpty<TName>, input: unknown, options?: StartOptions): Promise<ClientHandle>;
+    startOrSignal<TName extends KnownWorkflowName>(type: TName, input: WorkflowInput<WorkflowRegistry, TName>, signal: StartOrSignalSignal, options?: StartOptions): Promise<ClientHandle<WorkflowOutput<WorkflowRegistry, TName>>>;
+    startOrSignal<TName extends string>(type: UnknownNameWhenRegistryEmpty<TName>, input: unknown, signal: StartOrSignalSignal, options?: StartOptions): Promise<ClientHandle>;
     schedule<TName extends KnownWorkflowName>(type: TName, input: WorkflowInput<WorkflowRegistry, TName>, spec: string | ScheduleSpec, options?: ScheduleOptions): Promise<ClientScheduleHandle>;
     schedule<TName extends string>(type: UnknownNameWhenRegistryEmpty<TName>, input: unknown, spec: string | ScheduleSpec, options?: ScheduleOptions): Promise<ClientScheduleHandle>;
     get(id: string): Promise<WorkflowState | null>;
@@ -68,6 +70,7 @@ export declare class HttpClient implements WeftClient {
     list<const TAttributeKeys extends readonly AttributeFilterKey[] = readonly AttributeFilterKey[]>(filter?: TypedListFilter<TAttributeKeys>): Promise<PaginatedResult<WorkflowSummary>>;
     listSchedules(filter?: ScheduleFilter): Promise<PaginatedResult<ScheduleSummary>>;
     cancel(id: string): Promise<void>;
+    suspend(id: string): Promise<void>;
     pauseSchedule(id: string): Promise<void>;
     resumeSchedule(id: string): Promise<void>;
     cancelSchedule(id: string): Promise<void>;

package/dist/client/http-client.js

@@ -31,6 +31,7 @@ import {
   signalWorkflowRequest,
   submitCoordinatedUpdateRequest,
   submitReviewRequest,
+  suspendWorkflowRequest,
   tagAllWorkflowRequests,
   timeoutWorkflowRequest,
   untagAllWorkflowRequests,
@@ -43,7 +44,7 @@ import { HttpScheduleHandle } from "./http-schedule-handle.js";
 import { openClientEventSubscription } from "./open-event-subscription.js";
 import { buildScheduleListSearchParams } from "./schedule-list-search-params.js";
 import { buildWorkflowListSearchParams } from "./search-params.js";
-import { buildStartBody, scheduleSpecToWireFields } from "./start-body.js";
+import { buildStartBody, buildStartOrSignalBody, scheduleSpecToWireFields } from "./start-body.js";
 
 export class HttpClient {
   baseUrl;
@@ -72,6 +73,10 @@ export class HttpClient {
     });
     return new HttpHandle(response.id, this);
   }
+  async startOrSignal(type, input, signal, options) {
+    const body = buildStartOrSignalBody(type, input, signal, options), response = await request(this.baseUrl, "/workflows/start-or-signal", this.headers, { method: "POST", body: JSON.stringify(body) });
+    return new HttpHandle(response.id, this);
+  }
   async schedule(type, input, spec, options) {
     const body = {
       type,
@@ -107,6 +112,9 @@ export class HttpClient {
   async cancel(id) {
     return cancelWorkflowRequest(this, id);
   }
+  async suspend(id) {
+    return suspendWorkflowRequest(this, id);
+  }
   async pauseSchedule(id) {
     return pauseScheduleRequest(this, id);
   }

package/dist/client/interface.d.ts

@@ -8,7 +8,7 @@
 import type { CatalogOperationName, CatalogOperationTypes, WeftClient as CatalogOperations } from '../cli/generated/operation-client.generated.ts';
 import type { StoredStreamChunk } from '../core/context.ts';
 import type { TypedEventTarget, WeftEventMap } from '../core/events.ts';
-import type { AttributeFilterKey, BulkCancelResult, BulkDeleteResult, BulkSignalResult, BulkTagResult, CoordinatedUpdateResult, ForkOptions, ListFilter, PaginatedResult, PurgeResult, QueryDefinition, RetentionOverview, ReviewListEntry, ReviewListFilter, ScheduleFilter, ScheduleOptions, ScheduleSpec, ScheduleSummary, SearchAttributeValue, SignalDefinition, SignalDeliveryOptions, StartOptions, SubmitReviewOptions, TypedListFilter, UpdateDefinition, WorkflowEvent, WorkflowInput, WorkflowOutput, WorkflowRegistry, WorkflowReplay, WorkflowState, WorkflowSummary, WorkflowTimelineEntry } from '../core/types.ts';
+import type { AttributeFilterKey, BulkCancelResult, BulkDeleteResult, BulkSignalResult, BulkTagResult, CoordinatedUpdateResult, ForkOptions, ListFilter, PaginatedResult, PurgeResult, QueryDefinition, RetentionOverview, ReviewListEntry, ReviewListFilter, ScheduleFilter, ScheduleOptions, ScheduleSpec, ScheduleSummary, SearchAttributeValue, SignalDefinition, SignalDeliveryOptions, StartOptions, StartOrSignalSignal, SubmitReviewOptions, TypedListFilter, UpdateDefinition, WorkflowEvent, WorkflowInput, WorkflowOutput, WorkflowRegistry, WorkflowReplay, WorkflowState, WorkflowSummary, WorkflowTimelineEntry } from '../core/types.ts';
 import type { WorkflowEventTail } from './event-tail.ts';
 import type { KnownWorkflowName, UnknownNameWhenRegistryEmpty } from './workflow-name-typing.ts';
 /**
@@ -56,6 +56,20 @@ export interface ClientHandle<TResult = unknown> extends TypedEventTarget<WeftEv
     result(): Promise<TResult>;
     /** Cancel this workflow. */
     cancel(): Promise<void>;
+    /**
+     * Suspend this workflow without terminating it: it moves to the non-terminal
+     * `suspended` status, keeps its checkpoint, and is later resumable via
+     * {@link ClientHandle.resume}. Unlike {@link ClientHandle.cancel}, it does not
+     * run cancel handlers and does not settle `result()`. Inline execution mode
+     * only (worker-mode servers fault with `Unprocessable`).
+     */
+    suspend(): Promise<void>;
+    /**
+     * Resume this workflow from its persisted checkpoint after a
+     * {@link ClientHandle.suspend} (or after a process restart left it running).
+     * `result()` resolves when the resumed run completes.
+     */
+    resume(): Promise<void>;
     /** Send a named signal with an optional payload. */
     signal(name: SignalDefinition): Promise<void>;
     signal<TInput>(name: SignalDefinition<TInput>, payload: TInput, options?: SignalDeliveryOptions): Promise<void>;
@@ -189,9 +203,40 @@ export interface WeftClient {
      * returned handle's `result()` to its output type. Without augmentation the
      * permissive string-name overload applies, so the client stays usable with
      * plain string names and no hard dependency on codegen.
+     *
+     * Pass `options.idempotencyKey` for at-most-once starts: a repeated key returns
+     * a handle to the existing run rather than starting a second. Conflicts (a
+     * duplicate `id`, or a key whose run was purged) are transport-dependent:
+     * `LocalClient` throws the typed error (`WorkflowAlreadyExistsError` /
+     * `IdempotencyKeyPurgedError`), while `HttpClient` throws `HttpClientError`
+     * with `status === 409` and `faultCode === 'Conflict'`.
      */
     start<TName extends KnownWorkflowName>(type: TName, input: WorkflowInput<WorkflowRegistry, TName>, options?: StartOptions): Promise<ClientHandle<WorkflowOutput<WorkflowRegistry, TName>>>;
     start<TName extends string>(type: UnknownNameWhenRegistryEmpty<TName>, input: unknown, options?: StartOptions): Promise<ClientHandle>;
+    /**
+     * Atomically start a workflow or signal it if it already exists
+     * (signal-with-start). An absent target is created and delivered the signal in
+     * one batch; a non-terminal target (running, pending, or suspended) is
+     * signalled; a terminal target is rejected as a conflict.
+     *
+     * The rejection shape is transport-dependent: `LocalClient` throws the typed
+     * `StartOrSignalConflictError` (and `IdempotencyKeyPurgedError` for a spent
+     * key), while `HttpClient` throws `HttpClientError` with `status === 409` and
+     * `faultCode === 'Conflict'`. Branch on `faultCode`/`status` for code that runs
+     * over either transport.
+     *
+     * Pass `options.idempotencyKey` to dedup independent callers such as retried
+     * webhooks: concurrent same-key callers converge on one workflow and one
+     * delivered signal, with the signal id derived from the key. Convergence needs a
+     * shared workflow identity — `options.idempotencyKey` (id-free) or
+     * `options.id` + `signal.signalId`. A bare `signal.signalId` with neither is an
+     * atomic start-with-one-signal that does NOT converge concurrent callers (each
+     * gets its own run). Supply exactly one of `signal.signalId` or
+     * `options.idempotencyKey`; `options.id` and `options.idempotencyKey` are
+     * mutually exclusive.
+     */
+    startOrSignal<TName extends KnownWorkflowName>(type: TName, input: WorkflowInput<WorkflowRegistry, TName>, signal: StartOrSignalSignal, options?: StartOptions): Promise<ClientHandle<WorkflowOutput<WorkflowRegistry, TName>>>;
+    startOrSignal<TName extends string>(type: UnknownNameWhenRegistryEmpty<TName>, input: unknown, signal: StartOrSignalSignal, options?: StartOptions): Promise<ClientHandle>;
     /**
      * Register a recurring schedule (cron string or interval spec) and return a
      * handle to it.
@@ -212,6 +257,12 @@ export interface WeftClient {
     listSchedules(filter?: ScheduleFilter): Promise<PaginatedResult<ScheduleSummary>>;
     /** Cancel a running workflow. */
     cancel(id: string): Promise<void>;
+    /**
+     * Suspend a running workflow without terminating it. It moves to the
+     * non-terminal `suspended` status, keeps its checkpoint, and is later
+     * resumable via {@link WeftClient.resume}. Inline execution mode only.
+     */
+    suspend(id: string): Promise<void>;
     /** Pause a recurring schedule. */
     pauseSchedule(id: string): Promise<void>;
     /** Resume a recurring schedule. */
@@ -240,7 +291,11 @@ export interface WeftClient {
     }): Promise<unknown>;
     /** Out-of-band ("async") activity completion by task token. See {@link WeftClientActivity}. */
     readonly activity: WeftClientActivity;
-    /** Resume a failed or timed-out workflow. */
+    /**
+     * Re-drive a workflow from its persisted checkpoint. Accepts a workflow that
+     * was explicitly suspended (`suspend(id)`) or one left `'running'` by a prior
+     * process; throws for a status that cannot be resumed (terminal or pending).
+     */
     resume(id: string): Promise<ClientHandle>;
     /** Recover all interrupted workflows. */
     recoverAll(): Promise<ClientHandle[]>;

package/dist/client/local.d.ts

@@ -9,7 +9,7 @@
  */
 import { type CatalogOperationName, type CatalogOperationTypes, type WeftClient as CatalogOperations } from '../cli/generated/operation-client.generated.ts';
 import type { Engine } from '../core/engine.ts';
-import type { AttributeFilterKey, BulkCancelResult, BulkDeleteResult, BulkSignalResult, BulkTagResult, CoordinatedUpdateResult, ForkOptions, ListFilter, PaginatedResult, PurgeResult, QueryDefinition, RetentionOverview, ReviewListEntry, ReviewListFilter, ScheduleFilter, ScheduleOptions, ScheduleSpec, ScheduleSummary, SearchAttributeValue, SignalDefinition, SignalDeliveryOptions, StartOptions, SubmitReviewOptions, TypedListFilter, UpdateDefinition, WorkflowEvent, WorkflowInput, WorkflowOutput, WorkflowRegistry, WorkflowReplay, WorkflowState, WorkflowSummary, WorkflowTimelineEntry } from '../core/types.ts';
+import type { AttributeFilterKey, BulkCancelResult, BulkDeleteResult, BulkSignalResult, BulkTagResult, CoordinatedUpdateResult, ForkOptions, ListFilter, PaginatedResult, PurgeResult, QueryDefinition, RetentionOverview, ReviewListEntry, ReviewListFilter, ScheduleFilter, ScheduleOptions, ScheduleSpec, ScheduleSummary, SearchAttributeValue, SignalDefinition, SignalDeliveryOptions, StartOptions, StartOrSignalSignal, SubmitReviewOptions, TypedListFilter, UpdateDefinition, WorkflowEvent, WorkflowInput, WorkflowOutput, WorkflowRegistry, WorkflowReplay, WorkflowState, WorkflowSummary, WorkflowTimelineEntry } from '../core/types.ts';
 import type { WorkflowEventTail } from './event-tail.ts';
 import type { ClientHandle, ClientScheduleHandle, UpdateResult, WeftClient, WeftClientActivity } from './interface.ts';
 import type { KnownWorkflowName, UnknownNameWhenRegistryEmpty } from './workflow-name-typing.ts';
@@ -57,6 +57,8 @@ export declare class LocalClient implements WeftClient {
     call<Name extends CatalogOperationName>(name: Name, input: CatalogOperationTypes[Name]['input']): Promise<CatalogOperationTypes[Name]['output']>;
     start<TName extends KnownWorkflowName>(type: TName, input: WorkflowInput<WorkflowRegistry, TName>, options?: StartOptions): Promise<ClientHandle<WorkflowOutput<WorkflowRegistry, TName>>>;
     start<TName extends string>(type: UnknownNameWhenRegistryEmpty<TName>, input: unknown, options?: StartOptions): Promise<ClientHandle>;
+    startOrSignal<TName extends KnownWorkflowName>(type: TName, input: WorkflowInput<WorkflowRegistry, TName>, signal: StartOrSignalSignal, options?: StartOptions): Promise<ClientHandle<WorkflowOutput<WorkflowRegistry, TName>>>;
+    startOrSignal<TName extends string>(type: UnknownNameWhenRegistryEmpty<TName>, input: unknown, signal: StartOrSignalSignal, options?: StartOptions): Promise<ClientHandle>;
     schedule<TName extends KnownWorkflowName>(type: TName, input: WorkflowInput<WorkflowRegistry, TName>, spec: string | ScheduleSpec, options?: ScheduleOptions): Promise<ClientScheduleHandle>;
     schedule<TName extends string>(type: UnknownNameWhenRegistryEmpty<TName>, input: unknown, spec: string | ScheduleSpec, options?: ScheduleOptions): Promise<ClientScheduleHandle>;
     get(id: string): Promise<WorkflowState | null>;
@@ -64,6 +66,7 @@ export declare class LocalClient implements WeftClient {
     list<const TAttributeKeys extends readonly AttributeFilterKey[] = readonly AttributeFilterKey[]>(filter?: TypedListFilter<TAttributeKeys>): Promise<PaginatedResult<WorkflowSummary>>;
     listSchedules(filter?: ScheduleFilter): Promise<PaginatedResult<ScheduleSummary>>;
     cancel(id: string): Promise<void>;
+    suspend(id: string): Promise<void>;
     pauseSchedule(id: string): Promise<void>;
     resumeSchedule(id: string): Promise<void>;
     cancelSchedule(id: string): Promise<void>;

package/dist/client/local.js

@@ -53,6 +53,10 @@ export class LocalClient {
     const handle = await this.#engine.start(type, input, options);
     return new LocalHandle(handle, this);
   }
+  async startOrSignal(type, input, signal, options) {
+    const handle = await this.#engine.startOrSignal(type, input, signal, options);
+    return new LocalHandle(handle, this);
+  }
   async schedule(type, input, spec, options) {
     const handle = await this.#engine.schedule(type, input, spec, options);
     return new LocalScheduleHandle(handle.id, this);
@@ -72,6 +76,9 @@ export class LocalClient {
   async cancel(id) {
     return this.#engine.cancel(id);
   }
+  async suspend(id) {
+    return this.#engine.suspend(id);
+  }
   async pauseSchedule(id) {
     return this.#engine.pauseSchedule(id);
   }

package/dist/client/start-body.d.ts

@@ -1,4 +1,4 @@
-import type { ScheduleSpec, StartOptions } from '../core/types.ts';
+import type { ScheduleSpec, StartOptions, StartOrSignalSignal } from '../core/types.ts';
 export declare function setIfDefined(body: Record<string, unknown>, key: string, value: unknown): void;
 /**
  * Translate a schedule recurrence specification into the wire body fields the
@@ -7,3 +7,9 @@ export declare function setIfDefined(body: Record<string, unknown>, key: string,
  */
 export declare function scheduleSpecToWireFields(spec: string | ScheduleSpec): Record<string, unknown>;
 export declare function buildStartBody(type: string, input: unknown, options?: StartOptions): Record<string, unknown>;
+/**
+ * Build the wire body for `weft.workflows.startorsignal`. Flattens the signal
+ * spec into `signalName` / `signalPayload` / `signalId` and carries the same
+ * start options as {@link buildStartBody}.
+ */
+export declare function buildStartOrSignalBody(type: string, input: unknown, signal: StartOrSignalSignal, options?: StartOptions): Record<string, unknown>;

package/dist/client/start-body.js

@@ -9,15 +9,24 @@ export function scheduleSpecToWireFields(spec) {
     return { every: spec.every };
   return { cronExpression: spec.cron };
 }
-export function buildStartBody(type, input, options) {
-  if (options?.idempotencyKey !== void 0)
-    throw Error("idempotencyKey is not supported over HttpClient because the start workflow HTTP protocol does not implement start idempotency");
-  const body = { type, input };
+function applyStartOptionsToBody(body, options) {
   setIfDefined(body, "id", options?.id);
   setIfDefined(body, "executionTimeout", options?.executionTimeout);
   setIfDefined(body, "startAt", options?.startAt);
   setIfDefined(body, "startAfter", options?.startAfter);
   setIfDefined(body, "tags", options?.tags);
+  setIfDefined(body, "idempotencyKey", options?.idempotencyKey);
   setIfDefined(body, "searchAttributes", options?.searchAttributes);
+}
+export function buildStartBody(type, input, options) {
+  const body = { type, input };
+  applyStartOptionsToBody(body, options);
+  return body;
+}
+export function buildStartOrSignalBody(type, input, signal, options) {
+  const body = { type, input, signalName: signal.name };
+  setIfDefined(body, "signalPayload", signal.payload);
+  setIfDefined(body, "signalId", signal.signalId);
+  applyStartOptionsToBody(body, options);
   return body;
 }

package/dist/core/codec/extension-codec.js

@@ -5,8 +5,10 @@ import {
   decodeCodecDate,
   encodeCodecDate
 } from "../codec-helpers.js";
+import { bindSerializerRegistryToCodec, hasRegisteredSerializer } from "./serializer-registry.js";
 const EXTENSION_TYPE_DATE = 1, EXTENSION_TYPE_REGEXP = 2, EXTENSION_TYPE_MAP = 3, EXTENSION_TYPE_SET = 4, EXTENSION_TYPE_UNDEFINED = 5, EXTENSION_TYPE_ERROR = 6;
 export const extensionCodec = new ExtensionCodec;
+bindSerializerRegistryToCodec(extensionCodec, replaceUndefined);
 extensionCodec.register({
   type: EXTENSION_TYPE_DATE,
   encode: encodeCodecDate,
@@ -75,7 +77,7 @@ extensionCodec.register({
 extensionCodec.register({
   type: EXTENSION_TYPE_ERROR,
   encode(value) {
-    if (value instanceof Error)
+    if (value instanceof Error && !hasRegisteredSerializer(value))
       return msgpackEncode({
         name: value.name,
         message: value.message,
@@ -135,7 +137,7 @@ function replaceSetUndefined(value, visited) {
   return result;
 }
 function isNestedValueFree(value) {
-  return value instanceof Date || value instanceof RegExp || value instanceof Error || value instanceof Uint8Array || value instanceof ArrayBuffer;
+  return value instanceof Date || value instanceof RegExp || value instanceof Error || value instanceof Uint8Array || value instanceof ArrayBuffer || hasRegisteredSerializer(value);
 }
 function replaceRecordUndefined(value, visited) {
   const record = value, result = {};

package/dist/core/codec/index.d.ts

@@ -1,3 +1,4 @@
 export { decode, encode } from './api.ts';
+export { registerSerializer, type SerializerHandlers } from './serializer-registry.ts';
 export { validateCloneable } from './validation.ts';
 export type { CloneValidationError, CloneValidationResult } from './validation.ts';

package/dist/core/codec/index.js

@@ -1,2 +1,3 @@
 export { decode, encode } from "./api.js";
+export { registerSerializer } from "./serializer-registry.js";
 export { validateCloneable } from "./validation.js";

package/dist/core/codec/serializer-registry.d.ts

@@ -0,0 +1,122 @@
+import { ExtensionCodec } from '@msgpack/msgpack';
+/**
+ * Encode/decode handlers for a custom structured type that crosses Weft's
+ * checkpoint codec. `toJSON` reduces an instance to a plain, msgpack-encodable
+ * value; `fromJSON` rebuilds the instance from that value on the far side.
+ *
+ * The handlers must round-trip deterministically: a value encoded and then
+ * decoded must reconstruct an equivalent instance, with field order and content
+ * stable across calls (the codec backs replay-deterministic checkpoints).
+ *
+ * @example
+ * ```ts
+ * import { type SerializerHandlers } from '@lostgradient/weft';
+ *
+ * class ValidationError extends Error {
+ *   constructor(
+ *     message: string,
+ *     readonly issues: string[],
+ *   ) {
+ *     super(message);
+ *     this.name = 'ValidationError';
+ *   }
+ * }
+ *
+ * const handlers: SerializerHandlers<ValidationError> = {
+ *   toJSON: (error) => ({ message: error.message, issues: error.issues }),
+ *   fromJSON: (data) => {
+ *     const record = data as { message: string; issues: string[] };
+ *     return new ValidationError(record.message, record.issues);
+ *   },
+ * };
+ * void handlers;
+ * ```
+ */
+export type SerializerHandlers<T> = {
+    toJSON(value: T): unknown;
+    fromJSON(data: unknown): T;
+};
+/**
+ * Constructor of a registrable type. Uses a `never[]`-rest abstract constructor
+ * so it accepts any class (a concrete class is assignable to an abstract
+ * constructor whose parameters are `never[]`) without an `any`. The handlers,
+ * not the constructor signature, own (de)serialization; the constructor is used
+ * only for instance-identity matching.
+ */
+type RegistrableConstructor<T> = abstract new (...args: never[]) => T;
+/**
+ * Register a custom (de)serializer for `constructor` on Weft's checkpoint codec.
+ * Once registered, any instance of `constructor` that crosses the codec — an
+ * activity result, workflow input, signal payload, or error — round-trips
+ * through `handlers` instead of the generic structured-clone fallback (which,
+ * for errors, would otherwise drop subclass fields like a `ZodError`'s
+ * `.issues`).
+ *
+ * `options.tag` is a stable, developer-chosen discriminant stored inside each
+ * encoded value. Decode resolves the handler by this tag, so registration order
+ * and count are irrelevant and a checkpoint stays decodable across deploys.
+ * Choose an explicit, durable string — do NOT rely on `constructor.name`, which
+ * a minified build mangles, silently breaking cross-build decode.
+ *
+ * Matching is by exact constructor identity, and the built-in `Error` encoder
+ * defers to a registered serializer. The other built-in extension types
+ * (`Date`, `RegExp`, `Map`, `Set`) do NOT defer: registering a serializer for a
+ * subclass of one of those built-ins has no effect, because the built-in
+ * encoder matches the instance first. Register serializers for your own classes
+ * (or `Error` subclasses), not for built-in-collection subclasses.
+ *
+ * Registration is process-global and one-shot per constructor and per tag: call
+ * it once at module load, before constructing any engine. Re-registering the
+ * same constructor, or reusing a `tag` already taken by another constructor,
+ * throws. A checkpoint written with a registered serializer is decodable by any
+ * process that registered the same tag → handler.
+ *
+ * @example
+ * ```ts
+ * import { registerSerializer } from '@lostgradient/weft';
+ *
+ * class RateLimitError extends Error {
+ *   constructor(readonly retryAfterMs: number) {
+ *     super('rate limited');
+ *     this.name = 'RateLimitError';
+ *   }
+ * }
+ *
+ * registerSerializer(
+ *   RateLimitError,
+ *   {
+ *     toJSON: (error) => ({ retryAfterMs: error.retryAfterMs }),
+ *     fromJSON: (data) => new RateLimitError((data as { retryAfterMs: number }).retryAfterMs),
+ *   },
+ *   { tag: 'RateLimitError' },
+ * );
+ * ```
+ */
+export declare function registerSerializer<T>(constructor: RegistrableConstructor<T>, handlers: SerializerHandlers<T>, options: {
+    tag: string;
+}): void;
+/**
+ * Whether `value` is an instance of a registered constructor. The built-in
+ * Error extension encoder consults this to defer to a registered serializer
+ * (so a registered Error subclass uses its custom handler, not the generic
+ * Error encoding), regardless of extension-encoder registration order.
+ */
+export declare function hasRegisteredSerializer(value: object): boolean;
+/**
+ * Wire the shared extensionCodec so the single custom-serializer extension type
+ * is registered on the live codec, along with the codec's `replaceUndefined`
+ * preprocessor so custom-serializer output is encoded with the same `undefined`
+ * semantics as the public `encode()`. Called once at codec construction.
+ * `replaceUndefined` is passed in rather than imported to avoid a static cycle:
+ * extension-codec.ts imports this module for `hasRegisteredSerializer`.
+ */
+export declare function bindSerializerRegistryToCodec(codec: ExtensionCodec, replaceUndefined: (value: unknown, visited: Set<object>) => unknown): void;
+/**
+ * Test-only reset of the global registry. Production code never unregisters —
+ * a stale serializer could misread a checkpoint — but tests need isolation
+ * between registration cases. Clears both tag and constructor maps; the single
+ * extension-type decoder stays bound to the codec and simply finds an empty
+ * registry until the next registration.
+ */
+export declare function resetSerializerRegistryForTesting(): void;
+export {};

package/dist/core/codec/serializer-registry.js

@@ -0,0 +1,51 @@
+import { ExtensionCodec, decode as msgpackDecode, encode as msgpackEncode } from "@msgpack/msgpack";
+const CUSTOM_SERIALIZER_EXTENSION_TYPE = 100, registryByConstructor = new Map, registryByTag = new Map;
+export function registerSerializer(constructor, handlers, options) {
+  const key = constructor, { tag } = options;
+  if (typeof tag !== "string" || tag.length === 0)
+    throw Error("registerSerializer requires a non-empty string options.tag.");
+  if (registryByConstructor.has(key))
+    throw Error(`A serializer is already registered for ${constructor.name || "an anonymous constructor"}; registerSerializer is one-shot per constructor.`);
+  if (registryByTag.has(tag))
+    throw Error(`A serializer is already registered with tag "${tag}"; serializer tags must be unique.`);
+  const entry = {
+    tag,
+    constructor: key,
+    handlers
+  };
+  registryByConstructor.set(key, entry);
+  registryByTag.set(tag, entry);
+}
+export function hasRegisteredSerializer(value) {
+  return registryByConstructor.has(value.constructor);
+}
+export function bindSerializerRegistryToCodec(codec, replaceUndefined) {
+  codec.register({
+    type: CUSTOM_SERIALIZER_EXTENSION_TYPE,
+    encode(value) {
+      if (typeof value !== "object" || value === null)
+        return null;
+      const entry = registryByConstructor.get(value.constructor);
+      if (entry === void 0)
+        return null;
+      const data = replaceUndefined(entry.handlers.toJSON(value), new Set);
+      return msgpackEncode({ tag: entry.tag, data }, { extensionCodec: codec });
+    },
+    decode(bytes) {
+      const payload = msgpackDecode(bytes, { extensionCodec: codec });
+      if (typeof payload !== "object" || payload === null || !("tag" in payload))
+        throw Error("Corrupt custom-serializer payload: missing tag.");
+      const { tag, data } = payload;
+      if (typeof tag !== "string")
+        throw Error("Corrupt custom-serializer payload: tag is not a string.");
+      const entry = registryByTag.get(tag);
+      if (entry === void 0)
+        throw Error(`No serializer registered for tag "${tag}". Register it (with the same tag) before decoding a checkpoint that used it.`);
+      return entry.handlers.fromJSON(data);
+    }
+  });
+}
+export function resetSerializerRegistryForTesting() {
+  registryByConstructor.clear();
+  registryByTag.clear();
+}

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

@@ -55,6 +55,15 @@ export declare class Context implements WorkflowContext {
     run<TInput, TResult>(fn: ((input: TInput) => Promise<TResult> | TResult) & {
         execute?: never;
     }, input: TInput, options?: ActivityCallOptions): Generator<ContextOperationRequest, TResult, unknown>;
+    /**
+     * Durably sleep for `duration` before continuing. Unlike a wall-clock
+     * `setTimeout`, this is a checkpointed operation: the engine persists the timer
+     * and resumes the workflow when it fires, so a sleep survives process restarts
+     * and spans of days. On replay an already-elapsed sleep is a no-op — a
+     * recovered workflow does not wait again. `duration` is milliseconds
+     * (`number`) or a duration string (`'30s'`, `'1h'`, `'2d'` — see
+     * {@link Duration}); drive it with `yield*` from a workflow body.
+     */
     sleep(duration: Duration): Generator<ContextOperationRequest, void, unknown>;
     suspendUntil<T = unknown>(resumeToken: string): Generator<ContextOperationRequest, T, unknown>;
     waitForSignal<TInput>(definition: SignalDefinition<TInput>): Generator<ContextOperationRequest, TInput, unknown>;

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

@@ -29,3 +29,12 @@ export interface ContextInternals {
 }
 export declare function initializeInternals(context: Context, options: ContextOptions, initialSessionState: Record<string, unknown> | undefined): void;
 export declare function getInternals(context: Context): ContextInternals;
+/**
+ * Non-throwing probe: is `value` a concrete {@link Context} with initialized
+ * internals? Used to distinguish the inline-mode `Context` (which carries the
+ * `stepIndex`/`accumulatedResults` replay machinery) from the minimal
+ * worker-mode `WorkerWorkflowContext`, which is a different shape. WeakMap
+ * `.has` accepts any object key and returns `false` for non-`Context` objects,
+ * so this is safe to call on any context-shaped value.
+ */
+export declare function hasContextInternals(value: object): value is Context;

package/dist/core/context/internals.js

@@ -35,3 +35,6 @@ export function getInternals(context) {
     throw Error("Context internals not initialized");
   return internals;
 }
+export function hasContextInternals(value) {
+  return INTERNALS.has(value);
+}

package/dist/core/context/run-operation.d.ts

@@ -1,6 +1,19 @@
-import { type RetryPolicy } from '../types.ts';
+import { type RetryPolicy, type WorkflowContext } from '../types.ts';
 import type { Context } from './index.ts';
 import type { ContextOperationRequest } from './operation-request.ts';
+/**
+ * Recover the concrete {@link Context} from the public {@link WorkflowContext}
+ * the engine passes to a workflow handler. Under the inline execution strategy
+ * the engine invokes a handler with the concrete `Context` instance (carrying
+ * the `stepIndex`/`accumulatedResults` replay machinery). Worker execution mode
+ * instead drives the handler with a minimal `WorkerWorkflowContext`, which has
+ * no replay internals — so infrastructure such as `compileStepWorkflow` cannot
+ * drive the durable activity machinery there. This probes for the inline
+ * internals (via the `hasContextInternals` type guard, which narrows without a
+ * cast) and throws an actionable error rather than the cryptic
+ * "Context internals not initialized" from a downstream `getInternals` call.
+ */
+export declare function asConcreteContext(context: WorkflowContext): Context;
 type ActivityInput = string | (Function & {
     retry?: RetryPolicy;
 });
@@ -16,6 +29,6 @@ interface RunActivityRequest<TResult> {
     retryPolicy?: RetryPolicy;
 }
 export declare function shouldRetryActivityError(error: unknown, policy: RetryPolicy | undefined, attempt: number): policy is RetryPolicy;
-export declare function createRunActivityRequest<TResult>(context: Context, activity: ActivityInput, rest: readonly unknown[]): RunActivityRequest<TResult>;
-export declare function runActivityWithRetry<TResult>(context: Context, activity: ActivityInput, rest: readonly unknown[]): Generator<ContextOperationRequest, TResult, unknown>;
+export declare function createRunActivityRequest<TResult>(context: Context, activity: ActivityInput, rest: readonly unknown[], explicitName?: string): RunActivityRequest<TResult>;
+export declare function runActivityWithRetry<TResult>(context: Context, activity: ActivityInput, rest: readonly unknown[], explicitName?: string): Generator<ContextOperationRequest, TResult, unknown>;
 export {};