zentao-api 0.3.1 → 0.3.2

package/dist/modules/define.d.ts

@@ -0,0 +1,63 @@
+import type { ModuleAction, ModuleDefinition } from '../types/index.js';
+/** {@link defineModules} 的选项。 */
+export interface DefineModulesOptions {
+    /**
+     * 同名模块的写入策略。
+     *
+     * - `false`（默认）：合并模块的元数据，并按动作名对动作做"同名替换、未知追加"。
+     * - `true`：整体替换已存在的模块定义，原有动作会被丢弃。
+     */
+    replace?: boolean;
+}
+/**
+ * 注册或扩展模块定义。
+ *
+ * 行为细节：
+ * - 模块名匹配大小写不敏感。
+ * - 未知模块直接追加到注册表末尾。
+ * - 已存在的模块默认按 `mergeModule` 合并：模块元数据浅合并、动作按名同名替换/未知追加；
+ *   `options.replace` 为 `true` 时整体替换。
+ * - 所有写入都会做深克隆 + 深冻结：调用方后续修改自己的对象不会污染注册表，注册表也不可被外部改写。
+ *
+ * @param input - 单个或一组模块定义。
+ * @param options - 写入策略，参见 {@link DefineModulesOptions}。
+ * @throws {ZentaoError} `E_INVALID_MODULE_DEFINITION` —— 缺少 `name` 或 `actions` 字段。
+ */
+export declare function defineModules(input: ModuleDefinition | ModuleDefinition[], options?: DefineModulesOptions): void;
+/**
+ * 为已存在的模块追加或覆盖动作。
+ *
+ * 不做深度合并：同名动作整体替换，未知动作追加。这避免在 schema、参数数组等字段上出现隐式合并规则。
+ *
+ * @param moduleName - 目标模块名（大小写不敏感）。
+ * @param input - 单个或一组动作定义。
+ * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）或 `E_INVALID_ACTION_DEFINITION`
+ *   （动作缺少 `name` / `path` / `method` 等必填字段）。
+ */
+export declare function defineModuleActions(moduleName: string, input: ModuleAction | ModuleAction[]): void;
+/**
+ * 扩展已存在的模块动作。
+ *
+ * 与 {@link defineModuleActions} 的「整体替换」不同，这里对单个动作做**深度合并**：
+ * 只需给出待修改的字段，其余字段沿用原动作定义。普通对象递归合并，
+ * 数组及其他值由补丁整体替换，值为 `undefined` 的键会被忽略。
+ *
+ * 当 `action` 为函数时**不做合并**：会以当前动作的深克隆为入参调用它，
+ * 其返回值作为完整的动作定义直接取代原动作定义。
+ *
+ * @param moduleName - 目标模块名（大小写不敏感）。
+ * @param actionName - 目标动作名（大小写不敏感）。
+ * @param action - 深度合并的补丁对象，或接收当前动作深克隆并返回完整动作定义的函数。
+ * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）、`E_INVALID_ACTION`（动作不存在）
+ *   或 `E_INVALID_ACTION_DEFINITION`（合并结果缺少 `name` / `path` / `method` 等必填字段）。
+ */
+export declare function extendModuleAction(moduleName: string, actionName: string, action: Partial<ModuleAction> | ((action: ModuleAction) => ModuleAction)): void;
+/**
+ * 将注册表重置为内置基线。
+ *
+ * 重置会触发 store 的「重置后钩子」，由 barrel（`./registry.ts`）在其中重新应用内置覆盖
+ * （见 `./override.ts`），因此重置后内置扩展依旧生效。
+ *
+ * @internal
+ */
+export declare function resetModuleDefinitions(): void;

package/dist/modules/define.js

