M4: 范式引擎与任务运行时

skill-engine(L4):载方法不载权力(白名单外工具即拒)、结晶片段经 ToolInvoker 留痕、
  装配入信封、技能目录渐进披露

flow-engine(L5):四种步型、确定性谓词跳步、重试与声明给定的兜底、
  异步步即监听(时限必配)、写类工具登记动作意向、步序位置持久

loop-engine(L5):自研 CMMN 子集解析器(表外构件直接报错,子集封顶可机器证明)、
  两副标准生命周期与迁移拓扑(引擎不得私改)、Enabled ≠ Active、
  语义性前提标待裁量评估(引擎不代裁量)、DMN 确定性求值 + 命中行留痕、
  DRD 缺口演绎与拓扑序、双向驱动与交集导航(断点即人环)、三型行动、
  终局唯放行与 Harness

task(L6):终态五名裁定(released 唯一成功)、Harness 预算环外强制与停滞熔断
  (监听中是健康态)、控制三语义(叫停不是终态,记最重档纠正)、改派留痕通知双方、
  断点续跑三份持久状态、封卷触发蒸馏钩子

301 个测试通过,门禁五道全绿

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KeDBx2PHLavbURXB8LJJ7m

api-report/apps/api/src/modules/flow-engine/contract.d.ts

@@ -0,0 +1,40 @@
+/**
+ * module: flow-engine —— 对外类型(编码规范 §10.1;语义出处 AM 05)。
+ *
+ * flow 范式:步序声明运行器(四种步型、重试与兜底、事件即步条件)。
+ * **零临场调度** —— 运行中不得由 LLM 决定步序、跳步或兜底。
+ */
+import type { FlowModel, FlowStep, TaskId } from '@contracts';
+import type { FailureAction, FlowIssue, FlowPosition, NextAction, StepRuntime, StepState } from './internal/domain/step-sequence.ts';
+export type { FailureAction, FlowIssue, FlowModel, FlowPosition, FlowStep, NextAction, StepRuntime, StepState };
+export declare class FlowDeclarationInvalidError extends Error {
+    readonly issues: readonly FlowIssue[];
+    constructor(issues: readonly FlowIssue[]);
+}
+/** 一次推进的结果 —— 由 task 驱动,不自转 */
+export type AdvanceOutcome = {
+    readonly position: FlowPosition;
+    readonly status: 'running' | 'awaiting' | 'finished' | 'blocked';
+    /** awaiting 时:在等什么 */
+    readonly waitingFor?: {
+        readonly kind: 'human' | 'event' | 'time';
+        readonly ref: string;
+        readonly deadline: string;
+    };
+    /** finished 时:末步验收工单的裁决决定终态 */
+    readonly released?: boolean;
+    readonly blockedReason?: string;
+};
+export type FlowEngineService = {
+    /** 装载步序声明并校验 —— 谱必须全程可静态检查 */
+    load(taskId: TaskId, model: FlowModel): Promise<FlowPosition>;
+    position(taskId: TaskId): Promise<FlowPosition | undefined>;
+    /** 推进一步(或若干确定步);异步步进入 awaiting 并登记监听 */
+    advance(taskId: TaskId): Promise<AdvanceOutcome>;
+    /** 事件即步的完成条件:人事件 / 数据事件 / 时间事件到达即续跑 */
+    resume(taskId: TaskId, event: {
+        kind: 'human' | 'data' | 'time';
+        ref: string;
+        payload: Record<string, unknown>;
+    }): Promise<AdvanceOutcome>;
+};

api-report/apps/api/src/modules/flow-engine/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * module: flow-engine —— 唯一出口。只做 re-export,不写逻辑(编码规范 §10.1)。
+ */
+export type { AdvanceOutcome, FailureAction, FlowEngineService, FlowIssue, FlowModel, FlowPosition, FlowStep, NextAction, StepRuntime, StepState, } from './contract.ts';
+export { FlowDeclarationInvalidError } from './contract.ts';
+export type { CardGateway, Clock, FlowStateStore, IdGenerator, ListenerRegistrar, LlmStepGateway, MemoryRecorder, PredicateEvaluator, TaskContext, TaskDataGateway, ToolStepInvoker, } from './port.ts';
+export type { FlowRunnerDeps } from './internal/usecase/flow-runner.ts';
+export { createFlowRunner } from './internal/usecase/flow-runner.ts';
+export { checkDeclaration, failureAction, initialPosition, lastStepIsAcceptance, markStep, nextAction, parallelGroupComplete, STEP_STATES, } from './internal/domain/step-sequence.ts';
+export { createFlowStateStore } from './internal/adapter/flow-state-store.ts';
+export { flowStateTable } from './internal/adapter/flow-state-schema.ts';

