docs(spec): appName 文案与 parity pin 收口到 #5448 裁定的新序(PR #5498)

#5448 已裁 direction B 并由 PR #5498 落地:`resolveEmailCapabilityArg` 现在把
`appName` 放在 context 展开之后解析,五级链为 `OS_APP_NAME` >
`config.email.appName` > `defaultTemplateContext.appName` > 顶层 `appName` >
`'ObjectStack'`。本分支上写于旧序之上的三处东西随之收口:

- `serve-email-config-parity.contract.test.ts` 那条 pin 原本钉的是旧序
  (context.appName 压过 env),现改为钉新序。它保留本文件自己的角度而非
  重述 #5498 的用例:配置先过真正的 `EmailServiceConfigSchema.parse()` 再喂
  读侧,因此钉住的是 #5307 新加的两个契约键既能存活 parse、又确实落在
  schema 文案承诺的档位上。
- `email-config.zod.ts` 中 `appName` / `defaultTemplateContext` 的 TSDoc 与
  两处 `.describe()`:旧文案写的是「写在 context 里的 appName 压过 appName
  键与 OS_APP_NAME、是否合理 filed as #5448」,该事实已不成立。

`email-config.mdx` 由 `gen:docs` 整体重生成(未手改),9 个 generated 门全绿。
运行时零改动 —— `serve.ts` 未被本次改动触碰。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018fxLGQdatPbBUvCgiVxg6D

Author: claude

.changeset/email-config-runtime-read-keys.md

