spec/system 通知模板语汇在 C3 后成为零消费方孤儿:EmailTemplate/SMSTemplate/PushNotification/InAppNotification(Schema) 待 enforce-or-remove 处置

[os-zhuang]

#4610(#4535 C3)删除 system/notification.zod.ts 的 NotificationConfigSchema 后发现的范围外遗留,按 Prime Directive #10 立案记录,不在 C3 PR 内处理。

现状

C3 前,EmailTemplateSchema / SMSTemplateSchema / PushNotificationSchema / InAppNotificationSchema 的唯一非测试消费方是同文件 NotificationConfigSchema.template 联合。该 wrapper 因双源清账死删(三仓 import 级扫描零消费方)后,这四个模板 schema 只剩:

• 自己的单测(system/notification.test.ts)
• ./system barrel 导出(继续出现在 api-surface / json-schema.manifest / authorable-surface)

三仓(framework / cloud / objectui)import 语句级扫描:四个名字均无任何外部 import 站点(plugin-email 用的是 email-template.zod.ts 的 EmailTemplateDefinition,是另一个声明,勿混淆)。

同文件的 NotificationChannel(Schema) 是活的(经 contracts/notification-service.ts re-export,service-messaging 消费),不在本案范围。另注意 ui/notification.zod.ts 的 NotificationSeveritySchema 同样无外部消费方(objectui 只 pin 了 Type/Position/Action 三个枚举),可一并处置。

待决

按 ADR-0049 enforce-or-remove 与 ADR-0030 的收敛方向处置:

1. 死删(倾向):ADR-0030 的模板层是 sys_notification_template(topic×channel×locale 元数据对象),不是这些 spec 常量;渠道级投递语汇属于 service-messaging 的对象模型。这些 schema 声明了 runtime 从不读取的能力(declared ≠ enforced)。
2. 保留并接线:若某渠道实现(email/sms)确要用 spec 级模板 shape 校验,应先有消费方 PR 再谈保留。

处置走 spec-property-retirement skill 的整套流程(api-surface、manifest、authorable-surface、reference docs、changeset)。

关联:#4610(触发本发现的 C3 PR)、#4535(双源主账本)、ADR-0030(通知平台收敛)、ADR-0049(enforce-or-remove)、#3197(渠道 dead-letter 现状)。

[os-zhuang]

维护者质询的实查结论:短信/邮件模板功能确实存在,但都不读这四个孤儿 schema

维护者问:cloud 开发过短信功能,没用到短信模板吗?现有邮件模板功能和这个没关系吗?实查(objectstack @ d52d4fe3b,cloud @ 5df2c69):

1. 短信功能不在 cloud,在本仓 —— cloud 11 个包全仓 sms 大小写不敏感检索零命中;真实实现是 packages/services/service-sms(Aliyun 等 transport)+ packages/services/service-messaging/src/sms-channel.ts。

2. 短信链路用模板,但模板源是 ADR-0030 的 sys_notification_template 对象,不是 SMSTemplateSchema:

• sms-channel.ts:39-110:按 (topic, 'sms', locale) 从 NotificationTemplateStore 加载 sys_notification_template 行,template-renderer.ts 渲染;
• transport 层另有 provider 模板概念(aliyun.ts:预注册 TemplateCode + templateParams,阿里云拒收自由文本)——这是供应商 API 形状,与 spec 常量无关;
• service-messaging 对 spec 的全部 import 仅 ObjectSchema/Field/IDataEngine/TranslationData,零个来自 system/notification.zod.ts。

3. 邮件模板功能同样是另一个声明:真实邮件模板 = email_template 元数据 kind → spec/system/email-template.zod.ts 的 EmailTemplateDefinitionSchema(plugin-email 消费,与立单正文所记一致)。与孤儿 EmailTemplateSchema(notification.zod.ts)同名不同物。

