@yss123/cage-approval 0.3.0 → 0.3.2

package/README.md

@@ -60,6 +60,9 @@ export const poRoute = route('po-approval', [
 | `ApprovalAdapter` 等适配类型 | 对接外部审批实现时遵守的生命周期协议 |
 | `approvalRoutes` | 受认证保护的 HTTP 审批接口装配 |
 | `AiStepOptions`、`approvalRoleContext` | AI 节点配置与自动执行角色上下文 |
+| `TaskActionPolicy`、`TaskActionInput`、`InCodeEngine.act` | 人工节点显式开放转办、委派归还、当前节点并行必签；版本与操作记录共同提交 |
+| `InCodeEngine.taskHistory` | 当前单据授权读者按游标读取人工操作记录 |
+| `approvalOperations()` | 显式启用框架持久站内提醒、申请人催办与已读，复用现有 worker |
 
 领域绑定原语 `approval()` 从 `@yss123/cage-kernel` 导入；不要与本包的路由原语混淆。
 
@@ -67,8 +70,18 @@ AI 审批使用同一个 `step` 的 `kind: 'ai'` 选项，配置模型、材料
 
 ## 文档
 
-- [标准采购审批链路](https://github.com/shunshunyue/cage/blob/main/docs/ai/purchase-example.md)
-- [AI 审批三态、转人工和授权](https://github.com/shunshunyue/cage/blob/main/docs/ai/intelligence.md)
+人工节点可设置 `actions: { transfer: true, delegate: true, addSign: true }`，默认关闭并随流程实例保存。
+委派未归还不能批准；前、后及并行加签在 any/all 模式下都必须全部通过。候选任务先领取再决定，任务操作及启用候选/流转节点的决定须携带 revision。
+不能把任务管理理解为授予角色能力。升级需执行追加系统迁移，旧实例保持原政策。
+
+通用时效通过 `export const approvalOps = approvalOperations()` 启用。人工 `step` 配置 `sla: { durationMinutes: 1440, remindBeforeMinutes: 60 }`，
+`route` 第三参配置 `reminders: { requesterField: 'createdBy', cooldownMinutes: 15 }`，申请人字段必须进入 `approval.routable`。
+框架负责持久提醒、去重、当前接收人授权、冷却和已读；Admin 提供“我的申请”和“流程提醒”，业务应用无需自行实现通知表或定时器。
+节点时限采用自然分钟，加签、转办和领取不重置；尚无工作日历、自动升级、外部通知、并行网关或流程设计器。
+
+- [人工审批任务流转、SDK 与边界](https://github.com/shunshunyue/cage/blob/main/docs/development/guides/approvals.md)
+- [标准采购审批链路](https://github.com/shunshunyue/cage/blob/main/docs/development/examples/purchase-example.md)
+- [AI 审批三态、转人工和授权](https://github.com/shunshunyue/cage/blob/main/docs/development/guides/intelligence.md)
 - [采购审批完整源码](https://github.com/shunshunyue/cage/blob/main/examples/purchase-admin/packages/domain/src/modules/purchase/approvals.ts)
 
 源码与反馈：[GitHub](https://github.com/shunshunyue/cage)。许可证：[MIT](https://github.com/shunshunyue/cage/blob/main/LICENSE)。

package/dist/bridge.js

@@ -1,5 +1,5 @@
 // 桥接：引擎的结论只能转成命令，以流程身份调用，走完整 12 关。引擎侧没有任何业务表的数据库权限。
-import { cageError } from '@yss123/cage-kernel';
+import { cageError, loadUserGrants, userCtx } from '@yss123/cage-kernel';
 import { approvalRoleContext } from './ai.js';
 /**
  * 从流程绑定选择通过/驳回/退回命令，再为结论构造可信 process 上下文。
@@ -15,11 +15,15 @@ export async function applyOutcome(k, r, tx) {
         throw new Error('[CAGE-APPR-006] 审批未绑定退回修改命令');
     let ctx;
     if (r.lastApprover) {
-        const user = await k.contextFor(r.lastApprover, r.tenantId);
-        if (!user?.capabilities.has(k.registry.capabilityOf(cmd)))
+        // 待办决定已持有事务连接时复用它；同实例并发排队不能耗尽池后让锁持有者再等新连接。
+        const grants = await loadUserGrants(tx ?? k.app, r.lastApprover, r.tenantId);
+        const user = grants ? userCtx(grants) : null;
+        if (!user?.capabilities.has(k.registry.capabilityOf(cmd)) || !user.capabilities.has(`${binding.a.agg.name}.read`))
             throw cageError('FORBIDDEN');
         // 先核验真人对目标单据的权限；命令内声明的后台读依赖仍按已有流程身份完成业务校验。
-        await k.read.get(binding.a.agg, r.businessKey, user);
+        const visible = await k.read.tx(user, read => read.selectFrom(`safe.${binding.a.agg.table.name}`).select('id').where('id', '=', r.businessKey).executeTakeFirst());
+        if (!visible)
+            throw cageError('NOT_FOUND');
         ctx = k.processCtx({ process: r.process, tenantId: r.tenantId, onBehalfOf: r.lastApprover, capabilities: [k.registry.capabilityOf(cmd)] });
     }
     else

package/dist/bridge.js.map

@@ -1 +1 @@
-{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,OAAO,EAAE,SAAS,EAAyB,MAAM,qBAAqB,CAAC;AAGvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAE9C;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,CAAS,EAAE,CAAkB,EAAE,EAAqB;IACrF,MAAM,OAAO,GAAG,CAAC,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IACxD,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC,OAAO,QAAQ,CAAC,CAAC;IACzE,MAAM,GAAG,GAAG,CAAC,CAAC,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC;IACrI,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;IACzD,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC,CAAC,YAAY,EAAE,CAAC;QACnB,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC;QAC5D,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;YAAE,MAAM,SAAS,CAAC,WAAW,CAAC,CAAC;QACxF,2CAA2C;QAC3C,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;QACrD,GAAG,GAAG,CAAC,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,UAAU,EAAE,CAAC,CAAC,YAAY,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;IAC7I,CAAC;;QAAM,GAAG,GAAG,MAAM,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC;IACjE,MAAM,KAAK,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,eAAe,EAAE,CAAC,CAAC,eAAe,EAAE,CAAC;IACxE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;AAC/E,CAAC;AAED,uDAAuD;AACvD,oDAAoD;AACpD,MAAM,UAAU,YAAY,CAAC,OAAwB,EAAE,CAAS;IAC9D,OAAO,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;QAC9B,MAAM,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3B,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"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"}

package/dist/deadlines.d.ts

@@ -0,0 +1,29 @@
+import { type Transaction } from 'kysely';
+/** 自然分钟时限；允许小数，精度至少一毫秒，最长一年，不包含工作日历或暂停扣时。 */
+export interface ApprovalSla {
+    /** 从进入节点起计算的总办理分钟数，前后加签共用这一截止时间。 */
+    durationMinutes: number;
+    /** 在截止前多少分钟产生临期提醒；省略只提醒超时，必须小于总时限。 */
+    remindBeforeMinutes?: number;
+}
+/** 申请人催办政策随实例冻结；字段只标识申请人，不授予其审批结论能力。 */
+export interface ApprovalReminderPolicy {
+    /** routable 快照中的单个用户 UUID 字段，运行时还需当前用户有效且可见业务单据。 */
+    requesterField: string;
+    /** 两次成功催办间隔的自然分钟数，同实例各节点共用冷却；无收件人不占用冷却。 */
+    cooldownMinutes: number;
+}
+/** 校验并冻结节点政策；未知键和不合理提前量明确报声明错误，不把配置失误静默当作关闭提醒。 */
+export declare function approvalSla(value: ApprovalSla): Readonly<ApprovalSla>;
+/** 校验申请人字段名与正数冷却；真正的字段存在性、routable 和公开性在注册表装配后再检查。 */
+export declare function approvalReminderPolicy(value: ApprovalReminderPolicy): Readonly<ApprovalReminderPolicy>;
+/**
+ * 在进入人工节点的同一事务登记固定截止时间；使用数据库时间，服务重启不会丢失或重新计时。
+ * next_notice_scan_at 是有界扫描的持久轮转位置，后续收件人变化可补投，不让已提醒的旧步骤长期占满扫描批次。
+ */
+export declare function initializeDeadline(tx: Transaction<any>, instanceId: string, step: number, policy: ApprovalSla): Promise<void>;
+/** 前向迁移：时间只新增到节点，通知以来源/任务/接收人唯一；已读不删除历史，禁止修改已发布迁移。 */
+export declare const APPROVAL_DEADLINES_MIGRATION: {
+    name: string;
+    sql: string;
+};

package/dist/deadlines.js

@@ -0,0 +1,72 @@
+/**
+ * 人工节点的自然时间办理政策及持久存储，由 route 校验声明、engine 在进入节点时写入。
+ * 时限属于整个节点：领取、转办、委派和前后加签均不重置；这里只计时，不替代领域结论或自动批准。
+ * 迁移在已发布审批表之上追加，旧实例没有时限或催办政策，升级不会自动启用新行为。
+ */
+import { declError } from '@yss123/cage-kernel';
+import { sql } from 'kysely';
+import { z } from 'zod';
+const minutes = z.number().finite().min(1 / 60_000).max(525_600);
+const slaSchema = z.strictObject({ durationMinutes: minutes, remindBeforeMinutes: minutes.optional() })
+    .refine(value => value.remindBeforeMinutes === undefined || Math.round(value.remindBeforeMinutes * 60_000) < Math.round(value.durationMinutes * 60_000));
+const reminderSchema = z.strictObject({ requesterField: z.string().regex(/^[A-Za-z][A-Za-z0-9]*$/), cooldownMinutes: minutes });
+/** 校验并冻结节点政策；未知键和不合理提前量明确报声明错误，不把配置失误静默当作关闭提醒。 */
+export function approvalSla(value) {
+    const parsed = slaSchema.safeParse(value);
+    if (!parsed.success)
+        throw declError('CAGE-APPR-006', 'sla 须为有效自然分钟时限（至少一毫秒，最长一年），提前提醒必须小于总时限');
+    return Object.freeze(parsed.data);
+}
+/** 校验申请人字段名与正数冷却；真正的字段存在性、routable 和公开性在注册表装配后再检查。 */
+export function approvalReminderPolicy(value) {
+    const parsed = reminderSchema.safeParse(value);
+    if (!parsed.success)
+        throw declError('CAGE-APPR-006', 'reminders 需要有效 requesterField 和自然分钟 cooldownMinutes（至少一毫秒，最长一年）');
+    return Object.freeze(parsed.data);
+}
+/**
+ * 在进入人工节点的同一事务登记固定截止时间；使用数据库时间，服务重启不会丢失或重新计时。
+ * next_notice_scan_at 是有界扫描的持久轮转位置，后续收件人变化可补投，不让已提醒的旧步骤长期占满扫描批次。
+ */
+export async function initializeDeadline(tx, instanceId, step, policy) {
+    const duration = Math.round(policy.durationMinutes * 60_000);
+    const before = policy.remindBeforeMinutes === undefined ? null : Math.round(policy.remindBeforeMinutes * 60_000);
+    await tx.updateTable('flow.approval_step').set({
+        due_at: sql `now() + ${duration} * interval '1 millisecond'`,
+        remind_at: before === null ? null : sql `now() + ${duration - before} * interval '1 millisecond'`,
+        next_notice_scan_at: sql `now() + ${duration - (before ?? 0)} * interval '1 millisecond'`,
+    }).where('instance_id', '=', instanceId).where('step', '=', step).execute();
+}
+/** 前向迁移：时间只新增到节点，通知以来源/任务/接收人唯一；已读不删除历史，禁止修改已发布迁移。 */
+export const APPROVAL_DEADLINES_MIGRATION = {
+    name: 'cage:approval_deadlines_003',
+    sql: `
+ALTER TABLE flow.approval_instance ADD COLUMN reminder_policy jsonb;
+ALTER TABLE flow.approval_instance ADD COLUMN next_urge_at timestamptz;
+ALTER TABLE flow.approval_step ADD COLUMN due_at timestamptz;
+ALTER TABLE flow.approval_step ADD COLUMN remind_at timestamptz;
+ALTER TABLE flow.approval_step ADD COLUMN next_notice_scan_at timestamptz;
+ALTER TABLE flow.approval_step ADD CONSTRAINT approval_step_deadline_order CHECK (remind_at IS NULL OR (due_at IS NOT NULL AND remind_at < due_at));
+CREATE INDEX approval_step_notice_scan_idx ON flow.approval_step(next_notice_scan_at, instance_id) WHERE next_notice_scan_at IS NOT NULL;
+CREATE TABLE flow.approval_notice (
+  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  tenant_id uuid NOT NULL,
+  instance_id uuid NOT NULL REFERENCES flow.approval_instance(id),
+  task_id uuid NOT NULL REFERENCES flow.approval_task(id),
+  step integer NOT NULL,
+  recipient_id uuid NOT NULL,
+  source text NOT NULL,
+  kind text NOT NULL CHECK (kind IN ('due_soon','overdue','urge')),
+  actor_id uuid,
+  reason text,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  read_at timestamptz,
+  UNIQUE(instance_id, step, source, task_id, recipient_id)
+);
+CREATE INDEX approval_notice_recipient_idx ON flow.approval_notice(tenant_id, recipient_id, id);
+CREATE INDEX approval_notice_unread_idx ON flow.approval_notice(tenant_id, recipient_id, id) WHERE read_at IS NULL;
+GRANT SELECT, INSERT, UPDATE ON flow.approval_notice TO cage_app;
+GRANT USAGE, SELECT ON SEQUENCE flow.approval_notice_id_seq TO cage_app;
+`,
+};
+//# sourceMappingURL=deadlines.js.map

package/dist/deadlines.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deadlines.js","sourceRoot":"","sources":["../src/deadlines.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,GAAG,EAAoB,MAAM,QAAQ,CAAC;AAC/C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAkBxB,MAAM,OAAO,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AACjE,MAAM,SAAS,GAAG,CAAC,CAAC,YAAY,CAAC,EAAE,eAAe,EAAE,OAAO,EAAE,mBAAmB,EAAE,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC;KACpG,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,mBAAmB,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,mBAAmB,GAAG,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,eAAe,GAAG,MAAM,CAAC,CAAC,CAAC;AAC3J,MAAM,cAAc,GAAG,CAAC,CAAC,YAAY,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,wBAAwB,CAAC,EAAE,eAAe,EAAE,OAAO,EAAE,CAAC,CAAC;AAEhI,kDAAkD;AAClD,MAAM,UAAU,WAAW,CAAC,KAAkB;IAC5C,MAAM,MAAM,GAAG,SAAS,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC1C,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,MAAM,SAAS,CAAC,eAAe,EAAE,wCAAwC,CAAC,CAAC;IAChG,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AACpC,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,sBAAsB,CAAC,KAA6B;IAClE,MAAM,MAAM,GAAG,cAAc,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/C,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,MAAM,SAAS,CAAC,eAAe,EAAE,iEAAiE,CAAC,CAAC;IACzH,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AACpC,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,EAAoB,EAAE,UAAkB,EAAE,IAAY,EAAE,MAAmB;IAClH,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,eAAe,GAAG,MAAM,CAAC,CAAC;IAC7D,MAAM,MAAM,GAAG,MAAM,CAAC,mBAAmB,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,mBAAmB,GAAG,MAAM,CAAC,CAAC;IACjH,MAAM,EAAE,CAAC,WAAW,CAAC,oBAAoB,CAAC,CAAC,GAAG,CAAC;QAC7C,MAAM,EAAE,GAAG,CAAA,WAAW,QAAQ,6BAA6B;QAC3D,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAA,WAAW,QAAQ,GAAG,MAAM,6BAA6B;QAChG,mBAAmB,EAAE,GAAG,CAAA,WAAW,QAAQ,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC,6BAA6B;KACzF,CAAC,CAAC,KAAK,CAAC,aAAa,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;AAC9E,CAAC;AAED,sDAAsD;AACtD,MAAM,CAAC,MAAM,4BAA4B,GAAG;IAC1C,IAAI,EAAE,6BAA6B;IACnC,GAAG,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BN;CACA,CAAC"}

package/dist/engine.d.ts

@@ -1,8 +1,15 @@
+/**
+ * 原生结构化审批执行器：实例、AND 分支、候选/直派任务及签署阶段存在 flow 模式，结论经桥接调用领域命令。
+ * HTTP、worker 和 AI 运行时共用本入口；按实例锁串行决定，前后签激活与最后结论共同事务提交。
+ * waiting 不是完成；任务选人不授予能力，最后命令拒绝（如超额度）会回滚本次决定及附带变化。
+ */
 import { type Kernel, type Ctx } from '@yss123/cage-kernel';
 import { type ApprovalEngine } from '@yss123/cage-kernel/worker';
 import { type Transaction } from 'kysely';
 import { type Route } from './route.js';
+import { type BranchLocation } from './execution.js';
 import { type AiDecision } from './ai.js';
+import { type TaskActionInput, type TaskActionPolicy } from './task-actions.js';
 /** 对外待办摘要；step 为 0 基索引，vars 仅来自 routable 白名单，不包含整份领域对象。 */
 export interface TaskView {
     id: string;
@@ -12,23 +19,50 @@ export interface TaskView {
     businessKey: string;
     step: number;
     title: string;
+    /** 所属并行组/分支路径；普通主线或旧顺序实例为空数组，不把索引大小当作实际执行先后。 */
+    branchPath: BranchLocation[];
     status: string;
     vars: Record<string, unknown>;
     createdAt: string;
+    /** 节点总办理截止 UTC 时间；无 SLA 为 null，waiting 或转办不重置，不代表自动批准时间。 */
+    dueAt: string | null;
+    /** 待办版本，启用任务流转的节点提交决定时也必须携带。 */
+    revision: number;
+    /** 当前持有人；候选池待领取时为空。 */
+    assigneeId: string | null;
+    /** direct 直接分配，candidate 允许当前候选领取/持有人释放。 */
+    assignment: 'direct' | 'candidate';
+    /** 加签来源任务；旧并行加签和原始任务可为空。 */
+    parentTaskId: string | null;
+    /** 相对父任务的签署顺序；null 表示原票或旧版未记录签序。 */
+    signPosition: 'parallel' | 'before' | 'after' | null;
+    /** 实例允许的新加签位置；未开放为 []，第一批旧快照仅 parallel，不表示本任务可以再次加签。 */
+    signPositions: readonly ('parallel' | 'before' | 'after')[];
+    /** 委派原负责人；未委派或已转办时为空。 */
+    ownerId: string | null;
+    /** pending 表示受托处理中，只能归还；resolved 表示已归还原负责人。 */
+    delegation: 'pending' | 'resolved' | null;
+    /** original 是路由选人，additional 是节点前后/并行追加必签。 */
+    taskKind: 'original' | 'additional';
+    /** 实例快照中的动作政策，仅供界面显示；服务端仍会实时授权。 */
+    actions: Readonly<TaskActionPolicy>;
 }
 /**
- * 有限顺序路由的持久执行器：实例保存展开后的步骤，人工任务和 AI 节点共享同一推进/结束边界。
+ * 有限无环路由的持久执行器：实例冻结展开步骤与依赖，人工任务和 AI 节点共享同一推进/结束边界。
  * 以实例行锁串行化决定，最后结论与领域命令共同事务提交；命令失败时本次审批也不能算完成。
  */
 export declare class InCodeEngine implements ApprovalEngine {
     private readonly k;
     readonly route: Route;
     constructor(k: Kernel, route: Route);
-    /** 按显式用户、角色或部门负责人解析候选；部门无负责人向祖先查找，空结果由 openTasks 明确拒绝。 */
-    private approversOf;
+    /**
+     * 执行候选领取/释放或本人待办转办/委派/归还/前后加签；必需任务版本与原因，失败不会部分更新。
+     * 分配或动作政策须显式启用，接收人须已有批准和读取权限；返回版本及新任务 ID，不推进领域状态。
+     */
+    act(taskId: string, userId: string, tenantId: string, input: TaskActionInput): Promise<import("./task-actions.js").TaskActionResult>;
     /** 登记当前节点与提交版本；AI 节点排队等待运行时领取，人工节点立即解析候选并创建待办。 */
     private openStep;
-    /** 候选去重后逐个建立待办；找不到人是配置错误，不能跳过步骤或默认审批通过。 */
+    /** direct 逐人建立票，candidate 只建一项未领取任务；空候选明确报错，不跳过或默认通过。 */
     private openTasks;
     /**
      * 在消费事务中创建新轮次：先取消旧执行者，再保存展开步骤和触发事件/提交版本。
@@ -52,44 +86,86 @@ export declare class InCodeEngine implements ApprovalEngine {
         tenantId: string;
         tx: Transaction<any>;
     }): Promise<void>;
-    /** 我的待办 */
+    /**
+     * 从本人最近 200 条任务候选中按当前单据 read/范围过滤，撤权或停用后不继续披露任务摘要。
+     * vars 是历史 routable 摘要，始终去隐藏字段并掩码；需要明文时另经带审计的业务读接口获取。
+     */
     tasksOf(userId: string, tenantId: string, status?: string): Promise<TaskView[]>;
-    /** 以业务对象读权限查看审批轮次；隐藏内部 policy、提示词、工具历史和运行凭据。 */
+    /**
+     * 查询最近 200 项未领取候选中的可见任务；当前候选身份与批准/read 权限均需成立。
+     * 列表不是占用承诺，领取必须再次锁定并校验；待领取任务不会混入 tasksOf/AI 的可决定清单。
+     */
+    candidateTasks(userId: string, tenantId: string): Promise<TaskView[]>;
+    /** 共用安全摘要投影；候选规则在读取时解析，组织变化即时影响候选清单，历史变量仍始终掩码。 */
+    private listTasks;
+    /** 以业务对象读权限查看审批轮次；步骤标题取提交时的快照，隐藏内部 policy、提示词、工具历史和运行凭据。 */
     history(aggregate: string, businessKey: string, ctx: Ctx): Promise<{
         id: any;
         process: string;
         status: any;
         currentStep: any;
+        currentSteps: any[];
+        definitionVersion: string | null;
         createdAt: string;
         updatedAt: string;
         steps: {
             index: any;
+            title: string;
+            branchPath: BranchLocation[];
+            dependsOn: number[];
             kind: any;
             status: any;
             decision: any;
             detailRestricted: boolean;
             actor: any;
             updatedAt: string;
+            dueAt: string | null;
         }[];
     }[]>;
+    /**
+     * 按业务对象当前 read/范围读取本流程的人工操作记录，跨轮次以递增 ID 游标分页。
+     * after 是服务端返回的十进制字符串，避免 bigint 转为 JS number 丢失精度；默认 50、最多 200 条。
+     * 历史意见仅供同一对象的授权读者共享，不返回任务变量或 AI 提示词；旧迁移前的动作不会伪造补录。
+     */
+    taskHistory(aggregate: string, businessKey: string, ctx: Ctx, options?: {
+        after?: string;
+        limit?: number;
+    }): Promise<{
+        items: {
+            id: string;
+            instanceId: any;
+            taskId: any;
+            actorId: any;
+            action: any;
+            reason: any;
+            details: any;
+            createdAt: string;
+        }[];
+        nextCursor: string | null;
+    }>;
     /** 审批人做出决定；流程结束时在同一事务里执行结论命令 */
-    decide(taskId: string, userId: string, tenantId: string, outcome: 'approved' | 'rejected' | 'returned', comment?: string): Promise<{
+    decide(taskId: string, userId: string, tenantId: string, outcome: 'approved' | 'rejected' | 'returned', comment?: string, expectedRevision?: number): Promise<{
         finished: boolean;
         outcome?: string;
     }>;
     /** AI 助理的动作回执可与人工待办决定共用该事务，重试不重复审批。 */
     /**
      * 先按租户/受托人定位任务，再锁实例和任务并实时验证能力/单据可见性；过期待办不允许再次决定。
-     * 驳回/退回直接结束；all 等待同节点所有人通过，any 将其他待办标 skipped 后进入下一节点。
+     * 委派未归还或 waiting 时拒绝决定；候选/启用流转的节点要求 revision，避免责任或阶段变化后旧决定仍生效。
+     * 驳回/退回直接结束；all 等待全部，any 等任一原票及全部追加票；批准后激活已满足依赖的前后签。
      * 外层拥有事务提交权，可与 AI 助理动作回执共同提交；finished:false 仅表示流程还需后续步骤。
      */
-    decideIn(tx: Transaction<any>, taskId: string, userId: string, tenantId: string, outcome: 'approved' | 'rejected' | 'returned', comment?: string): Promise<{
+    decideIn(tx: Transaction<any>, taskId: string, userId: string, tenantId: string, outcome: 'approved' | 'rejected' | 'returned', comment?: string, expectedRevision?: number): Promise<{
         finished: boolean;
         outcome?: string;
     }>;
     /** 先执行带版本的领域结论命令，成功后才关闭剩余待办并写流程终态，保证两边不会各自成功。 */
     private finish;
-    /** 将当前节点标通过并开启下一步；最后一步转 finish，因此 AI pass 也不必然立即批准整张单据。 */
+    /**
+     * 在实例锁内完成一项节点，再开启所有前驱已通过且尚无持久记录的节点；AND 汇合等待每条分支末端。
+     * 创建节点和最终领域结论都在当前事务内，失败回滚本次签署；重启只依赖数据库状态，唯一键阻止重复节点。
+     * current_step 仅保留最小活跃索引给旧读者，决定、AI 与提醒均以节点自身状态为准。
+     */
     private advance;
     /** 只有仍然占据该节点的 run 能提交；调用方需在同一事务核验 AI run 租约。 */
     /**