@yss123/cage-kernel 0.0.0-stage → 0.2.0

package/dist/org.js

@@ -0,0 +1,127 @@
+import { COMBINATORS } from './types.js';
+/** 多角色能力取并集，数值参数（额度）取最大值 */
+export function mergeCaps(roles) {
+    const out = new Map();
+    for (const r of roles) {
+        for (const c of r.capabilities ?? []) {
+            const prev = out.get(c.capability);
+            const next = { ...(prev ?? {}) };
+            for (const [k, v] of Object.entries(c.params ?? {})) {
+                const pv = next[k];
+                next[k] = typeof v === 'number' && typeof pv === 'number' ? Math.max(v, pv) : pv ?? v;
+            }
+            out.set(c.capability, next);
+        }
+    }
+    return out;
+}
+/** 多角色范围取并集：同一聚合的多个组合子用 OR 连接；deptSet 的部门合并 */
+export function mergeScopes(roles) {
+    const out = {};
+    for (const r of roles) {
+        for (const s of r.scopes ?? []) {
+            if (!COMBINATORS.includes(s.combinator))
+                continue; // 授权数据异常时宁可少给
+            const list = (out[s.aggregate] ??= []);
+            const same = list.find((g) => g.combinator === s.combinator);
+            if (same && s.combinator === 'deptSet')
+                same.deptIds = [...new Set([...(same.deptIds ?? []), ...(s.deptIds ?? [])])];
+            else if (!same)
+                list.push(s.combinator === 'deptSet' ? { combinator: 'deptSet', deptIds: [...(s.deptIds ?? [])] } : { combinator: s.combinator });
+        }
+    }
+    return out;
+}
+/** 能力点 X.unmask.kind → 明文权限 X.kind */
+export function unmaskFrom(caps) {
+    const out = [];
+    for (const cap of caps.keys()) {
+        const m = /^([A-Z*][A-Za-z0-9]*)\.unmask\.([a-zA-Z]+)$/.exec(cap);
+        if (m)
+            out.push(`${m[1]}.${m[2]}`);
+    }
+    return out;
+}
+/** 从系统表读取一个用户的授权（内核账号） */
+export async function loadUserGrants(db, userId, tenantId) {
+    const user = await db
+        .selectFrom('sys.user as u')
+        .leftJoin('sys.dept as d', 'd.id', 'u.dept_id')
+        .select(['u.id', 'u.status', 'u.dept_id', 'u.role_ids', 'd.ancestors'])
+        .where('u.id', '=', userId)
+        .where('u.tenant_id', '=', tenantId)
+        .executeTakeFirst();
+    if (!user)
+        return null;
+    const roleIds = Array.isArray(user.role_ids) ? user.role_ids : [];
+    const roles = roleIds.length
+        ? await db
+            .selectFrom('sys.role')
+            .select(['capabilities', 'scopes'])
+            .where('id', 'in', roleIds)
+            .where('tenant_id', '=', tenantId)
+            .where('status', '=', 'active')
+            .execute()
+        : [];
+    const capabilities = mergeCaps(roles);
+    return {
+        userId,
+        tenantId,
+        deptId: user.dept_id ?? null,
+        deptPath: user.ancestors ?? null,
+        capabilities,
+        scopes: mergeScopes(roles),
+        unmask: unmaskFrom(capabilities),
+        active: user.status === 'active',
+    };
+}
+/** 用户上下文：禁用的用户没有任何能力 */
+export function userCtx(g, extra = {}) {
+    return {
+        actor: { kind: 'user', id: g.userId },
+        userId: g.userId,
+        tenantId: g.tenantId,
+        deptId: g.deptId,
+        deptPath: g.deptPath,
+        capabilities: g.active ? g.capabilities : new Map(),
+        scopes: g.active ? g.scopes : {},
+        unmask: g.active ? g.unmask : [],
+        source: 'api',
+        ...extra,
+    };
+}
+export function anonymousCtx(tenantId, extra = {}) {
+    return {
+        actor: { kind: 'anonymous', id: 'anonymous' },
+        userId: null,
+        tenantId,
+        deptId: null,
+        deptPath: null,
+        capabilities: new Map(),
+        scopes: {},
+        unmask: [],
+        source: 'api',
+        ...extra,
+    };
+}
+/**
+ * 系统身份上下文：能力只包含它声明过的命令；范围为全部（仍受租户约束）。
+ * 审批流程、定时任务、入站回调、反应各自用它。
+ */
+export function systemCtx(opts) {
+    const source = opts.kind === 'system' ? 'system' : opts.kind;
+    return {
+        actor: { kind: opts.kind, id: `${opts.kind}:${opts.name}` },
+        userId: null,
+        onBehalfOf: opts.onBehalfOf ?? null,
+        tenantId: opts.tenantId,
+        deptId: null,
+        deptPath: null,
+        capabilities: new Map(opts.capabilities.map((c) => [c, {}])),
+        scopes: { '*': [{ combinator: 'all' }] },
+        unmask: [],
+        source: source,
+        requestId: opts.requestId,
+    };
+}
+//# sourceMappingURL=org.js.map

