@lostgradient/weft 0.2.1 → 0.4.0

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,37 +24,23 @@ 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. */
     activities?: TActivityDefinitions;
-    /**
-     * Opt out of the persisted-data schema-version gate when opening a storage
-     * that contains workflow data written by `new Engine({ storage })` before
-     * the schema-version sentinel existed.
-     *
-     * The gate normally rejects any storage that already holds workflow records
-     * but lacks the sentinel — a safety check against silently classifying
-     * pre-sentinel data as schema-current. Set `allowLegacyData: true` only when
-     * you knowingly opened the same storage with the legacy constructor path and
-     * are intentionally recovering it via `Engine.create`. On success, the
-     * current schema-version sentinel is written. Remove the opt-in once the
-     * data has been migrated.
-     */
-    allowLegacyData?: boolean;
 } & ({
     /**
      * 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;
 } | {
@@ -63,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;
@@ -29,19 +35,40 @@ export interface ResolvedOptions {
     /** Operator-supplied sink for compacted event-log ranges; `null` when none. */
     archiveAdapter: ArchiveAdapter | null;
     payloadSizePolicy: NormalizedPayloadSizePolicy;
+    /** Whether the best-effort second-instance liveness detector is enabled. */
+    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 = {
@@ -61,4 +88,12 @@ export type QueuedInlineWorkflowExecutionStart = {
     nestingDepth: number;
     executionDeadline: number | undefined;
     executionStateOwnerId: string;
+    /**
+     * Liveness callback invoked once this queued start has actually begun
+     * executing (its generator has been driven). Set only for `defer: false`
+     * launches, which await it before `engine.start()` resolves. Fired exactly
+     * once; a discarded start (engine disposed without draining) settles it via
+     * the dispose path so the `defer: false` awaiter never hangs.
+     */
+    onStarted?: () => void;
 };

package/dist/core/engine/engine-leak-warnings.d.ts

@@ -6,6 +6,12 @@
 export type EngineCleanupIntervalDisposalTracker = {
     disposed: boolean;
     cleanupInterval: ReturnType<typeof setInterval> | null;
+    /**
+     * The optional second-instance detector interval, tracked alongside the
+     * cleanup interval so the same finalizer clears it when an engine is
+     * garbage-collected without `[Symbol.dispose]()`. Null when detection is off.
+     */
+    secondInstanceDetectionInterval: ReturnType<typeof setInterval> | null;
     testToken: symbol | undefined;
 };
 export declare const engineCleanupIntervalFinalizer: FinalizationRegistry<EngineCleanupIntervalDisposalTracker>;

package/dist/core/engine/engine-leak-warnings.js

@@ -6,6 +6,10 @@ export const engineCleanupIntervalFinalizer = new FinalizationRegistry((tracker)
     clearInterval(tracker.cleanupInterval);
     tracker.cleanupInterval = null;
   }
+  if (tracker.secondInstanceDetectionInterval !== null) {
+    clearInterval(tracker.secondInstanceDetectionInterval);
+    tracker.secondInstanceDetectionInterval = null;
+  }
   if (!tracker.disposed && shouldEmitEngineLeakWarning()) {
     if (tracker.testToken !== void 0)
       engineLeakWarningTokensForTesting.add(tracker.testToken);

package/dist/core/engine/engine-runtime-helpers.d.ts

@@ -2,7 +2,24 @@ import type { AnyActivityDefinition } from '../types.ts';
 import { type EngineCleanupIntervalDisposalTracker } from './engine-leak-warnings.ts';
 import type { Engine } from './index.ts';
 import { type EngineInternals } from './internals.ts';
+import type { SecondInstanceDetector } from './second-instance-detector.ts';
 export declare function isActivityDefinition(value: unknown): value is AnyActivityDefinition;
 export declare function createQueuedInlineWorkflowStartHandler<TWorkflows extends object, TActivities extends object>(weakEngine: WeakRef<Engine<TWorkflows, TActivities>>, channel: MessageChannel): () => void;
+/**
+ * Drain pending inline launches for `engine` before teardown. Built with the
+ * same inline-launch-queue callbacks as the scheduled flush handler so a drained
+ * start advances identically to a normally-flushed one. Called from
+ * `[Symbol.asyncDispose]` ahead of synchronous disposal (which aborts the signal
+ * and would otherwise discard the queue).
+ */
+export declare function drainQueuedInlineWorkflowStartsForEngine<TWorkflows extends object, TActivities extends object>(engine: Engine<TWorkflows, TActivities>): Promise<void>;
 export declare function createCleanupIntervalTick<TWorkflows extends object, TActivities extends object>(weakEngine: WeakRef<Engine<TWorkflows, TActivities>>, tracker: EngineCleanupIntervalDisposalTracker): () => void;
+/**
+ * Build the resolver the second-instance detection interval uses to find its live
+ * detector. Returns `null` when the engine has been garbage-collected or disposed
+ * (so the tick is skipped), otherwise the engine's current detector. Extracted
+ * here — like {@link createCleanupIntervalTick} — so the deref/disposed guard is
+ * directly testable without driving a real interval.
+ */
+export declare function createSecondInstanceDetectorResolver<TWorkflows extends object, TActivities extends object>(weakEngine: WeakRef<Engine<TWorkflows, TActivities>>): () => SecondInstanceDetector | null;
 export declare function disposeEngineCleanupInterval(internals: EngineInternals): void;

package/dist/core/engine/engine-runtime-helpers.js

@@ -3,12 +3,22 @@ import { createLifecycleCallbacks, createTerminationCallbacks } from "./callback
 import {
   engineCleanupIntervalFinalizer
 } from "./engine-leak-warnings.js";
-import { flushQueuedInlineWorkflowStarts } from "./inline-launch-queue.js";
+import {
+  drainQueuedInlineWorkflowStarts,
+  flushQueuedInlineWorkflowStarts
+} from "./inline-launch-queue.js";
 import { getInternals } from "./internals.js";
 import { swallowPromiseRejection } from "./strategy-helpers.js";
 export function isActivityDefinition(value) {
   return typeof value === "function" && typeof value.name === "string" && "execute" in value && typeof value.execute === "function";
 }
+function inlineLaunchQueueCallbacksForEngine(engine) {
+  const lifecycleCallbacks = createLifecycleCallbacks(engine);
+  return {
+    processPendingUpdatesAfterInlineAdvance: (workflowId) => lifecycleCallbacks.processPendingUpdatesAfterInlineAdvance(workflowId),
+    swallowPromiseRejection: (promise) => swallowPromiseRejection(promise)
+  };
+}
 export function createQueuedInlineWorkflowStartHandler(weakEngine, channel) {
   return function handleQueuedInlineWorkflowStart() {
     const engine = weakEngine.deref();
@@ -18,12 +28,12 @@ export function createQueuedInlineWorkflowStartHandler(weakEngine, channel) {
       return;
     }
     getInternals(engine).queuedInlineWorkflowStartFlushScheduled = !1;
-    swallowPromiseRejection(flushQueuedInlineWorkflowStarts(getInternals(engine), {
-      processPendingUpdatesAfterInlineAdvance: (workflowId) => createLifecycleCallbacks(engine).processPendingUpdatesAfterInlineAdvance(workflowId),
-      swallowPromiseRejection: (promise) => swallowPromiseRejection(promise)
-    }));
+    swallowPromiseRejection(flushQueuedInlineWorkflowStarts(getInternals(engine), inlineLaunchQueueCallbacksForEngine(engine)));
   };
 }
+export async function drainQueuedInlineWorkflowStartsForEngine(engine) {
+  await drainQueuedInlineWorkflowStarts(getInternals(engine), inlineLaunchQueueCallbacksForEngine(engine));
+}
 export function createCleanupIntervalTick(weakEngine, tracker) {
   return function cleanupExpiredResponsesForLiveEngine() {
     const engine = weakEngine.deref();
@@ -38,6 +48,17 @@ export function createCleanupIntervalTick(weakEngine, tracker) {
     createExpiredResponseCleanupTick(internals.updateCoordinator, (source, error) => createTerminationCallbacks(engine).handleCleanupError(source, error))();
   };
 }
+export function createSecondInstanceDetectorResolver(weakEngine) {
+  return function resolveLiveSecondInstanceDetector() {
+    const engine = weakEngine.deref();
+    if (engine === void 0)
+      return null;
+    const internals = getInternals(engine);
+    if (internals.disposed)
+      return null;
+    return internals.secondInstanceDetector;
+  };
+}
 export function disposeEngineCleanupInterval(internals) {
   if (internals.cleanupInterval !== null) {
     clearInterval(internals.cleanupInterval ?? void 0);

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

@@ -1,3 +1,4 @@
+import type { WorkflowStatus } from '../types/identity.ts';
 import { WeftError } from '../weft-error.ts';
 /**
  * Thrown by {@link Engine.start} when a workflow with the requested ID already
@@ -26,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,
@@ -186,6 +210,56 @@ 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
+ * inline strategy supports directly; a worker run cannot be paused without
+ * sending it a cancellation, so the engine refuses rather than silently
+ * aborting. Suspend/resume in worker mode is a scoped follow-up.
+ *
+ * @example
+ * ```ts
+ * import { Engine, WorkflowSuspendNotSupportedError } from '@lostgradient/weft';
+ *
+ * async function trySuspend(engine: Engine, id: string) {
+ *   try {
+ *     await engine.suspend(id);
+ *   } catch (err) {
+ *     if (err instanceof WorkflowSuspendNotSupportedError) {
+ *       // worker-mode engine: cancel instead, or run inline
+ *     }
+ *   }
+ * }
+ * void trySuspend;
+ * ```
+ */
+export declare class WorkflowSuspendNotSupportedError extends WeftError<'WorkflowSuspendNotSupportedError'> {
+    constructor(message: string);
+}
 /**
  * Thrown when the engine cannot resolve an activity name to a registered
  * function during dispatch. The per-workflow {@link ActivityRegistry} (built
@@ -212,4 +286,51 @@ export declare class ActivityResolutionError extends WeftError<'ActivityResoluti
     readonly activityName: string;
     constructor(workflowType: string, activityName: string);
 }
+/**
+ * Thrown by {@link Engine.startOrSignal} when the target workflow already exists
+ * and is in a terminal state (completed, failed, cancelled, or timed out). A
+ * terminal run cannot accept a signal and must not be silently replaced, so
+ * `startOrSignal` surfaces this conflict instead of starting a fresh run under
+ * the same id or dropping the signal.
+ *
+ * Inspect `workflowId` to identify the conflicting run and `status` to see why
+ * it was rejected. To deliberately start a new run, choose a different id (or
+ * idempotency key); to deliver to a fresh run, terminal-state reuse is not a
+ * supported policy.
+ *
+ * @example
+ * ```ts
+ * import { StartOrSignalConflictError } from '@lostgradient/weft';
+ *
+ * function isTerminalStartOrSignalConflict(error: unknown): boolean {
+ *   return error instanceof StartOrSignalConflictError;
+ * }
+ * ```
+ */
+export declare class StartOrSignalConflictError extends WeftError<'StartOrSignalConflictError'> {
+    readonly workflowId: string;
+    readonly status: WorkflowStatus;
+    constructor(workflowId: string, status: WorkflowStatus);
+}
+/**
+ * Thrown by {@link Engine.start} / {@link Engine.startOrSignal} when an
+ * `idempotencyKey` resolves to a workflow that no longer exists — its run was
+ * purged or bulk-deleted while the durable `start-idem:` mapping (intentionally
+ * not swept on cleanup) lived on. The key is "spent": it can neither return the
+ * gone run nor safely start a fresh one under the same key (a concurrent caller
+ * may still hold the mapping). Use a different idempotency key to start anew.
+ *
+ * @example
+ * ```ts
+ * import { IdempotencyKeyPurgedError } from '@lostgradient/weft';
+ *
+ * function isPurgedIdempotencyKey(error: unknown): boolean {
+ *   return error instanceof IdempotencyKeyPurgedError;
+ * }
+ * ```
+ */
+export declare class IdempotencyKeyPurgedError extends WeftError<'IdempotencyKeyPurgedError'> {
+    readonly workflowId: string;
+    constructor(workflowId: string);
+}
 export { PersistedDataIncompatibleError } from '../persisted-data-incompatible-error.ts';

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,13 +86,49 @@ 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);
+  }
+}
+
 export class ActivityResolutionError extends WeftError {
   workflowType;
   activityName;
   constructor(workflowType, activityName) {
-    super("ActivityResolutionError", `No activity registered with name "${activityName}" for workflow type "${workflowType}". Register the activity via \`workflow({ name }).activities({ ... })\` on the workflow that runs it, or via \`engine.register(activityDefinition)\` for the legacy global registry.`);
+    super("ActivityResolutionError", `No activity registered with name "${activityName}" for workflow type "${workflowType}". Register the activity via \`workflow({ name }).activities({ ... })\` on the workflow that runs it, or via \`engine.register(activityDefinition)\` to make it available to every workflow on that engine instance.`);
     this.workflowType = workflowType;
     this.activityName = activityName;
   }
 }
+
+export class StartOrSignalConflictError extends WeftError {
+  workflowId;
+  status;
+  constructor(workflowId, status) {
+    super("StartOrSignalConflictError", `Workflow "${workflowId}" is already in terminal state "${status}" and cannot accept a startOrSignal: a terminal run cannot be signalled and is not replaced. Use a different id or idempotency key to start a new run.`);
+    this.workflowId = workflowId;
+    this.status = status;
+  }
+}
+
+export class IdempotencyKeyPurgedError extends WeftError {
+  workflowId;
+  constructor(workflowId) {
+    super("IdempotencyKeyPurgedError", `The idempotency key maps to workflow "${workflowId}", which no longer exists (it was purged or deleted). Use a different idempotency key to start a new run.`);
+    this.workflowId = workflowId;
+  }
+}
 export { PersistedDataIncompatibleError } from "../persisted-data-incompatible-error.js";

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

package/dist/core/engine/event-log-compaction.js

@@ -2,6 +2,10 @@ import { hashBytes } from "../../runtime/portable.js";
 import { KEYS } from "../../storage/interface.js";
 import { decode, encode } from "../codec.js";
 import { isWorkflowLogEntry } from "../event-log-shared.js";
+import {
+  mergeCheckpointReplayPayloads,
+  readCheckpointReplayPayload
+} from "./checkpoint-replay.js";
 export const MAX_COMPACTION_BATCH = 1000;
 export function isEventLogWatermark(value) {
   if (typeof value !== "object" || value === null)
@@ -27,7 +31,7 @@ export async function readEventLogWatermark(storage, workflowId) {
 export async function appendCompactionOperations(storage, workflowId, headSequence, retentionWindow, operations) {
   if (retentionWindow === null)
     return null;
-  const targetFirstSurviving = Math.max(0, headSequence - retentionWindow + 1), currentFloor = (await readEventLogWatermark(storage, workflowId))?.sequence ?? 0, batchFirstSurviving = Math.min(targetFirstSurviving, currentFloor + MAX_COMPACTION_BATCH);
+  const targetFirstSurviving = Math.max(0, headSequence - retentionWindow + 1), existing = await readEventLogWatermark(storage, workflowId), currentFloor = existing?.sequence ?? 0, batchFirstSurviving = Math.min(targetFirstSurviving, currentFloor + MAX_COMPACTION_BATCH);
   if (batchFirstSurviving <= currentFloor)
     return null;
   const collected = await collectDeleteRange(storage, workflowId, currentFloor, batchFirstSurviving);
@@ -38,7 +42,8 @@ export async function appendCompactionOperations(storage, workflowId, headSequen
     version: 1,
     sequence: batchFirstSurviving,
     prevHash,
-    deletedThrough: batchFirstSurviving - 1
+    deletedThrough: batchFirstSurviving - 1,
+    ...optionalCheckpointReplay(mergeDeletedCheckpointReplayPayloads(existing?.checkpointReplay, collected.deletedEntries))
   };
   for (let sequence = currentFloor;sequence < batchFirstSurviving; sequence += 1)
     operations.push({ type: "delete", key: KEYS.event(workflowId, sequence) });
@@ -53,6 +58,19 @@ export async function appendCompactionOperations(storage, workflowId, headSequen
     deletedRange: { from: currentFloor, to: batchFirstSurviving - 1 }
   };
 }
+function optionalCheckpointReplay(checkpointReplay) {
+  return checkpointReplay === void 0 ? {} : { checkpointReplay };
+}
+function mergeDeletedCheckpointReplayPayloads(existing, deletedEntries) {
+  let merged = existing;
+  for (const bytes of deletedEntries) {
+    const decoded = decode(bytes);
+    if (!isWorkflowLogEntry(decoded))
+      continue;
+    merged = mergeCheckpointReplayPayloads(merged, readCheckpointReplayPayload(decoded.payload));
+  }
+  return merged;
+}
 async function collectDeleteRange(storage, workflowId, currentFloor, batchFirstSurviving) {
   const deletedEntries = [];
   let expected = currentFloor;

package/dist/core/engine/fenced-write.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Step-2 epoch fencing for `ownership: 'lease'` (issue #470).
+ *
+ * Step 1 made a rolling deploy a clean lease handoff but added no correctness
+ * backstop: a deposed zombie instance (GC pause, partition) that emerged after
+ * its lease expired could still issue a plain durable write and corrupt the
+ * successor's state. Step 2 closes that hole by conditioning every
+ * engine-generator-owned per-workflow durable write on the held lease epoch, so
+ * a deposed instance's write loses its CAS instead of landing.
+ *
+ * The correctness guarantee lives entirely in the epoch CONDITION: a deposed
+ * instance's commit CAS-fails regardless of any in-process flag, because the
+ * successor bumped `lease:epoch` when it took over. The {@link EngineInternals.deposed}
+ * flag and the engine teardown are hygiene on top of that — they stop the engine
+ * from silently spinning on swallowed write losses, surface the deposition to the
+ * operator, and release resources. They are not what makes the system safe.
+ *
+ * This module is allow-listed for import only from `src/core/engine/**`.
+ */
+import type { BatchOperation, ConditionalBatchCondition } from '../../storage/interface.ts';
+import type { EngineInternals } from './internals.ts';
+/**
+ * Reject an engine-owned work entry point (start, startOrSignal, fork, resume)
+ * when `ownership: 'lease'` is configured but the engine does not currently hold
+ * the lease. The lease is acquired at the two boot gates ({@link Engine.create}
+ * and {@link Engine.recoverAll}); a directly constructed engine that does engine
+ * work before `recoverAll()` would otherwise durably write workflow state without
+ * single-writer ownership and without having recovered existing runs. Placed at
+ * each public awaited entry so the caller gets a clean {@link EngineLeaseNotHeldError}
+ * — without this, fork/resume would reach `resolveFenceEpochOrHalt` with no held
+ * epoch and be misreported as a deposition (warn + teardown) rather than the true
+ * "lease not held yet" condition. A no-op under `ownership: 'none'`.
+ */
+export declare function assertLeaseHeldForEngineWork(internals: EngineInternals): void;
+/**
+ * Commit an engine-generator-owned durable write, fenced on the held lease epoch
+ * under `ownership: 'lease'` (a byte-for-byte no-op under `ownership: 'none'`). A
+ * lost CAS race throws the caller-supplied `onLostRace` error so existing retry
+ * semantics apply; a deposition halts the engine and throws
+ * {@link EngineDeposedError}. The helper owns the batch-vs-conditionalBatch
+ * decision — pass plain operations plus whatever base conditions you already need.
+ *
+ * @param internals - the engine internals (ownership mode, lease manager, deposed flag)
+ * @param operations - the durable operations to commit atomically
+ * @param baseConditions - CAS conditions the caller already requires (may be empty)
+ * @param onLostRace - builds the error thrown on a same-epoch lost CAS race
+ */
+export declare function commitFencedEngineWrite(internals: EngineInternals, operations: BatchOperation[], baseConditions: ConditionalBatchCondition[], onLostRace: () => Error): Promise<void>;
+/**
+ * Like {@link commitFencedEngineWrite}, but the caller treats a base-precondition
+ * failure as a legitimate outcome rather than an error — used by the idempotent
+ * start path, where a `false` means a concurrent same-key caller already wrote the
+ * record (resolve to the existing run) rather than "retry". Returns `true` when the
+ * batch committed and `false` when a base condition failed. Deposition is still a
+ * hard halt: if the epoch condition is the one that failed, this drives
+ * {@link handleDeposition} and throws {@link EngineDeposedError} — a deposed engine
+ * must never report a precondition-failure the caller would read as "already exists"
+ * and silently move on.
+ *
+ * @param internals - the engine internals
+ * @param operations - the durable operations to commit atomically
+ * @param baseConditions - the caller's required CAS conditions (non-empty in
+ *   practice — this path is for conditional starts, which always carry one)
+ */
+export declare function commitFencedEngineWriteAllowingPreconditionFailure(internals: EngineInternals, operations: BatchOperation[], baseConditions: ConditionalBatchCondition[]): Promise<boolean>;