@lostgradient/weft 0.2.1 → 0.4.0

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,7 +22,36 @@ 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 assertValidOnTerminalConflict(options) {
+  const onTerminalConflict = options?.onTerminalConflict;
+  if (onTerminalConflict === void 0 || onTerminalConflict === "error")
+    return;
+  if (onTerminalConflict !== "start-new")
+    throw new StartWorkflowValidationError("options.onTerminalConflict must be 'error' or 'start-new'");
+  if (options?.idempotencyKey !== void 0)
+    throw new StartWorkflowValidationError("options.onTerminalConflict: 'start-new' is mutually exclusive with options.idempotencyKey: idempotency is a permanent at-most-once mapping and cannot restart a terminal run");
+  if (options?.id === void 0)
+    throw new StartWorkflowValidationError("options.onTerminalConflict: 'start-new' requires an explicit options.id; a generated id is never a meaningful restart target");
+}
+export function assertIdAndIdempotencyKeyExclusive(options) {
+  if (options.id !== void 0 && options.idempotencyKey !== void 0)
+    throw new StartWorkflowValidationError("options.id and options.idempotencyKey are mutually exclusive: idempotency assigns its own workflow id and dedups through the idempotency key. Provide one or the other.");
+}
+export function assertOnTerminalConflictUnsupported(options, surface) {
+  if (options !== void 0 && "onTerminalConflict" in options && options.onTerminalConflict !== void 0)
+    throw new StartWorkflowValidationError(`${surface} does not support options.onTerminalConflict; it is available on engine.start only`);
+}
 export function coerceStartWorkflowTimestamp(value, fieldName) {
   if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
     throw new StartWorkflowValidationError(`${fieldName} must be a non-negative integer millisecond timestamp`);

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-verification.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Activity verification types: the two-phase verifier contract an activity can
+ * declare via {@link ActivityDefinition.verify}. Split out of `activity.ts` to
+ * keep that module under the per-file line ceiling; these types are re-exported
+ * through `../types.ts` so the public surface is unchanged.
+ */
+/**
+ * Identifies whether an activity verifier is checking a fresh result or
+ * reconciling a prior keyed dispatch before redispatch.
+ *
+ * @example
+ * ```ts
+ * import type { ActivityVerificationPhase } from '@lostgradient/weft';
+ *
+ * const phase: ActivityVerificationPhase = 'pre-dispatch-reconciliation';
+ * console.log(phase);
+ * ```
+ */
+export type ActivityVerificationPhase = 'post-execution-validation' | 'pre-dispatch-reconciliation';
+/**
+ * Metadata passed to a Tier-0 activity verifier.
+ *
+ * @example
+ * ```ts
+ * import type { ActivityVerificationContext } from '@lostgradient/weft';
+ *
+ * function shouldQueryExternalSystem(context: ActivityVerificationContext): boolean {
+ *   return context.phase === 'pre-dispatch-reconciliation';
+ * }
+ * ```
+ */
+export interface ActivityVerificationContext<TInput = unknown> {
+    phase: ActivityVerificationPhase;
+    workflowId: string;
+    activityName: string;
+    operationId: string;
+    input: TInput;
+    idempotencyKey?: string;
+    attempt: number;
+}
+/**
+ * Return value for activity verification. Post-execution validation uses a
+ * boolean; pre-dispatch reconciliation can report whether a prior keyed side
+ * effect completed, did not complete, or is indeterminate.
+ *
+ * @example
+ * ```ts
+ * import type { ActivityVerificationResult } from '@lostgradient/weft';
+ *
+ * const result: ActivityVerificationResult<string> = {
+ *   status: 'completed-with-result',
+ *   result: 'already-finished',
+ * };
+ * console.log(result.status);
+ * ```
+ */
+export type ActivityVerificationResult<TOutput = unknown> = boolean | 'not-completed' | 'completed-result-unavailable' | 'indeterminate' | {
+    status: 'completed-with-result';
+    result: TOutput;
+};
+export type ActivityPostExecutionVerifier<TOutput = unknown> = {
+    bivarianceHack(result: TOutput): Promise<boolean> | boolean;
+}['bivarianceHack'];
+export type ActivityTier0Verifier<TInput = unknown, TOutput = unknown> = {
+    bivarianceHack(result: TOutput | undefined, context: ActivityVerificationContext<TInput>): Promise<ActivityVerificationResult<TOutput>> | ActivityVerificationResult<TOutput>;
+}['bivarianceHack'];
+export type ActivityVerifier<TInput = unknown, TOutput = unknown> = ActivityPostExecutionVerifier<TOutput> | ActivityTier0Verifier<TInput, TOutput>;

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

@@ -1,3 +1,4 @@
+import type { ActivityVerifier } from './activity-verification.ts';
 import type { DefinitionSchema, InferSchemaOutput } from './definition-schema.ts';
 import type { Duration, RetryPolicy } from './retry-retention.ts';
 /**
@@ -47,6 +48,53 @@ export type ActivityFunction<TInput = unknown, TOutput = unknown> = (input: TInp
 export interface ActivityContext {
     signal: AbortSignal;
     heartbeat(details?: unknown): void;
+    /**
+     * The heartbeat payload recorded by the PREVIOUS attempt of this activity, or
+     * `undefined` if there is none. This is the resumable-batch pattern: a
+     * long-running activity that calls `ctx.heartbeat({ done: n })` to record its
+     * progress can read `ctx.lastHeartbeatDetails` on a retry and skip the work it
+     * already finished, instead of re-running from the start and producing
+     * duplicate side effects.
+     *
+     * It is `undefined` on the first attempt, after an engine restart (the value is
+     * held in engine memory, never checkpointed), and for worker-executed
+     * activities (which run their function out of process and never observe this).
+     * Because it is non-durable, treat it as a best-effort optimization: a correct
+     * activity must still produce the right result when `lastHeartbeatDetails` is
+     * `undefined`. For a durability guarantee, persist progress in workflow state
+     * (e.g. one `ctx.run` per batch with an `idempotencyKey`) instead.
+     *
+     * Only top-level `ctx.run` activities retry, so this is only ever populated
+     * there. An activity called inside `ctx.all` / `ctx.race` does not retry, so its
+     * `lastHeartbeatDetails` is always `undefined`.
+     *
+     * @example
+     * ```ts
+     * import { activity, type ActivityContext } from '@lostgradient/weft';
+     *
+     * function resumeFrom(details: unknown): number {
+     *   return typeof details === 'object' && details !== null && 'done' in details &&
+     *     typeof (details as { done: unknown }).done === 'number'
+     *     ? (details as { done: number }).done
+     *     : 0;
+     * }
+     *
+     * const postBatches = activity({
+     *   name: 'postBatches',
+     *   execute: async (batches: string[][], ctx?: ActivityContext) => {
+     *     let done = resumeFrom(ctx?.lastHeartbeatDetails);
+     *     for (; done < batches.length; done += 1) {
+     *       await postBatch(batches[done]!);
+     *       ctx?.heartbeat({ done: done + 1 });
+     *     }
+     *     return { posted: done };
+     *   },
+     * });
+     * declare function postBatch(batch: string[]): Promise<void>;
+     * void postBatches;
+     * ```
+     */
+    lastHeartbeatDetails?: unknown;
     /**
      * Defer this activity to out-of-band completion. Calling `completeAsync()`
      * hands the work off to an external system — a webhook, a human callback, a
@@ -120,68 +168,30 @@ export interface ActivityCallOptions {
     sticky?: boolean;
     /** Override the default visibility timeout for this invocation. */
     visibilityTimeout?: Duration;
+    /**
+     * Total wall-clock budget for this activity across ALL retry attempts and the
+     * backoff waits between them — close to Temporal's `scheduleToCloseTimeout`.
+     * Unlike `timeout` (a per-attempt cap, reset on every attempt), this budget is
+     * measured from the first dispatch and is not reset between attempts. When the
+     * budget bars the next attempt, the activity fails with an
+     * {@link ActivityScheduleToCloseTimeoutError} (a `timeout` failure category).
+     *
+     * Enforcement is at the **retry decision point**, not by waiting out the clock:
+     * the activity fails when the next retry's backoff would start it at or after the
+     * deadline (or when an attempt has already overrun the budget), rather than
+     * parking for a backoff that is already doomed. So a retry whose backoff would
+     * overshoot the budget is skipped immediately even though the actual elapsed time
+     * is still under the budget — the error reports the actual elapsed time and the
+     * projected next-dispatch that triggered the decision.
+     *
+     * It has **no effect unless a retry policy is configured** — a non-retried
+     * activity fails on its first error before the budget is ever consulted. Use
+     * `timeout` to bound a single attempt. It also applies to top-level `ctx.run`
+     * activities only; an activity inside `ctx.all` / `ctx.race` does not retry, so
+     * this budget never engages there.
+     */
+    scheduleToCloseTimeout?: Duration;
 }
