@lostgradient/weft 0.2.1 → 0.4.0

package/dist/core/inline-execution-strategy.context-options.js

@@ -0,0 +1,56 @@
+export function createInlineContextOptions(dependencies, registration, parameters, workflowAbort) {
+  return {
+    workflowId: parameters.workflowId,
+    workflowType: parameters.workflowType,
+    startedAt: parameters.startedAt ?? dependencies.getNow(),
+    abortController: workflowAbort,
+    getNow: dependencies.getNow,
+    nestingDepth: parameters.nestingDepth ?? 0,
+    executionStateOwnerId: parameters.executionStateOwnerId ?? parameters.workflowId,
+    ...parameters.sleepReferenceTime !== void 0 && {
+      sleepReferenceTime: parameters.sleepReferenceTime
+    },
+    ...dependencies.resolveWorkflowType !== void 0 && {
+      resolveWorkflowType: dependencies.resolveWorkflowType
+    },
+    ...registration.searchAttributes && {
+      searchAttributeSchema: registration.searchAttributes
+    },
+    ...parameters.deadline !== void 0 && { deadline: parameters.deadline },
+    ...resolveWorkflowScopedCallbackOptions(dependencies, parameters.workflowId),
+    services: dependencies.getWorkflowServices?.(parameters.workflowId),
+    ...resolveLogSinkOption(dependencies)
+  };
+}
+function resolveWorkflowScopedCallbackOptions(dependencies, workflowId) {
+  const { registerCancelHandler, recordFinalizerState } = dependencies;
+  return {
+    ...registerCancelHandler !== void 0 && {
+      registerCancelHandler: (handler) => registerCancelHandler(workflowId, handler)
+    },
+    ...recordFinalizerState !== void 0 && {
+      recordFinalizerState: (value) => recordFinalizerState(workflowId, value)
+    }
+  };
+}
+function resolveLogSinkOption(dependencies) {
+  const logSink = dependencies.getLogSink?.();
+  return logSink === void 0 ? {} : { logSink };
+}
+export function optionalInlineDependencies(candidates) {
+  return {
+    ...candidates.getComposedWorkflowInterceptor !== void 0 && {
+      getComposedWorkflowInterceptor: candidates.getComposedWorkflowInterceptor
+    },
+    ...candidates.registerCancelHandler !== void 0 && {
+      registerCancelHandler: candidates.registerCancelHandler
+    },
+    ...candidates.recordFinalizerState !== void 0 && {
+      recordFinalizerState: candidates.recordFinalizerState
+    },
+    ...candidates.getWorkflowServices !== void 0 && {
+      getWorkflowServices: candidates.getWorkflowServices
+    },
+    ...candidates.getLogSink !== void 0 && { getLogSink: candidates.getLogSink }
+  };
+}

package/dist/core/inline-execution-strategy.d.ts

@@ -11,38 +11,8 @@
  */
 import { Context } from './context.ts';
 import type { ExecutionStrategy } from './execution-strategy.ts';
-import type { ComposedWorkflowInterceptor } from './interceptor.ts';
-import type { FailureCategory, OperationOutcome, SearchAttributeSchema, WorkerOutboundMessage, WorkflowFunction } from './types.ts';
-export interface InlineExecutionDependencies {
-    getRegistration: (workflowType: string) => {
-        handler: WorkflowFunction;
-        version: string;
-        searchAttributes?: SearchAttributeSchema;
-    } | undefined;
-    getNow: () => number;
-    resolveWorkflowType?: (target: string | Function) => string;
-    maxNestingDepth: number;
-    development?: boolean;
-    getComposedWorkflowInterceptor?: () => ComposedWorkflowInterceptor | null;
-    registerCancelHandler?: (workflowId: string, handler: () => Promise<void> | void) => () => void;
-    /**
-     * Look up the non-serialized per-run `services` value for a workflow, exposed
-     * to the body as `ctx.services`. Returns `undefined` when none was supplied.
-     */
-    getWorkflowServices?: (workflowId: string) => unknown;
-}
-type InlineStartWorkflowParameters = {
-    workflowId: string;
-    workflowType: string;
-    input: unknown;
-    checkpoint: ArrayBuffer | Uint8Array;
-    nestingDepth?: number;
-    executionStateOwnerId?: string;
-    startedAt?: number;
-    sleepReferenceTime?: number;
-    deadline?: number;
-    headers?: [string, string][];
-};
+import type { InlineExecutionDependencies, InlineStartWorkflowParameters } from './inline-execution-strategy.context-options.ts';
+import type { FailureCategory, OperationOutcome, WorkerOutboundMessage } from './types.ts';
 export declare class InlineExecutionStrategy implements ExecutionStrategy {
     #private;
     constructor(dependencies: InlineExecutionDependencies);
@@ -54,8 +24,33 @@ export declare class InlineExecutionStrategy implements ExecutionStrategy {
         operationResult: OperationOutcome;
     }): void;
     cancelWorkflow(workflowId: string): void;
