export type NodeType =
  | 'input' | 'output' | 'llm' | 'agent' | 'supervisor' | 'tool' | 'code' | 'merge'
  | 'branch' | 'loop' | 'subgraph' | 'memory' | 'retrieve' | 'transform'
  | 'human' | 'validate' | 'metrics' | 'analysis' | 'report' | 'dual_check' | 'challenge'

export interface GraphNode {
  id: string
  type: NodeType
  position: { x: number; y: number }
  data: { label?: string; description?: string; config: Record<string, any> }
}

export interface GraphEdge {
  id?: string
  source: string
  target: string
  sourceHandle?: string | null
  targetHandle?: string | null
  label?: string
}

export interface GraphSpec {
  nodes: GraphNode[]
  edges: GraphEdge[]
  viewport?: Record<string, any>
  defaults?: Record<string, any>
}

export interface Workflow {
  id: string
  name: string
  description: string
  graph: GraphSpec
  tags: string[]
  version: number
  is_template: boolean
  status?: 'draft' | 'published' | 'governed'
  published_version?: number | null
  /** 当前发布版本的级别。画布上改过之后 status 回到 draft，「这是不是受管工作流」看这一项（老服务端不给） */
  published_level?: 'published' | 'governed' | null
  /** 画布这一版的图和当前发布版内容相同（服务端按图哈希比）：撤回改动后保存出来的新版本不算「领先」（老服务端不给） */
  same_as_published?: boolean
  /** 最近一次发布的署名。发布时没有署名为 null */
  published_by?: string | null
  run_count?: number
  created_at?: string
  updated_at?: string
}

/** 工作流的一个版本。列表接口只有前四项，取单个版本时才有 graph 等 */
export interface WorkflowVersion {
  id: string
  version: number
  note: string
  created_at?: string
  workflow_id?: string
  graph?: GraphSpec
  graph_hash?: string | null
  /** 这一版入口节点声明的字段。正式运行的表单照它填，不能照画布 */
  input_fields?: { name: string; required?: boolean; [key: string]: any }[]
  /** 是不是当前的已发布版本 */
  published?: boolean
  /** 发布时记下的数据目录版本，没记过为 null */
  catalog_versions?: CatalogVersions | null
  /** 发布之后目录有变化的表 */
  catalog_changes?: CatalogDriftTable[]
  /** 发布时记下的表结构版本 {源名: {表名: 结构版本}}（只记写死的 SQL 直接引用的表）；记录之前发布的为 null */
  schema_versions?: Record<string, Record<string, number>> | null
  /** 发布之后结构版本变了的表 */
  schema_changes?: SchemaDriftTable[]
}

/**
 * 发布时记下的数据目录版本（服务端 catalog_impact.recorded_versions），两组都是 {源名: {表名: 版本}}：
 * - direct：SQL 里写着的表，0 表示当时还没有目录
 * - possible：Agent 绑定了查询工具的数据源中所有有目录的表（SQL 运行时才生成）；源下为空表示当时一张有目录的
 *   表都没有。只记了直接引用的老版本这一组为空
 */
export interface CatalogVersions {
  direct: Record<string, Record<string, number>>
  possible: Record<string, Record<string, number>>
}

/** 发布之后数据目录有变化的一张表（服务端 catalog_impact.catalog_drift；运行里的 catalog.drift 事件同形） */
export interface CatalogDriftTable {
  source: string
  source_id: string
  table: string
  /** 表现在的中文名 */
  label: string | null
  /** 发布时的版本，0 表示当时还没有目录 */
  published: number | null
  current: number
  /** direct：SQL 里写着这张表；possible：Agent 可能查询的表。老事件没有这一项，按 direct */
  impact: 'direct' | 'possible'
}

/**
 * 发布之后表结构变了的一张表（服务端 catalog_impact.schema_drift；运行里的 schema.drift 事件同形）。和目录有变化
 * （CatalogDriftTable）分开记：这里的版本是表结构版本，不是目录版本
 */
export interface SchemaDriftTable {
  source: string
  source_id: string
  table: string
  /** 表现在的中文名 */
  label: string | null
  /** 发布时的结构版本 */
  published: number
  /** 现在的结构版本；表已删除时为 null */
  current: number | null
  removed: boolean
  /** 发布之后测到、还没处理的结构变化（最多 5 条，more 是另外还有几条） */
  changes: { id: string; kind: string; column: string | null; severity: 'info' | 'warning' | 'action'; summary: string }[]
  more: number
}

/**
 * 后端写进 runs.status 的值。interrupted 既可能是停在审批上，也可能是服务重启
 * 打断后挂起——显示时用 lib/status 的 resolveStatus 配合审批列表区分。
 * suspended 目前后端不写，前端推导的 RunPhase 会用到，这里一并收下。
 */
export type RunStatus =
  | 'queued' | 'running' | 'interrupted' | 'succeeded' | 'failed' | 'cancelled' | 'suspended'

/**
 * 运行的用量与时长。
 *
 * 三种时长口径不同，不能混用：duration_ms / active_ms 是各段执行时长之和（审批
 * 恢复、续跑的每一段都算），wall_ms 是从第一次开始到结束的墙钟，wait_ms 是等人
 * 审批的总时长。老数据只有 duration_ms，而且可能只是最后一段。
 */
export interface RunUsage {
  duration_ms?: number
  wall_ms?: number
  active_ms?: number
  wait_ms?: number
  input_tokens?: number
  output_tokens?: number
  cost_usd?: number
  /** 金额估不出来的调用次数（模型不在价格目录中），cost_usd 只是估得出的那部分。没有这种调用时不给 */
  unpriced_calls?: number
  [key: string]: any
}

export interface Run {
  id: string
  workflow_id: string | null
  workflow_name: string
  status: RunStatus
  input: Record<string, any>
  output: Record<string, any>
  error: string | null
  usage: RunUsage
  run_class?: 'formal' | 'exploratory'
  version?: number | null
  version_hash?: string | null
  manifest_hash?: string | null
  /** 封存到第几条事件为止。有它才说明这条运行的清单封存过 */
  manifest_seq?: number | null
  /** 失败时能定位到的节点 */
  error_node_id?: string | null
  started_by?: string | null
  /** 发起时实际生效的记忆域和知识库（没指定时取设置里的默认值）。老后端不给 */
  memory_scope?: string | null
  collection?: string | null
  created_at?: string
  started_at?: string
  finished_at?: string | null
}

export interface RunEvent {
  seq: number
  type: string
  node_id: string | null
  ts: number
  data: Record<string, any>
  replay?: boolean
}

export interface Approval {
  id: string
  run_id: string
  node_id: string
  mode: 'approve' | 'input' | 'edit'
  title: string
  /**
   * 工具审批的 payload 是 {kind: 'tool_approval', tool, args, title}。探索运行里 MCP /
   * 自定义工具的审批另带 trust_key（同 ToolInfo.trust_key）：有它，审批卡才给「始终允许」
   */
  payload: Record<string, any>
  status: string
  response: Record<string, any>
  created_at?: string
  // 以下是审批卡的上下文，老后端不给
  workflow_id?: string | null
  workflow_name?: string | null
  node_label?: string | null
  run_status?: RunStatus | null
  run_class?: 'formal' | 'exploratory' | null
  /** 谁处理的。null 表示处理时没有署名，显示「未署名」 */
  resolved_by?: string | null
  resolved_at?: string | null
  /**
   * 这条审批对应的待办（一次中断对应一条 Approval 和一条 Task，应用平台 D-r）。有它审批卡直接按 id 取待办，
   * 不必再按运行取一遍待办列表去对；老服务端不给
   */
  task_id?: string | null
}

/**
 * 人工审批审的报告的核对概况（human 节点请求里的 payload.reports，服务端 nodes/human._reviewed_reports）：
 * 上游直接连着的、或者标题和说明里引用了正文的报告撰写节点，各一项。stats 同 report.checked，judge 是裁判摘要
 * 的几项（mode：inline 节点里当场判的——交给审批的报告探索运行也当场判 / on_demand 按需判，老服务端的探索运行）。
 * 老后端、审的不是报告时没有
 */
export interface ApprovalReport {
  node_id: string
  label?: string
  stats?: EvidenceStats
  /** 结论句策略：off / require_citation / judge */
  claims?: string
  doc_artifact?: string
  judge?: { mode?: string; counts?: Record<string, unknown>; complete?: boolean; unjudged?: unknown; limits_hit?: unknown }
}

/**
 * 后端记着的最近一次测连接（模型接入、数据源、MCP 的列表接口都平铺这四项）。
 * 没测过、或者连接配置改过之后全是 null。用 lib/health 的 healthFromServer 转成
 * HealthRecord 给 HealthPill
 */
export interface ServerHealth {
  last_checked_at?: string | null
  last_check_ok?: boolean | null
  last_latency_ms?: number | null
  last_error?: string | null
}

export interface Provider extends ServerHealth {
  id: string
  name: string
  kind: string
  base_url: string | null
  default_model: string | null
  models: { id: string; label?: string; context?: number; pricing?: any }[]
  enabled: boolean
  extra: Record<string, any>
  api_key_masked: string
  has_key: boolean
}

/**
 * MCP / 自定义工具在探索运行里的信任档（节点审批策略为「仅危险工具」时才看它）：
 * ask 每次等人批（默认）；gated 每次先问门控模型，它判可疑的仍交给人；always 直接执行。
 * 正式运行不看它，一律按 ask
 */
export type ToolTrust = 'ask' | 'gated' | 'always'

export interface ToolInfo {
  id: string
  name: string
  description: string
  category: string
  source: 'builtin' | 'custom' | 'mcp'
  dangerous: boolean
  /**
   * 运行时可能停下来等审批。MCP / 自定义工具：ask、gated 为 true，always 为 false；
   * 更老的后端一律给 false（那时审批关卡认不出它们）
   */
  runtime_approval?: boolean
  /** 只有 MCP / 自定义工具有，老后端不给：没有它就不显示信任档控件 */
  trust?: ToolTrust
  /** 改信任档时用的键（PUT /api/tools/trust），等于 id */
  trust_key?: string
  schema: Record<string, any>
  /**
   * 只有自定义工具有：库里存着的参数定义哪里写坏了（一句中文）。绑了它的节点运行时
   * 一定失败，列表上要醒目地标出来。null / 缺省表示没问题
   */
  problem?: string | null
  /**
   * 在工具库里执行只演练、不发送：写外部系统的能力（被治理为写入，或绑定端点、视参数而定），和执行接口同一个判断。
   * 详情区的提示条照它说「这里只演练」，不说「请求会实际发出」（老服务端不给）
   */
  write_rehearsal?: boolean
}

/**
 * 数据源（GET /api/datasources 的一行）。tools 是它给模型的两个工具名
 * db_query__<name> / db_schema__<name>——/api/tools 里没有它们，挑工具要从这里取
 */
export interface DataSource extends ServerHealth {
  id: string
  /** 标识，进了工具名，建好不能改 */
  name: string
  kind: string
  host: string | null
  port: number | null
  database: string | null
  username: string | null
  options: Record<string, any>
  readonly: boolean
  description: string
  enabled: boolean
  password_masked?: string
  has_password?: boolean
  table_count?: number
  schema_synced_at?: string | null
  /** 上次探查为什么没拿到表；空串 = 没出错（或还没探查） */
  schema_error?: string
  available_schemas?: string[]
  tools?: string[]
  /** 缓存按哪个 schema 探的：'' 默认 schema，null 没有缓存 */
  cached_schema?: string | null
  /**
   * upload：上传的表格（连接信息由系统维护，不能手改、不能重新探查，更新数据靠同名重新上传）；
   * manual：手工登记的连接。卡片按它分到「表格」「数据库」两个标签，不再按库文件路径猜
   */
  origin?: 'upload' | 'manual' | (string & {})
  /** 上传表格当前启用的版本。手工登记的源恒为 null */
  current_snapshot?: CurrentSnapshot | null
  /** simple 简单导入；recipe 按配方导入；手工登记的源为 null。老后端没有这个字段 */
  import_mode?: 'simple' | 'recipe' | null
  /** 按配方导入的源当前启用的配方 */
  current_recipe?: { id: string; seq: number; origin: string; activated_at: string | null; signed_by: string | null } | null
  /** 这个源最近一个未结束的导入（按配方导入的暂存区） */
  open_staging?: { id: string; kind: ImportStagingKind; status: ImportStagingStatus; created_at: string } | null
}

/** 上传表格当前启用的版本（DataSource.current_snapshot） */
export interface CurrentSnapshot {
  id: string
  /**
   * 这一版导入（发布）的时间。迁移补建的初始版本（raw_state 为 absent、没有文件名）例外：
   * 这里是迁移那一刻（升级后服务启动的时间），不是导入时间
   */
  created_at: string | null
  /** 上传时的文件名。迁移前上传的老版本没有记录，是空串 */
  file_name: string
  /** 原件：kept 保存在服务端；purged 已清除；absent 没有保存（迁移前上传的老版本） */
  raw_state: 'kept' | 'purged' | 'absent' | (string & {})
  /** 期 3：导入模式。简单导入、期 3 之前的版本没有或为 null（按每期替换理解） */
  mode?: 'replace' | 'accumulate' | (string & {}) | null
  /** 期 3：当前版本含几期（按期累积时可以多于 1） */
  periods?: number
  /** 期 3：各期统计期的最早起点、最晚终点；没有统计期为 null */
  period_start?: string | null
  period_end?: string | null
  /** 期 3：最近一次成为当前版本的时刻（回滚之后卡片写「…启用」，不再写当初的导入时间） */
  activated_at?: string | null
}

/**
 * 上传表格时解析器要用户先拍板的事（POST /api/datasources/upload 回 422，body 是
 * {detail, decision}）。mixed：数字列混入非数字；shape：交叉表、多块结构
 */
export type UploadDecision =
  | { kind: 'mixed'; details: { columns: UploadMixedColumn[] } }
  | {
    kind: 'shape'
    details: {
      reasons: UploadShapeReason[]
      /** 预告：选了按原样导入之后还会问的混合列（没有就是 undefined） */
      mixed?: UploadMixedColumn[]
      /** 预告是不是看完了整张表；为假时之后的混合列可能比这里多 */
      mixed_complete?: boolean
    }
  }

/** 一列以数字为主、混有非数字的值。values 是非数字的取值和个数（最多五种） */
export interface UploadMixedColumn {
  sheet: string
  table: string
  /** SQL 列名 */
  column: string
  /** 原表头 */
  header: string
  numeric: number
  nonnumeric: number
  values: { value: string; count: number }[]
}

/** 这张表不是一行一条记录的一条理由。cells 是 A1 坐标或区域，message 是给人看的一句话（已含坐标） */
export interface UploadShapeReason {
  sheet: string
  /** date_header / date_row / section_title / table_totals / formula_above */
  kind: string
  cells: string[]
  message: string
}

/** 导入回执里的一张表 */
export interface UploadedTable {
  name: string
  /** 原工作表名（CSV 是文件名） */
  sheet: string
  rows: number
  /** name 是 SQL 列名，header 是原表头（表头格为空时是空串） */
  columns: { name: string; type: string; header?: string | null }[]
  /** 导入区域（A1，表头行到最后一行数据） */
  region?: string | null
  /** 按原样导入、未经规整 */
  unshaped?: boolean
  blank_rows_skipped?: number
  /** 去掉的左右两侧整列为空的列（列字母） */
  columns_trimmed?: string[]
}

/** 导入时做过的类型转换：kind 是 thousands_separator / nonnumeric_to_null / kept_as_text */
export interface UploadConversion {
  table: string
  column: string
  kind: string
  count: number
  examples: unknown[]
}

/** POST /api/datasources/upload 成功时的回执 */
export interface UploadResult {
  source: DataSource
  /** 同名就地更新（新版本替换了旧版本），不是新建 */
  replaced: boolean
  import_id?: string
  snapshot_id?: string
  /** 同一份文件、同样的选项以前导入过，沿用了那次的库 */
  build_reused?: boolean
  /** 期 3：服务端的同版本数据文件曾被改动，已用本次上传的文件恢复（P3-SPEC 第 8 节遗留项 1） */
  build_restored?: boolean
  /** reason：hidden 隐藏工作表不导入；empty 没有内容。state：visible / hidden / veryHidden */
  skipped_sheets?: { sheet: string; state: string; reason: string }[]
  conversions?: UploadConversion[]
  warnings?: string[]
  tables: UploadedTable[]
}

// ---------------------------------------------------------------------------
// 按配方导入（期 2：/api/datasources/imports/*、/{id}/reupload|redraft|recipe）
// 字段与后端 recipe_types.py 的 dataclass 同名；后端多出来的字段界面不认也不报错
// ---------------------------------------------------------------------------

/** first 首次导入；reupload 上传新一期；redraft 修改配方（不换文件）；switch 从简单导入切换 */
export type ImportStagingKind = 'first' | 'reupload' | 'redraft' | 'switch' | (string & {})
export type ImportStagingStatus = 'drafting' | 'trialed' | 'rejected' | 'committed' | 'discarded' | 'expired' | (string & {})

/**
 * 配方 JSON（agentlab-recipe/2）。结构由服务端的静态校验把关，界面只按已知字段读写，所以这里是宽松类型：
 * 表单改哪个字段就按路径写哪个字段，整份经 PUT recipe 交给服务端
 */
export type Recipe = Record<string, any>

/** 配方静态校验的问题：path 是 JSON Pointer（如 /tables/0/units/客流），message 是整句人话 */
export interface RecipeProblem {
  path: string
  code: string
  message: string
  /** 期 3：这条问题对应的修复提议 id（Staging.fixes 里的 FixProposal.id）；没有提议为 [] 或缺省 */
  fix_ids?: string[]
}

/** structure 结构问题；data_quality 数据质量；confirm 需确认；input 需要录入；recipe 配方不合法 */
export type ImportProblemCategory = 'structure' | 'data_quality' | 'confirm' | 'input' | 'recipe' | (string & {})

/** 干跑、试运行的问题（契约 Problem）。cells 是「工作表!A1」或「工作表!A1:B2」，最多 20 个 */
export interface ImportProblem {
  code: string
  category: ImportProblemCategory
  message: string
  cells?: string[]
  /** 修复按钮的种类（FixKind）；界面不靠它放按钮，只按 fix_ids 放（P3-SPEC 3.1） */
  fix?: string | null
  /** 期 3：构造修复补丁的参数（只含原文和坐标），界面不直接用：补丁由服务端算 */
  fix_args?: Record<string, any> | null
  /** 期 3：这条问题对应的修复提议 id（Staging.fixes 里的 FixProposal.id）；没有提议为 [] 或缺省 */
  fix_ids?: string[]
}

export type CheckStatus = 'passed' | 'mismatch' | 'unverifiable' | 'info' | (string & {})

/** 一条核对的结果（契约 CheckResult）。acceptable：可以写理由接受 */
export interface CheckResult {
  id: string
  kind: string
  title: string
  status: CheckStatus
  category: 'structure' | 'data_quality' | 'info' | (string & {})
  checked?: number
  failed?: number
  unverifiable?: number
  sql?: string | null
  params?: unknown[]
  details?: string[]
  cells?: string[]
  acceptable?: boolean
  reasons?: Record<string, number>
}

/**
 * 确认项的来源（契约 ConfirmItem.source），确认清单按它分组（P3-SPEC 9.5）：recipe 配方；edit 修改（fix:*、select:*、
 * redraft_adopted）；accumulate 累积；outside / sheet / context 本期；diff 差异；switch 切换
 */
export type ConfirmSource = 'recipe' | 'diff' | 'outside' | 'sheet' | 'context' | 'switch' | 'edit' | 'accumulate' | (string & {})

/** 启用前要逐条勾选的一项（契约 ConfirmItem；id 的取值见 P2-SPEC 7.5、P3-SPEC 9.5） */
export interface ConfirmItem {
  id: string
  label: string
  detail?: string
  required?: boolean
  /** 缺省按 recipe */
  source?: ConfirmSource
}

/** 上传新一期与上一期相比的一条差异（契约 DiffItem） */
export interface DiffItem {
  kind: string
  label: string
  detail?: string
  requires_confirm?: boolean
  confirm_id?: string | null
}

/** 建议卡片：一条建议加一句理由，指向网格上的格子 */
export interface Card {
  id: string
  title: string
  reason: string
  cells?: string[]
  /** 对应的待确认问题（Question.id） */
  question?: string | null
}

export interface QuestionOption {
  value: string
  label: string
  /** 选它时必须写理由（如「不登记」） */
  needs_reason?: boolean
}

/** 待确认问题：只有封闭的选项；选项对配方的修改由服务端应用，界面只发选了哪一项 */
export interface Question {
  id: string
  text: string
  options: QuestionOption[]
  default?: string | null
}

/** 已选的回答（StagingOut.answers 的值） */
export interface QuestionAnswer {
  value: string
  reason?: string | null
}

/** 规则或 AI 起草的结果（契约 Draft，不含给模型看的那份原因） */
export interface Draft {
  recipe: Recipe | null
  complete: boolean
  origin: 'rules' | 'ai' | (string & {})
  cards?: Card[]
  questions?: Question[]
  failures?: string[]
}

/** 一次模型调用的用量 */
export interface AiUsage {
  model: string
  input_tokens: number
  output_tokens: number
  cost_usd: number
  ok: boolean
  at: string
  attempt?: number
}

/** 一张可见工作表的原始网格预览 */
export interface GridPreview {
  sheet: string
  bounds: string | null
  total_rows?: number
  total_cols?: number
  /** 预览只取了前面的部分 */
  truncated?: boolean
  rows?: number[]
  cols?: number[]
  /** [行, 列, 显示文字, 种类]；种类：text / number / date / bool / error / formula / formula_uncached */
  cells: [number, number, string, string][]
  /** A1 → 公式原文 */
  formulas?: Record<string, string>
  merges?: string[]
  hidden_rows?: number[]
  hidden_cols?: number[]
}

/** 格子的去向（契约 Role），按区域给出。期 3 新增角色 ignored（按配方忽略） */
export interface RegionMark {
  sheet: string
  role: string
  ref: string
  /** 期 3：所在块的 id（区域外文字、统计期为 null）：网格按块描边、框选的重放比对按它过滤 */
  block?: string | null
}

/** 格子账：每张工作表的非空格和各去向的个数 */
export interface LedgerSheet {
  sheet: string
  nonempty_scan: number
  nonempty_read: number
  roles?: Record<string, number>
  unclaimed?: number
}

export interface ReceiptTable {
  name: string
  sheet: string
  kind: 'data' | 'reported_total' | (string & {})
  columns: { name: string; type: string; header?: string | null; unit?: string | null; role?: string }[]
  grain: string[]
  rows: number
  sources?: string[]
}

export interface PeriodOut {
  start: string
  end: string
  source: 'cells' | 'human' | (string & {})
  cells?: string[]
  signed_by?: string | null
  texts?: Record<string, string>
  annotated?: Record<string, string>
}

export interface OutsideText {
  sheet: string
  /** 带工作表名的坐标「工作表!A1」（与问题的 cells 同一写法） */
  cell: string
  text: string
  kind: 'text' | 'text_digits' | (string & {})
  period_source?: boolean
  /**
   * 期 4：所在行或列是否被隐藏（执行器写入）。true 在隐藏行列里；false 可见；null 或没有这个键：导入时没有记录
   * （期 4 之前的清单）。裁判摘录只送 false 的项，界面照常显示全部区域外文字
   */
  hidden?: boolean | null
}

/** 试运行回执（Extraction 去掉问题和核对之后给界面看的部分） */
export interface TrialReceipt {
  ledger?: LedgerSheet[]
  tables?: ReceiptTable[]
  period?: PeriodOut | null
  placeholders?: Record<string, number>
  outside_text?: OutsideText[]
  canonicalized_total?: number
  blank_rows_skipped?: number
  formula_cells_accepted?: number
  full_calc_on_load?: boolean
  db_sha256?: string
  /** 期 3：排除的行（H2）。期 3 之前的回执没有这个字段：缺省表示「未记录」，不等于「没有排除」。
   * 服务端：试运行回执（TrialOut.receipt）只抄 recipe_imports._RECEIPT_VIEW 白名单里的键，WP-5 要把
   * rows_excluded 加进去；导入清单的 receipt 也要有。期 3 的试运行一律带这个键（没有排除时是 []） */
  rows_excluded?: ExcludedRows[]
  [key: string]: any
}

/** passed 通过；needs_input 需要录入统计期；needs_decision 有可接受的核对待写理由；rejected 拒收 */
export type TrialStatus = 'passed' | 'needs_input' | 'needs_decision' | 'rejected' | (string & {})

/** 最近一次试运行（StagingOut.trial） */
export interface TrialOut {
  trial_id: string
  status: TrialStatus
  receipt: TrialReceipt
  problems: ImportProblem[]
  checks: CheckResult[]
  confirm_items: ConfirmItem[]
  /** 可以写理由接受、本次未通过的核对 id */
  acceptable: string[]
  /** 表 → 说明预览 */
  notes?: Record<string, { comment: string; columns?: Record<string, string> }>
  diff?: DiffItem[] | null
  same_as_import?: { id: string; seq: number } | null
  base_snapshot_id?: string | null
  /** 期 3：累积计划。新配方是按期累积、或现行是按期累积时给出 */
  accumulate?: AccumulatePlan | null
  /** 期 3：工作配方与现行配方不同时的新旧对照 */
  recipe_compare?: RecipeComparison | null
  /** 期 3：并集的结构核对 U1–U3（物化了才有） */
  union_checks?: CheckResult[] | null
  /** 期 3：同一份构建以前被接受过的理由，只读显示，不预填 */
  prior_acceptances?: PriorAcceptance[]
}

