@yss123/cage-kernel 0.0.0-stage → 0.2.0

package/dist/primitives/constraints.d.ts

@@ -0,0 +1,36 @@
+import type { CapabilityParams, Ctx, MaybePromise } from '../types.js';
+export type ConstraintResult = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+export declare const ok: () => ConstraintResult;
+export declare const violation: (message: string) => ConstraintResult;
+export interface ConstraintMeta {
+    /** 正在执行的命令的能力点，例如 PurchaseOrder.approve */
+    capability: string;
+    /** 取某人的能力（额度类约束用） */
+    capabilitiesOf(userId: string): Promise<Map<string, CapabilityParams>>;
+    /** 按当前主体的范围读取一条记录（框架内置约束用，例如防提权检查要看被分配的角色） */
+    load(aggregate: string, id: string): Promise<Record<string, any> | null>;
+    /** 能力目录 */
+    catalog(): string[];
+}
+export interface Constraint<_A = any> {
+    /** 约束名，出现在本体图和报错里 */
+    readonly name: string;
+    /** 用到的字段，抽取器据此画 uses 边，影响分析能找到它 */
+    readonly fields?: readonly string[];
+    readonly check: (current: any, ctx: Ctx, input: any, meta: ConstraintMeta) => MaybePromise<ConstraintResult>;
+}
+/** 职责分离：操作人（或系统身份代表的真人）不能是该字段记录的人，例如提单人不能审批 */
+export declare const sod: {
+    notSameAs(field: string): Constraint;
+};
+/** 额度：字段值不得超过操作人在该能力点上的 ceiling 参数；多角色取最大值 */
+export declare function ceiling(field: string, param?: string): Constraint;
+/** 二次认证：最近 maxAgeSec 秒内完成过二次认证 */
+export declare function stepUp(maxAgeSec?: number): Constraint;
+/** 自定义约束（仍然是一个纯函数，必须写清楚用到哪些字段） */
+export declare function constraint(name: string, fields: string[], check: Constraint['check']): Constraint;

package/dist/primitives/constraints.js

@@ -0,0 +1,41 @@
+export const ok = () => ({ ok: true });
+export const violation = (message) => ({ ok: false, message });
+/** 职责分离：操作人（或系统身份代表的真人）不能是该字段记录的人，例如提单人不能审批 */
+export const sod = {
+    notSameAs(field) {
+        return Object.freeze({
+            name: `sod.notSameAs(${field})`,
+            fields: [field],
+            check: (cur, ctx) => {
+                const who = ctx.onBehalfOf ?? ctx.userId;
+                return who && cur[field] === who ? violation(`操作人不能是 ${field} 记录的人（职责分离）`) : ok();
+            },
+        });
+    },
+};
+/** 额度：字段值不得超过操作人在该能力点上的 ceiling 参数；多角色取最大值 */
+export function ceiling(field, param = 'ceiling') {
+    return Object.freeze({
+        name: `ceiling(${field})`,
+        fields: [field],
+        check: async (cur, ctx, _input, meta) => {
+            const caps = ctx.onBehalfOf ? await meta.capabilitiesOf(ctx.onBehalfOf) : ctx.capabilities;
+            const limit = caps.get(meta.capability)?.[param];
+            if (limit === undefined || limit === null)
+                return violation(`没有为 ${meta.capability} 设置额度 ${param}`);
+            return Number(cur[field]) <= Number(limit) ? ok() : violation(`${field}=${cur[field]} 超过额度 ${limit}`);
+        },
+    });
+}
+/** 二次认证：最近 maxAgeSec 秒内完成过二次认证 */
+export function stepUp(maxAgeSec = 300) {
+    return Object.freeze({
+        name: 'stepUp',
+        check: (_cur, ctx) => ctx.stepUpAt && Date.now() - ctx.stepUpAt <= maxAgeSec * 1000 ? ok() : violation('需要二次认证'),
+    });
+}
+/** 自定义约束（仍然是一个纯函数，必须写清楚用到哪些字段） */
+export function constraint(name, fields, check) {
+    return Object.freeze({ name, fields, check });
+}
+//# sourceMappingURL=constraints.js.map

