@lostgradient/weft 0.9.0 → 0.11.0

package/dist/core/checkpoint/serialization.js

@@ -29,7 +29,7 @@ export function validateCheckpointShape(value) {
   validateAccumulatedResultReplayWatermark(record);
   validateWorkerReplaySignatures(record);
   validateWorkerReplayFailures(record);
-  dropLegacyPendingSignals(record);
+  dropRetiredPendingSignals(record);
   assertRecordField(record, "searchAttributes");
   assertStringField(record, "version");
   assertNumberField(record, "createdAt");
@@ -148,7 +148,7 @@ function validateAccumulatedResultReplayWatermark(record) {
   if (typeof watermark !== "number" || !Number.isSafeInteger(watermark) || watermark < 0)
     throw Error('Invalid checkpoint: invalid "accumulatedResultReplayWatermark" (expected non-negative safe integer)');
 }
-function dropLegacyPendingSignals(record) {
+function dropRetiredPendingSignals(record) {
   delete record.pendingSignals;
 }
 function assertCurrentSchemaVersion(record) {

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

@@ -1,6 +1,6 @@
 import type { ComposedWorkflowInterceptor } from '../interceptor.ts';
 import type { HumanReviewOptions, HumanReviewResult } from '../review/index.ts';
-import type { ActivityCallable, ActivityCallOptions, AwaitChildWorkflowOptions, ChildWorkflowHandle, ChildWorkflowTarget, DetachedChildWorkflowOptions, Duration, QueryDefinition, RunAllResult, SearchAttributeHandle, SearchAttributeValue, SignalDefinition, UpdateDefinition, WorkflowContext, WorkflowLogger, WorkflowMapOptions, WorkflowOperation, WorkflowOperationTupleResult, WorkflowPipeStageDefinition, WorkflowReduceInput, WorkflowReduceOptions, WorkflowRunAllBranch, WorkflowStateNamespace } from '../types.ts';
+import type { ActivityCallable, ActivityCallOptions, AwaitChildWorkflowOptions, ChildWorkflowHandle, ChildWorkflowTarget, DetachedChildWorkflowOptions, Duration, QueryDefinition, RunAllResult, SearchAttributeHandle, SearchAttributeValue, SignalDefinition, UpdateDefinition, WorkflowContext, WorkflowKeyedRaceResult, WorkflowLogger, WorkflowMapOptions, WorkflowOperation, WorkflowOperationTupleResult, WorkflowPipeStageDefinition, WorkflowReduceInput, WorkflowReduceOptions, WorkflowRunAllBranch, WorkflowStateNamespace } from '../types.ts';
 import type { ContextOperationRequest } from './operation-request.ts';
 import type { ContextOptions, ErasedSagaStep, OffloadReference, StreamReference, StreamSink } from './types.ts';
 import * as contextUpdates from './updates.ts';
@@ -82,6 +82,7 @@ export declare class Context implements WorkflowContext {
     review(options: HumanReviewOptions): Generator<ContextOperationRequest, HumanReviewResult, unknown>;
     all<const TOperations extends readonly WorkflowOperation<unknown>[]>(operations: TOperations): Generator<ContextOperationRequest, WorkflowOperationTupleResult<TOperations>, unknown>;
     race<const TOperations extends readonly WorkflowOperation<unknown>[]>(operations: TOperations): Generator<ContextOperationRequest, WorkflowOperationTupleResult<TOperations>[number], unknown>;
+    raceKeyed<const TOperations extends Readonly<Record<string, WorkflowOperation<unknown>>>>(operations: TOperations): Generator<ContextOperationRequest, WorkflowKeyedRaceResult<TOperations>, unknown>;
     memo<T>(key: string, fn: () => T | Promise<T>): Generator<ContextOperationRequest, T, unknown>;
     offload<T>(key: string, fn: () => Promise<T>): Generator<ContextOperationRequest, OffloadReference, unknown>;
     stream(key: string, fn: (sink: StreamSink) => AsyncGenerator<unknown, void, unknown>): Generator<ContextOperationRequest, StreamReference, unknown>;

package/dist/core/context/index.js

@@ -156,6 +156,14 @@ export class Context {
   *race(operations) {
     return yield* parallelOperations.race(this, getInternals(this), [...operations]);
   }
+  *raceKeyed(operations) {
+    if (Object.getOwnPropertySymbols(operations).length > 0)
+      throw TypeError("ctx.raceKeyed branch names must be strings or numbers, not symbols");
+    const entries = Object.entries(operations);
+    if (entries.length === 0)
+      throw TypeError("ctx.raceKeyed requires at least one branch");
+    return yield* parallelOperations.race(this, getInternals(this), entries.map(([, operation]) => operation), entries.map(([key]) => key));
+  }
   *memo(key, fn) {
     return yield* parallelOperations.memo(this, getInternals(this), key, fn);
   }

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

@@ -127,6 +127,8 @@ export type ContextOperationRequest = {
     type: 'race';
     operationId: string;
     operations: ContextOperationRequest[];
+    /** Ordered branch names for `ctx.raceKeyed`; absent for positional `ctx.race`. */
+    branchNames?: string[];
     callerStack?: string;
 } | {
     type: 'memo';

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

@@ -57,7 +57,7 @@ export type ParallelOperationCacheEntry = {
     formatVersion: 2;
     variant: 'all' | 'race' | 'run-all';
     branches: ParallelBranchSlot[];
-    /** Ordered key list for `run-all`; absent for `all` and `race`. */
+    /** Ordered key list for `run-all` or `raceKeyed`; absent for `all` and positional `race`. */
     branchNames?: string[];
     subOperationCount: number;
 };

package/dist/core/context/parallel-cache-entry.js

@@ -41,20 +41,24 @@ function hasParallelOperationCacheMarker(value) {
   return value !== null && typeof value === "object" && value.__weftParallelOperationCache === !0;
 }
 function hasValidBranchTopology(variant, branches, subOperationCount, branchNames) {
-  if (variant === "race") {
-    if (branches.length !== 1 || subOperationCount < 1)
-      return !1;
-    const winner = branches[0];
-    if (winner == null || typeof winner !== "object")
-      return !1;
-    return winner.status === "fulfilled" && branchNames === void 0;
-  }
+  if (variant === "race")
+    return hasValidRaceTopology(branches, subOperationCount, branchNames);
   if (branches.length !== subOperationCount)
     return !1;
   if (variant === "run-all")
     return Array.isArray(branchNames) && branchNames.length === subOperationCount;
   return branchNames === void 0;
 }
+function hasValidRaceTopology(branches, subOperationCount, branchNames) {
+  if (branches.length !== 1 || subOperationCount < 1)
+    return !1;
+  const winner = branches[0];
+  if (winner == null || typeof winner !== "object")
+    return !1;
+  if (winner.status !== "fulfilled")
+    return !1;
+  return branchNames === void 0 || Array.isArray(branchNames) && branchNames.length === subOperationCount;
+}
 export function isParallelOperationCacheEntry(value) {
   if (value === null || typeof value !== "object")
     return !1;

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

@@ -4,6 +4,6 @@ import type { ContextOperationRequest } from './operation-request.ts';
 import { assertValidParallelOperationCacheEntry, BranchTopologyChangedError, createParallelOperationCacheEntry, isParallelOperationCacheEntry, type ParallelBranchSlot, type ParallelOperationCacheEntry } from './parallel-cache-entry.ts';
 export { assertValidParallelOperationCacheEntry, BranchTopologyChangedError, createParallelOperationCacheEntry, isParallelOperationCacheEntry, type ParallelBranchSlot, type ParallelOperationCacheEntry, };
 export declare function all(context: Context, internals: ContextInternals, operations: Generator<ContextOperationRequest, unknown, unknown>[]): Generator<ContextOperationRequest, unknown[], unknown>;
-export declare function race(context: Context, internals: ContextInternals, operations: Generator<ContextOperationRequest, unknown, unknown>[]): Generator<ContextOperationRequest, unknown, unknown>;
+export declare function race(context: Context, internals: ContextInternals, operations: Generator<ContextOperationRequest, unknown, unknown>[], branchNames?: string[]): Generator<ContextOperationRequest, unknown, unknown>;
 export declare function memo<T>(context: Context, internals: ContextInternals, key: string, fn: () => T | Promise<T>): Generator<ContextOperationRequest, T, unknown>;
 export declare function runAll<T extends Record<string, readonly [Function] | readonly [Function, unknown]>>(context: Context, internals: ContextInternals, branches: T): Generator<ContextOperationRequest, Record<keyof T, unknown>, unknown>;

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

@@ -83,7 +83,7 @@ function buildFulfilledAllEntry(values, operationId, subOperationCount) {
     operationId: `${operationId}:${i}`
   })), subOperationCount);
 }
-export function* race(context, internals, operations) {
+export function* race(context, internals, operations, branchNames) {
   const step = internals.stepIndex++;
   if (internals.accumulatedResults?.has(step)) {
     const cached = internals.accumulatedResults.get(step);
@@ -91,32 +91,74 @@ export function* race(context, internals, operations) {
     if (isParallelOperationCacheEntry(cached)) {
       if (cached.variant !== "race")
         throw new BranchTopologyChangedError(`ctx.race step ${step} found a cached entry of variant '${cached.variant}'. The same step must use the same parallel primitive across retries.`);
-      if (operations.length !== cached.subOperationCount)
-        throw new BranchTopologyChangedError(`ctx.race branch count changed across retry: expected ${cached.subOperationCount}, got ${operations.length}. Branch count must be deterministic.`);
+      assertRaceBranchTopology(operations.length, branchNames, cached);
       const winner = cached.branches[0];
-      if (winner?.status !== "fulfilled")
-        throw new BranchTopologyChangedError(`ctx.race step ${step} cached entry has no fulfilled winner slot \u2014 entry is malformed.`);
       internals.stepIndex += cached.subOperationCount;
       return winner.value;
     }
+    if (branchNames !== void 0)
+      throw new BranchTopologyChangedError(`ctx.raceKeyed step ${step} found a raw cached race value without keyed branch topology. The same step must use raceKeyed across retries.`);
     return cached;
   }
-  const subOperations = primeParallelOperations(operations), operationId = `race:${step}`;
+  const operationId = `race:${step}`;
+  let subOperations;
+  if (branchNames === void 0)
+    subOperations = primeParallelOperations(operations);
+  else {
+    const primed = primeKeyedRaceOperations(operations);
+    subOperations = primed.subOperations;
+    if (primed.synchronousWinner !== void 0) {
+      const result = { key: branchNames[primed.synchronousWinner.index], value: primed.synchronousWinner.value };
+      cacheRaceWinner(context, step, result, operationId, operations.length, branchNames);
+      return result;
+    }
+  }
   stampDeterministicOperationIds(subOperations, operationId);
   const callerStack = captureCallerStack(), result = yield {
     type: "race",
     operationId,
     operations: subOperations,
+    ...branchNames !== void 0 ? { branchNames } : {},
     callerStack
   };
+  cacheRaceWinner(context, step, result, operationId, subOperations.length, branchNames);
+  return result;
+}
+function primeKeyedRaceOperations(operations) {
+  const subOperations = [];
+  let synchronousWinner;
+  for (const [index, operation] of operations.entries()) {
+    const primed = operation.next();
+    if (primed.done)
+      synchronousWinner ??= { index, value: primed.value };
+    else
+      subOperations.push(primed.value);
+  }
+  return { subOperations, synchronousWinner };
+}
+function cacheRaceWinner(context, step, result, operationId, subOperationCount, branchNames) {
   context.accumulatedResults.set(step, {
     __weftParallelOperationCache: !0,
     formatVersion: 2,
     variant: "race",
     branches: [{ status: "fulfilled", value: result, operationId: `${operationId}:winner` }],
-    subOperationCount: subOperations.length
+    ...branchNames !== void 0 ? { branchNames } : {},
+    subOperationCount
   });
-  return result;
+}
+function sameBranchNames(left, right) {
+  if (left === void 0 || right === void 0)
+    return left === right;
+  return left.length === right.length && left.every((name, index) => name === right[index]);
+}
+function assertRaceBranchTopology(operationCount, branchNames, cached) {
+  if (operationCount !== cached.subOperationCount)
+    throw new BranchTopologyChangedError(`ctx.race branch count changed across retry: expected ${cached.subOperationCount}, got ${operationCount}. Branch count must be deterministic.`);
+  if (!sameBranchNames(branchNames, cached.branchNames))
+    throw new BranchTopologyChangedError(`ctx.race branch names changed across retry: expected ${formatBranchNames(cached.branchNames)}, got ${formatBranchNames(branchNames)}. Branch names and order must be deterministic.`);
+}
+function formatBranchNames(branchNames) {
+  return branchNames === void 0 ? "positional branches" : JSON.stringify(branchNames);
 }
 function stampDeterministicOperationIds(subOperations, parentOperationId) {
   for (let i = 0;i < subOperations.length; i++) {

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

@@ -26,9 +26,33 @@
  * 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.
+ *
+ * Acknowledgement durability: `completeAsyncActivity` / `failAsyncActivity`
+ * resolve only after ONE fenced batch has durably (a) deleted the single-use
+ * token record and (b) written a resolution record
+ * ({@link KEYS.asyncActivityResolution}) carrying the supplied outcome. A crash
+ * any time after the acknowledgement therefore cannot lose the outcome:
+ * recovery reloads the resolution record, queues it, and redelivers it when
+ * replay re-parks on the same deterministic token. The resolution record is
+ * deleted through the atomic side-effect buffer, so in the normal case it rides
+ * the very checkpoint that records the resumed result; a record whose delete
+ * never commits is simply redelivered (idempotent for a deterministic token) or
+ * swept by terminal cleanup/purge. If the acknowledgement batch itself fails,
+ * the in-memory token claim is restored and the error propagates — the caller
+ * learns the completion did NOT stick and can retry the still-live token.
+ *
+ * One caveat survives a crash: the failure path's raw thrown reason
+ * (`originalReason`) is delivered as-is only within the acknowledging process.
+ * A redelivery after recovery reconstructs the error from the persisted outcome
+ * (message, name, failure category) — the same fidelity the worker resume path
+ * has always had.
+ *
+ * The persisted record shapes, decode guards, key derivations, and the queued
+ * resolution buffer live in `async-activity-records.ts`.
  */
 import type { OperationOutcome } from '../types.ts';
 import { WeftError } from '../weft-error.ts';
+import { type PendingAsyncActivity } from './async-activity-records.ts';
 import type { EngineInternals } from './internals.ts';
 type AsyncActivityResolutionCallbacks = {
     feedOperationResult: (workflowId: string, outcome: OperationOutcome, originalReason?: {
@@ -36,12 +60,6 @@ type AsyncActivityResolutionCallbacks = {
     }) => void;
     finalizeTimeline: (workflowId: string, status: 'completed' | 'failed', output: unknown) => void;
 };
-/**
- * Per-workflow prefix for all async-activity storage keys. Used by cleanup and
- * purge paths that need to sweep every async-activity record for a workflow
- * without enumerating individual tokens.
- */
-export declare function asyncActivityWorkflowPrefix(workflowId: string): string;
 /**
  * Sentinel thrown by `ActivityContext.completeAsync()` to signal that the
  * activity is handing off to an out-of-band completion. The engine recognizes
@@ -73,48 +91,6 @@ export declare class AsyncActivityTokenNotFoundError extends WeftError<'AsyncAct
     readonly token: string;
     constructor(token: string);
 }
-/**
- * In-memory record of an activity that deferred to out-of-band completion and
- * is awaiting `completeAsyncActivity` / `failAsyncActivity`.
- */
-export type PendingAsyncActivity = {
-    readonly token: string;
-    readonly workflowId: string;
-    readonly activityName: string;
-    readonly operationId: string;
-    readonly step: number;
-    readonly attempt: number;
-    readonly createdAt: number;
-};
-export type PendingAsyncActivityResolution = {
-    readonly token: string;
-    readonly outcome: OperationOutcome;
-    readonly originalReason?: {
-        value: unknown;
-    };
-    readonly timelineStatus: 'completed' | 'failed';
-    readonly timelineOutput: unknown;
-};
-/**
- * Derive the durable, deterministic task token for an async activity.
- *
- * 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. 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 | 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
- * token is already registered (e.g. because `recoverPendingAsyncActivities` loaded
- * it before the workflow replayed and re-deferred), the durable record is
- * refreshed but the event is NOT re-emitted, preventing duplicate side-effects
- * (e.g. re-sending a webhook notification) on replay.
- */
-export declare function registerPendingAsyncActivity(internals: EngineInternals, pending: PendingAsyncActivity): Promise<void>;
 /**
  * Park an activity that threw {@link AsyncActivityDeferral}: register the
  * pending entry durably and return a promise that never settles, so the
@@ -123,12 +99,6 @@ export declare function registerPendingAsyncActivity(internals: EngineInternals,
  * one-liner.
  */
 export declare function parkDeferredAsyncActivity(internals: EngineInternals, deferral: AsyncActivityDeferral, details: Omit<PendingAsyncActivity, 'token' | 'createdAt'>, callbacks: AsyncActivityResolutionCallbacks): Promise<never>;
-/**
- * Reload pending async-activity records from storage into memory. Called by
- * `recoverAll()` so a token minted before a crash is resolvable again — even
- * before the recovered workflow has replayed far enough to re-register it.
- */
-export declare function recoverPendingAsyncActivities(internals: EngineInternals): Promise<void>;
 /**
  * Complete a deferred activity out-of-band with `result`, resuming the parked
  * workflow as though the activity had returned `result` inline.

package/dist/core/engine/async-activity-completion.js

@@ -1,14 +1,15 @@
-import { KEYS, encodeStorageKeyComponent } from "../../storage/interface.js";
-import { decode, encode } from "../codec.js";
-import { ActivityAsyncPendingEvent } from "../events.js";
+import { KEYS } from "../../storage/interface.js";
 import { assertPayloadWithinLimit } from "../payload-size.js";
 import { WeftError } from "../weft-error.js";
+import {
+  buildAsyncActivityAcknowledgementOperations,
+  queuePendingAsyncActivityResolution,
+  registerPendingAsyncActivity,
+  shouldBufferPendingAsyncActivityResolution,
+  takePendingAsyncActivityResolution
+} from "./async-activity-records.js";
 import { stageAtomicWorkflowCommitSideEffects } from "./checkpoint-side-effects.js";
 import { commitFencedEngineWrite } from "./fenced-write.js";
-const ASYNC_ACTIVITY_TOKEN_PREFIX = "async-act:v1", ASYNC_ACTIVITY_KEY_PREFIX = "async-act:v1:";
-export function asyncActivityWorkflowPrefix(workflowId) {
-  return `${ASYNC_ACTIVITY_KEY_PREFIX}${encodeStorageKeyComponent(workflowId)}:`;
-}
 
 export class AsyncActivityDeferral extends Error {
   token;
@@ -26,43 +27,10 @@ export class AsyncActivityTokenNotFoundError extends WeftError {
     this.token = token;
   }
 }
-function isPersistedAsyncActivity(value) {
-  if (typeof value !== "object" || value === null)
-    return !1;
-  const record = value;
-  return record.version === 1 && typeof record.token === "string" && typeof record.workflowId === "string" && typeof record.activityName === "string" && typeof record.operationId === "string" && typeof record.step === "number" && typeof record.attempt === "number" && typeof record.createdAt === "number";
-}
-export function deriveAsyncActivityToken(workflowId, step, attempt) {
-  return `${ASYNC_ACTIVITY_TOKEN_PREFIX}:${workflowId}:${step}:${attempt}`;
-}
-function buildPersistPendingAsyncActivityOperation(pending) {
-  const record = {
-    version: 1,
-    token: pending.token,
-    workflowId: pending.workflowId,
-    activityName: pending.activityName,
-    operationId: pending.operationId,
-    step: pending.step,
-    attempt: pending.attempt,
-    createdAt: pending.createdAt
-  };
-  return {
-    type: "put",
-    key: KEYS.asyncActivity(pending.workflowId, pending.token),
-    value: encode(record)
-  };
-}
-export async function registerPendingAsyncActivity(internals, pending) {
-  const alreadyRegistered = internals.pendingAsyncActivities.has(pending.token);
-  internals.pendingAsyncActivities.set(pending.token, pending);
-  await commitFencedEngineWrite(internals, [buildPersistPendingAsyncActivityOperation(pending)], [], () => Error(`Async activity registration for token "${pending.token}" lost its precondition.`));
-  if (!alreadyRegistered)
-    internals.engine.dispatchEvent(new ActivityAsyncPendingEvent(pending.token, pending.operationId, pending.workflowId, pending.activityName, pending.attempt));
-}
 export async function parkDeferredAsyncActivity(internals, deferral, details, callbacks) {
   const queuedResolution = takePendingAsyncActivityResolution(internals, details.workflowId, deferral.token);
   if (queuedResolution !== void 0) {
-    deliverPendingAsyncActivityResolution(details.workflowId, queuedResolution, callbacks);
+    deliverPendingAsyncActivityResolution(internals, details.workflowId, queuedResolution, callbacks);
     return new Promise(() => {});
   }
   await registerPendingAsyncActivity(internals, {
@@ -72,64 +40,31 @@ export async function parkDeferredAsyncActivity(internals, deferral, details, ca
   });
   return new Promise(() => {});
 }
-export async function recoverPendingAsyncActivities(internals) {
-  for await (const [, bytes] of internals.storage.scan(ASYNC_ACTIVITY_KEY_PREFIX)) {
-    const decoded = decode(bytes);
-    if (!isPersistedAsyncActivity(decoded))
-      continue;
-    internals.pendingAsyncActivities.set(decoded.token, {
-      token: decoded.token,
-      workflowId: decoded.workflowId,
-      activityName: decoded.activityName,
-      operationId: decoded.operationId,
-      step: decoded.step,
-      attempt: decoded.attempt,
-      createdAt: decoded.createdAt
-    });
-  }
-}
-async function consumePendingAsyncActivity(internals, token) {
+async function consumePendingAsyncActivity(internals, token, outcome) {
   const pending = internals.pendingAsyncActivities.get(token);
   if (!pending)
     throw new AsyncActivityTokenNotFoundError(token);
   internals.pendingAsyncActivities.delete(token);
-  stageAtomicWorkflowCommitSideEffects(internals, pending.workflowId, {
-    conditions: [],
-    operations: [{ type: "delete", key: KEYS.asyncActivity(pending.workflowId, token) }]
-  });
+  try {
+    await commitFencedEngineWrite(internals, buildAsyncActivityAcknowledgementOperations(pending, outcome), [], () => Error(`Async activity acknowledgement for token "${token}" lost its precondition.`));
+  } catch (error) {
+    internals.pendingAsyncActivities.set(token, pending);
+    throw error;
+  }
   return pending;
 }
-function shouldBufferPendingAsyncActivityResolution(internals, workflowId) {
-  return internals.inlineStrategy !== null && !internals.inlineStrategy.hasGenerator(workflowId);
-}
-function queuePendingAsyncActivityResolution(internals, workflowId, resolution) {
-  internals.pendingAsyncActivityResolutions ??= new Map;
-  const queued = internals.pendingAsyncActivityResolutions.get(workflowId) ?? [];
-  queued.push(resolution);
-  internals.pendingAsyncActivityResolutions.set(workflowId, queued);
-}
-function takePendingAsyncActivityResolution(internals, workflowId, token) {
-  internals.pendingAsyncActivityResolutions ??= new Map;
-  const queued = internals.pendingAsyncActivityResolutions.get(workflowId);
-  if (queued === void 0)
-    return;
-  const index = queued.findIndex((resolution) => resolution.token === token);
-  if (index === -1)
-    return;
-  const resolution = queued[index];
-  if (resolution === void 0)
-    return;
-  queued.splice(index, 1);
-  if (queued.length === 0)
-    internals.pendingAsyncActivityResolutions.delete(workflowId);
-  return resolution;
-}
-function deliverPendingAsyncActivityResolution(workflowId, resolution, callbacks) {
+function deliverPendingAsyncActivityResolution(internals, workflowId, resolution, callbacks) {
+  stageAtomicWorkflowCommitSideEffects(internals, workflowId, {
+    conditions: [],
+    operations: [
+      { type: "delete", key: KEYS.asyncActivityResolution(workflowId, resolution.token) }
+    ]
+  });
   callbacks.finalizeTimeline(workflowId, resolution.timelineStatus, resolution.timelineOutput);
   callbacks.feedOperationResult(workflowId, resolution.outcome, resolution.originalReason);
 }
 async function resolvePendingAsyncActivity(internals, token, outcome, callbacks, originalReason) {
-  const pending = await consumePendingAsyncActivity(internals, token), timelineOutput = outcome.status === "completed" ? outcome.value : outcome.error, resolution = {
+  const pending = await consumePendingAsyncActivity(internals, token, outcome), timelineOutput = outcome.status === "completed" ? outcome.value : outcome.error, resolution = {
     token,
     outcome,
     timelineStatus: outcome.status,
@@ -140,7 +75,7 @@ async function resolvePendingAsyncActivity(internals, token, outcome, callbacks,
     queuePendingAsyncActivityResolution(internals, pending.workflowId, resolution);
     return;
   }
-  deliverPendingAsyncActivityResolution(pending.workflowId, resolution, callbacks);
+  deliverPendingAsyncActivityResolution(internals, pending.workflowId, resolution, callbacks);
 }
 export async function completeAsyncActivity(internals, token, result, callbacks) {
   assertPayloadWithinLimit(result, internals.options.payloadSizePolicy.maxBytes, "activity result");

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

@@ -0,0 +1,106 @@
+/**
+ * Durable record layer for out-of-band ("async") activity completion.
+ *
+ * Two record shapes share the `async-act:v1:` keyspace, discriminated by their
+ * decode guards (never by key shape):
+ *
+ * - **Pending token records** ({@link KEYS.asyncActivity}): an activity that
+ *   deferred via `ctx.completeAsync()` and is awaiting an external completion.
+ * - **Resolution records** ({@link KEYS.asyncActivityResolution}): an
+ *   acknowledged completion or failure whose resumed-workflow checkpoint has
+ *   not committed yet. Written atomically with the token-record delete so the
+ *   acknowledgement is durable before the caller learns it succeeded.
+ *
+ * The completion orchestration (park, consume, deliver, resume) lives in
+ * `async-activity-completion.ts`; this module owns the persisted shapes, the
+ * key derivations, and the in-memory resolution queue that recovery drains.
+ */
+import { type BatchOperation } from '../../storage/interface.ts';
+import type { OperationOutcome } from '../types.ts';
+import type { EngineInternals } from './internals.ts';
+/**
+ * Storage-key prefix for durable async-activity records. Matches the base of
+ * {@link KEYS.asyncActivity}; the full key appends `<workflowId>:<token>` (and
+ * `:resolution` for resolution records). The trailing colon (absent from the
+ * token prefix) scopes the global recovery scan to record keys only.
+ */
+export declare const ASYNC_ACTIVITY_KEY_PREFIX = "async-act:v1:";
+/**
+ * Per-workflow prefix for all async-activity storage keys — pending token
+ * records AND resolution records. Used by cleanup and purge paths that need to
+ * sweep every async-activity record for a workflow without enumerating
+ * individual tokens.
+ */
+export declare function asyncActivityWorkflowPrefix(workflowId: string): string;
+/**
+ * In-memory record of an activity that deferred to out-of-band completion and
+ * is awaiting `completeAsyncActivity` / `failAsyncActivity`.
+ */
+export type PendingAsyncActivity = {
+    readonly token: string;
+    readonly workflowId: string;
+    readonly activityName: string;
+    readonly operationId: string;
+    readonly step: number;
+    readonly attempt: number;
+    readonly createdAt: number;
+};
+/**
+ * In-memory form of an acknowledged outcome awaiting delivery into the workflow
+ * generator. `originalReason` (the raw thrown value on the failure path) exists
+ * only within the acknowledging process — it is not persisted, so a resolution
+ * reloaded by recovery reconstructs the error from the recorded outcome.
+ */
+export type PendingAsyncActivityResolution = {
+    readonly token: string;
+    readonly outcome: OperationOutcome;
+    readonly originalReason?: {
+        value: unknown;
+    };
+    readonly timelineStatus: 'completed' | 'failed';
+    readonly timelineOutput: unknown;
+};
+/**
+ * Derive the durable, deterministic task token for an async activity.
+ *
+ * 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. 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 | string, attempt: number): string;
+/**
+ * Build the acknowledgement batch for a consumed token: delete the pending
+ * token record and persist the resolution record carrying `outcome`, in one
+ * batch, so the acknowledgement is durable before the caller learns it
+ * succeeded.
+ */
+export declare function buildAsyncActivityAcknowledgementOperations(pending: PendingAsyncActivity, outcome: OperationOutcome): BatchOperation[];
+/**
+ * Register a deferred activity: record it in memory and durably, then announce
+ * the token via {@link ActivityAsyncPendingEvent}. Idempotent on `token`: if the
+ * token is already registered (e.g. because `recoverPendingAsyncActivities` loaded
+ * it before the workflow replayed and re-deferred), the durable record is
+ * refreshed but the event is NOT re-emitted, preventing duplicate side-effects
+ * (e.g. re-sending a webhook notification) on replay.
+ */
+export declare function registerPendingAsyncActivity(internals: EngineInternals, pending: PendingAsyncActivity): Promise<void>;
+/**
+ * Reload async-activity records from storage into memory. Called by
+ * `recoverAll()` so a token minted before a crash is resolvable again — even
+ * before the recovered workflow has replayed far enough to re-register it —
+ * and so an acknowledged-but-not-yet-checkpointed resolution is redelivered
+ * when replay re-parks on the same deterministic token.
+ */
+export declare function recoverPendingAsyncActivities(internals: EngineInternals): Promise<void>;
+/**
+ * True when a resolution cannot be delivered yet because inline replay has not
+ * adopted the workflow generator (the post-recovery window).
+ */
+export declare function shouldBufferPendingAsyncActivityResolution(internals: EngineInternals, workflowId: string): boolean;
+/** Queue a resolution for delivery when replay reaches its token again. */
+export declare function queuePendingAsyncActivityResolution(internals: EngineInternals, workflowId: string, resolution: PendingAsyncActivityResolution): void;
+/** Take the queued resolution for `token`, if one is waiting. */
+export declare function takePendingAsyncActivityResolution(internals: EngineInternals, workflowId: string, token: string): PendingAsyncActivityResolution | undefined;