@lostgradient/weft 0.6.0 → 0.8.0

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

@@ -0,0 +1,79 @@
+import { WeftError } from "../weft-error.js";
+import { captureCallerStack } from "./validation.js";
+
+export class DurableActivityScopeError extends WeftError {
+  constructor(message) {
+    super("DurableActivityScopeError", message);
+  }
+}
+
+export class DurableActivityUnsupportedError extends WeftError {
+  constructor(message) {
+    super("DurableActivityUnsupportedError", message);
+  }
+}
+let durableActivityScopeStorage;
+const fallbackDurableActivityScopes = [], AMBIGUOUS_FALLBACK_DURABLE_ACTIVITY_SCOPE = Symbol("AMBIGUOUS_FALLBACK_DURABLE_ACTIVITY_SCOPE");
+function loadAsyncLocalStorageConstructor() {
+  const getBuiltinModule = ("process" in globalThis ? globalThis.process : void 0)?.getBuiltinModule;
+  if (typeof getBuiltinModule !== "function")
+    return;
+  return getBuiltinModule("node:async_hooks")?.AsyncLocalStorage;
+}
+function getDurableActivityScopeStorage() {
+  if (durableActivityScopeStorage !== void 0)
+    return durableActivityScopeStorage;
+  const AsyncLocalStorage = loadAsyncLocalStorageConstructor();
+  durableActivityScopeStorage = AsyncLocalStorage === void 0 ? null : new AsyncLocalStorage;
+  return durableActivityScopeStorage;
+}
+function currentDurableActivityScope() {
+  const storage = getDurableActivityScopeStorage();
+  if (storage !== null)
+    return storage.getStore();
+  if (fallbackDurableActivityScopes.length > 1)
+    return AMBIGUOUS_FALLBACK_DURABLE_ACTIVITY_SCOPE;
+  return fallbackDurableActivityScopes.at(-1);
+}
+export function runWithDurableActivityScope(scope, execute) {
+  const storage = getDurableActivityScopeStorage();
+  if (storage === null)
+    return runWithFallbackDurableActivityScope(scope, execute);
+  return storage.run(scope, execute);
+}
+function runWithFallbackDurableActivityScope(scope, execute) {
+  fallbackDurableActivityScopes.push(scope);
+  let result;
+  try {
+    result = execute();
+  } catch (error) {
+    removeFallbackDurableActivityScope(scope);
+    throw error;
+  }
+  if (hasFinally(result))
+    return result.finally(() => removeFallbackDurableActivityScope(scope));
+  removeFallbackDurableActivityScope(scope);
+  return result;
+}
+function removeFallbackDurableActivityScope(scope) {
+  const index = fallbackDurableActivityScopes.lastIndexOf(scope);
+  if (index >= 0)
+    fallbackDurableActivityScopes.splice(index, 1);
+}
+function hasFinally(value) {
+  if (typeof value !== "object" && typeof value !== "function" || value === null)
+    return !1;
+  return "finally" in value && typeof value.finally === "function";
+}
+export function durableActivity(activity, ...activityArguments) {
+  const scope = currentDurableActivityScope();
+  if (scope === AMBIGUOUS_FALLBACK_DURABLE_ACTIVITY_SCOPE)
+    return Promise.reject(new DurableActivityScopeError("durableActivity() cannot resolve a unique ctx.memo() scope because AsyncLocalStorage is unavailable and multiple memo callbacks are active. Run this workflow in a runtime with AsyncLocalStorage support."));
+  if (scope === void 0)
+    return Promise.reject(new DurableActivityScopeError("durableActivity() can only be called from a ctx.memo() callback during inline workflow activation. Use yield* ctx.run() in generator workflow code outside that memo helper boundary."));
+  return scope.dispatch({
+    activity,
+    arguments: activityArguments,
+    callerStack: captureCallerStack()
+  });
+}

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