@@ -0,0 +1,119 @@
+import { ZentaoError } from '../misc/errors.js';
+import { asArray } from '../utils/index.js';
+import { deepClone, deepMerge, findActionIndex, freezeAction, freezeModule, getModuleMapState, getModulesState, mergeModule, rebuildModuleMap, resetState, validateAction, validateModule, } from './registry-store.js';
+/**
+ * 注册或扩展模块定义。
+ *
+ * 行为细节：
+ * - 模块名匹配大小写不敏感。
+ * - 未知模块直接追加到注册表末尾。
+ * - 已存在的模块默认按 `mergeModule` 合并：模块元数据浅合并、动作按名同名替换/未知追加；
+ *   `options.replace` 为 `true` 时整体替换。
+ * - 所有写入都会做深克隆 + 深冻结：调用方后续修改自己的对象不会污染注册表，注册表也不可被外部改写。
+ *
+ * @param input - 单个或一组模块定义。
+ * @param options - 写入策略，参见 {@link DefineModulesOptions}。
+ * @throws {ZentaoError} `E_INVALID_MODULE_DEFINITION` —— 缺少 `name` 或 `actions` 字段。
+ */
+export function defineModules(input, options = {}) {
+    const modules = getModulesState();
+    for (const module of asArray(input)) {
+        validateModule(module);
+        const key = module.name.toLowerCase();
+        const index = modules.findIndex((item) => item.name.toLowerCase() === key);
+        if (index >= 0) {
+            modules[index] = options.replace
+                ? freezeModule(deepClone(module))
+                : mergeModule(modules[index], module);
+        }
+        else {
+            modules.push(freezeModule(deepClone(module)));
+        }
+    }
+    rebuildModuleMap();
+}
+/**
+ * 为已存在的模块追加或覆盖动作。
+ *
+ * 不做深度合并：同名动作整体替换，未知动作追加。这避免在 schema、参数数组等字段上出现隐式合并规则。
+ *
+ * @param moduleName - 目标模块名（大小写不敏感）。
+ * @param input - 单个或一组动作定义。
+ * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）或 `E_INVALID_ACTION_DEFINITION`
+ *   （动作缺少 `name` / `path` / `method` 等必填字段）。
+ */
+export function defineModuleActions(moduleName, input) {
+    const key = moduleName.toLowerCase();
+    const module = getModuleMapState().get(key);
+    if (!module) {
+        throw new ZentaoError('E_INVALID_MODULE', { module: moduleName });
+    }
+    const actions = module.actions.slice();
+    for (const action of asArray(input)) {
+        validateAction(action);
+        const index = findActionIndex(actions, String(action.name));
+        const frozen = freezeAction(deepClone(action));
+        // 同名动作替换，未知动作追加；不做深度合并，避免 schema/数组字段出现隐式规则。
+        if (index >= 0) {
+            actions[index] = frozen;
+        }
+        else {
+            actions.push(frozen);
+        }
+    }
+    const nextModule = freezeModule({ ...module, actions });
+    const modules = getModulesState();
+    const index = modules.findIndex((item) => item.name.toLowerCase() === key);
+    modules[index] = nextModule;
+    rebuildModuleMap();
+}
+/**
+ * 扩展已存在的模块动作。
+ *
+ * 与 {@link defineModuleActions} 的「整体替换」不同，这里对单个动作做**深度合并**：
+ * 只需给出待修改的字段，其余字段沿用原动作定义。普通对象递归合并，
+ * 数组及其他值由补丁整体替换，值为 `undefined` 的键会被忽略。
+ *
+ * 当 `action` 为函数时**不做合并**：会以当前动作的深克隆为入参调用它，
+ * 其返回值作为完整的动作定义直接取代原动作定义。
+ *
+ * @param moduleName - 目标模块名（大小写不敏感）。
+ * @param actionName - 目标动作名（大小写不敏感）。
+ * @param action - 深度合并的补丁对象，或接收当前动作深克隆并返回完整动作定义的函数。
+ * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）、`E_INVALID_ACTION`（动作不存在）
+ *   或 `E_INVALID_ACTION_DEFINITION`（合并结果缺少 `name` / `path` / `method` 等必填字段）。
+ */
+export function extendModuleAction(moduleName, actionName, action) {
+    const key = moduleName.toLowerCase();
+    const module = getModuleMapState().get(key);
+    if (!module) {
+        throw new ZentaoError('E_INVALID_MODULE', { module: moduleName });
+    }
+    const actions = module.actions.slice();
+    const actionIndex = findActionIndex(actions, actionName);
+    if (actionIndex < 0) {
+        throw new ZentaoError('E_INVALID_ACTION', { module: moduleName, action: actionName });
+    }
+    const current = actions[actionIndex];
+    // 函数：以当前动作的深克隆为入参，返回值作为完整动作定义直接取代原定义，不做合并。
+    // 对象：作为补丁与原动作深度合并。
+    const next = typeof action === 'function' ? action(deepClone(current)) : deepMerge(current, action);
+    validateAction(next);
+    actions[actionIndex] = freezeAction(next);
+    const nextModule = freezeModule({ ...module, actions });
+    const modules = getModulesState();
+    const index = modules.findIndex((item) => item.name.toLowerCase() === key);
+    modules[index] = nextModule;
+    rebuildModuleMap();
+}
+/**
+ * 将注册表重置为内置基线。
+ *
+ * 重置会触发 store 的「重置后钩子」，由 barrel（`./registry.ts`）在其中重新应用内置覆盖
+ * （见 `./override.ts`），因此重置后内置扩展依旧生效。
+ *
+ * @internal
+ */
+export function resetModuleDefinitions() {
+    resetState();
+}

