From 44596dc0a3d89acf9619fd75f8933548d136b6e7 Mon Sep 17 00:00:00 2001 From: imccyu Date: Wed, 5 Aug 2026 17:47:59 +0800 Subject: [PATCH] docs(session): correct restore pipeline boundaries --- .../2026-08-05-large-session-jsonl-restore-pipeline.i18n.yaml | 4 ++-- .../2026-08-05-large-session-jsonl-restore-pipeline.md | 4 ++-- .../2026-08-05-large-session-jsonl-restore-pipeline.zh.md | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.i18n.yaml index bd0b224429..e991532e8e 100644 --- a/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.i18n.yaml @@ -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 diff --git a/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.md b/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.md index 159a529c29..a99fca8cfa 100644 --- a/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.md +++ b/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.md @@ -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 diff --git a/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.zh.md b/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.zh.md index b4e3b03201..73d2868700 100644 --- a/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.zh.md +++ b/.agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.zh.md @@ -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 读取器同样会拒绝日志；只有结构上撕裂的最终帧才能提供可恢复后缀。该撕裂帧产出的完整记录会经过同一扫描器，并保持既有修复偏移量与恢复事件语义。 ### 恢复准入