package/dist/primitives/constraints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constraints.js","sourceRoot":"","sources":["../../src/primitives/constraints.ts"],"names":[],"mappings":"AAKA,MAAM,CAAC,MAAM,EAAE,GAAG,GAAqB,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;AACzD,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,OAAe,EAAoB,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;AAqBzF,+CAA+C;AAC/C,MAAM,CAAC,MAAM,GAAG,GAAG;IACjB,SAAS,CAAC,KAAa;QACrB,OAAO,MAAM,CAAC,MAAM,CAAC;YACnB,IAAI,EAAE,iBAAiB,KAAK,GAAG;YAC/B,MAAM,EAAE,CAAC,KAAK,CAAC;YACf,KAAK,EAAE,CAAC,GAAQ,EAAE,GAAQ,EAAE,EAAE;gBAC5B,MAAM,GAAG,GAAG,GAAG,CAAC,UAAU,IAAI,GAAG,CAAC,MAAM,CAAC;gBACzC,OAAO,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,UAAU,KAAK,aAAa,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;YACpF,CAAC;SACF,CAAC,CAAC;IACL,CAAC;CACF,CAAC;AAEF,8CAA8C;AAC9C,MAAM,UAAU,OAAO,CAAC,KAAa,EAAE,KAAK,GAAG,SAAS;IACtD,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,IAAI,EAAE,WAAW,KAAK,GAAG;QACzB,MAAM,EAAE,CAAC,KAAK,CAAC;QACf,KAAK,EAAE,KAAK,EAAE,GAAQ,EAAE,GAAQ,EAAE,MAAW,EAAE,IAAoB,EAAE,EAAE;YACrE,MAAM,IAAI,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC;YAC3F,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;YACjD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;gBAAE,OAAO,SAAS,CAAC,OAAO,IAAI,CAAC,UAAU,SAAS,KAAK,EAAE,CAAC,CAAC;YACpG,OAAO,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,KAAK,IAAI,GAAG,CAAC,KAAK,CAAC,SAAS,KAAK,EAAE,CAAC,CAAC;QACxG,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED,kCAAkC;AAClC,MAAM,UAAU,MAAM,CAAC,SAAS,GAAG,GAAG;IACpC,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,IAAI,EAAE,QAAQ;QACd,KAAK,EAAE,CAAC,IAAS,EAAE,GAAQ,EAAE,EAAE,CAC7B,GAAG,CAAC,QAAQ,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,CAAC,QAAQ,IAAI,SAAS,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC;KAC7F,CAAC,CAAC;AACL,CAAC;AAED,kCAAkC;AAClC,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,MAAgB,EAAE,KAA0B;IACnF,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;AAChD,CAAC"}

package/dist/primitives/event.d.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import { EVENT } from '../brands.js';
+import { type FieldValues, type Fields } from './fields.js';
+export interface Event<N extends string = string, F extends Fields = Fields> {
+    readonly [EVENT]: true;
+    readonly name: N;
+    readonly fields: F;
+    readonly schema: z.ZodObject<any>;
+    readonly description?: string;
+}
+export type AnyEvent = Event<string, any>;
+export type PayloadOf<E> = E extends Event<any, infer F> ? FieldValues<F> : never;
+export declare function event<const N extends string, F extends Fields>(name: N, fields: F, opts?: {
+    description?: string;
+}): Event<N, F>;
+export declare function isEvent(v: unknown): v is AnyEvent;
+/** 显式指定载荷怎么从快照得到：emits: [emit(OrderApproved, (o) => ({ orderId: o.id, items: o.items }))] */
+export interface EmitSpec<E extends AnyEvent = AnyEvent> {
+    readonly event: E;
+    /** snapshot：写入后的快照；input：命令输入；previous：写入前的快照（新建时为 null） */
+    readonly map?: (snapshot: any, input: any, previous: any) => PayloadOf<E>;
+}
+export declare function emit<E extends AnyEvent>(ev: E, map: (snapshot: any, input: any, previous: any) => PayloadOf<E>): EmitSpec<E>;
+export declare function toEmitSpec(e: AnyEvent | EmitSpec): EmitSpec;
+/**
+ * 默认载荷映射规则（没有写 emit(...) 时）：
+ *   1. 载荷字段名在快照里存在 → 取快照的值
+ *   2. 载荷字段名以 Id 结尾、快照里没有同名字段 → 取聚合自己的 id（例如 orderId）
+ *   3. 其他 → 取命令输入里的同名值
+ */
+export declare function defaultPayload(ev: AnyEvent, snapshot: Record<string, unknown>, input: Record<string, unknown>): Record<string, unknown>;

