@pylonts/dsl 1.1.20 → 1.1.22

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/index.ts

@@ -16,6 +16,8 @@ export * from './pattern.js';
 export * from './patterns/retry.js';
 export * from './flow.js';
 export * from './action.js';
+export * from './journey.js';
+export * from './page-action.js';
 export * from './event.js';
 export * from './component.js';
 export * from './convert.js';
@@ -31,6 +33,7 @@ export * from './aggregate.js';
 export * from './repository.js';
 export * from './domain-event.js';
 export * from './third-service.js';
+export * from './task.js';
 export * from './token.js';
 export * from './field-rule.js';
 export * from './exception.js';

package/src/journey.ts

@@ -0,0 +1,61 @@
+import { SchemaBase } from './dsl.js';
+import type { ActionSchema } from './action.js';
+
+// Journey definitions: a cross-app business journey — one data's story along
+// the time axis. A journey is a plain running list (流水账) of actions:
+// page → page → controller → third → db → task, in business order.
+//
+// Design principles:
+// - The protagonist (the data the journey is about) is IMPLICIT — derived
+//   from the actions, never declared. Like a TV protagonist: no label on the
+//   forehead.
+// - Blueprint first, anchored later: actions start as names (text), then
+//   upgrade to real references (page/controller/third/db/task instances).
+//   The name-vs-reference ratio is the refinement level.
+// - Every action is `type + properties + data` (ActionSchema). No from/to
+//   state transitions, no branches — a journey is a single line.
+
+/** One business journey: a goal-directed line of actions. */
+export interface JourneySchema extends SchemaBase {
+  /** Chinese title of the journey. */
+  title: string;
+  /** The business goal the journey achieves (what it is for). */
+  goal: string;
+  /** The running list of actions, in business order. */
+  actions: ActionSchema[];
+}
+
+/**
+ * Defines a business journey. `name` is kebab-case (e.g. 'merchant-onboarding');
+ * the export symbol is the kebab-camel of the name (merchantOnboarding).
+ * File name is the name plus '.journey.ts' (journey_schema/merchant-onboarding.journey.ts).
+ */
+export function defineJourney(options: {
+  name: string;
+  title: string;
+  goal: string;
+  actions: ActionSchema[];
+  description?: string;
+}): JourneySchema {
+  if (!/^[a-z][a-z0-9-]*$/.test(options.name)) {
+    throw new Error(
+      `journey ${options.name}: name must be kebab-case (lowercase letters/digits/dashes)`,
+    );
+  }
+  if (!options.title) {
+    throw new Error(`journey ${options.name}: title is required`);
+  }
+  if (!options.goal) {
+    throw new Error(`journey ${options.name}: goal is required`);
+  }
+  if (!options.actions || options.actions.length === 0) {
+    throw new Error(`journey ${options.name}: actions must be non-empty (a journey is a line of actions)`);
+  }
+  return {
+    name: options.name,
+    title: options.title,
+    goal: options.goal,
+    description: options.description,
+    actions: options.actions,
+  };
+}

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/navigation.ts

@@ -1,9 +1,9 @@
 import type { RouteDataSchema } from './route.js';
-import type { ActionSchema } from './action.js';
+import type { PageActionSchema } from './page-action.js';
 import { PageSchema } from './page.js';
 
 /** Navigation primitives: front-end routing actions that are not provider calls. */
