fix(auth): read the recipient's own sys_user.locale for auth OTP SMS and auth mail

[claude]

Fixes #14762

sys_user.locale has been a first-class column since #13881 and user-writable since PR #14958, but plugin-auth's own sends never read it. A phone OTP rendered in the deployment's language, and auth mail in whichever language the triggering request asked for — so an admin-initiated password reset carried the admin's browser language onto the user's mail.

Both ladders now start one rung higher.

The ladder is ruled, not re-decided here

#14788 was ruled option D in the 2026-09-03 batch (maintainer verbatim: 「同意」):

sys_user.locale when set -> the request's Accept-Language -> the deployment default.

The recorded reasoning: a value the user chose is stronger evidence of intent than the Accept-Language the browser just sent. This PR implements that order and does not re-cost it. The card body's own suggestion — a stored rung between request and deployment — is the pre-ruling shape and is deliberately not what landed.

For OTP SMS the chain collapses to stored -> deployment, confirmed against the code rather than assumed: better-auth 1.7.x calls both sendOTP and sendPasswordResetOTP with { phoneNumber, code } and a ctx, so there is no request rung to rank on this surface.

What changed

• AuthManager.storedRecipientLocale(where) — one projected findOne on sys_user, under a system context, normalized. Best-effort by construction: no engine, no row, an unset column, a datasource outage or a value that cannot name a language all resolve to "no stored preference", never to a failed send.
• AuthManager.emailLocaleArg(requestSource, storedLocale) — three rungs instead of two. Threaded at sendResetPassword, sendVerificationEmail and sendChangeEmailNotice, the three sends that hold a recipient row.
• AuthManager.renderPhoneSmsBody(topic, data, storedLocale) — the OTP send resolves the recipient by the unique phone_number and renders in their language.
• Stale ladder docblocks on setDefaultSmsLocale, setDefaultEmailLocale, sendChangeEmailNotice and phone-sms-texts.ts — each said "auth mail does not read it yet", which this PR makes false.

Everything underneath is untouched: an account with no stored locale still gets the deployment default, and with nothing configured the documented en-US floor and the built-in en SMS row still apply. Nothing dead-letters.

Reuse, measured before depending on it

The dispatch flagged an earlier triage reading of git grep -c "normalizeRecipientLocale" -- packages/services/service-messaging/src/ -> 0, taken at a pre-#13881 ref. Re-measured at current origin/main, with a positive control first so a zero would be a live reading rather than a dead channel:

git grep -c "locale" origin/main -- packages/services/service-messaging/src/
  -> 21 files (positive control: the channel is live)
git grep -c "normalizeRecipientLocale" origin/main -- packages/services/service-messaging/src/
  -> recipient-locale.ts:5, recipient-locale.test.ts:12,
     recipient-locale-shape-parity.test.ts:3, index.ts:1
git grep -n "normalizeRecipientLocale" origin/main -- .../src/index.ts
  -> index.ts:68  (exported)

It exists and it is exported, so it is imported rather than copied. Its refusal of the stringified-nothing literals is load-bearing here and is pinned: without it, normalizeAuthEmailLocale('undefined') returns 'undefined' verbatim and names a row that does not exist.

@objectstack/plugin-auth therefore declares @objectstack/service-messaging as a dependency. Precedent: @objectstack/plugin-webhooks already depends on it; no manifest cycle (check:workspace-manifest-cycles green).

The premise the card got wrong, and what replaced it

The card's suggested shape says to read the column "off the row sendPhoneOtp already has". There is no such row, and no such method. deliverPhoneOtp(phone, code) is what exists, and better-auth hands its callbacks a phone number and a code — request-password-reset resolves the user for its own gate and does not pass it on (measured in the installed 1.7.x routes.mjs).

So the row is looked up here: one read on the unique phone_number index, paid only once the send is going to happen. The number is matched exactly, which is how better-auth matches it for its own user lookup on the same route; a differently formatted spelling resolves no row and lands on the deployment default, which is the documented floor rather than a failure.

The card's core premise — the column exists and plugin-auth does not read it — holds, and is quoted by the shipped source's own comments.

Deliberately out of scope

