@lostgradient/weft 0.2.0

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

@@ -0,0 +1,35 @@
+import type { ScheduleState } from '../types.ts';
+/**
+ * The recurrence cadence of a schedule, decoded from persisted state into a
+ * single discriminated value so occurrence computation never has to inspect
+ * both `cronExpression` and `intervalMs` at every call site.
+ */
+export type ScheduleCadence = {
+    kind: 'cron';
+    cronExpression: string;
+} | {
+    kind: 'interval';
+    intervalMs: number;
+    anchor: number;
+};
+type CadenceSource = Pick<ScheduleState, 'cronExpression' | 'intervalMs' | 'createdAt'>;
+/**
+ * Resolve the cadence of a schedule from its persisted state. Interval schedules
+ * are anchored at `createdAt`. Throws if the state carries neither a cron
+ * expression nor an interval, which should never happen for a record that passed
+ * decode validation.
+ */
+export declare function resolveScheduleCadence(state: CadenceSource): ScheduleCadence;
+/**
+ * Compute the next occurrence strictly after `afterTimestamp` for a schedule,
+ * dispatching on cadence kind. Cron schedules defer to the cron engine; interval
+ * schedules step forward one period anchored at creation time.
+ */
+export declare function getNextScheduleOccurrence(state: CadenceSource, afterTimestamp: number): number;
+/**
+ * Collect every occurrence in the inclusive window `[firstDueAt, throughTimestamp]`
+ * for a schedule, dispatching on cadence kind. `maxOccurrences` bounds the result
+ * so a long backfill window cannot produce an unbounded list.
+ */
+export declare function collectDueScheduleOccurrences(state: CadenceSource, firstDueAt: number, throughTimestamp: number, maxOccurrences: number): number[];
+export {};

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

@@ -0,0 +1,26 @@
+import { collectDueCronOccurrences, getNextCronOccurrence } from "../schedule.js";
+import {
+  collectDueIntervalOccurrences,
+  getNextIntervalOccurrence
+} from "../schedule/interval-occurrence.js";
+export function resolveScheduleCadence(state) {
+  if (state.intervalMs !== void 0)
+    return { kind: "interval", intervalMs: state.intervalMs, anchor: state.createdAt };
+  if (state.cronExpression !== void 0)
+    return { kind: "cron", cronExpression: state.cronExpression };
+  throw Error("Schedule state must define either a cron expression or an interval");
+}
+export function getNextScheduleOccurrence(state, afterTimestamp) {
+  const cadence = resolveScheduleCadence(state);
+  if (cadence.kind === "interval")
+    return getNextIntervalOccurrence(cadence.anchor, cadence.intervalMs, afterTimestamp);
+  return getNextCronOccurrence(cadence.cronExpression, afterTimestamp);
+}
+export function collectDueScheduleOccurrences(state, firstDueAt, throughTimestamp, maxOccurrences) {
+  const cadence = resolveScheduleCadence(state);
+  if (cadence.kind === "interval")
+    return collectDueIntervalOccurrences(cadence.anchor, cadence.intervalMs, firstDueAt, throughTimestamp, { maxOccurrences });
+  return collectDueCronOccurrences(cadence.cronExpression, firstDueAt, throughTimestamp, {
+    maxOccurrences
+  });
+}

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

@@ -0,0 +1,4 @@
+import type { TimerEntry } from '../types.ts';
+import type { EngineInternals } from './internals.ts';
+import type { ScheduleCallbacks } from './schedules.ts';
+export declare function handleScheduleTimer(internals: EngineInternals, entry: TimerEntry, callbacks: ScheduleCallbacks): Promise<void>;

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

