@yss123/cage-kernel 0.1.0 → 0.3.0

package/dist/types.d.ts

@@ -1,6 +1,14 @@
+/**
+ * 定义内核授权上下文、调用主体、来源和数据范围的公共类型。
+ * 认证、审批、任务与反应在服务端组装这些值，写流水线、安全读和审计共同消费；业务输入不能自行指定可信身份，类型描述也不等于已经验证或授予权限。
+ */
 /** 主体种类。系统身份（process/job/external/reaction）只能调用声明了对应 invokedBy 的命令，或自己声明过的命令。 */
 export type ActorKind = 'user' | 'process' | 'job' | 'external' | 'reaction' | 'system' | 'anonymous';
+/** 审计主体；id 的解释依赖 kind，系统主体名称不能当作真人用户 ID 使用。 */
 export interface Actor {
+    /**
+     * 真实调用身份类型，决定调用入口边界；真人委托信息放在 Ctx.onBehalfOf，不伪装为 user。
+     */
     kind: ActorKind;
     /** 用户 id，或系统身份名，例如 job:expireStaleOrders */
     id: string;
@@ -9,11 +17,18 @@ export interface Actor {
 export type Source = 'api' | 'process' | 'job' | 'import' | 'external' | 'reaction' | 'system';
 /** 范围组合子：封闭集合，每个都同时有内存语义和 SQL 语义 */
 export type Combinator = 'all' | 'self' | 'dept' | 'deptSubtree' | 'deptSet';
+/**
+ * 内核支持的数据范围组合子白名单，供配置校验与目录发现使用。
+ * 具体数据判定由 scope 的 SQL 和内存实现承担，数组顺序不等于范围授权的包含关系。
+ */
 export declare const COMBINATORS: readonly Combinator[];
 /** 组合子由窄到宽的顺序，用于「不能授出比自己更宽的范围」 */
 export declare const COMBINATOR_WIDTH: Record<Combinator, number>;
 /** 角色在某个聚合上的数据范围授权 */
 export interface ScopeGrant {
+    /**
+     * 此条授权采用的范围规则，多条授权按 OR 合并；all 仍受租户边界限制。
+     */
     combinator: Combinator;
     /** deptSet 用：角色配置的部门集合 */
     deptIds?: string[];
@@ -21,32 +36,53 @@ export interface ScopeGrant {
 /** 能力点参数，例如 { ceiling: 50000 } */
 export type CapabilityParams = Record<string, unknown>;
 /** 当前主体的上下文。HTTP 认证、审批桥接、调度器、反应各自构造它，交给内核。 */
+/**
+ * ctx 是可信服务端组装的授权快照，不是客户端可直接提交的请求体。
+ * capabilities 决定能做什么，scopes 决定可操作哪些记录，invokedBy 另由命令声明检查；
+ * 三者不可互相替代。异步处理派生上下文时要保留租户、真人委托和追踪信息。
+ */
 export interface Ctx {
+    /**
+     * 可信服务端主体；null 表示尚无身份，匿名公共调用也需显式 anonymous 主体。
+     */
     actor: Actor | null;
     /** 当前真人用户；系统身份时为 null（真人在 onBehalfOf） */
     userId: string | null;
     /** 系统身份代表的真人，用于职责分离和审计 */
     onBehalfOf?: string | null;
+    /** 所有数据库读写和异步事件的租户边界，不允许通过业务输入覆盖。 */
     tenantId: string;
+    /**
+     * 当前主体关联部门 ID；无部门时为 null，不能据空值自动扩展到全租户。
+     */
     deptId: string | null;
     /** 当前部门的祖先路径（含自己），例如 /root/purchase/ */
     deptPath: string | null;
     /** 能力集合及参数；多角色取并集，额度取最大值 */
     capabilities: Map<string, CapabilityParams>;
-    /** 各聚合上的范围授权，多角色取并集（OR）；未配置的聚合按「仅本人」 */
+    /** 各聚合上的范围授权，多角色取并集（OR）；具体聚合缺省时可使用 * 通配授权，仍未配置则按仅本人处理。 */
     scopes: Record<string, ScopeGrant[]>;
     /** 可以看明文的「聚合.种类」，例如 PurchaseOrder.phone */
     unmask: string[];
+    /**
+     * 本次业务入口来源，写入审计和异步关联，不独立授予对应调用身份或能力。
+     */
     source: Source;
+    /** 跨 HTTP、命令审计和 outbox 关联同一次请求；不承担业务去重。 */
     requestId?: string;
+    /** 同一次逻辑提交重试时复用；未提供时不会自动合并两次独立业务操作。 */
     idempotencyKey?: string;
     /** 二次认证时间（毫秒时间戳） */
     stepUpAt?: number | null;
+    /**
+     * 可选客户端来源信息，包含 IP 和 User-Agent，仅作审计上下文，不作为业务授权依据。
+     */
     client?: {
-        ip?: string;
+        ip?: string; /** 可选浏览器/客户端标识，属于不可信展示文本，不参与能力判断。 */
         userAgent?: string;
     };
     /** onBehalfOf 那个人的能力（额度类约束按他判断）；内核会按需加载 */
     onBehalfOfCapabilities?: Map<string, CapabilityParams>;
 }
+/** 声明回调既可同步计算，也可等待框架允许的读依赖；调用侧始终可以 await。 */
 export type MaybePromise<T> = T | Promise<T>;

package/dist/types.js

@@ -1,4 +1,12 @@
+/**
+ * 定义内核授权上下文、调用主体、来源和数据范围的公共类型。
+ * 认证、审批、任务与反应在服务端组装这些值，写流水线、安全读和审计共同消费；业务输入不能自行指定可信身份，类型描述也不等于已经验证或授予权限。
+ */
 // 内核公共类型：上下文 ctx、主体、范围授权。
+/**
+ * 内核支持的数据范围组合子白名单，供配置校验与目录发现使用。
+ * 具体数据判定由 scope 的 SQL 和内存实现承担，数组顺序不等于范围授权的包含关系。
+ */
 export const COMBINATORS = ['all', 'self', 'dept', 'deptSubtree', 'deptSet'];
 /** 组合子由窄到宽的顺序，用于「不能授出比自己更宽的范围」 */
 export const COMBINATOR_WIDTH = { self: 0, dept: 1, deptSet: 2, deptSubtree: 2, all: 3 };

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,0BAA0B;AAgB1B,MAAM,CAAC,MAAM,WAAW,GAA0B,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,CAAC,CAAC;AACpG,kCAAkC;AAClC,MAAM,CAAC,MAAM,gBAAgB,GAA+B,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,0BAA0B;AAoB1B;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAA0B,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,CAAC,CAAC;AACpG,kCAAkC;AAClC,MAAM,CAAC,MAAM,gBAAgB,GAA+B,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC"}

package/dist/util/names.d.ts

@@ -1,9 +1,15 @@
+/** 兼顾连续大写缩写和普通驼峰边界；输出用作数据库名字，调用前由声明层约束合法标识。 */
 export declare function snake(s: string): string;
+/** 与表名转换共享分词规则，使自动 HTTP 路径和领域命名保持可推导关系。 */
 export declare function kebab(s: string): string;
+/** 将数据库下划线列名转换为业务字段名；不改变已经是驼峰的字段。 */
 export declare function camel(s: string): string;
+/** 只改变首字符，供生成器保留后续缩写/驼峰；空字符串仍返回空字符串。 */
 export declare function lowerFirst(s: string): string;
+/** 只改变首字符，适合从字段名构造公开类型名，不承担标识符合法性检查。 */
 export declare function upperFirst(s: string): string;
 /** 32 位哈希（FNV-1a），用于咨询锁编号 */
 export declare function hash32(s: string): number;
 /** 稳定的 JSON 序列化（键排序），用于本体图比较 */
+/** 对对象键排序但保持数组顺序；仅用于可 JSON 化的声明资料，不作为密码学签名规范。 */
 export declare function stableStringify(v: unknown): string;

package/dist/util/names.js

@@ -1,19 +1,24 @@
 // 命名转换：聚合名大驼峰 → 表名 snake_case、路由 kebab-case；字段名 camelCase ↔ 列名 snake_case。
+/** 兼顾连续大写缩写和普通驼峰边界；输出用作数据库名字，调用前由声明层约束合法标识。 */
 export function snake(s) {
     return s
         .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
         .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
         .toLowerCase();
 }
+/** 与表名转换共享分词规则，使自动 HTTP 路径和领域命名保持可推导关系。 */
 export function kebab(s) {
     return snake(s).replace(/_/g, '-');
 }
+/** 将数据库下划线列名转换为业务字段名；不改变已经是驼峰的字段。 */
 export function camel(s) {
     return s.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
 }
+/** 只改变首字符，供生成器保留后续缩写/驼峰；空字符串仍返回空字符串。 */
 export function lowerFirst(s) {
     return s.charAt(0).toLowerCase() + s.slice(1);
 }
+/** 只改变首字符，适合从字段名构造公开类型名，不承担标识符合法性检查。 */
 export function upperFirst(s) {
     return s.charAt(0).toUpperCase() + s.slice(1);
 }
@@ -27,6 +32,7 @@ export function hash32(s) {
     return h | 0;
 }
 /** 稳定的 JSON 序列化（键排序），用于本体图比较 */
+/** 对对象键排序但保持数组顺序；仅用于可 JSON 化的声明资料，不作为密码学签名规范。 */
 export function stableStringify(v) {
     if (v === null || typeof v !== 'object')
         return JSON.stringify(v);

package/dist/util/names.js.map

@@ -1 +1 @@
-{"version":3,"file":"names.js","sourceRoot":"","sources":["../../src/util/names.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAE3E,MAAM,UAAU,KAAK,CAAC,CAAS;IAC7B,OAAO,CAAC;SACL,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC;SACtC,OAAO,CAAC,uBAAuB,EAAE,OAAO,CAAC;SACzC,WAAW,EAAE,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,CAAS;IAC7B,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,CAAS;IAC7B,OAAO,CAAC,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,EAAE,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;AACtE,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,CAAS;IAClC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,CAAS;IAClC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAChD,CAAC;AAED,6BAA6B;AAC7B,MAAM,UAAU,MAAM,CAAC,CAAS;IAC9B,IAAI,CAAC,GAAG,UAAU,CAAC;IACnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QACrB,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,CAAC;AACf,CAAC;AAED,gCAAgC;AAChC,MAAM,UAAU,eAAe,CAAC,CAAU;IACxC,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAClE,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IACrE,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAW,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAE,CAAS,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC;IACxF,OAAO,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,eAAe,CAAE,CAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AACpG,CAAC"}
+{"version":3,"file":"names.js","sourceRoot":"","sources":["../../src/util/names.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAE3E,+CAA+C;AAC/C,MAAM,UAAU,KAAK,CAAC,CAAS;IAC7B,OAAO,CAAC;SACL,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC;SACtC,OAAO,CAAC,uBAAuB,EAAE,OAAO,CAAC;SACzC,WAAW,EAAE,CAAC;AACnB,CAAC;AAED,2CAA2C;AAC3C,MAAM,UAAU,KAAK,CAAC,CAAS;IAC7B,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AACrC,CAAC;AAED,qCAAqC;AACrC,MAAM,UAAU,KAAK,CAAC,CAAS;IAC7B,OAAO,CAAC,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,EAAE,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;AACtE,CAAC;AAED,wCAAwC;AACxC,MAAM,UAAU,UAAU,CAAC,CAAS;IAClC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAChD,CAAC;AAED,wCAAwC;AACxC,MAAM,UAAU,UAAU,CAAC,CAAS;IAClC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAChD,CAAC;AAED,6BAA6B;AAC7B,MAAM,UAAU,MAAM,CAAC,CAAS;IAC9B,IAAI,CAAC,GAAG,UAAU,CAAC;IACnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QACrB,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,CAAC;AACf,CAAC;AAED,gCAAgC;AAChC,iDAAiD;AACjD,MAAM,UAAU,eAAe,CAAC,CAAU;IACxC,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAClE,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IACrE,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAW,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAE,CAAS,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC;IACxF,OAAO,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,eAAe,CAAE,CAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AACpG,CAAC"}

package/dist/worker/consumers.d.ts

@@ -9,6 +9,8 @@ export interface ApprovalEngine {
         tenantId: string;
         /** 只包含声明过的 routable 字段 */
         vars: Record<string, unknown>;
+        subjectVersion?: number;
+        eventId?: number;
         tx: Transaction<any>;
     }): Promise<{
         instanceId: string;
@@ -20,8 +22,13 @@ export interface ApprovalEngine {
         tx: Transaction<any>;
     }): Promise<void>;
 }
+/**
+ * 只装配 tx:outbox 的反应，same 反应已由主命令事务执行。消费名称稳定，供持久去重使用。
+ * 每个反应只获得目标命令能力；集合按声明顺序串行执行，失败带原始条目坐标并回滚消费事务。
+ */
 export declare function reactionConsumers(k: Kernel): EventConsumer[];
 /** 审批启动：只把 routable 字段作为流程变量传给引擎 */
+/** 启动时要求每个流程存在引擎，避免事件已标 done 却没有产生待办；启动/取消随消费事务提交。 */
 export declare function approvalConsumers(k: Kernel, engines: Record<string, ApprovalEngine>): EventConsumer[];
 /** 声明对象通过 CONSUMERS 扩展点提供的消费者（例如 @yss123/cage-connectors 的出站映射） */
 export declare function extensionConsumers(k: Kernel): EventConsumer[];

package/dist/worker/consumers.js

@@ -1,19 +1,22 @@
 import { CONSUMERS } from '../brands.js';
 import { systemCtx } from '../org.js';
 import { loadScoped } from '../pipeline/load.js';
+import { reactionEntries, reactionEntryError } from '../primitives/collection.js';
+/** 事件可来自真人或代表真人的系统身份，后续反应继续携带同一委托用于审计和职责分离。 */
 function actorUser(row) {
     return row.actor?.userId ?? row.actor?.onBehalfOf ?? null;
 }
+/**
+ * 只装配 tx:outbox 的反应，same 反应已由主命令事务执行。消费名称稳定，供持久去重使用。
+ * 每个反应只获得目标命令能力；集合按声明顺序串行执行，失败带原始条目坐标并回滚消费事务。
+ */
 export function reactionConsumers(k) {
-    return k.registry.reactions
-        .filter(({ r }) => r.tx === 'outbox')
+    const events = new Set(k.registry.reactions.map(({ r }) => r.event.name));
+    return [...events].flatMap((event) => k.registry.reactionsFor(event).filter(({ r }) => r.tx === 'outbox'))
         .map(({ r, name }) => ({
         name: `reaction:${name}`,
         event: r.event.name,
         async handle(row, tx) {
-            const input = r.map(row.payload);
-            if (input === null || input === undefined)
-                return;
             const ctx = systemCtx({
                 kind: 'reaction',
                 name,
@@ -22,25 +25,33 @@ export function reactionConsumers(k) {
                 onBehalfOf: actorUser(row),
                 requestId: row.request_id ?? undefined,
             });
-            await k.executeIn(tx, r.command, input, ctx, 0);
+            // 集合调用和去重登记共享同一事务；串行执行保留声明的锁顺序。
+            for (const entry of reactionEntries(r, row.payload)) {
+                try {
+                    await k.executeIn(tx, r.command, entry.input, ctx, 0);
+                }
+                catch (error) {
+                    throw reactionEntryError(error, r, name, entry);
+                }
+            }
         },
     }));
 }
 /** 审批启动：只把 routable 字段作为流程变量传给引擎 */
+/** 启动时要求每个流程存在引擎，避免事件已标 done 却没有产生待办；启动/取消随消费事务提交。 */
 export function approvalConsumers(k, engines) {
     const out = [];
     for (const { a, name } of k.registry.approvals) {
         const engine = engines[a.process];
         if (!engine) {
-            k.log.warn({ process: a.process }, `审批绑定 ${name} 没有可用的审批引擎，流程不会启动`);
-            continue;
+            throw new Error(`[CAGE-WORKER-001] 审批绑定 ${name} 缺少流程 ${a.process} 的审批引擎；补齐路由或装配引擎后再启动 worker`);
         }
         out.push({
             name: `approval:${name}:start`,
             event: a.start.name,
             async handle(row, tx) {
                 const vars = await routableVars(k, a, row, tx);
-                await engine.start({ process: a.process, businessKey: row.aggregate_id, tenantId: row.tenant_id, vars, tx });
+                await engine.start({ process: a.process, businessKey: row.aggregate_id, tenantId: row.tenant_id, vars, tx, subjectVersion: row.aggregate_version ?? undefined, eventId: row.id });
             },
         });
         for (const ev of a.cancelOn) {
@@ -55,6 +66,7 @@ export function approvalConsumers(k, engines) {
     }
     return out;
 }
+/** 只提取 routable 白名单，优先当前对象快照、再事件载荷；不把整个聚合或任意输入传给流程。 */
 async function routableVars(k, a, row, tx) {
     const ctx = systemCtx({ kind: 'process', name: a.process, tenantId: row.tenant_id, capabilities: [] });
     const snap = await loadScoped(tx, a.agg, row.aggregate_id, ctx, false);

package/dist/worker/consumers.js.map

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

package/dist/worker/health.d.ts

@@ -0,0 +1,38 @@
+import type { Kernel } from '../kernel.js';
+import type { EventConsumer } from './outbox.js';
+/** 进程实际装载的版本/协议/注册指纹及消费者清单，不能用磁盘源码代替这份运行证据。 */
+export interface WorkerManifest {
+    version: string;
+    protocolVersion: number;
+    registryFingerprint: string;
+    loadedAt: string;
+    consumers: {
+        name: string;
+        event: string;
+        ready: boolean;
+    }[];
+    events: {
+        name: string;
+        consumers: string[];
+        recordOnly: boolean;
+    }[];
+    jobs: string[];
+}
+/** 可观测运行状态；heartbeatAt 为 ISO 时间，null 表示尚无成功心跳，inFlight 是正在执行的任务标识。 */
+export interface WorkerSnapshot {
+    id: string;
+    pid: number;
+    status: 'starting' | 'running' | 'stopping' | 'stopped' | 'error';
+    listenerHealthy: boolean;
+    schedulerHealthy: boolean;
+    heartbeatAt: string | null;
+    inFlight: string[];
+    lastError: string | null;
+    manifest: WorkerManifest;
+}
+/** 清单按名称稳定排序；recordOnly 事件允许没有消费者，未知事件则由投递校验拒绝静默完成。 */
+export declare function describeConsumers(k: Kernel, consumers: EventConsumer[]): WorkerManifest;
+/** 保存实时快照提供器而非冻结结果，HTTP 同进程诊断可观察到最新状态；WeakMap 不延长 kernel 生命周期。 */
+export declare function registerWorkerSnapshot(k: Kernel, snapshot: () => WorkerSnapshot): void;
+/** 未在此进程装配 worker 时返回 null；跨进程状态应查询数据库心跳记录。 */
+export declare function workerSnapshot(k: Kernel): WorkerSnapshot | null;

package/dist/worker/health.js

@@ -0,0 +1,20 @@
+import { readFileSync } from 'node:fs';
+import { registryFingerprint } from '../registry.js';
+const { version } = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+/** 清单按名称稳定排序；recordOnly 事件允许没有消费者，未知事件则由投递校验拒绝静默完成。 */
+export function describeConsumers(k, consumers) {
+    const entries = consumers.map((c) => ({ name: c.name, event: c.event, ready: true })).sort((a, b) => a.name.localeCompare(b.name));
+    const events = [...new Set([...k.registry.events.map((event) => event.name), ...entries.map((c) => c.event)])].sort();
+    return {
+        version, protocolVersion: 2, registryFingerprint: registryFingerprint(k.registry), loadedAt: new Date().toISOString(),
+        consumers: entries,
+        events: events.map((name) => { const names = entries.filter((c) => c.event === name).map((c) => c.name); return { name, consumers: names, recordOnly: names.length === 0 }; }),
+        jobs: k.registry.jobs.map((j) => j.name).sort(),
+    };
+}
+const snapshots = new WeakMap();
+/** 保存实时快照提供器而非冻结结果，HTTP 同进程诊断可观察到最新状态；WeakMap 不延长 kernel 生命周期。 */
+export function registerWorkerSnapshot(k, snapshot) { snapshots.set(k, snapshot); }
+/** 未在此进程装配 worker 时返回 null；跨进程状态应查询数据库心跳记录。 */
+export function workerSnapshot(k) { return snapshots.get(k)?.() ?? null; }
+//# sourceMappingURL=health.js.map

package/dist/worker/health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.js","sourceRoot":"","sources":["../../src/worker/health.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAGrD,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,oBAAoB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAwB,CAAC;AA0B5H,uDAAuD;AACvD,MAAM,UAAU,iBAAiB,CAAC,CAAS,EAAE,SAA0B;IACrE,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACnI,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACtH,OAAO;QACL,OAAO,EAAE,eAAe,EAAE,CAAC,EAAE,mBAAmB,EAAE,mBAAmB,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,QAAQ,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACrH,SAAS,EAAE,OAAO;QAClB,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,GAAG,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAC9K,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE;KAChD,CAAC;AACJ,CAAC;AAED,MAAM,SAAS,GAAG,IAAI,OAAO,EAAgC,CAAC;AAC9D,kEAAkE;AAClE,MAAM,UAAU,sBAAsB,CAAC,CAAS,EAAE,QAA8B,IAAU,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;AACvH,+CAA+C;AAC/C,MAAM,UAAU,cAAc,CAAC,CAAS,IAA2B,OAAO,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC"}

package/dist/worker/index.d.ts

@@ -3,17 +3,24 @@ import { type Kernel } from '../kernel.js';
 import { type Logger } from '../telemetry.js';
 import { type ApprovalEngine } from './consumers.js';
 import { type EventConsumer } from './outbox.js';
+import { type WorkerManifest, type WorkerSnapshot } from './health.js';
 export * from './outbox.js';
 export * from './consumers.js';
 export * from './scheduler.js';
+export * from './health.js';
+/** 生命周期装配选项；注入 kernel 时 worker 不拥有其关闭权，所有带 Ms 后缀的时限均为毫秒。 */
 export interface WorkerOptions {
+    /** 未注入 kernel 时用于创建内核的领域导出；必须与 API 使用同一业务版本。 */
     domain?: object | object[];
+    /** 可选现有内核，提供时由宿主负责关闭；worker 仍拥有自己创建的监听及锁连接。 */
     kernel?: Kernel;
+    /** 数据库账号连接；未注入内核时缺省从环境读取，专用监听连接也需要 app URL。 */
     urls?: DatabaseUrls;
     /** 同时处理的事件数 */
     concurrency?: number;
     /** 没收到 NOTIFY 时的轮询间隔 */
     pollIntervalMs?: number;
+    /** 单个 outbox 事件的最大投递尝试次数，缺省使用 MAX_ATTEMPTS；失败终结后需人工诊断。 */
     maxAttempts?: number;
     /** 外部审批引擎（按流程名）；不传时使用代码内封闭路由 */
     approvalEngines?: Record<string, ApprovalEngine>;
@@ -21,16 +28,42 @@ export interface WorkerOptions {
     consumers?: EventConsumer[];
     /** 是否运行定时任务，默认 true */
     jobs?: boolean;
+    /** 停止后等待所有在途任务的时限；超时不会提前释放仍在执行的任务锁。 */
+    shutdownTimeoutMs?: number;
+    /** 调度扫描间隔，默认 5 秒；错过周期跳过，不积压补跑。 */
+    schedulerIntervalMs?: number;
+    /** 后台循环日志出口；省略使用默认日志器，不应在日志中输出完整连接、载荷或凭据。 */
     logger?: Logger;
 }
+/** stop 可重复调用并复用同一停机 Promise；snapshot 是观测证据，不可用于绕过数据库互斥。 */
 export interface WorkerHandle {
+    /** 供消费者复用的执行内核；是否由 stop 关闭取决于是否由 worker 创建。 */
     kernel: Kernel;
+    /** 当前装配的全部消费者，包含框架、扩展及宿主补充项。 */
     consumers: EventConsumer[];
-    /** 处理到 outbox 为空为止（测试和 cage dev 用） */
+    /** 注册指纹与消费者清单，用于判断实际装载版本；不证明某事件已经消费成功。 */
+    manifest: WorkerManifest;
+    /** 读取此进程最新内存状态、在途任务及心跳证据；人工驱动实例返回 manual/stopped 摘要。 */
+    snapshot(): WorkerSnapshot;
+    /** 手动处理当前可领取事件及扩展工作，默认最多 50 轮；返回处理数量，不代表未来重试或死信已清空。 */
     drain(maxRounds?: number): Promise<number>;
+    /** 停止新工作并等待在途任务；超时会拒绝等待，但不会提前释放仍执行中的任务锁。 */
     stop(): Promise<void>;
 }
+/** 合并内置、扩展和额外消费者，显式审批引擎覆盖同名代码路由；缺失引擎或名称冲突在启动前失败。 */
 export declare function buildConsumers(k: Kernel, opts?: Pick<WorkerOptions, 'approvalEngines' | 'consumers'>): EventConsumer[];
+/** 构建并验证消费者后描述装载清单；这不启动轮询、建立心跳或证明 worker 正在运行。 */
+export declare function workerManifest(k: Kernel, opts?: Pick<WorkerOptions, 'approvalEngines' | 'consumers'>): WorkerManifest;
 /** 不启动循环，只创建可手动驱动的 worker（测试用） */
+/**
+ * 手动驱动当前可领取任务，drain 默认最多 50 轮；无到期事件且扩展无进展即返回处理数量。
+ * 未来重试、死信及被前序阻塞的事件仍可能存在，因此 drain 返回并不证明完整业务链已经成功。
+ */
 export declare function createWorker(k: Kernel, opts?: WorkerOptions): Omit<WorkerHandle, 'stop'>;
+/**
+ * 装配服务和消费者后，建立独立 LISTEN/调度锁连接，写首个心跳，再启动投递、定时任务和维护循环。
+ * 所有后台 Promise 统一登记，停机先停止新工作、取消可取消 IO，再等待在途工作后释放连接与锁。
+ * 停机超时只向调用方报错，不提前关闭仍持有任务锁的连接；后台清理继续等待真实任务结束。
+ * LISTEN 失效可由轮询继续发现 outbox；调度连接异常会停止新调度，健康状态如实反映该区别。
+ */
 export declare function startWorker(opts?: WorkerOptions): Promise<WorkerHandle>;