@xneog/dsh-session-format-catalog 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-catalog/README.md
+README.md: 81f6345b4d2123ea1f5981e3921777cb0f14d550
+README.zh.md: 141c3f9dd78038835b13f7badaa65d59a69f45b7

package/README.md

@@ -0,0 +1,99 @@
+---
+description: "Build-static first-party Session format codec and adjacent migration assembly for persistence readers."
+kind: "package-library"
+---
+
+# @xneog/dsh-session-format-catalog
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`dsh-session-format-catalog` gives persistence one deterministic Session format reader without consulting mounted plugins. It assembles the frozen v0, v1, and v2 codecs with the adjacent v0-to-v1 and v1-to-v2 edges, checks the complete gap-free chain at module initialization, and exposes physical dispatch, header-only classification, migration, and current encoding through `sessionFormatCatalog`.
+
+## 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
+
+Import this library from persistence and test-support readers that need the complete first-party released-format inventory before any feature plugin mounts. Feature compositions do not register or reorder its entries. No runtime invariant companion is published because construction rejects an invalid static inventory and each read validates its complete result; the catalog retains no independently mutable runtime relationship.
+
+### Entry point
+
+```text
+const descriptor = sessionFormatCatalog.readHeader(physicalHeader)
+const current = sessionFormatCatalog.migrate(sessionFormatCatalog.decodeArtifact(physicalHeader, rows))
+```
+
+Import `sessionFormatCatalog` from the package root. JSONL readers pass parsed header and row JSON values to `decodeArtifact()` or `decodeRecoverableArtifact()`, migrate the logical result with `migrate()`, and serialize only the validated current artifact with `encodeCurrent()`. Listing calls `readHeader()` and never opens event bodies. Header reads validate every adjacent target and then restore the final header through the installed current Session package.
+
+The catalog contains all supported historical readers directly. A profile cannot add, remove, or reorder an edge by mounting a feature plugin. Its peer dependency on `dsh-session` supplies the installed current event vocabulary and current restoration rules, while historical edge validators remain frozen.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+[`src/generated.ts`](src/generated.ts) is the static owner of codec and edge ordering. [`src/current.ts`](src/current.ts) delegates final header, envelope, message, surface, seed, and current request-header validation to the installed Session semantics. The low-level constructor rejects duplicate codecs, duplicate edges, gaps, and entries beyond the current version before any Session read can begin.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Migration machinery](../session-format/README.md) — catalog construction and dispatch behavior.
+- [Released v0 to v1 edge](../session-format-v0-to-v1/README.md) — codec and validator ownership.
+- [Released v1 to v2 edge](../session-format-v1-to-v2/README.md) — Assistant stream embedding and cardinality-changing reference remapping.
+- [JSONL persistence](../session-persistence-jsonl/README.md) — immutable generation naming and exclusive publication.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Catalog dispatch
+
+#### What the model sees
+
+Nothing directly. The catalog only restores the `SessionEvent` history consumed by request reconstruction.
+
+#### Token effect
+
+Zero direct tokens.
+
+#### KV Cache effect
+
+No direct effect; restored history determines cache identity in its consumer.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **First-party build inventory only** — external migration ownership and distribution are not supported.
+- **Generated ordering is closed** — runtime plugin registration cannot supply a missing historical edge.
+
+<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,99 @@
+---
+description: "供持久化读取方使用的构建期静态第一方 Session 格式编解码器与相邻迁移装配。"
+kind: "package-library"
+---
+
+# @xneog/dsh-session-format-catalog
+
+[English](README.md) | 中文
+
+## 概述
+
+`dsh-session-format-catalog` 为持久化提供一个确定性的 Session 格式读取器，且无需查询已挂载插件。它把冻结的 v0、v1 与 v2 编解码器和相邻的 v0 到 v1、v1 到 v2 迁移边装配起来，在模块初始化时校验完整且无缺口的迁移链，并通过 `sessionFormatCatalog` 暴露物理分派、仅标头分类、迁移和当前格式编码。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+### 何时使用
+
+当持久化与测试支持读取方需要在任何功能插件挂载前取得完整第一方已发布格式清单时，导入本库。功能组合不会注册或重排其条目。它不发布运行时不变式伴生入口，因为构造过程会拒绝无效静态清单，每次读取也会校验完整结果；目录不保留可独立分叉的运行时可变关系。
+
+### 入口
+
+```text
+const descriptor = sessionFormatCatalog.readHeader(physicalHeader)
+const current = sessionFormatCatalog.migrate(sessionFormatCatalog.decodeArtifact(physicalHeader, rows))
+```
+
+从包根导入 `sessionFormatCatalog`。JSONL 读取方把解析后的标头与行 JSON 值传给 `decodeArtifact()` 或 `decodeRecoverableArtifact()`，使用 `migrate()` 迁移逻辑结果，并且只使用 `encodeCurrent()` 序列化经过校验的当前产物。列表读取调用 `readHeader()`，绝不打开事件正文。标头读取会校验每个相邻目标，然后通过已安装的当前 Session 包还原最终标头。
+
+该目录直接包含所有受支持的历史读取器。Profile 无法通过挂载功能插件来添加、移除或重新排列迁移边。它通过对 `dsh-session` 的 peer 依赖获得已安装的当前事件词表与当前还原规则，而历史迁移边校验器保持冻结。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+[`src/generated.ts`](src/generated.ts) 是编解码器与迁移边顺序的静态所有者。[`src/current.ts`](src/current.ts) 把最终标头、事件信封、消息、表面、种子和当前请求标头校验委托给已安装的 Session 语义。底层构造函数会在开始读取任何 Session 之前拒绝重复编解码器、重复迁移边、缺口，以及超过当前版本的条目。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+- [迁移机制](../session-format/README.zh.md)——目录构造与分派行为。
+- [已发布 v0 到 v1 迁移边](../session-format-v0-to-v1/README.zh.md)——编解码器与校验器所有权。
+- [已发布 v1 到 v2 迁移边](../session-format-v1-to-v2/README.zh.md)——Assistant stream 嵌入与基数变化引用重映射。
+- [JSONL 持久化](../session-persistence-jsonl/README.zh.md)——不可变 generation 命名与排他发布。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 目录分派
+
+#### 模型看到什么
+
+没有直接内容。该目录只还原由请求重建逻辑消费的 `SessionEvent` 历史。
+
+#### Token 影响
+
+不直接产生 token。
+
+#### KV Cache 影响
+
+没有直接影响；还原后的历史在其消费者中决定缓存身份。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **仅包含第一方构建清单**——尚不支持外部迁移所有权与分发。
+- **生成顺序封闭**——运行时插件注册无法补充缺失的历史迁移边。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,53 @@
+import { KNOWN_SESSION_EVENT_TYPES, SESSION_FORMAT_VERSION, Session, SessionId, SessionLogOffset } from "@xneog/dsh-session";
+import { SessionFormatUnsupportedMigrationError, createSessionFormatCatalog } from "@xneog/dsh-session-format";
+import { releasedV0SessionFormatCodec, releasedV1SessionFormatCodec, sessionFormatV0ToV1 } from "@xneog/dsh-session-format-v0-to-v1";
+import { assertReleasedV2Header, releasedV2SessionFormatCodec, restoreReleasedV2Artifact, sessionFormatV1ToV2 } from "@xneog/dsh-session-format-v1-to-v2";
+//#region lib/types/current.js
+/** Current installed Session validation used after vocabulary-aware format restoration. */
+/**
+* Validate current logical metadata through the installed Session package.
+* @param header - detached current logical header.
+* @returns nothing after successful validation.
+*/
+function validateInstalledCurrentSessionHeader(header) {
+	if (header.version !== SESSION_FORMAT_VERSION) throw new Error(`installed Session format is v${SESSION_FORMAT_VERSION}, got v${header.version}`);
+	Session.fromRestore(SessionId(header.id), [], header, SessionLogOffset(0));
+}
+/**
+* Validate current header, event envelopes, messages, surface operations, and seed cut through the installed Session package.
+* @param artifact - vocabulary-restored current logical artifact.
+* @returns nothing after successful validation.
+*/
+function validateInstalledCurrentSessionArtifact(artifact) {
+	if (artifact.header.version !== SESSION_FORMAT_VERSION) throw new Error(`installed Session format is v${SESSION_FORMAT_VERSION}, got v${artifact.header.version}`);
+	Session.fromRestore(SessionId(artifact.header.id), artifact.events, artifact.header, SessionLogOffset(artifact.inheritedEventCount));
+}
+//#endregion
+//#region lib/types/generated.js
+/**
+* GENERATED by `scripts/gen-session-format-catalog.ts` — do not edit by hand.
+* The direct imports make historical readability independent of mounted plugins.
+*/
+/** Physical codec dispatch and complete adjacent chain, independent of mounted plugins. */
+const sessionFormatCatalog = createSessionFormatCatalog({
+	currentVersion: 2,
+	codecs: [
+		releasedV0SessionFormatCodec,
+		releasedV1SessionFormatCodec,
+		releasedV2SessionFormatCodec
+	],
+	encodeCurrentArtifact: (artifact) => releasedV2SessionFormatCodec.encodeArtifact(artifact),
+	migrations: [sessionFormatV0ToV1, sessionFormatV1ToV2],
+	restoreCurrent(artifact) {
+		const restored = restoreReleasedV2Artifact(artifact, KNOWN_SESSION_EVENT_TYPES);
+		validateInstalledCurrentSessionArtifact(restored);
+		return restored;
+	},
+	restoreCurrentHeader(header) {
+		assertReleasedV2Header(header);
+		validateInstalledCurrentSessionHeader(header);
+		return header;
+	}
+});
+//#endregion
+export { SessionFormatUnsupportedMigrationError, sessionFormatCatalog };

