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

package/dist/index.d.ts

@@ -2,14 +2,16 @@ import * as _h_ai_core from '@h-ai/core';
 import { HaiResult, ValidationFormError } from '@h-ai/core';
 import { AIFunctions, AudioWsStartMessage, AudioFormat } from '@h-ai/ai';
 import { AnyContractRouter, OpenAPI } from '@orpc/contract';
-import { ProcedureHandler, ErrorMap, Meta, ProcedureHandlerOptions, ORPCErrorConstructorMap, Router, ContractRouter, Context, ContractProcedure, InferSchemaInput, InferSchemaOutput, UnlaziedRouter } from '@orpc/server';
-import { a as ServSession, S as ServContext, b as ServIam, R as RefreshCookieConfig, C as CreateServContext, c as ServRequestMetadata, p as parseRequestContext, d as buildAuthContextFactory } from './serv-context-CWzyrsdq.js';
-export { e as CreateServContextInput, N as NativeRefreshTokenTransportConfig, f as RefreshTokenPair } from './serv-context-CWzyrsdq.js';
+import { ProcedureHandler, ErrorMap, Meta, ProcedureHandlerOptions, ORPCErrorConstructorMap, Router } from '@orpc/server';
+import { a as ServSession, S as ServContext, b as ServIam, R as RefreshCookieConfig, C as CreateServContext, c as ServRequestMetadata, p as parseRequestContext, d as buildAuthContextFactory } from './serv-context-C48WdBcd.js';
+export { e as CreateServContextInput, N as NativeRefreshTokenTransportConfig, f as RefreshTokenPair } from './serv-context-C48WdBcd.js';
 import { MiddlewareHandler } from 'hono';
 import { z, ZodType } from 'zod';
-import { CryptoFunctions, TransportKeyStore } from '@h-ai/crypto';
+import { TransportServerKeyRing, CryptoFunctions, TransportKeyStore } from '@h-ai/crypto';
 import { ServerType } from '@hono/node-server';
 import { AddressInfo } from 'node:net';
+import { i as implement } from './serv-router-BX8hgYxo.js';
+export { A as AuthenticatedServContext, S as ServImplementer, a as ServRouteHandler, b as ServRoutePath, c as ServRouterBuilder } from './serv-router-BX8hgYxo.js';
 import { StorageFunctions } from '@h-ai/storage';
 
 /**
@@ -26,7 +28,18 @@ import { StorageFunctions } from '@h-ai/storage';
  * @module features/serv-feature-audio
  */
 
