@lostgradient/weft 0.2.1 → 0.4.0

package/dist/core/context/activity-schedule-to-close.d.ts

@@ -0,0 +1,159 @@
+import type { ActivityCallOptions, Duration } from '../types.ts';
+import { WeftError } from '../weft-error.ts';
+/**
+ * Thrown when an activity's {@link ActivityCallOptions.scheduleToCloseTimeout}
+ * is enforced at the retry boundary. This fires in two situations, both reported
+ * with the **actual** wall-clock {@link elapsed} at the moment of the throw:
+ *
+ * - The budget has genuinely elapsed (`elapsed >= budget`) — an attempt overran,
+ *   or downtime during a backoff sleep pushed wall time past the deadline.
+ * - The budget has NOT yet elapsed, but the next retry's backoff would start it at
+ *   or after the deadline — so Weft refuses to schedule a doomed sleep and fails at
+ *   the retry decision point. In this case {@link projectedNextDispatchElapsed} is
+ *   set to the elapsed milliseconds after first dispatch at which the skipped retry
+ *   would have started.
+ *
+ * The name is registered as a `timeout` failure category, so it classifies and is
+ * searchable the same way the other timeout errors are.
+ *
+ * @example
+ * ```ts
+ * import { ActivityScheduleToCloseTimeoutError } from '@lostgradient/weft';
+ *
+ * function exceededRetryBudget(error: unknown): boolean {
+ *   return error instanceof ActivityScheduleToCloseTimeoutError;
+ * }
+ * ```
+ */
+export declare class ActivityScheduleToCloseTimeoutError extends WeftError<'ActivityScheduleToCloseTimeoutError'> {
+    readonly activityName: string;
+    /** Actual wall-clock milliseconds elapsed since first dispatch, at the throw. */
+    readonly elapsed: number;
+    readonly budget: number;
+    /**
+     * When the failure is the early retry-decision case (the budget has not yet
+     * elapsed but the next backoff would start the retry at or after the deadline),
+     * the elapsed milliseconds after first dispatch at which that skipped retry would
+     * have started. `undefined` when the budget had genuinely elapsed at the throw.
+     */
+    readonly projectedNextDispatchElapsed?: number;
+    constructor(activityName: string, elapsed: number, budget: number, projectedNextDispatchElapsed?: number);
+}
+/**
+ * Thrown when an inline activity attempt overruns its per-attempt
+ * {@link ActivityCallOptions.timeout} wall-clock cap. The cap is measured fresh
+ * on every attempt (unlike {@link ActivityScheduleToCloseTimeoutError}, which is a
+ * single budget across all attempts), so the {@link attempt} number is reported.
+ *
+ * When this fires, the workflow stops awaiting the attempt and the activity's
+ * `AbortSignal` is aborted so a cooperating activity can stop promptly — but Weft
+ * cannot forcibly preempt a running activity function, so a non-cooperating
+ * activity keeps executing in the background until it returns. The timed-out
+ * attempt is retried (with a fresh cap) when a retry policy permits.
+ *
+ * The name is registered as a `timeout` failure category, so it classifies and is
+ * searchable the same way the other timeout errors are. `timeout` is enforced for
+ * **inline** execution only; worker-mode per-attempt bounds are governed by
+ * `visibilityTimeout`.
+ *
+ * @example
+ * ```ts
+ * import { ActivityPerAttemptTimeoutError } from '@lostgradient/weft';
+ *
+ * function overranAttempt(error: unknown): boolean {
+ *   return error instanceof ActivityPerAttemptTimeoutError;
+ * }
+ * ```
+ */
+export declare class ActivityPerAttemptTimeoutError extends WeftError<'ActivityPerAttemptTimeoutError'> {
+    readonly activityName: string;
+    /** The 1-based attempt number that overran its per-attempt cap. */
+    readonly attempt: number;
+    /** The per-attempt wall-clock cap, in milliseconds. */
+    readonly timeoutMs: number;
+    constructor(activityName: string, attempt: number, timeoutMs: number);
+}
+/**
+ * The largest delay a single `setTimeout` can represent without 32-bit overflow.
+ * A delay above this silently wraps and fires almost immediately, so a per-attempt
+ * `timeout` larger than this is rejected rather than misbehaving. (~24.8 days.)
+ */
+export declare const MAX_PER_ATTEMPT_TIMEOUT_MS = 2147483647;
+/**
+ * Parse a per-attempt `timeout` duration to milliseconds, or `undefined` when
+ * unset. The value is read off the serialized activity operation, so it is typed
+ * `unknown` and validated here as hostile input: only a `number`/`string`
+ * {@link Duration} is accepted, and `parseDuration` enforces finite/non-negative
+ * so the cap can never silently become `NaN`/`Infinity`/negative. A `0`ms cap is
+ * rejected as meaningless (it would expire an attempt before it could run) —
+ * callers must omit `timeout` to disable the cap rather than passing `0` — and a
+ * value above {@link MAX_PER_ATTEMPT_TIMEOUT_MS} is rejected because it would
+ * overflow the underlying `setTimeout` and fire almost immediately.
+ */
+export declare function parsePerAttemptTimeoutMs(timeout: unknown): number | undefined;
+/**
+ * The first-dispatch anchor and parsed budget for a `ctx.run` call's
+ * `scheduleToCloseTimeout`, or `undefined` when no budget is configured.
+ */
+export type ScheduleToCloseBudget = {
+    budgetMs: number;
+    dispatchedAt: number;
+};
+/**
+ * Parse a `scheduleToCloseTimeout` duration to milliseconds, or `undefined` when
+ * unset. `parseDuration` validates the result is finite and non-negative on every
+ * input path (numeric and string, via `assertValidDurationMilliseconds`) and
+ * throws otherwise — so the budget can never silently become `NaN`/`Infinity`
+ * (which would make `elapsed >= budgetMs` always-false) or negative. `0` is valid
+ * (it permits exactly one attempt).
+ */
+export declare function parseScheduleToCloseBudgetMs(scheduleToCloseTimeout: Duration | undefined): number | undefined;
+/**
+ * Resolve the cross-attempt wall-clock budget for a `ctx.run` call: a per-call
+ * `scheduleToCloseTimeout` overrides the activity definition's default. String
+ * activities have no definition fields, so only the per-call option applies. The
+ * by-reference arm is `Function & { scheduleToCloseTimeout?: Duration }` to match
+ * the caller's `ActivityInput` (a callable carrying the activity definition); this
+ * resolver reads only the single `scheduleToCloseTimeout` field off it.
+ */
+export declare function resolveActivityScheduleToCloseTimeout(activity: string | (Function & {
+    scheduleToCloseTimeout?: Duration;
+}), options: ActivityCallOptions | undefined): Duration | undefined;
+/**
+ * Resolve the per-attempt `timeout` for a `ctx.run` call: a per-call `timeout`
+ * overrides the activity definition's default. String activities have no
+ * definition fields, so only the per-call option applies. Mirrors
+ * {@link resolveActivityScheduleToCloseTimeout} so the per-attempt cap honors a
+ * `timeout` declared on the activity definition, not just at the call site.
+ */
+export declare function resolveActivityTimeout(activity: string | (Function & {
+    timeout?: Duration;
+}), options: ActivityCallOptions | undefined): Duration | undefined;
+/**
+ * Whether the schedule-to-close budget is exhausted at the given clock value.
+ * The comparison is `>=` so an exact-deadline or zero-budget retry is treated as
+ * exhausted — a `0`ms budget allows exactly one attempt, then throws.
+ */
+export declare function isScheduleToCloseBudgetExhausted(budget: ScheduleToCloseBudget, now: number): boolean;
+/**
+ * Throw {@link ActivityScheduleToCloseTimeoutError} when the schedule-to-close
+ * budget bars the next attempt, otherwise return. Called two ways at the retry
+ * boundary, both routing through this single check; the thrown error always
+ * reports the ACTUAL elapsed time at `now`, never a projected one:
+ *
+ * - **Top of the retry loop** (`now = getNow()`, no `projectedNextDispatchClock`):
+ *   the live clock has reached or passed the deadline — an attempt overran, or
+ *   downtime during a backoff replay pushed wall time past it. Exhaustion is
+ *   checked at `now`; the error reports `now - dispatchedAt` and no projection.
+ * - **Catch branch** (`now = getNow()`, `projectedNextDispatchClock = now +
+ *   nextBackoff`, both from a single clock read): the budget may not have elapsed
+ *   yet, but the next backoff would start the retry at or after the deadline, so we
+ *   refuse to schedule that doomed sleep and fail at the retry decision point.
+ *   Exhaustion is checked at the PROJECTED dispatch clock; the error still reports
+ *   the actual `now - dispatchedAt` elapsed plus the projected next-dispatch
+ *   (as elapsed-since-first-dispatch ms) as the deciding reason.
+ *
+ * `budget` is `undefined` when no `scheduleToCloseTimeout` is configured, in which
+ * case this is a no-op.
+ */
+export declare function assertScheduleToCloseBudgetNotExhausted(budget: ScheduleToCloseBudget | undefined, activityName: string, now: number, projectedNextDispatchClock?: number): void;

