@@ -0,0 +1,24 @@
+---
+'@objectstack/spec': minor
+---
+
+Email templates: say where the `en-US` fallback floor is, and report a bundle that has none.
+
+`IEmailService.sendTemplate` matches `(name, locale)` exactly and retries exactly one rung —
+the literal `en-US`. 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. An app declaring `i18n.defaultLocale: 'en'` and authoring `locale: 'en'` has
+done the consistent thing throughout and still shipped a bundle with no floor — and it
+validated, built and installed clean.
+
+- `EmailTemplateDefinitionSchema.locale`'s `describe` and TSDoc now state the exact match, the
+  single literal `en-US` rung, the absence of folding, and that the stack's own declared default
+  locale is the wrong tag whenever it is not spelled `en-US`.
+- New exported `EMAIL_TEMPLATE_FLOOR_LOCALE` names that tag once: it is both the schema default
+  and the resolver's sole retry rung.
+- `defineStack` now reports (advisory `console.warn`, warn-once per bundle) an `emailTemplates`
+  bundle that carries rows for the stack's own `i18n.supportedLocales` but none tagged `en-US`.
+
+Advisory only — no accept set moves. The stack still parses and is returned unchanged; the
+resolver's ladder is unchanged.
@@ -44,7 +44,7 @@ const result = EmailTemplateDefinitionSchema.parse(data);
 | **name** | `string` | ✅ | Template identifier (dotted snake_case) |
 | **label** | `string` | ✅ | Display label |
 | **category** | `Enum<'auth' \| 'notification' \| 'workflow' \| 'marketing' \| 'custom'>` | optional (default: `"custom"`) |  |
-| **locale** | `string` | optional (default: `"en-US"`) | BCP-47 locale (e.g. en-US, zh-CN) |
+| **locale** | `string` | optional (default: `"en-US"`) | BCP-47 locale (e.g. en-US, zh-CN) — the bundle key the resolver matches EXACTLY, with one retry rung: the literal `en-US`. No language-subtag folding, so `en` and `en-US` are different bundles and neither reaches the other. A bundle with no `en-US` row therefore has no fallback floor: any recipient locale it does not carry a row for raises TEMPLATE_NOT_FOUND, which is permanent — the delivery dead-letters with no retry. Your stack's own `i18n.defaultLocale` is the wrong tag here unless it is spelled `en-US`. |
 | **subject** | `string` | ✅ | Subject template |
 | **bodyHtml** | `string` | ✅ | HTML body template |
 | **bodyText** | `string` | optional | Plain-text body template (auto-derived from HTML when omitted) |
 
@@ -200,6 +200,7 @@
     "Doc (type)",
     "DocSchema (const)",
     "DocTranslation (type)",
+    "EMAIL_TEMPLATE_FLOOR_LOCALE (const)",
     "ENVIRONMENT_ARTIFACT_SCHEMA_VERSION (const)",
     "EmailAddressConfig (type)",
     "EmailAddressConfigSchema (const)",
 
@@ -194,6 +194,7 @@
     "Doc": "src/system/doc.zod.ts#Doc (type)",
     "DocSchema": "src/system/doc.zod.ts#DocSchema (const)",
     "DocTranslation": "src/system/doc.zod.ts#DocTranslation (type)",
+    "EMAIL_TEMPLATE_FLOOR_LOCALE": "src/system/email-template.zod.ts#EMAIL_TEMPLATE_FLOOR_LOCALE (const)",
     "ENVIRONMENT_ARTIFACT_SCHEMA_VERSION": "src/system/environment-artifact.zod.ts#ENVIRONMENT_ARTIFACT_SCHEMA_VERSION (const)",
     "EmailAddressConfig": "src/system/email-config.zod.ts#EmailAddressConfig (type)",
     "EmailAddressConfigSchema": "src/system/email-config.zod.ts#EmailAddressConfigSchema (const)",
 
