@yss123/cage-kernel 0.2.0 → 0.3.1

package/dist/files/schema.js

@@ -0,0 +1,51 @@
+// 追加系统迁移，文件字节不进入数据库、审计或 outbox。
+/**
+ * 上传会话记录用户、目标命令/字段、字节政策和幂等摘要；bound 与 bound_id 的约束固定文件归属。
+ * 分片由 upload_id/number 唯一定位，token/lease_until 解决并发写入和中断恢复，storage_key 指向字节存储。
+ * bound 文件不按临时会话过期清理；SQL 是历史迁移，修改结构须追加迁移而非编辑字符串。
+ */
+export const FILE_MIGRATION = {
+    name: 'cage:0004_files',
+    sql: `
+CREATE TABLE sys.file_upload (
+  id uuid PRIMARY KEY,
+  tenant_id uuid NOT NULL,
+  user_id uuid NOT NULL,
+  aggregate_name text NOT NULL,
+  field_name text NOT NULL,
+  command_name text NOT NULL,
+  target_id uuid,
+  filename text NOT NULL,
+  content_type text NOT NULL,
+  bytes bigint NOT NULL CHECK (bytes > 0),
+  part_bytes int NOT NULL CHECK (part_bytes > 0),
+  part_count int NOT NULL CHECK (part_count > 0),
+  storage text NOT NULL,
+  storage_key text,
+  status text NOT NULL CHECK (status IN ('uploading','completing','ready','bound','deleting','deleted')),
+  bound_id uuid,
+  operation_token uuid,
+  lease_until timestamptz,
+  pruned_at timestamptz,
+  idempotency_key text NOT NULL,
+  request_hash text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  expires_at timestamptz NOT NULL DEFAULT now() + interval '24 hours',
+  UNIQUE (tenant_id, user_id, idempotency_key),
+  CHECK ((status = 'bound') = (bound_id IS NOT NULL))
+);
+CREATE INDEX file_upload_owner_idx ON sys.file_upload(tenant_id, user_id, created_at DESC);
+CREATE INDEX file_upload_expiry_idx ON sys.file_upload(expires_at) WHERE status <> 'bound';
+CREATE TABLE sys.file_part (
+  upload_id uuid NOT NULL REFERENCES sys.file_upload(id),
+  number int NOT NULL CHECK (number > 0),
+  bytes int NOT NULL CHECK (bytes > 0),
+  sha256 text NOT NULL,
+  token uuid NOT NULL,
+  storage_key text,
+  lease_until timestamptz,
+  PRIMARY KEY (upload_id, number)
+);
+`,
+};
+//# sourceMappingURL=schema.js.map

package/dist/files/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/files/schema.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,IAAI,EAAE,iBAAiB;IACvB,GAAG,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwCN;CACA,CAAC"}

package/dist/index.d.ts

@@ -1,16 +1,25 @@
+/**
+ * 公共入口按声明原语、执行服务和基础类型组织；业务应优先消费声明与受限运行接口。
+ * 数据库迁移/连接与 worker 生命周期另有子路径入口，浏览器只依赖生成契约和 client。
+ * 增加导出意味着扩大公开 API，应同步能力发现和学习资料，不能仅凭实现文件存在让应用深层导入。
+ */
 export * from './brands.js';
 export * from './errors.js';
 export * from './types.js';
-export { Field, text, int, number, money, id, date, datetime, bool, enumOf, ref, hasMany, manyToMany, isRelation, list, json, isField, objectSchema, SENSITIVE_KINDS, type SensitiveKind, type FieldKind, type FieldMeta, type AnyField, type Fields, type FieldValues, type ValueOf, } from './primitives/fields.js';
+export { runtimeServices, type RuntimeDefinition, type RuntimeService } from './runtime.js';
+export { Field, text, int, number, money, id, date, datetime, bool, enumOf, ref, hasMany, manyToMany, isRelation, file, files, isFile, list, json, isField, objectSchema, SENSITIVE_KINDS, type SensitiveKind, type FieldKind, type FieldMeta, type FilePolicy, type AnyField, type Fields, type FieldValues, type ValueOf, } from './primitives/fields.js';
 export { states, isStates, DEFAULT_STATES, type StatesDef } from './primitives/states.js';