/** AI 起草的结果摘要 */
export interface AiDraftSummary {
  draft: Draft | null
  usage?: AiUsage[]
  attempts?: number
  total_tokens?: number
  cost_usd?: number
  error?: string | null
}

/** 暂存区（一次未提交的按配方导入）：GET /imports/{id} 等接口的返回 */
export interface Staging {
  id: string
  kind: ImportStagingKind
  status: ImportStagingStatus
  source: { id: string; name: string; exists: boolean; import_mode: 'simple' | 'recipe' | null }
  file: { name: string; size: number; sha256_prefix: string }
  sheets?: {
    name: string; state: string; bounds: string | null; nonempty: number; merged?: number
    formulas?: number; formulas_uncached?: number; hidden_rows?: number; hidden_cols?: number
  }[]
  skipped_sheets?: { sheet: string; state: string }[]
  full_calc_on_load?: boolean
  grids: GridPreview[]
  draft: Draft | null
  ai_draft: AiDraftSummary | null
  /** offered：这次导入提供 AI 起草入口；available：模型接入可用 */
  ai: { offered: boolean; available: boolean; reason?: string; model?: string; provider?: string }
  ai_consents?: { signed_by: string | null; at: string; model: string; compressed_sha256: string; chars: number }[]
  recipe: Recipe | null
  recipe_origin?: string | null
  recipe_problems: RecipeProblem[]
  answers: Record<string, QuestionAnswer>
  cards: Card[]
  questions: Question[]
  draft_problems: ImportProblem[]
  /** 干跑只检查了每张工作表的前若干行 */
  draft_partial: boolean
  /** 分段标题原文 → 常量可选的词 */
  candidates: Record<string, string[]>
  /** 单位词表 */
  units: string[]
  marks: RegionMark[]
  trial: TrialOut | null
  context_inputs?: Record<string, { start: string; end: string; signed_by?: string | null }>
  /** 最近一次试运行时数据源的当前版本（与 trial.base_snapshot_id 同值；提交时对不上回 409 base_changed）。
   *  数据源还没有当前版本（首次导入）或没试运行过时为 null；试运行作废后保留原值。
   *  所以不能拿它是不是 null 判断「试运行过没有」，那要看 trial 与 status */
  base_snapshot_id?: string | null
  /** 提交后生成的导入记录 id；未提交为 null */
  committed_import_id?: string | null
  /** 期 3：修复提议（按当前问题现算）。问题对象上的 fix_ids 指向这里的 id */
  fixes?: FixProposal[]
  /** 期 3：当前工作配方的哈希（撤销是否可用、预览是否过期都按它判断） */
  recipe_sha256?: string | null
  /** 期 3：已应用的修改（修复、框选），按 seq 升序 */
  edits?: StagingEdit[]
  /** 期 3：改配方后不再成立、被移除的回答 */
  answers_dropped?: AnswerDropped[]
  created_at?: string
  updated_at?: string
  expires_at?: string
}

/** GET draft-ai/preview：将要发给模型的压缩表示原文 */
export interface AiPreview {
  text: string
  chars: number
  /** 同意令牌：绑定全文、接入名和模型 id，POST draft-ai 原样带回（三者任一变了服务端回 409 ai_preview_stale） */
  sha256: string
  /** 全文本身的 sha256（留痕用） */
  text_sha256?: string
  model: string
  provider: string
}

/** POST imports/{id}/commit 的返回 */
export interface CommitOut {
  source: DataSource
  import_id: string
  snapshot_id: string
  build_id: string
  recipe_id: string
  build_reused: boolean
  /** 与某次导入完全相同，未新建版本 */
  unchanged: boolean
  /** 期 3：服务端的同版本数据文件曾被改动，已用本次上传的文件恢复 */
  build_restored?: boolean
  /** 期 3：启用后当前版本含几期 */
  parts?: number
  /** 期 3：与此前某个版本内容相同，直接启用了那个版本 */
  snapshot_reused?: boolean
}

/** GET /{source_id}/recipe：当前启用的配方（补全了默认值） */
export interface CurrentRecipe {
  recipe_id: string
  seq: number
  origin: string
  recipe: Recipe
  recipe_sha256: string
  confirmations: { id: string; label: string; at: string }[]
  signed_by: string | null
  activated_at: string | null
}

// ---------------------------------------------------------------------------
// 期 3：修复按钮、框选、按期累积、配方对照、版本页（P3-SPEC 第 9 节）。字段与后端 recipe_types.py 的 dataclass
// 和接口的 JSON 同名（Selection 的 as 除外：后端 dataclass 叫 as_，JSON 里是 as）
// ---------------------------------------------------------------------------

/** 修复按钮的种类（契约 FIX_KINDS） */
export type FixKind =
  | 'remove_label' | 'add_label' | 'edit_members' | 'rename_title' | 'declare_total' | 'ignore_cells'
  | 'declare_placeholder' | 'declare_hidden' | 'rename_sheet' | 'declare_subtotals' | 'declare_text_measure'
  | (string & {})

/** 修复提议的一个封闭选项。效果由服务端算：界面只发 fix_id、value 和理由 */
export interface FixOption {
  value: string
  label: string
  detail?: string
  /** 选它必须写理由（1–200 字）：理由填好后才预览，理由改了要重新预览 */
  needs_reason?: boolean
  breaking?: boolean
}

/** 提议对应哪一条问题：problem / recipe_problem 按下标，sheet_renamed 按本期的工作表名 */
export interface FixAnchor {
  kind: 'problem' | 'recipe_problem' | 'sheet_renamed' | (string & {})
  index?: number | null
  sheet?: string | null
}

/** 修复提议（Staging.fixes 的一项，契约 FixProposal） */
export interface FixProposal {
  /** fx- 加 12 位十六进制：同样的问题得到同样的 id */
  id: string
  kind: FixKind
  problem_code: string | null
  title: string
  cells: string[]
  target: Record<string, any>
  options: FixOption[]
  anchor: FixAnchor
}

/** 框选「选它是什么」的封闭取值（契约 SELECTION_AS） */
export type SelectionAs =
  | 'list' | 'crosstab' | 'segment' | 'derived' | 'section_title' | 'ignore_rows' | 'ignore_columns' | 'ignore_outside'

/** 框选的参数（按 as 取用：list 用 header_rows、table、bottom；segment 用 role、table；derived 用 keep；
 * section_title 用 segment；ignore_* 用 reason） */
export interface SelectionOptions {
  /** 1–3，默认 1 */
  header_rows?: number
  table?: string
  /** box 以框的下边为准（默认）；auto 下边界按规则推断 */
  bottom?: 'box' | 'auto'
  role?: 'measures' | 'dimension'
  keep?: boolean
  segment?: string
  reason?: string
  [key: string]: unknown
}

/** 一次框选（edits/preview、edits/apply 请求里的 selection） */
export interface SelectionRequest {
  sheet: string
  /** A1 区域，不带工作表名，列字母大写、不带 $（「C5」或「C5:F8」）：别的写法服务端回 422 edit_invalid */
  ref: string
  as: SelectionAs
  options?: SelectionOptions
}

/** edits/preview、edits/apply 的请求：fix 与 selection 二选一。seq 是界面的预览序号，原样回传 */
export type EditRequest =
  | { fix: { id: string; option: string; reason?: string }; selection?: never; seq?: number }
  | { selection: SelectionRequest; fix?: never; seq?: number }

/** 框选换算出的锚点（契约 Anchor），界面显示「按文字定位」 */
export interface EditAnchor {
  kind: 'header' | 'row_label' | 'section_title' | 'total_word' | 'axis' | 'after_title' | 'outside_text' | (string & {})
  text: string
  cell?: string | null
}

/** 框选的期望区域与重放结果的比对（契约 ReplayCompare） */
export interface ReplayCompare {
  /** 列表：{header, data, total}；交叉表：{axis, labels, values} */
  expected: Record<string, string | null>
  actual: Record<string, string | null>
  match: boolean
  diffs: string[]
  /** 部分干跑时只比较前多少行；完整比较为 null */
  window_rows?: number | null
}

/** POST edits/preview 的返回（P3-SPEC 9.4 EditPreview） */
export interface EditPreview {
  ok: boolean
  kind: 'fix' | 'selection' | (string & {})
  /** 目标键（remove_label:日间:7-8）；确认项 fix:<key> / select:<key> 用它 */
  key: string
  title: string
  summary: string[]
  /** 按完整形式写的 JSON Patch：不给用户看，最多收在技术细节里 */
  ops: { op: string; path: string; value?: unknown }[]
  anchors: EditAnchor[]
  notes: string[]
  /** ok=false 时的原因（category=recipe），坐标可点 */
  problems: ImportProblem[]
  recipe_sha256_before: string | null
  /** apply 时原样作为 expected_sha256 发回 */
  recipe_sha256_after: string | null
  recipe_problems: RecipeProblem[]
  dry_run: { problems: ImportProblem[]; partial: boolean; marks: RegionMark[] } | null
  replay: ReplayCompare | null
  /** 对现行配方的破坏性变化：表名 → 人话列表；空对象表示没有。
   * 注意：这不是后端 EditResult.breaking（那是服务端内部的布尔）。WP-5 组装预览时必须总是用
   * table_changes 算出的字典覆盖它；收到布尔说明服务端漏了覆盖，Object.entries(false) 是 []，
   * 破坏性变化会从预览里消失 */
  breaking: Record<string, string[]>
  accumulate_change: 'same' | 'compatible' | 'retire' | 'semantic' | (string & {}) | null
  /** 当前工作配方对比修改后的配方（复用 RecipeCompare 显示） */
  compare: RecipeComparison | null
  /** 框选：换算出的期望区域 */
  expected?: Record<string, string | null> | null
  /** 框选：新增或替换的块 id */
  block?: string | null
  /** 请求里的预览序号，原样回传：不是最新一次的回包丢弃 */
  seq?: number | null
}

/**
 * 暂存区里已应用的一次修改（Staging.edits 的一项）。服务端 recipe_imports._edit_out 从修改记录里去掉撤销用的起点
 * （before、base_sha256_after）和补丁（ops，只进导入清单），其余原样给出
 */
export interface StagingEdit {
  seq: number
  kind: 'fix' | 'selection' | (string & {})
  key: string
  title: string
  /** 预览时的人话摘要（EditPreview.summary），应用时原样记下 */
  summary?: string[]
  at: string
  signed_by: string | null
  recipe_sha256_before: string | null
  recipe_sha256_after: string | null
  /** 之后整份替换过配方（PUT）：不能撤销，也不再出确认项 */
  superseded: boolean
  /** 只有最后一条、未被覆盖的为 true */
  undoable: boolean
  /** kind=fix：人选的是哪条提议、哪一项、写的理由（与 edits/apply 请求里的 fix 同形）。WP-5 评审修复之前记下的修改没有 */
  fix?: { id: string; option: string; reason: string | null }
  /** kind=selection：这次框选（Selection.to_json，键是 as，options 总是对象）。同上，旧记录没有 */
  selection?: SelectionRequest & { options: SelectionOptions }
}

/** 改配方后被移除的回答：changed 需要重新回答；gone 问题已不适用。text 是问题文字（界面不露 id） */
export interface AnswerDropped {
  id: string
  text: string
  reason: 'changed' | 'gone' | (string & {})
}

/** 同一份构建以前被接受过的理由（TrialOut.prior_acceptances），只读显示 */
export interface PriorAcceptance {
  check_id: string
  reason: string
  signed_by: string | null
  at: string
  /** 第几次导入 */
  import_seq: number
}

/** 排除的行的原因（契约 ExcludedRows.reason） */
export type ExcludedReason =
  | 'hidden_excluded' | 'blank_skipped' | 'ignored_rows' | 'ignored_outside' | 'after_stop' | 'total_not_kept'
  | 'subtotal'
  | (string & {})

/** 回执里的「排除的行」（契约 ExcludedRows）。按表头忽略的列不在这里（记在回执的 ignored_columns） */
export interface ExcludedRows {
  sheet: string
  reason: ExcludedReason
  /** [[起, 止], …]，1 起的行号闭区间 */
  rows: [number, number][]
  cells: number
  anchor?: string | null
  block?: string | null
}

/** ReceiptBlocks.tsx 的「排除的行」：向导回执和版本页的清单视图共用。onFocus 收「工作表!A1」 */
export interface RowsExcludedProps {
  rows: ExcludedRows[] | null | undefined
  onFocus?: (cell: string) => void
}

/** ReceiptBlocks.tsx 的回执摘要：receipt 是试运行回执或导入清单里的 receipt（形状相同） */
export interface ReceiptSummaryProps {
  receipt: TrialReceipt | null | undefined
  onFocus?: (cell: string) => void
}

/** 累积计划的 action（契约 ACCUMULATE_ACTIONS） */
export type AccumulateAction = 'replace' | 'first' | 'append' | 'replace_period' | 'restart' | 'rejected' | (string & {})

/** 累积计划里的一期。本期 import_id、seq 为 null，new 为 true */
export interface AccumulatePart {
  import_id: string | null
  seq: number | null
  start: string
  end: string
  file_name: string
  new: boolean
  /** 表 → 该期行数 */
  rows: Record<string, number>
  /** 该期配方不满足按期累积的原因（契约 accumulate_blockers） */
  blockers: RecipeProblem[]
}

/** 计划里提到的一期（被替换、被移出、部分重叠）：至少有起止，其余字段同 AccumulatePart、可能缺省 */
export interface AccumulatePeriodRef {
  import_id?: string | null
  seq?: number | null
  start: string | null
  end: string | null
  file_name?: string
  rows?: Record<string, number>
}

/** 表或列的新增、退役：column 为 null 表示整张表 */
export interface TableColumnRef {
  table: string
  column: string | null
  periods?: string[]
}

/** 各期维度取值的差异（P3-SPEC 2.5） */
export interface LabelSetDiff {
  table: string
  column: string
  segment: string
  periods: { start: string; end: string; missing: string[]; extra: string[] }[]
}

/** 累积计划（TrialOut.accumulate，P3-SPEC 9.4 AccumulatePlan） */
export interface AccumulatePlan {
  mode: 'replace' | 'accumulate' | (string & {})
  action: AccumulateAction
  /** 本期统计期。source：cells 取自表内，human 人工录入；每期替换且没有统计期时 start、end 为 null */
  period: { start: string | null; end: string | null; source?: 'cells' | 'human' | (string & {}) }
  parts: AccumulatePart[]
  replaces: AccumulatePeriodRef | null
  /** restart、模式切换时移出当前版本的各期：界面标「将不在当前版本中」 */
  dropped: AccumulatePeriodRef[]
  overlaps: AccumulatePeriodRef[]
  gaps: { start: string; end: string }[]
  backfill: boolean
  change: 'same' | 'compatible' | 'retire' | 'semantic' | (string & {})
  added: TableColumnRef[]
  retired_new: TableColumnRef[]
  retired_existing: TableColumnRef[]
  semantic: string[]
  label_sets: LabelSetDiff[]
  mode_switch: 'replace->accumulate' | 'accumulate->replace' | (string & {}) | null
  reason: string | null
  /** 物化了的并集：rows 是「启用后当前版本」的行数；没有物化为 null（此时等于本期） */
  union: { union_id: string; db_sha256: string; rows: Record<string, number> } | null
}

/** 新旧配方对照里一列的摘要 */
export interface CompareColumnBrief {
  type: string
  unit?: string | null
  source?: string | null
}

export type CompareStatus = 'added' | 'removed' | 'changed' | 'same' | (string & {})

/** 新旧配方对照（P3-SPEC 9.4 RecipeComparison，WP-3 compare_recipes 产出） */
export interface RecipeComparison {
  tables: {
    name: string
    status: CompareStatus
    columns: {
      name: string
      status: CompareStatus
      old: CompareColumnBrief | null
      new: CompareColumnBrief | null
      /** table_changes 的 kind（type / unit / source / store / const_value …） */
      changes: string[]
    }[]
    grain: { old: string[] | null; new: string[] | null; changed: boolean }
    kind: { old: string | null; new: string | null }
    /** 这张表除单位以外的破坏性变化（table_changes 的原话），是完整清单；单位变化只在 columns[].changes 与 units_changed 里 */
    breaking: string[]
  }[]
  segments: {
    id: string
    status: CompareStatus
    title: { old: string | null; new: string | null }
    labels: { added: string[]; removed: string[] }
    ignore: { added: string[]; removed: string[] }
  }[]
  relations: { id: string; status: CompareStatus; old: string | null; new: string | null }[]
  sheets: { id: string; name: { old: string | null; new: string | null } }[]
  mode: { old: string | null; new: string | null }
  breaking: boolean
  /** 单位变化的列（界面排在最前） */
  units_changed: { table: string; column: string; old?: string | null; new?: string | null }[]
  accumulate: {
    change: string
    added: TableColumnRef[]
    retired_new: TableColumnRef[]
    retired_existing: TableColumnRef[]
  } | null
}

/** POST imports/{id}/redraft-rules 的返回：不改工作配方，「采用」时再 PUT recipe（origin: rules_redraft） */
export interface RedraftRulesOut {
  draft: Draft
  aligned_recipe: Recipe | null
  /** 名字对齐的人话说明 */
  alignment: string[]
  compare: RecipeComparison | null
}

// ---- 版本页（P3-SPEC 第 7 节）

/** 一期的统计期引用：简单导入或没有统计期的期，start、end 为 null，带 file_name */
export interface PeriodRef {
  start: string | null
  end: string | null
  file_name?: string
}

/** 版本列表里一个版本的一期 */
export interface SnapshotPart {
  import_id: string
  seq: number
  period_start: string | null
  period_end: string | null
  file_name: string
  raw_state: 'kept' | 'purged' | 'absent' | (string & {})
  status: string
  /** 表 → 该期行数 */
  rows: Record<string, number>
  /** 接受的条数（数据质量不成立 / 合计无法核对） */
  overrides: number
  waivers: number
  revoked: boolean
}

/** GET /{source_id}/snapshots 的一行（7.1）。当前版本排第一 */
/** 快照不能启用的原因代码（后端 recipe_types.SnapshotReasonCode；VERSIONS_TEXT.notActivatable 的键与它相同） */
export type SnapshotReasonCode = 'current' | 'retired' | 'file_lost' | 'contains_revoked'

export interface SnapshotOut {
  id: string
  current: boolean
  mode: 'replace' | 'accumulate' | (string & {}) | null
  created_at: string | null
  activated_at: string | null
  /** 简单导入为 null */
  recipe: { id: string; seq: number } | null
  parts: SnapshotPart[]
  /** 表 → 启用这个版本后的行数 */
  tables: Record<string, number>
  db_sha256_prefix: string
  /** 数据文件的字节数 */
  db_size: number | null
  /** 记录没回收、文件在 */
  available: boolean
  /** 引用它的运行数（任何状态） */
  pinned_runs: number
  activatable: boolean
  /** 不能启用的原因（人话）；能启用为 null。服务端取后端契约 SNAPSHOT_NOT_ACTIVATABLE[reason_code]，
   * 与 VERSIONS_TEXT.notActivatable 逐字相同 */
  reason: string | null
  /** 不能启用的原因的代码（契约补充：7.1 只给了人话，available=false 同时覆盖「已回收」和「数据文件已丢失」，
   * 界面分不出来）。能启用为 null。界面按 VERSIONS_TEXT.notActivatable[reason_code] 显示，缺省或不认识时
   * 退回显示 reason，不去匹配 reason 的原文。几种同时成立时服务端取第一个：current > retired > file_lost >
   * contains_revoked */
  reason_code?: SnapshotReasonCode | null
  /** 当前的遮罩列里，这个版本没有同名列的 */
  mask_lost: string[]
  /** 与当前版本相比，启用后增减的期 */
  periods_diff: { added: PeriodRef[]; removed: PeriodRef[] }
}

/** POST …/snapshots/{snapshot_id}/activate 的请求（7.2） */
export interface ActivateSnapshotBody {
  confirm: true
  /** 界面看到的当前版本 id：对不上回 409 base_changed */
  expected_current_snapshot_id: string | null
  /** mask_lost 非空时必填，与它相同 */
  ack_mask_lost?: string[]
  reason?: string
  signed_by?: string | null
}

export interface ActivateSnapshotOut {
  source: DataSource
  snapshot_id: string
  previous_snapshot_id: string | null
  recipe_id: string | null
}

/** 导入清单、快照清单（7.3）。verified：取回时内容哈希复验通过 */
export interface ManifestOut {
  artifact_id: string | null
  verified?: boolean
  /** import_manifest；简单导入是 build_report（构建回执）；snapshot_manifest；单期快照是 snapshot_view（合成的视图） */
  kind: 'import_manifest' | 'build_report' | 'snapshot_manifest' | 'snapshot_view' | (string & {})
  content: Record<string, any>
}

/** POST …/imports/{import_id}/remove 的请求（7.4，累积模式） */
export interface RemovePeriodBody {
  confirm: true
  expected_current_snapshot_id: string | null
  /** 1–500 字，必填 */
  reason: string
  signed_by?: string | null
}

export interface RemovePeriodOut {
  source: DataSource
  snapshot_id: string
  removed_import_id: string
  /** 复用（或复活）了同内容的已有版本 */
  reused: boolean
}

/** POST …/imports/{import_id}/revoke-acceptance 的请求（7.5） */
export interface RevokeAcceptanceBody {
  confirm: true
  expected_current_snapshot_id: string | null
  reason: string
  signed_by?: string | null
  /** 替换模式：取自 revoke_plan.target_snapshot_id */
  expected_target_snapshot_id?: string | null
  /** 回滚目标有遮罩列丢失时带上，与 revoke_plan.mask_lost 相同 */
  ack_mask_lost?: string[]
}

export interface RevokeAcceptanceOut {
  source: DataSource
  snapshot_id: string
  action: 'rollback' | 'remove_period' | (string & {})
}

/** 一条接受（导入记录的 acceptances） */
export interface ImportAcceptance {
  check_id: string
  kind: 'override' | 'waiver' | (string & {})
  reason: string
  signed_by: string | null
  at: string | null
}

/** 作废接受的预案（只对在当前版本里、带接受的导入给）：确认框照它写 */
export interface RevokePlan {
  /** 不能作废时为 null，reason 写原因 */
  action: 'rollback' | 'remove_period' | (string & {}) | null
  target_snapshot_id: string | null
  /** 替换模式的回滚目标 */
  target: { parts: PeriodRef[]; recipe_seq: number | null; mode: string | null; simple: boolean } | null
  /** 累积模式：移除后的各期 */
  result_parts: PeriodRef[]
  gaps: { start: string; end: string }[]
  mask_lost: string[]
  reason: string | null
}

/** GET /{source_id}/imports 的一行（期 1 接口，期 3 补字段，7.6） */
export interface ImportRecord {
  id: string
  seq: number
  build_id: string
  file_name: string
  file_size: number | null
  raw_sha256: string | null
  raw_state: 'kept' | 'purged' | 'absent' | (string & {})
  status: string
  /** 清除记录 {at, reason, signed_by…}；没清除为 null */
  purged: Record<string, any> | null
  /** 在当前版本里（与 in_current 同值） */
  current: boolean
  created_at: string | null
  activated_at: string | null
  recipe_id: string | null
  period_start: string | null
  period_end: string | null
  signed_by: string | null
  /** 署名是不是认证过的身份：按这一期导入清单里记下的（05-已知遗留 (c)），旧清单记的是 false。老后端不给 */
  signed_by_verified?: boolean
  /** 接受的条数 */
  overrides: number
  waivers: number
  /** 期 3 */
  acceptances?: ImportAcceptance[]
  revoked?: { at: string; reason: string; signed_by: string | null; signed_by_verified: boolean } | null
  manifest_artifact?: string | null
  recipe_seq?: number | null
  in_current?: boolean
  /** 表 → 该期行数 */
  rows?: Record<string, number>
  revoke_plan?: RevokePlan | null
  /** 同一份原件内容在其他导入记录里的引用，按源汇总（本源也算）。source_name：现在的后端对已删除的源写
   *  「已删除的数据源」，老后端或老数据可能是 null——声明成可空，让界面的兜底由类型强制（同 also_purged） */
  raw_shared_with?: { source_name: string | null; count: number }[]
  /** 引用这份原件的未结束导入个数 */
  raw_open_stagings?: number
}

/** POST …/imports/{import_id}/purge-raw 的请求（理由必填） */
export interface PurgeRawBody {
  confirm: true
  reason: string
  signed_by?: string | null
}

export interface PurgeRawOut {
  import: ImportRecord
  file_deleted: boolean
  /** 同一份内容一并清除的其他导入记录 */
  also_purged: { id: string; source_id: string; source_name: string | null; seq: number; file_name: string }[]
  /** 一并放弃的未完成导入 */
  discarded_stagings: string[]
}

/** 自定义工具（GET /api/custom-tools 的一行；POST / PATCH 的返回同形） */
export interface CustomTool {
  id: string
  name: string
  description: string
  kind: 'http' | 'python' | (string & {})
  parameters: Record<string, any>
  config: Record<string, any>
  enabled: boolean
  /** 同 ToolInfo.problem：参数定义写坏了的那句话，没问题是 null */
  problem?: string | null
}

export interface Skill {
  id: string
  name: string
  description: string
  instructions: string
  examples: { input?: string; output?: string }[]
  suggested_tools: string[]
  tags: string[]
  enabled: boolean
}

export interface MemoryItem {
  id: string
  scope: string
  kind: string
  content: string
  importance: number
  use_count: number
  meta: Record<string, any>
  /**
   * 从哪来。kind=run 时带运行、节点和工作流名；manual 是手动添加的；playground 是
   * 在工具库里直接调 remember 写进来的。老后端不给
   */
  source?: MemorySource | null
  created_at?: string
  /** 后端不再给：每次计数的回忆都会写这一行，updated_at 跟着回忆走，不是编辑时间 */
  updated_at?: never
  last_used_at?: string | null
}

