@lostgradient/weft 0.3.0 → 0.5.0

package/dist/core/engine/construction.d.ts

@@ -3,6 +3,7 @@ import type { Storage as WeftStorage } from '../../storage/interface.ts';
 import { ActivityWorkerDispatcher } from '../../workers/activity-worker-dispatcher.ts';
 import type { ComposedWorkflowInterceptor, Interceptor } from '../interceptor.ts';
 import { type AnyActivityDefinition, type AnyWorkflowDefinition, type EngineOptions, type RegisteredWorkflowDefinition } from '../types.ts';
+import type { WorkflowLogRecord } from '../types/workflow-log.ts';
 import type { EngineConstructorOptions, ExecutionStrategyBundle, RegistrationEntry, ResolvedOptions } from './engine-internal-types.ts';
 export type KnownWorkflowNames<TWorkflows extends object> = Extract<keyof TWorkflows, string>;
 declare const emptyWorkflowDefinitions: unique symbol;
@@ -53,7 +54,9 @@ export declare function createExecutionStrategyBundle(parameters: {
     getComposedWorkflowInterceptor?: () => ComposedWorkflowInterceptor | null;
     resolveWorkflowType: (target: string | Function) => string;
     registerCancelHandler?: (workflowId: string, handler: () => Promise<void> | void) => () => void;
+    recordFinalizerState?: (workflowId: string, value: unknown) => void;
     getWorkflowServices?: (workflowId: string) => unknown;
+    getLogSink?: () => ((record: WorkflowLogRecord) => void) | undefined;
 }): ExecutionStrategyBundle;
 export declare function createActivityWorkerDispatcher(activityExecution: EngineConstructorOptions['activityExecution']): ActivityWorkerDispatcher | null;
 export declare function createAlertManagerForEngine(engine: EventTarget, alerts: EngineOptions['alerts'] | undefined, getNow: () => number): AlertManager | null;

package/dist/core/engine/construction.js

@@ -3,6 +3,7 @@ import { CompressedStorage } from "../../storage/compressed-storage.js";
 import { MemoryStorage } from "../../storage/memory.js";
 import { ActivityWorkerDispatcher } from "../../workers/activity-worker-dispatcher.js";
 import { WorkerPool } from "../../workers/pool.js";
