fix(metadata-protocol): seed-loader pass 2 目标解析成功但源记录无 id 时,回填不再被静默丢弃 (#5127)

[os-zhuang]

Fixes #5127

问题

packages/metadata-protocol/src/seed-loader.ts 的 resolveDeferredUpdates() 里,if (recordId) 没有 else。pass 2 已经把目标解析成功了(resolvedValue 是一个真实内部 id),却在 insertedRecords 里找不到源记录的内部 id,于是整条 deferred 回填直接从函数里掉出去:

• 不写库 —— 引用永久保持 NULL;
• 不进 errors / allErrors —— success 仍然是 true;
• 不动 errored;
• 一行日志都没有。

唯一残留的痕迹是 pass 1 记下、再也没还回来的那一笔 referencesDeferred(只有成功回填才会 resultEntry.referencesDeferred--)—— 结果对象里挂着一个悬空数字,却没有任何一条错误解释它。

这是左右两个兄弟分支的更深一格:#4729 修的是「有计数、日志停在 warn」,#4997 修的是「有计数、完全没日志」,这一处是「没计数、也没日志」。

改动

命中同一条客观判据(该结局是否进入 errors/allErrors?)—— 进入,所以按 AGENTS.md「Degradation log levels」(#4632)记账 + 打一条 error,写明后果与修法:

1. 补上 else 分支,走 recordDeferredError(→ errors/allErrors + errored,load 报 success: false);
2. referencesDeferred 保持原语义 —— 「已 defer 且始终没落地的引用数」,只由成功回填递减,与另外两个失败分支的处理完全一致。变的不是算术,而是那笔悬空计数从此一定配得上一条 errors 记录;
3. 两种触发情形分开措辞,因为它们不是同一个故障:
   • recordExternalId 为空串 = 纯静默丢失。externalIdKey 在键字段为空、或组合键任一分量为空时返回 '',行本身写得好好的躺在库里,全局没有第二处会吭声 —— 这行日志是读者唯一能拿到的信号,所以它必须点名是哪个键空了(为此在 file-local 的 DeferredUpdate 上加了 externalIdLabel,值形如 name+region);
   • 非空键但不在 map 里 = 源记录压根没落地,而那次写失败pass-1 写入点已经按 [metadata-protocol] seed-loader 的「LOUD FAILURE」注释要求 error,代码却记 warn —— 第二类降级(#4632 规则),本轮因包冻结未修 #4729 用 error 报过了,所以这行指向那条错误而不是复述它 —— 一行,不是对同一根因的二次淹没。同时它不会谎称「引用停在 NULL」:那行根本不存在,没有 NULL 可停。

protocol.ts、packages/spec/** 零改动;DeferredUpdate 是本文件私有(未导出)接口,新增字段不构成公开契约变更;计数器、结果对象形状、既有 result.errors 文案均未改。

测试

新增 packages/metadata-protocol/src/seed-loader-deferred-dropped.test.ts(6 例):

• 纯静默丢失(判据 3c 必须覆盖项):组合键 ['name','region'] 且 region 为空 —— 行成功写入库、inserted: 1,head_id 仍为 null;errored: 1、success: false、恰好一条 error 日志(且是本次 load 唯一一条),含 name+region、EMPTY key、stays NULL、修法与 recordExternalId: '' 的 meta;
• 计数自洽(判据 2):referencesDeferred === 1 且 errors.length === 1;并对所有结果条目断言「计数大于 0 则必须有错误解释」;
• 对照组(判据 3b):同一组合键、region 填值 —— 正常回填、success: true、totalReferencesDeferred: 0、logger.error/warn 均未被调用。这证明触发点是空键而非组合键本身;
• 源记录 pass 1 写失败(判据 3c 另一半):两处损失都被报告(行 + 关联),dropped 回填只多打一条日志并指向 pass-1 那条错误,CHECK constraint failed 那条 [metadata-protocol] seed-loader 的「LOUD FAILURE」注释要求 error,代码却记 warn —— 第二类降级(#4632 规则),本轮因包冻结未修 #4729 日志原样保留;另有一例专门钉住它不会说 stays NULL / EMPTY key。

回归有效性已反向验证:把 seed-loader.ts 还原成 origin/main 后,6 例中 5 例失败(唯一通过的正是对照组)。

pnpm --filter @objectstack/metadata-protocol test
  Test Files  40 passed (40)
       Tests  354 passed (354)

pnpm --filter @objectstack/metadata-protocol build          # tsup ESM/CJS/DTS 全绿
node scripts/check-durability-degradation-log-level.mjs     # 14 seam(s), all loud
pnpm exec eslint <改动的两个文件>                            # 0 problems
tsc --noEmit -p packages/metadata-protocol                  # seed-loader.ts 自身 0 error

下游消费方(本改动会让原本静默的路径开始报错)也跑过:@objectstack/objectql 的 3 个 seed/publish 用例(24 passed)、@objectstack/runtime 的 4 个 seed 用例(56 passed)。

兼容性

用户可见:命中该路径的 load 过去返回 success: true 且计数干净,现在返回 success: false 并把这次丢失计入 errored。种子数据一直是不完整的,只是过去不肯说。已附 .changeset/plenty-poems-brush.md(patch)。

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01Pbu27iNUfQCHeuS551Rqo7

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 4, 2026 12:40pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/metadata-protocol.

3 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/concepts/metadata-lifecycle.mdx (via @objectstack/metadata-protocol)
• content/docs/kernel/services-checklist.mdx (via @objectstack/metadata-protocol)
• content/docs/releases/v9.mdx (via @objectstack/metadata-protocol)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.