@yss123/cage-kernel 0.0.0-stage → 0.1.0

package/dist/telemetry.js

@@ -0,0 +1,35 @@
+// 链路追踪：流水线每一关一个 span；写 outbox 时把链路上下文带上，worker 处理时接上。
+import { context, propagation, trace } from '@opentelemetry/api';
+const tracer = trace.getTracer('cage');
+export async function step(name, fn) {
+    return tracer.startActiveSpan(`cage.${name}`, async (span) => {
+        try {
+            return await fn();
+        }
+        catch (e) {
+            span.recordException(e);
+            throw e;
+        }
+        finally {
+            span.end();
+        }
+    });
+}
+export function traceCarrier() {
+    const carrier = {};
+    propagation.inject(context.active(), carrier);
+    return carrier;
+}
+export function withCarrier(carrier, fn) {
+    if (!carrier)
+        return fn();
+    const ctx = propagation.extract(context.active(), carrier);
+    return context.with(ctx, fn);
+}
+export const consoleLogger = {
+    info: (o, m) => console.log(m ?? '', typeof o === 'string' ? o : JSON.stringify(o)),
+    warn: (o, m) => console.warn(m ?? '', typeof o === 'string' ? o : JSON.stringify(o)),
+    error: (o, m) => console.error(m ?? '', typeof o === 'string' ? o : JSON.stringify(o)),
+};
+export const silentLogger = { info() { }, warn() { }, error() { } };
+//# sourceMappingURL=telemetry.js.map

package/dist/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEjE,MAAM,MAAM,GAAG,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AAEvC,MAAM,CAAC,KAAK,UAAU,IAAI,CAAI,IAAY,EAAE,EAAoB;IAC9D,OAAO,MAAM,CAAC,eAAe,CAAC,QAAQ,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QAC3D,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,eAAe,CAAC,CAAU,CAAC,CAAC;YACjC,MAAM,CAAC,CAAC;QACV,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,GAAG,EAAE,CAAC;QACb,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,MAAM,OAAO,GAA2B,EAAE,CAAC;IAC3C,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,OAAO,CAAC,CAAC;IAC9C,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,WAAW,CAAI,OAAkD,EAAE,EAAoB;IACrG,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,EAAE,CAAC;IAC1B,MAAM,GAAG,GAAG,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,OAAO,CAAC,CAAC;IAC3D,OAAO,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AAC/B,CAAC;AASD,MAAM,CAAC,MAAM,aAAa,GAAW;IACnC,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IACnF,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IACpF,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;CACvF,CAAC;AAEF,MAAM,CAAC,MAAM,YAAY,GAAW,EAAE,IAAI,KAAI,CAAC,EAAE,IAAI,KAAI,CAAC,EAAE,KAAK,KAAI,CAAC,EAAE,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,52 @@
+/** 主体种类。系统身份（process/job/external/reaction）只能调用声明了对应 invokedBy 的命令，或自己声明过的命令。 */
+export type ActorKind = 'user' | 'process' | 'job' | 'external' | 'reaction' | 'system' | 'anonymous';
+export interface Actor {
+    kind: ActorKind;
+    /** 用户 id，或系统身份名，例如 job:expireStaleOrders */
+    id: string;
+}
+/** 写入来源，记入审计 */
+export type Source = 'api' | 'process' | 'job' | 'import' | 'external' | 'reaction' | 'system';
+/** 范围组合子：封闭集合，每个都同时有内存语义和 SQL 语义 */
+export type Combinator = 'all' | 'self' | 'dept' | 'deptSubtree' | 'deptSet';
+export declare const COMBINATORS: readonly Combinator[];
+/** 组合子由窄到宽的顺序，用于「不能授出比自己更宽的范围」 */
+export declare const COMBINATOR_WIDTH: Record<Combinator, number>;
+/** 角色在某个聚合上的数据范围授权 */
+export interface ScopeGrant {
+    combinator: Combinator;
+    /** deptSet 用：角色配置的部门集合 */
+    deptIds?: string[];
+}
+/** 能力点参数，例如 { ceiling: 50000 } */
+export type CapabilityParams = Record<string, unknown>;
+/** 当前主体的上下文。HTTP 认证、审批桥接、调度器、反应各自构造它，交给内核。 */
+export interface Ctx {
+    actor: Actor | null;
+    /** 当前真人用户；系统身份时为 null（真人在 onBehalfOf） */
+    userId: string | null;
+    /** 系统身份代表的真人，用于职责分离和审计 */
+    onBehalfOf?: string | null;
+    tenantId: string;
+    deptId: string | null;
+    /** 当前部门的祖先路径（含自己），例如 /root/purchase/ */
+    deptPath: string | null;
+    /** 能力集合及参数；多角色取并集，额度取最大值 */
+    capabilities: Map<string, CapabilityParams>;
+    /** 各聚合上的范围授权，多角色取并集（OR）；未配置的聚合按「仅本人」 */
+    scopes: Record<string, ScopeGrant[]>;
+    /** 可以看明文的「聚合.种类」，例如 PurchaseOrder.phone */
+    unmask: string[];
+    source: Source;
+    requestId?: string;
+    idempotencyKey?: string;
+    /** 二次认证时间（毫秒时间戳） */
+    stepUpAt?: number | null;
+    client?: {
+        ip?: string;
+        userAgent?: string;
+    };
+    /** onBehalfOf 那个人的能力（额度类约束按他判断）；内核会按需加载 */
+    onBehalfOfCapabilities?: Map<string, CapabilityParams>;
+}
+export type MaybePromise<T> = T | Promise<T>;