export interface MemorySource {
  kind?: 'run' | 'manual' | 'playground' | string
  run_id?: string | null
  node_id?: string | null
  workflow_name?: string | null
  node_label?: string | null
  /** 来源运行是否还在。删掉之后只剩文字，不再给链接 */
  run_exists?: boolean
  [key: string]: any
}

export interface KbDocument {
  id: string
  collection: string
  title: string
  source: string
  mime: string
  chunk_count: number
  /** ready | processing | failed。大文件的切块和算向量在后台跑 */
  status?: string
  error?: string
  meta?: { progress?: { done: number; total: number } }
  created_at?: string
}

export interface ValidationIssue {
  /**
   * info 是建议，不是问题（比如 evidence.upgrade_available「可以升级为可追溯结构」）：store 在校验回来时
   * 就把它分到 advice 里，issues 里只有 error / warning——节点卡、检查器、运行按钮都只认这两档
   */
  level: 'error' | 'warning' | 'info'
  node_id?: string | null
  edge_id?: string | null
  message: string
  /** 出问题的是节点配置里的哪一项：'prompt'、'tools'、'cases[1].condition'。老后端不给 */
  field?: string | null
  /** 机读编号（governed.agent_approval_never 这类），发布前检查按它认修复。老后端不给 */
  code?: string | null
  /** 这条问题对应的修复 id：publish-check 的 fixes 里同 id 的那一项。没有修复时为空 */
  fix?: string | null
  /**
   * 发布门禁里的 SQL 检查：这条检查本来的级别。level 说的是拦不拦（已发布档一律 warning），它说的是错误还是提醒。
   * 别的问题、老服务端不给
   */
  sql_level?: 'error' | 'warning' | null
}

/** 发布等级：发布弹窗、问题面板的发布前检查共用 */
export type PublishLevel = 'published' | 'governed'

/**
 * 发布前检查给的一项修复（POST /workflows/{id}/publish-check 的 fixes）。
 * auto：答案唯一、不降低要求，预览后一键修；choice：要人拿主意，options 里挑（multiple 可多选）；
 * assist：结构性的，交给 Copilot 试着改，产出同样只是预览
 */
export interface PublishFix {
  id: string
  code: string
  kind: 'auto' | 'choice' | 'assist'
  node_id?: string | null
  /** 这条修复落在哪个字段：点名的模型接入一处一条（同一节点上的几处按它区分） */
  field?: string | null
  label: string
  preview?: { field?: string | null; before?: unknown; after?: unknown } | null
  /** handoff：选了这一项就是「交给 Copilot」（G4 的「它在做计算」）。只认这个标记，不认值——
   *  别的选项拿节点 id 当值，节点 id 恰好叫 copilot 的报告撰写节点照样是普通候选。
   *  demo：点名的模型接入的候选，修完以后执行时落到演示类接入（不调用真实模型），选项名旁加醒目的标签 */
  options?: { value: unknown; label: string; hint?: string | null; handoff?: boolean; demo?: boolean }[]
  multiple?: boolean
  /** 建议值：界面上标「建议」，仍然要人选 */
  default?: unknown
}

export interface PublishCheck {
  level: PublishLevel
  ok: boolean
  issues: ValidationIssue[]
  fixes: PublishFix[]
}

/** 自动修复预览里给人看的一项改动：「节点 · 字段：原值 → 新值」 */
export interface AutofixChange {
  fix_id: string
  node_id?: string | null
  node_title?: string | null
  field?: string | null
  before?: unknown
  after?: unknown
  label?: string | null
}

/** POST /workflows/{id}/autofix：只给预览，不改库、不发布 */
export interface AutofixResult {
  /** 修复后的整张图；人确认后前端走保存接口存成草稿 */
  graph: GraphSpec | null
  changes: AutofixChange[]
  applied: string[]
  rejected: { fix_id: string; reason: string }[]
  /** 修复后仍然存在的问题（带 code 和 fix） */
  remaining: ValidationIssue[]
  /** 交给 Copilot 的那一段：它认为要人拿主意的放进 questions，不硬改 */
  assist: { ok: boolean; summary?: string; questions?: string[] } | null
  /** 修复后是否已经没有 error */
  ok: boolean
}

/**
 * 一键升级预览里的一项改动。形状同自动修复的 AutofixChange，另认这几种：
 * field 为 type 是节点类型的变化（llm → report）；field 为 node 是新插入的节点（after 是节点）；
 * field 为 edge 是连线的改接（before / after 是 {source, target}）。rule 是命中的改写规则（R1–R4；Copilot 那一段是 assist）。
 * 同一步（同一个 fix_id）的几项改动共用一句 label
 */
export interface UpgradeChange extends AutofixChange {
  rule?: string | null
}

/** 升级给的说明：不改、只建议的（R5：代码节点要不要标成 source），原样给人看 */
export interface UpgradeNote {
  text: string
  node_id?: string | null
  rule?: string | null
  level?: 'info' | 'warning'
}

/** POST /copilot/upgrade-evidence：只给预览，不自动保存 */
export interface UpgradeResult {
  /** 升级后的整张图；人确认后走现有的保存 */
  graph: GraphSpec | null
  changes: UpgradeChange[]
  notes: UpgradeNote[]
  /** 升级后的图重跑 validate 和门禁剩下的问题 */
  issues: ValidationIssue[]
  /** 没有采用的改动（Copilot 的改写冒出新问题、碰了禁止规则），写明原因 */
  rejected: { fix_id: string; reason: string }[]
  /** assist 时 Copilot 的那一段：非纯算术、保留没改的代码节点在 warnings 里 */
  assist: { ok: boolean; summary?: string; questions?: string[]; warnings?: string[] } | null
}

/** 单个节点在一次运行中的实时状态，驱动画布上的高亮。 */
export interface NodeRuntime {
  /** cancelled / suspended 是终态清扫时收的：运行被取消或服务重启时还没跑完的节点 */
  /** rejected：这一步被人驳回（node.failed 带 reason=rejected，run/trace 的 NodeState 同名） */
  status: 'idle' | 'running' | 'done' | 'failed' | 'waiting' | 'skipped' | 'cancelled' | 'suspended' | 'rejected'
  durationMs?: number
  preview?: any
  error?: string
  tokens?: string
  thinking?: string
  toolCalls?: { tool: string; args?: any; result?: string; ok?: boolean; agent?: string }[]
  /** supervisor 的协作矩阵：谁被派了、在第几轮、几个人同时在跑。运行中长出来 */
  team?: TeamRun
  /** loop 走到第几轮（从 1 数）。卡片上那个"第 2/5 轮" */
  iteration?: number
  /** 分支/循环实际走的出口。命中的那条亮起来、其余压暗——不然一个六出口的
   *  分支节点跑完，谁也说不清它到底选了哪条 */
  takenHandle?: string
  /** 走这条出口的理由：表达式分支命中了哪条条件，或调度者为什么派给这个人 */
  reason?: string
}

/**
 * 协作团队一轮里的一个人。
 *
 * ms 是**各自量出来**的耗时，不是拿整轮墙钟摊的——界面要显示"并行省了多少"，
 * 那个数按 N×墙钟 推算会把快的那个也记成最慢那条，省下的时间就被夸大了。
 */
export interface TeamMember {
  agent: string
  instruction: string
  ms: number
  status: 'running' | 'done' | 'failed' | 'waiting' | 'cancelled' | 'suspended'
  result?: string
}

export interface TeamRound {
  round: number
  /** 这一轮同时派了几个人。1 就是串行的一步 */
  parallel: number
  /** 这一轮实际花的时间：并发时是最慢那个 */
  wallMs: number
  /** 各人耗时之和：并发时它大于 wallMs，差值就是省下的 */
  sumMs: number
  reason?: string
  members: TeamMember[]
}

export interface TeamRun {
  /** 花名册，按第一次出现的顺序——泳道的行顺序 */
  members: string[]
  rounds: TeamRound[]
  /** 并行一共省下多少毫秒。全程串行则为 0 */
  savedMs: number
  /** 协作是不是已经收尾了 */
  finished: boolean
}

/** 一处 {{ }} 引用 */
export interface VarRef {
  node_id: string
  node_label: string
  field: string
  expr: string
}

/** 一个可以被 {{ }} 引用的东西。由后端静态分析整张图得出 */
export interface Variable {
  path: string
  kind: 'input' | 'var' | 'node' | 'builtin' | 'loop'
  label: string
  produced_by?: string | null
  produced_by_label?: string | null
  order: number
  refs: VarRef[]
  description: string
}

export interface VarIssue {
  level: 'error' | 'warning' | 'info'
  message: string
  node_id?: string | null
  path: string
}

/**
 * 一次对话。
 *
 * kind 分两种：chat 是问数据页（一轮 = 建图 → 跑图 → 出答案，进左侧列表），
 * canvas 是画布右栏的 Copilot（依附某张图，一轮 = 一次改图，不进列表）。
 */
export interface Conversation {
  id: string
  title: string
  /**
   * 前端建的只有 chat、canvas；服务端另建两种：app 是应用编辑器的助手对话，blueprint 是蓝图对话（docs/design/normal-user-apps.md
   * §2.2，权限跟着蓝图走，经 GET /api/blueprints/{id}/conversation 读）
   */
  kind: 'chat' | 'canvas' | 'app' | 'blueprint'
  workflow_id?: string | null
  archived: boolean
  created_at?: string
  last_active_at?: string
  turn_count: number
  /** 列表里的副标题，让人一眼认出是哪次聊天 */
  last_question: string
  /**
   * 最后一轮停在哪。左栏对这次没打开过的会话也能标出运行中、待审批、失败、被驳回（rejected：运行被审批人驳回结束，
   * 服务端 cancelled + end_reason=rejected）。没有轮次时为 null；老后端不给
   */
  last_status?: 'running' | 'waiting' | 'error' | 'cancelled' | 'rejected' | 'suspended' | 'done' | null
  /** 最后一轮的运行。建图阶段就断了的没有 */
  last_run_id?: string | null
}

export interface ConversationDetail extends Conversation {
  turns: ConversationTurn[]
}

export interface ConversationTurn {
  id: string
  seq: number
  question: string
  answer: string
  explanation: string
  graph?: GraphSpec | null
  /** 可能为空：建图阶段就失败时压根没有 run，但这一轮仍然发生过 */
  run_id?: string | null
  status: 'running' | 'done' | 'error'
  error: string
  /** 复核结论。null = 这一轮没复核过，和「复核过、没发现问题」不是一回事 */
  review?: ReviewResult | null
  /**
   * 可信度元数据（出具档位、运行类别、耗时、查库次数……），前端整块写、整块读，
   * 后端只用它算 last_status。老轮次挂在 review.meta 下，后端读出来时统一放到这里
   */
  meta?: Record<string, any> | null
  created_at?: string
  /**
   * 这一轮最后一次落库的时刻（UTC，后端 TurnOut）。后端判「建图断了」按它算
   * （conversations.BUILD_STALE），前端判断同一件事时用同一只钟。老后端没有
   */
  updated_at?: string
  /** 这一轮在服务端的任务（问数据整轮在服务端跑，backend/app/chat/job.job_view）。这一波之前的老轮次没有，为 null */
  job?: ChatTurnJob | null
}

/** 问数据一轮在服务端的任务现在怎样。status 用后台任务的状态词；stage 是在哪一步；attempt_seq 是这一次尝试从哪一条事件开始 */
export interface ChatTurnJob {
  status: 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled' | 'interrupted'
  stage: 'build' | 'run' | 'waiting' | 'review' | null
  mode: string
  run_id: string | null
  attempt: number
  last_seq: number
  attempt_seq: number
  error: string | null
  /** 等不及的那次复核还在后台跑 */
  late_review?: boolean
}

/**
 * Copilot 改图前后都在、而绑定的工具变了的节点或协作成员。
 * 画布上看不出来（节点还在），跑起来才发现查不了库，所以改图回执要明说
 */
export interface ToolChange {
  node_id: string
  label: string
  /** 协作成员的名字；节点本身的工具为 null */
  member: string | null
  /** 配置里的哪一项：'tools' 或 'agents[2].tools' */
  field: string
  before: string[]
  after: string[]
  added: string[]
  removed: string[]
}

/**
 * Copilot 自查（SSE op='check'）里的一条问题。新后端给对象，老会话里存的是
 * 「「node_id」message」一行字符串，两种都要认，见 CopilotCheckEntry
 */
export interface CopilotCheckIssue {
  level: 'error' | 'warning'
  node_id: string | null
  edge_id: string | null
  /** 不再以「节点 id」开头；要带节点名自己用 node_id 查 */
  message: string
  /** 出问题的配置项，比如 'tools'、'agents[1].tools'，检查器据此定位 */
  field?: string | null
  /** datasource_out_of_scope、tools_dropped 这类机器码 */
  code?: string
}

export type CopilotCheckEntry = string | CopilotCheckIssue

/** SSE 的自查操作。repairing 时带第几轮；warnings 是不挡运行的提醒（tools_dropped） */
export interface CopilotCheckOp {
  op: 'check'
  status: 'repairing' | 'passed' | 'failed' | 'error'
  issues?: CopilotCheckEntry[]
  warnings?: CopilotCheckIssue[]
  round?: number
  repaired?: number
  message?: string
  detail?: string
}

/**
 * 一次运行跑完之后的复核结论（后端 engine/review.py）。
 *
 * 「跑完了」和「答得对」是两回事：检索降级、工具报错、agent 步数用满这些事
 * 原先一件都不会进到答案里，用户拿到一个看起来很完整的结论，却无从知道它是在
 * 什么条件下得出的。复核层就是把这段补上。
 */
export interface ReviewSignal {
  kind: string
  detail: string
  /** broken = 答案不可信；degraded = 能用但有缺口 */
  severity: 'broken' | 'degraded'
  /**
   * agent 为什么提前收尾（后端 engine/guards.py）：steps / stall / budget_tokens / budget_usd / context。
   * 老运行没有。只有 steps（或者没有这个字段的老运行）放宽步数才对症
   */
  reason?: string
}

export interface ReviewResult {
  /** ok=没问题 / annotated=加了说明 / rewritten=重写过 / reverted=重写里有新数字被退回 */
  verdict: 'ok' | 'annotated' | 'rewritten' | 'reverted'
  /** 给用户看的异常说明。排在成果上方 */
  note: string
  /** 重写后的答案。null 表示沿用原答案 */
  answer: string | null
  /** 改写之前的那份。改写是有损的，得能对照原件 */
  original?: string | null
  /** 换个配置重跑一遍大概率就好了 */
  retry: boolean
  severity: 'broken' | 'degraded' | ''
  signals: ReviewSignal[]
  /**
   * 要不要带着原图重来一次、重来时交给助手的话（服务端 backend/app/chat/turn.py 按这一轮试过几次判）：要就是那句话，不要
   * 是 null。老服务端没有这个字段，问数据页照原来的规则自己判
   */
  retry_instruction?: string | null
  /** 复核这一次的用量（服务端 providers/usage.py 的汇总，没调模型时全 0）：这一轮的花费 = 助手 + 运行 + 复核 */
  usage?: {
    cost_usd?: number | null; unpriced_calls?: number; calls?: number; input_tokens?: number; output_tokens?: number
    by_model?: Record<string, { input_tokens: number; output_tokens: number; calls: number; cost_usd: number
      unpriced_calls: number }>
  }
}

// -------------------------------------------------------------------------
// 可点击证据（报告撰写节点产出的文档、证据接口）
//
// 形状照后端 engine/evidence.py 和 api/evidence.py。前端对缺字段一律宽容：接口和文档
// 是分期长出来的，老运行、别的版本的后端都可能少几个键，少了就降级显示，不白屏。
// 偏移（span、start/end）按 Unicode 码点算，不是 JS 的 UTF-16 下标。
// -------------------------------------------------------------------------

/** 一处引用解析后的结果 */
export interface EvidenceCitation {
  /** 不带前缀的引用，如 gmv、week */
  ref?: string
  /** 目录里的别名，如 m:gmv、i:week、Q1 */
  alias?: string
  /** 引文：hit 是检索快照里第几条命中，start / end 是引文在那条原文里的码点位置；分析结论的具名的数：key（[[a:A1.top_share]]） */
  locator?: { metric?: string; field?: string; row?: number; column?: string; table?: string
              hit?: number; start?: number; end?: number; key?: string }
  eid?: string
  /** metric / input / cell / table / column / quote / query */
  kind?: string
  role?: string
  status?: 'resolved' | 'unresolved' | string
  /** 解析不了的原因（人话） */
  reason?: string
  conv?: string
  value?: unknown
  rendered?: string
  /** 引文的原文出处：检索快照、文档、片段 */
  source?: EvidenceQuoteSource
  /** [[t:]] / [[c:]] 写了一个哪里都找不到的名字：可能是编造的 */
  unknown?: boolean
  /** 表结构快照不全，找不到的名字只能说核对不了 */
  unverified?: boolean
}

/** 引文出自哪：检索快照工件、知识库里的文档和片段 */
export interface EvidenceQuoteSource {
  artifact?: string
  document?: string
  chunk?: string
  title?: string
  ordinal?: number
}

/** 可点的最小片段 */
export interface EvidenceSegment {
  id: string
  /** text / number / value / entity / quote / structural */
  kind: string
  text: string
  span?: [number, number]
  /** deterministic / none / neutral，后续期还有 probabilistic、candidate */
  state?: string
  /** 带前缀的原始引用，如 m:gmv|万 */
  ref?: string
  cite?: EvidenceCitation
  strong?: boolean
  /** uncited_number / unresolved_ref / unknown_entity（可能是编造的名字）/ unverified_entity（核对不了） */
  issue?: string
  /** 实体写在反引号里：text 自带两个反引号，按行内代码画 */
  code?: boolean
  /** 系统自动链接的名字，不是写作者写的标记（不算句子的依据） */
  auto?: boolean
  /** 反引号里自动发现的可疑名字（没有 ref 时名字在这里） */
  name?: string
  /** 旧运行按数值猜的候选（state 为 candidate） */
  candidates?: EvidenceCandidate[]
}

/**
 * 旧运行（没有契约）按数值猜的一个候选：查询快照的一格，或口径卡的一个指标。
 * 只做展示，不是证据
 */
export interface EvidenceCandidate {
  kind?: 'cell' | 'metric' | string
  /** Q1.r0.gmv / m:gmv */
  ref?: string
  alias?: string
  artifact?: string
  locator?: EvidenceLocator & { metric?: string }
  eid?: string
  value?: unknown
  rendered?: string
  /** 指标名 */
  name?: string
  caliber?: string
  version?: string
  node_id?: string
  tool?: string
  /** 和答案里那个数差多少 */
  diff?: number
}

/** 旧运行的猜测：guess_sources 的输出（agentlab.guess/1） */
export interface EvidenceGuess {
  schema?: string
  mode?: string
  /** 「猜测的来源，不能当证据：…」 */
  note?: string
  markdown?: string
  segments?: EvidenceSegment[]
  stats?: { numbers?: number; guessed?: number; unguessed?: number; candidates?: number }
  /** 猜的是成果里哪个字段 */
  field?: string
}

/** 句子、列表项或表格单元格 */
export interface EvidenceUnit {
  id: string
  /** claim / connective / heading / code。确定性规则分的，不是裁判结论 */
  kind?: string
  span?: [number, number]
  cites?: string[]
  see?: EvidenceCitation[]
  segments: EvidenceSegment[]
  /** 表格单元格的位置，表头 row = -1 */
  loc?: { row: number; col: number }
  /** 列表项的缩进层级 */
  depth?: number
  /**
   * 结论句裁判的判定（四期）：只有送了裁判的候选句有。正式运行（以及交给人工审批的探索运行）里节点当场判的
   * 进封存（post_seal false）；其余探索运行里候选句先标 unjudged + reason on_demand，点开再判
   */
  verdict?: EvidenceVerdict
}

/**
 * 模型对一句结论的判定。是模型的判断，不是证据，不能被引用。
 * status 为 unjudged 时 reason 写明为什么没判：四个上限（max_claims / max_cost_usd / daily_max_usd /
 * timeout_s，rationale 以「已到上限（…）」开头）、error、format、missing、on_demand（探索运行按需）
 */
export interface EvidenceVerdict {
  /**
   * contradicted：证据和原句冲突；insufficient：证据里没有相关信息（missing 写缺的是什么）。
   * unsupported 是拆档之前的取值：旧文档、旧事件里保留原样，界面上照旧写「证据不支持」
   */
  status: 'supported' | 'partial' | 'contradicted' | 'insufficient' | 'unsupported' | 'not_a_claim' | 'unjudged' | string
  /** 理由，最多 120 字（后端在句子边界截断，加「…」） */
  rationale?: string
  /** insufficient 时缺的是什么：「SQL」「字段清单」「取数的查询」…，由裁判给出 */
  missing?: string
  /** 按哪一版裁判规则判的（新判的都带；拆档之前判的没有） */
  rule_version?: number
  /** 判定自己带着的模型提醒（有的话盖过报告、答复、证据图里的） */
  same_model?: boolean
  priced?: boolean | null
  /** 裁判模型 id；探索运行还没判的是 null */
  judge?: string | null
  /** 封存之后按需追加的（evidence.judged 事件） */
  post_seal?: boolean
  /** 裁判看过、摘录里真有的证据编号 */
  used?: string[]
  reason?: string
  cost_usd?: number
}

/** 文档（和 report.checked、节点产出）里的裁判摘要：键的顺序同后端 judge.SUMMARY_KEYS */
export interface EvidenceJudgeSummary {
  /** inline：节点里当场判（正式运行，以及交给人工审批的探索运行）；on_demand：其余探索运行按需 */
  mode?: 'inline' | 'on_demand' | string
  model?: string | null
  on_unsupported?: 'degrade' | 'withhold' | string
  rewrite_once?: boolean
  limits?: { max_claims?: number | null; max_cost_usd?: number | null; timeout_s?: number | null
             daily_max_usd?: number | null } | null
  candidates?: number
  /** 预筛放掉、没送裁判的结论句 */
  screened?: string[]
  counts?: Partial<Record<'supported' | 'partial' | 'contradicted' | 'insufficient' | 'unsupported' | 'not_a_claim'
    | 'unjudged', number>>
  unjudged?: Record<string, number>
  limits_hit?: string[]
  complete?: boolean
  priced?: boolean | null
  cost_usd?: number
  calls?: number
  reused?: number
  duration_ms?: number
  gaps?: string[]
  notes?: string[]
  same_model?: boolean
  /** 撰写这份报告实际用的模型 id（裁判模型和它相同时 same_model 为真） */
  writer_model?: string | null
  /**
   * 不支持的句子交回写作者改写一次（rewrite_once）。units：交回的句子在封存文档里的编号（采用了改写稿时，
   * 改掉的句子是 null）；sentences：交回的原句；changed：改写稿里新写的句子的编号（没采用时为空）；
   * reason：没采用的原因
   */
  rewrite?: { units?: (string | null)[]; sentences?: string[]; applied?: boolean; reason?: string | null
              changed?: string[] } | null
}

/**
 * POST /runs/{id}/evidence/judge 的答复：evidence.judged 事件的载荷（NOTES-A4 §8）。前端对缺字段宽容：
 * verdicts 也认成 [{unit, …}] 的列表
 */
export interface EvidenceJudgeResult {
  /** 判的是哪份报告：{node_id, doc_artifact}（事件载荷里是节点 id 字符串） */
  report?: string | { node_id?: string; doc_artifact?: string }
  doc_artifact?: string
  verdicts?: Record<string, EvidenceVerdict> | (EvidenceVerdict & { unit?: string })[]
  model?: string | null
  cost_usd?: number
  calls?: number
  limits_hit?: string[]
  gaps?: string[]
  notes?: string[]
  skipped?: Record<string, string>
  post_seal?: boolean
  /** 触顶、没跑成、点的不是结论句时的一句话；判成了是 null */
  message?: string | null
  /** 触顶时怎么调，一个上限一句 */
  adjust?: string[]
  /** 这一次裁判模型和写作模型相同、模型在不在价格表里、写作模型 id */
  same_model?: boolean
  priced?: boolean | null
  writer_model?: string | null
  [key: string]: unknown
}

/** 证据图 reports[].judge_meta：这份报告最近一次按需裁判用的模型 */
export interface EvidenceJudgeMeta {
  model?: string | null
  same_model?: boolean
  priced?: boolean | null
  writer_model?: string | null
}

/** 这句能不能「请模型判断」：片段接口按运行的实际情况答（和按需裁判接口同一套条件） */
export interface EvidenceOnDemand {
  available?: boolean
  /**
   * formal / legacy / not_a_claim / judged / unsealed / seal_broken；outdated 是封存后追加的判定早于当前的裁判规则
   * （available 为真，照常给按钮）
   */
  reason?: string | null
  message?: string | null
}

export interface EvidenceBlock {
  id: string
  /** heading / paragraph / list / table / quote / code / hr */
  type: string
  level?: number
  ordered?: boolean
  start?: number
  lang?: string
  units: EvidenceUnit[]
}

export interface EvidenceViolation {
  /**
   * uncited_number / unresolved_ref / render_mismatch / eid_mismatch / …；分析能力一轮的说法违规：analysis_claim_uncited
   * （判断词未挂分析结论）、analysis_claim_mismatch（判断与分析结论不符）、causal_unsupported（因果说法没有依据）
   */
  code: string
  /** 说法违规：判断词的类（source、anomaly、causal……）、要挂的算子、所挂的分析结论编号 */
  claim?: string
  op?: string
  analyses?: string[]
  message?: string
  span?: [number, number]
  text?: string
  /** 指向的片段。结构片段（列表序号、代码围栏标签）里的数字没有可画线的文字，只能在清单里找 */
  segment?: string
  unit?: string
  ref?: string
  context?: string
}

