@lostgradient/weft 0.2.1 → 0.4.0

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

@@ -1,9 +1,11 @@
 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>;
+    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?: {
@@ -18,9 +20,12 @@ 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>;
+    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

@@ -3,13 +3,21 @@ 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);
   }
+  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

@@ -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>;
@@ -50,6 +51,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

@@ -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)
@@ -155,6 +162,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,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, 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,15 +59,20 @@ 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>;
+    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>>;
     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>;
@@ -118,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,11 +26,13 @@ import {
   removeTagsRequest,
   replayToRequest,
   resumeScheduleRequest,
+  retryFailedAllWorkflowRequests,
   setAttributesRequest,
   signalAllWorkflowRequests,
   signalWorkflowRequest,
   submitCoordinatedUpdateRequest,
   submitReviewRequest,
+  suspendWorkflowRequest,
   tagAllWorkflowRequests,
   timeoutWorkflowRequest,
   untagAllWorkflowRequests,
@@ -43,7 +45,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 +74,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, response.outcome);
+  }
   async schedule(type, input, spec, options) {
     const body = {
       type,
@@ -93,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);
   }
@@ -107,6 +118,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);
   }
@@ -196,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, UpdateResult, WeftClient, WeftClientActivity, } from './interface.ts';
 export type { KnownWorkflowName, UnknownNameWhenRegistryEmpty } from './workflow-name-typing.ts';

package/dist/client/interface.d.ts

@@ -7,10 +7,32 @@
  */
 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, 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;
+};
+export type StartOrSignalOutcome = EngineStartOrSignalOutcome;
 /**
  * A reference to a workflow that provides convenience methods.
  *
@@ -52,10 +74,30 @@ 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. */
     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 +231,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?: 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
+     * 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.
      */
-    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?: 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.
@@ -204,6 +277,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. */
@@ -212,6 +296,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 +330,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[]>;
@@ -288,6 +382,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.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, 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 { ClientHandle, ClientScheduleHandle, UpdateResult, WeftClient, WeftClientActivity } from './interface.ts';
 import type { KnownWorkflowName, UnknownNameWhenRegistryEmpty } from './workflow-name-typing.ts';
@@ -57,13 +57,18 @@ 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>;
+    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>>;
     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>;
@@ -103,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

@@ -12,8 +12,8 @@ import { createLocalWorkflowEventTail } from "./local-event-tail.js";
 
 class LocalHandle extends WorkflowHandleDelegation {
   #handle;
-  constructor(handle, client) {
-    super(handle.id, client);
+  constructor(handle, client, outcome) {
+    super(handle.id, client, outcome);
     this.#handle = handle;
   }
   async result() {
@@ -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, 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);
     return new LocalScheduleHandle(handle.id, this);
@@ -60,6 +64,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);
   }
@@ -72,6 +81,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);
   }
@@ -151,6 +163,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 } 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,4 +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?: ClientStartOptions): 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/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;
 /**