@lostgradient/weft 0.2.1 → 0.3.0

package/dist/core/engine/lifecycle/start.js

@@ -1,6 +1,5 @@
 import { KEYS } from "../../../storage/interface.js";
 import { createCheckpoint } from "../../checkpoint.js";
-import { WorkflowStartedEvent } from "../../events.js";
 import { assertPayloadWithinLimit } from "../../payload-size.js";
 import { normalizeStorageTimestamp } from "../../scheduler.js";
 import {
@@ -20,8 +19,12 @@ import {
   normalizeStartWorkflowTags,
   setWorkflowStartHeaders
 } from "./shared.js";
-import { buildStartBatchOperations } from "./start-batch.js";
-import { runWorkflowStartInterceptor, startWorkflowExecution } from "./start-exec.js";
+import { buildAndCommitStartBatch } from "./start-commit.js";
+import {
+  assertDeferSupported,
+  beginExecutionAwaitingLiveness,
+  runWorkflowStartInterceptor
+} from "./start-exec.js";
 export async function start(internals, type, input, options, callbacks) {
   return startWorkflow(internals, type, input, options, void 0, callbacks);
 }
@@ -43,9 +46,6 @@ function prepareStartWorkflow(internals, options, callbacks) {
     normalizedTags
   };
 }
-async function persistStartBatch(internals, startOperations) {
-  await internals.storage.batch(startOperations);
-}
 function rollbackTransientStartState(internals, workflowId) {
   forgetCommittedCheckpointBytes(internals, workflowId);
   internals.checkpoints.delete(workflowId);
@@ -58,12 +58,13 @@ function assertServicesSupportedForMode(internals, options) {
   if (options?.services !== void 0 && internals.inlineStrategy === null)
     throw Error('options.services is only supported in inline execution mode; it cannot be serialized to a Worker. Remove services or use workflowExecutionMode: "inline".');
 }
-export async function startWorkflow(internals, type, input, options, additionalStartOperations, callbacks) {
+export async function startWorkflow(internals, type, input, options, additionalStartOperations, callbacks, buildIdempotentStartOperations) {
   const registration = internals.registrations.get(type);
   if (!registration)
     throw new WorkflowNotRegisteredError(type);
   assertServicesSupportedForMode(internals, options);
   const preparation = prepareStartWorkflow(internals, options, callbacks), { workflowId, callerProvidedId, parentHeaders, executionStateOwnerId, delayedStartTimer } = preparation;
+  assertDeferSupported(internals, options, Boolean(delayedStartTimer));
   if (internals.pendingStarts.has(workflowId))
     throw new WorkflowAlreadyExistsError(workflowId);
   internals.pendingStarts.add(workflowId);
@@ -78,15 +79,32 @@ export async function startWorkflow(internals, type, input, options, additionalS
     internals.checkpoints.set(workflowId, checkpoint);
     setWorkflowStartHeaders(internals, workflowId, workflowStartHeaders, callbacks);
     internals.workflowVersionTuples.set(workflowId, versionTuple);
-    const startOperations = buildStartBatchOperations(internals, workflowId, state, checkpoint, registration, options, state.executionDeadline, delayedStartTimer, persistedWorkflowStartHeaders, additionalStartOperations, callbacks);
-    await persistStartBatch(internals, startOperations);
+    await buildAndCommitStartBatch({
+      internals,
+      workflowId,
+      state,
+      checkpoint,
+      registration,
+      options,
+      delayedStartTimer,
+      persistedWorkflowStartHeaders,
+      additionalStartOperations,
+      callbacks
+    }, buildIdempotentStartOperations);
     if (options?.services !== void 0) {
       internals.workflowServices.set(workflowId, options.services);
       internals.workflowsNeedingTerminalCleanup.add(workflowId);
     }
     const handle = createWorkflowHandle(internals, workflowId, callbacks);
-    if (!delayedStartTimer)
-      beginWorkflowExecution(internals, workflowId, type, input, checkpoint, state.executionDeadline, state.executionStateOwnerId ?? workflowId, registration, callbacks);
+    await beginExecutionAwaitingLiveness(internals, {
+      type,
+      input,
+      checkpoint,
+      state,
+      registration,
+      options,
+      isDelayed: Boolean(delayedStartTimer)
+    }, workflowId, callbacks);
     startSucceeded = !0;
     return handle;
   } finally {
@@ -112,42 +130,18 @@ export function resolveScheduledStartAt(internals, options, submissionTime, call
 export function parseStartOptionDuration(_internals, duration, fieldName, _callbacks) {
   return parseStartWorkflowDuration(duration, fieldName);
 }
-export function beginWorkflowExecution(internals, workflowId, workflowType, input, checkpoint, executionDeadline, executionStateOwnerId, _registration, callbacks) {
-  const nestingDepth = internals.pendingNestingDepth ?? 0;
-  internals.pendingNestingDepth = void 0;
-  if (internals.inlineStrategy !== null) {
-    callbacks.queueInlineWorkflowExecutionStart({
-      workflowId,
-      workflowType,
-      input,
-      checkpoint,
-      nestingDepth,
-      executionDeadline,
-      executionStateOwnerId
-    });
-    return;
-  }
-  callbacks.dispatchEvent(new WorkflowStartedEvent(workflowId, workflowType, input));
-  startWorkflowExecution(internals, workflowId, workflowType, input, checkpoint, nestingDepth, executionDeadline, executionStateOwnerId, callbacks);
-}
 function buildInitialIdentitySlice(workflowId, type, input, versionTuple, executionStateOwnerId, delayedStartTimer, now, tags) {
   return {
     id: workflowId,
     type,
     status: delayedStartTimer ? "pending" : "running",
     input,
-    version: versionTuple.workflowVersion,
+    versionTuple,
     executionStateOwnerId,
     createdAt: now,
     ...!delayedStartTimer && { startedAt: now },
     updatedAt: now,
-    ...tags !== void 0 && { tags },
-    ...versionTuple.agentVersion !== void 0 && {
-      agentVersion: versionTuple.agentVersion
-    },
-    ...versionTuple.toolVersions !== void 0 && {
-      toolVersions: versionTuple.toolVersions
-    }
+    ...tags !== void 0 && { tags }
   };
 }
 function resolveInitialExecutionDeadline(internals, options, delayedStartTimer, now, callbacks) {

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

@@ -1,8 +1,9 @@
 export { EMPTY_STORAGE_VALUE, createWorkflowHandle, loadTerminalCleanupTrackedState, loadWorkflowStartHeaders, normalizeStartWorkflowTags, processPendingUpdatesAfterReplay, setWorkflowStartHeaders, type LifecycleCallbacks, type RecoverAllOptions, } from './lifecycle/shared.ts';
 export { createWorkflowVersionTuple, derivePreparedExecutionState, prepareResumeState, throwVersionMismatch, workflowStateWithVersionTuple, workflowVersionTupleFromState, } from './lifecycle/persist.ts';
-export { beginWorkflowExecution, createInitialCheckpoint, createInitialWorkflowState, parseStartOptionDuration, resolveScheduledStartAt, start, startWorkflow, } from './lifecycle/start.ts';
+export { createInitialCheckpoint, createInitialWorkflowState, parseStartOptionDuration, resolveScheduledStartAt, start, startWorkflow, } from './lifecycle/start.ts';
+export { startOrSignal, startWithIdempotency, type StartOrSignalCallbacks, } from './lifecycle/start-or-signal.ts';
 export { buildInitialSearchAttributeOperations, buildStartBatchOperations, validateSearchAttributes, } from './lifecycle/start-batch.ts';
-export { runWorkflowStartInterceptor, startWorkflowExecution } from './lifecycle/start-exec.ts';
+export { beginWorkflowExecution, runWorkflowStartInterceptor, startWorkflowExecution, } from './lifecycle/start-exec.ts';
 export { buildForkBatchOperations, buildForkSearchAttributes, createForkLineage, createForkedWorkflowState, } from './lifecycle/fork-helpers.ts';
 export { fork, launchWorkflowFromCheckpoint, recoverAll, resume } from './lifecycle/transition.ts';
 export { resumeWorkflowFromStorage } from './lifecycle/resume.ts';

package/dist/core/engine/lifecycle.js

@@ -16,7 +16,6 @@ export {
   workflowVersionTupleFromState
 } from "./lifecycle/persist.js";
 export {
-  beginWorkflowExecution,
   createInitialCheckpoint,
   createInitialWorkflowState,
   parseStartOptionDuration,
@@ -24,12 +23,20 @@ export {
   start,
   startWorkflow
 } from "./lifecycle/start.js";
+export {
+  startOrSignal,
+  startWithIdempotency
+} from "./lifecycle/start-or-signal.js";
 export {
   buildInitialSearchAttributeOperations,
   buildStartBatchOperations,
   validateSearchAttributes
 } from "./lifecycle/start-batch.js";
-export { runWorkflowStartInterceptor, startWorkflowExecution } from "./lifecycle/start-exec.js";
+export {
+  beginWorkflowExecution,
+  runWorkflowStartInterceptor,
+  startWorkflowExecution
+} from "./lifecycle/start-exec.js";
 export {
   buildForkBatchOperations,
   buildForkSearchAttributes,

package/dist/core/engine/listing.js

@@ -88,7 +88,7 @@ function summaryFromState(state, attributeFailureCategory) {
     type: state.type,
     status: state.status,
     ...state.tags !== void 0 && { tags: state.tags },
-    version: state.version,
+    version: state.versionTuple.workflowVersion,
     createdAt: state.createdAt,
     updatedAt: state.updatedAt,
     ...state.executionDeadline !== void 0 && { executionDeadline: state.executionDeadline },

package/dist/core/engine/persisted-data-version.d.ts

@@ -12,13 +12,9 @@ import type { Storage as WeftStorage } from '../../storage/interface.ts';
  * 3. Sentinel is absent. Only stamp the storage when it carries no user
  *    workflow data. Stamping a database that already holds workflow records,
  *    schedules, checkpoints, or any other `wf:` / `op:` / `schedule:` / `ev:`
- *    prefixed key would silently classify pre-versioned data (written by an
- *    older Weft binary or by the `new Engine({ storage })` constructor path
- *    before the sentinel was introduced) as schema-current and risk replaying
- *    incompatible records. When user data is already present without a
- *    sentinel, fail with `PersistedDataIncompatibleError(null, …)` so the
- *    operator can choose explicitly whether to wipe and start fresh.
+ *    prefixed key would silently classify unversioned data as schema-current
+ *    and risk replaying incompatible records. When user data is already present
+ *    without a sentinel, fail with `PersistedDataIncompatibleError(null, …)` so
+ *    the operator can choose explicitly whether to wipe and start fresh.
  */
-export declare function assertCompatiblePersistedDataVersion(storage: WeftStorage, options?: {
-    allowLegacyData?: boolean;
-}): Promise<void>;
+export declare function assertCompatiblePersistedDataVersion(storage: WeftStorage): Promise<void>;

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.