@h-ai/core 0.1.0-alpha.66 → 0.1.0-alpha.68

package/README.en.md

@@ -4,9 +4,11 @@
 
 [Framework home](../../README.en.md)
 
-> The core of hai Agent Framework: shared utilities, types, configuration management, and logging.
+## Introduction
 
-## Capabilities
+The core of hai Agent Framework: shared utilities, types, configuration management, and logging.
+
+## Core features
 
 - **HaiResult types**: functional error handling (`ok` / `err`) with a shared result format across modules.
 - **Unified logging**: pino on Node.js and loglevel in browsers, with the same API.
@@ -18,9 +20,11 @@
 - **Module utilities**: NotInitializedKit proxies and shared lifecycle infrastructure.
 - **Utility library**: type checks and object / string / array / async / time operations.
 
-## Quick start
+## Getting started
+
+### Quick start
 
-### Node.js environment
+#### Node.js environment
 
 ```typescript
 import { core } from '@h-ai/core'
@@ -72,7 +76,7 @@ core.time.formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss')
 core.typeUtils.isDefined(value)
 ```
 
-### Browser environment
+#### Browser environment
 
 ```typescript
 import { core } from '@h-ai/core'
@@ -95,13 +99,13 @@ The browser retains the `core.config` API shape for type compatibility, but does
 - `watch()` immediately calls its callback with the same error and returns a safe no-op unsubscribe function.
 - Read configuration on the server and deliver it through an API, or use `core.init({ logging })` only to configure browser logging.
 
-## Detailed API
+### Detailed API
 
-### Logging (Logger)
+#### Logging (Logger)
 
 `core.logger` is both the default Logger instance and the shared entry point for logger management.
 
-#### Write logs
+##### Write logs
 
 Six levels: `trace` / `debug` / `info` / `warn` / `error` / `fatal`.
 
@@ -111,7 +115,7 @@ core.logger.error('Failed to connect', { error })
 core.logger.debug('Processing item', { id, step: 'validation' })
 ```
 
-#### Create a module logger
+##### Create a module logger
 
 ```typescript
 // 独立名称空间，适合模块内全局使用
@@ -119,7 +123,7 @@ const logger = core.logger.create({ name: 'payment' })
 logger.info('Payment processed')
 ```
 
-#### Child loggers
+##### Child loggers
 
 ```typescript
 // 携带固定上下文，每条日志自动附带这些字段
@@ -135,7 +139,7 @@ opLogger.error('Login failed', { reason: 'invalid_password' })
 
 > **Typical usage**: create `reqLogger` at the request entry, pass it to the service layer, and add operation context with `child`. Logs then include the complete request context.
 
-#### Logger management
+##### Logger management
 
 ```typescript
 // 配置输出格式和级别（Node.js / Browser）
@@ -154,9 +158,11 @@ After `core.init()` loads `_core.yml.logging`, or after `configure` / `setLevel`
 
 Browser logs still use the DevTools console: `pretty` prints readable messages with context, while `json` prints a JSON string containing `level` / `msg`. Default credential masking and configured path redaction both apply, including nested dot/bracket paths and `*`. Callers remain responsible for redacting message text.
 
-`core.logger` redacts log context by default: credentials such as `password`, `token`, `secret`, `privateKey`, and `apiV3Key` become `[REDACTED]`. Fields such as `url` / `baseUrl` / `endpoint` mask only embedded usernames/passwords. Email addresses and phone numbers are not masked by default.
+Native `Error` values in log context are copied into diagnostics containing `name`, `message`, `stack`, `cause`, `AggregateError.errors`, and enumerable own context before default field/URL masking and configured `redact` paths run. Both backends use the same rules and leave the original error unchanged. Error-subgraph cycles become `[Circular]` and the 32-level limit becomes `[MaxDepth]`; custom replacements in these subgraphs follow the same normalization, while ordinary-object replacement behavior is unchanged. Ordinary-object cycles without an Error retain their original structure and are not guaranteed to be directly JSON-serializable. `name/message/stack` are free text: secrets embedded in them are not automatically parsed. Clean them before logging or mask whole paths such as `error.message` / `error.stack`.
 
