/**
 * module: flow-engine —— 对外类型(编码规范 §10.1;语义出处 AM 05)。
 *
 * flow 范式:步序声明运行器(四种步型、重试与兜底、事件即步条件)。
 * **零临场调度** —— 运行中不得由 LLM 决定步序、跳步或兜底。
 */
import type { FlowModel, FlowStep, TaskId } from '@contracts';
import type { FailureAction, FlowIssue, FlowPosition, NextAction, StepRuntime, StepState } from './internal/domain/step-sequence.ts';

export type { FailureAction, FlowIssue, FlowModel, FlowPosition, FlowStep, NextAction, StepRuntime, StepState };

export class FlowDeclarationInvalidError extends Error {
  constructor(readonly issues: readonly FlowIssue[]) {
    super(`步序声明不完整,不得上架:${issues.map((i) => `${i.step}:${i.message}`).join('; ')}`);
    this.name = 'FlowDeclarationInvalidError';
  }
}

/** 一次推进的结果 —— 由 task 驱动,不自转 */
export type AdvanceOutcome = {
  readonly position: FlowPosition;
  readonly status: 'running' | 'awaiting' | 'finished' | 'blocked';
  /** awaiting 时:在等什么 */
  readonly waitingFor?: { readonly kind: 'human' | 'event' | 'time'; readonly ref: string; readonly deadline: string };
  /** finished 时:末步验收工单的裁决决定终态 */
  readonly released?: boolean;
  /** 选择组的出口选择:恰发一口,随放行一并确认 */
  readonly selectedPorts?: Record<string, string>;
  readonly blockedReason?: string;
};

export type FlowEngineService = {
  /** 装载步序声明并校验 —— 谱必须全程可静态检查 */
  load(taskId: TaskId, model: FlowModel): Promise<FlowPosition>;
  position(taskId: TaskId): Promise<FlowPosition | undefined>;
  /** 推进一步(或若干确定步);异步步进入 awaiting 并登记监听 */
  advance(taskId: TaskId): Promise<AdvanceOutcome>;
  /** 事件即步的完成条件:人事件 / 数据事件 / 时间事件到达即续跑 */
  resume(taskId: TaskId, event: { kind: 'human' | 'data' | 'time'; ref: string; payload: Record<string, unknown> }): Promise<AdvanceOutcome>;
};