package/lib/types/current.d.ts

@@ -0,0 +1,15 @@
+/** Current installed Session validation used after vocabulary-aware format restoration. */
+import type { SessionFormatArtifact, SessionFormatHeader } from '@xneog/dsh-session-format';
+/**
+ * Validate current logical metadata through the installed Session package.
+ * @param header - detached current logical header.
+ * @returns nothing after successful validation.
+ */
+export declare function validateInstalledCurrentSessionHeader(header: SessionFormatHeader): void;
+/**
+ * Validate current header, event envelopes, messages, surface operations, and seed cut through the installed Session package.
+ * @param artifact - vocabulary-restored current logical artifact.
+ * @returns nothing after successful validation.
+ */
+export declare function validateInstalledCurrentSessionArtifact(artifact: SessionFormatArtifact): void;
+//# sourceMappingURL=current.d.ts.map

package/lib/types/generated.d.ts

@@ -0,0 +1,7 @@
+/**
+ * GENERATED by `scripts/gen-session-format-catalog.ts` — do not edit by hand.
+ * The direct imports make historical readability independent of mounted plugins.
+ */
+/** Physical codec dispatch and complete adjacent chain, independent of mounted plugins. */
+export declare const sessionFormatCatalog: import("@xneog/dsh-session-format").SessionFormatCatalog;
+//# sourceMappingURL=generated.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,4 @@
+/** Build-static first-party Session format migration catalog. */
+export { sessionFormatCatalog } from './generated.ts';
+export { SessionFormatUnsupportedMigrationError } from '@xneog/dsh-session-format';
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@xneog/dsh-session-format-catalog",
+  "description": "Build-static first-party Session format codec and migration catalog",
+  "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-catalog"
+  },
+  "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-session-format": "^0.1.3-alpha.1",
+    "@xneog/dsh-session-format-v0-to-v1": "^0.1.3-alpha.1",
+    "@xneog/dsh-session-format-v1-to-v2": "^0.1.3-alpha.1"
+  },
+  "peerDependencies": {
+    "@xneog/cordis": "^4.0.2",
+    "@xneog/dsh-session": "^0.1.3-alpha.1"
+  },
+  "devDependencies": {
+    "@xneog/cordis": "^4.0.2",
+    "@xneog/dsh-session": "^0.1.3-alpha.1"
+  }
+}