@pylonts/dsl 1.1.21 → 1.1.22

package/docs/concepts.md

@@ -0,0 +1,109 @@
+# 概念层 (Concepts)
+
+概念层是**名字层**：每个业务名词先以"名字 + 名词解释"存在，先于一切结构（表、页面、接口、旅程）。它是蓝图体系的根——所有跨层引用（journey / table / PageFlow / DTO）的身份都从概念出发。
+
+## 认知顺序：名词在先，结构在后
+
+```
+名词（概念）：商户 —— 业务先说这个词，先解释它是什么
+   ↓ 派生
+词根（短语）：mer —— 为了字段名发明缩写
+   ↓ 长出
+结构：merchant 表 / 商户列表页 / 入驻旅程 —— 各维度引用"商户"
+```
+
+- **概念是本源**：业务人员嘴里只有"商户"，`mer` 是工程师后来为字段名发明的代号。
+- **短语（词根）是派生**：概念引用短语，不是短语解释概念。
+- **结构是生长**：表、页面、journey 都是概念"长出"的结构，各自引用概念名。
+
+## 与词典（_dictionary.ts）的关系
+
+| | 词典（dictionary） | 概念（concepts） |
+|---|---|---|
+| 单位 | 词根（mer / rate） | 完整名词（商户 / 银联报文） |
+| 主键 | 短语本身 | 名词标识 |
+| 内容 | 短语 + label + 描述 | 名词 + 经典段落解释 |
+| 服务对象 | 字段命名校验（lint field） | 所有维度的引用身份 |
+| 认知顺序 | 后于概念存在（缩写是派生的） | **先于一切存在** |
+
+**两者并存，互不反转**：`_dictionary.ts` 维持现状（词根字典，服务字段命名）；`_concepts.ts` 是新的概念清单（服务跨层身份）。概念通过 `phrase` 字段引用词根，把"名词 → 缩写"的派生关系显式化。
+
+## 规范位置：schema/_concepts.ts
+
+**所有概念统一定义在 `schema/_concepts.ts`**，一个文件一处定义（与 `_dictionary.ts` 同规则）。`table.ts` / journey / PageFlow 引用概念，禁止内联。
+
+## 定义形态
+
+```ts
+// schema/_concepts.ts
+import { defineConcept } from '@pylonts/dsl';
+
+export const merchant = defineConcept('merchant', {
+  title: '商户',
+  description: '入驻平台并签约收单的商家。由 BD 录入，平台审核，提交银联开通后获得登录资格，可登录商户端进行订单核销。',
+  phrase: mer,                        // 引用词根（_dictionary.ts 的实体短语）
+});
+
+export const unionpayReport = defineConcept('unionpay-report', {
+  title: '银联报文',
+  description: '提交给银联的商户资料报文，银联审核后返回审核结果。',
+});
+```
+
+- `name`：概念标识（kebab-case，跨层身份契约——journey / 表 / 页面都叫这个名字）。
+- `title`：中文名。
+- `description`：**经典段落**——一段话讲清楚"这是什么、干什么用的"，像文档术语表里的一条。
+- `phrase?`：引用 `_dictionary.ts` 的词根条目（实体短语），表达"这个概念在字段命名里缩写为什么"。
+- 一个概念可以还没有任何结构（没有表、没有页面）——**概念本身就是一个完整的存在**。
+
+## 蓝图态 → 锚定态：概念是跳板
+
+概念层解决"journey 不能等一切都好了才串起来"的矛盾：
+
+```
+journey 步骤："商户入驻"（名字）
+    │ ① 引用概念（只需名字存在）
+    ▼
+概念：merchant（名词 + 解释）          ← 跳板，先于一切存在
+    │ ② 概念长出结构
+    ▼
+表 / 页面 / 接口（引用概念名）
+    │ ③ 结构生成实现
+    ▼
+DDL / 路由 / 契约产物
+```
+
+- **蓝图态**：journey 引用概念名即可串线——概念不需要表、不需要页面，只需要名字存在。
+- **锚定态**：概念长出结构后，同一引用自然升级（引用依然有效，只是"对象"变厚了）。
+- **名字未长出结构的比例 = 细化度**：概念清单可统计"系统共 N 个概念，M 个已落表"——这是蓝图完成度的天然度量。
+
+## 身份契约
+
+概念名是**跨层身份**的唯一来源：
+
+- journey 说"商户入驻" → 引用 `merchant` 概念
+- 表说 `merchant.table.ts` → 引用 `merchant` 概念
+- 页面说"商户列表页" → 引用 `merchant` 概念
+- lint 检查字段 `mer_id` → 查概念的 `phrase`（词根 `mer`）
+
+所有维度说同一个词，指同一个概念；校验"引用的概念是否存在"是各维度的第一道闸门。
+
+## 校验草案
+
+| 规则 | 检查 |
+|------|------|
+| C1 | `name` 唯一、kebab-case；一文件一概念清单（`_concepts.ts` 专用名） |
+| C2 | `description` 必填（经典段落，非空） |
+| C3 | `phrase` 引用必须指向 `_dictionary.ts` 中已定义的短语条目 |
+| C4 | 下游引用（journey / table / PageFlow / DTO）引用的概念必须存在于 `_concepts.ts` |
+| C5 | 概念引用词根时，词根必须与该概念的中文语义一致（人工评审裁决） |
+
+## 消费者（未来）
+
+| 消费者 | 用途 |
+|--------|------|
+| journey（蓝图/旅程） | 步骤引用概念名——跨 app 业务线的身份锚点 |
+| table.ts | 表归属概念（现有 `phrase` 链接的上一级） |
+| PageFlow | 页面归属概念 |
+| lint | 跨层身份校验（C4） |
+| 文档/评审 | 概念清单渲染为术语表（markdown） |

