@xneog/dsh-session-format 0.1.3-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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-format/README.md
+README.md: 7c1c00bb3bace78ae9a38c9a6ddea13f0eff536f
+README.zh.md: 9171f554bdf8deee2fe0136cc253742025e3619c

package/README.md

@@ -0,0 +1,105 @@
+---
+description: "Pure adjacent Session format planning, lossless JSON snapshots, header-only migration, and physical codec dispatch."
+kind: "package-library"
+---
+
+# @xneog/dsh-session-format
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`dsh-session-format` lets persistence code restore a current Session directly or compose a unique sequence of adjacent whole-artifact migrations. It snapshots every durable input and output as detached lossless JSON, validates exact version progress, and keeps header-only listing separate from body reads. Physical framing, compression, immutable generation naming, exclusive publication, and Cordis lifecycle behavior remain outside this pure library.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+### When to use it
+
+Use this library from persistence or format-catalog code that must classify a physical Session header, restore current logical values, or compose released adjacent migrations. It is not a Cordis plugin and has no profile mount row. No runtime invariant companion is published because every operation validates its borrowed artifact before returning and retains no cross-call mutable state.
+
+### Entry point
+
+```text
+const catalog = createSessionFormatCatalog({ currentVersion, codecs, encodeCurrentArtifact, migrations, restoreCurrent, restoreCurrentHeader })
+const descriptor = catalog.readHeader(physicalHeader)
+```
+
+`createSessionFormatCatalog()` accepts one frozen decoder per supported version, the current format's encoder, one migration per adjacent version pair, and current artifact and header restorers. `readHeader()` returns a `current`, `migration-required`, `unsupported`, or `malformed` descriptor without reading events. Each edge validates its target header before the final current-header restorer runs. Body readers call `decodeArtifact()` or `decodeRecoverableArtifact()`, then `migrate()`; writers call `encodeCurrent()` only with a validated current artifact. Frozen v0/v1 codec exports retain their format-specific `packChunks` option without adding that historical control to the current writer or common decoder interface.
+
+The recoverable decoder returns the accepted logical prefix. A codec may drop one malformed or sequence-gapped row and its uncommitted suffix, but a later decoded `turn/end` makes the original issue fatal.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+The chain validates unique gap-free ordering at construction. A current artifact bypasses every migration callback and passes through only the current restorer. An old artifact runs each adjacent whole-document function in memory; only the caller decides whether and how to publish the final result.
+
+| File | Role |
+|---|---|
+| [`src/chain.ts`](src/chain.ts) | Adjacent plan construction and current bypass |
+| [`src/catalog.ts`](src/catalog.ts) | Physical version dispatch and header classification |
+| [`src/json.ts`](src/json.ts) | Detached lossless JSON snapshots and common coordinate checks |
+| [`src/filename.ts`](src/filename.ts) | Canonical `session[.vN].jsonl` basename shared by persistence, export, and fixtures |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Released v0 to v1 edge](../session-format-v0-to-v1/README.md) — frozen historical decoding and identity conversion.
+- [Static catalog](../session-format-catalog/README.md) — first-party codec and migration assembly.
+- [JSONL persistence](../session-persistence-jsonl/README.md) — durable framing and generation publication.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Session restoration
+
+#### What the model sees
+
+Nothing directly. Consumers reconstruct model history from the validated current artifact through `deriveMessages()`.
+
+#### Token effect
+
+Zero direct tokens.
+
+#### KV Cache effect
+
+No direct effect. A migration that changes current history can change the cache identity owned by request reconstruction.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **Whole-artifact memory use** — supported migrations materialize the complete logical Session; streamed transformation is deferred until measured artifacts require it.
+- **Adjacent integer versions only** — the library does not expose spans, stable event identities, or a general reference-rewrite algebra.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,105 @@
+---
+description: "纯函数式相邻 Session 格式规划、无损 JSON 快照、仅标头迁移与物理编解码分派。"
+kind: "package-library"
+---
+
+# @xneog/dsh-session-format
+
+[English](README.md) | 中文
+
+## 概述
+
+`dsh-session-format` 让持久化代码可以直接还原当前 Session，或组合唯一的相邻全产物迁移序列。它会把每个持久化输入和输出快照为分离的无损 JSON，校验精确的版本推进，并把仅标头的列表读取与正文读取分开。物理分帧、压缩、不可变 generation 命名、排他发布和 Cordis 生命周期行为不属于这个纯函数库。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+### 何时使用
+
+当持久化或格式目录代码需要分类物理 Session header、还原当前逻辑值或组合已发布相邻迁移时，使用本库。它不是 Cordis 插件，也没有 profile 挂载行。它不发布运行时不变式伴生入口，因为每个操作都会在返回前校验借入的完整 artifact，且不保留跨调用的可变状态。
+
+### 入口
+
+```text
+const catalog = createSessionFormatCatalog({ currentVersion, codecs, encodeCurrentArtifact, migrations, restoreCurrent, restoreCurrentHeader })
+const descriptor = catalog.readHeader(physicalHeader)
+```
+
+`createSessionFormatCatalog()` 接收每个受支持版本的一个冻结解码器、当前格式的编码器、每组相邻版本的一个迁移，以及当前产物与标头还原器。`readHeader()` 在不读取事件的情况下返回 `current`、`migration-required`、`unsupported` 或 `malformed` 描述符。每个迁移边会先校验自己的目标标头，然后再运行最终的当前标头还原器。正文读取方调用 `decodeArtifact()` 或 `decodeRecoverableArtifact()`，然后调用 `migrate()`；写入方只使用经过校验的当前产物调用 `encodeCurrent()`。冻结的 v0/v1 编解码器导出会保留其格式专用的 `packChunks` 选项，但不会把这项历史控制加入当前 writer 或通用解码器接口。
+
+可恢复解码器返回已接受的逻辑前缀。编解码器可以丢弃一个格式错误或序号不连续的行及其未提交后缀，但后续成功解码的 `turn/end` 会使原始问题成为致命错误。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+迁移链在构造时校验唯一且无缺口的顺序。当前产物绕过所有迁移回调，只经过当前格式还原器。旧产物在内存中依次运行每个相邻的全产物函数；只有调用方决定是否发布最终结果以及如何发布。
+
+| 文件 | 职责 |
+|---|---|
+| [`src/chain.ts`](src/chain.ts) | 相邻计划构造与当前格式绕过 |
+| [`src/catalog.ts`](src/catalog.ts) | 物理版本分派与标头分类 |
+| [`src/json.ts`](src/json.ts) | 分离的无损 JSON 快照与通用坐标校验 |
+| [`src/filename.ts`](src/filename.ts) | 持久化、导出与 fixture 共用的规范 `session[.vN].jsonl` 文件名 |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+- [已发布 v0 到 v1 迁移边](../session-format-v0-to-v1/README.zh.md)——冻结的历史解码与恒等转换。
+- [静态目录](../session-format-catalog/README.zh.md)——第一方编解码器与迁移装配。
+- [JSONL 持久化](../session-persistence-jsonl/README.zh.md)——持久化分帧与代际发布。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### Session 还原
+
+#### 模型看到什么
+
+没有直接内容。消费方通过 `deriveMessages()` 从经过校验的当前产物重建模型历史。
+
+#### Token 影响
+
+不直接产生 token。
+
+#### KV Cache 影响
+
+没有直接影响。迁移若改变当前历史，可能改变由请求重建逻辑拥有的缓存身份。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **全产物内存占用**——受支持的迁移会物化完整逻辑 Session；只有实测产物规模提出要求时，才会引入流式转换。
+- **仅支持相邻整数版本**——本库不暴露 span、稳定事件身份或通用引用重写代数。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,356 @@
+import { deepFreeze, snapshotJsonValue } from "@xneog/dsh-util-values";
+//#region lib/types/error.js
+/** Error raised when a durable Session artifact cannot be restored or migrated losslessly. */
+var SessionFormatError = class extends Error {
+	name = "SessionFormatError";
+};
+/** A readable artifact whose released source policy has no supported migration. */
+var SessionFormatUnsupportedMigrationError = class extends SessionFormatError {
+	name = "SessionFormatUnsupportedMigrationError";
+};
+//#endregion
+//#region lib/types/json.js
+/**
+* Test whether a value is a non-null, non-array object.
+* @param value - candidate value.
+* @returns whether the value is an object record.
+*/
+function isSessionFormatJsonObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Require a non-negative safe integer without the JSON-unstable negative zero.
+* @param value - candidate count.
+* @param label - diagnostic subject.
+* @returns validated count.
+*/
+function sessionFormatCount(value, label) {
+	if (!Number.isSafeInteger(value) || value < 0 || Object.is(value, -0)) throw new SessionFormatError(`${label} must be a non-negative safe integer`);
+	return value;
+}
+/**
+* Require a safe integer without the JSON-unstable negative zero.
+* @param value - candidate integer.
+* @param label - diagnostic subject.
+* @returns validated integer.
+*/
+function sessionFormatSafeInteger(value, label) {
+	if (!Number.isSafeInteger(value) || Object.is(value, -0)) throw new SessionFormatError(`${label} must be a safe integer`);
+	return value;
+}
+/**
+* Require a non-negative integral format version.
+* @param value - candidate version.
+* @param label - diagnostic subject.
+* @returns validated version.
+*/
+function sessionFormatVersion(value, label = "Session format version") {
+	return sessionFormatCount(value, label);
+}
+/**
+* Read only the version required for directional dispatch.
+* @param headerValue - untrusted physical header value.
+* @returns validated stored version.
+*/
+function inspectSessionFormatVersion(headerValue) {
+	if (!isSessionFormatJsonObject(headerValue)) throw new SessionFormatError("Session header must be a JSON object");
+	return sessionFormatVersion(headerValue["version"]);
+}
+/**
+* Detach and deeply freeze a caller-supplied lossless JSON value.
+* @param value - borrowed candidate.
+* @param label - diagnostic subject.
+* @returns an immutable detached JSON snapshot.
+*/
+function snapshotSessionFormatJson(value, label = "Session value") {
+	const snapshot = snapshotJsonValue(value);
+	if (snapshot === void 0) throw new SessionFormatError(`${label} is not lossless JSON`);
+	return deepFreeze(snapshot);
+}
+/**
+* Snapshot one complete artifact and validate its shared coordinates.
+* @param artifact - borrowed logical artifact.
+* @param label - diagnostic subject.
+* @returns immutable detached artifact.
+*/
+function snapshotSessionFormatArtifact(artifact, label = "Session artifact") {
+	const snapshot = snapshotSessionFormatJson(artifact, label);
+	const header = snapshot["header"];
+	const inheritedEventCount = snapshot["inheritedEventCount"];
+	const events = snapshot["events"];
+	if (!isSessionFormatJsonObject(header)) throw new SessionFormatError(`${label} header must be a JSON object`);
+	inspectSessionFormatVersion(header);
+	sessionFormatCount(inheritedEventCount, `${label} inheritedEventCount`);
+	if (!Array.isArray(events)) throw new SessionFormatError(`${label} events must be an array`);
+	for (let index = 0; index < events.length; index += 1) {
+		const event = events[index];
+		if (!isSessionFormatJsonObject(event)) throw new SessionFormatError(`${label} event ${index} must be a JSON object`);
+		if (event["seq"] !== index) throw new SessionFormatError(`${label} event ${index} has non-dense seq ${String(event["seq"])}`);
+		if (typeof event["type"] !== "string" || event["type"].length === 0) throw new SessionFormatError(`${label} event ${index} type must be a non-empty string`);
+		sessionFormatSafeInteger(event["time"], `${label} event ${index} time`);
+		if (!Object.hasOwn(event, "data")) throw new SessionFormatError(`${label} event ${index} lacks data`);
+	}
+	if (inheritedEventCount > events.length) throw new SessionFormatError(`${label} inheritedEventCount exceeds its event count`);
+	return snapshot;
+}
+/**
+* Snapshot one logical header without inspecting an event body.
+* @param header - borrowed logical header.
+* @param label - diagnostic subject.
+* @returns immutable detached header.
+*/
+function snapshotSessionFormatHeader(header, label = "Session header") {
+	const snapshot = snapshotSessionFormatJson(header, label);
+	if (!isSessionFormatJsonObject(snapshot)) throw new SessionFormatError(`${label} must be a JSON object`);
+	inspectSessionFormatVersion(snapshot);
+	if (typeof snapshot["id"] !== "string") throw new SessionFormatError(`${label} id must be a string`);
+	sessionFormatCount(snapshot["createdAt"], `${label} createdAt`);
+	if (typeof snapshot["isSeeded"] !== "boolean") throw new SessionFormatError(`${label} isSeeded must be a boolean`);
+	sessionFormatCount(snapshot["delegationDepth"], `${label} delegationDepth`);
+	return snapshot;
+}
+//#endregion
+//#region lib/types/chain.js
+/**
+* Validate and freeze one adjacent migration declaration.
+* @param migration - named exact adjacent conversion.
+* @returns immutable validated declaration.
+*/
+function defineSessionFormatMigration(migration) {
+	if (typeof migration.name !== "string" || migration.name.length === 0) throw new SessionFormatError("Session migration name must be a non-empty string");
+	const from = sessionFormatVersion(migration.fromVersion, `${migration.name} fromVersion`);
+	if (sessionFormatVersion(migration.toVersion, `${migration.name} toVersion`) !== from + 1) throw new SessionFormatError(`${migration.name} must declare adjacent v${from}->v${from + 1}`);
+	return Object.freeze({ ...migration });
+}
+/**
+* Compile a unique, complete adjacent migration chain.
+* @param options - current version, adjacent declarations, and current restorer.
+* @returns immutable planner and whole-artifact runner.
+*/
+function createSessionFormatChain(options) {
+	return new CompiledSessionFormatChain(options);
+}
+var CompiledSessionFormatChain = class {
+	currentVersion;
+	migrations;
+	restoreCurrent;
+	restoreCurrentHeader;
+	constructor(options) {
+		this.currentVersion = sessionFormatVersion(options.currentVersion, "current Session format version");
+		this.restoreCurrent = options.restoreCurrent;
+		this.restoreCurrentHeader = options.restoreCurrentHeader;
+		const byFrom = /* @__PURE__ */ new Map();
+		const names = /* @__PURE__ */ new Set();
+		for (const candidate of options.migrations) {
+			const migration = defineSessionFormatMigration(candidate);
+			if (byFrom.has(migration.fromVersion)) throw new SessionFormatError(`Session migration v${migration.fromVersion}->v${migration.toVersion} is duplicated`);
+			if (names.has(migration.name)) throw new SessionFormatError(`Session migration name ${JSON.stringify(migration.name)} is duplicated`);
+			byFrom.set(migration.fromVersion, migration);
+			names.add(migration.name);
+		}
+		const ordered = [];
+		for (let version = 0; version < this.currentVersion; version += 1) {
+			const migration = byFrom.get(version);
+			if (migration === void 0) throw new SessionFormatUnsupportedMigrationError(`Session migration v${version}->v${version + 1} is missing`);
+			ordered.push(migration);
+		}
+		if (byFrom.size !== ordered.length) throw new SessionFormatError(`Session migration from v${[...byFrom.keys()].find((version) => version >= this.currentVersion)} does not lead to current v${this.currentVersion}`);
+		this.migrations = Object.freeze(ordered);
+	}
+	plan(fromVersion) {
+		const from = sessionFormatVersion(fromVersion, "stored Session format version");
+		if (from > this.currentVersion) throw new SessionFormatUnsupportedMigrationError(`stored Session uses newer format v${from}; this build writes v${this.currentVersion}`);
+		return Object.freeze(this.migrations.slice(from));
+	}
+	migrate(source) {
+		const storedVersion = inspectSessionFormatVersion(source.header);
+		let current = snapshotSessionFormatArtifact(source, `format v${storedVersion} source`);
+		if (storedVersion === this.currentVersion) {
+			current = snapshotSessionFormatArtifact(this.restoreCurrent(current), "current Session restoration");
+			this.assertCurrent(current);
+			return current;
+		}
+		for (const migration of this.plan(storedVersion)) {
+			let migrated;
+			try {
+				migrated = migration.migrate(snapshotSessionFormatArtifact(current, `${migration.name} input`));
+			} catch (error) {
+				throwUnsupportedRefusal(migration, error);
+			}
+			current = snapshotSessionFormatArtifact(migrated, `${migration.name} output`);
+			if (current.header.version !== migration.toVersion) throw new SessionFormatError(`${migration.name} returned v${current.header.version}; expected v${migration.toVersion}`);
+			try {
+				migration.validateTarget(current);
+			} catch (error) {
+				throwUnsupportedRefusal(migration, error);
+			}
+		}
+		current = snapshotSessionFormatArtifact(this.restoreCurrent(current), "current Session restoration");
+		this.assertCurrent(current);
+		return current;
+	}
+	migrateHeader(source) {
+		let current = snapshotSessionFormatHeader(source, "stored Session header");
+		for (const migration of this.plan(current.version)) {
+			let migrated;
+			try {
+				migrated = migration.migrateHeader(snapshotSessionFormatHeader(current, `${migration.name} header input`));
+			} catch (error) {
+				throwUnsupportedRefusal(migration, error, "Session header");
+			}
+			current = snapshotSessionFormatHeader(migrated, `${migration.name} header output`);
+			if (current.version !== migration.toVersion) throw new SessionFormatError(`${migration.name} header returned v${current.version}; expected v${migration.toVersion}`);
+			try {
+				migration.validateTargetHeader(current);
+			} catch (error) {
+				throwUnsupportedRefusal(migration, error, "Session header");
+			}
+		}
+		current = snapshotSessionFormatHeader(this.restoreCurrentHeader(current), "current Session header restoration");
+		if (current.version !== this.currentVersion) throw new SessionFormatError(`current Session header restorer returned v${current.version}; expected v${this.currentVersion}`);
+		return current;
+	}
+	assertCurrent(artifact) {
+		if (artifact.header.version !== this.currentVersion) throw new SessionFormatError(`current Session restorer returned v${artifact.header.version}; expected v${this.currentVersion}`);
+	}
+};
+function throwUnsupportedRefusal(migration, error, subject = "Session") {
+	if (error instanceof SessionFormatUnsupportedMigrationError) throw error;
+	const detail = error instanceof Error ? error.message : String(error);
+	throw new SessionFormatUnsupportedMigrationError(`${migration.name} refuses this format v${migration.fromVersion} ${subject}: ${detail}`, { cause: error });
+}
+//#endregion
+//#region lib/types/catalog.js
+/**
+* Compile a build-static physical codec and adjacent migration catalog.
+* @param options - complete codecs, migrations, current version, and restorer.
+* @returns immutable physical dispatch and migration operations.
+*/
+function createSessionFormatCatalog(options) {
+	const chain = createSessionFormatChain(options);
+	const codecs = /* @__PURE__ */ new Map();
+	for (const codec of options.codecs) {
+		const version = sessionFormatVersion(codec.version, "Session format codec version");
+		if (codecs.has(version)) throw new SessionFormatError(`Session format codec v${version} is duplicated`);
+		codecs.set(version, Object.freeze({ ...codec }));
+	}
+	for (let version = 0; version <= chain.currentVersion; version += 1) if (!codecs.has(version)) throw new SessionFormatError(`Session format codec v${version} is missing`);
+	if (codecs.size !== chain.currentVersion + 1) throw new SessionFormatError(`Session format codec v${[...codecs.keys()].find((version) => version > chain.currentVersion)} is newer than current v${chain.currentVersion}`);
+	function readHeader(headerValue) {
+		let storedVersion;
+		try {
+			storedVersion = inspectSessionFormatVersion(headerValue);
+		} catch (error) {
+			return malformed(chain.currentVersion, error);
+		}
+		if (storedVersion > chain.currentVersion) return Object.freeze({
+			status: "unsupported",
+			storedVersion,
+			targetVersion: chain.currentVersion,
+			reason: `stored Session uses newer format v${storedVersion}; this build writes v${chain.currentVersion}`
+		});
+		const codec = codecs.get(storedVersion);
+		/* v8 ignore next -- construction proves every supported version has exactly one codec. */
+		if (codec === void 0) return Object.freeze({
+			status: "unsupported",
+			storedVersion,
+			targetVersion: chain.currentVersion,
+			reason: `this build has no Session format codec for v${storedVersion}`
+		});
+		try {
+			const decoded = snapshotSessionFormatHeader(codec.decodeHeader(headerValue), `format v${storedVersion} header`);
+			const header = chain.migrateHeader(decoded);
+			return Object.freeze({
+				status: storedVersion === chain.currentVersion ? "current" : "migration-required",
+				storedVersion,
+				targetVersion: chain.currentVersion,
+				header
+			});
+		} catch (error) {
+			if (error instanceof SessionFormatUnsupportedMigrationError) return Object.freeze({
+				status: "unsupported",
+				storedVersion,
+				targetVersion: chain.currentVersion,
+				reason: error.message
+			});
+			return malformed(chain.currentVersion, error, storedVersion);
+		}
+	}
+	function artifactCodec(headerValue) {
+		const storedVersion = inspectSessionFormatVersion(headerValue);
+		if (storedVersion > chain.currentVersion) throw new SessionFormatUnsupportedMigrationError(`stored Session uses newer format v${storedVersion}; this build writes v${chain.currentVersion}`);
+		const codec = codecs.get(storedVersion);
+		/* v8 ignore next -- construction proves every supported version has exactly one codec. */
+		if (codec === void 0) throw new SessionFormatUnsupportedMigrationError(`this build has no Session format codec for v${storedVersion}`);
+		return {
+			storedVersion,
+			codec
+		};
+	}
+	function decodeArtifact(headerValue, rowValues) {
+		const { storedVersion, codec } = artifactCodec(headerValue);
+		return snapshotSessionFormatArtifact(codec.decodeArtifact(headerValue, rowValues), `format v${storedVersion} decoded artifact`);
+	}
+	function decodeRecoverableArtifact(headerValue, rowValues) {
+		const { storedVersion, codec } = artifactCodec(headerValue);
+		return snapshotSessionFormatArtifact(codec.decodeRecoverableArtifact(headerValue, rowValues), `format v${storedVersion} recoverable artifact`);
+	}
+	function encodeCurrent(artifact) {
+		if (inspectSessionFormatVersion(artifact.header) !== chain.currentVersion) throw new SessionFormatError(`encodeCurrent requires Session format v${chain.currentVersion}`);
+		const encoded = options.encodeCurrentArtifact(artifact);
+		const header = snapshotSessionFormatJson(encoded.header, "encoded current Session header");
+		const rows = Object.freeze(encoded.rows.map((row, index) => snapshotSessionFormatJson(row, `encoded current Session row ${index}`)));
+		if (inspectSessionFormatVersion(header) !== chain.currentVersion) throw new SessionFormatError("current Session codec returned a non-current header");
+		return Object.freeze({
+			header,
+			rows
+		});
+	}
+	return Object.freeze({
+		currentVersion: chain.currentVersion,
+		readHeader,
+		decodeArtifact,
+		decodeRecoverableArtifact,
+		migrate: chain.migrate.bind(chain),
+		encodeCurrent
+	});
+}
+function malformed(targetVersion, error, storedVersion) {
+	return Object.freeze({
+		status: "malformed",
+		...storedVersion === void 0 ? {} : { storedVersion },
+		targetVersion,
+		reason: error instanceof Error ? error.message : String(error)
+	});
+}
+//#endregion
+//#region lib/types/filename.js
+/** Canonical raw log basename shared by every generation-addressed Session artifact. */
+const CANONICAL_LOG_FILENAME = /^session(?:\.v([1-9][0-9]*))?\.jsonl$/u;
+/**
+* Name the raw JSONL log of one immutable Session format generation. Version
+* zero keeps the original `session.jsonl`; every later generation carries a
+* lowercase numeric `.vN` component before the `.jsonl` suffix.
+* @param version - non-negative safe integer Session format version.
+* @returns the canonical basename, without any compression suffix.
+*/
+function sessionFormatLogFilename(version) {
+	const generation = sessionFormatVersion(version, "Session log generation version");
+	return generation === 0 ? "session.jsonl" : `session.v${generation}.jsonl`;
+}
+/**
+* Read the generation named by one raw JSONL log basename. Temporary,
+* uppercase, leading-zero, `.v0`, and compression-suffixed names are not
+* canonical.
+* @param filename - one basename from a Session directory or archive.
+* @returns its Session format version, or `undefined` when the name is not canonical.
+*/
+function parseSessionFormatLogFilename(filename) {
+	const match = CANONICAL_LOG_FILENAME.exec(filename);
+	if (match === null) return void 0;
+	if (match[1] === void 0) return 0;
+	const version = Number(match[1]);
+	return Number.isSafeInteger(version) ? version : void 0;
+}
+//#endregion
+export { SessionFormatError, SessionFormatUnsupportedMigrationError, createSessionFormatCatalog, createSessionFormatChain, defineSessionFormatMigration, inspectSessionFormatVersion, isSessionFormatJsonObject, parseSessionFormatLogFilename, sessionFormatCount, sessionFormatLogFilename, sessionFormatSafeInteger, sessionFormatVersion, snapshotSessionFormatArtifact, snapshotSessionFormatHeader, snapshotSessionFormatJson };

