@ferricstore/ferricstore 0.12.2 → 0.13.1

package/dist/index.js

@@ -30,9 +30,16 @@ var FerricStoreError = class extends Error {
 };
 var HTTPTransportError = class extends FerricStoreError {
   code = "http_transport";
+  requestDisposition;
   statusCode;
   constructor(message, options = {}) {
-    super(message, options);
+    const disposition = options.requestDisposition;
+    super(message, {
+      ...options,
+      retryable: options.retryable ?? (disposition === "unsent" ? false : void 0),
+      safeToRetry: options.safeToRetry ?? (disposition === "unsent" ? true : disposition === "possibly_sent" ? false : void 0)
+    });
+    this.requestDisposition = disposition;
     this.statusCode = options.statusCode;
   }
 };
@@ -57,6 +64,20 @@ var RequestTimeoutError = class extends FerricStoreError {
     this.timeoutMs = timeoutMs;
   }
 };
+var RequestNotSentError = class extends FerricStoreError {
+  code = "request_not_sent";
+  requestDisposition = "unsent";
+  constructor(message, options = {}) {
+    super(message, { ...options, retryable: false, safeToRetry: true });
+  }
+};
+function requestNotSentError(error, message) {
+  if (error instanceof RequestNotSentError) return error;
+  return new RequestNotSentError(
+    message ?? (error instanceof Error ? error.message : String(error)),
+    { cause: error, raw: error }
+  );
+}
 var FlowNotFoundError = class extends FerricStoreError {
   code = "flow_not_found";
 };
@@ -6315,7 +6336,10 @@ function decodeCompactPipeline(data, budget, claimModes) {
       );
       offset = read.offset;
     } else {
-      throw new FerricStoreError("unknown compact pipeline status");
+      throw new FerricStoreError(`unknown compact pipeline status ${status}`, {
+        retryable: false,
+        safeToRetry: false
+      });
     }
   }
   if (offset !== data.byteLength) throw new FerricStoreError("trailing compact pipeline bytes");
@@ -6485,6 +6509,7 @@ var COUNTED_COMPACT_TAGS = /* @__PURE__ */ new Set([
 ]);
 
 // src/protocol-response.ts