export interface EvidenceStats {
  /** 说法违规几处（只有记了分析说法核对的文档有） */
  analysis_claims?: number
  units?: number
  segments?: number
  claims?: number
  connective?: number
  numbers?: number
  numbers_cited?: number
  values?: number
  uncited_numbers?: number
  unresolved?: number
  see?: number
  uncited_claims?: number
  violations?: number
  /** 三期：有出处的实体、引文片段数；可疑实体、核对不了的名字数。老文档没有这几个键，缺省当 0 */
  entities?: number
  quotes?: number
  unknown_entities?: number
  unverified_entities?: number
  /** 四期：claims 为 judge 时追加，候选句按判定的句数（unsupported 是拆档之前的取值，旧文档里才有） */
  supported?: number
  partial?: number
  contradicted?: number
  insufficient?: number
  unsupported?: number
  not_a_claim?: number
  unjudged?: number
}

/** report_doc 工件的内容 */
export interface EvidenceDocData {
  schema?: string
  run_id?: string | null
  node_id?: string
  /** 渲染后的全文（真实数字，不含标记） */
  markdown?: string
  /** 建文档时的完整目录：alias → 条目 */
  catalog?: Record<string, Record<string, any>>
  blocks: EvidenceBlock[]
  stats?: EvidenceStats
  violations?: EvidenceViolation[]
  /** 四期：写作时结论句策略是 judge 才有 */
  judge?: EvidenceJudgeSummary
  /** 分析能力一轮：报告节点核分析说法时记下的处置（check / strict）和说法表版本；老文档没有 */
  analysis_claims?: { mode?: string; lexicon?: number }
  /** 系统写的「分析范围」：这次有分析结论、报告节点没关掉时才有 */
  analysis_scope?: AnalysisScope
}

/**
 * 成果上的标注：这几个字段逐字等于某个报告撰写节点的文档，可以逐段点开看证据。
 * 契约 report_from 指着的那份在最外层；另有报告也被原样放进成果的，列在 others 里
 */
export interface EvidenceFieldRef {
  report_node?: string
  doc_artifact?: string
  fields?: string[]
  others?: EvidenceFieldRef[]
}

/** 封存状态 */
export interface EvidenceSeal {
  sealed?: boolean
  ok?: boolean | null
  /** 这件证据在不在封存范围内 */
  covered?: boolean
  manifest_seq?: number
  legacy?: boolean
}

/** GET /runs/{id}/evidence：整次运行的证据图 */
export interface EvidenceGraph {
  run_id?: string
  schema?: string
  /** cited / legacy_contract / legacy_text / none */
  mode?: string
  /** 没有报告时为什么（none）、旧版出具怎么认的（legacy_*）：一句人话 */
  note?: string
  /**
   * legacy_contract：{note, tier, matched, unmatched, field}，按旧契约的位置标出的数字；
   * legacy_text：guess_sources 的输出（EvidenceGuess），可能按字段分成几份
   */
  legacy?: Record<string, any> | Record<string, any>[] | null
  /** legacy_text 另一种放法：猜测单独放在这里 */
  guess?: EvidenceGuess | EvidenceGuess[] | Record<string, EvidenceGuess> | null
  seal?: EvidenceSeal
  reports?: { node_id?: string; doc_artifact?: string; doc_sealed?: boolean; fields?: string[]; stats?: EvidenceStats
              /** 文档取回时哈希复验：false 对不上（或不是这次运行这个节点写的），null 文件不在了 */
              hash_ok?: boolean | null
              /** 写这份报告时的结论句策略（report.checked 里记的；老后端、升级前的运行没有） */
              claims?: string | null
              /**
               * 四期：封存之后按需追加的判定（evidence.judged 叠在一起），{unit: 判定}。后端没给时前端只认
               * 点开时片段接口、按需裁判接口答的那几句
               */
              post_seal_verdicts?: Record<string, EvidenceVerdict> | null
              /** 封存的裁判摘要（文档的 judge） */
              judge?: EvidenceJudgeSummary | null
              /** 最近一次按需裁判用的模型：和写作模型相同没有、在不在价格表里 */
              judge_meta?: EvidenceJudgeMeta | null
              /**
               * 期 4：被反方审过的句子 → 判断（_challenge_verdicts，和片段接口的 unit.challenge 同一个读法，每句的判断
               * 一字不差）。正文据此给被审过的句子挂句末标记、点开整句面板。一句都没审、文档读不出来、老服务端都没有这个键
               */
              challenge_verdicts?: EvidenceChallengeVerdicts }[]
  evidence?: { alias?: string; eid?: string; kind?: string; label?: string; node_id?: string; artifact?: string
               sealed?: boolean; cited_by?: string[]; report?: string }[]
  /** cites（片段 → 证据）、supports（句子 → 依据）、derived_from（分析结论 → 它的输入 Q、下钻的上一层 A）；report 是哪份报告的边 */
  edges?: { from: string; to: string; rel: string; report?: string }[]
}

/**
 * 查询快照里的位置：单元格 {row, column}；agent 的数组字段按行映射时是 {rows: [首, 尾], column | columns}
 * （columns 是「字段 → 列」）。行号从 0 数
 */
export interface EvidenceLocator {
  row?: number
  column?: string
  rows?: [number, number] | number[]
  columns?: Record<string, string>
}

/** 指标的一个输入：值从哪来 */
export interface EvidenceInput {
  path?: string
  value?: unknown
  node_id?: string
  /**
   * 一期：input / transform / agent / code / tool / llm …（产出节点的类型）；
   * 二期能追到查询快照那一格的两种：agent_field（agent 开了 cite_fields 的字段）、tool_cell（cell() 取数）
   */
  via?: string
  field?: string
  /** 只有 code 节点有：source 取数 / compute 计算（缺省） */
  role?: string
  /**
   * 一期 ok / missing；agent_field、tool_cell 是核对状态：verified 与快照一致、mismatch 对不上、
   * unresolved 核对不了、missing 模型照实说没查到（from 为 null）
   */
  status?: string
  /** agent 字段的出处，agent 节点内的编号（Q1.r0.gmv）。和报告目录的全局编号不是一回事，靠 artifact 对应 */
  ref?: string | null
  /** 查询快照的工件 id：跳到哪一个查询步骤按它认 */
  artifact?: string
  locator?: EvidenceLocator
  eid?: string
  /** agent_field mismatch：模型报的值（value 是快照里的） */
  model_value?: unknown
  /** tool_cell mismatch：快照里的值（value 是算的时候用的） */
  snapshot_value?: unknown
  /**
   * tool_cell：按位置取的格（vars.q.rows[0][0]）穿过了「只是把调用工具节点的结果原样按 JSON 解析」的整形节点，这是那个
   * 节点的 id；through_label 是它在图里的名字（证据接口补的）。cell() 取的格没有这两个键
   */
  through?: string | null
  through_label?: string
  /** unresolved 的原因（人话） */
  reason?: string
  /** 输入对到的查询在报告目录里的编号（Q3）：接口按工件补的全局编号 */
  query?: string | null
  /** 输入落在哪一格，全局编号（Q3.r5.amount） */
  cell?: string
  /** agent 的数组字段：引用的行段到了截断查询结果的末行，后面还有没取回的行（query 步骤上是快照本身截断了） */
  truncated?: boolean | null
  /**
   * 期 4：取自数据源设置了遮罩的列（_withheld）：服务端已把值换成「已遮罩」、拿掉 model_value / snapshot_value，这里写明
   * 是哪几列。没遮的没有这个键
   */
  masked?: string[]
  /**
   * 期 4：遮没遮核对不了（查询快照、取值链上的产出读不出来）：值同样换成「已遮罩」，这是原因（人话，服务端写好的一句）。
   * 不进 masked：面板底下「这些列设置了遮罩」不把它们算进去
   */
  mask_unverified?: string
  /**
   * via 为 metric、转抄另一张口径卡的指标（nodes.<卡>.metrics[i].value）时，运行时跨卡往下追的出处：那个指标的 id、那张卡的
   * 指标集工件、转抄了几层、那个指标的输入是不是都追到了原始数据（服务端 engine/lineage.metric_copy）。老运行、别的输入没有
   */
  upstream?: EvidenceUpstreamRef | null
  /**
   * 子工作流（docs/design/orchestration-round/00-总方案.md §2）：读子工作流出口的字段、接上子图里那一格的出处时，经过的子工作流
   * 节点和出口字段（subgraph、field）；node_id 落在子工作流里（「子工作流节点 id/…」）时证据接口另给图上的名字
   * （node_label、subgraph_label：「子工作流 › 节点」），画布、记录页认不出这个 id 时照它写。via 为 subgraph_input：停在
   * 子工作流的入口（子图的运行输入不是父图的原始数据）
   */
  subgraph?: string
  node_label?: string
  subgraph_label?: string
}

/** 转抄的输入跨卡往下追的出处（EvidenceInput.upstream） */
export interface EvidenceUpstreamRef {
  metric?: string
  artifact?: string | null
  depth?: number
  traced?: boolean
}

// ---------------------------------------------------------------------------
// 期 4：证据接口里的核查状态（api/evidence.py）。是核查，不是证据：没核查过的指标、句子不带这些键。形状照服务端的
// 真实输出逐字核对过，前端认的时候仍按「认不出就不画」写（run/EvidencePanel.tsx 的 dualCheckOf / challengeOf）
// ---------------------------------------------------------------------------

/** 双盲复算跳过一个指标的原因（_not_checked）：关闭了；这个指标没有来自查询的输入；不在复算范围内（或值不是数） */
export type EvidenceDualCheckSkip = 'disabled' | 'no_inputs' | 'not_targeted'

/**
 * 指标步骤上的双盲复算状态（_dual_check_of / _dual_status）。没有双盲复算复核过这份指标集时指标步骤没有 dual_check。
 * 产出读不出来、退回台账条目时只有 status、node_id 和 choice
 */
export interface EvidenceDualCheck {
  /** agreed 与盲算一致；disagreed 不一致；unchecked 未能完成（盲算触顶、出错，或输入没法单独复算）；skipped 没复算这个指标 */
  status: 'agreed' | 'disagreed' | 'unchecked' | 'skipped'
  /** 双盲复算节点 */
  node_id: string
  /** 只有 disagreed：审核人的选择（a 采用原流程、b 采用盲算、neither 两边都不对）。没选的没有 */
  choice?: DualCheckChoice
  /** 只有 agreed / disagreed：盲算值，服务端按口径卡的格式渲染好的 */
  blind_rendered?: string
  /** unchecked：给人看的原因；skipped：EvidenceDualCheckSkip 里的代码（界面认不出的代码不显示） */
  reason?: string
}

/**
 * 一份报告里被反方审过的句子 → 判断（证据图 reports[].challenge_verdicts，_challenge_verdicts）。只有被审过的句子；判断和
 * 点开这一句时片段接口答的 unit.challenge.verdict 一字不差。正文据此挂句末标记，证据面板在片段接口答回来之前先按它写判断
 */
export type EvidenceChallengeVerdicts = Record<string, ChallengeVerdict | (string & {})>

/** 句子上的反方审稿判断（_challenge_of）：片段接口答的 unit.challenge。没被反方审过的句子没有这个键 */
export interface EvidenceUnitChallenge {
  /** 这一句的判断（反方模型给的，不是系统核对） */
  verdict: ChallengeVerdict | (string & {})
  /** 反方审稿节点（几个都审了这一句时取最后跑完的那个） */
  node_id: string
  /** 审稿记录（challenge_artifact）。服务端保存失败时为 null：判断照样有，理由和查询看不了 */
  artifact: string | null
  /** 实际生效的处置：degrade 被推翻的计入出具缺口；flag 只标注；fail 节点报错、运行停了 */
  on_refuted: 'degrade' | 'flag' | 'fail'
  /** 报告撰写节点的名字（画布上的标题，取不到时是节点 id） */
  report_label: string
  /** 这次审稿四种判断各几句：整份报告的（节点产出里的那一份），不是这一句的 */
  counts: ChallengeCounts
  /** 没能反查的句数（都记为无法判断，不会多于 counts.inconclusive）。节点产出里有才带 */
  unreviewed?: number
}

/** 口径卡钉在另一个已发布工作流某个版本里的口径卡上 */
export interface EvidenceCaliberSource {
  workflow_id?: string
  workflow_version?: number | string
  node_id?: string
  /** 接口顺手给的工作流名；没给时前端按工作流目录找 */
  workflow_name?: string
}

/** 口径卡上游有新版本时声明的处置（和子工作流的升版处置同一套） */
export interface EvidenceCaliberUpgrade {
  node_id?: string
  workflow_id?: string
  pinned?: number
  latest?: number
  /** recompute / dual / incomparable */
  policy?: string
  policy_label?: string
}

/**
 * 片段证据链的一步：metric（指标）、input（指标的一个输入，也可能挂在 metric.inputs 里）、
 * run_input（报告直接引用的运行输入）、query（查询快照：被引用的行加前后各 2 行）。
 * input 步骤同时带着 EvidenceInput 的字段（via、status、model_value、ref、locator、artifact）
 */
/** 合并查询的一个输入（证据面板的 merge.inputs） */
export interface EvidenceMergeInput {
  /** 合并 SQL 里的表名 */
  alias: string
  node_id?: string | null
  /** 节点在画布上的名字 */
  label?: string | null
  /** 这个输入在报告目录里的编号（Q1）；不在这份报告的目录里时为空 */
  query?: string | null
  rows?: number | null
  /** 数据源名；输入本身是合并结果时是「合并查询」 */
  source?: string | null
  artifact?: string | null
  sealed?: boolean
  /** 这个输入查询对照数据目录查出的问题（形状同查询步骤的 checks）。没查出问题、快照读不出来时没有这个键 */
  checks?: SqlCheckItem[]
}

/**
 * 出具声明（output._issuance、issuance 事件）里的 sql_checks：没通过 SQL 检查的查询，一条一个。报告页、出具横幅据此
 * 在显眼处说「因为 SQL 检查没通过而降档」。gap 是 gaps 里对应的那一句（单列之后不在其余缺口里重复）
 */
export interface IssuanceSqlCheck {
  /** 「查询「取数」（Q1）」；给不出时没有 */
  query?: string
  node_id?: string
  /** 每条问题那半句 */
  problems?: string[]
  /** 受影响的引用：「指标「订单金额」」「Q1 第 1 行「gmv」」 */
  refs?: string[]
  gap?: string
}

/** 查询用到的一张表、查询当时它的数据目录版本 */
export interface EvidenceCatalogVersion {
  /** 表结构里的表名 */
  table: string
  /** 目录里的中文名 */
  label?: string
  version?: number | null
}

/** 被引用的一格追到了哪个输入的哪一格；追不到时 input 为空，note 说明只有表级来历 */
export interface EvidenceMergeTrace {
  /** 合并结果里的 [行, 列]，行号从 0 数 */
  cell: [number, string]
  input: string | null
  query: string | null
  row: number | null
  column: string | null
  note?: string
}

export interface EvidenceMerge {
  sql?: string | null
  inputs: EvidenceMergeInput[]
  warnings: { code?: string | null; message: string }[]
  traced: EvidenceMergeTrace[]
}

/** 指标的一个输入追不到原始数据：出处追到哪个节点为止。认不出是哪个节点时 node_id、label 为 null */
/** 查询区间里这张表没有数据的那几列（服务端 data/coverage.result_gaps） */
export interface EvidenceNoData {
  columns: string[]
  table?: string
  column?: string
  /** 查的区间（按天，两头都含），没有限制的那一头为 null */
  window?: (string | null)[]
  /** 表里这一列的范围；表里一个值都没有时为 null */
  data_range?: (string | null)[] | null
  /** live 现查；profile / observed 现查不成，按剖析、取值观察 */
  basis?: string
  basis_at?: string
  message: string
}

export interface EvidenceUntraced {
  path: string
  node_id: string | null
  /** 封存的图里那个节点的名字 */
  label: string | null
  /** 节点类型（transform、code、llm……） */
  type: string | null
}

// ---------------------------------------------------------------------------
// 分析能力一轮（docs/design/analysis-round）：分析结论在证据里的样子。形状照服务端 api/evidence.py 的 _analysis_chain、
// _comparability_view，报告文档的 analysis_scope（analysis.contract.ScopeBlock），出具声明的 analysis_claims / comparability /
// untraced（engine/nodes/io.py）。判定语、判定标准、原因、附带说明、代入式、闭合核对的数都是服务端写好的字，界面照原样显示
// ---------------------------------------------------------------------------

/** 分析结论的判定：判定码、点名的段（一段一个列表，多维时几个值；乘积拆解是因子名）、方向 */
export interface AnalysisVerdict {
  code?: string
  subjects?: (string | number | null)[][]
  direction?: 'up' | 'down' | null
}

/** 附带说明：一种说法，服务端渲染好的一句 */
export interface AnalysisCaveat { code?: string; text?: string }

/** 可比性检查现查的一条：一列的实际范围（table、column、min、max），或按运行当天现算的界（expr、value） */
export interface AnalysisProbe {
  source?: string
  table?: string
  column?: string
  min?: string | null
  max?: string | null
  basis?: 'live' | 'profile' | 'observed' | string
  at?: string
  expr?: string
  value?: string | null
}

/**
 * 出处链里分析结论的六步（step 依次是 analysis、analysis_method、analysis_calc、analysis_input（每份输入一步）、
 * analysis_recompute、analysis_seal）共用的形状：每一步只带自己那几项
 */
export interface EvidenceAnalysisStep {
  step: string
  alias?: string
  // ---- analysis：判定 ----
  op?: string
  mode?: string | null
  /** 「变化拆解（可加）」：服务端 contract.method_label */
  method_label?: string
  /** card 分析卡、agent Agent 现场做的、metric 口径卡执行时自动做的可比性检查 */
  origin?: 'card' | 'agent' | 'metric' | string
  item?: string
  call_id?: string
  node_id?: string | null
  label?: string | null
  artifact?: string | null
  eid?: string
  eid_ok?: boolean
  /** 这一处引用的是结论的哪一项：判定语、具名的数（key）、结果表的一格（row、column；column_label 是结果表的列名，给人看的） */
  cited?: {
    what?: 'phrase' | 'value' | 'cell' | string
    key?: string
    row?: number
    column?: string
    column_label?: string | null
    raw?: unknown
    conv?: string
  }
  rendered?: string
  render_ok?: boolean
  hash_ok?: boolean | null
  status?: string
  reason_code?: string | null
  reason?: string | null
  phrase?: string
  criterion?: string
  verdict?: AnalysisVerdict | null
  caveats?: AnalysisCaveat[]
  hypothesis?: string
  /** 「在验证什么」那一行的说法：谁写的照实说，服务端按台账条目给（Agent 写的假设 / 分析卡上写的『在验证什么』） */
  hypothesis_label?: string
  hypothesis_note?: string
  note?: string
  // ---- analysis_method：方法、参数、实际用的阈值、现查结果 ----
  method?: string
  params?: Record<string, unknown>
  settings?: { key: string; label?: string; value: unknown }[]
  probes?: AnalysisProbe[]
  // ---- analysis_calc：具名的数、代入式、结果表 ----
  values?: { key: string; raw?: unknown; rendered?: string; cited?: boolean }[]
  formulas?: { label?: string; text?: string }[]
  table?: {
    columns: string[]
    labels?: Record<string, string>
    total_rows?: number
    row_index?: number[]
    rows: unknown[][]
    masked?: string[]
    highlight?: { cells?: [number, string][] }
    window_truncated?: boolean
  }
  // ---- analysis_input：一份输入 ----
  /** 这一步是哪份结论的输入 */
  of?: string
  ref?: string
  role?: string
  role_label?: string
  columns?: string[]
  rows?: 'all' | number[]
  row?: number
  column?: string
  value?: string | null
  /** 那一格的值按服务端的规则渲染出来的字（render_cell：千分位、NULL 写「—」），和闭合核对里的写法一致 */
  value_rendered?: string
  /** 输入落到报告目录的哪个 Q */
  query?: string | null
  sealed?: boolean
  /** headline 那一格和结论里总数的闭合核对：mode 可加对各段之和，比率对各段分子之和 ÷ 分母之和 */
  closure?: { mode?: string; total_key?: string; total?: string; headline?: string; closed?: boolean }
  // ---- analysis_recompute：复算（服务端算好的那一句） ----
  text?: string
  // ---- analysis_seal：封存 ----
  ledger?: boolean
  /** metric_set：口径卡指标上的可比性结论，记在指标集里、随卡封存 */
  via?: string
}

/** 指标步骤上的两期可比性（api/evidence._comparability_view）：判定、判定语、原因，连同那份可比性结论的出处链 */
export interface EvidenceComparability {
  verdict?: 'comparable' | 'conditional' | 'incomparable' | string
  phrase?: string
  reasons?: string[]
  artifact?: string | null
  hash_ok?: boolean | null
  sealed?: boolean
  method?: string
  criterion?: string
  caveats?: AnalysisCaveat[]
  probes?: AnalysisProbe[]
  /** 判定 → 方法 → 计算 → 输入 → 复算 → 封存（两份输入快照的查询步骤指标链里已经有了，不再给） */
  steps?: EvidenceAnalysisStep[]
}

/** 报告文档里系统写的「分析范围」的一条（contract.ScopeItem） */
export interface AnalysisScopeItem {
  alias?: string
  op?: string
  mode?: string | null
  /** 拆解的维度（给人看的叫法） */
  dims?: string[]
  verdict?: string | null
  phrase?: string
  /** 下钻：上一层的编号 */
  parent?: string | null
  reason?: string | null
}

/** 报告文档的 analysis_scope（contract.ScopeBlock）：不进正文、不过裸数字和说法核对，随文档封存 */
export interface AnalysisScope {
  phenomena?: AnalysisScopeItem[]
  decomposed?: AnalysisScopeItem[]
  excluded?: AnalysisScopeItem[]
  refused?: AnalysisScopeItem[]
  /** 候选维度里没拆过的叫法；null 是候选维度核对不了（看 note） */
  not_decomposed?: string[] | null
  note?: string | null
  /** 这次做了几次差异检验 */
  tests?: number
  /** 检验校正过没有：只做了一次为 true，不止一次为 false，没做为 null */
  corrected?: boolean | null
}

/** 出具声明的 analysis_claims：处置、几处、记没记缺口、按种类的计数、前几处（同报告文档的说法违规） */
export interface IssuanceAnalysisClaims {
  mode?: 'check' | 'strict' | string
  count?: number
  counts?: Record<string, number>
  counted?: boolean
  violations?: EvidenceViolation[]
}

/** 出具声明的 comparability：两期有条件可比、不可比的指标，一条一个 */
export interface IssuanceComparability {
  metric?: string
  name?: string
  verdict?: string
  phrase?: string
  reasons?: string[]
  artifact?: string
}

/** 出具声明的 untraced：报告引用的指标里输入追不到原始数据的，counted 是记了缺口（受管级别的正式运行） */
export interface IssuanceUntraced {
  metrics?: { metric?: string; name?: string; stops?: { path?: string; node_id?: string | null; label?: string | null; type?: string | null }[] }[]
  counted?: boolean
}

/** Agent 分析工具 tool.end 的 analysis（服务端 tools/analysis.event_view）：preview 只是结论的前一截，判定语从这里读 */
export interface AnalysisEventView {
  /** 这份结论在本节点的编号（「【分析 An】」那个）；不记台账的执行没有 */
  alias?: string | null
  op?: string
  mode?: string | null
  status?: 'ok' | 'refused' | string
  verdict?: string | null
  direction?: string | null
  phrase?: string
  reason_code?: string | null
}

/** 分析卡的一项（节点配置 items[i]，engine/schema.analysis_issues 校验） */
export interface AnalysisItem {
  id?: string
  op?: string
  mode?: string | null
  /** 要分析的上游查询节点（调用数据库查询工具的「调用工具」节点，或「合并查询」）；两份查询时写在 params 的 base_query、target_query */
  from?: string
  params?: Record<string, any>
  hypothesis?: string
}

