/**
 * module: trace —— **全链留痕的观测面**(设计台「每个活动完全 Trace 监控」)。
 *
 * 一条工作流 = 一条 trace;节点实例 = 一个 span;活动内的每一步、每次工具调用、
 * 每次模型调用、每张人卡 = 子 span。span 由 **Mastra Observability 组件**产出
 * (我们的执行不经 Mastra 图,所以是**手动打点**),再由自定义 exporter 落库。
 *
 * 与任务记忆的分工:任务记忆是**人读的留痕**(谁在何时做了什么、依据什么),
 * 一件事一行;trace 是**机器读的时间轴**(嵌套、耗时、入出参、错误),
 * 一次调用一个 span。两者并行,不互相替代。
 */
export type SpanKind = 'workflow' | 'node' | 'step' | 'tool' | 'model' | 'human';

export type TraceSpan = {
  readonly id: string;
  readonly traceId: string;
  readonly parentId?: string;
  readonly name: string;
  readonly kind: SpanKind;
  readonly workflowId?: string;
  readonly nodeId?: string;
  readonly taskId?: string;
  readonly input?: Record<string, unknown>;
  readonly output?: Record<string, unknown>;
  readonly error?: { message: string };
  readonly attributes?: Record<string, unknown>;
  readonly startedAt: string;
  readonly endedAt?: string;
};

/** 一次可观测的执行:开一个 span,干活,收尾 —— 收尾必做,不然时间轴上永远挂着 */
export type SpanHandle = {
  readonly id: string;
  readonly traceId: string;
  child(input: {
    name: string;
    kind: SpanKind;
    nodeId?: string;
    taskId?: string;
    input?: Record<string, unknown>;
    attributes?: Record<string, unknown>;
  }): SpanHandle;
  end(out?: { output?: Record<string, unknown>; attributes?: Record<string, unknown> }): Promise<void>;
  fail(error: unknown): Promise<void>;
};

export type TraceService = {
  /*
   * 作用域索引 —— 调用方只报 id,父子关系由服务自己拼。
   * 打点散在装配层的十几处,让每处自己拎 handle 传来传去,一处漏传整棵树就断了。
   */
  /** 开一条工作流的 trace(root span) */
  beginWorkflow(input: { workflowId: string; subject: string; input?: Record<string, unknown> }): void;
  /** 开一个节点 span(自动挂在工作流 span 下) */
  beginNode(input: {
    workflowId: string;
    nodeId: string;
    label: string;
    taskId?: string;
    approvalId?: string;
    assigneeId?: string;
    input?: Record<string, unknown>;
  }): void;
  /** 活动内的一次动作:步骤 / 工具 / 模型 / 人卡 —— 自动挂在该任务的节点 span 下 */
  beginAction(input: {
    taskId: string;
    name: string;
    kind: SpanKind;
    input?: Record<string, unknown>;
  }): SpanHandle | undefined;
  /** 收尾:节点终态 / 工作流终态 */
  endNode(input: { taskId?: string; workflowId?: string; nodeId?: string; output?: Record<string, unknown> }): Promise<void>;
  endWorkflow(input: { workflowId: string; state: string }): Promise<void>;

  /** 起一条 trace(工作流级)或挂在既有 trace 下 —— 低层口,便利层用它 */
  start(input: {
    name: string;
    kind: SpanKind;
    workflowId?: string;
    nodeId?: string;
    taskId?: string;
    parent?: { traceId: string; spanId: string };
    input?: Record<string, unknown>;
    attributes?: Record<string, unknown>;
  }): SpanHandle;
  /** 这条工作流的完整 span 树(按开始时间序;树形由 parentId 拼) */
  ofWorkflow(workflowId: string): Promise<TraceSpan[]>;
  /** 这个任务(活动实例)的 span —— 活动内每一步都在这儿 */
  ofTask(taskId: string): Promise<TraceSpan[]>;
  flush(): Promise<void>;
};