+export { businessProcess, type BusinessProcess, type BusinessStage, type BusinessAction, type BusinessTransition } from './primitives/business-process.js';
 export { aggregate, isAggregate, hasStates, hiddenFields, sensitiveFields, RESERVED_FIELDS, type Aggregate, type AnyAggregate, type Snapshot, type SnapshotOf, type StateOf, type FieldsOf, type FieldValuesOf, type SystemCols, } from './primitives/aggregate.js';
 export { command, isCommand, idOnly, empty, type Command, type AnyCommand, type Reads, type ReadRepo, type DepsOf, type Draft, type HandlerCtx, type HandlerResult, type Invoker, type FindOptions, } from './primitives/command.js';
 export { event, emit, isEvent, defaultPayload, type Event, type AnyEvent, type PayloadOf, type EmitSpec } from './primitives/event.js';
+export { reactionEach, reactionInputs } from './primitives/collection.js';
 export { sod, ceiling, stepUp, ok, violation, type Constraint, type ConstraintResult, type ConstraintMeta, } from './primitives/constraints.js';
 export { reaction, query, approval, job, unsafe, daysAgo, type Reaction, type AnyReaction, type Query, type AnyQuery, type Approval, type Job, type JobApi, type JobQueryApi, type TxMode, type UnsafeTag, } from './primitives/flow.js';
 export { scope, compileScope, compileGrant, scopeMatches, grantsFor, DEFAULT_GRANTS, type ScopeSpec } from './scope/index.js';
-export { buildRegistry, type Registry, type RegisteredCommand, type CatalogEntry, type RegistryOptions, type RuntimeExtension } from './registry.js';
+export { buildRegistry, registryFingerprint, type Registry, type RegisteredCommand, type CatalogEntry, type RegistryOptions, type RuntimeExtension } from './registry.js';
 export { Kernel, createKernel, type KernelOptions, type AuditEntry, type BatchResult, type EmittedEvent } from './kernel.js';
+export { explainAuthorization, type AuthorizationCheck } from './authorization.js';
 export { ReadSide, compileNamedSql, type ListParams, type Page } from './read.js';
 export { DataTransfers, importRequestSchema, type TransferTask } from './transfer/index.js';
 export { maskValue, present, canUnmask, auditDiff } from './mask.js';

package/dist/index.js

@@ -1,17 +1,26 @@
 // @yss123/cage-kernel：声明原语、写入流水线、范围组合子、读侧上下文。不含任何业务名词。
+/**
+ * 公共入口按声明原语、执行服务和基础类型组织；业务应优先消费声明与受限运行接口。
+ * 数据库迁移/连接与 worker 生命周期另有子路径入口，浏览器只依赖生成契约和 client。
+ * 增加导出意味着扩大公开 API，应同步能力发现和学习资料，不能仅凭实现文件存在让应用深层导入。
+ */
 export * from './brands.js';
 export * from './errors.js';
 export * from './types.js';
-export { Field, text, int, number, money, id, date, datetime, bool, enumOf, ref, hasMany, manyToMany, isRelation, list, json, isField, objectSchema, SENSITIVE_KINDS, } from './primitives/fields.js';
+export { runtimeServices } from './runtime.js';
+export { Field, text, int, number, money, id, date, datetime, bool, enumOf, ref, hasMany, manyToMany, isRelation, file, files, isFile, list, json, isField, objectSchema, SENSITIVE_KINDS, } from './primitives/fields.js';
 export { states, isStates, DEFAULT_STATES } from './primitives/states.js';
+export { businessProcess } from './primitives/business-process.js';
 export { aggregate, isAggregate, hasStates, hiddenFields, sensitiveFields, RESERVED_FIELDS, } from './primitives/aggregate.js';
 export { command, isCommand, idOnly, empty, } from './primitives/command.js';
 export { event, emit, isEvent, defaultPayload } from './primitives/event.js';
+export { reactionEach, reactionInputs } from './primitives/collection.js';
 export { sod, ceiling, stepUp, ok, violation, } from './primitives/constraints.js';
 export { reaction, query, approval, job, unsafe, daysAgo, } from './primitives/flow.js';
 export { scope, compileScope, compileGrant, scopeMatches, grantsFor, DEFAULT_GRANTS } from './scope/index.js';
-export { buildRegistry } from './registry.js';
+export { buildRegistry, registryFingerprint } from './registry.js';
 export { Kernel, createKernel } from './kernel.js';