-export interface NavigationAction extends ActionSchema {
+export interface NavigationAction extends PageActionSchema {
   type: 'navigation';
   method: 'back' | 'push' | 'popup' | 'home';
   /** Target page for push navigation. */

package/src/page-action.ts

@@ -0,0 +1,59 @@
+import { SchemaBase } from './dsl.js';
+import type { DtoField, DtoMessage, DtoArrayField, DtoObjectField } from './dto.js';
+import type { RefSchema } from './ref.js';
+import type { ControllerMethodSchema } from './controller.js';
+
+// Page actions: what a user can do ON a page (e.g. submit, approve, reject).
+// Distinguished from the cross-domain Action (journey): page actions live in
+// the page skeleton (PageDef.actions / PageSchema.pageDef) and describe the
+// page's own operation surface; journey actions describe what happens along a
+// business line (page / controller / third / db / task). Subclasses use
+// `type` as the discriminator.
+
+/** An action a user can perform on a page (e.g. submit, approve, reject).
+ *  Subclasses use `type` as the discriminator. */
+export interface PageActionSchema extends SchemaBase {
+  type: string;
+}
+
+export function definePageAction(name: string, description?: string): PageActionSchema {
+  return { name, description, type: 'gesture' };
+}
+
+/** Parameter data source for a call argument. */
+export type DataRef =
+  | { type: 'route'; key: string }
+  | { type: 'data';  key: string }
+  | { type: 'value'; value: unknown };
+
+/** Create a route-parameter reference. */
+export function route(key: string): DataRef {
+  return { type: 'route', key };
+}
+
+/** Create a page-data reference. */
+export function data(key: string): DataRef {
+  return { type: 'data', key };
+}
+
+export interface CallAction extends PageActionSchema {
+  type: 'call';
+  func: ControllerMethodSchema;
+  args?: Record<string, DtoField | DtoMessage | DtoArrayField | DtoObjectField | RefSchema | string>;
+}
+
+export function call(func: ControllerMethodSchema, args?: Record<string, DtoField | DtoMessage | DtoArrayField | DtoObjectField | RefSchema | string>): CallAction {
+  return { name: func.name, type: 'call', func, args };
+}
+
+/** Assign a call's result to a page data field.
+ *  React: setState({ [field]: await ... }). Mini-program: this.setData({ [field]: ... }). */
+export interface SetDataAction extends PageActionSchema {
+  type: 'setData';
+  call: CallAction;
+  field: DtoField;
+}
+
+export function setData(call: CallAction, field: DtoField): SetDataAction {
+  return { name: 'setData', type: 'setData', call, field };
+}

package/src/page-def.ts

@@ -2,7 +2,7 @@ import type { ImportableSchemaBase, CollectionSchemaBase, SchemaBase } from './d
 import { DtoField } from './dto.js';
 import type { DtoMessage, DtoArrayField, DtoObjectField } from './dto.js';
 import type { ComponentSchema } from './component.js';
-import type { ActionSchema } from './action.js';
+import type { PageActionSchema } from './page-action.js';
 
 export type { RouteDataSchema } from './route.js';
 export { defineRouteData } from './route.js';
@@ -14,24 +14,24 @@ export { defineRouteData } from './route.js';
 /** Page lifecycle events that trigger data loading. */
 export interface EventSchema extends SchemaBase {
   type: 'onLoad' | 'onShow' | 'onHide' | 'onPullDownRefresh' | 'onReachBottom';
-  /** Actions that fire when this event occurs. */
-  actions?: ActionSchema[];
+  /** Page actions that fire when this event occurs. */
+  actions?: PageActionSchema[];
 }
 
 export const events = {
-  onLoad(actions?: ActionSchema[], description?: string): EventSchema {
+  onLoad(actions?: PageActionSchema[], description?: string): EventSchema {
     return { name: 'onLoad', type: 'onLoad', actions, description };
   },
-  onShow(actions?: ActionSchema[], description?: string): EventSchema {
+  onShow(actions?: PageActionSchema[], description?: string): EventSchema {
     return { name: 'onShow', type: 'onShow', actions, description };
   },
-  onHide(actions?: ActionSchema[], description?: string): EventSchema {
+  onHide(actions?: PageActionSchema[], description?: string): EventSchema {
     return { name: 'onHide', type: 'onHide', actions, description };
   },
-  onPullDownRefresh(actions?: ActionSchema[], description?: string): EventSchema {
+  onPullDownRefresh(actions?: PageActionSchema[], description?: string): EventSchema {
     return { name: 'onPullDownRefresh', type: 'onPullDownRefresh', actions, description };
   },
-  onReachBottom(actions?: ActionSchema[], description?: string): EventSchema {
+  onReachBottom(actions?: PageActionSchema[], description?: string): EventSchema {
     return { name: 'onReachBottom', type: 'onReachBottom', actions, description };
   },
 };
@@ -64,7 +64,7 @@ export interface PageDef extends ImportableSchemaBase {
   /** Lifecycle events that trigger data loading. */
   events: EventSchema[];
   /** Page actions (provider calls, navigation, etc.). */
-  actions: ActionSchema[];
+  actions: PageActionSchema[];
   /** UI component declarations that make up the page skeleton. */
   components: ComponentSchema[];
   /** Whether the driver should generate page-level loading / error / empty state wrappers. */

package/src/page-flow.ts

@@ -1,5 +1,5 @@
 import { SchemaBase } from './dsl.js';
-import type { ActionSchema } from './action.js';
+import type { PageActionSchema } from './page-action.js';
 import { Page, getRegisteredPages, clearRegisteredPages } from './page.js';
 import type { PageDef } from './page-def.js';
 import type { NavigationAction } from './navigation.js';
@@ -10,8 +10,8 @@ import type { NavigationAction } from './navigation.js';
 // models the flow graph between pages.
 
 export interface PageEdge extends SchemaBase {
-  /** Trigger action; undefined = default path (success/normal). */
-  when?: ActionSchema;
+  /** Trigger page action; undefined = default path (success/normal). */
+  when?: PageActionSchema;
   start: Page;
   end: Page;
 }
@@ -24,7 +24,7 @@ export interface PageFlow extends SchemaBase {
   edges: PageEdge[];
 }
 
-export function pageEdge(start: Page, end: Page, when?: ActionSchema, description?: string): PageEdge {
+export function pageEdge(start: Page, end: Page, when?: PageActionSchema, description?: string): PageEdge {
   // Auto name for uniformity with SchemaBase; `when` stays the branch marker.
   return { name: `${start.name}->${end.name}`, start, end, when, description };
 }

package/src/popup.ts

@@ -1,15 +1,15 @@
-import type { ActionSchema } from './action.js';
+import type { PageActionSchema } from './page-action.js';
 import type { RefSchema } from './ref.js';
 
 /** Display a toast notification. React: toast/message UI. Mini-program: wx.showToast. */
-export interface ToastAction extends ActionSchema {
+export interface ToastAction extends PageActionSchema {
   type: 'toast';
   message: string | RefSchema;
   icon?: 'success' | 'error' | 'loading' | 'none';
 }
 
 /** Display an alert dialog. React: modal. Mini-program: wx.showModal. */
-export interface AlertAction extends ActionSchema {
+export interface AlertAction extends PageActionSchema {
   type: 'alert';
   title: string | RefSchema;
   content: string | RefSchema;

package/src/repository.ts

@@ -1,35 +1,35 @@
-import { SchemaBase } from './dsl.js';
-import type { DomainAggregate } from './aggregate.js';
-
-/**
- * Aggregate-grained storage entry. The repository binds one aggregate and
- * 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
- *   delete(id)   = tx { memberDao delete + rootDao delete }
- *
- * Callers face the domain concept (Order), never the tables. DAO stays
- * single-table; Repository is the multi-table (aggregate) unit; Service is the
- * use-case unit. Inter-aggregate joins are prohibited — repositories only
- * reference each other by root ID.
- */
-export interface RepositorySchema extends SchemaBase {
-  type: 'repository';
-  /** The aggregate this repository persists (shared instance). */
-  aggregate: DomainAggregate;
-}
-
-export function defineRepository(options: {
-  name: string;
-  aggregate: DomainAggregate;
-  description?: string;
-}): RepositorySchema {
-  return {
-    type: 'repository',
-    name: options.name,
-    description: options.description,
-    aggregate: options.aggregate,
-  };
-}
+import { SchemaBase } from './dsl.js';
+import type { DomainAggregate } from './aggregate.js';
+
+/**
+ * Aggregate-grained storage entry. The repository binds one aggregate and
+ * 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 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
+ * single-table; Repository is the multi-table (aggregate) unit; Service is the
+ * use-case unit. Inter-aggregate joins are prohibited — repositories only
+ * reference each other by root ID.
+ */
+export interface RepositorySchema extends SchemaBase {
+  type: 'repository';
+  /** The aggregate this repository persists (shared instance). */
+  aggregate: DomainAggregate;
+}
+
+export function defineRepository(options: {
+  name: string;
+  aggregate: DomainAggregate;
+  description?: string;
+}): RepositorySchema {
+  return {
+    type: 'repository',
+    name: options.name,
+    description: options.description,
+    aggregate: options.aggregate,
+  };
+}

package/src/task.ts

@@ -0,0 +1,52 @@
+import { CollectionSchemaBase } from './dsl.js';
+
+// Task definitions: scheduled (timer) operations — the second member of the
+// action closure (action = controller | task | third callback).
+//
+// A task is a contract: name + cron + what it does. It declares NO state
+// changes — state changes are expressed by journey steps. Task implementation
+// (scan logic, idempotency) lives in the implementation layer (e.g. pylon-flow
+// steps).
+//
+// Task represents ONLY timers (cron-driven). Async/event-driven operations
+// belong to the event system (EventObserver / EventNotifier, pending), not
+// here.
+
+export interface TaskSchema extends CollectionSchemaBase {
+  type: 'task';
+  /** Display label (Chinese) for the task. */
+  label: string;
+  /** Cron expression — the timer schedule. */
+  cron: string;
+}
+
+/**
+ * Defines a scheduled task. `name` must end with 'Task' (PascalCase,
+ * e.g. 'AutoRefundTask'); the export symbol equals the name. File name is the
+ * name minus the Task suffix, kebab-cased, plus '.task.ts'
+ * (AutoRefundTask → task_schema/auto-refund.task.ts).
+ */
+export function defineTask(options: {
+  name: string;
+  label: string;
+  cron: string;
+  description?: string;
+}): TaskSchema {
+  if (!/(Task)$/.test(options.name)) {
+    throw new Error(
+      `task ${options.name}: name must end with 'Task' (PascalCase, e.g. 'AutoRefundTask')`,
+    );
+  }
+  if (!options.cron || options.cron.trim() === '') {
+    throw new Error(
+      `task ${options.name}: cron is required (a task is a timer)`,
+    );
+  }
+  return {
+    type: 'task',
+    name: options.name,
+    label: options.label,
+    description: options.description,
+    cron: options.cron,
+  };
+}

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) {