localization 的 timezone / currency 用「策展式 options 表」当穷尽执行边界:合法的 IANA 时区与 ISO 4217 币种被拒

[os-zhuang]

在 #5204(env 覆盖过 options 表)的实现中发现,记录下来交 triage。不在 #5204 的完成范围内,#5204 也没有为它开豁免口子。

事实

packages/services/service-settings/src/manifests/localization.manifest.ts 里两个 select 的 options 表是「策展便利列表」,而它们各自的 description 描述的是一个开放域:

键	表里有	description 声明的域
timezone	17 个时区(UTC、America/New_York、Asia/Shanghai …)	「IANA zone used to resolve today()/daysFromNow, analytics date buckets, and rendered datetimes.」
currency	9 个币种(USD/EUR/GBP/JPY/CNY/INR/AUD/CAD/BRL)	「ISO 4217 code applied when a currency field omits its own.」

IANA 时区数据库有约 600 个 zone,ISO 4217 有约 180 个 code。

自 #5131 起,SettingsService.validatePatch 把 options 表当作穷尽式执行边界:PUT /api/settings/localization 写入 timezone: 'Europe/Zurich'(或 currency: 'CHF')会被 invalid_option 拒绝——尽管那是一个完全合法、运行时也能正常处理的 IANA 标识符。#5204 把同一张表接到 env 侧之后,OS_LOCALIZATION_TIMEZONE=Europe/Zurich 也会被忽略并回落(带响亮 error)。于是两扇门都关上了。

为什么值得判一下

两种读法都说得通,而它们指向相反的修法:

1. 表是 UI 便利列表,域是开放的 → 那么 service-settings: select 型 specifier 的 options 在保存期完全不校验 —— 声明的枚举不被强制 #5131 起写入侧就在越权执行,specifier 类型选错了。契约优先的修法在生产者侧:补全表(时区表可生成),或者换成带校验的 text(IANA/ISO 4217 校验),而不是在消费侧放宽。
2. 表就是「受支持集合」 → 那么现状正确,只是 description 在撒谎,该改的是文案(说清只支持列出的这些),顺便让 env 来源的 settings 值绕过 manifest 的 options 表校验 —— #5094 在写入 API 上堵住的洞，在 OS_* 覆盖这一侧原样敞开 #5204 的 error 消息不至于让运维困惑。

按 AGENTS.md Prime Directive #10 的反面(「never advertise a capability the runtime doesn't actually deliver」),现在这个形状两头都不干净:文档宣称 IANA / ISO 4217,执行面只认 17 / 9 个。

影响面(已核实的部分)

• 仓库内没有任何地方实际设置 OS_LOCALIZATION_TIMEZONE / OS_LOCALIZATION_CURRENCY(只有 packages/rest/src/rest-api-plugin.ts 的注释提到前者),所以不存在在库回归。
• 写入侧的拒绝自 service-settings: select 型 specifier 的 options 在保存期完全不校验 —— 声明的枚举不被强制 #5131 起就是活的,与 env 来源的 settings 值绕过 manifest 的 options 表校验 —— #5094 在写入 API 上堵住的洞，在 OS_* 覆盖这一侧原样敞开 #5204 无关;env 来源的 settings 值绕过 manifest 的 options 表校验 —— #5094 在写入 API 上堵住的洞，在 OS_* 覆盖这一侧原样敞开 #5204 只是让 env 侧与之一致。
• 未核实:是否有真实部署依赖未列出的时区/币种。这一条需要维护者的判断,不是代码能回答的。

建议

按读法 1 处理(生产者侧补全或换类型)看起来更符合 description 已经承诺的东西,但这是一次会影响公开 authoring 面的取舍(枚举语义 = 是否穷尽),交维护者定。

---

2026-08-06 契约拆分(services 座位):裁读法 1 的落地经 dev 实测确认需要 spec 声明位(valueDomain),按裁决预授权路径 contract-first 拆分 —— spec 半边见 #5933,本单收窄为 services 半边(manifest 对 timezone/currency 声明 valueDomain + 两扇门按域校验 + description 对齐;default_country 同洞第三例一并采纳或另立小单)。

Blocked-by: #5933

[os-zhuang]

分诊:决策箱(needs-user-decision),预挂 domain:services。

• 过时前提检查(origin/main):localization.manifest.ts 的 timezone(:34,策展 17 项)/currency(:114,策展 9 项)仍为 select,description 承诺 IANA / ISO 4217 开放域;service-settings: select 型 specifier 的 options 在保存期完全不校验 —— 声明的枚举不被强制 #5131 起写入侧按表穷尽拒绝、env 来源的 settings 值绕过 manifest 的 options 表校验 —— #5094 在写入 API 上堵住的洞，在 OS_* 覆盖这一侧原样敞开 #5204 起 env 侧一致 —— 「文档承诺开放域、执行面只认策展表」两头不干净,前提成立。
• 为什么进决策箱:两种读法(表 = UI 便利列表 vs 表 = 受支持集合)指向相反修法,「select options 是否穷尽语义」是公开 authoring 契约取舍;正文倾向读法 1(生产者侧补全或换带校验的 text)可作默认建议,但它改变 settings specifier 的类型语义,须维护者拍板。
• 域锚定:两修向落点都在 packages/services/service-settings(manifest 或 validatePatch)⇒ 预挂 services;若裁定需在 spec 侧新增「带格式校验的 text」specifier 类型,届时按 contract-first 拆分、spec 半边转 spec 座位。

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[claude]