-    parkWorkflow(workflowId: string): void;
+    /**
+     * Evict a workflow's in-memory execution state (generator, abort controller,
+     * live context, tracked turns/advances).
+     *
+     * By default this is a hard eviction: nothing about the run stays reachable —
+     * which is what the suspend/general teardown path requires. The inline
+     * `waitForSignal` parking optimization opts into `retainContext: true` so the
+     * run's Context survives in `#parkedContexts` and its `ctx.onQuery` handlers
+     * stay callable while the run is parked. Retention is therefore strictly
+     * opt-in at the one call site that wants it; every other caller gets eviction.
+     */
+    parkWorkflow(workflowId: string, options?: {
+        retainContext?: boolean;
+    }): void;
+    /** Returns the live Context for a workflow, or `undefined` if not running. For parked workflows use {@link getParkedContext}. */
     getContext(workflowId: string): Context | undefined;
+    /** Returns the retained Context for a parked workflow, or `undefined` if not parked or already cleaned up. */
+    getParkedContext(workflowId: string): Context | undefined;
+    /**
+     * Drop any retained parked Context for a workflow without touching the abort
+     * controller or other live state. Terminal cleanup calls this so a workflow
+     * that reached a terminal status while parked (e.g. a failed resume, or normal
+     * completion of a run that had parked) cannot keep resolving `ctx.onQuery`
+     * handlers from a stale parked Context — and so the Context is not retained
+     * for the engine's lifetime.
+     */
+    clearParkedContext(workflowId: string): void;
     getAbortController(workflowId: string): AbortController | undefined;
     waitForWorkflowTurn(workflowId: string): Promise<void> | undefined;
     waitForWorkflowAdvance(workflowId: string): Promise<void> | undefined;
@@ -71,11 +66,11 @@ export declare class InlineExecutionStrategy implements ExecutionStrategy {
      */
     throwIntoWorkflow(workflowId: string, error: unknown, operationFailureCategory?: FailureCategory): void;
     /**
-     * Store a context and generator that were created externally (used by
-     * the engine's resume() path where context setup is more complex).
+     * Store a context and generator created externally (engine resume path).
+     * Clears any retained parked context so a concurrent query sees the new
+     * live context rather than the stale parked one.
      */
     adoptWorkflow(workflowId: string, generator: AsyncGenerator, context: Context, abortController: AbortController): void;
     [Symbol.dispose](): void;
     [Symbol.asyncDispose](): Promise<void>;
 }
-export {};

package/dist/core/inline-execution-strategy.js

@@ -3,38 +3,14 @@ import {
   classifyErrorAsFailureCategory,
   errorFromFailedOperationOutcome
 } from "./failure-categories.js";
