@pylonts/dsl 1.1.5 → 1.1.11

package/README.md

@@ -22,6 +22,10 @@ project（地图：应用与 API 拓扑）
 - [table.md](./docs/table.md) — 定义表（详细设计）
 - [dto.md](./docs/dto.md) — 定义 DTO
 - [curd.md](./docs/curd.md) — 管理端 CRUD 页面标准（CurdSchema）
+- [aggregate.md](./docs/aggregate.md) — 聚合/仓储 DSL 扩展规划（声明层已落地：DomainAggregate/RepositorySchema + 存储校验，生成器待选型）
+- [domain-event.md](./docs/domain-event.md) — 领域事件 DSL 扩展规划（声明层已落地：DomainEventSchema + event_schema 存储校验，发布/订阅待实现）
+- [ddd-principles.md](./docs/ddd-principles.md) — DDD 落地原则（已决策）
+- [trans-reentrant.md](./docs/trans-reentrant.md) — @Trans 可重入改造（已实现）
 - [enum.md](./docs/enum.md) — 定义枚举
 - [driver.md](./docs/driver.md) — driver 模式与产物生成
 - [mysql-connection.md](./docs/mysql-connection.md) — MySQL 连接说明

package/dist/action.d.ts

@@ -1,7 +1,39 @@
 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';
 /** An action a user can perform on a page (e.g. submit, approve, reject).
  *  Subclasses use `type` as the discriminator. */
 export interface ActionSchema extends SchemaBase {
     type: string;
 }
 export declare function defineAction(name: string, description?: string): ActionSchema;
+/** 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 declare function route(key: string): DataRef;
+/** Create a page-data reference. */
+export declare function data(key: string): DataRef;
+export interface CallAction extends ActionSchema {
+    type: 'call';
+    func: ControllerMethodSchema;
+    args?: Record<string, DtoField | DtoMessage | DtoArrayField | DtoObjectField | RefSchema | string>;
+}
+export declare function call(func: ControllerMethodSchema, args?: Record<string, DtoField | DtoMessage | DtoArrayField | DtoObjectField | RefSchema | string>): CallAction;
+/** Assign a call's result to a page data field.
+ *  React: setState({ [field]: await ... }). Mini-program: this.setData({ [field]: ... }). */
+export interface SetDataAction extends ActionSchema {
+    type: 'setData';
+    call: CallAction;
+    field: DtoField;
+}
+export declare function setData(call: CallAction, field: DtoField): SetDataAction;

package/dist/action.js

@@ -1,3 +1,17 @@
 export function defineAction(name, description) {
     return { name, description, type: 'gesture' };
 }
+/** Create a route-parameter reference. */
+export function route(key) {
+    return { type: 'route', key };
+}
+/** Create a page-data reference. */
+export function data(key) {
+    return { type: 'data', key };
+}
+export function call(func, args) {
+    return { name: func.name, type: 'call', func, args };
+}
+export function setData(call, field) {
+    return { name: 'setData', type: 'setData', call, field };
+}

package/dist/aggregate.d.ts

@@ -0,0 +1,38 @@
+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;
+}
+/** A cross-member invariant, checked by generated repository code. */
+export interface AggregateInvariant {
+    name: string;
+    /** Expression in the aggregate's field vocabulary (e.g. 'total == sum(items.price * items.qty)'). */
+    check: string;
+}
+export interface DomainAggregate extends SchemaBase {
+    type: 'aggregate';
+    /** The aggregate root table. */
+    root: TableSchema;
+    /** Member tables keyed by role name (e.g. 'items', 'address'). */
+    members: Record<string, AggregateMember>;
+    /** Cross-member invariants; optional. */
+    invariants?: AggregateInvariant[];
+    /** Inter-aggregate references: only by root ID, keyed by referenced role. */
+    references?: Record<string, string>;
+}
+export declare function defineAggregate(options: {
+    name: string;
+    root: TableSchema;
+    members?: Record<string, AggregateMember>;
+    invariants?: AggregateInvariant[];
+    references?: Record<string, string>;
+    description?: string;
+}): DomainAggregate;

package/dist/aggregate.js

