@lostgradient/weft 0.3.0 → 0.4.0

package/dist/core/events/update-events.d.ts

@@ -8,9 +8,8 @@
  * import { Engine, UpdateReceivedEvent } from '@lostgradient/weft';
  *
  * const engine = new Engine();
- * engine.addEventListener('update:received', (e: Event) => {
- *   const ev = e as UpdateReceivedEvent;
- *   console.log('update', ev.name, 'received for', ev.workflowId, '(id:', ev.updateId, ')');
+ * engine.addEventListener(UpdateReceivedEvent.type, (event) => {
+ *   console.log('update', event.name, 'received for', event.workflowId, '(id:', event.updateId, ')');
  * });
  * ```
  */
@@ -32,12 +31,11 @@ export declare class UpdateReceivedEvent extends Event {
  * import { Engine, UpdateCompletedEvent } from '@lostgradient/weft';
  *
  * const engine = new Engine();
- * engine.addEventListener('update:completed', (e: Event) => {
- *   const ev = e as UpdateCompletedEvent;
- *   if (ev.error) {
- *     console.error('update', ev.name, 'failed:', ev.error);
+ * engine.addEventListener(UpdateCompletedEvent.type, (event) => {
+ *   if (event.error) {
+ *     console.error('update', event.name, 'failed:', event.error);
  *   } else {
- *     console.log('update', ev.name, 'result:', ev.result);
+ *     console.log('update', event.name, 'result:', event.result);
  *   }
  * });
  * ```

package/dist/core/events/workflow-events.d.ts

@@ -1,4 +1,24 @@
 import type { TerminationReason } from '../types/history-policy.ts';
+/**
+ * Fired on the {@link Engine} after a workflow definition is successfully
+ * registered. Same-reference idempotent registration does not emit this event.
+ *
+ * @example
+ * ```ts
+ * import { Engine, WorkflowDefinitionRegisteredEvent, workflow } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.addEventListener(WorkflowDefinitionRegisteredEvent.type, (event) => {
+ *   console.log('registered workflow:', event.workflowType);
+ * });
+ * engine.register(workflow({ name: 'ping' }).execute(async function* () { return 'pong'; }));
+ * ```
+ */
+export declare class WorkflowDefinitionRegisteredEvent extends Event {
+    static readonly type: "workflow:definition-registered";
+    readonly workflowType: string;
+    constructor(workflowType: string);
+}
 /**
  * Fired on the {@link Engine} when a new workflow execution begins. Listen via
  * `engine.addEventListener('workflow:started', handler)` and read
@@ -9,9 +29,8 @@ import type { TerminationReason } from '../types/history-policy.ts';
  * import { workflow, Engine, WorkflowStartedEvent } from '@lostgradient/weft';
  *
  * const engine = new Engine();
- * engine.addEventListener('workflow:started', (e: Event) => {
- *   const ev = e as WorkflowStartedEvent;
- *   console.log('started', ev.workflowId, ev.workflowType);
+ * engine.addEventListener(WorkflowStartedEvent.type, (event) => {
+ *   console.log('started', event.workflowId, event.workflowType);
  * });
  * engine.register(workflow({ name: 'ping' }).execute(async function* () { return 'pong'; }));
  * await engine.start('ping', null);
@@ -34,9 +53,8 @@ export declare class WorkflowStartedEvent extends Event {
  * import { workflow, Engine, WorkflowCompletedEvent } from '@lostgradient/weft';
  *
  * const engine = new Engine();
- * engine.addEventListener('workflow:completed', (e: Event) => {
- *   const ev = e as WorkflowCompletedEvent;
- *   console.log('completed in', ev.duration, 'ms, result:', ev.result);
+ * engine.addEventListener(WorkflowCompletedEvent.type, (event) => {
+ *   console.log('completed in', event.duration, 'ms, result:', event.result);
  * });
  * engine.register(workflow({ name: 'ping' }).execute(async function* () { return 'pong'; }));
  * await (await engine.start('ping', null)).result();
@@ -59,9 +77,8 @@ export declare class WorkflowCompletedEvent extends Event {
  * import { workflow, Engine, WorkflowFailedEvent } from '@lostgradient/weft';
  *
  * const engine = new Engine();
- * engine.addEventListener('workflow:failed', (e: Event) => {
- *   const ev = e as WorkflowFailedEvent;
- *   console.error('workflow', ev.workflowId, 'failed:', ev.error.message);
+ * engine.addEventListener(WorkflowFailedEvent.type, (event) => {
+ *   console.error('workflow', event.workflowId, 'failed:', event.error.message);
  * });
  * engine.register(workflow({ name: 'boom' }).execute(async function* () { throw new Error('oops'); }));
  * await engine.start('boom', null).then(h => h.result()).catch(() => undefined);
@@ -83,9 +100,8 @@ export declare class WorkflowFailedEvent extends Event {
  * import { Engine, workflow, WorkflowCancelledEvent } from '@lostgradient/weft';
  *
  * const engine = new Engine();
- * engine.addEventListener('workflow:cancelled', (e: Event) => {
- *   const ev = e as WorkflowCancelledEvent;
- *   console.log('cancelled', ev.workflowId);
+ * engine.addEventListener(WorkflowCancelledEvent.type, (event) => {
+ *   console.log('cancelled', event.workflowId);
  * });
  * engine.register(
  *   workflow({ name: 'slow' }).execute(async function* (
@@ -117,9 +133,8 @@ export declare class WorkflowCancelledEvent extends Event {
  * import { Engine, WorkflowTimedOutEvent } from '@lostgradient/weft';
  *
  * const engine = new Engine();
- * engine.addEventListener('workflow:timed-out', (e: Event) => {
- *   const ev = e as WorkflowTimedOutEvent;
- *   console.log(ev.workflowId, 'timed out after', ev.elapsed, 'ms (', ev.timeoutType, ')');
+ * engine.addEventListener(WorkflowTimedOutEvent.type, (event) => {
+ *   console.log(event.workflowId, 'timed out after', event.elapsed, 'ms (', event.timeoutType, ')');
  * });
  * ```
  */
@@ -148,9 +163,8 @@ export declare const WORKFLOW_TERMINAL_EVENT_TYPES: ReadonlySet<string>;
  * import { Engine, WorkflowResumedEvent } from '@lostgradient/weft';
  *
  * const engine = new Engine();
- * engine.addEventListener('workflow:resumed', (e: Event) => {
- *   const ev = e as WorkflowResumedEvent;
- *   console.log('resumed', ev.workflowId, 'from step', ev.fromStep);
+ * engine.addEventListener(WorkflowResumedEvent.type, (event) => {
+ *   console.log('resumed', event.workflowId, 'from step', event.fromStep);
  * });
  * ```
  */
@@ -172,9 +186,8 @@ export declare class WorkflowResumedEvent extends Event {
  * import { Engine, WorkflowSuspendedEvent } from '@lostgradient/weft';
  *
  * const engine = new Engine();
- * engine.addEventListener('workflow:suspended', (e: Event) => {
- *   const ev = e as WorkflowSuspendedEvent;
- *   console.log('suspended', ev.workflowId);
+ * engine.addEventListener(WorkflowSuspendedEvent.type, (event) => {
+ *   console.log('suspended', event.workflowId);
  * });
  * ```
  */
@@ -207,8 +220,7 @@ export type WorkflowRecoverySkippedReason = 'type-not-registered';
  *
  * const engine = new Engine();
  * engine.addEventListener(WorkflowRecoverySkippedEvent.type, (event) => {
- *   const skipped = event as WorkflowRecoverySkippedEvent;
- *   console.warn('skipped recovery for', skipped.workflowType);
+ *   console.warn('skipped recovery for', event.workflowType);
  * });
  * ```
  */
@@ -219,3 +231,56 @@ export declare class WorkflowRecoverySkippedEvent extends Event {
     readonly reason: WorkflowRecoverySkippedReason;
     constructor(workflowId: string, workflowType: string, reason: WorkflowRecoverySkippedReason);
 }
+/**
+ * The lifecycle stage a {@link WorkflowTeardownEvent} reports for a workflow's
+ * definition-level `finalizer` (issue #446):
+ *
+ * - `'completed'`: the finalizer succeeded — the external resource recorded via
+ *   `ctx.setFinalizerState` has been torn down.
+ * - `'failed'`: a single attempt failed; the engine backs off and re-fires unless the
+ *   dead-letter horizon is reached. Per-attempt observability — fires on every retry.
+ * - `'dead-lettered'`: the retry horizon was reached without success; the external
+ *   resource may be leaked. The durable record is `KEYS.teardownDeadLetter`, which
+ *   survives purge so the leak is auditable after the workflow record is gone.
+ *
+ * @example
+ * ```ts
+ * import type { WorkflowTeardownStatus } from '@lostgradient/weft';
+ *
+ * const status: WorkflowTeardownStatus = 'dead-lettered';
+ * void status;
+ * ```
+ */
+export type WorkflowTeardownStatus = 'completed' | 'failed' | 'dead-lettered';
+/**
+ * Fired on the {@link Engine} as a workflow's definition-level `finalizer` progresses
+ * through teardown after a `cancelled`/`timed-out` terminal (issue #446). One event
+ * type carries the stage in `status`; `attempts` is the attempt count; `error` is the
+ * failure message on `'failed'`/`'dead-lettered'` (absent on `'completed'`). The schema is
+ * stable and compact, and `status` is low-cardinality; `workflowId`/`workflowType` are
+ * naturally high-cardinality identifiers. Keep `'failed'` listeners side-effect-light —
+ * they fire on every retry.
+ *
+ * @example
+ * ```ts
+ * import { Engine, WorkflowTeardownEvent } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.addEventListener(WorkflowTeardownEvent.type, (event) => {
+ *   if (event.status === 'dead-lettered') {
+ *     console.error('LEAKED resource: teardown for', event.workflowId, 'gave up after', event.attempts);
+ *   } else {
+ *     console.log('teardown', event.status, 'for', event.workflowId, 'attempt', event.attempts);
+ *   }
+ * });
+ * ```
+ */
+export declare class WorkflowTeardownEvent extends Event {
+    static readonly type: "workflow:teardown";
+    readonly workflowId: string;
+    readonly workflowType: string;
+    readonly status: WorkflowTeardownStatus;
+    readonly attempts: number;
+    readonly error: string | undefined;
+    constructor(workflowId: string, workflowType: string, status: WorkflowTeardownStatus, attempts: number, error?: string);
+}

package/dist/core/events/workflow-events.js

@@ -1,3 +1,12 @@
+export class WorkflowDefinitionRegisteredEvent extends Event {
+  static type = "workflow:definition-registered";
+  workflowType;
+  constructor(workflowType) {
+    super(WorkflowDefinitionRegisteredEvent.type);
+    this.workflowType = workflowType;
+  }
+}
+
 export class WorkflowStartedEvent extends Event {
   static type = "workflow:started";
   workflowId;
@@ -98,3 +107,20 @@ export class WorkflowRecoverySkippedEvent extends Event {
     this.reason = reason;
   }
 }
+
+export class WorkflowTeardownEvent extends Event {
+  static type = "workflow:teardown";
+  workflowId;
+  workflowType;
+  status;
+  attempts;
+  error;
+  constructor(workflowId, workflowType, status, attempts, error) {
+    super(WorkflowTeardownEvent.type);
+    this.workflowId = workflowId;
+    this.workflowType = workflowType;
+    this.status = status;
+    this.attempts = attempts;
+    this.error = error;
+  }
+}

package/dist/core/failure-categories.js

@@ -6,6 +6,8 @@ export const FAILURE_CATEGORIES = [
   "system"
 ];
 const currentFailureCategories = new Set(FAILURE_CATEGORIES), timeoutErrorNames = new Set([
+  "ActivityScheduleToCloseTimeoutError",
+  "ActivityPerAttemptTimeoutError",
   "MCPToolTimeoutError",
   "ReviewTimeoutError",
   "UpdateTimeoutError",
@@ -23,31 +25,17 @@ const cancellationErrorNames = new Set([
   "ResourceExhaustedError",
   "OutOfMemoryError",
   "StorageQuotaExceededError"
-]), legacyFailureCategoryMapping = {
-  action: "application",
-  memory: "resource",
-  planning: "application",
-  reflection: "application",
-  system: "system"
-}, failureCategorySearchAliases = {
-  application: ["application", "action", "planning", "reflection"],
-  timeout: ["timeout"],
-  cancellation: ["cancellation"],
-  resource: ["resource", "memory"],
-  system: ["system"]
-};
+]);
 export function isFailureCategory(value) {
   return currentFailureCategories.has(value);
 }
 export function normalizeFailureCategory(value) {
   if (isFailureCategory(value))
     return value;
-  if (typeof value !== "string")
-    return;
-  return legacyFailureCategoryMapping[value];
+  return;
 }
 export function failureCategorySearchValues(category) {
-  return failureCategorySearchAliases[category];
+  return [category];
 }
 export function classifyErrorAsFailureCategory(error, options = {}) {
   if (!(error instanceof Error))

package/dist/core/fault-code.d.ts

@@ -4,8 +4,10 @@
  * onto the wire so clients can branch on the failure programmatically rather
  * than string-matching a human message:
  *
- *   - REST: `{ error: { code, message, data? } }` (see `fault-to-http.ts`).
- *   - JSON-RPC: `data.weftCode` (see `fault-to-json-rpc.ts`).
+ *   - REST operation routes: HTTP status plus `{ error: string }` for declared
+ *     faults, with `EngineFailure` masked to `"Internal server error"`.
+ *   - JSON-RPC: `error.data.weftCode` plus `error.data.httpStatus` (see
+ *     `fault-to-json-rpc.ts`).
  *
  * The type lives in `core` — not `server` — because both the server (which
  * produces faults) and the client (which consumes them off the wire) need it,
@@ -23,6 +25,9 @@ import type { FailureCategory } from './types/identity.ts';
  * be added additively, and the `satisfies` map below forces every new code to
  * declare its failure category at compile time.
  *
+ * See `documentation/reference/api-errors.md#faultcode` for the REST HTTP
+ * status and JSON-RPC error-data mappings for every public fault code.
+ *
  * @example
  * ```ts
  * import { HttpClientError, type FaultCode } from '@lostgradient/weft';
@@ -34,7 +39,7 @@ import type { FailureCategory } from './types/identity.ts';
  * void describe;
  * ```
  */
-export type FaultCode = 'Unauthorized' | 'Forbidden' | 'NotFound' | 'Conflict' | 'Unprocessable' | 'Timeout' | 'NotImplemented' | 'UnsupportedTransport' | 'SubscriptionOverflow' | 'InvalidParams' | 'MethodNotFound' | 'EngineFailure';
+export type FaultCode = 'Unauthorized' | 'Forbidden' | 'NotFound' | 'Conflict' | 'Unprocessable' | 'Timeout' | 'PayloadTooLarge' | 'NotImplemented' | 'UnsupportedTransport' | 'SubscriptionOverflow' | 'InvalidParams' | 'MethodNotFound' | 'EngineFailure';
 /**
  * Maps each wire {@link FaultCode} onto a {@link FailureCategory}.
  *
@@ -61,6 +66,7 @@ export declare const FAULT_CODE_TO_FAILURE_CATEGORY: Readonly<{
     readonly InvalidParams: "application";
     readonly MethodNotFound: "application";
     readonly Timeout: "timeout";
+    readonly PayloadTooLarge: "resource";
     readonly SubscriptionOverflow: "resource";
     readonly NotImplemented: "system";
     readonly UnsupportedTransport: "system";

package/dist/core/fault-code.js

@@ -7,6 +7,7 @@ export const FAULT_CODE_TO_FAILURE_CATEGORY = Object.freeze({
   InvalidParams: "application",
   MethodNotFound: "application",
   Timeout: "timeout",
+  PayloadTooLarge: "resource",
   SubscriptionOverflow: "resource",
   NotImplemented: "system",
   UnsupportedTransport: "system",

package/dist/core/inline-execution-strategy.context-options.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Dependency shapes and the context-options builder used by
+ * {@link InlineExecutionStrategy}. Kept beside the strategy so the strategy
+ * module stays focused on generator lifecycle and context bookkeeping.
+ *
+ * @module core/inline-execution-strategy.context-options
+ */
+import type { ContextOptions } from './context.ts';
+import type { ComposedWorkflowInterceptor } from './interceptor.ts';
+import type { SearchAttributeSchema, WorkflowFunction } from './types.ts';
+import type { WorkflowLogRecord } from './types/workflow-log.ts';
+/** Capabilities the engine injects into the inline strategy at construction. */
+export interface InlineExecutionDependencies {
+    getRegistration: (workflowType: string) => {
+        handler: WorkflowFunction;
+        version: string;
+        searchAttributes?: SearchAttributeSchema;
+    } | undefined;
+    getNow: () => number;
+    resolveWorkflowType?: (target: string | Function) => string;
+    maxNestingDepth: number;
+    development?: boolean;
+    getComposedWorkflowInterceptor?: () => ComposedWorkflowInterceptor | null;
+    registerCancelHandler?: (workflowId: string, handler: () => Promise<void> | void) => () => void;
+    /**
+     * Durably record a `ctx.setFinalizerState(value)` payload for a workflow (#446).
+     * The engine stages it as a pending atomic side-effect so it commits with the
+     * next checkpoint or the terminal batch. Absent in worker mode.
+     */
+    recordFinalizerState?: (workflowId: string, value: unknown) => void;
+    /**
+     * Look up the non-serialized per-run `services` value for a workflow, exposed
+     * to the body as `ctx.services`. Returns `undefined` when none was supplied.
+     */
+    getWorkflowServices?: (workflowId: string) => unknown;
+    /**
+     * The host log sink (`EngineOptions.onLog`) for `ctx.log` records, or
+     * `undefined` for the default console behavior. Engine-scoped, so it takes no
+     * workflow id.
+     */
+    getLogSink?: () => ((record: WorkflowLogRecord) => void) | undefined;
+}
+/** A registration resolved through {@link InlineExecutionDependencies.getRegistration}, narrowed to the present case. */
+export type InlineWorkflowRegistration = NonNullable<ReturnType<InlineExecutionDependencies['getRegistration']>>;
+/** Parameters for starting a workflow run on the inline strategy. */
+export type InlineStartWorkflowParameters = {
+    workflowId: string;
+    workflowType: string;
+    input: unknown;
+    checkpoint: ArrayBuffer | Uint8Array;
+    nestingDepth?: number;
+    executionStateOwnerId?: string;
+    startedAt?: number;
+    sleepReferenceTime?: number;
+    deadline?: number;
+    headers?: [string, string][];
+};
+/** Build the {@link ContextOptions} for a single inline workflow run from the injected dependencies and start parameters. */
+export declare function createInlineContextOptions(dependencies: InlineExecutionDependencies, registration: InlineWorkflowRegistration, parameters: InlineStartWorkflowParameters, workflowAbort: AbortController): ContextOptions;
+/**
+ * Keep only the defined optional inline-strategy dependencies. Under
+ * `exactOptionalPropertyTypes` a key set to `undefined` is rejected while an
+ * absent key is fine, so each optional is included only when present. Lives here
+ * (rather than inline in `createExecutionStrategyBundle`) so its conditional
+ * spreads do not tip that function over the cyclomatic-complexity cap.
+ */
+export declare function optionalInlineDependencies(candidates: {
+    [Key in 'getComposedWorkflowInterceptor' | 'registerCancelHandler' | 'recordFinalizerState' | 'getWorkflowServices' | 'getLogSink']: InlineExecutionDependencies[Key] | undefined;
+}): Partial<InlineExecutionDependencies>;

package/dist/core/inline-execution-strategy.context-options.js

@@ -0,0 +1,56 @@
+export function createInlineContextOptions(dependencies, registration, parameters, workflowAbort) {
+  return {
+    workflowId: parameters.workflowId,
+    workflowType: parameters.workflowType,
+    startedAt: parameters.startedAt ?? dependencies.getNow(),
+    abortController: workflowAbort,
+    getNow: dependencies.getNow,
+    nestingDepth: parameters.nestingDepth ?? 0,
+    executionStateOwnerId: parameters.executionStateOwnerId ?? parameters.workflowId,
+    ...parameters.sleepReferenceTime !== void 0 && {
+      sleepReferenceTime: parameters.sleepReferenceTime
+    },
+    ...dependencies.resolveWorkflowType !== void 0 && {
+      resolveWorkflowType: dependencies.resolveWorkflowType
+    },
+    ...registration.searchAttributes && {
+      searchAttributeSchema: registration.searchAttributes
+    },
+    ...parameters.deadline !== void 0 && { deadline: parameters.deadline },
+    ...resolveWorkflowScopedCallbackOptions(dependencies, parameters.workflowId),
+    services: dependencies.getWorkflowServices?.(parameters.workflowId),
+    ...resolveLogSinkOption(dependencies)
+  };
+}
+function resolveWorkflowScopedCallbackOptions(dependencies, workflowId) {
+  const { registerCancelHandler, recordFinalizerState } = dependencies;
+  return {
+    ...registerCancelHandler !== void 0 && {
+      registerCancelHandler: (handler) => registerCancelHandler(workflowId, handler)
+    },
+    ...recordFinalizerState !== void 0 && {
+      recordFinalizerState: (value) => recordFinalizerState(workflowId, value)
+    }
+  };
+}
+function resolveLogSinkOption(dependencies) {
+  const logSink = dependencies.getLogSink?.();
+  return logSink === void 0 ? {} : { logSink };
+}
+export function optionalInlineDependencies(candidates) {
+  return {
+    ...candidates.getComposedWorkflowInterceptor !== void 0 && {
+      getComposedWorkflowInterceptor: candidates.getComposedWorkflowInterceptor
+    },
+    ...candidates.registerCancelHandler !== void 0 && {
+      registerCancelHandler: candidates.registerCancelHandler
+    },
+    ...candidates.recordFinalizerState !== void 0 && {
+      recordFinalizerState: candidates.recordFinalizerState
+    },
+    ...candidates.getWorkflowServices !== void 0 && {
+      getWorkflowServices: candidates.getWorkflowServices
+    },
+    ...candidates.getLogSink !== void 0 && { getLogSink: candidates.getLogSink }
+  };
+}

package/dist/core/inline-execution-strategy.d.ts

@@ -11,38 +11,8 @@
  */
 import { Context } from './context.ts';
 import type { ExecutionStrategy } from './execution-strategy.ts';
-import type { ComposedWorkflowInterceptor } from './interceptor.ts';
-import type { FailureCategory, OperationOutcome, SearchAttributeSchema, WorkerOutboundMessage, WorkflowFunction } from './types.ts';
-export interface InlineExecutionDependencies {
-    getRegistration: (workflowType: string) => {
-        handler: WorkflowFunction;
-        version: string;
-        searchAttributes?: SearchAttributeSchema;
-    } | undefined;
-    getNow: () => number;
-    resolveWorkflowType?: (target: string | Function) => string;
-    maxNestingDepth: number;
-    development?: boolean;
-    getComposedWorkflowInterceptor?: () => ComposedWorkflowInterceptor | null;
-    registerCancelHandler?: (workflowId: string, handler: () => Promise<void> | void) => () => void;
-    /**
-     * Look up the non-serialized per-run `services` value for a workflow, exposed
-     * to the body as `ctx.services`. Returns `undefined` when none was supplied.
-     */
-    getWorkflowServices?: (workflowId: string) => unknown;
-}
-type InlineStartWorkflowParameters = {
-    workflowId: string;
-    workflowType: string;
-    input: unknown;
-    checkpoint: ArrayBuffer | Uint8Array;
-    nestingDepth?: number;
-    executionStateOwnerId?: string;
-    startedAt?: number;
-    sleepReferenceTime?: number;
-    deadline?: number;
-    headers?: [string, string][];
-};
+import type { InlineExecutionDependencies, InlineStartWorkflowParameters } from './inline-execution-strategy.context-options.ts';
+import type { FailureCategory, OperationOutcome, WorkerOutboundMessage } from './types.ts';
 export declare class InlineExecutionStrategy implements ExecutionStrategy {
     #private;
     constructor(dependencies: InlineExecutionDependencies);
@@ -54,8 +24,33 @@ export declare class InlineExecutionStrategy implements ExecutionStrategy {
         operationResult: OperationOutcome;
     }): void;
     cancelWorkflow(workflowId: string): void;
-    parkWorkflow(workflowId: string): void;
+    /**
+     * Evict a workflow's in-memory execution state (generator, abort controller,
+     * live context, tracked turns/advances).
+     *
+     * By default this is a hard eviction: nothing about the run stays reachable —
+     * which is what the suspend/general teardown path requires. The inline
+     * `waitForSignal` parking optimization opts into `retainContext: true` so the
+     * run's Context survives in `#parkedContexts` and its `ctx.onQuery` handlers
+     * stay callable while the run is parked. Retention is therefore strictly
+     * opt-in at the one call site that wants it; every other caller gets eviction.
+     */
+    parkWorkflow(workflowId: string, options?: {
+        retainContext?: boolean;
+    }): void;
+    /** Returns the live Context for a workflow, or `undefined` if not running. For parked workflows use {@link getParkedContext}. */
     getContext(workflowId: string): Context | undefined;
+    /** Returns the retained Context for a parked workflow, or `undefined` if not parked or already cleaned up. */
+    getParkedContext(workflowId: string): Context | undefined;
+    /**
+     * Drop any retained parked Context for a workflow without touching the abort
+     * controller or other live state. Terminal cleanup calls this so a workflow
+     * that reached a terminal status while parked (e.g. a failed resume, or normal
+     * completion of a run that had parked) cannot keep resolving `ctx.onQuery`
+     * handlers from a stale parked Context — and so the Context is not retained
+     * for the engine's lifetime.
+     */
+    clearParkedContext(workflowId: string): void;
     getAbortController(workflowId: string): AbortController | undefined;
     waitForWorkflowTurn(workflowId: string): Promise<void> | undefined;
     waitForWorkflowAdvance(workflowId: string): Promise<void> | undefined;
@@ -71,11 +66,11 @@ export declare class InlineExecutionStrategy implements ExecutionStrategy {
      */
     throwIntoWorkflow(workflowId: string, error: unknown, operationFailureCategory?: FailureCategory): void;
     /**
-     * Store a context and generator that were created externally (used by
-     * the engine's resume() path where context setup is more complex).
+     * Store a context and generator created externally (engine resume path).
+     * Clears any retained parked context so a concurrent query sees the new
+     * live context rather than the stale parked one.
      */
     adoptWorkflow(workflowId: string, generator: AsyncGenerator, context: Context, abortController: AbortController): void;
     [Symbol.dispose](): void;
     [Symbol.asyncDispose](): Promise<void>;
 }
-export {};

package/dist/core/inline-execution-strategy.js

@@ -3,38 +3,14 @@ import {
   classifyErrorAsFailureCategory,
   errorFromFailedOperationOutcome
 } from "./failure-categories.js";
-function createInlineContextOptions(dependencies, registration, parameters, workflowAbort) {
-  const { registerCancelHandler } = dependencies;
-  return {
-    workflowId: parameters.workflowId,
-    workflowType: parameters.workflowType,
-    startedAt: parameters.startedAt ?? dependencies.getNow(),
-    abortController: workflowAbort,
-    getNow: dependencies.getNow,
-    nestingDepth: parameters.nestingDepth ?? 0,
-    executionStateOwnerId: parameters.executionStateOwnerId ?? parameters.workflowId,
-    ...parameters.sleepReferenceTime !== void 0 && {
-      sleepReferenceTime: parameters.sleepReferenceTime
-    },
-    ...dependencies.resolveWorkflowType !== void 0 && {
-      resolveWorkflowType: dependencies.resolveWorkflowType
-    },
-    ...registration.searchAttributes && {
-      searchAttributeSchema: registration.searchAttributes
-    },
-    ...parameters.deadline !== void 0 && { deadline: parameters.deadline },
-    ...registerCancelHandler !== void 0 && {
-      registerCancelHandler: (handler) => registerCancelHandler(parameters.workflowId, handler)
-    },
-    services: dependencies.getWorkflowServices?.(parameters.workflowId)
-  };
-}
+import { createInlineContextOptions } from "./inline-execution-strategy.context-options.js";
 
 export class InlineExecutionStrategy {
   #dependencies;
   #generators;
   #abortControllers;
   #contexts;
+  #parkedContexts;
   #workflowAdvances;
   #workflowTurns;
   #messageHandler;
@@ -43,6 +19,7 @@ export class InlineExecutionStrategy {
     this.#generators = new Map;
     this.#abortControllers = new Map;
     this.#contexts = new Map;
+    this.#parkedContexts = new Map;
     this.#workflowAdvances = new Map;
     this.#workflowTurns = new Map;
     this.#messageHandler = null;
@@ -93,12 +70,21 @@ export class InlineExecutionStrategy {
       abortController.abort();
     this.#cleanup(workflowId);
   }
-  parkWorkflow(workflowId) {
+  parkWorkflow(workflowId, options) {
+    const context = options?.retainContext ? this.#contexts.get(workflowId) ?? this.#parkedContexts.get(workflowId) : void 0;
     this.#cleanup(workflowId);
+    if (context !== void 0)
+      this.#parkedContexts.set(workflowId, context);
   }
   getContext(workflowId) {
     return this.#contexts.get(workflowId);
   }
+  getParkedContext(workflowId) {
+    return this.#parkedContexts.get(workflowId);
+  }
+  clearParkedContext(workflowId) {
+    this.#parkedContexts.delete(workflowId);
+  }
   getAbortController(workflowId) {
     return this.#abortControllers.get(workflowId);
   }
@@ -124,6 +110,7 @@ export class InlineExecutionStrategy {
     this.#throwIntoGenerator(workflowId, generator, error, operationFailureCategory);
   }
   adoptWorkflow(workflowId, generator, context, abortController) {
+    this.#parkedContexts.delete(workflowId);
     this.#generators.set(workflowId, generator);
     this.#contexts.set(workflowId, context);
     this.#abortControllers.set(workflowId, abortController);
@@ -132,6 +119,7 @@ export class InlineExecutionStrategy {
     this.#generators.clear();
     this.#abortControllers.clear();
     this.#contexts.clear();
+    this.#parkedContexts.clear();
     this.#workflowAdvances.clear();
     this.#workflowTurns.clear();
     this.#messageHandler = null;
@@ -257,6 +245,7 @@ export class InlineExecutionStrategy {
     this.#generators.delete(workflowId);
     this.#abortControllers.delete(workflowId);
     this.#contexts.delete(workflowId);
+    this.#parkedContexts.delete(workflowId);
     if (!options?.preserveTrackedAdvance)
       this.#workflowAdvances.delete(workflowId);
     if (!options?.preserveTrackedTurn)

package/dist/core/list-filter-validation.d.ts

@@ -11,7 +11,7 @@
 import { z } from 'zod';
 import { isFailureCategory } from './failure-categories.ts';
 import type { FailureCategory, WorkflowStatus } from './types/identity.ts';
-import type { ListFilter } from './types/options.ts';
+import type { ListFilter } from './types/list-options.ts';
 import { WeftError } from './weft-error.ts';
 /**
  * Concrete object schema for {@link ListFilter}. Supports `.omit()` and

package/dist/core/payload-size.d.ts

@@ -4,7 +4,7 @@ import { WeftError } from './weft-error.ts';
  * {@link PayloadSizeExceededError} message so operators can tell which
  * admission point rejected the value.
  */
-export type PayloadKind = 'workflow input' | 'signal payload' | 'activity result';
+export type PayloadKind = 'workflow input' | 'signal payload' | 'activity result' | 'finalizer state';
 /**
  * Thrown at admission when a payload's serialized (codec-encoded) size exceeds
  * the operator-configured {@link PayloadSizePolicy.maxBytes}. The rejection