@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/dist/shared/checkpointer/http-saver.js

@@ -0,0 +1,335 @@
+/**
+ * HTTP-backed LangGraph checkpoint saver.
+ *
+ * Routes checkpoint persistence through the Stigmer Side-Channel Proxy
+ * (api.stigmer.ai/v1/proxy) instead of connecting directly to MongoDB.
+ * The runner never touches MongoDB — the Java CheckpointerProxyController
+ * handles all database operations server-side.
+ *
+ * Serialization uses the LangGraph JsonPlusSerializer. Binary payloads
+ * are transported as MongoDB Extended JSON v2 $binary objects:
+ *
+ *   {"$binary": {"base64": "<base64-data>", "subType": "00"}}
+ *
+ * The Java proxy calls Document.parse(json) which handles $binary
+ * natively, and doc.toJson() emits the same format on reads.
+ *
+ * Every request runs through the shared bounded-backoff loop
+ * (http-retry.ts's fetchWithRetry, with this saver's policy: transient
+ * classification + a per-request abort timeout). That loop is the ONLY
+ * retry layer between an agent execution and its checkpoints — the deep
+ * agent activity is deliberately non-retryable at the Temporal level
+ * (maximumAttempts: 1; replaying a whole run is not safe), so before
+ * this existed a single dropped request killed the execution. Retrying puts
+ * is safe by server contract:
+ * CheckpointStore documents putCheckpoint/putWrite as keyed save-or-replace
+ * upserts. Budget exhaustion still fails loudly — checkpoints are not
+ * lossy-tolerable (unlike status updates, see status.ts), and silently
+ * dropping one would corrupt resume state.
+ *
+ * The bearer credential is a shared ref read on EVERY request, never a
+ * header frozen at construction: a saver lives for a whole turn, and the
+ * runner's control-plane credential rotates underneath it (a pool member
+ * claimed for a session, a sandbox token renewed in place). A frozen header
+ * kept presenting the boot credential and every read after the rotation
+ * was refused (config.ts header; ProxyArtifactStorage holds its credential
+ * the same way).
+ */
+import { BaseCheckpointSaver, } from "@langchain/langgraph-checkpoint";
+import { turnKeyHeader } from "../execution-context.js";
+import { fetchWithRetry } from "../http-retry.js";
+function encodeB64(data) {
+    if (typeof Buffer !== "undefined") {
+        return Buffer.from(data).toString("base64");
+    }
+    let binary = "";
+    for (const byte of data) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary);
+}
+function decodeB64(b64) {
+    if (typeof Buffer !== "undefined") {
+        return new Uint8Array(Buffer.from(b64, "base64"));
+    }
+    const binary = atob(b64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+function encodeBinary(payload) {
+    return { $binary: { base64: encodeB64(payload), subType: "00" } };
+}
+function decodeBinary(obj) {
+    return decodeB64(obj.$binary.base64);
+}
+function configThread(config) {
+    return config.configurable?.thread_id ?? "";
+}
+function configNs(config) {
+    return config.configurable?.checkpoint_ns ?? "";
+}
+function configCheckpointId(config) {
+    return config.configurable?.checkpoint_id;
+}
+function configOrg(config) {
+    return config.configurable?.org;
+}
+/**
+ * Default transient-retry policy. Wider than status.ts's DEFAULT_PERSIST_RETRY
+ * (3 retries, ~700 ms) on purpose: a dropped status update is lossy-tolerable,
+ * a dropped checkpoint kills the execution, so the budget here is sized to
+ * span a pod-restart reroute (~7.75 s of delays across 5 retries). Worst case
+ * with every attempt hanging — 6 x 30 s + delays, ~3.7 min — stays well inside
+ * the deep-agent activity's 1 h startToCloseTimeout (no heartbeatTimeout).
+ */
+const DEFAULT_RETRY = {
+    baseDelayMs: 250,
+    backoffFactor: 2,
+    maxRetries: 5,
+    requestTimeoutMs: 30_000,
+};
+export class HttpCheckpointSaver extends BaseCheckpointSaver {
+    baseUrl;
+    authToken;
+    retryPolicy;
+    constructor(proxyEndpoint, authToken, options = {}) {
+        super();
+        this.baseUrl = `${proxyEndpoint.replace(/\/+$/, "")}/v1/proxy/checkpoints`;
+        this.authToken = authToken;
+        this.retryPolicy = {
+            label: "HttpCheckpointSaver",
+            baseDelayMs: options.baseDelayMs ?? DEFAULT_RETRY.baseDelayMs,
+            backoffFactor: options.backoffFactor ?? DEFAULT_RETRY.backoffFactor,
+            maxRetries: options.maxRetries ?? DEFAULT_RETRY.maxRetries,
+            requestTimeoutMs: options.requestTimeoutMs ?? DEFAULT_RETRY.requestTimeoutMs,
+            delayFn: options.delayFn,
+        };
+    }
+    /** The request headers as of now: the credential is resolved here, per request (the header). */
+    get headers() {
+        return {
+            Authorization: `Bearer ${this.authToken.current ?? ""}`,
+            "Content-Type": "application/json",
+            // In the agent host: the turn's key, which the runner's local proxy checks.
+            ...turnKeyHeader(),
+        };
+    }
+    fetchWithRetry(url, init) {
+        return fetchWithRetry(url, init, this.retryPolicy);
+    }
+    async serializeTyped(obj) {
+        const [typeTag, payload] = await this.serde.dumpsTyped(obj);
+        return [typeTag, encodeBinary(payload)];
+    }
+    async deserializeTyped(typeTag, binaryObj) {
+        const payload = decodeBinary(binaryObj);
+        return this.serde.loadsTyped(typeTag, payload);
+    }
+    async getTuple(config) {
+        const threadId = configThread(config);
+        const checkpointNs = configNs(config);
+        const checkpointId = configCheckpointId(config);
+        const params = new URLSearchParams({
+            thread_id: threadId,
+            checkpoint_ns: checkpointNs,
+        });
+        if (checkpointId) {
+            params.set("checkpoint_id", checkpointId);
+        }
+        const resp = await this.fetchWithRetry(`${this.baseUrl}/checkpoint?${params}`, {
+            headers: this.headers,
+        });
+        if (resp.status === 404)
+            return undefined;
+        if (!resp.ok) {
+            throw new Error(`Checkpoint GET failed: ${resp.status} ${resp.statusText}`);
+        }
+        const doc = (await resp.json());
+        return this.parseCheckpointDoc(doc, threadId, checkpointNs);
+    }
+    async *list(config, options) {
+        const threadId = configThread(config);
+        const checkpointNs = configNs(config);
+        const limit = options?.limit ?? 10;
+        const params = new URLSearchParams({
+            thread_id: threadId,
+            checkpoint_ns: checkpointNs,
+            limit: String(limit),
+        });
+        const beforeId = options?.before?.configurable?.checkpoint_id;
+        if (beforeId) {
+            params.set("before", beforeId);
+        }
+        const resp = await this.fetchWithRetry(`${this.baseUrl}/checkpoints?${params}`, {
+            headers: this.headers,
+        });
+        if (!resp.ok) {
+            throw new Error(`Checkpoints list failed: ${resp.status} ${resp.statusText}`);
+        }
+        const data = (await resp.json());
+        for (const doc of data.checkpoints ?? []) {
+            yield await this.parseCheckpointDocWithoutWrites(doc);
+        }
+    }
+    async put(config, checkpoint, metadata, _newVersions) {
+        const threadId = configThread(config);
+        const checkpointNs = configNs(config);
+        const checkpointId = checkpoint.id;
+        const [cpType, cpBinary] = await this.serializeTyped(checkpoint);
+        const [mdType, mdBinary] = await this.serializeTyped(metadata);
+        const doc = {
+            thread_id: threadId,
+            checkpoint_ns: checkpointNs,
+            checkpoint_id: checkpointId,
+            parent_checkpoint_id: configCheckpointId(config),
+            type: cpType,
+            checkpoint: cpBinary,
+            metadata_type: mdType,
+            metadata: mdBinary,
+        };
+        const orgId = configOrg(config);
+        if (orgId)
+            doc.org_id = orgId;
+        const resp = await this.fetchWithRetry(`${this.baseUrl}/checkpoint`, {
+            method: "PUT",
+            headers: this.headers,
+            body: JSON.stringify(doc),
+        });
+        if (!resp.ok) {
+            throw new Error(`Checkpoint PUT failed: ${resp.status} ${resp.statusText}`);
+        }
+        return {
+            configurable: {
+                thread_id: threadId,
+                checkpoint_ns: checkpointNs,
+                checkpoint_id: checkpointId,
+            },
+        };
+    }
+    async deleteThread(threadId) {
+        const params = new URLSearchParams({ thread_id: threadId });
+        const resp = await this.fetchWithRetry(`${this.baseUrl}/thread?${params}`, {
+            method: "DELETE",
+            headers: this.headers,
+        });
+        if (!resp.ok && resp.status !== 404) {
+            throw new Error(`Checkpoint DELETE thread failed: ${resp.status} ${resp.statusText}`);
+        }
+    }
+    async putWrites(config, writes, taskId) {
+        const threadId = configThread(config);
+        const checkpointNs = configNs(config);
+        const checkpointId = configCheckpointId(config);
+        const orgId = configOrg(config);
+        const docs = await Promise.all(writes.map(async ([channel, value], idx) => {
+            const [typeTag, binaryVal] = await this.serializeTyped(value);
+            const doc = {
+                thread_id: threadId,
+                checkpoint_ns: checkpointNs,
+                checkpoint_id: checkpointId,
+                task_id: taskId,
+                idx,
+                channel,
+                type: typeTag,
+                value: binaryVal,
+            };
+            if (orgId)
+                doc.org_id = orgId;
+            return doc;
+        }));
+        const resp = await this.fetchWithRetry(`${this.baseUrl}/writes`, {
+            method: "PUT",
+            headers: this.headers,
+            body: JSON.stringify({ writes: docs }),
+        });
+        if (!resp.ok) {
+            throw new Error(`Checkpoint writes PUT failed: ${resp.status} ${resp.statusText}`);
+        }
+    }
+    async parseCheckpointDoc(doc, threadId, checkpointNs) {
+        const cpType = doc.type ?? "json";
+        const checkpoint = (await this.deserializeTyped(cpType, doc.checkpoint));
+        const mdType = doc.metadata_type ?? cpType;
+        const metadata = doc.metadata
+            ? (await this.deserializeTyped(mdType, doc.metadata))
+            : undefined;
+        let parentConfig;
+        if (doc.parent_checkpoint_id) {
+            parentConfig = {
+                configurable: {
+                    thread_id: doc.thread_id,
+                    checkpoint_ns: doc.checkpoint_ns ?? "",
+                    checkpoint_id: doc.parent_checkpoint_id,
+                },
+            };
+        }
+        const writesResp = await this.fetchWithRetry(`${this.baseUrl}/writes?${new URLSearchParams({
+            thread_id: threadId,
+            checkpoint_ns: checkpointNs,
+            checkpoint_id: doc.checkpoint_id,
+        })}`, { headers: this.headers });
+        // Fail loudly, never degrade: this used to map ANY non-ok response to "no
+        // pending writes", which silently stripped resume state on a transient
+        // 500 — a checkpoint would load without the writes recorded against it.
+        if (!writesResp.ok) {
+            throw new Error(`Checkpoint writes GET failed: ${writesResp.status} ${writesResp.statusText}`);
+        }
+        const pendingWrites = await this.parseWrites((await writesResp.json()));
+        return {
+            config: {
+                configurable: {
+                    thread_id: doc.thread_id,
+                    checkpoint_ns: doc.checkpoint_ns ?? "",
+                    checkpoint_id: doc.checkpoint_id,
+                },
+            },
+            checkpoint,
+            metadata,
+            parentConfig,
+            pendingWrites,
+        };
+    }
+    async parseCheckpointDocWithoutWrites(doc) {
+        const cpType = doc.type ?? "json";
+        const checkpoint = (await this.serde.loadsTyped(cpType, decodeBinary(doc.checkpoint)));
+        const mdType = doc.metadata_type ?? cpType;
+        const metadata = doc.metadata
+            ? (await this.serde.loadsTyped(mdType, decodeBinary(doc.metadata)))
+            : undefined;
+        let parentConfig;
+        if (doc.parent_checkpoint_id) {
+            parentConfig = {
+                configurable: {
+                    thread_id: doc.thread_id,
+                    checkpoint_ns: doc.checkpoint_ns ?? "",
+                    checkpoint_id: doc.parent_checkpoint_id,
+                },
+            };
+        }
+        return {
+            config: {
+                configurable: {
+                    thread_id: doc.thread_id,
+                    checkpoint_ns: doc.checkpoint_ns ?? "",
+                    checkpoint_id: doc.checkpoint_id,
+                },
+            },
+            checkpoint,
+            metadata,
+            parentConfig,
+        };
+    }
+    async parseWrites(data) {
+        const result = [];
+        for (const w of data.writes ?? []) {
+            const wType = w.type ?? "json";
+            const value = await this.serde.loadsTyped(wType, decodeBinary(w.value));
+            result.push([w.task_id, w.channel, value]);
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=http-saver.js.map

package/dist/shared/checkpointer/http-saver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-saver.js","sourceRoot":"","sources":["../../../src/shared/checkpointer/http-saver.ts"],"names":[],"mappings":"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"}

package/dist/shared/checkpointer/sqlite-saver.d.ts

@@ -0,0 +1,54 @@
+/**
+ * SQLite-backed LangGraph checkpoint saver — the durable checkpointer for the
+ * OSS / local edition.
+ *
+ * Why this exists: the OSS-local default used to be the ephemeral `MemorySaver`,
+ * recreated empty on every `ExecuteDeepAgent` invocation. The Temporal workflow
+ * re-invokes the activity with the SAME `thread_id` on HITL approval, pause/
+ * resume, and transient recovery — but with an empty checkpointer the graph has
+ * nothing to resume from, so it replays from the original user message instead
+ * of continuing after the interrupt. This saver makes the checkpoint survive
+ * across invocations on a single machine, so those re-invocations resume via
+ * `Command(resume)` exactly like the cloud (`http`) path (see stigmer/stigmer#204).
+ *
+ * Implementation notes:
+ * - Backed by Node's built-in `node:sqlite` (`DatabaseSync`). Zero external
+ *   dependencies and bundles cleanly into the slim artifact — `node:`-prefixed
+ *   builtins stay external to esbuild, unlike a native addon such as
+ *   `better-sqlite3` (which the official `@langchain/langgraph-checkpoint-sqlite`
+ *   depends on and which cannot be bundled).
+ * - Schema and the `put` / `putWrites` conflict-resolution semantics mirror the
+ *   official `@langchain/langgraph-checkpoint-sqlite` saver, so a checkpoint
+ *   written here is byte-compatible with the reference implementation.
+ * - Serialization uses the inherited `JsonPlusSerializer` (`this.serde`), exactly
+ *   like {@link HttpCheckpointSaver}. Serialized payloads are stored as raw BLOBs
+ *   and read back as `Uint8Array`, so binary (msgpack) payloads round-trip
+ *   losslessly — this is why writes are read via a dedicated query rather than
+ *   the reference saver's `CAST(value AS TEXT)` JSON aggregation.
+ * - WAL journaling plus a busy timeout make the file safe to open from more than
+ *   one process at once (the CLI daemon and the desktop runner can share a HOME).
+ */
+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";
+export declare class SqliteCheckpointSaver extends BaseCheckpointSaver {
+    private readonly db;
+    private isSetup;
+    constructor(dbPath: string, serde?: SerializerProtocol);
+    /**
+     * Create the schema on first use. WAL + the constructor's busy timeout make
+     * concurrent readers/writers (across processes sharing the file) safe. The
+     * tables and their primary keys mirror the official
+     * `@langchain/langgraph-checkpoint-sqlite` schema.
+     */
+    private setup;
+    getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined>;
+    list(config: RunnableConfig, options?: CheckpointListOptions): AsyncGenerator<CheckpointTuple>;
+    put(config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata, _newVersions: ChannelVersions): Promise<RunnableConfig>;
+    putWrites(config: RunnableConfig, writes: PendingWrite[], taskId: string): Promise<void>;
+    deleteThread(threadId: string): Promise<void>;
+    /** Close the underlying database handle. Idempotent and non-throwing. */
+    close(): void;
+    /** Deserialize a checkpoint row and hydrate its pending writes. */
+    private rowToTuple;
+    private loadPendingWrites;
+}

package/dist/shared/checkpointer/sqlite-saver.js

@@ -0,0 +1,272 @@
+/**
+ * SQLite-backed LangGraph checkpoint saver — the durable checkpointer for the
+ * OSS / local edition.
+ *
+ * Why this exists: the OSS-local default used to be the ephemeral `MemorySaver`,
+ * recreated empty on every `ExecuteDeepAgent` invocation. The Temporal workflow
+ * re-invokes the activity with the SAME `thread_id` on HITL approval, pause/
+ * resume, and transient recovery — but with an empty checkpointer the graph has
+ * nothing to resume from, so it replays from the original user message instead
+ * of continuing after the interrupt. This saver makes the checkpoint survive
+ * across invocations on a single machine, so those re-invocations resume via
+ * `Command(resume)` exactly like the cloud (`http`) path (see stigmer/stigmer#204).
+ *
+ * Implementation notes:
+ * - Backed by Node's built-in `node:sqlite` (`DatabaseSync`). Zero external
+ *   dependencies and bundles cleanly into the slim artifact — `node:`-prefixed
+ *   builtins stay external to esbuild, unlike a native addon such as
+ *   `better-sqlite3` (which the official `@langchain/langgraph-checkpoint-sqlite`
+ *   depends on and which cannot be bundled).
+ * - Schema and the `put` / `putWrites` conflict-resolution semantics mirror the
+ *   official `@langchain/langgraph-checkpoint-sqlite` saver, so a checkpoint
+ *   written here is byte-compatible with the reference implementation.
+ * - Serialization uses the inherited `JsonPlusSerializer` (`this.serde`), exactly
+ *   like {@link HttpCheckpointSaver}. Serialized payloads are stored as raw BLOBs
+ *   and read back as `Uint8Array`, so binary (msgpack) payloads round-trip
+ *   losslessly — this is why writes are read via a dedicated query rather than
+ *   the reference saver's `CAST(value AS TEXT)` JSON aggregation.
+ * - WAL journaling plus a busy timeout make the file safe to open from more than
+ *   one process at once (the CLI daemon and the desktop runner can share a HOME).
+ */
+import { DatabaseSync } from "node:sqlite";
+import { BaseCheckpointSaver, WRITES_IDX_MAP, copyCheckpoint, } from "@langchain/langgraph-checkpoint";
+/** Milliseconds SQLite waits on a locked database before erroring (WAL busy handler). */
+const DEFAULT_BUSY_TIMEOUT_MS = 5_000;
+export class SqliteCheckpointSaver extends BaseCheckpointSaver {
+    db;
+    isSetup = false;
+    constructor(dbPath, serde) {
+        super(serde);
+        this.db = new DatabaseSync(dbPath, { timeout: DEFAULT_BUSY_TIMEOUT_MS });
+    }
+    /**
+     * Create the schema on first use. WAL + the constructor's busy timeout make
+     * concurrent readers/writers (across processes sharing the file) safe. The
+     * tables and their primary keys mirror the official
+     * `@langchain/langgraph-checkpoint-sqlite` schema.
+     */
+    setup() {
+        if (this.isSetup)
+            return;
+        this.db.exec("PRAGMA journal_mode=WAL");
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS checkpoints (
+        thread_id TEXT NOT NULL,
+        checkpoint_ns TEXT NOT NULL DEFAULT '',
+        checkpoint_id TEXT NOT NULL,
+        parent_checkpoint_id TEXT,
+        type TEXT,
+        checkpoint BLOB,
+        metadata BLOB,
+        PRIMARY KEY (thread_id, checkpoint_ns, checkpoint_id)
+      );
+    `);
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS writes (
+        thread_id TEXT NOT NULL,
+        checkpoint_ns TEXT NOT NULL DEFAULT '',
+        checkpoint_id TEXT NOT NULL,
+        task_id TEXT NOT NULL,
+        idx INTEGER NOT NULL,
+        channel TEXT NOT NULL,
+        type TEXT,
+        value BLOB,
+        PRIMARY KEY (thread_id, checkpoint_ns, checkpoint_id, task_id, idx)
+      );
+    `);
+        this.isSetup = true;
+    }
+    async getTuple(config) {
+        this.setup();
+        const threadId = config.configurable?.thread_id;
+        const checkpointNs = config.configurable?.checkpoint_ns ?? "";
+        const checkpointId = config.configurable?.checkpoint_id;
+        const row = (checkpointId
+            ? this.db
+                .prepare(`SELECT thread_id, checkpoint_ns, checkpoint_id, parent_checkpoint_id, type, checkpoint, metadata
+             FROM checkpoints
+             WHERE thread_id = ? AND checkpoint_ns = ? AND checkpoint_id = ?`)
+                .get(threadId ?? null, checkpointNs, checkpointId)
+            : this.db
+                .prepare(`SELECT thread_id, checkpoint_ns, checkpoint_id, parent_checkpoint_id, type, checkpoint, metadata
+             FROM checkpoints
+             WHERE thread_id = ? AND checkpoint_ns = ?
+             ORDER BY checkpoint_id DESC LIMIT 1`)
+                .get(threadId ?? null, checkpointNs));
+        if (row === undefined)
+            return undefined;
+        return this.rowToTuple(row);
+    }
+    async *list(config, options) {
+        this.setup();
+        const threadId = config.configurable?.thread_id;
+        const checkpointNs = config.configurable?.checkpoint_ns;
+        const before = options?.before?.configurable?.checkpoint_id;
+        const limit = options?.limit;
+        // Supported filter subset mirrors HttpCheckpointSaver (thread_id /
+        // checkpoint_ns / before / limit). The runner's resume path reads via
+        // getState -> getTuple, so metadata filtering is not exercised here.
+        const where = [];
+        const args = [];
+        if (threadId !== undefined) {
+            where.push("thread_id = ?");
+            args.push(threadId);
+        }
+        if (checkpointNs !== undefined) {
+            where.push("checkpoint_ns = ?");
+            args.push(checkpointNs);
+        }
+        if (before !== undefined) {
+            where.push("checkpoint_id < ?");
+            args.push(before);
+        }
+        let sql = `SELECT thread_id, checkpoint_ns, checkpoint_id, parent_checkpoint_id, type, checkpoint, metadata
+       FROM checkpoints`;
+        if (where.length > 0)
+            sql += ` WHERE ${where.join(" AND ")}`;
+        sql += " ORDER BY checkpoint_id DESC";
+        if (limit !== undefined)
+            sql += ` LIMIT ${parseInt(String(limit), 10)}`;
+        const rows = this.db.prepare(sql).all(...args);
+        for (const row of rows) {
+            yield await this.rowToTuple(row);
+        }
+    }
+    async put(config, checkpoint, metadata, _newVersions) {
+        this.setup();
+        const threadId = config.configurable?.thread_id;
+        if (!threadId) {
+            throw new Error(`Missing "thread_id" field in passed "config.configurable".`);
+        }
+        const checkpointNs = config.configurable?.checkpoint_ns ?? "";
+        const parentCheckpointId = config.configurable?.checkpoint_id;
+        // Defensive copy before serialization, matching the reference saver.
+        const [[checkpointType, serializedCheckpoint], [metadataType, serializedMetadata]] = await Promise.all([
+            this.serde.dumpsTyped(copyCheckpoint(checkpoint)),
+            this.serde.dumpsTyped(metadata),
+        ]);
+        if (checkpointType !== metadataType) {
+            throw new Error("Failed to serialize checkpoint and metadata to the same type.");
+        }
+        this.db
+            .prepare(`INSERT OR REPLACE INTO checkpoints
+           (thread_id, checkpoint_ns, checkpoint_id, parent_checkpoint_id, type, checkpoint, metadata)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`)
+            .run(threadId, checkpointNs, checkpoint.id, parentCheckpointId ?? null, checkpointType, serializedCheckpoint, serializedMetadata);
+        return {
+            configurable: {
+                thread_id: threadId,
+                checkpoint_ns: checkpointNs,
+                checkpoint_id: checkpoint.id,
+            },
+        };
+    }
+    async putWrites(config, writes, taskId) {
+        this.setup();
+        const threadId = config.configurable?.thread_id;
+        if (!threadId)
+            throw new Error("Missing thread_id field in config.configurable.");
+        const checkpointId = config.configurable?.checkpoint_id;
+        if (!checkpointId)
+            throw new Error("Missing checkpoint_id field in config.configurable.");
+        const checkpointNs = config.configurable?.checkpoint_ns ?? "";
+        // Conflict resolution matches the reference saver and the
+        // langgraph-checkpoint contract:
+        // - All-special writes (ERROR / SCHEDULED / INTERRUPT / RESUME, each pinned
+        //   to a negative idx by WRITES_IDX_MAP) REPLACE, so e.g. INTERRUPT can be
+        //   overwritten by RESUME.
+        // - Otherwise IGNORE, so a regular write from one task never clobbers a
+        //   regular write another concurrent task already stored at the same
+        //   (task_id, idx).
+        const allSpecial = writes.every(([channel]) => channel in WRITES_IDX_MAP);
+        const stmt = this.db.prepare(`INSERT ${allSpecial ? "OR REPLACE" : "OR IGNORE"} INTO writes
+         (thread_id, checkpoint_ns, checkpoint_id, task_id, idx, channel, type, value)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+        const rows = await Promise.all(writes.map(async ([channel, value], idx) => {
+            const [type, serialized] = await this.serde.dumpsTyped(value);
+            return {
+                // Special channels are stored at fixed negative indices so they never
+                // collide with regular per-step writes (whose idx is the ordinal).
+                idx: WRITES_IDX_MAP[channel] ?? idx,
+                channel,
+                type,
+                value: serialized,
+            };
+        }));
+        this.db.exec("BEGIN");
+        try {
+            for (const row of rows) {
+                stmt.run(threadId, checkpointNs, checkpointId, taskId, row.idx, row.channel, row.type, row.value);
+            }
+            this.db.exec("COMMIT");
+        }
+        catch (err) {
+            this.db.exec("ROLLBACK");
+            throw err;
+        }
+    }
+    async deleteThread(threadId) {
+        this.setup();
+        this.db.exec("BEGIN");
+        try {
+            this.db.prepare("DELETE FROM checkpoints WHERE thread_id = ?").run(threadId);
+            this.db.prepare("DELETE FROM writes WHERE thread_id = ?").run(threadId);
+            this.db.exec("COMMIT");
+        }
+        catch (err) {
+            this.db.exec("ROLLBACK");
+            throw err;
+        }
+    }
+    /** Close the underlying database handle. Idempotent and non-throwing. */
+    close() {
+        try {
+            this.db.close();
+        }
+        catch {
+            /* already closed */
+        }
+    }
+    /** Deserialize a checkpoint row and hydrate its pending writes. */
+    async rowToTuple(row) {
+        const type = row.type ?? "json";
+        const checkpoint = (await this.serde.loadsTyped(type, row.checkpoint));
+        const metadata = (await this.serde.loadsTyped(type, row.metadata));
+        const pendingWrites = await this.loadPendingWrites(row.thread_id, row.checkpoint_ns, row.checkpoint_id);
+        return {
+            config: {
+                configurable: {
+                    thread_id: row.thread_id,
+                    checkpoint_ns: row.checkpoint_ns,
+                    checkpoint_id: row.checkpoint_id,
+                },
+            },
+            checkpoint,
+            metadata,
+            parentConfig: row.parent_checkpoint_id
+                ? {
+                    configurable: {
+                        thread_id: row.thread_id,
+                        checkpoint_ns: row.checkpoint_ns,
+                        checkpoint_id: row.parent_checkpoint_id,
+                    },
+                }
+                : undefined,
+            pendingWrites,
+        };
+    }
+    async loadPendingWrites(threadId, checkpointNs, checkpointId) {
+        const writeRows = this.db
+            .prepare(`SELECT task_id, channel, type, value
+         FROM writes
+         WHERE thread_id = ? AND checkpoint_ns = ? AND checkpoint_id = ?
+         ORDER BY task_id, idx`)
+            .all(threadId, checkpointNs, checkpointId);
+        return Promise.all(writeRows.map(async (w) => [
+            w.task_id,
+            w.channel,
+            await this.serde.loadsTyped(w.type ?? "json", w.value),
+        ]));
+    }
+}
+//# sourceMappingURL=sqlite-saver.js.map