@deepseek-ai/dsh-session-persistence-jsonl 0.1.5-rc.1 → 0.1.6-alpha.1

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/session/session-persistence-jsonl/README.md
-README.md: 194ea835f87e4c34e0821083246bcf89c0e0a684
-README.zh.md: 4512d67e3439cbb4cf8642ca67be56bf0c7ac5b1
+README.md: fc431ff27bcd236c4d44b8d3e7b20d4291b936d4
+README.zh.md: 3b265bf43f058d4c0711568df156825febed4d24

package/README.md

@@ -53,7 +53,7 @@ The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-a
 
 ### On-disk layout
 
-Each session gets a session-owned directory under a readable project directory. Every canonical generation starts with a physical header whose version equals its filename. The current format stores one physical row per durable event; the frozen v0 and v1 readers also understand their historical packed Assistant-delta rows. The current format stores `isSeeded` in the header and derives the inherited cut from the last tagged `session/end-seed` marker, while historical codecs translate their numeric `seedLength`. The format catalog completes that translation before a handle exposes current logical values. Current storage records use the lossless provenance representation described below:
+Each session gets a session-owned directory under a readable project directory. Every canonical generation starts with a physical header whose version equals its filename. The current format stores one physical row per durable event; the frozen v0 and v1 readers also understand their historical packed Assistant-delta rows. The current format stores `isSeeded` in the header and derives the inherited cut from the last tagged `session/end-seed` marker, while historical codecs translate their numeric `seedLength`. The format catalog completes that translation before a handle exposes current logical values. Current storage records use the lossless source-event representation described below:
 
 ```text
 <root>/
@@ -62,9 +62,11 @@ Each session gets a session-owned directory under a readable project directory.
       session.jsonl.zstd         # released v0, compressed root
       session.v1.jsonl.zstd      # released v1, compressed root
       session.v2.jsonl.zstd      # released v2, compressed root
+      session.v3.jsonl.zstd      # released v3/current, compressed root
       session.jsonl              # released v0, raw root
       session.v1.jsonl           # released v1, raw root
-      session.v2.jsonl           # released v2, raw root; later versions use vN
+      session.v2.jsonl           # released v2, raw root
+      session.v3.jsonl           # released v3/current, raw root; later versions use vN
 ```
 
 Session ids are injectively escaped to one safe path segment before use (no traversal, no collision). The normalized cwd keeps the project directory readable for navigation; cwd strings that normalize alike share a project directory while session ids still select distinct session directories. Runtime operations select the numerically highest canonical generation, and format-refusal diagnostics name that absolute path so an operator can find the raw log a build refused to interpret.

package/README.zh.md

@@ -29,7 +29,7 @@ kind: "package-reference"
 
 ### 何时选择
 
-当消费方受益于每会话一份产物——导航、外部工具或可逐行读取的原始日志——时选择此后端。它是随产品交付的唯一 Session 持久化 provider。后端把会话保存在部署控制的根下：项目本地、共享、临时或集中式。
+当消费方受益于每会话一份产物——导航、外部工具或可逐行读取的原始日志——时选择此后端。它是唯一的第一方会话持久化提供方。后端把会话保存在部署控制的根下：项目本地、共享、临时或集中式。
 
 ### 最小配置
 
@@ -62,12 +62,14 @@ kind: "package-reference"
       session.jsonl.zstd         # released v0, compressed root
       session.v1.jsonl.zstd      # released v1, compressed root
       session.v2.jsonl.zstd      # released v2, compressed root
+      session.v3.jsonl.zstd      # released v3/current, compressed root
       session.jsonl              # released v0, raw root
       session.v1.jsonl           # released v1, raw root