@@ -0,0 +1,148 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// #17614 — an `emailTemplates` bundle tagged with the stack's OWN
+// `i18n.defaultLocale` has no fallback floor.
+//
+// Measured before this landed, on an unmodified tree: a stack declaring
+// `defaultLocale: 'en'`, `supportedLocales: ['en','zh-CN','ja-JP','es-ES']`
+// and one row per those tags parsed with ZERO warnings and ZERO errors, and
+// 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 retries exactly one rung, the literal `en-US`; there is no
+// language-subtag folding, and 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.
+//
+// These pin the diagnostic ADVISORY: every case asserts the parse still
+// succeeds and the stack comes back unchanged. The diagnostic narrows what
+// passes SILENTLY; it moves no accept set.
+
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { defineStack } from './stack.zod';
+import { EmailTemplateDefinitionSchema, EMAIL_TEMPLATE_FLOOR_LOCALE } from './system/email-template.zod';
+
+const MANIFEST = { id: 'acme', name: 'acme', version: '1.0.0', namespace: 'acme', type: 'app' as const };
+
+const tpl = (locale: string | undefined, name = 'acme.welcome') => ({
+  name,
+  label: `Welcome ${locale ?? '(default)'}`,
+  ...(locale === undefined ? {} : { locale }),
+  subject: `[${locale ?? 'default'}] Hi {{name}}`,
+  bodyHtml: `<p>[${locale ?? 'default'}] Hi {{name}}</p>`,
+});
+
+const stack = (tpls: unknown[], i18n?: unknown) => ({
+  manifest: MANIFEST,
+  ...(i18n === undefined ? {} : { i18n }),
+  emailTemplates: tpls,
+}) as never;
+
+const THE_TRAP = { defaultLocale: 'en', supportedLocales: ['en', 'zh-CN', 'ja-JP', 'es-ES'], fallbackLocale: 'en' };
+
+/** Run `defineStack` capturing every `console.warn` it emits. */
+function warningsOf(config: unknown): { warns: string[]; value: ReturnType<typeof defineStack> } {
+  const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+  try {
+    const value = defineStack(config as never);
+    return { warns: spy.mock.calls.map((c) => c.map(String).join(' ')), value };
+  } finally {
+    spy.mockRestore();
+  }
+}
+
+const floorWarns = (warns: string[]) => warns.filter((w) => w.includes('no fallback floor'));
+
+afterEach(() => {
+  // The reporter is warn-once per (bundle, tags); each test authors its own
+  // tag set so the cache cannot mask a case, but keep runs independent.
+  vi.restoreAllMocks();
+});
+
+describe('#17614 — the floor tag is one named constant, not two spellings', () => {
+  it('is the schema default for `locale`, so a row that omits the key HAS the floor', () => {
+    expect(EMAIL_TEMPLATE_FLOOR_LOCALE).toBe('en-US');
+    const parsed = EmailTemplateDefinitionSchema.parse({
+      name: 'acme.welcome', label: 'W', subject: 's', bodyHtml: '<p>b</p>',
+    });
+    expect(parsed.locale).toBe(EMAIL_TEMPLATE_FLOOR_LOCALE);
+  });
+
+  it("states the two facts an author needs in the published `describe` — the floor tag and what a miss costs", () => {
+    // The `describe` is the authoring surface (it lands in the generated
+    // reference docs). The rule used to live only in a docstring two packages
+    // away, under a heading about a different subject — which is the finding.
+    const text = String(EmailTemplateDefinitionSchema.shape.locale.description ?? '');
+    expect(text).toContain('en-US');
+    expect(text).toContain('TEMPLATE_NOT_FOUND');
+  });
+});
+
+describe('#17614 — defineStack reports a bundle with no `en-US` floor', () => {
+  it('reports the trap: every supportedLocales tag authored, none of them the floor', () => {
+    const { warns, value } = warningsOf(stack(['en', 'zh-CN', 'ja-JP', 'es-ES'].map((l) => tpl(l)), THE_TRAP));
+    const hits = floorWarns(warns);
+    expect(hits).toHaveLength(1);
+    expect(hits[0]).toContain("emailTemplates 'acme.welcome'");
+    expect(hits[0]).toContain("none tagged 'en-US'");
+    expect(hits[0]).toContain('TEMPLATE_NOT_FOUND');
+    // ADVISORY — the accept set did not move: the stack parsed and came back
+    // carrying exactly the tags the author wrote.
+    expect(value.emailTemplates?.map((t) => t.locale)).toEqual(['en', 'zh-CN', 'ja-JP', 'es-ES']);
+  });
+
+  it('reports a single-row bundle tagged with the stack default — the consistent thing an author writes', () => {
+    const { warns, value } = warningsOf(stack([tpl('en')], THE_TRAP));
+    expect(floorWarns(warns)).toHaveLength(1);
+    expect(value.emailTemplates).toHaveLength(1);
+  });
+
+  it('reports each bundle separately, by name', () => {
+    const { warns } = warningsOf(stack(
+      [tpl('en', 'acme.welcome'), tpl('zh-CN', 'acme.welcome'), tpl('en', 'acme.reset')],
+      THE_TRAP,
+    ));
+    const hits = floorWarns(warns);
+    expect(hits).toHaveLength(2);
+    expect(hits.some((w) => w.includes("'acme.welcome'"))).toBe(true);
+    expect(hits.some((w) => w.includes("'acme.reset'"))).toBe(true);
+  });
+});
+
+describe('#17614 — and stays silent where the bundle HAS a floor (the controls)', () => {
+  it('silent when the bundle carries an en-US row beside the supported tags', () => {
+    const { warns, value } = warningsOf(stack(
+      ['en-US', 'zh-CN', 'ja-JP', 'es-ES'].map((l) => tpl(l)), THE_TRAP,
+    ));
+    expect(floorWarns(warns)).toEqual([]);
+    expect(value.emailTemplates).toHaveLength(4);
+  });
+
+  it('silent when the row omits `locale` entirely — the schema default already IS the floor', () => {
+    // Measured, by ablation: moving the call pre-parse does NOT break this —
+    // the reader mirrors the schema default for a missing key, so the two
+    // agree and the case is silent either way. The pin is the behaviour (an
+    // omitted `locale` is never reported), not the call site.
+    const { warns, value } = warningsOf(stack([tpl(undefined)], THE_TRAP));
+    expect(floorWarns(warns)).toEqual([]);
+    expect(value.emailTemplates?.[0]?.locale).toBe(EMAIL_TEMPLATE_FLOOR_LOCALE);
+  });
+
+  it('silent when the stack declares no supportedLocales to measure against', () => {
+    const { warns } = warningsOf(stack([tpl('en')]));
+    expect(floorWarns(warns)).toEqual([]);
+  });
+
+  it('silent when no authored tag is one this stack claims to support', () => {
+    const { warns } = warningsOf(stack([tpl('fr-CA')], { defaultLocale: 'en', supportedLocales: ['en'] }));
+    expect(floorWarns(warns)).toEqual([]);
+  });
+
+  it('warns once for one bundle, however many times the same stack is defined', () => {
+    const first = warningsOf(stack([tpl('pt-BR')], { defaultLocale: 'pt-BR', supportedLocales: ['pt-BR'] }));
+    const second = warningsOf(stack([tpl('pt-BR')], { defaultLocale: 'pt-BR', supportedLocales: ['pt-BR'] }));
+    expect(floorWarns(first.warns)).toHaveLength(1);
+    expect(floorWarns(second.warns)).toEqual([]);
+  });
+});
@@ -60,7 +60,7 @@ import { CubeSchema } from './data/analytics.zod';
 import { WebhookSchema } from './automation/webhook.zod';
 
 // System Protocol (additional)