package/dist/core/context/activity-schedule-to-close.js

@@ -0,0 +1,69 @@
+import { parseDuration } from "../scheduler.js";
+import { WeftError } from "../weft-error.js";
+
+export class ActivityScheduleToCloseTimeoutError extends WeftError {
+  activityName;
+  elapsed;
+  budget;
+  projectedNextDispatchElapsed;
+  constructor(activityName, elapsed, budget, projectedNextDispatchElapsed) {
+    super("ActivityScheduleToCloseTimeoutError", projectedNextDispatchElapsed === void 0 ? `Activity "${activityName}" exceeded its scheduleToCloseTimeout budget of ${budget}ms (elapsed ${elapsed}ms across retries)` : `Activity "${activityName}" will not retry within its scheduleToCloseTimeout budget of ${budget}ms (elapsed ${elapsed}ms; next retry would start at ${projectedNextDispatchElapsed}ms after first dispatch, at or beyond the deadline)`);
+    this.activityName = activityName;
+    this.elapsed = elapsed;
+    this.budget = budget;
+    if (projectedNextDispatchElapsed !== void 0)
+      this.projectedNextDispatchElapsed = projectedNextDispatchElapsed;
+  }
+}
+
+export class ActivityPerAttemptTimeoutError extends WeftError {
+  activityName;
+  attempt;
+  timeoutMs;
+  constructor(activityName, attempt, timeoutMs) {
+    super("ActivityPerAttemptTimeoutError", `Activity "${activityName}" attempt ${attempt} exceeded its per-attempt timeout of ${timeoutMs}ms`);
+    this.activityName = activityName;
+    this.attempt = attempt;
+    this.timeoutMs = timeoutMs;
+  }
+}
+export const MAX_PER_ATTEMPT_TIMEOUT_MS = 2147483647;
+export function parsePerAttemptTimeoutMs(timeout) {
+  if (timeout === void 0)
+    return;
+  if (typeof timeout !== "number" && typeof timeout !== "string")
+    throw Error(`Activity timeout must be a number or duration string when set (got ${typeof timeout}).`);
+  const ms = parseDuration(timeout);
+  if (ms <= 0)
+    throw Error(`Activity timeout must be greater than 0ms when set (got ${ms}ms); omit it to disable the per-attempt cap.`);
+  if (ms > MAX_PER_ATTEMPT_TIMEOUT_MS)
+    throw Error(`Activity timeout of ${ms}ms exceeds the maximum supported per-attempt cap of ${MAX_PER_ATTEMPT_TIMEOUT_MS}ms (~24.8 days).`);
+  return ms;
+}
+export function parseScheduleToCloseBudgetMs(scheduleToCloseTimeout) {
+  return scheduleToCloseTimeout === void 0 ? void 0 : parseDuration(scheduleToCloseTimeout);
+}
+export function resolveActivityScheduleToCloseTimeout(activity, options) {
+  if (options?.scheduleToCloseTimeout !== void 0)
+    return options.scheduleToCloseTimeout;
+  if (typeof activity === "string")
+    return;
+  return activity.scheduleToCloseTimeout;
+}
+export function resolveActivityTimeout(activity, options) {
+  if (options?.timeout !== void 0)
+    return options.timeout;
+  if (typeof activity === "string")
+    return;
+  return activity.timeout;
+}
+export function isScheduleToCloseBudgetExhausted(budget, now) {
+  return now - budget.dispatchedAt >= budget.budgetMs;
+}
+export function assertScheduleToCloseBudgetNotExhausted(budget, activityName, now, projectedNextDispatchClock) {
+  if (budget === void 0)
+    return;
+  if (!isScheduleToCloseBudgetExhausted(budget, projectedNextDispatchClock ?? now))
+    return;
+  throw new ActivityScheduleToCloseTimeoutError(activityName, now - budget.dispatchedAt, budget.budgetMs, projectedNextDispatchClock !== void 0 && now - budget.dispatchedAt < budget.budgetMs ? projectedNextDispatchClock - budget.dispatchedAt : void 0);
+}