package/dist/org.js.map

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

package/dist/pipeline/idempotency.d.ts

@@ -0,0 +1,10 @@
+import { type Transaction } from 'kysely';
+export declare const idempotency: {
+    claim(tx: Transaction<any>, key?: string): Promise<{
+        fresh: true;
+    } | {
+        fresh: false;
+        result: unknown;
+    }>;
+    complete(tx: Transaction<any>, key: string | undefined, result: unknown): Promise<void>;
+};

package/dist/pipeline/idempotency.js

@@ -0,0 +1,29 @@
+// 幂等：请求头带 Idempotency-Key，内核在事务开头先「抢占」这个键。
+// 唯一约束让并发的第二个请求等第一个提交后再判断，最终只执行一次；第一个回滚时第二个会正常执行。
+import { sql } from 'kysely';
+export const idempotency = {
+    async claim(tx, key) {
+        if (!key)
+            return { fresh: true };
+        const row = await tx
+            .insertInto('sys.idempotency')
+            .values({ key, status: 'running', expires_at: sql `now() + interval '24 hours'` })
+            .onConflict((oc) => oc.column('key').doNothing())
+            .returning('key')
+            .executeTakeFirst();
+        if (row)
+            return { fresh: true };
+        const prev = await tx.selectFrom('sys.idempotency').select(['result', 'status']).where('key', '=', key).executeTakeFirstOrThrow();
+        return { fresh: false, result: prev.result };
+    },
+    async complete(tx, key, result) {
+        if (!key)
+            return;
+        await tx
+            .updateTable('sys.idempotency')
+            .set({ status: 'done', result: JSON.stringify(result) })
+            .where('key', '=', key)
+            .execute();
+    },
+};
+//# sourceMappingURL=idempotency.js.map

package/dist/pipeline/idempotency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.js","sourceRoot":"","sources":["../../src/pipeline/idempotency.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,kDAAkD;AAClD,OAAO,EAAE,GAAG,EAAoB,MAAM,QAAQ,CAAC;AAE/C,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,KAAK,CAAC,KAAK,CAAC,EAAoB,EAAE,GAAY;QAC5C,IAAI,CAAC,GAAG;YAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QACjC,MAAM,GAAG,GAAG,MAAM,EAAE;aACjB,UAAU,CAAC,iBAAiB,CAAC;aAC7B,MAAM,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,CAAA,6BAA6B,EAAE,CAAC;aAChF,UAAU,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,EAAE,CAAC;aAChD,SAAS,CAAC,KAAK,CAAC;aAChB,gBAAgB,EAAE,CAAC;QACtB,IAAI,GAAG;YAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QAChC,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,uBAAuB,EAAE,CAAC;QAClI,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;IAC/C,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,EAAoB,EAAE,GAAuB,EAAE,MAAe;QAC3E,IAAI,CAAC,GAAG;YAAE,OAAO;QACjB,MAAM,EAAE;aACL,WAAW,CAAC,iBAAiB,CAAC;aAC9B,GAAG,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;aACvD,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,CAAC;aACtB,OAAO,EAAE,CAAC;IACf,CAAC;CACF,CAAC"}

