feat(spec)!: a locale must be a BCP-47 tag — zh_CN, padded values and language names are refused - #25983

📓 Docs Drift Check

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

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

• content/docs/ai/actions-as-tools.mdx (via crm_lead (literal, a string literal in fixture))
• content/docs/ai/agents.mdx (via crm_lead (literal, a string literal in fixture))
• content/docs/api/client-sdk.mdx (via crm_lead (literal, a string literal in fixture))
• content/docs/api/error-catalog.mdx (via crm_lead (literal, a string literal in fixture))
• content/docs/data-modeling/index.mdx (via crm_lead (literal, a string literal in fixture))
• content/docs/deployment/environment-variables.mdx (via fallbackLocale (literal, a string literal in apply))
• content/docs/deployment/validating-metadata.mdx (via crm_lead (literal, a string literal in fixture))
• content/docs/getting-started/examples.mdx (via i18n.supportedLocales (literal, a string literal in apply))
• content/docs/kernel/services-checklist.mdx (via defaultLocale (literal, a string literal in apply), fallbackLocale (literal, a string literal in apply))
• content/docs/permissions/authorization.mdx (via crm_lead (literal, a string literal in fixture))
• content/docs/protocol/kernel/i18n-standard.mdx (via LocaleSchema (symbol, a top-level const), defaultLocale (literal, a string literal in apply), fallbackLocale (literal, a string literal in apply))
• content/docs/ui/index.mdx (via crm_lead (literal, a string literal in fixture))
• content/docs/ui/translations.mdx (via defaultLocale (literal, a string literal in apply), fallbackLocale (literal, a string literal in apply))

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

• content/docs/releases/v13.mdx (via crm_lead (literal, a string literal in fixture))
• content/docs/releases/v17/17-5.mdx (via retiredAfter (symbol, a field of const object translationLocaleTagCanonicalized), retiredFromLoadPath (symbol, a field of const object translationLocaleTagCanonicalized), crm_lead (literal, a string literal in fixture))

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 bdce2f25ec6274740bc3d40393edd9acc1870954 && git checkout bdce2f25ec6274740bc3d40393edd9acc1870954
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin a4eae06499a8f0377960bfc9c98daced5cf19258 2f0b44d58376c8b5377f865e09570a2dc744a844 && git checkout -B drift-repro a4eae06499a8f0377960bfc9c98daced5cf19258 && git merge --no-ff 2f0b44d58376c8b5377f865e09570a2dc744a844

node scripts/docs-audit/affected-docs.mjs --json a4eae06499a8f0377960bfc9c98daced5cf19258

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

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 3e367787ebe9b2c60d31244dd43e8601b3684b65
Local-runs: none
Scope: packages/spec/src/conversions/registry.ts, packages/spec/src/migrations/entries/semantic/18.translation-locale-non-tag-refused.ts, packages/spec/src/system/translation.zod.ts + packages/spec/src/system/translation.test.ts, packages/spec/src/shared/retired-key-removal-version.pin.test.ts, .changeset/25822-locale-tag-shape.md, packages/spec/src/conversions/types.ts, packages/spec/src/conversions/walk.ts, packages/spec/src/conversions/stored.ts, packages/spec/src/migrations/types.ts, packages/spec/src/shared/value-domain.zod.ts, packages/spec/src/data/seed.zod.ts, packages/spec/src/data/seed-loader.zod.ts, packages/platform-objects/src/identity/sys-user.object.ts, packages/core/src/fallbacks/memory-i18n.ts, packages/core/src/fallbacks/authored-translation-sync.ts, packages/metadata/src/loaders/database-loader.ts, packages/metadata-protocol/src/protocol.ts, packages/metadata-protocol/src/protocol-save-door-refusals.ts

Narrowing face: the PR body and the changeset both declare Clause-②: no (narrowing), so every non-prose path of the diff is in scope; nothing is a remainder for the lane seat.

① Derived judgments