export interface EvidenceStep extends Omit<EvidenceInput, 'status'> {
  step: string
  /**
   * upstream：转抄另一张口径卡的指标时跨卡接上的那一步（api/evidence._upstream_steps）。of 是接在哪个输入后面（输入的路径），
   * label 是那张卡在图里的名字，traced 是那个指标的输入都追到了原始数据，depth 是转抄了几层
   */
  of?: string
  label?: string | null
  traced?: boolean
  depth?: number
  metric?: string
  decimals?: number | null
  format?: string
  conv?: string | null
  eid?: string
  /** eid 能由工件和定位重算出来 */
  eid_ok?: boolean
  /** 工件取回时哈希复验通过、指标在卡里 */
  hash_ok?: boolean
  /** 卡里的值按同样的格式渲染出来就是报告上的字 */
  render_ok?: boolean
  /** 这件证据在封存范围内 */
  sealed?: boolean
  alias?: string
  name?: string
  value?: unknown
  unit?: string
  rendered?: string
  caliber?: string
  version?: string
  node_id?: string
  artifact?: string
  expression?: string
  substituted?: string
  recompute_ok?: boolean | null
  status?: string
  /** metric：表达式把截断的查询结果当成整组用了（计数、求和……），值只算到了取回的那部分 */
  incomplete?: boolean
  /** metric：不完整的原因（人话，「基于被截断的查询结果计算（只取回了前 1000 行），结果不完整」） */
  incomplete_reason?: string
  /** metric：所依据的查询没通过 SQL 检查（有错误级的问题），值照算，出具已按缺口降档 */
  sql_check_failed?: boolean
  /** metric：没通过的原因（人话，「所依据的查询未通过 SQL 检查（…），结果不可靠」） */
  sql_check_reason?: string
  /** metric：没有值，不是缺输入，是输入都齐、计算式自己算不出来（分母为 0）。状态仍是 missing_input */
  undefined?: boolean
  /**
   * metric：输入取自「查询区间里这张表没有数据」的列，值照算，出具按缺口降档（true）；
   * query：这次查询里这样的几列（服务端 data/coverage.py，查询时记进快照）。没有问题时没有这个键
   */
  no_data?: boolean | EvidenceNoData[]
  /** metric：没有数据的原因（人话，「所依据的查询区间里这张表没有数据：…」） */
  no_data_reason?: string
  /** metric（期 4）：这个指标的双盲复算状态。没有双盲复算复核过这份指标集时没有这个键 */
  dual_check?: EvidenceDualCheck
  /**
   * metric：输入里追不到原始数据（查询快照里的格、运行输入）的，空数组是都追到了；卡上没有输入、老服务端没有这个键。
   * 和「有出处」（口径卡确定性复算一致）是两件事，面板分开说（服务端 engine/lineage.py）
   */
  untraced?: EvidenceUntraced[]
  /** query：这次查询对照数据目录查出的问题。没查出问题时没有这个键 */
  checks?: SqlCheckItem[]
  /** query：查询当时冻结的表结构快照（工件 id）。合并查询、老快照没有 */
  schema_artifact?: string
  /** query：这条查询用到的表在表结构快照里冻结的数据目录版本（SQL 检查对照的那一版）。没有目录时没有这个键 */
  catalog?: EvidenceCatalogVersion[]
  inputs?: EvidenceInput[]
  /** 口径卡钉在哪个工作流的哪一版（metric；方案第 5 节的写法，接口实际给在 source 上） */
  caliber_from?: EvidenceCaliberSource | null
  /** 上游有新版本时的处置（metric）；没有升版是 null */
  caliber_upgrade?: EvidenceCaliberUpgrade | null
  // ---- query：查询快照的一个窗口 ----
  tool?: string
  /** query：数据源名；metric：口径卡钉住的来源 {workflow_id, workflow_version, node_id, workflow_name} */
  source?: string | EvidenceCaliberSource | null
  sql?: string
  columns?: string[]
  /** 只有被引用的行加前后各 2 行；遮罩列的值已经换成「已遮罩」 */
  rows?: unknown[][]
  /** rows[0] 在快照里是第几行（从 0 数） */
  row_offset?: number
  /** rows 里每一行在快照里是第几行：被引用的行隔得远时窗口不连续，按它认 */
  row_index?: number[]
  /** 快照一共几行 */
  total_rows?: number | null
  /** 查询撞了行数上限，库里还有更多 */
  truncated?: boolean | null
  /** 被引用的行太多，窗口只给了前面一截 */
  window_truncated?: boolean
  /** 被引用的行（快照里的行号）和列；cells 是精确到格的 [行, 列]，有它就只高亮这几格 */
  highlight?: { rows?: number[]; cols?: string[]; cells?: [number, string][] }
  /** 这一步里被遮罩的列 */
  masked?: string[]
  /** 这一步为什么没有行（快照不在封存范围里、哈希对不上、取不回来） */
  note?: string
  /** 数据源改名或删掉了、按查询当时记下的遮罩处理时的那句说明。行照样有 */
  mask_note?: string
  /**
   * 期 4：可以请求推断来源（GET …/segments/{sid}/provenance）。只有带文档标记的报告、单元格片段的查询步骤、
   * 查询快照来自上传的表格时才有，且恒为 true；其余一个键都不加。前端只在 seg.cite?.kind === 'cell' 且它为 true 时请求
   */
  provenance?: boolean
  /** 合并查询的结果（快照的 source 是「合并查询」）：合并了哪几个输入、合并 SQL、执行时的警告、被引用的格追到哪 */
  merge?: EvidenceMerge
  /** 这一步是哪次合并查询的输入（合并结果在目录里的编号）：排在那个合并步骤后面，高亮的是追到的格 */
  merged_into?: string
  /** query：这一步是哪份分析结论的输入（结论在目录里的编号 A…）：接在那份结论的输入后面 */
  input_of?: string
  /** metric：跨两份同形查询算的环比、同比，口径卡执行时自动做的可比性检查。没做过检查的指标没有这个键 */
  comparability?: EvidenceComparability
  // ---- entity：表或字段（三期）----
  /** entity：table / column */
  kind?: string
  table?: string
  column?: string
  /** 字段类型（表结构快照里记的） */
  type?: string
  /** 同名字段在好几张表里时，是哪几张 */
  tables?: string[]
  /** 这个名字的来历：表结构快照、查询 SQL、查询结果列 */
  sources?: EvidenceEntitySource[]
  /** 出现在哪几次查询里（报告目录的全局编号） */
  queries?: string[]
  /** 表结构快照什么时候同步的 */
  synced_at?: string
  /** 可疑实体：最接近的已知名字 */
  closest?: (string | { alias?: string; name?: string; table?: string; kind?: string })[]
  /** 可疑实体：查过几份表结构快照、几次查询 */
  checked?: { schemas?: number; queries?: number }
  /** 表结构快照只存了一部分（库里表太多） */
  snapshot_truncated?: boolean
  /** 好几张表都有的同名字段：各表的类型 */
  types?: Record<string, string>
  /** 表：字段清单和类型（封存范围内的表结构快照，最多 60 个，遮罩的列不列入）；多出来的个数 */
  fields?: { name?: string; type?: string | null }[]
  fields_more?: number
  /** 有列按遮罩没列进字段清单 */
  fields_masked?: boolean
  /** 表：几个字段、是不是视图；表或字段的注释 */
  is_view?: boolean
  comment?: string
  nullable?: boolean
  primary_key?: boolean
  // ---- quote：逐字引文（三期）----
  /** quote：引文所在那条命中的原文（也可能放在 content 里） */
  text?: string
  /** quote：引文所在那条命中的全文；快照不在封存范围里、取不回来时是 null */
  content?: string | null
  quote?: string
  match?: { hit?: number; start?: number; end?: number }
  /** quote：按记下的位置把原文切出来，和引文逐字比对的结果 */
  match_ok?: boolean | null
  /** quote：哪个知识库、检索的是什么 */
  collection?: string
  query?: string | null
}

/** 实体的一处来历 */
export interface EvidenceEntitySource {
  /** schema（表结构快照）/ sql（查询 SQL 用到的表）/ result（查询结果列） */
  kind?: string
  artifact?: string
  alias?: string
  source?: string
  truncated?: boolean
}

/** GET /runs/{id}/evidence/audit 的一行（形状照 api/evidence.py；前端经 lib/evidence 的 auditFromApi 读） */
export interface EvidenceAuditRow {
  /** cited / none / suspicious / candidate */
  group?: string
  report?: string | null
  field?: string | null
  segment?: string | null
  unit?: string | null
  /** number / value / entity / quote / claim / violation */
  kind?: string
  text?: string
  state?: string
  issue?: string | null
  ref?: string | null
  alias?: string | null
  evidence_kind?: string | null
  evidence?: string | null
  eid?: string | null
  artifact?: string | null
  node_id?: string | null
  sealed?: boolean | null
  span?: [number, number] | null
  sentence?: string
  note?: string | null
  candidates?: EvidenceCandidate[]
}

/** GET /runs/{id}/evidence/audit：记录页的审计表 */
export interface EvidenceAudit {
  run_id?: string
  schema?: string
  mode?: string
  seal?: EvidenceSeal & { events?: number; message?: string }
  reports?: { node_id?: string; doc_artifact?: string; hash_ok?: boolean | null; doc_sealed?: boolean
              fields?: string[]; claims?: string | null; stats?: EvidenceStats }[]
  groups?: { key?: string; label?: string; count?: number; rows?: EvidenceAuditRow[] }[]
  counts?: Record<string, number>
  total?: number
  note?: string
  legacy_note?: string
}

/** GET /runs/{id}/evidence/segments/{sid}：点开一个片段 */
export interface EvidenceSegmentDetail {
  report?: { node_id?: string; doc_artifact?: string }
  segment?: Partial<EvidenceSegment> & { unit?: string }
  unit?: { id?: string; kind?: string; text?: string; span?: [number, number]; cites?: string[]
          /** 这一句的判定：封存的文档里的，或者按最新的 evidence.judged 叠上的（post_seal） */
          verdict?: EvidenceVerdict
          /** 这一句能不能请模型判断、不能的话为什么 */
          on_demand?: EvidenceOnDemand
          /** 期 4：反方审稿对这一句的判断。没审到这一句的没有这个键 */
          challenge?: EvidenceUnitChallenge }
  block?: { id?: string; type?: string }
  chain?: EvidenceStep[]
  /** 片段为什么是现在这个状态，一句人话 */
  note?: string
  /** 落在这个片段（或这一句、没有片段的）上的违规 */
  violations?: EvidenceViolation[]
  seal?: EvidenceSeal
  /** 查询步骤里被遮罩的列（数据源 options.mask_columns）。遮罩只减少暴露，不是安全边界 */
  redacted?: { columns?: string[] }
  /** 可疑实体：最接近的已知名字（最多 3 个），给「是不是想写…」 */
  closest?: (string | { alias?: string; name?: string; table?: string; kind?: string })[]
  /**
   * 口径账本（next-round 02 做法 3）：这个数的口径标签和比对的来历。封存后比对，没比对过的运行、不是数的片段没有这个键
   * （老运行的返回一字不差）。形状见 typesLedger.ts
   */
  ledger?: import('./typesLedger').SegmentLedger
  /** 指标接口（/evidence/metrics/{node}/{metric}）给的展示值：遮罩的写「已遮罩」 */
  rendered?: string
}

// -------------------------------------------------------------------------
// 期 4：推断的来源（GET /runs/{id}/evidence/segments/{sid}/provenance?report=…）
// 契约照 backend/app/data/provenance_types.py（asdict 之后的 JSON，P4-SPEC 2.8.1）。这是期 4 新加的接口，
// 答复里每个键都在（值可以是 null），所以这里不写成可选；老服务端没有这个接口时回 404 且没有 code，三节都不画。
// -------------------------------------------------------------------------

/** inferred 给出格子；table_only 只给表级来历（version 非空）；none 不画，或只画一句原因 / 红色提示 */
export type ProvenanceStatus = 'inferred' | 'table_only' | 'none'

/** 不下钻的原因（provenance_types.ReasonCode）。界面不按它拼字，原样显示服务端给的 reason.text */
export type ProvenanceReasonCode =
  | 'legacy_doc' | 'not_cell' | 'not_sealed' | 'not_upload' | 'simple_upload' | 'manifest_unreadable'
  | 'chain_mismatch' | 'expression' | 'alias' | 'multi_table' | 'unparsed' | 'no_pk' | 'pk_missing' | 'masked'
  | 'null_value' | 'null_pk' | 'snapshot_gone' | 'db_tampered' | 'recheck_missing' | 'recheck_multiple'
  | 'recheck_mismatch' | 'no_lineage' | 'merge_no_lineage'

/** 标红的提示：出现时 reason.code 与它相同，界面只画提示 */
export type ProvenanceAlertCode = 'db_tampered' | 'chain_mismatch' | 'manifest_unreadable'

/** 附带的格：日期表头格、行标签、分段标题、列表头、合计标签 */
export type ProvenanceFromRole = 'axis_header' | 'row_label' | 'section_title' | 'col_header' | 'total_label'

/** 本期结论（照搬清单里 CheckResult.status） */
export type ProvenancePartStatus = 'passed' | 'mismatch' | 'unverifiable' | 'info'
/** 这一行的关系核对结果（只给关系核对） */
export type ProvenanceRowStatus = 'passed' | 'mismatch' | 'unverifiable'
/** 这一格的合计核对结果（只给 K、G、T） */
export type ProvenanceCellStatus = 'ok' | 'unverifiable' | 'unknown' | 'not_formula'

export interface ProvenanceReportRef {
  node_id: string
  doc_artifact: string
}

/** 片段本身是单元格引用就给（与 status 无关），不是时为 null */
export interface ProvenanceCellRef {
  /** 目录里的查询编号（Q3） */
  alias: string
  row: number
  column: string
  /** 查询快照的工件 id */
  artifact: string | null
}

export interface ProvenanceReason {
  code: ProvenanceReasonCode
  /** 细分，给测试和日志用，界面不显示 */
  detail: string
  /** 界面原样显示 */
  text: string
}

export interface ProvenanceAlert {
  code: ProvenanceAlertCode
  text: string
}

export interface ProvenanceTableRef {
  name: string
  kind: 'data' | 'reported_total'
}

export interface ProvenancePeriod {
  start: string
  end: string
  source: 'cells' | 'human'
  /** 解析出统计期的格子，带工作表名（「客流汇总!B2」） */
  cells: string[]
  /** 人工录入时的署名（未认证） */
  signed_by: string | null
}

/** 一条接受理由（导入清单里的，内容寻址，是当时的事实） */
export interface ProvenanceAcceptance {
  check_id: string
  title: string | null
  kind: 'override' | 'waiver'
  reason: string
  signed_by: string | null
  at: string | null
}

/** 导入记录上的当前状态（清除原件、作废接受） */
export interface ProvenanceStateNote {
  at: string | null
  signed_by: string | null
  reason: string | null
}

/** 数据版本里的一期（按统计期升序）。raw_state、purged、revoked 是当前状态，界面标「当前状态」 */
export interface ProvenancePart {
  import_id: string
  seq: number
  /** 导入清单的工件 id：「查看导入清单」按它经 /api/artifacts/{id} 取 */
  manifest: string
  /** 没有统计期时 null（「统计期未记录」） */
  period: ProvenancePeriod | null
  file_name: string | null
  raw_sha256: string | null
  /** 区域（「客流汇总!B4:AG30」，多张表用「、」连）；取不到为 null */
  region: string | null
  /** 排除的行数之和；期 3 之前的回执没有记录时为 null */
  excluded_rows: number | null
  recipe_sha256: string | null
  /** 配方第几版（当前状态）；取不到为 null */
  recipe_seq: number | null
  /** 导入时间（清单的 created_at） */
  committed_at: string | null
  /** 署名（未认证） */
  signed_by: string | null
  acceptances: ProvenanceAcceptance[]
  raw_state: 'kept' | 'purged' | 'absent' | null
  purged: ProvenanceStateNote | null
  revoked: ProvenanceStateNote | null
  /** 这一格所在的一期：inferred 时恰好一项为 true */
  has_row: boolean
}

/** 数据版本（表级来历），来自封存链上的清单，不加「推断」标注 */
export interface ProvenanceVersion {
  source: string
  snapshot_id: string
  mode: 'replace' | 'accumulate'
  union: boolean
  tables: ProvenanceTableRef[]
  /** false：数据源设有遮罩，不出「查看导入清单」 */
  manifest_view: boolean
  parts: ProvenancePart[]
}

export interface ProvenanceFromCell {
  role: ProvenanceFromRole
  /** 这一格给出的是哪一列的值；宽表指标列的行标签（指标名取自哪一格）为 null */
  column: string | null
  sheet: string
  /** 不带工作表名的坐标（「G4」） */
  cell: string
  /** 格子原文；拿不到为 null */
  text: string | null
  /** 只给分段标题：配方中的定位文字 */
  locate_title: string | null
}

export interface ProvenanceYear {
  source: 'period' | 'human'
  cells: string[]
  signed_by: string | null
  /** 这一块的日期表头有的是日期格、有的是文本，无法确定这一格属于哪一种 */
  mixed: boolean
}

/**
 * 这一行标签列（交叉表的维度、合计表的合计项）的原文与数据库里的规范写法不同时给出。被引用的是值列也给：
 * 合计表那一格是「18-22 时合计」→「18-22时合计」，全角标签那一期的值格是「８－９」→「8-9」
 */
export interface ProvenanceCanonical {
  raw: string
  canonical: string
}

export interface ProvenanceRecheck {
  /** 占位符一律是 ?，按主键的顺序与 params 一一对应 */
  sql: string
  params: unknown[]
  ok: boolean
}

/** 推断出的格子（只在 inferred 时有） */
export interface ProvenanceCellSource {
  table: string
  column: string
  column_role: 'axis' | 'dim' | 'derive' | 'const' | 'measure' | 'value' | 'text' | (string & {})
  kind: 'data' | 'reported_total'
  pk: Record<string, unknown>
  /** 快照库的 rowid（累积时是合并后的行号） */
  rowid: number
  part_seq: number
  part_rowid: number
  sheet: string
  /** 不带工作表名的坐标（「G5」） */
  cell: string
  header: string | null
  unit: string | null
  from: ProvenanceFromCell[]
  year: ProvenanceYear | null
  canonical: ProvenanceCanonical | null
  raw_purged: boolean
  /** 列表这一块按合并单元格的左上格填充 */
  merged_fill: boolean
  recheck: ProvenanceRecheck
}

/** 相关核对的一条（只在 inferred 时有） */
export interface ProvenanceCheck {
  id: string
  kind: string
  title: string
  part_status: ProvenancePartStatus
  row_status: ProvenanceRowStatus | null
  cell_status: ProvenanceCellStatus | null
  acceptance: ProvenanceAcceptance | null
  /** K 无法核对时的原因摘要（可能带数字，系统呈现） */
  detail: string | null
}

/** GET /runs/{id}/evidence/segments/{sid}/provenance：推断的来源 */
export interface EvidenceProvenance {
  schema: 'agentlab.provenance/1' | (string & {})
  report: ProvenanceReportRef
  segment: string
  cell: ProvenanceCellRef | null
  status: ProvenanceStatus
  /** status 不是 inferred 时必有 */
  reason: ProvenanceReason | null
  /** 标红；有它时不再画 reason.text */
  alert: ProvenanceAlert | null
  /** 运行已封存且封存核对通过；false 时数据版本一节加一句未封存 */
  sealed: boolean
  /** status 为 none 时为 null */
  version: ProvenanceVersion | null
  cell_source: ProvenanceCellSource | null
  checks: ProvenanceCheck[]
  /** 被引用的格在合并查询的结果里时，经过的每一次合并；别的查询为空 */
  merge: ProvenanceMergeHop[]
}

/** 经过的一次合并查询：合并结果里被引用的格追到了哪个输入的哪一格；追不到的那一跳后四项为 null */
export interface ProvenanceMergeHop {
  /** 合并结果在目录里的编号（Q3） */
  alias: string
  node_id: string | null
  /** 追到的输入别名（合并 SQL 里的表名） */
  input: string | null
  /** 那个输入在目录里的编号（Q1） */
  query: string | null
  row: number | null
  column: string | null
}

// ===========================================================================
// 业务数据目录（/api/datasources/{id}/catalog，后端 app/data/catalog.py）。
// 每张表一份业务说明：中文名、粒度、业务主键、列的含义和度量类型、表与表的关联关系……每一项都注明来源和状态。
// 目录只记数据事实，不放计算公式（公式在口径卡里）。
// ===========================================================================

/** 项的来源：数据库注释、外键约束、命名推断、数据剖析、模型起草、人工填写 */
export type CatalogSource = 'comment' | 'fk' | 'name' | 'profile' | 'llm' | 'human'
/** 项的状态：推断、已验证（外键约束、数据剖析）、已确认（人工）、已驳回（人工） */
export type CatalogStatus = 'proposed' | 'verified' | 'confirmed' | 'rejected'
/** 表类型：明细（事实）、维度、快照、日志、配置 */
export type CatalogTableKind = 'fact' | 'dimension' | 'snapshot' | 'log' | 'config'
/** 列的度量类型：可累加（流量）、存量、比率、标识、状态、属性 */
export type CatalogMeasure = 'flow' | 'stock' | 'ratio' | 'identifier' | 'status' | 'attribute'
/** 关系的基数（从本表看过去） */
export type CatalogCardinality = 'many_to_one' | 'one_to_one' | 'one_to_many'

/** 目录里的一项：值连同来源、状态 */
export interface CatalogItem<T = unknown> {
  value: T
  source: CatalogSource
  status: CatalogStatus
  /** 备注：机器写的说明（模型起草的依据、数据剖析的测量、双盲复算的出处……） */
  note?: string
  /**
   * 确认时的依据：保存修改提案（表助手、助手流里「建议更新数据目录」）时使用者确认的依据，和备注分开存。值改了换成那一次的，
   * 撤销审阅回到推断时去掉；只由服务端写，整份提交时带上也不作数
   */
  reason?: string
  updated_at?: string
}

/** 业务日期：按哪一列算，规则和时区写成文字 */
export interface CatalogBusinessDate {
  column: string
  rule?: string
  timezone?: string
}

/** 一列的目录 */
export interface CatalogColumnNotes {
  label?: CatalogItem<string>
  meaning?: CatalogItem<string>
  unit?: CatalogItem<string>
  measure?: CatalogItem<CatalogMeasure>
  /** 码值 → 含义 */
  codes?: CatalogItem<Record<string, string>>
}

/** 一条关联关系。编号由两端的表和列算出来，改了指向就是另一条 */
export interface CatalogRelation {
  id: string
  columns: string[]
  to_table: string
  to_columns: string[]
  cardinality: CatalogCardinality | null
  /** 0 到 1：本表这几列的值在被指向表里找得到的比例（数据剖析给出） */
  coverage: number | null
  source: CatalogSource
  status: CatalogStatus
  note?: string
  /** 确认时的依据（同 CatalogItem.reason） */
  reason?: string
  updated_at?: string
  /**
   * 基数是数据剖析用数据核实的（子表一侧数过是否唯一），只由剖析写。外键、命名推断的基数没有这个键。
   * 一对多关联后重复计算的检查只在它为真、或者关系人工确认过时报「错误」，否则最多是「提醒」
   */
  cardinality_checked?: boolean
}

/** 一张表的目录（notes）。字段固定，服务端不认识的一律拒收 */
export interface CatalogNotes {
  label?: CatalogItem<string>
  description?: CatalogItem<string>
  grain?: CatalogItem<string>
  keys?: CatalogItem<string[]>
  kind?: CatalogItem<CatalogTableKind>
  business_date?: CatalogItem<CatalogBusinessDate>
  /** SQL 条件片段 */
  valid_filter?: CatalogItem<string>
  dedup?: CatalogItem<string>
  columns?: Record<string, CatalogColumnNotes>
  relations?: CatalogRelation[]
}

/** 各状态的项数（表级项、列级项、关系都算），四种状态都有键 */
export type CatalogCounts = Record<CatalogStatus, number>

/** 表清单的一行。表结构里的每张表各一行（没有目录的也列）；目录还在、表已不在的 in_schema 为 false，排在最后 */
export interface CatalogTableRow {
  table_name: string
  qualified: string
  is_view: boolean
  in_schema: boolean
  /** 中文名（被驳回的不算） */
  label: string | null
  label_status: CatalogStatus | null
  kind: CatalogTableKind | null
  counts: CatalogCounts
  /** 没被驳回的关联关系条数 */
  relations: number
  /** 被运行查询过的次数（同一次运行里结果相同的重复查询只算一次） */
  usage: number
  /** 这张表还没有目录时为 0 */
  version: number
  updated_at: string | null
  updated_by: string | null
  /** 这张表最近一次起草任务里的那一项（任务还在进行就是进行中的状态）；没起草过为 null。老服务端没有这个键 */
  last_draft?: CatalogLastDraft | null
  /** 这张表最近一次剖析（任务还在进行就是进行中的状态）；没剖析过为 null。老服务端没有这个键 */
  last_profile?: CatalogLastProfile | null
  /** 按「需要剖析」的口径这张表要不要剖析（表结构里、不是视图、有可剖析的项，且满足 profile_due_reason 之一） */
  profile_due?: boolean
  /**
   * 为什么需要剖析：never 从没剖析过；unfinished 最近一次剖析没做完（部分完成、失败、已停止）；new_relations 目录里有待核实的
   * 关系不在最近一次剖析的检查项里；new_checks 最近一次剖析之后多出了码值、日期检查（某一列被记成了状态类、日期列变了）。
   * 不需要时为 null
   */
  profile_due_reason?: CatalogProfileDueReason | null
  /** 按当前目录和表结构这张表要做几项检查；0 表示没有可剖析的项（视图为 0） */
  profile_checks?: number
}

/** GET /datasources/{id}/catalog */
export interface CatalogList {
  /** 使用次数多的在前 */
  tables: CatalogTableRow[]
  /** 导入表格的源：表和列的说明由系统按核对结果生成，只读 */
  system_notes: boolean
  /** 没有表结构时的原因（「尚未探查结构」「结构探查失败：…」）；有表结构时为 null */
  schema_note: string | null
  /** 探查结构截断了（每个数据源最多取 200 张表）：没探查到的表不在清单里，助手也看不到。老后端没有这一项 */
  schema_truncated?: boolean
  /** 数据库里一共几张表（含视图）；没截断时等于探查到的张数 */
  schema_total?: number
  /** 这个数据源的起草要求（使用者补充给模型的背景和要求）；没填为 null。老服务端没有这一项 */
  guidance?: string | null
  /** 排队或进行中的起草任务（页面据此显示进度）；没有为 null。老服务端没有这一项 */
  active_job?: CatalogActiveDraftJob | null
  /** 排队或进行中的剖析任务（页面据此显示进度）；没有为 null。老服务端没有这一项 */
  active_profile_job?: CatalogActiveProfileJob | null
}

/** 表结构里的一列 */
export interface CatalogStructureColumn {
  name: string
  type: string
  pk: boolean
  not_null: boolean
  /** 数据库注释；导入表格的源是系统按核对结果生成的说明 */
  comment: string | null
}

export interface CatalogForeignKey {
  columns: string[]
  to_table: string
  to_columns: string[]
}