+import { optionalInlineDependencies } from "../inline-execution-strategy.context-options.js";
 import { InlineExecutionStrategy } from "../inline-execution-strategy.js";
 import {
   DEFAULT_RETENTION_SWEEP_BATCH_SIZE,
@@ -14,6 +15,7 @@ import {
   DEFAULT_WORKER_TURN_TIMEOUT_MS,
   MIN_WORKER_PROTOCOL_MESSAGE_BYTES
 } from "../worker-protocol.js";
+import { resolveOwnershipFields } from "./ownership-options.js";
 import {
   normalizeHistoryPolicy,
   normalizePayloadSizePolicy,
@@ -70,7 +72,8 @@ export function copyWorkflowDefinition(type, registration) {
     ...registration.description === void 0 ? {} : { description: registration.description },
     ...registration.inputSchema === void 0 ? {} : { inputSchema: registration.inputSchema },
     ...registration.outputSchema === void 0 ? {} : { outputSchema: registration.outputSchema },
-    ...registration.searchAttributes === void 0 ? {} : { searchAttributes: registration.searchAttributes }
+    ...registration.searchAttributes === void 0 ? {} : { searchAttributes: registration.searchAttributes },
+    ...registration.concurrency === void 0 ? {} : { concurrency: registration.concurrency }
   };
 }
 function resolveRetentionFields(options) {
@@ -116,11 +119,13 @@ export function resolveEngineOptions(storage, options, getNow) {
     storage,
     getNow,
     resolveWorkflowServices: options?.resolveWorkflowServices ?? null,
+    onLog: options?.onLog ?? null,
     ...resolveBooleanDefaults(options),
     ...resolveNumericDefaults(options),
     ...resolveRetentionFields(options),
     ...resolveHistoryFields(options),
-    ...resolveSecondInstanceFields(options)
+    ...resolveSecondInstanceFields(options),
+    ...resolveOwnershipFields(options)
   };
 }
 export function normalizeWorkerExecutionConfiguration(options) {
@@ -180,19 +185,23 @@ export function createExecutionStrategyBundle(parameters) {
     getComposedWorkflowInterceptor,
     resolveWorkflowType,
     registerCancelHandler,
-    getWorkflowServices
+    recordFinalizerState,
+    getWorkflowServices,
+    getLogSink
   } = parameters, workerExecutionConfiguration = normalizeWorkerExecutionConfiguration(options);
   if (workerExecutionConfiguration.mode === "worker") {
     const pool = new WorkerPool({
       workerUrl: workerExecutionConfiguration.workerExecution.workerUrl,
       concurrency: workerExecutionConfiguration.workerExecution.poolSize ?? 4,
       smol: workerExecutionConfiguration.workerExecution.smol ?? !1
-    }), strategyOptions = {
+    }), logSink = getLogSink?.(), strategyOptions = {
       broadcastEvents,
       requireProtocolVersion: workerExecutionConfiguration.requireProtocolVersion,
       discardOnCancel: workerExecutionConfiguration.discardOnCancel,
       workflowTurnTimeoutMs: workerExecutionConfiguration.workflowTurnTimeoutMs,
-      maxProtocolMessageBytes: workerExecutionConfiguration.maxProtocolMessageBytes
+      maxProtocolMessageBytes: workerExecutionConfiguration.maxProtocolMessageBytes,
+      getNow,
+      ...logSink !== void 0 && { onLog: logSink }
     };
     return {
       strategy: new WorkerExecutionStrategy(pool, strategyOptions),
@@ -201,13 +210,17 @@ export function createExecutionStrategyBundle(parameters) {
   }
   const inlineStrategy = new InlineExecutionStrategy({
     getRegistration,
-    ...getComposedWorkflowInterceptor !== void 0 && { getComposedWorkflowInterceptor },
     getNow,
     maxNestingDepth,
     development,
     resolveWorkflowType,
-    ...registerCancelHandler !== void 0 && { registerCancelHandler },
-    ...getWorkflowServices !== void 0 && { getWorkflowServices }
+    ...optionalInlineDependencies({
+      getComposedWorkflowInterceptor,
+      registerCancelHandler,
+      recordFinalizerState,
+      getWorkflowServices,
+      getLogSink
+    })
   });
   return { strategy: inlineStrategy, inlineStrategy };
 }

package/dist/core/engine/coordination-branch-executors.d.ts

@@ -0,0 +1,70 @@
+import type { ContextOperationRequest } from '../context.ts';
+import type { EngineInternals } from './internals.ts';
+/**
+ * The largest delay a host `setTimeout` can hold without overflow. Node and Bun
+ * store the delay in a 32-bit signed integer, so a value above this wraps and
+ * the timer fires almost immediately. A multi-day race-branch sleep must be
+ * chunked under this ceiling and re-armed, or it would win its race instantly.
+ */
+export declare const MAX_TIMER_DELAY_MS = 2147483647;
+/**
+ * Compute the next host-timer delay for a race-branch sleep: the milliseconds
+ * remaining until the deterministic `scheduledFireAt` deadline, clamped to
+ * `[0, MAX_TIMER_DELAY_MS]`. Clamping to the ceiling is what prevents a multi-day
+ * sleep from overflowing `setTimeout` and firing instantly — the caller re-arms
+ * against the same deadline until the remaining delay reaches `0`.
+ */
+export declare function nextSleepTimerDelayMs(scheduledFireAt: number, now: number): number;
+/**
+ * Abortable in-process `sleep` branch for `ctx.race` / `ctx.all`.
+ *
+ * Unlike a top-level `ctx.sleep` (which arms a durable timer and parks the whole
+ * generator), a sleep branch inside a coordination operation is a TRANSIENT
+ * in-process wait: the coordination operation as a whole is the durable unit, and
+ * on replay the cached winner short-circuits before any branch re-runs. So this
+ * must NOT touch `internals.scheduler` (a durable timer write would corrupt the
+ * timer index) — it waits with a plain timer that the race's AbortController can
+ * cancel when another branch wins.
+ *
+ * The deadline is the operation's deterministic `scheduledFireAt`, compared
+ * against the engine clock (`internals.options.getNow()`), not wall-clock
+ * `Date.now()`, so a clock-overriding deployment stays consistent. The remaining
+ * delay is recomputed against that absolute deadline on every chunk, which both
+ * chunks delays beyond {@link MAX_TIMER_DELAY_MS} (so a multi-day sleep does not
+ * overflow `setTimeout` and fire instantly) and self-corrects for timer drift.
+ *
+ * Note: because the timer is a real event-loop timer, a long sleep that WINS its
+ * race is not driven by a virtual-clock `advanceTime`; tests should use short
+ * real durations for sleep-wins paths (sleep-loses paths need no timing — the
+ * abort fires).
+ *
+ * The timer also observes the engine abort signal so a long sleep branch does
+ * not outlive engine disposal. `ctx.all` does not abort siblings (it has no
+ * loser), so without watching `internals.abortController.signal` a multi-day
+ * `ctx.all([ctx.sleep('30d')])` branch would keep a host timer alive after the
+ * engine is gone.
+ */
+export declare function executeSleepSubOperation(internals: EngineInternals, operation: Extract<ContextOperationRequest, {
+    type: 'sleep';
+}>, signal?: AbortSignal): Promise<void>;
+/**
+ * Abortable in-process `wait-signal` branch for `ctx.race` / `ctx.all`.
+ *
+ * A wait-signal branch must never consume its durable signal record itself —
+ * when it is woken it does not yet know whether it WON its race. So on delivery
+ * it resolves with a {@link createDeferredConsumeEnvelope | deferred-consume
+ * envelope}: the single atomic {@link consumeSignalWithAtomicWorkflowCommit} is wrapped in
+ * `finalize` and performed ONLY by the coordinator, on the winner, strictly
+ * after `Promise.race` / `Promise.all` settles. A losing branch (race settled by
+ * a sibling → `signal` aborts) drops its envelope unfinalized and releases its
+ * waiter via {@link releaseSignalWaiter} WITHOUT consuming, so the signal
+ * survives for a later `waitForSignal` or a replay.
+ *
+ * Reads are non-destructive {@link peekSignal}s until the coordinator finalizes;
+ * the identity-guarded release (`expectedResolve === deliver`) ensures a loser
+ * never clobbers another waiter (e.g. a later top-level `waitForSignal`) that
+ * reused the shared `${workflowId}:${signalName}` key.
+ */
+export declare function executeWaitSignalSubOperation(internals: EngineInternals, workflowId: string, operation: Extract<ContextOperationRequest, {
+    type: 'wait-signal';
+}>, signal?: AbortSignal): Promise<unknown>;

package/dist/core/engine/coordination-branch-executors.js

@@ -0,0 +1,107 @@
+import { createDeferredConsumeEnvelope } from "./deferred-consume-envelope.js";
+import {
+  consumeSignalWithAtomicWorkflowCommit,
+  peekSignal,
+  releaseSignalWaiter,
+  trackWaiterKey
+} from "./signals.js";
+export const MAX_TIMER_DELAY_MS = 2147483647;
+export function nextSleepTimerDelayMs(scheduledFireAt, now) {
+  return Math.min(Math.max(0, scheduledFireAt - now), MAX_TIMER_DELAY_MS);
+}
+export function executeSleepSubOperation(internals, operation, signal) {
+  signal?.throwIfAborted();
+  const engineAbort = internals.abortController.signal;
+  if (engineAbort.aborted)
+    return Promise.reject(engineAbort.reason ?? Error("aborted"));
+  if (nextSleepTimerDelayMs(operation.scheduledFireAt, internals.options.getNow()) === 0)
+    return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    let timer;
+    const cleanup = () => {
+      signal?.removeEventListener("abort", onAbort);
+      engineAbort.removeEventListener("abort", onAbort);
+    }, onAbort = () => {
+      clearTimeout(timer);
+      cleanup();
+      reject(signal?.reason ?? engineAbort.reason ?? Error("aborted"));
+    }, arm = () => {
+      const remainingMs = nextSleepTimerDelayMs(operation.scheduledFireAt, internals.options.getNow());
+      if (remainingMs === 0) {
+        cleanup();
+        resolve();
+        return;
+      }
+      timer = setTimeout(arm, remainingMs);
+    };
+    signal?.addEventListener("abort", onAbort, { once: !0 });
+    engineAbort.addEventListener("abort", onAbort, { once: !0 });
+    arm();
+  });
+}
+export function executeWaitSignalSubOperation(internals, workflowId, operation, signal) {
+  signal?.throwIfAborted();
+  const { signalName } = operation, waiterKey = `${workflowId}:${signalName}`, engineAbort = internals.abortController.signal;
+  return new Promise((resolve, reject) => {
+    let settled = !1, registered = !1;
+    const { promise: delivered, resolve: deliver } = Promise.withResolvers(), cleanup = () => {
+      signal?.removeEventListener("abort", onAbort);
+      engineAbort.removeEventListener("abort", onAbort);
+    }, finalize = async () => {
+      const consumed = await consumeSignalWithAtomicWorkflowCommit(internals, workflowId, signalName);
+      return consumed.found ? consumed.payload : void 0;
+    }, onAbort = () => {
+      if (settled)
+        return;
+      settled = !0;
+      cleanup();
+      if (registered)
+        releaseSignalWaiter(internals, workflowId, waiterKey, deliver);
+      reject(signal?.reason ?? engineAbort.reason ?? Error("aborted"));
+    }, win = () => {
+      if (settled)
+        return;
+      settled = !0;
+      cleanup();
+      resolve(createDeferredConsumeEnvelope(finalize));
+    }, fail = (error) => {
+      if (settled)
+        return;
+      settled = !0;
+      cleanup();
+      if (registered)
+        releaseSignalWaiter(internals, workflowId, waiterKey, deliver);
+      reject(error);
+    };
+    signal?.addEventListener("abort", onAbort, { once: !0 });
+    engineAbort.addEventListener("abort", onAbort, { once: !0 });
+    if (engineAbort.aborted) {
+      onAbort();
+      return;
+    }
+    (async () => {
+      const existing = await peekSignal(internals, workflowId, signalName);
+      if (settled)
+        return;
+      if (existing.found) {
+        win();
+        return;
+      }
+      internals.signalWaiters.set(waiterKey, deliver);
+      trackWaiterKey(internals.signalWaitersByWorkflow, workflowId, waiterKey);
+      registered = !0;
+      const buffered = await peekSignal(internals, workflowId, signalName);
+      if (settled)
+        return;
+      if (buffered.found) {
+        releaseSignalWaiter(internals, workflowId, waiterKey, deliver);
+        win();
+        return;
+      }
+      await delivered;
+      if (settled)
+        return;
+      win();
+    })().catch(fail);
+  });
+}

