@stackonward/cli 1.4.0 → 1.5.0

package/dist/resources/templates/base/.claude/docs/architecture.md

@@ -52,6 +52,10 @@ Use actual paths in [Stack](stack.md). Nuxt routes belong in `app/pages/`, serve
 
 Request/response types stay beside the service/API owner. Component props/emits stay with the component. A type moves to a shared owner only when callers share semantics, not merely field names.
 
+Directories, modules and packages carry owner context; child files and symbols keep only the minimum responsibility. Within an owner use short names such as `Header`, `Config`, `Status`, `Menu`, `EventInput` and `items`; across owners add only the shortest qualifier, such as `SiteHeader`, `LocaleMenu`, `GTMOptions` or `GA4Event`. Never exchange one redundant prefix for another: `MarketingHeader` -> `PublicHeader` remains forbidden.
+
+Directories, packages and ordinary TypeScript modules use kebab-case; Vue composables use `useX.ts`; Vue component files and types use PascalCase; variables/functions use camelCase; only fixed invariants use `UPPER_SNAKE_CASE`. Framework routes and endpoints keep framework syntax. Generic transforms use business-free responsibility names. External identifiers such as `purchase`, `login` and `gateway_*` remain unchanged. Vague standalone or catch-all names such as `helper`, `utils`, `common` and `manager` are forbidden; choose a precise owner and responsibility. `temp`, `new` and `final` naming residue is forbidden. Search owners, siblings and usages before naming or renaming; update all references and delete superseded names together.
+
 | Type                       | Owner                                         |
 | -------------------------- | --------------------------------------------- |
 | HTTP request/response      | API or server contract                        |

package/dist/resources/templates/base/AGENTS.md

