@taicode/common-server 4.0.0-beta.3 → 4.0.0-beta.4

package/output/core/assemble.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assemble.d.ts","sourceRoot":"","sources":["../../source/core/assemble.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAA;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,SAAS,GAAG,eAAe,CAM7D;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,IAAI,eAAe,CAEvD;AAED,gBAAgB;AAChB,MAAM,WAAW,uBAAuB;IACtC,8DAA8D;IAC9D,QAAQ,EAAE,WAAW,CAAA;IACrB,GAAG,EAAE,SAAS,CAAA;IACd,yEAAyE;IACzE,qBAAqB,CAAC,EAAE,eAAe,CAAA;IACvC,2DAA2D;IAC3D,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;CACrC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,IAAI,CAAC,uBAAuB,EAAE,UAAU,CAAC,GAAG,IAAI,CAIrH;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,IAAI,CAAC,uBAAuB,EAAE,UAAU,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAOlI;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAWxG"}

package/output/core/assemble.js

@@ -0,0 +1,88 @@
+import Fastify from 'fastify';
+import { registerCookie } from './modules/cookie/index.js';
+import { registerRequestContext } from './modules/context/index.js';
+import { attachServerIdentity } from './modules/identity/index.js';
+import { createLoggerOptions } from './modules/logging/index.js';
+import { registerOpenApi } from './modules/openapi/index.js';
+import { createRequestIdOptions, registerRequestId } from './modules/request-id/index.js';
+import { registerResponse } from './modules/response/index.js';
+import { installRouteSchemaGuard, registerSchema } from './modules/schema/index.js';
+/**
+ * core 步骤 `createFastify`（`prepare`）。
+ *
+ * **总是**建 pino logger（level = `LOG_LEVEL`，默认 `info`） + 内置 `requestId`（入站 `x-request-id`
+ * 复用 / `randomUUID`，日志字段 `requestId`）。`trustProxy: true` 与四家现状一致。
+ *
+ * 固定装配，**不从包对外导出**：对外入口只有 `defineServer` / `startServer` / `generateOpenApi`。
+ */
+export function createFastify(env) {
+    return Fastify({
+        trustProxy: true,
+        logger: createLoggerOptions(env),
+        ...createRequestIdOptions(),
+    });
+}
+/**
+ * 出文档用的**最小实例**（`generateOpenApi` 专用）。
+ *
+ * 没有 logger、没有 `requestId`、没有 `trustProxy`——这些只在**有请求**时才有意义，
+ * 而构建期一条请求都不会发。`logger: false` 下 `app.log` 仍是 `abstract-logging` 的
+ * 空实现，满足 `LoggerLike`，因此下游单元拿到的 `ctx.log` 调用不会炸，也不会产生输出。
+ */
+export function createDocumentFastify() {
+    return Fastify({ logger: false });
+}
+/**
+ * **schema 契约**（固定序，不可替换）：`identity` → `schema`（zod compiler）→ 路由契约守卫。
+ *
+ * 两个入口都必须有它：
+ * - `startServer` 要让 zod 真的校验/序列化请求，并让「路由缺 `schema`」在注册处就失败；
+ * - `generateOpenApi` 要把 zod 转成 JSON Schema 出文档，也要同一个守卫——**文档就是权限目录**，
+ *   构建期放过的路由会在线上变成「接口永远判不过」。
+ *
+ * 单独成函数是为了让「运行期 core」与「文档 core」两条装配路径共用同一段契约，
+ * 而不用把整段运行期能力拖进出文档路径。
+ */
+export function registerSchemaContract(app, options) {
+    attachServerIdentity(app, options.identity);
+    registerSchema(app); // schema → zod compiler
+    installRouteSchemaGuard(app); // 强制所有路由声明 schema（含 operationId / summary / description / tags）
+}
+/**
+ * **文档 core**（`generateOpenApi` 专用）：schema 契约 + swagger。
+ *
+ * 只有这三件事与「把 zod schema 转成 OpenAPI 文档」有关：身份（`info.title` /
+ * `info.version`）、zod compiler（转换前得能读懂 zod）、守卫（不让文档缺条目）、swagger（转换器）。
+ * `requestContext` / `cookie` / `response` / `requestId` 全部**不装**——它们只影响
+ * 请求怎么被处理，而构建期一条请求都不会发。
+ */
+export async function registerDocumentCore(app, options) {
+    registerSchemaContract(app, options);
+    // await：确定性冲刷插件队列，保证 swagger 的 root `onRoute` 钩子在路由注册之前就位
+    await registerOpenApi(app, {
+        title: options.identity.title,
+        version: options.identity.version,
+    });
+}
+/**
+ * core 装配（固定序，不可替换）：`identity` → `schema`（+ 路由契约守卫）→ `requestContext`
+ * → `cookie` → `response` → `openapi` → `requestId` 回吐。
+ *
+ * 全部为框架内置能力，**不暴露选项面**；`request.ctx` 的装配也在这一步完成（`type-augment` 的
+ * 类型承诺因此总有运行期对应物）。**构造期不读配置**（`cookie` 的 domain 在请求期惰性读取），
+ * 故出 spec 路径（`readConfig` 不可用）不会触发。
+ *
+ * 这里**不建路由注册表**：权限目录直接由 `app.swagger()` 生成的文档派生（OpenAPI 是唯一来源）。
+ */
+export async function registerCore(app, options) {
+    registerSchemaContract(app, options);
+    registerRequestContext(app); // request.ctx（type-augment 承诺的运行期对应物）
+    registerCookie(app, { env: options.env, readConfig: options.readConfig });
+    registerResponse(app, { classifyResourceError: options.classifyResourceError });
+    // await：确定性冲刷插件队列，保证 swagger 的 root `onRoute` 钩子在路由注册之前就位
+    await registerOpenApi(app, {
+        title: options.identity.title,
+        version: options.identity.version,
+    });
+    registerRequestId(app); // 响应回吐 x-request-id
+}