@@ -0,0 +1,77 @@
+import { collectDueScheduleOccurrences, getNextScheduleOccurrence } from "./schedule-occurrence.js";
+import { loadScheduleState, writeScheduleState } from "./storage-io.js";
+const SCHEDULE_LATE_GRACE_MILLISECONDS = 1000, MAX_SCHEDULE_BACKFILL_OCCURRENCES_PER_TICK = 256;
+export async function handleScheduleTimer(internals, entry, callbacks) {
+  const state = await loadScheduleState(internals, entry.workflowId);
+  if (!isCurrentActiveScheduleTimer(state, entry))
+    return;
+  let nextState = state;
+  try {
+    const now = internals.options.getNow(), work = planScheduleTimerWork(state, entry, now);
+    if (!work)
+      return;
+    nextState = await processScheduleTimerOccurrences(internals, state, work.occurrencesToProcess, now, callbacks, (processedState) => {
+      nextState = processedState;
+    });
+    await writeScheduleState(internals, {
+      ...nextState,
+      updatedAt: now,
+      nextFireAt: resolveNextScheduleFireAt(nextState, work, now)
+    });
+  } catch (error) {
+    await pauseScheduleAfterTimerFailure(internals, nextState, error);
+  }
+}
+function isCurrentActiveScheduleTimer(state, entry) {
+  return state?.status === "active" && state.nextFireAt === entry.fireAt;
+}
+function planScheduleTimerWork(state, entry, now) {
+  const dueOccurrences = collectDueScheduleOccurrences(state, state.nextFireAt, Math.max(now, entry.fireAt), state.backfill ? MAX_SCHEDULE_BACKFILL_OCCURRENCES_PER_TICK : 2);
+  if (dueOccurrences.length === 0)
+    return null;
+  if (!state.backfill && now - state.nextFireAt > SCHEDULE_LATE_GRACE_MILLISECONDS)
+    return {
+      dueOccurrences,
+      occurrencesToProcess: [],
+      skipMissedOccurrences: !0
+    };
+  const occurrencesToProcess = state.backfill ? dueOccurrences : dueOccurrences.slice(0, 1);
+  return {
+    dueOccurrences,
+    occurrencesToProcess,
+    skipMissedOccurrences: !1
+  };
+}
+function resolveNextScheduleFireAt(state, work, now) {
+  if (work.skipMissedOccurrences)
+    return getNextScheduleOccurrence(state, now);
+  const anchorOccurrence = work.occurrencesToProcess.at(-1) ?? work.dueOccurrences.at(-1);
+  return getNextScheduleOccurrence(state, anchorOccurrence);
+}
+async function processScheduleTimerOccurrences(internals, state, occurrencesToProcess, now, callbacks, onProcessedState) {
+  let nextState = state;
+  for (const occurrence of occurrencesToProcess) {
+    nextState = {
+      ...await callbacks.applyScheduleOccurrence(nextState),
+      lastFireAt: occurrence,
+      updatedAt: now
+    };
+    onProcessedState(nextState);
+    await writeScheduleState(internals, nextState, { includeTimer: !1 });
+    if (state.backfill && nextState.currentWorkflowId !== void 0) {
+      nextState = await callbacks.settleBackfillScheduleState(nextState);
+      onProcessedState(nextState);
+    }
+  }
+  return nextState;
+}
+async function pauseScheduleAfterTimerFailure(internals, state, error) {
+  const errorNow = internals.options.getNow(), pausedState = {
+    ...state,
+    status: "paused",
+    updatedAt: errorNow,
+    nextFireAt: getNextScheduleOccurrence(state, errorNow)
+  };
+  await writeScheduleState(internals, pausedState, { includeTimer: !1 });
+  console.error(`[weft] Paused schedule "${pausedState.id}" after timer processing failed:`, error);
+}

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

@@ -0,0 +1,34 @@
+import type { BatchOperation } from '../../storage/interface.ts';
+import type { PaginatedResult, ScheduleFilter, ScheduleOptions, ScheduleSpec, ScheduleState, ScheduleSummary, WorkflowState } from '../types.ts';
+import { ScheduleHandle } from './handles.ts';
+import type { EngineInternals } from './internals.ts';
+export { handleScheduleTimer } from './schedule-timer.ts';
+export type RefreshedScheduleState = {
+    state: ScheduleState;
+    currentWorkflowState: WorkflowState | null;
+};
+export type ScheduleCallbacks = {
+    startWorkflow: (type: string, input: unknown, options: {
+        id: string;
+    }, additionalStartOperations?: BatchOperation[]) => Promise<void>;
+    loadWorkflowState: (workflowId: string) => Promise<WorkflowState | null | undefined>;
+    cancelWorkflow: (workflowId: string) => Promise<void>;
+    getWorkflowResult: (workflowId: string) => Promise<unknown>;
+    refreshScheduledWorkflowState: (state: ScheduleState) => Promise<RefreshedScheduleState>;
+    startScheduledRun: (state: ScheduleState) => Promise<string>;
+    applyScheduleOccurrence: (state: ScheduleState) => Promise<ScheduleState>;
+    settleBackfillScheduleState: (state: ScheduleState) => Promise<ScheduleState>;
+    flushQueuedInlineWorkflowStartsDirectly: () => Promise<void>;
+};
+export declare function schedule(internals: EngineInternals, type: string, input: unknown, spec: string | ScheduleSpec, options?: ScheduleOptions): Promise<ScheduleHandle>;
+export declare function listSchedules(internals: EngineInternals, filter?: ScheduleFilter): Promise<PaginatedResult<ScheduleSummary>>;
+export declare function toScheduleSummary(state: ScheduleState): ScheduleSummary;
+export declare function pauseSchedule(internals: EngineInternals, scheduleId: string): Promise<void>;
+export declare function resumeSchedule(internals: EngineInternals, scheduleId: string): Promise<void>;
+export declare function cancelSchedule(internals: EngineInternals, scheduleId: string): Promise<void>;
+export declare function updateSchedule(internals: EngineInternals, scheduleId: string, newSpec: string | ScheduleSpec): Promise<void>;
+export declare function refreshScheduledWorkflowState(internals: EngineInternals, state: ScheduleState, callbacks: Pick<ScheduleCallbacks, 'loadWorkflowState'>): Promise<RefreshedScheduleState>;
+export declare function startScheduledRun(_internals: EngineInternals, state: ScheduleState, callbacks: Pick<ScheduleCallbacks, 'startWorkflow'>): Promise<string>;
+export declare function applyScheduleOccurrence(_internals: EngineInternals, state: ScheduleState, callbacks: ScheduleCallbacks): Promise<ScheduleState>;
+export declare function settleBackfillScheduleState(internals: EngineInternals, state: ScheduleState, callbacks: Pick<ScheduleCallbacks, 'flushQueuedInlineWorkflowStartsDirectly' | 'refreshScheduledWorkflowState'>): Promise<ScheduleState>;
+export declare function handleScheduledWorkflowTerminal(internals: EngineInternals, workflowId: string, callbacks: ScheduleCallbacks): Promise<void>;

package/dist/core/engine/schedules.js

