docs(runtime): 说明抵消证明、ACK 重放和历史恢复边界 #12

2026-11-12T04:51:53Z

codex-bot commented

2026-11-12 04:51:53 +00:00

本批补充三个运行时模块的注释，使恢复与同步的实现边界能够被准确理解；执行代码保持不变。

改动范围：

import-duplicate.ts：说明完整 NDJSON 编码、依赖/外部 guard 收集、旧源基础校验、引用合同和提交前检查。
duplicate-source.ts：说明 checkpoint 绑定、FIFO 投影缓存、ordinal 懒转换与不同阶段的取消处理。
import-document.ts：说明完整索引准备、元数据/元素范围、父链成本及 ordinal 读取。
import-native.ts：说明目标与依赖生命周期、reserve 副作用、引用映射、声明式任务字段省略和资源授权边界。
import-read-proof.ts：说明 LRU/pending/hash 表、整范围提交证明、恢复 verify 合同、取消与底层读取容量。
import-identities.ts：说明基表捕获、used 索引复用、写时复制、finish/clear 生命周期和上层身份校验责任。
import-verification.ts：说明 durable seal 索引、发送闸门、连续块前缀及引擎拥有的证据发布。
import-byte-reader.ts：说明范围截断、返回缓冲所有权、错误分类和内容身份验证边界。
import-json-array.ts：说明字节游标、缓存/扫描栈、单条缓冲、分隔验证与记录级错误。
import-document-stream.ts：说明 header 准备、ordinal/range 区别、范围串行延伸、重读/重试和坏尾部处理。
copy-budget.ts、import-budget.ts：说明合作时间片、工作计数、取消检查点与顺序 await 合同。
import-batches.ts：说明运行时批大小反馈、增长/收缩阈值及非持久性能状态。
import-groups.ts：说明 SCC 邻接表/DFS 栈、就绪组扫描、软/硬预算及未就绪组的后续处理。
digest-pool.ts：说明等待/执行容量、输出合同、取消和关闭的真实执行边界。
browser-digests.ts、digest.worker.ts：说明能力选择、单任务 Worker 协议、错误传播与响应采纳。
digest-worker-source.ts：说明原生 64MiB 阈值、失败不重试和 Worker 微任务让出。
import-integrity.ts、sha256.ts：说明顺序读块、取消检查、内存生命周期和同步增量状态。
asset-depot.ts：说明元信息校验/捕获、每次采纳重新授权、已有绑定读取及关闭后的结果采纳。
display-cache.ts：说明 owner/key 复用、独立 lease、最后释放、错误清理与权限/pin 的调用方责任。
image-decoder.ts、browser-images.ts、image.worker.ts：说明等待/active 容量、取消后的槽位归还、Worker 消息校验和 bitmap 清理。
resource-retention.ts：说明 pin 表方向、working/ACK 合并、保守任务保留、软退休撤销和 reservation 发布屏障。
orphan-files.ts：说明孤立文件覆盖条件、永久身份保留、盘点更新与异步读取取消。
import-file-retention.ts：说明源归属索引、当前/旧源退休资格、generation 更新、快路和外围屏障职责。
depot-cut.ts：说明清单生成中的读取、元数据与字节项、采纳 revision 约束以及原子提交职责。
batch-projection.ts：解释稀疏基线、原条件链检查、guard 的组合语义、UTF-8 成本比较与回退/抛错区别。
change-rebase.ts：解释逆向意图上下文、样式键合并、世界空间重规划、创建依赖排序及候选发布边界。
network.ts：解释单实例 FIFO 名额转交、同步准入钩子及排队/运行中取消的差异。
elision.ts：解释闭合生命周期证明、候选前缀、全账本复核和本地墓碑的不同职责。
reconcile.ts：解释规范读取的版本条件、操作参与 canvas 的来源，以及未解决意图的重放范围。
history-replay.ts：解释历史证据的版本绑定、两栈元数据回放和 entries 比较，不将其描述为文档写入。

验证：本 PR 三十五个文件均为注释改动，分批 AST 一致；抵消/ACK/历史相关单测 31/31 通过；wire/网络/run/结构恢复相关单测 94/94 通过；资源/孤立文件/导入源/导入引擎/共享仓库相关单测 109/109 通过；共享仓库/显示租约/解码池相关单测 15/15 通过（Worker 替身，本轮未运行真实浏览器解码）；摘要调度/Worker 算法/流式 SHA/源完整性相关单测 13/13 通过（适配器使用 Worker 替身）；复制预算/自适应批/引用分组/导入相关单测 43/43 通过；JSON 数组/文档流/读取证明相关单测 23/23 通过；读取证明/稳定 ID/导入引擎 seal 相关单测 76/76 通过；文档索引/原生转换/导入引擎相关单测 67/67 通过；懒复制源/引用合同/复制预算相关单测 11/11 通过；git diff --check 通过。

从 PR #11 合并后的最新 main 创建，只包含本批注释提交。全项目注释工作仍在第 5 阶段审查中，本 PR 是可独立评审的阶段交付。
等待用户手动合并。