package/output/core/boot/context.d.ts

@@ -0,0 +1,89 @@
+import type { Disposer } from '@taicode/common-base';
+import type { ConfigEnv } from '../env.js';
+import type { AppInstance, ClientsContext, ClientsView, ConfigContext, ErrorClassifier, LoggerLike, MiddlewareContext, ResourcesContext, ResourcesView, RouterContext, ServiceContext } from '../types.js';
+/**
+ * 分阶段 ctx 的运行时构造（N1 §2）。
+ *
+ * 每个槽位拿到的是**字段最小集合**的普通对象；`config` 用 getter 暴露，出 spec 路径
+ * （`generateOpenApi` 不跑 `config` 槽位）读到它时抛 `SystemError('CONFIG_UNAVAILABLE')`
+ * —— 让「构造期不得读配置」有运行期护栏，而不仅是文档规则。
+ */
+/** 运行时镜像 `Live<T>`：剔除值为 `false` 的键（编译期静态关闭） */
+export declare function liveResources(resources: object): Record<string, unknown>;
+/** 客户端包的运行时镜像（口径与 `liveResources` 完全一致，另立一名只为调用处可读） */
+export declare function liveClients(clients: object): Record<string, unknown>;
+/**
+ * `config` 槽位的**读取能力**（不是容器）。
+ *
+ * 装配期各单元需要的是「能不能读、读到什么」，不是「一个有 `current` 字段的箱子」——
+ * 后者把**写入**也一并交给了每个拿到 `BootContext` 的步骤，绕开 `buildConfig` 就能改配置。
+ * 因此这里只暴露读：`available`（有没有产出）+ `read()`（读，未产出即抛）。
+ *
+ * 写入通道是**私有 Symbol**（本文件内、不导出）：调用方连键名都写不出来，只能通过
+ * `provideConfig()` 写，而它只被 `buildConfig` 调用。
+ */
+export interface ConfigAccess<C> {
+    /** `config` 槽位是否已产出（出 spec 路径恒为 `false`） */
+    readonly available: boolean;
+    /** 读配置；未产出时抛 `SystemError('CONFIG_UNAVAILABLE')` */
+    read(): Awaited<C>;
+}
+export declare function createConfigAccess<C>(): ConfigAccess<C>;
+/** 写入 `config` 产物（唯一的写入口：由 `buildConfig` 调用，不在 `BootContext` 上暴露） */
+export declare function provideConfig<C>(access: ConfigAccess<C>, value: Awaited<C>): void;
+/** 按**已知键**从配置值里取字段（框架内置单元消费配置的单一入口；不做形状校验） */
+export declare function readConfigKey(config: unknown, key: string): unknown;
+/** `resources(ctx)` 入参 */
+export interface ResourcesContextParams {
+    env: ConfigEnv;
+    log: LoggerLike;
+    disposer: Disposer;
+    /** 收集器：`buildResources` 注入，把各资源注册的分类器按注册顺序收起来 */
+    registerClassifyError: (classifier: ErrorClassifier) => void;
+}
+export declare function createResourcesContext(params: ResourcesContextParams): ResourcesContext;
+/** `config(ctx)` 入参 */
+export interface ConfigContextParams<R> {
+    env: ConfigEnv;
+    log: LoggerLike;
+    disposer: Disposer;
+    resources: ResourcesView<R>;
+}
+export declare function createConfigContext<R>(params: ConfigContextParams<R>): ConfigContext<R>;
+/** `clients(ctx)` 入参（与 `services` 同依赖集：`resources` + `config`） */
+export interface ClientsContextParams<R, C> {
+    log: LoggerLike;
+    disposer: Disposer;
+    resources: ResourcesView<R>;
+    configAccess: ConfigAccess<C>;
+}
+export declare function createClientsContext<R, C>(params: ClientsContextParams<R, C>): ClientsContext<R, C>;
+/** `services(ctx)` 入参 */
+export interface ServiceContextParams<R, C, CL> {
+    log: LoggerLike;
+    disposer: Disposer;
+    resources: ResourcesView<R>;
+    configAccess: ConfigAccess<C>;
+    clients: ClientsView<CL>;
+}
+export declare function createServiceContext<R, C, CL>(params: ServiceContextParams<R, C, CL>): ServiceContext<R, C, CL>;
+/** `middlewares(ctx)` 入参 */
+export interface MiddlewareContextParams<C, S, CL> {
+    app: AppInstance;
+    log: LoggerLike;
+    disposer: Disposer;
+    services: Awaited<S>;
+    configAccess: ConfigAccess<C>;
+    clients: ClientsView<CL>;
+}
+export declare function createMiddlewareContext<C, S, CL>(params: MiddlewareContextParams<C, S, CL>): MiddlewareContext<C, S, CL>;
+/** `routers(ctx)` 入参 */
+export interface RouterContextParams<S, CL> {
+    app: AppInstance;
+    log: LoggerLike;
+    disposer: Disposer;
+    services: Awaited<S>;
+    clients: ClientsView<CL>;
+}
+export declare function createRouterContext<S, CL>(params: RouterContextParams<S, CL>): RouterContext<S, CL>;
+//# sourceMappingURL=context.d.ts.map

