[Decision] One spelling for the signed-in user's language on the published surface — `SessionUserSchema.language` (unproduced), `sys_user.locale` (#13881) and `/auth/me/localization.locale` (request/deployment) coexist

[claude]

Filed by the domain:spec seat (session_017RbbUMnxkUnWhE4j94v8FE) from the contract review of PR #14775 (#13881, isolated reviewer verdict 5518923117, "Decisions to file for the maintainer" item 2). Decision inbox card — needs-user-decision; no domain:* / type set by this seat (triage's). PR #14775 lands without touching any of the three surfaces below; this card decides the follow-up.

背景

登录用户的「语言」在公开面上现在有三种拼法并存:

1. SessionUserSchema.language(packages/spec/src/api/auth.zod.ts:36,z.string().default('en'),描述 "Preferred language")—— 已发布的 session 契约,但全仓没有生产者也没有消费者(只有自己的 spec 测试);
2. sys_user.locale —— [Decision] Per-user notification locale —— 2026-08-13 裁决所等的「实测拉力」已到(hotcrm:4 个已发布语言 × 16 个 notify 节点 × 0 可本地化) #13881 裁决新增的一等列(PR feat(spec,platform-objects,service-messaging,plugin-auth): sys_user.locale + per-recipient notification locale (#13881) #14775),通知投递按收件人读它;
3. GET /auth/me/localization 返回的 locale(packages/plugins/plugin-auth/src/current-user-endpoints.ts ~:876-888)—— 取的是请求/部署的 locale,不是用户列;objectui 曾用它播种 UI 语言(console: the tenant's server-side locale (/auth/me/localization) is fetched but never seeds the UI language — first login is always browser-or-en #5419)。

#13881 的裁决明确排除「第二种拼法」,却没看见 language 早已躺在契约上。复审判 PR 可以不动它先落地,本卡决定收口方向。

带 re-check 命令的前提

• language 仍在契约上且无生产者:git grep -n "language" origin/main -- packages/spec/src/api/auth.zod.ts packages/plugins/plugin-auth/src packages/rest/src (只应命中 auth.zod.ts:36 与 Accept-Language 类用法)
• /auth/me/localization 仍返回请求/部署 locale:git grep -n -B3 -A8 "localization" origin/main -- packages/plugins/plugin-auth/src/current-user-endpoints.ts
• objectui 是否引用 SessionUser.language(未测,本席只有 objectstack 检出):在 objectui 仓 git grep -n "\.language\b\|SessionUser" origin/main -- packages apps

一句话问题

用户在个人资料里选了中文,前端问服务器「这个用户什么语言」时,契约上有一个永远是 'en' 的 language、一个不看用户只看请求的 locale,和一个刚落地但契约上不可见的用户列 —— 三个答案,没有一个是对的。

选项 × 真实代价

选项	做什么	真实代价
A 不动	language 继续躺在契约上,sys_user.locale 只做存储	前端/AI 读契约会相信 language 有意义,拿到永远的 'en';用户选的语言 UI 永远看不到 —— 「声明 ≠ 兑现」原样留着
B 加 locale 到 session 契约,与 language 并存	两种拼法一个面	正是 #13881 裁决明令排除的形状;每个消费者都要猜读哪个
C 直接改名 language → locale	破坏性改名,ADR-0087 登记	已发布契约破坏;objectui 是否引用未测 —— 可能弄坏 console 登录态
D 退役 language(ADR-0049 enforce-or-remove),只在 session 端点真正产出时再以 locale 投影用户列	先删从未兑现的键;/auth/me/localization 改成「用户列 → 请求 → 部署默认」并成为唯一的读面	一次 ADR-0087 退役登记 + 一个端点改动;需要先测 objectui 有没有读 language

业务上:A = 产品文档里写着「支持用户语言」但设置无效;B = 设置页有两个「语言」下拉;C = 一次升级把老客户端弄坏;D = 像成熟 SaaS 那样,只有一个「我的语言」,后端按它答。

四轴(从业务立场)

• 实际业务需求:language 零拉动(从未产出、从未消费);用户列的 UI 侧拉动是真的(console: the tenant's server-side locale (/auth/me/localization) is fetched but never seeds the UI language — first login is always browser-or-en #5419 显示 console 曾试图从 /auth/me/localization 播种语言,而它今天不读用户列)。
• 项目长远合理性(≥50%):一个概念一个拼法、声明即兑现 —— D 把契约收窄到真实生产者,B 扩生特例,A 留着假声明,C 用破坏性动作换一个本可以先删再加的结果。
• 防 AI 犯错:AI 读契约看到 language 就会用,拿到 'en' 还以为对了 —— 静默错误的温床;退役后读契约只剩一个 locale,错了是响亮的编译期缺键。
• 创业阶段不扩散:D 是 remove 优于 declare-and-maintain;不设双拼写宽限(2026-08-27 裁:创业阶段不渐进)。

推荐 + 回退 + 置信缺口

• 推荐 D:先在 ADR-0049 通道退役 SessionUserSchema.language(ADR-0087 登记),/auth/me/localization 的 locale 改为「用户列 → 请求 locale → 部署默认」,成为唯一读面;不在 session 契约上另加字段,直到有真实生产者。
• 回退 A(什么都不动,记录在案)。
• 本分析看不见什么:objectui / cloud / hotcrm 是否读 SessionUser.language(未测 —— 执行卡第一步必须先测,命中即改判为 C 的兼容路径);/auth/me/localization 的现有消费者对「用户列优先」的预期。

裁后我会怎么执行(你不用管)

• 裁 D:等 PR feat(spec,platform-objects,service-messaging,plugin-auth): sys_user.locale + per-recipient notification locale (#13881) #14775 合并后立执行卡(spec + plugin-auth 落点,条款② yes):测 objectui/cloud 引用 → ADR-0087 退役 language → 端点改读用户列 → 契约文本 + pin + changeset(spec minor,退役登记)。
• 裁 A/B/C:按裁决立卡或关卡;C 必须先测 objectui。

Refs

#13881(裁决 5494464459)· PR #14775(复审 5518923117,H3 finding)· #5419(console 播种 UI 语言,已关)· #14762 · ADR-0049 · ADR-0087

os-decision-facets

• ① 长远合理性:一个概念一个拼法、声明即兑现 —— 退役从未产出的 language,用户语言只经 locale 投影(D);B 扩生特例,A 留假声明,C 破坏性换同一结果。
• ② 实际业务拉动:language 零拉动(无生产者无消费者);用户列的 UI 播种拉动是真的(console: the tenant's server-side locale (/auth/me/localization) is fetched but never seeds the UI language — first login is always browser-or-en #5419)—— 拉动指向 D 的第二步,不指向保留 language。
• ③ 防 AI 犯错:留着 language = AI 读契约拿到永远的 'en' 还以为对;删掉后错误是响亮的缺键。
• ④ 创业阶段不扩散:remove 优于 declare-and-maintain,不设双拼写宽限。
• 推荐:D(回退 A;C 只在 objectui 实测有引用时作为兼容路径)。
• 置信缺口:objectui / cloud / hotcrm 对 SessionUser.language 与 /auth/me/localization 的引用未测。

---

Generated by Claude Code

[huangyiirene]

Triage — sweep ③ lane repair. Added priority:p2 · domain:spec · i18n; needs-user-decision kept. ⛔ No decision content added — the card carries its own, and the ruling is the maintainer's.

Anchor (the lane is read from where the fix lands, ⛔ never guessed from the title): SessionUserSchema is declared in packages/spec/src/api/auth.ts — confirmed via its test at packages/spec/src/api/auth.test.ts:4, which imports it from there. Whichever spelling wins, the published-surface half of it lands in packages/spec. ⇒ domain:spec.

p2, not p3: this decision gates real queued work rather than sitting on its own. #14762 (pm:blocked) names precisely this question as the one its ruling did not settle — "does the user's stored locale outrank the request's Accept-Language for a signed-in user's own sends?" — and #13881 (pm:dispatched, pm:blocking) is in flight on the column itself. Three spellings coexisting on a published surface is also the shape that gets more expensive per release, not less.

⚠️ Two facts a ruling here will want, measured this round and recorded so nobody re-derives them:

• [Decision] Per-user notification locale —— 2026-08-13 裁决所等的「实测拉力」已到(hotcrm:4 个已发布语言 × 16 个 notify 节点 × 0 可本地化) #13881 has not landed. git grep 13881 -- packages/ at origin/main returns 0 hits, and normalizeRecipientLocale in service-messaging is 0. Any card describing sys_user.locale as present is describing that branch.
• [Decision] May a user set their own sys_user.locale? — the ADR-0092 D2 self-service whitelist stays {name, image} after #13881 (column lands readonly, system-context writes only) #14787 is coupled to this, not parallel to it. If the column is readonly with system-context writes only, then "the user's stored locale" is an administered value rather than a stated preference — which changes what the right precedence is, not merely who may write it. ⛔ Ruling these two independently can produce a pair that does not compose.

---

Generated by Claude Code

[os-project-manager]

Maintainer ruling recorded — D: retire SessionUserSchema.language; /auth/me/localization.locale becomes the one read face, projecting the user column

Director seat, summon #11, session session_01ShyhexkB2d1AeRZ85tgAAe, 2026-09-03.

Provenance (who / verbatim / where): maintainer, live PM chat with the director seat, 2026-09-03, replying to decision batch #18 in which this card was item 1 with the recommendation D (fallback A), presented together with #14787 (item 2) because the two compose. Verbatim reply: 「同意」 — adopts D, and B on #14787.

Ruled: D. SessionUserSchema.language (packages/spec/src/api/auth.zod.ts) is retired under ADR-0049 enforce-or-remove with an ADR-0087 registry entry — no producer, no consumer, gone; no replacement field is added to the session contract until a real producer exists. GET /auth/me/localization keeps its locale and becomes the single read face for "this user's language", with the precedence that follows from #14787's ruling B (the column is a user-stated preference): sys_user.locale when set → the request's Accept-Language → the deployment default. Options A (leave the dead field), B (add locale beside language — the shape #13881 excluded) and C (breaking rename) are not taken; 不渐进 — no dual-spelling window.

Execution: domain:spec lane (spec half) with the plugin-auth endpoint in the same PR, after PR #14775 (#13881) has merged — the column must exist on main first. Clause-②: yes (a published session type loses a member; a published endpoint's semantics change) ⇒ claude-fable-5, needs:contract-review, in-seat review before ready. Step one of the dispatch is the measurement the card names: readers of SessionUser.language and of /auth/me/localization in objectui, cloud and hotcrm — any hit is changed in the same stroke (objectui by a cross-lane card with Blocked-by: this one), ⛔ not bridged. Changeset: @objectstack/spec minor with a BREAKING note per the launch-window convention; endpoint pin asserting the three-step precedence; #14762 (pm:blocked) re-reads its Blocked-by: once this lands.

State transition, same stroke: needs-user-decision → pm:queue. Ledger: director seat post #12708, summon #11.

---

Generated by Claude Code