-/** 语音 WebSocket 接入依赖。 */
+/**
+ * 语音 WebSocket 接入依赖。
+ *
+ * @example
+ * ```ts
+ * // 模块内部上下文：示例复用当前声明所在模块的实际绑定。
+ * function withAudioLimits(deps: AudioWsDeps): AudioWsDeps {
+ *   return { ...deps, maxSessionMs: 60000, maxBufferedBytes: 1024 * 1024 }
+ * }
+ * // verifyTicket 必须原子消费共享的一次性票据，不能仅解析客户端身份。
+ * ```
+ */
 interface AudioWsDeps {
     /** AI 服务对象的语音能力（`ai.audio`）。 */
     readonly ai: Pick<AIFunctions, 'audio'>;
@@ -59,21 +72,67 @@ interface AudioWsDeps {
  * @module pipelines/serv-pipeline-types
  */
 
-/** Serv 层 Hono middleware。 */
+/**
+ * Serv 层 Hono middleware。
+ *
+ * @example
+ * ```ts
+ * import type { ServMiddleware } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const middleware: ServMiddleware = async (context, next) => {
+ *   context.header('X-App-Version', '1')
+ *   await next()
+ * }
+ * ```
+ */
 type ServMiddleware = MiddlewareHandler;
 /**
  * Hono middleware 工厂类型。
  *
  * - 无配置 middleware：`ServMiddlewareFactory<void>`
  * - 带配置 middleware：`ServMiddlewareFactory<MyConfig>`
+ *
+ * @example
+ * ```ts
+ * import type { ServMiddlewareFactory } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const createTrace: ServMiddlewareFactory<{ header: string }> = config => async (context, next) => {
+ *   context.header(config.header, 'enabled')
+ *   await next()
+ * }
+ * const middleware = createTrace({ header: 'X-Trace-Enabled' })
+ * ```
  */
 type ServMiddlewareFactory<TConfig = void> = [TConfig] extends [void] ? () => ServMiddleware : (config: TConfig) => ServMiddleware;
 /**
  * 使用 oRPC 公开 `ProcedureHandler` 定义的 HaiResult procedure handler。
  *
  * handler options 完整保留 oRPC 的路径、procedure、signal 与错误构造器信息。
+ *
+ * @example
+ * ```ts
+ * import type { ServProcedureOptions } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * function requestId(options: ServProcedureOptions<{ id: string }>) {
+ *   return { id: options.input.id, requestId: options.context.requestId }
+ * }
+ * ```
  */
 type ServProcedureOptions<TInput = unknown, TContext extends ServContext = ServContext> = ProcedureHandlerOptions<TContext, TInput, ORPCErrorConstructorMap<ErrorMap>, Meta>;
+/**
+ * 基于 oRPC 真实 options 的 HaiResult handler；领域失败返回错误分支，异常由 route 包装收口。
+ *
+ * @example
+ * ```ts
+ * import type { ServProcedureHandler } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const handler: ServProcedureHandler<{ id: string }, { id: string }> = async ({ input }) => ({ success: true, data: { id: input.id } })
+ * ```
+ */
 type ServProcedureHandler<TInput, TOutput, TContext extends ServContext = ServContext> = ProcedureHandler<TContext, TInput, HaiResult<TOutput>, ErrorMap, Meta>;
 
 /**
@@ -84,41 +143,125 @@ type ServProcedureHandler<TInput, TOutput, TContext extends ServContext = ServCo
  * @module serv-config
  */
 
-/** 服务器监听配置（对应 `config/_serv.yml` 的 `server`）。 */
+/**
+ * 服务器监听配置（对应 `config/_serv.yml` 的 `server`）。
+ *
+ * @example
+ * ```ts
+ * import type { ServServerConfig } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const config: ServServerConfig = { host: '127.0.0.1', port: 3000 }
+ * const bindAddress = config.host
+ * ```
+ */
 interface ServServerConfig {
     readonly host: string;
     readonly port: number;
 }
-/** `config/_serv.yml` 中的服务器监听输入类型。 */
+/**
+ * `config/_serv.yml` 中的服务器监听输入类型。
+ *
+ * @example
+ * ```ts
+ * import type { ServServerConfigInput } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const input: ServServerConfigInput = { port: 3000 }
+ * // HOST/PORT 的环境覆盖由配置解析完成后传给 listen。
+ * ```
+ */
 type ServServerConfigInput = Partial<ServServerConfig>;
-/** OpenAPI JSON endpoint 配置。 */
+/**
+ * OpenAPI JSON endpoint 配置。
+ *
+ * @example
+ * ```ts
+ * import type { ServOpenAPIHttpConfig } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const openapi: ServOpenAPIHttpConfig = { path: '/openapi.json' }
+ * // 文档仅在 createApp.http 显式启用时挂载。
+ * ```
+ */
 interface ServOpenAPIHttpConfig {
     readonly path: `/${string}`;
 }
-/** 文档页面 endpoint 配置。 */
+/**
+ * 文档页面 endpoint 配置。
+ *
+ * @example
+ * ```ts
+ * import type { ServDocsHttpConfig } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const docs: ServDocsHttpConfig = { path: '/docs', requireAuth: true }
+ * ```
+ */
 interface ServDocsHttpConfig {
     readonly path: `/${string}`;
     readonly requireAuth?: boolean;
 }
-/** 健康检查 endpoint 配置。 */
+/**
+ * 健康检查 endpoint 配置。
+ *
+ * @example
+ * ```ts
+ * import type { ServHealthHttpConfig } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const health: ServHealthHttpConfig = { path: '/health', readyPath: '/ready' }
+ * ```
+ */
 interface ServHealthHttpConfig {
     readonly path: `/${string}`;
     readonly readyPath?: `/${string}`;
 }
-/** 内部 RPC endpoint 配置。 */
+/**
+ * 内部 RPC endpoint 配置。
+ *
+ * @example
+ * ```ts
+ * import type { ServRpcHttpConfig } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const rpc: ServRpcHttpConfig = { prefix: '/rpc', access: 'loopback' }
+ * // 缺少可信连接信息时拒绝；跨节点来源通过明确网关/网络策略控制。
+ * ```
+ */
 interface ServRpcHttpConfig {
     readonly prefix: `/${string}`;
     readonly access: 'loopback' | 'private-network' | 'gateway-only';
     readonly gatewayHeader?: string;
     readonly gatewaySecret?: string;
 }
-/** 传输加密运行时配置（对应 `config/_serv.yml`）。 */
+/**
+ * 传输加密运行时配置（对应 `config/_serv.yml`）。
+ *
+ * @example
+ * ```ts
+ * import type { ServTransportRuntimeConfig } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const transport: ServTransportRuntimeConfig = { keyExchangePath: '/_hai/key-exchange', excludePaths: ['/health'] }
+ * // 仅路径配置；真正启用还需私有 keyring 与共享 keyStore。
+ * ```
+ */
 interface ServTransportRuntimeConfig {
     readonly keyExchangePath: `/${string}`;
     readonly excludePaths: readonly `/${string}`[];
-    readonly maxClients: number;
 }
-/** `config/_serv.yml` 中可序列化的跨端 CORS 配置。 */
+/**
+ * `config/_serv.yml` 中可序列化的跨端 CORS 配置。
+ *
+ * @example
+ * ```ts
+ * import type { ServCorsRuntimeConfig } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const cors: ServCorsRuntimeConfig = { origin: 'https://app.example.com', allowedHeaders: ['Authorization', 'Content-Type'], exposedHeaders: [], credentials: true }
+ * ```
+ */
 interface ServCorsRuntimeConfig {
     readonly origin?: string;
     readonly nativeOrigins?: string;
@@ -126,7 +269,17 @@ interface ServCorsRuntimeConfig {
     readonly exposedHeaders: readonly string[];
     readonly credentials: boolean;
 }
-/** ServHttpApp 的 HTTP 挂载配置。 */
+/**
+ * ServHttpApp 的 HTTP 挂载配置。
+ *
+ * @example
+ * ```ts
+ * import type { ServHttpConfig } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const http: ServHttpConfig = { trustedProxies: [], apiPrefix: '/api/v1', openapi: false, docs: false, health: { path: '/health' }, rpc: false }
+ * ```
+ */
 interface ServHttpConfig {
     /** 可信任的连接代理 IP/CIDR；默认空数组，不采纳转发头。 */
     readonly trustedProxies: readonly string[];
@@ -136,22 +289,65 @@ interface ServHttpConfig {
     readonly health: false | ServHealthHttpConfig;
     readonly rpc: false | ServRpcHttpConfig;
 }
-/** `config/_serv.yml` 的顶层配置结构。 */
+/**
+ * `config/_serv.yml` 的顶层配置结构。
+ *
+ * @example
+ * ```ts
+ * import type { ServConfig } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * import { ServConfigSchema } from '@h-ai/serv'
+ *
+ * const config: ServConfig = ServConfigSchema.parse({ server: { host: '127.0.0.1', port: 3000 } })
+ * const port = config.server.port
+ * ```
+ */
 interface ServConfig {
     readonly server: ServServerConfig;
     readonly http: ServHttpConfig;
     readonly cors: ServCorsRuntimeConfig;
     readonly transport: false | ServTransportRuntimeConfig;
 }
-/** `config/_serv.yml` 中的 CORS 输入类型。 */
+/**
+ * `config/_serv.yml` 中的 CORS 输入类型。
+ *
+ * @example
+ * ```ts
+ * import type { ServCorsRuntimeConfigInput } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const input: ServCorsRuntimeConfigInput = { origin: 'https://app.example.com', credentials: true }
+ * ```
+ */
 type ServCorsRuntimeConfigInput = Partial<ServCorsRuntimeConfig>;
-/** `config/_serv.yml` 中的传输加密输入类型。 */
+/**
+ * `config/_serv.yml` 中的传输加密输入类型。
+ *
+ * @example
+ * ```ts
+ * import type { ServTransportRuntimeConfigInput } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const input: ServTransportRuntimeConfigInput = { keyExchangePath: '/_hai/key-exchange' }
+ * // 此输入不包含私钥；私有 Secret 仅在服务端运行时装配。
+ * ```
+ */
 type ServTransportRuntimeConfigInput = Partial<{
     readonly keyExchangePath: `/${string}`;
     readonly excludePaths: readonly `/${string}`[];
-    readonly maxClients: number;
 }>;
-/** `serv.createApp` 接受的 HTTP 配置入参类型。 */
+/**
+ * `serv.createApp` 接受的 HTTP 配置入参类型。
+ *
+ * @example
+ * ```ts
+ * import type { ServHttpConfigInput } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const http: ServHttpConfigInput = { apiPrefix: '/api/v2', trustedProxies: ['192.0.2.0/24'], docs: false }
+ * ```
+ */
 type ServHttpConfigInput = Partial<{
     readonly trustedProxies: readonly string[];
     readonly apiPrefix: `/api/${string}`;
@@ -160,14 +356,40 @@ type ServHttpConfigInput = Partial<{
     readonly health: false | Partial<ServHealthHttpConfig>;
     readonly rpc: false | Partial<ServRpcHttpConfig>;
 }>;
-/** `config/_serv.yml` 的顶层输入类型。 */
+/**
+ * `config/_serv.yml` 的顶层输入类型。
+ *
+ * @example
+ * ```ts
+ * import type { ServConfigInput } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * import { ServConfigSchema } from '@h-ai/serv'
+ *
+ * const input: ServConfigInput = { http: { apiPrefix: '/api/v2' }, transport: false }
+ * const parsed = ServConfigSchema.safeParse(input)
+ * if (!parsed.success) throw new Error('Invalid service configuration')
+ * ```
+ */
 interface ServConfigInput {
     readonly server?: ServServerConfigInput;
     readonly http?: ServHttpConfigInput;
     readonly cors?: ServCorsRuntimeConfigInput;
     readonly transport?: false | ServTransportRuntimeConfigInput;
 }
-/** `config/_serv.yml` 对应的配置 Schema。 */
+/**
+ * `config/_serv.yml` 对应的配置 Schema。
+ *
+ * @example
+ * ```ts
+ * import { ServConfigSchema } from '@h-ai/serv'
+ *
+ * const parsed = ServConfigSchema.safeParse({ http: { apiPrefix: '/api/v1', docs: false } })
+ * if (parsed.success) {
+ *   const host = parsed.data.server.host
+ * }
+ * ```
+ */
 declare const ServConfigSchema: z.ZodPipe<z.ZodObject<{
     server: z.ZodOptional<z.ZodObject<{
         host: z.ZodDefault<z.ZodString>;
@@ -208,7 +430,6 @@ declare const ServConfigSchema: z.ZodPipe<z.ZodObject<{
     transport: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
         keyExchangePath: z.ZodDefault<z.ZodCustom<`/${string}`, `/${string}`>>;
         excludePaths: z.ZodDefault<z.ZodArray<z.ZodCustom<`/${string}`, `/${string}`>>>;
-        maxClients: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>]>>;
 }, z.core.$strip>, z.ZodTransform<{
     server: ServServerConfig;
@@ -251,7 +472,6 @@ declare const ServConfigSchema: z.ZodPipe<z.ZodObject<{
     transport?: false | {
         keyExchangePath: `/${string}`;
         excludePaths: `/${string}`[];
-        maxClients: number;
     } | undefined;
 }>>;
 
@@ -273,8 +493,25 @@ declare const ServConfigSchema: z.ZodPipe<z.ZodObject<{
  * @module serv-transport
  */
 
-/** {@link createApp} 的 `transport` 配置项。 */
+/**
+ * {@link createApp} 的 `transport` 配置项。
+ *
+ * @example
+ * ```ts
+ * import type { ServTransportConfig } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * import { crypto } from '@h-ai/crypto'
+ *
+ * function configure(serverKeyRing: ServTransportConfig['serverKeyRing'], keyStore: ServTransportConfig['keyStore']): ServTransportConfig {
+ *   return { crypto, serverKeyRing, keyStore }
+ * }
+ * // 私有 keyring 跨节点共享并支持轮换；生产 keyStore 原子消费重放标识，不能用进程 Map。
+ * ```
+ */
 interface ServTransportConfig {
+    /** 受管服务端密钥环，仅运行时从私有 Secret 注入。 */
+    readonly serverKeyRing: TransportServerKeyRing;
     /**
      * crypto 服务实例。serv 通过 `crypto.transport.createServer()` 创建
      * 传输加密管理器，并使用 `crypto.transport.protocol` 中的协议常量。
@@ -290,9 +527,7 @@ interface ServTransportConfig {
      */
     readonly excludePaths?: readonly string[];
     /** 共享客户端公钥存储；适用于多节点部署。 */
-    readonly keyStore?: TransportKeyStore;
-    /** 服务端可缓存的客户端公钥数量上限。默认 10000。 */
-    readonly maxClients?: number;
+    readonly keyStore: TransportKeyStore;
 }
 
 /**
@@ -319,6 +554,15 @@ interface ServTransportConfig {
  * - `path` 省略时默认挂到 `'*'`
  * - 按数组顺序注册
  * - 注册位置固定在内置 `securityHeaders` 之后、`transport` / 业务路由之前
+ *
+ * @example
+ * ```ts
+ * import type { ServMiddlewareMount } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const mount: ServMiddlewareMount = { path: '/api/v1/*', middleware: serv.cors({ origin: 'https://app.example.com' }) }
+ * // middleware 在 transport 之前运行；短路响应不会经过传输加密。
+ * ```
  */
 interface ServMiddlewareMount {
     readonly path?: string;
@@ -330,6 +574,17 @@ interface ServMiddlewareMount {
  * Hono 是当前内部实现细节，应用代码只应依赖此最小接口：
  * - `fetch`：部署到 Fetch-first 运行时或交给 `serv.listen()`。
  * - `request`：测试 / 本地直连时发起 in-process 请求，避免消费方 import Hono。
+ *
+ * @example
+ * ```ts
+ * import type { ServHttpApp } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * async function health(app: ServHttpApp): Promise<boolean> {
+ *   const response = await app.request('/health')
+ *   return response.ok
+ * }
+ * ```
  */
 interface ServHttpApp {
     readonly fetch: (request: Request, metadata?: ServRequestMetadata) => Response | Promise<Response>;
@@ -347,10 +602,20 @@ interface ServHttpApp {
  * - **`refreshCookie`**（可选）：浏览器默认用 httpOnly cookie；受信原生客户端可配置 body 通道。与 `iam` 正交：
  *   `iam` 决定 *谁* 验证 token，`refreshCookie` 决定 refresh token *怎么* 传输。
  *
- * - **`verifyToken`**（高级）：不使用 IAM 模块的逆脱口。优先于 `iam.auth.verifyToken`。
+ * - **`verifyToken`**（高级）：不使用 IAM 模块的覆盖入口。优先于 `iam.auth.verifyToken`。
  *
  * - **`createContext`**（高级）：完全接管上下文构造，设置后 serv **不再**自动填充 session，
  *   由调用方负责。
+ *
+ * @example
+ * ```ts
+ * import type { CreateServAppOptions } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * function mount<TContract extends Parameters<typeof serv.createApp>[0]['contract'], TProcedures extends Parameters<typeof serv.createApp>[0]['procedures']>(options: CreateServAppOptions<TContract, TProcedures>) {
+ *   return serv.createApp(options)
+ * }
+ * ```
  */
 interface CreateServAppOptions<TContract extends AnyContractRouter, TProcedures extends Router<AnyContractRouter, ServContext>> {
     readonly contract: TContract;
@@ -389,14 +654,10 @@ interface CreateServAppOptions<TContract extends AnyContractRouter, TProcedures
     readonly createContext?: CreateServContext;
     /**
      * 启用传输加密（opt-in）。提供后 serv 自动：
-     * 1. 调用 `crypto.transport.createServer()` 创建管理器
+     * 1. 使用显式 serverKeyRing / keyStore 创建受管传输管理器
      * 2. 在 oRPC 路由之前挂载中间件，自动解密请求 / 加密响应
      * 3. 在 `${apiPrefix}${keyExchangePath}` 暴露 POST 密钥协商端点
      *
-     * @example
-     * ```ts
-     * serv.createApp({ contract, procedures, transport: { crypto } })
-     * ```
      */
     readonly transport?: ServTransportConfig;
     /**
@@ -407,14 +668,25 @@ interface CreateServAppOptions<TContract extends AnyContractRouter, TProcedures
      *
      * 需配合 `serv.listen()`（Node 适配器会自动完成 WebSocket 升级注入）。
      *
-     * @example
-     * ```ts
-     * serv.createApp({ contract, procedures, iam, audio: { ai, verifyTicket, authorize } })
-     * ```
      */
     readonly audio?: ServAudioConfig;
 }
-/** `serv.createApp()` 的语音 WebSocket 接入配置。 */
+/**
+ * `serv.createApp()` 的语音 WebSocket 接入配置。
+ *
+ * @example
+ * ```ts
+ * import type { ServAudioConfig } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * import { ai } from '@h-ai/ai'
+ *
+ * function configureAudio(verifyTicket: ServAudioConfig['verifyTicket']): ServAudioConfig {
+ *   return { ai, verifyTicket, preAuthTimeoutMs: 3000, maxSessionMs: 60000 }
+ * }
+ * // 应用实现 verifyTicket：原子消费共享票据并返回可信 session/grant。
+ * ```
+ */
 interface ServAudioConfig {
     /** AI 服务对象（提供 `ai.audio` 领域能力）。 */
     readonly ai: AudioWsDeps['ai'];
@@ -453,7 +725,18 @@ interface ServAudioConfig {
     /** 发送缓冲高水位（字节，默认 8 MiB）：`ws.bufferedAmount` 超过即以领域错误关闭慢客户端。 */
     readonly maxSendBufferBytes?: number;
 }
-/** Audio ticket 绑定的能力授权（消费时原样返回，供服务端交叉校验 start 帧）。 */
+/**
+ * Audio ticket 绑定的能力授权（消费时原样返回，供服务端交叉校验 start 帧）。
+ *
+ * @example
+ * ```ts
+ * import type { AudioTicketGrant } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const grant: AudioTicketGrant = { operation: 'synthesize', model: 'speech-model', sessionId: 'session-1' }
+ * // 签发时绑定；start 帧不能覆盖服务端核准的模型与操作。
+ * ```
+ */
 interface AudioTicketGrant {
     /** 允许的操作 */
     readonly operation?: 'transcribe' | 'synthesize';
@@ -464,14 +747,38 @@ interface AudioTicketGrant {
     /** 应用自定义绑定字段 */
     readonly [key: string]: unknown;
 }
-/** Audio ticket 验证结果：IAM 会话 + 可选能力授权。 */
+/**
+ * Audio ticket 验证结果：IAM 会话 + 可选能力授权。
+ *
+ * @example
+ * ```ts
+ * import type { AudioTicketVerification } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * function verified(session: AudioTicketVerification['session']): AudioTicketVerification {
+ *   return { session, grant: { operation: 'transcribe' } }
+ * }
+ * // session 必须来自成功消费的可信票据，不能从客户端 JSON 直接构造。
+ * ```
+ */
 interface AudioTicketVerification {
     /** IAM 会话摘要 */
     readonly session: ServSession;
     /** 票据绑定的能力授权（如有） */
     readonly grant?: AudioTicketGrant;
 }
-/** Audio WebSocket 经应用授权后允许生效的服务端参数。 */
+/**
+ * Audio WebSocket 经应用授权后允许生效的服务端参数。
+ *
+ * @example
+ * ```ts
+ * import type { AuthorizedAudioRequest } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const request: AuthorizedAudioRequest = { operation: 'synthesize', format: 'mp3' }
+ * // model/voice/instruction 只有经应用 authorize 确认后才生效。
+ * ```
+ */
 interface AuthorizedAudioRequest {
     readonly operation: 'transcribe' | 'synthesize';
     /** 服务端允许的模型 ID；不传时使用 `ai.audio` 对应操作的默认模型。 */
@@ -482,23 +789,24 @@ interface AuthorizedAudioRequest {
     readonly sampleRate?: number;
 }
 /**
- * 创建并装配 HTTP API app。
+ * 创建并装配 HTTP app；同步校验配置和依赖，返回可交给 Node 或标准 fetch 适配器的应用。
  *
- * @param options - contract/procedures/http 三段式配置
- * @returns 可被 `serv.listen()` / `serv.toFetch()` 使用的 ServHttpApp
+ * @param options - contract、procedures、HTTP、安全和可选能力依赖
+ * @returns 不拥有业务模块生命周期的 ServHttpApp
+ * @throws 配置或必需依赖缺失时在装配阶段抛错，宿主须停止启动并清理已初始化资源。
  *
  * @example
  * ```ts
- * const app = serv.createApp({
- *   contract,
- *   procedures,
- *   http: {
- *     apiPrefix: '/api/v1',
- *     openapi: { path: '/openapi.json' },
- *     docs: { path: '/docs' },
- *   },
- * })
- * serv.listen(app, { port: 3000, host: '0.0.0.0' })
+ * import type { ServContext } from '@h-ai/serv'
+ * import { apiContract } from '@h-ai/api-contract'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const contract = apiContract.create({})
+ * const procedures = serv.implement(contract).context<ServContext>().build()
+ * const app = serv.createApp({ contract, procedures })
+ *
+ * const response = await app.request('/health')
+ * const healthy = response.ok
  * ```
  */
 declare function createApp<TContract extends AnyContractRouter, TProcedures extends Router<AnyContractRouter, ServContext>>(options: CreateServAppOptions<TContract, TProcedures>): ServHttpApp;
@@ -507,35 +815,49 @@ declare function createApp<TContract extends AnyContractRouter, TProcedures exte
  * @h-ai/serv — Fetch 适配器
  *
  * 将 ServHttpApp 包装为标准 Web `fetch(Request)` 处理函数，
- * 适用于 Cloudflare Workers、Deno、Bun 等 Fetch-first 运行时。
+ * 用于 Node 兼容宿主与客户端测试的标准 fetch 注入；部署仍须满足包的 Node API 依赖。
  * @module adapters/serv-adapter-fetch
  */
 
 /**
- * Fetch runtime handler。
+ * 标准 fetch 签名类型，供 Node 兼容宿主或客户端 in-process 测试注入。签名兼容不代表包整体不依赖 Node API，也不承诺未经验证的边缘部署。
  *
- * 兼容标准 Web `fetch` 签名 `(input, init)` —— 既可作为 Cloudflare Workers / Bun
- * 的 `fetch` 导出，也可作为 oRPC client `fetch` 选项的替代实现，让客户端在测试
- * 中直连 in-process 服务。
+ * @example
+ * ```ts
+ * import type { ServFetchHandler } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * function handle(app: Parameters<typeof serv.toFetch>[0]): ServFetchHandler {
+ *   return serv.toFetch(app)
+ * }
+ * // 兼容 fetch 签名；宿主仍须支持此包的 Node 依赖。
+ * ```
  */
 type ServFetchHandler = typeof fetch;
 /**
- * 将 ServHttpApp 转成 Fetch handler。
+ * 将应用转换为标准 fetch 签名，供 Node 兼容宿主或客户端测试注入；签名适配不代表整个包可在无 Node API 的边缘运行时加载。
  *
- * @param app - `serv.createApp()` 返回的 HTTP app
- * @returns fetch-compatible handler
+ * RequestInit 的覆盖与正文锁定/消费检查交由标准 Request 构造器处理，不修改原 Request 的字段。
+ * 取消会拒绝响应等待并传递给应用，不能撤回 handler 已产生的外部效果；响应交付后的流取消由应用消费 signal。
+ *
+ * @param app - createApp 返回的应用
+ * @returns fetch 兼容处理器
+ * @throws 返回的 Promise 可因 Request 构造错误、取消或下游异常而 reject；成功返回 Response。
  *
  * @example
  * ```ts
- * // Cloudflare Workers
- * export default { fetch: serv.toFetch(app) }
+ * import type { ServContext } from '@h-ai/serv'
+ * import { apiContract } from '@h-ai/api-contract'
+ * import { serv } from '@h-ai/serv'
  *
- * // Bun
- * Bun.serve({ fetch: serv.toFetch(app), port: 3000 })
+ * const contract = apiContract.create({})
+ * const procedures = serv.implement(contract).context<ServContext>().build()
+ * const app = serv.createApp({ contract, procedures })
  *
- * // 测试：把服务端 app 当作 fetch 注入到 client，免去 HTTP 监听
- * const client = apiClient.create(contract)
- * await client.init({ baseUrl: 'http://test', fetch: serv.toFetch(app) })
+ * const fetchHandler = serv.toFetch(app)
+ * const request = new Request('http://service.test/health')
+ * const response = await fetchHandler(request, { headers: { 'x-hai-locale': 'en-US' } })
+ * const ready = response.ok
  * ```
  */
 declare function toFetch(app: ServHttpApp): ServFetchHandler;
@@ -548,7 +870,18 @@ declare function toFetch(app: ServHttpApp): ServFetchHandler;
  * @module adapters/serv-adapter-node
  */
 
-/** Node 服务器启动配置。 */
+/**
+ * Node 服务器启动配置。
+ *
+ * @example
+ * ```ts
+ * import type { ServListenOptions } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const options: ServListenOptions = { host: '127.0.0.1', port: 3000 }
+ * // HOST/PORT 与配置文件的解析由应用显式完成后传入。
+ * ```
+ */
 interface ServListenOptions {
     /**
      * 监听端口。
@@ -578,7 +911,20 @@ interface ServListenOptions {
      */
     readonly onClose?: () => Promise<void>;
 }
-/** Node 服务运行句柄。 */
+/**
+ * Node 服务运行句柄。
+ *
+ * @example
+ * ```ts
+ * import type { ServNodeServer } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * async function stop(handle: ServNodeServer) {
+ *   await handle.close()
+ * }
+ * // close 只关闭监听句柄；业务资源由宿主生命周期关闭。
+ * ```
+ */
 interface ServNodeServer {
     /** 底层 Node.js HTTP Server 实例。 */
     readonly server: ServerType;
@@ -594,7 +940,7 @@ interface ServNodeServer {
  * 在 Node.js 中启动 ServHttpApp。
  *
  * 默认监听 `127.0.0.1:3000`；host/port 建议由应用从 `serv` 配置的 `server`
- *（支持 `HOST` / `PORT` 环境变量覆盖，环境变量高于配置文件）解析后显式传入。
+ * （支持 `HOST` / `PORT` 环境变量覆盖，环境变量高于配置文件）解析后显式传入。
  * 传入 `onClose` 后自动注册 SIGINT/SIGTERM 优雅关闭，应用层无需手动处理信号。
  *
  * @param app - `serv.createApp()` 返回的 HTTP app
@@ -603,14 +949,16 @@ interface ServNodeServer {
  *
  * @example
  * ```ts
- * // host/port 来自已解析的 serv 配置（env > 配置文件 > 默认）
- * const { server } = core.config.getOrThrow<ServConfig>('serv')
- * serv.listen(app, {
- *   host: server.host,
- *   port: server.port,
- *   onListening: info => logger.info('listening', { port: info.port }),
- *   onClose: closeApp,
- * })
+ * import type { ServContext } from '@h-ai/serv'
+ * import { apiContract } from '@h-ai/api-contract'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const contract = apiContract.create({})
+ * const procedures = serv.implement(contract).context<ServContext>().build()
+ * const app = serv.createApp({ contract, procedures })
+ *
+ * const server = serv.listen(app, { host: '127.0.0.1', port: 3000 })
+ * await server.close()
  * ```
  */
 declare function listen(app: ServHttpApp, options?: ServListenOptions): ServNodeServer;
@@ -622,7 +970,18 @@ declare function listen(app: ServHttpApp, options?: ServListenOptions): ServNode
  * @module serv-cors
  */
 
-/** serv CORS 配置。 */
+/**
+ * serv CORS 配置。
+ *
+ * @example
+ * ```ts
+ * import type { ServCorsConfig } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const config: ServCorsConfig = { origin: 'https://app.example.com', credentials: true, exposedHeaders: ['X-Request-Id'] }
+ * const middleware = serv.cors(config)
+ * ```
+ */
 interface ServCorsConfig {
     /** 允许的 origin：`'*'`、单个字符串、数组或自定义匹配函数。默认 `'*'`。 */
     readonly origin?: '*' | string | readonly string[] | ((origin: string) => boolean);
@@ -637,7 +996,17 @@ interface ServCorsConfig {
     /** 预检缓存秒数。默认 `86400`。 */
     readonly maxAge?: number;
 }
-/** 创建可复用的 CORS middleware。 */
+/**
+ * 创建可复用的 CORS middleware。
+ *
+ * @example
+ * ```ts
+ * import { serv } from '@h-ai/serv'
+ *
+ * const middleware = serv.cors({ origin: ['https://app.example.com'], credentials: true })
+ * // 生产策略由 createRuntimeSecurityPolicy 先收敛 Origin，避免误用通配符。
+ * ```
+ */
 declare function cors(config?: ServCorsConfig): ServMiddleware;
 
 /**
@@ -648,7 +1017,17 @@ declare function cors(config?: ServCorsConfig): ServMiddleware;
  * @module serv-openapi
  */
 
-/** OpenAPI spec 生成配置。 */
+/**
+ * OpenAPI spec 生成配置。
+ *
+ * @example
+ * ```ts
+ * import type { GenerateOpenAPISpecOptions } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const options: GenerateOpenAPISpecOptions = { title: 'Reports API', version: '1.0.0', apiPrefix: '/api/v1' }
+ * ```
+ */
 interface GenerateOpenAPISpecOptions {
     readonly title?: string;
     readonly version?: string;
@@ -656,117 +1035,60 @@ interface GenerateOpenAPISpecOptions {
     readonly description?: string;
 }
 /**
- * 由应用级 contract 生成 OpenAPI 3.1 spec。
+ * 由真实应用 contract 生成 OpenAPI 3.1 文档。
  *
- * @param contract - 已组合完成的应用级 oRPC contract
- * @param options - 文档元信息
- * @returns OpenAPI 文档对象
+ * @param contract - 应用 contract
+ * @param options - 标题、版本、描述与服务前缀
+ * @returns OpenAPI 文档
+ * @throws 底层转换器不能处理该 Schema 时 reject，调用方在启动或导出边界处理。
  *
  * @example
  * ```ts
- * const spec = await serv.generateSpec(contract, {
- *   title: 'My API',
- *   version: '1.0.0',
- *   apiPrefix: '/api/v1',
- * })
+ * import { apiContract } from '@h-ai/api-contract'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const spec = await serv.generateSpec(apiContract.create({}), { title: 'Reports API', version: '1.0.0', apiPrefix: '/api/v1' })
+ * const title = spec.info.title
  * ```
  */
 declare function generateSpec(contract: AnyContractRouter, options?: GenerateOpenAPISpecOptions): Promise<OpenAPI.Document>;
 
 /**
- * @h-ai/serv — contract-first 链式 procedure 实现器
- *
- * 在 oRPC `implement()` 之上提供 route 名只出现一次的链式 DSL。
- * 应用只接触 contract 路径、上下文与 guard，不需要组装 oRPC router 对象。
- *
- * @module serv-router
- */
-
-type EmptyContext = Record<never, never>;
-type StringKey<T> = Extract<keyof T, string>;
-type ServContract = ContractRouter<Meta>;
-/** contract 中所有 procedure 的点分路径。 */
-type ServRoutePath<TContract extends ServContract> = TContract extends ContractProcedure<infer _TInputSchema, infer _TOutputSchema, infer _TErrorMap, infer _TMeta> ? never : {
-    [K in StringKey<TContract>]: TContract[K] extends ContractProcedure<infer _TChildInputSchema, infer _TChildOutputSchema, infer _TChildErrorMap, infer _TChildMeta> ? K : TContract[K] extends ServContract ? ServRoutePath<TContract[K]> extends infer TChild extends string ? `${K}.${TChild}` : never : never;
-}[StringKey<TContract>];
-type ContractAtPath<TContract, TPath extends string> = TPath extends `${infer THead}.${infer TTail}` ? THead extends keyof TContract ? ContractAtPath<TContract[THead], TTail> : never : TPath extends keyof TContract ? TContract[TPath] : never;
-type RouteContract<TContract extends ServContract, TPath extends ServRoutePath<TContract>> = ContractAtPath<TContract, TPath>;
-/** `.auth()`、`.permission()`、`.role()` 后的非空会话上下文。 */
-type AuthenticatedServContext<TContext extends ServContext = ServContext> = TContext & {
-    readonly session: NonNullable<TContext['session']>;
-};
-type RouteHandler<TRouteContract, TContext extends Context> = TRouteContract extends ContractProcedure<infer TInputSchema, infer TOutputSchema, infer TErrorMap, infer TMeta> ? InferSchemaInput<TOutputSchema> extends HaiResult<unknown> ? ProcedureHandler<TContext, InferSchemaOutput<TInputSchema>, InferSchemaInput<TOutputSchema>, TErrorMap, TMeta> : never : never;
-/** 从 contract procedure 精确推导当前 route 的 HaiResult handler。 */
-type ServRouteHandler<TContract extends ServContract, TPath extends ServRoutePath<TContract>, TContext extends Context> = RouteHandler<RouteContract<TContract, TPath>, TContext>;
-type ServGuardedRouteHandler<TContract extends ServContract, TPath extends ServRoutePath<TContract>, TContext extends ServContext> = RouteHandler<RouteContract<TContract, TPath>, AuthenticatedServContext<TContext>>;
-type NextBuilder<TContract extends ServContract, TInitialContext extends Context, TCurrentContext extends ServContext, TRemaining extends ServRoutePath<TContract>, TPath extends TRemaining> = ServRouterBuilder<TContract, TInitialContext, TCurrentContext, Exclude<TRemaining, TPath>>;
-/** 尚未声明 guard 的单 route 注册器。 */
-interface ServRouteRegistration<TContract extends ServContract, TInitialContext extends Context, TCurrentContext extends ServContext, TRemaining extends ServRoutePath<TContract>, TPath extends TRemaining> {
-    readonly auth: () => ServGuardedRouteRegistration<TContract, TInitialContext, TCurrentContext, TRemaining, TPath>;
-    readonly permission: (permission: string) => ServGuardedRouteRegistration<TContract, TInitialContext, TCurrentContext, TRemaining, TPath>;
-    readonly role: (role: string) => ServGuardedRouteRegistration<TContract, TInitialContext, TCurrentContext, TRemaining, TPath>;
-}
-/** 已声明认证或授权 guard 的单 route 注册器。 */
-interface ServGuardedRouteRegistration<TContract extends ServContract, TInitialContext extends Context, TCurrentContext extends ServContext, TRemaining extends ServRoutePath<TContract>, TPath extends TRemaining> {
-    readonly auth: () => ServGuardedRouteRegistration<TContract, TInitialContext, TCurrentContext, TRemaining, TPath>;
-    readonly permission: (permission: string) => ServGuardedRouteRegistration<TContract, TInitialContext, TCurrentContext, TRemaining, TPath>;
-    readonly role: (role: string) => ServGuardedRouteRegistration<TContract, TInitialContext, TCurrentContext, TRemaining, TPath>;
-    readonly handle: (handler: ServGuardedRouteHandler<TContract, TPath, TCurrentContext>) => NextBuilder<TContract, TInitialContext, TCurrentContext, TRemaining, TPath>;
-}
-interface ServRouteMethod<TContract extends ServContract, TInitialContext extends Context, TCurrentContext extends ServContext, TRemaining extends ServRoutePath<TContract>> {
-    <TPath extends TRemaining>(path: TPath, handler: ServRouteHandler<TContract, TPath, TCurrentContext>): NextBuilder<TContract, TInitialContext, TCurrentContext, TRemaining, TPath>;
-    <TPath extends TRemaining>(path: TPath): ServRouteRegistration<TContract, TInitialContext, TCurrentContext, TRemaining, TPath>;
-}
-type ServRouterBuilderBuild<TContract extends ServContract, TInitialContext extends Context, TRemaining> = [TRemaining] extends [never] ? {
-    /** 同步返回完整的普通 router，允许按需选用嵌套的默认 procedures。 */
-    readonly build: () => UnlaziedRouter<Router<TContract, TInitialContext>>;
-} : {
-    /** 仅供 TypeScript/IDE 展示尚未实现的 route；运行时不存在。 */
-    readonly missingRoutes: TRemaining;
-};
-/**
- * 链式 router builder。
+ * @h-ai/serv — 部署环境 HTTP 安全策略
  *
- * `TRemaining` 会随着 `.route()` 注册逐步收窄；未实现完整 contract 时没有 `.build()`。
+ * 将环境与 CORS 配置收敛为 fail-closed 的运行时策略，避免每个业务应用重复实现
+ * Origin 解析、生产通配符保护、Cookie Secure 与 API 文档暴露规则。
+ * @module serv-runtime-security
  */
-type ServRouterBuilder<TContract extends ServContract, TInitialContext extends Context, TCurrentContext extends ServContext, TRemaining extends ServRoutePath<TContract> = ServRoutePath<TContract>> = {
-    readonly route: ServRouteMethod<TContract, TInitialContext, TCurrentContext, TRemaining>;
-} & ServRouterBuilderBuild<TContract, TInitialContext, TRemaining>;
-/** hai-framework 链式 contract 实现器。 */
-interface ServImplementer<TContract extends ServContract> {
-    readonly context: <TContext extends ServContext>() => ServRouterBuilder<TContract, TContext & EmptyContext, TContext>;
-}
 /**
- * 创建链式 contract 实现器。
+ * 运行时安全策略输入；通常来自 `_core.yml.env` 与 `_serv.yml.cors`。
  *
  * @example
  * ```ts
- * serv
- *   .implement(contract)
- *   .context<ServContext>()
- *   .route('info', infoHandler)
- *   .route('echo')
- *   .auth()
- *   .handle(echoHandler)
- *   .build()
- * ```
- */
-declare function implement<TContract extends ServContract>(contract: TContract): ServImplementer<TContract>;
-
-/**
- * @h-ai/serv — 部署环境 HTTP 安全策略
+ * import type { ServRuntimeSecurityPolicyInput } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
  *
- * 将环境与 CORS 配置收敛为 fail-closed 的运行时策略，避免每个业务应用重复实现
- * Origin 解析、生产通配符保护、Cookie Secure 与 API 文档暴露规则。
- * @module serv-runtime-security
+ * const input: ServRuntimeSecurityPolicyInput = { environment: 'production', corsOrigin: 'https://app.example.com' }
+ * const policy = serv.createRuntimeSecurityPolicy(input)
+ * ```
  */
-/** 运行时安全策略输入；通常来自 `_core.yml.env` 与 `_serv.yml.cors`。 */
 interface ServRuntimeSecurityPolicyInput {
     readonly environment?: string;
     readonly corsOrigin?: string;
     readonly nativeOrigins?: string;
 }
-/** 可直接装配到 CORS、refresh cookie 与 HTTP 文档配置的安全策略。 */
+/**
+ * 可直接装配到 CORS、refresh cookie 与 HTTP 文档配置的安全策略。
+ *
+ * @example
+ * ```ts
+ * import type { ServRuntimeSecurityPolicy } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const policy: ServRuntimeSecurityPolicy = serv.createRuntimeSecurityPolicy({ environment: 'production', corsOrigin: 'https://app.example.com' })
+ * const allowed = policy.allowOrigin('https://app.example.com')
+ * ```
+ */
 interface ServRuntimeSecurityPolicy {
     readonly allowOrigin: (origin: string) => boolean;
     readonly isNativeOrigin: (origin: string) => boolean;
@@ -774,9 +1096,19 @@ interface ServRuntimeSecurityPolicy {
     readonly exposeApiDocs: boolean;
 }
 /**
- * 创建部署环境安全策略。
+ * 校验部署 Origin 并生成 Cookie、文档与跨端 CORS 安全策略。
+ *
+ * @param input - 部署环境与显式允许的 Web/原生 Origin
+ * @returns 可用于 HTTP 装配的策略
+ * @throws Origin 非法，或 production 缺少明确 Web Origin/使用通配符时抛配置错误。
  *
- * 生产环境必须显式配置 HTTP(S) Origin，禁止缺省或 `*`；开发环境保留通配符便利性。
+ * @example
+ * ```ts
+ * import { serv } from '@h-ai/serv'
+ *
+ * const policy = serv.createRuntimeSecurityPolicy({ environment: 'production', corsOrigin: 'https://app.example.com' })
+ * const middleware = serv.cors({ origin: policy.allowOrigin, credentials: true })
+ * ```
  */
 declare function createRuntimeSecurityPolicy(input: ServRuntimeSecurityPolicyInput): ServRuntimeSecurityPolicy;
 
@@ -788,11 +1120,32 @@ declare function createRuntimeSecurityPolicy(input: ServRuntimeSecurityPolicyInp
  * @module serv-storage-assets
  */
 
-/** 可由只读资源 middleware 使用的最小 Storage 能力。 */
+/**
+ * 可由只读资源 middleware 使用的最小 Storage 能力。
+ *
+ * @example
+ * ```ts
+ * // 模块内部上下文：示例复用当前声明所在模块的实际绑定。
+ * function withStorage(source: StorageAssetSource): ServStorageAssetsConfig {
+ *   return { storage: source, pathPrefix: '/assets/', keyPattern: new RegExp('^public/[a-z0-9-]+[.]webp$'), allowedContentTypes: ['image/webp'] }
+ * }
+ * ```
+ */
 interface StorageAssetSource {
     readonly file: Pick<StorageFunctions['file'], 'get' | 'head'>;
 }
-/** Storage 只读资源 middleware 配置。 */
+/**
+ * Storage 只读资源 middleware 配置。
+ *
+ * @example
+ * ```ts
+ * import { serv } from '@h-ai/serv'
+ * import { storage } from '@h-ai/storage'
+ *
+ * // 仅发布明确公共资源；私有业务资源另执行可信资源授权。
+ * const middleware = serv.storageAssets({ storage, pathPrefix: '/assets/', keyPattern: new RegExp('^public/[a-z0-9-]+[.]webp$'), allowedContentTypes: ['image/webp'], cacheControl: 'public, max-age=3600' })
+ * ```
+ */
 interface ServStorageAssetsConfig {
     /** 已初始化的 Storage 模块或等价文件读取能力。 */
     readonly storage: StorageAssetSource;
@@ -818,15 +1171,14 @@ interface ServStorageAssetsConfig {
  *
  * @param config - Storage、路径、key、MIME 与缓存策略。
  * @returns 可挂载到 `serv.createApp({ middlewares })` 的 middleware。
+ *
  * @example
  * ```ts
- * const middleware = serv.storageAssets({
- *   storage,
- *   pathPrefix: '/api/v1/avatar-assets/',
- *   keyPattern: /^avatars\/[\w-]+\/[\w-]+\.webp$/,
- *   allowedContentTypes: ['image/webp'],
- *   cacheControl: 'public, max-age=31536000, immutable',
- * })
+ * import { serv } from '@h-ai/serv'
+ * import { storage } from '@h-ai/storage'
+ *
+ * // 仅发布明确公共资源；私有业务资源另执行可信资源授权。
+ * const middleware = serv.storageAssets({ storage, pathPrefix: '/assets/', keyPattern: new RegExp('^public/[a-z0-9-]+[.]webp$'), allowedContentTypes: ['image/webp'], cacheControl: 'public, max-age=3600' })
  * ```
  */
 declare function storageAssets(config: ServStorageAssetsConfig): ServMiddleware;
@@ -848,6 +1200,17 @@ declare function storageAssets(config: ServStorageAssetsConfig): ServMiddleware;
  * 复用 `HaiResult` 失败分支结构。字段错误同时在两处出现：
  * - `error.cause`：与 `validateInputOrFail` 输出对齐，HaiResult 标准位置
  * - 顶层 `errors`：保留以兼容已有客户端
+ *
+ * @example
+ * ```ts
+ * import type { ServValidationFailureBody } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * function fields(body: ServValidationFailureBody) {
+ *   return body.error.cause ?? body.errors
+ * }
+ * // 业务调用先判断 success，字段错误仅包含安全的本地化文案。
+ * ```
  */
 interface ServValidationFailureBody {
     readonly success: false;
@@ -869,6 +1232,14 @@ interface ServValidationFailureBody {
  *
  * @param headers - 请求头（`Headers` 或与之等价的对象）
  * @returns 解析得到的 locale
+ *
+ * @example
+ * ```ts
+ * import { serv } from '@h-ai/serv'
+ *
+ * const locale = serv.resolveRequestLocale(new Headers({ 'x-hai-locale': 'en-US' }))
+ * const fallback = serv.resolveRequestLocale(new Headers())
+ * ```
  */
 declare function resolveRequestLocale(headers: Headers | Record<string, string | undefined>): string;
 /**
@@ -898,10 +1269,39 @@ declare function resolveRequestLocale(headers: Headers | Record<string, string |
  * @param schema - Zod schema
  * @param input - 待校验数据
  * @param locale - 期望 locale（通常来自请求上下文）
+ *
+ * @example
+ * ```ts
+ * import { serv } from '@h-ai/serv'
+ * import { z } from 'zod'
+ *
+ * const result = serv.validateInputOrFail(z.object({ name: z.string().min(1) }), { name: '' }, 'en-US')
+ * if (!result.success) {
+ *   const fields = result.error.cause
+ * } else {
+ *   const name = result.data.name
+ * }
+ * ```
  */
 declare function validateInputOrFail<TOutput>(schema: ZodType<TOutput>, input: unknown, locale?: string): HaiResult<TOutput>;
 
-/** hai-framework API service runtime 统一入口（扁平 API）。 */
+/**
+ * hai-framework API service runtime 统一入口（扁平 API）。
+ *
+ * @example
+ * ```ts
+ * import type { ServContext } from '@h-ai/serv'
+ * import { apiContract } from '@h-ai/api-contract'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const contract = apiContract.create({})
+ * const procedures = serv.implement(contract).context<ServContext>().build()
+ * const app = serv.createApp({ contract, procedures })
+ *
+ * const response = await app.request('/health')
+ * if (!response.ok) throw new Error('Health request failed')
+ * ```
+ */
 declare const serv: {
     createApp: typeof createApp;
     parseRequestContext: typeof parseRequestContext;
@@ -920,4 +1320,4 @@ declare const serv: {
     m: (key: "$schema" | "serv_validationFailed" | "serv_validationRequired" | "serv_validationInvalid" | "serv_validationInvalidType" | "serv_validationStringMin" | "serv_validationStringMax" | "serv_validationNumberMin" | "serv_validationNumberMax" | "serv_validationArrayMin" | "serv_validationArrayMax" | "serv_validationTooSmall" | "serv_validationTooBig" | "serv_validationEmail" | "serv_validationUrl" | "serv_validationUuid" | "serv_validationEnum" | "serv_errorUnauthorized" | "serv_errorForbidden" | "serv_errorInternal" | "serv_storageKeyRequired" | "serv_storageKeyTooLong" | "serv_storageKeyIllegalChars" | "serv_storageKeyDotSegments" | "serv_iamCannotDeleteCurrentUser" | "serv_transportInvalidPayload" | "serv_transportUnknownClient" | "serv_transportClientIdRequired" | "serv_transportClientKeyNotFound" | "serv_transportDecryptFailed" | "serv_transportEncryptFailed" | "serv_transportKeyExchangeFailed", options?: _h_ai_core.MessageOptions) => string;
 };
 
-export { type AudioTicketGrant, type AudioTicketVerification, type AuthenticatedServContext, type AuthorizedAudioRequest, type CreateServAppOptions, CreateServContext, type GenerateOpenAPISpecOptions, RefreshCookieConfig, type ServAudioConfig, type ServConfig, type ServConfigInput, ServConfigSchema, ServContext, type ServCorsConfig, type ServCorsRuntimeConfig, type ServCorsRuntimeConfigInput, type ServDocsHttpConfig, type ServFetchHandler, type ServHealthHttpConfig, type ServHttpApp, type ServHttpConfig, type ServHttpConfigInput, ServIam, type ServImplementer, type ServListenOptions, type ServMiddleware, type ServMiddlewareFactory, type ServMiddlewareMount, type ServNodeServer, type ServOpenAPIHttpConfig, type ServProcedureHandler, type ServProcedureOptions, ServRequestMetadata, type ServRouteHandler, type ServRoutePath, type ServRouterBuilder, type ServRpcHttpConfig, type ServRuntimeSecurityPolicy, type ServRuntimeSecurityPolicyInput, type ServServerConfig, type ServServerConfigInput, ServSession, type ServStorageAssetsConfig, type ServTransportConfig, type ServTransportRuntimeConfig, type ServTransportRuntimeConfigInput, type ServValidationFailureBody, serv };
+export { type AudioTicketGrant, type AudioTicketVerification, type AuthorizedAudioRequest, type CreateServAppOptions, CreateServContext, type GenerateOpenAPISpecOptions, RefreshCookieConfig, type ServAudioConfig, type ServConfig, type ServConfigInput, ServConfigSchema, ServContext, type ServCorsConfig, type ServCorsRuntimeConfig, type ServCorsRuntimeConfigInput, type ServDocsHttpConfig, type ServFetchHandler, type ServHealthHttpConfig, type ServHttpApp, type ServHttpConfig, type ServHttpConfigInput, ServIam, type ServListenOptions, type ServMiddleware, type ServMiddlewareFactory, type ServMiddlewareMount, type ServNodeServer, type ServOpenAPIHttpConfig, type ServProcedureHandler, type ServProcedureOptions, ServRequestMetadata, type ServRpcHttpConfig, type ServRuntimeSecurityPolicy, type ServRuntimeSecurityPolicyInput, type ServServerConfig, type ServServerConfigInput, ServSession, type ServStorageAssetsConfig, type ServTransportConfig, type ServTransportRuntimeConfig, type ServTransportRuntimeConfigInput, type ServValidationFailureBody, serv };