package/dist/modules/override.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 内置覆盖 / 扩展定义。
+ *
+ * 这里集中存放对自动生成注册表（`./generated.ts`）的手工扩展：补充缺失的模块动作、
+ * 修正个别动作的元数据，或登记 OpenAPI 尚未覆盖的自定义模块。
+ *
+ * 与「用户运行时调用 {@link defineModules}」不同，这里的定义会在模块加载时自动应用，
+ * 并在 {@link resetModuleDefinitions} 重置后重新应用，因此它们等同于**内置定义**，
+ * 会随 SDK 一起发布。
+ *
+ * 维护约定：
+ * - 不要修改 `./generated.ts`（它由 `scripts/update-registry.ts` 自动生成）。
+ *   能通过更新 OpenAPI 数据解决的，优先走生成流程；只有生成器无法表达的扩展才写在这里。
+ * - 复用 {@link defineModules} / {@link defineModuleActions} 的语义：
+ *   - {@link defineModuleActions}：为**已存在**的模块追加动作（同名替换、未知追加）。
+ *   - {@link defineModules}：登记**新模块**，或对已存在模块做合并 / 整体替换（`replace`）。
+ * - 写入会自动深克隆 + 深冻结，无需自己处理不可变性。
+ *
+ * @example 为已存在的 `bug` 模块补充一个自定义动作：
+ * ```ts
+ * defineModuleActions('bug', {
+ *   name: 'assignTo',
+ *   display: '指派 Bug',
+ *   type: 'action',
+ *   method: 'put',
+ *   path: '/bugs/{bugID}/assignto',
+ *   resultType: 'text',
+ *   pathParams: { bugID: 'Bug ID' },
+ *   requestBody: {
+ *     required: true,
+ *     schema: {
+ *       assignedTo: { type: 'string', description: '指派给' },
+ *       comment: { type: 'string', description: '备注' },
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @example 登记一个 OpenAPI 未覆盖的新模块：
+ * ```ts
+ * defineModules({
+ *   name: 'custom',
+ *   display: '自定义模块',
+ *   actions: [
+ *     {
+ *       name: 'list',
+ *       type: 'list',
+ *       method: 'get',
+ *       path: '/customs',
+ *       resultType: 'list',
+ *       pagerGetter: 'pager',
+ *       resultGetter: 'customs',
+ *     },
+ *   ],
+ * });
+ * ```
+ *
+ * @internal
+ */
+export declare function applyBuiltinOverrides(): void;

package/dist/modules/override.js

@@ -0,0 +1,113 @@
+import { extendModuleAction } from './define.js';
+/**
+ * 内置覆盖 / 扩展定义。
+ *
+ * 这里集中存放对自动生成注册表（`./generated.ts`）的手工扩展：补充缺失的模块动作、
+ * 修正个别动作的元数据，或登记 OpenAPI 尚未覆盖的自定义模块。
+ *
+ * 与「用户运行时调用 {@link defineModules}」不同，这里的定义会在模块加载时自动应用，
+ * 并在 {@link resetModuleDefinitions} 重置后重新应用，因此它们等同于**内置定义**，
+ * 会随 SDK 一起发布。
+ *
+ * 维护约定：
+ * - 不要修改 `./generated.ts`（它由 `scripts/update-registry.ts` 自动生成）。
+ *   能通过更新 OpenAPI 数据解决的，优先走生成流程；只有生成器无法表达的扩展才写在这里。
+ * - 复用 {@link defineModules} / {@link defineModuleActions} 的语义：
+ *   - {@link defineModuleActions}：为**已存在**的模块追加动作（同名替换、未知追加）。
+ *   - {@link defineModules}：登记**新模块**，或对已存在模块做合并 / 整体替换（`replace`）。
+ * - 写入会自动深克隆 + 深冻结，无需自己处理不可变性。
+ *
+ * @example 为已存在的 `bug` 模块补充一个自定义动作：
+ * ```ts
+ * defineModuleActions('bug', {
+ *   name: 'assignTo',
+ *   display: '指派 Bug',
+ *   type: 'action',
+ *   method: 'put',
+ *   path: '/bugs/{bugID}/assignto',
+ *   resultType: 'text',
+ *   pathParams: { bugID: 'Bug ID' },
+ *   requestBody: {
+ *     required: true,
+ *     schema: {
+ *       assignedTo: { type: 'string', description: '指派给' },
+ *       comment: { type: 'string', description: '备注' },
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @example 登记一个 OpenAPI 未覆盖的新模块：
+ * ```ts
+ * defineModules({
+ *   name: 'custom',
+ *   display: '自定义模块',
+ *   actions: [
+ *     {
+ *       name: 'list',
+ *       type: 'list',
+ *       method: 'get',
+ *       path: '/customs',
+ *       resultType: 'list',
+ *       pagerGetter: 'pager',
+ *       resultGetter: 'customs',
+ *     },
+ *   ],
+ * });
+ * ```
+ *
+ * @internal
+ */
+export function applyBuiltinOverrides() {
+    // 创建执行时，需要添加产品字段
+    extendModuleAction('execution', 'create', (action) => {
+        const required = action.requestBody.schema?.required;
+        if (Array.isArray(required) && !required.includes('products')) {
+            required.push('products');
+        }
+        return action;
+    });
+    // 修改 story/update 字段定义
+    extendModuleAction('story', 'update', (action) => {
+        const properties = action.requestBody.schema?.properties;
+        // 为 story/update 增加 plan 字段
+        if (properties && !properties.plan) {
+            properties.plan = {
+                type: 'integer',
+                description: '所属计划',
+                format: 'int32',
+            };
+        }
+        // 修改 category 字段类型为 string
+        if (properties && properties.category) {
+            properties.category = {
+                type: 'string',
+                description: '类别',
+            };
+        }
+        return action;
+    });
+    // 修改 task/list URL 定义
+    extendModuleAction('task', 'list', (action) => {
+        action.path = '/executions/{executionID}/tasks';
+        action.pathParams = {
+            executionID: '执行ID',
+        };
+        return action;
+    });
+    // 修改 acl 字段默认值为 open
+    [
+        ['product', 'create'],
+        ['product', 'update'],
+        ['execution', 'create'],
+        ['execution', 'update'],
+    ].forEach(([moduleName, actionName]) => {
+        extendModuleAction(moduleName, actionName, (action) => {
+            const properties = action.requestBody.schema?.properties;
+            if (properties.acl && properties.acl.defaultValue === undefined) {
+                properties.acl.defaultValue = 'open';
+            }
+            return action;
+        });
+    });
+}

package/dist/modules/query.d.ts

@@ -0,0 +1,44 @@
+import type { ModuleAction, ModuleDefinition } from '../types/index.js';
+/**
+ * 获取模块定义。
+ *
+ * 模块名匹配大小写不敏感。返回值是注册表内部的已深冻结引用（O(1) 查询、零拷贝），
+ * 任何写入尝试在严格模式下会抛 `TypeError`；如需修改请使用 {@link defineModules}。
+ *
+ * @param moduleName - 模块名。
+ * @returns 已注册的模块定义。
+ * @throws {ZentaoError} `E_INVALID_MODULE` —— 模块未注册。
+ */
+export declare function getModule(moduleName: string): ModuleDefinition;
+/**
+ * 获取指定模块下的某个动作。
+ *
+ * 解析顺序：
+ * 1. `actionName === 'ls'` 时映射为 `list`（仅作为别名，不会修改注册表）。
+ * 2. 在该模块的动作中按名称大小写不敏感匹配。
+ * 3. 当请求的动作不是基础 CRUD（`list`/`get`/`create`/`update`/`delete`）时，
+ *    额外允许命中 `type === 'action'` 的自定义动作（即使名字不在基础 CRUD 中）。
+ *
+ * 返回值同样是已深冻结的引用，请勿尝试修改。
+ *
+ * @param moduleName - 模块名（大小写不敏感）。
+ * @param actionName - 动作名（大小写不敏感）；支持 `ls` 作为 `list` 的别名。
+ * @returns 匹配到的动作定义。
+ * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）或 `E_INVALID_ACTION`（动作不存在）。
+ */
+export declare function getModuleAction(moduleName: string, actionName: string): ModuleAction;
+/**
+ * 返回当前运行时注册表中的所有模块名。
+ *
+ * 顺序与模块写入注册表的顺序一致；包括内置模块和通过 {@link defineModules} 追加的用户模块。
+ *
+ * @returns 模块名数组（保留原始大小写）。
+ */
+export declare function getModuleNames(): string[];
+/**
+ * 判断模块名是否已注册。
+ *
+ * @param moduleName - 模块名；匹配大小写不敏感。
+ * @returns 已注册返回 `true`，否则 `false`。
+ */
+export declare function isModuleName(moduleName: string): boolean;

package/dist/modules/query.js

@@ -0,0 +1,68 @@
+import { ZentaoError } from '../misc/errors.js';
+import { getModuleMapState, getModulesState } from './registry-store.js';
+/**
+ * 获取模块定义。
+ *
+ * 模块名匹配大小写不敏感。返回值是注册表内部的已深冻结引用（O(1) 查询、零拷贝），
+ * 任何写入尝试在严格模式下会抛 `TypeError`；如需修改请使用 {@link defineModules}。
+ *
+ * @param moduleName - 模块名。
+ * @returns 已注册的模块定义。
+ * @throws {ZentaoError} `E_INVALID_MODULE` —— 模块未注册。
+ */
+export function getModule(moduleName) {
+    const module = getModuleMapState().get(moduleName.toLowerCase());
+    if (!module) {
+        throw new ZentaoError('E_INVALID_MODULE', { module: moduleName });
+    }
+    return module;
+}
+/**
+ * 获取指定模块下的某个动作。
+ *
+ * 解析顺序：
+ * 1. `actionName === 'ls'` 时映射为 `list`（仅作为别名，不会修改注册表）。
+ * 2. 在该模块的动作中按名称大小写不敏感匹配。
+ * 3. 当请求的动作不是基础 CRUD（`list`/`get`/`create`/`update`/`delete`）时，
+ *    额外允许命中 `type === 'action'` 的自定义动作（即使名字不在基础 CRUD 中）。
+ *
+ * 返回值同样是已深冻结的引用，请勿尝试修改。
+ *
+ * @param moduleName - 模块名（大小写不敏感）。
+ * @param actionName - 动作名（大小写不敏感）；支持 `ls` 作为 `list` 的别名。
+ * @returns 匹配到的动作定义。
+ * @throws {ZentaoError} `E_INVALID_MODULE`（模块未注册）或 `E_INVALID_ACTION`（动作不存在）。
+ */
+export function getModuleAction(moduleName, actionName) {
+    const module = getModule(moduleName);
+    const normalized = actionName === 'ls' ? 'list' : actionName;
+    const direct = module.actions.find((action) => String(action.name).toLowerCase() === normalized.toLowerCase());
+    if (direct)
+        return direct;
+    const crud = new Set(['list', 'get', 'create', 'update', 'delete']);
+    if (!crud.has(normalized)) {
+        const custom = module.actions.find((action) => action.type === 'action' && String(action.name).toLowerCase() === normalized.toLowerCase());
+        if (custom)
+            return custom;
+    }
+    throw new ZentaoError('E_INVALID_ACTION', { module: moduleName, action: actionName });
+}
+/**
+ * 返回当前运行时注册表中的所有模块名。
+ *
+ * 顺序与模块写入注册表的顺序一致；包括内置模块和通过 {@link defineModules} 追加的用户模块。
+ *
+ * @returns 模块名数组（保留原始大小写）。
+ */
+export function getModuleNames() {
+    return getModulesState().map((module) => module.name);
+}
+/**
+ * 判断模块名是否已注册。
+ *
+ * @param moduleName - 模块名；匹配大小写不敏感。
+ * @returns 已注册返回 `true`，否则 `false`。
+ */
+export function isModuleName(moduleName) {
+    return getModuleMapState().has(moduleName.toLowerCase());
+}

package/dist/modules/registry-store.d.ts

@@ -0,0 +1,31 @@
+import type { ModuleAction, ModuleDefinition } from '../types/index.js';
+export declare function deepClone<T>(value: T): T;
+/**
+ * 深度合并：以 `patch` 覆盖 `base`，返回新对象，不修改任何入参。
+ *
+ * - 仅当两侧同为普通对象时递归合并；其余情况（含数组）由 `patch` 整体替换。
+ * - `patch` 中值为 `undefined` 的键会被跳过，因此扩展方只需给出待修改的字段。
+ * - 未被 `patch` 触及的嵌套值沿用 `base` 的引用（外层会重新深冻结，引用本就不可变）。
+ */
+export declare function deepMerge<T>(base: T, patch: unknown): T;
+export declare function cloneBuiltinModules(): ModuleDefinition[];
+export declare function deepFreeze<T>(value: T): T;
+export declare function freezeAction(action: ModuleAction): ModuleAction;
+export declare function freezeModule(module: ModuleDefinition): ModuleDefinition;
+export declare function freezeModules(source: ModuleDefinition[]): ModuleDefinition[];
+export declare function findActionIndex(source: readonly ModuleAction[], actionName: string): number;
+export declare function mergeActions(base: readonly ModuleAction[], extension: readonly ModuleAction[]): ModuleAction[];
+export declare function mergeModule(base: ModuleDefinition, extension: ModuleDefinition): ModuleDefinition;
+export declare function buildModuleMap(source: readonly ModuleDefinition[]): Map<string, ModuleDefinition>;
+export declare function validateModule(module: ModuleDefinition): void;
+export declare function validateAction(action: ModuleAction): void;
+/** 当前运行时注册表中的模块数组（define 侧原地修改，query 侧只读）。 */
+export declare function getModulesState(): ModuleDefinition[];
+/** 当前模块名（小写）到模块定义的查找表（O(1) 查询）。 */
+export declare function getModuleMapState(): Map<string, ModuleDefinition>;
+/** 依据当前 modules 重建 moduleMap。所有写入完成后调用以保持二者一致。 */
+export declare function rebuildModuleMap(): void;
+/** 注册「重置后钩子」，在每次 {@link resetState} 还原内置基线后调用。 */
+export declare function setPostResetHook(hook: (() => void) | undefined): void;
+/** 将注册表重置为内置模块（深克隆 + 深冻结），重建查找表，并触发重置后钩子。 */
+export declare function resetState(): void;

package/dist/modules/registry-store.js

@@ -0,0 +1,133 @@
+import { ZentaoError } from '../misc/errors.js';
+import { isRecord } from '../utils/object.js';
+import { BUILTIN_MODULES } from './generated.js';
+// 运行时注册表存放「深克隆 + 深冻结」后的模块定义：
+// - 深克隆：避免用户后续修改自己的输入对象时污染注册表；
+// - 深冻结：让 getModule / getModuleAction 可以零拷贝返回引用，
+//   外部尝试改写会在严格模式下抛 TypeError，开销也降到 O(1) 查询。
+//
+// 该模块是「定义」（define）与「查询」（query）两侧共享的底层存储：
+// - define 侧通过 mutate* 系列函数维护状态，并复用 freeze/clone/merge/validate 原语；
+// - query 侧只读访问 modules / moduleMap。
+let modules = freezeModules(cloneBuiltinModules());
+let moduleMap = buildModuleMap(modules);
+export function deepClone(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => deepClone(item));
+    }
+    if (value && typeof value === 'object' && !(value instanceof Function)) {
+        const result = {};
+        for (const [key, nestedValue] of Object.entries(value)) {
+            result[key] = deepClone(nestedValue);
+        }
+        return result;
+    }
+    return value;
+}
+/**
+ * 深度合并：以 `patch` 覆盖 `base`，返回新对象，不修改任何入参。
+ *
+ * - 仅当两侧同为普通对象时递归合并；其余情况（含数组）由 `patch` 整体替换。
+ * - `patch` 中值为 `undefined` 的键会被跳过，因此扩展方只需给出待修改的字段。
+ * - 未被 `patch` 触及的嵌套值沿用 `base` 的引用（外层会重新深冻结，引用本就不可变）。
+ */
+export function deepMerge(base, patch) {
+    if (!isRecord(patch)) {
+        return (patch === undefined ? base : deepClone(patch));
+    }
+    const result = isRecord(base) ? { ...base } : {};
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === undefined)
+            continue;
+        const current = result[key];
+        result[key] = isRecord(value) && isRecord(current) ? deepMerge(current, value) : deepClone(value);
+    }
+    return result;
+}
+export function cloneBuiltinModules() {
+    return deepClone(BUILTIN_MODULES);
+}
+export function deepFreeze(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (Object.isFrozen(value))
+        return value;
+    for (const key of Object.keys(value)) {
+        deepFreeze(value[key]);
+    }
+    return Object.freeze(value);
+}
+export function freezeAction(action) {
+    return deepFreeze(action);
+}
+export function freezeModule(module) {
+    module.actions.forEach(freezeAction);
+    return deepFreeze(module);
+}
+export function freezeModules(source) {
+    source.forEach(freezeModule);
+    return source;
+}
+export function findActionIndex(source, actionName) {
+    const key = actionName.toLowerCase();
+    return source.findIndex((action) => String(action.name).toLowerCase() === key);
+}
+export function mergeActions(base, extension) {
+    const next = base.slice();
+    for (const action of extension) {
+        const index = findActionIndex(next, String(action.name));
+        const frozen = freezeAction(deepClone(action));
+        if (index >= 0) {
+            next[index] = frozen;
+        }
+        else {
+            next.push(frozen);
+        }
+    }
+    return next;
+}
+export function mergeModule(base, extension) {
+    return freezeModule({
+        ...base,
+        ...deepClone(extension),
+        actions: mergeActions(base.actions, extension.actions),
+    });
+}
+export function buildModuleMap(source) {
+    return new Map(source.map((module) => [module.name.toLowerCase(), module]));
+}
+export function validateModule(module) {
+    if (!module || typeof module.name !== 'string' || !Array.isArray(module.actions)) {
+        throw new ZentaoError('E_INVALID_MODULE_DEFINITION');
+    }
+}
+export function validateAction(action) {
+    if (!action || typeof action.name !== 'string' || typeof action.path !== 'string' || typeof action.method !== 'string') {
+        throw new ZentaoError('E_INVALID_ACTION_DEFINITION');
+    }
+}
+/** 当前运行时注册表中的模块数组（define 侧原地修改，query 侧只读）。 */
+export function getModulesState() {
+    return modules;
+}
+/** 当前模块名（小写）到模块定义的查找表（O(1) 查询）。 */
+export function getModuleMapState() {
+    return moduleMap;
+}
+/** 依据当前 modules 重建 moduleMap。所有写入完成后调用以保持二者一致。 */
+export function rebuildModuleMap() {
+    moduleMap = buildModuleMap(modules);
+}
+// 重置后钩子：在 resetState 把状态还原为内置基线之后触发，
+// 用于让上层（barrel）重新应用内置覆盖（override），而无需 store / define 直接依赖 override。
+let postResetHook;
+/** 注册「重置后钩子」，在每次 {@link resetState} 还原内置基线后调用。 */
+export function setPostResetHook(hook) {
+    postResetHook = hook;
+}
+/** 将注册表重置为内置模块（深克隆 + 深冻结），重建查找表，并触发重置后钩子。 */
+export function resetState() {
+    modules = freezeModules(cloneBuiltinModules());
+    rebuildModuleMap();
+    postResetHook?.();
+}