/**
 * module: process —— 对外类型(编码规范 §10.1;语义出处 OS 03)。
 *
 * 流程层:流程包定义与版本、**边映射闭合校验**、工作流实例
 * (网关 / 审批点 / 失败走向 / 负责人四策略 / 聚合)。
 *
 * M5 进行中:domain 已落(闭合校验 / 四策略解析 / 状态聚合),
 * 用例与 Mastra 工作流编译随后(编码规范 §6.1)。
 */
import type {
  ClosureReport,
  ClosureViolation,
  OwnerSpec,
  ProcessNode,
  ProcessPackage,
  TerminalState,
  WorkflowState,
} from '@contracts';
import type { ActivityContractFace, ClosureInput } from './internal/domain/closure.ts';
import type { Candidate, NodeInstance, ResolveContext, Resolution } from './internal/domain/owner-resolution.ts';
import type { AssembleScope, Dispatch, RejectRoute } from './internal/domain/routing.ts';
import type { WorkflowRecord } from './port.ts';

export type {
  ActivityContractFace,
  AssembleScope,
  Candidate,
  ClosureInput,
  Dispatch,
  RejectRoute,
  WorkflowRecord,
  ClosureReport,
  ClosureViolation,
  NodeInstance,
  OwnerSpec,
  ProcessPackage,
  ProcessNode,
  ResolveContext,
  Resolution,
  TerminalState,
  WorkflowState,
};

/** 起单入参 —— 触发器与上游系统一律经**调用接口**调起(OS 03) */
export type StartWorkflowInput = {
  readonly packageId: string;
  readonly packageVersion?: number;
  readonly subject: string;
  /** 凡单必有来源:触发器即来源;纪要登记起单的,登记人即来源 */
  readonly source: { kind: 'periodic' | 'event' | 'registration'; ref: string; by?: string };
  readonly data: Record<string, unknown>;
};

export type ProcessService = {
  /**
   * 保存 —— **严格检查 + 即刻生效**,不闭合抛 `NotClosedError`。
   * 恒产生新版本号(服务端算,不采信入参的 version);返回实际落的那一版。
   * 落下来的新版**即为生效版**:同流的旧生效版随之停用(一条流恰一个生效版本)。
   */
  savePackage(pkg: ProcessPackage): Promise<ProcessPackage>;
  listPackages(): Promise<ProcessPackage[]>;
  getPackage(id: string, version?: number): Promise<ProcessPackage | undefined>;
  /**
   * 版本启停 —— 运行时开关,**不改定义一个字**。
   * 激活某版:同流其余版本一并停用(恰一个生效);停用生效版:整条流下线,新起单被拒。
   * 在途工作流按启动时钉住的版本跑完,启停对它们零影响。
   */
  setPackageState(id: string, version: number, state: 'active' | 'retired'): Promise<ProcessPackage[]>;
  /** 画图即校验 —— 与前端画布同源;只算不存 */
  validate(pkg: ProcessPackage): Promise<ClosureReport>;

  start(input: StartWorkflowInput): Promise<WorkflowRecord>;
  getWorkflow(id: string): Promise<WorkflowRecord>;
  listWorkflows(limit?: number): Promise<WorkflowRecord[]>;
  instancesOf(workflowId: string): Promise<NodeInstance[]>;

  /** 任务终态到达:完成即继续流转;非完成即走声明的失败走向 */
  onTaskTerminal(
    taskId: string,
    terminal: TerminalState,
    ports: Record<string, Record<string, unknown>>,
  ): Promise<WorkflowState | undefined>;
  applyFailure(
    workflowId: string,
    nodeId: string,
    instance: number,
    node: Extract<ProcessNode, { kind: 'activity' }>,
    terminal: TerminalState,
  ): Promise<WorkflowState>;
  /** 审批裁决:通过继续;驳回按声明走向回指定节点**重开新实例** */
  onApprovalVerdict(
    workflowId: string,
    nodeId: string,
    verdict: 'pass' | 'reject',
    payload: Record<string, unknown>,
  ): Promise<WorkflowState>;
  /** 状态是聚合投影 —— 每次变动后重算 */
  refreshState(workflowId: string): Promise<WorkflowState>;
  terminate(workflowId: string, reason: string): Promise<WorkflowState>;
};

/** 起单入参不合调用接口契约 —— 在建工作流之前判掉,不留半条在途单 */
export class CallInterfaceViolationError extends Error {
  constructor(
    readonly packageId: string,
    readonly errors: readonly string[],
  ) {
    super(`输入不合调用接口契约,不得起单:${errors.join('; ')}`);
    this.name = 'CallInterfaceViolationError';
  }
}

/** 不闭合不得**保存** —— 没有发布这道门,闸就落在保存上 */
export class NotClosedError extends Error {
  constructor(readonly report: ClosureReport) {
    super(`流程包不闭合,不得保存:${report.violations.map((v) => v.message).join('; ')}`);
    this.name = 'NotClosedError';
  }
}

export class PositionVacantError extends Error {
  constructor(readonly position: string) {
    super(`岗位空缺,无法解析负责人:${position} —— 按节点失败走向处置,或转治理台待指派`);
    this.name = 'PositionVacantError';
  }
}