export interface CatalogStructure {
  qualified: string | null
  is_view: boolean
  /** 表注释；导入表格的源是系统按核对结果生成的说明 */
  comment: string | null
  columns: CatalogStructureColumn[]
  primary_key: string[]
  /** 升级前探查的缓存里没有：null 表示不知道，空列表表示读过、没有 */
  foreign_keys: CatalogForeignKey[] | null
  unique: string[][] | null
}

/** GET /datasources/{id}/catalog/{table}；PUT、审阅也返回这个形状 */
export interface CatalogDetail {
  table_name: string
  in_schema: boolean
  notes: CatalogNotes
  version: number
  updated_at: string | null
  updated_by: string | null
  /** 表结构里已经没有这张表时为 null */
  structure: CatalogStructure | null
  system_notes: boolean
  usage: number
  /** 这张表最近一次剖析的完整结果（含检查清单、发现、发过的查询；任务还在进行就是进行中的状态）；没剖析过为 null */
  last_profile?: CatalogProfileTaskDetail | null
}

/** 单项审阅：确认、驳回、撤销审阅（回到来源的初始状态；人工填写的项直接删掉） */
export type CatalogReviewAction = 'confirm' | 'reject' | 'reset'

// ---------------------------------------------------------------------------
// 起草任务（/api/datasources/{id}/catalog/draft-jobs）：起草在服务端后台进行，逐表起草、每张表一结束就并入目录。
// 关掉对话框不停任务；服务重启时还没结束的任务记 interrupted，不自动续跑，由人点「重试」把没写全的表重新起草一遍
// （重试不跳过已写进目录的段，整张表重新分段起草；已写进目录的内容不会丢）。
// ---------------------------------------------------------------------------

/**
 * 起草任务的状态：排队、进行中、完成、部分完成（有失败、部分完成或停止的表）、失败（任务整体出错）、已停止（用户停止）、
 * 服务重启中断
 */
export type CatalogDraftJobStatus = 'queued' | 'running' | 'succeeded' | 'partial' | 'failed' | 'cancelled' | 'interrupted'

/**
 * 任务里一张表的状态。ok：写入成功（或没有东西要写），用模型时各段都写出来了；partial：用模型，有的段没写出来；
 * failed：整张表没起草（error），或用模型时一段都没写出来（model_error），按注释、外键、命名起草的部分照常写入；
 * skipped：表结构里没有这张表；cancelled：停止或服务重启时还没开始、没写完
 */
export type CatalogDraftTaskStatus = 'pending' | 'running' | 'ok' | 'partial' | 'failed' | 'skipped' | 'cancelled'

/** 起草任务里的一张表（按起草顺序） */
export interface CatalogDraftTask {
  table_name: string
  status: CatalogDraftTaskStatus
  /** 列数 */
  columns: number
  /** 模型分几段起草（超过 40 列的宽表拆成表级一段加列分段）；不用模型时为 null */
  parts_total: number | null
  parts_done: number
  /**
   * 已经写进目录的段数：每写完一段就并入目录，停止、服务重启时已写进的段保留。老服务端没有这个键
   */
  parts_written?: number
  /**
   * 这张表实际分成的块数和已结束的块数：额度用完、超时后段被缩小、拆半，块会比段多。不用模型时为 null；
   * 老服务端没有这两个键
   */
  chunks_total?: number | null
  chunks_done?: number | null
  added: number
  updated: number
  removed: number
  version: number
  /**
   * 模型给了这张表几项可用内容（并入目录之前）。没用模型、模型这部分失败时为 null。
   * 大于 0 而新增、更新、删除都是 0，才是「模型给了内容、只是和现有目录一致」
   */
  model_items: number | null
  /**
   * 模型拿不准、留空的列数：模型列出了（或这一段请它写了），中文名和含义却都没给（给了却都没通过校验的也算）。
   * 表的状态不因此变（照旧可以是已完成）。老服务端没有这个键
   */
  blank_columns?: number
  /** 留空的列里的前几个（最多 5 个，列名照表结构原样）。老服务端没有这个键 */
  blank_sample?: string[]
  /**
   * 这张表起草时记下的几句话（服务端整句中文，不算失败），比如模型提议的有效记录条件没有收下的原因。最多 10 句；
   * 老服务端没有这个键
   */
  log?: string[]
  /** 整张表没起草的原因：表结构里没有、写入一直冲突、服务重启中断 */
  error: string | null
  /** 模型那部分没写出来的原因和办法（第几段、哪些列、为什么） */
  model_error: string | null
  started_at: string | null
  finished_at: string | null
}

/** 起草任务的模型用量 */
export interface CatalogDraftUsage {
  /** 调用次数（没写出来的、超时的也算） */
  calls: number
  /** 超时的调用不计 token（照实记 0：服务方可能已经生成了内容） */
  input_tokens: number
  output_tokens: number
  /** 超时的调用次数。老服务端没有这个键 */
  timeouts?: number
  /** 没写出来的调用次数：额度用完、只给空壳、超时、出错。老服务端没有这个键 */
  failed_calls?: number
}

/** 一次起草任务 */
export interface CatalogDraftJob {
  id: string
  source_id: string
  status: CatalogDraftJobStatus
  use_model: boolean
  /** 实际用的模型 id；不用模型、还没开始时为 null */
  model: string | null
  /** 这次用到的起草要求（数据源级那份的快照） */
  guidance: string | null
  /** 这次的补充说明 */
  note: string | null
  created_at: string
  started_at: string | null
  finished_at: string | null
  /** 谁建的（X-Actor） */
  created_by: string | null
  /** 重试建的任务记着原任务的 id，别的为 null。接口约定里没有这一项，服务端多给的；界面不用，老服务端没有这个键 */
  retry_of?: string | null
  /** 表数 */
  total: number
  /** 已结束的表数 */
  done: number
  counts: Record<CatalogDraftTaskStatus, number>
  added: number
  updated: number
  removed: number
  /** 各表模型拿不准、留空的列数合计。老服务端没有这个键 */
  blank_columns?: number
  /** 模型调用的用量；拿不到用量时照实是 0 */
  usage: CatalogDraftUsage
  /**
   * 当前每段最多几列：一次起草里额度用完或超时累计 2 次后，之后新开始的段减半（40 → 20 → 10，最低 10）。
   * 不用模型时可能为 null；老服务端没有这个键
   */
  part_columns?: number | null
  /**
   * 调用接连没写出来时的提醒（一句中文：最近几次里几次没写出来、原因，建议换起草模型、缩小范围或停止）；
   * 好转后服务端清掉，为 null。老服务端没有这个键
   */
  notice?: string | null
  /** 任务整体出错的原因 */
  error: string | null
  /**
   * 排在同一个数据源的剖析任务后面（起草和剖析同源串行，按建立顺序）：剖析结束后自动开始。不在等时为 null；
   * 老服务端没有这个键
   */
  waiting_for?: 'profile' | 'introspect' | null
  tasks: CatalogDraftTask[]
}

/** 目录清单顶上的进行中任务（GET /datasources/{id}/catalog 的 active_job） */
export interface CatalogActiveDraftJob {
  id: string
  status: CatalogDraftJobStatus
  total: number
  done: number
  /** 排在剖析任务后面（同 CatalogDraftJob.waiting_for） */
  waiting_for?: 'profile' | 'introspect' | null
}

/** 清单一行上这张表最近一次起草的结果 */
export interface CatalogLastDraft {
  status: CatalogDraftTaskStatus
  job_id: string
  finished_at: string | null
  error: string | null
  model_error: string | null
  /** 那次起草模型拿不准、留空的列数（同 CatalogDraftTask.blank_columns）。老服务端没有这个键 */
  blank_columns?: number
  /**
   * 最近一次这张表结束于完成、部分完成的起草记下的留空列数（没有这样的起草为 null）。最近一次是停止、服务重启中断、
   * 又没有新写入时，界面用它接着提示留空的列。老服务端没有这个键
   */
  blank_columns_from?: number | null
  /** 那次起草已写进目录的段数（同 CatalogDraftTask.parts_written）。接口约定里没有这一项，服务端给了才用 */
  parts_written?: number
}

/**
 * 目录修改提案的一项（服务端 catalog.PatchChange）。助手转出的提案和预览接口都是这个形状。
 * path 是审阅接口的写法；新增关联关系已规范成 relations.<编号>
 */
export interface CatalogPatchChange {
  path: string
  /** 当前目录里的值；没有（或被驳回）为 null */
  before: unknown
  before_status: CatalogStatus | null
  /** 保存后的值（码值是补充后的完整对照） */
  after: unknown
  /** 交回保存的原样取值（码值只有补充的那几个） */
  value: unknown
  reason: string
  /** change 值有变化；confirm 值相同、还不是已确认（保存即确认）；same 已经是这个值且已确认 */
  state: 'change' | 'confirm' | 'same'
  /** 服务端对这一项的说明（目前只有：新增的关联关系没写基数、又推算不出来）。没有时不给 */
  note?: string
}

/** 保存、预览提案时交回的一项：路径、原样取值、理由 */
export interface CatalogPatchSubmit {
  path: string
  value: unknown
  reason?: string
}

/** POST /datasources/{id}/catalog/{table}/patch/preview：对着当前目录重算改前、改后（只读） */
export interface CatalogPatchPreview {
  table_name: string
  version: number
  changes: CatalogPatchChange[]
  /** 不合法的项的说明（目录刚被改过、列已删除……） */
  problems: string[]
}

/** 影响面里模板的一个节点（服务端 catalog_impact.template_refs） */
export interface CatalogImpactNode {
  node_id: string
  label: string
  type: string
  /** direct：SQL 里写着这张表；possible：Agent 运行时自己写 SQL，可能用到 */
  impact: 'direct' | 'possible'
  /** 合并查询：经由哪些输入（别名 → 节点） */
  via?: { node_id: string; label: string; alias: string }[]
  /** 协作节点：绑定了查询工具的成员 */
  member?: string
}

/** 引用这张表的一个已发布或受管模板（按它当前的已发布版本算） */
export interface CatalogImpactTemplate {
  workflow_id: string
  name: string
  /** 当前的已发布版本 */
  version: number
  level: 'published' | 'governed'
  impact: 'direct' | 'possible'
  nodes: CatalogImpactNode[]
}

// ---------------------------------------------------------------------------
// 审阅队列（/api/datasources/{id}/catalog/review-queue、review/batch、review-progress、{table}/usage，后端
// data/catalog_review.py）：跨表列出推断项，按表的使用次数、这一项对数字的影响和来源排好，可以成批确认、驳回。
// ---------------------------------------------------------------------------

/** 队列的筛选：全部、影响数字的项（有效记录条件、去重、业务日期、关联关系、业务主键、度量类型）、名称和含义 */
export type CatalogReviewKind = 'all' | 'facts' | 'names'

/** 队列里的一项（只列推断状态的项） */
export interface CatalogReviewItem {
  table_name: string
  /** 审阅接口的路径写法 */
  path: string
  /** 字段名（valid_filter、label……；关联关系是 relation） */
  field: string
  /**
   * 字段的界面叫法（服务端写好的「中文名」「码值」「有效记录条件」「关联关系」），不含是哪一列：界面上的位置按 path
   * 说（「列 status 的码值」，review.ts 的 reviewWhere）
   */
  field_label: string
  /** 列级的项是哪一列；表级的项、关联关系为 null。接口约定里没有写明，服务端给了才用 */
  column?: string | null
  value: unknown
  /** 值写成一行字（服务端写好的） */
  display: string
  source: CatalogSource
  status: CatalogStatus
  note: string | null
  /** 越大越靠前：表的使用次数权重 × 风险权重 × 来源权重 */
  priority: number
  /** 为什么排在这里（中文，服务端写好的） */
  reasons: string[]
  /** 所在表被运行用过的次数 */
  table_usage: number
  /** 所在表的目录版本：成批审阅时逐表带上 */
  version: number
}

/** GET /catalog/review-queue */
export interface CatalogReviewQueue {
  total: number
  items: CatalogReviewItem[]
}

/** POST /catalog/review/batch 的一项 */
export interface CatalogReviewBatchItem {
  table_name: string
  path: string
  action: CatalogReviewAction
  if_version: number
}

/** 成批审阅逐条的结果：一张表冲突不影响别的表；成功的写明这张表写入后的版本 */
export interface CatalogReviewBatchResult {
  table_name: string
  path: string
  ok: boolean
  version: number | null
  error: string | null
  code: string | null
}

/** 用过这张表的一次运行（新的在前） */
export interface CatalogUsageRun {
  run_id: string
  workflow_id: string | null
  workflow_name: string | null
  run_class: 'formal' | 'exploratory' | null
  status: string
  started_at: string | null
}

/** GET /catalog/{table}/usage */
export interface CatalogTableUsage {
  total: number
  runs: CatalogUsageRun[]
}

/**
 * GET /catalog/review-progress：常用的前 top_n 张表、全部表、影响数字的项各审阅到哪儿。
 * 「常用表」只算被运行用过的：tables 可能比 top_n 少，没有运行时是 0。三行的进度都按「已确认 ÷（已确认 + 待确认）」算
 * （review.ts 的 confirmProgress）：已驳回的、有确证的（外键约束）不用再确认，不计入
 */
export interface CatalogReviewProgress {
  top_n: number
  /** items_proposed、items_verified：接口约定里没有写明，服务端给了才用（没有待确认数时只写已确认几项） */
  top: { tables: number; items_total: number; items_confirmed: number; items_proposed?: number; items_verified?: number }
  all: { items_total: number; items_confirmed: number; items_proposed: number; items_rejected: number; items_verified?: number }
  facts: { proposed: number; confirmed: number }
}

// ---------------------------------------------------------------------------
// 导出导入（/api/datasources/{id}/catalog/export、import/preview、import，后端 data/catalog_transfer.py）：
// 本机整理好的目录带到另一个实例。先预览（只读），确认后逐表写入。
// ---------------------------------------------------------------------------

/** 导出的文件：含全部状态的项 */
export interface CatalogExportFile {
  format: 'agentlab-catalog'
  version: 1
  exported_at: string
  source: { name: string; kind: string }
  guidance: string | null
  tables: Record<string, { notes: CatalogNotes; version: number }>
}

/** 一处冲突：这里已确认、已驳回的项和文件中的不一样，以这里为准 */
export interface CatalogImportConflict {
  path: string
  label: string
  file_value: unknown
  target_value: unknown
  why: string
}

/** 预览、导入报告里的一张表 */
export interface CatalogImportTable {
  /** 文件中的表名 */
  table_name: string
  /** 对上的这个数据源里的表名（名字不一样时才有意思）；对不上为 null */
  matched_as: string | null
  add: number
  update: number
  keep: number
  conflicts: CatalogImportConflict[]
  skipped: { path: string; why: string }[]
  /** 导入后这张表的目录版本（只有导入的报告有） */
  version?: number | null
  /** 这张表没导入的原因（逐表写入，一张表失败不影响别的）。接口约定里没有写明，服务端给了才显示 */
  error?: string | null
}

export interface CatalogImportTotals {
  tables: number
  add: number
  update: number
  keep: number
  conflicts: number
  skipped: number
}

/** POST /catalog/import/preview、/catalog/import */
export interface CatalogImportReport {
  tables: CatalogImportTable[]
  /** 文件中有、这个数据源里对不上的表 */
  unmatched_tables: string[]
  totals: CatalogImportTotals
  /** 起草要求：写入文件中的（这里还没有）、保留这里的、不导入 */
  guidance: { file: string | null; target: string | null; action: 'keep' | 'replace' | 'none' }
}

// ---------------------------------------------------------------------------
// 表助手（POST /api/datasources/{id}/catalog/{table}/assistant，后端 data/catalog_assistant.py）：对话完善一张表的
// 目录。回答是事件流，每个事件一行 data: <JSON>。对话不存服务端，每一轮都把前面的对话和还没保存的修改带上。
// ---------------------------------------------------------------------------

/** 提案里的一项：和助手流里的 catalog_patch 一样，多一个给人看的位置 */
export interface CatalogAssistantChange extends CatalogPatchChange {
  label?: string
}

/**
 * 事件流里的一个事件。服务端等模型时另发 SSE 注释行（「: keep-alive」，不是事件），读流时跳过。
 * query 的 row_count 是取回的行数；truncated（接口约定里没有写明，服务端给了才用）为真时后面还有行，取回的只是前一截
 */
export type CatalogAssistantEvent =
  | { type: 'text'; delta: string }
  | { type: 'query'; sql: string; columns: string[]; rows: unknown[][]; row_count: number; truncated?: boolean; error: string | null }
  | { type: 'proposal'; source_id: string; table: string; version: number; changes: CatalogAssistantChange[] }
  | { type: 'done'; usage: { input_tokens: number; output_tokens: number }; queries: number }
  | { type: 'error'; message: string; code?: string | null }

/** 交给表助手的一轮请求 */
export interface CatalogAssistantRequest {
  messages: { role: 'user' | 'assistant'; content: string }[]
  /** 界面上还没保存的修改：最多 200 项（服务端同一个上限，多了整个请求 422），多出来的只交最近的 200 项 */
  pending: CatalogPatchSubmit[]
}

/** GET /datasources/{id}/catalog/{table}/impact */
export interface CatalogImpact {
  table: string
  /** 直接引用的在前 */
  templates: CatalogImpactTemplate[]
}

// ===========================================================================
// 数据剖析（后端 app/data/catalog_profile.py、catalog_profile_jobs.py）：对业务库发少量只读查询，核实推断的关联关系、
// 取码值候选、提议业务日期。默认关闭，按数据源在 options.catalog_profile 里开启。
// 剖析是服务端的后台任务（/api/datasources/{id}/catalog/profile-jobs）：逐表剖析，每张表有自己的查询次数和时长预算，
// 每张表一结束就写进目录；同时剖析几张表按设置（缺省一张），每张表的查询一条一条发，可以随时停止。和同一个数据源的起草任务
// 按建立顺序排队，一个结束了另一个才开始。
// 服务重启时还没结束的任务记 interrupted，不自动续跑（由人点「重试没做完的表」）。
// ===========================================================================

/** 剖析设置里的数值项 */
export type CatalogProfileNumberKey =
  'table_max_queries' | 'table_max_s' | 'query_timeout_s' | 'sample_size' | 'max_scan_rows' | 'table_concurrency'

/** 一个数据源的剖析设置（服务端 ProfileSettings.to_dict）；任务里的 settings 是建任务时的快照 */
export interface CatalogProfileSettings {
  enabled: boolean
  /** 每张表最多发几条查询，用完只停这张表 */
  table_max_queries: number
  /** 每张表最多剖析几秒，到时只停这张表 */
  table_max_s: number
  /** 单条查询时限（不超过数据源自身的查询时限，也不超过这张表剩下的时长） */
  query_timeout_s: number
  sample_size: number
  /** 0 表示一律不做整表统计 */
  max_scan_rows: number
  /** 同时剖析几张表（1–3，缺省 1）；每张表的查询仍一条一条发 */
  table_concurrency: number
}

/** 为什么需要剖析（GET /catalog 每行的 profile_due_reason） */
export type CatalogProfileDueReason = 'never' | 'unfinished' | 'new_relations' | 'new_checks'

/**
 * 剖析的范围：selected 指定的表；needed 需要剖析的表；all 全部可剖析的表（不含视图）；observe 观察到期的表（只做取值观察）；
 * maintenance 定时维护（需要剖析的表 + 观察到期的表）。后两种由定时维护建，界面不发起
 */
export type CatalogProfileScope = 'selected' | 'needed' | 'all' | 'observe' | 'maintenance'

/**
 * 剖析任务的状态：排队、进行中、完成、部分完成（有失败、部分完成、已停止的表）、失败（任务整体出错）、已停止（使用者停止）、
 * 服务重启中断。和起草任务同一套
 */
export type CatalogProfileJobStatus = CatalogDraftJobStatus

/**
 * 任务里一张表的状态。ok：每项检查都有结论；partial：有项因为运行原因没查成（unfinished）；failed：写入一直冲突或整张表出错；
 * skipped：视图、表结构里没有、空表、没有可剖析的项；cancelled：停止、止损、服务重启时还没开始、没做完
 */
export type CatalogProfileTaskStatus = CatalogDraftTaskStatus

/** 跳过一项的原因（CatalogProfileSkip.reason、检查项的 reason） */
export type CatalogProfileSkipReason = 'budget' | 'deadline' | 'failed' | 'timeout' | 'error' | 'rejected' | 'slow' | 'cancelled'
  | 'masked' | 'too_large' | 'view' | 'unsupported' | 'no_data' | 'missing' | 'high_cardinality' | 'nothing'

/** 一类检查：关联关系、码值、日期列；取值观察的四类（行数、码值观察、最新业务日期、按日行数） */
export type CatalogProfileCheckKind = 'relation' | 'codes' | 'date' | 'rows' | 'codes_observe' | 'freshness' | 'daily_volume'

/** 发现的合计（任务里是逐表合计） */
export interface CatalogProfileSummary {
  /** 有结论的关系条数 */
  relations_checked: number
  /** 其中状态为已验证的 */
  relations_verified: number
  /** 取到码值候选的列数 */
  codes: number
  /** 这些码值里含义还空着的个数之和 */
  codes_pending: number
  /** 提议了业务日期的表数（逐表时 0 或 1） */
  business_dates: number
}

/** 一张表的行数：stats 数据库的统计信息（估算）；count 数到上限为止；unknown 没能得到 */
export interface CatalogProfileSize {
  rows: number | null
  method: 'stats' | 'count' | 'unknown' | (string & {})
  /** 数到上限也没数完：至少这么多行 */
  at_least: number | null
}

/** 关系的核对结论：覆盖率、基数，升为已验证（verified）或保持推断（proposed）；人工确认过的只补覆盖率和基数 */
export interface CatalogProfileRelationFinding {
  kind: 'relation'
  path: string
  target: string
  columns: string[]
  to_table: string
  to_columns: string[]
  status: CatalogStatus
  confirmed: boolean
  /** 剖析之前目录里这条关系的状态：报告按它说「升为已验证」还是「仍为已验证」。老服务端不给 */
  previous_status?: CatalogStatus | null
  coverage: number
  cardinality: CatalogCardinality | null
  /** 基数是不是用数据核实的（子表一侧数过是否唯一）。老服务端不给 */
  cardinality_checked?: boolean
  /** 抽了几个不同的键值、在被指向表里对上几个 */
  sample: number
  matched: number
  summary: string
}

/** 码值候选：观察到的取值和行数，含义留给人填 */
export interface CatalogProfileCodesFinding {
  kind: 'codes'
  path: string
  column: string
  values: { value: string; rows: number }[]
  rows: number
  status: CatalogStatus
  /** 写进目录的码值里还有几个含义空着（别的来源写过的含义会沿用）。老服务端不给 */
  pending?: number
  summary: string
}

/** 业务日期提议：表里只有一个日期类列 */
export interface CatalogProfileDateFinding {
  kind: 'business_date'
  path: string
  column: string
  min: string
  max: string
  status: CatalogStatus
  summary: string
}

export type CatalogProfileFinding = CatalogProfileRelationFinding | CatalogProfileCodesFinding | CatalogProfileDateFinding

/** 没做的一项。detail 是可以直接显示的整句 */
export interface CatalogProfileSkip {
  /** relation / codes / date / row_estimate / table */
  kind: string
  target: string
  path: string | null
  /**
   * 运行原因没查成（计入 unfinished、使表成为部分完成）：budget 这张表的查询次数用完、deadline 这张表的时长用完、failed 连续失败
   * 止损、timeout、error、rejected 未通过只读守卫、slow 超时比例止损、cancelled 停止或服务重启。
   * 按规则不查（不算没做完）：masked、too_large、view、unsupported、no_data、missing、high_cardinality、nothing 没有可剖析的项
   */
  reason: CatalogProfileSkipReason | (string & {})
  detail: string
}

/** 任务里的一张表（按 seq） */
export interface CatalogProfileTaskRow {
  seq: number
  table_name: string
  status: CatalogProfileTaskStatus
  checks_total: number
  /** 结束了的项（含跳过的） */
  checks_done: number
  /** 每类检查 [结束了的, 一共]；这类没有检查时是 [0, 0]。取值观察的四类合成 observe 一类（老服务端不给） */
  checks_by_kind: Partial<Record<'relation' | 'codes' | 'date' | 'observe', [number, number]>>
  /** 进行中时正在做哪一项的整句（如「正在核对 orders.customer_id → customers.id」）；其余时候 null */
  current: string | null
  queries: number
  elapsed_ms: number
  row_estimate: CatalogProfileSize | null
  summary: CatalogProfileSummary
  /** 跳过的项数 */
  skipped_count: number
  /** 其中因为运行原因没查成的项数 */
  unfinished: number
  added: number
  updated: number
  removed: number
  version: number
  /** 整张表的原因：表结构里没有、视图、空表、没有可剖析的项、写入一直冲突、停止 / 中断 / 止损 */
  error: string | null
  started_at: string | null
  finished_at: string | null
}

/** 检查清单里的一项 */
export interface CatalogProfileCheck {
  kind: CatalogProfileCheckKind
  /** 哪一项：关系写「customer_id → customers.id」，码值、日期写列名 */
  target: string
  /** 审阅路径；没有为 null */
  path: string | null
  state: 'pending' | 'running' | 'done' | 'skipped'
  /** 跳过的原因（同 CatalogProfileSkip.reason）；没跳过为 null */
  reason: CatalogProfileSkipReason | (string & {}) | null
  /** 可以直接显示的整句（结论或跳过的原因）；没有为 null */
  detail: string | null
  queries: number
}

