@ferricstore/ferricstore 0.11.11 → 0.12.1

package/dist/langgraph.cjs

@@ -0,0 +1,1548 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/langgraph.ts
+var langgraph_exports = {};
+__export(langgraph_exports, {
+  FerricStoreSaver: () => FerricStoreSaver,
+  FerricStoreStore: () => FerricStoreStore,
+  LangGraphFlow: () => LangGraphFlow,
+  LangGraphFlowContext: () => LangGraphFlowContext,
+  LangGraphFlowRun: () => LangGraphFlowRun
+});
+module.exports = __toCommonJS(langgraph_exports);
+
+// src/langgraph/checkpoint.ts
+var import_node_crypto2 = require("crypto");
+var import_langgraph = require("@langchain/langgraph");
+
+// src/agent-persistence/durability.ts
+var import_node_crypto = require("crypto");
+var import_promises = require("timers/promises");
+
+// src/errors.ts
+var FerricStoreError = class extends Error {
+  code = "ferricstore_error";
+  raw;
+  retryable;
+  safeToRetry;
+  retryAfterMs;
+  constructor(message, options = {}) {
+    super(message, { cause: options.cause });
+    this.name = new.target.name;
+    this.raw = options.raw;
+    this.retryable = options.retryable ?? structuredBooleanField(options.raw, "retryable");
+    this.safeToRetry = options.safeToRetry ?? structuredBooleanField(options.raw, "safe_to_retry");
+    this.retryAfterMs = options.retryAfterMs ?? structuredIntegerField(options.raw, "retry_after_ms");
+  }
+};
+var LockHeldError = class extends FerricStoreError {
+  code = "lock_held";
+};
+function structuredIntegerField(raw, name) {
+  const value = structuredField(raw, name);
+  if (typeof value === "number") {
+    return Number.isSafeInteger(value) && value >= 0 ? value : void 0;
+  }
+  if (typeof value === "bigint") {
+    return value >= 0n && value <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(value) : void 0;
+  }
+  const text = binaryText(value);
+  return text == null ? void 0 : nonNegativeSafeIntegerText(text);
+}
+function structuredBooleanField(raw, name) {
+  const value = structuredField(raw, name);
+  if (typeof value === "boolean") return value;
+  const text = binaryText(value)?.toLowerCase();
+  if (text === "true" || text === "1") return true;
+  if (text === "false" || text === "0") return false;
+  return void 0;
+}
+function nonNegativeSafeIntegerText(value) {
+  if (!/^[0-9]+$/u.test(value)) return void 0;
+  const parsed = Number.parseInt(value, 10);
+  return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : void 0;
+}
+function structuredField(raw, name) {
+  if (raw instanceof Map) {
+    if (raw.has(name)) return raw.get(name);
+    for (const [key, value] of raw.entries()) {
+      if (binaryText(key) === name) return value;
+    }
+    return void 0;
+  }
+  if (typeof raw === "object" && raw != null && Object.hasOwn(raw, name)) {
+    return raw[name];
+  }
+  return void 0;
+}
+function binaryText(value) {
+  if (typeof value === "string") return value;
+  if (Buffer.isBuffer(value) || value instanceof Uint8Array) return Buffer.from(value).toString("utf8");
+  return void 0;
+}
+
+// src/agent-persistence/durability.ts
+var DEFAULT_LOCK_OPTIONS = {
+  lockRetryMs: 10,
+  lockTtlMs: 3e5,
+  lockWaitMs: 3e4
+};
+function normalizeKeyPrefix(value, defaultValue) {
+  const prefix = value.length === 0 ? defaultValue : value;
+  if (prefix.includes("\0")) throw new TypeError("keyPrefix must not contain NUL bytes");
+  const normalized = prefix.replace(/:+$/u, "");
+  if (normalized.length === 0) throw new TypeError("keyPrefix must contain a character other than ':'");
+  return normalized;
+}
+function positiveInteger(value, fallback, name) {
+  const normalized = value ?? fallback;
+  if (!Number.isSafeInteger(normalized) || normalized <= 0) {
+    throw new TypeError(`${name} must be a positive safe integer`);
+  }
+  return normalized;
+}
+function nonNegativeInteger(value, fallback, name) {
+  const normalized = value ?? fallback;
+  if (!Number.isSafeInteger(normalized) || normalized < 0) {
+    throw new TypeError(`${name} must be a non-negative safe integer`);
+  }
+  return normalized;
+}
+function textResponse(value, name) {
+  if (typeof value === "string") return value;
+  if (Buffer.isBuffer(value) || value instanceof Uint8Array) return Buffer.from(value).toString("utf8");
+  throw new TypeError(`FerricStore returned an invalid ${name}`);
+}
+function arrayResponse(value, name) {
+  if (!Array.isArray(value)) throw new TypeError(`FerricStore returned an invalid ${name}`);
+  return value;
+}
+function integerResponse(value, name) {
+  const parsed = typeof value === "number" ? value : Number(textResponse(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) {
+    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;
+  let primaryError;
+  let heartbeatError;
+  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) => {
+        loseOwnership(error);
+      }
+    );
+    try {
+      result = await operation(lease);
+      operationCompleted = true;
+    } catch (error) {
+      primaryError = error;
+    } finally {
+      heartbeatAbort.abort();
+      await heartbeat;
+    }
+  } catch (error) {
+    primaryError ??= error;
+  } finally {
+    heartbeatAbort.abort();
+    for (const key of acquired.reverse()) {
+      try {
+        await client.command("UNLOCK", key, owner);
+      } catch (error) {
+        releaseError ??= error;
+      }
+    }
+  }
+  if (primaryError != null) throw errorObject(primaryError);
+  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);
+    return response === true || response === "OK" || Buffer.isBuffer(response) && response.equals(Buffer.from("OK"));
+  } catch (error) {
+    if (error instanceof LockHeldError) return false;
+    throw error;
+  }
+}
+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 {
+      await (0, import_promises.setTimeout)(waitMs, void 0, { signal });
+    } catch (error) {
+      if (signal.aborted) return;
+      onError(error);
+      return;
+    }
+    const now = performance.now();
+    let retry = false;
+    for (const key of keys) {
+      try {
+        const response = await client.command("EXTEND", key, owner, ttlMs);
+        if (integerResponse(response, "EXTEND response") !== 1) {
+          onError(new Error(`lost FerricStore lock ${JSON.stringify(key)} while mutating data`));
+          return;
+        }
+        lastExtended.set(key, now);
+      } catch (error) {
+        if (now - (lastExtended.get(key) ?? 0) >= ttlMs) {
+          onError(new Error(`lost FerricStore lock ${JSON.stringify(key)} while mutating data`, { cause: error }));
+          return;
+        }
+        retry = true;
+      }
+    }
+    waitMs = retry ? retryMs : intervalMs;
+  }
+}
+function errorObject(value) {
+  return value instanceof Error ? value : new Error("FerricStore mutation failed", { cause: 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 = {
+  __error__: -1,
+  __interrupt__: -3,
+  __resume__: -4,
+  __scheduled__: -2
+};
+var FerricStoreSaver = class extends import_langgraph.BaseCheckpointSaver {
+  client;
+  keyPrefix;
+  scanCount;
+  lockOptions;
+  constructor(client, options = {}) {
+    super(options.serde);
+    this.client = client;
+    this.keyPrefix = normalizeKeyPrefix(options.keyPrefix ?? "langgraph:checkpoint", "langgraph:checkpoint");
+    this.scanCount = positiveInteger(options.scanCount, 256, "scanCount");
+    this.lockOptions = {
+      lockRetryMs: options.lockRetryMs,
+      lockTtlMs: options.lockTtlMs,
+      lockWaitMs: options.lockWaitMs
+    };
+  }
+  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.readRecordAtEpoch(key, id, epoch);
+    } else {
+      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;
+    return await this.tupleFromRecord(key, record);
+  }
+  async *list(config, options = {}) {
+    const limit = options.limit;
+    if (limit != null && (!Number.isSafeInteger(limit) || limit < 0)) {
+      throw new TypeError("limit must be a non-negative safe integer");
+    }
+    if (limit === 0) return;
+    const beforeId = options.before == null ? void 0 : checkpointId(options.before);
+    const configurable = config.configurable;
+    const threadId = optionalText(configurable?.thread_id, "thread_id");
+    const expectedId = optionalText(configurable?.checkpoint_id ?? configurable?.thread_ts, "checkpoint_id");
+    const namespaceSpecified = configurable != null && Object.hasOwn(configurable, "checkpoint_ns");
+    const checkpointNs = namespaceSpecified ? requiredText(configurable?.checkpoint_ns, "checkpoint_ns", true) : void 0;
+    const matches = [];
+    if (threadId == null) {
+      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 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.readRecordAtEpoch(key, id, epoch);
+          if (record == null || !metadataMatches(record.metadata, options.filter)) continue;
+          matches.push({ key, record });
+        }
+      }
+      matches.sort((left, right) => right.record.checkpointId.localeCompare(left.record.checkpointId));
+      if (limit != null) matches.splice(limit);
+    }
+    for (const match of matches) yield await this.tupleFromRecord(match.key, match.record);
+  }
+  async put(config, checkpoint, metadata, _newVersions) {
+    void _newVersions;
+    const { checkpointNs, threadId } = identity(config);
+    if (typeof checkpoint.id !== "string" || checkpoint.id.length === 0) {
+      throw new TypeError("checkpoint.id must be a non-empty string");
+    }
+    const parentCheckpointId = checkpointId(config);
+    const record = {
+      checkpoint: (0, import_langgraph.copyCheckpoint)(checkpoint),
+      checkpointId: checkpoint.id,
+      checkpointNs,
+      formatVersion: FORMAT_VERSION,
+      metadata,
+      ...parentCheckpointId == null ? {} : { parentCheckpointId },
+      threadId
+    };
+    const key = this.threadKey(threadId, checkpointNs);
+    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);
+  }
+  async putWrites(config, writes, taskId) {
+    const { checkpointNs, threadId } = identity(config);
+    const id = checkpointId(config);
+    if (id == null) throw new TypeError("putWrites requires configurable.checkpoint_id");
+    if (typeof taskId !== "string" || taskId.length === 0) throw new TypeError("taskId must be non-empty text");
+    const snapshots = await Promise.all(writes.map(async ([channel, value], fallbackIndex) => {
+      if (typeof channel !== "string") throw new TypeError("pending-write channel must be text");
+      const index = WRITES_INDEX[channel] ?? fallbackIndex;
+      const record = {
+        channel,
+        formatVersion: FORMAT_VERSION,
+        index,
+        taskId,
+        value
+      };
+      return { index, value: await this.serialize(record) };
+    }));
+    const key = this.threadKey(threadId, checkpointNs);
+    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) {
+        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 (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;
+      }
+      throw new Error("concurrent FerricStore LangGraph thread deletion did not converge");
+    }, this.lockOptions);
+  }
+  catalogKey() {
+    return `${this.keyPrefix}:checkpoints`;
+  }
+  threadCatalogKey(threadId) {
+    const digest = sha256(threadId);
+    return `${this.keyPrefix}:{lgt:${digest}}:namespaces`;
+  }
+  threadLocatorCatalogKey(threadId) {
+    return `${this.threadCatalogKey(threadId)}:checkpoint-locators`;
+  }
+  threadLockKey(threadId) {
+    return `${this.keyPrefix}:{lgt:${sha256(threadId)}}:mutation-lock`;
+  }
+  threadKey(threadId, checkpointNs) {
+    return `${this.keyPrefix}:{lg:${sha256(lengthPrefixed([threadId, checkpointNs]))}}:thread`;
+  }
+  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");
+    if (typeBytes.length > 65535) throw new TypeError("serialized LangGraph type name is too long");
+    const header = Buffer.allocUnsafe(2);
+    header.writeUInt16BE(typeBytes.length);
+    return Buffer.concat([header, typeBytes, Buffer.from(data)]);
+  }
+  async deserialize(value, name) {
+    if (!(typeof value === "string" || Buffer.isBuffer(value) || value instanceof Uint8Array)) {
+      throw new TypeError(`FerricStore returned a non-binary ${name}`);
+    }
+    const bytes = typeof value === "string" ? Buffer.from(value, "utf8") : Buffer.from(value);
+    if (bytes.length < 2) throw new Error(`invalid FerricStore ${name}`);
+    const typeLength = bytes.readUInt16BE(0);
+    if (bytes.length < typeLength + 2) throw new Error(`truncated FerricStore ${name}`);
+    const type = bytes.subarray(2, typeLength + 2).toString("utf8");
+    return await this.serde.loadsTyped(type, bytes.subarray(typeLength + 2));
+  }
+  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) {
+      throw new Error("unsupported or corrupt FerricStore LangGraph checkpoint record");
+    }
+    return record;
+  }
+  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");
+      }
+    }
+    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.pendingWritesAtEpoch(key, record.checkpointId, epoch),
+      ...record.parentCheckpointId == null ? {} : { parentConfig: checkpointConfig(record.threadId, record.checkpointNs, record.parentCheckpointId) }
+    };
+  }
+  async scanHash(key, pattern) {
+    let cursor = 0;
+    const result = [];
+    do {
+      const response = arrayResponse(
+        await this.client.command("HSCAN", key, cursor, "MATCH", pattern, "COUNT", this.scanCount),
+        "HSCAN response"
+      );
+      if (response.length !== 2) throw new Error("FerricStore HSCAN response must contain cursor and items");
+      cursor = integerResponse(response[0], "HSCAN cursor");
+      const values = response[1];
+      if (values instanceof Map) {
+        result.push(...values.entries());
+      } else {
+        const flat = arrayResponse(values, "HSCAN items");
+        if (flat.length % 2 !== 0) throw new Error("FerricStore HSCAN returned an odd item count");
+        for (let index = 0; index < flat.length; index += 2) result.push([flat[index], flat[index + 1]]);
+      }
+    } while (cursor !== 0);
+    return result;
+  }
+  async threadKeys(threadId) {
+    const values = arrayResponse(
+      await this.client.command("SMEMBERS", this.threadCatalogKey(threadId)),
+      "thread checkpoint catalog response"
+    );
+    return values.map((value) => textResponse(value, "thread checkpoint key")).sort();
+  }
+  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, 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),
+        "global checkpoint catalog response"
+      );
+      if (values.length === 0) break;
+      for (const value of values) {
+        const locator = decodeCheckpointLocator(value);
+        const { checkpointId: id, threadKey: key } = locator;
+        if (expectedId != null && id !== expectedId) continue;
+        if (beforeId != null && id >= beforeId) 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;
+      }
+      offset += values.length;
+      if (values.length < this.scanCount) break;
+    }
+  }
+};
+function identity(config) {
+  if (config.configurable == null || typeof config.configurable !== "object") {
+    throw new TypeError("LangGraph config must contain configurable.thread_id");
+  }
+  return {
+    checkpointNs: requiredText(config.configurable.checkpoint_ns ?? "", "checkpoint_ns", true),
+    threadId: requiredText(config.configurable.thread_id, "thread_id")
+  };
+}
+function checkpointId(config) {
+  return optionalText(config.configurable?.checkpoint_id ?? config.configurable?.thread_ts, "checkpoint_id");
+}
+function checkpointConfig(threadId, checkpointNs, id) {
+  return { configurable: { checkpoint_id: id, checkpoint_ns: checkpointNs, thread_id: threadId } };
+}
+function requiredText(value, name, allowEmpty = false) {
+  if (typeof value !== "string" || !allowEmpty && value.length === 0) {
+    throw new TypeError(`${name} must be ${allowEmpty ? "text" : "non-empty text"}`);
+  }
+  return value;
+}
+function optionalText(value, name) {
+  if (value == null || value === "") return void 0;
+  return requiredText(value, name);
+}
+function metadataMatches(metadata, filter) {
+  return filter == null || Object.entries(filter).every(([key, value]) => {
+    const actual = Object.getOwnPropertyDescriptor(metadata, key)?.value;
+    return Object.is(actual, value);
+  });
+}
+function checkpointField(id) {
+  return `${CHECKPOINT_FIELD_PREFIX}${encodeComponent(id)}`;
+}
+function writeField(id, taskId, index) {
+  return `${WRITE_FIELD_PREFIX}${encodeComponent(id)}:${encodeComponent(taskId)}:${index}`;
+}
+function encodeComponent(value) {
+  return Buffer.from(value, "utf8").toString("base64url");
+}
+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)) {
+    throw new TypeError("FerricStore returned a non-binary checkpoint locator");
+  }
+  const bytes = typeof value === "string" ? Buffer.from(value, "utf8") : Buffer.from(value);
+  const decoded = decodeOrderedText(bytes, 0);
+  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, ...threadId == null ? {} : { threadId }, threadKey };
+}
+function orderedText(value) {
+  const output = [];
+  for (const byte of Buffer.from(value, "utf8")) {
+    if (byte === 0) output.push(0, 255);
+    else output.push(byte);
+  }
+  output.push(0, 0);
+  return Buffer.from(output);
+}
+function decodeOrderedText(bytes, start) {
+  const output = [];
+  let offset = start;
+  while (offset < bytes.length) {
+    const byte = bytes[offset];
+    if (byte == null) throw new Error("truncated FerricStore checkpoint locator");
+    offset += 1;
+    if (byte !== 0) {
+      output.push(byte);
+      continue;
+    }
+    const escaped = bytes[offset];
+    offset += 1;
+    if (escaped === 0) return { offset, value: Buffer.from(output).toString("utf8") };
+    if (escaped === 255) output.push(0);
+    else throw new Error("invalid FerricStore checkpoint locator escape");
+  }
+  throw new Error("unterminated FerricStore checkpoint locator");
+}
+function sha256(value) {
+  return (0, import_node_crypto2.createHash)("sha256").update(value).digest("hex");
+}
+function lengthPrefixed(values) {
+  const parts = [];
+  for (const value of values) {
+    const payload = Buffer.from(value, "utf8");
+    const length = Buffer.allocUnsafe(8);
+    length.writeBigUInt64BE(BigInt(payload.length));
+    parts.push(length, payload);
+  }
+  return Buffer.concat(parts);
+}
+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
+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;
+  scanCount;
+  lockOptions;
+  constructor(client, options = {}) {
+    super();
+    this.client = client;
+    this.keyPrefix = normalizeKeyPrefix(options.keyPrefix ?? "langgraph:store", "langgraph:store");
+    this.scanCount = positiveInteger(options.scanCount, 256, "scanCount");
+    this.lockOptions = {
+      lockRetryMs: options.lockRetryMs,
+      lockTtlMs: options.lockTtlMs,
+      lockWaitMs: options.lockWaitMs
+    };
+  }
+  async batch(operations) {
+    if (!Array.isArray(operations)) throw new TypeError("operations must be an array");
+    const lockKeys = operations.filter(isPutOperation).map((operation) => {
+      validatePut(operation);
+      return this.itemLockKey(operation.namespace, operation.key);
+    });
+    return await withMutationLocks(this.client, lockKeys, async (lease) => {
+      const results = [];
+      const puts = /* @__PURE__ */ new Map();
+      for (const operation of operations) {
+        if (isPutOperation(operation)) {
+          puts.set(JSON.stringify([operation.namespace, operation.key]), operation);
+          results.push(void 0);
+        } else if (isSearchOperation(operation)) {
+          results.push(await this.searchOperation(operation));
+        } else if (isGetOperation(operation)) {
+          results.push(await this.getOperation(operation));
+        } else if (isListNamespacesOperation(operation)) {
+          results.push(await this.listNamespacesOperation(operation));
+        } else {
+          throw new TypeError("unsupported LangGraph store operation");
+        }
+      }
+      for (const operation of puts.values()) await this.putOperation(operation, lease);
+      return results;
+    }, this.lockOptions);
+  }
+  catalogKey() {
+    return `${this.keyPrefix}:namespaces`;
+  }
+  namespaceKey(namespace) {
+    return `${this.keyPrefix}:{lgs:${sha2562(namespaceIdentity(namespace))}}:namespace`;
+  }
+  itemLockKey(namespace, key) {
+    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 snapshot = await this.readItemSnapshot(operation.namespace, operation.key);
+    return snapshot.record == null ? null : itemFromRecord(snapshot.record);
+  }
+  async putOperation(operation, lease) {
+    validatePut(operation);
+    const dataKey = this.itemDataKey(operation.namespace, operation.key);
+    const locator = catalogMember(operation.namespace, operation.key);
+    if (operation.value == null) {
+      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);
+    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);
+    if (operation.query != null) {
+      throw new Error(
+        "FerricStoreStore semantic query search is not configured; use metadata filters or a vector-enabled store"
+      );
+    }
+    const limit = normalizePageNumber(operation.limit, 10, "search limit");
+    const offset = normalizePageNumber(operation.offset, 0, "search offset");
+    if (limit === 0) return [];
+    const matches = [];
+    for await (const locator of this.catalogLocators()) {
+      if (!startsWithNamespace(locator.namespace, operation.namespacePrefix)) continue;
+      const item = await this.readCatalogItem(locator.namespace, locator.key);
+      if (item == null || !matchesFilter(item.value, operation.filter)) continue;
+      matches.push(item);
+      if (matches.length >= offset + limit) break;
+    }
+    return matches.slice(offset, offset + limit);
+  }
+  async listNamespacesOperation(operation) {
+    const limit = normalizePageNumber(operation.limit, 100, "namespace limit");
+    const offset = normalizePageNumber(operation.offset, 0, "namespace offset");
+    const maxDepth = operation.maxDepth == null ? void 0 : positiveInteger(operation.maxDepth, operation.maxDepth, "maxDepth");
+    if (limit === 0) return [];
+    const namespaces = /* @__PURE__ */ new Map();
+    for await (const locator of this.catalogLocators()) {
+      const item = await this.readCatalogItem(locator.namespace, locator.key);
+      if (item == null) continue;
+      if (!matchesConditions(item.namespace, operation.matchConditions)) continue;
+      const namespace = maxDepth == null ? item.namespace : item.namespace.slice(0, maxDepth);
+      namespaces.set(JSON.stringify(namespace), namespace);
+    }
+    return [...namespaces.values()].sort(compareNamespaces).slice(offset, offset + limit);
+  }
+  async readCatalogItem(namespace, key) {
+    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;
+    while (true) {
+      const values = arrayResponse(
+        await this.client.command("ZRANGE", this.catalogKey(), offset, offset + this.scanCount - 1),
+        "LangGraph store catalog response"
+      );
+      if (values.length === 0) return;
+      for (const value of values) yield decodeCatalogMember(value);
+      offset += values.length;
+      if (values.length < this.scanCount) return;
+    }
+  }
+};
+function isPutOperation(operation) {
+  return "namespace" in operation && "key" in operation && "value" in operation;
+}
+function isGetOperation(operation) {
+  return "namespace" in operation && "key" in operation && !("value" in operation);
+}
+function isSearchOperation(operation) {
+  return "namespacePrefix" in operation;
+}
+function isListNamespacesOperation(operation) {
+  return !("namespace" in operation) && !("namespacePrefix" in operation);
+}
+function validatePut(operation) {
+  validateNamespace(operation.namespace);
+  if (typeof operation.key !== "string") throw new TypeError("store key must be text");
+  if (operation.value == null) return;
+  if (typeof operation.value !== "object" || Array.isArray(operation.value)) {
+    throw new TypeError("LangGraph store values must be JSON objects");
+  }
+  validateJson(operation.value, /* @__PURE__ */ new WeakSet());
+}
+function validateNamespace(namespace) {
+  if (!Array.isArray(namespace) || namespace.length === 0) {
+    throw new Error("namespace cannot be empty");
+  }
+  for (const label of namespace) {
+    if (typeof label !== "string" || label.length === 0 || label.includes(".")) {
+      throw new Error("namespace labels must be non-empty strings without periods");
+    }
+  }
+  if (namespace[0] === "langgraph") throw new Error('root namespace label cannot be "langgraph"');
+}
+function validateNamespacePrefix(namespace) {
+  if (!Array.isArray(namespace)) throw new TypeError("namespacePrefix must be an array");
+  if (namespace.length > 0) validateNamespace(namespace);
+}
+function validateJson(value, ancestors) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return;
+  if (value === void 0) throw new TypeError("LangGraph store values must not contain undefined");
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new TypeError("LangGraph store numbers must be finite");
+    return;
+  }
+  if (typeof value !== "object") throw new TypeError("LangGraph store values must be JSON serializable");
+  if (ancestors.has(value)) throw new TypeError("LangGraph store values must not be cyclic");
+  ancestors.add(value);
+  try {
+    if (Array.isArray(value)) {
+      const keys = Reflect.ownKeys(value);
+      if (keys.length !== value.length + 1 || keys.some((key) => typeof key !== "string" || key !== "length" && !isArrayIndex(key, value.length))) {
+        throw new TypeError("LangGraph store arrays must not be sparse or customized");
+      }
+      for (let index = 0; index < value.length; index += 1) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+        if (descriptor == null || !descriptor.enumerable || !("value" in descriptor)) {
+          throw new TypeError("LangGraph store arrays contain an unsupported item");
+        }
+        validateJson(descriptor.value, ancestors);
+      }
+      return;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new TypeError("LangGraph store values must contain only JSON objects");
+    }
+    for (const key of Reflect.ownKeys(value)) {
+      if (typeof key !== "string") throw new TypeError("LangGraph store objects must not have symbol keys");
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (descriptor == null || !descriptor.enumerable || !("value" in descriptor)) {
+        throw new TypeError("LangGraph store objects contain an unsupported property");
+      }
+      validateJson(descriptor.value, ancestors);
+    }
+  } finally {
+    ancestors.delete(value);
+  }
+}
+function snapshotJsonValue(value) {
+  validateJson(value, /* @__PURE__ */ new WeakSet());
+  return JSON.parse(JSON.stringify(value));
+}
+function encodeItem(record) {
+  return Buffer.from(JSON.stringify(record), "utf8");
+}
+function itemFromRecord(record) {
+  return {
+    createdAt: new Date(record.createdAt),
+    key: record.key,
+    namespace: [...record.namespace],
+    updatedAt: new Date(record.updatedAt),
+    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");
+  }
+  const text = typeof value === "string" ? value : Buffer.from(value).toString("utf8");
+  let record;
+  try {
+    record = JSON.parse(text);
+  } catch (error) {
+    throw new Error("invalid FerricStore LangGraph store item", { cause: error });
+  }
+  if (record == null || typeof record !== "object" || record.formatVersion !== FORMAT_VERSION2 || typeof record.key !== "string" || !Array.isArray(record.namespace) || typeof record.createdAt !== "string" || typeof record.updatedAt !== "string" || record.value == null || typeof record.value !== "object") {
+    throw new Error("unsupported or corrupt FerricStore LangGraph store item");
+  }
+  return record;
+}
+function matchesFilter(value, filter) {
+  return filter == null || Object.entries(filter).every(([key, expected]) => compareValue(value[key], expected));
+}
+function compareValue(value, expected) {
+  if (expected != null && typeof expected === "object" && !Array.isArray(expected)) {
+    const entries = Object.entries(expected);
+    if (entries.length > 0 && entries.every(([key]) => FILTER_OPERATORS.has(key))) {
+      return entries.every(([operator, operand]) => applyOperator(value, operator, operand));
+    }
+    return value != null && typeof value === "object" && !Array.isArray(value) && entries.every(([key, nested]) => compareValue(value[key], nested));
+  }
+  if (Array.isArray(expected)) {
+    return Array.isArray(value) && value.length === expected.length && value.every((item, index) => compareValue(item, expected[index]));
+  }
+  return Object.is(value, expected);
+}
+function applyOperator(value, operator, expected) {
+  switch (operator) {
+    case "$eq":
+      return Object.is(value, expected);
+    case "$ne":
+      return !Object.is(value, expected);
+    case "$gt":
+      return comparable(value, expected, (left, right) => left > right);
+    case "$gte":
+      return comparable(value, expected, (left, right) => left >= right);
+    case "$in":
+      return Array.isArray(expected) && expected.some((item) => Object.is(item, value));
+    case "$lt":
+      return comparable(value, expected, (left, right) => left < right);
+    case "$lte":
+      return comparable(value, expected, (left, right) => left <= right);
+    case "$nin":
+      return !Array.isArray(expected) || expected.every((item) => !Object.is(item, value));
+    default:
+      throw new Error(`unsupported filter operator: ${operator}`);
+  }
+}
+function comparable(value, expected, compare) {
+  try {
+    return compare(Number(value), Number(expected));
+  } catch {
+    return false;
+  }
+}
+var FILTER_OPERATORS = /* @__PURE__ */ new Set(["$eq", "$gt", "$gte", "$in", "$lt", "$lte", "$ne", "$nin"]);
+function matchesConditions(namespace, conditions) {
+  return conditions == null || conditions.every((condition) => {
+    if (namespace.length < condition.path.length) return false;
+    const actual = condition.matchType === "prefix" ? namespace : [...namespace].reverse();
+    const pattern = condition.matchType === "prefix" ? condition.path : [...condition.path].reverse();
+    return pattern.every((component, index) => component === "*" || actual[index] === component);
+  });
+}
+function startsWithNamespace(namespace, prefix) {
+  return prefix.length <= namespace.length && prefix.every((value, index) => namespace[index] === value);
+}
+function normalizePageNumber(value, fallback, name) {
+  const normalized = value ?? fallback;
+  if (!Number.isSafeInteger(normalized) || normalized < 0) {
+    throw new TypeError(`${name} must be a non-negative safe integer`);
+  }
+  return normalized;
+}
+function compareNamespaces(left, right) {
+  const count = Math.min(left.length, right.length);
+  for (let index = 0; index < count; index += 1) {
+    const compared = (left[index] ?? "").localeCompare(right[index] ?? "");
+    if (compared !== 0) return compared;
+  }
+  return left.length - right.length;
+}
+function itemField(key) {
+  return `${ITEM_FIELD_PREFIX}${Buffer.from(key, "utf8").toString("base64url")}`;
+}
+function namespaceIdentity(namespace) {
+  return Buffer.concat(namespace.flatMap((component) => {
+    const payload = Buffer.from(component, "utf8");
+    return [uint64(payload.length), payload];
+  }));
+}
+function catalogMember(namespace, key) {
+  return Buffer.concat([
+    ...namespace.map(orderedText2),
+    Buffer.from([0, 0]),
+    orderedText2(key)
+  ]);
+}
+function decodeCatalogMember(value) {
+  if (!(typeof value === "string" || Buffer.isBuffer(value) || value instanceof Uint8Array)) {
+    throw new TypeError("FerricStore returned a non-binary LangGraph store locator");
+  }
+  const bytes = typeof value === "string" ? Buffer.from(value, "utf8") : Buffer.from(value);
+  const namespace = [];
+  let offset = 0;
+  while (true) {
+    if (bytes[offset] === 0 && bytes[offset + 1] === 0) {
+      offset += 2;
+      break;
+    }
+    const decoded = decodeOrderedText2(bytes, offset);
+    namespace.push(decoded.value);
+    offset = decoded.offset;
+  }
+  const key = decodeOrderedText2(bytes, offset);
+  if (key.offset !== bytes.length || namespace.length === 0) {
+    throw new Error("invalid FerricStore LangGraph store locator");
+  }
+  return { key: key.value, namespace };
+}
+function orderedText2(value) {
+  const output = [];
+  for (const byte of Buffer.from(value, "utf8")) {
+    if (byte === 0) output.push(0, 255);
+    else output.push(byte);
+  }
+  output.push(0, 0);
+  return Buffer.from(output);
+}
+function decodeOrderedText2(bytes, start) {
+  const output = [];
+  let offset = start;
+  while (offset < bytes.length) {
+    const byte = bytes[offset];
+    if (byte == null) throw new Error("truncated FerricStore LangGraph store locator");
+    offset += 1;
+    if (byte !== 0) {
+      output.push(byte);
+      continue;
+    }
+    const escaped = bytes[offset];
+    offset += 1;
+    if (escaped === 0) return { offset, value: Buffer.from(output).toString("utf8") };
+    if (escaped === 255) output.push(0);
+    else throw new Error("invalid FerricStore LangGraph store locator escape");
+  }
+  throw new Error("unterminated FerricStore LangGraph store locator");
+}
+function uint64(value) {
+  const result = Buffer.allocUnsafe(8);
+  result.writeBigUInt64BE(BigInt(value));
+  return result;
+}
+function sha2562(value) {
+  return (0, import_node_crypto3.createHash)("sha256").update(value).digest("hex");
+}
+function isArrayIndex(key, length) {
+  if (!/^(?:0|[1-9]\d*)$/u.test(key)) return false;
+  const index = Number(key);
+  return Number.isSafeInteger(index) && index >= 0 && index < length;
+}
+
+// src/langgraph/flow.ts
+var import_node_crypto4 = require("crypto");
+var import_langgraph3 = require("@langchain/langgraph");
+
+// src/outcomes.ts
+var OUTCOME_BRAND = /* @__PURE__ */ Symbol("ferricstore.outcome");
+function transition(toState, options = {}) {
+  return brandOutcome({ ...options, kind: "transition", toState });
+}
+function complete(options = {}) {
+  return brandOutcome({ ...options, kind: "complete" });
+}
+function fail(options = {}) {
+  return brandOutcome({ ...options, kind: "fail" });
+}
+function brandOutcome(outcome) {
+  Object.defineProperty(outcome, "kind", {
+    configurable: false,
+    enumerable: true,
+    value: outcome.kind,
+    writable: false
+  });
+  if (outcome.kind === "transition") {
+    Object.defineProperty(outcome, "toState", {
+      configurable: false,
+      enumerable: true,
+      value: outcome.toState,
+      writable: false
+    });
+  }
+  Object.defineProperty(outcome, OUTCOME_BRAND, {
+    configurable: false,
+    enumerable: false,
+    value: true,
+    writable: false
+  });
+  return outcome;
+}
+
+// src/langgraph/flow.ts
+var LangGraphFlowContext = class {
+  flow;
+  threadId;
+  checkpointNs;
+  constructor(flow, threadId, checkpointNs) {
+    this.flow = flow;
+    this.threadId = threadId;
+    this.checkpointNs = checkpointNs;
+  }
+  get id() {
+    return this.flow.id;
+  }
+  get type() {
+    return this.flow.type;
+  }
+  get state() {
+    return this.flow.state;
+  }
+  get partitionKey() {
+    return this.flow.partitionKey;
+  }
+  get payload() {
+    return this.flow.payload;
+  }
+  get values() {
+    return this.flow.values;
+  }
+};
+var LangGraphFlowRun = class {
+  value;
+  threadId;
+  checkpointNs;
+  interrupts;
+  constructor(value, threadId, checkpointNs, interrupts2) {
+    this.value = value;
+    this.threadId = threadId;
+    this.checkpointNs = checkpointNs;
+    this.interrupts = interrupts2;
+  }
+  get interrupted() {
+    return this.interrupts.length > 0;
+  }
+  get interruptValues() {
+    return this.interrupts.map((item) => item != null && typeof item === "object" && "value" in item ? item.value : item);
+  }
+};
+var LangGraphFlow = class {
+  graph;
+  options;
+  constructor(graph, options = {}) {
+    if (options.onInterrupt != null && options.interruptState != null) {
+      throw new TypeError("onInterrupt and interruptState are mutually exclusive");
+    }
+    if (options.interruptState != null) requireText(options.interruptState, "interruptState");
+    this.graph = graph;
+    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 (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 (typeof rawMetadata !== "object" || Array.isArray(rawMetadata)) {
+      throw new TypeError("LangGraph config metadata must be an object");
+    }
+    const threadId = requireText(
+      await (this.options.threadId?.(flow) ?? defaultThreadId(flow)),
+      "threadId"
+    );
+    const checkpointNsOption = this.options.checkpointNs ?? "";
+    const checkpointNs = requireText(
+      await (typeof checkpointNsOption === "function" ? checkpointNsOption(flow) : checkpointNsOption),
+      "checkpointNs",
+      true
+    );
+    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 {
+      ...invokeOptions,
+      ...additional,
+      configurable: {
+        ...baseConfigurable,
+        ...rawConfigurable,
+        checkpoint_ns: checkpointNs,
+        thread_id: threadId
+      },
+      context,
+      metadata: {
+        ...baseMetadata,
+        ...rawMetadata,
+        ferricflow_id: flow.id,
+        ferricflow_state: flow.logicalState,
+        ferricflow_type: flow.type
+      }
+    };
+  }
+  async invoke(flow, graphInput, graphContext) {
+    const config = await this.config(flow, graphContext);
+    let input = graphInput;
+    if (input === void 0) {
+      let hasCheckpoint = false;
+      if ((this.options.recoverExisting ?? true) && this.graph.getState != null) {
+        hasCheckpoint = snapshotHasCheckpoint(await this.graph.getState(config));
+      }
+      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;
+    return new LangGraphFlowRun(
+      value,
+      requireText(configurable?.thread_id, "thread_id"),
+      requireText(configurable?.checkpoint_ns ?? "", "checkpoint_ns", true),
+      interrupts(value)
+    );
+  }
+  async outcome(run, flow) {
+    const mapper = run.interrupted ? this.options.onInterrupt : this.options.onComplete;
+    if (mapper != null) return await mapper(run, flow);
+    const stateMeta = {
+      langgraph_checkpoint_ns: run.checkpointNs,
+      langgraph_interrupt_count: run.interrupts.length,
+      langgraph_interrupted: run.interrupted,
+      langgraph_thread_id: run.threadId
+    };
+    if (!run.interrupted) return complete({ result: run.value, stateMeta });
+    if (this.options.interruptState != null) {
+      return transition(this.options.interruptState, { stateMeta });
+    }
+    return fail({
+      error: {
+        checkpointNs: run.checkpointNs,
+        interruptCount: run.interrupts.length,
+        threadId: run.threadId,
+        type: "unhandled_langgraph_interrupt"
+      },
+      stateMeta
+    });
+  }
+  async handle(flow, graphInput, graphContext) {
+    return await this.outcome(await this.invoke(flow, graphInput, graphContext), flow);
+  }
+  async resume(flow, value, graphContext) {
+    return await this.handle(flow, new import_langgraph3.Command({ resume: value }), graphContext);
+  }
+  async handler(flow) {
+    return await this.handle(flow);
+  }
+};
+function interrupts(value) {
+  if (value == null || typeof value !== "object" || !("__interrupt__" in value)) return [];
+  const raw = value.__interrupt__;
+  if (raw == null) return [];
+  return Array.isArray(raw) ? raw : [raw];
+}
+function snapshotHasCheckpoint(snapshot) {
+  if (snapshot == null || typeof snapshot !== "object") return false;
+  const value = snapshot;
+  if (value.config != null && typeof value.config === "object") {
+    const configurable = value.config.configurable;
+    if (configurable != null && typeof configurable === "object" && typeof configurable.checkpoint_id === "string") return true;
+  }
+  return value.createdAt != null || value.metadata != null;
+}
+function defaultThreadId(flow) {
+  const identity2 = Buffer.concat([
+    identityComponent(flow.type),
+    identityComponent(flow.partitionKey),
+    identityComponent(flow.id)
+  ]);
+  return `ferricflow:${(0, import_node_crypto4.createHash)("sha256").update(identity2).digest("hex")}`;
+}
+function identityComponent(value) {
+  if (value == null) return Buffer.concat([Buffer.from("n"), uint642(0)]);
+  const payload = Buffer.from(value, "utf8");
+  return Buffer.concat([Buffer.from("s"), uint642(payload.length), payload]);
+}
+function uint642(value) {
+  const result = Buffer.allocUnsafe(8);
+  result.writeBigUInt64BE(BigInt(value));
+  return result;
+}
+function requireText(value, name, allowEmpty = false) {
+  if (typeof value !== "string" || !allowEmpty && value.length === 0 || value.includes("\0")) {
+    throw new TypeError(`${name} must be ${allowEmpty ? "text" : "non-empty text"} without NUL bytes`);
+  }
+  return value;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FerricStoreSaver,
+  FerricStoreStore,
+  LangGraphFlow,
+  LangGraphFlowContext,
+  LangGraphFlowRun
+});
+//# sourceMappingURL=langgraph.cjs.map