Repository navigation
fix(coordination): distinguish invalid snapshots from invalid requests - #8545
Conversation
Signed-off-by: lusendong.6789 <lusendong.6789@bytedance.com> Co-authored-by: TRAE CLI <traecli@bytedance.com>
cocolord
left a comment
There was a problem hiding this comment.
Reviewer: model_agent; GPT-6; OpenAI; self_reported (runtime session attribution unavailable)
Approval conclusion (author-owned PR; GitHub blocks formal self-approval)
没有阻断性发现。审查对象为 9698eee441d4e9534d8854925908b1b1c6fbfddf;认可下面限定范围内的诊断修复,GitHub CI 的排队状态与合入门禁单独记录。
动机 / Motivation
读取工作列表的 CLI 用户和自动续跑调用方,在请求有效但持久化 Todo 契约不受支持时遇到误导性诊断。同一份合法读取请求遇到未知字段清单时,旧代码提示请求无效;修复后明确指出 snapshot projection 校验失败,并保留字段契约不匹配的具体原因。已验证 CLI 能返回准确的失败类别,完整保留原始原因,且拒绝结果不含部分工作记录。本次不升级已安装 runtime,不让旧 reader 接受未知新字段,也不证明整个最小内核的性能或完整交付。已安装 Host 的升级资格、完整成本及 adoption 仍由原发行和最小内核工作承接。
改动思路 / Approach
错误归属在既有 TypeScript snapshot owner 中判定,完整性校验继续由 canonicalTodoCollection 及其原 validator 负责;Python 只传递结果。本 PR 完整交付请求错误与持久化 projection 校验错误的区分,以及真实调用方可见的失败读回。最小替代方案就是当前这个局部 catch:若在最外层统一改错误码,会把真正的参数错误也归咎于存储。若放宽未知字段校验,又会破坏完整读取的前提。这里只按异常类型和实际失败阶段分类,没有新增校验器、provider、自动重试或迁移步骤。
具体改动 / Changes
关键代码讲解
readCanonicalSnapshotFromStore先解析请求并检查 continuation,再进入canonicalTodoCollection。只有该调用抛出的AuthorityStoreProtocolError被映射为新原因;原始错误信息完整保留。其他异常继续走原有处理。readCanonicalSnapshotPage复用现有 typed failure envelope,输出失败且不携带部分 rows;provider 打开失败和 writer fence 的专用诊断仍保留优先级。完整快照与分页读取共享这一边界,Python adapter 及真实 CLI 测试验证了原因没有在后续传输中丢失。
规范按修改前的 docs/architecture/rfcs/monorepo-distribution-split-v0.md、revision 8986ed85bf5477e1f0df7b93cc2934a97188bece 评判。complete-read 对应完整记录、lease、read-model 和 acceptance 仍由同一 owner 验证;snapshot-restart 对应过期 continuation 必须整次重读;authority-preservation 对应 revision、digest、lease 和无部分成功要求。三项均 implemented;双语新增 checkpoint 仅记录本次诊断结果,不作为自身正确性的依据。
生产变化为 11 行新增、3 行删除;其余为既有测试文件中的回归和双语说明。File/SQLite 用例同时给出无效参数和无效 head,证实请求错误仍优先;另外断言失败前后 authority head 完全相同。真实 PostgreSQL 用例补齐相同共享入口的后端读回。
对主干的风险 / Risks
最大风险是扩大 catch 范围后错误归属失真,或为了兼容旧客户端接受未知字段。当前代码按 typed 异常和调用边界限定范围,两种风险均被负例覆盖。原字段清单、历史 manifest 兼容、digest、lease、分页和完整读取规则保持原 owner,没有新增副作用、scope gate 或 feature-off 声明。既有 CLI 是实际消费者,本变更不涉及渲染页面。
PASS:同一完整测试 harness 在 baseline 为 59 pass / 4 个预期失败,在 head 为 63 pass;四个失败恰为被修复的诊断断言。另有 39 项 Python transport/RPC/CLI、392 项隔离 PostgreSQL 集成、TypeScript typecheck、Python lint 和标准 premerge 全部通过。预合入检查含双语、语义和公开边界校验,原始日志保留在私有证据中。
UNVERIFIED:读取 CI 时七个 job 仍在排队,一个过期 PR 取消 job 跳过,Summary 成功。它们不替代本地必要证据,也不能写成全部 CI 通过。安装版升级和模型实际采用效果未在本 PR 验证;未知字段仍需兼容 reader 或按原 authority 流程恢复。
语义与 CI 对齐
新增值扩展既有 failure reason_code;复用 SnapshotReadError,不改 schema keys、持久化 vocabulary 或默认 provider。diff advisory 没有捕获动态 string carrier,因此该值已人工沿 TS 到 Python/CLI 检查;完整语义 smoke 通过。CI 未完成保留为单独的 readiness 事实。
我的整体评价 / Verdict
justified_increment:错误归属已通过真实入口验证,收益是失败读回更准确。long_horizon 为 preserved:状态、重试和后续执行规则保持原状,未声称少重试或性能收益;user_experience 为 improved:CLI 原因更清楚,没有增加输入或确认轮次。只改变 todo list 的结构化错误类别;没有改动任何渲染页面或 UI 布局。兼容性选择保留已发布历史 manifest,未添加新的旧请求分支;相邻 owner 已直接复用,进一步拆 helper 没有收益。既有安装资格与完整成本缺口继续由原工作承接。
English verdict: APPROVE 9698eee441d4e9534d8854925908b1b1c6fbfddf. No blocking findings; real File/SQLite CLI and PostgreSQL checks validate the scoped diagnostic correction. Remote CI and installed-runtime upgrade remain separate qualifications.
A valid canonical snapshot request currently reports
canonical_snapshot_request_invalidwhen the persisted Todo field manifest or record digest fails validation. Reportcanonical_snapshot_projection_invalidat the existing TypeScript collection boundary, retaining the original cause and the rejection without partial records or a legacy fallback. Malformed request arguments retain their existing classification.The bilingual kernel RFC checkpoint records the diagnostic boundary and the remaining installed-runtime qualification. Older readers still reject unsupported newer field manifests.
Validation:
Scope review retained the existing typed validator, snapshot error carrier and provider interfaces; no new helper or parallel decision owner is needed.