@lostgradient/weft 0.2.0 → 0.3.0

package/dist/core/engine/persisted-data-version.js

@@ -4,7 +4,7 @@ import {
   PersistedDataIncompatibleError
 } from "../persisted-data-incompatible-error.js";
 const SCHEMA_VERSION_PATTERN = /^(?:0|[1-9]\d*)$/, USER_DATA_PREFIXES = ["wf:", "op:", "schedule:", "ev:", "sig:", "upd:", "idx:"];
-export async function assertCompatiblePersistedDataVersion(storage, options = {}) {
+export async function assertCompatiblePersistedDataVersion(storage) {
   const raw = await storage.get(PERSISTED_DATA_SCHEMA_VERSION_KEY);
   if (raw !== null) {
     const text = new TextDecoder().decode(raw);
@@ -17,9 +17,8 @@ export async function assertCompatiblePersistedDataVersion(storage, options = {}
       throw new PersistedDataIncompatibleError(parsed, CURRENT_PERSISTED_DATA_SCHEMA_VERSION);
     return;
   }
-  if (!options.allowLegacyData)
-    for (const prefix of USER_DATA_PREFIXES)
-      for await (const _entry of storage.scan(prefix, { limit: 1 }))
-        throw new PersistedDataIncompatibleError(null, CURRENT_PERSISTED_DATA_SCHEMA_VERSION);
+  for (const prefix of USER_DATA_PREFIXES)
+    for await (const _entry of storage.scan(prefix, { limit: 1 }))
+      throw new PersistedDataIncompatibleError(null, CURRENT_PERSISTED_DATA_SCHEMA_VERSION);
   await storage.put(PERSISTED_DATA_SCHEMA_VERSION_KEY, new TextEncoder().encode(String(CURRENT_PERSISTED_DATA_SCHEMA_VERSION)));
 }

package/dist/core/engine/schedule-handle.d.ts

@@ -0,0 +1,45 @@
+import type { ScheduleSpec, ScheduleSummary } from '../types.ts';
+/**
+ * Narrow engine view a {@link ScheduleHandle} delegates to. The full
+ * {@link Engine} implements it; the handle only depends on these schedule
+ * lifecycle operations.
+ */
+export interface ScheduleHandleEngine {
+    pauseSchedule(scheduleId: string): Promise<void>;
+    resumeSchedule(scheduleId: string): Promise<void>;
+    cancelSchedule(scheduleId: string): Promise<void>;
+    updateSchedule(scheduleId: string, newSpec: string | ScheduleSpec): Promise<void>;
+    getSchedule(scheduleId: string): Promise<ScheduleSummary | null>;
+}
+/**
+ * Handle to a recurring schedule created by {@link Engine.schedule}. Use
+ * `handle.pause()`, `handle.resume()`, `handle.cancel()`, or
+ * `handle.update(cronExpression)` to manage the schedule lifecycle.
+ * `handle.describe()` returns the current {@link ScheduleSummary}.
+ *
+ * @example
+ * ```ts
+ * import { workflow, Engine, ScheduleHandle } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.register(workflow({ name: 'daily-report' }).execute(async function* () { return 'ok'; }));
+ *
+ * const handle = await engine.schedule('daily-report', null, '0 9 * * *');
+ * const typedHandle: ScheduleHandle = handle;
+ * await handle.pause();
+ * const summary = await handle.describe();
+ * void typedHandle;
+ * console.log(summary.status); // 'paused'
+ * await handle.cancel();
+ * ```
+ */
+export declare class ScheduleHandle {
+    #private;
+    readonly id: string;
+    constructor(id: string, engine: ScheduleHandleEngine);
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    cancel(): Promise<void>;
+    update(newSpec: string | ScheduleSpec): Promise<void>;
+    describe(): Promise<ScheduleSummary>;
+}

package/dist/core/engine/schedule-handle.js

@@ -0,0 +1,26 @@
+export class ScheduleHandle {
+  id;
+  #engine;
+  constructor(id, engine) {
+    this.id = id;
+    this.#engine = engine;
+  }
+  async pause() {
+    await this.#engine.pauseSchedule(this.id);
+  }
+  async resume() {
+    await this.#engine.resumeSchedule(this.id);
+  }
+  async cancel() {
+    await this.#engine.cancelSchedule(this.id);
+  }
+  async update(newSpec) {
+    await this.#engine.updateSchedule(this.id, newSpec);
+  }
+  async describe() {
+    const schedule = await this.#engine.getSchedule(this.id);
+    if (!schedule)
+      throw Error(`Schedule "${this.id}" not found`);
+    return schedule;
+  }
+}

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

@@ -1,7 +1,7 @@
 import type { BatchOperation } from '../../storage/interface.ts';
 import type { PaginatedResult, ScheduleFilter, ScheduleOptions, ScheduleSpec, ScheduleState, ScheduleSummary, WorkflowState } from '../types.ts';
-import { ScheduleHandle } from './handles.ts';
 import type { EngineInternals } from './internals.ts';
+import { ScheduleHandle } from './schedule-handle.ts';
 export { handleScheduleTimer } from './schedule-timer.ts';
 export type RefreshedScheduleState = {
     state: ScheduleState;

package/dist/core/engine/schedules.js

@@ -1,7 +1,7 @@
 import { KEYS } from "../../storage/interface.js";
 import { decode, encode } from "../codec.js";
 import { WorkflowNotRegisteredError } from "./errors.js";
-import { ScheduleHandle } from "./handles.js";
+import { ScheduleHandle } from "./schedule-handle.js";
 import { getNextScheduleOccurrence } from "./schedule-occurrence.js";
 import {
   clearScheduleCurrentWorkflow,
@@ -123,11 +123,15 @@ export async function updateSchedule(internals, scheduleId, newSpec) {
   };
   await writeScheduleState(internals, updatedState, { includeTimer: state.status === "active" });
 }
+function scheduledRunOccupiesSlot(currentWorkflowState) {
+  const status = currentWorkflowState?.status;
+  return status === "running" || status === "pending" || status === "suspended";
+}
 export async function refreshScheduledWorkflowState(internals, state, callbacks) {
   if (!state.currentWorkflowId)
     return { state, currentWorkflowState: null };
   const currentWorkflowState = await callbacks.loadWorkflowState(state.currentWorkflowId);
-  if (currentWorkflowState?.status === "running" || currentWorkflowState?.status === "pending")
+  if (scheduledRunOccupiesSlot(currentWorkflowState))
     return { state, currentWorkflowState };
   await internals.storage.delete(KEYS.scheduleRun(state.currentWorkflowId));
   return {
@@ -141,7 +145,7 @@ export async function startScheduledRun(_internals, state, callbacks) {
   return workflowId;
 }
 function hasActiveScheduledWorkflow(currentWorkflowState) {
-  return currentWorkflowState?.status === "running" || currentWorkflowState?.status === "pending";
+  return scheduledRunOccupiesSlot(currentWorkflowState);
 }
 async function applyBlockedScheduleOccurrence(state, hasActiveWorkflow, callbacks) {
   if (!hasActiveWorkflow)

package/dist/core/engine/second-instance-detector.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Best-effort, warn-only detection of a SECOND engine instance writing to the
+ * same durable store — a smoke alarm for singleton-deployment misconfiguration
+ * (an autoscaler accidentally set above one replica, or overlapping rolling
+ * deploys), NOT a correctness mechanism.
+ *
+ * **This is liveness, not fencing.** Weft's supported model is one engine process
+ * per durable store (see the recovery-and-deploys guide); fenced ownership is a
+ * future `MultiEngine` capability that does not exist yet. This detector never
+ * blocks boot, gates recovery, refuses a write, or claims ownership. It only
+ * observes whether another instance's heartbeat is *advancing while this instance
+ * is also running* and emits a warning if so. It does not prevent duplicate
+ * execution — infrastructure-level enforcement (`replicas: 1` + a `Recreate`
+ * deploy strategy, or a single systemd unit) is the real control.
+ *
+ * **Why liveness, not a boot check.** A boot-time check cannot distinguish a
+ * rolling-deploy handoff from a genuine second instance: both leave a recent
+ * heartbeat record in the store. Only observing a *foreign* heartbeat advance
+ * across several of our own ticks separates a live peer (autoscaling=2 → both
+ * heartbeats advance forever → both warn) from a dead-but-recent predecessor (a
+ * clean `Recreate` deploy → old heartbeat never advances after handoff → quiet).
+ *
+ * **Advance is measured by sequence, not wall clock.** Each heartbeat carries a
+ * per-instance monotonic `sequence`; a peer counts as advancing only when its
+ * `sequence` grows between two of *our* ticks. A peer's sequence cannot increase
+ * unless it is alive and ticking in our own time frame, so detection never
+ * compares clocks across hosts — it stays correct even if a peer's clock is
+ * frozen, skewed, or stepped backward. `heartbeatAt` exists only for the boot
+ * staleness sweep that garbage-collects long-dead instances' keys.
+ *
+ * Each engine writes its own heartbeat under `liveness:<instanceId>` and scans
+ * the `liveness:` prefix to observe peers. Per-instance keys (not one shared,
+ * clobbered key) keep every heartbeat independently observable and the sequence
+ * monotonic per writer.
+ *
+ * @module core/engine/second-instance-detector
+ */
+import { type Storage } from '../../storage/interface.ts';
+import type { EngineCleanupIntervalDisposalTracker } from './engine-leak-warnings.ts';
+/** Options for {@link createSecondInstanceDetector}. */
+export type SecondInstanceDetectorOptions = {
+    storage: Storage;
+    /** This engine's unique instance id. */
+    instanceId: string;
+    /** Wall-clock source (ms), injected so tests can advance time deterministically. */
+    getNow: () => number;
+    /**
+     * Heartbeat interval in ms. The staleness window is derived from this, so the
+     * interval also sets how long a deploy overlap must last before it warns.
+     */
+    intervalMs: number;
+    /**
+     * Emit a warning. Defaults to `process.emitWarning(message, WARNING_NAME)`,
+     * so the emitted `Warning.name` is `WeftSecondInstanceWarning` and consumers
+     * can filter on `warning.name` rather than scraping the message. Injected for
+     * tests; the seam is message-only because the name is a fixed constant.
+     */
+    warn?: (message: string) => void;
+};
+/**
+ * The `name` of the emitted warning. A stable, filterable identifier on the
+ * `Warning` object — consumers subscribe to the process `warning` event and
+ * match `warning.name === WARNING_NAME` (see the singleton-deployment guide).
+ */
+export declare const SECOND_INSTANCE_WARNING_NAME = "WeftSecondInstanceWarning";
+/**
+ * A running detector. `tick()` runs one heartbeat round (exposed for tests and
+ * driven by an interval in production); `stop()` clears the interval and
+ * best-effort removes this instance's heartbeat so the next boot starts quiet.
+ */
+export type SecondInstanceDetector = {
+    /** Run one heartbeat round: observe peers, then write our own heartbeat. */
+    tick(): Promise<void>;
+    /** Stop the interval and best-effort delete this instance's heartbeat key. */
+    stop(): Promise<void>;
+};
+/**
+ * Create a best-effort second-instance detector. Does not start an interval
+ * itself — the engine owns timer lifecycle so disposal can clear it through the
+ * same path as its other intervals. Call {@link SecondInstanceDetector.tick} on
+ * an interval and {@link SecondInstanceDetector.stop} on dispose.
+ */
+export declare function createSecondInstanceDetector(options: SecondInstanceDetectorOptions): SecondInstanceDetector;
+/**
+ * Build the `setInterval` callback that drives a detector tick. `resolveDetector`
+ * returns the live detector, or `null` when the engine has been garbage-collected
+ * or disposed. When it returns `null` the tick SELF-CLEARS its own interval (via
+ * `tracker.secondInstanceDetectionInterval`) and returns — mirroring
+ * {@link createCleanupIntervalTick}. This is the prompt cleanup path: a leaked
+ * engine's first post-GC tick clears the timer immediately, rather than relying
+ * on the `FinalizationRegistry` backstop, whose callbacks are not guaranteed to
+ * run promptly (or at all). Extracted so the skip/clear guard is directly
+ * testable without a timer. A tick failure is swallowed: the detector is a smoke
+ * alarm, never a correctness path, so it must not surface as an unhandled rejection.
+ */
+export declare function createSecondInstanceDetectionTick(resolveDetector: () => SecondInstanceDetector | null, tracker: EngineCleanupIntervalDisposalTracker): () => void;

package/dist/core/engine/second-instance-detector.js

@@ -0,0 +1,108 @@
+import { KEYS } from "../../storage/interface.js";
+const textEncoder = new TextEncoder, textDecoder = new TextDecoder;
+function encodeHeartbeat(heartbeat) {
+  return textEncoder.encode(JSON.stringify(heartbeat));
+}
+async function bestEffort(operation) {
+  try {
+    await operation();
+  } catch {}
+}
+function isUsableHeartbeat(candidate) {
+  const { instanceId, heartbeatAt, sequence } = candidate;
+  return typeof instanceId === "string" && instanceId.length > 0 && typeof heartbeatAt === "number" && Number.isFinite(heartbeatAt) && typeof sequence === "number" && Number.isInteger(sequence) && sequence >= 0;
+}
+function decodeHeartbeat(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(textDecoder.decode(raw));
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null)
+    return null;
+  const candidate = parsed;
+  return isUsableHeartbeat(candidate) ? candidate : null;
+}
+export const SECOND_INSTANCE_WARNING_NAME = "WeftSecondInstanceWarning";
+const STALE_SWEEP_WINDOW_MULTIPLE = 10, ADVANCE_TICKS_BEFORE_WARN = 2;
+export function createSecondInstanceDetector(options) {
+  const { storage, instanceId, getNow, intervalMs } = options, warn = options.warn ?? ((message) => process.emitWarning(message, SECOND_INSTANCE_WARNING_NAME)), stalenessWindowMs = intervalMs * (ADVANCE_TICKS_BEFORE_WARN + 1);
+  let sequence = 0, swept = !1, stopped = !1;
+  const observed = new Map, warnedInstanceIds = new Set;
+  async function readPeers() {
+    const peers = [];
+    for await (const [key, value] of storage.scan(KEYS.livenessPrefix())) {
+      const heartbeat = decodeHeartbeat(value);
+      if (heartbeat !== null && heartbeat.instanceId !== instanceId)
+        peers.push({ key, heartbeat });
+    }
+    return peers;
+  }
+  async function sweepStaleHeartbeats(peers, now) {
+    const staleBefore = now - stalenessWindowMs * STALE_SWEEP_WINDOW_MULTIPLE;
+    for (const peer of peers)
+      if (peer.heartbeat.heartbeatAt < staleBefore)
+        await bestEffort(() => storage.delete(peer.key));
+  }
+  function evaluatePeers(peers) {
+    const seenThisTick = new Set;
+    for (const { key, heartbeat } of peers) {
+      if (KEYS.liveness(heartbeat.instanceId) !== key)
+        continue;
+      seenThisTick.add(heartbeat.instanceId);
+      const previous = observed.get(heartbeat.instanceId), advances = previous !== void 0 && heartbeat.sequence > previous.sequence ? previous.advances + 1 : 0;
+      observed.set(heartbeat.instanceId, { sequence: heartbeat.sequence, advances });
+      if (advances >= ADVANCE_TICKS_BEFORE_WARN && !warnedInstanceIds.has(heartbeat.instanceId)) {
+        warnedInstanceIds.add(heartbeat.instanceId);
+        warn(`another engine instance (${heartbeat.instanceId}) is writing to this durable store. Weft supports one engine process per store; running two can cause duplicate workflow execution. Enforce a single instance at the infrastructure layer (for example, one replica with a Recreate deploy strategy).`);
+      }
+    }
+    for (const knownInstanceId of Array.from(observed.keys()))
+      if (!seenThisTick.has(knownInstanceId))
+        observed.delete(knownInstanceId);
+  }
+  let tickInFlight = !1;
+  async function tick() {
+    if (stopped || tickInFlight)
+      return;
+    tickInFlight = !0;
+    let wroteHeartbeat = !1;
+    try {
+      const now = getNow(), peers = await readPeers();
+      if (!swept) {
+        swept = !0;
+        await sweepStaleHeartbeats(peers, now);
+      }
+      evaluatePeers(peers);
+      if (stopped)
+        return;
+      sequence += 1;
+      const heartbeat = { instanceId, heartbeatAt: now, sequence };
+      wroteHeartbeat = !0;
+      await bestEffort(() => storage.put(KEYS.liveness(instanceId), encodeHeartbeat(heartbeat)));
+    } finally {
+      tickInFlight = !1;
+      if (wroteHeartbeat && stopped)
+        await bestEffort(() => storage.delete(KEYS.liveness(instanceId)));
+    }
+  }
+  async function stop() {
+    stopped = !0;
+    await bestEffort(() => storage.delete(KEYS.liveness(instanceId)));
+  }
+  return { tick, stop };
+}
+export function createSecondInstanceDetectionTick(resolveDetector, tracker) {
+  return function secondInstanceDetectionTick() {
+    const detector = resolveDetector();
+    if (detector === null) {
+      if (tracker.secondInstanceDetectionInterval !== null) {
+        clearInterval(tracker.secondInstanceDetectionInterval);
+        tracker.secondInstanceDetectionInterval = null;
+      }
+      return;
+    }
+    detector.tick().catch(() => {});
+  };
+}

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

@@ -1,3 +1,4 @@
+import type { BatchOperation } from '../../storage/interface.ts';
 import type { ComposedWorkflowInterceptor } from '../interceptor.ts';
 import type { SignalDeliveryOptions, WorkflowState } from '../types.ts';
 import type { EngineInternals } from './internals.ts';
@@ -31,6 +32,27 @@ export type ConsumedSignalResult = {
 export declare function signal(internals: EngineInternals, workflowId: string, name: string, payload: unknown, callbacks: SignalCallbacks, options?: SignalDeliveryOptions): Promise<void>;
 export declare function releaseSignalWaiter(internals: EngineInternals, workflowId: string, waiterKey: string, expectedResolve?: () => void): void;
 export declare function bufferSignalPayloads(internals: EngineInternals, workflowId: string, deliveries: BufferedSignalDelivery[], callbacks: SignalCallbacks, defaultOptions?: SignalDeliveryOptions): Promise<void>;
+/**
+ * Build the durable operations for a single keyed signal so it can be folded
+ * into a workflow's create batch by {@link startOrSignal}. Writes the same pair
+ * the live signal path writes — the `sig:` payload (consumed on first drive by
+ * `processWaitSignalOperation`) and the `sigres:` accepted-response marker — so a
+ * concurrent caller that falls back to the standard signal path dedups against
+ * the SAME `signalId`. The accepted-response marker is consumption-independent:
+ * even after the winning run consumes the `sig:` payload, a late loser finds the
+ * `sigres:` key and short-circuits instead of re-delivering, which is what
+ * guarantees "one signal per signalId" across the create and signal paths.
+ *
+ * Returns both the put operations and the CAS condition (the `sig:` key must be
+ * absent) so the caller can gate the create batch on it.
+ */
+export declare function buildCreateBatchSignalOperations(internals: EngineInternals, workflowId: string, signalName: string, payload: unknown, signalId: string): {
+    operations: BatchOperation[];
+    condition: {
+        key: string;
+        expectedValue: null;
+    };
+};
 export declare function hasBufferedSignal(internals: EngineInternals, workflowId: string, signalName: string): Promise<boolean>;
 export declare function consumeSignal(internals: EngineInternals, workflowId: string, signalName: string): Promise<ConsumedSignalResult>;
 /** Register a waiter key in a workflow-keyed reverse index. */

package/dist/core/engine/signals.js

@@ -83,6 +83,21 @@ function createExplicitSignalOperations(internals, workflowId, deliveries, signa
     value: encodePayloadWithinLimit(payload, internals.options.payloadSizePolicy.maxBytes, "signal payload")
   }));
 }
+export function buildCreateBatchSignalOperations(internals, workflowId, signalName, payload, signalId) {
+  validateSignalId(signalId);
+  const signalKey = KEYS.signal(workflowId, signalName, signalId), acceptedResponseKey = KEYS.signalAcceptedResponse(workflowId, signalName, signalId);
+  return {
+    operations: [
+      {
+        type: "put",
+        key: signalKey,
+        value: encodePayloadWithinLimit(payload, internals.options.payloadSizePolicy.maxBytes, "signal payload")
+      },
+      { type: "put", key: acceptedResponseKey, value: encode(SIGNAL_ACCEPTED_RESPONSE) }
+    ],
+    condition: { key: signalKey, expectedValue: null }
+  };
+}
 function appendTerminalCleanupOperation(internals, workflowId, operations) {
   if (internals.workflowsNeedingTerminalCleanup.has(workflowId))
     return;

package/dist/core/engine/termination/cleanup.d.ts

@@ -17,12 +17,37 @@ export type TerminationCallbacks = {
     cleanupReviews: (workflowId: string) => Promise<void>;
 };
 export declare const TERMINAL_WORKFLOW_STATUSES: ReadonlySet<WorkflowStatus>;
+/**
+ * Non-terminal statuses a workflow can be *forcibly* terminated from — cancel/
+ * timeout (`terminateWorkflow`) or system fail (`failWorkflow`). Both read this
+ * single constant so they cannot drift. `'suspended'` is included (a paused run
+ * must still be reachable by cancel/fail, else the CAS no-ops and the run is
+ * stranded); `completeWorkflow` deliberately excludes it (a suspended run's
+ * generator is evicted, so it can never reach normal completion).
+ */
+export declare const FORCIBLY_TERMINABLE_STATUSES: readonly ["running", "pending", "suspended"];
 /**
  * Remove any pending signal, update, and sleep waiters for a workflow. This
  * prevents memory leaks and ensures that cancelled/completed/failed workflows
  * cannot accept new signals, updates, or resolve orphaned sleep timers.
  */
 export declare function cleanupWaiters(internals: EngineInternals, workflowId: string, callbacks: Pick<TerminationCallbacks, 'swallowPromiseRejection'>): void;
+/**
+ * Evict only the in-flight OPERATION waiters for a workflow that is being
+ * suspended (signal/update/review waiters, review escalations, and sleep
+ * resolvers), WITHOUT resolving them and WITHOUT touching the non-serialized
+ * `services`, headers, type, or nesting-depth bookkeeping.
+ *
+ * Suspend parks the inline run (evicting its context/generator), so a signal or
+ * update arriving afterwards must NOT wake the dormant operation loop and drive
+ * the gone generator — it should buffer durably and be replayed when the
+ * workflow resumes. Deleting (not resolving) each waiter leaves the loop dormant
+ * and severs that wake path; the durable signal/sleep state in storage is
+ * untouched, so resume replays it. This is the suspend-specific complement to
+ * {@link cleanupWaiters}, which is for terminal transitions and additionally
+ * drops `services` and resolves sleep resolvers — both wrong for a pause.
+ */
+export declare function evictSuspendedWorkflowWaiters(internals: EngineInternals, workflowId: string, callbacks: Pick<TerminationCallbacks, 'swallowPromiseRejection'>): void;
 /**
  * Remove durable records keyed by `workflowId` that otherwise leak after a
  * workflow reaches a terminal state.

package/dist/core/engine/termination/cleanup.js

@@ -8,7 +8,11 @@ export const TERMINAL_WORKFLOW_STATUSES = new Set([
   "failed",
   "cancelled",
   "timed-out"
-]);
+]), FORCIBLY_TERMINABLE_STATUSES = [
+  "running",
+  "pending",
+  "suspended"
+];
 function selectTrackedWaiterMaps(internals, kind) {
   return {
     signal: () => ({
@@ -48,6 +52,14 @@ function cleanupSleepResolvers(internals, workflowId) {
   }
   internals.sleepResolversByWorkflow.delete(workflowId);
 }
+function evictSleepResolversWithoutResolving(internals, workflowId) {
+  const sleepOps = internals.sleepResolversByWorkflow.get(workflowId);
+  if (!sleepOps)
+    return;
+  for (const operationId of sleepOps)
+    internals.sleepResolvers.delete(`${workflowId}:${operationId}`);
+  internals.sleepResolversByWorkflow.delete(workflowId);
+}
 function cleanupReviewEscalations(internals, workflowId, callbacks) {
   const reviewIds = internals.workflowReviewIds.get(workflowId);
   if (!reviewIds)
@@ -71,8 +83,15 @@ export function cleanupWaiters(internals, workflowId, callbacks) {
   cleanupReviewEscalations(internals, workflowId, callbacks);
   internals.workflowNestingDepths.delete(workflowId);
   internals.workflowHeaders.delete(workflowId);
+  internals.workflowServices.delete(workflowId);
   internals.workflowTypeByWorkflowId.delete(workflowId);
 }
+export function evictSuspendedWorkflowWaiters(internals, workflowId, callbacks) {
+  for (const kind of TRACKED_WAITER_KINDS)
+    cleanupTrackedWaiter(internals, workflowId, kind);
+  evictSleepResolversWithoutResolving(internals, workflowId);
+  cleanupReviewEscalations(internals, workflowId, callbacks);
+}
 export async function cleanupWorkflowStorage(internals, workflowId, includeOutputArtifacts) {
   const encodedWorkflowId = encodeStorageKeyComponent(workflowId), prefixes = [
     KEYS.activityReconciliationPrefix(workflowId),
@@ -86,6 +105,7 @@ export async function cleanupWorkflowStorage(internals, workflowId, includeOutpu
     prefixes.push(`offload:${encodedWorkflowId}:`, `blob:${encodedWorkflowId}:`);
   await internals.storage.delete(KEYS.workflowHeaders(workflowId));
   await internals.storage.delete(KEYS.signalSequence(workflowId));
+  await internals.storage.delete(KEYS.workflowHasServices(workflowId));
   if (internals.storage.deletePrefix) {
     for (const prefix of prefixes)
       await internals.storage.deletePrefix(prefix);

package/dist/core/engine/termination/complete.js

@@ -26,7 +26,8 @@ import { buildWorkflowVisibilityIndexTransition } from "../workflow-indexes.js";
 import {
   cleanupTerminalWorkflowImmediately,
   cleanupTerminalWorkflowSynchronously,
-  finalizeScheduledWorkflowTerminal
+  finalizeScheduledWorkflowTerminal,
+  FORCIBLY_TERMINABLE_STATUSES
 } from "./cleanup.js";
 async function runCancelHandlers(handlers, callbacks, workflowId) {
   for (const handler of handlers)
@@ -54,7 +55,7 @@ export async function terminateWorkflow(internals, workflowId, status, callbacks
   internals.strategy.cancelWorkflow(workflowId);
   try {
     const attributeBytes = await internals.storage.get(KEYS.attribute(workflowId)), attributes = attributeBytes ? decode(attributeBytes) : {}, retainedAttributes = buildRetainedTerminalSearchAttributes(attributes), terminationMessage = status === "timed-out" ? "Workflow timed out" : "Workflow cancelled", terminationResult = await updateWorkflowState(internals, workflowId, { status, ...reason !== void 0 ? { terminationReason: reason } : {} }, {
-      allowedStatuses: ["running", "pending"],
+      allowedStatuses: FORCIBLY_TERMINABLE_STATUSES,
       buildAdditionalOperations: (_previousState, updatedAt) => {
         finalizePendingTimelineEntry(internals, workflowId, status, terminationMessage, updatedAt);
         const pendingTimelineOperation = buildPendingTimelineOperation(internals, workflowId);
@@ -182,7 +183,7 @@ export async function failWorkflow(internals, workflowId, error, callbacks, fail
   if (error.stack !== void 0)
     stateUpdate.errorStack = error.stack;
   if (!await updateWorkflowState(internals, workflowId, stateUpdate, {
-    allowedStatuses: ["running", "pending"],
+    allowedStatuses: FORCIBLY_TERMINABLE_STATUSES,
     buildAdditionalOperations: (_previousState, updatedAt) => {
       finalizePendingTimelineEntry(internals, workflowId, "failed", error.message, updatedAt);
       const pendingTimelineOperation = buildPendingTimelineOperation(internals, workflowId);

package/dist/core/engine/termination/suspend.d.ts

@@ -0,0 +1,68 @@
+import type { EngineInternals } from '../internals.ts';
+import { type TerminationCallbacks } from './cleanup.ts';
+/**
+ * Suspend a running workflow without terminating it: a non-terminal cousin of
+ * {@link terminateWorkflow}. The workflow's status transitions `running →
+ * suspended`, its durable checkpoint is preserved, and it becomes resumable via
+ * `engine.resume(id)` / `handle.resume()`. Suspension is client-driven
+ * preemption, so — unlike a fault — a suspended workflow is NOT auto-recovered
+ * by `engine.recoverAll()`.
+ *
+ * Contrast with cancel/timeout, which this deliberately does NOT do:
+ * - does NOT abort the workflow's `AbortController` — suspend is a pause, not a
+ *   cancellation, so user code observing `ctx.signal.aborted` or registered
+ *   abort listeners must not fire. The live inline run is *parked*
+ *   (`parkWorkflow`: evict execution state without aborting), the same primitive
+ *   the engine uses for signal-parking,
+ * - does NOT run cancel handlers,
+ * - does NOT settle the result promise (`handle.result()` stays pending until a
+ *   later `resume()` drives the run to completion, or a `cancel()` terminates it),
+ * - does NOT clean up durable output artifacts or in-memory services (the
+ *   `services` value is preserved so an in-process `resume()` can reuse it),
+ * - does NOT schedule terminal cleanup.
+ *
+ * The CAS status flip and the in-memory teardown both run inside one serialized
+ * per-workflow write section with `allowedStatuses: ['running']`. If the
+ * workflow already left `running` (it completed, failed, or a concurrent cancel
+ * won the race), the flip is skipped and suspend is a no-op — and because the
+ * teardown is gated on the flip succeeding, a workflow that lost the race keeps
+ * its execution state intact.
+ *
+ * The teardown evicts every piece of in-memory execution state that could let a
+ * post-suspend operation drive the parked run: the inline context/generator (via
+ * `parkWorkflow`), the in-memory checkpoint, the parked-inline marker, and the
+ * in-flight operation waiters (signal/update/sleep/review — deleted, NOT
+ * resolved, so a signal arriving after suspend buffers durably and is replayed
+ * on resume instead of waking a dormant operation loop against the gone
+ * generator). The durable checkpoint, durable buffered signals, durable sleep
+ * timers, and `workflowServices` are all left intact for resume.
+ *
+ * A signal that races the in-lock teardown is benign: `continueWorkflow` no-ops
+ * for an evicted generator, and `persistCheckpoint` no-ops when the context and
+ * in-memory checkpoint are gone — so no step can commit past the suspend point.
+ *
+ * `'suspended'` is neither `'running'` nor `'pending'`, and both local-ownership
+ * predicates (`isInlineWorkflowLocallyOwned`, `hasLocalCheckpointOwnership`) are
+ * gated on those two statuses. So once the status flips, the workflow stops
+ * registering as locally owned — which is exactly what makes `recoverAll()` skip
+ * it AND what lets `engine.resume()` re-drive it from storage instead of taking
+ * its local-ownership early return.
+ *
+ * The execution deadline is absolute wall-clock time: suspension does NOT extend
+ * it. The pending `deadline:` timer is deleted durably IN THE SAME COMMIT BATCH
+ * as the status flip, and re-armed at the same absolute fire time on resume (or
+ * fires immediately if already past). It is a durable delete rather than a
+ * `scheduler.cancel()` call because the scheduler is durable-scan-based and
+ * resume's re-arm is likewise durable-only (`buildTimerBatchOperations`); folding
+ * the delete into the commit makes it atomic with the flip and ordered before any
+ * concurrent resume, so an immediate resume cannot have its freshly re-armed
+ * deadline deleted by a late fire-and-forget cancel.
+ *
+ * Worker execution mode is not supported: a worker run cannot be parked without
+ * sending it a cancellation. To keep the contract state-dependent (suspend on a
+ * non-running workflow is always a no-op), the mode check runs only AFTER the
+ * status load confirms the workflow is `running`; a `running` worker workflow
+ * throws {@link WorkflowSuspendNotSupportedError}, while a completed or unknown
+ * one is a no-op regardless of execution mode.
+ */
+export declare function suspendWorkflow(internals: EngineInternals, workflowId: string, callbacks: TerminationCallbacks): Promise<void>;

package/dist/core/engine/termination/suspend.js

@@ -0,0 +1,41 @@
+import { KEYS } from "../../../storage/interface.js";
+import { encode } from "../../codec.js";
+import { WorkflowSuspendedEvent } from "../../events.js";
+import { WorkflowSuspendNotSupportedError } from "../errors.js";
+import { dropQueuedInlineWorkflowStart } from "../inline-launch-queue.js";
+import { buildWorkflowVisibilityIndexTransition } from "../workflow-indexes.js";
+import { evictSuspendedWorkflowWaiters } from "./cleanup.js";
+export async function suspendWorkflow(internals, workflowId, callbacks) {
+  if (!await callbacks.runSerializedWorkflowStateWrite(workflowId, async () => {
+    const state = await callbacks.loadWorkflowState(workflowId);
+    if (!state || state.status !== "running")
+      return !1;
+    if (internals.inlineStrategy === null)
+      throw new WorkflowSuspendNotSupportedError("suspend is only supported in inline execution mode; a worker run cannot be paused without cancelling it.");
+    internals.inlineStrategy.parkWorkflow(workflowId);
+    dropQueuedInlineWorkflowStart(internals, workflowId);
+    internals.checkpoints.delete(workflowId);
+    internals.parkedInlineWorkflows.delete(workflowId);
+    evictSuspendedWorkflowWaiters(internals, workflowId, callbacks);
+    const updatedAt = internals.options.getNow(), updatedState = { ...state, status: "suspended", updatedAt };
+    await callbacks.commitWorkflowStateOperations(state, [
+      { type: "put", key: KEYS.workflow(workflowId), value: encode(updatedState) },
+      ...buildWorkflowVisibilityIndexTransition(workflowId, state, updatedState).batchOps,
+      ...buildDeadlineTimerDeleteOperations(workflowId, state.executionDeadline)
+    ]);
+    return !0;
+  }))
+    return;
+  const event = new WorkflowSuspendedEvent(workflowId);
+  callbacks.dispatchEvent(event);
+  callbacks.forwardEventToHandle(workflowId, event);
+}
+function buildDeadlineTimerDeleteOperations(workflowId, executionDeadline) {
+  if (executionDeadline === void 0)
+    return [];
+  const timerId = `deadline:${workflowId}`;
+  return [
+    { type: "delete", key: KEYS.deadline(executionDeadline, timerId) },
+    { type: "delete", key: `timer-idx:${timerId}` }
+  ];
+}

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

@@ -1,7 +1,9 @@
 /**
  * Thin barrel over the split termination modules. Keeps existing import paths
  * (`./termination.ts`) working while the implementation lives in
- * `./termination/cleanup.ts` and `./termination/complete.ts`.
+ * `./termination/cleanup.ts`, `./termination/complete.ts`, and
+ * `./termination/suspend.ts`.
  */
-export { TERMINAL_WORKFLOW_STATUSES, cleanupTerminalWorkflowDurableState, cleanupTerminalWorkflowImmediately, cleanupTerminalWorkflowMemory, cleanupTerminalWorkflowSynchronously, cleanupWaiters, cleanupWorkflowStorage, finalizeScheduledWorkflowTerminal, handleCleanupError, runDeferredTerminalCleanup, type TerminationCallbacks, } from './termination/cleanup.ts';
+export { TERMINAL_WORKFLOW_STATUSES, cleanupTerminalWorkflowDurableState, cleanupTerminalWorkflowImmediately, cleanupTerminalWorkflowMemory, cleanupTerminalWorkflowSynchronously, cleanupWaiters, cleanupWorkflowStorage, evictSuspendedWorkflowWaiters, finalizeScheduledWorkflowTerminal, handleCleanupError, runDeferredTerminalCleanup, type TerminationCallbacks, } from './termination/cleanup.ts';
 export { buildPendingTimelineOperation, buildTerminalCleanupTimerOperations, cancelWorkflow, completeWorkflow, ensureTerminalCleanupTracked, failWorkflow, finalizePendingTimelineEntry, terminateWorkflow, timeoutWorkflow, } from './termination/complete.ts';
+export { suspendWorkflow } from './termination/suspend.ts';