@@ -0,0 +1,12 @@
+---
+'@objectstack/spec': patch
+---
+
+docs(spec): the email template locale docs describe the ladder #28880 landed (#28896)
+
+Clause-②: no
+Metadata-protocol: none
+
+The `SendTemplateInput.template` / `.locale` docs, the `EMAIL_TEMPLATE_FLOOR_LOCALE` docblock, the `EmailTemplateDefinitionSchema.locale` docblock and its served `describe`, and the `defineStack` warning for a bundle with no `en-US` row said the resolver matches the named locale exactly and retries only `en-US`, with no language-subtag folding. Since #28880, over the built-in template loader, a call that names a locale folds it against the template's own locales (exact, case-insensitive, base language, variant expansion), then tries the stack's declared fallback locale (`i18n.fallbackLocale`, else `defaultLocale`) folded the same way, then `en-US`, then fails with `TEMPLATE_NOT_FOUND`. The texts now say so, and say that a replacement `TemplateLoader` keeps the exact ladder and that a call naming no locale keeps its own ladder (`en-US`, then the bundle's lowest tag).
+
+Text only: no schema shape, accept set or warning trigger changes. `en` and `en-US` are still two rows of one bundle.
@@ -48,7 +48,7 @@ const result = EmailTemplateDefinitionSchema.parse(data);
 | **name** | `string` | ✅ | Template identifier (dotted snake_case) |
 | **label** | `string` | ✅ | Display label |
 | **category** | `never` | optional | [REMOVED] `email_template.category` was removed in @objectstack/spec 18 (ADR-0049 enforce-or-remove) — nothing read it: the Studio listing never offered the filter facet it promised, and delivery never depended on it. Delete the key. A template is found by its `name`, so group templates with a dotted namespace prefix instead (`auth.password_reset`, `crm.welcome`). Run `os migrate meta --from 17` to list the mechanical edits for existing sources; `--write` applies the ones it can prove, and you apply the rest by hand. |
-| **locale** | `string` | optional (default: `"en-US"`) | BCP-47 locale (e.g. en-US, zh-CN) — the bundle key the resolver matches EXACTLY. A call that NAMES a locale gets exactly one retry rung, the literal `en-US`, with no language-subtag folding: `en` and `en-US` are different ROWS of one bundle and neither reaches the other, so a bundle with no `en-US` row has no fallback floor for those calls and every recipient locale it does not carry a row for raises TEMPLATE_NOT_FOUND, which is permanent — the delivery dead-letters with no retry. A call naming NO locale is the other case and does not dead-letter: it drops to the bundle's lowest locale tag and renders that silently. Your stack's own `i18n.defaultLocale` is the wrong tag here unless it is spelled `en-US`. |
+| **locale** | `string` | optional (default: `"en-US"`) | BCP-47 locale (e.g. en-US, zh-CN) — the bundle key. Each rung of the resolver reads one row at one tag exactly, so `en` and `en-US` are different ROWS of one bundle. A call that NAMES a locale, over the built-in template loader, folds it against the bundle's tags (exact, case-insensitive, base language, then variant expansion: `en-GB` reaches `en`, `zh-TW` reaches `zh-CN`), then folds the stack's declared fallback locale (`i18n.fallbackLocale`, else `defaultLocale`) the same way, then tries the literal `en-US`; a replacement template loader matches the tag exactly and retries only `en-US`. `en-US` is the floor every loader honours: when no rung lands on a row the call raises TEMPLATE_NOT_FOUND, which is permanent — the delivery dead-letters with no retry. A call naming NO locale folds nothing and does not dead-letter: it starts at `en-US` and otherwise drops to the bundle's lowest locale tag and renders that silently. Tag the English row `en-US` so every loader has the floor. |
 | **subject** | `string` | ✅ | Subject template. Holes are `{{ path }}` or `{{ path \| formatter[:arg] }}` over the send's `data`, with at most one formatter per hole (a second, chained formatter is refused). A formatter is one word, optionally followed by `:` and its argument (text that is not, such as `date-long`, is refused), and it is one the template engine knows (an unknown name, such as a misspelled `curency`, is refused, naming the known formatters). A `currency` argument is either a literal ISO 4217 code in three capital letters (`currency:EUR`) or, in a mail template only, `@` followed by a path into the send's data whose value is such a code (`currency:@currency_code`). |
 | **bodyHtml** | `string` | ✅ | HTML body template. Holes are `{{ path }}` or `{{ path \| formatter[:arg] }}` over the send's `data`, with at most one formatter per hole (a second, chained formatter is refused). A formatter is one word, optionally followed by `:` and its argument (text that is not, such as `date-long`, is refused), and it is one the template engine knows (an unknown name, such as a misspelled `curency`, is refused, naming the known formatters). A `currency` argument is either a literal ISO 4217 code in three capital letters (`currency:EUR`) or, in a mail template only, `@` followed by a path into the send's data whose value is such a code (`currency:@currency_code`). |
 | **bodyText** | `string` | optional | Plain-text body template (auto-derived from HTML when omitted). Holes are `{{ path }}` or `{{ path \| formatter[:arg] }}` over the send's `data`, with at most one formatter per hole (a second, chained formatter is refused). A formatter is one word, optionally followed by `:` and its argument (text that is not, such as `date-long`, is refused), and it is one the template engine knows (an unknown name, such as a misspelled `curency`, is refused, naming the known formatters). A `currency` argument is either a literal ISO 4217 code in three capital letters (`currency:EUR`) or, in a mail template only, `@` followed by a path into the send's data whose value is such a code (`currency:@currency_code`). |
 