@@ -0,0 +1,204 @@
+import { KEYS } from "../../storage/interface.js";
+import { decode, encode } from "../codec.js";
+import { WorkflowNotRegisteredError } from "./errors.js";
+import { ScheduleHandle } from "./handles.js";
+import { getNextScheduleOccurrence } from "./schedule-occurrence.js";
+import {
+  clearScheduleCurrentWorkflow,
+  createScheduleTimerId,
+  matchesScheduleFilter,
+  paginateScheduleSummaries
+} from "./state-utilities.js";
+import { loadScheduleState, requireScheduleState, writeScheduleState } from "./storage-io.js";
+import {
+  coerceScheduleId,
+  decodeScheduleState,
+  isValidScheduleIdentifier,
+  normalizeScheduleFilter,
+  normalizeScheduleOptions,
+  normalizeScheduleSpec
+} from "./validation/schedule.js";
+export { handleScheduleTimer } from "./schedule-timer.js";
+export async function schedule(internals, type, input, spec, options) {
+  if (!internals.registrations.has(type))
+    throw new WorkflowNotRegisteredError(type);
+  const normalizedSpec = normalizeScheduleSpec(spec), normalizedOptions = normalizeScheduleOptions(options), scheduleId = normalizedOptions.id ?? crypto.randomUUID();
+  if (internals.pendingScheduleCreations.has(scheduleId))
+    throw Error(`Schedule with id "${scheduleId}" already exists`);
+  internals.pendingScheduleCreations.add(scheduleId);
+  try {
+    if (await internals.storage.get(KEYS.schedule(scheduleId)))
+      throw Error(`Schedule with id "${scheduleId}" already exists`);
+    const now = internals.options.getNow(), cadenceFields = normalizedSpec.kind === "interval" ? { intervalMs: normalizedSpec.intervalMs } : { cronExpression: normalizedSpec.cronExpression }, state = {
+      id: scheduleId,
+      workflowType: type,
+      input,
+      ...cadenceFields,
+      status: "active",
+      overlap: normalizedOptions.overlap,
+      backfill: normalizedOptions.backfill,
+      createdAt: now,
+      updatedAt: now,
+      nextFireAt: getNextScheduleOccurrence({ ...cadenceFields, createdAt: now }, now),
+      queuedRuns: 0
+    };
+    await writeScheduleState(internals, state);
+    return new ScheduleHandle(scheduleId, internals.engine);
+  } finally {
+    internals.pendingScheduleCreations.delete(scheduleId);
+  }
+}
+export async function listSchedules(internals, filter) {
+  const normalizedFilter = normalizeScheduleFilter(filter), items = [];
+  for await (const [key, value] of internals.storage.scan("schedule:")) {
+    if (key.slice(9).includes(":"))
+      continue;
+    const state = decodeScheduleState(value);
+    if (!state || !matchesScheduleFilter(state, normalizedFilter))
+      continue;
+    const { input: _input, ...summary } = state;
+    items.push(summary);
+  }
+  return paginateScheduleSummaries(items, normalizedFilter);
+}
+export function toScheduleSummary(state) {
+  const { input: _input, ...summary } = state;
+  return summary;
+}
+export async function pauseSchedule(internals, scheduleId) {
+  const normalizedScheduleId = coerceScheduleId(scheduleId, "scheduleId"), state = await requireScheduleState(internals, normalizedScheduleId);
+  if (state.status !== "active")
+    return;
+  await internals.scheduler.cancel(createScheduleTimerId(normalizedScheduleId), normalizedScheduleId);
+  const now = internals.options.getNow(), updatedState = {
+    ...state,
+    status: "paused",
+    updatedAt: now,
+    nextFireAt: getNextScheduleOccurrence(state, now),
+    queuedRuns: 0
+  };
+  await writeScheduleState(internals, updatedState, { includeTimer: !1 });
+}
+export async function resumeSchedule(internals, scheduleId) {
+  const normalizedScheduleId = coerceScheduleId(scheduleId, "scheduleId"), state = await requireScheduleState(internals, normalizedScheduleId);
+  if (state.status === "cancelled")
+    throw Error(`Schedule "${normalizedScheduleId}" has been cancelled and cannot be resumed`);
+  if (state.status === "active")
+    return;
+  const now = internals.options.getNow(), updatedState = {
+    ...state,
+    status: "active",
+    updatedAt: now,
+    nextFireAt: getNextScheduleOccurrence(state, now)
+  };
+  await writeScheduleState(internals, updatedState);
+}
+export async function cancelSchedule(internals, scheduleId) {
+  const normalizedScheduleId = coerceScheduleId(scheduleId, "scheduleId"), state = await requireScheduleState(internals, normalizedScheduleId);
+  if (state.status === "active")
+    await internals.scheduler.cancel(createScheduleTimerId(normalizedScheduleId), normalizedScheduleId);
+  const updatedState = {
+    ...state,
+    status: "cancelled",
+    updatedAt: internals.options.getNow(),
+    nextFireAt: null,
+    queuedRuns: 0
+  };
+  await writeScheduleState(internals, updatedState, { includeTimer: !1 });
+}
+export async function updateSchedule(internals, scheduleId, newSpec) {
+  const normalizedScheduleId = coerceScheduleId(scheduleId, "scheduleId"), normalizedSpec = normalizeScheduleSpec(newSpec), state = await requireScheduleState(internals, normalizedScheduleId);
+  if (state.status === "active")
+    await internals.scheduler.cancel(createScheduleTimerId(normalizedScheduleId), normalizedScheduleId);
+  const now = internals.options.getNow(), {
+    cronExpression: _droppedCron,
+    intervalMs: _droppedInterval,
+    ...stateWithoutCadence
+  } = state, cadenceFields = normalizedSpec.kind === "interval" ? { intervalMs: normalizedSpec.intervalMs } : { cronExpression: normalizedSpec.cronExpression }, anchorFields = normalizedSpec.kind === "interval" ? { createdAt: now } : {}, updatedState = {
+    ...stateWithoutCadence,
+    ...cadenceFields,
+    ...anchorFields,
+    updatedAt: now,
+    nextFireAt: state.status === "cancelled" ? null : getNextScheduleOccurrence({ ...cadenceFields, createdAt: now }, now)
+  };
+  await writeScheduleState(internals, updatedState, { includeTimer: state.status === "active" });
+}
+export async function refreshScheduledWorkflowState(internals, state, callbacks) {
+  if (!state.currentWorkflowId)
+    return { state, currentWorkflowState: null };
+  const currentWorkflowState = await callbacks.loadWorkflowState(state.currentWorkflowId);
+  if (currentWorkflowState?.status === "running" || currentWorkflowState?.status === "pending")
+    return { state, currentWorkflowState };
+  await internals.storage.delete(KEYS.scheduleRun(state.currentWorkflowId));
+  return {
+    state: clearScheduleCurrentWorkflow(state),
+    currentWorkflowState: currentWorkflowState ?? null
+  };
+}
+export async function startScheduledRun(_internals, state, callbacks) {
+  const workflowId = crypto.randomUUID(), scheduleRunOperations = state.overlap === "allow" ? void 0 : [{ type: "put", key: KEYS.scheduleRun(workflowId), value: encode(state.id) }];
+  await callbacks.startWorkflow(state.workflowType, state.input, { id: workflowId }, scheduleRunOperations);
+  return workflowId;
+}
+function hasActiveScheduledWorkflow(currentWorkflowState) {
+  return currentWorkflowState?.status === "running" || currentWorkflowState?.status === "pending";
+}
+async function applyBlockedScheduleOccurrence(state, hasActiveWorkflow, callbacks) {
+  if (!hasActiveWorkflow)
+    return { ...state, currentWorkflowId: await callbacks.startScheduledRun(state) };
+  if (state.overlap === "cancel-running") {
+    if (state.currentWorkflowId) {
+      callbacks.getWorkflowResult(state.currentWorkflowId).catch(() => {});
+      await callbacks.cancelWorkflow(state.currentWorkflowId);
+    }
+    const stateForStart = clearScheduleCurrentWorkflow(state);
+    return { ...state, currentWorkflowId: await callbacks.startScheduledRun(stateForStart) };
+  }
+  if (state.overlap === "queue")
+    return { ...state, queuedRuns: state.queuedRuns + 1 };
+  return state;
+}
+export async function applyScheduleOccurrence(_internals, state, callbacks) {
+  const { state: refreshedState, currentWorkflowState } = await callbacks.refreshScheduledWorkflowState(state), hasActiveWorkflow = hasActiveScheduledWorkflow(currentWorkflowState);
+  if (refreshedState.overlap === "allow") {
+    await callbacks.startScheduledRun(refreshedState);
+    return refreshedState;
+  }
+  return applyBlockedScheduleOccurrence(refreshedState, hasActiveWorkflow, callbacks);
+}
+export async function settleBackfillScheduleState(internals, state, callbacks) {
+  if (!state.currentWorkflowId)
+    return state;
+  await callbacks.flushQueuedInlineWorkflowStartsDirectly();
+  const pendingTurn = internals.inlineStrategy?.waitForWorkflowTurn(state.currentWorkflowId);
+  if (pendingTurn)
+    await pendingTurn;
+  return (await callbacks.refreshScheduledWorkflowState(state)).state;
+}
+export async function handleScheduledWorkflowTerminal(internals, workflowId, callbacks) {
+  const scheduleRunBytes = await internals.storage.get(KEYS.scheduleRun(workflowId));
+  if (!scheduleRunBytes)
+    return;
+  await internals.storage.delete(KEYS.scheduleRun(workflowId));
+  const decodedScheduleId = decode(scheduleRunBytes);
+  if (!isValidScheduleIdentifier(decodedScheduleId))
+    return;
+  const state = await loadScheduleState(internals, decodedScheduleId);
+  if (!state || state.currentWorkflowId !== workflowId)
+    return;
+  const now = internals.options.getNow(), clearedState = {
+    ...clearScheduleCurrentWorkflow(state),
+    updatedAt: now
+  };
+  if (clearedState.status === "active" && clearedState.overlap === "queue" && clearedState.queuedRuns > 0) {
+    const nextWorkflowId = await callbacks.startScheduledRun(clearedState);
+    await writeScheduleState(internals, {
+      ...clearedState,
+      currentWorkflowId: nextWorkflowId,
+      queuedRuns: clearedState.queuedRuns - 1,
+      updatedAt: now
+    }, { includeTimer: !1 });
+    return;
+  }
+  await writeScheduleState(internals, clearedState, { includeTimer: !1 });
+}

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