api-report/apps/api/src/modules/flow-engine/port.d.ts

@@ -0,0 +1,110 @@
+/**
+ * module: flow-engine —— 本模块要外界提供的能力(编码规范 §10.1 / §5.3)。
+ */
+import type { FlowModel, StaffId, TaskId } from '@contracts';
+import type { FlowPosition } from './internal/domain/step-sequence.ts';
+export type Clock = {
+    now(): Date;
+};
+export type IdGenerator = {
+    next(): string;
+};
+/** 运行时实例状态 —— 三份持久状态之一(OS 09) */
+export type FlowStateStore = {
+    save(taskId: TaskId, model: FlowModel, position: FlowPosition): Promise<void>;
+    load(taskId: TaskId): Promise<{
+        model: FlowModel;
+        position: FlowPosition;
+    } | undefined>;
+};
+/** 条件谓词求值 —— app 注入 `@sfeel`;零 LLM */
+export type PredicateEvaluator = (expression: string, scope: Readonly<Record<string, unknown>>) => boolean;
+/** 任务数据 —— app 注入 `ledger`(L1):读任务视图 = 正式版 + 本任务草稿层 */
+export type TaskDataGateway = {
+    view(taskId: TaskId): Promise<Record<string, unknown>>;
+    draftWrite(input: {
+        taskId: TaskId;
+        domain: string;
+        object: string;
+        key: Record<string, string | number>;
+        patch: Record<string, unknown>;
+    }): Promise<void>;
+};
+/** 工具步与纯工具步 —— app 注入 `toolbox`(L2) */
+export type ToolStepInvoker = {
+    invoke(input: {
+        tool: string;
+        input: Record<string, unknown>;
+        activityId: string;
+        taskId: TaskId;
+        stepNo: number;
+    }): Promise<{
+        ok: boolean;
+        output?: Record<string, unknown>;
+        error?: {
+            message: string;
+            retryable: boolean;
+        };
+    }>;
+    /** 写类工具在 flow 里也走「登记动作意向」,除非契约显式预授权 */
+    registerIntent(input: {
+        taskId: TaskId;
+        tool: string;
+        input: Record<string, unknown>;
+        label: string;
+    }): Promise<void>;
+    isWriteEffect(tool: string): Promise<boolean>;
+};
+/** LLM 步 —— app 注入 `llm`(L1)的 ModelGateway;模板与出参 schema 随声明版本冻结 */
+export type LlmStepGateway = {
+    generate(input: {
+        model: string;
+        prompt: string;
+        outputSchema: Record<string, unknown>;
+        taskId: TaskId;
+        stepNo: number;
+    }): Promise<{
+        ok: boolean;
+        object?: unknown;
+        error?: string;
+    }>;
+};
+/** 人类工具步 —— app 注入 `human-tool`(L3) */
+export type CardGateway = {
+    issue(input: {
+        taskId: TaskId;
+        ownerId: StaffId;
+        humanCallCap: number;
+        workOrder: 'execution' | 'acceptance';
+        card: Record<string, unknown>;
+    }): Promise<{
+        id: string;
+    }>;
+};
+/** 监听登记 —— app 注入 `event`(L1):异步步的完成条件 = 监听,时限必配 */
+export type ListenerRegistrar = {
+    register(input: {
+        taskId: TaskId;
+        eventType: 'data' | 'time' | 'human';
+        keyFilter: Record<string, string>;
+        deadline: string;
+    }): Promise<{
+        id: string;
+    }>;
+};
+export type MemoryRecorder = {
+    append(input: {
+        taskId: TaskId;
+        kind: 'action' | 'result' | 'engine-transition';
+        title: string;
+        detail?: Record<string, unknown>;
+    }): Promise<void>;
+};
+/** 任务上下文 —— 活动 ID、负责人、预算 */
+export type TaskContext = {
+    of(taskId: TaskId): Promise<{
+        activityId: string;
+        ownerId: StaffId;
+        humanCallCap: number;
+    }>;
+};

api-report/apps/api/src/modules/loop-engine/contract.d.ts

