dsh-plugin-dev-kb 1.6.0 → 1.8.1

package/kb/extra/persistence-changes/2026-10-27-subagent-settlement-attribution.zh.md

@@ -0,0 +1,60 @@
+---
+description: "记录持久化类型更改及其兼容性确认。"
+kind: persistence-change
+---
+
+# 2026-10-27-subagent-settlement-attribution
+
+[English](2026-10-27-subagent-settlement-attribution.md) | 中文
+
+## 概述
+
+为持久化的子代理结算通知增加可选 stopReason 归属信息，保持 Session 格式版本不变。
+
+## 目录
+
+- [声明](#declaration)
+- [兼容性](#compatibility)
+- [验证](#verification)
+- [开发备注](#dev-note)
+
+<a id="declaration"></a>
+## 声明
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-10-27-subagent-settlement-attribution
+baseline: false
+changes:
+  - root: "event:agent/inbox/spliced"
+    previous: "2026-10-13-liveshare-share-viewer-principal"
+    after: "ddce54a3873dc57113b0cd38ad9b23b3c259186139e8847e5e5f415d86f52482"
+    decision: same-version
+  - root: "event:developer/message"
+    previous: "2026-10-13-liveshare-share-viewer-principal"
+    after: "70ea8e7943c5e2d76905bcc2e694e8c3d5b138aaae3609f3e261b8d369a6e35a"
+    decision: same-version
+  - root: "event:session/title-llm-request"
+    previous: "2026-10-13-liveshare-share-viewer-principal"
+    after: "d95c624eddecdacf1ee74356196c09d2f3fcd625714be5e852a6b643fa12a7ca"
+    decision: same-version
+  - root: "event:user/message"
+    previous: "2026-10-13-liveshare-share-viewer-principal"
+    after: "dcb07e04496586d2664d72dab0e94312917da56927b2a0dc3ee53d6a33e32450"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## 兼容性
+
+新读取方接受缺少 stopReason 的历史通知，不得从英文摘要推断该字段。写入方始终记录已捕获执行的确切 stopReason。旧读取方保留额外的 source 元数据，继续使用已有 kind、notice form、summary、senderSessionId 和未改变的内容；原生 V4 source 准入校验生产方 kind，不拒绝额外归属字段。新元数据只影响展示，不影响回放、权限或恢复。无需迁移或提升 Session 版本。
+
+<a id="verification"></a>
+## 验证
+
+定向 Vitest 运行通过：continuation-messages.spec.ts（14 个测试）、external-activation.spec.ts（19 个测试）、continuation-messages-adapter.spec.ts（1 个测试）和 continuation.spec.ts（166 个测试），均位于 packages/subagent/subagent/tests。命令为 node node_modules/vitest/vitest.mjs run，后接上述测试文件路径。覆盖全部五种终止原因、历史归属信息不作推断、外部清理失败保留已捕获的执行原因、冷恢复，以及不变的 DeepSeek Messages 线协议内容。历史 Session 代际保持不变；受影响的当前格式快照预期包含 stopReason。
+
+<a id="dev-note"></a>
+## 开发备注
+
+无。

package/kb/extra/persistence-changes/2026-11-02-subagent-catalog-names.md

@@ -0,0 +1,48 @@
+---
+description: "Records a persistence type transition and its compatibility acknowledgement."
+kind: persistence-change
+---
+
+# 2026-11-02-subagent-catalog-names
+
+English | [中文](2026-11-02-subagent-catalog-names.zh.md)
+
+## Summary
+
+Adds version 3 of the parent-owned subagent/catalog payload, which records each continuable or parent-delivered external child's name, unique among its creator's children.
+
+## Table of Contents
+
+- [Declaration](#declaration)
+- [Compatibility](#compatibility)
+- [Verification](#verification)
+- [Dev Note](#dev-note)
+
+<a id="declaration"></a>
+## Declaration
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-11-02-subagent-catalog-names
+baseline: false
+changes:
+  - root: "event:subagent/catalog"
+    previous: "2026-09-19-external-subagent-catalog"
+    after: "d49164d37eab0f0f70fa787c65d887abbea869c010ccb103d717fab3519c3a41"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## Compatibility
+
+Version 0, 1, and 2 payloads keep their schemas and meaning; current readers restore them as unnamed children addressed by Session id. New local and parent-delivered external creation writes version 3. Projection stateVersion remains 6: unnamed checkpoints stay usable, and their suffix replay matches full replay with named events. Earlier releases reject the unknown payload version during native V4 admission and catalog projection restoration instead of misreading the entry, so a parent Session that recorded a named child fails loudly rather than losing a child.
+
+<a id="verification"></a>
+## Verification
+
+pnpm exec vitest run packages/subagent/subagent/tests: 495 tests passed, including named catalog restoration, invalid version-3 facts, sibling-unique reservation, cold resume path recovery, and external parent-delivered names. pnpm exec vitest run packages/session/session-format-v3-to-v4/tests: 397 tests passed, including native version-3 admission and rejection.
+
+<a id="dev-note"></a>
+## Dev Note
+
+None.

package/kb/extra/persistence-changes/2026-11-02-subagent-catalog-names.zh.md

@@ -0,0 +1,48 @@
+---
+description: "记录持久化类型更改及其兼容性确认。"
+kind: persistence-change
+---
+
+# 2026-11-02-subagent-catalog-names
+
+[English](2026-11-02-subagent-catalog-names.md) | 中文
+
+## 概述
+
+为父 Session 拥有的 subagent/catalog 载荷增加 version 3，记录每个 continuable 子代理或父级交付的 external 子代理在其创建者子代理中唯一的名称。
+
+## 目录
+
+- [声明](#declaration)
+- [兼容性](#compatibility)
+- [验证](#verification)
+- [开发备注](#dev-note)
+
+<a id="declaration"></a>
+## 声明
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-11-02-subagent-catalog-names
+baseline: false
+changes:
+  - root: "event:subagent/catalog"
+    previous: "2026-09-19-external-subagent-catalog"
+    after: "d49164d37eab0f0f70fa787c65d887abbea869c010ccb103d717fab3519c3a41"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## 兼容性
+
+version 0、1、2 载荷的 schema 和含义保持不变；当前读取方将其恢复为按 Session id 寻址的无名子代理。新的本地创建和父级交付的 external 创建写入 version 3。投影 stateVersion 保持为 6：无名检查点仍可复用，后缀回放与包含具名事件的全量回放一致。较早版本在原生 V4 准入和目录投影恢复时拒绝未知载荷版本，而不会误读条目，因此记录了具名子代理的父 Session 会明确失败，而不是丢失子代理。
+
+<a id="verification"></a>
+## 验证
+
+pnpm exec vitest run packages/subagent/subagent/tests：495 个测试通过，覆盖具名目录恢复、无效 version 3 事实、同级唯一预留、冷恢复路径还原以及父级交付 external 子代理的名称。pnpm exec vitest run packages/session/session-format-v3-to-v4/tests：397 个测试通过，覆盖原生 version 3 准入与拒绝。
+
+<a id="dev-note"></a>
+## 开发备注
+
+无。

package/kb/extra/persistence-changes/2026-11-02-team-task-owner-names.md

@@ -0,0 +1,48 @@
+---
+description: "Records a persistence type transition and its compatibility acknowledgement."
+kind: persistence-change
+---
+
+# 2026-11-02-team-task-owner-names
+
+English | [中文](2026-11-02-team-task-owner-names.zh.md)
+
+## Summary
+
+Adds optional ownerName to durable Team task snapshots, captured with ownerId during claim or reassignment and cleared with it when ownership ends.
+
+## Table of Contents
+
+- [Declaration](#declaration)
+- [Compatibility](#compatibility)
+- [Verification](#verification)
+- [Dev Note](#dev-note)
+
+<a id="declaration"></a>
+## Declaration
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-11-02-team-task-owner-names
+baseline: false
+changes:
+  - root: "event:team/task"
+    previous: "2026-09-11-initial"
+    after: "bca0f9cb63d8620b6954bb045b07bb07cb557513a7f0e2e177f5e87f704e7ba7"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## Compatibility
+
+Current readers accept existing task payloads without ownerName and display ownerId without rewriting or backfilling historical logs. New task records retain the same ownerId authorization and version 2 task semantics. Earlier Team projections use a strict task schema and reject records containing ownerName, retaining their last valid tasks and reporting a projection failure rather than silently misinterpreting ownership. Session format version remains unchanged. The agentTeam projection state version remains 7: version-7 checkpoints without ownerName remain usable, and suffix replay preserves names from later task events. Version-6 checkpoints still rebuild from events.
+
+<a id="verification"></a>
+## Verification
+
+Focused Agent Teams projection, task-board, tool, and JSONL/SQLite recovery tests pass. They cover saved root and nested owner names, clearing ownership, historical ID fallback, rejection of ownerName without ownerId, checkpoint rebuilds, and task reads and edits without descendant catalog queries.
+
+<a id="dev-note"></a>
+## Dev Note
+
+None.

package/kb/extra/persistence-changes/2026-11-02-team-task-owner-names.zh.md

@@ -0,0 +1,48 @@
+---
+description: "记录持久化类型更改及其兼容性确认。"
+kind: persistence-change
+---
+
+# 2026-11-02-team-task-owner-names
+
+[English](2026-11-02-team-task-owner-names.md) | 中文
+
+## 概述
+
+为持久化 Team 任务快照增加可选的 ownerName，在认领或重新分配时与 ownerId 一起记录，并在结束归属时一起清除。
+
+## 目录
+
+- [声明](#declaration)
+- [兼容性](#compatibility)
+- [验证](#verification)
+- [开发备注](#dev-note)
+
+<a id="declaration"></a>
+## 声明
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-11-02-team-task-owner-names
+baseline: false
+changes:
+  - root: "event:team/task"
+    previous: "2026-09-11-initial"
+    after: "bca0f9cb63d8620b6954bb045b07bb07cb557513a7f0e2e177f5e87f704e7ba7"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## 兼容性
+
+当前读取方接受没有 ownerName 的已有任务载荷，直接显示 ownerId，不改写或回填历史日志。新任务记录保留相同的 ownerId 授权和第 2 版任务语义。旧 Team 投影使用严格任务 schema，会拒绝包含 ownerName 的记录，保留最后的有效任务并报告投影失败，不会静默误读归属。Session 格式版本保持不变。agentTeam 投影状态版本保持为 7：缺少 ownerName 的第 7 版检查点仍可复用，后缀回放保留后续任务事件中的名称。第 6 版检查点仍从事件重建。
+
+<a id="verification"></a>
+## 验证
+
+聚焦的 Agent Teams 投影、任务板、工具及 JSONL/SQLite 恢复测试通过，覆盖保存的根与嵌套所有者名称、清除归属、历史 ID 回退、拒绝没有 ownerId 的 ownerName、检查点重建，以及不查询后代目录的任务读取和编辑。
+
+<a id="dev-note"></a>
+## 开发备注
+
+无。

package/kb/extra/persistence-changes/2026-11-05-timeline-priority-notice.md

@@ -0,0 +1,60 @@
+---
+description: "Records a persistence type transition and its compatibility acknowledgement."
+kind: persistence-change
+---
+
+# 2026-11-05-timeline-priority-notice
+
+English | [中文](2026-11-05-timeline-priority-notice.zh.md)
+
+## Summary
+
+Records a Timeline notice when the user adds or removes urgent priority.
+
+## Table of Contents
+
+- [Declaration](#declaration)
+- [Compatibility](#compatibility)
+- [Verification](#verification)
+- [Dev Note](#dev-note)
+
+<a id="declaration"></a>
+## Declaration
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-11-05-timeline-priority-notice
+baseline: false
+changes:
+  - root: "event:agent/inbox/spliced"
+    previous: "2026-10-27-retry-control-input"
+    after: "f5d843edb0eeef61c9f5328599d5f92b61112b7710b0310b043196b15b390d64"
+    decision: same-version
+  - root: "event:developer/message"
+    previous: "2026-10-27-retry-control-input"
+    after: "7ee5a828196d9e4b1672f94f977e68f37125da4297c23029dd682823c09e12fd"
+    decision: same-version
+  - root: "event:session/title-llm-request"
+    previous: "2026-10-27-retry-control-input"
+    after: "4ee17e4219bd5fab6148ec0a8b3ec0fb939edb8f211374cf779bc8135ef9bed2"
+    decision: same-version
+  - root: "event:user/message"
+    previous: "2026-10-27-retry-control-input"
+    after: "fb6a6e338625067ac582f55dde412a583040cd738bb8fc6820cb0b941c59f05a"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## Compatibility
+
+Existing messages keep their source and meaning. Timeline notices carry ordinary text and a source label. Readers without Timeline can keep the unknown source and read the text without applying a task update. Timeline stores task trees, reports, and discussions in the session log as ignorable `plugin:timeline/*` records. Readers without Timeline skip these records.
+
+<a id="verification"></a>
+## Verification
+
+Timeline's priority tests check that only user edits to urgent priority enqueue a notice. The process recovery test checks that Timeline state survives an interrupted writer.
+
+<a id="dev-note"></a>
+## Dev Note
+
+None.

package/kb/extra/persistence-changes/2026-11-05-timeline-priority-notice.zh.md

@@ -0,0 +1,60 @@
+---
+description: "记录持久化类型更改及其兼容性确认。"
+kind: persistence-change
+---
+
+# 2026-11-05-timeline-priority-notice
+
+[English](2026-11-05-timeline-priority-notice.md) | 中文
+
+## 概述
+
+记录用户添加或取消紧急优先级时的时间线通知。
+
+## 目录
+
+- [声明](#declaration)
+- [兼容性](#compatibility)
+- [验证](#verification)
+- [开发备注](#dev-note)
+
+<a id="declaration"></a>
+## 声明
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-11-05-timeline-priority-notice
+baseline: false
+changes:
+  - root: "event:agent/inbox/spliced"
+    previous: "2026-10-27-retry-control-input"
+    after: "f5d843edb0eeef61c9f5328599d5f92b61112b7710b0310b043196b15b390d64"
+    decision: same-version
+  - root: "event:developer/message"
+    previous: "2026-10-27-retry-control-input"
+    after: "7ee5a828196d9e4b1672f94f977e68f37125da4297c23029dd682823c09e12fd"
+    decision: same-version
+  - root: "event:session/title-llm-request"
+    previous: "2026-10-27-retry-control-input"
+    after: "4ee17e4219bd5fab6148ec0a8b3ec0fb939edb8f211374cf779bc8135ef9bed2"
+    decision: same-version
+  - root: "event:user/message"
+    previous: "2026-10-27-retry-control-input"
+    after: "fb6a6e338625067ac582f55dde412a583040cd738bb8fc6820cb0b941c59f05a"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## 兼容性
+
+已有消息保留原有来源和含义。时间线通知包含普通文本和来源标签。未加载时间线的读取方可保留未知来源并读取文本，无需应用任务更新。时间线将任务树、报告和讨论保存为会话日志中可忽略的 `plugin:timeline/*` 记录。未加载时间线的读取方会跳过这些记录。
+
+<a id="verification"></a>
+## 验证
+
+时间线优先级测试验证仅用户修改紧急优先级时才排入通知。进程恢复测试验证写入进程意外退出后仍可恢复时间线状态。
+
+<a id="dev-note"></a>
+## 开发备注
+
+无。

package/kb/extra/persistence-changes/README.md

@@ -1,90 +1,92 @@
----
-description: "Review and maintain recorded Session persistence-type changes, their schema snapshots, and compatibility decisions."
----
-
-# Persistence-type change records
-
-English | [中文](README.zh.md)
-
-## Summary
-
-Use this reference to inspect an acknowledged Session persistence-type change and its predecessor. Each record binds a compatibility decision to exact generated schemas. Local checks compare the current source with the recorded history using only files in the checkout. Start with the [review cookbook](../cookbook/reviewing-persistence-type-changes.md) when changing a persisted type.
-
-For older tagged versions, use the [prerelease archive](releases/README.md). It reconstructs alpha/RC type differences for historical reading and format validation; its observations do not serve as current compatibility acknowledgements.
-
-For complete schemas grouped by Session format, use the [format references](historical-formats/README.md). Their coverage follows the writer constant, including intermediate formats without a release tag.
-
-## Table of Contents
-
-- [Files and ownership](#files-and-ownership)
-- [Compatibility rules](#compatibility-rules)
-- [History and limitations](#history-and-limitations)
-- [Dev Note](#dev-note)
-
------
-
-<a id="files-and-ownership"></a>
-## Files and ownership
-
-The generated [catalog](../persistence-catalog.md) provides readable declarations and digests; the [schema inventory](../persistence-schema.json) contains the normalized types. Roots cover the logical Session header, the physical JSONL header line, the event envelope, and every repository-declared event. Referenced types contribute transitively to each affected root's digest.
-
-Each dated record has four sibling files:
-
-| File | Owner |
-|---|---|
-| `YYYY-MM-DD-slug.md` | English acknowledgement with `kind: persistence-change`, one machine declaration, compatibility reasoning, and verification evidence |
-| `YYYY-MM-DD-slug.zh.md` | Chinese counterpart with the identical machine declaration |
-| `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>
-## Compatibility rules
-
-Every detected structural change requires an acknowledgement. Keep the Session version when older readers preserve the required meaning of accepted data, safely ignore optional features while retaining opaque records, or refuse unsupported required data before execution, mutation, or recovery truncation. New readers must preserve historical meaning and readability. Bump only when unsafe interpretation cannot be prevented by an effective discriminator. Unknown fields or values count only when existing readers actually handle them safely; type differences alone cannot establish that behavior. See the [reader-compatibility decision](../../.agents/notes/implemented/process/2026-10-08-session-reader-compatibility-review.md).
-
-| Detected change | Recording requirement |
-|---|---|
-| 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 under the existing compatibility rules | `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 | Compatibility review for `same-version`, or explicit `version-bump` |
-| Change the Session header or event envelope | Compatibility review for `same-version`; a header version change requires `version-bump` |
-
-The classifier identifies established same-version cases and changes requiring compatibility review; it cannot decide semantic safety. The latter require an explicit `--decision same-version` when recording or updating without a version increase. The acknowledgement’s Compatibility section explains actual reader behavior in both directions, and Verification records the executed checks. Review the complete transition, including simultaneous changes. An explicit `version-bump` instead requires its own increasing `SessionHeader.version` transition; a same-version decision cannot waive a header version change. Finalized records remain immutable, so a later record cannot reuse the accepted 3→4 transition.
-
-The CLI requires that explicit choice before generating a flagged same-version record. CI reads the recorded `decision: same-version` and accepts it when the ordinary history, schema, and header-version constraints hold, whether the record was generated or edited manually. Verification cannot establish how the record was authored or whether a human reviewed it. Reviewers compare base and head inventories with [`persistence-review`](../cookbook/reviewing-persistence-type-changes.md#generate); `--check` validates current-tree consistency and cannot reveal a transition already covered by an acknowledgement.
-
-An ordinary event may add payload alternatives with a required, nonnegative integer `data.version` greater than every existing payload version, provided every existing alternative remains readable under the established same-version rules above. Optional property additions and required-to-optional changes may accompany the new version; each retained alternative is compared separately. Other payload changes require compatibility review. 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 structural changes require compatibility review. Multiple context-form alternatives with the same wire kind form one group.
-
-Every same-version explanation states how old records remain readable and how older readers handle new records, including established cases that need no explicit CLI decision. A feature absent from a log must retain the old behavior; dispensable features must be safe to ignore; required features need an effective refusal signal. Unsupported-feature refusal must not become corruption recovery or tail truncation. For required-to-optional changes, explain how readers handle an absent value. Reviewers assess behavior and evidence; the checker validates the declaration and type classification. A version-bump record 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, 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. 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 and fingerprints; 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
-
-<details>
-<summary>Working context for maintainers — click to expand</summary>
-
-None.
-
-</details>
+---
+description: "Review and maintain recorded Session persistence-type changes, their schema snapshots, and compatibility decisions."
+---
+
+# Persistence-type change records
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Use this reference to inspect an acknowledged Session persistence-type change and its predecessor. Each record binds a compatibility decision to exact generated schemas. Local checks compare the current source with the recorded history using only files in the checkout. Start with the [review cookbook](../cookbook/reviewing-persistence-type-changes.md) when changing a persisted type.
+
+For older tagged versions, use the [prerelease archive](releases/README.md). It reconstructs alpha/RC type differences for historical reading and format validation; its observations do not serve as current compatibility acknowledgements.
+
+For complete schemas grouped by Session format, use the [format references](historical-formats/README.md). Their coverage follows the writer constant, including intermediate formats without a release tag.
+
+## Table of Contents
+
+- [Files and ownership](#files-and-ownership)
+- [Compatibility rules](#compatibility-rules)
+- [History and limitations](#history-and-limitations)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="files-and-ownership"></a>
+## Files and ownership
+
+The generated [catalog](../persistence-catalog.md) provides readable declarations and digests; the [schema inventory](../persistence-schema.json) contains the normalized types. Roots cover the logical Session header, the physical JSONL header line, the event envelope, and every repository-declared event. Referenced types contribute transitively to each affected root's digest.
+
+Each `.schema.json` file stores one node table keyed by the first 16 hexadecimal digits of each node's subgraph digest, with one root, type, or node per line. Roots and types locate their graphs through their own digests, so a type change rewrites only the changed nodes, their ancestors, and the affected digests. Generators own the exact text; verifiers reject any other layout.
+
+Each dated record has four sibling files:
+
+| File | Owner |
+|---|---|
+| `YYYY-MM-DD-slug.md` | English acknowledgement with `kind: persistence-change`, one machine declaration, compatibility reasoning, and verification evidence |
+| `YYYY-MM-DD-slug.zh.md` | Chinese counterpart with the identical machine declaration |
+| `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-writing/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>
+## Compatibility rules
+
+Every detected structural change requires an acknowledgement. Keep the Session version when older readers preserve the required meaning of accepted data, safely ignore optional features while retaining opaque records, or refuse unsupported required data before execution, mutation, or recovery truncation. New readers must preserve historical meaning and readability. Bump only when unsafe interpretation cannot be prevented by an effective discriminator. Unknown fields or values count only when existing readers actually handle them safely; type differences alone cannot establish that behavior. See the [reader-compatibility decision](../../.agents/notes/implemented/process/2026-10-08-session-reader-compatibility-review.md).
+
+| Detected change | Recording requirement |
+|---|---|
+| 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 under the existing compatibility rules | `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 | Compatibility review for `same-version`, or explicit `version-bump` |
+| Change the Session header or event envelope | Compatibility review for `same-version`; a header version change requires `version-bump` |
+
+The classifier identifies established same-version cases and changes requiring compatibility review; it cannot decide semantic safety. The latter require an explicit `--decision same-version` when recording or updating without a version increase. The acknowledgement’s Compatibility section explains actual reader behavior in both directions, and Verification records the executed checks. Review the complete transition, including simultaneous changes. An explicit `version-bump` instead requires its own increasing `SessionHeader.version` transition; a same-version decision cannot waive a header version change. Finalized records remain immutable, so a later record cannot reuse the accepted 3→4 transition.
+
+The CLI requires that explicit choice before generating a flagged same-version record. CI reads the recorded `decision: same-version` and accepts it when the ordinary history, schema, and header-version constraints hold, whether the record was generated or edited manually. Verification cannot establish how the record was authored or whether a human reviewed it. Reviewers compare base and head inventories with [`persistence-review`](../cookbook/reviewing-persistence-type-changes.md#generate); `--check` validates current-tree consistency and cannot reveal a transition already covered by an acknowledgement.
+
+An ordinary event may add payload alternatives with a required, nonnegative integer `data.version` greater than every existing payload version, provided every existing alternative remains readable under the established same-version rules above. Optional property additions and required-to-optional changes may accompany the new version; each retained alternative is compared separately. Other payload changes require compatibility review. 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 structural changes require compatibility review. Multiple context-form alternatives with the same wire kind form one group.
+
+Every same-version explanation states how old records remain readable and how older readers handle new records, including established cases that need no explicit CLI decision. A feature absent from a log must retain the old behavior; dispensable features must be safe to ignore; required features need an effective refusal signal. Unsupported-feature refusal must not become corruption recovery or tail truncation. For required-to-optional changes, explain how readers handle an absent value. Reviewers assess behavior and evidence; the checker validates the declaration and type classification. A version-bump record 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, 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. 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 and fingerprints; 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
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>