@langchain/langgraph 1.3.7 → 1.4.0

package/dist/channels/delta.d.cts

@@ -0,0 +1,99 @@
+import { BaseChannel } from "./base.cjs";
+import { OverwriteValue } from "../constants.cjs";
+import { CheckpointPendingWrite, DeltaSnapshot } from "@langchain/langgraph-checkpoint";
+
+//#region src/channels/delta.d.ts
+/**
+ * A batch reducer for use with {@link DeltaChannel}.
+ *
+ * Receives the current accumulated value and a batch of writes in one call,
+ * returning the new accumulated value:
+ * `reducer(state, [write1, write2, ...]) -> newState`.
+ *
+ * Reducers must be deterministic and batching-invariant (associative across
+ * folds): applying two consecutive write batches separately must produce the
+ * same state as applying their concatenation once:
+ *
+ * ```text
+ * reducer(reducer(state, xs), ys) === reducer(state, xs.concat(ys))
+ * ```
+ *
+ * This lets LangGraph replay checkpointed writes in larger batches than they
+ * were originally produced without changing reconstructed state. If your
+ * reducer is not associative, use {@link BinaryOperatorAggregate} instead —
+ * `DeltaChannel` is not a drop-in replacement for every reducer.
+ */
+type DeltaReducer<ValueType, UpdateType = unknown> = (state: ValueType, writes: UpdateType[]) => ValueType;
+type OverwriteOrValue<ValueType, UpdateType> = OverwriteValue<ValueType> | UpdateType;
+/**
+ * Reducer channel that stores only a sentinel in checkpoint blobs and
+ * reconstructs state by replaying ancestor writes through the reducer.
+ *
+ * `DeltaChannel` avoids re-serializing the full accumulated value at every
+ * step. Instead of writing the value into `channel_values`, the channel is
+ * omitted entirely and its state is reconstructed on read by walking the
+ * ancestor chain and replaying the per-step writes through the reducer (see
+ * {@link BaseCheckpointSaver.getDeltaChannelHistory}).
+ *
+ * Snapshot cadence is driven by two counters: a per-channel update count and
+ * the total supersteps since the last snapshot. A full {@link DeltaSnapshot}
+ * blob is written when EITHER the update count reaches `snapshotFrequency` OR
+ * the supersteps count reaches the system-wide
+ * `DELTA_MAX_SUPERSTEPS_SINCE_SNAPSHOT` bound (default 5000), bounding replay
+ * depth even for channels that stop receiving writes.
+ *
+ * @remarks Beta. The API and on-disk representation may change in future
+ * releases. Threads written with `DeltaChannel` today are expected to remain
+ * readable, but the surrounding contract (`getDeltaChannelHistory`, the
+ * `DeltaSnapshot` blob shape, the `counters_since_delta_snapshot` metadata
+ * field) is not yet stable.
+ *
+ * @example
+ * ```typescript
+ * import { Annotation } from "@langchain/langgraph";
+ * import { DeltaChannel, messagesDeltaReducer } from "@langchain/langgraph";
+ *
+ * const State = Annotation.Root({
+ *   messages: Annotation<BaseMessage[]>({
+ *     reducer: () => [], // ignored; DeltaChannel is supplied below
+ *   }),
+ * });
+ * ```
+ */
+declare class DeltaChannel<ValueType = unknown, UpdateType = unknown> extends BaseChannel<ValueType, OverwriteOrValue<ValueType, UpdateType>, undefined> {
+  lc_graph_name: string;
+  /** `undefined` represents the Python `MISSING` sentinel (empty channel). */
+  value: ValueType | undefined;
+  reducer: DeltaReducer<ValueType, UpdateType>;
+  snapshotFrequency: number;
+  initialValueFactory: () => ValueType;
+  constructor(reducer: DeltaReducer<ValueType, UpdateType>, options?: {
+    snapshotFrequency?: number;
+    initialValueFactory?: () => ValueType;
+  });
+  fromCheckpoint(checkpoint?: undefined | DeltaSnapshot | ValueType): this;
+  /**
+   * Apply ancestor writes oldest-to-newest via a single reducer call.
+   *
+   * If any write is an Overwrite, the last one in the sequence acts as the
+   * reset point: its value becomes the new base and only writes after it are
+   * passed to the reducer.
+   */
+  replayWrites(writes: CheckpointPendingWrite[]): void;
+  update(values: OverwriteOrValue<ValueType, UpdateType>[]): boolean;
+  get(): ValueType;
+  /**
+   * Always returns `undefined` (the Python `MISSING` sentinel). Snapshot
+   * decisions live in `createCheckpoint`, which has the channel version and
+   * writes a {@link DeltaSnapshot} directly into `channel_values`. For
+   * non-snapshot steps the channel does not appear in `channel_values`;
+   * reconstruction walks ancestor writes via the saver's
+   * `getDeltaChannelHistory`.
+   */
+  checkpoint(): undefined;
+  isAvailable(): boolean;
+  equals(other: BaseChannel): boolean;
+}
+//#endregion
+export { DeltaChannel, DeltaReducer };
+//# sourceMappingURL=delta.d.cts.map