@@ -0,0 +1,100 @@
+/**
+ * module: loop-engine —— 对外类型(编码规范 §10.1;语义出处 AM 03 / 04)。
+ *
+ * loop 的运行 = **CMMN 语义引擎(下层,零 LLM)× Agent 回路(上层,临场裁量)**。
+ * 两层的耦合点是任务数据(驱动耦合)与任务记忆(记录同轴)。
+ */
+import type { LoopModel, TaskId } from '@contracts';
+import type { CaseModel, PlanItem, PlanItemType } from './internal/domain/cmmn-parse.ts';
+import type { CaseRuntime, CaseState, EnabledEntry, EnabledSet, ItemRuntime, ItemState, Navigation, TerminalAuthority } from './internal/domain/lifecycle.ts';
+import type { DecisionResult, DecisionTrace, Gap } from './internal/domain/dmn.ts';
+export type { CaseModel, CaseRuntime, CaseState, DecisionResult, DecisionTrace, EnabledEntry, EnabledSet, Gap, ItemRuntime, ItemState, LoopModel, Navigation, PlanItem, PlanItemType, TerminalAuthority, };
+export { CmmnParseError } from './internal/domain/cmmn-parse.ts';
+export { IllegalTransitionError } from './internal/domain/lifecycle.ts';
+export declare class ForbiddenTerminalError extends Error {
+    readonly by: TerminalAuthority;
+    constructor(by: TerminalAuthority);
+}
+export declare class AutomaticOnWorldTouchingError extends Error {
+    readonly itemId: string;
+    constructor(itemId: string);
+}
+/** Agent 的三型行动 —— 每一步行动属于且仅属于其一(AM 4.2) */
+export type AgentAction = 
+/** 调工具:系统调用与 LLM 工具 */
+{
+    readonly kind: 'tool';
+    readonly itemId: string;
+    readonly tool: string;
+    readonly input: Record<string, unknown>;
+}
+/** 调人:四卡之一 —— 调人 = 立监听听人 */
+ | {
+    readonly kind: 'human';
+    readonly itemId: string;
+    readonly card: Record<string, unknown>;
+    readonly workOrder: 'execution' | 'acceptance';
+}
+/** 立监听:AI 不能调用世界,对世界只有两种合法姿势 —— 触达它(动作)与等它(监听) */
+ | {
+    readonly kind: 'listen';
+    readonly itemId: string;
+    readonly eventType: 'data' | 'time';
+    readonly keyFilter: Record<string, string>;
+    readonly deadline: string;
+}
+/** 启动一个 Enabled 项(manualStart,留痕) */
+ | {
+    readonly kind: 'start';
+    readonly itemId: string;
+}
+/** 规划裁量项入场 */
+ | {
+    readonly kind: 'plan';
+    readonly itemId: string;
+}
+/** 弃用某项(此单不走这条) */
+ | {
+    readonly kind: 'disable';
+    readonly itemId: string;
+    readonly reason: string;
+}
+/** 评估语义性前提(评估留痕,可回放可归因) */
+ | {
+    readonly kind: 'judge';
+    readonly criterion: string;
+    readonly satisfied: boolean;
+    readonly rationale: string;
+}
+/** 判定成果已齐,提交放行 */
+ | {
+    readonly kind: 'submit';
+    readonly rationale: string;
+};
+export type TurnOutcome = {
+    readonly runtime: CaseRuntime;
+    readonly enabled: EnabledSet;
+    readonly navigation: Navigation;
+    readonly action?: AgentAction;
+    readonly status: 'running' | 'awaiting' | 'submitted' | 'blocked';
+    readonly blockedReason?: string;
+};
+export type LoopEngineService = {
+    /** 装载:XML 进语义引擎,说明书进 Agent 上下文;版本全部入信封 */
+    load(taskId: TaskId, model: LoopModel): Promise<CaseRuntime>;
+    runtime(taskId: TaskId): Promise<CaseRuntime | undefined>;
+    /** 发布 Enabled 集与红绿灯 —— 引擎推进的终点 */
+    publish(taskId: TaskId): Promise<EnabledSet>;
+    /** 跑一个回合:定位 → 择向 → 决断 → 行动 → 写数据 */
+    runTurn(taskId: TaskId): Promise<TurnOutcome>;
+    /** 事件驱动续跑:数据 / 时间 / 人 / 控制 */
+    onEvent(taskId: TaskId, event: {
+        kind: 'data' | 'time' | 'human' | 'control';
+        ref: string;
+        payload: Record<string, unknown>;
+    }): Promise<TurnOutcome>;
+    /** DMN 确定性求值 —— 能算的不问 LLM */
+    decide(taskId: TaskId, decision: string): Promise<DecisionResult>;
+    /** 驳回:相关计划项以新实例重新入场(迁移不是状态) */
+    reenter(taskId: TaskId, itemId: string): Promise<CaseRuntime>;
+};