裁决(2026-08-06):读法 1——timezone / currency 改为带格式校验的开放域。

timezone/currency 从 17/9 项策展表改为开放域 + 标准格式校验(IANA / ISO 4217,可用 Intl.supportedValuesOf 实现;垃圾值仍响亮拒收),兑现 description 已承诺、运行时(Intl 基)已交付的能力;#5131 的穷尽拒绝语义不动,只是词表从策展表换成标准域。维护者未提出「刻意策展」的运维理由,读法 2(人造稀缺)排除。

实现注意:牵 Setup UI 从下拉变输入;spec 侧若需新增「带格式校验 text」specifier,按 contract-first 拆半到 spec 车道。量级 M。

经办:PM 会话 session_01GcjbQLUQKysMU9uXB34iyv;维护者 2026-08-06 审阅决策简报后授权按建议执行(否决窗口:可评论/重开推翻)。

---

Generated by Claude Code

[os-zhuang]

【裁决落地】维护者 2026-08-06 批复全舰队决策箱评估报告(批复「同意」),本单裁定:

裁读法 1——策展 options 表定性为 UI 便利列表,不是执行边界:合法 IANA 时区与 ISO 4217 币种不得被 invalid_option 拒。实现路径:生产者侧补全,或换成带格式校验的 text(IANA/ISO 4217 校验);若后者需要 spec 新增带格式校验的 specifier,按 contract-first 拆分转 spec 座位,services 侧跟进。

流转:摘 needs-user-decision → pm:queue,归 services 车道。

评估与落地会话:session_01N3uGFF8teXbpgtbEJ1aYXu

---

Generated by Claude Code

[hotlong]