-/**
- * Identifies whether an activity verifier is checking a fresh result or
- * reconciling a prior keyed dispatch before redispatch.
- *
- * @example
- * ```ts
- * import type { ActivityVerificationPhase } from '@lostgradient/weft';
- *
- * const phase: ActivityVerificationPhase = 'pre-dispatch-reconciliation';
- * console.log(phase);
- * ```
- */
-export type ActivityVerificationPhase = 'post-execution-validation' | 'pre-dispatch-reconciliation';
-/**
- * Metadata passed to a Tier-0 activity verifier.
- *
- * @example
- * ```ts
- * import type { ActivityVerificationContext } from '@lostgradient/weft';
- *
- * function shouldQueryExternalSystem(context: ActivityVerificationContext): boolean {
- *   return context.phase === 'pre-dispatch-reconciliation';
- * }
- * ```
- */
-export interface ActivityVerificationContext<TInput = unknown> {
-    phase: ActivityVerificationPhase;
-    workflowId: string;
-    activityName: string;
-    operationId: string;
-    input: TInput;
-    idempotencyKey?: string;
-    attempt: number;
-}
-/**
- * Return value for activity verification. Post-execution validation uses a
- * boolean; pre-dispatch reconciliation can report whether a prior keyed side
- * effect completed, did not complete, or is indeterminate.
- *
- * @example
- * ```ts
- * import type { ActivityVerificationResult } from '@lostgradient/weft';
- *
- * const result: ActivityVerificationResult<string> = {
- *   status: 'completed-with-result',
- *   result: 'already-finished',
- * };
- * console.log(result.status);
- * ```
- */
-export type ActivityVerificationResult<TOutput = unknown> = boolean | 'not-completed' | 'completed-result-unavailable' | 'indeterminate' | {
-    status: 'completed-with-result';
-    result: TOutput;
-};
-export type ActivityPostExecutionVerifier<TOutput = unknown> = {
-    bivarianceHack(result: TOutput): Promise<boolean> | boolean;
-}['bivarianceHack'];
-export type ActivityTier0Verifier<TInput = unknown, TOutput = unknown> = {
-    bivarianceHack(result: TOutput | undefined, context: ActivityVerificationContext<TInput>): Promise<ActivityVerificationResult<TOutput>> | ActivityVerificationResult<TOutput>;
-}['bivarianceHack'];
-export type ActivityVerifier<TInput = unknown, TOutput = unknown> = ActivityPostExecutionVerifier<TOutput> | ActivityTier0Verifier<TInput, TOutput>;
 /**
  * Full metadata for an activity, combining the execute function with optional
  * retry policy, timeout, queue routing, compensation, and idempotency. Built
@@ -218,12 +228,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;
@@ -232,6 +245,15 @@ export interface ActivityDefinition<TInput = unknown, TOutput = unknown, TName e
     idempotent?: boolean;
     /** Visibility timeout for this activity. Defaults to 30 seconds. */
     visibilityTimeout?: Duration;
