@langchain/langgraph 1.4.21 → 1.5.1

package/dist/pregel/loop.js

@@ -1,40 +1,116 @@
-import { CONFIG_KEY_CHECKPOINT_ID, CONFIG_KEY_CHECKPOINT_MAP, CONFIG_KEY_CHECKPOINT_NS, CONFIG_KEY_READ, CONFIG_KEY_REPLAY_STATE, CONFIG_KEY_RESUME_MAP, CONFIG_KEY_RESUMING, CONFIG_KEY_SCRATCHPAD, CONFIG_KEY_STREAM, ERROR, INPUT, INTERRUPT, NULL_TASK_ID, PUSH, RESUME, _isOverwriteValue, _isSend, isCommand } from "../constants.js";
+import { CONFIG_KEY_CHECKPOINT_ID, CONFIG_KEY_CHECKPOINT_MAP, CONFIG_KEY_CHECKPOINT_NS, CONFIG_KEY_READ, CONFIG_KEY_REPLAY_STATE, CONFIG_KEY_RESUME_MAP, CONFIG_KEY_RESUMING, CONFIG_KEY_SCRATCHPAD, CONFIG_KEY_STREAM, ERROR, INPUT, INTERRUPT, NULL_TASK_ID, Overwrite, PUSH, RESUME, _getOverwriteValue, _isOverwriteValue, _isSend, isCommand } from "../constants.js";
 import { EmptyInputError, GraphInterrupt, isGraphInterrupt } from "../errors.js";
-import { DELTA_WRITES_VERSIONED, channelsFromCheckpoint, createCheckpoint, deltaChannelsToSnapshot, exitDeltaTaskId, isDeltaChannel, isDeltaWritesVersioned } from "../channels/base.js";
+import { DELTA_WRITES_VERSIONED, channelsFromCheckpoint, createCheckpoint, deltaChannelWrites, deltaChannelsToSnapshot, deltaChannelsWithPendingWrites, exitDeltaLateTaskId, exitDeltaTaskId, isDeltaChannel, isDeltaWritesVersioned } from "../channels/base.js";
 import { gatherIterator, gatherIteratorSync, prefixGenerator } from "../utils.js";
+import { advanceDeltaCounters, checkpointSuperseded } from "./checkpoint.js";
 import { isXXH3 } from "../hash.js";
 import { mapCommand, mapInput, mapOutputUpdates, mapOutputValues, readChannels } from "./io.js";
 import { getNewChannelVersions, patchConfigurable } from "./utils/index.js";
-import { _applyWrites, _prepareNextTasks, _prepareNodeErrorHandlerTask, _prepareSingleTask, increment, sanitizeUntrackedValuesInSend, shouldInterrupt } from "./algo.js";
+import { _applyWrites, _prepareNextTasks, _prepareNodeErrorHandlerTask, _prepareSingleTask, increment, sanitizeUntrackedValuesInSend, shouldInterrupt, taskPathStr } from "./algo.js";
 import { mapDebugCheckpoint, mapDebugTaskResults, mapDebugTasks, printStepTasks } from "./debug.js";
+import { isMessagesDeltaReducer } from "../graph/messages_reducer.js";
 import { ReplayState } from "./replay.js";
 import { createDuplexStream } from "./stream.js";
-import { AsyncBatchedStore, BaseCache, WRITES_IDX_MAP, copyCheckpoint, emptyCheckpoint } from "@langchain/langgraph-checkpoint";
+import { AsyncBatchedStore, BaseCache, WRITES_IDX_MAP, copyCheckpoint, emptyCheckpoint, uuid5 } from "@langchain/langgraph-checkpoint";
 import { v4 } from "@langchain/core/utils/uuid";
-import { BaseMessage } from "@langchain/core/messages";
+import { BaseMessage, coerceMessageLikeToMessage } from "@langchain/core/messages";
 //#region src/pregel/loop.ts
 const INPUT_DONE = Symbol.for("INPUT_DONE");
 const INPUT_RESUMING = Symbol.for("INPUT_RESUMING");
 const DEFAULT_LOOP_LIMIT = 25;
 /**
-* Recursively assign a stable UUID to any {@link BaseMessage} (in a value, an
-* array, or an object's values) that is missing an `id`. Used so DeltaChannel
-* writes — replayed on every read — reconstruct identical message identities.
+* Give the messages written to DeltaChannels stable ids, and return the writes
+* in `writes` that go to a DeltaChannel.
+*
+* A DeltaChannel replays its saved writes on every read, and its reducer may
+* not assign missing ids (`messagesDeltaReducer` doesn't), so a message saved
+* without an id comes back without one, or with a new one on every read, and
+* nothing can target it by id, for example `RemoveMessage`.
+*
+* In a channel whose reducer is {@link messagesDeltaReducer}, every
+* message-like it accepts (a message, a plain object, a string, a
+* `[role, content]` pair; alone, in an array or in an `Overwrite`) gets an id.
+* A plain message object stays plain, with the id on a copy, except in an
+* `Overwrite`, whose value the channel keeps as it is, so there it becomes a
+* message. Other DeltaChannels may hold other data, so there only message
+* objects get ids. Anything that can't become a message is left as it is, so
+* it fails where it always has, when the reducer reads it.
+*
+* A write that changes is replaced in `writes` by a new `[channel, value]`
+* pair: arrays and pairs the caller passed in are never changed, only the ids
+* of message objects.
 */