package/dist/types.js

@@ -0,0 +1,5 @@
+// 内核公共类型：上下文 ctx、主体、范围授权。
+export const COMBINATORS = ['all', 'self', 'dept', 'deptSubtree', 'deptSet'];
+/** 组合子由窄到宽的顺序，用于「不能授出比自己更宽的范围」 */
+export const COMBINATOR_WIDTH = { self: 0, dept: 1, deptSet: 2, deptSubtree: 2, all: 3 };
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +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"}

package/dist/util/names.d.ts

@@ -0,0 +1,9 @@
+export declare function snake(s: string): string;
+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 序列化（键排序），用于本体图比较 */
+export declare function stableStringify(v: unknown): string;

package/dist/util/names.js

@@ -0,0 +1,38 @@
+// 命名转换：聚合名大驼峰 → 表名 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();
+}
+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);
+}
+/** 32 位哈希（FNV-1a），用于咨询锁编号 */
+export function hash32(s) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return h | 0;
+}
+/** 稳定的 JSON 序列化（键排序），用于本体图比较 */
+export function stableStringify(v) {
+    if (v === null || typeof v !== 'object')
+        return JSON.stringify(v);
+    if (Array.isArray(v))
+        return `[${v.map(stableStringify).join(',')}]`;
+    const keys = Object.keys(v).filter((k) => v[k] !== undefined).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(v[k])}`).join(',')}}`;
+}
+//# sourceMappingURL=names.js.map

package/dist/util/names.js.map

@@ -0,0 +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"}

package/dist/worker/consumers.d.ts

