ComputedFieldCacheSchema 是 2026-06 字段剪除留下的第二个孤儿(#3726 表格误记为「已清理」)

[os-zhuang]

一句话说明

cached 字段键在 2026-06 的 dead-surface 剪除里被删掉了,但 ComputedFieldCacheSchema 及其类型仍留在 @objectstack/spec 的公开 API 面上,零消费者。形态与 #3726 的 DataQualityRules 完全一致。

在 #3726 上做剪除时发现(PR #3732),按 Prime Directive #10 单独跟踪 —— 没有在那个 PR 里顺手扩大公开 API 的移除范围。

更正 #3726 的核对表

#3726 列了张表核对 tombstone 里的五项,把 cached 记为「❌ 已清理」。实际没有:

剪除项	schema 是否仍导出	#3726 表格	实际
encryptionConfig	❌	不是残留(system 层另一个独立 schema)	一致
maskingRule	❌ 已清理	已清理	一致
auditTrail	❌ 已清理	已清理	一致
cached	✅ 残留	已清理	误记
dataQuality	✅ 残留	残留	一致(#3726 / #3732 已处置)

所以那批剪除留下的是两个孤儿,不是一个。

事实核实

tombstone 在 packages/spec/src/data/field.zod.ts,cached 在列:

// docs/audits/2026-06-dead-surface-disposition-plan.md (P0/P2 field prune):
// encryptionConfig, maskingRule, auditTrail, cached, dataQuality.

cached 作为 FieldSchema 的键确实没了(全文件仅剩注释里这一处)。disposition plan 也把 cached 列进了 P2 剪除清单。但 schema 本体和类型还活着,且在公开 API 快照里(packages/spec/api-surface.json:195-196):

"ComputedFieldCache (type)",
"ComputedFieldCacheSchema (const)",

定义在 field.zod.ts(含一段 @example)+ 类型导出一行,并发布了 data/ComputedFieldCache.json(json-schema.manifest.json:674),以及生成的参考文档 content/docs/references/data/field.mdx 里的 ## ComputedFieldCache 一节。

全仓消费者:零。剔除 node_modules / dist 后的全部引用:

packages/spec/src/data/field.zod.ts   (定义 + 类型导出)
packages/spec/api-surface.json        (生成物)
packages/spec/json-schema.manifest.json (生成物)
content/docs/references/data/field.mdx  (生成物)

为什么值得修

与 #3726 同理,不重复展开。一点补充:FieldSchema 不是 .strict()(#3726 的第 1 条理由在这里写错了,已在 #3732 更正),所以作者按参考文档写 cached: { enabled: true, ttl: 3600 } 不会报错 —— 解析成功,键被静默丢弃。对缓存配置来说这个失败模式格外难察觉:作者会以为公式字段结果被缓存了 1 小时,实际什么都没发生,而且没有任何信号。这正是 field.zod.ts 里 accept / maxSize 注释点名的 ADR-0104 失败类。

建议处置

与 #3726 相同的两条路,二选一:

1. 删除(与其余四项一致):移除 ComputedFieldCacheSchema + ComputedFieldCache,跑 pnpm --filter @objectstack/spec gen:api-surface 更新快照,从 json-schema.manifest.json 删掉 data/ComputedFieldCache 键(json-schema ratchet gen:schema silently drops PageTabsProps since #2967 — references regen would delete real docs #2978 会拦下停发,这是它要求的 deliberate-retirement 步骤),配 changeset。公开面少 2 条。
2. enforce(ADR-0049 的另一侧):真做计算字段缓存 —— 接上消费者,并把 cached 键加回 FieldSchema。

当前这种「schema 公开、键不存在、无人消费」的中间态是三者里最差的一种。

参考实现:#3732 对 DataQualityRules 做的就是路线 1,步骤可以照搬。

关联

• DataQualityRulesSchema 是 2026-06 字段剪除留下的孤儿:字段键已删,schema + 类型仍公开导出 #3726 / refactor(spec)!: 补完 2026-06 字段剪除 — 删除两个孤儿 value schema (#3726, #3733) #3732(同批剪除的另一个孤儿;本 issue 更正了 DataQualityRulesSchema 是 2026-06 字段剪除留下的孤儿:字段键已删,schema + 类型仍公开导出 #3726 核对表里的 cached 一行)
• docs/audits/2026-06-dead-surface-disposition-plan.md(P0/P2 field prune)
• ADR-0049 enforce-or-remove
• gen:schema silently drops PageTabsProps since #2967 — references regen would delete real docs #2978(json-schema ratchet)

[os-zhuang]

按维护者要求,与 #3726 合并到 PR #3732 一起处置(路线 1,删除)。

已移除:ComputedFieldCacheSchema (const)、ComputedFieldCache (type),以及停发的 data/ComputedFieldCache.json。api-surface.json 少掉本 issue 预言的那 2 条(整个 PR 合计 4383 → 4381)。json-schema ratchet(#2978)如设计般拦下停发,manifest 键的移除是它要求的 deliberate-retirement 步骤。

本 issue 里推测的失败模式已实测确认:

FieldSchema.safeParse({ name: 'total', type: 'formula',
                        cached: { enabled: true, ttl: 3600 } })
→ parse success: true
→ cached key survived? false

解析成功、键被静默丢弃 —— 作者会以为公式结果缓存了一小时,没有报错,也永远看不到信号。

field.zod.ts 的 tombstone 已改写为同时覆盖两个孤儿,并写明五个键至此在两层都真的死了(与它一直以来的声明相符),以及若将来真做计算字段缓存,键与 schema 必须连同消费者一起加回(ADR-0049 enforce 侧)。changeset 也重写为覆盖两次移除。

验证:全仓 pnpm build 71/71、pnpm test 132/132,六项 spec drift check + check:liveness 全绿。

---

Generated by Claude Code