package/dist/channels/delta.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delta.d.cts","names":[],"sources":["../../src/channels/delta.ts"],"mappings":";;;;;;;AAiCA;;;;;;;;;;;;;;;;;AAGe;KAHH,YAAA,qCACV,KAAA,EAAO,SAAA,EACP,MAAA,EAAQ,UAAA,OACL,SAAA;AAAA,KAEA,gBAAA,0BACD,cAAA,CAAe,SAAA,IACf,UAAA;;;;;;;;;;;;;AA2CJ;;;;;;;;;;;;;;;;;;;;;;;cAAa,YAAA,oDAGH,WAAA,CACR,SAAA,EACA,gBAAA,CAAiB,SAAA,EAAW,UAAA;EAG5B,aAAA;EALmB;EAQnB,KAAA,EAAO,SAAA;EAEP,OAAA,EAAS,YAAA,CAAa,SAAA,EAAW,UAAA;EAEjC,iBAAA;EAEA,mBAAA,QAA2B,SAAA;EAE3B,WAAA,CACE,OAAA,EAAS,YAAA,CAAa,SAAA,EAAW,UAAA,GACjC,OAAA;IACE,iBAAA;IACA,mBAAA,SAA4B,SAAA;EAAA;EAiBzB,cAAA,CAAe,UAAA,eAAyB,aAAA,GAAgB,SAAA;EA7B/D;;;;;;;EAmDO,YAAA,CAAa,MAAA,EAAQ,sBAAA;EAqBrB,MAAA,CAAO,MAAA,EAAQ,gBAAA,CAAiB,SAAA,EAAW,UAAA;EAsC3C,GAAA,CAAA,GAAO,SAAA;EArGH;;;;;;;;EAoHJ,UAAA,CAAA;EAIP,WAAA,CAAA;EAIA,MAAA,CAAO,KAAA,EAAO,WAAA;AAAA"}

package/dist/channels/delta.d.ts

@@ -0,0 +1,99 @@
+import { BaseChannel } from "./base.js";
+import { OverwriteValue } from "../constants.js";
+import { CheckpointPendingWrite, DeltaSnapshot } from "@langchain/langgraph-checkpoint";
+
+//#region src/channels/delta.d.ts
+/**
+ * A batch reducer for use with {@link DeltaChannel}.
+ *
+ * Receives the current accumulated value and a batch of writes in one call,
+ * returning the new accumulated value:
+ * `reducer(state, [write1, write2, ...]) -> newState`.
+ *
+ * Reducers must be deterministic and batching-invariant (associative across
+ * folds): applying two consecutive write batches separately must produce the
+ * same state as applying their concatenation once:
+ *
+ * ```text
+ * reducer(reducer(state, xs), ys) === reducer(state, xs.concat(ys))
+ * ```
+ *
+ * This lets LangGraph replay checkpointed writes in larger batches than they
+ * were originally produced without changing reconstructed state. If your
+ * reducer is not associative, use {@link BinaryOperatorAggregate} instead —
+ * `DeltaChannel` is not a drop-in replacement for every reducer.
+ */
+type DeltaReducer<ValueType, UpdateType = unknown> = (state: ValueType, writes: UpdateType[]) => ValueType;
+type OverwriteOrValue<ValueType, UpdateType> = OverwriteValue<ValueType> | UpdateType;
+/**
+ * Reducer channel that stores only a sentinel in checkpoint blobs and
+ * reconstructs state by replaying ancestor writes through the reducer.
+ *
+ * `DeltaChannel` avoids re-serializing the full accumulated value at every
+ * step. Instead of writing the value into `channel_values`, the channel is
+ * omitted entirely and its state is reconstructed on read by walking the
+ * ancestor chain and replaying the per-step writes through the reducer (see
+ * {@link BaseCheckpointSaver.getDeltaChannelHistory}).
+ *
+ * Snapshot cadence is driven by two counters: a per-channel update count and
+ * the total supersteps since the last snapshot. A full {@link DeltaSnapshot}
+ * blob is written when EITHER the update count reaches `snapshotFrequency` OR
+ * the supersteps count reaches the system-wide
+ * `DELTA_MAX_SUPERSTEPS_SINCE_SNAPSHOT` bound (default 5000), bounding replay
+ * depth even for channels that stop receiving writes.
+ *
+ * @remarks Beta. The API and on-disk representation may change in future
+ * releases. Threads written with `DeltaChannel` today are expected to remain
+ * readable, but the surrounding contract (`getDeltaChannelHistory`, the
+ * `DeltaSnapshot` blob shape, the `counters_since_delta_snapshot` metadata
+ * field) is not yet stable.
+ *
+ * @example
+ * ```typescript
+ * import { Annotation } from "@langchain/langgraph";
+ * import { DeltaChannel, messagesDeltaReducer } from "@langchain/langgraph";
+ *
+ * const State = Annotation.Root({
+ *   messages: Annotation<BaseMessage[]>({
+ *     reducer: () => [], // ignored; DeltaChannel is supplied below
+ *   }),
+ * });
+ * ```
+ */
+declare class DeltaChannel<ValueType = unknown, UpdateType = unknown> extends BaseChannel<ValueType, OverwriteOrValue<ValueType, UpdateType>, undefined> {
+  lc_graph_name: string;
+  /** `undefined` represents the Python `MISSING` sentinel (empty channel). */
+  value: ValueType | undefined;
+  reducer: DeltaReducer<ValueType, UpdateType>;
+  snapshotFrequency: number;
+  initialValueFactory: () => ValueType;
+  constructor(reducer: DeltaReducer<ValueType, UpdateType>, options?: {
+    snapshotFrequency?: number;
+    initialValueFactory?: () => ValueType;
+  });
+  fromCheckpoint(checkpoint?: undefined | DeltaSnapshot | ValueType): this;
+  /**
+   * Apply ancestor writes oldest-to-newest via a single reducer call.
+   *
+   * If any write is an Overwrite, the last one in the sequence acts as the
+   * reset point: its value becomes the new base and only writes after it are
+   * passed to the reducer.
+   */
+  replayWrites(writes: CheckpointPendingWrite[]): void;
+  update(values: OverwriteOrValue<ValueType, UpdateType>[]): boolean;
+  get(): ValueType;
+  /**
+   * Always returns `undefined` (the Python `MISSING` sentinel). Snapshot
+   * decisions live in `createCheckpoint`, which has the channel version and
+   * writes a {@link DeltaSnapshot} directly into `channel_values`. For
+   * non-snapshot steps the channel does not appear in `channel_values`;
+   * reconstruction walks ancestor writes via the saver's
+   * `getDeltaChannelHistory`.
+   */
+  checkpoint(): undefined;
+  isAvailable(): boolean;
+  equals(other: BaseChannel): boolean;
+}
+//#endregion
+export { DeltaChannel, DeltaReducer };
+//# sourceMappingURL=delta.d.ts.map

