Skip to content

fix(coordination): distinguish invalid snapshots from invalid requests - #8545

Merged
cocolord merged 1 commit into
mainfrom
codex/canonical-snapshot-failure-classification-20261111
Nov 11, 2026
Merged

cocolord merged 1 commit into
mainfrom
codex/canonical-snapshot-failure-classification-20261111

Conversation

@cocolord

@cocolord cocolord commented Nov 11, 2026 •

Copy link
Copy Markdown
Collaborator

A valid canonical snapshot request currently reports canonical_snapshot_request_invalid when the persisted Todo field manifest or record digest fails validation. Report canonical_snapshot_projection_invalid at 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:

  • 63 TypeScript snapshot/coordination tests and 39 Python transport/RPC/CLI tests passed.
  • 392 PostgreSQL authority integration tests passed on an isolated disposable server, including the new rejected-manifest read.
  • TypeScript typecheck, focused Python lint, bilingual diff check and public-boundary scan passed.
  • The four File/SQLite regression cases fail on the base revision and pass with the fix; rejected reads preserve the authority head.
  • Repository standard premerge passed, including all direct checks and selected catalog/public-boundary checks.

Scope review retained the existing typed validator, snapshot error carrier and provider interfaces; no new helper or parallel decision owner is needed.

Signed-off-by: lusendong.6789 <lusendong.6789@bytedance.com>
Co-authored-by: TRAE CLI <traecli@bytedance.com>

@cocolord cocolord left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

关键代码讲解

  1. readCanonicalSnapshotFromStore 先解析请求并检查 continuation,再进入 canonicalTodoCollection。只有该调用抛出的 AuthorityStoreProtocolError 被映射为新原因;原始错误信息完整保留。其他异常继续走原有处理。
  2. 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.

@cocolord
cocolord merged commit beff0f3 into main Nov 11, 2026
11 of 14 checks passed
@cocolord
cocolord deleted the codex/canonical-snapshot-failure-classification-20261111 branch November 11, 2026 00:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant