@lostgradient/weft 0.3.0 → 0.5.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;
@@ -76,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>;
@@ -86,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>,
@@ -120,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,25 @@ 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;

package/dist/core/context/internals.js

@@ -25,7 +25,9 @@ export function initializeInternals(context, options, initialSessionState) {
     executionStateOwnerId: options.executionStateOwnerId ?? options.workflowId,
     resolveWorkflowType: options.resolveWorkflowType,
     registerCancelHandler: options.registerCancelHandler,
-    services: options.services
+    services: options.services,
+    logSink: options.logSink,
+    recordFinalizerState: options.recordFinalizerState
   };
   INTERNALS.set(context, internals);
 }

package/dist/core/context/operation-request.d.ts

@@ -58,6 +58,41 @@ export type ContextOperationRequest = {
     operationId: string;
     updateName: string;
     callerStack?: string;
+} | {
+    type: 'wait-condition';
+    operationId: string;
+    /**
+     * Deterministic workflow step index for this `ctx.waitUntil` call. Stable
+     * across replay (unlike `operationId`, which is regenerated each yield), so
+     * it anchors both the deterministic deadline timer key
+     * (`cond:${workflowId}:${step}`) and the in-process condition waiter to a
+     * fixed step. Re-using a regenerated `operationId` would arm duplicate
+     * durable timers on recovery.
+     */
+    step: number;
+    /**
+     * The condition predicate. A non-serializable closure (like `memo.fn`) held
+     * in-process by the engine processor and re-evaluated on every wake; it is
+     * never checkpointed. The workflow re-yields a fresh request after each
+     * replay, so the engine always has a live closure to call. Must be pure and
+     * read only checkpoint-restored workflow-local state.
+     */
+    predicate: () => boolean;
+    /**
+     * Absolute deadline (epoch millis) after which the wait completes with
+     * `false`. Anchored once via `readOrInitConditionDeadline` so crash/replay
+     * never resets the window. Absent means "wait forever".
+     */
+    deadline?: number;
+    callerStack?: string;
+} | {
+    type: 'get-version';
+    operationId: string;
+    changeId: string;
+    minSupported: number;
+    maxSupported: number;
+    version: number;
+    callerStack?: string;
 } | {
     type: 'parallel';
     operationId: string;

package/dist/core/context/parallel-cache-entry.d.ts

@@ -66,6 +66,15 @@ export type ParallelOperationCacheEntry = {
  * key list for `ctx.runAll`) differs from the cached entry on retry.
  * Indicates non-deterministic workflow code — branches must be stable
  * across retries.
+ *
+ * @example
+ * ```ts
+ * import { BranchTopologyChangedError } from '@lostgradient/weft';
+ *
+ * function isBranchTopologyChange(error: unknown): boolean {
+ *   return error instanceof BranchTopologyChangedError;
+ * }
+ * ```
  */
 export declare class BranchTopologyChangedError extends WeftError<'BranchTopologyChangedError'> {
     constructor(message: string);
@@ -80,11 +89,11 @@ export declare function isParallelOperationCacheEntry(value: unknown): value is
  * replay behavior.
  *
  * NOT an `asserts` predicate: a value without the marker is also a
- * valid input here (it just means the cache slot held a non-parallel
- * legacy value). Callers still narrow via `isParallelOperationCacheEntry`
- * after calling this — using `asserts` would over-narrow plain
- * non-parallel cached values and mark the legacy fallback paths
- * (`return cached as unknown[]`) as dead code in TypeScript.
+ * valid input here (it means the cache slot held a plain cached value).
+ * Callers still narrow via `isParallelOperationCacheEntry` after calling
+ * this. Using `asserts` would over-narrow plain non-parallel cached
+ * values and mark the current plain-value return path as dead code in
+ * TypeScript.
  */
 export declare function assertValidParallelOperationCacheEntry(value: unknown): void;
 /** Build a fresh v2 cache entry with the given branch slots. */

package/dist/core/context/run-operation.d.ts

@@ -1,4 +1,5 @@
-import { type RetryPolicy, type WorkflowContext } from '../types.ts';
+import { type Duration, type RetryPolicy, type WorkflowContext } from '../types.ts';
+import { completeActivityRetryAttempt, readActivityRetryAttempt, readCompletedRetrySleepCount } from './activity-retry-state.ts';
 import type { Context } from './index.ts';
 import type { ContextOperationRequest } from './operation-request.ts';
 /**
@@ -27,7 +28,11 @@ interface RunActivityRequest<TResult> {
     cachedResult?: TResult;
     retryAttempt: number;
     retryPolicy?: RetryPolicy;
+    scheduleToCloseTimeout?: Duration;
 }
+export declare const readActivityRetryAttemptForTesting: typeof readActivityRetryAttempt;
+export declare const readCompletedRetrySleepCountForTesting: typeof readCompletedRetrySleepCount;
+export declare const completeActivityRetryAttemptForTesting: typeof completeActivityRetryAttempt;
 export declare function shouldRetryActivityError(error: unknown, policy: RetryPolicy | undefined, attempt: number): policy is RetryPolicy;
 export declare function createRunActivityRequest<TResult>(context: Context, activity: ActivityInput, rest: readonly unknown[], explicitName?: string): RunActivityRequest<TResult>;
 export declare function runActivityWithRetry<TResult>(context: Context, activity: ActivityInput, rest: readonly unknown[], explicitName?: string): Generator<ContextOperationRequest, TResult, unknown>;

package/dist/core/context/run-operation.js

@@ -2,6 +2,19 @@ import { calculateBackoff } from "../scheduler.js";
 import {
   DEFAULT_RETRY_POLICY
 } from "../types.js";
+import {
+  completeActivityRetryAttempt,
+  readActivityRetryAttempt,
+  readCompletedRetrySleepCount,
+  readOrInitActivityDispatchedAt,
+  writeActivityRetryAttempt
+} from "./activity-retry-state.js";
+import {
+  assertScheduleToCloseBudgetNotExhausted,
+  parseScheduleToCloseBudgetMs,
+  resolveActivityScheduleToCloseTimeout,
+  resolveActivityTimeout
+} from "./activity-schedule-to-close.js";
 import { getInternals, hasContextInternals } from "./internals.js";
 import { isActivityCallOptions } from "./session-state.js";
 import { captureCallerStack } from "./validation.js";
@@ -10,7 +23,6 @@ export function asConcreteContext(context) {
     throw Error("Step-based workflows (compileStepWorkflow / ctx.step) require workflowExecutionMode: 'inline'. The worker execution strategy runs workflows with a different context that has no durable step machinery. Use the generator workflow API for worker execution mode.");
   return context;
 }
-const ACTIVITY_RETRY_STATE_LOCAL_KEY = "__weftActivityRetryState", ACTIVITY_RETRY_STATE_VERSION = 1, MAX_CHECKPOINTED_RETRY_ATTEMPT = 1e4;
 function acceptsNoActivityInput(fn) {
   if (typeof fn !== "function")
     return !1;
@@ -29,86 +41,14 @@ function parseRunArguments(activity, rest) {
     throw Error("ctx.run() accepts one activity input value plus optional ActivityCallOptions.");
   return { input: values[0], options };
 }
-function isRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function isActivityRetryState(value) {
-  return isRecord(value) && value.version === ACTIVITY_RETRY_STATE_VERSION && isRecord(value.attempts) && (value.completedRetrySleeps === void 0 || isRecord(value.completedRetrySleeps));
-}
-function assertValidRetryAttempt(attempt, step) {
-  if (!Number.isInteger(attempt) || attempt <= 1 || attempt > MAX_CHECKPOINTED_RETRY_ATTEMPT)
-    throw Error(`Invalid checkpointed activity retry attempt ${String(attempt)} for step ${String(step)}`);
-}
-function readActivityRetryAttempt(internals, step) {
-  const state = internals.checkpointLocals[ACTIVITY_RETRY_STATE_LOCAL_KEY];
-  if (!isActivityRetryState(state))
-    return;
-  const attempt = state.attempts[String(step)];
-  if (attempt === void 0)
-    return;
-  assertValidRetryAttempt(attempt, step);
-  return attempt;
-}
-function readCompletedRetrySleepCount(internals, step) {
-  const state = internals.checkpointLocals[ACTIVITY_RETRY_STATE_LOCAL_KEY];
-  if (!isActivityRetryState(state))
-    return 0;
-  const count = state.completedRetrySleeps?.[String(step)];
-  if (count === void 0)
-    return 0;
-  if (!Number.isInteger(count) || count < 0 || count > MAX_CHECKPOINTED_RETRY_ATTEMPT)
-    throw Error(`Invalid checkpointed activity retry sleep count ${String(count)} for step ${String(step)}`);
-  return count;
-}
-function writeActivityRetryAttempt(internals, step, attempt) {
-  assertValidRetryAttempt(attempt, step);
-  const current = internals.checkpointLocals[ACTIVITY_RETRY_STATE_LOCAL_KEY], attempts = isActivityRetryState(current) ? { ...current.attempts } : {};
-  attempts[String(step)] = attempt;
-  const completedRetrySleeps = isActivityRetryState(current) ? current.completedRetrySleeps : void 0;
-  internals.checkpointLocals = {
-    ...internals.checkpointLocals,
-    [ACTIVITY_RETRY_STATE_LOCAL_KEY]: {
-      version: ACTIVITY_RETRY_STATE_VERSION,
-      attempts,
-      ...completedRetrySleeps === void 0 ? {} : { completedRetrySleeps }
-    }
-  };
-}
-function clearActivityRetryAttempt(internals, step) {
-  const current = internals.checkpointLocals[ACTIVITY_RETRY_STATE_LOCAL_KEY];
-  if (!isActivityRetryState(current))
+export const readActivityRetryAttemptForTesting = readActivityRetryAttempt, readCompletedRetrySleepCountForTesting = readCompletedRetrySleepCount, completeActivityRetryAttemptForTesting = completeActivityRetryAttempt;
+function resolveScheduleToCloseBudget(internals, step, scheduleToCloseTimeout) {
+  const budgetMs = parseScheduleToCloseBudgetMs(scheduleToCloseTimeout);
+  if (budgetMs === void 0)
     return;
-  const attempts = { ...current.attempts };
-  delete attempts[String(step)];
-  const completedRetrySleeps = current.completedRetrySleeps, { [ACTIVITY_RETRY_STATE_LOCAL_KEY]: _removed, ...remainingLocals } = internals.checkpointLocals;
-  if (Object.keys(attempts).length === 0 && completedRetrySleeps === void 0) {
-    internals.checkpointLocals = remainingLocals;
-    return;
-  }
-  internals.checkpointLocals = {
-    ...remainingLocals,
-    [ACTIVITY_RETRY_STATE_LOCAL_KEY]: {
-      version: ACTIVITY_RETRY_STATE_VERSION,
-      attempts,
-      ...completedRetrySleeps === void 0 ? {} : { completedRetrySleeps }
-    }
-  };
-}
-function completeActivityRetryAttempt(internals, step, completedRetrySleepCount) {
-  if (!Number.isInteger(completedRetrySleepCount) || completedRetrySleepCount < 0 || completedRetrySleepCount > MAX_CHECKPOINTED_RETRY_ATTEMPT)
-    throw Error(`Invalid completed activity retry sleep count ${String(completedRetrySleepCount)} for step ${String(step)}`);
-  clearActivityRetryAttempt(internals, step);
-  if (completedRetrySleepCount === 0)
-    return;
-  const current = internals.checkpointLocals[ACTIVITY_RETRY_STATE_LOCAL_KEY], attempts = isActivityRetryState(current) ? { ...current.attempts } : {}, completedRetrySleeps = isActivityRetryState(current) ? { ...current.completedRetrySleeps } : {};
-  completedRetrySleeps[String(step)] = completedRetrySleepCount;
-  internals.checkpointLocals = {
-    ...internals.checkpointLocals,
-    [ACTIVITY_RETRY_STATE_LOCAL_KEY]: {
-      version: ACTIVITY_RETRY_STATE_VERSION,
-      attempts,
-      completedRetrySleeps
-    }
+  return {
+    budgetMs,
+    dispatchedAt: readOrInitActivityDispatchedAt(internals, step, internals.getNow())
   };
 }
 function getActivityName(activity, explicitName) {
@@ -203,27 +143,38 @@ export function createRunActivityRequest(context, activity, rest, explicitName)
   const { input, options } = parseRunArguments(activity, rest), activityName = getActivityName(activity, explicitName), activityFunction = getActivityFunction(activity), internals = getInternals(context), step = internals.stepIndex++, cachedRequest = getCachedRunActivityRequest(internals, step, activityName, input);
   if (cachedRequest.hasCachedResult)
     return cachedRequest;
-  const retryPolicy = resolveActivityRetryPolicy(activity, options);
+  const retryPolicy = resolveActivityRetryPolicy(activity, options), scheduleToCloseTimeout = resolveActivityScheduleToCloseTimeout(activity, options), effectiveTimeout = resolveActivityTimeout(activity, options), dispatchedOptions = effectiveTimeout === void 0 ? options : { ...options, timeout: effectiveTimeout };
   return {
-    request: createFreshRunActivityRequest(internals, step, activityName, activityFunction, input, options),
+    request: createFreshRunActivityRequest(internals, step, activityName, activityFunction, input, dispatchedOptions),
     step,
     hasCachedResult: !1,
     retryAttempt: cachedRequest.retryAttempt,
-    ...retryPolicy === void 0 ? {} : { retryPolicy }
+    ...retryPolicy === void 0 ? {} : { retryPolicy },
+    ...scheduleToCloseTimeout === void 0 ? {} : { scheduleToCloseTimeout }
   };
 }
 export function* runActivityWithRetry(context, activity, rest, explicitName) {
-  const { request, step, hasCachedResult, cachedResult, retryAttempt, retryPolicy } = createRunActivityRequest(context, activity, rest, explicitName);
+  const {
+    request,
+    step,
+    hasCachedResult,
+    cachedResult,
+    retryAttempt,
+    retryPolicy,
+    scheduleToCloseTimeout
+  } = createRunActivityRequest(context, activity, rest, explicitName);
   if (hasCachedResult)
     return cachedResult;
-  const internals = getInternals(context);
+  const internals = getInternals(context), budget = retryPolicy === void 0 ? void 0 : resolveScheduleToCloseBudget(internals, step, scheduleToCloseTimeout);
   let attempt = retryAttempt;
   if (attempt > 1) {
     if (retryPolicy === void 0)
       throw Error(`Missing activity retry policy for checkpointed retry attempt ${attempt}`);
     yield* context.sleep(calculateBackoff(attempt - 1, retryPolicy));
   }
-  while (!0)
+  while (!0) {
+    if (attempt > 1)
+      assertScheduleToCloseBudgetNotExhausted(budget, request.activityName, internals.getNow());
     try {
       const result = yield prepareActivityRetryRequest(request, attempt);
       context.accumulatedResults.set(step, result);
@@ -232,9 +183,12 @@ export function* runActivityWithRetry(context, activity, rest, explicitName) {
     } catch (error) {
       if (!shouldRetryActivityError(error, retryPolicy, attempt))
         throw error;
+      const backoff = calculateBackoff(attempt, retryPolicy), now = internals.getNow();
+      assertScheduleToCloseBudgetNotExhausted(budget, request.activityName, now, now + backoff);
       const nextAttempt = attempt + 1;
       writeActivityRetryAttempt(internals, step, nextAttempt);
-      yield* context.sleep(calculateBackoff(attempt, retryPolicy));
+      yield* context.sleep(backoff);
       attempt = nextAttempt;
     }
+  }
 }

package/dist/core/context/session-state.js

@@ -4,23 +4,24 @@ import {
   cloneSessionStateValue,
   createSessionStateStore,
   hasSessionStateKey,
-  LEGACY_SESSION_STATE_LOCAL_KEY,
   SESSION_STATE_LOCAL_KEY,
   validateSessionStateStore
 } from "../session-state.js";
-const EMPTY_CHECKPOINT_LOCALS = Object.freeze({}), ACTIVITY_CALL_OPTION_KEYS = new Set([
+const EMPTY_CHECKPOINT_LOCALS = Object.freeze({}), RETIRED_SESSION_STATE_LOCAL_KEY = "sessionState", ACTIVITY_CALL_OPTION_KEYS = new Set([
   "timeout",
   "queue",
   "retry",
   "idempotencyKey",
   "sticky",
-  "visibilityTimeout"
+  "visibilityTimeout",
+  "scheduleToCloseTimeout"
 ]), DISCRIMINATOR_KEYS = new Set([
   "queue",
   "retry",
   "idempotencyKey",
   "sticky",
-  "visibilityTimeout"
+  "visibilityTimeout",
+  "scheduleToCloseTimeout"
 ]);
 export function isActivityCallOptions(value) {
   if (value === null || typeof value !== "object" || Array.isArray(value))
@@ -37,7 +38,7 @@ export function isActivityCallOptions(value) {
   return !1;
 }
 export function createCheckpointLocals(stateSessionStore, existingLocals) {
-  const localEntries = existingLocals === void 0 ? [] : Object.entries(existingLocals).filter(([key]) => key !== SESSION_STATE_LOCAL_KEY && key !== LEGACY_SESSION_STATE_LOCAL_KEY);
+  const localEntries = existingLocals === void 0 ? [] : Object.entries(existingLocals).filter(([key]) => key !== SESSION_STATE_LOCAL_KEY && key !== RETIRED_SESSION_STATE_LOCAL_KEY);
   if (stateSessionStore === void 0) {
     if (localEntries.length === 0)
       return EMPTY_CHECKPOINT_LOCALS;
@@ -73,9 +74,7 @@ export function clearSessionStateValue(internals, key) {
   assertValidSessionStateKey(key);
   if (!internals.stateSession || !hasSessionStateKey(internals.stateSession, key))
     return;
-  const candidate = cloneSessionStateStore(internals.stateSession);
-  if (!candidate)
-    return;
+  const candidate = cloneSessionStateStore(internals.stateSession) ?? createSessionStateStore();
   delete candidate[key];
   commitSessionStateStore(internals, Object.keys(candidate).length === 0 ? void 0 : candidate);
 }

package/dist/core/context/speculative-child.js

@@ -18,6 +18,8 @@ function assignOptionalContextOptions(options, internals) {
     options.resolveWorkflowType = internals.resolveWorkflowType;
   if (internals.services !== void 0)
     options.services = internals.services;
+  if (internals.logSink !== void 0)
+    options.logSink = internals.logSink;
 }
 function createSpeculativeChildOptions(parent, internals) {
   const options = {

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

@@ -1,4 +1,5 @@
 import type { ActivityDefinition, SearchAttributeSchema, SearchAttributeValue } from '../types.ts';
+import type { WorkflowLogRecord } from '../types/workflow-log.ts';
 /**
  * A single step in a saga: an activity definition and the input to pass to it.
  *
@@ -184,4 +185,18 @@ export interface ContextOptions {
      * engine's `resolveWorkflowServices` resolver.
      */
     services?: unknown;
+    /**
+     * Host sink for `ctx.log` records (`EngineOptions.onLog`). When set, non-replayed
+     * records route here instead of the console; when absent, the default console
+     * behavior is preserved. Never checkpointed.
+     */
+    logSink?: (record: WorkflowLogRecord) => void;
+    /**
+     * Called by `ctx.setFinalizerState(value)` (#446) to durably record the payload
+     * the engine passes to the workflow's `finalizer` activity on cancel/timeout
+     * teardown. The engine stages it as a pending atomic side-effect so it commits
+     * with the next checkpoint or the terminal batch. Absent for worker-mode and
+     * speculative contexts, where `ctx.setFinalizerState` is unsupported.
+     */
+    recordFinalizerState?: (value: unknown) => void;
 }

package/dist/core/context/version-patching.d.ts

@@ -0,0 +1,8 @@
+export declare const WORKFLOW_VERSION_LOCAL_PREFIX = "version:";
+export type WorkflowVersionPatchResolution = {
+    localKey: string;
+    version: number;
+    newlyPinned: boolean;
+    checkpointLocals: Record<string, unknown>;
+};
+export declare function resolveWorkflowVersionPatch(checkpointLocals: Record<string, unknown>, changeId: string, minSupported: number, maxSupported: number): WorkflowVersionPatchResolution;