Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@langchain/langgraph-checkpoint-redis": patch
---

fix: `RedisSaver.putWrites` now honors `WRITES_IDX_MAP`, pinning special channels (`__error__`, `__scheduled__`, `__interrupt__`, `__resume__`) to fixed negative indices in their Redis key (`checkpoint_write:…:<idx>`) instead of the call-local ordinal. Previously a mixed `putWrites([[…regular…], [INTERRUPT, …]], taskId)` placed the INTERRUPT key at the positive idx of its position in the batch, where a peer task's regular write at the same idx would overwrite it via the unconditional `JSON.SET`. The conflict-resolution clause now matches Postgres / SQLite / MongoDB: unguarded `JSON.SET` when every write is a special channel, `JSON.SET … NX` (insert-or-ignore) otherwise.
32 changes: 29 additions & 3 deletions libs/checkpoint-redis/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ import {
PendingWrite,
uuid6,
TASKS,
WRITES_IDX_MAP,
maxChannelVersion,
copyCheckpoint,
} from "@langchain/langgraph-checkpoint";
Expand Down Expand Up @@ -667,26 +668,51 @@ export class RedisSaver extends BaseCheckpointSaver {
// Use high-resolution timestamp to ensure unique ordering across putWrites calls
const baseTimestamp = performance.now() * 1000; // Microsecond precision

// Conflict resolution matches the Python checkpointer contract and the
// sibling TS implementations (Memory, Postgres, SQLite #2516, MongoDB):
// - When every write targets a special channel (ERROR / SCHEDULED /
// INTERRUPT / RESUME, each pinned to a negative `idx` by
// WRITES_IDX_MAP), the write OVERWRITES any existing row so e.g.
// INTERRUPT can be overwritten on RESUME.
// - Otherwise it's an insert-or-ignore so a regular write from one
// task can never silently clobber a regular write that another
// concurrent task already stored at the same (task_id, idx).
const allSpecial = writes.every(([channel]) => channel in WRITES_IDX_MAP);

// Store each write as a separate indexed JSON document
for (let idx = 0; idx < writes.length; idx++) {
const [channel, value] = writes[idx];
const writeKey = `checkpoint_write:${threadId}:${checkpointNs}:${checkpointId}:${taskId}:${idx}`;
// Special channels are stored at fixed negative indices so they
// never collide with regular per-step writes (whose `idx` is the
// ordinal within `writes`).
const writeIdx = WRITES_IDX_MAP[channel] ?? idx;
const writeKey = `checkpoint_write:${threadId}:${checkpointNs}:${checkpointId}:${taskId}:${writeIdx}`;
writeKeys.push(writeKey);

const writeDoc = {
thread_id: threadId,
checkpoint_ns: checkpointNs,
checkpoint_id: checkpointId,
task_id: taskId,
idx: idx,
idx: writeIdx,
channel: channel,
type: typeof value === "object" ? "json" : "string",
value: value,
timestamp: baseTimestamp,
global_idx: baseTimestamp + idx, // Add microseconds for sub-millisecond ordering
};

await this.client.json.set(writeKey, "$", writeDoc as any);
if (allSpecial) {
await this.client.json.set(writeKey, "$", writeDoc as never);
} else {
// Equivalent of SQL `INSERT OR IGNORE`: only set when the key is
// absent. `node-redis` exposes this as the `NX` modifier on
// `JSON.SET`. The return value is the string "OK" on insert and
// `null` on no-op, both of which are fine to discard here.
await this.client.json.set(writeKey, "$", writeDoc as never, {
NX: true,
});
}
}

// Register write keys in sorted set for efficient retrieval
Expand Down
97 changes: 97 additions & 0 deletions libs/checkpoint-redis/src/tests/putWrites.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
import { describe, it, expect } from "vitest";
import { RedisSaver } from "../index.js";

// `RedisSaver.putWrites` stores one JSON document per write under a key shaped
// `checkpoint_write:<thread>:<ns>:<ckpt>:<task>:<idx>`. The two things this
// suite needs to assert are:
// 1. special channels (ERROR / SCHEDULED / INTERRUPT / RESUME) are written
// to fixed negative `idx`es from WRITES_IDX_MAP, not the ordinal in the
// call — otherwise they collide with regular per-step writes.
// 2. the conflict-resolution clause matches the contract: `$set`-style
// overwrite when every write is a special channel, NX (insert-or-ignore)
// otherwise.
// Both are observable from the `json.set` call sites without standing up
// real Redis.
const makeMockClient = () => {
const jsonSetCalls: Array<{
key: string;
path: string;
value: unknown;
options?: { NX?: boolean; XX?: boolean };
}> = [];
const client = {
exists: async () => 0,
keys: async () => [],
json: {
set: async (
key: string,
path: string,
value: unknown,
options?: { NX?: boolean; XX?: boolean }
) => {
jsonSetCalls.push({ key, path, value, options });
return "OK";
},
get: async () => null,
},
zAdd: async () => 0,
ft: { info: async () => ({}) },
} as never;
return { client, jsonSetCalls };
};

describe("RedisSaver.putWrites — WRITES_IDX_MAP", () => {
const config = {
configurable: {
thread_id: "t",
checkpoint_ns: "",
checkpoint_id: "c",
},
};

it("uses fixed negative indices for special channels mixed with regular writes, and NX-guards the inserts", async () => {
const { client, jsonSetCalls } = makeMockClient();
const saver = new RedisSaver(client);

await saver.putWrites(
config,
[
["foo", "v_foo"],
["bar", "v_bar"],
["__interrupt__", "paused"],
],
"task_A"
);

// Only the write-doc json.set calls — drop the trailing checkpoint
// has_writes marker by filtering on the key prefix.
const writeSets = jsonSetCalls.filter((c) =>
c.key.startsWith("checkpoint_write:")
);

const tails = writeSets.map((c) => c.key.split(":").pop());
// foo (idx 0), bar (idx 1), __interrupt__ (idx -3 via WRITES_IDX_MAP)
expect(tails.sort()).toEqual(["-3", "0", "1"].sort());

// Mixed batch → every JSON.SET must carry NX so a peer task's existing
// row at the same (task_id, idx) doesn't get clobbered.
for (const c of writeSets) {
expect(c.options).toMatchObject({ NX: true });
}
});

it("uses unguarded JSON.SET when every write is a special channel (INTERRUPT → RESUME state transitions must overwrite)", async () => {
const { client, jsonSetCalls } = makeMockClient();
const saver = new RedisSaver(client);

await saver.putWrites(config, [["__resume__", "carry_on"]], "task_A");

const writeSets = jsonSetCalls.filter((c) =>
c.key.startsWith("checkpoint_write:")
);
expect(writeSets).toHaveLength(1);
expect(writeSets[0].key.endsWith(":-4")).toBe(true); // RESUME → idx -4
// No NX option, so it overwrites whatever was there before.
expect(writeSets[0].options ?? {}).not.toHaveProperty("NX");
});
});
Loading