@lostgradient/weft 0.12.0 → 0.14.0

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-cache-entry.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,

package/dist/core/engine/validation.js

@@ -4,6 +4,10 @@ import { normalizeFailureCategory } from "../failure-categories.js";
 import { coerceStartWorkflowId, parseStartWorkflowDuration } from "../start-workflow-validation.js";
 import { DEFAULT_WORKFLOW_VERSION } from "../versioning.js";
 import { isWorkflowTagArray } from "../workflow-tags.js";
+import {
+  MAX_TIMELINE_COORDINATOR_DETAILS,
+  MAX_TIMELINE_DETAIL_STRING_LENGTH
+} from "./timeline-coordinator-constants.js";
 const WORKFLOW_TIMELINE_STATUSES = new Set([
   "running",
   "completed",
@@ -28,12 +32,15 @@ const WORKFLOW_STATE_FIELD_NAMES = new Set(defineCompleteWorkflowStateFieldNames
   "versionTuple",
   "workflowExecutionToken",
   "executionStateOwnerId",
+  "parentWorkflowId",
+  "parentWorkflowExecutionToken",
   "createdAt",
   "startedAt",
   "updatedAt",
   "terminalCleanupToken",
   "executionDeadline",
-  "forkedFrom"
+  "forkedFrom",
+  "restartedFrom"
 ]));
 export function isSanitizedSearchAttributeValue(value) {
   if (typeof value === "string" || typeof value === "number" || typeof value === "boolean")
@@ -53,6 +60,30 @@ export function isFiniteNumber(value) {
 export function isTimelineStep(value) {
   return typeof value === "number" && Number.isSafeInteger(value) && value >= 1;
 }
+const WORKFLOW_TIMELINE_DETAIL_OUTCOMES = new Set(["fulfilled", "rejected", "won", "lost"]);
+function isBoundedTimelineDetailString(value) {
+  return typeof value === "string" && value.length <= MAX_TIMELINE_DETAIL_STRING_LENGTH;
+}
+const TIMELINE_DETAIL_FIELD_CHECKS = [
+  (detail) => typeof detail.index === "number" && Number.isSafeInteger(detail.index) && detail.index >= 0,
+  (detail) => detail.key === void 0 || isBoundedTimelineDetailString(detail.key),
+  (detail) => isBoundedTimelineDetailString(detail.operationId),
+  (detail) => isBoundedTimelineDetailString(detail.operationType),
+  (detail) => isBoundedTimelineDetailString(detail.operationLabel),
+  (detail) => WORKFLOW_TIMELINE_DETAIL_OUTCOMES.has(detail.outcome),
+  (detail) => detail.errorSummary === void 0 || isBoundedTimelineDetailString(detail.errorSummary)
+];
+function isWorkflowTimelineOperationDetail(value) {
+  if (!isRecord(value))
+    return !1;
+  return TIMELINE_DETAIL_FIELD_CHECKS.every((check) => check(value));
+}
+function isWorkflowTimelineOperationDetails(value) {
+  return value === void 0 || Array.isArray(value) && value.length <= MAX_TIMELINE_COORDINATOR_DETAILS && value.every(isWorkflowTimelineOperationDetail);
+}
+function isOmittedTimelineDetailCount(value) {
+  return value === void 0 || typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
 const TIMELINE_ENTRY_FIELD_CHECKS = [
   (entry) => isTimelineStep(entry.step),
   (entry) => typeof entry.operationType === "string",
@@ -62,7 +93,12 @@ const TIMELINE_ENTRY_FIELD_CHECKS = [
   (entry) => WORKFLOW_TIMELINE_STATUSES.has(entry.status),
   (entry) => entry.outputSummary === void 0 || typeof entry.outputSummary === "string",
   (entry) => entry.duration === void 0 || isFiniteNumber(entry.duration),
-  (entry) => entry.versionTuple === void 0 || isWorkflowVersionTuple(entry.versionTuple)
+  (entry) => entry.versionTuple === void 0 || isWorkflowVersionTuple(entry.versionTuple),
+  (entry) => isWorkflowTimelineOperationDetails(entry.branches),
+  (entry) => isOmittedTimelineDetailCount(entry.branchesOmitted),
+  (entry) => isWorkflowTimelineOperationDetails(entry.children),
+  (entry) => isOmittedTimelineDetailCount(entry.childrenOmitted),
+  (entry) => entry.speculationOutcome === void 0 || entry.speculationOutcome === "committed" || entry.speculationOutcome === "rolled-back"
 ];
 export function isWorkflowTimelineEntry(value) {
   if (!isRecord(value))
@@ -102,8 +138,36 @@ export function decodeWorkflowState(bytes) {
       console.warn(`[weft] Decoded workflow state for "${String(state.id)}" has an invalid executionStateOwnerId field; falling back to the workflow id as the execution owner. This usually indicates corruption or tampering of the storage record.`);
       delete state.executionStateOwnerId;
     }
+  sanitizeDecodedParentLineage(state);
+  sanitizeDecodedRestartLineage(state);
   return decodedRecord === void 0 ? state : stripUnknownWorkflowStateFields(state, decodedRecord);
 }
+function sanitizeDecodedParentLineage(state) {
+  if (state.parentWorkflowId !== void 0)
+    try {
+      coerceStartWorkflowId(state.parentWorkflowId, "parentWorkflowId");
+    } catch {
+      delete state.parentWorkflowId;
+    }
+  if (typeof state.parentWorkflowExecutionToken !== "string" || state.parentWorkflowExecutionToken.length === 0 || state.parentWorkflowId === void 0)
+    delete state.parentWorkflowExecutionToken;
+}
+function sanitizeDecodedRestartLineage(state) {
+  const restartedFrom = state.restartedFrom;
+  if (!isRecord(restartedFrom)) {
+    delete state.restartedFrom;
+    return;
+  }
+  try {
+    coerceStartWorkflowId(restartedFrom.workflowId, "restartedFrom.workflowId");
+  } catch {
+    delete state.restartedFrom;
+    return;
+  }
+  const { workflowExecutionToken, replacedAt } = restartedFrom;
+  if (workflowExecutionToken !== void 0 && (typeof workflowExecutionToken !== "string" || workflowExecutionToken.length === 0) || typeof replacedAt !== "number" || !Number.isSafeInteger(replacedAt) || replacedAt < 0)
+    delete state.restartedFrom;
+}
 function stripUnknownWorkflowStateFields(state, stateFields) {
   for (const fieldName of Object.keys(stateFields))
     if (!WORKFLOW_STATE_FIELD_NAMES.has(fieldName))

package/dist/core/engine/workflow-state-stream.d.ts

@@ -2,8 +2,12 @@ import type { AttributeFilter, ListFilter, WorkflowState } from '../types.ts';
 import type { EngineInternals } from './internals.ts';
 /** Stream decoded workflow states that match a list filter. */
 export declare function streamMatchingWorkflowStates(internals: EngineInternals, filter?: ListFilter): AsyncGenerator<WorkflowState>;
-/** Resolve the indexed workflow IDs implied by tag and search-attribute filters. */
+/** Resolve indexed workflow IDs implied by lineage, schedule, tag, and search-attribute filters. */
 export declare function resolveConstrainedIds(internals: EngineInternals, filter: ListFilter | undefined, normalizedTagFilters: readonly string[] | undefined): Promise<Set<string> | null>;
 /** Query a single search-attribute index filter and return matching workflow IDs. */
 export declare function queryAttributeIndex(internals: EngineInternals, filter: AttributeFilter): Promise<Set<string>>;
+/** Resolve the durable reverse index from one concrete parent run to its direct children. */
+export declare function queryChildWorkflowIndex(internals: EngineInternals, parentWorkflowId: string, parentWorkflowExecutionToken: string | undefined): Promise<Set<string>>;
+/** Resolve the durable reverse index from a schedule id to launched workflow ids. */
+export declare function queryScheduleRunIndex(internals: EngineInternals, scheduleId: string): Promise<Set<string>>;
 export declare function isTopLevelWorkflowStateKey(key: string): boolean;

package/dist/core/engine/workflow-state-stream.js

@@ -15,6 +15,7 @@ import {
   matchesListFilter
 } from "./state-utilities.js";
 import { decodeWorkflowState } from "./validation.js";
+import { MAX_LIST_SCAN_ROWS, WorkflowListScanCapExceededError } from "./workflow-indexes.js";
 const ATTRIBUTE_SCAN_CONCURRENCY = 8;
 export async function* streamMatchingWorkflowStates(internals, filter) {
   const normalizedTagFilters = normalizeWorkflowTags(filter?.tags), constrainedIds = await resolveConstrainedIds(internals, filter, normalizedTagFilters);
@@ -54,10 +55,9 @@ async function readSearchAttributesForFilter(internals, workflowId, filter) {
   return decodeSearchAttributeRecord(await internals.storage.get(KEYS.attribute(workflowId)));
 }
 export async function resolveConstrainedIds(internals, filter, normalizedTagFilters) {
-  const attributeFilters = filter?.attributes, hasAttributeFilters = attributeFilters !== void 0 && attributeFilters.length > 0, hasTagFilters = normalizedTagFilters !== void 0 && normalizedTagFilters.length > 0;
-  if (!hasAttributeFilters && !hasTagFilters)
+  const attributeFilters = filter?.attributes, queries = buildConstrainedIdQueries(internals, normalizedTagFilters, attributeFilters, filter?.scheduleId, filter?.parentWorkflowId, filter?.parentWorkflowExecutionToken);
+  if (queries.length === 0)
     return null;
-  const queries = buildConstrainedIdQueries(internals, normalizedTagFilters, attributeFilters);
   return intersectIdentifierSets(await runConstrainedIdQueries(queries));
 }
 export async function queryAttributeIndex(internals, filter) {
@@ -68,29 +68,52 @@ export async function queryAttributeIndex(internals, filter) {
     await collectRangeAttributeMatches(internals, filter, prefix, ids);
   return ids;
 }
-function buildConstrainedIdQueries(internals, normalizedTagFilters, attributeFilters) {
+function buildConstrainedIdQueries(internals, normalizedTagFilters, attributeFilters, scheduleId, parentWorkflowId, parentWorkflowExecutionToken) {
   return [
+    ...scheduleId === void 0 ? [] : [() => queryScheduleRunIndex(internals, scheduleId)],
+    ...parentWorkflowId === void 0 ? [] : [() => queryChildWorkflowIndex(internals, parentWorkflowId, parentWorkflowExecutionToken)],
     ...normalizedTagFilters?.map((tag) => () => queryTagIndex(internals, tag)) ?? [],
     ...attributeFilters?.map((attributeFilter) => () => queryAttributeIndex(internals, attributeFilter)) ?? []
   ];
 }
+export async function queryChildWorkflowIndex(internals, parentWorkflowId, parentWorkflowExecutionToken) {
+  const workflowIds = new Set, prefix = KEYS.childWorkflowByParentPrefix(parentWorkflowId, parentWorkflowExecutionToken);
+  for await (const [key] of internals.storage.scan(prefix)) {
+    if (workflowIds.size >= MAX_LIST_SCAN_ROWS)
+      throw new WorkflowListScanCapExceededError(MAX_LIST_SCAN_ROWS);
+    const encodedWorkflowId = key.slice(prefix.length).split(":").at(-1);
+    if (encodedWorkflowId === void 0)
+      continue;
+    const workflowId = tryDecodeStorageKeyComponent(encodedWorkflowId);
+    if (workflowId !== null)
+      workflowIds.add(workflowId);
+  }
+  return workflowIds;
+}
+export async function queryScheduleRunIndex(internals, scheduleId) {
+  const workflowIds = new Set, prefix = KEYS.scheduleRunBySchedulePrefix(scheduleId);
+  for await (const [key] of internals.storage.scan(prefix)) {
+    if (workflowIds.size >= MAX_LIST_SCAN_ROWS)
+      throw new WorkflowListScanCapExceededError(MAX_LIST_SCAN_ROWS);
+    const encodedWorkflowId = key.slice(prefix.length), workflowId = tryDecodeStorageKeyComponent(encodedWorkflowId);
+    if (workflowId !== null)
+      workflowIds.add(workflowId);
+  }
+  return workflowIds;
+}
 async function runConstrainedIdQueries(queries) {
-  const idSets = Array.from({ length: queries.length });
   let nextIndex = 0;
   const runWorker = async () => {
+    const workerResults = [];
     while (nextIndex < queries.length) {
       const currentIndex = nextIndex;
       nextIndex += 1;
-      idSets[currentIndex] = await queries[currentIndex]();
+      workerResults.push([currentIndex, await queries[currentIndex]()]);
     }
-  }, workerLimit = Math.max(1, Math.min(ATTRIBUTE_SCAN_CONCURRENCY, queries.length));
-  await Promise.all(Array.from({ length: workerLimit }, () => runWorker()));
-  return idSets.map(requireConstrainedIdSet);
-}
-function requireConstrainedIdSet(idSet) {
-  if (idSet === void 0)
-    throw Error("Attribute index query did not produce a workflow ID set.");
-  return idSet;
+    return workerResults;
+  }, workerLimit = Math.max(1, Math.min(ATTRIBUTE_SCAN_CONCURRENCY, queries.length)), completedResults = (await Promise.all(Array.from({ length: workerLimit }, () => runWorker()))).flat();
+  completedResults.sort(([leftIndex], [rightIndex]) => leftIndex - rightIndex);
+  return completedResults.map(([, idSet]) => idSet);
 }
 async function collectExactAttributeMatches(internals, filter, attributeName, ids) {
   const exactValues = attributeFilterExactValues(filter);

package/dist/core/events/schedule-events.d.ts

@@ -38,10 +38,9 @@ export declare class ScheduleFiredEvent extends Event {
     /** Wall-clock time the run was launched, from the engine's injected clock. */
     readonly firedAt: number;
     /**
-     * The scheduled grid timestamp the occurrence was due. `undefined` for a run
-     * that drained from the `queue` overlap policy: a queued occurrence is tracked
-     * only as a count (`queuedRuns`), so its original due timestamp is not retained
-     * and cannot be reported when the run finally launches.
+     * The scheduled grid timestamp the occurrence was due. Queue overlap retains
+     * this timestamp on the durable queue entry and reports it when the run drains.
+     * It is undefined only when an internal caller did not supply an occurrence.
      */
     readonly occurrence: number | undefined;
     constructor(scheduleId: string, workflowId: string, firedAt: number, occurrence?: number);

package/dist/core/events/workflow-events.d.ts

@@ -241,7 +241,8 @@ export declare class WorkflowRecoverySkippedEvent extends Event {
  *   dead-letter horizon is reached. Per-attempt observability — fires on every retry.
  * - `'dead-lettered'`: the retry horizon was reached without success; the external
  *   resource may be leaked. The durable record is `KEYS.teardownDeadLetter`, which
- *   survives purge so the leak is auditable after the workflow record is gone.
+ *   survives purge so `getFinalizerStatus()` remains auditable after the workflow
+ *   record is gone.
  *
  * @example
  * ```ts

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

@@ -20,6 +20,9 @@ import { WeftError } from './weft-error.ts';
 export declare const listFilterObjectSchema: z.ZodObject<{
     status: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<WorkflowStatus, unknown, z.core.$ZodTypeInternals<WorkflowStatus, unknown>>, z.ZodArray<z.ZodType<WorkflowStatus, unknown, z.core.$ZodTypeInternals<WorkflowStatus, unknown>>>]>>;
     type: z.ZodOptional<z.ZodString>;
+    scheduleId: z.ZodOptional<z.ZodString>;
+    parentWorkflowId: z.ZodOptional<z.ZodString>;
+    parentWorkflowExecutionToken: z.ZodOptional<z.ZodString>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     attributes: z.ZodOptional<z.ZodArray<z.ZodObject<{
         key: z.ZodUnion<readonly [z.ZodString, z.ZodAny]>;

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

@@ -35,6 +35,9 @@ const WORKFLOW_STATUSES = [
 export const listFilterObjectSchema = z.object({
   status: z.union([workflowStatusSchema, z.array(workflowStatusSchema)]).optional(),
   type: z.string().min(1).optional(),
+  scheduleId: z.string().min(1).optional(),
+  parentWorkflowId: z.string().min(1).optional(),
+  parentWorkflowExecutionToken: z.string().min(1).optional(),
   tags: z.array(z.string()).optional(),
   attributes: z.array(attributeFilterSchema).optional(),
   limit: z.number().int().min(1).max(1000).optional(),
@@ -70,6 +73,14 @@ export function normalizeListFilter(input) {
   const result = listFilterObjectSchema.safeParse(input ?? {});
   if (!result.success)
     throw new ListFilterValidationError(result.error.issues.map(flattenIssue));
+  if (result.data.parentWorkflowExecutionToken !== void 0 && result.data.parentWorkflowId === void 0)
+    throw new ListFilterValidationError([
+      {
+        path: ["parentWorkflowExecutionToken"],
+        message: "parentWorkflowExecutionToken requires parentWorkflowId",
+        code: "custom"
+      }
+    ]);
   return result.data;
 }
 

package/dist/core/registry-snapshot.d.ts

@@ -1,3 +1,25 @@
+/**
+ * Pure builder that captures a snapshot of the engine's locally-registered
+ * workflows and activities, with their JSON Schemas. This is the data source
+ * behind the `GET /v1/registry` REST endpoint and (later) the MCP server.
+ *
+ * The output is a plain object designed to be safe for JSON serialization.
+ * Absent metadata fields are omitted (never `null`, never `{}`); converter
+ * exceptions surface as a typed {@link RegistrySchemaConversionError} (see
+ * its JSDoc for what reaches the wire vs server logs).
+ *
+ * **Ordering guarantee.** Builder code inserts workflow, activity, signal,
+ * update, and query keys in alphabetical (codepoint) order. Workflow and
+ * activity names cannot be integer-like (the name grammar requires a leading
+ * letter or underscore), but signal/update/query names accept any string, so
+ * integer-like message names could theoretically be reordered by JS engines
+ * despite the explicit sort. Clients that want to protect themselves from
+ * future registry sources should still sort `Object.keys(...)` before
+ * presenting or diffing snapshot entries.
+ *
+ * @module core/registry-snapshot
+ */
+import type { ActivityMetadata } from './activity-registry.ts';
 import type { Engine } from './engine.ts';
 import { WeftError } from './weft-error.ts';
 /**
@@ -6,12 +28,20 @@ import { WeftError } from './weft-error.ts';
  * versions with a clear upgrade message.
  */
 export declare const REGISTRY_VERSION = 1;
+/** Schema metadata reported for a statically registered workflow message. */
+export type RegistryMessageEntry = {
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+};
 /** Metadata reported per workflow in a registry snapshot. */
 export type RegistryWorkflowEntry = {
     inputSchema?: Record<string, unknown>;
     outputSchema?: Record<string, unknown>;
     description?: string;
     tags?: ReadonlyArray<string>;
+    signals?: Record<string, RegistryMessageEntry>;
+    updates?: Record<string, RegistryMessageEntry>;
+    queries?: Record<string, RegistryMessageEntry>;
 };
 /**
  * Metadata reported per activity in a registry snapshot.
@@ -31,6 +61,8 @@ export type RegistryActivityEntry = {
     /** Engine assigns a default queue when none is specified, so this is always populated. */
     queue: string;
     description?: string;
+    retry?: ActivityMetadata['retry'];
+    timeout?: ActivityMetadata['timeout'];
 };
 /**
  * Snapshot of every locally-registered workflow and activity, suitable for