package/dist/core/context/child-workflow-pipe.d.ts

@@ -1,18 +1,18 @@
-import type { ChildWorkflowOptions, ChildWorkflowTarget, WorkflowMapOptions, WorkflowPipeStage, WorkflowReduceInput, WorkflowReduceOptions } from '../types.ts';
+import type { AwaitChildWorkflowOptions, ChildWorkflowHandle, ChildWorkflowOptions, ChildWorkflowTarget, WorkflowMapOptions, WorkflowPipeStage, WorkflowReduceInput, WorkflowReduceOptions } from '../types.ts';
 import type { Context } from './index.ts';
 import type { ContextInternals } from './internals.ts';
 import type { ContextOperationRequest } from './operation-request.ts';
 export declare function normalizePipeStage(internals: ContextInternals, stage: WorkflowPipeStage | ChildWorkflowTarget): {
     workflowType: string;
-    options: ChildWorkflowOptions | undefined;
+    options: AwaitChildWorkflowOptions | undefined;
 };
 export declare function resolveChildWorkflowTarget<TInput = unknown, TOutput = unknown>(internals: ContextInternals, target: ChildWorkflowTarget<TInput, TOutput>): string;
 export declare function resolveMapConcurrency(totalItems: number, requestedConcurrency: number | undefined): number;
 export declare function createCompositionToken(internals: ContextInternals, kind: 'map' | 'pipe' | 'reduce'): string;