4. 附带发现一处误导性注释,建议随本单一并修:kernel/metadata-plugin.zod.ts:116 写着 'email_template', // Outbound email templates (EmailTemplateSchema) —— 括号里的名字指错了声明(应为 EmailTemplateDefinitionSchema),正是维护者这次质疑的混淆源头。

结论:维护者记忆中的功能都真实存在,但两条链路(sys_notification_template 对象 + EmailTemplateDefinition)恰好证实了立单前提——四个孤儿 schema 声明的能力 runtime 从不读取,与 RateLimitConfig(#4686)「真干活的是第三形状」同构。死删路线(待决项 1)经此质询后更稳固;实施时注意:NotificationChannel(Schema) 仍活(contracts 消费)不在范围,第 4 点的注释修正纳入。

---

Generated by Claude Code

[os-zhuang]

🔒 认领:PM 会话 session_0176qgxgCXTJCUv4YFLtusP9,分支 claude/issue-4616-notification-orphan-schemas。

ADR-0049 队列接派(前序 #4634 → PR #4783 已合并)。派发前快检(07:0xZ):相关 schema 仍在 main(api/protocol.zod.ts、contracts/notification-service.ts、kernel/events/bus.zod.ts),.changeset/pre.json 仍 mode: pre。

前置调查结论(2026-08-03,维护者质询后由 PM 核实,可直接采信但仍须自行复核):本单的移除判定与现有短信/邮件功能不冲突 —— 短信实现在本仓 service-sms / service-messaging(cloud 仓零 SMS 代码),短信模板来自 sys_notification_template 对象 + 阿里云 provider 的 TemplateCode;邮件模板走 email-template.zod.ts 的 EmailTemplateDefinitionSchema。三者都不经过本单要移除的孤儿 schema。kernel/metadata-plugin.zod.ts:116 那条误导性注释是混淆来源,顺手一并修正。

区域:api + contracts + kernel/events;与在飞 C7 #4789(kernel/plugin-security.zod.ts + cloud/)文件不相交,可并行实施,入队排其后。

---

Generated by Claude Code

[os-zhuang]

实施完成 → draft PR #4809(分支 claude/issue-4616-notification-orphan-schemas)

按待决项 1(死删) 处置。实施中复核出立单前提有两处与事实不符,两处都写进了 PR body,结论方向不变但依据换了:

1. EmailTemplateSchema 不是零消费方 —— 有一个,而且它本身是 bug

立单正文说四个名字「均无任何外部 import 站点」。这是按 import 语句扫描得出的;改用裸名扫描后,objectui packages/app-shell/src/views/metadata-admin/clientValidation.ts:89 命中:

email_template: async () => (await import('@objectstack/spec/system')).EmailTemplateSchema as unknown as ZodLikeSchema,

动态 import() + 属性访问,import 语句级扫描看不见 —— 正是 spec-property-retirement skill §1「build 才是裁判」防的形态。

但它不构成保留理由,反而是移除的加强论据:该 kind 的规范 schema 是 EmailTemplateDefinitionSchema,两者形状不相交(id vs name+locale;body+bodyType vs bodyHtml/bodyText),所以今天 Studio 里一份合法的 email_template 草稿会被报 id/body 缺失,真正的键因非 strict 被静默剥离。这与 spec 7.1.0 在框架侧修过的是同一个缺陷 —— 当时把 TYPE_TO_SCHEMA / BUILTIN_METADATA_TYPE_SCHEMAS 改指到 Definition,objectui 侧从未跟进。

按本单待决项 2 自己的判据(「应先有消费方 PR 再谈保留」),一个误接站点不是消费方。移除把静默错校验变成恰好落在那一行上的编译错误。已按 Prime Directive #10 单独立案 #4807(未指派),不在本 PR 内修。

2. ui NotificationSeveritySchema 是活的,「可一并处置」的建议被证伪 —— 本 PR 未动 ui/

立单正文说「objectui 只 pin 了 Type/Position/Action 三个枚举」。实查为假,objectui 有四处消费:packages/types/src/index.ts re-export 类型、core/src/protocols/NotificationProtocol.ts 消费、packages/types/src/__tests__/spec-ui-schema-reexports.test.ts pin 了 schema 名、components/src/notifications/severity.ts 与 app-shell/src/chrome/notificationToast.tsx 把 severity→tone 映射写成 Record< NotificationSeverityLevel, … >,注释明写「a new severity in the spec NotificationSeveritySchema fails type-check here」。

packages/spec/src/ui/ 一个字节未动。 为免下次审计照着本单正文再来一遍,pin 里加了断言:该名必须仍由 ./ui 独占持有(sabotage S3 实测会红)。

---

实际移除

./system 的 EmailTemplate(Schema) / SMSTemplate(Schema) / PushNotification(Schema) / InAppNotification(Schema)(4 const + 4 type)。NotificationChannel(Schema) 按立单要求保留(contracts re-export,service-messaging 消费)。

退役形态:#4650 路径 3(整 def 消失),不是 retiredKey() 墓碑

判据以门禁实跑为准:墓碑必须挂在存活的 schema 形状上,这里四个 def 整体消失,无形状可挂。gen:schema 自己给出裁定 def no longer emitted by this build; whole-schema removals are adjudicated by json-schema.manifest.json (#2978) and check:api-surface,故 authorable-surface.json 22 行 + json-schema.manifest.json 4 键在本 PR 内刻意删除(C10/C16 及本文件 #4610 谱系)。

ADR-0087 conversion:逐条评估后不需要

三种先例对照:#4734 需要(key 挂在 root-reachable schema、作者源真写着它);#4767 / #4783 不需要;本单不需要 —— 四个 def 从任何 metadata-type 根都不可达(computeSurfaceReachability BFS 证明,门禁据此放行),os migrate meta 无匹配目标;D3 semantic[] 是给响应面 key 用的,也不适用。#4610 在同一文件做同样的事同样未注册。破坏面纯粹是 TS 导出面。

changeset 定级 major(#4535 §5 逐条自证)

TS2305/TS2339?是(objectui 那行就是现存实例)· 元数据迁移?否 · 形状变更?否(NotificationChannelSchema 逐字节未变)。changeset 逐个给 FROM → TO,并明写 Definition 是形状变更而非改名。

顺带修正

kernel/metadata-plugin.zod.ts:116 的 (EmailTemplateSchema) → (EmailTemplateDefinitionSchema) —— 这条括号正是维护者质疑与 objectui 误接的共同源头。

pin 与 sabotage

TypeScript compiler API 符号身份解析:exports-map 枚举全 16 入口 + 防空转守卫 + holders 精确相等 [](而非「./system 不含它」)。4 组 sabotage 全部实跑转红:S1 复活被删名、S2 从 ./contracts 顶名 re-export(此时 runtime 那条仍绿,正好证明 compiler-API pin 才承重)、S3 退役被证伪的 NotificationSeverity、S4 空转检验。另把 #4610 留下的 typeof import 条件类型 pin 折叠进来 —— #4642 已确认它在本包空转。

验证

check:generated 8/8 · check:authorable-surface · check:api-surface(./system 精确 −8 行,零新增)· check:dual-source-exports · 源码审计组含 check:strictness-ledger 全绿 · spec test 293 files / 7359 tests · spec typecheck · 全仓 typecheck 122/122 · 全仓 build 71/71 · check:i18n 9 包 in sync · service-sms 28 / service-messaging 160 / plugin-email 76 全通过。content/docs/releases/ 未触碰。

已 git merge origin/main(未 rebase / 未 force-push),进来的 3 个提交不触碰 packages/spec,四张 ratchet 相对 main 的 delta 精确等于本 PR 的一处改动。入队排在 C7 #4789 之后;draft/ready 与合并归 PM。

---

Generated by Claude Code

[os-zhuang]

✅ 验收通过 → PR #4809 已转正 + auto-merge(入队排 #4789 之后,已满足)

对照 GitHub 实际 diff(d1086e64 vs main 459f925c)逐项复核,全部合格:

实质面(首轮已审,维持结论)

• 退役形态:authorable-surface 的 tombstone 门禁可被手编基线绕过 —— 删掉基线行就删掉了证据(#4638 / #4643 已两次这样过绿) #4650 路径 3(整 def 消失),gen:schema 对新 merge-base 重新自证 4 项删除;非 retiredKey() 墓碑判定正确(无存活形状可挂)。
• 两处立单前提证伪处置正确:EmailTemplateSchema 的误接消费方(动态 import,objectui)→ 立案 objectui: metadata-admin 用错的 schema 校验 email_template 草稿 —— 注册的是被降级的 EmailTemplateSchema,而非 EmailTemplateDefinitionSchema #4807 而非保留;ui NotificationSeveritySchema 实活 → ui/ 零触碰 + 反复议 pin(S3 实测红)。
• conversion 不登记的论证成立(D2 无源可改写、D3 非响应面,与 spec 双源清账 C3:通知语汇 Notification(Schema)(./api ≠ ./ui)+ NotificationConfig(Schema)(./system ≠ ./ui)—— 4 条,单 PR #4610 同文件同处置一致);changeset major 三问自证成立,EmailTemplateDefinitionSchema 明写形状变更非改名。
• pin 形态达标:compiler-API + 全入口枚举 + holders 精确相等,S2(从 ./contracts 顶名)时 runtime pin 保持绿 —— 正是 holders-equality 承重的实证。

本轮打回项(main 同步)复核合格

• 静默回退陷阱实证复现:携带 feat(spec)!: 改名 kernel 侧 PackageDependencySchema → ResolvedPackageDependencySchema —— 双源清账 C7,裸名唯一归 ./cloud (#4741) #4789 的 merge 零冲突标记退出 0,却在三张 ratchet 里全错(改名被吞)—— merge=os-regen 驱动 defer 不再生,证实 git merge-tree 的静默不构成证据。按 feat(spec)!: 退役 DriverCapabilities 31 个零读者能力位 —— 全表活性审计,3 活 31 死(#4634,ADR-0049) #4783 干净路线修复:四张生成物 checkout origin/main,仅重施本 PR 删除,再整体重生成。
• 读数逐项核实:manifest delta = 纯删本单 4 键,kernel/ResolvedPackageDependency 在、kernel/PackageDependency 不在;authorable −22/+0;api-surface −8/+0;dual-source-exports.baseline.json([])、renamed-defs.ts(6 条)、docs-import-surface 均与 main 逐字节一致;check:dual-source-exports 实报 0(未把 feat(spec)!: 改名 kernel 侧 PackageDependencySchema → ResolvedPackageDependencySchema —— 双源清账 C7,裸名唯一归 ./cloud (#4741) #4789 的成果带回 2)。
• 期间 main 又前进两步(fix(i18n): 删掉九份 i18n-extract 配置里未声明的 name: 键 #4803 i18n、fix(plugin-auth): 每号码 OTP 发送预算改用惰性解析的共享计数存储 —— 多节点下不再按节点数倍增 (#4790) #4806 OTP、feat(lint,docs): has(x) 不是 null 守卫 —— 发布期拒绝未守卫的可空比较 (#4763) #4810 lint)均零 spec 交叠,合并队列可平凡处理。
• 合并后全量重验:check:generated 8/8、spec test 294 文件 7362 用例、全仓 typecheck 122/122、全仓 build 71/71、三个受影响 service 包全绿;content/docs/releases/ 全程未触碰。

第二批 ADR-0049 队列至此只剩在飞的 #4657(activationEvents)与 #4793(batch 行形状,方案 B)。

---

Generated by Claude Code