@@ -67,6 +67,21 @@ For non-trivial additions, declare `PLACEMENT/NAMING` (owner, name, kind, respon
 
 External calls, user-selectable alternatives, variable business policy, replaceable technology, standard extension points and multi-tenant behavior require `EXTENSIBILITY-INTENT`: signal, current and expected implementations, confidence, pattern, interface/configuration first, and exact files a second adapter would change. Otherwise state `NO-ABSTRACTION-JUSTIFICATION` and its refactor trigger.
 
+## Owner-Scoped Naming (CRITICAL)
+
+Directories, modules and packages are namespaces. Child files and symbols **MUST** keep only the minimum responsibility-bearing name and **MUST NOT** repeat the owner or replace one redundant caller prefix with another (`MarketingHeader` -> `PublicHeader` remains forbidden).
+
+- Inside an explicit owner, use short names such as `Header`, `Config`, `Status`, `Menu`, `EventInput` or `items`; across owners, add only the shortest required qualifier, such as `SiteHeader`, `LocaleMenu`, `GTMOptions` or `GA4Event`.
+- Names describe responsibility, never the first caller, page, brand, task or conversation. Pure transforms use business-free names; business and protocol nouns remain only when they enforce that contract.
+- Directories, packages and ordinary TypeScript modules use kebab-case; Vue composables use `useX.ts`; Vue component files and types use PascalCase; variables and functions use camelCase; only true fixed invariants use UPPER_SNAKE_CASE. Framework route and endpoint files follow framework syntax.
+- External or business-owned identifiers such as `purchase`, `login` and `gateway_*` are semantic contracts, not code-name redundancy, and remain unchanged.
+- Vague standalone or catch-all names such as `helper`, `utils`, `common` and `manager` are forbidden; choose a precise owner and responsibility. `temp`, `new` and `final` naming residue is forbidden. Search owners, siblings and usages before naming or renaming; update all references and delete superseded names together.
+- Nuxt component directories remain namespaces: preserve default path-aware auto-naming and never set global `pathPrefix: false`. Local explicit imports may use the short name; cross-owner and global auto-imports use the path qualifier.
+
+✅ `analytics/events.ts::EventInput`, `components/site/Header.vue` -> `SiteHeader`, `useTracking`, `GTMOptions`, `GA4Event`
+
+❌ `types/marketing-analytics.ts`, `MarketingHeader`, `PublicHeader`, `GoogleTagManagerOptions`
+
 ---
 
 # AI Execution Standard

package/dist/resources/templates/base/CLAUDE.md

@@ -67,6 +67,21 @@ For non-trivial additions, declare `PLACEMENT/NAMING` (owner, name, kind, respon
 
 External calls, user-selectable alternatives, variable business policy, replaceable technology, standard extension points and multi-tenant behavior require `EXTENSIBILITY-INTENT`: signal, current and expected implementations, confidence, pattern, interface/configuration first, and exact files a second adapter would change. Otherwise state `NO-ABSTRACTION-JUSTIFICATION` and its refactor trigger.
 
+## Owner-Scoped Naming (CRITICAL)
+
+Directories, modules and packages are namespaces. Child files and symbols **MUST** keep only the minimum responsibility-bearing name and **MUST NOT** repeat the owner or replace one redundant caller prefix with another (`MarketingHeader` -> `PublicHeader` remains forbidden).
+
+- Inside an explicit owner, use short names such as `Header`, `Config`, `Status`, `Menu`, `EventInput` or `items`; across owners, add only the shortest required qualifier, such as `SiteHeader`, `LocaleMenu`, `GTMOptions` or `GA4Event`.
+- Names describe responsibility, never the first caller, page, brand, task or conversation. Pure transforms use business-free names; business and protocol nouns remain only when they enforce that contract.
+- Directories, packages and ordinary TypeScript modules use kebab-case; Vue composables use `useX.ts`; Vue component files and types use PascalCase; variables and functions use camelCase; only true fixed invariants use UPPER_SNAKE_CASE. Framework route and endpoint files follow framework syntax.
+- External or business-owned identifiers such as `purchase`, `login` and `gateway_*` are semantic contracts, not code-name redundancy, and remain unchanged.
+- Vague standalone or catch-all names such as `helper`, `utils`, `common` and `manager` are forbidden; choose a precise owner and responsibility. `temp`, `new` and `final` naming residue is forbidden. Search owners, siblings and usages before naming or renaming; update all references and delete superseded names together.
+- Nuxt component directories remain namespaces: preserve default path-aware auto-naming and never set global `pathPrefix: false`. Local explicit imports may use the short name; cross-owner and global auto-imports use the path qualifier.
+
+✅ `analytics/events.ts::EventInput`, `components/site/Header.vue` -> `SiteHeader`, `useTracking`, `GTMOptions`, `GA4Event`
+
+❌ `types/marketing-analytics.ts`, `MarketingHeader`, `PublicHeader`, `GoogleTagManagerOptions`
+
 ---
 
 # AI Execution Standard

package/dist/resources/templates/go-backend/.dockerignore

@@ -1,6 +1,28 @@
 .git
+.github
+.claude
+.husky
+.idea
+.vscode
 .env
 .env.*
-bin
-coverage.*
-node_modules
+.npmrc
+*.key
+*.pem
+
+bin/
+coverage/
+coverage.out
+coverage.html
+node_modules/
+**/node_modules/
+tmp/
+
+*.log
+.DS_Store
+
+AGENTS.md
+CLAUDE.md
+README.md
+deploy.config.json
+docs/

package/dist/resources/templates/go-backend/deploy.config.json

@@ -0,0 +1,26 @@
+{
+  "schemaVersion": 1,
+  "name": "{{projectName}}",
+  "profile": "go-service",
+  "source": {
+    "verify": {
+      "executable": "make",
+      "args": ["check"]
+    },
+    "build": {
+      "executable": "make",
+      "args": ["build"]
+    }
+  },
+  "image": {
+    "dockerfile": "Dockerfile",
+    "context": ".",
+    "repository": "{{projectName}}",
+    "platform": "linux/amd64"
+  },
+  "environments": {
+    "production": {
+      "target": "registry-only"
+    }
+  }
+}

package/dist/resources/templates/go-backend/docs/runtime-provenance.json

@@ -112,8 +112,9 @@
     },
     {
       "target": "migrations/000001_infrastructure.up.sql",
-      "target_template_sha256": "7805df78ce83bb5e7c7bdf8452b4da904d85c9251e25fa37cc24a87262b2d179",
-      "transformation": "Extract seven generic baseline tables and complete command replay table as eight infrastructure owners, preserving fields, defaults, sequences, primary/unique/check constraints, indexes and comments. Keep four log partition parents and add default partitions. Preserve delivery identity and schema-version immutable triggers plus operation-log finalization guard. Omit platform event-catalog schema binding trigger; product producers assign their own schema_version without platform table queries.",
+      "target_template_sha256": "fe971c4bd743fda85d557c5f9634dae6347f5032414cb24d6e3f85dc5468457b",
+      "transformation": "source-adapted",
+      "details": "Defines eleven business-neutral infrastructure owner tables: seven retained OneX baseline tables, command replay with mandatory principal-scoped five-field identity, and three StackOnward-owned integration-event inbox, subscriber-receipt and aggregate-checkpoint tables. The three integration-event tables and their transition guards are not attributed to the listed OneX origins. Four log partition parents retain default partitions; outbox identity/schema immutability and operation-log finalization guards remain. The platform event-catalog binding trigger stays excluded because independent producers assign schema_version without platform database queries.",
       "origins": [
         {
           "source": "backend/migrations/000001_platform_baseline.up.sql",
@@ -127,8 +128,9 @@
     },
     {
       "target": "migrations/000001_infrastructure.down.sql",
-      "target_template_sha256": "142598fb71a4e4b9586455495064ddaf62d0c67c3ffd95d7fa7c162b0a9abaca",
-      "transformation": "Reverse only the eight product infrastructure owners, their dependent partitions/sequences and three retained guard functions. Keep shared pgcrypto extension.",
+      "target_template_sha256": "7e7b9e9682128e98eeee02cbbf4eafd4df255d67727896669e12244b76bc4cfc",
+      "transformation": "source-adapted",
+      "details": "Reverses the eleven business-neutral infrastructure owner tables and six associated guard functions; dependent partitions, triggers and sequences are removed through table cascade. The three integration-event tables and their guards are StackOnward-owned rather than derived from the listed OneX origins. The shared pgcrypto extension remains installed.",
       "origins": [
         {
           "source": "backend/migrations/000001_platform_baseline.up.sql",
@@ -160,8 +162,9 @@
     },
     {
       "target": "tests/infrastructure.sql",
-      "target_template_sha256": "c7d445af3c6404ea664018f41111c93abaef606f6925f2fbd0b0ee9d6bfacc61",
-      "transformation": "Eight-table presence, command replay unique/state constraints, outbox identity/schema immutability and operation-log append/finalization protection.",
+      "target_template_sha256": "342171c4af1ba35ab174439cb3673489b48f4e0073fa91d24939c9251e88f0a7",
+      "transformation": "source-adapted",
+      "details": "Template-owned verification asserts the exact eleven business-neutral infrastructure owner tables, five-field principal-scoped command replay uniqueness and required principal values, integration-event global identity and append-only storage, subscriber receipt isolation and terminal transitions, aggregate checkpoint source isolation and contiguous advancement, plus retained outbox and operation-log invariants.",
       "origins": []
     }
   ],

package/dist/resources/templates/go-backend/docs/source-provenance.json

@@ -430,9 +430,10 @@
     {
       "source": "backend/internal/core/commandreplay/model.go",
       "target": "internal/core/commandreplay/model.go",
-      "transformation": "module/import namespace only",
+      "transformation": "source-adapted",
+      "details": "Makes principal_type and principal_ref mandatory members of command replay identity. The database unique key is the five-field tuple (namespace, principal_type, principal_ref, command_scope, idempotency_key), isolating identical idempotency keys across trusted principals.",
       "source_sha256": "e610b620e96cabafad53ca1265455bd7fececcf6db73783beebe26bf6adf0c49",
-      "target_template_sha256": "91f3fdddc489ce7249cd997584d1f61f06cb29a584523fcf30ac68c4fd0035aa"
+      "target_template_sha256": "537673b5ada9d6f8e375d76e65e76764162622f2867485e25b858cf15c8da823"
     },
     {
       "source": "backend/internal/core/commandreplay/model_test.go",
@@ -451,16 +452,18 @@
     {
       "source": "backend/internal/core/commandreplay/persistence.go",
       "target": "internal/core/commandreplay/persistence.go",
-      "transformation": "module/import namespace only",
+      "transformation": "source-adapted",
+      "details": "Scopes repository lookup, conflict handling and the length-prefixed PostgreSQL advisory lock key by the five-field tuple (namespace, principal_type, principal_ref, command_scope, idempotency_key).",
       "source_sha256": "6b495eb7d886dea43f50fb5457c99450cf75ee3180ab138dc4b6f71d5e912308",
-      "target_template_sha256": "fd8e034952709522d842dce4079f86ec4a2f8d499ea54f7d60c00758fca07784"
+      "target_template_sha256": "e335b9085acec0a83789e4e115ab0a04e2a6db8bae97384ab81a9d78e39debac"
     },
     {
       "source": "backend/internal/core/commandreplay/persistence_test.go",
       "target": "internal/core/commandreplay/persistence_test.go",
-      "transformation": "module/import namespace only",
+      "transformation": "source-adapted",
+      "details": "Verifies database lookup, conflict targets and advisory locks use the complete five-field principal scope and do not collide across distinct principals.",
       "source_sha256": "58228cdb9f0fcf22da36e620d565d810fe3c618e061a68e61a140da44bacac3b",
-      "target_template_sha256": "1cff76682460690e89b5c80f58f0422c02cfb1319ed079447a2c9104e9104107"
+      "target_template_sha256": "0947eab5e124ebd4168a78cc3a2ed9957462a6fed1d3967c4672f590644db760"
     },
     {
       "source": "backend/internal/core/commandreplay/provider.go",
@@ -472,37 +475,42 @@
     {
       "source": "backend/internal/core/commandreplay/repository.go",
       "target": "internal/core/commandreplay/repository.go",
-      "transformation": "module/import namespace only",
+      "transformation": "source-adapted",
+      "details": "Extends replay lookup and scope-lock contracts with required principal type and principal reference so every repository operation addresses the same five-field identity.",
       "source_sha256": "90a0e737c8df5f65e6f1897c82b3087ef35a6cbf1e46bd4ca291ce18a686610f",
-      "target_template_sha256": "90a0e737c8df5f65e6f1897c82b3087ef35a6cbf1e46bd4ca291ce18a686610f"
+      "target_template_sha256": "4e52704849a4bbc1842e812d6a6244d0860f23a73a92ae7b27694cf1fa2bc617"
     },
     {
       "source": "backend/internal/core/commandreplay/service.go",
       "target": "internal/core/commandreplay/service.go",
-      "transformation": "module/import namespace only",
+      "transformation": "source-adapted",
+      "details": "Requires trusted principal type and reference at the service boundary and propagates the complete five-field scope through lock, lookup, create and duplicate-reload paths.",
       "source_sha256": "e6773b4fa604133333ca193d73c7ede037abf7d00df2293df4618e22cd2b616c",
-      "target_template_sha256": "6a80ef4df446a6bb10da4972890fdbd166d879bd4a01368f9605a28e781b197e"
+      "target_template_sha256": "266dd3787265091404af83be76c26d887b5115abddaf97f3ce3b76b3c456b093"
     },
     {
       "source": "backend/internal/core/commandreplay/service_persistence_test.go",
       "target": "internal/core/commandreplay/service_persistence_test.go",
-      "transformation": "module/import namespace only",
+      "transformation": "source-adapted",
+      "details": "Verifies persisted replay isolation for identical command and idempotency values owned by different trusted principals, including concurrent acquisition behavior.",
       "source_sha256": "1e5e2fd1b720f069f926c5cfc009e243606b0e87bccd6773a71ee53cc8b7e02b",
-      "target_template_sha256": "05b14b08732cae67d54093953936d1531b75bc2ee2b3aa86e48c2bbacacb9e0c"
+      "target_template_sha256": "47ecb12805fe8efa1d59cbcf22bc03ae971f8bb2725a418d2cfc416b27785a19"
     },
     {
       "source": "backend/internal/core/commandreplay/service_test.go",
       "target": "internal/core/commandreplay/service_test.go",
-      "transformation": "module/import namespace only",
+      "transformation": "source-adapted",
+      "details": "Verifies principal fields are mandatory and that replay, conflict and external-lease behavior consistently use the five-field principal scope.",
       "source_sha256": "f022ef1d41d9d296af275ef335ac87431c5f55307d19c7d9252a1b7e3f71116b",
-      "target_template_sha256": "2b6cdf86e4bf1020552a1009ee1500e68e1b1804f19ddd5f35caa53688cf9051"
+      "target_template_sha256": "24ff2e89c58fe24447051fac0b03000a6e608317366a5ccbe73761570cde47af"
     },
     {
       "source": "backend/internal/core/commandreplay/types.go",
       "target": "internal/core/commandreplay/types.go",
-      "transformation": "module/import namespace only",
+      "transformation": "source-adapted",
+      "details": "Makes principal type and principal reference required request and normalized values because both fields participate in command replay identity.",
       "source_sha256": "14c038c1f4cf4ff076e0b71727276604550dd62557e7e2c72b8e4d38aa179c04",
-      "target_template_sha256": "51b67144ae463a38ecf4b01729f91f130f4b0deccc60b601f51981779be84686"
+      "target_template_sha256": "53c7278ebea7ed97ef2817c30feb8a60846336b8d79886d08a046396d81b36fa"
     },
     {
       "source": "backend/internal/core/config/config.go",
@@ -2175,9 +2183,10 @@
     {
       "source": "backend/internal/common/enums/register_locale.go",
       "target": "internal/common/enums/register_locale.go",
-      "transformation": "module/import namespace only",
+      "transformation": "source-adapted",
+      "details": "Expands business-neutral locale presentation metadata to the exact 19 internal short codes exposed by the locale Resource Bundle; no alias codes are registered.",
       "source_sha256": "3334a68915c6a6c10b5ff1e36bc523e4111a962b451779165cfb70c0e6e4837d",
-      "target_template_sha256": "1210020d94c87af0a78146a6f782352a87d25a9581514d6f8c413f64e6c62f98"
+      "target_template_sha256": "62ab6b920cd7e394c99dd0855bc0479e70183bc0f631e0c2e5a83826791a694a"
     },
     {
       "source": "backend/internal/common/enums/register_mailbox.go",
@@ -2546,16 +2555,18 @@
     {
       "source": "backend/internal/common/locale/locale.go",
       "target": "internal/common/locale/locale.go",
-      "transformation": "module/import namespace only",
+      "transformation": "source-adapted",
+      "details": "Replaces permissive case-folded aliases and fallback normalization with one exact 19-entry Resource Bundle mapping between canonical external tags and internal short codes. It provides deterministic round trips and text direction, marks only Arabic as RTL, and rejects unknown, non-canonical or colliding locale keys.",
       "source_sha256": "17b5db8f7f0d0667cc88e37351435214e04ad98fe214b22c1c857e77ef7cb02d",
-      "target_template_sha256": "17b5db8f7f0d0667cc88e37351435214e04ad98fe214b22c1c857e77ef7cb02d"
+      "target_template_sha256": "bafde441fe8a3d7d0e6db8c413a9d562030cfb2145357fc2406b6d831b2f77a5"
     },
     {
       "source": "backend/internal/common/locale/locale_test.go",
       "target": "internal/common/locale/locale_test.go",
-      "transformation": "module/import namespace only",
+      "transformation": "source-adapted",
+      "details": "Verifies all 19 canonical external-tag and short-code round trips and directions, plus fail-closed rejection of aliases, case variants, whitespace, punctuation, unknown keys, blank text and duplicate canonical targets.",
       "source_sha256": "67c1b6b955603c3797d8231b916ce5ee3f55c7463a600f6bc931a9e2ad706cbc",
-      "target_template_sha256": "67c1b6b955603c3797d8231b916ce5ee3f55c7463a600f6bc931a9e2ad706cbc"
+      "target_template_sha256": "5f76e478cdaa12a2e6bcea3ddb8501e7473530efff0f628d4f77d82364809946"
     },
     {
       "source": "backend/internal/common/mediaref/mediaref.go",

package/dist/resources/templates/go-backend/internal/common/enums/register_locale.go

@@ -18,8 +18,15 @@ var localeEnumMetadataByCode = map[string]localeEnumMetadata{
 	"ja": {label: "日本語", color: "magenta"},
 	"ko": {label: "한국어", color: "green"},
 	"pt": {label: "Português", color: "orange"},
+	"ru": {label: "Русский", color: "purple"},
 	"hi": {label: "हिंदी", color: "lime"},
 	"ar": {label: "العربية", color: "volcano"},
+	"id": {label: "Bahasa Indonesia", color: "blue"},
+	"th": {label: "ไทย", color: "green"},
+	"vi": {label: "Tiếng Việt", color: "cyan"},
+	"tr": {label: "Türkçe", color: "red"},
+	"pl": {label: "Polski", color: "magenta"},
+	"nl": {label: "Nederlands", color: "geekblue"},
 }
 
 func commonLocaleEnumItems() []EnumItem {

package/dist/resources/templates/go-backend/internal/common/enums/register_locale_test.go

@@ -0,0 +1,30 @@
+package enums
+
+import (
+	"reflect"
+	"testing"
+
+	commonlocale "{{module}}/internal/common/locale"
+)
+
+func TestCommonLocaleEnumItemsCoverSupportedCodes(t *testing.T) {
+	items := commonLocaleEnumItems()
+	wantCodes := commonlocale.SupportedCodes()
+	if len(items) != len(wantCodes) {
+		t.Fatalf("commonLocaleEnumItems() count = %d, want %d", len(items), len(wantCodes))
+	}
+
+	gotCodes := make([]string, 0, len(items))
+	for _, item := range items {
+		gotCodes = append(gotCodes, item.Value)
+		if item.Label == "" {
+			t.Errorf("locale %q has empty label", item.Value)
+		}
+		if item.Color == "" {
+			t.Errorf("locale %q has empty color", item.Value)
+		}
+	}
+	if !reflect.DeepEqual(gotCodes, wantCodes) {
+		t.Fatalf("commonLocaleEnumItems() values = %#v, want %#v", gotCodes, wantCodes)
+	}
+}

package/dist/resources/templates/go-backend/internal/common/locale/locale.go

@@ -2,6 +2,7 @@ package locale
 
 import (
 	"encoding/json"
+	"fmt"
 	"strings"
 )
 
@@ -10,124 +11,143 @@ const (
 	AdminDefaultCode = "cn"
 )
 
-var supportedCodes = []string{
-	"en",
-	"cn",
-	"tw",
-	"de",
-	"es",
-	"fr",
-	"it",
-	"ja",
-	"ko",
-	"pt",
-	"hi",
-	"ar",
+// Direction 表示语言内容的排版方向。
+type Direction string
+
+const (
+	DirectionLTR Direction = "ltr"
+	DirectionRTL Direction = "rtl"
+)
+
+// Mapping 定义规范外部语言标签与内部短码之间的唯一映射。
+type Mapping struct {
+	ExternalTag string
+	ShortCode   string
+	Direction   Direction
 }
 
-var supportedCodeSet = buildSupportedCodeSet()
+var mappings = []Mapping{
+	{ExternalTag: "en", ShortCode: "en", Direction: DirectionLTR},
+	{ExternalTag: "zh-Hans", ShortCode: "cn", Direction: DirectionLTR},
+	{ExternalTag: "zh-Hant", ShortCode: "tw", Direction: DirectionLTR},
+	{ExternalTag: "ja", ShortCode: "ja", Direction: DirectionLTR},
+	{ExternalTag: "ko", ShortCode: "ko", Direction: DirectionLTR},
+	{ExternalTag: "es", ShortCode: "es", Direction: DirectionLTR},
+	{ExternalTag: "fr", ShortCode: "fr", Direction: DirectionLTR},
+	{ExternalTag: "de", ShortCode: "de", Direction: DirectionLTR},
+	{ExternalTag: "pt-BR", ShortCode: "pt", Direction: DirectionLTR},
+	{ExternalTag: "it", ShortCode: "it", Direction: DirectionLTR},
+	{ExternalTag: "ru", ShortCode: "ru", Direction: DirectionLTR},
+	{ExternalTag: "ar", ShortCode: "ar", Direction: DirectionRTL},
+	{ExternalTag: "hi", ShortCode: "hi", Direction: DirectionLTR},
+	{ExternalTag: "id", ShortCode: "id", Direction: DirectionLTR},
+	{ExternalTag: "th", ShortCode: "th", Direction: DirectionLTR},
+	{ExternalTag: "vi", ShortCode: "vi", Direction: DirectionLTR},
+	{ExternalTag: "tr", ShortCode: "tr", Direction: DirectionLTR},
+	{ExternalTag: "pl", ShortCode: "pl", Direction: DirectionLTR},
+	{ExternalTag: "nl", ShortCode: "nl", Direction: DirectionLTR},
+}
+
+var externalTagIndex, shortCodeIndex = buildIndexes()
 
-func buildSupportedCodeSet() map[string]struct{} {
-	result := make(map[string]struct{}, len(supportedCodes))
-	for _, code := range supportedCodes {
-		result[code] = struct{}{}
+func buildIndexes() (map[string]Mapping, map[string]Mapping) {
+	byExternalTag := make(map[string]Mapping, len(mappings))
+	byShortCode := make(map[string]Mapping, len(mappings))
+	for _, mapping := range mappings {
+		byExternalTag[mapping.ExternalTag] = mapping
+		byShortCode[mapping.ShortCode] = mapping
 	}
+	return byExternalTag, byShortCode
+}
+
+// Mappings 返回按稳定顺序排列的全部语言映射。
+func Mappings() []Mapping {
+	result := make([]Mapping, len(mappings))
+	copy(result, mappings)
 	return result
 }
 
+// SupportedCodes 返回按稳定顺序排列的全部内部短码。
 func SupportedCodes() []string {
-	result := make([]string, len(supportedCodes))
-	copy(result, supportedCodes)
+	result := make([]string, 0, len(mappings))
+	for _, mapping := range mappings {
+		result = append(result, mapping.ShortCode)
+	}
 	return result
 }
 
-func NormalizeCode(value string) string {
-	code := strings.ToLower(strings.TrimSpace(strings.ReplaceAll(value, "_", "-")))
-	switch code {
-	case "en", "en-us", "en-gb":
-		return "en"
-	case "cn", "zh", "zh-cn", "zh-hans", "zh-hans-cn":
-		return "cn"
-	case "tw", "hk", "zh-tw", "zh-hk", "zh-hant", "zh-hant-tw", "zh-hant-hk":
-		return "tw"
-	case "ja", "jp", "ja-jp":
-		return "ja"
-	case "ko", "ko-kr":
-		return "ko"
-	case "de", "de-de":
-		return "de"
-	case "es", "es-es":
-		return "es"
-	case "fr", "fr-fr":
-		return "fr"
-	case "it", "it-it":
-		return "it"
-	case "pt", "pt-br", "pt-pt":
-		return "pt"
-	case "hi", "in", "hi-in":
-		return "hi"
-	case "ar", "ar-sa":
-		return "ar"
-	}
-	return ""
+// ShortCodeForExternalTag 将规范外部语言标签精确映射为内部短码。
+func ShortCodeForExternalTag(externalTag string) (string, bool) {
+	mapping, ok := externalTagIndex[externalTag]
+	return mapping.ShortCode, ok
 }
 
-func NormalizeCodeOrDefault(value string, fallback string) string {
-	if code := NormalizeCode(value); code != "" {
-		return code
+// ExternalTagForShortCode 将内部短码精确映射为规范外部语言标签。
+func ExternalTagForShortCode(shortCode string) (string, bool) {
+	mapping, ok := shortCodeIndex[shortCode]
+	return mapping.ExternalTag, ok
+}
+
+// DirectionForShortCode 返回内部短码对应的排版方向。
+func DirectionForShortCode(shortCode string) (Direction, bool) {
+	mapping, ok := shortCodeIndex[shortCode]
+	return mapping.Direction, ok
+}
+
+// NormalizeCode 将规范外部语言标签或内部短码精确转换为内部短码。
+func NormalizeCode(value string) string {
+	if mapping, ok := externalTagIndex[value]; ok {
+		return mapping.ShortCode
 	}
-	if code := NormalizeCode(fallback); code != "" {
-		return code
+	if mapping, ok := shortCodeIndex[value]; ok {
+		return mapping.ShortCode
 	}
-	return DefaultCode
+	return ""
 }
 
+// IsShortCode 判断值是否为受支持的精确内部短码。
 func IsShortCode(value string) bool {
-	code := strings.TrimSpace(value)
-	if code == "" || code != strings.ToLower(code) {
-		return false
-	}
-	_, ok := supportedCodeSet[code]
+	_, ok := shortCodeIndex[value]
 	return ok
 }
 
-func NormalizeTextMap(input map[string]string) map[string]string {
-	if len(input) == 0 {
-		return map[string]string{}
-	}
+// NormalizeTextMap 将语言键精确转换为内部短码并拒绝无效或冲突输入。
+func NormalizeTextMap(input map[string]string) (map[string]string, error) {
 	result := make(map[string]string, len(input))
 	for key, value := range input {
 		code := NormalizeCode(key)
+		if code == "" {
+			return nil, fmt.Errorf("unsupported locale key %q", key)
+		}
 		text := strings.TrimSpace(value)
-		if code == "" || text == "" {
-			continue
+		if text == "" {
+			return nil, fmt.Errorf("locale %q has empty text", key)
 		}
 		if _, exists := result[code]; exists {
-			continue
+			return nil, fmt.Errorf("duplicate locale mapping for short code %q", code)
 		}
 		result[code] = text
 	}
-	return result
+	return result, nil
 }
 
-func NormalizeLocaleRootedMap[T any](input map[string]T) map[string]T {
-	if len(input) == 0 {
-		return map[string]T{}
-	}
+// NormalizeLocaleRootedMap 将语言根键精确转换为内部短码并拒绝无效或冲突输入。
+func NormalizeLocaleRootedMap[T any](input map[string]T) (map[string]T, error) {
 	result := make(map[string]T, len(input))
 	for key, value := range input {
 		code := NormalizeCode(key)
 		if code == "" {
-			continue
+			return nil, fmt.Errorf("unsupported locale key %q", key)
 		}
 		if _, exists := result[code]; exists {
-			continue
+			return nil, fmt.Errorf("duplicate locale mapping for short code %q", code)
 		}
 		result[code] = value
 	}
-	return result
+	return result, nil
 }
 
+// NormalizeRawTextMap 将 JSON 文本映射规范化为内部短码键。
 func NormalizeRawTextMap(raw json.RawMessage) (json.RawMessage, error) {
 	if len(raw) == 0 {
 		return json.RawMessage(`{}`), nil
@@ -136,7 +156,13 @@ func NormalizeRawTextMap(raw json.RawMessage) (json.RawMessage, error) {
 	if err := json.Unmarshal(raw, &input); err != nil {
 		return nil, err
 	}
-	normalized := NormalizeTextMap(input)
+	if input == nil {
+		return nil, fmt.Errorf("locale text map must be a JSON object")
+	}
+	normalized, err := NormalizeTextMap(input)
+	if err != nil {
+		return nil, err
+	}
 	payload, err := json.Marshal(normalized)
 	if err != nil {
 		return nil, err