@yss123/cage-kernel 0.1.0 → 0.3.0

package/README.md

@@ -1,19 +1,81 @@
 # @yss123/cage-kernel
 
-笼子内核：声明原语、写入流水线、范围组合子、读侧、worker 运行时
+Cage 的服务端内核：用 TypeScript 声明业务对象、状态、命令和事件，再统一执行权限、数据范围、版本、事务、审计与异步消息。适合有审批、组织权限和跨对象业务规则的中后台；它不是浏览器库，也不是绕过业务规则的通用表 CRUD。
 
-Cage 是通过 TypeScript 声明业务、由框架统一执行权限和数据规则的中后台框架。此包是框架的一部分。
+## 安装与位置
 
-## 使用
+需要 Node.js 24+、PostgreSQL；框架包应使用同一版本。在应用的 domain 包中安装：
 
 ```powershell
-pnpm add @yss123/cage-kernel
+pnpm add @yss123/cage-kernel zod
 ```
 
-首次使用建议通过脚手架创建完整项目，所需依赖由模板统一配置。需要 Node.js 24 或更新版本。
+新项目推荐 `pnpm create @yss123/cage-app my-app --template blank`，由模板配置 domain、API、worker、Web 与数据库连接。
 
-- [完整使用说明](https://github.com/shunshunyue/cage/blob/main/docs/使用说明.md)
-- [框架源码与范例](https://github.com/shunshunyue/cage)
-- [问题反馈](https://github.com/shunshunyue/cage/issues)
+## 最小业务声明
 
-许可证：[MIT](https://github.com/shunshunyue/cage/blob/main/LICENSE)。
+在 `packages/domain/src/modules/note/note.ts` 中声明便笺。声明本身不连接数据库；handler 返回业务变化，由内核负责真正写入。
+
+```ts
+/** 部门便笺声明；经 domain 根入口注册，供 CLI 生成契约与 API 执行。 */
+import { aggregate, command, ref, scope, states, text } from '@yss123/cage-kernel';
+import { z } from 'zod';
+
+/** 同部门范围的便笺；归属字段由内核依据当前主体补入，角色仍须显式授权。 */
+export const Note = aggregate('Note', {
+  description: '部门便笺',
+  fields: {
+    title: text(120),
+    deptId: ref('Dept'),
+    createdBy: ref('User'),
+  },
+  states: states('active', 'archived', { terminal: ['archived'] }),
+  scope: scope.deptSubtree('deptId'),
+  invariants: { titleNotBlank: (note) => note.title.trim().length > 0 },
+});
+
+/** 创建有效便笺；输入规范化后进入草稿，权限、范围及最终不变量失败均不会提交。 */
+export const createNote = command(Note, {
+  name: 'create',
+  description: '创建部门便笺',
+  from: 'new',
+  to: 'active',
+  input: z.object({ title: z.string().trim().min(1).max(120) }),
+  handler: (draft) => draft,
+});
+```
+
+模块入口导出 `export * from './note.js';`，domain 根入口保留组织模型并导出新模块：
+
+```ts
+/** 组合所有可注册声明；未从这里导出的业务不会进入生成器和运行注册表。 */
+export * from '@yss123/cage-admin/domain';
+export * from './modules/note/index.js';
+```
+
+随后在应用根目录执行 `pnpm exec cage check`、`pnpm gen`；审查迁移后执行 `pnpm migrate`。管理员为目标角色授予 `Note.create`、`Note.read` 及 `Note` 数据范围，前端通过生成的 `@app/contracts` 调用 `note.create({ title })`、`note.list()`。
+
+## 主要能力与边界
+
+| 入口 | 用途 |
+| --- | --- |
+| `aggregate`、字段工厂、`states`、`scope` | 定义对象字段、关系、生命周期与范围字段 |
+| `command`、`event`、`emit` | 定义唯一业务写入口及成功后产生的事实 |
+| `reaction`、`reactionEach`、`job` | 同事务或异步协作、有界集合处理和定时任务 |
+| `query`、`ReadSide` | 通过只读账号与 `safe.*` 安全视图读取 |
+| `buildRegistry`、`createKernel` | 服务端集成时构建注册表和执行内核；普通应用交给 HTTP 装配 |
+| `@yss123/cage-kernel/worker` | 底层 worker 启停、消费者和健康状态 |
+| `@yss123/cage-kernel/db` | 迁移、DDL 与数据库基础设施，供工具链使用 |
+| `@yss123/cage-kernel/brands` | 框架声明标识 |
+
+handler 的读取写入 `reads`，任务的读取和命令调用写入 `reads/calls`。handler 不直接执行 SQL、HTTP 或文件 IO；外呼使用连接器。`scope` 声明不自动授权，前端 `can()` 不代替后端检查。`ref/hasMany/manyToMany` 统一写在 `fields`，集合关系由命令修改并通过安全读侧分页读取。
+
+金额 `money()` 使用十进制字符串；不要重复定义框架的 `id/version/status/createdAt/updatedAt/tenantId`。新结构用新迁移表达，服务启动不自动建库、迁移或初始化账号。
+
+## 继续阅读
+
+- [架构与执行模型](https://github.com/shunshunyue/cage/blob/main/docs/ai/architecture.md)
+- [原语、命令与查询](https://github.com/shunshunyue/cage/blob/main/docs/ai/primitives.md)
+- [对象关系](https://github.com/shunshunyue/cage/blob/main/docs/ai/relations.md)
+
+脚手架项目自带 `docs/ai` 与 `docs/errors`，可离线学习。源码与反馈：[GitHub](https://github.com/shunshunyue/cage)。许可证：[MIT](https://github.com/shunshunyue/cage/blob/main/LICENSE)。

package/dist/authorization.d.ts

@@ -0,0 +1,34 @@
+import type { Kernel } from './kernel.js';
+import type { Ctx } from './types.js';
+/** not-inspected 表示证据不足，与 fail、pass 分开，避免把未检查结果误当成功。 */
+export interface AuthorizationCheck {
+    stage: string;
+    status: 'pass' | 'fail' | 'not-inspected';
+    code?: string;
+    reason?: unknown;
+}
+/** 无 handler、无锁、无写入；可解释的判断复用实际身份、范围和约束实现。结果仅代表观测时刻。 */
+/**
+ * 先检查输入和主体，再在只读事务中检查对象可见性、状态、版本及硬约束。
+ * 新建最终范围依赖 handler，约束依赖异常也不可判定：二者均返回 allowed:null 所需的未知证据。
+ * 已确认拒绝优先返回 false；返回的 observedAt 标记时效，实际执行仍会重新鉴权和加锁。
+ */
+export declare function explainAuthorization(k: Kernel, capability: string, raw: Record<string, unknown>, ctx: Ctx): Promise<{
+    command: string;
+    actor: import("./types.js").Actor | null;
+    observedAt: string;
+    allowed: boolean;
+    checks: AuthorizationCheck[];
+    scope?: undefined;
+    params?: undefined;
+    limitations?: undefined;
+} | {
+    command: string;
+    actor: import("./types.js").Actor | null;
+    observedAt: string;
+    allowed: boolean | null;
+    checks: AuthorizationCheck[];
+    scope: import("./types.js").ScopeGrant[];
+    params: import("./types.js").CapabilityParams;
+    limitations: string[];
+}>;

package/dist/authorization.js

@@ -0,0 +1,89 @@
+/**
+ * 权限解释器只收集观测证据，不执行 handler、写审计或抢锁。
+ * 它复用真实输入、调用身份、范围及约束检查；输出不能当作后续执行的授权凭证。
+ */
+import { cageError, toCageError } from './errors.js';
+import { loadUserGrants } from './org.js';
+import { assertInvoker } from './pipeline/invoker.js';
+import { loadScoped } from './pipeline/load.js';
+import { newDraft, splitRaw } from './pipeline/draft.js';
+/** 固定公开文案代替任意自定义约束消息，防止消息中拼接的业务明文穿过诊断边界。 */
+function constraintReason(name) {
+    if (name.startsWith('ceiling('))
+        return '额度未配置或不足；请检查该能力的有效参数';
+    if (name.startsWith('sod.notSameAs('))
+        return '职责分离条件未满足';
+    if (name === 'stepUp')
+        return '需要近期二次认证';
+    return '硬约束未满足；请按约束名称检查规则';
+}
+/** 无 handler、无锁、无写入；可解释的判断复用实际身份、范围和约束实现。结果仅代表观测时刻。 */
+/**
+ * 先检查输入和主体，再在只读事务中检查对象可见性、状态、版本及硬约束。
+ * 新建最终范围依赖 handler，约束依赖异常也不可判定：二者均返回 allowed:null 所需的未知证据。
+ * 已确认拒绝优先返回 false；返回的 observedAt 标记时效，实际执行仍会重新鉴权和加锁。
+ */
+export async function explainAuthorization(k, capability, raw, ctx) {
+    const rc = k.registry.command(capability);
+    if (!rc)
+        throw cageError('NOT_FOUND');
+    const cmd = rc.cmd, checks = [];
+    const add = (stage, allowed, code, reason) => checks.push({ stage, status: allowed ? 'pass' : 'fail', code: allowed ? undefined : code, reason });
+    add('authentication', !!ctx.actor && (ctx.actor.kind !== 'anonymous' || cmd.public), 'UNAUTHENTICATED');
+    let split;
+    try {
+        split = splitRaw(raw);
+    }
+    catch (error) {
+        const result = toCageError(error);
+        checks.push({ stage: 'input', status: 'fail', code: result.code, reason: result.detail });
+        return { command: capability, actor: ctx.actor, observedAt: new Date().toISOString(), allowed: false, checks };
+    }
+    const { expectedVersion, rest } = split;
+    const parsed = cmd.input.safeParse(rest);
+    add('input', parsed.success, 'INVALID_INPUT', parsed.success ? undefined : parsed.error.issues.map((issue) => ({ path: issue.path.join('.'), message: issue.message })));
+    try {
+        if (ctx.actor)
+            assertInvoker(cmd, ctx, capability);
+        else
+            throw cageError('UNAUTHENTICATED');
+        add('invoker', true);
+    }
+    catch (error) {
+        const result = toCageError(error);
+        add('invoker', false, result.code, result.detail);
+    }
+    add('capability', cmd.public || ctx.capabilities.has(capability), 'FORBIDDEN', { capability });
+    if (checks.every((check) => check.status === 'pass'))
+        await k.app.transaction().setAccessMode('read only').execute(async (tx) => {
+            const parsedInput = parsed.data;
+            const current = cmd.from === 'new' ? newDraft(cmd, parsedInput, ctx, new Date()) : typeof parsedInput.id === 'string' ? await loadScoped(tx, cmd.agg, parsedInput.id, ctx, false) : null;
+            if (cmd.from === 'new')
+                checks.push({ stage: 'scope', status: 'not-inspected', reason: '新建最终范围要在 handler 合并后实际校验；诊断不执行 handler' });
+            else
+                add('scope', !!current, 'NOT_FOUND', current ? undefined : '对象不存在或不在有效范围内');
+            if (!current)
+                return;
+            add('state', cmd.from === 'new' || cmd.from.includes(current.status), 'INVALID_TRANSITION');
+            add('version', cmd.from === 'new' || expectedVersion === undefined || expectedVersion === current.version, 'CONFLICT');
+            const meta = {
+                capability, capabilitiesOf: async (id) => (await loadUserGrants(tx, id, ctx.tenantId))?.capabilities ?? new Map(),
+                load: async (name, id) => { const agg = k.registry.aggregate(name); return agg ? loadScoped(tx, agg, id, ctx, false) : null; },
+                catalog: () => k.catalogCaps(),
+            };
+            for (const constraint of cmd.constraints) {
+                // 自定义 message 可能拼入未解掩码的字段或关联对象值，诊断只返回固定说明与规则名称。
+                try {
+                    const result = await constraint.check(current, ctx, parsed.data, meta);
+                    add(`constraint:${constraint.name}`, result.ok, 'CONSTRAINT_VIOLATED', result.ok ? undefined : constraintReason(constraint.name));
+                }
+                catch {
+                    checks.push({ stage: `constraint:${constraint.name}`, status: 'not-inspected', reason: '约束检查依赖不可用，不能判定通过' });
+                }
+            }
+        });
+    return { command: capability, actor: ctx.actor, observedAt: new Date().toISOString(), allowed: checks.some((check) => check.status === 'fail') ? false : checks.some((check) => check.status === 'not-inspected') ? null : true, checks,
+        scope: ctx.scopes[cmd.agg.name] ?? ctx.scopes['*'] ?? [{ combinator: 'self' }], params: ctx.capabilities.get(capability) ?? {},
+        limitations: ['只解释认证、输入、调用身份、能力、范围、状态、版本和硬约束；不执行 handler 或预测最终不变量。', '执行时会重新鉴权和加锁，诊断结果不能用于跳过实际授权。'] };
+}
+//# sourceMappingURL=authorization.js.map

package/dist/authorization.js.map

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

package/dist/brands.d.ts

@@ -1,3 +1,4 @@
+/** 持久化对象声明；注册表据此收集字段、状态、范围和不变量。 */
 export declare const AGGREGATE: unique symbol;
 export declare const STATES: unique symbol;
 export declare const COMMAND: unique symbol;
@@ -6,6 +7,7 @@ export declare const REACTION: unique symbol;
 export declare const QUERY: unique symbol;
 export declare const APPROVAL: unique symbol;
 export declare const JOB: unique symbol;
+export declare const BUSINESS_PROCESS: unique symbol;
 export declare const UNSAFE: unique symbol;
 export declare const CONNECTOR: unique symbol;
 export declare const OUTBOUND: unique symbol;
@@ -13,6 +15,12 @@ export declare const INBOUND: unique symbol;
 export declare const ROUTE: unique symbol;
 export declare const CONSUMERS: unique symbol;
 export declare const SYSTEM_DDL: unique symbol;
+export declare const RUNTIME: unique symbol;
+export declare const MIGRATIONS: unique symbol;
+/**
+ * 领域声明的识别目录。这里不包含 CONSUMERS、SYSTEM_DDL 等扩展协议标记：
+ * 它们描述声明附带的能力，不是一个独立业务节点，避免抽取时将同一对象重复分类。
+ */
 export declare const ALL_BRANDS: {
     readonly AGGREGATE: typeof AGGREGATE;
     readonly STATES: typeof STATES;
@@ -22,6 +30,7 @@ export declare const ALL_BRANDS: {
     readonly QUERY: typeof QUERY;
     readonly APPROVAL: typeof APPROVAL;
     readonly JOB: typeof JOB;
+    readonly BUSINESS_PROCESS: typeof BUSINESS_PROCESS;
     readonly UNSAFE: typeof UNSAFE;
     readonly CONNECTOR: typeof CONNECTOR;
     readonly OUTBOUND: typeof OUTBOUND;
@@ -29,4 +38,5 @@ export declare const ALL_BRANDS: {
     readonly ROUTE: typeof ROUTE;
 };
 /** 判断一个值属于哪种原语；不是原语返回 null。 */
+/** 只读取标记，不执行声明中的回调；可安全用于模块导出的混合值筛选。 */
 export declare function brandOf(v: unknown): keyof typeof ALL_BRANDS | null;

package/dist/brands.js

@@ -1,5 +1,6 @@
 // 品牌标记：抽取器、注册表和内核靠它们识别原语返回的描述对象。
 // 使用 Symbol.for，即使同一个包被加载两份，标记也相同。
+/** 持久化对象声明；注册表据此收集字段、状态、范围和不变量。 */
 export const AGGREGATE = Symbol.for('cage.aggregate');
 export const STATES = Symbol.for('cage.states');
 export const COMMAND = Symbol.for('cage.command');
@@ -8,6 +9,7 @@ export const REACTION = Symbol.for('cage.reaction');
 export const QUERY = Symbol.for('cage.query');
 export const APPROVAL = Symbol.for('cage.approval');
 export const JOB = Symbol.for('cage.job');
+export const BUSINESS_PROCESS = Symbol.for('cage.businessProcess');
 export const UNSAFE = Symbol.for('cage.unsafe');
 // 以下原语由 @yss123/cage-connectors、@yss123/cage-approval 实现，标记放在这里统一管理
 export const CONNECTOR = Symbol.for('cage.connector');
@@ -18,11 +20,19 @@ export const ROUTE = Symbol.for('cage.route');
 export const CONSUMERS = Symbol.for('cage.consumers');
 // 运行时扩展点：带这个标记的声明对象可以提供框架自己的系统表 DDL
 export const SYSTEM_DDL = Symbol.for('cage.systemDdl');
+// 基础设施扩展，不增加领域原语：服务自行提供迁移、HTTP 与后台处理器。
+export const RUNTIME = Symbol.for('cage.runtime');
+export const MIGRATIONS = Symbol.for('cage.migrations');
+/**
+ * 领域声明的识别目录。这里不包含 CONSUMERS、SYSTEM_DDL 等扩展协议标记：
+ * 它们描述声明附带的能力，不是一个独立业务节点，避免抽取时将同一对象重复分类。
+ */
 export const ALL_BRANDS = {
-    AGGREGATE, STATES, COMMAND, EVENT, REACTION, QUERY, APPROVAL, JOB, UNSAFE,
+    AGGREGATE, STATES, COMMAND, EVENT, REACTION, QUERY, APPROVAL, JOB, BUSINESS_PROCESS, UNSAFE,
     CONNECTOR, OUTBOUND, INBOUND, ROUTE,
 };
 /** 判断一个值属于哪种原语；不是原语返回 null。 */
+/** 只读取标记，不执行声明中的回调；可安全用于模块导出的混合值筛选。 */
 export function brandOf(v) {
     if (!v || (typeof v !== 'object' && typeof v !== 'function'))
         return null;

package/dist/brands.js.map

@@ -1 +1 @@
-{"version":3,"file":"brands.js","sourceRoot":"","sources":["../src/brands.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,mCAAmC;AAEnC,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;AACtD,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;AAChD,MAAM,CAAC,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;AAClD,MAAM,CAAC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;AAC9C,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;AACpD,MAAM,CAAC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;AAC9C,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;AACpD,MAAM,CAAC,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;AAC1C,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;AAChD,oEAAoE;AACpE,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;AACtD,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;AACpD,MAAM,CAAC,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;AAClD,MAAM,CAAC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;AAE9C,sCAAsC;AACtC,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;AACtD,oCAAoC;AACpC,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;AAEvD,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM;IACzE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK;CAC3B,CAAC;AAEX,+BAA+B;AAC/B,MAAM,UAAU,OAAO,CAAC,CAAU;IAChC,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1E,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QAChD,IAAK,CAAS,CAAC,CAAC,CAAC;YAAE,OAAO,CAA4B,CAAC;IACzD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"brands.js","sourceRoot":"","sources":["../src/brands.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,mCAAmC;AAEnC,mCAAmC;AACnC,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;AACtD,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;AAChD,MAAM,CAAC,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;AAClD,MAAM,CAAC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;AAC9C,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;AACpD,MAAM,CAAC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;AAC9C,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;AACpD,MAAM,CAAC,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;AAC1C,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;AACnE,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;AAChD,oEAAoE;AACpE,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;AACtD,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;AACpD,MAAM,CAAC,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;AAClD,MAAM,CAAC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;AAE9C,sCAAsC;AACtC,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;AACtD,oCAAoC;AACpC,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;AACvD,uCAAuC;AACvC,MAAM,CAAC,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;AAClD,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;AAExD;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,gBAAgB,EAAE,MAAM;IAC3F,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK;CAC3B,CAAC;AAEX,+BAA+B;AAC/B,uCAAuC;AACvC,MAAM,UAAU,OAAO,CAAC,CAAU;IAChC,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1E,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QAChD,IAAK,CAAS,CAAC,CAAC,CAAC;YAAE,OAAO,CAA4B,CAAC;IACzD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/db/connect.d.ts

@@ -1,16 +1,26 @@
 import { Kysely } from 'kysely';
 import pg from 'pg';
+/** 内核自建连接的所有权句柄；close 销毁 Kysely 及底层池，调用方不应继续复用它。 */
 export interface DbHandle {
     db: Kysely<any>;
     pool: pg.Pool;
     close(): Promise<void>;
 }
+/**
+ * 创建一个独立账号的连接池，所有超时均以毫秒计；构造池不等于已验证数据库可连通。
+ * 读账号与写账号分别建池，避免会话权限混用。onConnect 是连接事件钩子，不承担迁移或账号初始化。
+ * 默认的连接、语句、空闲事务时限让池耗尽和遗留事务可失败退出，不能用无限等待隐藏锁问题。
+ */
 export declare function connect(url: string, opts?: {
     max?: number;
     onConnect?: (c: pg.PoolClient) => Promise<void>;
     applicationName?: string;
+    connectionTimeoutMs?: number;
+    statementTimeoutMs?: number;
+    idleTransactionTimeoutMs?: number;
 }): DbHandle;
 /** 单独的长连接（LISTEN、咨询锁用），不进连接池 */
+/** 成功返回已连接客户端；调用方必须 end，并在网络断开时重建 LISTEN/咨询锁状态。 */
 export declare function dedicatedClient(url: string, applicationName?: string): Promise<pg.Client>;
 export interface DatabaseUrls {
     /** 内核账号 cage_app */
@@ -25,4 +35,8 @@ export interface DatabaseUrls {
  *   CAGE_APP_DATABASE_URL / CAGE_READ_DATABASE_URL / CAGE_MIGRATE_DATABASE_URL
  * 或只给一个 DATABASE_URL（主机、端口、库名），各账号用默认用户名和 CAGE_DB_PASSWORD。
  */
+/**
+ * 专用连接串优先于 DATABASE_URL 派生值；仅解析配置，不创建数据库、角色或重置密码。
+ * 返回值含凭据，应只传给连接层，排障时提取主机/端口/库名而不要输出整个对象。
+ */
 export declare function urlsFromEnv(env?: NodeJS.ProcessEnv): DatabaseUrls;

package/dist/db/connect.js

@@ -12,8 +12,19 @@ const types = {
         return p ?? pg.types.getTypeParser(oid, format);
     },
 };
+/**
+ * 创建一个独立账号的连接池，所有超时均以毫秒计；构造池不等于已验证数据库可连通。
+ * 读账号与写账号分别建池，避免会话权限混用。onConnect 是连接事件钩子，不承担迁移或账号初始化。
+ * 默认的连接、语句、空闲事务时限让池耗尽和遗留事务可失败退出，不能用无限等待隐藏锁问题。
+ */
 export function connect(url, opts = {}) {
-    const pool = new pg.Pool({ connectionString: url, max: opts.max ?? 10, types: types, application_name: opts.applicationName ?? 'cage' });
+    // 池耗尽和遗留事务都必须有界；加大连接池不能修复持有连接再等待同池连接的循环。
+    const pool = new pg.Pool({
+        connectionString: url, max: opts.max ?? 10, types: types, application_name: opts.applicationName ?? 'cage',
+        connectionTimeoutMillis: opts.connectionTimeoutMs ?? 5_000,
+        statement_timeout: opts.statementTimeoutMs ?? 30_000,
+        idle_in_transaction_session_timeout: opts.idleTransactionTimeoutMs ?? 30_000,
+    });
     if (opts.onConnect)
         pool.on('connect', (c) => void opts.onConnect(c));
     const db = new Kysely({ dialect: new PostgresDialect({ pool }) });
@@ -26,8 +37,9 @@ export function connect(url, opts = {}) {
     };
 }
 /** 单独的长连接（LISTEN、咨询锁用），不进连接池 */
+/** 成功返回已连接客户端；调用方必须 end，并在网络断开时重建 LISTEN/咨询锁状态。 */
 export async function dedicatedClient(url, applicationName = 'cage-listener') {
-    const c = new pg.Client({ connectionString: url, types: types, application_name: applicationName });
+    const c = new pg.Client({ connectionString: url, types: types, application_name: applicationName, connectionTimeoutMillis: 5_000, statement_timeout: 30_000 });
     await c.connect();
     return c;
 }
@@ -36,6 +48,10 @@ export async function dedicatedClient(url, applicationName = 'cage-listener') {
  *   CAGE_APP_DATABASE_URL / CAGE_READ_DATABASE_URL / CAGE_MIGRATE_DATABASE_URL
  * 或只给一个 DATABASE_URL（主机、端口、库名），各账号用默认用户名和 CAGE_DB_PASSWORD。
  */
+/**
+ * 专用连接串优先于 DATABASE_URL 派生值；仅解析配置，不创建数据库、角色或重置密码。
+ * 返回值含凭据，应只传给连接层，排障时提取主机/端口/库名而不要输出整个对象。
+ */
 export function urlsFromEnv(env = process.env) {
     const base = env.DATABASE_URL;
     const derive = (user, pwVar) => {

package/dist/db/connect.js.map

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

package/dist/db/ddl.d.ts

@@ -1,10 +1,13 @@
 import type { AnyAggregate } from '../primitives/aggregate.js';
 import type { Registry } from '../registry.js';
+/** SQL 标识符引用，双引号转义；仅用于已由声明验证的名称，不接受任意 SQL 片段。 */
 export declare const q: (ident: string) => string;
+/** 模式和表名分别引用，避免把含点名称误当成一个未限定标识符。 */
 export declare const qt: (t: {
     schema: string;
     name: string;
 }) => string;
+/** 可序列化物理列规格；它描述期望结构，迁移执行前还需审查旧数据兼容性。 */
 export interface ColumnModel {
     name: string;
     type: string;
@@ -15,48 +18,84 @@ export interface ColumnModel {
     /** 枚举取值（CHECK 约束） */
     values?: string[];
 }
+/** 普通聚合表与自动关联表共享模型；relation 存在时没有普通聚合的状态和版本语义。 */
 export interface TableModel {
     schema: string;
     name: string;
     aggregate: string;
     columns: ColumnModel[];
     statusValues: string[];
-    /** 普通索引：名字 → 列 */
+    /** 索引也表达租户复合唯一键，供自动关系表的复合外键引用。 */
     indexes: {
         name: string;
         columns: string[];
+        unique?: boolean;
     }[];
+    /** 物理关联表不是聚合：没有状态、版本、独立命令和能力点。 */
+    relation?: {
+        field: string;
+        source: string;
+        target: string;
+    };
 }
+/** 随迁移嵌入的结构快照，version 是此序列化格式版本，不是应用或数据库迁移号。 */
 export interface SchemaModel {
     version: 1;
     tables: TableModel[];
 }
+/**
+ * 从字段/状态/范围生成主表列和索引，集合关系不作为主表列。
+ * 参与 manyToMany 的主表补租户/id 复合唯一键，让关联外键在数据库层保证双方租户一致。
+ */
 export declare function tableModel(agg: AnyAggregate, reg: Registry): TableModel;
 /** 按外键依赖排序：被引用的表在前 */
 export declare function schemaModel(reg: Registry): SchemaModel;
+/**
+ * 生成建表与索引 SQL，不执行它。普通表创建状态约束，关联表创建租户复合主键和双方外键。
+ * 仅关联表授予删除链接权限；普通业务对象的删除仍应由命令状态迁移表达。
+ */
 export declare function createTableSql(t: TableModel): string;
 /**
  * 比较两份结构，生成迁移草稿语句。破坏性变更（删表、删列）只生成注释，按「先扩展再收缩」由人决定。
  */
+/**
+ * prev 为迁移中的历史期望快照，null 表示首次建表；这里不会连接数据库扫描实际结构。
+ * 非空新增列和类型变化会生成待审查步骤，删除只给注释；自动草稿不保证既有数据能够直接迁移。
+ */
 export declare function diffSchemas(prev: SchemaModel | null, next: SchemaModel): string[];
+/** 数据库范围函数与 scope/index.ts 保持同口径；缺少身份/授权会保守拒绝，不默认开放全部。 */
 export declare const IN_SCOPE_SQL = "\n-- \u751F\u6210\u7269\uFF1A\u8303\u56F4\u5224\u65AD\u3002\u8BFB\u53D6\u4F1A\u8BDD\u53D8\u91CF app.scopes\uFF08{\"\u805A\u5408\":[{\"c\":\"\u7EC4\u5408\u5B50\",\"deptIds\":[...]}]}\uFF09\uFF0C\u591A\u4E2A\u6388\u6743\u53D6\u5E76\u96C6\u3002\n-- SECURITY DEFINER\uFF1A\u4EE5\u8868\u5C5E\u4E3B\u8EAB\u4EFD\u8BFB\u90E8\u95E8\u8868\uFF0C\u907F\u514D\u90E8\u95E8\u8868\u81EA\u5DF1\u7684\u884C\u7EA7\u7B56\u7565\u9012\u5F52\u3002\nCREATE OR REPLACE FUNCTION sys.in_scope(agg text, dept uuid, owner uuid)\nRETURNS boolean LANGUAGE sql STABLE SECURITY DEFINER SET search_path = pg_catalog, sys AS $$\n  SELECT coalesce(bool_or(\n    CASE g->>'c'\n      WHEN 'all' THEN true\n      WHEN 'self' THEN owner IS NOT NULL AND owner = nullif(current_setting('app.user_id', true), '')::uuid\n      WHEN 'dept' THEN dept IS NOT NULL AND dept = nullif(current_setting('app.dept_id', true), '')::uuid\n      WHEN 'deptSubtree' THEN dept IN (\n        SELECT d.id FROM sys.dept d\n        WHERE d.ancestors LIKE nullif(current_setting('app.dept_path', true), '') || '%')\n      WHEN 'deptSet' THEN dept = ANY (ARRAY(SELECT jsonb_array_elements_text(coalesce(g->'deptIds', '[]'::jsonb)))::uuid[])\n      ELSE false\n    END), false)\n  FROM jsonb_array_elements(coalesce(\n    nullif(current_setting('app.scopes', true), '')::jsonb -> agg,\n    nullif(current_setting('app.scopes', true), '')::jsonb -> '*',\n    '[{\"c\":\"self\"}]'::jsonb)) AS g\n$$;";
+/** 安全视图使用的字段掩码函数；明文权限来自事务会话变量，展示策略须与内存 maskValue 一致。 */
 export declare const MASK_SQL = "\n-- \u751F\u6210\u7269\uFF1A\u6309\u654F\u611F\u79CD\u7C7B\u63A9\u7801\u3002\u6301\u6709\u300C\u805A\u5408.\u79CD\u7C7B\u300D\u660E\u6587\u6743\u9650\u65F6\u539F\u6837\u8FD4\u56DE\u3002\nCREATE OR REPLACE FUNCTION sys.mask(agg text, kind text, val text)\nRETURNS text LANGUAGE sql STABLE AS $$\n  SELECT CASE\n    WHEN val IS NULL THEN NULL\n    WHEN (agg || '.' || kind) = ANY (string_to_array(coalesce(current_setting('app.unmask', true), ''), ','))\n      OR ('*.' || kind) = ANY (string_to_array(coalesce(current_setting('app.unmask', true), ''), ',')) THEN val\n    WHEN kind = 'phone' THEN CASE WHEN length(val) >= 7 THEN left(val, 3) || '****' || right(val, 4) ELSE '****' END\n    WHEN kind = 'idCard' THEN CASE WHEN length(val) >= 8 THEN left(val, 4) || '**********' || right(val, 4) ELSE '****' END\n    WHEN kind = 'bankCard' THEN '**** **** **** ' || right(val, 4)\n    WHEN kind = 'email' THEN CASE WHEN strpos(val, '@') > 1 THEN left(val, 1) || '***' || substr(val, strpos(val, '@')) ELSE '******' END\n    WHEN kind = 'name' THEN left(val, 1) || '**'\n    WHEN kind = 'address' THEN left(val, 6) || '******'\n    ELSE '******'\n  END\n$$;";
+/**
+ * 为单聚合生成 RLS 和 security_barrier 安全视图；hidden/关系字段不投影，敏感字段调用 sys.mask。
+ * cage_read 只有视图 SELECT，视图属主受到范围策略；cage_app 的写入授权由内核流水线执行。
+ */
 export declare function aggregateSafeSql(agg: AnyAggregate): string;
+/** 系统审计视图只做租户过滤，系统管理接口还需检查 Sys.audit.read 等能力。 */
 export declare const SYSTEM_SAFE_SQL = "\n-- \u5BA1\u8BA1\u67E5\u8BE2\u89C6\u56FE\uFF1A\u8BFB\u4FA7\u8D26\u53F7\u7ECF\u7CFB\u7EDF\u7BA1\u7406\u63A5\u53E3\u4F7F\u7528\uFF0C\u6309\u79DF\u6237\u8FC7\u6EE4\nDROP VIEW IF EXISTS safe.audit_log;\nCREATE VIEW safe.audit_log WITH (security_barrier) AS\n  SELECT id, at, actor, actor_kind, on_behalf_of, source, kind, capability, command, aggregate, aggregate_id,\n         result, diff, request_id, idempotency_key, client\n  FROM sys.audit_log\n  WHERE tenant_id = nullif(current_setting('app.tenant_id', true), '')::uuid;\nALTER VIEW safe.audit_log OWNER TO cage_view_owner;\nGRANT SELECT ON safe.audit_log TO cage_read;";
 /** 整个安全层：先删掉旧的 safe 视图，再按声明重建（幂等） */
+/** 主视图先于关系视图重建；关系视图连接双方安全视图，因此来源/目标范围和逻辑删除都生效。 */
 export declare function safeLayerSql(reg: Registry): string;
+/** 初始化专用账号所需秘密；仅用于生成/执行受控初始化 SQL，不应写入源码、日志或公开文档。 */
 export interface BootstrapPasswords {
     app: string;
     read: string;
     migrate: string;
 }
 /** 建库时执行一次（超级用户）：模式、账号、默认权限 */
+/**
+ * 为已有数据库生成模式、角色与默认权限 SQL；函数本身不执行、不建库，也不提供业务数据初始化。
+ * SQL 含密码且会调整既有同名账号，调用方必须先核对集群角色复用策略，不能直接用于普通 dev 启动。
+ */
 export declare function bootstrapSql(pw: BootstrapPasswords, dbName?: string): string;
 /** 单租户部署使用的默认租户（启用多租户时每个租户一行 sys.tenant） */
 export declare const DEFAULT_TENANT = "00000000-0000-4000-8000-000000000001";
 /** 框架系统表（框架自己的迁移流，按名字记入 sys.schema_migrations） */
+/** 系统迁移按数组顺序前向执行；历史 SQL（包括字符串内注释）参与 checksum，必须保持不可变。 */
 export declare const SYSTEM_MIGRATIONS: {
     name: string;
     sql: string;
 }[];
+/** 迁移账本记录名称、摘要及提交时间；执行器先建账本，再校验全部已执行文件内容。 */
 export declare const SCHEMA_MIGRATIONS_SQL = "\nCREATE TABLE IF NOT EXISTS sys.schema_migrations (\n  name text PRIMARY KEY,\n  checksum text,\n  applied_at timestamptz NOT NULL DEFAULT now()\n);";