package/dist/pipeline/load.d.ts

@@ -0,0 +1,15 @@
+import { type Kysely, type Transaction } from 'kysely';
+import type { AnyAggregate } from '../primitives/aggregate.js';
+import type { FindOptions, ReadRepo, Reads } from '../primitives/command.js';
+import type { Ctx } from '../types.js';
+type Db = Transaction<any> | Kysely<any>;
+export declare const tableRef: (agg: AnyAggregate, alias?: string) => string;
+export declare function loadScoped(tx: Db, agg: AnyAggregate, id: string, ctx: Ctx, forUpdate: boolean): Promise<Record<string, any> | null>;
+/** 把等值条件翻译成列条件；只允许声明过的字段 */
+export declare function whereColumns(agg: AnyAggregate, where: Record<string, unknown> | undefined): [string, unknown][];
+export declare function scopedFind(tx: Db, agg: AnyAggregate, ctx: Ctx, where?: Record<string, unknown>, opts?: FindOptions): import("kysely").SelectQueryBuilder<any, string, {
+    [x: string]: any;
+}>;
+/** 第 7 关：只把 reads 里的聚合做成只读仓储，同样受范围约束 */
+export declare function bindReads<R extends Reads>(tx: Db, reads: R, ctx: Ctx): Record<string, ReadRepo<any>>;
+export {};

package/dist/pipeline/load.js

