JX-BPOS/apps/api/src/modules/flow-engine/port.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 }>;
};