package/dist/channels/delta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delta.d.ts","names":[],"sources":["../../src/channels/delta.ts"],"mappings":";;;;;;;AAiCA;;;;;;;;;;;;;;;;;AAGe;KAHH,YAAA,qCACV,KAAA,EAAO,SAAA,EACP,MAAA,EAAQ,UAAA,OACL,SAAA;AAAA,KAEA,gBAAA,0BACD,cAAA,CAAe,SAAA,IACf,UAAA;;;;;;;;;;;;;AA2CJ;;;;;;;;;;;;;;;;;;;;;;;cAAa,YAAA,oDAGH,WAAA,CACR,SAAA,EACA,gBAAA,CAAiB,SAAA,EAAW,UAAA;EAG5B,aAAA;EALmB;EAQnB,KAAA,EAAO,SAAA;EAEP,OAAA,EAAS,YAAA,CAAa,SAAA,EAAW,UAAA;EAEjC,iBAAA;EAEA,mBAAA,QAA2B,SAAA;EAE3B,WAAA,CACE,OAAA,EAAS,YAAA,CAAa,SAAA,EAAW,UAAA,GACjC,OAAA;IACE,iBAAA;IACA,mBAAA,SAA4B,SAAA;EAAA;EAiBzB,cAAA,CAAe,UAAA,eAAyB,aAAA,GAAgB,SAAA;EA7B/D;;;;;;;EAmDO,YAAA,CAAa,MAAA,EAAQ,sBAAA;EAqBrB,MAAA,CAAO,MAAA,EAAQ,gBAAA,CAAiB,SAAA,EAAW,UAAA;EAsC3C,GAAA,CAAA,GAAO,SAAA;EArGH;;;;;;;;EAoHJ,UAAA,CAAA;EAIP,WAAA,CAAA;EAIA,MAAA,CAAO,KAAA,EAAO,WAAA;AAAA"}

package/dist/channels/delta.js

@@ -0,0 +1,136 @@
+import { _getOverwriteValue, _isOverwriteValue } from "../constants.js";
+import { EmptyChannelError, InvalidUpdateError } from "../errors.js";
+import { BaseChannel } from "./base.js";
+import { isDeltaSnapshot } from "@langchain/langgraph-checkpoint";
+//#region src/channels/delta.ts
+const isDeltaChannel = (value) => {
+	return value != null && value.lc_graph_name === "DeltaChannel";
+};
+/**
+* Reducer channel that stores only a sentinel in checkpoint blobs and
+* reconstructs state by replaying ancestor writes through the reducer.
+*
+* `DeltaChannel` avoids re-serializing the full accumulated value at every
+* step. Instead of writing the value into `channel_values`, the channel is
+* omitted entirely and its state is reconstructed on read by walking the
+* ancestor chain and replaying the per-step writes through the reducer (see
+* {@link BaseCheckpointSaver.getDeltaChannelHistory}).
+*
+* Snapshot cadence is driven by two counters: a per-channel update count and
+* the total supersteps since the last snapshot. A full {@link DeltaSnapshot}
+* blob is written when EITHER the update count reaches `snapshotFrequency` OR
+* the supersteps count reaches the system-wide
+* `DELTA_MAX_SUPERSTEPS_SINCE_SNAPSHOT` bound (default 5000), bounding replay
+* depth even for channels that stop receiving writes.
+*
+* @remarks Beta. The API and on-disk representation may change in future
+* releases. Threads written with `DeltaChannel` today are expected to remain
+* readable, but the surrounding contract (`getDeltaChannelHistory`, the
+* `DeltaSnapshot` blob shape, the `counters_since_delta_snapshot` metadata
+* field) is not yet stable.
+*
+* @example
+* ```typescript
+* import { Annotation } from "@langchain/langgraph";
+* import { DeltaChannel, messagesDeltaReducer } from "@langchain/langgraph";
+*
+* const State = Annotation.Root({
+*   messages: Annotation<BaseMessage[]>({
+*     reducer: () => [], // ignored; DeltaChannel is supplied below
+*   }),
+* });
+* ```
+*/
+var DeltaChannel = class DeltaChannel extends BaseChannel {
+	lc_graph_name = "DeltaChannel";
+	/** `undefined` represents the Python `MISSING` sentinel (empty channel). */
+	value;
+	reducer;
+	snapshotFrequency;
+	initialValueFactory;
+	constructor(reducer, options) {
+		super();
+		const snapshotFrequency = options?.snapshotFrequency ?? 1e3;
+		if (!Number.isInteger(snapshotFrequency) || snapshotFrequency <= 0) throw new Error(`snapshotFrequency must be a positive integer, got ${snapshotFrequency}`);
+		this.reducer = reducer;
+		this.snapshotFrequency = snapshotFrequency;
+		this.initialValueFactory = options?.initialValueFactory ?? (() => []);
+		this.value = void 0;
+	}
+	fromCheckpoint(checkpoint) {
+		const empty = new DeltaChannel(this.reducer, {
+			snapshotFrequency: this.snapshotFrequency,
+			initialValueFactory: this.initialValueFactory
+		});
+		if (checkpoint === void 0) empty.value = this.initialValueFactory();
+		else if (isDeltaSnapshot(checkpoint)) empty.value = checkpoint.value;
+		else empty.value = checkpoint;
+		return empty;
+	}
+	/**
+	* Apply ancestor writes oldest-to-newest via a single reducer call.
+	*
+	* If any write is an Overwrite, the last one in the sequence acts as the
+	* reset point: its value becomes the new base and only writes after it are
+	* passed to the reducer.
+	*/
+	replayWrites(writes) {
+		const values = writes.map((w) => w[2]);
+		if (values.length === 0) return;
+		let base = this.value;
+		let start = 0;
+		for (let i = 0; i < values.length; i += 1) {
+			const [isOverwrite, overwriteValue] = _getOverwriteValue(values[i]);
+			if (isOverwrite) {
+				base = overwriteValue !== void 0 && overwriteValue !== null ? overwriteValue : this.initialValueFactory();
+				start = i + 1;
+			}
+		}
+		const remaining = values.slice(start);
+		this.value = remaining.length > 0 ? this.reducer(base, remaining) : base;
+	}
+	update(values) {
+		if (values.length === 0) return false;
+		let overwriteIdx;
+		for (let i = 0; i < values.length; i += 1) if (_isOverwriteValue(values[i])) {
+			if (overwriteIdx !== void 0) throw new InvalidUpdateError("Can receive only one Overwrite value per step.");
+			overwriteIdx = i;
+		}
+		if (overwriteIdx !== void 0) {
+			const [, overwriteValue] = _getOverwriteValue(values[overwriteIdx]);
+			const base = overwriteValue !== void 0 && overwriteValue !== null ? overwriteValue : this.initialValueFactory();
+			const remaining = values.slice(overwriteIdx + 1);
+			this.value = remaining.length > 0 ? this.reducer(base, remaining) : base;
+			return true;
+		}
+		const base = this.value === void 0 ? this.initialValueFactory() : this.value;
+		this.value = this.reducer(base, values);
+		return true;
+	}
+	get() {
+		if (this.value === void 0) throw new EmptyChannelError();
+		return this.value;
+	}
+	/**
+	* Always returns `undefined` (the Python `MISSING` sentinel). Snapshot
+	* decisions live in `createCheckpoint`, which has the channel version and
+	* writes a {@link DeltaSnapshot} directly into `channel_values`. For
+	* non-snapshot steps the channel does not appear in `channel_values`;
+	* reconstruction walks ancestor writes via the saver's
+	* `getDeltaChannelHistory`.
+	*/
+	checkpoint() {}
+	isAvailable() {
+		return this.value !== void 0;
+	}
+	equals(other) {
+		if (this === other) return true;
+		if (!isDeltaChannel(other)) return false;
+		if (this.snapshotFrequency !== other.snapshotFrequency) return false;
+		return this.reducer === other.reducer;
+	}
+};
+//#endregion
+export { DeltaChannel };
+
+//# sourceMappingURL=delta.js.map

