@ferricstore/ferricstore 0.12.0 → 0.12.1

package/dist/openai-agents.d.cts

@@ -10,14 +10,17 @@ interface FerricStoreSessionOptions extends FerricStoreLockOptions {
     initialItems?: AgentInputItem[];
     /** FerricStore key prefix. Defaults to `openai:agents:session`. */
     keyPrefix?: string;
+    /** Previous worker locales to accept when migrating unversioned operation receipts. */
+    legacyReceiptLocales?: string[];
 }
 /**
  * Durable OpenAI Agents SDK conversation history backed by FerricStore.
  *
- * Every mutation is serialized by an ownership-checked, renewable FerricStore
- * lock. History transactions and their operation receipts are persisted in one
- * atomic hash-field write, implementing the SDK's retry-safe transaction
- * capability in addition to its base Session contract.
+ * Renewable locks reduce contention, while compare-and-swap makes every state
+ * commit safe even if a writer's lease expires in flight. History transactions
+ * and their operation receipts are persisted in one atomic value, implementing
+ * the SDK's retry-safe transaction capability in addition to its base Session
+ * contract.
  */
 declare class FerricStoreSession implements Session, SessionHistoryRewriteAwareSession, SessionHistoryTransactionAwareSession {
     readonly client: FerricStoreCommandClient;
@@ -25,7 +28,9 @@ declare class FerricStoreSession implements Session, SessionHistoryRewriteAwareS
     readonly keyPrefix: string;
     private readonly initialItems;
     private readonly lockOptions;
+    private readonly legacyReceiptLocales;
     private readonly sessionKey;
+    private readonly stateKey;
     private readonly lockKey;
     constructor(client: FerricStoreCommandClient, options?: FerricStoreSessionOptions);
     getSessionId(): Promise<string>;
@@ -38,6 +43,7 @@ declare class FerricStoreSession implements Session, SessionHistoryRewriteAwareS
     applyHistoryTransaction(args: SessionHistoryTransactionArgs): Promise<void>;
     private mutate;
     private readState;
+    private readMutationState;
     private emptyState;
 }
 

package/dist/openai-agents.d.ts

@@ -10,14 +10,17 @@ interface FerricStoreSessionOptions extends FerricStoreLockOptions {
     initialItems?: AgentInputItem[];
     /** FerricStore key prefix. Defaults to `openai:agents:session`. */
     keyPrefix?: string;
+    /** Previous worker locales to accept when migrating unversioned operation receipts. */
+    legacyReceiptLocales?: string[];
 }
 /**
  * Durable OpenAI Agents SDK conversation history backed by FerricStore.
  *
- * Every mutation is serialized by an ownership-checked, renewable FerricStore
- * lock. History transactions and their operation receipts are persisted in one
- * atomic hash-field write, implementing the SDK's retry-safe transaction
- * capability in addition to its base Session contract.
+ * Renewable locks reduce contention, while compare-and-swap makes every state
+ * commit safe even if a writer's lease expires in flight. History transactions
+ * and their operation receipts are persisted in one atomic value, implementing
+ * the SDK's retry-safe transaction capability in addition to its base Session
+ * contract.
  */
 declare class FerricStoreSession implements Session, SessionHistoryRewriteAwareSession, SessionHistoryTransactionAwareSession {
     readonly client: FerricStoreCommandClient;
@@ -25,7 +28,9 @@ declare class FerricStoreSession implements Session, SessionHistoryRewriteAwareS
     readonly keyPrefix: string;
     private readonly initialItems;
     private readonly lockOptions;
+    private readonly legacyReceiptLocales;
     private readonly sessionKey;
+    private readonly stateKey;
     private readonly lockKey;
     constructor(client: FerricStoreCommandClient, options?: FerricStoreSessionOptions);
     getSessionId(): Promise<string>;
@@ -38,6 +43,7 @@ declare class FerricStoreSession implements Session, SessionHistoryRewriteAwareS
     applyHistoryTransaction(args: SessionHistoryTransactionArgs): Promise<void>;
     private mutate;
     private readState;
+    private readMutationState;
     private emptyState;
 }
 