-#### Log level conventions
+`core.logger` redacts log context by default: credentials such as `password`, `token`, `secret`, `privateKey`, and `apiV3Key` become `[REDACTED]`. Fields such as `url` / `baseUrl` / `endpoint` mask embedded usernames/passwords, sensitive query parameters, and OAuth key/value fragments; malformed URLs return a fixed placeholder. Email addresses and phone numbers are not masked by default.
+
+##### Log level conventions
 
 | Level   | Use case                                            |
 | ------- | --------------------------------------------------- |
@@ -167,7 +173,9 @@ Browser logs still use the DevTools console: `pretty` prints readable messages w
 | `error` | Operation failures requiring investigation          |
 | `fatal` | Fatal errors preventing continued service           |
 
-### Internationalization (i18n)
+#### Internationalization (i18n)
+
+Built-in locales are `zh-CN`, `en-US` and `ja-JP`. The `ja` alias normalizes to `ja-JP`; all modules share this setting.
 
 ```typescript
 // 设置全局语言（所有 getMessage 函数自动响应）
@@ -187,13 +195,13 @@ getMessage('welcome', { params: { name: 'Alice' } }) // 'Welcome Alice'
 getMessage('welcome', { locale: 'zh-CN', params: { name: 'Alice' } }) // '欢迎 Alice'
 
 // 常量
-core.i18n.DEFAULT_LOCALES // [{ code: 'zh-CN', label: '简体中文' }, { code: 'en-US', label: 'English' }]
+core.i18n.DEFAULT_LOCALES // [{ code: 'zh-CN', label: '简体中文' }, { code: 'en-US', label: 'English' }, { code: 'ja-JP', label: '日本語' }]
 core.i18n.DEFAULT_LOCALE // 'zh-CN'
 ```
 
-### Redaction utilities
+#### Redaction utilities
 
-`core.sanitize.sanitizeSensitiveFields()` recursively redacts objects and arrays. By default it handles password, token, secret, privateKey, apiV3Key, and similar credentials, and masks embedded credentials in `url` / `baseUrl` / `endpoint`. Modules can supply custom matchers.
+`core.sanitize.sanitizeSensitiveFields()` recursively redacts objects and arrays. By default it handles password, token, secret, privateKey, apiV3Key, and similar credentials, and masks embedded credentials in `url` / `baseUrl` / `endpoint`. `core.sanitize.sanitizeUrl(url, options)` also handles individual URLs and returns `(invalid url)` for malformed input. Custom matchers apply to parameter names as well.
 
 ```typescript
 core.sanitize.sanitizeSensitiveFields({
@@ -211,7 +219,7 @@ core.sanitize.sanitizeSensitiveFields({ email: 'user@example.com' }, {
 // => { email: '***' }
 ```
 
-### Zod validation error localization
+#### Zod validation error localization
 
 `core.zodValidation` converts Zod `SafeParseError` / `ZodError` into flat form errors and maps Zod's
 default English messages to the caller's own localized messages.
@@ -272,17 +280,19 @@ if (!result.success) {
 }
 ```
 
-### Configuration management (Node.js only)
+#### Configuration management (Node.js only)
 
 > Browsers have no filesystem access. `core.config` offers placeholder APIs only: file-related methods return `SERVICE_UNAVAILABLE` and do not load YAML.
 
+Node automatically loads and watches runtime `.yml` / `.yaml` files, excluding exactly `_deploy.yml` and `_deploy.yaml`. The deployment CLI parses those reserved files after loading its target environment and credentials. Business `deploy.yml` and explicit `core.config.load` remain supported. A failed per-file load result is logged and loading continues; applications must validate required configuration and check `success`. Directory scanning, logger setup and other exceptions may still propagate.
+
 ```typescript
 import { core, HaiConfigError } from '@h-ai/core'
 import { z } from 'zod'
 
-// 方式 1：init 时自动加载整个配置目录
+// 方式 1：init 时自动加载运行时配置
 core.init({
-  configDir: './config', // 扫描该目录所有 .yml 文件
+  configDir: './config', // 扫描 .yml / .yaml，排除 _deploy.yml / _deploy.yaml
   watchConfig: true, // 监听变更并自动重载
 })
 
@@ -304,8 +314,8 @@ const validResult = core.config.validate('app', AppSchema)
 
 // 查询和获取
 if (core.config.has('app')) {
-  const cfg = core.config.get<typeof AppSchema>('app') // undefined 或配置
-  const cfg2 = core.config.getOrThrow<typeof AppSchema>('app') // 未加载时抛异常
+  const cfg = core.config.get<z.infer<typeof AppSchema>>('app') // undefined 或配置
+  const cfg2 = core.config.getOrThrow<z.infer<typeof AppSchema>>('app') // 未加载时抛异常
 }
 core.config.keys() // ['core', 'app', 'db', ...]
 