api-report/apps/api/src/modules/loop-engine/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * module: loop-engine —— 唯一出口。只做 re-export,不写逻辑(编码规范 §10.1)。
+ */
+export type { AgentAction, CaseModel, CaseRuntime, CaseState, DecisionResult, DecisionTrace, EnabledEntry, EnabledSet, Gap, ItemRuntime, ItemState, LoopEngineService, LoopModel, Navigation, PlanItem, PlanItemType, TerminalAuthority, TurnOutcome, } from './contract.ts';
+export { AutomaticOnWorldTouchingError, CmmnParseError, ForbiddenTerminalError, IllegalTransitionError, } from './contract.ts';
+export type { AgentPort, CardGateway, Clock, ListenerRegistrar, LoopStateStore, MemoryRecorder, Sfeel, TaskContext, TaskDataGateway, ToolGateway, } from './port.ts';
+export type { TurnRunnerDeps } from './internal/usecase/turn-runner.ts';
+export { createTurnRunner } from './internal/usecase/turn-runner.ts';
+export { parseCmmn, parseXml, PLAN_ITEM_TYPES } from './internal/domain/cmmn-parse.ts';
+export { assertItemTransition, autoCompleteReady, canTransitionCase, canTransitionItem, CASE_STATES, evaluateCriterion, initialRuntime, ITEM_STATES, mayCompleteCase, mayTerminateCase, navigate, occur, publishEnabled, reenter, transitionItem, } from './internal/domain/lifecycle.ts';
+export { deduceGaps, evaluateTable, evaluationOrder, isBindingConclusion } from './internal/domain/dmn.ts';
+export { createLoopStateStore } from './internal/adapter/loop-state-store.ts';
+export { loopStateTable } from './internal/adapter/loop-state-schema.ts';

api-report/apps/api/src/modules/loop-engine/port.d.ts

