@ferricstore/ferricstore 0.12.2 → 0.13.1

package/dist/index.d.cts

@@ -1,8 +1,8 @@
 import { ConnectionOptions } from 'node:tls';
 import { C as CommandArgument, a as Command } from './internal-lEEDZpPH.cjs';
 import { Buffer as Buffer$1 } from 'node:buffer';
-import { F as FencingToken, S as StateMeta, a as FlowRecord, C as ClaimedItem, M as MaxActiveMs, R as RateLimitResult, K as KeyInfo, b as FetchOrComputeResult, c as ChildSpec, d as FencedItem, e as CreateItem, O as Outcome } from './outcomes-DmBwnq0Y.cjs';
-export { f as CompleteOutcome, g as FailOutcome, h as FetchOrComputeComputeResult, i as FetchOrComputeFencedResult, j as FetchOrComputeHitResult, k as FlowMaxActiveFailure, N as NamedValueMutation, l as RetryOutcome, m as StateMetaValue, T as TransitionOutcome, n as complete, o as fail, p as isOutcome, r as retry, t as transition } from './outcomes-DmBwnq0Y.cjs';
+import { F as FencingToken, S as StateMeta, a as FlowRecord, C as ClaimedItem, M as MaxActiveMs, R as RateLimitResult, K as KeyInfo, b as FetchOrComputeResult, c as ChildSpec, d as FencedItem, e as CreateItem, A as AlreadyAppliedOutcome, W as WorkflowStepResult, O as Outcome } from './outcomes-CcX956h4.cjs';
+export { f as AppliedStepOutcome, g as CompleteOutcome, h as FailOutcome, i as FetchOrComputeComputeResult, j as FetchOrComputeFencedResult, k as FetchOrComputeHitResult, l as FlowMaxActiveFailure, N as NamedValueMutation, m as ReplayedStepResult, n as RetryOutcome, o as StateMetaValue, T as TransitionOutcome, p as complete, q as fail, r as isAlreadyAppliedOutcome, s as isOutcome, t as retry, u as transition } from './outcomes-CcX956h4.cjs';
 
 declare class FerricStoreError extends Error {
     readonly code: string;
@@ -18,14 +18,16 @@ declare class FerricStoreError extends Error {
         retryAfterMs?: number;
     });
 }
+type RequestDisposition = "unsent" | "possibly_sent";
 declare class HTTPTransportError extends FerricStoreError {
     readonly code = "http_transport";
+    readonly requestDisposition: RequestDisposition | undefined;
     readonly statusCode: number | undefined;
     constructor(message: string, options?: ConstructorParameters<typeof FerricStoreError>[1] & {
+        requestDisposition?: RequestDisposition;
         statusCode?: number;
     });
 }
-type RequestDisposition = "unsent" | "possibly_sent";
 /** Connection closure annotated with whether the current request may have reached the server. */
 declare class ConnectionClosedError extends FerricStoreError {
     readonly code = "connection_closed";
@@ -46,6 +48,15 @@ declare class RequestTimeoutError extends FerricStoreError {
         cause?: unknown;
     });
 }
+/** A local validation, encoding, sizing, or lifecycle failure before submission. */
+declare class RequestNotSentError extends FerricStoreError {
+    readonly code = "request_not_sent";
+    readonly requestDisposition: "unsent";
+    constructor(message: string, options?: {
+        raw?: unknown;
+        cause?: unknown;
+    });
+}
 declare class FlowNotFoundError extends FerricStoreError {
     readonly code = "flow_not_found";
 }
@@ -984,6 +995,11 @@ interface MutateOptions {
     attributesMerge?: Record<string, CommandArgument>;
     attributesDelete?: string[];
     stateMeta?: StateMeta;
+    /**
+     * Explicit client-supplied command timestamp. Omit in production so each
+     * request samples the current client wall clock; primarily useful for tests.
+     * This is not the server response time or the client transport deadline.
+     */
     nowMs?: number;
     returnRecord?: boolean;
 }
@@ -996,6 +1012,7 @@ interface ExtendLeaseOptions {
     fencingToken: FencingToken;
     leaseMs: number;
     partitionKey?: string;
+    /** See {@link MutateOptions.nowMs}; this is a client timestamp override. */
     nowMs?: number;
     returnOkOnSuccess?: boolean;
 }
@@ -1014,6 +1031,26 @@ interface StepContinueOptions extends Omit<LeaseMutationOptions, "returnRecord">
     /** Flow type to retain when returnJob requests a compact response. */
     type?: string;
 }
+/** Options for advancing an already-claimed Flow to its next logical state. */
+interface AdvanceOptions extends Omit<MutateOptions, "returnRecord"> {
+    toState: string;
+    leaseMs?: number;
+}
+/** Options for a closure whose result is journaled with its state transition. */
+interface StepOptions<TResult> extends AdvanceOptions {
+    /** Stable operation identity. Keep this unchanged across retries. */
+    name: string;
+    /**
+     * Runs directly in the caller or worker's JavaScript execution context. The
+     * SDK awaits its result and does not submit it to a global thread pool.
+     */
+    run: () => TResult | PromiseLike<TResult>;
+}
+/** The renewed claim and durable result returned by a durable `step()` call. */
+interface StepResult<TResult> {
+    readonly job: ClaimedItem;
+    readonly result: TResult;
+}
 interface RunStepsItem {
     id: string;
     partitionKey?: string;
@@ -2249,7 +2286,19 @@ declare class FerricStoreClient extends FerricStoreProducerClient {
     }): Promise<unknown>;
     flowSignal(id: string, options: Parameters<FerricStoreClient["signal"]>[1]): Promise<unknown>;
     startAndClaim(id: string, options: StartAndClaimOptions): Promise<FlowRecord>;
