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

/**
 * module: task —— 本模块要外界提供的能力(编码规范 §10.1 / §5.3)。
 */
import type { BudgetCaps, 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<{
    caps: BudgetCaps;
    envelope: Record<string, unknown>;
    /** 输入 data 的 JSON Schema —— 缺项不得启动 */
    inputSchema: Record<string, unknown>;
    /**
     * 这一单是被一封信叫起来的 —— 活动清单声明的**来件字段映射**。
     * 声明了,起单那一刻就把来件归进沟通记录(工作台那一屏)。
     */
    inboundComm?: {
      channel: string;
      partyField: string;
      subjectField?: string | undefined;
      bodyField?: string | undefined;
      attachmentsField?: string | undefined;
    };
    businessModel: unknown;
    stallAfter: string;
  }>;
};

/** 沟通记录 —— 一单往来的原件存档(工作台「沟通记录」那一屏读它) */
export type CommRecorder = {
  record(input: {
    taskId: TaskId;
    direction: 'in' | 'out';
    channel: string;
    party: string;
    subject: string;
    body: string;
    attachments: readonly unknown[];
    note: string;
  }): Promise<void>;
};

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 = 治理干预(叫停 / 恢复 / 改派):人对过程的裁断,归人裁决侧。
     * trigger = 触发事件:这一单被什么叫起来的 —— 不是机器产出,也不是谁的动作。
     */
    kind: 'engine-transition' | 'terminal' | 'observation' | 'control' | 'trigger';
    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):控制权按态转交 */
/**
 * 受理补全台(2026-07-30 宽进):把缺的必填字段做成补全卡发到负责人的任务对话流,
 * 并武装 human 监听等答复 —— app 注入 human-tool + event。
 */
export type IntakeDesk = {
  askCompletion(input: {
    taskId: string;
    ownerId: string;
    title: string;
    fields: ReadonlyArray<{ key: string; label: string }>;
  }): Promise<void>;
};

export type InteractionPhaseSetter = {
  setPhase(taskId: TaskId, phase: 'activating' | 'active' | 'awaiting-human' | 'awaiting-event' | 'transitioning' | 'terminal'): Promise<void>;
};