docs(session): name the frozen v0/v1 vocabulary in the v0-to-v1 README

The README file table listed four of the six source modules and omitted
the two largest, so the package read as an oversized identity conversion.
The summary now states that most of the source is the frozen released
v0/v1 event vocabulary, why the edge refuses a malformed historical log
before the installed current restorer runs, and that later edges reuse
those shapes; the table gains `payload-validation.ts` and
`relationships.ts` rows.
This commit is contained in:
Tianyi Cui committed 2026-09-03 22:23:53 +08:00
1 parent c97df989ff
commit 6c419795f6
3 files changed
+8 -4

No files matched your search

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write packages/session/session-format-v0-to-v1/README.md
README.md: 1685831b49814b80979a0e54cb1a6a6d6b618a1d
README.zh.md: 4a511920f4b364d730e9db2bb59e7b43ac47c63a
README.md: 829bca816c7770aecfc8cf98fbec34f3ee3a9741
README.zh.md: 4c5566d28687bb9528d2e6070c7a03bdc52ff611
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
## Summary
`dsh-session-format-v0-to-v1` decodes the complete released-v0 JSONL record language and converts it into the shared-layout v1 format. The edge preserves validated header and event facts except for `version: 0` becoming `version: 1`; it also applies the finite legacy normalizers that v0 persistence accepted. The package freezes the v0 reader, the strict v1 migration target validator, and a vocabulary-neutral v1 physical codec that a later edge can reuse without importing the latest Session representation.
`dsh-session-format-v0-to-v1` decodes the complete released-v0 JSONL record language and converts it into the shared-layout v1 format. The edge preserves validated header and event facts except for `version: 0` becoming `version: 1`; it also applies the finite legacy normalizers that v0 persistence accepted. The package freezes the v0 reader, the strict v1 migration target validator, and a vocabulary-neutral v1 physical codec that a later edge can reuse without importing the latest Session representation. Most of its source is the frozen released v0/v1 event vocabulary rather than the identity conversion: `payload-validation.ts` and `relationships.ts` pin the payload members and lifecycle pairings of every first-party event type, so a malformed historical log is refused as an unsupported migration with its source retained before the installed current restorer runs, and a later edge that restructures released events can trust their shapes without importing the current Session package.
## Table of Contents
@@ -56,6 +56,8 @@ The physical codec expands each packed row atomically and never mutates parsed i
|---|---|
| [`src/codec.ts`](src/codec.ts) | Frozen v0/v1 physical headers, packed rows, and provenance ranges |
| [`src/dispositions.ts`](src/dispositions.ts) | Released-v0 event and payload-member inventory |
| [`src/payload-validation.ts`](src/payload-validation.ts) | Frozen nested payload semantics for every released-v0/v1 event type |
| [`src/relationships.ts`](src/relationships.ts) | Frozen cross-event pairings: turns, steps, tool starts and results, retries, compaction, titles |
| [`src/migration.ts`](src/migration.ts) | Identity edge and legacy normalization |
| [`src/validation.ts`](src/validation.ts) | Exact source and target validation |
@@ -9,7 +9,7 @@ kind: "package-library"
## 概述
`dsh-session-format-v0-to-v1` 解码完整的已发布 v0 JSONL 记录语言,并把它转换为共享布局的 v1 格式。除把 `version: 0` 改为 `version: 1` 外,该迁移边会保留经过校验的标头与事件事实;它也会应用 v0 持久化曾接受的有限旧格式规范化。该包冻结 v0 读取器、严格的 v1 迁移目标校验器,以及不冻结事件词表的 v1 物理编解码器,使后续迁移边无需导入最新 Session 表示即可复用它。
`dsh-session-format-v0-to-v1` 解码完整的已发布 v0 JSONL 记录语言,并把它转换为共享布局的 v1 格式。除把 `version: 0` 改为 `version: 1` 外,该迁移边会保留经过校验的标头与事件事实;它也会应用 v0 持久化曾接受的有限旧格式规范化。该包冻结 v0 读取器、严格的 v1 迁移目标校验器,以及不冻结事件词表的 v1 物理编解码器,使后续迁移边无需导入最新 Session 表示即可复用它。它的大部分源码是冻结的已发布 v0/v1 事件词表而不是恒等转换本身:`payload-validation.ts` 与 `relationships.ts` 钉住每种第一方事件类型的 payload 成员与生命周期配对,使畸形历史日志在已安装的 current 恢复器运行之前就以「不支持的迁移」被拒绝并保留源文件,也使后续重构已发布事件的迁移边无需导入当前 Session 包即可信任其形状。
## 目录
@@ -56,6 +56,8 @@ Alpha 迁移边会拒绝冻结清单之外的所有事件类型,包括带有 `
|---|---|
| [`src/codec.ts`](src/codec.ts) | 冻结的 v0/v1 物理标头、打包行与来源序号范围 |
| [`src/dispositions.ts`](src/dispositions.ts) | 已发布 v0 事件与 payload 成员清单 |
| [`src/payload-validation.ts`](src/payload-validation.ts) | 每种已发布 v0/v1 事件类型的冻结嵌套 payload 语义 |
| [`src/relationships.ts`](src/relationships.ts) | 冻结的跨事件配对:轮次、步骤、工具开始与结果、重试、压缩、标题 |
| [`src/migration.ts`](src/migration.ts) | 恒等迁移边与旧格式规范化 |
| [`src/validation.ts`](src/validation.ts) | 精确的源与目标校验 |