BPOS-MVP/apps/api/src/modules/release/port.ts

/**
 * module: release —— 本模块要外界提供的能力(编码规范 §10.1 / §5.3)。
 */
import type { ActionIntent, StaffId, TaskId } from '@contracts';
import type { LandingOutcome } from './internal/domain/precheck.ts';

export type Clock = { now(): Date };
export type IdGenerator = { next(): string };

export type IntentStore = {
  save(intent: ActionIntent): Promise<void>;
  list(taskId: TaskId): Promise<ActionIntent[]>;
  setState(id: string, state: ActionIntent['state'], error?: string): Promise<void>;
};

/** 台账 —— app 注入 `ledger`(L1);放行写与冲突检查都在它那 */
export type LedgerGateway = {
  checkConflicts(taskId: TaskId): Promise<Array<{ field: string; key: Record<string, string | number> }>>;
  releaseWrite(taskId: TaskId): Promise<{
    mergedRows: number;
    emittedEvents: number;
    /** 合并进正式版的行 —— 输出口发射的载荷取自这里 */
    merged: ReadonlyArray<{
      domain: string;
      object: string;
      key: Record<string, unknown>;
      values: Record<string, unknown>;
    }>;
  }>;
};

/** 工具 —— app 注入 `toolbox`(L2);预检的②③④项与落地执行都经它 */
export type ToolGateway = {
  /** 工具可用(未停用)与授权有效 */
  isInvocable(tool: string, activityId: string): Promise<{ ok: boolean; reason?: string }>;
  /** 入参 schema 校验 */
  validateInput(tool: string, input: Record<string, unknown>): Promise<{ ok: boolean; errors: string[] }>;
  /** 目标预校验:工具契约含 validate 能力时调之(ADR-005) */
  validateTarget(input: {
    tool: string;
    activityId: string;
    taskId: TaskId;
    payload: Record<string, unknown>;
  }): Promise<{ ok: boolean; error?: string } | undefined>;
  /** 落地执行 —— 附幂等键 */
  execute(input: {
    tool: string;
    activityId: string;
    taskId: TaskId;
    payload: Record<string, unknown>;
    idempotencyKey: string;
  }): Promise<LandingOutcome>;
};

/** 人类工具 —— app 注入 `human-tool`(L3):发验收工单与落地失败卡 */
export type CardGateway = {
  issueAcceptance(input: {
    taskId: TaskId;
    ownerId: StaffId;
    humanCallCap: number;
    title: string;
    basis: ReadonlyArray<{ k: string; v: string }>;
    deliverable: string;
    criteria: ReadonlyArray<{ label: string; level: 'L1' | 'L2' | 'L3' | 'L4' | 'L5'; pass: boolean }>;
    actions: ReadonlyArray<{ label: string; effect: 'read' | 'write'; detail: string }>;
  }): Promise<{ id: string }>;
  issueLandingFailure(input: {
    taskId: TaskId;
    ownerId: StaffId;
    humanCallCap: number;
    failures: ReadonlyArray<{ label: string; reason: string }>;
  }): Promise<{ id: string }>;
};

/** 任务上下文 —— app 注入(活动 ID 与契约的输出口声明) */
export type TaskContext = {
  activityIdOf(taskId: TaskId): Promise<string>;
  outputPortsOf(taskId: TaskId): Promise<{ mandatory: string[]; selective: Array<{ group: string; ports: string[] }> }>;
};

/** 输出口发射 —— app 注入 `event`(L1):落地收敛**之后**才发 */
export type PortEmitter = {
  emit(input: { taskId: TaskId; port: string; payload: Record<string, unknown> }): Promise<void>;
};

export type MemoryRecorder = {
  append(input: {
    taskId: TaskId;
    kind: 'action-intent' | 'release-verdict' | 'ledger-write';
    title: string;
    detail?: Record<string, unknown>;
  }): Promise<void>;
};