@h-ai/core 0.1.0-alpha9 → 1.0.0-beta.10

package/dist/core-types-DM_AiIaS.d.ts

@@ -0,0 +1,2885 @@
+import { z, ZodType } from 'zod';
+
+/**
+ * @h-ai/core — 访问条件与请求策略配置；Schema 可在构建工具中使用，不依赖 Node API。
+ * @module core-access-config
+ */
+
+/**
+ * 可信代理列表；auto 仅在受管的私有容器入口中使用本容器网段，普通宿主忽略转发头。
+ * @example
+ * ```ts
+ * import { TrustedProxiesSchema } from '@h-ai/core'
+ * const proxies = TrustedProxiesSchema.parse(['192.0.2.10'])
+ * ```
+ */
+declare const TrustedProxiesSchema: z.ZodUnion<readonly [z.ZodLiteral<"auto">, z.ZodArray<z.ZodUnion<readonly [z.ZodIPv4, z.ZodIPv6, z.ZodCIDRv4, z.ZodCIDRv6]>>]>;
+/**
+ * 可复用的可信 IP 与时间窗口条件；空列表不限制对应维度。
+ * @example
+ * ```ts
+ * import { AccessConditionSchema } from '@h-ai/core'
+ * const condition = AccessConditionSchema.parse({ allowIps: ['192.0.2.0/24'], timezone: 'Asia/Shanghai' })
+ * ```
+ */
+declare const AccessConditionSchema: z.ZodObject<{
+    allowIps: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodIPv4, z.ZodIPv6, z.ZodCIDRv4, z.ZodCIDRv6]>>>;
+    denyIps: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodIPv4, z.ZodIPv6, z.ZodCIDRv4, z.ZodCIDRv6]>>>;
+    timezone: z.ZodDefault<z.ZodString>;
+    windows: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        days: z.ZodArray<z.ZodNumber>;
+        start: z.ZodString;
+        end: z.ZodString;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+/**
+ * 每次请求的访问策略：全局条件与所有命中规则必须同时满足；未命中规则不受该规则限制。
+ * @example
+ * ```ts
+ * import { RequestAccessPolicySchema } from '@h-ai/core'
+ * const policy = RequestAccessPolicySchema.parse({ rules: [{ id: 'external', paths: ['/api/v1/external/**'], allowIps: ['192.0.2.0/24'] }] })
+ * ```
+ */
+declare const RequestAccessPolicySchema: z.ZodObject<{
+    global: z.ZodOptional<z.ZodObject<{
+        allowIps: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodIPv4, z.ZodIPv6, z.ZodCIDRv4, z.ZodCIDRv6]>>>;
+        denyIps: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodIPv4, z.ZodIPv6, z.ZodCIDRv4, z.ZodCIDRv6]>>>;
+        timezone: z.ZodDefault<z.ZodString>;
+        windows: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            days: z.ZodArray<z.ZodNumber>;
+            start: z.ZodString;
+            end: z.ZodString;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+    rules: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        allowIps: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodIPv4, z.ZodIPv6, z.ZodCIDRv4, z.ZodCIDRv6]>>>;
+        denyIps: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodIPv4, z.ZodIPv6, z.ZodCIDRv4, z.ZodCIDRv6]>>>;
+        timezone: z.ZodDefault<z.ZodString>;
+        windows: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            days: z.ZodArray<z.ZodNumber>;
+            start: z.ZodString;
+            end: z.ZodString;
+        }, z.core.$strict>>>;
+        id: z.ZodString;
+        paths: z.ZodArray<z.ZodString>;
+        methods: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            GET: "GET";
+            HEAD: "HEAD";
+            POST: "POST";
+            PUT: "PUT";
+            PATCH: "PATCH";
+            DELETE: "DELETE";
+            OPTIONS: "OPTIONS";
+            CONNECT: "CONNECT";
+            TRACE: "TRACE";
+        }>>>;
+        encryption: z.ZodOptional<z.ZodEnum<{
+            required: "required";
+            disabled: "disabled";
+        }>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+/**
+ * 关闭策略、内联策略或单个独立 YAML 文件；文件与内联规则不能混合。
+ * @example
+ * ```ts
+ * import { RequestAccessConfigSchema } from '@h-ai/core'
+ * const config = RequestAccessConfigSchema.parse({ file: './config/security/request-access.yml' })
+ * ```
+ */
+declare const RequestAccessConfigSchema: z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+    file: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    global: z.ZodOptional<z.ZodObject<{
+        allowIps: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodIPv4, z.ZodIPv6, z.ZodCIDRv4, z.ZodCIDRv6]>>>;
+        denyIps: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodIPv4, z.ZodIPv6, z.ZodCIDRv4, z.ZodCIDRv6]>>>;
+        timezone: z.ZodDefault<z.ZodString>;
+        windows: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            days: z.ZodArray<z.ZodNumber>;
+            start: z.ZodString;
+            end: z.ZodString;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+    rules: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        allowIps: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodIPv4, z.ZodIPv6, z.ZodCIDRv4, z.ZodCIDRv6]>>>;
+        denyIps: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodIPv4, z.ZodIPv6, z.ZodCIDRv4, z.ZodCIDRv6]>>>;
+        timezone: z.ZodDefault<z.ZodString>;
+        windows: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            days: z.ZodArray<z.ZodNumber>;
+            start: z.ZodString;
+            end: z.ZodString;
+        }, z.core.$strict>>>;
+        id: z.ZodString;
+        paths: z.ZodArray<z.ZodString>;
+        methods: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            GET: "GET";
+            HEAD: "HEAD";
+            POST: "POST";
+            PUT: "PUT";
+            PATCH: "PATCH";
+            DELETE: "DELETE";
+            OPTIONS: "OPTIONS";
+            CONNECT: "CONNECT";
+            TRACE: "TRACE";
+        }>>>;
+        encryption: z.ZodOptional<z.ZodEnum<{
+            required: "required";
+            disabled: "disabled";
+        }>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>]>;
+
+/**
+ * @h-ai/core — 核心配置 Schema
+ *
+ * 核心模块的配置 Schema 定义（使用 Zod 校验）
+ * @module core-config
+ */
+
+/**
+ * 环境类型 Schema。
+ * @example
+ * ```ts
+ * import { EnvSchema } from '@h-ai/core'
+ * const config = EnvSchema.parse('production')
+ * ```
+ */
+declare const EnvSchema: z.ZodEnum<{
+    development: "development";
+    production: "production";
+    test: "test";
+    staging: "staging";
+}>;
+/**
+ * 日志级别 Schema。
+ * @example
+ * ```ts
+ * import { LogLevelSchema } from '@h-ai/core'
+ * const config = LogLevelSchema.parse('info')
+ * ```
+ */
+declare const LogLevelSchema: z.ZodEnum<{
+    error: "error";
+    trace: "trace";
+    debug: "debug";
+    info: "info";
+    warn: "warn";
+    fatal: "fatal";
+}>;
+/**
+ * 日志格式 Schema。
+ * @example
+ * ```ts
+ * import { LogFormatSchema } from '@h-ai/core'
+ * const config = LogFormatSchema.parse('json')
+ * ```
+ */
+declare const LogFormatSchema: z.ZodEnum<{
+    json: "json";
+    pretty: "pretty";
+}>;
+/**
+ * 日志配置 Schema。
+ * @example
+ * ```ts
+ * import { LoggingConfigSchema } from '@h-ai/core'
+ * const config = LoggingConfigSchema.parse({ level: 'warn', format: 'json', redact: ['password'] })
+ * ```
+ */
+declare const LoggingConfigSchema: z.ZodObject<{
+    level: z.ZodDefault<z.ZodEnum<{
+        error: "error";
+        trace: "trace";
+        debug: "debug";
+        info: "info";
+        warn: "warn";
+        fatal: "fatal";
+    }>>;
+    format: z.ZodDefault<z.ZodEnum<{
+        json: "json";
+        pretty: "pretty";
+    }>>;
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    redact: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * Core 配置 Schema。
+ *
+ * 描述应用的基础元数据和日志配置，通常通过 `_core.yml` 加载。
+ * 未声明的字段拒绝加载；业务配置放独立 app.yml 并使用应用 Schema 校验。
+ * ID 长度/前缀由每次 core.id 调用参数决定，不存在全局 ID 配置。
+ * @example
+ * ```ts
+ * import { CoreConfigSchema } from '@h-ai/core'
+ * const config = CoreConfigSchema.parse({ name: 'orders', env: 'production', logging: { level: 'info' } })
+ * ```
+ */
+declare const CoreConfigSchema: z.ZodObject<{
+    name: z.ZodDefault<z.ZodString>;
+    version: z.ZodDefault<z.ZodString>;
+    env: z.ZodDefault<z.ZodEnum<{
+        development: "development";
+        production: "production";
+        test: "test";
+        staging: "staging";
+    }>>;
+    logging: z.ZodOptional<z.ZodObject<{
+        level: z.ZodDefault<z.ZodEnum<{
+            error: "error";
+            trace: "trace";
+            debug: "debug";
+            info: "info";
+            warn: "warn";
+            fatal: "fatal";
+        }>>;
+        format: z.ZodDefault<z.ZodEnum<{
+            json: "json";
+            pretty: "pretty";
+        }>>;
+        context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        redact: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    defaultLocale: z.ZodDefault<z.ZodString>;
+}, z.core.$strict>;
+
+/**
+ * 校验消息 key 集合（locale 无关的标识符）。
+ *
+ * 调用方负责把每个 key 映射到自己模块的 i18n 字典（例如 kit 的
+ * `kit_validationStringMin`、serv 的 `serv_validationStringMin`）。
+ *
+ * @example
+ * ```ts
+ * const key: ZodValidationMessageKey = 'validationRequired'
+ * ```
+ */
+/**
+ * 创建按固定前缀派生消息 key 的 `ZodMessageGetter`。
+ *
+ * 适用于模块消息键遵循 `{prefix}_{ZodValidationMessageKey}` 命名约定的场景，
+ * 例如 `serv_validationRequired`、`kit_validationEmail`。
+ *
+ * @param prefix - 模块消息前缀，如 `serv`、`kit`
+ * @param getMessage - 实际消息获取函数，接收带前缀的消息 key
+ * @returns 可注入给 `core.zodValidation.*` 的 `ZodMessageGetter`
+ *
+ * @example
+ * ```ts
+ * const getMessage = createPrefixedZodMessageGetter<string>(
+ *   'serv',
+ *   (messageKey, params) => `${messageKey}:${params?.min ?? ''}`,
+ * )
+ *
+ * getMessage('validationStringMin', { min: 3 })
+ * // 'serv_validationStringMin:3'
+ * ```
+ */
+declare function createPrefixedZodMessageGetter<TMessageKey extends string>(prefix: string, getMessage: (messageKey: TMessageKey, params?: Record<string, string | number>) => string): ZodMessageGetter;
+/**
+ * 一步把 Zod SafeParseError / ZodError 转为扁平 `ValidationFormError[]`。
+ *
+ * @param error - Zod `SafeParseError`、`ZodError` 或兼容的错误对象
+ * @param getMessage - 调用方注入的消息获取器
+ * @returns 扁平化后的表单错误列表
+ *
+ * @example
+ * ```ts
+ * const errors = mapZodErrorToFormErrors(
+ *   {
+ *     issues: [
+ *       { path: ['email'], code: 'invalid_format', format: 'email', message: 'Invalid email address' },
+ *     ],
+ *   },
+ *   key => key === 'validationEmail' ? '请输入合法邮箱地址' : '输入不合法',
+ * )
+ * ```
+ */
+declare function mapZodErrorToFormErrors(error: unknown, getMessage: ZodMessageGetter): ValidationFormError[];
+/**
+ * Zod 校验 i18n 工具集合（通过 `core.zodValidation` 暴露）。
+ *
+ * 按最小知识原则，仅暴露调用方真正需要的两个入口：
+ * 1. `createPrefixedZodMessageGetter()`：把模块前缀与消息获取器适配起来
+ * 2. `mapZodErrorToFormErrors()`：一步完成 ZodError → 本地化扁平错误列表
+ * @example
+ * ```ts
+ * import { core } from '@h-ai/core'
+ * const tools = core.zodValidation
+ * tools.mapZodErrorToFormErrors({ issues: [{ path: ['name'], code: 'invalid_type', expected: 'string', message: 'Invalid input' }] }, key => key)
+ * ```
+ */
+declare const zodValidation: {
+    createPrefixedZodMessageGetter: typeof createPrefixedZodMessageGetter;
+    mapZodErrorToFormErrors: typeof mapZodErrorToFormErrors;
+};
+
+/**
+ * @h-ai/core — 配置管理（浏览器占位实现）
+ *
+ * 浏览器环境没有文件系统，不能加载 / 监听 YAML 配置文件。
+ * 该实现保持 `core.config` API 形态与 Node.js 一致，但所有文件相关操作
+ * 都返回明确的 SERVICE_UNAVAILABLE，避免运行时出现 `core.config` 为 undefined。
+ * @module core-function-config.browser
+ */
+
+/**
+ * 浏览器端 config 占位对象，API 与 Node.js config 保持一致。
+ * @example 模块内部上下文
+ * ```ts
+ * const result = config.load('app', '/srv/app/config/app.yml')
+ * if (!result.success) result.error.message
+ * ```
+ */
+declare const config$1: {
+    loadEnvFiles(_options: {
+        mode: string;
+        envDir?: string;
+    }): HaiResult<Record<string, string>>;
+    load<T>(_name: string, _filePath: string, _schema?: ZodType<T>): HaiResult<T>;
+    validate<T>(_name: string, _schema: ZodType<T>): HaiResult<T>;
+    get<T>(_name: string): T | undefined;
+    getOrThrow<T>(_name: string): T;
+    reload(_name: string): HaiResult<unknown>;
+    has(_name: string): boolean;
+    clear(_name?: string): void;
+    keys(): string[];
+    watch<T = unknown>(_name: string, callback: WatchCallback<T>): () => void;
+    unwatch(_name?: string): void;
+    isWatching(_name: string): boolean;
+};
+
+/** 通用环境配置：来源合并、结构覆盖与无损 dotenv 编解码，不依赖业务模块。 */
+
+/**
+ * 单个环境来源中的字面变量，undefined 表示未设置。
+ * @example 模块内部上下文
+ * ```ts
+ * const values: Environment = { HAI_APP_NAME: 'Example' }
+ * ```
+ */
+type Environment = Record<string, string | undefined>;
+/**
+ * 从低到高合并来源；高来源父项删除旧细项，同来源始终先父后子。
+ * @example 模块内部上下文
+ * ```ts
+ * const values = mergeEnv([{ HAI_APP_NAME: 'base' }, { HAI_APP_NAME: 'test' }])
+ * ```
+ */
+declare function mergeEnv(layers: readonly Environment[]): Record<string, string>;
+/**
+ * dotenv 使用 Node 字面规则；补齐生成器双引号的 JSON 转义，拒绝同文件重复键。
+ * @example 模块内部上下文
+ * ```ts
+ * const values = parseEnvironment('HAI_APP_NAME=Example\n')
+ * ```
+ */
+declare function parseEnvironment(text: string): Record<string, string>;
+/**
+ * 所有值均按字面量编码；排序让模块 JSON 位于其细项之前。
+ * @example 模块内部上下文
+ * ```ts
+ * const text = stringifyEnv({ HAI_APP_NAME: 'Example' })
+ * ```
+ */
+declare function stringifyEnv(values: Record<string, string>, options?: {
+    target?: 'node' | 'compose';
+}): string;
+/**
+ * 在给定结构上解析环境变量；父对象提供基础值，具体路径继续覆盖。
+ * @example 模块内部上下文
+ * ```ts
+ * const result = resolveEnvironment({ name: 'app', value: { name: 'Example' }, environment: { HAI_APP_NAME: 'Test' } })
+ * ```
+ */
+declare function resolveEnvironment(options: {
+    name: string;
+    value: unknown;
+    environment?: Environment;
+    schema?: ZodType;
+    shape?: Readonly<Record<string, unknown>>;
+    missing?: 'error' | 'empty';
+}, literal?: boolean): HaiResult<unknown>;
+/**
+ * 默认展开对象，数组与动态键字典保留 JSON；不做模块名称判断。
+ * @example 模块内部上下文
+ * ```ts
+ * const values = toEnv({ prefix: 'HAI_APP', value: { name: 'Example', tags: ['demo'] } })
+ * ```
+ */
+declare function toEnv(options: {
+    prefix: string;
+    value: unknown;
+    schema?: ZodType;
+    shape?: Readonly<Record<string, unknown>>;
+}): Record<string, string>;
+
+/**
+ * 配置管理对象。
+ * @example 模块内部上下文
+ * ```ts
+ * const result = config.load('app', '/srv/app/config/app.yml')
+ * if (!result.success) result.error.message
+ * ```
+ */
+declare const config: {
+    /**
+     * 合并从低到高的环境来源；高来源父项替换旧节点，同来源细项覆盖父 JSON。
+     * @param layers - 按优先级排列的字面变量。
+     * @returns 合并后的变量，可能含秘密。
+     * @example
+     * ```ts
+     * import { core } from '@h-ai/core'
+     * const value = core.config.mergeEnv([{ HAI_APP_NAME: 'base' }, { HAI_APP_NAME: 'test' }])
+     * ```
+     */
+    mergeEnv: typeof mergeEnv;
+    /**
+     * 解析 dotenv 字面文本，拒绝重复键，不执行 shell 或变量展开。
+     * @param text - dotenv 文本，可能包含秘密。
+     * @returns 字面变量；重复键抛出不含变量值的错误。
+     * @example
+     * ```ts
+     * import { core } from '@h-ai/core'
+     * const value = core.config.parseEnv('HAI_APP_NAME=Example\n')
+     * ```
+     */
+    parseEnv: typeof parseEnvironment;
+    /**
+     * 无损编码 dotenv，父变量排在细项前；含秘密时只能写入受保护文件。
+     * @param values - 字面变量，不进行脱敏。
+     * @param options - 输出语法目标，默认 Node dotenv。
+     * @param options.target - Compose 目标同时处理其美元符号插值规则。
+     * @returns dotenv 文本；非法变量名抛错。
+     * @example
+     * ```ts
+     * import { core } from '@h-ai/core'
+     * const value = core.config.stringifyEnv({ HAI_APP_NAME: 'Example' })
+     * ```
+     */
+    stringifyEnv: typeof stringifyEnv;
+    /**
+     * 按已有结构或 Schema 解析父 JSON 和细项，不修改缓存或进程环境。
+     * @param options - 配置名、原始结构、变量、可选 Schema 和缺失插值规则。
+     * @returns 解析结果；调用方仍须执行最终 Schema 校验。
+     * @example
+     * ```ts
+     * import { core } from '@h-ai/core'
+     * const value = core.config.resolve({ name: 'app', value: { name: 'Example' }, environment: { HAI_APP_NAME: 'Test' } })
+     * ```
+     */
+    resolve: (options: Parameters<typeof resolveEnvironment>[0]) => HaiResult<unknown>;
+    /**
+     * 默认将对象展开为细项；数组、动态字典和空对象保留 JSON。
+     * @param options - 完整变量前缀、配置值和可选 Schema。
+     * @returns 字面环境变量，不脱敏；非法名称抛错。
+     * @example
+     * ```ts
+     * import { core } from '@h-ai/core'
+     * const value = core.config.toEnv({ prefix: 'HAI_APP', value: { name: 'Example', tags: ['demo'] } })
+     * ```
+     */
+    toEnv: typeof toEnv;
+    /**
+     * 读取 dotenv 文件并按统一顺序合并，不修改进程环境。
+     *
+     * 优先级：已有进程环境 > .env.<mode>.local > .env.local > .env.<mode> > .env。
+     * development/production 分别映射到 dev/prod；不存在的文件跳过。
+     * 返回值可能包含私有配置，仅在 Node 启动/构建边界注入，不下发浏览器。
+     * @param options - 文件所在目录及环境模式
+     * @param options.mode - dev/test/prod 或 Vite 的 development/production
+     * @param options.envDir - dotenv 所在目录，默认进程工作目录
+     * @returns 已合并的变量；非法模式或读取失败返回配置错误，不包含文件内容
+     * @example
+     * ```ts
+     * const env = core.config.loadEnvFiles({ mode: 'dev', envDir: '.' })
+     * if (!env.success) throw new Error(env.error.message)
+     * Object.assign(process.env, env.data)
+     * core.init({ configDir: './config' })
+     * ```
+     */
+    loadEnvFiles(options: {
+        mode: string;
+        envDir?: string;
+    }): HaiResult<Record<string, string>>;
+    /**
+     * 加载配置到缓存。
+     *
+     * 加载 YAML 文件并可选地用 Zod Schema 校验，成功后写入缓存。
+     *
+     * @param name - 配置名称（缓存 key）
+     * @param filePath - YAML 文件路径
+     * @param schema - 可选 Zod Schema（不传则跳过校验）
+     * @returns 成功时返回解析后的配置数据；失败时返回 HaiError
+     *
+     * @example
+     * ```ts
+     * const result = config.load('core', './config/_core.yml', CoreConfigSchema)
+     * if (result.success) {
+     *   // result.data 为校验后的配置
+     * }
+     * ```
+     */
+    load<T>(name: string, filePath: string, schema?: ZodType<T>): HaiResult<T>;
+    /**
+     * 验证已加载的配置数据。
+     *
+     * 对缓存中的配置数据重新用 Schema 校验，校验通过后更新缓存。
+     *
+     * @param name - 配置名称
+     * @param schema - Zod 验证模式
+     * @returns 校验结果；未加载时返回 NOT_LOADED，格式错误返回 VALIDATION_ERROR
+     *
+     * @example
+     * ```ts
+     * const result = config.validate('app', AppSchema)
+     * if (!result.success) {
+     *   // result.error.code 可能为 NOT_LOADED 或 VALIDATION_ERROR
+     * }
+     * ```
+     */
+    validate<T>(name: string, schema: ZodType<T>): HaiResult<T>;
+    /**
+     * 获取已加载的配置。
+     *
+     * @param name - 配置名称
+     * @returns 配置数据；未加载时返回 undefined
+     *
+     * @example
+     * ```ts
+     * const cfg = config.get<CoreConfig>('core')
+     * if (cfg) {
+     *   // 使用 cfg
+     * }
+     * ```
+     */
+    get<T>(name: string): T | undefined;
+    /**
+     * 获取配置，不存在时抛出错误。
+     *
+     * @param name - 配置名称
+     * @returns 配置数据
+     * @throws 配置未加载时抛出 Error
+     *
+     * @example
+     * ```ts
+     * try {
+     *   const cfg = config.getOrThrow<CoreConfig>('core')
+     * } catch (e) {
+     *   // 配置未加载
+     * }
+     * ```
+     */
+    getOrThrow<T>(name: string): T;
+    /**
+     * 重新加载配置。
+     *
+     * 从磁盘重新读取配置文件并更新缓存，同时通知所有 watch 回调。
+     *
+     * @param name - 配置名称
+     * @returns 重载结果；未加载时返回 NOT_LOADED
+     *
+     * @example
+     * ```ts
+     * const result = config.reload('app')
+     * ```
+     */
+    reload(name: string): HaiResult<unknown>;
+    /**
+     * 检查配置是否已加载。
+     *
+     * @param name - 配置名称
+     * @returns 是否已加载到缓存
+     *
+     * @example
+     * ```ts
+     * if (config.has('db')) {
+     *   const dbCfg = config.get('db')
+     * }
+     * ```
+     */
+    has(name: string): boolean;
+    /**
+     * 清除配置缓存（同时停止对应监听）。
+     *
+     * @param name - 配置名称；不传则清除全部
+     *
+     * @example
+     * ```ts
+     * config.clear('app')   // 清除单个
+     * config.clear()        // 清除全部
+     * ```
+     */
+    clear(name?: string): void;
+    /**
+     * 获取所有已加载的配置名称。
+     *
+     * @returns 配置名称数组
+     *
+     * @example
+     * ```ts
+     * const names = config.keys() // ['core', 'db', 'app']
+     * ```
+     */
+    keys(): string[];
+    /**
+     * 监听配置文件变更并自动重载。
+     *
+     * 普通写入、原子替换及删除重建均触发重载；失败保留最近成功的缓存并通知错误。
+     * 配置未加载时立即回调 NOT_LOADED 错误。
+     *
+     * @param name - 配置名称
+     * @param callback - 配置变更回调，接收新配置或错误
+     * @returns 取消监听函数
+     *
+     * @example
+     * ```ts
+     * const unwatch = config.watch('app', (cfg, error) => {
+     *   if (error) { core.logger.error('reload failed', { error }); return }
+     *   core.logger.info('config updated', { cfg })
+     * })
+     * // 取消监听
+     * unwatch()
+     * ```
+     */
+    watch<T = unknown>(name: string, callback: WatchCallback<T>): () => void;
+    /**
+     * 停止配置文件监听。
+     *
+     * @param name - 配置名称；不传则停止所有监听
+     *
+     * @example
+     * ```ts
+     * config.unwatch('app')  // 停止单个
+     * config.unwatch()       // 停止全部
+     * ```
+     */
+    unwatch(name?: string): void;
+    /**
+     * 检查是否正在监听某个配置。
+     *
+     * @param name - 配置名称
+     * @returns 是否有活跃的 watcher
+     *
+     * @example
+     * ```ts
+     * if (config.isWatching('app')) {
+     *   config.unwatch('app')
+     * }
+     * ```
+     */
+    isWatching(name: string): boolean;
+};
+
+/**
+ * @h-ai/core — ID 生成器
+ *
+ * 基于 nanoid 的 ID 生成工具。
+ * @module core-function-id
+ */
+/**
+ * ID 生成工具对象。
+ * @example
+ * ```ts
+ * import { core } from '@h-ai/core'
+ * const tools = core.id
+ * tools.withPrefix('order_')
+ * ```
+ */
+declare const id: {
+    /**
+     * 生成标准 nanoid（默认 21 字符）。
+     *
+     * @param length - ID 长度
+     * @returns nanoid 字符串
+     *
+     * @example
+     * ```ts
+     * const id = core.id.generate(16)
+     * ```
+     */
+    generate(length?: number): string;
+    /**
+     * 生成短 ID（10 字符）。
+     *
+     * @example
+     * ```ts
+     * const shortId = core.id.short()
+     * ```
+     */
+    short(): string;
+    /**
+     * 生成带前缀的 ID。
+     *
+     * @param prefix - 前缀
+     * @param length - ID 长度
+     *
+     * @example
+     * ```ts
+     * const userId = core.id.withPrefix('user_')
+     * ```
+     */
+    withPrefix(prefix: string, length?: number): string;
+    /**
+     * 生成 Trace ID。
+     *
+     * @example
+     * ```ts
+     * const traceId = core.id.trace()
+     * ```
+     */
+    trace(): string;
+    /**
+     * 生成 Request ID。
+     *
+     * @example
+     * ```ts
+     * const requestId = core.id.request()
+     * ```
+     */
+    request(): string;
+    /**
+     * 生成 UUID v4。
+     *
+     * @example
+     * ```ts
+     * const uuid = core.id.uuid()
+     * ```
+     */
+    uuid(): string;
+    /**
+     * 验证是否为有效的 UUID v4。
+     *
+     * @example
+     * ```ts
+     * core.id.isValidUUID('f47ac10b-58cc-4372-a567-0e02b2c3d479')
+     * ```
+     */
+    isValidUUID(uuid: string): boolean;
+    /**
+     * 验证是否为有效的 nanoid。
+     *
+     * @param str - 待验证字符串
+     * @param length - 期望长度
+     *
+     * @example
+     * ```ts
+     * core.id.isValidNanoId('abc', 3)
+     * ```
+     */
+    isValidNanoId(str: string, length?: number): boolean;
+};
+
+/**
+ * @h-ai/core — i18n 国际化工具
+ *
+ * 国际化核心实现，为 JSON 消息字典提供通用类型支持。
+ * @module core-i18n-utils
+ */
+
+declare function getGlobalLocale(): Locale;
+declare function setGlobalLocale(locale: Locale): void;
+/**
+ * 在独立的 Node 请求语言上下文中运行操作，异步子任务继承当前语言。
+ *
+ * 显式 MessageOptions.locale 优先于请求语言，请求结束不会改变进程启动默认值。
+ *
+ * @param locale - 当前请求的语言
+ * @param operation - 请求处理或 SSR 操作；保留原同步值或 Promise 返回类型
+ * @returns operation 的原始返回值
+ * @throws 浏览器入口没有 Node 请求上下文时抛出错误；浏览器使用 setGlobalLocale。
+ * @example
+ * ```ts
+ * const response = await core.i18n.runWithLocale('en-US', async () => {
+ *   await loadData()
+ *   return renderPage()
+ * })
+ * ```
+ */
+declare function runWithLocale<T>(locale: Locale, operation: () => T): T;
+/**
+ * 创建消息获取函数。
+ *
+ * 各模块通过此函数创建消息获取器，依次读取显式 locale、Node 请求语言和应用默认语言。
+ * 若指定的 locale 不支持，回退到默认语言；key 不存在时返回 key 本身。
+ *
+ * @param messages - 多语言消息对象
+ * @returns 消息获取函数
+ *
+ * @example
+ * ```ts
+ * const getMessage = createMessageGetter({
+ *   'zh-CN': { hello: '你好' },
+ *   'en-US': { hello: 'Hello' },
+ * })
+ * getMessage('hello')                              // '你好'
+ * getMessage('hello', { locale: 'en-US' })          // 'Hello'
+ * getMessage('msg', { params: { name: 'World' } }) // 插值
+ * ```
+ */
+declare function createMessageGetter<K extends string>(messages: LocaleMessages<K>): (key: K, options?: MessageOptions) => string;
+/**
+ * 语言上下文、字典消息获取与插值工具；Node 请求通过 runWithLocale 隔离语言。
+ * @example
+ * ```ts
+ * import { core } from '@h-ai/core'
+ * const tools = core.i18n
+ * const message = tools.createMessageGetter({ 'en-US': { hello: 'Hello' }, 'zh-CN': { hello: '你好' } })
+ * message('hello', { locale: 'en-US' })
+ * ```
+ */
+declare const i18n: {
+    DEFAULT_LOCALES: LocaleInfo[];
+    DEFAULT_LOCALE: string;
+    setGlobalLocale: typeof setGlobalLocale;
+    getGlobalLocale: typeof getGlobalLocale;
+    runWithLocale: typeof runWithLocale;
+    createMessageGetter: typeof createMessageGetter;
+    coreM: (key: "$schema" | "core_errorUnknown" | "core_errorNetwork" | "core_errorTimeout" | "core_errorNotFound" | "core_errorUnauthorized" | "core_errorForbidden" | "core_errorValidation" | "core_errorInternal" | "core_actionConfirm" | "core_actionCancel" | "core_actionSave" | "core_actionDelete" | "core_actionEdit" | "core_actionCreate" | "core_actionUpdate" | "core_actionSearch" | "core_actionReset" | "core_actionSubmit" | "core_actionLoading" | "core_actionRetry" | "core_statusSuccess" | "core_statusFailed" | "core_statusPending" | "core_statusProcessing" | "core_statusCompleted" | "core_statusCancelled" | "core_validationRequired" | "core_validationMinLength" | "core_validationMaxLength" | "core_validationEmail" | "core_validationUrl" | "core_validationNumber" | "core_validationInteger" | "core_validationPositive" | "core_validationPattern" | "core_timeJustNow" | "core_timeSecondsAgo" | "core_timeMinutesAgo" | "core_timeHoursAgo" | "core_timeDaysAgo" | "core_timeWeeksAgo" | "core_timeMonthsAgo" | "core_timeYearsAgo" | "core_browserFeatureUnsupported" | "core_configEnvVarMissing" | "core_configFileNotExist" | "core_configParseFailed" | "core_configValidationFailed" | "core_configNotLoaded" | "core_configUnsupportedInBrowser" | "core_cryptoRandomUnavailable" | "core_parallelConcurrencyInvalid" | "core_runtimeStartFailed" | "core_runtimeCloseFailed" | "core_runtimeEnvMissing" | "core_runtimeConfigInvalid" | "core_runtimeConfigProblem" | "core_runtimeErrorCode" | "core_requestAccessDenied", options?: MessageOptions) => string;
+};
+
+/**
+ * @h-ai/core — 数组操作工具
+ * @module core-util-array
+ */
+/**
+ * 数组去重。
+ * @param arr - 输入数组
+ * @returns 去重后的新数组
+ * @remarks 保留首次出现的顺序；空数组返回空数组。
+ *
+ * @example
+ * ```ts
+ * array.unique([1, 1, 2]) // [1, 2]
+ * ```
+ */
+declare function unique<T>(arr: T[]): T[];
+/**
+ * 按条件分组。
+ * @param arr - 输入数组
+ * @param fn - 分组键生成函数
+ * @returns 分组结果对象
+ * @remarks 当数组为空时返回空对象；原型同名键也作为独立的自有分组。
+ *
+ * @example
+ * ```ts
+ * array.groupBy([{ r: 'a' }, { r: 'b' }], item => item.r)
+ * ```
+ */
+declare function groupBy<T, K extends string | number>(arr: T[], fn: (item: T) => K): Record<K, T[]>;
+/**
+ * 分割为指定大小的块。
+ * @param arr - 输入数组
+ * @param size - 每块大小（应为正整数）
+ * @returns 分块后的二维数组
+ * @remarks size <= 0 时结果为空数组。
+ *
+ * @example
+ * ```ts
+ * array.chunk([1, 2, 3], 2) // [[1,2],[3]]
+ * ```
+ */
+declare function chunk<T>(arr: T[], size: number): T[][];
+/**
+ * 获取第一个元素。
+ * @param arr - 输入数组
+ * @returns 第一个元素或 undefined
+ * @remarks 空数组返回 undefined。
+ *
+ * @example
+ * ```ts
+ * array.first([1, 2, 3]) // 1
+ * ```
+ */
+declare function first<T>(arr: T[]): T | undefined;
+/**
+ * 获取最后一个元素。
+ * @param arr - 输入数组
+ * @returns 最后一个元素或 undefined
+ * @remarks 空数组返回 undefined。
+ *
+ * @example
+ * ```ts
+ * array.last([1, 2, 3]) // 3
+ * ```
+ */
+declare function last<T>(arr: T[]): T | undefined;
+/**
+ * 数组扁平化。
+ * @param arr - 二维数组
+ * @returns 扁平化后的数组
+ * @remarks 仅扁平一层。
+ *
+ * @example
+ * ```ts
+ * array.flatten([[1], [2, 3]]) // [1, 2, 3]
+ * ```
+ */
+declare function flatten<T>(arr: T[][]): T[];
+/**
+ * 过滤掉 null 和 undefined。
+ * @param arr - 输入数组
+ * @returns 过滤后的数组
+ * @remarks 会保留 0、false、'' 等假值。
+ *
+ * @example
+ * ```ts
+ * array.compact([0, null, 1]) // [0, 1]
+ * ```
+ */
+declare function compact<T>(arr: (T | null | undefined)[]): T[];
+/**
+ * 随机打乱数组。
+ * @param arr - 输入数组
+ * @returns 打乱后的新数组
+ * @remarks 不修改原数组。
+ *
+ * @example
+ * ```ts
+ * const shuffled = array.shuffle([1, 2, 3])
+ * ```
+ */
+declare function shuffle<T>(arr: T[]): T[];
+/**
+ * 取数组交集。
+ * @param arr1 - 数组 1
+ * @param arr2 - 数组 2
+ * @returns 交集数组
+ * @remarks 保持 arr1 中的顺序。
+ *
+ * @example
+ * ```ts
+ * array.intersection([1, 2], [2, 3]) // [2]
+ * ```
+ */
+declare function intersection<T>(arr1: T[], arr2: T[]): T[];
+/**
+ * 取数组差集。
+ * @param arr1 - 数组 1
+ * @param arr2 - 数组 2
+ * @returns 差集数组（arr1 中存在且 arr2 不存在）
+ * @remarks 保持 arr1 中的顺序。
+ *
+ * @example
+ * ```ts
+ * array.difference([1, 2, 3], [2]) // [1, 3]
+ * ```
+ */
+declare function difference<T>(arr1: T[], arr2: T[]): T[];
+/**
+ * 数组操作工具对象。
+ * @example
+ * ```ts
+ * import { core } from '@h-ai/core'
+ * const tools = core.array
+ * tools.chunk([1, 2, 3], 2)
+ * ```
+ */
+declare const array: {
+    unique: typeof unique;
+    groupBy: typeof groupBy;
+    chunk: typeof chunk;
+    first: typeof first;
+    last: typeof last;
+    flatten: typeof flatten;
+    compact: typeof compact;
+    shuffle: typeof shuffle;
+    intersection: typeof intersection;
+    difference: typeof difference;
+};
+
+/**
+ * @h-ai/core — 异步操作工具
+ * @module core-util-async
+ */
+/**
+ * 延迟执行。
+ *
+ * @param ms - 延迟毫秒数
+ * @returns 延迟完成后的 Promise
+ *
+ * @example
+ * ```ts
+ * await async.delay(1000)
+ * ```
+ */
+declare function delay(ms: number): Promise<void>;
+/**
+ * 添加超时限制。
+ *
+ * @param promise - 目标 Promise
+ * @param ms - 超时时间（毫秒）
+ * @returns 原 Promise 的结果
+ * @throws 超时将抛出错误
+ *
+ * @example
+ * ```ts
+ * await async.withTimeout(fetch('/api'), 5000)
+ * ```
+ */
+declare function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T>;
+/**
+ * 重试操作。
+ *
+ * @param fn - 待重试函数
+ * @param options - 重试配置
+ * @param options.maxRetries - 最大重试次数
+ * @param options.delay - 重试间隔（毫秒）
+ * @returns 成功的结果
+ * @throws 重试耗尽后抛出最后一次错误
+ *
+ * @example
+ * ```ts
+ * await async.retry(() => fetch('/api'), { maxRetries: 3, delay: 500 })
+ * ```
+ */
+declare function retry<T>(fn: () => Promise<T>, options?: {
+    maxRetries?: number;
+    delay?: number;
+}): Promise<T>;
+/**
+ * 并行执行，限制并发数。
+ *
+ * @param items - 输入列表
+ * @param fn - 处理函数
+ * @param concurrency - 最大并发数，必须为大于 0 的安全整数
+ * @returns 处理结果列表
+ * @remarks 结果顺序与输入顺序一致。
+ * @throws 并发数非法时拒绝为 RangeError，不执行任何任务；任务异常原样传播。
+ *
+ * @example
+ * ```ts
+ * await async.parallel([1, 2, 3], async n => n * 2, 2)
+ * ```
+ */
+declare function parallel<T, R>(items: T[], fn: (item: T, index: number) => Promise<R>, concurrency?: number): Promise<R[]>;
+/**
+ * 串行执行。
+ *
+ * @param items - 输入列表
+ * @param fn - 处理函数
+ * @returns 处理结果列表
+ *
+ * @example
+ * ```ts
+ * await async.serial([1, 2], async n => n * 2)
+ * ```
+ */
+declare function serial<T, R>(items: T[], fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+/**
+ * 防抖。
+ *
+ * @param fn - 目标函数
+ * @param ms - 延迟毫秒数
+ * @returns 防抖后的函数
+ * @remarks 只会在最后一次调用后执行。
+ *
+ * @example
+ * ```ts
+ * const onInput = async.debounce(() => {}, 300)
+ * ```
+ */
+declare function debounce<Args extends unknown[]>(fn: (...args: Args) => unknown, ms: number): (...args: Args) => void;
+/**
+ * 节流。
+ *
+ * @param fn - 目标函数
+ * @param ms - 间隔毫秒数
+ * @returns 节流后的函数
+ * @remarks 在时间窗口内最多触发一次。
+ *
+ * @example
+ * ```ts
+ * const onScroll = async.throttle(() => {}, 200)
+ * ```
+ */
+declare function throttle<Args extends unknown[]>(fn: (...args: Args) => unknown, ms: number): (...args: Args) => void;
+/**
+ * 异步操作工具对象。
+ * @example
+ * ```ts
+ * import { core } from '@h-ai/core'
+ * const tools = core.async
+ * await tools.retry(async () => 'ready', { maxRetries: 2 })
+ * ```
+ */
+declare const async: {
+    delay: typeof delay;
+    withTimeout: typeof withTimeout;
+    retry: typeof retry;
+    parallel: typeof parallel;
+    serial: typeof serial;
+    debounce: typeof debounce;
+    throttle: typeof throttle;
+};
+
+/**
+ * 生产进程默认要求跨主机共享状态；显式E2E测试可使用测试替身。
+ * @param environment - 服务端实际进程环境，不接受请求参数
+ * @param environment.NODE_ENV - 实际运行环境
+ * @param environment.HAI_CORE_ENV - 框架环境文件声明的运行环境
+ * @param environment.HAI_E2E - 显式真实端到端测试标记
+ * @param environment.HAI_E2E_MOCK - 显式模拟端到端测试标记
+ * @returns 是否拒绝仅本机/进程有效的状态后端
+ * @example
+ * ```ts
+ * import { core } from '@h-ai/core'
+ * const production = core.module.requiresSharedState({ HAI_CORE_ENV: 'production' }) // true
+ * const test = core.module.requiresSharedState({ NODE_ENV: 'production', HAI_E2E: '1' }) // false
+ * ```
+ */
+declare function requiresSharedState(environment: {
+    NODE_ENV?: string;
+    HAI_CORE_ENV?: string;
+    HAI_E2E?: string;
+    HAI_E2E_MOCK?: string;
+}): boolean;
+
+/**
+ * @h-ai/core — 对象操作工具
+ * @module core-util-object
+ */
+/**
+ * 深度克隆对象。
+ * 使用 structuredClone（Node 17+ / 现代浏览器），支持 Date、Map、Set、RegExp、
+ * ArrayBuffer、循环引用等 JSON 方案无法处理的类型。
+ *
+ * @param obj - 目标对象
+ * @returns 深度克隆结果
+ *
+ * @example
+ * ```ts
+ * const cloned = object.deepClone({ a: 1, d: new Date() })
+ * ```
+ */
+declare function deepClone<T>(obj: T): T;
+/**
+ * 深度合并多个对象。
+ * @param objects - 需要合并的对象列表
+ * @returns 合并后的新对象
+ * @remarks 仅递归合并普通对象字段；数组、Date、Map、Set 和类实例由后值直接覆盖，不修改输入。
+ *
+ * @example
+ * ```ts
+ * const merged = object.deepMerge({ a: 1 }, { b: 2 })
+ * ```
+ */
+declare function deepMerge<T extends Record<string, unknown>>(...objects: Partial<T>[]): T;
+/**
+ * 从对象中选取指定的键。
+ * @param obj - 目标对象
+ * @param keys - 要选取的键列表
+ * @returns 仅包含指定键的新对象
+ *
+ * @example
+ * ```ts
+ * object.pick({ a: 1, b: 2 }, ['a'])
+ * ```
+ */
+declare function pick<T extends Record<string, unknown>, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;
+/**
+ * 从对象中排除指定的键。
+ * @param obj - 目标对象
+ * @param keys - 要排除的键列表
+ * @returns 排除指定键后的新对象
+ *
+ * @example
+ * ```ts
+ * object.omit({ a: 1, b: 2 }, ['b'])
+ * ```
+ */
+declare function omit<T extends Record<string, unknown>, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
+/**
+ * 获取对象的所有键。
+ * @param obj - 目标对象
+ * @returns 键列表
+ *
+ * @example
+ * ```ts
+ * object.keys({ a: 1, b: 2 })
+ * ```
+ */
+declare function keys<T extends Record<string, unknown>>(obj: T): (keyof T)[];
+/**
+ * 获取对象的所有值。
+ * @param obj - 目标对象
+ * @returns 值列表
+ *
+ * @example
+ * ```ts
+ * object.values({ a: 1, b: 2 })
+ * ```
+ */
+declare function values<T extends Record<string, unknown>>(obj: T): T[keyof T][];
+/**
+ * 获取对象的键值对数组。
+ * @param obj - 目标对象
+ * @returns 键值对数组
+ *
+ * @example
+ * ```ts
+ * object.entries({ a: 1 })
+ * ```
+ */
+declare function entries<T extends Record<string, unknown>>(obj: T): [keyof T, T[keyof T]][];
+/**
+ * 从键值对数组创建对象。
+ * @param entries - 键值对数组
+ * @returns 生成的对象
+ *
+ * @example
+ * ```ts
+ * object.fromEntries([['a', 1]])
+ * ```
+ */
+declare function fromEntries<K extends string, V>(entries: [K, V][]): Record<K, V>;
+/**
+ * 对象操作工具对象。
+ * @example
+ * ```ts
+ * import { core } from '@h-ai/core'
+ * const tools = core.object
+ * tools.pick({ id: 'order-1', password: 'example-only' }, ['id'])
+ * ```
+ */
+declare const object: {
+    deepClone: typeof deepClone;
+    deepMerge: typeof deepMerge;
+    pick: typeof pick;
+    omit: typeof omit;
+    keys: typeof keys;
+    values: typeof values;
+    entries: typeof entries;
+    fromEntries: typeof fromEntries;
+};
+
+/** 顺序启动、反序关闭的薄编排，不持有模块配置、依赖容器或业务服务。 */
+
+/**
+ * 编排宿主明确拥有的模块和业务钩子，不推断模块类型或初始化参数。
+ * start/close 合并并发；启动失败反序回滚；关闭失败保留依赖和清理义务，下次 close/start 会重试。
+ * @param definitions - 按真实依赖顺序声明的初始化和关闭动作。
+ * @returns 不抛业务异常的生命周期控制器；仅报告安全诊断，配置失败附带原因和处理建议。
+ * @example
+ * ```ts
+ * import { core, ok } from '@h-ai/core'
+ * const runtime = core.module.createRuntime([
+ *   { name: 'application', start: () => ok(undefined), close: () => ok(undefined) },
+ * ])
+ * const started = await runtime.start()
+ * if (started.success) await runtime.close()
+ * ```
+ */
+declare function createRuntime(definitions: readonly RuntimeStep[]): ModuleRuntime;
+
+/**
+ * 清理诊断文本中的显式凭据、URL 凭据及调用方已知的秘密值；不猜测无标签的任意文本。
+ * @example
+ * ```ts
+ * import { core } from '@h-ai/core'
+ * const safe = core.sanitize.sanitizeText('verificationCode=123456')
+ * ```
+ */
+declare function sanitizeText(text: string, secretValues?: readonly string[]): string;
+/**
+ * 判断键名是否属于敏感字段
+ * @param key - 原始字段名；会统一 camelCase、kebab-case 与 snake_case。
+ * @param matcher - 自定义规则；省略时使用凭证字段默认规则。
+ * @returns 当前字段名是否被匹配为敏感字段。
+ * @example
+ * ```ts
+ * import { core } from '@h-ai/core'
+ * const safe = core.sanitize.isSensitiveKey('apiKey')
+ * ```
+ */
+declare function isSensitiveKey(key: string, matcher?: SensitiveKeyMatcher): boolean;
+/**
+ * 遮蔽 URL 的用户名、密码及敏感查询参数；OAuth 风格 fragment 按查询参数处理。
+ *
+ * 解析失败返回固定占位符，避免畸形地址把凭据原样写入日志。
+ *
+ * @param url - 待记录的绝对 URL
+ * @param options - 与对象脱敏一致的匹配规则和替换值
+ * @returns 可安全用于结构化日志的 URL
+ * @example
+ * ```ts
+ * import { core } from '@h-ai/core'
+ * const safe = core.sanitize.sanitizeUrl('https://service.example/path?token=example-only')
+ * ```
+ */
+declare function sanitizeUrl(url: string, options?: SanitizeSensitiveFieldsOptions): string;
+/**
+ * 递归脱敏单个值。
+ *
+ * @param value - 原始值
+ * @param key - 当前字段名；根节点传 null
+ * @param options - 脱敏选项
+ * @param cache - 循环引用 / 重复引用缓存
+ * @returns 脱敏数据副本；类实例不保留原型和方法，普通对象循环保留，Error 规范化为有界诊断树，原值不被修改。
+ * @example
+ * ```ts
+ * import { core } from '@h-ai/core'
+ * const safe = core.sanitize.sanitizeSensitiveValue('example-only', 'password')
+ * ```
+ */
+declare function sanitizeSensitiveValue(value: unknown, key: string | null, options?: SanitizeSensitiveFieldsOptions, cache?: WeakMap<object, unknown>): unknown;
+/**
+ * 对对象中的敏感字段执行递归脱敏，并自动处理 URL/endpoint 字段中的内嵌凭证。
+ * Error 保留 name/message/stack/cause、aggregate errors 与枚举上下文；错误子图循环和过深路径用固定标记，普通对象循环保留。
+ * 诊断文本不会自动解析自由文本中的秘密；记录前仍需调用方清理，或配置明确的 redact 路径。
+ *
+ * @param value - 原始对象/数组/值
+ * @param options - 脱敏选项
+ * 类实例只复制自有可枚举数据属性；不保留原型、访问器和 toJSON。Date 转 ISO 字符串，URL 转脱敏字符串。
+ * @returns 用于诊断的脱敏副本，不作为原类实例使用。
+ * @example
+ * ```ts
+ * import { core } from '@h-ai/core'
+ * const safe = core.sanitize.sanitizeSensitiveFields({ password: 'example-only', id: 'order-1' })
+ * ```
+ */
+declare function sanitizeSensitiveFields<T>(value: T, options?: SanitizeSensitiveFieldsOptions): T;
+/**
+ * 脱敏工具对象。
+ * @example
+ * ```ts
+ * import { core } from '@h-ai/core'
+ * const tools = core.sanitize
+ * tools.sanitizeSensitiveFields({ apiKey: 'example-only', id: 'order-1' })
+ * ```
+ */
+declare const sanitize: {
+    defaultSensitiveKeyRegex: RegExp;
+    defaultSensitiveReplacement: string;
+    isSensitiveKey: typeof isSensitiveKey;
+    sanitizeUrl: typeof sanitizeUrl;
+    sanitizeText: typeof sanitizeText;
+    sanitizeSensitiveValue: typeof sanitizeSensitiveValue;
+    sanitizeSensitiveFields: typeof sanitizeSensitiveFields;
+};
+
+/**
+ * @h-ai/core — 字符串操作工具
+ * @module core-util-string
+ */
+/**
+ * 首字母大写。
+ * @param str - 输入字符串
+ * @returns 首字母大写后的字符串
+ * @remarks 空字符串返回空字符串。
+ *
+ * @example
+ * ```ts
+ * string.capitalize('hello') // 'Hello'
+ * ```
+ */
+declare function capitalize(str: string): string;
+/**
+ * 转换为 kebab-case。
+ * @param str - 输入字符串
+ * @returns kebab-case 字符串
+ * @remarks 支持连续大写字母拆分（如 `getHTTPSUrl` → `get-https-url`）。
+ *
+ * @example
+ * ```ts
+ * string.kebabCase('helloWorld') // 'hello-world'
+ * string.kebabCase('getHTTPSUrl') // 'get-https-url'
+ * ```
+ */
+declare function kebabCase(str: string): string;
+/**
+ * 转换为 camelCase。
+ * @param str - 输入字符串
+ * @returns camelCase 字符串
+ * @remarks 仅处理包含 '-' 的字符串。
+ *
+ * @example
+ * ```ts
+ * string.camelCase('hello-world') // 'helloWorld'
+ * ```
+ */
+declare function camelCase(str: string): string;
+/**
+ * 截断字符串。
+ * @param str - 输入字符串
+ * @param length - 最大长度（小于等于 0 时返回原字符串）
+ * @param suffix - 超出长度时的后缀
+ * @returns 截断后的字符串
+ *
+ * @example
+ * ```ts
+ * string.truncate('hello world', 5) // 'hello...'
+ * ```
+ */
+declare function truncate(str: string, length: number, suffix?: string): string;
+/**
+ * 转换为 snake_case。
+ * @param str - 输入字符串
+ * @returns snake_case 字符串
+ * @remarks 支持连续大写字母拆分（如 `getHTTPSUrl` → `get_https_url`）。
+ *
+ * @example
+ * ```ts
+ * string.snakeCase('helloWorld') // 'hello_world'
+ * string.snakeCase('getHTTPSUrl') // 'get_https_url'
+ * ```
+ */
+declare function snakeCase(str: string): string;
+/**
+ * 转换为 PascalCase。
+ * @param str - 输入字符串
+ * @returns PascalCase 字符串
+ * @remarks 支持 '-' 与 '_' 分隔。
+ *
+ * @example
+ * ```ts
+ * string.pascalCase('hello-world') // 'HelloWorld'
+ * ```
+ */
+declare function pascalCase(str: string): string;
+/**
+ * 移除字符串两端的空白。
+ * @param str - 输入字符串
+ * @returns 去除两端空白后的字符串
+ *
+ * @example
+ * ```ts
+ * string.trim('  hi  ') // 'hi'
+ * ```
+ */
+declare function trim(str: string): string;
+/**
+ * 检查字符串是否为空或只包含空白。
+ * @param str - 输入字符串
+ * @returns 是否为空或全空白
+ *
+ * @example
+ * ```ts
+ * string.isBlank('   ') // true
+ * ```
+ */
+declare function isBlank(str: string): boolean;
+/**
+ * 检查字符串是否不为空。
+ * @param str - 输入字符串
+ * @returns 是否非空
+ *
+ * @example
+ * ```ts
+ * string.isNotBlank('ok') // true
+ * ```
+ */
+declare function isNotBlank(str: string): boolean;
+/**
+ * 填充字符串到指定长度（左侧）。
+ * @param str - 输入字符串
+ * @param length - 目标长度
+ * @param char - 填充字符
+ * @returns 填充后的字符串
+ *
+ * @example
+ * ```ts
+ * string.padStart('1', 3, '0') // '001'
+ * ```
+ */
+declare function padStart(str: string, length: number, char?: string): string;
+/**
+ * 填充字符串到指定长度（右侧）。
+ * @param str - 输入字符串
+ * @param length - 目标长度
+ * @param char - 填充字符
+ * @returns 填充后的字符串
+ *
+ * @example
+ * ```ts
+ * string.padEnd('1', 3, '0') // '100'
+ * ```
+ */
+declare function padEnd(str: string, length: number, char?: string): string;
+/**
+ * 无内容提前返回的字符串比较；Node 入口使用原生 timingSafeEqual 覆盖此实现。
+ *
+ * 浏览器 JavaScript 引擎不提供恒时保证，不能将此实现当作服务端凭证校验的安全边界。
+ *
+ * @param a - 字符串 a
+ * @param b - 字符串 b
+ * @returns 是否相等
+ *
+ * @example
+ * ```ts
+ * string.constantTimeEqual('abc', 'abc') // true
+ * string.constantTimeEqual('abc', 'abd') // false
+ * ```
+ */
+declare function constantTimeEqual(a: string, b: string): boolean;
+/**
+ * 字符串操作工具对象。
+ * @example
+ * ```ts
+ * import { core } from '@h-ai/core'
+ * const tools = core.string
+ * tools.camelCase('order-created')
+ * ```
+ */
+declare const string: {
+    capitalize: typeof capitalize;
+    kebabCase: typeof kebabCase;
+    camelCase: typeof camelCase;
+    truncate: typeof truncate;
+    snakeCase: typeof snakeCase;
+    pascalCase: typeof pascalCase;
+    trim: typeof trim;
+    isBlank: typeof isBlank;
+    isNotBlank: typeof isNotBlank;
+    padStart: typeof padStart;
+    padEnd: typeof padEnd;
+    constantTimeEqual: typeof constantTimeEqual;
+};
+
+/**
+ * @h-ai/core — 时间操作工具
+ * @module core-util-time
+ */
+/**
+ * 格式化日期。
+ * @param date - 日期对象
+ * @param format - 格式模板（默认 YYYY-MM-DD）
+ * @returns 格式化后的字符串
+ *
+ * @example
+ * ```ts
+ * time.formatDate(new Date(), 'YYYY-MM-DD')
+ * ```
+ */
+declare function formatDate(date: Date, format?: string): string;
+/**
+ * 相对时间描述。
+ * @param date - 目标日期
+ * @returns 相对时间文案
+ * @remarks 使用 i18n 消息返回结果。
+ *
+ * @example
+ * ```ts
+ * time.timeAgo(new Date(Date.now() - 60000))
+ * ```
+ */
+declare function timeAgo(date: Date): string;
+/**
+ * 获取当前时间戳（毫秒）。
+ * @returns 当前时间戳（毫秒）
+ *
+ * @example
+ * ```ts
+ * const ts = time.now()
+ * ```
+ */
+declare function now(): number;
+/**
+ * 获取当前时间戳（秒）。
+ * @returns 当前时间戳（秒）
+ *
+ * @example
+ * ```ts
+ * const ts = time.nowSeconds()
+ * ```
+ */
+declare function nowSeconds(): number;
+/**
+ * 解析日期字符串。
+ * @param dateStr - 日期字符串
+ * @returns Date 对象
+ * @remarks 无效字符串将生成 Invalid Date。
+ *
+ * @example
+ * ```ts
+ * const date = time.parseDate('2024-01-01')
+ * ```
+ */
+declare function parseDate(dateStr: string): Date;
+/**
+ * 判断是否为有效日期。
+ * @param date - Date 对象
+ * @returns 是否为有效日期
+ *
+ * @example
+ * ```ts
+ * time.isValidDate(new Date('invalid')) // false
+ * ```
+ */
+declare function isValidDate(date: Date): boolean;
+/**
+ * 添加天数。
+ * @param date - 原始日期
+ * @param days - 增加天数（可为负数）
+ * @returns 新的日期对象
+ *
+ * @example
+ * ```ts
+ * time.addDays(new Date(), 7)
+ * ```
+ */
+declare function addDays(date: Date, days: number): Date;
+/**
+ * 添加小时。
+ * @param date - 原始日期
+ * @param hours - 增加小时（可为负数）
+ * @returns 新的日期对象
+ *
+ * @example
+ * ```ts
+ * time.addHours(new Date(), 1)
+ * ```
+ */
+declare function addHours(date: Date, hours: number): Date;
+/**
+ * 获取日期的开始时间（00:00:00）。
+ * @param date - 目标日期
+ * @returns 当天开始时间
+ *
+ * @example
+ * ```ts
+ * time.startOfDay(new Date())
+ * ```
+ */
+declare function startOfDay(date: Date): Date;
+/**
+ * 获取日期的结束时间（23:59:59）。
+ * @param date - 目标日期
+ * @returns 当天结束时间
+ *
+ * @example
+ * ```ts
+ * time.endOfDay(new Date())
+ * ```
+ */
+declare function endOfDay(date: Date): Date;
+/**
+ * 时间操作工具对象。
+ * @example
+ * ```ts
+ * import { core } from '@h-ai/core'
+ * const tools = core.time
+ * tools.addDays(new Date('2026-01-01T00:00:00Z'), 1)
+ * ```
+ */
+declare const time: {
+    formatDate: typeof formatDate;
+    timeAgo: typeof timeAgo;
+    now: typeof now;
+    nowSeconds: typeof nowSeconds;
+    parseDate: typeof parseDate;
+    isValidDate: typeof isValidDate;
+    addDays: typeof addDays;
+    addHours: typeof addHours;
+    startOfDay: typeof startOfDay;
+    endOfDay: typeof endOfDay;
+};
+
+/**
+ * @h-ai/core — 类型检查工具
+ * @module core-util-type
+ */
+/**
+ * 检查值是否已定义（非 null 和 undefined）。
+ * @param value - 待检查值
+ * @returns 是否已定义
+ *
+ * @example
+ * ```ts
+ * typeUtils.isDefined(0) // true
+ * ```
+ */
+declare function isDefined<T>(value: T | undefined | null): value is T;
+/**
+ * 检查值是否为纯对象（排除数组）。
+ * @param value - 待检查值
+ * @returns 是否为纯对象
+ *
+ * @example
+ * ```ts
+ * typeUtils.isObject({}) // true
+ * ```
+ */
+declare function isObject(value: unknown): value is Record<string, unknown>;
+/**
+ * 检查值是否为函数。
+ * @param value - 待检查值
+ * @returns 是否为函数
+ *
+ * @example
+ * ```ts
+ * typeUtils.isFunction(() => {}) // true
+ * ```
+ */
+declare function isFunction(value: unknown): value is (...args: unknown[]) => unknown;
+/**
+ * 检查值是否为 Promise。
+ * @param value - 待检查值
+ * @returns 是否为 Promise
+ *
+ * @example
+ * ```ts
+ * typeUtils.isPromise(Promise.resolve()) // true
+ * ```
+ */
+declare function isPromise<T>(value: unknown): value is Promise<T>;
+/**
+ * 检查值是否为字符串。
+ * @param value - 待检查值
+ * @returns 是否为字符串
+ *
+ * @example
+ * ```ts
+ * typeUtils.isString('a') // true
+ * ```
+ */
+declare function isString(value: unknown): value is string;
+/**
+ * 检查值是否为数字。
+ * @param value - 待检查值
+ * @returns 是否为数字（排除 NaN）
+ *
+ * @example
+ * ```ts
+ * typeUtils.isNumber(1) // true
+ * ```
+ */
+declare function isNumber(value: unknown): value is number;
+/**
+ * 检查值是否为布尔值。
+ * @param value - 待检查值
+ * @returns 是否为布尔值
+ *
+ * @example
+ * ```ts
+ * typeUtils.isBoolean(false) // true
+ * ```
+ */
+declare function isBoolean(value: unknown): value is boolean;
+/**
+ * 检查值是否为数组。
+ * @param value - 待检查值
+ * @returns 是否为数组
+ *
+ * @example
+ * ```ts
+ * typeUtils.isArray([1, 2]) // true
+ * ```
+ */
+declare function isArray<T = unknown>(value: unknown): value is T[];
+/**
+ * 类型检查工具对象。
+ * @example
+ * ```ts
+ * import { core } from '@h-ai/core'
+ * const tools = core.typeUtils
+ * const value: unknown = 'order-1'
+ * if (tools.isString(value)) value.toUpperCase()
+ * ```
+ */
+declare const typeUtils: {
+    isDefined: typeof isDefined;
+    isObject: typeof isObject;
+    isFunction: typeof isFunction;
+    isPromise: typeof isPromise;
+    isString: typeof isString;
+    isNumber: typeof isNumber;
+    isBoolean: typeof isBoolean;
+    isArray: typeof isArray;
+};
+
+/**
+ * @h-ai/core — 错误注册与处理
+ *
+ * 提供统一的错误定义生成与实例化能力。
+ *
+ * @module core-function-error
+ */
+
+/**
+ * 错误提示末尾显示关联标识；重复格式化不会重复追加。
+ * @example
+ * ```ts
+ * import { core } from '@h-ai/core'
+ * const message = core.error.formatMessage({ message: '保存失败', traceId: 'request-1' })
+ * ```
+ */
+declare function formatMessage(error: Pick<HaiError, 'message' | 'traceId'>): string;
+/**
+ * HTTP/UI 边界仅公开安全消息和关联标识；内部异常及扩展信息留在脱敏日志。
+ * @example
+ * ```ts
+ * import { core } from '@h-ai/core'
+ * const safe = core.error.toPublic({ code: 'app:failed', message: 'Internal detail', httpStatus: 500 }, 'request-1')
+ * ```
+ */
+declare function toPublic(error: HaiError, traceId?: string, locale?: string): HaiError;
+/**
+ * 根据模块错误映射生成标准错误定义对象。
+ *
+ * 将错误信息映射（如 `{ CONFIG_NOT_FOUND: '010:500' }`）转换为结构化的 HaiErrorDef，
+ * 自动组装完整的错误码（格式：`system:module:code`）以及对应的 HTTP 状态码。
+ *
+ * @template T - 错误信息映射的类型
+ *
+ * @param module - 模块名称（如 'core'、'db'、'api'），会作为错误码的第二段
+ * @param errorInfo - 错误信息映射对象，值格式为 `'错误码数字:HTTP状态码'`（如 `'010:500'`）
+ * @param system - 系统标识，默认 'hai'，会作为错误码的第一段
+ *
+ * @returns 返回同类型的错误定义对象，每个 key 对应一个 HaiErrorDef 对象
+ *
+ * @example
+ * ```ts
+ * const ConfigErrorInfo = {
+ *   FILE_NOT_FOUND: '010:500',
+ *   PARSE_ERROR: '011:500',
+ *   VALIDATION_ERROR: '012:500',
+ * } as const
+ *
+ * const ConfigError = buildHaiErrorsDef('core', ConfigErrorInfo)
+ * // =>
+ * // ConfigError.FILE_NOT_FOUND = {
+ * //   code: 'hai:core:010',
+ * //   httpStatus: 500,
+ * //   system: 'hai',
+ * //   module: 'core',
+ * // }
+ * ```
+ */
+declare function buildHaiErrorsDef<T extends Record<string, string>>(module: string, errorInfo: T, system?: string): {
+    [K in keyof T]: HaiErrorDef;
+};
+/**
+ * 根据错误定义创建错误实例。
+ *
+ * 将 HaiErrorDef（错误定义）扩展为 HaiError（运行时错误实例），
+ * 添加具体的错误消息、原因和建议等运行时信息。
+ *
+ * @param def - 错误定义对象（通常由 buildHaiErrorsDef 生成）
+ * @param message - 错误消息（描述此次具体发生了什么）
+ * @param cause - 原始错误原因（可选，用于链式错误追踪）
+ * @param suggestion - 用户可采取的建议（可选，如 "'请检查配置文件格式'）
+ *
+ * @returns 返回完整的 HaiError 实例，包含错误码、HTTP 状态、消息、原因和建议
+ *
+ * @example
+ * ```ts
+ * const err = buildHaiErrorInst(
+ *   HaiConfigError.FILE_NOT_FOUND,
+ *   'config.yml 文件不存在',
+ *   new Error('ENOENT: no such file'),
+ *   '请确保 _core.yml 在项目根目录'
+ * )
+ * // => {
+ * //   code: 'hai:core:010',
+ * //   httpStatus: 500,
+ * //   system: 'hai',
+ * //   module: 'core',
+ * //   message: 'config.yml 文件不存在',
+ * //   cause: Error('ENOENT: no such file'),
+ * //   suggestion: '请确保 _core.yml 在项目根目录'
+ * // }
+ * ```
+ */
+declare function buildHaiErrorInst(def: HaiErrorDef, message: string, cause?: unknown, suggestion?: string): HaiError;
+/**
+ * 错误定义生成及错误实例组装工具；通过 core.error 使用。
+ * @example
+ * ```ts
+ * import { core } from '@h-ai/core'
+ * const tools = core.error
+ * tools.buildHaiErrorsDef('orders', { NOT_FOUND: '001:404' })
+ * ```
+ */
+declare const error: {
+    buildHaiErrorsDef: typeof buildHaiErrorsDef;
+    buildHaiErrorInst: typeof buildHaiErrorInst;
+    formatMessage: typeof formatMessage;
+    toPublic: typeof toPublic;
+};
+
+/**
+ * Zod 校验错误使用的稳定消息键。
+ * @example
+ * ```ts
+ * import type { ZodValidationMessageKey } from '@h-ai/core'
+ * const value: ZodValidationMessageKey = 'validationRequired'
+ * ```
+ */
+type ZodValidationMessageKey = 'validationFailed' | 'validationRequired' | 'validationInvalid' | 'validationInvalidType' | 'validationUnexpectedFields' | 'validationStringMin' | 'validationStringMax' | 'validationNumberMin' | 'validationNumberMax' | 'validationArrayMin' | 'validationArrayMax' | 'validationTooSmall' | 'validationTooBig' | 'validationEmail' | 'validationUrl' | 'validationUuid' | 'validationEnum';
+/**
+ * 把校验消息键及插值参数转换为显示文本的函数。
+ * @example
+ * ```ts
+ * import type { ZodMessageGetter } from '@h-ai/core'
+ * const message: ZodMessageGetter = (key, params) => key === 'validationRequired' ? 'Required' : `${key}: ${String(params?.field ?? '')}`
+ * message('validationRequired')
+ * ```
+ */
+type ZodMessageGetter = (key: ZodValidationMessageKey, params?: Record<string, string | number>) => string;
+/**
+ * 可绑定表单字段路径的本地化错误。
+ * @example
+ * ```ts
+ * import type { ValidationFormError } from '@h-ai/core'
+ * const value: ValidationFormError = { field: 'email', message: 'Enter an email address' }
+ * ```
+ */
+interface ValidationFormError {
+    field: string;
+    message: string;
+}
+/**
+ * 共享 Zod 错误映射契约；业务自定义消息保持原文。
+ * @example
+ * ```ts
+ * import { core, type ZodValidationFn } from '@h-ai/core'
+ * import { z } from 'zod'
+ * const validator: ZodValidationFn = core.zodValidation
+ * const input = z.object({ email: z.email() }).safeParse({ email: 'invalid' })
+ * if (!input.success) validator.mapZodErrorToFormErrors(input.error, key => key)
+ * ```
+ */
+interface ZodValidationFn {
+    readonly createPrefixedZodMessageGetter: <TMessageKey extends string>(prefix: string, getMessage: (messageKey: TMessageKey, params?: Record<string, string | number>) => string) => ZodMessageGetter;
+    readonly mapZodErrorToFormErrors: (error: unknown, getMessage: ZodMessageGetter) => ValidationFormError[];
+}
+/**
+ * 业务操作的成功数据或标准失败；访问 data/error 前必须按 success 收窄。
+ * @example
+ * ```ts
+ * import { ok, type HaiResult } from '@h-ai/core'
+ * const result: HaiResult<{ id: string }> = ok({ id: 'order-1' })
+ * const label = result.success ? result.data.id : result.error.message
+ * ```
+ */
+type HaiResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: HaiError;
+};
+/**
+ * 创建成功结果；不会自动捕获后续操作异常。
+ * @param data - 成功分支的数据；保留原类型和对象引用。
+ * @returns success 为 true、data 为输入值的结果。
+ * @example
+ * ```ts
+ * import { ok } from '@h-ai/core'
+ * const result = ok({ id: 'order-1' })
+ * if (result.success) result.data.id.toUpperCase()
+ * ```
+ */
+declare function ok<T>(data: T): HaiResult<T>;
+/**
+ * 创建失败结果；支持标准错误定义、已有 HaiError 与原生 Error。
+ * @param errorOrDef - 已定义的错误、已有业务错误或原生异常。
+ * @param message - 从错误定义创建实例时使用的消息。
+ * @param cause - 原始原因；对外展示前应按边界脱敏。
+ * @param suggestion - 可选的处理建议。
+ * @returns success 为 false、error 为标准业务错误的结果。
+ * @example
+ * ```ts
+ * import { err, HaiCommonError } from '@h-ai/core'
+ * const result = err(HaiCommonError.NOT_FOUND, 'Order not found')
+ * if (!result.success) result.error.httpStatus
+ * ```
+ */
+declare function err(errorOrDef: HaiErrorDef | HaiError | Error, message?: string, cause?: unknown, suggestion?: string): HaiResult<never>;
+/**
+ * HaiResult 模式匹配处理器。
+ *
+ * 提供对 HaiResult 的模式匹配能力，分别处理成功和失败两种情况。
+ *
+ * @template T - 成功数据类型
+ * @template R1 - ok 分支返回类型
+ * @template R2 - err 分支返回类型
+ * @example
+ * ```ts
+ * import { type MatchHandlers, ok } from '@h-ai/core'
+ * const handlers: MatchHandlers<number, string, string> = { ok: n => String(n + 1), err: error => error.message }
+ * const result = ok(2)
+ * const label = result.success ? handlers.ok(result.data) : handlers.err(result.error)
+ * ```
+ */
+interface MatchHandlers<T, R1, R2> {
+    /** 成功分支处理器 */
+    ok: (data: T) => R1;
+    /** 失败分支处理器 */
+    err: (error: HaiError) => R2;
+}
+/**
+ * 错误信息值格式：`错误码数字段:HTTP状态码`，例如 `001:500`。
+ * @example
+ * ```ts
+ * import type { ErrorInfoValue } from '@h-ai/core'
+ * const value: ErrorInfoValue = '001:500'
+ * ```
+ */
+type ErrorInfoValue = `${string}:${string}`;
+/**
+ * 模块错误信息映射。
+ * @example
+ * ```ts
+ * import type { ErrorInfo } from '@h-ai/core'
+ * const value: ErrorInfo = { NOT_READY: '001:503' }
+ * ```
+ */
+type ErrorInfo = Record<string, ErrorInfoValue>;
+/**
+ * 稳定的错误码与 HTTP 映射；消息在创建错误实例时填入。
+ * @example
+ * ```ts
+ * import type { HaiErrorDef } from '@h-ai/core'
+ * const value: HaiErrorDef = { code: 'app:orders:001', httpStatus: 409, system: 'app', module: 'orders' }
+ * ```
+ */
+interface HaiErrorDef {
+    code: string | number;
+    httpStatus: number;
+    system: string;
+    module: string;
+}
+/**
+ * 可跨业务边界传递的错误；cause/ext 对外展示前仍需脱敏。
+ * @example
+ * ```ts
+ * import type { HaiError } from '@h-ai/core'
+ * const value: HaiError = { code: 'app:orders:001', message: 'Order already exists', httpStatus: 409 }
+ * ```
+ */
+interface HaiError {
+    code: string | number;
+    message: string;
+    /** 用户提示与前后端诊断共用的关联标识。 */
+    traceId?: string;
+    httpStatus?: number;
+    system?: string;
+    module?: string;
+    cause?: unknown;
+    suggestion?: string;
+    ext?: Record<string, unknown>;
+    /** 由服务端明确批准公开的业务进度；边界转换为 ext，内部 ext 默认不公开。 */
+    publicExt?: Record<string, unknown>;
+}
+/**
+ * 跨模块通用错误定义及 HTTP 状态映射。
+ * @example
+ * ```ts
+ * import { err, HaiCommonError } from '@h-ai/core'
+ * const result = err(HaiCommonError.UNAUTHORIZED, 'Authentication required')
+ * if (!result.success) result.error.code
+ * ```
+ */
+declare const HaiCommonError: {
+    readonly NOT_INITIALIZED: HaiErrorDef;
+    readonly INIT_FAILED: HaiErrorDef;
+    readonly INIT_IN_PROGRESS: HaiErrorDef;
+    readonly UNAUTHORIZED: HaiErrorDef;
+    readonly FORBIDDEN: HaiErrorDef;
+    readonly TOKEN_EXPIRED: HaiErrorDef;
+    readonly TOKEN_INVALID: HaiErrorDef;
+    readonly REQUEST_ACCESS_DENIED: HaiErrorDef;
+    readonly VALIDATION_ERROR: HaiErrorDef;
+    readonly INVALID_REQUEST: HaiErrorDef;
+    readonly PARAMETER_MISSING: HaiErrorDef;
+    readonly NOT_FOUND: HaiErrorDef;
+    readonly ALREADY_EXISTS: HaiErrorDef;
+    readonly CONFLICT: HaiErrorDef;
+    readonly API_ERROR: HaiErrorDef;
+    readonly NETWORK_ERROR: HaiErrorDef;
+    readonly TIMEOUT: HaiErrorDef;
+    readonly SERVICE_UNAVAILABLE: HaiErrorDef;
+    readonly INTERNAL_ERROR: HaiErrorDef;
+    readonly DATABASE_ERROR: HaiErrorDef;
+    readonly UNKNOWN_ERROR: HaiErrorDef;
+};
+/**
+ * 文件配置加载、校验、环境缺失及缓存读取的错误定义。
+ * @example
+ * ```ts
+ * import { err, HaiConfigError } from '@h-ai/core'
+ * const result = err(HaiConfigError.CONFIG_NOT_LOADED, 'App configuration is unavailable')
+ * if (!result.success) result.error.message
+ * ```
+ */
+declare const HaiConfigError: {
+    readonly CONFIG_FILE_NOT_FOUND: HaiErrorDef;
+    readonly CONFIG_PARSE_ERROR: HaiErrorDef;
+    readonly CONFIG_VALIDATION_ERROR: HaiErrorDef;
+    readonly CONFIG_ENV_VAR_MISSING: HaiErrorDef;
+    readonly CONFIG_NOT_LOADED: HaiErrorDef;
+};
+/**
+ * 分页参数输入（可选字段，未提供时使用默认值）。
+ * @example
+ * ```ts
+ * import type { PaginationOptionsInput } from '@h-ai/core'
+ * const value: PaginationOptionsInput = { page: 2, pageSize: 20 }
+ * ```
+ */
+interface PaginationOptionsInput {
+    /** 页码（从 1 开始，默认 1） */
+    page?: number;
+    /** 每页数量（默认由业务层决定） */
+    pageSize?: number;
+}
+/**
+ * 分页参数（必填，已确定具体值）。
+ * @example
+ * ```ts
+ * import type { PaginationOptions } from '@h-ai/core'
+ * const value: PaginationOptions = { page: 1, pageSize: 20 }
+ * ```
+ */
+interface PaginationOptions {
+    /** 页码（从 1 开始） */
+    page: number;
+    /** 每页数量 */
+    pageSize: number;
+}
+/**
+ * 分页结果。
+ *
+ * @template T - 数据项类型
+ * @example
+ * ```ts
+ * import type { PaginatedResult } from '@h-ai/core'
+ * const page: PaginatedResult<{ id: string }> = { items: [{ id: 'order-1' }], total: 1, page: 1, pageSize: 20 }
+ * const ids = page.items.map(item => item.id)
+ * ```
+ */
+interface PaginatedResult<T> {
+    /** 当前页数据 */
+    items: T[];
+    /** 总数量 */
+    total: number;
+    /** 页码（从 1 开始） */
+    page: number;
+    /** 每页数量 */
+    pageSize: number;
+}
+/**
+ * 日志上下文。
+ * @example
+ * ```ts
+ * import type { LogContext } from '@h-ai/core'
+ * const value: LogContext = { requestId: 'request-1', level: 'info' }
+ * ```
+ */
+interface LogContext {
+    timestamp?: Date;
+    level?: LogLevel;
+    message?: string;
+    [key: string]: unknown;
+}
+/**
+ * 可信关联范围，不包含访问令牌。Node 异步请求/任务隔离，浏览器仅同步作用域。
+ * @example
+ * ```ts
+ * import type { RequestContext } from '@h-ai/core'
+ * const context: RequestContext = { requestId: 'request-1', scopeId: 'tenant-1', userId: 'user-1' }
+ * ```
+ */
+interface RequestContext {
+    readonly requestId?: string;
+    readonly traceId?: string;
+    readonly scopeId?: string;
+    readonly userId?: string;
+    readonly jobId?: string;
+    /** 内部采集/存储路径可暂停观察回调，常规日志输出仍执行。 */
+    readonly suppressLogObservers?: boolean;
+}
+/**
+ * 经过当前级别和脱敏策略的日志，不代表日志已持久化。
+ * @example
+ * ```ts
+ * import type { LogRecord } from '@h-ai/core'
+ * const record: LogRecord = { timestamp: 1, level: 'error', message: 'Request failed', context: { requestId: 'request-1' } }
+ * ```
+ */
+interface LogRecord {
+    readonly timestamp: number;
+    readonly level: LogLevel;
+    readonly message: string;
+    readonly context: Readonly<LogContext>;
+}
+/**
+ * 同步日志观察者；只做有界内存收集，I/O 由消费者异步处理。
+ * @example
+ * ```ts
+ * import { core, type LogObserver } from '@h-ai/core'
+ * const observer: LogObserver = record => { const requestId = record.context.requestId }
+ * const unsubscribe = core.logger.observe(observer)
+ * unsubscribe()
+ * ```
+ */
+type LogObserver = (record: LogRecord) => void;
+/**
+ * 日志选项。
+ * @example
+ * ```ts
+ * import type { LoggerOptions } from '@h-ai/core'
+ * const value: LoggerOptions = { name: 'orders', level: 'debug', context: { service: 'api' } }
+ * ```
+ */
+interface LoggerOptions {
+    name?: string;
+    /** 显式级别保持不变；未指定时动态继承全局配置。 */
+    level?: LogLevel;
+    /** 显式格式保持不变；未指定时动态继承全局配置。 */
+    format?: LogFormat;
+    /** 固定上下文覆盖当前全局上下文，调用时上下文可进一步覆盖。 */
+    context?: Record<string, unknown>;
+}
+/**
+ * Logger 接口。
+ * 统一的日志记录接口，具体实现由 Provider 提供。
+ * @example
+ * ```ts
+ * import { core, type Logger } from '@h-ai/core'
+ * const logger: Logger = core.logger.child({ service: 'orders' })
+ * logger.info('Order created', { orderId: 'order-1' })
+ * ```
+ */
+interface Logger {
+    trace: (message: string, context?: LogContext) => void;
+    debug: (message: string, context?: LogContext) => void;
+    info: (message: string, context?: LogContext) => void;
+    warn: (message: string, context?: LogContext) => void;
+    error: (message: string, context?: LogContext) => void;
+    fatal: (message: string, context?: LogContext) => void;
+    child: (context: Record<string, unknown>) => Logger;
+}
+/**
+ * Core 公共 Logger — Logger 实例 + 管理方法。
+ * @example
+ * ```ts
+ * import { core, type CoreLogger } from '@h-ai/core'
+ * const logger: CoreLogger = core.logger
+ * logger.configure({ level: 'warn', redact: ['password'] })
+ * logger.child({ component: 'worker' }).warn('Retry scheduled')
+ * ```
+ */
+interface CoreLogger extends Logger {
+    /**
+     * 观察通过日志级别与脱敏策略的记录，返回取消函数；异常与同步重入被隔离。
+     * @example
+     * ```ts
+     * import { core } from '@h-ai/core'
+     * const records: string[] = []
+     * const unsubscribe = core.logger.observe(record => { records.push(record.message) })
+     * core.logger.info('Application ready')
+     * unsubscribe()
+     * ```
+     */
+    observe: (observer: LogObserver) => () => void;
+    /** 创建新的 Logger 实例 */
+    create: (options?: LoggerOptions) => Logger;
+    /** 配置全局 Logger 选项，后续输出同时应用到已有默认、模块与 child Logger。 */
+    configure: (config: Partial<LoggingConfig>) => void;
+    /** 设置全局日志级别 */
+    setLevel: (level: LogLevel) => void;
+    /** 获取当前全局日志级别 */
+    getLevel: () => LogLevel;
+}
+/**
+ * Logger 函数组合（平台实现依赖）。
+ *
+ * 由各平台（Node.js / Browser）提供具体实现，通过 `createCore()` 注入。
+ * @example
+ * ```ts
+ * import { core, type LoggerFunctions } from '@h-ai/core'
+ * const platform: LoggerFunctions = { createLogger: options => core.logger.create(options), getLogger: name => core.logger.create({ name }), configureLogger: config => core.logger.configure(config), setLogLevel: level => core.logger.setLevel(level), getLogLevel: () => core.logger.getLevel() }
+ * platform.createLogger({ name: 'worker' }).info('Worker ready')
+ * ```
+ */
+interface LoggerFunctions {
+    /** 创建新的 Logger 实例 */
+    createLogger: (options?: LoggerOptions) => Logger;
+    /** 获取默认或命名 Logger 实例（单例） */
+    getLogger: (name?: string) => Logger;
+    /** 配置全局 Logger 选项（级别、格式、上下文等） */
+    configureLogger: (config: Partial<LoggingConfig>) => void;
+    /** 设置全局日志级别 */
+    setLogLevel: (level: LogLevel) => void;
+    /** 获取当前全局日志级别 */
+    getLogLevel: () => LogLevel;
+}
+/**
+ * Core 配置选项。
+ * @example
+ * ```ts
+ * import type { CoreOptions } from '@h-ai/core'
+ * const value: CoreOptions = { configDir: './config', watchConfig: false }
+ * ```
+ */
+interface CoreOptions {
+    /** 日志配置 */
+    logging?: Partial<LoggingConfig>;
+    /**
+     * 配置目录（约定优于配置模式）
+     *
+     * 指定后会自动扫描目录中的 yml/yaml 文件：
+     * - `_core.yml` → 自动使用 CoreConfigSchema 校验
+     * - `_xx.yml` → 加载为 'xx'（各模块自行调用 `config.validate` 校验）
+     * - `app.yml` → 加载为 'app'（需使用方自行校验）
+     * 项目构建和部署配置位于根目录 hai.json，不参与运行时 YAML 扫描。
+     *
+     * 单项加载返回失败时记日志并继续；必需配置须检查 `config.validate` 的 success。
+     * 目录扫描等文件系统异常仍可能向调用方传播。
+     *
+     * @example
+     * ```ts
+     * core.init({ configDir: './config' })
+     * ```
+     */
+    configDir?: string;
+    /** 宿主显式提供模块 Schema，供扫描时识别可选字段和环境变量类型；Core 不注册业务模块。 */
+    configSchemas?: Readonly<Record<string, z.ZodType>>;
+    /** 是否启用配置文件监听（默认 false） */
+    watchConfig?: boolean;
+}
+/**
+ * 语言代码（ISO 639-1 + 地区代码）。
+ * @example
+ * ```ts
+ * import type { Locale } from '@h-ai/core'
+ * const value: Locale = 'en-US'
+ * ```
+ */
+type Locale = string;
+/**
+ * 语言信息。
+ * @example
+ * ```ts
+ * import type { LocaleInfo } from '@h-ai/core'
+ * const value: LocaleInfo = { code: 'en-US', label: 'English' }
+ * ```
+ */
+interface LocaleInfo {
+    /** 语言代码（如 'zh-CN'、'en-US'） */
+    code: Locale;
+    /** 显示名称（如 '简体中文'、'English'） */
+    label: string;
+    /** 是否为从右到左书写的语言（如阿拉伯语），默认 false */
+    rtl?: boolean;
+}
+/**
+ * 插值参数类型。
+ *
+ * 用于 i18n 消息模板中的 `{key}` 占位符替换。
+ * @example
+ * ```ts
+ * import type { InterpolationParams } from '@h-ai/core'
+ * const value: InterpolationParams = { name: 'Alice', count: 2 }
+ * ```
+ */
+type InterpolationParams = Record<string, string | number | boolean>;
+/**
+ * 消息字典类型（单语言的 key-value 映射）。
+ * @example
+ * ```ts
+ * import type { MessageDictionary } from '@h-ai/core'
+ * const value: MessageDictionary = { greeting: 'Hello, {name}!' }
+ * ```
+ */
+type MessageDictionary = Record<string, string>;
+/**
+ * 多语言消息集合。
+ *
+ * 以 locale 为键，每个 locale 下包含该语言的所有消息 key-value。
+ *
+ * @template K - 消息 key 的联合类型
+ * @example
+ * ```ts
+ * import { core, type LocaleMessages } from '@h-ai/core'
+ * const messages: LocaleMessages<'hello'> = { 'en-US': { hello: 'Hello, {name}!' }, 'zh-CN': { hello: '你好，{name}！' } }
+ * const message = core.i18n.createMessageGetter(messages)
+ * message('hello', { locale: 'en-US', params: { name: 'Alice' } })
+ * ```
+ */
+type LocaleMessages<K extends string = string> = Record<Locale, Record<K, string>>;
+/**
+ * 消息获取选项。
+ * @example
+ * ```ts
+ * import type { MessageOptions } from '@h-ai/core'
+ * const value: MessageOptions = { locale: 'en-US', params: { name: 'Alice' } }
+ * ```
+ */
+interface MessageOptions {
+    /** 指定 locale（不传时依次读取 Node 请求上下文、应用默认语言） */
+    locale?: Locale;
+    /** 插值参数 */
+    params?: InterpolationParams;
+}
+/**
+ * Core 服务聚合接口（createCore 返回类型）
+ * @example
+ * ```ts
+ * import { core, type CoreFunctions } from '@h-ai/core'
+ * function createRequestId(tools: CoreFunctions): string { return tools.id.request() }
+ * const requestId = createRequestId(core)
+ * ```
+ */
+interface CoreFunctions {
+    /**
+     * Node 中跨 await 隔离请求关联，浏览器仅同步作用域；不向下游注入任何凭据。
+     * @example
+     * ```ts
+     * import { core } from '@h-ai/core'
+     * await core.context.run({ requestId: 'request-1' }, async () => {
+     *   await Promise.resolve()
+     *   core.logger.info('Work completed')
+     * })
+     * const outside = core.context.get()
+     * ```
+     */
+    readonly context: {
+        readonly get: () => Readonly<RequestContext>;
+        readonly run: <T>(context: RequestContext, operation: () => T) => T;
+    };
+    /** 默认 Logger（懒加载单例），同时提供日志管理方法 */
+    readonly logger: CoreLogger;
+    /** 国际化工具 */
+    readonly i18n: I18nFn;
+    /** Zod 校验错误 → i18n 消息映射工具（kit / serv / api-client 共享） */
+    readonly zodValidation: typeof zodValidation;
+    /** ID 生成工具 */
+    readonly id: IdFn;
+    /** 类型检查工具 */
+    readonly typeUtils: TypeUtilFn;
+    /** 对象操作工具 */
+    readonly object: ObjectFn;
+    /** 脱敏工具 */
+    readonly sanitize: SanitizeFn;
+    /** 字符串操作工具 */
+    readonly string: StringFn;
+    /** 数组操作工具 */
+    readonly array: ArrayFn;
+    /** 异步操作工具 */
+    readonly async: AsyncFn;
+    /** 时间操作工具 */
+    readonly time: TimeFn;
+    /** 错误工具 */
+    readonly error: ErrorFn;
+    /** 模块基础工具 */
+    readonly module: ModuleFn;
+}
+/**
+ * Node 专属访问工具，通过 core.access 调用；浏览器不提供该能力。
+ * @example
+ * ```ts
+ * import { core, type AccessFunctions } from '@h-ai/core'
+ * const tools: AccessFunctions = core.access
+ * const check = tools.createRequestCheck(false)
+ * const decision = check('/api/v1/sync', 'POST', '192.0.2.10')
+ * ```
+ */
+interface AccessFunctions {
+    /** 规范化可信宿主地址；非法 IP 返回 undefined。 */
+    normalizeClientIp: (value?: string) => string | undefined;
+    /** 启动编译可信代理；第二参数必须来自 socket 或受信平台。auto 只在受管私有代理部署生效。 */
+    createClientIpResolver: (trustedProxies?: TrustedProxies | readonly string[]) => (request: Request, remoteAddress?: string) => string | undefined;
+    /** 编译共享的 IP/时间条件，供登录许可和其他可信服务端流程使用。 */
+    createConditionCheck: (condition: AccessCondition) => (ip?: string) => AccessDecision;
+    /** 启动读取和编译请求策略；检查期间无文件 I/O、CIDR 解析或全规则扫描。 */
+    createRequestCheck: (input?: RequestAccessConfigInput) => RequestAccessCheck;
+    /** 启动读取最大 1 MiB 的 YAML；相对路径按服务工作目录或显式目录解析，配置失败抛出安全错误。 */
+    loadPolicy: (input?: RequestAccessConfigInput, baseDirectory?: string) => RequestAccessPolicy | false;
+}
+/**
+ * Node 入口的完整 Core 形态；访问检查和文件配置不属于浏览器运行时。
+ * @example
+ * ```ts
+ * import { core, type NodeCoreFunctions } from '@h-ai/core'
+ * const tools: NodeCoreFunctions = core
+ * tools.init({ logging: { level: 'info' } })
+ * ```
+ */
+interface NodeCoreFunctions extends CoreFunctions {
+    readonly access: AccessFunctions;
+    readonly config: ConfigFn;
+    readonly init: (options?: CoreOptions) => void;
+}
+/**
+ * 浏览器 Core 形态；文件配置方法明确返回不可用，不包含 Node 的 access 能力。
+ * @example
+ * ```ts
+ * import type { BrowserCoreFunctions } from '@h-ai/core'
+ * function nextId(tools: BrowserCoreFunctions) { return tools.id.request() }
+ * ```
+ */
+interface BrowserCoreFunctions extends CoreFunctions {
+    readonly config: BrowserConfigFn;
+    readonly init: (options?: CoreOptions) => void;
+}
+/**
+ * 运行环境标识；不会自行设置进程环境或初始化模块。
+ * @example
+ * ```ts
+ * import type { Env } from '@h-ai/core'
+ * const value: Env = 'production'
+ * ```
+ */
+type Env = z.infer<typeof EnvSchema>;
+/**
+ * 日志输出级别；未显式配置的 Logger 动态继承全局级别。
+ * @example
+ * ```ts
+ * import type { LogLevel } from '@h-ai/core'
+ * const value: LogLevel = 'warn'
+ * ```
+ */
+type LogLevel = z.infer<typeof LogLevelSchema>;
+/**
+ * 日志输出格式：JSON 或适合终端阅读的 pretty。
+ * @example
+ * ```ts
+ * import type { LogFormat } from '@h-ai/core'
+ * const value: LogFormat = 'json'
+ * ```
+ */
+type LogFormat = z.infer<typeof LogFormatSchema>;
+/**
+ * 经过默认值填充的 Logger 配置；redact 是输出脱敏路径。
+ * @example
+ * ```ts
+ * import { LoggingConfigSchema, type LoggingConfig } from '@h-ai/core'
+ * const config: LoggingConfig = LoggingConfigSchema.parse({})
+ * ```
+ */
+type LoggingConfig = z.infer<typeof LoggingConfigSchema>;
+/**
+ * 严格校验后的 Core 配置；业务配置使用独立 Schema。
+ * @example
+ * ```ts
+ * import { CoreConfigSchema, type CoreConfig } from '@h-ai/core'
+ * const config: CoreConfig = CoreConfigSchema.parse({})
+ * ```
+ */
+type CoreConfig = z.infer<typeof CoreConfigSchema>;
+/**
+ * 可信代理配置；空数组显式忽略全部转发头。
+ * @example
+ * ```ts
+ * import type { TrustedProxies } from '@h-ai/core'
+ * const proxies: TrustedProxies = []
+ * ```
+ */
+type TrustedProxies = z.infer<typeof TrustedProxiesSchema>;
+/**
+ * 已补齐默认值的 IP/时间条件。
+ * @example
+ * ```ts
+ * import { AccessConditionSchema, type AccessCondition } from '@h-ai/core'
+ * const condition: AccessCondition = AccessConditionSchema.parse({})
+ * ```
+ */
+type AccessCondition = z.infer<typeof AccessConditionSchema>;
+/**
+ * 已验证的请求策略。
+ * @example
+ * ```ts
+ * import { RequestAccessPolicySchema, type RequestAccessPolicy } from '@h-ai/core'
+ * const policy: RequestAccessPolicy = RequestAccessPolicySchema.parse({ rules: [] })
+ * ```
+ */
+type RequestAccessPolicy = z.infer<typeof RequestAccessPolicySchema>;
+/**
+ * 请求访问策略的输入；默认关闭由宿主配置决定。
+ * @example
+ * ```ts
+ * import type { RequestAccessConfigInput } from '@h-ai/core'
+ * const input: RequestAccessConfigInput = { rules: [{ id: 'external', paths: ['/api/v1/external/**'], allowIps: ['192.0.2.10'] }] }
+ * ```
+ */
+type RequestAccessConfigInput = z.input<typeof RequestAccessConfigSchema>;
+/**
+ * 路径的应用层加解密要求；不改变 TLS、身份鉴别或访问条件。
+ * @example
+ * ```ts
+ * import type { RequestEncryptionMode } from '@h-ai/core'
+ * const mode: RequestEncryptionMode = 'disabled'
+ * ```
+ */
+type RequestEncryptionMode = NonNullable<RequestAccessPolicy['rules'][number]['encryption']>;
+/**
+ * 启动编译后的请求检查器；加密选择只查路径索引，不重新计算 IP 或时间条件。
+ * @example
+ * ```ts
+ * import { core, type RequestAccessCheck } from '@h-ai/core'
+ * const check: RequestAccessCheck = core.access.createRequestCheck({ rules: [{ id: 'partner', paths: ['/api/v1/partner/**'], encryption: 'disabled' }] })
+ * const mode = check.encryption('/api/v1/partner/sync', 'POST')
+ * const decision = check('/api/v1/partner/sync', 'POST', '192.0.2.10')
+ * ```
+ */
+interface RequestAccessCheck {
+    (pathname: string, method: string, ip?: string): AccessDecision;
+    /** 是否存在强制加密的规则；宿主未装配加密时必须拒绝启动。 */
+    readonly requiresEncryption: boolean;
+    /** 选取路径及方法对应的模式；undefined 表示沿用宿主；无请求期 I/O 或全规则扫描。 */
+    readonly encryption: (pathname: string, method: string) => RequestEncryptionMode | undefined;
+}
+/**
+ * 安全判断只携带原因类别及规则编号，不向调用方复制策略内容。
+ * @example
+ * ```ts
+ * import type { AccessDecision } from '@h-ai/core'
+ * const decision: AccessDecision = { allowed: false, reason: 'address', ruleId: 'external' }
+ * ```
+ */
+type AccessDecision = Readonly<{
+    allowed: true;
+} | {
+    allowed: false;
+    reason: 'address' | 'time' | 'path';
+    ruleId?: string;
+}>;
+/**
+ * id 子工具类型
+ * @example
+ * ```ts
+ * import { core, type IdFn } from '@h-ai/core'
+ * const tools: IdFn = core.id
+ * tools.withPrefix('order_')
+ * ```
+ */
+type IdFn = typeof id;
+/**
+ * error 子工具类型
+ * @example 模块内部上下文
+ * ```ts
+ * const tools: ErrorFn = error
+ * tools.buildHaiErrorsDef('orders', { NOT_FOUND: '001:404' })
+ * ```
+ */
+type ErrorFn = typeof error;
+/**
+ * 监听回调类型。
+ *
+ * @template T - 配置数据类型
+ * @example 模块内部上下文
+ * ```ts
+ * const callback: WatchCallback<{ enabled: boolean }> = (config, failure) => {
+ *   if (failure) { messages.push(failure.message); return }
+ *   if (config) messages.push(String(config.enabled))
+ * }
+ * const messages: string[] = []
+ * ```
+ */
+type WatchCallback<T = unknown> = (config: T | null, error?: HaiError) => void;
+/**
+ * config 子工具类型
+ * @example
+ * ```ts
+ * import { core, type ConfigFn } from '@h-ai/core'
+ * const result = core.config.load('app', '/srv/app/config/app.yml')
+ * if (!result.success) result.error.message
+ * ```
+ */
+type ConfigFn = typeof config;
+/**
+ * config 子工具类型
+ * @example
+ * ```ts
+ * import { core, type BrowserConfigFn } from '@h-ai/core'
+ * const result = core.config.load('app', '/srv/app/config/app.yml')
+ * if (!result.success) result.error.message
+ * ```
+ */
+type BrowserConfigFn = typeof config$1;
+/**
+ * i18n 子工具类型
+ * @example
+ * ```ts
+ * import { core, type I18nFn } from '@h-ai/core'
+ * const tools: I18nFn = core.i18n
+ * const message = tools.createMessageGetter({ 'en-US': { hello: 'Hello' }, 'zh-CN': { hello: '你好' } })
+ * message('hello', { locale: 'en-US' })
+ * ```
+ */
+type I18nFn = typeof i18n;
+/**
+ * array 子工具类型
+ * @example
+ * ```ts
+ * import { core, type ArrayFn } from '@h-ai/core'
+ * const tools: ArrayFn = core.array
+ * tools.chunk([1, 2, 3], 2)
+ * ```
+ */
+type ArrayFn = typeof array;
+/**
+ * async 子工具类型
+ * @example
+ * ```ts
+ * import { core, type AsyncFn } from '@h-ai/core'
+ * const tools: AsyncFn = core.async
+ * await tools.retry(async () => 'ready', { maxRetries: 2 })
+ * ```
+ */
+type AsyncFn = typeof async;
+/**
+ * object 子工具类型
+ * @example
+ * ```ts
+ * import { core, type ObjectFn } from '@h-ai/core'
+ * const tools: ObjectFn = core.object
+ * tools.pick({ id: 'order-1', password: 'example-only' }, ['id'])
+ * ```
+ */
+type ObjectFn = typeof object;
+/**
+ * string 子工具类型
+ * @example
+ * ```ts
+ * import { core, type StringFn } from '@h-ai/core'
+ * const tools: StringFn = core.string
+ * tools.camelCase('order-created')
+ * ```
+ */
+type StringFn = typeof string;
+/**
+ * time 子工具类型
+ * @example
+ * ```ts
+ * import { core, type TimeFn } from '@h-ai/core'
+ * const tools: TimeFn = core.time
+ * tools.addDays(new Date('2026-01-01T00:00:00Z'), 1)
+ * ```
+ */
+type TimeFn = typeof time;
+/**
+ * typeUtils 子工具类型
+ * @example
+ * ```ts
+ * import { core, type TypeUtilFn } from '@h-ai/core'
+ * const tools: TypeUtilFn = core.typeUtils
+ * const value: unknown = 'order-1'
+ * if (tools.isString(value)) value.toUpperCase()
+ * ```
+ */
+type TypeUtilFn = typeof typeUtils;
+/**
+ * 未初始化工具集返回类型。
+ *
+ * 提供错误创建、HaiResult 包装和 Proxy 代理等能力，
+ * 用于模块未初始化时的安全回退。
+ *
+ * @template E - 模块错误类型（必须继承 HaiError）
+ * @example
+ * ```ts
+ * import { core, type HaiError, type NotInitializedKit } from '@h-ai/core'
+ * const state: NotInitializedKit<HaiError> = core.module.createNotInitializedKit({ code: 'app:orders:001', httpStatus: 503, system: 'app', module: 'orders' }, () => 'Orders unavailable')
+ * const result = state.result<string>()
+ * if (!result.success) result.error.message
+ * ```
+ */
+interface NotInitializedKit<E extends HaiError> {
+    /** 创建未初始化错误对象 */
+    error: () => E;
+    /** 创建包含未初始化错误的失败 HaiResult */
+    result: <T>() => HaiResult<T>;
+    /**
+     * 创建 Proxy 代理，拦截所有方法调用并返回未初始化错误。
+     *
+     * @param mode - 'async'（默认）所有方法返回 `Promise<HaiResult>`；'sync' 所有方法返回 `HaiResult`
+     */
+    proxy: <T>(mode?: 'async' | 'sync') => T;
+}
+/** module 子工具类型 */
+/**
+ * 未初始化代理的两个重载：错误定义或具体错误码。
+ * @example
+ * ```ts
+ * import { core, type CreateNotInitializedKitFn } from '@h-ai/core'
+ * const create: CreateNotInitializedKitFn = core.module.createNotInitializedKit
+ * const state = create({ code: 'app:orders:001', httpStatus: 503, system: 'app', module: 'orders' }, () => 'Orders unavailable')
+ * const result = state.result<string>()
+ * if (!result.success) result.error.code
+ * ```
+ */
+interface CreateNotInitializedKitFn {
+    (codeOrDef: HaiErrorDef, messageFn: () => string): NotInitializedKit<HaiError>;
+    <E extends HaiError>(codeOrDef: E['code'], messageFn: () => string): NotInitializedKit<E>;
+}
+/**
+ * 模块初始化占位与生产共享状态要求的工具契约。
+ * @example 模块内部上下文
+ * ```ts
+ * function createHostRuntime(tools: ModuleFn) { return tools.createRuntime([]) }
+ * ```
+ */
+interface ModuleFn {
+    /** 顺序启动和反序关闭真实模块；不持有业务配置。 */
+    createRuntime: typeof createRuntime;
+    createNotInitializedKit: CreateNotInitializedKitFn;
+    /** 生产共享状态要求；浏览器工具为纯函数，不隐式读取进程环境。 */
+    requiresSharedState: typeof requiresSharedState;
+}
+/**
+ * 敏感字段匹配器
+ * @example
+ * ```ts
+ * import { core, type SensitiveKeyMatcher } from '@h-ai/core'
+ * const matcher: SensitiveKeyMatcher = ['password', 'credential']
+ * const safe = core.sanitize.sanitizeSensitiveFields({ credential: 'example-only', id: 'order-1' }, { matcher })
+ * ```
+ */
+type SensitiveKeyMatcher = RegExp | string[] | ((key: string) => boolean);
+/**
+ * 敏感字段脱敏选项
+ * @example
+ * ```ts
+ * import { core, type SanitizeSensitiveFieldsOptions } from '@h-ai/core'
+ * const options: SanitizeSensitiveFieldsOptions = { matcher: ['credential'], replacement: '[HIDDEN]' }
+ * const safe = core.sanitize.sanitizeSensitiveFields({ credential: 'example-only' }, options)
+ * ```
+ */
+interface SanitizeSensitiveFieldsOptions {
+    /** 自定义敏感字段匹配规则 */
+    matcher?: SensitiveKeyMatcher;
+    /** 自定义脱敏替换值 */
+    replacement?: unknown;
+}
+/**
+ * sanitize 子工具类型
+ * @example
+ * ```ts
+ * import { core, type SanitizeFn } from '@h-ai/core'
+ * const tools: SanitizeFn = core.sanitize
+ * tools.sanitizeSensitiveFields({ apiKey: 'example-only', id: 'order-1' })
+ * ```
+ */
+type SanitizeFn = typeof sanitize;
+/**
+ * 单个真实模块或业务钩子的资源所有权；close 应可重试。
+ * @example 模块内部上下文
+ * ```ts
+ * const step: RuntimeStep = { name: 'example', start: () => {}, close: () => {} }
+ * ```
+ */
+interface RuntimeStep {
+    name: string;
+    enabled?: () => boolean;
+    start: () => void | HaiResult<unknown> | Promise<void | HaiResult<unknown>>;
+    close: () => void | HaiResult<unknown> | Promise<void | HaiResult<unknown>>;
+}
+/**
+ * 初始化和关闭合并并发调用；失败关闭保留自身及尚未关闭的依赖，供下次重试。
+ * @example
+ * ```ts
+ * import { core, type ModuleRuntime } from '@h-ai/core'
+ * const runtime: ModuleRuntime = core.module.createRuntime([])
+ * await runtime.close()
+ * ```
+ */
+interface ModuleRuntime {
+    readonly isInitialized: boolean;
+    start: () => Promise<HaiResult<void>>;
+    close: () => Promise<HaiResult<void>>;
+}
+
+export { type PaginationOptionsInput as $, type AccessCondition as A, type BrowserCoreFunctions as B, type ConfigFn as C, LogFormatSchema as D, type Env as E, type LogLevel as F, LogLevelSchema as G, HaiCommonError as H, type I18nFn as I, type LogObserver as J, type LogRecord as K, type Locale as L, type Logger as M, type LoggerFunctions as N, type LoggerOptions as O, type LoggingConfig as P, LoggingConfigSchema as Q, type MatchHandlers as R, type MessageDictionary as S, type MessageOptions as T, type ModuleFn as U, type ModuleRuntime as V, type NodeCoreFunctions as W, type NotInitializedKit as X, type ObjectFn as Y, type PaginatedResult as Z, type PaginationOptions as _, AccessConditionSchema as a, type RequestAccessCheck as a0, type RequestAccessConfigInput as a1, RequestAccessConfigSchema as a2, type RequestAccessPolicy as a3, RequestAccessPolicySchema as a4, type RequestContext as a5, type RequestEncryptionMode as a6, type RuntimeStep as a7, type SanitizeFn as a8, type SanitizeSensitiveFieldsOptions as a9, type SensitiveKeyMatcher as aa, type StringFn as ab, type TimeFn as ac, type TrustedProxies as ad, TrustedProxiesSchema as ae, type TypeUtilFn as af, type ValidationFormError as ag, type WatchCallback as ah, type ZodMessageGetter as ai, type ZodValidationFn as aj, type ZodValidationMessageKey as ak, err as al, ok as am, type AccessDecision as b, type AccessFunctions as c, type ArrayFn as d, type AsyncFn as e, type BrowserConfigFn as f, type CoreConfig as g, CoreConfigSchema as h, type CoreFunctions as i, type CoreLogger as j, type CoreOptions as k, type CreateNotInitializedKitFn as l, EnvSchema as m, type ErrorFn as n, type ErrorInfo as o, type ErrorInfoValue as p, HaiConfigError as q, type HaiError as r, type HaiErrorDef as s, type HaiResult as t, type IdFn as u, type InterpolationParams as v, type LocaleInfo as w, type LocaleMessages as x, type LogContext as y, type LogFormat as z };