@@ -327,7 +337,7 @@ core.config.clear('app') // 清除单个
 core.config.clear() // 清除全部
 ```
 
-#### Dotenv files and environment modes
+##### Dotenv files and environment modes
 
 Node-only `core.config.loadEnvFiles({ mode, envDir })` returns HaiResult and merges `.env` → `.env.<mode>` → `.env.local`, with existing process variables taking priority. development/production map to dev/prod; missing files are skipped. It does not mutate the process: check success before assigning. Track public environment files and `.env.example`; ignore private `.env.local`. core.init does not load dotenv. Browser calls return SERVICE_UNAVAILABLE.
 
@@ -339,7 +349,7 @@ Object.assign(process.env, env.data)
 core.init({ configDir: './config' })
 ```
 
-#### Environment variable mapping and interpolation
+##### Environment variable mapping and interpolation
 
 `core.config.load(name, ...)` automatically maps each YAML leaf to an
 environment variable named `HAI_<CONFIG_NAME>_<YAML_PATH>`. Configuration names and keys are uppercased, levels are separated by `_`,
@@ -382,7 +392,7 @@ database: ${DB_CONNECTION} # → 环境变量缺失时报错
 url: http://${HOST}:${PORT} # → string（混合文本）
 ```
 
-### ID generation
+#### ID generation
 
 ```typescript
 const id = core.id.generate() // nanoid 21 字符
@@ -398,7 +408,9 @@ core.id.isValidUUID('f47ac10b-...') // true/false
 core.id.isValidNanoId('abc123', 6) // true/false
 ```
 
-### Utilities
+UUID generation requires cryptographic randomUUID/getRandomValues and throws if neither is available; it never falls back to Math.random.
+
+#### Utilities
 
 ```typescript
 // 类型检查
@@ -434,7 +446,7 @@ core.string.isBlank('') // true
 core.string.isNotBlank('x') // true
 core.string.padStart('5', 3, '0') // '005'
 core.string.padEnd('5', 3, '0') // '500'
-core.string.constantTimeEqual(a, b) // 防时序攻击比较
+core.string.constantTimeEqual(a, b) // Node 使用原生等长比较；浏览器不保证恒时
 
 // 数组操作
 core.array.unique([1, 1, 2]) // [1, 2]
@@ -470,7 +482,9 @@ core.time.startOfDay(date)
 core.time.endOfDay(date)
 ```
 
-### Module utilities (module)
+The Node entry uses node:crypto.timingSafeEqual over equal-length UTF-16LE code units. Different lengths return false; length is not hidden. The browser implementation avoids content-based early returns but has no JavaScript-engine timing guarantee and is not a server credential boundary. Surrounding branches, encoding and request handling are not made timing-safe by this helper.
+
+#### Module utilities (module)
 
 Shared initialization error handling for modules:
 
@@ -488,9 +502,9 @@ const currentDdl: DdlOperations = notInitialized.proxy<DdlOperations>()
 const currentHash: HashOperations = notInitialized.proxy<HashOperations>('sync')
 ```
 
-## Error handling
+### Error handling
 
-### HaiResult types
+#### HaiResult types
 
 All operations that may fail return `HaiResult<T>`:
 
@@ -513,7 +527,7 @@ else {
 }
 ```
 
-### Custom error codes (per module)
+#### Custom error codes (per module)
 
 ```typescript
 import type { ErrorInfo } from '@h-ai/core'
@@ -539,7 +553,7 @@ const errorInst = core.error.buildHaiErrorInst(
 )
 ```
 
-### Configuration error codes
+#### Configuration error codes
 
 ```typescript
 import { HaiConfigError } from '@h-ai/core'