package/dist/channels/delta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delta.js","names":[],"sources":["../../src/channels/delta.ts"],"sourcesContent":["import {\n  type CheckpointPendingWrite,\n  DeltaSnapshot,\n  isDeltaSnapshot,\n} from \"@langchain/langgraph-checkpoint\";\nimport {\n  _getOverwriteValue,\n  _isOverwriteValue,\n  type OverwriteValue,\n} from \"../constants.js\";\nimport { EmptyChannelError, InvalidUpdateError } from \"../errors.js\";\nimport { BaseChannel } from \"./base.js\";\n\n/**\n * A batch reducer for use with {@link DeltaChannel}.\n *\n * Receives the current accumulated value and a batch of writes in one call,\n * returning the new accumulated value:\n * `reducer(state, [write1, write2, ...]) -> newState`.\n *\n * Reducers must be deterministic and batching-invariant (associative across\n * folds): applying two consecutive write batches separately must produce the\n * same state as applying their concatenation once:\n *\n * ```text\n * reducer(reducer(state, xs), ys) === reducer(state, xs.concat(ys))\n * ```\n *\n * This lets LangGraph replay checkpointed writes in larger batches than they\n * were originally produced without changing reconstructed state. If your\n * reducer is not associative, use {@link BinaryOperatorAggregate} instead —\n * `DeltaChannel` is not a drop-in replacement for every reducer.\n */\nexport type DeltaReducer<ValueType, UpdateType = unknown> = (\n  state: ValueType,\n  writes: UpdateType[]\n) => ValueType;\n\ntype OverwriteOrValue<ValueType, UpdateType> =\n  | OverwriteValue<ValueType>\n  | UpdateType;\n\nconst isDeltaChannel = (\n  value: BaseChannel\n): value is DeltaChannel<unknown, unknown> => {\n  return value != null && value.lc_graph_name === \"DeltaChannel\";\n};\n\n/**\n * Reducer channel that stores only a sentinel in checkpoint blobs and\n * reconstructs state by replaying ancestor writes through the reducer.\n *\n * `DeltaChannel` avoids re-serializing the full accumulated value at every\n * step. Instead of writing the value into `channel_values`, the channel is\n * omitted entirely and its state is reconstructed on read by walking the\n * ancestor chain and replaying the per-step writes through the reducer (see\n * {@link BaseCheckpointSaver.getDeltaChannelHistory}).\n *\n * Snapshot cadence is driven by two counters: a per-channel update count and\n * the total supersteps since the last snapshot. A full {@link DeltaSnapshot}\n * blob is written when EITHER the update count reaches `snapshotFrequency` OR\n * the supersteps count reaches the system-wide\n * `DELTA_MAX_SUPERSTEPS_SINCE_SNAPSHOT` bound (default 5000), bounding replay\n * depth even for channels that stop receiving writes.\n *\n * @remarks Beta. The API and on-disk representation may change in future\n * releases. Threads written with `DeltaChannel` today are expected to remain\n * readable, but the surrounding contract (`getDeltaChannelHistory`, the\n * `DeltaSnapshot` blob shape, the `counters_since_delta_snapshot` metadata\n * field) is not yet stable.\n *\n * @example\n * ```typescript\n * import { Annotation } from \"@langchain/langgraph\";\n * import { DeltaChannel, messagesDeltaReducer } from \"@langchain/langgraph\";\n *\n * const State = Annotation.Root({\n *   messages: Annotation<BaseMessage[]>({\n *     reducer: () => [], // ignored; DeltaChannel is supplied below\n *   }),\n * });\n * ```\n */\nexport class DeltaChannel<\n  ValueType = unknown,\n  UpdateType = unknown,\n> extends BaseChannel<\n  ValueType,\n  OverwriteOrValue<ValueType, UpdateType>,\n  undefined\n> {\n  lc_graph_name = \"DeltaChannel\";\n\n  /** `undefined` represents the Python `MISSING` sentinel (empty channel). */\n  value: ValueType | undefined;\n\n  reducer: DeltaReducer<ValueType, UpdateType>;\n\n  snapshotFrequency: number;\n\n  initialValueFactory: () => ValueType;\n\n  constructor(\n    reducer: DeltaReducer<ValueType, UpdateType>,\n    options?: {\n      snapshotFrequency?: number;\n      initialValueFactory?: () => ValueType;\n    }\n  ) {\n    super();\n    const snapshotFrequency = options?.snapshotFrequency ?? 1000;\n    if (!Number.isInteger(snapshotFrequency) || snapshotFrequency <= 0) {\n      throw new Error(\n        `snapshotFrequency must be a positive integer, got ${snapshotFrequency}`\n      );\n    }\n    this.reducer = reducer;\n    this.snapshotFrequency = snapshotFrequency;\n    this.initialValueFactory =\n      options?.initialValueFactory ?? (() => [] as ValueType);\n    this.value = undefined;\n  }\n\n  public fromCheckpoint(checkpoint?: undefined | DeltaSnapshot | ValueType) {\n    const empty = new DeltaChannel<ValueType, UpdateType>(this.reducer, {\n      snapshotFrequency: this.snapshotFrequency,\n      initialValueFactory: this.initialValueFactory,\n    });\n    if (checkpoint === undefined) {\n      empty.value = this.initialValueFactory();\n    } else if (isDeltaSnapshot(checkpoint)) {\n      empty.value = checkpoint.value as ValueType;\n    } else {\n      empty.value = checkpoint as ValueType;\n    }\n    return empty as this;\n  }\n\n  /**\n   * Apply ancestor writes oldest-to-newest via a single reducer call.\n   *\n   * If any write is an Overwrite, the last one in the sequence acts as the\n   * reset point: its value becomes the new base and only writes after it are\n   * passed to the reducer.\n   */\n  public replayWrites(writes: CheckpointPendingWrite[]): void {\n    const values = writes.map((w) => w[2]);\n    if (values.length === 0) return;\n    let base = this.value as ValueType;\n    let start = 0;\n    for (let i = 0; i < values.length; i += 1) {\n      const [isOverwrite, overwriteValue] = _getOverwriteValue<ValueType>(\n        values[i]\n      );\n      if (isOverwrite) {\n        base =\n          overwriteValue !== undefined && overwriteValue !== null\n            ? overwriteValue\n            : this.initialValueFactory();\n        start = i + 1;\n      }\n    }\n    const remaining = values.slice(start) as UpdateType[];\n    this.value = remaining.length > 0 ? this.reducer(base, remaining) : base;\n  }\n\n  public update(values: OverwriteOrValue<ValueType, UpdateType>[]): boolean {\n    if (values.length === 0) return false;\n\n    let overwriteIdx: number | undefined;\n    for (let i = 0; i < values.length; i += 1) {\n      if (_isOverwriteValue<ValueType>(values[i])) {\n        if (overwriteIdx !== undefined) {\n          throw new InvalidUpdateError(\n            \"Can receive only one Overwrite value per step.\"\n          );\n        }\n        overwriteIdx = i;\n      }\n    }\n\n    if (overwriteIdx !== undefined) {\n      const [, overwriteValue] = _getOverwriteValue<ValueType>(\n        values[overwriteIdx]\n      );\n      const base =\n        overwriteValue !== undefined && overwriteValue !== null\n          ? overwriteValue\n          : this.initialValueFactory();\n      // Treat Overwrite as a hard reset: drop everything up to and including\n      // the overwrite, keeping only writes that follow it. This mirrors\n      // `replayWrites` so reconstruction from a checkpoint reproduces the live\n      // state even when a plain write precedes the Overwrite in the same step.\n      const remaining = values.slice(overwriteIdx + 1) as UpdateType[];\n      this.value = remaining.length > 0 ? this.reducer(base, remaining) : base;\n      return true;\n    }\n\n    const base =\n      this.value === undefined ? this.initialValueFactory() : this.value;\n    this.value = this.reducer(base, values as UpdateType[]);\n    return true;\n  }\n\n  public get(): ValueType {\n    if (this.value === undefined) {\n      throw new EmptyChannelError();\n    }\n    return this.value;\n  }\n\n  /**\n   * Always returns `undefined` (the Python `MISSING` sentinel). Snapshot\n   * decisions live in `createCheckpoint`, which has the channel version and\n   * writes a {@link DeltaSnapshot} directly into `channel_values`. For\n   * non-snapshot steps the channel does not appear in `channel_values`;\n   * reconstruction walks ancestor writes via the saver's\n   * `getDeltaChannelHistory`.\n   */\n  public checkpoint(): undefined {\n    return undefined;\n  }\n\n  isAvailable(): boolean {\n    return this.value !== undefined;\n  }\n\n  equals(other: BaseChannel): boolean {\n    if (this === other) return true;\n    if (!isDeltaChannel(other)) return false;\n    if (this.snapshotFrequency !== other.snapshotFrequency) return false;\n    return this.reducer === other.reducer;\n  }\n}\n"],"mappings":";;;;;AA0CA,MAAM,kBACJ,UAC4C;AAC5C,QAAO,SAAS,QAAQ,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsClD,IAAa,eAAb,MAAa,qBAGH,YAIR;CACA,gBAAgB;;CAGhB;CAEA;CAEA;CAEA;CAEA,YACE,SACA,SAIA;AACA,SAAO;EACP,MAAM,oBAAoB,SAAS,qBAAqB;AACxD,MAAI,CAAC,OAAO,UAAU,kBAAkB,IAAI,qBAAqB,EAC/D,OAAM,IAAI,MACR,qDAAqD,oBACtD;AAEH,OAAK,UAAU;AACf,OAAK,oBAAoB;AACzB,OAAK,sBACH,SAAS,8BAA8B,EAAE;AAC3C,OAAK,QAAQ,KAAA;;CAGf,eAAsB,YAAoD;EACxE,MAAM,QAAQ,IAAI,aAAoC,KAAK,SAAS;GAClE,mBAAmB,KAAK;GACxB,qBAAqB,KAAK;GAC3B,CAAC;AACF,MAAI,eAAe,KAAA,EACjB,OAAM,QAAQ,KAAK,qBAAqB;WAC/B,gBAAgB,WAAW,CACpC,OAAM,QAAQ,WAAW;MAEzB,OAAM,QAAQ;AAEhB,SAAO;;;;;;;;;CAUT,aAAoB,QAAwC;EAC1D,MAAM,SAAS,OAAO,KAAK,MAAM,EAAE,GAAG;AACtC,MAAI,OAAO,WAAW,EAAG;EACzB,IAAI,OAAO,KAAK;EAChB,IAAI,QAAQ;AACZ,OAAK,IAAI,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAK,GAAG;GACzC,MAAM,CAAC,aAAa,kBAAkB,mBACpC,OAAO,GACR;AACD,OAAI,aAAa;AACf,WACE,mBAAmB,KAAA,KAAa,mBAAmB,OAC/C,iBACA,KAAK,qBAAqB;AAChC,YAAQ,IAAI;;;EAGhB,MAAM,YAAY,OAAO,MAAM,MAAM;AACrC,OAAK,QAAQ,UAAU,SAAS,IAAI,KAAK,QAAQ,MAAM,UAAU,GAAG;;CAGtE,OAAc,QAA4D;AACxE,MAAI,OAAO,WAAW,EAAG,QAAO;EAEhC,IAAI;AACJ,OAAK,IAAI,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAK,EACtC,KAAI,kBAA6B,OAAO,GAAG,EAAE;AAC3C,OAAI,iBAAiB,KAAA,EACnB,OAAM,IAAI,mBACR,iDACD;AAEH,kBAAe;;AAInB,MAAI,iBAAiB,KAAA,GAAW;GAC9B,MAAM,GAAG,kBAAkB,mBACzB,OAAO,cACR;GACD,MAAM,OACJ,mBAAmB,KAAA,KAAa,mBAAmB,OAC/C,iBACA,KAAK,qBAAqB;GAKhC,MAAM,YAAY,OAAO,MAAM,eAAe,EAAE;AAChD,QAAK,QAAQ,UAAU,SAAS,IAAI,KAAK,QAAQ,MAAM,UAAU,GAAG;AACpE,UAAO;;EAGT,MAAM,OACJ,KAAK,UAAU,KAAA,IAAY,KAAK,qBAAqB,GAAG,KAAK;AAC/D,OAAK,QAAQ,KAAK,QAAQ,MAAM,OAAuB;AACvD,SAAO;;CAGT,MAAwB;AACtB,MAAI,KAAK,UAAU,KAAA,EACjB,OAAM,IAAI,mBAAmB;AAE/B,SAAO,KAAK;;;;;;;;;;CAWd,aAA+B;CAI/B,cAAuB;AACrB,SAAO,KAAK,UAAU,KAAA;;CAGxB,OAAO,OAA6B;AAClC,MAAI,SAAS,MAAO,QAAO;AAC3B,MAAI,CAAC,eAAe,MAAM,CAAE,QAAO;AACnC,MAAI,KAAK,sBAAsB,MAAM,kBAAmB,QAAO;AAC/D,SAAO,KAAK,YAAY,MAAM"}

