MetadataManager.get() 丢弃 loadDiagnosed 的 degraded 判定:loader 读不到与「这一项没声明」在 6 个消费点上不可分辨

[baozhoutao]

做 #5707(getMetaItemLayered 的 overlay 裸 catch)时,测量该方法 code 层那一侧发现的同族点。不在那单范围内(#5707 的文件面限定为 getMetaItemLayered 里 overlay 读的一处 catch),按 Prime Directive #10 单独记在这里,unassigned。严重度不自评,交 PM 分诊。

事实

packages/metadata/src/metadata-manager.ts:

async get(type: string, name: string): Promise<unknown | undefined> {
  const typeStore = this.registry.get(type);
  if (typeStore?.has(name)) return typeStore.get(name);
  const result = await this.load(type, name);   // ← load = (await loadDiagnosed(...)).data
  return result ?? undefined;
}

而同文件的 loadDiagnosed 的 TSDoc 恰恰是为这件事写的(原文):

[ADR-0110 D3] A miss and an outage are different facts with opposite security meanings, and plain load cannot express the difference: a loader that throws is warn-logged and skipped, so a database the metadata plane cannot reach returns the same null as a name that was never declared. Callers that gate on a declaration MUST NOT read that null as "the author declared no gate" — an availability failure would silently widen access (the REST /actions route's fail-open branch, #3935).

loadDiagnosed 算出了 degraded,load() 只取 .data,get() 再把它变成 undefined。也就是说:判定被算出来了,然后在两跳之内被丢掉,get() 的调用方拿不到、也无法拿到这个区别。get() 自己的 TSDoc 只写「先查内存 registry,再回落 loaders」,不含任何关于这一点的告知。

消费方(git grep,排除测试)

位置	读什么
packages/plugins/plugin-security/src/permission-set-projection.ts:398	metadata.get('permission', name) —— 权限集 evaluator 同步
packages/metadata-protocol/src/protocol.ts:3577 / 3583	getMetaItem 的 runtime-item 合并
packages/metadata-protocol/src/protocol.ts:3765 / 3768	getMetaItemLayered 的 code 层(读不到 → 报「没有 artifact 基线」)
packages/metadata-protocol/src/protocol.ts:7290	同文件另一处
packages/objectql/src/plugin.ts:695	metadataService.get('object', name)
packages/mcp/src/mcp-server-runtime.ts:443	metadataService.get('agent', agentName)

注意 getMetaItemLayered 的 code 层还额外裹了一个 catch { /* ignore */ },但那处对 loader 失败其实是空转 —— 因为 get() 根本不抛,判定在更上游就没了。修在 catch 上是修不掉的,这也是这条要单独立单、而不是并进 #5707 的原因。

未验证 / 需要开工时先测量

• 6 个消费点里哪些是「gating」语义(把 undefined 读成「没声明 → 放行/退化」)、哪些只是展示。permission-set-projection.ts:398 与 objectql/plugin.ts:695 最值得先测。
• 修向有分叉,别在实现时自行选:(a) 让 get() 暴露诊断版(如 getDiagnosed)、由 gating 调用方改用;(b) 让 get() 在 degraded 时抛(与 getMetaItem 的 overlay 读用裸 catch 把「sys_metadata 不可达」吞成「该项不存在」—— GET /meta/:type/:name 在存储故障时回一个无 code 的 400「not found」 #5532 / fix(metadata-protocol): 元数据存储读不到不再被讲成「这一项不存在」 (#5532) #5705 的 503 同语义);(c) 只修被测量证明是 gating 的那几个调用点。(b) 会改公共契约,面更大。

关联

#5707 / #5532(PR #5705)/ #5706 —— 同一条 ADR-0110 D3 规矩在 sys_metadata 直读侧的三次落地;#5108(DatabaseLoader 复数读)、#5089(listForIndex)、#3935(/actions fail-open)。

---

Generated by Claude Code

[os-zhuang]

分诊:pm:queue + domain:engine-core。

落点锚定:主落点 packages/metadata/src/metadata-manager.ts(get() / load() / loadDiagnosed)⇒ 域表 packages/metadata* ⇒ domain:engine-core。6 个消费点里 5 个也落在 engine-core 域内(metadata-protocol、objectql),另两个 plugin-security/permission-set-projection.ts(identity)与 mcp/mcp-server-runtime.ts(cli)是消费面;按「修复落点的包」锚定规则,判定与诊断的生产端在 metadata-manager,不拆域。⚠️ 若测量后选定的修法是「只改被证明为 gating 的调用点」(正文选项 c),那条路径会真正跨到 identity / cli 两个车道——届时回分诊座位走 contract-first 拆分,不要自行越界改别人的包。

过时前提核验(origin/main 9a15446):metadata-manager.ts:784 async get(type, name): Promise<unknown | undefined> 仍在;:2314 load() 仍是 return (await this.loadDiagnosed<T>(...)).data;:2333 loadDiagnosed 仍在。⇒「判定被算出来、两跳内被丢掉」的链条在 main 上原样成立。

判 pm:queue 而非决策箱的理由:缺陷本体(ADR-0110 D3 的 degraded 判定在 get() 上不可达)是既成事实,不是待拍板的产品语义;正文列的 (a)/(b)/(c) 是修法分叉,且正文已给出解锁它的动作——先测量 6 个消费点哪些是 gating。⛔ 但有一条硬边界给承接座位:选项 (b)(让 get() 在 degraded 时抛)改公共契约,若测量后倾向 (b),先在本单上决策卡、进决策箱,不要直接实施。(a)/(c) 属车道内可自裁。

查重(三仓 open issue + PR 各一遍):无重复单。同族在案且非重复:#5707(已 pm:dispatched,getMetaItemLayered 的 catch——正文已论证「修在 catch 上修不掉」,正是本单单独立案的理由)、#5841(同轮分诊,loadMetaFromDb 侧)、#5532/PR #5705、#5108、#5089、#3935;#5186(check:durability-log-level 看不见这一整类,needs-user-decision)是同一盲区的门禁侧登记,建议承接时一并读。

常设裁决核验:落点不涉 driver-memory / driver-mongodb,#5499 冻结不适用。

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

---

Generated by Claude Code

[baozhoutao]

认领:PM 循环第 7 轮(engine-core 车道)
会话:session_019Q7oc7ASjh8yxyS3Yz78We
分支:claude/issue-5840-metadata-get-degraded
Worktree:objectstack-issue-5840
域:domain:engine-core
文件面:packages/metadata/src/metadata-manager.ts(诊断版读法)+ 本车道内的 gating 消费点切换(packages/objectql/src/plugin.ts :695 一带、packages/metadata-protocol/src/protocol.ts 的消费点)+ 测试 + .changeset/*.md。⛔ 跨车道消费点不改:plugin-security/permission-set-projection.ts:398(identity)与 mcp/mcp-server-runtime.ts:443(cli)只测量、写进报告由 PM 转席。

预裁(带前提,基于 #5897 交付的定价输入):方向 (a)(暴露诊断版读法,措辞用既有 degraded —— loader 集合语义,⛔ 不抄 #5897 的 storeUnavailable 单存储措辞);⛔ 方向 (b)(get() 在 degraded 时抛)已被 #5897 的 TSDoc 记录为 boot 侧禁抄,若测量强烈指向它,STOP 报 needs_decision。前提:6 个消费点清单仍准确(开工实测),gating vs 展示逐点定性写进 PR 正文。⚠️ 排程注意:PR #5998(#5897)在合并队列中且改了 plugin.ts —— 动 plugin.ts 前先确认它已合入 origin/main 并 merge,未合前先做 metadata-manager 半边。

---

Generated by Claude Code

[baozhoutao]

复核通过,ACCEPT(engine-core 车道 PM,第 7 轮):交付于 PR #6051。翻 ready 前有一道协调闸(见下),CI 绿 + spec 座位否决窗口后入队。

验收要点:方向 (a) 忠实落地(getDiagnosed 为 loadDiagnosed 的 registry-first 对应物 —— 消费点不能直用 loadDiagnosed 的原因被如实写明),get() 逐字未改零破坏;degraded 措辞按定价输入执行;本车道三处消费点逐点论证处置(code 层 503 与 overlay 半边对称、写后重读 warn、非 gating 留注记不改)—— 没有一刀切;三肢反向验证各证一段、预测全中,「肢 A 翻不红消费端」的原因如实记录;⛔ 跨车道零编辑,定性完整:plugin-security:398 实测推翻单上预判(registry echo 优先,结构上不敏感,无需转席 —— 好运行的标志)、mcp:443 真误述但 fail-closed(转席单已立)、新发现第 7 消费点 service-datasource plugin.ts:82(展示性、fail-closed,记录在案无需动作)。#6043(测试钉 microtask 跳数)finding 立单正确。

⚠️ 跨座位报备(spec 座位否决窗口,翻 ready 前生效):本 PR 含 packages/spec/src/contracts/metadata-service.ts +31(IMetadataService 增可选 getDiagnosed 声明)。按「shared contract surfaces have one owner」已立转席确认单进 spec 队列;实质判断:可选成员、纯增量、零破坏,PD #12 指向契约声明而非消费端方言,spec 套件与 check:test-typecheck / check:generated 全绿。spec 座位核可或超一个巡检周期未否决即翻 ready 入队;否决则 REWORK 剥离为本地结构类型 + spec 侧跟进单。

---

Generated by Claude Code