+export { explainAuthorization } from './authorization.js';
 export { ReadSide, compileNamedSql } from './read.js';
 export { DataTransfers, importRequestSchema } from './transfer/index.js';
 export { maskValue, present, canUnmask, auditDiff } from './mask.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,OAAO,EACL,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,EAC1I,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAkB,MAAM,wBAAwB,CAAC;AAC1F,OAAO,EACL,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,YAAY,EAAE,eAAe,EAAE,eAAe,GAElF,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,GAElC,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,EAA4D,MAAM,uBAAuB,CAAC;AACvI,OAAO,EACL,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,GACpC,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,GAEhD,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,cAAc,EAAkB,MAAM,kBAAkB,CAAC;AAC9H,OAAO,EAAE,aAAa,EAAyG,MAAM,eAAe,CAAC;AACrJ,OAAO,EAAE,MAAM,EAAE,YAAY,EAA4E,MAAM,aAAa,CAAC;AAC7H,OAAO,EAAE,QAAQ,EAAE,eAAe,EAA8B,MAAM,WAAW,CAAC;AAClF,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAqB,MAAM,qBAAqB,CAAC;AAC5F,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACrE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAsC,MAAM,UAAU,CAAC;AACpJ,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAe,MAAM,gBAAgB,CAAC;AAC3G,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvG,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAqB,MAAM,iBAAiB,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD;;;;GAIG;AACH,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,eAAe,EAA+C,MAAM,cAAc,CAAC;AAC5F,OAAO,EACL,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,EAC/J,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAkB,MAAM,wBAAwB,CAAC;AAC1F,OAAO,EAAE,eAAe,EAA0F,MAAM,kCAAkC,CAAC;AAC3J,OAAO,EACL,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,YAAY,EAAE,eAAe,EAAE,eAAe,GAElF,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,GAElC,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,EAA4D,MAAM,uBAAuB,CAAC;AACvI,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC1E,OAAO,EACL,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,GACpC,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,GAEhD,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,cAAc,EAAkB,MAAM,kBAAkB,CAAC;AAC9H,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAyG,MAAM,eAAe,CAAC;AAC1K,OAAO,EAAE,MAAM,EAAE,YAAY,EAA4E,MAAM,aAAa,CAAC;AAC7H,OAAO,EAAE,oBAAoB,EAA2B,MAAM,oBAAoB,CAAC;AACnF,OAAO,EAAE,QAAQ,EAAE,eAAe,EAA8B,MAAM,WAAW,CAAC;AAClF,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAqB,MAAM,qBAAqB,CAAC;AAC5F,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACrE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAsC,MAAM,UAAU,CAAC;AACpJ,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAe,MAAM,gBAAgB,CAAC;AAC3G,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvG,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAqB,MAAM,iBAAiB,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/kernel.d.ts

@@ -8,81 +8,166 @@ import { type RegisteredCommand, type Registry, type RegistryOptions } from './r
 import { type Logger } from './telemetry.js';
 import type { CapabilityParams, Ctx } from './types.js';
 import { DataTransfers } from './transfer/index.js';
+/** 内核实例配置；传 db 时连接归宿主所有，传 urls 时内核自行创建并在 close 时销毁池。 */
 export interface KernelOptions {
     /** domain 包的导出（可以是多个模块，例如框架自带的组织模型 + 业务声明） */
     domain: object | object[];
     /** 数据库连接串；或者直接传入已有的连接 */
     urls?: DatabaseUrls;
+    /** 宿主注入的写库与只读库句柄；提供后优先于 urls，close 不销毁这些外部连接。 */
     db?: {
         app: Kysely<any>;
         read: Kysely<any>;
     };
+    /** 注册表的额外能力等选项；不用于运行期动态改变角色授权。 */
     registryOptions?: RegistryOptions;
+    /** 结构化日志实现；省略时使用默认 consoleLogger，调用方仍不能在元数据中塞入敏感业务原文。 */
     logger?: Logger;
     /** 同事务反应的最大嵌套深度 */
     maxReactionDepth?: number;
     /** 连接池大小 */
     poolSize?: number;
 }
+/** 当前事务已登记的事件，含 outbox ID；事务尚未提交时不可将其视为外部已收到的事实。 */
 export interface EmittedEvent {
+    /** 同事务写入的 outbox 数字 ID，用于关联投递记录；不是业务对象 ID。 */
     outboxId: number;
+    /** 已注册的事件名称，决定匹配哪些消费者。 */
     event: string;
+    /** 通过事件 schema 校验的业务载荷，仅供内部消费者使用，不可直接作为公共诊断响应。 */
     payload: Record<string, unknown>;
 }
