@lostgradient/weft 0.6.0 → 0.7.0

package/dist/client/open-event-subscription.d.ts

@@ -10,7 +10,8 @@
  * @module client/open-event-subscription
  */
 import type { WorkflowEvent } from '../core/types.ts';
-import { WorkflowEventSubscription, type WorkflowEventStreamOptions } from './event-stream.ts';
+import type { WorkflowEventStreamOptions } from './event-stream-options.ts';
+import type { WorkflowEventTail } from './event-tail.ts';
 /**
  * The streaming-relevant view of an HTTP client: the fields a workflow event
  * subscription needs to open its `/watch` socket and run `getEvents` catch-up.
@@ -30,4 +31,4 @@ export type WorkflowEventStreamHost = {
  * consumers (`tail()`) so the connect catch-up is buffered for the async
  * iterator rather than dropped.
  */
-export declare function openClientEventSubscription(host: WorkflowEventStreamHost, streamOptions: WorkflowEventStreamOptions, workflowId: string, onEvent: (event: WorkflowEvent) => void, bufferForIteration?: boolean): WorkflowEventSubscription;
+export declare function openClientEventSubscription(host: WorkflowEventStreamHost, streamOptions: WorkflowEventStreamOptions, workflowId: string, onEvent: (event: WorkflowEvent) => void, bufferForIteration?: boolean): WorkflowEventTail;

package/dist/client/open-event-subscription.js

@@ -1,5 +1,32 @@
+import { detectRuntime } from "../runtime/portable.js";
 import { workflowWatchWebSocketUrl } from "./event-stream-transport.js";
 import { WorkflowEventSubscription } from "./event-stream.js";
+import { SseWorkflowEventSubscription, workflowEventsSseUrl } from "./sse-event-stream.js";
 export function openClientEventSubscription(host, streamOptions, workflowId, onEvent, bufferForIteration = !1) {
-  return new WorkflowEventSubscription(workflowWatchWebSocketUrl(host.baseUrl, workflowId), host.headers, workflowId, (id) => host.getEvents(id), onEvent, bufferForIteration ? { ...streamOptions, bufferForIteration } : streamOptions);
+  const options = bufferForIteration ? { ...streamOptions, bufferForIteration } : streamOptions, transport = options.eventTransport ?? "auto";
+  if (transport === "sse")
+    return openSseEventSubscription(host, workflowId, onEvent, options);
+  if (shouldPreferServerSentEventsFallback(host, options, transport))
+    return openSseEventSubscription(host, workflowId, onEvent, options);
+  try {
+    return new WorkflowEventSubscription(workflowWatchWebSocketUrl(host.baseUrl, workflowId), host.headers, workflowId, (id) => host.getEvents(id), onEvent, options);
+  } catch (error) {
+    if (transport !== "auto")
+      throw error;
+    if (!isWebSocketTransportUnavailable(error))
+      throw error;
+    return openSseEventSubscription(host, workflowId, onEvent, options);
+  }
+}
+function shouldPreferServerSentEventsFallback(host, options, transport) {
+  return transport === "auto" && options.webSocketFactory === void 0 && detectRuntime() !== "bun" && Object.keys(host.headers).length > 0;
+}
+function isWebSocketTransportUnavailable(error) {
+  if (!(error instanceof Error))
+    return !1;
+  const message = error.message.toLowerCase();
+  return message.includes("no global websocket") || message.includes("cannot send the configured auth headers over websocket") || message.includes("websocket headers unavailable") || message.includes("websocket constructor has no header support") || message.includes("provide httpclientoptions.websocketfactory");
+}
+function openSseEventSubscription(host, workflowId, onEvent, options) {
+  return new SseWorkflowEventSubscription(workflowEventsSseUrl(host.baseUrl, workflowId), host.headers, workflowId, onEvent, options);
 }

package/dist/client/sse-event-stream.d.ts

@@ -0,0 +1,27 @@
+import type { WorkflowEvent } from '../core/types.ts';
+import type { StreamCloseReason } from './event-stream.ts';
+import type { WorkflowEventTail } from './event-tail.ts';
+export type ServerSentEventFrame = {
+    readonly id?: string;
+    readonly event?: string;
+    readonly data: string;
+};
+export type ServerSentEventParseResult = {
+    readonly frames: ReadonlyArray<ServerSentEventFrame>;
+    readonly remainder: string;
+};
+export type SseWorkflowEventStreamOptions = {
+    readonly maxReconnectAttempts?: number;
+    readonly reconnectBackoffMs?: number;
+    readonly bufferForIteration?: boolean;
+};
+export declare function workflowEventsSseUrl(baseUrl: string, workflowId: string): string;
+export declare function parseServerSentEventChunk(text: string, previousRemainder?: string): ServerSentEventParseResult;
+export declare class SseWorkflowEventSubscription implements WorkflowEventTail {
+    #private;
+    constructor(url: string, headers: Record<string, string>, workflowId: string, onEvent: (event: WorkflowEvent) => void, options?: SseWorkflowEventStreamOptions);
+    get closeReason(): StreamCloseReason | null;
+    whenConnected(): Promise<void>;
+    close(): void;
+    [Symbol.asyncIterator](): AsyncIterator<WorkflowEvent>;
+}