@@ -40,6 +40,14 @@ export type ContextOperationRequest = {
      * anchors the durable async-completion task token to a fixed activity.
      */
     step?: number;
+    /**
+     * Optional deterministic state key for activity sub-operations that are
+     * owned by another workflow step. Plain `ctx.run()` leaves this unset and
+     * uses `step`; memo-scoped helper activities set it to a key derived from
+     * the owning memo step, memo key, and helper-call ordinal so retry and
+     * heartbeat state cannot collide with the parent memo step.
+     */
+    activityStateKey?: string;
     /** Serialized interceptor headers (Map entries) for remote worker propagation. */
     headers?: [string, string][];
 } | {
@@ -122,6 +130,13 @@ export type ContextOperationRequest = {
     type: 'memo';
     operationId: string;
     key: string;
+    /**
+     * Workflow step index for the owning `ctx.memo()` call. Plain async
+     * helper activity calls derive sub-operation identity from this parent
+     * step, the memo key, and their call ordinal without consuming the
+     * workflow's outer step index.
+     */
+    step?: number;
     fn: () => unknown;
     callerStack?: string;
 } | {

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

@@ -139,6 +139,7 @@ export function* memo(context, internals, key, fn) {
     type: "memo",
     operationId,
     key,
+    step,
     fn,
     callerStack
   };

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

@@ -0,0 +1,8 @@
+import { type ActivityRetryStateKey } from './activity-retry-state.ts';
+import type { ContextInternals } from './internals.ts';
+import type { RunActivityRequest } from './run-operation.ts';
+type CachedRunActivityRequestConfiguration = {
+    advanceStepIndexForCachedRetryState: boolean;
+};
+export declare function getCachedRunActivityRequest<TResult>(internals: ContextInternals, step: number, retryStateKey: ActivityRetryStateKey, cacheResultStep: number | undefined, activityName: string, input: unknown, configuration: CachedRunActivityRequestConfiguration): RunActivityRequest<TResult>;
+export {};

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

@@ -0,0 +1,59 @@
+import {
+  readActivityRetryAttempt,
+  readCompletedRetrySleepCount
+} from "./activity-retry-state.js";
+export function getCachedRunActivityRequest(internals, step, retryStateKey, cacheResultStep, activityName, input, configuration) {
+  const cachedResultState = readCachedResultState(internals, cacheResultStep);
+  if (cachedResultState.hasCachedResult)
+    return createCachedResultRequest(internals, step, retryStateKey, cacheResultStep, activityName, input, cachedResultState.cachedResult, configuration);
+  const retryAttempt = readActivityRetryAttempt(internals, retryStateKey);
+  if (retryAttempt !== void 0)
+    return createRetryStateRequest(internals, step, retryStateKey, cacheResultStep, activityName, input, retryAttempt, configuration);
+  return {
+    ...createBaseRequest(step, retryStateKey, cacheResultStep, activityName, input),
+    hasCachedResult: !1,
+    retryAttempt: 1
+  };
+}
+function readCachedResultState(internals, cacheResultStep) {
+  if (cacheResultStep === void 0)
+    return { hasCachedResult: !1 };
+  if (internals.accumulatedResults?.has(cacheResultStep) !== !0)
+    return { hasCachedResult: !1 };
+  return {
+    cachedResult: internals.accumulatedResults.get(cacheResultStep),
+    hasCachedResult: !0
+  };
+}
+function createCachedResultRequest(internals, step, retryStateKey, cacheResultStep, activityName, input, cachedResult, configuration) {
+  if (configuration.advanceStepIndexForCachedRetryState)
+    internals.stepIndex += readCompletedRetrySleepCount(internals, retryStateKey);
+  if (internals.explainMode)
+    console.log(`[weft] ctx.run(${activityName}) \u2192 Returning cached result from step ${step}`);
+  return {
+    ...createBaseRequest(step, retryStateKey, cacheResultStep, activityName, input),
+    cachedResult,
+    hasCachedResult: !0,
+    retryAttempt: 1
+  };
+}
+function createRetryStateRequest(internals, step, retryStateKey, cacheResultStep, activityName, input, retryAttempt, configuration) {
+  if (configuration.advanceStepIndexForCachedRetryState)
+    internals.stepIndex += retryAttempt - 2;
+  return {
+    ...createBaseRequest(step, retryStateKey, cacheResultStep, activityName, input),
+    hasCachedResult: !1,
+    retryAttempt
+  };
+}
+function createBaseRequest(step, retryStateKey, cacheResultStep, activityName, input) {
+  return {
+    request: createReplayActivityOperation(activityName, input),
+    step,
+    retryStateKey,
+    ...cacheResultStep === void 0 ? {} : { cacheResultStep }
+  };
+}
+function createReplayActivityOperation(activityName, input) {
+  return { type: "activity", operationId: "", activityName, input };
+}

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

@@ -1,6 +1,8 @@
 import { type Duration, type RetryPolicy, type WorkflowContext } from '../types.ts';
-import { completeActivityRetryAttempt, readActivityRetryAttempt, readCompletedRetrySleepCount } from './activity-retry-state.ts';
+import { completeActivityRetryAttempt, readActivityRetryAttempt, readCompletedRetrySleepCount, type ActivityRetryStateKey } from './activity-retry-state.ts';
+import { type ScheduleToCloseBudget } from './activity-schedule-to-close.ts';
 import type { Context } from './index.ts';
+import { type ContextInternals } from './internals.ts';
 import type { ContextOperationRequest } from './operation-request.ts';
 /**
  * Recover the concrete {@link Context} from the public {@link WorkflowContext}
@@ -15,25 +17,41 @@ import type { ContextOperationRequest } from './operation-request.ts';
  * "Context internals not initialized" from a downstream `getInternals` call.
  */
 export declare function asConcreteContext(context: WorkflowContext): Context;
-type ActivityInput = string | (Function & {
+export type ActivityInput = string | (Function & {
     retry?: RetryPolicy;
 });
-type ActivityOperationRequest = Extract<ContextOperationRequest, {
+export type ActivityOperationRequest = Extract<ContextOperationRequest, {
     type: 'activity';
 }>;
-interface RunActivityRequest<TResult> {
+export interface RunActivityRequest<TResult> {
     request: ActivityOperationRequest;
     step: number;
+    retryStateKey: ActivityRetryStateKey;
+    cacheResultStep?: number;
     hasCachedResult: boolean;
     cachedResult?: TResult;
     retryAttempt: number;
     retryPolicy?: RetryPolicy;
     scheduleToCloseTimeout?: Duration;
 }
+export type ActivityRetrySleepGenerator = (duration: number, nextAttempt: number) => Generator<ContextOperationRequest, void, unknown>;
+export interface RunActivityAtStepConfiguration {
+    explicitName?: string;
+    advanceStepIndexForCachedRetryState?: boolean;
+    retryStateKey?: ActivityRetryStateKey;
+    cacheResultStep?: number | false;
+    activityStateKey?: string;
+    retrySleep?: ActivityRetrySleepGenerator;
+}
 export declare const readActivityRetryAttemptForTesting: typeof readActivityRetryAttempt;
 export declare const readCompletedRetrySleepCountForTesting: typeof readCompletedRetrySleepCount;
 export declare const completeActivityRetryAttemptForTesting: typeof completeActivityRetryAttempt;
+export declare function readOrInitActivityRetrySleepFireAt(context: Context, operationId: string, duration: number): number;
+/** Parse the schedule-to-close budget and anchor it to the step's first dispatch. */
+export declare function resolveScheduleToCloseBudget(internals: ContextInternals, retryStateKey: ActivityRetryStateKey, scheduleToCloseTimeout: Duration | undefined): ScheduleToCloseBudget | undefined;
 export declare function shouldRetryActivityError(error: unknown, policy: RetryPolicy | undefined, attempt: number): policy is RetryPolicy;
+export declare function prepareActivityRetryRequest(request: ActivityOperationRequest, attempt: number): ActivityOperationRequest;
 export declare function createRunActivityRequest<TResult>(context: Context, activity: ActivityInput, rest: readonly unknown[], explicitName?: string): RunActivityRequest<TResult>;
+export declare function createRunActivityRequestAtStep<TResult>(context: Context, activity: ActivityInput, rest: readonly unknown[], step: number, configuration?: RunActivityAtStepConfiguration): RunActivityRequest<TResult>;
 export declare function runActivityWithRetry<TResult>(context: Context, activity: ActivityInput, rest: readonly unknown[], explicitName?: string): Generator<ContextOperationRequest, TResult, unknown>;
-export {};
+export declare function runActivityWithRetryAtStep<TResult>(context: Context, activity: ActivityInput, rest: readonly unknown[], step: number, configuration?: RunActivityAtStepConfiguration): Generator<ContextOperationRequest, TResult, unknown>;

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

@@ -16,6 +16,7 @@ import {
   resolveActivityTimeout
 } from "./activity-schedule-to-close.js";
 import { getInternals, hasContextInternals } from "./internals.js";
+import { getCachedRunActivityRequest } from "./run-operation-cached-request.js";
 import { isActivityCallOptions } from "./session-state.js";
 import { captureCallerStack } from "./validation.js";
 export function asConcreteContext(context) {
@@ -42,13 +43,27 @@ function parseRunArguments(activity, rest) {
   return { input: values[0], options };
 }
 export const readActivityRetryAttemptForTesting = readActivityRetryAttempt, readCompletedRetrySleepCountForTesting = readCompletedRetrySleepCount, completeActivityRetryAttemptForTesting = completeActivityRetryAttempt;
-function resolveScheduleToCloseBudget(internals, step, scheduleToCloseTimeout) {
+const ACTIVITY_RETRY_SLEEP_DEADLINE_LOCAL_PREFIX = "__weftActivityRetrySleepDeadline:";
+export function readOrInitActivityRetrySleepFireAt(context, operationId, duration) {
+  const internals = getInternals(context), localKey = `${ACTIVITY_RETRY_SLEEP_DEADLINE_LOCAL_PREFIX}${operationId}`, existing = internals.checkpointLocals[localKey];
+  if (typeof existing === "number" && Number.isFinite(existing))
+    return existing;
+  if (existing !== void 0)
+    throw Error(`Invalid checkpointed activity retry sleep deadline ${JSON.stringify(existing)} for "${operationId}".`);
+  const scheduledFireAt = internals.getNow() + duration;
+  internals.checkpointLocals = {
+    ...internals.checkpointLocals,
+    [localKey]: scheduledFireAt
+  };
+  return scheduledFireAt;
+}
+export function resolveScheduleToCloseBudget(internals, retryStateKey, scheduleToCloseTimeout) {
   const budgetMs = parseScheduleToCloseBudgetMs(scheduleToCloseTimeout);
   if (budgetMs === void 0)
     return;
   return {
     budgetMs,
-    dispatchedAt: readOrInitActivityDispatchedAt(internals, step, internals.getNow())
+    dispatchedAt: readOrInitActivityDispatchedAt(internals, retryStateKey, internals.getNow())
   };
 }
 function getActivityName(activity, explicitName) {
@@ -59,39 +74,7 @@ function getActivityName(activity, explicitName) {
 function getActivityFunction(activity) {
   return typeof activity === "function" ? activity : void 0;
 }
-function getCachedRunActivityRequest(internals, step, activityName, input) {
-  const hasCachedResult = internals.accumulatedResults?.has(step) ?? !1;
-  if (hasCachedResult) {
-    const cachedResult = internals.accumulatedResults?.get(step);
-    internals.stepIndex += readCompletedRetrySleepCount(internals, step);
-    if (internals.explainMode)
-      console.log(`[weft] ctx.run(${activityName}) \u2192 Returning cached result from step ${step}`);
-    return {
-      request: { type: "activity", operationId: "", activityName, input },
-      step,
-      hasCachedResult,
-      cachedResult,
-      retryAttempt: 1
-    };
-  }
-  const retryAttempt = readActivityRetryAttempt(internals, step);
-  if (retryAttempt !== void 0) {
-    internals.stepIndex += retryAttempt - 2;
-    return {
-      request: { type: "activity", operationId: "", activityName, input },
-      step,
-      hasCachedResult: !1,
-      retryAttempt
-    };
-  }
-  return {
-    request: { type: "activity", operationId: "", activityName, input },
-    step,
-    hasCachedResult,
-    retryAttempt: 1
-  };
-}
-function createFreshRunActivityRequest(internals, step, activityName, activityFunction, input, options) {
+function createFreshRunActivityRequest(internals, step, activityName, activityFunction, input, options, activityStateKey) {
   const queue = options?.queue ?? "default";
   if (internals.explainMode) {
     console.log(`[weft] ctx.run(${activityName}, ${JSON.stringify(input)})`);
@@ -103,6 +86,7 @@ function createFreshRunActivityRequest(internals, step, activityName, activityFu
     operationId: crypto.randomUUID(),
     activityName,
     step,
+    ...activityStateKey === void 0 ? {} : { activityStateKey },
     ...activityFunction !== void 0 ? { fn: activityFunction } : {},
     input,
     callerStack: captureCallerStack(),
@@ -130,7 +114,7 @@ function isNonRetryableActivityError(error, policy) {
 export function shouldRetryActivityError(error, policy, attempt) {
   return policy !== void 0 && attempt < policy.maxAttempts && !isNonRetryableActivityError(error, policy);
 }
-function prepareActivityRetryRequest(request, attempt) {
+export function prepareActivityRetryRequest(request, attempt) {
   if (attempt === 1)
     return request;
   return {
@@ -140,45 +124,76 @@ function prepareActivityRetryRequest(request, attempt) {
   };
 }
 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);
+  parseRunArguments(activity, rest);
+  const internals = getInternals(context), step = internals.stepIndex++;
+  return createRunActivityRequestAtStep(context, activity, rest, step, {
+    ...explicitName === void 0 ? {} : { explicitName },
+    advanceStepIndexForCachedRetryState: !0,
+    retryStateKey: step,
+    cacheResultStep: step
+  });
+}
+export function createRunActivityRequestAtStep(context, activity, rest, step, configuration = {}) {
+  const { input, options } = parseRunArguments(activity, rest), activityName = getActivityName(activity, configuration.explicitName), activityFunction = getActivityFunction(activity), internals = getInternals(context), retryStateKey = configuration.retryStateKey ?? step, cacheResultStep = configuration.cacheResultStep === !1 ? void 0 : configuration.cacheResultStep ?? step, cachedRequest = getCachedRunActivityRequest(internals, step, retryStateKey, cacheResultStep, activityName, input, {
+    advanceStepIndexForCachedRetryState: configuration.advanceStepIndexForCachedRetryState ?? !1
+  });
   if (cachedRequest.hasCachedResult)
     return cachedRequest;
-  const retryPolicy = resolveActivityRetryPolicy(activity, options), scheduleToCloseTimeout = resolveActivityScheduleToCloseTimeout(activity, options), effectiveTimeout = resolveActivityTimeout(activity, options), dispatchedOptions = effectiveTimeout === void 0 ? options : { ...options, timeout: effectiveTimeout };
+  const retryPolicy = resolveActivityRetryPolicy(activity, options), scheduleToCloseTimeout = resolveActivityScheduleToCloseTimeout(activity, options);
   return {
-    request: createFreshRunActivityRequest(internals, step, activityName, activityFunction, input, dispatchedOptions),
+    request: createFreshRunActivityRequest(internals, step, activityName, activityFunction, input, resolveDispatchedActivityOptions(activity, options), configuration.activityStateKey),
     step,
+    retryStateKey,
+    ...cacheResultStep === void 0 ? {} : { cacheResultStep },
     hasCachedResult: !1,
     retryAttempt: cachedRequest.retryAttempt,
     ...retryPolicy === void 0 ? {} : { retryPolicy },
     ...scheduleToCloseTimeout === void 0 ? {} : { scheduleToCloseTimeout }
   };
 }
+function resolveDispatchedActivityOptions(activity, options) {
+  const effectiveTimeout = resolveActivityTimeout(activity, options);
+  return effectiveTimeout === void 0 ? options : { ...options, timeout: effectiveTimeout };
+}
 export function* runActivityWithRetry(context, activity, rest, explicitName) {
+  return yield* runPreparedActivityWithRetry(context, createRunActivityRequest(context, activity, rest, explicitName), defaultActivityRetrySleep(context));
+}
+export function* runActivityWithRetryAtStep(context, activity, rest, step, configuration = {}) {
+  return yield* runPreparedActivityWithRetry(context, createRunActivityRequestAtStep(context, activity, rest, step, configuration), configuration.retrySleep ?? defaultActivityRetrySleep(context));
+}
+function defaultActivityRetrySleep(context) {
+  return function* sleepForRetry(duration) {
+    yield* context.sleep(duration);
+  };
+}
+function* runPreparedActivityWithRetry(context, prepared, retrySleep) {
   const {
     request,
-    step,
+    retryStateKey,
+    cacheResultStep,
     hasCachedResult,
     cachedResult,
     retryAttempt,
     retryPolicy,
     scheduleToCloseTimeout
-  } = createRunActivityRequest(context, activity, rest, explicitName);
+  } = prepared;
   if (hasCachedResult)
     return cachedResult;
-  const internals = getInternals(context), budget = retryPolicy === void 0 ? void 0 : resolveScheduleToCloseBudget(internals, step, scheduleToCloseTimeout);
+  const internals = getInternals(context), budget = retryPolicy === void 0 ? void 0 : resolveScheduleToCloseBudget(internals, retryStateKey, 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));
+    yield* retrySleep(calculateBackoff(attempt - 1, retryPolicy), attempt);
   }
   while (!0) {
     if (attempt > 1)
       assertScheduleToCloseBudgetNotExhausted(budget, request.activityName, internals.getNow());
     try {
       const result = yield prepareActivityRetryRequest(request, attempt);
-      context.accumulatedResults.set(step, result);
-      completeActivityRetryAttempt(internals, step, attempt - 1);
+      if (cacheResultStep !== void 0)
+        context.accumulatedResults.set(cacheResultStep, result);
+      completeActivityRetryAttempt(internals, retryStateKey, attempt - 1);
       return result;
     } catch (error) {
       if (!shouldRetryActivityError(error, retryPolicy, attempt))
@@ -186,8 +201,8 @@ export function* runActivityWithRetry(context, activity, rest, explicitName) {
       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(backoff);
+      writeActivityRetryAttempt(internals, retryStateKey, nextAttempt);
+      yield* retrySleep(backoff, nextAttempt);
       attempt = nextAttempt;
     }
   }

package/dist/core/engine/activity-heartbeat-tracking.d.ts

@@ -1,19 +1,10 @@
 import type { ActivityContext } from '../types.ts';
 import type { EngineInternals } from './internals.ts';
-/**
- * Per-step heartbeat tracking for {@link ActivityContext.lastHeartbeatDetails}.
- *
- * The store is keyed `workflowId -> step` (not `workflowId` alone) so a retry of
- * an activity step reads the heartbeat ITS prior attempt recorded — and so a
- * later step's first attempt never inherits an earlier step's heartbeat, and
- * concurrent `ctx.all` activities never clobber one another. The step is stable
- * across retry attempts (assigned once at `stepIndex++`). Held only in engine
- * memory and cleared by workflowId (the outer key) on terminal cleanup and purge.
- */
-/** Record the heartbeat the current attempt of a step sent. */
-export declare function recordLastHeartbeatForStep(internals: EngineInternals, workflowId: string, step: number, details: unknown): void;
-/** Read the heartbeat a prior attempt of this step recorded, or `undefined`. */
-export declare function readLastHeartbeatForStep(internals: EngineInternals, workflowId: string, step: number): unknown;
+export type ActivityHeartbeatKey = number | string;
+/** Record the heartbeat the current attempt of an activity sent. */
+export declare function recordLastHeartbeatForStep(internals: EngineInternals, workflowId: string, step: ActivityHeartbeatKey, details: unknown): void;
+/** Read the heartbeat a prior attempt of this activity recorded, or `undefined`. */
+export declare function readLastHeartbeatForStep(internals: EngineInternals, workflowId: string, step: ActivityHeartbeatKey): unknown;
 /**
  * Drop the heartbeat tracked for a single step once that step has completed
  * successfully — after inline verify, and (on the idempotency path) after the
@@ -26,7 +17,7 @@ export declare function readLastHeartbeatForStep(internals: EngineInternals, wor
  * resumable-batch heartbeat a retry depends on, so this is only ever called from
  * the non-speculative success path.
  */
-export declare function clearLastHeartbeatForStep(internals: EngineInternals, workflowId: string, step: number): void;
+export declare function clearLastHeartbeatForStep(internals: EngineInternals, workflowId: string, step: ActivityHeartbeatKey): void;
 /**
  * #493: in development mode, emit a COARSE warning when an inline activity RETRY
  * (`attempt > 1`) starts with no `lastHeartbeatDetails` — the closest runtime
@@ -53,7 +44,7 @@ export declare function clearLastHeartbeatForStep(internals: EngineInternals, wo
  * routing model would need this gate to key on the resolved per-dispatch mode
  * instead.
  */
-export declare function warnIfRetryMissingHeartbeat(internals: EngineInternals, workflowId: string, step: number, attempt: number): void;
+export declare function warnIfRetryMissingHeartbeat(internals: EngineInternals, workflowId: string, step: ActivityHeartbeatKey, attempt: number): void;
 /**
  * Build the {@link ActivityContext} handed to an inline activity function. The
  * signal comes from the per-workflow AbortController (so workflow cancellation
@@ -61,4 +52,4 @@ export declare function warnIfRetryMissingHeartbeat(internals: EngineInternals,
  * tracking above; `completeAsync` is supplied by the caller (it owns the
  * async-completion token machinery).
  */
-export declare function buildActivityContext(internals: EngineInternals, workflowId: string, step: number, signal: AbortSignal, completeAsync: () => never): ActivityContext;
+export declare function buildActivityContext(internals: EngineInternals, workflowId: string, step: ActivityHeartbeatKey, signal: AbortSignal, completeAsync: () => never): ActivityContext;

package/dist/core/engine/activity-heartbeat-tracking.js

@@ -1,4 +1,10 @@
 import { DevelopmentWarningEvent } from "../events.js";
+function activityHeartbeatKeyLabel(key) {
+  return typeof key === "number" ? `step ${String(key)}` : `activity state key ${key}`;
+}
+function activityHeartbeatFieldPath(key) {
+  return typeof key === "number" ? `step.${String(key)}.lastHeartbeatDetails` : `activityStateKey.${key}.lastHeartbeatDetails`;
+}
 export function recordLastHeartbeatForStep(internals, workflowId, step, details) {
   let byStep = internals.lastHeartbeatDetailsByStep.get(workflowId);
   if (byStep === void 0) {
@@ -27,7 +33,7 @@ export function warnIfRetryMissingHeartbeat(internals, workflowId, step, attempt
     return;
   if (readLastHeartbeatForStep(internals, workflowId, step) !== void 0)
     return;
-  internals.engine.dispatchEvent(new DevelopmentWarningEvent(workflowId, `Activity retry (attempt ${attempt}) at step ${step} has no lastHeartbeatDetails. Either the previous attempt never recorded heartbeat details (it never called heartbeat(), or called it with no details), or the engine process restarted and discarded the in-memory heartbeat (it is not durable). The resumable-batch pattern only resumes across in-process retries; design the activity to restart cleanly when lastHeartbeatDetails is undefined.`, [`step.${step}.lastHeartbeatDetails`]));
+  internals.engine.dispatchEvent(new DevelopmentWarningEvent(workflowId, `Activity retry (attempt ${attempt}) at ${activityHeartbeatKeyLabel(step)} has no lastHeartbeatDetails. Either the previous attempt never recorded heartbeat details (it never called heartbeat(), or called it with no details), or the engine process restarted and discarded the in-memory heartbeat (it is not durable). The resumable-batch pattern only resumes across in-process retries; design the activity to restart cleanly when lastHeartbeatDetails is undefined.`, [activityHeartbeatFieldPath(step)]));
 }
 export function buildActivityContext(internals, workflowId, step, signal, completeAsync) {
   return {

package/dist/core/engine/activity-reconciliation.d.ts

@@ -102,6 +102,7 @@ export declare function resolveStartedActivityReconciliationRecord(internals: En
 }>;
 export declare function writeActivityReconciliationTransition(storage: Storage, reference: ActivityReconciliationReference, expectedRecord: ActivityReconciliationRecord, nextRecord: ActivityReconciliationRecord): Promise<void>;
 export declare function stageActivityReconciliationTransitionWithAtomicWorkflowCommit(internals: EngineInternals, workflowId: string, reference: ActivityReconciliationReference, expectedRecord: ActivityReconciliationRecord, nextRecord: ActivityReconciliationRecord): void;
+export declare function commitActivityReconciliationTransitionWithFencedWrite(internals: EngineInternals, reference: ActivityReconciliationReference, expectedRecord: ActivityReconciliationRecord, nextRecord: ActivityReconciliationRecord): Promise<void>;
 export declare function normalizePreDispatchVerificationResult(result: ActivityVerificationResult): 'not-completed' | 'completed-result-unavailable' | 'indeterminate' | {
     result: unknown;
 };

package/dist/core/engine/activity-reconciliation.js

@@ -7,6 +7,7 @@ import { decode, encode } from "../codec.js";
 import { assertPayloadWithinLimit } from "../payload-size.js";
 import { WeftError } from "../weft-error.js";
 import { stageAtomicWorkflowCommitSideEffects } from "./checkpoint-side-effects.js";
+import { commitFencedEngineWrite } from "./fenced-write.js";
 
 export class ActivityReconciliationCapabilityError extends WeftError {
   constructor() {
@@ -83,7 +84,7 @@ export async function resolveStartedActivityReconciliationRecord(internals, work
       ownerId: crypto.randomUUID(),
       updatedAt: internals.options.getNow()
     };
-    await writeActivityReconciliationTransition(internals.storage, reference, record, nextRecord);
+    await commitActivityReconciliationTransitionWithFencedWrite(internals, reference, record, nextRecord);
     return nextRecord;
   }
   if (normalized === "completed-result-unavailable")
@@ -92,7 +93,7 @@ export async function resolveStartedActivityReconciliationRecord(internals, work
     throw new ActivityReconciliationIndeterminateError(`Activity "${operation.activityName}" reconciliation is indeterminate.`);
   validateActivityResultForReconciliation(normalized.result, internals.options.payloadSizePolicy.maxBytes);
   const completedRecord = createCompletedActivityReconciliationRecord(record, normalized.result, internals.options.getNow());
-  await writeActivityReconciliationTransition(internals.storage, reference, record, completedRecord);
+  await commitActivityReconciliationTransitionWithFencedWrite(internals, reference, record, completedRecord);
   return { completedResult: normalized.result };
 }
 export async function writeActivityReconciliationTransition(storage, reference, expectedRecord, nextRecord) {
@@ -103,6 +104,10 @@ export async function writeActivityReconciliationTransition(storage, reference,
 export function stageActivityReconciliationTransitionWithAtomicWorkflowCommit(internals, workflowId, reference, expectedRecord, nextRecord) {
   stageAtomicWorkflowCommitSideEffects(internals, workflowId, buildActivityReconciliationTransitionSideEffects(reference, expectedRecord, nextRecord));
 }
+export async function commitActivityReconciliationTransitionWithFencedWrite(internals, reference, expectedRecord, nextRecord) {
+  const sideEffects = buildActivityReconciliationTransitionSideEffects(reference, expectedRecord, nextRecord);
+  await commitFencedEngineWrite(internals, sideEffects.operations, sideEffects.conditions, () => new ActivityReconciliationConflictError("Activity reconciliation completion lost compare-and-set ownership."));
+}
 function buildActivityReconciliationTransitionSideEffects(reference, expectedRecord, nextRecord) {
   return {
     conditions: [{ key: reference.key, expectedValue: encode(expectedRecord) }],

package/dist/core/engine/anonymous-signal-sequence.js

@@ -79,16 +79,18 @@ async function scanNextAnonymousSignalSequence(internals, workflowId) {
     if (sequence !== null && sequence >= nextSequence)
       nextSequence = sequence + 1;
   }
+  if (!Number.isSafeInteger(nextSequence))
+    throw Error(`Anonymous signal sequence overflow for workflow "${workflowId}": computed ${nextSequence}`);
   return nextSequence;
 }
 function extractAnonymousSignalSequence(key) {
-  const marker = ":anonymous%3A", markerIndex = key.lastIndexOf(marker);
-  if (markerIndex === -1)
+  const idComponent = key.slice(key.lastIndexOf(":") + 1), marker = "anonymous%3A";
+  if (!idComponent.startsWith(marker))
     return null;
-  const sequenceStart = markerIndex + marker.length, sequenceEnd = key.indexOf("%3A", sequenceStart);
+  const sequenceStart = marker.length, sequenceEnd = idComponent.indexOf("%3A", sequenceStart);
   if (sequenceEnd === -1)
     return null;
-  const sequence = Number(key.slice(sequenceStart, sequenceEnd));
+  const sequence = Number(idComponent.slice(sequenceStart, sequenceEnd));
   return Number.isSafeInteger(sequence) && sequence >= 0 ? sequence : null;
 }
 function decodeSignalSequence(bytes) {

package/dist/core/engine/async-activity-completion.d.ts

@@ -26,9 +26,6 @@
  * arrives after token recovery but before replay has adopted the workflow
  * generator, the engine buffers the completion or failure outcome and drains it
  * when replay reaches the same deterministic token.
- *
- * Internal-only. Imported from `src/core/engine/**` and the `ActivityContext`
- * construction path.
  */
 import type { OperationOutcome } from '../types.ts';
 import { WeftError } from '../weft-error.ts';
@@ -101,13 +98,14 @@ export type PendingAsyncActivityResolution = {
 /**
  * Derive the durable, deterministic task token for an async activity.
  *
- * The token is anchored to the workflow id, the workflow step index, and the
+ * The token is anchored to the workflow id, the activity state key, and the
  * dispatch attempt — all of which are stable across replay — so a workflow that
  * crashes while parked on an async activity mints the identical token after
- * recovery. `operationId` is deliberately excluded because it is regenerated on
- * every yield and would change on replay.
+ * recovery. Plain `ctx.run()` uses the workflow step as the state key.
+ * `operationId` is deliberately excluded because it is regenerated on every
+ * yield and would change on replay.
  */
-export declare function deriveAsyncActivityToken(workflowId: string, step: number, attempt: number): string;
+export declare function deriveAsyncActivityToken(workflowId: string, step: number | string, attempt: number): string;
 /**
  * Register a deferred activity: record it in memory and durably, then announce
  * the token via {@link ActivityAsyncPendingEvent}. Idempotent on `token`: if the