+/** index 为输入行的 0 基索引；atomic 模式任一失败会把其余行标为已回滚，不能交付暂存成功结果。 */
 export interface BatchResult {
+    /** 输入 rows 中从零开始的位置，调用方据此对应原始导入行。 */
     index: number;
+    /** 该行最终是否成功提交；整批原子失败时此前暂存成功也会被改为失败。 */
     ok: boolean;
+    /** 成功时可交付的记录快照，已按主体权限处理敏感字段；失败时省略。 */
     data?: Record<string, unknown>;
+    /** 失败时的框架错误码、可选领域码和详情；不包含成功数据。 */
     error?: {
         code: string;
         domainCode?: string;
         detail?: unknown;
     };
 }
+/** 审计写入规格；diff/client 必须由可信调用方脱敏，writeAudit 不推断业务字段的敏感政策。 */
 export interface AuditEntry {
+    /** 审计所属租户，必须来自可信执行上下文。 */
     tenantId: string;
+    /** 实际执行主体标识，可能是真人用户 ID 或流程/任务身份名。 */
     actor: string;
+    /** 执行主体种类，与 actor 共同解释身份；不能仅凭字符串把系统主体当作真人。 */
     actorKind: string;
+    /** 系统执行代表的真人 ID；没有委托时省略或 null。 */
     onBehalfOf?: string | null;
+    /** 触发入口来源，如 api、process、job、external；用于追踪，不授予权限。 */
     source: string;
+    /** write 业务写审计、read 读取审计、denied 拒绝记录、ops 运维动作。 */
     kind: 'write' | 'read' | 'denied' | 'ops';
+    /** 本次操作关联的能力名；无单一能力时可空。 */
     capability?: string | null;
+    /** 关联的完整命令名；读取或普通运维事件可空。 */
     command?: string | null;
+    /** 关联聚合名；无具体业务对象时可空。 */
     aggregate?: string | null;
+    /** 单一关联记录 ID；多记录读取或无对象时可空。 */
     aggregateId?: string | null;
+    /** 执行结论或机器错误码，由调用者按实际提交/拒绝结果填写。 */
     result: string;
+    /** 经调用方脱敏的变化或操作摘要；writeAudit 不替调用方恢复字段策略。 */
     diff?: unknown;
+    /** 跨 HTTP、命令和异步事件关联的追踪标识；省略或 null 表示未提供。 */
     requestId?: string | null;
+    /** 本次逻辑提交的去重键，仅记录审计关联，不在本方法执行去重。 */
     idempotencyKey?: string | null;
+    /** 调用方允许记录的客户端摘要，例如 IP/UA；不得包含 Cookie、密码或完整请求体。 */
     client?: unknown;
 }
+/**
+ * 领域写入的统一执行器。权限、版本、状态、约束、不变量、关联、审计和事件在此汇合，
+ * 业务 handler 仅计算字段变化，不能越过这些阶段。读服务使用独立账号，worker 复用注册规格。
+ * 实例关闭只释放自身创建的池；运行时扩展和 worker 的生命周期由其装配方先行停止。
+ */
 export declare class Kernel {
+    /** 解释能力、范围、状态及约束的当前证据，不执行 handler 或提交业务写入；结果不是未来执行一定成功的承诺。 */
+    explain(capability: string, input: Record<string, unknown>, ctx: Ctx): Promise<{
+        command: string;
+        actor: import("./types.js").Actor | null;
+        observedAt: string;
+        allowed: boolean;
+        checks: import("./authorization.js").AuthorizationCheck[];
+        scope?: undefined;
+        params?: undefined;
+        limitations?: undefined;
+    } | {
+        command: string;
+        actor: import("./types.js").Actor | null;
+        observedAt: string;
+        allowed: boolean | null;
+        checks: import("./authorization.js").AuthorizationCheck[];
+        scope: import("./types.js").ScopeGrant[];
+        params: CapabilityParams;
+        limitations: string[];
+    }>;
+    /** 由 domain 导出建立的运行规格，供命令解析、读侧、DDL 和 worker 共享。 */
     readonly registry: Registry;
+    /** 内部写账号连接；业务应用应走命令，不能据此绕过流水线直接写表。 */
     readonly app: Kysely<any>;
+    /** 只读账号连接，用于 safe 视图事务；不能用写账号代替以省略数据库权限隔离。 */
     readonly readDb: Kysely<any>;
+    /** 按当前 Ctx 授权、范围与掩码读取的公共读服务。 */
     readonly read: ReadSide;
+    /** 后台导入导出协调器，任务状态和结果文件不等同于单次同步读写返回。 */
     readonly transfers: DataTransfers;
+    /** 实例日志出口，用于安全元数据与机器码，不传未经处理的敏感业务数据。 */
     readonly log: Logger;
     private readonly handles;
     private readonly maxDepth;
     constructor(opts: KernelOptions);
+    /** 释放由本实例创建的数据库句柄；外部注入 db 不在 handles 中，不会被擅自销毁。 */
     close(): Promise<void>;
+    /** 按能力字符串或声明对象解析命令；未从 domain 导出时明确报错，不动态注册陌生命令。 */
     resolve(ref: string | AnyCommand): RegisteredCommand;
     /** 执行一个命令（自己开事务）。返回按当前主体掩码后的新快照。 */
+    /**
+     * 事务拥有者：run 任一阶段失败都会回滚，最终返回掩码后的结果或已提交幂等回放。
+     * 预期拒绝转换为统一错误；部分拒绝另做尽力审计，审计失败不改变原请求的拒绝结论。
+     */
     execute(ref: string | AnyCommand, raw: unknown, ctx: Ctx): Promise<Record<string, any>>;
     /** 在已有事务里执行（同事务反应、审批桥接、批量整批原子模式用）。返回未掩码的快照。 */
+    /** 外层持有提交权；返回完整内部快照只供受信任框架流程使用，不可直接写入 HTTP 响应。 */
     executeIn(tx: Transaction<any>, ref: string | AnyCommand, raw: unknown, ctx: Ctx, depth?: number): Promise<Record<string, any>>;
+    /** 可选服务在同一事务登记执行回执时使用；只返回可交付字段，避免泄漏内部快照。 */
+    executePresentedIn(tx: Transaction<any>, ref: string | AnyCommand, raw: unknown, ctx: Ctx): Promise<Record<string, any>>;
     /** 批量写入：每一行都完整走 12 关；默认逐行独立提交，可选整批原子。批量没有快捷路径。 */
     executeBatch(ref: string | AnyCommand, rows: unknown[], ctx: Ctx, opts?: {
         atomic?: boolean;
     }): Promise<BatchResult[]>;
+    /**
+     * 完整事务流水线：输入/身份→幂等→加锁加载→状态/版本→硬约束→受限 handler→合并/不变量→持久化。
+     * 写记录、关系、附件、成功审计、outbox 和 same 反应共同提交；任何失败都必须传播到事务拥有者。
+     * depth 限制同事务递归，只在最外层使用请求幂等键，避免不同反应错误共享同一回放结果。
+     * next 是内部完整快照，presented 是可交付快照，replay 是已有请求结果，三者用途不可混淆。
+     */
     private run;
+    /**
+     * 在业务事务内映射并校验每个事件，遮盖敏感载荷后持久化提交版本、真人委托与追踪上下文。
+     * 任一映射/schema 错误使整个命令回滚；NOTIFY 也随事务提交生效，不会唤醒 worker 消费未提交数据。
+     */
     private enqueueEvents;
+    /**
+     * 只负责持久化审计，不吞异常。传事务时与业务共同提交；可靠读审计失败应阻止交付明文。
+     * 拒绝审计等尽力路径由上层自行 catch，不能在此统一忽略错误而破坏成功写入的审计保证。
+     */
     writeAudit(db: Transaction<any> | Kysely<any>, e: AuditEntry): Promise<void>;
     /** 被拒绝的尝试异步记录，用于发现探测和配置问题；记录失败不影响请求 */
     auditDenied(rc: RegisteredCommand, raw: unknown, ctx: Ctx, err: CageError): Promise<void>;
     private catalogCache?;
+    /** 当前实例注册表固定，故可缓存能力名称；角色实际授权仍需按用户从数据库读取。 */
     catalogCaps(): string[];
+    /** 实时加载真人能力供额度约束使用；用户不存在或禁用时返回空集合。 */
     capabilitiesOf(userId: string, tenantId: string): Promise<Map<string, CapabilityParams>>;
     /** 把一个用户解析成上下文（HTTP 层会加缓存） */
     contextFor(userId: string, tenantId: string, extra?: Partial<Ctx>): Promise<Ctx | null>;
@@ -95,5 +180,6 @@ export declare class Kernel {
         requestId?: string;
     }): Ctx;
 }
+/** 构造注册表、连接句柄及读/传输服务；不会自动迁移、初始化组织或启动 worker。 */
 export declare function createKernel(opts: KernelOptions): Kernel;
 export type { AnyAggregate };

package/dist/kernel.js

@@ -1,6 +1,3 @@
-// 内核：唯一的写入入口 execute。HTTP、审批流程、定时任务、反应、批量导入都调用它，
-// 所以检查只写一遍，顺序永远一样（设计文档第 5 节的 12 关）。
-import { randomUUID } from 'node:crypto';
 import { sql } from 'kysely';
 import { connect } from './db/connect.js';
 import { diffFields, fieldsToColumns } from './db/rows.js';
