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