Skip to content

feat: opt-in branch-aware block masking via persistedMessageIds - #518

Open
SeniorHan wants to merge 3 commits into
ranxianglei:masterfrom
SeniorHan:2026-10-23_branch-aware-masking
Open

SeniorHan wants to merge 3 commits into
ranxianglei:masterfrom
SeniorHan:2026-10-23_branch-aware-masking

Conversation

@SeniorHan

Copy link
Copy Markdown

Same content as #516 (closed: branch name violated the YYYY-MM-DD_short-title convention; plus prettier formatting).

Opt-in engine support for extension-managed conversation-branch masking (needed by SeniorHan/keel-fold). Details in #516. [feat] branch-awareness · [feat] compress wiring · [test] end-to-end (4 cases, message-order matching upstream syncBlocks conventions; 1237/1237 locally).

SeniorHan and others added 3 commits October 24, 2026 01:00
Review cleanup for ranxianglei#518 (no behavior change): hoist the Set built from
findOffBranchBlocks so the restore path reuses it instead of an O(n^2)
Array.includes scan, and drop a redundant type assertion — CompressionBlock.expanded is already typed boolean | undefined.
@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 查重:不重复——#518 是 #516 的重新提交(#516 因分支命名不规范 + prettier 关闭,本次已改为 2026-10-23_branch-aware-masking 并过 prettier);按失败签名/关键词检索 open+closed 的 issue 与 PR,无其他相关条目。

标签: pi · scope/kernel · p3(场景源头是 pi 的 /tree rewind;改动集中在压缩引擎核心;opt-in 功能、对不参与宿主零影响,故最低档。)

Review 结论(独立重审,未照抄 issue 侧结论)

① 方向关:合理。我独立验证了机制:src/sync.ts:73-97 —— syncBlocks 只要一个 block「还有任何覆盖消息在视」就保持 active;rewind 落到 block 覆盖区间中部时,block 的摘要(含 rewind 点之后的另一分支决策)会顶替仍在视的少量消息注入,模型看到没发生的"未来"。根因是内核层信息缺失(内核不知道宿主的会话树),不是 syncBlocks 逻辑 bug;让宿主每轮声明全树持久化 id 集合 + turn 级 mask 打到了核心,且复用了既有 expanded ⇒ deactivate 路径(src/sync.ts:82),不加新状态、不加新节点。

