@lostgradient/weft 0.2.1 → 0.4.0

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);
 }
@@ -35,3 +37,6 @@ export function getInternals(context) {
     throw Error("Context internals not initialized");
   return internals;
 }
+export function hasContextInternals(value) {
+  return INTERNALS.has(value);
+}

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,6 +1,20 @@
-import { type RetryPolicy } 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';
+/**
+ * Recover the concrete {@link Context} from the public {@link WorkflowContext}
+ * the engine passes to a workflow handler. Under the inline execution strategy
+ * the engine invokes a handler with the concrete `Context` instance (carrying
+ * the `stepIndex`/`accumulatedResults` replay machinery). Worker execution mode
+ * instead drives the handler with a minimal `WorkerWorkflowContext`, which has
+ * no replay internals — so infrastructure such as `compileStepWorkflow` cannot
+ * drive the durable activity machinery there. This probes for the inline
+ * internals (via the `hasContextInternals` type guard, which narrows without a
+ * cast) and throws an actionable error rather than the cryptic
+ * "Context internals not initialized" from a downstream `getInternals` call.
+ */
+export declare function asConcreteContext(context: WorkflowContext): Context;
 type ActivityInput = string | (Function & {
     retry?: RetryPolicy;
 });
@@ -14,8 +28,12 @@ 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[]): RunActivityRequest<TResult>;
-export declare function runActivityWithRetry<TResult>(context: Context, activity: ActivityInput, rest: readonly unknown[]): Generator<ContextOperationRequest, TResult, unknown>;
+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>;
 export {};

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

@@ -1,9 +1,28 @@
 import { calculateBackoff } from "../scheduler.js";
