@lostgradient/weft 0.3.0 → 0.5.0

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 "./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
@@ -139,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 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/signals.d.ts

@@ -43,8 +43,14 @@ export declare function bufferSignalPayloads(internals: EngineInternals, workflo
  * `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.
+ * 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[];
@@ -55,6 +61,16 @@ export declare function buildCreateBatchSignalOperations(internals: EngineIntern
 };
 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. */

package/dist/core/engine/signals.js

@@ -9,8 +9,9 @@ import { SignalReceivedEvent } from "../events.js";
 import { encodePayloadWithinLimit } from "../payload-size.js";
 import { validateSignalId } from "../signal-id.js";
 import { commitAnonymousSignalOperations } from "./anonymous-signal-sequence.js";
+import { stageAtomicWorkflowCommitSideEffects } from "./checkpoint-side-effects.js";
 import { isTerminalWorkflowStatus } from "./validation.js";
-const EMPTY_STORAGE_VALUE = new Uint8Array(0), SIGNAL_ACCEPTED_RESPONSE = { ok: !0 };
+const EMPTY_STORAGE_VALUE = new Uint8Array(0), SIGNAL_ACCEPTED_RESPONSE = { ok: !0 }, SIGNAL_KEY_COMPONENT_COUNT = 5;
 export async function signal(internals, workflowId, name, payload, callbacks, options = {}) {
   const deliverSignal = async (targetWorkflowId, signalName, signalPayload) => {
     await bufferSignalPayloads(internals, targetWorkflowId, [{ signalName, payload: signalPayload }], callbacks, options);
@@ -65,10 +66,8 @@ export async function bufferSignalPayloads(internals, workflowId, deliveries, ca
     const delivery = deliveries[0], acceptedResponseKey = KEYS.signalAcceptedResponse(workflowId, delivery.signalName, signalId), acceptedResponse = encode(SIGNAL_ACCEPTED_RESPONSE);
     if (await internals.storage.get(acceptedResponseKey) !== null)
       return;
-    if (!await storageConditionalBatch(internals.storage, [{ key: KEYS.signal(workflowId, delivery.signalName, signalId), expectedValue: null }], [...operations, { type: "put", key: acceptedResponseKey, value: acceptedResponse }])) {
-      await ensureDuplicateSignalAcceptedResponse(internals, acceptedResponseKey, acceptedResponse);
+    if (!await storageConditionalBatch(internals.storage, [{ key: acceptedResponseKey, expectedValue: null }], [...operations, { type: "put", key: acceptedResponseKey, value: acceptedResponse }]))
       return;
-    }
     markTerminalCleanupTracked(internals, workflowId);
     deliverBufferedSignals(internals, workflowId, deliveries, callbacks);
     return;
@@ -85,7 +84,7 @@ function createExplicitSignalOperations(internals, workflowId, deliveries, signa
 }
 export function buildCreateBatchSignalOperations(internals, workflowId, signalName, payload, signalId) {
   validateSignalId(signalId);
-  const signalKey = KEYS.signal(workflowId, signalName, signalId), acceptedResponseKey = KEYS.signalAcceptedResponse(workflowId, signalName, signalId);
+  const signalKey = KEYS.startSignal(workflowId, signalName, signalId), acceptedResponseKey = KEYS.signalAcceptedResponse(workflowId, signalName, signalId);
   return {
     operations: [
       {
@@ -95,7 +94,7 @@ export function buildCreateBatchSignalOperations(internals, workflowId, signalNa
       },
       { type: "put", key: acceptedResponseKey, value: encode(SIGNAL_ACCEPTED_RESPONSE) }
     ],
-    condition: { key: signalKey, expectedValue: null }
+    condition: { key: acceptedResponseKey, expectedValue: null }
   };
 }
 function appendTerminalCleanupOperation(internals, workflowId, operations) {
@@ -130,18 +129,45 @@ function deliverBufferedSignals(internals, workflowId, deliveries, callbacks) {
     callbacks.resumeParkedInlineWorkflow(workflowId);
 }
 export async function hasBufferedSignal(internals, workflowId, signalName) {
-  const prefix = `sig:${encodeStorageKeyComponent(workflowId)}:${signalName}:`;
-  for await (const _entry of internals.storage.scan(prefix, { limit: 1 }))
-    return !0;
-  return !1;
+  return await findBufferedSignalRecord(internals, workflowId, signalName) !== null;
 }
 export async function consumeSignal(internals, workflowId, signalName) {
-  const prefix = `sig:${encodeStorageKeyComponent(workflowId)}:${signalName}:`;
-  for await (const [key, value] of internals.storage.scan(prefix, { limit: 1 })) {
-    await internals.storage.delete(key);
-    return { found: !0, payload: decode(value) };
-  }
-  return { found: !1 };
+  const record = await findBufferedSignalRecord(internals, workflowId, signalName);
+  if (record === null)
+    return { found: !1 };
+  await internals.storage.delete(record.key);
+  return { found: !0, payload: decode(record.value) };
+}
+export async function consumeSignalWithAtomicWorkflowCommit(internals, workflowId, signalName) {
+  const record = await findBufferedSignalRecord(internals, workflowId, signalName);
+  if (record === null)
+    return { found: !1 };
+  stageAtomicWorkflowCommitSideEffects(internals, workflowId, {
+    conditions: [{ key: record.key, expectedValue: new Uint8Array(record.value) }],
+    operations: [{ type: "delete", key: record.key }]
+  });
+  return { found: !0, payload: decode(record.value) };
+}
+export async function peekSignal(internals, workflowId, signalName) {
+  const record = await findBufferedSignalRecord(internals, workflowId, signalName);
+  return record === null ? { found: !1 } : { found: !0, payload: decode(record.value) };
+}
+async function findBufferedSignalRecord(internals, workflowId, signalName) {
+  const encodedWorkflowId = encodeStorageKeyComponent(workflowId), encodedSignalName = encodeStorageKeyComponent(signalName), encodedPrefix = signalKeyPrefix(encodedWorkflowId, encodedSignalName);
+  return await findBufferedSignalRecordByPrefix(internals, encodedPrefix, encodedWorkflowId, encodedSignalName);
+}
+async function findBufferedSignalRecordByPrefix(internals, prefix, encodedWorkflowId, signalNameKeyComponent) {
+  for await (const [key, value] of internals.storage.scan(prefix, { limit: 1 }))
+    if (isExactSignalKey(key, encodedWorkflowId, signalNameKeyComponent))
+      return { key, value };
+  return null;
+}
+function signalKeyPrefix(encodedWorkflowId, signalNameKeyComponent) {
+  return `sig:${encodedWorkflowId}:${signalNameKeyComponent}:`;
+}
+function isExactSignalKey(key, encodedWorkflowId, signalNameKeyComponent) {
+  const components = key.split(":");
+  return components.length === SIGNAL_KEY_COMPONENT_COUNT && components[0] === "sig" && components[1] === encodedWorkflowId && components[2] === signalNameKeyComponent && (components[3] === "0" || components[3] === "1") && components[4] !== "";
 }
 function getSingleSignalId(deliveries, defaultOptions) {
   if (deliveries.length !== 1)
@@ -159,11 +185,6 @@ function validateSignalIdsBeforeKeyConstruction(deliveries, defaultOptions, sing
       validateSignalId(deliverySignalId);
   }
 }
-async function ensureDuplicateSignalAcceptedResponse(internals, acceptedResponseKey, acceptedResponse) {
-  if (await internals.storage.get(acceptedResponseKey) !== null)
-    return;
-  await storageConditionalBatch(internals.storage, [{ key: acceptedResponseKey, expectedValue: null }], [{ type: "put", key: acceptedResponseKey, value: acceptedResponse }]);
-}
 export function trackWaiterKey(reverseIndex, workflowId, waiterKey) {
   let keys = reverseIndex.get(workflowId);
   if (!keys) {

package/dist/core/engine/state-utilities.d.ts

@@ -1,5 +1,49 @@
 import type { ContextOperationRequest } from '../context.ts';
-import type { ListFilter, PaginatedResult, ScheduleFilter, ScheduleState, ScheduleSummary, WorkflowState, WorkflowSummary } from '../types.ts';
+import type { AttributeFilter, AttributeFilterScalarValue, ListFilter, PaginatedResult, ScheduleFilter, ScheduleState, ScheduleSummary, SearchAttributeValue, WorkflowState, WorkflowSummary } from '../types.ts';
+/**
+ * Durable execution-claim record stored at {@link KEYS.teardownOwed} for a workflow
+ * that owes an engine-driven finalizer run (issue #446 Phase 2). A holder fenced-CAS's
+ * it from `'owed'` to `'running'` before invoking the finalizer, then back to `'owed'`
+ * (with `attempts` bumped) on a retryable failure, or deletes it on success/dead-letter.
+ *
+ * Liveness is decided by TIME, not by an in-memory set or a lease epoch: a `'running'`
+ * claim is reclaimable once `claimedAt` is older than the stale threshold (the
+ * finalizer's per-attempt timeout plus a margin — see `teardownStaleThresholdMs`). This
+ * makes crash recovery an ordinary stale-claim retry with no special re-hydration: a
+ * fresh process simply re-fires the surviving timer and reclaims the stale `'running'`
+ * marker. The cost is that a finalizer running past the threshold may be re-driven
+ * concurrently, which is why workflow finalizers must be idempotent.
+ *
+ * - `status`: `'owed'` until claimed, `'running'` while a holder is executing it.
+ * - `attempts`: count of finalizer attempts so far (`0` until the first claim).
+ * - `token`: ties the marker to its `wf-teardown:` timer so a stale timer for a
+ *   re-armed (different-token) claim cannot drive it.
+ * - `claimedAt`: engine clock at the `owed → running` transition; `undefined` while
+ *   `'owed'`. Drives the time-based reclaim of an abandoned `'running'` claim.
+ */
+export type TeardownClaim = {
+    status: 'owed' | 'running';
+    attempts: number;
+    token: string;
+    claimedAt?: number;
+};
+/** Build the durable teardown timer id from its claim token (parsed by {@link parseTeardownTimerId}). */
+export declare function createTeardownTimerId(token: string): string;
+/** Recover the claim token from a teardown timer id, or `null` when the id is malformed. */
+export declare function parseTeardownTimerId(timerId: string): string | null;
+/**
+ * Runtime type guard for a decoded {@link TeardownClaim} read back from storage.
+ *
+ * `attempts` must be a non-negative SAFE INTEGER and `claimedAt` (when present) a
+ * finite non-negative number — not merely `typeof === 'number'`. A persisted `NaN`
+ * or `Infinity` would otherwise drive the marker forever: `attempt >= MAX_TEARDOWN_ATTEMPTS`
+ * is always false for `NaN` (never dead-letters) and `now - claimedAt >= threshold` never
+ * holds for a non-finite `claimedAt` (never reclaims a stale running claim). Rejecting them
+ * here routes a corrupt-but-claim-shaped marker through the clear path instead. `claimedAt`
+ * is checked with `isFinite` rather than `isSafeInteger` because `getNow()` may return a
+ * fractional timestamp.
+ */
+export declare function isTeardownClaim(value: unknown): value is TeardownClaim;
 type PaginationFilter = {
     limit?: number;
     offset?: number;
@@ -34,7 +78,10 @@ export declare function encodeWorkflowStartHeaders(headers: Map<string, string>)
 export declare function decodeWorkflowStartHeaders(bytes: Uint8Array): Map<string, string>;
 export declare function selectPersistedWorkflowStartHeaders(headers: Map<string, string> | undefined): Map<string, string> | undefined;
 export declare function intersectIdentifierSets(idSets: Set<string>[]): Set<string> | null;
-export declare function matchesListFilter(state: WorkflowState, filter: ListFilter | undefined, constrainedIds: Set<string> | null, normalizedTagFilters: readonly string[] | undefined): boolean;
+export declare function listFilterHasAttributeFilters(filter: ListFilter | undefined): boolean;
+export declare function decodeSearchAttributeRecord(attributeBytes: Uint8Array | null): Record<string, SearchAttributeValue> | null;
+export declare function attributeFilterExactValues(filter: AttributeFilter): readonly AttributeFilterScalarValue[] | null;
+export declare function matchesListFilter(state: WorkflowState, filter: ListFilter | undefined, constrainedIds: Set<string> | null, normalizedTagFilters: readonly string[] | undefined, searchAttributes?: Readonly<Record<string, SearchAttributeValue>> | null): boolean;
 /**
  * Slice an in-memory list of {@link WorkflowSummary} into a {@link PaginatedResult}.
  *

package/dist/core/engine/state-utilities.js

@@ -1,8 +1,32 @@
 import { decode, encode } from "../codec.js";
 import { isRecord, safeDebugStringify, sanitizeDebugValueForDisplay } from "../debug-output.js";
+import { encodeAttributeValue } from "../search-attributes.js";
+import { searchAttributeName } from "../types.js";
 import { matchesWorkflowTagFilter } from "../workflow-tags.js";
+import { stripInternalCheckpointReplayPayload } from "./checkpoint-replay.js";
 import { isPlainObjectRecord, isSanitizedSearchAttributeValue } from "./validation.js";
-const PERSISTED_WORKFLOW_START_HEADER_NAMES = new Set(["traceparent", "tracestate"]), PRESERVE_OUTPUT_TERMINAL_CLEANUP_TIMER_PREFIX = "terminal-cleanup:preserve-output:", FULL_TERMINAL_CLEANUP_TIMER_PREFIX = "terminal-cleanup:full:";
+const PERSISTED_WORKFLOW_START_HEADER_NAMES = new Set(["traceparent", "tracestate"]), PRESERVE_OUTPUT_TERMINAL_CLEANUP_TIMER_PREFIX = "terminal-cleanup:preserve-output:", FULL_TERMINAL_CLEANUP_TIMER_PREFIX = "terminal-cleanup:full:", TEARDOWN_TIMER_PREFIX = "teardown:";
+export function createTeardownTimerId(token) {
+  return `${TEARDOWN_TIMER_PREFIX}${token}`;
+}
+export function parseTeardownTimerId(timerId) {
+  if (!timerId.startsWith(TEARDOWN_TIMER_PREFIX))
+    return null;
+  const token = timerId.slice(TEARDOWN_TIMER_PREFIX.length);
+  return token.length === 0 ? null : token;
+}
+export function isTeardownClaim(value) {
+  if (typeof value !== "object" || value === null)
+    return !1;
+  const candidate = value;
+  return (candidate.status === "owed" || candidate.status === "running") && typeof candidate.token === "string" && isNonNegativeSafeInteger(candidate.attempts) && isAbsentOrFiniteNonNegative(candidate.claimedAt);
+}
+function isNonNegativeSafeInteger(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function isAbsentOrFiniteNonNegative(value) {
+  return value === void 0 || typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
 export function workflowFeedListenerKey(workflowId, selector) {
   return `${workflowId}\x00${selector}`;
 }
@@ -33,6 +57,8 @@ export function getTimelineOperationLabel(operation) {
       return operation.signalName;
     case "wait-update":
       return operation.updateName;
+    case "get-version":
+      return operation.changeId;
     case "child-workflow":
       return operation.workflowType;
     case "load":
@@ -84,6 +110,13 @@ export function getTimelineBasicInputSummary(operation) {
       return summarizeTimelineValue({ signalName: operation.signalName });
     case "wait-update":
       return summarizeTimelineValue({ updateName: operation.updateName });
+    case "get-version":
+      return summarizeTimelineValue({
+        changeId: operation.changeId,
+        minSupported: operation.minSupported,
+        maxSupported: operation.maxSupported,
+        version: operation.version
+      });
     case "parallel":
     case "race":
       return summarizeTimelineValue({ operationCount: operation.operations.length });
@@ -138,7 +171,7 @@ export function sanitizeCheckpointState(checkpoint) {
 }
 export function sanitizeWorkflowEventPayload(payload) {
   const sanitized = sanitizeDebugValueForDisplay(payload);
-  return isRecord(sanitized) ? sanitized : { value: sanitized };
+  return isRecord(sanitized) ? stripInternalCheckpointReplayPayload(sanitized) : { value: sanitized };
 }
 export function sanitizeTimelineSummary(summary) {
   if (summary === void 0)
@@ -207,7 +240,83 @@ function matchesListFilterFailureCategory(state, filter) {
   const categories = Array.isArray(filter.failureCategory) ? filter.failureCategory : [filter.failureCategory];
   return state.failureCategory !== void 0 && state.failureCategory !== null && categories.includes(state.failureCategory);
 }
-export function matchesListFilter(state, filter, constrainedIds, normalizedTagFilters) {
+export function listFilterHasAttributeFilters(filter) {
+  return (filter?.attributes?.length ?? 0) > 0;
+}
+function isSearchAttributeFilterValue(value) {
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || value instanceof Date)
+    return !0;
+  return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+export function decodeSearchAttributeRecord(attributeBytes) {
+  if (attributeBytes === null)
+    return null;
+  const decoded = decode(attributeBytes);
+  if (!isPlainObjectRecord(decoded))
+    return null;
+  const attributes = {};
+  for (const [key, value] of Object.entries(decoded))
+    if (isSearchAttributeFilterValue(value))
+      attributes[key] = value;
+  return attributes;
+}
+export function attributeFilterExactValues(filter) {
+  if (filter.value === void 0)
+    return null;
+  if (Array.isArray(filter.value))
+    return [...filter.value];
+  return [filter.value];
+}
+function storedAttributeScalarValues(value) {
+  return Array.isArray(value) ? value : [value];
+}
+function attributeValuesEqual(actual, expected) {
+  if (actual instanceof Date || expected instanceof Date)
+    return actual instanceof Date && expected instanceof Date && actual.getTime() === expected.getTime();
+  return actual === expected;
+}
+function attributeValueMatchesAnyOf(actual, expectedValues) {
+  if (expectedValues.length === 0)
+    return !1;
+  for (const actualValue of storedAttributeScalarValues(actual))
+    if (expectedValues.some((expectedValue) => attributeValuesEqual(actualValue, expectedValue)))
+      return !0;
+  return !1;
+}
+function encodedAttributeValueSatisfiesRange(encodedValue, filter) {
+  if (filter.gte !== void 0 && encodedValue < encodeAttributeValue(filter.gte))
+    return !1;
+  if (filter.gt !== void 0 && encodedValue <= encodeAttributeValue(filter.gt))
+    return !1;
+  if (filter.lte !== void 0 && encodedValue > encodeAttributeValue(filter.lte))
+    return !1;
+  if (filter.lt !== void 0 && encodedValue >= encodeAttributeValue(filter.lt))
+    return !1;
+  return !0;
+}
+function attributeValueMatchesRange(value, filter) {
+  for (const scalarValue of storedAttributeScalarValues(value))
+    if (encodedAttributeValueSatisfiesRange(encodeAttributeValue(scalarValue), filter))
+      return !0;
+  return !1;
+}
+function matchesAttributeFilter(searchAttributes, filter) {
+  const attributeValue = searchAttributes[searchAttributeName(filter.key)];
+  if (attributeValue === void 0)
+    return !1;
+  const exactValues = attributeFilterExactValues(filter);
+  if (exactValues !== null)
+    return attributeValueMatchesAnyOf(attributeValue, exactValues);
+  return attributeValueMatchesRange(attributeValue, filter);
+}
+function matchesListFilterAttributes(searchAttributes, filter) {
+  if (!listFilterHasAttributeFilters(filter))
+    return !0;
+  if (searchAttributes === null || searchAttributes === void 0)
+    return !1;
+  return filter.attributes.every((attributeFilter) => matchesAttributeFilter(searchAttributes, attributeFilter));
+}
+export function matchesListFilter(state, filter, constrainedIds, normalizedTagFilters, searchAttributes) {
   if (constrainedIds !== null && !constrainedIds.has(state.id))
     return !1;
   if (!matchesWorkflowTagFilter(state.tags, normalizedTagFilters))
@@ -220,6 +329,8 @@ export function matchesListFilter(state, filter, constrainedIds, normalizedTagFi
     return !1;
   if (!matchesListFilterFailureCategory(state, filter))
     return !1;
+  if (!matchesListFilterAttributes(searchAttributes, filter))
+    return !1;
   return !0;
 }
 function timestampInRange(value, range) {

package/dist/core/engine/storage-io.d.ts

@@ -7,8 +7,21 @@ export declare function runSerializedWorkflowStateWrite<TResult>(internals: Engi
 export declare function loadWorkflowState(internals: EngineInternals, workflowId: string): Promise<WorkflowState | null>;
 /** Load a terminal workflow result or throw the persisted terminal error. */
 export declare function loadWorkflowResult(internals: EngineInternals, workflowId: string): Promise<unknown>;
-/** Commit workflow state operations. */
-export declare function commitWorkflowStateOperations(internals: EngineInternals, _state: WorkflowState, operations: BatchOperation[]): Promise<void>;
+type WorkflowStateCommitOptions = {
+    includePendingAtomicSideEffects?: boolean;
+};
+/**
+ * Commit an engine-generator-owned workflow-state advance, FENCED on the lease
+ * epoch under `ownership: 'lease'` (issue #470 Step 2). A deposed engine's write
+ * loses its CAS instead of corrupting the successor's state; the deposition is
+ * detected and the engine halts (see {@link commitFencedEngineWrite}). Under
+ * `ownership: 'none'` it is byte-for-byte the pre-Step-2 commit shape — the epoch
+ * condition is only appended when a lease is held. Use this for suspend,
+ * completion, and other state advances driven by the workflow lifecycle. Operator/
+ * external mutations (search-attribute and tag edits) do NOT use this helper; they
+ * batch directly and are intentionally never fenced.
+ */
+export declare function commitFencedWorkflowStateOperations(internals: EngineInternals, state: WorkflowState, operations: BatchOperation[], options?: WorkflowStateCommitOptions): Promise<void>;
 /** Load and decode persisted schedule state by schedule ID. */
 export declare function loadScheduleState(internals: EngineInternals, scheduleId: string): Promise<ScheduleState | null>;
 /** Load a schedule state. */
@@ -19,3 +32,4 @@ export declare function writeScheduleState(internals: EngineInternals, state: Sc
 }): Promise<void>;
 /** Load persisted workflow start headers by workflow ID. */
 export declare function loadWorkflowStartHeaders(internals: EngineInternals, workflowId: string): Promise<Map<string, string> | undefined>;
+export {};

package/dist/core/engine/storage-io.js

@@ -1,8 +1,16 @@
-import { KEYS } from "../../storage/interface.js";
+import {
+  KEYS
+} from "../../storage/interface.js";
 import { encode } from "../codec.js";
 import { buildTimerBatchOperations } from "../scheduler.js";
 import { WorkflowTimeoutError } from "../timeouts.js";
+import {
+  clearPendingAtomicWorkflowCommitSideEffects,
+  takePendingAtomicWorkflowCommitSideEffects
+} from "./checkpoint-side-effects.js";
+import { commitFencedEngineWrite } from "./fenced-write.js";
 import { getWorkflowExecutionStartedAt } from "./handles.js";
+import { resolveEffectiveScheduleFireAt } from "./schedule-jitter.js";
 import { createScheduleTimerId, decodeWorkflowStartHeaders } from "./state-utilities.js";
 import { decodeWorkflowState } from "./validation.js";
 import { decodeScheduleState } from "./validation/schedule.js";
@@ -48,8 +56,19 @@ export async function loadWorkflowResult(internals, workflowId) {
   }
   throw Error(`Workflow "${workflowId}" is still ${state.status}`);
 }
-export async function commitWorkflowStateOperations(internals, _state, operations) {
-  await internals.storage.batch(operations);
+function buildWorkflowStateCommit(internals, workflowId, operations, options) {
+  const pendingSideEffects = options.includePendingAtomicSideEffects ? takePendingAtomicWorkflowCommitSideEffects(internals, workflowId) : void 0, operationsWithSideEffects = pendingSideEffects === void 0 ? operations : [...operations, ...pendingSideEffects.operations], conditions = internals.storage.capabilities().conditionalBatch ? pendingSideEffects?.conditions ?? [] : [];
+  return {
+    operations: operationsWithSideEffects,
+    conditions,
+    hasPendingSideEffects: pendingSideEffects !== void 0
+  };
+}
+export async function commitFencedWorkflowStateOperations(internals, state, operations, options = {}) {
+  const commit = buildWorkflowStateCommit(internals, state.id, operations, options);
+  await commitFencedEngineWrite(internals, commit.operations, commit.conditions, () => Error(`Workflow state commit for workflow "${state.id}" lost its atomic side-effect precondition.`));
+  if (commit.hasPendingSideEffects)
+    clearPendingAtomicWorkflowCommitSideEffects(internals, state.id);
 }
 export async function loadScheduleState(internals, scheduleId) {
   const bytes = await internals.storage.get(KEYS.schedule(scheduleId));
@@ -65,13 +84,15 @@ export async function writeScheduleState(internals, state, options) {
   const operations = [
     { type: "put", key: KEYS.schedule(state.id), value: encode(state) }
   ];
-  if ((options?.includeTimer ?? state.status === "active") && state.status === "active" && state.nextFireAt !== null)
+  if ((options?.includeTimer ?? state.status === "active") && state.status === "active" && state.nextFireAt !== null) {
+    const effectiveFireAt = resolveEffectiveScheduleFireAt(state, state.nextFireAt);
     operations.push(...buildTimerBatchOperations({
       id: createScheduleTimerId(state.id),
       workflowId: state.id,
-      fireAt: state.nextFireAt,
+      fireAt: effectiveFireAt,
       kind: "schedule"
     }));
+  }
   await internals.storage.batch(operations);
 }
 export async function loadWorkflowStartHeaders(internals, workflowId) {

package/dist/core/engine/stream-chunk-loading.d.ts

@@ -3,3 +3,5 @@ import type { StoredStreamChunk } from '../context.ts';
 export declare function loadStoredStreamChunks(storage: Storage, workflowId: string, key: string, options?: {
     after?: number;
 }): Promise<StoredStreamChunk[]>;
+export declare function encodeStoredStreamTailSequence(sequence: number): Uint8Array;
+export declare function loadStoredStreamTailSequence(storage: Storage, workflowId: string, key: string): Promise<number | null>;

package/dist/core/engine/stream-chunk-loading.js

@@ -1,5 +1,5 @@
 import { KEYS } from "../../storage/interface.js";
-import { decode } from "../codec.js";
+import { decode, encode } from "../codec.js";
 const STREAM_CHUNK_SEQUENCE_PATTERN = /^\d+$/;
 function parseStreamChunkSequence(sequenceText) {
   if (!STREAM_CHUNK_SEQUENCE_PATTERN.test(sequenceText))
@@ -20,3 +20,26 @@ export async function loadStoredStreamChunks(storage, workflowId, key, options)
   }
   return chunks;
 }
+export function encodeStoredStreamTailSequence(sequence) {
+  return encode({ sequence });
+}
+function parseStoredStreamTailSequence(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    return null;
+  if (!("sequence" in value))
+    return null;
+  const sequence = value.sequence;
+  if (typeof sequence !== "number" || !Number.isSafeInteger(sequence) || sequence < -1)
+    return null;
+  return sequence;
+}
+export async function loadStoredStreamTailSequence(storage, workflowId, key) {
+  const bytes = await storage.get(KEYS.streamTail(workflowId, key));
+  if (bytes === null)
+    return null;
+  try {
+    return parseStoredStreamTailSequence(decode(bytes));
+  } catch {
+    return null;
+  }
+}