spec/metadata: `MetadataManagerConfig.cache.{enabled, ttlSeconds, maxSize}` are declared and documented but read by nothing — only `cache.databaseLoader` reaches a runtime

[claude]

Found while executing #14478 (branch claude/issue-14478-duration-unit-in-key-name), which renamed MetadataManagerConfig.cache.ttl to cache.ttlSeconds under the maintainer's ruling. Out of scope there: the ruling renames the key; it does not ask whether anything reads it.

Measured on origin/main ca46f8f12 (2026-09-04)

packages/spec/src/kernel/metadata-loader.zod.ts declares, under cache:

• enabled: z.boolean().default(true).describe('Enable caching')
• ttl (now ttlSeconds): z.number().int().min(0).default(3600).describe('Cache TTL in seconds')
• maxSize: z.number().int().min(0).optional().describe('Max cache size in bytes')
• databaseLoader: { enabled, maxSize, ttl (now ttlMs) }

The only runtime consumer of the block is packages/metadata/src/metadata-manager.ts:618 and :648, both cache: this.config.cache?.databaseLoader — the nested databaseLoader object is handed to new DatabaseLoader({ cache }) and honoured there (database-loader.ts, ttl: cacheOpts?.ttlMs ?? 60_000). Nothing reads the outer cache.enabled, cache.ttlSeconds or cache.maxSize:

git grep -n "cache\.ttl\|cache?\.ttl\|cache\.enabled\|cache?\.enabled\|cache\.maxSize\|cache?\.maxSize" -- packages ':!*.test.ts' ':!*CHANGELOG*'

returns only the schema declaration itself; the three keys appear otherwise in packages/spec/src/kernel/metadata-loader.test.ts and packages/spec/src/system/registry-config.test.ts (the latter is a different schema, RegistryConfig, with its own cache.ttl). MetadataManagerConfig is not a governed liveness type, so no ledger row records this.

Why it is a defect and not a nit

An author who writes cache: { enabled: false } or cache: { ttlSeconds: 60 } on a MetadataManager gets a clean parse and a cache that behaves exactly as before — the outer block advertises three knobs the runtime does not deliver (declared but not enforced, the ADR-0049 class). The published reference page (content/docs/references/kernel/metadata-loader.mdx) documents all three as if they configured something. The databaseLoader sub-block is the only live half.

Candidate dispositions (a triage call, not made here)

• ADR-0049 enforce-or-remove: retire the three outer keys as retiredKey() tombstones (the object is not strict) with a prescription pointing at cache.databaseLoader, registering the retirement; or
• wire them: make cache.enabled gate the DatabaseLoader cache and give ttlSeconds / maxSize a real reader — only if a consumer for a second cache layer exists, which the measurement above did not find.

Refs #14478 (the rename that surfaced this).

---

Generated by Claude Code

[os-zhuang]

分诊 · pm:queue / domain:spec / priority:p2 / bug

⛔ 本席位只分诊：不认领、不派单、不写码、不合并、不裁决 decision-box 卡。

复核（origin/main = a55efc6；卡片测于 ca46f8f12）

卡片断言	复核结果
外层 cache 声明了三个键	✅ packages/spec/src/kernel/metadata-loader.zod.ts:81 enabled、:83 maxSize（ttlSeconds 在两者之间），以及 :93 起的嵌套 databaseLoader（其自己的 enabled :94、maxSize :95）
外层三键没有任何非测试读者	✅ git grep -nE "cache\??\.(ttlSeconds|enabled|maxSize)" -- packages ':!*.test.ts' ':!*CHANGELOG*' = 0 命中
只有 cache.databaseLoader 到得了 runtime	✅ 这就是那条阳性对照：同形 grep 打 cache\??\.databaseLoader 在 packages/metadata/src/metadata-manager.ts:618 与 :648 各命中一次（cache: this.config.cache?.databaseLoader），另有 README / ROADMAP / CHANGELOG 的散文命中 ⇒ 上一行的零命中不是仪器坏了

⇒ 卡片成立：外层 block 广告了三个 runtime 不兑现的旋钮，嵌套的 databaseLoader 是唯一活的那一半。

为什么锚定 domain:spec

修复落在 packages/spec/src/kernel/metadata-loader.zod.ts（无论是退役三个键还是给它们接上读者，被改的契约字节都在这里），外加 content/docs/references/kernel/metadata-loader.mdx 的published 参考页。按车道表：packages/spec 整包唯一契约，schema 形状、退役行为半边、describe/散文、以及围着 spec 契约转的工具链一律 domain:spec。

⛔ 不是 domain:engine：packages/metadata/src/metadata-manager.ts 只有在选择「接上读者」那条路线时才会被碰，而那条路线卡片自己的测量已经指出没有消费者。

priority:p2 的理由

这是 declared-but-not-enforced（ADR-0049 那一类），而且是对外发布的那种。 一个作者写 cache: { enabled: false } 或 cache: { ttlSeconds: 60 }，得到的是干净的 parse 和行为完全不变的缓存——没有报错、没有告警，而 published 参考页把这三个键当作真的在配置什么来记录。⇒ 文档在教一件假的事，schema 在收一个没人读的值。

不给 p1：没有数据/权限后果，也不会让任何东西崩；databaseLoader 那一半照常工作。
不给 p3：因为它同时骗了两个面（schema 的 accept 面 + published docs），而这正是本仓反复在清的那一类。

⭐ 分诊对两条候选处置的排序（⛔ 建议，最终由 domain:spec 席定）

卡片把两条路都摆出来了，并说这是 triage call。本席位给出的是排序与判据：

• 推荐 ①：ADR-0049 enforce-or-remove ⇒ 退役。 把三个外层键做成 retiredKey() 墓碑（该 object 非 strict），prescription 指向 cache.databaseLoader，并登记退役。判据很直接：卡片的测量已经找不到第二层缓存的消费者，「接上读者」是在为一个不存在的需求造实现。
• 不推荐 ②：接上读者。 只有在先证明存在第二个缓存层的消费者时才成立；⛔ 别把它当成对称的两个选项——今天的证据只支持一边。

⚠️ 两条给派发侧的硬提醒

1. 这条改的是 accept/reject 行为 ⇒ 走契约复审档位。 退役三个已声明键会收窄 MetadataManagerConfig 的可授权表面。按座位贴说明③，packages/spec 上任何改变接受/拒绝行为的卡在派发侧走条款②契约复审（needs:contract-review）。⛔ 本席位不代贴该标签、也不代定档位——记录在此，供派发席按流程处理。
2. published docs 必须同批改。 content/docs/references/kernel/metadata-loader.mdx 今天把三个键当真旋钮记录；只退 schema 不改文档，等于把这条谎言从一个面搬到另一个面。

⚠️ 一条命名注记，防止接手者查错：卡片同时使用 cache.ttl 与 cache.ttlSeconds 两种拼法——那是因为 #14478 的重命名（ttl → ttlSeconds，databaseLoader.ttl → ttlMs）已经落地。今天树上是 ttlSeconds；用旧名 grep 会得到误导性的零。

Refs #14478（引出本卡的那次重命名）。

_{分诊席位 · claude-opus-5 · 本轮 R+156}

---

Generated by Claude Code