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

/**
 * 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 LandedFacts = {
    readonly flat: Record<string, unknown>;
    readonly rows: ReadonlyArray<{
        key: Record<string, unknown>;
        values: Record<string, unknown>;
    }>;
};
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>>;
    /** 起单入参:契约的 data —— 引擎求值的作用域底料 */
    readonly data: 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>;
    /** 终态裁定 —— 完成由框架裁定,终态由系统命名 */
    /** `facts` = 落地收敛的事实(仅放行路径有);作为输出口载荷上报流程层 */
    finish(taskId: TaskId, cause: TerminalCause, facts?: LandedFacts): Promise<Task>;
    /** 断点续跑的三份持久状态是否齐备 */
    resumeReadiness(taskId: TaskId): Promise<ResumeReadiness>;
};