@@ -0,0 +1,87 @@
+// 按范围加载：把「能不能看到这条数据」直接写进 SQL 条件，范围外的数据根本查不出来。
+import { sql } from 'kysely';
+import { cageError } from '../errors.js';
+import { rowToSnapshot } from '../db/rows.js';
+import { compileScope } from '../scope/index.js';
+import { snake } from '../util/names.js';
+import { loadRelationIds } from '../relations.js';
+import { isRelation } from '../primitives/fields.js';
+export const tableRef = (agg, alias = 't') => `${agg.table.schema}.${agg.table.name} as ${alias}`;
+export async function loadScoped(tx, agg, id, ctx, forUpdate) {
+    let q = tx
+        .selectFrom(tableRef(agg))
+        .selectAll()
+        .where('t.id', '=', id)
+        .where(compileScope(agg.scope, agg.name, ctx, 't'));
+    if (forUpdate)
+        q = q.forUpdate();
+    const row = await q.executeTakeFirst();
+    return row ? (await loadRelationIds(tx, agg, [rowToSnapshot(agg, row)], ctx))[0] : null;
+}
+const SYSTEM_KEYS = {
+    id: 'id', status: 'status', version: 'version', createdAt: 'created_at', updatedAt: 'updated_at',
+};
+/** 把等值条件翻译成列条件；只允许声明过的字段 */
+export function whereColumns(agg, where) {
+    const out = [];
+    for (const [k, v] of Object.entries(where ?? {})) {
+        if (v === undefined)
+            continue;
+        const col = SYSTEM_KEYS[k] ?? (k in agg.fields ? snake(k) : undefined);
+        if (!col)
+            throw cageError('INVALID_INPUT', { field: k, message: `${agg.name} 没有字段 ${k}` });
+        const f = agg.fields[k];
+        if (f && (f.sql === 'jsonb' || isRelation(f)))
+            throw cageError('INVALID_INPUT', { field: k, message: '明细或集合关系不能作为主表查询条件' });
+        out.push([col, v]);
+    }
+    return out;
+}
+export function scopedFind(tx, agg, ctx, where, opts = {}) {
+    let q = tx.selectFrom(tableRef(agg)).selectAll().where(compileScope(agg.scope, agg.name, ctx, 't'));
+    for (const [col, v] of whereColumns(agg, where)) {
+        q = v === null ? q.where(sql.ref(`t.${col}`), 'is', null) : q.where(sql.ref(`t.${col}`), '=', v);
+    }
+    if (opts.orderBy) {
+        const col = SYSTEM_KEYS[opts.orderBy] ?? (opts.orderBy in agg.fields ? snake(opts.orderBy) : undefined);
+        const field = agg.fields[opts.orderBy];
+        if (!col || (field && isRelation(field)))
+            throw cageError('INVALID_INPUT', { field: opts.orderBy });
+        q = q.orderBy(sql.ref(`t.${col}`), opts.desc ? 'desc' : 'asc');
+    }
+    else {
+        q = q.orderBy('t.created_at', 'asc');
+    }
+    return q.limit(Math.min(opts.limit ?? 1000, 5000));
+}
+/** 第 7 关：只把 reads 里的聚合做成只读仓储，同样受范围约束 */
+export function bindReads(tx, reads, ctx) {
+    const deps = {};
+    for (const [alias, agg] of Object.entries(reads)) {
+        deps[alias] = Object.freeze({
+            get: async (id) => (typeof id === 'string' && /^[0-9a-f-]{36}$/i.test(id) ? loadScoped(tx, agg, id, ctx, false) : null),
+            find: async (where, opts) => loadRelationIds(tx, agg, (await scopedFind(tx, agg, ctx, where, opts).execute()).map((r) => rowToSnapshot(agg, r)), ctx),
+            findOne: async (where) => {
+                const rows = await scopedFind(tx, agg, ctx, where, { limit: 1 }).execute();
+                return rows[0] ? (await loadRelationIds(tx, agg, [rowToSnapshot(agg, rows[0])], ctx))[0] : null;
+            },
+            count: async (where) => {
+                let q = tx.selectFrom(tableRef(agg)).select(sql `count(*)::int`.as('n')).where(compileScope(agg.scope, agg.name, ctx, 't'));
+                for (const [col, v] of whereColumns(agg, where))
+                    q = q.where(sql.ref(`t.${col}`), '=', v);
+                const r = await q.executeTakeFirst();
+                return Number(r?.n ?? 0);
+            },
+        });
+    }
+    // 访问未声明的读依赖：类型上已经报错；运行时也给出明确的错误码
+    return new Proxy(deps, {
+        get(target, prop) {
+            if (typeof prop === 'string' && !(prop in target) && prop !== 'then' && prop !== 'toJSON') {
+                throw new Error(`[CAGE-READS-001] handler 使用了未声明的读依赖 ${prop}（详见 docs/errors/CAGE-READS-001.md）`);
+            }
+            return target[prop];
+        },
+    });
+}
+//# sourceMappingURL=load.js.map

package/dist/pipeline/load.js.map

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