+    /**
+     * Total wall-clock budget across all retry attempts and their backoff waits,
+     * measured from the first dispatch. The per-call {@link ActivityCallOptions.scheduleToCloseTimeout}
+     * overrides this default. Enforced at the retry decision point (the activity
+     * fails when the next retry would start at or after the deadline, not by waiting
+     * out the clock), so it only engages for a retried, top-level `ctx.run` activity.
+     * See the per-call option for the full contract.
+     */
+    scheduleToCloseTimeout?: Duration;
     /**
      * Optional compensation function. When defined and a saga step that ran this
      * activity needs to be rolled back, the engine calls `compensate(input, output)`

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

@@ -1,5 +1,5 @@
 import type { WorkflowId, WorkflowStatus } from './identity.ts';
-import type { SearchAttributeValue } from './search-attributes.ts';
+import type { AttributeFilterScalarValue } from './list-options.ts';
 export declare const MAX_BULK_OPERATION_REQUEST_ID_LENGTH = 200;
 export declare const MAX_BULK_CONFIRMATION_TOKEN_LENGTH = 256;
 /**
@@ -14,7 +14,7 @@ export declare const MAX_BULK_CONFIRMATION_TOKEN_LENGTH = 256;
  * void action;
  * ```
  */
-export type BulkOperationAction = 'cancel' | 'signal' | 'delete' | 'tag:add' | 'tag:remove' | 'recover';
+export type BulkOperationAction = 'cancel' | 'signal' | 'delete' | 'tag:add' | 'tag:remove' | 'retry-failed';
 /**
  * Credential-safe caller summary recorded on bulk audit events. Claims,
  * bearer tokens, API keys, and other credentials are intentionally absent.
@@ -55,11 +55,11 @@ export type BulkOperationFilterSummary = {
     tags?: string[];
     attributes?: Array<{
         key: string;
-        value?: SearchAttributeValue;
-        gt?: SearchAttributeValue;
-        lt?: SearchAttributeValue;
-        gte?: SearchAttributeValue;
-        lte?: SearchAttributeValue;
+        value?: AttributeFilterScalarValue | AttributeFilterScalarValue[];
+        gt?: AttributeFilterScalarValue;
+        lt?: AttributeFilterScalarValue;
+        gte?: AttributeFilterScalarValue;
+        lte?: AttributeFilterScalarValue;
     }>;
     limit?: number;
     offset?: number;
@@ -126,6 +126,16 @@ export type BulkOperationDryRunResult = {
     sampleWorkflowIds: WorkflowId[];
     confirmationToken: string;
     confirmationTokenVersion: 1;
+    /**
+     * Delete-only, point-in-time advisory: ids in the matched scope that currently owe an
+     * engine-driven finalizer (#446) and so would be SKIPPED by the commit (mirrors
+     * {@link BulkDeleteResult.skippedTeardownPending}). Present only on a `delete` preview
+     * and only when non-empty. `matched`, `scope`, and `confirmationToken` still describe
+     * the full filter scope — they are stable and derive the commit token — so this field
+     * surfaces the skip without recomputing them (teardown-owed is transient and is
+     * re-evaluated at commit time, where the authoritative skip list is reported).
+     */
+    skippedTeardownPending?: WorkflowId[];
 };
 /**
  * Options for a dry-run bulk operation preview.
@@ -145,6 +155,7 @@ export type BulkOperationDryRunOptions = {
     dryRun: true;
     requestId?: string;
     principal?: BulkOperationPrincipal;
+    bulkConcurrency?: number;
 };
 /**
  * Options for a committed bulk operation.
@@ -165,6 +176,7 @@ export type BulkOperationCommitOptions = {
     confirmationToken?: string;
     requestId?: string;
     principal?: BulkOperationPrincipal;
+    bulkConcurrency?: number;
 };
 /**
  * Options accepted by bulk workflow operations.
@@ -173,7 +185,7 @@ export type BulkOperationCommitOptions = {
  * ```ts
  * import type { BulkOperationOptions } from '@lostgradient/weft';
  *
- * const options: BulkOperationOptions = { dryRun: true };
+ * const options: BulkOperationOptions = { dryRun: true, bulkConcurrency: 4 };
  * void options;
  * ```
  */
