@pylonts/dsl 1.1.20 → 1.1.21

package/dist/aggregate.d.ts

@@ -1,16 +1,7 @@
 import type { SchemaBase } from './dsl.js';
-import type { TableSchema, ForeignKey } from './db.js';
-/** 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;
-}
+import type { TableSchema } from './db.js';
+/** 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 {
     name: string;
@@ -29,7 +20,6 @@ export interface DomainAggregate extends SchemaBase {
     references?: Record<string, string>;
 }
 export declare function defineAggregate(options: {
-    name: string;
     root: TableSchema;
     members?: Record<string, AggregateMember>;
     invariants?: AggregateInvariant[];

package/dist/aggregate.js

@@ -1,7 +1,7 @@
 export function defineAggregate(options) {
     const schema = {
         type: 'aggregate',
-        name: options.name,
+        name: options.root.name,
         description: options.description,
         root: options.root,
         members: options.members ?? {},
@@ -10,36 +10,33 @@ 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)) {
-                throw new Error(`aggregate '${options.name}': member '${role}' via must be one of table '${member.table.name}' foreignKeys — got a non-FK object`);
+        if (Array.isArray(member)) {
+            if (member.length !== 1) {
+                throw new Error(`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)))) {
-                throw new Error(`aggregate '${options.name}': member '${role}' via must reference root '${options.root.name}' primary key columns`);
+            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 '${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`);
+                throw new Error(`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.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`);
         }
     }
     return schema;

package/dist/dto.d.ts

@@ -106,8 +106,15 @@ 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). */
+/** 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 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. */
@@ -118,6 +125,15 @@ export declare function dtoArrayField(def: {
 export declare function dtoObjectField(def: {
     properties: Record<string, DtoField>;
 } & Omit<BaseField, 'name'>): DtoObjectField;
+/** 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 declare function assertNoInlineContainers(dtoName: string, fields: Record<string, DtoField>): void;
 export declare function buildInput(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage;
 export declare function buildOutput(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage;
 export declare function buildQuery(name: string, fields: Record<string, DtoField>, description?: string): DtoMessage;

package/dist/dto.js

@@ -133,15 +133,50 @@ export function resolveDtoRefChain(f) {
     }
     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) {
-    const f = df.field;
-    if (f.type === 'enum')
-        return f.enum.jsName;
-    if (f.type === 'date' || f.type === 'datetime')
+    const owner = df.schema;
+    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) {
+    const f = field.field ?? field;
+    const inner = f;
+    if (inner.type === 'enum')
+        return inner.enum.jsName;
+    if (inner.type === 'date' || inner.type === 'datetime')
         return 'string';
-    return f.jsType;
+    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.optional ?? false;
+            const type = isDtoField(v) ? dtoFieldJsType(v) : dtoFieldJsTypeInner(v);
+            return `${k}${optional ? '?' : ''}: ${type}`;
+        })
+            .join('; ');
+        return `{ ${props} }`;
+    }
+    return inner.jsType ?? '';
 }
 /** Enum JS names referenced by a DtoField, recursing into inline array/object
  *  wrappers; DtoMessage item references stop the walk. First-occurrence order. */
@@ -162,14 +197,45 @@ export function dtoCollectEnumRefs(df, 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>)).
+    // 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 });
 }
 export function dtoObjectField(def) {
     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, fields) {
+    for (const [key, df] of Object.entries(fields)) {
+        const f = df.field.field ?? df.field;
+        const field = f;
+        // 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.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.field ?? field.items.field;
+            const item = items;
+            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, direction, fields, description) {
+    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/dist/flow-script.js

@@ -9,7 +9,7 @@
 // The IR stays the single executable model (mermaid, must-analysis, throws
 // coverage, service contracts all consume it); this layer is a lowering, not
 // a parallel model.
-import { defineFlow, defineSlots, edge, guard, ifNode, isCall, isEnd, isFlowNode, isFlowSlot, isGuard, isIfNode, methodOf, node, tryNode, } from './flow.js';
+import { defineFlow, defineSlots, edge, guard, ifNode, isCall, isConditionGroup, isEnd, isFlowNode, isFlowSlot, isGuard, isIfNode, methodOf, node, tryNode, } from './flow.js';
 /** Call a method as a statement or (in IF position) as a utils predicate. */
 export function invoke(method, args, result) {
     return { kind: 'invoke', method, args, result };
@@ -132,6 +132,11 @@ function addUsed(ctx, slot) {
     ctx.usedNames.add(slot.name);
 }
 function addConditionUsed(ctx, c) {
+    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;
@@ -144,6 +149,8 @@ function addConditionUsed(ctx, c) {
 function isInvokeStep(c) {
     return c.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) {
     if (isInvokeStep(c)) {
         if (c.result !== undefined) {
@@ -151,6 +158,9 @@ function toCondition(c) {
         }
         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;
 }
 /** Display form mirrors the mermaid driver: owner.name / schema.name. */
@@ -172,11 +182,36 @@ function methodThrows(m) {
     return 'throws' in m && m.throws !== undefined ? m.throws : [];
 }
 /** 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) {
+    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;
         const ref = `${c.field.slot.name}.${field.name}`;
@@ -363,15 +398,21 @@ function compileTry(step, ctx, cont, inherit) {
     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);
@@ -401,6 +442,25 @@ function compileSub(step, ctx, cont, inherit) {
     ctx.edges.push(edge(n, cont));
     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) {
+    const out = new Set();
+    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). */
@@ -432,8 +492,11 @@ function buildFlow(name, description, ctx, start) {
     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,
@@ -475,6 +538,9 @@ function rewriteSlots(nodes, edges, slots, entrySlots) {
         return { method: m.method, args: m.args?.map(map), result: m.result ? map(m.result) : undefined };
     };
     const cond = (c) => {
+        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/dist/flow.d.ts

@@ -94,13 +94,30 @@ export interface Comparison {
     value?: string | number | EnumValue;
 }
 /** 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 declare function isConditionGroup(c: unknown): c is ConditionGroup;
+/** Negation — the only way to invert a condition (e.g. !predicate). */
+export declare function not(...conds: GuardCondition[]): ConditionGroup;
+/** Conjunction — every sub-condition must hold. */
+export declare function and(...conds: GuardCondition[]): ConditionGroup;
+/** Disjunction — at least one sub-condition holds. */
+export declare function or(...conds: GuardCondition[]): ConditionGroup;
 /** 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
  *  reads without field interception; a field access resolves to { slot, field }. */
 export declare function isFlowSlot(v: unknown): v is FlowSlot;
+/** 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 declare function isScalarSlot(slot: FlowSlot): boolean;
 export declare function lt(field: unknown, value: string | number): Comparison;
 export declare function le(field: unknown, value: string | number): Comparison;
 export declare function gt(field: unknown, value: string | number): Comparison;

package/dist/flow.js

@@ -80,19 +80,61 @@ export function isCall(m) {
 export function methodOf(m) {
     return isCall(m) ? m.method : m;
 }
+export function isConditionGroup(c) {
+    return (typeof c === 'object' &&
+        c !== null &&
+        (c.kind === 'not' || c.kind === 'and' || c.kind === 'or') &&
+        Array.isArray(c.conds));
+}
+/** Negation — the only way to invert a condition (e.g. !predicate). */
+export function not(...conds) {
+    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) {
+    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) {
+    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
  *  reads without field interception; a field access resolves to { slot, field }. */
 export function isFlowSlot(v) {
     return typeof v === 'object' && v !== null && typeof v.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) {
+    const t = slot.type;
+    return typeof t === 'object' && t !== null && t.jsType !== undefined;
+}
 function comparison(op, field, value) {
     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`);
+        const nullOp = op === 'isNull' || op === 'isNotNull';
+        if (nullOp) {
+            if (value !== undefined) {
+                throw new Error(`${op}: takes no value`);
+            }
         }
-        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 };
     }
@@ -495,18 +537,39 @@ function validateGuardChecks(schema) {
     }
 }
 // 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 = ['lt', 'le', 'gt', 'ge', 'eq', 'ne', 'isNull', 'isNotNull'];
 function validateCondition(where, c) {
+    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 (nullOp) {
+                if (c.value !== undefined) {
+                    throw new Error(`${where}: ${c.op} takes no value`);
+                }
             }
-            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;
         }
@@ -540,10 +603,18 @@ function validateCondition(where, c) {
     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) {
+    if (isConditionGroup(c))
+        return c.conds.flatMap(conditionSlots);
     if (!isCall(c))
         return [isFlowSlot(c.field) ? c.field : c.field.slot];
     return c.args ?? [];

package/dist/mermaid-driver.js

@@ -1,4 +1,4 @@
-import { isCall, isFlowSlot, methodOf } from './flow.js';
+import { isCall, isConditionGroup, isFlowSlot, methodOf } from './flow.js';
 // Mermaid driver: converts a FlowSchema into a Mermaid flowchart (TD).
 // Node ids are hierarchical (n0, n0_0, n0_0_0, ...) so nested sub-flows stay
 // globally unique. A node with a sub-flow renders as a subgraph block whose
@@ -214,6 +214,11 @@ function renderDataLine(n, outgoing) {
     const addCondition = (c) => {
         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/dist/repository.d.ts

@@ -5,8 +5,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/dist/utils.d.ts

@@ -1,5 +1,6 @@
 import type { CollectionSchemaBase, Field, SchemaBase } from './dsl.js';
 import type { DtoField } from './dto.js';
+import type { ExceptionSchema } from './exception.js';
 import type { FrontAppSchema, ProjectApiSchema } from './project.js';
 /** A utility method with a full signature. */
 export interface UtilsMethodSchema extends SchemaBase {
@@ -12,6 +13,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. */
 export type UtilsMethodDef = Omit<UtilsMethodSchema, 'type' | 'schema' | 'name'>;

package/dist/utils.js

@@ -1,3 +1,4 @@
+import { assertNoInlineContainers } from './dto.js';
 export function defineUtils(options) {
     if (options.api !== undefined && options.app !== undefined && !options.api.apps.includes(options.app)) {
         throw new Error(`utils ${options.name}: api '${options.api.name}' does not serve app '${options.app.name}'`);
@@ -12,6 +13,9 @@ export function defineUtils(options) {
     };
     for (const key of Object.keys(options.methods)) {
         const method = options.methods[key];
+        // 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 = {
             type: 'utilsMethod',
             name: key,
@@ -19,14 +23,18 @@ 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];
+            if (df.schema !== undefined)
+                continue;
             df.name = argKey;
             df.schema = schema;
             if (df.field.schema === undefined) {