dsh-plugin-guide 0.3.21 → 0.3.23

package/references/official-docs/docs/persistence-changes/2026-09-21-user-question-reply.zh.md

@@ -0,0 +1,60 @@
+---
+description: "记录持久化类型更改及其兼容性确认。"
+kind: persistence-change
+---
+
+# 2026-09-21-user-question-reply
+
+[English](2026-09-21-user-question-reply.md) | 中文
+
+## 概述
+
+新增受限定的 user-question-reply 消息来源，将已继续的 ask_user_question 调用的迟到回答送入 agent inbox。
+
+## 目录
+
+- [声明](#declaration)
+- [兼容性](#compatibility)
+- [验证](#verification)
+- [开发备注](#dev-note)
+
+<a id="declaration"></a>
+## 声明
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-09-21-user-question-reply
+baseline: false
+changes:
+  - root: "event:agent/inbox/spliced"
+    previous: "2026-09-16-session-format-v4"
+    after: "6178f1edcb23f361f2a6cb2c859b1c2187220d5695ece4a3400e0d92845a7178"
+    decision: same-version
+  - root: "event:developer/message"
+    previous: "2026-09-16-session-format-v4"
+    after: "186159f5f6f67a0b8cd095b8fe55bef42d4f25ca1a1c248f859867af2ece0467"
+    decision: same-version
+  - root: "event:session/title-llm-request"
+    previous: "2026-09-16-session-format-v4"
+    after: "ae84c5e493f94acc63cfb70389073ba616ed7ae7aa4fadde048bdcc64d49bb46"
+    decision: same-version
+  - root: "event:user/message"
+    previous: "2026-09-16-session-format-v4"
+    after: "b83ed1b1cfffbd7bd5cca06ea72e44be57beb68b39e5a96660ce42a9e21aa411"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## 兼容性
+
+已有日志不含该来源，仍然有效。新来源是普通用户消息上的受限定归属；没有 dsh-user-questions 的读取方保留消息，并从内容推导历史。只有 userQuestions projection 读取该来源，关闭指定的问题并记录答案。answer RPC 是唯一生产方，只写入 outcome answered；关闭 Client 面板不会持久化回复。不新增事件类型，也不改变 Session header。
+
+<a id="verification"></a>
+## 验证
+
+pnpm exec vitest run packages/interaction/user-questions/tests packages/interaction/tool-ask-user/tests：81 个测试通过。projection、reply、view 和 process-group 的定向测试共 70 个通过。pnpm run typecheck 通过。pnpm run doc-sync 的 42 项检查全部通过，包括持久化历史和翻译配对。
+
+<a id="dev-note"></a>
+## 开发备注
+
+无。

package/references/official-docs/docs/persistence-changes/README.i18n.yaml

@@ -1,6 +1,28 @@
-# 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:
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/persistence-changes/README.md
-README.md: 7eb46efe69e139c294ad76e1b584e2d7384151b5
-README.zh.md: d91cfff9e5010bfff92b905ce0f075e7e419eb52
+/:
+  en: 10d173d8956e12a0
+  zh: 3c32dcdb66727fed
+/persistence-type-change-records:
+  en: 9054f01380aa9207
+  zh: 10e27fb51600cd08
+/persistence-type-change-records/summary:
+  en: 272d85bc8ddda7b6
+  zh: 01614508fc8f332e
+/persistence-type-change-records/table-of-contents:
+  en: 1ba6efaa0b5d6e47
+  zh: 6e216391ad24c541
+/persistence-type-change-records/files-and-ownership:
+  en: 6cd0f79a9455bdf2
+  zh: a5978b7834c0802b
+/persistence-type-change-records/compatibility-rules:
+  en: 7d5ce8c14e387922
+  zh: 9106c78283ad932c
+/persistence-type-change-records/history-and-limitations:
+  en: 10a426d36c41548b
+  zh: ef03b693d9d9be26
+/persistence-type-change-records/dev-note:
+  en: 5de1d6304e00c58f
+  zh: 8d8225361cfa29e5

package/references/official-docs/docs/persistence-changes/README.md

@@ -37,6 +37,10 @@ Each dated record has four sibling files:
 | `YYYY-MM-DD-slug.i18n.yaml` | Generated bilingual consistency record |
 | `YYYY-MM-DD-slug.schema.json` | Generated complete after schemas for the affected roots that remain present |
 
+`finalized/vN.json` records the complete root classifications/digests of an accepted compatibility baseline and semantic hashes of its accepted records. The [finalization record](../session-format-status.md#finalization-record) requires its checkpoint. Current V4 schemas may evolve compatibly; the checkpoint protects accepted machine declarations and after schemas even after the writer advances, while excluding prose, aliases, and source locations from record hashes.
+
+A maintainer captures an agreed format with [`createPersistenceFinalizationCheckpoint`](../../scripts/persistence-finalization.ts), writes a new version-named checkpoint without replacing an earlier one, and advances the paired `latestFinalizedVersion`. The helper requires current schemas to match complete acknowledged history. Run the ordinary verifier before committing.
+
 The [record template](../../.agents/skills/dsh-doc/templates/persistence-change.md) defines the authored format. Record creation accepts a bilingual prose input and generates the machine declaration, snapshots, catalog pair, and consistency records. The verifier reads the machine declaration once from the English file and checks the Chinese declaration for equality. A declaration names each affected root, its predecessor record, its after digest, and its compatibility decision. A new root has no predecessor; a deletion has no after schema and retains an explicit tombstone.
 
 <a id="compatibility-rules"></a>
@@ -49,19 +53,29 @@ Every detected structural change requires an acknowledgement. Record creation an
 | Add an optional event-body property, including its complete subtree | `same-version` |
 | Make a required event-body property optional | `same-version` |
 | Add an ordinary event type | `same-version` |
+| Add a higher numeric `data.version` to an ordinary event while retaining every old payload alternative unchanged | `same-version` |
+| Add an explicitly qualified attribution kind to a user/developer source slot whose before and after schemas carry the same supported policy | `same-version` |
 | Make an optional property required, add a required property, change an existing type, or remove/rename a property or event | `version-bump` |
 | Change the Session header or event envelope | `version-bump` |
 
-A same-version explanation states why old records can omit the addition and why older readers can ignore it without changing replay. For required-to-optional changes, it explains how readers handle an absent value. The checker validates the type classification; reviewers assess the explanation. A version-bump record includes the increasing header version in the same transition and follows the [Session-format procedure](../cookbook/adding-a-session-format-version.md).
+A finalized checkpoint protects the accepted baseline without replacing these compatibility rules. At V4, optional additions, ordinary events, and qualified attribution additions can receive new same-version records. Breaking differences require a higher writer version and an acknowledgement containing its own header increase. The accepted V4 record cannot be updated to reuse its original 3→4 transition.
+
+An ordinary event may add payload alternatives with a required, nonnegative integer `data.version` greater than every existing payload version, provided all existing alternatives remain structurally unchanged. The reader must retain support for the old payloads; adding variants at an existing version, dropping old versions, and changing the Session header or envelope remain breaking. Older readers may reject the new payload version. The [catalog acknowledgement](2026-09-20-unknown-child-catalog.md) records one such transition.
+
+The extractor accepts an explicit `@persistenceSource` binding for a core-owned source property on a literal user or developer role; it does not infer a binding from an unannotated type. A producer qualifies its `MessageSourceMap` entry with `@persistenceAttribution`. Qualification promises that an unknown kind and its JSON metadata survive reading without the producer, and that the kind imposes no validation, replay, or authority requirement. A producer may inspect its own kind to resume duplicate suppression; other readers must preserve and derive the recorded messages without that projection. The recorded schema retains the binding, policy version, literal `kind` discriminator, preservation promise, and qualified kind set. Inventory format 2 stores those promises; extraction without a bound policy retains format 1. Session format versions are independent. Both compared snapshots must carry compatible policy state. Existing kind groups still receive ordinary structural comparison; removals, unmarked additions, policy changes, and unrelated breaking changes remain strict. Multiple context-form alternatives with the same wire kind form one group.
+
+A same-version explanation states how old records remain readable and how older readers handle new records. Optional additions explain why older readers can ignore them without changing replay; a new payload version records the older-reader rejection. For required-to-optional changes, it explains how readers handle an absent value. The checker validates the type classification; reviewers assess the explanation. A version-bump record includes the increasing header version in the same transition and follows the [Session-format procedure](../cookbook/adding-a-session-format-version.md).
+
+When a reader rejects a JSON property by name, declare the property as optional `never` and mark it with argument-free `@persistenceReserved`. The extractor retains the forbidden field, so allowing a JSON value later requires an existing-field type change. Required or JSON-valued properties cannot carry this marker. Unmarked optional `never` and `undefined` properties retain their existing omission behavior.
 
 <a id="history-and-limitations"></a>
 ## History and limitations
 
 One baseline records the complete initial inventory. Later records use their predecessor's after schema as the before schema. The verifier rejects missing predecessors, cycles, duplicate successors for one root, digest mismatches, and current roots that disagree with their latest records. Independent roots can advance independently. Two changes to the same predecessor require a single ordered history after integration.
 
-Accepted records describe historical transitions; preserve their machine declarations and schema snapshots when adding a successor. An unaccepted terminal record can be refreshed explicitly; the command rejects baselines and records with dependants. The tree cannot establish review acceptance. Verification proves consistency within the tree, not that history was never rewritten. No Git ref, remote service, or released checkout supplies the baseline.
+Accepted records describe historical transitions; preserve their machine declarations and schema snapshots when adding a successor. An unaccepted terminal record can be refreshed explicitly; the command rejects baselines, records with dependants, and checkpoint-locked records before producing artifacts. Verification checks retained checkpoint hashes; it does not prove that the checkpoints and their authority record were never edited together. No Git ref, remote service, or released checkout supplies the baseline.
 
-Digests describe declared persistence types, not runtime validation or behavior. Comments, source locations, alias names, and harmless declaration reordering do not affect them. Object fields, union alternatives, intersection operands, and index signatures can be reordered when their resolved types stay the same; tuple positions and numeric enum values remain significant. Catalog text and source locations may still change, so regenerate stale artifacts without adding an acknowledgement for an unchanged digest. Opaque types such as `unknown` expose no hidden structure to compare. Behavior-only changes and structures hidden inside opaque values are outside this mechanism's scope. The [decision](../../.agents/notes/implemented/process/2026-09-11-persistence-type-history.md) records these trade-offs.
+Digests describe declared persistence types, not runtime validation or behavior. Ordinary comments, source locations, alias names, and harmless declaration reordering do not affect them. Compatibility annotations are recorded policy data and do affect digests. Unannotated version-1 snapshots retain their original normalization, fingerprints, and strict classification; policy-bearing graphs use a separate fingerprint domain. Object fields, union alternatives, intersection operands, and index signatures can be reordered when their resolved types stay the same; tuple positions and numeric enum values remain significant. Catalog text and source locations may still change, so regenerate stale artifacts without adding an acknowledgement for an unchanged digest. Opaque types such as `unknown` expose no hidden structure to compare. Behavior-only changes and structures hidden inside opaque values are outside this mechanism's scope. The [decision](../../.agents/notes/implemented/process/2026-09-11-persistence-type-history.md) records these trade-offs.
 
 <a id="dev-note"></a>
 ## Dev Note

package/references/official-docs/docs/persistence-changes/README.zh.md

@@ -37,6 +37,10 @@ description: "审阅和维护已记录的会话持久化类型变更、对应 sc
 | `YYYY-MM-DD-slug.i18n.yaml` | 生成的双语一致性记录 |
 | `YYYY-MM-DD-slug.schema.json` | 生成的完整变更后 schema，覆盖受影响且仍然存在的根 |
 
+`finalized/vN.json` 记录已接受兼容性基线的完整根分类／摘要，以及对应已接受记录的语义哈希。[定稿记录](../session-format-status.zh.md#finalization-record)要求检查点存在。当前 V4 schema 可以兼容演进；即使写入器已推进，检查点仍保护已接受的机器声明和变更后 schema，而记录哈希不包含说明文字、别名和源码位置。
+
+维护者通过 [`createPersistenceFinalizationCheckpoint`](../../scripts/persistence-finalization.ts) 捕获已确认格式，写入按版本命名的新检查点而不替换旧文件，并推进双语 `latestFinalizedVersion`。该函数要求当前 schema 与完整确认历史一致。提交前运行常规验证器。
+
 [记录模板](../../.agents/skills/dsh-doc/templates/persistence-change.md)定义人工编写的格式。创建记录时可以提供双语说明输入，由命令生成机器声明、快照、目录对和一致性记录。验证器从英文文件读取一次机器声明，并检查中文声明是否相同。声明列出每个受影响的根、其前驱记录、变更后摘要和兼容性决策。新根没有前驱；删除操作没有变更后 schema，并保留显式删除标记。
 
 <a id="compatibility-rules"></a>
@@ -49,19 +53,29 @@ description: "审阅和维护已记录的会话持久化类型变更、对应 sc
 | 添加可选事件体属性，包括其完整子树 | `same-version` |
 | 将必选事件体属性改为可选 | `same-version` |
 | 添加普通事件类型 | `same-version` |
+| 为普通事件增加更高的数字 `data.version`，并原样保留所有旧载荷分支 | `same-version` |
+| 在前后 schema 均带有相同受支持策略的 user/developer 消息源字段中，添加显式声明为归属信息的 kind | `same-version` |
 | 将可选属性改为必选、添加必选属性、更改已有类型，或删除／重命名属性或事件 | `version-bump` |
 | 更改会话头或事件封装 | `version-bump` |
 
-同版本说明须解释旧记录为何可以缺少新增内容，以及旧读取器为何可以忽略它而不改变回放。对于必选改可选的变更，说明须解释读取器如何处理缺失值。检查器验证类型分类；审阅者判断说明是否成立。升版本记录在同一转换中包含递增的头部版本，并遵循[会话格式流程](../cookbook/adding-a-session-format-version.zh.md)。
+定稿检查点保护已接受基线，不替换这些兼容性规则。在 V4 中，可选新增、普通事件及符合条件的归属 kind 新增可以使用新的同版本记录。破坏性差异要求更高的写入器版本，以及包含自身头版本递增的确认记录。不能更新已接受 V4 记录以复用其原有 3→4 转换。
+
+普通事件可增加具有必选、非负整数 `data.version` 的载荷分支，新版本必须高于所有已有载荷版本，且所有已有分支结构保持不变。读取器必须保留旧载荷支持；在已有版本中增加分支、移除旧版本，以及修改 Session header 或事件封装仍属于破坏性变更。旧读取器可能拒绝新载荷版本。[Catalog 确认记录](2026-09-20-unknown-child-catalog.zh.md) 记录了此类演进。
+
+提取器接受核心拥有的 source 属性上针对 user 或 developer 字面量角色的显式 `@persistenceSource` 绑定，不会从未标记类型中推断绑定。生产者用 `@persistenceAttribution` 标记其 `MessageSourceMap` 成员。该标记承诺：读取器无需生产者即可保留未知 kind 及其 JSON 元数据，且该 kind 不引入校验、回放或权限要求。生产者可以检查自身 kind 来恢复去重状态；其他读取器必须无需该投影也能保留并派生已记录的消息。记录的 schema 保存绑定、策略版本、字面量 `kind` 判别字段、保留承诺及符合条件的 kind 集合。Inventory format 2 保存这些承诺；没有绑定策略的提取仍使用 format 1。Session 格式版本独立于此。比较双方的快照必须带有兼容的策略状态。已有 kind 分组仍进行常规结构比较；删除、未标记的添加、策略更改及无关破坏性变更继续采用严格规则。同一 wire kind 的多个上下文形式分支归为一组。
+
+同版本说明须解释旧记录如何保持可读，以及旧读取器如何处理新记录。可选新增须说明旧读取器为何可以忽略它而不改变回放；新增载荷版本须记录旧读取器的拒绝行为。对于必选改可选的变更，说明须解释读取器如何处理缺失值。检查器验证类型分类；审阅者判断说明是否成立。升版本记录在同一转换中包含递增的头部版本，并遵循[会话格式流程](../cookbook/adding-a-session-format-version.zh.md)。
+
+当读取器按属性名拒绝 JSON 字段时，将该属性声明为可选 `never`，并添加无参数的 `@persistenceReserved` 标记。提取器保留这一禁止字段，因此后续允许 JSON 值属于已有字段类型变更。必选属性或允许 JSON 值的属性不能携带该标记。未标记的可选 `never` 和 `undefined` 属性保留现有省略行为。
 
 <a id="history-and-limitations"></a>
 ## 历史与限制
 
 一条基线记录完整的初始清单。后续记录使用前驱的变更后 schema 作为变更前 schema。验证器拒绝缺失前驱、环、同一根的重复后继、摘要不匹配，以及当前根与最新记录不一致的情况。独立的根可以独立演进。同一前驱上的两个变更在集成后需要形成一条有序历史。
 
-已接受记录描述历史转换；添加后继时须保留其机器声明和 schema 快照。尚未接受的末端记录可以显式刷新；命令拒绝基线及被依赖的记录。目录本身无法证明审阅接受状态。验证证明目录内的一致性，不证明历史从未被改写。基线不依赖 Git 引用、远端服务或已发布版本的检出目录。
+已接受记录描述历史转换；添加后继时须保留其机器声明和 schema 快照。尚未接受的末端记录可以显式刷新；命令在生成产物前拒绝基线、被依赖的记录和被检查点锁定的记录。验证检查所保留检查点的哈希，但不证明检查点及其真源记录从未被一起修改。基线不依赖 Git 引用、远端服务或已发布版本的检出目录。
 
-摘要描述声明的持久化类型，不描述运行时验证或行为。注释、源码位置、别名名称和无语义变化的声明重排不影响摘要。对象字段、联合类型分支、交叉类型操作数和索引签名可以在解析类型不变时重排；元组位置和数字枚举值仍然影响摘要。目录文本和源码位置仍可能变化，因此应重新生成陈旧产物，无需为未变的摘要添加确认记录。`unknown` 等不透明类型不提供可比较的内部结构。纯行为变更以及不透明值中隐藏的结构不在本机制范围内。[决策记录](../../.agents/notes/implemented/process/2026-09-11-persistence-type-history.zh.md)说明这些取舍。
+摘要描述声明的持久化类型，不描述运行时验证或行为。普通注释、源码位置、别名名称和无语义变化的声明重排不影响摘要。兼容性标记是记录的策略数据，会影响摘要。不带标记的版本 1 快照保留原有规范化、指纹和严格分类；包含策略的图使用独立的指纹域。对象字段、联合类型分支、交叉类型操作数和索引签名可以在解析类型不变时重排；元组位置和数字枚举值仍然影响摘要。目录文本和源码位置仍可能变化，因此应重新生成陈旧产物，无需为未变的摘要添加确认记录。`unknown` 等不透明类型不提供可比较的内部结构。纯行为变更以及不透明值中隐藏的结构不在本机制范围内。[决策记录](../../.agents/notes/implemented/process/2026-09-11-persistence-type-history.zh.md)说明这些取舍。
 
 <a id="dev-note"></a>
 ## 开发备注

package/references/official-docs/docs/persistence-changes/finalized/v4.json

@@ -0,0 +1,379 @@
+{
+  "schemaVersion": 1,
+  "sessionFormatVersion": 4,
+  "roots": {
+    "JsonlHeaderLine": {
+      "kind": "header",
+      "digest": "18ee62b8900a4c3d046700f05d7a4d49d6cab2a660a020c87481d1603dd8bd4f"
+    },
+    "SessionEventEnvelope": {
+      "kind": "envelope",
+      "digest": "5776e5553ff2dfe3f5bc202dbb1e7c9f93e35a531aebb7764c23b2b6153b2ccc"
+    },
+    "SessionHeader": {
+      "kind": "header",
+      "digest": "1a3440e3577382704d42a6263aa463504eb74c566734a55e9503a63efcd02445"
+    },
+    "event:agent-preset/selected": {
+      "kind": "event",
+      "digest": "a10c17474eaf2ddab7095a099e0fe3d046fc18e56c3e344fc8894c05ff9ef97b",
+      "event": "agent-preset/selected",
+      "surface": false
+    },
+    "event:agent/inbox/spliced": {
+      "kind": "event",
+      "digest": "1506a9b8224986c83015ae99d2cb5ede705538c58c063d6a48ef6d761a31ba6c",
+      "event": "agent/inbox/spliced",
+      "surface": false
+    },
+    "event:approval/asked": {
+      "kind": "event",
+      "digest": "3bfeb47b58606f4661904bc723da612782214c463d01e6d61cd6d6193d7374e1",
+      "event": "approval/asked",
+      "surface": false
+    },
+    "event:approval/decided": {
+      "kind": "event",
+      "digest": "bb1ab3d08f49a9f3b265f844cd78d5c49813062a7b34b54904b426f85d0ff6e3",
+      "event": "approval/decided",
+      "surface": false
+    },
+    "event:approval/policy": {
+      "kind": "event",
+      "digest": "26718e15e7e395bce9642dba5bbe09b3b1a4ce2213d20d566cd9207d7fc5fb78",
+      "event": "approval/policy",
+      "surface": false
+    },
+    "event:assistant/attempt": {
+      "kind": "event",
+      "digest": "15d5dfdd822aa35e115afd74a8982825a493880457774e6850bc1520b50875e4",
+      "event": "assistant/attempt",
+      "surface": false
+    },
+    "event:assistant/message": {
+      "kind": "event",
+      "digest": "1033093edd0db80ff410e00830b523405e00bb0c7684948e531ff65095799625",
+      "event": "assistant/message",
+      "surface": true
+    },
+    "event:command/done": {
+      "kind": "event",
+      "digest": "15196447222782e773eb943c92b18316ce96b9af0f0cfddb6e57ba8274ecc5ff",
+      "event": "command/done",
+      "surface": false
+    },
+    "event:command/run": {
+      "kind": "event",
+      "digest": "37184378c6439257d105c4e2022d80fc9c3a3f7c7f6ac661b00bc9f18d871006",
+      "event": "command/run",
+      "surface": false
+    },
+    "event:compaction/end": {
+      "kind": "event",
+      "digest": "b0127044ab31a702bddfd785d345f5abd7a70876746e895ce443afa3e60ddf2d",
+      "event": "compaction/end",
+      "surface": false
+    },
+    "event:compaction/prune": {
+      "kind": "event",
+      "digest": "7f7fd5a6b0064f597534b29ff62ef26e786dffccf5e14f654a7d4fcea2c35f04",
+      "event": "compaction/prune",
+      "surface": false
+    },
+    "event:compaction/start": {
+      "kind": "event",
+      "digest": "db874d463b0fdec77e9da1c4568f37cb70bd6596781eb93800db44fb8a116965",
+      "event": "compaction/start",
+      "surface": false
+    },
+    "event:compaction/summary": {
+      "kind": "event",
+      "digest": "e2f9a41e0989f54ed8cee80f8db2bcf9d60a5c810dc9d45b83fa050b9dce7602",
+      "event": "compaction/summary",
+      "surface": false
+    },
+    "event:deliverables/presented": {
+      "kind": "event",
+      "digest": "13d3d180f977bf78081d487ffa0ecb75857349bcab29a5a3fb48189fca2a6176",
+      "event": "deliverables/presented",
+      "surface": false
+    },
+    "event:developer/message": {
+      "kind": "event",
+      "digest": "eef4ef54dc7a133d47448a4ee822e45a351314923ef5f66db34c8b24e4b32d80",
+      "event": "developer/message",
+      "surface": true
+    },
+    "event:feedback/message-delete": {
+      "kind": "event",
+      "digest": "3ee93b06f3a125850337602bcdf155d2538c43a5c944ec55b1b3c365152d6796",
+      "event": "feedback/message-delete",
+      "surface": false
+    },
+    "event:feedback/message-put": {
+      "kind": "event",
+      "digest": "b5086d249e8502e9ead1d39156bb8d559bde7951cac0f14ce150345b4e42a2bf",
+      "event": "feedback/message-put",
+      "surface": false
+    },
+    "event:feedback/record": {
+      "kind": "event",
+      "digest": "b54940ff095c17e874c5be03815f4c2145a256cf3a1d34dae4ab2f7769dfffe8",
+      "event": "feedback/record",
+      "surface": false
+    },
+    "event:goal/change": {
+      "kind": "event",
+      "digest": "763c8a20af487263a0080548274f7437ef4a86e0ba8769127d1ced10a72c664d",
+      "event": "goal/change",
+      "surface": false
+    },
+    "event:hook/invoked": {
+      "kind": "event",
+      "digest": "8a6e1ec9e8db346b0e02f027db73c07a94f067a26d40c1aef1abd09c47ce7ba0",
+      "event": "hook/invoked",
+      "surface": false
+    },
+    "event:hook/result": {
+      "kind": "event",
+      "digest": "e75916628f3f10c2d50658bd143052a46285fbf1a9a700ba54947614603d26b4",
+      "event": "hook/result",
+      "surface": false
+    },
+    "event:image/offload": {
+      "kind": "event",
+      "digest": "b222069eea2d768065161c1147b1f2c78c1b54328c84b3586ae5c8f91b8ed35e",
+      "event": "image/offload",
+      "surface": false
+    },
+    "event:llm/retry": {
+      "kind": "event",
+      "digest": "525254db03b1d1e6b74cf55aced52817568331ac1f96c0818728910b6692e336",
+      "event": "llm/retry",
+      "surface": false
+    },
+    "event:llm/retry-started": {
+      "kind": "event",
+      "digest": "48e5c9861f16ac07e78cb7b5ae9dabdf7bb85c58baed5a51b4ad275050ea58e3",
+      "event": "llm/retry-started",
+      "surface": false
+    },
+    "event:model/selection": {
+      "kind": "event",
+      "digest": "35203ba7ad5ef6f97d556b85df20ae98f04f09c65748cecdf8eefdb8b6405ffc",
+      "event": "model/selection",
+      "surface": false
+    },
+    "event:permission/preset": {
+      "kind": "event",
+      "digest": "5c45bf4c544a7211dcd8ba6ba7e5f1bc39b49e7a9df9d5cbdc8e87c22771b37b",
+      "event": "permission/preset",
+      "surface": false
+    },
+    "event:plan/mode": {
+      "kind": "event",
+      "digest": "a7cf43ce7c2a4c038feed1885cd7a00d5c6ee2d90a7e0d56b46f78a3e1ca327f",
+      "event": "plan/mode",
+      "surface": false
+    },
+    "event:request/context": {
+      "kind": "event",
+      "digest": "37cbc9cf06d494cfe5c67f078af1605eacb8e4c2c853e9e26455b73de0ee7ccf",
+      "event": "request/context",
+      "surface": false
+    },
+    "event:request/header": {
+      "kind": "event",
+      "digest": "4208123b50df5006b181481ab45fcf1cde807b88d3fd4d340090bc2e202fac41",
+      "event": "request/header",
+      "surface": false
+    },
+    "event:sandbox/mode": {
+      "kind": "event",
+      "digest": "516da4cdd6d2f1e5ce488e648578ca51f40e458f707b803e5b24de870e799415",
+      "event": "sandbox/mode",
+      "surface": false
+    },
+    "event:schedule/change": {
+      "kind": "event",
+      "digest": "2a7f86849ae54b3398ee49661a757c4fcb59a6192b7036ee2ff514617e13fb42",
+      "event": "schedule/change",
+      "surface": false
+    },
+    "event:session-log-deepseek/delivery-accepted": {
+      "kind": "event",
+      "digest": "d63b8b8ffad9c02fd80c43a17df4f240c1fe8118ecca9de34f9d5871838ab5b9",
+      "event": "session-log-deepseek/delivery-accepted",
+      "surface": false
+    },
+    "event:session/end-seed": {
+      "kind": "event",
+      "digest": "5e6db6e24948d4a853c71cb9fabd252ad051ce93d4672c1266cf837c1c17b84e",
+      "event": "session/end-seed",
+      "surface": false
+    },
+    "event:session/title": {
+      "kind": "event",
+      "digest": "1b912703e2d64f91c99c675b8f805b01076c8325b905c1218ad81ef0b24909d5",
+      "event": "session/title",
+      "surface": false
+    },
+    "event:session/title-llm-request": {
+      "kind": "event",
+      "digest": "fa8f7d3ebf08a76c7f7a8b0781873c4d819b964da5dbb52cd3cdfa5da34f452d",
+      "event": "session/title-llm-request",
+      "surface": false
+    },
+    "event:step/end": {
+      "kind": "event",
+      "digest": "e0a787e6ec76c7c94fecbc501b489164ab0293db05bc947914077ad01e674f05",
+      "event": "step/end",
+      "surface": false
+    },
+    "event:step/start": {
+      "kind": "event",
+      "digest": "4513e088d43e6c68425be30451b9f961cc264fe7318ca62681c41d4d78615986",
+      "event": "step/start",
+      "surface": false
+    },
+    "event:subagent/catalog": {
+      "kind": "event",
+      "digest": "ae1f7110feeec697b8cab42b68f7709aa7b3279764099dfb53c25890d2e5c871",
+      "event": "subagent/catalog",
+      "surface": false
+    },
+    "event:subagent/descriptor": {
+      "kind": "event",
+      "digest": "b79ada42962cad0190a9d465805260567621fa3a4abd757eb31e6016b52d5ab5",
+      "event": "subagent/descriptor",
+      "surface": false
+    },
+    "event:subagent/model-selection-policy": {
+      "kind": "event",
+      "digest": "a6567ccb2e530606b775371eb4fa31468d72084339968e8b0440a516a23b39dc",
+      "event": "subagent/model-selection-policy",
+      "surface": false
+    },
+    "event:system/message": {
+      "kind": "event",
+      "digest": "69081694be231d56fd9580ba14645fd5e35373202605d5c5c841a9435b5fa3b1",
+      "event": "system/message",
+      "surface": true
+    },
+    "event:team/member": {
+      "kind": "event",
+      "digest": "4fb59762612c3e3ac3a3bd4f84c9c148d3c3893bd422ba2b201cc039fabd49bc",
+      "event": "team/member",
+      "surface": false
+    },
+    "event:team/message/delivered": {
+      "kind": "event",
+      "digest": "48f9c19417a1abbedfa59f4667bba36b93ac2db407adf5e84cb3ba0de30942cb",
+      "event": "team/message/delivered",
+      "surface": false
+    },
+    "event:team/message/queued": {
+      "kind": "event",
+      "digest": "21fb6a90d5068f6a0003b7ab316ed2f56342477146a65c00db0f13c4d8df667d",
+      "event": "team/message/queued",
+      "surface": false
+    },
+    "event:team/task": {
+      "kind": "event",
+      "digest": "d595ec73b32b016a6055333c67a5d646032b22e672da1d4a09c5b1ae398a093a",
+      "event": "team/task",
+      "surface": false
+    },
+    "event:todo/write": {
+      "kind": "event",
+      "digest": "b978cff734e62143eb56c9125423ec275405eda969802d42aaf73ecb987d3b26",
+      "event": "todo/write",
+      "surface": false
+    },
+    "event:tool-workflow/agent-end": {
+      "kind": "event",
+      "digest": "babf9ee4d1af62bf6c3a8103737f7a5e4e78ce179be835ce05a38803e15884b7",
+      "event": "tool-workflow/agent-end",
+      "surface": false
+    },
+    "event:tool-workflow/agent-start": {
+      "kind": "event",
+      "digest": "5f26a6c20b37632f8f57729d171c671def4683d994ac6257a8dffcd855101627",
+      "event": "tool-workflow/agent-start",
+      "surface": false
+    },
+    "event:tool-workflow/run-end": {
+      "kind": "event",
+      "digest": "42e0916e0dda5f6d1e7bb05d8514717147c036a79c9f36085683469516c1fd3f",
+      "event": "tool-workflow/run-end",
+      "surface": false
+    },
+    "event:tool-workflow/run-start": {
+      "kind": "event",
+      "digest": "c1f9e0405de6d18cabb9ee70782a027f9bbdc57e5abec9dcccdd56119e2e9058",
+      "event": "tool-workflow/run-start",
+      "surface": false
+    },
+    "event:tool/call": {
+      "kind": "event",
+      "digest": "3b1be838223869fe0a08210db85bf773796ed3f2373ac16555dff227cade0c48",
+      "event": "tool/call",
+      "surface": false
+    },
+    "event:tool/ptc-dispatch": {
+      "kind": "event",
+      "digest": "100f6dca1468538239522cde3533e5bd721d0f1a7b50bea8b0eb533ea6c96163",
+      "event": "tool/ptc-dispatch",
+      "surface": false
+    },
+    "event:tool/ptc-dispatch-start": {
+      "kind": "event",
+      "digest": "ec38b5949af8eacaf00df002f4acbe344f934f8a061e9cdc65a52a48e5f6dd93",
+      "event": "tool/ptc-dispatch-start",
+      "surface": false
+    },
+    "event:tool/result": {
+      "kind": "event",
+      "digest": "7c9f44e90a0058f4cc532ae20dad0c10afa6eba22e70a6c79fc79490bad64397",
+      "event": "tool/result",
+      "surface": true
+    },
+    "event:turn/end": {
+      "kind": "event",
+      "digest": "0f8512903d94f57a4748fa1a2092e64342856796684e6b8343db685b192745ce",
+      "event": "turn/end",
+      "surface": false
+    },
+    "event:turn/start": {
+      "kind": "event",
+      "digest": "aa0957eca50aeb28bcd2e6930b95809926edacb550c8c340ba526ba6b861b3d8",
+      "event": "turn/start",
+      "surface": false
+    },
+    "event:user/message": {
+      "kind": "event",
+      "digest": "3f72db3d87a0c5c43e68be467b4cca728eaf5adc1d5d2b6975ff42bfbd961761",
+      "event": "user/message",
+      "surface": true
+    },
+    "event:web/deepseek-search-llm-request": {
+      "kind": "event",
+      "digest": "cf6e3aaf1e2de6480aa0157730a41b9a492108a55304100b0f7e112711dd4331",
+      "event": "web/deepseek-search-llm-request",
+      "surface": false
+    },
+    "event:workspace/changes": {
+      "kind": "event",
+      "digest": "e308ccf867a5398e316e0af8cb6ce238a8d33a63b9b384c8250a686786285f72",
+      "event": "workspace/changes",
+      "surface": false
+    }
+  },
+  "acceptedRecords": {
+    "2026-09-11-initial": "1257b73faa71fda3504b42af8ef7fa6a8c608a1aafe4fc77f21b8cd1c30e0ec1",
+    "2026-09-12-auto-review-error-metadata": "a98f6eb5d28618a355a358bddf7b278a25ab8aa08288c85e32c2031d7994b865",
+    "2026-09-14-image-offload": "ec2ac7c3e20842e33870307384200b893a3ec0b0028882858abb0ac9dfc002c6",
+    "2026-09-14-workspace-changes-event": "b5455973864a92f227f4af0c8eae2182dc33a20d22d2121083652aa0e61af83d",
+    "2026-09-16-session-format-v4": "0d854cc665bea188f82b6b8d2298a7e484fd138dfdf1d1e974b8be2c9f15c6ac"
+  }
+}

package/references/official-docs/docs/persistence-changes/historical-formats/README.i18n.yaml

@@ -1,6 +1,28 @@
-# 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:
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/persistence-changes/historical-formats/README.md
-README.md: fda6ac3b4fc3e52ef215dc0a2fca00576cd4ef0c
-README.zh.md: 792f47e532d6ebfdbb745c1bc2703c7b5f4fcc17
+/:
+  en: 1257a74512f9daed
+  zh: 74e1378126c7dd99
+/session-persistence-formats:
+  en: a740a4786e0488d6
+  zh: c17883a78695cf67
+/session-persistence-formats/summary:
+  en: f1592445394a7daf
+  zh: 2a1c5f7fa307db45
+/session-persistence-formats/table-of-contents:
+  en: 14c57f30e676f6e3
+  zh: b1a0ccf26fab3727
+/session-persistence-formats/format-references:
+  en: b19e6cfc84bfc46d
+  zh: 5b1d86bcdab672ca
+/session-persistence-formats/scope-and-evidence:
+  en: b220062139ddac1e
+  zh: 7c4c0efe05dafa9c
+/session-persistence-formats/maintain-coverage:
+  en: 0be8010f3fd20d2d
+  zh: b6e3af11c81e8702
+/session-persistence-formats/dev-note:
+  en: b75c8458928b72b9
+  zh: 003ba4e17b4b5269

package/references/official-docs/docs/persistence-changes/historical-formats/README.md

@@ -31,7 +31,8 @@ The index is generated from validated snapshots and the current writer constant.
 | 0 | `dsh-v0.1.2-rc.1` | [V0](v0.md) | [JSON](v0.schema.json) | 54 / 415 |
 | 1 | PR #3349 | [V1](v1.md) | [JSON](v1.schema.json) | 54 / 415 |
 | 2 | `dsh-v0.1.3-alpha.2` | [V2](v2.md) | [JSON](v2.schema.json) | 56 / 435 |
-| 3 | Current checkout | [Current catalog](../../persistence-catalog.md) | [JSON](../../persistence-schema.json) | 61 / 470 |
+| 3 | PR #4320 | [V3](v3.md) | [JSON](v3.schema.json) | 60 / 467 |
+| 4 | Current checkout | [Current catalog](../../persistence-catalog.md) | [JSON](../../persistence-schema.json) | 62 / 590 |
 
 <!-- persistence-format-index:end -->
 
@@ -40,7 +41,7 @@ The index is generated from validated snapshots and the current writer constant.
 
 Each `vN.md` / `vN.zh.md` pair has `kind: persistence-format`, an identical `yaml persistence-format` declaration binding every root key to its captured digest, a pairing sidecar, and a complete `vN.schema.json`. The [template](../../../.agents/skills/dsh-doc/templates/persistence-format.md) defines these records. Roots cover the logical Session header, physical JSONL header, event envelope, and all first-party events at the selected checkpoint; each root includes every reachable declared type. Packed physical body records have separate codec owners linked from each page.
 
-V0 and V2 use the latest matching tags in the [captured prerelease archive](../releases/README.md). V1 uses an intermediate source tree identified in its reference because the captured tags contain no V1 writer. Historical sources retain file paths without line numbers. Snapshots preserve historical optional fields and opaque values; they do not substitute current types into older formats. Historical identifiers remain intact only in schema JSON and the verified generated schema regions; authored prose follows current terminology rules.
+V0 and V2 use the latest matching tags in the [captured prerelease archive](../releases/README.md). V1 uses an intermediate source tree identified in its reference because the captured tags contain no V1 writer. V3 captures the verified inventory before the V4 writer change in PR #4320. Historical sources retain file paths without line numbers. Snapshots preserve historical optional fields and opaque values; they do not substitute current types into older formats. Historical identifiers remain intact only in schema JSON and the verified generated schema regions; authored prose follows current terminology rules.
 
 These references describe selected schemas, not historical application replay or migration safety. Same-version event additions and optional payload changes can produce other valid inventories. The prerelease archive retains tag-by-tag differences; [change records](../README.md) retain current compatibility acknowledgements. Neither history is replaced by these format snapshots.