-export declare function createCompositionChildWorkflowOptions(internals: ContextInternals, token: string, index: number, options?: ChildWorkflowOptions | undefined): ChildWorkflowOptions;
-export declare function createReduceChildWorkflowOptions(internals: ContextInternals, token: string, index: number, options: WorkflowReduceOptions | undefined): ChildWorkflowOptions;
+export declare function createCompositionChildWorkflowOptions(internals: ContextInternals, token: string, index: number, options?: AwaitChildWorkflowOptions | undefined): AwaitChildWorkflowOptions;
+export declare function createReduceChildWorkflowOptions(internals: ContextInternals, token: string, index: number, options: WorkflowReduceOptions | undefined): AwaitChildWorkflowOptions;
 export declare function primeParallelOperations(operations: Generator<ContextOperationRequest, unknown, unknown>[]): ContextOperationRequest[];
-export declare function startChild<TResult = unknown>(context: Context, internals: ContextInternals, workflowType: string, input: unknown, options?: ChildWorkflowOptions): Generator<ContextOperationRequest, TResult, unknown>;
+export declare function startChild<TResult = unknown>(context: Context, internals: ContextInternals, workflowType: string, input: unknown, options?: ChildWorkflowOptions): Generator<ContextOperationRequest, TResult | ChildWorkflowHandle<TResult>, unknown>;
 export declare function pipe<TResult = unknown>(context: Context, internals: ContextInternals, stages: Array<WorkflowPipeStage | ChildWorkflowTarget>, input: unknown): Generator<ContextOperationRequest, TResult, unknown>;
 export declare function map<TItem, TResult>(context: Context, internals: ContextInternals, items: readonly TItem[], workflowType: ChildWorkflowTarget<TItem, TResult>, options?: WorkflowMapOptions): Generator<ContextOperationRequest, TResult[], unknown>;
 export declare function reduce<TItem, TAccumulator>(context: Context, internals: ContextInternals, items: readonly TItem[], workflowType: ChildWorkflowTarget<WorkflowReduceInput<TAccumulator, TItem>, TAccumulator>, initialValue: TAccumulator, options?: WorkflowReduceOptions): Generator<ContextOperationRequest, TAccumulator, unknown>;

package/dist/core/context/child-workflow-pipe.js

