loadMetaFromDb 的返回值无法表达「没读到存储」—— restoreMetadataFromDb 把 outage 记成 debug 级 "No persisted metadata found",boot 照常报告健康(ADR-0110 D3 的 boot 侧)

[baozhoutao]

来自 #5841 的事实 2(该单按范围裁定只交付事实 1,事实 2 测量后立单)。测量证据与修向分析见 PR #5889 报告,此处摘录并附 PM 裁决。未指派;标签交分诊。

事实(#5841 的 dev 实测,origin/main)

loadMetaFromDb 的返回值 { loaded, errors, invalid } 没有任何字段能表达「这次水合根本没读到存储」。其返回值的唯一生产消费方是 packages/objectql/src/plugin.ts:1140 的 restoreMetadataFromDb,且没有任何调用方对 loaded: 0 做分支处置 —— 唯一分支是选哪条日志:读不到存储的 boot 在 kernel 日志里被写成 debug 级的 "No persisted metadata found in database"。

下游后果(plugin.ts Phase 2 自己的注释已写明):registry.getObject 返回空 → unknown-$select guard / hooks / relationships silently degrade;没读到的 overlay 对象既不建表也不桥接,kernel 照常 ready。自托管运维在 boot 期只有日志一个信号,而这个信号是 debug 级的「库是空的」。

修向(dev 的四案分析,原文见 #5841 报告)

• A(dev 推荐):返回值加诊断位(如 storeUnavailable / degraded),restoreMetadataFromDb 读它并按 AGENTS「Degradation log levels」升到 error。改返回契约 + objectql/src/plugin.ts:23 的 ProtocolWithDbRestore 接口声明与消费分支;面小、不改控制流;与 MetadataManager.get() 丢弃 loadDiagnosed 的 degraded 判定:loader 读不到与「这一项没声明」在 6 个消费点上不可分辨 #5840 的方向 (a)(诊断版读法)同形,可共用。
• B:非良性时抛出(getMetaItem 的 overlay 读用裸 catch 把「sys_metadata 不可达」吞成「该项不存在」—— GET /meta/:type/:name 在存储故障时回一个无 code 的 400「not found」 #5532/fix(metadata-protocol): 元数据存储读不到不再被讲成「这一项不存在」 (#5532) #5705 的 503 同语义)—— 语义最纯,但把「可降级继续」的 boot 升级成失败路径,且 restoreMetadataFromDb 现有 catch 会重新吞掉,不同步改消费方等于没改。
• C:只把消费方 loaded===0 分支从 debug 升 warn —— 空库与 outage 仍不可分,把两个相反事实继续用同一个名字叫,workaround。
• D:不修。

PM 裁决(第三档:带前提,否决窗口开放)

裁 A,前提两条(实施 dev 开工先核,任一不成立即报 fork、⛔ 不许静默改道):

1. loadMetaFromDb 返回值的消费方仍然只有 restoreMetadataFromDb 一个(loadMetaFromDb 用 /no such table/i 正则判「良性首启」,其余 sys_metadata 读失败吞成 console.warn + loaded:0 —— isMissingTableError 的手抄第二份 #5841 测量时如此);
2. ProtocolWithDbRestore 是 objectql 内部接口声明,不在 packages/spec 公开契约面上(若实测它已进 spec,转 domain:spec 座位)。

依据:ADR-0110 D3(outage ≠ miss)已是本仓在 DatabaseLoader(#5108)、listForIndex(#5089)、协议 overlay 读(#5532/#5705/#5843)的既定方向,A 是同一条规矩的 boot 侧落地 —— 属 restore-invariant,不占维护者决策位;B 过重(boot 应 degrade loudly 而非 die),C 属 workaround(两个相反事实一个名字),D 违背 D3。

协调

• MetadataManager.get() 丢弃 loadDiagnosed 的 degraded 判定:loader 读不到与「这一项没声明」在 6 个消费点上不可分辨 #5840(MetadataManager.get() 丢 degraded 判定,已排队):同族相邻,A 的诊断位形状可与其方向 (a) 共用;两单派发时注意 plugin.ts / metadata-manager.ts 文件面切分,先派者在报告里回答对后派者的必答项。⚠️ MetadataManager.get() 丢弃 loadDiagnosed 的 degraded 判定:loader 读不到与「这一项没声明」在 6 个消费点上不可分辨 #5840 若选 (b)(degraded 时抛),boot 侧不宜照抄(会让首启之外的任何读失败起不来)—— loadMetaFromDb 用 /no such table/i 正则判「良性首启」,其余 sys_metadata 读失败吞成 console.warn + loaded:0 —— isMissingTableError 的手抄第二份 #5841 的 dev 已预警。
• loadMetaFromDb 用 /no such table/i 正则判「良性首启」,其余 sys_metadata 读失败吞成 console.warn + loaded:0 —— isMissingTableError 的手抄第二份 #5841(事实 1,PR fix(metadata-protocol): loadMetaFromDb 判「表未建」改问 isMissingTableError,退休手抄的 /no such table/i (#5841) #5889)只换良性判定谓词,与本单无文件级依赖。

Refs #5841 / PR #5889、#5840、ADR-0110 D3、#5108、#5089、#5532。

[claude]

分诊:入队 pm:queue,域 domain:engine-core。

落点锚定:packages/objectql/src/plugin.ts(loadMetaFromDb 的返回契约、restoreMetadataFromDb:1140 的唯一消费分支、:23 的 ProtocolWithDbRestore 接口声明)⇒ packages/objectql 属 domain:engine-core。

单上裁决前提 2 的分诊侧核实(可省 dev 一次往返):git grep -l ProtocolWithDbRestore origin/main -- packages 在 origin/main @ 7adc841 上只命中 packages/objectql/src/plugin.ts 一个文件,packages/spec/** 零命中 ⇒ 该接口未进公开契约面,前提 2 成立,不转 domain:spec 座位。前提 1(返回值消费方只有 restoreMetadataFromDb)仍按裁决要求由实施 dev 开工时复核。

分类理由:pm:queue —— 单上已有 PM 第三档裁决(裁 A,带两条前提与否决窗口),依据是 ADR-0110 D3(outage ≠ miss)在本仓 DatabaseLoader(#5108)/ listForIndex(#5089)/ overlay 读(#5532/#5705/#5843)的既定方向,属 restore-invariant,按 step 0 自动入队,不占维护者决策位。

⚠️ 同族文件面切分:#5840(pm:queue / domain:engine-core,MetadataManager.get() 丢 degraded 判定)与本单是同一条 D3 规矩的两处落地,诊断位形状可共用。两单分别落 plugin.ts / metadata-manager.ts,请由 engine-core 车道确认切分后再决定是否同批;先派者的报告须回答对后派者的必答项(单上已记 #5840 若选 (b) 抛错则 boot 侧不宜照抄)。

查重:三仓搜 loadMetaFromDb / restoreMetadataFromDb / No persisted metadata,命中 #4636(同函数但另一轴:snake_case 行读 record.packageId,已带 needs-user-decision)与 #5840;三者互不重复,各有独立入口。

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

---

Generated by Claude Code

[baozhoutao]

认领:PM 循环第 6 轮(engine-core 车道;protocol.ts 已随 #5926 落地释放,同文件无在飞)
会话:session_019Q7oc7ASjh8yxyS3Yz78We
分支:claude/issue-5897-hydration-outage-diagnostic
Worktree:objectstack-issue-5897
域:domain:engine-core
文件面:packages/metadata-protocol/src/protocol.ts(loadMetaFromDb 返回形状加诊断位)+ packages/objectql/src/plugin.ts(ProtocolWithDbRestore 接口声明 + restoreMetadataFromDb 消费分支升 error)+ 两侧测试 + .changeset/*.md。⛔ 不碰 loadMetaFromDb 的 object 分支 packageId 登记(#4636 决策箱在途)、不碰 #5840 的 metadata-manager.ts。

按正文 PM 裁 A 执行,开工先核两条前提(任一不成立即报 fork):(1) 返回值消费方仍只有 restoreMetadataFromDb;(2) ProtocolWithDbRestore 不在 packages/spec 公开契约面上(若已进 spec,停手 —— 那要转 spec 座位,而该座位当前空缺,报告后由 PM 处置)。

---

Generated by Claude Code

[baozhoutao]

复核通过,ACCEPT(engine-core 车道 PM,第 6 轮):交付于 PR #5998,CI 23 项全绿(dev 读实 + PM 抽核文件面),转 ready 入合并队列。

验收要点:裁 A 两条前提均实测复核(消费方唯一、接口不在 spec);storeUnavailable 与 errors 的语义边界刻意分开并有 pin(「行没到」≠「行到了水合失败」)—— 命名取舍正确;optional 字段的破坏面取舍如实写进 changeset;双肢反向验证各证一半且诚实记录肢 A 翻不红消费端的原因(替身直喂契约),没有为凑模板制造假红;⛔ 三条硬边界(packageId 行 / metadata-manager.ts / 控制流)全部遵守。必答项质量高:#5840 变简单 —— 语义形状可复用但建议改用既有 degraded 措辞(loader 集合 vs 单一存储读),且 (b) 路线的 boot 侧禁抄理由已写进 plugin.ts TSDoc 常驻。#4636/#5079 无影响。

---

Generated by Claude Code