package/lib/types/catalog.d.ts

@@ -0,0 +1,8 @@
+import type { SessionFormatCatalog, SessionFormatCatalogOptions } from './types.ts';
+/**
+ * Compile a build-static physical codec and adjacent migration catalog.
+ * @param options - complete codecs, migrations, current version, and restorer.
+ * @returns immutable physical dispatch and migration operations.
+ */
+export declare function createSessionFormatCatalog(options: SessionFormatCatalogOptions): SessionFormatCatalog;
+//# sourceMappingURL=catalog.d.ts.map

package/lib/types/chain.d.ts

@@ -0,0 +1,14 @@
+import type { SessionFormatChain, SessionFormatChainOptions, SessionFormatMigration } from './types.ts';
+/**
+ * Validate and freeze one adjacent migration declaration.
+ * @param migration - named exact adjacent conversion.
+ * @returns immutable validated declaration.
+ */
+export declare function defineSessionFormatMigration(migration: SessionFormatMigration): SessionFormatMigration;
+/**
+ * Compile a unique, complete adjacent migration chain.
+ * @param options - current version, adjacent declarations, and current restorer.
+ * @returns immutable planner and whole-artifact runner.
+ */
+export declare function createSessionFormatChain(options: SessionFormatChainOptions): SessionFormatChain;
+//# sourceMappingURL=chain.d.ts.map

