@ferricstore/ferricstore 0.12.0 → 0.12.2

package/dist/langgraph.cjs

@@ -139,14 +139,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 = (0, import_node_crypto.randomUUID)();
   const acquired = [];
   const deadline = performance.now() + normalized.lockWaitMs;
@@ -155,29 +185,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 (0, import_promises.setTimeout)(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;
@@ -198,11 +280,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);
@@ -212,10 +315,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 {
@@ -252,6 +354,8 @@ function errorObject(value) {
 
 // src/langgraph/checkpoint.ts
 var FORMAT_VERSION = 1;
+var LEGACY_EPOCH_PREFIX = "legacy:";
+var CURRENT_EPOCH_PREFIX = "v2:";
 var CHECKPOINT_FIELD_PREFIX = "checkpoint:";
 var WRITE_FIELD_PREFIX = "write:";
 var WRITES_INDEX = {
@@ -279,22 +383,18 @@ var FerricStoreSaver = class extends import_langgraph.BaseCheckpointSaver {
   async getTuple(config) {
     const { checkpointNs, threadId } = identity(config);
     const key = this.threadKey(threadId, checkpointNs);
+    const epoch = await this.readThreadEpoch(threadId);
     let id = checkpointId(config);
     let record;
     if (id != null) {
-      record = await this.readRecord(key, id);
+      record = await this.readRecordAtEpoch(key, id, epoch);
     } else {
-      let offset = 0;
-      while (true) {
-        const values = arrayResponse(
-          await this.client.command("ZREVRANGE", this.checkpointIndexKey(key), offset, offset),
-          "ZREVRANGE checkpoint response"
-        );
-        if (values.length === 0) return void 0;
-        id = textResponse(values[0], "checkpoint ID");
-        record = await this.readRecord(key, id);
-        if (record != null) break;
-        offset += 1;
+      for (const candidate of await this.checkpointIdsAtEpoch(key, epoch)) {
+        record = await this.readRecordAtEpoch(key, candidate, epoch);
+        if (record != null) {
+          id = candidate;
+          break;
+        }
       }
     }
     if (id == null || record == null) return void 0;
@@ -314,14 +414,15 @@ var FerricStoreSaver = class extends import_langgraph.BaseCheckpointSaver {
     const checkpointNs = namespaceSpecified ? requiredText(configurable?.checkpoint_ns, "checkpoint_ns", true) : void 0;
     const matches = [];
     if (threadId == null) {
-      await this.collectGlobal(matches, beforeId, expectedId, options.filter, limit);
+      await this.collectGlobal(matches, beforeId, expectedId, checkpointNs, options.filter, limit);
     } else {
       const keys = checkpointNs == null ? await this.threadKeys(threadId) : [this.threadKey(threadId, checkpointNs)];
       for (const key of keys) {
-        const ids = expectedId == null ? await this.checkpointIds(key) : [expectedId];
+        const epoch = await this.readThreadEpoch(threadId);
+        const ids = expectedId == null ? await this.checkpointIdsAtEpoch(key, epoch) : [expectedId];
         for (const id of ids) {
           if (beforeId != null && id >= beforeId) continue;
-          const record = await this.readRecord(key, id);
+          const record = await this.readRecordAtEpoch(key, id, epoch);
           if (record == null || !metadataMatches(record.metadata, options.filter)) continue;
           matches.push({ key, record });
         }
@@ -348,13 +449,24 @@ var FerricStoreSaver = class extends import_langgraph.BaseCheckpointSaver {
       threadId
     };
     const key = this.threadKey(threadId, checkpointNs);
-    await withMutationLocks(this.client, [this.threadLockKey(threadId)], async () => {
-      const locator = checkpointLocator(checkpoint.id, key);
-      await this.client.command("SADD", this.threadCatalogKey(threadId), key);
-      await this.client.command("ZADD", this.threadLocatorCatalogKey(threadId), 0, locator);
-      await this.client.command("ZADD", this.catalogKey(), 0, locator);
-      await this.client.command("ZADD", this.checkpointIndexKey(key), 0, checkpoint.id);
-      await this.client.command("HSET", key, checkpointField(checkpoint.id), await this.serialize(record));
+    await withMutationLocks(this.client, [this.threadLockKey(threadId)], async (lease) => {
+      const epoch = await this.ensureThreadEpoch(threadId, lease);
+      const locator = checkpointLocator(checkpoint.id, key, threadId);
+      await lease.publish("SADD", this.threadCatalogKey(threadId), key);
+      await lease.publish("ZADD", this.threadLocatorCatalogKey(threadId), 0, locator);
+      await lease.publish("ZADD", this.catalogKey(), 0, locator);
+      await lease.publish("ZADD", this.checkpointIndexKey(key), 0, checkpoint.id);
+      await lease.publish("ZADD", this.atomicCheckpointIndexKey(key, requireEpoch(epoch)), 0, checkpoint.id);
+      const dataKey = this.checkpointRecordKey(key, requireEpoch(epoch), checkpoint.id);
+      const value = await this.serialize(record);
+      for (let attempt = 0; attempt < 8; attempt += 1) {
+        const expected = await readAtomicValue(this.client, dataKey, "LangGraph atomic checkpoint record");
+        if (await lease.compareAndSet(dataKey, expected, value)) {
+          await this.assertCurrentEpoch(threadId, epoch);
+          return;
+        }
+      }
+      throw new Error("concurrent FerricStore LangGraph checkpoint mutation did not converge");
     }, this.lockOptions);
     return checkpointConfig(threadId, checkpointNs, checkpoint.id);
   }
@@ -376,35 +488,39 @@ var FerricStoreSaver = class extends import_langgraph.BaseCheckpointSaver {
       return { index, value: await this.serialize(record) };
     }));
     const key = this.threadKey(threadId, checkpointNs);
-    await withMutationLocks(this.client, [this.threadLockKey(threadId)], async () => {
-      await this.client.command("SADD", this.threadCatalogKey(threadId), key);
+    await withMutationLocks(this.client, [this.threadLockKey(threadId)], async (lease) => {
+      const epoch = await this.ensureThreadEpoch(threadId, lease);
+      const epochValue = requireEpoch(epoch);
+      await lease.publish("SADD", this.threadCatalogKey(threadId), key);
       for (const snapshot of snapshots) {
-        await this.client.command(
-          snapshot.index < 0 ? "HSET" : "HSETNX",
-          key,
-          writeField(id, taskId, snapshot.index),
-          snapshot.value
-        );
+        const dataKey = this.pendingWriteKey(key, epochValue, id, taskId, snapshot.index);
+        const indexKey = this.atomicPendingWriteIndexKey(key, epochValue, id);
+        await lease.publish("ZADD", indexKey, 0, dataKey);
+        for (let attempt = 0; attempt < 8; attempt += 1) {
+          const expected = await readAtomicValue(this.client, dataKey, "LangGraph atomic pending write");
+          if (snapshot.index >= 0 && expected != null) break;
+          if (snapshot.index >= 0 && epoch.legacyFallback) {
+            const legacy = await this.client.command("HGET", key, writeField(id, taskId, snapshot.index));
+            if (legacy != null) break;
+          }
+          if (await lease.compareAndSet(dataKey, expected, snapshot.value)) break;
+          if (attempt === 7) {
+            throw new Error("concurrent FerricStore LangGraph pending-write mutation did not converge");
+          }
+        }
       }
+      await this.assertCurrentEpoch(threadId, epoch);
     }, this.lockOptions);
   }
   async deleteThread(threadId) {
     const normalized = requiredText(threadId, "threadId");
-    await withMutationLocks(this.client, [this.threadLockKey(normalized)], async () => {
-      for (const key of await this.threadKeys(normalized)) {
-        await this.client.command("DEL", key, this.checkpointIndexKey(key));
-      }
-      const locatorKey = this.threadLocatorCatalogKey(normalized);
-      while (true) {
-        const locators = arrayResponse(
-          await this.client.command("ZRANGE", locatorKey, 0, this.scanCount - 1),
-          "thread checkpoint locator response"
-        );
-        if (locators.length === 0) break;
-        await this.client.command("ZREM", this.catalogKey(), ...asArguments(locators));
-        await this.client.command("ZREM", locatorKey, ...asArguments(locators));
+    await withMutationLocks(this.client, [this.threadLockKey(normalized)], async (lease) => {
+      for (let attempt = 0; attempt < 8; attempt += 1) {
+        const epoch = await this.ensureThreadEpoch(normalized, lease);
+        const next = Buffer.from(`${CURRENT_EPOCH_PREFIX}${(0, import_node_crypto2.randomUUID)()}`, "utf8");
+        if (await lease.compareAndSet(this.threadEpochKey(normalized), epoch.raw, next)) return;
       }
-      await this.client.command("DEL", this.threadCatalogKey(normalized), locatorKey);
+      throw new Error("concurrent FerricStore LangGraph thread deletion did not converge");
     }, this.lockOptions);
   }
   catalogKey() {
@@ -426,6 +542,47 @@ var FerricStoreSaver = class extends import_langgraph.BaseCheckpointSaver {
   checkpointIndexKey(threadKey) {
     return `${threadKey}:checkpoint-index`;
   }
+  threadEpochKey(threadId) {
+    return `${this.threadCatalogKey(threadId)}:atomic-epoch`;
+  }
+  atomicCheckpointIndexKey(threadKey, epoch) {
+    return `${threadKey}:atomic:${sha256(epoch)}:checkpoint-index`;
+  }
+  atomicPendingWriteIndexKey(threadKey, epoch, checkpointId2) {
+    return `${threadKey}:atomic:${sha256(epoch)}:writes:${encodeComponent(checkpointId2)}`;
+  }
+  checkpointRecordKey(threadKey, epoch, checkpointId2) {
+    return `${threadKey}:atomic:${sha256(epoch)}:checkpoint:${encodeComponent(checkpointId2)}`;
+  }
+  pendingWriteKey(threadKey, epoch, checkpointId2, taskId, index) {
+    return `${threadKey}:atomic:${sha256(epoch)}:write:${encodeComponent(checkpointId2)}:${encodeComponent(taskId)}:${index}`;
+  }
+  async readThreadEpoch(threadId) {
+    const raw = await readAtomicValue(this.client, this.threadEpochKey(threadId), "LangGraph thread epoch");
+    if (raw == null) return { legacyFallback: true, raw, value: void 0 };
+    const value = raw.toString("utf8");
+    if (!value.startsWith(LEGACY_EPOCH_PREFIX) && !value.startsWith(CURRENT_EPOCH_PREFIX)) {
+      throw new Error("unsupported or corrupt FerricStore LangGraph thread epoch");
+    }
+    return { legacyFallback: value.startsWith(LEGACY_EPOCH_PREFIX), raw, value };
+  }
+  async ensureThreadEpoch(threadId, lease) {
+    for (let attempt = 0; attempt < 8; attempt += 1) {
+      const epoch = await this.readThreadEpoch(threadId);
+      if (epoch.value != null) return epoch;
+      const raw = Buffer.from(`${LEGACY_EPOCH_PREFIX}${(0, import_node_crypto2.randomUUID)()}`, "utf8");
+      if (await lease.compareAndSet(this.threadEpochKey(threadId), void 0, raw)) {
+        return { legacyFallback: true, raw, value: raw.toString("utf8") };
+      }
+    }
+    throw new Error("concurrent FerricStore LangGraph epoch initialization did not converge");
+  }
+  async assertCurrentEpoch(threadId, expected) {
+    const current = await this.readThreadEpoch(threadId);
+    if (expected.raw == null || current.raw?.equals(expected.raw) !== true) {
+      throw new Error("FerricStore LangGraph thread epoch changed while committing data");
+    }
+  }
   async serialize(value) {
     const [type, data] = await this.serde.dumpsTyped(value);
     const typeBytes = Buffer.from(type, "utf8");
@@ -445,8 +602,16 @@ var FerricStoreSaver = class extends import_langgraph.BaseCheckpointSaver {
     const type = bytes.subarray(2, typeLength + 2).toString("utf8");
     return await this.serde.loadsTyped(type, bytes.subarray(typeLength + 2));
   }
-  async readRecord(key, id) {
-    const value = await this.client.command("HGET", key, checkpointField(id));
+  async readRecordAtEpoch(key, id, epoch) {
+    let value;
+    if (epoch.value != null) {
+      value = await this.client.command("GET", this.checkpointRecordKey(key, epoch.value, id));
+      if (value == null && epoch.legacyFallback) {
+        value = await this.client.command("HGET", key, checkpointField(id));
+      }
+    } else {
+      value = await this.client.command("HGET", key, checkpointField(id));
+    }
     if (value == null) return void 0;
     const record = await this.deserialize(value, "LangGraph checkpoint record");
     if (record.formatVersion !== FORMAT_VERSION || record.checkpointId !== id) {
@@ -454,23 +619,45 @@ var FerricStoreSaver = class extends import_langgraph.BaseCheckpointSaver {
     }
     return record;
   }
-  async pendingWrites(key, id) {
-    const fields = await this.scanHash(key, `${WRITE_FIELD_PREFIX}${encodeComponent(id)}:*`);
-    const records = await Promise.all(fields.map(async ([, value]) => await this.deserialize(value, "LangGraph pending write")));
-    for (const record of records) {
+  async pendingWritesAtEpoch(key, id, epoch) {
+    const records = /* @__PURE__ */ new Map();
+    if (epoch.value != null) {
+      const keys = arrayResponse(
+        await this.client.command("ZRANGE", this.atomicPendingWriteIndexKey(key, epoch.value, id), 0, -1),
+        "LangGraph atomic pending-write index response"
+      );
+      for (const rawKey of keys) {
+        const dataKey = textResponse(rawKey, "LangGraph pending-write key");
+        const value = await this.client.command("GET", dataKey);
+        if (value == null) continue;
+        const record = await this.deserialize(value, "LangGraph pending write");
+        records.set(pendingWriteIdentity(record), record);
+      }
+    }
+    if (epoch.legacyFallback) {
+      const fields = await this.scanHash(key, `${WRITE_FIELD_PREFIX}${encodeComponent(id)}:*`);
+      for (const [, value] of fields) {
+        const record = await this.deserialize(value, "LangGraph pending write");
+        const identity2 = pendingWriteIdentity(record);
+        if (!records.has(identity2)) records.set(identity2, record);
+      }
+    }
+    const ordered = [...records.values()];
+    for (const record of ordered) {
       if (record.formatVersion !== FORMAT_VERSION) {
         throw new Error("unsupported FerricStore LangGraph pending-write format");
       }
     }
-    records.sort((left, right) => left.taskId.localeCompare(right.taskId) || left.index - right.index);
-    return records.map((record) => [record.taskId, record.channel, record.value]);
+    ordered.sort((left, right) => left.taskId.localeCompare(right.taskId) || left.index - right.index);
+    return ordered.map((record) => [record.taskId, record.channel, record.value]);
   }
   async tupleFromRecord(key, record) {
+    const epoch = await this.readThreadEpoch(record.threadId);
     return {
       checkpoint: record.checkpoint,
       config: checkpointConfig(record.threadId, record.checkpointNs, record.checkpointId),
       metadata: record.metadata,
-      pendingWrites: await this.pendingWrites(key, record.checkpointId),
+      pendingWrites: await this.pendingWritesAtEpoch(key, record.checkpointId, epoch),
       ...record.parentCheckpointId == null ? {} : { parentConfig: checkpointConfig(record.threadId, record.checkpointNs, record.parentCheckpointId) }
     };
   }
@@ -502,15 +689,27 @@ var FerricStoreSaver = class extends import_langgraph.BaseCheckpointSaver {
     );
     return values.map((value) => textResponse(value, "thread checkpoint key")).sort();
   }
-  async checkpointIds(key) {
-    const values = arrayResponse(
-      await this.client.command("ZREVRANGE", this.checkpointIndexKey(key), 0, -1),
-      "checkpoint index response"
-    );
-    return values.map((value) => textResponse(value, "checkpoint ID"));
+  async checkpointIdsAtEpoch(key, epoch) {
+    const ids = /* @__PURE__ */ new Set();
+    if (epoch.value != null) {
+      const values = arrayResponse(
+        await this.client.command("ZREVRANGE", this.atomicCheckpointIndexKey(key, epoch.value), 0, -1),
+        "atomic checkpoint index response"
+      );
+      for (const value of values) ids.add(textResponse(value, "checkpoint ID"));
+    }
+    if (epoch.legacyFallback) {
+      const values = arrayResponse(
+        await this.client.command("ZREVRANGE", this.checkpointIndexKey(key), 0, -1),
+        "checkpoint index response"
+      );
+      for (const value of values) ids.add(textResponse(value, "checkpoint ID"));
+    }
+    return [...ids].sort((left, right) => right.localeCompare(left));
   }
-  async collectGlobal(result, beforeId, expectedId, filter, limit) {
+  async collectGlobal(result, beforeId, expectedId, checkpointNs, filter, limit) {
     let offset = 0;
+    const seen = /* @__PURE__ */ new Set();
     while (limit == null || result.length < limit) {
       const values = arrayResponse(
         await this.client.command("ZREVRANGE", this.catalogKey(), offset, offset + this.scanCount - 1),
@@ -518,11 +717,24 @@ var FerricStoreSaver = class extends import_langgraph.BaseCheckpointSaver {
       );
       if (values.length === 0) break;
       for (const value of values) {
-        const { checkpointId: id, threadKey: key } = decodeCheckpointLocator(value);
+        const locator = decodeCheckpointLocator(value);
+        const { checkpointId: id, threadKey: key } = locator;
         if (expectedId != null && id !== expectedId) continue;
         if (beforeId != null && id >= beforeId) continue;
-        const record = await this.readRecord(key, id);
-        if (record == null || !metadataMatches(record.metadata, filter)) continue;
+        let record;
+        if (locator.threadId != null) {
+          record = await this.readRecordAtEpoch(key, id, await this.readThreadEpoch(locator.threadId));
+        } else {
+          const legacy = await this.client.command("HGET", key, checkpointField(id));
+          if (legacy != null) {
+            const candidate = await this.deserialize(legacy, "LangGraph checkpoint record");
+            record = await this.readRecordAtEpoch(key, id, await this.readThreadEpoch(candidate.threadId));
+          }
+        }
+        if (record == null || checkpointNs != null && record.checkpointNs !== checkpointNs || !metadataMatches(record.metadata, filter)) continue;
+        const identity2 = lengthPrefixed([record.threadId, record.checkpointNs, record.checkpointId]).toString("base64url");
+        if (seen.has(identity2)) continue;
+        seen.add(identity2);
         result.push({ key, record });
         if (limit != null && result.length >= limit) break;
       }
@@ -571,8 +783,18 @@ function writeField(id, taskId, index) {
 function encodeComponent(value) {
   return Buffer.from(value, "utf8").toString("base64url");
 }
-function checkpointLocator(id, threadKey) {
-  return Buffer.concat([orderedText(id), Buffer.from(threadKey, "utf8")]);
+function checkpointLocator(id, threadKey, threadId) {
+  if (threadId == null) return Buffer.concat([orderedText(id), Buffer.from(threadKey, "utf8")]);
+  const threadIdBytes = Buffer.from(threadId, "utf8");
+  const length = Buffer.allocUnsafe(4);
+  length.writeUInt32BE(threadIdBytes.length);
+  return Buffer.concat([
+    orderedText(id),
+    Buffer.from([0, 1]),
+    length,
+    threadIdBytes,
+    Buffer.from(threadKey, "utf8")
+  ]);
 }
 function decodeCheckpointLocator(value) {
   if (!(typeof value === "string" || Buffer.isBuffer(value) || value instanceof Uint8Array)) {
@@ -580,9 +802,21 @@ function decodeCheckpointLocator(value) {
   }
   const bytes = typeof value === "string" ? Buffer.from(value, "utf8") : Buffer.from(value);
   const decoded = decodeOrderedText(bytes, 0);
-  const threadKey = bytes.subarray(decoded.offset).toString("utf8");
+  let offset = decoded.offset;
+  let threadId;
+  if (bytes[offset] === 0 && bytes[offset + 1] === 1) {
+    offset += 2;
+    if (bytes.length < offset + 4) throw new Error("truncated FerricStore checkpoint locator");
+    const length = bytes.readUInt32BE(offset);
+    offset += 4;
+    if (bytes.length < offset + length) throw new Error("truncated FerricStore checkpoint locator thread ID");
+    threadId = bytes.subarray(offset, offset + length).toString("utf8");
+    offset += length;
+    if (threadId.length === 0) throw new Error("FerricStore checkpoint locator has an empty thread ID");
+  }
+  const threadKey = bytes.subarray(offset).toString("utf8");
   if (threadKey.length === 0) throw new Error("FerricStore checkpoint locator has an empty thread key");
-  return { checkpointId: decoded.value, threadKey };
+  return { checkpointId: decoded.value, ...threadId == null ? {} : { threadId }, threadKey };
 }
 function orderedText(value) {
   const output = [];
@@ -625,12 +859,12 @@ function lengthPrefixed(values) {
   }
   return Buffer.concat(parts);
 }
-function asArguments(values) {
-  return values.map((value) => {
-    if (typeof value === "string" || typeof value === "number" || Buffer.isBuffer(value)) return value;
-    if (value instanceof Uint8Array) return Buffer.from(value);
-    throw new TypeError("FerricStore returned an invalid command argument");
-  });
+function requireEpoch(epoch) {
+  if (epoch.value == null) throw new Error("FerricStore LangGraph thread epoch is not initialized");
+  return epoch.value;
+}
+function pendingWriteIdentity(record) {
+  return lengthPrefixed([record.taskId, String(record.index)]).toString("base64url");
 }
 
 // src/langgraph/store.ts
@@ -638,6 +872,7 @@ var import_node_crypto3 = require("crypto");
 var import_langgraph2 = require("@langchain/langgraph");
 var FORMAT_VERSION2 = 1;
 var ITEM_FIELD_PREFIX = "item:";
+var DELETED_ITEM = Buffer.from("ferricstore:langgraph:item:deleted:v2", "utf8");
 var FerricStoreStore = class extends import_langgraph2.BaseStore {
   client;
   keyPrefix;
@@ -660,7 +895,7 @@ var FerricStoreStore = class extends import_langgraph2.BaseStore {
       validatePut(operation);
       return this.itemLockKey(operation.namespace, operation.key);
     });
-    return await withMutationLocks(this.client, lockKeys, async () => {
+    return await withMutationLocks(this.client, lockKeys, async (lease) => {
       const results = [];
       const puts = /* @__PURE__ */ new Map();
       for (const operation of operations) {
@@ -677,7 +912,7 @@ var FerricStoreStore = class extends import_langgraph2.BaseStore {
           throw new TypeError("unsupported LangGraph store operation");
         }
       }
-      for (const operation of puts.values()) await this.putOperation(operation);
+      for (const operation of puts.values()) await this.putOperation(operation, lease);
       return results;
     }, this.lockOptions);
   }
@@ -688,47 +923,45 @@ var FerricStoreStore = class extends import_langgraph2.BaseStore {
     return `${this.keyPrefix}:{lgs:${sha2562(namespaceIdentity(namespace))}}:namespace`;
   }
   itemLockKey(namespace, key) {
-    const keyBytes = Buffer.from(key, "utf8");
-    return `${this.keyPrefix}:{lgsi:${sha2562(Buffer.concat([
-      namespaceIdentity(namespace),
-      uint64(keyBytes.length),
-      keyBytes
-    ]))}}:mutation-lock`;
+    return `${this.keyPrefix}:{lgsi:${itemIdentityDigest(namespace, key)}}:mutation-lock`;
+  }
+  itemDataKey(namespace, key) {
+    return `${this.keyPrefix}:{lgsi:${itemIdentityDigest(namespace, key)}}:atomic-item`;
   }
   async getOperation(operation) {
     validateNamespace(operation.namespace);
     if (typeof operation.key !== "string") throw new TypeError("store key must be text");
-    const value = await this.client.command(
-      "HGET",
-      this.namespaceKey(operation.namespace),
-      itemField(operation.key)
-    );
-    return value == null ? null : decodeItem(value);
+    const snapshot = await this.readItemSnapshot(operation.namespace, operation.key);
+    return snapshot.record == null ? null : itemFromRecord(snapshot.record);
   }
-  async putOperation(operation) {
+  async putOperation(operation, lease) {
     validatePut(operation);
-    const namespaceKey = this.namespaceKey(operation.namespace);
-    const field = itemField(operation.key);
+    const dataKey = this.itemDataKey(operation.namespace, operation.key);
     const locator = catalogMember(operation.namespace, operation.key);
     if (operation.value == null) {
-      await this.client.command("HDEL", namespaceKey, field);
-      await this.client.command("ZREM", this.catalogKey(), locator);
-      return;
+      for (let attempt = 0; attempt < 8; attempt += 1) {
+        const snapshot = await this.readItemSnapshot(operation.namespace, operation.key);
+        if (snapshot.expected?.equals(DELETED_ITEM) === true) return;
+        if (await lease.compareAndSet(dataKey, snapshot.expected, DELETED_ITEM)) return;
+      }
+      throw new Error("concurrent FerricStore LangGraph store deletion did not converge");
     }
     const storedValue = snapshotJsonValue(operation.value);
-    const existing = await this.client.command("HGET", namespaceKey, field);
-    const now = (/* @__PURE__ */ new Date()).toISOString();
-    const createdAt = existing == null ? now : decodeItemRecord(existing).createdAt;
-    const record = {
-      createdAt,
-      formatVersion: FORMAT_VERSION2,
-      key: operation.key,
-      namespace: [...operation.namespace],
-      updatedAt: now,
-      value: storedValue
-    };
-    await this.client.command("ZADD", this.catalogKey(), 0, locator);
-    await this.client.command("HSET", namespaceKey, field, encodeItem(record));
+    await lease.publish("ZADD", this.catalogKey(), 0, locator);
+    for (let attempt = 0; attempt < 8; attempt += 1) {
+      const snapshot = await this.readItemSnapshot(operation.namespace, operation.key);
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const record = {
+        createdAt: snapshot.record?.createdAt ?? now,
+        formatVersion: FORMAT_VERSION2,
+        key: operation.key,
+        namespace: [...operation.namespace],
+        updatedAt: now,
+        value: storedValue
+      };
+      if (await lease.compareAndSet(dataKey, snapshot.expected, encodeItem(record))) return;
+    }
+    throw new Error("concurrent FerricStore LangGraph store mutation did not converge");
   }
   async searchOperation(operation) {
     validateNamespacePrefix(operation.namespacePrefix);
@@ -766,8 +999,23 @@ var FerricStoreStore = class extends import_langgraph2.BaseStore {
     return [...namespaces.values()].sort(compareNamespaces).slice(offset, offset + limit);
   }
   async readCatalogItem(namespace, key) {
-    const value = await this.client.command("HGET", this.namespaceKey(namespace), itemField(key));
-    return value == null ? null : decodeItem(value);
+    const snapshot = await this.readItemSnapshot(namespace, key);
+    return snapshot.record == null ? null : itemFromRecord(snapshot.record);
+  }
+  async readItemSnapshot(namespace, key) {
+    const expected = await readAtomicValue(
+      this.client,
+      this.itemDataKey(namespace, key),
+      "LangGraph atomic store item"
+    );
+    if (expected != null) {
+      return {
+        expected,
+        record: expected.equals(DELETED_ITEM) ? null : decodeItemRecord(expected)
+      };
+    }
+    const legacy = await this.client.command("HGET", this.namespaceKey(namespace), itemField(key));
+    return { expected, record: legacy == null ? null : decodeItemRecord(legacy) };
   }
   async *catalogLocators() {
     let offset = 0;
@@ -867,8 +1115,7 @@ function snapshotJsonValue(value) {
 function encodeItem(record) {
   return Buffer.from(JSON.stringify(record), "utf8");
 }
-function decodeItem(value) {
-  const record = decodeItemRecord(value);
+function itemFromRecord(record) {
   return {
     createdAt: new Date(record.createdAt),
     key: record.key,
@@ -877,6 +1124,14 @@ function decodeItem(value) {
     value: record.value
   };
 }
+function itemIdentityDigest(namespace, key) {
+  const keyBytes = Buffer.from(key, "utf8");
+  return sha2562(Buffer.concat([
+    namespaceIdentity(namespace),
+    uint64(keyBytes.length),
+    keyBytes
+  ]));
+}
 function decodeItemRecord(value) {
   if (!(typeof value === "string" || Buffer.isBuffer(value) || value instanceof Uint8Array)) {
     throw new TypeError("FerricStore returned a non-binary LangGraph store item");
@@ -1143,13 +1398,22 @@ var LangGraphFlow = class {
     this.options = { ...options };
   }
   async config(flow, graphContext) {
+    const invokeOptions = this.options.invokeOptions ?? {};
     const additional = await this.options.config?.(flow) ?? {};
+    const baseConfigurable = invokeOptions.configurable ?? {};
+    if (typeof baseConfigurable !== "object" || Array.isArray(baseConfigurable)) {
+      throw new TypeError("LangGraph invokeOptions configurable must be an object");
+    }
     const rawConfigurable = additional.configurable ?? {};
-    if (rawConfigurable == null || typeof rawConfigurable !== "object" || Array.isArray(rawConfigurable)) {
+    if (typeof rawConfigurable !== "object" || Array.isArray(rawConfigurable)) {
       throw new TypeError("LangGraph config configurable must be an object");
     }
+    const baseMetadata = invokeOptions.metadata ?? {};
+    if (typeof baseMetadata !== "object" || Array.isArray(baseMetadata)) {
+      throw new TypeError("LangGraph invokeOptions metadata must be an object");
+    }
     const rawMetadata = additional.metadata ?? {};
-    if (rawMetadata == null || typeof rawMetadata !== "object" || Array.isArray(rawMetadata)) {
+    if (typeof rawMetadata !== "object" || Array.isArray(rawMetadata)) {
       throw new TypeError("LangGraph config metadata must be an object");
     }
     const threadId = requireText(
@@ -1162,13 +1426,19 @@ var LangGraphFlow = class {
       "checkpointNs",
       true
     );
-    const context = graphContext === void 0 ? this.options.context == null ? new LangGraphFlowContext(flow, threadId, checkpointNs) : await this.options.context(flow) : graphContext;
+    const context = graphContext === void 0 ? this.options.context != null ? await this.options.context(flow) : Object.hasOwn(additional, "context") ? additional.context : Object.hasOwn(invokeOptions, "context") ? invokeOptions.context : new LangGraphFlowContext(flow, threadId, checkpointNs) : graphContext;
     return {
-      ...this.options.invokeOptions,
+      ...invokeOptions,
       ...additional,
-      configurable: { ...rawConfigurable, checkpoint_ns: checkpointNs, thread_id: threadId },
+      configurable: {
+        ...baseConfigurable,
+        ...rawConfigurable,
+        checkpoint_ns: checkpointNs,
+        thread_id: threadId
+      },
       context,
       metadata: {
+        ...baseMetadata,
         ...rawMetadata,
         ferricflow_id: flow.id,
         ferricflow_state: flow.logicalState,
@@ -1184,7 +1454,7 @@ var LangGraphFlow = class {
       if ((this.options.recoverExisting ?? true) && this.graph.getState != null) {
         hasCheckpoint = snapshotHasCheckpoint(await this.graph.getState(config));
       }
-      input = hasCheckpoint ? null : await (this.options.input?.(flow) ?? flow.payload);
+      input = hasCheckpoint ? null : this.options.input == null ? flow.payload : await this.options.input(flow);
     }
     const value = await this.graph.invoke(input, config);
     const configurable = config.configurable;