@lostgradient/weft 0.2.1 → 0.4.0

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

@@ -0,0 +1,38 @@
+import { KEYS } from "../../storage/interface.js";
+import { encode } from "../codec.js";
+import { ScheduleFiredEvent } from "../events.js";
+import { unavailableServicesError } from "./lifecycle/recovered-services.js";
+import { EMPTY_STORAGE_VALUE } from "./lifecycle/shared.js";
+export async function startScheduledRun(internals, state, callbacks, occurrence) {
+  const workflowId = crypto.randomUUID(), scheduleRunOperations = state.overlap === "allow" ? [] : [{ type: "put", key: KEYS.scheduleRun(workflowId), value: encode(state.id) }], resolution = await resolveScheduledRunServices(internals, workflowId, state);
+  if (resolution !== null) {
+    scheduleRunOperations.push({ type: "put", key: KEYS.workflowHasServices(workflowId), value: EMPTY_STORAGE_VALUE }, { type: "put", key: KEYS.terminalCleanupNeeded(workflowId), value: EMPTY_STORAGE_VALUE });
+    internals.workflowsNeedingTerminalCleanup.add(workflowId);
+    if (resolution.status === "available")
+      internals.workflowServices.set(workflowId, resolution.services);
+  }
+  await callbacks.startWorkflow(state.workflowType, state.input, { id: workflowId }, scheduleRunOperations);
+  internals.engine.dispatchEvent(new ScheduleFiredEvent(state.id, workflowId, internals.options.getNow(), occurrence));
+  if (resolution !== null && resolution.status === "unavailable") {
+    const unavailableError = unavailableServicesError(workflowId, resolution.reason);
+    try {
+      await callbacks.failWorkflow(workflowId, unavailableError);
+    } catch (error) {
+      callbacks.handleCleanupError("startScheduledRun", error, workflowId);
+    }
+  }
+  return workflowId;
+}
+async function resolveScheduledRunServices(internals, workflowId, state) {
+  const resolver = internals.options.resolveWorkflowServices;
+  if (internals.inlineStrategy === null || !resolver)
+    return null;
+  try {
+    return await resolver({ workflowId, workflowType: state.workflowType, input: state.input });
+  } catch (error) {
+    return {
+      status: "unavailable",
+      reason: error instanceof Error ? error.message : String(error)
+    };
+  }
+}

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

@@ -1,6 +1,16 @@
+import { ScheduleMissedFireEvent } from "../events/schedule-events.js";
+import { resolveEffectiveScheduleFireAt } from "./schedule-jitter.js";
 import { collectDueScheduleOccurrences, getNextScheduleOccurrence } from "./schedule-occurrence.js";
 import { loadScheduleState, writeScheduleState } from "./storage-io.js";