package/lib/types/error.d.ts

@@ -0,0 +1,9 @@
+/** Error raised when a durable Session artifact cannot be restored or migrated losslessly. */
+export declare class SessionFormatError extends Error {
+    readonly name: string;
+}
+/** A readable artifact whose released source policy has no supported migration. */
+export declare class SessionFormatUnsupportedMigrationError extends SessionFormatError {
+    readonly name = "SessionFormatUnsupportedMigrationError";
+}
+//# sourceMappingURL=error.d.ts.map

package/lib/types/filename.d.ts

@@ -0,0 +1,18 @@
+/** Canonical raw log basename shared by every generation-addressed Session artifact. */
+/**
+ * Name the raw JSONL log of one immutable Session format generation. Version
+ * zero keeps the original `session.jsonl`; every later generation carries a
+ * lowercase numeric `.vN` component before the `.jsonl` suffix.
+ * @param version - non-negative safe integer Session format version.
+ * @returns the canonical basename, without any compression suffix.
+ */
+export declare function sessionFormatLogFilename(version: number): string;
+/**
+ * Read the generation named by one raw JSONL log basename. Temporary,
+ * uppercase, leading-zero, `.v0`, and compression-suffixed names are not
+ * canonical.
+ * @param filename - one basename from a Session directory or archive.
+ * @returns its Session format version, or `undefined` when the name is not canonical.
+ */
+export declare function parseSessionFormatLogFilename(filename: string): number | undefined;
+//# sourceMappingURL=filename.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,8 @@
+/** Pure adjacent whole-artifact Session format migration machinery. */
+export * from './chain.ts';
+export * from './catalog.ts';
+export * from './error.ts';
+export * from './filename.ts';
+export * from './json.ts';
+export * from './types.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/json.d.ts