package/dist/channels/index.cjs

@@ -5,12 +5,14 @@ const require_last_value = require("./last_value.cjs");
 const require_topic = require("./topic.cjs");
 const require_ephemeral_value = require("./ephemeral_value.cjs");
 const require_named_barrier_value = require("./named_barrier_value.cjs");
+const require_delta = require("./delta.cjs");
 const require_any_value = require("./any_value.cjs");
 const require_dynamic_barrier_value = require("./dynamic_barrier_value.cjs");
 const require_untracked_value = require("./untracked_value.cjs");
 exports.AnyValue = require_any_value.AnyValue;
 exports.BaseChannel = require_base.BaseChannel;
 exports.BinaryOperatorAggregate = require_binop.BinaryOperatorAggregate;
+exports.DeltaChannel = require_delta.DeltaChannel;
 exports.DynamicBarrierValue = require_dynamic_barrier_value.DynamicBarrierValue;
 exports.EphemeralValue = require_ephemeral_value.EphemeralValue;
 exports.LastValue = require_last_value.LastValue;
@@ -19,5 +21,8 @@ exports.NamedBarrierValue = require_named_barrier_value.NamedBarrierValue;
 exports.NamedBarrierValueAfterFinish = require_named_barrier_value.NamedBarrierValueAfterFinish;
 exports.Topic = require_topic.Topic;
 exports.UntrackedValueChannel = require_untracked_value.UntrackedValueChannel;
