@lostgradient/weft 0.12.0 → 0.13.0

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

package/dist/core/registry-snapshot.js

@@ -49,8 +49,32 @@ function buildWorkflowEntry(definition) {
     entry.description = definition.description;
   if (definition.tags.length > 0)
     entry.tags = [...definition.tags];
+  addWorkflowMessageEntries(entry, definition);
   return entry;
 }
+function addWorkflowMessageEntries(entry, definition) {
+  if (definition.signals !== void 0 && Object.keys(definition.signals).length > 0)
+    entry.signals = buildMessageEntries(definition.type, "signal", definition.signals);
+  if (definition.updates !== void 0 && Object.keys(definition.updates).length > 0)
+    entry.updates = buildMessageEntries(definition.type, "update", definition.updates);
+  if (definition.queries !== void 0 && Object.keys(definition.queries).length > 0)
+    entry.queries = buildMessageEntries(definition.type, "query", definition.queries);
+}
+function buildMessageEntries(workflowType, messageKind, definitions) {
+  const entries = Object.create(null);
+  for (const name of Object.keys(definitions).toSorted()) {
+    const definition = definitions[name];
+    if (definition === void 0)
+      continue;
+    const entry = {}, entityName = `${workflowType}.${messageKind}.${name}`;
+    if (definition.inputSchema !== void 0)
+      entry.inputSchema = convertSchema("workflow", entityName, "inputSchema", definition.inputSchema);
+    if (definition.outputSchema !== void 0)
+      entry.outputSchema = convertSchema("workflow", entityName, "outputSchema", definition.outputSchema);
+    entries[name] = entry;
+  }
+  return entries;
+}
 function buildActivityEntry(metadata) {
   const entry = { queue: metadata.queue };
   if (metadata.inputSchema !== void 0)
@@ -59,6 +83,10 @@ function buildActivityEntry(metadata) {
     entry.outputSchema = convertSchema("activity", metadata.name, "outputSchema", metadata.outputSchema);
   if (metadata.description !== void 0)
     entry.description = metadata.description;
+  if (metadata.retry !== void 0)
+    entry.retry = metadata.retry;
+  if (metadata.timeout !== void 0)
+    entry.timeout = metadata.timeout;
   return entry;
 }
 function convertSchema(entityKind, entityName, field, schema) {

package/dist/core/review/index.d.ts

@@ -43,7 +43,7 @@ export interface ReviewRequest {
  * The `decision` field is the binary outcome; `sectionDecisions` carries
  * per-section verdicts when `allowPartial` is enabled on the request.
  */
-export interface ReviewDecision {
+export interface ReviewDecisionRecord {
     reviewId: string;
     decision: 'approved' | 'rejected' | 'needs-changes';
     reviewer: string;
@@ -119,7 +119,7 @@ export interface HumanReviewOptions extends ReviewOptions {
 }
 /**
  * The decision payload returned to the workflow from `ctx.review()`.
- * Alias for {@link ReviewDecision}.
+ * Alias for {@link ReviewDecisionRecord}.
  *
  * @example
  * ```ts
@@ -134,7 +134,7 @@ export interface HumanReviewOptions extends ReviewOptions {
  * void result;
  * ```
  */
-export type HumanReviewResult = ReviewDecision;
+export type HumanReviewResult = ReviewDecisionRecord;
 /**
  * The action returned by {@link ReviewCoordinator.checkEscalations} when an
  * escalation step has fired. Either reassigns the review to a new owner or
@@ -253,7 +253,7 @@ export declare class ReviewCoordinator {
     /** Create a review request and persist it. */
     createReview(workflowId: string, options: ReviewOptions): Promise<ReviewRequest>;
     /** Submit a review decision. */
-    submitDecision(reviewId: string, decision: Omit<ReviewDecision, 'reviewId' | 'timestamp'>): Promise<ReviewDecision>;
+    submitDecision(reviewId: string, decision: Omit<ReviewDecisionRecord, 'reviewId' | 'timestamp'>): Promise<ReviewDecisionRecord>;
     /** Get a pending review. */
     getReview(workflowId: string, reviewId: string): Promise<ReviewRequest | null>;
     /** List pending reviews. */

package/dist/core/types/activity.d.ts

@@ -116,16 +116,18 @@ export interface ActivityContext {
      * `client.activity.*` methods).
      *
      * The durable task token is announced on the engine as an
-     * `activity:async-pending` event (listen for it to receive the token).
-     * The token is deterministic and survives engine restart: it is re-minted
-     * identically when the activity replays after recovery.
+     * `activity:async-pending` event and remains discoverable through
+     * `engine.listPendingAsyncActivities(workflowId)` or
+     * `client.activity.listPending(workflowId)`. The token is deterministic and
+     * survives engine restart: it is re-minted identically on recovery.
      *
      * Security: the token is a deterministic identifier, NOT a secret. When the
      * completion endpoint is reachable by untrusted callers, anyone who can infer
      * a workflow id can forge this activity's result or error. Treat the completed
      * value as hostile external input (validate it as you would a signal payload),
-     * and gate the mutating surface with `serve({ auth })` if completions must not
-     * be anonymous.
+     * The transport query requires `workflows:read`; completion and failure require
+     * `workflows:write`. Configure `serve({ auth })` with those scopes before
+     * exposing the routes.
      *
      * `completeAsync()` never returns normally — it throws an internal sentinel
      * that the engine recognizes to park the activity. Call it as the last
@@ -148,6 +150,51 @@ export interface ActivityContext {
      */
     completeAsync(): never;
 }
+/**
+ * Durable metadata for one activity awaiting out-of-band completion.
+ * @example
+ * ```ts
+ * import type { PendingAsyncActivityInfo } from '@lostgradient/weft';
+ * declare const pending: PendingAsyncActivityInfo; console.log(pending.token, pending.activityName);
+ * ```
+ */
+export interface PendingAsyncActivityInfo {
+    readonly token: string;
+    readonly operationId: string;
+    readonly activityName: string;
+    readonly step: number;
+    readonly attempt: number;
+    readonly createdAt: number;
+}
+/**
+ * Bounded cursor options for listing a workflow's pending async activities.
+ * @example
+ * ```ts
+ * import type { PendingAsyncActivityListOptions } from '@lostgradient/weft';
+ * const options: PendingAsyncActivityListOptions = { limit: 25 };
+ * void options;
+ * ```
+ */
+export interface PendingAsyncActivityListOptions {
+    /** Maximum records to inspect for this page. Defaults to 50 and cannot exceed 200. */
+    readonly limit?: number;
+    /** Opaque continuation cursor returned by the previous page. */
+    readonly cursor?: string;
+}
+/**
+ * One deterministic page of pending async activities.
+ * @example
+ * ```ts
+ * import type { PendingAsyncActivityPage } from '@lostgradient/weft';
+ * const page: PendingAsyncActivityPage = { items: [] };
+ * void page;
+ * ```
+ */
+export interface PendingAsyncActivityPage {
+    readonly items: PendingAsyncActivityInfo[];
+    /** Present when another page of durable records may remain. */
+    readonly nextCursor?: string;
+}
 /**
  * Per-invocation overrides when calling an activity from a workflow via
  * `ctx.run(activity, input, options)`. Any field overrides the

package/dist/core/types/bulk.d.ts

@@ -52,6 +52,7 @@ export type BulkOperationPrincipal = {
 export type BulkOperationFilterSummary = {
     status?: WorkflowStatus | WorkflowStatus[];
     type?: string;
+    scheduleId?: string;
     tags?: string[];
     attributes?: Array<{
         key: string;

package/dist/core/types/list-options.d.ts

@@ -43,6 +43,12 @@ export interface ListFilter {
      * ```
      */
     type?: string;
+    /** Match workflow runs launched by this recurring schedule. */
+    scheduleId?: string;
+    /** Match direct child workflows launched by this parent workflow id. */
+    parentWorkflowId?: string;
+    /** Narrow `parentWorkflowId` to one concrete parent run generation. */
+    parentWorkflowExecutionToken?: string;
     /** Match workflows that carry every listed tag. */
     tags?: string[];
     /** Filter on indexed search attributes (equality, string any-of, or range). */

package/dist/core/types/options.d.ts

@@ -446,14 +446,15 @@ export interface EngineOptions<TServices = unknown> {
     resolveWorkflowServices?: (info: WorkflowServicesResolverInfo) => WorkflowServicesResolution<TServices> | Promise<WorkflowServicesResolution<TServices>>;
     /**
      * Optional host sink for `ctx.log` records. When provided, every non-replayed
-     * record from inline workflow execution is routed here (into your pino / winston
-     * / OpenTelemetry stack, etc.) **instead of** the console; when omitted, records
-     * fall back to the matching `console` method, preserving the default behavior.
+     * record from inline and worker workflow execution is routed here (into your
+     * pino / winston / OpenTelemetry stack, etc.) **instead of** the console; when
+     * omitted, records fall back to the matching process console.
      *
      * Engine-scoped infrastructure: set once at construction, never per run. The sink
      * is not invoked for records suppressed during replay, so a recovered run does
-     * not re-emit its replayed prefix. Worker-mode records still log to the worker
-     * process's console — routing them back to the host is tracked separately.
+     * not re-emit its replayed prefix. Weft does not persist these records or expose
+     * a log-history API; the sink is the integration point for retention and remote
+     * log queries.
      */
     onLog?: (record: WorkflowLogRecord) => void;
 }

package/dist/core/types/reviews.d.ts

@@ -1,4 +1,4 @@
-import type { ReviewDecision as CompletedReviewDecision, ReviewRequest } from '../review/index.ts';
+import type { ReviewDecisionRecord, ReviewRequest } from '../review/index.ts';
 /**
  * Outcome of a human review step initiated by `ctx.waitForReview`. Pass as
  * the `decision` field in {@link SubmitReviewOptions} when calling
@@ -125,7 +125,7 @@ export interface PendingReviewEntry extends ReviewRequest {
  * void entry;
  * ```
  */
-export interface CompletedReviewEntry extends CompletedReviewDecision {
+export interface CompletedReviewEntry extends ReviewDecisionRecord {
     status: 'completed';
     workflowId: string;
     artifact: unknown;

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

@@ -23,6 +23,29 @@ export type ScheduleStatus = 'active' | 'paused' | 'cancelled';
  * ```
  */
 export type ScheduleOverlapPolicy = 'skip' | 'queue' | 'cancel-running' | 'allow';
+/**
+ * One occurrence waiting behind the active run of a `queue` overlap schedule.
+ * `workflowId` is reserved when the occurrence enters the durable queue and is
+ * used when it eventually starts. No workflow record exists for that id until
+ * the queue drains, so `engine.get(workflowId)` returns `null` while it waits.
+ *
+ * @example
+ * ```ts
+ * import type { ScheduleQueuedRun } from '@lostgradient/weft';
+ *
+ * const queuedRun: ScheduleQueuedRun = {
+ *   workflowId: 'daily-report-queued-1',
+ *   queuedAt: Date.now(),
+ * };
+ * void queuedRun;
+ * ```
+ */
+export interface ScheduleQueuedRun {
+    workflowId: string;
+    queuedAt: number;
+    /** Nominal cadence timestamp retained from the occurrence that was queued. */
+    occurrence?: number;
+}
 /**
  * Recurrence specification for a schedule. A schedule fires either on a cron
  * cadence (`{ cron: '0 9 * * *' }`) or at a fixed interval
@@ -95,6 +118,24 @@ export interface ScheduleOptions {
      */
     jitter?: Duration;
 }
+/**
+ * Mutable options accepted when updating an existing schedule. Omitted fields
+ * retain their persisted values. Schedule identity, workflow type, and input
+ * are intentionally excluded.
+ *
+ * @example
+ * ```ts
+ * import { Engine, workflow, type ScheduleUpdateOptions } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.register(workflow({ name: 'report' }).execute(async function* () { return 'done'; }));
+ * await engine.schedule('report', null, '0 9 * * *', { id: 'daily-report' });
+ * const options: ScheduleUpdateOptions = { overlap: 'queue', jitter: '30s' };
+ * await engine.updateSchedule('daily-report', '30 9 * * *', options);
+ * engine[Symbol.dispose]();
+ * ```
+ */
+export type ScheduleUpdateOptions = Pick<ScheduleOptions, 'description' | 'overlap' | 'backfill' | 'jitter'>;
 /**
  * Declarative recurring schedule definition returned by {@link schedule}. Supply
  * exactly one of `cron` (cron cadence) or `every` (fixed interval).
@@ -176,7 +217,8 @@ export interface ScheduleState {
     missedFireCount: number;
     nextFireAt: number | null;
     currentWorkflowId?: string;
-    queuedRuns: number;
+    /** Ordered durable occurrences waiting behind `currentWorkflowId`. */
+    queuedRuns: ScheduleQueuedRun[];
 }
 /**
  * Lightweight summary of a recurring schedule returned by list operations.
@@ -208,7 +250,8 @@ export interface ScheduleSummary {
     missedFireCount: number;
     nextFireAt: number | null;
     currentWorkflowId?: string;
-    queuedRuns: number;
+    /** Ordered durable occurrences waiting behind `currentWorkflowId`. */
+    queuedRuns: ScheduleQueuedRun[];
 }
 /**
  * Filter criteria for `engine.listSchedules`. All fields are optional.

package/dist/core/types/services-resolution.d.ts

@@ -50,11 +50,11 @@ export interface WorkflowServicesResolverLaunchOptions {
 }
 /**
  * Schedule context passed to {@link EngineOptions.resolveWorkflowServices} for
- * scheduled occurrences. New scheduled runs persist this context with the
- * workflow record, so a fresh-process recovery receives the same schedule id and
- * known occurrence timestamp as the live launch path. Runs from older stores
- * that predate the metadata may omit it, and queue-drained runs may omit
- * `occurrence` because their original grid timestamp was not retained.
+ * scheduled occurrences. Scheduled runs persist this context with the workflow
+ * record, so a fresh-process recovery receives the same schedule id and known
+ * occurrence timestamp as the live launch path. Queue entries retain the
+ * occurrence timestamp through drain; runs from older stores that predate this
+ * metadata may omit the context or occurrence.
  *
  * @example
  * ```ts