@pylonts/dsl 1.1.20 → 1.1.21

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

@@ -200,13 +200,55 @@ export function resolveDtoRefChain(f: DtoField): DtoField {
   return cur;
 }
 
-/** TS type of a DtoField in generated code — unwraps the wrapped field
- *  (enum → its JS name, date/datetime → string, containers → jsType). */
+/** 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
@@ -225,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 });
 }
 
@@ -234,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 };

package/src/flow.ts

@@ -210,9 +210,49 @@ export interface Comparison {
 }
 
 /** The machine-readable condition behind a guard check or a branch edge
- *  (optional): a utils predicate call (its boolean result decides) or a field
- *  comparison. */
-export type GuardCondition = FlowCall | Comparison;
+ *  (optional): a utils predicate call (its boolean result decides), a field
+ *  comparison, or a composite (not/and/or over sub-conditions). */
+export type GuardCondition = FlowCall | Comparison | ConditionGroup;
+
+/** A composite condition: not (exactly one sub-condition), and/or (two or
+ *  more). Renderers parenthesize sub-groups, so nesting stays unambiguous. */
+export interface ConditionGroup {
+  kind: 'not' | 'and' | 'or';
+  conds: GuardCondition[];
+}
+
+export function isConditionGroup(c: unknown): c is ConditionGroup {
+  return (
+    typeof c === 'object' &&
+    c !== null &&
+    ((c as { kind?: unknown }).kind === 'not' || (c as { kind?: unknown }).kind === 'and' || (c as { kind?: unknown }).kind === 'or') &&
+    Array.isArray((c as { conds?: unknown }).conds)
+  );
+}
+
+/** Negation — the only way to invert a condition (e.g. !predicate). */
+export function not(...conds: GuardCondition[]): ConditionGroup {
+  if (conds.length !== 1) {
+    throw new Error('not: takes exactly one condition');
+  }
+  return { kind: 'not', conds };
+}
+
+/** Conjunction — every sub-condition must hold. */
+export function and(...conds: GuardCondition[]): ConditionGroup {
+  if (conds.length < 2) {
+    throw new Error('and: requires at least two conditions');
+  }
+  return { kind: 'and', conds };
+}
+
+/** Disjunction — at least one sub-condition holds. */
+export function or(...conds: GuardCondition[]): ConditionGroup {
+  if (conds.length < 2) {
+    throw new Error('or: requires at least two conditions');
+  }
+  return { kind: 'or', conds };
+}
 
 /** True when the condition operand is the slot itself (slot-level null check),
  *  not a field access on it. Slot metadata (name) lives on the proxy target and
@@ -221,13 +261,28 @@ export function isFlowSlot(v: unknown): v is FlowSlot {
   return typeof v === 'object' && v !== null && typeof (v as FlowSlot).name === 'string';
 }
 
+/** True when the slot carries a scalar Field (its declared type has a jsType)
+ *  rather than a message — scalar slots support full comparisons
+ *  (gt(slots.total, 100)); message slots only slot-level null checks. */
+export function isScalarSlot(slot: FlowSlot): boolean {
+  const t = slot.type as { jsType?: unknown } | undefined;
+  return typeof t === 'object' && t !== null && t.jsType !== undefined;
+}
+
 function comparison(op: CompareOp, field: unknown, value?: string | number | EnumValue): Comparison {
   if (isFlowSlot(field)) {
-    if (op !== 'isNull' && op !== 'isNotNull') {
-      throw new Error(`${op}: a slot-level check only supports isNull/isNotNull — field comparisons need slots.args.amt`);
-    }
-    if (value !== undefined) {
-      throw new Error(`${op}: takes no value`);
+    const nullOp = op === 'isNull' || op === 'isNotNull';
+    if (nullOp) {
+      if (value !== undefined) {
+        throw new Error(`${op}: takes no value`);
+      }
+    } else {
+      if (!isScalarSlot(field)) {
+        throw new Error(`${op}: a slot-level check only supports isNull/isNotNull — field comparisons need slots.args.amt`);
+      }
+      if (value === undefined) {
+        throw new Error(`${op}: requires a value`);
+      }
     }
     return { kind: 'comparison', op, field, value };
   }
@@ -869,19 +924,37 @@ function validateGuardChecks(schema: FlowSchema): void {
 }
 
 // A condition must be a utils predicate call (boolean result, no result
-// slot) or a field comparison whose op is known and whose value presence and
-// type match the operator.
+// slot), a field comparison whose op is known and whose value presence and
+// type match the operator, or a composite (not/and/or) whose sub-conditions
+// are each valid.
 const COMPARE_OPS: readonly CompareOp[] = ['lt', 'le', 'gt', 'ge', 'eq', 'ne', 'isNull', 'isNotNull'];
 
 function validateCondition(where: string, c: GuardCondition): void {
+  if (isConditionGroup(c)) {
+    if (c.kind === 'not') {
+      if (c.conds.length !== 1) {
+        throw new Error(`${where}: not() takes exactly one condition`);
+      }
+    } else if (c.conds.length < 2) {
+      throw new Error(`${where}: ${c.kind}() takes at least two conditions`);
+    }
+    for (const sub of c.conds) validateCondition(where, sub);
+    return;
+  }
   if (!isCall(c)) {
     if (isFlowSlot(c.field)) {
       const nullOp = c.op === 'isNull' || c.op === 'isNotNull';
-      if (!nullOp) {
-        throw new Error(`${where}: a slot-level check only supports isNull/isNotNull`);
-      }
-      if (c.value !== undefined) {
-        throw new Error(`${where}: ${c.op} takes no value`);
+      if (nullOp) {
+        if (c.value !== undefined) {
+          throw new Error(`${where}: ${c.op} takes no value`);
+        }
+      } else {
+        if (!isScalarSlot(c.field)) {
+          throw new Error(`${where}: a slot-level check only supports isNull/isNotNull`);
+        }
+        if (c.value === undefined) {
+          throw new Error(`${where}: ${c.op} requires a value`);
+        }
       }
       return;
     }
@@ -908,18 +981,27 @@ function validateCondition(where: string, c: GuardCondition): void {
     }
     return;
   }
-  const m = c.method as { type?: string; name: string };
+  const m = c.method as Partial<UtilsMethodSchema> & { type?: string; name: string };
   if (m.type !== 'utilsMethod') {
     throw new Error(`${where}: check call must be a utils predicate, got ${m.type ?? m.name}`);
   }
   if (c.result !== undefined) {
     throw new Error(`${where}: a predicate call cannot bind a result slot`);
   }
+  if (m.result === undefined || m.result.jsType !== 'boolean') {
+    const declared = m.result === undefined ? 'void' : m.result.jsType;
+    throw new Error(
+      `${where}: utils predicate "${m.name}" must declare a boolean result (got ${declared}) — ` +
+        `predicates (can/is/has) return boolean; defense guards (assert/validate/ensure) throw internally and are invoked, not used in IF`,
+    );
+  }
 }
 
 /** Slots a condition reads: a comparison's field slot (or the slot itself for
- *  slot-level checks) or a predicate call's arg slots. */
+ *  slot-level checks), a predicate call's arg slots, or every sub-condition's
+ *  slots for a composite. */
 function conditionSlots(c: GuardCondition): FlowSlot[] {
+  if (isConditionGroup(c)) return c.conds.flatMap(conditionSlots);
   if (!isCall(c)) return [isFlowSlot(c.field) ? c.field : c.field.slot];
   return c.args ?? [];
 }

package/src/mermaid-driver.ts

@@ -1,5 +1,5 @@
 import { FlowEdge, FlowEnd, FlowNode, FlowSchema, FlowStep, FlowNodeOrEnd, GuardNode, TryNode, IfNode } from './flow.js';
-import { isCall, isFlowSlot, methodOf } from './flow.js';
+import { isCall, isConditionGroup, isFlowSlot, methodOf } from './flow.js';
 import type { FlowMethodRef, FlowNodeMethodRef, GuardCondition } from './flow.js';
 import { Page } from './page.js';
 import { PageEdge, PageFlow } from './page-flow.js';
@@ -219,6 +219,10 @@ function renderDataLine(n: FlowNode | GuardNode | IfNode, outgoing: FlowEdge[]):
   const writes = new Set<string>();
   const addCondition = (c: GuardCondition | undefined): void => {
     if (c === undefined) return;
+    if (isConditionGroup(c)) {
+      for (const s of c.conds) addCondition(s);
+      return;
+    }
     if (!isCall(c)) {
       reads.add(isFlowSlot(c.field) ? c.field.name : c.field.slot.name);
       return;

package/src/repository.ts

@@ -6,8 +6,8 @@ import type { DomainAggregate } from './aggregate.js';
  * exposes the three fixed operation skeletons (load / save / delete) that the
  * generator expands from the aggregate structure:
  *
- *   save(order)  = tx { rootDao.upsert + memberDao cascade by via FK }
- *   load(id)     = rootDao.get + memberDao by via FK
+ *   save(order)  = tx { rootDao.upsert + memberDao cascade by FK / extends }
+ *   load(id)     = rootDao.get + memberDao by FK / extends
  *   delete(id)   = tx { memberDao delete + rootDao delete }
  *
  * Callers face the domain concept (Order), never the tables. DAO stays

package/src/utils.ts

@@ -1,5 +1,7 @@
 import type { CollectionSchemaBase, Field, SchemaBase } from './dsl.js';
+import { assertNoInlineContainers } from './dto.js';
 import type { DtoField } from './dto.js';
+import type { ExceptionSchema } from './exception.js';
 import type { FrontAppSchema, ProjectApiSchema } from './project.js';
 
 // Base utility modules — business-agnostic helpers with full method
@@ -22,6 +24,12 @@ export interface UtilsMethodSchema extends SchemaBase {
    *  computed amounts, ...). The method output is a fresh value, never a
    *  shared table column. Omit for void methods (pure actions). */
   result?: Field;
+  /** Exceptions this method may throw — the failure contract of a defense
+   *  guard (assert/validate/ensure: void, throws internally). Flows route
+   *  invoked guards' throws into their escape set automatically, so a
+   *  guard's throws must be declared by the calling service method (or
+   *  caught in a TRY). Predicates (can/is/has, boolean) do not throw. */
+  throws?: ExceptionSchema[];
 }
 
 /** Method input for defineUtils: type/schema/name are set by the builder. */
@@ -62,6 +70,9 @@ export function defineUtils(options: {
   };
   for (const key of Object.keys(options.methods)) {
     const method = options.methods[key] as UtilsMethodDef;
+    // Same rule as DTO fields: args must not nest inline containers — use a
+    // DTO field reference (args: { items: SubmitRequest.fields.items }).
+    assertNoInlineContainers(options.name, method.args);
     const methodSchema: UtilsMethodSchema = {
       type: 'utilsMethod',
       name: key,
@@ -69,14 +80,17 @@ export function defineUtils(options: {
       schema,
       args: method.args,
       result: method.result,
+      throws: method.throws,
     };
     // 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.
+    // created per method via dtoField(), never shared). Shared instances —
+    // DTO fields passed by reference (args: { items: OrderSubmitRequest.fields.items })
+    // and fields wrapping table columns (domain rules) — stay untouched: the
+    // DTO owns its field name/schema, the shared column instance keeps its
+    // table identity.
     for (const argKey of Object.keys(methodSchema.args)) {
       const df = methodSchema.args[argKey] as DtoField;
+      if (df.schema !== undefined) continue;
       df.name = argKey;
       df.schema = schema;
       if (df.field.schema === undefined) {