本批补充三个运行时模块的注释，使恢复与同步的实现边界能够被准确理解；执行代码保持不变。改动范围： - import-duplicate.ts：说明完整 NDJSON 编码、依赖/外部 guard 收集、旧源基础校验、引用合同和提交前检查。 - duplicate-source.ts：说明 checkpoint 绑定、FIFO 投影缓存、ordinal 懒转换与不同阶段的取消处理。 - import-document.ts：说明完整索引准备、元数据/元素范围、父链成本及 ordinal 读取。 - import-native.ts：说明目标与依赖生命周期、reserve 副作用、引用映射、声明式任务字段省略和资源授权边界。 - import-read-proof.ts：说明 LRU/pending/hash 表、整范围提交证明、恢复 verify 合同、取消与底层读取容量。 - import-identities.ts：说明基表捕获、used 索引复用、写时复制、finish/clear 生命周期和上层身份校验责任。 - import-verification.ts：说明 durable seal 索引、发送闸门、连续块前缀及引擎拥有的证据发布。 - import-byte-reader.ts：说明范围截断、返回缓冲所有权、错误分类和内容身份验证边界。 - import-json-array.ts：说明字节游标、缓存/扫描栈、单条缓冲、分隔验证与记录级错误。 - import-document-stream.ts：说明 header 准备、ordinal/range 区别、范围串行延伸、重读/重试和坏尾部处理。 - copy-budget.ts、import-budget.ts：说明合作时间片、工作计数、取消检查点与顺序 await 合同。 - import-batches.ts：说明运行时批大小反馈、增长/收缩阈值及非持久性能状态。 - import-groups.ts：说明 SCC 邻接表/DFS 栈、就绪组扫描、软/硬预算及未就绪组的后续处理。 - digest-pool.ts：说明等待/执行容量、输出合同、取消和关闭的真实执行边界。 - browser-digests.ts、digest.worker.ts：说明能力选择、单任务 Worker 协议、错误传播与响应采纳。 - digest-worker-source.ts：说明原生 64MiB 阈值、失败不重试和 Worker 微任务让出。 - import-integrity.ts、sha256.ts：说明顺序读块、取消检查、内存生命周期和同步增量状态。 - asset-depot.ts：说明元信息校验/捕获、每次采纳重新授权、已有绑定读取及关闭后的结果采纳。 - display-cache.ts：说明 owner/key 复用、独立 lease、最后释放、错误清理与权限/pin 的调用方责任。 - image-decoder.ts、browser-images.ts、image.worker.ts：说明等待/active 容量、取消后的槽位归还、Worker 消息校验和 bitmap 清理。 - resource-retention.ts：说明 pin 表方向、working/ACK 合并、保守任务保留、软退休撤销和 reservation 发布屏障。 - orphan-files.ts：说明孤立文件覆盖条件、永久身份保留、盘点更新与异步读取取消。 - import-file-retention.ts：说明源归属索引、当前/旧源退休资格、generation 更新、快路和外围屏障职责。 - depot-cut.ts：说明清单生成中的读取、元数据与字节项、采纳 revision 约束以及原子提交职责。 - batch-projection.ts：解释稀疏基线、原条件链检查、guard 的组合语义、UTF-8 成本比较与回退/抛错区别。 - change-rebase.ts：解释逆向意图上下文、样式键合并、世界空间重规划、创建依赖排序及候选发布边界。 - network.ts：解释单实例 FIFO 名额转交、同步准入钩子及排队/运行中取消的差异。 - elision.ts：解释闭合生命周期证明、候选前缀、全账本复核和本地墓碑的不同职责。 - reconcile.ts：解释规范读取的版本条件、操作参与 canvas 的来源，以及未解决意图的重放范围。 - history-replay.ts：解释历史证据的版本绑定、两栈元数据回放和 entries 比较，不将其描述为文档写入。验证：本 PR 三十五个文件均为注释改动，分批 AST 一致；抵消/ACK/历史相关单测 31/31 通过；wire/网络/run/结构恢复相关单测 94/94 通过；资源/孤立文件/导入源/导入引擎/共享仓库相关单测 109/109 通过；共享仓库/显示租约/解码池相关单测 15/15 通过（Worker 替身，本轮未运行真实浏览器解码）；摘要调度/Worker 算法/流式 SHA/源完整性相关单测 13/13 通过（适配器使用 Worker 替身）；复制预算/自适应批/引用分组/导入相关单测 43/43 通过；JSON 数组/文档流/读取证明相关单测 23/23 通过；读取证明/稳定 ID/导入引擎 seal 相关单测 76/76 通过；文档索引/原生转换/导入引擎相关单测 67/67 通过；懒复制源/引用合同/复制预算相关单测 11/11 通过；git diff --check 通过。从 PR #11 合并后的最新 main 创建，只包含本批注释提交。全项目注释工作仍在第 5 阶段审查中，本 PR 是可独立评审的阶段交付。等待用户手动合并。

codex-bot added 1 commit 2026-11-12 04:51:54 +00:00

docs(runtime): clarify elision and reconciliation evidence 20bdc7d44a

codex-bot added 1 commit 2026-11-12 04:54:41 +00:00

docs(runtime): explain wire projection and conflict replanning c491cd023c

codex-bot added 1 commit 2026-11-12 04:58:21 +00:00

docs(runtime): clarify resource and file retention boundaries 9ea8463867

codex-bot added 1 commit 2026-11-12 05:01:42 +00:00

docs(runtime): explain asset display and image decode lifecycles f6acdac8d8

codex-bot added 1 commit 2026-11-12 05:04:30 +00:00

docs(runtime): explain digest scheduling and streaming boundaries 2b0afddd07

codex-bot added 1 commit 2026-11-12 05:07:23 +00:00

docs(runtime): explain import scheduling and dependency selection d02cd2b01d