@lostgradient/weft 0.6.0 → 0.8.0

package/dist/core/engine/async-activity-completion.js

@@ -3,6 +3,8 @@ import { decode, encode } from "../codec.js";
 import { ActivityAsyncPendingEvent } from "../events.js";
 import { assertPayloadWithinLimit } from "../payload-size.js";
 import { WeftError } from "../weft-error.js";
+import { stageAtomicWorkflowCommitSideEffects } from "./checkpoint-side-effects.js";
+import { commitFencedEngineWrite } from "./fenced-write.js";
 const ASYNC_ACTIVITY_TOKEN_PREFIX = "async-act:v1", ASYNC_ACTIVITY_KEY_PREFIX = "async-act:v1:";
 export function asyncActivityWorkflowPrefix(workflowId) {
   return `${ASYNC_ACTIVITY_KEY_PREFIX}${encodeStorageKeyComponent(workflowId)}:`;
@@ -33,7 +35,7 @@ function isPersistedAsyncActivity(value) {
 export function deriveAsyncActivityToken(workflowId, step, attempt) {
   return `${ASYNC_ACTIVITY_TOKEN_PREFIX}:${workflowId}:${step}:${attempt}`;
 }
-function persistPendingAsyncActivity(storage, pending) {
+function buildPersistPendingAsyncActivityOperation(pending) {
   const record = {
     version: 1,
     token: pending.token,
@@ -44,12 +46,16 @@ function persistPendingAsyncActivity(storage, pending) {
     attempt: pending.attempt,
     createdAt: pending.createdAt
   };
-  return storage.put(KEYS.asyncActivity(pending.workflowId, pending.token), encode(record));
+  return {
+    type: "put",
+    key: KEYS.asyncActivity(pending.workflowId, pending.token),
+    value: encode(record)
+  };
 }
 export async function registerPendingAsyncActivity(internals, pending) {
   const alreadyRegistered = internals.pendingAsyncActivities.has(pending.token);
   internals.pendingAsyncActivities.set(pending.token, pending);
-  await persistPendingAsyncActivity(internals.storage, pending);
+  await commitFencedEngineWrite(internals, [buildPersistPendingAsyncActivityOperation(pending)], [], () => Error(`Async activity registration for token "${pending.token}" lost its precondition.`));
   if (!alreadyRegistered)
     internals.engine.dispatchEvent(new ActivityAsyncPendingEvent(pending.token, pending.operationId, pending.workflowId, pending.activityName, pending.attempt));
 }
@@ -87,12 +93,10 @@ async function consumePendingAsyncActivity(internals, token) {
   if (!pending)
     throw new AsyncActivityTokenNotFoundError(token);
   internals.pendingAsyncActivities.delete(token);
-  try {
-    await internals.storage.delete(KEYS.asyncActivity(pending.workflowId, token));
-  } catch (error) {
-    internals.pendingAsyncActivities.set(token, pending);
-    throw error;
-  }
+  stageAtomicWorkflowCommitSideEffects(internals, pending.workflowId, {
+    conditions: [],
+    operations: [{ type: "delete", key: KEYS.asyncActivity(pending.workflowId, token) }]
+  });
   return pending;
 }
 function shouldBufferPendingAsyncActivityResolution(internals, workflowId) {

package/dist/core/engine/bulk-operations-purge.js

@@ -10,6 +10,7 @@ import { buildIndexOperations } from "../search-attributes.js";
 import { buildWorkflowTagIndexOperations, normalizeWorkflowTags } from "../workflow-tags.js";
 import { asyncActivityWorkflowPrefix } from "./async-activity-completion.js";
 import { forgetCommittedCheckpointBytes } from "./checkpoint-commit-snapshots.js";
+import { commitFencedEngineWrite } from "./fenced-write.js";
 import { streamWorkflowStates } from "./listing.js";
 import { createTerminalCleanupTimerId } from "./state-utilities.js";
 import {
@@ -131,7 +132,7 @@ function getWorkflowRetentionDeadline(internals, state) {
 }
 export async function purgeWorkflow(internals, state, cleanupWaiters) {
   const deleteOperations = await collectWorkflowPurgeDeleteOperations(internals, state);
-  await internals.storage.batch(deleteOperations);
+  await commitFencedEngineWrite(internals, deleteOperations, [], () => Error(`Purge commit for workflow "${state.id}" lost its precondition.`));
   clearPurgedWorkflowInMemoryState(internals, state.id, cleanupWaiters);
 }
 export async function collectWorkflowPurgeDeleteOperations(internals, state) {

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

@@ -1,7 +1,6 @@
 import {
   KEYS,
   requireStorageCapability,
-  storageConditionalBatch,
   storageHas
 } from "../../storage/interface.js";
 import { assertScopedBulkWorkflowFilter } from "../bulk-workflow-filter.js";
@@ -24,6 +23,10 @@ import {
   withBulkAuditEvent
 } from "./bulk-operations-shared.js";
 import { BulkDeleteRequiresTerminalWorkflowsError } from "./errors.js";
+import {
+  assertLeaseHeldForEngineWork,
+  commitFencedEngineWriteAllowingPreconditionFailure
+} from "./fenced-write.js";
 import { BULK_OPERATION_BATCH_SIZE } from "./listing.js";
 import { createTerminalCleanupTimerId } from "./state-utilities.js";
 import { loadWorkflowState, runSerializedWorkflowStateWrite } from "./storage-io.js";
@@ -132,6 +135,7 @@ async function runBulkFailedWorkflowRetry(internals, filter, options = {}) {
   return withBulkAuditEvent(internals, preparation, options, result, retried);
 }
 export async function retryFailedAll(internals, filter, options = {}) {
+  assertLeaseHeldForEngineWork(internals);
   return runBulkFailedWorkflowRetry(internals, filter, options);
 }
 async function retryFailedWorkflow(internals, workflowId) {
@@ -194,12 +198,9 @@ async function reactivateFailedWorkflowFromCheckpointSerialized(internals, workf
   throw Error(`Workflow concurrency admission for "${lastConcurrencyStateKey ?? workflowId}" changed too many times while retrying failed workflow "${workflowId}"`);
 }
 async function commitFailedWorkflowReactivation(internals, operations, conditions) {
-  if (conditions.length === 0) {
-    await internals.storage.batch(operations);
-    return !0;
-  }
-  requireStorageCapability(internals.storage, "conditionalBatch", "retry failed workflow");
-  return storageConditionalBatch(internals.storage, conditions, operations);
+  if (conditions.length > 0)
+    requireStorageCapability(internals.storage, "conditionalBatch", "retry failed workflow");
+  return commitFencedEngineWriteAllowingPreconditionFailure(internals, operations, conditions);
 }
 function buildReactivatedWorkflowState(internals, state) {
   const reactivatedState = {

package/dist/core/engine/callback-checkpoint-persistence.d.ts

@@ -0,0 +1,3 @@
+import type { ContextOperationRequest } from '../context.ts';
+import type { Engine } from './index.ts';
+export declare function persistCheckpointForDataOperation<TWorkflows extends object, TActivities extends object>(engine: Engine<TWorkflows, TActivities>, workflowId: string, operation: ContextOperationRequest): Promise<void>;

package/dist/core/engine/callback-checkpoint-persistence.js

@@ -0,0 +1,25 @@
+import { HISTORY_CIRCUIT_BREAKER_REASON } from "../types.js";
+import { validateAttributeValueSizes } from "./attributes-tags.js";
+import { createTerminationCallbacks } from "./callback-creators-core.js";
+import {
+  appendTimelineBatchOperations,
+  persistCheckpoint,
+  pruneCheckpointHistory
+} from "./checkpoint-io.js";
+import { getInternals } from "./internals.js";
+import { swallowPromiseRejection } from "./strategy-helpers.js";
+import { terminateWorkflow } from "./termination.js";
+export function persistCheckpointForDataOperation(engine, workflowId, operation) {
+  return persistCheckpoint(getInternals(engine), workflowId, operation, void 0, {
+    appendTimelineBatchOperations: (id, checkpointOperation, step, timestamp, operations) => appendTimelineBatchOperations(getInternals(engine), id, checkpointOperation, step, timestamp, operations),
+    swallowPromiseRejection: (promise) => {
+      swallowPromiseRejection(promise);
+    },
+    validateAttributeValueSizes,
+    pruneCheckpointHistory: (id, step) => pruneCheckpointHistory(getInternals(engine), id, step),
+    dispatchEvent: (event) => {
+      engine.dispatchEvent(event);
+    },
+    enforceHistoryCircuitBreaker: (id) => terminateWorkflow(getInternals(engine), id, "timed-out", createTerminationCallbacks(engine), HISTORY_CIRCUIT_BREAKER_REASON)
+  }, { timeline: "preserve-pending" });
+}

package/dist/core/engine/callback-creators-bundles.js

@@ -3,6 +3,7 @@ import {
   broadcast as broadcastFromInternals,
   dispatchPendingUpdateReceived as dispatchPendingUpdateReceivedFromBroadcast
 } from "./broadcast.js";
+import { persistCheckpointForDataOperation } from "./callback-checkpoint-persistence.js";
 import {
   createBroadcastCallbacks,
   createGuardCallbacks,
@@ -97,7 +98,9 @@ export function createConditionOperationCallbacks(engine) {
 }
 export function createDataOperationCallbacks(engine) {
   return {
-    runOperationWithResult: (workflowId, operation, execute) => runOperationWithResultForEngine(engine, workflowId, operation, execute)
+    runOperationWithResult: (workflowId, operation, execute) => runOperationWithResultForEngine(engine, workflowId, operation, execute),
+    persistCheckpoint: (workflowId, operation) => persistCheckpointForDataOperation(engine, workflowId, operation),
+    getActivityOperationCallbacks: () => createActivityOperationCallbacks(engine)
   };
 }
 export function createStateOperationCallbacks(engine) {

package/dist/core/engine/checkpoint-io.d.ts

@@ -6,6 +6,9 @@ type PendingTimelineEntryValue = {
     startedAt: number;
     entry: WorkflowTimelineEntry;
 };
+export type PersistCheckpointOptions = {
+    timeline?: 'record-operation' | 'preserve-pending';
+};
 type PersistCheckpointCallbacks = {
     appendTimelineBatchOperations: (workflowId: string, operation: ContextOperationRequest, step: number, timestamp: number, operations: BatchOperation[]) => PendingTimelineEntryValue;
     swallowPromiseRejection: (promise: Promise<void>) => void;
@@ -26,7 +29,7 @@ type DevelopmentCheckpointCallbacks = {
 };
 export declare function appendTimelineBatchOperations(internals: EngineInternals, workflowId: string, operation: ContextOperationRequest, step: number, timestamp: number, operations: BatchOperation[]): PendingTimelineEntryValue;
 /** Persist a workflow checkpoint, history entry, timeline record, and event log record. */
-export declare function persistCheckpoint(internals: EngineInternals, workflowId: string, operation: ContextOperationRequest, workerCheckpointBytes: ArrayBuffer | undefined, callbacks: PersistCheckpointCallbacks): Promise<void>;
+export declare function persistCheckpoint(internals: EngineInternals, workflowId: string, operation: ContextOperationRequest, workerCheckpointBytes: ArrayBuffer | undefined, callbacks: PersistCheckpointCallbacks, options?: PersistCheckpointOptions): Promise<void>;
 /** Delete the single checkpoint history entry that overflows the retention limit. */
 export declare function pruneCheckpointHistory(internals: EngineInternals, workflowId: string, currentStep: number): Promise<void>;
 /** Validate checkpoint serialization in development mode and dispatch warnings. */

package/dist/core/engine/checkpoint-io.js

@@ -60,13 +60,13 @@ export function appendTimelineBatchOperations(internals, workflowId, operation,
     entry
   };
 }
-export async function persistCheckpoint(internals, workflowId, operation, workerCheckpointBytes, callbacks) {
+export async function persistCheckpoint(internals, workflowId, operation, workerCheckpointBytes, callbacks, options = {}) {
   if (internals.inlineStrategy?.getContext(workflowId))
-    await persistInlineCheckpoint(internals, workflowId, operation, callbacks);
+    await persistInlineCheckpoint(internals, workflowId, operation, callbacks, options);
   else if (workerCheckpointBytes && workerCheckpointBytes.byteLength > 0)
-    await persistWorkerCheckpoint(internals, workflowId, operation, workerCheckpointBytes, callbacks);
+    await persistWorkerCheckpoint(internals, workflowId, operation, workerCheckpointBytes, callbacks, options);
 }
-async function persistInlineCheckpoint(internals, workflowId, operation, callbacks) {
+async function persistInlineCheckpoint(internals, workflowId, operation, callbacks, options) {
   const current = internals.checkpoints.get(workflowId), context = internals.inlineStrategy?.getContext(workflowId);
   if (!current || !context)
     return;
@@ -76,13 +76,13 @@ async function persistInlineCheckpoint(internals, workflowId, operation, callbac
     ...pendingAttributeChanges !== void 0 ? { searchAttributes: pendingAttributeChanges } : {}
   }), pruned = pruneCheckpointReplayState(advanced, resolvePendingOperationStep(operation, context.stepIndex)), commit = createCheckpointCommit(internals, workflowId, pruned.checkpoint, serializeCheckpoint(attachTransientCheckpointReplayPayload(pruned.checkpoint, pruned.replayPayload)), pruned.replayPayload);
   appendAttributeOperations(workflowId, commit, previousAttributes, pendingAttributeChanges, hasPendingAttributeChangesValue, callbacks);
-  await commitCheckpoint(internals, workflowId, operation, commit, callbacks);
+  await commitCheckpoint(internals, workflowId, operation, commit, callbacks, options);
   if (hasPendingAttributeChangesValue)
     callbacks.dispatchEvent(new AttributesChangedEvent(workflowId, { ...pendingAttributeChanges }));
 }
-async function persistWorkerCheckpoint(internals, workflowId, operation, workerCheckpointBytes, callbacks) {
+async function persistWorkerCheckpoint(internals, workflowId, operation, workerCheckpointBytes, callbacks, options) {
   const serialized = new Uint8Array(workerCheckpointBytes), checkpoint = deserializeCheckpoint(serialized), workerReplayPayload = readCheckpointReplayPayload(checkpoint), pruned = pruneCheckpointReplayState(checkpoint, resolvePendingOperationStep(operation, checkpoint.step)), replayPayload = mergeCheckpointReplayPayloads(workerReplayPayload, pruned.replayPayload), prunedSerialized = serializeCheckpoint(attachTransientCheckpointReplayPayload(pruned.checkpoint, replayPayload));
-  await commitCheckpoint(internals, workflowId, operation, createCheckpointCommit(internals, workflowId, pruned.checkpoint, prunedSerialized, replayPayload), callbacks);
+  await commitCheckpoint(internals, workflowId, operation, createCheckpointCommit(internals, workflowId, pruned.checkpoint, prunedSerialized, replayPayload), callbacks, options);
 }
 function createCheckpointCommit(internals, workflowId, checkpoint, serialized, replayPayload) {
   const operations = [
@@ -116,9 +116,9 @@ function appendAttributeOperations(workflowId, commit, previousAttributes, pendi
   });
   commit.operations.push(...buildIndexOperations(workflowId, previousAttributes, commit.checkpoint.searchAttributes));
 }
-async function commitCheckpoint(internals, workflowId, operation, commit, callbacks) {
+async function commitCheckpoint(internals, workflowId, operation, commit, callbacks, options) {
   dispatchCheckpointSizeWarning(internals, workflowId, commit, callbacks);
-  const nextPendingTimelineEntry = callbacks.appendTimelineBatchOperations(workflowId, operation, commit.step, commit.timestamp, commit.operations), { newHead, timestamp } = appendCheckpointEventLog(internals, workflowId, commit), retentionWindow = internals.options.historyPolicy.retentionWindow, compaction = retentionWindow === null ? null : await appendCompactionOperations(internals.storage, workflowId, newHead.sequence, retentionWindow, commit.operations), pendingSideEffects = takePendingAtomicWorkflowCommitSideEffects(internals, workflowId);
+  const nextPendingTimelineEntry = options.timeline === "preserve-pending" ? preservePendingTimelineEntry(internals, workflowId, commit.operations) : callbacks.appendTimelineBatchOperations(workflowId, operation, commit.step, commit.timestamp, commit.operations), { newHead, timestamp } = appendCheckpointEventLog(internals, workflowId, commit), retentionWindow = internals.options.historyPolicy.retentionWindow, compaction = retentionWindow === null ? null : await appendCompactionOperations(internals.storage, workflowId, newHead.sequence, retentionWindow, commit.operations), pendingSideEffects = takePendingAtomicWorkflowCommitSideEffects(internals, workflowId);
   if (pendingSideEffects !== void 0)
     commit.operations.push(...pendingSideEffects.operations);
   const storageSupportsConditionalBatch = internals.storage.capabilities().conditionalBatch, sideEffectConditions = checkpointSideEffectConditions(pendingSideEffects, storageSupportsConditionalBatch), conditions = buildCheckpointCommitConditions(workflowId, commit, storageSupportsConditionalBatch, sideEffectConditions);
@@ -129,7 +129,10 @@ async function commitCheckpoint(internals, workflowId, operation, commit, callba
     clearPendingAtomicWorkflowCommitSideEffects(internals, workflowId);
   if (commit.expectedSerialized !== void 0)
     rememberCommittedCheckpointBytes(internals, workflowId, commit.serialized);
-  internals.pendingTimelineEntries.set(workflowId, nextPendingTimelineEntry);
+  if (nextPendingTimelineEntry === void 0)
+    internals.pendingTimelineEntries.delete(workflowId);
+  else
+    internals.pendingTimelineEntries.set(workflowId, nextPendingTimelineEntry);
   internals.checkpoints.set(workflowId, commit.checkpoint);
   internals.eventLogHeads.set(workflowId, newHead);
   if (compaction !== null)
@@ -146,6 +149,12 @@ async function commitCheckpoint(internals, workflowId, operation, commit, callba
   if (historyEventLimitBreached(internals, newHead.sequence))
     await callbacks.enforceHistoryCircuitBreaker(workflowId);
 }
+function preservePendingTimelineEntry(internals, workflowId, operations) {
+  const pendingTimelineOperation = buildPendingTimelineOperation(internals, workflowId);
+  if (pendingTimelineOperation)
+    operations.push(pendingTimelineOperation);
+  return internals.pendingTimelineEntries.get(workflowId);
+}
 function checkpointSideEffectConditions(pendingSideEffects, storageSupportsConditionalBatch) {
   if (!storageSupportsConditionalBatch)
     return [];

package/dist/core/engine/completed-review-storage.d.ts

@@ -1,6 +1,7 @@
 import type { Storage } from '../../storage/interface.ts';
 import type { HumanReviewResult, ReviewRequest } from '../review/index.ts';
 import type { CompletedReviewEntry, ReviewListFilter } from '../types.ts';
+import type { EngineInternals } from './internals.ts';
 type ReviewListFilterableEntry = {
     workflowId?: string;
     reviewType?: string;
@@ -9,6 +10,6 @@ export declare function matchesReviewListFilter(review: ReviewListFilterableEntr
 export declare function completedReviewStoragePrefix(workflowId?: string): string;
 export declare function completedReviewStorageKey(workflowId: string, reviewId: string): string;
 export declare function listCompletedReviewsFromStorage(storage: Storage, filter: ReviewListFilter): Promise<CompletedReviewEntry[]>;
-export declare function persistCompletedReviewRecord(storage: Storage, reviewKey: string, reviewData: ReviewRequest, decisionResult: HumanReviewResult): Promise<void>;
+export declare function persistCompletedReviewRecord(internals: EngineInternals, reviewKey: string, reviewData: ReviewRequest, decisionResult: HumanReviewResult): Promise<void>;
 export declare function deleteCompletedReviewsForWorkflow(storage: Storage, workflowId: string): Promise<void>;
 export {};

package/dist/core/engine/completed-review-storage.js

@@ -1,5 +1,6 @@
 import { encodeStorageKeyComponent } from "../../storage/interface.js";
 import { encode } from "../codec.js";
+import { commitFencedEngineWrite } from "./fenced-write.js";
 import { parseCompletedReviewEntry, toCompletedReviewEntry } from "./review-list-entries.js";
 export function matchesReviewListFilter(review, filter) {
   if (filter.workflowId !== void 0 && review.workflowId !== filter.workflowId)
@@ -32,16 +33,16 @@ export async function listCompletedReviewsFromStorage(storage, filter) {
   await appendCompletedReviews(reviews, storage.scan("review-decision:"), filter, (key) => scopedPrefix === null || !key.startsWith(scopedPrefix));
   return reviews;
 }
-export async function persistCompletedReviewRecord(storage, reviewKey, reviewData, decisionResult) {
+export async function persistCompletedReviewRecord(internals, reviewKey, reviewData, decisionResult) {
   const completedReview = toCompletedReviewEntry(reviewData, decisionResult);
-  await storage.batch([
+  await commitFencedEngineWrite(internals, [
     {
       type: "put",
       key: completedReviewStorageKey(reviewData.workflowId, reviewData.reviewId),
       value: encode(completedReview)
     },
     { type: "delete", key: reviewKey }
-  ]);
+  ], [], () => Error(`Completed review commit for review "${reviewData.reviewId}" lost its precondition.`));
 }
 export async function deleteCompletedReviewsForWorkflow(storage, workflowId) {
   const completedPrefix = completedReviewStoragePrefix(workflowId), deleteOperations = [];

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';
@@ -36,6 +36,25 @@ 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;
+/**
+ * The `name` of the `process` warning emitted when a lease-owning engine is
+ * disposed through the synchronous `[Symbol.dispose]()` path. Sync disposal can
+ * only fire the lease release in the background; use `await engine.shutdown()`,
+ * `await using`, or `await engine[Symbol.asyncDispose]()` when prompt rolling
+ * deploy handoff matters.
+ *
+ * @example
+ * ```ts
+ * import { ENGINE_LEASE_SYNCHRONOUS_DISPOSE_WARNING_NAME } from '@lostgradient/weft';
+ *
+ * process.on('warning', (warning) => {
+ *   if (warning.name === ENGINE_LEASE_SYNCHRONOUS_DISPOSE_WARNING_NAME) {
+ *     // Alert on shutdown paths that can make lease handoff wait for leaseTtl.
+ *   }
+ * });
+ * ```
+ */
+export declare const ENGINE_LEASE_SYNCHRONOUS_DISPOSE_WARNING_NAME = "WeftEngineLeaseSynchronousDisposeWarning";
 export { ENGINE_LEASE_LOST_WARNING_NAME };
 /**
  * Durable execution engine.
@@ -202,8 +221,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 +233,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>;
@@ -407,6 +427,18 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
         timeout?: number;
         idempotencyKey?: string;
     }): Promise<CoordinatedUpdateResult>;
+    /**
+     * Awaited engine shutdown. Equivalent to
+     * `await engine[Symbol.asyncDispose]()` and useful in explicit signal handlers
+     * where `await using` syntax cannot own the process lifetime directly.
+     *
+     * Under `ownership: 'lease'`, this is the explicit prompt-handoff primitive:
+     * it drains queued inline starts, tears down in-memory write paths, and awaits
+     * lease release before resolving. Synchronous disposal remains immediate and
+     * can make the next engine wait for `leaseTtl` if the process exits before its
+     * background release completes.
+     */
+    shutdown(): Promise<void>;
     /**
      * Synchronous teardown (`using engine = ...`). Pending inline launches that
      * have not yet run are **discarded**, not executed. When you need queued

package/dist/core/engine/index.js

@@ -206,7 +206,7 @@ export {
   shouldEmitEngineLeakWarningForTesting
 } from "./engine-leak-warnings.js";
 export { assertCompatiblePersistedDataVersion };
-export const ENGINE_PARKED_WORKFLOW_COUNT_FOR_TESTING = Symbol("engineParkedWorkflowCountForTesting"), ENGINE_SIGNAL_WAITER_COUNT_FOR_TESTING = Symbol("engineSignalWaiterCountForTesting"), ENGINE_SLEEP_RESOLVER_COUNT_FOR_TESTING = Symbol("engineSleepResolverCountForTesting");
+export const ENGINE_PARKED_WORKFLOW_COUNT_FOR_TESTING = Symbol("engineParkedWorkflowCountForTesting"), ENGINE_SIGNAL_WAITER_COUNT_FOR_TESTING = Symbol("engineSignalWaiterCountForTesting"), ENGINE_SLEEP_RESOLVER_COUNT_FOR_TESTING = Symbol("engineSleepResolverCountForTesting"), ENGINE_LEASE_SYNCHRONOUS_DISPOSE_WARNING_NAME = "WeftEngineLeaseSynchronousDisposeWarning";
 
 export { ENGINE_LEASE_LOST_WARNING_NAME };
 
@@ -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"))
     });
@@ -768,8 +769,13 @@ export class Engine extends EventTarget {
   async submitCoordinatedUpdate(workflowId, name, payload, options) {
     return submitCoordinatedUpdateFromInternals(getInternals(this), workflowId, name, payload, options, this.#createUpdateCallbacks());
   }
+  async shutdown() {
+    return this[Symbol.asyncDispose]();
+  }
   [Symbol.dispose]() {
     const leaseManager = getInternals(this).leaseManager;
+    if (leaseManager !== null && leaseManager.currentEpochBytes() !== null)
+      process.emitWarning("engine ownership lease disposed synchronously; lease release is fire-and-forget, so exiting before the release completes can make the next instance wait for leaseTtl. Use await engine.shutdown(), await using, or await engine[Symbol.asyncDispose]() for prompt rolling-deploy handoff.", ENGINE_LEASE_SYNCHRONOUS_DISPOSE_WARNING_NAME);
     disposeEngine(getInternals(this));
     leaseManager?.release();
   }

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

@@ -31,6 +31,7 @@ import type { Scheduler } from '../scheduler.ts';
 import type { Checkpoint, StartWorkflowOptions } from '../types.ts';
 import type { UpdateCoordinator } from '../updates.ts';
 import type { WorkflowVersionTuple } from '../workflow-version-tuple.ts';
+import type { ActivityHeartbeatKey } from './activity-heartbeat-tracking.ts';
 import type { PendingTimelineEntry, QueuedInlineWorkflowExecutionStart, RegistrationEntry, ResolvedOptions, TrackedWaiterKeys, WorkflowResultWaiter } from './engine-internal-types.ts';
 import type { EngineCleanupIntervalDisposalTracker } from './engine-leak-warnings.ts';
 import type { WorkflowHandle, WorkflowHandleEngine } from './handles.ts';
@@ -148,7 +149,7 @@ export interface EngineInternals {
      * {@link heartbeatDetails}. Inline-execution only; worker-executed activities run
      * their function out of process and never observe this.
      */
-    lastHeartbeatDetailsByStep: Map<string, Map<number, unknown>>;
+    lastHeartbeatDetailsByStep: Map<string, Map<ActivityHeartbeatKey, unknown>>;
     /**
      * Per-run, non-serialized `services` value exposed to the workflow body as
      * `ctx.services`. Set at `engine.start({ services })` and re-provided on

package/dist/core/engine/lease-manager.js

@@ -8,7 +8,7 @@ import {
 import { EngineLeaseAcquisitionTimeoutError, EngineLeaseCorruptedError } from "./lease-errors.js";
 const DEFAULT_ACQUIRE_POLL_INTERVAL_MS = 1000;
 export function createLeaseManager(options) {
-  const { storage, holderId, getNow, ttlMs, renewIntervalMs, waitTimeoutMs } = options, acquirePollIntervalMs = options.acquirePollIntervalMs ?? DEFAULT_ACQUIRE_POLL_INTERVAL_MS, unconfirmableMarginMs = renewIntervalMs;
+  const { storage, holderId, getNow, ttlMs, renewIntervalMs, waitTimeoutMs } = options, acquirePollIntervalMs = options.acquirePollIntervalMs ?? DEFAULT_ACQUIRE_POLL_INTERVAL_MS;
   let stopped = !1, heldEpoch = null, heldEpochBytes = null, lastHolderBytes = null, renewalInterval = null, leaseLost = !1, inFlightRenewal = null;
   const delay = options.delay ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
   function reportLeaseLost(reason) {
@@ -81,7 +81,7 @@ export function createLeaseManager(options) {
       committed = await storageConditionalBatch(storage, [{ key: KEYS.leaseHolder(), expectedValue: lastHolderBytes }], [{ type: "put", key: KEYS.leaseHolder(), value: holderBytes }]);
     } catch {
       const priorExpiry = decodeHolder(lastHolderBytes)?.expiresAt ?? 0;
-      if (getNow() >= priorExpiry - unconfirmableMarginMs)
+      if (getNow() >= priorExpiry)
         reportLeaseLost("renewal-unconfirmable");
       return;
     }

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