@lostgradient/weft 0.3.0 → 0.5.0

package/dist/core/codec/extension-codec.d.ts

@@ -1,7 +1,23 @@
 import { ExtensionCodec } from '@msgpack/msgpack';
+import { WeftError } from '../weft-error.ts';
+declare const EXTENSION_TYPE_REGEXP = 2;
+export declare class RegExpExtensionDecodeError extends WeftError<'RegExpExtensionDecodeError'> {
+    readonly extensionType: typeof EXTENSION_TYPE_REGEXP;
+    readonly source: string;
+    readonly flags: string;
+    readonly sourceByteLength: number;
+    constructor(parameters: {
+        source: string;
+        flags: string;
+        sourceByteLength: number;
+        reason: string;
+        cause?: unknown;
+    });
+}
 export declare const extensionCodec: ExtensionCodec<undefined>;
 /**
  * Recursively replace `undefined` with the sentinel so msgpack's encoder
  * routes it through the extension codec instead of encoding it as null.
  */
 export declare function replaceUndefined(value: unknown, visited: Set<object>): unknown;
+export {};

package/dist/core/codec/extension-codec.js

@@ -5,8 +5,50 @@ import {
   decodeCodecDate,
   encodeCodecDate
 } from "../codec-helpers.js";
+import { WeftError } from "../weft-error.js";
 import { bindSerializerRegistryToCodec, hasRegisteredSerializer } from "./serializer-registry.js";