package/dist/primitives/event.js

@@ -0,0 +1,44 @@
+import { EVENT } from '../brands.js';
+import { declError } from '../errors.js';
+import { isRelation, objectSchema } from './fields.js';
+export function event(name, fields, opts) {
+    if (!/^[A-Z][A-Za-z0-9]*$/.test(name))
+        throw declError('CAGE-NAME-003', `事件名 ${name} 必须是大驼峰`);
+    if (Object.values(fields).some(isRelation))
+        throw declError('CAGE-REL-001', '事件载荷不声明持久化关系；传递 ID 数组请使用 list(id())');
+    return Object.freeze({
+        [EVENT]: true,
+        name,
+        fields: Object.freeze({ ...fields }),
+        schema: objectSchema(fields),
+        description: opts?.description,
+    });
+}
+export function isEvent(v) {
+    return !!v && typeof v === 'object' && v[EVENT] === true;
+}
+export function emit(ev, map) {
+    return Object.freeze({ event: ev, map });
+}
+export function toEmitSpec(e) {
+    return isEvent(e) ? { event: e } : e;
+}
+/**
+ * 默认载荷映射规则（没有写 emit(...) 时）：
+ *   1. 载荷字段名在快照里存在 → 取快照的值
+ *   2. 载荷字段名以 Id 结尾、快照里没有同名字段 → 取聚合自己的 id（例如 orderId）
+ *   3. 其他 → 取命令输入里的同名值
+ */
+export function defaultPayload(ev, snapshot, input) {
+    const out = {};
+    for (const k of Object.keys(ev.fields)) {
+        if (k in snapshot)
+            out[k] = snapshot[k];
+        else if (k.endsWith('Id'))
+            out[k] = snapshot.id;
+        else if (input && k in input)
+            out[k] = input[k];
+    }
+    return out;
+}
+//# sourceMappingURL=event.js.map

package/dist/primitives/event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.js","sourceRoot":"","sources":["../../src/primitives/event.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAiC,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAatF,MAAM,UAAU,KAAK,CAA2C,IAAO,EAAE,MAAS,EAAE,IAA+B;IACjH,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,MAAM,SAAS,CAAC,eAAe,EAAE,OAAO,IAAI,SAAS,CAAC,CAAC;IAC9F,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC;QAAE,MAAM,SAAS,CAAC,cAAc,EAAE,qCAAqC,CAAC,CAAC;IACnH,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,CAAC,KAAK,CAAC,EAAE,IAAa;QACtB,IAAI;QACJ,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,MAAM,EAAE,CAAC;QACpC,MAAM,EAAE,YAAY,CAAC,MAAM,CAAC;QAC5B,WAAW,EAAE,IAAI,EAAE,WAAW;KAC/B,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,CAAU;IAChC,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAK,CAAS,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC;AACpE,CAAC;AASD,MAAM,UAAU,IAAI,CAAqB,EAAK,EAAE,GAA+D;IAC7G,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,CAAsB;IAC/C,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AACvC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,EAAY,EAAE,QAAiC,EAAE,KAA8B;IAC5G,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC;QACvC,IAAI,CAAC,IAAI,QAAQ;YAAE,GAAG,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;aACnC,IAAI,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,GAAG,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,EAAE,CAAC;aAC3C,IAAI,KAAK,IAAI,CAAC,IAAI,KAAK;YAAE,GAAG,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/primitives/fields.d.ts