@@ -28,6 +28,7 @@ export function createCompositionToken(internals, kind) {
   return `${kind}:${internals.stepIndex}`;
 }
 export function createCompositionChildWorkflowOptions(internals, token, index, options = void 0) {
+  assertCompositionAwaitsChildWorkflow(options);
   if (options?.id !== void 0)
     return options;
   return {
@@ -39,11 +40,20 @@ export function createReduceChildWorkflowOptions(internals, token, index, option
   if (options === void 0)
     return createCompositionChildWorkflowOptions(internals, token, index);
   const { idPrefix, ...childWorkflowOptions } = options;
+  assertCompositionAwaitsChildWorkflow(childWorkflowOptions);
   return createCompositionChildWorkflowOptions(internals, token, index, idPrefix !== void 0 ? {
     ...childWorkflowOptions,
     id: `${idPrefix}:${index}`
   } : childWorkflowOptions);
 }
+function assertCompositionAwaitsChildWorkflow(options) {
+  if (typeof options !== "object" || options === null || !("parentClosePolicy" in options))
+    return;
+  const parentClosePolicy = options.parentClosePolicy;
+  if (parentClosePolicy === void 0 || parentClosePolicy === "await")
+    return;
+  throw Error('ctx.pipe, ctx.map, and ctx.reduce always await child workflow results. Use ctx.startChild() directly for parentClosePolicy: "abandon" or "request-cancel".');
+}
 export function primeParallelOperations(operations) {
   const subOperations = [];
   for (const generator of operations) {
@@ -58,7 +68,7 @@ export function* startChild(context, internals, workflowType, input, options) {
   if (internals.accumulatedResults?.has(step)) {
     if (internals.explainMode)
       console.log(`[weft] ctx.startChild("${workflowType}") \u2192 Returning cached result from step ${step}`);
-    return internals.accumulatedResults.get(step);
+    return resolveCachedStartChildResult(internals.accumulatedResults.get(step), options);
   }
   if (internals.explainMode) {
     console.log(`[weft] ctx.startChild("${workflowType}", ${JSON.stringify(input)})`);
@@ -74,7 +84,10 @@ export function* startChild(context, internals, workflowType, input, options) {
     ...options !== void 0 ? { options } : {}
   };
   context.accumulatedResults.set(step, result);
-  return result;
+  return resolveCachedStartChildResult(result, options);
+}
+function resolveCachedStartChildResult(result, options) {
+  return (options?.parentClosePolicy ?? "await") === "await" ? result : result;
 }
 export function* pipe(context, internals, stages, input) {
   const pipelineToken = createCompositionToken(internals, "pipe");

package/dist/core/context/context-presence.d.ts

@@ -0,0 +1,19 @@
+import type { Context } from './index.ts';
+/**
+ * Presence checks over a {@link Context}'s lazily-allocated internal maps. Each
+ * returns `true` only when the backing structure exists *and* is non-empty, so
+ * the checkpoint-commit and inline-parking paths can decide whether a context
+ * carries pending attribute changes, registered update handlers, or exposed
+ * accessors without forcing allocation through the public getters.
+ *
+ * Extracted from the `Context` class (which sits at the module line ceiling) as
+ * free functions; behavior is identical to the former `ctx.has*` getters.
+ *
+ * @module core/context/context-presence
+ */
+/** True when the context has at least one pending search-attribute change. */
+export declare function hasPendingAttributeChanges(context: Context): boolean;
+/** True when the context has at least one registered update handler. */
+export declare function hasUpdateHandlers(context: Context): boolean;
+/** True when the context has at least one exposed accessor. */
+export declare function hasExposedAccessors(context: Context): boolean;

package/dist/core/context/context-presence.js

@@ -0,0 +1,13 @@
+import { getInternals } from "./internals.js";
+export function hasPendingAttributeChanges(context) {
+  const pendingAttributeChanges = getInternals(context).pendingAttributeChanges;
+  return pendingAttributeChanges !== void 0 && Object.keys(pendingAttributeChanges).length > 0;
+}
+export function hasUpdateHandlers(context) {
+  const updateHandlers = getInternals(context).updateHandlers;
+  return updateHandlers !== void 0 && updateHandlers.size > 0;
+}
+export function hasExposedAccessors(context) {
+  const exposedValues = getInternals(context).exposedValues;
+  return exposedValues !== void 0 && exposedValues.size > 0;
+}

package/dist/core/context/durable-operations.d.ts

@@ -18,6 +18,31 @@ export declare function completePreparedSleepOperation(context: Context, prepare
 }>): Generator<ContextOperationRequest, void, unknown>;
 export declare function sleep(context: Context, internals: ContextInternals, duration: Duration): Generator<ContextOperationRequest, void, unknown>;
 export declare function waitForSignal<T = unknown>(context: Context, internals: ContextInternals, name: string): Generator<ContextOperationRequest, T, unknown>;
+/**
+ * Read the absolute deadline anchor for a `ctx.waitUntil` step, writing it on the
+ * first evaluation. Read-first so a crash/replay never resets the window: the
+ * timeout is measured from the original first yield, and the anchor lands in the
+ * checkpoint committed at that yield — the same atomicity the activity
+ * schedule-to-close anchor (`readOrInitActivityDispatchedAt`) relies on.
+ *
+ * Returns `undefined` when no timeout was supplied (wait forever).
+ */
+export declare function readOrInitConditionDeadline(internals: ContextInternals, step: number, timeout: Duration | undefined): number | undefined;
+/**
+ * Wait until `predicate` returns `true`, re-evaluated by the engine each time the
+ * workflow is driven forward (an `onUpdate` handler mutating state, or the
+ * optional timeout). The predicate is a non-serializable closure held in-process,
+ * never checkpointed. Once the wait outcome has been checkpointed, replay returns
+ * the cached outcome and does not re-invoke the predicate. A predicate that
+ * throws fails the workflow at the `yield*` call site (like a throwing activity).
+ * Inline execution only.
+ *
+ * With no `timeout` the generator yields `void` (waits forever). With a `timeout`
+ * it yields `true` when the predicate was met or `false` when the deadline
+ * elapsed first.
+ */
+export declare function waitUntil(context: Context, internals: ContextInternals, predicate: () => boolean, timeout?: Duration): Generator<ContextOperationRequest, boolean | void, unknown>;
+export declare function getVersion(_context: Context, internals: ContextInternals, changeId: string, minSupported: number, maxSupported: number): Generator<ContextOperationRequest, number, unknown>;
 export declare function waitForUpdate<T = unknown>(context: Context, internals: ContextInternals, name: string): Generator<ContextOperationRequest, {
     payload: T;
     respond: (result: unknown) => void;

package/dist/core/context/durable-operations.js

@@ -1,5 +1,6 @@
 import { parseDuration } from "../scheduler.js";
 import { captureCallerStack } from "./validation.js";
+import { resolveWorkflowVersionPatch } from "./version-patching.js";
 export function prepareSleepOperation(internals, duration) {
   const step = internals.stepIndex++;
   if (internals.accumulatedResults?.has(step))
@@ -53,6 +54,69 @@ export function* waitForSignal(context, internals, name) {
   context.accumulatedResults.set(step, result);
   return result;
 }
+const CONDITION_DEADLINE_LOCAL_PREFIX = "__weftConditionDeadline:";
+export function readOrInitConditionDeadline(internals, step, timeout) {
+  if (timeout === void 0)
+    return;
+  const localKey = `${CONDITION_DEADLINE_LOCAL_PREFIX}${step}`, existing = internals.checkpointLocals[localKey];
+  if (typeof existing === "number" && Number.isFinite(existing))
+    return existing;
+  if (existing !== void 0)
+    throw Error(`Invalid checkpointed wait-condition deadline ${JSON.stringify(existing)} for step ${step}`);
+  const milliseconds = parseDuration(timeout), referenceTime = internals.sleepReferenceTime ?? internals.getNow();
+  internals.sleepReferenceTime = void 0;
+  const deadline = referenceTime + milliseconds;
+  internals.checkpointLocals = { ...internals.checkpointLocals, [localKey]: deadline };
+  return deadline;
+}
+export function* waitUntil(context, internals, predicate, timeout) {
+  const step = internals.stepIndex++;
+  if (internals.accumulatedResults?.has(step))
+    return internals.accumulatedResults.get(step);
+  const deadline = readOrInitConditionDeadline(internals, step, timeout);
+  if (internals.explainMode) {
+    console.log("[weft] ctx.waitUntil(predicate)");
+    console.log(`  \u2192 Creating checkpoint at step ${step}`);
+    console.log(deadline === void 0 ? "  \u2192 Waiting indefinitely" : `  \u2192 Deadline at ${deadline}`);
+  }
+  const operationId = crypto.randomUUID(), callerStack = captureCallerStack(), result = yield {
+    type: "wait-condition",
+    operationId,
+    step,
+    predicate,
+    ...deadline !== void 0 && { deadline },
+    callerStack
+  };
+  context.accumulatedResults.set(step, result);
+  return result;
+}
+export function* getVersion(_context, internals, changeId, minSupported, maxSupported) {
+  const step = internals.stepIndex++, resolution = resolveWorkflowVersionPatch(internals.checkpointLocals, changeId, minSupported, maxSupported);
+  internals.checkpointLocals = resolution.checkpointLocals;
+  if (!resolution.newlyPinned)
+    return resolution.version;
+  if (internals.accumulatedResults?.has(step)) {
+    const cachedVersion = internals.accumulatedResults.get(step);
+    if (cachedVersion !== resolution.version)
+      throw Error(`ctx.getVersion("${changeId}") replay result ${String(cachedVersion)} does not match pinned version ${String(resolution.version)}`);
+    return resolution.version;
+  }
+  if (internals.explainMode) {
+    console.log(`[weft] ctx.getVersion("${changeId}", ${minSupported}, ${maxSupported})`);
+    console.log(`  \u2192 Creating checkpoint at step ${step}`);
+    console.log(`  \u2192 Pinning workflow patch "${changeId}" to version ${resolution.version}`);
+  }
+  const operationId = crypto.randomUUID(), callerStack = captureCallerStack();
+  return yield {
+    type: "get-version",
+    operationId,
+    changeId,
+    minSupported,
+    maxSupported,
+    version: resolution.version,
+    callerStack
+  };
+}
 export function* waitForUpdate(context, internals, name) {
   const step = internals.stepIndex++;
   if (internals.accumulatedResults?.has(step))

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

@@ -1,6 +1,6 @@
 import type { ComposedWorkflowInterceptor } from '../interceptor.ts';
 import type { HumanReviewOptions, HumanReviewResult } from '../review/index.ts';
-import type { ActivityCallable, ActivityCallOptions, ChildWorkflowOptions, ChildWorkflowTarget, Duration, QueryDefinition, RunAllResult, SearchAttributeHandle, SearchAttributeValue, SignalDefinition, UpdateDefinition, WorkflowContext, WorkflowMapOptions, WorkflowOperation, WorkflowOperationTupleResult, WorkflowPipeStageDefinition, WorkflowReduceInput, WorkflowReduceOptions, WorkflowRunAllBranch, WorkflowStateNamespace } from '../types.ts';
+import type { ActivityCallable, ActivityCallOptions, AwaitChildWorkflowOptions, ChildWorkflowHandle, ChildWorkflowTarget, DetachedChildWorkflowOptions, Duration, QueryDefinition, RunAllResult, SearchAttributeHandle, SearchAttributeValue, SignalDefinition, UpdateDefinition, WorkflowContext, WorkflowLogger, WorkflowMapOptions, WorkflowOperation, WorkflowOperationTupleResult, WorkflowPipeStageDefinition, WorkflowReduceInput, WorkflowReduceOptions, WorkflowRunAllBranch, WorkflowStateNamespace } from '../types.ts';
 import type { ContextOperationRequest } from './operation-request.ts';
 import type { ContextOptions, ErasedSagaStep, OffloadReference, StreamReference, StreamSink } from './types.ts';
 import * as contextUpdates from './updates.ts';
@@ -21,6 +21,7 @@ export declare function setContextWorkflowInterceptor(context: Context, workflow
  * ```
  */
 export declare class Context implements WorkflowContext {
+    #private;
     readonly workflowId: string;
     readonly workflowType: string;
     readonly startedAt: number;
@@ -28,6 +29,7 @@ export declare class Context implements WorkflowContext {
     constructor(options: ContextOptions);
     get executionTimeRemaining(): number;
     get services(): unknown;
+    get log(): WorkflowLogger;
     get stepIndex(): number;
     get nestingDepth(): number;
     get accumulatedResults(): Map<number, unknown>;
@@ -40,9 +42,6 @@ export declare class Context implements WorkflowContext {
     get explainEnabled(): boolean;
     get checkpointAccumulatedResults(): Array<[number, unknown]>;
     get checkpointPendingAttributeChanges(): Record<string, SearchAttributeValue> | undefined;
-    get hasPendingAttributeChanges(): boolean;
-    get hasUpdateHandlers(): boolean;
-    get hasExposedAccessors(): boolean;
     createSpeculativeChild(): Context;
     commitSpeculativeChild(child: Context): void;
     get state(): WorkflowStateNamespace;
@@ -55,6 +54,15 @@ export declare class Context implements WorkflowContext {
     run<TInput, TResult>(fn: ((input: TInput) => Promise<TResult> | TResult) & {
         execute?: never;
     }, input: TInput, options?: ActivityCallOptions): Generator<ContextOperationRequest, TResult, unknown>;
+    /**
+     * Durably sleep for `duration` before continuing. Unlike a wall-clock
+     * `setTimeout`, this is a checkpointed operation: the engine persists the timer
+     * and resumes the workflow when it fires, so a sleep survives process restarts
+     * and spans of days. On replay an already-elapsed sleep is a no-op — a
+     * recovered workflow does not wait again. `duration` is milliseconds
+     * (`number`) or a duration string (`'30s'`, `'1h'`, `'2d'` — see
+     * {@link Duration}); drive it with `yield*` from a workflow body.
+     */
     sleep(duration: Duration): Generator<ContextOperationRequest, void, unknown>;
     suspendUntil<T = unknown>(resumeToken: string): Generator<ContextOperationRequest, T, unknown>;
     waitForSignal<TInput>(definition: SignalDefinition<TInput>): Generator<ContextOperationRequest, TInput, unknown>;
@@ -67,6 +75,9 @@ export declare class Context implements WorkflowContext {
         payload: T;
         respond: (result: unknown) => void;
     }, unknown>;
+    waitUntil(predicate: () => boolean): Generator<ContextOperationRequest, void, unknown>;
+    waitUntil(p: () => boolean, t: Duration): Generator<ContextOperationRequest, boolean, unknown>;
+    getVersion(changeId: string, minSupported: number, maxSupported: number): Generator<ContextOperationRequest, number, unknown>;
     review(options: HumanReviewOptions): Generator<ContextOperationRequest, HumanReviewResult, unknown>;
     all<const TOperations extends readonly WorkflowOperation<unknown>[]>(operations: TOperations): Generator<ContextOperationRequest, WorkflowOperationTupleResult<TOperations>, unknown>;
     race<const TOperations extends readonly WorkflowOperation<unknown>[]>(operations: TOperations): Generator<ContextOperationRequest, WorkflowOperationTupleResult<TOperations>[number], unknown>;
@@ -77,7 +88,8 @@ export declare class Context implements WorkflowContext {
     archive(key: string, data: unknown): Generator<ContextOperationRequest, void, unknown>;
     runAll<const TBranches extends Record<string, WorkflowRunAllBranch>>(branches: TBranches): Generator<ContextOperationRequest, RunAllResult<TBranches>, unknown>;
     saga<TFinalOutput = unknown>(steps: ErasedSagaStep[]): Generator<ContextOperationRequest, TFinalOutput, unknown>;
-    startChild<TResult = unknown>(workflowType: string, input: unknown, options?: ChildWorkflowOptions): Generator<ContextOperationRequest, TResult, unknown>;
+    startChild<TResult = unknown>(workflowType: string, input: unknown, options: DetachedChildWorkflowOptions): Generator<ContextOperationRequest, ChildWorkflowHandle<TResult>, unknown>;
+    startChild<TResult = unknown>(workflowType: string, input: unknown, options?: AwaitChildWorkflowOptions): Generator<ContextOperationRequest, TResult, unknown>;
     pipe<TInput, TOutput>(stages: [WorkflowPipeStageDefinition<TInput, TOutput>], input: TInput): Generator<ContextOperationRequest, TOutput, unknown>;
     pipe<TInput, TIntermediate, TOutput>(stages: [
         WorkflowPipeStageDefinition<TInput, TIntermediate>,
@@ -111,5 +123,6 @@ export declare class Context implements WorkflowContext {
     onQuery(name: string, handler: (input: unknown) => unknown): void;
     expose(accessors: Record<string, () => unknown>): void;
     onCancel(handler: () => Promise<void> | void): void;
+    setFinalizerState(value: unknown): void;
     streamUrl(reference: StreamReference): string;
 }

package/dist/core/context/index.js

@@ -14,6 +14,7 @@ import {
 } from "./speculative-child.js";
 import * as stateNamespaceHelpers from "./state-namespace.js";
 import * as contextUpdates from "./updates.js";
+import { createInlineWorkflowLogger } from "./workflow-logger.js";
 export function setContextWorkflowInterceptor(context, workflowInterceptor) {
   getInternals(context).workflowInterceptor = workflowInterceptor;
 }
@@ -23,6 +24,7 @@ export class Context {
   workflowType;
   startedAt;
   signal;
+  #log;
   constructor(options) {
     this.workflowId = options.workflowId;
     this.workflowType = options.workflowType;
@@ -40,6 +42,9 @@ export class Context {
   get services() {
     return getInternals(this).services;
   }
+  get log() {
+    return this.#log ??= createInlineWorkflowLogger(this.workflowId, this.workflowType, () => getInternals(this), getInternals(this).logSink);
+  }
   get stepIndex() {
     return getInternals(this).stepIndex;
   }
@@ -90,18 +95,6 @@ export class Context {
     const pendingAttributeChanges = getInternals(this).pendingAttributeChanges;
     return pendingAttributeChanges ? { ...pendingAttributeChanges } : void 0;
   }
-  get hasPendingAttributeChanges() {
-    const pendingAttributeChanges = getInternals(this).pendingAttributeChanges;
-    return pendingAttributeChanges !== void 0 && Object.keys(pendingAttributeChanges).length > 0;
-  }
-  get hasUpdateHandlers() {
-    const updateHandlers = getInternals(this).updateHandlers;
-    return updateHandlers !== void 0 && updateHandlers.size > 0;
-  }
-  get hasExposedAccessors() {
-    const exposedValues = getInternals(this).exposedValues;
-    return exposedValues !== void 0 && exposedValues.size > 0;
-  }
   createSpeculativeChild() {
     return createSpeculativeChildState(this, (options) => new Context(options));
   }
@@ -146,6 +139,12 @@ export class Context {
   *waitForUpdate(nameOrDefinition) {
     return yield* durableOperations.waitForUpdate(this, getInternals(this), messageName(nameOrDefinition));
   }
+  *waitUntil(predicate, timeout) {
+    return yield* durableOperations.waitUntil(this, getInternals(this), predicate, timeout);
+  }
+  *getVersion(changeId, minSupported, maxSupported) {
+    return yield* durableOperations.getVersion(this, getInternals(this), changeId, minSupported, maxSupported);
+  }
   *review(options) {
     return yield* durableOperations.review(this, getInternals(this), options);
   }
@@ -221,6 +220,12 @@ export class Context {
       throw Error("ctx.onCancel() is only supported for inline workflow execution");
     internals.registerCancelHandler(handler);
   }
+  setFinalizerState(value) {
+    const internals = getInternals(this);
+    if (internals.recordFinalizerState === void 0)
+      throw Error("ctx.setFinalizerState() is only supported for inline workflow execution; it is unavailable in worker execution mode and inside ctx.speculate() branches.");
+    internals.recordFinalizerState(value);
+  }
   streamUrl(reference) {
     return `/v1/workflows/${encodeURIComponent(reference.workflowId)}/streams/${encodeURIComponent(reference.key)}`;
   }

package/dist/core/context/internals.d.ts

@@ -1,5 +1,6 @@
 import type { ComposedWorkflowInterceptor } from '../interceptor.ts';
 import type { SearchAttributeSchema, SearchAttributeValue } from '../types.ts';
+import type { WorkflowLogRecord } from '../types/workflow-log.ts';
 import type { Context, ContextOptions } from './index.ts';
 export interface ContextInternals {
     context: Context;
@@ -26,6 +27,34 @@ export interface ContextInternals {
     resolveWorkflowType: ((target: string | Function) => string) | undefined;
     registerCancelHandler: ((handler: () => Promise<void> | void) => () => void) | undefined;
     services: unknown;
+    /**
+     * Host sink for `ctx.log` records (`EngineOptions.onLog`), or `undefined` for the
+     * default console behavior. Captured by value when the `ctx.log` getter first
+     * builds its logger; `onLog` is fixed at engine construction, so there is nothing
+     * to re-read per emit.
+     */
+    logSink: ((record: WorkflowLogRecord) => void) | undefined;
+    /**
+     * Engine callback that durably records `ctx.setFinalizerState(value)` payloads
+     * (#446); `undefined` in speculative branches, where the branch reuses this
+     * inline {@link Context} but the engine leaves the callback unset, so
+     * `ctx.setFinalizerState` throws a descriptive guard error. (Worker-mode
+     * generators never reach this field at all — they receive a reduced worker-side
+     * context that does not carry `setFinalizerState`, so the call fails there with a
+     * `TypeError`.) Finalizer *registration* and teardown are unaffected — those run
+     * on the engine host in every mode (#564). Injected at context construction,
+     * mirroring {@link registerCancelHandler}.
+     */
+    recordFinalizerState: ((value: unknown) => void) | undefined;
 }
 export declare function initializeInternals(context: Context, options: ContextOptions, initialSessionState: Record<string, unknown> | undefined): void;
 export declare function getInternals(context: Context): ContextInternals;
+/**
+ * Non-throwing probe: is `value` a concrete {@link Context} with initialized
+ * internals? Used to distinguish the inline-mode `Context` (which carries the
+ * `stepIndex`/`accumulatedResults` replay machinery) from the minimal
+ * worker-mode `WorkerWorkflowContext`, which is a different shape. WeakMap
+ * `.has` accepts any object key and returns `false` for non-`Context` objects,
+ * so this is safe to call on any context-shaped value.
+ */
+export declare function hasContextInternals(value: object): value is Context;