package/dist/core/engine/deferred-consume-envelope.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Deferred-consume envelopes for `wait-signal` branches inside `ctx.race` /
+ * `ctx.all`.
+ *
+ * A `wait-signal` branch must NOT destructively consume its durable signal
+ * record when it is woken — at that moment it does not yet know whether it WON
+ * its race. If a losing branch consumed, it would delete a signal that a later
+ * `waitForSignal` (or a replay) still needs. So a woken wait-signal branch
+ * resolves with one of these envelopes instead of a value: the branch defers the
+ * single destructive {@link import('./signals.ts').consumeSignal} into
+ * `finalize`, and ONLY the coordinator — which authoritatively knows the race
+ * winner once `Promise.race` settles — calls `finalize()`, on the winner alone.
+ * Losing branches drop their envelope unfinalized and release their waiter
+ * without consuming, so the signal survives.
+ *
+ * The envelope is branded with a unique {@link DEFERRED_CONSUME_BRAND} symbol and
+ * detected ONLY by that symbol, never structurally — a user's signal payload can
+ * legitimately be an object shaped like `{ finalize }`, and a structural check
+ * would misfire on it.
+ *
+ * Envelopes must never reach the durable operation cache (a function cannot
+ * round-trip `encode`/`decode`), so the coordinator finalize-and-unwraps every
+ * winning branch's envelope before the operation result is written — including
+ * envelopes nested at arbitrary positions inside a `ctx.all` array result that a
+ * nested coordinator surfaces up to its parent.
+ */
+declare const DEFERRED_CONSUME_BRAND: unique symbol;
+/**
+ * A branch result whose real value is produced by a single deferred consume that
+ * only the winning coordinator performs.
+ */
+export type DeferredConsumeEnvelope = {
+    readonly [DEFERRED_CONSUME_BRAND]: true;
+    /** Perform the single destructive consume and return the consumed payload. */
+    readonly finalize: () => Promise<unknown>;
+};
+/** Wrap a deferred consume into a branded envelope. */
+export declare function createDeferredConsumeEnvelope(finalize: () => Promise<unknown>): DeferredConsumeEnvelope;
+/** Detect an envelope by its brand symbol only (never structurally). */
+export declare function isDeferredConsumeEnvelope(value: unknown): value is DeferredConsumeEnvelope;
+/**
+ * Finalize-and-unwrap a coordination result before it is written to the durable
+ * cache. A winning `wait-signal` branch surfaces a {@link DeferredConsumeEnvelope}
+ * whose `finalize()` performs the single consume; a nested `ctx.all` branch
+ * surfaces an ARRAY that may hold envelopes at arbitrary positions, so arrays are
+ * walked and each element finalized. Any other value passes through untouched.
+ *
+ * This runs only on the WINNING path (race winner, or every branch of a settled
+ * `ctx.all`), so finalizing here is exactly the linearization point of "this
+ * branch won" — the consume happens strictly after the coordinator settled, and a
+ * losing branch's envelope is never reached, so its signal is never consumed.
+ *
+ * The array walk reconstructs arrays via `Promise.all(map(...))`. This is safe
+ * because coordination results are cache-safe encoded data: they round-trip
+ * `encode`/`decode` for the durable cache, so sparse holes, custom array
+ * properties, subclasses, and array identity are not preserved semantics here.
+ */
+export declare function finalizeAndUnwrap(value: unknown): Promise<unknown>;
+export {};

