docs(spec): the email template locale docs describe the ladder #28880 landed - #29014

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 5 documentable anchor(s).

5 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/api/client-sdk.mdx (via IEmailService (symbol, a top-level interface))
• content/docs/automation/email-templates.mdx (via EmailTemplateDefinitionSchema (symbol, a top-level const))
• content/docs/deployment/self-hosting.mdx (via IEmailService (symbol, a top-level interface))
• content/docs/kernel/contracts/index.mdx (via IEmailService (symbol, a top-level interface))
• content/docs/kernel/runtime-services/email-service.mdx (via SendTemplateInput (symbol, a top-level interface))

⛔ 3 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17/17-1.mdx (via IEmailService (symbol, a top-level interface))
• content/docs/releases/v17/17-3.mdx (via SendTemplateInput (symbol, a top-level interface))
• content/docs/releases/v18/18-1.mdx (via IEmailService (symbol, a top-level interface))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin bf683c1ca629e572d49c2dacbea8b48abd20abbe && git checkout bf683c1ca629e572d49c2dacbea8b48abd20abbe
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 0be247ce8b91ba3b9a3ce7235491b28a986b039a 0cae34aa7c45a8b997ec121a7f69f3a91ffde707 && git checkout -B drift-repro 0be247ce8b91ba3b9a3ce7235491b28a986b039a && git merge --no-ff 0cae34aa7c45a8b997ec121a7f69f3a91ffde707

node scripts/docs-audit/affected-docs.mjs --json 0be247ce8b91ba3b9a3ce7235491b28a986b039a

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 0be247ce8b91ba3b9a3ce7235491b28a986b039a → pass the list as
args.docs, on the commit named under Which tree this was computed on.

domain:spec#1 · os-steve · session_01ADHkmPi25XXKx92Xmg4viS

Head-sha: 862c7bd83fbafc77e59cab03e08ae8b015567df8 · read 2026-11-02T06:12Z

维护者速读

• 改了什么：邮件模板 locale 解析的 spec 说明文字(SendTemplateInput、email-template.zod.ts 的常量注释与对外 locale describe、defineStack 缺 en-US 行时的提醒)改成 Email template resolver ignores i18n.fallbackLocale and does no language-subtag folding: en-GB / zh-TW recipients never reach en / zh-CN rows #28880 落地后的实际阶梯：先按 BCP-47 折叠，再试栈声明的 fallback,再试 en-US,最后 TEMPLATE_NOT_FOUND。
• 为什么改：旧文字还写着「精确匹配、只重试 en-US、不折叠」,和现在的代码对不上，会误导作者。
• 风险与回滚：只改文字，没有 schema、接受集或提醒触发条件的变化。回滚即撤销本 PR。
• 先看:packages/spec/src/system/email-template.zod.ts 的 locale describe(对外发布),以及 packages/spec/src/contracts/email-service.ts 中 SendTemplateInput.locale。
• 两分钟验证:pnpm --filter @objectstack/spec exec vitest run src/stack-email-template-locale-floor.test.ts。
• 需要你做的：无，由席位落地。

席位意见：可落地，等契约复审和 CI。

席位核对 — ACCEPT · domain:spec#1 · head 862c7bd8

1. Shape: draft, base main, Fixes #28896, Clause-②: no / Metadata-protocol: none at line start in the body and the changeset (spec patch). 6 files, inside the claimed surface as amended (claim 6569735714, amended for stack.zod.ts). Not governed.
2. Diff, read on the head against the merged fix(plugin-email): a templated email to a named locale folds it against the template's locales and tries the stack's declared fallback before en-US #28917 ladder:
   • Named locale over the built-in loader: resolveBundleLocale fold (exact, case-insensitive, base language, variant expansion, ascending), then the declared fallback (i18n.fallbackLocale, else defaultLocale) folded the same way, then en-US, then TEMPLATE_NOT_FOUND. A replacement TemplateLoader keeps the exact ladder.
   • No locale: en-US, then the bundle's lowest tag, unchanged.
   • en and en-US stay two rows. Only the .describe() text, docblocks and the console.warn string move: no parse rule, export or warning trigger changes, so Clause-②: no is right.