@@ -0,0 +1,112 @@
+/**
+ * module: loop-engine —— 本模块要外界提供的能力(编码规范 §10.1 / §5.3)。
+ */
+import type { LoopModel, StaffId, TaskId } from '@contracts';
+import type { CaseModel } from './internal/domain/cmmn-parse.ts';
+import type { CaseRuntime, EnabledSet } from './internal/domain/lifecycle.ts';
+import type { AgentAction } from './contract.ts';
+export type Clock = {
+    now(): Date;
+};
+/** 运行时实例状态 —— loop 的模型定位与就绪集(OS 09 三份持久状态之一) */
+export type LoopStateStore = {
+    save(taskId: TaskId, model: LoopModel, parsed: CaseModel, runtime: CaseRuntime): Promise<void>;
+    load(taskId: TaskId): Promise<{
+        model: LoopModel;
+        parsed: CaseModel;
+        runtime: CaseRuntime;
+    } | undefined>;
+};
+/** S-FEEL —— app 注入 `@sfeel`;引擎零 LLM */
+export type Sfeel = {
+    condition(expression: string, scope: Readonly<Record<string, unknown>>): boolean;
+    expression(expression: string, scope: Readonly<Record<string, unknown>>): unknown;
+    unaryTest(cell: string, value: unknown, scope: Readonly<Record<string, unknown>>): boolean;
+};
+/** 任务数据 —— app 注入 `ledger`(L1):引擎对**任务视图**求值,不依赖事件 */
+export type TaskDataGateway = {
+    view(taskId: TaskId): Promise<Record<string, unknown>>;
+    draftWrite(input: {
+        taskId: TaskId;
+        domain: string;
+        object: string;
+        key: Record<string, string | number>;
+        patch: Record<string, unknown>;
+    }): Promise<void>;
+};
+/**
+ * Agent 回路 —— app 注入(Mastra Agent 在 adapter,§6.1)。
+ * **回合由 usecase 驱动,不放开自由 maxSteps,预算在环外由 Harness 强制。**
+ */
+export type AgentPort = {
+    decide(input: {
+        taskId: TaskId;
+        /** 叙事面:说明书 + 活动记忆选摘 + 任务记忆窗口 */
+        narrative: string;
+        enabled: EnabledSet;
+        scope: Record<string, unknown>;
+    }): Promise<AgentAction>;
+};
+/** 工具 / 人类工具 / 监听 —— 三型行动的落点 */
+export type ToolGateway = {
+    invoke(input: {
+        tool: string;
+        input: Record<string, unknown>;
+        activityId: string;
+        taskId: TaskId;
+    }): Promise<{
+        ok: boolean;
+        output?: Record<string, unknown>;
+        error?: {
+            message: string;
+        };
+    }>;
+    isWriteEffect(tool: string): Promise<boolean>;
+    registerIntent(input: {
+        taskId: TaskId;
+        tool: string;
+        input: Record<string, unknown>;
+        label: string;
+    }): Promise<void>;
+};
+export type CardGateway = {
+    issue(input: {
+        taskId: TaskId;
+        ownerId: StaffId;
+        humanCallCap: number;
+        workOrder: 'execution' | 'acceptance';
+        card: Record<string, unknown>;
+    }): Promise<{
+        id: string;
+    }>;
+};
+export type ListenerRegistrar = {
+    register(input: {
+        taskId: TaskId;
+        eventType: 'data' | 'time' | 'human';
+        keyFilter: Record<string, string>;
+        deadline: string;
+    }): Promise<{
+        id: string;
+    }>;
+};
+export type MemoryRecorder = {
+    append(input: {
+        taskId: TaskId;
+        kind: 'engine-transition' | 'evaluation' | 'thought' | 'action' | 'result' | 'observation';
+        title: string;
+        detail?: Record<string, unknown>;
+    }): Promise<void>;
+    /** 装载:按定位选摘活动记忆入 Agent 上下文(渐进披露) */
+    loadActivityMemory(activityId: string, limit: number): Promise<Array<{
+        layer: string;
+        statement: string;
+    }>>;
+};
+export type TaskContext = {
+    of(taskId: TaskId): Promise<{
+        activityId: string;
+        ownerId: StaffId;
+        humanCallCap: number;
+    }>;
+};

api-report/apps/api/src/modules/skill-engine/contract.d.ts

@@ -0,0 +1,42 @@
+/**
+ * module: skill-engine —— 对外类型(编码规范 §10.1;语义出处 AM 08)。
+ *
+ * 技能不是独立范式:没有自己的约束体系 —— 留痕、治理、权力边界与生命周期全部继承本规范。
+ * **内容软**(方法正文自由,用不用由 AI 决断),**边框硬**(装配入信封 · 脚本注册留痕 ·
+ * 不得扩权 · 版本过进化关口)。
+ */
+import type { Skill, TaskId } from '@contracts';
+import type { AssemblyContext, CrystallizedStep, SkillIndexEntry, SkillStamp, SkillViolation } from './internal/domain/skill-assembly.ts';
+export type { AssemblyContext, CrystallizedStep, Skill, SkillIndexEntry, SkillStamp, SkillViolation };
+export declare class SkillPowerEscalationError extends Error {
+    readonly violations: readonly SkillViolation[];
+    constructor(violations: readonly SkillViolation[]);
+}
+export type RunScriptInput = {
+    readonly taskId: TaskId;
+    readonly activityId: string;
+    readonly skillId: string;
+    /** 任务数据 —— 结晶片段的入参插值面 */
+    readonly scope: Readonly<Record<string, unknown>>;
+    readonly stepNo?: number;
+};
+export type ScriptOutcome = {
+    readonly ok: boolean;
+    readonly steps: ReadonlyArray<{
+        tool: string;
+        ok: boolean;
+        output?: Record<string, unknown>;
+        error?: string;
+    }>;
+    readonly stamp: readonly SkillStamp[];
+};
+export type SkillEngineService = {
+    /** 常驻上下文只有目录 —— 渐进披露 */
+    index(activityId: string): Promise<SkillIndexEntry[]>;
+    /** 按事加载正文;装配前过扩权检查 */
+    load(activityId: string, skillIds: readonly string[]): Promise<Skill[]>;
+    /** 结晶片段脚本 = 确定性动作链;经 ToolInvoker 调用而留痕,不得内联绕过 */
+    runScript(input: RunScriptInput): Promise<ScriptOutcome>;
+    /** 装配入信封 —— 供任务记忆盖戳 */
+    stamp(activityId: string, skillIds: readonly string[]): Promise<SkillStamp[]>;
+};

