@ferricstore/ferricstore 0.12.1 → 0.13.0

package/dist/index.cjs

@@ -89,6 +89,7 @@ __export(index_exports, {
   complete: () => complete,
   fail: () => fail2,
   httpCommandDisposition: () => httpCommandDisposition,
+  isAlreadyAppliedOutcome: () => isAlreadyAppliedOutcome,
   isOutcome: () => isOutcome,
   isReconnectableClosedConnectionError: () => isReconnectableClosedConnectionError,
   mapException: () => mapException,
@@ -9122,6 +9123,8 @@ var HTTPTransport = class {
     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) {
@@ -18598,12 +18601,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);
@@ -18626,7 +18637,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 });
@@ -19007,6 +19018,254 @@ var FerricStoreProducerClient = class extends FerricStoreClaimClient {
   }
 };
 
+// src/client-durable-step.ts
+var import_node_crypto2 = require("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");
+  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);
+    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) {
+    hooks.commitFailed?.(error);
+    throw error;
+  }
+  hooks.committed?.(refreshed);
+  return { job: refreshed, result };
+}
+function normalizeStepResult(client, value) {
+  return client.codec.decode(client.codec.encode(value));
+}
+function durableStepValueName(name) {
+  const digest = (0, import_node_crypto2.createHash)("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.ts
 var FerricStoreClient = class _FerricStoreClient extends FerricStoreProducerClient {
   static async fromUrl(url, options = {}) {
@@ -19121,6 +19380,10 @@ 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;
@@ -19148,6 +19411,18 @@ var FerricStoreClient = class _FerricStoreClient extends FerricStoreProducerClie
     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;
@@ -19397,6 +19672,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 });
 }
@@ -19409,6 +19686,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;
@@ -19419,6 +19712,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,
@@ -19442,6 +19741,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) {
@@ -19458,8 +19772,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 });
@@ -19470,37 +19783,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,
@@ -19511,17 +19845,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;
     });
   }
 };
@@ -19545,8 +19874,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";
@@ -19589,18 +19924,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);
@@ -19612,7 +19947,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)) {
@@ -19623,8 +19958,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,
@@ -19746,7 +20081,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) {
@@ -19799,7 +20134,7 @@ async function waitForRefillWindow(delayMs, signal) {
 }
 
 // src/queue.ts
-var import_node_crypto2 = require("crypto");
+var import_node_crypto3 = require("crypto");
 
 // src/queue-completion-batcher.ts
 function queueClaimOptions(queue, options, overrides = {}) {
@@ -20664,7 +20999,7 @@ var Queue = class {
     this.client = client;
     this.type = captured.type;
     this.state = captured.state ?? "queued";
-    this.defaultWorker = captured.worker ?? `${this.type}-${(0, import_node_crypto2.randomUUID)()}`;
+    this.defaultWorker = captured.worker ?? `${this.type}-${(0, import_node_crypto3.randomUUID)()}`;
   }
   async enqueue(id, options = {}) {
     return await this.client.enqueue(id, {
@@ -20686,53 +21021,55 @@ var Queue = class {
 };
 
 // src/workflow.ts
-var import_node_crypto3 = require("crypto");
+var import_node_crypto4 = require("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;
-  leaseJob;
-  valueCache = /* @__PURE__ */ new Map();
-  constructor(workflow, job, stateName, leaseJob = job) {
+  constructor(workflow, job, stateName, leaseJob = job, mutationCoordinator) {
+    this.mutationCoordinator = mutationCoordinator;
     this.workflow = workflow;
     this.job = job;
     this.leaseJob = leaseJob;
-    this.stateName = stateName;
+    this.currentStateName = stateName;
     this.flow = new WorkflowFlowCommands(this);
   }
+  mutationCoordinator;
+  workflow;
+  job;
+  flow;
+  appliedMutation = false;
+  currentStateName;
+  leaseJob;
+  mutationFailure;
+  mutationPhase = "idle";
+  valueCache = /* @__PURE__ */ new Map();
   get client() {
     return this.workflow.client;
   }
+  get stateName() {
+    return this.currentStateName;
+  }
   get id() {
     return this.leaseJob.id;
   }
@@ -20743,7 +21080,7 @@ var WorkflowContext = class {
     return this.leaseJob.state;
   }
   get logicalState() {
-    return this.stateName;
+    return this.currentStateName;
   }
   get partitionKey() {
     return this.leaseJob.partitionKey;
@@ -20781,6 +21118,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)) {
@@ -20860,7 +21244,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 {
@@ -20898,6 +21324,7 @@ var WorkflowFlowCommands = class {
       toState
     });
   }
+  /** @deprecated Use `ctx.advance(toState)`. */
   async stepContinue(toState, options = {}) {
     return await this.ctx.client.stepContinue(this.ctx.id, {
       ...options,
@@ -21060,24 +21487,77 @@ 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-job-execution.ts
+async function executeWorkflowJob(workflow, workerOptions, job, registration, guard) {
+  guard.assertActive();
+  const ctx = new WorkflowContext(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
@@ -21106,7 +21586,7 @@ var Workflow = class {
       localCache: captured.valueConfig?.localCache ?? false,
       valueMaxBytes: captured.valueConfig?.valueMaxBytes
     };
-    this.defaultWorker = captured.worker ?? `${this.type}-${(0, import_node_crypto3.randomUUID)()}`;
+    this.defaultWorker = captured.worker ?? `${this.type}-${(0, import_node_crypto4.randomUUID)()}`;
   }
   state(name, handler, options = {}) {
     this.states.set(name, createWorkflowStateRegistration(
@@ -21207,6 +21687,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;
@@ -21217,19 +21701,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())
@@ -21340,42 +21827,12 @@ 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";
@@ -21442,6 +21899,7 @@ var FERRICSTORE_NATIVE_PROTOCOL_VERSION = 1;
   complete,
   fail,
   httpCommandDisposition,
+  isAlreadyAppliedOutcome,
   isOutcome,
   isReconnectableClosedConnectionError,
   mapException,