@lostgradient/weft 0.12.0 → 0.13.0

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.`));
 }

package/dist/core/engine/state-utilities.js

@@ -223,7 +223,7 @@ function matchesListFilterStatus(state, filter) {
   return (Array.isArray(filter.status) ? filter.status : [filter.status]).includes(state.status);
 }
 function matchesListFilterIdentity(state, filter) {
-  return matchesListFilterStatus(state, filter) && (filter.type === void 0 || state.type === filter.type) && (filter.idPrefix === void 0 || state.id.startsWith(filter.idPrefix));
+  return matchesListFilterStatus(state, filter) && (filter.type === void 0 || state.type === filter.type) && (filter.parentWorkflowId === void 0 || state.parentWorkflowId === filter.parentWorkflowId) && (filter.parentWorkflowExecutionToken === void 0 || state.parentWorkflowExecutionToken === filter.parentWorkflowExecutionToken) && (filter.idPrefix === void 0 || state.id.startsWith(filter.idPrefix));
 }
 function matchesListFilterTimeRanges(state, filter) {
   if (filter.createdAt !== void 0 && !timestampInRange(state.createdAt, filter.createdAt))

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

@@ -3,6 +3,16 @@ import type { ScheduleState, WorkflowState } from '../types.ts';
 import type { EngineInternals } from './internals.ts';
 /** Run a workflow-state write after any earlier write for that workflow has settled. */
 export declare function runSerializedWorkflowStateWrite<TResult>(internals: EngineInternals, workflowId: string, writeOperation: () => Promise<TResult>): Promise<TResult>;
+/**
+ * Serialize a schedule read-modify-write operation with its timer callback.
+ *
+ * Unlike workflow-state write serialization, a failed predecessor is propagated
+ * to callers that were already queued behind it. In particular, an update that
+ * arrives while a scanned timer callback is rearming must not delete the fired
+ * timer after that callback fails; rejecting the queued update leaves the durable
+ * timer available for the scheduler (or a lease successor) to retry.
+ */
+export declare function runSerializedScheduleStateOperation<TResult>(internals: EngineInternals, scheduleId: string, operation: () => Promise<TResult>): Promise<TResult>;
 /** Load and decode persisted workflow state by workflow ID. */
 export declare function loadWorkflowState(internals: EngineInternals, workflowId: string): Promise<WorkflowState | null>;
 /** Load a terminal workflow result or throw the persisted terminal error. */
@@ -29,6 +39,8 @@ export declare function requireScheduleState(internals: EngineInternals, schedul
 /** Persist schedule state and optionally write the next schedule timer. */
 export declare function writeScheduleState(internals: EngineInternals, state: ScheduleState, options?: {
     includeTimer?: boolean;
+    replaceTimerFrom?: ScheduleState;
+    additionalOperations?: BatchOperation[];
 }): Promise<void>;
 /** Load persisted workflow start headers by workflow ID. */
 export declare function loadWorkflowStartHeaders(internals: EngineInternals, workflowId: string): Promise<Map<string, string> | undefined>;

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

@@ -30,6 +30,21 @@ export async function runSerializedWorkflowStateWrite(internals, workflowId, wri
       internals.workflowStateWriteChains.delete(workflowId);
   }
 }
+export async function runSerializedScheduleStateOperation(internals, scheduleId, operation) {
+  const execution = (internals.scheduleStateOperationChains.get(scheduleId) ?? Promise.resolve()).then(operation), trackedExecution = execution.then(() => {
+    return;
+  });
+  trackedExecution.catch(() => {
+    return;
+  });
+  internals.scheduleStateOperationChains.set(scheduleId, trackedExecution);
+  try {
+    return await execution;
+  } finally {
+    if (internals.scheduleStateOperationChains.get(scheduleId) === trackedExecution)
+      internals.scheduleStateOperationChains.delete(scheduleId);
+  }
+}
 export async function loadWorkflowState(internals, workflowId) {
   const bytes = await internals.storage.get(KEYS.workflow(workflowId));
   if (!bytes)
@@ -80,19 +95,43 @@ export async function requireScheduleState(internals, scheduleId) {
     throw Error(`Schedule "${scheduleId}" not found`);
   return state;
 }
+function buildPreviousScheduleTimerDeleteOperations(previousState) {
+  if (previousState?.status !== "active" || previousState.nextFireAt === null)
+    return [];
+  return [
+    {
+      type: "delete",
+      key: KEYS.scheduleTick(resolveEffectiveScheduleFireAt(previousState, previousState.nextFireAt), previousState.id)
+    }
+  ];
+}
+function buildNextScheduleTimerOperations(state, includeTimer) {
+  if (!includeTimer || state.status !== "active" || state.nextFireAt === null)
+    return [];
+  return buildTimerBatchOperations({
+    id: createScheduleTimerId(state.id),
+    workflowId: state.id,
+    fireAt: resolveEffectiveScheduleFireAt(state, state.nextFireAt),
+    kind: "schedule"
+  });
+}
+function buildScheduleTimerReplacementOperations(state, includeTimer, previousState) {
+  const deleteOperations = buildPreviousScheduleTimerDeleteOperations(previousState), nextTimerOperations = buildNextScheduleTimerOperations(state, includeTimer);
+  if (nextTimerOperations.length > 0)
+    return [...deleteOperations, ...nextTimerOperations];
+  if (previousState === void 0)
+    return deleteOperations;
+  return [
+    ...deleteOperations,
+    { type: "delete", key: `timer-idx:${createScheduleTimerId(state.id)}` }
+  ];
+}
 export async function writeScheduleState(internals, state, options) {
   const operations = [
     { type: "put", key: KEYS.schedule(state.id), value: encode(state) }
-  ];
-  if ((options?.includeTimer ?? state.status === "active") && state.status === "active" && state.nextFireAt !== null) {
-    const effectiveFireAt = resolveEffectiveScheduleFireAt(state, state.nextFireAt);
-    operations.push(...buildTimerBatchOperations({
-      id: createScheduleTimerId(state.id),
-      workflowId: state.id,
-      fireAt: effectiveFireAt,
-      kind: "schedule"
-    }));
-  }
+  ], includeTimer = options?.includeTimer ?? state.status === "active";
+  operations.push(...buildScheduleTimerReplacementOperations(state, includeTimer, options?.replaceTimerFrom));
+  operations.push(...options?.additionalOperations ?? []);
   await commitFencedEngineWrite(internals, operations, [], () => Error(`Schedule state commit for schedule "${state.id}" lost its precondition.`));
 }
 export async function loadWorkflowStartHeaders(internals, workflowId) {

package/dist/core/engine/termination/finalizer-claim.d.ts

@@ -37,11 +37,11 @@ export declare function runningClaimIsStale(internals: EngineInternals, claim: T
 /**
  * Durable audit record written to {@link KEYS.teardownDeadLetter} when a workflow's
  * finalizer permanently fails — the retry horizon was reached, or the recorded resource
- * state vanished so the finalizer can never run. It is the supported operator surface
- * for a leaked external resource: raw storage inspection of the `wf-teardown-deadletter:`
- * key is the contract (in-process teardown events are best-effort and not durable, and
- * the record is excluded from the workflow purge delete-set so it survives after the
- * workflow record is gone).
+ * state vanished so the finalizer can never run. It is the supported durable operator
+ * record for a leaked external resource; {@link Engine.getFinalizerStatus} and the matching
+ * transport operation expose it without relying on best-effort teardown events. The record
+ * is excluded from the workflow purge delete-set so it survives after the workflow record
+ * is gone.
  */
 export interface TeardownDeadLetterRecord {
     /** The workflow type whose finalizer leaked. */
@@ -52,6 +52,8 @@ export interface TeardownDeadLetterRecord {
     attempts: number;
     /** Engine clock when the record was written. */
     deadLetteredAt: number;
+    /** Concrete run identity, present on records written from current workflow state. */
+    workflowExecutionToken?: string;
     /** The decoded `ctx.setFinalizerState` payload, when it was still recoverable. */
     finalizerInput?: unknown;
 }
@@ -107,4 +109,4 @@ export declare function settleOnRunningClaim(internals: EngineInternals, workflo
 export declare function deadLetterTeardown(internals: EngineInternals, workflowId: string, workflowType: string, attempts: number, expectedBytes: Uint8Array, details: {
     lastError: string;
     finalizerInput: unknown;
-}): Promise<boolean>;
+}, workflowExecutionToken?: string): Promise<boolean>;

package/dist/core/engine/termination/finalizer-claim.js

@@ -64,12 +64,13 @@ export async function settleOnRunningClaim(internals, workflowId, runningBytes,
     { key: KEYS.teardownOwed(workflowId), expectedValue: runningBytes }
   ]);
 }
-export async function deadLetterTeardown(internals, workflowId, workflowType, attempts, expectedBytes, details) {
+export async function deadLetterTeardown(internals, workflowId, workflowType, attempts, expectedBytes, details, workflowExecutionToken) {
   const deadLetter = {
     type: workflowType,
     lastError: details.lastError,
     attempts,
     deadLetteredAt: internals.options.getNow(),
+    ...workflowExecutionToken === void 0 ? {} : { workflowExecutionToken },
     ...details.finalizerInput === void 0 ? {} : { finalizerInput: details.finalizerInput }
   };
   return settleOnRunningClaim(internals, workflowId, expectedBytes, [

package/dist/core/engine/termination/finalizer.js

@@ -1,6 +1,7 @@
 import { KEYS } from "../../../storage/interface.js";
 import { decode } from "../../codec.js";
 import { WorkflowTeardownEvent } from "../../events.js";
+import { buildTeardownSuccessOperations } from "../finalizer-status.js";
 import { isTeardownClaim, parseTeardownTimerId } from "../state-utilities.js";
 import { runFinalizerActivity } from "./finalizer-activity.js";
 import {
@@ -21,10 +22,7 @@ export { teardownStaleThresholdMs } from "./finalizer-claim.js";
 const TERMINAL_STATUSES_OWED_TEARDOWN = new Set([
   "cancelled",
   "timed-out"
-]);
-function errorMessage(error) {
-  return error instanceof Error ? error.message : String(error);
-}
+]), errorMessage = (error) => error instanceof Error ? error.message : String(error);
 async function rearmOnLostSettle(internals, workflowId, token) {
   await rearmTeardownTimer(internals, workflowId, token, TEARDOWN_SELF_HEAL_DELAY_MS);
 }
@@ -63,7 +61,7 @@ async function resolveTeardownDrive(internals, workflowId, token, callbacks) {
     return { kind: "rearm", token };
   const finalizerStateBytes = await internals.storage.get(KEYS.finalizerState(workflowId));
   if (finalizerStateBytes === null) {
-    await deadLetterMissingState(internals, workflowId, state.type, claim.attempts, markerBytes, callbacks);
+    await deadLetterMissingState(internals, workflowId, state.type, state.workflowExecutionToken, claim.attempts, markerBytes, callbacks);
     return { kind: "cleared" };
   }
   return {
@@ -71,12 +69,12 @@ async function resolveTeardownDrive(internals, workflowId, token, callbacks) {
     drive: { state, claim, markerBytes, finalizer, finalizerInput: decode(finalizerStateBytes) }
   };
 }
-async function deadLetterMissingState(internals, workflowId, workflowType, attempts, expectedBytes, callbacks) {
+async function deadLetterMissingState(internals, workflowId, workflowType, workflowExecutionToken, attempts, expectedBytes, callbacks) {
   const lastError = "finalizer state missing \u2014 recorded resource cannot be torn down";
   if (await deadLetterTeardown(internals, workflowId, workflowType, attempts, expectedBytes, {
     lastError,
     finalizerInput: void 0
-  }))
+  }, workflowExecutionToken))
     callbacks.dispatchEvent(new WorkflowTeardownEvent(workflowId, workflowType, "dead-lettered", attempts, lastError));
 }
 export async function runWorkflowFinalizer(internals, workflowId, timerId, callbacks) {
@@ -105,7 +103,7 @@ async function driveResolvedTeardown(internals, workflowId, token, drive, callba
   }
   const result = await runFinalizerActivity(finalizer, finalizerInput, attempt, internals.abortController.signal, state.workflowExecutionToken);
   if (result.ok) {
-    await settleTeardownSuccess(internals, workflowId, state.type, token, attempt, runningBytes, callbacks);
+    await settleTeardownSuccess(internals, workflowId, state.type, state.workflowExecutionToken, token, attempt, runningBytes, callbacks);
     return;
   }
   if (result.abortedByShutdown) {
@@ -123,11 +121,9 @@ async function driveResolvedTeardown(internals, workflowId, token, drive, callba
   }
   await settleTeardownFailure(internals, workflowId, state, attempt, token, runningBytes, result.error, callbacks);
 }
-async function settleTeardownSuccess(internals, workflowId, workflowType, token, attempt, runningBytes, callbacks) {
-  if (!await settleOnRunningClaim(internals, workflowId, runningBytes, [
-    { type: "delete", key: KEYS.teardownOwed(workflowId) },
-    { type: "delete", key: KEYS.finalizerState(workflowId) }
-  ])) {
+async function settleTeardownSuccess(internals, workflowId, workflowType, workflowExecutionToken, token, attempt, runningBytes, callbacks) {
+  const operations = buildTeardownSuccessOperations(workflowId, attempt, internals.options.getNow(), workflowExecutionToken);
+  if (!await settleOnRunningClaim(internals, workflowId, runningBytes, operations)) {
     await rearmOnLostSettle(internals, workflowId, token);
     return;
   }
@@ -140,7 +136,7 @@ async function settleTeardownFailure(internals, workflowId, state, attempt, toke
     if (!await deadLetterTeardown(internals, workflowId, state.type, attempt, runningBytes, {
       lastError: message,
       finalizerInput: finalizerStateBytes === null ? void 0 : decode(finalizerStateBytes)
-    })) {
+    }, state.workflowExecutionToken)) {
       await rearmOnLostSettle(internals, workflowId, token);
       return;
     }

package/dist/core/engine/timeline-coordinator-constants.d.ts

@@ -0,0 +1,3 @@
+/** Prevent one fan-out operation from making a timeline record grow without bound. */
+export declare const MAX_TIMELINE_COORDINATOR_DETAILS = 100;
+export declare const MAX_TIMELINE_DETAIL_STRING_LENGTH = 512;

package/dist/core/engine/timeline-coordinator-constants.js

@@ -0,0 +1 @@
+export const MAX_TIMELINE_COORDINATOR_DETAILS = 100, MAX_TIMELINE_DETAIL_STRING_LENGTH = 512;

package/dist/core/engine/timeline-coordinator-detail.d.ts

@@ -0,0 +1,13 @@
+import type { ContextOperationRequest } from '../context.ts';
+import type { ParallelBranchSlot } from '../context/parallel-operations.ts';
+import type { WorkflowTimelineOperationDetail } from '../types.ts';
+import type { EngineInternals } from './internals.ts';
+export declare function operationTimelineDetail(operation: ContextOperationRequest, index: number, outcome: WorkflowTimelineOperationDetail['outcome'], options?: {
+    error?: unknown;
+    key?: string;
+}): WorkflowTimelineOperationDetail;
+export declare function parallelTimelineDetails(operations: readonly ContextOperationRequest[], slots: readonly ParallelBranchSlot[], branchNames?: readonly string[]): WorkflowTimelineOperationDetail[];
+export declare function raceTimelineDetails(operations: readonly ContextOperationRequest[], winnerIndex: number, branchNames?: readonly string[], winnerError?: unknown): WorkflowTimelineOperationDetail[];
+export declare function runAllTimelineDetails(branchNames: readonly string[], slots: readonly ParallelBranchSlot[], branches: Record<string, readonly [Function] | readonly [Function, unknown]>): WorkflowTimelineOperationDetail[];
+export declare function recordTimelineBranches(internals: EngineInternals, workflowId: string, details: readonly WorkflowTimelineOperationDetail[]): void;
+export declare function recordTimelineSpeculation(internals: EngineInternals, workflowId: string, details: readonly WorkflowTimelineOperationDetail[], outcome: 'committed' | 'rolled-back'): void;

package/dist/core/engine/timeline-coordinator-detail.js

@@ -0,0 +1,76 @@
+import { getTimelineOperationLabel, summarizeTimelineValue } from "./state-utilities.js";
+import {
+  MAX_TIMELINE_COORDINATOR_DETAILS,
+  MAX_TIMELINE_DETAIL_STRING_LENGTH
+} from "./timeline-coordinator-constants.js";
+function boundedString(value) {
+  return value.length <= MAX_TIMELINE_DETAIL_STRING_LENGTH ? value : `${value.slice(0, MAX_TIMELINE_DETAIL_STRING_LENGTH - 1)}\u2026`;
+}
+function boundedErrorSummary(error) {
+  return boundedString(summarizeTimelineValue(error));
+}
+export function operationTimelineDetail(operation, index, outcome, options = {}) {
+  return {
+    index,
+    ...options.key === void 0 ? {} : { key: boundedString(options.key) },
+    operationId: boundedString(operation.operationId),
+    operationType: operation.type,
+    operationLabel: boundedString(getTimelineOperationLabel(operation)),
+    outcome,
+    ...options.error === void 0 ? {} : { errorSummary: boundedErrorSummary(options.error) }
+  };
+}
+export function parallelTimelineDetails(operations, slots, branchNames) {
+  return operations.map((operation, index) => {
+    const slot = slots[index];
+    return operationTimelineDetail(operation, index, slot?.status === "fulfilled" ? "fulfilled" : "rejected", {
+      ...branchNames?.[index] === void 0 ? {} : { key: branchNames[index] },
+      ...slot?.status === "rejected" ? { error: slot.reason } : {}
+    });
+  });
+}
+export function raceTimelineDetails(operations, winnerIndex, branchNames, winnerError) {
+  return operations.map((operation, index) => operationTimelineDetail(operation, index, index === winnerIndex ? "won" : "lost", {
+    ...branchNames?.[index] === void 0 ? {} : { key: branchNames[index] },
+    ...index === winnerIndex && winnerError !== void 0 ? { error: winnerError } : {}
+  }));
+}
+export function runAllTimelineDetails(branchNames, slots, branches) {
+  return branchNames.map((key, index) => {
+    const slot = slots[index], branchFunction = branches[key]?.[0];
+    return {
+      index,
+      key: boundedString(key),
+      operationId: boundedString(slot?.operationId ?? `run-all:${String(index)}:${key}`),
+      operationType: "activity",
+      operationLabel: boundedString(branchFunction?.name || key),
+      outcome: slot?.status === "fulfilled" ? "fulfilled" : "rejected",
+      ...slot?.status === "rejected" ? { errorSummary: boundedErrorSummary(slot.reason) } : {}
+    };
+  });
+}
+function boundedDetails(details) {
+  return {
+    details: details.slice(0, MAX_TIMELINE_COORDINATOR_DETAILS),
+    omitted: Math.max(0, details.length - MAX_TIMELINE_COORDINATOR_DETAILS)
+  };
+}
+export function recordTimelineBranches(internals, workflowId, details) {
+  const entry = internals.pendingTimelineEntries?.get(workflowId)?.entry;
+  if (entry === void 0)
+    return;
+  const bounded = boundedDetails(details);
+  entry.branches = bounded.details;
+  if (bounded.omitted > 0)
+    entry.branchesOmitted = bounded.omitted;
+}
+export function recordTimelineSpeculation(internals, workflowId, details, outcome) {
+  const entry = internals.pendingTimelineEntries?.get(workflowId)?.entry;
+  if (entry === void 0)
+    return;
+  const bounded = boundedDetails(details);
+  entry.children = bounded.details;
+  if (bounded.omitted > 0)
+    entry.childrenOmitted = bounded.omitted;
+  entry.speculationOutcome = outcome;
+}

package/dist/core/engine/validation/schedule-options.d.ts

@@ -1,9 +1,16 @@
-import type { ScheduleOptions, ScheduleOverlapPolicy } from '../../types.ts';
+import type { ScheduleOptions, ScheduleOverlapPolicy, ScheduleUpdateOptions } from '../../types.ts';
 export declare const SCHEDULE_OVERLAP_POLICIES: Set<ScheduleOverlapPolicy>;
 type NormalizedScheduleOptions = Required<Pick<ScheduleOptions, 'overlap' | 'backfill'>> & {
     id?: string;
     description?: string;
     jitterMs?: number;
 };
+type NormalizedScheduleUpdateOptions = {
+    description?: string;
+    overlap?: ScheduleOverlapPolicy;
+    backfill?: boolean;
+    jitterMs?: number;
+};
 export declare function normalizeScheduleOptions(options: ScheduleOptions | undefined): NormalizedScheduleOptions;
+export declare function normalizeScheduleUpdateOptions(options: ScheduleUpdateOptions | undefined): NormalizedScheduleUpdateOptions;
 export {};

package/dist/core/engine/validation/schedule-options.js

@@ -23,6 +23,24 @@ export function normalizeScheduleOptions(options) {
     }
   };
 }
+export function normalizeScheduleUpdateOptions(options) {
+  if (options === void 0)
+    return {};
+  if (typeof options !== "object" || options === null)
+    throw Error("options must be an object when provided");
+  return {
+    ...options.description !== void 0 && {
+      description: normalizeScheduleDescription(options.description)
+    },
+    ...options.overlap !== void 0 && { overlap: normalizeScheduleOverlap(options.overlap) },
+    ...options.backfill !== void 0 && {
+      backfill: normalizeScheduleBackfill(options.backfill)
+    },
+    ...options.jitter !== void 0 && {
+      jitterMs: normalizeScheduleJitter(options.jitter, "options.jitter")
+    }
+  };
+}
 function normalizeScheduleDescription(description) {
   if (typeof description !== "string")
     throw Error("options.description must be a string when provided");

package/dist/core/engine/validation/schedule.d.ts

@@ -1,5 +1,5 @@
 import type { ScheduleFilter, ScheduleOverlapPolicy, ScheduleSpec, ScheduleState, ScheduleStatus } from '../../types.ts';
-export { normalizeScheduleOptions, SCHEDULE_OVERLAP_POLICIES } from './schedule-options.ts';
+export { normalizeScheduleOptions, normalizeScheduleUpdateOptions, SCHEDULE_OVERLAP_POLICIES, } from './schedule-options.ts';
 export declare const SCHEDULE_STATUSES: Set<ScheduleStatus>;
 export declare function isValidScheduleTimestamp(value: unknown): value is number;
 export declare function isValidScheduleStatus(value: unknown): value is ScheduleStatus;

package/dist/core/engine/validation/schedule.js

@@ -4,7 +4,11 @@ import { parseCronExpression } from "../../schedule.js";
 import { parseDuration } from "../../scheduler.js";
 import { coerceStartWorkflowId } from "../../start-workflow-validation.js";
 import { SCHEDULE_OVERLAP_POLICIES } from "./schedule-options.js";
-export { normalizeScheduleOptions, SCHEDULE_OVERLAP_POLICIES } from "./schedule-options.js";
+export {
+  normalizeScheduleOptions,
+  normalizeScheduleUpdateOptions,
+  SCHEDULE_OVERLAP_POLICIES
+} from "./schedule-options.js";
 export const SCHEDULE_STATUSES = new Set(["active", "paused", "cancelled"]);
 export function isValidScheduleTimestamp(value) {
   return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
@@ -206,11 +210,29 @@ function decodeScheduleCurrentWorkflowId(decoded, scheduleId) {
 }
 function decodeScheduleQueuedRuns(decoded, scheduleId) {
   const queuedRuns = decoded.queuedRuns;
-  if (typeof queuedRuns !== "number" || !Number.isSafeInteger(queuedRuns) || queuedRuns < 0) {
+  if (!Array.isArray(queuedRuns)) {
     rejectInvalidScheduleRecord(scheduleId, "with invalid queuedRuns");
     return null;
   }
-  return queuedRuns;
+  const result = [], workflowIds = new Set;
+  for (const queuedRun of queuedRuns) {
+    if (!isRecord(queuedRun)) {
+      rejectInvalidScheduleRecord(scheduleId, "with invalid queuedRuns");
+      return null;
+    }
+    const { workflowId, queuedAt, occurrence } = queuedRun;
+    if (!isValidScheduleIdentifier(workflowId) || !isValidScheduleTimestamp(queuedAt) || occurrence !== void 0 && !isValidScheduleTimestamp(occurrence)) {
+      rejectInvalidScheduleRecord(scheduleId, "with invalid queuedRuns");
+      return null;
+    }
+    if (workflowIds.has(workflowId)) {
+      rejectInvalidScheduleRecord(scheduleId, "with duplicate queued workflow ids");
+      return null;
+    }
+    workflowIds.add(workflowId);
+    result.push({ workflowId, queuedAt, ...occurrence !== void 0 && { occurrence } });
+  }
+  return result;
 }
 function decodeScheduleMissedFireCount(decoded, scheduleId) {
   const missedFireCount = decoded.missedFireCount;
@@ -263,6 +285,8 @@ export function decodeScheduleRuntimeFields(decoded, scheduleId) {
   const queueFields = decodeScheduleQueueFields(decoded, scheduleId);
   if (queueFields === null)
     return null;
+  if (currentWorkflow.value !== void 0 && queueFields.queuedRuns.some((queuedRun) => queuedRun.workflowId === currentWorkflow.value))
+    return rejectInvalidScheduleRecord(scheduleId, "whose current workflow is also queued");
   return {
     ...optionFields,
     ...timestamps,