package/docs/table.md

@@ -131,47 +131,47 @@ export const audit = defineTable('audit', {
 
 > **外键是逻辑作用**：`foreignKeys` 用于定义期命名强校验与关系表达，**DDL 默认不渲染物理 FOREIGN KEY 约束**（`pylonts gen sql init` 不传 `generateForeignKeys`）。数据完整性由 Service/DAO 层保证；如需物理约束，调用 `buildCreateTableSql(schema, { generateForeignKeys: true })`。
 
-## 扩展表（extends）
-
-扩展表表示“本表是某张根表的延伸”：主键与根表主键同义、类型一致，生命周期跟随根表（创建 / 保存 / 删除一起做）。除这两条外，扩展表与普通表完全一样，可以有索引、外键、被其他表引用等。
-
-### 定义
-
-```ts
-// order 根表
-export const order = defineTable('order', {
-  ...
-  primaryKey: id,
-});
-
-// order_address 是 order 的扩展表
-const addressId = stringField({ maxLength: 32 }); // 与 order.id 同类型
-
-export const orderAddress = defineTable('order_address', {
-  extends: order,          // 声明本表是 order 的扩展
-  primaryKey: addressId,   // 主键与根主键同义
-  columns: {
-    id: addressId,
-    receiver_name: stringField({ label: '收货人', maxLength: 32, optional: false }),
-    ...
-  },
-});
-```
-
-### 规则
-
-- 扩展表的主键与根表主键同义，类型必须一致；
-- 根表不能是扩展表；
-- 扩展表不能再 `extends`（禁止链式延伸）；
-- 一个根表可以有多个扩展表；
-- 除主键和生命周期外，扩展表与普通表完全一样：可以有普通外键、索引、枚举等，也可被其他表引用；
-- 扩展表不需要像普通外键那样命名 `{phrase}_{field}`，也不需要显式声明 `foreignKeys` 来表达与根的关系，`extends` 本身就是关系。
-
-### 与聚合的关系
-
-- `members: { items: [orderItem] }`：数组 → 普通表 → 一对多；
-- `members: { address: orderAddress }`：非数组 → 扩展表 → 一对一。
-
+## 扩展表（extends）
+
+扩展表表示“本表是某张根表的延伸”：主键与根表主键同义、类型一致，生命周期跟随根表（创建 / 保存 / 删除一起做）。除这两条外，扩展表与普通表完全一样，可以有索引、外键、被其他表引用等。
+
+### 定义
+
+```ts
+// order 根表
+export const order = defineTable('order', {
+  ...
+  primaryKey: id,
+});
+
+// order_address 是 order 的扩展表
+const addressId = stringField({ maxLength: 32 }); // 与 order.id 同类型
+
+export const orderAddress = defineTable('order_address', {
+  extends: order,          // 声明本表是 order 的扩展
+  primaryKey: addressId,   // 主键与根主键同义
+  columns: {
+    id: addressId,
+    receiver_name: stringField({ label: '收货人', maxLength: 32, optional: false }),
+    ...
+  },
+});
+```
+
+### 规则
+
+- 扩展表的主键与根表主键同义，类型必须一致；
+- 根表不能是扩展表；
+- 扩展表不能再 `extends`（禁止链式延伸）；
+- 一个根表可以有多个扩展表；
+- 除主键和生命周期外，扩展表与普通表完全一样：可以有普通外键、索引、枚举等，也可被其他表引用；
+- 扩展表不需要像普通外键那样命名 `{phrase}_{field}`，也不需要显式声明 `foreignKeys` 来表达与根的关系，`extends` 本身就是关系。
+
+### 与聚合的关系
+
+- `members: { items: [orderItem] }`：数组 → 普通表 → 一对多；
+- `members: { address: orderAddress }`：非数组 → 扩展表 → 一对一。
+
 ## 生成 SQL
 
 见 [driver.md](./driver.md)。

package/docs/task.md

@@ -0,0 +1,81 @@
+# 任务 (Task)
+
+Task 是**定时任务（定时器）**的定义——**action 闭包的第二成员**（action = controller | task | third callback，无第四种）。
+
+```
+action = trigger =
+  ① controller       —— 前端/外部调用的 RPC 入口
+  ② task             —— 定时器（cron 驱动）：到期退款、结算、提现、报表、关单
+  ③ third callback   —— 外部系统主动回调
+```
+
+- **Task 只表示定时器**（cron 驱动）。异步/事件驱动的操作归 event 体系（EventObserver / EventNotifier，待设计），不属于 task。
+- Task 是**契约**（名字 + cron + 做什么），不声明状态变化——状态变化由 journey 步骤表达。
+- Task 实现（扫描逻辑、幂等）在实现层（如 pylon-flow step）。
+
+## 定义
+
+```ts
+// task_schema/auto-refund.task.ts
+export const AutoRefundTask = defineTask({
+  name: 'AutoRefundTask',
+  label: '到期自动退款',
+  cron: '0 3 * * *',
+  description: '扫描已锁定券码 + auto_refund + valid_to<now → 按订单发起全额退款',
+});
+```
+
+## 字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `name` | string | ✅ | `XxTask`（PascalCase + `Task` 后缀） |
+| `label` | string | ✅ | 中文名 |
+| `cron` | string | ✅ | 定时表达式（系统怎么触发的契约，一处看全） |
+| `description` | string | 可选 | 做什么（叙述） |
+
+## 命名与存储规则
+
+| 约定 | 规则 | 例子 |
+|---|---|---|
+| `name` | PascalCase + `Task` 后缀 | `AutoRefundTask` |
+| 导出符号 | = name | `export const AutoRefundTask` |
+| 文件位置 | `task_schema/`（项目根，与 schema/ 并列） | `task_schema/auto-refund.task.ts` |
+| 文件名 | name 去 `Task` 后缀转 kebab + `.task.ts` | `auto-refund.task.ts` |
+| 一文件一 task | loader 机器校验（仿 loadDaos/loadEntities） | 多导出/零导出报错 |
+
+## 校验
+
+- 运行时（`defineTask`）：
+  - `name` 必须以 `Task` 结尾，否则抛错
+  - `cron` 必填（task 是定时器），否则抛错
+- 存储（`loadTasks`）：
+  - 唯一合法目录是 `task_schema/` 根（一级）
+  - **导出符号 == schema name**，否则抛错
+  - 文件名 = name 去 `Task` 后缀转 kebab + `.task.ts`，否则抛错
+  - 一文件一 task（多导出/零导出报错）
+
+## 作为 action 引用
+
+Task 与 controller、third callback 并列，是 action 闭包成员，被状态迁移与 journey 步骤引用：
+
+```ts
+// journey 步骤
+{ action: AutoRefundTask, host: api, text: '到期自动退款' }
+```
+
+lint 校验：`action` 引用必须是三类之一（controller | task | third callback）且引用存在。
+
+## 与 pylon-flow 的关系
+
+pylon-flow 的 step 函数是 task 的实现形态之一：
+
+```ts
+// flow/flows/settlement.flow.ts（api driver）
+export async function autoRefund(flow, deps) { ... }   // 实现 AutoRefundTask
+export default { autoRefund };
+```
+
+- **task schema = 契约**（名字/cron/做什么）
+- **pylon-flow step = 实现**（怎么跑）
+- 对账：task schema 的 name ↔ pylon-flow 的 step names——"定时任务已声明但没实现"可 lint

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonts/dsl",
-  "version": "1.1.21",
+  "version": "1.1.22",
   "description": "Schema definition DSL with drivers: MySQL DDL, TS enum, TypeBox schema codegen.",
   "type": "module",
   "main": "dist/index.js",

package/src/action.ts

@@ -1,52 +1,87 @@
-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 function defineAction(name: string, description?: string): ActionSchema {
-  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 ActionSchema {
-  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 ActionSchema {
-  type: 'setData';
-  call: CallAction;
-  field: DtoField;
-}
-
-export function setData(call: CallAction, field: DtoField): SetDataAction {
-  return { name: 'setData', type: 'setData', call, field };
-}
+import { SchemaBase } from './dsl.js';
+import type { ControllerMethodSchema } from './controller.js';
+import type { ThirdServiceMethodSchema, ThirdCallbackSchema } from './third-service.js';
+import type { TaskSchema } from './task.js';
+import type { TableSchema } from './db.js';
+import type { PageSchema } from './page.js';
+
+// Cross-domain actions: what happens along a business line (journey).
+// Distinguished from PageActionSchema (what a user can do ON a page):
+// an Action is one beat of a journey — a page visit, an API call, a
+// third-party invocation, a database write, or a task trigger.
+//
+// Every action is `type + properties + data`: the type picks the property
+// set (page for page visits, method for controller/third, table for db,
+// task for task triggers), and `data` is the input of that beat. No further
+// classification — page/controller/third/db/task are all actions, only their
+// properties differ.
+
+/** A beat of a journey: type + properties + input data. */
+export interface ActionSchema extends SchemaBase {
+  type: 'page' | 'controller' | 'third' | 'db' | 'task';
+  /** Input data of this beat (blueprint: names first, refined to refs later). */
+  data?: Record<string, unknown>;
+}
+
+/** Visit a page — `data` present means fill/submit a form, absent means pure view. */
+export interface PageAction extends ActionSchema {
+  type: 'page';
+  /** Target page (PageFlow node). */
+  page: PageSchema;
+  /** Page url/path (e.g. '/bd/apply'). */
+  url: string;
+}
+
+/** Call a backend controller method. */
+export interface ControllerAction extends ActionSchema {
+  type: 'controller';
+  /** The controller method invoked (shared instance). */
+  method: ControllerMethodSchema;
+}
+
+/** Invoke a third-party service method or receive its callback. */
+export interface ThirdAction extends ActionSchema {
+  type: 'third';
+  /** The third-party method invoked (outbound). */
+  method?: ThirdServiceMethodSchema;
+  /** The third-party callback received (inbound) — mutually exclusive with method. */
+  callback?: ThirdCallbackSchema;
+  /** Wait for the async callback (inbound) before the journey continues. */
+  async?: boolean;
+}
+
+/** Write to a database table. */
+export interface DbAction extends ActionSchema {
+  type: 'db';
+  /** The table written (shared instance). */
+  table: TableSchema;
+  /** Write operation: insert | update | delete. */
+  op: 'insert' | 'update' | 'delete';
+}
+
+/** Trigger a system task (scheduled or async). */
+export interface TaskAction extends ActionSchema {
+  type: 'task';
+  /** The task triggered (shared instance). */
+  task: TaskSchema;
+}
+
+/** Builder for a journey action. */
+export const action = {
+  page(options: { page: PageSchema; url: string; data?: Record<string, unknown>; description?: string }): PageAction {
+    return { name: options.page.name, type: 'page', page: options.page, url: options.url, data: options.data, description: options.description };
+  },
+  controller(options: { method: ControllerMethodSchema; data?: Record<string, unknown>; description?: string }): ControllerAction {
+    return { name: options.method.name, type: 'controller', method: options.method, data: options.data, description: options.description };
+  },
+  third(options: { method?: ThirdServiceMethodSchema; callback?: ThirdCallbackSchema; data?: Record<string, unknown>; async?: boolean; description?: string }): ThirdAction {
+    const name = options.method?.name ?? options.callback?.name ?? 'third';
+    return { name, type: 'third', method: options.method, callback: options.callback, data: options.data, async: options.async, description: options.description };
+  },
+  db(options: { table: TableSchema; op: 'insert' | 'update' | 'delete'; data?: Record<string, unknown>; description?: string }): DbAction {
+    return { name: options.table.name, type: 'db', table: options.table, op: options.op, data: options.data, description: options.description };
+  },
+  task(options: { task: TaskSchema; data?: Record<string, unknown>; description?: string }): TaskAction {
+    return { name: options.task.name, type: 'task', task: options.task, data: options.data, description: options.description };
+  },
+};

package/src/aggregate.ts

@@ -1,95 +1,95 @@
-import type { SchemaBase } from './dsl.js';
-import type { TableSchema } from './db.js';
-
-// Aggregate declaration: groups multiple tables into one domain concept with
-// a root table, member tables, cross-member invariants and inter-aggregate
-// reference rules. This turns "multi-table consistency" from a convention
-// (hand-written in flows) into a constraint (lintable, codegen-able).
-//
-// Members are intentionally minimal:
-//   members: { items: [orderItem] }   -> array  = 1:N (normal table)
-//   members: { address: orderAddress } -> single = 1:1 (extension table;
-//                                          designed but not implemented yet)
-
-/** Member table(s) keyed by role name. Array = 1:N; non-array = 1:1 extension. */
-export type AggregateMember = TableSchema | TableSchema[];
-
-/** A cross-member invariant, checked by generated repository code. */
-export interface AggregateInvariant {
-  name: string;
-  /** 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 function defineAggregate(options: {
-  root: TableSchema;
-  members?: Record<string, AggregateMember>;
-  invariants?: AggregateInvariant[];
-  references?: Record<string, string>;
-  description?: string;
-}): DomainAggregate {
-  const schema: DomainAggregate = {
-    type: 'aggregate',
-    name: options.root.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 '${schema.name}': root table '${options.root.name}' must have a primary key`);
-  }
-
-  const rootPkRefs = Array.isArray(options.root.primaryKey)
-    ? options.root.primaryKey
-    : [options.root.primaryKey];
-
-  // Each member must attach to the root. Array members are normal 1:N tables
-  // and must have exactly one FK referencing the root. Non-array (1:1 extension)
-  // members are designed but not implemented yet.
-  for (const [role, member] of Object.entries(schema.members)) {
-    if (Array.isArray(member)) {
-      if (member.length !== 1) {
-        throw new Error(
-          `aggregate '${schema.name}': member '${role}' array must contain exactly one table schema`,
-        );
-      }
-      const table = member[0];
-      const fks = Object.values(table.foreignKeys ?? {}).filter((fk) => {
-        const refs = Array.isArray(fk.references) ? fk.references : [fk.references];
-        return refs.length === rootPkRefs.length && refs.every((r) => rootPkRefs.includes(r));
-      });
-      if (fks.length === 0) {
-        throw new Error(
-          `aggregate '${schema.name}': member '${role}' table '${table.name}' has no foreign key referencing root '${options.root.name}' — declare one in the table's foreignKeys`,
-        );
-      }
-      if (fks.length > 1) {
-        throw new Error(
-          `aggregate '${schema.name}': member '${role}' table '${table.name}' has ${fks.length} foreign keys referencing root '${options.root.name}' — reduce to one FK for minimal aggregate declarations`,
-        );
-      }
-    } else {
-      throw new Error(
-        `aggregate '${schema.name}': member '${role}' is a non-array table — 1:1 extension tables are designed but not implemented yet; use an array for 1:N members`,
-      );
-    }
-  }
-
-  return schema;
+import type { SchemaBase } from './dsl.js';
+import type { TableSchema } from './db.js';
+
+// Aggregate declaration: groups multiple tables into one domain concept with
+// a root table, member tables, cross-member invariants and inter-aggregate
+// reference rules. This turns "multi-table consistency" from a convention
+// (hand-written in flows) into a constraint (lintable, codegen-able).
+//
+// Members are intentionally minimal:
+//   members: { items: [orderItem] }   -> array  = 1:N (normal table)
+//   members: { address: orderAddress } -> single = 1:1 (extension table;
+//                                          designed but not implemented yet)
+
+/** Member table(s) keyed by role name. Array = 1:N; non-array = 1:1 extension. */
+export type AggregateMember = TableSchema | TableSchema[];
+
+/** A cross-member invariant, checked by generated repository code. */
+export interface AggregateInvariant {
+  name: string;
+  /** 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 function defineAggregate(options: {
+  root: TableSchema;
+  members?: Record<string, AggregateMember>;
+  invariants?: AggregateInvariant[];
+  references?: Record<string, string>;
+  description?: string;
+}): DomainAggregate {
+  const schema: DomainAggregate = {
+    type: 'aggregate',
+    name: options.root.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 '${schema.name}': root table '${options.root.name}' must have a primary key`);
+  }
+
+  const rootPkRefs = Array.isArray(options.root.primaryKey)
+    ? options.root.primaryKey
+    : [options.root.primaryKey];
+
+  // Each member must attach to the root. Array members are normal 1:N tables
+  // and must have exactly one FK referencing the root. Non-array (1:1 extension)
+  // members are designed but not implemented yet.
+  for (const [role, member] of Object.entries(schema.members)) {
+    if (Array.isArray(member)) {
+      if (member.length !== 1) {
+        throw new Error(
+          `aggregate '${schema.name}': member '${role}' array must contain exactly one table schema`,
+        );
+      }
+      const table = member[0];
+      const fks = Object.values(table.foreignKeys ?? {}).filter((fk) => {
+        const refs = Array.isArray(fk.references) ? fk.references : [fk.references];
+        return refs.length === rootPkRefs.length && refs.every((r) => rootPkRefs.includes(r));
+      });
+      if (fks.length === 0) {
+        throw new Error(
+          `aggregate '${schema.name}': member '${role}' table '${table.name}' has no foreign key referencing root '${options.root.name}' — declare one in the table's foreignKeys`,
+        );
+      }
+      if (fks.length > 1) {
+        throw new Error(
+          `aggregate '${schema.name}': member '${role}' table '${table.name}' has ${fks.length} foreign keys referencing root '${options.root.name}' — reduce to one FK for minimal aggregate declarations`,
+        );
+      }
+    } else {
+      throw new Error(
+        `aggregate '${schema.name}': member '${role}' is a non-array table — 1:1 extension tables are designed but not implemented yet; use an array for 1:N members`,
+      );
+    }
+  }
+
+  return schema;
 }

package/src/component.ts

@@ -1,14 +1,14 @@
 import type { SchemaBase } from './dsl.js';
 import type { RefSchema } from './ref.js';
-import type { ActionSchema } from './action.js';
+import type { PageActionSchema } from './page-action.js';
 import type { EventDataSchema } from './event.js';
 
 /** A component event trigger declaration. */
 export interface TriggerSchema extends SchemaBase {
   /** Data the event carries (e.g. e.detail). */
   eventData?: EventDataSchema;
-  /** Actions that fire when the event occurs. */
-  actions?: ActionSchema[];
+  /** Page actions that fire when the event occurs. */
+  actions?: PageActionSchema[];
 }
 
 /** A UI component declaration — a virtual schema that describes props and