@lingxi-ai-cn/dsh-session-export 0.1.6-rc.8 → 0.1.7-alpha.2

package/README.md

@@ -1,17 +1,31 @@
+---
+description: "Native atomic Session archive and Markdown export over official durable persistence owners."
+kind: "package-reference"
+---
+
 # `@lingxi-ai-cn/dsh-session-export`
 
 English | [中文](README.zh.md)
 
-Host-owned Session-log ZIP producer, human-readable Markdown projection, and native path writer. The `SessionLogExporter` service (`ctx.sessionLogExporter`) flushes each live Session before reading its persistence backend's raw artifact, streams the root artifact, optional descendants, and referenced images through bounded fflate compression, and never reconstructs the raw archive from parsed events. `stream()` exposes the archive to a host transport; `writeToDirectory()` writes the same archive to an existing absolute directory and returns its exact final path. `writeMarkdownToDirectory()` separately reads the validated logical events and publishes a summary-only Markdown projection.
+## Summary
+
+Native Session archive writer and human-readable projection over the official [`@deepseek-ai/dsh-session-log-export`](../../session-query/session-log-export/README.md) producer. The `SessionLogExporter` service (`ctx.sessionLogExporter`) reuses that package's root preflight, raw-artifact ZIP stream, descendant ordering, attachment collection, compression, backpressure, and cancellation. `stream()` exposes the official archive stream to a native consumer; `writeToDirectory()` writes it into an existing absolute host directory and returns the exact final path. `writeMarkdownToDirectory()` separately reads validated logical events and publishes a summary-only Markdown projection.
 
-The native writer creates an owner-only random sibling, forwards cancellation through root preparation, lineage, persistence, attachment reads, compression, and file writes, syncs and closes the complete file, then publishes it with an exclusive hard link. Existing exports are never overwritten: the first collision uses `-2`, followed by increasing suffixes. A failure before publication removes the partial sibling and leaves no final archive. The destination filesystem must support same-directory hard links.
+The adapter adds only native publication: it creates an owner-only random sibling, forwards cancellation through the official producer and file writes, syncs and closes the complete file, then publishes it with an exclusive hard link. Existing exports are never overwritten: the first collision uses `-2`, followed by increasing suffixes. A failure before publication removes the partial sibling and leaves no final archive. The destination filesystem must support same-directory hard links.
 
-Markdown export is intentionally a human-readable projection, not a replacement for the raw archive. It includes the current surface of the root and optional descendants, bounded user/assistant text, tool names and bounded result summaries, and explicit sequence/time facts. Tool argument values are omitted by default and marked as omitted; the exporter does not offer a silent sensitive-detail mode. Image attachments use `attachment:<id>` reference-only links and are never copied into the Markdown file. The same private sibling, cancellation, `0600` mode, collision suffix, and exclusive hard-link publication rules apply to `.md` output.
+Markdown export is intentionally a human-readable projection, not a replacement for the official raw archive. It includes the current surface of the root and optional descendants, bounded user/assistant text, tool names and bounded result summaries, and explicit sequence/time facts. Tool argument values are omitted and marked as omitted. Image attachments use `attachment:<id>` references and their bytes are never copied into the Markdown file. The same private sibling, cancellation, `0600` mode, collision suffix, and exclusive hard-link publication rules apply to `.md` output.
 
 Expected preparation failures use `SessionLogExportError`: `services-unavailable`, `raw-artifacts-unsupported`, `session-not-found`, and `prepare-failed`. Destination and output failures use `destination-invalid` and `write-failed`. The operator-facing messages do not expose backend preparation errors; the original error remains attached as `cause` for host diagnostics. Signal cancellation preserves the signal's reason instead of becoming an export failure.
 
 The archive is diagnostic material containing the stored Session artifacts verbatim. Provider credential stores and transient OAuth progress are outside Session persistence and are never included, but prompts and tool arguments already present in the durable log remain present; consumers must choose an operator-controlled destination and treat the result as sensitive.
 
+## Table of Contents
+
+- [Configuration](#configuration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
 ## Configuration
 
 | Key | Default | Behavior |
@@ -29,6 +43,11 @@ None. Export does not assemble or send provider requests.
 ## Known Limitations and Deferred Work
 
 - Persistence backends that do not expose per-Session raw artifacts cannot export; the shipped JSONL backend supports plaintext and zstd artifacts, while SQLite does not.
-- Markdown projection can use a backend's validated logical `inspect()` API even when raw-artifact ZIP export is unavailable; its attachment policy remains reference-only.
+- Markdown projection can use a backend's validated logical `inspect()` API even when official raw-artifact ZIP export is unavailable; its attachment policy remains reference-only.
 - A tree export is a sequence of per-Session durability barriers and reads, not one atomic snapshot across the whole lineage; a live descendant may append after its artifact was read.
 - Native publication requires hard-link support in the selected directory. The service fails without publishing a partial final file when the filesystem rejects that operation.
+
+<a id="dev-note"></a>
+### Dev Note
+
+None.

package/README.zh.md

@@ -1,23 +1,39 @@
+---
+description: "基于官方 durable persistence owner 的原生原子 Session archive 与 Markdown 导出。"
+kind: "package-reference"
+---
+
 # `@lingxi-ai-cn/dsh-session-export`
 
 [English](README.md) | 中文
 
-宿主侧拥有的 Session 日志 ZIP 生产器、人类可读 Markdown projection 与原生路径写入器。`SessionLogExporter` 服务（`ctx.sessionLogExporter`）会在读取持久化后端的原始工件前 flush 每个实时 Session，通过有界 fflate 压缩流式输出根工件、可选后代和引用的图片，并且绝不从解析事件重建原始归档。`stream()` 向宿主传输层提供归档；`writeToDirectory()` 把同一归档写入一个既有的绝对目录，并返回精确的最终路径。`writeMarkdownToDirectory()` 则独立读取已验证的逻辑事件并发布仅供摘要阅读的 Markdown projection。
+## 概述
+
+基于官方 [`@deepseek-ai/dsh-session-log-export`](../../session-query/session-log-export/README.zh.md) 生产器的原生 Session 归档写入器与人类可读 projection。`SessionLogExporter` 服务（`ctx.sessionLogExporter`）复用该包的根工件预检、原始工件 ZIP 流、后代顺序、附件收集、压缩、背压与取消。`stream()` 向原生消费方暴露官方归档流；`writeToDirectory()` 把它写入既有的绝对宿主目录，并返回精确的最终路径。`writeMarkdownToDirectory()` 则独立读取已验证的逻辑事件并发布仅供摘要阅读的 Markdown projection。
 
-原生写入器先创建一个仅所有者可读写的随机同级文件，把取消转发到根工件准备、血缘、持久化、附件读取、压缩和文件写入，随后同步并关闭完整文件，最后通过排他硬链接发布。既有导出永远不会被覆盖：第一次冲突使用 `-2`，随后递增后缀。发布前的失败会删除局部同级文件，不留下最终归档。目标文件系统必须支持同目录硬链接。
+该适配器只增加原生发布：先创建一个仅所有者可读写的随机同级文件，把取消转发到官方生产器和文件写入，随后同步并关闭完整文件，最后通过排他硬链接发布。既有导出永远不会被覆盖：第一次冲突使用 `-2`，随后递增后缀。发布前的失败会删除局部同级文件，不留下最终归档。目标文件系统必须支持同目录硬链接。
 
-Markdown 导出明确是人类可读 projection，不替代原始归档。它包含根 Session 及可选后代的当前表层、有界的人类/助手文本、工具名称、有界结果摘要，以及明确的 seq/time 事实。工具参数值默认省略并明确标记；导出器不会提供静默的敏感详情模式。图片附件只使用 `attachment:<id>` 的仅引用链接，绝不复制到 Markdown 文件。同一私有同级临时文件、取消、`0600` 权限、冲突后缀和排他硬链接发布规则也适用于 `.md` 输出。
+Markdown 导出明确是人类可读 projection，不替代官方原始归档。它包含根 Session 及可选后代的当前表层、有界的用户/助手文本、工具名称、有界结果摘要，以及明确的 seq/time 事实。工具参数值会被省略并明确标记。图片附件只使用 `attachment:<id>` 引用，其字节绝不复制到 Markdown 文件。同一私有同级临时文件、取消、`0600` 权限、冲突后缀和排他硬链接发布规则也适用于 `.md` 输出。
 
 预期的准备失败使用 `SessionLogExportError`：`services-unavailable`、`raw-artifacts-unsupported`、`session-not-found` 和 `prepare-failed`。目标与输出失败使用 `destination-invalid` 和 `write-failed`。面向操作者的消息不会泄露后端准备错误；原始错误保留为 `cause`，供宿主诊断。signal 取消会保留 signal 的 reason，而不会改写成导出失败。
 
 该归档是逐字包含所存 Session 工件的诊断材料。提供方凭据存储和 transient OAuth 进度位于 Session 持久化之外，绝不会包含在内；但已经进入持久日志的 prompt 与工具参数仍会保留，因此 Consumer 必须选择由操作者控制的目标位置，并把结果视为敏感材料。
 
+## 目录
+
+- [配置](#configuration)
+- [模型体验](#model-experience)
+- [已知限制与暂缓事项](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+<a id="configuration"></a>
 ## 配置
 
 | 键 | 默认值 | 行为 |
 |---|---:|---|
 | `compressionLevel` | `6` | 从 `0`（仅存储）到 `9`（最小归档）的整数 fflate DEFLATE 级别。 |
 
+<a id="model-experience"></a>
 ## 模型体验
 
 无，因为导出只读取持久工件并写入宿主文件，不增加 Session 事件或模型可见内容。
@@ -26,9 +42,15 @@ Markdown 导出明确是人类可读 projection，不替代原始归档。它包
 
 无。导出不会组装或发送提供方请求。
 
+<a id="known-limitations-and-deferred-work"></a>
 ## 已知限制与暂缓事项
 
 - 不提供逐 Session 原始工件的持久化后端无法导出；随附的 JSONL 后端支持明文与 zstd 工件，SQLite 尚不支持。
-- 即使原始工件 ZIP 不可用，Markdown projection 仍可使用后端已验证的逻辑 `inspect()` API；附件策略仍固定为仅引用。
+- 即使官方原始工件 ZIP 不可用，Markdown projection 仍可使用后端已验证的逻辑 `inspect()` API；附件策略仍固定为仅引用。
 - 树导出是一系列逐 Session 的持久性屏障与读取，并非覆盖整条血缘的一次原子快照；实时后代可能在自身工件被读取后继续追加。
 - 原生发布要求所选目录支持硬链接。文件系统拒绝该操作时，服务会失败且不会发布局部最终文件。
+
+<a id="dev-note"></a>
+### 开发备注
+
+无。

package/lib/index.js

@@ -3,365 +3,9 @@ import { link, open, rm, stat } from "node:fs/promises";
 import { basename, extname, isAbsolute, join } from "node:path";
 import { Service } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
-import { Zip, ZipDeflate } from "fflate";
+import { DEFAULT_SESSION_LOG_COMPRESSION_LEVEL, DEFAULT_SESSION_LOG_COMPRESSION_LEVEL as DEFAULT_SESSION_LOG_COMPRESSION_LEVEL$1, flushLiveSessionLog, flushLiveSessionLog as flushLiveSessionLog$1, sessionLogExportDeps, sessionLogExportDeps as sessionLogExportDeps$1, sessionLogZipEntries, sessionLogZipFilename, sessionLogZipFilename as sessionLogZipFilename$1, streamSessionLogZip, streamSessionLogZip as streamSessionLogZip$1 } from "@deepseek-ai/dsh-session-log-export";
 import { foldSurface } from "@deepseek-ai/dsh-session";
 import { extractSessionEventText } from "@deepseek-ai/dsh-session-query";
-//#region lib/types/zip.js
-/**
-* Host-side Session ZIP producer: streams one archive whose files are the
-* sessions' stored artifact text verbatim plus every referenced media object.
-* The root artifact sits under its original base name (`session.jsonl`); each
-* subagent descendant under `subagents/<id>/<filename>`; each image referenced
-* by any included log under `media/<attachmentId>.<ext>` (content-addressed,
-* so one archive never duplicates a shared image). No manifest is written —
-* every file is byte-identical to the backend's durable artifact or attachment
-* store and self-describing through its own header line or media type. Before
-* each live session's artifact read, the SessionStore flush barrier makes the
-* current in-memory log durable; cold sessions need no barrier. Request abort
-* and response-consumer cancellation share one producer signal and terminate
-* the active compressor.
-* Compression runs on the host with fflate's streaming Zip API, so the archive
-* bytes are produced incrementally and the host never holds the whole archive
-* in one buffer; production waits for consumer pull whenever the response queue
-* reaches its byte high-water mark, so a slow consumer bounds accumulation to
-* the fixed 64 KiB response queue plus one synchronous fflate push.
-* @module @lingxi-ai-cn/dsh-session-export/zip
-*/
-/** Balanced default used when a deployment omits compression config. */
-const DEFAULT_SESSION_LOG_COMPRESSION_LEVEL = 6;
-/**
-* Resolve the persistence, session-query, and attachment services a log export needs.
-* @param ctx - the composed host context.
-* @returns the export services (absent when the deployment does not mount them).
-*/
-function sessionLogExportDeps(ctx) {
-	return {
-		sessionQuery: ctx.get("sessionQuery"),
-		sessionPersistence: ctx.get("sessionPersistence"),
-		attachments: ctx.get("attachments"),
-		sessions: ctx.get("sessions")
-	};
-}
-/**
-* Flush one currently live session through the store's authoritative durability
-* barrier immediately before its raw artifact is read. A cold or absent id has
-* no in-memory work to flush.
-* @param deps - export services, including the optional live-session store.
-* @param id - the session whose artifact is about to be read.
-* @param signal - optional cancellation observed around the flush barrier.
-*/
-async function flushLiveSessionLog(deps, id, signal) {
-	signal?.throwIfAborted();
-	const sessions = deps.sessions;
-	if (sessions === void 0) return;
-	const session = sessions.get(id);
-	if (session === void 0) return;
-	await sessions.flush(session);
-	signal?.throwIfAborted();
-}
-/** Zip extension for each accepted raster media type. */
-const MEDIA_TYPE_EXTENSIONS = {
-	"image/png": "png",
-	"image/jpeg": "jpg",
-	"image/webp": "webp",
-	"image/gif": "gif"
-};
-/**
-* The zip path for one media object: content-addressed by the opaque
-* attachment id so shared images land once and the id in the log maps back to
-* the archive entry without a manifest.
-* @param ref - the durable reference from a session log.
-* @returns the archive path.
-*/
-function mediaEntryPath(ref) {
-	return `media/${String(ref.attachmentId)}.${MEDIA_TYPE_EXTENSIONS[ref.mediaType]}`;
-}
-/**
-* Collect every image reference inside one content array, descending into
-* nested tool results the way the live attachment route does.
-* @param content - an event content array (or nested tool-result content).
-* @param refs - the dedupe map being filled (keyed by attachment id).
-*/
-function collectImageRefs(content, refs) {
-	if (!Array.isArray(content)) return;
-	const pending = [];
-	for (const item of content) pending.push(item);
-	while (pending.length > 0) {
-		const value = pending.pop();
-		if (typeof value !== "object" || value === null || Array.isArray(value)) continue;
-		const block = value;
-		if (block.type === "image" && typeof block.attachment === "object" && block.attachment !== null) {
-			const ref = block.attachment;
-			refs.set(String(ref.attachmentId), ref);
-		}
-		if (Array.isArray(block.content)) for (const item of block.content) pending.push(item);
-	}
-}
-/**
-* Collect every image reference one session event carries, across the same
-* carriers the live attachment route scans (direct content, message content,
-* inserted messages, and completed assistant chunk blocks).
-* @param event - one parsed JSONL event object.
-* @param refs - the dedupe map being filled (keyed by attachment id).
-*/
-function collectEventImageRefs(event, refs) {
-	const data = event.data;
-	if (typeof data !== "object" || data === null) return;
-	const carrier = data;
-	collectImageRefs(carrier.content, refs);
-	if (carrier.message !== void 0) collectImageRefs(carrier.message.content, refs);
-	if (carrier.inserted !== void 0) for (const message of carrier.inserted) collectImageRefs(message.content, refs);
-	if (carrier.chunk?.type === "block-end") collectImageRefs([carrier.chunk.block], refs);
-}
-/**
-* Collect the distinct media references one stored artifact text names.
-* Lines that fail to parse cannot reference media and are skipped (the
-* artifact text itself is exported verbatim regardless).
-* @param content - the stored artifact text.
-* @returns the dedupe map keyed by attachment id.
-*/
-function imageRefsInArtifact(content) {
-	const refs = /* @__PURE__ */ new Map();
-	for (const line of content.split("\n")) {
-		if (line === "") continue;
-		let event;
-		try {
-			event = JSON.parse(line);
-		} catch {
-			continue;
-		}
-		collectEventImageRefs(event, refs);
-	}
-	return refs;
-}
-/**
-* One safe zip path segment from an untrusted session id. Session ids are
-* host-controlled, but the brand allows any non-empty string, so `../`, dot
-* segments, and separator characters are neutralized before they can shape
-* archive entries. Distinct ids may collapse onto one segment (id collision
-* is impossible for the host-minted UUIDs, so no uniqueness suffix is kept).
-* @param id - the raw session id.
-* @returns a filesystem-safe single path segment.
-*/
-function safeSessionIdSegment(id) {
-	return id.replace(/[^A-Za-z0-9_-]/g, "_");
-}
-/**
-* The export archive filename for one root session.
-* @param sessionId - the root session id (sanitized to one safe path segment).
-* @returns the attachment filename for the session's export archive.
-*/
-function sessionLogZipFilename(sessionId) {
-	return `dsh-session-${safeSessionIdSegment(sessionId)}.zip`;
-}
-/**
-* Yield the export entries in zip order: the preloaded root artifact first,
-* then every subagent descendant in lineage order (each flushed when live,
-* read from the persistence backend right before it is yielded, and dropped
-* after the consumer moves on), then every distinct media object referenced by any of
-* the included logs (read and verified from the attachment store, one archive
-* entry per attachment id). The host holds at most one descendant's artifact
-* text and one media object at a time beyond the root.
-* @param deps - the mounted export services (the caller answered 500 before this runs).
-* @param root - the already-read root artifact (read by the caller so the
-* missing-session path can answer cleanly before streaming starts).
-* @param sessionId - the root session id.
-* @param includeDescendants - whether to include every subagent descendant.
-* @param signal - optional cancellation forwarded to lineage, persistence, and attachment reads.
-* @returns the export entries in zip order.
-*/
-async function* sessionLogZipEntries(deps, root, sessionId, includeDescendants, signal) {
-	const media = /* @__PURE__ */ new Map();
-	const rememberMedia = (content) => {
-		for (const [id, ref] of imageRefsInArtifact(content)) media.set(id, ref);
-	};
-	rememberMedia(root.content);
-	yield {
-		path: root.filename,
-		content: root.content
-	};
-	if (includeDescendants) {
-		const seen = /* @__PURE__ */ new Set([sessionId]);
-		const collect = async function* (nodes) {
-			for (const node of nodes) {
-				signal?.throwIfAborted();
-				const id = node.session.header.id;
-				if (seen.has(id)) continue;
-				seen.add(id);
-				await flushLiveSessionLog(deps, id, signal);
-				const raw = await deps.sessionPersistence.readRaw(id, signal);
-				signal?.throwIfAborted();
-				if (raw === void 0) throw new Error(`subagent "${id}" has no stored log artifact`);
-				rememberMedia(raw.content);
-				yield {
-					path: `subagents/${safeSessionIdSegment(id)}/${raw.filename}`,
-					content: raw.content
-				};
-				yield* collect(node.descendants);
-			}
-		};
-		const lineage = await deps.sessionQuery.traceSession(sessionId, signal);
-		signal?.throwIfAborted();
-		yield* collect(lineage.descendants);
-	}
-	for (const ref of media.values()) {
-		signal?.throwIfAborted();
-		const stored = await deps.attachments.readImage(ref, signal);
-		signal?.throwIfAborted();
-		yield {
-			path: mediaEntryPath(ref),
-			data: stored.data
-		};
-	}
-}
-/** How many code units of artifact text one zip push carries (bounded encode memory). */
-const PUSH_CHUNK_CODE_UNITS = 65536;
-/** How many bytes of media one zip push carries (bounded memory; images are already size-capped). */
-const PUSH_CHUNK_BYTES = 65536;
-/** Byte capacity retained by the response stream before ZIP production waits for pull. */
-const RESPONSE_HIGH_WATER_MARK_BYTES = 65536;
-/** One producer waiter released only when ReadableStream pull restores capacity. */
-var ResponseCapacityGate = class {
-	releasePending;
-	/**
-	* Wait until the response queue has positive byte capacity or cancellation wins.
-	* @param controller - response controller whose desired size owns capacity.
-	* @param signal - combined request/consumer cancellation.
-	*/
-	async wait(controller, signal) {
-		signal.throwIfAborted();
-		if (controller.desiredSize === null || controller.desiredSize > 0) return;
-		await new Promise((resolve) => {
-			const release = () => {
-				this.releasePending = void 0;
-				signal.removeEventListener("abort", release);
-				resolve();
-			};
-			this.releasePending = release;
-			signal.addEventListener("abort", release, { once: true });
-		});
-		signal.throwIfAborted();
-	}
-	/** Release the current producer waiter after a consumer pull. */
-	pulled() {
-		this.releasePending?.();
-	}
-};
-/**
-* Push one media object's bytes into a deflate stream in bounded chunks,
-* waiting for consumer capacity between chunks like the artifact path does.
-* @param deflate - the zip entry's deflate stream.
-* @param data - the stored image bytes.
-* @param controller - response queue controller.
-* @param capacity - pull-driven response-capacity gate.
-* @param signal - cancellation; throws when aborted.
-*/
-async function pushBinaryChunks(deflate, data, controller, capacity, signal) {
-	let offset = 0;
-	do {
-		signal.throwIfAborted();
-		const end = Math.min(offset + PUSH_CHUNK_BYTES, data.byteLength);
-		const finalChunk = end >= data.byteLength;
-		deflate.push(data.subarray(offset, end), finalChunk);
-		offset = end;
-		await capacity.wait(controller, signal);
-	} while (offset < data.byteLength);
-}
-/**
-* Push one artifact's text into a deflate stream in bounded chunks, never
-* splitting a surrogate pair across a chunk boundary (a lone high surrogate
-* re-encodes as U+FFFD and would silently corrupt the exported artifact).
-* @param deflate - the zip entry's deflate stream.
-* @param content - the artifact text verbatim.
-* @param controller - response queue controller.
-* @param capacity - pull-driven response-capacity gate.
-* @param signal - cancellation; throws when aborted.
-*/
-async function pushArtifactChunks(deflate, content, controller, capacity, signal) {
-	const encoder = new TextEncoder();
-	let offset = 0;
-	let finalChunk;
-	do {
-		signal.throwIfAborted();
-		let end = Math.min(offset + PUSH_CHUNK_CODE_UNITS, content.length);
-		if (end < content.length && end - offset > 1) {
-			const last = content.charCodeAt(end - 1);
-			if (last >= 55296 && last <= 56319) end -= 1;
-		}
-		finalChunk = end >= content.length;
-		deflate.push(encoder.encode(content.slice(offset, end)), finalChunk);
-		offset = end;
-		await capacity.wait(controller, signal);
-	} while (!finalChunk);
-}
-/**
-* Stream one session-log ZIP as a WHATWG ReadableStream. The root artifact is
-* read and validated by the caller before this is called (missing root or
-* missing services answer cleanly before any byte is produced); each entry is
-* then encoded and deflated in bounded chunks as it is produced, so the
-* archive bytes arrive incrementally. A descendant that fails to read errors
-* the stream (fail-loud, never silent under-export).
-* @param deps - the mounted export services (the caller answered 500 before this runs).
-* @param root - the already-read root artifact (first zip entry).
-* @param sessionId - the root session id.
-* @param includeDescendants - whether to include every subagent descendant.
-* @param compressionLevel - validated fflate DEFLATE level for every ZIP entry.
-* @param signal - request cancellation combined with response-consumer cancellation.
-* @returns the zip byte stream.
-*/
-function streamSessionLogZip(deps, root, sessionId, includeDescendants, compressionLevel, signal) {
-	const consumerAbort = new AbortController();
-	const producerSignal = AbortSignal.any([signal, consumerAbort.signal]);
-	let zip;
-	let zipTerminated = false;
-	const capacity = new ResponseCapacityGate();
-	const terminateZip = () => {
-		if (zip === void 0 || zipTerminated) return;
-		zipTerminated = true;
-		zip.terminate();
-	};
-	return new ReadableStream({
-		start(controller) {
-			const archive = new Zip((error, data, final) => {
-				/* v8 ignore next 3 -- fflate reports only internal zip failures, unreachable for valid inputs */
-				if (error) {
-					controller.error(error);
-					return;
-				}
-				/* v8 ignore next -- fflate may emit empty chunks; not controllable from tests */
-				if (data.byteLength > 0) controller.enqueue(data);
-				if (final) controller.close();
-			});
-			zip = archive;
-			(async () => {
-				try {
-					for await (const entry of sessionLogZipEntries(deps, root, sessionId, includeDescendants, producerSignal)) {
-						const deflate = new ZipDeflate(entry.path, { level: compressionLevel });
-						archive.add(deflate);
-						if ("content" in entry) await pushArtifactChunks(deflate, entry.content, controller, capacity, producerSignal);
-						else await pushBinaryChunks(deflate, entry.data, controller, capacity, producerSignal);
-					}
-					archive.end();
-				} catch (error) {
-					/* v8 ignore next -- typed backends reject with Error, and DOMException is one in Node */
-					terminateZip();
-					controller.error(error instanceof Error ? error : new Error(String(error)));
-				}
-			})();
-		},
-		pull() {
-			capacity.pulled();
-		},
-		cancel(reason) {
-			consumerAbort.abort(reason instanceof Error ? reason : /* @__PURE__ */ new Error("session log export stream cancelled"));
-			terminateZip();
-		}
-	}, {
-		highWaterMark: RESPONSE_HIGH_WATER_MARK_BYTES,
-		size: (chunk) => chunk.byteLength
-	});
-}
-//#endregion
 //#region lib/types/markdown.js
 /** Human-readable Markdown projection for durable Session history. */
 /**
@@ -565,9 +209,9 @@ function formatTime(value) {
 //#endregion
 //#region lib/types/index.js
 /**
-* Host session-log export service: prepares the canonical stored-artifact ZIP,
-* exposes it as a bounded byte stream, and publishes complete archives into a
-* host directory without exposing a partial final file.
+* Native Session-log export service: reuses the official canonical ZIP stream
+* and publishes complete archives into a host directory without exposing a
+* partial final file.
 * @module @lingxi-ai-cn/dsh-session-export
 */
 /** Typed session-log export failure with a consumer-safe message. */
@@ -595,7 +239,7 @@ var SessionLogExportError = class extends Error {
 */
 async function prepareSessionLogExport(ctx, sessionId, signal) {
 	signal.throwIfAborted();
-	const deps = sessionLogExportDeps(ctx);
+	const deps = sessionLogExportDeps$1(ctx);
 	if (deps.sessionQuery === void 0 || deps.sessionPersistence === void 0 || deps.attachments === void 0) throw new SessionLogExportError("services-unavailable", "session log export is unavailable: missing session-query, session-persistence, or attachments service");
 	if (!deps.sessionPersistence.supportsRawArtifacts) throw new SessionLogExportError("raw-artifacts-unsupported", "session log export is unavailable: the persistence backend does not expose per-session raw artifacts");
 	const ready = {
@@ -606,7 +250,7 @@ async function prepareSessionLogExport(ctx, sessionId, signal) {
 	};
 	let root;
 	try {
-		await flushLiveSessionLog(deps, sessionId, signal);
+		await flushLiveSessionLog$1(deps, sessionId, signal);
 		root = await deps.sessionPersistence.readRaw(sessionId, signal);
 		signal.throwIfAborted();
 	} catch (error) {
@@ -665,11 +309,11 @@ var SessionLogExporter = class extends Service {
 		"sessionQuery",
 		"sessions"
 	];
-	static Config = z.object({ compressionLevel: z.number().step(1).min(0).max(9).default(6) });
+	static Config = z.object({ compressionLevel: z.number().step(1).min(0).max(9).default(DEFAULT_SESSION_LOG_COMPRESSION_LEVEL$1) });
 	compressionLevel;
 	constructor(ctx, config) {
 		super(ctx, "sessionLogExporter");
-		this.compressionLevel = config.compressionLevel ?? 6;
+		this.compressionLevel = config.compressionLevel ?? DEFAULT_SESSION_LOG_COMPRESSION_LEVEL$1;
 	}
 	/**
 	* Prepare and expose one bounded ZIP byte stream.
@@ -680,8 +324,8 @@ var SessionLogExporter = class extends Service {
 	async stream(request, signal) {
 		const prepared = await prepareSessionLogExport(this.ctx, request.sessionId, signal);
 		return {
-			filename: sessionLogZipFilename(request.sessionId),
-			stream: streamSessionLogZip(prepared.ready, prepared.root, request.sessionId, request.includeDescendants, this.compressionLevel, signal)
+			filename: sessionLogZipFilename$1(request.sessionId),
+			stream: streamSessionLogZip$1(prepared.ready, prepared.root, request.sessionId, request.includeDescendants, this.compressionLevel, signal)
 		};
 	}
 	/**
@@ -736,9 +380,9 @@ var SessionLogExporter = class extends Service {
 	}
 	/**
 	* Render a summary-only human-readable Markdown projection and publish it
-	* atomically under the first available safe filename. The raw ZIP remains
-	* the diagnostic source of truth; tool arguments are omitted and attachment
-	* references are never copied into the Markdown file.
+	* atomically under the first available safe filename. The official raw ZIP
+	* remains the diagnostic source of truth; tool arguments are omitted and
+	* attachment bytes are never copied into the Markdown file.
 	* @param request - root identity, descendant policy, and explicit attachment policy.
 	* @param directory - existing absolute host directory chosen by the operator.
 	* @param signal - complete projection, writing, and publication lifetime.

package/lib/types/index.d.ts

@@ -1,17 +1,17 @@
 /**
- * Host session-log export service: prepares the canonical stored-artifact ZIP,
- * exposes it as a bounded byte stream, and publishes complete archives into a
- * host directory without exposing a partial final file.
+ * Native Session-log export service: reuses the official canonical ZIP stream
+ * and publishes complete archives into a host directory without exposing a
+ * partial final file.
  * @module @lingxi-ai-cn/dsh-session-export
  */
 import { Context, Service } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import type { SessionId } from '@deepseek-ai/dsh-session';
 import type { SessionRawArtifact } from '@deepseek-ai/dsh-session-persistence';
-import { type SessionLogCompressionLevel, type SessionLogExportReady } from './zip.ts';
+import { type SessionLogCompressionLevel, type SessionLogExportReady } from '@deepseek-ai/dsh-session-log-export';
 import type { SessionMarkdownExportRequest } from './markdown.ts';
-export { DEFAULT_SESSION_LOG_COMPRESSION_LEVEL, flushLiveSessionLog, sessionLogExportDeps, sessionLogZipEntries, sessionLogZipFilename, streamSessionLogZip, } from './zip.ts';
-export type { SessionLogCompressionLevel, SessionLogExportDeps, SessionLogExportReady, SessionLogZipEntry, } from './zip.ts';
+export { DEFAULT_SESSION_LOG_COMPRESSION_LEVEL, flushLiveSessionLog, sessionLogExportDeps, sessionLogZipEntries, sessionLogZipFilename, streamSessionLogZip, } from '@deepseek-ai/dsh-session-log-export';
+export type { SessionLogCompressionLevel, SessionLogExportDeps, SessionLogExportReady, SessionLogZipEntry, } from '@deepseek-ai/dsh-session-log-export';
 export { renderSessionMarkdown, sessionMarkdownExportDeps, sessionMarkdownFilename, } from './markdown.ts';
 export type { SessionMarkdownAttachmentPolicy, SessionMarkdownExportDeps, SessionMarkdownExportRequest, SessionMarkdownSessionStore, } from './markdown.ts';
 /** Stable failure categories shared by the native writer and host transports. */
@@ -105,9 +105,9 @@ export default class SessionLogExporter extends Service {
     writeToDirectory(request: SessionLogExportRequest, directory: string, signal: AbortSignal): Promise<SessionLogExportFile>;
     /**
      * Render a summary-only human-readable Markdown projection and publish it
-     * atomically under the first available safe filename. The raw ZIP remains
-     * the diagnostic source of truth; tool arguments are omitted and attachment
-     * references are never copied into the Markdown file.
+     * atomically under the first available safe filename. The official raw ZIP
+     * remains the diagnostic source of truth; tool arguments are omitted and
+     * attachment bytes are never copied into the Markdown file.
      * @param request - root identity, descendant policy, and explicit attachment policy.
      * @param directory - existing absolute host directory chosen by the operator.
      * @param signal - complete projection, writing, and publication lifetime.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lingxi-ai-cn/dsh-session-export",
-  "description": "Host-owned streaming Session ZIP producer and atomic path writer",
-  "version": "0.1.6-rc.8",
+  "description": "Native atomic path writer over the official Session ZIP producer",
+  "version": "0.1.7-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -30,17 +30,16 @@
     "lib/types/**/*.d.ts"
   ],
   "license": "MIT",
-  "dependencies": {
-    "fflate": "^0.8.2"
-  },
+  "dependencies": {},
   "peerDependencies": {
-    "@deepseek-ai/cordis": "4.0.1",
-    "@deepseek-ai/dsh-attachment": "0.1.0-rc.8",
-    "@deepseek-ai/dsh-invariants": "0.1.0-rc.8",
-    "@deepseek-ai/dsh-session": "0.1.0-rc.8",
-    "@deepseek-ai/dsh-session-persistence": "0.1.0-rc.8",
-    "@deepseek-ai/dsh-session-query": "0.1.0-rc.8",
-    "@deepseek-ai/schemastery": "3.18.1"
+    "@deepseek-ai/cordis": "4.0.2",
+    "@deepseek-ai/dsh-attachment": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-invariants": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session-log-export": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session-persistence": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session-query": "0.1.2-alpha.2",
+    "@deepseek-ai/schemastery": "3.18.2"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/cordis": {
@@ -55,6 +54,9 @@
     "@deepseek-ai/dsh-session": {
       "optional": true
     },
+    "@deepseek-ai/dsh-session-log-export": {
+      "optional": true
+    },
     "@deepseek-ai/dsh-session-persistence": {
       "optional": true
     },
@@ -66,13 +68,15 @@
     }
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "4.0.1",
-    "@deepseek-ai/dsh-attachment": "0.1.0-rc.8",
-    "@deepseek-ai/dsh-invariants": "0.1.0-rc.8",
-    "@deepseek-ai/dsh-llm": "0.1.0-rc.8",
-    "@deepseek-ai/dsh-session": "0.1.0-rc.8",
-    "@deepseek-ai/dsh-session-persistence": "0.1.0-rc.8",
-    "@deepseek-ai/dsh-session-query": "0.1.0-rc.8",
-    "@deepseek-ai/schemastery": "3.18.1"
+    "@deepseek-ai/cordis": "4.0.2",
+    "@deepseek-ai/dsh-attachment": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-invariants": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-llm": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session-log-export": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session-persistence": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session-query": "0.1.2-alpha.2",
+    "@deepseek-ai/schemastery": "3.18.2",
+    "fflate": "^0.8.2"
   }
 }

package/lib/types/zip.d.ts

@@ -1,106 +0,0 @@
-/**
- * Host-side Session ZIP producer: streams one archive whose files are the
- * sessions' stored artifact text verbatim plus every referenced media object.
- * The root artifact sits under its original base name (`session.jsonl`); each
- * subagent descendant under `subagents/<id>/<filename>`; each image referenced
- * by any included log under `media/<attachmentId>.<ext>` (content-addressed,
- * so one archive never duplicates a shared image). No manifest is written —
- * every file is byte-identical to the backend's durable artifact or attachment
- * store and self-describing through its own header line or media type. Before
- * each live session's artifact read, the SessionStore flush barrier makes the
- * current in-memory log durable; cold sessions need no barrier. Request abort
- * and response-consumer cancellation share one producer signal and terminate
- * the active compressor.
- * Compression runs on the host with fflate's streaming Zip API, so the archive
- * bytes are produced incrementally and the host never holds the whole archive
- * in one buffer; production waits for consumer pull whenever the response queue
- * reaches its byte high-water mark, so a slow consumer bounds accumulation to
- * the fixed 64 KiB response queue plus one synchronous fflate push.
- * @module @lingxi-ai-cn/dsh-session-export/zip
- */
-import type { Context } from '@deepseek-ai/cordis';
-import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
-import type { SessionQueryEngine } from '@deepseek-ai/dsh-session-query';
-import type { SessionId, SessionStore } from '@deepseek-ai/dsh-session';
-import type { SessionPersistence, SessionRawArtifact } from '@deepseek-ai/dsh-session-persistence';
-/** Valid fflate DEFLATE levels accepted by session-log export. */
-export type SessionLogCompressionLevel = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
-/** Balanced default used when a deployment omits compression config. */
-export declare const DEFAULT_SESSION_LOG_COMPRESSION_LEVEL: SessionLogCompressionLevel;
-/** The services a session-log export needs (the live-session store is optional). */
-export interface SessionLogExportDeps {
-    readonly sessionQuery: SessionQueryEngine | undefined;
-    readonly sessionPersistence: SessionPersistence | undefined;
-    readonly attachments: AttachmentStore | undefined;
-    readonly sessions: SessionStore | undefined;
-}
-/** The export services narrowed to the mounted ones streaming actually reads. */
-export interface SessionLogExportReady {
-    readonly sessionQuery: SessionQueryEngine;
-    readonly sessionPersistence: SessionPersistence;
-    readonly attachments: AttachmentStore;
-    readonly sessions: SessionStore | undefined;
-}
-/**
- * Resolve the persistence, session-query, and attachment services a log export needs.
- * @param ctx - the composed host context.
- * @returns the export services (absent when the deployment does not mount them).
- */
-export declare function sessionLogExportDeps(ctx: Context): SessionLogExportDeps;
-/**
- * Flush one currently live session through the store's authoritative durability
- * barrier immediately before its raw artifact is read. A cold or absent id has
- * no in-memory work to flush.
- * @param deps - export services, including the optional live-session store.
- * @param id - the session whose artifact is about to be read.
- * @param signal - optional cancellation observed around the flush barrier.
- */
-export declare function flushLiveSessionLog(deps: Pick<SessionLogExportDeps, 'sessions'>, id: SessionId, signal?: AbortSignal): Promise<void>;
-/** One exported file: a stored artifact text or one referenced media object. */
-export type SessionLogZipEntry = {
-    readonly path: string;
-    readonly content: string;
-} | {
-    readonly path: string;
-    readonly data: Uint8Array;
-};
-/**
- * The export archive filename for one root session.
- * @param sessionId - the root session id (sanitized to one safe path segment).
- * @returns the attachment filename for the session's export archive.
- */
-export declare function sessionLogZipFilename(sessionId: string): string;
-/**
- * Yield the export entries in zip order: the preloaded root artifact first,
- * then every subagent descendant in lineage order (each flushed when live,
- * read from the persistence backend right before it is yielded, and dropped
- * after the consumer moves on), then every distinct media object referenced by any of
- * the included logs (read and verified from the attachment store, one archive
- * entry per attachment id). The host holds at most one descendant's artifact
- * text and one media object at a time beyond the root.
- * @param deps - the mounted export services (the caller answered 500 before this runs).
- * @param root - the already-read root artifact (read by the caller so the
- * missing-session path can answer cleanly before streaming starts).
- * @param sessionId - the root session id.
- * @param includeDescendants - whether to include every subagent descendant.
- * @param signal - optional cancellation forwarded to lineage, persistence, and attachment reads.
- * @returns the export entries in zip order.
- */
-export declare function sessionLogZipEntries(deps: SessionLogExportReady, root: SessionRawArtifact, sessionId: SessionId, includeDescendants: boolean, signal?: AbortSignal): AsyncGenerator<SessionLogZipEntry>;
-/**
- * Stream one session-log ZIP as a WHATWG ReadableStream. The root artifact is
- * read and validated by the caller before this is called (missing root or
- * missing services answer cleanly before any byte is produced); each entry is
- * then encoded and deflated in bounded chunks as it is produced, so the
- * archive bytes arrive incrementally. A descendant that fails to read errors
- * the stream (fail-loud, never silent under-export).
- * @param deps - the mounted export services (the caller answered 500 before this runs).
- * @param root - the already-read root artifact (first zip entry).
- * @param sessionId - the root session id.
- * @param includeDescendants - whether to include every subagent descendant.
- * @param compressionLevel - validated fflate DEFLATE level for every ZIP entry.
- * @param signal - request cancellation combined with response-consumer cancellation.
- * @returns the zip byte stream.
- */
-export declare function streamSessionLogZip(deps: SessionLogExportReady, root: SessionRawArtifact, sessionId: SessionId, includeDescendants: boolean, compressionLevel: SessionLogCompressionLevel, signal: AbortSignal): ReadableStream<Uint8Array>;
-//# sourceMappingURL=zip.d.ts.map