+exports.channelsFromCheckpoint = require_base.channelsFromCheckpoint;
 exports.createCheckpoint = require_base.createCheckpoint;
+exports.deltaChannelsToSnapshot = require_base.deltaChannelsToSnapshot;
 exports.empty = require_base.emptyChannels;
+exports.isDeltaChannel = require_base.isDeltaChannel;

package/dist/channels/index.d.cts

@@ -1,4 +1,5 @@
-import { BaseChannel, createCheckpoint, emptyChannels } from "./base.cjs";
+import { BaseChannel, channelsFromCheckpoint, createCheckpoint, deltaChannelsToSnapshot, emptyChannels, isDeltaChannel } from "./base.cjs";
+import { DeltaChannel, DeltaReducer } from "./delta.cjs";
 import { BinaryOperator, BinaryOperatorAggregate } from "./binop.cjs";
 import { AnyValue } from "./any_value.cjs";
 import { LastValue, LastValueAfterFinish } from "./last_value.cjs";
@@ -7,4 +8,4 @@ import { EphemeralValue } from "./ephemeral_value.cjs";
 import { NamedBarrierValue, NamedBarrierValueAfterFinish } from "./named_barrier_value.cjs";
 import { Topic } from "./topic.cjs";
 import { UntrackedValueChannel } from "./untracked_value.cjs";