+    /**
+     * @deprecated Low-level compatibility API. Use {@link advance} for state-only
+     * continuation or {@link step} for a durable closure.
+     */
     stepContinue(id: string, options: StepContinueOptions): Promise<FlowRecord | ClaimedItem>;
+    /** Advance a claimed Flow and return its renewed claim. */
+    advance(job: FlowRecord | ClaimedItem, options: AdvanceOptions): Promise<ClaimedItem>;
+    /**
+     * 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.
+     */
+    step<TResult>(job: FlowRecord | ClaimedItem, options: StepOptions<TResult>): Promise<StepResult<TResult>>;
     runStepsMany(items: readonly (string | RunStepsItem)[], options: RunStepsManyOptions): Promise<unknown>;
     transitionMany(partitionKey: string | undefined, options: {
         fromState: string;
@@ -2406,15 +2455,28 @@ declare class Queue {
     worker(options?: WorkerConfig): QueueWorker;
 }
 
+/** @internal Coordinates lease renewal around an atomic lease-rotating write. */
+interface MutationCoordinator {
+    pause(): Promise<void>;
+    resume(job: ClaimedItem): void;
+}
+
 declare class WorkflowContext {
     readonly workflow: Workflow;
     readonly job: FlowRecord | ClaimedItem;
-    readonly stateName: string;
     readonly flow: WorkflowFlowCommands;
-    private readonly leaseJob;
+    private appliedMutation;
+    private currentStateName;
+    private leaseJob;
+    private mutationFailure?;
+    private mutationPhase;
+    private mutationCoordinator?;
     private readonly valueCache;
-    constructor(workflow: Workflow, job: FlowRecord | ClaimedItem, stateName: string, leaseJob?: ClaimedItem);
+    constructor(workflow: Workflow, job: FlowRecord | ClaimedItem, stateName: string);
+    /** @internal */
+    protected configureWorkerMutation(leaseJob: ClaimedItem, coordinator: MutationCoordinator): void;
     get client(): FerricStoreClient;
+    get stateName(): string;
     get id(): string;
     get type(): string;
     get state(): string;
@@ -2431,6 +2493,16 @@ declare class WorkflowContext {
     get parentFlowId(): string | undefined;
     get rootFlowId(): string | undefined;
     get correlationId(): string | undefined;
+    advance(toState: string, options?: Omit<AdvanceOptions, "toState">): Promise<AlreadyAppliedOutcome>;
+    step<TResult>(options: StepOptions<TResult>): Promise<WorkflowStepResult<TResult>>;
+    /** @internal */
+    get hasAppliedMutation(): boolean;
+    /** @internal */
+    get uncertainMutationFailure(): unknown;
+    /** @internal */
+    get hasUncertainMutation(): boolean;
+    /** @internal */
+    assertAppliedOutcome(outcome: AlreadyAppliedOutcome): void;
     value(name: string, defaultValue?: unknown, options?: {
         localCache?: boolean;
     }): Promise<unknown>;
@@ -2438,6 +2510,12 @@ declare class WorkflowContext {
         localCache?: boolean;
     }): Promise<Record<string, unknown>>;
     private valueMaxBytes;
+    private durableClaim;
+    private beforeCommit;
+    private commitFailed;
+    private committed;
+    private replayed;
+    private acceptJob;
 }
 declare class WorkflowFlowCommands {
     private readonly ctx;
@@ -2453,6 +2531,7 @@ declare class WorkflowFlowCommands {
     transition(toState: string, options?: Partial<Omit<Parameters<FerricStoreClient["transition"]>[1], "toState" | "fromState" | "leaseToken" | "fencingToken">> & {
         fromState?: string;
     }): Promise<FlowRecord | Buffer | unknown>;
+    /** @deprecated Use `ctx.advance(toState)`. */
     stepContinue(toState: string, options?: Partial<Omit<StepContinueOptions, "toState" | "fromState" | "leaseToken" | "fencingToken">> & {
         fromState?: string;
     }): Promise<FlowRecord | ClaimedItem>;
@@ -2595,11 +2674,10 @@ declare class WorkflowWorker {
     private resolveStates;
     private claimState;
     private applyJob;
-    private applyHandlerError;
 }
 
 /** TypeScript SDK package version. */
-declare const FERRICSTORE_SDK_VERSION = "0.12.0";
+declare const FERRICSTORE_SDK_VERSION = "0.13.1";
 /** Oldest FerricStore server supported by this breaking beta contract. */
 declare const FERRICSTORE_MINIMUM_SERVER_VERSION = "0.11.4";
 /** Native framing and opcode ABI version; unchanged by FerricStore 0.11. */
@@ -2608,4 +2686,4 @@ declare const FERRICSTORE_NATIVE_PROTOCOL_VERSION = 1;
 /** @deprecated Use RequestDisposition; retained for source compatibility. */
 type ConnectionRequestDisposition = RequestDisposition;
 
-export { type AdminListOptions, type ApprovalListOptions, type ApprovalRequestOptions, type AttributeQueryOptions, type AutoBatchOptions, type BackoffKind, type BackpressurePolicy, BitmapStore, BloomFilterStore, type BudgetCommitOptions, type BudgetReserveOptions, COMMAND_OPCODES, type CancelOptions, ChildSpec, type CircuitOpenOptions, type ClaimDueOptions, ClaimHydrationError, type ClaimHydrationItem, ClaimedItem, type Codec, type CollectionScanOptions, Command, CommandArgument, type CommandExecutor, type CompleteJobsAndClaimJobsResult, type CompleteManyOptions, type CompleteOptions, ConnectionClosedError, type ConnectionRequestDisposition, type CountMinMergeOptions, CountMinSketchStore, CreateItem, type CreateManyOptions, type CreateOptions, CuckooFilterStore, type EffectCompensateOptions, type EffectConfirmOptions, type EffectFailOptions, type EffectReserveOptions, type EffectStatusOptions, type EndpointPolicy, type ExceptionPolicy, type ExecutePipelineOptions, type ExpiryCondition, type ExtendLeaseOptions, FERRICSTORE_MINIMUM_SERVER_VERSION, FERRICSTORE_NATIVE_PROTOCOL_VERSION, FERRICSTORE_SDK_VERSION, type FailOptions, FencedItem, FencingToken, FerricStoreClient, type FerricStoreClientFromUrlOptions, type FerricStoreClientOptions, FerricStoreError, FetchOrComputeResult, type FlowAdminRecord, FlowAlreadyExistsError, type FlowBatchCompletedItem, FlowBatchError, type FlowEventProjectionField, type FlowExplainCapabilities, type FlowExplainResult, FlowNotFoundError, type FlowPolicyBackoffKind, type FlowPolicyBackoffSnapshot, type FlowPolicyOptions, type FlowPolicyRetentionSnapshot, type FlowPolicyRetrySnapshot, type FlowPolicySnapshot, type FlowPolicyStateSnapshot, FlowProjection, type FlowProjectionField, type FlowProjectionShape, type FlowQueryCountResult, FlowQueryError, type FlowQueryErrorPosition, type FlowQueryIndex, type FlowQueryIndexBuild, type FlowQueryIndexCoverage, type FlowQueryIndexField, type FlowQueryIndexFormat, type FlowQueryIndexProgress, type FlowQueryIndexRegistry, type FlowQueryIndexRetirement, type FlowQueryIndexServiceState, type FlowQueryIndexServices, type FlowQueryIndexStatistics, type FlowQueryIndexStatus, type FlowQueryIndexValidation, type FlowQueryInteger, type FlowQueryPage, type FlowQueryParameter, type FlowQueryParameters, type FlowQueryQuality, type FlowQueryRecord, type FlowQueryRecordsResult, type FlowQueryResult, type FlowQueryUsage, FlowRecord, type FlowRunProjectionField, type FlowStateMode, type FlowStatePolicy, type FlowStatePolicyLike, type FlowStatsOptions, FlowWrongStateError, type GeoAddOptions, type GeoMember, GeoStore, type GetExOptions, type GovernanceLedgerOptions, HTTPAdapter, type HTTPAdapterOptions, type HTTPCommandDisposition, HTTPTransportError, type HashScanResult, HashStore, type HistoryOptions, HyperLogLogStore, type IntegerReply, InvalidCommandError, type InvocationCreateOptions, JsonCodec, KeyInfo, KeyValueStore, type LeaseMutationOptions, LeaseRenewalError, type LimitAmountOptions, type LimitLeaseOptions, type LimitListOptions, type LimitReleaseOptions, ListStore, LockHeldError, LockNotOwnedError, MAX_FLOW_POLICY_GENERATION, type ManagementPairs, MaxActiveMs, type MutateOptions, NativeAdapter, type NativeAdapterOptions, type NativeClientOptions, type NativeProtocolEvent, Outcome, OverloadedError, type ProtocolCommand, Queue, type QueueBatchHandler, QueueClient, QueueCompletionError, type QueueHandler, type QueueJob, type QueueOptions, QueueWorker, type QueueWorkerResult, type RangeLimit, RateLimitResult, RawCodec, type ReadOptions, type ReclaimOptions, type ReconnectOptions, ReconnectingExecutor, type RequestContext, type RequestContextOptions, type RequestDisposition, RequestTimeoutError, RerouteError, type RetryOptions, type RetryPolicy, type RoutingEndpoint, type RoutingRoute, RoutingTopology, type RunStepsItem, type RunStepsManyOptions, type ScanOptions, type ScheduleCatchupPolicy, type ScheduleFireDueOptions, type ScheduleFireDueResult, type ScheduleFireOptions, type ScheduleFireResult, type ScheduleKind, type ScheduleListOptions, type ScheduleOptions, type ScheduleOverlapPolicy, type ScheduleRecord, type ScheduleState, type SearchOptions, type SearchStateMeta, type SetOptions, type SetScanResult, SetStore, type SortedSetScanResult, SortedSetStore, StaleLeaseError, StalePolicyGenerationError, type StartAndClaimOptions, StateMeta, type StateOptions, type StateRegistration, type StepContinueOptions, type StoreCommandClient, StreamStore, type TDigestCreateOptions, type TDigestMergeOptions, TDigestStore, type TopKReserveOptions, TopKStore, type TopologyNativeAdapterOptions, TopologyNativeAdapterPool, type TransitionOptions, type ValueConfig, type WorkerConfig, type WorkerProfile, type WorkerRefillStrategy, Workflow, WorkflowClient, WorkflowContext, WorkflowFlowCommands, type WorkflowHandler, type WorkflowOptions, WorkflowWorker, type WorkflowWorkerResult, type XReadStream, type ZAddMember, type ZAddOptions, classifyServerError, httpCommandDisposition, isReconnectableClosedConnectionError, mapException, projectFlowQuery };
+export { type AdminListOptions, type AdvanceOptions, AlreadyAppliedOutcome, type ApprovalListOptions, type ApprovalRequestOptions, type AttributeQueryOptions, type AutoBatchOptions, type BackoffKind, type BackpressurePolicy, BitmapStore, BloomFilterStore, type BudgetCommitOptions, type BudgetReserveOptions, COMMAND_OPCODES, type CancelOptions, ChildSpec, type CircuitOpenOptions, type ClaimDueOptions, ClaimHydrationError, type ClaimHydrationItem, ClaimedItem, type Codec, type CollectionScanOptions, Command, CommandArgument, type CommandExecutor, type CompleteJobsAndClaimJobsResult, type CompleteManyOptions, type CompleteOptions, ConnectionClosedError, type ConnectionRequestDisposition, type CountMinMergeOptions, CountMinSketchStore, CreateItem, type CreateManyOptions, type CreateOptions, CuckooFilterStore, type EffectCompensateOptions, type EffectConfirmOptions, type EffectFailOptions, type EffectReserveOptions, type EffectStatusOptions, type EndpointPolicy, type ExceptionPolicy, type ExecutePipelineOptions, type ExpiryCondition, type ExtendLeaseOptions, FERRICSTORE_MINIMUM_SERVER_VERSION, FERRICSTORE_NATIVE_PROTOCOL_VERSION, FERRICSTORE_SDK_VERSION, type FailOptions, FencedItem, FencingToken, FerricStoreClient, type FerricStoreClientFromUrlOptions, type FerricStoreClientOptions, FerricStoreError, FetchOrComputeResult, type FlowAdminRecord, FlowAlreadyExistsError, type FlowBatchCompletedItem, FlowBatchError, type FlowEventProjectionField, type FlowExplainCapabilities, type FlowExplainResult, FlowNotFoundError, type FlowPolicyBackoffKind, type FlowPolicyBackoffSnapshot, type FlowPolicyOptions, type FlowPolicyRetentionSnapshot, type FlowPolicyRetrySnapshot, type FlowPolicySnapshot, type FlowPolicyStateSnapshot, FlowProjection, type FlowProjectionField, type FlowProjectionShape, type FlowQueryCountResult, FlowQueryError, type FlowQueryErrorPosition, type FlowQueryIndex, type FlowQueryIndexBuild, type FlowQueryIndexCoverage, type FlowQueryIndexField, type FlowQueryIndexFormat, type FlowQueryIndexProgress, type FlowQueryIndexRegistry, type FlowQueryIndexRetirement, type FlowQueryIndexServiceState, type FlowQueryIndexServices, type FlowQueryIndexStatistics, type FlowQueryIndexStatus, type FlowQueryIndexValidation, type FlowQueryInteger, type FlowQueryPage, type FlowQueryParameter, type FlowQueryParameters, type FlowQueryQuality, type FlowQueryRecord, type FlowQueryRecordsResult, type FlowQueryResult, type FlowQueryUsage, FlowRecord, type FlowRunProjectionField, type FlowStateMode, type FlowStatePolicy, type FlowStatePolicyLike, type FlowStatsOptions, FlowWrongStateError, type GeoAddOptions, type GeoMember, GeoStore, type GetExOptions, type GovernanceLedgerOptions, HTTPAdapter, type HTTPAdapterOptions, type HTTPCommandDisposition, HTTPTransportError, type HashScanResult, HashStore, type HistoryOptions, HyperLogLogStore, type IntegerReply, InvalidCommandError, type InvocationCreateOptions, JsonCodec, KeyInfo, KeyValueStore, type LeaseMutationOptions, LeaseRenewalError, type LimitAmountOptions, type LimitLeaseOptions, type LimitListOptions, type LimitReleaseOptions, ListStore, LockHeldError, LockNotOwnedError, MAX_FLOW_POLICY_GENERATION, type ManagementPairs, MaxActiveMs, type MutateOptions, NativeAdapter, type NativeAdapterOptions, type NativeClientOptions, type NativeProtocolEvent, Outcome, OverloadedError, type ProtocolCommand, Queue, type QueueBatchHandler, QueueClient, QueueCompletionError, type QueueHandler, type QueueJob, type QueueOptions, QueueWorker, type QueueWorkerResult, type RangeLimit, RateLimitResult, RawCodec, type ReadOptions, type ReclaimOptions, type ReconnectOptions, ReconnectingExecutor, type RequestContext, type RequestContextOptions, type RequestDisposition, RequestNotSentError, RequestTimeoutError, RerouteError, type RetryOptions, type RetryPolicy, type RoutingEndpoint, type RoutingRoute, RoutingTopology, type RunStepsItem, type RunStepsManyOptions, type ScanOptions, type ScheduleCatchupPolicy, type ScheduleFireDueOptions, type ScheduleFireDueResult, type ScheduleFireOptions, type ScheduleFireResult, type ScheduleKind, type ScheduleListOptions, type ScheduleOptions, type ScheduleOverlapPolicy, type ScheduleRecord, type ScheduleState, type SearchOptions, type SearchStateMeta, type SetOptions, type SetScanResult, SetStore, type SortedSetScanResult, SortedSetStore, StaleLeaseError, StalePolicyGenerationError, type StartAndClaimOptions, StateMeta, type StateOptions, type StateRegistration, type StepContinueOptions, type StepOptions, type StepResult, type StoreCommandClient, StreamStore, type TDigestCreateOptions, type TDigestMergeOptions, TDigestStore, type TopKReserveOptions, TopKStore, type TopologyNativeAdapterOptions, TopologyNativeAdapterPool, type TransitionOptions, type ValueConfig, type WorkerConfig, type WorkerProfile, type WorkerRefillStrategy, Workflow, WorkflowClient, WorkflowContext, WorkflowFlowCommands, type WorkflowHandler, type WorkflowOptions, WorkflowStepResult, WorkflowWorker, type WorkflowWorkerResult, type XReadStream, type ZAddMember, type ZAddOptions, classifyServerError, httpCommandDisposition, isReconnectableClosedConnectionError, mapException, projectFlowQuery };

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { ConnectionOptions } from 'node:tls';
 import { C as CommandArgument, a as Command } from './internal-lEEDZpPH.js';
 import { Buffer as Buffer$1 } from 'node:buffer';
-import { F as FencingToken, S as StateMeta, a as FlowRecord, C as ClaimedItem, M as MaxActiveMs, R as RateLimitResult, K as KeyInfo, b as FetchOrComputeResult, c as ChildSpec, d as FencedItem, e as CreateItem, O as Outcome } from './outcomes-BbFDp3AH.js';
-export { f as CompleteOutcome, g as FailOutcome, h as FetchOrComputeComputeResult, i as FetchOrComputeFencedResult, j as FetchOrComputeHitResult, k as FlowMaxActiveFailure, N as NamedValueMutation, l as RetryOutcome, m as StateMetaValue, T as TransitionOutcome, n as complete, o as fail, p as isOutcome, r as retry, t as transition } from './outcomes-BbFDp3AH.js';
+import { F as FencingToken, S as StateMeta, a as FlowRecord, C as ClaimedItem, M as MaxActiveMs, R as RateLimitResult, K as KeyInfo, b as FetchOrComputeResult, c as ChildSpec, d as FencedItem, e as CreateItem, A as AlreadyAppliedOutcome, W as WorkflowStepResult, O as Outcome } from './outcomes-DLJYTrX8.js';
+export { f as AppliedStepOutcome, g as CompleteOutcome, h as FailOutcome, i as FetchOrComputeComputeResult, j as FetchOrComputeFencedResult, k as FetchOrComputeHitResult, l as FlowMaxActiveFailure, N as NamedValueMutation, m as ReplayedStepResult, n as RetryOutcome, o as StateMetaValue, T as TransitionOutcome, p as complete, q as fail, r as isAlreadyAppliedOutcome, s as isOutcome, t as retry, u as transition } from './outcomes-DLJYTrX8.js';
 
 declare class FerricStoreError extends Error {
     readonly code: string;
@@ -18,14 +18,16 @@ declare class FerricStoreError extends Error {
         retryAfterMs?: number;
     });
 }
+type RequestDisposition = "unsent" | "possibly_sent";
 declare class HTTPTransportError extends FerricStoreError {
     readonly code = "http_transport";
+    readonly requestDisposition: RequestDisposition | undefined;
     readonly statusCode: number | undefined;
     constructor(message: string, options?: ConstructorParameters<typeof FerricStoreError>[1] & {
+        requestDisposition?: RequestDisposition;
         statusCode?: number;
     });
 }
-type RequestDisposition = "unsent" | "possibly_sent";
 /** Connection closure annotated with whether the current request may have reached the server. */
 declare class ConnectionClosedError extends FerricStoreError {
     readonly code = "connection_closed";
@@ -46,6 +48,15 @@ declare class RequestTimeoutError extends FerricStoreError {
         cause?: unknown;
     });
 }
+/** A local validation, encoding, sizing, or lifecycle failure before submission. */
+declare class RequestNotSentError extends FerricStoreError {
+    readonly code = "request_not_sent";
+    readonly requestDisposition: "unsent";
+    constructor(message: string, options?: {
+        raw?: unknown;
+        cause?: unknown;
+    });
+}
 declare class FlowNotFoundError extends FerricStoreError {
     readonly code = "flow_not_found";
 }
@@ -984,6 +995,11 @@ interface MutateOptions {
     attributesMerge?: Record<string, CommandArgument>;
     attributesDelete?: string[];
     stateMeta?: StateMeta;
+    /**
+     * Explicit client-supplied command timestamp. Omit in production so each
+     * request samples the current client wall clock; primarily useful for tests.
+     * This is not the server response time or the client transport deadline.
+     */
     nowMs?: number;
     returnRecord?: boolean;
 }
@@ -996,6 +1012,7 @@ interface ExtendLeaseOptions {
     fencingToken: FencingToken;
     leaseMs: number;
     partitionKey?: string;
+    /** See {@link MutateOptions.nowMs}; this is a client timestamp override. */
     nowMs?: number;
     returnOkOnSuccess?: boolean;
 }
@@ -1014,6 +1031,26 @@ interface StepContinueOptions extends Omit<LeaseMutationOptions, "returnRecord">
     /** Flow type to retain when returnJob requests a compact response. */
     type?: string;
 }
+/** Options for advancing an already-claimed Flow to its next logical state. */
+interface AdvanceOptions extends Omit<MutateOptions, "returnRecord"> {
+    toState: string;
+    leaseMs?: number;
+}
+/** Options for a closure whose result is journaled with its state transition. */
+interface StepOptions<TResult> extends AdvanceOptions {
+    /** Stable operation identity. Keep this unchanged across retries. */
+    name: string;
+    /**
+     * Runs directly in the caller or worker's JavaScript execution context. The
+     * SDK awaits its result and does not submit it to a global thread pool.
+     */
+    run: () => TResult | PromiseLike<TResult>;
+}
+/** The renewed claim and durable result returned by a durable `step()` call. */
+interface StepResult<TResult> {
+    readonly job: ClaimedItem;
+    readonly result: TResult;
+}
 interface RunStepsItem {
     id: string;
     partitionKey?: string;
@@ -2249,7 +2286,19 @@ declare class FerricStoreClient extends FerricStoreProducerClient {
     }): Promise<unknown>;
     flowSignal(id: string, options: Parameters<FerricStoreClient["signal"]>[1]): Promise<unknown>;
     startAndClaim(id: string, options: StartAndClaimOptions): Promise<FlowRecord>;
+    /**
+     * @deprecated Low-level compatibility API. Use {@link advance} for state-only
+     * continuation or {@link step} for a durable closure.
+     */
     stepContinue(id: string, options: StepContinueOptions): Promise<FlowRecord | ClaimedItem>;
+    /** Advance a claimed Flow and return its renewed claim. */
+    advance(job: FlowRecord | ClaimedItem, options: AdvanceOptions): Promise<ClaimedItem>;
+    /**
+     * 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.
+     */
+    step<TResult>(job: FlowRecord | ClaimedItem, options: StepOptions<TResult>): Promise<StepResult<TResult>>;
     runStepsMany(items: readonly (string | RunStepsItem)[], options: RunStepsManyOptions): Promise<unknown>;
     transitionMany(partitionKey: string | undefined, options: {
         fromState: string;
@@ -2406,15 +2455,28 @@ declare class Queue {
     worker(options?: WorkerConfig): QueueWorker;
 }
 
+/** @internal Coordinates lease renewal around an atomic lease-rotating write. */
+interface MutationCoordinator {
+    pause(): Promise<void>;
+    resume(job: ClaimedItem): void;
+}
+
 declare class WorkflowContext {
     readonly workflow: Workflow;
     readonly job: FlowRecord | ClaimedItem;
-    readonly stateName: string;
     readonly flow: WorkflowFlowCommands;
-    private readonly leaseJob;
+    private appliedMutation;
+    private currentStateName;
+    private leaseJob;
+    private mutationFailure?;
+    private mutationPhase;
+    private mutationCoordinator?;
     private readonly valueCache;
-    constructor(workflow: Workflow, job: FlowRecord | ClaimedItem, stateName: string, leaseJob?: ClaimedItem);
+    constructor(workflow: Workflow, job: FlowRecord | ClaimedItem, stateName: string);
+    /** @internal */
+    protected configureWorkerMutation(leaseJob: ClaimedItem, coordinator: MutationCoordinator): void;
     get client(): FerricStoreClient;
+    get stateName(): string;
     get id(): string;
     get type(): string;
     get state(): string;
@@ -2431,6 +2493,16 @@ declare class WorkflowContext {
     get parentFlowId(): string | undefined;
     get rootFlowId(): string | undefined;
     get correlationId(): string | undefined;
+    advance(toState: string, options?: Omit<AdvanceOptions, "toState">): Promise<AlreadyAppliedOutcome>;
+    step<TResult>(options: StepOptions<TResult>): Promise<WorkflowStepResult<TResult>>;
+    /** @internal */
+    get hasAppliedMutation(): boolean;
+    /** @internal */
+    get uncertainMutationFailure(): unknown;
+    /** @internal */
+    get hasUncertainMutation(): boolean;
+    /** @internal */
+    assertAppliedOutcome(outcome: AlreadyAppliedOutcome): void;
     value(name: string, defaultValue?: unknown, options?: {
         localCache?: boolean;
     }): Promise<unknown>;
@@ -2438,6 +2510,12 @@ declare class WorkflowContext {
         localCache?: boolean;
     }): Promise<Record<string, unknown>>;
     private valueMaxBytes;
+    private durableClaim;
+    private beforeCommit;
+    private commitFailed;
+    private committed;
+    private replayed;
+    private acceptJob;
 }
 declare class WorkflowFlowCommands {
     private readonly ctx;
@@ -2453,6 +2531,7 @@ declare class WorkflowFlowCommands {
     transition(toState: string, options?: Partial<Omit<Parameters<FerricStoreClient["transition"]>[1], "toState" | "fromState" | "leaseToken" | "fencingToken">> & {
         fromState?: string;
     }): Promise<FlowRecord | Buffer | unknown>;
+    /** @deprecated Use `ctx.advance(toState)`. */
     stepContinue(toState: string, options?: Partial<Omit<StepContinueOptions, "toState" | "fromState" | "leaseToken" | "fencingToken">> & {
         fromState?: string;
     }): Promise<FlowRecord | ClaimedItem>;
@@ -2595,11 +2674,10 @@ declare class WorkflowWorker {
     private resolveStates;
     private claimState;
     private applyJob;
-    private applyHandlerError;
 }
 
 /** TypeScript SDK package version. */
-declare const FERRICSTORE_SDK_VERSION = "0.12.0";
+declare const FERRICSTORE_SDK_VERSION = "0.13.1";
 /** Oldest FerricStore server supported by this breaking beta contract. */
 declare const FERRICSTORE_MINIMUM_SERVER_VERSION = "0.11.4";
 /** Native framing and opcode ABI version; unchanged by FerricStore 0.11. */
@@ -2608,4 +2686,4 @@ declare const FERRICSTORE_NATIVE_PROTOCOL_VERSION = 1;
 /** @deprecated Use RequestDisposition; retained for source compatibility. */
 type ConnectionRequestDisposition = RequestDisposition;
 
-export { type AdminListOptions, type ApprovalListOptions, type ApprovalRequestOptions, type AttributeQueryOptions, type AutoBatchOptions, type BackoffKind, type BackpressurePolicy, BitmapStore, BloomFilterStore, type BudgetCommitOptions, type BudgetReserveOptions, COMMAND_OPCODES, type CancelOptions, ChildSpec, type CircuitOpenOptions, type ClaimDueOptions, ClaimHydrationError, type ClaimHydrationItem, ClaimedItem, type Codec, type CollectionScanOptions, Command, CommandArgument, type CommandExecutor, type CompleteJobsAndClaimJobsResult, type CompleteManyOptions, type CompleteOptions, ConnectionClosedError, type ConnectionRequestDisposition, type CountMinMergeOptions, CountMinSketchStore, CreateItem, type CreateManyOptions, type CreateOptions, CuckooFilterStore, type EffectCompensateOptions, type EffectConfirmOptions, type EffectFailOptions, type EffectReserveOptions, type EffectStatusOptions, type EndpointPolicy, type ExceptionPolicy, type ExecutePipelineOptions, type ExpiryCondition, type ExtendLeaseOptions, FERRICSTORE_MINIMUM_SERVER_VERSION, FERRICSTORE_NATIVE_PROTOCOL_VERSION, FERRICSTORE_SDK_VERSION, type FailOptions, FencedItem, FencingToken, FerricStoreClient, type FerricStoreClientFromUrlOptions, type FerricStoreClientOptions, FerricStoreError, FetchOrComputeResult, type FlowAdminRecord, FlowAlreadyExistsError, type FlowBatchCompletedItem, FlowBatchError, type FlowEventProjectionField, type FlowExplainCapabilities, type FlowExplainResult, FlowNotFoundError, type FlowPolicyBackoffKind, type FlowPolicyBackoffSnapshot, type FlowPolicyOptions, type FlowPolicyRetentionSnapshot, type FlowPolicyRetrySnapshot, type FlowPolicySnapshot, type FlowPolicyStateSnapshot, FlowProjection, type FlowProjectionField, type FlowProjectionShape, type FlowQueryCountResult, FlowQueryError, type FlowQueryErrorPosition, type FlowQueryIndex, type FlowQueryIndexBuild, type FlowQueryIndexCoverage, type FlowQueryIndexField, type FlowQueryIndexFormat, type FlowQueryIndexProgress, type FlowQueryIndexRegistry, type FlowQueryIndexRetirement, type FlowQueryIndexServiceState, type FlowQueryIndexServices, type FlowQueryIndexStatistics, type FlowQueryIndexStatus, type FlowQueryIndexValidation, type FlowQueryInteger, type FlowQueryPage, type FlowQueryParameter, type FlowQueryParameters, type FlowQueryQuality, type FlowQueryRecord, type FlowQueryRecordsResult, type FlowQueryResult, type FlowQueryUsage, FlowRecord, type FlowRunProjectionField, type FlowStateMode, type FlowStatePolicy, type FlowStatePolicyLike, type FlowStatsOptions, FlowWrongStateError, type GeoAddOptions, type GeoMember, GeoStore, type GetExOptions, type GovernanceLedgerOptions, HTTPAdapter, type HTTPAdapterOptions, type HTTPCommandDisposition, HTTPTransportError, type HashScanResult, HashStore, type HistoryOptions, HyperLogLogStore, type IntegerReply, InvalidCommandError, type InvocationCreateOptions, JsonCodec, KeyInfo, KeyValueStore, type LeaseMutationOptions, LeaseRenewalError, type LimitAmountOptions, type LimitLeaseOptions, type LimitListOptions, type LimitReleaseOptions, ListStore, LockHeldError, LockNotOwnedError, MAX_FLOW_POLICY_GENERATION, type ManagementPairs, MaxActiveMs, type MutateOptions, NativeAdapter, type NativeAdapterOptions, type NativeClientOptions, type NativeProtocolEvent, Outcome, OverloadedError, type ProtocolCommand, Queue, type QueueBatchHandler, QueueClient, QueueCompletionError, type QueueHandler, type QueueJob, type QueueOptions, QueueWorker, type QueueWorkerResult, type RangeLimit, RateLimitResult, RawCodec, type ReadOptions, type ReclaimOptions, type ReconnectOptions, ReconnectingExecutor, type RequestContext, type RequestContextOptions, type RequestDisposition, RequestTimeoutError, RerouteError, type RetryOptions, type RetryPolicy, type RoutingEndpoint, type RoutingRoute, RoutingTopology, type RunStepsItem, type RunStepsManyOptions, type ScanOptions, type ScheduleCatchupPolicy, type ScheduleFireDueOptions, type ScheduleFireDueResult, type ScheduleFireOptions, type ScheduleFireResult, type ScheduleKind, type ScheduleListOptions, type ScheduleOptions, type ScheduleOverlapPolicy, type ScheduleRecord, type ScheduleState, type SearchOptions, type SearchStateMeta, type SetOptions, type SetScanResult, SetStore, type SortedSetScanResult, SortedSetStore, StaleLeaseError, StalePolicyGenerationError, type StartAndClaimOptions, StateMeta, type StateOptions, type StateRegistration, type StepContinueOptions, type StoreCommandClient, StreamStore, type TDigestCreateOptions, type TDigestMergeOptions, TDigestStore, type TopKReserveOptions, TopKStore, type TopologyNativeAdapterOptions, TopologyNativeAdapterPool, type TransitionOptions, type ValueConfig, type WorkerConfig, type WorkerProfile, type WorkerRefillStrategy, Workflow, WorkflowClient, WorkflowContext, WorkflowFlowCommands, type WorkflowHandler, type WorkflowOptions, WorkflowWorker, type WorkflowWorkerResult, type XReadStream, type ZAddMember, type ZAddOptions, classifyServerError, httpCommandDisposition, isReconnectableClosedConnectionError, mapException, projectFlowQuery };
+export { type AdminListOptions, type AdvanceOptions, AlreadyAppliedOutcome, type ApprovalListOptions, type ApprovalRequestOptions, type AttributeQueryOptions, type AutoBatchOptions, type BackoffKind, type BackpressurePolicy, BitmapStore, BloomFilterStore, type BudgetCommitOptions, type BudgetReserveOptions, COMMAND_OPCODES, type CancelOptions, ChildSpec, type CircuitOpenOptions, type ClaimDueOptions, ClaimHydrationError, type ClaimHydrationItem, ClaimedItem, type Codec, type CollectionScanOptions, Command, CommandArgument, type CommandExecutor, type CompleteJobsAndClaimJobsResult, type CompleteManyOptions, type CompleteOptions, ConnectionClosedError, type ConnectionRequestDisposition, type CountMinMergeOptions, CountMinSketchStore, CreateItem, type CreateManyOptions, type CreateOptions, CuckooFilterStore, type EffectCompensateOptions, type EffectConfirmOptions, type EffectFailOptions, type EffectReserveOptions, type EffectStatusOptions, type EndpointPolicy, type ExceptionPolicy, type ExecutePipelineOptions, type ExpiryCondition, type ExtendLeaseOptions, FERRICSTORE_MINIMUM_SERVER_VERSION, FERRICSTORE_NATIVE_PROTOCOL_VERSION, FERRICSTORE_SDK_VERSION, type FailOptions, FencedItem, FencingToken, FerricStoreClient, type FerricStoreClientFromUrlOptions, type FerricStoreClientOptions, FerricStoreError, FetchOrComputeResult, type FlowAdminRecord, FlowAlreadyExistsError, type FlowBatchCompletedItem, FlowBatchError, type FlowEventProjectionField, type FlowExplainCapabilities, type FlowExplainResult, FlowNotFoundError, type FlowPolicyBackoffKind, type FlowPolicyBackoffSnapshot, type FlowPolicyOptions, type FlowPolicyRetentionSnapshot, type FlowPolicyRetrySnapshot, type FlowPolicySnapshot, type FlowPolicyStateSnapshot, FlowProjection, type FlowProjectionField, type FlowProjectionShape, type FlowQueryCountResult, FlowQueryError, type FlowQueryErrorPosition, type FlowQueryIndex, type FlowQueryIndexBuild, type FlowQueryIndexCoverage, type FlowQueryIndexField, type FlowQueryIndexFormat, type FlowQueryIndexProgress, type FlowQueryIndexRegistry, type FlowQueryIndexRetirement, type FlowQueryIndexServiceState, type FlowQueryIndexServices, type FlowQueryIndexStatistics, type FlowQueryIndexStatus, type FlowQueryIndexValidation, type FlowQueryInteger, type FlowQueryPage, type FlowQueryParameter, type FlowQueryParameters, type FlowQueryQuality, type FlowQueryRecord, type FlowQueryRecordsResult, type FlowQueryResult, type FlowQueryUsage, FlowRecord, type FlowRunProjectionField, type FlowStateMode, type FlowStatePolicy, type FlowStatePolicyLike, type FlowStatsOptions, FlowWrongStateError, type GeoAddOptions, type GeoMember, GeoStore, type GetExOptions, type GovernanceLedgerOptions, HTTPAdapter, type HTTPAdapterOptions, type HTTPCommandDisposition, HTTPTransportError, type HashScanResult, HashStore, type HistoryOptions, HyperLogLogStore, type IntegerReply, InvalidCommandError, type InvocationCreateOptions, JsonCodec, KeyInfo, KeyValueStore, type LeaseMutationOptions, LeaseRenewalError, type LimitAmountOptions, type LimitLeaseOptions, type LimitListOptions, type LimitReleaseOptions, ListStore, LockHeldError, LockNotOwnedError, MAX_FLOW_POLICY_GENERATION, type ManagementPairs, MaxActiveMs, type MutateOptions, NativeAdapter, type NativeAdapterOptions, type NativeClientOptions, type NativeProtocolEvent, Outcome, OverloadedError, type ProtocolCommand, Queue, type QueueBatchHandler, QueueClient, QueueCompletionError, type QueueHandler, type QueueJob, type QueueOptions, QueueWorker, type QueueWorkerResult, type RangeLimit, RateLimitResult, RawCodec, type ReadOptions, type ReclaimOptions, type ReconnectOptions, ReconnectingExecutor, type RequestContext, type RequestContextOptions, type RequestDisposition, RequestNotSentError, RequestTimeoutError, RerouteError, type RetryOptions, type RetryPolicy, type RoutingEndpoint, type RoutingRoute, RoutingTopology, type RunStepsItem, type RunStepsManyOptions, type ScanOptions, type ScheduleCatchupPolicy, type ScheduleFireDueOptions, type ScheduleFireDueResult, type ScheduleFireOptions, type ScheduleFireResult, type ScheduleKind, type ScheduleListOptions, type ScheduleOptions, type ScheduleOverlapPolicy, type ScheduleRecord, type ScheduleState, type SearchOptions, type SearchStateMeta, type SetOptions, type SetScanResult, SetStore, type SortedSetScanResult, SortedSetStore, StaleLeaseError, StalePolicyGenerationError, type StartAndClaimOptions, StateMeta, type StateOptions, type StateRegistration, type StepContinueOptions, type StepOptions, type StepResult, type StoreCommandClient, StreamStore, type TDigestCreateOptions, type TDigestMergeOptions, TDigestStore, type TopKReserveOptions, TopKStore, type TopologyNativeAdapterOptions, TopologyNativeAdapterPool, type TransitionOptions, type ValueConfig, type WorkerConfig, type WorkerProfile, type WorkerRefillStrategy, Workflow, WorkflowClient, WorkflowContext, WorkflowFlowCommands, type WorkflowHandler, type WorkflowOptions, WorkflowStepResult, WorkflowWorker, type WorkflowWorkerResult, type XReadStream, type ZAddMember, type ZAddOptions, classifyServerError, httpCommandDisposition, isReconnectableClosedConnectionError, mapException, projectFlowQuery };