@pylonts/dsl 1.1.19 → 1.1.21

package/docs/table.md

@@ -131,6 +131,47 @@ export const audit = defineTable('audit', {
 
 > **外键是逻辑作用**：`foreignKeys` 用于定义期命名强校验与关系表达，**DDL 默认不渲染物理 FOREIGN KEY 约束**（`pylonts gen sql init` 不传 `generateForeignKeys`）。数据完整性由 Service/DAO 层保证；如需物理约束，调用 `buildCreateTableSql(schema, { generateForeignKeys: true })`。
 
+## 扩展表（extends）
+
+扩展表表示“本表是某张根表的延伸”：主键与根表主键同义、类型一致，生命周期跟随根表（创建 / 保存 / 删除一起做）。除这两条外，扩展表与普通表完全一样，可以有索引、外键、被其他表引用等。
+
+### 定义
+
+```ts
+// order 根表
+export const order = defineTable('order', {
+  ...
+  primaryKey: id,
+});
+
+// order_address 是 order 的扩展表
+const addressId = stringField({ maxLength: 32 }); // 与 order.id 同类型
+
+export const orderAddress = defineTable('order_address', {
+  extends: order,          // 声明本表是 order 的扩展
+  primaryKey: addressId,   // 主键与根主键同义
+  columns: {
+    id: addressId,
+    receiver_name: stringField({ label: '收货人', maxLength: 32, optional: false }),
+    ...
+  },
+});
+```
+
+### 规则
+
+- 扩展表的主键与根表主键同义，类型必须一致；
+- 根表不能是扩展表；
+- 扩展表不能再 `extends`（禁止链式延伸）；
+- 一个根表可以有多个扩展表；
+- 除主键和生命周期外，扩展表与普通表完全一样：可以有普通外键、索引、枚举等，也可被其他表引用；
+- 扩展表不需要像普通外键那样命名 `{phrase}_{field}`，也不需要显式声明 `foreignKeys` 来表达与根的关系，`extends` 本身就是关系。
+
+### 与聚合的关系
+
+- `members: { items: [orderItem] }`：数组 → 普通表 → 一对多；
+- `members: { address: orderAddress }`：非数组 → 扩展表 → 一对一。
+
 ## 生成 SQL
 
 见 [driver.md](./driver.md)。

package/docs/utils.md

@@ -0,0 +1,111 @@
+# 工具模块与领域规则（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 通过时无返回值）。
+- **throws**：`ExceptionSchema[] | undefined`——方法可抛的异常清单，**防御 guard 的失败契约**。flow 里 `invoke` 防御 guard 时，其 throws 自动进入流程逃逸集——调用方 service 方法的 throws 必须包含它（或 TRY 捕获）。谓词（can/is/has）不抛，无需声明。
+- **失败语义**：规则失败直接 `throw`（配合 `throws` 声明的 `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 | throws | 失败语义 | 典型示例 |
+|---|---|---|---|---|---|---|
+| **1 防御 guard** | `assertXX` / `validateXX` / `ensureXX` | 条件抛错（前置校验） | `void` | **必填**（失败契约） | **失败必抛错**，通过无返回值 | `assertCancelable`——已完成/已取消订单 throw `BusinessException` |
+| **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 + 必须声明 throws**（guard：通过无值、失败抛契约异常）；
+- `can/is/has` 前缀 → **必须 boolean**（判断谓词，进 flow `IF` 条件位）；
+- 计算类 → 标量 result。
+
+**双重校验**：
+
+1. **声明侧**（`pylonts lint utils`）：命名与 result 形态不匹配（如 `canXX` 返回 void、`assertXX` 返回 boolean）即违规报错；防御 guard 缺 throws 声明（失败契约缺失）同样违规。
+2. **使用侧**（flow 编译期，`defineFlow` 校验）：条件位谓词必须声明 boolean result——`IF(invoke(xxUtils.canCancel, ...))` 通过；`IF(invoke(xxUtils.assertCancelable, ...))`（void 守卫）和标量方法进 IF 直接报错，提示"守卫应 invoke 而非 IF"。
+
+**逃逸集联动**：`invoke` 防御 guard 时，guard 的 throws 自动并入流程逃逸集（与 dao/third 的 throws 同规则）——调用方 service 方法契约因此必须声明该异常（或 TRY 捕获），守卫的失败成为可验证的契约，而不是隐式冒泡。
+
+## 建议（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 多槽位），`gen service --flow` 渲染为 `OrderUtils.canCancel(body.status)`；防御 guard 通过 `invoke` 在流程前置位调用，渲染为 `OrderUtils.assertCancelable(body.status);`（void、内部 throw）。**计算类绑定标量槽**：flow 声明 `slots: { total: decimalField(...) }`，`invoke(calcTotal, args, slots.total)` 渲染 `const total: string = OrderUtils.calcTotal(body.unitPrice);`，标量槽可直接进守卫比较（`IF(gt(slots.total, 100))` → `if (Number(total) > 100)`）或作后续调用的标量参数（jsType 匹配直传）。
+
+## 生成与合并
+
+`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`：存储位置 + 绑定共享实例 + 文件名 + **命名↔result 一致性**（assert/validate/ensure → void，can/is/has → boolean）机器校验（`lint all` 已包含）。使用侧谓词 boolean 校验在 flow 编译期（`defineFlow`）执行。

package/package.json

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

package/src/aggregate.ts

@@ -1,22 +1,18 @@
 import type { SchemaBase } from './dsl.js';
-import type { TableSchema, ForeignKey } from './db.js';
+import type { TableSchema } from './db.js';
 
 // Aggregate declaration: groups multiple tables into one domain concept with
-// a root table, member attachment rules, cross-member invariants and
-// inter-aggregate reference rules. This turns "multi-table consistency" from a
-// convention (hand-written in flows) into a constraint (lintable, codegen-able).
+// a root table, member tables, cross-member invariants and inter-aggregate
+// reference rules. This turns "multi-table consistency" from a convention
+// (hand-written in flows) into a constraint (lintable, codegen-able).
+//
+// Members are intentionally minimal:
+//   members: { items: [orderItem] }   -> array  = 1:N (normal table)
+//   members: { address: orderAddress } -> single = 1:1 (extension table;
+//                                          designed but not implemented yet)
 
-/** How a member table attaches to the aggregate root. */
-export interface AggregateMember {
-  /** The member table (shared instance from schema/*.table.ts). */
-  table: TableSchema;
-  /** The foreign key on the member table pointing to the root table.
-   *  Must exist in table.foreignKeys and its references must be the root's PK
-   *  columns. Defaults to the (unique) FK referencing the root table. */
-  via?: ForeignKey;
-  /** 1:1 member (unique constraint on via.columns) vs 1:N (default). */
-  one?: boolean;
-}
+/** Member table(s) keyed by role name. Array = 1:N; non-array = 1:1 extension. */
+export type AggregateMember = TableSchema | TableSchema[];
 
 /** A cross-member invariant, checked by generated repository code. */
 export interface AggregateInvariant {
@@ -38,7 +34,6 @@ export interface DomainAggregate extends SchemaBase {
 }
 
 export function defineAggregate(options: {
-  name: string;
   root: TableSchema;
   members?: Record<string, AggregateMember>;
   invariants?: AggregateInvariant[];
@@ -47,7 +42,7 @@ export function defineAggregate(options: {
 }): DomainAggregate {
   const schema: DomainAggregate = {
     type: 'aggregate',
-    name: options.name,
+    name: options.root.name,
     description: options.description,
     root: options.root,
     members: options.members ?? {},
@@ -57,46 +52,42 @@ export function defineAggregate(options: {
 
   // Root must have a primary key (aggregate identity).
   if (options.root.primaryKey === undefined) {
-    throw new Error(`aggregate '${options.name}': root table '${options.root.name}' must have a primary key`);
+    throw new Error(`aggregate '${schema.name}': root table '${options.root.name}' must have a primary key`);
   }
 
-  // Each member must attach to the root via an existing FK referencing the root.
   const rootPkRefs = Array.isArray(options.root.primaryKey)
     ? options.root.primaryKey
     : [options.root.primaryKey];
+
+  // Each member must attach to the root. Array members are normal 1:N tables
+  // and must have exactly one FK referencing the root. Non-array (1:1 extension)
+  // members are designed but not implemented yet.
   for (const [role, member] of Object.entries(schema.members)) {
-    const fks = Object.values(member.table.foreignKeys ?? {}).filter(
-      (fk) => {
-        const refs = Array.isArray(fk.references) ? fk.references : [fk.references];
-        return refs.every((r) => rootPkRefs.includes(r)) && refs.length === rootPkRefs.length;
-      },
-    );
-    if (fks.length === 0) {
-      throw new Error(
-        `aggregate '${options.name}': member '${role}' table '${member.table.name}' has no foreign key referencing root '${options.root.name}' — declare one in the table's foreignKeys`,
-      );
-    }
-    if (member.via !== undefined) {
-      const viaKeys = Object.values(member.table.foreignKeys ?? {});
-      if (!viaKeys.includes(member.via)) {
+    if (Array.isArray(member)) {
+      if (member.length !== 1) {
         throw new Error(
-          `aggregate '${options.name}': member '${role}' via must be one of table '${member.table.name}' foreignKeys — got a non-FK object`,
+          `aggregate '${schema.name}': member '${role}' array must contain exactly one table schema`,
         );
       }
-      const refs = Array.isArray(member.via.references) ? member.via.references : [member.via.references];
-      if (!(refs.length === rootPkRefs.length && refs.every((r) => rootPkRefs.includes(r)))) {
+      const table = member[0];
+      const fks = Object.values(table.foreignKeys ?? {}).filter((fk) => {
+        const refs = Array.isArray(fk.references) ? fk.references : [fk.references];
+        return refs.length === rootPkRefs.length && refs.every((r) => rootPkRefs.includes(r));
+      });
+      if (fks.length === 0) {
         throw new Error(
-          `aggregate '${options.name}': member '${role}' via must reference root '${options.root.name}' primary key columns`,
+          `aggregate '${schema.name}': member '${role}' table '${table.name}' has no foreign key referencing root '${options.root.name}' — declare one in the table's foreignKeys`,
         );
       }
-    } else {
-      // Default: the (single) FK referencing the root. More than one → must declare via.
       if (fks.length > 1) {
         throw new Error(
-          `aggregate '${options.name}': member '${role}' table '${member.table.name}' has ${fks.length} foreign keys referencing root '${options.root.name}' — declare via explicitly`,
+          `aggregate '${schema.name}': member '${role}' table '${table.name}' has ${fks.length} foreign keys referencing root '${options.root.name}' — reduce to one FK for minimal aggregate declarations`,
         );
       }
-      (member as { via: ForeignKey }).via = fks[0];
+    } else {
+      throw new Error(
+        `aggregate '${schema.name}': member '${role}' is a non-array table — 1:1 extension tables are designed but not implemented yet; use an array for 1:N members`,
+      );
     }
   }
 

package/src/dto.ts

@@ -185,13 +185,70 @@ export function isDtoField(v: unknown): v is DtoField {
   return 'field' in v && !('type' in v);
 }
 
-/** TS type of a DtoField in generated code — unwraps the wrapped field
- *  (enum → its JS name, date/datetime → string, containers → jsType). */
+/** 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.
+ *  A field shared by reference (its schema is the owning DTO — utils args
+ *  like `args: { items: OrderSubmitRequest.fields.items }`) renders as an
+ *  indexed access on the DTO's generated type (the DTO owns the structure).
+ *  Array elements render by name (`ItemDto[]` — named DTO) or by recursion
+ *  (`Array<string>` — scalar). Plain wire objects (objectField) render
+ *  their property shape (`{ key: type }`); DtoField-class containers are
+ *  rejected at build time (DTOs must not nest inline structures).
+ *  Enum → its JS name, date/datetime → string. */
 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;
+  const owner = df.schema as { type?: string; name?: string } | undefined;
+  if (owner?.type === 'dto' && owner.name !== undefined && owner.name !== '' && df.name !== '') {
+    return `${owner.name}['${df.name}']`;
+  }
+  return dtoFieldJsTypeInner(df.field);
+}
+
+/** Type of a raw field object — unwraps DtoField-class wrappers
+ *  (dtoField(dtoArrayField(...)) stores the def inside the instance's
+ *  .field) and recurses: named-DTO elements (Name[]), scalar elements
+ *  (Array<T>), plain wire objects ({ key: type }), enums, and scalars. */
+function dtoFieldJsTypeInner(field: Field | DtoArrayFieldDef | DtoObjectFieldDef): string {
+  const f = (field as { field?: unknown }).field ?? field;
+  const inner = f as {
+    type?: string;
+    jsType?: string;
+    enum?: { jsName: string };
+    items?: DtoField | DtoMessage;
+    properties?: Record<string, DtoField | Field>;
+  };
+  if (inner.type === 'enum') return inner.enum!.jsName;
+  if (inner.type === 'date' || inner.type === 'datetime') return 'string';
+  if (inner.type === 'array') {
+    const items = inner.items!;
+    return isDtoMessage(items) ? `${items.name}[]` : `Array<${dtoFieldJsType(items)}>`;
+  }
+  if (inner.type === 'object') {
+    // Plain objectField properties are bare Fields; DtoObjectFieldDef
+    // properties are DtoFields. Recurse through both.
+    const props = Object.entries(inner.properties ?? {})
+      .map(([k, v]) => {
+        const optional = isDtoField(v) ? v.isOptional() : (v as Field).optional ?? false;
+        const type = isDtoField(v) ? dtoFieldJsType(v) : dtoFieldJsTypeInner(v as Field);
+        return `${k}${optional ? '?' : ''}: ${type}`;
+      })
+      .join('; ');
+    return `{ ${props} }`;
+  }
+  return inner.jsType ?? '';
 }
 
 /** Enum JS names referenced by a DtoField, recursing into inline array/object
@@ -210,8 +267,10 @@ export function dtoCollectEnumRefs(df: DtoField, out: string[] = []): string[] {
 }
 
 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>)).
+  // Items stay as-is: a DtoMessage is referenced by name (the driver renders
+  // Type.Array(<DtoName>)); a scalar DtoField element renders its primitive
+  // type. Inline container elements are rejected by buildMessage/defineUtils
+  // (DTOs must not nest inline structures — every object needs a name).
   return new DtoArrayField({ name: '', type: 'array', jsType: 'array', ...def });
 }
 
@@ -219,7 +278,42 @@ export function dtoObjectField(def: { properties: Record<string, DtoField> } & O
   return new DtoObjectField({ name: '', type: 'object', jsType: 'object', ...def });
 }
 
+/** DTOs must not nest DtoField-class containers inline: dtoObjectField /
+ *  dtoArrayField instances (and dtoField(dtoObjectField(...))-style wraps)
+ *  have no reusable name — extract a named DTO and reference it as an array
+ *  element (dtoArrayField({ items: namedDto })), and array items must be a
+ *  named DTO or a scalar field. Plain Field containers (objectField /
+ *  arrayField — wire-format nesting) stay legal and render inline.
+ *  DtoField-class wrappers (dtoField(dtoArrayField(...))) carry the def
+ *  inside the instance's .field, so both layers are unwrapped. */
+export function assertNoInlineContainers(dtoName: string, fields: Record<string, DtoField>): void {
+  for (const [key, df] of Object.entries(fields)) {
+    const f = (df.field as { field?: unknown }).field ?? df.field;
+    const field = f as { type?: string; items?: DtoField | DtoMessage };
+    // Only DtoField-class containers are banned (they need a name). Plain
+    // Field objects (objectField — wire-format nesting) are legal and render
+    // inline: dtoField(objectField({...})) stays allowed.
+    const isDtoClassContainer =
+      isDtoField(df.field) || typeof (df as { properties?: unknown }).properties === 'function';
+    if (isDtoClassContainer && field.type === 'object') {
+      throw new Error(
+        `[dto] "${dtoName}" field "${key}": inline object is not allowed — dtoObjectField containers must be named: extract a named DTO and reference it (dtoArrayField({ items: itemDto })) or use a plain objectField for wire-format nesting`,
+      );
+    }
+    if (field.type === 'array' && isDtoField(field.items)) {
+      const items = (field.items.field as { field?: unknown }).field ?? field.items.field;
+      const item = items as { type?: string };
+      if (item.type === 'object' || item.type === 'array') {
+        throw new Error(
+          `[dto] "${dtoName}" field "${key}": inline container elements are not allowed — array items must be a named DTO or a scalar field`,
+        );
+      }
+    }
+  }
+}
+
 function buildMessage(name: string, direction: DtoDirection, fields: Record<string, DtoField>, description?: string): DtoMessage {
+  assertNoInlineContainers(name, fields);
   const message = new DtoMessage(name, direction, fields, description);
   // Write back the DTO field name from the map key (safe: DtoField instances
   // are created per DTO, never shared).

package/src/flow-script.ts

@@ -21,6 +21,7 @@ import {
   guard,
   ifNode,
   isCall,
+  isConditionGroup,
   isEnd,
   isFlowNode,
   isFlowSlot,
@@ -297,6 +298,10 @@ function addUsed(ctx: FlowCompile, slot: FlowSlot | undefined): void {
 }
 
 function addConditionUsed(ctx: FlowCompile, c: GuardCondition): void {
+  if (isConditionGroup(c)) {
+    for (const s of c.conds) addConditionUsed(ctx, s);
+    return;
+  }
   if (!isCall(c)) {
     addUsed(ctx, isFlowSlot(c.field) ? c.field : c.field.slot);
     return;
@@ -310,6 +315,8 @@ function isInvokeStep(c: GuardCondition | InvokeStep): c is InvokeStep {
   return (c as InvokeStep).kind === 'invoke';
 }
 
+/** Lower an IF condition: a top-level invoke is a predicate call, and
+ *  composites convert invoke steps nested inside them recursively. */
 function toCondition(c: GuardCondition | InvokeStep): GuardCondition {
   if (isInvokeStep(c)) {
     if (c.result !== undefined) {
@@ -317,6 +324,9 @@ function toCondition(c: GuardCondition | InvokeStep): GuardCondition {
     }
     return { method: c.method, args: c.args === undefined ? [] : Array.isArray(c.args) ? c.args : [c.args] };
   }
+  if (isConditionGroup(c)) {
+    return { kind: c.kind, conds: c.conds.map((sub) => toCondition(sub)) };
+  }
   return c;
 }
 
@@ -341,11 +351,35 @@ function methodThrows(m: FlowMethodRef): ExceptionSchema[] {
 }
 
 /** Readable condition text used as node/branch labels (and as the throw
- *  label when THROW carries no message). */
+ *  label when THROW carries no message). Composites render parenthesized
+ *  sub-conditions: !(a), (a && b), (a || b). */
 function renderCondition(c: GuardCondition): string {
+  if (isConditionGroup(c)) {
+    const inner = c.conds.map(renderCondition).join(c.kind === 'and' ? ' && ' : c.kind === 'or' ? ' || ' : '');
+    return c.kind === 'not' ? `!(${inner})` : `(${inner})`;
+  }
   if (!isCall(c)) {
     if (isFlowSlot(c.field)) {
-      return c.op === 'isNull' ? `${c.field.name} is null` : `${c.field.name} is not null`;
+      const nullOp = c.op === 'isNull' || c.op === 'isNotNull';
+      if (nullOp) return c.op === 'isNull' ? `${c.field.name} is null` : `${c.field.name} is not null`;
+      // scalar slot comparison: total > 100
+      const ref = c.field.name;
+      switch (c.op) {
+        case 'lt':
+          return `${ref} < ${renderValue(c.value)}`;
+        case 'le':
+          return `${ref} <= ${renderValue(c.value)}`;
+        case 'gt':
+          return `${ref} > ${renderValue(c.value)}`;
+        case 'ge':
+          return `${ref} >= ${renderValue(c.value)}`;
+        case 'eq':
+          return `${ref} = ${renderValue(c.value)}`;
+        case 'ne':
+          return `${ref} ≠ ${renderValue(c.value)}`;
+        default:
+          throw new Error(`unsupported comparison op '${c.op}'`);
+      }
     }
     const field = c.field.field as { name: string };
     const ref = `${c.field.slot.name}.${field.name}`;
@@ -546,15 +580,21 @@ function compileTry(step: TryStep, ctx: FlowCompile, cont: FlowNodeOrEnd, inheri
   const ordinal = ctx.tryTotal - ++ctx.tryCount + 1;
   const suffix = ordinal === 1 ? '' : `${ordinal}`;
   const body = compileFlowBody(`${ctx.name}.tryBody${suffix}`, undefined, step.body, ctx, inherit);
+  // Catch handlers and finally may read what the body produced before the
+  // failure point (Java semantics: try { row = dao.get() } catch { use(row) }).
+  // The body's productions seed their entry availability alongside the
+  // enclosing flow's inherited slots.
+  const bodyProduced = flowProducedSlots(body);
+  const catchInherit = [...inherit, ...bodyProduced];
   const catches = step.catches.map(([ex, steps]) => ({
     exception: ex,
-    handler: compileFlowBody(`${ctx.name}.catch${ex.name}${suffix}`, undefined, steps, ctx, inherit),
+    handler: compileFlowBody(`${ctx.name}.catch${ex.name}${suffix}`, undefined, steps, ctx, catchInherit),
   }));
   const t = tryNode(step.name ?? 'try', {
     body,
     catches,
     finally: step.finally
-      ? compileFlowBody(`${ctx.name}.finally${suffix}`, undefined, step.finally, ctx, inherit)
+      ? compileFlowBody(`${ctx.name}.finally${suffix}`, undefined, step.finally, ctx, catchInherit)
       : undefined,
   });
   ctx.seen.add(t);
@@ -585,6 +625,22 @@ function compileSub(step: SubStep, ctx: FlowCompile, cont: FlowNodeOrEnd, inheri
   return n;
 }
 
+/** Slots a flow's own nodes produce (call results and writes) — the try
+ *  body's productions become visible to its catch handlers and finally. */
+function flowProducedSlots(f: FlowSchema): FlowSlot[] {
+  const out = new Set<FlowSlot>();
+  for (const n of f.nodes) {
+    if (isEnd(n)) continue;
+    if (isGuard(n) || isFlowNode(n)) {
+      for (const m of n.methods ?? []) {
+        if (isCall(m) && m.result !== undefined) out.add(m.result);
+      }
+      if (isFlowNode(n)) for (const w of n.writes ?? []) out.add(w);
+    }
+  }
+  return [...out];
+}
+
 /** Compile one flow (top-level or sub-flow): its own slots registry (args
  *  plus the named slots actually used inside), its own exception ends, and
  *  its own return end (linked through DANGLE). */
@@ -628,8 +684,11 @@ function buildFlow(
   const nodes = [...ctx.seen];
   const registry = defineSlots(buildSlots(ctx));
   // Entry inheritance only for slots the flow actually consumes; unused
-  // productions of the enclosing flow are not this flow's concern.
-  const entrySlots = rewriteSlots(nodes, ctx.edges, registry, ctx.entrySlots.filter((s) => ctx.usedSlots.has(s)));
+  // productions of the enclosing flow are not this flow's concern. Name-based
+  // matching: inherited instances may come from another flow's registry (the
+  // try body's re-bound productions), so identity comparison would drop them.
+  const usedNames = new Set([...ctx.usedSlots].map((s) => s.name));
+  const entrySlots = rewriteSlots(nodes, ctx.edges, registry, ctx.entrySlots.filter((s) => usedNames.has(s.name)));
   return defineFlow(name, {
     start,
     description,
@@ -671,6 +730,9 @@ function rewriteSlots(nodes: FlowNodeOrEnd[], edges: FlowEdge[], slots: FlowSlot
     return { method: m.method, args: m.args?.map(map), result: m.result ? map(m.result) : undefined };
   };
   const cond = (c: GuardCondition): GuardCondition => {
+    if (isConditionGroup(c)) {
+      return { kind: c.kind, conds: c.conds.map(cond) };
+    }
     if (!isCall(c)) {
       if (isFlowSlot(c.field)) {
         return { kind: 'comparison', op: c.op, field: map(c.field), value: c.value };