@pylonts/dsl 1.1.6 → 1.1.11

package/dist/index.d.ts

@@ -23,15 +23,19 @@ export * from './ref.js';
 export * from './route.js';
 export * from './service.js';
 export * from './controller.js';
-export * from './endpoint.js';
 export * from './dao.js';
+export * from './entity.js';
+export * from './expr.js';
+export * from './filter.js';
+export * from './aggregate.js';
+export * from './repository.js';
+export * from './domain-event.js';
 export * from './third-service.js';
 export * from './field-rule.js';
 export * from './exception.js';
 export * from './page.js';
 export * from './curd.js';
 export * from './page-flow.js';
-export * from './provider.js';
 export * from './page-def.js';
 export * from './mermaid-driver.js';
 export * from './navigation.js';

package/dist/index.js

@@ -23,15 +23,19 @@ export * from './ref.js';
 export * from './route.js';
 export * from './service.js';
 export * from './controller.js';
-export * from './endpoint.js';
 export * from './dao.js';
+export * from './entity.js';
+export * from './expr.js';
+export * from './filter.js';
+export * from './aggregate.js';
+export * from './repository.js';
+export * from './domain-event.js';
 export * from './third-service.js';
 export * from './field-rule.js';
 export * from './exception.js';
 export * from './page.js';
 export * from './curd.js';
 export * from './page-flow.js';
-export * from './provider.js';
 export * from './page-def.js';
 export * from './mermaid-driver.js';
 export * from './navigation.js';

package/dist/mermaid-driver.js

