@lostgradient/weft 0.3.0 → 0.5.0

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

@@ -1,7 +1,7 @@
 import type { WeftEventMap } from '../core/events.ts';
 import type { QueryDefinition, ScheduleSpec, ScheduleSummary, SearchAttributeValue, SignalDefinition, SignalDeliveryOptions, UpdateDefinition } from '../core/types.ts';
 import type { WorkflowEventTail } from './event-tail.ts';
-import type { ClientHandle, ClientScheduleHandle } from './interface.ts';
+import type { ClientHandle, ClientScheduleHandle, StartOrSignalOutcome } from './interface.ts';
 export interface WorkflowHandleDelegationClient {
     cancel(id: string): Promise<void>;
     suspend(id: string): Promise<void>;
@@ -20,7 +20,8 @@ export interface WorkflowHandleDelegationClient {
 export declare abstract class WorkflowHandleDelegation<TClient extends WorkflowHandleDelegationClient = WorkflowHandleDelegationClient> implements ClientHandle {
     readonly id: string;
     protected readonly client: TClient;
-    constructor(id: string, client: TClient);
+    readonly outcome: StartOrSignalOutcome | undefined;
+    constructor(id: string, client: TClient, outcome?: StartOrSignalOutcome);
     abstract result(): Promise<unknown>;
     cancel(): Promise<void>;
     suspend(): Promise<void>;

package/dist/client/handle-delegation.js

@@ -3,9 +3,11 @@ import { messageName } from "../core/types.js";
 export class WorkflowHandleDelegation {
   id;
   client;
-  constructor(id, client) {
+  outcome;
+  constructor(id, client, outcome) {
     this.id = id;
     this.client = client;
+    this.outcome = outcome;
   }
   async cancel() {
     return this.client.cancel(this.id);

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

@@ -1,5 +1,5 @@
 import type { StoredStreamChunk } from '../core/context.ts';
-import type { BulkCancelResult, BulkDeleteResult, BulkSignalResult, BulkTagResult, CoordinatedUpdateResult, ForkOptions, ListFilter, PurgeResult, RetentionOverview, ReviewListEntry, ReviewListFilter, ScheduleSpec, ScheduleSummary, SearchAttributeValue, SignalDeliveryOptions, SubmitReviewOptions, WorkflowReplay, WorkflowState, WorkflowTimelineEntry } from '../core/types.ts';
+import type { BulkCancelResult, BulkDeleteResult, BulkRetryFailedResult, BulkSignalResult, BulkTagResult, CoordinatedUpdateResult, ForkOptions, ListFilter, PurgeResult, RetentionOverview, ReviewListEntry, ReviewListFilter, ScheduleSpec, ScheduleSummary, SearchAttributeValue, SignalDeliveryOptions, SubmitReviewOptions, WorkflowReplay, WorkflowState, WorkflowTimelineEntry } from '../core/types.ts';
 import type { UpdateResult } from './interface.ts';
 export type HttpClientRequestContext = {
     readonly baseUrl: string;
@@ -14,6 +14,7 @@ export declare function forkWorkflowRequest(context: HttpClientRequestContext, i
 export declare function getRetentionOverviewRequest(context: HttpClientRequestContext): Promise<RetentionOverview>;
 export declare function purgeWorkflowRequests(context: HttpClientRequestContext, filter?: ListFilter): Promise<PurgeResult>;
 export declare function cancelAllWorkflowRequests(context: HttpClientRequestContext, filter: ListFilter): Promise<BulkCancelResult>;
+export declare function retryFailedAllWorkflowRequests(context: HttpClientRequestContext, filter: ListFilter): Promise<BulkRetryFailedResult>;
 export declare function signalAllWorkflowRequests(context: HttpClientRequestContext, filter: ListFilter, name: string, payload?: unknown): Promise<BulkSignalResult>;
 export declare function deleteAllWorkflowRequests(context: HttpClientRequestContext, filter: ListFilter): Promise<BulkDeleteResult>;
 export declare function tagAllWorkflowRequests(context: HttpClientRequestContext, filter: ListFilter, tags: string[]): Promise<BulkTagResult>;

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

@@ -44,6 +44,13 @@ export function cancelAllWorkflowRequests(context, filter) {
     body: JSON.stringify({ filter })
   });
 }
+export function retryFailedAllWorkflowRequests(context, filter) {
+  assertScopedBulkWorkflowFilter(filter);
+  return request(context.baseUrl, "/workflows/bulk/retry-failed", context.headers, {
+    method: "POST",
+    body: JSON.stringify({ filter })
+  });
+}
 export function signalAllWorkflowRequests(context, filter, name, payload) {
   assertScopedBulkWorkflowFilter(filter);
   if (name.length === 0)

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

@@ -1,10 +1,10 @@
 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, StartOrSignalSignal, SubmitReviewOptions, TypedListFilter, UpdateDefinition, WorkflowEvent, WorkflowInput, WorkflowOutput, WorkflowRegistry, WorkflowReplay, WorkflowState, WorkflowSummary, WorkflowTimelineEntry } from '../core/types.ts';
+import type { AttributeFilterKey, BulkCancelResult, BulkDeleteResult, BulkRetryFailedResult, BulkSignalResult, BulkTagResult, CoordinatedUpdateResult, ForkOptions, ListFilter, PaginatedResult, PurgeResult, QueryDefinition, RetentionOverview, ReviewListEntry, ReviewListFilter, ScheduleFilter, ScheduleOptions, ScheduleSpec, ScheduleSummary, SearchAttributeValue, SignalDefinition, SignalDeliveryOptions, 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';
-import type { ClientHandle, ClientScheduleHandle, UpdateResult, WeftClient, WeftClientActivity } from './interface.ts';
+import type { ClientHandle, ClientScheduleHandle, ClientStartOptions, UpdateResult, WeftClient, WeftClientActivity } from './interface.ts';
 import type { KnownWorkflowName, UnknownNameWhenRegistryEmpty } from './workflow-name-typing.ts';
 /**
  * Remote Weft client backed by HTTP requests.
@@ -59,13 +59,15 @@ export declare class HttpClient implements WeftClient {
     readonly activity: WeftClientActivity;
     constructor(options?: HttpClientOptions);
     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>;
+    start<TName extends KnownWorkflowName>(type: TName, input: WorkflowInput<WorkflowRegistry, TName>, options?: ClientStartOptions): Promise<ClientHandle<WorkflowOutput<WorkflowRegistry, TName>>>;
+    start<TName extends string>(type: UnknownNameWhenRegistryEmpty<TName>, input: unknown, options?: ClientStartOptions): Promise<ClientHandle>;
+    startOrSignal<TName extends KnownWorkflowName>(type: TName, input: WorkflowInput<WorkflowRegistry, TName>, signal: StartOrSignalSignal, options?: ClientStartOptions): Promise<ClientHandle<WorkflowOutput<WorkflowRegistry, TName>>>;
+    startOrSignal<TName extends string>(type: UnknownNameWhenRegistryEmpty<TName>, input: unknown, signal: StartOrSignalSignal, options?: ClientStartOptions): 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>;
+    getHandle(id: string): Promise<ClientHandle | null>;
+    getHandle<TName extends KnownWorkflowName>(id: string): Promise<ClientHandle<WorkflowOutput<WorkflowRegistry, TName>> | null>;
     getSchedule(id: string): Promise<ScheduleSummary | null>;
     list<const TAttributeKeys extends readonly AttributeFilterKey[] = readonly AttributeFilterKey[]>(filter?: TypedListFilter<TAttributeKeys>): Promise<PaginatedResult<WorkflowSummary>>;
     listSchedules(filter?: ScheduleFilter): Promise<PaginatedResult<ScheduleSummary>>;
@@ -121,6 +123,7 @@ export declare class HttpClient implements WeftClient {
     getRetentionOverview(): Promise<RetentionOverview>;
     purge(filter?: ListFilter): Promise<PurgeResult>;
     cancelAll(filter: ListFilter): Promise<BulkCancelResult>;
+    retryFailedAll(filter: ListFilter): Promise<BulkRetryFailedResult>;
     signalAll(filter: ListFilter, name: string, payload?: unknown): Promise<BulkSignalResult>;
     deleteAll(filter: ListFilter): Promise<BulkDeleteResult>;
     tagAll(filter: ListFilter, tags: string[]): Promise<BulkTagResult>;

package/dist/client/http-client.js

@@ -26,6 +26,7 @@ import {
   removeTagsRequest,
   replayToRequest,
   resumeScheduleRequest,
+  retryFailedAllWorkflowRequests,
   setAttributesRequest,
   signalAllWorkflowRequests,
   signalWorkflowRequest,
@@ -75,7 +76,7 @@ export class HttpClient {
   }
   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);
+    return new HttpHandle(response.id, this, response.outcome);
   }
   async schedule(type, input, spec, options) {
     const body = {
@@ -98,6 +99,11 @@ export class HttpClient {
   async get(id) {
     return getWorkflowRequest(this, id);
   }
+  async getHandle(id) {
+    if (await getWorkflowRequest(this, id) === null)
+      return null;
+    return new HttpHandle(id, this);
+  }
   async getSchedule(id) {
     return getScheduleRequest(this, id);
   }
@@ -204,6 +210,9 @@ export class HttpClient {
   async cancelAll(filter) {
     return cancelAllWorkflowRequests(this, filter);
   }
+  async retryFailedAll(filter) {
+    return retryFailedAllWorkflowRequests(this, filter);
+  }
   async signalAll(filter, name, payload) {
     return signalAllWorkflowRequests(this, filter, name, payload);
   }

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

@@ -1,6 +1,6 @@
 import { type FaultCode } from '../core/fault-code.ts';
 import type { FailureCategory } from '../core/types/identity.ts';
-import { WeftError } from '../core/weft-error.ts';
+import { WeftError, type WeftErrorCode } from '../core/weft-error.ts';
 import type { WebSocketFactory } from './event-stream-transport.ts';
 /**
  * Configuration for the HTTP client.
@@ -94,8 +94,18 @@ export declare class HttpClientError extends WeftError<'HttpClientError'> {
      * carried on the wire; `undefined` when `faultCode` is `undefined`.
      */
     readonly category?: FailureCategory | undefined;
+    /**
+     * The fine-grained originating public {@link WeftErrorCode} the server
+     * attached (e.g. `WorkflowNotFoundError`), when the structured fault carried
+     * one. This is what makes cross-transport branching work: a producer can call
+     * `isWeftFault(error, 'WorkflowNotFoundError')` and have it match over HTTP
+     * exactly as it matches the in-process typed error. `undefined` when the fault
+     * carried only the coarse {@link faultCode} (most faults) or no structured body.
+     */
+    readonly weftCode?: WeftErrorCode | undefined;
     constructor(status: number, message: string, options?: {
         faultCode?: FaultCode | undefined;
+        weftCode?: WeftErrorCode | undefined;
     });
 }
 export declare function request<T>(baseUrl: string, path: string, baseHeaders: Record<string, string>, options?: RequestInit): Promise<T>;

package/dist/client/http-request.js

@@ -1,6 +1,6 @@
 import { resolveConnection } from "../connection.js";
 import { failureCategoryForFaultCode, isFaultCode } from "../core/fault-code.js";
-import { WeftError } from "../core/weft-error.js";
+import { isWeftErrorCode, WeftError } from "../core/weft-error.js";
 export function resolveHttpClientConnection(options) {
   const connection = resolveConnection({
     includeRunLockfile: !1,
@@ -16,11 +16,13 @@ export class HttpClientError extends WeftError {
   status;
   faultCode;
   category;
+  weftCode;
   constructor(status, message, options) {
     super("HttpClientError", message);
     this.status = status;
     this.faultCode = options?.faultCode;
     this.category = options?.faultCode === void 0 ? void 0 : failureCategoryForFaultCode(options.faultCode);
+    this.weftCode = options?.weftCode;
   }
 }
 function buildRequestHeaders(baseHeaders, options) {
@@ -45,15 +47,23 @@ function isStructuredErrorBody(value) {
     return !1;
   return typeof error.message === "string";
 }
+function weftCodeFromData(data) {
+  if (data === null || typeof data !== "object")
+    return;
+  const candidate = data.weftCode;
+  return isWeftErrorCode(candidate) ? candidate : void 0;
+}
 async function parseErrorBody(response) {
   try {
     const body = await response.json();
     if (isStructuredErrorBody(body)) {
-      const { code, message } = body.error;
-      return isFaultCode(code) ? { message, faultCode: code } : { message };
+      const { code, message, data } = body.error, weftCode = weftCodeFromData(data), base = weftCode === void 0 ? { message } : { message, weftCode };
+      return isFaultCode(code) ? { ...base, faultCode: code } : base;
+    }
+    if (isFlatErrorBody(body) && body.error) {
+      const weftCode = isWeftErrorCode(body.weftCode) ? body.weftCode : void 0;
+      return weftCode === void 0 ? { message: body.error } : { message: body.error, weftCode };
     }
-    if (isFlatErrorBody(body) && body.error)
-      return { message: body.error };
     return { message: response.statusText };
   } catch {
     return { message: response.statusText };
@@ -64,8 +74,8 @@ export async function request(baseUrl, path, baseHeaders, options) {
   if (response.status === 404 && (!options?.method || options.method === "GET"))
     return null;
   if (!response.ok) {
-    const { message, faultCode } = await parseErrorBody(response);
-    throw new HttpClientError(response.status, message, { faultCode });
+    const { message, faultCode, weftCode } = await parseErrorBody(response);
+    throw new HttpClientError(response.status, message, { faultCode, weftCode });
   }
   if (response.status === 204)
     return;

package/dist/client/index.d.ts

@@ -11,5 +11,5 @@ export type { WorkflowEventTail } from './event-tail.ts';
 export { HttpClient } from './http-client.ts';
 export { HttpClientError } from './http-request.ts';
 export type { HttpClientOptions } from './http-request.ts';
-export type { ClientHandle, ClientScheduleHandle, UpdateResult, WeftClient, WeftClientActivity, } from './interface.ts';
+export type { ClientHandle, ClientScheduleHandle, ClientStartOptions, StartOrSignalOutcome, UpdateResult, WeftClient, WeftClientActivity, } from './interface.ts';
 export type { KnownWorkflowName, UnknownNameWhenRegistryEmpty } from './workflow-name-typing.ts';

package/dist/client/interface.d.ts

@@ -7,10 +7,47 @@
  */
 import type { CatalogOperationName, CatalogOperationTypes, WeftClient as CatalogOperations } from '../cli/generated/operation-client.generated.ts';
 import type { StoredStreamChunk } from '../core/context.ts';
+import type { StartOrSignalOutcome as EngineStartOrSignalOutcome } from '../core/engine/handles.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, StartOrSignalSignal, SubmitReviewOptions, TypedListFilter, UpdateDefinition, WorkflowEvent, WorkflowInput, WorkflowOutput, WorkflowRegistry, WorkflowReplay, WorkflowState, WorkflowSummary, WorkflowTimelineEntry } from '../core/types.ts';
+import type { AttributeFilterKey, BulkCancelResult, BulkDeleteResult, BulkRetryFailedResult, 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';
+/**
+ * Start options accepted by remote-capable clients. These options intentionally
+ * exclude inline-only engine features such as `defer` and per-run `services`
+ * because they cannot be serialized over the HTTP transport.
+ *
+ * @example
+ * ```ts
+ * import type { ClientStartOptions } from '@lostgradient/weft/client';
+ *
+ * const options: ClientStartOptions = {
+ *   id: 'welcome-ada',
+ *   tags: ['onboarding'],
+ * };
+ * void options;
+ * ```
+ */
+export type ClientStartOptions = Omit<StartOptions, 'defer' | 'services'> & {
+    readonly defer?: never;
+    readonly services?: never;
+};
+/**
+ * Which atomic path a {@link WeftClient.startOrSignal} call took, returned
+ * alongside the {@link ClientHandle}. `'started'` when the call created the
+ * run; `'signalled'` when it delivered a signal to a run that already existed,
+ * including losing a concurrent same-key create race and converging onto the
+ * winner. Each call receives its OWN handle regardless of the outcome.
+ *
+ * @example
+ * ```ts
+ * import type { StartOrSignalOutcome } from '@lostgradient/weft/client';
+ *
+ * const outcome: StartOrSignalOutcome = 'started';
+ * void outcome;
+ * ```
+ */
+export type StartOrSignalOutcome = EngineStartOrSignalOutcome;
 /**
  * A reference to a workflow that provides convenience methods.
  *
@@ -52,6 +89,12 @@ import type { KnownWorkflowName, UnknownNameWhenRegistryEmpty } from './workflow
 export interface ClientHandle<TResult = unknown> extends TypedEventTarget<WeftEventMap>, Disposable {
     /** The workflow's unique identifier. */
     readonly id: string;
+    /**
+     * For a {@link WeftClient.startOrSignal} handle, which atomic path the call
+     * took (see {@link StartOrSignalOutcome}); `undefined` on handles from any
+     * other call (`start`, `getHandle`, `resume`, …).
+     */
+    readonly outcome: StartOrSignalOutcome | undefined;
     /** Resolves when the workflow completes (or rejects on failure). */
     result(): Promise<TResult>;
     /** Cancel this workflow. */
@@ -211,8 +254,8 @@ export interface WeftClient {
      * `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>;
+    start<TName extends KnownWorkflowName>(type: TName, input: WorkflowInput<WorkflowRegistry, TName>, options?: ClientStartOptions): Promise<ClientHandle<WorkflowOutput<WorkflowRegistry, TName>>>;
+    start<TName extends string>(type: UnknownNameWhenRegistryEmpty<TName>, input: unknown, options?: ClientStartOptions): 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
@@ -235,8 +278,8 @@ export interface WeftClient {
      * `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>;
+    startOrSignal<TName extends KnownWorkflowName>(type: TName, input: WorkflowInput<WorkflowRegistry, TName>, signal: StartOrSignalSignal, options?: ClientStartOptions): Promise<ClientHandle<WorkflowOutput<WorkflowRegistry, TName>>>;
+    startOrSignal<TName extends string>(type: UnknownNameWhenRegistryEmpty<TName>, input: unknown, signal: StartOrSignalSignal, options?: ClientStartOptions): Promise<ClientHandle>;
     /**
      * Register a recurring schedule (cron string or interval spec) and return a
      * handle to it.
@@ -249,6 +292,17 @@ export interface WeftClient {
     schedule<TName extends string>(type: UnknownNameWhenRegistryEmpty<TName>, input: unknown, spec: string | ScheduleSpec, options?: ScheduleOptions): Promise<ClientScheduleHandle>;
     /** Get the full persisted state of a workflow, or `null` if not found. */
     get(id: string): Promise<WorkflowState | null>;
+    /**
+     * Re-attach a {@link ClientHandle} to an existing workflow by id, or `null`
+     * when none exists — handle ergonomics for a run you did not start yourself.
+     * `result()` on an already-terminal run resolves (or rejects) from persisted
+     * state, so a fire-and-forget run can be observed later without hand-rolling
+     * terminal-status polling. Supplying the workflow name as a type argument
+     * (`getHandle<'my-workflow'>(id)`) narrows `result()` to that workflow's output
+     * when the {@link WorkflowRegistry} is augmented; the name is a type hint only.
+     */
+    getHandle(id: string): Promise<ClientHandle | null>;
+    getHandle<TName extends KnownWorkflowName>(id: string): Promise<ClientHandle<WorkflowOutput<WorkflowRegistry, TName>> | null>;
     /** Get the current summary of a recurring schedule, or `null` if not found. */
     getSchedule(id: string): Promise<ScheduleSummary | null>;
     /** List workflows with optional filtering and pagination. */
@@ -343,6 +397,8 @@ export interface WeftClient {
     purge(filter?: ListFilter): Promise<PurgeResult>;
     /** Cancel all running or pending workflows that match a filter. */
     cancelAll(filter: ListFilter): Promise<BulkCancelResult>;
+    /** Retry all failed workflows that match a filter. */
+    retryFailedAll(filter: ListFilter): Promise<BulkRetryFailedResult>;
     /** Signal all running or pending workflows that match a filter. */
     signalAll(filter: ListFilter, name: string, payload?: unknown): Promise<BulkSignalResult>;
     /** Delete all matching terminal workflows. */

package/dist/client/local-handles.d.ts

@@ -0,0 +1,22 @@
+/**
+ * In-process handle wrappers for {@link LocalClient}. Split out of
+ * `client/local.ts` to keep that module under the per-file line ceiling.
+ *
+ * @module client/local-handles
+ */
+import type { WorkflowHandle } from '../core/engine.ts';
+import type { WeftEventMap } from '../core/events.ts';
+import { ScheduleHandleDelegation, WorkflowHandleDelegation } from './handle-delegation.ts';
+import type { StartOrSignalOutcome } from './interface.ts';
+import type { LocalClient } from './local.ts';
+export declare class LocalHandle extends WorkflowHandleDelegation<LocalClient> {
+    #private;
+    constructor(handle: WorkflowHandle, client: LocalClient, outcome?: StartOrSignalOutcome);
+    result(): Promise<unknown>;
+    addEventListener<K extends keyof WeftEventMap>(type: K, listener: (event: WeftEventMap[K]) => void, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener<K extends keyof WeftEventMap>(type: K, listener: (event: WeftEventMap[K]) => void, options?: boolean | EventListenerOptions): void;
+    [Symbol.dispose](): void;
+}
+export declare class LocalScheduleHandle extends ScheduleHandleDelegation<LocalClient> {
+    [Symbol.dispose](): void;
+}

package/dist/client/local-handles.js

@@ -0,0 +1,23 @@
+import { ScheduleHandleDelegation, WorkflowHandleDelegation } from "./handle-delegation.js";
+
+export class LocalHandle extends WorkflowHandleDelegation {
+  #handle;
+  constructor(handle, client, outcome) {
+    super(handle.id, client, outcome);
+    this.#handle = handle;
+  }
+  async result() {
+    return this.#handle.result();
+  }
+  addEventListener(type, listener, options) {
+    this.#handle.addEventListener(type, listener, options);
+  }
+  removeEventListener(type, listener, options) {
+    this.#handle.removeEventListener(type, listener, options);
+  }
+  [Symbol.dispose]() {}
+}
+
+export class LocalScheduleHandle extends ScheduleHandleDelegation {
+  [Symbol.dispose]() {}
+}

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, StartOrSignalSignal, SubmitReviewOptions, TypedListFilter, UpdateDefinition, WorkflowEvent, WorkflowInput, WorkflowOutput, WorkflowRegistry, WorkflowReplay, WorkflowState, WorkflowSummary, WorkflowTimelineEntry } from '../core/types.ts';
+import type { AttributeFilterKey, BulkCancelResult, BulkDeleteResult, BulkRetryFailedResult, BulkSignalResult, BulkTagResult, CoordinatedUpdateResult, DefaultActivityTypes, DefaultWorkflowRegistry, 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';
@@ -32,7 +32,7 @@ import type { KnownWorkflowName, UnknownNameWhenRegistryEmpty } from './workflow
  * console.log(await handle.result()); // 'Hello, World!'
  * ```
  */
-export declare class LocalClient implements WeftClient {
+export declare class LocalClient<TWorkflows extends object = DefaultWorkflowRegistry, TActivities extends object = DefaultActivityTypes> implements WeftClient {
     #private;
     /** Typed low-level accessor for every catalog operation, routed in-process. */
     readonly operations: CatalogOperations;
@@ -53,7 +53,7 @@ export declare class LocalClient implements WeftClient {
      * ```
      */
     readonly activity: WeftClientActivity;
-    constructor(engine: Engine);
+    constructor(engine: Engine<TWorkflows, TActivities> | Engine);
     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>;
@@ -62,6 +62,8 @@ export declare class LocalClient implements WeftClient {
     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>;
+    getHandle(id: string): Promise<ClientHandle | null>;
+    getHandle<TName extends KnownWorkflowName>(id: string): Promise<ClientHandle<WorkflowOutput<WorkflowRegistry, TName>> | null>;
     getSchedule(id: string): Promise<ScheduleSummary | null>;
     list<const TAttributeKeys extends readonly AttributeFilterKey[] = readonly AttributeFilterKey[]>(filter?: TypedListFilter<TAttributeKeys>): Promise<PaginatedResult<WorkflowSummary>>;
     listSchedules(filter?: ScheduleFilter): Promise<PaginatedResult<ScheduleSummary>>;
@@ -106,6 +108,7 @@ export declare class LocalClient implements WeftClient {
     getRetentionOverview(): Promise<RetentionOverview>;
     purge(filter?: ListFilter): Promise<PurgeResult>;
     cancelAll(filter: ListFilter): Promise<BulkCancelResult>;
+    retryFailedAll(filter: ListFilter): Promise<BulkRetryFailedResult>;
     signalAll(filter: ListFilter, name: string, payload?: unknown): Promise<BulkSignalResult>;
     deleteAll(filter: ListFilter): Promise<BulkDeleteResult>;
     tagAll(filter: ListFilter, tags: string[]): Promise<BulkTagResult>;

package/dist/client/local.js

@@ -6,31 +6,9 @@ import {
   runtimeWorkflowEngine
 } from "../core/runtime-workflow-engine.js";
 import { messageName } from "../core/types.js";
-import { ScheduleHandleDelegation, WorkflowHandleDelegation } from "./handle-delegation.js";
 import { inProcessCatalogTransport } from "./in-process-operations.js";
 import { createLocalWorkflowEventTail } from "./local-event-tail.js";
-
-class LocalHandle extends WorkflowHandleDelegation {
-  #handle;
-  constructor(handle, client) {
-    super(handle.id, client);
-    this.#handle = handle;
-  }
-  async result() {
-    return this.#handle.result();
-  }
-  addEventListener(type, listener, options) {
-    this.#handle.addEventListener(type, listener, options);
-  }
-  removeEventListener(type, listener, options) {
-    this.#handle.removeEventListener(type, listener, options);
-  }
-  [Symbol.dispose]() {}
-}
-
-class LocalScheduleHandle extends ScheduleHandleDelegation {
-  [Symbol.dispose]() {}
-}
+import { LocalHandle, LocalScheduleHandle } from "./local-handles.js";
 
 export class LocalClient {
   #engine;
@@ -44,7 +22,7 @@ export class LocalClient {
       complete: (token, result) => this.#engine.completeAsyncActivity(token, result),
       completeExceptionally: (token, error) => this.#engine.failAsyncActivity(token, error)
     };
-    this.operations = createCatalogWeftClient(CATALOG_OPERATION_NAMES, inProcessCatalogTransport(engine));
+    this.operations = createCatalogWeftClient(CATALOG_OPERATION_NAMES, inProcessCatalogTransport(this.#rawEngine));
   }
   call(name, input) {
     return this.operations[name](input);
@@ -54,8 +32,8 @@ export class LocalClient {
     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);
+    const { handle, outcome } = await this.#engine.startOrSignal(type, input, signal, options);
+    return new LocalHandle(handle, this, outcome);
   }
   async schedule(type, input, spec, options) {
     const handle = await this.#engine.schedule(type, input, spec, options);
@@ -64,6 +42,11 @@ export class LocalClient {
   async get(id) {
     return this.#engine.get(id);
   }
+  async getHandle(id) {
+    if (await this.#engine.get(id) === null)
+      return null;
+    return new LocalHandle(this.#engine.getHandle(id), this);
+  }
   async getSchedule(id) {
     return this.#engine.getSchedule(id);
   }
@@ -158,6 +141,9 @@ export class LocalClient {
   async cancelAll(filter) {
     return this.#engine.cancelAll(filter);
   }
+  async retryFailedAll(filter) {
+    return this.#engine.retryFailedAll(filter);
+  }
   async signalAll(filter, name, payload) {
     return this.#engine.signalAll(filter, name, payload);
   }

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

@@ -1,4 +1,5 @@
-import type { ScheduleSpec, StartOptions, StartOrSignalSignal } from '../core/types.ts';
+import type { ScheduleSpec, StartOrSignalSignal } from '../core/types.ts';
+import type { ClientStartOptions } from './interface.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
@@ -6,10 +7,10 @@ export declare function setIfDefined(body: Record<string, unknown>, key: string,
  * `cronExpression`; an interval spec is sent as `every`.
  */
 export declare function scheduleSpecToWireFields(spec: string | ScheduleSpec): Record<string, unknown>;
-export declare function buildStartBody(type: string, input: unknown, options?: StartOptions): Record<string, unknown>;
+export declare function buildStartBody(type: string, input: unknown, options?: ClientStartOptions): 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>;
+export declare function buildStartOrSignalBody(type: string, input: unknown, signal: StartOrSignalSignal, options?: ClientStartOptions): Record<string, unknown>;

package/dist/core/byte-arrays.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Copy arbitrary `Uint8Array` data into a fresh `ArrayBuffer` for Web APIs that
+ * reject `SharedArrayBuffer`-backed views.
+ */
+export declare function copyBytesToArrayBuffer(bytes: Uint8Array): ArrayBuffer;

package/dist/core/byte-arrays.js

@@ -0,0 +1,5 @@
+export function copyBytesToArrayBuffer(bytes) {
+  const copy = new Uint8Array(bytes.byteLength);
+  copy.set(bytes);
+  return copy.buffer;
+}

package/dist/core/checkpoint/lifecycle.d.ts

@@ -29,6 +29,9 @@ export declare function createCheckpoint(workflowId: WorkflowId, version: string
 export declare function advanceCheckpoint(checkpoint: Checkpoint, locals: Record<string, unknown>, options?: {
     searchAttributes?: Record<string, SearchAttributeValue>;
     accumulatedResults?: Array<[number, unknown]>;
+    accumulatedResultReplayWatermark?: number;
+    workerReplaySignatures?: Checkpoint['workerReplaySignatures'];
+    workerReplayFailures?: Checkpoint['workerReplayFailures'];
     now?: number;
 }): Checkpoint;
 /**

package/dist/core/checkpoint/lifecycle.js

@@ -6,7 +6,6 @@ export function createCheckpoint(workflowId, version, now) {
     step: 0,
     locals: {},
     accumulatedResults: [],
-    pendingSignals: [],
     searchAttributes: {},
     version,
     schemaVersion: CURRENT_CHECKPOINT_SCHEMA_VERSION,
@@ -19,9 +18,15 @@ export function advanceCheckpoint(checkpoint, locals, options) {
     step: checkpoint.step + 1,
     locals,
     accumulatedResults: options?.accumulatedResults ?? checkpoint.accumulatedResults,
-    ...checkpoint.workerReplaySignatures === void 0 ? {} : { workerReplaySignatures: checkpoint.workerReplaySignatures },
-    ...checkpoint.workerReplayFailures === void 0 ? {} : { workerReplayFailures: checkpoint.workerReplayFailures },
-    pendingSignals: checkpoint.pendingSignals,
+    ...(options?.accumulatedResultReplayWatermark ?? checkpoint.accumulatedResultReplayWatermark) === void 0 ? {} : {
+      accumulatedResultReplayWatermark: options?.accumulatedResultReplayWatermark ?? checkpoint.accumulatedResultReplayWatermark
+    },
+    ...(options?.workerReplaySignatures ?? checkpoint.workerReplaySignatures) === void 0 ? {} : {
+      workerReplaySignatures: options?.workerReplaySignatures ?? checkpoint.workerReplaySignatures
+    },
+    ...(options?.workerReplayFailures ?? checkpoint.workerReplayFailures) === void 0 ? {} : {
+      workerReplayFailures: options?.workerReplayFailures ?? checkpoint.workerReplayFailures
+    },
     searchAttributes: {
       ...checkpoint.searchAttributes,
       ...options?.searchAttributes

package/dist/core/checkpoint/serialization.js

@@ -26,9 +26,10 @@ export function validateCheckpointShape(value) {
   assertRecordField(record, "locals");
   validateSessionStateLocals(record.locals);
   normalizeAccumulatedResults(record);
+  validateAccumulatedResultReplayWatermark(record);
   validateWorkerReplaySignatures(record);
   validateWorkerReplayFailures(record);
-  assertArrayField(record, "pendingSignals");
+  dropLegacyPendingSignals(record);
   assertRecordField(record, "searchAttributes");
   assertStringField(record, "version");
   assertNumberField(record, "createdAt");
@@ -132,10 +133,6 @@ function assertRecordField(record, field) {
   if (typeof record[field] !== "object" || record[field] === null)
     throw Error(`Invalid checkpoint: missing or invalid "${field}" (expected object)`);
 }
-function assertArrayField(record, field) {
-  if (!Array.isArray(record[field]))
-    throw Error(`Invalid checkpoint: missing or invalid "${field}" (expected array)`);
-}
 function normalizeAccumulatedResults(record) {
   if (!("accumulatedResults" in record)) {
     record.accumulatedResults = [];
@@ -144,6 +141,16 @@ function normalizeAccumulatedResults(record) {
   if (!Array.isArray(record.accumulatedResults))
     throw Error('Invalid checkpoint: invalid "accumulatedResults" (expected array)');
 }
+function validateAccumulatedResultReplayWatermark(record) {
+  const watermark = record.accumulatedResultReplayWatermark;
+  if (watermark === void 0)
+    return;
+  if (typeof watermark !== "number" || !Number.isSafeInteger(watermark) || watermark < 0)
+    throw Error('Invalid checkpoint: invalid "accumulatedResultReplayWatermark" (expected non-negative safe integer)');
+}
+function dropLegacyPendingSignals(record) {
+  delete record.pendingSignals;
+}
 function assertCurrentSchemaVersion(record) {
   const schemaVersion = record.schemaVersion;
   if (schemaVersion === void 0)