docs(session): correct restore pipeline boundaries

2026-08-06 10:40:31 +08:00
parent 9cd2a20141
commit 44596dc0a3
@@ -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 .agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.md
-2026-08-05-large-session-jsonl-restore-pipeline.md: 159a529c299ece5aa2377779b4e8f79facb1608a
-2026-08-05-large-session-jsonl-restore-pipeline.zh.md: b4e3b03201513c7e02d52d6588ae8471590fbf84
+2026-08-05-large-session-jsonl-restore-pipeline.md: a99fca8cfa1b35f40b82778b2f2462b318348722
+2026-08-05-large-session-jsonl-restore-pipeline.zh.md: 73d2868700a0543d29fbcc16e913dda24defd37a
@@ -12,7 +12,7 @@ A representative profile contained 61.8 MiB of Zstandard data, 97.1 MiB of plain

 ## Decision

-Restoration is one ownership-transfer pipeline from the persistence artifact into `Session.fromRestore`. Each stage consumes the previous stage's output incrementally and retains only the authoritative event array plus incomplete-record state.
+Restoration is one ownership-transfer pipeline from the persistence artifact into `Session.fromRestore`. The compressed artifact remains the source buffer, while each decoding and scanning stage consumes the previous stage's output incrementally without retaining a whole-log plaintext or parsed copy; the resulting event array is the only complete decoded representation.

 ### Frame decoding

@@ -26,7 +26,7 @@ After approximately one second of accumulated frame work, the asynchronous reade

 `SessionLogScanner` searches raw buffers with `Buffer.indexOf(0x0A)` and converts only complete records to UTF-8 for `JSON.parse`. It carries an incomplete record across decoder writes and copies only that fragment because the private decoder may reuse its output buffer. It does not build a whole plaintext buffer or string, a line array, or a second parsed-record array.

-The scanner stops retaining events at the first unparsable row or sequence gap but continues inspecting later complete records. A later `turn/end` proves that the issue lies in the committed region and rejects the log; otherwise the issue is a recoverable final suffix. A partial JSONL record in a complete frame remains corruption, while complete records emitted from a torn final frame pass through the same scanner and retain the existing repair offset and recovered-event semantics.
+The scanner stops retaining events at the first unparsable row or sequence gap but continues inspecting later complete records. A later `turn/end` proves that the issue lies in the committed region and rejects the log. The Zstandard reader also rejects any unresolved parse, sequence, or partial-record issue after all complete frames; only a structurally torn final frame may contribute a recoverable suffix. Complete records emitted from that torn frame pass through the same scanner and retain the existing repair offset and recovered-event semantics.

 ### Restore admission

@@ -12,7 +12,7 @@ Status: implemented

 ## 决策

-恢复过程是一条从持久化产物进入 `Session.fromRestore` 的所有权转移流水线。每个阶段都会增量消费上一阶段的输出，只保留权威事件数组和不完整记录状态。
+恢复过程是一条从持久化产物进入 `Session.fromRestore` 的所有权转移流水线。压缩产物仍作为源缓冲区驻留，但解码与扫描阶段会增量消费上一阶段的输出，不会保留整份日志的明文或解析副本；最终事件数组是唯一完整的已解码表示。

 ### 帧解码

@@ -26,7 +26,7 @@ Zstandard 结构扫描器会在解码前识别完整帧范围。系统单独解

 `SessionLogScanner` 使用 `Buffer.indexOf(0x0A)` 在原始缓冲区中查找换行，只把完整记录转换为 UTF-8 并交给 `JSON.parse`。扫描器会跨解码写入保留不完整记录；由于私有解码器可能复用输出缓冲区，它只复制这个片段。扫描过程不会构造整份明文缓冲区或字符串，也不会构造行数组或第二份解析记录数组。

-扫描器在遇到第一条无法解析的记录或序列缺口后停止保留事件，但会继续检查后续完整记录。后续出现 `turn/end`，说明问题位于已提交区域，系统会拒绝该日志；否则该问题属于可恢复的最终后缀。完整帧内的部分 JSONL 记录仍视为损坏；撕裂最终帧产出的完整记录会经过同一扫描器，并保持既有修复偏移量与恢复事件语义。
+扫描器在遇到第一条无法解析的记录或序列缺口后停止保留事件，但会继续检查后续完整记录。后续出现 `turn/end`，说明问题位于已提交区域，系统会拒绝该日志。处理完所有完整帧后，如果仍存在未决的解析错误、序列错误或部分记录，Zstandard 读取器同样会拒绝日志；只有结构上撕裂的最终帧才能提供可恢复后缀。该撕裂帧产出的完整记录会经过同一扫描器，并保持既有修复偏移量与恢复事件语义。

 ### 恢复准入