-function createInlineContextOptions(dependencies, registration, parameters, workflowAbort) {
-  const { registerCancelHandler } = dependencies;
-  return {
-    workflowId: parameters.workflowId,
-    workflowType: parameters.workflowType,
-    startedAt: parameters.startedAt ?? dependencies.getNow(),
-    abortController: workflowAbort,
-    getNow: dependencies.getNow,
-    nestingDepth: parameters.nestingDepth ?? 0,
-    executionStateOwnerId: parameters.executionStateOwnerId ?? parameters.workflowId,
-    ...parameters.sleepReferenceTime !== void 0 && {
-      sleepReferenceTime: parameters.sleepReferenceTime
-    },
-    ...dependencies.resolveWorkflowType !== void 0 && {
-      resolveWorkflowType: dependencies.resolveWorkflowType
-    },
-    ...registration.searchAttributes && {
-      searchAttributeSchema: registration.searchAttributes
-    },
-    ...parameters.deadline !== void 0 && { deadline: parameters.deadline },
-    ...registerCancelHandler !== void 0 && {
-      registerCancelHandler: (handler) => registerCancelHandler(parameters.workflowId, handler)
-    },
-    services: dependencies.getWorkflowServices?.(parameters.workflowId)
-  };
-}
+import { createInlineContextOptions } from "./inline-execution-strategy.context-options.js";
 
 export class InlineExecutionStrategy {
   #dependencies;
   #generators;
   #abortControllers;
   #contexts;
+  #parkedContexts;
   #workflowAdvances;
   #workflowTurns;
   #messageHandler;
@@ -43,6 +19,7 @@ export class InlineExecutionStrategy {
     this.#generators = new Map;
     this.#abortControllers = new Map;
     this.#contexts = new Map;
+    this.#parkedContexts = new Map;
     this.#workflowAdvances = new Map;
     this.#workflowTurns = new Map;
     this.#messageHandler = null;
@@ -93,12 +70,21 @@ export class InlineExecutionStrategy {
       abortController.abort();
     this.#cleanup(workflowId);
   }
-  parkWorkflow(workflowId) {
+  parkWorkflow(workflowId, options) {
+    const context = options?.retainContext ? this.#contexts.get(workflowId) ?? this.#parkedContexts.get(workflowId) : void 0;
     this.#cleanup(workflowId);
+    if (context !== void 0)
+      this.#parkedContexts.set(workflowId, context);
   }
   getContext(workflowId) {
     return this.#contexts.get(workflowId);
   }
+  getParkedContext(workflowId) {
+    return this.#parkedContexts.get(workflowId);
+  }
+  clearParkedContext(workflowId) {
+    this.#parkedContexts.delete(workflowId);
+  }
   getAbortController(workflowId) {
     return this.#abortControllers.get(workflowId);
   }
@@ -124,6 +110,7 @@ export class InlineExecutionStrategy {
     this.#throwIntoGenerator(workflowId, generator, error, operationFailureCategory);
   }
   adoptWorkflow(workflowId, generator, context, abortController) {
+    this.#parkedContexts.delete(workflowId);
     this.#generators.set(workflowId, generator);
     this.#contexts.set(workflowId, context);
     this.#abortControllers.set(workflowId, abortController);
@@ -132,6 +119,7 @@ export class InlineExecutionStrategy {
     this.#generators.clear();
     this.#abortControllers.clear();
     this.#contexts.clear();
+    this.#parkedContexts.clear();
     this.#workflowAdvances.clear();
     this.#workflowTurns.clear();
     this.#messageHandler = null;
@@ -257,6 +245,7 @@ export class InlineExecutionStrategy {
     this.#generators.delete(workflowId);
     this.#abortControllers.delete(workflowId);
     this.#contexts.delete(workflowId);
+    this.#parkedContexts.delete(workflowId);
     if (!options?.preserveTrackedAdvance)
       this.#workflowAdvances.delete(workflowId);
     if (!options?.preserveTrackedTurn)

package/dist/core/list-filter-validation.d.ts

@@ -11,7 +11,7 @@
 import { z } from 'zod';
 import { isFailureCategory } from './failure-categories.ts';
 import type { FailureCategory, WorkflowStatus } from './types/identity.ts';
-import type { ListFilter } from './types/options.ts';
+import type { ListFilter } from './types/list-options.ts';
 import { WeftError } from './weft-error.ts';
 /**
  * Concrete object schema for {@link ListFilter}. Supports `.omit()` and

package/dist/core/list-filter-validation.js

@@ -7,7 +7,8 @@ const WORKFLOW_STATUSES = [
   "completed",
   "failed",
   "cancelled",
-  "timed-out"
+  "timed-out",
+  "suspended"
 ], ID_PREFIX_PATTERN = /^[A-Za-z0-9_-]+$/, workflowStatusSchema = z.enum(WORKFLOW_STATUSES), failureCategorySchema = z.enum(FAILURE_CATEGORIES), timeRangeSchema = z.object({
   gte: z.number().optional(),
   lte: z.number().optional(),

package/dist/core/payload-size.d.ts

@@ -4,7 +4,7 @@ import { WeftError } from './weft-error.ts';
  * {@link PayloadSizeExceededError} message so operators can tell which
  * admission point rejected the value.
  */
-export type PayloadKind = 'workflow input' | 'signal payload' | 'activity result';
+export type PayloadKind = 'workflow input' | 'signal payload' | 'activity result' | 'finalizer state';
 /**
  * Thrown at admission when a payload's serialized (codec-encoded) size exceeds
  * the operator-configured {@link PayloadSizePolicy.maxBytes}. The rejection

package/dist/core/persisted-data-incompatible-error.d.ts

@@ -1,15 +1,17 @@
 import { WeftError } from './weft-error.ts';
 /**
  * Thrown by {@link Engine.create} (and other storage-opening entry points) when
- * a persisted Weft database carries a schema version older than the engine
- * understands. Pre-MVP Weft does not migrate persisted data — bumping
- * {@link CURRENT_PERSISTED_DATA_SCHEMA_VERSION} intentionally invalidates older
- * databases so the failure surfaces deterministically at boot, before any
- * workflow attempts replay.
+ * a persisted Weft database's schema version does not match what the engine
+ * requires — an older version, a newer one, an unparseable sentinel, or user
+ * data present with no sentinel at all. Weft loads persisted data only at the
+ * exact current schema version; it never reshapes a non-matching database in
+ * place. Bumping {@link CURRENT_PERSISTED_DATA_SCHEMA_VERSION} intentionally
+ * invalidates databases stamped with any other version so the failure surfaces
+ * deterministically at boot, before any workflow attempts replay.
  *
  * Inspect `foundVersion` to see what the storage advertised and `expectedVersion`
- * to see what this engine requires. Resolve by deleting the database (acceptable
- * pre-MVP) or by starting from fresh storage.
+ * to see what this engine requires. Resolve by deleting the database or by
+ * starting from fresh storage.
  *
  * @example
  * ```ts

package/dist/core/review/events.d.ts

@@ -6,12 +6,11 @@
  *
  * @example Route review notifications to a webhook
  * ```ts
- * import { ReviewRequestedEvent } from '@lostgradient/weft';
+ * import { ReviewRequestedEvent, type TypedEventTarget, type WeftReviewEventMap } from '@lostgradient/weft';
  *
- * const target = new EventTarget();
+ * declare const target: TypedEventTarget<WeftReviewEventMap>;
  *
- * target.addEventListener(ReviewRequestedEvent.type, (e) => {
- *   const event = e as ReviewRequestedEvent;
+ * target.addEventListener(ReviewRequestedEvent.type, (event) => {
  *   console.log(`Review ${event.reviewId} requested for workflow ${event.workflowId}`);
  *   console.log('Reviewers:', event.reviewers);
  * });
@@ -33,12 +32,11 @@ export declare class ReviewRequestedEvent extends Event {
  *
  * @example Record review decisions in an audit log
  * ```ts
- * import { ReviewCompletedEvent } from '@lostgradient/weft';
+ * import { ReviewCompletedEvent, type TypedEventTarget, type WeftReviewEventMap } from '@lostgradient/weft';
  *
- * const target = new EventTarget();
+ * declare const target: TypedEventTarget<WeftReviewEventMap>;
  *
- * target.addEventListener(ReviewCompletedEvent.type, (e) => {
- *   const event = e as ReviewCompletedEvent;
+ * target.addEventListener(ReviewCompletedEvent.type, (event) => {
  *   console.log(`Review ${event.reviewId}: '${event.decision}' by ${event.reviewer} in ${event.duration}ms`);
  * });
  * ```

package/dist/core/scheduler/scheduler-class.d.ts

@@ -1,10 +1,19 @@
-import type { Storage } from '../../storage/interface.ts';
+import type { BatchOperation, Storage } from '../../storage/interface.ts';
 import type { TimerEntry } from '../types.ts';
 export interface SchedulerOptions {
     storage: Storage;
     onTimerFired: (entry: TimerEntry) => void | Promise<void>;
     pollIntervalMs?: number;
     getNow?: () => number;
+    /**
+     * Commit the batch that deletes a fired timer's keys after its callback
+     * returns. Defaults to an unfenced `storage.batch`. The engine supplies a
+     * lease-fenced commit (#563) so the fired-timer delete and the callback's own
+     * follow-up writes share the same ownership fence — under deposition both are
+     * rejected and the timer survives for the successor to re-drive. With no lease
+     * held this commits exactly as the unfenced default would.
+     */
+    commitTimerCleanup?: (operations: BatchOperation[]) => Promise<void>;
 }
 /**
  * Scheduler manages durable timers and polls for expired deadlines.

package/dist/core/scheduler/scheduler-class.js

@@ -4,16 +4,19 @@ import { buildTimerBatchOperations } from "./timer-batch.js";
 import {
   advanceTimerSource,
   readNextScannedTimerEntry,
+  readNextTeardownTimerEntry,
   readNextTerminalCleanupTimerEntry,
   selectNextTimerSource,
   shouldDeleteTimerIndexWithoutLookup
 } from "./timer-sources.js";
+const EXPIRED_TIMER_SCAN_LIMIT_PER_SOURCE = 1000;
 
 export class Scheduler {
   #storage;
   #onTimerFired;
   #pollIntervalMs;
   #getNow;
+  #commitTimerCleanup;
   #intervalHandle = null;
   #stopped = !1;
   constructor(options) {
@@ -21,6 +24,7 @@ export class Scheduler {
     this.#onTimerFired = options.onTimerFired;
     this.#pollIntervalMs = options.pollIntervalMs ?? 1000;
     this.#getNow = options.getNow ?? Date.now;
+    this.#commitTimerCleanup = options.commitTimerCleanup ?? ((operations) => this.#storage.batch(operations));
   }
   start() {
     if (this.#intervalHandle !== null)
@@ -66,7 +70,7 @@ export class Scheduler {
     this.stop();
   }
   async#processExpiredTimers(now, { respectStopped }) {
-    const currentTime = now ?? this.#getNow(), timerSources = this.#createTimerSources(this.#scanExpiredTimers(currentTime));
+    const currentTime = now ?? this.#getNow(), timerSources = this.#createTimerSources(this.#scanExpiredTimers(currentTime)), cleanupOperations = [];
     for (const timerSource of timerSources)
       await advanceTimerSource(timerSource, this.#storage);
     while (this.#hasPendingTimer(timerSources)) {
@@ -74,27 +78,36 @@ export class Scheduler {
       if (!nextEntry || !selectedSource)
         break;
       if (respectStopped && this.#stopped)
-        return;
-      if (await this.#processSelectedTimer(nextEntry) === "retry") {
+        break;
+      if (await this.#processSelectedTimer(nextEntry, cleanupOperations) === "retry") {
         await advanceTimerSource(selectedSource, this.#storage);
         continue;
       }
       await advanceTimerSource(selectedSource, this.#storage);
     }
+    await this.#deleteProcessedTimerKeys(cleanupOperations);
   }
   #scanExpiredTimers(currentTime) {
     return {
       deadline: this.#storage.scan("wf-deadline:", {
-        lt: resolvePrefixRangeEnd(KEYS.deadline(currentTime, ""))
+        lt: resolvePrefixRangeEnd(KEYS.deadline(currentTime, "")),
+        limit: EXPIRED_TIMER_SCAN_LIMIT_PER_SOURCE
       }),
       delayedStart: this.#storage.scan("wf-delayed:", {
-        lt: resolvePrefixRangeEnd(KEYS.delayedStart(currentTime, ""))
+        lt: resolvePrefixRangeEnd(KEYS.delayedStart(currentTime, "")),
+        limit: EXPIRED_TIMER_SCAN_LIMIT_PER_SOURCE
       }),
       schedule: this.#storage.scan("schedule-due:", {
-        lt: resolvePrefixRangeEnd(KEYS.scheduleTick(currentTime, ""))
+        lt: resolvePrefixRangeEnd(KEYS.scheduleTick(currentTime, "")),
+        limit: EXPIRED_TIMER_SCAN_LIMIT_PER_SOURCE
       }),
       terminalCleanup: this.#storage.scan("wf-cleanup:", {
-        lt: resolvePrefixRangeEnd(KEYS.terminalCleanup(currentTime, ""))
+        lt: resolvePrefixRangeEnd(KEYS.terminalCleanup(currentTime, "")),
+        limit: EXPIRED_TIMER_SCAN_LIMIT_PER_SOURCE
+      }),
+      teardown: this.#storage.scan("wf-teardown:", {
+        lt: resolvePrefixRangeEnd(KEYS.teardownTimer(currentTime, "")),
+        limit: EXPIRED_TIMER_SCAN_LIMIT_PER_SOURCE
       })
     };
   }
@@ -119,29 +132,43 @@ export class Scheduler {
         iterator: iterators.terminalCleanup[Symbol.asyncIterator](),
         next: null,
         readNext: readNextTerminalCleanupTimerEntry
+      },
+      {
+        iterator: iterators.teardown[Symbol.asyncIterator](),
+        next: null,
+        readNext: readNextTeardownTimerEntry
       }
     ];
   }
   #hasPendingTimer(timerSources) {
     return timerSources.some((timerSource) => timerSource.next !== null);
   }
-  async#processSelectedTimer(nextEntry) {
+  async#processSelectedTimer(nextEntry, cleanupOperations) {
     try {
       await this.#onTimerFired(nextEntry.entry);
     } catch (error) {
       console.error(`Timer callback failed for timer ${nextEntry.entry.id}:`, error);
       return "retry";
     }
-    await this.#deleteTimerKeysAfterCallback(nextEntry);
+    await this.#appendTimerCleanupOperationsAfterCallback(nextEntry, cleanupOperations);
     return "processed";
   }
-  async#deleteTimerKeysAfterCallback(nextEntry) {
+  async#appendTimerCleanupOperationsAfterCallback(nextEntry, cleanupOperations) {
     try {
-      await this.#storage.batch(await this.#buildTimerCleanupOperations(nextEntry));
+      cleanupOperations.push(...await this.#buildTimerCleanupOperations(nextEntry));
     } catch (deleteError) {
       console.error(`Failed to delete timer keys for ${nextEntry.entry.id}:`, deleteError);
     }
   }
+  async#deleteProcessedTimerKeys(cleanupOperations) {
+    if (cleanupOperations.length === 0)
+      return;
+    try {
+      await this.#commitTimerCleanup(cleanupOperations);
+    } catch (deleteError) {
+      console.error("Failed to delete timer keys for processed scheduler tick:", deleteError);
+    }
+  }
   async#buildTimerCleanupOperations(nextEntry) {
     const cleanupOperations = [{ type: "delete", key: nextEntry.key }], indexDeleteOperation = await this.#buildTimerIndexDeleteOperation(nextEntry);
     if (indexDeleteOperation)

package/dist/core/scheduler/timer-batch.js

@@ -2,7 +2,7 @@ import { KEYS } from "../../storage/interface.js";
 import { encode } from "../codec.js";
 import { normalizeStorageTimestamp } from "./duration.js";
 function isTimerEntryKind(value) {
-  return value === "sleep" || value === "visibility-timeout" || value === "execution-deadline" || value === "delayed-start" || value === "schedule" || value === "terminal-cleanup";
+  return value === "sleep" || value === "visibility-timeout" || value === "execution-deadline" || value === "delayed-start" || value === "schedule" || value === "terminal-cleanup" || value === "teardown" || value === "wait-condition";
 }
 function isRecord(value) {
   return typeof value === "object" && value !== null;
@@ -30,6 +30,14 @@ export function buildTimerBatchOperations(entry) {
         value: encode(normalizedEntry.workflowId)
       }
     ];
+  if (normalizedEntry.kind === "teardown")
+    return [
+      {
+        type: "put",
+        key: KEYS.teardownTimer(normalizedEntry.fireAt, normalizedEntry.id),
+        value: encode(normalizedEntry.workflowId)
+      }
+    ];
   const deadlineKey = normalizedEntry.kind === "delayed-start" ? KEYS.delayedStart(normalizedEntry.fireAt, normalizedEntry.workflowId) : normalizedEntry.kind === "schedule" ? KEYS.scheduleTick(normalizedEntry.fireAt, normalizedEntry.workflowId) : KEYS.deadline(normalizedEntry.fireAt, normalizedEntry.id), operations = [
     { type: "put", key: deadlineKey, value: encode(normalizedEntry) }
   ];

package/dist/core/scheduler/timer-sources.d.ts

@@ -12,6 +12,7 @@ export type TimerSource = {
 export declare function compareScannedTimerEntries(left: ScannedTimerEntry, right: ScannedTimerEntry): number;
 export declare function readNextScannedTimerEntry(iterator: AsyncIterator<[string, Uint8Array]>, storage: Storage): Promise<ScannedTimerEntry | null>;
 export declare function readNextTerminalCleanupTimerEntry(iterator: AsyncIterator<[string, Uint8Array]>, storage: Storage): Promise<ScannedTimerEntry | null>;
+export declare function readNextTeardownTimerEntry(iterator: AsyncIterator<[string, Uint8Array]>, storage: Storage): Promise<ScannedTimerEntry | null>;
 export declare function advanceTimerSource(timerSource: TimerSource, storage: Storage): Promise<void>;
 export declare function selectNextTimerSource(timerSources: TimerSource[]): TimerSource | undefined;
 export declare function shouldDeleteTimerIndexWithoutLookup(entry: TimerEntry): boolean;

package/dist/core/scheduler/timer-sources.js

@@ -20,15 +20,15 @@ export async function readNextScannedTimerEntry(iterator, storage) {
     return { key, entry: decoded };
   }
 }
-export async function readNextTerminalCleanupTimerEntry(iterator, storage) {
-  const prefix = "wf-cleanup:";
+async function readNextWorkflowTimerEntry(iterator, storage, kind) {
+  const { diagnosticName, prefix } = kind === "terminal-cleanup" ? { diagnosticName: "terminal cleanup", prefix: "wf-cleanup:" } : { diagnosticName: "teardown timer", prefix: "wf-teardown:" };
   while (!0) {
     const next = await iterator.next();
     if (next.done)
       return null;
     const [key, value] = next.value, separatorIndex = key.indexOf(":", prefix.length), fireAtValue = separatorIndex === -1 ? Number.NaN : Number(key.slice(prefix.length, separatorIndex)), timerId = separatorIndex === -1 ? null : tryDecodeStorageKeyComponent(key.slice(separatorIndex + 1)), decodedWorkflowId = decode(value);
     if (!Number.isSafeInteger(fireAtValue) || fireAtValue < 0 || timerId === null || typeof decodedWorkflowId !== "string") {
-      console.error(`Corrupted terminal cleanup entry at ${key}: removing`);
+      console.error(`Corrupted ${diagnosticName} entry at ${key}: removing`);
       await storage.delete(key);
       continue;
     }
@@ -38,11 +38,17 @@ export async function readNextTerminalCleanupTimerEntry(iterator, storage) {
         id: timerId,
         workflowId: decodedWorkflowId,
         fireAt: fireAtValue,
-        kind: "terminal-cleanup"
+        kind
       }
     };
   }
 }
+export async function readNextTerminalCleanupTimerEntry(iterator, storage) {
+  return readNextWorkflowTimerEntry(iterator, storage, "terminal-cleanup");
+}
+export async function readNextTeardownTimerEntry(iterator, storage) {
+  return readNextWorkflowTimerEntry(iterator, storage, "teardown");
+}
 export async function advanceTimerSource(timerSource, storage) {
   timerSource.next = await timerSource.readNext(timerSource.iterator, storage);
 }
@@ -57,5 +63,5 @@ export function selectNextTimerSource(timerSources) {
   return selectedSource;
 }
 export function shouldDeleteTimerIndexWithoutLookup(entry) {
-  return entry.kind !== "schedule" && entry.kind !== "terminal-cleanup";
+  return entry.kind !== "schedule" && entry.kind !== "terminal-cleanup" && entry.kind !== "teardown";
 }

package/dist/core/session-state.d.ts

@@ -1,6 +1,5 @@
 import { WeftError } from './weft-error.ts';
 export declare const SESSION_STATE_LOCAL_KEY = "stateSession";
-export declare const LEGACY_SESSION_STATE_LOCAL_KEY = "sessionState";
 export declare const MAX_SESSION_STATE_ENTRY_COUNT = 256;
 export declare const MAX_SESSION_STATE_KEY_LENGTH = 256;
 export declare const MAX_SESSION_STATE_SERIALIZED_BYTES: number;

package/dist/core/session-state.js

@@ -1,6 +1,6 @@
 import { encode } from "./codec.js";
 import { WeftError } from "./weft-error.js";
-export const SESSION_STATE_LOCAL_KEY = "stateSession", LEGACY_SESSION_STATE_LOCAL_KEY = "sessionState", MAX_SESSION_STATE_ENTRY_COUNT = 256, MAX_SESSION_STATE_KEY_LENGTH = 256, MAX_SESSION_STATE_SERIALIZED_BYTES = 32768;
+export const SESSION_STATE_LOCAL_KEY = "stateSession", MAX_SESSION_STATE_ENTRY_COUNT = 256, MAX_SESSION_STATE_KEY_LENGTH = 256, MAX_SESSION_STATE_SERIALIZED_BYTES = 32768;
 const RESERVED_SESSION_STATE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 
 export class SessionStateValidationError extends WeftError {
@@ -55,7 +55,7 @@ export function normalizeSessionStateRecord(value) {
 export function normalizeSessionStateLocals(locals) {
   if (!locals)
     return;
-  return normalizeSessionStateRecord(locals[SESSION_STATE_LOCAL_KEY] ?? locals[LEGACY_SESSION_STATE_LOCAL_KEY]);
+  return normalizeSessionStateRecord(locals[SESSION_STATE_LOCAL_KEY]);
 }
 export function validateSessionStateStore(store) {
   const keys = Object.keys(store);

package/dist/core/start-workflow-validation.d.ts

@@ -2,11 +2,67 @@ import type { Duration } from './types.ts';
 import { WeftError } from './weft-error.ts';
 export declare const MAX_WORKFLOW_TAGS = 32;
 export declare const MAX_WORKFLOW_TAG_BYTES = 128;
+/**
+ * Upper bound on a start `idempotencyKey`, in UTF-8 bytes. `startOrSignal`
+ * derives a signal id of `start-idem:${key}` (an 11-byte prefix) from the key,
+ * and `validateSignalId` caps a signal id at 128 bytes — so the raw key must fit
+ * in `128 - 11 = 117` bytes for the derived id to stay within that ceiling.
+ */
+export declare const MAX_IDEMPOTENCY_KEY_BYTES = 117;
 export declare class StartWorkflowValidationError extends WeftError<'StartWorkflowValidationError'> {
     constructor(message: string);
 }
 export declare const assertExclusiveStartWorkflowOptions: (startAt: unknown, startAfter: unknown) => void;
 export declare const coerceStartWorkflowId: (value: unknown, fieldName: string) => string;
+/**
+ * Coerce a transport-supplied idempotency key to a non-empty string. The key is
+ * a caller-chosen dedup token (it becomes part of a `start-idem:` storage key),
+ * so an empty string — which would collide across unrelated starts — is rejected.
+ */
+export declare const coerceStartWorkflowIdempotencyKey: (value: unknown, fieldName: string) => string;
+/**
+ * Validate an already-string `idempotencyKey`: non-empty (an empty key would
+ * collide across unrelated starts under the shared `start-idem:` mapping) and at
+ * most {@link MAX_IDEMPOTENCY_KEY_BYTES} UTF-8 bytes (so the derived
+ * `start-idem:${key}` signal id stays within the signal-id ceiling). Shared by
+ * the transport coercion and the engine boundary so a direct `engine.start`
+ * caller gets the same guarantees as an HTTP caller.
+ */
+export declare const assertValidIdempotencyKey: (value: string, fieldName: string) => string;
+/**
+ * Validate the `onTerminalConflict` start policy against the rest of the start
+ * options. `'error'` (the default) and `'start-new'` are the only accepted
+ * values. `'start-new'` (Temporal's `ALLOW_DUPLICATE` for terminal runs) requires
+ * an explicit, caller-chosen `id` and is mutually exclusive with `idempotencyKey`:
+ * idempotency is a permanent at-most-once mapping that survives terminal state, so
+ * restarting under it would contradict that contract. A generated UUID is never a
+ * meaningful restart target, hence the explicit-`id` requirement.
+ */
+export declare function assertValidOnTerminalConflict(options: {
+    onTerminalConflict?: unknown;
+    id?: unknown;
+    idempotencyKey?: unknown;
+} | undefined): void;
+/**
+ * `options.id` and `options.idempotencyKey` are mutually exclusive: idempotency
+ * assigns its own generated workflow id and dedups through the key, so pinning a
+ * caller id alongside it conflates "id already taken" with "lost the idempotency
+ * race". Reject the combination so each concern stays separable. Shared by the
+ * plain idempotent-start path and `startOrSignal` convergence validation.
+ */
+export declare function assertIdAndIdempotencyKeyExclusive(options: {
+    id?: unknown;
+    idempotencyKey?: unknown;
+}): void;
+/**
+ * Reject `onTerminalConflict` on a start surface that does not support it
+ * (`engine.startOrSignal`). The option is type-absent from those surfaces, but a
+ * transport or untyped JS caller could still smuggle the field into the options
+ * object — this is the runtime backstop. `engine.startOrSignal`'s identity is the
+ * permanent at-most-once idempotency mapping, which `'start-new'` would violate,
+ * so the policy is `engine.start`-only (see follow-up issue #489).
+ */
+export declare function assertOnTerminalConflictUnsupported(options: object | undefined, surface: string): void;
 export declare function coerceStartWorkflowTimestamp(value: unknown, fieldName: string): number;
 export declare function parseStartWorkflowDuration(duration: Duration, fieldName: string): number;
 export declare function coerceStartWorkflowDuration(value: unknown, fieldName: string): Duration;