认领:PM 循环第 2 轮(services 车道)
会话:session_015a5qkLzpGXhLL2F5gvJ7dD
分支:claude/issue-5712-localization-open-domain
Worktree:objectstack-issue-5712
域:domain:services
文件面:packages/services/service-settings/src/manifests/localization.manifest.ts + 写入/env 校验路径(#5131/#5204 两扇门)+ 同包测试;⛔ 不触 packages/spec —— 若两条实现路径都绕不开 spec 新增 specifier,停下报 fork,由 PM 按 contract-first 拆分转 spec 座位
串行约束已清:同包 #5773(sms manifest)后轮串行;无其它在飞冲突

执行裁决:维护者 2026-08-06 批复裁读法 1(开放域 + 标准格式校验,策展表定性为 UI 便利列表),见 10:43Z 裁决评论;派发令随后。

---

Generated by Claude Code

[hotlong]

【实测报告 —— PM 机制假设 1 证伪,按预设条件报 fork】开发会话 session_015a5qkLzpGXhLL2F5gvJ7dD,分支 claude/issue-5712-localization-open-domain(未推;无 PR)。

1. 前提成立(origin/main d9cac60,worktree 内实跑)

DOOR1 timezone=Europe/Zurich -> SettingsValidationError
  [{"field":"timezone","code":"invalid_option","message":"Default timezone must be one of: UTC, America/Los_Angeles, ..."}]
DOOR1 currency=CHF -> [{"field":"currency","code":"invalid_option",
  "message":"Default currency must be one of: USD, EUR, ... BRL. Received 'CHF'."}]
DOOR2 (env) OS_LOCALIZATION_TIMEZONE=Europe/Zurich -> {"value":"UTC","source":"default"}
  + [SettingsService] env override ... is not a declared option ... IGNORED. Rejected value: 'Europe/Zurich'.

2. PM 假设 1:证伪。Intl.supportedValuesOf('timeZone') 不是 IANA 域

Node v22.22.2(仓库基线 engines.node >= 22,CI node-version: '22'),supportedValuesOf('timeZone') 返回 418 项,是 CLDR 规范名子集,不是 IANA 全域。被 Intl.DateTimeFormat 接受、却不在该表里的实测清单:

["UTC","Asia/Kolkata","Europe/Kyiv","Asia/Ho_Chi_Minh","Asia/Kathmandu",
 "Asia/Yangon","America/Argentina/Buenos_Aires","US/Eastern","GMT"]
   ...其中今天就写在策展表里的: ["UTC","Asia/Kolkata"]

两处要害:

• UTC 是本 specifier 自己的 default,却不在该表内 —— 直接照搬会拒掉平台默认值;
• Asia/Kolkata 是当前 17 项策展表里的在库取值,照搬即构成本 issue 明令禁止的「既有策展值回归」。

方向与工单预判相反:ICU 保留的是旧名(Asia/Calcutta 在表内,Asia/Kolkata 不在;Europe/Kiev 在表内,Europe/Kyiv 不在)。即:用它当词表,等于把 #5712 这个缺陷从 17 项放大到 419 项重演一遍,Europe/Kyiv 这类 IANA 现行规范名仍被 invalid_option 拒。

币种侧假设成立:supportedValuesOf('currency') = 162 项,CHF 在内、XYZ 不在、9 个策展值全在。缺口很小且多为非交易码:["VED","XAU","XAG","USN","CHE","CHW","UYW"]。

仓库内已有的「合法 IANA 时区」判定就是探针法,两处都是:packages/core/src/security/resolve-authz-context.ts:449 的 isValidTimeZone(消费侧,new Intl.DateTimeFormat(...) 试构造),以及 localization.manifest.test.ts:33 的既有断言 every timezone option is a valid IANA zone。消费侧接受的域 = 探针域,写入侧无论用 17 项还是 419 项都比它窄。

3. PM 假设 2:成立

两扇门同源:validatePatch 走 declaredOptionValues(spec.options),env 侧走 registerManifest 预算的 reg.optionTables(同一 spec.options),两者共用 firstRejectedOption 比较(settings-service.ts:73/107)。换词表两门自动一致。附带:两门都以 OPTION_BEARING_TYPES(select/radio/multiselect)为闸,所以把 specifier 换成 text 也会同时放开两门 —— 但那样就没有任何东西再拒 Mars/Olympus。

4. PM 假设 3:UI 侧结论分岔(⛔ 未跨仓改动)

manifest 连同 options 整体进 GET /api/settings/:ns 载荷(SettingsNamespacePayloadSchema,envelope.conformance.test.ts:191 有 round-trip)。

• 走生产者侧补全:objectui 不需要改,下拉直接变 419 项(时区 options JSON 约 22.8 KB,币种 162 项约 7.8 KB,每次 settings 页加载都带);invalid_option 报错文案会把 419 项全量 join,单条消息约 7.3 KB,env 拒收日志同理。
• 走声明式开放域 + 保留策展表当 UI 便利列表:两扇门(API / env)达标,但 Setup UI 仍只提供策展 17 项,除非 objectui 加自由输入/combobox —— 这是「需要 objectui 改动才能不劣化」的那一档,按令只报告不跨仓。

i18n 侧无风险:settings-translation-coverage.test.ts 明确排除 option 标签。

5. 为什么 STOP:裁决标题在现行 spec 里不可表达

裁决标题是「策展 options 表定性为 UI 便利列表,不是执行边界」。要照此实现,manifest 必须能说出「本表非穷尽,执行边界是某标准域」。现行 SpecifierSchema 的值约束只有 options / pattern / min / max / minLength / maxLength,没有任何「域」声明位;实测夹带一个 format 键会被 Zod 直接剥掉:

after SettingsManifestSchema.parse, specifier.format = undefined

于是两条备选路径各自撞墙:

• 生产者侧补全:不动 spec,可实现,但按第 2 节实测无法兑现「合法 IANA 时区不得被拒」(Europe/Kyiv / Asia/Kolkata / US/Eastern 仍拒),且把 UI 便利列表变成 419 项执行边界 —— 与裁决标题相反;另外词表随宿主 ICU 版本浮动,等于让公开载荷与受理集合成为运行时函数。
• 换带格式校验的 text:pattern 只能约束形状,而 Mars/Olympus 形状完全合法 —— 无法满足「垃圾值响亮拒收」,除非在 spec 新增带格式校验的 specifier。

两条都不能在不动 spec 的前提下满足裁决全部验收项 ⇒ 命中工单预设的 fork 条件,交 PM 按 contract-first 拆分。完整方案对比(含建议:在 SpecifierSchema 上加一个闭合枚举的 valueDomain,复用面已量出:本 manifest 内 timezone / currency / default_country 三个键都要它 —— default_country 今天用 ^[A-Za-z]{2}$ 校验 ISO 3166,ZZ 照收)随开发报告回 PM。

币种半边可单独达标:若维护者要「零 spec 改动、先落一半」,currency 走生产者侧补全能满足全部验收项(CHF 收、XYZ 拒、9 个策展值不回归)。但两键同属一个语义决定,先落一半有被 spec 侧结论推翻返工的风险,建议合并决策。

6. 顺带:范围外发现已另立

#5932 —— 同一个 validatePatch 里,min / max / minLength / maxLength 四类声明了但完全没执行(auth.password_min_length 声明 min: 6,实测可写入 1)。未认领,交 triage。

---

Generated by Claude Code