-const EXTENSION_TYPE_DATE = 1, EXTENSION_TYPE_REGEXP = 2, EXTENSION_TYPE_MAP = 3, EXTENSION_TYPE_SET = 4, EXTENSION_TYPE_UNDEFINED = 5, EXTENSION_TYPE_ERROR = 6;
+const EXTENSION_TYPE_DATE = 1, EXTENSION_TYPE_REGEXP = 2, EXTENSION_TYPE_MAP = 3, EXTENSION_TYPE_SET = 4, EXTENSION_TYPE_UNDEFINED = 5, EXTENSION_TYPE_ERROR = 6, REGEXP_SOURCE_MAX_BYTES = 65535, regexpSourceTextEncoder = new TextEncoder;
+
+export class RegExpExtensionDecodeError extends WeftError {
+  extensionType;
+  source;
+  flags;
+  sourceByteLength;
+  constructor(parameters) {
+    super("RegExpExtensionDecodeError", `RegExp extension type ${EXTENSION_TYPE_REGEXP} could not be decoded: source=${formatRegExpSourceForMessage(parameters.source, parameters.sourceByteLength)} flags=${JSON.stringify(parameters.flags)} ${parameters.reason}`, parameters.cause === void 0 ? void 0 : { cause: parameters.cause });
+    this.extensionType = EXTENSION_TYPE_REGEXP;
+    this.source = parameters.source;
+    this.flags = parameters.flags;
+    this.sourceByteLength = parameters.sourceByteLength;
+  }
+}
+function formatRegExpSourceForMessage(source, sourceByteLength) {
+  if (sourceByteLength <= 200)
+    return JSON.stringify(source);
+  return `${sourceByteLength}-byte string starting ${JSON.stringify(source.slice(0, 120))}`;
+}
+function decodeRegExpExtension(source, flags) {
+  const sourceByteLength = regexpSourceTextEncoder.encode(source).byteLength;
+  if (sourceByteLength > REGEXP_SOURCE_MAX_BYTES)
+    throw new RegExpExtensionDecodeError({
+      source,
+      flags,
+      sourceByteLength,
+      reason: `because source exceeds the ${REGEXP_SOURCE_MAX_BYTES}-byte limit.`
+    });
+  try {
+    return new RegExp(source, flags);
+  } catch (cause) {
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    throw new RegExpExtensionDecodeError({
+      source,
+      flags,
+      sourceByteLength,
+      reason: `because ${reason}`,
+      cause
+    });
+  }
+}
 export const extensionCodec = new ExtensionCodec;
 bindSerializerRegistryToCodec(extensionCodec, replaceUndefined);
 extensionCodec.register({
@@ -23,7 +65,7 @@ extensionCodec.register({
   },
   decode(data) {
     const decoded = coerceCodecRecord(msgpackDecode(data)), source = typeof decoded.source === "string" ? decoded.source : "", flags = typeof decoded.flags === "string" ? decoded.flags : "";
-    return new RegExp(source, flags);
+    return decodeRegExpExtension(source, flags);
   }
 });
 extensionCodec.register({
@@ -94,6 +136,11 @@ extensionCodec.register({
   }
 });
 export function replaceUndefined(value, visited) {
+  if (!containsUndefined(value, visited))
+    return value;
+  return replaceUndefinedDeep(value, new Set);
+}
+function replaceUndefinedDeep(value, visited) {
   if (value === void 0)
     return undefinedSentinel;
   if (value === null || typeof value !== "object")
@@ -121,19 +168,19 @@ function replaceObjectUndefined(value, visited) {
 function replaceArrayUndefined(value, visited) {
   const result = Array.from({ length: value.length });
   for (let index = 0;index < value.length; index++)
-    result[index] = replaceUndefined(value[index], visited);
+    result[index] = replaceUndefinedDeep(value[index], visited);
   return result;
 }
 function replaceMapUndefined(value, visited) {
   const result = new Map;
   for (const [key, mapValue] of value)
-    result.set(replaceUndefined(key, visited), replaceUndefined(mapValue, visited));
+    result.set(replaceUndefinedDeep(key, visited), replaceUndefinedDeep(mapValue, visited));
   return result;
 }
 function replaceSetUndefined(value, visited) {
   const result = new Set;
   for (const setValue of value)
-    result.add(replaceUndefined(setValue, visited));
+    result.add(replaceUndefinedDeep(setValue, visited));
   return result;
 }
 function isNestedValueFree(value) {
@@ -142,6 +189,53 @@ function isNestedValueFree(value) {
 function replaceRecordUndefined(value, visited) {
   const record = value, result = {};
   for (const key of Object.keys(record))
-    result[key] = replaceUndefined(record[key], visited);
+    result[key] = replaceUndefinedDeep(record[key], visited);
   return result;
 }
+function containsUndefined(value, visited) {
+  if (value === void 0)
+    return !0;
+  if (value === null || typeof value !== "object")
+    return !1;
+  if (visited.has(value))
+    return !1;
+  if (isNestedValueFree(value))
+    return !1;
+  visited.add(value);
+  try {
+    if (Array.isArray(value))
+      return arrayContainsUndefined(value, visited);
+    if (value instanceof Map)
+      return mapContainsUndefined(value, visited);
+    if (value instanceof Set)
+      return setContainsUndefined(value, visited);
+    return recordContainsUndefined(value, visited);
+  } finally {
+    visited.delete(value);
+  }
+}
+function arrayContainsUndefined(value, visited) {
+  for (let index = 0;index < value.length; index++)
+    if (containsUndefined(value[index], visited))
+      return !0;
+  return !1;
+}
+function mapContainsUndefined(value, visited) {
+  for (const [key, mapValue] of value)
+    if (containsUndefined(key, visited) || containsUndefined(mapValue, visited))
+      return !0;
+  return !1;
+}
+function setContainsUndefined(value, visited) {
+  for (const setValue of value)
+    if (containsUndefined(setValue, visited))
+      return !0;
+  return !1;
+}
+function recordContainsUndefined(value, visited) {
+  const record = value;
+  for (const key of Object.keys(record))
+    if (containsUndefined(record[key], visited))
+      return !0;
+  return !1;
+}

package/dist/core/context/activity-retry-state.d.ts

@@ -0,0 +1,38 @@
+import type { ContextInternals } from './internals.ts';
+/**
+ * Durable per-step retry bookkeeping for `ctx.run`, stored in the workflow's
+ * `checkpointLocals` so it survives crash/replay. One slot holds, per step: the
+ * current attempt number, how many backoff sleeps already completed, and the
+ * first-dispatch timestamp anchoring `scheduleToCloseTimeout`. Every mutator
+ * rebuilds the slot through {@link writeRetryStateSlot} so no sub-map is silently
+ * erased when another is updated.
+ */
+export declare const ACTIVITY_RETRY_STATE_LOCAL_KEY = "__weftActivityRetryState";
+declare const ACTIVITY_RETRY_STATE_VERSION = 1;
+export declare const MAX_CHECKPOINTED_RETRY_ATTEMPT = 10000;
+export interface ActivityRetryState {
+    version: typeof ACTIVITY_RETRY_STATE_VERSION;
+    attempts: Record<string, number>;
+    completedRetrySleeps?: Record<string, number>;
+    /**
+     * First-dispatch engine-clock timestamp per step, the anchor for
+     * `scheduleToCloseTimeout`. Written ONCE on the first dispatch of a step and
+     * never overwritten, so the wall-clock budget is measured from the original
+     * dispatch even across crash/replay. Like `completedRetrySleeps`, it must be
+     * preserved whenever the retry-state slot is rebuilt.
+     */
+    dispatchedAt?: Record<string, number>;
+}
+export declare function isActivityRetryState(value: unknown): value is ActivityRetryState;
+export declare function readActivityRetryAttempt(internals: ContextInternals, step: number): number | undefined;
+export declare function readCompletedRetrySleepCount(internals: ContextInternals, step: number): number;
+export declare function writeActivityRetryAttempt(internals: ContextInternals, step: number, attempt: number): void;
+export declare function completeActivityRetryAttempt(internals: ContextInternals, step: number, completedRetrySleepCount: number): void;
+/**
+ * Read the first-dispatch anchor for a step's `scheduleToCloseTimeout`, writing
+ * `now` on the first dispatch. Read-first so a crash/replay never resets the
+ * window: the budget is measured from the original dispatch, and the anchor
+ * lands in the checkpoint committed at the dispatch `yield` that follows.
+ */
+export declare function readOrInitActivityDispatchedAt(internals: ContextInternals, step: number, now: number): number;
+export {};

package/dist/core/context/activity-retry-state.js

@@ -0,0 +1,89 @@
+export const ACTIVITY_RETRY_STATE_LOCAL_KEY = "__weftActivityRetryState";
+const ACTIVITY_RETRY_STATE_VERSION = 1;
+export const MAX_CHECKPOINTED_RETRY_ATTEMPT = 1e4;
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function isActivityRetryState(value) {
+  return isRecord(value) && value.version === ACTIVITY_RETRY_STATE_VERSION && isRecord(value.attempts) && (value.completedRetrySleeps === void 0 || isRecord(value.completedRetrySleeps)) && (value.dispatchedAt === void 0 || isRecord(value.dispatchedAt));
+}
+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)}`);
+}
+export 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;
+}
+export 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 currentRetryState(internals) {
+  const current = internals.checkpointLocals[ACTIVITY_RETRY_STATE_LOCAL_KEY];
+  return isActivityRetryState(current) ? current : void 0;
+}
+function writeRetryStateSlot(internals, attempts, completedRetrySleeps, dispatchedAt) {
+  const { [ACTIVITY_RETRY_STATE_LOCAL_KEY]: _removed, ...remainingLocals } = internals.checkpointLocals, hasAttempts = Object.keys(attempts).length > 0, hasSleeps = completedRetrySleeps !== void 0 && Object.keys(completedRetrySleeps).length > 0, hasDispatched = dispatchedAt !== void 0 && Object.keys(dispatchedAt).length > 0;
+  if (!hasAttempts && !hasSleeps && !hasDispatched) {
+    internals.checkpointLocals = remainingLocals;
+    return;
+  }
+  internals.checkpointLocals = {
+    ...remainingLocals,
+    [ACTIVITY_RETRY_STATE_LOCAL_KEY]: {
+      version: ACTIVITY_RETRY_STATE_VERSION,
+      attempts,
+      ...hasSleeps ? { completedRetrySleeps } : {},
+      ...hasDispatched ? { dispatchedAt } : {}
+    }
+  };
+}
+export function writeActivityRetryAttempt(internals, step, attempt) {
+  assertValidRetryAttempt(attempt, step);
+  const current = currentRetryState(internals), attempts = current ? { ...current.attempts } : {};
+  attempts[String(step)] = attempt;
+  writeRetryStateSlot(internals, attempts, current?.completedRetrySleeps, current?.dispatchedAt);
+}
+function clearActivityRetryAttempt(internals, step) {
+  const current = currentRetryState(internals);
+  if (!current)
+    return;
+  const attempts = { ...current.attempts };
+  delete attempts[String(step)];
+  writeRetryStateSlot(internals, attempts, current.completedRetrySleeps, current.dispatchedAt);
+}
+export 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 = currentRetryState(internals), attempts = current ? { ...current.attempts } : {}, completedRetrySleeps = current ? { ...current.completedRetrySleeps } : {};
+  completedRetrySleeps[String(step)] = completedRetrySleepCount;
+  writeRetryStateSlot(internals, attempts, completedRetrySleeps, current?.dispatchedAt);
+}
+export function readOrInitActivityDispatchedAt(internals, step, now) {
+  const current = currentRetryState(internals), existing = current?.dispatchedAt?.[String(step)];
+  if (typeof existing === "number" && Number.isFinite(existing))
+    return existing;
+  if (existing !== void 0)
+    throw Error(`Invalid checkpointed activity dispatch anchor ${String(existing)} for step ${String(step)}`);
+  const attempts = current ? { ...current.attempts } : {}, dispatchedAt = current?.dispatchedAt ? { ...current.dispatchedAt } : {};
+  dispatchedAt[String(step)] = now;
+  writeRetryStateSlot(internals, attempts, current?.completedRetrySleeps, dispatchedAt);
+  return now;
+}

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;
+}