八问:

  1. 是什么问题:可 rewind 会话树的宿主(pi /tree)回退后落在某个压缩块覆盖区间内时,该块的摘要描述的是另一分支(含回退点之后才做出的决策),却被注入顶替仍在视的少量消息——模型基于"未来"行动。
  2. 什么原因导致的:内核只看当前视图,无法区分"被压缩掉"与"在另一分支上";激活规则是 any-present⇒active,无法表达 off-branch 块。修法 = 宿主每轮声明全树持久化 id 集合(ProcessTurnInput.persistedMessageIds,可选),内核检出「部分可见 + 部分持久化但不可见」的块,本回合强制按 expanded 处理。
  3. 影响范围与严重程度:仅显式传入新字段的宿主受影响(keel-fold 为首家);不传字段的宿主行为零变化(已验证缺省路径与旧逻辑逐字节等价)。无此功能时,rewindable 宿主上的问题是内容完整性类(模型基于错误分支决策行动),触发条件为 rewind 落点在块区间内部。
  4. 怎么修复的:纯检测函数 findOffBranchBlocks()(镜像 syncBlocks 的 baseIdOf 子 id 语义,含 [bug] 0.0.90 regression: syncBlocks throws on id-less host-shaped messages (baseIdOf of undefined) #421 的字符串 id 防护教训);processTurn 在 pipeline 运行前把这类块强制 expanded=true(syncBlocks 随即将其 deactivate → 在视消息原文渲染),pipeline 结束后把原始 expanded 标志还原到结果 state——mask 永不落盘,回到主分支自然复活(syncBlocks 每轮重算 active)。
  5. 是否有回归问题:逐项清点结论——无回归。
    • 不参与路径:字段缺省 → offBranch=[] → 无 mask/restore,与旧代码等价 ✓
    • 输入 state 不变性:mask 构造新 state 对象;未被 mask 的块共享引用但 syncBlocks 深拷贝后才改;测试断言了输入不可变 ✓
    • 结果 state 中 masked 块为 active=false + expanded=undefined(只还原 expanded、不还原 active)——有意为之:types.ts 将此组合文档化为 legacy-resurrection,下一轮 syncBlocks 重算自愈 ✓
    • pipeline 内无任何节点写 expanded(grep 确认唯一读者 src/sync.ts:82,写者全在宿主侧)→ restore 不会覆盖回合内合法变更 ✓
    • masked 回合内 nudge/recommend/search/status 将该块视为 inactive——与既有 decompressed 块语义一致 ✓
    • §7.3 契约全部未触碰(节点顺序、wire 格式、state 形状、单 owner 原则、ref 不可变均不变;输入为增量可选字段)✓
    • 本地验证:typecheck / prettier / 定向测试(branch-awareness 4 + compress/pipeline/sync/hide-consumed/refold/regression-bugfixes 共 99)全绿;CI:pr-validation、build-artifact、test(Node 24) 绿,test(Node 22) 排队中(旧 head 8 项全绿)。
  6. 是否破坏缓存:不涉及失效策略变更。masked 回合 wire 字节从摘要 ref 变为原文 → 该回合前缀缓存 miss,这正是功能的意图(展示真值而非另一分支摘要);回到主分支渲染复原、缓存恢复。不参与宿主零影响;重试/游标/去重键策略未动。
  7. 是否改了设计方向:没有。新模块 src/branch-awareness.ts 是纯检测;接线是 processTurn 前后处理(与 lastPassIds 盖戳同风格),不加节点、不持久化、平台无关原则保持。
  8. 是否引入新配置:ProcessTurnInput.persistedMessageIds?: ReadonlySet<string>——可选,默认 undefined(=关闭),无 env/默认值变化,adapter 需要时自行接线(keel-fold)。

行为变更披露(Deliverables #4):不参与宿主零变化;参与宿主在被 mask 的回合:旧 = off-branch 块摘要替换在视消息(泄漏另一分支内容)→ 新 = 在视消息原文显示、摘要不注入。即修复目标本身。

Diff 整洁处置(已完成):

  • 原分支混入两个与本 PR 无关的个人笔记 commit(FORK-NOTES.md:fork 治理备忘、CCR 立项取消记录)——已移除(cherry-pick feat+style 至 master,作者信息保留),现 PR diff = 3 文件:src/branch-awareness.ts(新,+52)、src/compress.ts(+52/-1)、tests/branch-awareness.test.ts(新,+175)。
  • 顺手修了两处小 nit(独立 commit 32ecaf8,无行为变化):mask/restore 两路共享同一 Set(原先 restore 用 O(n²) 的 Array.includes);去掉冗余 as boolean | undefined 断言(字段本就如此类型化)。

测试有效性(④):4 个用例是真测试——用例 1 先钉住基线泄漏(不传字段时 FUTURE_DECISION 出现在输出里),再断言带字段输出不含它 + e1 原文渲染 + mask 未持久化 + 输入未被改;masking 回归会立刻变红。非阻塞建议:后续可补一例「完全 off-branch(无任何消息在视)不应被 mask」。

热点提示:PR #515 也改 src/compress.ts(applyCompression 区域:重复失败守卫、normalizeRangeKey),与本 PR 的 processTurn 区域不同段、无文本冲突;谁后合谁 rebase。

判定:可合——机制成立、实现最小、测试钉住了行为、diff 已收敛。按仓库规则 §7.4 这是 feat(新增能力面)属 human-gated,§6 另要求至少 2 个独立 agent review 后方可合并(本回复为第 1 个);当前 mergeable_state=blocked 即缺 required review。CI 除 test(Node 22) 尚在 runner 队列外全绿,owner 给 approval 即可。我不执行合并。

@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 补一行:cleaned head 32ecaf8 的 CI 现已全绿(test Node 22 / test Node 24 / pr-validation / build-artifact 四项均 success),上一条回复中"test(Node 22) 排队中"已过时。状态不变:可合,待 owner approval + 第二个 agent review。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants