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

/**
 * 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;
        text?: string;
        error?: string;
    }>;
};
/** 出参校验 —— app 注入 ajv:LLM 步的出参**必过声明的 schema**(AM 12.3) */
export type SchemaValidator = {
    validate(schema: Record<string, unknown>, value: unknown): {
        ok: boolean;
        errors: string[];
    };
};
/**
 * 视图流控 —— app 注入 `interaction`(L3)。
 * flow 按步序位置推声明的模版;推的是**填好数的 HTML**,容器只渲染不执行。
 */
export type ViewGateway = {
    /** 按模版名取模版、以任务视图填数、推给前端;模版不存在就什么都不做 */
    push(input: {
        taskId: TaskId;
        activityId: string;
        template: string;
        scope: Record<string, unknown>;
    }): Promise<void>;
};
/** 人类工具步 —— 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;
    }>;
};