`MetadataProtocol.listCommits` 把 commit store 读不到答成 `[]` —— ADR-0067 时间线上「无历史」与「读不到」不可分辨(零日志,JSDoc 里写着这是设计)

[hotlong]

发现于 #5186(为「读接缝把故障答成空值」这一族新增闸门)实施期,由新规则在 packages/metadata-protocol 扫出;不在该单文件面内(#5186 是纯 scripts/ 闸门单,不改被扫包),故单独立卡并已作为 baseline 条目记录在 scripts/durability-read-invention.baseline.json。

现象

packages/metadata-protocol/src/protocol.ts 的 listCommits()(约 9720–9745 行,以 origin/main 为准):

/**
 * List the commit timeline for a package, newest-first (ADR-0067). Returns
 * [] if the commit store is unavailable.        ←← JSDoc 自己就这么写
 */
async listCommits(request): Promise< …[] > {
  try {
    const rows = (await this.engine.find('sys_metadata_commit', { where, … })) as any[];
    // … 映射 + 按 createdAt 倒序 …
    return mapped;
  } catch {
    return [];
  }
}

catch 里:没有任何日志、没有 rethrow、没有按错误类型区分。

为什么这是缺陷而不是设计

这是 ADR-0110 D3(miss 与 outage 是两个意义相反的事实,消费方不得把其中一个读成另一个)在 ADR-0067 提交时间线上的违反,与 #5108 在 DatabaseLoader 修的、#5532 在同一个文件的 getMetaItems 修的是同一形状:

• 存储读不到 → 调用方看到「这个 package 没有任何提交历史」;
• 「没有提交历史」与「有 12 次提交但库连不上」在返回值上完全一致;
• 一行日志都没有,整条链路上没有任何地方说过这次读失败了。

后果面朝向 revert:提交时间线是 revertCommit 的选择面。历史被答成空的那一刻,UI 上「无可回滚项」,而实际上有——一次故障期间的运维判断会因此做反。

同一个文件几千行之上已经有了正确形状的处方:rethrowUnlessMetadataStoreUnprovisioned()(#5532 引入),它问 isMissingTableError,良性放行、其余包成 503 上抛。listCommits 只是没走它。

修法

} catch (error) {
  this.rethrowUnlessMetadataStoreUnprovisioned(error);   // 良性(表未建)放行
  return [];                                            // 首启确实没有提交
}

isMissingTableError 与该 guard 在本文件里都已经在用,无新依赖。

验收

• sys_metadata_commit 未 provision(首启)→ 仍返回 [],不抛、不噪;
• 驱动报连接错误 / 超时 / 权限失败 → 上抛(503 信封),调用方能把 outage 与 miss 分开;
• 更新 JSDoc:删掉「Returns [] if the commit store is unavailable」这句(它现在描述的是缺陷);
• 修好后删除 scripts/durability-read-invention.baseline.json 里的 packages/metadata-protocol/src/protocol.ts::listCommits 条目(shrink-only,条目失效即红)。

关联

#5186(新增本族闸门,本卡由它扫出)、#5532(同文件、同处方,getMetaItems)、#5108(同族,DatabaseLoader 五处读)、#5841(同文件另一处,退休手抄的 /no such table/i)、#4825 / #4728(同族)、ADR-0110 D3、ADR-0067、AGENTS.md「Absence must be loud」。

[claude]

分诊:pm:queue(可派发缺陷)+ 维持 domain:engine-core。

⚠️ 本单此前处于「半分诊」态:有 bug + domain:engine-core 但无任何 pm-state 标签,于是它既不在派发队列、也不在决策箱、也不在 finding 池 —— 对所有队列视图不可见。本轮补上状态标签,这是它今天才被扫到的原因(本轮扫描口径已从「无任何 domain:*」放宽到「无 pm-state」,见收尾简报)。

过时前提检查(origin/main 9e3709a)—— 三处逐一实读,全部成立

• protocol.ts:9706 listCommits() 在;结尾 } catch { return []; } 原样(实读 :9743-9745 区段);
• JSDoc 的 "Returns [] if the commit store is unavailable" 仍在(:9702-9704,跨行折行 —— ⚠️ 首次单行 grep 零命中是读取端折行所致,已用整段 sed 反查证伪「扫描器坏了」,SKILL notes 6);
• 处方 rethrowUnlessMetadataStoreUnprovisioned 在同文件已有 12 处调用点 ⇒ 修法无新依赖,正文的「只是没走它」成立;
• baseline 条目 packages/metadata-protocol/src/protocol.ts::listCommits 仍在 scripts/durability-read-invention.baseline.json(:40),shrink-only ⇒ 修好即可摘,验收判据是机械的。

为什么入队而不是 finding:落点、修法、验收三项齐备且都不需要产品裁决 —— 落点是同文件同函数的一行 catch,处方是本文件既有的 rethrowUnlessMetadataStoreUnprovisioned(#5532 为 getMetaItems 引入的同一处方),验收有 baseline 条目做机械判据。这是 ADR-0110 D3 的 restore-invariant 形状(miss 与 outage 不可混读),不是观察类。

域锚定:落点 packages/metadata-protocol/src/protocol.ts ⇒ 域表 packages/metadata* 那一行 ⇒ domain:engine-core。⛔ 不因为标题里的 "ADR-0067 / commit" 字样归 spec —— ADR 是判据来源,不是落点。

串行约束(派发时必读):在飞 PR #6051(draft,getDiagnosed)实读触 packages/metadata-protocol/src/protocol.ts 与 packages/objectql/src/plugin.ts ⇒ 本单排其后,⛔ 不同轮派发。

查重:三仓 open issue / PR 各搜一遍(listCommits / commit 时间线 / miss-vs-outage)—— 同族 #5532 / #5108 / #4825 均已收官,#5841 是同文件另一处(退休手抄的 /no such table/i),入口不同不重复;objectui / cloud 无影子单。本单是该处唯一派发入口。

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[baozhoutao]

认领(执行席 PM,engine-core 车道,第 9 轮)

• 会话:session_019Q7oc7ASjh8yxyS3Yz78We
• 分支:claude/issue-5980-listcommits-outage
• 工作树:../objectstack-issue-5980(worktree-first)
• 文件面:packages/metadata-protocol/src/protocol.ts(仅 listCommits 的 catch + 其 JSDoc)+ 相邻测试扩展 + scripts/durability-read-invention.baseline.json 摘条目

分诊串行约束已解除:PR #6051(同文件)已于 01:49Z MERGED,开工即以 origin/main 为基。⚠️ 同文件今日已两次大改(#5998、#6051),前提行号全部按内容重定位。

---

Generated by Claude Code