@@ -0,0 +1,56 @@
+import type { SessionFormatArtifact, SessionFormatHeader, SessionFormatJsonValue } from './types.ts';
+/**
+ * Test whether a value is a non-null, non-array object.
+ * @param value - candidate value.
+ * @returns whether the value is an object record.
+ */
+export declare function isSessionFormatJsonObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Require a non-negative safe integer without the JSON-unstable negative zero.
+ * @param value - candidate count.
+ * @param label - diagnostic subject.
+ * @returns validated count.
+ */
+export declare function sessionFormatCount(value: unknown, label: string): number;
+/**
+ * Require a safe integer without the JSON-unstable negative zero.
+ * @param value - candidate integer.
+ * @param label - diagnostic subject.
+ * @returns validated integer.
+ */
+export declare function sessionFormatSafeInteger(value: unknown, label: string): number;
+/**
+ * Require a non-negative integral format version.
+ * @param value - candidate version.
+ * @param label - diagnostic subject.
+ * @returns validated version.
+ */
+export declare function sessionFormatVersion(value: unknown, label?: string): number;
+/**
+ * Read only the version required for directional dispatch.
+ * @param headerValue - untrusted physical header value.
+ * @returns validated stored version.
+ */
+export declare function inspectSessionFormatVersion(headerValue: unknown): number;
+/**
+ * Detach and deeply freeze a caller-supplied lossless JSON value.
+ * @param value - borrowed candidate.
+ * @param label - diagnostic subject.
+ * @returns an immutable detached JSON snapshot.
+ */
+export declare function snapshotSessionFormatJson(value: unknown, label?: string): SessionFormatJsonValue;
+/**
+ * Snapshot one complete artifact and validate its shared coordinates.
+ * @param artifact - borrowed logical artifact.
+ * @param label - diagnostic subject.
+ * @returns immutable detached artifact.
+ */
+export declare function snapshotSessionFormatArtifact(artifact: SessionFormatArtifact, label?: string): SessionFormatArtifact;
+/**
+ * Snapshot one logical header without inspecting an event body.
+ * @param header - borrowed logical header.
+ * @param label - diagnostic subject.
+ * @returns immutable detached header.
+ */
+export declare function snapshotSessionFormatHeader(header: SessionFormatHeader, label?: string): SessionFormatHeader;
+//# sourceMappingURL=json.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,125 @@
+/** Scalar value admitted at the durable Session JSON boundary. */
+export type SessionFormatJsonPrimitive = null | boolean | number | string;
+/** Lossless JSON value admitted at the durable Session boundary. */
+export type SessionFormatJsonValue = SessionFormatJsonPrimitive | readonly SessionFormatJsonValue[] | SessionFormatJsonObject;
+/** Lossless JSON object admitted at the durable Session boundary. */
+export interface SessionFormatJsonObject {
+    readonly [key: string]: SessionFormatJsonValue;
+}
+/** Logical Session metadata shared by supported historical and current formats. */
+export interface SessionFormatHeader extends SessionFormatJsonObject {
+    readonly version: number;
+    readonly id: string;
+    readonly createdAt: number;
+    readonly cwd?: string;
+    readonly parentSession?: string;
+    readonly isSeeded: boolean;
+    readonly origin?: 'subagent';
+    readonly delegationDepth: number;
+    readonly agentPreset?: string;
+}
+/** One decoded logical Session event. */
+export interface SessionFormatEvent extends SessionFormatJsonObject {
+    readonly type: string;
+    readonly seq: number;
+    readonly time: number;
+    readonly data: SessionFormatJsonValue;
+}
+/** One detached complete logical Session artifact. */
+export interface SessionFormatArtifact {
+    readonly header: SessionFormatHeader;
+    /** Exact inherited prefix length, available only after a body read. */
+    readonly inheritedEventCount: number;
+    readonly events: readonly SessionFormatEvent[];
+}
+/** One independently maintained adjacent whole-artifact migration. */
+export interface SessionFormatMigration {
+    readonly name: string;
+    readonly fromVersion: number;
+    readonly toVersion: number;
+    /** Convert one header without reading event bodies. */
+    migrateHeader(header: SessionFormatHeader): SessionFormatHeader;
+    /** Convert one detached complete artifact to exactly {@link toVersion}. */
+    migrate(artifact: SessionFormatArtifact): SessionFormatArtifact;
+    /** Refuse any artifact that the adjacent target writer cannot emit. */
+    validateTarget(artifact: SessionFormatArtifact): void;
+    /** Refuse any header that the adjacent target writer cannot emit. */
+    validateTargetHeader(header: SessionFormatHeader): void;
+}
+/** Inputs that compile the unique complete migration chain. */
+export interface SessionFormatChainOptions {
+    readonly currentVersion: number;
+    readonly migrations: readonly SessionFormatMigration[];
+    /** Restore and validate a detached current artifact through the current parser. */
+    readonly restoreCurrent: (artifact: SessionFormatArtifact) => SessionFormatArtifact;
+    /** Restore and validate a detached current header without reading event bodies. */
+    readonly restoreCurrentHeader: (header: SessionFormatHeader) => SessionFormatHeader;
+}
+/** Pure adjacent planner and whole-artifact migration runner. */
+export interface SessionFormatChain {
+    readonly currentVersion: number;
+    /** Return the complete ordered plan from one supported stored version. */
+    plan(fromVersion: number): readonly SessionFormatMigration[];
+    /** Restore current input directly or migrate old input entirely in memory. */
+    migrate(artifact: SessionFormatArtifact): SessionFormatArtifact;
+    /** Convert only a supported header to the current logical representation. */
+    migrateHeader(header: SessionFormatHeader): SessionFormatHeader;
+}
+/** Physical JSON records emitted by one format-specific codec. */
+export interface EncodedSessionFormatArtifact {
+    readonly header: SessionFormatJsonObject;
+    readonly rows: readonly SessionFormatJsonObject[];
+}
+/** Options that affect only physical row layout, never logical contents. */
+export interface SessionFormatEncodeOptions {
+    readonly packChunks: boolean;
+}
+/** Pure physical JSON codec frozen with one released Session format. */
+export interface SessionFormatCodec {
+    readonly version: number;
+    /** Decode one physical header into body-independent logical metadata. */
+    decodeHeader(value: unknown): SessionFormatHeader;
+    /** Decode one complete physical header and row sequence into logical events. */
+    decodeArtifact(headerValue: unknown, rowValues: readonly unknown[]): SessionFormatArtifact;
+    /** Decode the row-atomic recoverable prefix used by crash-tail repair. */
+    decodeRecoverableArtifact(headerValue: unknown, rowValues: readonly unknown[]): SessionFormatArtifact;
+}
+/** Header-only classification that never inspects event rows. */
+export type SessionFormatHeaderReadResult = {
+    readonly status: 'current' | 'migration-required';
+    readonly storedVersion: number;
+    readonly targetVersion: number;
+    /** Latest logical header. The exact inherited cut requires a body read. */
+    readonly header: SessionFormatHeader;
+} | {
+    readonly status: 'unsupported';
+    readonly storedVersion: number;
+    readonly targetVersion: number;
+    readonly reason: string;
+} | {
+    readonly status: 'malformed';
+    readonly storedVersion?: number;
+    readonly targetVersion: number;
+    readonly reason: string;
+};
+/** Inputs for a build-static physical codec and migration catalog. */
+export interface SessionFormatCatalogOptions extends SessionFormatChainOptions {
+    readonly codecs: readonly SessionFormatCodec[];
+    /** Encode one already-restored current artifact through its format-specific writer. */
+    readonly encodeCurrentArtifact: (artifact: SessionFormatArtifact) => EncodedSessionFormatArtifact;
+}
+/** Build-static physical dispatch and adjacent migration catalog. */
+export interface SessionFormatCatalog {
+    readonly currentVersion: number;
+    /** Classify and translate one header without reading event rows. */
+    readHeader(headerValue: unknown): SessionFormatHeaderReadResult;
+    /** Dispatch a complete physical JSON artifact through its frozen version codec. */
+    decodeArtifact(headerValue: unknown, rowValues: readonly unknown[]): SessionFormatArtifact;
+    /** Dispatch a physical artifact through its released row-prefix recovery rules. */
+    decodeRecoverableArtifact(headerValue: unknown, rowValues: readonly unknown[]): SessionFormatArtifact;
+    /** Restore current input directly or run all required adjacent migrations in memory. */
+    migrate(artifact: SessionFormatArtifact): SessionFormatArtifact;
+    /** Encode one current artifact that `migrate` returned or a live Session produced; it is not re-validated here. */
+    encodeCurrent(artifact: SessionFormatArtifact): EncodedSessionFormatArtifact;
+}
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@xneog/dsh-session-format",
+  "description": "Pure adjacent whole-artifact Session format migration machinery",
+  "version": "0.1.3-alpha.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gomes007-alt/xneog-harness.git",
+    "directory": "packages/session/session-format"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@xneog/dsh-util-values": "^0.1.3-alpha.1"
+  },
+  "peerDependencies": {
+    "@xneog/cordis": "^4.0.2"
+  },
+  "devDependencies": {
+    "@xneog/cordis": "^4.0.2"
+  }
+}