@lostgradient/weft 0.11.0 → 0.13.0

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

@@ -21,6 +21,12 @@ import {
   untrackWaiterKey
 } from "./signals.js";
 import { callActivityFunction } from "./state-utilities.js";
+import {
+  parallelTimelineDetails,
+  raceTimelineDetails,
+  recordTimelineBranches,
+  runAllTimelineDetails
+} from "./timeline-coordinator-detail.js";
 export function assertSupportedSignalBranches(operations) {
   const seen = new Set, walk = (subOperations) => {
     for (const subOperation of subOperations)
@@ -74,6 +80,7 @@ export async function processParallelOperation(internals, workflowId, operation,
     await finalizeFulfilledSlots(slots);
     const entry = buildEntryFromSlots("all", slots);
     writePartialEntry(internals, workflowId, operation.step, entry);
+    recordTimelineBranches(internals, workflowId, parallelTimelineDetails(operation.operations, slots));
     if (hasFirstError)
       throw firstError;
     return valuesFromSlots(slots);
@@ -111,8 +118,22 @@ export async function processRaceOperation(internals, workflowId, operation, cal
   return callbacks.runOperationWithResult(workflowId, operation, async () => {
     assertSupportedSignalBranches(operation.operations);
     assertValidRaceBranchNames(operation);
-    const winner = await executeRaceSubOperations(internals, workflowId, operation.operations, (subOperation, signal) => callbacks.executeSubOperation(workflowId, subOperation, signal), void 0, (winnerIndex, value) => wrapRaceWinner(operation, winnerIndex, value));
-    return finalizeAndUnwrap(winner);
+    let winnerIndex, winnerError;
+    try {
+      const winner = await executeRaceSubOperations(internals, workflowId, operation.operations, (subOperation, signal) => callbacks.executeSubOperation(workflowId, subOperation, signal), void 0, (selectedIndex, value) => wrapRaceWinner(operation, selectedIndex, value), (selectedIndex, error) => {
+        winnerIndex = selectedIndex;
+        winnerError = error;
+      });
+      try {
+        return await finalizeAndUnwrap(winner);
+      } catch (error) {
+        winnerError = error;
+        throw error;
+      }
+    } finally {
+      if (winnerIndex !== void 0)
+        recordTimelineBranches(internals, workflowId, raceTimelineDetails(operation.operations, winnerIndex, operation.branchNames, winnerError));
+    }
   });
 }
 export function assertValidRaceBranchNames(operation) {
@@ -123,21 +144,46 @@ export function wrapRaceWinner(operation, winnerIndex, value) {
   const key = operation.branchNames?.[winnerIndex];
   return key === void 0 ? value : createKeyedRaceResultEnvelope(key, value);
 }
-export async function executeRaceSubOperations(internals, workflowId, operations, execute, parentSignal, wrapWinner) {
+function createRaceWinnerObservers(wrapWinner, observeWinner) {
+  const observers = {};
+  if (wrapWinner !== void 0)
+    observers.wrapWinner = wrapWinner;
+  if (observeWinner !== void 0)
+    observers.observeWinner = observeWinner;
+  return observers;
+}
+async function settleRaceBranch(operation, index, signal, execute) {
+  try {
+    return { index, status: "fulfilled", value: await execute(operation, signal) };
+  } catch (error) {
+    return { error, index, status: "rejected" };
+  }
+}
+function resolveRaceSettlement(settlement, observers) {
+  if (settlement.status === "rejected") {
+    observers.observeWinner?.(settlement.index, settlement.error);
+    throw settlement.error;
+  }
+  observers.observeWinner?.(settlement.index);
+  return observers.wrapWinner === void 0 ? settlement.value : observers.wrapWinner(settlement.index, settlement.value);
+}
+async function executeBufferedRaceWinner(bufferedSignal, signal, execute, observers) {
+  const settlement = await settleRaceBranch(bufferedSignal.operation, bufferedSignal.index, signal, execute);
+  return resolveRaceSettlement(settlement, observers);
+}
+export async function executeRaceSubOperations(internals, workflowId, operations, execute, parentSignal, wrapWinner, observeWinner) {
   parentSignal?.throwIfAborted();
-  const controller = new AbortController, abortFromParent = () => controller.abort(parentSignal?.reason);
+  const controller = new AbortController, abortFromParent = () => controller.abort(parentSignal?.reason), observers = createRaceWinnerObservers(wrapWinner, observeWinner);
   parentSignal?.addEventListener("abort", abortFromParent, { once: !0 });
   try {
     const bufferedSignal = await findBufferedSignalDrainBranch(internals, workflowId, operations);
     parentSignal?.throwIfAborted();
-    if (bufferedSignal !== void 0) {
-      const value = await execute(bufferedSignal.operation, controller.signal);
-      return wrapWinner === void 0 ? value : wrapWinner(bufferedSignal.index, value);
-    }
-    const subOperations = operations.map((operation, index) => execute(operation, controller.signal).then((value) => ({ index, value })));
+    if (bufferedSignal !== void 0)
+      return await executeBufferedRaceWinner(bufferedSignal, controller.signal, execute, observers);
+    const subOperations = operations.map((operation, index) => settleRaceBranch(operation, index, controller.signal, execute));
     Promise.allSettled(subOperations);
     const winner = await Promise.race(subOperations);
-    return wrapWinner === void 0 ? winner.value : wrapWinner(winner.index, winner.value);
+    return resolveRaceSettlement(winner, observers);
   } finally {
     parentSignal?.removeEventListener("abort", abortFromParent);
     controller.abort();
@@ -156,6 +202,7 @@ async function findBufferedSignalDrainBranch(internals, workflowId, operations)
 export async function processRunAllOperation(internals, workflowId, operation, callbacks) {
   return callbacks.runOperationWithResult(workflowId, operation, async () => {
     const branchNames = Object.keys(operation.branches), operationIds = branchNames.map((name) => `run-all:${operation.step}:${name}`), resumedSlots = extractResumedSlots(operation.resumedCacheEntry), resumedSlotsByName = mapResumedSlotsByName(resumedSlots, branchNames), branchesToRun = filterBranchesToRun(operation.branches, branchNames, resumedSlotsByName), { outcomes, hasFirstError, firstError } = await executeRunAllBranchesSettled(branchesToRun, (fn, input) => callActivityFunction(fn, input)), slots = mergeRunAllSlots(branchNames, operationIds, resumedSlotsByName, outcomes), entry = buildEntryFromSlots("run-all", slots, branchNames), partialEntryWritten = writePartialEntry(internals, workflowId, operation.step, entry);
+    recordTimelineBranches(internals, workflowId, runAllTimelineDetails(branchNames, slots, operation.branches));
     if (hasFirstError) {
       assertPartialFailurePersistenceSupported(partialEntryWritten, slots, "ctx.runAll", "worker execution mode");
       throw firstError;

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

@@ -12,5 +12,5 @@ export type SpeculateOperationCallbacks = {
 };
 export declare function processSpeculateOperation(internals: EngineInternals, workflowId: string, operation: SpeculateOperation, callbacks: SpeculateOperationCallbacks): Promise<void>;
 export declare function executeSpeculativeBranch(internals: EngineInternals, workflowId: string, operation: SpeculateOperation, callbacks: Pick<SpeculateOperationCallbacks, 'executeSubOperation'>): Promise<unknown>;
-export declare function driveSpeculativeGenerator(workflowId: string, generator: SpeculativeOperationGenerator, speculativeState: SpeculativeExecutionState, callbacks: Pick<SpeculateOperationCallbacks, 'executeSubOperation'>): Promise<unknown>;
+export declare function driveSpeculativeGenerator(workflowId: string, generator: SpeculativeOperationGenerator, speculativeState: SpeculativeExecutionState, callbacks: Pick<SpeculateOperationCallbacks, 'executeSubOperation'>, observeChild?: (operation: ContextOperationRequest, index: number, error?: unknown) => void): Promise<unknown>;
 export {};

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

@@ -1,6 +1,10 @@
 import { finalizeAndUnwrap } from "./deferred-consume-envelope.js";
 import { assertSupportedSignalBranches } from "./operations-coordination.js";
 import { SpeculativeExecutionState } from "./speculative-execution-state.js";
+import {
+  operationTimelineDetail,
+  recordTimelineSpeculation
+} from "./timeline-coordinator-detail.js";
 export async function processSpeculateOperation(internals, workflowId, operation, callbacks) {
   return callbacks.runOperationWithResult(workflowId, operation, () => executeSpeculativeBranch(internals, workflowId, operation, callbacks));
 }
@@ -11,32 +15,42 @@ export async function executeSpeculativeBranch(internals, workflowId, operation,
   const parentContext = inlineStrategy.getContext(workflowId);
   if (!parentContext)
     throw Error(`No active inline context for workflow "${workflowId}"`);
-  const speculativeContext = parentContext.createSpeculativeChild(), speculativeState = new SpeculativeExecutionState, generator = createSpeculativeOperationGenerator(operation, speculativeContext);
+  const speculativeContext = parentContext.createSpeculativeChild(), speculativeState = new SpeculativeExecutionState, generator = createSpeculativeOperationGenerator(operation, speculativeContext), children = [];
   try {
-    const result = await driveSpeculativeGenerator(workflowId, generator, speculativeState, callbacks);
+    const result = await driveSpeculativeGenerator(workflowId, generator, speculativeState, callbacks, (child, index, error) => {
+      children.push(operationTimelineDetail(child, index, error === void 0 ? "fulfilled" : "rejected", error === void 0 ? {} : { error }));
+    });
     await speculativeState.drainVerifications();
     parentContext.commitSpeculativeChild(speculativeContext);
+    recordTimelineSpeculation(internals, workflowId, children, "committed");
     return result;
   } catch (error) {
-    await speculativeState.rollback();
+    try {
+      await speculativeState.rollback();
+    } finally {
+      recordTimelineSpeculation(internals, workflowId, children, "rolled-back");
+    }
     throw error;
   }
 }
 function createSpeculativeOperationGenerator(operation, speculativeContext) {
   return operation.execute(speculativeContext);
 }
-export async function driveSpeculativeGenerator(workflowId, generator, speculativeState, callbacks) {
+export async function driveSpeculativeGenerator(workflowId, generator, speculativeState, callbacks, observeChild) {
+  let childIndex = 0;
   const advance = async (lastResult, errorToThrow) => {
     const iterationResult = errorToThrow === void 0 ? await generator.next(lastResult) : await generator.throw(errorToThrow);
     if (iterationResult.done)
       return iterationResult.value;
-    const nextOperation = iterationResult.value;
+    const nextOperation = iterationResult.value, currentChildIndex = childIndex++;
     try {
       if (nextOperation.type === "race" || nextOperation.type === "parallel")
         assertSupportedSignalBranches(nextOperation.operations);
       const nextResult = await callbacks.executeSubOperation(workflowId, nextOperation, void 0, speculativeState), finalizedResult = await finalizeAndUnwrap(nextResult);
+      observeChild?.(nextOperation, currentChildIndex);
       return advance(finalizedResult, void 0);
     } catch (error) {
+      observeChild?.(nextOperation, currentChildIndex, error);
       return advance(lastResult, error instanceof Error ? error : Error(String(error)));
     }
   };

package/dist/core/engine/registration.js

@@ -59,8 +59,22 @@ function applyOptionalRegistrationFields(entry, registration) {
 function buildRegistrationEntry(name, registration) {
   const entry = buildBaseRegistrationEntry(name, registration);
   applyOptionalRegistrationFields(entry, registration);
+  if (isBuilderWorkflowDefinition(registration)) {
+    entry.signals = normalizeMessageDefinitions(name, "signal", registration.signals);
+    entry.updates = normalizeMessageDefinitions(name, "update", registration.updates);
+    entry.queries = normalizeMessageDefinitions(name, "query", registration.queries);
+  }
   return entry;
 }
+function normalizeMessageDefinitions(workflowType, messageKind, definitions) {
+  const normalized = Object.create(null), sortedDefinitions = Object.values(definitions).toSorted((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+  for (const definition of sortedDefinitions) {
+    if (Object.hasOwn(normalized, definition.name))
+      throw Error(`Duplicate ${messageKind} runtime name "${definition.name}" in workflow "${workflowType}"`);
+    normalized[definition.name] = definition;
+  }
+  return normalized;
+}
 function commitWorkflowDefinition(internals, definition, callbacks) {
   const name = definition.name;
   validateWorkflowOrActivityName(name, "workflow");

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

@@ -1,4 +1,4 @@
-import type { ScheduleSpec, ScheduleSummary } from '../types.ts';
+import type { ScheduleSpec, ScheduleSummary, ScheduleUpdateOptions } from '../types.ts';
 /**
  * Narrow engine view a {@link ScheduleHandle} delegates to. The full
  * {@link Engine} implements it; the handle only depends on these schedule
@@ -8,13 +8,13 @@ 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>;
+    updateSchedule(scheduleId: string, newSpec: string | ScheduleSpec, options?: ScheduleUpdateOptions): 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.update(spec, options?)` to manage the schedule lifecycle.
  * `handle.describe()` returns the current {@link ScheduleSummary}.
  *
  * @example
@@ -40,6 +40,6 @@ export declare class ScheduleHandle {
     pause(): Promise<void>;
     resume(): Promise<void>;
     cancel(): Promise<void>;
-    update(newSpec: string | ScheduleSpec): Promise<void>;
+    update(newSpec: string | ScheduleSpec, options?: ScheduleUpdateOptions): Promise<void>;
     describe(): Promise<ScheduleSummary>;
 }

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

@@ -14,8 +14,8 @@ export class ScheduleHandle {
   async cancel() {
     await this.#engine.cancelSchedule(this.id);
   }
-  async update(newSpec) {
-    await this.#engine.updateSchedule(this.id, newSpec);
+  async update(newSpec, options) {
+    await this.#engine.updateSchedule(this.id, newSpec, options);
   }
   async describe() {
     const schedule = await this.#engine.getSchedule(this.id);

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

@@ -0,0 +1,11 @@
+import type { ScheduleState } from '../types.ts';
+import type { EngineInternals } from './internals.ts';
+import type { ScheduledRunStartOptions } from './schedule-run.ts';
+type ScheduleOverlapCallbacks = {
+    cancelWorkflow: (workflowId: string) => Promise<void>;
+    getWorkflowResult: (workflowId: string) => Promise<unknown>;
+    startScheduledRun: (state: ScheduleState, options?: ScheduledRunStartOptions) => Promise<string>;
+};
+export declare function applyBlockedScheduleOccurrence(internals: EngineInternals, state: ScheduleState, hasActiveWorkflow: boolean, callbacks: ScheduleOverlapCallbacks, occurrence?: number): Promise<ScheduleState>;
+export declare function drainQueuedScheduleRun(state: ScheduleState, callbacks: Pick<ScheduleOverlapCallbacks, 'startScheduledRun'>, completedWorkflowId?: string): Promise<ScheduleState>;
+export {};

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

@@ -0,0 +1,50 @@
+import { clearScheduleCurrentWorkflow } from "./state-utilities.js";
+export async function applyBlockedScheduleOccurrence(internals, state, hasActiveWorkflow, callbacks, occurrence) {
+  if (!hasActiveWorkflow)
+    return startScheduleRunInOccupiedSlot(state, callbacks, occurrence);
+  if (state.overlap === "cancel-running") {
+    if (state.currentWorkflowId) {
+      callbacks.getWorkflowResult(state.currentWorkflowId).catch(() => {});
+      await callbacks.cancelWorkflow(state.currentWorkflowId);
+    }
+    return startScheduleRunInOccupiedSlot(clearScheduleCurrentWorkflow(state), callbacks, occurrence);
+  }
+  if (state.overlap === "queue")
+    return {
+      ...state,
+      queuedRuns: [
+        ...state.queuedRuns,
+        {
+          workflowId: crypto.randomUUID(),
+          queuedAt: internals.options.getNow(),
+          ...occurrence !== void 0 && { occurrence }
+        }
+      ]
+    };
+  return state;
+}
+async function startScheduleRunInOccupiedSlot(state, callbacks, occurrence) {
+  const workflowId = crypto.randomUUID(), stateAfterStart = { ...state, currentWorkflowId: workflowId };
+  await callbacks.startScheduledRun(state, {
+    workflowId,
+    ...occurrence !== void 0 && { occurrence }
+  });
+  return stateAfterStart;
+}
+export async function drainQueuedScheduleRun(state, callbacks, completedWorkflowId) {
+  const [queuedRun, ...remainingQueuedRuns] = state.queuedRuns;
+  if (queuedRun === void 0)
+    return state;
+  const stateAfterStart = {
+    ...state,
+    currentWorkflowId: queuedRun.workflowId,
+    queuedRuns: remainingQueuedRuns
+  };
+  await callbacks.startScheduledRun(state, {
+    workflowId: queuedRun.workflowId,
+    ...queuedRun.occurrence !== void 0 && { occurrence: queuedRun.occurrence },
+    scheduleStateAfterStart: stateAfterStart,
+    ...completedWorkflowId !== void 0 && { completedWorkflowId }
+  });
+  return stateAfterStart;
+}

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

@@ -1,6 +1,15 @@
 import type { ScheduleState } from '../types.ts';
 import type { EngineInternals } from './internals.ts';
 import type { ScheduleCallbacks } from './schedules.ts';
+export type ScheduledRunStartOptions = {
+    occurrence?: number;
+    /** Reserved queue identity. A fresh id is minted when omitted. */
+    workflowId?: string;
+    /** Schedule state committed atomically with the workflow start. */
+    scheduleStateAfterStart?: ScheduleState;
+    /** Prior terminal run whose transient schedule metadata is now settled. */
+    completedWorkflowId?: string;
+};
 /**
  * Launch one scheduled occurrence's workflow run and emit `schedule:fired`.
  *
@@ -11,7 +20,6 @@ import type { ScheduleCallbacks } from './schedules.ts';
  * 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.
+ * timer loop or retained on its durable queue entry until drain.
  */
-export declare function startScheduledRun(internals: EngineInternals, state: ScheduleState, callbacks: Pick<ScheduleCallbacks, 'startWorkflow' | 'failWorkflow' | 'handleCleanupError'>, occurrence?: number): Promise<string>;
+export declare function startScheduledRun(internals: EngineInternals, state: ScheduleState, callbacks: Pick<ScheduleCallbacks, 'startWorkflow' | 'failWorkflow' | 'handleCleanupError'>, options?: ScheduledRunStartOptions): Promise<string>;

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

@@ -1,21 +1,44 @@
 import { KEYS } from "../../storage/interface.js";
+import { encode } from "../codec.js";
 import { ScheduleFiredEvent } from "../events.js";
 import { unavailableServicesError } from "./lifecycle/recovered-services.js";
 import { EMPTY_STORAGE_VALUE } from "./lifecycle/shared.js";
 import { encodeScheduleRunMetadata } from "./schedule-run-metadata.js";
-export async function startScheduledRun(internals, state, callbacks, occurrence) {
-  const workflowId = crypto.randomUUID(), scheduleRunOperations = [
+export async function startScheduledRun(internals, state, callbacks, options = {}) {
+  const workflowId = options.workflowId ?? crypto.randomUUID(), occurrence = options.occurrence, metadata = encodeScheduleRunMetadata(state.id, occurrence), scheduleRunOperations = [
     {
       type: "put",
       key: KEYS.scheduleRun(workflowId),
-      value: encodeScheduleRunMetadata(state.id, occurrence)
+      value: metadata
+    },
+    {
+      type: "put",
+      key: KEYS.scheduleRunLink(workflowId),
+      value: metadata
+    },
+    {
+      type: "put",
+      key: KEYS.scheduleRunBySchedule(state.id, workflowId),
+      value: EMPTY_STORAGE_VALUE
     },
     {
       type: "put",
       key: KEYS.terminalCleanupNeeded(workflowId),
       value: EMPTY_STORAGE_VALUE
     }
-  ], resolution = await resolveScheduledRunServices(internals, workflowId, state, occurrence);
+  ];
+  if (options.scheduleStateAfterStart !== void 0)
+    scheduleRunOperations.push({
+      type: "put",
+      key: KEYS.schedule(options.scheduleStateAfterStart.id),
+      value: encode(options.scheduleStateAfterStart)
+    });
+  if (options.completedWorkflowId !== void 0)
+    scheduleRunOperations.push({
+      type: "delete",
+      key: KEYS.scheduleRun(options.completedWorkflowId)
+    });
+  const resolution = await resolveScheduledRunServices(internals, workflowId, state, occurrence);
   if (resolution !== null) {
     scheduleRunOperations.push({
       type: "put",

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

@@ -1,7 +1,11 @@
 import { ScheduleMissedFireEvent } from "../events/schedule-events.js";
 import { resolveEffectiveScheduleFireAt } from "./schedule-jitter.js";
 import { collectDueScheduleOccurrences, getNextScheduleOccurrence } from "./schedule-occurrence.js";
-import { loadScheduleState, writeScheduleState } from "./storage-io.js";
+import {
+  loadScheduleState,
+  runSerializedScheduleStateOperation,
+  writeScheduleState
+} from "./storage-io.js";
 const SCHEDULE_LATE_GRACE_MILLISECONDS = 1000, MAX_SCHEDULE_BACKFILL_OCCURRENCES_PER_TICK = 256, MAX_MISSED_FIRE_COUNT_PER_TICK = MAX_SCHEDULE_BACKFILL_OCCURRENCES_PER_TICK;
 
 class ScheduleStatePersistenceError extends Error {
@@ -12,6 +16,11 @@ class ScheduleStatePersistenceError extends Error {
   }
 }
 export async function handleScheduleTimer(internals, entry, callbacks) {
+  await runSerializedScheduleStateOperation(internals, entry.workflowId, async () => {
+    await handleSerializedScheduleTimer(internals, entry, callbacks);
+  });
+}
+async function handleSerializedScheduleTimer(internals, entry, callbacks) {
   if (internals.deposed)
     return;
   const state = await loadScheduleState(internals, entry.workflowId);

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

@@ -1,7 +1,8 @@
 import type { BatchOperation } from '../../storage/interface.ts';
-import type { PaginatedResult, ScheduleFilter, ScheduleOptions, ScheduleSpec, ScheduleState, ScheduleSummary, WorkflowState } from '../types.ts';
+import type { PaginatedResult, ScheduleFilter, ScheduleOptions, ScheduleSpec, ScheduleState, ScheduleSummary, ScheduleUpdateOptions, WorkflowState } from '../types.ts';
 import type { EngineInternals } from './internals.ts';
 import { ScheduleHandle } from './schedule-handle.ts';
+import type { ScheduledRunStartOptions } from './schedule-run.ts';
 export { startScheduledRun } from './schedule-run.ts';
 export { handleScheduleTimer } from './schedule-timer.ts';
 export type RefreshedScheduleState = {
@@ -16,7 +17,7 @@ export type ScheduleCallbacks = {
     cancelWorkflow: (workflowId: string) => Promise<void>;
     getWorkflowResult: (workflowId: string) => Promise<unknown>;
     refreshScheduledWorkflowState: (state: ScheduleState) => Promise<RefreshedScheduleState>;
-    startScheduledRun: (state: ScheduleState, occurrence?: number) => Promise<string>;
+    startScheduledRun: (state: ScheduleState, options?: ScheduledRunStartOptions) => Promise<string>;
     applyScheduleOccurrence: (state: ScheduleState, occurrence?: number) => Promise<ScheduleState>;
     settleBackfillScheduleState: (state: ScheduleState) => Promise<ScheduleState>;
     flushQueuedInlineWorkflowStartsDirectly: () => Promise<void>;
@@ -30,8 +31,8 @@ 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 updateSchedule(internals: EngineInternals, scheduleId: string, newSpec: string | ScheduleSpec, options?: ScheduleUpdateOptions): Promise<void>;
 export declare function refreshScheduledWorkflowState(internals: EngineInternals, state: ScheduleState, callbacks: Pick<ScheduleCallbacks, 'loadWorkflowState'>): Promise<RefreshedScheduleState>;
-export declare function applyScheduleOccurrence(_internals: EngineInternals, state: ScheduleState, callbacks: ScheduleCallbacks, occurrence?: number): Promise<ScheduleState>;
+export declare function applyScheduleOccurrence(internals: EngineInternals, state: ScheduleState, callbacks: ScheduleCallbacks, occurrence?: number): 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

@@ -1,9 +1,11 @@
 import { KEYS } from "../../storage/interface.js";
 import { decode } from "../codec.js";
 import { WorkflowNotRegisteredError } from "./errors.js";
+import { commitFencedEngineWrite } from "./fenced-write.js";
 import { ScheduleHandle } from "./schedule-handle.js";
 import { resolveEffectiveScheduleFireAt } from "./schedule-jitter.js";
 import { getNextScheduleOccurrence } from "./schedule-occurrence.js";
+import { applyBlockedScheduleOccurrence, drainQueuedScheduleRun } from "./schedule-overlap.js";
 import { decodeScheduleRunMetadata } from "./schedule-run-metadata.js";
 import {
   clearScheduleCurrentWorkflow,
@@ -11,14 +13,20 @@ import {
   matchesScheduleFilter,
   paginateScheduleSummaries
 } from "./state-utilities.js";
-import { loadScheduleState, requireScheduleState, writeScheduleState } from "./storage-io.js";
+import {
+  loadScheduleState,
+  requireScheduleState,
+  runSerializedScheduleStateOperation,
+  writeScheduleState
+} from "./storage-io.js";
 import {
   coerceScheduleId,
   decodeScheduleState,
   isValidScheduleIdentifier,
   normalizeScheduleFilter,
   normalizeScheduleOptions,
-  normalizeScheduleSpec
+  normalizeScheduleSpec,
+  normalizeScheduleUpdateOptions
 } from "./validation/schedule.js";
 export { startScheduledRun } from "./schedule-run.js";
 export { handleScheduleTimer } from "./schedule-timer.js";
@@ -48,7 +56,7 @@ export async function schedule(internals, type, input, spec, options) {
       updatedAt: now,
       nextFireAt: getNextScheduleOccurrence({ ...cadenceFields, createdAt: now }, now),
       missedFireCount: 0,
-      queuedRuns: 0
+      queuedRuns: []
     };
     await writeScheduleState(internals, state);
     return new ScheduleHandle(scheduleId, internals.engine);
@@ -64,8 +72,7 @@ export async function listSchedules(internals, filter) {
     const state = decodeScheduleState(value);
     if (!state || !matchesScheduleFilter(state, normalizedFilter))
       continue;
-    const { input: _input, ...summary } = state;
-    items.push(summary);
+    items.push(toScheduleSummary(state));
   }
   return paginateScheduleSummaries(items, normalizedFilter);
 }
@@ -93,7 +100,7 @@ async function hasCurrentScheduleTimer(internals, state) {
 }
 export function toScheduleSummary(state) {
   const { input: _input, ...summary } = state;
-  return summary;
+  return { ...summary, queuedRuns: summary.queuedRuns.map((queuedRun) => ({ ...queuedRun })) };
 }
 export async function pauseSchedule(internals, scheduleId) {
   const normalizedScheduleId = coerceScheduleId(scheduleId, "scheduleId"), state = await requireScheduleState(internals, normalizedScheduleId);
@@ -105,7 +112,7 @@ export async function pauseSchedule(internals, scheduleId) {
     status: "paused",
     updatedAt: now,
     nextFireAt: getNextScheduleOccurrence(state, now),
-    queuedRuns: 0
+    queuedRuns: []
   };
   await writeScheduleState(internals, updatedState, { includeTimer: !1 });
 }
@@ -132,23 +139,30 @@ export async function cancelSchedule(internals, scheduleId) {
     status: "cancelled",
     updatedAt: internals.options.getNow(),
     nextFireAt: null,
-    queuedRuns: 0
+    queuedRuns: []
   };
   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), 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 updateSchedule(internals, scheduleId, newSpec, options) {
+  const normalizedScheduleId = coerceScheduleId(scheduleId, "scheduleId"), normalizedSpec = normalizeScheduleSpec(newSpec), normalizedOptions = normalizeScheduleUpdateOptions(options);
+  await runSerializedScheduleStateOperation(internals, normalizedScheduleId, async () => {
+    const state = await requireScheduleState(internals, normalizedScheduleId), 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,
+      ...normalizedOptions,
+      ...cadenceFields,
+      ...anchorFields,
+      updatedAt: now,
+      nextFireAt: state.status === "cancelled" ? null : getNextScheduleOccurrence({ ...cadenceFields, createdAt: now }, now)
+    };
+    await writeScheduleState(internals, updatedState, {
+      includeTimer: state.status === "active",
+      replaceTimerFrom: state
+    });
+  });
 }
 function scheduledRunOccupiesSlot(currentWorkflowState) {
   const status = currentWorkflowState?.status;
@@ -169,31 +183,20 @@ export async function refreshScheduledWorkflowState(internals, state, callbacks)
 function hasActiveScheduledWorkflow(currentWorkflowState) {
   return scheduledRunOccupiesSlot(currentWorkflowState);
 }
-async function applyBlockedScheduleOccurrence(state, hasActiveWorkflow, callbacks, occurrence) {
-  if (!hasActiveWorkflow)
-    return { ...state, currentWorkflowId: await callbacks.startScheduledRun(state, occurrence) };
-  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, occurrence)
-    };
+export async function applyScheduleOccurrence(internals, state, callbacks, occurrence) {
+  const { state: refreshedState, currentWorkflowState } = await callbacks.refreshScheduledWorkflowState(state);
+  let stateForOccurrence = refreshedState, hasActiveWorkflow = hasActiveScheduledWorkflow(currentWorkflowState);
+  if (!hasActiveWorkflow && stateForOccurrence.queuedRuns.length > 0) {
+    stateForOccurrence = await drainQueuedScheduleRun(stateForOccurrence, callbacks);
+    hasActiveWorkflow = !0;
   }
-  if (state.overlap === "queue")
-    return { ...state, queuedRuns: state.queuedRuns + 1 };
-  return state;
-}
-export async function applyScheduleOccurrence(_internals, state, callbacks, occurrence) {
-  const { state: refreshedState, currentWorkflowState } = await callbacks.refreshScheduledWorkflowState(state), hasActiveWorkflow = hasActiveScheduledWorkflow(currentWorkflowState);
-  if (refreshedState.overlap === "allow") {
-    await callbacks.startScheduledRun(refreshedState, occurrence);
-    return refreshedState;
+  if (stateForOccurrence.overlap === "allow") {
+    await callbacks.startScheduledRun(stateForOccurrence, {
+      ...occurrence !== void 0 && { occurrence }
+    });
+    return stateForOccurrence;
   }
-  return applyBlockedScheduleOccurrence(refreshedState, hasActiveWorkflow, callbacks, occurrence);
+  return applyBlockedScheduleOccurrence(internals, stateForOccurrence, hasActiveWorkflow, callbacks, occurrence);
 }
 export async function settleBackfillScheduleState(internals, state, callbacks) {
   if (!state.currentWorkflowId)
@@ -208,26 +211,29 @@ export async function handleScheduledWorkflowTerminal(internals, workflowId, cal
   const scheduleRunBytes = await internals.storage.get(KEYS.scheduleRun(workflowId));
   if (!scheduleRunBytes)
     return;
-  await internals.storage.delete(KEYS.scheduleRun(workflowId));
   const metadata = decodeScheduleRunMetadata(scheduleRunBytes);
-  if (metadata === null || !isValidScheduleIdentifier(metadata.id))
+  if (metadata === null || !isValidScheduleIdentifier(metadata.id)) {
+    await deleteTransientScheduleRunMetadata(internals, workflowId);
     return;
+  }
   const scheduleId = metadata.id, state = await loadScheduleState(internals, scheduleId);
-  if (!state || state.currentWorkflowId !== workflowId)
+  if (!state || state.currentWorkflowId !== workflowId) {
+    await deleteTransientScheduleRunMetadata(internals, 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 });
+  if (clearedState.status === "active" && clearedState.queuedRuns.length > 0) {
+    await drainQueuedScheduleRun({ ...clearedState, updatedAt: now }, callbacks, workflowId);
     return;
   }
-  await writeScheduleState(internals, clearedState, { includeTimer: !1 });
+  await writeScheduleState(internals, clearedState, {
+    includeTimer: !1,
+    additionalOperations: [{ type: "delete", key: KEYS.scheduleRun(workflowId) }]
+  });
+}
+async function deleteTransientScheduleRunMetadata(internals, workflowId) {
+  await commitFencedEngineWrite(internals, [{ type: "delete", key: KEYS.scheduleRun(workflowId) }], [], () => Error(`Schedule-run cleanup for workflow "${workflowId}" lost its precondition.`));
 }