@lostgradient/weft 0.2.0 → 0.3.0

package/dist/core/engine/termination.js

@@ -6,6 +6,7 @@ export {
   cleanupTerminalWorkflowSynchronously,
   cleanupWaiters,
   cleanupWorkflowStorage,
+  evictSuspendedWorkflowWaiters,
   finalizeScheduledWorkflowTerminal,
   handleCleanupError,
   runDeferredTerminalCleanup
@@ -21,3 +22,4 @@ export {
   terminateWorkflow,
   timeoutWorkflow
 } from "./termination/complete.js";
+export { suspendWorkflow } from "./termination/suspend.js";

package/dist/core/engine/validation.js

@@ -2,6 +2,7 @@ import { decode } from "../codec.js";
 import { isRecord } from "../debug-output.js";
 import { normalizeFailureCategory } from "../failure-categories.js";
 import { coerceStartWorkflowId, parseStartWorkflowDuration } from "../start-workflow-validation.js";
+import { DEFAULT_WORKFLOW_VERSION } from "../versioning.js";
 import { isWorkflowTagArray } from "../workflow-tags.js";
 const WORKFLOW_TIMELINE_STATUSES = new Set([
   "running",
@@ -55,7 +56,10 @@ export function isValidDecodedTags(value) {
   return value === void 0 || isWorkflowTagArray(value);
 }
 export function decodeWorkflowState(bytes) {
-  const state = decode(bytes);
+  const decoded = decode(bytes);
+  if (isRecord(decoded))
+    liftFlatVersionTuple(decoded);
+  const state = decoded;
   if ("tenant" in state)
     delete state.tenant;
   if (!isValidDecodedTags(state.tags)) {
@@ -78,6 +82,26 @@ export function decodeWorkflowState(bytes) {
     }
   return state;
 }
+function liftFlatVersionTuple(record) {
+  const flatVersion = record.version, hasFlatVersion = typeof flatVersion === "string";
+  if (isWorkflowVersionTuple(record.versionTuple)) {
+    delete record.version;
+    delete record.agentVersion;
+    delete record.toolVersions;
+    return;
+  }
+  const { agentVersion: flatAgentVersion, toolVersions: flatToolVersions } = record, versionTuple = {
+    workflowVersion: hasFlatVersion ? flatVersion : DEFAULT_WORKFLOW_VERSION,
+    ...typeof flatAgentVersion === "string" && { agentVersion: flatAgentVersion },
+    ...Array.isArray(flatToolVersions) && flatToolVersions.every((entry) => typeof entry === "string") && {
+      toolVersions: flatToolVersions
+    }
+  };
+  record.versionTuple = versionTuple;
+  delete record.version;
+  delete record.agentVersion;
+  delete record.toolVersions;
+}
 export function normalizeRetentionDuration(value, fieldName) {
   if (value === void 0)
     return;

package/dist/core/engine/workflow-feed.d.ts

@@ -7,9 +7,11 @@ import type { EngineInternals } from './internals.ts';
  */
 export type WorkflowFeedSelector = 'events' | 'tokens';
 /**
- * Hard-coded stream key for the `tokens` selector. Matches the
- * legacy REST SSE endpoint's key so resumption cursors round-trip
- * across transports.
+ * Hard-coded stream key for the `tokens` selector. Every transport that
+ * exposes the token feed — `engine.getStreamChunks(id, 'tokens')` and the REST
+ * SSE / WebSocket stream-chunk routes layered on it — keys its stored chunks
+ * under this single value, so a resumption cursor issued by one transport
+ * round-trips through another.
  */
 export declare const TOKENS_STREAM_KEY = "tokens";
 /** Record `kind` for every token stream chunk emitted by the feed. */

package/dist/core/events/event-map.d.ts

@@ -4,7 +4,7 @@ import type { AttributesChangedEvent } from './attribute-events.ts';
 import type { SignalDeliveredEvent, SignalReceivedEvent } from './signal-events.ts';
 import type { AlertFiredEvent, AlertResolvedEvent, CheckpointSizeWarningEvent, CleanupWarningEvent, ConstraintViolatedEvent, DevelopmentWarningEvent, StorageSizeReportedEvent } from './system-events.ts';
 import type { UpdateCompletedEvent, UpdateReceivedEvent } from './update-events.ts';
-import type { WorkflowCancelledEvent, WorkflowCompletedEvent, WorkflowFailedEvent, WorkflowRecoverySkippedEvent, WorkflowResumedEvent, WorkflowStartedEvent, WorkflowTimedOutEvent } from './workflow-events.ts';
+import type { WorkflowCancelledEvent, WorkflowCompletedEvent, WorkflowFailedEvent, WorkflowRecoverySkippedEvent, WorkflowResumedEvent, WorkflowStartedEvent, WorkflowSuspendedEvent, WorkflowTimedOutEvent } from './workflow-events.ts';
 /**
  * Record mapping each event-name string the {@link Engine} dispatches to its
  * corresponding typed `Event` subclass. Use this as the type parameter for
@@ -31,6 +31,7 @@ export type WeftEventMap = {
     'workflow:cancelled': WorkflowCancelledEvent;
     'workflow:timed-out': WorkflowTimedOutEvent;
     'workflow:resumed': WorkflowResumedEvent;
+    'workflow:suspended': WorkflowSuspendedEvent;
     'workflow:recovery-skipped': WorkflowRecoverySkippedEvent;
     'activity:started': ActivityStartedEvent;
     'activity:completed': ActivityCompletedEvent;

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

@@ -160,6 +160,29 @@ export declare class WorkflowResumedEvent extends Event {
     readonly fromStep: number;
     constructor(workflowId: string, fromStep: number);
 }
+/**
+ * Fired when a running workflow is explicitly suspended via
+ * `handle.suspend()` / `engine.suspend(id)`. Suspension is a non-terminal pause:
+ * the workflow keeps its checkpoint and is later resumable. This event is
+ * intentionally NOT in {@link WORKFLOW_TERMINAL_EVENT_TYPES} — a suspended
+ * workflow has not ended, and `handle.result()` stays pending.
+ *
+ * @example
+ * ```ts
+ * 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);
+ * });
+ * ```
+ */
+export declare class WorkflowSuspendedEvent extends Event {
+    static readonly type: "workflow:suspended";
+    readonly workflowId: string;
+    constructor(workflowId: string);
+}
 /**
  * Reason carried by {@link WorkflowRecoverySkippedEvent}.
  *

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

@@ -77,6 +77,15 @@ export class WorkflowResumedEvent extends Event {
   }
 }
 
+export class WorkflowSuspendedEvent extends Event {
+  static type = "workflow:suspended";
+  workflowId;
+  constructor(workflowId) {
+    super(WorkflowSuspendedEvent.type);
+    this.workflowId = workflowId;
+  }
+}
+
 export class WorkflowRecoverySkippedEvent extends Event {
   static type = "workflow:recovery-skipped";
   workflowId;

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

@@ -25,6 +25,11 @@ export interface InlineExecutionDependencies {
     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;

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

@@ -25,7 +25,8 @@ function createInlineContextOptions(dependencies, registration, parameters, work
     ...parameters.deadline !== void 0 && { deadline: parameters.deadline },
     ...registerCancelHandler !== void 0 && {
       registerCancelHandler: (handler) => registerCancelHandler(parameters.workflowId, handler)
-    }
+    },
+    services: dependencies.getWorkflowServices?.(parameters.workflowId)
   };
 }
 

package/dist/core/list-filter-validation.js

@@ -7,7 +7,8 @@ const WORKFLOW_STATUSES = [
   "completed",
   "failed",
   "cancelled",
-  "timed-out"
+  "timed-out",
+  "suspended"
 ], ID_PREFIX_PATTERN = /^[A-Za-z0-9_-]+$/, workflowStatusSchema = z.enum(WORKFLOW_STATUSES), failureCategorySchema = z.enum(FAILURE_CATEGORIES), timeRangeSchema = z.object({
   gte: z.number().optional(),
   lte: z.number().optional(),

package/dist/core/start-workflow-validation.d.ts

@@ -2,11 +2,33 @@ import type { Duration } from './types.ts';
 import { WeftError } from './weft-error.ts';
 export declare const MAX_WORKFLOW_TAGS = 32;
 export declare const MAX_WORKFLOW_TAG_BYTES = 128;
+/**
+ * Upper bound on a start `idempotencyKey`, in UTF-8 bytes. `startOrSignal`
+ * derives a signal id of `start-idem:${key}` (an 11-byte prefix) from the key,
+ * and `validateSignalId` caps a signal id at 128 bytes — so the raw key must fit
+ * in `128 - 11 = 117` bytes for the derived id to stay within that ceiling.
+ */
+export declare const MAX_IDEMPOTENCY_KEY_BYTES = 117;
 export declare class StartWorkflowValidationError extends WeftError<'StartWorkflowValidationError'> {
     constructor(message: string);
 }
 export declare const assertExclusiveStartWorkflowOptions: (startAt: unknown, startAfter: unknown) => void;
 export declare const coerceStartWorkflowId: (value: unknown, fieldName: string) => string;
+/**
+ * Coerce a transport-supplied idempotency key to a non-empty string. The key is
+ * a caller-chosen dedup token (it becomes part of a `start-idem:` storage key),
+ * so an empty string — which would collide across unrelated starts — is rejected.
+ */
+export declare const coerceStartWorkflowIdempotencyKey: (value: unknown, fieldName: string) => string;
+/**
+ * Validate an already-string `idempotencyKey`: non-empty (an empty key would
+ * collide across unrelated starts under the shared `start-idem:` mapping) and at
+ * most {@link MAX_IDEMPOTENCY_KEY_BYTES} UTF-8 bytes (so the derived
+ * `start-idem:${key}` signal id stays within the signal-id ceiling). Shared by
+ * the transport coercion and the engine boundary so a direct `engine.start`
+ * caller gets the same guarantees as an HTTP caller.
+ */
+export declare const assertValidIdempotencyKey: (value: string, fieldName: string) => string;
 export declare function coerceStartWorkflowTimestamp(value: unknown, fieldName: string): number;
 export declare function parseStartWorkflowDuration(duration: Duration, fieldName: string): number;
 export declare function coerceStartWorkflowDuration(value: unknown, fieldName: string): Duration;

package/dist/core/start-workflow-validation.js

@@ -1,7 +1,7 @@
 import { parseDuration } from "./scheduler.js";
 import { WeftError } from "./weft-error.js";
 import { assertValidWorkflowId } from "./workflow-identifiers.js";
-export const MAX_WORKFLOW_TAGS = 32, MAX_WORKFLOW_TAG_BYTES = 128;
+export const MAX_WORKFLOW_TAGS = 32, MAX_WORKFLOW_TAG_BYTES = 128, MAX_IDEMPOTENCY_KEY_BYTES = 117;
 const textEncoder = new TextEncoder, EXCLUSIVE_START_WORKFLOW_OPTIONS_ERROR = "Provide only one of startAt or startAfter";
 
 export class StartWorkflowValidationError extends WeftError {
@@ -22,6 +22,16 @@ export const assertExclusiveStartWorkflowOptions = (startAt, startAfter) => {
     const message = error instanceof Error ? error.message : String(error);
     throw new StartWorkflowValidationError(message);
   }
+}, coerceStartWorkflowIdempotencyKey = (value, fieldName) => {
+  if (typeof value !== "string")
+    throw new StartWorkflowValidationError(`${fieldName} must be a string`);
+  return assertValidIdempotencyKey(value, fieldName);
+}, assertValidIdempotencyKey = (value, fieldName) => {
+  if (value.length === 0)
+    throw new StartWorkflowValidationError(`${fieldName} must not be empty`);
+  if (textEncoder.encode(value).byteLength > MAX_IDEMPOTENCY_KEY_BYTES)
+    throw new StartWorkflowValidationError(`${fieldName} must be at most ${MAX_IDEMPOTENCY_KEY_BYTES} UTF-8 bytes`);
+  return value;
 };
 export function coerceStartWorkflowTimestamp(value, fieldName) {
   if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)

package/dist/core/step-context.d.ts

@@ -7,19 +7,23 @@
  *
  * @module core/step-context
  */
-import type { ContextOperationRequest } from './context.ts';
 import type { StepWorkflowContext, WorkflowFunction } from './types.ts';
 interface QueuedOperation {
-    request: ContextOperationRequest;
+    /** Explicit, user-supplied step name. Used as the durable activity label. */
+    name: string;
+    /** The zero-argument step body. Executed by the engine as an inline activity. */
+    fn: () => unknown;
     resolve: (value: unknown) => void;
     reject: (reason: unknown) => void;
 }
 /**
  * Internal implementation of {@link StepWorkflowContext} for step-based
- * ("progressive disclosure") workflows. Wraps the generator protocol in a
- * queue so that plain `async function` workflows can be registered on the
- * engine without writing explicit generators. Build via
- * {@link compileStepWorkflow} rather than constructing directly.
+ * ("progressive disclosure") workflows. Each `step()` call is a thin async
+ * enqueue; the compiled generator (see {@link compileStepWorkflow}) drains the
+ * queue and runs each step through the engine's durable activity machinery, so
+ * a completed step is replayed from the checkpoint rather than re-executed
+ * after a crash. Build via {@link compileStepWorkflow} rather than constructing
+ * directly.
  *
  * @example
  * ```ts

package/dist/core/step-context.js

@@ -1,3 +1,5 @@
+import { asConcreteContext, runActivityWithRetry } from "./context/run-operation.js";
+
 export class StepContext {
   workflowId;
   signal;
@@ -9,18 +11,8 @@ export class StepContext {
     this.signal = signal;
   }
   async step(name, fn) {
-    const operationId = crypto.randomUUID(), { promise, resolve, reject } = Promise.withResolvers();
-    this.#queue.push({
-      request: {
-        type: "activity",
-        operationId,
-        activityName: name,
-        fn,
-        input: void 0
-      },
-      resolve,
-      reject
-    });
+    const { promise, resolve, reject } = Promise.withResolvers();
+    this.#queue.push({ name, fn, resolve, reject });
     this.#notifyQueue?.();
     return promise;
   }
@@ -43,8 +35,8 @@ export class StepContext {
   }
 }
 export function compileStepWorkflow(stepFunction) {
-  return async function* (_rawContext, input) {
-    const rawContext = _rawContext, stepContext = new StepContext(rawContext.workflowId, rawContext.signal);
+  return async function* (publicContext, input) {
+    const rawContext = asConcreteContext(publicContext), stepContext = new StepContext(rawContext.workflowId, rawContext.signal);
     let workflowResult, workflowError;
     const userPromise = stepFunction(stepContext, input).then((result) => {
       workflowResult = result;
@@ -59,7 +51,7 @@ export function compileStepWorkflow(stepFunction) {
       if (queued === null)
         break;
       try {
-        const result = yield queued.request;
+        const result = yield* runActivityWithRetry(rawContext, queued.fn, [], queued.name);
         queued.resolve(result);
       } catch (error) {
         queued.reject(error);

package/dist/core/types/activity.d.ts

@@ -218,12 +218,15 @@ export interface ActivityDefinition<TInput = unknown, TOutput = unknown, TName e
     /** Activity implementation called by the engine or worker. */
     execute: ActivityFunction<TInput, TOutput>;
     /**
-     * Optional post-execution verifier.
+     * Optional verifier, invoked in two phases (see
+     * `ActivityVerificationContext.phase`).
      *
      * During normal post-execution validation, return `true` to confirm the
      * activity result or `false` to reject it. During pre-dispatch crash recovery
-     * for keyed activities, return an explicit reconciliation state; legacy boolean
-     * answers are not treated as proof of external completion.
+     * for keyed activities, return an explicit reconciliation state. A boolean is
+     * the post-execution result shape, not a Tier-0 reconciliation state, so a
+     * boolean returned during pre-dispatch reconciliation fails closed rather than
+     * being treated as proof of external completion.
      */
     verify?: ActivityVerifier<TInput, TOutput>;
     retry?: RetryPolicy;

package/dist/core/types/identity.d.ts

@@ -51,5 +51,12 @@ export type FailureCategory = 'application' | 'timeout' | 'cancellation' | 'reso
  * Read this off `(await handle.state()).status` to learn whether a workflow
  * is still running, finished cleanly, or failed. Pass it to `engine.list()`
  * filters to scope queries by status.
+ *
+ * `'suspended'` is a non-terminal, non-running pause: a workflow that was
+ * explicitly suspended via {@link WorkflowHandle.suspend} (or
+ * `engine.suspend(id)`) keeps its checkpoint and is resumable via
+ * {@link WorkflowHandle.resume} (or `engine.resume(id)`), but is NOT
+ * auto-recovered by `engine.recoverAll()` — suspension is client-driven
+ * preemption, not a fault condition.
  */
-export type WorkflowStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled' | 'timed-out';
+export type WorkflowStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled' | 'timed-out' | 'suspended';

package/dist/core/types/launch-metadata.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Launch context for a workflow, reconstructed from its persisted state by
+ * {@link WorkflowHandle.getLaunchMetadata}. Lets a caller — typically after
+ * `engine.recoverAll()` — recover the original input and the launch options that
+ * survive in durable state, without keeping a side table that correlates a
+ * recovered workflow back to how it was started.
+ *
+ * `launchOptions` carries only the options recoverable *faithfully* from
+ * persisted state: `id` (always) and `tags`. Note `tags` is the run's *current*
+ * tag set (tags are mutable via `addTags`/`removeTags`), not necessarily the
+ * tags passed at launch. Deliberately excluded: `executionTimeout` (state
+ * stores the absolute deadline, not the original duration, so it cannot be
+ * reproduced exactly); `idempotencyKey` (no durable trace); `searchAttributes`
+ * (live in their own durable index — read them via
+ * {@link WorkflowHandle.getAttributes}); and `services` (non-serializable,
+ * re-provided on recovery by {@link EngineOptions.resolveWorkflowServices}).
+ *
+ * @example
+ * ```ts
+ * import { type LaunchMetadata } from '@lostgradient/weft';
+ *
+ * function describe(metadata: LaunchMetadata): string {
+ *   return `input=${JSON.stringify(metadata.input)} id=${metadata.launchOptions.id}`;
+ * }
+ * ```
+ */
+export interface LaunchMetadata {
+    input: unknown;
+    launchOptions: {
+        id: string;
+        tags?: string[];
+    };
+}

package/dist/core/types/message-handles.d.ts

@@ -111,6 +111,31 @@ export interface SignalOptions<TInput = void> {
 export interface SignalDeliveryOptions {
     readonly signalId?: string;
 }
+/**
+ * The signal half of `startOrSignal` (signal-with-start): a signal `name`, an
+ * optional `payload`, and an optional `signalId`. When `signalId` is omitted it
+ * is derived from `options.idempotencyKey`. The id is load-bearing for
+ * convergence — concurrent callers deliver one signal only when they share it,
+ * and independent webhook retries share only the idempotency key — so a
+ * caller-supplied `signalId` covers the single-caller case while idempotent
+ * convergence relies on the derived-from-key value.
+ *
+ * @example
+ * ```ts
+ * import type { StartOrSignalSignal } from '@lostgradient/weft';
+ *
+ * const signal: StartOrSignalSignal = {
+ *   name: 'webhook',
+ *   payload: { event: 'payment.succeeded' },
+ * };
+ * void signal;
+ * ```
+ */
+export interface StartOrSignalSignal {
+    readonly name: string;
+    readonly payload?: unknown;
+    readonly signalId?: string;
+}
 /**
  * Create a typed workflow signal handle. When an `inputSchema` is supplied
  * via options, the payload type is inferred from the schema's

package/dist/core/types/options.d.ts

@@ -9,19 +9,28 @@ import type { PayloadSizePolicy } from './payload-size-policy.ts';
 import type { Duration, RetentionPolicy } from './retry-retention.ts';
 import type { SearchAttributeHandle, SearchAttributeValue } from './search-attributes.ts';
 import type { Serializer } from './serializer.ts';
+import type { WorkflowServicesResolution, WorkflowServicesResolverInfo } from './services-resolution.ts';
 /**
  * Options accepted by `engine.start(type, input, options?)`.
  *
  * Every field is optional. `id` lets you specify your own workflow ID;
- * `idempotencyKey` enforces single-execution semantics within a window;
- * `executionTimeout` caps wall-clock time; `startAt`/`startAfter` defer
+ * `idempotencyKey` enforces at-most-once starts (a repeated key returns the
+ * existing run instead of starting a second, even after it reaches a terminal
+ * state); `executionTimeout` caps wall-clock time; `startAt`/`startAfter` defer
  * execution; `tags` and `searchAttributes` make the workflow discoverable
- * via filters.
+ * via filters. `id` and `idempotencyKey` are mutually exclusive — idempotency
+ * assigns its own generated id and dedups through the key.
  *
- * `HttpClient.start` forwards `searchAttributes` to the server. It rejects
- * `idempotencyKey` until the HTTP start protocol exposes matching
- * single-execution semantics, so callers do not accidentally rely on a
- * silently dropped option.
+ * The `idempotencyKey` mapping is durable and permanent: it survives the run
+ * reaching a terminal state, so repeat calls keep returning the same handle. When
+ * the workflow record is purged or swept by retention the mapping itself survives
+ * (purge does not touch the `start-idem:` keyspace) but now points at a gone run;
+ * a call with that spent key throws {@link IdempotencyKeyPurgedError} (mapped to
+ * HTTP 409 over REST/JSON-RPC) rather than silently starting a new run.
+ *
+ * Both `LocalClient.start` and `HttpClient.start` forward `idempotencyKey` and
+ * `searchAttributes` to the server, so single-execution semantics hold across
+ * transports. Idempotent start requires a storage backend with `conditionalBatch`.
  *
  * @example Start a delayed workflow with tags and search attributes
  * ```ts
@@ -52,6 +61,31 @@ export interface StartOptions {
     startAfter?: Duration;
     tags?: string[];
     searchAttributes?: Record<string, SearchAttributeValue>;
+    /**
+     * Host-supplied, per-run capabilities exposed to the workflow body as
+     * `ctx.services` (live clients, closures, tool registries). The value is
+     * **never checkpointed**; on a fresh-process recovery it is re-provided by the
+     * engine's {@link EngineOptions.resolveWorkflowServices} resolver before the
+     * generator advances.
+     *
+     * Inline execution mode only. Passing `services` under
+     * `workflowExecutionMode: 'worker'` throws at `engine.start()`, because a
+     * non-serializable value cannot cross to a Worker.
+     */
+    services?: unknown;
+    /**
+     * When `false`, `engine.start()` resolves only after the workflow has begun
+     * executing (its generator has been driven its first turn), not merely after
+     * the initial state is persisted. The default (`true`) returns a handle as
+     * soon as state is written and queues execution onto a macrotask, so a caller
+     * cannot assume the run is live without a round-trip. Use `defer: false` when a
+     * caller — or a test — must rely on the run being live immediately after
+     * `await engine.start(...)`. If the body throws on its first turn, `start()`
+     * still resolves; observe the failure via `handle.result()`. Inline mode only;
+     * throws at `engine.start()` under `workflowExecutionMode: 'worker'` or with a
+     * delayed start (`startAt`/`startAfter`), neither of which has liveness to await.
+     */
+    defer?: boolean;
 }
 /**
  * Options for {@link Engine.fork}. Controls which checkpoint step to fork
@@ -103,6 +137,25 @@ export interface EngineOptions {
     retention?: RetentionPolicy;
     retentionSweepInterval?: Duration;
     retentionSweepBatchSize?: number;
+    /**
+     * Enable a best-effort, warn-only detector for a SECOND engine instance writing
+     * to the same durable store — a smoke alarm for singleton misconfiguration (an
+     * autoscaler above one replica, or overlapping rolling deploys). Default `false`.
+     * This is **liveness, not fencing**: it never blocks boot, gates recovery, or
+     * prevents duplicate execution — enforce one instance at the infrastructure layer
+     * (one replica + a `Recreate` deploy, or a single systemd unit). When enabled,
+     * each engine writes a periodic heartbeat and warns (`process.emitWarning`) when
+     * it sees another instance's heartbeat advancing while it runs. The periodic
+     * writes are an ongoing cost, so leave it off unless you want the backstop.
+     */
+    detectSecondInstance?: boolean;
+    /**
+     * Heartbeat interval for {@link EngineOptions.detectSecondInstance} (default
+     * `15s`). A foreign heartbeat must advance across two intervals before warning,
+     * so this also sets how long a deploy overlap must last before it warns — keep it
+     * well above your deploy drain window. Ignored when detection is disabled.
+     */
+    secondInstanceHeartbeatInterval?: Duration;
     /**
      * History circuit-breaker thresholds. When `history.maxEvents` is set, a
      * workflow whose event-log record count would exceed it is forced to a
@@ -197,6 +250,36 @@ export interface EngineOptions {
      * after passing it has no effect.
      */
     interceptors?: readonly Interceptor[];
+    /**
+     * Re-provide the non-serialized per-run `services` value (see
+     * {@link StartOptions.services}) for a workflow recovered in a fresh process.
+     * `engine.recoverAll()` and `engine.resume(id)` call this **before** the
+     * generator is driven forward (and the delayed-start timer handler calls it
+     * for a `startAfter`/`startAt` run that crashed before firing), so the resumed
+     * body can read `ctx.services` exactly as it did before the crash.
+     *
+     * Return `{ status: 'available', services }` to supply the rebuilt
+     * capabilities, or `{ status: 'unavailable', reason }` to fail just that one
+     * recovered run — the engine and every other recovered run are unaffected.
+     * Without a resolver, a recovered inline workflow that reads `ctx.services`
+     * sees `undefined`.
+     *
+     * Contract a fresh integrator must know:
+     * - Fires only for recovered inline runs that were launched WITH `services`
+     *   (those carrying the durable "expects services" marker). A run started
+     *   without `services` never reaches the resolver, regardless of what it would
+     *   return — so a fail-closed resolver does not fail innocent no-services runs.
+     * - `{ status: 'unavailable' }` permanently fails the run (terminal `failed`,
+     *   `system` category) with `reason` as the message — not a "retry later"
+     *   signal. A resolver *throw* is treated identically (error message → reason).
+     * - May be called again on a later boot if a prior recovery left the run still
+     *   recoverable (e.g. the terminal-fail commit faulted), so keep it idempotent.
+     * - Inline only; worker-mode runs never invoke it.
+     *
+     * Engine-scoped: each engine instance carries its own resolver, so two engines
+     * in one process never collide on per-run dependency reconstruction.
+     */
+    resolveWorkflowServices?: (info: WorkflowServicesResolverInfo) => WorkflowServicesResolution | Promise<WorkflowServicesResolution>;
 }
 /**
  * Filter criteria for {@link Engine.list}. All fields are optional and

package/dist/core/types/reviews.d.ts

@@ -54,7 +54,8 @@ export type ReviewStatus = 'pending' | 'completed';
  * Filter accepted by `engine.listReviews(filter?)` and the `/v1/reviews`
  * transport surfaces.
  *
- * Omitting `status` preserves the legacy pending-only behavior.
+ * Omitting `status` lists pending reviews; pass `status: 'completed'` to list
+ * completed reviews instead.
  *
  * @example
  * ```ts

package/dist/core/types/services-resolution.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Result of {@link EngineOptions.resolveWorkflowServices}. An explicit union
+ * rather than a nullable return: `'unavailable'` is a deliberate, named outcome
+ * (the run's dependencies cannot be rebuilt in this process) that fails just
+ * that recovered run — it does not overload the resolved value with a lifecycle
+ * signal.
+ *
+ * @example
+ * ```ts
+ * import { type WorkflowServicesResolution } from '@lostgradient/weft';
+ *
+ * const ok: WorkflowServicesResolution = {
+ *   status: 'available',
+ *   services: { db: { query: () => [] } },
+ * };
+ * const no: WorkflowServicesResolution = { status: 'unavailable', reason: 'no config' };
+ * void ok;
+ * void no;
+ * ```
+ */
+export type WorkflowServicesResolution = {
+    status: 'available';
+    services: unknown;
+} | {
+    status: 'unavailable';
+    reason: string;
+};
+/**
+ * Information passed to {@link EngineOptions.resolveWorkflowServices} for each
+ * recovered workflow. `input` is the original durable launch input, available
+ * at resume time — typically enough to rebuild the run's dependencies (tenant,
+ * model, tool registry) without a side table.
+ *
+ * @example
+ * ```ts
+ * import { type WorkflowServicesResolverInfo } from '@lostgradient/weft';
+ *
+ * function describe(info: WorkflowServicesResolverInfo): string {
+ *   return `${info.workflowType}/${info.workflowId}`;
+ * }
+ * ```
+ */
+export interface WorkflowServicesResolverInfo {
+    workflowId: string;
+    workflowType: string;
+    input: unknown;
+}

package/dist/core/types/state.d.ts

@@ -42,7 +42,17 @@ export interface WorkflowState {
      * leaves this `undefined`).
      */
     terminationReason?: TerminationReason;
-    version: string;
+    /**
+     * The `(workflowVersion, agentVersion?, toolVersions?)` tuple captured for
+     * this workflow. This is the single canonical representation of version
+     * metadata on the state: it shares the {@link WorkflowVersionTuple} shape the
+     * event log records, so the two cannot drift, and it is rewritten on every
+     * versioned persist. `workflowVersion` is always present;
+     * `agentVersion`/`toolVersions` are present only when the workflow declares
+     * them. Resuming compares this against the currently registered definition to
+     * detect version drift.
+     */
+    versionTuple: WorkflowVersionTuple;
     /**
      * Owner identifier for execution-scoped durable state. Top-level workflows
      * own their own execution state; durable child workflows inherit the
@@ -50,16 +60,6 @@ export interface WorkflowState {
      * tree.
      */
     executionStateOwnerId?: string;
-    /**
-     * Legacy version tuple metadata retained so existing persisted workflow
-     * states can still be decoded and compared during recovery.
-     */
-    agentVersion?: string;
-    /**
-     * Legacy version tuple metadata retained so existing persisted workflow
-     * states can still be decoded and compared during recovery.
-     */
-    toolVersions?: string[];
     createdAt: number;
     startedAt?: number;
     updatedAt: number;