package/output/core/boot/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../source/core/boot/context.ts"],"names":[],"mappings":"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"}

package/output/{app → core/boot}/context.js

@@ -1,4 +1,4 @@
-import { SystemError } from './errors.js';
+import { SystemError } from '@taicode/common-base';
 /**
  * 分阶段 ctx 的运行时构造（N1 §2）。
  *
@@ -16,15 +16,36 @@ export function liveResources(resources) {
     }
     return result;
 }
-export function createConfigHolder() {
-    return { current: undefined };
+/** 客户端包的运行时镜像（口径与 `liveResources` 完全一致，另立一名只为调用处可读） */
+export function liveClients(clients) {
+    return liveResources(clients);
 }
-/** 读配置：react 未就绪时抛 `SystemError('CONFIG_UNAVAILABLE')` */
-export function requireConfig(holder) {
-    if (holder.current === undefined) {
-        throw new SystemError('CONFIG_UNAVAILABLE', undefined, '配置尚未就绪（generateOpenApi 路径不跑 config 槽位）：任何单元不得在构造期读配置');
+const CONFIG_WRITE = Symbol('config.write');
+export function createConfigAccess() {
+    let value;
+    const access = {
+        get available() {
+            return value !== undefined;
+        },
+        read() {
+            if (value === undefined) {
+                throw new SystemError('CONFIG_UNAVAILABLE', undefined, '配置尚未就绪（generateOpenApi 路径不跑 config 槽位）：任何单元不得在构造期读配置');
+            }
+            return value;
+        },
+        [CONFIG_WRITE](next) {
+            value = next;
+        },
+    };
+    return access;
+}
+/** 写入 `config` 产物（唯一的写入口：由 `buildConfig` 调用，不在 `BootContext` 上暴露） */
+export function provideConfig(access, value) {
+    const write = access[CONFIG_WRITE];
+    if (write === undefined) {
+        throw new Error('[config] 非法写入：`ConfigAccess` 只能由 `createConfigAccess()` 产出');
     }
-    return holder.current;
+    write(value);
 }
 /** 按**已知键**从配置值里取字段（框架内置单元消费配置的单一入口；不做形状校验） */
 export function readConfigKey(config, key) {
@@ -41,13 +62,24 @@ export function createResourcesContext(params) {
 export function createConfigContext(params) {
     return { env: params.env, log: params.log, disposer: params.disposer, resources: params.resources };
 }
+export function createClientsContext(params) {
+    return {
+        log: params.log,
+        disposer: params.disposer,
+        resources: params.resources,
+        get config() {
+            return params.configAccess.read();
+        },
+    };
+}
 export function createServiceContext(params) {
     return {
         log: params.log,
         disposer: params.disposer,
         resources: params.resources,
+        clients: params.clients,
         get config() {
-            return requireConfig(params.holder);
+            return params.configAccess.read();
         },
     };
 }
@@ -57,23 +89,18 @@ export function createMiddlewareContext(params) {
         log: params.log,
         disposer: params.disposer,
         services: params.services,
+        clients: params.clients,
         get config() {
-            return requireConfig(params.holder);
+            return params.configAccess.read();
         },
     };
 }
 export function createRouterContext(params) {
-    return { app: params.app, log: params.log, disposer: params.disposer, services: params.services };
-}
-export function createShutdownContext(params) {
     return {
         app: params.app,
         log: params.log,
         disposer: params.disposer,
-        resources: params.resources,
-        get config() {
-            return requireConfig(params.holder);
-        },
         services: params.services,
+        clients: params.clients,
     };
 }

package/output/{app → core/boot}/lifecycle.d.ts

@@ -1,26 +1,30 @@
 import type { Disposer } from '@taicode/common-base';
-import type { LoggerLike } from './types.js';
+import type { LoggerLike } from '../types.js';
 /**
  * 生命周期序（N1 §4 / N2 §2.5）。
  *
  * **每个阶段一个 `Disposer`**（`ctx.disposer`，所有槽位都有）：在创建某个东西的地方当场
  * `ctx.disposer.add(() => 释放它)` —— 创建与释放同处一地。
  *
- * 关闭时按阶段**逆序 flush**：`routers → middlewares → services → config → resources`
+ * 关闭时按阶段**逆序 flush**：`routers → middlewares → services → clients → config → resources`
  * （后创建的先销毁；Prisma / Redis 这类资源最后才断）。
  *
+ * **`clients` 为什么排在 `services` 之后关**：服务单元 `dispose()` 时可能还要落一次外部调用
+ * （落库、通知、上报），客户端必须先活着。
+ *
  * **`services` 额外有逐单元生命周期**：
  * - 单元之间**不得相互依赖**（`services` 的 ctx 没有 `services` 字段，编译期禁止）；
  * - `init` 按**对象声明序**，`dispose` **逆序**；
  * - services 阶段内部**先 flush `ctx.disposer`**（构造期注册的清理），再逐单元 `dispose`。
  *
- * `middlewares` 按数组序注册；它只有 `disposer`，没有逐单元生命周期。
+ * `middlewares` 按**对象键序**注册；它只有 `disposer`，没有逐单元生命周期。
  */
-export declare const SERVICES_STAGE = "services";
+export declare const RESOURCES_STAGE = "resources";
 export declare const CONFIG_STAGE = "config";
+export declare const CLIENTS_STAGE = "clients";
+export declare const SERVICES_STAGE = "services";
 export declare const MIDDLEWARES_STAGE = "middlewares";
 export declare const ROUTERS_STAGE = "routers";
-export declare const RESOURCES_STAGE = "resources";
 /** `middlewares` 的**注册期日志**阶段标签（与生命周期阶段同名） */
 export declare const MIDDLEWARES_LOG_STAGE = "middlewares";
 /** 生命周期相位（逐单元日志字段 `phase`） */
@@ -47,13 +51,11 @@ export interface LifecycleUnitLogFields {
     phase: LifecyclePhase;
 }
 /**
- * `services` 有效名字：**对象键即单元名**（N1 §4：没有 `name` 字段）。
- */
-export declare function serviceUnitName(key: string): string;
-/**
- * `middlewares` 日志名字：`unit.name ?? '<service>:middleware[<index>]'`（仅用于注册期日志）。
+ * `middlewares` 日志名字：**对象键即单元名**（与 `services` 同口径）。
+ *
+ * 键为空串时退路 `<service>:middleware`（仅用于注册期日志，不影响注册序）。
  */
-export declare function middlewareUnitName(service: string, unit: unknown, index: number): string;
+export declare function middlewareUnitName(service: string, key: string): string;
 /** `initServiceUnits` 入参（参数签名内联对象类型已按 lint 规则外提） */
 export interface InitServiceUnitsParams extends LifecycleLogContext {
     /** `services(ctx)` 返回的对象（**对象键即单元名**） */
@@ -68,10 +70,6 @@ export interface DisposeServiceUnitsParams extends LifecycleLogContext {
     /** `services(ctx)` 返回的对象（**对象键即单元名**） */
     services?: Record<string, unknown>;
 }
-/**
- * 关闭序：`services` 按声明序**逆序**逐项 `dispose?.()`。
- */
-export declare function buildDisposeOrder(params: DisposeServiceUnitsParams): Array<() => void | Promise<void>>;
 /**
  * 关闭步 `disposeServices`：`services` 声明序逆序释放。
  *

package/output/core/boot/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../source/core/boot/lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;;;;;;;;;;;;;;GAkBG;AAEH,eAAO,MAAM,eAAe,cAAc,CAAA;AAC1C,eAAO,MAAM,YAAY,WAAW,CAAA;AACpC,eAAO,MAAM,aAAa,YAAY,CAAA;AACtC,eAAO,MAAM,cAAc,aAAa,CAAA;AACxC,eAAO,MAAM,iBAAiB,gBAAgB,CAAA;AAC9C,eAAO,MAAM,aAAa,YAAY,CAAA;AACtC,8CAA8C;AAC9C,eAAO,MAAM,qBAAqB,gBAAoB,CAAA;AAEtD,8BAA8B;AAC9B,eAAO,MAAM,oBAAoB,SAAS,CAAA;AAC1C,eAAO,MAAM,uBAAuB,YAAY,CAAA;AAChD,MAAM,MAAM,cAAc,GAAG,OAAO,oBAAoB,GAAG,OAAO,uBAAuB,CAAA;AAEzF;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,sCAAsC;IACtC,GAAG,CAAC,EAAE,UAAU,CAAA;CACjB;AAED,8DAA8D;AAC9D,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,cAAc,CAAA;CACtB;AAaD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,oDAAoD;AACpD,MAAM,WAAW,sBAAuB,SAAQ,mBAAmB;IACjE,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAmCD;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAIpF;AAED,6EAA6E;AAC7E,MAAM,WAAW,yBAA0B,SAAQ,mBAAmB;IACpE,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAaD;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,yBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC,CAQtF;AAED,gDAAgD;AAChD,MAAM,WAAW,kBAAmB,SAAQ,mBAAmB;IAC7D,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAA;IACb,6CAA6C;IAC7C,QAAQ,EAAE,QAAQ,CAAA;CACnB;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAU5E"}

package/output/{app → core/boot}/lifecycle.js

@@ -4,21 +4,25 @@
  * **每个阶段一个 `Disposer`**（`ctx.disposer`，所有槽位都有）：在创建某个东西的地方当场
  * `ctx.disposer.add(() => 释放它)` —— 创建与释放同处一地。
  *
- * 关闭时按阶段**逆序 flush**：`routers → middlewares → services → config → resources`
+ * 关闭时按阶段**逆序 flush**：`routers → middlewares → services → clients → config → resources`
  * （后创建的先销毁；Prisma / Redis 这类资源最后才断）。
  *
+ * **`clients` 为什么排在 `services` 之后关**：服务单元 `dispose()` 时可能还要落一次外部调用
+ * （落库、通知、上报），客户端必须先活着。
+ *
  * **`services` 额外有逐单元生命周期**：
  * - 单元之间**不得相互依赖**（`services` 的 ctx 没有 `services` 字段，编译期禁止）；
  * - `init` 按**对象声明序**，`dispose` **逆序**；
  * - services 阶段内部**先 flush `ctx.disposer`**（构造期注册的清理），再逐单元 `dispose`。
  *
- * `middlewares` 按数组序注册；它只有 `disposer`，没有逐单元生命周期。
+ * `middlewares` 按**对象键序**注册；它只有 `disposer`，没有逐单元生命周期。
  */
-export const SERVICES_STAGE = 'services';
+export const RESOURCES_STAGE = 'resources';
 export const CONFIG_STAGE = 'config';
+export const CLIENTS_STAGE = 'clients';
+export const SERVICES_STAGE = 'services';
 export const MIDDLEWARES_STAGE = 'middlewares';
 export const ROUTERS_STAGE = 'routers';
-export const RESOURCES_STAGE = 'resources';
 /** `middlewares` 的**注册期日志**阶段标签（与生命周期阶段同名） */
 export const MIDDLEWARES_LOG_STAGE = MIDDLEWARES_STAGE;
 /** 生命周期相位（逐单元日志字段 `phase`） */
@@ -30,17 +34,16 @@ function isObject(value) {
 /**
  * `services` 有效名字：**对象键即单元名**（N1 §4：没有 `name` 字段）。
  */
-export function serviceUnitName(key) {
+function serviceUnitName(key) {
     return key;
 }
 /**
- * `middlewares` 日志名字：`unit.name ?? '<service>:middleware[<index>]'`（仅用于注册期日志）。
+ * `middlewares` 日志名字：**对象键即单元名**（与 `services` 同口径）。
+ *
+ * 键为空串时退路 `<service>:middleware`（仅用于注册期日志，不影响注册序）。
  */
-export function middlewareUnitName(service, unit, index) {
-    if (isObject(unit) && typeof unit.name === 'string' && unit.name.length > 0) {
-        return unit.name;
-    }
-    return `${service}:middleware[${index}]`;
+export function middlewareUnitName(service, key) {
+    return key.length > 0 ? key : `${service}:middleware`;
 }
 async function callInit(unit) {
     if (isObject(unit) && typeof unit.init === 'function') {
@@ -85,7 +88,7 @@ export async function initServiceUnits(params) {
 /**
  * 关闭序：`services` 按声明序**逆序**逐项 `dispose?.()`。
  */
-export function buildDisposeOrder(params) {
+function buildDisposeOrder(params) {
     const steps = [];
     for (const key of Object.keys(params.services ?? {}).reverse()) {
         steps.push(() => runLifecycleUnit(params, serviceUnitName(key), params.services?.[key], LIFECYCLE_PHASE_DISPOSE));

package/output/{app → core/boot}/shutdown.d.ts

@@ -2,20 +2,22 @@
  * 固定关闭步（N1 §5）——**顺序写死在数组里**。
  *
  * `disposer` 是所有槽位 ctx 的标配：每个阶段一个 `Disposer`，在**创建处**注册释放。
- * 关闭时按阶段**逆序 flush**：`routers → middlewares → services → config → resources`
+ * 关闭时按阶段**逆序 flush**：`routers → middlewares → services → clients → config → resources`
  * （后创建的先销毁；Prisma / Redis 这类资源**最后**才断）。
  *
  * `services` 阶段内部保持既有语义：先 flush 自己的 `disposer`（原 `stopProducers`），
  * 再 `disposeServices`（单元**逆序** `dispose`）。配置失效通道已删除，故没有 `unsubscribeConfig` 步。
  *
- * 固定六步：`flushRouters` → `flushMiddlewares` → `flushServices` → `disposeServices`
- * → `flushConfig` → `flushResources`。
+ * `clients` 排在 `services` **之后**：服务单元 `dispose()` 时可能还要落一次外部调用。
+ *
+ * 固定七步：`flushRouters` → `flushMiddlewares` → `flushServices` → `disposeServices`
+ * → `flushClients` → `flushConfig` → `flushResources`。
  *
  * 每步失败记日志、不阻断后续，最后聚合上报。
  */
-export declare const SHUTDOWN_ORDER: readonly ["flushRouters", "flushMiddlewares", "flushServices", "disposeServices", "flushConfig", "flushResources"];
-export type ShutdownStepName = (typeof SHUTDOWN_ORDER)[number];
-export type ShutdownHandles = Record<ShutdownStepName, () => void | Promise<void>>;
+declare const SHUTDOWN_ORDER: readonly ["flushRouters", "flushMiddlewares", "flushServices", "disposeServices", "flushClients", "flushConfig", "flushResources"];
+type ShutdownStepName = (typeof SHUTDOWN_ORDER)[number];
+type ShutdownHandles = Record<ShutdownStepName, () => void | Promise<void>>;
 export interface ShutdownLogger {
     error: (obj: unknown, msg?: string) => void;
 }
@@ -24,4 +26,5 @@ export interface ShutdownLogger {
  * （避免「一步报错导致后面资源没关」）。
  */
 export declare function runShutdown(handles: ShutdownHandles, log: ShutdownLogger): Promise<void>;
+export {};
 //# sourceMappingURL=shutdown.d.ts.map

package/output/core/boot/shutdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["../../../source/core/boot/shutdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,QAAA,MAAM,cAAc,oIAQV,CAAA;AAEV,KAAK,gBAAgB,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAA;AAEvD,KAAK,eAAe,GAAG,MAAM,CAAC,gBAAgB,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;AAE3E,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CAC5C;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAe9F"}

package/output/{app → core/boot}/shutdown.js

@@ -2,22 +2,25 @@
  * 固定关闭步（N1 §5）——**顺序写死在数组里**。
  *
  * `disposer` 是所有槽位 ctx 的标配：每个阶段一个 `Disposer`，在**创建处**注册释放。
- * 关闭时按阶段**逆序 flush**：`routers → middlewares → services → config → resources`
+ * 关闭时按阶段**逆序 flush**：`routers → middlewares → services → clients → config → resources`
  * （后创建的先销毁；Prisma / Redis 这类资源**最后**才断）。
  *
  * `services` 阶段内部保持既有语义：先 flush 自己的 `disposer`（原 `stopProducers`），
  * 再 `disposeServices`（单元**逆序** `dispose`）。配置失效通道已删除，故没有 `unsubscribeConfig` 步。
  *
- * 固定六步：`flushRouters` → `flushMiddlewares` → `flushServices` → `disposeServices`
- * → `flushConfig` → `flushResources`。
+ * `clients` 排在 `services` **之后**：服务单元 `dispose()` 时可能还要落一次外部调用。
+ *
+ * 固定七步：`flushRouters` → `flushMiddlewares` → `flushServices` → `disposeServices`
+ * → `flushClients` → `flushConfig` → `flushResources`。
  *
  * 每步失败记日志、不阻断后续，最后聚合上报。
  */
-export const SHUTDOWN_ORDER = [
+const SHUTDOWN_ORDER = [
     'flushRouters',
     'flushMiddlewares',
     'flushServices',
     'disposeServices',
+    'flushClients',
     'flushConfig',
     'flushResources',
 ];

package/output/core/boot/signal.d.ts

@@ -0,0 +1,13 @@
+import type { LoggerLike } from '../types.js';
+import type { FastifyInstance } from 'fastify';
+/**
+ * 内置信号处理（设计 §7.1 `activate` 尾部 / §7.2）。
+ *
+ * `SIGTERM` / `SIGINT` / `uncaughtException` / `unhandledRejection` ⇒ `app.close()`（触发 `onClose`
+ * 的关闭 6 步）⇒ `process.exit(0/1)`。**只有 `startServer` 装信号处理**（它一定 `listen`）；
+ * `createTestServer` 不装——它跑在测试进程里，退出由测试框架决定。
+ *
+ * @returns detach 函数（移除本次注册的监听器）；`startServer` 已把它挂到 `onClose` 上
+ */
+export declare function attachSignalHandlers(app: FastifyInstance, log: LoggerLike): () => void;
+//# sourceMappingURL=signal.d.ts.map

package/output/core/boot/signal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal.d.ts","sourceRoot":"","sources":["../../../source/core/boot/signal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,UAAU,GAAG,MAAM,IAAI,CA2CtF"}

package/output/{app → core/boot}/signal.js

@@ -2,9 +2,10 @@
  * 内置信号处理（设计 §7.1 `activate` 尾部 / §7.2）。
  *
  * `SIGTERM` / `SIGINT` / `uncaughtException` / `unhandledRejection` ⇒ `app.close()`（触发 `onClose`
- * 的关闭 6 步）⇒ `process.exit(0/1)`。**仅 `listen: true` 时装信号处理**。
+ * 的关闭 6 步）⇒ `process.exit(0/1)`。**只有 `startServer` 装信号处理**（它一定 `listen`）；
+ * `createTestServer` 不装——它跑在测试进程里，退出由测试框架决定。
  *
- * @returns detach 函数（移除本次注册的监听器）
+ * @returns detach 函数（移除本次注册的监听器）；`startServer` 已把它挂到 `onClose` 上
  */
 export function attachSignalHandlers(app, log) {
     let closing = false;

package/output/core/boot/steps.d.ts

@@ -0,0 +1,107 @@
+import { Disposer } from '@taicode/common-base';
+import type { ConfigAccess } from './context.js';
+import type { ConfigEnv } from '../env.js';
+import type { AppInstance, ClientsView, ErrorClassifier, LoggerLike, ResourcesView, Server } from '../types.js';
+import type { FastifyInstance } from 'fastify';
+/**
+ * 装配**步料**（不是装配流程）。
+ *
+ * `startServer` / `generateOpenApi` 各自在 `start.ts` / `openapi.ts` 里写明自己的步序——
+ * 这里只放「一步」的实现，**不含任何 `phase` / `mode` / 跳过集**。哪个入口跑哪几步，
+ * 在入口文件里一眼可见，不需要在数据结构和分支之间来回对照。
+ */
+/** 每个阶段一个 `Disposer`（创建与释放同处一地；关闭时按阶段逆序 flush） */
+export interface StageDisposers {
+    resources: Disposer;
+    config: Disposer;
+    clients: Disposer;
+    services: Disposer;
+    middlewares: Disposer;
+    routers: Disposer;
+}
+/** 一次装配的**运行期上下文**（步料之间传递的、不放公共类型里的东西） */
+export interface BootContext<R, C, CL, S> {
+    server: Server<R, C, CL, S>;
+    env: ConfigEnv;
+    /** 原生 Fastify 实例（对外返回的就是它） */
+    app: FastifyInstance;
+    /** 同一实例的框架视图（`request.ctx` 等类型增强的载体） */
+    instance: AppInstance;
+    log: LoggerLike;
+    /** 身份块的 `service`（日志标签用） */
+    service: string;
+    /** `config` 槽位的**读取能力**（出 spec 路径未产出 → `read()` 抛错） */
+    configAccess: ConfigAccess<C>;
+    disposers: StageDisposers;
+}
+/** 建 app + 六个阶段 `Disposer`（两个入口的**第一步**，内容完全相同） */
+export declare function createBootContext<R, C, CL, S>(server: Server<R, C, CL, S>, env: ConfigEnv): BootContext<R, C, CL, S>;
+/**
+ * 出文档用的上下文：**同一个 `BootContext` 形状，但实例是最小 Fastify**（无 logger /
+ * 无 requestId / 无 trustProxy，见 `createDocumentFastify`）。
+ *
+ * 形状不变是刻意的——`buildResources` / `registerRouters` 这些单步实现
+ * 因此**不需要知道自己在哪个入口跑**，轻量只体现在「实例怎么造」和「跑哪几步」上。
+ */
+export declare function createDocumentContext<R, C, CL, S>(server: Server<R, C, CL, S>, env: ConfigEnv): BootContext<R, C, CL, S>;
+/**
+ * 取**已加载**配置的访问器（框架内置单元消费配置的唯一入口）。
+ *
+ * 出 spec 路径下 `config` 槽位未产出，读到即抛 `CONFIG_UNAVAILABLE`——
+ * 「构造期不得读配置」因此有运行期护栏，而不只是文档约定。
+ */
+export declare function createConfigReader<C>(configAccess: ConfigAccess<C>): (key: string) => unknown;
+export interface ResourceBuildResult<R> {
+    /** 剔除了「编译期静态关闭」（值为 `false`）的键 */
+    resources: ResourcesView<R>;
+    /** 各资源注册的分类器合成结果（零个 = `undefined`） */
+    classifyResourceError: ErrorClassifier | undefined;
+}
+/** `resources(ctx)`：**只构造、不建连**（仅运行期入口执行） */
+export declare function buildResources<R, C, CL, S>(ctx: BootContext<R, C, CL, S>): Promise<ResourceBuildResult<R>>;
+/**
+ * core 装配：`identity` → `schema`（+ 路由契约守卫）→ `requestContext` → `cookie` →
+ * `response` → `openapi` → `requestId` 回吐。
+ *
+ * 仅运行期入口执行——它装的是「请求怎么被处理」，构建期没有请求。
+ */
+export declare function registerCoreStep<R, C, CL, S>(ctx: BootContext<R, C, CL, S>, classifyResourceError?: ErrorClassifier): Promise<void>;
+/**
+ * **文档 core** 装配：`identity` → `schema`（+ 路由契约守卫）→ `openapi`。
+ *
+ * 只装「把 zod schema 转成 OpenAPI 文档」所需的四件事。`requestContext` / `cookie` /
+ * `response` / `requestId` 不装：它们影响的是请求怎么被处理，而构建期一条请求都不会发。
+ * 守卫仍必须在——文档就是权限目录（§10-26）。
+ */
+export declare function registerDocumentCoreStep<R, C, CL, S>(ctx: BootContext<R, C, CL, S>): Promise<void>;
+/** `config(ctx)`：**仅运行期**（出 spec 路径不跑） */
+export declare function buildConfig<R, C, CL, S>(ctx: BootContext<R, C, CL, S>, resources: ResourcesView<R>): Promise<void>;
+/**
+ * `clients(ctx)`：**仅运行期**（需要 `config`，出 spec 路径不跑）。
+ *
+ * 外部客户端的地址 / 凭证来自业务配置，所以它必须排在 `config` 之后；
+ * 又因为多个 service 要共享同一份实例（而 `services` 之间禁止互依），所以它必须排在 `services` 之前。
+ */
+export declare function buildClients<R, C, CL, S>(ctx: BootContext<R, C, CL, S>, resources: ResourcesView<R>): Promise<ClientsView<CL>>;
+/** `services(ctx)`：**只构造**（`init()` 由调用方决定跑不跑） */
+export declare function buildServices<R, C, CL, S>(ctx: BootContext<R, C, CL, S>, resources: ResourcesView<R>, clients: ClientsView<CL>): Promise<Awaited<S>>;
+/** `middlewares(ctx)`：按**对象键序**逐个 `register(app)`（两个入口都执行） */
+export declare function registerMiddlewares<R, C, CL, S>(ctx: BootContext<R, C, CL, S>, services: Awaited<S>, clients: ClientsView<CL>): Promise<void>;
+/** 框架内置系统路由（`/` / `/health` / `/system/health` / `/system/openapi` / `/system/info`） */
+export declare function registerSystemRoutesStep<R, C, CL, S>(ctx: BootContext<R, C, CL, S>, services: Awaited<S>): void;
+/** `routers(ctx)`：业务路由（文档与权限目录都从这里来） */
+export declare function registerRouters<R, C, CL, S>(ctx: BootContext<R, C, CL, S>, services: Awaited<S>, clients: ClientsView<CL>): Promise<void>;
+/** 系统路由（出文档路径：不构造 `services`） */
+export declare function registerDocumentSystemRoutesStep<R, C, CL, S>(ctx: BootContext<R, C, CL, S>): void;
+/** 业务路由（出文档路径：不构造 `services` / `clients`；这是文档内容的**唯一**业务来源） */
+export declare function registerDocumentRoutersStep<R, C, CL, S>(ctx: BootContext<R, C, CL, S>): Promise<void>;
+/**
+ * 关闭流程（固定七步，顺序写在 `shutdown.ts` 里，不可覆盖）。
+ *
+ * 由 `onClose` 钩子触发；spec 入口在 `finally` 里 `close()` 同样会走它——
+ * 「构造了什么就释放什么」，构建脚本不再留下未释放的资源。
+ */
+export declare function buildShutdownFlow<R, C, CL, S>(ctx: BootContext<R, C, CL, S>, services: Awaited<S>): () => Promise<void>;
+/** 把关闭流程挂到 `onClose`（两个入口都挂：谁 `close()` 谁负责释放） */
+export declare function installShutdownHook<R, C, CL, S>(ctx: BootContext<R, C, CL, S>, services: Awaited<S>): void;
+//# sourceMappingURL=steps.d.ts.map