@@ -278,6 +290,29 @@ export type BulkCancelResult = {
     errors: BulkOperationError[];
     auditEvent?: BulkOperationAuditEvent;
 };
+/**
+ * Result of a bulk failed-workflow retry operation (`engine.retryFailedAll`).
+ * Reports the number of workflows accepted for retry, the number that failed
+ * to restart or resume, and per-workflow error details in `errors`.
+ *
+ * @example
+ * ```ts
+ * import type { BulkRetryFailedResult } from '@lostgradient/weft';
+ *
+ * const result: BulkRetryFailedResult = {
+ *   retried: 2,
+ *   failed: 1,
+ *   errors: [{ id: 'wf-3', error: 'Checkpoint no longer exists' }],
+ * };
+ * void result;
+ * ```
+ */
+export type BulkRetryFailedResult = {
+    retried: number;
+    failed: number;
+    errors: BulkOperationError[];
+    auditEvent?: BulkOperationAuditEvent;
+};
 /**
  * Result of a bulk signal operation (`engine.signalAll`). Reports the number
  * of workflows that received the signal and the number for which delivery failed.
@@ -289,10 +324,16 @@ export type BulkSignalResult = {
 };
 /**
  * Result of a bulk delete operation (`engine.deleteAll`). Reports how many
- * terminal workflows were deleted from storage.
+ * terminal workflows were deleted from storage. Workflows that still owe an
+ * engine-driven finalizer (#446) are NOT deleted — deleting them would drop the
+ * finalizer payload before the resource is torn down — and are reported, by id, in
+ * `skippedTeardownPending` so the skip is visible rather than silent. The skip is
+ * transient: once the finalizer settles, a later `deleteAll` removes the record.
  */
 export type BulkDeleteResult = {
     deleted: number;
+    /** Ids of terminal workflows skipped because they still owe a finalizer run. */
+    skippedTeardownPending?: WorkflowId[];
     auditEvent?: BulkOperationAuditEvent;
 };
 /**

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

@@ -3,6 +3,7 @@ import { WeftError } from '../weft-error.ts';
 import type { FailureCategory, OperationId, WorkflowId } from './identity.ts';
 import type { Duration, RetryPolicy } from './retry-retention.ts';
 import type { SearchAttributeValue } from './search-attributes.ts';
+import type { WorkflowLogRecord } from './workflow-log.ts';
 /** Version tag for Worker-mode operation replay signatures stored in checkpoints. */
 export declare const WORKER_REPLAY_SIGNATURE_FORMAT = "weft-worker-operation-signature-v1";
 /**
@@ -69,7 +70,7 @@ export interface WorkerReplayOperationFailure {
 /**
  * Durable snapshot of a workflow's execution state persisted at each
  * `yield` boundary. Contains the accumulated operation results, local
- * variables, pending signals, search attributes, and the step counter.
+ * variables, search attributes, and the step counter.
  * Users don't construct checkpoints directly; the engine manages them.
  * Available via time-travel APIs and {@link WorkflowReplay}.
  *
@@ -91,6 +92,12 @@ export interface Checkpoint {
     step: number;
     locals: Record<string, unknown>;
     accumulatedResults: Array<[number, unknown]>;
+    /**
+     * Highest accumulated-result step whose replay data has been emitted to the
+     * workflow event log. Missing means no consumed results have been emitted yet,
+     * which is how old unpruned checkpoints are read.
+     */
+    accumulatedResultReplayWatermark?: number;
     /**
      * Worker-mode replay guards for cached operation results. Inline execution
      * ignores this optional field; Worker recovery uses it to prove a cached
@@ -103,15 +110,13 @@ export interface Checkpoint {
      * can throw them back into the generator without trusting user result shape.
      */
     workerReplayFailures?: Array<[number, WorkerReplayOperationFailure]>;