package/dist/client/sse-event-stream.js

@@ -0,0 +1,276 @@
+import { WORKFLOW_TERMINAL_EVENT_TYPES } from "../core/events/workflow-events.js";
+import { WorkflowEventTailLifecycle } from "./event-tail-lifecycle.js";
+const DEFAULT_MAX_RECONNECT_ATTEMPTS = 5, DEFAULT_RECONNECT_BACKOFF_MS = 50;
+export function workflowEventsSseUrl(baseUrl, workflowId) {
+  return `${baseUrl.replace(/\/+$/, "")}/v1/workflows/${encodeURIComponent(workflowId)}/events/sse`;
+}
+export function parseServerSentEventChunk(text, previousRemainder = "") {
+  const parts = `${previousRemainder}${text}`.replaceAll(`\r
+`, `
+`).replaceAll("\r", `
+`).split(`
+
+`), remainder = parts.pop() ?? "";
+  return { frames: parts.map(parseServerSentEventFrame).filter((frame) => frame !== null), remainder };
+}
+function parseServerSentEventFrame(block) {
+  const parts = {
+    id: void 0,
+    event: void 0,
+    dataLines: []
+  };
+  for (const rawLine of block.split(`
+`))
+    applyServerSentEventLine(parts, rawLine);
+  return frameFromParts(parts);
+}
+function applyServerSentEventLine(parts, rawLine) {
+  if (rawLine === "" || rawLine.startsWith(":"))
+    return;
+  const { field, value } = splitServerSentEventLine(rawLine);
+  if (field === "id")
+    parts.id = value;
+  else if (field === "event")
+    parts.event = value;
+  else if (field === "data")
+    parts.dataLines.push(value);
+}
+function splitServerSentEventLine(rawLine) {
+  const separator = rawLine.indexOf(":"), field = separator === -1 ? rawLine : rawLine.slice(0, separator), rawValue = separator === -1 ? "" : rawLine.slice(separator + 1);
+  return {
+    field,
+    value: rawValue.startsWith(" ") ? rawValue.slice(1) : rawValue
+  };
+}
+function frameFromParts(parts) {
+  if (parts.id === void 0 && parts.event === void 0 && parts.dataLines.length === 0)
+    return null;
+  return {
+    ...parts.id === void 0 ? {} : { id: parts.id },
+    ...parts.event === void 0 ? {} : { event: parts.event },
+    data: parts.dataLines.join(`
+`)
+  };
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseWorkflowEventEnvelope(data) {
+  const parsed = parseJson(data);
+  if (!isRecord(parsed))
+    return null;
+  return workflowEventEnvelopeFromRecord(parsed);
+}
+function isReplayCompletePing(data) {
+  const parsed = parseJson(data);
+  return isRecord(parsed) && parsed.replayComplete === !0;
+}
+function parseJson(data) {
+  try {
+    return JSON.parse(data);
+  } catch {
+    return null;
+  }
+}
+function workflowEventEnvelopeFromRecord(parsed) {
+  if (typeof parsed.kind !== "string")
+    return null;
+  if (typeof parsed.workflowId !== "string")
+    return null;
+  if (!isWorkflowEventSelector(parsed.selector))
+    return null;
+  const sequence = finiteNumber(parsed.sequence);
+  if (sequence === null)
+    return null;
+  if (typeof parsed.cursor !== "string")
+    return null;
+  const emittedAtMs = finiteNumber(parsed.emittedAtMs);
+  if (emittedAtMs === null)
+    return null;
+  if (!Object.hasOwn(parsed, "payload"))
+    return null;
+  return {
+    kind: parsed.kind,
+    workflowId: parsed.workflowId,
+    selector: parsed.selector,
+    sequence,
+    cursor: parsed.cursor,
+    emittedAtMs,
+    payload: parsed.payload
+  };
+}
+function isWorkflowEventSelector(value) {
+  return value === "events" || value === "tokens";
+}
+function finiteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function envelopeToWorkflowEvent(envelope) {
+  return {
+    type: envelope.kind,
+    timestamp: envelope.emittedAtMs,
+    data: isRecord(envelope.payload) ? envelope.payload : { value: envelope.payload }
+  };
+}
+function isEventStreamResponse(response) {
+  const contentType = response.headers.get("Content-Type");
+  if (contentType === null)
+    return !1;
+  return contentType.split(";", 1)[0]?.trim().toLowerCase() === "text/event-stream";
+}
+
+export class SseWorkflowEventSubscription {
+  #url;
+  #headers;
+  #workflowId;
+  #onEvent;
+  #maxReconnectAttempts;
+  #reconnectBackoffMs;
+  #lifecycle;
+  #connected = Promise.withResolvers();
+  #abortController = null;
+  #reconnectAttempts = 0;
+  #reconnectTimer = null;
+  #lastEventId = null;
+  constructor(url, headers, workflowId, onEvent, options) {
+    this.#url = url;
+    this.#headers = headers;
+    this.#workflowId = workflowId;
+    this.#onEvent = onEvent;
+    this.#maxReconnectAttempts = options?.maxReconnectAttempts ?? DEFAULT_MAX_RECONNECT_ATTEMPTS;
+    this.#reconnectBackoffMs = options?.reconnectBackoffMs ?? DEFAULT_RECONNECT_BACKOFF_MS;
+    this.#lifecycle = new WorkflowEventTailLifecycle({
+      bufferForIteration: options?.bufferForIteration ?? !1,
+      onClose: (reason) => this.#onLifecycleClose(reason)
+    });
+    this.#connect();
+  }
+  get closeReason() {
+    return this.#lifecycle.closeReason;
+  }
+  whenConnected() {
+    return this.#connected.promise;
+  }
+  async#connect() {
+    if (this.#lifecycle.closed)
+      return;
+    const abortController = new AbortController;
+    this.#abortController = abortController;
+    try {
+      const response = await fetch(this.#url, {
+        headers: this.#requestHeaders(),
+        signal: abortController.signal
+      });
+      if (!response.ok || response.body === null) {
+        this.#terminate("server-error");
+        return;
+      }
+      if (!isEventStreamResponse(response)) {
+        this.#terminate("server-error");
+        return;
+      }
+      await this.#readResponseBody(response.body);
+      if (!this.#lifecycle.closed)
+        this.#scheduleReconnect();
+    } catch {
+      if (!this.#lifecycle.closed)
+        this.#scheduleReconnect();
+    } finally {
+      if (this.#abortController === abortController)
+        this.#abortController = null;
+    }
+  }
+  #requestHeaders() {
+    const headers = new Headers(this.#headers);
+    headers.set("Accept", "text/event-stream");
+    headers.set("Cache-Control", "no-cache");
+    if (this.#lastEventId !== null)
+      headers.set("Last-Event-ID", this.#lastEventId);
+    return headers;
+  }
+  async#readResponseBody(body) {
+    const reader = body.getReader(), decoder = new TextDecoder;
+    let remainder = "";
+    try {
+      while (!this.#lifecycle.closed) {
+        const chunk = await reader.read();
+        if (chunk.done)
+          return;
+        const parsed = parseServerSentEventChunk(decoder.decode(chunk.value, { stream: !0 }), remainder);
+        remainder = parsed.remainder;
+        for (const frame of parsed.frames) {
+          const handling = this.#handleFrame(frame);
+          if (this.#lifecycle.closed || handling === "server-error")
+            return;
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+  #handleFrame(frame) {
+    if (frame.event === "ping") {
+      this.#markHealthyFrame();
+      if (isReplayCompletePing(frame.data))
+        this.#markConnected();
+      return "healthy";
+    }
+    if (frame.event === "error") {
+      this.#terminate("server-error");
+      return "server-error";
+    }
+    const envelope = parseWorkflowEventEnvelope(frame.data);
+    if (envelope === null)
+      return "ignored";
+    if (envelope.workflowId !== this.#workflowId)
+      return "ignored";
+    this.#lastEventId = frame.id ?? envelope.cursor;
+    this.#markHealthyFrame();
+    this.#emit(envelopeToWorkflowEvent(envelope));
+    return "healthy";
+  }
+  #emit(event) {
+    if (!this.#lifecycle.emit(event, this.#onEvent))
+      return;
+    if (WORKFLOW_TERMINAL_EVENT_TYPES.has(event.type))
+      this.#terminate("workflow-terminal");
+  }
+  #scheduleReconnect() {
+    if (this.#lifecycle.closed || this.#reconnectTimer !== null)
+      return;
+    if (this.#reconnectAttempts >= this.#maxReconnectAttempts) {
+      this.#terminate("reconnect-exhausted");
+      return;
+    }
+    this.#reconnectAttempts += 1;
+    const delay = this.#reconnectBackoffMs * this.#reconnectAttempts;
+    this.#reconnectTimer = setTimeout(() => {
+      this.#reconnectTimer = null;
+      this.#connect();
+    }, delay);
+  }
+  #markConnected() {
+    this.#connected.resolve();
+  }
+  #markHealthyFrame() {
+    this.#reconnectAttempts = 0;
+  }
+  #terminate(reason) {
+    this.#lifecycle.terminate(reason);
+  }
+  #onLifecycleClose(_reason) {
+    this.#markConnected();
+    if (this.#reconnectTimer !== null) {
+      clearTimeout(this.#reconnectTimer);
+      this.#reconnectTimer = null;
+    }
+    this.#abortController?.abort();
+    this.#abortController = null;
+  }
+  close() {
+    this.#lifecycle.close();
+  }
+  [Symbol.asyncIterator]() {
+    return this.#lifecycle[Symbol.asyncIterator]();
+  }
+}

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

@@ -1,5 +1,5 @@
 import type { ScheduleSpec, StartOrSignalSignal } from '../core/types.ts';
-import type { ClientStartOptions } from './interface.ts';
+import type { ClientStartOptions, ClientStartOrSignalOptions } 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
@@ -13,4 +13,4 @@ export declare function buildStartBody(type: string, input: unknown, options?: C
  * 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>;
+export declare function buildStartOrSignalBody(type: string, input: unknown, signal: StartOrSignalSignal, options?: ClientStartOrSignalOptions): Record<string, unknown>;

package/dist/client/start-body.js

@@ -28,5 +28,6 @@ export function buildStartOrSignalBody(type, input, signal, options) {
   setIfDefined(body, "signalPayload", signal.payload);
   setIfDefined(body, "signalId", signal.signalId);
   applyStartOptionsToBody(body, options);
+  setIfDefined(body, "onTerminalConflict", options?.onTerminalConflict);
   return body;
 }

package/dist/core/engine/construction.js

@@ -6,6 +6,7 @@ import { WorkerPool } from "../../workers/pool.js";
 import { optionalInlineDependencies } from "../inline-execution-strategy.context-options.js";
 import { InlineExecutionStrategy } from "../inline-execution-strategy.js";
 import {
+  DEFAULT_POLL_INTERVAL_MS,
   DEFAULT_RETENTION_SWEEP_BATCH_SIZE,
   DEFAULT_RETENTION_SWEEP_INTERVAL_MS
 } from "../types.js";
@@ -96,7 +97,8 @@ function resolveNumericDefaults(options) {
   return {
     checkpointHistory: defaultTo(options?.checkpointHistory, 10),
     checkpointSizeWarningThreshold: defaultTo(options?.checkpointSizeWarningThreshold, 65536),
-    maxNestingDepth: defaultTo(options?.maxNestingDepth, 10)
+    maxNestingDepth: defaultTo(options?.maxNestingDepth, 10),
+    schedulerPollIntervalMs: normalizePositiveSafeIntegerOption(options?.schedulerPollIntervalMs, "options.schedulerPollIntervalMs", DEFAULT_POLL_INTERVAL_MS) ?? DEFAULT_POLL_INTERVAL_MS
   };
 }
 function resolveHistoryFields(options) {

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

@@ -27,6 +27,8 @@ export interface ResolvedOptions {
     checkpointHistory: number;
     checkpointSizeWarningThreshold: number;
     maxNestingDepth: number;
+    /** Durable-timer scheduler poll interval (ms). */
+    schedulerPollIntervalMs: number;
     broadcastEvents: boolean;
     retention: NormalizedRetentionPolicy | null;
     retentionSweepIntervalMs: number;

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

@@ -289,14 +289,14 @@ export declare class ActivityResolutionError extends WeftError<'ActivityResoluti
 /**
  * Thrown by {@link Engine.startOrSignal} when the target workflow already exists
  * and is in a terminal state (completed, failed, cancelled, or timed out). A
- * terminal run cannot accept a signal and must not be silently replaced, so
- * `startOrSignal` surfaces this conflict instead of starting a fresh run under
- * the same id or dropping the signal.
+ * terminal run cannot accept a signal. By default `startOrSignal` surfaces this
+ * conflict instead of starting a fresh run under the same id or dropping the
+ * signal.
  *
  * Inspect `workflowId` to identify the conflicting run and `status` to see why
- * it was rejected. To deliberately start a new run, choose a different id (or
- * idempotency key); to deliver to a fresh run, terminal-state reuse is not a
- * supported policy.
+ * it was rejected. To deliberately reuse a stable id, call `startOrSignal` with
+ * `onTerminalConflict: 'start-new'`, an explicit `id`, and a deterministic
+ * `signalId`; otherwise choose a different id or idempotency key.
  *
  * @example
  * ```ts

package/dist/core/engine/errors.js

@@ -118,7 +118,7 @@ export class StartOrSignalConflictError extends WeftError {
   workflowId;
   status;
   constructor(workflowId, status) {
-    super("StartOrSignalConflictError", `Workflow "${workflowId}" is already in terminal state "${status}" and cannot accept a startOrSignal: a terminal run cannot be signalled and is not replaced. Use a different id or idempotency key to start a new run.`);
+    super("StartOrSignalConflictError", `Workflow "${workflowId}" is already in terminal state "${status}" and cannot accept a startOrSignal. Use options.onTerminalConflict: 'start-new' with an explicit id and signalId, or choose a different id or idempotency key to start a new run.`);
     this.workflowId = workflowId;
     this.status = status;
   }

package/dist/core/engine/handles.js

@@ -129,7 +129,7 @@ export class WorkflowHandle extends EventTarget {
             observer.error?.(event.error);
           } else if (event instanceof WorkflowTimedOutEvent) {
             terminalDelivered = !0;
-            observer.error?.(new WorkflowTimeoutError(event.workflowId, event.timeoutType, event.elapsed));
+            observer.error?.(new WorkflowTimeoutError(event.workflowId, event.timeoutType, event.elapsed, event.reason));
           }
         };
         this.addEventListener("workflow:failed", errorHandler, { signal: controller.signal });

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

@@ -5,7 +5,7 @@ import type { TypedEventTarget, WeftEventMap } from '../events.ts';
 import type { Interceptor } from '../interceptor.ts';
 import { type ReviewRequest } from '../review/index.ts';
 import { Scheduler } from '../scheduler.ts';
-import { type AnyActivityDefinition, type AnyWorkflowDefinition, type AttributeFilterKey, type BulkCancelResult, type BulkDeleteResult, type BulkOperationCommitOptions, type BulkOperationDryRunOptions, type BulkOperationDryRunResult, type BulkRetryFailedResult, type BulkSignalAllCommitOptions, type BulkSignalAllDryRunOptions, type BulkSignalResult, type BulkTagResult, type CheckpointState, type CheckpointSummary, type CoordinatedUpdateResult, type DefaultActivityTypes, type DefaultWorkflowRegistry, type ForkOptions, type InferActivityEntries, type InferActivityEntry, type InferWorkflowEntries, type InferWorkflowEntry, type ListFilter, type ListOptions, type PaginatedResult, type PurgeResult, type QueryDefinition, type RegisteredWorkflowDefinition, type RetentionOverview, type ReviewListEntry, type ReviewListFilter, type ScheduleDefinition, type ScheduleFilter, type ScheduleOptions, type ScheduleSpec, type ScheduleSummary, type SearchAttributeValue, type SignalDefinition, type SignalDeliveryOptions, type StartOptions, type StartOrSignalSignal, type StartWorkflowOptions, type SubmitReviewOptions, type TypedListFilter, type UpdateDefinition, type WorkflowEvent, type WorkflowInput, type WorkflowOutput, type WorkflowReplay, type WorkflowServices, type WorkflowServicesUnion, type WorkflowState, type WorkflowSummary, type WorkflowTimelineEntry } from '../types.ts';
+import { type AnyActivityDefinition, type AnyWorkflowDefinition, type AttributeFilterKey, type BulkCancelResult, type BulkDeleteResult, type BulkOperationCommitOptions, type BulkOperationDryRunOptions, type BulkOperationDryRunResult, type BulkRetryFailedResult, type BulkSignalAllCommitOptions, type BulkSignalAllDryRunOptions, type BulkSignalResult, type BulkTagResult, type CheckpointState, type CheckpointSummary, type CoordinatedUpdateResult, type DefaultActivityTypes, type DefaultWorkflowRegistry, type ForkOptions, type InferActivityEntries, type InferActivityEntry, type InferWorkflowEntries, type InferWorkflowEntry, type ListFilter, type ListOptions, type PaginatedResult, type PurgeResult, type QueryDefinition, type RegisteredWorkflowDefinition, type RetentionOverview, type ReviewListEntry, type ReviewListFilter, type ScheduleDefinition, type ScheduleFilter, type ScheduleOptions, type ScheduleSpec, type ScheduleSummary, type SearchAttributeValue, type SignalDefinition, type SignalDeliveryOptions, type StartOrSignalOptions, type StartOrSignalSignal, type StartWorkflowOptions, type SubmitReviewOptions, type TypedListFilter, type UpdateDefinition, type WorkflowEvent, type WorkflowInput, type WorkflowOutput, type WorkflowReplay, type WorkflowServices, type WorkflowServicesUnion, type WorkflowState, type WorkflowSummary, type WorkflowTimelineEntry } from '../types.ts';
 import type { TimerEntry } from '../types/checkpoint.ts';
 import type { WorkflowAlreadyRegistered } from '../types/workflow-builder.ts';
 import { type AggregateOptions, type AggregateResult } from './aggregate.ts';
@@ -202,8 +202,9 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
      * first signal commit in one batch and the freshly-launched run consumes the
      * signal on its first drive. A non-terminal target (running, pending, or
      * suspended) is signalled through the normal signal path; a terminal target
-     * throws {@link StartOrSignalConflictError} rather than starting a new run or
-     * dropping the signal.
+     * throws {@link StartOrSignalConflictError} unless
+     * `options.onTerminalConflict: 'start-new'` is supplied with an explicit
+     * workflow id and deterministic `signal.signalId`.
      *
      * Concurrent callers converge on one workflow and one delivered signal. Pass
      * `options.idempotencyKey` to dedup independent callers (e.g. retried
@@ -213,8 +214,8 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
      * are `options.id` and `options.idempotencyKey`. Requires a storage backend
      * with `conditionalBatch`.
      */
-    startOrSignal<TName extends KnownWorkflowNames<TWorkflows>>(type: TName, input: WorkflowInput<TWorkflows, TName>, signal: StartOrSignalSignal, options?: StartOptions<WorkflowServices<TWorkflows, TName>>): Promise<StartOrSignalResult<WorkflowOutput<TWorkflows, TName>>>;
-    startOrSignal<TName extends string>(type: UnknownWorkflowNameWhenDefaultRegistryIsEmpty<TWorkflows, TName>, input: unknown, signal: StartOrSignalSignal, options?: StartOptions): Promise<StartOrSignalResult>;
+    startOrSignal<TName extends KnownWorkflowNames<TWorkflows>>(type: TName, input: WorkflowInput<TWorkflows, TName>, signal: StartOrSignalSignal, options?: StartOrSignalOptions<WorkflowServices<TWorkflows, TName>>): Promise<StartOrSignalResult<WorkflowOutput<TWorkflows, TName>>>;
+    startOrSignal<TName extends string>(type: UnknownWorkflowNameWhenDefaultRegistryIsEmpty<TWorkflows, TName>, input: unknown, signal: StartOrSignalSignal, options?: StartOrSignalOptions): Promise<StartOrSignalResult>;
     getHandle(workflowId: string): WorkflowHandle;
     list<const TAttributeKeys extends readonly AttributeFilterKey[] = readonly AttributeFilterKey[]>(filter?: TypedListFilter<TAttributeKeys>, options?: ListOptions): Promise<PaginatedResult<WorkflowSummary>>;
     aggregate(filter: ListFilter | undefined, options: AggregateOptions): Promise<AggregateResult>;

package/dist/core/engine/index.js

@@ -289,6 +289,7 @@ export class Engine extends EventTarget {
     getInternals(this).scheduler = new Scheduler({
       storage,
       onTimerFired: (entry) => handleTimerFiredFromInternals(getInternals(this), entry, this.#createTimeOperationCallbacks()),
+      pollIntervalMs: resolvedOptions.schedulerPollIntervalMs,
       getNow,
       commitTimerCleanup: (operations) => commitFencedEngineWrite(getInternals(this), operations, [], () => Error("Timer cleanup lost its fenced CAS race"))
     });

package/dist/core/engine/lifecycle/recovered-services.js

@@ -24,7 +24,8 @@ export async function reprovideRecoveredServices(internals, state, failRun, onCo
     const resolution = await resolver({
       workflowId: state.id,
       workflowType: state.type,
-      input: state.input
+      input: state.input,
+      launchOptions: launchOptionsFromWorkflowState(state)
     });
     if (resolution.status === "available") {
       internals.workflowServices.set(state.id, resolution.services);
@@ -47,3 +48,9 @@ export function unavailableServicesError(workflowId, reason) {
 function missingServicesResolverReason(workflowId) {
   return `Workflow "${workflowId}" was started with services, but this engine has no resolveWorkflowServices option. Configure EngineOptions.resolveWorkflowServices before recovery so ctx.services can be re-provided.`;
 }
+function launchOptionsFromWorkflowState(state) {
+  return {
+    id: state.id,
+    ...state.tags !== void 0 && state.tags.length > 0 ? { tags: [...state.tags] } : {}
+  };
+}

package/dist/core/engine/lifecycle/start-or-signal-create.d.ts

@@ -7,7 +7,7 @@
  *
  * @module core/engine/lifecycle/start-or-signal-create
  */
-import type { StartOptions, StartOrSignalSignal } from '../../types.ts';
+import type { StartOrSignalOptions, StartOrSignalSignal } from '../../types.ts';
 import { type StartOrSignalOutcome, type WorkflowHandle } from '../handles.ts';
 import type { EngineInternals } from '../internals.ts';
 import { type BuildIdempotentStartOperations } from './start-commit.ts';
@@ -55,4 +55,4 @@ export type StartOrSignalResult<TResult = unknown> = {
  *   (scan-then-park), and the caller's payload loses to the pre-buffered one by
  *   the same first-wins dedup.
  */
-export declare function createWithSignalOrFallback(internals: EngineInternals, type: string, input: unknown, signalSpec: StartOrSignalSignal, signalId: string, options: StartOptions | undefined, callbacks: StartOrSignalCallbacks): Promise<StartOrSignalResult>;
+export declare function createWithSignalOrFallback(internals: EngineInternals, type: string, input: unknown, signalSpec: StartOrSignalSignal, signalId: string, options: StartOrSignalOptions | undefined, callbacks: StartOrSignalCallbacks): Promise<StartOrSignalResult>;

package/dist/core/engine/lifecycle/start-or-signal-create.js

@@ -44,23 +44,25 @@ export async function createWithSignalOrFallback(internals, type, input, signalS
     });
     if (outcome.kind === "created")
       return { handle: outcome.handle, outcome: "started" };
-    if (outcome.kind === "lost-keyed")
-      return {
-        handle: await resolveWinnerWithSignal(internals, outcome.id, signalSpec, signalId, callbacks, outcome.idempotencyKey),
-        outcome: "signalled"
-      };
-    if (outcome.kind === "lost-caller-id") {
-      const resolved = await resolveCallerIdWinnerOrRetry(internals, outcome.id, signalSpec, signalId, callbacks);
-      if (resolved !== void 0)
-        return { handle: resolved, outcome: "signalled" };
-    } else {
-      const resolved = await plainCreateBufferedSignalOrResolve(internals, type, input, signalSpec, signalId, options, callbacks);
-      if (resolved !== void 0)
-        return resolved;
-    }
+    const resolved = await resolveCreateFallbackOutcome(internals, outcome, type, input, signalSpec, signalId, options, callbacks);
+    if (resolved !== void 0)
+      return resolved;
   }
   throw Error(`startOrSignal could not create workflow "${options?.id ?? "<generated>"}" after ${CALLER_ID_CREATE_MAX_ATTEMPTS} attempts: each concurrent same-id winner aborted before its durable commit.`);
 }
+async function resolveCreateFallbackOutcome(internals, outcome, type, input, signalSpec, signalId, options, callbacks) {
+  if (outcome.kind === "lost-keyed")
+    return {
+      handle: await resolveWinnerWithSignal(internals, outcome.id, signalSpec, signalId, callbacks, outcome.idempotencyKey),
+      outcome: "signalled"
+    };
+  const allowTerminalRestart = options?.onTerminalConflict === "start-new";
+  if (outcome.kind === "lost-caller-id") {
+    const resolved = await resolveCallerIdWinnerOrRetry(internals, outcome.id, signalSpec, signalId, callbacks, allowTerminalRestart);
+    return resolved === void 0 ? void 0 : { handle: resolved, outcome: "signalled" };
+  }
+  return plainCreateBufferedSignalOrResolve(internals, type, input, signalSpec, signalId, options, callbacks);
+}
 async function plainCreateBufferedSignalOrResolve(internals, type, input, signalSpec, signalId, options, callbacks) {
   try {
     return {
@@ -70,7 +72,7 @@ async function plainCreateBufferedSignalOrResolve(internals, type, input, signal
   } catch (error) {
     if (!(error instanceof WorkflowAlreadyExistsError))
       throw error;
-    const resolved = await resolveCallerIdWinnerOrRetry(internals, error.workflowId, signalSpec, signalId, callbacks);
+    const resolved = await resolveCallerIdWinnerOrRetry(internals, error.workflowId, signalSpec, signalId, callbacks, options?.onTerminalConflict === "start-new");
     return resolved === void 0 ? void 0 : { handle: resolved, outcome: "signalled" };
   }
 }

package/dist/core/engine/lifecycle/start-or-signal-resolution.d.ts

@@ -47,7 +47,7 @@ export declare function resolveExistingRunOrThrowPurged(internals: EngineInterna
  *   committing (storage failure, oversized payload, throwing start interceptor): no
  *   run exists, so return `undefined` and let the caller retry its own create.
  */
-export declare function resolveCallerIdWinnerOrRetry(internals: EngineInternals, winnerId: string, signalSpec: StartOrSignalSignal, signalId: string, callbacks: StartOrSignalCallbacks): Promise<WorkflowHandle | undefined>;
+export declare function resolveCallerIdWinnerOrRetry(internals: EngineInternals, winnerId: string, signalSpec: StartOrSignalSignal, signalId: string, callbacks: StartOrSignalCallbacks, allowTerminalRestart?: boolean): Promise<WorkflowHandle | undefined>;
 /**
  * For a workflow that already exists: signal it if non-terminal, conflict if
  * terminal. Returns the handle on a successful signal, or `undefined` when the

package/dist/core/engine/lifecycle/start-or-signal-resolution.js

@@ -23,12 +23,30 @@ async function awaitReservationCleared(internals, workflowId) {
     await sleep(RESERVATION_CLEAR_RETRY_DELAY_MS);
   }
 }
-export async function resolveCallerIdWinnerOrRetry(internals, winnerId, signalSpec, signalId, callbacks) {
-  const resolved = await signalOrConflictExistingWorkflow(internals, winnerId, signalSpec, signalId, callbacks);
-  if (resolved !== void 0)
-    return resolved;
+export async function resolveCallerIdWinnerOrRetry(internals, winnerId, signalSpec, signalId, callbacks, allowTerminalRestart = !1) {
+  const state = await loadWorkflowState(internals, winnerId);
+  if (state !== null) {
+    if (!isTerminalWorkflowStatus(state.status)) {
+      await callbacks.signalExistingWorkflow(winnerId, signalSpec.name, signalSpec.payload, signalId);
+      return callbacks.getHandle(winnerId);
+    }
+    if (!allowTerminalRestart)
+      throw new StartOrSignalConflictError(winnerId, state.status);
+  }
   await awaitReservationCleared(internals, winnerId);
-  return signalOrConflictExistingWorkflow(internals, winnerId, signalSpec, signalId, callbacks);
+  const stateAfterReservation = await loadWorkflowState(internals, winnerId);
+  if (stateAfterReservation === null)
+    return;
+  if (isTerminalWorkflowStatus(stateAfterReservation.status)) {
+    if (state !== null && isSameTerminalRun(state, stateAfterReservation))
+      return;
+    throw new StartOrSignalConflictError(winnerId, stateAfterReservation.status);
+  }
+  await callbacks.signalExistingWorkflow(winnerId, signalSpec.name, signalSpec.payload, signalId);
+  return callbacks.getHandle(winnerId);
+}
+function isSameTerminalRun(before, after) {
+  return before.id === after.id && before.type === after.type && before.status === after.status && before.createdAt === after.createdAt && before.updatedAt === after.updatedAt && before.terminalCleanupToken === after.terminalCleanupToken;
 }
 export async function signalOrConflictExistingWorkflow(internals, workflowId, signalSpec, signalId, callbacks) {
   const state = await loadWorkflowState(internals, workflowId);

package/dist/core/engine/lifecycle/start-or-signal.d.ts

@@ -1,4 +1,4 @@
-import type { StartOptions, StartOrSignalSignal } from '../../types.ts';
+import type { StartOptions, StartOrSignalOptions, StartOrSignalSignal } from '../../types.ts';
 import { type WorkflowHandle } from '../handles.ts';
 import type { EngineInternals } from '../internals.ts';
 import { type LifecycleCallbacks } from './shared.ts';
@@ -28,8 +28,10 @@ export declare function startWithIdempotency(internals: EngineInternals, type: s
  * - **Non-terminal** (running, pending, suspended) → deliver the signal through
  *   the standard engine signal path with the same `signalId`, so it dedups
  *   against a create-batch signal a concurrent winner may have written.
- * - **Terminal** → throw {@link StartOrSignalConflictError}: a finished run
- *   cannot be signalled and is not silently replaced.
+ * - **Terminal** → throw {@link StartOrSignalConflictError} by default. With
+ *   `options.onTerminalConflict: 'start-new'`, purge the prior terminal run
+ *   through the shared terminal-replacement path, start a fresh run, and deliver
+ *   the initial signal in the create batch.
  *
  * Convergence requires a SHARED workflow identity. Concurrent callers converge on
  * one workflow and one signal only when they share an `options.idempotencyKey`
@@ -43,4 +45,4 @@ export declare function startWithIdempotency(internals: EngineInternals, type: s
  * convergence primitive. Use `idempotencyKey` (id-free convergence) or
  * `id` + `signalId` when concurrent callers must converge.
  */
-export declare function startOrSignal(internals: EngineInternals, type: string, input: unknown, signalSpec: StartOrSignalSignal, options: StartOptions | undefined, callbacks: StartOrSignalCallbacks): Promise<StartOrSignalResult>;
+export declare function startOrSignal(internals: EngineInternals, type: string, input: unknown, signalSpec: StartOrSignalSignal, options: StartOrSignalOptions | undefined, callbacks: StartOrSignalCallbacks): Promise<StartOrSignalResult>;