-      session.v2.jsonl           # released v2, raw root; later versions use vN
+      session.v2.jsonl           # released v2, raw root
+      session.v3.jsonl           # released v3/current, raw root; later versions use vN
 ```
 
-会话 id 在使用前被单射转义为一个安全路径段（无遍历、无冲突）。规范化 cwd 让项目目录保持可读、便于导航；规范化相同的 cwd 字符串共享项目目录，而会话 id 仍选择不同会话目录。runtime 操作选择数值最高的规范 generation，格式拒绝诊断会点名该绝对路径，让操作者能找到构建拒绝解读的原始日志。
+会话 id 在使用前被单射转义为一个安全路径段（无遍历、无冲突）。规范化 cwd 让项目目录保持可读、便于导航；规范化相同的 cwd 字符串共享项目目录，而会话 id 仍选择不同会话目录。运行时操作选择数值最高的规范 generation，格式拒绝诊断会点名该绝对路径，让操作者能找到构建拒绝解读的原始日志。
 
 ### 持久性与崩溃语义
 
@@ -77,7 +79,7 @@ kind: "package-reference"
 
 ### 读取日志
 
-`open(id, 'read'|'write')` 选择最高规范 generation。当前格式输入走普通快速路径。对于历史输入，只读 open 会单遍解码并迁移源、校验当前逻辑结果，然后在不发布后继的情况下返回。写 open 会在可用时复用按 revision 为键的 preparation，否则执行同一套 preparation，再按有界分片编码同目录临时文件、在 Worker Thread 中校验、复查源修订，并在返回前以不覆盖方式发布当前后继。源保持逐字节不变。如果源在 preparation 后发生变化，该次写 open 会失败，已经返回给读方的逻辑历史不会被替换；后续写 open 会针对新的 revision 重新执行 preparation。Backend 在 memo 化前冻结已解码的 event graph，并在此时将其标记为 `shared-frozen`；句柄读取和 slice 即使为空也保留该状态。只有尚未实体化的 pending 空日志报告 `detached`。`stat(id)` 与 `list()` 只选择并转换最高 generation 的 header，不读取事件行，也不启动迁移；快照携带所选文件的 `sizeBytes` 与尽力而为的 stat 派生修订号。选择 `compression: 'none'` 后，日志是外部读取方可直接消费的换行分隔文本；压缩默认值必须经后端读取。
+`open(id, 'read'|'write')` 选择最高规范 generation。当前格式输入走普通快速路径。对于历史输入，只读 open 会单遍解码并迁移源、校验当前逻辑结果，然后在不发布后继的情况下返回。写 open 会在可用时复用按 revision 为键的 preparation，否则执行同一套 preparation，再按有界分片编码同目录临时文件、在 Worker Thread 中校验、复查源修订，并在返回前以不覆盖方式发布当前后继。源保持逐字节不变。如果源在 preparation 后发生变化，该次写 open 会失败，已经返回给读方的逻辑历史不会被替换；后续写 open 会针对新的 revision 重新执行 preparation。后端在 memo 化前冻结已解码的 event graph，并在此时将其标记为 `shared-frozen`；句柄读取和 slice 即使为空也保留该状态。只有尚未实体化的 pending 空日志报告 `detached`。`stat(id)` 与 `list()` 只选择并转换最高 generation 的 header，不读取事件行，也不启动迁移；快照携带所选文件的 `sizeBytes` 与尽力而为的 stat 派生修订号。选择 `compression: 'none'` 后，日志是外部读取方可直接消费的换行分隔文本；压缩默认值必须经后端读取。
 
 -----
 
@@ -108,7 +110,7 @@ kind: "package-reference"
 | [`src/migration-verifier.ts`](src/migration-verifier.ts) | stage 与竞争 generation 校验的 Worker 生命周期 |
 | [`src/zstd.ts`](src/zstd.ts) | Zstandard 帧压缩、解码与帧扫描 |
 | [`src/win32.ts`](src/win32.ts) | Windows write-through 发布与目录创建 |
-| — | 不发布运行时不变式伴生入口；身份在存储层强制。 |
+| — | 不发布运行时不变式伴生入口；身份在存储层强制；持久化正确性依赖后端往返与崩溃尾部测试，本包不公开可持续观察的进程内关系。 |
 
 </details>
 
@@ -151,11 +153,11 @@ JSONL 存储不修改实时请求前缀。只有重建历史、当前 envelope
 
 这些限制说明本后端何时不合适，或何时需要特别的运维注意。它们是当前包约束，不是任务积压。
 
-- **格式迁移保留已配置编码，且只支持 catalog 中的链**——本 build 把受支持的历史代迁移到当前格式；更改压缩需要独立根，保留的前任不提供自动 fallback 或 downgrade 支持。
+- **格式迁移保留已配置编码，且只支持 catalog 中的链**——本 build 把受支持的历史代迁移到当前格式；更改压缩需要独立根，保留的旧版本不提供自动 fallback 或 downgrade 支持。
 - **平铺文件存储布局不加载**——加载前使用独立根，或将预发布产物移入项目/会话目录布局。
 - **压缩文件不能直接按行读取**——使用后端加载；或在写入新根前选择 `compression: 'none'`，供外部行读取方使用。
 - **不删除会话文件**——日志在 `root` 下累积，直到外部移除；seam 无删除接口。
-- **每会话一个活动写入方**——写句柄认领在所属后端实例内排除第二个写入方，内核锁（`session.lock` 上的非阻塞 `flock(2)`；Windows 上为由该路径派生的命名内核信号量，零文件系统足迹）排除其他所有实例与进程；锁在写打开既有工件时立即获取，新建会话则仅在首次物化写入之前获取，因此未物化的会话不留任何文件系统足迹。崩溃持有者的锁随其进程消亡，会话立即可再写入，而活着但卡死的持有者会阻塞写入方直到其进程退出（POSIX 上删除锁文件即放弃该排他；释放本身从不删除它）。咨询式 `flock` 在部分网络文件系统（NFSv3）上不可靠，Windows 信号量名按登录会话隔离。
+- **每会话一个活动写入方**——写句柄认领在所属后端实例内排除第二个写入方，内核锁（`session.lock` 上的非阻塞 `flock(2)`；Windows 上为由该路径派生的命名内核信号量，零文件系统足迹）排除其他所有实例与进程；锁在以写模式打开既有产物时立即获取，新建会话则仅在首次实体化写入之前获取，因此未实体化的会话不留任何文件系统足迹。崩溃持有者的锁随其进程消亡，会话立即可再写入，而活着但卡死的持有者会阻塞写入方直到其进程退出（POSIX 上删除锁文件即放弃该排他；释放本身从不删除它）。咨询式 `flock` 在部分网络文件系统（NFSv3）上不可靠，Windows 信号量名按登录会话隔离。
 - **POSIX 实体化需要硬链接支持**——第一次 append 使用 `link()`，使同 id 竞态失败而不覆盖已提交日志；Windows 使用无替换 write-through rename。
 - **POSIX 写入需要匹配的预编译系统 addon**——[`node-addon-system`](../../../native/system/README.zh.md) 提供异步 flock，无须在用户侧编译。addon 缺失时拒绝写入所有权；Windows 保留其信号量实现。
 

package/lib/index.js

@@ -16,6 +16,7 @@ import { constants, createZstdCompress, createZstdDecompress, zstdCompress, zstd
 import { isDeepStrictEqual, promisify } from "node:util";
 import { constants as constants$1 } from "node:buffer";
 import { Worker } from "node:worker_threads";
+import { currentSessionMessageProjections } from "@deepseek-ai/dsh-session-format-catalog/message-projections";
 import { Readable, pipeline } from "node:stream";
 /**
 * The JSONL session handle. Mutations serialize on a per-handle promise
@@ -1819,7 +1820,7 @@ async function verifyCurrentGeneration(path, compression, expectedId, expectedEv
 	});
 	if (generation.meta.id !== expectedId) throw new Error(`current session generation contains id "${generation.meta.id}", expected "${expectedId}"`);
 	if (generation.events.length !== expectedEventCount) throw new Error(`current session generation contains ${generation.events.length} events, expected ${expectedEventCount}`);
-	Session.fromRestore(generation.meta.id, generation.events, generation.meta, generation.inheritedEventCount, "detached");
+	Session.fromRestore(generation.meta.id, generation.events, generation.meta, generation.inheritedEventCount, "detached", currentSessionMessageProjections);
 	assertCurrentAssistantStreams(generation.events);
 	return {
 		identity: snapshot.identity,

package/lib/worker.cjs

@@ -9,6 +9,320 @@ let node_util = require("node:util");
 let node_zlib = require("node:zlib");
 let node_module = require("node:module");
 let node_buffer = require("node:buffer");
+//#region ../../util/values/src/index.ts
+/**
+* Mark an unreachable closed-union branch.
+* @param value - impossible value; an unhandled typed variant fails at the call site.
+* @param context - optional switch-site label included in the failure message.
+* @returns never; a runtime value that escaped its type always throws.
+*/
+function assertNever(value, context) {
+	const rendered = JSON.stringify(value) ?? String(value);
+	throw new Error(`unreachable variant${context ? ` in ${context}` : ""}: ${rendered}`);
+}
+/** Whether a realm-owned intrinsic prototype is backed by its native constructor. */
+function hasIntrinsicConstructor(prototype, name) {
+	const constructor = Object.getOwnPropertyDescriptor(prototype, "constructor")?.value;
+	if (typeof constructor !== "function") return false;
+	try {
+		return constructor.name === name && constructor.prototype === prototype && Function.prototype.toString.call(constructor) === `function ${name}() { [native code] }`;
+	} catch {
+		return false;
+	}
+}
+/** Whether a candidate is one realm's intrinsic `Object.prototype`. */
+function isIntrinsicObjectPrototype(value) {
+	return Object.getPrototypeOf(value) === null && hasIntrinsicConstructor(value, "Object");
+}
+/** Whether an array uses one realm's intrinsic `Array.prototype`, not a subclass or forged prototype. */
+function hasPlainArrayPrototype(value) {
+	const prototype = Object.getPrototypeOf(value);
+	if (!Array.isArray(prototype) || !hasIntrinsicConstructor(prototype, "Array")) return false;
+	const objectPrototype = Object.getPrototypeOf(prototype);
+	return typeof objectPrototype === "object" && objectPrototype !== null && isIntrinsicObjectPrototype(objectPrototype);
+}
+/** Whether an object is a plain or null-prototype record from any JavaScript realm. */
+function hasPlainObjectPrototype(value) {
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === null || typeof prototype === "object" && isIntrinsicObjectPrototype(prototype);
+}
+/** Return every JSON-visible object key, or reject own data JSON would discard. */
+function enumerableStringKeys(value) {
+	const keys = Reflect.ownKeys(value);
+	if (keys.some((key) => typeof key !== "string" || !Object.prototype.propertyIsEnumerable.call(value, key))) return void 0;
+	return keys;
+}
+/** Validate lossless JSON iteratively, optionally materializing a detached snapshot. */
+function walkJsonValue(value, detach) {
+	const ancestors = /* @__PURE__ */ new Set();
+	let root;
+	const assign = (destination, item) => {
+		if (destination === void 0) return;
+		if (destination.kind === "root") root = item;
+		else if (destination.kind === "array") destination.target[destination.index] = item;
+		else Object.defineProperty(destination.target, destination.key, {
+			value: item,
+			enumerable: true,
+			configurable: true,
+			writable: true
+		});
+	};
+	const tasks = [{
+		kind: "visit",
+		value,
+		...detach ? { destination: { kind: "root" } } : {}
+	}];
+	for (let task = tasks.pop(); task !== void 0; task = tasks.pop()) {
+		if (task.kind === "leave") {
+			ancestors.delete(task.source);
+			continue;
+		}
+		if (task.kind === "array-item") {
+			if (!Object.prototype.hasOwnProperty.call(task.source, task.index)) return void 0;
+			tasks.push({
+				kind: "visit",
+				value: task.source[task.index],
+				...task.target === void 0 ? {} : { destination: {
+					kind: "array",
+					target: task.target,
+					index: task.index
+				} }
+			});
+			continue;
+		}
+		if (task.kind === "object-property") {
+			tasks.push({
+				kind: "visit",
+				value: task.source[task.key],
+				...task.target === void 0 ? {} : { destination: {
+					kind: "object",
+					target: task.target,
+					key: task.key
+				} }
+			});
+			continue;
+		}
+		const current = task.value;
+		if (current === null) {
+			assign(task.destination, null);
+			continue;
+		}
+		if (typeof current === "boolean" || typeof current === "string") {
+			assign(task.destination, current);
+			continue;
+		}
+		if (typeof current === "number") {
+			if (!Number.isFinite(current) || Object.is(current, -0)) return void 0;
+			assign(task.destination, current);
+			continue;
+		}
+		if (typeof current !== "object") return void 0;
+		if (ancestors.has(current)) return void 0;
+		if (Array.isArray(current)) {
+			if (!hasPlainArrayPrototype(current)) return void 0;
+			const length = current.length;
+			if (Reflect.ownKeys(current).length !== length + 1) return void 0;
+			const target = detach ? [] : void 0;
+			if (target !== void 0) assign(task.destination, target);
+			ancestors.add(current);
+			tasks.push({
+				kind: "leave",
+				source: current
+			});
+			for (let index = length - 1; index >= 0; index--) tasks.push({
+				kind: "array-item",
+				source: current,
+				index,
+				...target === void 0 ? {} : { target }
+			});
+			continue;
+		}
+		if (!hasPlainObjectPrototype(current)) return void 0;
+		const keys = enumerableStringKeys(current);
+		if (keys === void 0) return void 0;
+		const target = detach ? {} : void 0;
+		if (target !== void 0) assign(task.destination, target);
+		ancestors.add(current);
+		tasks.push({
+			kind: "leave",
+			source: current
+		});
+		for (let index = keys.length - 1; index >= 0; index--) {
+			const key = keys[index];
+			/* v8 ignore next -- the loop is bounded by the captured key count. */
+			if (key === void 0) return void 0;
+			tasks.push({
+				kind: "object-property",
+				source: current,
+				key,
+				...target === void 0 ? {} : { target }
+			});
+		}
+	}
+	return detach ? root : true;
+}
+/**
+* Validate and detach lossless JSON in one read per property.
+* @param value - candidate value to validate and detach.
+* @returns the detached snapshot, or `undefined` when the value is not losslessly JSON-serializable.
+*/
+function snapshotJsonValue(value) {
+	return walkJsonValue(value, true);
+}
+/**
+* Test the same lossless JSON rules as {@link snapshotJsonValue} without detaching the value.
+* @param value - candidate value to test.
+* @returns whether the value survives a JSON round trip without loss.
+*/
+function isJsonValue(value) {
+	return walkJsonValue(value, false) === true;
+}
+/**
+* Compare JSON-compatible values structurally.
+* @param a - one JSON-compatible value.
+* @param b - the other JSON-compatible value.
+* @returns whether both values contain the same JSON data.
+*/
+function deepEqualJson(a, b) {
+	if (a === b) return true;
+	if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+	if (Array.isArray(a) || Array.isArray(b)) {
+		if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+		return a.every((entry, index) => deepEqualJson(entry, b[index]));
+	}
+	const left = a;
+	const right = b;
+	const keys = Object.keys(left);
+	if (keys.length !== Object.keys(right).length) return false;
+	return keys.every((key) => key in right && deepEqualJson(left[key], right[key]));
+}
+/**
+* Deep-freeze an object graph in place while leaving live AbortSignal objects mutable.
+* @param value - value to freeze.
+* @returns the same value after every reachable enumerable child is frozen.
+*/
+function deepFreeze(value) {
+	const seen = /* @__PURE__ */ new WeakSet();
+	const pending = [{
+		kind: "visit",
+		node: value
+	}];
+	while (pending.length > 0) {
+		const task = pending.pop();
+		/* v8 ignore next -- the loop condition guarantees one pending task. */
+		if (task === void 0) continue;
+		if (task.kind === "property") {
+			pending.push({
+				kind: "visit",
+				node: task.source[task.key]
+			});
+			continue;
+		}
+		const node = task.node;
+		if (node === null || typeof node !== "object") continue;
+		if (node instanceof AbortSignal) continue;
+		if (seen.has(node)) continue;
+		seen.add(node);
+		Object.freeze(node);
+		const keys = Object.keys(node);
+		for (let index = keys.length - 1; index >= 0; index--) {
+			const key = keys[index];
+			/* v8 ignore next -- the loop is bounded by the captured key count. */
+			if (key === void 0) continue;
+			pending.push({
+				kind: "property",
+				source: node,
+				key
+			});
+		}
+	}
+	return value;
+}
+//#endregion
+//#region ../../compaction/compaction-image-offload/src/project-message.ts
+/**
+* Project selected image occurrences to immutable offloaded blocks.
+* @param message - message projected before this decision.
+* @param indexes - nonempty, strictly increasing depth-first image indexes.
+* @returns an immutable message with the same identity and selected images marked.
+* @throws when a selected occurrence is missing or already offloaded.
+*/
+function offloadMessageImages(message, indexes) {
+	let imageIndex = 0;
+	let selected = 0;
+	const visit = (blocks) => {
+		let next;
+		for (const [index, block] of blocks.entries()) {
+			let projected = block;
+			if (block.type === "image") {
+				if (imageIndex === indexes[selected]) {
+					if (block.offloaded === true) throw new Error(`image/offload: image index ${imageIndex} is already offloaded`);
+					projected = {
+						...block,
+						offloaded: true
+					};
+					selected += 1;
+				}
+				imageIndex += 1;
+			} else if (block.type === "tool-result") {
+				const content = visit(block.content);
+				if (content !== block.content) projected = {
+					...block,
+					content
+				};
+			}
+			if (projected !== block) next ??= blocks.slice(0, index);
+			next?.push(projected);
+		}
+		return next ?? blocks;
+	};
+	const content = visit(message.content);
+	if (selected !== indexes.length) throw new Error(`image/offload: image index ${indexes[selected]} does not exist`);
+	return deepFreeze({
+		...message,
+		content
+	});
+}
+//#endregion
+//#region ../../compaction/compaction-image-offload/src/projection.ts
+/** Whether a durable value is a JSON object. */
+function isRecord$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Whether a durable occurrence index or sequence is canonical. */
+function isIndex(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && !Object.is(value, -0);
+}
+//#endregion
+//#region ../session-format-catalog/src/message-projections.ts
+/** Pure first-party message interpreters for detached current-format replay, including browser readers. */
+/** Installed interpretation definitions; recovery listeners are mounted separately by their owning plugins. */
+const currentSessionMessageProjections = [{
+	type: "image/offload",
+	project(event, context) {
+		const data = event.data;
+		if (!isRecord$1(data) || Object.keys(data).length !== 1 || !Array.isArray(data["targets"]) || data["targets"].length === 0) throw new Error("image/offload: data must contain a nonempty targets array");
+		const messages = /* @__PURE__ */ new Map();
+		const nodes = new Set(context.nodes);
+		for (const target of data["targets"]) {
+			if (!isRecord$1(target) || Object.keys(target).length !== 2 || !isIndex(target["seq"]) || !Array.isArray(target["imageIndexes"]) || target["imageIndexes"].length === 0) throw new Error("image/offload: each target must contain a seq and nonempty imageIndexes");
+			const seq = target["seq"];
+			if (messages.has(seq)) throw new Error(`image/offload: duplicate target seq ${seq}`);
+			if (!nodes.has(seq)) throw new Error(`image/offload: target seq ${seq} is not a current surface node`);
+			const source = context.events[seq - context.baseSeq];
+			if (source?.type !== "user/message" && source?.type !== "tool/result") throw new Error(`image/offload: target seq ${seq} must be user/message or tool/result`);
+			let previous = -1;
+			for (const index of target["imageIndexes"]) {
+				if (!isIndex(index) || index <= previous) throw new Error("image/offload: imageIndexes must be strictly increasing non-negative safe integers");
+				previous = index;
+			}
+			const message = context.messages.get(seq) ?? (source.type === "user/message" ? source.data : source.data.message);
+			messages.set(seq, offloadMessageImages(message, target["imageIndexes"]));
+		}
+		return messages;
+	}
+}];
+//#endregion
 //#region ../../../vendor/cosmokit/src/misc.ts
 /** Return true when a value is `null` or `undefined`. */
 function isNullable(value) {
@@ -1390,8 +1704,8 @@ var Fiber = class {
 	*
 	* @param config — the new raw config; validated before anything restarts.
 	* @param noSave — hint for persistence hooks not to write the change back.
-	* @returns the update waterfall result; the default restart returns a promise.
-	* @throws when validation, an update listener, or the restarted plugin fails.
+	* @returns nothing; the restart runs behind the `internal/update` waterfall.
+	* @throws {ValidationError} when the new config fails validation.
 	*/
 	update(config, noSave = false) {
 		this.assertActive();
@@ -1403,7 +1717,7 @@ var Fiber = class {
 			return;
 		}
 		config = this._resolveConfig(config);
-		return this.context.waterfall(this, "internal/update", config, noSave, () => {
+		this.context.waterfall(this, "internal/update", config, noSave, () => {
 			this.config = config;
 			this._error = void 0;
 			return this.restart();
@@ -2083,236 +2397,6 @@ function brandNumber(value) {
 	return value;
 }
 //#endregion
-//#region ../../util/values/src/index.ts
-/**
-* Mark an unreachable closed-union branch.
-* @param value - impossible value; an unhandled typed variant fails at the call site.
-* @param context - optional switch-site label included in the failure message.
-* @returns never; a runtime value that escaped its type always throws.
-*/
-function assertNever(value, context) {
-	const rendered = JSON.stringify(value) ?? String(value);
-	throw new Error(`unreachable variant${context ? ` in ${context}` : ""}: ${rendered}`);
-}
-/** Whether a realm-owned intrinsic prototype is backed by its native constructor. */
-function hasIntrinsicConstructor(prototype, name) {
-	const constructor = Object.getOwnPropertyDescriptor(prototype, "constructor")?.value;
-	if (typeof constructor !== "function") return false;
-	try {
-		return constructor.name === name && constructor.prototype === prototype && Function.prototype.toString.call(constructor) === `function ${name}() { [native code] }`;
-	} catch {
-		return false;
-	}
-}
-/** Whether a candidate is one realm's intrinsic `Object.prototype`. */
-function isIntrinsicObjectPrototype(value) {
-	return Object.getPrototypeOf(value) === null && hasIntrinsicConstructor(value, "Object");
-}
-/** Whether an array uses one realm's intrinsic `Array.prototype`, not a subclass or forged prototype. */
-function hasPlainArrayPrototype(value) {
-	const prototype = Object.getPrototypeOf(value);
-	if (!Array.isArray(prototype) || !hasIntrinsicConstructor(prototype, "Array")) return false;
-	const objectPrototype = Object.getPrototypeOf(prototype);
-	return typeof objectPrototype === "object" && objectPrototype !== null && isIntrinsicObjectPrototype(objectPrototype);
-}
-/** Whether an object is a plain or null-prototype record from any JavaScript realm. */
-function hasPlainObjectPrototype(value) {
-	const prototype = Object.getPrototypeOf(value);
-	return prototype === null || typeof prototype === "object" && isIntrinsicObjectPrototype(prototype);
-}
-/** Return every JSON-visible object key, or reject own data JSON would discard. */
-function enumerableStringKeys(value) {
-	const keys = Reflect.ownKeys(value);
-	if (keys.some((key) => typeof key !== "string" || !Object.prototype.propertyIsEnumerable.call(value, key))) return void 0;
-	return keys;
-}
-/** Validate lossless JSON iteratively, optionally materializing a detached snapshot. */
-function walkJsonValue(value, detach) {
-	const ancestors = /* @__PURE__ */ new Set();
-	let root;
-	const assign = (destination, item) => {
-		if (destination === void 0) return;
-		if (destination.kind === "root") root = item;
-		else if (destination.kind === "array") destination.target[destination.index] = item;
-		else Object.defineProperty(destination.target, destination.key, {
-			value: item,
-			enumerable: true,
-			configurable: true,
-			writable: true
-		});
-	};
-	const tasks = [{
-		kind: "visit",
-		value,
-		...detach ? { destination: { kind: "root" } } : {}
-	}];
-	for (let task = tasks.pop(); task !== void 0; task = tasks.pop()) {
-		if (task.kind === "leave") {
-			ancestors.delete(task.source);
-			continue;
-		}
-		if (task.kind === "array-item") {
-			if (!Object.prototype.hasOwnProperty.call(task.source, task.index)) return void 0;
-			tasks.push({
-				kind: "visit",
-				value: task.source[task.index],
-				...task.target === void 0 ? {} : { destination: {
-					kind: "array",
-					target: task.target,
-					index: task.index
-				} }
-			});
-			continue;
-		}
-		if (task.kind === "object-property") {
-			tasks.push({
-				kind: "visit",
-				value: task.source[task.key],
-				...task.target === void 0 ? {} : { destination: {
-					kind: "object",
-					target: task.target,
-					key: task.key
-				} }
-			});
-			continue;
-		}
-		const current = task.value;
-		if (current === null) {
-			assign(task.destination, null);
-			continue;
-		}
-		if (typeof current === "boolean" || typeof current === "string") {
-			assign(task.destination, current);
-			continue;
-		}
-		if (typeof current === "number") {
-			if (!Number.isFinite(current) || Object.is(current, -0)) return void 0;
-			assign(task.destination, current);
-			continue;
-		}
-		if (typeof current !== "object") return void 0;
-		if (ancestors.has(current)) return void 0;
-		if (Array.isArray(current)) {
-			if (!hasPlainArrayPrototype(current)) return void 0;
-			const length = current.length;
-			if (Reflect.ownKeys(current).length !== length + 1) return void 0;
-			const target = detach ? [] : void 0;
-			if (target !== void 0) assign(task.destination, target);
-			ancestors.add(current);
-			tasks.push({
-				kind: "leave",
-				source: current
-			});
-			for (let index = length - 1; index >= 0; index--) tasks.push({
-				kind: "array-item",
-				source: current,
-				index,
-				...target === void 0 ? {} : { target }
-			});
-			continue;
-		}
-		if (!hasPlainObjectPrototype(current)) return void 0;
-		const keys = enumerableStringKeys(current);
-		if (keys === void 0) return void 0;
-		const target = detach ? {} : void 0;
-		if (target !== void 0) assign(task.destination, target);
-		ancestors.add(current);
-		tasks.push({
-			kind: "leave",
-			source: current
-		});
-		for (let index = keys.length - 1; index >= 0; index--) {
-			const key = keys[index];
-			/* v8 ignore next -- the loop is bounded by the captured key count. */
-			if (key === void 0) return void 0;
-			tasks.push({
-				kind: "object-property",
-				source: current,
-				key,
-				...target === void 0 ? {} : { target }
-			});
-		}
-	}
-	return detach ? root : true;
-}
-/**
-* Validate and detach lossless JSON in one read per property.
-* @param value - candidate value to validate and detach.
-* @returns the detached snapshot, or `undefined` when the value is not losslessly JSON-serializable.
-*/
-function snapshotJsonValue(value) {
-	return walkJsonValue(value, true);
-}
-/**
-* Test the same lossless JSON rules as {@link snapshotJsonValue} without detaching the value.
-* @param value - candidate value to test.
-* @returns whether the value survives a JSON round trip without loss.
-*/
-function isJsonValue(value) {
-	return walkJsonValue(value, false) === true;
-}
-/**
-* Compare JSON-compatible values structurally.
-* @param a - one JSON-compatible value.
-* @param b - the other JSON-compatible value.
-* @returns whether both values contain the same JSON data.
-*/
-function deepEqualJson(a, b) {
-	if (a === b) return true;
-	if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
-	if (Array.isArray(a) || Array.isArray(b)) {
-		if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
-		return a.every((entry, index) => deepEqualJson(entry, b[index]));
-	}
-	const left = a;
-	const right = b;
-	const keys = Object.keys(left);
-	if (keys.length !== Object.keys(right).length) return false;
-	return keys.every((key) => key in right && deepEqualJson(left[key], right[key]));
-}
-/**
-* Deep-freeze an object graph in place while leaving live AbortSignal objects mutable.
-* @param value - value to freeze.
-* @returns the same value after every reachable enumerable child is frozen.
-*/
-function deepFreeze(value) {
-	const seen = /* @__PURE__ */ new WeakSet();
-	const pending = [{
-		kind: "visit",
-		node: value
-	}];
-	while (pending.length > 0) {
-		const task = pending.pop();
-		/* v8 ignore next -- the loop condition guarantees one pending task. */
-		if (task === void 0) continue;
-		if (task.kind === "property") {
-			pending.push({
-				kind: "visit",
-				node: task.source[task.key]
-			});
-			continue;
-		}
-		const node = task.node;
-		if (node === null || typeof node !== "object") continue;
-		if (node instanceof AbortSignal) continue;
-		if (seen.has(node)) continue;
-		seen.add(node);
-		Object.freeze(node);
-		const keys = Object.keys(node);
-		for (let index = keys.length - 1; index >= 0; index--) {
-			const key = keys[index];
-			/* v8 ignore next -- the loop is bounded by the captured key count. */
-			if (key === void 0) continue;
-			pending.push({
-				kind: "property",
-				source: node,
-				key
-			});
-		}
-	}
-	return value;
-}
-//#endregion
 //#region ../../core/session/src/types.ts
 /**
 * Brand a string as a {@link SessionId}.
@@ -2383,6 +2467,7 @@ const KNOWN_SESSION_EVENT_TYPES = new Set([
 	"goal/change",
 	"hook/invoked",
 	"hook/result",
+	"image/offload",
 	"llm/retry",
 	"llm/retry-started",
 	"model/selection",
@@ -2420,6 +2505,8 @@ const KNOWN_SESSION_EVENT_TYPES = new Set([
 	"user/message",
 	"web/deepseek-search-llm-request"
 ]);
+/** Event types whose model-visible effects require an explicit pure interpreter. */
+const MESSAGE_PROJECTION_EVENT_TYPES = new Set(["image/offload"]);
 //#endregion
 //#region ../../core/session/src/surface.ts
 /** Runtime counterpart of the message-producing event union. */
@@ -2440,17 +2527,18 @@ function isSurfaceEligibleType(type) {
 /**
 * Project a single event into the LLM message it derives to, or null when it
 * produces none — a non-surface event (attempt, boundary, log-only record) or an
-* empty-content assistant/message (which exists only to host usage). This is
-* THE per-node projection rule: `Session.deriveMessages` folds it over the
-* live surface, external reconstructors and pure projections fold the same
-* function over a log prefix's surface to rebuild the exact messages any
-* request was built from. The returned message is the already frozen message
-* nested in the event wrapper and shared by delivery, durable history, and
-* model requests.
+* empty-content assistant/message (which exists only to host usage). A caller
+* reconstructing model input supplies the same prefix's `projectedMessages`
+* from {@link foldSurface}; without that map this function reads original
+* event content. Session instance methods apply the live projection. Messages
+* are immutable and unchanged content retains its durable identity.
 * @param event - the event to project.
+* @param projectedMessages - message projections from the same log prefix's surface fold.
 * @returns the derived message, or null when the event produces none.
 */
-function deriveEventMessage(event) {
+function deriveEventMessage(event, projectedMessages) {
+	const projected = projectedMessages?.get(event.seq);
+	if (projected !== void 0) return projected;
 	switch (event.type) {
 		case "user/message": return event.data;
 		case "system/message":
@@ -2495,7 +2583,10 @@ function validateSessionEventData(event, subject) {
 function createFoldState() {
 	return {
 		nodes: [],
-		replaceGeneration: 0
+		replaceGeneration: 0,
+		contentGeneration: 0,
+		projectedMessages: /* @__PURE__ */ new Map(),
+		projections: /* @__PURE__ */ new Set()
 	};
 }
 /** Whether a runtime value is a non-negative safe event sequence. */
@@ -2524,7 +2615,7 @@ function surfaceOpOf(event) {
 	return op;
 }
 /** Validate cited source-event seqs against prior log entries and the replacement range. */
-function assertProvenance(event, shadowedSeqs) {
+function assertSourceEventReferences(event, shadowedSeqs) {
 	const raw = event.sourceEventSeqs;
 	if (event.type === "assistant/message" && raw !== void 0) throw new Error("assistant/message embeds its source stream and cannot carry sourceEventSeqs");
 	const sources = /* @__PURE__ */ new Set();
@@ -2553,7 +2644,7 @@ function assertProvenance(event, shadowedSeqs) {
 function validateSurfaceMetadata(event) {
 	const op = surfaceOpOf(event);
 	if (op !== void 0 && op !== "append" && (op.startSeq >= event.seq || op.endSeq >= event.seq)) throw new Error(`surface replace at seq ${event.seq}: startSeq and endSeq must reference earlier events`);
-	if (op !== void 0) assertProvenance(event, []);
+	if (op !== void 0) assertSourceEventReferences(event, []);
 	return op;
 }
 /** Locate one replacement range without mutating the current fold state. */
@@ -2626,16 +2717,28 @@ function assertSystemHeadRewrite(event, state, startIdx, shadowedSeqs, events, b
 	if (event.type !== "system/message" || shadowedSeqs.length !== 1) throw new Error("surface replace: node 0 holds the system prompt and may be rewritten only by a system/message over exactly that node");
 }
 /** Validate one event at its replay boundary and prepare its atomic fold transition. */
-function planSurfaceEvent(state, event, expectedSeq, events, baseSeq) {
+function planSurfaceEvent(state, event, expectedSeq, events, baseSeq, projections) {
 	if (event.seq !== expectedSeq) throw new Error(`session event seq ${event.seq} is not contiguous; expected ${expectedSeq}`);
 	const surfaceOp = validateSurfaceMetadata(event);
+	const projection = projections.find((item) => item.type === event.type);
+	if (projection !== void 0) return {
+		kind: "project",
+		projection,
+		messages: projection.project(event, {
+			nodes: state.nodes,
+			events,
+			baseSeq,
+			messages: state.projectedMessages
+		})
+	};
+	if (MESSAGE_PROJECTION_EVENT_TYPES.has(event.type)) throw new Error(`session event "${event.type}" requires a message projection; load its owning plugin or supply its projection definition`);
 	if (surfaceOp === void 0) return;
 	if (surfaceOp === "append") return {
 		kind: "append",
 		seq: event.seq
 	};
 	const range = replacementRange(state, surfaceOp);
-	assertProvenance(event, range.shadowedSeqs);
+	assertSourceEventReferences(event, range.shadowedSeqs);
 	assertToolResultRewrite(event, range.shadowedSeqs, events, baseSeq);
 	assertSystemHeadRewrite(event, state, range.startIdx, range.shadowedSeqs, events, baseSeq);
 	return {
@@ -2647,8 +2750,8 @@ function planSurfaceEvent(state, event, expectedSeq, events, baseSeq) {
 	};
 }
 /** Apply one event and return replacement metadata only when one occurred. */
-function applySurfaceEvent(state, event, expectedSeq, events, baseSeq) {
-	return applySurfacePlan(state, planSurfaceEvent(state, event, expectedSeq, events, baseSeq));
+function applySurfaceEvent(state, event, expectedSeq, events, baseSeq, projections) {
+	return applySurfacePlan(state, planSurfaceEvent(state, event, expectedSeq, events, baseSeq, projections));
 }
 /** Commit one previously validated surface transition. */
 function applySurfacePlan(state, plan) {
@@ -2656,6 +2759,11 @@ function applySurfacePlan(state, plan) {
 	else if (plan?.kind === "replace") {
 		state.nodes.splice(plan.startIdx, plan.endIdx - plan.startIdx + 1, plan.seq);
 		state.replaceGeneration += 1;
+		state.contentGeneration += 1;
+	} else if (plan?.kind === "project") {
+		for (const [seq, message] of plan.messages) state.projectedMessages.set(seq, message);
+		state.projections.add(plan.projection);
+		state.contentGeneration += 1;
 	}
 	if (plan?.kind !== "replace") return;
 	return {
@@ -2669,6 +2777,7 @@ function applySurfacePlan(state, plan) {
 var SurfaceManager = class {
 	log;
 	baseSeq;
+	projections;
 	/** Shared transition state; replacement history is not retained. */
 	_state = createFoldState();
 	/** Last processed absolute seq. */
@@ -2678,10 +2787,12 @@ var SurfaceManager = class {
 	/**
 	* @param log - Contiguous complete log or loaded event window.
 	* @param baseSeq - Absolute sequence of the window's first event.
+	* @param projections - live borrowed definitions; removing a used definition invalidates further reads.
 	*/
-	constructor(log, baseSeq = SessionLogOffset(0)) {
+	constructor(log, baseSeq = SessionLogOffset(0), projections = []) {
 		this.log = log;
 		this.baseSeq = baseSeq;
+		this.projections = projections;
 		this._lastProcessedSeq = baseSeq === 0 ? -1 : SessionSeq(baseSeq - 1);
 	}
 	/**
@@ -2689,21 +2800,40 @@ var SurfaceManager = class {
 	* @param event - candidate event that has not entered the log yet.
 	*/
 	validateNext(event) {
+		this._assertProjections();
 		if (this._lastProcessedSeq < this.baseSeq + this.log.length - 1) this._processDelta();
 		const expectedSeq = SessionSeq(this.baseSeq + this.log.length);
 		this._pendingPlan = {
 			event,
 			expectedSeq,
-			plan: planSurfaceEvent(this._state, event, expectedSeq, this.log, this.baseSeq)
+			plan: planSurfaceEvent(this._state, event, expectedSeq, this.log, this.baseSeq, this.projections)
 		};
 	}
 	/** Monotonic count of folded positional replacements. */
 	get replaceGeneration() {
+		this._assertProjections();
 		if (this._lastProcessedSeq < this.baseSeq + this.log.length - 1) this._processDelta();
 		return this._state.replaceGeneration;
 	}
+	/** Monotonic count of committed changes to existing model-visible content. */
+	get contentGeneration() {
+		this._assertProjections();
+		if (this._lastProcessedSeq < this.baseSeq + this.log.length - 1) this._processDelta();
+		return this._state.contentGeneration;
+	}
+	/**
+	* Project one message with every committed message projection applied.
+	* @param event - message-producing or log-only event.
+	* @returns its immutable projected message, or null when it produces none.
+	*/
+	deriveEventMessage(event) {
+		this._assertProjections();
+		if (this._lastProcessedSeq < this.baseSeq + this.log.length - 1) this._processDelta();
+		return deriveEventMessage(event, this._state.projectedMessages);
+	}
 	/** Surface event sequences in model-visible order. */
 	get nodes() {
+		this._assertProjections();
 		if (this._lastProcessedSeq < this.baseSeq + this.log.length - 1) this._processDelta();
 		return this._state.nodes;
 	}
@@ -2715,11 +2845,18 @@ var SurfaceManager = class {
 			const event = this.log[index];
 			const pending = this._pendingPlan;
 			if (pending?.event === event && pending.expectedSeq === seq) applySurfacePlan(this._state, pending.plan);
-			else applySurfaceEvent(this._state, event, SessionSeq(seq), this.log, this.baseSeq);
+			else applySurfaceEvent(this._state, event, SessionSeq(seq), this.log, this.baseSeq, this.projections);
 			if (pending !== void 0 && pending.expectedSeq <= seq) this._pendingPlan = void 0;
 			this._lastProcessedSeq = SessionSeq(seq);
 		}
 	}
+	/** Cached messages cannot outlive the definitions that interpreted their log. */
+	_assertProjections() {
+		const candidate = this._pendingPlan;
+		const pending = candidate !== void 0 && this.log[candidate.expectedSeq - this.baseSeq] === candidate.event ? candidate.plan : void 0;
+		const required = pending?.kind === "project" ? [...this._state.projections, pending.projection] : this._state.projections;
+		for (const projection of required) if (!this.projections.includes(projection)) throw new Error(`session message projection "${projection.type}" was removed or replaced; restore the session with its owning plugin`);
+	}
 };
 //#endregion
 //#region ../../typert/protocol/src/remote-error.ts
@@ -3719,13 +3856,15 @@ function failureSnapshot(value) {
 		const status = candidate.status;
 		const providerRetryAfterMs = candidate.providerRetryAfterMs;
 		const requestId = candidate.requestId;
-		if (typeof message !== "string" || message.length === 0 || typeof code !== "string" || code.length === 0 || status !== void 0 && (!Number.isInteger(status) || status < 100 || status > 599) || providerRetryAfterMs !== void 0 && (!Number.isFinite(providerRetryAfterMs) || providerRetryAfterMs <= 0) || requestId !== void 0 && (typeof requestId !== "string" || requestId.length === 0)) return void 0;
+		const offloadImages = candidate.offloadImages;
+		if (typeof message !== "string" || message.length === 0 || typeof code !== "string" || code.length === 0 || status !== void 0 && (!Number.isInteger(status) || status < 100 || status > 599) || providerRetryAfterMs !== void 0 && (!Number.isFinite(providerRetryAfterMs) || providerRetryAfterMs <= 0) || requestId !== void 0 && (typeof requestId !== "string" || requestId.length === 0) || offloadImages !== void 0 && (!Number.isSafeInteger(offloadImages) || offloadImages <= 0)) return void 0;
 		return Object.freeze({
 			message,
 			code,
 			...status === void 0 ? {} : { status },
 			...providerRetryAfterMs === void 0 ? {} : { providerRetryAfterMs },
-			...requestId === void 0 ? {} : { requestId }
+			...requestId === void 0 ? {} : { requestId },
+			...offloadImages === void 0 ? {} : { offloadImages }
 		});
 	} catch (_sdkFailureGetter) {
 		return;
@@ -4414,7 +4553,8 @@ var LlmError = class extends HarnessError {
 			code,
 			...options?.status === void 0 ? {} : { status: options.status },
 			...options?.providerRetryAfterMs === void 0 ? {} : { providerRetryAfterMs: options.providerRetryAfterMs },
-			...options?.requestId === void 0 ? {} : { requestId: options.requestId }
+			...options?.requestId === void 0 ? {} : { requestId: options.requestId },
+			...options?.offloadImages === void 0 ? {} : { offloadImages: options.offloadImages }
 		});
 	}
 };
@@ -5291,7 +5431,7 @@ const attachments = /* @__PURE__ */ new WeakMap();
 var Session = class Session {
 	log = [];
 	/** Single incremental owner of surface acceptance and projection state. */
-	surfaceManager = new SurfaceManager(this.log);
+	surfaceManager;
 	/** The ordered surface over this session's event log. */
 	get surface() {
 		return this.surfaceManager;
@@ -5342,10 +5482,12 @@ var Session = class Session {
 	* @param seed - optional borrowed replay or fork events.
 	* @param header - optional borrowed storage metadata.
 	* @param inheritedEventCount - exact fork-inherited prefix length for a seeded header.
+	* @param projections - pure interpreters for plugin-owned message changes.
 	* @returns a detached session.
+	* @throws when a seed event requires a missing message interpreter or fails validation.
 	*/
-	static create(id, seed, header, inheritedEventCount) {
-		return new Session(id, seed, header, "snapshot", inheritedEventCount);
+	static create(id, seed, header, inheritedEventCount, projections) {
+		return new Session(id, seed, header, "snapshot", inheritedEventCount, projections);
 	}
 	/**
 	* Restore a detached session by adopting an independently owned or deeply frozen seed.
@@ -5358,12 +5500,15 @@ var Session = class Session {
 	* @param header - independently owned storage metadata.
 	* @param inheritedEventCount - exact fork-inherited prefix length decoded from storage.
 	* @param eventState - aliasing state carried from the operation that produced the seed.
+	* @param projections - pure interpreters for plugin-owned message changes.
 	* @returns a restored detached session.
+	* @throws when a seed event requires a missing message interpreter or fails validation.
 	*/
-	static fromRestore(id, seed, header, inheritedEventCount, eventState) {
-		return new Session(id, seed, header, eventState, inheritedEventCount);
+	static fromRestore(id, seed, header, inheritedEventCount, eventState, projections) {
+		return new Session(id, seed, header, eventState, inheritedEventCount, projections);
 	}
-	constructor(id, seed, header, mode = "snapshot", suppliedInheritedEventCount) {
+	constructor(id, seed, header, mode = "snapshot", suppliedInheritedEventCount, projections = []) {
+		this.surfaceManager = new SurfaceManager(this.log, SessionLogOffset(0), projections);
 		const restoredHeader = mode === "snapshot" ? void 0 : validateRestoredSessionHeader(id, header);
 		if (seed !== void 0) for (const [index, source] of seed.entries()) {
 			const snapshot = mode === "snapshot" ? snapshotJsonValue(source) : source;
@@ -5393,6 +5538,8 @@ var Session = class Session {
 	eventsSnapshot;
 	/**
 	* Return the immutable event stored at one exact sequence number.
+	* @deprecated Existing logic may remain unmigrated for now, but new calls are prohibited.
+	* See the [Agent Note](../../../../.agents/notes/implemented/architecture/2026-09-09-deprecate-synchronous-session-event-reads.md).
 	* @param seq - event sequence number.
 	* @returns the accepted event, or undefined when the log does not contain it.
 	*/
@@ -5403,6 +5550,8 @@ var Session = class Session {
 	* Materialize an immutable snapshot of a half-open event sequence range.
 	* A full current snapshot is reused until the next append; every previously
 	* returned snapshot remains stable after later appends.
+	* @deprecated Existing logic may remain unmigrated for now, but new calls are prohibited.
+	* See the [Agent Note](../../../../.agents/notes/implemented/architecture/2026-09-09-deprecate-synchronous-session-event-reads.md).
 	* @param fromSeq - non-negative inclusive sequence number; defaults to the log start.
 	* @param toSeqExclusive - non-negative exclusive sequence number; defaults to the current end.
 	* @returns a frozen array of the selected deeply frozen events.
@@ -5416,6 +5565,8 @@ var Session = class Session {
 	}
 	/**
 	* Return this Session's events after its fork-inherited prefix.
+	* @deprecated Existing logic may remain unmigrated for now, but new calls are prohibited.
+	* See the [Agent Note](../../../../.agents/notes/implemented/architecture/2026-09-09-deprecate-synchronous-session-event-reads.md).
 	* @returns a fresh array containing child-owned events in log order.
 	*/
 	ownEvents() {
@@ -5549,7 +5700,7 @@ var Session = class Session {
 	derived = [];
 	/** Surface position (nodes projected) the cache has reached. */
 	derivedNodes = 0;
-	/** {@link SurfaceManager.replaceGeneration} the cache was built under. */
+	/** {@link SurfaceManager.contentGeneration} the cache was built under. */
 	derivedGeneration = 0;
 	/**
 	* Derive the LLM message history by walking the ordered sequences of
@@ -5558,21 +5709,21 @@ var Session = class Session {
 	* append records its `surfaceOp`, so a raw event with no marker (a chunk, a
 	* turn boundary) is correctly absent, and a compaction `replace` deletes the
 	* shadowed nodes from the derivation. The projection rules are
-	* {@link deriveEventMessage}, folded per node.
+	* {@link deriveEventMessage}, with logged message projections applied
+	* without changing node membership or message identity.
 	*
-	* CACHED: each surface node is projected exactly once, when first seen — a
-	* call costs O(new nodes), and a surface rewrite (a `replace`;
-	* {@link SessionSurface.replaceGeneration}) rebuilds. The returned array is
+	* CACHED: pure tail growth costs O(new nodes); a replacement or message projection
+	* ({@link SessionSurface.contentGeneration}) rebuilds. The returned array is
 	* a fresh snapshot per call (later appends never grow an array a caller
 	* already holds); the `Message` objects in it are SHARED and **deep-frozen**.
-	* Their content reuses the already frozen durable event data, so the cache
-	* needs no second deep clone and consumers still cannot mutate the log.
+	* Unchanged content reuses frozen event data; projected blocks are frozen
+	* derived copies. Consumers cannot mutate the log through either form.
 	* @returns a fresh array of the shared, frozen derived history.
 	*/
 	deriveMessages() {
 		const surface = this.surface;
 		const nodes = surface.nodes;
-		const generation = surface.replaceGeneration;
+		const generation = surface.contentGeneration;
 		if (generation !== this.derivedGeneration) {
 			this.derived = [];
 			this.derivedNodes = 0;
@@ -5586,13 +5737,13 @@ var Session = class Session {
 		return [...this.derived];
 	}
 	/**
-	* Instance face of the pure per-node `deriveEventMessage` export from
-	* `surface.ts`.
+	* Project one event with all committed message projections applied.
+	* The original durable event remains unchanged.
 	* @param event - the event to project.
 	* @returns the derived message, or null when the event produces none.
 	*/
 	deriveEventMessage(event) {
-		return deriveEventMessage(event);
+		return this.surfaceManager.deriveEventMessage(event);
 	}
 };
 //#endregion
@@ -6183,7 +6334,7 @@ function validateInstalledCurrentSessionHeader(header) {
 */
 function validateInstalledCurrentSessionArtifact(artifact) {
 	if (artifact.header.version !== 3) throw new Error(`installed Session format is v3, got v${artifact.header.version}`);
-	Session.fromRestore(SessionId(artifact.header.id), artifact.events, artifact.header, SessionLogOffset(artifact.inheritedEventCount), "detached");
+	Session.fromRestore(SessionId(artifact.header.id), artifact.events, artifact.header, SessionLogOffset(artifact.inheritedEventCount), "detached", currentSessionMessageProjections);
 }
 //#endregion
 //#region ../session-format-v0-to-v1/src/dispositions.ts
@@ -7657,11 +7808,11 @@ function assertReleasedV1Header(header) {
 * @param record - exact event envelope.
 * @param seq - event position used for earlier-reference checks.
 * @param type - surface event type used in diagnostics.
-* @param assistantSources - whether this generation admits empty Assistant chunk provenance.
+* @param assistantSources - whether this generation admits empty Assistant chunk references.
 */
 function assertReleasedSurfaceMetadata(record, seq, type, assistantSources) {
 	const sources = record["sourceEventSeqs"];
-	if (type === "assistant/message" && sources !== void 0 && assistantSources === "forbid-assistant") throw new SessionFormatError(`assistant/message ${seq} retains obsolete chunk provenance`);
+	if (type === "assistant/message" && sources !== void 0 && assistantSources === "forbid-assistant") throw new SessionFormatError(`assistant/message ${seq} retains obsolete chunk references`);
 	if (sources !== void 0) {
 		if (!Array.isArray(sources)) throw new SessionFormatError(`${type} ${seq} sourceEventSeqs must be an array`);
 		const seen = /* @__PURE__ */ new Set();
@@ -7977,6 +8128,7 @@ function decodeSeqRanges$1(value, maxEntries) {
 }
 //#endregion
 //#region ../session-format-v0-to-v1/src/migration.ts
+const LEGACY_ASSISTANT_SOURCE_KEY = ["pro", "venance"].join("");
 /** Identity format edge that promotes released v0 into released v1. */
 const sessionFormatV0ToV1 = defineSessionFormatMigration({
 	name: "@deepseek-ai/dsh-session-format-v0-to-v1",
@@ -8300,9 +8452,12 @@ function normalizeLegacyMessage(event, sessionId, messageIds) {
 				}
 			};
 		case "assistant/message": {
-			if (Object.hasOwn(data, "message") || !Object.hasOwn(data, "content") || !Object.hasOwn(data, "provenance")) return event;
-			const { content, provenance, ...eventData } = data;
-			const source = releasedV0Record(provenance, `assistant/message ${event.seq} provenance`);
+			if (Object.hasOwn(data, "message") || !Object.hasOwn(data, "content") || !Object.hasOwn(data, LEGACY_ASSISTANT_SOURCE_KEY)) return event;
+			const content = data["content"];
+			const eventData = { ...data };
+			delete eventData["content"];
+			const source = releasedV0Record(eventData[LEGACY_ASSISTANT_SOURCE_KEY], `assistant/message ${event.seq} legacy source`);
+			Reflect.deleteProperty(eventData, LEGACY_ASSISTANT_SOURCE_KEY);
 			return {
 				...event,
 				data: {
@@ -8878,7 +9033,7 @@ const releasedV2SessionFormatCodec = Object.freeze({
 		return encodeHeader(header, inheritedEventCount);
 	},
 	encodeEvent(event) {
-		return encodeProvenance(event);
+		return encodeSourceEventRanges(event);
 	}
 });
 function decodePhysicalHeader(value) {
@@ -8986,7 +9141,7 @@ function encodeHeader(header, inheritedEventCount) {
 		...header.agentPreset === void 0 ? {} : { agentPreset: header.agentPreset }
 	};
 }
-function encodeProvenance(event) {
+function encodeSourceEventRanges(event) {
 	if (event.sourceEventSeqs === void 0) return event;
 	return {
 		...event,
@@ -9229,7 +9384,7 @@ function transformMessage(state, event, context) {
 		emitSource(state, messageEvent(event, attemptGroup(turn, step)), context);
 		return;
 	}
-	if (pending === void 0 || !matchesChunkSources(pending.group, sources)) throw refusal(`assistant/message ${event.seq} chunk provenance is not one complete ordered attempt`);
+	if (pending === void 0 || !matchesChunkSources(pending.group, sources)) throw refusal(`assistant/message ${event.seq} chunk references are not one complete ordered attempt`);
 	assertAttemptCut(state, pending.group, event.seq);
 	pending.group.terminal = true;
 	flushBuffered(state, pending, context);
@@ -10053,7 +10208,7 @@ function relationshipEvent(event) {
 //#endregion
 //#region ../session-format-v2-to-v3/src/codec.ts
 /** V3 framing with hard structural admission and recoverable canonical event validation. */
-/** V3 codec validates structural rows before recovery and logical envelopes after provenance decoding. */
+/** V3 codec validates structural rows before recovery and logical envelopes after source-event range decoding. */
 const releasedV3SessionFormatCodec = Object.freeze({
 	version: 3,
 	decodeHeader(value) {
@@ -10119,7 +10274,7 @@ const releasedV3SessionFormatCodec = Object.freeze({
 });
 /**
 * Validate owned V3 admission rules before a scanner or codec can discard a recoverable tail.
-* This checks only identified structural payloads; physical provenance still belongs to decoding.
+* This checks only identified structural payloads; physical source-event ranges still belong to decoding.
 * @param row - parsed physical row, before envelope or compressed-range decoding.
 */
 function assertV3RowAdmission(row) {
@@ -11289,7 +11444,7 @@ async function verifyCurrentGeneration(path, compression, expectedId, expectedEv
 	});
 	if (generation.meta.id !== expectedId) throw new Error(`current session generation contains id "${generation.meta.id}", expected "${expectedId}"`);
 	if (generation.events.length !== expectedEventCount) throw new Error(`current session generation contains ${generation.events.length} events, expected ${expectedEventCount}`);
-	Session.fromRestore(generation.meta.id, generation.events, generation.meta, generation.inheritedEventCount, "detached");
+	Session.fromRestore(generation.meta.id, generation.events, generation.meta, generation.inheritedEventCount, "detached", currentSessionMessageProjections);
 	assertCurrentAssistantStreams(generation.events);
 	return {
 		identity: snapshot.identity,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-persistence-jsonl",
   "description": "JSONL durable session persistence backend for the DeepSeek Harness",
-  "version": "0.1.5-rc.1",
+  "version": "0.1.6-alpha.1",
   "publishConfig": {
     "access": "public"
   },
@@ -28,23 +28,23 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-session": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-session": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.6-alpha.1",
     "@deepseek-ai/cordis": "^4.0.2"
   },
   "dependencies": {
     "koffi": "^3.1.0",
-    "@deepseek-ai/dsh-llm": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-session-format": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-session-format-catalog": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-session-format": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-session-format-catalog": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-session-format-v2-to-v3": "^0.1.6-alpha.1",
     "@deepseek-ai/node-addon-system": "^0.1.2",
-    "@deepseek-ai/schemastery": "^3.18.2",
-    "@deepseek-ai/dsh-session-format-v2-to-v3": "^0.1.5-rc.1"
+    "@deepseek-ai/schemastery": "^3.18.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-session": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-session-format-v0-to-v1": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-session": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-session-format-v0-to-v1": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.6-alpha.1",
     "@deepseek-ai/cordis": "^4.0.2"
   }
 }