-    pendingSignals: string[];
     searchAttributes: Record<string, SearchAttributeValue>;
-    /** User-defined workflow code version. Used for code migrations. */
+    /** User-defined workflow code version. Checked during recovery. */
     version: string;
     /**
      * Checkpoint schema version. Distinct from `version` (which is the
      * user's workflow code version). Bumped whenever the engine changes
-     * the on-disk checkpoint format. Pre-1.0: refuse to load older
-     * versions; post-1.0: every bump must ship a migration.
+     * the on-disk checkpoint format. Pre-1.0: refuse to load older versions.
      */
     schemaVersion: number;
     createdAt: number;
@@ -126,8 +131,9 @@ export interface Checkpoint {
 export declare const CURRENT_CHECKPOINT_SCHEMA_VERSION = 2;
 /**
  * Thrown by `validateCheckpointShape` when a checkpoint's
- * `schemaVersion` does not match the engine's current version. Pre-1.0
- * we refuse to load mismatched checkpoints rather than migrating.
+ * `schemaVersion` does not match the engine's current version. A mismatched
+ * checkpoint is rejected, never upgraded in place: the engine loads only
+ * checkpoints stamped with the exact current schema version.
  */
 export declare class CheckpointSchemaVersionError extends WeftError<'CheckpointSchemaVersionError'> {
     readonly found: number | 'pre-versioned';
@@ -183,7 +189,7 @@ export interface TimerEntry {
     id: string;
     workflowId: WorkflowId;
     fireAt: number;
-    kind: 'sleep' | 'visibility-timeout' | 'execution-deadline' | 'delayed-start' | 'schedule' | 'terminal-cleanup';
+    kind: 'sleep' | 'visibility-timeout' | 'execution-deadline' | 'delayed-start' | 'schedule' | 'terminal-cleanup' | 'teardown' | 'wait-condition';
     executionTimeoutMs?: number;
 }
 export type WorkerInboundMessage = {
@@ -198,6 +204,14 @@ export type WorkerInboundMessage = {
     executionStateOwnerId?: string;
     deadline?: number;
     headers?: [string, string][];
+    /**
+     * Whether the engine host has an `EngineOptions.onLog` sink installed. The
+     * worker routes `ctx.log` records back to the host (as a `log` outbound
+     * message) only when this is `true`; otherwise it logs to the worker's own
+     * console, preserving the default. Omitted (treated as `false`) when no host
+     * sink exists, so a worker can never lose logs to a no-op host callback.
+     */
+    hostHasLogSink?: boolean;
 } | {
     type: 'resume';
     protocolVersion?: number;
@@ -206,6 +220,8 @@ export type WorkerInboundMessage = {
     workflowId: WorkflowId;
     checkpoint: ArrayBuffer;
     operationResult: OperationOutcome;
+    /** See {@link WorkerInboundMessage} `run.hostHasLogSink`; carried on every turn so a rebuilt or resumed worker keeps the capability. */
+    hostHasLogSink?: boolean;
 } | {
     type: 'cancel';
     protocolVersion?: number;
@@ -234,4 +250,24 @@ export type WorkerOutboundMessage = {
     errorStack?: string;
     /** Populated when the execution strategy can classify the failure cause. */
     failureCategory?: FailureCategory;
+} | {
+    /**
+     * A `ctx.log` record forwarded from a worker to the engine host's
+     * `EngineOptions.onLog` sink (#529). Unlike the other variants, `log` is a
+     * NON-TERMINAL, best-effort observability message: it carries no turn-protocol
+     * state, never settles or clears the worker turn, and never reaches the strict
+     * accept-or-discard gate. The host delivers a record to the sink IFF the sending
+     * worker owns `workflowId` (active or parked) AND `record.workflowId` matches the
+     * envelope AND the record is a structurally valid `WorkflowLogRecord` within the
+     * size cap; otherwise the record is dropped — a wrong-owner, malformed, oversize,
+     * or out-of-turn `log` is never a protocol violation and never discards the
+     * worker. A between-turns self-log (a fire-and-forget log resolving while the
+     * worker is parked) IS delivered, because the worker still owns its parked
+     * workflow. The worker emits these only when the inbound message reported
+     * `hostHasLogSink: true`.
+     */
+    type: 'log';
+    protocolVersion?: number;
+    workflowId: WorkflowId;
+    record: WorkflowLogRecord;
 };

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