@ferricstore/ferricstore 0.1.7 → 0.3.0

package/dist/index.d.cts

@@ -4,9 +4,15 @@ import { Buffer as Buffer$1 } from 'node:buffer';
 declare class FerricStoreError extends Error {
     readonly code: string;
     readonly raw: unknown;
+    readonly retryable: boolean | undefined;
+    readonly safeToRetry: boolean | undefined;
+    readonly retryAfterMs: number | undefined;
     constructor(message: string, options?: {
         raw?: unknown;
         cause?: unknown;
+        retryable?: boolean;
+        safeToRetry?: boolean;
+        retryAfterMs?: number;
     });
 }
 type RequestDisposition = "unsent" | "possibly_sent";
@@ -39,6 +45,10 @@ declare class FlowWrongStateError extends FerricStoreError {
 declare class StaleLeaseError extends FerricStoreError {
     readonly code = "stale_lease";
 }
+/** FLOW.POLICY.SET expected_generation did not match the stored generation. */
+declare class StalePolicyGenerationError extends FerricStoreError {
+    readonly code = "stale_policy_generation";
+}
 declare class FlowAlreadyExistsError extends FerricStoreError {
     readonly code = "flow_already_exists";
 }
@@ -53,13 +63,14 @@ declare class InvalidCommandError extends FerricStoreError {
 }
 declare class OverloadedError extends FerricStoreError {
     readonly code = "overloaded";
-    readonly retryAfterMs: number | undefined;
     readonly reason: string | undefined;
     constructor(message: string, options?: {
         raw?: unknown;
         cause?: unknown;
         retryAfterMs?: number;
         reason?: string;
+        retryable?: boolean;
+        safeToRetry?: boolean;
     });
 }
 /** The contacted endpoint cannot serve this route and topology should be refreshed. */
@@ -391,16 +402,6 @@ declare const COMMAND_OPCODES: {
     readonly "FERRICSTORE.METRICS": 783;
     readonly "FERRICSTORE.BLOBGC": 784;
 };
-/** Direct compact response kinds advertised by the FerricStore native protocol. */
-declare const COMPACT_RESPONSE_OPCODES: {
-    readonly flow_claim_jobs_v1: readonly [515];
-    readonly flow_record_list_v1: readonly [526, 535, 536, 537, 538, 539, 541];
-    readonly flow_record_v1: readonly [514];
-    readonly kv_get_v1: readonly [257];
-    readonly kv_mget_v1: readonly [260, 524];
-    readonly ok_list_v1: readonly [258, 261, 527, 528, 530, 531, 532];
-    readonly pipeline_v1: readonly [14];
-};
 interface ProtocolCommand {
     readonly opcode: number;
     readonly payload: unknown;
@@ -428,9 +429,9 @@ declare class NativeAdapter implements CommandExecutor {
     private readonly closedWaiters;
     private readonly chunkAssembler;
     private closed;
+    private readonly capabilities;
     private protocolLanes;
     private maxPipelineCommands;
-    private maxRequestFrameBytes;
     private pendingControlRequests;
     private readonly maxPendingControlRequests;
     private readonly heartbeat;
@@ -641,17 +642,7 @@ interface FetchOrComputeHitResult<T = unknown> {
     readonly status: "hit";
     readonly value: T | null;
 }
-interface FetchOrComputeLegacyResult {
-    /** Opaque application hint echoed for the process elected to compute. */
-    readonly computeHint: Buffer;
-    readonly computeMode: "legacy";
-    /** Explicit null distinguishes a legacy tokenless lease from an omitted token. */
-    readonly computeToken: null;
-    readonly hit: false;
-    readonly shouldCompute: true;
-    readonly status: "compute";
-}
-interface FetchOrComputeFencedResult {
+interface FetchOrComputeComputeResult {
     /** Opaque application hint echoed for the process elected to compute. */
     readonly computeHint: Buffer;
     readonly computeMode: "fenced";
@@ -661,8 +652,12 @@ interface FetchOrComputeFencedResult {
     readonly shouldCompute: true;
     readonly status: "compute";
 }
-type FetchOrComputeComputeResult = FetchOrComputeLegacyResult | FetchOrComputeFencedResult;
+type FetchOrComputeFencedResult = FetchOrComputeComputeResult;
 type FetchOrComputeResult<T = unknown> = FetchOrComputeHitResult<T> | FetchOrComputeComputeResult;
+interface FlowMaxActiveFailure {
+    readonly maxActiveMs: number;
+    readonly reason: "max_active_ms";
+}
 interface FlowRecord<TPayload = unknown> {
     id: string;
     type: string;
@@ -677,6 +672,8 @@ interface FlowRecord<TPayload = unknown> {
     rootFlowId?: string;
     correlationId?: string;
     maxActiveMs?: number;
+    error?: unknown;
+    failureReason?: string;
     valueRefs?: Record<string, unknown>;
     values?: Record<string, unknown>;
     valueSizes?: Record<string, unknown>;
@@ -901,6 +898,8 @@ interface StartAndClaimOptions {
     nowMs?: number;
     priority?: number;
     retentionTtlMs?: number;
+    /** Maximum active lifetime from creation, or "infinity" to disable a type policy timeout. */
+    maxActiveMs?: MaxActiveMs;
     attributes?: Record<string, CommandArgument>;
     stateMeta?: StateMeta;
     values?: Record<string, unknown>;
@@ -965,6 +964,10 @@ interface FlowStatePolicy {
 }
 type FlowStatePolicyLike = FlowStatePolicy | RetryPolicy;
 interface FlowPolicyOptions {
+    /** Replace the complete stored policy instead of applying the default deep patch. */
+    replace?: boolean;
+    /** Compare-and-swap generation. Must be a nonnegative JavaScript safe integer. */
+    expectedGeneration?: number;
     state?: string;
     mode?: FlowStateMode;
     retry?: RetryPolicy;
@@ -1569,11 +1572,9 @@ declare class HashStore {
 type TopKReserveOptions = {
     width?: never;
     depth?: never;
-    decay?: never;
 } | {
     width: number;
     depth: number;
-    decay: number;
 };
 interface CountMinMergeOptions {
     weights?: readonly (number | bigint)[];
@@ -1753,10 +1754,10 @@ declare class FerricStoreClientCore extends FerricStoreAdministrationClient {
     }): Promise<FetchOrComputeResult<T>>;
     fetchOrComputeResult(key: string, value: unknown, options: {
         ttlMs: number;
-        computeToken: Buffer$1 | null;
+        computeToken: Buffer$1;
     }): Promise<boolean>;
     fetchOrComputeError(key: string, message: string, options: {
-        computeToken: Buffer$1 | null;
+        computeToken: Buffer$1;
     }): Promise<boolean>;
 }
 
@@ -1830,6 +1831,49 @@ declare class FerricStoreManagementClient extends FerricStoreClientCore {
     governanceLedger(id: string, options?: GovernanceLedgerOptions): Promise<FlowAdminRecord[]>;
 }
 
+declare const MAX_FLOW_POLICY_GENERATION: number;
+type FlowPolicyBackoffKind = "none" | "fixed" | "linear" | "exponential";
+interface FlowPolicyBackoffSnapshot {
+    readonly kind: FlowPolicyBackoffKind;
+    readonly baseMs: number;
+    readonly maxMs: number;
+    readonly jitterPct: number;
+}
+interface FlowPolicyRetrySnapshot {
+    readonly maxRetries: number;
+    readonly backoff: FlowPolicyBackoffSnapshot;
+    readonly exhaustedTo: string;
+}
+interface FlowPolicyRetentionSnapshot {
+    readonly ttlMs: number;
+    readonly historyMaxEvents: number;
+}
+interface FlowPolicyStateSnapshot {
+    readonly mode: FlowStateMode;
+    readonly maxActiveMs?: number;
+    readonly retry: FlowPolicyRetrySnapshot;
+    readonly retention: FlowPolicyRetentionSnapshot;
+    readonly governance?: Readonly<Record<string, unknown>>;
+}
+/** Resolved policy state returned by FLOW.POLICY.SET and FLOW.POLICY.GET. */
+interface FlowPolicySnapshot {
+    readonly type: string;
+    /** Server-allocated monotonic generation in the JavaScript safe-integer range. */
+    readonly generation: number;
+    readonly state?: string;
+    readonly version?: string | number;
+    readonly mode?: FlowStateMode;
+    readonly maxActiveMs?: number;
+    readonly retry: FlowPolicyRetrySnapshot;
+    readonly retention: FlowPolicyRetentionSnapshot;
+    readonly indexedAttributes: readonly string[];
+    readonly indexedStateMeta?: string;
+    readonly governance?: Readonly<Record<string, unknown>>;
+    readonly states?: Readonly<Record<string, FlowPolicyStateSnapshot>>;
+    /** Original protocol value for forward-compatible fields not yet modeled by the SDK. */
+    readonly raw: unknown;
+}
+
 /** @internal Read, policy, and shared Flow helpers kept off the primary implementation module. */
 declare class FerricStoreFlowSupportClient extends FerricStoreManagementClient {
     rewind(id: string, options?: {
@@ -1879,10 +1923,10 @@ declare class FerricStoreFlowSupportClient extends FerricStoreManagementClient {
         values?: Record<string, unknown>;
         valueRefs?: Record<string, string>;
     }): Promise<unknown>;
-    installPolicy(type: string, options?: FlowPolicyOptions): Promise<unknown>;
+    installPolicy(type: string, options?: FlowPolicyOptions): Promise<FlowPolicySnapshot>;
     policyGet(type: string, options?: {
         state?: string;
-    }): Promise<Record<string, unknown>>;
+    }): Promise<FlowPolicySnapshot>;
     retentionCleanup(): Promise<Record<string, unknown>>;
     protected executeProducerWrite(args: CommandArgument[]): Promise<unknown>;
     protected recordOrGet(response: unknown, id: string, partitionKey: string | undefined): Promise<FlowRecord>;
@@ -2006,7 +2050,6 @@ declare class FerricStoreClient extends FerricStoreProducerClient {
         transitionTo?: string;
         runAtMs?: number;
         nowMs?: number;
-        priority?: number;
         values?: Record<string, unknown>;
         valueRefs?: Record<string, string>;
         dropValues?: string[];
@@ -2338,7 +2381,7 @@ declare class Workflow {
     worker(options?: WorkerConfig & {
         states?: string[];
     }): WorkflowWorker;
-    installPolicy(options?: Omit<FlowPolicyOptions, "mode" | "state" | "states">): Promise<unknown>;
+    installPolicy(options?: Omit<FlowPolicyOptions, "mode" | "state" | "states">): Promise<FlowPolicySnapshot>;
     stateNames(): string[];
     stateRegistration(name: string): StateRegistration | undefined;
 }
@@ -2360,7 +2403,14 @@ declare class WorkflowWorker {
     private applyHandlerError;
 }
 
+/** TypeScript SDK package version. */
+declare const FERRICSTORE_SDK_VERSION = "0.3.0";
+/** Oldest FerricStore server supported by this breaking beta contract. */
+declare const FERRICSTORE_MINIMUM_SERVER_VERSION = "0.9.1";
+/** Native framing and opcode ABI version; unchanged by FerricStore 0.9.1. */
+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, COMPACT_RESPONSE_OPCODES, type CancelOptions, type ChildSpec, type CircuitOpenOptions, type ClaimDueOptions, ClaimHydrationError, type ClaimHydrationItem, type ClaimedItem, type Codec, type CollectionScanOptions, type Command, type CommandArgument, type CommandExecutor, type CompleteJobsAndClaimJobsResult, type CompleteManyOptions, type CompleteOptions, type CompleteOutcome, ConnectionClosedError, type ConnectionRequestDisposition, type CountMinMergeOptions, CountMinSketchStore, type 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, type FailOptions, type FailOutcome, type FencedItem, type FencingToken, FerricStoreClient, type FerricStoreClientFromUrlOptions, type FerricStoreClientOptions, FerricStoreError, type FetchOrComputeComputeResult, type FetchOrComputeFencedResult, type FetchOrComputeHitResult, type FetchOrComputeLegacyResult, type FetchOrComputeResult, type FlowAdminRecord, FlowAlreadyExistsError, type FlowBatchCompletedItem, FlowBatchError, FlowNotFoundError, type FlowPolicyOptions, type FlowRecord, type FlowStateMode, type FlowStatePolicy, type FlowStatePolicyLike, type FlowStatsOptions, FlowWrongStateError, type GeoAddOptions, type GeoMember, GeoStore, type GetExOptions, type GovernanceLedgerOptions, type HashScanResult, HashStore, type HistoryOptions, HyperLogLogStore, type IntegerReply, InvalidCommandError, type InvocationCreateOptions, JsonCodec, type KeyInfo, KeyValueStore, type LeaseMutationOptions, LeaseRenewalError, type LimitAmountOptions, type LimitLeaseOptions, type LimitListOptions, type LimitReleaseOptions, ListStore, LockHeldError, LockNotOwnedError, type ManagementPairs, type MaxActiveMs, type MutateOptions, type NamedValueMutation, NativeAdapter, type NativeAdapterOptions, type NativeClientOptions, type NativeProtocolEvent, type Outcome, OverloadedError, type ProtocolCommand, Queue, type QueueBatchHandler, QueueClient, QueueCompletionError, type QueueHandler, type QueueJob, type QueueOptions, QueueWorker, type QueueWorkerResult, type RangeLimit, type RateLimitResult, RawCodec, type ReadOptions, type ReclaimOptions, type ReconnectOptions, ReconnectingExecutor, type RequestContext, type RequestContextOptions, type RequestDisposition, RequestTimeoutError, RerouteError, type RetryOptions, type RetryOutcome, type RetryPolicy, type RoutingEndpoint, type RoutingRoute, RoutingTopology, type RunStepsItem, type RunStepsManyOptions, type ScanOptions, type ScheduleFireDueOptions, type ScheduleListOptions, type ScheduleOptions, type SearchOptions, type SearchStateMeta, type SetOptions, type SetScanResult, SetStore, type SortedSetScanResult, SortedSetStore, StaleLeaseError, type StartAndClaimOptions, type StateMeta, type StateMetaValue, type StateOptions, type StateRegistration, type StepContinueOptions, type StoreCommandClient, StreamStore, type TDigestCreateOptions, type TDigestMergeOptions, TDigestStore, type TopKReserveOptions, TopKStore, type TopologyNativeAdapterOptions, TopologyNativeAdapterPool, type TransitionOptions, type TransitionOutcome, 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, complete, fail, isOutcome, isReconnectableClosedConnectionError, mapException, retry, transition };
+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, type ChildSpec, type CircuitOpenOptions, type ClaimDueOptions, ClaimHydrationError, type ClaimHydrationItem, type ClaimedItem, type Codec, type CollectionScanOptions, type Command, type CommandArgument, type CommandExecutor, type CompleteJobsAndClaimJobsResult, type CompleteManyOptions, type CompleteOptions, type CompleteOutcome, ConnectionClosedError, type ConnectionRequestDisposition, type CountMinMergeOptions, CountMinSketchStore, type 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, type FailOutcome, type FencedItem, type FencingToken, FerricStoreClient, type FerricStoreClientFromUrlOptions, type FerricStoreClientOptions, FerricStoreError, type FetchOrComputeComputeResult, type FetchOrComputeFencedResult, type FetchOrComputeHitResult, type FetchOrComputeResult, type FlowAdminRecord, FlowAlreadyExistsError, type FlowBatchCompletedItem, FlowBatchError, type FlowMaxActiveFailure, FlowNotFoundError, type FlowPolicyBackoffKind, type FlowPolicyBackoffSnapshot, type FlowPolicyOptions, type FlowPolicyRetentionSnapshot, type FlowPolicyRetrySnapshot, type FlowPolicySnapshot, type FlowPolicyStateSnapshot, type FlowRecord, type FlowStateMode, type FlowStatePolicy, type FlowStatePolicyLike, type FlowStatsOptions, FlowWrongStateError, type GeoAddOptions, type GeoMember, GeoStore, type GetExOptions, type GovernanceLedgerOptions, type HashScanResult, HashStore, type HistoryOptions, HyperLogLogStore, type IntegerReply, InvalidCommandError, type InvocationCreateOptions, JsonCodec, type KeyInfo, KeyValueStore, type LeaseMutationOptions, LeaseRenewalError, type LimitAmountOptions, type LimitLeaseOptions, type LimitListOptions, type LimitReleaseOptions, ListStore, LockHeldError, LockNotOwnedError, MAX_FLOW_POLICY_GENERATION, type ManagementPairs, type MaxActiveMs, type MutateOptions, type NamedValueMutation, NativeAdapter, type NativeAdapterOptions, type NativeClientOptions, type NativeProtocolEvent, type Outcome, OverloadedError, type ProtocolCommand, Queue, type QueueBatchHandler, QueueClient, QueueCompletionError, type QueueHandler, type QueueJob, type QueueOptions, QueueWorker, type QueueWorkerResult, type RangeLimit, type RateLimitResult, RawCodec, type ReadOptions, type ReclaimOptions, type ReconnectOptions, ReconnectingExecutor, type RequestContext, type RequestContextOptions, type RequestDisposition, RequestTimeoutError, RerouteError, type RetryOptions, type RetryOutcome, type RetryPolicy, type RoutingEndpoint, type RoutingRoute, RoutingTopology, type RunStepsItem, type RunStepsManyOptions, type ScanOptions, type ScheduleFireDueOptions, type ScheduleListOptions, type ScheduleOptions, type SearchOptions, type SearchStateMeta, type SetOptions, type SetScanResult, SetStore, type SortedSetScanResult, SortedSetStore, StaleLeaseError, StalePolicyGenerationError, type StartAndClaimOptions, type StateMeta, type StateMetaValue, type StateOptions, type StateRegistration, type StepContinueOptions, type StoreCommandClient, StreamStore, type TDigestCreateOptions, type TDigestMergeOptions, TDigestStore, type TopKReserveOptions, TopKStore, type TopologyNativeAdapterOptions, TopologyNativeAdapterPool, type TransitionOptions, type TransitionOutcome, 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, complete, fail, isOutcome, isReconnectableClosedConnectionError, mapException, retry, transition };

package/dist/index.d.ts

@@ -4,9 +4,15 @@ import { Buffer as Buffer$1 } from 'node:buffer';
 declare class FerricStoreError extends Error {
     readonly code: string;
     readonly raw: unknown;
+    readonly retryable: boolean | undefined;
+    readonly safeToRetry: boolean | undefined;
+    readonly retryAfterMs: number | undefined;
     constructor(message: string, options?: {
         raw?: unknown;
         cause?: unknown;
+        retryable?: boolean;
+        safeToRetry?: boolean;
+        retryAfterMs?: number;
     });
 }
 type RequestDisposition = "unsent" | "possibly_sent";
@@ -39,6 +45,10 @@ declare class FlowWrongStateError extends FerricStoreError {
 declare class StaleLeaseError extends FerricStoreError {
     readonly code = "stale_lease";
 }
+/** FLOW.POLICY.SET expected_generation did not match the stored generation. */
+declare class StalePolicyGenerationError extends FerricStoreError {
+    readonly code = "stale_policy_generation";
+}
 declare class FlowAlreadyExistsError extends FerricStoreError {
     readonly code = "flow_already_exists";
 }
@@ -53,13 +63,14 @@ declare class InvalidCommandError extends FerricStoreError {
 }
 declare class OverloadedError extends FerricStoreError {
     readonly code = "overloaded";
-    readonly retryAfterMs: number | undefined;
     readonly reason: string | undefined;
     constructor(message: string, options?: {
         raw?: unknown;
         cause?: unknown;
         retryAfterMs?: number;
         reason?: string;
+        retryable?: boolean;
+        safeToRetry?: boolean;
     });
 }
 /** The contacted endpoint cannot serve this route and topology should be refreshed. */
@@ -391,16 +402,6 @@ declare const COMMAND_OPCODES: {
     readonly "FERRICSTORE.METRICS": 783;
     readonly "FERRICSTORE.BLOBGC": 784;
 };
-/** Direct compact response kinds advertised by the FerricStore native protocol. */
-declare const COMPACT_RESPONSE_OPCODES: {
-    readonly flow_claim_jobs_v1: readonly [515];
-    readonly flow_record_list_v1: readonly [526, 535, 536, 537, 538, 539, 541];
-    readonly flow_record_v1: readonly [514];
-    readonly kv_get_v1: readonly [257];
-    readonly kv_mget_v1: readonly [260, 524];
-    readonly ok_list_v1: readonly [258, 261, 527, 528, 530, 531, 532];
-    readonly pipeline_v1: readonly [14];
-};
 interface ProtocolCommand {
     readonly opcode: number;
     readonly payload: unknown;
@@ -428,9 +429,9 @@ declare class NativeAdapter implements CommandExecutor {
     private readonly closedWaiters;
     private readonly chunkAssembler;
     private closed;
+    private readonly capabilities;
     private protocolLanes;
     private maxPipelineCommands;
-    private maxRequestFrameBytes;
     private pendingControlRequests;
     private readonly maxPendingControlRequests;
     private readonly heartbeat;
@@ -641,17 +642,7 @@ interface FetchOrComputeHitResult<T = unknown> {
     readonly status: "hit";
     readonly value: T | null;
 }
-interface FetchOrComputeLegacyResult {
-    /** Opaque application hint echoed for the process elected to compute. */
-    readonly computeHint: Buffer;
-    readonly computeMode: "legacy";
-    /** Explicit null distinguishes a legacy tokenless lease from an omitted token. */
-    readonly computeToken: null;
-    readonly hit: false;
-    readonly shouldCompute: true;
-    readonly status: "compute";
-}
-interface FetchOrComputeFencedResult {
+interface FetchOrComputeComputeResult {
     /** Opaque application hint echoed for the process elected to compute. */
     readonly computeHint: Buffer;
     readonly computeMode: "fenced";
@@ -661,8 +652,12 @@ interface FetchOrComputeFencedResult {
     readonly shouldCompute: true;
     readonly status: "compute";
 }
-type FetchOrComputeComputeResult = FetchOrComputeLegacyResult | FetchOrComputeFencedResult;
+type FetchOrComputeFencedResult = FetchOrComputeComputeResult;
 type FetchOrComputeResult<T = unknown> = FetchOrComputeHitResult<T> | FetchOrComputeComputeResult;
+interface FlowMaxActiveFailure {
+    readonly maxActiveMs: number;
+    readonly reason: "max_active_ms";
+}
 interface FlowRecord<TPayload = unknown> {
     id: string;
     type: string;
@@ -677,6 +672,8 @@ interface FlowRecord<TPayload = unknown> {
     rootFlowId?: string;
     correlationId?: string;
     maxActiveMs?: number;
+    error?: unknown;
+    failureReason?: string;
     valueRefs?: Record<string, unknown>;
     values?: Record<string, unknown>;
     valueSizes?: Record<string, unknown>;
@@ -901,6 +898,8 @@ interface StartAndClaimOptions {
     nowMs?: number;
     priority?: number;
     retentionTtlMs?: number;
+    /** Maximum active lifetime from creation, or "infinity" to disable a type policy timeout. */
+    maxActiveMs?: MaxActiveMs;
     attributes?: Record<string, CommandArgument>;
     stateMeta?: StateMeta;
     values?: Record<string, unknown>;
@@ -965,6 +964,10 @@ interface FlowStatePolicy {
 }
 type FlowStatePolicyLike = FlowStatePolicy | RetryPolicy;
 interface FlowPolicyOptions {
+    /** Replace the complete stored policy instead of applying the default deep patch. */
+    replace?: boolean;
+    /** Compare-and-swap generation. Must be a nonnegative JavaScript safe integer. */
+    expectedGeneration?: number;
     state?: string;
     mode?: FlowStateMode;
     retry?: RetryPolicy;
@@ -1569,11 +1572,9 @@ declare class HashStore {
 type TopKReserveOptions = {
     width?: never;
     depth?: never;
-    decay?: never;
 } | {
     width: number;
     depth: number;
-    decay: number;
 };
 interface CountMinMergeOptions {
     weights?: readonly (number | bigint)[];
@@ -1753,10 +1754,10 @@ declare class FerricStoreClientCore extends FerricStoreAdministrationClient {
     }): Promise<FetchOrComputeResult<T>>;
     fetchOrComputeResult(key: string, value: unknown, options: {
         ttlMs: number;
-        computeToken: Buffer$1 | null;
+        computeToken: Buffer$1;
     }): Promise<boolean>;
     fetchOrComputeError(key: string, message: string, options: {
-        computeToken: Buffer$1 | null;
+        computeToken: Buffer$1;
     }): Promise<boolean>;
 }
 
@@ -1830,6 +1831,49 @@ declare class FerricStoreManagementClient extends FerricStoreClientCore {
     governanceLedger(id: string, options?: GovernanceLedgerOptions): Promise<FlowAdminRecord[]>;
 }
 
+declare const MAX_FLOW_POLICY_GENERATION: number;
+type FlowPolicyBackoffKind = "none" | "fixed" | "linear" | "exponential";
+interface FlowPolicyBackoffSnapshot {
+    readonly kind: FlowPolicyBackoffKind;
+    readonly baseMs: number;
+    readonly maxMs: number;
+    readonly jitterPct: number;
+}
+interface FlowPolicyRetrySnapshot {
+    readonly maxRetries: number;
+    readonly backoff: FlowPolicyBackoffSnapshot;
+    readonly exhaustedTo: string;
+}
+interface FlowPolicyRetentionSnapshot {
+    readonly ttlMs: number;
+    readonly historyMaxEvents: number;
+}
+interface FlowPolicyStateSnapshot {
+    readonly mode: FlowStateMode;
+    readonly maxActiveMs?: number;
+    readonly retry: FlowPolicyRetrySnapshot;
+    readonly retention: FlowPolicyRetentionSnapshot;
+    readonly governance?: Readonly<Record<string, unknown>>;
+}
+/** Resolved policy state returned by FLOW.POLICY.SET and FLOW.POLICY.GET. */
+interface FlowPolicySnapshot {
+    readonly type: string;
+    /** Server-allocated monotonic generation in the JavaScript safe-integer range. */
+    readonly generation: number;
+    readonly state?: string;
+    readonly version?: string | number;
+    readonly mode?: FlowStateMode;
+    readonly maxActiveMs?: number;
+    readonly retry: FlowPolicyRetrySnapshot;
+    readonly retention: FlowPolicyRetentionSnapshot;
+    readonly indexedAttributes: readonly string[];
+    readonly indexedStateMeta?: string;
+    readonly governance?: Readonly<Record<string, unknown>>;
+    readonly states?: Readonly<Record<string, FlowPolicyStateSnapshot>>;
+    /** Original protocol value for forward-compatible fields not yet modeled by the SDK. */
+    readonly raw: unknown;
+}
+
 /** @internal Read, policy, and shared Flow helpers kept off the primary implementation module. */
 declare class FerricStoreFlowSupportClient extends FerricStoreManagementClient {
     rewind(id: string, options?: {
@@ -1879,10 +1923,10 @@ declare class FerricStoreFlowSupportClient extends FerricStoreManagementClient {
         values?: Record<string, unknown>;
         valueRefs?: Record<string, string>;
     }): Promise<unknown>;
-    installPolicy(type: string, options?: FlowPolicyOptions): Promise<unknown>;
+    installPolicy(type: string, options?: FlowPolicyOptions): Promise<FlowPolicySnapshot>;
     policyGet(type: string, options?: {
         state?: string;
-    }): Promise<Record<string, unknown>>;
+    }): Promise<FlowPolicySnapshot>;
     retentionCleanup(): Promise<Record<string, unknown>>;
     protected executeProducerWrite(args: CommandArgument[]): Promise<unknown>;
     protected recordOrGet(response: unknown, id: string, partitionKey: string | undefined): Promise<FlowRecord>;
@@ -2006,7 +2050,6 @@ declare class FerricStoreClient extends FerricStoreProducerClient {
         transitionTo?: string;
         runAtMs?: number;
         nowMs?: number;
-        priority?: number;
         values?: Record<string, unknown>;
         valueRefs?: Record<string, string>;
         dropValues?: string[];
@@ -2338,7 +2381,7 @@ declare class Workflow {
     worker(options?: WorkerConfig & {
         states?: string[];
     }): WorkflowWorker;
-    installPolicy(options?: Omit<FlowPolicyOptions, "mode" | "state" | "states">): Promise<unknown>;
+    installPolicy(options?: Omit<FlowPolicyOptions, "mode" | "state" | "states">): Promise<FlowPolicySnapshot>;
     stateNames(): string[];
     stateRegistration(name: string): StateRegistration | undefined;
 }
@@ -2360,7 +2403,14 @@ declare class WorkflowWorker {
     private applyHandlerError;
 }
 
+/** TypeScript SDK package version. */
+declare const FERRICSTORE_SDK_VERSION = "0.3.0";
+/** Oldest FerricStore server supported by this breaking beta contract. */
+declare const FERRICSTORE_MINIMUM_SERVER_VERSION = "0.9.1";
+/** Native framing and opcode ABI version; unchanged by FerricStore 0.9.1. */
+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, COMPACT_RESPONSE_OPCODES, type CancelOptions, type ChildSpec, type CircuitOpenOptions, type ClaimDueOptions, ClaimHydrationError, type ClaimHydrationItem, type ClaimedItem, type Codec, type CollectionScanOptions, type Command, type CommandArgument, type CommandExecutor, type CompleteJobsAndClaimJobsResult, type CompleteManyOptions, type CompleteOptions, type CompleteOutcome, ConnectionClosedError, type ConnectionRequestDisposition, type CountMinMergeOptions, CountMinSketchStore, type 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, type FailOptions, type FailOutcome, type FencedItem, type FencingToken, FerricStoreClient, type FerricStoreClientFromUrlOptions, type FerricStoreClientOptions, FerricStoreError, type FetchOrComputeComputeResult, type FetchOrComputeFencedResult, type FetchOrComputeHitResult, type FetchOrComputeLegacyResult, type FetchOrComputeResult, type FlowAdminRecord, FlowAlreadyExistsError, type FlowBatchCompletedItem, FlowBatchError, FlowNotFoundError, type FlowPolicyOptions, type FlowRecord, type FlowStateMode, type FlowStatePolicy, type FlowStatePolicyLike, type FlowStatsOptions, FlowWrongStateError, type GeoAddOptions, type GeoMember, GeoStore, type GetExOptions, type GovernanceLedgerOptions, type HashScanResult, HashStore, type HistoryOptions, HyperLogLogStore, type IntegerReply, InvalidCommandError, type InvocationCreateOptions, JsonCodec, type KeyInfo, KeyValueStore, type LeaseMutationOptions, LeaseRenewalError, type LimitAmountOptions, type LimitLeaseOptions, type LimitListOptions, type LimitReleaseOptions, ListStore, LockHeldError, LockNotOwnedError, type ManagementPairs, type MaxActiveMs, type MutateOptions, type NamedValueMutation, NativeAdapter, type NativeAdapterOptions, type NativeClientOptions, type NativeProtocolEvent, type Outcome, OverloadedError, type ProtocolCommand, Queue, type QueueBatchHandler, QueueClient, QueueCompletionError, type QueueHandler, type QueueJob, type QueueOptions, QueueWorker, type QueueWorkerResult, type RangeLimit, type RateLimitResult, RawCodec, type ReadOptions, type ReclaimOptions, type ReconnectOptions, ReconnectingExecutor, type RequestContext, type RequestContextOptions, type RequestDisposition, RequestTimeoutError, RerouteError, type RetryOptions, type RetryOutcome, type RetryPolicy, type RoutingEndpoint, type RoutingRoute, RoutingTopology, type RunStepsItem, type RunStepsManyOptions, type ScanOptions, type ScheduleFireDueOptions, type ScheduleListOptions, type ScheduleOptions, type SearchOptions, type SearchStateMeta, type SetOptions, type SetScanResult, SetStore, type SortedSetScanResult, SortedSetStore, StaleLeaseError, type StartAndClaimOptions, type StateMeta, type StateMetaValue, type StateOptions, type StateRegistration, type StepContinueOptions, type StoreCommandClient, StreamStore, type TDigestCreateOptions, type TDigestMergeOptions, TDigestStore, type TopKReserveOptions, TopKStore, type TopologyNativeAdapterOptions, TopologyNativeAdapterPool, type TransitionOptions, type TransitionOutcome, 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, complete, fail, isOutcome, isReconnectableClosedConnectionError, mapException, retry, transition };
+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, type ChildSpec, type CircuitOpenOptions, type ClaimDueOptions, ClaimHydrationError, type ClaimHydrationItem, type ClaimedItem, type Codec, type CollectionScanOptions, type Command, type CommandArgument, type CommandExecutor, type CompleteJobsAndClaimJobsResult, type CompleteManyOptions, type CompleteOptions, type CompleteOutcome, ConnectionClosedError, type ConnectionRequestDisposition, type CountMinMergeOptions, CountMinSketchStore, type 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, type FailOutcome, type FencedItem, type FencingToken, FerricStoreClient, type FerricStoreClientFromUrlOptions, type FerricStoreClientOptions, FerricStoreError, type FetchOrComputeComputeResult, type FetchOrComputeFencedResult, type FetchOrComputeHitResult, type FetchOrComputeResult, type FlowAdminRecord, FlowAlreadyExistsError, type FlowBatchCompletedItem, FlowBatchError, type FlowMaxActiveFailure, FlowNotFoundError, type FlowPolicyBackoffKind, type FlowPolicyBackoffSnapshot, type FlowPolicyOptions, type FlowPolicyRetentionSnapshot, type FlowPolicyRetrySnapshot, type FlowPolicySnapshot, type FlowPolicyStateSnapshot, type FlowRecord, type FlowStateMode, type FlowStatePolicy, type FlowStatePolicyLike, type FlowStatsOptions, FlowWrongStateError, type GeoAddOptions, type GeoMember, GeoStore, type GetExOptions, type GovernanceLedgerOptions, type HashScanResult, HashStore, type HistoryOptions, HyperLogLogStore, type IntegerReply, InvalidCommandError, type InvocationCreateOptions, JsonCodec, type KeyInfo, KeyValueStore, type LeaseMutationOptions, LeaseRenewalError, type LimitAmountOptions, type LimitLeaseOptions, type LimitListOptions, type LimitReleaseOptions, ListStore, LockHeldError, LockNotOwnedError, MAX_FLOW_POLICY_GENERATION, type ManagementPairs, type MaxActiveMs, type MutateOptions, type NamedValueMutation, NativeAdapter, type NativeAdapterOptions, type NativeClientOptions, type NativeProtocolEvent, type Outcome, OverloadedError, type ProtocolCommand, Queue, type QueueBatchHandler, QueueClient, QueueCompletionError, type QueueHandler, type QueueJob, type QueueOptions, QueueWorker, type QueueWorkerResult, type RangeLimit, type RateLimitResult, RawCodec, type ReadOptions, type ReclaimOptions, type ReconnectOptions, ReconnectingExecutor, type RequestContext, type RequestContextOptions, type RequestDisposition, RequestTimeoutError, RerouteError, type RetryOptions, type RetryOutcome, type RetryPolicy, type RoutingEndpoint, type RoutingRoute, RoutingTopology, type RunStepsItem, type RunStepsManyOptions, type ScanOptions, type ScheduleFireDueOptions, type ScheduleListOptions, type ScheduleOptions, type SearchOptions, type SearchStateMeta, type SetOptions, type SetScanResult, SetStore, type SortedSetScanResult, SortedSetStore, StaleLeaseError, StalePolicyGenerationError, type StartAndClaimOptions, type StateMeta, type StateMetaValue, type StateOptions, type StateRegistration, type StepContinueOptions, type StoreCommandClient, StreamStore, type TDigestCreateOptions, type TDigestMergeOptions, TDigestStore, type TopKReserveOptions, TopKStore, type TopologyNativeAdapterOptions, TopologyNativeAdapterPool, type TransitionOptions, type TransitionOutcome, 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, complete, fail, isOutcome, isReconnectableClosedConnectionError, mapException, retry, transition };