@lostgradient/weft 0.11.0 → 0.13.0

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/definition-schema-to-json.d.ts

@@ -1,4 +1,15 @@
 import type { DefinitionSchema } from './definition-schema.ts';
+/**
+ * Reset the module-level cached Valibot `toJsonSchema` converter.
+ *
+ * `cachedValibotConverter` is a process-global singleton shared by every test
+ * file that imports this module in the same `bun test` run, so whether it is
+ * already warm when a given test executes depends on unrelated test order.
+ * Tests that need to exercise the cache-miss path deterministically (e.g. the
+ * "no `process.getBuiltinModule`" error) must reset it first.
+ * @internal Test-only.
+ */
+export declare function resetValibotConverterCacheForTesting(): void;
 /**
  * Direction parameter for {@link definitionSchemaToJsonSchema}. `"input"`
  * produces the JSON Schema describing the validator's accepted input;

package/dist/core/types/definition-schema-to-json.js

@@ -1,6 +1,9 @@
-import { createRequire } from "node:module";
 import { z } from "zod";
+import { tryLoadNodeBuiltin } from "../../runtime/portable.js";
 let cachedValibotConverter;
+export function resetValibotConverterCacheForTesting() {
+  cachedValibotConverter = void 0;
+}
 export function definitionSchemaToJsonSchema(schema, direction = "input") {
   const standard = schema["~standard"], vendor = standard.vendor;
   if (vendor === "zod")
@@ -28,10 +31,16 @@ function convertValibot(schema) {
   const result = loadValibotConverter()(schema);
   return stripDialect(requirePlainObject(result, "valibot"));
 }
+function loadNodeRequire() {
+  return tryLoadNodeBuiltin("node:module")?.createRequire(import.meta.url);
+}
 export function loadValibotConverter(requireModule) {
-  const shouldUseCache = requireModule === void 0, resolver = requireModule ?? createRequire(import.meta.url);
+  const shouldUseCache = requireModule === void 0;
   if (shouldUseCache && cachedValibotConverter !== void 0)
     return cachedValibotConverter;
+  const resolver = requireModule ?? loadNodeRequire();
+  if (resolver === void 0)
+    throw Error("definitionSchemaToJsonSchema: converting a Valibot schema requires Bun or Node 22.5+ (process.getBuiltinModule) to resolve `@valibot/to-json-schema`. Not available in browser or edge runtimes; attach a `~standard.jsonSchema` converter to the schema instead.");
   let valibotModule;
   try {
     valibotModule = resolver("@valibot/to-json-schema");

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

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

@@ -66,6 +66,10 @@ export interface WorkflowState {
      * tree.
      */
     executionStateOwnerId?: string;
+    /** Immediate parent workflow id for runs launched through `ctx.startChild()`. */
+    parentWorkflowId?: WorkflowId;
+    /** Concrete parent run token, used to distinguish stable-id reuse generations. */
+    parentWorkflowExecutionToken?: string;
     createdAt: number;
     startedAt?: number;
     updatedAt: number;
@@ -76,6 +80,30 @@ export interface WorkflowState {
      * another workflow checkpoint. Absent for workflows started normally.
      */
     forkedFrom?: ForkLineage;
+    /** Immediate terminal run displaced when this run was created with `start-new`. */
+    restartedFrom?: RestartLineage;
+}
+/**
+ * Immediate predecessor recorded when `onTerminalConflict: 'start-new'` reuses
+ * a stable workflow id. The execution token identifies the concrete displaced
+ * run because both runs share the same workflow id.
+ *
+ * @example
+ * ```ts
+ * import type { RestartLineage } from '@lostgradient/weft';
+ *
+ * const lineage: RestartLineage = {
+ *   workflowId: 'nightly-reconciliation',
+ *   workflowExecutionToken: 'prior-run-token',
+ *   replacedAt: Date.now(),
+ * };
+ * void lineage;
+ * ```
+ */
+export interface RestartLineage {
+    workflowId: WorkflowId;
+    workflowExecutionToken?: string;
+    replacedAt: number;
 }
 /**
  * Lineage metadata recorded when a workflow was created by forking another
@@ -92,6 +120,32 @@ export interface ForkLineage {
  * whole workflow. Used in {@link WorkflowTimelineEntry}.
  */
 export type WorkflowTimelineStatus = 'running' | 'completed' | 'failed' | 'cancelled' | 'timed-out';
+/**
+ * Bounded metadata describing one direct operation inside a timeline coordinator.
+ *
+ * @example
+ * ```ts
+ * import type { WorkflowTimelineOperationDetail } from '@lostgradient/weft';
+ *
+ * const winner: WorkflowTimelineOperationDetail = {
+ *   index: 0,
+ *   operationId: 'race:0:0',
+ *   operationType: 'activity',
+ *   operationLabel: 'fetchPrimary',
+ *   outcome: 'won',
+ * };
+ * void winner;
+ * ```
+ */
+export type WorkflowTimelineOperationDetail = {
+    index: number;
+    key?: string;
+    operationId: string;
+    operationType: string;
+    operationLabel: string;
+    outcome: 'fulfilled' | 'rejected' | 'won' | 'lost';
+    errorSummary?: string;
+};
 /**
  * A single chronological entry in a workflow's execution timeline, summarising
  * one operation (activity call, sleep, signal wait, etc.). Returned by
@@ -110,6 +164,16 @@ export type WorkflowTimelineEntry = {
     timestamp: number;
     status: WorkflowTimelineStatus;
     versionTuple?: WorkflowVersionTuple;
+    /** Direct branch metadata for `ctx.all`, `ctx.runAll`, and `ctx.race`. */
+    branches?: WorkflowTimelineOperationDetail[];
+    /** Number of direct branches omitted from `branches` by the durable size bound. */
+    branchesOmitted?: number;
+    /** Ordered direct operations yielded by `ctx.speculate`. */
+    children?: WorkflowTimelineOperationDetail[];
+    /** Number of direct speculative children omitted from `children` by the durable size bound. */
+    childrenOmitted?: number;
+    /** Whether the speculative child context committed or rolled back. */
+    speculationOutcome?: 'committed' | 'rolled-back';
 };
 /**
  * Options accepted by `ctx.state.session(key, options)`.