@@ -1,10 +1,17 @@
+import { isCall, 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
-// internals are rendered recursively. ok edges render as -->, conditional
-// edges render as -->|"WHEN"|.
+// internals are rendered recursively. A TryNode renders as a subgraph for its
+// body plus one per catch handler (and finally): body exception ends route to
+// handlers as dashed `catch X` edges, fall-through paths (body return end and
+// handler return ends, through finally when present) continue via the
+// TryNode's outgoing edges, and handler exception ends rethrow via the
+// TryNode's typed throws edges. Guard nodes render as diamonds, FlowEnd nodes
+// as stadium shapes. Normal edges render as -->, conditional edges as
+// -->|"WHEN"|, typed throws and catch routes as dashed edges.
 function escapeLabel(s) {
-    return s.replace(/"/g, '\\"').replace(/\n/g, '<br/>');
+    return s.replace(/"/g, '\\"').replace(/\n/g, '<br/>').replace(/\|/g, '&#124;');
 }
 export function renderFlowMermaid(schema) {
     const lines = ['flowchart TD'];
@@ -24,46 +31,279 @@ function renderFlow(schema, prefix, lines, ids) {
         outgoing.get(e.start).push(e);
     for (const n of schema.nodes) {
         const id = ids.get(n);
-        if (n.flow) {
-            lines.push(`    subgraph ${id}["${escapeLabel(renderNodeLabel(n))}"]`);
+        if (isTryNode(n)) {
+            lines.push(`    subgraph ${id}["${escapeLabel(n.name)}"]`);
+            renderFlow(n.body, `${id}_b`, lines, ids);
+            lines.push('    end');
+            const handlers = [];
+            const handlerIdx = new Map();
+            for (const c of n.catches) {
+                if (handlerIdx.has(c.handler))
+                    continue; // one handler may serve many catches
+                handlerIdx.set(c.handler, handlers.length);
+                handlers.push(c.handler);
+            }
+            handlers.forEach((h, i) => {
+                lines.push(`    subgraph ${id}_h${i}["${escapeLabel(h.name)}"]`);
+                renderFlow(h, `${id}_h${i}_`, lines, ids);
+                lines.push('    end');
+            });
+            if (n.finally) {
+                lines.push(`    subgraph ${id}_f["${escapeLabel(n.finally.name)}"]`);
+                renderFlow(n.finally, `${id}_f_`, lines, ids);
+                lines.push('    end');
+            }
+        }
+        else if (isFlowNode(n) && n.flow) {
+            lines.push(`    subgraph ${id}["${escapeLabel(renderNodeLabel(n, outgoing.get(n)))}"]`);
             renderFlow(n.flow, `${id}_`, lines, ids);
             lines.push('    end');
         }
         else {
             const shape = renderShape(n, schema, outgoing.get(n));
-            lines.push(`    ${id}${shape.open}${escapeLabel(renderNodeLabel(n))}${shape.close}`);
+            lines.push(`    ${id}${shape.open}${escapeLabel(renderNodeLabel(n, outgoing.get(n)))}${shape.close}`);
         }
     }
     for (const e of schema.edges) {
-        lines.push(renderEdge(e, ids));
+        if (isTryNode(e.start))
+            continue; // rendered by renderTryRoutes
+        if (isTryNode(e.end)) {
+            // entering a TryNode means entering its body
+            lines.push(renderEdgeLine(e, ids.get(e.start), ids.get(e.end.body.start)));
+            continue;
+        }
+        lines.push(renderEdgeLine(e, ids.get(e.start), ids.get(e.end)));
+    }
+    // guard checks: implicit branch edges of the guard itself
+    for (const n of schema.nodes) {
+        if (!isGuard(n))
+            continue;
+        const id = ids.get(n);
+        for (const c of n.checks) {
+            if (c.return) {
+                lines.push(`    ${id} -->|"${escapeLabel(c.when)}"| ${ids.get(schema.returnEnd)}`);
+            }
+            else if (c.exception) {
+                const t = findExceptionEnd(schema, c.exception.name);
+                lines.push(`    ${id} -.->|"${escapeLabel(c.when)} · throw ${escapeLabel(c.exception.name)}"| ${ids.get(t)}`);
+            }
+        }
+    }
+    // ifNode cases: implicit branch edges of the decision node
+    const branchTarget = (t) => (isTryNode(t) ? t.body.start : t);
+    for (const n of schema.nodes) {
+        if (!isIfNode(n))
+            continue;
+        const id = ids.get(n);
+        for (const c of n.cases) {
+            lines.push(`    ${id} -->|"${escapeLabel(c.when)}"| ${ids.get(branchTarget(c.to))}`);
+        }
+        lines.push(`    ${id} -->|"else"| ${ids.get(branchTarget(n.else))}`);
+    }
+    // TryNode internal routes
+    for (const n of schema.nodes) {
+        if (isTryNode(n))
+            renderTryRoutes(n, schema, ids, lines);
+    }
+}
+/** Routes of a TryNode: catch edges, fall-through continuation (through
+ *  finally when present), and handler rethrows (also through finally). */
+function renderTryRoutes(n, schema, ids, lines) {
+    const next = schema.edges.filter((e) => e.start === n && e.throws === undefined && e.exception !== true);
+    const rethrows = schema.edges.filter((e) => e.start === n && e.throws !== undefined);
+    for (const c of n.catches) {
+        const end = findExceptionEnd(n.body, c.exception.name);
+        lines.push(`    ${ids.get(end)} -.->|"catch ${escapeLabel(c.exception.name)}"| ${ids.get(c.handler.start)}`);
+    }
+    const continueFrom = (sourceId) => {
+        if (n.finally) {
+            lines.push(`    ${sourceId} --> ${ids.get(n.finally.start)}`);
+            return;
+        }
+        for (const e of next) {
+            lines.push(renderEdgeLine(e, sourceId, ids.get(e.end)));
+        }
+    };
+    continueFrom(ids.get(n.body.returnEnd));
+    const doneHandlers = new Set();
+    for (const c of n.catches) {
+        if (doneHandlers.has(c.handler))
+            continue; // one handler may serve many catches
+        doneHandlers.add(c.handler);
+        // A handler whose every path throws has no fall-through — its return end
+        // is never targeted and stays out of the handler's node list.
+        const handlerReturn = ids.get(c.handler.returnEnd);
+        if (handlerReturn !== undefined)
+            continueFrom(handlerReturn);
+    }
+    if (n.finally) {
+        for (const e of next) {
+            lines.push(renderEdgeLine(e, ids.get(n.finally.returnEnd), ids.get(e.end)));
+        }
+    }
+    const rethrown = new Map();
+    for (const e of rethrows) {
+        for (const c of n.catches) {
+            let names = rethrown.get(c.handler);
+            if (!names) {
+                names = new Set();
+                rethrown.set(c.handler, names);
+            }
+            if (names.has(e.throws.name))
+                continue; // one handler may serve many catches
+            names.add(e.throws.name);
+            const end = findExceptionEnd(c.handler, e.throws.name);
+            if (!end)
+                continue;
+            if (n.finally) {
+                lines.push(`    ${ids.get(end)} -.->|"rethrow ${escapeLabel(e.throws.name)}"| ${ids.get(n.finally.start)}`);
+                lines.push(`    ${ids.get(n.finally.returnEnd)} -.->|"rethrow ${escapeLabel(e.throws.name)}"| ${ids.get(e.end)}`);
+            }
+            else {
+                lines.push(`    ${ids.get(end)} -.->|"rethrow ${escapeLabel(e.throws.name)}"| ${ids.get(e.end)}`);
+            }
+        }
     }
 }
-/** Node label: name on the first line, method references on the second. */
-function renderNodeLabel(n) {
-    if (n.methods === undefined || n.methods.length === 0)
+/** The exception end of a flow carrying the given exception name. */
+function findExceptionEnd(flow, exceptionName) {
+    const end = flow.nodes.find((n) => isEnd(n) && n.type === 'exception' && n.exception?.name === exceptionName);
+    if (!end) {
+        throw new Error(`flow ${flow.name}: no exception end for ${exceptionName}`);
+    }
+    return end;
+}
+/** Node label: name on the first line, method references (including utils
+ *  predicates of guard checks) on the second, and the data line (slots
+ *  consumed `r:` / produced `w:`) last. */
+function renderNodeLabel(n, outgoing) {
+    if (isEnd(n) || isTryNode(n))
         return n.name;
-    return `${n.name}\n${n.methods.map((m) => renderMethodRef(m)).join(' | ')}`;
+    const lines = [n.name];
+    if (isFlowNode(n) && n.publish) {
+        const payload = n.publish.payload ? ` (${n.publish.payload.name})` : '';
+        lines.push(`publish ${n.publish.event.name}${payload}`);
+    }
+    const refs = [];
+    if (!isIfNode(n)) {
+        refs.push(...(n.methods ?? []));
+        if (isGuard(n)) {
+            for (const c of n.checks) {
+                if (c.check !== undefined && isCall(c.check))
+                    refs.push(c.check);
+            }
+        }
+    }
+    if (refs.length > 0) {
+        const rendered = refs.map((m) => renderMethodRef(methodOf(m))).join(' | ');
+        // Script-compiled nodes carry the full method name themselves.
+        if (rendered !== n.name)
+            lines.push(rendered);
+    }
+    const data = renderDataLine(n, outgoing);
+    if (data !== '')
+        lines.push(data);
+    return lines.join('\n');
 }
-/** Display form: owner.name for descriptors and container methods, bare name for converts. */
+/** Data line: `r:` lists slots the node consumes (reads, call args, decision
+ *  condition slots, and branch-edge conditions decided here), `w:` lists
+ *  slots it produces (writes and call results). */
+function renderDataLine(n, outgoing) {
+    const reads = new Set();
+    const writes = new Set();
+    const addCondition = (c) => {
+        if (c === undefined)
+            return;
+        if (!isCall(c)) {
+            reads.add(c.field.slot.name);
+            return;
+        }
+        for (const t of c.args ?? [])
+            reads.add(t.name);
+    };
+    if (isGuard(n)) {
+        for (const c of n.checks) {
+            for (const t of c.reads ?? [])
+                reads.add(t.name);
+            addCondition(c.check);
+        }
+    }
+    else if (isIfNode(n)) {
+        for (const c of n.cases)
+            addCondition(c.check);
+    }
+    else {
+        for (const t of n.reads ?? [])
+            reads.add(t.name);
+        for (const t of n.writes ?? [])
+            writes.add(t.name);
+        if (isFlowNode(n) && n.publish?.payload)
+            reads.add(n.publish.payload.name);
+    }
+    for (const e of outgoing)
+        addCondition(e.check);
+    if (!isIfNode(n)) {
+        for (const ref of n.methods ?? []) {
+            if (!isCall(ref))
+                continue;
+            for (const t of ref.args ?? [])
+                reads.add(t.name);
+            if (ref.result)
+                writes.add(ref.result.name);
+        }
+    }
+    const parts = [];
+    if (reads.size > 0)
+        parts.push(`r:${[...reads].join(',')}`);
+    if (writes.size > 0)
+        parts.push(`w:${[...writes].join(',')}`);
+    return parts.join(' ');
+}
+/** Display form: owner.name for descriptors, schema.name for container methods. */
 function renderMethodRef(m) {
     if ('owner' in m)
         return `${m.owner}.${m.name}`;
-    if ('schema' in m)
-        return `${m.schema.name}.${m.name}`;
-    return m.name;
+    return `${m.schema.name}.${m.name}`;
 }
-/** Shape derived from topology: start and terminals rounded, branching nodes diamond, else rect.
- *  Exception edges do not count as branches. */
+/** Shape derived from topology: guards are diamonds, ends rounded, other
+ *  branching nodes diamonds, else rect. Exception edges (typed or not) do not
+ *  count as branches. The start keeps its rounded shape unless it branches. */
 function renderShape(n, schema, outgoing) {
-    if (n === schema.start || outgoing.length === 0)
+    if (isGuard(n))
+        return { open: '{"', close: '"}' };
+    if (isIfNode(n))
+        return { open: '{"', close: '"}' };
+    if (isEnd(n) || outgoing.length === 0)
+        return { open: '(["', close: '"])' };
+    const normal = outgoing.filter((e) => e.exception !== true && e.throws === undefined).length;
+    if (normal >= 2)
+        return { open: '{"', close: '"}' };
+    if (n === schema.start)
         return { open: '(["', close: '"])' };
-    const normal = outgoing.filter((e) => e.exception !== true).length;
-    return normal >= 2 ? { open: '{"', close: '"}' } : { open: '["', close: '"]' };
+    return { open: '["', close: '"]' };
+}
+function renderEdgeLine(e, startId, endId) {
+    const isException = e.exception === true || e.throws !== undefined;
+    const arrow = isException ? '-.->' : '-->';
+    const throwLabel = e.throws ? `throw ${escapeLabel(e.throws.name)}` : '';
+    const labelParts = [e.when ? escapeLabel(e.when) : '', throwLabel].filter((s) => s !== '');
+    const label = labelParts.length > 0 ? `|"${labelParts.join(' · ')}"|` : '';
+    return `    ${startId} ${arrow}${label} ${endId}`;
+}
+function isEnd(n) {
+    return 'type' in n && (n.type === 'return' || n.type === 'exception');
+}
+function isFlowNode(n) {
+    return !('type' in n);
+}
+function isGuard(n) {
+    return 'type' in n && n.type === 'guard';
+}
+function isTryNode(n) {
+    return 'type' in n && n.type === 'try';
 }
-function renderEdge(e, ids) {
-    const arrow = e.exception === true ? '-.->' : '-->';
-    const label = e.when ? `|"${escapeLabel(e.when)}"|` : '';
-    return `    ${ids.get(e.start)} ${arrow}${label} ${ids.get(e.end)}`;
+function isIfNode(n) {
+    return 'type' in n && n.type === 'if';
 }
 // Page-driven flow renderer: groups pages by their app into swimlane
 // subgraphs, then renders edges across the whole flow.

package/dist/mysql-driver.js

@@ -37,6 +37,9 @@ function columnType(field) {
         case 'object':
             // Nested fields are wire-format only (third-party messages); table columns cannot nest.
             throw new Error(`field ${field.name} (${field.type}): nested fields are not supported on table columns`);
+        case 'aggregate':
+            // Aggregate fields are query outputs, never table columns.
+            throw new Error(`field ${field.name} (aggregate): aggregate fields are not supported on table columns`);
     }
 }
 function renderDefault(field) {

package/dist/project.d.ts

@@ -1,16 +1,17 @@
 import { SchemaBase } from './dsl.js';
 import type { TableSchema } from './db.js';
 /** Frontend form factor. Closed enum, extend when new form factors appear. */
-export type FrontType = 'admin' | 'wxmini';
+export type FrontType = 'admin' | 'wxmini' | 'mobile';
 /** A frontend application (e.g. admin console, wechat mini program). */
 export interface FrontAppSchema extends SchemaBase {
     type: FrontType;
     /** Source directory relative to project root, e.g. 'web-admin/'. */
     dir: string;
     /**
-     * Tenant table for this app. When set, all tables with a foreign key
-     * pointing to this table get automatic tenant scoping: the tenant PK
-     * value is injected from `user.id` into all curd operations.
+     * Tenant table for this app. The tenant column of a business table is
+     * deterministic: `{tenant.phrase}_{tenant.pk}` (e.g. shop with pk id →
+     * `shop_id`). Tables carrying that column get automatic tenant scoping;
+     * tables without it are global tables (e.g. system config) — both valid.
      */
     tenant?: TableSchema;
 }

package/dist/project.js

@@ -1,3 +1,12 @@
+// Instance naming: lowercase letters/digits/dashes only. Underscores belong
+// to table names; the instance export symbol in project.config.ts must equal
+// the kebab-camel of the name, so 'admin_api' cannot map to a valid symbol.
+const INSTANCE_NAME_RE = /^[a-z][a-z0-9-]*$/;
+function checkInstanceName(project, kind, name) {
+    if (!INSTANCE_NAME_RE.test(name)) {
+        throw new Error(`project ${project}: ${kind} name '${name}' must match ${INSTANCE_NAME_RE} (lowercase letters/digits/dashes; underscores are table-only)`);
+    }
+}
 /**
  * Defines the project topology. FrontAppSchema instances are shared value objects:
  * api.apps references the same instances from project.apps, so an app served
@@ -12,11 +21,12 @@ export function defineProject(name, schema) {
     for (const app of project.apps) {
         if (!app.name)
             throw new Error(`project ${name}: app name is required`);
+        checkInstanceName(name, 'app', app.name);
         if (appNames.has(app.name))
             throw new Error(`project ${name}: duplicate app name '${app.name}'`);
         appNames.add(app.name);
-        if (app.type !== 'admin' && app.type !== 'wxmini') {
-            throw new Error(`project ${name}: app '${app.name}' must be type 'admin' or 'wxmini' (got '${app.type}')`);
+        if (app.type !== 'admin' && app.type !== 'wxmini' && app.type !== 'mobile') {
+            throw new Error(`project ${name}: app '${app.name}' must be type 'admin', 'wxmini' or 'mobile' (got '${app.type}')`);
         }
         if (!app.dir)
             throw new Error(`project ${name}: app '${app.name}' dir is required`);
@@ -25,6 +35,7 @@ export function defineProject(name, schema) {
     for (const api of project.apis) {
         if (!api.name)
             throw new Error(`project ${name}: api name is required`);
+        checkInstanceName(name, 'api', api.name);
         if (apiNames.has(api.name))
             throw new Error(`project ${name}: duplicate api name '${api.name}'`);
         apiNames.add(api.name);
@@ -39,6 +50,7 @@ export function defineProject(name, schema) {
     for (const third of project.thirdApis) {
         if (!third.name)
             throw new Error(`project ${name}: thirdApi name is required`);
+        checkInstanceName(name, 'thirdApi', third.name);
         if (!third.dir)
             throw new Error(`project ${name}: thirdApi '${third.name}' dir is required`);
     }

package/dist/repository.d.ts

@@ -0,0 +1,26 @@
+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 declare function defineRepository(options: {
+    name: string;
+    aggregate: DomainAggregate;
+    description?: string;
+}): RepositorySchema;

package/dist/repository.js

@@ -0,0 +1,8 @@
+export function defineRepository(options) {
+    return {
+        type: 'repository',
+        name: options.name,
+        description: options.description,
+        aggregate: options.aggregate,
+    };
+}

package/dist/service.d.ts

@@ -1,9 +1,15 @@
-import { SchemaBase } from './dsl.js';
-import { FrontAppSchema } from './project.js';
+import type { SchemaBase } from './dsl.js';
+import type { FrontAppSchema, ProjectApiSchema } from './project.js';
 import type { DtoMessage } from './dto.js';
+import type { ExceptionSchema } from './exception.js';
+import type { FlowSchema } from './flow.js';
 /** A backend service serving exactly one frontend app (1:1 module). */
 export interface ServiceSchema extends SchemaBase {
     type: 'service';
+    /** The backend api module this service belongs to (shared instance from
+     *  project.config.ts apis). Services are always backend-side, so storage is
+     *  service_schema/{api.name}/{app.name}/service/. */
+    api: ProjectApiSchema;
     /** The frontend app this service serves (shared instance from project.config). */
     app: FrontAppSchema;
     /** Methods keyed by name — the map key is written back as the method name. */
@@ -13,6 +19,7 @@ export interface ServiceSchema extends SchemaBase {
 export type ServiceMethodDef = Omit<ServiceMethodSchema, 'type' | 'schema' | 'name'>;
 export declare function defineService(options: {
     name: string;
+    api: ProjectApiSchema;
     app: FrontAppSchema;
     methods: Record<string, ServiceMethodDef>;
     description?: string;
@@ -23,4 +30,9 @@ export interface ServiceMethodSchema extends SchemaBase {
     schema: ServiceSchema;
     args: DtoMessage;
     results: DtoMessage;
+    /** Exceptions this method may throw (e.g. IOException, CodeException). */
+    throws?: ExceptionSchema[];
+    /** Implementation flow — the method's logic graph. The method carries the
+     *  contract (args/results/throws), the flow carries the structure. */
+    flow?: FlowSchema;
 }

package/dist/service.js

@@ -1,8 +1,13 @@
+import { exceptionEndNames } from './flow.js';
 export function defineService(options) {
+    if (!options.api.apps.includes(options.app)) {
+        throw new Error(`service ${options.name}: api '${options.api.name}' does not serve app '${options.app.name}'`);
+    }
     const schema = {
         type: 'service',
         name: options.name,
         description: options.description,
+        api: options.api,
         app: options.app,
         methods: {},
     };
@@ -10,5 +15,49 @@ export function defineService(options) {
         const method = options.methods[key];
         schema.methods[key] = { type: 'method', schema, ...method, name: key };
     }
+    validateFlowBindings(schema);
     return schema;
 }
+// A method bound to a flow: the flow's escape set (its exception ends) must
+// equal the method's declared throws, the flow's own args/results (when
+// present) must be the same objects as the method's, and one flow may serve
+// only one method.
+//
+// Notes: (1) the unique-binding check is per defineService call — a flow
+// shared across two service schemas is not detected; (2) escape-set equality
+// means exceptions swallowed by an internal catch (or routed through a
+// catch-all end) disappear from the contract, so the method must not declare
+// them.
+function validateFlowBindings(schema) {
+    const seenFlows = new Set();
+    for (const key of Object.keys(schema.methods)) {
+        const m = schema.methods[key];
+        if (!m.flow)
+            continue;
+        if (seenFlows.has(m.flow)) {
+            throw new Error(`service ${schema.name}: flow "${m.flow.name}" is bound to more than one method`);
+        }
+        seenFlows.add(m.flow);
+        if (m.flow.args !== undefined && m.flow.args !== m.args) {
+            throw new Error(`service ${schema.name}: method "${key}" args and its flow "${m.flow.name}" args must be the same object`);
+        }
+        if (m.flow.results !== undefined && m.flow.results !== m.results) {
+            throw new Error(`service ${schema.name}: method "${key}" results and its flow "${m.flow.name}" results must be the same object`);
+        }
+        const escaped = exceptionEndNames(m.flow);
+        const declared = new Set((m.throws ?? []).map((t) => t.name));
+        for (const e of escaped) {
+            if (!declared.has(e)) {
+                throw new Error(`service ${schema.name}: method "${key}" flow escapes ${e} but the method does not declare it`);
+            }
+        }
+        for (const d of declared) {
+            if (!escaped.has(d)) {
+                throw new Error(`service ${schema.name}: method "${key}" declares throw ${d} but its flow never escapes it`);
+            }
+        }
+        if (m.flow.name !== key) {
+            console.warn(`service ${schema.name}: method "${key}" flow name "${m.flow.name}" differs from the method key`);
+        }
+    }
+}

package/dist/third-service.d.ts

@@ -1,4 +1,5 @@
 import { CollectionSchemaBase, Field, SchemaBase } from './dsl.js';
+import type { ExceptionSchema } from './exception.js';
 import type { FieldRuleEnd, FieldRuleSchema } from './field-rule.js';
 import type { ThirdApiSchema } from './project.js';
 /** A third-party integration service (e.g. tenpay wechat pay).
@@ -20,6 +21,8 @@ export interface ThirdServiceMethodSchema extends SchemaBase {
     args: ThirdMethodSchema;
     /** Output message. */
     results: ThirdMethodSchema;
+    /** Exceptions this method may throw (e.g. IOException, CodeException). */
+    throws?: ExceptionSchema[];
 }
 /** Field binding to a rule: which end the local wire field stands on.
  *  The ref always stands on the other end — from/to carry no extra information. */
@@ -65,6 +68,8 @@ export interface ThirdServiceMethodDef {
     args: ThirdMethodDef;
     /** Output message. */
     results: ThirdMethodDef;
+    /** Exceptions this method may throw (e.g. IOException, CodeException). */
+    throws?: ExceptionSchema[];
     description?: string;
 }
 export declare function defineThirdService(options: {

package/dist/third-service.js

@@ -85,6 +85,7 @@ export function defineThirdService(options) {
             schema,
             args: undefined,
             results: undefined,
+            throws: method.throws,
         };
         methodSchema.args = defineThirdMethod(method.args);
         methodSchema.results = defineThirdMethod(method.results);

package/dist/typebox-driver.js

@@ -62,6 +62,10 @@ function renderBasic(field, pattern, defaultValue, resolver, indent = 0) {
             }
             return `Type.Enum(${ref.name})`;
         }
+        case 'aggregate':
+            // Aggregate query outputs: count/sum(int) are numbers, everything else
+            // arrives as a precision string.
+            return field.jsType === 'number' ? 'Type.Number()' : 'Type.String()';
         case 'array':
             return `Type.Array(${renderFieldValue(field.items, indent, resolver)})`;
         case 'object':

package/dist/utils.d.ts

@@ -1,5 +1,5 @@
 import type { Field, SchemaBase } from './dsl.js';
-import type { FrontAppSchema } from './project.js';
+import type { FrontAppSchema, ProjectApiSchema } from './project.js';
 /** A utility method with a full signature. */
 export interface UtilsMethodSchema extends SchemaBase {
     type: 'utilsMethod';
@@ -15,13 +15,20 @@ export type UtilsMethodDef = Omit<UtilsMethodSchema, 'type' | 'schema' | 'name'>
 /** A base utility module (e.g. DateTimeUtils). */
 export interface UtilsSchema extends SchemaBase {
     type: 'utils';
-    /** Optional binding — empty means a shared public module. */
+    /** Backend binding — the api module this utils belongs to (shared instance
+     *  from project.config.ts apis). With `app` it serves that frontend
+     *  ({api}/{app}/utils/); alone it is the api's public module
+     *  ({api}/common/utils/). Unset = not backend-side. */
+    api?: ProjectApiSchema;
+    /** Optional binding — the frontend app this utils serves (shared instance
+     *  from project.config.ts apps). Empty means a shared public module. */
     app?: FrontAppSchema;
     /** Methods keyed by name — the map key is written back as the method name. */
     methods: Record<string, UtilsMethodSchema>;
 }
 export declare function defineUtils(options: {
     name: string;
+    api?: ProjectApiSchema;
     app?: FrontAppSchema;
     methods: Record<string, UtilsMethodDef>;
     description?: string;