@@ -0,0 +1,29 @@
+import type { Transaction } from 'kysely';
+import type { Kernel } from '../kernel.js';
+import type { EventConsumer } from './outbox.js';
+/** 审批引擎的最小接口（完整接口见 @yss123/cage-approval）。引擎只给结论，结论由桥接代码转成命令。 */
+export interface ApprovalEngine {
+    start(input: {
+        process: string;
+        businessKey: string;
+        tenantId: string;
+        /** 只包含声明过的 routable 字段 */
+        vars: Record<string, unknown>;
+        tx: Transaction<any>;
+    }): Promise<{
+        instanceId: string;
+    }>;
+    cancel(input: {
+        process: string;
+        businessKey: string;
+        tenantId: string;
+        tx: Transaction<any>;
+    }): Promise<void>;
+}
+export declare function reactionConsumers(k: Kernel): EventConsumer[];
+/** 审批启动：只把 routable 字段作为流程变量传给引擎 */
+export declare function approvalConsumers(k: Kernel, engines: Record<string, ApprovalEngine>): EventConsumer[];
+/** 声明对象通过 CONSUMERS 扩展点提供的消费者（例如 @yss123/cage-connectors 的出站映射） */
+export declare function extensionConsumers(k: Kernel): EventConsumer[];
+/** 从 ROUTE 扩展（代码内封闭路由）里找审批引擎 */
+export declare function routeEngines(k: Kernel): Record<string, ApprovalEngine>;

package/dist/worker/consumers.js

@@ -0,0 +1,79 @@
+import { CONSUMERS } from '../brands.js';
+import { systemCtx } from '../org.js';
+import { loadScoped } from '../pipeline/load.js';
+function actorUser(row) {
+    return row.actor?.userId ?? row.actor?.onBehalfOf ?? null;
+}
+export function reactionConsumers(k) {
+    return k.registry.reactions
+        .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,
+                tenantId: row.tenant_id,
+                capabilities: [k.registry.capabilityOf(r.command)],
+                onBehalfOf: actorUser(row),
+                requestId: row.request_id ?? undefined,
+            });
+            await k.executeIn(tx, r.command, input, ctx, 0);
+        },
+    }));
+}
+/** 审批启动：只把 routable 字段作为流程变量传给引擎 */
+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;
+        }
+        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 });
+            },
+        });
+        for (const ev of a.cancelOn) {
+            out.push({
+                name: `approval:${name}:cancel:${ev.name}`,
+                event: ev.name,
+                async handle(row, tx) {
+                    await engine.cancel({ process: a.process, businessKey: row.aggregate_id, tenantId: row.tenant_id, tx });
+                },
+            });
+        }
+    }
+    return out;
+}
+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);
+    const vars = {};
+    for (const f of a.routable)
+        vars[f] = snap?.[f] ?? row.payload?.[f] ?? null;
+    return vars;
+}
+/** 声明对象通过 CONSUMERS 扩展点提供的消费者（例如 @yss123/cage-connectors 的出站映射） */
+export function extensionConsumers(k) {
+    return k.registry.consumerProviders().flatMap((p) => p[CONSUMERS](k) ?? []);
+}
+/** 从 ROUTE 扩展（代码内封闭路由）里找审批引擎 */
+export function routeEngines(k) {
+    const out = {};
+    for (const e of k.registry.extensions) {
+        if (e.kind === 'ROUTE' && typeof e.value?.engine === 'function')
+            out[e.value.process] = e.value.engine(k);
+    }
+    return out;
+}
+//# sourceMappingURL=consumers.js.map

package/dist/worker/consumers.js.map

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

package/dist/worker/index.d.ts