@@ -0,0 +1,46 @@
+export function defineAggregate(options) {
+    const schema = {
+        type: 'aggregate',
+        name: options.name,
+        description: options.description,
+        root: options.root,
+        members: options.members ?? {},
+        invariants: options.invariants,
+        references: options.references,
+    };
+    // 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`);
+    }
+    // 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];
+    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`);
+            }
+            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`);
+            }
+        }
+        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`);
+            }
+            member.via = fks[0];
+        }
+    }
+    return schema;
+}

package/dist/business-flow.d.ts

@@ -0,0 +1,9 @@
+import type { FlowSchema } from './flow.js';
+/** One chart step: from → to, the optional branch label between them
+ *  (mandatory for decision branches). */
+export type ChartStep = [from: string, to: string] | [from: string, when: string, to: string];
+/** Compile a tuple chart into a FlowSchema. */
+export declare function flowChart(name: string, steps: ChartStep[], options?: {
+    description?: string;
+    start?: string;
+}): FlowSchema;

package/dist/business-flow.js

@@ -0,0 +1,72 @@
+// business-flow: the minimal form of a flow — a chart. Steps are [from, when,
+// to] tuples (the condition sits between source and target; a two-element
+// [from, to] step has no label); nodes are collected by name from the edges
+// (a name shared by several steps is one node); the first step's from is the
+// start; every node with no outgoing edge falls through to the flow's return
+// end. A node with several outgoing edges is a decision — the mermaid driver
+// draws it as a diamond, and every branch edge must carry a when label or the
+// chart cannot be read (nor later upgraded to machine conditions).
+//
+// The chart compiles to the same graph IR as flow-script: mermaid rendering,
+// reachability checks, and future consumers (an executor) all work unchanged.
+// A chart is the skeleton — upgrade a decision to IF(cond) and a node to
+// invoke(...) when the business logic arrives.
+import { defineFlow, edge, node } from './flow.js';
+/** Compile a tuple chart into a FlowSchema. */
+export function flowChart(name, steps, options = {}) {
+    if (steps.length === 0) {
+        throw new Error(`business-flow ${name}: at least one step is required`);
+    }
+    for (const step of steps) {
+        const from = step[0];
+        const to = step.length === 3 ? step[2] : step[1];
+        if (from === '' || to === '') {
+            throw new Error(`business-flow ${name}: node names must not be empty`);
+        }
+    }
+    if (options.start !== undefined && !steps.some((step) => step[0] === options.start)) {
+        throw new Error(`business-flow ${name}: start "${options.start}" is not the source of any step`);
+    }
+    const nodes = new Map();
+    const byName = (n) => {
+        let found = nodes.get(n);
+        if (found === undefined) {
+            found = node(n, {});
+            nodes.set(n, found);
+        }
+        return found;
+    };
+    const edges = steps.map((step) => {
+        const from = step[0];
+        const to = step.length === 3 ? step[2] : step[1];
+        const when = step.length === 3 ? step[1] : undefined;
+        return edge(byName(from), byName(to), { when });
+    });
+    // Decision rule: every branch of a multi-outgoing node must carry a label.
+    const outgoing = new Map();
+    for (const e of edges) {
+        const list = outgoing.get(e.start);
+        if (list === undefined)
+            outgoing.set(e.start, [e]);
+        else
+            list.push(e);
+    }
+    for (const [n, list] of outgoing) {
+        if (list.length > 1 && list.some((e) => e.when === undefined)) {
+            throw new Error(`business-flow ${name}: decision node "${n.name}" — every outgoing branch edge needs a when label`);
+        }
+    }
+    return defineFlow(name, {
+        start: byName(options.start ?? steps[0][0]),
+        description: options.description,
+        edges: (flow) => {
+            // Every path ends somewhere: nodes with no outgoing edge return.
+            const sinks = [];
+            for (const n of nodes.values()) {
+                if (!outgoing.has(n))
+                    sinks.push(edge(n, flow.returnEnd));
+            }
+            return [...edges, ...sinks];
+        },
+    });
+}

package/dist/controller.d.ts

@@ -0,0 +1,35 @@
+import { SchemaBase } from './dsl.js';
+import { FrontAppSchema, ProjectApiSchema } from './project.js';
+import type { DtoMessage } from './dto.js';
+/** A backend RPC controller. Strong constraints:
+ *  - a backend module maps 1:1 to a frontend app (they are peers);
+ *  - a controller serves exactly one frontend app — no cross-module calls. */
+export interface ControllerSchema extends SchemaBase {
+    type: 'controller';
+    /** The backend api module this controller belongs to (shared instance from
+     *  project.config.ts apis). Controllers are always backend-side, so storage
+     *  is controller_schema/{api.name}/{app.name}/controller/. */
+    api: ProjectApiSchema;
+    /** The frontend app this controller serves (shared instance from project.config). */
+    app: FrontAppSchema;
+    /** RPC methods, keyed by method name (key === method.name, enforced by the builder). */
+    methods: Record<string, ControllerMethodSchema>;
+}
+export declare function defineController(options: {
+    name: string;
+    api: ProjectApiSchema;
+    app: FrontAppSchema;
+    /** Method declarations: type/schema/name are injected by this builder. */
+    methods: Record<string, Omit<ControllerMethodSchema, 'type' | 'schema' | 'name'>>;
+    description?: string;
+}): ControllerSchema;
+/** An RPC method exposed by a controller. Carries the shared API call
+ *  signature: one request DTO in, one response shape out. Referenced by
+ *  frontend page actions — both sides use the exact same instance, so
+ *  drift is impossible. */
+export interface ControllerMethodSchema extends SchemaBase {
+    type: 'method';
+    schema: ControllerSchema;
+    args: DtoMessage;
+    results: DtoMessage | number | boolean | string;
+}

package/dist/controller.js

@@ -0,0 +1,17 @@
+export function defineController(options) {
+    if (!options.api.apps.includes(options.app)) {
+        throw new Error(`controller ${options.name}: api '${options.api.name}' does not serve app '${options.app.name}'`);
+    }
+    const schema = {
+        type: 'controller',
+        name: options.name,
+        description: options.description,
+        api: options.api,
+        app: options.app,
+        methods: {},
+    };
+    for (const [key, method] of Object.entries(options.methods)) {
+        schema.methods[key] = { type: 'method', schema, name: key, ...method };
+    }
+    return schema;
+}

package/dist/convert.d.ts

@@ -1,12 +1,42 @@
 import type { SchemaBase } from './dsl.js';
-import type { FrontAppSchema } from './project.js';
-/** Declares post-call result → page data field mapping.
- *  Driver generates per-item transform (e.g. .map()) before setData. */
+import type { DtoMessage } from './dto.js';
+import type { TableSchema } from './db.js';
+import type { EntitySchema } from './entity.js';
+import type { ThirdMethodSchema } from './third-service.js';
+import type { FrontAppSchema, ProjectApiSchema } from './project.js';
+/** A source/target collection of a convert — dto, entity, table or
+ *  third-party message. Entity sources may carry aggregate fields
+ *  (aggField), e.g. an aggregate result entity projected into a wire
+ *  message. */
+export type ConvertSourceSchema = DtoMessage | TableSchema | ThirdMethodSchema | EntitySchema;
+/** Method input for defineConvert: type/schema/name are set by the builder. */
+export type ConvertMethodDef = Omit<ConvertMethodSchema, 'type' | 'schema' | 'name'>;
+/** One conversion: multiple source collections → single target collection. */
+export interface ConvertMethodSchema extends SchemaBase {
+    type: 'convertMethod';
+    /** The convert file this method belongs to. */
+    schema: ConvertSchema;
+    /** Source schemas — one or more, mixed dimensions. */
+    sources: ConvertSourceSchema[];
+    /** Target schema — the single integrated collection. */
+    target: ConvertSourceSchema;
+}
+/** Declares multi-source → single-target schema integrations grouped by source identity. */
 export interface ConvertSchema extends SchemaBase {
     type: 'convert';
-    /** The frontend app this convert belongs to (shared instance from project.config). */
+    /** The backend api module this convert belongs to (shared instance from
+     *  project.config.ts apis). Storage is convert_schema/{api.name}/{app.name}/
+     *  — same layout as service_schema. */
+    api: ProjectApiSchema;
+    /** The app (module) this convert belongs to — its artifact lands in modules/{app}/convert/. */
     app: FrontAppSchema;
-    /** { targetField: sourceField } — renames or copies fields from call result. */
-    fields: Record<string, string>;
+    /** Methods keyed by name — the map key is written back as the method name. */
+    methods: Record<string, ConvertMethodSchema>;
 }
-export declare function defineConvert(name: string, app: FrontAppSchema, fields: Record<string, string>): ConvertSchema;
+export declare function defineConvert(options: {
+    name: string;
+    api: ProjectApiSchema;
+    app: FrontAppSchema;
+    methods: Record<string, ConvertMethodDef>;
+    description?: string;
+}): ConvertSchema;

package/dist/convert.js

@@ -1,3 +1,24 @@
-export function defineConvert(name, app, fields) {
-    return { name, type: 'convert', app, fields };
+export function defineConvert(options) {
+    if (Object.keys(options.methods).length === 0) {
+        throw new Error(`convert '${options.name}': methods must not be empty`);
+    }
+    if (!options.api.apps.includes(options.app)) {
+        throw new Error(`convert '${options.name}': api '${options.api.name}' does not serve app '${options.app.name}'`);
+    }
+    const schema = {
+        type: 'convert',
+        name: options.name,
+        description: options.description,
+        api: options.api,
+        app: options.app,
+        methods: {},
+    };
+    for (const key of Object.keys(options.methods)) {
+        const method = options.methods[key];
+        if (method.sources.length === 0) {
+            throw new Error(`convert '${options.name}': method '${key}' sources must not be empty`);
+        }
+        schema.methods[key] = { type: 'convertMethod', schema, ...method, name: key };
+    }
+    return schema;
 }

package/dist/curd.d.ts

@@ -1,14 +1,13 @@
-import { SchemaBase, Field, Operator } from './dsl.js';
+import { SchemaBase, Field } from './dsl.js';
 import { TableSchema } from './db.js';
 import { FrontAppSchema } from './project.js';
 import { ActionSchema } from './action.js';
+import type { FilterSchema } from './filter.js';
 /** Mode of an action page: modal dialog or standalone route. */
 export type ActionPageMode = 'modal' | 'route';
 /** One CRUD action page (add / update / detail). */
 export interface ActionPage {
     mode: ActionPageMode;
-    /** For add/update: when true, render as modal on list page; when false/undefined, render as standalone route page. */
-    modal?: boolean;
     /** Fields rendered on this page. Required, non-empty — every field the
      *  frontend shows must be listed explicitly. */
     columns: Field[];
@@ -18,20 +17,16 @@ export interface CurdListConfig {
     /** List columns; required, non-empty. Every field the list shows must be
      *  listed explicitly. May include cross-table fields via foreign refs. */
     columns: Field[];
-    /** Fuzzy keyword search on this table's columns. */
-    keyword?: {
-        columns: Field[];
-    };
+    /** Page filter (search form + keyword search). Conditions declared on the
+     *  filter render the search form; the filter's keyword (when present)
+     *  drives the keyword query endpoint. Optional — a page without a filter
+     *  has no search form. */
+    filter?: FilterSchema;
     /** Default sort. Required — column and direction are both mandatory. */
     orderBy: {
         column: Field;
         direction: 'asc' | 'desc';
     };
-    /** Search condition fields; op defaults to 'eq'. */
-    searchFields?: {
-        field: Field;
-        op?: Operator;
-    }[];
     /** Column header text overrides: Field.name → header text. */
     columnTitles?: Record<string, string>;
 }

package/dist/curd.js

@@ -1,3 +1,4 @@
+import { toKebabCase } from '@pylonts/core';
 function assertColumns(curd, pageName, columns) {
     if (columns.length === 0) {
         throw new Error(`curd ${curd.name}: ${pageName}.columns must be non-empty`);
@@ -17,6 +18,12 @@ export function defineCurd(name, schema) {
     if (curd.app.type !== 'admin') {
         throw new Error(`curd ${name}: app ${curd.app.name} must be type 'admin' (got '${curd.app.type}')`);
     }
+    // The name is the admin route path — it must be the kebab-case table name
+    // so paths cannot drift from the table they serve.
+    const expectedName = toKebabCase(curd.table.name);
+    if (name !== expectedName) {
+        throw new Error(`curd name must be '${expectedName}' (kebab-case of table '${curd.table.name}'); got '${name}'`);
+    }
     if (!curd.section) {
         throw new Error(`curd ${name}: section is required (sidebar menu group, e.g. '商户管理')`);
     }
@@ -25,7 +32,9 @@ export function defineCurd(name, schema) {
         if (page)
             assertColumns(curd, `actionPages.${pageName}`, page.columns);
     }
-    assertFieldsOwnTable(curd, 'keyword', curd.list.keyword?.columns ?? []);
+    if (curd.list.filter !== undefined && curd.list.filter.app !== curd.app) {
+        throw new Error(`curd ${name}: list.filter '${curd.list.filter.name}' is bound to app '${curd.list.filter.app.name}' but the curd belongs to app '${curd.app.name}'`);
+    }
     assertFieldsOwnTable(curd, 'orderBy', [curd.list.orderBy.column]);
     return curd;
 }

package/dist/dao.d.ts

@@ -1,9 +1,146 @@
-import { SchemaBase } from './dsl.js';
-import { FrontAppSchema } from './project.js';
+import { SchemaBase, Field } from './dsl.js';
+import type { FrontAppSchema, ProjectApiSchema } from './project.js';
+import { TableSchema } from './db.js';
+import type { EntitySchema } from './entity.js';
+import type { FilterSchema } from './filter.js';
+import type { SetExpr } from './expr.js';
 /** A data-access layer bound to exactly one frontend app. */
 export interface DaoSchema extends SchemaBase {
     type: 'dao';
+    /** The backend api module this DAO belongs to (shared instance from
+     *  project.config.ts apis). DAOs are always backend-side, so storage is
+     *  dao_schema/{api.name}/{app.name}/dao/. */
+    api: ProjectApiSchema;
     /** The frontend app this DAO belongs to (shared instance from project.config). */
     app: FrontAppSchema;
+    /** The table this DAO operates on (single-table atomicity). */
+    table: TableSchema;
+    /** Methods keyed by name — the map key is written back as the method name. */
+    methods: Record<string, DaoMethodSchema>;
+}
+/** Method input for defineDao: name is written back from the methods map key. */
+export type DaoMethodDef = Omit<FindSchema, 'schema' | 'name'> | Omit<GetSchema, 'schema' | 'name'> | Omit<InsertSchema, 'schema' | 'name'> | Omit<UpdateSchema, 'schema' | 'name'> | Omit<DeleteSchema, 'schema' | 'name'> | Omit<UpsertSchema, 'schema' | 'name'> | Omit<AggregateSchema, 'schema' | 'name'>;
+/** The tenant column of the dao table when the app declares a tenant.
+ *  Deterministic name derivation: `{tenant.phrase}_{tenant.pk}` (e.g. shop
+ *  with pk id → `shop_id`) — checked directly against the table columns,
+ *  no FK traversal. Tables without that column are global tables (valid:
+ *  system config tables carry no tenant id). Exported for generator/linter. */
+export declare function tenantFkOf(dao: DaoSchema): Field | undefined;
+export declare function defineDao(options: {
+    name: string;
+    api: ProjectApiSchema;
+    app: FrontAppSchema;
+    table: TableSchema;
+    methods: Record<string, DaoMethodDef>;
+    description?: string;
+}): DaoSchema;
+/** Sort specification for find results. */
+export interface OrderBySchema {
+    /** Column to sort by. */
+    column: Field;
+    /** Sort direction. */
+    sort: 'asc' | 'desc';
+}
+/** Query rows by criteria; returns a list of row objects. */
+export interface FindSchema extends SchemaBase {
+    type: 'find';
+    schema: DaoSchema;
+    /** Query filter; omit = all rows. */
+    args?: FilterSchema;
+    /** Pagination marker: 'page' (page/pageSize) or 'limit' (position/limit).
+     *  Only presence matters — parameter shapes are a generator convention. */
+    mode?: 'page' | 'limit';
+    /** Result sort; omit = no explicit order. */
+    orderBy?: OrderBySchema | OrderBySchema[];
+    /** Result row: selected columns (multi-table via external reference columns). */
+    results: EntitySchema;
+}
+/** Fetch a single row by exact key — any column or AND combination of
+ *  columns (single PK, composite PK, getByXX are all legal declarations).
+ *  May miss the row: the generated signature returns Row | null. */
+export interface GetSchema extends SchemaBase {
+    type: 'get';
+    schema: DaoSchema;
+    /** Key column(s): one field or AND-exact-matched fields. */
+    args: Field | Field[];
+    /** Additional criteria AND-combined onto the key (e.g. state condition
+     *  for optimistic reads). */
+    where?: FilterSchema;
+    /** Result row: selected columns (multi-table via external reference columns). */
+    results: EntitySchema;
+}
+/** Insert one row; returns the generated key (string). */
+export interface InsertSchema extends SchemaBase {
+    type: 'insert';
+    schema: DaoSchema;
+    /** Row object. */
+    args: EntitySchema;
+}
+/** Update one row; returns number (affected rows). The where key is derived
+ *  from the PK columns inside args; tenant/version columns are extracted
+ *  from the row into WHERE and never SET (optimistic lock auto-manages
+ *  `version = version + 1`). */
+export interface UpdateSchema extends SchemaBase {
+    type: 'update';
+    schema: DaoSchema;
+    /** Row object containing the PK columns plus the columns to set. */
+    args: EntitySchema;
+    /** Expression-set columns (`col = expr`) beyond direct assignment. */
+    set?: SetExpr[];
+    /** Additional criteria beyond the derived PK (AND-combined). */
+    where?: FilterSchema;
+}
+/** Delete one row by exact key; returns number (affected rows). */
+export interface DeleteSchema extends SchemaBase {
+    type: 'delete';
+    schema: DaoSchema;
+    /** Key column(s): one field or AND-exact-matched fields. */
+    args: Field | Field[];
+}
+/** Insert-or-update (MySQL ON DUPLICATE KEY UPDATE): atomic idempotent write.
+ *  Returns affected rows (1 = inserted, 2 = updated, 0 = unchanged).
+ *  No id generation — every conflict key must be carried in args. Tables with
+ *  an auto-increment pk are forbidden (MySQL auto_increment burns ids on
+ *  duplicate-key updates). */
+export interface UpsertSchema extends SchemaBase {
+    type: 'upsert';
+    schema: DaoSchema;
+    /** Row object: must carry every conflict key plus the columns to merge. */
+    args: EntitySchema;
+    /** Conflict keys: must equal the pk or a complete unique index column set. */
+    keys: Field | Field[];
+}
+export type DaoMethodSchema = FindSchema | GetSchema | InsertSchema | UpdateSchema | DeleteSchema | UpsertSchema | AggregateSchema;
+/** Aggregate query (find upgraded at the select level): the result entity
+ *  mixes plain columns (the GROUP BY dimensions) and aggregate fields
+ *  (aggField — count/sum/avg).
+ *
+ *  Usage — aggregate fields are defined in the entity file, the dao method
+ *  only references the entity:
+ *
+ *  ```ts
+ *  // entity_schema/{api}/{app}/entity/order.entity.ts
+ *  export const orderStatusStats = defineEntity({
+ *    name: 'OrderStatusStats',
+ *    api, app,
+ *    columns: [
+ *      order.columns.status,                      // GROUP BY dimension
+ *      aggField('total', Compute.count()),        // count → jsType 'number'
+ *      aggField('sumAmt', Compute.sum(order.columns.amount)), // sum(decimal) → 'string'
+ *    ],
+ *  });
+ *
+ *  // dao_schema/{api}/{app}/dao/order.dao.ts
+ *  stats: { type: 'aggregate', args: orderFilter, results: orderStatusStats },
+ *  ``` */
+export interface AggregateSchema extends SchemaBase {
+    type: 'aggregate';
+    schema: DaoSchema;
+    /** Criteria filter, same shape as find. */
+    args?: FilterSchema;
+    /** Result entity: plain columns group the rows (one row per group);
+     *  aggregate fields become the computed output columns. The entity — with
+     *  its aggField definitions — lives in the entity file ({table}.entity.ts);
+     *  the dao method only references it, never defines aggregate fields inline. */
+    results: EntitySchema;
 }
-export declare function defineDao(name: string, app: FrontAppSchema, description?: string): DaoSchema;