package/dist/core/engine/deferred-consume-envelope.js

@@ -0,0 +1,14 @@
+const DEFERRED_CONSUME_BRAND = Symbol("weft.deferredConsume");
+export function createDeferredConsumeEnvelope(finalize) {
+  return { [DEFERRED_CONSUME_BRAND]: !0, finalize };
+}
+export function isDeferredConsumeEnvelope(value) {
+  return typeof value === "object" && value !== null && value[DEFERRED_CONSUME_BRAND] === !0;
+}
+export async function finalizeAndUnwrap(value) {
+  if (isDeferredConsumeEnvelope(value))
+    return value.finalize();
+  if (Array.isArray(value))
+    return Promise.all(value.map((element) => finalizeAndUnwrap(element)));
+  return value;
+}

package/dist/core/engine/disposal.js

@@ -10,6 +10,9 @@ export function disposeEngine(internals) {
     resolveSignalWaiter();
   internals.signalWaiters.clear();
   internals.signalWaitersByWorkflow.clear();
+  for (const resolveConditionWaiter of internals.conditionWaiters.values())
+    resolveConditionWaiter();
+  internals.conditionWaiters.clear();
   disposeQueuedInlineWorkflowStarts(internals);
   internals.scheduler[Symbol.dispose]();
   internals.strategy[Symbol.dispose]();
@@ -23,6 +26,7 @@ export function disposeEngine(internals) {
   }
   internals.nextRetentionSweepAt = null;
   disposeSecondInstanceDetection(internals);
+  disposeLeaseManager(internals);
   internals.handleCache.clear();
   for (const waiter of internals.resultResolvers.values())
     waiter.reject(new EngineDisposedError);
@@ -35,6 +39,7 @@ export function disposeEngine(internals) {
   internals.workflowReviewIds.clear();
   internals.parkedInlineWorkflows.clear();
   internals.terminalizingWorkflows.clear();
+  internals.deliveredPendingUpdateIds.clear();
   internals.reviewTimerIds.clear();
   for (const controller of internals.pendingWebhooks)
     controller.abort();
@@ -50,6 +55,8 @@ export function disposeEngine(internals) {
   internals.pendingScheduleCreations.clear();
   internals.eventLogHeads.clear();
   internals.pendingTimelineEntries.clear();
+  internals.pendingAtomicWorkflowCommitSideEffects.clear();
+  internals.pendingAsyncActivityResolutions.clear();
   internals.workflowVersionTuples.clear();
   internals.workflowFeedListeners.clear();
   internals.activityRegistriesByWorkflow.clear();
@@ -68,3 +75,9 @@ function disposeSecondInstanceDetection(internals) {
     internals.secondInstanceDetector = null;
   }
 }
+function disposeLeaseManager(internals) {
+  if (internals.leaseManager !== null) {
+    internals.leaseManager.stop();
+    internals.leaseManager = null;
+  }
+}

package/dist/core/engine/engine-create-types.d.ts

@@ -1,4 +1,4 @@
-import type { AnyActivityDefinition, AnyWorkflowDefinition, IsDefaultWorkflowRegistry } from '../types.ts';
+import type { AnyActivityDefinition, AnyWorkflowDefinition, DefaultWorkflowRegistry, InferWorkflowEntries, IsDefaultWorkflowRegistry, WorkflowServicesUnion } from '../types.ts';
 import type { UnknownNameWhenRegistryHasNoKnownNames } from '../types/registry-type-helpers.ts';
 import type { KnownWorkflowNames } from './construction.ts';
 import type { EngineConstructorOptions } from './engine-internal-types.ts';
@@ -24,7 +24,7 @@ import type { EngineConstructorOptions } from './engine-internal-types.ts';
  * void engine;
  * ```
  */
-export type EngineCreateOptions<TWorkflowDefinitions extends Record<string, AnyWorkflowDefinition> = {}, TActivityDefinitions extends Record<string, AnyActivityDefinition> = {}> = EngineConstructorOptions & {
+export type EngineCreateOptions<TWorkflowDefinitions extends Record<string, AnyWorkflowDefinition> = {}, TActivityDefinitions extends Record<string, AnyActivityDefinition> = {}> = EngineConstructorOptions<WorkflowServicesUnion<EngineCreateWorkflowRegistry<TWorkflowDefinitions>>> & {
     /** Workflow definitions to register before recovery. */
     workflows?: TWorkflowDefinitions;
     /** Activity definitions to register before workflows. */
@@ -34,13 +34,13 @@ export type EngineCreateOptions<TWorkflowDefinitions extends Record<string, AnyW
      * Recover stored running workflows after registration. Defaults to
      * `true`: a fresh engine booting against durable storage resumes any
      * workflows left in flight by a previous process. Pass `recover: false`
-     * to opt out (tests, `ScopedStorage` isolation, pre-migration
+     * to opt out (tests, `ScopedStorage` isolation, explicit operator
      * inspection).
      */
     recover?: true | undefined;
     /**
      * Forwarded to `Engine.recoverAll`. Only use this during rolling
-     * deploys or explicit storage migrations.
+     * deploys or explicit operator storage repair.
      */
     acknowledgeUnknownWorkflowTypes?: boolean;
 } | {
@@ -49,6 +49,16 @@ export type EngineCreateOptions<TWorkflowDefinitions extends Record<string, AnyW
     /** Only valid when recovery is enabled (the default). Invalid with `recover: false`. */
     acknowledgeUnknownWorkflowTypes?: never;
 });
+/**
+ * Resolves the workflow registry type for `Engine.create` return values.
+ *
+ * When the provided workflow definition map is empty (`{}`), the resulting
+ * engine carries the same `DefaultWorkflowRegistry` brand as an engine
+ * constructed without a `workflows` map at all — the two are semantically
+ * identical. A non-empty map routes to `InferWorkflowEntries` so literal
+ * workflow-name inference is preserved.
+ */
+export type EngineCreateWorkflowRegistry<TWorkflowDefinitions extends Record<string, AnyWorkflowDefinition>> = [keyof TWorkflowDefinitions & string] extends [never] ? DefaultWorkflowRegistry : InferWorkflowEntries<TWorkflowDefinitions>;
 export type UnknownWorkflowNameWhenDefaultRegistryIsEmpty<TWorkflows extends object, TName extends string> = IsDefaultWorkflowRegistry<TWorkflows> extends true ? UnknownNameWhenRegistryHasNoKnownNames<TName, KnownWorkflowNames<TWorkflows>> : never;
 export type ActivityDefinitionName<TDefinition extends AnyActivityDefinition> = TDefinition extends {
     readonly name: infer TName extends string;

package/dist/core/engine/engine-internal-types.d.ts

@@ -2,7 +2,7 @@ import type { Storage as WeftStorage } from '../../storage/interface.ts';
 import type { ConstraintDefinition } from '../constraint.ts';
 import type { ExecutionStrategy } from '../execution-strategy.ts';
 import type { InlineExecutionStrategy } from '../inline-execution-strategy.ts';
-import type { ArchiveAdapter, Checkpoint, DefinitionSchema, EngineOptions, NormalizedHistoryPolicy, NormalizedPayloadSizePolicy, NormalizedRetentionPolicy, SearchAttributeSchema, WorkflowFunction, WorkflowTimelineEntry } from '../types.ts';
+import type { AnyActivityDefinition, ArchiveAdapter, Checkpoint, DefinitionSchema, EngineOptions, NormalizedHistoryPolicy, NormalizedPayloadSizePolicy, NormalizedRetentionPolicy, SearchAttributeSchema, WorkflowConcurrencyOptions, WorkflowFunction, WorkflowTimelineEntry } from '../types.ts';
 export interface RegistrationEntry {
     handler: WorkflowFunction;
     version: string;
@@ -10,10 +10,16 @@ export interface RegistrationEntry {
     tags?: ReadonlyArray<string>;
     inputSchema?: DefinitionSchema;
     outputSchema?: DefinitionSchema;
-    migrate?: (checkpoint: unknown, fromVersion: string) => unknown;
     searchAttributes?: SearchAttributeSchema;
     retention?: NormalizedRetentionPolicy;
+    concurrency?: WorkflowConcurrencyOptions;
     constraints?: ConstraintDefinition[];
+    /**
+     * Definition-level teardown activity (issue #446), driven by the engine after a
+     * `cancelled`/`timed-out` terminal. Stored on the engine-lifetime registry so it
+     * survives per-workflow terminal cleanup; resolved at teardown by workflow type.
+     */
+    finalizer?: AnyActivityDefinition;
 }
 export interface ResolvedOptions {
     storage: WeftStorage;
@@ -33,19 +39,36 @@ export interface ResolvedOptions {
     secondInstanceDetectionEnabled: boolean;
     /** Heartbeat interval (ms) for the second-instance detector when enabled. */
     secondInstanceHeartbeatIntervalMs: number;
+    /**
+     * Single-writer ownership posture. `'none'` recovers immediately (infra owns
+     * mutual exclusion); `'lease'` acquires a storage lease before recovery. The
+     * lease tuning fields below are only meaningful when this is `'lease'`.
+     */
+    ownershipMode: 'none' | 'lease';
+    /** Lease time-to-live (ms) when `ownershipMode` is `'lease'`. */
+    leaseTtlMs: number;
+    /** Lease renewal interval (ms) when `ownershipMode` is `'lease'`. */
+    leaseRenewIntervalMs: number;
+    /** Boot-time lease acquisition wait window (ms) when `ownershipMode` is `'lease'`. */
+    leaseWaitTimeoutMs: number;
     getNow: () => number;
     /**
      * Re-provides the non-serialized per-run `services` value on recovery; `null`
      * when the engine was created without `resolveWorkflowServices`.
      */
     resolveWorkflowServices: EngineOptions['resolveWorkflowServices'] | null;
+    /**
+     * Host sink for `ctx.log` records (`EngineOptions.onLog`); `null` when the engine
+     * was created without one (the default console behavior).
+     */
+    onLog: EngineOptions['onLog'] | null;
 }
 export interface WorkflowResultWaiter {
     promise: Promise<unknown>;
     resolve: (value: unknown) => void;
     reject: (reason: unknown) => void;
 }
-export type EngineConstructorOptions = Partial<EngineOptions> & {
+export type EngineConstructorOptions<TServices = unknown> = Partial<EngineOptions<TServices>> & {
     getNow?: () => number;
 };
 export type ExecutionStrategyBundle = {

package/dist/core/engine/errors.d.ts

@@ -27,6 +27,29 @@ export declare class WorkflowAlreadyExistsError extends WeftError<'WorkflowAlrea
     readonly workflowId: string;
     constructor(workflowId: string);
 }
+/**
+ * Thrown by {@link Engine.start} with `onTerminalConflict: 'start-new'` when the
+ * prior terminal run under the requested id still owes an engine-driven finalizer
+ * (issue #446). Unlike {@link WorkflowAlreadyExistsError}, this is **transient**:
+ * the restart is refused only so the displacing purge cannot delete the finalizer
+ * payload before the resource is torn down. Once the finalizer completes (or
+ * permanently dead-letters), the marker clears and the same restart succeeds — so a
+ * caller should retry after a short delay rather than treat the id as permanently
+ * taken.
+ *
+ * @example
+ * ```ts
+ * import { WorkflowTeardownPendingError } from '@lostgradient/weft';
+ *
+ * function shouldRetryRestartLater(error: unknown): boolean {
+ *   return error instanceof WorkflowTeardownPendingError;
+ * }
+ * ```
+ */
+export declare class WorkflowTeardownPendingError extends WeftError<'WorkflowTeardownPendingError'> {
+    readonly workflowId: string;
+    constructor(workflowId: string);
+}
 /**
  * Thrown by {@link Engine.deleteAll} when the supplied filter would match
  * non-terminal workflows. Narrow the filter to completed, failed, cancelled,
@@ -187,6 +210,30 @@ export declare class WorkflowNotRegisteredError extends WeftError<'WorkflowNotRe
     readonly workflowType: string;
     constructor(workflowType: string);
 }
+/**
+ * Thrown by {@link Engine.start} when a workflow definition's `concurrency`
+ * policy has no free slot for the requested workflow type or partition key.
+ * Starts are rejected immediately; Weft does not queue excess starts.
+ *
+ * @example
+ * ```ts
+ * import { WorkflowConcurrencyLimitExceededError } from '@lostgradient/weft';
+ *
+ * function isCapacityRejection(error: unknown): boolean {
+ *   return error instanceof WorkflowConcurrencyLimitExceededError;
+ * }
+ * ```
+ */
+export declare class WorkflowConcurrencyLimitExceededError extends WeftError<'WorkflowConcurrencyLimitExceededError'> {
+    readonly workflowType: string;
+    readonly limit: number;
+    readonly partitionKey: string;
+    constructor(parameters: {
+        workflowType: string;
+        limit: number;
+        partitionKey: string;
+    });
+}
 /**
  * Thrown by {@link Engine.suspend} when invoked on an engine running in worker
  * execution mode. Suspension parks the live run without aborting it, which the

package/dist/core/engine/errors.js

@@ -8,6 +8,14 @@ export class WorkflowAlreadyExistsError extends WeftError {
   }
 }
 
+export class WorkflowTeardownPendingError extends WeftError {
+  workflowId;
+  constructor(workflowId) {
+    super("WorkflowTeardownPendingError", `Cannot restart workflow "${workflowId}" under the same id: its prior run is tearing down a resource (finalizer in progress). Retry after the teardown completes.`);
+    this.workflowId = workflowId;
+  }
+}
+
 export class BulkDeleteRequiresTerminalWorkflowsError extends WeftError {
   constructor() {
     super("BulkDeleteRequiresTerminalWorkflowsError", "Bulk delete matches non-terminal workflows");
@@ -78,6 +86,18 @@ export class WorkflowNotRegisteredError extends WeftError {
   }
 }
 
+export class WorkflowConcurrencyLimitExceededError extends WeftError {
+  workflowType;
+  limit;
+  partitionKey;
+  constructor(parameters) {
+    super("WorkflowConcurrencyLimitExceededError", `Workflow "${parameters.workflowType}" concurrency limit ${parameters.limit} reached for partition key "${parameters.partitionKey}"`);
+    this.workflowType = parameters.workflowType;
+    this.limit = parameters.limit;
+    this.partitionKey = parameters.partitionKey;
+  }
+}
+
 export class WorkflowSuspendNotSupportedError extends WeftError {
   constructor(message) {
     super("WorkflowSuspendNotSupportedError", message);

package/dist/core/engine/event-log-compaction.d.ts

@@ -18,6 +18,7 @@
  * @module core/engine/event-log-compaction
  */
 import type { BatchOperation, Storage } from '../../storage/interface.ts';
+import { type CheckpointReplayPayload } from './checkpoint-replay.ts';
 /**
  * Upper bound on event-log records deleted in a single compaction (one
  * checkpoint commit). A workflow that enables `retentionWindow` with a large
@@ -52,6 +53,13 @@ export type EventLogWatermark = {
      * deleted prefix — unambiguous across incremental batches.
      */
     deletedThrough: number;
+    /**
+     * Internal replay deltas folded from compacted checkpoint events. Canonical
+     * checkpoints can prune consumed results only because recovery can seed replay
+     * from the event log; when old events are compacted, their replay deltas move
+     * here before deletion.
+     */
+    checkpointReplay?: CheckpointReplayPayload;
 };
 /**
  * Narrow an unknown decoded value to {@link EventLogWatermark}, rejecting