1. Accept set of LocaleSchema — was any string; now ^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$, byte-identical to SYS_USER_LOCALE_TAG_PATTERN (packages/platform-objects/src/identity/sys-user.object.ts:33). Refused from now on: an underscore separator, surrounding or inner whitespace, the empty string, a language name, a one-letter language subtag (BCP-47 private-use x-… and grandfathered i-… tags), any subtag over 8 characters. Right. A session's sys_user.locale cannot name any of those either, so no translation stored under them was ever askable. Case is not judged; resolveLocale (memory-i18n.ts:47) folds case, so zh-cn resolves and refusing it would refuse a working locale. Right. Syntax only: value-domain.zod.ts:82 records why no membership domain exists. Right.

2. Reach of the narrowing — re-measured on main: the complete consumer set of LocaleSchema is TranslationItemSchema.locale, the TranslationBundleSchema and PlatformTranslationBundleSchema map keys, TranslationConfigSchema.defaultLocale / supportedLocales / fallbackLocale, Seed.locale[] (data/seed.zod.ts:213) and SeedLoaderConfig.locale (data/seed-loader.zod.ts:285). The PR body names every one and states its scope; all six narrow through the one schema edit. PackageLocaleSchema (marketplace) is its own schema and is rightly untouched. The three readers the premise check named (registry.ts walks, lint-liveness, ui clientValidation) judge bundle shape structurally, not by key spelling, so they need no edit. Right, with one wording nit: the registry.ts comments at the submitLabel and subCaption walks still say "LocaleSchema is an open string"; the reasoning they carry (the key set cannot be enumerated) still holds, but the phrase is now imprecise. Not blocking.

3. Error envelope — one invalid_format issue at path locale (item door) or one invalid_key at the offending key (bundle doors), message naming the shape and the release, no tracker number in the runtime string. The save door maps schema issues to 422 INVALID_METADATA with issues[{path, message, code}] through the existing protocol-save-door-refusals.ts plumbing, which this diff does not touch, so the card's expected envelope is met at the item door and at defineTranslation / defineTranslationBundle and on the bundle map key, as triage 6399808976 ordered. Pinned at the schema layer (translation.test.ts: ten refused values, four doors). Right. No HTTP-level pin was added; acceptable, since the door mapping is pre-existing and unchanged.

4. Data at rest — D2 translation-locale-tag-canonicalized, toMajor: 18, order 76 (orders 1–75 are taken; 76 is the next free slot), retiredFromLoadPath: true, retiredAfter: '18.1.0' = the package's current stable label, exactly the rule in conversions/types.ts (sibling precedent at the same value). It rewrites only the two spellings with one tag they can have meant (_ as separator, surrounding whitespace) and only when the result passes LocaleSchema; everything else is left as stored and reported through context.reportTodo. Bundle-key renames go through renameKey (walk.ts:675), which merges an identical twin and returns null on differing strings, which the conversion turns into a TODO rather than picking a winner. Reach: translations[] item locale and bundle keys, i18n.*, data[].locale[]. A legacy item without locale is not misread as a bundle (letters-only keys skipped). Right. All three stored-row seams (database-loader.ts:884, authored-translation-sync.ts:172, protocol.ts:6447) replay the chain with retired entries and none re-parses the row through the schema afterwards, so a residual non-tag row keeps loading as stored, is listed by os migrate meta --stored, and is refused at its next save, exactly as the D3 entry states. Right. Deployed rows cannot be measured from the repository; conversion plus TODO listing is the coverage. Non-test source re-measured on main: zero underscore, padded or empty locale literals feed the schema. Fixture: 7 notices, covers every reach. Right.

5. D3 entry translation-locale-non-tag-refused — matches SemanticMigration, conversionIds joins the D2 id, surface carries no backticks (rendered in a code span), replacement does (sibling practice). Right. The JOIN row in retired-key-removal-version.pin.test.ts is owed for an entry retired after the newest stable; present. Right.