api-report/apps/api/src/modules/skill-engine/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * module: skill-engine —— 唯一出口。只做 re-export,不写逻辑(编码规范 §10.1)。
+ */
+export type { AssemblyContext, CrystallizedStep, RunScriptInput, ScriptOutcome, Skill, SkillEngineService, SkillIndexEntry, SkillStamp, SkillViolation, } from './contract.ts';
+export { SkillPowerEscalationError } from './contract.ts';
+export type { Clock, MemoryRecorder, ScriptToolInvoker, SkillCatalog } from './port.ts';
+export type { SkillEngineDeps } from './internal/usecase/skill-engine-service.ts';
+export { createSkillEngineService } from './internal/usecase/skill-engine-service.ts';
+export { checkCatalog, checkSkillPower, crystallizedChain, interpolate, skillIndex, stampOf, } from './internal/domain/skill-assembly.ts';

api-report/apps/api/src/modules/skill-engine/port.d.ts

@@ -0,0 +1,39 @@
+/**
+ * module: skill-engine —— 本模块要外界提供的能力(编码规范 §10.1 / §5.3)。
+ */
+import type { Skill, TaskId } from '@contracts';
+export type Clock = {
+    now(): Date;
+};
+/** 技能目录 —— app 注入 `activity-registry`(L4 同层):技能是活动的资产之一 */
+export type SkillCatalog = {
+    skillsOf(activityId: string): Promise<Skill[]>;
+    allowlistOf(activityId: string): Promise<string[]>;
+};
+/**
+ * 工具调用 —— app 注入 `toolbox`(L2)的 `ToolInvoker`。
+ * 脚本引用的工具**仍过本活动白名单与调用契约** —— 载方法不载权力。
+ */
+export type ScriptToolInvoker = {
+    invoke(input: {
+        tool: string;
+        input: Record<string, unknown>;
+        activityId: string;
+        taskId: TaskId;
+        stepNo?: number;
+    }): Promise<{
+        ok: boolean;
+        output?: Record<string, unknown>;
+        error?: {
+            message: string;
+        };
+    }>;
+};
+export type MemoryRecorder = {
+    append(input: {
+        taskId: TaskId;
+        kind: 'action' | 'result';
+        title: string;
+        detail?: Record<string, unknown>;
+    }): Promise<void>;
+};

api-report/apps/api/src/modules/task/contract.d.ts