@@ -19,8 +19,13 @@ spec: `EmailServiceConfigSchema` 补齐 CLI 实读的 `queueDelivery` / `appName
 
 本次是把契约追平既成事实,**运行时零改动**:三个键都是 optional,不带 `.default()`
 (默认值由 `resolveEmailCapabilityArg` 对着 env 与顶层 config 解析,schema 再造一个只会
-多出一个谁也不赢的答案),`defaultTemplateContext` 保持自由 record —— 读侧原样透传,
-声明一套读侧没有的约束等于发明契约。
+多出一个谁也不赢的答案),`defaultTemplateContext` 保持自由 record —— 除 `appName` 外
+读侧原样透传,声明一套读侧没有的约束等于发明契约。
+
+`appName` 与 `defaultTemplateContext` 的 TSDoc / `.describe()` 按 #5448 已裁定的新序落笔
+(`OS_APP_NAME` > `config.email.appName` > `defaultTemplateContext.appName` > 顶层
+`appName` > `'ObjectStack'`,PR #5498 落地),因此生成的 `email-config.mdx` 属性表文案
+随之更新:此前 context 里的 `appName` 压过 env 的旧行为已不复存在,文档不再那样承诺。
 
 同时新增跨包契约测试 `serve-email-config-parity.contract.test.ts`,把 issue 里那条手工
 grep 机械化:读侧多出一个未声明的键即变红,不必再等下一次人工比对。

content/docs/references/system/email-config.mdx

@@ -102,8 +102,8 @@ const result = EmailAddressConfigSchema.parse(data);
 | **persist** | `boolean` | optional | Persist to sys_email (default true) |
 | **queueDelivery** | `boolean` | optional | Deliver through the durable sys_job_queue instead of inline (or OS_EMAIL_QUEUE_ENABLED env). Default false. Reuses `retries` as the queue attempt budget; requires a queue service and sys_email persistence, else the boot fails |
 | **options** | `Record<string, any>` | optional | Provider-specific extras. smtp: host (required) / port / secure / user / password, mirroring OS_EMAIL_SMTP_HOST / _PORT / _SECURE / _USER / _PASSWORD. postmark: messageStream |
-| **appName** | `string` | optional | Product name templates interpolate as the appName variable — OS_APP_NAME env wins, then this, then the top-level config appName, then "ObjectStack". Also seeds the placeholder no-reply sender when no defaultFrom is configured |
-| **defaultTemplateContext** | `Record<string, any>` | optional | Free-form render context merged into every sendTemplate() call, under the per-call data. Passed through unchanged. An appName written here overrides both the appName key and OS_APP_NAME |
+| **appName** | `string` | optional | Product name templates interpolate as the appName variable — OS_APP_NAME env wins, then this, then defaultTemplateContext.appName, then the top-level config appName, then "ObjectStack". Also seeds the placeholder no-reply sender when no defaultFrom is configured |
+| **defaultTemplateContext** | `Record<string, any>` | optional | Free-form render context merged into every sendTemplate() call, under the per-call data. Passed through unchanged except appName, which is resolved by its own chain — OS_APP_NAME and the appName key both override the value written here |
 
 
 ---

packages/cli/src/commands/serve-email-config-parity.contract.test.ts

@@ -166,20 +166,54 @@ describe('a config the schema accepts reaches the plugin intact', () => {
     expect(options.defaultFrom).toEqual({ name: 'Acme CRM', address: 'no-reply@acme-crm.local' });
   });
 
-  it('spreads defaultTemplateContext OVER the resolved appName, as documented', () => {
-    // Not the precedence the header TSDoc's "env overrides per setting" line
-    // would predict — `OS_APP_NAME` loses to an `appName` written inside
-    // `defaultTemplateContext`. Measured, documented in the schema, and filed
-    // as #5448; pinned here so a change to it is deliberate rather than
-    // discovered by an operator whose branded mail says the wrong name.
+  it('resolves appName by the five-rung chain — env over both declared keys (#5448)', () => {
+    // This pin used to record the OPPOSITE: `defaultTemplateContext` was
+    // spread OVER the resolved value, so `OS_APP_NAME` lost to an `appName`
+    // written inside it. That was measured behaviour, not intent, and was
+    // filed as #5448 — settled direction B (the env must win, per the header's
+    // "override per setting") and implemented by PR #5498, which resolves
+    // `appName` AFTER the spread. This pin now guards the new order.
+    //
+    // Its angle is this file's own, and not a restatement of
+    // `serve-email-appname-precedence.test.ts`: that file feeds the resolver
+    // raw objects, whereas the config below goes through the real
+    // `EmailServiceConfigSchema.parse()` first. So what is pinned here is that
+    // the two keys #5307 added to the CONTRACT survive the parse AND land on
+    // the rungs the schema's own prose promises — a schema that renamed,
+    // stripped or reshaped either key would be red here even while the
+    // resolver's own tests stayed green.
     const parsed = EmailServiceConfigSchema.parse({
       appName: 'From The Key',
-      defaultTemplateContext: { appName: 'From The Context' },
+      defaultTemplateContext: { appName: 'From The Context', supportEmail: 'help@acme.test' },
     });
-    const { options } = resolveEmailCapabilityArg(parsed as Record<string, any>, {
+
+    // Rung 1 — all three sources distinct and present: the env var wins.
+    // (Three DIFFERENT values on purpose: asserting a value all three sources
+    // agree on would pass under any ordering, including the old one.)
+    const withEnv = resolveEmailCapabilityArg(parsed as Record<string, any>, {
       OS_APP_NAME: 'From The Env',
+    }).options;
+    expect(withEnv.defaultTemplateContext).toEqual({
+      appName: 'From The Env',
+      supportEmail: 'help@acme.test',   // every other context key still spreads verbatim
     });
+    // The blast radius #5448 named: the placeholder sender is slugged from the
+    // resolved name, so the envelope moves with the body or the fix is half done.
+    expect(withEnv.defaultFrom).toEqual({ name: 'From The Env', address: 'no-reply@from-the-env.local' });
+
+    // Rung 2 — no env: the declared `appName` key beats the context form.
+    // Under the old spread-over order this answered 'From The Context' too,
+    // so this half discriminates the two orders even without an env var set.
+    const noEnv = resolveEmailCapabilityArg(parsed as Record<string, any>, {}).options;
+    expect(noEnv.defaultTemplateContext).toMatchObject({ appName: 'From The Key' });
 
-    expect(options.defaultTemplateContext).toMatchObject({ appName: 'From The Context' });
+    // Rung 3 — the context form is still IN the chain, not dropped behind the
+    // dedicated key: a config that declares only this shape keeps its name
+    // rather than being demoted to 'ObjectStack'.
+    const contextOnly = EmailServiceConfigSchema.parse({
+      defaultTemplateContext: { appName: 'From The Context' },
+    });
+    expect(resolveEmailCapabilityArg(contextOnly as Record<string, any>, {}).options
+      .defaultTemplateContext).toMatchObject({ appName: 'From The Context' });
   });
 });

packages/spec/src/system/email-config.zod.ts

@@ -153,10 +153,18 @@ export const EmailServiceConfigSchema = lazySchema(() => z.object({
    * template context this schema names explicitly because the runtime also
    * derives a *from-address* out of it.
    *
-   * Resolved as `OS_APP_NAME` env → this key → the top-level `appName` of
-   * `objectstack.config.ts` → `'ObjectStack'`. It is seeded into
-   * `defaultTemplateContext` as `appName`, so setting it here is exactly
-   * `defaultTemplateContext: { appName: … }` with the env layer in front.
+   * Resolved on a five-rung chain: `OS_APP_NAME` env → this key →
+   * `defaultTemplateContext.appName` → the top-level `appName` of
+   * `objectstack.config.ts` → `'ObjectStack'`. The resolved value is then
+   * written into `defaultTemplateContext` as `appName`, so templates read one
+   * answer whichever rung supplied it.
+   *
+   * This key and `defaultTemplateContext: { appName: … }` are therefore NOT
+   * interchangeable — this one is the higher rung, and both lose to the env
+   * var. That ordering was settled by #5448 (implemented in PR #5498): before
+   * it, the whole context was spread OVER the resolved value, which made
+   * `OS_APP_NAME` inert for any config that spelled the context form — the one
+   * per-environment lever over a repo-pinned config, silently doing nothing.
    *
    * When no `defaultFrom` resolves from any source, the resolved app name
    * also becomes the placeholder sender — `Acme CRM` ⇒
@@ -170,31 +178,40 @@ export const EmailServiceConfigSchema = lazySchema(() => z.object({
       // into MDX as `` `{{x}` `` plus a stray `}` (three such sites already on
       // main — filed as #5452), so the name is spelled without them.
       'Product name templates interpolate as the appName variable — OS_APP_NAME env wins, then '
-      + 'this, then the top-level config appName, then "ObjectStack". Also seeds the placeholder '
-      + 'no-reply sender when no defaultFrom is configured',
+      + 'this, then defaultTemplateContext.appName, then the top-level config appName, then '
+      + '"ObjectStack". Also seeds the placeholder no-reply sender when no defaultFrom is configured',
     ),
 
   /**
    * Render context merged into every `sendTemplate()` call, under the
    * per-call `data`. Free-form on purpose: the CLI passes this object
-   * through to `EmailServicePlugin` unchanged and the template engine
-   * resolves whatever names a template happens to reference, so there is no
-   * closed vocabulary here to declare — put the values your own templates
-   * interpolate (support address, brand URL, footer text …).
+   * through to `EmailServicePlugin` as written — `appName` excepted, see
+   * below — and the template engine resolves whatever names a template
+   * happens to reference, so there is no closed vocabulary here to declare —
+   * put the values your own templates interpolate (support address, brand
+   * URL, footer text …).
+   *
+   * One key is not passed through as written: `appName`. It is always
+   * present in the delivered context, and its value comes from the chain on
+   * the `appName` key above — `OS_APP_NAME` → `appName` → this map's
+   * `appName` → the top-level config `appName` → `'ObjectStack'`. So writing
+   * it here still works (it is the third rung, and a config that spells only
+   * this form keeps its name), but the env var and the dedicated key both
+   * override it.
    *
-   * `appName` is always present: it is computed first and this object is
-   * spread OVER it, so an `appName` written here wins over `OS_APP_NAME`
-   * and over the `appName` key above. That is the one place the header's
-   * "env overrides per setting" does not hold, measured rather than
-   * intended — whether it should is filed as #5448. Until it is settled,
-   * prefer `appName` (or the env var) for that one value and keep this map
-   * for everything else.
+   * It used to be the other way round: the resolver computed the value and
+   * then spread this whole map OVER it, which made `OS_APP_NAME` inert and
+   * broke the header's "env overrides per setting" on exactly one key.
+   * #5448 settled that the env must win (implemented in PR #5498), and the
+   * exception is gone. Every OTHER key here has no env or dedicated-config
+   * carrier, so it remains the only source for itself and reaches templates
+   * verbatim.
    */
   defaultTemplateContext: z.record(z.string(), z.unknown()).optional()
     .describe(
       'Free-form render context merged into every sendTemplate() call, under the per-call data. '
-      + 'Passed through unchanged. An appName written here overrides both the appName key and '
-      + 'OS_APP_NAME',
+      + 'Passed through unchanged except appName, which is resolved by its own chain — '
+      + 'OS_APP_NAME and the appName key both override the value written here',
     ),
 }));
 export type EmailServiceConfig = z.infer<typeof EmailServiceConfigSchema>;