@@ -551,12 +565,24 @@ HaiConfigError.CONFIG_ENV_VAR_MISSING // hai:core:013 - 环境变量缺失
 HaiConfigError.CONFIG_NOT_LOADED // hai:core:014 - 配置未加载
 ```
 
-## Tests
+### Request locale isolation
+
+Wrap Node requests and SSR in `core.i18n.runWithLocale(locale, () => handleRequest())`. SvelteKit can use `kit.i18n.runWithLocale(locale, () => resolve(event))`; serv creates the scope automatically from request headers. Async descendants inherit it. Explicit `MessageOptions.locale` takes precedence over the request locale and the startup default. Within a scope, `setGlobalLocale` only changes that request; outside a scope it configures the startup default and must not be called by request hooks.
+
+Browsers keep application-level `setGlobalLocale` / `createLocaleStore`. During SSR, UI store initialization and setters only update the store; messages read the request scope. `runWithLocale` requires the Node entry; browser translations use explicit locale options or application state.
+
+## Configuration consumption
+
+`_core.yml` accepts only name/version/env/defaultLocale metadata and logging; unknown fields fail loading. Core has no global debug, ID length/prefix, business features or locale registration list. Use logging.level, per-call core.id arguments, and application-owned app.yml with its own schema. defaultLocale is metadata, not automatic translation registration or a Paraglide switch. Importing Logger preserves LANG, LC_ALL and PYTHONIOENCODING, including Windows TTY. See the [configuration-to-consumer map (Chinese)](../../.agents/skills/hai-module-create/configuration.md).
+
+## Development and testing
 
 ```bash
 pnpm --filter @h-ai/core test
 ```
 
+See the [module JSDoc conventions (Chinese)](../../.agents/instructions/module-conventions.md#jsdoc-与示例验证) for declaration comments and compilable examples. Node core.init is synchronous and returns void. A failed per-file config.load result is logged and loading continues; validate required configuration and check success. Directory scanning and other exceptions may still throw. Business HaiResult APIs require a success check.
+
 ## License
 
 Apache-2.0

package/README.ja.md

@@ -4,7 +4,9 @@
 
 [フレームワークのホーム](../../README.ja.md)
 
-> hai Agent Framework の中核モジュール。共通ツール、型定義、設定管理、ログ機能を提供します。
+## 概要
+
+hai Agent Framework の中核モジュール。共通ツール、型定義、設定管理、ログ機能を提供します。
 
 ## 主な機能
 
@@ -18,9 +20,11 @@
 - **モジュールツール**：NotInitializedKit のプロキシと共通のライフサイクル基盤。
 - **ツール関数**：型確認、オブジェクト・文字列・配列・非同期・時刻の操作。
 
-## クイックスタート
+## 使い始める
+
+### クイックスタート
 
-### Node.js 環境
+#### Node.js 環境
 
 ```typescript
 import { core } from '@h-ai/core'
@@ -72,7 +76,7 @@ core.time.formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss')
 core.typeUtils.isDefined(value)
 ```
 
-### ブラウザー環境
+#### ブラウザー環境
 
 ```typescript
 import { core } from '@h-ai/core'
@@ -95,13 +99,13 @@ core.array.unique([1, 1, 2])
 - `watch()` は同じエラーで直ちにコールバックを呼び、安全な no-op の監視解除関数を返します。
 - 設定が必要な場合はサーバーで読み込み API で渡すか、ブラウザーでは `core.init({ logging })` でログのみ設定してください。
 
-## API の詳細
+### API の詳細
 
-### ログ（Logger）
+#### ログ（Logger）
 
 `core.logger` は既定の Logger インスタンスであり、ログ管理の共通入口でもあります。
 
-#### ログの記録
+##### ログの記録
 
 6 つのレベル：`trace` / `debug` / `info` / `warn` / `error` / `fatal`。
 
@@ -111,7 +115,7 @@ core.logger.error('Failed to connect', { error })
 core.logger.debug('Processing item', { id, step: 'validation' })
 ```
 
-#### モジュール用 logger の作成
+##### モジュール用 logger の作成
 
 ```typescript
 // 独立名称空间，适合模块内全局使用
@@ -119,7 +123,7 @@ const logger = core.logger.create({ name: 'payment' })
 logger.info('Payment processed')
 ```
 
-#### 子 logger（child）
+##### 子 logger（child）
 
 ```typescript
 // 携带固定上下文，每条日志自动附带这些字段
@@ -135,7 +139,7 @@ opLogger.error('Login failed', { reason: 'invalid_password' })
 
 > **典型的な使い方**：リクエスト入口で `reqLogger` を作成してサービス層に渡し、サービス層で `child` に操作コンテキストを追加します。ログに処理全体のコンテキストが自動的に含まれます。
 