package/dist/primitives/aggregate.d.ts

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+import { AGGREGATE } from '../brands.js';
+import type { ScopeSpec } from '../scope/index.js';
+import { type AnyField, type FieldValues, type Fields } from './fields.js';
+import { type StatesDef } from './states.js';
+/** 每张表都有的系统列 */
+export interface SystemCols<S extends string> {
+    id: string;
+    version: number;
+    status: S;
+    createdAt: string;
+    updatedAt: string;
+}
+export type Snapshot<F extends Fields = Fields, S extends string = string> = FieldValues<F> & SystemCols<S>;
+export declare const RESERVED_FIELDS: readonly ["id", "version", "status", "createdAt", "updatedAt", "tenantId"];
+export interface Aggregate<N extends string = string, F extends Fields = Fields, S extends string = string> {
+    readonly [AGGREGATE]: true;
+    /** 聚合名，同时是表名和能力点前缀 */
+    readonly name: N;
+    readonly fields: F;
+    readonly states: StatesDef<S>;
+    readonly scope: ScopeSpec;
+    readonly invariants: Readonly<Record<string, (o: Snapshot<F, S>) => boolean>>;
+    /** 由 fields 拼出的整体校验 */
+    readonly schema: z.ZodObject<any>;
+    readonly table: {
+        readonly schema: 'core' | 'sys';
+        readonly name: string;
+    };
+    readonly description?: string;
+    /** 内部选项：授权类聚合写入后通知各实例清缓存 */
+    readonly options: {
+        readonly grants?: 'self' | 'all';
+    };
+}
+export type AnyAggregate = Aggregate<string, any, any>;
+export type StateOf<A> = A extends Aggregate<any, any, infer S> ? S : never;
+export type FieldsOf<A> = A extends Aggregate<any, infer F, any> ? F : never;
+export type SnapshotOf<A> = A extends Aggregate<any, infer F, infer S> ? Snapshot<F, S> : never;
+export type FieldValuesOf<A> = A extends Aggregate<any, infer F, any> ? FieldValues<F> : never;
+type FieldInput = Record<string, AnyField | StatesDef<any>>;
+type PlainFields<FI> = {
+    [K in keyof FI as FI[K] extends StatesDef<any> ? never : K]: FI[K] extends AnyField ? FI[K] : never;
+};
+type StatesIn<FI> = {
+    [K in keyof FI]: FI[K] extends StatesDef<infer S> ? S : never;
+}[keyof FI];
+type ResolveStates<FI, SS extends string> = [SS] extends [never] ? ([StatesIn<FI>] extends [never] ? 'active' | 'deleted' : StatesIn<FI>) : SS;
+export interface AggregateDef<FI extends FieldInput, SS extends string> {
+    fields: FI;
+    /** 状态集；也可以写在 fields 里：status: POStatus */
+    states?: StatesDef<SS>;
+    /** 数据范围：哪个字段是部门、哪个是创建人 */
+    scope?: ScopeSpec;
+    /** 不变量：普通函数，每次写入后逐条校验 */
+    invariants?: Record<string, (o: Snapshot<PlainFields<FI>, ResolveStates<FI, SS>>) => boolean>;
+    description?: string;
+    /** 框架内部使用：系统聚合放在 sys 模式 */
+    table?: {
+        schema?: 'core' | 'sys';
+        name?: string;
+    };
+    /** 框架内部使用 */
+    options?: {
+        grants?: 'self' | 'all';
+    };
+}
+export declare function aggregate<const N extends string, FI extends FieldInput, SS extends string = never>(name: N, def: AggregateDef<FI, SS>): Aggregate<N, PlainFields<FI>, ResolveStates<FI, SS>>;
+export declare function isAggregate(v: unknown): v is AnyAggregate;
+export declare function hasStates(agg: AnyAggregate, s: string | readonly string[]): boolean;
+/** 聚合中不对外暴露（hidden）的字段名 */
+export declare function hiddenFields(agg: AnyAggregate): string[];
+/** 聚合中的敏感字段：字段名 → 种类 */
+export declare function sensitiveFields(agg: AnyAggregate): Record<string, string>;
+export {};

package/dist/primitives/aggregate.js