@@ -0,0 +1,36 @@
+import { type DatabaseUrls } from '../db/connect.js';
+import { type Kernel } from '../kernel.js';
+import { type Logger } from '../telemetry.js';
+import { type ApprovalEngine } from './consumers.js';
+import { type EventConsumer } from './outbox.js';
+export * from './outbox.js';
+export * from './consumers.js';
+export * from './scheduler.js';
+export interface WorkerOptions {
+    domain?: object | object[];
+    kernel?: Kernel;
+    urls?: DatabaseUrls;
+    /** 同时处理的事件数 */
+    concurrency?: number;
+    /** 没收到 NOTIFY 时的轮询间隔 */
+    pollIntervalMs?: number;
+    maxAttempts?: number;
+    /** 外部审批引擎（按流程名）；不传时使用代码内封闭路由 */
+    approvalEngines?: Record<string, ApprovalEngine>;
+    /** 额外的事件消费者 */
+    consumers?: EventConsumer[];
+    /** 是否运行定时任务，默认 true */
+    jobs?: boolean;
+    logger?: Logger;
+}
+export interface WorkerHandle {
+    kernel: Kernel;
+    consumers: EventConsumer[];
+    /** 处理到 outbox 为空为止（测试和 cage dev 用） */
+    drain(maxRounds?: number): Promise<number>;
+    stop(): Promise<void>;
+}
+export declare function buildConsumers(k: Kernel, opts?: Pick<WorkerOptions, 'approvalEngines' | 'consumers'>): EventConsumer[];
+/** 不启动循环，只创建可手动驱动的 worker（测试用） */
+export declare function createWorker(k: Kernel, opts?: WorkerOptions): Omit<WorkerHandle, 'stop'>;
+export declare function startWorker(opts?: WorkerOptions): Promise<WorkerHandle>;

package/dist/worker/index.js