-#### ログの管理
+##### ログの管理
 
 ```typescript
 // 配置输出格式和级别（Node.js / Browser）
@@ -154,9 +158,11 @@ const level = core.logger.getLevel() // 'debug'
 
 ブラウザーでは引き続き DevTools console に出力します。`pretty` は読みやすいメッセージと context、`json` は `level` / `msg` を含む JSON 文字列です。既定の認証情報マスキングと設定したパスのマスキングを併用し、ネストしたドット・括弧パスと `*` に対応します。メッセージ本文の機密情報は呼び出し側で除去してください。
 
-`core.logger` は既定でログの機密情報をマスクします。`password`、`token`、`secret`、`privateKey`、`apiV3Key` などは `[REDACTED]` に置換されます。`url` / `baseUrl` / `endpoint` は URL 内のユーザー名・パスワードのみをマスクします。メールアドレス・電話番号は既定では隠しません。
+ログ文脈のネイティブ `Error` は、`name`、`message`、`stack`、`cause`、`AggregateError.errors` と列挙可能な自身の文脈を持つコピーに変換してから、既定のフィールド/URL マスクと設定済み `redact` を適用します。両環境で同じ規則を使い、元の例外は変更しません。例外サブグラフの循環は `[Circular]`、32 階層の上限は `[MaxDepth]` になり、この範囲の独自置換値にも同じ正規化を適用します。通常オブジェクトの置換動作は変えません。Error を含まない通常オブジェクトの循環は元の構造を保持し、直接 JSON 化できる保証はありません。`name/message/stack` は自由文で、含まれる秘密を自動解析しません。記録前に除去するか、`error.message` / `error.stack` などのパス全体を隠してください。
 
-#### ログレベルの規約
+`core.logger` は既定でログの機密情報をマスクします。`password`、`token`、`secret`、`privateKey`、`apiV3Key` などは `[REDACTED]` に置換されます。`url` / `baseUrl` / `endpoint` は URL 内のユーザー名・パスワード、機密クエリ値、OAuth 形式の fragment をマスクします。不正な URL は固定値を返します。メールアドレス・電話番号は既定では隠しません。
+
+##### ログレベルの規約
 
 | レベル  | 用途                                     |
 | ------- | ---------------------------------------- |
@@ -167,7 +173,9 @@ const level = core.logger.getLevel() // 'debug'
 | `error` | 調査が必要な操作の失敗                   |
 | `fatal` | サービス継続不能の致命的エラー           |
 
-### 国際化（i18n）
+#### 国際化（i18n）
+
+組み込みの言語は `zh-CN`、`en-US`、`ja-JP` です。略記 `ja` は `ja-JP` に正規化され、すべてのモジュールで設定を共有します。
 
 ```typescript
 // 设置全局语言（所有 getMessage 函数自动响应）
@@ -187,13 +195,13 @@ getMessage('welcome', { params: { name: 'Alice' } }) // 'Welcome Alice'
 getMessage('welcome', { locale: 'zh-CN', params: { name: 'Alice' } }) // '欢迎 Alice'
 
 // 常量