@@ -0,0 +1,82 @@
+/**
+ * module: task —— 对外类型(编码规范 §10.1;语义出处 OS 04,AM 01/10)。
+ *
+ * 任务运行时:生命周期与**终态五名裁定**、Harness 预算执行器 / 停滞熔断、
+ * 控制三语义、改派、断点续跑。范式(loop / flow)在此汇流 —— 对流程层与交互层不可区分。
+ */
+import type { BudgetCaps, ControlSemantic, Paradigm, StaffId, TaskId, TaskRuntimeState, TerminalState } from '@contracts';
+import type { BudgetBreach, Consumption, HarnessVerdict } from './internal/domain/harness.ts';
+import type { ControlOutcome, ResumeReadiness, TaskSnapshot, TerminalCause } from './internal/domain/lifecycle.ts';
+export type { BudgetBreach, BudgetCaps, Consumption, ControlOutcome, ControlSemantic, HarnessVerdict, Paradigm, ResumeReadiness, TaskRuntimeState, TaskSnapshot, TerminalCause, TerminalState, };
+export declare class TaskNotFoundError extends Error {
+    readonly taskId: TaskId;
+    constructor(taskId: TaskId);
+}
+export declare class TaskAlreadyTerminalError extends Error {
+    readonly taskId: TaskId;
+    readonly terminal: TerminalState;
+    constructor(taskId: TaskId, terminal: TerminalState);
+}
+/** 一单任务 —— 活动的运行时实例;**恰有一名负责人** */
+export type Task = {
+    readonly id: TaskId;
+    readonly activityId: string;
+    readonly paradigm: Paradigm;
+    /** 起单来源:工作流节点;登记触发的直起单为 undefined */
+    readonly workflowId?: string;
+    readonly nodeId?: string;
+    readonly ownerId: StaffId;
+    readonly title: string;
+    readonly runtime: TaskRuntimeState;
+    readonly terminal?: TerminalState;
+    readonly reason?: string;
+    /** 装载信封:包版本 + 各资产生效版 —— 行为可归因 */
+    readonly envelope: Readonly<Record<string, unknown>>;
+    readonly caps: BudgetCaps;
+    readonly used: Consumption;
+    readonly startedAt: string;
+    readonly finishedAt?: string;
+};
+export type StartTaskInput = {
+    readonly activityId: string;
+    readonly ownerId: StaffId;
+    readonly title: string;
+    readonly workflowId?: string;
+    readonly nodeId?: string;
+    /** 输入:data(按 schema 校验,缺项不得启动)+ message(委托消息,可为空) */
+    readonly data: Record<string, unknown>;
+    readonly message?: string;
+};
+export type TickOutcome = {
+    readonly task: Task;
+    readonly verdict: HarnessVerdict;
+    readonly progressed: boolean;
+};
+export type TaskService = {
+    /** 起单:装载 → 校验输入 → 建任务记忆 → 首个回合 */
+    start(input: StartTaskInput): Promise<Task>;
+    get(taskId: TaskId): Promise<Task>;
+    listByOwner(ownerId: StaffId, openOnly?: boolean): Promise<Task[]>;
+    /** org 停用前置检查要问的「在途任务」 */
+    openTasksOf(ownerId: StaffId): Promise<Array<{
+        taskId: string;
+        title: string;
+    }>>;
+    /** 推进一拍:**预算在环外先扣先判**,再交范式引擎 */
+    tick(taskId: TaskId): Promise<TickOutcome>;
+    /** 事件驱动续跑 —— 挂起期间事件不丢,恢复即补投 */
+    deliver(taskId: TaskId, event: {
+        kind: 'data' | 'time' | 'human' | 'control';
+        ref: string;
+        payload: Record<string, unknown>;
+    }): Promise<TickOutcome>;
+    /** 控制三语义:暂停 / 叫停 / 终止 */
+    control(taskId: TaskId, semantic: ControlSemantic, by: StaffId, reason?: string): Promise<ControlOutcome>;
+    resume(taskId: TaskId, by: StaffId): Promise<Task>;
+    /** 改派:在途任务的负责人变更,**留痕并通知双方** */
+    reassign(taskId: TaskId, to: StaffId, by: StaffId): Promise<Task>;
+    /** 终态裁定 —— 完成由框架裁定,终态由系统命名 */
+    finish(taskId: TaskId, cause: TerminalCause): Promise<Task>;
+    /** 断点续跑的三份持久状态是否齐备 */
+    resumeReadiness(taskId: TaskId): Promise<ResumeReadiness>;
+};

api-report/apps/api/src/modules/task/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * module: task —— 唯一出口。只做 re-export,不写逻辑(编码规范 §10.1)。
+ */
+export type { BudgetBreach, BudgetCaps, Consumption, ControlOutcome, ControlSemantic, HarnessVerdict, Paradigm, ResumeReadiness, StartTaskInput, Task, TaskRuntimeState, TaskService, TaskSnapshot, TerminalCause, TerminalState, TickOutcome, } from './contract.ts';
+export { TaskAlreadyTerminalError, TaskNotFoundError } from './contract.ts';
+export type { ActivityLoader, Clock, IdGenerator, InteractionPhaseSetter, ListenerProbe, MemoryRecorder, ParadigmEngine, PersistenceProbe, ReassignNotifier, SchemaValidator, TaskEventPublisher, TaskStore, } from './port.ts';
+export type { TaskServiceDeps } from './internal/usecase/task-service.ts';
+export { createTaskService } from './internal/usecase/task-service.ts';
+export { budgetBreaches, durationMs, isStalled, judge, terminalOf, ZERO_CONSUMPTION, } from './internal/domain/harness.ts';
+export { applyControl, decideTerminal, isPassiveOpen, isSuccess, isTerminalControl, landingBlocked, RESUME_SOURCES, rejectionKeepsRunning, resumeReadiness, triggersFailureDisposition, } from './internal/domain/lifecycle.ts';
+export { createTaskStore } from './internal/adapter/task-store.ts';
+export { taskTable } from './internal/adapter/task-schema.ts';

api-report/apps/api/src/modules/task/port.d.ts