@@ -11,20 +8,38 @@ import { loadUserGrants, systemCtx, userCtx } from './org.js';
 import { bindReads, loadScoped } from './pipeline/load.js';
 import { idempotency } from './pipeline/idempotency.js';
 import { defaultPayload } from './primitives/event.js';
+import { reactionEntries, reactionEntryError } from './primitives/collection.js';
 import { ReadSide } from './read.js';
 import { buildRegistry } from './registry.js';
 import { consoleLogger, step, traceCarrier } from './telemetry.js';
 import { DataTransfers } from './transfer/index.js';
 import { writeRelations } from './relations.js';
+import { assertInvoker } from './pipeline/invoker.js';
+import { explainAuthorization } from './authorization.js';
+import { newDraft, splitRaw } from './pipeline/draft.js';
+import { writeFileLinks } from './files/links.js';
 function zodIssues(e) {
     return e.issues.map((i) => ({ path: i.path.join('.'), message: i.message }));
 }
+/**
+ * 领域写入的统一执行器。权限、版本、状态、约束、不变量、关联、审计和事件在此汇合，
+ * 业务 handler 仅计算字段变化，不能越过这些阶段。读服务使用独立账号，worker 复用注册规格。
+ * 实例关闭只释放自身创建的池；运行时扩展和 worker 的生命周期由其装配方先行停止。
+ */
 export class Kernel {
+    /** 解释能力、范围、状态及约束的当前证据，不执行 handler 或提交业务写入；结果不是未来执行一定成功的承诺。 */
+    explain(capability, input, ctx) { return explainAuthorization(this, capability, input, ctx); }
+    /** 由 domain 导出建立的运行规格，供命令解析、读侧、DDL 和 worker 共享。 */
     registry;
+    /** 内部写账号连接；业务应用应走命令，不能据此绕过流水线直接写表。 */
     app;
+    /** 只读账号连接，用于 safe 视图事务；不能用写账号代替以省略数据库权限隔离。 */
     readDb;
+    /** 按当前 Ctx 授权、范围与掩码读取的公共读服务。 */
     read;
+    /** 后台导入导出协调器，任务状态和结果文件不等同于单次同步读写返回。 */
     transfers;
+    /** 实例日志出口，用于安全元数据与机器码，不传未经处理的敏感业务数据。 */
     log;
     handles = [];
     maxDepth;
@@ -49,10 +64,12 @@ export class Kernel {
         this.read = new ReadSide(this);
         this.transfers = new DataTransfers(this);
     }
+    /** 释放由本实例创建的数据库句柄；外部注入 db 不在 handles 中，不会被擅自销毁。 */
     async close() {
         for (const h of this.handles)
             await h.close();
     }
+    /** 按能力字符串或声明对象解析命令；未从 domain 导出时明确报错，不动态注册陌生命令。 */
     resolve(ref) {
         const rc = this.registry.command(ref);
         if (!rc) {
@@ -62,6 +79,10 @@ export class Kernel {
     }
     // ---------------- 写入 ----------------
     /** 执行一个命令（自己开事务）。返回按当前主体掩码后的新快照。 */
+    /**
+     * 事务拥有者：run 任一阶段失败都会回滚，最终返回掩码后的结果或已提交幂等回放。
+     * 预期拒绝转换为统一错误；部分拒绝另做尽力审计，审计失败不改变原请求的拒绝结论。
+     */
     async execute(ref, raw, ctx) {
         const rc = this.resolve(ref);
         try {
@@ -81,11 +102,18 @@ export class Kernel {
         }
     }
     /** 在已有事务里执行（同事务反应、审批桥接、批量整批原子模式用）。返回未掩码的快照。 */
+    /** 外层持有提交权；返回完整内部快照只供受信任框架流程使用，不可直接写入 HTTP 响应。 */
     async executeIn(tx, ref, raw, ctx, depth = 1) {
         const rc = this.resolve(ref);
         const r = await this.run(tx, rc, raw, ctx, depth);
         return (r.next ?? r.replay);
     }
+    /** 可选服务在同一事务登记执行回执时使用；只返回可交付字段，避免泄漏内部快照。 */
+    async executePresentedIn(tx, ref, raw, ctx) {
+        const rc = this.resolve(ref);
+        const result = await this.run(tx, rc, raw, ctx, 0);
+        return result.presented ?? present(rc.cmd.agg, result.replay, ctx);
+    }
     /** 批量写入：每一行都完整走 12 关；默认逐行独立提交，可选整批原子。批量没有快捷路径。 */
     async executeBatch(ref, rows, ctx, opts = {}) {
         const rc = this.resolve(ref);
@@ -129,6 +157,12 @@ export class Kernel {
             }));
         }
     }
+    /**
+     * 完整事务流水线：输入/身份→幂等→加锁加载→状态/版本→硬约束→受限 handler→合并/不变量→持久化。
+     * 写记录、关系、附件、成功审计、outbox 和 same 反应共同提交；任何失败都必须传播到事务拥有者。
+     * depth 限制同事务递归，只在最外层使用请求幂等键，避免不同反应错误共享同一回放结果。
+     * next 是内部完整快照，presented 是可交付快照，replay 是已有请求结果，三者用途不可混淆。
+     */
     async run(tx, rc, raw, ctx, depth) {
         const { cmd, capability } = rc;
         const agg = cmd.agg;
@@ -166,12 +200,7 @@ export class Kernel {
         if (isNew) {
             // 新建：跳过第 4、5 关，由内核生成 id 和初始版本号；输入里的同名字段预填进草稿
             // 输入里带了 id（确定性主键，例如库存锁用采购单 id）时使用它，重复时报 CONFLICT
-            const givenId = typeof input.id === 'string' ? input.id : undefined;
-            cur = { id: givenId ?? randomUUID(), status: cmd.to, version: 0, createdAt: now.toISOString(), updatedAt: now.toISOString() };
-            for (const k of fieldKeys)
-                cur[k] = k in input ? input[k] : fields[k].kind === 'manyToMany' ? [] : null;
-            if (agg.scope.deptField && agg.scope.deptField !== 'id' && cur[agg.scope.deptField] == null)
-                cur[agg.scope.deptField] = ctx.deptId;
+            cur = newDraft(cmd, input, ctx, now);
         }
         else {
             if (typeof input.id !== 'string')
@@ -191,7 +220,12 @@ export class Kernel {
         // 第 6 关：硬约束
         const meta = {
             capability,
-            capabilitiesOf: (uid) => this.capabilitiesOf(uid, ctx.tenantId),
+            // 额度等约束复用当前写事务连接，避免同对象的并发等待者占满池后，锁持有者再借连接形成死锁。
+            // 仍实时加载角色并检查账号 active；不缓存能力，也不改变约束看到的权限集合。
+            capabilitiesOf: async (uid) => {
+                const grants = await loadUserGrants(tx, uid, ctx.tenantId);
+                return grants?.active ? grants.capabilities : new Map();
+            },
             load: async (aggName, id) => {
                 const a = this.registry.aggregate(aggName);
                 return a && /^[0-9a-f-]{36}$/i.test(id) ? loadScoped(tx, a, id, ctx, false) : null;
@@ -232,6 +266,11 @@ export class Kernel {
         for (const k of fieldKeys)
             if (fields[k].kind === 'manyToMany')
                 next[k] = [...new Set(next[k].map((id) => id.toLowerCase()))].sort();
+        for (const k of fieldKeys)
+            if (fields[k].kind === 'file' || fields[k].kind === 'files') {
+                next[k] = Array.isArray(next[k]) ? next[k].map((id) => id.toLowerCase()) : next[k]?.toLowerCase() ?? null;
+                record[k] = next[k];
+            }
         // 第 10 关：不变量
         for (const [name, fn] of Object.entries(agg.invariants)) {
             let holds = false;
@@ -271,6 +310,7 @@ export class Kernel {
         }
         next.updatedAt = now.toISOString();
         await writeRelations(tx, this.registry, agg, isNew ? {} : cur, next, ctx);
+        await writeFileLinks(tx, agg, isNew ? {} : cur, next, ctx);
         const changed = isNew ? fieldKeys.filter((k) => next[k] !== null) : diffFields(agg, cur, next);
         await this.writeAudit(tx, {
             tenantId: ctx.tenantId,
@@ -294,14 +334,18 @@ export class Kernel {
             for (const { r, name } of this.registry.reactionsFor(ev.event)) {
                 if (r.tx !== 'same')
                     continue;
-                const rin = r.map(ev.payload);
-                if (rin === null || rin === undefined)
-                    continue;
                 const rctx = systemCtx({
                     kind: 'reaction', name, tenantId: ctx.tenantId, capabilities: [this.registry.capabilityOf(r.command)],
                     onBehalfOf: actorUserId, requestId: ctx.requestId,
                 });
-                await this.run(tx, this.resolve(r.command), rin, rctx, depth + 1);
+                for (const entry of reactionEntries(r, ev.payload)) {
+                    try {
+                        await this.run(tx, this.resolve(r.command), entry.input, rctx, depth + 1);
+                    }
+                    catch (error) {
+                        throw reactionEntryError(error, r, name, entry);
+                    }
+                }
             }
         }
         if (agg.options.grants) {
@@ -314,6 +358,10 @@ export class Kernel {
         // 第 12 关：函数返回即提交事务；随后由 outbox 投递器异步分发事件
         return { next, presented };
     }
+    /**
+     * 在业务事务内映射并校验每个事件，遮盖敏感载荷后持久化提交版本、真人委托与追踪上下文。
+     * 任一映射/schema 错误使整个命令回滚；NOTIFY 也随事务提交生效，不会唤醒 worker 消费未提交数据。
+     */
     async enqueueEvents(tx, cmd, next, input, ctx, prev) {
         const out = [];
         if (cmd.emits.length === 0)
@@ -334,6 +382,7 @@ export class Kernel {
                 event: ev.name,
                 aggregate: cmd.agg.name,
                 aggregate_id: next.id,
+                aggregate_version: next.version,
                 payload: JSON.stringify(payload),
                 actor: JSON.stringify({ kind: ctx.actor?.kind, id: ctx.actor?.id, userId: ctx.userId, onBehalfOf: ctx.onBehalfOf ?? null }),
                 trace: JSON.stringify(carrier),
@@ -347,6 +396,10 @@ export class Kernel {
         return out;
     }
     // ---------------- 审计 ----------------
+    /**
+     * 只负责持久化审计，不吞异常。传事务时与业务共同提交；可靠读审计失败应阻止交付明文。
+     * 拒绝审计等尽力路径由上层自行 catch，不能在此统一忽略错误而破坏成功写入的审计保证。
+     */
     async writeAudit(db, e) {
         await db
             .insertInto('sys.audit_log')
@@ -396,9 +449,11 @@ export class Kernel {
     }
     // ---------------- 上下文 ----------------
     catalogCache;
+    /** 当前实例注册表固定，故可缓存能力名称；角色实际授权仍需按用户从数据库读取。 */
     catalogCaps() {
         return (this.catalogCache ??= this.registry.capabilityCatalog().map((c) => c.capability));
     }
+    /** 实时加载真人能力供额度约束使用；用户不存在或禁用时返回空集合。 */
     async capabilitiesOf(userId, tenantId) {
         const g = await loadUserGrants(this.app, userId, tenantId);
         return g && g.active ? g.capabilities : new Map();
@@ -413,36 +468,11 @@ export class Kernel {
         return systemCtx({ kind: 'process', name: opts.process, tenantId: opts.tenantId, capabilities: opts.capabilities, onBehalfOf: opts.onBehalfOf, requestId: opts.requestId });
     }
 }
+/** 构造注册表、连接句柄及读/传输服务；不会自动迁移、初始化组织或启动 worker。 */
 export function createKernel(opts) {
     return new Kernel(opts);
 }
-function splitRaw(raw) {
-    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
-        return { rest: raw ?? {} };
-    const { expectedVersion, ...rest } = raw;
-    if (expectedVersion === undefined || expectedVersion === null)
-        return { rest };
-    const v = Number(expectedVersion);
-    if (!Number.isInteger(v))
-        throw cageError('INVALID_INPUT', [{ path: 'expectedVersion', message: '版本号必须是整数' }]);
-    return { expectedVersion: v, rest };
-}
-/** 第 3 关之一：流程专用命令只接受流程身份；用户命令可以被声明过它的系统身份调用 */
-function assertInvoker(cmd, ctx, capability) {
-    const kind = ctx.actor.kind;
-    if (kind === 'system')
-        return;
-    if (kind === 'user' || kind === 'anonymous') {
-        if (!cmd.invokedBy.includes('user')) {
-            throw cageError('FORBIDDEN', { capability, message: `该命令只接受 ${cmd.invokedBy.join('/')} 调用` });
-        }
-        return;
-    }
-    const as = kind === 'reaction' ? 'process' : kind;
-    if (!cmd.invokedBy.includes('user') && !cmd.invokedBy.includes(as)) {
-        throw cageError('FORBIDDEN', { capability, message: `${kind} 身份不能调用该命令` });
-    }
-}
+/** 事件持久化不继承操作者明文权限：按事件字段声明掩码/删除，避免异步消费者获得多余秘密。 */
 function maskEventPayload(ev, payload) {
     const out = { ...payload };
     for (const [k, f] of Object.entries(ev.fields)) {