@@ -0,0 +1,69 @@
+import { AGGREGATE } from '../brands.js';
+import { declError } from '../errors.js';
+import { snake } from '../util/names.js';
+import { isField, isRelation, objectSchema } from './fields.js';
+import { DEFAULT_STATES, isStates } from './states.js';
+export const RESERVED_FIELDS = ['id', 'version', 'status', 'createdAt', 'updatedAt', 'tenantId'];
+export function aggregate(name, def) {
+    if (!/^[A-Z][A-Za-z0-9]*$/.test(name)) {
+        throw declError('CAGE-NAME-001', `聚合名 ${name} 必须是大驼峰`);
+    }
+    let st = def.states;
+    const fields = {};
+    for (const [k, v] of Object.entries(def.fields)) {
+        if (isStates(v)) {
+            if (k !== 'status')
+                throw declError('CAGE-STATE-005', `状态集只能放在 status 字段上（发现 ${name}.${k}）`);
+            if (st)
+                throw declError('CAGE-STATE-005', `${name} 同时在 states 和 fields.status 里声明了状态`);
+            st = v;
+            continue;
+        }
+        if (!isField(v))
+            throw declError('CAGE-FIELD-003', `${name}.${k} 不是字段原语`);
+        if (RESERVED_FIELDS.includes(k)) {
+            throw declError('CAGE-FIELD-004', `${name}.${k} 是保留字段名，由内核维护`);
+        }
+        if (!/^[a-z][A-Za-z0-9]*$/.test(k))
+            throw declError('CAGE-NAME-002', `字段名 ${name}.${k} 必须是小驼峰`);
+        fields[k] = v;
+    }
+    const states = st ?? DEFAULT_STATES;
+    // 范围：未写创建人字段时，自动识别 createdBy
+    const sc = def.scope ?? {};
+    const ownerField = sc.ownerField ?? ('createdBy' in fields ? 'createdBy' : undefined);
+    for (const f of [sc.deptField, ownerField]) {
+        if (f && f !== 'id' && !(f in fields))
+            throw declError('CAGE-SCOPE-002', `${name} 的范围字段 ${f} 不存在`);
+        if (f && f !== 'id' && isRelation(fields[f]))
+            throw declError('CAGE-REL-001', `${name} 的范围字段必须是主表列，不能使用集合关系 ${f}`);
+    }
+    const scope = Object.freeze({ ...sc, ownerField });
+    return Object.freeze({
+        [AGGREGATE]: true,
+        name,
+        fields: Object.freeze(fields),
+        states,
+        scope,
+        invariants: Object.freeze({ ...(def.invariants ?? {}) }),
+        schema: objectSchema(fields),
+        table: Object.freeze({ schema: def.table?.schema ?? 'core', name: def.table?.name ?? snake(name) }),
+        description: def.description,
+        options: Object.freeze({ ...(def.options ?? {}) }),
+    });
+}
+export function isAggregate(v) {
+    return !!v && typeof v === 'object' && v[AGGREGATE] === true;
+}
+export function hasStates(agg, s) {
+    return [s].flat().every((x) => agg.states.values.includes(x));
+}
+/** 聚合中不对外暴露（hidden）的字段名 */
+export function hiddenFields(agg) {
+    return Object.entries(agg.fields).filter(([, f]) => f.isHidden).map(([k]) => k);
+}
+/** 聚合中的敏感字段：字段名 → 种类 */
+export function sensitiveFields(agg) {
+    return Object.fromEntries(Object.entries(agg.fields).filter(([, f]) => f.sensitiveKind).map(([k, f]) => [k, f.sensitiveKind]));
+}
+//# sourceMappingURL=aggregate.js.map

package/dist/primitives/aggregate.js.map

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