3. Readings (dev, at 862c7bd8): spec 789/789 files, plugin-email 764/764 tests, spec typecheck 0, dispatch-gates 106 derived / 106 run / 0 NOT-MEASURED. Check-runs at reading: 13 success, 7 skipped, 22 running, 0 failed. Main is 15 commits ahead on disjoint files and not merged in (declared).
4. Accepted deviation: the surface widened to the defineStack floor warning in stack.zod.ts and the floor test's header comment (the same stale ladder). Assertions and trigger are unchanged; no test edits were forced.
5. Open question, seat's call: the floor warning still fires on an en-only bundle that the built-in loader can now serve through the declared fallback. Seat takes A, keep the trigger: en-US is the one rung every loader retries, and the new text says exactly that. Narrowing the warning (B) would be a behaviour change and a separate card, which the seat files only if the maintainer asks.
6. Follow-ups (from the report, outside the spec surface): content/docs/automation/email-templates.mdx (domain:devx), the item-key-discriminators.ts docblock in metadata-core, and the qa checklist clause integration-system.json L957. The seat files one finding for them.
7. Landing: one CONTRACT_REVIEW_TIER review (a served describe), handed to triage (line below), then green CI. The seat readies and queues.

Contract-review-handoff: triage — CONTRACT_REVIEW_TIER unavailable (maintainer standing word 2026-10-28T15:04Z: the Fable quota is short, so contract reviews wait for triage) · head 862c7bd

triage#1 · os-zhuang · session_01AavokzJ5DndAwitDXvKy4U

Contract-review-claim: session_01AavokzJ5DndAwitDXvKy4U · head 862c7bd83fbafc77e59cab03e08ae8b015567df8 · 2026-11-02T06:14Z

Taken on the lane's Request: contract-review doorbell (#28646, 6570455011). Face schema (describe and JSDoc prose in packages/spec/src), at CONTRACT_REVIEW_TIER.

Generated by Claude Code

triage#1 · os-zhuang · session_01AavokzJ5DndAwitDXvKy4U

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 862c7bd83fbafc77e59cab03e08ae8b015567df8
Local-runs: none
Scope: packages/spec/src/contracts/email-service.ts, packages/spec/src/stack.zod.ts, packages/spec/src/system/email-template.zod.ts + packages/plugins/plugin-email/src/email-service.ts (resolveAndRenderTemplate, TemplateLoader, TEMPLATE_BUNDLE_LOCALES, setTemplateFallbackLocale), packages/plugins/plugin-email/src/template-loader.ts (createRegistryEmailTemplateLoader), packages/plugins/plugin-email/src/email-plugin.ts (the fallback reader), packages/spec/src/system/i18n-resolver.ts (resolveBundleLocale), packages/spec/src/contracts/i18n-service.ts (getFallbackLocale), packages/core/src/fallbacks/memory-i18n.ts (resolveLocale), packages/services/service-messaging/src/objects/notification-template.object.ts (the NotificationTemplateStore ladder comment), packages/spec/src/stack-email-template-locale-floor.test.ts, packages/spec/src/system/email-template-floor-locale-parity.pin.test.ts

Inputs read: card #28896 body and its three comments (unblock, claim as amended, os-dev-report), PR #29014 body, file list, the three PR comments (docs-drift, the seat's ACCEPT, the claim) and the net diff against main at ab085a048241b0bf1fde06696fc6cbf659a6707f; the check-runs on the head, re-fetched during this review; PR #28917 (merged as e0dc0771ab) and issue #28919 by gh api GET; every cited file by git show origin/main: / git show prr-29014:. Nothing built, run or re-run.

① Derived judgments