@@ -171,28 +171,50 @@ export interface SendEmailResult {
 export interface SendTemplateInput {
   /**
    * Template identifier (the `email_template` item's `name`), e.g.
-   * `'auth.password_reset'`. There is no "best match" and no language-subtag
-   * folding: the locale member is resolved by the exact ladder documented on
-   * `locale` below.
+   * `'auth.password_reset'`. The name is matched exactly; only the locale
+   * member is resolved, by the ladder documented on `locale` below. Every
+   * rung of it loads one row at one tag exactly, so `en` and `en-US` stay two
+   * distinct rows of the bundle: folding chooses which row is read, it never
+   * merges two.
    */
   template: string;
   /** Envelope recipients. */
   to: EmailAddress | EmailAddress[];
   /** Render context — placeholders in subject/body are resolved against this object. */
   data?: Record<string, unknown>;
   /**
-   * Preferred BCP-47 locale (e.g. user's locale). Falls back to `'en-US'`.
+   * Preferred BCP-47 locale (e.g. user's locale).
    *
-   * Resolution is exact, then default, then deterministic — never "whichever
-   * row the store yields first" (#7731):
+   * Resolution is deterministic, never "whichever row the store yields first"
+   * (#7731). A call that NAMES a locale, over the built-in registry template
+   * loader (the one `EmailServicePlugin` wires), walks (#28880):
    *
-   *  1. this locale, matched exactly (no language-only prefix matching: `zh`
-   *     does not resolve `zh-CN`);
-   *  2. `'en-US'` — which is also where a call that omits `locale` STARTS, so
-   *     "no locale" means the default rather than an arbitrary member;
-   *  3. only for a call that named no locale, and only when the bundle has no
-   *     `en-US` member at all: its lowest locale tag, so a single-locale
-   *     bundle keeps rendering and does so identically on every boot.
+   *  1. this locale, folded against the locale tags the template's bundle
+   *     carries by `resolveBundleLocale` (`@objectstack/spec/system`, the
+   *     BCP-47 fold plugin-email imports rather than copying): exact, then
+   *     case-insensitive (`zh-cn` → `zh-CN`), then base language (`en-GB` →
+   *     `en`), then variant expansion (`zh` and `zh-TW` → `zh-CN`), the first
+   *     match in ascending tag order;
+   *  2. the stack's declared fallback locale, as
+   *     `II18nService.getFallbackLocale()` answers it (`i18n.fallbackLocale`,
+   *     else `defaultLocale`), folded the same way. A host whose i18n service
+   *     declares none, or that has no i18n service, skips this rung;
+   *  3. `'en-US'`, exactly;
+   *  4. none of them lands on a row: `TEMPLATE_NOT_FOUND`, which is permanent.
+   *
+   * A rung that resolves to a tag already tried is skipped. A replacement
+   * `TemplateLoader` keeps the exact ladder: this locale matched exactly, then
+   * `'en-US'`, then `TEMPLATE_NOT_FOUND`, with no fold and no declared
+   * fallback.
+   *
+   * A call that omits `locale` keeps its own ladder. The service's part of it
+   * holds over any loader: no fold, no declared fallback, and `'en-US'` first,
+   * exactly, so "no locale" means the default rather than an arbitrary member.
+   * When that misses, the service asks the loader for its own no-locale
+   * answer. The built-in registry loader answers the bundle's `en-US` member,
+   * else its lowest locale tag, so a single-locale bundle keeps rendering and
+   * does so identically on every boot; a replacement `TemplateLoader` gives
+   * its own deterministic best answer for the name.
    */
   locale?: string;
   /**
@@ -279,8 +301,8 @@ export interface RenderTemplateInput {
   currency?: string;
   /**
    * Preferred BCP-47 locale. Resolution is the SAME ladder as
-   * {@link SendTemplateInput.locale} — exact match, then `'en-US'`, then
-   * (no-locale calls only) the bundle's deterministic single-locale answer.
+   * {@link SendTemplateInput.locale}, both the named-locale and the no-locale
+   * one.
    */
   locale?: string;
   /**
@@ -330,8 +352,9 @@ export interface IEmailService {
    * Locale resolution is the ladder on {@link SendTemplateInput.locale}.
    *
    * Errors:
-   * - `TEMPLATE_NOT_FOUND` — no template matches `(name, locale|en-US)`, and
-   *   (for a call that named no locale) the name carries no members at all.
+   * - `TEMPLATE_NOT_FOUND` — no rung of the locale ladder lands on a row of
+   *   the name's bundle; for a call that named no locale, the name carries no
+   *   members at all.
    * - `TEMPLATE_INACTIVE`  — the template exists but `active=false`.
    * - `MISSING_VARIABLES`  — declared `required` variables absent from `data`.
    * - `TEMPLATE_INVALID`   — the stored template has a hole the authoring rules
@@ -361,8 +384,9 @@ export interface IEmailService {
    * Locale resolution is the ladder on {@link SendTemplateInput.locale}.
    *
    * Errors (same vocabulary as `sendTemplate`, since resolution is shared):
-   * - `TEMPLATE_NOT_FOUND` — no template matches `(name, locale|en-US)`, and
-   *   (for a call that named no locale) the name carries no members at all.
+   * - `TEMPLATE_NOT_FOUND` — no rung of the locale ladder lands on a row of
+   *   the name's bundle; for a call that named no locale, the name carries no
+   *   members at all.
    * - `TEMPLATE_INACTIVE`  — the template exists but `active=false`.
    * - `MISSING_VARIABLES`  — declared `required` variables absent from `data`.
    * - `TEMPLATE_INVALID`   — the stored template has a hole the authoring rules
 
@@ -9,14 +9,17 @@
 // the resolver then answered `TEMPLATE_NOT_FOUND` — which classifies
 // PERMANENT, so the delivery dead-letters with no retry — for `de-DE` and for
 // the literal `en-US`. The identical bundle with its English row tagged
-// `en-US` delivered for `de-DE`. `sendTemplate` matches `(name, locale)`
-// exactly and, for a call that NAMES a locale, retries exactly one rung — the
-// literal `en-US` — and stops; there is no language-subtag folding. A call that
-// names NO locale is the other case and does NOT dead-letter: it starts at
-// `en-US` by name and, when the bundle carries no `en-US` row, drops to that
-// bundle's lowest locale tag and renders it silently. That ladder's shape is a
-// settled ruling this change deliberately does not touch. The remedy is the
-// bundle, so the diagnostic is where the author is standing.
+// `en-US` delivered for `de-DE`. At that time `sendTemplate` matched
+// `(name, locale)` exactly and retried only the literal `en-US`. Since #28880,
+// over the built-in template loader, a call that NAMES a locale folds it
+// against the bundle's tags and then tries the stack's declared fallback
+// locale folded the same way, before `en-US`; a replacement `TemplateLoader`
+// keeps the exact ladder. `en-US` stays the one rung every loader retries,
+// which is the floor this diagnostic names. A call that names NO locale is the
+// other case and does NOT dead-letter: it starts at `en-US` by name and, when
+// the bundle carries no `en-US` row, drops to that bundle's lowest locale tag
+// and renders it silently. The remedy is the bundle, so the diagnostic is
+// where the author is standing.
 //
 // These pin the diagnostic ADVISORY: every case asserts the parse still
 // succeeds and the stack comes back unchanged. The diagnostic narrows what
 
@@ -5929,12 +5929,18 @@ const warnedEmailTemplateFloors = new Set<string>();
  *
  * ## What goes wrong without this
  *
- * `IEmailService.sendTemplate` matches `(name, locale)` EXACTLY and, for a call
- * that NAMES a locale, retries exactly one rung — the literal `en-US` — and
- * stops. There is no language-subtag folding, so a bundle whose English row is
- * tagged `en` is unreachable from `en-US` and from every other tag it does not
- * itself carry: each such delivery raises `TEMPLATE_NOT_FOUND`, which
- * classifies **permanent**, so it dead-letters with no retry. `sys_user.locale`
+ * `IEmailService.sendTemplate` reads one row at one tag exactly. For a call
+ * that NAMES a locale, over the built-in registry template loader, it folds
+ * that locale against the bundle's tags (`resolveBundleLocale`: exact,
+ * case-insensitive, base language, variant expansion), then the stack's
+ * declared fallback locale (`i18n.fallbackLocale`, else `defaultLocale`) the
+ * same way, then the literal `en-US` (#28880); a replacement `TemplateLoader`
+ * matches the named tag exactly and retries only `en-US`. So a bundle with no
+ * `en-US` row is reachable from a recipient tag only when that tag or the
+ * declared fallback folds to one of its rows, and behind a replacement loader
+ * only from the tags it carries exactly. Every other delivery raises
+ * `TEMPLATE_NOT_FOUND`, which classifies **permanent**, so it dead-letters
+ * with no retry. `sys_user.locale`
  * is user-editable free-text BCP-47 and is NOT constrained to
  * `supportedLocales`, so the locales that can reach the lookup are not the ones
  * the author enumerated — a recipient can break their own mail by setting a
@@ -5944,15 +5950,17 @@ const warnedEmailTemplateFloors = new Set<string>();
  * starts at `en-US` by name and, when the bundle carries no `en-US` row, drops
  * to that bundle's lowest locale tag and renders it silently. So one floorless
  * bundle dead-letters the recipients whose locale was named and quietly fills
- * for the ones whose was not. The full three-rung ladder is on
+ * for the ones whose was not. The full ladders are on
  * `SendTemplateInput.locale` in `packages/spec/src/contracts/email-service.ts`
- * and is not restated here.
+ * and are not restated here.
  *
- * ⭐ The trap is that the author does the CONSISTENT thing: a stack declaring
- * `defaultLocale: 'en'` whose English row says `locale: 'en'` agrees with
- * itself everywhere, validates, builds and installs clean, and still ships a
- * bundle with no floor. The stack's own declared default locale is the wrong
- * answer whenever it is not spelled `en-US`.
+ * ⭐ The CONSISTENT thing an author writes, a stack declaring
+ * `defaultLocale: 'en'` whose English row says `locale: 'en'`, validates,
+ * builds and installs clean. Over the built-in loader, on a host whose i18n
+ * service answers that declared fallback, it reaches every recipient; behind
+ * a replacement loader, or on a host that declares no fallback, it still has
+ * no floor. This report reads the bundle alone, so it fires for that shape
+ * whichever host serves it: `en-US` is the one rung every loader retries.
  *
  * ## Posture — advisory, and deliberately so
  *
@@ -6030,15 +6038,17 @@ function warnEmailTemplateLocaleFloor(data: ObjectStackDefinition): void {
     warnedEmailTemplateFloors.add(key);
     console.warn(
       `defineStack: emailTemplates '${name}' carries rows for ${declared.map((t) => `'${t}'`).join(', ')} ` +
-      `but none tagged '${EMAIL_TEMPLATE_FLOOR_LOCALE}', so this bundle has no fallback floor for a ` +
-      `send that names a locale. sendTemplate matches (name, locale) exactly and retries only the ` +
-      `literal '${EMAIL_TEMPLATE_FLOOR_LOCALE}' — there is no language-subtag folding, so every ` +
-      `recipient locale this bundle does not carry a row for raises TEMPLATE_NOT_FOUND, which is ` +
-      `permanent (dead-letter, no retry). A send naming NO locale does not fail: it drops to this ` +
-      `bundle's lowest tag and renders that silently, so one gap is loud for some recipients and ` +
-      `invisible for others. Your stack's own i18n.defaultLocale is the wrong tag here unless ` +
-      `it is spelled '${EMAIL_TEMPLATE_FLOOR_LOCALE}': tag the English row '${EMAIL_TEMPLATE_FLOOR_LOCALE}' ` +
-      `and keep the other tags beside it.`,
+      `but none tagged '${EMAIL_TEMPLATE_FLOOR_LOCALE}', so this bundle has no fallback floor that ` +
+      `holds for every send naming a locale. With the built-in template loader such a send folds its ` +
+      `locale against these rows (exact, case-insensitive, base language, variant expansion), then ` +
+      `tries the stack's declared fallback locale (i18n.fallbackLocale, else defaultLocale) folded ` +
+      `the same way; a replacement TemplateLoader matches exactly and retries only ` +
+      `'${EMAIL_TEMPLATE_FLOOR_LOCALE}'. When no rung lands on a row the send raises ` +
+      `TEMPLATE_NOT_FOUND, which is permanent (dead-letter, no retry). A send naming NO locale does ` +
+      `not fail: it drops to this bundle's lowest tag and renders that silently, so one gap is loud ` +
+      `for some recipients and invisible for others. '${EMAIL_TEMPLATE_FLOOR_LOCALE}' is the one rung ` +
+      `every loader retries: tag the English row '${EMAIL_TEMPLATE_FLOOR_LOCALE}' and keep the other ` +
+      `tags beside it.`,
     );
   }
 }