@artenx/dshb 0.1.30 → 0.1.32

package/lib/{session-sync-C0uoizyB.js → session-sync-CIqjuWkh.js}

@@ -2,14 +2,14 @@ import { compareSyncRevision } from "./core/sync/revision.js";
 import { isNonNegativeSafeInteger, isRecord as isRecord$1, syncRecordKey, syncWorkspaceKey } from "./core/sync/model.js";
 import "./core/workspace-instructions.js";
 import { i as deepFreeze, r as brandString } from "./lib-gdtU_WKT.js";
+import { MAX_SESSION_OBJECT_INLINE_BYTES, MAX_SESSION_OBJECT_STREAM_BYTES, MAX_SYNC_TRANSFER_BYTES } from "./core/sync/protocol.js";
 import { SyncSessionJournalStore } from "./core/sync/session-journal.js";
-import { MAX_SYNC_TRANSFER_BYTES } from "./core/sync/protocol.js";
 import { homedir, tmpdir } from "node:os";
-import { chmodSync, closeSync, constants, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { chmodSync, closeSync, constants, createReadStream, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, normalize, posix, resolve } from "node:path";
 import { createHash, randomBytes } from "node:crypto";
 import "@deepseek-ai/cordis";
-import { lstat, mkdir, open, realpath, unlink } from "node:fs/promises";
+import { access, lstat, mkdir, open, readdir, realpath, rename, stat, unlink } from "node:fs/promises";
 //#region ../../node_modules/@deepseek-ai/dsh-session/lib/index.js
 /**
 * Brand a string as a {@link SessionId}.
@@ -488,6 +488,7 @@ var SyncSessionExportCacheStore = class {
 //#region src/core/sync/session-sync.ts
 const SESSION_READ_PAGE_SIZE = 256;
 const MAX_SYNC_SESSIONS = 1e4;
+const MAX_SESSION_EXPORT_ENTRY_BYTES = 100663296;
 const MAX_MANIFEST_PAYLOAD_CACHE_BYTES = 4194304;
 const MAX_MANIFEST_PAYLOAD_CACHE_COUNT = 8;
 const SESSION_EXPORT_CACHE_VERSION = 1;
@@ -496,6 +497,156 @@ const SPILL_ARTIFACT_META_KEY = "@deepseek-ai/dsh-spill";
 const LEGACY_LOCAL_SPILL_HINT = "Use read with offset/limit, or grep this path to search within it.";
 const LEGACY_LOCAL_SPILL_MARKER = "Full formatted result stored at: ";
 const LEGACY_LOCAL_SPILL_SUFFIX = `. ${LEGACY_LOCAL_SPILL_HINT})`;
+var SyncSessionObjectInbox = class {
+	root;
+	constructor(home) {
+		this.root = join(home ?? process.env.DSH_HOME ?? homedir(), "dshb", "sync-objects");
+	}
+	get path() {
+		return this.root;
+	}
+	fileFor(digest) {
+		const match = /^sha256:([a-f0-9]{64})$/.exec(digest);
+		if (!match) return void 0;
+		return join(this.root, match[1]);
+	}
+	/**
+	* 打开一个收件箱写入器：逐帧流式写盘 + 增量摘要校验，内存 O(帧)。
+	* commit() 校验字节数与 digest 后原子重命名；abort() 清理临时文件。
+	*/
+	async writerFor(digest, expectedBytes) {
+		const file = this.fileFor(digest);
+		if (!file) throw new SyncSessionError("object-invalid", "session object digest is invalid");
+		await mkdir(this.root, {
+			recursive: true,
+			mode: 448
+		});
+		const temporary = `${file}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
+		const hash = createHash("sha256");
+		const handle = await open(temporary, "wx", 384);
+		let written = 0;
+		let closed = false;
+		const closeHandle = async () => {
+			if (closed) return;
+			closed = true;
+			await handle.close().catch(() => {});
+		};
+		return {
+			async write(chunk) {
+				if (closed) throw new SyncSessionError("object-invalid", "session object writer is closed");
+				written += chunk.byteLength;
+				if (written > expectedBytes) throw new SyncSessionError("object-integrity", "session object stream exceeds declared bytes");
+				hash.update(chunk);
+				let offset = 0;
+				while (offset < chunk.byteLength) {
+					const { bytesWritten } = await handle.write(chunk, offset, chunk.byteLength - offset, null);
+					if (bytesWritten <= 0) throw new SyncSessionError("object-integrity", "session object stream write made no progress");
+					offset += bytesWritten;
+				}
+			},
+			async commit() {
+				if (written !== expectedBytes || `sha256:${hash.digest("hex")}` !== digest) {
+					await closeHandle();
+					try {
+						await unlink(temporary);
+					} catch {}
+					throw new SyncSessionError("object-integrity", "session object stream digest mismatch");
+				}
+				await handle.sync();
+				await closeHandle();
+				await rename(temporary, file);
+			},
+			async abort() {
+				await closeHandle();
+				try {
+					await unlink(temporary);
+				} catch {}
+			}
+		};
+	}
+	/** 便捷写入：把对象流整段写进收件箱（测试与小对象用）。 */
+	async write(digest, bytes, stream) {
+		const writer = await this.writerFor(digest, bytes);
+		try {
+			for await (const chunk of stream) {
+				if (!(chunk instanceof Uint8Array) || chunk.byteLength === 0) throw new SyncSessionError("object-invalid", "session object stream contains an invalid chunk");
+				await writer.write(chunk);
+			}
+			await writer.commit();
+		} catch (error) {
+			await writer.abort();
+			throw error;
+		}
+	}
+	/** 打开收件箱文件的只读流（apply 水合用）；调用方负责消费完毕。 */
+	async read(digest) {
+		const file = this.fileFor(digest);
+		if (!file) throw new SyncSessionError("object-missing", "session object is not in the inbox");
+		try {
+			await access(file);
+		} catch {
+			throw new SyncSessionError("object-missing", "session object is not in the inbox");
+		}
+		return createReadStream(file);
+	}
+	async delete(digest) {
+		const file = this.fileFor(digest);
+		if (!file) return;
+		try {
+			await unlink(file);
+		} catch {}
+	}
+	/** TTL 清扫：删除超过 maxAgeMs 未修改的孤儿文件。 */
+	async sweep(maxAgeMs = 864e5) {
+		let entries;
+		try {
+			entries = await readdir(this.root, { withFileTypes: true });
+		} catch {
+			return 0;
+		}
+		const cutoff = Date.now() - maxAgeMs;
+		let removed = 0;
+		for (const entry of entries) {
+			if (!entry.isFile() || !/^[a-f0-9]{64}(\.|$)/.test(entry.name)) continue;
+			const file = join(this.root, entry.name);
+			try {
+				if ((await stat(file)).mtimeMs < cutoff) {
+					await unlink(file);
+					removed += 1;
+				}
+			} catch {}
+		}
+		return removed;
+	}
+};
+/**
+* 导出期附件对象缓存：跨会话去重同一附件（同 id 只读一次存储、只算一次摘要）。
+* 附件对象携带 base64 数据，若整轮导出无上限持有（此前是普通 Map），多图会话的
+* 首次同步会把堆吃满（桌面端 OOM 崩溃的直接推手之一）。这里按原始字节数做
+* LRU 上限，超限淘汰最早条目；被淘汰的附件在后续会话中按 cache miss 重新读取。
+*/
+const MAX_EXPORT_OBJECT_CACHE_BYTES = 67108864;
+var ExportObjectCache = class {
+	entries = /* @__PURE__ */ new Map();
+	bytes = 0;
+	get(key) {
+		return this.entries.get(key);
+	}
+	set(key, entry) {
+		const existing = this.entries.get(key);
+		if (existing) this.bytes -= existing.object.bytes;
+		this.entries.delete(key);
+		this.entries.set(key, entry);
+		this.bytes += entry.object.bytes;
+		while (this.bytes > MAX_EXPORT_OBJECT_CACHE_BYTES && this.entries.size > 1) {
+			const oldest = this.entries.keys().next().value;
+			if (oldest === void 0) break;
+			const removed = this.entries.get(oldest);
+			this.entries.delete(oldest);
+			if (removed) this.bytes -= removed.object.bytes;
+		}
+	}
+};
 var SyncSessionError = class extends Error {
 	code;
 	constructor(code, message, cause) {
@@ -668,16 +819,30 @@ async function writeLocalSpillTransfer(root, input) {
 	return ref;
 }
 async function saveSpillTransfer(store, input) {
-	if (store.saveTextStream) return store.saveTextStream({
-		owner: input.owner,
-		source: input.source,
-		suggestedName: input.suggestedName,
-		transferId: input.transferId,
-		bytes: input.bytes,
-		digest: input.digest,
-		content: oneChunk(input.data)
+	if (store.saveTextStream) {
+		if (input.content !== void 0) return store.saveTextStream({
+			owner: input.owner,
+			source: input.source,
+			suggestedName: input.suggestedName,
+			transferId: input.transferId,
+			bytes: input.bytes,
+			digest: input.digest,
+			content: input.content
+		});
+		return store.saveTextStream({
+			owner: input.owner,
+			source: input.source,
+			suggestedName: input.suggestedName,
+			transferId: input.transferId,
+			bytes: input.bytes,
+			digest: input.digest,
+			content: oneChunk(input.data)
+		});
+	}
+	if (typeof store.root === "string" && input.content === void 0 && input.data !== void 0) return writeLocalSpillTransfer(store.root, {
+		...input,
+		data: input.data
 	});
-	if (typeof store.root === "string") return writeLocalSpillTransfer(store.root, input);
 	throw new SyncSessionError("spill-transfer-unavailable", "目标实例的 spill provider 不支持安全写入");
 }
 function canonicalJson(value) {
@@ -865,30 +1030,43 @@ function sessionEventDigest(header, inheritedEventCount, events, workspace, inst
 		return output;
 	};
 	const { id: _id, cwd: _cwd, parentSession: _parent, ...stableHeader } = header;
-	return sha256(canonicalJson({
-		header: stableHeader,
-		inheritedEventCount,
-		events: events.map(normalize),
-		workspace: {
-			originInstanceId: workspace.originInstanceId,
-			originWorkspaceId: workspace.originWorkspaceId,
-			nodeOrigin: workspace.nodeOrigin,
-			remotePath: workspace.remotePath
-		},
-		parentOrigin,
-		instructionSnapshot: instructionSnapshot ? {
-			text: instructionSnapshot.text,
-			capturedAt: instructionSnapshot.capturedAt,
-			workspaceOrigin: instructionSnapshot.workspaceOrigin,
-			workspaceRemotePath: instructionSnapshot.workspaceRemotePath,
-			workspaceRevision: instructionSnapshot.workspaceRevision,
-			digest: instructionSnapshot.digest,
-			inheritedFromOrigin: instructionSnapshot.inheritedFromOrigin
-		} : void 0
-	}));
+	const hash = createHash("sha256");
+	hash.update("{\"events\":[");
+	for (let index = 0; index < events.length; index += 1) {
+		if (index > 0) hash.update(",");
+		hash.update(canonicalJson(normalize(events[index])));
+	}
+	hash.update("]");
+	hash.update(`,"header":${canonicalJson(stableHeader)}`);
+	hash.update(`,"inheritedEventCount":${canonicalJson(inheritedEventCount)}`);
+	hash.update(`,"instructionSnapshot":${instructionSnapshot ? canonicalJson({
+		text: instructionSnapshot.text,
+		capturedAt: instructionSnapshot.capturedAt,
+		workspaceOrigin: instructionSnapshot.workspaceOrigin,
+		workspaceRemotePath: instructionSnapshot.workspaceRemotePath,
+		workspaceRevision: instructionSnapshot.workspaceRevision,
+		digest: instructionSnapshot.digest,
+		inheritedFromOrigin: instructionSnapshot.inheritedFromOrigin
+	}) : "undefined"}`);
+	hash.update(`,"parentOrigin":${parentOrigin ? canonicalJson(parentOrigin) : "undefined"}`);
+	hash.update(`,"workspace":${canonicalJson({
+		originInstanceId: workspace.originInstanceId,
+		originWorkspaceId: workspace.originWorkspaceId,
+		nodeOrigin: workspace.nodeOrigin,
+		remotePath: workspace.remotePath
+	})}`);
+	hash.update("}");
+	return `sha256:${hash.digest("hex")}`;
 }
 function sessionEventListDigest(events) {
-	return sha256(canonicalJson(events));
+	const hash = createHash("sha256");
+	hash.update("[");
+	for (let index = 0; index < events.length; index += 1) {
+		if (index > 0) hash.update(",");
+		hash.update(canonicalJson(events[index]));
+	}
+	hash.update("]");
+	return `sha256:${hash.digest("hex")}`;
 }
 function sessionStateDigest(workspace, workspacePosition, archived, pinned) {
 	return sha256(canonicalJson({
@@ -1033,6 +1211,52 @@ async function collectBytes(stream, maxBytes = MAX_SYNC_TRANSFER_BYTES) {
 	}
 	return Buffer.concat(chunks, size);
 }
+/** 流式计算对象摘要：内存 O(单块)，供超过内联阈值的带外对象测长 + 摘要。 */
+async function hashStream(stream, maxBytes) {
+	const hash = createHash("sha256");
+	let total = 0;
+	for await (const chunk of stream) {
+		if (!(chunk instanceof Uint8Array)) throw new SyncSessionError("object-invalid", "session object stream contains a non-byte chunk");
+		total += chunk.byteLength;
+		if (total > maxBytes) throw new SyncSessionError("bundle-too-large", "session object exceeds the transfer limit");
+		hash.update(chunk);
+	}
+	return {
+		bytes: total,
+		digest: `sha256:${hash.digest("hex")}`
+	};
+}
+/**
+* 带外水合的内容流：边消费边校验字节数与摘要，全部消费完才放行
+* （摘要不符在流末尾抛出，内存 O(单块)）。
+*/
+async function* verifiedObjectStream(stream, expectedBytes, expectedDigest) {
+	const hash = createHash("sha256");
+	let total = 0;
+	for await (const chunk of stream) {
+		if (!(chunk instanceof Uint8Array)) throw new SyncSessionError("object-invalid", "session object stream contains a non-byte chunk");
+		total += chunk.byteLength;
+		if (total > expectedBytes) throw new SyncSessionError("object-integrity", "session object content exceeds declared bytes");
+		hash.update(chunk);
+		yield chunk;
+	}
+	if (total !== expectedBytes || `sha256:${hash.digest("hex")}` !== expectedDigest) throw new SyncSessionError("object-integrity", "session object content failed digest validation");
+}
+/** 校验带外对象帧头：{"id":"...","bytes":N,"digest":"sha256:..."} */
+function parseObjectStreamHeader(line) {
+	let parsed;
+	try {
+		parsed = JSON.parse(line.toString("utf8"));
+	} catch {
+		throw new SyncSessionError("object-invalid", "object stream header is not valid JSON");
+	}
+	if (!isRecord$1(parsed) || typeof parsed.id !== "string" || !parsed.id || !isNonNegativeSafeInteger(parsed.bytes) || parsed.bytes > 68719476736 || typeof parsed.digest !== "string" || !/^sha256:[a-f0-9]{64}$/.test(parsed.digest)) throw new SyncSessionError("object-invalid", "object stream header is invalid");
+	return {
+		id: parsed.id,
+		bytes: parsed.bytes,
+		digest: parsed.digest
+	};
+}
 async function* oneChunk(data) {
 	yield data;
 }
@@ -1104,7 +1328,9 @@ function workspaceCandidateKey(workspace) {
 }
 function validateObjectPayload(object) {
 	if (!isRecord$1(object) || typeof object.id !== "string" || !object.id || typeof object.digest !== "string" || !/^sha256:[a-f0-9]{64}$/.test(object.digest) || !isNonNegativeSafeInteger(object.bytes) || typeof object.data !== "string") throw new SyncSessionError("object-invalid", "session object metadata is invalid");
-	if (!(object.kind === "spill" && object.unavailable === true && object.bytes === 0 && object.data === "")) {
+	const isDeferred = object.deferred === true && object.data === "";
+	const isUnavailableSpill = object.kind === "spill" && object.unavailable === true && object.bytes === 0 && object.data === "";
+	if (!isDeferred && !isUnavailableSpill) {
 		const bytes = Buffer.from(object.data, "base64");
 		if (bytes.toString("base64") !== object.data || bytes.byteLength !== object.bytes || sha256(bytes) !== object.digest) throw new SyncSessionError("object-invalid", "session object encoding or digest is invalid");
 	}
@@ -1292,7 +1518,7 @@ function validateSyncSessionBundle(value) {
 		digest: value.digest
 	};
 	if (bundleDigest(bundle) !== bundle.digest) throw new SyncSessionError("manifest-digest", "session bundle digest does not match");
-	if (Buffer.byteLength(JSON.stringify(bundle), "utf8") > 107374182400) throw new SyncSessionError("bundle-too-large", "session bundle exceeds the transfer limit");
+	if (Buffer.byteLength(JSON.stringify(bundle), "utf8") > 134217728) throw new SyncSessionError("bundle-too-large", "session bundle exceeds the transfer limit");
 	return bundle;
 }
 function makeSyncSessionBundle(instanceId, entries, skipped = [], sharedObjects) {
@@ -1314,7 +1540,7 @@ function makeSyncSessionBundle(instanceId, entries, skipped = [], sharedObjects)
 			digest: ""
 		};
 		bundle.digest = bundleDigest(bundle);
-		if (Buffer.byteLength(JSON.stringify(bundle), "utf8") > 107374182400) throw new SyncSessionError("bundle-too-large", "session bundle exceeds the transfer limit");
+		if (Buffer.byteLength(JSON.stringify(bundle), "utf8") > 134217728) throw new SyncSessionError("bundle-too-large", "session bundle exceeds the transfer limit");
 		return bundle;
 	}
 	const bundle = {
@@ -1325,7 +1551,7 @@ function makeSyncSessionBundle(instanceId, entries, skipped = [], sharedObjects)
 		digest: ""
 	};
 	bundle.digest = bundleDigest(bundle);
-	if (Buffer.byteLength(JSON.stringify(bundle), "utf8") > 107374182400) throw new SyncSessionError("bundle-too-large", "session bundle exceeds the transfer limit");
+	if (Buffer.byteLength(JSON.stringify(bundle), "utf8") > 134217728) throw new SyncSessionError("bundle-too-large", "session bundle exceeds the transfer limit");
 	return bundle;
 }
 function syncSessionEntryKey(entry) {
@@ -1380,7 +1606,7 @@ function makeSyncSessionManifest(instanceId, entries, skipped = []) {
 		digest: ""
 	};
 	manifest.digest = sessionManifestDigest(manifest);
-	if (Buffer.byteLength(JSON.stringify(manifest), "utf8") > 107374182400) throw new SyncSessionError("bundle-too-large", "session manifest exceeds the transfer limit");
+	if (Buffer.byteLength(JSON.stringify(manifest), "utf8") > 134217728) throw new SyncSessionError("bundle-too-large", "session manifest exceeds the transfer limit");
 	return manifest;
 }
 function validateSyncSessionManifest(value) {
@@ -1399,7 +1625,7 @@ function validateSyncSessionManifest(value) {
 		digest: value.digest
 	};
 	if (sessionManifestDigest(manifest) !== manifest.digest) throw new SyncSessionError("manifest-digest", "session manifest digest does not match");
-	if (Buffer.byteLength(JSON.stringify(manifest), "utf8") > 107374182400) throw new SyncSessionError("bundle-too-large", "session manifest exceeds the transfer limit");
+	if (Buffer.byteLength(JSON.stringify(manifest), "utf8") > 134217728) throw new SyncSessionError("bundle-too-large", "session manifest exceeds the transfer limit");
 	return manifest;
 }
 function emptyApplyResult() {
@@ -1501,7 +1727,7 @@ function instructionsForSession(store, sessionId, stateIndex, preferredWorkspace
 		...inheritedFromOrigin ? { inheritedFromOrigin } : {}
 	};
 }
-var SyncSessionService = class {
+var SyncSessionService = class SyncSessionService {
 	state;
 	nodes;
 	registry;
@@ -1518,6 +1744,8 @@ var SyncSessionService = class {
 	exportCacheStore;
 	manifestPayloadCache = /* @__PURE__ */ new Map();
 	manifestPayloadCacheBytes = 0;
+	/** 带外对象收件箱：对象流 RPC 的落盘暂存区，apply 水合后删除。 */
+	objectInbox;
 	constructor(state, nodes, registry, bindings, getWorkspaces, getPersistence, getAttachments, getSpills, instructions, journal = new SyncSessionJournalStore(), now = Date.now, home) {
 		this.state = state;
 		this.nodes = nodes;
@@ -1531,6 +1759,7 @@ var SyncSessionService = class {
 		this.journal = journal;
 		this.now = now;
 		this.exportCacheStore = new SyncSessionExportCacheStore(home);
+		this.objectInbox = new SyncSessionObjectInbox(home);
 		for (const [key, entry] of this.exportCacheStore.entries()) if (!this.exportCache.has(key)) this.exportCache.set(key, entry);
 	}
 	exportBundle() {
@@ -1575,7 +1804,8 @@ var SyncSessionService = class {
 				bundle = makeSyncSessionBundle(payloadCache.instanceId, [...cachedEntries, ...additional.entries], additional.skipped);
 			} else bundle = await this.exportBundleNow({
 				selectedKeys,
-				sharedObjects: options.sharedObjects === true
+				sharedObjects: options.sharedObjects === true,
+				deferredObjects: options.deferredObjects === true
 			});
 			const withTails = bundle.entries.map((entry) => withEventTail(entry, prefixesByKey.get(syncSessionEntryKey(entry))));
 			if (bundle.objects !== void 0) return makeSyncSessionBundle(bundle.instanceId, withTails, bundle.skipped, bundle.objects);
@@ -1709,9 +1939,10 @@ var SyncSessionService = class {
 		const entries = [];
 		const skipped = [];
 		const eligibleLocalIds = /* @__PURE__ */ new Set();
+		const preservedLocalIds = /* @__PURE__ */ new Set();
 		const workspaceById = /* @__PURE__ */ new Map();
 		const archivedBranchSessionIds = new Set(Object.values(stateIndex.state.archives).map((archive) => archive.localSessionId));
-		const objectCache = /* @__PURE__ */ new Map();
+		const objectCache = new ExportObjectCache();
 		const descriptorCache = /* @__PURE__ */ new Map();
 		const getWorkspaceDescriptor = (workspace, binding, nodeOrigin, preferredOrigin) => {
 			const key = canonicalJson({
@@ -1764,7 +1995,18 @@ var SyncSessionService = class {
 						continue;
 					}
 				}
-				const exported = await this.exportSessionEntry(persistence, workspace, descriptor, position, SessionId(sessionId), snapshot, archivedIds.has(sessionId), pinnedIds.has(sessionId), void 0, stateIndex, objectCache);
+				let exported;
+				try {
+					exported = await this.exportSessionEntry(persistence, workspace, descriptor, position, SessionId(sessionId), snapshot, archivedIds.has(sessionId), pinnedIds.has(sessionId), void 0, stateIndex, objectCache, options.deferredObjects === true);
+				} catch (error) {
+					if (!(error instanceof SyncSessionError && error.code === "session-too-large")) throw error;
+					skipped.push({
+						sessionId,
+						reason: "session-payload-too-large"
+					});
+					preservedLocalIds.add(sessionId);
+					continue;
+				}
 				if (exported) {
 					const { entry } = exported;
 					if (manifestOnly && options.payloadCache) {
@@ -1801,6 +2043,7 @@ var SyncSessionService = class {
 				continue;
 			}
 			if (eligibleLocalIds.has(metadata.localEntityId)) continue;
+			if (preservedLocalIds.has(metadata.localEntityId)) continue;
 			const tombstone = {
 				...metadata,
 				revision: this.state.nextRevision(this.now()),
@@ -1828,7 +2071,18 @@ var SyncSessionService = class {
 			const descriptor = getWorkspaceDescriptor(workspace, binding, nodeOrigin, stateIndex.archivesByLocalSessionId.get(archive.localSessionId)?.workspaceOrigin);
 			const snapshot = await persistence.stat(SessionId(archive.localSessionId));
 			if (!snapshot) continue;
-			const exported = await this.exportSessionEntry(persistence, workspace, descriptor, archive.workspacePosition, SessionId(archive.localSessionId), snapshot, true, false, archive, stateIndex, objectCache);
+			let exported;
+			try {
+				exported = await this.exportSessionEntry(persistence, workspace, descriptor, archive.workspacePosition, SessionId(archive.localSessionId), snapshot, true, false, archive, stateIndex, objectCache, options.deferredObjects === true);
+			} catch (error) {
+				if (!(error instanceof SyncSessionError && error.code === "session-too-large")) throw error;
+				skipped.push({
+					sessionId: archive.localSessionId,
+					reason: "session-payload-too-large"
+				});
+				preservedLocalIds.add(archive.localSessionId);
+				continue;
+			}
 			if (exported) {
 				const { entry } = exported;
 				if (manifestOnly && options.payloadCache) {
@@ -1887,6 +2141,7 @@ var SyncSessionService = class {
 		const batchId = pendingBatch?.batchId ?? this.journal.beginWithBundle(peerId, safeSourceName, bundle.digest, recordKeys, bundle, new Date(this.now()).toISOString(), resolvedImportedVia, allowSameInstance);
 		const result = emptyApplyResult();
 		const attachmentImportCache = /* @__PURE__ */ new Map();
+		const inboxConsumed = /* @__PURE__ */ new Set();
 		result.skipped += bundle.skipped.length;
 		result.unmapped += bundle.skipped.length;
 		const workspaceOrders = /* @__PURE__ */ new Map();
@@ -1992,7 +2247,7 @@ var SyncSessionService = class {
 				let prepared;
 				if (preparedValue === void 0) {
 					try {
-						prepared = await this.prepareEntry(entry, safeSourceName, plannedSessionIds, entryWorkspace, resolvedImportedVia, attachmentImportCache);
+						prepared = await this.prepareEntry(entry, safeSourceName, plannedSessionIds, entryWorkspace, resolvedImportedVia, attachmentImportCache, inboxConsumed);
 					} catch (error) {
 						if (error instanceof SyncSessionError && error.code === "workspace-unmapped") {
 							result.skipped += 1;
@@ -2018,6 +2273,7 @@ var SyncSessionService = class {
 			await this.orderWorkspaceSessions(workspaceOrders);
 			this.journal.complete(batchId);
 			this.exportCacheStore.flush();
+			if (inboxConsumed.size > 0) await this.deleteInboxedObjects(inboxConsumed);
 			return result;
 		} catch (error) {
 			if (error instanceof SyncSessionError) throw error;
@@ -2052,7 +2308,7 @@ var SyncSessionService = class {
 		}
 		return validateSyncSessionBundle(makeSyncSessionBundle(bundle.instanceId, entries, bundle.skipped));
 	}
-	async prepareEntry(entry, sourceName, plannedSessionIds, workspace, importedVia, attachmentImportCache) {
+	async prepareEntry(entry, sourceName, plannedSessionIds, workspace, importedVia, attachmentImportCache, inboxConsumed) {
 		if (!entry.header || !entry.events || !entry.workspace || !entry.objects) throw new SyncSessionError("manifest-invalid", "active session entry is incomplete");
 		const sessionId = entry.branchId ? archivedSessionId(entry.branchId) : importedSessionId(entry.metadata);
 		const sourceHeader = entry.header;
@@ -2077,7 +2333,7 @@ var SyncSessionService = class {
 				await handle.close();
 			}
 		}
-		const objectMap = await this.importObjects(entry.objects, sessionId, attachmentImportCache);
+		const objectMap = await this.importObjects(entry.objects, sessionId, attachmentImportCache, inboxConsumed);
 		const validatedEvents = validateStoredEvents(header, this.rewriteEvents(entry.events, entry.objects, objectMap, sessionId, String(entry.header.id)));
 		assertContiguous(sessionId, validatedEvents, 0);
 		const instructionWorkspaceId = entry.instructionSnapshot?.workspaceOrigin ? this.localWorkspaceIdForOrigin(entry.instructionSnapshot.workspaceOrigin, entry.instructionSnapshot.workspaceRemotePath) : void 0;
@@ -2163,7 +2419,7 @@ var SyncSessionService = class {
 		if (!committedWorkspace) throw new SyncSessionError("workspace-unmapped", "目标实例没有对应的可用远程节点");
 		return committedWorkspace;
 	}
-	async importObjects(objects, sessionId, attachmentImportCache) {
+	async importObjects(objects, sessionId, attachmentImportCache, inboxConsumed) {
 		const attachments = objects.some((object) => object.kind === "image" || object.kind === "file") ? this.getAttachments() : void 0;
 		const spills = objects.some((object) => object.kind === "spill" && !object.unavailable) ? this.getSpills() : void 0;
 		if (objects.some((object) => object.kind === "image" || object.kind === "file") && !attachments) throw new SyncSessionError("attachments-unavailable", "目标实例的附件存储服务不可用");
@@ -2178,6 +2434,54 @@ var SyncSessionService = class {
 					continue;
 				}
 			}
+			if (object.deferred === true) {
+				inboxConsumed?.add(object.digest);
+				if (object.kind === "image") {
+					const data = await collectBytes(await this.objectInbox.read(object.digest), MAX_SESSION_OBJECT_INLINE_BYTES * 256);
+					if (data.byteLength !== object.bytes || sha256(data) !== object.digest) throw new SyncSessionError("object-integrity", "session object failed digest validation");
+					const ref = await attachments.saveImage({
+						data,
+						mediaType: object.ref.mediaType,
+						...object.ref.name === void 0 ? {} : { name: object.ref.name }
+					});
+					output.set(object.id, ref);
+					attachmentImportCache?.set(object.id, ref);
+				} else if (object.kind === "file") {
+					const stream = await this.objectInbox.read(object.digest);
+					const ref = await attachments.saveFileStream({
+						data: verifiedObjectStream(stream, object.bytes, object.digest),
+						name: object.ref.name
+					});
+					output.set(object.id, ref);
+					attachmentImportCache?.set(object.id, ref);
+				} else if (spills.saveTextStream) {
+					const stream = await this.objectInbox.read(object.digest);
+					const ref = await saveSpillTransfer(spills, {
+						owner: { sessionId },
+						source: object.reference.source,
+						suggestedName: object.reference.suggestedName,
+						transferId: object.id,
+						bytes: object.bytes,
+						digest: object.digest,
+						content: verifiedObjectStream(stream, object.bytes, object.digest)
+					});
+					output.set(object.id, ref);
+				} else {
+					const data = await collectBytes(await this.objectInbox.read(object.digest), MAX_SESSION_OBJECT_INLINE_BYTES * 1024);
+					if (data.byteLength !== object.bytes || sha256(data) !== object.digest) throw new SyncSessionError("object-integrity", "session object failed digest validation");
+					const ref = await saveSpillTransfer(spills, {
+						owner: { sessionId },
+						source: object.reference.source,
+						suggestedName: object.reference.suggestedName,
+						transferId: object.id,
+						bytes: object.bytes,
+						digest: object.digest,
+						data
+					});
+					output.set(object.id, ref);
+				}
+				continue;
+			}
 			const data = arrayBuffer(object.data);
 			if (data.byteLength !== object.bytes || sha256(data) !== object.digest) throw new SyncSessionError("object-integrity", "session object failed digest validation");
 			if (object.kind === "image") {
@@ -2627,7 +2931,7 @@ var SyncSessionService = class {
 			contentDigest: digest
 		};
 	}
-	async exportSessionEntry(persistence, workspace, descriptor, workspacePosition, sessionId, firstSnapshot, archived, pinned, archive, stateIndex, objectCache) {
+	async exportSessionEntry(persistence, workspace, descriptor, workspacePosition, sessionId, firstSnapshot, archived, pinned, archive, stateIndex, objectCache, deferredObjects = false) {
 		const { header, inheritedEventCount, events, revision: sourceRevision } = await this.readStableSession(persistence, sessionId, firstSnapshot);
 		const localSessionId = String(sessionId);
 		const cacheKey = sessionExportCacheKey(localSessionId);
@@ -2648,7 +2952,7 @@ var SyncSessionService = class {
 			originEntityId: descriptor.originWorkspaceId
 		});
 		const eventDigest = sessionEventListDigest(events);
-		const objects = await this.exportObjects(events, localSessionId, objectCache);
+		const objects = await this.exportObjects(events, localSessionId, objectCache, deferredObjects);
 		const digest = sessionEventDigest(header, inheritedEventCount, events, descriptor, syncInstructions, objects, parentOrigin);
 		const current = archive ? void 0 : index.recordsByLocalId.get(localSessionId) ?? state.records[syncRecordKey("session", {
 			originInstanceId: this.state.instanceId(),
@@ -2711,6 +3015,28 @@ var SyncSessionService = class {
 			});
 			indexSessionRecord(index, metadata);
 		}
+		const wireEntry = {
+			metadata,
+			...outputBranchId ? { branchId: outputBranchId } : {},
+			sourceLocalSessionId: localSessionId,
+			header,
+			inheritedEventCount,
+			...parentOrigin ? { parentOrigin } : {},
+			workspace: descriptor,
+			workspacePosition,
+			archived,
+			pinned,
+			...syncInstructions ? { instructionSnapshot: syncInstructions } : {},
+			events: [...events],
+			objects,
+			eventCount: events.length,
+			eventDigest
+		};
+		if (Buffer.byteLength(JSON.stringify(wireEntry), "utf8") > MAX_SESSION_EXPORT_ENTRY_BYTES) {
+			this.exportCache.delete(cacheKey);
+			this.exportCacheStore.delete(cacheKey);
+			throw new SyncSessionError("session-too-large", "会话内容超过单会话传输上限");
+		}
 		if (!archive && !objects.some((object) => object.kind === "spill")) {
 			const fingerprint = sessionExportFingerprint({
 				revision: sourceRevision,
@@ -2739,23 +3065,7 @@ var SyncSessionService = class {
 			this.exportCacheStore.delete(cacheKey);
 		}
 		return {
-			entry: {
-				metadata,
-				...outputBranchId ? { branchId: outputBranchId } : {},
-				sourceLocalSessionId: localSessionId,
-				header,
-				inheritedEventCount,
-				...parentOrigin ? { parentOrigin } : {},
-				workspace: descriptor,
-				workspacePosition,
-				archived,
-				pinned,
-				...syncInstructions ? { instructionSnapshot: syncInstructions } : {},
-				events: [...events],
-				objects,
-				eventCount: events.length,
-				eventDigest
-			},
+			entry: wireEntry,
 			eventCount: events.length,
 			eventDigest,
 			inheritedEventCount
@@ -2794,7 +3104,7 @@ var SyncSessionService = class {
 		}
 		throw new SyncSessionError("session-changing", "会话在导出期间持续变化，请稍后重试");
 	}
-	async exportObjects(events, sessionId, objectCache) {
+	async exportObjects(events, sessionId, objectCache, deferredObjects = false) {
 		const attachments = attachmentReferences(events);
 		const spills = spillReferences(events);
 		const structuredSpills = new Set(spills.map(spillKey));
@@ -2802,6 +3112,11 @@ var SyncSessionService = class {
 		const payloads = /* @__PURE__ */ new Map();
 		const attachmentStore = attachments.images.length + attachments.files.length > 0 ? this.getAttachments() : void 0;
 		if (attachments.images.length + attachments.files.length > 0 && !attachmentStore) throw new SyncSessionError("attachments-unavailable", "附件存储服务不可用");
+		const deferredDescriptor = (object) => ({
+			...object,
+			data: "",
+			deferred: true
+		});
 		for (const ref of attachments.images) {
 			const key = attachmentKey("image", ref);
 			const cached = objectCache?.get(key)?.object;
@@ -2811,7 +3126,7 @@ var SyncSessionService = class {
 			}
 			const stored = await attachmentStore.readImage(ref);
 			const digest = sha256(stored.data);
-			const object = {
+			let object = {
 				id: key,
 				kind: "image",
 				ref: stored.ref,
@@ -2819,6 +3134,7 @@ var SyncSessionService = class {
 				digest,
 				data: Buffer.from(stored.data).toString("base64")
 			};
+			if (deferredObjects && object.bytes > 262144) object = deferredDescriptor(object);
 			payloads.set(key, object);
 			objectCache?.set(key, { object });
 		}
@@ -2829,7 +3145,30 @@ var SyncSessionService = class {
 				payloads.set(key, cached);
 				continue;
 			}
-			const data = await collectBytes(attachmentStore.readFileStream(ref));
+			let data;
+			const inlineCap = deferredObjects ? MAX_SESSION_OBJECT_INLINE_BYTES : MAX_SYNC_TRANSFER_BYTES;
+			try {
+				data = await collectBytes(attachmentStore.readFileStream(ref), inlineCap);
+			} catch (error) {
+				if (!(error instanceof SyncSessionError && error.code === "bundle-too-large")) throw error;
+				data = void 0;
+			}
+			if (data === void 0) {
+				if (!deferredObjects) throw new SyncSessionError("session-too-large", "会话文件附件超过传输大小限制");
+				const measured = await hashStream(attachmentStore.readFileStream(ref), MAX_SESSION_OBJECT_STREAM_BYTES);
+				const object = {
+					id: key,
+					kind: "file",
+					ref,
+					bytes: measured.bytes,
+					digest: measured.digest,
+					data: "",
+					deferred: true
+				};
+				payloads.set(key, object);
+				objectCache?.set(key, { object });
+				continue;
+			}
 			const object = {
 				id: key,
 				kind: "file",
@@ -2856,7 +3195,37 @@ var SyncSessionService = class {
 					continue;
 				}
 				try {
-					const data = await collectBytes(readSpillStream(store, reference));
+					let data;
+					const inlineCap = deferredObjects ? MAX_SESSION_OBJECT_INLINE_BYTES : MAX_SYNC_TRANSFER_BYTES;
+					try {
+						data = await collectBytes(readSpillStream(store, reference), inlineCap);
+					} catch (error) {
+						if (!(error instanceof SyncSessionError && error.code === "bundle-too-large")) throw error;
+						data = void 0;
+					}
+					if (data === void 0) {
+						if (!deferredObjects) {
+							untransferred.push(reference);
+							continue;
+						}
+						const measured = await hashStream(readSpillStream(store, reference), MAX_SESSION_OBJECT_STREAM_BYTES);
+						if (reference.ref.bytes !== void 0 && measured.bytes !== reference.ref.bytes) {
+							untransferred.push(reference);
+							continue;
+						}
+						const object = {
+							id: key,
+							kind: "spill",
+							reference,
+							bytes: measured.bytes,
+							digest: measured.digest,
+							data: "",
+							deferred: true
+						};
+						payloads.set(key, object);
+						objectCache?.set(key, { object });
+						continue;
+					}
 					if (reference.ref.bytes !== void 0 && data.byteLength !== reference.ref.bytes) {
 						untransferred.push(reference);
 						continue;
@@ -2901,6 +3270,111 @@ var SyncSessionService = class {
 		if (!persistence) throw new SyncSessionError("session-persistence-unavailable", "会话持久化服务不可用");
 		return persistence;
 	}
+	/**
+	* 把 deferred 对象编码为带外帧流：每对象一行 JSON 头 + 原始字节。
+	* 内容从本地存储流式读取（spill/文件流式；图片体积有限走缓冲），
+	* 逐块校验字节数与摘要，内存 O(单块)。
+	*/
+	async *streamObjects(objects) {
+		for (const object of objects) {
+			yield Buffer.from(`${JSON.stringify({
+				id: object.id,
+				bytes: object.bytes,
+				digest: object.digest
+			})}\n`, "utf8");
+			if (object.deferred !== true) {
+				const data = arrayBuffer(object.data);
+				if (data.byteLength !== object.bytes || sha256(data) !== object.digest) throw new SyncSessionError("object-integrity", "session object failed digest validation");
+				yield data;
+				continue;
+			}
+			const hash = createHash("sha256");
+			let verified = 0;
+			const source = await this.openObjectContent(object);
+			for await (const chunk of source) {
+				if (!(chunk instanceof Uint8Array)) throw new SyncSessionError("object-invalid", "session object stream contains a non-byte chunk");
+				verified += chunk.byteLength;
+				if (verified > object.bytes) throw new SyncSessionError("object-integrity", "session object content exceeds declared bytes");
+				hash.update(chunk);
+				yield chunk;
+			}
+			if (verified !== object.bytes || `sha256:${hash.digest("hex")}` !== object.digest) throw new SyncSessionError("object-integrity", "session object content failed digest validation");
+		}
+	}
+	async openObjectContent(object) {
+		if (object.kind === "spill") {
+			const store = this.getSpills();
+			if (!store) throw new SyncSessionError("spill-transfer-unavailable", "目标实例没有 owner-scoped spill transfer API");
+			return readSpillStream(store, object.reference);
+		}
+		const attachments = this.getAttachments();
+		if (!attachments) throw new SyncSessionError("attachments-unavailable", "附件存储服务不可用");
+		if (object.kind === "file") return attachments.readFileStream(object.ref);
+		return oneChunk((await attachments.readImage(object.ref)).data);
+	}
+	/** 单帧写入上限：超过即认为流失控。 */
+	static OBJECT_STREAM_HEADER_MAX_BYTES = 65536;
+	/**
+	* 解析并落盘对端推送的对象帧流：逐帧写收件箱，边写边校验摘要，
+	* 内存 O(单帧)。返回接收的对象数。
+	*/
+	async ingestObjectStream(source) {
+		let buffer = Buffer.alloc(0);
+		const reader = source[Symbol.asyncIterator]();
+		const nextChunk = async () => {
+			const { value, done } = await reader.next();
+			return done ? void 0 : Buffer.from(value);
+		};
+		let count = 0;
+		for (;;) {
+			let newline = buffer.indexOf(10);
+			while (newline < 0) {
+				const chunk = await nextChunk();
+				if (chunk === void 0) {
+					if (buffer.length === 0) return count;
+					throw new SyncSessionError("object-invalid", "object stream ended inside a header");
+				}
+				buffer = Buffer.concat([buffer, chunk]);
+				if (buffer.length > SyncSessionService.OBJECT_STREAM_HEADER_MAX_BYTES) throw new SyncSessionError("object-invalid", "object stream header exceeds size limit");
+				newline = buffer.indexOf(10);
+			}
+			const header = parseObjectStreamHeader(buffer.subarray(0, newline));
+			buffer = buffer.subarray(newline + 1);
+			const writer = await this.objectInbox.writerFor(header.digest, header.bytes);
+			try {
+				const writePart = async (part) => {
+					if (part.byteLength > 0) await writer.write(part);
+				};
+				let remaining = header.bytes;
+				for (;;) {
+					if (buffer.length > 0) {
+						const take = Math.min(buffer.length, remaining);
+						await writePart(buffer.subarray(0, take));
+						remaining -= take;
+						buffer = buffer.subarray(take);
+						if (remaining === 0) break;
+						continue;
+					}
+					const chunk = await nextChunk();
+					if (chunk === void 0) throw new SyncSessionError("object-invalid", "object stream ended inside a payload");
+					const take = Math.min(chunk.length, remaining);
+					await writePart(chunk.subarray(0, take));
+					remaining -= take;
+					if (take < chunk.length) buffer = Buffer.concat([buffer, chunk.subarray(take)]);
+					if (remaining === 0) break;
+				}
+				await writer.commit();
+			} catch (error) {
+				await writer.abort();
+				throw error;
+			}
+			count += 1;
+		}
+	}
+	/** apply 成功后删除已水合对象的收件箱文件；失败保留供 journal 回放。 */
+	async deleteInboxedObjects(digests) {
+		for (const digest of digests) await this.objectInbox.delete(digest);
+	}
 	serializeMutation(operation) {
 		const result = this.operationTail.then(operation);
 		this.operationTail = result.then(() => void 0, () => void 0);
@@ -2908,6 +3382,6 @@ var SyncSessionService = class {
 	}
 };
 //#endregion
-export { planSessionTransfers as a, validateSyncSessionBundle as c, makeSyncSessionManifest as i, validateSyncSessionManifest as l, SyncSessionService as n, sessionEventListDigest as o, makeSyncSessionBundle as r, syncSessionEntryKey as s, SyncSessionError as t };
+export { estimateJsonBytes as a, planSessionTransfers as c, validateObjectPayload as d, validateSyncSessionBundle as f, SyncSessionService as i, sessionEventListDigest as l, SyncSessionError as n, makeSyncSessionBundle as o, validateSyncSessionManifest as p, SyncSessionObjectInbox as r, makeSyncSessionManifest as s, ExportObjectCache as t, syncSessionEntryKey as u };
 
-//# sourceMappingURL=session-sync-C0uoizyB.js.map
+//# sourceMappingURL=session-sync-CIqjuWkh.js.map