docs(#13881): contract-review patch round 1 — two auth-manager docblocks, second behaviour change + TEMPLATE_* asymmetry in the changeset, wording

Author: claude

.changeset/notification-locale-per-recipient.md

@@ -19,8 +19,10 @@ deferral.
 
 Now the locale is resolved PER RECIPIENT, at delivery time, through ONE read
 point (`recipient-locale.ts`, `resolveRecipientLocale`): the recipient's own
-`sys_user.locale` — read off the same row the channel already fetches for the
-address, so it costs no second query — else the deployment default, probed
+`sys_user.locale` — email and SMS read it off the same row they already fetch
+for the address, so it costs no second query there; the inbox channel, which
+never read the row before, makes one read for it on the template path — else
+the deployment default, probed
 lazily so live `localization` changes are honoured. The same chain serves the
 email channel's two arms (`sendTemplate` and `sys_notification_template`), the
 inbox channel's template path, and the SMS channel, so one notification cannot
@@ -42,13 +44,28 @@ it now sends each recipient their own language, else the deployment default —
 which is the ruled behaviour, not a regression. Nothing to migrate: remove the
 key, or leave it, it is inert either way.
 
+Second behaviour change: on the `sys_notification_template` arm (email topic
+path, SMS) the deployment default (`II18nService.getDefaultLocale()`) is now
+the second rung; before, that arm fell straight from `payload.locale` to the
+static `en` and never consulted it. A deployment whose `localization.locale`
+is e.g. `zh-CN` with a topic bundle holding `en` and `zh` rows renders `zh`
+there now for recipients without a column. SMS is newly handed the
+deployment-default probe.
+
 `@objectstack/spec` ships the contract text: the `notify` node's `template`
 description and its refusal messages now state the per-recipient chain and
 name `payload.locale` as not consulted (`automation/io-node-config.zod.ts`),
 mirrored on the runtime descriptor in `@objectstack/service-automation`.
 
 Interaction with the `TEMPLATE_*` permanent-failure class is unchanged in
-kind: `sendTemplate`'s ladder still ends at `en-US`, so a recipient locale can
-dead-letter a delivery only where the deployment default would have too — a
-bundle with neither the requested row nor an `en-US` row, which is off the
-documented contract.
+kind: `sendTemplate`'s ladder for a NAMED locale still ends at `en-US`, so a
+recipient locale can dead-letter a delivery only against a bundle that has
+neither the requested row nor an `en-US` row — off the documented contract.
+Two asymmetries against the old single value, both on such bundles: (a) the
+bundle carries the deployment default's row but no `en-US` row — old delivered,
+new fails for a recipient whose own tag is a third language; (b) there is NO
+deployment default (i18n absent or `getDefaultLocale` unimplemented) — old
+called `sendTemplate` with no locale and the ladder's any-row rung delivered,
+new names the recipient's tag, the any-row rung is skipped, and a tag absent
+from the bundle is `TEMPLATE_NOT_FOUND` (permanent). The fix in both is the
+bundle (`en-US` is the ladder's floor), not a third rung.

.changeset/sys-user-locale-column.md

@@ -30,7 +30,8 @@ D4, so the standard edit form does not advertise a write the runtime refuses)
 and is NOT added to `MANAGED_EXTENSION_EDITABLE_FIELDS` or to the ADR-0092 D2
 self-service whitelist (`{name, image}`). Widening that whitelist so a user can
 set their own language is a security-boundary decision recorded on #13881, not
-made here; until then the column is written by admin / system surfaces.
+made here; until then the column is written only by system-context callers (no
+admin surface writes it today).
 
 Who reads it: the messaging channels, per recipient, after fan-out — see the
 `@objectstack/service-messaging` changeset in the same release.

packages/plugins/plugin-auth/src/auth-manager.ts

@@ -4456,9 +4456,10 @@ export class AuthManager {
    * entirely and `EmailService`'s ladder resolves its documented `en-US`
    * default exactly as before.
    *
-   * Still NOT a per-recipient stored preference: `sys_user` carries no locale
-   * column and the 2026-09-02 ruling continues to defer one. What is read is
-   * the language this request expressed, not a profile.
+   * Still NOT a per-recipient stored preference: `sys_user.locale` exists
+   * since #13881 (ruling 2026-09-01) but auth mail does not read it yet
+   * (#14762 for this send; #14641 for invitations). What is read is the
+   * language this request expressed, not a profile.
    */
   private async sendChangeEmailNotice(
     from: { email: string; name?: string; id?: string },
@@ -4665,8 +4666,9 @@ export class AuthManager {
    * `kernel:ready` and on every settings change (same pattern as
    * {@link setAppName}). Unset ⇒ the built-in English text.
    *
-   * Per-user locale is not resolved yet — `sys_user` carries no locale
-   * column; when it grows one, resolution should prefer it (#2815).
+   * Per-user locale is not resolved here yet — `sys_user.locale` exists since
+   * #13881 (ruling 2026-09-01) and the messaging channels read it per
+   * recipient; auth SMS adopting it is #14762 (supersedes the #2815 note).
    */
   setDefaultSmsLocale(locale: string | undefined): void {
     this.smsLocale = locale?.trim() || undefined;

packages/services/service-messaging/src/recipient-locale.ts

@@ -17,9 +17,11 @@
  *
  * ## The chain
  *
- *  1. the recipient's own `sys_user.locale` ({@link RECIPIENT_LOCALE_FIELD}),
- *     read from the SAME `sys_user` row the channel already fetches for the
- *     address (email / phone) — one query per recipient, no second lookup;
+ *  1. the recipient's own `sys_user.locale` ({@link RECIPIENT_LOCALE_FIELD}).
+ *     Email and SMS read it off the SAME `sys_user` row they already fetch
+ *     for the address — one query per recipient, no second lookup there; the
+ *     inbox channel, which never read the row before, makes one read for it
+ *     on the template path only;
  *  2. the deployment default — `II18nService.getDefaultLocale()`, probed
  *     lazily at delivery time by the plugin (`getDefaultTemplateLocale`).
  *