-export { AnyValue, BaseChannel, type BinaryOperator, BinaryOperatorAggregate, DynamicBarrierValue, EphemeralValue, LastValue, LastValueAfterFinish, NamedBarrierValue, NamedBarrierValueAfterFinish, Topic, UntrackedValueChannel, type WaitForNames, createCheckpoint, emptyChannels as empty };
+export { AnyValue, BaseChannel, type BinaryOperator, BinaryOperatorAggregate, DeltaChannel, type DeltaReducer, DynamicBarrierValue, EphemeralValue, LastValue, LastValueAfterFinish, NamedBarrierValue, NamedBarrierValueAfterFinish, Topic, UntrackedValueChannel, type WaitForNames, channelsFromCheckpoint, createCheckpoint, deltaChannelsToSnapshot, emptyChannels as empty, isDeltaChannel };

package/dist/channels/index.d.ts

@@ -1,4 +1,5 @@
-import { BaseChannel, createCheckpoint, emptyChannels } from "./base.js";
+import { BaseChannel, channelsFromCheckpoint, createCheckpoint, deltaChannelsToSnapshot, emptyChannels, isDeltaChannel } from "./base.js";
+import { DeltaChannel, DeltaReducer } from "./delta.js";
 import { BinaryOperator, BinaryOperatorAggregate } from "./binop.js";
 import { AnyValue } from "./any_value.js";
 import { LastValue, LastValueAfterFinish } from "./last_value.js";
@@ -7,4 +8,4 @@ import { EphemeralValue } from "./ephemeral_value.js";
 import { NamedBarrierValue, NamedBarrierValueAfterFinish } from "./named_barrier_value.js";
 import { Topic } from "./topic.js";
 import { UntrackedValueChannel } from "./untracked_value.js";
-export { AnyValue, BaseChannel, type BinaryOperator, BinaryOperatorAggregate, DynamicBarrierValue, EphemeralValue, LastValue, LastValueAfterFinish, NamedBarrierValue, NamedBarrierValueAfterFinish, Topic, UntrackedValueChannel, type WaitForNames, createCheckpoint, emptyChannels as empty };
+export { AnyValue, BaseChannel, type BinaryOperator, BinaryOperatorAggregate, DeltaChannel, type DeltaReducer, DynamicBarrierValue, EphemeralValue, LastValue, LastValueAfterFinish, NamedBarrierValue, NamedBarrierValueAfterFinish, Topic, UntrackedValueChannel, type WaitForNames, channelsFromCheckpoint, createCheckpoint, deltaChannelsToSnapshot, emptyChannels as empty, isDeltaChannel };

package/dist/channels/index.js

@@ -1,10 +1,11 @@
-import { BaseChannel, createCheckpoint, emptyChannels } from "./base.js";
+import { BaseChannel, channelsFromCheckpoint, createCheckpoint, deltaChannelsToSnapshot, emptyChannels, isDeltaChannel } from "./base.js";
 import { BinaryOperatorAggregate } from "./binop.js";
 import { LastValue, LastValueAfterFinish } from "./last_value.js";
 import { Topic } from "./topic.js";
 import { EphemeralValue } from "./ephemeral_value.js";
 import { NamedBarrierValue, NamedBarrierValueAfterFinish } from "./named_barrier_value.js";
+import { DeltaChannel } from "./delta.js";
 import { AnyValue } from "./any_value.js";
 import { DynamicBarrierValue } from "./dynamic_barrier_value.js";
 import { UntrackedValueChannel } from "./untracked_value.js";
-export { AnyValue, BaseChannel, BinaryOperatorAggregate, DynamicBarrierValue, EphemeralValue, LastValue, LastValueAfterFinish, NamedBarrierValue, NamedBarrierValueAfterFinish, Topic, UntrackedValueChannel, createCheckpoint, emptyChannels as empty };
+export { AnyValue, BaseChannel, BinaryOperatorAggregate, DeltaChannel, DynamicBarrierValue, EphemeralValue, LastValue, LastValueAfterFinish, NamedBarrierValue, NamedBarrierValueAfterFinish, Topic, UntrackedValueChannel, channelsFromCheckpoint, createCheckpoint, deltaChannelsToSnapshot, emptyChannels as empty, isDeltaChannel };

package/dist/constants.cjs

@@ -1,3 +1,4 @@
+const require_timeout = require("./pregel/utils/timeout.cjs");
 //#region src/constants.ts
 /** Special reserved node name denoting the start of a graph. */
 const START = "__start__";
@@ -6,8 +7,36 @@ const END = "__end__";
 const INPUT = "__input__";
 const COPY = "__copy__";
 const ERROR = "__error__";
+/**
+* Special reserved write key recording the name of the node whose execution
+* failed, so node-level error handlers see the same failure provenance after a
+* checkpoint resume. Value format in pending writes:
+* `[taskId, ERROR_SOURCE_NODE, nodeName: string]`.
+*/
+const ERROR_SOURCE_NODE = "__error_source_node__";
 /** Special reserved cache namespaces */
 const CACHE_NS_WRITES = "__pregel_ns_writes";
+/**
+* System-wide upper bound on how many supersteps a {@link DeltaChannel} may go
+* without writing a {@link DeltaSnapshot} blob. Once a channel's
+* supersteps-since-snapshot counter reaches this value, a snapshot is forced
+* even if the channel's own `snapshotFrequency` has not been reached — this
+* prevents unbounded ancestor walks on threads where a delta channel exists
+* but is no longer being updated.
+*
+* Overridable via the `LANGGRAPH_DELTA_MAX_SUPERSTEPS_SINCE_SNAPSHOT`
+* environment variable. Read lazily so test/runtime overrides take effect.
+*
+* @remarks Beta.
+*/
+function getDeltaMaxSuperstepsSinceSnapshot() {
+	const raw = typeof process !== "undefined" ? process.env?.LANGGRAPH_DELTA_MAX_SUPERSTEPS_SINCE_SNAPSHOT : void 0;
+	if (raw !== void 0 && raw !== "") {
+		const parsed = Number.parseInt(raw, 10);
+		if (Number.isFinite(parsed) && parsed > 0) return parsed;
+	}
+	return 5e3;
+}
 const CONFIG_KEY_SEND = "__pregel_send";
 /** config key containing function used to call a node (push task) */
 const CONFIG_KEY_CALL = "__pregel_call";