/** 发过的一条查询。sql 的字面量都换成了 ?（IN 列表里抽到的键值不留在 AgentLab 的库里） */
export interface CatalogProfileQuery {
  at: string
  kind: 'row_estimate' | CatalogProfileCheckKind
  target: string
  sql: string
  ms: number
  /** 返回的行数；没返回（超时、出错、守卫拒）时为 null */
  rows: number | null
  outcome: 'ok' | 'timeout' | 'error' | 'rejected'
  /** 超时、出错、守卫拒时的原因 */
  detail: string | null
}

/** GET /profile-jobs/{id}/tasks/{seq}：一张表的完整结果；GET /catalog/{table} 的 last_profile 也是这个形状 */
export interface CatalogProfileTaskDetail extends CatalogProfileTaskRow {
  job_id: string
  job_status: CatalogProfileJobStatus
  created_by: string | null
  checks: CatalogProfileCheck[]
  findings: CatalogProfileFinding[]
  skipped: CatalogProfileSkip[]
  /** 日期类列的取值范围 */
  /** invalid：零日期、占位日期这类不计入最小值和最大值的个数（没有时不给） */
  date_ranges: { column: string; min: string; max: string; invalid?: number }[]
  query_log: CatalogProfileQuery[]
}

/** 一次剖析任务 */
export interface CatalogProfileJob {
  id: string
  source_id: string
  status: CatalogProfileJobStatus
  scope: CatalogProfileScope
  /** 建任务时的剖析设置快照 */
  settings: CatalogProfileSettings
  created_at: string
  started_at: string | null
  finished_at: string | null
  /** 谁建的（X-Actor） */
  created_by: string | null
  /** 重试建的任务记着原任务的 id */
  retry_of: string | null
  /** manual 人点的；schedule 定时维护建的（fire_at 是那一次触发的计划时刻）。老服务端不给 */
  trigger?: 'manual' | 'schedule'
  fire_at?: string | null
  /** 排在同一个数据源的起草任务后面：起草结束后自动开始。不在等时为 null */
  waiting_for: 'draft' | 'introspect' | null
  total: number
  /** 已结束的表数 */
  done: number
  counts: Record<CatalogProfileTaskStatus, number>
  /** 整个任务发出的查询数、其中超时的、失败的 */
  queries: number
  timeouts: number
  errors: number
  /** 任务级止损停下的原因：failed 连续 3 条查询失败；slow 最近 10 条里 7 条超时。没停为 null */
  stop_reason: 'failed' | 'slow' | null
  /** 最近查询多数超时时的提醒（一句中文）；好转后服务端清掉 */
  notice: string | null
  /** 任务整体出错或止损的整句原因 */
  error: string | null
  added: number
  updated: number
  removed: number
  summary: CatalogProfileSummary
  tasks: CatalogProfileTaskRow[]
}

/** 清单一行上这张表最近一次剖析 */
export interface CatalogLastProfile {
  job_id: string
  seq: number
  status: CatalogProfileTaskStatus
  started_at: string | null
  finished_at: string | null
  summary: CatalogProfileSummary
  skipped_count: number
  unfinished: number
  error: string | null
  row_estimate: CatalogProfileSize | null
}

/** 目录清单顶上的进行中剖析任务（GET /catalog 的 active_profile_job） */
export interface CatalogActiveProfileJob {
  id: string
  status: CatalogProfileJobStatus
  total: number
  done: number
  waiting_for: 'draft' | 'introspect' | null
}

// ===========================================================================
// 基于数据目录的 SQL 检查（后端 app/data/sqlcheck.py）：七条规则，编号稳定
// ===========================================================================

export type SqlCheckCode = 'fanout_sum' | 'stock_summed' | 'join_unconfirmed' | 'ratio_aggregated' | 'missing_valid_filter'
  | 'unknown_code' | 'wrong_date_column'

/** error：依据已核实、结果很可能有误；warning：依据有确证、结果可能有误；info：依据只是推断 */
export type SqlCheckLevel = 'error' | 'warning' | 'info'

/** 一条检查结果（证据接口查询步骤里的 checks、助手自查和发布前检查的问题）。交回模型改写用的那句不上界面，这里不收 */
export interface SqlCheckItem {
  code: SqlCheckCode | (string & {})
  level: SqlCheckLevel | (string & {})
  /** 给人看的说明 */
  message: string
  /** schema_cache 里的表名 */
  table: string
  column?: string
  relation_id?: string
  sql_excerpt?: string
}

// ===========================================================================
// 数字推演（后端 app/api/whatif.py、app/engine/recompute.py）：在一次运行的口径卡上改输入、排除查询快照里的行，
// 看指标和报告里引用它的地方会变成多少。推演不是出具：不写运行记录、不改报告
// ===========================================================================

/** 推演的改动：输入路径 → 新值；查询快照的工件 id → 要排除的行号（快照里的行号，从 0 数） */
export interface WhatIfOverrides {
  inputs: Record<string, number>
  exclude_rows: Record<string, number[]>
}

/** POST /runs/{id}/evidence/whatif 的请求体 */
export interface WhatIfRequest {
  /** 报告撰写节点 id：只列这份报告里引用的地方 */
  report?: string
  /** 口径卡节点 id */
  card: string
  /** 只推演这一个指标 */
  metric?: string
  overrides: WhatIfOverrides
}

/** 一个输入在推演里的样子 */
export interface WhatIfInput {
  path: string
  via?: string | null
  node_id?: string | null
  /** 落在哪份查询快照上（cell() 取的格、agent 字段、整份查询结果）：排除这份快照里的行会影响它 */
  artifact?: string
  locator?: EvidenceLocator
  kind: 'number' | 'text' | 'bool' | 'missing' | 'container' | (string & {})
  /** 数值（或原本缺失）的标量、不是遮罩列、不决定取哪一格、还原得出：可以改。整个指标推演不了时一律为 false */
  editable: boolean
  /** 原值、推演用的值。容器写大概（「[12 项]」）；遮罩列的一律是 null */
  old?: unknown
  new?: unknown
  changed?: boolean
  /** 起了作用的被排除行（快照里的行号，从 0 数） */
  excluded_rows?: number[]
  /**
   * 这个输入实际用到的快照行（含两端，从 0 数）：单格一行、数组字段一段、整份查询结果全部。排除别的行影响不到它，
   * 界面只让这几行可勾。遮罩的、还原不了的（完整值找不回来、快照读不出来）没有，决定取哪一格的数组字段、整份结果
   * 也没有（少了几行，取到哪一格说不准），整个指标推演不了时一律没有
   */
  row_span?: [number, number]
  masked?: boolean
  /** 落在的查询快照读不出来（文件不在、与哈希不一致）：遮没遮核对不了，值不给 */
  withheld?: boolean
}

/**
 * unchanged：没碰到改动，原值原样交回；ok：重算了；excluded：排除行后缺了输入，算不出来；error：新值让计算出错（除以零……）；
 * unsupported：推演不了（有输入还原不了、口径卡没记输入，或者排除行后说不准受不受影响）；masked：用到了遮罩列，
 * 不推演。整个指标推演不了的不改动也是 unsupported / masked（unsupported 里另有一条 input 为空的）
 */
export type WhatIfStatus = 'unchanged' | 'ok' | 'excluded' | 'error' | 'unsupported' | 'masked'

export interface WhatIfMetric {
  id: string
  name: string
  unit: string
  decimals?: number | null
  format?: string
  old: unknown
  new: unknown
  delta: number | null
  /** 按口径卡的格式渲染（和报告里的字同一套规则） */
  rendered_old: string
  /** unsupported、masked 时为 null：不知道会变成什么 */
  rendered_new: string | null
  /** 带正负号；比率、百分数写「个百分点」。没变化、不是数时为 null */
  rendered_delta: string | null
  changed: boolean | null
  status: WhatIfStatus | (string & {})
  reason: string | null
  /** 推演用的代入式（重算了才有；没碰到改动的是卡上原来的代入式） */
  substituted: string | null
  inputs: WhatIfInput[]
}

/** 报告里引用这个指标的一处，推演之后会写成什么 */
export interface WhatIfSegment {
  report: string
  unit: string
  sid: string
  metric: string
  rendered_old: string
  rendered_new: string | null
  changed: boolean | null
}

export interface WhatIfUnsupported {
  metric: string
  /**
   * null：整个指标都推演不了（口径卡没记输入、用到了遮罩列、有输入还原不了或所在的快照读不出来），reason 和指标上的
   * 一样。不论改什么都推演不了，不改动也有这一条；界面据此只写原因，不画输入框、勾选框
   */
  input: string | null
  reason: string
}

/** 引用了这张口径卡的下游口径卡：只标可能受影响，不重算 */
export interface WhatIfAffectedCard {
  node_id: string
  artifact: string
  caliber: string
  version: string
  metrics: string[]
  /** 直接引用（false 是经别的卡间接引用） */
  direct: boolean
}

/**
 * GET /runs/{id}/evidence/whatif/rows：一页查询快照的行（推演时勾行用），形状和证据面板的查询步骤一致，
 * 可以直接交给 queryWindow。遮罩列写「已遮罩」；快照读不出来时没有行，note 说明原因
 */
export interface WhatIfRowsPage {
  run_id: string
  artifact: string
  node_id?: string | null
  tool?: string | null
  source?: string | null
  columns: string[]
  rows: unknown[][]
  row_offset: number
  row_index: number[]
  total_rows: number | null
  truncated: boolean | null
  masked: string[]
  hash_ok: boolean | null
  sealed: boolean
  note?: string
}

export interface WhatIfResult {
  run_id: string
  card: { node_id: string; artifact: string; caliber: string; version: string }
  report: string | null
  /** 运行已封存且封存核对一致：推演依据的数据不会再变 */
  sealed: boolean
  seal: { sealed: boolean; ok: boolean | null }
  metrics: WhatIfMetric[]
  segments: WhatIfSegment[]
  unsupported: WhatIfUnsupported[]
  affected_cards: WhatIfAffectedCard[]
}

// ---------------------------------------------------------------------------
// 定时任务（/api/schedules，页面在 pages/schedules）。前后端按同一份接口约定，字段名和形状不各自发挥；时间一律是
// ISO 字符串（UTC），按定时任务自己的时区显示
// ---------------------------------------------------------------------------

/**
 * 运行列表里的定时来源：发起它的定时任务，手动发起的是 null，老服务端不给。写在这里而不是上面 Run 的定义里：
 * 同名接口会合并，定时任务的类型集中在文件末尾这一段，不和别的工作包改同一处
 */
export interface Run {
  schedule_id?: string | null
}

export type ScheduleRunClass = 'formal' | 'exploratory'
/** Webhook 消息的格式：通用 JSON、飞书 / 企业微信 / 钉钉的群机器人 */
export type ScheduleWebhookFormat = 'generic' | 'feishu' | 'wecom' | 'dingtalk'
/** 订阅的事件：运行结束、运行失败、停在人工审批上（只在真有待审批时发） */
export type ScheduleEvent = 'finished' | 'failed' | 'awaiting_approval'
/** 触发的来源：到点、手动「立即运行」、错过之后在宽限内补发、由数据事件触发（trigger_kind=event 的任务） */
export type ScheduleFireKind = 'scheduled' | 'manual' | 'misfire' | 'event'
/** 触发的结局：发起了运行、上一次还没结束而跳过、错过时间超出宽限而跳过、发起时被拒 */
export type ScheduleFireStatus = 'started' | 'skipped_overlap' | 'skipped_misfire' | 'failed_to_start'
/**
 * 定时的目标种类（next-round X4：定时只有一套）：工作流、评测题集、数据源维护。非工作流目标没有工作流、输入模板、运行类别
 * 和 Webhook（backend/app/api/schedules.py）
 */
export type ScheduleTargetKind = 'workflow' | 'eval_suite' | 'source_maintenance'

/** 读出来的 Webhook 设置。完整地址服务端加密保存、不再返回，只露主机和末 4 位 */
export interface ScheduleWebhook {
  format: ScheduleWebhookFormat
  /** 如 open.feishu.cn/…ab12 */
  url_hint: string
  has_secret: boolean
  events: ScheduleEvent[]
}

/** 一次触发发出的一条通知 */
export interface ScheduleFireNotice {
  event: ScheduleEvent
  status: 'ok' | 'failed'
  at: string
}

/**
 * 运行成功结束后和同一定时任务上一次成功的运行的自动对比：基准是哪一次、各类指标的个数（同对比接口的 summary）。
 * 只有个数，具体的数在对比页上
 */
export interface ScheduleFireCompare {
  base_run_id: string
  summary: RunCompareSummary
  /**
   * 基准是不是紧挨着的上一次。上一次失败了、取消了时，基准是再往前成功的那一次，为 false：界面写明比的是哪一次。
   * 老服务端不给，按 true 看
   */
  previous?: boolean
}

/** 一次触发（触发历史的一行） */
/** 数据源定时维护的步骤（app/data/source_maintenance.STEPS） */
export type ScheduleMaintenanceStep = 'introspect' | 'profile_needed' | 'observe'

/**
 * 数据源维护的一次触发建了什么（app/data/source_maintenance 记在触发上的 inputs）：要做的步骤、建了的探查 / 剖析任务（step 是
 * 这个任务做的那几步，剖析、观察合成一个任务时写成 profile_needed+observe）、没执行的步骤和原因。和数据源页「定时维护」的
 * 「最近一次」读的是同一份
 */
export interface ScheduleMaintenanceInputs {
  steps?: ScheduleMaintenanceStep[]
  jobs?: { step: string; kind: 'introspect' | 'profile'; id: string; tables?: number; scope?: string }[]
  skipped?: { step: ScheduleMaintenanceStep; reason: string }[]
}

export interface ScheduleFire {
  id: string
  /** 计划触发的时间；手动运行是按下的那一刻 */
  fire_at: string
  kind: ScheduleFireKind
  status: ScheduleFireStatus
  run_id: string | null
  /** 发起的那次运行现在的状态（同 Run.status） */
  run_status: RunStatus | null
  /** 跳过、发起失败的原因（中文） */
  reason: string | null
  /** 目标是评测题集时这一次触发建的那次评测（没有 run_id）；老服务端不给 */
  eval_run_id?: string | null
  /** 目标是数据源维护时这一次建了哪些任务、哪几步没执行和原因（触发记录的 inputs）；别的目标为 null，老服务端不给 */
  inputs?: ScheduleMaintenanceInputs | null
  notified: ScheduleFireNotice[]
  /**
   * 和同一定时任务上一次成功的运行的对比。运行没有成功结束、没有可比的、还没算、比不了、任何一边又在执行（不在终态）
   * 或重新封存过时为 null；老服务端不给
   */
  compare?: ScheduleFireCompare | null
  created_at: string
}

export interface Schedule {
  id: string
  name: string
  /** 目标：种类、id、种类的叫法、目标现在的名字（不在了是保存时记下的）、还在不在。老服务端不给（都是工作流） */
  target_kind?: ScheduleTargetKind
  target_id?: string
  target_label?: string
  target_name?: string
  target_exists?: boolean
  /** 非工作流目标存空串 */
  workflow_id: string
  workflow_name: string
  /** 五段 cron：分 时 日 月 星期 */
  cron: string
  /** IANA 时区名，如 Asia/Shanghai */
  timezone: string
  run_class: ScheduleRunClass
  /** 字段名 → 模板字符串，变量（{{ schedule.yesterday }} 这类）按触发时间计算 */
  input_template: Record<string, string>
  enabled: boolean
  /** 上一次还没结束时怎么办：目前只有跳过 */
  overlap: 'skip'
  /** 错过触发时间后多少秒内恢复还补发一次 */
  misfire_grace_s: number
  webhook: ScheduleWebhook | null
  /** 暂停中、或者往后不会再触发时为 null */
  next_run_at: string | null
  last_fire: ScheduleFire | null
  /** 频率的中文说法，如「每周一 09:00（Asia/Shanghai）」 */
  description_text: string
  created_by: string | null
  created_at: string
  updated_at: string
  /** 乐观锁：修改时带上读到的版本，别人在这期间改过时回 409 */
  version: number
}

/** 新建、修改时交上去的 Webhook。地址、密钥的明文只在写的时候给 */
export interface ScheduleWebhookIn {
  format: ScheduleWebhookFormat
  /** 修改时：省略表示不改，空串表示删除整个 Webhook */
  url?: string
  /** 修改时：省略表示不改，空串表示清除 */
  secret?: string
  events: ScheduleEvent[]
}

/** POST /api/schedules 的请求体 */
export interface ScheduleCreate {
  name: string
  workflow_id: string
  cron: string
  timezone: string
  run_class: ScheduleRunClass
  input_template: Record<string, string>
  enabled: boolean
  overlap: 'skip'
  misfire_grace_s: number
  webhook: ScheduleWebhookIn | null
}

/**
 * POST /api/schedules 建非工作流目标（评测题集、数据源维护，总方案 X4）的请求体：写 target_kind、target_id，不写工作流、
 * 输入模板和 Webhook（服务端回 422，field 是那一项）；运行类别不用。改的时候照样用 SchedulePatch（只带 name、cron、timezone、
 * enabled、misfire_grace_s 这几项）
 */
export interface ScheduleTargetCreate {
  name: string
  target_kind: Exclude<ScheduleTargetKind, 'workflow'>
  target_id: string
  cron: string
  timezone: string
  enabled: boolean
  overlap: 'skip'
  misfire_grace_s: number
}

/** PATCH /api/schedules/{id} 的请求体：只带改了的字段，外加读到的版本 */
export type SchedulePatch = Partial<Omit<ScheduleCreate, 'webhook'>> & {
  webhook?: ScheduleWebhookIn
  version: number
}

export interface SchedulePreviewRequest {
  cron: string
  timezone: string
  input_template?: Record<string, string>
  workflow_id?: string
  n?: number
}

/** 预览：频率的中文说法、接下来几次触发时间、按下一次触发时间渲染出的输入。非法时 422 {detail, field} */
export interface SchedulePreview {
  description_text: string
  next: string[]
  inputs: Record<string, string>
}

/** 输入模板里能用的变量 */
export interface ScheduleVariable {
  /** 如 schedule.yesterday */
  name: string
  /** 如「昨天（YYYY-MM-DD）」 */
  label: string
  example: string
  /** 补充说明（ISO 周的跨年规则），没有的是空串；老服务端没有这个键 */
  note?: string
}

/** POST /api/schedules/{id}/run：这次手动触发和它发起的运行（没发起时为 null） */
export interface ScheduleRunResult {
  fire: ScheduleFire
  run_id: string | null
}

// ---------------------------------------------------------------------------
// 数据事件触发（docs/design/orchestration-round/00-总方案.md §4；服务端 scheduler/triggers.py、outbox.py）：一个
// trigger_kind=event 的定时任务，目标只能是工作流。同名接口会合并，这里只往上面几个类型上补字段
// ---------------------------------------------------------------------------

/** 触发方式：按 cron 到点、由数据事件触发。老服务端不给，按 cron 看 */
export type ScheduleTriggerKind = 'cron' | 'event'
/** 事件种类：上传表格出了新的一期、上游工作流运行成功结束、数据源有要处理的变化 */
export type ScheduleEventKind = 'table.version' | 'workflow.finished' | 'source.changed'

/** 触发条件（服务端规范化过的那一份）。对象键按事件种类：表格、数据源写 source_id，上游工作流写 workflow_id */
export interface ScheduleTrigger {
  event: ScheduleEventKind
  source_id?: string
  workflow_id?: string
  /** 只认新增的一期（不写即新增、替换都认），只给 table.version */
  period?: 'new' | 'any'
  /** 只认某个应用发起的、某种来源的运行，只给 workflow.finished */
  app_id?: string
  origin_kind?: string
  /**
   * 也认途经驳回的（上游走了某个审批的驳回出口、按驳回那条路跑完，状态仍是成功）、也认应用补算的；缺省都不认。只给
   * workflow.finished，不写即 false
   */
  include_rejected?: boolean
  include_backfill?: boolean
  /** 去抖：同一个任务这么多秒内的几次事件合成一次 */
  debounce_s: number
  /** 保存时记下的对象名（对象删掉之后界面写它）；读出来才有，交上去不用带 */
  subject_name?: string
}

/** 事件触发任务现在有几条事件在等：没派发的（调度关着时一直留着）、在去抖窗口里的、窗口结束的时刻、调度开没开 */
export interface ScheduleTriggerState {
  events: number
  waiting: number
  due_at: string | null
  scheduler_on: boolean
}

export interface Schedule {
  trigger_kind?: ScheduleTriggerKind
  /** 事件触发时的触发条件；cron 任务为 null */
  trigger?: ScheduleTrigger | null
  /** 给人看的触发说明（事件触发时同 description_text）；cron 任务为 null */
  trigger_text?: string | null
  trigger_state?: ScheduleTriggerState | null
}

/** 事件触发的那一次触发带的事件说明（服务端 outbox.EventFire.brief，不含出口字段的值） */
export interface ScheduleFireEvent {
  event: ScheduleEventKind
  subject_id: string
  subject_name: string
  /** 一句说法：「上传表格「门店销售」出了新的一期（2026-09）」 */
  text: string
  /** 去抖合并了几次事件 */
  merged: number
  first_at: string | null
  last_at: string | null
  /** 这次运行在事件触发链上是第几层 */
  depth: number
  /** 立即运行时按示例事件发起的（不是真来了一次事件）；real 为假时是示例值 */
  sample: boolean
  real: boolean
  /** 几个过了补发宽限的去抖窗口合成一条跳过时才有：合了几个窗口、合掉的期次（上传表格）；老服务端不给 */
  windows?: number | null
  periods?: string[] | null
}

export interface ScheduleFire {
  /** 事件触发的那几次的事件说明；别的为 null，老服务端不给 */
  event?: ScheduleFireEvent | null
}

export interface ScheduleCreate {
  /** 不写即 cron（字段和以前一字不差） */
  trigger_kind?: ScheduleTriggerKind
  trigger?: Omit<ScheduleTrigger, 'debounce_s'> & { debounce_s?: number }
}

export interface SchedulePreviewRequest {
  trigger_kind?: ScheduleTriggerKind
  trigger?: Omit<ScheduleTrigger, 'debounce_s'> & { debounce_s?: number }
}

export interface SchedulePreview {
  /** 事件触发时：按哪一次事件渲染的（real 为假时是示例值，对象还没发生过这种事件） */
  event?: { text: string; real: boolean } | null
}

/** GET /api/schedules/trigger-options：每种事件能选的对象（ok 为假时不能选，reason 写为什么，由服务端判）、来源、应用 */
export interface ScheduleTriggerOptions {
  events: {
    event: ScheduleEventKind
    label: string
    subject_label: string
    objects: { id: string; name: string; ok: boolean; reason: string | null }[]
    /** 一页没给完（对象按名字排、一页有上限）：界面按关键字再查。老服务端不给，当作给完了 */
    more?: boolean
  }[]
  origins: { kind: string; label: string }[]
  apps: { id: string; name: string }[]
  default_debounce_s: number
  max_debounce_s: number
  max_depth: number
}

/** GET /api/schedules/{id}/fires 的一页，新的在前；next_before 是下一页的游标，没有更多时为 null */
export interface ScheduleFirePage {
  items: ScheduleFire[]
  next_before: string | null
}

/** POST /api/schedules/{id}/webhook/test：用已保存的设置发一条测试消息 */
export interface ScheduleWebhookTest {
  ok: boolean
  http_status: number | null
  message: string
}

// 运行对比（GET /api/runs/{id}/compare/base、/compare?base=）：两次运行的指标变化按数据 / 口径 / 模板与 SQL 拆开说。
// 形状照前后端共用的接口约定，字段名一个不改；数值都是服务端算好的，界面只排版，渲染值原样显示
// ---------------------------------------------------------------------------

/** 对比里的一次运行。版本是空的：没从固定版本发起（探索运行）；schedule_id 是空的：手动发起 */
export interface RunCompareRef {
  id: string
  workflow_name: string
  version: number | null
  run_class: 'formal' | 'exploratory' | null
  started_at: string | null
  finished_at: string | null
  schedule_id: string | null
}

/** 默认基准从哪来：同一定时任务的上一次，没有就同一工作流、同一运行类别的上一次 */
export type RunCompareBaseReason = 'same_schedule' | 'same_workflow'

/** GET /runs/{id}/compare/base。找不到时 404，detail 是一句原因 */
export interface RunCompareBase {
  base_run_id: string
  reason: RunCompareBaseReason | (string & {})
  base: RunCompareRef
  /**
   * 基准是不是紧挨着的上一次（服务端 pick_base 算的，同触发历史里自动对比的 previous）：上一次失败、取消、还没结束时
   * 为 false，运行详情「更多」里的入口据此写「与上一次成功的运行对比」。老服务端不给，按 true 算
   */
  previous?: boolean
}

/**
 * 指标的分类。unchanged：未变；data_only：只数据变；caliber_and_data：口径与数据都变（能严格拆时给口径效应、数据效应）；
 * sql_changed：所依据的查询 SQL 结构变了（口径不同，不拆）；params_only：SQL 只差字面量（定时运行的日期）；
 * added / removed：只有本次 / 只有基准有；incomparable：缺比较所需的信息
 */
export type RunCompareClass =
  | 'unchanged' | 'data_only' | 'caliber_and_data' | 'sql_changed' | 'params_only' | 'added' | 'removed' | 'incomparable'

/** 各类指标的个数 */
export type RunCompareSummary = Record<RunCompareClass, number>

export interface RunCompareTemplateNode {
  node_id: string
  title: string
  change: 'added' | 'removed' | 'config' | (string & {})
  /** 改了的配置项（节点配置里的键） */
  keys: string[]
  /** 约定之外、服务端顺带给的：各配置项在界面上的叫法，和 keys 一一对应。没给（或对不上）时照写键名 */
  labels?: string[]
}

export interface RunCompareTemplate {
  base_version: number | null
  target_version: number | null
  /** 两次运行的执行图完全相同 */
  same_graph: boolean
  nodes: RunCompareTemplateNode[]
}