package/dist/primitives/command.d.ts

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+import { COMMAND } from '../brands.js';
+import { type DomainError } from '../errors.js';
+import type { MaybePromise } from '../types.js';
+import { type AnyAggregate, type FieldValuesOf, type SnapshotOf, type StateOf } from './aggregate.js';
+import type { Constraint } from './constraints.js';
+import { type AnyEvent, type EmitSpec } from './event.js';
+/** reads 的形状：别名 → 聚合 */
+export type Reads = Record<string, AnyAggregate>;
+export interface FindOptions {
+    limit?: number;
+    orderBy?: string;
+    desc?: boolean;
+}
+/** 注入给 handler 的只读仓储：自动附加数据范围，范围外等于不存在 */
+export interface ReadRepo<A extends AnyAggregate> {
+    /** 按 id 取一条，范围外返回 null */
+    get(id: string): Promise<SnapshotOf<A> | null>;
+    /** 等值条件查询，自动附加范围 */
+    find(where?: Partial<SnapshotOf<A>>, opts?: FindOptions): Promise<SnapshotOf<A>[]>;
+    /** 按条件取第一条 */
+    findOne(where: Partial<SnapshotOf<A>>): Promise<SnapshotOf<A> | null>;
+    /** 计数，同样自动附加范围 */
+    count(where?: Partial<SnapshotOf<A>>): Promise<number>;
+}
+export type DepsOf<R extends Reads> = {
+    readonly [K in keyof R]: ReadRepo<R[K]>;
+};
+/** handler 拿到的草稿：业务字段可改；状态、主键、版本号只读，handler 改不了 */
+export type Draft<A extends AnyAggregate> = FieldValuesOf<A> & {
+    readonly id: string;
+    readonly status: StateOf<A>;
+    readonly version: number;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+};
+/** handler 的第四个参数：只读的调用信息 */
+export interface HandlerCtx {
+    /** 当前时间（同一次命令里固定） */
+    readonly now: Date;
+    /** 真人操作者（系统身份时为它代表的人） */
+    readonly actorUserId: string | null;
+}
+export type HandlerResult<A extends AnyAggregate> = Draft<A> | Partial<FieldValuesOf<A>> | DomainError | void;
+export type Invoker = 'user' | 'process' | 'job' | 'external';
+export interface Command<A extends AnyAggregate = AnyAggregate, R extends Reads = Reads, I extends z.ZodType = z.ZodType> {
+    readonly [COMMAND]: true;
+    readonly agg: A;
+    readonly from: readonly StateOf<A>[] | 'new';
+    /** null 表示保持加锁读到的当前状态；仍检查 from、权限、版本并写审计。 */
+    readonly to: StateOf<A> | null;
+    readonly input: I;
+    readonly reads: R;
+    readonly emits: readonly EmitSpec[];
+    readonly constraints: readonly Constraint<A>[];
+    readonly invokedBy: readonly Invoker[];
+    /** 匿名用户也能调用（极少使用） */
+    readonly public: boolean;
+    /** 显式命令名；不写时取导出名 */
+    readonly name?: string;
+    readonly description?: string;
+    readonly handler: (o: Draft<A>, input: z.output<I>, deps: DepsOf<R>, ctx: HandlerCtx) => MaybePromise<HandlerResult<A>>;
+}
+/**
+ * 注册表中的命令可以有不同聚合、输入与 reads，因此这里擦除具体泛型。
+ * 不能用 Command<AnyAggregate, Reads, ZodType>：函数参数逆变会要求业务
+ * handler 接受任意聚合，导致带 stock 等明确读依赖的命令无法传给 approval。
+ * command() 的返回值仍保留 A/R/I，调用处的类型推导不受这个内部容器类型影响。
+ */
+export type AnyCommand = Omit<Command<AnyAggregate, Reads, z.ZodType>, 'handler'> & {
+    readonly handler: (...args: any[]) => MaybePromise<any>;
+};
+export declare const idOnly: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+export declare const empty: z.ZodObject<{}, z.core.$strip>;
+type DefaultInput<F> = F extends 'new' ? typeof empty : typeof idOnly;
+export interface CommandDef<A extends AnyAggregate, R extends Reads, I extends z.ZodType, F> {
+    /** 起始状态；'new' 表示新建 */
+    from: F;
+    /** 目标状态；非新建命令可显式写 null，只更新业务字段而不迁移状态。 */
+    to: F extends 'new' ? StateOf<A> : StateOf<A> | null;
+    /** 输入校验；非新建命令的输入必须包含 id */
+    input?: I;
+    /** 读依赖，决定 handler 能拿到什么 */
+    reads?: R;
+    /** 发出的事件 */
+    emits?: (AnyEvent | EmitSpec)[];
+    /** 硬约束组合子 */
+    constraints?: NoInfer<Constraint<A>>[];
+    /** 谁能调用，默认 user */
+    invokedBy?: Invoker | Invoker[];
+    public?: boolean;
+    name?: string;
+    description?: string;
+    /** AI 写的业务逻辑：纯函数，返回新草稿、字段变更或业务错误 */
+    handler: (o: Draft<A>, input: z.output<[I] extends [never] ? DefaultInput<F> : I>, deps: DepsOf<R>, ctx: HandlerCtx) => MaybePromise<HandlerResult<A>>;
+}
+export declare function command<A extends AnyAggregate, const F extends StateOf<A> | readonly StateOf<A>[] | 'new', R extends Reads = {}, I extends z.ZodType = never>(agg: A, def: CommandDef<A, R, I, F>): Command<A, R, [I] extends [never] ? DefaultInput<F> : I>;
+export declare function isCommand(v: unknown): v is AnyCommand;
+export {};