@@ -0,0 +1,127 @@
+import { z } from 'zod';
+/** 敏感种类是封闭集合，每种在内核里有一个掩码函数（见 db/ddl.ts 的 sys.mask）。 */
+export type SensitiveKind = 'phone' | 'idCard' | 'bankCard' | 'email' | 'name' | 'address';
+export declare const SENSITIVE_KINDS: readonly SensitiveKind[];
+export type FieldKind = 'id' | 'ref' | 'text' | 'int' | 'number' | 'money' | 'date' | 'datetime' | 'bool' | 'enum' | 'list' | 'hasMany' | 'manyToMany';
+export interface FieldMeta {
+    readonly kind: FieldKind;
+    readonly sql: string;
+    readonly isOptional: boolean;
+    readonly sensitiveKind?: SensitiveKind;
+    /** 引用的聚合名，抽取器据此画引用边，生成外键 */
+    readonly ref?: string;
+    /** hasMany 的反向外键。关系字段不占主表列，sql 为空字符串。 */
+    readonly mappedBy?: string;
+    readonly isUnique?: boolean;
+    /** 隐藏字段：不进入安全视图、审计、事件、前端契约（例如密码哈希） */
+    readonly isHidden?: boolean;
+    /** 口径说明：变化会出现在影响分析里 */
+    readonly description?: string;
+    /** enum 的取值 */
+    readonly values?: readonly string[];
+    /** list 的元素结构；标量数组时为 { item } */
+    readonly shape?: Readonly<Record<string, AnyField>>;
+    /** 文本最大长度 */
+    readonly max?: number;
+}
+/**
+ * 字段定义。方法都返回新对象（不可变），可以链式调用：
+ *   text(50).sensitive('phone').optional()
+ */
+export declare class Field<T extends z.ZodType = z.ZodType, Opt extends boolean = boolean, K extends FieldKind = FieldKind> implements FieldMeta {
+    readonly kind: K;
+    readonly sql: string;
+    readonly isOptional: boolean;
+    readonly sensitiveKind?: SensitiveKind;
+    readonly ref?: string;
+    readonly mappedBy?: string;
+    readonly isUnique?: boolean;
+    readonly isHidden?: boolean;
+    readonly description?: string;
+    readonly values?: readonly string[];
+    readonly shape?: Readonly<Record<string, AnyField>>;
+    readonly max?: number;
+    /** 基础校验（不含可空） */
+    readonly base: T;
+    /** 仅用于类型推导 */
+    readonly __opt?: Opt;
+    constructor(base: T, meta: Omit<FieldMeta, 'kind' | 'isOptional'> & {
+        kind: K;
+        isOptional?: boolean;
+    });
+    meta(): FieldMeta & {
+        kind: K;
+    };
+    private with;
+    /** 校验规则（前后端共用）；可选字段允许 null 与缺省 */
+    get zod(): z.ZodType;
+    /** 可选字段：列可空，输入可以不填 */
+    optional(): Field<T, true, K>;
+    /** 敏感字段：读侧按种类掩码，持有 聚合.unmask.种类 能力才能看明文 */
+    sensitive(kind: SensitiveKind): Field<T, Opt, K>;
+    /** 唯一约束（租户内） */
+    unique(): Field<T, Opt, K>;
+    /** 隐藏字段：不出现在读侧、审计、事件和前端契约 */
+    hidden(): Field<T, Opt, K>;
+    /** 口径说明 */
+    describe(text: string): Field<T, Opt, K>;
+}
+export type AnyField = Field<z.ZodType, boolean>;
+export type Fields = Record<string, AnyField>;
+/** 字段的 TypeScript 值类型 */
+export type ValueOf<F> = F extends Field<infer T, infer O, any> ? ([O] extends [true] ? z.output<T> | null : z.output<T>) : never;
+export type FieldValues<F extends Fields> = {
+    -readonly [K in keyof F as F[K]['kind'] extends 'hasMany' ? never : K]: ValueOf<F[K]>;
+};
+/** 文本，默认最长 500 字 */
+export declare const text: (max?: number) => Field<z.ZodString, false, "text">;
+/** 整数 */
+export declare const int: () => Field<z.ZodNumber, false, "int">;
+/** 数值（双精度）。金额请用 money() */
+export declare const number: () => Field<z.ZodNumber, false, "number">;
+/** 金额：用字符串传输，避免浮点误差 */
+export declare const money: () => Field<z.ZodString, false, "money">;
+/** 主键或外键 */
+export declare const id: () => Field<z.ZodString, false, "id">;
+/** 日期 YYYY-MM-DD */
+export declare const date: () => Field<z.ZodString, false, "date">;
+/** 时间戳（ISO 8601） */
+export declare const datetime: () => Field<z.ZodString, false, "datetime">;
+/** 布尔 */
+export declare const bool: () => Field<z.ZodBoolean, false, "bool">;
+/** 枚举：enumOf('A', 'B') */
+export declare function enumOf<const V extends readonly [string, ...string[]]>(...values: V): Field<z.ZodEnum<{ [k_1 in V[number]]: k_1; } extends infer T ? { [k in keyof T]: T[k]; } : never>, false, "enum">;
+/** 引用另一个聚合：本质是 uuid，额外记下引用目标。可传聚合对象或聚合名（解决循环导入）。 */
+export declare function ref(to: {
+    name: string;
+} | string): Field<z.ZodString, false, "ref">;
+/** 一对多反查：实际外键在目标聚合上，不创建另一份关系或可写数组。 */
+export declare function hasMany(to: {
+    name: string;
+} | string, options: {
+    mappedBy: string;
+    description?: string;
+}): Field<z.ZodArray<z.ZodString>, false, "hasMany">;
+/** 多对多：字段与普通属性一处声明，中间表由框架生成；业务命令返回目标 ID 数组。 */
+export declare function manyToMany(to: {
+    name: string;
+} | string, options?: {
+    description?: string;
+}): Field<z.ZodArray<z.ZodString>, false, "manyToMany">;
+export declare const isRelation: (field: FieldMeta) => boolean;
+type ShapeZod<S extends Fields> = {
+    [K in keyof S]: S[K] extends Field<infer T, infer O> ? ([O] extends [true] ? z.ZodOptional<z.ZodNullable<T>> : T) : never;
+};
+/**
+ * 明细行，存为 jsonb：
+ *   list({ sku: text(), qty: int() })   对象数组
+ *   list(id())                          标量数组
+ */
+export declare function list<T extends z.ZodType>(item: Field<T, false>): Field<z.ZodArray<T>, false>;
+export declare function list<S extends Fields>(shape: S): Field<z.ZodArray<z.ZodObject<ShapeZod<S>>>, false>;
+export declare function isField(v: unknown): v is AnyField;
+/** 把一组字段拼成对象 schema */
+export declare function objectSchema(fields: Fields): z.ZodObject<any>;
+/** 结构不固定的 JSON 对象（例如能力点参数），存为 jsonb。业务字段请优先用 list 或具体类型。 */
+export declare const json: () => Field<z.ZodRecord<z.ZodString, z.ZodUnknown>, false, "list">;
+export {};