@@ -0,0 +1,40 @@
+import type { ComposedWorkflowInterceptor } from '../interceptor.ts';
+import type { SignalDeliveryOptions, WorkflowState } from '../types.ts';
+import type { EngineInternals } from './internals.ts';
+type TrackedWaiterKeys = string | Set<string>;
+export type SignalCallbacks = {
+    loadWorkflowState: (workflowId: string) => Promise<WorkflowState | null | undefined>;
+    dispatchEvent: (event: Event) => boolean;
+    broadcast: (message: {
+        type: 'signal:received';
+        workflowId: string;
+        signalName: string;
+    }) => void;
+    getComposedInterceptor: () => ComposedWorkflowInterceptor | null | undefined;
+    resumeParkedInlineWorkflow: (workflowId: string) => Promise<void>;
+};
+export type BufferedSignalOptions = {
+    emitPublicEvent?: boolean;
+    signalId?: string;
+};
+export type BufferedSignalDelivery = {
+    signalName: string;
+    payload: unknown;
+    options?: BufferedSignalOptions;
+};
+export type ConsumedSignalResult = {
+    found: false;
+} | {
+    found: true;
+    payload: unknown;
+};
+export declare function signal(internals: EngineInternals, workflowId: string, name: string, payload: unknown, callbacks: SignalCallbacks, options?: SignalDeliveryOptions): Promise<void>;
+export declare function releaseSignalWaiter(internals: EngineInternals, workflowId: string, waiterKey: string, expectedResolve?: () => void): void;
+export declare function bufferSignalPayloads(internals: EngineInternals, workflowId: string, deliveries: BufferedSignalDelivery[], callbacks: SignalCallbacks, defaultOptions?: SignalDeliveryOptions): Promise<void>;
+export declare function hasBufferedSignal(internals: EngineInternals, workflowId: string, signalName: string): Promise<boolean>;
+export declare function consumeSignal(internals: EngineInternals, workflowId: string, signalName: string): Promise<ConsumedSignalResult>;
+/** Register a waiter key in a workflow-keyed reverse index. */
+export declare function trackWaiterKey(reverseIndex: Map<string, TrackedWaiterKeys>, workflowId: string, waiterKey: string): void;
+/** Remove a waiter key from a workflow-keyed reverse index. */
+export declare function untrackWaiterKey(reverseIndex: Map<string, TrackedWaiterKeys>, workflowId: string, waiterKey: string): void;
+export {};

