feat(spec)!: 通知模板孤儿语汇退役 —— ./system 不再导出 EmailTemplate/SMSTemplate/PushNotification/InAppNotification (#4616) (#4809)

* feat(spec)!: retire the orphan notification-template vocabulary from ./system (#4616)

ADR-0049 enforce-or-remove, resolved by REMOVE in the v17 breaking window.
`EmailTemplateSchema`, `SMSTemplateSchema`, `PushNotificationSchema` and
`InAppNotificationSchema` (+ their four type aliases) existed ONLY as the
member shapes of the `NotificationConfigSchema.template` union that #4610
(#4535 C3) deleted. Since then they have been reachable from no parent schema
and from no metadata-type root — declared delivery capability the runtime
never read.

Three-repo consumer review (objectstack, cloud @ 5df2c69, objectui @ 785b8a5),
by bare name rather than by import statement — which is what changed the
answer:

- SMSTemplate / PushNotification / InAppNotification: zero references outside
  their own declaration, their own unit tests and the generated artifacts.
- EmailTemplateSchema: NOT consumer-free. objectui's metadata-admin registers
  it as the client-side validator for the `email_template` kind through a
  DYNAMIC import (app-shell/src/views/metadata-admin/clientValidation.ts:89),
  which an import-statement scan cannot see. That registration is itself the
  bug: the canonical schema for the kind is `EmailTemplateDefinitionSchema`,
  and validating an authored definition against the legacy shape reports its
  real keys as missing — the same defect spec 7.1.0 fixed on the framework
  side when it demoted `EmailTemplateSchema` to "an inline sub-shape inside
  `Notification`". Filed separately; removing the legacy export turns that
  silent mis-validation into a compile error at the one site that needs it.
- ui `NotificationSeveritySchema`: REFUTED. The issue proposed retiring it in
  the same sweep on the premise that objectui pins only Type/Position/Action.
  objectui re-exports the type (packages/types), consumes it in
  core/src/protocols/NotificationProtocol.ts, pins the schema name in
  packages/types/src/__tests__/spec-ui-schema-reexports.test.ts, and types two
  severity->tone maps as Record<NotificationSeverityLevel, ...> precisely so a
  new spec severity fails type-check downstream. It is untouched, and the pin
  below asserts it stays ./ui-owned so the claim is not re-litigated.

Route: whole-def removal (#4650 route 3), not a `retiredKey()` tombstone — a
tombstone lives on a surviving schema's shape and none survives here.
gen:schema adjudicates the four defs itself ("def no longer emitted by this
build; whole-schema removals are adjudicated by json-schema.manifest.json and
check:api-surface"), which is why the 22 authorable-surface lines and the 4
manifest keys are deleted in this commit. No ADR-0087 D2 conversion,
deliberately: a conversion rewrites authored or stored sources, and no
metadata document was ever parsed against these defs, so `os migrate meta`
would have nothing to match — same disposition as #4610 in this module, and
as #4767/#4783.

Also corrects `kernel/metadata-plugin.zod.ts`'s `email_template` comment,
which named `EmailTemplateSchema` where the registry resolves
`EmailTemplateDefinitionSchema`. That one parenthetical is the documented
source of the confusion, including objectui's.

The pin is a TypeScript compiler-API test over the package.json exports map
(all 16 entries), asserting each removed name has ZERO holders anywhere — not
merely that ./system omits it — with anti-vacuity guards on entry resolution
and surface size. #4642 established that the conditional-type pin #4610 left
here is a no-op (tsconfig excludes **/*.test.ts), so it is folded in rather
than left as a gate that cannot fail.

Co-Authored-By: Claude <noreply@anthropic.com>

* chore(spec): regenerate the three ratchets after merging #4789 — its rename must not ride out on this branch

`git merge origin/main` brought in #4789 (kernel PackageDependencySchema ->
ResolvedPackageDependencySchema, dual-source C7), which touches the same three
generated artifacts this branch does. The merge reported NO conflicts and left
NO conflict markers, and it was wrong in all three:

  api-surface.json         re-added `PackageDependency (type)` +
                           `PackageDependencySchema (const)` and dropped
                           `ResolvedPackageDependency(Schema)`
  authorable-surface.json  re-added the 4 `kernel/PackageDependency:*` lines and
                           dropped the 4 `kernel/ResolvedPackageDependency:*` ones
  json-schema.manifest.json re-added `kernel/PackageDependency` and dropped
                           `kernel/ResolvedPackageDependency`

json-schema.manifest.json is routed to the `merge=os-regen` driver, which defers
rather than regenerates, so nothing textual signals this — the C17/C10 silent
revert, reproduced. `git merge-tree` does not run external merge drivers and so
cannot see it either.

Resolved the way #4783 did, without any textual merge: reset all three (plus
api-surface-signatures.json) to origin/main, re-applied ONLY this PR's own
deletion to the two hand-ratcheted files, then re-ran the generators over the
merged source. The 22 authorable-surface lines and 4 manifest keys are once
again deliberate deletions, now anchored at merge base ffab803, which
gen:schema re-proved under #4650 route 3 ("def no longer emitted by this
build").

Delta vs origin/main is now pure deletion in all three, with #4789's rename
intact:

  api-surface.json          -8  (4 const + 4 type), 0 insertions
  authorable-surface.json  -22  lines,              0 insertions
  json-schema.manifest.json -4  keys,               0 insertions

check:dual-source-exports reports 0 accepted dual-source (#4789's shrink to []
survives; this branch does not carry it back to 2). renamed-defs.ts is
byte-identical to main and keeps all 6 entries including #4789's.

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/notification-orphan-template-schemas.md

@@ -0,0 +1,60 @@
+---
+"@objectstack/spec": major
+---
+
+feat(spec)!: `@objectstack/spec/system` no longer exports the orphan notification-template vocabulary — `EmailTemplate(Schema)`, `SMSTemplate(Schema)`, `PushNotification(Schema)`, `InAppNotification(Schema)` (#4616)
+
+These four schemas existed **only** as the member shapes of the
+`NotificationConfigSchema.template` union, and #4610 (#4535 C3) deleted that
+union. Since then they have been reachable from no parent schema and from no
+metadata-type root: nothing in framework, cloud or objectui parsed a document
+against them, so they declared delivery capability the runtime never read
+(ADR-0049 enforce-or-remove, resolved by REMOVE in the v17 breaking window).
+
+Migration — one line each, and in every case the replacement already exists:
+
+- FROM `import { EmailTemplateSchema, type EmailTemplate } from '@objectstack/spec/system'` →
+  TO `import { EmailTemplateDefinitionSchema, type EmailTemplateDefinition } from '@objectstack/spec/system'`.
+  **Shape change** — this is a different, richer contract, not a rename:
+  `EmailTemplateDefinitionSchema` is keyed `name` + `locale` (not `id`), splits
+  the body into `bodyHtml` / `bodyText` (not `body` + `bodyType`), and adds
+  `label` / `category` / `active` / `fromOverride` / `replyTo`. It is also a
+  `strictObject`, so the old keys are rejected loudly rather than stripped.
+  This is the schema the `email_template` metadata kind has resolved to since
+  spec **7.1.0**, which demoted `EmailTemplateSchema` when it fixed that Prime
+  Directive #8 double-declaration and kept it "only as an inline sub-shape
+  inside `Notification`" — #4610 removed that holder, and #4616 finishes the
+  job. If your code registers a client-side or publish-time validator for
+  `email_template`, it must point at `EmailTemplateDefinitionSchema`;
+  `BUILTIN_METADATA_TYPE_SCHEMAS` (`kernel/metadata-type-schemas.ts`) is the
+  authority.
+- FROM `import { SMSTemplateSchema, type SMSTemplate } from '@objectstack/spec/system'` →
+  TO: no spec replacement, and none is needed. SMS templates are
+  `sys_notification_template` rows resolved by `(topic, 'sms', locale)`
+  (`service-messaging/src/sms-channel.ts`) and rendered by
+  `template-renderer.ts`; the provider-side template is Aliyun's pre-registered
+  `TemplateCode` in `service-sms` — a vendor API shape, never a spec constant.
+- FROM `import { PushNotificationSchema, type PushNotification } from '@objectstack/spec/system'`
+  and FROM `import { InAppNotificationSchema, type InAppNotification } from '@objectstack/spec/system'` →
+  TO: no replacement. Neither channel has a delivery implementation (#3197):
+  the dispatcher dead-letters any message addressed to them, so these payload
+  shapes advertised a capability nothing delivers. The live delivery ingress is
+  `NotificationService.emit` (`INotificationService`,
+  `@objectstack/spec/contracts`); the in-app bell reads `./api`'s
+  `Notification(Schema)` inbox row; the presentation vocabulary is
+  `@objectstack/spec/ui` (`NotificationTypeSchema`, `NotificationSeveritySchema`,
+  `NotificationPositionSchema`, `NotificationActionSchema` — all unchanged).
+
+Unchanged and explicitly NOT part of this removal:
+`@objectstack/spec/system`'s `NotificationChannel(Schema)` (live — re-exported
+by `@objectstack/spec/contracts`, consumed by `service-messaging`),
+`EmailTemplateDefinition*`, and every `@objectstack/spec/ui` notification
+export.
+
+No ADR-0087 D2 conversion accompanies this change, deliberately: a conversion
+rewrites authored or stored sources, and these defs were reachable from no
+metadata-type root, so `os migrate meta` would have nothing to match. The
+removal is a TypeScript export-surface break only — same disposition as #4610
+in this very module. `json-schema.manifest.json` loses 4 keys and
+`authorable-surface.json` loses their 22 lines; both deletions are adjudicated
+by `gen:schema`'s #4650 route-3 check ("def no longer emitted by this build").

content/docs/references/system/notification.mdx

@@ -5,43 +5,23 @@ description: Notification protocol schemas
 
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
 
-Email Template Schema
+Notification Channel Enum
 
-Defines the structure and content of email notifications.
+Supported notification delivery channels.
 
-Supports variables for personalization and file attachments.
+⚠️ PARTIALLY ENFORCED — the delivery channels actually registered by
 
-@example
+`service-messaging` are `inbox`, `email`, and `sms` (#3197). `push`,
 
-```json
+`slack`, `teams`, and `webhook` have no delivery implementation, and the
 
-\{
+dispatcher dead-letters any message addressed to an unregistered channel.
 
-"id": "welcome-email",
+Note also the naming drift: this enum says `in-app` while the implemented
 
-"subject": "Welcome to \{\{company_name\}\}",
+channel registers as `inbox` (which this enum does not contain) —
 
-"body": "<h1>Welcome \{\{user_name\}\}!</h1>",
-
-"bodyType": "html",
-
-"variables": ["company_name", "user_name"],
-
-"attachments": [
-
-\{
-
-"name": "guide.pdf",
-
-"url": "https://example.com/guide.pdf"
-
-\}
-
-]
-
-\}
-
-```
+reconcile before wiring this enum into the runtime.
 
 <Callout type="info">
 **Source:** `packages/spec/src/system/notification.zod.ts`
@@ -50,45 +30,13 @@ Supports variables for personalization and file attachments.
 ## TypeScript Usage
 
 ```typescript
-import { EmailTemplateSchema, InAppNotificationSchema, NotificationChannelSchema, PushNotificationSchema, SMSTemplateSchema } from '@objectstack/spec/system';
-import type { EmailTemplate, InAppNotification, NotificationChannel, PushNotification, SMSTemplate } from '@objectstack/spec/system';
+import { NotificationChannelSchema } from '@objectstack/spec/system';
+import type { NotificationChannel } from '@objectstack/spec/system';
 
 // Validate data
-const result = EmailTemplateSchema.parse(data);
+const result = NotificationChannelSchema.parse(data);
 ```
 
----
-
-## EmailTemplate
-
-### Properties
-
-| Property | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| **id** | `string` | ✅ | Template identifier |
-| **subject** | `string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | ✅ | Email subject — supports `{{var}`} interpolation |
-| **body** | `string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | ✅ | Email body content — supports `{{var}`} interpolation |
-| **bodyType** | `Enum<'text' \| 'html' \| 'markdown'>` | optional | Body content type |
-| **variables** | `string[]` | optional | Template variables |
-| **attachments** | `{ name: string; url: string }[]` | optional | Email attachments |
-
-
----
-
-## InAppNotification
-
-### Properties
-
-| Property | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| **title** | `string` | ✅ | Notification title |
-| **message** | `string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | ✅ | Notification message — supports `{{var}`} interpolation |
-| **type** | `Enum<'info' \| 'success' \| 'warning' \| 'error'>` | ✅ | Notification type |
-| **actionUrl** | `string` | optional | Action URL |
-| **dismissible** | `boolean` | optional | User dismissible |
-| **expiresAt** | `number` | optional | Expiration timestamp |
-
-
 ---
 
 ## NotificationChannel
@@ -108,33 +56,3 @@ Notification delivery channel (implemented today: inbox, email, sms — push/sla
 
 ---
 
-## PushNotification
-
-### Properties
-
-| Property | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| **title** | `string` | ✅ | Notification title |
-| **body** | `string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | ✅ | Notification body — supports `{{var}`} interpolation |
-| **icon** | `string` | optional | Notification icon URL |
-| **badge** | `number` | optional | Badge count |
-| **data** | `Record<string, any>` | optional | Custom data |
-| **actions** | `{ action: string; title: string }[]` | optional | Notification actions |
-
-
----
-
-## SMSTemplate
-
-### Properties
-
-| Property | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| **id** | `string` | ✅ | Template identifier |
-| **message** | `string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | ✅ | SMS message content — supports `{{var}`} interpolation |
-| **maxLength** | `number` | optional | Maximum message length |
-| **variables** | `string[]` | optional | Template variables |
-
-
----
-

packages/spec/api-surface.json

@@ -896,15 +896,13 @@
     "EmailProviderSchema (const)",
     "EmailServiceConfig (type)",
     "EmailServiceConfigSchema (const)",
-    "EmailTemplate (type)",
     "EmailTemplateDefinition (type)",
     "EmailTemplateDefinitionCategory (type)",
     "EmailTemplateDefinitionCategorySchema (const)",
     "EmailTemplateDefinitionInput (type)",
     "EmailTemplateDefinitionSchema (const)",
     "EmailTemplateDefinitionVariable (type)",
     "EmailTemplateDefinitionVariableSchema (const)",
-    "EmailTemplateSchema (const)",
     "EmailVerificationConfig (type)",
     "EmailVerificationConfigSchema (const)",
     "EncryptionAlgorithm (type)",
@@ -950,8 +948,6 @@
     "HttpServerConfigSchema (const)",
     "ISettingsCapability (interface)",
     "ISettingsClient (interface)",
-    "InAppNotification (type)",
-    "InAppNotificationSchema (const)",
     "Incident (type)",
     "IncidentCategory (type)",
     "IncidentCategorySchema (const)",
@@ -1146,8 +1142,6 @@
     "PlanSchema (const)",
     "PresignedUrlConfig (type)",
     "PresignedUrlConfigSchema (const)",
-    "PushNotification (type)",
-    "PushNotificationSchema (const)",
     "QueueConfig (type)",
     "QueueConfigInput (type)",
     "QueueConfigSchema (const)",
@@ -1188,8 +1182,6 @@
     "RowLevelIsolationStrategyInput (type)",
     "RowLevelIsolationStrategySchema (const)",
     "SETTINGS_CHANGE_EVENT (const)",
-    "SMSTemplate (type)",
-    "SMSTemplateSchema (const)",
     "SamplingDecision (type)",
     "SamplingStrategyType (type)",
     "Schedule (type)",

packages/spec/authorable-surface.json

@@ -5903,12 +5903,6 @@
     "system/EmailServiceConfig:persist",
     "system/EmailServiceConfig:provider",
     "system/EmailServiceConfig:retries",
-    "system/EmailTemplate:attachments",
-    "system/EmailTemplate:body",
-    "system/EmailTemplate:bodyType",
-    "system/EmailTemplate:id",
-    "system/EmailTemplate:subject",
-    "system/EmailTemplate:variables",
     "system/EmailTemplateDefinition:_lock",
     "system/EmailTemplateDefinition:_lockDocsUrl",
     "system/EmailTemplateDefinition:_lockReason",
@@ -6010,12 +6004,6 @@
     "system/HttpServerConfig:security",
     "system/HttpServerConfig:static",
     "system/HttpServerConfig:trustProxy",
-    "system/InAppNotification:actionUrl",
-    "system/InAppNotification:dismissible",
-    "system/InAppNotification:expiresAt",
-    "system/InAppNotification:message",
-    "system/InAppNotification:title",
-    "system/InAppNotification:type",
     "system/Incident:affectedDataClassifications",
     "system/Incident:affectedSystems",
     "system/Incident:category",
@@ -6470,12 +6458,6 @@
     "system/PresignedUrlConfig:operation",
     "system/PresignedUrlConfig:responseContentDisposition",
     "system/PresignedUrlConfig:responseContentType",
-    "system/PushNotification:actions",
-    "system/PushNotification:badge",
-    "system/PushNotification:body",
-    "system/PushNotification:data",
-    "system/PushNotification:icon",
-    "system/PushNotification:title",
     "system/QueueConfig:autoScale",
     "system/QueueConfig:concurrency",
     "system/QueueConfig:deadLetterQueue",
@@ -6536,10 +6518,6 @@
     "system/RowLevelIsolationStrategy:database",
     "system/RowLevelIsolationStrategy:performance",
     "system/RowLevelIsolationStrategy:strategy",
-    "system/SMSTemplate:id",
-    "system/SMSTemplate:maxLength",
-    "system/SMSTemplate:message",
-    "system/SMSTemplate:variables",
     "system/SchemaChange:changeType",
     "system/SchemaChange:entityName",
     "system/SchemaChange:entityType",

packages/spec/json-schema.manifest.json

@@ -1258,7 +1258,6 @@
     "system/EmailAndPasswordConfig",
     "system/EmailProvider",
     "system/EmailServiceConfig",
-    "system/EmailTemplate",
     "system/EmailTemplateDefinition",
     "system/EmailTemplateDefinitionCategory",
     "system/EmailTemplateDefinitionVariable",
@@ -1280,7 +1279,6 @@
     "system/HistogramBucketConfig",
     "system/HttpDestinationConfig",
     "system/HttpServerConfig",
-    "system/InAppNotification",
     "system/Incident",
     "system/IncidentCategory",
     "system/IncidentNotificationMatrix",
@@ -1372,7 +1370,6 @@
     "system/PackagePublishResult",
     "system/Plan",
     "system/PresignedUrlConfig",
-    "system/PushNotification",
     "system/QueueConfig",
     "system/QuotaEnforcementResult",
     "system/RPO",
@@ -1387,7 +1384,6 @@
     "system/RollbackPlan",
     "system/RouteHandlerMetadata",
     "system/RowLevelIsolationStrategy",
-    "system/SMSTemplate",
     "system/SamplingDecision",
     "system/SamplingStrategyType",
     "system/Schedule",

packages/spec/src/kernel/metadata-plugin.zod.ts

@@ -113,7 +113,13 @@ export const MetadataTypeSchema = lazySchema(() => z.enum([
   // code contributions: plugin `contributes.routes` + declarative `apis:`
   // (router), `defineStack({ functions })` + `contributes.functions`
   // (function), and the plugin/service registry itself (service).
-  'email_template', // Outbound email templates (EmailTemplateSchema)
+  // #4616: the canonical schema is `EmailTemplateDefinitionSchema`
+  // (`system/email-template.zod.ts`), which is what `BUILTIN_METADATA_TYPE_SCHEMAS`
+  // resolves this kind to. This comment used to name `EmailTemplateSchema` — the
+  // legacy sub-shape spec 7.1.0 demoted when it fixed that Prime Directive #8
+  // double-declaration, and removed outright in #4616 — which is exactly how
+  // consumers kept wiring the wrong one.
+  'email_template', // Outbound email templates (EmailTemplateDefinitionSchema)
   'doc',         // Package documentation — flat Markdown items (DocSchema, ADR-0046)
   'book',        // Documentation navigation spine (BookSchema, ADR-0046 §6)