package/dist/primitives/fields.js

@@ -0,0 +1,151 @@
+// 字段原语：每个字段同时携带校验（Zod）、存储（SQL 列类型）和元数据（敏感种类、引用目标）。
+import { z } from 'zod';
+import { declError } from '../errors.js';
+export const SENSITIVE_KINDS = ['phone', 'idCard', 'bankCard', 'email', 'name', 'address'];
+/**
+ * 字段定义。方法都返回新对象（不可变），可以链式调用：
+ *   text(50).sensitive('phone').optional()
+ */
+export class Field {
+    kind;
+    sql;
+    isOptional;
+    sensitiveKind;
+    ref;
+    mappedBy;
+    isUnique;
+    isHidden;
+    description;
+    values;
+    shape;
+    max;
+    /** 基础校验（不含可空） */
+    base;
+    constructor(base, meta) {
+        this.base = base;
+        this.kind = meta.kind;
+        this.sql = meta.sql;
+        this.isOptional = meta.isOptional ?? false;
+        this.sensitiveKind = meta.sensitiveKind;
+        this.ref = meta.ref;
+        this.mappedBy = meta.mappedBy;
+        this.isUnique = meta.isUnique;
+        this.isHidden = meta.isHidden;
+        this.description = meta.description;
+        this.values = meta.values;
+        this.shape = meta.shape;
+        this.max = meta.max;
+        Object.freeze(this);
+    }
+    meta() {
+        return {
+            kind: this.kind, sql: this.sql, isOptional: this.isOptional, sensitiveKind: this.sensitiveKind, ref: this.ref,
+            isUnique: this.isUnique, isHidden: this.isHidden, description: this.description, values: this.values,
+            shape: this.shape, max: this.max,
+            mappedBy: this.mappedBy,
+        };
+    }
+    with(patch) {
+        return new Field(this.base, { ...this.meta(), ...patch });
+    }
+    /** 校验规则（前后端共用）；可选字段允许 null 与缺省 */
+    get zod() {
+        return this.isOptional ? this.base.nullable().optional() : this.base;
+    }
+    /** 可选字段：列可空，输入可以不填 */
+    optional() {
+        if (isRelation(this))
+            throw declError('CAGE-REL-001', '集合关系使用空集合表示没有关联，不支持 optional');
+        return this.with({ isOptional: true });
+    }
+    /** 敏感字段：读侧按种类掩码，持有 聚合.unmask.种类 能力才能看明文 */
+    sensitive(kind) {
+        if (isRelation(this))
+            throw declError('CAGE-REL-001', '关系字段不支持 sensitive；目标字段按目标聚合权限掩码');
+        if (!SENSITIVE_KINDS.includes(kind))
+            throw declError('CAGE-FIELD-001', `未知的敏感种类 ${kind}`);
+        return this.with({ sensitiveKind: kind });
+    }
+    /** 唯一约束（租户内） */
+    unique() {
+        if (isRelation(this))
+            throw declError('CAGE-REL-001', '集合关系自动保证关联对唯一，不支持单字段 unique');
+        return this.with({ isUnique: true });
+    }
+    /** 隐藏字段：不出现在读侧、审计、事件和前端契约 */
+    hidden() {
+        if (isRelation(this))
+            throw declError('CAGE-REL-001', '关系使用所属对象和目标对象权限，不支持 hidden 修饰');
+        return this.with({ isHidden: true });
+    }
+    /** 口径说明 */
+    describe(text) {
+        return this.with({ description: text });
+    }
+}
+// ---------- 字段构造函数 ----------
+function mk(base, meta) {
+    return new Field(base, meta);
+}
+/** 文本，默认最长 500 字 */
+export const text = (max = 500) => mk(z.string().max(max), { kind: 'text', sql: 'text', max });
+/** 整数 */
+export const int = () => mk(z.number().int(), { kind: 'int', sql: 'integer' });
+/** 数值（双精度）。金额请用 money() */
+export const number = () => mk(z.number(), { kind: 'number', sql: 'double precision' });
+/** 金额：用字符串传输，避免浮点误差 */
+export const money = () => mk(z.string().regex(/^-?\d+(\.\d{1,2})?$/, '金额格式应为最多两位小数的数字字符串'), { kind: 'money', sql: 'numeric(18,2)' });
+/** 主键或外键 */
+export const id = () => mk(z.string().uuid(), { kind: 'id', sql: 'uuid' });
+/** 日期 YYYY-MM-DD */
+export const date = () => mk(z.string().regex(/^\d{4}-\d{2}-\d{2}$/, '日期格式应为 YYYY-MM-DD'), { kind: 'date', sql: 'date' });
+/** 时间戳（ISO 8601） */
+export const datetime = () => mk(z.string().datetime({ offset: true }), { kind: 'datetime', sql: 'timestamptz' });
+/** 布尔 */
+export const bool = () => mk(z.boolean(), { kind: 'bool', sql: 'boolean' });
+/** 枚举：enumOf('A', 'B') */
+export function enumOf(...values) {
+    return mk(z.enum(values), { kind: 'enum', sql: 'text', values });
+}
+/** 引用另一个聚合：本质是 uuid，额外记下引用目标。可传聚合对象或聚合名（解决循环导入）。 */
+export function ref(to) {
+    const target = typeof to === 'string' ? to : to?.name;
+    if (!target)
+        throw declError('CAGE-FIELD-002', 'ref() 的目标为空，可能是循环导入；可改为 ref("聚合名")');
+    return mk(z.string().uuid(), { kind: 'ref', sql: 'uuid', ref: target });
+}
+/** 一对多反查：实际外键在目标聚合上，不创建另一份关系或可写数组。 */
+export function hasMany(to, options) {
+    const target = typeof to === 'string' ? to : to?.name;
+    if (!target)
+        throw declError('CAGE-REL-001', 'hasMany() 需要目标聚合；循环引用请使用聚合名字符串');
+    return mk(z.array(z.string().uuid()), { kind: 'hasMany', sql: '', ref: target, ...options });
+}
+/** 多对多：字段与普通属性一处声明，中间表由框架生成；业务命令返回目标 ID 数组。 */
+export function manyToMany(to, options = {}) {
+    const target = typeof to === 'string' ? to : to?.name;
+    if (!target)
+        throw declError('CAGE-REL-001', 'manyToMany() 需要目标聚合；循环引用请使用聚合名字符串');
+    return mk(z.array(z.string().uuid()), { kind: 'manyToMany', sql: '', ref: target, ...options });
+}
+export const isRelation = (field) => field.kind === 'hasMany' || field.kind === 'manyToMany';
+export function list(arg) {
+    const members = isField(arg) ? [arg] : Object.values(arg);
+    if (members.some(isRelation))
+        throw declError('CAGE-REL-001', '关系字段只能直接声明在聚合 fields 中，不能嵌入 JSON 明细');
+    if (isField(arg)) {
+        return mk(z.array(arg.zod), { kind: 'list', sql: 'jsonb', shape: { item: arg } });
+    }
+    const item = z.object(Object.fromEntries(Object.entries(arg).map(([k, f]) => [k, f.zod])));
+    return mk(z.array(item), { kind: 'list', sql: 'jsonb', shape: arg });
+}
+export function isField(v) {
+    return v instanceof Field || (!!v && typeof v === 'object' && 'kind' in v && 'base' in v && 'sql' in v);
+}
+/** 把一组字段拼成对象 schema */
+export function objectSchema(fields) {
+    return z.object(Object.fromEntries(Object.entries(fields).filter(([, f]) => f.kind !== 'hasMany').map(([k, f]) => [k, f.zod])));
+}
+/** 结构不固定的 JSON 对象（例如能力点参数），存为 jsonb。业务字段请优先用 list 或具体类型。 */
+export const json = () => mk(z.record(z.string(), z.unknown()), { kind: 'list', sql: 'jsonb' });
+//# sourceMappingURL=fields.js.map