package/dist/core/engine/signals.js

@@ -0,0 +1,185 @@
+import {
+  KEYS,
+  encodeStorageKeyComponent,
+  requireStorageCapability,
+  storageConditionalBatch
+} from "../../storage/interface.js";
+import { decode, encode } from "../codec.js";
+import { SignalReceivedEvent } from "../events.js";
+import { encodePayloadWithinLimit } from "../payload-size.js";
+import { validateSignalId } from "../signal-id.js";
+import { commitAnonymousSignalOperations } from "./anonymous-signal-sequence.js";
+import { isTerminalWorkflowStatus } from "./validation.js";
+const EMPTY_STORAGE_VALUE = new Uint8Array(0), SIGNAL_ACCEPTED_RESPONSE = { ok: !0 };
+export async function signal(internals, workflowId, name, payload, callbacks, options = {}) {
+  const deliverSignal = async (targetWorkflowId, signalName, signalPayload) => {
+    await bufferSignalPayloads(internals, targetWorkflowId, [{ signalName, payload: signalPayload }], callbacks, options);
+  }, composed = callbacks.getComposedInterceptor();
+  if (composed) {
+    let deliveryPromise, nextCalled = !1;
+    try {
+      composed.signalReceived({
+        workflowId,
+        signalName: name,
+        payload,
+        headers: new Map
+      }, (interception) => {
+        if (nextCalled)
+          throw Error("signalReceived interceptor called next() more than once");
+        nextCalled = !0;
+        deliveryPromise = deliverSignal(interception.workflowId, interception.signalName, interception.payload);
+      });
+    } catch (error) {
+      if (deliveryPromise)
+        await deliveryPromise;
+      throw error;
+    }
+    if (!deliveryPromise)
+      return;
+    await deliveryPromise;
+  } else
+    await deliverSignal(workflowId, name, payload);
+}
+export function releaseSignalWaiter(internals, workflowId, waiterKey, expectedResolve) {
+  const currentWaiter = internals.signalWaiters.get(waiterKey);
+  if (!currentWaiter)
+    return;
+  if (expectedResolve && currentWaiter !== expectedResolve)
+    return;
+  internals.signalWaiters.delete(waiterKey);
+  untrackWaiterKey(internals.signalWaitersByWorkflow, workflowId, waiterKey);
+}
+export async function bufferSignalPayloads(internals, workflowId, deliveries, callbacks, defaultOptions = {}) {
+  if (deliveries.length === 0)
+    return;
+  const targetState = await callbacks.loadWorkflowState(workflowId);
+  if (targetState && isTerminalWorkflowStatus(targetState.status))
+    return;
+  const signalId = getSingleSignalId(deliveries, defaultOptions);
+  validateSignalIdsBeforeKeyConstruction(deliveries, defaultOptions, signalId);
+  if (signalId !== void 0)
+    requireStorageCapability(internals.storage, "conditionalBatch", "signal idempotency");
+  if (signalId !== void 0) {
+    const operations = createExplicitSignalOperations(internals, workflowId, deliveries, signalId);
+    appendTerminalCleanupOperation(internals, workflowId, operations);
+    const delivery = deliveries[0], acceptedResponseKey = KEYS.signalAcceptedResponse(workflowId, delivery.signalName, signalId), acceptedResponse = encode(SIGNAL_ACCEPTED_RESPONSE);
+    if (await internals.storage.get(acceptedResponseKey) !== null)
+      return;
+    if (!await storageConditionalBatch(internals.storage, [{ key: KEYS.signal(workflowId, delivery.signalName, signalId), expectedValue: null }], [...operations, { type: "put", key: acceptedResponseKey, value: acceptedResponse }])) {
+      await ensureDuplicateSignalAcceptedResponse(internals, acceptedResponseKey, acceptedResponse);
+      return;
+    }
+    markTerminalCleanupTracked(internals, workflowId);
+    deliverBufferedSignals(internals, workflowId, deliveries, callbacks);
+    return;
+  }
+  await commitAnonymousSignalOperations(internals, workflowId, deliveries, (operations) => appendTerminalCleanupOperation(internals, workflowId, operations), () => markTerminalCleanupTracked(internals, workflowId));
+  deliverBufferedSignals(internals, workflowId, deliveries, callbacks);
+}
+function createExplicitSignalOperations(internals, workflowId, deliveries, signalId) {
+  return deliveries.map(({ signalName, payload }) => ({
+    type: "put",
+    key: KEYS.signal(workflowId, signalName, signalId),
+    value: encodePayloadWithinLimit(payload, internals.options.payloadSizePolicy.maxBytes, "signal payload")
+  }));
+}
+function appendTerminalCleanupOperation(internals, workflowId, operations) {
+  if (internals.workflowsNeedingTerminalCleanup.has(workflowId))
+    return;
+  operations.push({
+    type: "put",
+    key: KEYS.terminalCleanupNeeded(workflowId),
+    value: EMPTY_STORAGE_VALUE
+  });
+}
+function markTerminalCleanupTracked(internals, workflowId) {
+  internals.workflowsNeedingTerminalCleanup.add(workflowId);
+}
+function deliverBufferedSignals(internals, workflowId, deliveries, callbacks) {
+  let shouldResumeParkedWorkflow = !1;
+  for (const { signalName, payload, options } of deliveries) {
+    if (options?.emitPublicEvent !== !1) {
+      callbacks.dispatchEvent(new SignalReceivedEvent(workflowId, signalName, payload));
+      callbacks.broadcast({ type: "signal:received", workflowId, signalName });
+    }
+    const waiterKey = `${workflowId}:${signalName}`, waiter = internals.signalWaiters.get(waiterKey);
+    if (waiter) {
+      releaseSignalWaiter(internals, workflowId, waiterKey, waiter);
+      waiter();
+      continue;
+    }
+    if (internals.parkedInlineWorkflows.has(workflowId))
+      shouldResumeParkedWorkflow = !0;
+  }
+  if (shouldResumeParkedWorkflow)
+    callbacks.resumeParkedInlineWorkflow(workflowId);
+}
+export async function hasBufferedSignal(internals, workflowId, signalName) {
+  const prefix = `sig:${encodeStorageKeyComponent(workflowId)}:${signalName}:`;
+  for await (const _entry of internals.storage.scan(prefix, { limit: 1 }))
+    return !0;
+  return !1;
+}
+export async function consumeSignal(internals, workflowId, signalName) {
+  const prefix = `sig:${encodeStorageKeyComponent(workflowId)}:${signalName}:`;
+  for await (const [key, value] of internals.storage.scan(prefix, { limit: 1 })) {
+    await internals.storage.delete(key);
+    return { found: !0, payload: decode(value) };
+  }
+  return { found: !1 };
+}
+function getSingleSignalId(deliveries, defaultOptions) {
+  if (deliveries.length !== 1)
+    return;
+  return deliveries[0]?.options?.signalId ?? defaultOptions.signalId;
+}
+function validateSignalIdsBeforeKeyConstruction(deliveries, defaultOptions, singleSignalId) {
+  if (singleSignalId !== void 0) {
+    validateSignalId(singleSignalId);
+    return;
+  }
+  for (const delivery of deliveries) {
+    const deliverySignalId = delivery.options?.signalId ?? defaultOptions.signalId;
+    if (deliverySignalId !== void 0)
+      validateSignalId(deliverySignalId);
+  }
+}
+async function ensureDuplicateSignalAcceptedResponse(internals, acceptedResponseKey, acceptedResponse) {
+  if (await internals.storage.get(acceptedResponseKey) !== null)
+    return;
+  await storageConditionalBatch(internals.storage, [{ key: acceptedResponseKey, expectedValue: null }], [{ type: "put", key: acceptedResponseKey, value: acceptedResponse }]);
+}
+export function trackWaiterKey(reverseIndex, workflowId, waiterKey) {
+  let keys = reverseIndex.get(workflowId);
+  if (!keys) {
+    reverseIndex.set(workflowId, waiterKey);
+    return;
+  }
+  if (typeof keys === "string") {
+    if (keys === waiterKey)
+      return;
+    reverseIndex.set(workflowId, new Set([keys, waiterKey]));
+    return;
+  }
+  keys.add(waiterKey);
+}
+export function untrackWaiterKey(reverseIndex, workflowId, waiterKey) {
+  const keys = reverseIndex.get(workflowId);
+  if (!keys)
+    return;
+  if (typeof keys === "string") {
+    if (keys === waiterKey)
+      reverseIndex.delete(workflowId);
+    return;
+  }
+  keys.delete(waiterKey);
+  if (keys.size === 0) {
+    reverseIndex.delete(workflowId);
+    return;
+  }
+  if (keys.size === 1) {
+    const [remainingWaiterKey] = keys;
+    if (remainingWaiterKey !== void 0)
+      reverseIndex.set(workflowId, remainingWaiterKey);
+  }
+}