/**
 * 严格拆分：口径效应 = 新口径(本次的数据) − 旧口径(本次的数据)，数据效应 = 旧口径(本次的数据) − 旧口径(基准的数据)，
 * 两者之和正好是总变化。*_rendered 是服务端按口径卡格式写好的（带正负号）
 */
export interface RunCompareDecomposition {
  caliber_effect: number
  data_effect: number
  caliber_rendered: string
  data_rendered: string
}

/** 一个输入在两次运行里的值（容器写大概，缺的是 null） */
export interface RunCompareInput {
  path: string
  base: unknown
  target: unknown
  /** 约定之外、服务端顺带给的：取自设置了遮罩的列，两边的值都不给 */
  masked?: boolean
}

export interface RunCompareAttributionRow {
  /** 各维度列上的取值，和 columns 一一对应 */
  key: unknown[]
  base: number | null
  target: number | null
  delta: number | null
  /** 这一项的变化占总变化的比例（小数，0.4 是 40%）。度量列之和对不上指标的输入时为 null，原因在 note */
  share: number | null
}

/** 维度归因：按键对齐两边查询结果的行，变化最大的排在前面 */
export interface RunCompareAttribution {
  columns: string[]
  measure: string
  rows: RunCompareAttributionRow[]
  total_delta: number | null
  note: string | null
}

export interface RunCompareMetric {
  card_id: string
  card_title: string
  metric_id: string
  name: string
  unit: string
  decimals: number | null
  base: number | null
  target: number | null
  base_rendered: string | null
  target_rendered: string | null
  delta: number | null
  /** 带正负号；比率、百分数写「个百分点」。没变化、不是数时可能为 null */
  delta_rendered: string | null
  /** 相对基准变化了百分之几（已乘 100，保留两位：12.5 是 +12.5%，和占比的小数写法不同）；基准为 0、缺值时为 null */
  delta_pct: number | null
  classification: RunCompareClass | (string & {})
  reasons: string[]
  decomposition: RunCompareDecomposition | null
  /** 没法严格拆分的原因；能拆、或者用不着拆（只数据变、未变）时为 null */
  decomposition_note: string | null
  inputs: RunCompareInput[]
  attribution: RunCompareAttribution | null
}

/** same：完全相同；params_only：规范化之后相同，只差字面量；changed：结构不同；added / removed：只有一边有 */
export type RunCompareStructure = 'same' | 'params_only' | 'changed' | 'added' | 'removed'

export interface RunCompareQuery {
  node_id: string
  node_title: string
  /** 同一节点里的第几条查询（服务端的序号，只用来排序和区分，界面另按 1 起数） */
  ordinal: number
  structure: RunCompareStructure | (string & {})
  base_sql: string | null
  target_sql: string | null
  /** 不同的字面量（SQL 写法，字符串带引号），按出现的顺序 */
  literals: { base: unknown; target: unknown }[]
  base_rows: number | null
  target_rows: number | null
  base_truncated: boolean | null
  target_truncated: boolean | null
  /** 约定之外、服务端顺带给的：结构变了时差在哪，一处一句中文（按对结果的影响从大到小） */
  differences?: string[]
  /** 约定之外、服务端顺带给的：快照读不出来、与哈希不一致时的一句说明 */
  problem?: string
}

/** 运行对比里分析卡的一边（analysis.end 那一项）：没有这一项为 null */
export interface RunCompareAnalysisSide {
  status?: string | null
  verdict?: string | null
  direction?: string | null
  phrase?: string
  artifact?: string | null
}

/**
 * 运行对比里分析卡的一项（engine/compare._analyses）：两次运行的分析卡按节点和项的标识对齐。change：same 判定和判定语都一样、
 * verdict 状态或判定变了、phrase 判定一样而判定语里的数变了、added / removed 只在一边有
 */
export interface RunCompareAnalysis {
  node_id: string
  title?: string
  item: string
  op?: string | null
  mode?: string | null
  base: RunCompareAnalysisSide | null
  target: RunCompareAnalysisSide | null
  change: 'same' | 'verdict' | 'phrase' | 'added' | 'removed' | string
}

/** GET /runs/{id}/compare?base=。任一未封存或封存核对不一致 409；不是同一工作流、是同一次运行 422 */
export interface RunComparison {
  target: RunCompareRef
  base: RunCompareRef
  summary: RunCompareSummary
  template: RunCompareTemplate
  metrics: RunCompareMetric[]
  /** 分析卡按项对齐（分析能力一轮）；老服务端没有 */
  analyses?: RunCompareAnalysis[]
  queries: RunCompareQuery[]
  notes: string[]
}

/** 运行接口回的运行带着发起它的定时任务（RunOut.schedule_id）；Run 上没写这一项，对比页的运行卡要用 */
export type RunWithSchedule = Run & { schedule_id?: string | null }

// ---------------------------------------------------------------------------
// 双盲复算：审批 payload、完整对照工件、节点配置，以及设置里「核查」一组（期 3 前后端共用的约定）
// ---------------------------------------------------------------------------

/** 审核人对一个指标的裁决：a 采用原流程的结果，b 采用盲算的结果，neither 两边都不对 */
export type DualCheckChoice = 'a' | 'b' | 'neither'

/** 双盲复算挂起时 payload.summary 的一项：审批卡先用它画，完整对照另从 card_artifact 取 */
export interface DualCheckSummaryItem {
  metric_id: string
  name: string
  unit?: string | null
  original_rendered: string | null
  blind_rendered: string | null
  /** (盲算值 − 原流程值) ÷ |原流程值| × 100，保留两位小数（12.5 表示相差 12.5%）；原流程值为 0 时为 null */
  delta_pct: number | null
  /** 具体差异，一条一句中文，最多 3 条 */
  diff: string[]
  /** 只有兜底说明：两条 SQL 的写法不同，未能归纳成具体差异 */
  fallback: boolean
  /**
   * 约定之外、服务端另带的：采用原流程（a）、采用盲算（b）各会往数据目录里写什么。老服务端没有这一项，卡上按差异的
   * 形状有条件地说
   */
  catalog?: { a: DualCheckCatalogSide; b: DualCheckCatalogSide }
}

/**
 * 采用一边的结果会往数据目录里写什么：服务端按发起审批时的数据目录预告（dual_check_facts.preview，和裁决后真写的
 * 是同一套判断）。write 为真时 table 的 item（business_date / valid_filter / dedup）会记为 value（有效记录条件是和
 * 目录里已有的条件合起来之后的整句）；为假时 reason 说明为什么不写
 */
export type DualCheckCatalogSide =
  | { write: true; source?: string | null; table: string; item: string; value: unknown }
  | { write: false; reason?: string | null }

/** payload.kind 为 dual_check 的审批 payload（审批的 mode 是 input） */
export interface DualCheckPayload {
  kind: 'dual_check'
  node_id: string
  title: string
  /** 完整对照放在这个工件里（GET /api/artifacts/{id}），内容见 DualCheckCard */
  card_artifact: string
  summary: DualCheckSummaryItem[]
  /** 约定之外、服务端另带的：节点实际生效的「未采用原流程时」。没有时卡上从运行的图快照里读 */
  on_reject?: 'degrade' | 'fail'
}

/** 审核人的回复：POST /approvals/{id}/decide 的 value */
export interface DualCheckReply {
  choices: Record<string, DualCheckChoice>
  note: string
}

/** 指标的一个输入：取自哪条查询的哪一格（alias 是查询快照的编号） */
export interface DualCheckInput {
  path: string
  value: unknown
  sql?: string | null
  source?: string | null
  alias?: string | null
}

/** 盲算那一边的输入多一段盲算模型自己的说明 */
export interface DualCheckBlindInput extends DualCheckInput {
  rationale?: string | null
}

export interface DualCheckSide<I extends DualCheckInput = DualCheckInput> {
  value: number | null
  rendered: string | null
  inputs: I[]
}

/** 两条 SQL 差在哪（服务端 sql_semantics.explain_sql_diff）。aspect 为 other 的是兜底说明，parse 是解析不了 */
export interface DualCheckDiff {
  equivalent: boolean
  items: { aspect: string; text: string }[]
  /** 用了兜底说明（一条具体说法都没有，或者具体说法只覆盖了一部分） */
  fallback: boolean
  /**
   * 规范化之后两条 SQL 不同的行：「- 」开头是原流程的，「+ 」开头是盲算的；「  」开头的是两边相同的上级行，只为标出
   * 不同的行在哪个子句里（老工件里没有）
   */
  text_diff: string[]
}

export interface DualCheckMetric {
  metric_id: string
  name: string
  unit?: string | null
  decimals?: number | null
  original: DualCheckSide
  blind: DualCheckSide<DualCheckBlindInput>
  diff: DualCheckDiff
  /** 相差比例，口径同 DualCheckSummaryItem.delta_pct（有的话） */
  delta_pct?: number | null
}

/** card_artifact 工件的内容 */
export interface DualCheckCard {
  metrics: DualCheckMetric[]
  /** 盲算用的模型 */
  model?: string | null
  /** 盲算模型和原流程的模型相同 */
  same_model?: boolean
}

/** 双盲复算节点的配置。留空的项：card 取上游的口径卡，metrics 取输入来自查询的全部指标，其余跟随设置 */
export interface DualCheckConfig {
  card?: string
  metrics?: string[]
  definitions?: Record<string, string>
  provider?: string
  model?: string
  tolerance?: number
  on_reject?: 'degrade' | 'fail'
  /** null 或不写：跟随设置 */
  enabled?: boolean | null
}

/**
 * 设置里的 analysis 一组（GET /settings 给的是补齐缺省之后的完整一组）：判定用的阈值、Agent 每次执行最多分析几次、最多下钻
 * 几层、列出前几段。键、叫法、范围见 lib/termsAnalysis（照服务端 analysis/contract.py）
 */
export type AnalysisSettings = Record<string, number>

/** 设置里的 verify 一组（GET /settings 给的是补齐默认之后的完整一组；上限为 null 表示不限） */
export interface VerifySettings {
  provider: string | null
  model: string | null
  dual_check: { enabled: boolean; tolerance: number; max_queries: number | null; timeout_s: number | null }
  challenge: { enabled: boolean; max_claims: number | null; max_queries: number | null; timeout_s: number | null }
  inquiry: { enabled: boolean; max_queries: number | null; timeout_s: number | null }
  daily_max_usd: number | null
}

/** GET /settings/verify/spend：今天（本地日期）核查花了多少。unpriced_calls 是估不出金额、没算进 usd 的调用次数 */
export interface VerifySpend {
  date?: string
  usd?: number
  calls?: number
  unpriced_calls?: number
  daily_max_usd?: number | null
}

// ---------------------------------------------------------------------------
// 反方审稿（challenge 节点）：审批卡上的概况、challenge_artifact 工件的内容。形状照前后端共用的接口约定，字段名一个不改；
// 判断由反方模型给出，界面只排版，理由正文、行数这些都是服务端给的
// ---------------------------------------------------------------------------

/** 一句结论经受住反方的复核没有：经受住 / 被削弱 / 被推翻 / 无法判断 */
export type ChallengeVerdict = 'stands' | 'weakened' | 'refuted' | 'inconclusive'

/** 各种判断的句数 */
export type ChallengeCounts = Record<ChallengeVerdict, number>

/** 审批卡、节点产出里列的一句：unit 是报告文档里这一句的 id，text 是结论原文 */
export interface ChallengeItem {
  unit: string
  text: string
  verdict: ChallengeVerdict | (string & {})
}

/**
 * 审批卡上的反方审稿概况（human 节点 payload.reports[i].challenge）。items 最多 10 条，完整内容在 artifact 指的工件里。
 * on_refuted 是实际生效的处理方式：degrade 被推翻的结论计入出具缺口；flag 只标注。报错（fail）时节点已经失败，到不了审批。
 * 老服务端不给时按 degrade
 */
export interface ApprovalChallenge {
  counts: ChallengeCounts
  items: ChallengeItem[]
  /** challenge_artifact 工件 id。服务端保存审稿记录失败时为 null：判断照样有，理由和查询看不了 */
  artifact: string | null
  on_refuted?: 'degrade' | 'flag' | (string & {})
  /** 期 4（nodes/challenge.challenge_summary）：没能反查的句数，都记为无法判断。升级前的产出、老服务端没有 */
  unreviewed?: number
  /**
   * 期 4：被推翻的会不会让出具降档（按降档处置、又接在带出具契约的成果节点上游才为真）。升级前的产出、老服务端没有，
   * 审批卡按「没写只标注就降档」的旧规则说
   */
  degrades?: boolean
}

/**
 * 审批审的报告经过反方审稿时多一个 challenge。和上面的 ApprovalReport 是同一个接口（声明合并）：反方审稿的类型集中在
 * 这一段，这一项也就近写在这里
 */
export interface ApprovalReport {
  challenge?: ApprovalChallenge
}

/** 反方为复核一句结论执行的一次只读查询：编号是它自己的（Q1、Q2…），和报告里的查询编号无关 */
export interface ChallengeQuery {
  alias: string
  /** 查询快照工件 */
  artifact: string
  sql: string
  row_count: number | null
  truncated: boolean
  /** 数据源名 */
  source: string | null
}

/** 工件里的一句：判断、理由、查询 */
export interface ChallengeClaim extends ChallengeItem {
  /** 理由渲染后的正文（数字已换成查询结果里的值） */
  rationale: string
  /**
   * 理由组装成的文档（和报告文档同一种形状，数字带出处、裸数字被标出）。约定没说是工件 id 还是文档本身，两种都认；
   * 没有时只显示 rationale
   */
  rationale_doc?: string | EvidenceDocData | null
  queries: ChallengeQuery[]
  usage?: { input_tokens?: number; output_tokens?: number; total_tokens?: number; cost_usd?: number | null; calls?: number }
}

/** challenge_artifact 工件的内容：审的哪份报告、每句的复核，以及反方用的模型 */
export interface ChallengeArtifact {
  /** 被审的报告撰写节点 */
  report: string
  doc_artifact: string
  claims: ChallengeClaim[]
  model: string | null
}

// ---------------------------------------------------------------------------
// 审批质询：审批人就待审的报告提问，核查模型只读查库作答。形状照前后端共用的接口约定（F5a / F5b 同一份），字段名一个
// 不改；回答正文、行数、触顶原因都是服务端给的，界面只排版
// ---------------------------------------------------------------------------

/** 回答停在哪个上限上：每次最多查询次数、时长、这一次的金额、核查的每日金额 */
export type InquiryLimit = 'max_queries' | 'timeout_s' | 'max_cost_usd' | 'daily_max_usd'

/** 质询的回答 */
export interface InquiryAnswer {
  /** 渲染后的正文（数字已按出处换好） */
  text: string
  /** compose_doc 组装的文档工件：有它，正文里的数字可以点开看出处；没有（组装失败）只显示 text */
  doc_artifact: string | null
  ok: boolean
  limit: InquiryLimit | (string & {}) | null
  /** 没答成时的中文说明 */
  error: string | null
}

/** 核查模型为回答执行的一次只读查询。编号是这次质询自己的，快照按质询工件接口取（遮罩列已遮掉） */
export interface InquiryQuery {
  alias: string
  artifact: string
  sql: string
  row_count: number | null
  truncated: boolean
  /** 数据源名 */
  source: string | null
}

export interface InquiryUsage {
  input_tokens?: number
  output_tokens?: number
  cost_usd?: number | null
  calls?: number
  unpriced_calls?: number
}

/** 一次质询：问的是哪份报告的哪一句（或划选的哪段原文）、问了什么、怎么答的、查了什么 */
export interface Inquiry {
  /** 运行记录里那条 approval.inquiry 事件的序号；没写进运行记录时为 null */
  seq: number | null
  /** 什么时候问的（ISO 时间或秒级时间戳） */
  at: string | number | null
  /** 提问人的署名；没署名时为 null */
  actor: string | null
  /** 报告撰写节点 id */
  report: string
  /** 句子单元 id（如 u12）；就整份报告提问时为 null */
  unit: string | null
  /** 划选的原文 */
  quote: string | null
  question: string
  answer: InquiryAnswer
  queries: InquiryQuery[]
  /** 作答的核查模型 */
  model: string | null
  usage: InquiryUsage
  /** 运行封存之后才问的（只有探索运行可以） */
  post_seal: boolean
  /** 提问时停在的那张审批；封存之后问的为 null */
  approval_id: string | null
}

/** POST /runs/{id}/inquiries 的请求体 */
export interface InquiryRequest {
  report: string
  unit: string | null
  quote?: string | null
  question: string
  /** 运行停在审批上时必填：指明是哪一张 */
  approval_id?: string
}

/** POST /runs/{id}/inquiries 的答复 */
export interface InquiryResponse {
  inquiry: Inquiry
  /** 是否写进了运行记录 */
  recorded: boolean
  /** 没写进运行记录时的中文说明，否则为 null */
  note: string | null
}

/** GET /runs/{id}/inquiries 的答复 */
export interface InquiryList {
  items: Inquiry[]
}

/**
 * GET /runs/{id}/inquiries/artifacts/{artifact}：质询引用过的查询快照，遮罩列照证据面板的规则遮掉（值写「已遮罩」）。
 * 约定只说了是快照：可能是快照本身，也可能包在 {id, content} 里（同工件接口），界面两种都认
 */
export interface InquirySnapshot {
  columns: string[]
  rows: unknown[][]
  sql: string | null
  truncated: boolean
  /** 结果一共几行（快照的 row_count / total_rows），不给时按 rows 的长度 */
  total: number | null
  /** 遮掉的列 */
  masked: string[]
  source: string | null
}

// ---------------------------------------------------------------------------
// 应用平台（docs/design/app-platform-and-look.md）：运行来源、版本的发布 / 退役与使用情况、从运行提取的来源。
// 接口约定的主体在 typesApp.ts（冻结）；这里只往已有的类型上补字段，同名接口会合并
// ---------------------------------------------------------------------------

/** 运行来源（X3）。老运行四项都为空，界面写「来源未记录」 */
export interface Run {
  origin_kind?: import('./typesApp').OriginKind | null
  /** run.origin 事件的数据：kind、app_id、entry / view、hook、actor、actor_verified…… */
  origin?: Record<string, any> | null
  app_id?: string | null
  app_version?: number | null
}

/** 每个版本各自记发布、退役（A1、F5）；VersionDetailOut 另带入口表单和使用情况 */
export interface WorkflowVersion {
  level?: 'published' | 'governed' | null
  published_at?: string | null
  published_by?: string | null
  retired_at?: string | null
  retired_by?: string | null
  retire_note?: string | null
  /** 入口字段按 agentlab.form/1 转好的表单（服务端 input_schema(fields)），发起表单照它画 */
  input_schema?: import('./typesApp').FormSchema | null
  /** 被哪些应用固定、生效记录数、正式运行数（同 GET /api/ledger/workflow-versions/{wf}/{v}） */
  usage?: { apps: { app_id: string; name: string; app_version: number }[]; effects: number; formal_runs: number } | null
}

/** 从运行提取时的来源：run_id、对话、轮次（/copilot/from-run 写） */
export interface Workflow {
  origin?: Record<string, any> | null
}

/**
 * GET /api/datasources/names（应用平台 D-c）：开了登录、允许使用者问数据时，问数据页按它列可选的数据源。
 * 只有名字和说明，没有连接信息、表结构
 */
export interface DataSourceName {
  id: string
  name: string
  description?: string
  kind?: string
  enabled?: boolean
}

// ---------------------------------------------------------------------------
// 驳回 ≠ 失败（docs/design/next-round/05-已知遗留.md (a)，总方案 X9）

/** 运行为什么结束在 cancelled（服务端 Run.end_reason）：rejected 人工驳回，stopped 手动停止。其余终态、老运行为空 */
export type RunEndReason = 'rejected' | 'stopped'

export interface Run {
  end_reason?: RunEndReason | null
}

// ---------------------------------------------------------------------------
// 大库：对象索引、探查范围、后台探查（docs/design/next-round/03-数据接入与目录维护.md A1、A2，第 2 波 W2-a）

/** 探查范围的摘要（服务端 schema_cache.scope）：范围内几张、读到结构的、读不到的、范围外的、上限、各原因几张 */
export interface SchemaScope {
  in_scope: number
  reflected: number
  failed: number
  out_of_scope: number
  cap: number
  index_total: number
  pinned: number
  explicit: number
  rule: number
  on_demand: number
  /** dictionary 字典查询 / inspector 退回 Inspector（没有注释） */
  index_method?: string
  /** 对象索引超过了 5 万个的上限，只收了按名字排序的前面那些 */
  index_capped?: boolean
  index_at?: string
}

export type IntrospectJobStatus = 'queued' | 'running' | 'succeeded' | 'partial' | 'failed' | 'cancelled' | 'interrupted'

/** 同源队里排在前面的事（waiting_for）：起草、剖析、导入目录、同步起草 */
export type LaneKind = 'draft' | 'profile' | 'import' | 'sync_draft' | 'introspect'

/** 数据源卡片上最近一个探查任务（DataSourceOut.introspect_job） */
export interface IntrospectJobBrief {
  id: string
  status: IntrospectJobStatus
  total: number
  done: number
  failed: number
  cancelled: number
  waiting_for: LaneKind | null
  finished_at: string | null
  error: string | null
}

/** GET /datasources/{id}/introspect-jobs/{job_id} 的 job */
export interface IntrospectJob {
  id: string
  source_id: string
  status: IntrospectJobStatus
  /** manual 人点的 | schedule 定时维护 */
  trigger: string
  schema: string
  created_by: string | null
  created_at: string | null
  started_at: string | null
  finished_at: string | null
  total: number
  done: number
  counts: Record<'pending' | 'running' | 'ok' | 'failed' | 'cancelled', number>
  /** 正在读的那张表 */
  current: string | null
  /** 读不到结构的表（最多 50 张）和原因 */
  failures: { name: string; error: string | null }[]
  error: string | null
  /** 建任务那一刻的范围：规则原样、各原因几张、对象索引的情况 */
  scope: Partial<SchemaScope> & { rules?: IntrospectScopeRules; hits?: number; added?: number; removed?: number }
  waiting_for: LaneKind | null
}

/** 探查范围的规则（数据源 options.introspect_scope） */
export interface IntrospectScopeRules {
  mode: 'all' | 'rules'
  include: string[]
  exclude: string[]
  /** 显式列出：一律进范围 */
  tables: string[]
  /** 显式移出：有数据目录、被已发布模板用到的表也排得掉 */
  removed: string[]
  views: boolean
  max_tables: number
  updated_by?: string | null
  updated_at?: string | null
}

/** 按规则对着对象索引数的命中 */
export interface IntrospectScopePreview {
  in_scope: number
  /** 计上限的那部分（规则、一律在范围内、显式列出；按需加入的另算） */
  hits: number
  cap: number
  out_of_scope: number
  index_total: number
  pinned: number
  explicit: number
  rule: number
  on_demand: number
  over: boolean
}

/** 按需加入、目录页手工加入范围的留痕 */
export interface IntrospectScopeTrail {
  name: string
  scope_reason: string | null
  /** look 助手查看 | db_schema 运行时查表结构 | catalog 目录页 */
  via: 'look' | 'db_schema' | 'catalog' | null
  by: string | null
  run_id: string | null
  conversation_id: string | null
  ref: string | null
  need: string | null
  at: string | null
}

/** GET / PUT /datasources/{id}/introspect-scope、POST …/preview */
export interface IntrospectScope {
  scope: IntrospectScopeRules
  defaults: { max_tables: number; max_limit: number; index_limit: number; rules_max: number }
  /** 没有对象索引时为 null：先刷新对象索引才数得出命中 */
  preview: IntrospectScopePreview | null
  index: { ready: boolean; schema: string; method: string | null; capped: boolean; at: string | null; total: number | null }
  /** 一律在范围内的表（举前 20 个例子） */
  pinned_sample: string[]
  on_demand: IntrospectScopeTrail[]
}

export interface DataSource {
  /** 探查范围的摘要；升级前探查的源、上传表格为 null */
  schema_scope?: SchemaScope | null
  /** 最近一个探查任务；没有（或升级前同步探查的）为 null */
  introspect_job?: IntrospectJobBrief | null
}

/**
 * 表结构里没有这张表时为什么（目录清单、表详情的 absent_reason）：removed 表已不在（真删除）、missing 数据源里从来没有、
 * out_of_scope 在探查范围外、reflect_failed 在范围里却读不到结构、unknown 说不清（升级前只探查了一部分的老缓存）
 */
export type CatalogAbsentReason = 'removed' | 'missing' | 'out_of_scope' | 'reflect_failed' | 'unknown'

export interface CatalogTableRow {
  absent_reason?: CatalogAbsentReason | null
}

export interface CatalogDetail {
  absent_reason?: CatalogAbsentReason | null
}

export interface CatalogList {
  /** 探查范围的摘要；升级前探查的源、上传表格为 null */
  scope?: SchemaScope | null
}

/** GET /datasources/{id}/catalog/search 的一项：对象索引里按名字、注释找到的表（含探查范围外的） */
export interface CatalogSearchItem {
  name: string
  qualified: string
  kind: 'table' | 'view'
  comment: string | null
  est_rows: number | null
  in_scope: boolean
  scope_reason: string | null
  absent_reason: CatalogAbsentReason | null
}

export interface CatalogSearch {
  items: CatalogSearchItem[]
  total: number
  /** 有对象索引（没有的只在表结构里找） */
  indexed: boolean
}

/** POST /datasources/{id}/catalog/scope/add */
export interface CatalogScopeAdd {
  added: string[]
  already: string[]
  failed: { name: string; error: string }[]
  refused: { name: string; reason: string }[]
  scope: SchemaScope | null
}