@rushdb/langchain 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 Collect Software Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,128 @@
-# Temporary Holding Version
+# @rushdb/langchain
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+LangChain.js and LangGraph.js integration for [RushDB](https://rushdb.com). It works
+the same on RushDB Cloud and on a self-hosted RushDB engine.
+
+| Component | LangChain / LangGraph interface | What it does |
+|---|---|---|
+| `RushDBVectorStore` | `VectorStore` | Documents with filterable metadata and vector search; the filter is applied before ranking |
+| `RushDBHybridRetriever` | `BaseRetriever` | Vector + BM25 keyword search fused in the engine (RRF or DBSF) |
+| `RushDBStore` | LangGraph `BaseStore` | Long-term agent memory: namespaces, filters, semantic search, TTL |
+| `RushDBSaver` | LangGraph `BaseCheckpointSaver` | Thread checkpoints and pending writes (human-in-the-loop, time travel) |
+
+```bash
+npm install @rushdb/langchain @langchain/core @langchain/langgraph-checkpoint
+```
+
+## Connect
+
+Every class takes a `@rushdb/javascript-sdk` client, or builds one from the
+environment.
+
+```ts
+import RushDB from '@rushdb/javascript-sdk'
+
+// RushDB Cloud
+const client = new RushDB('RUSHDB_API_KEY')
+
+// Self-hosted engine (docker run -e RUSHDB_TOKEN=... -p 127.0.0.1:3000:3000 rushdb/rushdb)
+const client = new RushDB('ENGINE_TOKEN', { direct: true, engineUrl: 'http://127.0.0.1:3000' })
+```
+
+From the environment (`clientFromEnv()`, used when `client` is omitted):
+
+| Mode | Variables |
+|---|---|
+| RushDB Cloud | `RUSHDB_API_KEY`, optional `RUSHDB_URL` |
+| Self-hosted | `RUSHDB_ENGINE_URL`, `RUSHDB_ENGINE_TOKEN`, optional `RUSHDB_SCOPE` (multitenant engine) |
+
+The rest of this page is identical for both modes.
+
+## Vector store and hybrid retrieval
+
+```ts
+import { OpenAIEmbeddings } from '@langchain/openai'
+import { RushDBHybridRetriever, RushDBVectorStore } from '@rushdb/langchain'
+
+const store = new RushDBVectorStore(new OpenAIEmbeddings({ model: 'text-embedding-3-small' }), {
+  client,
+  hybrid: true
+})
+await store.addDocuments([
+  { pageContent: 'RushDB stores JSON as a graph', metadata: { topic: 'db', year: 2026 } },
+  { pageContent: 'LangGraph persists agent state', metadata: { topic: 'agents', year: 2025 } }
+])
+
+await store.similaritySearch('graph database', 2, { year: { $gte: 2026 } })
+
+const retriever = new RushDBHybridRetriever({ vectorstore: store, k: 5, fusion: 'rrf' })
+await retriever.invoke('how are agent checkpoints stored?')
+```
+
+Filters use the LangChain/MongoDB form on metadata:
+- equality;
+- `$eq $ne $gt $gte $lt $lte`;
+- `$in $nin`;
+- `$exists`;
+- `$contains $startsWith $endsWith`;
+- `$and $or $not`.
+
+An unsupported filter throws `FilterError`; it is never ignored.
+`store.searchWithScore(query, { k, filter, where })` also takes a raw RushDB `where`,
+which can match related records.
+
+Only top-level metadata values that are strings, numbers, booleans or flat arrays of
+one of those are filterable. The full metadata, nested values included, is always
+returned.
+
+`store.delete({ ids })` deletes documents by id. `store.delete({ deleteAll: true })`
+deletes every document of the store's label.
+
+## Long-term memory store
+
+```ts
+import { RushDBStore } from '@rushdb/langchain'
+
+const store = new RushDBStore({
+  client,
+  index: { dims: 1536, embeddings: new OpenAIEmbeddings({ model: 'text-embedding-3-small' }), fields: ['text'] },
+  ttl: { defaultTtl: 60 * 24 * 30, refreshOnRead: true }
+})
+await store.put(['users', 'u1', 'memories'], 'm1', { text: 'Prefers dark mode', kind: 'pref' })
+await store.search(['users', 'u1'], { query: 'ui preferences', filter: { kind: 'pref' } })
+```
+
+RushDB records have no native TTL. Expired items are hidden from every read.
+`store.sweep()` deletes them, and `store.start()` runs it periodically.
+LangGraph.js's `put` takes no TTL, so every item gets `ttl.defaultTtl`.
+
+## Checkpointer
+
+```ts
+import { RushDBSaver } from '@rushdb/langchain'
+
+const graph = builder.compile({ checkpointer: new RushDBSaver({ client }) })
+await graph.invoke(inputs, { configurable: { thread_id: 't-1' } })
+```
+
+## Embeddings: the one mode difference
+
+The default is the same everywhere: you pass a LangChain `Embeddings` object and the
+connector stores and searches with the vectors it produces. On RushDB Cloud you can
+instead let RushDB compute embeddings:
+
+```ts
+new RushDBVectorStore('managed', { client: cloudClient })
+```
+
+A self-hosted engine never computes embeddings, so `'managed'` throws there.
+
+## Data layout
+
+The records the connector writes (labels `LC_DOCUMENT`, `LG_STORE_ITEM`,
+`LG_STORE_VECTOR`, `LG_CHECKPOINT*`) are specified in
+[`spec/README.md`](https://github.com/rush-db/langchain-rushdb/blob/main/spec/README.md).
+The Python package `langchain-rushdb` uses the same layout:
+- **Vector-store documents and store items:** either package can read what the other
+  wrote.
+- **Checkpoints:** each language reads only its own, because the serializers differ.

package/dist/checkpoint.d.ts

@@ -0,0 +1,45 @@
+/** RushDB-backed LangGraph checkpointer. */
+import type { RunnableConfig } from '@langchain/core/runnables';
+import { BaseCheckpointSaver, type ChannelVersions, type Checkpoint, type CheckpointListOptions, type CheckpointMetadata, type CheckpointTuple, type PendingWrite, type SerializerProtocol } from '@langchain/langgraph-checkpoint';
+import { type Client } from './connection.js';
+export declare const DEFAULT_LABEL = "LG_CHECKPOINT";
+export interface RushDBSaverConfig {
+    /** A RushDB client; built from the environment when omitted. */
+    client?: Client;
+    /** The serializer; LangGraph's default when omitted. */
+    serde?: SerializerProtocol;
+    /**
+     * Label of checkpoint records; channel values and pending writes use
+     * `<label>_BLOB` and `<label>_WRITE`. Separate labels keep separate
+     * applications in one RushDB project apart.
+     */
+    label?: string;
+}
+/**
+ * LangGraph checkpointer on RushDB, Cloud or self-hosted alike.
+ *
+ * Checkpoints, channel values and pending writes are records of
+ * `<label>`, `<label>_BLOB` and `<label>_WRITE` (see the
+ * repository's `spec/README.md`); serialized bytes are stored base64-encoded.
+ * Each `put` and `putWrites` is one RushDB transaction.
+ */
+export declare class RushDBSaver extends BaseCheckpointSaver {
+    readonly client: Client;
+    readonly label: string;
+    readonly blobLabel: string;
+    readonly writeLabel: string;
+    constructor(config?: RushDBSaverConfig);
+    getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined>;
+    list(config: RunnableConfig, options?: CheckpointListOptions): AsyncGenerator<CheckpointTuple>;
+    private tuple;
+    /** Checkpoints before format v4 kept pending sends as writes of the parent. */
+    private migratePendingSends;
+    private loadBlobs;
+    private loadWrites;
+    put(config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata, newVersions: ChannelVersions): Promise<RunnableConfig>;
+    putWrites(config: RunnableConfig, writes: PendingWrite[], taskId: string, taskPath?: string): Promise<void>;
+    deleteThread(threadId: string): Promise<void>;
+    /** Delete the checkpoints whose metadata `run_id` is one of `runIds`, with their pending writes. */
+    deleteForRuns(runIds: string[]): Promise<void>;
+}
+//# sourceMappingURL=checkpoint.d.ts.map

package/dist/checkpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.d.ts","sourceRoot":"","sources":["../src/checkpoint.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAC/D,OAAO,EACL,mBAAmB,EACnB,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EAEvB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EAOxB,MAAM,iCAAiC,CAAA;AAExC,OAAO,EACL,KAAK,MAAM,EAUZ,MAAM,iBAAiB,CAAA;AAExB,eAAO,MAAM,aAAa,kBAAkB,CAAA;AAG5C,MAAM,WAAW,iBAAiB;IAChC,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,wDAAwD;IACxD,KAAK,CAAC,EAAE,kBAAkB,CAAA;IAC1B;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;GAOG;AACH,qBAAa,WAAY,SAAQ,mBAAmB;IAClD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;gBAEf,MAAM,GAAE,iBAAsB;IAUpC,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;IAiBrE,IAAI,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,GAAE,qBAA0B,GAAG,cAAc,CAAC,eAAe,CAAC;YA2C3F,KAAK;IAyBnB,+EAA+E;YACjE,mBAAmB;YAkBnB,SAAS;YAoBT,UAAU;IAyBlB,GAAG,CACP,MAAM,EAAE,cAAc,EACtB,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,kBAAkB,EAC5B,WAAW,EAAE,eAAe,GAC3B,OAAO,CAAC,cAAc,CAAC;IA8DpB,SAAS,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,YAAY,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,SAAK,GAAG,OAAO,CAAC,IAAI,CAAC;IA2CvG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMnD,oGAAoG;IAC9F,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAqBrD"}

package/dist/checkpoint.js

@@ -0,0 +1,291 @@
+import { BaseCheckpointSaver, TASKS, WRITES_IDX_MAP, compareWritesSortKeys, copyCheckpoint, maxChannelVersion, writesSortKey } from '@langchain/langgraph-checkpoint';
+import { b64, clientFromEnv, deleteIds, findAll, isScalar, mirror, transact, unb64 } from './connection.js';
+export const DEFAULT_LABEL = 'LG_CHECKPOINT';
+const METADATA_PREFIX = 'metadata';
+/**
+ * LangGraph checkpointer on RushDB, Cloud or self-hosted alike.
+ *
+ * Checkpoints, channel values and pending writes are records of
+ * `<label>`, `<label>_BLOB` and `<label>_WRITE` (see the
+ * repository's `spec/README.md`); serialized bytes are stored base64-encoded.
+ * Each `put` and `putWrites` is one RushDB transaction.
+ */
+export class RushDBSaver extends BaseCheckpointSaver {
+    client;
+    label;
+    blobLabel;
+    writeLabel;
+    constructor(config = {}) {
+        super(config.serde);
+        this.client = config.client ?? clientFromEnv();
+        this.label = config.label ?? DEFAULT_LABEL;
+        this.blobLabel = `${this.label}_BLOB`;
+        this.writeLabel = `${this.label}_WRITE`;
+    }
+    // ── reads ──────────────────────────────────────────────────────────────
+    async getTuple(config) {
+        const configurable = config.configurable ?? {};
+        const where = {
+            thread_id: String(configurable.thread_id),
+            checkpoint_ns: configurable.checkpoint_ns ?? ''
+        };
+        if (configurable.checkpoint_id)
+            where.checkpoint_id = configurable.checkpoint_id;
+        const page = await this.client.records.find({
+            labels: [this.label],
+            where,
+            orderBy: { checkpoint_id: 'desc' },
+            limit: 1
+        });
+        if (!page.data.length)
+            return undefined;
+        return this.tuple(page.data[0].data);
+    }
+    async *list(config, options = {}) {
+        const { filter, before, limit } = options;
+        const configurable = config?.configurable ?? {};
+        const where = {};
+        if (configurable.thread_id !== undefined)
+            where.thread_id = String(configurable.thread_id);
+        if (configurable.checkpoint_ns !== undefined && configurable.checkpoint_ns !== null) {
+            where.checkpoint_ns = configurable.checkpoint_ns;
+        }
+        if (configurable.checkpoint_id)
+            where.checkpoint_id = configurable.checkpoint_id;
+        // The engine compares numbers and datetimes only: `before` (a string id)
+        // is applied here, on rows already ordered by id, newest first.
+        const beforeId = before?.configurable?.checkpoint_id;
+        const [pushed, pushedAll] = metadataPushdown(filter);
+        Object.assign(where, pushed);
+        const exact = pushedAll && beforeId === undefined;
+        const search = { labels: [this.label], orderBy: { checkpoint_id: 'desc' } };
+        if (Object.keys(where).length)
+            search.where = where;
+        let rows;
+        if (exact && limit !== undefined) {
+            if (limit <= 0)
+                return;
+            const page = await this.client.records.find({ ...search, limit });
+            rows = page.data.map((r) => r.data);
+        }
+        else {
+            rows = await findAll(this.client, search);
+        }
+        let count = 0;
+        for (const row of rows) {
+            if (limit !== undefined && count >= limit)
+                return;
+            if (beforeId !== undefined && row.checkpoint_id >= beforeId)
+                continue;
+            const checkpointTuple = await this.tuple(row);
+            if (filter &&
+                !Object.entries(filter).every(([k, v]) => checkpointTuple.metadata?.[k] === v)) {
+                continue;
+            }
+            count += 1;
+            yield checkpointTuple;
+        }
+    }
+    async tuple(row) {
+        const { thread_id, checkpoint_ns, checkpoint_id } = row;
+        const checkpoint = await this.serde.loadsTyped(row.checkpoint_type, unb64(row.checkpoint));
+        const metadata = await this.serde.loadsTyped(row.metadata_type, unb64(row.metadata));
+        const loaded = {
+            ...checkpoint,
+            channel_values: await this.loadBlobs(thread_id, checkpoint_ns, checkpoint.channel_versions)
+        };
+        if (checkpoint.v < 4 && row.parent_checkpoint_id) {
+            await this.migratePendingSends(loaded, thread_id, checkpoint_ns, row.parent_checkpoint_id);
+        }
+        const tuple = {
+            config: { configurable: { thread_id, checkpoint_ns, checkpoint_id } },
+            checkpoint: loaded,
+            metadata,
+            pendingWrites: await this.loadWrites(thread_id, checkpoint_ns, checkpoint_id)
+        };
+        if (row.parent_checkpoint_id) {
+            tuple.parentConfig = {
+                configurable: { thread_id, checkpoint_ns, checkpoint_id: row.parent_checkpoint_id }
+            };
+        }
+        return tuple;
+    }
+    /** Checkpoints before format v4 kept pending sends as writes of the parent. */
+    async migratePendingSends(checkpoint, threadId, checkpointNs, parentId) {
+        const sends = (await this.loadWrites(threadId, checkpointNs, parentId))
+            .filter(([, channel]) => channel === TASKS)
+            .map(([, , value]) => value);
+        checkpoint.channel_values ??= {};
+        checkpoint.channel_values[TASKS] = sends;
+        checkpoint.channel_versions ??= {};
+        const versions = Object.values(checkpoint.channel_versions);
+        checkpoint.channel_versions[TASKS] = versions.length
+            ? maxChannelVersion(...versions)
+            : this.getNextVersion(undefined);
+    }
+    async loadBlobs(threadId, checkpointNs, versions) {
+        const channels = Object.keys(versions ?? {});
+        if (!channels.length)
+            return {};
+        const wanted = new Set(channels.map((c) => JSON.stringify([c, String(versions[c])])));
+        const rows = await findAll(this.client, {
+            labels: [this.blobLabel],
+            where: { thread_id: threadId, checkpoint_ns: checkpointNs, channel: { $in: channels.sort() } }
+        });
+        const values = {};
+        for (const row of rows) {
+            if (!wanted.has(JSON.stringify([row.channel, row.version])) || row.blob_type === 'empty')
+                continue;
+            values[row.channel] = await this.serde.loadsTyped(row.blob_type, unb64(row.blob ?? ''));
+        }
+        return values;
+    }
+    async loadWrites(threadId, checkpointNs, checkpointId) {
+        const rows = await findAll(this.client, {
+            labels: [this.writeLabel],
+            where: { thread_id: threadId, checkpoint_ns: checkpointNs, checkpoint_id: checkpointId }
+        });
+        rows.sort((a, b) => compareWritesSortKeys(writesSortKey(a.task_path, a.task_id, Number(a.idx)), writesSortKey(b.task_path, b.task_id, Number(b.idx))));
+        return Promise.all(rows.map(async (r) => [r.task_id, r.channel, await this.serde.loadsTyped(r.blob_type, unb64(r.blob ?? ''))]));
+    }
+    // ── writes ─────────────────────────────────────────────────────────────
+    async put(config, checkpoint, metadata, newVersions) {
+        const configurable = config.configurable ?? {};
+        if (configurable.thread_id === undefined) {
+            throw new Error('Failed to put checkpoint: the config is missing "configurable.thread_id".');
+        }
+        const threadId = String(configurable.thread_id);
+        const checkpointNs = configurable.checkpoint_ns ?? '';
+        const parentId = configurable.checkpoint_id;
+        const { channel_values: values, ...stored } = copyCheckpoint(checkpoint);
+        const channels = Object.keys(newVersions ?? {});
+        const present = new Set(channels.length
+            ? (await findAll(this.client, {
+                labels: [this.blobLabel],
+                where: { thread_id: threadId, checkpoint_ns: checkpointNs, channel: { $in: [...channels].sort() } }
+            })).map((r) => JSON.stringify([r.channel, r.version]))
+            : []);
+        const blobs = [];
+        for (const channel of channels) {
+            const version = String(newVersions[channel]);
+            if (present.has(JSON.stringify([channel, version])))
+                continue;
+            const row = { thread_id: threadId, checkpoint_ns: checkpointNs, channel, version };
+            if (channel in values) {
+                const [blobType, data] = await this.serde.dumpsTyped(values[channel]);
+                row.blob_type = blobType;
+                row.blob = b64(data);
+            }
+            else {
+                row.blob_type = 'empty';
+            }
+            blobs.push(row);
+        }
+        const [checkpointType, checkpointData] = await this.serde.dumpsTyped(stored);
+        const [metadataType, metadataData] = await this.serde.dumpsTyped(metadata);
+        const record = {
+            thread_id: threadId,
+            checkpoint_ns: checkpointNs,
+            checkpoint_id: checkpoint.id,
+            checkpoint_type: checkpointType,
+            checkpoint: b64(checkpointData),
+            metadata_type: metadataType,
+            metadata: b64(metadataData),
+            ...mirror(METADATA_PREFIX, (metadata ?? {}))
+        };
+        if (parentId)
+            record.parent_checkpoint_id = parentId;
+        const replaced = (await findAll(this.client, {
+            labels: [this.label],
+            where: { thread_id: threadId, checkpoint_ns: checkpointNs, checkpoint_id: checkpoint.id }
+        })).map((r) => r.__id);
+        await transact(this.client, replaced, [
+            [this.blobLabel, blobs],
+            [this.label, [record]]
+        ]);
+        return { configurable: { thread_id: threadId, checkpoint_ns: checkpointNs, checkpoint_id: checkpoint.id } };
+    }
+    async putWrites(config, writes, taskId, taskPath = '') {
+        const configurable = config.configurable ?? {};
+        if (configurable.thread_id === undefined) {
+            throw new Error('Failed to put writes: the config is missing "configurable.thread_id".');
+        }
+        if (configurable.checkpoint_id === undefined) {
+            throw new Error('Failed to put writes: the config is missing "configurable.checkpoint_id".');
+        }
+        const threadId = String(configurable.thread_id);
+        const checkpointNs = configurable.checkpoint_ns ?? '';
+        const checkpointId = configurable.checkpoint_id;
+        const existing = new Map();
+        for (const r of await findAll(this.client, {
+            labels: [this.writeLabel],
+            where: { thread_id: threadId, checkpoint_ns: checkpointNs, checkpoint_id: checkpointId, task_id: taskId }
+        })) {
+            existing.set(Number(r.idx), r.__id);
+        }
+        const replaced = [];
+        const rows = [];
+        for (const [position, [channel, value]] of writes.entries()) {
+            const idx = WRITES_IDX_MAP[channel] ?? position;
+            const prior = existing.get(idx);
+            if (prior !== undefined) {
+                if (idx >= 0)
+                    continue;
+                replaced.push(prior);
+            }
+            const [blobType, data] = await this.serde.dumpsTyped(value);
+            rows.push({
+                thread_id: threadId,
+                checkpoint_ns: checkpointNs,
+                checkpoint_id: checkpointId,
+                task_id: taskId,
+                task_path: taskPath,
+                idx,
+                channel,
+                blob_type: blobType,
+                blob: b64(data)
+            });
+        }
+        await transact(this.client, replaced, [[this.writeLabel, rows]]);
+    }
+    async deleteThread(threadId) {
+        for (const label of [this.label, this.blobLabel, this.writeLabel]) {
+            await this.client.records.delete({ labels: [label], where: { thread_id: String(threadId) } });
+        }
+    }
+    /** Delete the checkpoints whose metadata `run_id` is one of `runIds`, with their pending writes. */
+    async deleteForRuns(runIds) {
+        if (!runIds.length)
+            return;
+        const rows = await findAll(this.client, {
+            labels: [this.label],
+            where: { [`${METADATA_PREFIX}.run_id`]: { $in: runIds.map(String) } }
+        });
+        for (const row of rows) {
+            await this.client.records.delete({
+                labels: [this.writeLabel],
+                where: {
+                    thread_id: row.thread_id,
+                    checkpoint_ns: row.checkpoint_ns,
+                    checkpoint_id: row.checkpoint_id
+                }
+            });
+        }
+        await deleteIds(this.client, rows.map((r) => r.__id));
+    }
+}
+/** Equality on scalar metadata runs in the engine; the rest in the client. */
+function metadataPushdown(filter) {
+    if (!filter || !Object.keys(filter).length)
+        return [{}, true];
+    const pushed = {};
+    let exact = true;
+    for (const [key, val] of Object.entries(filter)) {
+        if (isScalar(val))
+            pushed[`${METADATA_PREFIX}.${key}`] = val;
+        else
+            exact = false;
+    }
+    return [pushed, exact];
+}
+//# sourceMappingURL=checkpoint.js.map