@@ -0,0 +1,10 @@
+---
+'@objectstack/metadata-core': patch
+---
+
+docs(metadata-core): the `ITEM_KEY_DISCRIMINATORS` docblock no longer says email template resolution is exact with no language-subtag folding
+
+Clause-②: no
+Metadata-protocol: none
+
+The docblock ships in the package's type declarations, and it still described the exact `(name, locale)` ladder: the named tag matched exactly, then `en-US`. Over the built-in registry template loader a named locale is now folded against the bundle's tags, then the stack's declared fallback locale is tried, then `en-US`. The docblock now cites `SendTemplateInput.locale` in `@objectstack/spec` as the ladder of record instead of restating its rungs, and keeps the point the table rests on: every rung loads one row at one tag exactly, so `en` and `en-US` stay two distinct rows of one bundle. No code changed.
@@ -244,23 +244,41 @@ export const passwordResetZh = defineEmailTemplateDefinition({
 });
 ```
 
-`sendTemplate({ template, locale })` walks a fixed ladder — exact, then default,
-then deterministic:
-
-1. **`locale`, matched exactly.** There is **no language-prefix matching**:
-   `zh` does not resolve `zh-CN`, and `en` does not resolve `en-US`. Author the
-   tags your callers actually pass.
-2. **`en-US`** — which is also where a call that omits `locale` *starts*, so
-   "no locale" means the default rather than an arbitrary row.
-3. Only for a call that named **no** locale, and only when the bundle has no
-   `en-US` row at all: the bundle's lowest locale tag. A single-locale tenant
-   keeps rendering, and renders identically on every boot.
-
-A call that names a locale with no exact row and no `en-US` row fails with
-`TEMPLATE_NOT_FOUND` — it does not silently fall through to another language.
-That rung ordering exists because one seam once answered "whichever row the
-store yields first" and a no-locale send rendered `zh-CN` out of an
-`en-US` + `zh-CN` bundle.
+The template name is matched exactly; only the locale member is resolved, by
+the ladder 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. Resolution is deterministic, never "whichever row the store
+yields first". The ladder of record is `SendTemplateInput.locale` in
+`packages/spec/src/contracts/email-service.ts`; this section copies it.
+
+A call that **names** a locale, over the built-in registry template loader (the
+one `EmailServicePlugin` wires), walks:
+
+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.
 
 ## Reaching a template
 
 
@@ -897,7 +897,7 @@
       "title": "Email templates resolve from the registry (no sys_email_template row since ADR-0131 D6/D10), resolve (name, locale) with en-US fallback, render {{path}} holes, gate on required variables and active:false, survive admin edits across redeploys — and the raw POST /api/v1/email/send door authenticates, requires manage_platform_settings, bounds sentBy, from, headers, organizationId and identityMail, refuses anonymous, and 400s malformed input",
       "since": "v15",
       "status": "active",
-      "revision": 12,
+      "revision": 13,
       "priority": "P2",
       "surface": "mixed",
       "fixtures": {
@@ -914,7 +914,7 @@
         ]
       },
       "variants": [
-        "locale resolution: exact (name, locale) match / en-US fallback / two-locale bundle picking by recipient locale",
+        "locale resolution: exact (name, locale) match / a named locale folded to a bundle member (zh → zh-CN) / the declared fallback locale, then en-US / two-locale bundle picking by recipient locale",
         "body: bodyHtml + bodyText authored / bodyText omitted (service derives text from HTML — omitted from the ROW, not nulled)",
         "gate: active:false → TEMPLATE_INACTIVE",
         "gate: missing required variable → fail-fast (requireVars)",
@@ -926,7 +926,7 @@
         "drive a send with full data ({ title, project }) through the scratch notify flow of knownGaps[1] (POST /api/v1/automation; channels ['email'], template, templateData; fired through its api trigger); capture the rendered subject/body from the sys_email row it lands (the dev log transport logs no body)",
         "drive a send MISSING the required `title`; capture the fast failure",
         "make the template inactive (a Studio save of the item with active:false, or a scratch template authored active:false) and send; capture the TEMPLATE_INACTIVE error",
-        "author the zh-CN twin; send to a zh-CN-locale recipient and to an unmatched-locale recipient; capture which row rendered each",
+        "author the zh-CN twin; send to a zh-CN-locale recipient, to a zh-locale recipient (a tag the bundle folds) and to a recipient whose language the bundle lacks (e.g. ja-JP); capture which row rendered each. The showcase declares i18n fallbackLocale 'en' (examples/app-showcase/objectstack.config.ts), which folds to the en-US row",
         "author a template with fromOverride + replyTo and verify both on the outbound message. fromOverride is an object { name?, address } with address an email (EmailAddressInlineSchema, packages/spec/src/system/email-template.zod.ts) and replyTo a plain address string; a string fromOverride is refused at save, 422 INVALID_METADATA 'expected object'",
         "edit the template wording as an admin in Studio (an environment overlay over the declared item), redeploy/reboot, and re-read the served item over GET /api/v1/meta/email_template/showcase_task_done_email — the admin's wording must still be served",
         "on the WRITABLE showcase copy (fixtures.requires[3]), edit the DECLARED source template and metadata-reload WITHOUT a reboot, then GET /api/v1/meta/email_template/<name> — the registry serves the edited item (email_template is allowRuntimeCreate:true; the plugin subscribes to metadata changes). Keep the reboot out of it: under os dev's default watcher a declared-source save recompiles AND restarts the server (packages/cli/src/commands/dev.ts, --restart defaults on), which proves nothing about a reload. Compile into the running copy's artifact with objectstack compile --output COPY/dist/objectstack.json, or boot the copy with os dev --no-restart (the watcher then only rebuilds the artifact), and read the listener's PID before and after (lsof -ti tcp:PORT): an unchanged PID is part of the evidence, and a changed one means this half was not driven. On the stock read-only showcase this half is not drivable: record it partial, as QA run #23166 did",
@@ -954,9 +954,9 @@
           "evidence": "the error"
         },
         {
-          "clause": "(name, locale) resolution is an EXACT match with no language-subtag folding — two rows with one name are an i18n bundle, each reachable ONLY from its own exact tag; a call naming a locale with no row retries the single literal rung en-US and then raises TEMPLATE_NOT_FOUND, and a call naming no locale starts at en-US",
+          "clause": "(name, locale) resolution walks the ladder of record, SendTemplateInput.locale in packages/spec/src/contracts/email-service.ts: two rows with one name are an i18n bundle, the name is matched exactly and only the locale member is resolved, and every rung loads one row at one tag exactly, so en and en-US stay two distinct rows (folding chooses which row is read, it never merges two). A call that NAMES a locale, over the built-in registry template loader, walks: (1) this locale, folded against the bundle's locale tags by resolveBundleLocale — 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 (II18nService.getFallbackLocale(): i18n.fallbackLocale, else defaultLocale), folded the same way, skipped when none is declared; (3) en-US, exactly; (4) TEMPLATE_NOT_FOUND, which is permanent. A rung that resolves to a tag already tried is skipped; a replacement TemplateLoader keeps the exact ladder. A call that names no locale starts at en-US exactly, with no fold and no declared fallback, then takes the loader's own no-locale answer (the built-in loader: the bundle's lowest locale tag)",
           "oracle": "log",
-          "verify": "the zh-CN recipient gets the zh-CN render; a recipient whose locale has no row (e.g. zh) gets the en-US row, NOT the zh-CN one",
+          "verify": "the zh-CN recipient gets the zh-CN render; the zh recipient gets the zh-CN render too (variant expansion); a recipient whose language the bundle lacks (e.g. ja-JP) gets the en-US row, through the showcase's declared fallback en folding to en-US. A zh recipient getting the en-US row is the FAIL",
           "evidence": "the two renders"
         },
         {
@@ -994,7 +994,7 @@
       ],
       "automated": {
         "kind": "e2e",
-        "ref": "packages/qa/dogfood/test/email-template-materialization.dogfood.test.ts — on its own fixture package (auth.password_reset), not the showcase template: acceptance[0] (the registry serves the authored item beside the built-in and sendTemplate renders it, the subject exact and the body by containment), and halves only of acceptance[3] (the exact zh-CN member is reachable; not the no-folding case or the TEMPLATE_NOT_FOUND end) and of acceptance[5] (a Studio save sends on the next mail with no restart; not redeploy survival, not the declared-source reload). + packages/qa/dogfood/test/email-template-overlay-survives-boot.dogfood.test.ts ('after a cold boot the metadata door and the rendered mail both carry the admin's wording') — acceptance[5]'s redeploy-survival half on the showcase. + packages/qa/dogfood/test/email-template-two-locales-survive-boot.dogfood.test.ts ('control: a locale nobody saved keeps the package ladder') — acceptance[3]'s en-US rung for a locale with no row (ja-JP). acceptance[6] rests on no pin; acceptance[7]'s capability, sentBy, sender, headers-shape, organization and identity-mail bounds are pinned below the e2e layer by packages/rest/src/email-send-door-bounds.test.ts (the real Hono transport over a contract-typed mail-service double — the dev-transport landing and the sys_email row stay hand-driven), and acceptance[1], [2] and [4] on one below their oracle's layer: packages/plugins/plugin-email/src/send-template.test.ts drives EmailService over a fake loader and a capture transport, asserting MISSING_VARIABLES (acceptance[1]), TEMPLATE_INACTIVE (acceptance[2]) and the fromOverride and derived text (acceptance[4]) at unit — whether the error names the variable, the registry-resolved inactive item, replyTo and the row stay hand-driven: drive them by hand"
+        "ref": "packages/qa/dogfood/test/email-template-materialization.dogfood.test.ts — on its own fixture package (auth.password_reset), not the showcase template: acceptance[0] (the registry serves the authored item beside the built-in and sendTemplate renders it, the subject exact and the body by containment), and halves only of acceptance[3] (the exact zh-CN member is reachable; not the fold rungs, the declared-fallback rung or the TEMPLATE_NOT_FOUND end, which packages/plugins/plugin-email/src/template-locale-fold.test.ts pins at unit and template-locale-fold.integration.test.ts on a booted EmailServicePlugin, below this oracle's layer) and of acceptance[5] (a Studio save sends on the next mail with no restart; not redeploy survival, not the declared-source reload). + packages/qa/dogfood/test/email-template-overlay-survives-boot.dogfood.test.ts ('after a cold boot the metadata door and the rendered mail both carry the admin's wording') — acceptance[5]'s redeploy-survival half on the showcase. + packages/qa/dogfood/test/email-template-two-locales-survive-boot.dogfood.test.ts ('control: a locale nobody saved keeps the package ladder') — acceptance[3]'s en-US rung for a locale with no row (ja-JP). acceptance[6] rests on no pin; acceptance[7]'s capability, sentBy, sender, headers-shape, organization and identity-mail bounds are pinned below the e2e layer by packages/rest/src/email-send-door-bounds.test.ts (the real Hono transport over a contract-typed mail-service double — the dev-transport landing and the sys_email row stay hand-driven), and acceptance[1], [2] and [4] on one below their oracle's layer: packages/plugins/plugin-email/src/send-template.test.ts drives EmailService over a fake loader and a capture transport, asserting MISSING_VARIABLES (acceptance[1]), TEMPLATE_INACTIVE (acceptance[2]) and the fromOverride and derived text (acceptance[4]) at unit — whether the error names the variable, the registry-resolved inactive item, replyTo and the row stay hand-driven: drive them by hand"
       },
       "source": [
         "packages/spec/src/system/email-template.zod.ts#fromOverride (requireds, dotted-name regex, aliases #5013, variables/required, fromOverride/replyTo/active)",
@@ -1078,6 +1078,12 @@
           "date": "2026-11-01",
           "change": "Two QA run #28656 (W3-RT) findings. knownGaps[1]'s recipe was incomplete. #28656 met three refusals on the way: an inline title/message beside template (400), type 'autolaunched' at POST /api/v1/automation/NAME/trigger (403), and type 'api' with no config.secret or secretRef (400). It now spells a type:'api' flow with start config {triggerType:'api', hookId, secret}, a notify node with channels ['email'], template and templateData and no inline title/message, fired as the admin. Source: NotifyConfigSchema's template/inline exclusivity (io-node-config.zod.ts) and validateApiTriggerSecret (flow-registration-checks.ts). The 403's rule is read from flow-start-admission.ts, which refuses a runAs: 'system' self-triggered type. That #28656's flow declared runAs: 'system' is not confirmed from source, and the 400 and 403 statuses are #28656's readings. steps[7] said 'metadata-reload WITHOUT a reboot' on a copy whose os dev watcher restarts on every save (dev.ts --restart, default on). It now names objectstack compile --output into the running copy's dist/objectstack.json or --no-restart, and requires an unchanged listener PID as evidence. No clause changed. Re-verified against source at base 1c5b1773ec. Wave anchor #27377, wave-3 accuracy slice S10 (#28701); findings parked in anchor comment 6557904764",
           "ref": "#28656"
+        },
+        {
+          "revision": 13,
+          "date": "2026-11-02",
+          "change": "CORRECTION: acceptance[3] said (name, locale) resolution is an EXACT match with no language-subtag folding, and its verify line scored a zh recipient getting the en-US row as the pass. Since #28880 a named locale, over the built-in registry template loader, is folded against the bundle's tags by resolveBundleLocale, then the stack's declared fallback locale is tried folded the same way, then en-US, then TEMPLATE_NOT_FOUND, so a run against main scored the clause wrong. The clause now copies the ladder of record, SendTemplateInput.locale in packages/spec/src/contracts/email-service.ts, and keeps en and en-US as two rows of one bundle; the verify line and steps[4] add a zh recipient (folds to zh-CN) and a recipient whose language the bundle lacks (declared fallback en folds to en-US); variants[0] names the fold and fallback rungs; automated.ref no longer calls the uncovered half 'the no-folding case' and names the plugin-email fold pins below the oracle's layer. Read from source at base 8ca9dd7b",
+          "ref": "#29032"
         }
       ]
     },
 
@@ -10,13 +10,14 @@
  * an i18n bundle, one row per locale tag — and its header says a template
  * "is resolved by `(name, locale)`".
  *
- * That resolution is exact. `SendTemplateInput.template` in
- * `packages/spec/src/contracts/email-service.ts` rules out any best match and
- * any language-subtag folding, and `SendTemplateInput.locale` there is the
- * ladder of record: the named tag matched exactly, then the literal `en-US`,
- * then — only for a call that named no locale, and only when the bundle has
- * no `en-US` row — the bundle's lowest locale tag. Both are cited rather than
- * quoted, so a rewording on the spec side cannot strand a copy here.
+ * The pair stays the identity whichever row a send reads.
+ * `SendTemplateInput.template` in `packages/spec/src/contracts/email-service.ts`
+ * matches the name exactly and resolves only the locale member, by the ladder
+ * of record on `SendTemplateInput.locale` there. 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. The ladder's rungs
+ * are cited rather than quoted, so a rewording on the spec side cannot strand
+ * a copy here.
  *
  * Every layer that keys metadata by `name` therefore has to agree on ONE
  * answer to "what else is part of this type's identity?", or a bundle survives