-core.i18n.DEFAULT_LOCALES // [{ code: 'zh-CN', label: '简体中文' }, { code: 'en-US', label: 'English' }]
+core.i18n.DEFAULT_LOCALES // [{ code: 'zh-CN', label: '简体中文' }, { code: 'en-US', label: 'English' }, { code: 'ja-JP', label: '日本語' }]
 core.i18n.DEFAULT_LOCALE // 'zh-CN'
 ```
 
-### 機密情報のマスク
+#### 機密情報のマスク
 
-`core.sanitize.sanitizeSensitiveFields()` はオブジェクト・配列内の機密情報を再帰的にマスクします。既定では password、token、secret、privateKey、apiV3Key などを処理し、`url` / `baseUrl` / `endpoint` の認証情報もマスクします。独自の matcher も指定できます。
+`core.sanitize.sanitizeSensitiveFields()` はオブジェクト・配列内の機密情報を再帰的にマスクします。既定では password、token、secret、privateKey、apiV3Key などを処理し、`url` / `baseUrl` / `endpoint` の認証情報もマスクします。`core.sanitize.sanitizeUrl(url, options)` は単独の URL にも使用でき、不正な URL は `(invalid url)` を返します。独自の matcher はクエリ名にも適用されます。
 
 ```typescript
 core.sanitize.sanitizeSensitiveFields({
@@ -211,7 +219,7 @@ core.sanitize.sanitizeSensitiveFields({ email: 'user@example.com' }, {
 // => { email: '***' }
 ```
 
-### Zod 検証エラーの i18n 変換
+#### Zod 検証エラーの i18n 変換
 
 `core.zodValidation` は Zod の `SafeParseError` / `ZodError` をフラットなフォームエラーに変換し、
 Zod の既定の英語メッセージを呼び出し元の i18n 文言に変換します。
@@ -272,17 +280,19 @@ if (!result.success) {
 }
 ```
 
-### 設定管理（Node.js 専用）
+#### 設定管理（Node.js 専用）
 
 > ブラウザーにはファイルシステムがないため、`core.config` は代替 API の形状のみを提供します。ファイル関連メソッドは `SERVICE_UNAVAILABLE` を返し、YAML を読み込みません。
 
+Node は実行時の `.yml` / `.yaml` を自動読み込み・監視しますが、予約名 `_deploy.yml` と `_deploy.yaml` は除外します。これらはデプロイ CLI が対象環境と認証情報の読み込み後に個別解析します。業務用 `deploy.yml` と明示的な `core.config.load` は引き続き利用できます。単一ファイルの失敗結果はログに記録して続行するため、アプリは必須設定を validate して `success` を確認してください。ディレクトリー走査や Logger 設定などの例外は伝播する場合があります。
+
 ```typescript
 import { core, HaiConfigError } from '@h-ai/core'
 import { z } from 'zod'
 
-// 方式 1：init 时自动加载整个配置目录
+// 方式 1：init 时自动加载运行时配置
 core.init({
-  configDir: './config', // 扫描该目录所有 .yml 文件
+  configDir: './config', // 扫描 .yml / .yaml，排除 _deploy.yml / _deploy.yaml
   watchConfig: true, // 监听变更并自动重载
 })
 
@@ -304,8 +314,8 @@ const validResult = core.config.validate('app', AppSchema)
 
 // 查询和获取
 if (core.config.has('app')) {
-  const cfg = core.config.get<typeof AppSchema>('app') // undefined 或配置
-  const cfg2 = core.config.getOrThrow<typeof AppSchema>('app') // 未加载时抛异常
+  const cfg = core.config.get<z.infer<typeof AppSchema>>('app') // undefined 或配置
+  const cfg2 = core.config.getOrThrow<z.infer<typeof AppSchema>>('app') // 未加载时抛异常
 }
 core.config.keys() // ['core', 'app', 'db', ...]
 
@@ -327,7 +337,7 @@ core.config.clear('app') // 清除单个
 core.config.clear() // 清除全部
 ```
 
-#### dotenv ファイルと環境切り替え
+##### dotenv ファイルと環境切り替え
 
 Node 専用の `core.config.loadEnvFiles({ mode, envDir })` は HaiResult を返し、`.env` → `.env.<mode>` → `.env.local` の順で読み込みます。既存のプロセス変数が最優先です。development/production は dev/prod に対応し、存在しないファイルは省略します。プロセスは変更しないため、success を確認してから代入します。公開設定と `.env.example` は Git 登録し、私有の `.env.local` は除外します。core.init は dotenv を読み込まず、ブラウザーでは SERVICE_UNAVAILABLE を返します。
 
@@ -339,7 +349,7 @@ Object.assign(process.env, env.data)
 core.init({ configDir: './config' })
 ```
 
-#### 環境変数のマッピングと展開
+##### 環境変数のマッピングと展開
 
 `core.config.load(name, ...)` は YAML の各末端設定を
 `HAI_<CONFIG_NAME>_<YAML_PATH>` の環境変数に自動対応付けします。設定名・各 key は大文字化し、階層は `_` で区切り、
@@ -382,7 +392,7 @@ database: ${DB_CONNECTION} # → 环境变量缺失时报错
 url: http://${HOST}:${PORT} # → string（混合文本）
 ```
 
-### ID 生成
+#### ID 生成
 
 ```typescript
 const id = core.id.generate() // nanoid 21 字符
@@ -398,7 +408,9 @@ core.id.isValidUUID('f47ac10b-...') // true/false
 core.id.isValidNanoId('abc123', 6) // true/false
 ```
 
-### ツール関数
+UUID は暗号学的乱数の randomUUID/getRandomValues のみを使用し、どちらも利用できない場合は例外を送出します。Math.random にはフォールバックしません。
+
+#### ツール関数
 
 ```typescript
 // 类型检查
@@ -434,7 +446,7 @@ core.string.isBlank('') // true
 core.string.isNotBlank('x') // true
 core.string.padStart('5', 3, '0') // '005'
 core.string.padEnd('5', 3, '0') // '500'
-core.string.constantTimeEqual(a, b) // 防时序攻击比较
+core.string.constantTimeEqual(a, b) // Node 使用原生等长比较；浏览器不保证恒时
 
 // 数组操作
 core.array.unique([1, 1, 2]) // [1, 2]
@@ -470,7 +482,9 @@ core.time.startOfDay(date)
 core.time.endOfDay(date)
 ```
 
-### モジュール共通ツール（module）
+Node 入口は元の UTF-16 コード単位を UTF-16LE に変換し、同じバイト長を node:crypto.timingSafeEqual で比較します。長さが違えば false となり、長さ自体は隠しません。ブラウザー実装には JavaScript エンジンの定時間保証がなく、サーバーの認証境界には使用しません。周辺の分岐・変換・リクエスト処理まで定時間になるわけではありません。
+
+#### モジュール共通ツール（module）
 
 モジュール共通の初期化エラー処理：
 
@@ -488,9 +502,9 @@ const currentDdl: DdlOperations = notInitialized.proxy<DdlOperations>()
 const currentHash: HashOperations = notInitialized.proxy<HashOperations>('sync')
 ```
 
-## エラー処理
+### エラー処理
 
-### HaiResult 型
+#### HaiResult 型
 
 失敗する可能性がある操作は `HaiResult<T>` を返します：
 
@@ -513,7 +527,7 @@ else {
 }
 ```
 
-### 独自のエラーコード（モジュール単位）
+#### 独自のエラーコード（モジュール単位）
 
 ```typescript
 import type { ErrorInfo } from '@h-ai/core'
@@ -539,7 +553,7 @@ const errorInst = core.error.buildHaiErrorInst(
 )
 ```
 
-### 設定エラーコード
+#### 設定エラーコード
 
 ```typescript
 import { HaiConfigError } from '@h-ai/core'
@@ -551,12 +565,24 @@ HaiConfigError.CONFIG_ENV_VAR_MISSING // hai:core:013 - 环境变量缺失
 HaiConfigError.CONFIG_NOT_LOADED // hai:core:014 - 配置未加载
 ```
 
-## テスト
+### リクエスト言語の分離
+
+Node リクエストと SSR は `core.i18n.runWithLocale(locale, () => handleRequest())` で囲みます。SvelteKit は `kit.i18n.runWithLocale(locale, () => resolve(event))` を使えます。serv はリクエストヘッダーから自動設定します。非同期の子処理も言語を継承し、明示的な `MessageOptions.locale`、リクエスト言語、起動時の既定値の順で優先します。コンテキスト内の `setGlobalLocale` はそのリクエストだけを変更します。コンテキスト外の設定は起動時に限定し、リクエスト hook から呼びません。
+
+ブラウザーはアプリ全体の `setGlobalLocale` / `createLocaleStore` を使います。SSR の UI store 初期化と setter は自身の状態のみ変更し、メッセージはリクエストコンテキストを参照します。`runWithLocale` は Node 入口専用です。
+
+## 設定の消費範囲
+
+`_core.yml` は name/version/env/defaultLocale のメタデータと logging のみを受け付け、不明なフィールドでは読み込みに失敗します。グローバルな debug、ID 長/接頭辞、業務 features、言語登録リストは提供しません。logging.level、core.id の呼び出し引数、独自 Schema で検証する app.yml を使用してください。defaultLocale はメタデータであり、翻訳登録や Paraglide の切り替えを自動実行しません。Logger の import は Windows TTY でも LANG、LC_ALL、PYTHONIOENCODING を変更しません。[設定と消費点の対応表（中国語）](../../.agents/skills/hai-module-create/configuration.md)を参照してください。
+
+## 開発とテスト
 
 ```bash
 pnpm --filter @h-ai/core test
 ```
 
-## License
+宣言の注釈と型検査できる例は [JSDoc 規約（中国語）](../../.agents/instructions/module-conventions.md#jsdoc-与示例验证) を参照してください。Node core.init は同期的に void を返します。単一ファイルの config.load 失敗結果は記録して続行するため、必須設定は validate して success を確認してください。ディレクトリー走査などの例外は伝播する場合があります。業務 HaiResult API は success を先に確認します。
+
+## ライセンス
 
 Apache-2.0