-import { EmailTemplateDefinitionSchema } from './system/email-template.zod';
+import { EmailTemplateDefinitionSchema, EMAIL_TEMPLATE_FLOOR_LOCALE } from './system/email-template.zod';
 import { DocSchema } from './system/doc.zod';
 import { BookSchema } from './system/book.zod';
 
@@ -2663,6 +2663,86 @@ function warnUnknownAuthoringKeys(raw: unknown): void {
   }
 }
 
+const warnedEmailTemplateFloors = new Set<string>();
+
+/**
+ * Report an `emailTemplates` bundle that carries rows for this stack's own
+ * `i18n.supportedLocales` but none tagged {@link EMAIL_TEMPLATE_FLOOR_LOCALE}.
+ *
+ * ## What goes wrong without this
+ *
+ * `IEmailService.sendTemplate` matches `(name, locale)` EXACTLY and retries
+ * exactly one rung — the literal `en-US`. 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` 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 legal tag.
+ *
+ * ⭐ 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`.
+ *
+ * ## Posture — advisory, and deliberately so
+ *
+ * Same seam and same posture as {@link warnUnknownAuthoringKeys}: this only
+ * WARNS. It moves no accept set — the parse above already succeeded and its
+ * result is returned unchanged — because refusing an `emailTemplates` shape
+ * that ships today would be a behaviour change on an authoring surface, which
+ * is a scheduled migration rather than something to slip in behind a lint. The
+ * resolver's ladder is fenced by a standing ruling and is NOT touched here: the
+ * remedy this points at is the bundle.
+ *
+ * Runs post-parse, on the value the schema produced. `locale` defaults to
+ * `en-US`, so a row that omits the key entirely already has the floor and must
+ * not be reported — the reader below mirrors that default rather than relying
+ * on the call site for it, so the two agree wherever this is called from.
+ * Warn-once per bundle, keyed by name plus the tags it actually carries.
+ */
+function warnEmailTemplateLocaleFloor(data: ObjectStackDefinition): void {
+  const supported = data.i18n?.supportedLocales;
+  if (!Array.isArray(supported) || supported.length === 0) return;
+  const templates = data.emailTemplates;
+  if (!Array.isArray(templates) || templates.length === 0) return;
+
+  const supportedSet = new Set(supported.map((l) => String(l)));
+
+  /** name → the locale tags that bundle carries, in authored order. */
+  const bundles = new Map<string, string[]>();
+  for (const tpl of templates) {
+    const name = typeof tpl?.name === 'string' ? tpl.name : '';
+    if (!name) continue;
+    const locale = typeof tpl?.locale === 'string' ? tpl.locale : EMAIL_TEMPLATE_FLOOR_LOCALE;
+    const tags = bundles.get(name);
+    if (tags) tags.push(locale);
+    else bundles.set(name, [locale]);
+  }
+
+  for (const [name, tags] of bundles) {
+    if (tags.includes(EMAIL_TEMPLATE_FLOOR_LOCALE)) continue;
+    const declared = tags.filter((t) => supportedSet.has(t));
+    if (declared.length === 0) continue;
+
+    const key = `${name} ${tags.join(',')}`;
+    if (warnedEmailTemplateFloors.has(key)) continue;
+    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. ` +
+      `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). 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.`,
+    );
+  }
+}
+
 export function defineStack(
   config: ObjectStackDefinitionInput,
   options?: DefineStackOptions,
@@ -2757,6 +2837,11 @@ export function defineStack(
     throw new StackTriggerCapabilityRequiredError(`${header}\n\n${lines.join('\n')}`, triggerErrors);
   }
 
+  // Post-parse and advisory: the stack is valid and is returned unchanged.
+  // `locale` carries a default, so this has to run AFTER the parse or a row
+  // that omits the key would read as a missing floor it actually has.
+  warnEmailTemplateLocaleFloor(data);
+
   return mergeActionsIntoObjects(data);
 }