-const SCHEDULE_LATE_GRACE_MILLISECONDS = 1000, MAX_SCHEDULE_BACKFILL_OCCURRENCES_PER_TICK = 256;
+const SCHEDULE_LATE_GRACE_MILLISECONDS = 1000, MAX_SCHEDULE_BACKFILL_OCCURRENCES_PER_TICK = 256, MAX_MISSED_FIRE_COUNT_PER_TICK = MAX_SCHEDULE_BACKFILL_OCCURRENCES_PER_TICK;
+
+class ScheduleStatePersistenceError extends Error {
+  scheduleId;
+  constructor(scheduleId, cause) {
+    super(`Failed to persist schedule "${scheduleId}" while processing its timer`, { cause });
+    this.scheduleId = scheduleId;
+  }
+}
 export async function handleScheduleTimer(internals, entry, callbacks) {
   const state = await loadScheduleState(internals, entry.workflowId);
   if (!isCurrentActiveScheduleTimer(state, entry))
@@ -10,28 +20,43 @@ export async function handleScheduleTimer(internals, entry, callbacks) {
     const now = internals.options.getNow(), work = planScheduleTimerWork(state, entry, now);
     if (!work)
       return;
-    nextState = await processScheduleTimerOccurrences(internals, state, work.occurrencesToProcess, now, callbacks, (processedState) => {
-      nextState = processedState;
-    });
-    await writeScheduleState(internals, {
-      ...nextState,
-      updatedAt: now,
-      nextFireAt: resolveNextScheduleFireAt(nextState, work, now)
+    if (work.occurrencesToProcess.length === 0) {
+      nextState = {
+        ...nextState,
+        updatedAt: now,
+        nextFireAt: resolveNextScheduleFireAt(nextState, work, now),
+        ...work.missedOccurrences && {
+          lastMissedFireAt: work.missedOccurrences.lastMissedFireAt,
+          missedFireCount: nextState.missedFireCount + work.missedOccurrences.count
+        }
+      };
+      await persistScheduleTimerState(internals, nextState);
+      if (work.missedOccurrences)
+        internals.engine.dispatchEvent(new ScheduleMissedFireEvent(nextState.id, work.missedOccurrences.count, work.missedOccurrences.windowStart, work.missedOccurrences.windowEnd));
+      return;
+    }
+    nextState = await processScheduleTimerOccurrences(internals, state, work, now, callbacks, {
+      onProcessedState: (processedState) => {
+        nextState = processedState;
+      }
     });
   } catch (error) {
+    if (error instanceof ScheduleStatePersistenceError)
+      throw error;
     await pauseScheduleAfterTimerFailure(internals, nextState, error);
   }
 }
 function isCurrentActiveScheduleTimer(state, entry) {
-  return state?.status === "active" && state.nextFireAt === entry.fireAt;
+  return state?.status === "active" && state.nextFireAt !== null && resolveEffectiveScheduleFireAt(state, state.nextFireAt) === entry.fireAt;
 }
 function planScheduleTimerWork(state, entry, now) {
   const dueOccurrences = collectDueScheduleOccurrences(state, state.nextFireAt, Math.max(now, entry.fireAt), state.backfill ? MAX_SCHEDULE_BACKFILL_OCCURRENCES_PER_TICK : 2);
   if (dueOccurrences.length === 0)
     return null;
-  if (!state.backfill && now - state.nextFireAt > SCHEDULE_LATE_GRACE_MILLISECONDS)
+  if (!state.backfill && now - entry.fireAt > SCHEDULE_LATE_GRACE_MILLISECONDS)
     return {
       dueOccurrences,
+      missedOccurrences: countMissedScheduleOccurrences(state, state.nextFireAt, now),
       occurrencesToProcess: [],
       skipMissedOccurrences: !0
     };
@@ -42,29 +67,68 @@ function planScheduleTimerWork(state, entry, now) {
     skipMissedOccurrences: !1
   };
 }
+function countMissedScheduleOccurrences(state, firstDueAt, throughTimestamp) {
+  let count = 0, occurrence = firstDueAt, lastMissedFireAt = firstDueAt;
+  while (occurrence <= throughTimestamp && count < MAX_MISSED_FIRE_COUNT_PER_TICK) {
+    count += 1;
+    lastMissedFireAt = occurrence;
+    const nextOccurrence = getNextScheduleOccurrence(state, occurrence);
+    if (nextOccurrence <= occurrence)
+      throw Error(`Schedule "${state.id}" produced a non-advancing occurrence`);
+    occurrence = nextOccurrence;
+  }
+  const cappedBeforeThroughTimestamp = occurrence <= throughTimestamp;
+  return {
+    count,
+    lastMissedFireAt,
+    windowStart: firstDueAt,
+    windowEnd: cappedBeforeThroughTimestamp ? lastMissedFireAt : throughTimestamp
+  };
+}
 function resolveNextScheduleFireAt(state, work, now) {
   if (work.skipMissedOccurrences)
-    return getNextScheduleOccurrence(state, now);
+    return getNextScheduleOccurrence(state, work.missedOccurrences?.lastMissedFireAt ?? now);
   const anchorOccurrence = work.occurrencesToProcess.at(-1) ?? work.dueOccurrences.at(-1);
   return getNextScheduleOccurrence(state, anchorOccurrence);
 }
-async function processScheduleTimerOccurrences(internals, state, occurrencesToProcess, now, callbacks, onProcessedState) {
+async function processScheduleTimerOccurrences(internals, state, work, now, callbacks, options) {
   let nextState = state;
-  for (const occurrence of occurrencesToProcess) {
+  for (const [index, occurrence] of work.occurrencesToProcess.entries()) {
+    const finalOccurrence = index === work.occurrencesToProcess.length - 1;
     nextState = {
-      ...await callbacks.applyScheduleOccurrence(nextState),
+      ...await callbacks.applyScheduleOccurrence(nextState, occurrence),
       lastFireAt: occurrence,
       updatedAt: now
     };
-    onProcessedState(nextState);
-    await writeScheduleState(internals, nextState, { includeTimer: !1 });
+    if (finalOccurrence)
+      nextState = {
+        ...nextState,
+        nextFireAt: resolveNextScheduleFireAt(nextState, work, now)
+      };
+    options.onProcessedState(nextState);
+    await persistScheduleTimerState(internals, nextState, { includeTimer: finalOccurrence });
     if (state.backfill && nextState.currentWorkflowId !== void 0) {
       nextState = await callbacks.settleBackfillScheduleState(nextState);
-      onProcessedState(nextState);
+      if (finalOccurrence) {
+        nextState = {
+          ...nextState,
+          updatedAt: now,
+          nextFireAt: resolveNextScheduleFireAt(nextState, work, now)
+        };
+        await persistScheduleTimerState(internals, nextState);
+      }
+      options.onProcessedState(nextState);
     }
   }
   return nextState;
 }
+async function persistScheduleTimerState(internals, state, options) {
+  try {
+    await writeScheduleState(internals, state, options);
+  } catch (error) {
+    throw new ScheduleStatePersistenceError(state.id, error);
+  }
+}
 async function pauseScheduleAfterTimerFailure(internals, state, error) {
   const errorNow = internals.options.getNow(), pausedState = {
     ...state,

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

@@ -1,7 +1,8 @@
 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 { startScheduledRun } from './schedule-run.ts';
 export { handleScheduleTimer } from './schedule-timer.ts';
 export type RefreshedScheduleState = {
     state: ScheduleState;
@@ -15,20 +16,22 @@ export type ScheduleCallbacks = {
     cancelWorkflow: (workflowId: string) => Promise<void>;
     getWorkflowResult: (workflowId: string) => Promise<unknown>;
     refreshScheduledWorkflowState: (state: ScheduleState) => Promise<RefreshedScheduleState>;
-    startScheduledRun: (state: ScheduleState) => Promise<string>;
-    applyScheduleOccurrence: (state: ScheduleState) => Promise<ScheduleState>;
+    startScheduledRun: (state: ScheduleState, occurrence?: number) => Promise<string>;
+    applyScheduleOccurrence: (state: ScheduleState, occurrence?: number) => Promise<ScheduleState>;
     settleBackfillScheduleState: (state: ScheduleState) => Promise<ScheduleState>;
     flushQueuedInlineWorkflowStartsDirectly: () => Promise<void>;
+    failWorkflow: (workflowId: string, error: Error) => Promise<void>;
+    handleCleanupError: (source: string, error: unknown, workflowId: string) => void;
 };
 export declare function schedule(internals: EngineInternals, type: string, input: unknown, spec: string | ScheduleSpec, options?: ScheduleOptions): Promise<ScheduleHandle>;
 export declare function listSchedules(internals: EngineInternals, filter?: ScheduleFilter): Promise<PaginatedResult<ScheduleSummary>>;
+export declare function recoverOrphanedScheduleTimers(internals: EngineInternals): Promise<void>;
 export declare function toScheduleSummary(state: ScheduleState): ScheduleSummary;
 export declare function pauseSchedule(internals: EngineInternals, scheduleId: string): Promise<void>;
 export declare function resumeSchedule(internals: EngineInternals, scheduleId: string): Promise<void>;
 export declare function cancelSchedule(internals: EngineInternals, scheduleId: string): Promise<void>;
 export declare function updateSchedule(internals: EngineInternals, scheduleId: string, newSpec: string | ScheduleSpec): Promise<void>;
 export declare function refreshScheduledWorkflowState(internals: EngineInternals, state: ScheduleState, callbacks: Pick<ScheduleCallbacks, 'loadWorkflowState'>): Promise<RefreshedScheduleState>;
-export declare function startScheduledRun(_internals: EngineInternals, state: ScheduleState, callbacks: Pick<ScheduleCallbacks, 'startWorkflow'>): Promise<string>;
-export declare function applyScheduleOccurrence(_internals: EngineInternals, state: ScheduleState, callbacks: ScheduleCallbacks): Promise<ScheduleState>;
+export declare function applyScheduleOccurrence(_internals: EngineInternals, state: ScheduleState, callbacks: ScheduleCallbacks, occurrence?: number): Promise<ScheduleState>;
 export declare function settleBackfillScheduleState(internals: EngineInternals, state: ScheduleState, callbacks: Pick<ScheduleCallbacks, 'flushQueuedInlineWorkflowStartsDirectly' | 'refreshScheduledWorkflowState'>): Promise<ScheduleState>;
 export declare function handleScheduledWorkflowTerminal(internals: EngineInternals, workflowId: string, callbacks: ScheduleCallbacks): Promise<void>;

package/dist/core/engine/schedules.js

@@ -1,7 +1,8 @@
 import { KEYS } from "../../storage/interface.js";
-import { decode, encode } from "../codec.js";
+import { decode } from "../codec.js";
 import { WorkflowNotRegisteredError } from "./errors.js";
-import { ScheduleHandle } from "./handles.js";
+import { ScheduleHandle } from "./schedule-handle.js";
+import { resolveEffectiveScheduleFireAt } from "./schedule-jitter.js";
 import { getNextScheduleOccurrence } from "./schedule-occurrence.js";
 import {
   clearScheduleCurrentWorkflow,
@@ -18,6 +19,7 @@ import {
   normalizeScheduleOptions,
   normalizeScheduleSpec
 } from "./validation/schedule.js";
+export { startScheduledRun } from "./schedule-run.js";
 export { handleScheduleTimer } from "./schedule-timer.js";
 export async function schedule(internals, type, input, spec, options) {
   if (!internals.registrations.has(type))
@@ -37,9 +39,11 @@ export async function schedule(internals, type, input, spec, options) {
       status: "active",
       overlap: normalizedOptions.overlap,
       backfill: normalizedOptions.backfill,
+      ...normalizedOptions.jitterMs !== void 0 && { jitterMs: normalizedOptions.jitterMs },
       createdAt: now,
       updatedAt: now,
       nextFireAt: getNextScheduleOccurrence({ ...cadenceFields, createdAt: now }, now),
+      missedFireCount: 0,
       queuedRuns: 0
     };
     await writeScheduleState(internals, state);
@@ -61,6 +65,28 @@ export async function listSchedules(internals, filter) {
   }
   return paginateScheduleSummaries(items, normalizedFilter);
 }
+export async function recoverOrphanedScheduleTimers(internals) {
+  for await (const [key, value] of internals.storage.scan("schedule:")) {
+    if (key.slice(9).includes(":"))
+      continue;
+    const state = decodeScheduleState(value);
+    if (!isActiveScheduleWithTimer(state))
+      continue;
+    if (await hasCurrentScheduleTimer(internals, state))
+      continue;
+    await writeScheduleState(internals, state);
+  }
+}
+function isActiveScheduleWithTimer(state) {
+  return state?.status === "active" && state.nextFireAt !== null;
+}
+async function hasCurrentScheduleTimer(internals, state) {
+  const timerKey = KEYS.scheduleTick(resolveEffectiveScheduleFireAt(state, state.nextFireAt), state.id);
+  if (await internals.storage.get(timerKey) === null)
+    return !1;
+  const timerIndexBytes = await internals.storage.get(`timer-idx:${createScheduleTimerId(state.id)}`);
+  return timerIndexBytes !== null && decode(timerIndexBytes) === timerKey;
+}
 export function toScheduleSummary(state) {
   const { input: _input, ...summary } = state;
   return summary;
@@ -107,10 +133,7 @@ export async function cancelSchedule(internals, scheduleId) {
   await writeScheduleState(internals, updatedState, { includeTimer: !1 });
 }
 export async function updateSchedule(internals, scheduleId, newSpec) {
-  const normalizedScheduleId = coerceScheduleId(scheduleId, "scheduleId"), normalizedSpec = normalizeScheduleSpec(newSpec), state = await requireScheduleState(internals, normalizedScheduleId);
-  if (state.status === "active")
-    await internals.scheduler.cancel(createScheduleTimerId(normalizedScheduleId), normalizedScheduleId);
-  const now = internals.options.getNow(), {
+  const normalizedScheduleId = coerceScheduleId(scheduleId, "scheduleId"), normalizedSpec = normalizeScheduleSpec(newSpec), state = await requireScheduleState(internals, normalizedScheduleId), now = internals.options.getNow(), {
     cronExpression: _droppedCron,
     intervalMs: _droppedInterval,
     ...stateWithoutCadence
@@ -123,11 +146,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 {
@@ -135,36 +162,34 @@ export async function refreshScheduledWorkflowState(internals, state, callbacks)
     currentWorkflowState: currentWorkflowState ?? null
   };
 }
-export async function startScheduledRun(_internals, state, callbacks) {
-  const workflowId = crypto.randomUUID(), scheduleRunOperations = state.overlap === "allow" ? void 0 : [{ type: "put", key: KEYS.scheduleRun(workflowId), value: encode(state.id) }];
-  await callbacks.startWorkflow(state.workflowType, state.input, { id: workflowId }, scheduleRunOperations);
-  return workflowId;
-}
 function hasActiveScheduledWorkflow(currentWorkflowState) {
-  return currentWorkflowState?.status === "running" || currentWorkflowState?.status === "pending";
+  return scheduledRunOccupiesSlot(currentWorkflowState);
 }
-async function applyBlockedScheduleOccurrence(state, hasActiveWorkflow, callbacks) {
+async function applyBlockedScheduleOccurrence(state, hasActiveWorkflow, callbacks, occurrence) {
   if (!hasActiveWorkflow)
-    return { ...state, currentWorkflowId: await callbacks.startScheduledRun(state) };
+    return { ...state, currentWorkflowId: await callbacks.startScheduledRun(state, occurrence) };
   if (state.overlap === "cancel-running") {
     if (state.currentWorkflowId) {
       callbacks.getWorkflowResult(state.currentWorkflowId).catch(() => {});
       await callbacks.cancelWorkflow(state.currentWorkflowId);
     }
     const stateForStart = clearScheduleCurrentWorkflow(state);
-    return { ...state, currentWorkflowId: await callbacks.startScheduledRun(stateForStart) };
+    return {
+      ...state,
+      currentWorkflowId: await callbacks.startScheduledRun(stateForStart, occurrence)
+    };
   }
   if (state.overlap === "queue")
     return { ...state, queuedRuns: state.queuedRuns + 1 };
   return state;
 }
-export async function applyScheduleOccurrence(_internals, state, callbacks) {
+export async function applyScheduleOccurrence(_internals, state, callbacks, occurrence) {
   const { state: refreshedState, currentWorkflowState } = await callbacks.refreshScheduledWorkflowState(state), hasActiveWorkflow = hasActiveScheduledWorkflow(currentWorkflowState);
   if (refreshedState.overlap === "allow") {
-    await callbacks.startScheduledRun(refreshedState);
+    await callbacks.startScheduledRun(refreshedState, occurrence);
     return refreshedState;
   }
-  return applyBlockedScheduleOccurrence(refreshedState, hasActiveWorkflow, callbacks);
+  return applyBlockedScheduleOccurrence(refreshedState, hasActiveWorkflow, callbacks, occurrence);
 }
 export async function settleBackfillScheduleState(internals, state, callbacks) {
   if (!state.currentWorkflowId)

package/dist/core/engine/search-attribute-records.d.ts

@@ -0,0 +1,4 @@
+import type { ListFilter, SearchAttributeValue } from '../types.ts';
+import type { EngineInternals } from './internals.ts';
+export declare function readSearchAttributesForStates(internals: EngineInternals, stateBytesList: readonly (Uint8Array | null)[], filter: ListFilter | undefined): Promise<Map<string, Record<string, SearchAttributeValue> | null>>;
+export declare function readSearchAttributesForFilter(internals: EngineInternals, workflowId: string, filter: ListFilter | undefined): Promise<Record<string, SearchAttributeValue> | null>;

package/dist/core/engine/search-attribute-records.js

@@ -0,0 +1,17 @@
+import { KEYS } from "../../storage/interface.js";
+import { decodeSearchAttributeRecord, listFilterHasAttributeFilters } from "./state-utilities.js";
+import { decodeWorkflowState } from "./validation.js";
+export async function readSearchAttributesForStates(internals, stateBytesList, filter) {
+  const searchAttributesByWorkflowId = new Map;
+  if (!listFilterHasAttributeFilters(filter))
+    return searchAttributesByWorkflowId;
+  const states = stateBytesList.flatMap((stateBytes) => stateBytes === null ? [] : [decodeWorkflowState(stateBytes)]), attributeBytesList = await Promise.all(states.map((state) => internals.storage.get(KEYS.attribute(state.id))));
+  for (let index = 0;index < states.length; index += 1)
+    searchAttributesByWorkflowId.set(states[index].id, decodeSearchAttributeRecord(attributeBytesList[index] ?? null));
+  return searchAttributesByWorkflowId;
+}
+export async function readSearchAttributesForFilter(internals, workflowId, filter) {
+  if (!listFilterHasAttributeFilters(filter))
+    return null;
+  return decodeSearchAttributeRecord(await internals.storage.get(KEYS.attribute(workflowId)));
+}

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,8 +32,45 @@ 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 condition gates on
+ * the `sigres:` accepted-response marker (the dedup identity, keyed by signalId
+ * alone), NOT the `sig:` payload key: the FIFO sort-class (#458) makes the
+ * start-signal's `sig:` key (class `0`) differ from the live signal path's (class
+ * `1`), so a `sig:`-keyed CAS would no longer collide with a pre-buffered signal
+ * of the same signalId and would buffer a second copy. The class-independent
+ * `sigres:` marker is what both paths share, so gating on it preserves "one
+ * signal per signalId" across the create and signal paths.
+ */
+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>;
+export declare function consumeSignalWithAtomicWorkflowCommit(internals: EngineInternals, workflowId: string, signalName: string): Promise<ConsumedSignalResult>;
+/**
+ * Read the first buffered signal payload WITHOUT deleting it. Use when a caller
+ * must check for a buffered signal but might not end up consuming it — e.g. a
+ * `ctx.race` / `ctx.all` wait-signal branch that could lose, where a destructive
+ * {@link consumeSignal} on the losing path would silently drop the signal. The
+ * winner calls {@link consumeSignalWithAtomicWorkflowCommit} to stage the
+ * durable delete into the checkpoint batch.
+ */
+export declare function peekSignal(internals: EngineInternals, workflowId: string, signalName: string): Promise<ConsumedSignalResult>;
 /** Register a waiter key in a workflow-keyed reverse index. */
 export declare function trackWaiterKey(reverseIndex: Map<string, TrackedWaiterKeys>, workflowId: string, waiterKey: string): void;
 /** Remove a waiter key from a workflow-keyed reverse index. */