@lostgradient/weft 0.4.0 → 0.6.0

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, ClientStartOptions, 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

@@ -32,6 +32,21 @@ 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.

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, 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 { 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>;

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, 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]() {}
-}
-
-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);

package/dist/core/engine/activity-per-attempt-timeout.d.ts

@@ -15,8 +15,13 @@ type ActivityOperation = Extract<ContextOperationRequest, {
  * EITHER workflow cancellation OR a per-attempt timeout — without the timeout
  * reaching back to cancel the whole workflow (which would also poison the next
  * retry's signal).
+ *
+ * An optional `coordinatorSignal` (from a `ctx.race` or `ctx.all` coordinator)
+ * is also composed in (#584): when a sibling branch wins the race, the coordinator
+ * aborts its controller, propagating to the activity's `ctx.signal` for
+ * cooperative cancellation of losing activity branches.
  */
-export declare function resolvePerAttemptTimeout(internals: EngineInternals, workflowId: string, operation: ActivityOperation): {
+export declare function resolvePerAttemptTimeout(internals: EngineInternals, workflowId: string, operation: ActivityOperation, coordinatorSignal?: AbortSignal): {
     perAttemptTimeoutMs: number | undefined;
     attemptAbortController: AbortController | undefined;
     activitySignal: AbortSignal;

package/dist/core/engine/activity-per-attempt-timeout.js

@@ -2,12 +2,12 @@ import {
   ActivityPerAttemptTimeoutError,
   parsePerAttemptTimeoutMs
 } from "../context/activity-schedule-to-close.js";
-export function resolvePerAttemptTimeout(internals, workflowId, operation) {
-  const workflowAbortController = internals.inlineStrategy?.getAbortController(workflowId), perAttemptTimeoutMs = internals.activityWorkerDispatcher ? void 0 : parsePerAttemptTimeoutMs(operation.options?.timeout), attemptAbortController = perAttemptTimeoutMs === void 0 ? void 0 : new AbortController, activitySignal = composeActivitySignal(workflowAbortController?.signal, attemptAbortController?.signal);
+export function resolvePerAttemptTimeout(internals, workflowId, operation, coordinatorSignal) {
+  const workflowAbortController = internals.inlineStrategy?.getAbortController(workflowId), perAttemptTimeoutMs = internals.activityWorkerDispatcher ? void 0 : parsePerAttemptTimeoutMs(operation.options?.timeout), attemptAbortController = perAttemptTimeoutMs === void 0 ? void 0 : new AbortController, activitySignal = composeActivitySignal(workflowAbortController?.signal, attemptAbortController?.signal, coordinatorSignal);
   return { perAttemptTimeoutMs, attemptAbortController, activitySignal };
 }
-function composeActivitySignal(workflowSignal, attemptSignal) {
-  const signals = [workflowSignal, attemptSignal].filter((signal) => signal !== void 0), [first] = signals;
+function composeActivitySignal(workflowSignal, attemptSignal, coordinatorSignal) {
+  const signals = [workflowSignal, attemptSignal, coordinatorSignal].filter((signal) => signal !== void 0), [first] = signals;
   if (first === void 0)
     return new AbortController().signal;
   if (signals.length === 1)

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

@@ -19,6 +19,7 @@ export type EngineCreateRuntimeOptions = EngineConstructorOptions & {
     workflows?: Record<string, AnyWorkflowDefinition> | undefined;
     recover?: boolean | undefined;
     acknowledgeUnknownWorkflowTypes?: boolean | undefined;
+    startScheduler?: boolean | undefined;
 };
 export type NormalizedWorkerExecutionConfiguration = {
     mode: 'inline';

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

@@ -29,6 +29,20 @@ export type EngineCreateOptions<TWorkflowDefinitions extends Record<string, AnyW
     workflows?: TWorkflowDefinitions;
     /** Activity definitions to register before workflows. */
     activities?: TActivityDefinitions;
+    /**
+     * Start the scheduler's durable-timer polling loop after registration so
+     * `ctx.sleep(...)` and `engine.schedule(...)` timers fire in a long-lived
+     * in-process host. This is independent of `recover`: it controls *whether
+     * timers fire*, not *who drives `recoverAll`*.
+     *
+     * Defaults to `recover !== false`. A host that opts out of auto-recovery
+     * with `recover: false` (because it drives its own `recoverAll()` to capture
+     * the recovered handles) can still arm the poller by passing
+     * `startScheduler: true`. Pass `startScheduler: false` to keep the poller
+     * stopped even when recovery runs (tests / `ScopedStorage` engines that tick
+     * the scheduler deterministically).
+     */
+    startScheduler?: boolean;
 } & ({
     /**
      * Recover stored running workflows after registration. Defaults to

package/dist/core/engine/index.js

@@ -228,6 +228,8 @@ export class Engine extends EventTarget {
       await engine.#acquireLeaseIfConfigured();
       if (options.recover !== !1)
         await engine.recoverAll(options.acknowledgeUnknownWorkflowTypes !== void 0 ? { acknowledgeUnknownWorkflowTypes: options.acknowledgeUnknownWorkflowTypes } : {});
+      if (options.startScheduler ?? options.recover !== !1)
+        getInternals(engine).scheduler.start();
     } catch (error) {
       await engine[Symbol.asyncDispose]();
       throw error;

package/dist/core/engine/operations-activity.d.ts

@@ -27,7 +27,7 @@ export declare function invokeInlineActivity(internals: EngineInternals, workflo
  * Execute an activity function, dispatching to a Web Worker pool when
  * `activityExecution` is configured, or running inline on the main thread.
  */
-export declare function executeActivity(internals: EngineInternals, workflowId: string, operation: ActivityOperation, callbacks: ActivityOperationCallbacks, attempt?: number): Promise<unknown>;
-export declare function executeActivityOperationResult(internals: EngineInternals, workflowId: string, operation: ActivityOperation, callbacks: ActivityOperationCallbacks, speculativeState?: SpeculativeExecutionState): Promise<unknown>;
+export declare function executeActivity(internals: EngineInternals, workflowId: string, operation: ActivityOperation, callbacks: ActivityOperationCallbacks, attempt?: number, coordinatorSignal?: AbortSignal): Promise<unknown>;
+export declare function executeActivityOperationResult(internals: EngineInternals, workflowId: string, operation: ActivityOperation, callbacks: ActivityOperationCallbacks, coordinatorSignal?: AbortSignal, speculativeState?: SpeculativeExecutionState): Promise<unknown>;
 export declare function processActivityOperation(internals: EngineInternals, workflowId: string, operation: ActivityOperation, callbacks: ActivityOperationCallbacks): Promise<void>;
 export {};

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

@@ -69,10 +69,10 @@ function getActivityAttempt(operation) {
   const attempt = operation.attempt;
   return typeof attempt === "number" && Number.isInteger(attempt) && attempt > 0 ? attempt : 1;
 }
-export async function executeActivity(internals, workflowId, operation, callbacks, attempt = getActivityAttempt(operation)) {
+export async function executeActivity(internals, workflowId, operation, callbacks, attempt = getActivityAttempt(operation), coordinatorSignal) {
   const activityInput = operation.input, step = operation.step ?? 0;
   warnIfRetryMissingHeartbeat(internals, workflowId, step, attempt);
-  const asyncToken = deriveAsyncActivityToken(workflowId, step, attempt), { perAttemptTimeoutMs, attemptAbortController, activitySignal } = resolvePerAttemptTimeout(internals, workflowId, operation), activityContext = buildActivityContext(internals, workflowId, step, activitySignal, () => {
+  const asyncToken = deriveAsyncActivityToken(workflowId, step, attempt), { perAttemptTimeoutMs, attemptAbortController, activitySignal } = resolvePerAttemptTimeout(internals, workflowId, operation, coordinatorSignal), activityContext = buildActivityContext(internals, workflowId, step, activitySignal, () => {
     throw new AsyncActivityDeferral(asyncToken);
   }), invokeActivity = internals.activityWorkerDispatcher ? (activityName, input) => invokeWorkerActivity(internals, operation.operationId, activityName, input, attempt) : (activityName, input) => withPerAttemptTimeout(invokeInlineActivity(internals, workflowId, operation, activityContext, activityName, input), perAttemptTimeoutMs, activityName, attempt, attemptAbortController), composedActivity = callbacks.getComposedActivityInterceptor(), executeWithActivityInterceptors = async (activityName, input, headers) => {
     if (!composedActivity)
@@ -107,7 +107,7 @@ export async function executeActivity(internals, workflowId, operation, callback
   copyActivityHeadersToOperation(operation, headers);
   return result;
 }
-export async function executeActivityOperationResult(internals, workflowId, operation, callbacks, speculativeState) {
+export async function executeActivityOperationResult(internals, workflowId, operation, callbacks, coordinatorSignal, speculativeState) {
   const activity = getActivityFunctionWithMetadata(internals, workflowId, operation), idempotencyKey = resolveActivityIdempotencyKey(activity, operation), operationAttempt = getActivityAttempt(operation);
   if (idempotencyKey !== void 0) {
     const reference = await buildActivityReconciliationReference(workflowId, operation.activityName, idempotencyKey), started = await resolveStartedActivityReconciliationRecord(internals, workflowId, operation, reference, activity, idempotencyKey, operationAttempt);
@@ -115,7 +115,7 @@ export async function executeActivityOperationResult(internals, workflowId, oper
       validateActivityResultForReconciliation(started.completedResult, internals.options.payloadSizePolicy.maxBytes);
       return started.completedResult;
     }
-    const result = await executeActivity(internals, workflowId, operation, callbacks, started.attempt);
+    const result = await executeActivity(internals, workflowId, operation, callbacks, started.attempt, coordinatorSignal);
     validateActivityResultForReconciliation(result, internals.options.payloadSizePolicy.maxBytes);
     await finalizeActivityResult(internals, workflowId, operation, result, activity, idempotencyKey, started.attempt, speculativeState, !0);
     const completedRecord = createCompletedActivityReconciliationRecord(started, result, internals.options.getNow());
@@ -124,7 +124,7 @@ export async function executeActivityOperationResult(internals, workflowId, oper
       clearLastHeartbeatForStep(internals, workflowId, operation.step ?? 0);
     return result;
   }
-  const result = await executeActivity(internals, workflowId, operation, callbacks, operationAttempt);
+  const result = await executeActivity(internals, workflowId, operation, callbacks, operationAttempt, coordinatorSignal);
   assertPayloadWithinLimit(result, internals.options.payloadSizePolicy.maxBytes, "activity result");
   await finalizeActivityResult(internals, workflowId, operation, result, activity, idempotencyKey, operationAttempt, speculativeState);
   if (!speculativeState)

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

@@ -192,6 +192,6 @@ export async function executeRunAllOperationResult(internals, workflowId, operat
       activityName: fn.name,
       fn,
       input
-    }, callbacks.getActivityOperationCallbacks(), speculativeState);
+    }, callbacks.getActivityOperationCallbacks(), void 0, speculativeState);
   });
 }

package/dist/core/engine/sub-operation.js

@@ -36,7 +36,7 @@ export async function executeSubOperation(internals, workflowId, operation, call
   }, operation);
 }
 const subOperationExecutors = {
-  activity: (context, operation) => executeActivitySubOperation(context.internals, context.workflowId, operation, context.callbacks, context.speculativeState),
+  activity: (context, operation) => executeActivitySubOperation(context.internals, context.workflowId, operation, context.callbacks, context.signal, context.speculativeState),
   "child-workflow": (context, operation) => executeChildWorkflowSubOperation(context.internals, context.workflowId, operation, context.callbacks),
   memo: (_context, operation) => Promise.resolve(callMemoFunction(operation.fn)),
   "state-read": (context, operation) => executeStateReadSubOperation(context.internals, operation),
@@ -50,8 +50,8 @@ const subOperationExecutors = {
     throw Error("ctx.waitUntil() cannot be used as a ctx.race() / ctx.all() / ctx.speculate() branch. Use `yield* ctx.waitUntil(...)` directly, or gate it behind a signal/update the coordinator resolves.");
   }
 };
-async function executeActivitySubOperation(internals, workflowId, operation, callbacks, speculativeState) {
-  return executeActivityOperationResult(internals, workflowId, operation, callbacks.createActivityOperationCallbacks(), speculativeState);
+async function executeActivitySubOperation(internals, workflowId, operation, callbacks, signal, speculativeState) {
+  return executeActivityOperationResult(internals, workflowId, operation, callbacks.createActivityOperationCallbacks(), signal, speculativeState);
 }
 async function executeChildWorkflowSubOperation(internals, workflowId, operation, callbacks) {
   return executeChildWorkflow(internals, workflowId, operation, assertChildWorkflowNestingDepth(internals, workflowId), callbacks.createChildWorkflowOperationCallbacks());

package/dist/index.d.ts

@@ -108,7 +108,7 @@ export type { RemoteWorkerActivityFunction, RemoteWorkerActivityImplementation,
 export type { WorkflowEventTail } from './client/event-tail';
 export { HttpClient, HttpClientError } from './client/index';
 export type { HttpClientOptions } from './client/index';
-export type { ClientHandle, ClientStartOptions, UpdateResult, WeftClient, WeftClientActivity, } from './client/interface';
+export type { ClientHandle, ClientStartOptions, StartOrSignalOutcome, UpdateResult, WeftClient, WeftClientActivity, } from './client/interface';
 export { LocalClient } from './client/local';
 export type { KnownWorkflowName, UnknownNameWhenRegistryEmpty, } from './client/workflow-name-typing';
 export { ConnectionConfigurationError, DEFAULT_WEFT_ADDRESS, resolveConnection, } from './connection';