@@ -0,0 +1,120 @@
+// worker 进程：投递 outbox、执行反应、启动审批、跑定时任务、调用第三方。与 api 同一份代码和镜像，只是启动命令不同。
+import { sql } from 'kysely';
+import { dedicatedClient, urlsFromEnv } from '../db/connect.js';
+import { createKernel } from '../kernel.js';
+import { consoleLogger } from '../telemetry.js';
+import { approvalConsumers, extensionConsumers, reactionConsumers, routeEngines, } from './consumers.js';
+import { claimBatch, deliver, MAX_ATTEMPTS, sweepStale } from './outbox.js';
+import { nextRun, tick } from './scheduler.js';
+export * from './outbox.js';
+export * from './consumers.js';
+export * from './scheduler.js';
+export function buildConsumers(k, opts = {}) {
+    const engines = { ...routeEngines(k), ...(opts.approvalEngines ?? {}) };
+    return [...reactionConsumers(k), ...approvalConsumers(k, engines), ...extensionConsumers(k), ...(opts.consumers ?? [])];
+}
+/** 不启动循环，只创建可手动驱动的 worker（测试用） */
+export function createWorker(k, opts = {}) {
+    const consumers = buildConsumers(k, opts);
+    const max = opts.maxAttempts ?? MAX_ATTEMPTS;
+    return {
+        kernel: k,
+        consumers,
+        async drain(maxRounds = 50) {
+            let n = 0;
+            for (let i = 0; i < maxRounds; i++) {
+                const rows = await claimBatch(k, opts.concurrency ?? 8);
+                if (rows.length === 0)
+                    break;
+                await Promise.all(rows.map((r) => deliver(k, r, consumers, max)));
+                n += rows.length;
+            }
+            return n;
+        },
+    };
+}
+export async function startWorker(opts = {}) {
+    const log = opts.logger ?? consoleLogger;
+    const urls = opts.urls ?? (opts.kernel ? undefined : urlsFromEnv());
+    const k = opts.kernel ?? createKernel({ domain: opts.domain ?? {}, urls, logger: log });
+    const w = createWorker(k, opts);
+    const concurrency = opts.concurrency ?? 8;
+    const poll = opts.pollIntervalMs ?? 500;
+    let stopped = false;
+    let wake = null;
+    const timers = [];
+    // LISTEN：有新事件时立刻醒来，不用等轮询
+    const appUrl = urls?.app ?? urlsFromEnv().app;
+    const listener = await dedicatedClient(appUrl, 'cage-worker-listen');
+    await listener.query('LISTEN cage_outbox');
+    listener.on('notification', () => wake?.());
+    listener.on('error', (e) => log.error({ err: String(e) }, 'outbox 监听连接出错'));
+    const loop = (async () => {
+        while (!stopped) {
+            try {
+                const rows = await claimBatch(k, concurrency);
+                if (rows.length > 0) {
+                    await Promise.all(rows.map((r) => deliver(k, r, w.consumers, opts.maxAttempts ?? MAX_ATTEMPTS)));
+                    continue;
+                }
+            }
+            catch (e) {
+                log.error({ err: String(e) }, 'outbox 领取失败');
+            }
+            await new Promise((resolve) => {
+                const t = setTimeout(resolve, poll);
+                wake = () => {
+                    clearTimeout(t);
+                    resolve();
+                };
+            });
+            wake = null;
+        }
+    })();
+    // 清扫与日常维护
+    timers.push(setInterval(() => void sweepStale(k).catch(() => { }), 60_000));
+    const housekeeping = async () => {
+        try {
+            await sql `select sys.ensure_audit_partitions(3)`.execute(k.app);
+            await k.app.deleteFrom('sys.idempotency').where('expires_at', '<', new Date()).execute();
+            await k.app.deleteFrom('sys.session').where('expires_at', '<', new Date()).execute();
+        }
+        catch (e) {
+            log.warn({ err: String(e) }, '日常维护失败');
+        }
+    };
+    void housekeeping();
+    timers.push(setInterval(() => void housekeeping(), 3600_000));
+    // 定时任务
+    let lockConn = null;
+    if (opts.jobs !== false && k.registry.jobs.length > 0) {
+        lockConn = await dedicatedClient(appUrl, 'cage-scheduler');
+        const due = new Map(k.registry.jobs.map((j) => [j.name, nextRun(j.cron, new Date())]));
+        timers.push(setInterval(() => {
+            const now = new Date();
+            for (const j of k.registry.jobs) {
+                const at = due.get(j.name);
+                if (now < at)
+                    continue;
+                due.set(j.name, nextRun(j.cron, now));
+                void tick(k, j, lockConn, at).catch((e) => log.error({ job: j.name, err: String(e) }, '调度失败'));
+            }
+        }, 5_000));
+    }
+    log.info({ consumers: w.consumers.map((c) => c.name), jobs: k.registry.jobs.map((j) => j.name) }, 'worker 已启动');
+    return {
+        ...w,
+        async stop() {
+            stopped = true;
+            wake?.();
+            for (const t of timers)
+                clearInterval(t);
+            await loop;
+            await listener.end().catch(() => { });
+            await lockConn?.end().catch(() => { });
+            if (!opts.kernel)
+                await k.close();
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/worker/index.js.map

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

package/dist/worker/outbox.d.ts

@@ -0,0 +1,38 @@
+import { type Transaction } from 'kysely';
+import type { Kernel } from '../kernel.js';
+export interface OutboxRow {
+    id: number;
+    tenant_id: string;
+    event: string;
+    aggregate: string;
+    aggregate_id: string;
+    payload: Record<string, any>;
+    actor: {
+        kind?: string;
+        id?: string;
+        userId?: string | null;
+        onBehalfOf?: string | null;
+    } | null;
+    trace: Record<string, string> | null;
+    request_id: string | null;
+    status: string;
+    attempts: number;
+}
+/** 事件消费者：反应、出站映射、审批启动都实现这个接口。登记去重和业务写入在同一个事务里提交。 */
+export interface EventConsumer {
+    /** 唯一名，用于 (事件 id, 消费者) 去重 */
+    name: string;
+    event: string;
+    handle(row: OutboxRow, tx: Transaction<any>, kernel: Kernel): Promise<void>;
+}
+export declare const MAX_ATTEMPTS = 10;
+/** 指数退避：1 秒、2 秒、4 秒……最多 1 小时 */
+export declare function backoffMs(attempts: number): number;
+export declare function claimBatch(k: Kernel, limit: number): Promise<OutboxRow[]>;
+export declare function deliver(k: Kernel, row: OutboxRow, consumers: EventConsumer[], maxAttempts?: number): Promise<'done' | 'retry' | 'dead'>;
+/** 清扫：worker 崩溃后卡在「处理中」超过 5 分钟的事件重置为待投递 */
+export declare function sweepStale(k: Kernel, olderThanMs?: number): Promise<number>;
+/** 人工重放死信：仍然走内核流水线 */
+export declare function replayDeadLetter(k: Kernel, deadLetterId: number, handledBy: string): Promise<void>;
+/** 人工丢弃死信：标记完成，解除对同一聚合后续事件的阻塞 */
+export declare function discardDeadLetter(k: Kernel, deadLetterId: number, handledBy: string): Promise<void>;

package/dist/worker/outbox.js

@@ -0,0 +1,121 @@
+// outbox 投递器：多个 worker 实例同时领取，靠 FOR UPDATE SKIP LOCKED 避免重复领取；同一聚合的事件严格按顺序处理。
+import { sql } from 'kysely';
+import { isCageError } from '../errors.js';
+import { withCarrier } from '../telemetry.js';
+export const MAX_ATTEMPTS = 10;
+/** 指数退避：1 秒、2 秒、4 秒……最多 1 小时 */
+export function backoffMs(attempts) {
+    return Math.min(3600_000, 1000 * 2 ** Math.max(0, attempts - 1));
+}
+export async function claimBatch(k, limit) {
+    return k.app.transaction().execute(async (tx) => {
+        const { rows } = await sql `
+      select o.* from sys.outbox o
+      where o.status = 'pending'
+        and o.next_at <= now()
+        and not exists (
+          select 1 from sys.outbox p
+          where p.aggregate_id = o.aggregate_id
+            and p.id < o.id and p.status <> 'done')
+      order by o.id
+      limit ${limit}
+      for update skip locked`.execute(tx);
+        if (rows.length > 0) {
+            await tx
+                .updateTable('sys.outbox')
+                .set({ status: 'processing', locked_at: sql `now()` })
+                .where('id', 'in', rows.map((r) => r.id))
+                .execute();
+        }
+        return rows.map((r) => ({ ...r, id: Number(r.id) }));
+    });
+}
+/** 业务错误、状态不对、越权这类错误重试也不会成功，直接进死信 */
+function isPermanent(err) {
+    const e = err;
+    if (e?.permanent === true)
+        return true;
+    if (e?.retryable === true)
+        return false;
+    if (isCageError(err))
+        return !['CONFLICT', 'INTERNAL', 'RATE_LIMITED'].includes(e.code);
+    // 带错误码的框架错误（声明不一致、载荷不符合声明等）重试也不会好
+    return /\[CAGE-/.test(String(e?.message ?? ''));
+}
+export async function deliver(k, row, consumers, maxAttempts = MAX_ATTEMPTS) {
+    const mine = consumers.filter((c) => c.event === row.event);
+    try {
+        await withCarrier(row.trace, async () => {
+            for (const c of mine) {
+                await k.app.transaction().execute(async (tx) => {
+                    const first = await tx
+                        .insertInto('sys.processed_event')
+                        .values({ event_id: row.id, consumer: c.name })
+                        .onConflict((oc) => oc.columns(['event_id', 'consumer']).doNothing())
+                        .returning('event_id')
+                        .executeTakeFirst();
+                    if (!first)
+                        return; // 处理过了：直接跳过，保证幂等
+                    await c.handle(row, tx, k);
+                });
+            }
+        });
+        await k.app.updateTable('sys.outbox').set({ status: 'done', done_at: sql `now()`, locked_at: null }).where('id', '=', row.id).execute();
+        return 'done';
+    }
+    catch (err) {
+        const attempts = row.attempts + 1;
+        const message = isCageError(err) ? JSON.stringify(err.toJSON()) : String(err?.message ?? err);
+        if (attempts >= maxAttempts || isPermanent(err)) {
+            await k.app.transaction().execute(async (tx) => {
+                await tx
+                    .insertInto('sys.dead_letter')
+                    .values({ outbox_id: row.id, tenant_id: row.tenant_id, event: row.event, aggregate_id: row.aggregate_id, payload: JSON.stringify(row.payload), error: message, attempts })
+                    .execute();
+                await tx.updateTable('sys.outbox').set({ status: 'dead', attempts, last_error: message, locked_at: null }).where('id', '=', row.id).execute();
+            });
+            k.log.error({ outboxId: row.id, event: row.event, err: message }, '事件进入死信');
+            return 'dead';
+        }
+        await k.app
+            .updateTable('sys.outbox')
+            .set({ status: 'pending', attempts, last_error: message, locked_at: null, next_at: new Date(Date.now() + backoffMs(attempts)) })
+            .where('id', '=', row.id)
+            .execute();
+        k.log.warn({ outboxId: row.id, event: row.event, attempts, err: message }, '事件投递失败，稍后重试');
+        return 'retry';
+    }
+}
+/** 清扫：worker 崩溃后卡在「处理中」超过 5 分钟的事件重置为待投递 */
+export async function sweepStale(k, olderThanMs = 5 * 60_000) {
+    const r = await k.app
+        .updateTable('sys.outbox')
+        .set({ status: 'pending', locked_at: null })
+        .where('status', '=', 'processing')
+        .where('locked_at', '<', new Date(Date.now() - olderThanMs))
+        .executeTakeFirst();
+    return Number(r.numUpdatedRows);
+}
+/** 人工重放死信：仍然走内核流水线 */
+export async function replayDeadLetter(k, deadLetterId, handledBy) {
+    await k.app.transaction().execute(async (tx) => {
+        const d = await tx.selectFrom('sys.dead_letter').selectAll().where('id', '=', deadLetterId).where('handled_at', 'is', null).forUpdate().executeTakeFirst();
+        if (!d)
+            throw new Error('[CAGE-DLQ-001] 死信不存在或已处理');
+        await tx.updateTable('sys.outbox').set({ status: 'pending', attempts: 0, next_at: sql `now()`, last_error: null }).where('id', '=', d.outbox_id).execute();
+        await tx.updateTable('sys.dead_letter').set({ handled_by: handledBy, handled_at: sql `now()`, resolution: 'replayed' }).where('id', '=', deadLetterId).execute();
+        await sql `select pg_notify('cage_outbox', '')`.execute(tx);
+    });
+}
+/** 人工丢弃死信：标记完成，解除对同一聚合后续事件的阻塞 */
+export async function discardDeadLetter(k, deadLetterId, handledBy) {
+    await k.app.transaction().execute(async (tx) => {
+        const d = await tx.selectFrom('sys.dead_letter').selectAll().where('id', '=', deadLetterId).where('handled_at', 'is', null).forUpdate().executeTakeFirst();
+        if (!d)
+            throw new Error('[CAGE-DLQ-001] 死信不存在或已处理');
+        await tx.updateTable('sys.outbox').set({ status: 'done', done_at: sql `now()` }).where('id', '=', d.outbox_id).execute();
+        await tx.updateTable('sys.dead_letter').set({ handled_by: handledBy, handled_at: sql `now()`, resolution: 'discarded' }).where('id', '=', deadLetterId).execute();
+        await sql `select pg_notify('cage_outbox', '')`.execute(tx);
+    });
+}
+//# sourceMappingURL=outbox.js.map

package/dist/worker/outbox.js.map

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

package/dist/worker/scheduler.d.ts

@@ -0,0 +1,7 @@
+import type pg from 'pg';
+import type { Kernel } from '../kernel.js';
+import type { Job, JobApi } from '../primitives/flow.js';
+export declare function nextRun(cron: string, after: Date): Date;
+export declare function jobApi(k: Kernel, j: Job, tenantId: string, now: Date): JobApi;
+/** 执行一次任务（拿到锁才执行）；返回是否执行了 */
+export declare function tick(k: Kernel, j: Job, lockConn: pg.Client, scheduledAt: Date, force?: boolean): Promise<boolean>;