+var KNOWN_NATIVE_RESPONSE_STATUSES = /* @__PURE__ */ new Set([0, 1, 2, 3, 4, 5, 6]);
 function decodeResponse(frame, expectedOpcode, hints = {}) {
   if (frame.opcode !== expectedOpcode) {
     throw new FerricStoreError(
@@ -6509,6 +6534,13 @@ function decodeResponse(frame, expectedOpcode, hints = {}) {
     customPayload
   );
   if (status === STATUS_OK) return value;
+  if (!KNOWN_NATIVE_RESPONSE_STATUSES.has(status)) {
+    throw new FerricStoreError(`unknown native response status ${status}`, {
+      raw: value,
+      retryable: false,
+      safeToRetry: false
+    });
+  }
   const message = protocolErrorMessage(status, value);
   throw classifyServerError(message, value, void 0, status);
 }
@@ -6548,7 +6580,7 @@ function unwrapPipelineResponse(value, options = {}, expectedItems) {
           continue;
         }
         const error = classifyServerError(
-          protocolErrorMessage(status === "busy" ? 4 : 1, payload),
+          protocolErrorMessage(pipelineStatusCode(status), payload),
           payload,
           void 0,
           status
@@ -6557,15 +6589,46 @@ function unwrapPipelineResponse(value, options = {}, expectedItems) {
         out[index] = error;
         continue;
       }
+      if (pipelineStatusToken(item[0]) != null) {
+        const unknown = pipelineStatusToken(item[0]) ?? "unknown";
+        const error = new FerricStoreError(`unknown native pipeline status ${JSON.stringify(unknown)}`, {
+          raw: item,
+          retryable: false,
+          safeToRetry: false
+        });
+        if (options.throwOnItemError !== false) throw error;
+        out[index] = error;
+        continue;
+      }
     }
     out[index] = item;
   }
   return out;
 }
 function pipelineStatus(value) {
+  const status = pipelineStatusToken(value);
+  if (status == null) return null;
+  return status === "ok" || status === "error" || status === "auth" || status === "noperm" || status === "busy" || status === "reroute" || status === "bad_request" ? status : null;
+}
+function pipelineStatusToken(value) {
   if (typeof value !== "string" && !Buffer26.isBuffer(value) && !(value instanceof Uint8Array)) return null;
-  const status = asText(value).toLowerCase();
-  return status === "ok" || status === "busy" || status === "error" ? status : null;
+  return asText(value).toLowerCase();
+}
+function pipelineStatusCode(status) {
+  switch (status) {
+    case "error":
+      return 1;
+    case "auth":
+      return 2;
+    case "noperm":
+      return 3;
+    case "busy":
+      return 4;
+    case "reroute":
+      return 5;
+    case "bad_request":
+      return 6;
+  }
 }
 function decodeResponseValue(opcode, body, hints, allowCompact, customPayload) {
   if (customPayload && allowCompact) {
@@ -8225,6 +8288,22 @@ function plainRecord(value) {
   return value;
 }
 
+// src/native-command-preparation.ts
+function prepareNativeCommand(args, maxFrameBytes) {
+  try {
+    return buildProtocolCommand(args, maxFrameBytes);
+  } catch (error) {
+    throw requestNotSentError(error);
+  }
+}
+function encodeNativeRequest(command, requestId, maxFrameBytes) {
+  try {
+    return encodeRequest(command, requestId, maxFrameBytes);
+  } catch (error) {
+    throw requestNotSentError(error);
+  }
+}
+
 // src/native-adapter.ts
 var NativeAdapter = class _NativeAdapter {
   socket;
@@ -8332,15 +8411,13 @@ var NativeAdapter = class _NativeAdapter {
     return await this.executeCommandArgs(args);
   }
   async executeCommandArgs(args) {
-    const command = buildProtocolCommand(args, this.capabilities.requestFrameBytes);
+    const command = prepareNativeCommand(args, this.capabilities.requestFrameBytes);
     return await this.request(command);
   }
   /** @internal Execute raw command arguments on a topology-selected lane. */
   async executeCommandOnLane(args, laneId) {
-    return await this.executeProtocolCommand(
-      buildProtocolCommand(args, this.capabilities.requestFrameBytes),
-      laneId
-    );
+    const command = prepareNativeCommand(args, this.capabilities.requestFrameBytes);
+    return await this.executeProtocolCommand(command, laneId);
   }
   async executeProtocolCommand(command, laneId) {
     return await this.request(laneId == null ? command : { ...command, laneId });
@@ -8434,14 +8511,14 @@ var NativeAdapter = class _NativeAdapter {
     let frame;
     try {
       requestId = this.requestScheduler.nextRequestId();
-      frame = encodeRequest(
+      frame = encodeNativeRequest(
         withFlowQueryDeadline(command, timeoutMs),
         requestId,
         this.capabilities.requestFrameBytes
       );
     } catch (error) {
       if (hasFlowControlCredit) this.flowControl.release(laneId);
-      return Promise.reject(error instanceof Error ? error : new FerricStoreError(String(error), { raw: error }));
+      return Promise.reject(error instanceof Error ? error : requestNotSentError(error));
     }
     return new Promise((resolve, reject) => {
       const timer = timeoutMs == null ? void 0 : setLongTimeout(() => {
@@ -9016,12 +9093,16 @@ var HTTPTransport = class {
   #requests = /* @__PURE__ */ new Set();
   #closed = false;
   async post(body, timeoutMs) {
-    if (this.#closed) throw new HTTPTransportError("HTTP transport is closed");
+    if (this.#closed) {
+      throw new HTTPTransportError("HTTP transport is closed", { requestDisposition: "unsent" });
+    }
     const controller = new AbortController();
     this.#requests.add(controller);
     const timer = timeoutMs == null ? void 0 : setLongTimeout(() => controller.abort(requestTimeoutReason), timeoutMs);
     timer?.unref();
     try {
+      const response = await this.request(this.config.commandUrl, "POST", body, 0, controller.signal);
+      if (response.status !== 401 || this.config.headers.authorization == null) return response;
       return await this.request(this.config.commandUrl, "POST", body, 0, controller.signal);
     } catch (error) {
       if (controller.signal.aborted) {
@@ -9031,9 +9112,22 @@ var HTTPTransport = class {
           raw: { retryable: true, safe_to_retry: false }
         });
       }
-      if (error instanceof HTTPTransportError || error instanceof RequestTimeoutError) throw error;
+      if (error instanceof RequestTimeoutError) throw error;
+      if (error instanceof HTTPTransportError) {
+        if (error.requestDisposition != null) throw error;
+        throw new HTTPTransportError(error.message, {
+          cause: error.cause ?? error,
+          raw: error.raw,
+          requestDisposition: "possibly_sent",
+          retryAfterMs: error.retryAfterMs,
+          retryable: error.retryable,
+          safeToRetry: false,
+          statusCode: error.statusCode
+        });
+      }
       throw new HTTPTransportError("HTTP command request failed", {
         cause: error,
+        requestDisposition: "possibly_sent",
         retryable: true,
         safeToRetry: false
       });
@@ -9045,7 +9139,9 @@ var HTTPTransport = class {
   async close() {
     if (this.#closed) return;
     this.#closed = true;
-    const error = new HTTPTransportError("HTTP transport is closed");
+    const error = new HTTPTransportError("HTTP transport is closed", {
+      requestDisposition: "possibly_sent"
+    });
     for (const controller of this.#requests) controller.abort(error);
     this.#httpAgent.destroy();
     this.#httpsAgent.destroy();
@@ -9288,16 +9384,22 @@ var HTTPAdapter = class _HTTPAdapter {
     await this.#transport.close();
   }
   async executeBatch(commands) {
-    if (commands.length > this.#config.maxBatchItems) {
-      throw new HTTPTransportError("HTTP command batch exceeds maxBatchItems");
-    }
-    for (const command of commands) assertHTTPCommandSupported(command[0]);
-    const prepared = commands.map((command) => prepareHTTPCommand(command, this.#config.maxRequestBytes));
-    const body = encodeHTTPCommands(prepared.map((command) => command.encoded), this.#config.maxRequestBytes);
-    if (body.byteLength > this.#config.maxRequestBytes) {
-      throw new HTTPTransportError("HTTP command request exceeds maxRequestBytes");
+    let body;
+    let serverBlockMs;
+    try {
+      if (commands.length > this.#config.maxBatchItems) {
+        throw new HTTPTransportError("HTTP command batch exceeds maxBatchItems");
+      }
+      for (const command of commands) assertHTTPCommandSupported(command[0]);
+      const prepared = commands.map((command) => prepareHTTPCommand(command, this.#config.maxRequestBytes));
+      body = encodeHTTPCommands(prepared.map((command) => command.encoded), this.#config.maxRequestBytes);
+      if (body.byteLength > this.#config.maxRequestBytes) {
+        throw new HTTPTransportError("HTTP command request exceeds maxRequestBytes");
+      }
+      serverBlockMs = combinedServerBlockMs(prepared.map((command) => command.serverBlockMs));
+    } catch (error) {
+      throw unsentHTTPError(error);
     }
-    const serverBlockMs = combinedServerBlockMs(prepared.map((command) => command.serverBlockMs));
     const response = await this.#transport.post(
       body,
       serverResponseTimeoutMs(this.#config.timeoutMs, serverBlockMs)
@@ -9354,16 +9456,32 @@ function commandError(value) {
 }
 function topLevelError(status, envelope, retryAfter) {
   const details = isRecord2(envelope.error) ? envelope.error : {};
+  const code = typeof details.code === "string" ? details.code.toLowerCase() : void 0;
   const message = typeof details.message === "string" ? details.message : `HTTP command request failed with status ${status}`;
   const retryAfterMs2 = retryAfterMilliseconds(retryAfter);
+  const ambiguousTimeout = status === 408 || code === "request_timeout";
+  const safeToRetry = !ambiguousTimeout && (details.safe_to_retry === true || definitelyRejectedHTTPStatus(status));
   return new HTTPTransportError(message, {
     raw: details,
     retryable: status === 408 || status === 425 || status === 429 || status >= 500,
     retryAfterMs: retryAfterMs2,
-    safeToRetry: false,
+    requestDisposition: "possibly_sent",
+    safeToRetry,
     statusCode: status
   });
 }
+function definitelyRejectedHTTPStatus(status) {
+  return status === 400 || status === 401 || status === 403 || status === 404 || status === 405 || status === 406 || status === 411 || status === 413 || status === 414 || status === 415 || status === 422 || status === 426 || status === 431;
+}
+function unsentHTTPError(error) {
+  if (error instanceof HTTPTransportError && error.requestDisposition === "unsent") return error;
+  const message = error instanceof Error ? error.message : String(error);
+  return new HTTPTransportError(message, {
+    cause: error,
+    raw: error instanceof FerricStoreError ? error.raw ?? error : error,
+    requestDisposition: "unsent"
+  });
+}
 function retryAfterMilliseconds(value) {
   if (value == null) return void 0;
   if (/^\d+$/u.test(value)) {
@@ -9456,9 +9574,9 @@ var ReconnectingExecutor = class {
     const snapshot = snapshotPipelineCommands(commands);
     const snapshotOptions = snapshotPipelineOptions(options) ?? {};
     for (const command of snapshot) assertCommandHasStableConnectionState(command);
-    if (this.closed) throw new FerricStoreError("FerricStore client is closed");
+    if (this.closed) throw new RequestNotSentError("FerricStore client is closed");
     const initialExecutor = await this.executorPromise;
-    if (this.closed) throw new FerricStoreError("FerricStore client is closed");
+    if (this.closed) throw new RequestNotSentError("FerricStore client is closed");
     if (initialExecutor.executePipeline == null) {
       return await executeCommandArraysIndividually(
         async (command) => await this.executeCommandArgs(command),
@@ -9479,9 +9597,9 @@ var ReconnectingExecutor = class {
     const snapshot = snapshotPipelineCommands(commands);
     const snapshotOptions = snapshotPipelineOptions(options) ?? {};
     for (const command of snapshot) assertCommandHasStableConnectionState(command);
-    if (this.closed) throw new FerricStoreError("FerricStore client is closed");
+    if (this.closed) throw new RequestNotSentError("FerricStore client is closed");
     const initialExecutor = await this.executorPromise;
-    if (this.closed) throw new FerricStoreError("FerricStore client is closed");
+    if (this.closed) throw new RequestNotSentError("FerricStore client is closed");
     if (initialExecutor.executeFusedPipeline == null) return void 0;
     try {
       return await initialExecutor.executeFusedPipeline(snapshot, snapshotOptions);
@@ -9514,7 +9632,7 @@ var ReconnectingExecutor = class {
       return;
     }
     this.closed = true;
-    this.retryAbortController.abort(new FerricStoreError("FerricStore client is closed"));
+    this.retryAbortController.abort(new RequestNotSentError("FerricStore client is closed"));
     const executorPromise = this.executorPromise;
     const reconnectPromise = this.reconnectPromise;
     this.closePromise = (async () => {
@@ -9536,7 +9654,7 @@ var ReconnectingExecutor = class {
     let executor = await this.executorPromise;
     let retries = 0;
     for (; ; ) {
-      if (this.closed) throw new FerricStoreError("FerricStore client is closed");
+      if (this.closed) throw new RequestNotSentError("FerricStore client is closed");
       try {
         return await operation(executor);
       } catch (error) {
@@ -9565,17 +9683,17 @@ var ReconnectingExecutor = class {
     try {
       await sleep(Math.min(this.maxDelayMs, base + jitter), this.retryAbortController.signal);
     } catch (error) {
-      if (this.closed) throw new FerricStoreError("FerricStore client is closed", { cause: error });
+      if (this.closed) throw new RequestNotSentError("FerricStore client is closed", { cause: error });
       throw error;
     }
   }
   async reconnect(staleExecutor) {
-    if (this.closed) throw new FerricStoreError("FerricStore client is closed");
+    if (this.closed) throw new RequestNotSentError("FerricStore client is closed");
     const competingReconnect = this.reconnectPromise;
     if (competingReconnect != null) return await competingReconnect;
     const observedExecutorPromise = this.executorPromise;
     const currentExecutor = await observedExecutorPromise.catch(() => void 0);
-    if (this.closed) throw new FerricStoreError("FerricStore client is closed");
+    if (this.closed) throw new RequestNotSentError("FerricStore client is closed");
     if (this.reconnectPromise != null) return await this.reconnectPromise;
     if (this.executorPromise !== observedExecutorPromise) return await this.executorPromise;
     if (currentExecutor != null && currentExecutor !== staleExecutor) return currentExecutor;
@@ -9584,7 +9702,7 @@ var ReconnectingExecutor = class {
       const nextExecutor = await this.createExecutor(this.retryAbortController.signal);
       if (this.closed) {
         await Promise.resolve(nextExecutor.close?.()).catch(() => void 0);
-        throw new FerricStoreError("FerricStore client is closed");
+        throw new RequestNotSentError("FerricStore client is closed");
       }
       this.executorPromise = Promise.resolve(nextExecutor);
       return nextExecutor;
@@ -10994,7 +11112,7 @@ var TopologyNativeAdapterPool = class _TopologyNativeAdapterPool {
     );
   }
   assertOpen() {
-    if (this.closed) throw new FerricStoreError("FerricStore topology adapter pool is closed");
+    if (this.closed) throw new RequestNotSentError("FerricStore topology adapter pool is closed");
   }
 };
 
@@ -12120,7 +12238,7 @@ var AutoBatchExecutor = class {
   }
   async executeCommandArgs(args) {
     if (this.closed) {
-      throw new FerricStoreError("FerricStore client is closed");
+      throw new RequestNotSentError("FerricStore client is closed");
     }
     const command = snapshotCommandArguments(args);
     if (this.executor.executePipeline == null) {
@@ -12140,7 +12258,7 @@ var AutoBatchExecutor = class {
     if (orderingBarrier != null) {
       await orderingBarrier;
       if (this.closed) {
-        throw new FerricStoreError("FerricStore client is closed");
+        throw new RequestNotSentError("FerricStore client is closed");
       }
     }
     return await new Promise((resolve, reject) => {
@@ -12154,7 +12272,7 @@ var AutoBatchExecutor = class {
   }
   async executePipeline(commands, options) {
     if (this.closed) {
-      throw new FerricStoreError("FerricStore client is closed");
+      throw new RequestNotSentError("FerricStore client is closed");
     }
     const snapshot = snapshotPipelineCommands(commands);
     const snapshotOptions = snapshotPipelineOptions(options);
@@ -12171,7 +12289,7 @@ var AutoBatchExecutor = class {
   }
   async executeFusedPipeline(commands, options) {
     if (this.closed) {
-      throw new FerricStoreError("FerricStore client is closed");
+      throw new RequestNotSentError("FerricStore client is closed");
     }
     if (this.executor.executeFusedPipeline == null) return void 0;
     const snapshot = snapshotPipelineCommands(commands);
@@ -12182,7 +12300,7 @@ var AutoBatchExecutor = class {
   }
   async refreshTopology() {
     if (this.closed) {
-      throw new FerricStoreError("FerricStore client is closed");
+      throw new RequestNotSentError("FerricStore client is closed");
     }
     const refreshTopology = this.executor.refreshTopology?.bind(this.executor);
     if (refreshTopology == null) {
@@ -12192,7 +12310,7 @@ var AutoBatchExecutor = class {
   }
   async route(key) {
     if (this.closed) {
-      throw new FerricStoreError("FerricStore client is closed");
+      throw new RequestNotSentError("FerricStore client is closed");
     }
     const route = this.executor.route?.bind(this.executor);
     if (route == null) {
@@ -12212,7 +12330,7 @@ var AutoBatchExecutor = class {
         this.timer.cancel();
         this.timer = void 0;
       }
-      this.failPending(new Error("FerricStore client closed before auto-batch flush"));
+      this.failPending(new RequestNotSentError("FerricStore client closed before auto-batch flush"));
       await this.orderingBarrier;
       await this.waitForInFlightBatches();
       await Promise.allSettled([...this.inFlightHelpers]);
@@ -12222,7 +12340,7 @@ var AutoBatchExecutor = class {
   }
   async executeAfterPendingBatches(operation) {
     if (this.closed) {
-      throw new FerricStoreError("FerricStore client is closed");
+      throw new RequestNotSentError("FerricStore client is closed");
     }
     const previousBarrier = this.orderingBarrier;
     let releaseBarrier;
@@ -12243,7 +12361,7 @@ var AutoBatchExecutor = class {
   }
   executeHelper(operation) {
     if (this.closed) {
-      return Promise.reject(new FerricStoreError("FerricStore client is closed"));
+      return Promise.reject(new RequestNotSentError("FerricStore client is closed"));
     }
     const task = Promise.resolve().then(operation);
     this.inFlightHelpers.add(task);
@@ -12265,7 +12383,7 @@ var AutoBatchExecutor = class {
       await previousBarrier;
       await this.flushNow();
       if (this.closed) {
-        throw new FerricStoreError("FerricStore client is closed");
+        throw new RequestNotSentError("FerricStore client is closed");
       }
       dispatched = operation();
     } finally {
@@ -14604,7 +14722,7 @@ var FerricStoreClientBase = class {
     return validatePipelineResponse(results, snapshot.length);
   }
   async close() {
-    this.closeAbortController.abort(new FerricStoreError("FerricStore client is closed"));
+    this.closeAbortController.abort(new RequestNotSentError("FerricStore client is closed"));
     this.closePromise ??= (async () => await this.executor.close?.())();
     await this.closePromise;
   }
@@ -17680,7 +17798,7 @@ async function executeProducerWriteWithBackpressure(execute, policy, signal) {
 function throwIfClosed(signal) {
   if (!signal.aborted) return;
   if (signal.reason instanceof Error) throw signal.reason;
-  throw new FerricStoreError("FerricStore client is closed", { raw: signal.reason });
+  throw new RequestNotSentError("FerricStore client is closed", { raw: signal.reason });
 }
 
 // src/flow-policy.ts
@@ -18498,12 +18616,20 @@ var FerricStoreClaimClient = class extends FerricStoreMutationClient {
     return this.records(items);
   }
   async claimJobs(type, options) {
-    return await this.claimDue(type, {
+    const requestedState = options.state;
+    const includeState = options.includeState ?? requestedState == null;
+    const jobs = await this.claimDue(type, {
       ...options,
-      includeState: options.includeState ?? false,
+      includeState,
       jobOnly: true,
       limit: options.limit ?? 100
     });
+    if (!includeState && requestedState != null) {
+      for (const job of jobs) {
+        if (job[CLAIMED_ITEM_WIRE] != null) job.runState ??= requestedState;
+      }
+    }
+    return jobs;
   }
   async reclaim(type, options) {
     const captured = snapshotClaimOptions(options);
@@ -18526,7 +18652,7 @@ var FerricStoreClaimClient = class extends FerricStoreMutationClient {
     this.appendPartitionOptions(args, captured);
     append(args, "PRIORITY", captured.priority);
     if (jobOnly) {
-      append(args, "RETURN", compactClaimReturnMode2(false, captured.includeAttributes === true));
+      append(args, "RETURN", compactClaimReturnMode2(true, captured.includeAttributes === true));
     }
     appendPayloadRead(args, captured.payload, captured.payloadMaxBytes);
     appendValueReturn(args, { values: captured.values, valueMaxBytes: captured.valueMaxBytes });
@@ -18907,6 +19033,291 @@ var FerricStoreProducerClient = class extends FerricStoreClaimClient {
   }
 };
 
+// src/client-durable-step.ts
+import { createHash as createHash2 } from "crypto";
+
+// src/workflow-utilities.ts
+function resolveWorkflowStates(configured, registrationFor) {
+  const stateNames = [...new Set(configured)];
+  if (stateNames.length === 0) throw new Error("Workflow worker requires at least one state");
+  return stateNames.map((stateName) => {
+    const registration = registrationFor(stateName);
+    if (registration == null) {
+      throw new Error(`No handler registered for workflow state '${stateName}'`);
+    }
+    return { registration, stateName };
+  });
+}
+function normalizeStateMode(mode) {
+  if (mode === "fifo" || mode === "parallel") return mode;
+  throw new Error("state mode must be 'fifo' or 'parallel'");
+}
+function valueRefToString(value) {
+  if (typeof value === "string") return value;
+  if (Buffer.isBuffer(value)) return value.toString("utf8");
+  if (typeof value === "object" && value != null && Object.hasOwn(value, "ref")) {
+    const ref = value.ref;
+    return typeof ref === "string" ? ref : Buffer.isBuffer(ref) ? ref.toString("utf8") : void 0;
+  }
+  return void 0;
+}
+
+// src/client-durable-step.ts
+var DURABLE_STEP_VALUE_PREFIX = "__ferricstore_step__:sha256:";
+function durableMutationMayHaveCommitted(error) {
+  if (error instanceof ConnectionClosedError || error instanceof RequestTimeoutError) {
+    return error.requestDisposition === "possibly_sent";
+  }
+  if (error instanceof HTTPTransportError) return error.safeToRetry !== true;
+  if (error instanceof FlowNotFoundError || error instanceof FlowWrongStateError || error instanceof InvalidCommandError || error instanceof StaleLeaseError) {
+    return false;
+  }
+  if (error instanceof FerricStoreError && error.safeToRetry === true) return false;
+  return true;
+}
+async function advanceClaim(client, job, options) {
+  assertDurableClaim(job);
+  assertNonEmptyString(options.toState, "toState");
+  const partitionKey = job.partitionKey === "" ? void 0 : job.partitionKey;
+  const response = await client.stepContinue(job.id, {
+    attributesDelete: options.attributesDelete,
+    attributesMerge: options.attributesMerge,
+    dropValues: options.dropValues,
+    fencingToken: job.fencingToken,
+    fromState: job.runState,
+    leaseMs: options.leaseMs,
+    leaseToken: job.leaseToken,
+    nowMs: options.nowMs,
+    overrideValues: options.overrideValues,
+    partitionKey,
+    payload: options.payload,
+    returnJob: true,
+    stateMeta: options.stateMeta,
+    type: job.type,
+    toState: options.toState,
+    valueRefs: options.valueRefs,
+    values: options.values
+  });
+  const refreshed = response;
+  if (refreshed[CLAIMED_ITEM_WIRE] != null) {
+    if (refreshed.runState != null && refreshed.runState !== options.toState) {
+      throw new FerricStoreError("compact continuation response returned the wrong runState");
+    }
+    refreshed.runState ??= options.toState;
+    if (refreshed.type == null && job.type != null) refreshed.type = job.type;
+  }
+  assertContinuationClaim(job, refreshed, options.toState);
+  return refreshed;
+}
+async function runDurableStep(client, job, options, hooks = {}) {
+  assertDurableClaim(job);
+  const name = options.name;
+  const run2 = options.run;
+  const continuation = snapshotAdvanceOptions(options);
+  assertNonEmptyString(name, "name");
+  if (name.trim().length === 0) throw new TypeError("name must not be blank");
+  if (!name.isWellFormed()) throw new TypeError("name must contain valid Unicode");
+  assertNonEmptyString(continuation.toState, "toState");
+  if (typeof run2 !== "function") throw new TypeError("run must be a function");
+  const resultName = durableStepValueName(name);
+  assertStepValueIsReserved(continuation, resultName);
+  const leaseMs = continuation.leaseMs ?? 3e4;
+  const partitionKey = job.partitionKey === "" ? void 0 : job.partitionKey;
+  const validated = await client.extendLease(job.id, {
+    fencingToken: job.fencingToken,
+    leaseMs,
+    leaseToken: job.leaseToken,
+    nowMs: continuation.nowMs,
+    partitionKey
+  });
+  assertValidatedLease(job, validated);
+  if (validated.valueRefs != null && Object.hasOwn(validated.valueRefs, resultName)) {
+    if (validated.runState !== continuation.toState) {
+      throw new FerricStoreError("committed durable step result does not match the requested target state");
+    }
+    const ref = valueRefToString(validated.valueRefs[resultName]);
+    if (ref == null) {
+      throw new FerricStoreError("committed durable step result has invalid reference metadata");
+    }
+    const entry = (await valueMGetEntries(client, [ref]))[0];
+    if (entry?.found !== true) {
+      throw new FerricStoreError("committed durable step result is missing");
+    }
+    const replayedJob = claimedItemFromRecord(validated);
+    notifyWithoutReplacingOutcome(hooks.replayed, replayedJob);
+    return { job: replayedJob, result: entry.value };
+  }
+  const result = normalizeStepResult(client, await run2());
+  await hooks.beforeCommit?.();
+  let refreshed;
+  try {
+    refreshed = await advanceClaim(client, validated, {
+      ...continuation,
+      leaseMs,
+      values: { ...continuation.values, [resultName]: result }
+    });
+  } catch (error) {
+    notifyWithoutReplacingOutcome(hooks.commitFailed, error);
+    throw error;
+  }
+  notifyWithoutReplacingOutcome(hooks.committed, refreshed);
+  return { job: refreshed, result };
+}
+function notifyWithoutReplacingOutcome(callback, value) {
+  try {
+    callback?.(value);
+  } catch {
+  }
+}
+function normalizeStepResult(client, value) {
+  return client.codec.decode(client.codec.encode(value));
+}
+function durableStepValueName(name) {
+  const digest = createHash2("sha256").update(name, "utf8").digest("hex");
+  return `${DURABLE_STEP_VALUE_PREFIX}${digest}`;
+}
+function snapshotAdvanceOptions(options) {
+  return {
+    ...options.attributesDelete == null ? {} : { attributesDelete: [...options.attributesDelete] },
+    ...options.attributesMerge == null ? {} : { attributesMerge: { ...options.attributesMerge } },
+    ...options.dropValues == null ? {} : { dropValues: [...options.dropValues] },
+    ...options.leaseMs == null ? {} : { leaseMs: options.leaseMs },
+    ...options.nowMs == null ? {} : { nowMs: options.nowMs },
+    ...options.overrideValues == null ? {} : { overrideValues: [...options.overrideValues] },
+    ...options.payload === void 0 ? {} : { payload: options.payload },
+    ...options.stateMeta == null ? {} : { stateMeta: { ...options.stateMeta } },
+    toState: options.toState,
+    ...options.valueRefs == null ? {} : { valueRefs: { ...options.valueRefs } },
+    ...options.values == null ? {} : { values: { ...options.values } }
+  };
+}
+function assertDurableClaim(job) {
+  if (typeof job !== "object" || job == null) throw new TypeError("job must be a claimed Flow");
+  assertNonEmptyString(job.id, "job.id");
+  assertNonEmptyString(job.runState, "job.runState");
+  if (!Buffer.isBuffer(job.leaseToken) || job.leaseToken.byteLength === 0) {
+    throw new TypeError("job.leaseToken must be a non-empty Buffer");
+  }
+  if ((typeof job.fencingToken !== "number" || !Number.isSafeInteger(job.fencingToken)) && typeof job.fencingToken !== "bigint") {
+    throw new TypeError("job.fencingToken must be an integer");
+  }
+  if (fencingValue(job.fencingToken) <= 0n) {
+    throw new TypeError("job.fencingToken must be a positive integer");
+  }
+  if (job.state !== "running") {
+    throw new TypeError("job.state must be running");
+  }
+}
+function assertValidatedLease(expected, actual) {
+  try {
+    assertDurableClaim(actual);
+  } catch (error) {
+    throw new FerricStoreError("lease validation returned an invalid claim", { cause: error });
+  }
+  if (actual.id !== expected.id) throw leaseValidationMismatch("id");
+  if (normalizedPartition(actual.partitionKey) !== normalizedPartition(expected.partitionKey)) {
+    throw leaseValidationMismatch("partition");
+  }
+  if (!actual.leaseToken.equals(expected.leaseToken)) throw leaseValidationMismatch("lease token");
+  if (fencingValue(actual.fencingToken) !== fencingValue(expected.fencingToken)) {
+    throw leaseValidationMismatch("fencing token");
+  }
+  if (actual.state !== expected.state) throw leaseValidationMismatch("physical state");
+  if (actual.runState !== expected.runState) throw leaseValidationMismatch("runState");
+}
+function assertContinuationClaim(previous, refreshed, toState) {
+  try {
+    assertDurableClaim(refreshed);
+  } catch (error) {
+    throw new FerricStoreError("continuation response returned an invalid claim", { cause: error });
+  }
+  if (refreshed.id !== previous.id) throw continuationMismatch("id");
+  if (normalizedPartition(refreshed.partitionKey) !== normalizedPartition(previous.partitionKey)) {
+    throw continuationMismatch("partition");
+  }
+  if (refreshed.leaseToken.equals(previous.leaseToken)) {
+    throw continuationMismatch("lease token did not change");
+  }
+  if (fencingValue(refreshed.fencingToken) <= fencingValue(previous.fencingToken)) {
+    throw continuationMismatch("fencing token did not increase");
+  }
+  if (refreshed.state !== "running") throw continuationMismatch("physical state");
+  if (refreshed.runState !== toState) throw continuationMismatch("runState");
+}
+function leaseValidationMismatch(field3) {
+  return new FerricStoreError(`lease validation returned a mismatched ${field3}`);
+}
+function continuationMismatch(field3) {
+  return new FerricStoreError(`continuation response returned a mismatched ${field3}`);
+}
+function normalizedPartition(value) {
+  return value == null || value === "" ? void 0 : value;
+}
+function fencingValue(value) {
+  return typeof value === "bigint" ? value : BigInt(value);
+}
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${name} must be a non-empty string`);
+  }
+}
+function assertStepValueIsReserved(options, resultName) {
+  if (options.values != null && Object.hasOwn(options.values, resultName)) {
+    throw new TypeError("values cannot mutate the reserved durable step result");
+  }
+  if (options.valueRefs != null && Object.hasOwn(options.valueRefs, resultName)) {
+    throw new TypeError("valueRefs cannot mutate the reserved durable step result");
+  }
+  if (options.dropValues?.includes(resultName) === true) {
+    throw new TypeError("dropValues cannot mutate the reserved durable step result");
+  }
+  if (options.overrideValues?.includes(resultName) === true) {
+    throw new TypeError("overrideValues cannot mutate the reserved durable step result");
+  }
+}
+function claimedItemFromRecord(record) {
+  return {
+    ...record.attributes == null ? {} : { attributes: record.attributes },
+    fencingToken: record.fencingToken,
+    id: record.id,
+    leaseToken: Buffer.from(record.leaseToken),
+    ...record.partitionKey === "" ? {} : { partitionKey: record.partitionKey },
+    ...record.payload === void 0 ? {} : { payload: record.payload },
+    ...record.runState == null ? {} : { runState: record.runState },
+    state: record.state,
+    type: record.type
+  };
+}
+
+// src/client-step-continue.ts
+function stepContinueArguments(id, options, codec) {
+  try {
+    const args = [
+      "FLOW.STEP_CONTINUE",
+      id,
+      options.leaseToken,
+      options.fromState,
+      options.toState,
+      "FENCING",
+      options.fencingToken,
+      "LEASE_MS",
+      options.leaseMs ?? 3e4,
+      "NOW",
+      options.nowMs ?? nowMs()
+    ];
+    append(args, "PARTITION", options.partitionKey);
+    append(args, "WORKER", options.worker);
+    appendEncoded(args, "PAYLOAD", codec, options.payload);
+    if (options.returnJob === true) args.push("RETURN", "JOBS_COMPACT");
+    appendStateMeta(args, options.stateMeta);
+    appendNamedValues(args, codec, options);
+    appendAttributeMutations(args, options);
+    return args;
+  } catch (error) {
+    throw requestNotSentError(error);
+  }
+}
+
 // src/client.ts
 var FerricStoreClient = class _FerricStoreClient extends FerricStoreProducerClient {
   static async fromUrl(url, options = {}) {
@@ -19021,33 +19432,30 @@ var FerricStoreClient = class _FerricStoreClient extends FerricStoreProducerClie
     appendNamedValues(args, this.codec, options);
     return await this.recordOrGet(await this.commandArgs(args), id, partitionKey);
   }
+  /**
+   * @deprecated Low-level compatibility API. Use {@link advance} for state-only
+   * continuation or {@link step} for a durable closure.
+   */
   async stepContinue(id, options) {
     const partitionKey = options.partitionKey;
     const returnJob = options.returnJob === true;
     const type = options.type;
-    const args = [
-      "FLOW.STEP_CONTINUE",
-      id,
-      options.leaseToken,
-      options.fromState,
-      options.toState,
-      "FENCING",
-      options.fencingToken,
-      "LEASE_MS",
-      options.leaseMs ?? 3e4,
-      "NOW",
-      options.nowMs ?? nowMs()
-    ];
-    append(args, "PARTITION", partitionKey);
-    append(args, "WORKER", options.worker);
-    appendEncoded(args, "PAYLOAD", this.codec, options.payload);
-    if (returnJob) args.push("RETURN", "JOBS_COMPACT");
-    appendStateMeta(args, options.stateMeta);
-    appendNamedValues(args, this.codec, options);
-    appendAttributeMutations(args, options);
+    const args = stepContinueArguments(id, options, this.codec);
     const response = await this.commandArgs(args);
     return returnJob ? claimedItemFromResp(response, this.codec, { type }) : await this.recordOrGet(response, id, partitionKey);
   }
+  /** Advance a claimed Flow and return its renewed claim. */
+  async advance(job, options) {
+    return await advanceClaim(this, job, options);
+  }
+  /**
+   * Run a closure after validating the claim, then atomically journal its
+   * result and advance the Flow. A committed result is replayed without
+   * invoking the closure again.
+   */
+  async step(job, options) {
+    return await runDurableStep(this, job, options);
+  }
   async runStepsMany(items, options) {
     if (items.length === 0) return Buffer.from("OK");
     const hasStates = options.states != null;
@@ -19297,6 +19705,8 @@ function validateUnicodeScalarText2(value) {
 
 // src/outcomes.ts
 var OUTCOME_BRAND = /* @__PURE__ */ Symbol("ferricstore.outcome");
+var ALREADY_APPLIED_BRAND = /* @__PURE__ */ Symbol("ferricstore.alreadyApplied");
+var REPLAYED_STEP_BRAND = /* @__PURE__ */ Symbol("ferricstore.replayedStep");
 function transition(toState, options = {}) {
   return brandOutcome({ ...options, kind: "transition", toState });
 }
@@ -19309,6 +19719,22 @@ function retry(options = {}) {
 function fail2(options = {}) {
   return brandOutcome({ ...options, kind: "fail" });
 }
+function alreadyApplied(job) {
+  return brandAlreadyApplied({ job, kind: "already_applied" });
+}
+function appliedStep(job, result) {
+  return brandAlreadyApplied({ applied: true, job, kind: "already_applied", result });
+}
+function replayedStep(job, result) {
+  const replayed = { applied: false, job, result };
+  Object.defineProperty(replayed, REPLAYED_STEP_BRAND, {
+    configurable: false,
+    enumerable: false,
+    value: true,
+    writable: false
+  });
+  return replayed;
+}
 function isOutcome(value) {
   if (typeof value !== "object" || value == null || !Object.hasOwn(value, OUTCOME_BRAND) || value[OUTCOME_BRAND] !== true) {
     return false;
@@ -19319,6 +19745,12 @@ function isOutcome(value) {
   }
   return outcome.kind === "complete" || outcome.kind === "retry" || outcome.kind === "fail";
 }
+function isAlreadyAppliedOutcome(value) {
+  return typeof value === "object" && value != null && Object.hasOwn(value, ALREADY_APPLIED_BRAND) && value[ALREADY_APPLIED_BRAND] === true && value.kind === "already_applied";
+}
+function isReplayedStepResult(value) {
+  return typeof value === "object" && value != null && Object.hasOwn(value, REPLAYED_STEP_BRAND) && value[REPLAYED_STEP_BRAND] === true && value.applied === false;
+}
 function brandOutcome(outcome) {
   Object.defineProperty(outcome, "kind", {
     configurable: false,
@@ -19342,6 +19774,21 @@ function brandOutcome(outcome) {
   });
   return outcome;
 }
+function brandAlreadyApplied(outcome) {
+  Object.defineProperty(outcome, "kind", {
+    configurable: false,
+    enumerable: true,
+    value: "already_applied",
+    writable: false
+  });
+  Object.defineProperty(outcome, ALREADY_APPLIED_BRAND, {
+    configurable: false,
+    enumerable: false,
+    value: true,
+    writable: false
+  });
+  return outcome;
+}
 
 // src/worker-config.ts
 function snapshotWorkerConfig(options) {
@@ -19358,8 +19805,7 @@ function snapshotWorkerConfig(options) {
   return Object.freeze(snapshot);
 }
 
-// src/worker-internal.ts
-var DEFAULT_FLOW_MANY_BATCH_LIMIT2 = 1e3;
+// src/worker-lease-guard.ts
 var LeaseRenewalError = class extends Error {
   constructor(cause) {
     super("FerricStore lease renewal failed", { cause });
@@ -19370,37 +19816,58 @@ var LeaseRenewalGuard = class {
   constructor(client, leasedJob, leaseMs, options) {
     this.client = client;
     this.leaseMs = leaseMs;
-    this.job = snapshotLeasedJob(leasedJob);
-    if (options.leaseRenewal === false) {
-      return;
-    }
-    const intervalMs = positiveInteger4(options.leaseRenewIntervalMs, Math.max(1, Math.trunc(leaseMs / 2)));
-    this.timer = setLongInterval(() => this.renew(), intervalMs);
-    this.timer.unref();
+    this.currentJob = snapshotLeasedJob(leasedJob);
+    this.renewalEnabled = options.leaseRenewal !== false;
+    this.intervalMs = positiveInteger4(options.leaseRenewIntervalMs, Math.max(1, Math.trunc(leaseMs / 2)));
+    this.startRenewal();
   }
   client;
   leaseMs;
   error;
   inFlight;
-  job;
+  currentJob;
+  intervalMs;
+  renewalEnabled;
+  state = "active";
   timer;
+  get job() {
+    return this.currentJob;
+  }
   assertActive() {
-    if (this.error != null) {
-      throw this.error;
-    }
+    if (this.error != null) throw this.error;
   }
   async stop() {
-    if (this.timer != null) {
-      this.timer.cancel();
-      this.timer = void 0;
-    }
+    this.state = "stopped";
+    this.cancelRenewal();
+    await this.inFlight;
+    this.assertActive();
+  }
+  async pauseForLeaseMutation() {
+    if (this.state === "stopped") throw new Error("lease renewal guard is stopped");
+    if (this.state === "paused") return;
+    this.state = "paused";
+    this.cancelRenewal();
     await this.inFlight;
     this.assertActive();
   }
+  resumeWith(job) {
+    if (this.state !== "paused") throw new Error("lease renewal guard is not paused");
+    this.currentJob = snapshotLeasedJob(job);
+    this.state = "active";
+    this.startRenewal();
+  }
+  cancelRenewal() {
+    if (this.timer == null) return;
+    this.timer.cancel();
+    this.timer = void 0;
+  }
+  startRenewal() {
+    if (!this.renewalEnabled || this.state !== "active") return;
+    this.timer = setLongInterval(() => this.renew(), this.intervalMs);
+    this.timer.unref();
+  }
   renew() {
-    if (this.error != null || this.inFlight != null) {
-      return;
-    }
+    if (this.state !== "active" || this.error != null || this.inFlight != null) return;
     const renewal = this.client.extendLease(this.job.id, {
       fencingToken: this.job.fencingToken,
       leaseMs: this.leaseMs,
@@ -19411,17 +19878,12 @@ var LeaseRenewalGuard = class {
       () => void 0,
       (error) => {
         this.error = new LeaseRenewalError(error);
-        if (this.timer != null) {
-          this.timer.cancel();
-          this.timer = void 0;
-        }
+        this.cancelRenewal();
       }
     );
     this.inFlight = renewal;
     void renewal.finally(() => {
-      if (this.inFlight === renewal) {
-        this.inFlight = void 0;
-      }
+      if (this.inFlight === renewal) this.inFlight = void 0;
     });
   }
 };
@@ -19445,8 +19907,14 @@ function snapshotLeasedJob(job) {
   }
   return snapshot;
 }
+function positiveInteger4(value, fallback) {
+  return value == null || !Number.isFinite(value) ? fallback : Math.max(1, Math.trunc(value));
+}
+
+// src/worker-internal.ts
+var DEFAULT_FLOW_MANY_BATCH_LIMIT2 = 1e3;
 function workerConcurrency(options) {
-  return positiveInteger4(options.concurrency ?? options.workers, 1);
+  return positiveInteger5(options.concurrency ?? options.workers, 1);
 }
 function workerRefillStrategy(options) {
   return options.refillStrategy === "wave" ? "wave" : "continuous";
@@ -19489,18 +19957,18 @@ function workerErrorPayload(error, options, codec) {
 }
 function workerBatchSize(options, flowManyBatchLimit = DEFAULT_FLOW_MANY_BATCH_LIMIT2) {
   return Math.min(
-    positiveInteger4(options.batchSize, 10),
-    positiveInteger4(flowManyBatchLimit, DEFAULT_FLOW_MANY_BATCH_LIMIT2)
+    positiveInteger5(options.batchSize, 10),
+    positiveInteger5(flowManyBatchLimit, DEFAULT_FLOW_MANY_BATCH_LIMIT2)
   );
 }
 function workerClaimLimit(options, flowManyBatchLimit = DEFAULT_FLOW_MANY_BATCH_LIMIT2) {
   return Math.min(workerBatchSize(options, flowManyBatchLimit), workerConcurrency(options));
 }
 function workerDrainBatches(options) {
-  return positiveInteger4(options.claimDrainBatches, 1);
+  return positiveInteger5(options.claimDrainBatches, 1);
 }
 function workerLeaseMs(options, fallback = 3e4) {
-  return positiveInteger4(options.leaseMs, positiveInteger4(fallback, 3e4));
+  return positiveInteger5(options.leaseMs, positiveInteger5(fallback, 3e4));
 }
 function workerIdleSleepMs(options) {
   return nonNegativeDuration(options.idleSleepMs, 250);
@@ -19512,7 +19980,7 @@ function workerClaimBlockMs(options, useBlocking) {
   if (options.signal == null || !Number.isFinite(options.blockMs) || options.blockMs < 0) {
     return options.blockMs;
   }
-  const abortPollMs = positiveInteger4(options.abortPollMs, 1e3);
+  const abortPollMs = positiveInteger5(options.abortPollMs, 1e3);
   return options.blockMs === 0 ? abortPollMs : Math.min(Math.trunc(options.blockMs), abortPollMs);
 }
 function workerMaxIdleSleepMs(options, idleSleepMs = workerIdleSleepMs(options)) {
@@ -19523,8 +19991,8 @@ function nextWorkerIdleSleepMs(currentIdleSleepMs, maxIdleSleepMs) {
   return Math.min(maxIdleSleepMs, Math.max(1, currentIdleSleepMs * 2));
 }
 async function runContinuousWorkerPool(options) {
-  const concurrency = positiveInteger4(options.concurrency, 1);
-  const maxClaimSize = positiveInteger4(options.maxClaimSize, concurrency);
+  const concurrency = positiveInteger5(options.concurrency, 1);
+  const maxClaimSize = positiveInteger5(options.maxClaimSize, concurrency);
   const initialIdleSleepMs = nonNegativeDuration(options.idleSleepMs, 250);
   const maxIdleSleepMs = Math.max(
     initialIdleSleepMs,
@@ -19646,7 +20114,7 @@ function normalizeWorkflowWorkerConfig(options) {
     ...captured
   });
 }
-function positiveInteger4(value, fallback) {
+function positiveInteger5(value, fallback) {
   return value == null || !Number.isFinite(value) ? fallback : Math.max(1, Math.trunc(value));
 }
 function nonNegativeInteger5(value, fallback) {
@@ -20588,51 +21056,57 @@ var Queue = class {
 // src/workflow.ts
 import { randomUUID as randomUUID2 } from "crypto";
 
-// src/workflow-utilities.ts
-function resolveWorkflowStates(configured, registrationFor) {
-  const stateNames = [...new Set(configured)];
-  if (stateNames.length === 0) throw new Error("Workflow worker requires at least one state");
-  return stateNames.map((stateName) => {
-    const registration = registrationFor(stateName);
-    if (registration == null) {
-      throw new Error(`No handler registered for workflow state '${stateName}'`);
-    }
-    return { registration, stateName };
+// src/workflow-registration.ts
+function createWorkflowStateRegistration(name, handler, options, defaultValueMaxBytes) {
+  const own2 = { ...options };
+  const claimValues = own2.claimValues == null ? void 0 : snapshotOwnStringArray(own2.claimValues, "claimValues");
+  const retryPolicy = own2.retryPolicy == null ? void 0 : Object.freeze({ ...own2.retryPolicy });
+  return Object.freeze({
+    claimPayload: own2.claimPayload ?? true,
+    claimRecord: own2.claimRecord ?? true,
+    exceptionPolicy: normalizeExceptionPolicy(own2.exceptionPolicy),
+    handler,
+    leaseMs: own2.leaseMs ?? 3e4,
+    ...own2.mode == null ? {} : { mode: normalizeStateMode(own2.mode) },
+    name,
+    returnRecord: own2.returnRecord ?? false,
+    valueMaxBytes: own2.valueMaxBytes ?? defaultValueMaxBytes,
+    ...claimValues == null ? {} : { claimValues },
+    ...retryPolicy == null ? {} : { retryPolicy }
   });
 }
-function normalizeStateMode(mode) {
-  if (mode === "fifo" || mode === "parallel") return mode;
-  throw new Error("state mode must be 'fifo' or 'parallel'");
-}
-function valueRefToString(value) {
-  if (typeof value === "string") return value;
-  if (Buffer.isBuffer(value)) return value.toString("utf8");
-  if (typeof value === "object" && value != null && Object.hasOwn(value, "ref")) {
-    const ref = value.ref;
-    return typeof ref === "string" ? ref : Buffer.isBuffer(ref) ? ref.toString("utf8") : void 0;
-  }
-  return void 0;
-}
 
 // src/workflow-context.ts
 var MISSING_VALUE = /* @__PURE__ */ Symbol("ferricstore.missingValue");
 var WorkflowContext = class {
   workflow;
   job;
-  stateName;
   flow;
+  appliedMutation = false;
+  currentStateName;
   leaseJob;
+  mutationFailure;
+  mutationPhase = "idle";
+  mutationCoordinator;
   valueCache = /* @__PURE__ */ new Map();
-  constructor(workflow, job, stateName, leaseJob = job) {
+  constructor(workflow, job, stateName) {
     this.workflow = workflow;
     this.job = job;
-    this.leaseJob = leaseJob;
-    this.stateName = stateName;
+    this.leaseJob = job;
+    this.currentStateName = stateName;
     this.flow = new WorkflowFlowCommands(this);
   }
+  /** @internal */
+  configureWorkerMutation(leaseJob, coordinator) {
+    this.leaseJob = leaseJob;
+    this.mutationCoordinator = coordinator;
+  }
   get client() {
     return this.workflow.client;
   }
+  get stateName() {
+    return this.currentStateName;
+  }
   get id() {
     return this.leaseJob.id;
   }
@@ -20643,7 +21117,7 @@ var WorkflowContext = class {
     return this.leaseJob.state;
   }
   get logicalState() {
-    return this.stateName;
+    return this.currentStateName;
   }
   get partitionKey() {
     return this.leaseJob.partitionKey;
@@ -20681,6 +21155,53 @@ var WorkflowContext = class {
   get correlationId() {
     return "correlationId" in this.job ? this.job.correlationId : void 0;
   }
+  async advance(toState, options = {}) {
+    if (typeof toState !== "string" || toState.length === 0) {
+      throw new TypeError("toState must be a non-empty string");
+    }
+    const current = this.durableClaim();
+    await this.beforeCommit();
+    let refreshed;
+    try {
+      refreshed = await advanceClaim(this.client, current, { ...options, toState });
+    } catch (error) {
+      this.commitFailed(error);
+      throw error;
+    }
+    this.committed(refreshed);
+    return alreadyApplied(refreshed);
+  }
+  async step(options) {
+    let applied = false;
+    const stepped = await runDurableStep(this.client, this.durableClaim(), options, {
+      beforeCommit: async () => await this.beforeCommit(),
+      commitFailed: (error) => this.commitFailed(error),
+      committed: (job) => {
+        applied = true;
+        this.committed(job);
+      },
+      replayed: (job) => this.replayed(job)
+    });
+    return applied ? appliedStep(stepped.job, stepped.result) : replayedStep(stepped.job, stepped.result);
+  }
+  /** @internal */
+  get hasAppliedMutation() {
+    return this.appliedMutation;
+  }
+  /** @internal */
+  get uncertainMutationFailure() {
+    return this.mutationPhase === "uncertain" ? this.mutationFailure : void 0;
+  }
+  /** @internal */
+  get hasUncertainMutation() {
+    return this.mutationPhase === "uncertain";
+  }
+  /** @internal */
+  assertAppliedOutcome(outcome) {
+    if (!this.appliedMutation || !outcome.job.leaseToken.equals(this.leaseJob.leaseToken) || outcome.job.fencingToken !== this.leaseJob.fencingToken) {
+      throw new Error("already-applied outcome does not match the workflow's refreshed claim");
+    }
+  }
   async value(name, defaultValue, options = {}) {
     const useLocalCache = options.localCache ?? this.workflow.valueConfig.localCache;
     if (useLocalCache && this.valueCache.has(name)) {
@@ -20760,7 +21281,49 @@ var WorkflowContext = class {
     return result;
   }
   valueMaxBytes() {
-    return this.workflow.stateRegistration(this.stateName)?.valueMaxBytes;
+    return this.workflow.stateRegistration(this.currentStateName)?.valueMaxBytes;
+  }
+  durableClaim() {
+    const runState = this.leaseJob.runState ?? (this.leaseJob[CLAIMED_ITEM_WIRE] == null ? void 0 : this.currentStateName);
+    if (typeof runState !== "string" || runState.length === 0) {
+      throw new TypeError("job.runState must be a non-empty string");
+    }
+    return {
+      ...this.leaseJob,
+      leaseToken: Buffer.from(this.leaseJob.leaseToken),
+      runState
+    };
+  }
+  async beforeCommit() {
+    if (this.mutationPhase !== "idle") {
+      throw new Error("a durable workflow mutation is already in progress or has an uncertain result");
+    }
+    await this.mutationCoordinator?.pause();
+    this.mutationPhase = "committing";
+  }
+  commitFailed(error) {
+    if (!durableMutationMayHaveCommitted(error)) {
+      this.mutationFailure = void 0;
+      this.mutationPhase = "idle";
+      this.mutationCoordinator?.resume(this.leaseJob);
+      return;
+    }
+    this.mutationFailure = error;
+    this.mutationPhase = "uncertain";
+  }
+  committed(job) {
+    this.acceptJob(job);
+    this.appliedMutation = true;
+    this.mutationCoordinator?.resume(job);
+  }
+  replayed(job) {
+    this.acceptJob(job);
+  }
+  acceptJob(job) {
+    this.leaseJob = job;
+    this.currentStateName = job.runState ?? this.currentStateName;
+    this.mutationFailure = void 0;
+    this.mutationPhase = "idle";
   }
 };
 var WorkflowFlowCommands = class {
@@ -20798,6 +21361,7 @@ var WorkflowFlowCommands = class {
       toState
     });
   }
+  /** @deprecated Use `ctx.advance(toState)`. */
   async stepContinue(toState, options = {}) {
     return await this.ctx.client.stepContinue(this.ctx.id, {
       ...options,
@@ -20960,25 +21524,86 @@ async function applyFail(client, ctx, outcome, returnRecord) {
   });
 }
 
-// src/workflow-registration.ts
-function createWorkflowStateRegistration(name, handler, options, defaultValueMaxBytes) {
-  const own2 = { ...options };
-  const claimValues = own2.claimValues == null ? void 0 : snapshotOwnStringArray(own2.claimValues, "claimValues");
-  const retryPolicy = own2.retryPolicy == null ? void 0 : Object.freeze({ ...own2.retryPolicy });
-  return Object.freeze({
-    claimPayload: own2.claimPayload ?? true,
-    claimRecord: own2.claimRecord ?? true,
-    exceptionPolicy: normalizeExceptionPolicy(own2.exceptionPolicy),
-    handler,
-    leaseMs: own2.leaseMs ?? 3e4,
-    ...own2.mode == null ? {} : { mode: normalizeStateMode(own2.mode) },
-    name,
-    returnRecord: own2.returnRecord ?? false,
-    valueMaxBytes: own2.valueMaxBytes ?? defaultValueMaxBytes,
-    ...claimValues == null ? {} : { claimValues },
-    ...retryPolicy == null ? {} : { retryPolicy }
+// src/workflow-worker-context.ts
+var WorkerWorkflowContext = class extends WorkflowContext {
+  constructor(workflow, job, stateName, leaseJob, mutationCoordinator) {
+    super(workflow, job, stateName);
+    this.configureWorkerMutation(leaseJob, mutationCoordinator);
+  }
+};
+
+// src/workflow-job-execution.ts
+async function executeWorkflowJob(workflow, workerOptions, job, registration, guard) {
+  guard.assertActive();
+  const ctx = new WorkerWorkflowContext(workflow, job, registration.name, guard.job, {
+    pause: async () => await guard.pauseForLeaseMutation(),
+    resume: (refreshed) => guard.resumeWith(refreshed)
+  });
+  let value;
+  try {
+    value = await registration.handler(ctx);
+  } catch (error) {
+    await guard.stop();
+    if (ctx.hasUncertainMutation) throw asError(error, "durable workflow mutation result is uncertain");
+    await applyHandlerError(workflow, workerOptions, ctx, registration, error);
+    return;
+  }
+  await guard.stop();
+  if (ctx.hasUncertainMutation) {
+    throw asError(ctx.uncertainMutationFailure, "durable workflow mutation result is uncertain");
+  }
+  if (isAlreadyAppliedOutcome(value)) {
+    ctx.assertAppliedOutcome(value);
+    await releaseAppliedMutation(workflow, ctx);
+    return;
+  }
+  if (isReplayedStepResult(value)) {
+    await applyWorkflowOutcome(
+      workflow.client,
+      ctx,
+      complete({ result: value.result }),
+      registration.returnRecord
+    );
+    return;
+  }
+  if (isOutcome(value)) {
+    await applyWorkflowOutcome(workflow.client, ctx, value, registration.returnRecord);
+    return;
+  }
+  if (ctx.hasAppliedMutation) {
+    await releaseAppliedMutation(workflow, ctx);
+    return;
+  }
+  await applyWorkflowOutcome(
+    workflow.client,
+    ctx,
+    complete({ result: value }),
+    registration.returnRecord
+  );
+}
+function asError(value, message) {
+  return value instanceof Error ? value : new Error(message, { cause: value });
+}
+async function releaseAppliedMutation(workflow, ctx) {
+  await workflow.client.transition(ctx.id, {
+    fencingToken: ctx.fencingToken,
+    fromState: ctx.state,
+    leaseToken: ctx.leaseToken,
+    partitionKey: ctx.partitionKey,
+    toState: ctx.logicalState
   });
 }
+async function applyHandlerError(workflow, workerOptions, ctx, registration, error) {
+  const policy = workerOptions.exceptionPolicy ?? registration.exceptionPolicy;
+  if (policy === "raise") throw error;
+  const encodedError = workerErrorPayload(error, workerOptions, workflow.client.codec);
+  await applyWorkflowOutcome(
+    workflow.client,
+    ctx,
+    policy === "fail" ? fail2({ error: encodedError }) : retry({ error: encodedError }),
+    registration.returnRecord
+  );
+}
 
 // src/workflow.ts
 var WorkflowClient = class {
@@ -21107,6 +21732,10 @@ var WorkflowWorker = class {
         claimed += jobs.length;
         const guards = jobs.map((job) => new LeaseRenewalGuard(this.workflow.client, job, leaseMs, this.options));
         let cursor = 0;
+        let batchFailure;
+        const recordFailure = (error) => {
+          batchFailure ??= { error };
+        };
         const runNext = async () => {
           while (cursor < jobs.length) {
             const index = cursor;
@@ -21117,19 +21746,22 @@ var WorkflowWorker = class {
             try {
               await this.applyJob(job, registration, guard);
               applied += 1;
+            } catch (error) {
+              recordFailure(error);
             } finally {
-              await guard.stop();
+              try {
+                await guard.stop();
+              } catch (error) {
+                recordFailure(error);
+              }
             }
           }
         };
         try {
-          const handlers = await Promise.allSettled(
+          await Promise.all(
             Array.from({ length: Math.min(concurrency, jobs.length) }, () => runNext())
           );
-          const failed = handlers.find((handler) => handler.status === "rejected");
-          if (failed != null) {
-            throw failed.reason;
-          }
+          if (batchFailure != null) throwError(batchFailure.error);
         } finally {
           await Promise.allSettled(
             guards.slice(cursor).map(async (guard) => await guard.stop())
@@ -21240,45 +21872,15 @@ var WorkflowWorker = class {
     });
   }
   async applyJob(job, registration, guard) {
-    guard.assertActive();
-    const ctx = new WorkflowContext(this.workflow, job, registration.name, guard.job);
-    let outcome;
-    try {
-      const value = await registration.handler(ctx);
-      outcome = isOutcome(value) ? value : complete({ result: value });
-    } catch (error) {
-      await guard.stop();
-      await this.applyHandlerError(ctx, registration, error);
-      return;
-    }
-    await guard.stop();
-    await applyWorkflowOutcome(this.workflow.client, ctx, outcome, registration.returnRecord);
-  }
-  async applyHandlerError(ctx, registration, error) {
-    const policy = this.options.exceptionPolicy ?? registration.exceptionPolicy;
-    if (policy === "raise") {
-      throw error;
-    }
-    if (policy === "fail") {
-      await applyWorkflowOutcome(
-        this.workflow.client,
-        ctx,
-        fail2({ error: workerErrorPayload(error, this.options, this.workflow.client.codec) }),
-        registration.returnRecord
-      );
-      return;
-    }
-    await applyWorkflowOutcome(
-      this.workflow.client,
-      ctx,
-      retry({ error: workerErrorPayload(error, this.options, this.workflow.client.codec) }),
-      registration.returnRecord
-    );
+    await executeWorkflowJob(this.workflow, this.options, job, registration, guard);
   }
 };
+function throwError(value) {
+  throw value instanceof Error ? value : new Error("workflow worker failed", { cause: value });
+}
 
 // src/version.ts
-var FERRICSTORE_SDK_VERSION = "0.12.0";
+var FERRICSTORE_SDK_VERSION = "0.13.1";
 var FERRICSTORE_MINIMUM_SERVER_VERSION = "0.11.4";
 var FERRICSTORE_NATIVE_PROTOCOL_VERSION = 1;
 export {
@@ -21321,6 +21923,7 @@ export {
   QueueWorker,
   RawCodec,
   ReconnectingExecutor,
+  RequestNotSentError,
   RequestTimeoutError,
   RerouteError,
   RoutingTopology,
@@ -21341,6 +21944,7 @@ export {
   complete,
   fail2 as fail,
   httpCommandDisposition,
+  isAlreadyAppliedOutcome,
   isOutcome,
   isReconnectableClosedConnectionError,
   mapException,