@lostgradient/weft 0.3.0 → 0.5.0

package/dist/core/engine/event-log-compaction.js

@@ -2,6 +2,10 @@ import { hashBytes } from "../../runtime/portable.js";
 import { KEYS } from "../../storage/interface.js";
 import { decode, encode } from "../codec.js";
 import { isWorkflowLogEntry } from "../event-log-shared.js";
+import {
+  mergeCheckpointReplayPayloads,
+  readCheckpointReplayPayload
+} from "./checkpoint-replay.js";
 export const MAX_COMPACTION_BATCH = 1000;
 export function isEventLogWatermark(value) {
   if (typeof value !== "object" || value === null)
@@ -27,7 +31,7 @@ export async function readEventLogWatermark(storage, workflowId) {
 export async function appendCompactionOperations(storage, workflowId, headSequence, retentionWindow, operations) {
   if (retentionWindow === null)
     return null;
-  const targetFirstSurviving = Math.max(0, headSequence - retentionWindow + 1), currentFloor = (await readEventLogWatermark(storage, workflowId))?.sequence ?? 0, batchFirstSurviving = Math.min(targetFirstSurviving, currentFloor + MAX_COMPACTION_BATCH);
+  const targetFirstSurviving = Math.max(0, headSequence - retentionWindow + 1), existing = await readEventLogWatermark(storage, workflowId), currentFloor = existing?.sequence ?? 0, batchFirstSurviving = Math.min(targetFirstSurviving, currentFloor + MAX_COMPACTION_BATCH);
   if (batchFirstSurviving <= currentFloor)
     return null;
   const collected = await collectDeleteRange(storage, workflowId, currentFloor, batchFirstSurviving);
@@ -38,7 +42,8 @@ export async function appendCompactionOperations(storage, workflowId, headSequen
     version: 1,
     sequence: batchFirstSurviving,
     prevHash,
-    deletedThrough: batchFirstSurviving - 1
+    deletedThrough: batchFirstSurviving - 1,
+    ...optionalCheckpointReplay(mergeDeletedCheckpointReplayPayloads(existing?.checkpointReplay, collected.deletedEntries))
   };
   for (let sequence = currentFloor;sequence < batchFirstSurviving; sequence += 1)
     operations.push({ type: "delete", key: KEYS.event(workflowId, sequence) });
@@ -53,6 +58,19 @@ export async function appendCompactionOperations(storage, workflowId, headSequen
     deletedRange: { from: currentFloor, to: batchFirstSurviving - 1 }
   };
 }
+function optionalCheckpointReplay(checkpointReplay) {
+  return checkpointReplay === void 0 ? {} : { checkpointReplay };
+}
+function mergeDeletedCheckpointReplayPayloads(existing, deletedEntries) {
+  let merged = existing;
+  for (const bytes of deletedEntries) {
+    const decoded = decode(bytes);
+    if (!isWorkflowLogEntry(decoded))
+      continue;
+    merged = mergeCheckpointReplayPayloads(merged, readCheckpointReplayPayload(decoded.payload));
+  }
+  return merged;
+}
 async function collectDeleteRange(storage, workflowId, currentFloor, batchFirstSurviving) {
   const deletedEntries = [];
   let expected = currentFloor;

package/dist/core/engine/fenced-write.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Step-2 epoch fencing for `ownership: 'lease'` (issue #470).
+ *
+ * Step 1 made a rolling deploy a clean lease handoff but added no correctness
+ * backstop: a deposed zombie instance (GC pause, partition) that emerged after
+ * its lease expired could still issue a plain durable write and corrupt the
+ * successor's state. Step 2 closes that hole by conditioning every
+ * engine-generator-owned per-workflow durable write on the held lease epoch, so
+ * a deposed instance's write loses its CAS instead of landing.
+ *
+ * The correctness guarantee lives entirely in the epoch CONDITION: a deposed
+ * instance's commit CAS-fails regardless of any in-process flag, because the
+ * successor bumped `lease:epoch` when it took over. The {@link EngineInternals.deposed}
+ * flag and the engine teardown are hygiene on top of that — they stop the engine
+ * from silently spinning on swallowed write losses, surface the deposition to the
+ * operator, and release resources. They are not what makes the system safe.
+ *
+ * This module is allow-listed for import only from `src/core/engine/**`.
+ */
+import type { BatchOperation, ConditionalBatchCondition } from '../../storage/interface.ts';
+import type { EngineInternals } from './internals.ts';
+/**
+ * Reject an engine-owned work entry point (start, startOrSignal, fork, resume)
+ * when `ownership: 'lease'` is configured but the engine does not currently hold
+ * the lease. The lease is acquired at the two boot gates ({@link Engine.create}
+ * and {@link Engine.recoverAll}); a directly constructed engine that does engine
+ * work before `recoverAll()` would otherwise durably write workflow state without
+ * single-writer ownership and without having recovered existing runs. Placed at
+ * each public awaited entry so the caller gets a clean {@link EngineLeaseNotHeldError}
+ * — without this, fork/resume would reach `resolveFenceEpochOrHalt` with no held
+ * epoch and be misreported as a deposition (warn + teardown) rather than the true
+ * "lease not held yet" condition. A no-op under `ownership: 'none'`.
+ */
+export declare function assertLeaseHeldForEngineWork(internals: EngineInternals): void;
+/**
+ * Commit an engine-generator-owned durable write, fenced on the held lease epoch
+ * under `ownership: 'lease'` (a byte-for-byte no-op under `ownership: 'none'`). A
+ * lost CAS race throws the caller-supplied `onLostRace` error so existing retry
+ * semantics apply; a deposition halts the engine and throws
+ * {@link EngineDeposedError}. The helper owns the batch-vs-conditionalBatch
+ * decision — pass plain operations plus whatever base conditions you already need.
+ *
+ * @param internals - the engine internals (ownership mode, lease manager, deposed flag)
+ * @param operations - the durable operations to commit atomically
+ * @param baseConditions - CAS conditions the caller already requires (may be empty)
+ * @param onLostRace - builds the error thrown on a same-epoch lost CAS race
+ */
+export declare function commitFencedEngineWrite(internals: EngineInternals, operations: BatchOperation[], baseConditions: ConditionalBatchCondition[], onLostRace: () => Error): Promise<void>;
+/**
+ * Like {@link commitFencedEngineWrite}, but the caller treats a base-precondition
+ * failure as a legitimate outcome rather than an error — used by the idempotent
+ * start path, where a `false` means a concurrent same-key caller already wrote the
+ * record (resolve to the existing run) rather than "retry". Returns `true` when the
+ * batch committed and `false` when a base condition failed. Deposition is still a
+ * hard halt: if the epoch condition is the one that failed, this drives
+ * {@link handleDeposition} and throws {@link EngineDeposedError} — a deposed engine
+ * must never report a precondition-failure the caller would read as "already exists"
+ * and silently move on.
+ *
+ * @param internals - the engine internals
+ * @param operations - the durable operations to commit atomically
+ * @param baseConditions - the caller's required CAS conditions (non-empty in
+ *   practice — this path is for conditional starts, which always carry one)
+ */
+export declare function commitFencedEngineWriteAllowingPreconditionFailure(internals: EngineInternals, operations: BatchOperation[], baseConditions: ConditionalBatchCondition[]): Promise<boolean>;

package/dist/core/engine/fenced-write.js

@@ -0,0 +1,71 @@
+import { KEYS, storageConditionalBatch } from "../../storage/interface.js";
+import { decodeEpoch } from "./lease-codec.js";
+import { handleDeposition } from "./lease-deposition.js";
+import { EngineDeposedError, EngineLeaseNotHeldError } from "./lease-errors.js";
+export function assertLeaseHeldForEngineWork(internals) {
+  if (internals.options.ownershipMode !== "lease")
+    return;
+  if (!(!internals.deposed && internals.leaseManager !== null && internals.leaseManager.currentEpochBytes() !== null))
+    throw new EngineLeaseNotHeldError;
+}
+async function fencedCommit(internals, operations, baseConditions) {
+  const epochBytes = resolveFenceEpochOrHalt(internals);
+  if (epochBytes === null) {
+    if (baseConditions.length === 0) {
+      await internals.storage.batch(operations);
+      return "committed";
+    }
+    return await storageConditionalBatch(internals.storage, baseConditions, operations) ? "committed" : "lost-race";
+  }
+  const conditions = [
+    ...baseConditions,
+    { key: KEYS.leaseEpoch(), expectedValue: epochBytes }
+  ];
+  if (await storageConditionalBatch(internals.storage, conditions, operations))
+    return "committed";
+  if (await isDeposed(internals, epochBytes)) {
+    handleDeposition(internals);
+    throw new EngineDeposedError;
+  }
+  return "lost-race";
+}
+function resolveFenceEpochOrHalt(internals) {
+  if (internals.deposed)
+    throw new EngineDeposedError;
+  if (internals.options.ownershipMode !== "lease")
+    return null;
+  const epochBytes = internals.leaseManager?.currentEpochBytes() ?? null;
+  if (epochBytes === null) {
+    handleDeposition(internals);
+    throw new EngineDeposedError;
+  }
+  return epochBytes;
+}
+export async function commitFencedEngineWrite(internals, operations, baseConditions, onLostRace) {
+  if (await fencedCommit(internals, operations, baseConditions) === "lost-race")
+    throw onLostRace();
+}
+export async function commitFencedEngineWriteAllowingPreconditionFailure(internals, operations, baseConditions) {
+  return await fencedCommit(internals, operations, baseConditions) === "committed";
+}
+function epochBytesEqual(a, b) {
+  if (b === null || a.byteLength !== b.byteLength)
+    return !1;
+  for (let index = 0;index < a.byteLength; index += 1)
+    if (a[index] !== b[index])
+      return !1;
+  return !0;
+}
+async function isDeposed(internals, heldEpochBytes) {
+  let currentEpochRaw;
+  try {
+    currentEpochRaw = await internals.storage.get(KEYS.leaseEpoch());
+  } catch {
+    return !0;
+  }
+  if (currentEpochRaw === null)
+    return !0;
+  if (decodeEpoch(currentEpochRaw) === null)
+    return !0;
+  return !epochBytesEqual(heldEpochBytes, currentEpochRaw);
+}

package/dist/core/engine/finalizer-state.d.ts

@@ -0,0 +1,28 @@
+import type { EngineInternals } from './internals.ts';
+/**
+ * Engine-side handler for `ctx.setFinalizerState(value)` (issue #446). Durably
+ * records the payload associated with the workflow's definition-level
+ * `finalizer` activity.
+ *
+ * This handler only records the value; the engine passes the decoded payload as
+ * the finalizer's input when it drives cancel/timeout teardown (#446 Phase 2).
+ *
+ * The value is staged as a pending atomic side-effect — a `put` of
+ * {@link KEYS.finalizerState} — that commits with whichever durable write lands
+ * first: the next checkpoint/suspend commit, or, if no checkpoint runs before the
+ * workflow terminates, the terminal `updateWorkflowState` batch
+ * (`includePendingAtomicSideEffects` is set for terminal transitions). Either way
+ * the resource id is durable before teardown is driven: a cancel arriving before
+ * the next checkpoint still flushes the staged op in the terminal batch, so the
+ * finalizer always sees the resource id. The staged op inherits the lease-epoch
+ * fence (#470) for free, since checkpoint and terminal commits route through
+ * `commitFencedWorkflowStateOperations`.
+ *
+ * Oversized payloads are rejected before staging (the same hostile-input guard
+ * activity results use). A call made once the workflow is already terminalizing
+ * — e.g. from an `onCancel` handler, which runs after the terminal batch has
+ * already taken the pending side-effects — is a no-op: the staged op has no
+ * future commit to ride and is cleared on terminal cleanup. A development
+ * warning is emitted so the footgun is visible, but no error is thrown.
+ */
+export declare function recordFinalizerState(internals: EngineInternals, workflowId: string, value: unknown): void;

package/dist/core/engine/finalizer-state.js

@@ -0,0 +1,16 @@
+import { KEYS } from "../../storage/interface.js";
+import { encode } from "../codec.js";
+import { assertPayloadWithinLimit } from "../payload-size.js";
+import { stageAtomicWorkflowCommitSideEffects } from "./checkpoint-side-effects.js";
+export function recordFinalizerState(internals, workflowId, value) {
+  if (internals.terminalizingWorkflows.has(workflowId)) {
+    if (internals.options.development)
+      console.warn(`[weft] ctx.setFinalizerState() called for workflow "${workflowId}" after it began terminalizing; the value is ignored. Record finalizer state while the workflow is still running.`);
+    return;
+  }
+  assertPayloadWithinLimit(value, internals.options.payloadSizePolicy.maxBytes, "finalizer state");
+  stageAtomicWorkflowCommitSideEffects(internals, workflowId, {
+    conditions: [],
+    operations: [{ type: "put", key: KEYS.finalizerState(workflowId), value: encode(value) }]
+  });
+}

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

@@ -1,5 +1,13 @@
 import type { LaunchMetadata, QueryDefinition, SearchAttributeValue, SignalDefinition, SignalDeliveryOptions, UpdateDefinition, WorkflowState } from '../types.ts';
 import type { WorkflowSnapshot } from '../types/workflow-snapshot.ts';
+/**
+ * Which atomic path a `startOrSignal` call took, returned alongside the
+ * {@link WorkflowHandle} in `StartOrSignalResult` (not a field on the handle —
+ * converged concurrent callers share one cached engine handle, so the outcome
+ * rides the per-call result instead). `'started'` when the call created the
+ * run, `'signalled'` when it delivered a signal to a run that already existed.
+ */
+export type StartOrSignalOutcome = 'started' | 'signalled';
 export declare function getWorkflowExecutionStartedAt(state: Pick<WorkflowState, 'createdAt' | 'startedAt'>): number;
 export declare const HANDLE_RESULT_PROMISE: unique symbol;
 export interface WorkflowHandleEngine extends EventTarget {

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

@@ -1,19 +1,21 @@
 import { type Storage as WeftStorage } from '../../storage/interface.ts';
 import { type ActivityMetadata, type ActivityRegistrationOptions, type RegisteredActivityFunction } from '../activity-registry.ts';
 import type { StoredStreamChunk } from '../context.ts';
+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 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 SubmitReviewOptions, type TypedListFilter, type UpdateDefinition, type WorkflowEvent, type WorkflowInput, type WorkflowOutput, type WorkflowReplay, 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 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 { TimerEntry } from '../types/checkpoint.ts';
 import type { WorkflowAlreadyRegistered } from '../types/workflow-builder.ts';
 import { type AggregateOptions, type AggregateResult } from './aggregate.ts';
 import { type EmptyActivityDefinitions, type EmptyWorkflowDefinitions, type KnownWorkflowNames } from './construction.ts';
-import { type ActivityDefinitionName, type EngineCreateOptions, type RegisteredActivityDefinitionExecute, type UnknownWorkflowNameWhenDefaultRegistryIsEmpty } from './engine-create-types.ts';
+import { type ActivityDefinitionName, type EngineCreateOptions, type EngineCreateWorkflowRegistry, type RegisteredActivityDefinitionExecute, type UnknownWorkflowNameWhenDefaultRegistryIsEmpty } from './engine-create-types.ts';
 import type { EngineConstructorOptions } from './engine-internal-types.ts';
 import type { EngineStateNamespace } from './engine-state-namespace.ts';
 import { HANDLE_RESULT_PROMISE, WorkflowHandle } from './handles.ts';
-import { type RecoverAllOptions } from './lifecycle.ts';
+import { ENGINE_LEASE_LOST_WARNING_NAME } from './lease-deposition.ts';
+import { type RecoverAllOptions, type StartOrSignalResult } from './lifecycle.ts';
 import { assertCompatiblePersistedDataVersion } from './persisted-data-version.ts';
 import { ScheduleHandle } from './schedule-handle.ts';
 import { type WorkflowFeedListener, type WorkflowFeedRecord, type WorkflowFeedSelector } from './workflow-feed.ts';
@@ -21,8 +23,9 @@ export { ActivityReconciliationCapabilityError, ActivityReconciliationConflictEr
 export { AsyncActivityTokenNotFoundError } from './async-activity-completion.ts';
 export type { PendingAsyncActivity } from './async-activity-completion.ts';
 export type { PendingTimelineEntry, RegistrationEntry, ResolvedOptions, TrackedWaiterKeys, WorkflowResultWaiter, } from './engine-internal-types.ts';
-export { ActivityResolutionError, BulkDeleteRequiresTerminalWorkflowsError, BulkOperationConfirmationError, EngineCreateNameMismatchError, EngineDisposedError, IdempotencyKeyPurgedError, PersistedDataIncompatibleError, StartOrSignalConflictError, WorkflowAlreadyExistsError, WorkflowNotFoundError, WorkflowNotRegisteredError, WorkflowSuspendNotSupportedError, WorkflowTypeNotRegisteredForRecoveryError, } from './errors.ts';
+export { ActivityResolutionError, BulkDeleteRequiresTerminalWorkflowsError, BulkOperationConfirmationError, EngineCreateNameMismatchError, EngineDisposedError, IdempotencyKeyPurgedError, PersistedDataIncompatibleError, StartOrSignalConflictError, WorkflowAlreadyExistsError, WorkflowConcurrencyLimitExceededError, WorkflowNotFoundError, WorkflowNotRegisteredError, WorkflowSuspendNotSupportedError, WorkflowTeardownPendingError, WorkflowTypeNotRegisteredForRecoveryError, } from './errors.ts';
 export { HANDLE_RESULT_PROMISE, WorkflowHandle } from './handles.ts';
+export { EngineLeaseAcquisitionTimeoutError, EngineLeaseCorruptedError, EngineLeaseNotHeldError, } from './lease-errors.ts';
 export type { RecoverAllOptions } from './lifecycle.ts';
 export { ScheduleHandle } from './schedule-handle.ts';
 export type { WorkflowFeedListener, WorkflowFeedRecord, WorkflowFeedSelector, } from './workflow-feed.ts';
@@ -33,6 +36,7 @@ export { assertCompatiblePersistedDataVersion };
 export declare const ENGINE_PARKED_WORKFLOW_COUNT_FOR_TESTING: unique symbol;
 export declare const ENGINE_SIGNAL_WAITER_COUNT_FOR_TESTING: unique symbol;
 export declare const ENGINE_SLEEP_RESOLVER_COUNT_FOR_TESTING: unique symbol;
+export { ENGINE_LEASE_LOST_WARNING_NAME };
 /**
  * Durable execution engine.
  *
@@ -75,7 +79,7 @@ export declare const ENGINE_SLEEP_RESOLVER_COUNT_FOR_TESTING: unique symbol;
  * void engine;
  * ```
  */
-export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry, TActivities extends object = DefaultActivityTypes> extends EventTarget implements Disposable, AsyncDisposable {
+export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry, TActivities extends object = DefaultActivityTypes> extends EventTarget implements Disposable, AsyncDisposable, TypedEventTarget<WeftEventMap> {
     #private;
     /**
      * Construct and register an engine in one step. Activities are registered
@@ -105,7 +109,7 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
     static create<TWorkflowDefinitions extends Record<string, AnyWorkflowDefinition>>(options: EngineCreateOptions<TWorkflowDefinitions, EmptyActivityDefinitions> & {
         activities?: undefined;
         workflows: TWorkflowDefinitions;
-    }): Promise<Engine<InferWorkflowEntries<TWorkflowDefinitions>>>;
+    }): Promise<Engine<EngineCreateWorkflowRegistry<TWorkflowDefinitions>>>;
     static create<TActivityDefinitions extends Record<string, AnyActivityDefinition>>(options: EngineCreateOptions<EmptyWorkflowDefinitions, TActivityDefinitions> & {
         activities: TActivityDefinitions;
         workflows?: undefined;
@@ -113,8 +117,12 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
     static create<TWorkflowDefinitions extends Record<string, AnyWorkflowDefinition>, TActivityDefinitions extends Record<string, AnyActivityDefinition>>(options: EngineCreateOptions<TWorkflowDefinitions, TActivityDefinitions> & {
         activities: TActivityDefinitions;
         workflows: TWorkflowDefinitions;
-    }): Promise<Engine<InferWorkflowEntries<TWorkflowDefinitions>, InferActivityEntries<TActivityDefinitions>>>;
-    constructor(options?: EngineConstructorOptions);
+    }): Promise<Engine<EngineCreateWorkflowRegistry<TWorkflowDefinitions>, InferActivityEntries<TActivityDefinitions>>>;
+    constructor(options?: EngineConstructorOptions<WorkflowServicesUnion<TWorkflows>>);
+    addEventListener<K extends Extract<keyof WeftEventMap, string>>(type: K, listener: (event: WeftEventMap[K]) => void, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener<K extends Extract<keyof WeftEventMap, string>>(type: K, listener: (event: WeftEventMap[K]) => void, options?: boolean | EventListenerOptions): void;
+    removeEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | EventListenerOptions): void;
     get state(): EngineStateNamespace;
     /**
      * Register a workflow by name or definition, or register an activity
@@ -186,8 +194,8 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
     listWorkflowDefinitions(): RegisteredWorkflowDefinition[];
     getActivityDefinition(name: string): ActivityMetadata | undefined;
     listActivityDefinitions(): ActivityMetadata[];
-    start<TName extends KnownWorkflowNames<TWorkflows>>(type: TName, input: WorkflowInput<TWorkflows, TName>, options?: StartOptions): Promise<WorkflowHandle<WorkflowOutput<TWorkflows, TName>>>;
-    start<TName extends string>(type: UnknownWorkflowNameWhenDefaultRegistryIsEmpty<TWorkflows, TName>, input: unknown, options?: StartOptions): Promise<WorkflowHandle>;
+    start<TName extends KnownWorkflowNames<TWorkflows>>(type: TName, input: WorkflowInput<TWorkflows, TName>, options?: StartWorkflowOptions<WorkflowServices<TWorkflows, TName>>): Promise<WorkflowHandle<WorkflowOutput<TWorkflows, TName>>>;
+    start<TName extends string>(type: UnknownWorkflowNameWhenDefaultRegistryIsEmpty<TWorkflows, TName>, input: unknown, options?: StartWorkflowOptions): Promise<WorkflowHandle>;
     /**
      * Atomically start a workflow or signal it if it already exists
      * (signal-with-start). With an absent target, the workflow record and the
@@ -205,8 +213,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): Promise<WorkflowHandle<WorkflowOutput<TWorkflows, TName>>>;
-    startOrSignal<TName extends string>(type: UnknownWorkflowNameWhenDefaultRegistryIsEmpty<TWorkflows, TName>, input: unknown, signal: StartOrSignalSignal, options?: StartOptions): Promise<WorkflowHandle>;
+    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>;
     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>;
@@ -214,6 +222,8 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
     purge(filter?: ListFilter): Promise<PurgeResult>;
     cancelAll(filter: ListFilter, options: BulkOperationDryRunOptions): Promise<BulkOperationDryRunResult>;
     cancelAll(filter: ListFilter, options?: BulkOperationCommitOptions): Promise<BulkCancelResult>;
+    retryFailedAll(filter: ListFilter, options: BulkOperationDryRunOptions): Promise<BulkOperationDryRunResult>;
+    retryFailedAll(filter: ListFilter, options?: BulkOperationCommitOptions): Promise<BulkRetryFailedResult>;
     signalAll(filter: ListFilter, name: string, payload: unknown, options: BulkSignalAllDryRunOptions): Promise<BulkOperationDryRunResult>;
     signalAll(filter: ListFilter, name: string, payload: unknown, options: BulkSignalAllCommitOptions): Promise<BulkSignalResult>;
     signalAll(filter: ListFilter, name: string, payload?: unknown, options?: BulkOperationCommitOptions): Promise<BulkSignalResult>;
@@ -231,7 +241,7 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
      * Two call forms:
      * - A {@link ScheduleDefinition} object: `engine.schedule({ workflow, cron, input })`.
      *   Carries the workflow (definition or type name), the `cron`/`every` spec,
-     *   optional `input`, `id`, `overlapPolicy`, and `backfill`.
+     *   optional `input`, `id`, `overlapPolicy`, `backfill`, and `jitter`.
      * - Positional: `engine.schedule(type, input, spec, options?)` where `spec` is
      *   a cron string or a {@link ScheduleSpec} (`{ cron }` or `{ every }`).
      *
@@ -325,7 +335,7 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
      * registered workflow type on this engine.
      *
      * `acknowledgeUnknownWorkflowTypes` is a dangerous escape hatch for rolling
-     * deploys or explicit storage migrations.
+     * deploys or explicit operator storage repair.
      * When set, unknown workflow types are skipped and reported through
      * {@link WorkflowRecoverySkippedEvent}.
      */
@@ -335,7 +345,11 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
      * have parked itself via `ActivityContext.completeAsync()`; pass the durable
      * task token announced through the `activity:async-pending` event (or
      * persisted by your callback dispatcher). The parked workflow resumes as
-     * though the activity had returned `result` inline.
+     * though the activity had returned `result` inline. During recovery, a
+     * completion that arrives after token recovery but before replay adopts the
+     * workflow generator is buffered and delivered when replay reaches the same
+     * async-activity token. Await `recoverAll()` before accepting callback traffic
+     * when your application needs startup ordering to be fully deterministic.
      *
      * @throws {AsyncActivityTokenNotFoundError} when no pending activity matches
      * the token (unknown, or already completed/failed — tokens are single-use).
@@ -345,7 +359,11 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
      * Fail a deferred activity out-of-band with `error`. The error is thrown into
      * the workflow generator at the parked step — identical to an inline activity
      * that threw — so the workflow's own try/catch and any configured retry
-     * policy apply unchanged.
+     * policy apply unchanged. During recovery, a failure that arrives after token
+     * recovery but before replay adopts the workflow generator is buffered and
+     * delivered when replay reaches the same async-activity token. Await
+     * `recoverAll()` before accepting callback traffic when your application needs
+     * startup ordering to be fully deterministic.
      *
      * @throws {AsyncActivityTokenNotFoundError} when no pending activity matches
      * the token (unknown, or already completed/failed — tokens are single-use).