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

/**
 * 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 { LandedFacts, 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<EngineOutcome>;
    onEvent(taskId: TaskId, event: {
        kind: 'data' | 'time' | 'human' | 'control';
        ref: string;
        payload: Record<string, unknown>;
    }): Promise<EngineOutcome>;
};
export type EngineOutcome = {
    readonly status: 'running' | 'awaiting' | 'submitted' | 'finished' | 'blocked';
    readonly reason?: string;
    /** 谱走完时:放行是否通过 —— **完成只出自放行通过**,引擎不自行宣布完成 */
    readonly released?: boolean;
    /** 选择组的出口选择:恰发一口,随放行一并确认 */
    readonly selectedPorts?: Record<string, string>;
};
/**
 * 落地收敛 —— app 注入 `release`(L4)。
 * 放行通过的那一刻才落地:草稿合并入正式版、动作意向执行、收敛后才发射输出口。
 */
export type LandingGateway = {
    land(input: {
        taskId: TaskId;
        ownerId: StaffId;
        humanCallCap: number;
        /** 选择组的出口选择 —— 恰发一口,由放行时的确认给定 */
        selectedPorts: Readonly<Record<string, string>>;
    }): Promise<{
        converged: boolean;
        emittedPorts: readonly string[];
        ledgerRowsMerged: number;
        /** 已落地的事实 —— 输出口载荷,随终态报给流程层 */
        facts: LandedFacts;
    }>;
};
export type MemoryRecorder = {
    append(input: {
        taskId: TaskId;
        /** control = 治理干预(叫停 / 恢复 / 改派):人对过程的裁断,归人裁决侧 */
        kind: 'engine-transition' | 'terminal' | 'observation' | 'control';
        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>;
    /** `facts` = 落地收敛的事实,作为输出口载荷随终态报给流程层;非放行终态为空 */
    publishTerminal(taskId: TaskId, terminal: TerminalState, reason: string, facts: LandedFacts): 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>;
};