feat: add project-owned error catalogs and HTTP 200 failure contracts

test: record remote connector and HTTP configuration acceptance
feat: support database connectors and HTTP server configuration
2026-09-24 12:40:05 +08:00 · 2026-09-24 02:19:33 +08:00 · 2026-09-24 02:18:18 +08:00 · 2026-09-24 01:49:49 +08:00
59 changed files with 3420 additions and 149 deletions
--- a/API.md
+++ b/API.md
@@ -111,6 +111,27 @@ service user-api {

 ## 业务错误：声明、代码和文档共用一份定义

+从 `v0.10.0-preview` 起，推荐用 `errorCatalog` 同时定义逻辑标识、对外业务码、提示和 HTTP 状态：
+
+```text
+errorCatalog CommonErrors (
+    defaultStatus: 200
+    errors: {
+        "UsernameInvalid": {"key": "USERNAME_INVALID", "code": 400002, "message": "用户名格式不正确"},
+        "PasswordInvalid": {"key": "PASSWORD_INVALID", "code": 400002, "message": "密码格式不正确"},
+        "Forbidden": {"key": "FORBIDDEN", "status": 403, "code": 403001, "message": "没有权限"}
+    }
+)
+```
+
+对象键是生成函数名；`key` 是唯一逻辑标识，允许项目自己的命名；`code` 是对外业务码，可以重复。数字码需搭配 `codeType: int32` 或 `int64` 的公共响应；字符串码搭配 `string`。目录不规定返回体字段。
+
+省略 `defaultStatus` 时为 400；设为 200 时，只作用于目录里未单独写 `status` 的条目。生成路由自动绑定它实际声明的错误目录，在 App 中间件之前生效。业务只调用 `apierrors.UsernameInvalid()`；无需再维护 `codes` / `messages`，也无需修改 main。手写路由可复用生成的 `apierrors.Catalog()`。
+
+同一 HTTP 200 下，OpenAPI 用 `anyOf` 保留成功 DTO 和错误体，日志与指标仍识别业务失败。完整语法、路由作用域与手写项目配置见 [统一错误目录](errors/README.md)，可运行契约见 [errors.api](examples/contracts/errors.api)。
+
+原有声明继续支持：
+
 ```go
 error (
    Unauthenticated 401 "UNAUTHENTICATED" "authentication required"
@@ -121,7 +142,7 @@ error (
 ```

 也可写单条 `error EmailTaken 409 "EMAIL_TAKEN" "email already in use"`，或把错误目录放进相对导入的 `errors.api`。
-名称用 UpperCamelCase，HTTP 状态范围 400–599，错误码用大写字母/数字/下划线且全局唯一，message 是可公开返回的稳定提示。
+名称用 UpperCamelCase，HTTP 状态允许 200–599 中可携带响应体的最终状态（排除 204/205/304），旧声明的逻辑错误码用大写字母/数字/下划线且全局唯一，message 是可公开返回的稳定提示。`Catalog` 为生成函数保留名称。

 `@server (errors: Unauthenticated)` 声明组级错误；路由 `@errors UserNotFound, EmailTaken` 追加到组级列表并去重。
 `@errors none` 清空继承的业务错误。未声明、重复声明或生成符号冲突会报告源码位置。
@@ -138,7 +159,7 @@ return nil, apierrors.EmailTaken()

 OpenAPI 对每个状态按选定的响应模板生成结构和命名 examples，同一 409 下多个错误不会相互覆盖；平铺模式的纯业务状态还列出 code enum。
 默认框架错误状态与自动添加的鉴权 401 保留开放的 code 字段，容纳校验器/中间件实际错误。
-`x-omni-errors` 提供错误目录与路由关联。文档声明不拦截、改写或穷举运行时的所有错误。
+`x-omni-errors` 提供错误目录与路由关联。目录解析已定义的错误，不自动推断数据库或其他未声明错误的业务含义，也不穷举所有运行时错误。

 ## 鉴权：声明与路由注册一起变化

--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,24 @@
 # Changelog

+## v0.10.0-preview
+
+- 新增 App/路由独立错误目录：`omni.WithErrors`、`errors.Catalog`、`ByCode` 与不可变 Registry，业务只选逻辑标识；对外码和提示由项目配置。
+- 默认 HTTP 状态与逐项覆盖均可配置，包括 HTTP 200 的业务失败；错误模板、RawJSON、日志、业务失败指标、链路、标准中间件桥接和幂等重放保留失败语义。
+- `.api errorCatalog` 同源生成 Catalog、独立错误函数、路由目录和 OpenAPI；允许重复对外码、不同路由不同码类型、公共契约导入。旧 error 声明也允许 HTTP 200。
+- 同一 200 的成功/错误响应使用 anyOf 保留两种 schema，错误示例保持各自提示；自定义 Encoder 和直接输出继续支持。
+- 目录校验类型、范围、状态和冲突；JSON 配置拒绝重复键，整数保留 int64 精度；未知标识使用系统兜底，默认公开响应不暴露 cause。
+- 新生成代码最低要求 v0.10.0-preview；原有构造函数、Codes/Messages 与旧生成代码继续可用。Catalog 为生成错误包保留函数名。
+
+
+## v0.9.1-preview
+
+- 新增标准 `database.OpenConnector` 和独立 `PoolConfig`；与 DSN 入口共享池参数、限时启动 Ping、失败清理、Health、事务，不注册全局驱动配置。
+- 新增 `omni.WithHTTPConfig` / `Config.HTTP`：读头、读请求、写响应、空闲超时和头大小，贯通代码、JSON/YAML、环境变量、Run/Serve 与 NewServer；nethttp 支持 Go-only ErrorLog。
+- 保持已有默认行为；负值和实验 http2 不支持的超时项在监听前报错；记录各网络层的具体语义。
+- 增加真实 MySQL TLS/驱动日志隔离、连接池归属/取消/事务、nethttp/native 慢连接与写背压验收，以及无本地 replace 的远程消费者脚本。
+- 兼容 v0.9.0-preview 生成代码；不修改业务项目的数据库策略或生成代码最低版本。
+
+
 ## v0.9.0-preview

 - 标准 HTTP Handler/Middleware 桥接：跟踪 Raw 状态与提交，保留取消、流式能力和中间件跨请求状态；已提交响应不追加 JSON。
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@

 GoOmni 是面向多个业务项目复用的 Go 后端框架：用 `.api` 定义接口、请求和返回类型，生成项目目录、HTTP 接入代码及 OpenAPI，业务代码负责 Service 和 Repository。也可以在已有项目中直接使用 `omni.New()`，或单独引入日志、存储等模块。

-**从这份 README 开始即可接入。** 当前版本为 **`v0.9.0-preview`**，Go **1.22+**；CLI 和项目依赖使用同一固定版本。框架不依赖 Gin，默认使用标准库网络层，提供可切换的 native HTTP/1.1 和实验性 HTTP/2 适配器。
+**从这份 README 开始即可接入。** 当前版本为 **`v0.10.0-preview`**，Go **1.22+**；CLI 和项目依赖使用同一固定版本。框架不依赖 Gin，默认使用标准库网络层，提供可切换的 native HTTP/1.1 和实验性 HTTP/2 适配器。

 响应字段、业务码、登录方式、权限规则和数据库表结构由接入项目决定。文中的 `code/msg/data`、`200/9999` 都是示例配置，可以替换。

@@ -26,7 +26,7 @@ module 地址是 `git.yuntuo.hk/k2safe/go-omni`。先确保本机 Go 和 Git 可

 ```sh
 export GOPRIVATE=git.yuntuo.hk
-go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.9.0-preview
+go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.10.0-preview
 export PATH="$(go env GOPATH)/bin:$PATH"
 go-omni --help
 ```
@@ -38,7 +38,7 @@ go-omni --help
 在准备存放业务项目的目录执行，`./hello` 必须是新目录或空目录；把 `example.com/hello` 换成自己的 Go module 名称。

 ```sh
-go-omni api new --framework-version v0.9.0-preview \
+go-omni api new --framework-version v0.10.0-preview \
  --module example.com/hello ./hello
 cd hello
 go mod tidy
@@ -126,7 +126,7 @@ service catalog-api {

 ```sh
 go-omni api validate --api catalog.api
-go-omni new --api catalog.api --framework-version v0.9.0-preview \
+go-omni new --api catalog.api --framework-version v0.10.0-preview \
  --module example.com/catalog ./catalog
 cd catalog
 go mod tidy
@@ -167,21 +167,21 @@ curl -i http://127.0.0.1:8080/api/v1/items/missing
 需要 MySQL、文件存储或文件日志时，**首次生成**可以使用：

 ```sh
-go-omni new --api catalog.api --framework-version v0.9.0-preview \
+go-omni new --api catalog.api --framework-version v0.10.0-preview \
  --module example.com/catalogFull --database mysql --storage local \
  --log-output file --log-format json ./catalogFull
 ```

 该命令在 `catalog.api` 所在目录执行，目标仍需是新目录。数据库迁移、表结构和 Repository 由项目维护，API 模板不自动建表；MySQL DSN 通过 `GO_OMNI_DB_DSN` 提供。存储还可选 `s3`、`r2`、`oss`，按生成项目的配置说明提供桶、端点和凭据。完整装配例子见 [userService](examples/userService/README.md)。

-不采用 `.api` 时，也可以用 `go-omni new --framework-version v0.9.0-preview --module example.com/billing ./billing` 创建手写接口的 CRUD 示例项目；两种生成方式选择一种即可。
+不采用 `.api` 时，也可以用 `go-omni new --framework-version v0.10.0-preview --module example.com/billing ./billing` 创建手写接口的 CRUD 示例项目；两种生成方式选择一种即可。

 ## 已有项目：按模块接入

 在业务项目的 **go.mod 所在目录**执行：

 ```sh
-go get git.yuntuo.hk/k2safe/go-omni@v0.9.0-preview
+go get git.yuntuo.hk/k2safe/go-omni@v0.10.0-preview
 ```

 已有项目可直接复用现有目录、Service、Repository 和数据库连接，先选择一个接口接入。也可以只用 `logx`、`storage` 等包，暂时保留原来的 HTTP 框架。
@@ -307,12 +307,69 @@ auth UserAuth (

 生成器会创建 `internal/middleware/auth.go`，由项目实现凭据校验和身份注入。声明会生成路由绑定与 OpenAPI 的认证描述，**不会自动实现登录或授权规则**；未实现的 hook 返回 501。手写路由可使用 `auth.RequireAuth(authenticator)` 或自己的中间件。JWT、Session 和 Policy 按需选择。

-业务错误在 `.api` 中用 `error` 声明，通过 `@errors` 关联路由后，生成可调用的错误函数和 OpenAPI 中对应的 401、403、409 等响应。手写路由可以直接返回 `omni.NotFound`、`omni.Forbidden` 等错误。已有项目在自己的适配层转换原错误，内部原因和公开提示分开处理。
+业务错误可以集中定义，业务只选择发生了哪个错误。**HTTP 状态由项目配置，业务失败可以返回 HTTP 200**；框架不根据 HTTP 状态单独判断成功与否。
+
+API 项目推荐在公共 `.api` 中声明目录，其他契约通过 `import` 引用：
+
+```text
+errorCatalog CommonErrors (
+    defaultStatus: 200
+    errors: {
+        "UsernameInvalid": {"key": "USERNAME_INVALID", "code": 400002, "message": "用户名格式不正确"},
+        "PasswordInvalid": {"key": "PASSWORD_INVALID", "code": 400002, "message": "密码格式不正确"},
+        "PermissionDenied": {"key": "PERMISSION_DENIED", "status": 403, "code": 403001, "message": "没有权限"}
+    }
+)
+```
+
+`UsernameInvalid` 是生成函数名；`key` 是唯一逻辑标识；`code` 是项目对外的字符串或整数业务码，可以重复。条目没有填写 `status` 时使用目录的 `defaultStatus`，未配置目录默认值时为 400。这个默认值只作用于该目录的条目，不会把所有框架异常都改成 200。
+
+在已有公共响应中保留 `codeType: int32` / `int64` / `string`、成功码、未定义错误的兜底码和返回体模板；不再重复填写这几条错误的 `codes` / `messages`。通过 `@server (errors: UsernameInvalid, PasswordInvalid)` 或路由 `@errors UsernameInvalid` 引用它们。
+
+生成后业务调用：
+
+```go
+return TokenResponse{}, apierrors.UsernameInvalid()
+// 需要保留内部原因时：
+return TokenResponse{}, apierrors.UsernameInvalid().WithCause(err)
+```
+
+生成器同时提供 `internal/apierrors.Catalog()`、错误函数、路由错误目录及 OpenAPI。目录会在 App 中间件执行前绑定到生成路由；无需手动改已经生成的 main。HTTP 200 的错误使用失败响应模板；OpenAPI 用 `anyOf` 同时保留成功 DTO 和错误体，多条错误共用数字码时仍保留各自示例。完整契约见 [errors.api](examples/contracts/errors.api)。
+
+手写项目可在启动时加载自己的目录，保留原来的响应配置：
+
+```go
+// omnierrors 是 git.yuntuo.hk/k2safe/go-omni/errors。
+catalog := omnierrors.Catalog{
+    DefaultStatus: 200,
+    Definitions: map[string]omnierrors.Definition{
+        "USERNAME_INVALID": {Code: 400002, Message: "用户名格式不正确"},
+        "PASSWORD_INVALID": {Code: 400002, Message: "密码格式不正确"},
+    },
+}
+app := omni.New(
+    omni.WithErrors(catalog),
+    omni.WithResponse(response.Config{
+        CodeType: "int32", SuccessCode: 0, ErrorCode: 9999,
+        MessageField: "msg", DataMode: "always",
+    }),
+)
+// Service 只返回标准 error，不依赖 App 或 HTTP Context：
+// return omnierrors.ByCode("USERNAME_INVALID").WithCause(err)
+```
+
+目录也可放入 `config.Config.Errors`，由 JSON/YAML 加载；生成项目的路径为 `server.errors`，但契约生成路由以 `.api` 绑定的目录为准。不同 App 独立持有配置，单路由也可通过 `response.WithErrors` 绑定专用目录与自定义 Encoder。直接输出文本、XML、下载或已提交的响应继续保留原协议。
+
+访问日志保留实际 HTTP 状态，并增加失败标记、逻辑错误标识和目录业务码；指标、链路及框架标准中间件/幂等重放也保留失败语义。未知标识使用系统错误兜底，内部 cause 不写入默认公开响应。旧 `error (...)`、`New` / `BadRequest` / `Codes` / `Messages` 继续支持；新目录与旧映射冲突会报错，避免静默覆盖。
+
+更详细的配置、作用域和升级步骤见 [统一错误目录](errors/README.md)。

 ### 数据库、存储及其他模块

 依赖在启动入口或项目自己的 `internal/servicecontext` 中创建，通过构造函数传给 Service/Repository，避免每个请求都新建连接池。只注册自己拥有的资源，例如 `app.OnShutdown(db.Close)`；关闭按注册的逆序执行。

+已有项目使用 `driver.Connector` 时，直接 `database.OpenConnector(ctx, connector, database.DefaultPoolConfig())`。MySQL 等驱动的独立 TLS、Logger、时区与拨号参数由项目构造 Connector；框架负责连接池、启动 Ping、健康检查及事务。无需转成 DSN，也无需注册全局 TLS/Logger。具体示例和资源归属见 [Connector 接入](database/README.md#connector-接入v091-preview)。
+
 | 能力 | 包与接入说明 |
 | --- | --- |
 | 数据库连接池、事务、显式迁移 | `database`，见 [数据库](database/README.md)；表结构与驱动由项目选择 |
@@ -332,6 +389,9 @@ API 项目的数据库迁移需要单独维护并显式执行；启动不会自
 | `GO_OMNI_HTTP_ADDR` | 监听地址；生成项目默认 `127.0.0.1:8080` |
 | `GO_OMNI_TRANSPORT` | `nethttp`（默认）、`native`、`http2` |
 | `GO_OMNI_TLS_CERT_FILE` / `GO_OMNI_TLS_KEY_FILE` | 成对设置 TLS 证书和私钥路径 |
+| `GO_OMNI_HTTP_READ_HEADER_TIMEOUT` / `GO_OMNI_HTTP_READ_TIMEOUT` | 请求头 / 请求读取超时，如 `5s` / `30s` |
+| `GO_OMNI_HTTP_WRITE_TIMEOUT` / `GO_OMNI_HTTP_IDLE_TIMEOUT` | 响应写入 / Keep-Alive 空闲超时 |
+| `GO_OMNI_HTTP_MAX_HEADER_BYTES` | 请求头大小限制，字节数 |
 | `GO_OMNI_SHUTDOWN_TIMEOUT` | 优雅退出等待时间，默认 `10s` |
 | `GO_OMNI_ENABLE_LOGGER` / `GO_OMNI_LOG_LEVEL` | 访问日志开关、日志级别 |
 | `GO_OMNI_TRUSTED_PROXIES` | 可解析转发地址头的可信代理 IP/CIDR，逗号分隔 |
@@ -345,6 +405,20 @@ GO_OMNI_TRANSPORT=native go run ./cmd/server

 手写入口可用 `omni.WithTransport(omni.TransportNative)`；TLS 配置为 `omni.WithTLS(certFile, keyFile)`。native 提供 HTTP/1.1、Keep-Alive、TLS、超时、连接/请求并发上限和对象复用；HTTP/2 是单独的实验适配器，必须配置 TLS。默认 nethttp 的 TLS 支持 HTTP/1.1 与 HTTP/2。

+读写超时也可以在生成项目的 `etc/config.yaml` 中声明（放在 `server.http` 下）：
+
+```yaml
+server:
+  http:
+    readHeaderTimeout: 5s
+    readTimeout: 30s
+    writeTimeout: 30s
+    idleTimeout: 60s
+    maxHeaderBytes: 1048576
+```
+
+代码配置使用 `omni.WithHTTPConfig(omni.HTTPConfig{ReadTimeout: 30*time.Second, WriteTimeout: 30*time.Second})`。`Run`、`RunContext`、`ServeContext` 会应用它；`NewServer` 会配置返回的标准 `http.Server`，包含可选的 Go 字段 `ErrorLog`。**正值覆盖、零值保留所选网络层的原有默认行为、负值报错**；不配置时升级行为不变。超时含义与支持范围见 [HTTP 配置](transport/README.md#http-配置v091-preview)，不要把网络 I/O 超时当成业务执行时限。
+
 自研网络层通过 `RunWith(ctx, runner)` 接入监听与连接生命周期，通过 `NewWithRouter(router)` 替换路由；业务 Handler/Service 不需要导入具体适配器。细节与验收契约见 [网络适配层](transport/README.md)。

 `Run` 处理 SIGINT/SIGTERM；`RunContext` 接收调用方控制的退出信号。服务先停止接收新请求，等待活跃请求完成，再清理资源；超时会取消请求并关闭连接，业务代码仍需响应 context 取消。
@@ -364,7 +438,7 @@ go test ./...

 `Gen.go`、`docs/openapi.json` 和 manifest 由生成器管理，手动修改会报告冲突。Service、Repository、中间件实现、main、配置和依赖装配属于项目，重复生成保留手写内容；契约改变后仍需自行调整业务签名并通过编译。将 `.api`、生成文件和 `.goOmni/apiManifest.json` 一起提交，CI 可运行 `generate --check` 检查是否同步。

-升级时先安装目标版本的 CLI，再在业务 module 中 `go get` **同一版本**；API 项目随后执行上述生成与测试步骤，手写项目只需依赖升级及业务回归。`v0.9.0-preview` 的变化、迁移边界和验收记录见 [发布说明](RELEASE.md)。
+升级时先安装目标版本的 CLI，再在业务 module 中 `go get` **同一版本**；API 项目随后执行上述生成与测试步骤，手写项目只需依赖升级及业务回归。`v0.10.0-preview` 的变化、迁移边界和验收记录见 [发布说明](RELEASE.md)。

 ## 按需深入

--- a/RELEASE.md
+++ b/RELEASE.md
@@ -1,34 +1,38 @@
-# v0.9.0-preview
+# v0.10.0-preview

-本版补齐已有 HTTP 项目的迁移接入能力：标准 Handler/Middleware 桥接、动态 JSON、路由级请求体限额与手写绑定、自定义标量转换。业务的响应格式、身份、资金事务和数据库实现仍由项目决定。
+统一错误目录：由项目集中定义逻辑标识、对外业务码、公开提示和 HTTP 状态，业务只选择错误。支持 HTTP 200 的业务失败，并贯通响应、错误函数生成、日志与 OpenAPI。

-## 安装与升级
+## 升级

 ```sh
-export GOPRIVATE=git.yuntuo.hk
-go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.9.0-preview
-# 在业务 module 中：
-go get git.yuntuo.hk/k2safe/go-omni@v0.9.0-preview
+go get git.yuntuo.hk/k2safe/go-omni@v0.10.0-preview
+go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.10.0-preview
+# 使用 .api 的项目再执行：
+go-omni api generate --dry-run
+go-omni api generate
+go test ./...
 ```

-将私有域名追加到已有 GOPRIVATE；凭据通过本机 Git 凭据管理器配置。CLI 与项目框架依赖一起升级。进入已生成的项目，再运行 `go-omni api generate --dry-run`、`go-omni api generate`、`go test ./...`。
+先升级项目依赖，再使用同版 CLI。新生成代码最低运行时为本版；旧的 APIError/New/BadRequest、Codes/Messages、error 声明及旧生成代码继续支持。API 错误包增加 `Catalog()`，该名称成为保留符号。项目的手写 main、Service 和 Repository 不被重生成覆盖。

-## 本次变化
+## 接入

- `httpx.WrapHandler`、`WrapMiddleware`、`WrapFuncMiddleware` 将现有标准代码接入 App 中间件链。Raw 写入会记录真实状态和提交；已经输出的响应不再追加错误 JSON。下载/流式输出不整体缓存，保留底层支持的 HTTP 可选能力和取消信号。
- `.api` 的 `any` / `interface{}` 支持动态 JSON。数字保留为 json.Number，外围 DTO 严格校验不变。
- `@body` 按路由声明限额；内置 App 在全局中间件读取前限制 body。`@binding custom`、`@handlerMode manual` 生成保留的项目实现文件；上传、原文验签、下载可自行处理。`@produces` 描述手写成功输出的媒体类型。
- `scalar` 显式引用项目 Go 类型，调用标准 JSON/Text 方法；输入和输出各自生成 OpenAPI。普通基础类型不会自动放宽。
+- 手写项目：`omni.New(omni.WithErrors(catalog), omni.WithResponse(responseConfig))`，业务返回 `omnierrors.ByCode(key)`，按需 `.WithCause(err)`。
+- 契约项目：`.api errorCatalog` 定义一次，路由 `@errors` 或 `@server errors` 引用，生成 `apierrors.UsernameInvalid()` 等函数、Catalog、路由策略及 OpenAPI。
+- 项目目录的 `defaultStatus` 可以设为 200，单条错误可设置 403、409 等；默认只作用于目录条目，不改变未配置系统错误的兜底。
+- 逻辑标识必须唯一，对外业务码可以重复，支持字符串/int32/int64；整数精度与所选响应类型在加载/编译时校验。
+- HTTP 200 失败使用错误响应模板，OpenAPI 的 200 使用 anyOf 保留成功 DTO 和错误体；同码错误保留不同示例。
+- App 和路由目录隔离、初始化复制；每次生成/解析错误都返回独立对象。未知标识转系统兜底，默认公开响应不暴露 cause。

-详见 [迁移扩展指南](MIGRATION.md)、[完整契约](examples/contracts/compatibility.api)、[运行示例](examples/compatibility/main.go) 和 [历史更新](CHANGELOG.md)。
+完整接入从 [README](README.md) 开始；目录/作用域/配置边界见 [错误目录](errors/README.md)；可直接生成的例子见 [errors.api](examples/contracts/errors.api)。

-## 兼容与边界
+## 配置边界

-原有 `.api`、公共响应配置和普通 Handler 可以继续使用。新生成代码最低运行时版本为本版。`Raw()` 现在返回跟踪包装器；直接断言某个具体 writer 类型的代码需改用标准接口/ResponseController。
+生成路由的目录和响应以 `.api` 为准，优先于 App 默认配置；ByCode 需要当前目录中存在该标识。使用生成函数后仍须声明实际路由的 @errors，保持文档准确。不同路由可使用不同码类型与返回格式。

-标准中间件须保留 incoming request context 并同步调用 next；第三方框架私有的参数读取器仍由项目适配。手写 Handler/绑定 hook 初始返回 501；实现和文档一致性由项目负责，未实现不能上线。切换 manual 回自动模式时须显式迁移并移除对应手写文件，生成器不会删除它。
+目录与响应模板分开，自定义 Encoder 继续控制最终 HTTP 状态和文本/XML 等协议。直接输出与已提交响应不会被再次包装。旧同标识 Codes/Messages 若与新目录冲突会明确拒绝。

-新增能力没有引入 Gin 或 go-zero 依赖。不是完整 goctl 语法兼容层，不代表任何业务项目已完成迁移。HTTP/2 仍为实验功能，本轮没有重新做 Linux 长测、代理验收或云存储账号实网验收。
+访问日志记录实际提交状态，并带 failed/errorKey/可用的 businessCode。指标与链路识别 HTTP 200 业务失败；标准中间件和本地/共享幂等重放保留错误标识，旧缓存缺少标记时不补推历史状态。业务代码中的散落提示仍需业务项目按目录逐步迁移；本轮没有改写 eTax/ePay 业务逻辑。

 ## 验证入口

@@ -36,8 +40,13 @@ go get git.yuntuo.hk/k2safe/go-omni@v0.9.0-preview
 GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race -p=1 -count=1 -timeout=300s ./...
 go vet ./...
 go build ./...
-python3 scripts/verifyCompatibilityRelease.py --version v0.9.0-preview \
-  --report performance/compatibilityRemote.json
+python3 scripts/verifyErrorCatalogRelease.py --version v0.10.0-preview
+python3 scripts/verifyCompatibilityRelease.py --version v0.10.0-preview \
+  --report performance/errorCatalogCompatibilityRemote.json
 ```

-测试覆盖旧 Handler 404 与访问日志、提交后错误/panic、标准中间件状态/取消/提前写响应、nethttp/native 实际流式下载与请求体超限、multipart 临时文件清理、自定义标量精度/越界/nullable/集合，以及真实生成项目的验签与重生成保护。远程脚本从全新 module cache 安装 CLI，并检查生成项目的固定版本、校验和以及没有本地 replace。
+测试覆盖多 App 隔离、并发原因隔离、精确 int64、重复/非法定义拒绝、200 失败与 403 覆盖、未知错误兜底、已提交响应不追加、文本回执、访问日志、指标/链路、标准桥接、本地与序列化共享幂等存储，以及真实生成项目的 early middleware、raw 输出和重生成保护。远程脚本从全新缓存安装 CLI，检查固定版本、模块校验和与没有本地 replace。
+
+本版结果见 [统一错误目录验收](performance/errorCatalogAcceptance.md)。
+
+历史 Connector/HTTP 配置验收保留在 [v0.9.1 记录](performance/connectorAcceptance.md)，历史版本变化见 [CHANGELOG](CHANGELOG.md)。
--- a/RESPONSE.md
+++ b/RESPONSE.md
@@ -138,3 +138,12 @@ go run ./cmd/go-omni api generate --api examples/contracts/responses.api \
 ```

 示例业务方法起初为 501，完成 Service 后就会套用声明的模板。参考 [完整 .api](examples/contracts/responses.api)。验收测试会在临时目录生成真实项目，写入业务方法，执行已生成路由，检查数字错误码、原始 JSON、鉴权错误、路由覆盖与重复生成保护。
+
+
+## 错误目录与 HTTP 200 失败（v0.10.0-preview）
+
+错误含义由项目的 `errors.Catalog` 或 `.api errorCatalog` 集中定义，返回字段/结构仍由本页的 response 模板控制。目录提供独立的逻辑标识、对外字符串/整数码、消息、HTTP 状态，使用 `WithErrors` 或生成路由绑定。详见 [统一错误目录](errors/README.md)。
+
+`response.Result.IsError()` 综合明确失败标记、Err 和 HTTP 状态判断；HTTP 200 的业务错误不会使用成功码/成功提示，仍可选择 `errorBody`。新目录的公开码与提示优先于通用兜底；与同标识 Codes/Messages 冲突会拒绝，不会静默覆盖。没有目录的旧映射保持原有行为。
+
+自定义 Encoder 可读取 `Code`（逻辑标识）、`BusinessCode`（目录对外码）、Message 与 Err，并返回项目要求的最终状态和媒体类型。不要仅通过 Status 判断成功；内部原因默认只供诊断，不应由 Encoder 直接序列化 Err。RawJSON 的成功输出保持原样，失败继续交给所选错误编码器。
--- a/app/app.go
+++ b/app/app.go
@@ -67,6 +67,7 @@ func configure(options ...config.Option) config.Config {

 func newApp(router httpx.Router, settings config.Config) *App {
 	settings.Response = settings.Response.Clone()
+	settings.Errors = settings.Errors.Clone()
 	encoder, responseErr := response.New(settings.Response)
 	if responseErr != nil {
 		panic(responseErr)
@@ -77,6 +78,10 @@ func newApp(router httpx.Router, settings config.Config) *App {
 	}
 	settings.TrustedProxies = append([]string(nil), settings.TrustedProxies...)
 	settings.Log.RedactKeys = append([]string(nil), settings.Log.RedactKeys...)
+	responseEncoder, responseErr = response.WithErrors(settings.Errors, responseEncoder)
+	if responseErr != nil {
+		panic(responseErr)
+	}
 	resolver, err := httpx.NewClientIPResolver(settings.TrustedProxies...)
 	if err != nil {
 		panic("go-omni: " + err.Error())
@@ -114,6 +119,7 @@ func (a *App) ServeHTTP(writer http.ResponseWriter, request *http.Request) {
 func (a *App) Config() config.Config {
 	settings := a.config
 	settings.Response = settings.Response.Clone()
+	settings.Errors = settings.Errors.Clone()
 	settings.TrustedProxies = append([]string(nil), settings.TrustedProxies...)
 	settings.Log.RedactKeys = append([]string(nil), settings.Log.RedactKeys...)
 	return settings
@@ -156,16 +162,24 @@ func (a *App) Run(address ...string) error {
 	return a.RunContext(ctx, address...)
 }

-// NewServer creates a plain standard HTTP server around the application.
+// NewServer creates a plain standard HTTP server with the configured HTTP options.
+// Invalid HTTP options panic; RunContext/ServeContext return validation errors.
 // Use RunContext or ServeContext to apply the configured transport and TLS.
 func (a *App) NewServer(address string) *http.Server {
+	if err := a.config.HTTP.Validate(); err != nil {
+		panic(err)
+	}
 	if address == "" {
 		address = a.config.Address
 		if address == "" {
 			address = ":8080"
 		}
 	}
-	return &http.Server{Addr: address, Handler: a.router}
+	cfg := a.config.HTTP
+	return &http.Server{Addr: address, Handler: a.router,
+		ReadHeaderTimeout: cfg.ReadHeaderTimeout, ReadTimeout: cfg.ReadTimeout,
+		WriteTimeout: cfg.WriteTimeout, IdleTimeout: cfg.IdleTimeout,
+		MaxHeaderBytes: cfg.MaxHeaderBytes, ErrorLog: cfg.ErrorLog}
 }

 // RunContext serves until the context is canceled, then performs a graceful shutdown.
--- a/app/errorCatalog_test.go
+++ b/app/errorCatalog_test.go
@@ -0,0 +1,178 @@
+package app_test
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	omni "git.yuntuo.hk/k2safe/go-omni"
+	apierrors "git.yuntuo.hk/k2safe/go-omni/errors"
+	"git.yuntuo.hk/k2safe/go-omni/httpx"
+	"git.yuntuo.hk/k2safe/go-omni/logx"
+	"git.yuntuo.hk/k2safe/go-omni/metrics"
+	"git.yuntuo.hk/k2safe/go-omni/middleware"
+	"git.yuntuo.hk/k2safe/go-omni/response"
+)
+
+func TestAppErrorCatalogHTTP200LogsAndReplay(t *testing.T) {
+	var logs bytes.Buffer
+	logCfg := logx.Default()
+	logCfg.Writer = &logs
+	l, err := logx.New(logCfg)
+	if err != nil {
+		t.Fatal(err)
+	}
+	logx.SetDefault(l)
+	defer logx.SetDefault(nil)
+	defer l.Close()
+	cat := apierrors.Catalog{DefaultStatus: 200, Definitions: map[string]apierrors.Definition{"INVALID": {Code: 400002, Message: "项目提示"}, "DENIED": {Status: 403, Code: 9, Message: "no"}}}
+	policy := response.Config{CodeType: "int32", SuccessCode: 0, ErrorCode: 9999, MessageField: "msg", DataMode: "always"}
+	app := omni.New(omni.WithErrors(cat), omni.WithResponse(policy), omni.WithLogger(true))
+	defer app.Close()
+	meter := metrics.New()
+	app.Use(meter.Middleware())
+	cat.Definitions["INVALID"] = apierrors.Definition{Status: 500, Code: 1, Message: "mutated"}
+	app.Config().Errors.Definitions["INVALID"] = apierrors.Definition{Status: 500, Code: 2, Message: "mutated"}
+	app.GET("/error", func(c *omni.Context) error {
+		return fmt.Errorf("wrapped: %w", apierrors.ByCode("INVALID").WithCause(errors.New("private")))
+	})
+	app.GET("/direct", func(c *omni.Context) error { c.WriteError(apierrors.ByCode("INVALID")); return nil })
+	app.GET("/bridge", func(c *omni.Context) error { return apierrors.ByCode("INVALID") }, httpx.WrapMiddleware(func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { next.ServeHTTP(w, r) })
+	}))
+	app.GET("/missing", func(c *omni.Context) error { return apierrors.ByCode("MISSING") })
+	app.GET("/denied", func(c *omni.Context) error { return apierrors.ByCode("DENIED") })
+	app.GET("/committed", func(c *omni.Context) error {
+		if err := c.Text(201, "done"); err != nil {
+			return err
+		}
+		return apierrors.ByCode("INVALID")
+	})
+	app.HandleWithResponse("GET", "/callback", response.EncoderFunc(func(r response.Result) (response.Payload, error) {
+		if !r.IsError() || r.BusinessCode != int64(400002) {
+			t.Fatal(r)
+		}
+		return response.Text(202, "ACK"), nil
+	}), func(c *omni.Context) error { return apierrors.ByCode("INVALID") })
+	idem, err := middleware.NewIdempotency(middleware.IdempotencyConfig{Scope: func(*httpx.Context) (string, error) { return "fixture", nil }})
+	if err != nil {
+		t.Fatal(err)
+	}
+	calls := 0
+	app.POST("/idempotent", func(c *omni.Context) error { calls++; return apierrors.ByCode("INVALID") }, idem.Middleware())
+	shared, err := middleware.NewIdempotency(middleware.IdempotencyConfig{Store: &catalogStore{records: map[string]middleware.IdempotencyRecord{}}, Scope: func(*httpx.Context) (string, error) { return "fixture", nil }})
+	if err != nil {
+		t.Fatal(err)
+	}
+	app.POST("/shared", func(c *omni.Context) error { calls++; return apierrors.ByCode("INVALID") }, shared.Middleware())
+
+	for _, path := range []string{"/error", "/direct", "/bridge", "/idempotent", "/idempotent", "/shared", "/shared"} {
+		method := "GET"
+		if path == "/idempotent" || path == "/shared" {
+			method = "POST"
+		}
+		w := httptest.NewRecorder()
+		r := httptest.NewRequest(method, path, nil)
+		r.Header.Set("Idempotency-Key", "same")
+		app.ServeHTTP(w, r)
+		if w.Code != 200 || !strings.Contains(w.Body.String(), `"code":400002`) || !strings.Contains(w.Body.String(), "项目提示") || strings.Contains(w.Body.String(), "private") {
+			t.Fatal(w.Code, w.Body.String())
+		}
+	}
+	if stats := meter.Snapshot(); stats.Errors != 7 || stats.StatusCounts["200"] != 7 {
+		t.Fatal("lost business failure metrics", stats)
+	}
+	if calls != 2 {
+		t.Fatal("replay executed business twice")
+	}
+	for _, test := range []struct {
+		path   string
+		status int
+		body   string
+	}{{"/denied", 403, `"code":9`}, {"/missing", 500, `"code":9999`}, {"/committed", 201, "done"}, {"/callback", 202, "ACK"}} {
+		w := httptest.NewRecorder()
+		app.ServeHTTP(w, httptest.NewRequest("GET", test.path, nil))
+		if w.Code != test.status || !strings.Contains(w.Body.String(), test.body) {
+			t.Fatal(test.path, w.Code, w.Body.String())
+		}
+	}
+	for _, line := range strings.Split(strings.TrimSpace(logs.String()), "\n") {
+		var entry map[string]any
+		if err := json.Unmarshal([]byte(line), &entry); err != nil {
+			t.Fatal(err)
+		}
+		if entry["msg"] != "http.request" {
+			continue
+		}
+		if entry["failed"] != true {
+			t.Fatal("lost failure:", entry)
+		}
+		if entry["path"] == "/callback" {
+			if entry["status"] != float64(202) {
+				t.Fatal(entry)
+			}
+		} else if entry["path"] == "/error" || entry["path"] == "/direct" || entry["path"] == "/bridge" || entry["path"] == "/idempotent" || entry["path"] == "/shared" {
+			if entry["status"] != float64(200) || entry["businessCode"] != float64(400002) || entry["errorKey"] != "INVALID" {
+				t.Fatal(entry)
+			}
+		}
+	}
+	// A second application may interpret the same logical identifier differently.
+	app2 := omni.New(omni.WithErrors(apierrors.Catalog{Definitions: map[string]apierrors.Definition{"INVALID": {Status: 409, Code: "conflict", Message: "other"}}}))
+	defer app2.Close()
+	app2.GET("/", func(*omni.Context) error { return apierrors.ByCode("INVALID") })
+	w := httptest.NewRecorder()
+	app2.ServeHTTP(w, httptest.NewRequest("GET", "/", nil))
+	if w.Code != 409 || !strings.Contains(w.Body.String(), "other") {
+		t.Fatal(w.Code, w.Body.String())
+	}
+}
+
+// A serialized store exercises the shared middleware contract, including replay
+// metadata. No external service or project database is used by this fixture.
+type catalogStore struct {
+	mu      sync.Mutex
+	records map[string]middleware.IdempotencyRecord
+}
+
+func (s *catalogStore) Claim(_ context.Context, key, fp, owner string) (middleware.IdempotencyRecord, bool, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if r, ok := s.records[key]; ok {
+		return r, false, nil
+	}
+	r := middleware.IdempotencyRecord{Fingerprint: fp, Owner: owner, State: "running"}
+	s.records[key] = r
+	return r, true, nil
+}
+func (s *catalogStore) Complete(_ context.Context, key, owner string, response *middleware.StoredResponse, _ time.Duration) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	r := s.records[key]
+	if r.Owner != owner {
+		return errors.New("wrong owner")
+	}
+	r.State = "failed"
+	if response != nil {
+		r.State = "completed"
+		encoded, err := json.Marshal(response)
+		if err != nil {
+			return err
+		}
+		var copy middleware.StoredResponse
+		if err := json.Unmarshal(encoded, &copy); err != nil {
+			return err
+		}
+		r.Response = &copy
+	}
+	s.records[key] = r
+	return nil
+}
--- a/app/httpConfig_test.go
+++ b/app/httpConfig_test.go
@@ -0,0 +1,199 @@
+package app_test
+
+import (
+	"bufio"
+	"context"
+	"errors"
+	"io"
+	"log"
+	"net"
+	"net/http"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	omni "git.yuntuo.hk/k2safe/go-omni"
+)
+
+func TestHTTPConfiguredStandardServer(t *testing.T) {
+	cfg := omni.HTTPConfig{ReadHeaderTimeout: time.Second, ReadTimeout: 2 * time.Second, WriteTimeout: 3 * time.Second, IdleTimeout: 4 * time.Second, MaxHeaderBytes: 8192, ErrorLog: log.New(io.Discard, "", 0)}
+	a := omni.New(omni.WithHTTPConfig(cfg))
+	s := a.NewServer(":9000")
+	if s.ReadHeaderTimeout != cfg.ReadHeaderTimeout || s.ReadTimeout != cfg.ReadTimeout || s.WriteTimeout != cfg.WriteTimeout || s.IdleTimeout != cfg.IdleTimeout || s.MaxHeaderBytes != cfg.MaxHeaderBytes || s.ErrorLog != cfg.ErrorLog || s.Addr != ":9000" {
+		t.Fatalf("server options: %+v", s)
+	}
+	s = omni.New().NewServer("")
+	if s.ReadHeaderTimeout != 0 || s.ReadTimeout != 0 || s.WriteTimeout != 0 || s.IdleTimeout != 0 || s.MaxHeaderBytes != 0 || s.ErrorLog != nil {
+		t.Fatal("default behavior changed")
+	}
+}
+
+func TestHTTPInvalidStartupReleasesResources(t *testing.T) {
+	a := omni.New(omni.WithHTTPConfig(omni.HTTPConfig{ReadTimeout: -time.Second}))
+	called := 0
+	cleanupErr := errors.New("cleanup")
+	a.OnShutdown(func() error { called++; return cleanupErr })
+	err := a.RunContext(context.Background(), "bad address")
+	if err == nil || !strings.Contains(err.Error(), "http.readTimeout") || !errors.Is(err, cleanupErr) || called != 1 {
+		t.Fatalf("validation/cleanup: %v, %d", err, called)
+	}
+	defer func() {
+		if recover() == nil {
+			t.Error("NewServer accepted invalid config")
+		}
+	}()
+	a.NewServer("")
+}
+
+type httpConfigListener struct{ net.Listener }
+
+func (l httpConfigListener) Accept() (net.Conn, error) {
+	c, err := l.Listener.Accept()
+	if err == nil {
+		if tcp, ok := c.(*net.TCPConn); ok {
+			_ = tcp.SetWriteBuffer(32 << 10)
+		}
+	}
+	return c, err
+}
+
+func httpConfigConnection(t *testing.T, transport string, cfg omni.HTTPConfig, handler omni.Handler) net.Conn {
+	t.Helper()
+	a := omni.New(omni.WithTransport(transport), omni.WithHTTPConfig(cfg), omni.WithShutdownTimeout(time.Second))
+	a.GET("/", handler)
+	a.POST("/", handler)
+	l, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan error, 1)
+	go func() { done <- a.ServeContext(ctx, httpConfigListener{l}) }()
+	t.Cleanup(func() {
+		cancel()
+		select {
+		case err := <-done:
+			if err != nil {
+				t.Errorf("server shutdown: %v", err)
+			}
+		case <-time.After(3 * time.Second):
+			t.Error("server did not stop")
+		}
+	})
+	c, err := net.DialTimeout("tcp", l.Addr().String(), time.Second)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { c.Close() })
+	_ = c.SetDeadline(time.Now().Add(3 * time.Second))
+	return c
+}
+
+func TestHTTPConfiguredNetworkLimits(t *testing.T) {
+	for _, transport := range []string{omni.TransportNetHTTP, omni.TransportNative} {
+		t.Run(transport, func(t *testing.T) {
+			empty := func(c *omni.Context) error { w := c.Raw(); w.WriteHeader(204); return nil }
+			t.Run("slowHeaders", func(t *testing.T) {
+				c := httpConfigConnection(t, transport, omni.HTTPConfig{ReadHeaderTimeout: 60 * time.Millisecond}, empty)
+				if _, err := io.WriteString(c, "GET / HTTP/1.1\r\nHost: localhost\r\nX-Incomplete:"); err != nil {
+					t.Fatal(err)
+				}
+				_, err := io.ReadAll(c)
+				if e, ok := err.(net.Error); ok && e.Timeout() {
+					t.Fatal("server read-header timeout not applied")
+				}
+			})
+			t.Run("slowBody", func(t *testing.T) {
+				var accepted atomic.Bool
+				c := httpConfigConnection(t, transport, omni.HTTPConfig{ReadTimeout: 60 * time.Millisecond}, func(c *omni.Context) error {
+					_, err := io.ReadAll(c.Request().Body)
+					accepted.Store(err == nil)
+					return nil
+				})
+				if _, err := io.WriteString(c, "POST / HTTP/1.1\r\nHost: localhost\r\nConnection: close\r\nContent-Length: 10\r\n\r\nx"); err != nil {
+					t.Fatal(err)
+				}
+				_, err := io.ReadAll(c)
+				if e, ok := err.(net.Error); ok && e.Timeout() {
+					t.Fatal("read timeout not applied")
+				}
+				if accepted.Load() {
+					t.Fatal("incomplete body accepted")
+				}
+			})
+			t.Run("idle", func(t *testing.T) {
+				c := httpConfigConnection(t, transport, omni.HTTPConfig{IdleTimeout: 60 * time.Millisecond}, empty)
+				if _, err := io.WriteString(c, "GET / HTTP/1.1\r\nHost: localhost\r\n\r\n"); err != nil {
+					t.Fatal(err)
+				}
+				r, err := http.ReadResponse(bufio.NewReader(c), nil)
+				if err != nil {
+					t.Fatal(err)
+				}
+				r.Body.Close()
+				if r.StatusCode != 204 {
+					t.Fatal(r.StatusCode)
+				}
+				_, err = c.Read(make([]byte, 1))
+				if e, ok := err.(net.Error); ok && e.Timeout() {
+					t.Fatal("idle timeout not applied")
+				}
+				if err == nil {
+					t.Fatal("idle connection not closed")
+				}
+			})
+			t.Run("writeBackpressure", func(t *testing.T) {
+				done := make(chan error, 1)
+				c := httpConfigConnection(t, transport, omni.HTTPConfig{WriteTimeout: 60 * time.Millisecond}, func(c *omni.Context) error {
+					w := c.Raw()
+					w.WriteHeader(200)
+					if err := http.NewResponseController(w).Flush(); err != nil {
+						done <- err
+						return nil
+					}
+					_, err := io.Copy(w, io.LimitReader(repeatingHTTPReader{}, 64<<20))
+					done <- err
+					return nil
+				})
+				if tcp, ok := c.(*net.TCPConn); ok {
+					_ = tcp.SetReadBuffer(1024)
+				}
+				if _, err := io.WriteString(c, "GET / HTTP/1.1\r\nHost: localhost\r\n\r\n"); err != nil {
+					t.Fatal(err)
+				}
+				select {
+				case err := <-done:
+					if err == nil {
+						t.Fatal("write unexpectedly completed")
+					}
+				case <-time.After(2 * time.Second):
+					t.Fatal("write timeout not applied")
+				}
+			})
+			t.Run("headerLimit", func(t *testing.T) {
+				c := httpConfigConnection(t, transport, omni.HTTPConfig{MaxHeaderBytes: 1024}, empty)
+				if _, err := io.WriteString(c, "GET / HTTP/1.1\r\nHost: localhost\r\nX-Large: "+strings.Repeat("a", 8192)+"\r\n\r\n"); err != nil {
+					t.Fatal(err)
+				}
+				r, err := http.ReadResponse(bufio.NewReader(c), nil)
+				if err != nil {
+					t.Fatal(err)
+				}
+				r.Body.Close()
+				if r.StatusCode != 431 {
+					t.Fatalf("oversized header status: %d", r.StatusCode)
+				}
+			})
+		})
+	}
+}
+
+type repeatingHTTPReader struct{}
+
+func (repeatingHTTPReader) Read(b []byte) (int, error) {
+	for i := range b {
+		b[i] = 'x'
+	}
+	return len(b), nil
+}
--- a/app/router.go
+++ b/app/router.go
@@ -30,6 +30,9 @@ func (a *App) adaptResponse(encoder response.Encoder, handler httpx.Handler, mid
 			request = request.WithContext(httpx.WithClientIPResolver(request.Context(), a.clientIPResolver))
 		}
 		requestContext := httpx.NewContext(request, writer, httpx.RouteParams(request.Context()))
+		if provider, ok := a.responseEncoder.(response.ErrorRegistryProvider); ok {
+			requestContext.SetErrorRegistry(provider.ErrorRegistry())
+		}
 		requestContext.SetResponseEncoder(encoder)
 		defer func() { httpx.CleanupMultipart(requestContext.Request()) }()
 		if err := wrapped(requestContext); err != nil {
--- a/app/transport.go
+++ b/app/transport.go
@@ -57,6 +57,22 @@ func (a *App) prepareTransport() (func(context.Context, net.Listener) error, err
 	case config.TransportNative:
 		server := native.New(a)
 		server.ShutdownTimeout = shutdownTimeout
+		cfg := a.config.HTTP
+		if cfg.ReadHeaderTimeout > 0 {
+			server.ReadHeaderTimeout = cfg.ReadHeaderTimeout
+		}
+		if cfg.ReadTimeout > 0 {
+			server.ReadTimeout = cfg.ReadTimeout
+		}
+		if cfg.WriteTimeout > 0 {
+			server.WriteTimeout = cfg.WriteTimeout
+		}
+		if cfg.IdleTimeout > 0 {
+			server.IdleTimeout = cfg.IdleTimeout
+		}
+		if cfg.MaxHeaderBytes > 0 {
+			server.MaxHeaderBytes = cfg.MaxHeaderBytes
+		}
 		if tlsConfig != nil {
 			return func(ctx context.Context, listener net.Listener) error {
 				return server.ServeTLS(ctx, listener, tlsConfig)
@@ -66,6 +82,12 @@ func (a *App) prepareTransport() (func(context.Context, net.Listener) error, err
 	case config.TransportHTTP2:
 		server := h2transport.New(a)
 		server.ShutdownTimeout = shutdownTimeout
+		if a.config.HTTP.IdleTimeout > 0 {
+			server.IdleTimeout = a.config.HTTP.IdleTimeout
+		}
+		if a.config.HTTP.MaxHeaderBytes > 0 {
+			server.MaxHeaderBytes = a.config.HTTP.MaxHeaderBytes
+		}
 		return func(ctx context.Context, listener net.Listener) error {
 			return server.ServeTLS(ctx, listener, tlsConfig)
 		}, nil
--- a/cmd/go-omni/README.md
+++ b/cmd/go-omni/README.md
@@ -21,6 +21,8 @@ go run ./cmd/go-omni api validate --api examples/contracts/user.api
 后续在生成项目内执行 `go-omni api generate --api api/user.api --dir .`。
 项目内可省略 `--api` / `--dir`。`api inspect` 展示路由和鉴权/业务错误，`api export` 向 stdout 导出 OpenAPI，`api generate --dry-run` 预览文件变化。`--check` 只读检查生成产物是否过期。生成器记录所有权，保留 Service / Repository / 配置 / main 的手写内容，遇到生成文件被手动修改则报冲突。新 Service 与中间件占位实现返回 501。支持 `error (...)`、具名 `auth`、路由 `@errors` / `@auth` 和多行 `@doc`；错误目录同步生成 `internal/apierrors` 调用函数。

+`v0.10.0-preview` 新增 `errorCatalog`：集中配置业务码、提示和 HTTP 状态，支持默认 HTTP 200 与单条覆盖，生成函数、路由策略和 OpenAPI 共用一份定义。语法及配置方式见 [统一错误目录](../../errors/README.md)。
+
 支持范围、参数语义、目录及安全更新策略见 [API 开发指南](../../API.md)。本版借鉴 go-zero 的工作流，不宣称兼容全部 goctl 语法；仍通过 Omni/httpx 保留网络层替换能力。

 ## 日志与对象存储按需装配
@@ -75,8 +77,8 @@ Handler / Service / Repository / Model 与模块注册入口。模块名为 lowe
 从远程安装，生成一个带 Handler / Service / Repository / Model 分层的服务骨架：

 ```sh
-GOPRIVATE=git.yuntuo.hk go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.9.0-preview
-go-omni new --framework-version v0.9.0-preview --module example.com/billing ./billing
+GOPRIVATE=git.yuntuo.hk go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.10.0-preview
+go-omni new --framework-version v0.10.0-preview --module example.com/billing ./billing
 cd billing
 go mod tidy
 go run ./cmd/server
--- a/cmd/go-omni/apigen/contractMetadata.go
+++ b/cmd/go-omni/apigen/contractMetadata.go
@@ -8,6 +8,7 @@ import (
 	"sort"
 	"strings"

+	apierrors "git.yuntuo.hk/k2safe/go-omni/errors"
 	"git.yuntuo.hk/k2safe/go-omni/openapi"
 	"git.yuntuo.hk/k2safe/go-omni/response"
 )
@@ -20,14 +21,18 @@ var credentialName = regexp.MustCompile("^[!#$%&'*+.^_`|~0-9A-Za-z-]+$")
 func prepareMetadata(original *Spec) (*Spec, error) {
 	spec := *original
 	spec.Routes = append([]Route(nil), original.Routes...)
+	spec.Errors = append([]ErrorDefinition(nil), original.Errors...)
 	if err := validateResponses(&spec); err != nil {
 		return nil, err
 	}
 	definitions := map[string]ErrorDefinition{}
-	codes, symbols := map[string]bool{}, map[string]bool{}
+	codes, symbols := map[string]bool{}, map[string]bool{"Catalog": true}
 	for _, e := range spec.Errors {
-		if !exportedName.MatchString(e.Name) || e.Status < 400 || e.Status > 599 || !errorCode.MatchString(e.Code) || strings.TrimSpace(e.Message) == "" {
-			return nil, fmt.Errorf("%s: error requires UpperCamelCase name, status 400..599, UPPER_SNAKE_CASE code and a nonempty public message", e.Position)
+		if !exportedName.MatchString(e.Name) || !apierrors.ValidErrorStatus(e.Status) || strings.TrimSpace(e.Message) == "" {
+			return nil, fmt.Errorf("%s: error requires UpperCamelCase name, a final body-bearing status (200..599 except 204/205/304) and a nonempty public message", e.Position)
+		}
+		if e.Catalog == "" && !errorCode.MatchString(e.Code) {
+			return nil, fmt.Errorf("%s: legacy error declaration requires UPPER_SNAKE_CASE code", e.Position)
 		}
 		if codes[e.Code] {
 			return nil, fmt.Errorf("%s: duplicate error code %s", e.Position, e.Code)
@@ -41,6 +46,17 @@ func prepareMetadata(original *Spec) (*Spec, error) {
 		codes[e.Code] = true
 		definitions[e.Name] = e
 	}
+	registry, err := apierrors.NewRegistry(errorCatalog(&spec, nil))
+	if err != nil {
+		return nil, err
+	}
+	normalized := registry.Catalog()
+	for i := range spec.Errors {
+		spec.Errors[i].BusinessCode = normalized.Definitions[spec.Errors[i].Code].Code
+	}
+	if err := validateErrorPolicies(&spec); err != nil {
+		return nil, err
+	}
 	auth := map[string]AuthDefinition{}
 	for _, a := range spec.Auth {
 		if !exportedName.MatchString(a.Name) || !goName.MatchString(a.Middleware) || strings.EqualFold(a.Middleware, "defaults") || strings.EqualFold(a.Middleware, "registryGen") {
@@ -84,7 +100,7 @@ func prepareMetadata(original *Spec) (*Spec, error) {
 		seen := map[string]bool{}
 		for _, name := range r.Errors {
 			if _, ok := definitions[name]; !ok {
-				return nil, fmt.Errorf("%s: unknown error %s; declare it in error (...)", r.Position, name)
+				return nil, fmt.Errorf("%s: unknown error %s; declare it in errorCatalog or error (...)", r.Position, name)
 			}
 			if seen[name] {
 				return nil, fmt.Errorf("%s: duplicate error %s", r.Position, name)
@@ -182,11 +198,31 @@ func decorateDocument(doc map[string]any, spec *Spec) {
 				response = genericErrorResponse(http.StatusText(status), cfg)
 				responses[key] = response
 			}
-			media := response["content"].(map[string]any)["application/json"].(map[string]any)
+			content, ok := response["content"].(map[string]any)
+			if !ok {
+				content = map[string]any{}
+				response["content"] = content
+			}
+			media, hasJSON := content["application/json"].(map[string]any)
+			if !hasJSON {
+				media = map[string]any{}
+				content["application/json"] = media
+			}
+			errorMedia := genericErrorResponse("", cfg)["content"].(map[string]any)["application/json"].(map[string]any)
+			if exists && status < 400 && media["schema"] != nil {
+				media["schema"] = map[string]any{"anyOf": []any{media["schema"], errorMedia["schema"]}}
+			} else if media["schema"] == nil {
+				media["schema"] = errorMedia["schema"]
+			}
 			examples := map[string]any{}
 			codes := []any{}
 			seenCodes := map[string]bool{}
 			description := []string{}
+			if exists {
+				if text, ok := response["description"].(string); ok && text != "" {
+					description = append(description, text)
+				}
+			}
 			sort.Slice(errs, func(i, j int) bool { return errs[i].Name < errs[j].Name })
 			for _, e := range errs {
 				value := policy.Value(responseResult(e))
@@ -207,7 +243,7 @@ func decorateDocument(doc map[string]any, spec *Spec) {
 	}
 }
 func responseResult(e ErrorDefinition) response.Result {
-	return response.Result{Status: e.Status, Code: e.Code, Message: e.Message, RequestID: "exampleRequest"}
+	return response.Result{Status: e.Status, Code: e.Code, Message: e.Message, BusinessCode: e.BusinessCode, Failed: true, RequestID: "exampleRequest"}
 }
 func genericErrorResponse(description string, cfg response.Config) map[string]any {
 	if description == "" {
--- a/cmd/go-omni/apigen/declarations.go
+++ b/cmd/go-omni/apigen/declarations.go
@@ -10,6 +10,8 @@ import (
 // a fresh error each time so WithCause cannot mutate a shared singleton.
 type ErrorDefinition struct {
 	Name         string `json:"name"`
+	BusinessCode any    `json:"businessCode,omitempty"`
+	Catalog      string `json:"catalog,omitempty"`
 	Status       int    `json:"status"`
 	Code         string `json:"code"`
 	Message      string `json:"message"`
--- a/cmd/go-omni/apigen/errorCatalog.go
+++ b/cmd/go-omni/apigen/errorCatalog.go
@@ -0,0 +1,118 @@
+package apigen
+
+import (
+	"encoding/json"
+	"fmt"
+	"sort"
+	"strconv"
+
+	apierrors "git.yuntuo.hk/k2safe/go-omni/errors"
+	"git.yuntuo.hk/k2safe/go-omni/response"
+)
+
+// A named catalog groups project definitions under one default HTTP status.
+// Each JSON object key supplies the generated Go function's name, while key is
+// the independent logical identifier and code is the public string/integer.
+func (p *parser) parseErrorCatalog() error {
+	pos := p.next().position
+	name, err := p.ident()
+	if err != nil {
+		return err
+	}
+	if !exportedName.MatchString(name) {
+		return p.err("errorCatalog requires an UpperCamelCase name")
+	}
+	for _, prior := range p.spec.ErrorCatalogs {
+		if prior == name {
+			return p.err("duplicate errorCatalog " + name)
+		}
+	}
+	p.spec.ErrorCatalogs = append(p.spec.ErrorCatalogs, name)
+	p.skip()
+	props, err := p.metadata()
+	if err != nil {
+		return err
+	}
+	defaultStatus := 400
+	if value, ok := props["defaultStatus"]; ok {
+		defaultStatus, err = strconv.Atoi(value)
+		if err != nil {
+			return p.err("defaultStatus must be an integer")
+		}
+	}
+	if !apierrors.ValidErrorStatus(defaultStatus) {
+		return p.err("invalid errorCatalog defaultStatus")
+	}
+	for key := range props {
+		if key != "defaultStatus" && key != "errors" {
+			return p.err("unsupported errorCatalog property " + key)
+		}
+	}
+	type entry struct {
+		Key     string `json:"key"`
+		Code    any    `json:"code"`
+		Message string `json:"message"`
+		Status  int    `json:"status"`
+	}
+	var entries map[string]entry
+	if err := apierrors.DecodeCatalogJSON([]byte(props["errors"]), &entries); err != nil {
+		return fmt.Errorf("%s: catalog %s: %w", pos, name, err)
+	}
+	if len(entries) == 0 {
+		return p.err("errorCatalog requires errors")
+	}
+	names := make([]string, 0, len(entries))
+	for key := range entries {
+		names = append(names, key)
+	}
+	sort.Strings(names)
+	for _, fn := range names {
+		e := entries[fn]
+		if e.Code == nil {
+			return p.err("errorCatalog error requires code")
+		}
+		if e.Status == 0 {
+			e.Status = defaultStatus
+		}
+		p.spec.Errors = append(p.spec.Errors, ErrorDefinition{Name: fn, Status: e.Status, Code: e.Key, Message: e.Message, BusinessCode: e.Code, Catalog: name, Position: pos})
+	}
+	return nil
+}
+
+func errorCatalog(spec *Spec, names []string) apierrors.Catalog {
+	c := apierrors.Catalog{Definitions: map[string]apierrors.Definition{}}
+	selected := map[string]bool{}
+	for _, n := range names {
+		selected[n] = true
+	}
+	for _, e := range spec.Errors {
+		if names != nil && !selected[e.Name] {
+			continue
+		}
+		c.Definitions[e.Code] = apierrors.Definition{Status: e.Status, Code: e.BusinessCode, Message: e.Message}
+	}
+	return c
+}
+
+// Validate the exact catalog/template pair used by each route. Different routes
+// can use different code types without forcing a global response representation.
+func validateErrorPolicies(spec *Spec) error {
+	for _, r := range spec.Routes {
+		f, err := response.New(responseConfig(spec, r))
+		if err != nil {
+			return err
+		}
+		if _, err = response.WithErrors(errorCatalog(spec, append([]string{}, r.Errors...)), f); err != nil {
+			return fmt.Errorf("%s: %w", r.Position, err)
+		}
+	}
+	return nil
+}
+
+func errorCatalogJSON(spec *Spec, names []string) string {
+	data, err := json.Marshal(errorCatalog(spec, names))
+	if err != nil {
+		panic(err)
+	}
+	return string(data)
+}
--- a/cmd/go-omni/apigen/errorCatalog_test.go
+++ b/cmd/go-omni/apigen/errorCatalog_test.go
@@ -0,0 +1,205 @@
+package apigen
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestErrorCatalogDocumentAndValidation(t *testing.T) {
+	path := filepath.Join(frameworkRoot(t), "examples/contracts/errors.api")
+	source := readFile(t, path)
+	spec, err := Parse(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	compiled, err := Compile(spec)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, path := range []string{"/token", "/raw"} {
+		method := "post"
+		if path == "/raw" {
+			method = "get"
+		}
+		op := operation(t, document(t, compiled), path, method)
+		response := op["responses"].(map[string]any)["200"].(map[string]any)
+		media := response["content"].(map[string]any)["application/json"].(map[string]any)
+		alternatives := media["schema"].(map[string]any)["anyOf"].([]any)
+		if len(alternatives) != 2 {
+			t.Fatal("lost success or failure shape")
+		}
+		if path == "/raw" {
+			if alternatives[0].(map[string]any)["properties"].(map[string]any)["token"] == nil {
+				t.Fatal("raw success wrapped")
+			}
+		}
+		examples := media["examples"].(map[string]any)
+		if len(examples) != 2 {
+			t.Fatal(examples)
+		}
+		for _, name := range []string{"UsernameInvalid", "PasswordInvalid"} {
+			value := examples[name].(map[string]any)["value"].(map[string]any)
+			if value["ok"] != false || value["code"] != float64(400002) || value["msg"] == nil {
+				t.Fatal(value)
+			}
+		}
+	}
+	for _, change := range [][2]string{
+		{`defaultStatus: 200`, `defaultStatus: 204`},
+		{`"status": 403`, `"status": 304`},
+		{`"PASSWORD_INVALID"`, `"USERNAME_INVALID"`},
+		{`"code": 400002`, `"code": 2147483648`},
+		{`"code": 400002`, `"code": "400002"`},
+		{`"code": 400002`, `"code": 1.5`},
+		{`"code": 400002`, `"code": null`},
+		{`"code": 400002`, `"code": 400002, "code": 400003`},
+		{`"message": "用户名格式不正确"`, `"message": "用户名格式不正确", "typo": true`},
+		{`@handler token`, `@errors Unknown\n    @handler token`},
+		{`successCode: 0`, `successCode: 0\n    codes: {"USERNAME_INVALID": 999}`},
+	} {
+		text := strings.Replace(source, change[0], strings.ReplaceAll(change[1], `\n`, "\n"), 1)
+		s, err := parseText(t, text)
+		if err == nil {
+			_, err = Compile(s)
+		}
+		if err == nil {
+			t.Errorf("accepted %s", change[1])
+		}
+	}
+	// The legacy declaration is also allowed to carry a HTTP 200 failure.
+	old := strings.Replace(declaredAPI, "EmailTaken 409", "EmailTaken 200", 1)
+	s, err := parseText(t, old)
+	if err == nil {
+		_, err = Compile(s)
+	}
+	if err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestErrorCatalogConsumer(t *testing.T) {
+	if os.Getenv("GO_OMNI_SCAFFOLD_INTEGRATION") == "" {
+		t.Skip("consumer integration")
+	}
+	root := frameworkRoot(t)
+	dir := filepath.Join(t.TempDir(), "consumer")
+	opts := Options{API: filepath.Join(root, "examples/contracts/errors.api"), Dir: dir, Module: "example.com/errorCatalog", FrameworkDir: root}
+	cli := os.Getenv("GO_OMNI_RELEASE_CLI")
+	generate := func(check bool) {
+		t.Helper()
+		if cli == "" {
+			o := opts
+			o.Check = check
+			if _, err := Generate(o); err != nil {
+				t.Fatal(err)
+			}
+			return
+		}
+		args := []string{"api", "generate", "--api", opts.API, "--dir", dir, "--module", opts.Module}
+		if check {
+			args = append(args, "--check")
+		}
+		cmd := exec.Command(cli, args...)
+		cmd.Dir = filepath.Dir(dir)
+		if output, err := cmd.CombinedOutput(); err != nil {
+			t.Fatalf("release generate %v\n%s", err, output)
+		}
+	}
+	generate(false)
+
+	fixture := readFile(t, "testdata/errorCatalog/consumer_test.go")
+	writeFile(t, filepath.Join(dir, "consumer_test.go"), fixture)
+	generate(false)
+	generate(true)
+	if readFile(t, filepath.Join(dir, "consumer_test.go")) != fixture {
+		t.Fatal("regeneration overwrote manual code")
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 120*time.Second)
+	defer cancel()
+	cmd := exec.CommandContext(ctx, "go", "test", "-race", "-mod=mod", "-count=1", "./...")
+	cmd.Dir = dir
+	cmd.Env = append(os.Environ(), "GOWORK=off")
+	if output, err := cmd.CombinedOutput(); err != nil {
+		t.Fatalf("consumer %v\n%s", err, output)
+	}
+	if cli != "" {
+		cmd = exec.CommandContext(ctx, "go", "list", "-m", "-json", frameworkModule)
+		cmd.Dir = dir
+		cmd.Env = append(os.Environ(), "GOWORK=off")
+		output, err := cmd.CombinedOutput()
+		if err != nil {
+			t.Fatal(err, string(output))
+		}
+		var module struct {
+			Version, Sum string
+			Replace      any
+		}
+		if err = json.Unmarshal(output, &module); err != nil {
+			t.Fatal(err)
+		}
+		if module.Version != os.Getenv("GO_OMNI_RELEASE_VERSION") || module.Replace != nil || module.Sum == "" {
+			t.Fatal("not a fixed remote consumer")
+		}
+		t.Logf("remote framework %s checksum %s; no local replace", module.Version, module.Sum)
+	}
+}
+
+func TestErrorCatalogImportsAndRouteScopes(t *testing.T) {
+	dir := t.TempDir()
+	writeFile(t, filepath.Join(dir, "common.api"), `errorCatalog Numeric (
+ defaultStatus: 200
+ errors: {"NumberInvalid":{"key":"number.invalid","code":12,"message":"number"}}
+)
+errorCatalog Text (
+ defaultStatus: 409
+ errors: {"TextInvalid":{"key":"textInvalid","code":"000012","message":"text"}}
+)
+response NumericResponse (
+ codeType: int32
+ successCode: 0
+ errorCode: 9999
+)
+`)
+	writeFile(t, filepath.Join(dir, "service.api"), `import "common.api"
+@server (
+ response: NumericResponse
+ errors: NumberInvalid
+)
+service scopes-api {
+ @handler numeric
+ get /number
+}
+@server (
+ errors: TextInvalid
+)
+service scopes-api {
+ @handler text
+ get /text
+}
+`)
+	s, err := Parse(filepath.Join(dir, "service.api"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	compiled, err := Compile(s)
+	if err != nil {
+		t.Fatal(err)
+	}
+	doc := document(t, compiled)
+	for _, tc := range []struct {
+		path, status, name string
+		code               any
+	}{{"/number", "200", "NumberInvalid", float64(12)}, {"/text", "409", "TextInvalid", "000012"}} {
+		response := operation(t, doc, tc.path, "get")["responses"].(map[string]any)[tc.status].(map[string]any)
+		value := response["content"].(map[string]any)["application/json"].(map[string]any)["examples"].(map[string]any)[tc.name].(map[string]any)["value"].(map[string]any)
+		if value["code"] != tc.code {
+			t.Fatal(value)
+		}
+	}
+}
--- a/cmd/go-omni/apigen/generate.go
+++ b/cmd/go-omni/apigen/generate.go
@@ -19,7 +19,7 @@ import (
 )

 const frameworkModule = "git.yuntuo.hk/k2safe/go-omni"
-const minimumVersion = "v0.9.0-preview"
+const minimumVersion = "v0.10.0-preview"
 const generatedHeader = "// Code generated by go-omni api. DO NOT EDIT.\n"

 type Options struct {
@@ -140,13 +140,13 @@ func generate(o Options, c *Compiled, starter bool) (Output, error) {
 					if !filepath.IsAbs(path) {
 						path = filepath.Join(directory, path)
 					}
-					if _, err := os.Stat(filepath.Join(path, "contract", "scalar.go")); err == nil {
+					if _, err := os.Stat(filepath.Join(path, "errors", "catalog.go")); err == nil {
 						localCurrent = true
 					}
 				}
 			}
 			if !localCurrent {
-				return Output{}, fmt.Errorf("existing framework dependency predates migration extensions; use %s or a current local replacement", minimumVersion)
+				return Output{}, fmt.Errorf("existing framework dependency predates error catalog support; use %s or a current local replacement", minimumVersion)
 			}
 		}
 		if o.FrameworkDir != "" {
@@ -312,12 +312,14 @@ func renderProject(o Options, c *Compiled, starter bool) (map[string][]byte, map
 	generated, seeds := map[string][]byte{}, map[string][]byte{}
 	put := func(files map[string][]byte, name, content string) { files[name] = []byte(content) }
 	if len(c.Spec.Errors) > 0 {
-		content := "package apierrors\nimport omnierrors " + strconv.Quote(frameworkModule+"/errors") + "\n"
+		content := "package apierrors\nimport(\"encoding/json\"; omnierrors " + strconv.Quote(frameworkModule+"/errors") + ")\n"
+		content += fmt.Sprintf("func Catalog()omnierrors.Catalog{var c omnierrors.Catalog;if err:=json.Unmarshal([]byte(%q),&c);err!=nil{panic(err)};return c}\nvar errorRegistry=omnierrors.MustRegistry(Catalog())\n", errorCatalogJSON(c.Spec, nil))
 		for _, e := range c.Spec.Errors {
-			content += fmt.Sprintf("const Code%s = %q\n// %s returns a fresh public error declared in the API contract.\nfunc %s()*omnierrors.APIError{return omnierrors.New(%d,Code%s,%q)}\n", e.Name, e.Code, e.Name, e.Name, e.Status, e.Name, e.Message)
+			content += fmt.Sprintf("const Code%s=%q\nfunc %s()*omnierrors.APIError{return errorRegistry.Resolve(omnierrors.ByCode(Code%s))}\n", e.Name, e.Code, e.Name, e.Name)
 		}
 		put(generated, "internal/apierrors/errorsGen.go", generatedHeader+content)
 	}
+
 	types := "package types\n\n"
 	if len(c.Spec.Scalars) > 0 {
 		types += "import("
@@ -343,7 +345,7 @@ func renderProject(o Options, c *Compiled, starter bool) (map[string][]byte, map
 	put(generated, "internal/types/typesGen.go", generatedHeader+types)
 	put(generated, "docs/openapi.json", string(c.Document)+"\n")
 	put(generated, "internal/handler/openapiGen.go", generatedHeader+fmt.Sprintf("package handler\nimport (\"net/http\"; %q)\nconst OpenAPIDocument = %q\nfunc OpenAPI(c *httpx.Context) error { return c.WriteResponse(200,http.Header{\"Content-Type\": {\"application/json; charset=utf-8\"}},[]byte(OpenAPIDocument)) }\n", frameworkModule+"/httpx", string(c.Document)+"\n"))
-	policySource := fmt.Sprintf("package handler\nimport(\"encoding/json\";\"strings\";%q)\nvar responseTemplates=map[string]response.Encoder{\"\":response.Default(),\n", frameworkModule+"/response")
+	policySource := fmt.Sprintf("package handler\nimport(\"encoding/json\";\"strings\";%q; omnierrors %q)\nvar responseTemplates=map[string]response.Encoder{\"\":response.Default(),\n", frameworkModule+"/response", frameworkModule+"/errors")
 	for _, definition := range c.Spec.Responses {
 		data, err := json.Marshal(definition.Config)
 		if err != nil {
@@ -351,7 +353,8 @@ func renderProject(o Options, c *Compiled, starter bool) (map[string][]byte, map
 		}
 		policySource += fmt.Sprintf("%q: newResponseTemplate(%q),\n", definition.Name, string(data))
 	}
-	policySource += "}\nfunc newResponseTemplate(raw string)response.Encoder{var cfg response.Config;decoder:=json.NewDecoder(strings.NewReader(raw));decoder.UseNumber();if err:=decoder.Decode(&cfg);err!=nil{panic(err)};return response.MustNew(cfg)}\nfunc responseEncoder(name string,raw bool)response.Encoder{encoder:=responseTemplates[name];if encoder==nil{panic(\"unknown response template\")};if raw{encoder=response.RawJSON(encoder)};return encoder}\n"
+	policySource += "}\nfunc newResponseTemplate(raw string)response.Encoder{var cfg response.Config;decoder:=json.NewDecoder(strings.NewReader(raw));decoder.UseNumber();if err:=decoder.Decode(&cfg);err!=nil{panic(err)};return response.MustNew(cfg)}\n"
+	policySource += "func responseEncoder(name string,raw bool,catalogJSON string)response.Encoder{encoder:=responseTemplates[name];if encoder==nil{panic(\"unknown response template\")};var catalog omnierrors.Catalog;if err:=json.Unmarshal([]byte(catalogJSON),&catalog);err!=nil{panic(err)};encoder=response.MustWithErrors(catalog,encoder);if raw{encoder=response.RawJSON(encoder)};return encoder}\n"
 	put(generated, "internal/handler/responseGen.go", generatedHeader+policySource)
 	imports := fmt.Sprintf("import (\"fmt\"; %q; %q; %q;", frameworkModule+"/httpx", frameworkModule+"/openapi", o.Module+"/internal/servicecontext")
 	routes := "func RegisterRoutes(router openapi.Registrar, deps *servicecontext.Context) error {\n if router==nil || deps==nil {return fmt.Errorf(\"router and dependencies required\")}\n"
@@ -412,9 +415,9 @@ func renderProject(o Options, c *Compiled, starter bool) (map[string][]byte, map
 			name := upper(r.Handler)
 			// The response policy and body reader cap are installed before App middleware.
 			if r.MaxBodyBytes > 0 {
-				routes += fmt.Sprintf("httpx.HandleWithBodyLimit(router,%q,%q,%d,responseEncoder(%q,%t),h%d.%s", strings.ToUpper(r.Method), r.Path, r.MaxBodyBytes, responseName(r), r.ResponseFormat == "raw", i, name)
+				routes += fmt.Sprintf("httpx.HandleWithBodyLimit(router,%q,%q,%d,responseEncoder(%q,%t,%q),h%d.%s", strings.ToUpper(r.Method), r.Path, r.MaxBodyBytes, responseName(r), r.ResponseFormat == "raw", errorCatalogJSON(c.Spec, append([]string{}, r.Errors...)), i, name)
 			} else {
-				routes += fmt.Sprintf("httpx.HandleWithResponse(router,%q,%q,responseEncoder(%q,%t),h%d.%s", strings.ToUpper(r.Method), r.Path, responseName(r), r.ResponseFormat == "raw", i, name)
+				routes += fmt.Sprintf("httpx.HandleWithResponse(router,%q,%q,responseEncoder(%q,%t,%q),h%d.%s", strings.ToUpper(r.Method), r.Path, responseName(r), r.ResponseFormat == "raw", errorCatalogJSON(c.Spec, append([]string{}, r.Errors...)), i, name)
 			}
 			for _, m := range r.Middleware {
 				routes += fmt.Sprintf(",deps.Middlewares[%q]", m)
--- a/cmd/go-omni/apigen/metadata_test.go
+++ b/cmd/go-omni/apigen/metadata_test.go
@@ -137,7 +137,7 @@ func TestDeclaredErrorsAndAuthentication(t *testing.T) {
 func TestInvalidDeclarations(t *testing.T) {
 	replacements := [][2]string{
 		{`"EMAIL_TAKEN"`, `"UNAUTHENTICATED"`},
-		{`EmailTaken 409`, `EmailTaken 200`},
+		{`EmailTaken 409`, `EmailTaken 204`},
 		{`EmailTaken 409`, `emailTaken 409`},
 		{`NameTaken 409`, `CodeEmailTaken 409`},
 		{`auth: UserAuth`, `auth: Unknown`},
--- a/cmd/go-omni/apigen/parse.go
+++ b/cmd/go-omni/apigen/parse.go
@@ -16,6 +16,7 @@ import (
 type Spec struct {
 	Title, Version, Service, Description string
 	Errors                               []ErrorDefinition
+	ErrorCatalogs                        []string
 	Auth                                 []AuthDefinition
 	Responses                            []ResponseDefinition
 	Scalars                              []ScalarDefinition
@@ -266,6 +267,10 @@ func (p *parser) parse() error {
 				}
 				p.imports = append(p.imports, v)
 			}
+		case "errorCatalog":
+			if err := p.parseErrorCatalog(); err != nil {
+				return err
+			}
 		case "error":
 			if err := p.parseErrors(); err != nil {
 				return err
--- a/cmd/go-omni/apigen/testdata/errorCatalog/consumer_test.go
+++ b/cmd/go-omni/apigen/testdata/errorCatalog/consumer_test.go
@@ -0,0 +1,92 @@
+package consumer_test
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"example.com/errorCatalog/internal/apierrors"
+	"example.com/errorCatalog/internal/handler"
+	"example.com/errorCatalog/internal/servicecontext"
+	omni "git.yuntuo.hk/k2safe/go-omni"
+	omnierrors "git.yuntuo.hk/k2safe/go-omni/errors"
+	"git.yuntuo.hk/k2safe/go-omni/httpx"
+	"git.yuntuo.hk/k2safe/go-omni/logx"
+)
+
+func TestGeneratedCatalog(t *testing.T) {
+	first := apierrors.UsernameInvalid().WithCause(errors.New("private"))
+	second := apierrors.UsernameInvalid()
+	if first == second || second.Cause != nil || second.Status != 200 || second.BusinessCode != int64(400002) {
+		t.Fatal("shared or incomplete generated error")
+	}
+	copy := apierrors.Catalog()
+	delete(copy.Definitions, apierrors.CodeUsernameInvalid)
+	if len(apierrors.Catalog().Definitions) != 3 {
+		t.Fatal("shared catalog")
+	}
+	cfg := logx.Default()
+	cfg.Writer = io.Discard
+	logger, err := logx.New(cfg)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer logger.Close()
+	deps, err := servicecontext.New(context.Background(), logger)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer deps.Close()
+	app := omni.New()
+	defer app.Close()
+	// Global middleware exits early: generated route policy must already be active.
+	app.Use(func(next httpx.Handler) httpx.Handler {
+		return func(c *httpx.Context) error {
+			switch c.Header("X-Fixture") {
+			case "username":
+				return omnierrors.ByCode(apierrors.CodeUsernameInvalid).WithCause(errors.New("private"))
+			case "password":
+				return apierrors.PasswordInvalid()
+			case "denied":
+				return apierrors.PermissionDenied()
+			case "unknown":
+				return omnierrors.ByCode("MISSING")
+			default:
+				return c.OK(map[string]string{"token": "ok"})
+			}
+		}
+	})
+	if err := handler.RegisterRoutes(app, deps); err != nil {
+		t.Fatal(err)
+	}
+	for _, path := range []string{"/token", "/raw"} {
+		for _, test := range []struct {
+			kind   string
+			status int
+			want   string
+		}{{"username", 200, "用户名格式不正确"}, {"password", 200, "密码格式不正确"}, {"denied", 403, "没有权限"}, {"unknown", 500, "internal server error"}, {"", 200, `"token":"ok"`}} {
+			method := "POST"
+			if path == "/raw" {
+				method = "GET"
+			}
+			w := httptest.NewRecorder()
+			r := httptest.NewRequest(method, path, nil)
+			r.Header.Set("X-Fixture", test.kind)
+			app.ServeHTTP(w, r)
+			if w.Code != test.status || !strings.Contains(w.Body.String(), test.want) || strings.Contains(w.Body.String(), "private") {
+				t.Fatal(path, test.kind, w.Code, w.Body.String())
+			}
+			if test.kind == "username" || test.kind == "password" {
+				if !strings.Contains(w.Body.String(), `"code":400002`) || !strings.Contains(w.Body.String(), `"ok":false`) {
+					t.Fatal(w.Body.String())
+				}
+			}
+			if path == "/raw" && test.kind == "" && strings.Contains(w.Body.String(), "code") {
+				t.Fatal("raw success wrapped")
+			}
+		}
+	}
+}
--- a/cmd/go-omni/scaffold/version.go
+++ b/cmd/go-omni/scaffold/version.go
@@ -10,7 +10,7 @@ const frameworkModule = "git.yuntuo.hk/k2safe/go-omni"
 // Source builds can carry an unpublished VCS version (including +dirty).
 // Keep this fallback in sync with the next release; installed CLIs use their
 // downloaded module version, which also has a module checksum.
-const defaultFrameworkVersion = "v0.9.0-preview"
+const defaultFrameworkVersion = "v0.10.0-preview"

 // This target is not a claim that the release already exists. Source users
 // select a local framework checkout until the module templates are published.
--- a/config/config.go
+++ b/config/config.go
@@ -4,6 +4,7 @@ import (
 	"strings"
 	"time"

+	apierrors "git.yuntuo.hk/k2safe/go-omni/errors"
 	"git.yuntuo.hk/k2safe/go-omni/httpx"
 	"git.yuntuo.hk/k2safe/go-omni/logx"
 	"git.yuntuo.hk/k2safe/go-omni/response"
@@ -28,12 +29,14 @@ type Config struct {
 	Address              string            `json:"address"`
 	Transport            string            `json:"transport"`
 	TLS                  TLSConfig         `json:"tls"`
+	HTTP                 HTTPConfig        `json:"http"`
 	RequestIDHeader      string            `json:"requestIdHeader"`
 	EnableLogger         bool              `json:"enableLogger"`
 	SlowRequestThreshold time.Duration     `json:"slowRequestThreshold"`
 	TrustedProxies       []string          `json:"trustedProxies"`
 	ShutdownTimeout      time.Duration     `json:"shutdownTimeout"`
 	Log                  logx.Config       `json:"log"`
+	Errors               apierrors.Catalog `json:"errors"`
 	Response             response.Config   `json:"response"`
 	ResponseEncoder      response.Encoder  `json:"-"`
 }
@@ -50,6 +53,18 @@ func Default() Config {

 // Validate checks configuration values before an application starts.
 func (c Config) Validate() error {
+	if err := c.Errors.Validate(); err != nil {
+		return err
+	}
+	if c.ResponseEncoder == nil {
+		f, err := response.New(c.Response)
+		if err != nil {
+			return err
+		}
+		if err = f.ValidateErrors(c.Errors); err != nil {
+			return err
+		}
+	}
 	if err := c.Response.Validate(); err != nil {
 		return err
 	}
@@ -74,11 +89,20 @@ func (c Config) Validate() error {
 // ValidateTransport checks built-in transport selection without opening files
 // or sockets. Empty Transport preserves the standard net/http default.
 func (c Config) ValidateTransport() error {
+	if err := c.HTTP.Validate(); err != nil {
+		return err
+	}
 	switch c.Transport {
 	case "", TransportNetHTTP, TransportNative, TransportHTTP2:
 	default:
 		return &ConfigError{Field: "transport", Message: "must be nethttp, native or http2"}
 	}
+	if c.Transport == TransportHTTP2 && (c.HTTP.ReadHeaderTimeout > 0 || c.HTTP.ReadTimeout > 0 || c.HTTP.WriteTimeout > 0) {
+		return &ConfigError{Field: "http", Message: "readHeaderTimeout, readTimeout and writeTimeout are not supported by the experimental http2 transport"}
+	}
+	if c.HTTP.ErrorLog != nil && c.Transport != "" && c.Transport != TransportNetHTTP {
+		return &ConfigError{Field: "http.errorLog", Message: "is supported only by the nethttp transport"}
+	}
 	cert, key := strings.TrimSpace(c.TLS.CertFile), strings.TrimSpace(c.TLS.KeyFile)
 	if (cert == "") != (key == "") {
 		return &ConfigError{Field: "tls", Message: "requires both certFile and keyFile"}
@@ -141,11 +165,13 @@ func WithTrustedProxies(proxies ...string) Option {
 // environment. Later options can still override individual fields.
 func WithConfig(settings Config) Option {
 	settings.Response = settings.Response.Clone()
+	settings.Errors = settings.Errors.Clone()
 	settings.TrustedProxies = append([]string(nil), settings.TrustedProxies...)
 	settings.Log.RedactKeys = append([]string(nil), settings.Log.RedactKeys...)
 	return func(cfg *Config) {
 		*cfg = settings
 		cfg.Response = settings.Response.Clone()
+		cfg.Errors = settings.Errors.Clone()
 		cfg.TrustedProxies = append([]string(nil), settings.TrustedProxies...)
 		cfg.Log.RedactKeys = append([]string(nil), settings.Log.RedactKeys...)
 	}
@@ -180,3 +206,9 @@ func WithShutdownTimeout(timeout time.Duration) Option {
 		}
 	}
 }
+
+// WithErrors installs a project-owned, app-local catalog.
+func WithErrors(catalog apierrors.Catalog) Option {
+	catalog = catalog.Clone()
+	return func(cfg *Config) { cfg.Errors = catalog.Clone() }
+}
--- a/config/env.go
+++ b/config/env.go
@@ -19,6 +19,7 @@ func LoadFromEnv(prefix string) (Config, error) {
 // ApplyEnv overlays nonempty environment values on a caller's defaults or file
 // settings, then validates the result. Caller-owned slices are not retained.
 func ApplyEnv(defaults Config, prefix string) (Config, error) {
+	defaults.Errors = defaults.Errors.Clone()
 	defaults.TrustedProxies = append([]string(nil), defaults.TrustedProxies...)
 	defaults.Log.RedactKeys = append([]string(nil), defaults.Log.RedactKeys...)
 	return applyEnv(defaults, prefix)
@@ -48,6 +49,28 @@ func applyEnv(cfg Config, prefix string) (Config, error) {
 	cfg.Log.Environment = envString(prefix+"ENVIRONMENT", cfg.Log.Environment)

 	var err error
+	for _, field := range []struct {
+		name  string
+		value *time.Duration
+	}{
+		{"HTTP_READ_HEADER_TIMEOUT", &cfg.HTTP.ReadHeaderTimeout},
+		{"HTTP_READ_TIMEOUT", &cfg.HTTP.ReadTimeout},
+		{"HTTP_WRITE_TIMEOUT", &cfg.HTTP.WriteTimeout},
+		{"HTTP_IDLE_TIMEOUT", &cfg.HTTP.IdleTimeout},
+	} {
+		if value := strings.TrimSpace(os.Getenv(prefix + field.name)); value != "" {
+			*field.value, err = time.ParseDuration(value)
+			if err != nil {
+				return Config{}, fmt.Errorf("%s%s must be a duration: %w", prefix, field.name, err)
+			}
+		}
+	}
+	if value := strings.TrimSpace(os.Getenv(prefix + "HTTP_MAX_HEADER_BYTES")); value != "" {
+		cfg.HTTP.MaxHeaderBytes, err = strconv.Atoi(value)
+		if err != nil {
+			return Config{}, fmt.Errorf("%sHTTP_MAX_HEADER_BYTES must be an integer: %w", prefix, err)
+		}
+	}
 	if cfg.EnableLogger, err = envBool(prefix+"ENABLE_LOGGER", cfg.EnableLogger); err != nil {
 		return Config{}, err
 	}
--- a/config/errorCatalog_test.go
+++ b/config/errorCatalog_test.go
@@ -0,0 +1,75 @@
+package config_test
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"git.yuntuo.hk/k2safe/go-omni/config"
+	apierrors "git.yuntuo.hk/k2safe/go-omni/errors"
+	"git.yuntuo.hk/k2safe/go-omni/logx"
+)
+
+func TestCatalogConfigFiles(t *testing.T) {
+	for _, file := range []struct{ name, body string }{
+		{"server.json", `{"response":{"codeType":"int64","successCode":0,"errorCode":9999},"errors":{"defaultStatus":200,"definitions":{"LIMIT":{"code":9223372036854775807,"message":"limit"}}}}`},
+		{"server.yaml", "response:\n  codeType: int64\n  successCode: 0\n  errorCode: 9999\nerrors:\n  defaultStatus: 200\n  definitions:\n    LIMIT:\n      code: 9223372036854775807\n      message: limit\n"},
+	} {
+		t.Run(file.name, func(t *testing.T) {
+			path := filepath.Join(t.TempDir(), file.name)
+			if err := os.WriteFile(path, []byte(file.body), 0600); err != nil {
+				t.Fatal(err)
+			}
+			cfg, err := config.LoadFile(path, "CATALOG_FIXTURE_")
+			if err != nil {
+				t.Fatal(err)
+			}
+			e := apierrors.MustRegistry(cfg.Errors).Resolve(apierrors.ByCode("LIMIT"))
+			if e.Status != 200 || e.BusinessCode != int64(9223372036854775807) {
+				t.Fatal(e)
+			}
+		})
+	}
+	for _, body := range []string{
+		`{"errors":{"definitions":{"A":{"message":"a","code":1},"A":{"message":"b","code":2}}}}`,
+		`{"response":{"codeType":"int32","successCode":0,"errorCode":99},"errors":{"definitions":{"A":{"message":"a","code":2147483648}}}}`,
+		`{"errors":{"definitions":{"A":{"message":"a","code":"a","status":204}}}}`,
+	} {
+		path := filepath.Join(t.TempDir(), "bad.json")
+		if err := os.WriteFile(path, []byte(body), 0600); err != nil {
+			t.Fatal(err)
+		}
+		if _, err := config.LoadFile(path, "CATALOG_FIXTURE_"); err == nil {
+			t.Fatal("accepted invalid catalog", body)
+		}
+	}
+}
+
+func TestCatalogReloadSnapshotIsolation(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "config.json")
+	original := `{"errors":{"defaultStatus":200,"definitions":{"invalid":{"code":"invalid","message":"original"}}}}`
+	if err := os.WriteFile(path, []byte(original), 0600); err != nil {
+		t.Fatal(err)
+	}
+	logger, err := logx.New(logx.Default())
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer logger.Close()
+	reloader, err := config.NewReloader(path, "CATALOG_RELOAD_", logger)
+	if err != nil {
+		t.Fatal(err)
+	}
+	snapshot := reloader.Snapshot()
+	snapshot.Errors.Definitions["invalid"] = apierrors.Definition{Message: "changed"}
+	if reloader.Snapshot().Errors.Definitions["invalid"].Message != "original" {
+		t.Fatal("snapshot changed live catalog")
+	}
+	if err := os.WriteFile(path, []byte(strings.Replace(original, "original", "new message", 1)), 0600); err != nil {
+		t.Fatal(err)
+	}
+	if err := reloader.Reload(); err == nil || reloader.Snapshot().Errors.Definitions["invalid"].Message != "original" {
+		t.Fatal("catalog changed without restart", err)
+	}
+}
--- a/config/file.go
+++ b/config/file.go
@@ -5,8 +5,6 @@ import (
 	"context"
 	"encoding/json"
 	"errors"
-	"git.yuntuo.hk/k2safe/go-omni/logx"
-	"gopkg.in/yaml.v3"
 	"io"
 	"os"
 	"path/filepath"
@@ -14,6 +12,10 @@ import (
 	"strings"
 	"sync"
 	"time"
+
+	apierrors "git.yuntuo.hk/k2safe/go-omni/errors"
+	"git.yuntuo.hk/k2safe/go-omni/logx"
+	"gopkg.in/yaml.v3"
 )

 // DecodeFile merges a bounded JSON/YAML document into defaults. It uses JSON
@@ -45,15 +47,9 @@ func DecodeFile[T any](path string, defaults T) (T, error) {
 			return zero, errors.New("config: one YAML document required")
 		}
 	case ".json":
-		dec := json.NewDecoder(bytes.NewReader(data))
-		dec.UseNumber()
-		if err := dec.Decode(&value); err != nil {
+		if err := apierrors.DecodeCatalogJSON(data, &value); err != nil {
 			return zero, err
 		}
-		var extra any
-		if err := dec.Decode(&extra); err != io.EOF {
-			return zero, errors.New("config: one JSON document required")
-		}
 	default:
 		return zero, errors.New("config: expected .json, .yaml or .yml")
 	}
@@ -182,6 +178,7 @@ func (r *Reloader) Snapshot() Config {
 	defer r.mu.Unlock()
 	cfg := r.current
 	cfg.Response = r.current.Response.Clone()
+	cfg.Errors = r.current.Errors.Clone()
 	cfg.TrustedProxies = append([]string(nil), cfg.TrustedProxies...)
 	cfg.Log.RedactKeys = append([]string(nil), cfg.Log.RedactKeys...)
 	return cfg
--- a/config/http.go
+++ b/config/http.go
@@ -0,0 +1,45 @@
+package config
+
+import (
+	"log"
+	"time"
+)
+
+// HTTPConfig controls built-in HTTP servers. Positive values override the
+// selected transport's defaults; zero keeps its existing behavior. Timeouts
+// follow that transport's semantics, not a handler execution deadline.
+type HTTPConfig struct {
+	ReadHeaderTimeout time.Duration `json:"readHeaderTimeout"`
+	ReadTimeout       time.Duration `json:"readTimeout"`
+	WriteTimeout      time.Duration `json:"writeTimeout"`
+	IdleTimeout       time.Duration `json:"idleTimeout"`
+	MaxHeaderBytes    int           `json:"maxHeaderBytes"`
+	// ErrorLog is a Go-only hook for the nethttp server's internal diagnostics.
+	ErrorLog *log.Logger `json:"-"`
+}
+
+func (c HTTPConfig) Validate() error {
+	for _, field := range []struct {
+		name  string
+		value time.Duration
+	}{
+		{"readHeaderTimeout", c.ReadHeaderTimeout},
+		{"readTimeout", c.ReadTimeout},
+		{"writeTimeout", c.WriteTimeout},
+		{"idleTimeout", c.IdleTimeout},
+	} {
+		if field.value < 0 {
+			return &ConfigError{Field: "http." + field.name, Message: "must be nonnegative"}
+		}
+	}
+	if c.MaxHeaderBytes < 0 {
+		return &ConfigError{Field: "http.maxHeaderBytes", Message: "must be nonnegative"}
+	}
+	return nil
+}
+
+// WithHTTPConfig sets the built-in server's HTTP options. RunWith uses a
+// caller-owned Runner and does not apply these options to that runner.
+func WithHTTPConfig(settings HTTPConfig) Option {
+	return func(cfg *Config) { cfg.HTTP = settings }
+}
--- a/config/http_test.go
+++ b/config/http_test.go
@@ -0,0 +1,87 @@
+package config_test
+
+import (
+	"io"
+	"log"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"git.yuntuo.hk/k2safe/go-omni/config"
+)
+
+func TestHTTPFileAndEnvironment(t *testing.T) {
+	for _, file := range []struct{ name, body string }{
+		{"server.json", `{"http":{"readHeaderTimeout":"2s","readTimeout":"3s","writeTimeout":"4s","idleTimeout":"5s","maxHeaderBytes":8192}}`},
+		{"server.yaml", "http:\n  readHeaderTimeout: 2s\n  readTimeout: 3s\n  writeTimeout: 4s\n  idleTimeout: 5s\n  maxHeaderBytes: 8192\n"},
+	} {
+		t.Run(file.name, func(t *testing.T) {
+			path := filepath.Join(t.TempDir(), file.name)
+			if err := os.WriteFile(path, []byte(file.body), 0600); err != nil {
+				t.Fatal(err)
+			}
+			cfg, err := config.LoadFile(path, "HTTP_TEST_")
+			if err != nil {
+				t.Fatal(err)
+			}
+			want := config.HTTPConfig{ReadHeaderTimeout: 2 * time.Second, ReadTimeout: 3 * time.Second, WriteTimeout: 4 * time.Second, IdleTimeout: 5 * time.Second, MaxHeaderBytes: 8192}
+			if cfg.HTTP != want {
+				t.Fatalf("HTTP: %+v", cfg.HTTP)
+			}
+			t.Setenv("HTTP_TEST_HTTP_READ_HEADER_TIMEOUT", "6s")
+			t.Setenv("HTTP_TEST_HTTP_READ_TIMEOUT", "7s")
+			t.Setenv("HTTP_TEST_HTTP_WRITE_TIMEOUT", "8s")
+			t.Setenv("HTTP_TEST_HTTP_IDLE_TIMEOUT", "9s")
+			t.Setenv("HTTP_TEST_HTTP_MAX_HEADER_BYTES", "16384")
+			got, err := config.ApplyEnv(cfg, "HTTP_TEST_")
+			if err != nil {
+				t.Fatal(err)
+			}
+			want = config.HTTPConfig{ReadHeaderTimeout: 6 * time.Second, ReadTimeout: 7 * time.Second, WriteTimeout: 8 * time.Second, IdleTimeout: 9 * time.Second, MaxHeaderBytes: 16384}
+			if got.HTTP != want {
+				t.Fatalf("overlay: %+v", got.HTTP)
+			}
+		})
+	}
+}
+
+func TestHTTPInvalidAndUnsupportedSettings(t *testing.T) {
+	for _, key := range []string{"READ_HEADER_TIMEOUT", "READ_TIMEOUT", "WRITE_TIMEOUT", "IDLE_TIMEOUT", "MAX_HEADER_BYTES"} {
+		for _, value := range []string{"invalid", "-1"} {
+			t.Run(key+value, func(t *testing.T) {
+				if value == "-1" && key != "MAX_HEADER_BYTES" {
+					value = "-1s"
+				}
+				t.Setenv("HTTP_INVALID_HTTP_"+key, value)
+				if _, err := config.LoadFromEnv("HTTP_INVALID_"); err == nil {
+					t.Fatal("invalid HTTP value accepted")
+				}
+			})
+		}
+	}
+	for _, http := range []config.HTTPConfig{{ReadHeaderTimeout: time.Second}, {ReadTimeout: time.Second}, {WriteTimeout: time.Second}} {
+		cfg := config.Default()
+		cfg.Transport = config.TransportHTTP2
+		cfg.TLS = config.TLSConfig{CertFile: "c", KeyFile: "k"}
+		cfg.HTTP = http
+		if err := cfg.ValidateTransport(); err == nil || !strings.Contains(err.Error(), "not supported") {
+			t.Fatalf("HTTP/2: %v", err)
+		}
+	}
+	cfg := config.Default()
+	cfg.Transport = config.TransportHTTP2
+	cfg.TLS = config.TLSConfig{CertFile: "c", KeyFile: "k"}
+	cfg.HTTP = config.HTTPConfig{IdleTimeout: time.Minute, MaxHeaderBytes: 8192}
+	if err := cfg.ValidateTransport(); err != nil {
+		t.Fatal(err)
+	}
+	for _, transport := range []string{config.TransportNative, config.TransportHTTP2} {
+		cfg.Transport = transport
+		cfg.HTTP = config.HTTPConfig{ErrorLog: log.New(io.Discard, "", 0)}
+		if err := cfg.ValidateTransport(); err == nil || !strings.Contains(err.Error(), "http.errorLog") {
+			t.Fatalf("ErrorLog silently ignored: %v", err)
+		}
+	}
+}
--- a/database/README.md
+++ b/database/README.md
@@ -3,7 +3,7 @@
 `database` 包提供基于标准库 `database/sql` 的连接池生命周期，不绑定 ORM 或驱动：

 - `Config` / `ConfigFromEnv`：连接池参数和 `GO_OMNI_DB_*` 环境变量。
- `Open`：创建连接池、设置连接上限并在返回前执行 `PingContext`。
+- `Open` / `OpenConnector`：通过 DSN 或标准 Connector 创建连接池、设置连接上限并在返回前执行 `PingContext`。
 - `Health`：用于就绪检查，等待连接和 Ping 均受 `PingTimeout` 限制。
 - `InTx`：统一事务提交和回滚；工作函数返回错误或 panic 时回滚。
 - `Close`：由嵌入的 `*sql.DB` 提供，应用退出时显式调用。
@@ -40,7 +40,7 @@ GO_OMNI_DB_CONN_MAX_IDLE_TIME=5m
 GO_OMNI_DB_PING_TIMEOUT=5s
 ```

-`DSN` 必填，驱动默认是 `mysql`。数据库建库、迁移、表结构和具体 Repository 属于业务项目或可选模块，不会被核心包自动执行。
+使用 `ConfigFromEnv` / `Open` 时 `DSN` 必填，环境变量入口的驱动默认是 `mysql`。数据库建库、迁移、表结构和具体 Repository 属于业务项目或可选模块，不会被核心包自动执行。

 `MaxIdleConns=0` 会禁用空闲连接。初始化 Ping 失败会关闭已创建的连接池。

@@ -64,3 +64,61 @@ python3 scripts/verifyDatabase.py --version v0.2.0
 `Config` 的 JSON/YAML 字段使用 lowerCamelCase，`DSN` 使用 `json:"-"`，连接密钥从环境变量加载。
 API 脚手架 `--database mysql` 使用此流程，并要求正的 `maxOpenConns`，提供数据库 readiness 与幂等清理。
 具体表结构、迁移和 Repository 留在业务项目，参考 `examples/userService`。
+
+## Connector 接入（v0.9.1-preview）
+
+项目已有 `database/sql/driver.Connector` 时使用 `OpenConnector`。这是标准驱动接口，核心包不增加具体驱动依赖。项目可以在同一进程创建多个使用不同证书、日志、拨号策略的连接池。
+
+下面是 MySQL 的完整组装函数；连接地址、凭据、TLS 和驱动 Logger 都从调用方传入，不在框架中约定：
+
+```go
+package connection
+
+import (
+    "context"
+    "crypto/tls"
+    "github.com/go-sql-driver/mysql"
+    "git.yuntuo.hk/k2safe/go-omni/database"
+)
+
+func Open(ctx context.Context, address, user, password, name string,
+    tlsConfig *tls.Config, logger mysql.Logger,
+    pool database.PoolConfig) (*database.DB, error) {
+    cfg := mysql.NewConfig()
+    cfg.Net, cfg.Addr = "tcp", address
+    cfg.User, cfg.Passwd, cfg.DBName = user, password, name
+    cfg.TLS = tlsConfig // 项目设置 RootCAs、ServerName、MinVersion 等
+    if logger != nil {
+        cfg.Logger = logger // 项目现有的 Print(...any) 日志适配器
+    }
+    connector, err := mysql.NewConnector(cfg)
+    if err != nil {
+        return nil, err
+    }
+    return database.OpenConnector(ctx, connector, pool)
+}
+```
+
+调用时以 `database.DefaultPoolConfig()` 为起点，按项目需要调整。已有 `database.Config` 可调用 `.PoolConfig()` 提取池设置；`ConfigFromEnv` / `ApplyEnv` 仍是 DSN 入口，不用为 Connector 填假 DSN。`PoolConfig` 支持通过 `config.DecodeFile` 加载项目的 JSON/YAML 嵌套配置，环境覆盖由项目按自己的驱动配置组织。
+
+| PoolConfig 字段 | 默认值 / 含义 |
+| --- | --- |
+| `MaxOpenConns` | `10`；`0` 表示不限制 |
+| `MaxIdleConns` | `5`；`0` 禁止保留空闲连接 |
+| `ConnMaxLifetime` | `30m`；`0` 不因连接年龄回收 |
+| `ConnMaxIdleTime` | `5m`；`0` 不因空闲时长回收 |
+| `PingTimeout` | `5s`；必须为正，约束启动 Ping 和 Health 等待 |
+
+返回的 `*database.DB` 嵌入 `*sql.DB`，可使用 `QueryContext`、`ExecContext`、`Stats`，以及框架的 `Health`、`InTx`。需要标准数据库指针的 ORM/迁移器可取 `db.DB`；不要重复建立池。项目负责驱动支持的 context 取消与读写超时设置，框架不能强制中断不遵守 context 的自定义驱动。
+
+**生命周期：** nil/带类型的 nil Connector、非法池参数、启动前已取消的 context 会在创建池前返回，Connector 仍归调用方。进入 `sql.OpenDB` 后由池持有；启动 Ping 失败自动关闭，成功后由调用方负责 `db.Close`，通常注册 `app.OnShutdown(db.Close)`。若 Connector 实现 `io.Closer`，遵循标准 `database/sql` 规则随池关闭；有资源的 Connector 不应跨多个池共享。资源初始化过程中、注册退出回调之前若业务校验失败，项目也须关闭池。
+
+`db.PoolConfig()` 返回池配置快照。Connector 入口的 `db.Config()` 中 `Driver` / `DSN` 为空，不能用它重建 Connector。TLS、Logger、驱动版本检查、字符集、时区以及迁移规则保持由项目负责；不写入框架配置快照。
+
+验收脚本使用独立本地 MySQL 8.4 容器（1 CPU / 768 MiB），自动生成测试 CA/证书与随机凭据，检查 TLS 信任/主机名、两池配置隔离、驱动日志、事务和 HTTP 超时，结束后清理本次资源：
+
+```sh
+python3 scripts/verifyConnector.py --local --report performance/connectorLocal.json
+# 发布后通过全新 module cache 验证远程依赖，无本地 replace：
+python3 scripts/verifyConnector.py --version v0.9.1-preview --report performance/connectorRemote.json
+```
--- a/database/connector.go
+++ b/database/connector.go
@@ -0,0 +1,82 @@
+package database
+
+import (
+	"context"
+	"database/sql"
+	"database/sql/driver"
+	"errors"
+	"reflect"
+	"time"
+)
+
+// PoolConfig contains only driver-independent settings. Connection credentials,
+// TLS, logging and dial behavior belong to the application's Connector.
+// Start from DefaultPoolConfig; zero PingTimeout is invalid.
+type PoolConfig struct {
+	MaxOpenConns    int           `json:"maxOpenConns"`
+	MaxIdleConns    int           `json:"maxIdleConns"`
+	ConnMaxLifetime time.Duration `json:"connMaxLifetime"`
+	ConnMaxIdleTime time.Duration `json:"connMaxIdleTime"`
+	PingTimeout     time.Duration `json:"pingTimeout"`
+}
+
+func DefaultPoolConfig() PoolConfig {
+	return PoolConfig{MaxOpenConns: 10, MaxIdleConns: 5, ConnMaxLifetime: 30 * time.Minute, ConnMaxIdleTime: 5 * time.Minute, PingTimeout: 5 * time.Second}
+}
+
+func (c PoolConfig) Validate() error {
+	if c.MaxOpenConns < 0 || c.MaxIdleConns < 0 {
+		return errors.New("database pool limits cannot be negative")
+	}
+	if c.MaxOpenConns > 0 && c.MaxIdleConns > c.MaxOpenConns {
+		return errors.New("max idle connections cannot exceed max open connections")
+	}
+	if c.ConnMaxLifetime < 0 || c.ConnMaxIdleTime < 0 || c.PingTimeout <= 0 {
+		return errors.New("database timeouts are invalid")
+	}
+	return nil
+}
+
+func (c PoolConfig) config() Config {
+	return Config{MaxOpenConns: c.MaxOpenConns, MaxIdleConns: c.MaxIdleConns, ConnMaxLifetime: c.ConnMaxLifetime, ConnMaxIdleTime: c.ConnMaxIdleTime, PingTimeout: c.PingTimeout}
+}
+
+// OpenConnector opens an independent pool using the supplied standard Connector.
+// No registered driver name or DSN is required. It applies cfg and completes a
+// startup Ping bounded by ctx and PingTimeout before returning.
+//
+// Validation failures and an already-canceled ctx leave the Connector untouched.
+// Once sql.OpenDB is called, the pool owns its lifecycle: a failed startup closes
+// the pool; on success the caller must Close the returned DB. As in database/sql,
+// this also closes a Connector that implements io.Closer. Use a separate Connector
+// for each pool if it owns resources. Nil ctx means context.Background.
+func OpenConnector(ctx context.Context, connector driver.Connector, cfg PoolConfig) (*DB, error) {
+	if nilConnector(connector) {
+		return nil, errors.New("database connector is required")
+	}
+	if err := cfg.Validate(); err != nil {
+		return nil, err
+	}
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	if err := ctx.Err(); err != nil {
+		return nil, err
+	}
+	return initializePool(ctx, sql.OpenDB(connector), cfg.config())
+}
+
+func nilConnector(connector driver.Connector) bool {
+	if connector == nil {
+		return true
+	}
+	v := reflect.ValueOf(connector)
+	switch v.Kind() {
+	case reflect.Chan, reflect.Func, reflect.Interface, reflect.Map, reflect.Pointer, reflect.Slice:
+		return v.IsNil()
+	}
+	return false
+}
+
+// PoolConfig returns a copy of the settings used to create this pool.
+func (db *DB) PoolConfig() PoolConfig { return db.config.PoolConfig() }
--- a/database/connector_test.go
+++ b/database/connector_test.go
@@ -0,0 +1,336 @@
+package database_test
+
+import (
+	"context"
+	"database/sql"
+	"database/sql/driver"
+	"errors"
+	"io"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"git.yuntuo.hk/k2safe/go-omni/database"
+)
+
+type fixtureConnector struct {
+	identity                                                         string
+	connects, closedConnections, closedConnector, commits, rollbacks atomic.Int32
+	connect                                                          func(context.Context) error
+	ping                                                             func(context.Context) error
+	query                                                            func(context.Context) error
+	closeErr                                                         error
+}
+
+func (c *fixtureConnector) Connect(ctx context.Context) (driver.Conn, error) {
+	c.connects.Add(1)
+	if c.connect != nil {
+		if err := c.connect(ctx); err != nil {
+			return nil, err
+		}
+	}
+	return &fixtureConn{owner: c}, nil
+}
+func (c *fixtureConnector) Driver() driver.Driver { return fixtureDriver{} }
+func (c *fixtureConnector) Close() error          { c.closedConnector.Add(1); return c.closeErr }
+
+type fixtureDriver struct{}
+
+func (fixtureDriver) Open(string) (driver.Conn, error) {
+	return nil, errors.New("unexpected driver name/DSN path")
+}
+
+type fixtureConn struct{ owner *fixtureConnector }
+
+func (c *fixtureConn) Prepare(string) (driver.Stmt, error) { return nil, errors.New("not used") }
+func (c *fixtureConn) Close() error                        { c.owner.closedConnections.Add(1); return nil }
+func (c *fixtureConn) Begin() (driver.Tx, error)           { return fixtureTx{c.owner}, nil }
+func (c *fixtureConn) Ping(ctx context.Context) error {
+	if c.owner.ping != nil {
+		return c.owner.ping(ctx)
+	}
+	return nil
+}
+func (c *fixtureConn) QueryContext(ctx context.Context, _ string, _ []driver.NamedValue) (driver.Rows, error) {
+	if c.owner.query != nil {
+		if err := c.owner.query(ctx); err != nil {
+			return nil, err
+		}
+	}
+	return &fixtureRows{identity: c.owner.identity}, nil
+}
+
+type fixtureTx struct{ owner *fixtureConnector }
+
+func (tx fixtureTx) Commit() error   { tx.owner.commits.Add(1); return nil }
+func (tx fixtureTx) Rollback() error { tx.owner.rollbacks.Add(1); return nil }
+
+type fixtureRows struct {
+	identity string
+	sent     bool
+}
+
+func (r *fixtureRows) Columns() []string { return []string{"identity"} }
+func (r *fixtureRows) Close() error      { return nil }
+func (r *fixtureRows) Next(values []driver.Value) error {
+	if r.sent {
+		return io.EOF
+	}
+	r.sent = true
+	values[0] = r.identity
+	return nil
+}
+
+func TestConnectorIndependentPoolsAndContext(t *testing.T) {
+	type key struct{}
+	ctx := context.WithValue(context.Background(), key{}, "startup")
+	cfg := database.DefaultPoolConfig()
+	cfg.MaxOpenConns = 2
+	cfg.MaxIdleConns = 2
+	var owners []*fixtureConnector
+	var pools []*database.DB
+	for _, identity := range []string{"alpha", "beta"} {
+		owner := &fixtureConnector{identity: identity}
+		// Startup Connect/Ping and each query preserve their caller context.
+		// database/sql may also open replacement connections in the background.
+		owner.connect = func(ctx context.Context) error {
+			if owner.connects.Load() == 1 && ctx.Value(key{}) != "startup" {
+				return errors.New("lost request context")
+			}
+			return nil
+		}
+		owner.ping = func(ctx context.Context) error {
+			if ctx.Value(key{}) != "startup" {
+				return errors.New("lost ping context")
+			}
+			return nil
+		}
+		owner.query = func(ctx context.Context) error {
+			if ctx.Value(key{}) != "startup" {
+				return errors.New("lost query context")
+			}
+			return nil
+		}
+		pool, err := database.OpenConnector(ctx, owner, cfg)
+		if err != nil {
+			t.Fatal(err)
+		}
+		t.Cleanup(func() { pool.Close() })
+		if pool.PoolConfig() != cfg || pool.Config().Driver != "" || pool.Config().DSN != "" || pool.Stats().MaxOpenConnections != 2 {
+			t.Fatal("pool settings or DSN boundary")
+		}
+		owners = append(owners, owner)
+		pools = append(pools, pool)
+	}
+	var wg sync.WaitGroup
+	for i, pool := range pools {
+		for n := 0; n < 16; n++ {
+			wg.Add(1)
+			go func(i int, pool *database.DB) {
+				defer wg.Done()
+				var identity string
+				if err := pool.QueryRowContext(ctx, "identity").Scan(&identity); err != nil {
+					t.Error(err)
+				} else if identity != owners[i].identity {
+					t.Error("crossed connectors")
+				}
+			}(i, pool)
+		}
+	}
+	wg.Wait()
+	for i, pool := range pools {
+		if pool.Stats().OpenConnections > cfg.MaxOpenConns {
+			t.Fatal("pool cap not applied")
+		}
+		if err := pool.Close(); err != nil {
+			t.Fatal(err)
+		}
+		if err := pool.Close(); err != nil {
+			t.Fatal(err)
+		}
+		if owners[i].closedConnector.Load() != 1 || owners[i].closedConnections.Load() != owners[i].connects.Load() {
+			t.Fatal("close did not release owned resources exactly once")
+		}
+		if pool.Health(ctx) == nil {
+			t.Fatal("closed pool is healthy")
+		}
+	}
+}
+
+func TestConnectorRejectsInvalidInputWithoutTakingOwnership(t *testing.T) {
+	var typedNil *fixtureConnector
+	for _, connector := range []driver.Connector{nil, typedNil} {
+		if db, err := database.OpenConnector(nil, connector, database.DefaultPoolConfig()); err == nil || db != nil {
+			t.Fatal("nil connector accepted")
+		}
+	}
+	for _, mutate := range []func(*database.PoolConfig){
+		func(c *database.PoolConfig) { c.MaxOpenConns = -1 }, func(c *database.PoolConfig) { c.MaxIdleConns = -1 },
+		func(c *database.PoolConfig) { c.MaxIdleConns = c.MaxOpenConns + 1 }, func(c *database.PoolConfig) { c.PingTimeout = 0 },
+		func(c *database.PoolConfig) { c.ConnMaxLifetime = -1 }, func(c *database.PoolConfig) { c.ConnMaxIdleTime = -1 },
+	} {
+		cfg := database.DefaultPoolConfig()
+		mutate(&cfg)
+		owner := &fixtureConnector{}
+		if db, err := database.OpenConnector(nil, owner, cfg); err == nil || db != nil {
+			t.Fatal("invalid config accepted")
+		}
+		if owner.connects.Load() != 0 || owner.closedConnector.Load() != 0 {
+			t.Fatal("validation consumed connector")
+		}
+	}
+	owner := &fixtureConnector{}
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	if db, err := database.OpenConnector(ctx, owner, database.DefaultPoolConfig()); !errors.Is(err, context.Canceled) || db != nil {
+		t.Fatalf("pre-canceled context: %v", err)
+	}
+	if owner.connects.Load() != 0 || owner.closedConnector.Load() != 0 {
+		t.Fatal("pre-cancellation consumed connector")
+	}
+	if err := database.DefaultConfig().Validate(); err == nil {
+		t.Fatal("legacy DSN requirements changed")
+	}
+}
+
+func TestConnectorStartupFailuresReleaseResources(t *testing.T) {
+	failure := errors.New("fixture unavailable")
+	closeFailure := errors.New("fixture close failed")
+	for _, phase := range []string{"connect", "ping"} {
+		t.Run(phase, func(t *testing.T) {
+			owner := &fixtureConnector{closeErr: closeFailure}
+			if phase == "connect" {
+				owner.connect = func(context.Context) error { return failure }
+			} else {
+				owner.ping = func(context.Context) error { return failure }
+			}
+			pool, err := database.OpenConnector(nil, owner, database.DefaultPoolConfig())
+			if pool != nil || !errors.Is(err, failure) || !errors.Is(err, closeFailure) {
+				t.Fatalf("lost failure or cleanup error: %v", err)
+			}
+			expectedConnections := int32(0)
+			if phase == "ping" {
+				expectedConnections = 1
+			}
+			if owner.closedConnector.Load() != 1 || owner.closedConnections.Load() != expectedConnections {
+				t.Fatal("startup failure leaked resources")
+			}
+		})
+	}
+}
+
+func TestConnectorTimeoutBoundsConnectAndPing(t *testing.T) {
+	for _, phase := range []string{"connect", "ping"} {
+		t.Run(phase, func(t *testing.T) {
+			owner := &fixtureConnector{}
+			cfg := database.DefaultPoolConfig()
+			cfg.PingTimeout = 20 * time.Millisecond
+			wait := func(ctx context.Context) error {
+				if _, ok := ctx.Deadline(); !ok {
+					return errors.New("missing deadline")
+				}
+				<-ctx.Done()
+				return ctx.Err()
+			}
+			if phase == "connect" {
+				owner.connect = wait
+			} else {
+				owner.ping = wait
+			}
+			pool, err := database.OpenConnector(context.Background(), owner, cfg)
+			if pool != nil || !errors.Is(err, context.DeadlineExceeded) {
+				t.Fatalf("%s timeout: %v", phase, err)
+			}
+			if owner.closedConnector.Load() != 1 {
+				t.Fatal("timeout leaked connector")
+			}
+		})
+	}
+}
+
+func TestConnectorHealthBoundsPoolWaitAndRecovers(t *testing.T) {
+	cfg := database.DefaultPoolConfig()
+	cfg.MaxOpenConns = 1
+	cfg.MaxIdleConns = 1
+	cfg.PingTimeout = 20 * time.Millisecond
+	owner := &fixtureConnector{}
+	pool, err := database.OpenConnector(nil, owner, cfg)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer pool.Close()
+	conn, err := pool.Conn(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer conn.Close()
+	if err = pool.Health(nil); !errors.Is(err, context.DeadlineExceeded) {
+		t.Fatalf("waiting for busy pool was not bounded: %v", err)
+	}
+	if err = conn.Close(); err != nil {
+		t.Fatal(err)
+	}
+	if err = pool.Health(nil); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestConnectorIdleZeroAndLifetime(t *testing.T) {
+	for _, mode := range []string{"noIdle", "expired"} {
+		t.Run(mode, func(t *testing.T) {
+			cfg := database.DefaultPoolConfig()
+			if mode == "noIdle" {
+				cfg.MaxIdleConns = 0
+			} else {
+				cfg.ConnMaxLifetime = time.Nanosecond
+			}
+			owner := &fixtureConnector{}
+			pool, err := database.OpenConnector(nil, owner, cfg)
+			if err != nil {
+				t.Fatal(err)
+			}
+			defer pool.Close()
+			if err = pool.Health(nil); err != nil {
+				t.Fatal(err)
+			}
+			if owner.connects.Load() < 2 || owner.closedConnections.Load() == 0 {
+				t.Fatal("pool did not retire connections")
+			}
+			if mode == "noIdle" && pool.Stats().Idle != 0 {
+				t.Fatal("zero idle not honored")
+			}
+			if mode == "expired" && pool.Stats().MaxLifetimeClosed == 0 {
+				t.Fatal("lifetime not honored")
+			}
+		})
+	}
+}
+
+func TestConnectorTransactionsKeepCommitAndRollbackSemantics(t *testing.T) {
+	owner := &fixtureConnector{}
+	pool, err := database.OpenConnector(nil, owner, database.DefaultPoolConfig())
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer pool.Close()
+	ctx := context.Background()
+	if err = pool.InTx(ctx, nil, func(*sql.Tx) error { return nil }); err != nil {
+		t.Fatal(err)
+	}
+	failed := errors.New("business failed")
+	if err = pool.InTx(ctx, nil, func(*sql.Tx) error { return failed }); !errors.Is(err, failed) {
+		t.Fatal(err)
+	}
+	func() {
+		defer func() {
+			if recover() != failed {
+				t.Error("panic not preserved")
+			}
+		}()
+		_ = pool.InTx(ctx, nil, func(*sql.Tx) error { panic(failed) })
+	}()
+	if owner.commits.Load() != 1 || owner.rollbacks.Load() != 2 {
+		t.Fatal("transaction semantics changed")
+	}
+}
--- a/database/database.go
+++ b/database/database.go
@@ -23,13 +23,14 @@ type Config struct {
 	PingTimeout     time.Duration `json:"pingTimeout"`
 }

-func DefaultConfig() Config {
-	return Config{
-		MaxOpenConns:    10,
-		MaxIdleConns:    5,
-		ConnMaxLifetime: 30 * time.Minute,
-		ConnMaxIdleTime: 5 * time.Minute,
-		PingTimeout:     5 * time.Second,
+func DefaultConfig() Config { return DefaultPoolConfig().config() }
+
+// PoolConfig returns driver-independent connection pool settings.
+func (c Config) PoolConfig() PoolConfig {
+	return PoolConfig{
+		MaxOpenConns: c.MaxOpenConns, MaxIdleConns: c.MaxIdleConns,
+		ConnMaxLifetime: c.ConnMaxLifetime, ConnMaxIdleTime: c.ConnMaxIdleTime,
+		PingTimeout: c.PingTimeout,
 	}
 }

@@ -83,16 +84,7 @@ func (c Config) Validate() error {
 	if strings.TrimSpace(c.DSN) == "" {
 		return errors.New("database DSN is required")
 	}
-	if c.MaxOpenConns < 0 || c.MaxIdleConns < 0 {
-		return errors.New("database pool limits cannot be negative")
-	}
-	if c.MaxIdleConns > c.MaxOpenConns && c.MaxOpenConns > 0 {
-		return errors.New("max idle connections cannot exceed max open connections")
-	}
-	if c.ConnMaxLifetime < 0 || c.ConnMaxIdleTime < 0 || c.PingTimeout <= 0 {
-		return errors.New("database timeouts are invalid")
-	}
-	return nil
+	return c.PoolConfig().Validate()
 }

 // DB owns a connection pool and exposes the embedded database/sql methods.
@@ -112,23 +104,30 @@ func Open(ctx context.Context, cfg Config) (*DB, error) {
 	if err != nil {
 		return nil, fmt.Errorf("open database: %w", err)
 	}
-	if cfg.MaxOpenConns > 0 {
-		db.SetMaxOpenConns(cfg.MaxOpenConns)
+	return initializePool(ctx, db, cfg)
 }
-	// database/sql uses zero to disable idle connections; do not leave its
-	// default pool size in place when the caller explicitly chooses zero.
-	db.SetMaxIdleConns(cfg.MaxIdleConns)
+
+// initializePool is the shared ownership boundary for both creation paths.
+// All configuration is validated before creating the sql.DB.
+func initializePool(ctx context.Context, db *sql.DB, cfg Config) (*DB, error) {
+	db.SetMaxOpenConns(cfg.MaxOpenConns)
+	db.SetMaxIdleConns(cfg.MaxIdleConns) // Zero explicitly disables idle connections.
 	db.SetConnMaxLifetime(cfg.ConnMaxLifetime)
 	db.SetConnMaxIdleTime(cfg.ConnMaxIdleTime)
 	checkCtx, cancel := context.WithTimeout(ctx, cfg.PingTimeout)
 	defer cancel()
 	if err := db.PingContext(checkCtx); err != nil {
-		_ = db.Close()
-		return nil, fmt.Errorf("ping database: %w", err)
+		pingErr := fmt.Errorf("ping database: %w", err)
+		if closeErr := db.Close(); closeErr != nil {
+			return nil, errors.Join(pingErr, fmt.Errorf("close database after failed ping: %w", closeErr))
+		}
+		return nil, pingErr
 	}
 	return &DB{DB: db, config: cfg}, nil
 }

+// Config returns the original DSN configuration. Pools opened with a Connector
+// have empty Driver/DSN fields; their connector cannot be reconstructed from Config.
 func (db *DB) Config() Config { return db.config }

 func (db *DB) Health(ctx context.Context) error {
--- a/database/mysqlConnector_test.go
+++ b/database/mysqlConnector_test.go
@@ -0,0 +1,180 @@
+package database_test
+
+import (
+	"context"
+	"crypto/tls"
+	"crypto/x509"
+	"database/sql"
+	"errors"
+	"net"
+	"os"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"git.yuntuo.hk/k2safe/go-omni/database"
+	"github.com/go-sql-driver/mysql"
+)
+
+type connectorDriverLog struct{ count atomic.Int32 }
+
+func (l *connectorDriverLog) Print(...any) { l.count.Add(1) }
+
+func TestMySQLConnectorDriverLoggerIsolation(t *testing.T) {
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	stopped := make(chan struct{})
+	go func() {
+		defer close(stopped)
+		for {
+			c, err := listener.Accept()
+			if err != nil {
+				return
+			}
+			c.Close()
+		}
+	}()
+	defer func() { listener.Close(); <-stopped }()
+	logs := [2]connectorDriverLog{}
+	for i := range logs {
+		cfg := mysql.NewConfig()
+		cfg.Net = "tcp"
+		cfg.Addr = listener.Addr().String()
+		cfg.Timeout = time.Second
+		cfg.ReadTimeout = time.Second
+		cfg.Logger = &logs[i]
+		connector, err := mysql.NewConnector(cfg)
+		if err != nil {
+			t.Fatal(err)
+		}
+		before := [2]int32{logs[0].count.Load(), logs[1].count.Load()}
+		db, err := database.OpenConnector(context.Background(), connector, database.DefaultPoolConfig())
+		if err == nil {
+			db.Close()
+			t.Fatal("handshake to closed socket succeeded")
+		}
+		if logs[i].count.Load() <= before[i] || logs[1-i].count.Load() != before[1-i] {
+			t.Fatal("driver logger did not stay on its connector")
+		}
+	}
+}
+
+func TestMySQLConnectorTLSAndPoolIsolation(t *testing.T) {
+	if os.Getenv("GO_OMNI_CONNECTOR_MYSQL_TEST") != "1" {
+		t.Skip("use scripts/verifyConnector.py for isolated MySQL TLS verification")
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+	defer cancel()
+	ca, err := os.ReadFile(os.Getenv("GO_OMNI_CONNECTOR_CA_FILE"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	roots := x509.NewCertPool()
+	if !roots.AppendCertsFromPEM(ca) {
+		t.Fatal("invalid test CA")
+	}
+	cfg := mysql.NewConfig()
+	cfg.Net = "tcp"
+	cfg.Addr = os.Getenv("GO_OMNI_CONNECTOR_ADDR")
+	cfg.User = os.Getenv("GO_OMNI_CONNECTOR_USER")
+	cfg.Passwd = os.Getenv("GO_OMNI_CONNECTOR_PASSWORD")
+	cfg.DBName = os.Getenv("GO_OMNI_CONNECTOR_DATABASE")
+	cfg.Timeout = time.Second
+	cfg.ReadTimeout = 2 * time.Second
+	cfg.WriteTimeout = 2 * time.Second
+	cfg.TLS = &tls.Config{MinVersion: tls.VersionTLS12, ServerName: "localhost", RootCAs: roots}
+	pool := database.DefaultPoolConfig()
+	pool.MaxOpenConns = 2
+	pool.MaxIdleConns = 2
+	pool.PingTimeout = 2 * time.Second
+	open := func(cfg *mysql.Config) (*database.DB, error) {
+		connector, err := mysql.NewConnector(cfg)
+		if err != nil {
+			return nil, err
+		}
+		return database.OpenConnector(ctx, connector, pool)
+	}
+	cfg.Params = map[string]string{"time_zone": "'+00:00'"}
+	first, err := open(cfg)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer first.Close()
+	other := cfg.Clone()
+	other.Params["time_zone"] = "'+08:00'"
+	second, err := open(other)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer second.Close()
+	for i, db := range []*database.DB{first, second} {
+		var name, cipher, zone string
+		if err := db.QueryRowContext(ctx, "SHOW SESSION STATUS LIKE 'Ssl_cipher'").Scan(&name, &cipher); err != nil {
+			t.Fatal(err)
+		}
+		if cipher == "" {
+			t.Fatal("connection is not encrypted")
+		}
+		if err := db.QueryRowContext(ctx, "SELECT @@session.time_zone").Scan(&zone); err != nil {
+			t.Fatal(err)
+		}
+		if zone != []string{"+00:00", "+08:00"}[i] {
+			t.Fatalf("session config leaked: %s", zone)
+		}
+		if db.Stats().MaxOpenConnections != 2 {
+			t.Fatal("pool configuration ignored")
+		}
+	}
+	for _, bad := range []string{"untrustedCA", "wrongHostname"} {
+		t.Run(bad, func(t *testing.T) {
+			invalid := cfg.Clone()
+			if bad == "untrustedCA" {
+				invalid.TLS.RootCAs = x509.NewCertPool()
+			} else {
+				invalid.TLS.ServerName = "wrong.invalid"
+			}
+			db, err := open(invalid)
+			if err == nil {
+				db.Close()
+				t.Fatal("invalid server certificate accepted")
+			}
+			var verification *tls.CertificateVerificationError
+			if !errors.As(err, &verification) {
+				t.Fatalf("not a TLS verification failure: %v", err)
+			}
+			if err := first.Health(ctx); err != nil {
+				t.Fatalf("failed connector affected existing pool: %v", err)
+			}
+		})
+	}
+	if _, err := first.ExecContext(ctx, "CREATE TABLE connector_check (id INT PRIMARY KEY)"); err != nil {
+		t.Fatal(err)
+	}
+	if err := first.InTx(ctx, nil, func(tx *sql.Tx) error {
+		_, err := tx.ExecContext(ctx, "INSERT INTO connector_check VALUES (1)")
+		return err
+	}); err != nil {
+		t.Fatal(err)
+	}
+	rollbackErr := errors.New("rollback requested")
+	if err := first.InTx(ctx, nil, func(tx *sql.Tx) error {
+		if _, err := tx.ExecContext(ctx, "INSERT INTO connector_check VALUES (2)"); err != nil {
+			return err
+		}
+		return rollbackErr
+	}); !errors.Is(err, rollbackErr) {
+		t.Fatal(err)
+	}
+	var count int
+	if err := second.QueryRowContext(ctx, "SELECT COUNT(*) FROM connector_check").Scan(&count); err != nil || count != 1 {
+		t.Fatalf("transaction count=%d err=%v", count, err)
+	}
+	if err := first.Close(); err != nil {
+		t.Fatal(err)
+	}
+	if err := second.Health(ctx); err != nil {
+		t.Fatal("closing first pool affected second:", err)
+	}
+}
--- a/errors/README.md
+++ b/errors/README.md
@@ -0,0 +1,133 @@
+# 统一错误目录
+
+从 `v0.10.0-preview` 起，业务可以只返回逻辑错误标识，框架从项目目录取得 HTTP 状态、对外业务码与公开提示。目录不依赖具体业务、数据库、身份模型或网络层，也不定义固定返回体。
+
+## 基本规则
+
+- `key` / `Definitions` 的 map key 是唯一逻辑标识，例如 `USERNAME_INVALID`、`user.notFound`。API 新目录允许项目自己的标识命名；旧 `error (...)` 声明保持原有大写标识规则。
+- `code` 是对外业务码，支持字符串、整数，同一个码可以由多个不同标识使用。JSON/YAML 和 `.api` 读取整数时保留 int64 精度。
+- `DefaultStatus` / `defaultStatus` 只为目录中未写状态的条目提供默认值，省略时为 400。项目可设为 200；单项 `Status` / `status` 优先。
+- 目录条目允许有响应体的最终 HTTP 状态：200..599，排除 204、205、304。成功输出与错误输出分开；HTTP 200 并不把错误变成成功。
+- 数字码类型与范围遵守选中响应的 `codeType`（string/int32/int64；integer 是旧别名）。不同路由可以选择不同类型的公共响应与目录。
+- 新目录声明完整公开提示；每条错误的业务码和提示优先于统一 `errorCode` / `errorMessage` 兜底。旧的同标识 `codes` / `messages` 若与目录冲突，初始化或契约编译报错；相同值允许保留，便于逐步迁移。
+
+## 手写项目
+
+```go
+import (
+    omni "git.yuntuo.hk/k2safe/go-omni"
+    omnierrors "git.yuntuo.hk/k2safe/go-omni/errors"
+    "git.yuntuo.hk/k2safe/go-omni/response"
+)
+
+catalog := omnierrors.Catalog{
+    DefaultStatus: 200,
+    Definitions: map[string]omnierrors.Definition{
+        "USERNAME_INVALID": {Code: 400002, Message: "用户名格式不正确"},
+        "PASSWORD_INVALID": {Code: 400002, Message: "密码格式不正确"},
+        "FORBIDDEN": {Status: 403, Code: 403001, Message: "没有权限"},
+    },
+}
+app := omni.New(
+    omni.WithErrors(catalog),
+    omni.WithResponse(response.Config{
+        CodeType: "int32", SuccessCode: 0, ErrorCode: 9999,
+        MessageField: "msg", DataMode: "always",
+    }),
+)
+```
+
+Service 返回 `omnierrors.ByCode("USERNAME_INVALID")`，或 `.WithCause(err)`。业务无需接收 App/HTTP Context。目录属于 App，初始化时校验并复制；后续修改原 map 不影响正在服务的应用。配置快照也不暴露内部 map。
+
+`NewRegistry(catalog)` / `MustRegistry(catalog)` 可在 CLI/任务消费者等非 HTTP 入口使用；`registry.Resolve(err)` 返回独立的 `*APIError`，包含逻辑 `Code`、对外 `BusinessCode`、Status、Message 与内部 Cause。每次调用都创建新对象；不要自行将一个可变错误对象保存为共享单例再调用 WithCause。
+
+原有 `New(status, key, message)` 等明确错误也能被同标识目录条目覆盖；未在目录中的明确错误沿用原状态与提示。未配置目录时，原有行为保持。Go 目录允许 `Definition.Code == nil` 以继续使用旧 Codes/errorCode 映射；新 `.api errorCatalog` 要求显式 code。
+
+## 文件配置
+
+下面是生成项目的 `etc/config.yaml` 结构；直接 `config.LoadFile` 加载框架配置时去掉外面的 `server`。手写 main 需显式将加载结果传入 `WithConfig`。
+
+```yaml
+server:
+  errors:
+    defaultStatus: 200
+    definitions:
+      USERNAME_INVALID:
+        code: 400002
+        message: 用户名格式不正确
+      FORBIDDEN:
+        status: 403
+        code: 403001
+        message: 没有权限
+  response:
+    codeType: int32
+    successCode: 0
+    errorCode: 9999
+    messageField: msg
+    dataMode: always
+```
+
+重复 JSON/YAML key、未知字段、非法状态、非整数数值及类型/范围错误会拒绝加载。目录不支持运行时热更新；修改后重新启动，避免请求与文档在运行期间漂移。
+
+## .api：定义一次，生成调用与文档
+
+完整示例见 [errors.api](../examples/contracts/errors.api)。语法：
+
+```text
+errorCatalog CommonErrors (
+    defaultStatus: 200
+    errors: {
+        "UsernameInvalid": {"key": "USERNAME_INVALID", "code": 400002, "message": "用户名格式不正确"},
+        "PasswordInvalid": {"key": "PASSWORD_INVALID", "code": 400002, "message": "密码格式不正确"}
+    }
+)
+```
+
+目录可放进公共 `.api` 再 import；也可以拆成多个命名目录，各自设置默认状态。生成器合并定义时检查目录名、函数名、逻辑标识冲突。`Catalog` 是生成包的保留函数名。目录对象的键是生成的 UpperCamelCase 函数名，条目的 `key` 是运行时逻辑标识，二者用途不同。
+
+在 `@server` 的 `errors` 或路由 `@errors` 中引用函数名，响应仍通过原有 `response` 声明选择：
+
+```text
+@server (
+    response: CommonResponse
+    errors: UsernameInvalid, PasswordInvalid
+)
+service account-api {
+    @handler token
+    post /token returns (TokenResponse)
+}
+```
+
+生成结果包括：
+
+- `apierrors.UsernameInvalid()` 等无参数函数，每次返回独立错误，支持 WithCause。
+- `apierrors.CodeUsernameInvalid` 等逻辑标识常量。
+- `apierrors.Catalog()`：整个契约的可复制运行时目录，方便手写路由复用。
+- 自动绑定到生成路由的目录：只包含该路由通过 `@errors` / `@server errors` 声明的错误，在 App 全局中间件之前生效，支持认证提前返回和缓冲克隆。
+- OpenAPI 的错误响应与示例。同一 HTTP 200 下用 `anyOf` 同时描述成功 DTO 和错误体；多个错误共用数字码时保持多个示例；raw 成功体与失败公共体也分开描述。
+
+业务直接 `return TokenResponse{}, apierrors.UsernameInvalid()`。也可以返回 `omnierrors.ByCode(apierrors.CodeUsernameInvalid)`；使用标识引用时，当前 App/路由目录必须包含该错误。不要把“函数已生成”视作“所有路由都已声明这个错误”：新增实际错误后仍应补相应 `@errors`，保持文档准确。
+
+生成路由的目录和响应由 `.api` 管理；YAML 或 App 默认策略不覆盖它。手写路由可在 main 用 `omni.WithErrors(apierrors.Catalog())` 并选择兼容的 `WithResponse`。新项目和重复生成都会自动绑定路由目录，无需手动修改 main；已有手写文件保持不动。
+
+## 特殊协议与失败信息
+
+`response.WithErrors(catalog, encoder)` / `MustWithErrors` 可绑定路由专用策略，再通过 `HandleWithResponse` 注册。内置模板校验目录码类型与旧映射；自定义 Encoder 自行决定最终 HTTP 状态、媒体类型和字段结构，可将失败转换成第三方要求的文本/XML 回执。一个 Encoder 作用域不叠加不同目录；外层空目录或相同目录不会覆盖已有目录。
+
+Encoder 的 `response.Result` 包含逻辑 `Code`、对外 `BusinessCode`、公开 `Message`、原始 `Err` 及 `Failed`。使用 `result.IsError()` 判断失败，不要仅判断 `Status >= 400`。`RawJSON` 仅让成功结果保持未包装，HTTP 200 的失败仍使用选定错误策略。`c.Text` / `c.XML` / `c.JSON` 等直接输出及已提交的标准 Handler 响应不会被目录重新包装。
+
+启用访问日志时，记录最终写出的 HTTP 状态，并保留 `failed`、`errorKey` 和可用的 `businessCode`。内置指标将已处理的业务失败计入 Errors；链路记录保留 HTTP 200 和业务失败标记。标准中间件桥接和本地/共享幂等重放保留失败标识；已有缓存条目没有新增元数据时无法追溯识别业务失败，等待正常过期即可。
+
+未知的 ByCode 标识、普通 error、panic 默认走 `INTERNAL_ERROR`，公开兜底不暴露 cause。项目可显式配置 INTERNAL_ERROR 条目，但目录 DefaultStatus 本身不会改变系统兜底。启用访问日志后，可通过原始 error 追查未知标识和内部原因。
+
+## 升级
+
+```sh
+go get git.yuntuo.hk/k2safe/go-omni@v0.10.0-preview
+go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.10.0-preview
+go-omni api generate --dry-run
+go-omni api generate
+go test ./...
+```
+
+先升级框架依赖，再用同版 CLI 生成；新生成代码最低依赖 v0.10.0-preview。原来的错误构造函数、旧 `error (...)`、Codes/Messages 与已生成代码可继续运行。把业务中散落的状态/提示逐步替换为生成函数属于项目迁移工作，框架不会自动改写业务逻辑。
--- a/errors/catalog.go
+++ b/errors/catalog.go
@@ -0,0 +1,217 @@
+package apierrors
+
+import (
+	"bytes"
+	"encoding/json"
+	stdErrors "errors"
+	"fmt"
+	"io"
+	"math"
+	"reflect"
+	"strings"
+)
+
+// Definition belongs to the project. Code is the public string/integer code;
+// the Catalog map key is the distinct logical identifier used by ByCode.
+// Nil Code retains legacy response code mapping (useful when migrating).
+type Definition struct {
+	Status  int    `json:"status,omitempty"`
+	Code    any    `json:"code,omitempty"`
+	Message string `json:"message"`
+}
+
+type Catalog struct {
+	DefaultStatus int                   `json:"defaultStatus,omitempty"`
+	Definitions   map[string]Definition `json:"definitions"`
+}
+
+// UnmarshalJSON preserves int64 precision and rejects ambiguous duplicate keys.
+func (c *Catalog) UnmarshalJSON(data []byte) error {
+	type plain Catalog
+	value := plain(c.Clone())
+	if err := DecodeCatalogJSON(data, &value); err != nil {
+		return err
+	}
+	*c = Catalog(value)
+	return nil
+}
+
+// DecodeCatalogJSON strictly decodes catalog metadata without float conversion.
+// It is also used by the API compiler so runtime and contracts agree.
+func DecodeCatalogJSON(data []byte, dst any) error {
+	scan := json.NewDecoder(bytes.NewReader(data))
+	scan.UseNumber()
+	var read func() error
+	read = func() error {
+		token, err := scan.Token()
+		if err != nil {
+			return err
+		}
+		if d, ok := token.(json.Delim); ok {
+			switch d {
+			case '{':
+				seen := map[string]bool{}
+				for scan.More() {
+					k, err := scan.Token()
+					if err != nil {
+						return err
+					}
+					key, ok := k.(string)
+					if !ok {
+						return fmt.Errorf("errors: object key required")
+					}
+					if seen[key] {
+						return fmt.Errorf("errors: duplicate key %q", key)
+					}
+					seen[key] = true
+					if err := read(); err != nil {
+						return err
+					}
+				}
+			case '[':
+				for scan.More() {
+					if err := read(); err != nil {
+						return err
+					}
+				}
+			default:
+				return fmt.Errorf("errors: invalid JSON delimiter")
+			}
+			_, err = scan.Token()
+			return err
+		}
+		return nil
+	}
+	if err := read(); err != nil {
+		return err
+	}
+	if _, err := scan.Token(); err != io.EOF {
+		return fmt.Errorf("errors: one JSON value required")
+	}
+	dec := json.NewDecoder(bytes.NewReader(data))
+	dec.UseNumber()
+	dec.DisallowUnknownFields()
+	return dec.Decode(dst)
+}
+
+func (c Catalog) Clone() Catalog {
+	out := c
+	out.Definitions = make(map[string]Definition, len(c.Definitions))
+	for key, d := range c.Definitions {
+		out.Definitions[key] = d
+	}
+	return out
+}
+
+// Registry is immutable after construction and may be shared across requests.
+// It has no process-global state. Every Resolve call returns a fresh error.
+type Registry struct{ catalog Catalog }
+
+func NewRegistry(c Catalog) (*Registry, error) {
+	c = c.Clone()
+	if c.DefaultStatus == 0 {
+		c.DefaultStatus = 400
+	}
+	if !ValidErrorStatus(c.DefaultStatus) {
+		return nil, fmt.Errorf("errors: invalid defaultStatus %d", c.DefaultStatus)
+	}
+	for key, d := range c.Definitions {
+		if strings.TrimSpace(key) == "" || strings.TrimSpace(key) != key || strings.ContainsAny(key, "\r\n\t") {
+			return nil, fmt.Errorf("errors: invalid logical identifier %q", key)
+		}
+		if d.Status == 0 {
+			d.Status = c.DefaultStatus
+		}
+		if !ValidErrorStatus(d.Status) {
+			return nil, fmt.Errorf("errors: %s has invalid status %d", key, d.Status)
+		}
+		if strings.TrimSpace(d.Message) == "" {
+			return nil, fmt.Errorf("errors: %s requires a public message", key)
+		}
+		if d.Code != nil {
+			code, err := normalizeCatalogCode(d.Code)
+			if err != nil {
+				return nil, fmt.Errorf("errors: %s code: %w", key, err)
+			}
+			d.Code = code
+		}
+		c.Definitions[key] = d
+	}
+	return &Registry{catalog: c}, nil
+}
+
+// ValidErrorStatus permits final responses with a JSON body, including HTTP 200.
+func ValidErrorStatus(status int) bool {
+	return status >= 200 && status <= 599 && status != 204 && status != 205 && status != 304
+}
+
+func MustRegistry(c Catalog) *Registry {
+	r, err := NewRegistry(c)
+	if err != nil {
+		panic(err)
+	}
+	return r
+}
+func (c Catalog) Validate() error { _, err := NewRegistry(c); return err }
+func (r *Registry) Catalog() Catalog {
+	if r == nil {
+		return Catalog{}
+	}
+	return r.catalog.Clone()
+}
+
+// ByCode identifies an error without coupling business code to its HTTP policy.
+// Resolution occurs in the application's/request's registry. An unknown reference
+// becomes an internal error; its identifier and cause stay available to logs.
+func ByCode(key string) *APIError { return &APIError{Code: key, reference: true} }
+
+func (r *Registry) Resolve(err error) *APIError {
+	if err == nil {
+		return nil
+	}
+	var source *APIError
+	if !stdErrors.As(err, &source) || source == nil {
+		source = Internal(err)
+	}
+	if r != nil {
+		if d, ok := r.catalog.Definitions[source.Code]; ok {
+			return &APIError{Status: d.Status, Code: source.Code, Message: d.Message, BusinessCode: d.Code, Cause: source.Cause}
+		}
+	}
+	if source.reference {
+		source = Internal(err)
+		if r != nil {
+			if d, ok := r.catalog.Definitions[source.Code]; ok {
+				return &APIError{Status: d.Status, Code: source.Code, Message: d.Message, BusinessCode: d.Code, Cause: err}
+			}
+		}
+	}
+	copy := *source
+	return &copy
+}
+
+func normalizeCatalogCode(value any) (any, error) {
+	if v, ok := value.(string); ok {
+		if v == "" {
+			return nil, fmt.Errorf("must be nonempty")
+		}
+		return v, nil
+	}
+	if v, ok := value.(json.Number); ok {
+		n, err := v.Int64()
+		if err != nil {
+			return nil, fmt.Errorf("must be an exact int64")
+		}
+		return n, nil
+	}
+	v := reflect.ValueOf(value)
+	switch v.Kind() {
+	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+		return v.Int(), nil
+	case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
+		if v.Uint() <= math.MaxInt64 {
+			return int64(v.Uint()), nil
+		}
+	}
+	return nil, fmt.Errorf("must be a string or signed 64-bit integer")
+}
--- a/errors/catalog_test.go
+++ b/errors/catalog_test.go
@@ -0,0 +1,100 @@
+package apierrors_test
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"math"
+	"sync"
+	"testing"
+
+	apierrors "git.yuntuo.hk/k2safe/go-omni/errors"
+)
+
+func TestCatalogIsolationDefaultsAndCauses(t *testing.T) {
+	catalog := apierrors.Catalog{DefaultStatus: 200, Definitions: map[string]apierrors.Definition{
+		"FIRST": {Code: 400002, Message: "first"}, "SECOND": {Code: 400002, Message: "second"}, "DENIED": {Status: 403, Code: "denied", Message: "denied"},
+	}}
+	r, err := apierrors.NewRegistry(catalog)
+	if err != nil {
+		t.Fatal(err)
+	}
+	catalog.Definitions["FIRST"] = apierrors.Definition{Message: "changed"}
+	r.Catalog().Definitions["FIRST"] = apierrors.Definition{Message: "also changed"}
+	cause := errors.New("private secret")
+	var wg sync.WaitGroup
+	for i := 0; i < 40; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			ref := apierrors.ByCode("FIRST").WithCause(cause)
+			e := r.Resolve(fmt.Errorf("wrapped: %w", ref))
+			if e.Status != 200 || e.BusinessCode != int64(400002) || e.Message != "first" || !errors.Is(e, cause) {
+				t.Error(e)
+			}
+			e.WithCause(errors.New("different"))
+			if ref.Cause != cause || r.Resolve(apierrors.ByCode("FIRST")).Cause != nil {
+				t.Error("shared state")
+			}
+		}()
+	}
+	wg.Wait()
+	if got := r.Resolve(apierrors.ByCode("SECOND")); got.Message != "second" || got.BusinessCode != int64(400002) {
+		t.Fatal(got)
+	}
+	if got := r.Resolve(apierrors.ByCode("DENIED")); got.Status != 403 || got.BusinessCode != "denied" {
+		t.Fatal(got)
+	}
+	other := apierrors.MustRegistry(apierrors.Catalog{Definitions: map[string]apierrors.Definition{"FIRST": {Status: 409, Code: 9, Message: "other"}}})
+	if got := other.Resolve(apierrors.ByCode("FIRST")); got.Status != 409 || got.Message != "other" {
+		t.Fatal(got)
+	}
+	if got := r.Resolve(apierrors.ByCode("MISSING").WithCause(cause)); got.Status != 500 || got.Code != "INTERNAL_ERROR" || got.Message == cause.Error() || !errors.Is(got, cause) {
+		t.Fatal(got)
+	}
+	if got := apierrors.From(apierrors.ByCode("MISSING")); got.Status != 500 {
+		t.Fatal(got)
+	}
+	legacy := apierrors.New(422, "OLD", "legacy")
+	if got := r.Resolve(legacy); got == legacy || got.Status != 422 || got.Message != "legacy" {
+		t.Fatal(got)
+	}
+}
+
+func TestCatalogStrictJSONAndValues(t *testing.T) {
+	raw := `{"defaultStatus":200,"definitions":{"LARGE":{"code":9223372036854775807,"message":"large"}}}`
+	var c apierrors.Catalog
+	if err := json.Unmarshal([]byte(raw), &c); err != nil {
+		t.Fatal(err)
+	}
+	e := apierrors.MustRegistry(c).Resolve(apierrors.ByCode("LARGE"))
+	if e.BusinessCode != int64(math.MaxInt64) {
+		t.Fatal(e.BusinessCode)
+	}
+	for _, raw := range []string{
+		`{"definitions":{"A":{"code":1,"message":"a"},"A":{"code":2,"message":"b"}}}`,
+		`{"definitions":{"A":{"code":1,"code":2,"message":"a"}}}`,
+		`{"definitions":{"A":{"code":1,"message":"a","typo":true}}}`,
+		`{"defaultStatus":204,"definitions":{}}`,
+		`{"definitions":{"A":{"code":1.5,"message":"a"}}}`,
+		`{"definitions":{"A":{"code":9223372036854775808,"message":"a"}}}`,
+	} {
+		var invalid apierrors.Catalog
+		err := json.Unmarshal([]byte(raw), &invalid)
+		if err == nil {
+			err = invalid.Validate()
+		}
+		if err == nil {
+			t.Errorf("accepted %s", raw)
+		}
+	}
+	for _, status := range []int{0, 99, 199, 204, 205, 304, 600} {
+		c := apierrors.Catalog{Definitions: map[string]apierrors.Definition{"A": {Status: status, Code: "a", Message: "a"}}}
+		if status == 0 {
+			continue
+		}
+		if c.Validate() == nil {
+			t.Fatal(status)
+		}
+	}
+}
--- a/errors/errors.go
+++ b/errors/errors.go
@@ -12,6 +12,8 @@ type APIError struct {
 	Code         string
 	Message      string
 	Cause        error
+	BusinessCode any // Optional public code resolved from a project catalog.
+	reference    bool
 }

 func (e *APIError) Error() string {
@@ -68,6 +70,9 @@ func From(err error) *APIError {
 	}
 	var apiErr *APIError
 	if stdErrors.As(err, &apiErr) && apiErr != nil {
+		if apiErr.reference {
+			return Internal(err)
+		}
 		return apiErr
 	}
 	return Internal(err)
--- a/examples/contracts/errors.api
+++ b/examples/contracts/errors.api
@@ -0,0 +1,36 @@
+syntax = "v1"
+
+errorCatalog CommonErrors (
+    defaultStatus: 200
+    errors: {
+        "UsernameInvalid": {"key": "USERNAME_INVALID", "code": 400002, "message": "用户名格式不正确"},
+        "PasswordInvalid": {"key": "PASSWORD_INVALID", "code": 400002, "message": "密码格式不正确"},
+        "PermissionDenied": {"key": "PERMISSION_DENIED", "status": 403, "code": 403001, "message": "没有权限"}
+    }
+)
+
+response CommonResponse (
+    codeType: int32
+    successCode: 0
+    errorCode: 9999
+    body: {"ok": "${ok}", "code": "${code}", "data": "${data}"}
+    errorBody: {"ok": "${ok}", "code": "${code}", "msg": "${message}"}
+)
+
+type TokenResponse {
+    Token string `json:"token"`
+}
+
+@server (
+    group: account
+    response: CommonResponse
+    errors: UsernameInvalid, PasswordInvalid, PermissionDenied
+)
+service errors-api {
+    @handler token
+    post /token returns (TokenResponse)
+
+    @response raw
+    @handler raw
+    get /raw returns (TokenResponse)
+}
--- a/httpx/bridge.go
+++ b/httpx/bridge.go
@@ -45,10 +45,18 @@ func WrapMiddleware(middleware func(http.Handler) http.Handler) Middleware {
 				child.writer.(interface{ inheritCommit(int) }).inheritCommit(c.Status())
 			}
 			defer CleanupMultipart(r)
-			defer func() { c.values = child.values; c.encoder = child.encoder }()
-			if err := next(child); err != nil && !c.Responded() {
+			defer func() {
+				c.values = child.values
+				c.encoder = child.encoder
+				c.errorRegistry = child.errorRegistry
+				c.failure = child.failure
+			}()
+			if err := next(child); err != nil {
+				child.RecordError(err)
+				if !c.Responded() {
 					child.WriteError(err)
 				}
+			}
 		}))
 		if wrapped == nil {
 			panic("httpx: HTTP middleware returned nil handler")
--- a/httpx/context.go
+++ b/httpx/context.go
@@ -95,6 +95,8 @@ type Context struct {
 	responded     bool
 	status        int
 	encoder       response.Encoder
+	errorRegistry *apierrors.Registry
+	failure       *apierrors.APIError
 }

 // NewContext creates a transport-neutral GoOmni context.
@@ -133,6 +135,7 @@ func (c *Context) Raw() http.ResponseWriter { return c.writer }
 func (c *Context) Clone(ctx context.Context, writer http.ResponseWriter) *Context {
 	clone := NewContext(c.request.Clone(ctx), writer, c.params)
 	clone.encoder = c.encoder
+	clone.errorRegistry = c.errorRegistry
 	for key, value := range c.values {
 		clone.values[key] = value
 	}
@@ -279,8 +282,11 @@ func (c *Context) WriteError(err error) {
 	if errors.As(err, &bodyErr) {
 		err = bodyTooLarge()
 	}
-	apiErr := apierrors.From(err)
+	apiErr := c.ResolveError(err)
+	c.failure = apiErr
 	if writeErr := c.writeResult(response.Result{
+		BusinessCode: apiErr.BusinessCode,
+		Failed:       true,
 		Status:       apiErr.Status,
 		Code:         apiErr.Code,
 		Message:      apiErr.Message,
@@ -291,3 +297,28 @@ func (c *Context) WriteError(err error) {
 		_ = c.WriteResponse(http.StatusInternalServerError, nil, nil)
 	}
 }
+
+// SetErrorRegistry sets an application fallback. Route encoders can supply their
+// own registry; clones retain both policies without any process-global lookup.
+func (c *Context) SetErrorRegistry(r *apierrors.Registry) { c.errorRegistry = r }
+func (c *Context) ResolveError(err error) *apierrors.APIError {
+	registry := c.errorRegistry
+	if provider, ok := c.encoder.(response.ErrorRegistryProvider); ok {
+		if scoped := provider.ErrorRegistry(); scoped != nil {
+			registry = scoped
+		}
+	}
+	return registry.Resolve(err)
+}
+
+// RecordError preserves failure semantics when a middleware commits buffered bytes.
+func (c *Context) RecordError(err error) { c.failure = c.ResolveError(err) }
+
+// Failure returns a detached description of a failure already handled by Context.
+func (c *Context) Failure() *apierrors.APIError {
+	if c.failure == nil {
+		return nil
+	}
+	copy := *c.failure
+	return &copy
+}
--- a/metrics/metrics.go
+++ b/metrics/metrics.go
@@ -7,7 +7,6 @@ import (
 	"sync/atomic"
 	"time"

-	apierrors "git.yuntuo.hk/k2safe/go-omni/errors"
 	"git.yuntuo.hk/k2safe/go-omni/httpx"
 )

@@ -46,10 +45,10 @@ func (m *Metrics) Middleware() httpx.Middleware {
 			err := next(ctx)
 			status := ctx.Status()
 			if err != nil && !ctx.Responded() {
-				status = apierrors.From(err).Status
+				status = ctx.ResolveError(err).Status
 			}
 			m.requests.Add(1)
-			if err != nil || status >= 400 {
+			if err != nil || ctx.Failure() != nil || status >= 400 {
 				m.errors.Add(1)
 			}
 			if status >= 0 && status < len(m.statuses) {
--- a/middleware/idempotency.go
+++ b/middleware/idempotency.go
@@ -31,6 +31,7 @@ type IdempotencyConfig struct {

 type replay struct {
 	fingerprint     [32]byte
+	errorCode       string
 	status          int
 	headers         http.Header
 	body            []byte
@@ -150,8 +151,12 @@ func (i *Idempotency) Middleware() httpx.Middleware {
 					return apierrors.New(409, "IDEMPOTENCY_UNAVAILABLE", "request is in progress or its outcome cannot be replayed")
 				}
 				status, headers, data := saved.status, saved.headers.Clone(), append([]byte(nil), saved.body...)
+				errorCode := saved.errorCode
 				i.mu.Unlock()
 				headers.Set("Idempotency-Replayed", "true")
+				if errorCode != "" {
+					c.RecordError(apierrors.New(status, errorCode, ""))
+				}
 				return c.WriteResponse(status, headers, data)
 			}
 			if len(i.items) >= i.config.MaxEntries {
@@ -171,6 +176,9 @@ func (i *Idempotency) Middleware() httpx.Middleware {
 				saved.failed = true
 				saved.expires = i.now().Add(i.config.TTL)
 				size := buffer.body.Len()
+				if failure := c.Failure(); failure != nil {
+					size += len(failure.Code)
+				}
 				for k, values := range buffer.headers {
 					size += len(k)
 					for _, v := range values {
@@ -180,6 +188,9 @@ func (i *Idempotency) Middleware() httpx.Middleware {
 				if buffer.complete && buffer.err == nil && buffer.status < 500 && buffer.headers.Get("Set-Cookie") == "" && !strings.Contains(strings.ToLower(buffer.headers.Get("Cache-Control")), "no-store") && size <= i.config.MaxBytes-i.bytes {
 					saved.failed = false
 					saved.status = buffer.status
+					if failure := c.Failure(); failure != nil {
+						saved.errorCode = failure.Code
+					}
 					saved.headers = buffer.headers.Clone()
 					saved.body = append([]byte(nil), buffer.body.Bytes()...)
 					saved.size = size
@@ -202,6 +213,9 @@ func (i *Idempotency) Middleware() httpx.Middleware {
 			if buffer.status == 0 {
 				buffer.status = 200
 			}
+			if failure := child.Failure(); failure != nil {
+				c.RecordError(failure)
+			}
 			buffer.complete = true
 			return c.WriteResponse(buffer.status, buffer.headers, buffer.body.Bytes())
 		}
--- a/middleware/middleware.go
+++ b/middleware/middleware.go
@@ -73,10 +73,10 @@ func AccessLog(options ...AccessLogOption) httpx.Middleware {
 		return func(ctx *httpx.Context) error {
 			started := time.Now()
 			err := next(ctx)
-			status := ctx.Status()
 			if err != nil && !ctx.Responded() {
-				status = apierrors.From(err).Status
+				ctx.WriteError(err)
 			}
+			status := ctx.Status()
 			duration := time.Since(started)
 			slow := settings.slowThreshold > 0 && duration >= settings.slowThreshold
 			attrs := []any{
@@ -87,6 +87,16 @@ func AccessLog(options ...AccessLogOption) httpx.Middleware {
 				"durationMs", duration.Seconds() * 1000,
 				"clientIp", ctx.ClientIP(),
 			}
+			failure := ctx.Failure()
+			if failure == nil && err != nil {
+				failure = ctx.ResolveError(err)
+			}
+			if failure != nil {
+				attrs = append(attrs, "failed", true, "errorKey", failure.Code)
+				if failure.BusinessCode != nil {
+					attrs = append(attrs, "businessCode", failure.BusinessCode)
+				}
+			}
 			if slow {
 				attrs = append(attrs, "slow", true)
 			}
--- a/middleware/sharedIdempotency.go
+++ b/middleware/sharedIdempotency.go
@@ -15,6 +15,7 @@ import (

 type StoredResponse struct {
 	Status    int         `json:"status"`
+	ErrorCode string      `json:"errorCode,omitempty"`
 	Headers   http.Header `json:"headers"`
 	Body      []byte      `json:"body"`
 }
@@ -54,6 +55,9 @@ func (i *Idempotency) shared(c *httpx.Context, next httpx.Handler, id, fingerpri
 		response := record.Response
 		headers := response.Headers.Clone()
 		headers.Set("Idempotency-Replayed", "true")
+		if response.ErrorCode != "" {
+			c.RecordError(apierrors.New(response.Status, response.ErrorCode, ""))
+		}
 		return c.WriteResponse(response.Status, headers, response.Body)
 	}
 	completed := false
@@ -84,9 +88,15 @@ func (i *Idempotency) shared(c *httpx.Context, next httpx.Handler, id, fingerpri
 	if buffer.status == 0 {
 		buffer.status = 200
 	}
+	if failure := child.Failure(); failure != nil {
+		c.RecordError(failure)
+	}
 	var response *StoredResponse
 	if buffer.status < 500 && buffer.headers.Get("Set-Cookie") == "" && !strings.Contains(strings.ToLower(buffer.headers.Get("Cache-Control")), "no-store") {
 		response = &StoredResponse{Status: buffer.status, Headers: buffer.headers.Clone(), Body: append([]byte(nil), buffer.body.Bytes()...)}
+		if failure := child.Failure(); failure != nil {
+			response.ErrorCode = failure.Code
+		}
 	}
 	if err = finish(response); err != nil {
 		return apierrors.New(503, "IDEMPOTENCY_UNAVAILABLE", "outcome requires reconciliation").WithCause(err)
--- a/omni.go
+++ b/omni.go
@@ -26,6 +26,7 @@ type HTTPRouterGroup = httpx.RouterGroup
 type APIError = apierrors.APIError
 type Config = config.Config
 type TLSConfig = config.TLSConfig
+type HTTPConfig = config.HTTPConfig
 type Option = config.Option
 type Response = response.Response
 type LogConfig = logx.Config
@@ -48,6 +49,8 @@ func WithRequestIDHeader(header string) Option { return config.WithRequestIDHead

 func WithLogger(enabled bool) Option { return config.WithLogger(enabled) }

+func WithErrors(catalog apierrors.Catalog) Option { return config.WithErrors(catalog) }
+
 func WithResponse(settings response.Config) Option { return config.WithResponse(settings) }

 func WithResponseEncoder(encoder response.Encoder) Option { return config.WithResponseEncoder(encoder) }
@@ -62,6 +65,8 @@ func WithConfig(settings Config) Option { return config.WithConfig(settings) }

 func WithTransport(name string) Option { return config.WithTransport(name) }

+func WithHTTPConfig(settings HTTPConfig) Option { return config.WithHTTPConfig(settings) }
+
 func WithTLS(certFile, keyFile string) Option { return config.WithTLS(certFile, keyFile) }

 func WithLogConfig(settings LogConfig) Option { return config.WithLogConfig(settings) }
--- a/performance/compatibilityAcceptance.md
+++ b/performance/compatibilityAcceptance.md
@@ -17,7 +17,15 @@

 ## 远程验收

-发布后执行 `scripts/verifyCompatibilityRelease.py --version v0.9.0-preview`，结果生成到 `performance/compatibilityRemote.json`，校验从全新 module cache 安装的 CLI 与消费者固定依赖、无本地 replace、重生成保护和运行时行为。该结果在 main 单独记录，发布标签保持不可变。
+已执行 `scripts/verifyCompatibilityRelease.py --version v0.9.0-preview`，通过。详见 [远程验收记录](compatibilityRemote.json)。
+
+- 从全新 module cache 安装发布版 CLI，消费者固定依赖 `v0.9.0-preview`，无本地 replace。
+- 消费者实际生成、race 测试、自定义 ID/动态 JSON、请求体限额、上传清理、原文签名、下载和重生成保护通过。
+- 发布源码：`a8c973d8a2c24f3cc572f32a976349d9a97427a1`。
+- module 校验和：`h1:cYpW6HwZnLHsxq7thO1C2pR/H3vyoUQQhuBVuEHhtHw=`。
+- 耗时 13.51 秒；临时目录和缓存已清理。脚本与 fixture 哈希保存在 JSON 中。
+
+验收结果在 main 单独记录，发布标签保持不可变。

 ## 范围

--- a/performance/compatibilityRemote.json
+++ b/performance/compatibilityRemote.json
@@ -0,0 +1,31 @@
+{
+  "passed": true,
+  "frameworkVersion": "v0.9.0-preview",
+  "frameworkSum": "h1:cYpW6HwZnLHsxq7thO1C2pR/H3vyoUQQhuBVuEHhtHw=",
+  "freshModuleCache": true,
+  "noLocalReplace": true,
+  "durationSeconds": 13.51,
+  "checks": [
+    "remoteCLIInstall",
+    "scalarContractValidation",
+    "manualProjectGeneration",
+    "int64MaxValueOnWire",
+    "dynamicJSON",
+    "rawBodySignature",
+    "routeBodyLimits",
+    "multipartTempCleanup",
+    "unwrappedDownloads",
+    "handwrittenFilesPreserved",
+    "generatedConsumerRaceTests",
+    "fixedRemoteModuleChecksum"
+  ],
+  "sourceHashes": {
+    "scripts/verifyCompatibilityRelease.py": "90e487d3203ed4eb4bc721da8086356413345b3e05193e473250a834aeb8d293",
+    "cmd/go-omni/apigen/compatibility_test.go": "98cf5fbe6cb6413c12f709806d385726f3dec1468575f76967786de4707667ba",
+    "examples/contracts/compatibility.api": "3ede909e7f60386012e55c916a8e4887dd08562e7f023665f663288c809873d4",
+    "cmd/go-omni/apigen/testdata/compatibility/consumer_test.go": "0a99ffd6a5cc16d47ae8208d9140c8d6afd9c19106fac8e5e61096cb90d8c463",
+    "cmd/go-omni/apigen/testdata/compatibility/hooks.go": "435baf37c7f8adffd18d4be0353a791124e0bc5dcb79abdcc345276b6f9867f4",
+    "cmd/go-omni/apigen/testdata/compatibility/echo.go": "9e13cb18a0951974e723a1fd915c0f4610d823c95eadb752c3d1cd75c44fa293",
+    "cmd/go-omni/apigen/testdata/compatibility/download.go": "e7f4bcdb34c90ec63fdab1f3c4e524964ac153944352d8a9053a9f19b74030fd"
+  }
+}
--- a/performance/connectorAcceptance.md
+++ b/performance/connectorAcceptance.md
@@ -0,0 +1,36 @@
+# v0.9.1-preview Connector 与 HTTP 配置验收
+
+## 范围
+
+新增标准 `driver.Connector` 注入和 HTTP 服务器读写配置；没有修改 eTax/ePay 业务代码。数据库驱动/TLS/Logger/时区/版本校验仍归项目。网络测试只监听本地回环地址，MySQL 使用独立本地容器（1 CPU / 768 MiB / 128 PID），没有使用业务服务器压测。
+
+## 全量回归
+
+- `GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race -p=1 -count=1 -timeout=300s ./...`：40 个有测试的包全部通过，包含真实脚手架/契约生成的集成消费者。
+- `go vet ./...`、`go build ./...`、gofmt、`git diff --check` 通过。
+
+## 专项验收
+
+- `go test -race -count=3 ./database ./app ./config` 通过。
+- 两个 Connector 并发读写保持独立；启动 Connect/Ping 与查询 context 保留，后台补连接遵循 database/sql 行为；最大连接数、禁用 idle、连接生命周期、健康检查等待上限及恢复验证通过。
+- nil/带类型的 nil、无效参数、启动前取消不取得 Connector 所有权；Connect/Ping 失败与超时关闭池，清理错误和原错误可同时检查；成功关闭幂等，事务提交/错误/panic 回滚通过。
+- 标准库服务器字段、ErrorLog 透传、无效配置启动前返回并清理资源、JSON/YAML/环境变量覆盖通过；不支持的独立 http2 选项明确拒绝。
+- nethttp/native 的实际 TCP 慢请求头、慢 body、Keep-Alive 空闲关闭、Flush 后客户端停止读取触发写超时、超限头 431 通过。测试不假定两种网络层有完全相同的超时响应格式。
+- `scripts/verifyConnector.py --local` 的独立消费者通过：真实 MySQL 8.4 TLS、错误 CA/主机名拒绝、不同 session time_zone、每个 Connector 的驱动 Logger、两池独立关闭、事务提交/回滚。所有专项测试无跳过，详情见 [本地记录](connectorLocal.json)。
+- MySQL 镜像固定记录为 `sha256:1afd25fe334a1be64a3866495dd43a6bdba3c55dd1d6190ea12933163fe2843c`。临时容器、卷、证书、凭据及消费者目录已清理。
+
+环境：`go version go1.27.1 darwin/arm64`。记录时间：2026-09-23T18:17:16.897323+00:00。
+
+独立 `TransportHTTP2` 的逐请求读写时限未实现，本次没有进行 Linux soak、代理长测或完整业务迁移验收。
+
+## 远程验收
+
+发布后两条独立远程验收均通过；各自使用全新 module cache，消费者依赖固定版本，无本地 replace。
+
+- 发布标签：`v0.9.1-preview`；源码：`20e84e5ff86d872f42301cd3c256030fc41c8ce2`。
+- module 校验和：`h1:yCqjVGv4rH8UN2M3WzjraNEfdEI6WJD2A64F4HFP0FI=`。
+- Connector/HTTP 远程消费者执行全部专项 race 测试及真实 MySQL TLS 用例，无跳过；耗时 16.49 秒，详见 [Connector 远程记录](connectorRemote.json)。
+- 从远程安装 CLI，生成消费者，验证标量、动态 JSON、上传/原文签名、下载、请求体上限和重生成保护；耗时 13.27 秒，详见 [CLI 远程记录](connectorCompatibilityRemote.json)。
+- 两条验收脚本确认相同框架校验和；临时消费者、缓存、数据库容器与测试证书/凭据已清理。fixture 哈希与当前文件核对一致。
+
+结果在 main 单独追加，已发布标签保持不可变。
--- a/performance/connectorCompatibilityRemote.json
+++ b/performance/connectorCompatibilityRemote.json
@@ -0,0 +1,31 @@
+{
+  "passed": true,
+  "frameworkVersion": "v0.9.1-preview",
+  "frameworkSum": "h1:yCqjVGv4rH8UN2M3WzjraNEfdEI6WJD2A64F4HFP0FI=",
+  "freshModuleCache": true,
+  "noLocalReplace": true,
+  "durationSeconds": 13.27,
+  "checks": [
+    "remoteCLIInstall",
+    "scalarContractValidation",
+    "manualProjectGeneration",
+    "int64MaxValueOnWire",
+    "dynamicJSON",
+    "rawBodySignature",
+    "routeBodyLimits",
+    "multipartTempCleanup",
+    "unwrappedDownloads",
+    "handwrittenFilesPreserved",
+    "generatedConsumerRaceTests",
+    "fixedRemoteModuleChecksum"
+  ],
+  "sourceHashes": {
+    "scripts/verifyCompatibilityRelease.py": "90e487d3203ed4eb4bc721da8086356413345b3e05193e473250a834aeb8d293",
+    "cmd/go-omni/apigen/compatibility_test.go": "98cf5fbe6cb6413c12f709806d385726f3dec1468575f76967786de4707667ba",
+    "examples/contracts/compatibility.api": "3ede909e7f60386012e55c916a8e4887dd08562e7f023665f663288c809873d4",
+    "cmd/go-omni/apigen/testdata/compatibility/consumer_test.go": "0a99ffd6a5cc16d47ae8208d9140c8d6afd9c19106fac8e5e61096cb90d8c463",
+    "cmd/go-omni/apigen/testdata/compatibility/hooks.go": "435baf37c7f8adffd18d4be0353a791124e0bc5dcb79abdcc345276b6f9867f4",
+    "cmd/go-omni/apigen/testdata/compatibility/echo.go": "9e13cb18a0951974e723a1fd915c0f4610d823c95eadb752c3d1cd75c44fa293",
+    "cmd/go-omni/apigen/testdata/compatibility/download.go": "e7f4bcdb34c90ec63fdab1f3c4e524964ac153944352d8a9053a9f19b74030fd"
+  }
+}
--- a/performance/connectorLocal.json
+++ b/performance/connectorLocal.json
@@ -0,0 +1,70 @@
+{
+  "passed": true,
+  "frameworkVersion": "v0.9.1-preview",
+  "localSource": true,
+  "frameworkSum": null,
+  "freshModuleCache": false,
+  "noLocalReplace": false,
+  "mysqlImage": "sha256:1afd25fe334a1be64a3866495dd43a6bdba3c55dd1d6190ea12933163fe2843c",
+  "mysqlLimits": {
+    "cpus": 1,
+    "memoryMiB": 768,
+    "pids": 128
+  },
+  "durationSeconds": 9.61,
+  "tests": [
+    "TestHTTPFileAndEnvironment/server.json",
+    "TestHTTPFileAndEnvironment/server.yaml",
+    "TestHTTPFileAndEnvironment",
+    "TestHTTPInvalidAndUnsupportedSettings/READ_HEADER_TIMEOUTinvalid",
+    "TestHTTPInvalidAndUnsupportedSettings/READ_HEADER_TIMEOUT-1",
+    "TestHTTPInvalidAndUnsupportedSettings/READ_TIMEOUTinvalid",
+    "TestHTTPInvalidAndUnsupportedSettings/READ_TIMEOUT-1",
+    "TestHTTPInvalidAndUnsupportedSettings/WRITE_TIMEOUTinvalid",
+    "TestHTTPInvalidAndUnsupportedSettings/WRITE_TIMEOUT-1",
+    "TestHTTPInvalidAndUnsupportedSettings/IDLE_TIMEOUTinvalid",
+    "TestHTTPInvalidAndUnsupportedSettings/IDLE_TIMEOUT-1",
+    "TestHTTPInvalidAndUnsupportedSettings/MAX_HEADER_BYTESinvalid",
+    "TestHTTPInvalidAndUnsupportedSettings/MAX_HEADER_BYTES-1",
+    "TestHTTPInvalidAndUnsupportedSettings",
+    "TestHTTPConfiguredStandardServer",
+    "TestHTTPInvalidStartupReleasesResources",
+    "TestHTTPConfiguredNetworkLimits/nethttp/slowHeaders",
+    "TestHTTPConfiguredNetworkLimits/nethttp/slowBody",
+    "TestHTTPConfiguredNetworkLimits/nethttp/idle",
+    "TestHTTPConfiguredNetworkLimits/nethttp/writeBackpressure",
+    "TestConnectorIndependentPoolsAndContext",
+    "TestConnectorRejectsInvalidInputWithoutTakingOwnership",
+    "TestConnectorStartupFailuresReleaseResources/connect",
+    "TestConnectorStartupFailuresReleaseResources/ping",
+    "TestConnectorStartupFailuresReleaseResources",
+    "TestConnectorTimeoutBoundsConnectAndPing/connect",
+    "TestConnectorTimeoutBoundsConnectAndPing/ping",
+    "TestConnectorTimeoutBoundsConnectAndPing",
+    "TestConnectorHealthBoundsPoolWaitAndRecovers",
+    "TestConnectorIdleZeroAndLifetime/noIdle",
+    "TestConnectorIdleZeroAndLifetime/expired",
+    "TestConnectorIdleZeroAndLifetime",
+    "TestConnectorTransactionsKeepCommitAndRollbackSemantics",
+    "TestMySQLConnectorDriverLoggerIsolation",
+    "TestMySQLConnectorTLSAndPoolIsolation/untrustedCA",
+    "TestMySQLConnectorTLSAndPoolIsolation/wrongHostname",
+    "TestMySQLConnectorTLSAndPoolIsolation",
+    "TestHTTPConfiguredNetworkLimits/nethttp/headerLimit",
+    "TestHTTPConfiguredNetworkLimits/nethttp",
+    "TestHTTPConfiguredNetworkLimits/native/slowHeaders",
+    "TestHTTPConfiguredNetworkLimits/native/slowBody",
+    "TestHTTPConfiguredNetworkLimits/native/idle",
+    "TestHTTPConfiguredNetworkLimits/native/writeBackpressure",
+    "TestHTTPConfiguredNetworkLimits/native/headerLimit",
+    "TestHTTPConfiguredNetworkLimits/native",
+    "TestHTTPConfiguredNetworkLimits"
+  ],
+  "sourceHashes": {
+    "database/connector_test.go": "0663dfc9794ba24130225fa3b6418a6d5f75d57d0f01686151f70c7ea3f592c0",
+    "database/mysqlConnector_test.go": "e1cdd11ef76b09f1332ba92bfdde5b1917d84c85cc42fac48f65a8b23f5e9720",
+    "app/httpConfig_test.go": "b060dc0b76fb8e5feebae7e3b12cb7bca845693fcc097e2a0496a5ba937c837a",
+    "config/http_test.go": "0cae3dcf213369cfaff5487bf630c2bc3ec097739ca1d40794124e69c3880db8",
+    "scripts/verifyConnector.py": "a0ba3fa29a4d1efcbed5dad82c09afb97d8ddecd904f20fee1e3aa74ec0f9e06"
+  }
+}
--- a/performance/connectorRemote.json
+++ b/performance/connectorRemote.json
@@ -0,0 +1,70 @@
+{
+  "passed": true,
+  "frameworkVersion": "v0.9.1-preview",
+  "localSource": false,
+  "frameworkSum": "h1:yCqjVGv4rH8UN2M3WzjraNEfdEI6WJD2A64F4HFP0FI=",
+  "freshModuleCache": true,
+  "noLocalReplace": true,
+  "mysqlImage": "sha256:1afd25fe334a1be64a3866495dd43a6bdba3c55dd1d6190ea12933163fe2843c",
+  "mysqlLimits": {
+    "cpus": 1,
+    "memoryMiB": 768,
+    "pids": 128
+  },
+  "durationSeconds": 16.49,
+  "tests": [
+    "TestHTTPConfiguredStandardServer",
+    "TestHTTPInvalidStartupReleasesResources",
+    "TestHTTPConfiguredNetworkLimits/nethttp/slowHeaders",
+    "TestHTTPConfiguredNetworkLimits/nethttp/slowBody",
+    "TestHTTPConfiguredNetworkLimits/nethttp/idle",
+    "TestHTTPConfiguredNetworkLimits/nethttp/writeBackpressure",
+    "TestHTTPFileAndEnvironment/server.json",
+    "TestHTTPFileAndEnvironment/server.yaml",
+    "TestHTTPFileAndEnvironment",
+    "TestHTTPInvalidAndUnsupportedSettings/READ_HEADER_TIMEOUTinvalid",
+    "TestHTTPInvalidAndUnsupportedSettings/READ_HEADER_TIMEOUT-1",
+    "TestHTTPInvalidAndUnsupportedSettings/READ_TIMEOUTinvalid",
+    "TestHTTPInvalidAndUnsupportedSettings/READ_TIMEOUT-1",
+    "TestHTTPInvalidAndUnsupportedSettings/WRITE_TIMEOUTinvalid",
+    "TestHTTPInvalidAndUnsupportedSettings/WRITE_TIMEOUT-1",
+    "TestHTTPInvalidAndUnsupportedSettings/IDLE_TIMEOUTinvalid",
+    "TestHTTPInvalidAndUnsupportedSettings/IDLE_TIMEOUT-1",
+    "TestHTTPInvalidAndUnsupportedSettings/MAX_HEADER_BYTESinvalid",
+    "TestHTTPInvalidAndUnsupportedSettings/MAX_HEADER_BYTES-1",
+    "TestHTTPInvalidAndUnsupportedSettings",
+    "TestConnectorIndependentPoolsAndContext",
+    "TestConnectorRejectsInvalidInputWithoutTakingOwnership",
+    "TestConnectorStartupFailuresReleaseResources/connect",
+    "TestConnectorStartupFailuresReleaseResources/ping",
+    "TestConnectorStartupFailuresReleaseResources",
+    "TestConnectorTimeoutBoundsConnectAndPing/connect",
+    "TestConnectorTimeoutBoundsConnectAndPing/ping",
+    "TestConnectorTimeoutBoundsConnectAndPing",
+    "TestConnectorHealthBoundsPoolWaitAndRecovers",
+    "TestConnectorIdleZeroAndLifetime/noIdle",
+    "TestConnectorIdleZeroAndLifetime/expired",
+    "TestConnectorIdleZeroAndLifetime",
+    "TestConnectorTransactionsKeepCommitAndRollbackSemantics",
+    "TestMySQLConnectorDriverLoggerIsolation",
+    "TestMySQLConnectorTLSAndPoolIsolation/untrustedCA",
+    "TestMySQLConnectorTLSAndPoolIsolation/wrongHostname",
+    "TestMySQLConnectorTLSAndPoolIsolation",
+    "TestHTTPConfiguredNetworkLimits/nethttp/headerLimit",
+    "TestHTTPConfiguredNetworkLimits/nethttp",
+    "TestHTTPConfiguredNetworkLimits/native/slowHeaders",
+    "TestHTTPConfiguredNetworkLimits/native/slowBody",
+    "TestHTTPConfiguredNetworkLimits/native/idle",
+    "TestHTTPConfiguredNetworkLimits/native/writeBackpressure",
+    "TestHTTPConfiguredNetworkLimits/native/headerLimit",
+    "TestHTTPConfiguredNetworkLimits/native",
+    "TestHTTPConfiguredNetworkLimits"
+  ],
+  "sourceHashes": {
+    "database/connector_test.go": "0663dfc9794ba24130225fa3b6418a6d5f75d57d0f01686151f70c7ea3f592c0",
+    "database/mysqlConnector_test.go": "e1cdd11ef76b09f1332ba92bfdde5b1917d84c85cc42fac48f65a8b23f5e9720",
+    "app/httpConfig_test.go": "b060dc0b76fb8e5feebae7e3b12cb7bca845693fcc097e2a0496a5ba937c837a",
+    "config/http_test.go": "0cae3dcf213369cfaff5487bf630c2bc3ec097739ca1d40794124e69c3880db8",
+    "scripts/verifyConnector.py": "a0ba3fa29a4d1efcbed5dad82c09afb97d8ddecd904f20fee1e3aa74ec0f9e06"
+  }
+}
--- a/performance/errorCatalogAcceptance.md
+++ b/performance/errorCatalogAcceptance.md
@@ -0,0 +1,32 @@
+# v0.10.0-preview 统一错误目录验收
+
+## 范围
+
+项目定义错误目录，框架解析逻辑标识、HTTP 状态、对外业务码及公开提示；支持 HTTP 200 的业务失败，并贯通 `.api` 生成、响应、日志、指标、链路和错误重放。没有修改 eTax/ePay 业务代码，也没有使用业务服务器压测。
+
+目录与响应模板分离；不同 App、路由可选择不同目录和协议。系统兜底不受 DefaultStatus 隐式影响，自定义 Encoder 继续控制最终输出。
+
+## 本地回归
+
+环境：go1.27.1 darwin/arm64。验收日期：2026-09-24。
+
+- `GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race -p=1 -count=1 -timeout=300s ./...` 全部通过，包含实际生成并编译的脚手架/契约消费者。
+- 全量之后增加配置快照隔离与 Encoder 包装策略测试，完成 `go test -race -count=1 ./response ./config ./cmd/go-omni/apigen`。
+- 本地/共享幂等错误元数据补充用例通过 `go test -race -count=1 ./app ./config ./httpx ./middleware/... ./metrics ./response ./telemetry`。
+- `go vet ./...`、`go build ./...`、gofmt、`git diff --check` 与 CLI 校验 `examples/contracts/errors.api` 通过。
+
+## 专项覆盖
+
+- 多 App 隔离、目录复制、配置快照隔离、静态配置变更要求重启；并发解析及 WithCause 不互相污染。
+- JSON/YAML 精确 int64、字符串/整数类型与范围、重复 key、非法状态/字段/映射冲突拒绝。重复对外业务码允许保留独立提示。
+- HTTP 200 业务失败、403 单项覆盖、未知标识 500、内部原因不进入默认公开响应、已提交响应不追加、文本 ACK 由自定义 Encoder 输出。
+- RawJSON 成功不包装、失败保持错误响应；嵌套相同/空目录保留已有策略，不同目录叠加明确拒绝。
+- 访问日志记录最终状态和业务失败；指标计入 HTTP 200 失败，链路保留状态与失败标记。标准中间件、本地/共享幂等重放保留失败语义。
+- 多文件导入、多个目录和不同码类型的路由作用域；200 成功/失败 OpenAPI anyOf、多错误同码的独立示例。
+- 实际生成项目的无参数错误函数、全局中间件提前返回时的路由目录、unknown fallback、raw 成功/失败、手写文件重生成保护。
+
+## 验证边界
+
+共享幂等新增用例使用 JSON 序列化的内存替身，验证字段在持久化边界上保留；未为本特性运行外部 Redis 服务。没有进行 Linux soak、代理长测或完整业务迁移验收。业务项目仍需升级框架/CLI，并逐步将散落错误改为目录调用。
+
+远程固定版本验收在发布后追加，已发布标签保持不可变。
--- a/response/catalog_test.go
+++ b/response/catalog_test.go
@@ -0,0 +1,82 @@
+package response_test
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	apierrors "git.yuntuo.hk/k2safe/go-omni/errors"
+	"git.yuntuo.hk/k2safe/go-omni/response"
+)
+
+func TestCatalogHTTP200AndRawJSON(t *testing.T) {
+	c := apierrors.Catalog{DefaultStatus: 200, Definitions: map[string]apierrors.Definition{"INVALID": {Code: 400002, Message: "invalid"}}}
+	cfg := response.Config{CodeType: "int32", SuccessCode: 0, ErrorCode: 9999, ErrorMessage: "fallback", Body: map[string]any{"ok": "${ok}", "code": "${code}", "data": "${data}"}, ErrorBody: map[string]any{"failed": "${ok}", "code": "${code}", "msg": "${message}"}}
+	enc, err := response.WithErrors(c, response.MustNew(cfg))
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, encoder := range []response.Encoder{enc, response.RawJSON(enc)} {
+		p, err := encoder.Encode(response.Result{Status: 500, Err: apierrors.ByCode("INVALID")})
+		if err != nil {
+			t.Fatal(err)
+		}
+		var body map[string]any
+		if err = json.Unmarshal(p.Body, &body); err != nil {
+			t.Fatal(err)
+		}
+		if p.Status != 200 || body["failed"] != false || body["code"] != float64(400002) || body["msg"] != "invalid" || body["data"] != nil {
+			t.Fatal(string(p.Body))
+		}
+	}
+	p, err := response.RawJSON(enc).Encode(response.Result{Status: 200, Data: map[string]bool{"value": true}})
+	if err != nil || strings.Contains(string(p.Body), "code") {
+		t.Fatal(string(p.Body), err)
+	}
+	for _, change := range []response.Config{
+		{CodeType: "string"},
+		{CodeType: "int32", SuccessCode: 0, ErrorCode: 9, Codes: map[string]any{"INVALID": 1}},
+		{CodeType: "int32", SuccessCode: 0, ErrorCode: 9, Messages: map[string]string{"INVALID": "different"}},
+	} {
+		if _, err := response.WithErrors(c, response.MustNew(change)); err == nil {
+			t.Fatal("accepted conflicting catalog mapping")
+		}
+	}
+	enc, err = response.WithErrors(c, response.EncoderFunc(func(r response.Result) (response.Payload, error) {
+		if !r.IsError() || r.Status != 200 || r.BusinessCode != int64(400002) {
+			t.Fatal(r)
+		}
+		return response.Text(202, "ACK"), nil
+	}))
+	if err != nil {
+		t.Fatal(err)
+	}
+	p, err = enc.Encode(response.Result{Err: apierrors.ByCode("INVALID")})
+	if err != nil || p.Status != 202 || string(p.Body) != "ACK" {
+		t.Fatal(p, err)
+	}
+}
+
+func TestCatalogWrapperPreservesScope(t *testing.T) {
+	catalog := apierrors.Catalog{DefaultStatus: 200, Definitions: map[string]apierrors.Definition{
+		"invalid": {Code: "invalid", Message: "project message"},
+	}}
+	inner := response.MustWithErrors(catalog, response.Default())
+	for _, encoder := range []response.Encoder{inner, response.RawJSON(inner)} {
+		for _, outer := range []apierrors.Catalog{{}, catalog} {
+			bound, err := response.WithErrors(outer, encoder)
+			if err != nil {
+				t.Fatal(err)
+			}
+			payload, err := bound.Encode(response.Result{Err: apierrors.ByCode("invalid")})
+			if err != nil || payload.Status != 200 || !strings.Contains(string(payload.Body), "project message") {
+				t.Fatal(payload, err)
+			}
+		}
+		other := catalog.Clone()
+		other.Definitions["invalid"] = apierrors.Definition{Status: 409, Code: "other", Message: "other"}
+		if _, err := response.WithErrors(other, encoder); err == nil {
+			t.Fatal("stacked conflicting policies")
+		}
+	}
+}
--- a/response/config.go
+++ b/response/config.go
@@ -162,7 +162,7 @@ func (f *Formatter) Config() Config {
 func (f *Formatter) Value(r Result) map[string]any {
 	c := f.config
 	code, message := any(r.Code), r.Message
-	isError := r.Err != nil || r.Status >= 400
+	isError := r.IsError()
 	if isError {
 		if c.ErrorCode != nil {
 			code = c.ErrorCode
@@ -184,6 +184,9 @@ func (f *Formatter) Value(r Result) map[string]any {
 	if mapped, ok := c.Messages[r.Code]; ok {
 		message = mapped
 	}
+	if isError && r.BusinessCode != nil {
+		code, message = r.BusinessCode, r.Message
+	}
 	body := c.Body
 	if isError && c.ErrorBody != nil {
 		body = c.ErrorBody
@@ -206,7 +209,12 @@ func (f *Formatter) Value(r Result) map[string]any {
 	}
 	return value
 }
-func (f *Formatter) Encode(r Result) (Payload, error) { return JSON(r.Status, f.Value(r)) }
+func (f *Formatter) Encode(r Result) (Payload, error) {
+	if err := f.validateError(r); err != nil {
+		return Payload{}, err
+	}
+	return JSON(r.Status, f.Value(r))
+}

 func normalizeCode(value any, kind string) (any, error) {
 	if kind == "string" {
--- a/response/encoder.go
+++ b/response/encoder.go
@@ -3,6 +3,8 @@ package response
 import (
 	"encoding/json"
 	"net/http"
+
+	apierrors "git.yuntuo.hk/k2safe/go-omni/errors"
 )

 // Result is the transport-independent input to an Encoder. Err is available for
@@ -12,8 +14,13 @@ type Result struct {
 	Code, Message, RequestID string
 	Data                     any
 	Err                      error
+	BusinessCode             any
+	Failed                   bool
 }

+// IsError preserves failure semantics independently of the HTTP status.
+func (r Result) IsError() bool { return r.Failed || r.Err != nil || r.Status >= 400 }
+
 // Payload is a complete response. Encoders must be safe for concurrent use.
 // Status and headers are intentionally part of the contract: callback protocols
 // may acknowledge an error using a different HTTP status or media type.
@@ -47,14 +54,30 @@ func Default() Encoder { return defaultEncoder }

 // RawJSON leaves successful data unwrapped. Errors use the selected error
 // policy; callback protocols with custom acknowledgments should use EncoderFunc.
+type rawJSONEncoder struct{ errors Encoder }
+
+func (e *rawJSONEncoder) ErrorRegistry() *apierrors.Registry {
+	if p, ok := e.errors.(ErrorRegistryProvider); ok {
+		return p.ErrorRegistry()
+	}
+	return nil
+}
+func (e *rawJSONEncoder) Encode(r Result) (Payload, error) {
+	if r.IsError() {
+		return e.errors.Encode(r)
+	}
+	return JSON(r.Status, r.Data)
+}
 func RawJSON(errors Encoder) Encoder {
 	if errors == nil {
 		errors = Default()
 	}
-	return EncoderFunc(func(r Result) (Payload, error) {
-		if r.Err != nil || r.Status >= 400 {
-			return errors.Encode(r)
+	return &rawJSONEncoder{errors: errors}
 }
-		return JSON(r.Status, r.Data)
-	})
+
+func (e *rawJSONEncoder) ValidateErrors(catalog apierrors.Catalog) error {
+	if checker, ok := e.errors.(interface{ ValidateErrors(apierrors.Catalog) error }); ok {
+		return checker.ValidateErrors(catalog)
+	}
+	return nil
 }
--- a/response/errors.go
+++ b/response/errors.go
@@ -0,0 +1,84 @@
+package response
+
+import (
+	"fmt"
+	"reflect"
+
+	apierrors "git.yuntuo.hk/k2safe/go-omni/errors"
+)
+
+// ErrorRegistryProvider attaches an immutable error catalog to a route policy.
+// Contexts and buffered clones use it before encoding or running middleware.
+type ErrorRegistryProvider interface{ ErrorRegistry() *apierrors.Registry }
+type errorEncoder struct {
+	next     Encoder
+	registry *apierrors.Registry
+}
+
+func (e *errorEncoder) ErrorRegistry() *apierrors.Registry { return e.registry }
+func (e *errorEncoder) Encode(r Result) (Payload, error) {
+	if r.Err != nil {
+		err := e.registry.Resolve(r.Err)
+		r.Status, r.Code, r.Message, r.BusinessCode, r.Failed = err.Status, err.Code, err.Message, err.BusinessCode, true
+	}
+	return e.next.Encode(r)
+}
+
+// WithErrors binds a catalog to an encoder without imposing a response shape.
+// Built-in templates are checked for incompatible code types and conflicting
+// legacy mappings. Custom encoders remain responsible for their wire contract.
+func WithErrors(catalog apierrors.Catalog, next Encoder) (Encoder, error) {
+	registry, err := apierrors.NewRegistry(catalog)
+	if err != nil {
+		return nil, err
+	}
+	if next == nil {
+		next = Default()
+	}
+	if provider, ok := next.(ErrorRegistryProvider); ok && provider.ErrorRegistry() != nil {
+		if len(catalog.Definitions) == 0 {
+			return next, nil
+		}
+		if reflect.DeepEqual(registry.Catalog(), provider.ErrorRegistry().Catalog()) {
+			return next, nil
+		}
+		return nil, fmt.Errorf("response: cannot stack different error catalogs; choose one policy per scope")
+	}
+	if checker, ok := next.(interface{ ValidateErrors(apierrors.Catalog) error }); ok {
+		if err := checker.ValidateErrors(registry.Catalog()); err != nil {
+			return nil, err
+		}
+	}
+	return &errorEncoder{next: next, registry: registry}, nil
+}
+func MustWithErrors(catalog apierrors.Catalog, next Encoder) Encoder {
+	e, err := WithErrors(catalog, next)
+	if err != nil {
+		panic(err)
+	}
+	return e
+}
+func (f *Formatter) ValidateErrors(catalog apierrors.Catalog) error {
+	for key, d := range catalog.Definitions {
+		if err := f.validateError(Result{Code: key, Message: d.Message, BusinessCode: d.Code, Failed: true}); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+func (f *Formatter) validateError(r Result) error {
+	if !r.IsError() || r.BusinessCode == nil {
+		return nil
+	}
+	normalized, err := normalizeCode(r.BusinessCode, f.config.CodeType)
+	if err != nil {
+		return fmt.Errorf("response: catalog %s code does not match codeType %s: %w", r.Code, f.config.CodeType, err)
+	}
+	if code, ok := f.config.Codes[r.Code]; ok && !reflect.DeepEqual(code, normalized) {
+		return fmt.Errorf("response: conflicting catalog/code mapping for %s", r.Code)
+	}
+	if msg, ok := f.config.Messages[r.Code]; ok && msg != r.Message {
+		return fmt.Errorf("response: conflicting catalog/message mapping for %s", r.Code)
+	}
+	return nil
+}
--- a/scripts/verifyConnector.py
+++ b/scripts/verifyConnector.py
@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+"""Verify Connector TLS/isolation and HTTP limits from a local or remote module.
+
+Uses a disposable local MySQL container (1 CPU, 768 MiB), private test credentials,
+and generated test certificates. Never connects to a project database.
+"""
+import argparse
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import secrets
+import shutil
+import subprocess
+import tempfile
+import time
+import uuid
+
+ROOT = Path(__file__).resolve().parents[1]
+MODULE = "git.yuntuo.hk/k2safe/go-omni"
+SOURCES = ("database/connector_test.go", "database/mysqlConnector_test.go",
+           "app/httpConfig_test.go", "config/http_test.go")
+
+
+def run(args, cwd, env, timeout=300):
+    result = subprocess.run([str(a) for a in args], cwd=cwd, env=env,
+                            text=True, capture_output=True, timeout=timeout)
+    output = re.sub(r"https://[^/@\s]+:[^/@\s]+@", "https://", result.stdout + result.stderr)
+    # Never print generated database credentials, including from a failed command.
+    for key in ("MYSQL_ROOT_PASSWORD", "MYSQL_PASSWORD", "GO_OMNI_CONNECTOR_PASSWORD"):
+        if env.get(key):
+            output = output.replace(env[key], "[redacted]")
+    if result.returncode:
+        raise RuntimeError(f"{args[0]} failed ({result.returncode}): {output}")
+    return output
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    source = parser.add_mutually_exclusive_group(required=True)
+    source.add_argument("--local", action="store_true")
+    source.add_argument("--version")
+    parser.add_argument("--report", type=Path, required=True)
+    parser.add_argument("--image", default="mysql:8.4")
+    args = parser.parse_args()
+    if args.version and not re.fullmatch(r"v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?", args.version):
+        parser.error("a fixed release version is required")
+    env = {k: v for k, v in os.environ.items() if not k.startswith("GO_OMNI_")}
+    env.update(GOWORK="off", GOFLAGS="")
+    for key in ("GOPRIVATE", "GONOSUMDB"):
+        env[key] = ",".join(filter(None, [env.get(key), "git.yuntuo.hk"]))
+    began = time.monotonic()
+    with tempfile.TemporaryDirectory(prefix="goOmniConnector-") as directory:
+        temp = Path(directory)
+        endpoint = env.get("DOCKER_HOST") or run(["docker", "context", "inspect", "--format", "{{.Endpoints.docker.Host}}"], temp, env).strip()
+        if not endpoint.startswith(("unix://", "npipe://")):
+            raise RuntimeError("requires local Docker; remote servers are not used")
+        certs = temp / "certs"
+        certs.mkdir(mode=0o755)
+        run(["openssl", "req", "-x509", "-newkey", "rsa:2048", "-nodes", "-keyout", certs / "ca.key", "-out", certs / "ca.pem", "-days", "2", "-subj", "/CN=GoOmni Test CA"], temp, env)
+        run(["openssl", "req", "-newkey", "rsa:2048", "-nodes", "-keyout", certs / "server.key", "-out", temp / "server.csr", "-subj", "/CN=localhost"], temp, env)
+        (temp / "extensions.cnf").write_text("subjectAltName=DNS:localhost,IP:127.0.0.1\nbasicConstraints=CA:FALSE\nextendedKeyUsage=serverAuth\n")
+        run(["openssl", "x509", "-req", "-in", temp / "server.csr", "-CA", certs / "ca.pem", "-CAkey", certs / "ca.key", "-CAcreateserial", "-out", certs / "server.pem", "-days", "2", "-extfile", temp / "extensions.cnf"], temp, env)
+        (certs / "ca.key").unlink()
+        for path in certs.iterdir():
+            path.chmod(0o644)  # Disposable fixtures, readable by the container's mysql uid.
+        project = temp / "consumer"
+        project.mkdir()
+        version = args.version or "v0.9.1-preview"
+        (project / "go.mod").write_text(f"module example.com/connectorAcceptance\n\ngo 1.22.0\n\nrequire {MODULE} {version}\n")
+        if args.local:
+            run(["go", "mod", "edit", f"-replace={MODULE}={ROOT}"], project, env)
+        else:
+            env["GOMODCACHE"] = str(temp / "modcache")
+        for name in SOURCES:
+            target = project / name
+            target.parent.mkdir(exist_ok=True)
+            shutil.copyfile(ROOT / name, target)
+        print("Resolving consumer dependency", flush=True)
+        run(["go", "mod", "tidy"], project, env)
+        module = json.loads(run(["go", "list", "-m", "-json", MODULE], project, env))
+        if not args.local:
+            assert module["Version"] == args.version and module.get("Sum") and not module.get("Replace"), module
+        env.update(MYSQL_ROOT_PASSWORD=secrets.token_hex(24), MYSQL_PASSWORD=secrets.token_hex(24))
+        name = "go-omni-connector-" + uuid.uuid4().hex[:12]
+        created = False
+        try:
+            print("Starting isolated MySQL TLS fixture (1 CPU, 768 MiB)", flush=True)
+            run(["docker", "create", "--name", name, "--label", "go-omni.test=connector", "--cpus", "1", "--memory", "768m", "--pids-limit", "128", "--publish", "127.0.0.1::3306", "--mount", f"type=bind,src={certs},dst=/certs,readonly", "--env", "MYSQL_ROOT_PASSWORD", "--env", "MYSQL_PASSWORD", "--env", "MYSQL_DATABASE=omni_test", "--env", "MYSQL_USER=omni_test", args.image, "--ssl-ca=/certs/ca.pem", "--ssl-cert=/certs/server.pem", "--ssl-key=/certs/server.key", "--require-secure-transport=ON", "--innodb-buffer-pool-size=64M", "--max-connections=20"], temp, env)
+            created = True
+            run(["docker", "start", name], temp, env)
+            ready = False
+            for _ in range(60):
+                try:
+                    check_env = dict(env, MYSQL_PWD=env["MYSQL_PASSWORD"])
+                    result = run(["docker", "exec", "--env", "MYSQL_PWD", name, "mysql", "--protocol=tcp", "-h127.0.0.1", "-uomni_test", "--batch", "--skip-column-names", "-e", "SELECT 1"], temp, check_env, timeout=5)
+                    if result.strip() == "1":
+                        ready = True
+                        break
+                except (RuntimeError, subprocess.TimeoutExpired):
+                    pass
+                time.sleep(1)
+            if not ready:
+                raise RuntimeError("isolated MySQL fixture did not become ready")
+            addr = run(["docker", "port", name, "3306/tcp"], temp, env).strip()
+            assert addr.startswith("127.0.0.1:"), addr
+            env.update(GO_OMNI_CONNECTOR_MYSQL_TEST="1", GO_OMNI_CONNECTOR_ADDR=addr,
+                       GO_OMNI_CONNECTOR_USER="omni_test", GO_OMNI_CONNECTOR_PASSWORD=env["MYSQL_PASSWORD"],
+                       GO_OMNI_CONNECTOR_DATABASE="omni_test", GO_OMNI_CONNECTOR_CA_FILE=str(certs / "ca.pem"))
+            print("Testing TLS trust, per-connector options, driver logging, lifecycle and HTTP limits", flush=True)
+            output = run(["go", "test", "-race", "-count=1", "-json", "-timeout=60s", "./..."], project, env)
+            events = [json.loads(line) for line in output.splitlines() if line.startswith("{")]
+            passed = [e["Test"] for e in events if e.get("Action") == "pass" and "Test" in e]
+            assert "TestMySQLConnectorTLSAndPoolIsolation" in passed
+            assert not any(e.get("Action") in ("fail", "skip") for e in events), output
+            image = run(["docker", "inspect", "--format", "{{.Image}}", name], temp, env).strip()
+        finally:
+            if created:
+                run(["docker", "rm", "--force", "--volumes", name], temp, env)
+        report = {"passed": True, "frameworkVersion": version, "localSource": args.local,
+                  "frameworkSum": module.get("Sum"), "freshModuleCache": not args.local,
+                  "noLocalReplace": not bool(module.get("Replace")), "mysqlImage": image,
+                  "mysqlLimits": {"cpus": 1, "memoryMiB": 768, "pids": 128},
+                  "durationSeconds": round(time.monotonic() - began, 2), "tests": passed,
+                  "sourceHashes": {name: hashlib.sha256((ROOT / name).read_bytes()).hexdigest() for name in (*SOURCES, "scripts/verifyConnector.py")}}
+        args.report.parent.mkdir(parents=True, exist_ok=True)
+        args.report.write_text(json.dumps(report, ensure_ascii=False, indent=2) + "\n")
+    print("PASS; isolated container, credentials, certificates and consumer removed", flush=True)
+
+
+if __name__ == "__main__":
+    main()
--- a/scripts/verifyErrorCatalogRelease.py
+++ b/scripts/verifyErrorCatalogRelease.py
@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""Install the released CLI in a fresh cache, then test its generated consumer.
+
+The fixture tests project-owned error catalogs, HTTP 200 business failures,
+route policies, generated constructors and regeneration protection. Only local temporary resources
+are used; the framework and CLI are fetched from the specified remote version.
+"""
+import argparse
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import subprocess
+import tempfile
+import time
+
+ROOT = Path(__file__).resolve().parents[1]
+MODULE = "git.yuntuo.hk/k2safe/go-omni"
+
+
+def run(args, cwd, env, timeout=300):
+    result = subprocess.run([str(arg) for arg in args], cwd=cwd, env=env,
+                            capture_output=True, text=True, timeout=timeout)
+    output = re.sub(r"https://[^/@\s]+:[^/@\s]+@", "https://", result.stdout + result.stderr)
+    if result.returncode:
+        raise RuntimeError(f"{args[0]} failed ({result.returncode}):\n{output}")
+    return output
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--version", required=True)
+    parser.add_argument("--report", type=Path, default=ROOT / "performance/errorCatalogRemote.json")
+    args = parser.parse_args()
+    if not re.fullmatch(r"v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?", args.version):
+        parser.error("a fixed release version is required")
+    env = {k: v for k, v in os.environ.items() if not k.startswith("GO_OMNI_")}
+    env.update(GOWORK="off", GOFLAGS="", GOPRIVATE="git.yuntuo.hk", GONOSUMDB="git.yuntuo.hk")
+    start = time.monotonic()
+    with tempfile.TemporaryDirectory(prefix="goOmniErrorCatalogRelease-") as directory:
+        temp = Path(directory)
+        (temp / "bin").mkdir()
+        env.update(GOBIN=str(temp / "bin"), GOMODCACHE=str(temp / "modcache"))
+        print(f"Installing CLI {args.version} in an empty module cache", flush=True)
+        run(["go", "install", MODULE + "/cmd/go-omni@" + args.version], temp, env)
+        cli = temp / "bin/go-omni"
+        run([cli, "api", "validate", "--api", ROOT / "examples/contracts/errors.api"], temp, env)
+        env.update(GO_OMNI_SCAFFOLD_INTEGRATION="1", GO_OMNI_RELEASE_CLI=str(cli), GO_OMNI_RELEASE_VERSION=args.version)
+        print("Testing remote error catalog generation, HTTP 200 failures and raw responses", flush=True)
+        output = run(["go", "test", "-race", "-count=1", "-json", "-timeout=180s",
+                      "./cmd/go-omni/apigen", "-run", "^TestErrorCatalogConsumer$"], ROOT, env)
+        events = [json.loads(line) for line in output.splitlines() if line.startswith("{")]
+        passed = [e["Test"] for e in events if e.get("Action") == "pass" and "Test" in e]
+        assert passed == ["TestErrorCatalogConsumer"], output
+        evidence = "".join(e.get("Output", "") for e in events)
+        checksum = re.search(r"checksum (h1:\S+); no local replace", evidence)
+        assert checksum, "consumer did not verify its remote dependency"
+        report = {
+            "passed": True, "frameworkVersion": args.version, "frameworkSum": checksum.group(1),
+            "freshModuleCache": True, "noLocalReplace": True,
+            "durationSeconds": round(time.monotonic() - start, 2),
+            "checks": ["remoteCLIInstall", "errorCatalogValidation", "generatedErrorConstructors",
+                       "http200BusinessFailure", "duplicatePublicCodeDistinctMessages", "perErrorHTTPStatus",
+                       "unknownErrorFallback", "causeNotExposed", "rawSuccessAndWrappedFailure",
+                       "earlyMiddlewareCatalog", "handwrittenFilesPreserved", "generatedConsumerRaceTests",
+                       "fixedRemoteModuleChecksum"],
+            "sourceHashes": {name: hashlib.sha256((ROOT / name).read_bytes()).hexdigest() for name in
+                             ("scripts/verifyErrorCatalogRelease.py", "cmd/go-omni/apigen/errorCatalog_test.go",
+                              "examples/contracts/errors.api",
+                              "cmd/go-omni/apigen/testdata/errorCatalog/consumer_test.go")},
+        }
+        args.report.write_text(json.dumps(report, ensure_ascii=False, indent=2) + "\n")
+    print(f"PASS remote error catalog contract {args.version}; temporary files removed", flush=True)
+
+
+if __name__ == "__main__":
+    main()
--- a/telemetry/errorCatalog_test.go
+++ b/telemetry/errorCatalog_test.go
@@ -0,0 +1,51 @@
+package telemetry_test
+
+import (
+	"context"
+	"net/http/httptest"
+	"testing"
+
+	omni "git.yuntuo.hk/k2safe/go-omni"
+	apierrors "git.yuntuo.hk/k2safe/go-omni/errors"
+	"git.yuntuo.hk/k2safe/go-omni/response"
+	"git.yuntuo.hk/k2safe/go-omni/telemetry"
+	"go.opentelemetry.io/otel/codes"
+	"go.opentelemetry.io/otel/sdk/trace/tracetest"
+)
+
+func TestCatalogFailureTraceWithHTTP200(t *testing.T) {
+	exporter := tracetest.NewInMemoryExporter()
+	runtime, err := telemetry.New(telemetry.Config{Service: "fixture", SampleRatio: 1, Exporter: exporter})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer runtime.Close()
+	app := omni.New(omni.WithErrors(apierrors.Catalog{DefaultStatus: 200, Definitions: map[string]apierrors.Definition{"INVALID": {Code: 123, Message: "invalid"}}}), omni.WithResponse(response.Config{CodeType: "int32", SuccessCode: 0, ErrorCode: 9999}))
+	defer app.Close()
+	app.Use(runtime.Middleware())
+	app.GET("/", func(c *omni.Context) error { c.WriteError(apierrors.ByCode("INVALID")); return nil })
+	w := httptest.NewRecorder()
+	app.ServeHTTP(w, httptest.NewRequest("GET", "/", nil))
+	if w.Code != 200 {
+		t.Fatal(w.Code)
+	}
+	if err := runtime.Flush(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	spans := exporter.GetSpans()
+	if len(spans) != 1 || spans[0].Status.Code != codes.Error {
+		t.Fatal(spans)
+	}
+	seenStatus, seenFailure := false, false
+	for _, attr := range spans[0].Attributes {
+		if attr.Key == "http.response.status_code" && attr.Value.AsInt64() == 200 {
+			seenStatus = true
+		}
+		if attr.Key == "omni.request.failed" && attr.Value.AsBool() {
+			seenFailure = true
+		}
+	}
+	if !seenStatus || !seenFailure {
+		t.Fatal(spans[0].Attributes)
+	}
+}
--- a/telemetry/telemetry.go
+++ b/telemetry/telemetry.go
@@ -4,7 +4,10 @@ package telemetry
 import (
 	"context"
 	"errors"
-	apierrors "git.yuntuo.hk/k2safe/go-omni/errors"
+	"math"
+	"net/http"
+	"time"
+
 	"git.yuntuo.hk/k2safe/go-omni/httpx"
 	"git.yuntuo.hk/k2safe/go-omni/logx"
 	"go.opentelemetry.io/otel/attribute"
@@ -15,9 +18,6 @@ import (
 	"go.opentelemetry.io/otel/sdk/resource"
 	sdktrace "go.opentelemetry.io/otel/sdk/trace"
 	"go.opentelemetry.io/otel/trace"
-	"math"
-	"net/http"
-	"time"
 )

 type Config struct {
@@ -99,15 +99,22 @@ func (r *Runtime) Middleware() httpx.Middleware {
 			defer func() {
 				status := c.Status()
 				if err != nil && !c.Responded() {
-					status = apierrors.From(err).Status
+					status = c.ResolveError(err).Status
 				}
 				p := recover()
 				if p != nil {
 					status = 500
 				}
 				attrs := []attribute.KeyValue{attribute.String("http.request.method", method), attribute.String("http.route", route), attribute.Int("http.response.status_code", status)}
+				failure := c.Failure()
+				if failure == nil && err != nil {
+					failure = c.ResolveError(err)
+				}
+				if failure != nil {
+					attrs = append(attrs, attribute.Bool("omni.request.failed", true), attribute.String("omni.error.key", failure.Code))
+				}
 				span.SetAttributes(attrs...)
-				if status >= 500 {
+				if status >= 500 || (failure != nil && status < 400) {
 					span.SetStatus(codes.Error, "request failed")
 				}
 				r.requests.Add(ctx, 1, metric.WithAttributes(attrs...))
--- a/transport/README.md
+++ b/transport/README.md
@@ -14,7 +14,7 @@ registerRoutes(application) // 与 omni.New() 复用同一份业务注册代码

 `transport/nethttp` 是当前内置的标准库路由实现。它提供一套可移植的路径、方法和错误回退规则；自研网络层可以直接实现同一个 `httpx.Router` 契约。

-`transport/http2` 是独立的 opt-in 实验 Runner，负责连接接入、TLS/ALPN、连接上限和全局请求背压，底层帧解析与 stream 流控暂由 `golang.org/x/net/http2` 提供。它不替换 `transport/native`，也不改变默认启动器；只有通过 `App.RunWith(ctx, http2.New(nil), address)` 显式启用才会运行。
+`transport/http2` 是独立的 opt-in 实验 Runner，负责连接接入、TLS/ALPN、连接上限和全局请求背压，底层帧解析与 stream 流控暂由 `golang.org/x/net/http2` 提供。它不替换 `transport/native`，也不改变默认启动器；通过 `WithTransport(TransportHTTP2)` 或 `App.RunWith(ctx, http2.New(nil), address)` 显式启用后运行。

 `transport/native` 是第一版自研 HTTP/1.1 服务端：它自己管理 TCP listener、连接、Keep-Alive、请求解析、响应写回和优雅关闭，再把请求交给现有 `http.Handler`。请求体支持 `Content-Length` 和 chunked，并统一受 `MaxBodyBytes` 限制；其他传输编码会被拒绝。它仍使用标准 `http.Request` / `http.ResponseWriter` 作为业务桥接，因此不会影响现有 Handler / Service。

@@ -119,3 +119,37 @@ python3 scripts/verifyTransports.py --version v0.6.0-preview
 第一条验证标准库适配器复用完整 Handler / Service / Repository。第二条在源码目录外创建无 replace 的消费模块，从远程版本导入同一套验收包；自研适配器也应使用同一个公共测试包。

 当前替换边界分成两层：`transport/nethttp` 提供标准库路由，`transport/native` 进一步接管 TCP 监听、连接管理和 HTTP/1.1 协议 I/O。`App.Run` / `App.RunContext` 仍使用标准库 `net/http.Server`，需要显式调用 `App.RunWith(ctx, native.New(nil), address)` 才会启用 native 预览实现。native 当前通过标准 `http.Request` / `http.ResponseWriter` 桥接到业务层，后续可在不改 Handler / Service 的前提下逐步替换解析器和响应写回。
+
+## HTTP 配置（v0.9.1-preview）
+
+`omni.WithHTTPConfig` / `config.Config.HTTP` 提供服务端配置入口，作用于 `Run`、`RunContext`、`ServeContext`；也作用于 `NewServer` 创建的标准库服务器。与客户端 `httpc` 的出站请求超时无关。
+
+```go
+application := omni.New(omni.WithHTTPConfig(omni.HTTPConfig{
+    ReadHeaderTimeout: 5 * time.Second,
+    ReadTimeout:       30 * time.Second,
+    WriteTimeout:      30 * time.Second,
+    IdleTimeout:       60 * time.Second,
+    MaxHeaderBytes:    1 << 20,
+    // ErrorLog: existingLogger, // *log.Logger，仅 nethttp；不通过 YAML/JSON 序列化
+}))
+// 注册业务路由后：
+return application.RunContext(ctx, ":8080")
+```
+
+| 字段 | nethttp | native | 独立实验 http2 |
+| --- | --- | --- | --- |
+| `ReadHeaderTimeout` | 标准 http.Server 语义 | 请求头读取时限 | 正值拒绝启动 |
+| `ReadTimeout` | 整个请求读取时限，包括头与 body | 头解析完成后读取 body 的时限 | 正值拒绝启动 |
+| `WriteTimeout` | 标准 http.Server 写截止时间 | 每次底层响应写入/Flush 的截止时间 | 正值拒绝启动 |
+| `IdleTimeout` | Keep-Alive 等待下一请求 | 复用连接等待下一请求（含头读取）；首个请求读头也取它与读头时限的较小值 | HTTP/2 空闲连接超时 |
+| `MaxHeaderBytes` | 标准 http.Server 头限制语义 | native 请求头字节限制 | 解压后请求头限制 |
+| `ErrorLog` | 标准库内部错误日志，不是访问日志 | 非 nil 拒绝启动 | 非 nil 拒绝启动 |
+
+参数为正时覆盖适配器默认值；**零值保留默认行为，不统一表示禁用**。nethttp 未配置时遵循 Go 标准服务器零值，包括读头/空闲时限回退到 ReadTimeout 的规则；native 仍默认读头 5s、读 body 30s、写 30s、空闲 60s、头 1 MiB。负数在启动前报错；HTTP/2 不支持的字段也会明确报错，不会悄悄忽略。默认 nethttp 的 TLS/HTTP2 行为仍由标准库管理，表格最后一列专指 `TransportHTTP2`。
+
+I/O 超时不会强制终止 CPU 计算或数据库调用；业务和下游调用继续通过 `context` 控制时限。native 需要流式输出时显式 `Flush()`，否则保持原有缓冲响应方式。不要依赖不同网络层在慢请求时返回完全相同的 HTTP 错误体；有些超时会直接断开连接。
+
+YAML/JSON 字段与上述字段对应的 lowerCamelCase 一致，位于 `config.Config` 的 `http` 对象。脚手架将框架配置包在 `server` 下，因此生成项目填写 `server.http`；直接用 `config.LoadFile` 加载框架配置时填写根级 `http`。环境变量为 `GO_OMNI_HTTP_READ_HEADER_TIMEOUT`、`GO_OMNI_HTTP_READ_TIMEOUT`、`GO_OMNI_HTTP_WRITE_TIMEOUT`、`GO_OMNI_HTTP_IDLE_TIMEOUT`（如 `30s`），以及 `GO_OMNI_HTTP_MAX_HEADER_BYTES`（整数）。`omni.New` 不自动加载环境；先 `config.LoadFile` / `config.ApplyEnv`，再 `WithConfig`。Go-only 的 `ErrorLog` 在文件加载之后设置。
+
+`NewServer` 始终返回普通 `*http.Server`，应用 HTTP 字段但不负责加载 TLS、监听、退出或资源清理；非法 HTTP 值会 panic。`RunContext` / `ServeContext` 的非法配置则作为 error 返回并关闭 App 资源。手动修改返回服务器的字段仍然有效。项目自己的 Runner 通过 `RunWith` 接入时，配置由该 Runner 持有，这组 HTTP 配置不会覆盖它。
Author	SHA1	Message	Date
k2safe	ebfd279f9a	feat: add project-owned error catalogs and HTTP 200 failure contracts	2026-09-24 12:40:05 +08:00
k2safe	bb2caefbb4	test: record remote connector and HTTP configuration acceptance	2026-09-24 02:19:33 +08:00
k2safe	20e84e5ff8	feat: support database connectors and HTTP server configuration	2026-09-24 02:18:18 +08:00
k2safe	6200864a64	test: record remote migration release acceptance	2026-09-24 01:49:49 +08:00