@pylonts/dsl 1.1.18 → 1.1.20

package/README.md

@@ -22,6 +22,7 @@ project（地图：应用与 API 拓扑）
 - [table.md](./docs/table.md) — 定义表（详细设计）
 - [dto.md](./docs/dto.md) — 定义 DTO
 - [curd.md](./docs/curd.md) — 管理端 CRUD 页面标准（CurdSchema）
+- [utils.md](./docs/utils.md) — 工具模块与领域规则（UtilsSchema：防御 guard / 判断 / 计算）
 - [aggregate.md](./docs/aggregate.md) — 聚合/仓储 DSL 扩展规划（声明层已落地：DomainAggregate/RepositorySchema + 存储校验，生成器待选型）
 - [domain-event.md](./docs/domain-event.md) — 领域事件 DSL 扩展规划（声明层已落地：DomainEventSchema + event_schema 存储校验，发布/订阅待实现）
 - [ddd-principles.md](./docs/ddd-principles.md) — DDD 落地原则（已决策）

package/dist/dto.d.ts

@@ -103,6 +103,15 @@ export declare function dtoField(field: Field | DtoArrayFieldDef | DtoObjectFiel
 export declare function isDtoMessage(v: unknown): v is DtoMessage;
 /** Structural check — a DtoField wraps a Field in a .field property and has no .type of its own. */
 export declare function isDtoField(v: unknown): v is DtoField;
+/** Resolve a ref chain to its terminal DtoField (the one without .ref).
+ *  Cycles are a DSL definition error — fail loudly at render time. */
+export declare function resolveDtoRefChain(f: DtoField): DtoField;
+/** TS type of a DtoField in generated code — unwraps the wrapped field
+ *  (enum → its JS name, date/datetime → string, containers → jsType). */
+export declare function dtoFieldJsType(df: DtoField): string;
+/** Enum JS names referenced by a DtoField, recursing into inline array/object
+ *  wrappers; DtoMessage item references stop the walk. First-occurrence order. */
+export declare function dtoCollectEnumRefs(df: DtoField, out?: string[]): string[];
 export declare function dtoArrayField(def: {
     items: DtoField | DtoMessage;
 } & Omit<BaseField, 'name'>): DtoArrayField;

package/dist/dto.js

@@ -119,6 +119,48 @@ export function isDtoField(v) {
         return false;
     return 'field' in v && !('type' in v);
 }
+/** Resolve a ref chain to its terminal DtoField (the one without .ref).
+ *  Cycles are a DSL definition error — fail loudly at render time. */
+export function resolveDtoRefChain(f) {
+    const seen = new Set();
+    let cur = f;
+    while (cur.ref !== undefined) {
+        if (seen.has(cur.ref)) {
+            throw new Error(`dto field ${cur.name}: circular ref chain (field references itself)`);
+        }
+        seen.add(cur.ref);
+        cur = cur.ref;
+    }
+    return cur;
+}
+/** TS type of a DtoField in generated code — unwraps the wrapped field
+ *  (enum → its JS name, date/datetime → string, containers → jsType). */
+export function dtoFieldJsType(df) {
+    const f = df.field;
+    if (f.type === 'enum')
+        return f.enum.jsName;
+    if (f.type === 'date' || f.type === 'datetime')
+        return 'string';
+    return f.jsType;
+}
+/** Enum JS names referenced by a DtoField, recursing into inline array/object
+ *  wrappers; DtoMessage item references stop the walk. First-occurrence order. */
+export function dtoCollectEnumRefs(df, out = []) {
+    const f = df.field;
+    if (f.type === 'enum') {
+        out.push(f.enum.jsName);
+    }
+    else if (f.type === 'array') {
+        const items = f.items;
+        if (isDtoField(items))
+            dtoCollectEnumRefs(items, out);
+    }
+    else if (f.type === 'object') {
+        for (const child of Object.values(f.properties))
+            dtoCollectEnumRefs(child, out);
+    }
+    return out;
+}
 export function dtoArrayField(def) {
     // Items stay as-is: an inline DtoField is rendered inline, a DtoMessage is
     // referenced by name (the driver renders Type.Array(<DtoName>)).

package/dist/typebox-driver.js

@@ -1,4 +1,4 @@
-import { isDtoField, isDtoMessage } from './dto.js';
+import { isDtoField, isDtoMessage, resolveDtoRefChain } from './dto.js';
 import { collectEnumRefs } from './dsl.js';
 function renderString(s) {
     return `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
@@ -16,20 +16,6 @@ function fieldDescription(field) {
 function dtoFieldDescription(f) {
     return f.description ?? fieldDescription(f.field);
 }
-/** Resolve a ref chain to its terminal field (the one without .ref).
- *  Cycles are a DSL definition error — fail loudly at render time. */
-function resolveRefChain(f) {
-    const seen = new Set();
-    let cur = f;
-    while (cur.ref !== undefined) {
-        if (seen.has(cur.ref)) {
-            throw new Error(`dto field ${cur.name}: circular ref chain (field references itself)`);
-        }
-        seen.add(cur.ref);
-        cur = cur.ref;
-    }
-    return cur;
-}
 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})`);
@@ -176,7 +162,7 @@ function renderField(f, indent, resolver) {
  *  chain, inherit the terminal field's type/constraints, keep the referencing
  *  field's own overrides (pattern / default / description). */
 function renderRefBase(f, indent, resolver) {
-    const target = resolveRefChain(f);
+    const target = resolveDtoRefChain(f);
     const targetField = target.field;
     const pattern = f.pattern ?? target.pattern;
     const defaultValue = f.default ?? target.default;
@@ -187,7 +173,7 @@ function renderRefBase(f, indent, resolver) {
  *  override first, then the chain's DtoField-level optional, then the bare
  *  column optionality. */
 function renderRefField(f, indent, resolver) {
-    const target = resolveRefChain(f);
+    const target = resolveDtoRefChain(f);
     const optional = f.optional ?? target.optional ?? target.field.optional ?? false;
     const base = renderRefBase(f, indent, resolver);
     return optional ? `Type.Optional(${base})` : base;
@@ -225,7 +211,7 @@ function renderValue(f, indent, resolver) {
 }
 function collectEnumImports(f, resolver, out) {
     if (f.ref !== undefined) {
-        collectEnumImports(resolveRefChain(f), resolver, out);
+        collectEnumImports(resolveDtoRefChain(f), resolver, out);
         return;
     }
     if (f.field.type === 'array') {
@@ -270,14 +256,25 @@ export function collectDtoImports(schema, resolver, out) {
     for (const f of Object.values(schema.fields))
         collectEnumImports(f, resolver, out);
 }
+/** JSON Schema readOnly annotation on a rendered scalar schema: the token
+ *  owns the field, the client must not send it (the __inject adapter
+ *  overwrites any client-supplied value anyway). Injection fields are always
+ *  scalar columns (tables forbid nested columns), so the only object literal
+ *  in a rendered scalar base is its options block. */
+function withReadOnly(base) {
+    const idx = base.lastIndexOf('{');
+    if (idx === -1)
+        return base.replace(/\(\s*\)$/, '({ readOnly: true })');
+    return `${base.slice(0, idx + 1)} readOnly: true,${base.slice(idx + 1)}`;
+}
 /** Render the server-injection base: token-injected fields as Optional
- *  properties of a TypeBox object, plus a non-enumerable __inject adapter
- *  (same mechanism as hand-written bases, see pylon __inject docs) that fills
- *  each field from the token at runtime. */
+ *  readOnly properties of a TypeBox object, plus a non-enumerable __inject
+ *  adapter (same mechanism as hand-written bases, see pylon __inject docs)
+ *  that fills each field from the token at runtime. */
 function renderInjectBase(fields, resolver) {
     const entries = Object.entries(fields).map(([name, f]) => {
         const base = f.ref !== undefined ? renderRefBase(f, 1, resolver) : renderValue(f, 1, resolver);
-        return `  ${name}: Type.Optional(${base})`;
+        return `  ${name}: Type.Optional(${withReadOnly(base)})`;
     });
     const inner = `Type.Object({\n${entries.join(',\n')}\n})`;
     const assigns = Object.keys(fields)

package/dist/utils.d.ts

@@ -1,14 +1,17 @@
 import type { CollectionSchemaBase, Field, SchemaBase } from './dsl.js';
+import type { DtoField } from './dto.js';
 import type { FrontAppSchema, ProjectApiSchema } from './project.js';
 /** A utility method with a full signature. */
 export interface UtilsMethodSchema extends SchemaBase {
     type: 'utilsMethod';
     /** The utility module this method belongs to. */
     schema: UtilsSchema;
-    /** Input fields. */
-    args: Record<string, Field>;
-    /** Output field. */
-    result: Field;
+    /** Input fields — DtoField wrappers (dtoField(...)); may wrap table columns. */
+    args: Record<string, DtoField>;
+    /** Output field — a plain inline Field (boolean for checks, decimal for
+     *  computed amounts, ...). The method output is a fresh value, never a
+     *  shared table column. Omit for void methods (pure actions). */
+    result?: Field;
 }
 /** Method input for defineUtils: type/schema/name are set by the builder. */
 export type UtilsMethodDef = Omit<UtilsMethodSchema, 'type' | 'schema' | 'name'>;

package/dist/utils.js

@@ -20,13 +20,27 @@ export function defineUtils(options) {
             args: method.args,
             result: method.result,
         };
+        // Args: write back on the DtoField wrapper only (safe: wrappers are
+        // created per method via dtoField(), never shared). Inline fields get
+        // their underlying Field written back too; fields wrapping table columns
+        // (domain rules) keep the shared column instance untouched — its
+        // name/schema already point to the table.
         for (const argKey of Object.keys(methodSchema.args)) {
-            const field = methodSchema.args[argKey];
-            field.name = argKey;
-            field.schema = methodSchema;
+            const df = methodSchema.args[argKey];
+            df.name = argKey;
+            df.schema = schema;
+            if (df.field.schema === undefined) {
+                df.field.name = argKey;
+                df.field.schema = schema;
+            }
+        }
+        // Result (optional): a plain inline Field — write name/schema back only
+        // when it is unowned (schema === undefined); shared instances (table
+        // columns, fields already claimed by another container) stay untouched.
+        if (methodSchema.result !== undefined && methodSchema.result.schema === undefined) {
+            methodSchema.result.name = key;
+            methodSchema.result.schema = schema;
         }
-        methodSchema.result.name = key;
-        methodSchema.result.schema = methodSchema;
         schema.methods[key] = methodSchema;
     }
     return schema;

package/docs/dto.md

@@ -48,6 +48,39 @@ dtoField(stringField({ maxLength: 32 })).setOperator('like')
 dtoField(intField()).setDefault(0)        // TypeBox default 注解
 ```
 
+## 字段引用规格（Reference Spec）
+
+`DtoField` 通过 `setRef(other)` 或共享字段实例引用其他字段，表达"本字段来源于 X"。**引用不是任意的**——只有业务契约 DTO（controller/service 消费的 `dto_schema/{app}` 或 `dto_schema/common` DTO）的字段可以作为引用方，且只能引用三类被引用方：
+
+| # | 引用 | 语法 | 语义 |
+|---|---|---|---|
+| 1 | **field 引用** | `dtoField(table.columns.x)`（共享实例）或 `setRef` 指向包装表列的 DtoField | 与数据库字段同义（来源：库） |
+| 2 | **token 引用** | `fromToken(token, [...])` 或 `setRef(token 字段)` | 字段来源于登录身份（服务端注入） |
+| 3 | **third 引用** | `setRef(third 消息字段)` | 字段来源于第三方消息（参数或结果） |
+
+**方向约束**：
+
+- 引用方：业务契约 DTO 的字段；
+- 被引用方：token 字段 / third 消息字段 / 表列 field——**业务 DTO 之间不能互相引用**（convert 的 sources/target 各自独立，映射由搬运生成推导，不靠 DTO 互 ref）；
+- third 字段、token 字段不可反向引用业务 DTO；
+- ref 链无环（渲染期强校验，循环引用报错）。
+
+**对 convert 自动搬运的意义**：同源判定 = ref 链终端 / 共享 field 实例，且只有规格内合法引用构成可推导搬运——业务 DTO ← third（防腐翻译，`setRef(thirdField)` = "本字段从 third 参数/结果来"）、业务 DTO ← entity（共享表列实例）都是可自动生成搬运的映射；越界引用是声明错误。
+
+> entity 列是裸 `Field` 实例：DTO 字段 `dtoField(order.columns.x)` 与 entity 列共享同一实例即构成 field 引用。
+
+### token 引用的注入与 readOnly
+
+`fromToken(token, fields)` 是 token 引用的标准入口：每个投影字段 `setRef(token 字段)`（复用类型/约束）+ 标记 `injectFrom`（服务端注入）。typebox 生成物中注入字段渲染为 **`Type.Optional(...)` + `readOnly: true` 注解**（JSON Schema annotation）——服务器字段，客户端不得上送：
+
+```ts
+id: Type.Optional(Type.Integer({ readOnly: true })),
+```
+
+同时生成非枚举 `__inject` 适配器，fastify RPC 层在进 controller 前执行 `body.k = token.k` 从登录身份填充——**客户端即使上送也会被覆盖**（上送无效）。三层闭环：声明 readOnly（不可上送语义）+ Optional（可不传）+ 运行时覆盖（上送无效）。
+
+注意：**只有 `fromToken()` 自动设置 `injectFrom`**；手写 `setRef(token 字段)` 只表达引用关系，不触发注入渲染（如需注入须显式标记或改走 fromToken）。
+
 ## 默认值
 
 - `setDefault(v)` 设 DTO 层默认值，渲染为 TypeBox `default:` 注解（`Type.String({ default: 'PENDING' })`、`Type.Enum(OrderStatus, { default: OrderStatus.PENDING })`）。

package/docs/utils.md

@@ -0,0 +1,104 @@
+# 工具模块与领域规则（UtilsSchema）
+
+UtilsSchema 是**业务无关工具模块**（base utility modules）的声明：带完整签名的纯函数集合，在 service 层被调用（含 flow 的 `invoke`）。方法签名（args/result）由 schema 声明，方法体由用户实现。
+
+**当 utils 名称与某张表同名时，它就是该实体的领域规则集**（DDD 领域服务落点）——命名即归属、位置即角色：`utils_schema/.../order.utils.ts` = order 表的领域规则（`OrderUtils`）。
+
+## 定义
+
+```ts
+import { defineUtils, booleanField, decimalField, dtoField, intField, stringField } from '@pylonts/dsl';
+import { api, miniuser } from '../../../../project.config';
+import { order } from '../../../../schema/order.table';
+
+const orderUtils = defineUtils({
+  name: 'OrderUtils',
+  api,
+  app: miniuser,
+  description: '订单领域规则',
+  methods: {
+    // 防御 guard：条件抛错，通过无返回值（void），失败即 throw
+    assertCancelable: {
+      args: { status: dtoField(order.columns.status) },
+    },
+    // 判断：返回 boolean 判定值，供 flow IF 条件位使用
+    canCancel: {
+      args: { status: dtoField(order.columns.status) },
+      result: booleanField(),
+    },
+    // 计算：返回派生标量
+    calcTotal: {
+      args: { unitPrice: dtoField(decimalField({ precision: 10, scale: 2 })), qty: dtoField(intField({ min: 1 })) },
+      result: decimalField({ precision: 10, scale: 2 }),
+    },
+  },
+});
+
+// 必须 default-export 方法引用对象（XXUtils 约定），loader 从 refs 反推 schema
+export default {
+  assertCancelable: orderUtils.methods.assertCancelable,
+  canCancel: orderUtils.methods.canCancel,
+  calcTotal: orderUtils.methods.calcTotal,
+};
+```
+
+### 方法形态
+
+- **args**：`Record<string, DtoField>`——用 `dtoField(...)` 包装。可包装**表列**（`dtoField(order.columns.status)`，领域规则引用表字段的标准方式）或内联字段（`dtoField(stringField(...))`）。包装层反写不污染共享表列实例（与 `buildMessage` 同规则：仅内联字段写回底层）。
+- **result**：`Field | undefined`——输出是全新值（boolean 判断、decimal 计算、string 派生文案），**不是共享表列**；省略 = void 方法（防御 guard 通过时无返回值）。
+- **失败语义**：规则失败直接 `throw`（配合 flow 的 `BusinessException`/`CodeException` 通道），**不返回错误码结构**。
+
+## 文件与存储约定
+
+- 一文件一 utils；文件必须 **default-export 方法引用对象**（`export default { m: xxUtils.methods.m }`），schema 变量模块私有不导出。
+- 文件名 = 名字去 `Utils`/`Util` 后缀转 kebab：`OrderUtils → order.utils.ts`、`AmtUtils → amt.utils.ts`。
+- 存储位置按绑定（机器校验，`lint utils`）：
+
+| 绑定 | 目录（utils_schema/） | 生成物 |
+|---|---|---|
+| api + app | `{api}/{app}/utils/` | `{api}/src/modules/{app}/utils/{Name}.ts` |
+| 仅 api | `{api}/common/utils/` | `{api}/src/modules/common/utils/`（后端公共） |
+| 仅 app | `{app}/utils/` | `{app.dir}/src/utils/`（前端） |
+| 无绑定 | `common/utils/` 或 `shared/utils/` | `{root}/shared/utils/`（前后端共享） |
+
+## 领域规则三分类
+
+从纯函数视角，方法的出口只有两种：**返回值**或**抛异常**。因此领域规则方法恰好三类：
+
+| 分类 | 命名 | 本质 | result | 失败语义 | 典型示例 |
+|---|---|---|---|---|---|
+| **1 防御 guard** | `assertXX` / `validateXX` / `ensureXX` | 条件抛错（前置校验） | `void` | **失败必抛错**，通过无返回值 | `assertCancelable`——已完成/已取消订单 throw |
+| **2 判断** | `canXX` / `isXX` / `hasXX` | 返回判定值（谓词） | `boolean` / 枚举 | 返回 false/枚举值，不抛 | `canCancel`、`isExpired`——供 flow `IF(...)` 条件位 |
+| **3 计算** | `calcXX` / `formatXX` / 动词 | 派生值计算 | 标量（金额/数量/文案） | 一般不抛（入参合法前提） | `calcTotal`——金额计算 |
+
+### 为什么这就是全集
+
+- **判断 = 计算的特例**：boolean/枚举也是值，只是返回值窄化——单独分类是为 flow 谓词位（`IF(canCancel(slots.status))`）的语义清晰，不是本质区别。
+- **防御 guard = 判断 + 抛错**：guard 内部必然先判断再 throw，是"判断"失败分支的显式化；通过时没有调用方需要的值，所以返回 `void`。
+- **void 方法只能是防御 guard**：纯函数无副作用，不返回也不抛 = 什么都没做——void 方法若默认通过、特殊状态才抛，就是 guard 的语义。
+
+### 命名与返回的一致性（可机器校验）
+
+- `assert/validate/ensure` 前缀 → **必须 void**（guard：通过无值、失败抛错）；
+- `can/is/has` 前缀 → **必须 boolean 或枚举**（判断谓词）；
+- 计算类 → 标量 result。
+- 命名与 result 形态不匹配（如 `canXX` 返回 void）即声明错误——lint 可按此机器校验。
+
+## 建议（best practices）
+
+1. **命名即归属**：utils 名与表名一致 = 该实体领域规则集（`OrderUtils` ↔ `order`）。业务无关的通用工具（`AmtUtils`/`DateTimeUtils`）不绑定表，放共享目录。
+2. **规则二分定性**（既定决策）：**不查库 → utils 谓词**（纯函数）；**查库 → service 断言方法**（`invoke(dao.findByName) → IF(isNotNull) → THROW`）；**硬不变量 → 表约束**（TableSchema unique/FK，DB 物理兜底）。不建 RuleSchema——规则已有 schema：表/谓词/守卫。
+3. **失败抛错，不返回错误码结构**：校验失败 `throw new Error('ORDER_CANNOT_CANCEL: ...')` 或业务异常类；flow 的 TRY-CATCH 按异常名捕获。
+4. **复用判据**：规则被 ≥2 处使用才提取为 utils；单处使用留在 flow 守卫片段（"三行相似胜过过早抽象"）。
+5. **纯函数、无 I/O**：utils 不做数据库/网络访问；需要 I/O 的规则属于 service。
+6. **表列引用用 `dtoField(table.columns.x)` 包装**：包装层反写安全，共享列实例永不被动；参数名可以与列名不同（如 `state` 包装 `status` 列）。
+7. **result 选型与命名一致**：防御 guard → **`void`** + `assert/validate/ensure` 前缀（抛错即语义）；判断 → `booleanField()`（或枚举）+ `can/is/has` 前缀（供 flow 谓词位）；计算 → `decimalField`/`intField`/`stringField` 标量。
+8. **flow 集成**：判断类可直接作 `IF(cond)` 条件位谓词（多入参靠 invoke 多槽位）；防御 guard 通过 `invoke` 在流程前置位调用。
+
+## 生成与合并
+
+`pylonts gen utils`：生成 `export class OrderUtils { static ... }` 骨架（每方法 `Not implemented` throw），签名由 schema 推导（enum → 枚举类型名 + 自动 import；date/datetime → string；无 result → `void`）。已存在文件**方法级 MERGE**（用户填充的方法体保留、私有 helper 不碰、契约删方法移除、新方法追加 stub）；`--force` 整文件覆盖。覆盖规范见 [gen-utils-overwrite.md](../../docs/gen-utils-overwrite.md)。
+
+## 校验
+
+`pylonts lint utils`：存储位置 + 绑定共享实例 + 文件名机器校验（`lint all` 已包含）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonts/dsl",
-  "version": "1.1.18",
+  "version": "1.1.20",
   "description": "Schema definition DSL with drivers: MySQL DDL, TS enum, TypeBox schema codegen.",
   "type": "module",
   "main": "dist/index.js",

package/src/dto.ts

@@ -185,6 +185,45 @@ export function isDtoField(v: unknown): v is DtoField {
   return 'field' in v && !('type' in v);
 }
 
+/** Resolve a ref chain to its terminal DtoField (the one without .ref).
+ *  Cycles are a DSL definition error — fail loudly at render time. */
+export function resolveDtoRefChain(f: DtoField): DtoField {
+  const seen = new Set<DtoField>();
+  let cur: DtoField = f;
+  while (cur.ref !== undefined) {
+    if (seen.has(cur.ref)) {
+      throw new Error(`dto field ${cur.name}: circular ref chain (field references itself)`);
+    }
+    seen.add(cur.ref);
+    cur = cur.ref;
+  }
+  return cur;
+}
+
+/** TS type of a DtoField in generated code — unwraps the wrapped field
+ *  (enum → its JS name, date/datetime → string, containers → jsType). */
+export function dtoFieldJsType(df: DtoField): string {
+  const f = df.field;
+  if (f.type === 'enum') return f.enum.jsName;
+  if (f.type === 'date' || f.type === 'datetime') return 'string';
+  return f.jsType;
+}
+
+/** Enum JS names referenced by a DtoField, recursing into inline array/object
+ *  wrappers; DtoMessage item references stop the walk. First-occurrence order. */
+export function dtoCollectEnumRefs(df: DtoField, out: string[] = []): string[] {
+  const f = df.field;
+  if (f.type === 'enum') {
+    out.push(f.enum.jsName);
+  } else if (f.type === 'array') {
+    const items = f.items;
+    if (isDtoField(items)) dtoCollectEnumRefs(items, out);
+  } else if (f.type === 'object') {
+    for (const child of Object.values(f.properties)) dtoCollectEnumRefs(child, out);
+  }
+  return out;
+}
+
 export function dtoArrayField(def: { items: DtoField | DtoMessage } & Omit<BaseField, 'name'>): DtoArrayField {
   // Items stay as-is: an inline DtoField is rendered inline, a DtoMessage is
   // referenced by name (the driver renders Type.Array(<DtoName>)).

package/src/typebox-driver.ts

@@ -1,4 +1,4 @@
-import { DtoArrayField, DtoField, DtoMessage, DtoObjectField, ImportBase, ImportRef, isDtoField, isDtoMessage } from './dto.js';
+import { DtoArrayField, DtoField, DtoMessage, DtoObjectField, ImportBase, ImportRef, isDtoField, isDtoMessage, resolveDtoRefChain } from './dto.js';
 import { collectEnumRefs, EnumField, Field } from './dsl.js';
 import type { TableSchema } from './db.js';
 import type { TokenSchema } from './token.js';
@@ -34,21 +34,6 @@ function dtoFieldDescription(f: DtoField): string | undefined {
   return f.description ?? fieldDescription(f.field);
 }
 
-/** Resolve a ref chain to its terminal field (the one without .ref).
- *  Cycles are a DSL definition error — fail loudly at render time. */
-function resolveRefChain(f: DtoField): DtoField {
-  const seen = new Set<DtoField>();
-  let cur: DtoField = f;
-  while (cur.ref !== undefined) {
-    if (seen.has(cur.ref)) {
-      throw new Error(`dto field ${cur.name}: circular ref chain (field references itself)`);
-    }
-    seen.add(cur.ref);
-    cur = cur.ref;
-  }
-  return cur;
-}
-
 function renderBasic(
   field: Field,
   pattern: string | undefined,
@@ -198,7 +183,7 @@ function renderField(f: DtoField, indent: number, resolver: EnumResolver | undef
  *  chain, inherit the terminal field's type/constraints, keep the referencing
  *  field's own overrides (pattern / default / description). */
 function renderRefBase(f: DtoField, indent: number, resolver: EnumResolver | undefined): string {
-  const target = resolveRefChain(f);
+  const target = resolveDtoRefChain(f);
   const targetField = target.field as Field;
   const pattern = f.pattern ?? target.pattern;
   const defaultValue = f.default ?? target.default;
@@ -210,7 +195,7 @@ function renderRefBase(f: DtoField, indent: number, resolver: EnumResolver | und
  *  override first, then the chain's DtoField-level optional, then the bare
  *  column optionality. */
 function renderRefField(f: DtoField, indent: number, resolver: EnumResolver | undefined): string {
-  const target = resolveRefChain(f);
+  const target = resolveDtoRefChain(f);
   const optional = f.optional ?? target.optional ?? (target.field as Field).optional ?? false;
   const base = renderRefBase(f, indent, resolver);
   return optional ? `Type.Optional(${base})` : base;
@@ -253,7 +238,7 @@ function collectEnumImports(
   out: Map<string, ImportBase>,
 ): void {
   if (f.ref !== undefined) {
-    collectEnumImports(resolveRefChain(f), resolver, out);
+    collectEnumImports(resolveDtoRefChain(f), resolver, out);
     return;
   }
   if (f.field.type === 'array') {
@@ -303,14 +288,25 @@ export function collectDtoImports(
   for (const f of Object.values(schema.fields)) collectEnumImports(f, resolver, out);
 }
 
+/** JSON Schema readOnly annotation on a rendered scalar schema: the token
+ *  owns the field, the client must not send it (the __inject adapter
+ *  overwrites any client-supplied value anyway). Injection fields are always
+ *  scalar columns (tables forbid nested columns), so the only object literal
+ *  in a rendered scalar base is its options block. */
+function withReadOnly(base: string): string {
+  const idx = base.lastIndexOf('{');
+  if (idx === -1) return base.replace(/\(\s*\)$/, '({ readOnly: true })');
+  return `${base.slice(0, idx + 1)} readOnly: true,${base.slice(idx + 1)}`;
+}
+
 /** Render the server-injection base: token-injected fields as Optional
- *  properties of a TypeBox object, plus a non-enumerable __inject adapter
- *  (same mechanism as hand-written bases, see pylon __inject docs) that fills
- *  each field from the token at runtime. */
+ *  readOnly properties of a TypeBox object, plus a non-enumerable __inject
+ *  adapter (same mechanism as hand-written bases, see pylon __inject docs)
+ *  that fills each field from the token at runtime. */
 function renderInjectBase(fields: Record<string, DtoField>, resolver: EnumResolver | undefined): string {
   const entries = Object.entries(fields).map(([name, f]) => {
     const base = f.ref !== undefined ? renderRefBase(f, 1, resolver) : renderValue(f, 1, resolver);
-    return `  ${name}: Type.Optional(${base})`;
+    return `  ${name}: Type.Optional(${withReadOnly(base)})`;
   });
   const inner = `Type.Object({\n${entries.join(',\n')}\n})`;
   const assigns = Object.keys(fields)

package/src/utils.ts

@@ -1,19 +1,27 @@
 import type { CollectionSchemaBase, Field, SchemaBase } from './dsl.js';
+import type { DtoField } from './dto.js';
 import type { FrontAppSchema, ProjectApiSchema } from './project.js';
 
 // Base utility modules — business-agnostic helpers with full method
 // signatures (e.g. DateTimeUtils.format). Called at the service layer;
 // their args/results are own wire types, independent of business schemas.
+// A utils whose name matches a table name is a domain rule module: its
+// methods may wrap table columns via dtoField(table.columns.x) — the DtoField
+// wrapper owns the write-back, so the shared column instance is never
+// mutated (same rule as buildMessage: only inline fields get their
+// underlying Field written back).
 
 /** A utility method with a full signature. */
 export interface UtilsMethodSchema extends SchemaBase {
   type: 'utilsMethod';
   /** The utility module this method belongs to. */
   schema: UtilsSchema;
-  /** Input fields. */
-  args: Record<string, Field>;
-  /** Output field. */
-  result: Field;
+  /** Input fields — DtoField wrappers (dtoField(...)); may wrap table columns. */
+  args: Record<string, DtoField>;
+  /** Output field — a plain inline Field (boolean for checks, decimal for
+   *  computed amounts, ...). The method output is a fresh value, never a
+   *  shared table column. Omit for void methods (pure actions). */
+  result?: Field;
 }
 
 /** Method input for defineUtils: type/schema/name are set by the builder. */
@@ -62,13 +70,27 @@ export function defineUtils(options: {
       args: method.args,
       result: method.result,
     };
+    // Args: write back on the DtoField wrapper only (safe: wrappers are
+    // created per method via dtoField(), never shared). Inline fields get
+    // their underlying Field written back too; fields wrapping table columns
+    // (domain rules) keep the shared column instance untouched — its
+    // name/schema already point to the table.
     for (const argKey of Object.keys(methodSchema.args)) {
-      const field = methodSchema.args[argKey] as Field;
-      field.name = argKey;
-      field.schema = methodSchema;
+      const df = methodSchema.args[argKey] as DtoField;
+      df.name = argKey;
+      df.schema = schema;
+      if (df.field.schema === undefined) {
+        df.field.name = argKey;
+        df.field.schema = schema;
+      }
+    }
+    // Result (optional): a plain inline Field — write name/schema back only
+    // when it is unowned (schema === undefined); shared instances (table
+    // columns, fields already claimed by another container) stay untouched.
+    if (methodSchema.result !== undefined && methodSchema.result.schema === undefined) {
+      methodSchema.result.name = key;
+      methodSchema.result.schema = schema;
     }
-    methodSchema.result.name = key;
-    methodSchema.result.schema = methodSchema;
     schema.methods[key] = methodSchema;
   }
   return schema;