@@ -25,7 +54,14 @@ const CONFIG_KEY_DURABILITY = "__pregel_durability";
 const CONFIG_KEY_CHECKPOINT_ID = "checkpoint_id";
 const CONFIG_KEY_CHECKPOINT_NS = "checkpoint_ns";
 const CONFIG_KEY_NODE_FINISHED = "__pregel_node_finished";
+/**
+* Config key holding a {@link NodeError} (failed source node + error) for the
+* current node-level error handler invocation. Injected when an error handler
+* task is prepared after the failing node's retry policy is exhausted.
+*/
+const CONFIG_KEY_NODE_ERROR = "__pregel_node_error";
 const CONFIG_KEY_CHECKPOINT_MAP = "checkpoint_map";
+const CONFIG_KEY_REPLAY_STATE = "__pregel_replay_state";
 const CONFIG_KEY_ABORT_SIGNALS = "__pregel_abort_signals";
 /** Special channel reserved for graph interrupts */
 const INTERRUPT = "__interrupt__";
@@ -50,6 +86,7 @@ const RESERVED = [
 	INTERRUPT,
 	RESUME,
 	ERROR,
+	ERROR_SOURCE_NODE,
 	NO_WRITES,
 	CONFIG_KEY_SEND,
 	CONFIG_KEY_READ,
@@ -64,7 +101,8 @@ const RESERVED = [
 	CONFIG_KEY_PREVIOUS_STATE,
 	CONFIG_KEY_CHECKPOINT_MAP,
 	CONFIG_KEY_CHECKPOINT_NS,
-	CONFIG_KEY_CHECKPOINT_ID
+	CONFIG_KEY_CHECKPOINT_ID,
+	CONFIG_KEY_REPLAY_STATE
 ];
 /**
 * Symbol used internally to identify Command instances.
@@ -122,6 +160,14 @@ function _isSendInterface(x) {
 *   });
 * };
 *
+* @remarks
+* A per-task timeout can be supplied via the third argument's `timeout` option
+* to override the target node's configured timeout for this specific pushed task:
+*
+* ```typescript
+* new Send("generate_joke", { subjects: [subject] }, { timeout: { idleTimeout: 5000 } });
+* ```
+*
 * const graph = new StateGraph(ChainState)
 *   .addNode("generate_joke", (state) => ({
 *     jokes: [`Joke about ${state.subjects}`],
@@ -141,15 +187,23 @@ var Send = class {
 	lg_name = "Send";
 	node;
 	args;
-	constructor(node, args) {
+	/**
+	* Optional per-task timeout policy that overrides the target node's timeout
+	* for this specific pushed task. A bare number is treated as a hard
+	* `runTimeout` (in milliseconds).
+	*/
+	timeout;
+	constructor(node, args, options) {
 		this.node = node;
 		this.args = _deserializeCommandSendObjectGraph(args);
+		this.timeout = require_timeout.coerceTimeoutPolicy(options?.timeout);
 	}
 	toJSON() {
 		return {
 			lg_name: this.lg_name,
 			node: this.node,
-			args: this.args
+			args: this.args,
+			timeout: this.timeout
 		};
 	}
 };
@@ -423,7 +477,7 @@ function _deserializeCommandSendObjectGraph(x, seen = /* @__PURE__ */ new Map())
 			result = new Command(x);
 			seen.set(x, result);
 		} else if (_isSendInterface(x)) {
-			result = new Send(x.node, x.args);
+			result = new Send(x.node, x.args, x.timeout !== void 0 ? { timeout: x.timeout } : void 0);
 			seen.set(x, result);
 		} else if ("lc_serializable" in x && x.lc_serializable) {
 			result = x;
@@ -447,9 +501,11 @@ exports.CONFIG_KEY_CHECKPOINT_ID = CONFIG_KEY_CHECKPOINT_ID;
 exports.CONFIG_KEY_CHECKPOINT_MAP = CONFIG_KEY_CHECKPOINT_MAP;
 exports.CONFIG_KEY_CHECKPOINT_NS = CONFIG_KEY_CHECKPOINT_NS;
 exports.CONFIG_KEY_DURABILITY = CONFIG_KEY_DURABILITY;
+exports.CONFIG_KEY_NODE_ERROR = CONFIG_KEY_NODE_ERROR;
 exports.CONFIG_KEY_NODE_FINISHED = CONFIG_KEY_NODE_FINISHED;
 exports.CONFIG_KEY_PREVIOUS_STATE = CONFIG_KEY_PREVIOUS_STATE;
 exports.CONFIG_KEY_READ = CONFIG_KEY_READ;
+exports.CONFIG_KEY_REPLAY_STATE = CONFIG_KEY_REPLAY_STATE;
 exports.CONFIG_KEY_RESUME_MAP = CONFIG_KEY_RESUME_MAP;
 exports.CONFIG_KEY_RESUMING = CONFIG_KEY_RESUMING;
 exports.CONFIG_KEY_SCRATCHPAD = CONFIG_KEY_SCRATCHPAD;
@@ -461,6 +517,7 @@ exports.Command = Command;
 exports.CommandInstance = CommandInstance;
 exports.END = END;
 exports.ERROR = ERROR;
+exports.ERROR_SOURCE_NODE = ERROR_SOURCE_NODE;
 exports.INPUT = INPUT;
 exports.INTERRUPT = INTERRUPT;
 exports.NO_WRITES = NO_WRITES;
@@ -482,6 +539,7 @@ exports._getOverwriteValue = _getOverwriteValue;
 exports._isOverwriteValue = _isOverwriteValue;
 exports._isSend = _isSend;
 exports._isSendInterface = _isSendInterface;
+exports.getDeltaMaxSuperstepsSinceSnapshot = getDeltaMaxSuperstepsSinceSnapshot;
 exports.isCommand = isCommand;
 exports.isInterrupted = isInterrupted;