Invitations. Mail (sendInvitationEmail) and SMS (sendPhoneInviteSms) both keep the deployment rung; an invitee has no sys_user row until acceptance. That is #14641's, and both abstentions are pinned rather than merely described.

sendMagicLink is handed only { email, url, token }, so its stored rung needs a lookup keyed by email — a query shape on a path this card does not name. Filed as #15106 rather than smuggled in.

Pins, and the ablation

Nine new SMS pins and eleven new mail pins. Both fixture locales render genuinely different text in both directions (验证码 only in the zh row, verification code only in the en row), and the three-rung mail pin gives each rung a different locale (stored ja-JP / header zh-CN / deployment es-ES), so no assertion can pass on a rung it did not measure. Two pins assert the mechanism — that the read happened, on the right predicate, with the right projection, under a system context — so a body assertion cannot be satisfied by some other resolution step reaching the same answer by luck.

Ablation. With the implementation committed first (so the restore leg has a real reference), both rungs were reverted in place and the mutation proved on disk before measuring — injected marker count 2, both deleted anchors at 0, blob 3b6add63 -> 41febcbe. No rebuild leg is owed: both suites import ./auth-manager by relative source path, so the mutated source is what vitest ran. Restore proved the same way: git diff HEAD empty, git status --porcelain empty, on-disk blob back to 3b6add63c4a4006266351d79fec6e9339ed40d5e, zero residual markers.

	predicted	measured
red	5	5
auth-email-locale.test.ts	outranks-BOTH · catalog-language mapping · unshipped-tag passthrough	same 3, by name
auth-manager.test.ts	zh-CN user on en-US deployment · the reverse	same 2, by name
green under ablation	the four floor pins and the two mechanism pins in each file	311 passed

No divergence. The floor pins staying green is the intended result — they assert the behaviour the ablation restores.

Clause-②: no