package/dist/primitives/fields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields.js","sourceRoot":"","sources":["../../src/primitives/fields.ts"],"names":[],"mappings":"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"}

package/dist/primitives/flow.d.ts

@@ -0,0 +1,126 @@
+import type { Kysely } from 'kysely';
+import { z } from 'zod';
+import { APPROVAL, JOB, QUERY, REACTION } from '../brands.js';
+import type { AnyAggregate, FieldsOf, SnapshotOf } from './aggregate.js';
+import type { AnyCommand } from './command.js';
+import type { AnyEvent, PayloadOf } from './event.js';
+export type TxMode = 'outbox' | 'same';
+export interface Reaction<E extends AnyEvent = AnyEvent, C extends AnyCommand = AnyCommand> {
+    readonly [REACTION]: true;
+    readonly event: E;
+    readonly command: C;
+    /** 作用的聚合（等于 command.agg，写出来便于阅读） */
+    readonly target: AnyAggregate;
+    /** 把事件载荷映射成命令输入（纯函数）；返回 null 表示这次不处理 */
+    readonly map: (e: PayloadOf<E>) => z.input<C['input']> | null;
+    /** 事务语义：outbox 异步（默认，见 D3）；same 与触发命令同一事务 */
+    readonly tx: TxMode;
+    /** 获得的资源，供资源配对检查使用 */
+    readonly acquires?: string;
+    /** 释放的资源 */
+    readonly releases?: string;
+    readonly name?: string;
+}
+export type AnyReaction = Reaction<AnyEvent, AnyCommand>;
+export declare function reaction<E extends AnyEvent, C extends AnyCommand>(ev: E, def: {
+    command: C;
+    map: (e: PayloadOf<E>) => z.input<C['input']> | null;
+    target?: AnyAggregate;
+    tx?: TxMode;
+    acquires?: string;
+    releases?: string;
+    name?: string;
+}): Reaction<E, C>;
+export interface Query<I extends z.ZodType = z.ZodType> {
+    readonly [QUERY]: true;
+    readonly name: string;
+    /** 查询读了哪些聚合：只能引用它们的安全视图；调用者需要每个聚合的 read 能力 */
+    readonly reads: readonly AnyAggregate[];
+    readonly input: I;
+    /** 手写 SQL：只能引用 safe.* 视图，参数用 :name 占位 */
+    readonly sql?: string;
+    /** 查询构建器写法：db 是只读账号上的 Kysely，只映射安全视图 */
+    readonly build?: (db: Kysely<any>, input: z.output<I>) => {
+        execute(): Promise<unknown[]>;
+    };
+    readonly description?: string;
+}
+export type AnyQuery = Query<z.ZodType>;
+export declare function query<I extends z.ZodType = z.ZodObject<{}>>(name: string, def: {
+    reads: AnyAggregate[];
+    input?: I;
+    sql?: string;
+    build?: (db: Kysely<any>, input: z.output<I>) => {
+        execute(): Promise<unknown[]>;
+    };
+    description?: string;
+}): Query<I>;
+export interface Approval<A extends AnyAggregate = AnyAggregate> {
+    readonly [APPROVAL]: true;
+    readonly agg: A;
+    /** 流程名，例如 po-approval */
+    readonly process: string;
+    /** 哪个事件启动流程 */
+    readonly start: AnyEvent;
+    /** 哪些事件取消流程（例如撤回、取消） */
+    readonly cancelOn: readonly AnyEvent[];
+    /** 可路由字段：只有它们会作为流程变量传给引擎 */
+    readonly routable: readonly (keyof FieldsOf<A> & string)[];
+    /** 通过与驳回分别落到哪个命令（必须 invokedBy: process） */
+    readonly onApproved: AnyCommand;
+    readonly onRejected: AnyCommand;
+}
+export declare function approval<A extends AnyAggregate>(agg: A, def: {
+    process: string;
+    start: AnyEvent;
+    cancelOn?: AnyEvent[];
+    routable: (keyof FieldsOf<A> & string)[];
+    onApproved: AnyCommand;
+    onRejected: AnyCommand;
+}): Approval<A>;
+export interface JobQueryApi {
+    /** 只读查询：等值条件，另支持 createdBefore / createdAfter / updatedBefore */
+    list<A extends AnyAggregate>(agg: A, where?: Partial<SnapshotOf<A>> & {
+        createdBefore?: Date | string;
+        createdAfter?: Date | string;
+        updatedBefore?: Date | string;
+    }, opts?: {
+        limit?: number;
+    }): Promise<SnapshotOf<A>[]>;
+}
+export interface JobApi {
+    query: JobQueryApi;
+    /** 只能调用 calls 里声明过的命令；每次调用都走完整流水线，审计 source = job */
+    call<C extends AnyCommand>(cmd: C, input: z.input<C['input']>): Promise<SnapshotOf<C['agg']>>;
+    tenantId: string;
+    now: Date;
+    log: (msg: string, extra?: Record<string, unknown>) => void;
+}
+export interface Job {
+    readonly [JOB]: true;
+    readonly name: string;
+    /** cron 表达式，例如 0 2 * * * */
+    readonly cron: string;
+    readonly reads: readonly AnyAggregate[];
+    readonly calls: readonly AnyCommand[];
+    readonly run: (api: JobApi) => Promise<void>;
+    readonly description?: string;
+}
+export declare function job(name: string, def: {
+    cron: string;
+    reads?: AnyAggregate[];
+    calls?: AnyCommand[];
+    run: (api: JobApi) => Promise<void>;
+    description?: string;
+}): Job;
+/** 前 N 天 */
+export declare function daysAgo(n: number, from?: Date): Date;
+export interface UnsafeTag {
+    readonly reason: string;
+    readonly owner: string;
+}
+/**
+ * 逃生口：声明表达不了时使用，必须写明原因和负责人。lint 检查参数，计数进 PR 摘要。
+ *   const v = unsafe({ reason: '…', owner: 'zhangsan' }, () => …)
+ */
+export declare function unsafe<T>(tag: UnsafeTag, fn: () => T): T;