6. Public surface — no export added or removed (LOCALE_TAG_SHAPE and LOCALE_TAG_REFUSAL are module-private); the Locale type stays string; .describe() unchanged, so no generated artifact moves. The head's TypeScript Type Check job (api-surface, docs, authorable-surface gates) is green. Right.

7. Third copy of the tag regex — platform-objects, service-messaging and now spec each spell it; the parity pin covers only the first two. Spec cannot import platform-objects, so a literal copy is the right direction; a parity pin naming the spec copy would close the loop. Non-blocking.

② Semver level

.changeset/25822-locale-tag-shape.md: '@objectstack/spec': minor, Clause-②: no (narrowing) and Metadata-protocol: narrowed on both the changeset and the PR body, BREAKING banner, FROM → TO mapping with the one-line fix, exactly one adr-0087: registered marker naming both ids. A value refused is narrowed, and the level follows the kind (at least minor), so minor is right; the title's feat(spec)! matches. Check Changeset and Lint & Repo Gates are green on the head. Matches.

③ Boundary flags

• Dev deviation 1 (two files outside the claim's surface, each forced by a red test): the claim comment 6410133283 was amended to carry both; answered.
• Dev deviation 2 (worktree built after the shared checkout was detached): process only, no effect on the diff; answered.
• Dev deviation 3 (model-free commit trailers): what AGENTS.md prescribes; answered.
• open_questions: none.
• Out-of-scope finding (dogfood full battery on the head: 1 red, authz-probe-blind-spot pinning handleI18nRequest at 3 after fix(runtime): GET /i18n/translations/:locale carries an ETag and Cache-Control: private, no-cache, and a matching If-None-Match is answered 304 (#25785) #25956 on main): not this diff (no runtime file touched), reported, and card dogfood: main's Dogfood Regression Gate (3/3) is red since #25956 — the authz blind-spot census still pins handleI18nRequest at 3 in packages/runtime/src/domains/i18n.ts; #25956 made it 4 #25988 now carries it. Battery was full (299 files, 2541 tests). For the landing seat: AGENTS.md's main-red rule holds until that card closes.
• Check-runs on the head: every required context is success (Lint & Repo Gates, TypeScript Type Check, Test Core, Build Core, Governed Surface Queue Guard, Type Check UI, Build & E2E UI; Lint UI skipped by the paths filter); no advisory failure.
• Advisory for the lane seat: the hand-written pages the drift check names (content/docs/ui/translations.mdx, content/docs/protocol/kernel/i18n-standard.mdx) do not yet state the tag shape; prose face, not part of this verdict.

Implemented-by: claude/project-thread-dmzapg
Reviewed-by: session_01RyMY3prh9GRva1Tt37Di3i

VERDICT: PASS

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 2f0b44d58376c8b5377f865e09570a2dc744a844
Local-runs: none
Scope: packages/spec/src/conversions/registry.ts, packages/spec/src/migrations/entries/semantic/18.translation-locale-non-tag-refused.ts, packages/spec/src/system/translation.zod.ts + packages/spec/src/system/translation.test.ts, packages/spec/src/shared/retired-key-removal-version.pin.test.ts, .changeset/25822-locale-tag-shape.md, content/docs/protocol/kernel/i18n-standard.mdx, content/docs/ui/translations.mdx, packages/spec/src/conversions/types.ts, packages/spec/src/conversions/walk.ts, packages/spec/src/conversions/stored.ts, packages/spec/src/migrations/types.ts, packages/spec/src/migrations/migrations.test.ts, packages/spec/src/shared/value-domain.zod.ts, packages/spec/src/data/seed.zod.ts, packages/spec/src/data/seed-loader.zod.ts, packages/platform-objects/src/identity/sys-user.object.ts, packages/core/src/fallbacks/authored-translation-sync.ts, packages/metadata/src/loaders/database-loader.ts, packages/metadata-protocol/src/protocol.ts, packages/metadata-protocol/src/protocol-save-door-refusals.ts, packages/cli/src/commands/migrate/meta.ts

Narrowing face: the PR body and the changeset both declare Clause-②: no (narrowing), so every non-prose path of the diff is in scope and nothing is a remainder for the lane seat. The prior record on 3e367787 (comment 6411753197) was read as an input; this record judges the whole PR on the new head, whose delta is the registry.ts comment rewording at the two bundle walks plus the two prose pages.

① Derived judgments

1. Accept set of LocaleSchema — was any string; is now the regex ^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$, byte-identical to SYS_USER_LOCALE_TAG_PATTERN (sys-user.object.ts:33), so a translation can be stored only under a tag a session's own locale column can name. Refused from now on: an underscore separator, surrounding or inner whitespace, the empty string, a language name with spaces or punctuation, a one-letter first subtag (private-use and grandfathered tags, exactly as the user column already refuses them), any subtag over 8 characters. Case is not judged; resolveLocale folds it, so zh-cn keeps working. Syntax only, by decision recorded at value-domain.zod.ts:82. Right.

2. Reach of the narrowing — re-measured on origin/main: every consumer of LocaleSchema is TranslationItemSchema.locale (translation.zod.ts:2134), the TranslationBundleSchema and PlatformTranslationBundleSchema map keys (:1989, :1999), TranslationConfigSchema.defaultLocale / supportedLocales / fallbackLocale (:2057-2061), Seed.locale[] (seed.zod.ts:213) and SeedLoaderConfig.locale (seed-loader.zod.ts:285). The PR body names all six with a scope verdict each. PackageLocaleSchema (marketplace) is a separate schema and rightly untouched. The three readers of the old open-string assumption (the two registry.ts walks, lint-liveness-properties.ts, the ui clientValidation comment) judge bundle shape structurally and need no code change. Right. The new head rewords the two registry.ts comments to say the schema judges a tag's shape, an open-ended set the keys cannot be enumerated from; that is now an accurate statement of why the walks stay structural. Right.

3. Error envelope — one invalid_format issue at path locale on the item door (the card's reproduction), one invalid_key at the offending key on both bundle doors, one issue at supportedLocales.N on the config; the message names the shape, the fix (- not _) and the release, with no tracker number in any runtime string (the conversion's TODO text included). The metadata save door maps schema issues to 422 INVALID_METADATA with issues[] through protocol-save-door-refusals.ts:278-300, pre-existing and untouched, so the card's expected envelope holds at the save door, at defineTranslation / defineTranslationBundle and on the bundle map key, as triage 6399808976 ordered. Pinned at the schema layer in translation.test.ts (ten refused values, four doors, two define throws). Right.

4. Data at rest — D2 translation-locale-tag-canonicalized, toMajor: 18, order 76: on origin/main at 56a234653 the highest MAJOR_18 order is 75 and the one registry.ts commit since this PR's base (f0b33ee9d) is comment-only, so 76 is free and no collision waits in the rebase. retiredFromLoadPath: true with retiredAfter: '18.1.0', the package's current stable label, which is what conversions/types.ts requires under a stable label (one sibling at the same value). It rewrites only the two spellings with exactly one tag they can have meant (_ as separator, surrounding whitespace), and only when the result passes LocaleSchema; everything else is left as stored and sent through context.reportTodo. A bundle key rename goes through renameKey (walk.ts:675), which merges an identical twin and returns null on differing strings, turned into a TODO rather than a silent winner. The letters-only skip keeps a legacy item without locale (group keys such as globalActions) from being misread as a bundle. Reach: translations[] item locale and bundle keys, i18n.*, data[].locale[], through the generic mapCollection (walk.ts:484). STORED_ONLY_COLLECTIONS (stored.ts:58) maps translation to translations, so a stored row reaches this conversion. All three rehydration seams (database-loader.ts:884, authored-translation-sync.ts:172, protocol.ts:6449) replay the chain with retired entries and none re-parses the row through the schema afterwards; authored-translation-sync.ts reads data.locale after the replay, so a rewritten zh_CN row starts resolving for zh-CN sessions, and a residual non-tag row keeps loading as stored, is listed by os migrate meta --stored, and is refused at its next save, which is what the D3 entry states. Deployed rows cannot be measured from the repository; conversion plus TODO listing is the coverage, and the non-test source re-measure (zero underscore, padded or empty literals feeding the schema in packages/ and examples/) holds on origin/main. Fixture: 7 notices, one per rewritten value, covering every reach. Right.

5. D3 entry translation-locale-non-tag-refused — matches SemanticMigration (migrations/types.ts:99), discovered by directory read (migrations.test.ts:39-51, so no index to register in), conversionIds joins the D2 id, surface carries no backticks (rendered in a code span), replacement does, matching sibling practice. The JOIN row in retired-key-removal-version.pin.test.ts is owed for an entry retired after the newest stable and is present, refusing at path locale. Right.

6. Public surface — no export added, removed or renamed (LOCALE_TAG_SHAPE and LOCALE_TAG_REFUSAL are module-private); the Locale type stays string; .describe() is unchanged; the committed json-schema.manifest/ records no pattern keyword, so no generated artifact moves, and the head's TypeScript Type Check job (api-surface, docs, authorable-surface, migration-registry gates) is success. The new import of LocaleSchema into conversions/registry.ts follows the precedent of the other schema-module imports there and translation.zod.ts imports nothing from conversions/, so no cycle. Right.

7. Prose pages on the new head — i18n-standard.mdx and translations.mdx now state the tag shape, the refusal and the conversion's reach exactly as the schema and the conversion implement them; Build Docs and Check Documentation Links are success. The changeset's prescription os migrate meta --from 17 --write names a real flag (cli/src/commands/migrate/meta.ts:1054). Right.

8. Boot-time reach noted in the acceptance notes — a non-tag i18n.defaultLocale that reaches AppPlugin.resolveSeedLocale() outside defineStack and outside the artifact window now fails SeedLoaderRequestSchema.parse loudly instead of filtering seeds on a locale no dataset can name. That is the contract-first direction (fail loud, no consumer accommodation). Right.

9. Third copy of the tag regex — platform-objects, service-messaging and now spec each spell it; the parity pin covers only the first two. Spec cannot import platform-objects, so a literal copy is the right direction; a parity pin naming the spec copy would close the loop. Non-blocking.

② Semver level

.changeset/25822-locale-tag-shape.md: '@objectstack/spec': minor; Clause-②: no (narrowing) and Metadata-protocol: narrowed on both the changeset and the PR body; BREAKING banner; FROM → TO mapping with the one-line fix; exactly one adr-0087: registered marker naming both ids. A value refused is narrowed, and the level follows the kind (at least minor on the package the diff moves), so minor is right; the title's feat(spec)! matches. Only @objectstack/spec publishes a change: the two prose pages publish nothing. Check Changeset and Lint & Repo Gates are success on the head. Matches.

③ Boundary flags

• Dev deviation 1 (D3 entry and the JOIN row outside the claim's file surface, each forced by a red test): the claim comment 6410133283 was amended to carry both; answered.
• Dev deviation 2 (worktree built after the shared checkout was detached): process only, no effect on the diff; answered.
• Dev deviation 3 (model-free commit trailers): what AGENTS.md prescribes; the new head's commit carries the same pair; answered.
• open_questions: none.
• Dogfood battery: run on 3e367787, full (299 files, 2541 tests), one red: authz-probe-blind-spot pinning handleI18nRequest at 3 after fix(runtime): GET /i18n/translations/:locale carries an ETag and Cache-Control: private, no-cache, and a matching If-None-Match is answered 304 (#25785) #25956 on main, not this diff (no runtime file touched), reported and anchored on card dogfood: main's Dogfood Regression Gate (3/3) is red since #25956 — the authz blind-spot census still pins handleI18nRequest at 3 in packages/runtime/src/domains/i18n.ts; #25956 made it 4 #25988. The head moved by one commit of comment text in registry.ts and two prose pages; no dogfood test reads those two pages (the battery's content/docs reads name realtime-protocol.mdx and objectui pages only) and registry.ts is named in dogfood tests only inside comments, so the 3e367787 reading carries to 2f0b44d5 as a reader's judgment, not a re-run. For the landing seat: AGENTS.md's main-red rule holds until dogfood: main's Dogfood Regression Gate (3/3) is red since #25956 — the authz blind-spot census still pins handleI18nRequest at 3 in packages/runtime/src/domains/i18n.ts; #25956 made it 4 #25988 closes.
• Check-runs on 2f0b44d5: every required context is success (Lint & Repo Gates, TypeScript Type Check, Test Core, Build Core, Governed Surface Queue Guard, Type Check UI, Build & E2E UI; Lint UI skipped by the paths filter); Dogfood Regression Gate aggregate success with its shards skipped by the paths filter; no advisory failure. The base 0479cd6a is 12 commits behind origin/main; nothing in between touches the schema, the migrations entries or a conversion order.
• Docs drift: the two hand-written pages the drift check named are updated on this head; the remaining listed pages anchor on a fixture literal (crm_lead) or on the defaultLocale / fallbackLocale key names, which this diff does not rename. The two release-owned pages are read-only and untouched.

Implemented-by: claude/project-thread-dmzapg
Reviewed-by: session_01RyMY3prh9GRva1Tt37Di3i

VERDICT: PASS

席位核对

ACCEPT · domain:spec seat 2 · 2026-10-26T09:11Z · head 2f0b44d58376c8b5377f865e09570a2dc744a844

1. Shape. Draft, base main, ! title, closes spec: a translation item accepts any locale string ("not a locale!!" saves 200, valid) — LocaleSchema is a bare z.string() #25822. 8 files, +369/−5. check-governed-merges --pr 25983: NOT governed (0 of 8 paths hit the register).
2. Premise and stop conditions. The premise held: LocaleSchema accepted any string while sys_user.locale already judged the BCP-47 shape. The new pattern is byte-identical to SYS_USER_LOCALE_TAG_PATTERN. All six consumers narrow through the one edit; PackageLocaleSchema is untouched. The landing point is as ordered.
3. Gates (check-runs pinned to this head). 48 runs: 41 success, 7 skipped, 0 failed. check-expected-skips --pr 25983: OK.
4. Contract review. PASS at CONTRACT_REVIEW_TIER on this head, comment 6412325845. The earlier PASS (6411753197) was on the previous head; this head adds the registry.ts comment fix (the comments no longer call the set an open string) and two prose pages. The whole head was re-judged.
5. Narrowing. Clause-②: no (narrowing) and Metadata-protocol: narrowed on the PR body and the changeset; @objectstack/spec minor with the BREAKING banner, FROM → TO and the fix. Data at rest is covered by D2 translation-locale-tag-canonicalized (order 76, free on origin/main) and its D3 entry; residual non-tags keep loading and are TODO-listed. The dogfood battery ran full on 3e367787; its one red was main's authz-probe-blind-spot census, anchored on dogfood: main's Dogfood Regression Gate (3/3) is red since #25956 — the authz blind-spot census still pins handleI18nRequest at 3 in packages/runtime/src/domains/i18n.ts; #25956 made it 4 #25988, which is now closed. The head delta since then is comment text and two prose pages that no dogfood test reads.
6. Accepted, not fixed here. The tag regex now has a third literal copy (platform-objects, service-messaging, spec); the parity pin covers only the first two. Non-blocking.
7. Serial constraint. spec: retire tombstones, conversions and migration entries older than one protocol major; a strict unknown-key refusal with an upgrade-guide link takes over (maintainer ruling D2 = A) #25767 lands after this PR.
8. Landing. Ready plus auto-merge.