@@ -0,0 +1,100 @@
+/**
+ * module: task —— 本模块要外界提供的能力(编码规范 §10.1 / §5.3)。
+ */
+import type { BudgetCaps, Paradigm, StaffId, TaskId, TerminalState } from '@contracts';
+import type { Consumption } from './internal/domain/harness.ts';
+import type { Task } from './contract.ts';
+export type Clock = {
+    now(): Date;
+};
+export type IdGenerator = {
+    next(): string;
+};
+export type TaskStore = {
+    insert(task: Task): Promise<void>;
+    get(taskId: TaskId): Promise<Task | undefined>;
+    listByOwner(ownerId: StaffId, openOnly: boolean): Promise<Task[]>;
+    update(taskId: TaskId, patch: Partial<Task>): Promise<Task>;
+    addConsumption(taskId: TaskId, delta: Partial<Consumption>): Promise<Consumption>;
+    lastProgressAt(taskId: TaskId): Promise<Date | undefined>;
+    markProgress(taskId: TaskId, at: Date): Promise<void>;
+};
+/** 活动装载 —— app 注入 `activity-registry`(L4) */
+export type ActivityLoader = {
+    load(activityId: string): Promise<{
+        paradigm: Paradigm;
+        caps: BudgetCaps;
+        envelope: Record<string, unknown>;
+        /** 输入 data 的 JSON Schema —— 缺项不得启动 */
+        inputSchema: Record<string, unknown>;
+        businessModel: unknown;
+        stallAfter: string;
+    }>;
+};
+export type SchemaValidator = {
+    validate(schema: Record<string, unknown>, value: unknown): {
+        ok: boolean;
+        errors: string[];
+    };
+};
+/** 范式引擎 —— loop / flow 在此汇流;对上层不可区分(§9 双层边界) */
+export type ParadigmEngine = {
+    load(taskId: TaskId, model: unknown): Promise<void>;
+    advance(taskId: TaskId): Promise<{
+        status: 'running' | 'awaiting' | 'submitted' | 'finished' | 'blocked';
+        reason?: string;
+    }>;
+    onEvent(taskId: TaskId, event: {
+        kind: 'data' | 'time' | 'human' | 'control';
+        ref: string;
+        payload: Record<string, unknown>;
+    }): Promise<{
+        status: 'running' | 'awaiting' | 'submitted' | 'finished' | 'blocked';
+        reason?: string;
+    }>;
+};
+export type MemoryRecorder = {
+    append(input: {
+        taskId: TaskId;
+        kind: 'engine-transition' | 'terminal' | 'observation';
+        title: string;
+        detail?: Record<string, unknown>;
+    }): Promise<void>;
+    seal(taskId: TaskId): Promise<void>;
+    /** 终态封卷触发蒸馏钩子 —— 产出活动记忆候选条目 */
+    distill(input: {
+        taskId: TaskId;
+        activityId: string;
+        trigger: 'terminal';
+        prompt: string;
+    }): Promise<unknown>;
+    hasHistory(taskId: TaskId): Promise<boolean>;
+};
+/** 监听在等?—— app 注入 `event`(L1):监听中是健康态,与停滞分别对待 */
+export type ListenerProbe = {
+    hasArmedListener(taskId: TaskId): Promise<boolean>;
+};
+/** 草稿层与运行时状态是否在 —— 断点续跑的三份持久状态 */
+export type PersistenceProbe = {
+    hasDrafts(taskId: TaskId): Promise<boolean>;
+    hasRuntimeState(taskId: TaskId): Promise<boolean>;
+};
+/** 控制事件与终态事件 —— app 注入 `event`(L1) */
+export type TaskEventPublisher = {
+    publishControl(taskId: TaskId, semantic: string, by: StaffId, reason?: string): Promise<void>;
+    publishTerminal(taskId: TaskId, terminal: TerminalState, reason: string): Promise<void>;
+};
+/** 改派通知 —— app 注入 `message`(L2):改派留痕并**通知双方** */
+export type ReassignNotifier = {
+    notify(input: {
+        from: StaffId;
+        to: StaffId;
+        taskId: TaskId;
+        title: string;
+        by: StaffId;
+    }): Promise<void>;
+};
+/** 交互态 —— app 注入 `interaction`(L3):控制权按态转交 */
+export type InteractionPhaseSetter = {
+    setPhase(taskId: TaskId, phase: 'activating' | 'active' | 'awaiting-human' | 'awaiting-event' | 'transitioning' | 'terminal'): Promise<void>;
+};