-function ensureMessageIds(value) {
-	if (value == null || typeof value !== "object") return;
+function ensureDeltaMessageIds(channels, writes) {
+	const deltaWrites = [];
+	for (let i = 0; i < writes.length; i += 1) {
+		const [channelName, value] = writes[i];
+		const channel = channels[String(channelName)];
+		if (!isDeltaChannel(channel)) continue;
+		if (isMessagesDeltaReducer(channel.reducer)) {
+			const newValue = withMessageIds(value);
+			if (newValue !== value) writes[i] = [channelName, newValue];
+		} else stampMessageIds(value);
+		deltaWrites.push(writes[i]);
+	}
+	return deltaWrites;
+}
+function withMessageIds(value) {
+	const [isOverwrite, overwriteValue] = _getOverwriteValue(value);
+	if (!isOverwrite) return Array.isArray(value) ? mapItems(value, writtenMessageWithId) : writtenMessageWithId(value);
+	if (!Array.isArray(overwriteValue)) return value;
+	const items = mapItems(overwriteValue, messageWithId);
+	return items === overwriteValue ? value : new Overwrite(items);
+}
+function mapItems(items, fn) {
+	const mapped = items.map(fn);
+	return mapped.every((item, i) => item === items[i]) ? items : mapped;
+}
+function writtenMessageWithId(item) {
+	if (!isPlainObject(item)) return messageWithId(item);
+	try {
+		if (coerceMessageLikeToMessage(item).id) return item;
+	} catch {
+		return item;
+	}
+	return {
+		...item,
+		id: v4()
+	};
+}
+function messageWithId(item) {
+	if (BaseMessage.isInstance(item)) {
+		stampMessageIds(item);
+		return item;
+	}
+	let message;
+	try {
+		message = coerceMessageLikeToMessage(item);
+	} catch {
+		return item;
+	}
+	if (!message.id) setMessageId(message);
+	return message;
+}
+function isPlainObject(item) {
+	if (typeof item !== "object" || item === null) return false;
+	const proto = Object.getPrototypeOf(item);
+	return (proto === Object.prototype || proto === null) && !("lc" in item);
+}
+function stampMessageIds(value) {
 	if (BaseMessage.isInstance(value)) {
-		const msg = value;
-		if (msg.id == null) {
-			msg.id = v4();
-			if (msg.lc_kwargs != null) msg.lc_kwargs.id = msg.id;
-		}
+		if (value.id == null) setMessageId(value);
 		return;
 	}
 	if (Array.isArray(value)) {
-		for (const item of value) ensureMessageIds(item);
+		for (const item of value) stampMessageIds(item);
 		return;
 	}
+	const [isOverwrite, overwriteValue] = _getOverwriteValue(value);
+	if (isOverwrite) stampMessageIds(overwriteValue);
+}
+function setMessageId(message) {
+	message.id = v4();
+	if (message.lc_kwargs != null) message.lc_kwargs.id = message.id;
 }
 /**
 * Split a serialized checkpoint namespace into its path segments.
@@ -111,20 +187,67 @@ var PregelLoop = class PregelLoop {
 	checkpointIdSaved;
 	/**
 	* Exit-mode accumulator of DeltaChannel writes across the whole run, as
-	* `[step, taskId, channel, value]`. `undefined` outside "exit" durability.
+	* `[step, taskId, taskPath, channel, value]` — see `_putExitDeltaWrites`
+	* for how they are ordered. `undefined` outside "exit" durability.
 	*/
 	_exitDeltaWrites;
 	/**
-	* DeltaChannels that saw an Overwrite since the last checkpoint. These
-	* channels are force-snapshotted at the next checkpoint so reconstruction
-	* starts from the post-overwrite value and never has to replay across the
-	* reset (the live `update` discards every sibling write in the overwriting
-	* super-step). Cleared once the channel snapshots.
+	* The `(taskId, channel)` pairs whose delta writes are stored on the loaded
+	* checkpoint, which a resume addressed by `checkpoint_id` can rerun.
+	* Captured in the constructor, before this run's Command processing adds
+	* writes (mirrors Python's `_first`). Used by the exit-mode accumulator to
+	* skip the loaded writes on the first superstep — they are already stored
+	* on the checkpoint.
+	*/
+	_storedDeltaWrites = /* @__PURE__ */ new Set();
+	/**
+	* This run's `Command` delta writes (`NULL_TASK_ID`), kept apart from the
+	* `NULL_TASK_ID` writes loaded with the checkpoint, which the first
+	* superstep skips. Written by the input handler; replayed into the
+	* exit-mode accumulator at the first superstep.
+	*/
+	_exitCommandWrites = [];
+	/**
+	* The step of the first superstep this run completed (the loaded
+	* checkpoint's own), or `null` before it ticks. The exit-mode accumulator
+	* keeps that superstep's real task paths so its writes interleave with the
+	* loaded ones as live execution did; later supersteps get `~~`-prefixed
+	* synthetic paths (see `_putExitDeltaWrites`).
+	*/
+	_exitFirstStep = null;
+	/**
+	* DeltaChannels that must snapshot at the next checkpoint, whatever their
+	* cadence counters say:
+	* - an Overwrite arrived since the last checkpoint, so sparse replay has to
+	*   start from the post-overwrite value;
+	* - the checkpoint this run starts from has pending writes to them; see
+	*   {@link deltaChannelsWithPendingWrites}.
+	* Cleared once the channel snapshots.
+	*/
+	_deltaChannelsForcedSnapshot = /* @__PURE__ */ new Set();
+	/**
+	* Set by `_first` for a resume: the writes it loaded with the checkpoint,
+	* which the end of the superstep checks against the ones handed back to
+	* their tasks.
+	*/
+	_resumeLoadedWrites = [];
+	/** Tasks a resume handed loaded writes back to. */
+	_reappliedTaskIds = /* @__PURE__ */ new Set();
+	/** Tasks that wrote during this run, the only ones exit mode saves at exit. */
+	_writtenTaskIds = /* @__PURE__ */ new Set();
+	/**
+	* A checkpoint addressed by `checkpoint_id` that the thread has moved past,
+	* so it may already have children.
 	*/
-	_deltaChannelsWithOverwrite = /* @__PURE__ */ new Set();
+	addressedCheckpointSuperseded;
 	/** Whether a real checkpoint was loaded from the saver at initialization. */
 	_hasPersistedParent = false;
 	/**
+	* Whether initialization loaded the thread's latest checkpoint, not one a
+	* `checkpoint_id` addressed, so nothing has been built on it yet.
+	*/
+	_loadedLatest = false;
+	/**
 	* Whether this branch carries {@link DELTA_WRITES_VERSIONED}: a graph with
 	* a DeltaChannel on a new thread, or a loaded checkpoint that has it. Every
 	* checkpoint this loop writes inherits it.
@@ -143,7 +266,9 @@ var PregelLoop = class PregelLoop {
 	outputKeys;
 	streamKeys;
 	nodes;
-	skipDoneTasks;
+	/** Whether the run points this loop at a checkpoint. */
+	addressed;
+	skipDoneTasks = true;
 	prevCheckpointConfig;
 	updatedChannels;
 	status = "pending";
@@ -162,6 +287,14 @@ var PregelLoop = class PregelLoop {
 	resumeAtHead;
 	_checkpointerChainedPromise = Promise.resolve();
 	/**
+	* The DeltaChannel writes this loop sent to the saver since the last
+	* checkpoint save was scheduled. That save waits for them, and a rejection
+	* skips it and every later save: a DeltaChannel is rebuilt from its writes
+	* along the parent chain, so a checkpoint saved past a missing write or
+	* parent reads back short for good.
+	*/
+	_pendingDeltaWrites = [];
+	/**
 	* Track a checkpointer promise, removing it from the set on success.
 	* Failed promises are kept so that Promise.all() in the finally block
 	* of _streamIterator can surface the error.
@@ -175,6 +308,7 @@ var PregelLoop = class PregelLoop {
 		}, (error) => {
 			throw error;
 		});
+		tracked.catch(() => {});
 		this.checkpointerPromises.add(tracked);
 	}
 	/**
@@ -222,18 +356,20 @@ var PregelLoop = class PregelLoop {
 		this.checkpointPreviousVersions = params.checkpointPreviousVersions;
 		this.channels = params.channels;
 		this.checkpointPendingWrites = params.checkpointPendingWrites;
+		for (const [tid, ch] of this.checkpointPendingWrites) if (tid !== "00000000-0000-0000-0000-000000000000" && isDeltaChannel(this.channels[ch])) this._storedDeltaWrites.add(`${tid}\u0000${ch}`);
 		this.step = params.step;
 		this.stop = params.stop;
 		this.config = params.config;
 		this.checkpointConfig = params.checkpointConfig;
 		this.isNested = params.isNested;
 		this.resumeAtHead = params.resumeAtHead;
+		this.addressedCheckpointSuperseded = params.addressedCheckpointSuperseded;
 		this.manager = params.manager;
 		this.lifecycleEvents = params.hasGraphCallbacks ? [] : void 0;
 		this.outputKeys = params.outputKeys;
 		this.streamKeys = params.streamKeys;
 		this.nodes = params.nodes;
-		this.skipDoneTasks = params.skipDoneTasks;
+		this.addressed = params.addressed;
 		this.store = params.store;
 		this.cache = params.cache ? new AsyncBatchedCache(params.cache) : void 0;
 		this.stream = params.stream;
@@ -247,6 +383,7 @@ var PregelLoop = class PregelLoop {
 		this.control = this.config.control;
 		this._exitDeltaWrites = this.durability === "exit" && this.checkpointer != null ? [] : void 0;
 		this._hasPersistedParent = params.hasPersistedParent ?? false;
+		this._loadedLatest = params.loadedLatest ?? false;
 		this._deltaWritesVersioned = params.deltaWritesVersioned ?? false;
 		this._initialCheckpointConfig = params.checkpointConfig;
 		this.checkpointIdSaved = params.checkpoint.id;
@@ -254,13 +391,11 @@ var PregelLoop = class PregelLoop {
 	static async initialize(params) {
 		let { config, stream } = params;
 		if (stream !== void 0 && config.configurable?.["__pregel_stream"] !== void 0) stream = createDuplexStream(stream, config.configurable[CONFIG_KEY_STREAM]);
-		const skipDoneTasks = config.configurable ? !("checkpoint_id" in config.configurable) : true;
 		const scratchpad = config.configurable?.[CONFIG_KEY_SCRATCHPAD];
 		if (config.configurable && scratchpad) {
 			if (scratchpad.subgraphCounter > 0) config = patchConfigurable(config, { [CONFIG_KEY_CHECKPOINT_NS]: [config.configurable[CONFIG_KEY_CHECKPOINT_NS], scratchpad.subgraphCounter.toString()].join("|") });
 			scratchpad.subgraphCounter += 1;
 		}
-		const requestedCheckpointId = config.configurable?.checkpoint_id;
 		const isNested = CONFIG_KEY_READ in (config.configurable ?? {});
 		if (!isNested && config.configurable?.checkpoint_ns !== void 0 && config.configurable?.checkpoint_ns !== "") config = patchConfigurable(config, {
 			checkpoint_ns: "",
@@ -268,15 +403,21 @@ var PregelLoop = class PregelLoop {
 		});
 		let checkpointConfig = config;
 		if (config.configurable?.checkpoint_id === void 0 && config.configurable?.["checkpoint_map"] !== void 0 && config.configurable?.["checkpoint_map"]?.[config.configurable?.checkpoint_ns]) checkpointConfig = patchConfigurable(config, { checkpoint_id: config.configurable[CONFIG_KEY_CHECKPOINT_MAP][config.configurable?.checkpoint_ns] });
+		const addressed = Boolean(checkpointConfig.configurable?.["checkpoint_id"] || config.configurable?.["__pregel_replay_state"]);
 		const checkpointNamespace = checkpointNamespaceFromNs(config.configurable?.checkpoint_ns);
 		let saved;
+		let loadedLatest = false;
 		if (!params.checkpointer) saved = void 0;
 		else if (checkpointConfig.configurable?.["checkpoint_id"]) saved = await params.checkpointer.getTuple(checkpointConfig);
 		else if (config.configurable?.["__pregel_replay_state"]) {
 			saved = await config.configurable[CONFIG_KEY_REPLAY_STATE].getCheckpoint(config.configurable?.["checkpoint_ns"] ?? "", params.checkpointer, checkpointConfig);
 			if (config.configurable) delete config.configurable[CONFIG_KEY_RESUMING];
-		} else saved = await params.checkpointer.getTuple(checkpointConfig);
+		} else {
+			saved = await params.checkpointer.getTuple(checkpointConfig);
+			loadedLatest = true;
+		}
 		const hasPersistedParent = saved !== void 0;
+		const addressedConfig = checkpointConfig;
 		if (!saved) saved = {
 			config,
 			checkpoint: emptyCheckpoint(),
@@ -304,12 +445,13 @@ var PregelLoop = class PregelLoop {
 		const checkpointMap = config.configurable?.[CONFIG_KEY_CHECKPOINT_MAP];
 		if (typeof currentCheckpointNamespace === "string" && currentCheckpointNamespace !== "" && typeof checkpointMap === "object" && checkpointMap !== null && currentCheckpointNamespace in checkpointMap && checkpointPendingWrites.length > 0) checkpointPendingWrites = checkpointPendingWrites.filter(([, channel]) => channel !== RESUME);
 		let resumeAtHead = false;
-		const threadId = checkpointConfig.configurable?.thread_id;
-		const checkpointNs = checkpointConfig.configurable?.checkpoint_ns ?? "";
-		if (params.checkpointer && requestedCheckpointId && typeof threadId === "string") resumeAtHead = (await params.checkpointer.getTuple({ configurable: {
-			thread_id: threadId,
-			checkpoint_ns: checkpointNs
-		} }))?.config.configurable?.checkpoint_id === requestedCheckpointId && checkpointMetadata.source !== "update" && checkpointMetadata.source !== "fork";
+		let addressedCheckpointSuperseded = false;
+		if (params.checkpointer && hasPersistedParent) {
+			const superseded = await checkpointSuperseded(params.checkpointer, addressedConfig, saved);
+			const isUpdateOrFork = checkpointMetadata.source === "update" || checkpointMetadata.source === "fork";
+			resumeAtHead = addressedConfig.configurable?.checkpoint_id !== void 0 && !superseded && !isUpdateOrFork;
+			addressedCheckpointSuperseded = superseded;
+		}
 		const deltaWritesVersioned = Object.values(params.channelSpecs).some(isDeltaChannel) && (!hasPersistedParent || isDeltaWritesVersioned(saved.metadata));
 		const channels = await channelsFromCheckpoint(params.channelSpecs, checkpoint, {
 			saver: params.checkpointer,
@@ -333,9 +475,10 @@ var PregelLoop = class PregelLoop {
 			channels,
 			isNested,
 			resumeAtHead,
+			addressedCheckpointSuperseded,
 			manager: params.manager,
 			hasGraphCallbacks: params.hasGraphCallbacks,
-			skipDoneTasks,
+			addressed,
 			step,
 			stop,
 			checkpointPreviousVersions,
@@ -352,11 +495,14 @@ var PregelLoop = class PregelLoop {
 			debug: params.debug,
 			triggerToNodes: params.triggerToNodes,
 			hasPersistedParent,
+			loadedLatest,
 			deltaWritesVersioned
 		});
 	}
 	_checkpointerPutAfterPrevious(input) {
-		this._checkpointerChainedPromise = this._checkpointerChainedPromise.then(() => {
+		const pendingDeltaWrites = this._pendingDeltaWrites;
+		this._pendingDeltaWrites = [];
+		this._checkpointerChainedPromise = this._checkpointerChainedPromise.then(() => Promise.all(pendingDeltaWrites)).then(() => {
 			return this.checkpointer?.put(input.config, input.checkpoint, input.metadata, input.newVersions);
 		});
 		this._trackCheckpointerPromise(this._checkpointerChainedPromise);
@@ -365,10 +511,14 @@ var PregelLoop = class PregelLoop {
 	* Put writes for a task, to be read by the next tick.
 	* @param taskId
 	* @param writes
+	* @param cached The writes were served from the node cache: stream them as
+	* cached and don't write them to the cache again.
 	*/
-	putWrites(taskId, writes) {
+	putWrites(taskId, writes, cached = false) {
 		let writesCopy = writes;
 		if (writesCopy.length === 0) return;
+		this._writtenTaskIds.add(taskId);
+		const deltaWrites = ensureDeltaMessageIds(this.channels, writes);
 		if (writesCopy.every(([key]) => key in WRITES_IDX_MAP)) writesCopy = Array.from(new Map(writesCopy.map((w) => [w[0], w])).values());
 		let hasUntrackedChannels = false;
 		for (const key in this.channels) if (Object.prototype.hasOwnProperty.call(this.channels, key)) {
@@ -391,17 +541,18 @@ var PregelLoop = class PregelLoop {
 			c,
 			v
 		]);
-		for (const [c, v] of writesToSave) {
-			const channel = this.channels[c];
-			if (channel != null && isDeltaChannel(channel)) ensureMessageIds(v);
-		}
 		const config = patchConfigurable(this.checkpointConfig, {
 			[CONFIG_KEY_CHECKPOINT_NS]: this.config.configurable?.checkpoint_ns ?? "",
 			[CONFIG_KEY_CHECKPOINT_ID]: this.checkpoint.id
 		});
-		if (this.durability !== "exit" && this.checkpointer != null) this._trackCheckpointerPromise(this.checkpointer.putWrites(config, writesToSave, taskId));
-		if (this.tasks) this._outputWrites(taskId, writesCopy);
-		if (!writes.length || !this.cache || !this.tasks) return;
+		if (this.durability !== "exit" && this.checkpointer != null) {
+			const task = this.tasks[taskId];
+			const saved = this.checkpointer.putWrites(config, writesToSave, taskId, task != null ? taskPathStr(task.path) : "");
+			this._trackCheckpointerPromise(saved);
+			if (deltaWrites.length > 0) this._pendingDeltaWrites.push(saved);
+		}
+		if (this.tasks) this._outputWrites(taskId, writesCopy, cached);
+		if (cached || !writes.length || !this.cache || !this.tasks) return;
 		const task = this.tasks[taskId];
 		if (task == null || task.cache_key == null) return;
 		if (writes[0][0] === "__error__" || writes[0][0] === "__interrupt__") return;
@@ -411,6 +562,10 @@ var PregelLoop = class PregelLoop {
 			ttl: task.cache_key.ttl
 		}]);
 	}
+	/** Streams the writes reapplied to tasks that finished in a previous run. */
+	_outputCachedWrites(tasks) {
+		for (const task of tasks) if (task.writes.length > 0) this._outputWrites(task.id, task.writes, true);
+	}
 	_outputWrites(taskId, writes, cached = false) {
 		const task = this.tasks[taskId];
 		if (task !== void 0) {
@@ -469,19 +624,37 @@ var PregelLoop = class PregelLoop {
 			const finishTaskList = Object.values(this.tasks);
 			const writes = finishTaskList.flatMap((t) => t.writes);
 			this.updatedChannels = _applyWrites(this.checkpoint, this.channels, finishTaskList, this.checkpointerGetNextVersion, this.triggerToNodes);
-			for (const [ch, v] of writes) {
-				const channel = this.channels[ch];
-				if (channel != null && isDeltaChannel(channel) && _isOverwriteValue(v)) this._deltaChannelsWithOverwrite.add(ch);
+			for (const [ch, v] of deltaChannelWrites(this.channels, writes)) if (_isOverwriteValue(v)) this._deltaChannelsForcedSnapshot.add(ch);
+			if (this._resumeLoadedWrites.length > 0) {
+				for (const ch of deltaChannelsWithPendingWrites(this.channels, this._resumeLoadedWrites.filter(([tid]) => !this._reappliedTaskIds.has(tid)))) this._deltaChannelsForcedSnapshot.add(ch);
+				this._resumeLoadedWrites = [];
 			}
 			const valuesOutput = await gatherIterator(prefixGenerator(mapOutputValues(this.outputKeys, writes, this.channels), "values"));
-			if (this._exitDeltaWrites !== void 0) for (const [tid, ch, v] of this.checkpointPendingWrites) {
-				const channel = this.channels[ch];
-				if (channel != null && isDeltaChannel(channel)) this._exitDeltaWrites.push([
-					this.step,
-					tid,
-					ch,
-					v
-				]);
+			if (this._exitDeltaWrites !== void 0) {
+				const first = this._exitFirstStep === null;
+				if (first) {
+					this._exitFirstStep = this.step;
+					for (const [ch, v] of this._exitCommandWrites) this._exitDeltaWrites.push([
+						this.step,
+						NULL_TASK_ID,
+						"",
+						ch,
+						v
+					]);
+				}
+				for (const [tid, ch, v] of this.checkpointPendingWrites) {
+					const channel = this.channels[ch];
+					if (channel == null || !isDeltaChannel(channel)) continue;
+					if (first && (tid === "00000000-0000-0000-0000-000000000000" || this._storedDeltaWrites.has(`${tid}\u0000${ch}`))) continue;
+					const task = this.tasks[tid];
+					this._exitDeltaWrites.push([
+						this.step,
+						tid,
+						task != null ? taskPathStr(task.path) : "",
+						ch,
+						v
+					]);
+				}
 			}
 			this.checkpointPendingWrites = [];
 			await this._putCheckpoint({ source: "loop" });
@@ -513,25 +686,24 @@ var PregelLoop = class PregelLoop {
 			this.status = "done";
 			return false;
 		}
-		if (this.control != null && this.control.drainRequested) {
-			this.status = "draining";
-			return false;
-		}
 		if (this.skipDoneTasks && this.checkpointPendingWrites.length > 0) {
-			for (const [tid, k, v] of this.checkpointPendingWrites) {
-				if (k === "__error__" || k === "__error_source_node__" || k === "__interrupt__" || k === "__resume__") continue;
-				const task = taskList.find((t) => t.id === tid);
-				if (task) task.writes.push([k, v]);
-			}
+			this._reapplyWritesToSucceededNodes(this.tasks);
 			this._resumeErrorHandlersIfApplicable();
 			taskList = Object.values(this.tasks);
-			for (const task of taskList) if (task.writes.length > 0) this._outputWrites(task.id, task.writes, true);
 		}
-		if (taskList.every((task) => task.writes.length > 0)) return this.tick({ inputKeys });
+		if (taskList.every((task) => task.writes.length > 0)) {
+			this._outputCachedWrites(taskList);
+			return this.tick({ inputKeys });
+		}
 		if (shouldInterrupt(this.checkpoint, this.interruptBefore, taskList)) {
 			this.status = "interrupt_before";
 			throw new GraphInterrupt();
 		}
+		if (this.control != null && this.control.drainRequested) {
+			this.status = "draining";
+			return false;
+		}
+		this._outputCachedWrites(taskList);
 		if (this.stream.modes.has("tasks") || this.stream.modes.has("debug")) {
 			const debugOutput = await gatherIterator(prefixGenerator(mapDebugTasks(taskList), "tasks"));
 			this._emit(debugOutput);
@@ -583,7 +755,7 @@ var PregelLoop = class PregelLoop {
 		this.tasks[pushed.id] = pushed;
 		if (this.skipDoneTasks) this._matchWrites({ [pushed.id]: pushed });
 		const tasks = await this._matchCachedWrites();
-		for (const { task } of tasks) this._outputWrites(task.id, task.writes, true);
+		for (const { task } of tasks) this.putWrites(task.id, task.writes, true);
 		return pushed;
 	}
 	/**
@@ -667,33 +839,54 @@ var PregelLoop = class PregelLoop {
 	}
 	async _first(inputKeys) {
 		const { configurable } = this.config;
-		if (isCommand(this.input)) {
-			const hasResume = this.input.resume != null;
-			if (this.input.resume != null && typeof this.input.resume === "object" && Object.keys(this.input.resume).every(isXXH3)) {
+		const inputIsCommand = isCommand(this.input);
+		const isTimeTraveling = this.addressed && (this.isNested && configurable?.["checkpoint_ns"] !== void 0 && configurable?.["checkpoint_ns"] !== "" && configurable?.["checkpoint_map"] !== void 0 && configurable["checkpoint_ns"] in configurable["checkpoint_map"] || !(inputIsCommand && this.input.resume != null || configurable?.["__pregel_resuming"] === true || this.resumeAtHead));
+		this.skipDoneTasks = !(isTimeTraveling || this.addressedCheckpointSuperseded);
+		const isUpdateOrFork = this.checkpointMetadata.source === "update" || this.checkpointMetadata.source === "fork";
+		const forks = isTimeTraveling && (inputIsCommand || this.isResuming) && (!isUpdateOrFork || this.addressedCheckpointSuperseded);
+		const carried = [];
+		const reapplies = this.isResuming && this.skipDoneTasks;
+		this._resumeLoadedWrites = reapplies ? this.checkpointPendingWrites.filter(([tid]) => tid !== NULL_TASK_ID) : [];
+		this._reappliedTaskIds = /* @__PURE__ */ new Set();
+		this._deltaChannelsForcedSnapshot = reapplies ? /* @__PURE__ */ new Set() : deltaChannelsWithPendingWrites(this.channels, this.checkpointPendingWrites);
+		if (inputIsCommand) {
+			const command = this.input;
+			const hasResume = command.resume != null;
+			if (command.resume != null && typeof command.resume === "object" && Object.keys(command.resume).every(isXXH3)) {
 				this.config.configurable ??= {};
-				this.config.configurable[CONFIG_KEY_RESUME_MAP] = this.input.resume;
+				this.config.configurable[CONFIG_KEY_RESUME_MAP] = command.resume;
 			}
 			if (hasResume && this.checkpointer == null) throw new Error("Cannot use Command(resume=...) without checkpointer");
 			const writes = {};
-			for (const [tid, key, value] of mapCommand(this.input, this.checkpointPendingWrites)) {
+			for (const [tid, key, value] of mapCommand(command, this.checkpointPendingWrites)) {
 				writes[tid] ??= [];
 				writes[tid].push([key, value]);
 			}
 			if (Object.keys(writes).length === 0) throw new EmptyInputError("Received empty Command input");
-			for (const [tid, ws] of Object.entries(writes)) this.putWrites(tid, ws);
+			for (const [tid, ws] of Object.entries(writes)) if (forks) {
+				ensureDeltaMessageIds(this.channels, ws);
+				for (const [c, v] of ws) carried.push([
+					tid,
+					c,
+					v
+				]);
+			} else {
+				this.putWrites(tid, ws);
+				if (this._exitDeltaWrites !== void 0 && tid === "00000000-0000-0000-0000-000000000000") this._exitCommandWrites.push(...deltaChannelWrites(this.channels, ws));
+			}
+			for (const ch of deltaChannelsWithPendingWrites(this.channels, carried)) this._deltaChannelsForcedSnapshot.add(ch);
 		}
-		const nullWrites = (this.checkpointPendingWrites ?? []).filter((w) => w[0] === NULL_TASK_ID).map((w) => w.slice(1));
+		const nullWrites = [...this.checkpointPendingWrites ?? [], ...carried].filter((w) => w[0] === NULL_TASK_ID).map((w) => w.slice(1));
 		if (nullWrites.length > 0) _applyWrites(this.checkpoint, this.channels, [{
 			name: INPUT,
 			writes: nullWrites,
 			triggers: []
 		}], this.checkpointerGetNextVersion, this.triggerToNodes);
-		const inputIsCommand = isCommand(this.input);
 		const isCommandUpdateOrGoto = inputIsCommand && nullWrites.length > 0;
-		const isTimeTraveling = this.isReplaying && (this.isNested && configurable?.["checkpoint_ns"] !== void 0 && configurable?.["checkpoint_ns"] !== "" && configurable?.["checkpoint_map"] !== void 0 && configurable["checkpoint_ns"] in configurable["checkpoint_map"] || !(inputIsCommand && this.input.resume != null || configurable?.["__pregel_resuming"] === true || this.resumeAtHead));
 		if (isTimeTraveling) this.checkpointPendingWrites = this.checkpointPendingWrites.filter((w) => w[1] !== RESUME);
-		const scratchpad = configurable?.[CONFIG_KEY_SCRATCHPAD];
-		if (scratchpad && scratchpad.nullResume !== void 0) this.putWrites(NULL_TASK_ID, [[RESUME, scratchpad.nullResume]]);
+		const nullResume = (configurable?.[CONFIG_KEY_SCRATCHPAD])?.nullResume;
+		if (nullResume !== void 0 && !forks) this.putWrites(NULL_TASK_ID, [[RESUME, nullResume]]);
+		let replayBound;
 		const cachedIsResuming = this.isResuming;
 		if (cachedIsResuming || isCommandUpdateOrGoto) {
 			const interruptSeen = { ...this.checkpoint.versions_seen[INTERRUPT] };
@@ -702,9 +895,11 @@ var PregelLoop = class PregelLoop {
 				if (this.checkpoint.channel_versions[channelName] !== void 0) interruptSeen[channelName] = this.checkpoint.channel_versions[channelName];
 			}
 			this.checkpoint.versions_seen[INTERRUPT] = interruptSeen;
-			if (isTimeTraveling && this.checkpointMetadata.source !== "update" && this.checkpointMetadata.source !== "fork") {
+			if (forks) {
+				if (isUpdateOrFork && this.prevCheckpointConfig) replayBound = this.prevCheckpointConfig;
 				this.checkpointPendingWrites = this.checkpointPendingWrites.filter((w) => w[1] !== INTERRUPT);
 				await this._putCheckpoint({ source: "fork" });
+				if (nullResume !== void 0) this.putWrites(NULL_TASK_ID, [[RESUME, nullResume]]);
 			}
 			const valuesOutput = await gatherIterator(prefixGenerator(mapOutputValues(this.outputKeys, true, this.channels), "values"));
 			if (cachedIsResuming) this.input = INPUT_RESUMING;
@@ -716,25 +911,24 @@ var PregelLoop = class PregelLoop {
 		} else {
 			const inputWrites = await gatherIterator(mapInput(inputKeys, this.input));
 			if (inputWrites.length > 0) {
+				const deltaInput = ensureDeltaMessageIds(this.channels, inputWrites);
 				const discardTasks = _prepareNextTasks(this.checkpoint, this.checkpointPendingWrites, this.nodes, this.channels, this.config, true, { step: this.step });
 				this.updatedChannels = _applyWrites(this.checkpoint, this.channels, Object.values(discardTasks).concat([{
 					name: INPUT,
 					writes: inputWrites,
 					triggers: []
 				}]), this.checkpointerGetNextVersion, this.triggerToNodes);
-				const deltaInput = inputWrites.filter(([c]) => {
-					const channel = this.channels[c];
-					return channel != null && isDeltaChannel(channel);
-				});
-				for (const [c, v] of deltaInput) if (_isOverwriteValue(v)) this._deltaChannelsWithOverwrite.add(c);
+				for (const [c, v] of deltaInput) if (_isOverwriteValue(v)) this._deltaChannelsForcedSnapshot.add(c);
 				if (deltaInput.length > 0) {
 					if (this._exitDeltaWrites !== void 0) for (const [c, v] of deltaInput) this._exitDeltaWrites.push([
 						this.step,
 						NULL_TASK_ID,
+						"",
 						c,
 						v
 					]);
-					else if (this.checkpointer != null) this.putWrites(NULL_TASK_ID, deltaInput);
+					else if (this.checkpointer != null) if (this._hasPersistedParent && this._loadedLatest) this.putWrites(uuid5(INPUT, this.checkpoint.id), deltaInput);
+					else for (const [c] of deltaInput) this._deltaChannelsForcedSnapshot.add(c);
 				}
 				await this._putCheckpoint({ source: "input" });
 				this.input = INPUT_DONE;
@@ -745,7 +939,8 @@ var PregelLoop = class PregelLoop {
 			let replayState;
 			if (isTimeTraveling) {
 				let replayCheckpointId = this.checkpoint.id;
-				if ((this.checkpointMetadata.source === "update" || this.checkpointMetadata.source === "fork") && this.prevCheckpointConfig) replayCheckpointId = this.prevCheckpointConfig.configurable?.["checkpoint_id"] ?? replayCheckpointId;
+				if (replayBound !== void 0) replayCheckpointId = replayBound.configurable?.["checkpoint_id"] ?? replayCheckpointId;
+				else if ((this.checkpointMetadata.source === "update" || this.checkpointMetadata.source === "fork") && this.prevCheckpointConfig) replayCheckpointId = this.prevCheckpointConfig.configurable?.["checkpoint_id"] ?? replayCheckpointId;
 				replayState = new ReplayState(replayCheckpointId);
 			}
 			this.config = patchConfigurable(this.config, {
@@ -855,15 +1050,7 @@ var PregelLoop = class PregelLoop {
 		};
 		let newCounters;
 		if (!exiting) {
-			const prevCounters = this.checkpointMetadata.counters_since_delta_snapshot ?? {};
-			newCounters = {};
-			const updated = this.updatedChannels ?? /* @__PURE__ */ new Set();
-			for (const chName in this.channels) {
-				if (!Object.prototype.hasOwnProperty.call(this.channels, chName)) continue;
-				if (!isDeltaChannel(this.channels[chName])) continue;
-				const [u, s] = prevCounters[chName] ?? [0, 0];
-				newCounters[chName] = [updated.has(chName) ? u + 1 : u, s + 1];
-			}
+			newCounters = advanceDeltaCounters(this.channels, this.updatedChannels ?? /* @__PURE__ */ new Set(), this.checkpointMetadata.counters_since_delta_snapshot);
 			this.checkpointMetadata = {
 				...inputMetadata,
 				step: this.step,
@@ -872,16 +1059,17 @@ var PregelLoop = class PregelLoop {
 		} else newCounters = { ...this.checkpointMetadata.counters_since_delta_snapshot ?? {} };
 		if (this._deltaWritesVersioned) this.checkpointMetadata[DELTA_WRITES_VERSIONED] = true;
 		const channelsToSnapshot = doCheckpoint ? deltaChannelsToSnapshot(this.channels, newCounters, this._deltaWritesVersioned ? this.checkpoint.channel_versions : void 0) : /* @__PURE__ */ new Set();
-		if (doCheckpoint) for (const ch of this._deltaChannelsWithOverwrite) channelsToSnapshot.add(ch);
+		if (doCheckpoint) for (const ch of this._deltaChannelsForcedSnapshot) channelsToSnapshot.add(ch);
 		this.checkpoint = createCheckpoint(this.checkpoint, doCheckpoint ? this.channels : void 0, this.step, {
 			id: exiting ? this.checkpoint.id : void 0,
 			channelsToSnapshot,
-			updatedChannels: this.updatedChannels,
-			getNextVersion: doCheckpoint ? (current) => this.checkpointerGetNextVersion(current) : void 0
+			storedVersions: this.checkpointPreviousVersions,
+			getNextVersion: doCheckpoint ? (current) => this.checkpointerGetNextVersion(current) : void 0,
+			triggerToNodes: this.triggerToNodes
 		});
 		for (const k of channelsToSnapshot) {
 			newCounters[k] = [0, 0];
-			this._deltaChannelsWithOverwrite.delete(k);
+			this._deltaChannelsForcedSnapshot.delete(k);
 		}
 		const nonZero = {};
 		for (const k in newCounters) {
@@ -907,10 +1095,11 @@ var PregelLoop = class PregelLoop {
 	*/
 	async _putExitDeltaWrites() {
 		if (this._exitDeltaWrites === void 0 || this._exitDeltaWrites.length === 0 || this.checkpointer == null || this._initialCheckpointConfig === void 0) return;
+		if (this._hasPersistedParent && !this._loadedLatest) for (const [, , , ch] of this._exitDeltaWrites) this._deltaChannelsForcedSnapshot.add(ch);
 		const counters = this.checkpointMetadata.counters_since_delta_snapshot ?? {};
 		const channelsToSnapshot = deltaChannelsToSnapshot(this.channels, counters, this._deltaWritesVersioned ? this.checkpoint.channel_versions : void 0);
-		for (const ch of this._deltaChannelsWithOverwrite) channelsToSnapshot.add(ch);
-		const pending = this._exitDeltaWrites.filter(([, , ch]) => !channelsToSnapshot.has(ch));
+		for (const ch of this._deltaChannelsForcedSnapshot) channelsToSnapshot.add(ch);
+		const pending = this._exitDeltaWrites.filter(([, , , ch]) => !channelsToSnapshot.has(ch));
 		if (pending.length === 0) return;
 		let anchorConfig;
 		if (this._hasPersistedParent) anchorConfig = this._initialCheckpointConfig;
@@ -920,11 +1109,16 @@ var PregelLoop = class PregelLoop {
 			stubCp.ts = (/* @__PURE__ */ new Date()).toISOString();
 			const stubPutConfig = patchConfigurable(this._initialCheckpointConfig, { [CONFIG_KEY_CHECKPOINT_ID]: void 0 });
 			anchorConfig = patchConfigurable(this._initialCheckpointConfig, { [CONFIG_KEY_CHECKPOINT_ID]: stubCp.id });
-			this._trackCheckpointerPromise(this.checkpointer.put(stubPutConfig, stubCp, {
-				source: "loop",
-				step: -2,
-				parents: {}
-			}, {}));
+			this._checkpointerPutAfterPrevious({
+				config: stubPutConfig,
+				checkpoint: stubCp,
+				metadata: {
+					source: "loop",
+					step: -2,
+					parents: {}
+				},
+				newVersions: {}
+			});
 			this.checkpointConfig = anchorConfig;
 		}
 		const anchorWriteConfig = patchConfigurable(anchorConfig, {
@@ -933,23 +1127,36 @@ var PregelLoop = class PregelLoop {
 		});
 		const grouped = /* @__PURE__ */ new Map();
 		const order = [];
-		for (const [step, tid, ch, v] of pending) {
-			const key = `${step}\u0000${tid}`;
+		for (const [step, tid, path, ch, v] of pending) {
+			let synthTid;
+			let synthPath;
+			if (tid === "00000000-0000-0000-0000-000000000000") {
+				synthTid = exitDeltaTaskId(step, tid);
+				synthPath = "";
+			} else if (step === this._exitFirstStep) {
+				synthTid = exitDeltaTaskId(step, tid);
+				synthPath = path;
+			} else {
+				synthTid = exitDeltaLateTaskId(step, tid);
+				synthPath = `~~${taskPathStr(step)}${path}`;
+			}
+			const key = `${synthTid}\u0000${synthPath}`;
 			let group = grouped.get(key);
 			if (group === void 0) {
 				group = [];
 				grouped.set(key, group);
 				order.push({
 					key,
-					step,
-					tid
+					tid: synthTid,
+					path: synthPath
 				});
 			}
 			group.push([ch, v]);
 		}
-		for (const { key, step, tid } of order) {
-			const synthTid = exitDeltaTaskId(step, tid);
-			this._trackCheckpointerPromise(this.checkpointer.putWrites(anchorWriteConfig, grouped.get(key), synthTid));
+		for (const { key, tid, path } of order) {
+			const saved = this.checkpointer.putWrites(anchorWriteConfig, grouped.get(key), tid, path);
+			this._trackCheckpointerPromise(saved);
+			this._pendingDeltaWrites.push(saved);
 		}
 	}
 	_flushPendingWrites() {
@@ -961,21 +1168,36 @@ var PregelLoop = class PregelLoop {
 		});
 		const byTask = {};
 		for (const [tid, key, value] of this.checkpointPendingWrites) {
+			if (!this._writtenTaskIds.has(tid)) continue;
 			byTask[tid] ??= [];
 			byTask[tid].push([key, value]);
 		}
-		for (const [tid, ws] of Object.entries(byTask)) this._trackCheckpointerPromise(this.checkpointer.putWrites(config, ws, tid));
+		for (const [tid, ws] of Object.entries(byTask)) {
+			const task = this.tasks[tid];
+			this._trackCheckpointerPromise(this.checkpointer.putWrites(config, ws, tid, task != null ? taskPathStr(task.path) : ""));
+		}
 	}
-	_matchWrites(tasks) {
+	/**
+	* Hands the writes loaded with the checkpoint back to the finished tasks
+	* among `tasks`. A failed or interrupted task keeps empty writes, so it
+	* reruns or goes to its error handler.
+	*/
+	_reapplyWritesToSucceededNodes(tasks) {
 		for (const [tid, k, v] of this.checkpointPendingWrites) {
-			if (k === "__error__" || k === "__interrupt__" || k === "__resume__") continue;
-			const task = Object.values(tasks).find((t) => t.id === tid);
-			if (task) task.writes.push([k, v]);
+			if (k === "__error__" || k === "__error_source_node__" || k === "__interrupt__" || k === "__resume__") continue;
+			const task = tasks[tid];
+			if (task) {
+				task.writes.push([k, v]);
+				this._reappliedTaskIds.add(tid);
+			}
 		}
+	}
+	_matchWrites(tasks) {
+		this._reapplyWritesToSucceededNodes(tasks);
 		for (const task of Object.values(tasks)) if (task.writes.length > 0) this._outputWrites(task.id, task.writes, true);
 	}
 };
 //#endregion
-export { PregelLoop };
+export { PregelLoop, ensureDeltaMessageIds };
 
 //# sourceMappingURL=loop.js.map