package/dist/openai-agents.js

@@ -104,14 +104,44 @@ function integerResponse(value, name) {
   if (!Number.isSafeInteger(parsed)) throw new TypeError(`FerricStore returned an invalid ${name}`);
   return parsed;
 }
+async function readAtomicValue(client, key, name) {
+  const value = await client.command("GET", key);
+  if (value == null) return void 0;
+  if (typeof value === "string") return Buffer.from(value, "utf8");
+  if (Buffer.isBuffer(value) || value instanceof Uint8Array) return Buffer.from(value);
+  throw new TypeError(`FerricStore returned a non-binary ${name}`);
+}
+async function compareAndSetAtomicValue(client, key, expected, value) {
+  if (expected == null) {
+    const response2 = await client.command("SET", key, value, "NX");
+    if (response2 == null || response2 === false) return false;
+    if (response2 === true) return true;
+    return textResponse(response2, "SET NX response").toUpperCase() === "OK";
+  }
+  const response = await client.command("CAS", key, expected, value);
+  if (response == null || response === false) return false;
+  if (response === true) return true;
+  return integerResponse(response, "CAS response") === 1;
+}
 async function withMutationLocks(client, keys, operation, options = {}) {
   const orderedKeys = [...new Set(keys)].sort();
-  if (orderedKeys.length === 0) return await operation();
+  if (orderedKeys.length === 0) {
+    const signal = new AbortController().signal;
+    return await operation({
+      signal,
+      assertOwned: () => void 0,
+      publish: async (...args) => await additiveCommand(client, args),
+      compareAndSet: async (key, expected, value) => await compareAndSetAtomicValue(client, key, expected, value)
+    });
+  }
   const normalized = {
     lockRetryMs: positiveInteger(options.lockRetryMs, DEFAULT_LOCK_OPTIONS.lockRetryMs, "lockRetryMs"),
     lockTtlMs: positiveInteger(options.lockTtlMs, DEFAULT_LOCK_OPTIONS.lockTtlMs, "lockTtlMs"),
     lockWaitMs: nonNegativeInteger(options.lockWaitMs, DEFAULT_LOCK_OPTIONS.lockWaitMs, "lockWaitMs")
   };
+  if (normalized.lockRetryMs >= normalized.lockTtlMs) {
+    throw new TypeError("lockRetryMs must be less than lockTtlMs");
+  }
   const owner = randomUUID();
   const acquired = [];
   const deadline = performance.now() + normalized.lockWaitMs;
@@ -120,29 +150,81 @@ async function withMutationLocks(client, keys, operation, options = {}) {
   let releaseError;
   let result;
   let operationCompleted = false;
+  let conditionalCommitCompleted = false;
   const heartbeatAbort = new AbortController();
+  const ownershipAbort = new AbortController();
+  const lastExtended = /* @__PURE__ */ new Map();
+  const loseOwnership = (error) => {
+    const normalizedError = errorObject(error);
+    heartbeatError ??= normalizedError;
+    if (!ownershipAbort.signal.aborted) ownershipAbort.abort(normalizedError);
+    return normalizedError;
+  };
+  const assertOwned = () => {
+    if (heartbeatError != null) throw errorObject(heartbeatError);
+    if (ownershipAbort.signal.aborted) throw errorObject(ownershipAbort.signal.reason);
+  };
+  const renewOwned = async () => {
+    assertOwned();
+    for (const key of acquired) {
+      try {
+        const response = await client.command("EXTEND", key, owner, normalized.lockTtlMs);
+        if (integerResponse(response, "EXTEND response") !== 1) {
+          throw new Error(`lost FerricStore lock ${JSON.stringify(key)} while mutating data`);
+        }
+        lastExtended.set(key, performance.now());
+      } catch (error) {
+        throw loseOwnership(new Error(
+          `could not validate FerricStore lock ${JSON.stringify(key)} before mutating data`,
+          { cause: error }
+        ));
+      }
+    }
+    assertOwned();
+  };
+  const lease = {
+    signal: ownershipAbort.signal,
+    assertOwned,
+    publish: async (...args) => {
+      await renewOwned();
+      const response = await additiveCommand(client, args);
+      assertOwned();
+      return response;
+    },
+    compareAndSet: async (key, expected, value) => {
+      await renewOwned();
+      const committed = await compareAndSetAtomicValue(client, key, expected, value);
+      if (committed) conditionalCommitCompleted = true;
+      else assertOwned();
+      return committed;
+    }
+  };
   try {
     for (const key of orderedKeys) {
       while (!await tryAcquireLock(client, key, owner, normalized.lockTtlMs)) {
         if (performance.now() >= deadline) {
           throw new Error(`timed out acquiring FerricStore lock ${JSON.stringify(key)}`);
         }
+        await extendAcquiredLocks(client, acquired, owner, normalized.lockTtlMs);
         await delay(normalized.lockRetryMs);
       }
       acquired.push(key);
     }
+    await extendAcquiredLocks(client, acquired, owner, normalized.lockTtlMs);
+    for (const key of acquired) lastExtended.set(key, performance.now());
     const heartbeat = renewLocks(
       client,
       acquired,
       owner,
       normalized.lockTtlMs,
+      lastExtended,
       heartbeatAbort.signal,
       (error) => {
-        heartbeatError ??= error;
+        loseOwnership(error);
       }
     );
     try {
-      result = await operation();
+      result = await operation(lease);
       operationCompleted = true;
     } catch (error) {
       primaryError = error;
@@ -163,11 +245,32 @@ async function withMutationLocks(client, keys, operation, options = {}) {
     }
   }
   if (primaryError != null) throw errorObject(primaryError);
-  if (heartbeatError != null) throw errorObject(heartbeatError);
-  if (releaseError != null) throw errorObject(releaseError);
+  if (heartbeatError != null && !conditionalCommitCompleted) throw errorObject(heartbeatError);
+  if (releaseError != null && !(heartbeatError != null && conditionalCommitCompleted)) {
+    throw errorObject(releaseError);
+  }
   if (!operationCompleted) throw new Error("FerricStore mutation did not complete");
   return result;
 }
+async function additiveCommand(client, args) {
+  const rawName = args[0];
+  const name = typeof rawName === "string" ? rawName.toUpperCase() : Buffer.isBuffer(rawName) || rawName instanceof Uint8Array ? Buffer.from(rawName).toString("utf8").toUpperCase() : "";
+  if (name !== "SADD" && name !== "ZADD") {
+    throw new TypeError("FerricStore mutation leases only publish add-only SADD or ZADD indexes");
+  }
+  if (name === "ZADD" && (args.length < 4 || args.length % 2 !== 0 || args.slice(2).some((value, index) => index % 2 === 0 && Number(value) !== 0))) {
+    throw new TypeError("FerricStore mutation leases only publish zero-score ZADD indexes");
+  }
+  return await client.command(...args);
+}
+async function extendAcquiredLocks(client, keys, owner, ttlMs) {
+  for (const key of keys) {
+    const response = await client.command("EXTEND", key, owner, ttlMs);
+    if (integerResponse(response, "EXTEND response") !== 1) {
+      throw new Error(`lost FerricStore lock ${JSON.stringify(key)} before mutating data`);
+    }
+  }
+}
 async function tryAcquireLock(client, key, owner, ttlMs) {
   try {
     const response = await client.command("LOCK", key, owner, ttlMs);
@@ -177,10 +280,9 @@ async function tryAcquireLock(client, key, owner, ttlMs) {
     throw error;
   }
 }
-async function renewLocks(client, keys, owner, ttlMs, signal, onError) {
-  const intervalMs = Math.max(Math.floor(ttlMs / 3), 10);
-  const retryMs = Math.min(Math.max(Math.floor(intervalMs / 10), 10), 1e3);
-  const lastExtended = new Map(keys.map((key) => [key, performance.now()]));
+async function renewLocks(client, keys, owner, ttlMs, lastExtended, signal, onError) {
+  const intervalMs = Math.max(Math.floor(ttlMs / 3), 1);
+  const retryMs = Math.min(Math.max(Math.floor(intervalMs / 10), 1), 1e3);
   let waitMs = intervalMs;
   while (!signal.aborted) {
     try {
@@ -218,7 +320,7 @@ function errorObject(value) {
 // src/agent-persistence/snapshot.ts
 import { createHash } from "crypto";
 function encodeSnapshot(value) {
-  return Buffer.from(JSON.stringify(snapshot(value, /* @__PURE__ */ new WeakSet())), "utf8");
+  return encodeSnapshotWith(value, defaultKeyComparator);
 }
 function decodeSnapshot(value, name) {
   const bytes = typeof value === "string" ? Buffer.from(value, "utf8") : Buffer.from(asBytes(value, name));
@@ -233,13 +335,22 @@ function decodeSnapshot(value, name) {
 function snapshotDigest(value) {
   return createHash("sha256").update(encodeSnapshot(value)).digest("hex");
 }
+function legacySnapshotDigest(value, locale) {
+  return createHash("sha256").update(encodeSnapshotWith(value, (left, right) => left.localeCompare(right, locale))).digest("hex");
+}
 function cloneSnapshot(value) {
   return decodeSnapshot(encodeSnapshot(value), "snapshot");
 }
 function snapshotsEqual(left, right) {
   return encodeSnapshot(left).equals(encodeSnapshot(right));
 }
-function snapshot(value, ancestors) {
+function encodeSnapshotWith(value, compareKeys) {
+  return Buffer.from(JSON.stringify(snapshot(value, /* @__PURE__ */ new WeakSet(), compareKeys)), "utf8");
+}
+function defaultKeyComparator(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+function snapshot(value, ancestors, compareKeys) {
   if (value === null) return ["null"];
   if (value === void 0) return ["undefined"];
   if (typeof value === "string") return ["string", value];
@@ -273,7 +384,7 @@ function snapshot(value, ancestors) {
         if (descriptor == null || !descriptor.enumerable || !("value" in descriptor)) {
           throw new TypeError("session history contains an unsupported array item");
         }
-        items.push(snapshot(descriptor.value, ancestors));
+        items.push(snapshot(descriptor.value, ancestors, compareKeys));
       }
       return ["array", items];
     }
@@ -286,12 +397,12 @@ function snapshot(value, ancestors) {
       throw new TypeError("session history contains a symbol property");
     }
     const entries = [];
-    for (const key of keys.sort((left, right) => left.localeCompare(right))) {
+    for (const key of keys.sort(compareKeys)) {
       const descriptor = Object.getOwnPropertyDescriptor(value, key);
       if (descriptor == null || !descriptor.enumerable || !("value" in descriptor)) {
         throw new TypeError("session history contains an unsupported property");
       }
-      entries.push([key, snapshot(descriptor.value, ancestors)]);
+      entries.push([key, snapshot(descriptor.value, ancestors, compareKeys)]);
     }
     return ["object", entries];
   } finally {
@@ -362,13 +473,16 @@ function isArrayIndex(key, length) {
 // src/openai-agents.ts
 var SESSION_FORMAT_VERSION = 1;
 var SESSION_STATE_FIELD = "state";
+var RECEIPT_DIGEST_VERSION = "v2:";
 var FerricStoreSession = class {
   client;
   sessionId;
   keyPrefix;
   initialItems;
   lockOptions;
+  legacyReceiptLocales;
   sessionKey;
+  stateKey;
   lockKey;
   constructor(client, options = {}) {
     this.client = client;
@@ -383,8 +497,17 @@ var FerricStoreSession = class {
       lockTtlMs: options.lockTtlMs,
       lockWaitMs: options.lockWaitMs
     };
+    if (options.legacyReceiptLocales != null && !Array.isArray(options.legacyReceiptLocales)) {
+      throw new TypeError("legacyReceiptLocales must be an array");
+    }
+    try {
+      this.legacyReceiptLocales = Intl.getCanonicalLocales(options.legacyReceiptLocales ?? []);
+    } catch (error) {
+      throw new TypeError("legacyReceiptLocales contains an invalid locale", { cause: error });
+    }
     const digest = createHash2("sha256").update(this.sessionId, "utf8").digest("hex");
     this.sessionKey = `${this.keyPrefix}:{oais:${digest}}:session`;
+    this.stateKey = `${this.sessionKey}:atomic-state`;
     this.lockKey = `${this.keyPrefix}:{oais:${digest}}:mutation-lock`;
   }
   async getSessionId() {
@@ -455,15 +578,21 @@ var FerricStoreSession = class {
   }
   async applyHistoryTransaction(args) {
     const { operationId, transaction } = snapshotTransactionArgs(args);
-    const digest = snapshotDigest(transaction);
+    const digest = `${RECEIPT_DIGEST_VERSION}${snapshotDigest(transaction)}`;
+    const legacyDigests = /* @__PURE__ */ new Set([
+      snapshotDigest(transaction),
+      legacySnapshotDigest(transaction),
+      ...this.legacyReceiptLocales.map((locale) => legacySnapshotDigest(transaction, locale))
+    ]);
     await this.mutate(async (state) => {
       const existing = Object.getOwnPropertyDescriptor(state.operations, operationId)?.value;
       if (existing != null) {
         if (typeof existing !== "string") throw new Error("corrupt session history operation receipt");
-        if (existing !== digest) {
+        if (existing === digest) return state;
+        if (!legacyDigests.has(existing)) {
           throw new Error("session history operation was already applied with a different transaction");
         }
-        return state;
+        return { ...state, operations: { ...state.operations, [operationId]: digest } };
       }
       let items;
       if (transaction.type === "append_items") {
@@ -484,20 +613,28 @@ var FerricStoreSession = class {
     });
   }
   async mutate(operation) {
-    await withMutationLocks(this.client, [this.lockKey], async () => {
-      const current = await this.readState();
-      const next = await operation(current);
-      await this.client.command("HSET", this.sessionKey, SESSION_STATE_FIELD, encodeSnapshot(next));
+    await withMutationLocks(this.client, [this.lockKey], async (lease) => {
+      for (let attempt = 0; attempt < 8; attempt += 1) {
+        lease.assertOwned();
+        const snapshot2 = await this.readMutationState();
+        const next = await operation(snapshot2.state);
+        if (await lease.compareAndSet(this.stateKey, snapshot2.expected, encodeSnapshot(next))) return;
+      }
+      throw new Error("concurrent FerricStore OpenAI Agents session mutation did not converge");
     }, this.lockOptions);
   }
   async readState() {
-    const value = await this.client.command("HGET", this.sessionKey, SESSION_STATE_FIELD);
-    if (value == null) return this.emptyState();
+    return (await this.readMutationState()).state;
+  }
+  async readMutationState() {
+    const expected = await readAtomicValue(this.client, this.stateKey, "OpenAI Agents atomic session state");
+    const value = expected ?? await this.client.command("HGET", this.sessionKey, SESSION_STATE_FIELD);
+    if (value == null) return { expected, state: this.emptyState() };
     const state = decodeSnapshot(value, "OpenAI Agents session state");
     if (state == null || typeof state !== "object" || state.formatVersion !== SESSION_FORMAT_VERSION || state.sessionId !== this.sessionId || !Array.isArray(state.items) || state.operations == null || typeof state.operations !== "object" || Array.isArray(state.operations) || Object.values(state.operations).some((digest) => typeof digest !== "string")) {
       throw new Error("unsupported or corrupt FerricStore OpenAI Agents session state");
     }
-    return state;
+    return { expected, state };
   }
   emptyState() {
     return {