-import { DEFAULT_RETRY_POLICY } from "../types.js";
-import { getInternals } from "./internals.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";
-const ACTIVITY_RETRY_STATE_LOCAL_KEY = "__weftActivityRetryState", ACTIVITY_RETRY_STATE_VERSION = 1, MAX_CHECKPOINTED_RETRY_ATTEMPT = 1e4;
+export function asConcreteContext(context) {
+  if (!hasContextInternals(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;
+}
 function acceptsNoActivityInput(fn) {
   if (typeof fn !== "function")
     return !1;
@@ -22,89 +41,19 @@ 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) {
+function getActivityName(activity, explicitName) {
+  if (explicitName !== void 0)
+    return explicitName;
   return typeof activity === "string" ? activity : activity.name || "anonymous";
 }
 function getActivityFunction(activity) {
@@ -190,31 +139,42 @@ function prepareActivityRetryRequest(request, attempt) {
     attempt
   };
 }
-export function createRunActivityRequest(context, activity, rest) {
-  const { input, options } = parseRunArguments(activity, rest), activityName = getActivityName(activity), activityFunction = getActivityFunction(activity), internals = getInternals(context), step = internals.stepIndex++, cachedRequest = getCachedRunActivityRequest(internals, step, activityName, input);
+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) {
-  const { request, step, hasCachedResult, cachedResult, retryAttempt, retryPolicy } = createRunActivityRequest(context, activity, rest);
+export function* runActivityWithRetry(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);
@@ -223,9 +183,12 @@ export function* runActivityWithRetry(context, activity, rest) {
     } 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;

package/dist/core/context/version-patching.js

@@ -0,0 +1,40 @@
+export const WORKFLOW_VERSION_LOCAL_PREFIX = "version:";
+export function resolveWorkflowVersionPatch(checkpointLocals, changeId, minSupported, maxSupported) {
+  validateWorkflowVersionPatchArguments(changeId, minSupported, maxSupported);
+  const localKey = `${WORKFLOW_VERSION_LOCAL_PREFIX}${changeId}`, existing = checkpointLocals[localKey];
+  if (existing === void 0)
+    return {
+      localKey,
+      version: maxSupported,
+      newlyPinned: !0,
+      checkpointLocals: { ...checkpointLocals, [localKey]: maxSupported }
+    };
+  if (typeof existing !== "number" || !Number.isSafeInteger(existing))
+    throw Error(`Invalid checkpointed workflow version patch "${changeId}" value ${JSON.stringify(existing)}`);
+  const version = existing;
+  assertPinnedVersionSupported(changeId, version, minSupported, maxSupported);
+  return {
+    localKey,
+    version,
+    newlyPinned: !1,
+    checkpointLocals
+  };
+}
+function validateWorkflowVersionPatchArguments(changeId, minSupported, maxSupported) {
+  if (typeof changeId !== "string" || changeId.length === 0)
+    throw Error("ctx.getVersion() requires a non-empty changeId");
+  assertVersionBoundary("minSupported", minSupported);
+  assertVersionBoundary("maxSupported", maxSupported);
+  if (minSupported > maxSupported)
+    throw Error("ctx.getVersion() minSupported must be less than or equal to maxSupported");
+}
+function assertVersionBoundary(name, value) {
+  if (!Number.isSafeInteger(value))
+    throw Error(`ctx.getVersion() ${name} must be a safe integer`);
+}
+function assertPinnedVersionSupported(changeId, version, minSupported, maxSupported) {
+  if (version < minSupported)
+    throw Error(`Workflow version patch "${changeId}" is pinned to version ${version}, below the minimum supported version ${minSupported}`);
+  if (version > maxSupported)
+    throw Error(`Workflow version patch "${changeId}" is pinned to version ${version}, above the maximum supported version ${maxSupported}`);
+}

package/dist/core/context/workflow-logger.d.ts

@@ -0,0 +1,98 @@
+import type { WorkflowLogger, WorkflowLogRecord } from '../types/workflow-log.ts';
+import type { ContextInternals } from './internals.ts';
+/**
+ * Dispatch one record to the matching `console` method (`debug`/`info`/`warn`/`error`).
+ * The single console-fallback primitive: the logger factory uses it when no sink is
+ * installed or a sink throws, and the worker-log host-delivery path (#529) uses it when
+ * the host `onLog` sink throws — so console-fallback behavior cannot drift between the
+ * inline and worker-forwarded paths.
+ */
+export declare function logRecordToConsole(record: WorkflowLogRecord): void;
+/**
+ * Inputs the logger needs at construction. The replay/clock probes (`isReplaying`,
+ * `now`) are evaluated fresh per emit so they track the live frontier; the identity
+ * fields (`workflowId`, `workflowType`) and the `sink` are fixed values.
+ */
+export interface WorkflowLoggerBindings {
+    readonly workflowId: string;
+    readonly workflowType: string;
+    /**
+     * Whether the current execution position is a replay of an already-committed
+     * step. Evaluated lazily at each emit call so it reflects the live frontier.
+     */
+    isReplaying(): boolean;
+    /** Wall-clock millisecond timestamp for the record (never checkpointed). */
+    now(): number;
+    /**
+     * Optional host sink (`EngineOptions.onLog`). When provided, each non-replayed
+     * record is routed here INSTEAD of the console — the host owns where logs go
+     * (pino / winston / OpenTelemetry / etc.). When absent, records fall back to the
+     * matching `console` method, preserving the default behavior. `onLog` is fixed at
+     * engine construction (it has no public setter), so this is a captured value, not
+     * a per-emit resolver.
+     */
+    readonly sink?: (record: WorkflowLogRecord) => void;
+}
+/**
+ * Create a {@link WorkflowLogger} from the given bindings. Each method suppresses
+ * emission when `bindings.isReplaying()` is true (so a recovered run does not
+ * re-emit logs from the replayed prefix). A non-replayed record is routed to the
+ * host sink (`bindings.sink`) when one is installed, and otherwise to the matching
+ * `console` method — so a host that wires `EngineOptions.onLog` takes full control
+ * of log routing without duplicate console noise, while the default stays console.
+ *
+ * A logger must never be able to crash the thing it is logging: if the host sink
+ * throws (a serialization error, a transport failure, a bug in the callback — all
+ * realistic for the pino / winston / OpenTelemetry integrations this targets), the
+ * throw is swallowed and the record falls back to `console` so the workflow run is
+ * not marked failed by a logging error.
+ */
+export declare function createWorkflowLogger(bindings: WorkflowLoggerBindings): WorkflowLogger;
+/**
+ * Build the inline `ctx.log` logger for a {@link Context}. The replay probe reads
+ * the RAW nullable `internals.accumulatedResults` field (not the allocating
+ * `ctx.accumulatedResults` getter) and the live `internals.stepIndex` without
+ * incrementing it — `ctx.log` consumes no durable position, the same step-neutral
+ * peek `waitForSignal` makes. `getInternals` is read per emit so the probe tracks
+ * the frontier as durable ops advance `stepIndex`. The `sink` is captured by value:
+ * `EngineOptions.onLog` is fixed at engine construction, so it never changes for the
+ * life of the context.
+ */
+export declare function createInlineWorkflowLogger(workflowId: string, workflowType: string, getInternals: () => Pick<ContextInternals, 'accumulatedResults' | 'stepIndex' | 'getNow'>, sink?: (record: WorkflowLogRecord) => void): WorkflowLogger;
+/**
+ * The slice of worker replay state the worker logger's replay probe reads. A step
+ * being replayed is cached in `accumulatedResults` (it succeeded) OR in
+ * `failedOutcomes` (it failed and the failure is replayed) — the logger must check
+ * both, mirroring the runner's own `hasCachedWorkerOutcome`, or a log at a
+ * replayed *failure* position would re-emit on recovery.
+ */
+export interface WorkerLoggerReplayState {
+    readonly accumulatedResults: ReadonlyMap<number, unknown>;
+    readonly failedOutcomes: ReadonlyMap<number, unknown>;
+    readonly nextStepIndex: number;
+}
+/**
+ * Build the worker-side `ctx.log` logger. Mirrors {@link createInlineWorkflowLogger}
+ * through the shared factory; only the replay probe differs. `nextStepIndex` points
+ * at the step the worker generator is about to run, so a cached outcome at that
+ * index (success in `accumulatedResults` or failure in `failedOutcomes`) means the
+ * step is replaying and its preceding log is suppressed; an uncached index is the
+ * live frontier — the same per-position check the inline path makes (and the same
+ * union the runner's own replay short-circuit uses). The state is read through
+ * `getReplayState` (not captured by value) because the worker registers its replay
+ * state *after* the context is built, so the closure must observe the live state at
+ * emit time. Worker records use wall-clock `Date.now()` (the worker has no engine
+ * clock); the timestamp is observability metadata only, never checkpointed.
+ *
+ * When the engine host installs an `EngineOptions.onLog` sink, the run/resume message
+ * reports `hostHasLogSink: true` and the worker supplies a `forwardToHost` callback
+ * here (#529): each non-replayed record is posted back to the host as a `log`
+ * protocol message INSTEAD of the worker console, mirroring the inline sink. The
+ * callback runs through the shared factory's `sink` slot, so its existing
+ * throw-then-console fallback applies — if forwarding is impossible (an oversized or
+ * non-cloneable record makes `postMessage` throw), the record falls back to the
+ * worker console rather than failing the run. When no host sink exists, `forwardToHost`
+ * is omitted and the worker logs to its own console, preserving the default and never
+ * losing a log to a no-op host callback.
+ */
+export declare function createWorkerWorkflowLogger(workflowId: string, workflowType: string, getReplayState: () => WorkerLoggerReplayState | undefined, forwardToHost?: (record: WorkflowLogRecord) => void): WorkflowLogger;

package/dist/core/context/workflow-logger.js

@@ -0,0 +1,68 @@
+const CONSOLE_METHOD = {
+  debug: "debug",
+  info: "info",
+  warn: "warn",
+  error: "error"
+};
+export function logRecordToConsole(record) {
+  console[CONSOLE_METHOD[record.level]](record);
+}
+function buildLogRecord(bindings, level, message, attributes) {
+  return {
+    level,
+    message,
+    workflowId: bindings.workflowId,
+    workflowType: bindings.workflowType,
+    timestamp: bindings.now(),
+    ...attributes !== void 0 && { attributes }
+  };
+}
+export function createWorkflowLogger(bindings) {
+  const emit = (level, message, attributes) => {
+    if (bindings.isReplaying())
+      return;
+    const record = buildLogRecord(bindings, level, message, attributes);
+    if (bindings.sink !== void 0) {
+      try {
+        bindings.sink(record);
+      } catch {
+        logRecordToConsole(record);
+      }
+      return;
+    }
+    logRecordToConsole(record);
+  };
+  return {
+    debug: (message, attributes) => emit("debug", message, attributes),
+    info: (message, attributes) => emit("info", message, attributes),
+    warn: (message, attributes) => emit("warn", message, attributes),
+    error: (message, attributes) => emit("error", message, attributes)
+  };
+}
+export function createInlineWorkflowLogger(workflowId, workflowType, getInternals, sink) {
+  return createWorkflowLogger({
+    workflowId,
+    workflowType,
+    isReplaying: () => {
+      const internals = getInternals();
+      return internals.accumulatedResults?.has(internals.stepIndex) ?? !1;
+    },
+    now: () => getInternals().getNow(),
+    ...sink !== void 0 && { sink }
+  });
+}
+export function createWorkerWorkflowLogger(workflowId, workflowType, getReplayState, forwardToHost) {
+  return createWorkflowLogger({
+    workflowId,
+    workflowType,
+    isReplaying: () => {
+      const replayState = getReplayState();
+      if (replayState === void 0)
+        return !1;
+      const step = replayState.nextStepIndex;
+      return replayState.accumulatedResults.has(step) || replayState.failedOutcomes.has(step);
+    },
+    now: () => Date.now(),
+    ...forwardToHost !== void 0 && { sink: forwardToHost }
+  });
+}