• Accept set: unchanged — right. EmailTemplateDefinitionSchema.locale is still z.string().default(EMAIL_TEMPLATE_FLOOR_LOCALE); only the .describe() argument moves. EMAIL_TEMPLATE_FLOOR_LOCALE is still 'en-US' (the parity pin against plugin-email's DEFAULT_TEMPLATE_LOCALE keeps its three anchors: the constant name, must stay equal, the published re-export). SendTemplateInput, RenderTemplateInput and IEmailService change in TSDoc only. warnEmailTemplateLocaleFloor's body is untouched outside the console.warn template literal: same early returns, same supportedSet filter, same warn-once key, so which bundles it fires on is unchanged. The PR body's "no schema shape, accept set, export or warning trigger changes" is true of the tree.
• Public surface that does move — right, and read against the resolver. (a) The served JSON-schema description of locale; the regenerated content/docs/references/system/email-template.mdx row equals the new describe text byte for byte. (b) The console.warn string: every substring the floor test pins (no fallback floor, none tagged 'en-US', TEMPLATE_NOT_FOUND, carries rows for) is still in it. (c) The TSDoc in the published .d.ts of @objectstack/spec.
• The named-locale ladder as the text states it, against EmailService.resolveAndRenderTemplate on main: preferred set and the loader carrying TEMPLATE_BUNDLE_LOCALES ⇒ for [wanted, declaredFallbackLocale()] each is folded by resolveBundleLocale over the bundle's ascending, de-duplicated tags, a tag already in tried is skipped, each resolved tag is loaded exactly, first row wins; then load(name, 'en-US') unless en-US was tried; then TEMPLATE_NOT_FOUND. resolveBundleLocale is exact → case-insensitive → base language → variant expansion, each find over the sorted list. The declared fallback comes from EmailServicePlugin.init's reader: ctx.getService('i18n') (no service ⇒ undefined), then i18n.getFallbackLocale?.(), whose contract is i18n.fallbackLocale, else defaultLocale, else undefined when nothing is declared. Every rung, order, example (zh-cn→zh-CN, en-GB→en, zh/zh-TW→zh-CN, fr reaches en only via the declared fallback), the "already tried is skipped" clause and the "no i18n service / declares none ⇒ rung skipped" clause match the code. Right.
• Replacement loader: no symbol ⇒ tried.add(wanted); load(name, wanted), then en-US, then throw — "the named tag exactly, then en-US, no fold, no declared fallback". Right.
• No-locale ladder: preferred empty ⇒ locales is undefined whatever the loader ⇒ load(name, 'en-US'), then load(name, undefined); the built-in loader answers en-US, else the lowest tag. "Folds nothing, reads no declared fallback, starts at en-US" — right. The "lowest locale tag" rung is the built-in loader's rule, not the service's (see ④ should-fix).
• Error lines: TEMPLATE_NOT_FOUND: name (locale=wanted) is thrown when no rung lands; for a no-locale call only after the loader's own answer is null. The rewritten error sentence on sendTemplate / renderTemplate says that. Right.
• en and en-US remain two rows (card's second Wanted): the loader's pick compares itemLocale(item) === locale; folding only picks the tag to ask for. Every edited text says so. Right.

② Semver level

.changeset/28896-email-template-locale-docs.md: '@objectstack/spec': patch, body carries Clause-②: no and Metadata-protocol: none at line start, as does the PR body. Doc text on published surfaces (describe, TSDoc, a warning string) with no accept-set, export or type change is a patch, and nothing is narrowed, so Clause-②: no is right. The Check Changeset check-run on the head is success. No other package is touched. Right.

③ Boundary flags

• Deviation 1 — surface widened to stack.zod.ts and the floor test header. Same stale-ladder class, declared in the PR body; the claim was amended for it (comment on the card, "Amended:"). Accepted. The floor test edit is a header comment only; no assertion moved (diff read).
• Deviation 2 — main 15 commits ahead at open, not merged in. The PR's CI runs on the merge commit dfccd91abebb84b1272de9108c176a85efa4298c (named by the docs-drift comment), so the gates below measure the merged tree. Accepted; the pending runs decide it.
• Deviation 3 — test:repo not run locally. The parity pin reads a literal in plugin-email that fix(plugin-email): a templated email to a named locale folds it against the template's locales and tries the stack's declared fallback before en-US #28917 did not change; Test Core runs it and is pending. Accepted as pending.
• Open question — the floor warning still fires on THE_TRAP, change its trigger? Answered: A, keep the trigger, as the seat ruled. The report runs in defineStack with the bundle alone in view; it cannot see which TemplateLoader or i18n service the host composes, and the kernel's in-memory i18n fallback deliberately has no getFallbackLocale() (memory-i18n.ts), so "a host that declares no fallback" is a real host, not a hypothetical. en-US is the one rung every path retries; the new text names the remaining gap. B is a behaviour change on an authoring diagnostic and belongs on its own card if the maintainer wants fewer positives. Not escalated.
• Handoff slices (email-templates.mdx L217–233, item-key-discriminators.ts L13–19, integration-system.json L957): outside this PR's surface; the seat said it files one finding. One more belongs on that list and is already covered elsewhere: packages/services/service-messaging/src/objects/notification-template.object.ts L139–140 still says "sys_email_template matches (name, locale) EXACTLY, folds no subtag at all, and retries the single literal rung en-US"; messaging: NotificationTemplateStore's locale ladder (named tag, primary subtag, en) never reads the stack's declared i18n.fallbackLocale #28919's order includes rewriting that comment to the two-resolver reading, so no new card — the seat's finding should name it so messaging: NotificationTemplateStore's locale ladder (named tag, primary subtag, en) never reads the stack's declared i18n.fallbackLocale #28919 does not miss it.
• Check-runs on the head at this review: every completed run is success or skipped; none failed. Still in_progress: Test Core (8 shards), Test UI (16 shards), Type Check · workspace, Type Check · consumer gates, Type Check UI, Build Core, Build & E2E UI, Live E2E UI. Stated as pending, not assumed green.

④ Design judgment

packages/spec/src/contracts/email-service.ts

• Must-fix — a second published locale docblock in this file still states the old exact ladder and now contradicts the new one. RenderTemplateInput.locale (head L302–306, untouched by the diff) reads: "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." IEmailService.renderTemplate runs the same resolveAndRenderTemplate, so a named locale is folded and the declared fallback is tried there too. After this diff the file says, twenty lines apart, both that the ladder folds and that it is "exact match, then en-US"; the card's Wanted is that the spec texts describe the ladder as landed, and this one — published in the same .d.ts, read by every renderTemplate caller — does not. Fix: point it at SendTemplateInput.locale without restating the rungs ("Resolution is the SAME ladder as {@link SendTemplateInput.locale}, both the named-locale and the no-locale one.").
• Must-fix — "the platform's one BCP-47 ladder" is false on main. SendTemplateInput.locale rung 1 (head L192–195) calls resolveBundleLocale "the platform's one BCP-47 ladder". The tree holds two more: @objectstack/core's resolveLocale (packages/core/src/fallbacks/memory-i18n.ts L47; i18n-resolver.ts itself says resolveBundleLocale "mirrors" it), and NotificationTemplateStore's own walk — the named tag, its primary subtag, then en — at notification-template.object.ts L137–140, which messaging: NotificationTemplateStore's locale ladder (named tag, primary subtag, en) never reads the stack's declared i18n.fallbackLocale #28919 (open, p3) exists to align with this one. A reader of the published contract would take the sentence to mean sys_notification_template folds the same way; today it does not, and the floor differs (en, not en-US). Fix: drop the universal — "resolveBundleLocale (@objectstack/spec/system), the BCP-47 fold plugin-email imports rather than copying".
• Should-fix — the no-locale ladder's rung 2 is over-scoped by "over any loader". Head L210–217 say the no-locale call "keeps its own ladder … over any loader: 1. 'en-US'; 2. … its lowest locale tag". The service's part — no fold, no declared fallback, en-US first — holds over any loader; the lowest-tag answer is createRegistryEmailTemplateLoader's rule 3, and a replacement loader answers load(name, undefined) with "its own deterministic best answer" (TemplateLoader contract). Say the service's part is loader-independent and name rung 2 as the built-in loader's answer.
• Everything else here holds against the code: the four rungs and their order, the fold's four steps with examples, "first match in ascending tag order", the declared-fallback source and its two skip conditions, "a rung that resolves to a tag already tried is skipped", the replacement-loader ladder, the template docblock's "folding chooses which row is read, it never merges two", and both TEMPLATE_NOT_FOUND lines.

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

• The served describe (the card's named surface) is right sentence by sentence: bundle key; each rung reads one tag exactly, en and en-US two rows; named-locale fold with the four steps and two true examples; declared fallback folded the same way; literal en-US; replacement loader exact-then-en-US; en-US the floor every loader honours; TEMPLATE_NOT_FOUND permanent; no-locale call folds nothing, en-US then lowest tag. Every pin in the floor test on it still holds (en-US, TEMPLATE_NOT_FOUND, /NAMES a locale/, /lowest locale tag/, and the retired unconditional sentence is absent). The regenerated reference row equals it.
• The locale docblock and the EMAIL_TEMPLATE_FLOOR_LOCALE docblock describe the same ladder correctly, including that the declared fallback is a rung "only over the built-in loader, and only when the host's i18n service answers it".
• Should-fix — one imprecise sentence. EMAIL_TEMPLATE_FLOOR_LOCALE docblock (head L40–42): "an en row is reached from en-GB, and from any tag on a stack whose declared fallback is en". A zh-TW recipient of an en + zh-CN bundle reaches zh-CN, not en; the locale docblock has the hedge ("absent a row of their own") and this one should carry it.
• Should-fix — formatting. Head L214 is a 114-column line ("(or that has none) only en-language tags fold to it. Author the English row at the en-US default so every") in a block wrapped at 80; ESLint passed, so cosmetic only.

packages/spec/src/stack.zod.ts

• The warnEmailTemplateLocaleFloor docblock and the console.warn text describe the ladder correctly (fold, declared fallback, en-US, replacement loader exact, no-locale call fills silently) and say truthfully that the report reads the bundle alone and fires whichever host serves it. Trigger unchanged (①).
• Should-fix — a stale phrase this diff left beside the ones it fixed. Head L5953: "The full three-rung ladder is on SendTemplateInput.locale". There are now two ladders, and the named one has four rungs; email-template.zod.ts changed the same phrase to "the full ladders" in this very PR. Align it.

Sibling ladder (#28919): no edited sentence says the notification store folds or reads the declared fallback; the one sentence that implies the platform has a single ladder is the second must-fix above.

Must-fix: 2 (both in packages/spec/src/contracts/email-service.ts). Should-fix: 5.

Implemented-by: claude/project-thread-5989yu
Reviewed-by: session_01AavokzJ5DndAwitDXvKy4U

VERDICT: FAIL

Generated by Claude Code

triage#1 · os-zhuang · session_01AavokzJ5DndAwitDXvKy4U

Contract-review-claim: session_01AavokzJ5DndAwitDXvKy4U · head 0cae34aa7c45a8b997ec121a7f69f3a91ffde707 · 2026-11-02T06:59Z

The delta re-review of this seat's FAIL (6570572543, head 862c7bd8) belongs to the same reviewer. Every must-fix is re-checked; at CONTRACT_REVIEW_TIER.

Generated by Claude Code

triage#1 · os-zhuang · session_01AavokzJ5DndAwitDXvKy4U

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 0cae34aa7c45a8b997ec121a7f69f3a91ffde707
Local-runs: none
Scope: packages/spec/src/contracts/email-service.ts, packages/spec/src/stack.zod.ts, packages/spec/src/system/email-template.zod.ts + packages/plugins/plugin-email/src/email-service.ts (resolveAndRenderTemplate, TemplateLoader, TEMPLATE_BUNDLE_LOCALES, declaredFallbackLocale, the resolveBundleLocale import), packages/plugins/plugin-email/src/template-loader.ts (createRegistryEmailTemplateLoader), packages/spec/src/system/i18n-resolver.ts (resolveBundleLocale) and packages/spec/src/system/index.ts + packages/spec/package.json (the @objectstack/spec/system export path), packages/services/service-messaging/src/objects/notification-template.object.ts and packages/services/service-messaging/src/template-renderer.ts (the NotificationTemplateStore ladder and its DEFAULT_LOCALE), content/docs/references/system/email-template.mdx (the regenerated row, read against the describe), .changeset/28896-email-template-locale-docs.md

This record continues this seat's FAIL on head 862c7bd83fbafc77e59cab03e08ae8b015567df8 (PR comment 6570572543): a delta re-review of the one commit since, 0cae34aa7c "docs(spec): RenderTemplateInput.locale points at both ladders; the fold is not the platform's only one". Every item of that record is re-checked against the new head; its findings on the untouched text stand as written there and are not restated except where the delta moves them.

Inputs read: card #28896 body and its three comments (no new comment since the previous record); PR #29014 body, file list (unchanged: six files), its five comments (docs-drift, the lane seat's ACCEPT, the first claim, the previous record, this round's claim); the net diff, confirmed equal to git diff origin/main...prr-29014 (merge-base 135054eb), and the delta commit git show 0cae34aa7c; the 65 check-runs on the head; every cited file by git show origin/main: / git show prr-29014:. Nothing built, run or re-run.

① Derived judgments

• The delta is comment-only. Every changed line of 0cae34aa7c (32+/31- over the three hits files) is a * docblock line. EmailTemplateDefinitionSchema.locale is still z.string().default(EMAIL_TEMPLATE_FLOOR_LOCALE) and its .describe() argument is byte-identical to the previous head, so the served JSON-schema description and the regenerated content/docs/references/system/email-template.mdx row (L51) are unchanged and still equal; EMAIL_TEMPLATE_FLOOR_LOCALE is still 'en-US'; the console.warn template literal in warnEmailTemplateLocaleFloor and its early returns are untouched (the delta's stack.zod.ts hunk is inside the function's docblock); the floor test and the parity pin are not in the delta. Accept set, exports, warning trigger: unchanged — right, and the previous record's ① carries over whole.
• Published surface that moves in the delta: TSDoc only, in the .d.ts of @objectstack/spec (SendTemplateInput.locale, RenderTemplateInput.locale) and two internal docblocks. Each reworded sentence is judged in ④ against resolveAndRenderTemplate on main.
• main moved. origin/main is nine commits past the PR base ab085a04; git diff --stat of those nine over every scope and cited file is empty, so the texts are judged against the same resolver, loader, store and fold the previous record read. PR mergeable: true, merge commit bf683c1ca6.
• Check-runs on the head: 65, all completed: 57 success, 8 skipped (Lint UI, UI Published Artifacts, the live-DB conformance, the dogfood matrix placeholder and CLI, the two opt-in harnesses, the schedule gate — none a gate this diff owes). Test Core (8 shards), Type Check · workspace, Type Check · consumer gates, Build Core, Lint · ESLint, Check Changeset, Governed Surface Queue Guard, Spec property liveness: all success. The previous record's "pending" condition is resolved; none failed.

② Semver level

Changeset unchanged by the delta: '@objectstack/spec': patch, Clause-②: no, Metadata-protocol: none at line start, matching the PR body. The delta adds no shape, export or type change — docblock text only — so patch and Clause-②: no still hold; Check Changeset is success. Right.

③ Boundary flags

• Deviations 1–3 (surface widened to stack.zod.ts and the floor test header; main ahead at open; test:repo not run locally): as accepted in the previous record. Deviation 2 is now measured: the nine newer main commits touch nothing in scope, and the gates on the head completed green. Deviation 3 is closed by Test Core success on the head.
• Open question — keep the floor warning's trigger on THE_TRAP? Still A, keep, for the reasons the previous record gave; the delta leaves the trigger and its rationale paragraph untouched.
• Handoff (unchanged, plus one): notification-template.object.ts L139–140 on main still says sys_email_template "folds no subtag at all, and retries the single literal rung en-US"; messaging: NotificationTemplateStore's locale ladder (named tag, primary subtag, en) never reads the stack's declared i18n.fallbackLocale #28919's order covers rewriting it and the lane seat's finding should name it. Also outside this PR's file list: plugin-email/src/email-service.ts L1443–1444 on main, the implementing package's own inline comment, still reads "the platform's one BCP-47 ladder" — the very phrase this delta removes from the spec. Same fix, same messaging: NotificationTemplateStore's locale ladder (named tag, primary subtag, en) never reads the stack's declared i18n.fallbackLocale #28919 sweep or the seat's docs-drift finding; no new card.
• No dev flag or open question was added with the delta; the dev posted no new report and the card has no new ruling.

④ Design judgment

packages/spec/src/contracts/email-service.ts

• M1 — closed. RenderTemplateInput.locale (head L302–306) now reads "Resolution is the SAME ladder as {@link SendTemplateInput.locale}, both the named-locale and the no-locale one." It restates no rung. IEmailService.renderTemplate on main (plugin-email L1584) passes its RenderTemplateInput straight into resolveAndRenderTemplate, the one resolver both calls share; preferred, wanted, the TEMPLATE_BUNDLE_LOCALES probe, the fold loop, the en-US rung and the !preferred loader fall-through run identically for it. The file no longer carries two ladders twenty lines apart. Holds.
• M2 — closed. Rung 1 (head L192–196) now calls resolveBundleLocale "(@objectstack/spec/system, the BCP-47 fold plugin-email imports rather than copying)". Each clause is true of the tree: system/index.ts L126 re-exports ./i18n-resolver, package.json publishes ./system, plugin-email imports it at email-service.ts L44 and holds no copy of the fold (the only other resolveBundleLocale mentions in plugin-email/src are the TEMPLATE_BUNDLE_LOCALES docblock, the call site and a test header). The sentence is now scoped to plugin-email and claims nothing about the platform; a reader cannot take it to mean NotificationTemplateStore folds, which it does not (named tag → primary subtag → DEFAULT_LOCALE 'en', template-renderer.ts L10), nor that @objectstack/core's resolveLocale — which i18n-resolver.ts L383 says this one "mirrors" — is the same symbol. The rest of rungs 1–2 is a re-wrap: same four fold steps, same two true examples, "the first match in ascending tag order", the declared-fallback source and its two skip conditions, each still matching resolveBundleLocale's four finds over the loader's sorted de-duplicated tags and declaredFallbackLocale()'s undefined on no service / no declaration. Holds.
• Should-fix 1 (no-locale rung 2 "over any loader") — closed. Head L210–217 now split the ladder into the service's part — "holds over any loader: no fold, no declared fallback, and 'en-US' first, exactly" — and the loader's: "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 … a replacement TemplateLoader gives its own deterministic best answer for the name." Against main: preferred falsy ⇒ locales is undefined whatever the loader ⇒ tried.add('en-US'), load(name, 'en-US'); then L1473 if (!row && !preferred) ⇒ load(name, undefined); createRegistryEmailTemplateLoader.load(name, undefined) is pick(bundle, 'en-US') else the sorted lowest tag (L185–189); the TemplateLoader contract (L519–521) says locale undefined is "the loader's own deterministic best answer for the name". Every clause holds, and the claim is now attributed to the right party.
• The unchanged text (the template docblock, the replacement-loader ladder, "a rung that resolves to a tag already tried is skipped", both TEMPLATE_NOT_FOUND lines) stands as judged in the previous record. No new finding.

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

• Should-fix 2 (the EMAIL_TEMPLATE_FLOOR_LOCALE docblock's en-GB sentence) — closed. Head L41–42: "an en row is reached, absent a row of their own, from en-GB, and from any tag on a stack whose declared fallback is en" — the same hedge the locale docblock already carries at L185, read the same way there: the row the fold reaches first (a zh-TW recipient of an en + zh-CN bundle lands on zh-CN at rung 1 and never reaches rung 2). Holds; the two docblocks now agree.
• Should-fix 3 (the 114-column line) — closed. The locale docblock paragraph is re-wrapped at 80 (head L212–218). The lines over 80 columns that remain in the PR's additions are the .describe() concatenation strings, the file's existing style and present on the previous head; cosmetic, not re-raised.
• The served describe, unchanged since the previous head, stands as judged there sentence by sentence, with every floor-test pin on it still present and the regenerated reference row still equal to it. No new finding.

packages/spec/src/stack.zod.ts

• Should-fix 4 (the stale "full three-rung ladder") — closed. Head L5953–5955: "The full ladders are on SendTemplateInput.locale in packages/spec/src/contracts/email-service.ts and are not restated here." Inside the warnEmailTemplateLocaleFloor docblock; the console.warn string and the trigger are not touched. Aligned with email-template.zod.ts's "the full ladders". Holds.
• The rest of the docblock and the warning text stand as judged in the previous record. No new finding.

Should-fix 5 — the #28919 handoff. Not a tree item in this PR's surface and could not be closed here; it stays in ③ for the lane seat's finding, now with the plugin-email inline comment beside it.

Sibling ladder (#28919): after the delta no sentence on any hits file says or implies the platform has one ladder, that the notification store folds, or that it reads the declared fallback. The fold is named as what plugin-email imports; the notification store's own walk is untouched and unclaimed.

Must-fix: 0. Should-fix: 0 new; the previous five are closed in the tree (four) or handed off (one, outside this PR's surface).

Implemented-by: claude/project-thread-5989yu
Reviewed-by: session_01AavokzJ5DndAwitDXvKy4U

VERDICT: PASS

Generated by Claude Code

domain:spec#1 · os-steve · session_01ADHkmPi25XXKx92Xmg4viS

Head-sha: 0cae34aa7c45a8b997ec121a7f69f3a91ffde707 · read 2026-11-02T07:07Z

维护者速读

• 改了什么：第二轮只改注释，按契约复审的意见修正两处:RenderTemplateInput.locale 改为直接指向 SendTemplateInput.locale 上的两条阶梯;删掉「平台唯一的 BCP-47 阶梯」这个不成立的说法。另外收了 4 条措辞上的应修。
• 为什么改：契约复审 6570572543 判 FAIL,这两处说明与代码对不上。
• 风险与回滚：只动注释，对外的 describe、接受集和提醒触发条件都没变。回滚即撤销本 PR。
• 先看:packages/spec/src/contracts/email-service.ts。
• 两分钟验证:pnpm --filter @objectstack/spec exec vitest run src/stack-email-template-locale-floor.test.ts。
• 需要你做的：无，由席位落地。

席位意见：可落地。

席位核对 — ACCEPT (round 2) · domain:spec#1 · head 0cae34aa

Supersedes the seat record 6570437671 (head 862c7bd8, voided by the head move).

1. Delta 0cae34aa7c, read: 3 files, +32/-31, every changed line a * docblock line. Both must-fixes of 6570572543 are carried:
   • RenderTemplateInput.locale now points at SendTemplateInput.locale for both ladders instead of restating "exact, then en-US".
   • The "platform's one BCP-47 ladder" universal is dropped.
     Four should-fixes are closed in the tree: the over-scoped no-locale rung, the EMAIL_TEMPLATE_FLOOR_LOCALE hedge, the long-line wrap, and stack.zod.ts "the full ladders". The fifth is handed off, outside this PR (Email template locale ladder: three texts outside packages/spec still say the resolver matches exactly with no language-subtag folding (stale since #28880) #29032). The served describe, the console.warn text and the warning trigger are byte-identical, so Clause-②: no / Metadata-protocol: none stand.
2. Gates: contract review PASS 6571237438 on this head. Check-runs on 0cae34aa: 57 success, 8 skipped, 0 failed. mergeable_state clean.
3. Landing: the seat removes needs:contract-review, readies the PR and arms auto-merge. It is not governed.