package/dist/core/engine/speculative-execution-state.d.ts

@@ -0,0 +1,8 @@
+export declare class SpeculativeExecutionState {
+    #private;
+    constructor();
+    recordVerification(verification: Promise<void>): void;
+    recordCompensation(compensation: () => Promise<void>): void;
+    drainVerifications(): Promise<void>;
+    rollback(): Promise<void>;
+}

package/dist/core/engine/speculative-execution-state.js

@@ -0,0 +1,26 @@
+export class SpeculativeExecutionState {
+  #verifications;
+  #compensations;
+  constructor() {
+    this.#verifications = [];
+    this.#compensations = [];
+  }
+  recordVerification(verification) {
+    this.#verifications.push(verification.then(() => ({ failed: !1 }), (error) => ({ failed: !0, error })));
+  }
+  recordCompensation(compensation) {
+    this.#compensations.push(compensation);
+  }
+  async drainVerifications() {
+    const failure = (await Promise.all(this.#verifications)).find((outcome) => outcome.failed);
+    if (failure)
+      throw failure.error;
+  }
+  async rollback() {
+    for (let index = this.#compensations.length - 1;index >= 0; index--)
+      try {
+        await this.#compensations[index]();
+      } catch {}
+    await Promise.all(this.#verifications);
+  }
+}