@lostgradient/weft 0.2.1 → 0.4.0

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

@@ -35,6 +35,8 @@ function operationProcessors(callbacks) {
     sleep: callbacks.processSleepOperation,
     "wait-signal": callbacks.processWaitSignalOperation,
     "wait-update": callbacks.processWaitUpdateOperation,
+    "wait-condition": callbacks.processWaitConditionOperation,
+    "get-version": callbacks.processGetVersionOperation,
     parallel: callbacks.processParallelOperation,
     race: callbacks.processRaceOperation,
     memo: callbacks.processMemoOperation,

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

@@ -1,3 +1,5 @@
+import { finalizeAndUnwrap } from "./deferred-consume-envelope.js";
+import { assertSupportedSignalBranches } from "./operations-coordination.js";
 import { SpeculativeExecutionState } from "./speculative-execution-state.js";
 export async function processSpeculateOperation(internals, workflowId, operation, callbacks) {
   return callbacks.runOperationWithResult(workflowId, operation, () => executeSpeculativeBranch(internals, workflowId, operation, callbacks));
@@ -30,8 +32,10 @@ export async function driveSpeculativeGenerator(workflowId, generator, speculati
       return iterationResult.value;
     const nextOperation = iterationResult.value;
     try {
-      const nextResult = await callbacks.executeSubOperation(workflowId, nextOperation, void 0, speculativeState);
-      return advance(nextResult, void 0);
+      if (nextOperation.type === "race" || nextOperation.type === "parallel")
+        assertSupportedSignalBranches(nextOperation.operations);
+      const nextResult = await callbacks.executeSubOperation(workflowId, nextOperation, void 0, speculativeState), finalizedResult = await finalizeAndUnwrap(nextResult);
+      return advance(finalizedResult, void 0);
     } catch (error) {
       return advance(lastResult, error instanceof Error ? error : Error(String(error)));
     }

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

@@ -1,7 +1,7 @@
 import { KEYS } from "../../storage/interface.js";
 import { encode } from "../codec.js";
 import { cleanupPartialStreamChunks, createCleanupErrorReporter } from "../engine-helpers.js";
-import { loadStoredStreamChunks } from "./stream-chunk-loading.js";
+import { encodeStoredStreamTailSequence, loadStoredStreamChunks } from "./stream-chunk-loading.js";
 import { STREAM_CHUNK_KIND, TOKENS_STREAM_KEY, notifyWorkflowFeedCommit } from "./workflow-feed.js";
 export async function getStreamChunksFromInternals(internals, workflowId, key, options) {
   return loadStoredStreamChunks(internals.storage, workflowId, key, options);
@@ -33,7 +33,17 @@ export async function writeStreamChunksFromInternals(internals, workflowId, oper
   let chunkCount = 0, totalSizeBytes = 0;
   for await (const chunk of asyncGenerator) {
     const encoded = encode(chunk), sequence = chunkCount, chunkKey = KEYS.streamChunk(workflowId, operation.key, sequence);
-    await internals.storage.put(chunkKey, encoded);
+    if (operation.key === TOKENS_STREAM_KEY)
+      await internals.storage.batch([
+        { type: "put", key: chunkKey, value: encoded },
+        {
+          type: "put",
+          key: KEYS.streamTail(workflowId, operation.key),
+          value: encodeStoredStreamTailSequence(sequence)
+        }
+      ]);
+    else
+      await internals.storage.put(chunkKey, encoded);
     writtenKeys.push(chunkKey);
     totalSizeBytes += encoded.byteLength;
     chunkCount++;

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

@@ -8,6 +8,7 @@ type SleepOperation = Extract<ContextOperationRequest, {
 }>;
 export type TimeOperationCallbacks = {
     completeOperation: (workflowId: string, value: unknown) => void;
+    dispatchEvent: (event: Event) => void;
     loadWorkflowState: (workflowId: string) => Promise<WorkflowState | null>;
     failWorkflow: (workflowId: string, error: Error) => Promise<void>;
     runSerializedWorkflowStateWrite: <Result>(workflowId: string, writeOperation: () => Promise<Result>) => Promise<Result>;
@@ -17,6 +18,7 @@ export type TimeOperationCallbacks = {
     loadWorkflowStartHeaders: (workflowId: string) => Promise<Map<string, string> | undefined>;
     parseStartOptionDuration: (value: Duration, fieldName: 'options.executionTimeout' | 'options.startAfter') => number;
     runDeferredTerminalCleanup: (workflowId: string, timerId: string) => Promise<void>;
+    runWorkflowFinalizer: (workflowId: string, timerId: string) => Promise<void>;
     handleScheduleTimer: (entry: TimerEntry) => Promise<void>;
     timeout: (workflowId: string) => Promise<void>;
     handleCleanupError: (source: string, error: unknown, workflowId: string) => void;
@@ -24,6 +26,6 @@ export type TimeOperationCallbacks = {
 export declare function createDelayedStartTimerEntry(_internals: EngineInternals, workflowId: string, scheduledStartAt: number, options: StartOptions | undefined, callbacks: Pick<TimeOperationCallbacks, 'parseStartOptionDuration'>): TimerEntry;
 export declare function processSleepOperation(internals: EngineInternals, workflowId: string, operation: SleepOperation, callbacks: Pick<TimeOperationCallbacks, 'completeOperation' | 'loadWorkflowState'>): Promise<void>;
 export declare function registerSleepResolver(internals: EngineInternals, workflowId: string, operationId: string, resolve: () => void): void;
-export declare function startDelayedWorkflow(internals: EngineInternals, entry: TimerEntry, callbacks: Pick<TimeOperationCallbacks, 'beginWorkflowExecution' | 'failWorkflow' | 'handleCleanupError' | 'loadWorkflowStartHeaders' | 'loadWorkflowState' | 'runSerializedWorkflowStateWrite' | 'setWorkflowStartHeaders' | 'workflowVersionTupleFromState'>): Promise<void>;
-export declare function handleTimerFired(internals: EngineInternals, entry: TimerEntry, callbacks: Pick<TimeOperationCallbacks, 'failWorkflow' | 'handleCleanupError' | 'loadWorkflowStartHeaders' | 'loadWorkflowState' | 'runDeferredTerminalCleanup' | 'runSerializedWorkflowStateWrite' | 'handleScheduleTimer' | 'setWorkflowStartHeaders' | 'timeout' | 'beginWorkflowExecution' | 'workflowVersionTupleFromState'>): Promise<void>;
+export declare function startDelayedWorkflow(internals: EngineInternals, entry: TimerEntry, callbacks: Pick<TimeOperationCallbacks, 'beginWorkflowExecution' | 'dispatchEvent' | 'failWorkflow' | 'handleCleanupError' | 'loadWorkflowStartHeaders' | 'loadWorkflowState' | 'runSerializedWorkflowStateWrite' | 'setWorkflowStartHeaders' | 'workflowVersionTupleFromState'>): Promise<void>;
+export declare function handleTimerFired(internals: EngineInternals, entry: TimerEntry, callbacks: Pick<TimeOperationCallbacks, 'failWorkflow' | 'handleCleanupError' | 'loadWorkflowStartHeaders' | 'loadWorkflowState' | 'runDeferredTerminalCleanup' | 'runWorkflowFinalizer' | 'runSerializedWorkflowStateWrite' | 'handleScheduleTimer' | 'setWorkflowStartHeaders' | 'timeout' | 'beginWorkflowExecution' | 'dispatchEvent' | 'workflowVersionTupleFromState'>): Promise<void>;
 export {};

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

@@ -2,6 +2,7 @@ import { KEYS, storageHas } from "../../storage/interface.js";
 import { deserializeCheckpoint } from "../checkpoint.js";
 import { encode } from "../codec.js";
 import { buildTimerBatchOperations, normalizeStorageTimestamp } from "../scheduler.js";
+import { commitFencedEngineWrite } from "./fenced-write.js";
 import { reprovideRecoveredServices } from "./lifecycle/recovered-services.js";
 import { buildWorkflowVisibilityIndexTransition } from "./workflow-indexes.js";
 export function createDelayedStartTimerEntry(_internals, workflowId, scheduledStartAt, options, callbacks) {
@@ -81,12 +82,12 @@ export async function startDelayedWorkflow(internals, entry, callbacks) {
         fireAt: executionDeadline,
         kind: "execution-deadline"
       }));
-    await internals.storage.batch(operations);
+    await commitFencedEngineWrite(internals, operations, [], () => Error(`Delayed-start transition for workflow "${entry.workflowId}" lost its CAS race.`));
     return nextRunningState;
   });
   if (!runningState)
     return;
-  if (await reprovideRecoveredServices(internals, runningState, (workflowId, error) => callbacks.failWorkflow(workflowId, error), callbacks.handleCleanupError))
+  if (await reprovideRecoveredServices(internals, runningState, (workflowId, error) => callbacks.failWorkflow(workflowId, error), callbacks.handleCleanupError, callbacks.dispatchEvent))
     return;
   if (await storageHas(internals.storage, KEYS.terminalCleanupNeeded(entry.workflowId)))
     internals.workflowsNeedingTerminalCleanup.add(entry.workflowId);
@@ -133,15 +134,26 @@ export async function handleTimerFired(internals, entry, callbacks) {
     await callbacks.runDeferredTerminalCleanup(entry.workflowId, entry.id);
     return;
   }
+  if (entry.kind === "teardown") {
+    await callbacks.runWorkflowFinalizer(entry.workflowId, entry.id);
+    return;
+  }
   if (entry.kind === "schedule") {
     await callbacks.handleScheduleTimer(entry);
     return;
   }
   if (entry.kind === "sleep")
     resolveSleepTimer(internals, entry);
+  else if (entry.kind === "wait-condition")
+    resolveConditionTimer(internals, entry);
   else if (entry.kind === "execution-deadline")
     await callbacks.timeout(entry.workflowId);
 }
+function resolveConditionTimer(internals, entry) {
+  const resolver = internals.conditionWaiters.get(entry.workflowId);
+  if (resolver)
+    resolver();
+}
 async function handleReviewTimer(internals, entry, callbacks) {
   const reviewId = entry.id.split(":")[1];
   if (!reviewId)

package/dist/core/engine/operations-wait-condition.d.ts

@@ -0,0 +1,23 @@
+import type { ContextOperationRequest } from '../context.ts';
+import type { EngineInternals } from './internals.ts';
+import type { CoordinationOperationCallbacks } from './operations-coordination.ts';
+type WaitConditionOperation = Extract<ContextOperationRequest, {
+    type: 'wait-condition';
+}>;
+export type ConditionOperationCallbacks = Pick<CoordinationOperationCallbacks, 'completeOperation'> & {
+    /**
+     * Fail the pending operation, feeding the error to the generator so it
+     * re-throws at the `yield* ctx.waitUntil` site. Used when the user predicate
+     * throws — a throwing predicate must surface as a catchable workflow failure,
+     * not park the run forever.
+     */
+    failOperation: (workflowId: string, operation: WaitConditionOperation, error: unknown) => void;
+    /** Whether the workflow is still running — gates completion after a wake. */
+    isWorkflowRunning: (workflowId: string) => Promise<boolean>;
+    /** Schedule the deterministic deadline timer (`cond:${workflowId}:${step}`). */
+    scheduleConditionDeadline: (workflowId: string, step: number, fireAt: number) => Promise<void>;
+    /** Cancel the deadline timer in storage on teardown. */
+    cancelConditionDeadline: (workflowId: string, step: number) => Promise<void>;
+};
+export declare function processWaitConditionOperation(internals: EngineInternals, workflowId: string, operation: WaitConditionOperation, callbacks: ConditionOperationCallbacks): Promise<void>;
+export {};

package/dist/core/engine/operations-wait-condition.js

@@ -0,0 +1,62 @@
+function evaluateConditionOutcome(internals, predicate, deadline) {
+  if (predicate())
+    return { done: !0, value: deadline === void 0 ? void 0 : !0 };
+  if (deadline !== void 0 && internals.options.getNow() >= deadline)
+    return { done: !0, value: !1 };
+  return { done: !1 };
+}
+export async function processWaitConditionOperation(internals, workflowId, operation, callbacks) {
+  const abortSignal = internals.abortController.signal, { predicate, deadline } = operation;
+  let settled = !1;
+  const complete = (value) => {
+    if (settled)
+      return;
+    settled = !0;
+    callbacks.completeOperation(workflowId, value);
+  };
+  if (abortSignal.aborted)
+    return;
+  try {
+    const initial = evaluateConditionOutcome(internals, predicate, deadline);
+    if (initial.done) {
+      complete(initial.value);
+      return;
+    }
+    if (deadline !== void 0)
+      await callbacks.scheduleConditionDeadline(workflowId, operation.step, deadline);
+    try {
+      let step = await runConditionWaitStep(internals, workflowId, predicate, deadline, callbacks);
+      while (step.status === "continue")
+        step = await runConditionWaitStep(internals, workflowId, predicate, deadline, callbacks);
+      if (step.status === "complete")
+        complete(step.value);
+    } finally {
+      releaseConditionWaiter(internals, workflowId);
+      if (deadline !== void 0)
+        await callbacks.cancelConditionDeadline(workflowId, operation.step);
+    }
+  } catch (error) {
+    callbacks.failOperation(workflowId, operation, error);
+  }
+}
+async function runConditionWaitStep(internals, workflowId, predicate, deadline, callbacks) {
+  const abortSignal = internals.abortController.signal;
+  if (abortSignal.aborted)
+    return { status: "stop" };
+  const { promise, resolve } = Promise.withResolvers();
+  internals.conditionWaiters.set(workflowId, resolve);
+  const outcome = abortSignal.aborted ? { done: !0, value: void 0, aborted: !0 } : { ...evaluateConditionOutcome(internals, predicate, deadline), aborted: !1 };
+  if (outcome.done) {
+    releaseConditionWaiter(internals, workflowId);
+    return outcome.aborted ? { status: "stop" } : { status: "complete", value: outcome.value };
+  }
+  await promise;
+  if (abortSignal.aborted)
+    return { status: "stop" };
+  if (!await callbacks.isWorkflowRunning(workflowId))
+    return { status: "stop" };
+  return { status: "continue" };
+}
+function releaseConditionWaiter(internals, workflowId) {
+  internals.conditionWaiters.delete(workflowId);
+}

package/dist/core/engine/ownership-options.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Resolution of the `ownership` posture options (`Engine.create({ ownership })`)
+ * into {@link ResolvedOptions}. Extracted from `construction.ts` to keep that
+ * file under the `max-lines` ceiling; mirrors the second-instance resolver's
+ * "only validate when the feature is enabled" discipline.
+ *
+ * @module core/engine/ownership-options
+ */
+import type { EngineConstructorOptions, ResolvedOptions } from './engine-internal-types.ts';
+/** Default lease time-to-live for `ownership: 'lease'`. */
+export declare const DEFAULT_LEASE_TTL_MS = 30000;
+/** Default lease renewal interval for `ownership: 'lease'`. */
+export declare const DEFAULT_LEASE_RENEW_INTERVAL_MS = 5000;
+/** Default boot-time lease acquisition wait window for `ownership: 'lease'`. */
+export declare const DEFAULT_LEASE_WAIT_TIMEOUT_MS = 60000;
+/**
+ * Resolve the ownership posture and lease tuning into their `ResolvedOptions`
+ * fields. Defaults to `'none'`. The lease durations are documented as "ignored
+ * when ownership is not 'lease'", so they are only normalized (and thus only
+ * able to throw on an invalid value) when lease ownership is actually enabled —
+ * an invalid duration must not make an off-by-default config fatal at boot.
+ */
+export declare function resolveOwnershipFields(options: EngineConstructorOptions | undefined): Pick<ResolvedOptions, 'ownershipMode' | 'leaseTtlMs' | 'leaseRenewIntervalMs' | 'leaseWaitTimeoutMs'>;

package/dist/core/engine/ownership-options.js

@@ -0,0 +1,26 @@
+import { normalizeRetentionDuration } from "./validation.js";
+export const DEFAULT_LEASE_TTL_MS = 30000, DEFAULT_LEASE_RENEW_INTERVAL_MS = 5000, DEFAULT_LEASE_WAIT_TIMEOUT_MS = 60000;
+export function resolveOwnershipFields(options) {
+  const ownershipMode = assertKnownOwnershipMode(options?.ownership ?? "none");
+  if (ownershipMode !== "lease")
+    return {
+      ownershipMode,
+      leaseTtlMs: DEFAULT_LEASE_TTL_MS,
+      leaseRenewIntervalMs: DEFAULT_LEASE_RENEW_INTERVAL_MS,
+      leaseWaitTimeoutMs: DEFAULT_LEASE_WAIT_TIMEOUT_MS
+    };
+  const leaseTtlMs = normalizeRetentionDuration(options?.leaseTtl, "options.leaseTtl") ?? DEFAULT_LEASE_TTL_MS, leaseRenewIntervalMs = normalizeRetentionDuration(options?.leaseRenewInterval, "options.leaseRenewInterval") ?? DEFAULT_LEASE_RENEW_INTERVAL_MS, leaseWaitTimeoutMs = normalizeRetentionDuration(options?.leaseWaitTimeout, "options.leaseWaitTimeout") ?? DEFAULT_LEASE_WAIT_TIMEOUT_MS;
+  assertLeaseTimingCoherent(leaseTtlMs, leaseRenewIntervalMs, leaseWaitTimeoutMs);
+  return { ownershipMode, leaseTtlMs, leaseRenewIntervalMs, leaseWaitTimeoutMs };
+}
+function assertKnownOwnershipMode(mode) {
+  if (mode !== "none" && mode !== "lease")
+    throw Error(`Unknown ownership posture "${String(mode)}". Expected 'none' or 'lease'.`);
+  return mode;
+}
+function assertLeaseTimingCoherent(leaseTtlMs, leaseRenewIntervalMs, leaseWaitTimeoutMs) {
+  if (leaseTtlMs <= 0 || leaseRenewIntervalMs <= 0 || leaseWaitTimeoutMs <= 0)
+    throw Error(`ownership: 'lease' requires positive leaseTtl, leaseRenewInterval, and leaseWaitTimeout (got leaseTtl=${leaseTtlMs}ms, leaseRenewInterval=${leaseRenewIntervalMs}ms, leaseWaitTimeout=${leaseWaitTimeoutMs}ms).`);
+  if (leaseRenewIntervalMs >= leaseTtlMs)
+    throw Error(`ownership: 'lease' requires leaseRenewInterval (${leaseRenewIntervalMs}ms) to be strictly less than leaseTtl (${leaseTtlMs}ms), so a renewal fires before the lease can lapse.`);
+}

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

@@ -0,0 +1,3 @@
+import type { Engine } from './index.ts';
+/** Internal server bridge for the engine's normalized payload-size cap. */
+export declare function getEnginePayloadSizeMaxBytes(engine: Engine): number | null;

package/dist/core/engine/payload-size-policy.js

@@ -0,0 +1,4 @@
+import { getInternals } from "./internals.js";
+export function getEnginePayloadSizeMaxBytes(engine) {
+  return getInternals(engine).options.payloadSizePolicy.maxBytes;
+}

package/dist/core/engine/pending-updates.d.ts

@@ -14,5 +14,22 @@ export declare function invokeUpdateHandler(internals: EngineInternals, name: st
  */
 export declare function processPendingUpdatesAfterInlineAdvance(internals: EngineInternals, workflowId: string, callbacks: PendingUpdateCallbacks): Promise<void>;
 export declare function schedulePendingInlineUpdateDrain(internals: EngineInternals, workflowId: string, callbacks: PendingUpdateCallbacks): void;
+/**
+ * Drain a workflow's buffered coordinated updates and deliver each to its
+ * handler exactly once, even when several drains race.
+ *
+ * Several triggers can fire near-simultaneously: each `engine.update()` schedules
+ * a `setTimeout(0)` drain, and the post-advance path drains too. Their consume-
+ * deletes are durable (`storage.batch`) and lag the in-memory `getPendingUpdates`
+ * scan, so two overlapping drains both see the same pending set. Each update id
+ * is therefore CLAIMED synchronously in `deliveredPendingUpdateIds` before
+ * delivery (no `await` between the membership check and the add, so a concurrent
+ * drain cannot interleave): a racing drain that re-reads the same id skips it.
+ *
+ * After the drain, re-drive a parked `ctx.waitUntil` once. A coordinated update
+ * buffered before `ctx.onUpdate` was registered drains here (not on the inline
+ * `tryInlineUpdateHandler` path), and a handler may have mutated the workflow-
+ * local state a predicate reads, so the wait must be poked to re-evaluate.
+ */
 export declare function processPendingUpdatesForHandlers(internals: EngineInternals, workflowId: string, callbacks: PendingUpdateCallbacks): Promise<void>;
 export {};

package/dist/core/engine/pending-updates.js

@@ -1,5 +1,7 @@
 import { UpdateCompletedEvent, UpdateReceivedEvent } from "../events.js";
 import { UpdateValidationError } from "../updates.js";
+import { notifyConditionWaiters } from "./condition-waiters.js";
+import { commitFencedEngineWrite } from "./fenced-write.js";
 import {
   extractStandardSchemaIssues,
   invokeUpdateHandler as invokeUpdateHandlerFromInternals
@@ -71,17 +73,37 @@ export async function processPendingUpdatesForHandlers(internals, workflowId, ca
   const pendingUpdates = await internals.updateCoordinator.getPendingUpdates(workflowId);
   if (pendingUpdates.length === 0)
     return;
-  for (const update of pendingUpdates) {
-    const handler = handlers.get(update.name);
-    if (!handler)
-      continue;
-    const validatorRejectionError = await runValidatorIfPresent(context, update);
-    if (validatorRejectionError !== null) {
-      await rejectPendingUpdate(internals, workflowId, update, validatorRejectionError, callbacks);
-      continue;
+  let handlerRan = !1;
+  try {
+    for (const update of pendingUpdates) {
+      const handler = handlers.get(update.name);
+      if (!handler)
+        continue;
+      if (!claimPendingUpdateForDelivery(internals, workflowId, update.updateId))
+        continue;
+      const validatorRejectionError = await runValidatorIfPresent(context, update);
+      if (validatorRejectionError !== null) {
+        await rejectPendingUpdate(internals, workflowId, update, validatorRejectionError, callbacks);
+        continue;
+      }
+      handlerRan = !0;
+      await deliverPendingUpdate(internals, workflowId, update, handler, callbacks);
     }
-    await deliverPendingUpdate(internals, workflowId, update, handler, callbacks);
+  } finally {
+    if (handlerRan)
+      notifyConditionWaiters(internals, workflowId);
+  }
+}
+function claimPendingUpdateForDelivery(internals, workflowId, updateId) {
+  let claimed = internals.deliveredPendingUpdateIds.get(workflowId);
+  if (claimed === void 0) {
+    claimed = new Set;
+    internals.deliveredPendingUpdateIds.set(workflowId, claimed);
   }
+  if (claimed.has(updateId))
+    return !1;
+  claimed.add(updateId);
+  return !0;
 }
 async function runValidatorIfPresent(context, update) {
   const validator = context.updateValidators?.get(update.name);
@@ -91,7 +113,7 @@ async function runValidatorIfPresent(context, update) {
 }
 async function rejectPendingUpdate(internals, workflowId, update, errorMessage, callbacks) {
   const responseOperations = internals.updateCoordinator.buildResponseOperations(update.updateId, workflowId, void 0, errorMessage, update.idempotencyKey);
-  await internals.storage.batch(responseOperations);
+  await commitFencedEngineWrite(internals, responseOperations, [], () => Error(`Update rejection for workflow "${workflowId}" lost its CAS race.`));
   callbacks.broadcast({ type: "update:completed", workflowId, updateId: update.updateId });
 }
 async function deliverPendingUpdate(internals, workflowId, update, handler, callbacks) {
@@ -103,7 +125,7 @@ async function deliverPendingUpdate(internals, workflowId, update, handler, call
     error = handlerError instanceof Error ? handlerError.message : String(handlerError);
   }
   const responseOperations = internals.updateCoordinator.buildResponseOperations(update.updateId, workflowId, result, error, update.idempotencyKey);
-  await internals.storage.batch(responseOperations);
+  await commitFencedEngineWrite(internals, responseOperations, [], () => Error(`Update response for workflow "${workflowId}" lost its CAS race.`));
   callbacks.dispatchEvent(new UpdateCompletedEvent(update.updateId, workflowId, update.name, result, error));
   callbacks.broadcast({ type: "update:completed", workflowId, updateId: update.updateId });
 }

package/dist/core/engine/persisted-data-version.d.ts

@@ -12,13 +12,9 @@ import type { Storage as WeftStorage } from '../../storage/interface.ts';
  * 3. Sentinel is absent. Only stamp the storage when it carries no user
  *    workflow data. Stamping a database that already holds workflow records,
  *    schedules, checkpoints, or any other `wf:` / `op:` / `schedule:` / `ev:`
- *    prefixed key would silently classify pre-versioned data (written by an
- *    older Weft binary or by the `new Engine({ storage })` constructor path
- *    before the sentinel was introduced) as schema-current and risk replaying
- *    incompatible records. When user data is already present without a
- *    sentinel, fail with `PersistedDataIncompatibleError(null, …)` so the
- *    operator can choose explicitly whether to wipe and start fresh.
+ *    prefixed key would silently classify unversioned data as schema-current
+ *    and risk replaying incompatible records. When user data is already present
+ *    without a sentinel, fail with `PersistedDataIncompatibleError(null, …)` so
+ *    the operator can choose explicitly whether to wipe and start fresh.
  */
-export declare function assertCompatiblePersistedDataVersion(storage: WeftStorage, options?: {
-    allowLegacyData?: boolean;
-}): Promise<void>;
+export declare function assertCompatiblePersistedDataVersion(storage: WeftStorage): Promise<void>;

package/dist/core/engine/persisted-data-version.js

@@ -4,7 +4,7 @@ import {
   PersistedDataIncompatibleError
 } from "../persisted-data-incompatible-error.js";
 const SCHEMA_VERSION_PATTERN = /^(?:0|[1-9]\d*)$/, USER_DATA_PREFIXES = ["wf:", "op:", "schedule:", "ev:", "sig:", "upd:", "idx:"];
-export async function assertCompatiblePersistedDataVersion(storage, options = {}) {
+export async function assertCompatiblePersistedDataVersion(storage) {
   const raw = await storage.get(PERSISTED_DATA_SCHEMA_VERSION_KEY);
   if (raw !== null) {
     const text = new TextDecoder().decode(raw);
@@ -17,9 +17,8 @@ export async function assertCompatiblePersistedDataVersion(storage, options = {}
       throw new PersistedDataIncompatibleError(parsed, CURRENT_PERSISTED_DATA_SCHEMA_VERSION);
     return;
   }
-  if (!options.allowLegacyData)
-    for (const prefix of USER_DATA_PREFIXES)
-      for await (const _entry of storage.scan(prefix, { limit: 1 }))
-        throw new PersistedDataIncompatibleError(null, CURRENT_PERSISTED_DATA_SCHEMA_VERSION);
+  for (const prefix of USER_DATA_PREFIXES)
+    for await (const _entry of storage.scan(prefix, { limit: 1 }))
+      throw new PersistedDataIncompatibleError(null, CURRENT_PERSISTED_DATA_SCHEMA_VERSION);
   await storage.put(PERSISTED_DATA_SCHEMA_VERSION_KEY, new TextEncoder().encode(String(CURRENT_PERSISTED_DATA_SCHEMA_VERSION)));
 }

package/dist/core/engine/queries.js

@@ -4,7 +4,7 @@ export async function query(internals, workflowId, name, input) {
   const inlineStrategy = internals.inlineStrategy;
   if (!inlineStrategy)
     throw Error("Workflow queries are not supported when using the worker execution strategy.");
-  const context = inlineStrategy.getContext(workflowId);
+  const context = inlineStrategy.getContext(workflowId) ?? inlineStrategy.getParkedContext(workflowId);
   if (!context)
     return;
   const queryHandler = context.queryHandlers.get(name);

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

@@ -1,6 +1,7 @@
 import type { EngineInternals } from './internals.ts';
 export type RegistrationCallbacks = {
     ensureRetentionSweepInterval: () => void;
+    dispatchEvent: (event: Event) => void;
 };
 export declare function register(internals: EngineInternals, definition: unknown, callbacks: RegistrationCallbacks): void;
 export declare function resolveWorkflowTypeTarget(internals: EngineInternals, target: string | Function, _callbacks: RegistrationCallbacks): string;

package/dist/core/engine/registration.js

@@ -1,4 +1,5 @@
 import { ActivityRegistry } from "../activity-registry.js";
+import { WorkflowDefinitionRegisteredEvent } from "../events.js";
 import {
   activity,
   validateDefinitionSchemaMetadata
@@ -31,16 +32,29 @@ function buildBaseRegistrationEntry(name, registration) {
     ...registration.outputSchema === void 0 ? {} : {
       outputSchema: validateDefinitionSchemaMetadata(registration.outputSchema, `registration("${name}").outputSchema`)
     },
-    ...normalizedRetention !== null && { retention: normalizedRetention }
+    ...normalizedRetention !== null && { retention: normalizedRetention },
+    ...registration.concurrency !== void 0 ? {
+      concurrency: normalizeWorkflowConcurrencyOptions(registration.concurrency, `registration("${name}").concurrency`)
+    } : {}
   };
 }
+function normalizeWorkflowConcurrencyOptions(concurrency, fieldName) {
+  if (!Number.isInteger(concurrency.max) || concurrency.max < 1)
+    throw RangeError(`${fieldName}.max must be a positive integer`);
+  if (concurrency.key !== void 0 && typeof concurrency.key !== "function")
+    throw TypeError(`${fieldName}.key must be a function when provided`);
+  return Object.freeze({
+    max: concurrency.max,
+    ...concurrency.key === void 0 ? {} : { key: concurrency.key }
+  });
+}
 function applyOptionalRegistrationFields(entry, registration) {
-  if (registration.migrate)
-    entry.migrate = registration.migrate;
   if (registration.searchAttributes && Object.keys(registration.searchAttributes).length > 0)
     entry.searchAttributes = registration.searchAttributes;
   if (registration.constraints && registration.constraints.length > 0)
     entry.constraints = registration.constraints;
+  if (registration.finalizer !== void 0)
+    entry.finalizer = registration.finalizer;
 }
 function buildRegistrationEntry(name, registration) {
   const entry = buildBaseRegistrationEntry(name, registration);
@@ -55,6 +69,7 @@ function commitWorkflowDefinition(internals, definition, callbacks) {
   internals.registrations.set(name, entry);
   callbacks.ensureRetentionSweepInterval();
   internals.workflowTypesByHandler.set(definition.handler, name);
+  callbacks.dispatchEvent(new WorkflowDefinitionRegisteredEvent(name));
 }
 function hasNonNullObjectField(value, key) {
   if (!(key in value))

package/dist/core/engine/schedule-handle.d.ts

@@ -0,0 +1,45 @@
+import type { ScheduleSpec, ScheduleSummary } from '../types.ts';
+/**
+ * Narrow engine view a {@link ScheduleHandle} delegates to. The full
+ * {@link Engine} implements it; the handle only depends on these schedule
+ * lifecycle operations.
+ */
+export interface ScheduleHandleEngine {
+    pauseSchedule(scheduleId: string): Promise<void>;
+    resumeSchedule(scheduleId: string): Promise<void>;
+    cancelSchedule(scheduleId: string): Promise<void>;
+    updateSchedule(scheduleId: string, newSpec: string | ScheduleSpec): Promise<void>;
+    getSchedule(scheduleId: string): Promise<ScheduleSummary | null>;
+}
+/**
+ * Handle to a recurring schedule created by {@link Engine.schedule}. Use
+ * `handle.pause()`, `handle.resume()`, `handle.cancel()`, or
+ * `handle.update(cronExpression)` to manage the schedule lifecycle.
+ * `handle.describe()` returns the current {@link ScheduleSummary}.
+ *
+ * @example
+ * ```ts
+ * import { workflow, Engine, ScheduleHandle } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.register(workflow({ name: 'daily-report' }).execute(async function* () { return 'ok'; }));
+ *
+ * const handle = await engine.schedule('daily-report', null, '0 9 * * *');
+ * const typedHandle: ScheduleHandle = handle;
+ * await handle.pause();
+ * const summary = await handle.describe();
+ * void typedHandle;
+ * console.log(summary.status); // 'paused'
+ * await handle.cancel();
+ * ```
+ */
+export declare class ScheduleHandle {
+    #private;
+    readonly id: string;
+    constructor(id: string, engine: ScheduleHandleEngine);
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    cancel(): Promise<void>;
+    update(newSpec: string | ScheduleSpec): Promise<void>;
+    describe(): Promise<ScheduleSummary>;
+}

package/dist/core/engine/schedule-handle.js

@@ -0,0 +1,26 @@
+export class ScheduleHandle {
+  id;
+  #engine;
+  constructor(id, engine) {
+    this.id = id;
+    this.#engine = engine;
+  }
+  async pause() {
+    await this.#engine.pauseSchedule(this.id);
+  }
+  async resume() {
+    await this.#engine.resumeSchedule(this.id);
+  }
+  async cancel() {
+    await this.#engine.cancelSchedule(this.id);
+  }
+  async update(newSpec) {
+    await this.#engine.updateSchedule(this.id, newSpec);
+  }
+  async describe() {
+    const schedule = await this.#engine.getSchedule(this.id);
+    if (!schedule)
+      throw Error(`Schedule "${this.id}" not found`);
+    return schedule;
+  }
+}

package/dist/core/engine/schedule-jitter.d.ts

@@ -0,0 +1,5 @@
+import type { ScheduleState } from '../types.ts';
+type JitteredSchedule = Pick<ScheduleState, 'id' | 'jitterMs'>;
+export declare function computeScheduleJitterOffset(scheduleId: string, nominalFireAt: number, jitterMs: number | undefined): number;
+export declare function resolveEffectiveScheduleFireAt(schedule: JitteredSchedule, nominalFireAt: number): number;
+export {};

package/dist/core/engine/schedule-jitter.js

@@ -0,0 +1,10 @@
+import { hashString } from "../../runtime/portable.js";
+export function computeScheduleJitterOffset(scheduleId, nominalFireAt, jitterMs) {
+  if (jitterMs === void 0 || jitterMs <= 0)
+    return 0;
+  const hash = BigInt(`0x${hashString(`${scheduleId}\x00${nominalFireAt}`)}`);
+  return Number(hash % BigInt(jitterMs));
+}
+export function resolveEffectiveScheduleFireAt(schedule, nominalFireAt) {
+  return nominalFireAt + computeScheduleJitterOffset(schedule.id, nominalFireAt, schedule.jitterMs);
+}

package/dist/core/engine/schedule-run.d.ts

@@ -0,0 +1,17 @@
+import type { ScheduleState } from '../types.ts';
+import type { EngineInternals } from './internals.ts';
+import type { ScheduleCallbacks } from './schedules.ts';
+/**
+ * Launch one scheduled occurrence's workflow run and emit `schedule:fired`.
+ *
+ * This is the single chokepoint every occurrence launch flows through — initial
+ * cadence ticks, `cancel-running` replacements, and `queue`-drained runs — so it
+ * is the one place that reliably holds the launched `workflowId` across all
+ * overlap policies. The blocked policies (`skip`, and `queue` while a run is
+ * active) never reach here, so they correctly do not fire.
+ *
+ * `occurrence` is the scheduled grid timestamp the run was due, threaded from the
+ * timer loop. It is `undefined` for a `queue`-drained run, whose grid slot was
+ * tracked only as a count and whose original timestamp is therefore gone.
+ */
+export declare function startScheduledRun(internals: EngineInternals, state: ScheduleState, callbacks: Pick<ScheduleCallbacks, 'startWorkflow' | 'failWorkflow' | 'handleCleanupError'>, occurrence?: number): Promise<string>;