fix(metadata): 降级的 list() 结果按「降级」缓存 —— degraded 标记 + 2s 短 TTL (#5184)

[os-zhuang]

Fixes #5184

按 PM 裁定(11:00Z 分诊评论)取方向 1:降级结果照存,但条目带 degraded 标记 + 单独的短 TTL;同时把 listCache 字段注释改成代码真实做的事(现象二随手闭环)。

裁定内置的前提核实:knex/SQLite 单连接死锁今天仍然可达

裁定要求先确认注释里那个死锁场景在当前驱动栈下是否还走得到 —— 若已不可达,方向 3(只缓存完整读)才是更简单的正解。核实结论:仍然可达,因此维持方向 1。证据(全部读自合并后的 origin/main):

证据	位置	说明
DatabaseLoader 的读不串调用方事务	packages/metadata/src/loaders/database-loader.ts _find()	直接 this.engine.find(table, query),没有把 ctx.transaction 透下去 —— 正是注释描述的「事务持锁时再去要一条新连接」
driver-sql 仍把 SQLite 当单连接池	packages/plugins/driver-sql/src/sql-driver.ts activeTransactions 字段注释、assertBareKnexSafe()	「the pool holds a single connection … any bare this.knex query would dead-lock acquiring a second one」
该守卫在生产是 no-op	同上,assertBareKnexSafe 开头 if (this.isProductionEnv()) return;	所以生产环境不会快速失败,而是老老实实等满 acquireConnectionTimeout(60s)
同一危害在别处仍被手工规避	packages/plugins/plugin-audit/src/audit-writers.ts captureBefore	注释明写:不走 api.sudo() 而手动把 trx 串下去,否则「will deadlock for the full acquireConnectionTimeout (~60s)」

也就是说「降级结果干脆不入缓存」会把一个 30s 的静默窗口换成每次调用一个 60s 的挂起,明显更糟。这一核实在合入 origin/main(含 #5212 对 sql-driver.ts 的改动)之后又复核了一遍,结论不变。

改了什么

现象一 —— 降级结果不再和完整读长得一模一样:

• listCache 的条目类型从匿名的 { ts, items } 提为文件内(不导出)的 ListCacheEntry,新增 degraded: boolean;list() 在 loader 循环里记录这次读有没有丢 loader,cacheListResult() 的 degraded 参数是必填的 —— 它正是这个缓存以前唯一丢掉的信息。
• 降级条目按 DEGRADED_LIST_CACHE_TTL_MS(2s)过期,完整读仍是 LIST_CACHE_TTL_MS(30s)。取 1–2s 区间的上沿是有理由的:留着降级缓存的唯一目的就是吸收「一个打开的事务里连发的那串 list()」,那串调用彼此只差毫秒但可能被逐行工作拉开,2s 覆盖得住,同时仍比健康 TTL 短 15 倍。
• 新增 readCachedList() 作为唯一的读缓存入口:TTL 分支只在这一处,返回整个条目(而不是只返回 items),所以「这份是残缺的」对任何后续消费方都是可读的 —— 包括 DatabaseLoader 把存储读故障吞成空结果 —— ADR-0110 D3 的 miss/outage 之分在复数读路径上不成立 #5108 那条 once-only 报告的判断依据。裁定要求的「flag 在被消费处可读、但不加公开 API」就是这样落的。
• 效果对齐 issue 的复现:存储恢复后最迟 ~2s 就会有人再去问 loader,DatabaseLoader 把存储读故障吞成空结果 —— ADR-0110 D3 的 miss/outage 之分在复数读路径上不成立 #5108 的 reportLoaderReadRecovered 恢复日志跟着在秒级出现,而不是最晚 30s。

现象二 —— 注释即契约:

• 原注释声称缓存「only cache positive (non-empty) hits or repeated hits with a stable miss signature」。代码里从来没有这个条件。这是一处对着我们自己内部文档的 declared ≠ enforced,现在整段替换成 cacheListResult() / readCachedList() 真实做的事,并附上上面那份前提核实,免得下一个人再把「不缓存降级读」当成显而易见的修法。
• 顺带把 reportLoaderReadFailure() 的文案改对:它原本承诺「30s 后重试」,现在报的是降级 TTL。这是裁定允许的「fast-expiry 交互所必需的调整」,fix(metadata): DatabaseLoader 的读故障不再被吞成「什么都没声明」 (#5108) #5183 落地的降级缝本身没有回改。

测试

新增 packages/metadata/src/metadata-manager-degraded-list-cache.test.ts(8 例),issue 的复现被逐字做成回归用例:

• 降级读的条目 degraded === true、且仍然入缓存(降级窗口内第二次 list() 不碰 loader —— 吸收效果保住了);
• heal() 之后越过降级 TTL,loader 被重新问到、返回的是恢复后的集合(修复前这里会继续吐那份残缺结果);
• 恢复日志在 heal 后的秒级出现,且 error 仍然只有一行(更快的重试没有变成日志刷屏);
• 完整读的 30s TTL 原样不动(2s/6s/29.999s 都命中缓存,30.001s 才重读);
• 空的完整读照样入缓存 —— 这一条专门钉住替换后的注释所声称的行为(即原注释那个 "non-empty" 条件确实不存在)。

把 readCachedList() 改回「一律用 30s + 永远 degraded: false」(模拟修复前行为)重跑,8 例中 4 例失败 —— 回归覆盖是真的,不是自证。

范围

只动了认领时声明的文件面:packages/metadata/src/metadata-manager.ts、本包新增测试、一个 changeset。packages/spec/** 零改动;content/docs/releases/** 未碰;#5183/#5219/#5229 今日落地的面(loader 降级缝、invalidateForForeignWrite、集群订阅、NodeMetadataManager.handleFileEvent)未回改;IMetadataService 与公开导出未变(ListCacheEntry 刻意不导出)。

🤖 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:27pm

[github-actions]

📓 Docs Drift Check

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

7 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)
• content/docs/kernel/cluster.mdx (via packages/metadata)
• content/docs/kernel/services-checklist.mdx (via @objectstack/metadata)
• content/docs/plugins/packages.mdx (via @objectstack/metadata)
• content/docs/protocol/kernel/metadata-service.mdx (via @objectstack/metadata)
• content/docs/releases/v12.mdx (via @objectstack/metadata)
• content/docs/releases/v9.mdx (via @objectstack/metadata)

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.

[os-zhuang]

范围外发现,已按 Prime Directive #10 单独立卡、未认领:

• MetadataManager.list() 没有 in-flight 去重:冷缓存下 N 个并发调用各自完整走一遍 loader,listCache 承诺的「每个 TTL 窗口只打一次 loader」只对串行调用者成立 #5253 —— MetadataManager.list() 没有 in-flight 去重:缓存只在读完成后才写,所以在第一次读返回之前发出的并发 list(type) 全部 miss、各自完整走一遍 loader。listCache 注释承诺的「the loader is only hit once per TTL window」因此只对串行调用者成立。日常影响温和(健康路径下单次读很便宜,只是浪费),但在注释描述的那个 knex 60s 场景里会被放大成「每个并发请求各烧一次 60s」。

本 PR 不修它(越界),只做了一件属于本 PR 自己责任的事:既然这次把那段注释重写成了契约,就不能让它带着一句新的过度承诺 —— 第二个 commit 把那句话限定为「for SEQUENTIAL callers」并指向 #5253。

两者共用 list() 同一段代码,#5253 建议排在本 PR 之后,别并行。

搜索过重复:listCache / in-flight / single-flight / DatabaseLoader transaction knex deadlock 关键词下的 open issue 只命中 #5184 自身与无关的 #5228,无同题卡。

---

Generated by Claude Code

[os-zhuang]

一处未能推上来的收尾,记在这里以免丢失。

新增测试里有一个 describe 标题带了中文:

describe('#5184 — 现象二: the comment now describes the code', () => {

仓库里没有任何测试标题含 CJK(全量 grep 过),AGENTS.md 也说仓库产物(标识符、测试标题这类)沿用现有英文惯例 —— 所以这是我引入的一处不一致。我已经在本地把它改成:

describe('#5184 — the comment now describes the code', () => {

改完重跑 8 例仍全绿。但推送时被拒:

remote: - A pull request for this branch has been added to a merge queue. Branches that
remote:   are queued for merging cannot be updated.

本 PR 已被(非我)标记 ready 并加入合并队列,分支处于锁定状态。为一个纯文案的 describe 标题去 dequeue 一个已排队、CI 全绿的 PR,风险明显大于收益,所以我不动队列,本地那个 commit 就不推了。

影响:零功能影响,纯标题措辞。留给之后任何一次触碰该文件时顺手带上即可 —— 不值得单独立卡。

本 PR head 47a6bb829 的 CI 已全绿:ESLint / TypeScript Type Check / Build Core / Test Core (3/3) / Dogfood Regression Gate (3/3) / Dogfood Verify CLI / Temporal Conformance (live PG + MySQL) / Check Changeset 均 success。

---

Generated by Claude Code