spec: EmailServiceConfigSchema 未声明 CLI 实读的 queueDelivery / appName / defaultTemplateContext(与 #5104 同族,不同键)

[os-zhuang]

在实施 #5104(给 EmailProviderSchema 补 smtp)时,顺带实测了 config.email 的读侧与声明侧的差集。provider 之外还有三个键落在同一类缺口上,属于 #5104 的同族缺陷但不在其验收范围内,故单独立单。

实测(origin/main @ 5993c5b)

packages/cli/src/commands/serve.ts 的 resolveEmailCapabilityArg 从 config.email 读这些键:

cfgEmail.apiKey
cfgEmail.appName                 <-- 未声明
cfgEmail.defaultFrom
cfgEmail.defaultTemplateContext  <-- 未声明
cfgEmail.options
cfgEmail.provider
cfgEmail.queueDelivery           <-- 未声明
cfgEmail.retries

packages/spec/src/system/email-config.zod.ts 的 EmailServiceConfigSchema 声明:
provider / apiKey / defaultFrom / retries / persist / options。

差集三个:queueDelivery、appName、defaultTemplateContext。

复现命令:

grep -oE "cfgEmail\.[a-zA-Z]+" packages/cli/src/commands/serve.ts | sort -u

影响

与 #5104 完全同型 —— spec 落后于运行时的 declared != implemented,只是键不同:

• queueDelivery 是 plugin-email: 邮件投递接入持久化队列 —— send 走 email.send.async / sys_job_queue(重试+DLQ),可配置开关 #5160 落地的耐久队列投递开关(对应 OS_EMAIL_QUEUE_ENABLED),是已发布的真实能力。用 EmailServiceConfig 类型标注 objectstack.config.ts 的作者写 queueDelivery: true 会拿到类型错误,而运行时完全支持 —— CLI 直读 config.email,不过这个 schema。
• appName / defaultTemplateContext 同理,喂的是邮件模板渲染上下文。
• 生成的参考文档 content/docs/references/system/email-config.mdx 的属性表同样看不到这三个键,AI 作者读到的是「不支持」。

注意这三个键都是运行时已经在读的,所以补声明是把契约追平既成事实,不是新增能力。

与 #5104 的关系

不是 #5104 的子集:#5104 的验收面明确只到 provider 枚举 + SMTP 的 TSDoc/生成文档,PR 已按该范围收口。本单需要新增可授权键,因此还要走 #5220 的 strictness-ledger 纪律(pnpm gen:strictness-ledger 整体重算,禁止手改数字),体量与风险都与 #5104 不同,合并在一起会让那单的 diff 失焦。

两单碰同一个文件 email-config.zod.ts 与同一个生成物(merge=os-regen,会静默吞掉一侧),建议串行:等 #5104 的 PR 落地后再派发本单。

待确认(不要照抄,以实施者实测为准)

• 三个键的正确 Zod 形状,尤其 defaultTemplateContext(自由 record 还是有约束的对象?)。
• persist 是反向的:schema 声明了它,但 resolveEmailCapabilityArg 没读 —— 需要确认它是在别处(plugin 侧)被消费,还是一个 declared-but-unenforced 的键。若是后者,按 ADR-0049 enforce-or-remove 处理,与本单三键方向相反。

---

由 #5104 的实施过程中发现并记录(session session_01ErbEDVAg1No9gdg1pgDAGB),未认领。