The diff touches no packages/spec/src/**, no *.zod.ts contract schema and no error-code ledger; it adds no exported symbol to any package's public API (both new helpers are private, and emailLocaleArg's new parameter is on a private method); and it changes no accept/reject behaviour — a locale ladder is a resolution preference, and no input is newly accepted or newly refused at any boundary. The one published-metadata movement is the new workspace dependency noted above, which is not a contract surface. Flagging it explicitly so a reviewer who reads that differently can say so.

packages/spec is untouched. content/docs/releases/** is untouched. No test is skipped, disabled or quarantined.

Verification — at c2f8324 (final commit), tree clean

Every reading below was taken at this exact tree, with the exit code captured before any pipe.

• pnpm --filter '@objectstack/plugin-auth^...' build — dependency closure built first, so nothing below reads a stale dist. Exit 0.
• pnpm --filter @objectstack/plugin-auth test — 93 files / 1958 tests passed, exit 0.
• pnpm --filter @objectstack/plugin-auth typecheck — exit 0, all three programs. Its check:test-typecheck step is what makes this cover the new test files: 10 file(s) / 94 error(s) / 23 pinned signature(s) held, unmoved.
• All 48 derived gate families (node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands, derived from the real change set rather than a hand-written diff): 47 green.
  • node scripts/check-test-completeness.mjs answered exit 3 = NOT MEASURED, not a pass and not a red: it grades a saved turbo run test log and none exists locally. Unreachable in CI, which tees the log and passes the path. This diff cannot move it.
  • The ratchet families were re-run against the built workspace closure: check:type-check-debt --re-measure — 17 ledger entries re-measured, 217 raw tsc errors, none above its recorded number, surplus: none. check:dual-build-cjs-loads — 102 require entry points across 66 packages load.
  • Two gates were red first and are the reason the two config commits exist: check:test-source-alias and check:type-source-resolution both refused the new cross-package value import until tsc and vitest resolve it from source. Fixed by wiring, never by widening either shrink-only registry.
• ESLint — a declared narrowing, not a skip. eslint --no-inline-config --format json over the five authored files this diff touches: 5 files linted, 0 errors, 0 warnings (count read from the JSON, not from prose). The narrowing is sound because this repo runs ONE eslint.config.mjs which never enables type-aware linting for any file — no parserOptions.project, no typed @typescript-eslint rules, a fact that config records at line 328 with its own positive control. With no cross-file type information in play, this diff cannot move the verdict on a file it does not touch. The remaining four files it changes (package.json, two tsconfig*.json, one changeset) fall outside every files glob in that config. CI runs the full sweep regardless.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AUF1NoViznQK32gqpK8wS8

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/plugin-auth, touching 7 documentable anchor(s). ⚠️ 5 changed file(s) yielded no anchor (packages/plugins/plugin-auth/package.json, packages/plugins/plugin-auth/src/phone-sms-texts.ts, packages/plugins/plugin-auth/tsconfig.examples.json, …), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

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

• content/docs/kernel/contracts/auth-service.mdx (via AuthManager (symbol, a top-level class))
• content/docs/kernel/services-checklist.mdx (via AuthManager (symbol, a top-level class))
• content/docs/permissions/authentication.mdx (via AuthManager (symbol, a top-level class))

What this run could not see

• 5 changed file(s) yielded no anchor (packages/plugins/plugin-auth/package.json, packages/plugins/plugin-auth/src/phone-sms-texts.ts, packages/plugins/plugin-auth/tsconfig.examples.json, …) — pages documenting those are invisible to this run
• 1 anchor(s) matched too much of the corpus to be a work list: sys_user (literal, 30 pages)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 11 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 4428dd5756750939e2fd503e431c34c1cb83a19c → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 37056d579bdf4eebcd4d380efcfed1b867e5b6e1 — the merge of head 19c2aed981d6a8c1ae2e12bfa082fd9319c753c3 into base 4428dd5756750939e2fd503e431c34c1cb83a19c, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 37056d579bdf4eebcd4d380efcfed1b867e5b6e1 && git checkout 37056d579bdf4eebcd4d380efcfed1b867e5b6e1
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 4428dd5756750939e2fd503e431c34c1cb83a19c 19c2aed981d6a8c1ae2e12bfa082fd9319c753c3 && git checkout -B drift-repro 4428dd5756750939e2fd503e431c34c1cb83a19c && git merge --no-ff 19c2aed981d6a8c1ae2e12bfa082fd9319c753c3

node scripts/docs-audit/affected-docs.mjs --json 4428dd5756750939e2fd503e431c34c1cb83a19c

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

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 4428dd5756750939e2fd503e431c34c1cb83a19c → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Landing — green after patch round 1, undrafted then armed

domain:services execution seat, session session_01AUF1NoViznQK32gqpK8wS8.

State on head 19c2aed981: all checks complete, 0 failures, read at job level with the latest run taken per check name (Test Core is an aggregator over its shards and is not a substitute for reading them).

Landing order observed: undraft first, draft=false confirmed on read-back, then auto-merge armed at 23:26:09Z. Auto-merge does not survive a draft conversion, so the order is load-bearing. ⛔ One re-arm maximum, unspent.

No carrier is hung. Clause-② was declared no, and this seat verified the stated basis rather than accepting it: 0 added export lines across 574 added lines, with all three new helpers (storedRecipientLocale, emailLocaleArg, renderPhoneSmsBody) declared private.

What patch round 1 corrected, and what it deliberately did not

content/docs/permissions/authentication.mdx stated the OTP SMS locale "follows the deployment default", which this change makes false. The page now distinguishes the two SMS sends — the OTP takes the recipient's own sys_user.locale when the account has one (matched on phone_number, so an unmatched number takes the deployment default too), while the invitation SMS still reads the deployment default alone, since invitations are #14641's and untouched here.

⭐ The zh-CN → zh → en fallback chain was measured before being left alone, not assumed: phoneSmsLocaleChain is byte-identical to origin/main (sha256 9a009ec7c14f4a79 on both refs). It is a different mechanism from the rung ladder, so the corrected sentence says the chain resolves whichever locale the ladder named rather than restating it. The template-precedence rule, the hole lists and the best-effort sentence are untouched.

The docs sweep behind that correction gave every zero a positive control: localization.locale → exactly 1 hit (this page); setDefaultEmailLocale|setDefaultSmsLocale → 0 (control: three sibling greps non-zero on the same corpus); sys_user.locale → 2, both the messaging path #13881 already shipped correctly; Accept-Language → 8, all request-rendering or UI translation.

On MERGED, pm:dispatched comes off card #14762.

---

Generated by Claude Code