@pylonts/dsl 1.1.14 → 1.1.16

package/dist/typebox-driver.js

@@ -8,11 +8,21 @@ function renderDefault(v) {
         return renderString(v);
     return JSON.stringify(v);
 }
-function renderBasic(field, pattern, defaultValue, resolver, indent = 0) {
+/** BaseField-level description: description takes priority over label. */
+function fieldDescription(field) {
+    return field.description ?? field.label;
+}
+/** DtoField-level description: own description > referenced field description/label. */
+function dtoFieldDescription(f) {
+    return f.description ?? fieldDescription(f.field);
+}
+function renderBasic(field, pattern, defaultValue, resolver, indent = 0, description) {
     if (pattern !== undefined && field.type !== 'string') {
         throw new Error(`pattern is only supported on string fields, got ${field.type} (${field.name})`);
     }
     const def = defaultValue !== undefined ? `default: ${renderDefault(defaultValue)}` : undefined;
+    const desc = description !== undefined ? `description: ${renderString(description)}` : undefined;
+    const withOpts = (base, opts) => opts.length > 0 ? `${base}({ ${opts.join(', ')} })` : `${base}()`;
     switch (field.type) {
         case 'string': {
             const opts = [];
@@ -24,10 +34,18 @@ function renderBasic(field, pattern, defaultValue, resolver, indent = 0) {
                 opts.push(`pattern: ${renderString(pattern)}`);
             if (def !== undefined)
                 opts.push(def);
-            return opts.length > 0 ? `Type.String({ ${opts.join(', ')} })` : 'Type.String()';
+            if (desc !== undefined)
+                opts.push(desc);
+            return withOpts('Type.String', opts);
+        }
+        case 'text': {
+            const opts = [];
+            if (def !== undefined)
+                opts.push(def);
+            if (desc !== undefined)
+                opts.push(desc);
+            return withOpts('Type.String', opts);
         }
-        case 'text':
-            return def !== undefined ? `Type.String({ ${def} })` : 'Type.String()';
         case 'integer': {
             const opts = [];
             if (field.min !== undefined)
@@ -36,21 +54,41 @@ function renderBasic(field, pattern, defaultValue, resolver, indent = 0) {
                 opts.push(`maximum: ${field.max}`);
             if (def !== undefined)
                 opts.push(def);
-            return opts.length > 0 ? `Type.Integer({ ${opts.join(', ')} })` : 'Type.Integer()';
+            if (desc !== undefined)
+                opts.push(desc);
+            return withOpts('Type.Integer', opts);
         }
         case 'bigint':
         case 'decimal':
         case 'rate':
         case 'time':
         case 'date':
-        case 'datetime':
+        case 'datetime': {
             // Transmitted as string over HTTP: bigint/decimal/rate keep full
             // precision, date/time serialize to string.
-            return def !== undefined ? `Type.String({ ${def} })` : 'Type.String()';
-        case 'boolean':
-            return def !== undefined ? `Type.Boolean({ ${def} })` : 'Type.Boolean()';
-        case 'json':
-            return def !== undefined ? `Type.Unknown({ ${def} })` : 'Type.Unknown()';
+            const opts = [];
+            if (def !== undefined)
+                opts.push(def);
+            if (desc !== undefined)
+                opts.push(desc);
+            return withOpts('Type.String', opts);
+        }
+        case 'boolean': {
+            const opts = [];
+            if (def !== undefined)
+                opts.push(def);
+            if (desc !== undefined)
+                opts.push(desc);
+            return withOpts('Type.Boolean', opts);
+        }
+        case 'json': {
+            const opts = [];
+            if (def !== undefined)
+                opts.push(def);
+            if (desc !== undefined)
+                opts.push(desc);
+            return withOpts('Type.Unknown', opts);
+        }
         case 'enum': {
             const ref = resolver?.(field.enum.jsName);
             if (!ref)
@@ -60,18 +98,29 @@ function renderBasic(field, pattern, defaultValue, resolver, indent = 0) {
                 if (!member) {
                     throw new Error(`enum field ${field.name}: default ${renderDefault(defaultValue)} is not a member of ${field.enum.jsName}`);
                 }
-                return `Type.Enum(${ref.name}, { default: ${ref.name}.${member.symbol} })`;
+                const opts = [];
+                if (desc !== undefined)
+                    opts.push(desc);
+                return `Type.Enum(${ref.name}, { default: ${ref.name}.${member.symbol}${opts.length > 0 ? `, ${opts.join(', ')}` : ''} })`;
             }
+            if (desc !== undefined)
+                return `Type.Enum(${ref.name}, { ${desc} })`;
             return `Type.Enum(${ref.name})`;
         }
-        case 'aggregate':
+        case 'aggregate': {
             // Aggregate query outputs: count/sum(int) are numbers, everything else
             // arrives as a precision string.
-            return field.jsType === 'number' ? 'Type.Number()' : 'Type.String()';
+            const opts = [];
+            if (desc !== undefined)
+                opts.push(desc);
+            return field.jsType === 'number' ? withOpts('Type.Number', opts) : withOpts('Type.String', opts);
+        }
         case 'array':
-            return `Type.Array(${renderFieldValue(field.items, indent, resolver)})`;
+            return desc !== undefined
+                ? `Type.Array(${renderFieldValue(field.items, indent, resolver)}, { ${desc} })`
+                : `Type.Array(${renderFieldValue(field.items, indent, resolver)})`;
         case 'object':
-            return renderFieldObject(field.properties, indent + 1, resolver);
+            return renderFieldObject(field.properties, indent + 1, resolver, description);
         default:
             // Field union is exhaustive; this branch is unreachable at runtime.
             throw new Error(`unsupported field type: ${String(field.type)}`);
@@ -79,22 +128,28 @@ function renderBasic(field, pattern, defaultValue, resolver, indent = 0) {
 }
 /** Render a plain Field value (wire-format nested fields), wrapping optional. */
 function renderFieldValue(field, indent, resolver) {
-    const base = renderBasic(field, undefined, undefined, resolver, indent);
+    const base = renderBasic(field, undefined, undefined, resolver, indent, fieldDescription(field));
     return field.optional ? `Type.Optional(${base})` : base;
 }
 /** Render a plain Field object (wire-format nested object). */
-function renderFieldObject(properties, indent, resolver) {
+function renderFieldObject(properties, indent, resolver, description) {
     const pad = '  '.repeat(indent);
     const entries = Object.entries(properties).map(([name, f]) => `${pad}${name}: ${renderFieldValue(f, indent, resolver)}`);
-    return `Type.Object({\n${entries.join(',\n')}\n${'  '.repeat(indent - 1)}})`;
+    const obj = `Type.Object({\n${entries.join(',\n')}\n${'  '.repeat(indent - 1)}})`;
+    return description !== undefined
+        ? `Type.Object({\n${entries.join(',\n')}\n${'  '.repeat(indent - 1)}}, { description: ${renderString(description)} })`
+        : obj;
 }
-function renderObject(fields, indent, resolver) {
+function renderObject(fields, indent, resolver, description) {
     const pad = '  '.repeat(indent);
     const entries = Object.entries(fields).map(([name, f]) => {
         const rendered = isDtoField(f) ? renderField(f, indent, resolver) : renderFieldValue(f, indent, resolver);
         return `${pad}${name}: ${rendered}`;
     });
-    return `Type.Object({\n${entries.join(',\n')}\n${'  '.repeat(indent - 1)}})`;
+    const obj = `Type.Object({\n${entries.join(',\n')}\n${'  '.repeat(indent - 1)}})`;
+    return description !== undefined
+        ? `Type.Object({\n${entries.join(',\n')}\n${'  '.repeat(indent - 1)}}, { description: ${renderString(description)} })`
+        : obj;
 }
 function renderField(f, indent, resolver) {
     const base = renderValue(f, indent, resolver);
@@ -103,20 +158,31 @@ function renderField(f, indent, resolver) {
 function renderValue(f, indent, resolver) {
     if (f.field.type === 'array') {
         const items = f.field.items;
+        const desc = dtoFieldDescription(f);
         // Referenced DTO element — render by name (same-file export), not expanded.
-        if (isDtoMessage(items))
-            return `Type.Array(${items.name})`;
-        if (isDtoField(items))
-            return `Type.Array(${renderField(items, indent + 1, resolver)})`;
-        return `Type.Array(${renderFieldValue(items, indent, resolver)})`;
+        if (isDtoMessage(items)) {
+            return desc !== undefined
+                ? `Type.Array(${items.name}, { description: ${renderString(desc)} })`
+                : `Type.Array(${items.name})`;
+        }
+        if (isDtoField(items)) {
+            const rendered = `Type.Array(${renderField(items, indent + 1, resolver)})`;
+            return desc !== undefined
+                ? `Type.Array(${renderField(items, indent + 1, resolver)}, { description: ${renderString(desc)} })`
+                : rendered;
+        }
+        const rendered = `Type.Array(${renderFieldValue(items, indent, resolver)})`;
+        return desc !== undefined
+            ? `Type.Array(${renderFieldValue(items, indent, resolver)}, { description: ${renderString(desc)} })`
+            : rendered;
     }
     if (f.field.type === 'object') {
-        return renderObject(f.field.properties, indent + 1, resolver);
+        return renderObject(f.field.properties, indent + 1, resolver, dtoFieldDescription(f));
     }
     // DtoField only wraps a database Field; array/object defs live in the subclasses.
     // Only DTO-level defaults (setDefault) are emitted as TypeBox default
     // annotations; DB field defaults are not carried into the API contract.
-    return renderBasic(f.field, f.pattern, f.default, resolver, indent);
+    return renderBasic(f.field, f.pattern, f.default, resolver, indent, dtoFieldDescription(f));
 }
 function collectEnumImports(f, resolver, out) {
     if (f.field.type === 'array') {
@@ -163,7 +229,7 @@ export function collectDtoImports(schema, resolver, out) {
 }
 /** Render one DTO export (const + type) — no file header, for file-level generation. */
 export function renderDtoExport(schema, resolver) {
-    const object = renderObject(schema.fields, 1, resolver);
+    const object = renderObject(schema.fields, 1, resolver, schema.description);
     const bases = schema.bases ?? [];
     const body = bases.length > 0
         ? `Type.Intersect([${bases.map(renderBase).join(', ')}, ${object}])`

package/docs/third-service.md

@@ -2,121 +2,151 @@
 
 第三方服务适配器契约（如微信支付 tenpay、短信、文件存储）。`defineThirdService` 声明适配器类契约：构造函数配置 + 方法列表。
 
+> 完整对接流程（前置准备 → 契约化 → gen third → 填充 client → 沙箱验证）见 [methodology/third-party-integration.md](../../docs/methodology/third-party-integration.md)。
+
+与两个相近概念区分：
+
+- `ServiceSchema`（service_schema/）——后端业务服务；
+- `ThirdApiSchema`（project.config.ts `thirdApis`）——项目拓扑：第三方系统的目录归属，如 `wx/`、`ble/`。
+
+`ThirdServiceSchema.schema` 引用 `ThirdApiSchema` 实例（拓扑引用）。第三方方法实现在外部系统，仅声明契约、不建模内部流程。
+
+## 定义
+
 ```ts
-import { defineFieldRule, defineThirdService } from '@pylonts/dsl';
+import { buildInput, buildOutput, CodeException, defineThirdService, dtoField, intField, IOException, stringField } from '@pylonts/dsl';
 import { wx } from '../project.config';
 
-const balance = intField({ optional: false, label: '余额（分）' });
-
-// Rule = name + two named ends. One rule per semantic (defining fenYuan twice throws).
-const fenYuan = defineFieldRule({
-  name: 'fenYuan',
-  ends: { fen: {}, yuan: {} },
-});
+const totalFee = intField({ optional: false, label: '金额（分）' });
 
 export const wxPayService = defineThirdService({
   schema: wx,
   name: 'WxPayService',
   description: '微信支付服务（tenpay APIv2）',
-  methods: [
-    {
-      name: 'queryBalance',
-      args: { name: 'QueryBalanceArgs', fields: { openid: user.columns.openid } },
-      results: {
-        name: 'QueryBalanceResult',
-        fields: {
-          balance,
-        },
-        refs: [
-          { field: balance, ref: order.columns.amount, convert: { rule: fenYuan, end: fenYuan.ends.fen } },
-        ],
-      },
+  methods: {
+    getPayParams: {
+      args: buildInput('PayParams', {
+        out_trade_no: dtoField(stringField({ maxLength: 32, optional: false, label: '订单号' })),
+        total_fee: dtoField(totalFee),
+        // Same fact and same type as the entity column — shared instance.
+        openid: dtoField(user.columns.openid),
+      }),
+      results: buildOutput('PayParamsResult', {
+        appId: dtoField(stringField({ optional: false, label: 'appId' })),
+        paySign: dtoField(stringField({ optional: false, label: '签名' })),
+      }),
+      throws: [CodeException, IOException],
+      description: '获取支付参数',
     },
-  ],
+  },
 });
 ```
 
-## ThirdMethodSchema：方法的 args / results
-
-每个方法的 `args` / `results` 各是一个 `ThirdMethodSchema`——**字段集合容器**，与 `TableSchema.columns` 同构，但字段是线格式（wire-format）字段。结构上它是 `DtoMessage` 的字段集合对应物。
+- `methods` 是 **map**：key 即方法名（构建器写回 `method.name`），value 为 `ThirdServiceMethodDef`。
+- 每个方法的 `args` / `results` 各是一个 `DtoMessage`，用 `buildInput` / `buildOutput` 构建。`buildInput` 构建 `args`（输入消息），`buildOutput` 构建 `results`（输出消息）——与业务 DTO 同一 POJO 聚合，字段以 `dtoField(field)` 包装，map key 即线格式（wire-format）字段名，**原样保留协议拼写**（`out_trade_no`、`appId`，不做 camelCase）。
+- `throws`（**必填**）：每个方法必须声明 **`CodeException` + `IOException`** 两个异常——`CodeException`（第三方返回的业务错误码）与 `IOException`（网络/超时/不可恢复故障）。两个异常都来自 `@pylonts/core`，**不能自定义、不能替换**（`pylonts gen third` 会校验，缺失即报错拒绝生成）。原因：第三方集成有两类必然失败——业务层失败（第三方返回错误码，需转译给调用方）与传输层失败（网络/超时，需按故障重试或上报），client 骨架的异常翻译依赖这两个契约。
+- `description`（可选）：服务或方法说明。
 
-| 属性 | 说明 |
-|------|------|
-| `name` | 消息名（如 `QueryBalanceResult`），生成产物的类型名 |
-| `fields` | 线格式字段 map，key 即协议字段名（`out_trade_no`、`appId` 原样保留） |
-| `refs` | 同事实变体链接（见下） |
-| `schema` | 反向指针，指向所属 method（构建器写入） |
-
-`defineThirdMethod` 写回自有字段的 `name/schema`（与 `defineTable` 同一惯例）。
-
-## 字段与本地实体的关系
-
-两个通道，按"同一事实"的表达方式选择：
+字段与本地实体列/其他消息字段的关系，两个通道，按"同一事实"的表达方式选择：
 
 ### 同一概念且类型一致 → 共享实例
 
-直接复用本地实体列实例，类型/语义/默认值自动跟随实体，DTO 投影继承全部语义（与 `from(table)` 完全同构）：
+直接复用本地实体列实例，类型/语义/默认值自动跟随实体，DTO 投影继承全部语义：
 
 ```ts
 args: {
-  name: 'QueryBalanceArgs',
+  name: 'PayParams',
   fields: {
-    openid: user.columns.openid,   // 共享实例，schema 仍指向 t_user
+    openid: dtoField(user.columns.openid),   // user 是 TableSchema 实例，此处复用其 openid 列的 Field 对象
   },
 },
 ```
 
-前提是线格式字段名与实体列名一致（协议恰好也叫 `openid`）。名字不同时（协议叫 `userId` 而列叫 `user_id`），不共享实例，走 refs。
+线格式字段名（map key）与列名无需一致——key 是协议拼写，value 是任意 Field 实例，两者解耦。协议叫 `userId`、列叫 `user_id` 照样共享：
 
-### 同一概念但类型/格式不同（变体）→ 自有字段 + refs
+```ts
+fields: {
+  userId: dtoField(user.columns.user_id),   // key 按协议拼写，value 复用列实例
+},
+```
 
-声明自有线格式类型，再挂一条 `refs` 链接指向实体列。规则先定义一次：
+> `user` 是 `schema/user.table.ts` 中 `export const user = defineTable('user', { ... })` 导出的 **TableSchema 实例**（`user.columns` 是它的列 map，`user.columns.openid` 是该表 `openid` 列的 Field 实例）。共享实例即把**同一个 Field 对象**放入消息字段，类型/语义/默认值全部跟随表定义。
 
-```ts
-// 规则 = 名称 + 两端（具名 map）。同一语义全局只允许一条（重复定义抛错）。
-const fenYuan = defineFieldRule({
-  name: 'fenYuan',
-  ends: { fen: {}, yuan: {} },
-});
+### 同一概念但类型/格式不同 → 自有字段
 
+声明自有线格式类型：
+
+```ts
 const totalFee = intField({ optional: false, label: '金额（分）' });
 
 fields: {
-  total_fee: totalFee,
+  total_fee: dtoField(totalFee),
 },
-refs: [
-  {
-    field: totalFee,              // 本地定义（本消息的 wire 字段）
-    ref: order.columns.amount,    // 其他定义（表列或其他消息字段）
-    convert: { rule: fenYuan, end: fenYuan.ends.fen },
-  },
-],
 ```
 
-- `field`：本消息的 wire 字段实例（构建器校验必须是本消息字段）
-- `ref`：其他 schema 的字段实例（表列或其他消息字段，构建器校验不得是本消息字段）
-- `convert`（可选）：绑定一条规则到这对字段——仅当两字段需要转化时声明，纯关联不需要
-  - `rule`：`FieldRuleSchema`——规则 = 名称 + 两端（如 `fenYuan` 的 `fen`/`yuan` 端）。加密/脱敏/换算统一为规则名维度，`defineFieldRule` 按名称查重，同一语义只声明一次
-  - `end`：`field` 所站的端——引用 `rule.ends.fen` / `rule.ends.yuan`（具名引用，无索引魔法；构建器按实例校验），`ref` 自动占另一端——不再重复声明 from/to
-  - 生成器将来为这对字段产出两个方向的函数（field 端→ref 端 与 ref 端→field 端）
+wire 字段与本地字段之间的换算/映射（分↔元、加密、脱敏）由 convert 防腐层承载，`FieldRuleSchema` 换算规则为规划能力、尚未接入消息绑定。
 
 ## 嵌套字段
 
-线格式字段支持递归嵌套，用 `arrayField` / `objectField`（Field 体系，非表列）：
+线格式字段支持递归嵌套，用 `objectField` / `arrayField`（Field 体系，非表列）：
 
 ```ts
 fields: {
-  payer_info: objectField({
+  payer_info: dtoField(objectField({
     properties: {
       openid: stringField({ optional: false, maxLength: 64 }),
     },
-  }),
-  coupons: arrayField({ items: intField() }),
+  })),
+  coupons: dtoField(arrayField({ items: intField() })),
 },
 ```
 
-表列不支持这两个类型（`buildCreateTableSql` 直接报错）。
+表列不支持这两个类型（`buildCreateTableSql` 直接报错，定义期即拦截）。
+
+## 枚举与异常
+
+第三方消息字段可用 `enumField` 挂 `defineEnum` 枚举，两者与 `defineThirdService` 定义在同一源文件中（named export），供 `pylonts gen third` 生成枚举产物。
+
+异常不在此处定义——方法 `throws` 固定声明 `@pylonts/core` 的 `CodeException` + `IOException`（见上文「定义」一节），`pylonts gen third` 强校验。
+
+## 存储与生成
+
+- 声明：`third_schema/{thirdApi.name}/*.third-service.ts`——一文件一服务（named export），目录名 = project.config.ts 的 `thirdApis` 实例名。
+- 生成：`pylonts gen third`——对每个 thirdApi，扫描 `third_schema/{name}/`，按三步产出到 `third/{name}/`：
+  0. **throws 校验**（生成前置闸门）：每个方法必须声明 `CodeException` + `IOException`，缺失即报错列出违规方法，不写任何产物；
+  1. **枚举**：模块导出的 `defineEnum` 实例 → `third/{name}/enums/{JsName}.enum.ts`（复用 enum-driver 的 `renderEnum`，与表枚举同一渲染），一 jsName 一文件；
+  2. **DTO**：每方法 args/results 用 typebox-driver 渲染 TypeBox 消息 + Static 类型，**一源文件一生成文件**，输出 `third/{name}/{stem}.third-service.gen.ts`（覆盖写）；
+  3. **客户端骨架**：每服务渲染一个 class（构造配置接口 + 每方法 async 签名 + Not-implemented throw），输出 `third/{name}/{stem}.client.ts`——**已存在则跳过**（方法体是用户填充的），`--force` 覆盖。
+- DTO 的枚举字段 import 走**相对路径** `./enums/{JsName}.enum`（DTO 与 enums/ 同处 `third/{name}/` 下，`moduleResolution: bundler` 解析 `.enum.ts`），不依赖根 `enums/` 子包。
+- 生成物目录是子包：`third/` 目录带 `package.json`，`exports` 声明 `*.third-service.gen` 子路径，供 convert 产物 import。
+
+## 客户端骨架是生成的，方法体是手写的
 
-## DTO 转发
+`defineThirdService` 只描述**契约**（构造配置 + 方法列表）。`gen third` 生成的 `{name}.client.ts` 是一个**骨架**：导出 `{Service}Config` 接口（TODO 注释标注 transport 配置——baseUrl/凭据/密钥属外部实现，不在契约内）+ `{Service}` 类（constructor 空实现），每方法带完整签名（args/results 类型从同名 `.third-service.gen` import type）与 `throw new Error('Not implemented: ...')` stub（含 `// @gen:stub` 标记，与 gen-service 骨架同一套 marker 约定）。**签名/throws 注释由生成器保证与契约同步，方法体、构造配置、签名加密等外部交互由人工填充**——已存在文件默认跳过（避免覆盖人工实现），`--force` 才重写。
+
+## convert 防腐接线
+
+第三方消息（`args`/`results` 是 `DtoMessage`，天然满足 `ConvertSourceSchema`）可直接作为 convert 的**源或目标**，用于 wire 消息 ↔ 本地模型的防腐翻译。```ts
+// convert_schema/{api.name}/{app.name}/convert/wx-pay.convert.ts
+import { wxPayService } from '../../../third_schema/wx/wxpay.third-service';
+
+const getPayParams = wxPayService.methods.getPayParams;
+
+export const wxPayConvert = defineConvert({
+  name: 'WxPayConvert',
+  api,
+  app: admin,
+  methods: {
+    toPayParams: {
+      sources: [order],                 // 本地订单表 → wire 请求
+      target: getPayParams.args,
+    },
+    toLocalPayResult: {
+      sources: [getPayParams.results],  // wire 响应 → 本地 DTO
+      target: WxPayParamsResultDto,
+    },
+  },
+});
+```
 
-DTO 通过 `from(thirdMethod, fields)` 投影第三方消息字段，构建转发引用（透传不复制）。线格式字段名保持协议原样，不做 camelCase。见 [dto.md](./dto.md#从字段集合投影)。
+convert 文件绑定第三方服务身份时按 `{third-service}.convert.ts` 命名（上例 `wx-pay.convert.ts` 对应 `wxpay.third-service.ts` 的 `WxPayService`）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonts/dsl",
-  "version": "1.1.14",
+  "version": "1.1.16",
   "description": "Schema definition DSL with drivers: MySQL DDL, TS enum, TypeBox schema codegen.",
   "type": "module",
   "main": "dist/index.js",
@@ -41,7 +41,7 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@pylonts/core": "^1.1.2"
+    "@pylonts/core": "^1.1.3"
   },
   "devDependencies": {
     "typescript": "^7.0.2",

package/src/typebox-driver.ts

@@ -1,235 +1,304 @@
-import { DtoArrayField, DtoField, DtoMessage, DtoObjectField, ImportBase, ImportRef, isDtoField, isDtoMessage } from './dto.js';
-import { collectEnumRefs, EnumField, Field } from './dsl.js';
-
-// TypeBox driver: renders a DtoMessage into TypeBox TypeScript source.
-// Shape matches the codegen product consumed by fastify v5 TypeBoxTypeProvider:
-//
-//   export const RegisterUserInput = Type.Object({...});
-//   export type RegisterUserInput = Static<typeof RegisterUserInput>;
-//
-// ENUM fields reference a generated enum (see enum-driver) by its import
-// location — the resolver maps a jsName to its product import.
-// DTO bases (.include()) render as Type.Intersect([...bases, Type.Object({...})]).
-
-export type EnumResolver = (enumName: string) => ImportBase | undefined;
-
-function renderString(s: string): string {
-  return `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
-}
-
-function renderDefault(v: unknown): string {
-  if (typeof v === 'string') return renderString(v);
-  return JSON.stringify(v);
-}
-
-function renderBasic(
-  field: Field,
-  pattern: string | undefined,
-  defaultValue: unknown,
-  resolver: EnumResolver | undefined,
-  indent = 0,
-): string {
-  if (pattern !== undefined && field.type !== 'string') {
-    throw new Error(`pattern is only supported on string fields, got ${field.type} (${field.name})`);
-  }
-  const def = defaultValue !== undefined ? `default: ${renderDefault(defaultValue)}` : undefined;
-  switch (field.type) {
-    case 'string': {
-      const opts: string[] = [];
-      if (field.minLength !== undefined) opts.push(`minLength: ${field.minLength}`);
-      if (field.maxLength !== undefined) opts.push(`maxLength: ${field.maxLength}`);
-      if (pattern !== undefined) opts.push(`pattern: ${renderString(pattern)}`);
-      if (def !== undefined) opts.push(def);
-      return opts.length > 0 ? `Type.String({ ${opts.join(', ')} })` : 'Type.String()';
-    }
-    case 'text':
-      return def !== undefined ? `Type.String({ ${def} })` : 'Type.String()';
-    case 'integer': {
-      const opts: string[] = [];
-      if (field.min !== undefined) opts.push(`minimum: ${field.min}`);
-      if (field.max !== undefined) opts.push(`maximum: ${field.max}`);
-      if (def !== undefined) opts.push(def);
-      return opts.length > 0 ? `Type.Integer({ ${opts.join(', ')} })` : 'Type.Integer()';
-    }
-    case 'bigint':
-    case 'decimal':
-    case 'rate':
-    case 'time':
-    case 'date':
-    case 'datetime':
-      // Transmitted as string over HTTP: bigint/decimal/rate keep full
-      // precision, date/time serialize to string.
-      return def !== undefined ? `Type.String({ ${def} })` : 'Type.String()';
-    case 'boolean':
-      return def !== undefined ? `Type.Boolean({ ${def} })` : 'Type.Boolean()';
-    case 'json':
-      return def !== undefined ? `Type.Unknown({ ${def} })` : 'Type.Unknown()';
-    case 'enum': {
-      const ref = resolver?.(field.enum.jsName);
-      if (!ref) throw new Error(`enum field ${field.name}: no import ref for ${field.enum.jsName} — pass an EnumResolver`);
-      if (def !== undefined) {
-        const member = field.enum.values.find((v) => v.value === defaultValue);
-        if (!member) {
-          throw new Error(
-            `enum field ${field.name}: default ${renderDefault(defaultValue)} is not a member of ${field.enum.jsName}`,
-          );
-        }
-        return `Type.Enum(${ref.name}, { default: ${ref.name}.${member.symbol} })`;
-      }
-      return `Type.Enum(${ref.name})`;
-    }
-    case 'aggregate':
-      // Aggregate query outputs: count/sum(int) are numbers, everything else
-      // arrives as a precision string.
-      return field.jsType === 'number' ? 'Type.Number()' : 'Type.String()';
-    case 'array':
-      return `Type.Array(${renderFieldValue(field.items, indent, resolver)})`;
-    case 'object':
-      return renderFieldObject(field.properties, indent + 1, resolver);
-    default:
-      // Field union is exhaustive; this branch is unreachable at runtime.
-      throw new Error(`unsupported field type: ${String((field as Field).type)}`);
-  }
-}
-
-/** Render a plain Field value (wire-format nested fields), wrapping optional. */
-function renderFieldValue(field: Field, indent: number, resolver: EnumResolver | undefined): string {
-  const base = renderBasic(field, undefined, undefined, resolver, indent);
-  return field.optional ? `Type.Optional(${base})` : base;
-}
-
-/** Render a plain Field object (wire-format nested object). */
-function renderFieldObject(properties: Record<string, Field>, indent: number, resolver: EnumResolver | undefined): string {
-  const pad = '  '.repeat(indent);
-  const entries = Object.entries(properties).map(([name, f]) => `${pad}${name}: ${renderFieldValue(f, indent, resolver)}`);
-  return `Type.Object({\n${entries.join(',\n')}\n${'  '.repeat(indent - 1)}})`;
-}
-
-function renderObject(fields: Record<string, DtoField | Field>, indent: number, resolver: EnumResolver | undefined): string {
-  const pad = '  '.repeat(indent);
-  const entries = Object.entries(fields).map(([name, f]) => {
-    const rendered = isDtoField(f) ? renderField(f, indent, resolver) : renderFieldValue(f, indent, resolver);
-    return `${pad}${name}: ${rendered}`;
-  });
-  return `Type.Object({\n${entries.join(',\n')}\n${'  '.repeat(indent - 1)}})`;
-}
-
-function renderField(f: DtoField, indent: number, resolver: EnumResolver | undefined): string {
-  const base = renderValue(f, indent, resolver);
-  return f.isOptional() ? `Type.Optional(${base})` : base;
-}
-
-function renderValue(f: DtoField, indent: number, resolver: EnumResolver | undefined): string {
-  if (f.field.type === 'array') {
-    const items = f.field.items;
-    // Referenced DTO element — render by name (same-file export), not expanded.
-    if (isDtoMessage(items)) return `Type.Array(${items.name})`;
-    if (isDtoField(items)) return `Type.Array(${renderField(items, indent + 1, resolver)})`;
-    return `Type.Array(${renderFieldValue(items, indent, resolver)})`;
-  }
-  if (f.field.type === 'object') {
-    return renderObject(f.field.properties, indent + 1, resolver);
-  }
-  // DtoField only wraps a database Field; array/object defs live in the subclasses.
-  // Only DTO-level defaults (setDefault) are emitted as TypeBox default
-  // annotations; DB field defaults are not carried into the API contract.
-  return renderBasic(f.field as Field, f.pattern, f.default, resolver, indent);
-}
-
-function collectEnumImports(
-  f: DtoField,
-  resolver: EnumResolver | undefined,
-  out: Map<string, ImportBase>,
-): void {
-  if (f.field.type === 'array') {
-    const items = f.field.items;
-    if (isDtoMessage(items)) return;
-    if (isDtoField(items)) {
-      collectEnumImports(items, resolver, out);
-      return;
-    }
-    collectFieldEnumImports(items, resolver, out);
-    return;
-  }
-  if (f.field.type === 'object') {
-    for (const child of Object.values(f.field.properties)) {
-      if (isDtoField(child)) collectEnumImports(child, resolver, out);
-      else collectFieldEnumImports(child, resolver, out);
-    }
-    return;
-  }
-  if (f.field.type === 'enum') collectEnumRef(f.field, resolver, out);
-}
-
-/** Enum import collection over a plain Field (wire-format nested fields). */
-function collectFieldEnumImports(
-  field: Field,
-  resolver: EnumResolver | undefined,
-  out: Map<string, ImportBase>,
-): void {
-  for (const jsName of collectEnumRefs(field)) {
-    const ref = resolver?.(jsName);
-    if (!ref) throw new Error(`enum ${jsName}: no import ref — pass an EnumResolver`);
-    out.set(`${ref.from}#${ref.name}`, ref);
-  }
-}
-
-function collectEnumRef(field: EnumField, resolver: EnumResolver | undefined, out: Map<string, ImportBase>): void {
-  collectFieldEnumImports(field, resolver, out);
-}
-
-/** Collect all imports needed to render a DTO: include() bases + enum references. */
-export function collectDtoImports(
-  schema: DtoMessage,
-  resolver: EnumResolver | undefined,
-  out: Map<string, ImportBase>,
-): void {
-  for (const base of schema.bases ?? []) out.set(`${base.from}#${base.name}`, base);
-  for (const f of Object.values(schema.fields)) collectEnumImports(f, resolver, out);
-}
-
-/** Render one DTO export (const + type) — no file header, for file-level generation. */
-export function renderDtoExport(schema: DtoMessage, resolver: EnumResolver | undefined): string {
-  const object = renderObject(schema.fields, 1, resolver);
-  const bases = schema.bases ?? [];
-  const body =
-    bases.length > 0
-      ? `Type.Intersect([${bases.map(renderBase).join(', ')}, ${object}])`
-      : object;
-  return `export const ${schema.name} = ${body};`;
-}
-
-/** Render the Static type export for a DTO. */
-export function renderDtoTypeExport(name: string): string {
-  return `export type ${name} = Static<typeof ${name}>;`;
-}
-
-export function renderDtoMessage(
-  schema: DtoMessage,
-  options: { resolver?: EnumResolver; source?: string } = {},
-): string {
-  const { resolver, source } = options;
-  const imports = new Map<string, ImportBase>();
-  collectDtoImports(schema, resolver, imports);
-
-  const header = [
-    '// AUTO-GENERATED by typebox-driver — DO NOT EDIT',
-    ...(source !== undefined ? [`// Source: ${source}`] : []),
-    "import { Type, Static } from '@sinclair/typebox';",
-    ...[...imports.values()].map((r) => `import${r.type ? ' type' : ''} { ${r.name} } from '${r.from}';`),
-  ];
-
-  return [
-    ...header,
-    '',
-    renderDtoExport(schema, resolver),
-    renderDtoTypeExport(schema.name),
-    '',
-  ].join('\n');
-}
-
-function renderBase(base: ImportRef): string {
-  if (base.args === undefined || base.args.length === 0) return base.name;
-  const args = base.args.map((a) => (typeof a === 'string' ? a : a.name));
-  return `${base.name}(${args.join(', ')})`;
+import { DtoArrayField, DtoField, DtoMessage, DtoObjectField, ImportBase, ImportRef, isDtoField, isDtoMessage } from './dto.js';
+import { collectEnumRefs, EnumField, Field } from './dsl.js';
+
+// TypeBox driver: renders a DtoMessage into TypeBox TypeScript source.
+// Shape matches the codegen product consumed by fastify v5 TypeBoxTypeProvider:
+//
+//   export const RegisterUserInput = Type.Object({...});
+//   export type RegisterUserInput = Static<typeof RegisterUserInput>;
+//
+// ENUM fields reference a generated enum (see enum-driver) by its import
+// location — the resolver maps a jsName to its product import.
+// DTO bases (.include()) render as Type.Intersect([...bases, Type.Object({...})]).
+
+export type EnumResolver = (enumName: string) => ImportBase | undefined;
+
+function renderString(s: string): string {
+  return `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+
+function renderDefault(v: unknown): string {
+  if (typeof v === 'string') return renderString(v);
+  return JSON.stringify(v);
+}
+
+/** BaseField-level description: description takes priority over label. */
+function fieldDescription(field: { description?: string; label?: string }): string | undefined {
+  return field.description ?? field.label;
+}
+
+/** DtoField-level description: own description > referenced field description/label. */
+function dtoFieldDescription(f: DtoField): string | undefined {
+  return f.description ?? fieldDescription(f.field);
+}
+
+function renderBasic(
+  field: Field,
+  pattern: string | undefined,
+  defaultValue: unknown,
+  resolver: EnumResolver | undefined,
+  indent = 0,
+  description?: string,
+): string {
+  if (pattern !== undefined && field.type !== 'string') {
+    throw new Error(`pattern is only supported on string fields, got ${field.type} (${field.name})`);
+  }
+  const def = defaultValue !== undefined ? `default: ${renderDefault(defaultValue)}` : undefined;
+  const desc = description !== undefined ? `description: ${renderString(description)}` : undefined;
+  const withOpts = (base: string, opts: string[]): string =>
+    opts.length > 0 ? `${base}({ ${opts.join(', ')} })` : `${base}()`;
+  switch (field.type) {
+    case 'string': {
+      const opts: string[] = [];
+      if (field.minLength !== undefined) opts.push(`minLength: ${field.minLength}`);
+      if (field.maxLength !== undefined) opts.push(`maxLength: ${field.maxLength}`);
+      if (pattern !== undefined) opts.push(`pattern: ${renderString(pattern)}`);
+      if (def !== undefined) opts.push(def);
+      if (desc !== undefined) opts.push(desc);
+      return withOpts('Type.String', opts);
+    }
+    case 'text': {
+      const opts: string[] = [];
+      if (def !== undefined) opts.push(def);
+      if (desc !== undefined) opts.push(desc);
+      return withOpts('Type.String', opts);
+    }
+    case 'integer': {
+      const opts: string[] = [];
+      if (field.min !== undefined) opts.push(`minimum: ${field.min}`);
+      if (field.max !== undefined) opts.push(`maximum: ${field.max}`);
+      if (def !== undefined) opts.push(def);
+      if (desc !== undefined) opts.push(desc);
+      return withOpts('Type.Integer', opts);
+    }
+    case 'bigint':
+    case 'decimal':
+    case 'rate':
+    case 'time':
+    case 'date':
+    case 'datetime': {
+      // Transmitted as string over HTTP: bigint/decimal/rate keep full
+      // precision, date/time serialize to string.
+      const opts: string[] = [];
+      if (def !== undefined) opts.push(def);
+      if (desc !== undefined) opts.push(desc);
+      return withOpts('Type.String', opts);
+    }
+    case 'boolean': {
+      const opts: string[] = [];
+      if (def !== undefined) opts.push(def);
+      if (desc !== undefined) opts.push(desc);
+      return withOpts('Type.Boolean', opts);
+    }
+    case 'json': {
+      const opts: string[] = [];
+      if (def !== undefined) opts.push(def);
+      if (desc !== undefined) opts.push(desc);
+      return withOpts('Type.Unknown', opts);
+    }
+    case 'enum': {
+      const ref = resolver?.(field.enum.jsName);
+      if (!ref) throw new Error(`enum field ${field.name}: no import ref for ${field.enum.jsName} — pass an EnumResolver`);
+      if (def !== undefined) {
+        const member = field.enum.values.find((v) => v.value === defaultValue);
+        if (!member) {
+          throw new Error(
+            `enum field ${field.name}: default ${renderDefault(defaultValue)} is not a member of ${field.enum.jsName}`,
+          );
+        }
+        const opts: string[] = [];
+        if (desc !== undefined) opts.push(desc);
+        return `Type.Enum(${ref.name}, { default: ${ref.name}.${member.symbol}${opts.length > 0 ? `, ${opts.join(', ')}` : ''} })`;
+      }
+      if (desc !== undefined) return `Type.Enum(${ref.name}, { ${desc} })`;
+      return `Type.Enum(${ref.name})`;
+    }
+    case 'aggregate': {
+      // Aggregate query outputs: count/sum(int) are numbers, everything else
+      // arrives as a precision string.
+      const opts: string[] = [];
+      if (desc !== undefined) opts.push(desc);
+      return field.jsType === 'number' ? withOpts('Type.Number', opts) : withOpts('Type.String', opts);
+    }
+    case 'array':
+      return desc !== undefined
+        ? `Type.Array(${renderFieldValue(field.items, indent, resolver)}, { ${desc} })`
+        : `Type.Array(${renderFieldValue(field.items, indent, resolver)})`;
+    case 'object':
+      return renderFieldObject(field.properties, indent + 1, resolver, description);
+    default:
+      // Field union is exhaustive; this branch is unreachable at runtime.
+      throw new Error(`unsupported field type: ${String((field as Field).type)}`);
+  }
+}
+
+/** Render a plain Field value (wire-format nested fields), wrapping optional. */
+function renderFieldValue(field: Field, indent: number, resolver: EnumResolver | undefined): string {
+  const base = renderBasic(field, undefined, undefined, resolver, indent, fieldDescription(field));
+  return field.optional ? `Type.Optional(${base})` : base;
+}
+
+/** Render a plain Field object (wire-format nested object). */
+function renderFieldObject(
+  properties: Record<string, Field>,
+  indent: number,
+  resolver: EnumResolver | undefined,
+  description?: string,
+): string {
+  const pad = '  '.repeat(indent);
+  const entries = Object.entries(properties).map(([name, f]) => `${pad}${name}: ${renderFieldValue(f, indent, resolver)}`);
+  const obj = `Type.Object({\n${entries.join(',\n')}\n${'  '.repeat(indent - 1)}})`;
+  return description !== undefined
+    ? `Type.Object({\n${entries.join(',\n')}\n${'  '.repeat(indent - 1)}}, { description: ${renderString(description)} })`
+    : obj;
+}
+
+function renderObject(
+  fields: Record<string, DtoField | Field>,
+  indent: number,
+  resolver: EnumResolver | undefined,
+  description?: string,
+): string {
+  const pad = '  '.repeat(indent);
+  const entries = Object.entries(fields).map(([name, f]) => {
+    const rendered = isDtoField(f) ? renderField(f, indent, resolver) : renderFieldValue(f, indent, resolver);
+    return `${pad}${name}: ${rendered}`;
+  });
+  const obj = `Type.Object({\n${entries.join(',\n')}\n${'  '.repeat(indent - 1)}})`;
+  return description !== undefined
+    ? `Type.Object({\n${entries.join(',\n')}\n${'  '.repeat(indent - 1)}}, { description: ${renderString(description)} })`
+    : obj;
+}
+
+function renderField(f: DtoField, indent: number, resolver: EnumResolver | undefined): string {
+  const base = renderValue(f, indent, resolver);
+  return f.isOptional() ? `Type.Optional(${base})` : base;
+}
+
+function renderValue(f: DtoField, indent: number, resolver: EnumResolver | undefined): string {
+  if (f.field.type === 'array') {
+    const items = f.field.items;
+    const desc = dtoFieldDescription(f);
+    // Referenced DTO element — render by name (same-file export), not expanded.
+    if (isDtoMessage(items)) {
+      return desc !== undefined
+        ? `Type.Array(${items.name}, { description: ${renderString(desc)} })`
+        : `Type.Array(${items.name})`;
+    }
+    if (isDtoField(items)) {
+      const rendered = `Type.Array(${renderField(items, indent + 1, resolver)})`;
+      return desc !== undefined
+        ? `Type.Array(${renderField(items, indent + 1, resolver)}, { description: ${renderString(desc)} })`
+        : rendered;
+    }
+    const rendered = `Type.Array(${renderFieldValue(items, indent, resolver)})`;
+    return desc !== undefined
+      ? `Type.Array(${renderFieldValue(items, indent, resolver)}, { description: ${renderString(desc)} })`
+      : rendered;
+  }
+  if (f.field.type === 'object') {
+    return renderObject(f.field.properties, indent + 1, resolver, dtoFieldDescription(f));
+  }
+  // DtoField only wraps a database Field; array/object defs live in the subclasses.
+  // Only DTO-level defaults (setDefault) are emitted as TypeBox default
+  // annotations; DB field defaults are not carried into the API contract.
+  return renderBasic(f.field as Field, f.pattern, f.default, resolver, indent, dtoFieldDescription(f));
+}
+
+function collectEnumImports(
+  f: DtoField,
+  resolver: EnumResolver | undefined,
+  out: Map<string, ImportBase>,
+): void {
+  if (f.field.type === 'array') {
+    const items = f.field.items;
+    if (isDtoMessage(items)) return;
+    if (isDtoField(items)) {
+      collectEnumImports(items, resolver, out);
+      return;
+    }
+    collectFieldEnumImports(items, resolver, out);
+    return;
+  }
+  if (f.field.type === 'object') {
+    for (const child of Object.values(f.field.properties)) {
+      if (isDtoField(child)) collectEnumImports(child, resolver, out);
+      else collectFieldEnumImports(child, resolver, out);
+    }
+    return;
+  }
+  if (f.field.type === 'enum') collectEnumRef(f.field, resolver, out);
+}
+
+/** Enum import collection over a plain Field (wire-format nested fields). */
+function collectFieldEnumImports(
+  field: Field,
+  resolver: EnumResolver | undefined,
+  out: Map<string, ImportBase>,
+): void {
+  for (const jsName of collectEnumRefs(field)) {
+    const ref = resolver?.(jsName);
+    if (!ref) throw new Error(`enum ${jsName}: no import ref — pass an EnumResolver`);
+    out.set(`${ref.from}#${ref.name}`, ref);
+  }
+}
+
+function collectEnumRef(field: EnumField, resolver: EnumResolver | undefined, out: Map<string, ImportBase>): void {
+  collectFieldEnumImports(field, resolver, out);
+}
+
+/** Collect all imports needed to render a DTO: include() bases + enum references. */
+export function collectDtoImports(
+  schema: DtoMessage,
+  resolver: EnumResolver | undefined,
+  out: Map<string, ImportBase>,
+): void {
+  for (const base of schema.bases ?? []) out.set(`${base.from}#${base.name}`, base);
+  for (const f of Object.values(schema.fields)) collectEnumImports(f, resolver, out);
+}
+
+/** Render one DTO export (const + type) — no file header, for file-level generation. */
+export function renderDtoExport(schema: DtoMessage, resolver: EnumResolver | undefined): string {
+  const object = renderObject(schema.fields, 1, resolver, schema.description);
+  const bases = schema.bases ?? [];
+  const body =
+    bases.length > 0
+      ? `Type.Intersect([${bases.map(renderBase).join(', ')}, ${object}])`
+      : object;
+  return `export const ${schema.name} = ${body};`;
+}
+
+/** Render the Static type export for a DTO. */
+export function renderDtoTypeExport(name: string): string {
+  return `export type ${name} = Static<typeof ${name}>;`;
+}
+
+export function renderDtoMessage(
+  schema: DtoMessage,
+  options: { resolver?: EnumResolver; source?: string } = {},
+): string {
+  const { resolver, source } = options;
+  const imports = new Map<string, ImportBase>();
+  collectDtoImports(schema, resolver, imports);
+
+  const header = [
+    '// AUTO-GENERATED by typebox-driver — DO NOT EDIT',
+    ...(source !== undefined ? [`// Source: ${source}`] : []),
+    "import { Type, Static } from '@sinclair/typebox';",
+    ...[...imports.values()].map((r) => `import${r.type ? ' type' : ''} { ${r.name} } from '${r.from}';`),
+  ];
+
+  return [
+    ...header,
+    '',
+    renderDtoExport(schema, resolver),
+    renderDtoTypeExport(schema.name),
+    '',
+  ].join('\n');
+}
+
+function renderBase(base: ImportRef): string {
+  if (base.args === undefined || base.args.length === 0) return base.name;
+  const args = base.args.map((a) => (typeof a === 'string' ? a : a.name));
+  return `${base.name}(${args.join(', ')})`;
 }