package/dist/primitives/command.js

@@ -0,0 +1,49 @@
+// command 原语：一次写操作。命令名由导出的变量名决定：export const approve = command(PurchaseOrder, …)
+// 的能力点就是 PurchaseOrder.approve。
+import { z } from 'zod';
+import { COMMAND } from '../brands.js';
+import { declError } from '../errors.js';
+import { hasStates, } from './aggregate.js';
+import { toEmitSpec } from './event.js';
+export const idOnly = z.object({ id: z.string().uuid() });
+export const empty = z.object({});
+export function command(agg, def) {
+    const from = def.from;
+    if (from !== 'new' && !hasStates(agg, from)) {
+        throw declError('CAGE-STATE-001', `${agg.name} 的命令 from 里有未声明的状态：${[from].flat().join(', ')}`);
+    }
+    // 回执等异步元数据可能在单据取消/完成后到达。允许显式保留当前状态，
+    // 避免业务 handler 通过篡改 status 绕过状态机；新建命令必须有实际目标状态。
+    if (from === 'new' && def.to === null) {
+        throw declError('CAGE-CMD-003', `${agg.name} 的新建命令必须指定目标状态，不能使用 to: null`);
+    }
+    if (def.to !== null && !hasStates(agg, def.to)) {
+        throw declError('CAGE-STATE-001', `${agg.name} 的命令 to 是未声明的状态：${String(def.to)}`);
+    }
+    const input = (def.input ?? (from === 'new' ? empty : idOnly));
+    if (from !== 'new' && input instanceof z.ZodObject && !('id' in input.shape)) {
+        throw declError('CAGE-CMD-002', `${agg.name} 的非新建命令输入必须包含 id`);
+    }
+    if (def.name !== undefined && !/^[a-z][A-Za-z0-9]*$/.test(def.name)) {
+        throw declError('CAGE-NAME-004', `命令名 ${def.name} 必须是小驼峰`);
+    }
+    return Object.freeze({
+        [COMMAND]: true,
+        agg,
+        from: (from === 'new' ? 'new' : Object.freeze([from].flat())),
+        to: def.to,
+        input: input,
+        reads: Object.freeze({ ...(def.reads ?? {}) }),
+        emits: Object.freeze((def.emits ?? []).map(toEmitSpec)),
+        constraints: Object.freeze([...(def.constraints ?? [])]),
+        invokedBy: Object.freeze([def.invokedBy ?? 'user'].flat()),
+        public: def.public ?? false,
+        name: def.name,
+        description: def.description,
+        handler: def.handler,
+    });
+}
+export function isCommand(v) {
+    return !!v && typeof v === 'object' && v[COMMAND] === true;
+}
+//# sourceMappingURL=command.js.map

package/dist/primitives/command.js.map

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