@pylonts/dsl 1.1.6 → 1.1.12

package/src/index.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/src/mermaid-driver.ts

@@ -1,21 +1,28 @@
-import { FlowEdge, FlowNode, FlowSchema } from './flow.js';
-import type { FlowMethodRef } from './flow.js';
+import { FlowEdge, FlowEnd, FlowNode, FlowSchema, FlowStep, FlowNodeOrEnd, GuardNode, TryNode, IfNode } from './flow.js';
+import { isCall, methodOf } from './flow.js';
+import type { FlowMethodRef, FlowNodeMethodRef, GuardCondition } from './flow.js';
 import { Page } from './page.js';
 import { PageEdge, PageFlow } from './page-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: string): string {
-  return s.replace(/"/g, '\\"').replace(/\n/g, '<br/>');
+  return s.replace(/"/g, '\\"').replace(/\n/g, '<br/>').replace(/\|/g, '&#124;');
 }
 
 export function renderFlowMermaid(schema: FlowSchema): string {
   const lines: string[] = ['flowchart TD'];
-  const ids = new Map<FlowNode, string>();
+  const ids = new Map<FlowNodeOrEnd, string>();
   renderFlow(schema, 'n', lines, ids);
   lines.push('');
   lines.push('    classDef start fill:#e6f4ea,stroke:#333,stroke-width:1px;');
@@ -23,53 +30,273 @@ export function renderFlowMermaid(schema: FlowSchema): string {
   return lines.join('\n');
 }
 
-function renderFlow(schema: FlowSchema, prefix: string, lines: string[], ids: Map<FlowNode, string>): void {
+function renderFlow(schema: FlowSchema, prefix: string, lines: string[], ids: Map<FlowNodeOrEnd, string>): void {
   schema.nodes.forEach((n, i) => ids.set(n, `${prefix}${i}`));
-  const outgoing = new Map<FlowNode, FlowEdge[]>();
+  const outgoing = new Map<FlowNodeOrEnd, FlowEdge[]>();
   for (const n of schema.nodes) outgoing.set(n, []);
   for (const e of schema.edges) 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: FlowSchema[] = [];
+      const handlerIdx = new Map<FlowSchema, number>();
+      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: FlowNodeOrEnd): FlowNodeOrEnd => (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);
   }
 }
 
-/** Node label: name on the first line, method references on the second. */
-function renderNodeLabel(n: FlowNode): string {
-  if (n.methods === undefined || n.methods.length === 0) return n.name;
-  return `${n.name}\n${n.methods.map((m: FlowMethodRef) => renderMethodRef(m)).join(' | ')}`;
+/** Routes of a TryNode: catch edges, fall-through continuation (through
+ *  finally when present), and handler rethrows (also through finally). */
+function renderTryRoutes(n: TryNode, schema: FlowSchema, ids: Map<FlowNodeOrEnd, string>, lines: string[]): void {
+  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: string): void => {
+    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<FlowSchema>();
+  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<FlowSchema, Set<string>>();
+  for (const e of rethrows) {
+    for (const c of n.catches) {
+      let names = rethrown.get(c.handler);
+      if (!names) {
+        names = new Set<string>();
+        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)}`);
+      }
+    }
+  }
 }
 
-/** Display form: owner.name for descriptors and container methods, bare name for converts. */
+/** The exception end of a flow carrying the given exception name. */
+function findExceptionEnd(flow: FlowSchema, exceptionName: string): FlowEnd {
+  const end = flow.nodes.find(
+    (n): n is FlowEnd => 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: FlowNodeOrEnd, outgoing: FlowEdge[]): string {
+  if (isEnd(n) || isTryNode(n)) return n.name;
+  const lines: string[] = [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: FlowNodeMethodRef[] = [];
+  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');
+}
+
+/** 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: FlowNode | GuardNode | IfNode, outgoing: FlowEdge[]): string {
+  const reads = new Set<string>();
+  const writes = new Set<string>();
+  const addCondition = (c: GuardCondition | undefined): void => {
+    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: string[] = [];
+  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: FlowMethodRef): string {
   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: 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: FlowNodeOrEnd, schema: FlowSchema, outgoing: FlowEdge[]): { open: string; close: string } {
+  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: '"])' };
+  return { open: '["', close: '"]' };
+}
+
+function renderEdgeLine(e: FlowEdge, startId: string, endId: string): string {
+  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: FlowNodeOrEnd): n is FlowEnd {
+  return 'type' in n && (n.type === 'return' || n.type === 'exception');
+}
+
+function isFlowNode(n: FlowNodeOrEnd): n is FlowNode {
+  return !('type' in n);
+}
+
+function isGuard(n: FlowNodeOrEnd): n is GuardNode {
+  return 'type' in n && n.type === 'guard';
 }
 
-/** Shape derived from topology: start and terminals rounded, branching nodes diamond, else rect.
- *  Exception edges do not count as branches. */
-function renderShape(n: FlowNode, schema: FlowSchema, outgoing: FlowEdge[]): { open: string; close: string } {
-  if (n === schema.start || outgoing.length === 0) return { open: '(["', close: '"])' };
-  const normal = outgoing.filter((e) => e.exception !== true).length;
-  return normal >= 2 ? { open: '{"', close: '"}' } : { open: '["', close: '"]' };
+function isTryNode(n: FlowNodeOrEnd): n is TryNode {
+  return 'type' in n && n.type === 'try';
 }
 
-function renderEdge(e: FlowEdge, ids: Map<FlowNode, string>): string {
-  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: FlowNodeOrEnd): n is IfNode {
+  return 'type' in n && n.type === 'if';
 }
 
 // Page-driven flow renderer: groups pages by their app into swimlane

package/src/mysql-driver.ts

@@ -40,6 +40,9 @@ function columnType(field: Field): string {
     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`);
   }
 }
 

package/src/project.ts

@@ -1,98 +1,139 @@
-import { SchemaBase } from './dsl.js';
-import type { TableSchema } from './db.js';
-
-// Project topology definitions: describe the applications (frontends) and
-// backend APIs of a repository, and which frontends each API serves.
-
-/** Frontend form factor. Closed enum, extend when new form factors appear. */
-export type FrontType = 'admin' | 'wxmini';
-
-/** 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?: TableSchema;
-}
-
-/** A backend API service. apps references shared FrontAppSchema instances. */
-export interface ProjectApiSchema extends SchemaBase {
-  /** Source directory relative to project root, e.g. 'api/'. */
-  dir: string;
-  /** Frontends this API serves. Direct instance references (see defineProject). */
-  apps: FrontAppSchema[];
-  /** API base URL prefix shared by all apps it serves, e.g. '/mall'. '' = no prefix. */
-  contextPath?: string;
-  /** API service base URL for node clients, e.g. 'http://127.0.0.1:3000'. */
-  baseUrl?: string;
-}
-
-/** A third-party system (e.g. wechat pay, unionpay). Owns its own
- *  implementation dir and contract (controller_types), just like an API,
- *  but is not part of this repo's served surface. */
-export interface ThirdApiSchema extends SchemaBase {
-  /** Source directory relative to project root, e.g. 'wechat/'. */
-  dir: string;
-}
-
-export interface ProjectSchema extends SchemaBase {
-  apps: FrontAppSchema[];
-  apis: ProjectApiSchema[];
-  thirdApis: ThirdApiSchema[];
-}
-
-/**
- * Defines the project topology. FrontAppSchema instances are shared value objects:
- * api.apps references the same instances from project.apps, so an app served
- * by multiple APIs is defined once and referenced many times.
- *
- * Runtime-validates app type whitelist, unique names and api.apps reference
- * integrity (same style as defineTable/defineCurd).
- */
-export function defineProject(
-  name: string,
-  schema: {
-    description?: string;
-    apps: FrontAppSchema[];
-    apis: ProjectApiSchema[];
-    thirdApis?: ThirdApiSchema[];
-  },
-): ProjectSchema {
-  const project: ProjectSchema = { name, ...schema, thirdApis: schema.thirdApis ?? [] };
-
-  const appNames = new Set<string>();
-  for (const app of project.apps) {
-    if (!app.name) throw new Error(`project ${name}: app name is required`);
-    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.dir) throw new Error(`project ${name}: app '${app.name}' dir is required`);
-  }
-
-  const apiNames = new Set<string>();
-  for (const api of project.apis) {
-    if (!api.name) throw new Error(`project ${name}: api name is required`);
-    if (apiNames.has(api.name)) throw new Error(`project ${name}: duplicate api name '${api.name}'`);
-    apiNames.add(api.name);
-    if (!api.dir) throw new Error(`project ${name}: api '${api.name}' dir is required`);
-    for (const ref of api.apps) {
-      if (!project.apps.includes(ref)) {
-        throw new Error(`project ${name}: api '${api.name}' references app '${ref.name}' that is not a shared instance in project.apps (define once and reference it)`);
-      }
-    }
-  }
-
-  for (const third of project.thirdApis) {
-    if (!third.name) throw new Error(`project ${name}: thirdApi name is required`);
-    if (!third.dir) throw new Error(`project ${name}: thirdApi '${third.name}' dir is required`);
-  }
-
-  return project;
+import { SchemaBase } from './dsl.js';
+import type { TableSchema } from './db.js';
+
+// Project topology definitions: describe the applications (frontends) and
+// backend APIs of a repository, and which frontends each API serves.
+
+/** Frontend form factor. Closed enum, extend when new form factors appear. */
+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. 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;
+}
+
+/** A backend API service. apps references shared FrontAppSchema instances. */
+export interface ProjectApiSchema extends SchemaBase {
+  /** Source directory relative to project root, e.g. 'api/'. */
+  dir: string;
+  /** Frontends this API serves. Direct instance references (see defineProject). */
+  apps: FrontAppSchema[];
+  /** API base URL prefix shared by all apps it serves, e.g. '/mall'. '' = no prefix. */
+  contextPath?: string;
+  /** API service base URL for node clients, e.g. 'http://127.0.0.1:3000'. */
+  baseUrl?: string;
+}
+
+/** A third-party system (e.g. wechat pay, unionpay). Owns its own
+ *  implementation dir and contract (controller_types), just like an API,
+ *  but is not part of this repo's served surface. */
+export interface ThirdApiSchema extends SchemaBase {
+  /** Source directory relative to project root, e.g. 'wechat/'. */
+  dir: string;
+}
+
+export interface ProjectSchema extends SchemaBase {
+  apps: FrontAppSchema[];
+  apis: ProjectApiSchema[];
+  thirdApis: ThirdApiSchema[];
+}
+
+// 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: string, kind: string, name: string): void {
+  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)`,
+    );
+  }
+}
+
+// Directory convention: the instance dir equals its name ('api/' == 'api').
+// One concept, one spelling — no separate dir/name pairs to keep in sync.
+function normalizedDir(dir: string): string {
+  return dir.replace(/[\\/]+$/, '');
+}
+
+function checkDirMatchesName(project: string, kind: string, name: string, dir: string): void {
+  if (normalizedDir(dir) !== name) {
+    throw new Error(`project ${project}: ${kind} '${name}' dir must equal its name (got '${dir}')`);
+  }
+}
+
+/**
+ * Defines the project topology. FrontAppSchema instances are shared value objects:
+ * api.apps references the same instances from project.apps, so an app served
+ * by multiple APIs is defined once and referenced many times.
+ *
+ * Runtime-validates app type whitelist, unique names, api.apps reference
+ * integrity (same style as defineTable/defineCurd), plus two naming
+ * conventions: every app/api/thirdApi dir equals its name ('api/' == 'api'),
+ * and the first api must be named exactly 'api' (prefixed names like
+ * 'xx-api' are only allowed from the second api on).
+ */
+export function defineProject(
+  name: string,
+  schema: {
+    description?: string;
+    apps: FrontAppSchema[];
+    apis: ProjectApiSchema[];
+    thirdApis?: ThirdApiSchema[];
+  },
+): ProjectSchema {
+  const project: ProjectSchema = { name, ...schema, thirdApis: schema.thirdApis ?? [] };
+
+  const appNames = new Set<string>();
+  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' && 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`);
+    checkDirMatchesName(name, 'app', app.name, app.dir);
+  }
+
+  const apiNames = new Set<string>();
+  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);
+    if (!api.dir) throw new Error(`project ${name}: api '${api.name}' dir is required`);
+    checkDirMatchesName(name, 'api', api.name, api.dir);
+    for (const ref of api.apps) {
+      if (!project.apps.includes(ref)) {
+        throw new Error(`project ${name}: api '${api.name}' references app '${ref.name}' that is not a shared instance in project.apps (define once and reference it)`);
+      }
+    }
+  }
+
+  if (project.apis.length > 0 && project.apis[0].name !== 'api') {
+    throw new Error(
+      `project ${name}: first api must be named 'api' (got '${project.apis[0].name}'); prefixed names like 'xx-api' are only allowed from the second api on`,
+    );
+  }
+
+  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`);
+    checkDirMatchesName(name, 'thirdApi', third.name, third.dir);
+  }
+
+  return project;
 }

package/src/repository.ts

@@ -0,0 +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,
+  };
+}