/**
 * 治理台路由契约(编码规范 §8.1 / §9.1)。
 * 治理台九功能不设后端 governance 模块:每个功能是对应模块的管理用例 + 本文件的路由组装(§3)。
 */
import { z } from 'zod';
import type { RouteContract } from './http.ts';
import {
  disableCheckSchema,
  grantSchema,
  inFlightWorkSchema,
  positionSchema,
  roleAccessSchema,
  rosterSyncOutcomeSchema,
  staffSchema,
  workGroupSchema,
} from '../org.ts';
import { surfaceSchema } from './http.ts';
import { positionIdSchema, staffIdSchema, taskIdSchema } from '../id.ts';
import { ledgerObjectKindSchema } from '../ledger.ts';
import { approvalTemplateSchema, closureReportSchema, processPackageSchema, triggerConfigSchema } from '../process-package.ts';
import { controlSemanticSchema, taskRuntimeStateSchema, terminalStateSchema, workflowStateSchema } from '../terminal.ts';
import { activityManifestSchema } from '../manifest.ts';
import { reportMetricsSchema, reportPeriodSchema } from './workbench.ts';

/* ── 员工管理 ─────────────────────────────────────────────────────────── */

export const listStaffRoute = {
  method: 'GET',
  path: '/api/gov/staff',
  access: ['design', 'ops'],
  output: z.object({
    staff: z.array(staffSchema.extend({ position: positionSchema })),
    positions: z.array(positionSchema),
  }),
} as const satisfies RouteContract;

/** @deprecated 随 ADR-012 退役,后端回 410;人来自 Keycloak,改用 syncStaffRoute */
export const createStaffRoute = {
  method: 'POST',
  path: '/api/gov/staff',
  access: 'public',
  body: z.object({
    account: z.string().min(1),
    name: z.string().min(1),
    positionId: positionIdSchema,
  }),
  output: staffSchema,
} as const satisfies RouteContract;

/** @deprecated 随 ADR-012 退役,后端回 410;改用 staffInFlightRoute */
export const disableStaffCheckRoute = {
  method: 'GET',
  path: '/api/gov/staff/:staffId/disable-check',
  access: 'public',
  params: z.object({ staffId: staffIdSchema }),
  output: disableCheckSchema,
} as const satisfies RouteContract;

/** @deprecated 随 ADR-012 退役,后端回 410;停用改在 Keycloak 做,名册同步据此落 disabled */
export const disableStaffRoute = {
  method: 'POST',
  path: '/api/gov/staff/:staffId/disable',
  access: 'public',
  params: z.object({ staffId: staffIdSchema }),
  output: z.object({ ok: z.boolean(), check: disableCheckSchema }),
} as const satisfies RouteContract;

/** @deprecated 随 ADR-012 退役,后端回 410;权限只到端,改用 listRoleAccessRoute */
export const listGrantsRoute = {
  method: 'GET',
  path: '/api/gov/positions/:positionId/grants',
  access: 'public',
  params: z.object({ positionId: positionIdSchema }),
  output: z.object({ grants: z.array(grantSchema) }),
} as const satisfies RouteContract;

/** @deprecated 随 ADR-012 退役,后端回 410;权限只到端,改用 setRoleAccessRoute */
export const setGrantsRoute = {
  method: 'POST',
  path: '/api/gov/positions/:positionId/grants',
  access: 'public',
  params: z.object({ positionId: positionIdSchema }),
  body: z.object({ grants: z.array(grantSchema) }),
  output: z.object({ grants: z.array(grantSchema) }),
} as const satisfies RouteContract;

/* ── 员工管理 · 名册与岗位(ADR-012:人来自鉴权中心,岗位本地指派) ────── */

/** 从 Keycloak Admin API 同步名册;没配 provisioning 服务账号就如实回 configured:false */
export const syncStaffRoute = {
  method: 'POST',
  path: '/api/gov/staff/sync',
  access: 'ops',
  output: rosterSyncOutcomeSchema,
} as const satisfies RouteContract;

/** 指派岗位;指回哨兵岗 NONE = 取消指派 */
export const setStaffPositionRoute = {
  method: 'PUT',
  path: '/api/gov/staff/:staffId/position',
  access: 'ops',
  params: z.object({ staffId: staffIdSchema }),
  body: z.object({ positionId: positionIdSchema }),
  output: staffSchema.extend({ position: positionSchema }),
} as const satisfies RouteContract;

/** 此人身上还挂着什么(只读)—— 原「停用前置检查」;停用本身在 Keycloak 做 */
export const staffInFlightRoute = {
  method: 'GET',
  path: '/api/gov/staff/:staffId/in-flight',
  access: 'ops',
  params: z.object({ staffId: staffIdSchema }),
  output: inFlightWorkSchema,
} as const satisfies RouteContract;

/* ── 角色 → 端(ADR-012:权限只到端,这张表运营中心可改) ─────────────── */

export const listRoleAccessRoute = {
  method: 'GET',
  path: '/api/gov/access/roles',
  access: 'ops',
  output: z.object({
    roles: z.array(roleAccessSchema),
    /** 名册上见过的角色 ∪ 已配置的角色 —— 配置前它等于「无端可进」 */
    knownRoles: z.array(z.string()),
  }),
} as const satisfies RouteContract;

/** 锁死不变量不过(改完没人能进运营中心)→ 409 conflict */
export const setRoleAccessRoute = {
  method: 'PUT',
  path: '/api/gov/access/roles/:role',
  access: 'ops',
  params: z.object({ role: z.string().min(1) }),
  body: z.object({ ends: z.array(surfaceSchema) }),
  output: roleAccessSchema,
} as const satisfies RouteContract;

export const deleteRoleAccessRoute = {
  method: 'DELETE',
  path: '/api/gov/access/roles/:role',
  access: 'ops',
  params: z.object({ role: z.string().min(1) }),
  output: z.object({ ok: z.boolean() }),
} as const satisfies RouteContract;

/* ── 系统管理 · LLM 实例(四元绑定) ────────────────────────────────── */

export const LLM_PROVIDERS = ['openai-compatible', 'openai', 'deepseek', 'anthropic', 'qwen'] as const;
export const llmProviderSchema = z.enum(LLM_PROVIDERS);
export type LlmProvider = z.infer<typeof llmProviderSchema>;

/** 活动只见自定义模型名;Provider / URL / API-Key / Model 四元在系统侧绑定,活动不触厂商与密钥 */
export const llmInstanceViewSchema = z.object({
  id: z.string(),
  /** 自定义模型名(逻辑名)—— 活动以此声明引用 */
  name: z.string().min(1),
  provider: llmProviderSchema,
  baseUrl: z.string().min(1),
  model: z.string().min(1),
  /** 密钥不出治理台:只回是否已绑定,永不回明文(OS 7.3 凭证隔离) */
  apiKeyBound: z.boolean(),
  /** 系统用途绑定:叙述性小结 / 汇报生成 / 蒸馏钩子,计量入系统账 */
  systemUse: z.boolean().default(false),
  enabled: z.boolean().default(true),
});
export type LlmInstanceView = z.infer<typeof llmInstanceViewSchema>;

/**
 * Provider 一览 —— 建实例那张表要**预填默认端点**,而唯一真相在服务端的 provider 档案里。
 * 前端不自带一份 URL 表:那种表迟早与服务端漂移,漂移的那天没人会发现(端点错了只表现为「连不上」)。
 */
export const listLlmProvidersRoute = {
  method: 'GET',
  path: '/api/gov/llm/providers',
  access: 'design',
  output: z.object({
    providers: z.array(
      z.object({
        provider: llmProviderSchema,
        label: z.string(),
        /** 留空即取它;`openai-compatible` 没有默认,回空串 —— 界面据此要求自填 */
        defaultBaseUrl: z.string(),
        /** 结构化出参口径:json-object = 厂商原生支持;prompt-only = 靠提示约束 */
        structuredOutput: z.enum(['json-object', 'prompt-only']),
      }),
    ),
  }),
} as const satisfies RouteContract;

export const listLlmInstancesRoute = {
  method: 'GET',
  path: '/api/gov/llm',
  access: 'design',
  output: z.object({ instances: z.array(llmInstanceViewSchema) }),
} as const satisfies RouteContract;

export const upsertLlmInstanceRoute = {
  method: 'POST',
  path: '/api/gov/llm',
  access: 'design',
  body: z.object({
    id: z.string().optional(),
    name: z.string().min(1),
    provider: llmProviderSchema,
    /** 留空 = 取该 provider 的默认端点(openai-compatible 没有默认,必须自填) */
    baseUrl: z.string().default(''),
    model: z.string().min(1),
    /** 只写不读:留空表示保持原值 */
    apiKey: z.string().optional(),
    systemUse: z.boolean().default(false),
    enabled: z.boolean().default(true),
  }),
  output: llmInstanceViewSchema,
} as const satisfies RouteContract;

/**
 * 测试连接(草稿)—— **只测不存**:拿表单上正填的四元真发一次最小调用,一个字节不落库。
 * 「测试」把表单写进库是个会咬人的副作用:人只想知道钥匙对不对,取消却收不回已改的端点。
 * 留空 `apiKey` 时取该实例已存的密钥(改端点、换型号不必重打钥匙)。
 */
/**
 * 删一条模型实例 —— 还有活动声明着它的用途名就拒(409):
 * 删了那些活动一调模型就是「用途名未绑定」,而人当时以为只是清掉一条没用的记录。
 */
export const deleteLlmInstanceRoute = {
  method: 'DELETE',
  path: '/api/gov/llm/:id',
  access: 'design',
  params: z.object({ id: z.string() }),
  output: z.object({ ok: z.boolean() }),
} as const satisfies RouteContract;

export const probeLlmDraftRoute = {
  method: 'POST',
  path: '/api/gov/llm/probe',
  access: 'design',
  body: z.object({
    id: z.string().optional(),
    name: z.string().optional(),
    provider: llmProviderSchema,
    baseUrl: z.string().default(''),
    model: z.string().min(1),
    apiKey: z.string().optional(),
  }),
  output: z.object({ ok: z.boolean(), latencyMs: z.number().int().optional(), error: z.string().optional() }),
} as const satisfies RouteContract;

export const probeLlmInstanceRoute = {
  method: 'POST',
  path: '/api/gov/llm/:id/probe',
  access: 'design',
  params: z.object({ id: z.string() }),
  output: z.object({ ok: z.boolean(), latencyMs: z.number().int().optional(), error: z.string().optional() }),
} as const satisfies RouteContract;

/* ── 任务管理:在途监控 · 控制事件 · 改派 ─────────────────────────────── */

export const govTaskRowSchema = z.object({
  id: taskIdSchema,
  title: z.string(),
  activityId: z.string(),
  ownerName: z.string(),
  runtime: taskRuntimeStateSchema,
  terminal: terminalStateSchema.optional(),
  workflowId: z.string().optional(),
  usedSteps: z.number().int(),
  capSteps: z.number().int(),
  startedAt: z.string(),
});
export type GovTaskRow = z.infer<typeof govTaskRowSchema>;

export const listGovTasksRoute = {
  method: 'GET',
  path: '/api/gov/tasks',
  access: 'ops',
  output: z.object({
    tasks: z.array(govTaskRowSchema),
    workflows: z.array(
      z.object({
        id: z.string(),
        subject: z.string(),
        state: workflowStateSchema,
        packageId: z.string(),
        startedAt: z.string(),
      }),
    ),
  }),
} as const satisfies RouteContract;

/** 控制三语义:暂停 / 叫停 / 终止 —— 治理台的干预面(OS 06) */
export const controlTaskRoute = {
  method: 'POST',
  path: '/api/gov/tasks/:taskId/control',
  access: 'ops',
  params: z.object({ taskId: taskIdSchema }),
  body: z.object({ semantic: controlSemanticSchema, reason: z.string().optional() }),
  output: z.object({ ok: z.boolean(), resumable: z.boolean() }),
} as const satisfies RouteContract;

export const resumeTaskRoute = {
  method: 'POST',
  path: '/api/gov/tasks/:taskId/resume',
  access: 'ops',
  params: z.object({ taskId: taskIdSchema }),
  output: z.object({ ok: z.boolean(), runtime: taskRuntimeStateSchema }),
} as const satisfies RouteContract;

/** 改派 —— 在途任务的负责人变更,留痕并通知双方 */
export const reassignTaskRoute = {
  method: 'POST',
  path: '/api/gov/tasks/:taskId/reassign',
  access: 'ops',
  params: z.object({ taskId: taskIdSchema }),
  body: z.object({ to: staffIdSchema }),
  output: z.object({ ok: z.boolean(), ownerId: staffIdSchema }),
} as const satisfies RouteContract;

/** 任务日志 —— 治理台可查看任意任务的任务日志(OS 02) */
export const govTaskLogRoute = {
  method: 'GET',
  path: '/api/gov/tasks/:taskId/log',
  access: 'ops',
  params: z.object({ taskId: taskIdSchema }),
  output: z.object({
    // 与工作台同一份日志:章是四字动作,内容带主语(见 workbench 的 log 项)
    log: z.array(
      z.object({ id: z.string(), at: z.string(), sideLabel: z.string(), action: z.string(), title: z.string() }),
    ),
  }),
} as const satisfies RouteContract;

/* ── 工作流管理:流程包编排与版本 ─────────────────────────────────────── */

export const listProcessPackagesRoute = {
  method: 'GET',
  path: '/api/gov/process',
  access: ['design', 'ops'],
  output: z.object({ packages: z.array(processPackageSchema) }),
} as const satisfies RouteContract;

/**
 * 保存流程包 —— **严格检查 + 保存即生效**,没有发布这一道门。
 *
 * 不闭合即拒存(412 带闭合报告):存下来的就是能起单的。
 * 保存**恒产生新版本号**,由服务端算 —— body 里的 `version` 只用于「改的是哪一版」的溯源,
 * 服务端不采信它当目标版本号。在途工作流按 (包id, 版本) 读定义,就地覆盖会改掉它们读的东西。
 * 返回的 `pkg.version` 是**实际落的新版本**,`report` 是这一版的闭合报告(必然 closed)。
 */
export const saveProcessRoute = {
  method: 'PUT',
  path: '/api/gov/process',
  access: 'design',
  /**
   * 编辑即其身:pkg.version 已存在 → 就地写回该版(号不变)。
   * `asNew: true`(或版本不存在,如新流程首版)→ 产生新版本号(服务端算,不生效)。
   * 就地写回的两道闸:在途钉版 409;写回生效版不闭合 412(带整份报告)。
   */
  body: z.object({ pkg: processPackageSchema, asNew: z.boolean().optional() }),
  output: z.object({ pkg: processPackageSchema, report: closureReportSchema }),
} as const satisfies RouteContract;

/**
 * 版本启停 —— 运行时开关,不改定义一个字。
 * 激活某版:同流其余版本一并停用(一条流恰一个生效版本);停用生效版:整条流下线,新起单被拒。
 * 在途工作流按启动时钉住的版本跑完,启停对它们零影响。
 * 返回这条流启停后的全部版本(新→旧),界面直接以它刷新版本列表。
 */
export const setProcessStateRoute = {
  method: 'POST',
  path: '/api/gov/process/:id/:version/state',
  access: 'design',
  params: z.object({ id: z.string(), version: z.string() }),
  body: z.object({ state: z.enum(['active', 'retired']) }),
  output: z.object({ packages: z.array(processPackageSchema) }),
} as const satisfies RouteContract;

/**
 * 删一版 —— 两道闸(2026-07-30):
 *   · **生效版不可删**:先停用,免得手滑把正在起单的定义删了;
 *   · **在途钉版不可删**:那些单要按它跑完,定义没了就再也推不动。
 */
export const deleteProcessVersionRoute = {
  method: 'DELETE',
  path: '/api/gov/process/:id/:version',
  access: 'design',
  params: z.object({ id: z.string(), version: z.string() }),
  output: z.object({ packages: z.array(processPackageSchema) }),
} as const satisfies RouteContract;

/* ── 审批模板(审批活动)──────────────────────────────────────────────── */

/** 审批模板一览 —— 活动库里「审批活动」那一格看的就是它 */
export const listApprovalTemplatesRoute = {
  method: 'GET',
  path: '/api/gov/approval-templates',
  access: 'design',
  output: z.object({
    templates: z.array(
      approvalTemplateSchema.extend({
        /** 被哪些流程包的审批点引着 —— 删之前要能看见 */
        usedBy: z.array(z.object({ packageId: z.string(), nodeId: z.string() })),
      }),
    ),
  }),
} as const satisfies RouteContract;

/** 建或改一张模板 —— id 已存在即覆盖(模板是配置,不长版本) */
export const upsertApprovalTemplateRoute = {
  method: 'PUT',
  path: '/api/gov/approval-templates',
  access: 'design',
  body: z.object({ template: approvalTemplateSchema }),
  output: z.object({ template: approvalTemplateSchema }),
} as const satisfies RouteContract;

/** 删一张模板 —— 还被审批点引着就拒(409):删了引它的节点会退回「载荷全摊开」 */
export const deleteApprovalTemplateRoute = {
  method: 'DELETE',
  path: '/api/gov/approval-templates/:id',
  access: 'design',
  params: z.object({ id: z.string() }),
  output: z.object({ ok: z.boolean() }),
} as const satisfies RouteContract;

/**
 * 删整条流 —— 连同它的**所有版本**。货架上一条流一张卡,删的就是那张卡。
 * 两道闸:任一版有在途单即拒(那些单要按它跑完);还有调起规则指着它也拒 ——
 * 删了包留着规则,那规则再命中就调不动任何东西,是个哑火的配置。
 */
export const deleteProcessFlowRoute = {
  method: 'DELETE',
  path: '/api/gov/process/:id',
  access: 'design',
  params: z.object({ id: z.string() }),
  output: z.object({ packages: z.array(processPackageSchema) }),
} as const satisfies RouteContract;

/**
 * 改版本记录 —— **版本号自己定**(2026-07-29 用户定)、名字随之:改哪版只动哪版。
 *
 * 号从前只能由系统递增。设计人员要能自己编号(1 / 2 / 10 都行),所以放开;
 * 两条约束是数据本身要求的:号不许撞同流已有版本;**在途钉版不许改号**
 * (那些单正按这个号找定义)。已完结的单跟着改指 —— 号只是这一版的名牌,
 * 搬号连引用一起搬,留痕仍指同一份定义。
 */
export const editProcessVersionRoute = {
  method: 'POST',
  path: '/api/gov/process/:id/:version/edit',
  access: 'design',
  params: z.object({ id: z.string(), version: z.string() }),
  body: z.object({
    version: z.number().int().min(1).max(9999).optional(),
    name: z.string().min(1).max(40).optional(),
  }),
  output: z.object({ packages: z.array(processPackageSchema) }),
} as const satisfies RouteContract;

/** 画图即校验 —— 与前端画布同源;保存前随手看还差几条,不改任何状态 */

export const validateProcessRoute = {
  method: 'POST',
  path: '/api/gov/process/validate',
  access: 'design',
  body: z.object({ pkg: processPackageSchema }),
  output: closureReportSchema,
} as const satisfies RouteContract;

/* ── 触发器配置 ──────────────────────────────────────────────────────── */

export const listTriggersRoute = {
  method: 'GET',
  path: '/api/gov/triggers',
  access: ['design', 'ops'],
  output: z.object({ triggers: z.array(triggerConfigSchema) }),
} as const satisfies RouteContract;

export const toggleTriggerRoute = {
  method: 'POST',
  path: '/api/gov/triggers/:id/toggle',
  access: 'ops',
  params: z.object({ id: z.string() }),
  body: z.object({ enabled: z.boolean() }),
  output: z.object({ ok: z.boolean() }),
} as const satisfies RouteContract;

/**
 * 调起规则的**定义面**(设计中心):新建 / 改规则 / 改起单装配。
 *
 * 与 `toggleTriggerRoute` 分开是有意的:定义归设计,启停归运营 ——
 * 同一个触发器,「它按什么规则调起」和「今天开不开」是两个人在两个台面上做的两件事。
 * 触发器与流程包平级:改它**不动任何包版本**。
 */
export const upsertTriggerRoute = {
  method: 'PUT',
  path: '/api/gov/triggers',
  access: 'design',
  body: z.object({ trigger: triggerConfigSchema }),
  output: z.object({ trigger: triggerConfigSchema }),
} as const satisfies RouteContract;

/* ── 员工管理 · 工作组(ADR-011) ───────────────────────────────────── */

/**
 * 工作组 = 一组「岗位 → 员工」的绑定,**起单时装载、随工作流走**。
 *
 * 它是**绑定先于策略**,不是第五种负责人策略:起单人有组,整条流的岗位就按组指人;
 * 没有组才回落四策略。装进工作流的是**快照** —— 改组不改已起的单。
 */
export const listWorkGroupsRoute = {
  method: 'GET',
  path: '/api/gov/work-groups',
  access: 'ops',
  /** `ownerName` 是组长姓名的呈现补充,读表时一并带出,免得前端再对一次 id */
  output: z.object({ groups: z.array(workGroupSchema.extend({ ownerName: z.string() })) }),
} as const satisfies RouteContract;

/** 一人一组:按 `ownerId` 落,已有即更新、没有即新建 */
export const saveWorkGroupRoute = {
  method: 'PUT',
  path: '/api/gov/work-groups',
  access: 'ops',
  body: z.object({
    ownerId: staffIdSchema,
    name: z.string().min(1),
    /** 岗位 code → 员工 id;留空的岗位不绑定,那一位仍走四策略 */
    members: z.record(z.string().min(1), staffIdSchema),
  }),
  output: z.object({ group: workGroupSchema }),
} as const satisfies RouteContract;

/* ── 活动库 · 装入 / 换版(安装通道) ─────────────────────────────── */

/**
 * 经安装通道装入活动包 —— **无代码通道**(ADR-004):交的是清单 + .js 产物,都是数据。
 *
 * 安装两审在服务端跑:静态审读清单(工具契约在否、模型名绑没绑、模版有没有脚本、
 * 声明与已物化的台账冲不冲),回放审重演历史(首装无历史即免,以样例集替代)。
 * **恒为新增、版本并存**:装入不覆盖旧版本,在途任务按其启动时版本跑完。
 * **路径(2026-08-27)**:`/api/gov/activity-packages` —— 从前叫 `/api/gov/activities`;那个前缀整个让给了运营端
 * 活动模块(L1/L2/L3,`api/activity-ops.ts`),这里管的是**包**(版本 / 资产 / 装入),名副其实。
 */
export const installActivityRoute = {
  method: 'POST',
  path: '/api/gov/activity-packages',
  access: 'design',
  body: z.object({
    /** 清单六区:身份 / 七件契约 / 声明 / 资产初始版 / 样例集 / 代码入口 */
    manifest: activityManifestSchema,
    /** .js 产物原文 —— 只当数据存,不 import、不 eval */
    artifact: z.string().min(1),
  }),
  output: z.object({
    accepted: z.boolean(),
    activityId: z.string(),
    packageVersion: z.string(),
    staticFindings: z.array(z.object({ code: z.string(), severity: z.string(), message: z.string() })),
    replay: z.object({
      oldPassStillPass: z.boolean(),
      checked: z.number().int(),
      skippedNoHistory: z.boolean(),
      regressions: z.array(z.object({ taskId: z.string(), detail: z.string() })),
    }),
  }),
} as const satisfies RouteContract;

/* ── 工具管理 · 导入自定义工具 ─────────────────────────────────────── */

/**
 * 导入自定义工具 —— 与第一方工具走**同一条门**:静态审 + 试运行审。
 *
 * 工具承载权力,约束严于活动包:契约对活动、实现对系统、凭证对治理台(OS 7.3)。
 * 连接配置**只声明键**;值随本次导入送到治理台加密落库,此后只读得到「是否已绑定」。
 */
export const registerToolRoute = {
  method: 'POST',
  path: '/api/gov/tools',
  access: 'design',
  body: z.object({
    contract: z.object({
      name: z.string().min(1),
      /** 中文名 —— 治理台主显示;不给就以逻辑名兜底(界面宁可显示机器名,不显示空白) */
      displayName: z.string().min(1).optional(),
      version: z.string().min(1),
      description: z.string().min(1),
      input: z.record(z.string(), z.unknown()),
      output: z.record(z.string(), z.unknown()),
      effect: z.enum(['read', 'write']),
      errors: z
        .array(z.object({ code: z.string(), retryable: z.boolean(), message: z.string() }))
        .default([]),
      idempotent: z.boolean().default(true),
      timeoutMs: z.number().int().positive().default(10_000),
      retries: z.number().int().min(0).default(1),
      connectionKeys: z.array(z.string()).default([]),
    }),
    /** 连接值只写不读 —— 键在契约里,值密封在治理台 */
    connectionValues: z.record(z.string(), z.string()).optional(),
    /** 契约测试集:没有样例就没有试运行审,门形同虚设 */
    samples: z.array(z.object({ input: z.record(z.string(), z.unknown()) })).min(1),
  }),
  output: z.object({
    accepted: z.boolean(),
    findings: z.array(z.object({ code: z.string(), severity: z.string(), message: z.string() })),
    trialRun: z.object({ ran: z.number().int(), passed: z.number().int(), failures: z.array(z.string()) }),
  }),
} as const satisfies RouteContract;

/* ── 活动库管理:两维分类 × 包版本 × 资产版本 ─────────────────────────── */

/** 路径同 `installActivityRoute` 的说明:`/api/gov/activity-packages`(2026-08-27 让位给运营端活动模块) */
export const listActivitiesRoute = {
  method: 'GET',
  path: '/api/gov/activity-packages',
  access: 'design',
  output: z.object({
    activities: z.array(
      z.object({
        activityId: z.string(),
        name: z.string(),
        category: z.string(),
              enabled: z.boolean(),
        packageVersions: z.array(z.object({ version: z.string(), state: z.string(), installedAt: z.string() })),
        assetVersions: z.array(z.object({ kind: z.string(), version: z.number().int(), effective: z.boolean() })),
        /**
         * 契约面 —— 开发这个活动要照着的东西:吃什么、吐什么、用谁的工具、动哪些域对象。
         * 治理台不给这一层,「编排定契约」就只是句口号:编排的人看不到自己引用的活动要什么。
         */
        contract: z.object({
          requiredInputs: z.array(z.string()),
          inputFields: z.array(
            z.object({
              name: z.string(),
              type: z.string(),
              required: z.boolean(),
              /** 人读名(清单里的 title)—— 表单上摆中文,不摆字段名 */
              label: z.string().optional(),
              /** `file` = 这一格收**真文件**(界面给文件选择器);缺席 = 普通文本格 */
              format: z.string().optional(),
              /** 声明了枚举 → 界面给下拉选,不给自由文本框猜合法值 */
              options: z.array(z.object({ value: z.string(), label: z.string() })).optional(),
              /** 示例值(JSON Schema `examples` 第一项)—— 占位提示用,比裸类型名能抄 */
              example: z.string().optional(),
              /** 声明了 → 只在另一格(`field`)等于 `equals` 时才出现(级联下拉那类场景) */
              showWhen: z.object({ field: z.string(), equals: z.string() }).optional(),
            }),
          ),
          /**
           * 包自带的样例集 —— 试跑一个活动时**照它预填**。
           * 「首装审以静态审 + 样例集替代回放审」的那份样例,本来就是这个活动
           * 「一单长什么样」的权威说法;让人对着空表单自己编,编出来的多半跑不通。
           */
          samples: z.array(z.object({ name: z.string(), input: z.record(z.string(), z.unknown()) })).default([]),
          outputPorts: z.array(
            z.object({
              name: z.string(),
              description: z.string().optional(),
              /** 字段名 + 类型;**数组写成 `T[]`**(如 `object[]`)—— 声明得看得出是不是一串 */
              fields: z.array(z.object({ name: z.string(), type: z.string() })),
            }),
          ),
          tools: z.array(z.string()),
          models: z.array(z.string()),
          objects: z.array(z.string()),
          roles: z.array(z.string()),
          humanCallBudget: z.number().int(),
        }),
      }),
    ),
  }),
} as const satisfies RouteContract;

/* ── 工具管理 ────────────────────────────────────────────────────────── */

export const listToolsRoute = {
  method: 'GET',
  path: '/api/gov/tools',
  access: 'design',
  output: z.object({
    tools: z.array(
      z.object({
        name: z.string(),
        /** 中文名 —— 治理台主显示;逻辑名退居副标 */
        displayName: z.string(),
        version: z.string(),
        description: z.string(),
        effect: z.enum(['read', 'write']),
        pure: z.boolean(),
        connectionKeys: z.array(z.string()),
      }),
    ),
  }),
} as const satisfies RouteContract;

/* ── 数据管理:域 / 对象目录 + 记录浏览 ───────────────────────────────── */

export const listLedgerObjectsRoute = {
  method: 'GET',
  path: '/api/gov/data/objects',
  access: ['design', 'ops'],
  /** `label` 是人读名(落在表注释上);缺省即没登记,呈现退回对象键 */
  output: z.object({
    objects: z.array(
      z.object({
        domain: z.string(),
        object: z.string(),
        label: z.string().optional(),
        /**
         * 这张表的**性质**(单据 / 主数据 / 派生)—— 取自装在库里的活动清单声明。
         *
         * 物化出来的物理表本身不知道自己是什么:表里只有列和主键。
         * 而「该不该管它、谁有权改它」全看性质,所以这一维必须摆到治理台上 ——
         * 从前没有它,一屏 19 张表看着一模一样,人分不出哪几张是要治理的主数据。
         * 缺省 = 库里有这张表,却没有哪个在装的活动声明它(多半是退役活动留下的壳)。
         */
        kind: ledgerObjectKindSchema.optional(),
        /** 单据的单标识列名 —— 呈现上摆出来,人一眼看得出「这张表按什么分单」 */
        caseKey: z.string().optional(),
      }),
    ),
  }),
} as const satisfies RouteContract;

/**
 * **按活动看数据域**(2026-08-24 用户定:「按活动数据来分类,要让每个活动执行完成后
 * 台账在这里看到变化」)。
 *
 * 从前这一屏按**性质**(主数据/单据/派生)分组 —— 那是给「治理这张表」的人用的分法,
 * 回答的是「这个对象定义全不全」。而人跑完一单来这儿,问的是另一件事:
 * **我这个活动写了哪几张表,现在各有几行,刚才那一单落下了什么**。
 * 按活动分组、带上行数,那个问题才答得了。
 *
 * 三个数各有各的意思,不能混:
 *   · `rows` —— 正式表里现在有几行(过了放行门的事实);
 *   · `drafts` —— 还在某一单草稿层的几行(**在办中,放行才进正式表**);
 *   · `recent` —— 这个活动最近几单,让人认出「刚跑完的那一单」。
 */
export const ledgerByActivityRoute = {
  method: 'GET',
  path: '/api/gov/data/by-activity',
  access: ['design', 'ops'],
  output: z.object({
    activities: z.array(
      z.object({
        activityId: z.string(),
        name: z.string(),
        version: z.string().optional(),
        tables: z.array(
          z.object({
            domain: z.string(),
            object: z.string(),
            label: z.string().optional(),
            kind: z.string().optional(),
            caseKey: z.string().optional(),
            primaryKey: z.array(z.string()),
            /** 正式表行数;表还没物化(活动声明了但一次都没写过)时缺席 */
            rows: z.number().int().optional(),
            /** 还在草稿层的行数(在办中的单写下的) */
            drafts: z.number().int(),
            /** 草稿层最近一次落笔的时刻 —— 在办中才有 */
            draftAt: z.string().optional(),
          }),
        ),
        /** 这个活动最近几单 —— 「刚跑完那一单」在这儿认得出来 */
        recent: z.array(
          z.object({
            id: z.string(),
            title: z.string(),
            runtime: z.string(),
            terminal: z.string().optional(),
            at: z.string(),
          }),
        ),
      }),
    ),
    /** 库里有表、却没有哪个在装的活动声明它 —— 多半是退役活动留下的空壳 */
    unclaimed: z.array(
      z.object({ domain: z.string(), object: z.string(), label: z.string().optional(), rows: z.number().int().optional() }),
    ),
  }),
} as const satisfies RouteContract;

export const browseLedgerRoute = {
  method: 'GET',
  path: '/api/gov/data/:domain/:object',
  access: ['design', 'ops'],
  params: z.object({ domain: z.string(), object: z.string() }),
  output: z.object({
    label: z.string().optional(),
    columns: z.array(z.object({ name: z.string(), type: z.string(), label: z.string().optional() })),
    primaryKey: z.array(z.string()),
    rows: z.array(z.record(z.string(), z.unknown())),
    total: z.number().int(),
  }),
} as const satisfies RouteContract;

/* ── 记忆管理:活动记忆四层 ──────────────────────────────────────────── */

export const listActivityMemoryRoute = {
  method: 'GET',
  path: '/api/gov/memory/:activityId',
  access: 'design',
  params: z.object({ activityId: z.string() }),
  output: z.object({
    entries: z.array(
      z.object({
        id: z.string(),
        layer: z.string(),
        statement: z.string(),
        evidenceCount: z.number().int(),
        incrementState: z.string().optional(),
        createdAt: z.string(),
      }),
    ),
  }),
} as const satisfies RouteContract;

/* ── 系统管理 · 通道实例 ──────────────────────────────────────────────── */

/** 通道配置里本就没有凭证字段(凭证只在治理台的连接配置中,ADR-009);此处整体可回 */
export const listChannelsRoute = {
  method: 'GET',
  path: '/api/gov/channels',
  access: ['design', 'ops'],
  output: z.object({
    channels: z.array(
      z.object({
        id: z.string(),
        name: z.string(),
        kind: z.enum(['mail', 'im']),
        address: z.string(),
        enabled: z.boolean(),
        extractCount: z.number().int(),
        /**
         * 抽键规则原文 —— 测试台的**抽键预检**要在人打字时就点灯,
         * 跑的必须是与服务端同一套正则,不是前端另编的一套(正则不是密钥,回它无妨)。
         */
        extract: z
          .array(z.object({ key: z.string(), regex: z.string(), source: z.enum(['subject', 'body', 'from', 'to', 'both']) }))
          .default([]),
        mappingCount: z.number().int(),
        fallbackPosition: z.string().optional(),
        addressWindowMs: z.number().int(),
      }),
    ),
  }),
} as const satisfies RouteContract;

/* ── 任务管理 · 审批单 ────────────────────────────────────────────────── */

/** 审批单不是任务:没有预算、没有任务日志,只有批不批(卡在审批人工位的验收工单) */
export const listApprovalsRoute = {
  method: 'GET',
  path: '/api/gov/approvals',
  access: 'ops',
  output: z.object({
    approvals: z.array(
      z.object({
        id: z.string(),
        workflowId: z.string(),
        workflowSubject: z.string(),
        title: z.string(),
        approverName: z.string(),
        state: z.enum(['pending', 'passed', 'rejected']),
        issuedAt: z.string(),
      }),
    ),
  }),
} as const satisfies RouteContract;

/* ── 工作流下钻:实例 × 节点 ──────────────────────────────────────────── */

/* ── 设计台 · 仿真测试台 ─────────────────────────────────────────────── */

/**
 * 起一条流(测试台专用):**带节点指派**把整条流定向到指定账号 ——
 * 真实任务照旧落到那个人的工作台,测试台只管起单与观测。
 */
/**
 * 触发器的**运营配置**:要不要人工确认、谁来确认 —— 与设计面的 upsert 分口,
 * 设计动规则不碰这两项,运营动这两项不碰规则。
 */
export const setTriggerConfirmRoute = {
  method: 'POST',
  path: '/api/gov/triggers/:id/confirm',
  access: 'ops',
  params: z.object({ id: z.string() }),
  body: z.object({ required: z.boolean(), staffId: z.string().optional() }),
  output: z.object({ ok: z.boolean() }),
} as const satisfies RouteContract;

/** 节点负责人(运营配置):流程包的哪个节点归谁 —— 显式指派 > 这里 > 轮值 */
export const listNodeOwnersRoute = {
  method: 'GET',
  path: '/api/gov/packages/:id/owners',
  access: 'ops',
  params: z.object({ id: z.string() }),
  output: z.object({ owners: z.array(z.object({ nodeId: z.string(), staffId: z.string() })) }),
} as const satisfies RouteContract;

export const setNodeOwnerRoute = {
  method: 'PUT',
  path: '/api/gov/packages/:id/owners/:nodeId',
  access: 'ops',
  params: z.object({ id: z.string(), nodeId: z.string() }),
  /** null = 撤掉运营指定,回到轮值 */
  body: z.object({ staffId: z.string().nullable() }),
  output: z.object({ ok: z.boolean() }),
} as const satisfies RouteContract;

export const testRunRoute = {
  method: 'POST',
  path: '/api/gov/testbed/run',
  access: 'design',
  body: z.object({
    packageId: z.string(),
    /**
     * 启动输入**就是一封信** —— 这条流真实的起法即客户来信(RFQ 正文 + BOM 附件)。
     * 服务端拿**真通道的抽键规则**抽出关联键、拿**真触发器的装配映射**推出调用入参:
     * 测试台不自带一套解析,否则试通的是测试台、不是这条流。
     */
    mail: z.object({
      from: z.string().min(1),
      /**
       * 收件箱**不由界面写**(2026-07-29):投给哪个信箱是通道配置的事,不是造信的人该操心的。
       * 留空 = 服务端取在用的邮件通道(与线上真来一封信同一条路)。
       */
      to: z.string().default(''),
      subject: z.string(),
      body: z.string(),
      attachments: z
        .array(z.object({ name: z.string(), contentType: z.string(), size: z.number().int().min(0) }))
        .default([]),
    }),
    /** 节点指派 `{ 节点id → 员工id }`;不指的节点照旧轮值 */
    assignments: z.record(z.string(), z.string()).default({}),
  }),
  output: z.object({ workflowId: z.string(), state: workflowStateSchema }),
} as const satisfies RouteContract;

/**
 * 仿真测试台 · 试跑**一个活动** —— 与试跑流程包并列的第二种试法。
 *
 * 为什么要单有一条:开发一个活动时,关心的是「这个活动自己跑不跑得动」——
 * 案例模型推不推得开、判据取不取得齐、台账写不写得对、验收卡长什么样。
 * 走流程包试,前面几个节点的噪音全得先趟一遍,而且每改一次活动就要重跑整条流。
 *
 * 起出来的是**真任务**(不挂工作流),照旧落到被指派人的工作台、照旧过 Harness 与放行门 ——
 * 试跑不等于假跑:假跑试不出任何东西。区别只在它带 `origin='testbed'`,可以连根拔掉。
 */
export const testRunActivityRoute = {
  method: 'POST',
  path: '/api/gov/testbed/run-activity',
  access: 'design',
  body: z.object({
    activityId: z.string().min(1),
    /** 起单入参 —— 按该活动契约的 `input.data` 填;可用包自带样例预填 */
    data: z.record(z.string(), z.unknown()).default({}),
    /** 委托消息(可空)—— 契约允许时才有意义 */
    message: z.string().default(''),
    /** 派给谁;留空 = 操作者自己(试跑不该派到别人工作台上) */
    ownerId: z.string().default(''),
    /**
     * **连主数据一起落真库** —— 默认 `true`(2026-08-24 用户定:「那你就默认给它打开」)。
     *
     * 从前主数据一律挡在活动缓存里,理由是保护样例:试跑往 `customer.profile` 建一位客户,
     * 那位客户就永久留在库里,「新客户来函」那条样例第二次跑就成了老客户。
     * 可实际用起来,这条保护挡住的恰恰是人要看的东西 —— E04 的台账更新明细白纸黑字写着
     * 「亲密度 3 → 10」,而 `customer.contact` 里还是 3:**单据说改了、主数据没改**,
     * 两份事实对不上,谁看谁糊涂。跑一遍活动就该看见数据真的变了,这是本分。
     *
     * 保护没有取消,只是**换了个落点**:要它的那个调用方自己关
     * (`tools/e2e-a2.mjs` 显式传 `false` —— 只能测一次的样例归它管)。
     * 默认值服务于人手点的那条路;脚本要什么,脚本自己说。
     */
    landMaster: z.boolean().default(true),
  }),
  output: z.object({ taskId: z.string(), title: z.string() }),
} as const satisfies RouteContract;

/**
 * 停止仿真 —— **把这一单连根拔掉**:工作流、它的活动任务、工单、实例、trace 全部销毁。
 * 仿真不是生产:试跑留下的东西不该在库里、在别人工作台上过夜。
 */
export const testStopRoute = {
  method: 'POST',
  path: '/api/gov/testbed/stop',
  access: 'design',
  /** 两种试法各有其拔法:流程包给 workflowId,单活动给 taskId;都不给 = 拔掉所有试跑残留 */
  body: z.object({ workflowId: z.string().default(''), taskId: z.string().default('') }),
  output: z.object({ destroyed: z.boolean(), tasks: z.number().int() }),
} as const satisfies RouteContract;

/** 当前在跑的仿真(测试台一次只跑一条)—— 刷新页面也认得回来 */
/**
 * 当前这一台仪器上的试跑单(测试台一次只跑一条)—— 刷新页面也认得回来。
 *
 * **返回还在跑的那一单,以及刚跑完的那一单** —— 两者要分得开:
 * `live` 为真才锁旋钮(在跑的不许换台);为假表示它已收尾,观测面照旧摆着结果给人看,
 * 但可以再起一单了。从前不分,已终结的单照样被当成「在跑」——
 * 跑完之后旋钮永久锁住,人只能刷新整页才起得了下一单(实测)。
 */
export const testCurrentRoute = {
  method: 'GET',
  path: '/api/gov/testbed/current',
  access: 'design',
  output: z.object({
    workflowId: z.string().optional(),
    subject: z.string().optional(),
    /** 单活动试跑:没有工作流,认的是任务 */
    taskId: z.string().optional(),
    activityId: z.string().optional(),
    /** 还在跑(未终结)—— 只有它为真才算「占着这台仪器」 */
    live: z.boolean().default(false),
    /** 已收尾时的终态名(released / blocked / terminated …),给观测面收灯用 */
    terminal: z.string().optional(),
  }),
} as const satisfies RouteContract;

/**
 * 单活动试跑的**观测面** —— 一屏看穿这一单:
 * 轨迹(每一拍干了什么)· 台账草稿(成果落到哪儿了)· 卡(问了谁什么)· 预算读数。
 *
 * 流程包那侧看的是 trace 树(节点 → 步骤);活动这侧要看的是**活动内部**,
 * 拿 trace 树看不出「第三拍为什么被拒」。
 */
export const testActivityStateRoute = {
  method: 'GET',
  path: '/api/gov/testbed/activity/:taskId',
  access: 'design',
  params: z.object({ taskId: z.string() }),
  output: z.object({
    taskId: z.string(),
    activityId: z.string(),
    title: z.string(),
    runtime: taskRuntimeStateSchema,
    terminal: terminalStateSchema.optional(),
    reason: z.string().optional(),
    used: z.object({ steps: z.number().int(), tokens: z.number().int(), humanCalls: z.number().int() }),
    caps: z.object({ steps: z.number().int(), tokens: z.number().int(), humanCalls: z.number().int() }),
    /** 每一拍的轨迹:干了什么、拿回了什么、被拒的理由 */
    trail: z.array(
      z.object({
        at: z.string(),
        kind: z.string(),
        title: z.string(),
        detail: z.record(z.string(), z.unknown()).optional(),
      }),
    ),
    /** 本单写下的台账草稿 —— 成果就是这些行 */
    drafts: z.array(
      z.object({
        address: z.string(),
        key: z.record(z.string(), z.unknown()),
        patch: z.record(z.string(), z.unknown()),
      }),
    ),
    /** 待答与已答的卡 */
    cards: z.array(
      z.object({
        id: z.string(),
        mode: z.enum(['execution', 'acceptance']),
        title: z.string(),
        done: z.boolean(),
        result: z.string().optional(),
      }),
    ),
  }),
} as const satisfies RouteContract;

/* ── 试跑日志:运行数据不过夜,观测记录留下来 ─────────────────────────── */

/* ── 上传件:附件要能真正进活动,不能只剩一个文件名 ────────────────── */

/**
 * 上传一个文件 —— 走 base64 而不是 multipart。
 *
 * 这一层所有路由都由同一套 zod 契约与 typed-fetch 收着,multipart 得在它旁边另开一条
 * 不受契约管的路;而这里要传的是 BOM、规格书这类几十 KB 的件,base64 那点膨胀
 * 换来「照旧一条契约管到底」是划算的。真大的件不该走界面上传,该走通道。
 */
export const uploadFileRoute = {
  method: 'POST',
  path: '/api/gov/upload',
  access: 'design',
  body: z.object({
    name: z.string().min(1),
    contentType: z.string().default(''),
    /** 文件字节的 base64 —— 上限 8MB(超了当场拒,不静默截断) */
    dataBase64: z.string().min(1),
  }),
  output: z.object({
    ref: z.string(),
    name: z.string(),
    contentType: z.string(),
    size: z.number().int(),
    /** 读出来的文本;缺席 = 这类文件读不出文本(理由在 note 里) */
    text: z.string().optional(),
    note: z.string(),
  }),
} as const satisfies RouteContract;
export type UploadedFile = z.infer<typeof uploadFileRoute.output>;

/** 取回原件 —— 存的是真字节,人点得开才算真留住了 */
export const downloadFileRoute = {
  method: 'GET',
  path: '/api/gov/upload/:id',
  access: 'design',
  params: z.object({ id: z.string() }),
  output: z.object({ name: z.string(), contentType: z.string(), dataBase64: z.string() }),
} as const satisfies RouteContract;

/**
 * 一次试跑的存档 —— **销毁那一刻拍的快照**。
 *
 * 「停止仿真 = 连根拔掉」这条不变(试跑起的是真任务,不该在别人工作台上过夜);
 * 拔掉之前把这一单的观测面存下来。开发活动是反复试的活,「上一版跑了几拍、
 * 卡在哪一步、台账写成什么样」正是要拿来比对的东西 —— 拔干净等于每改一次
 * 就把上一次的账一并烧了。
 */
export const testLogRowSchema = z.object({
  id: z.string(),
  kind: z.enum(['activity', 'package']),
  subject: z.string(),
  /** 试的是谁:activityId 或 packageId */
  target: z.string(),
  taskId: z.string().optional(),
  workflowId: z.string().optional(),
  /** 终态名;缺省 = 人中途停的 */
  terminal: z.string().optional(),
  reason: z.string().optional(),
  used: z.object({ steps: z.number().int(), tokens: z.number().int(), humanCalls: z.number().int() }).partial(),
  caps: z.object({ steps: z.number().int(), tokens: z.number().int(), humanCalls: z.number().int() }).partial(),
  /** 列表页只要计数,详情才给正文 —— 一次试跑的轨迹有上百条 */
  trailCount: z.number().int(),
  draftCount: z.number().int(),
  cardCount: z.number().int(),
  startedAt: z.string().optional(),
  archivedAt: z.string(),
});
export type TestLogRow = z.infer<typeof testLogRowSchema>;

export const listTestLogsRoute = {
  method: 'GET',
  path: '/api/gov/testbed/logs',
  access: 'design',
  output: z.object({ runs: z.array(testLogRowSchema) }),
} as const satisfies RouteContract;

/** 一次试跑的正文 —— 逐拍轨迹 / 台账草稿 / 发过的卡 */
export const testLogDetailRoute = {
  method: 'GET',
  path: '/api/gov/testbed/logs/:id',
  access: 'design',
  params: z.object({ id: z.string() }),
  output: testLogRowSchema.extend({
    trail: z.array(
      z.object({
        at: z.string(),
        kind: z.string(),
        title: z.string(),
        detail: z.record(z.string(), z.unknown()).optional(),
      }),
    ),
    drafts: z.array(
      z.object({
        address: z.string(),
        key: z.record(z.string(), z.unknown()),
        patch: z.record(z.string(), z.unknown()),
      }),
    ),
    cards: z.array(
      z.object({
        id: z.string(),
        mode: z.string(),
        title: z.string(),
        done: z.boolean(),
        result: z.string().optional(),
      }),
    ),
  }),
} as const satisfies RouteContract;

/** 删一条 / 清空 —— 日志是给人比对用的,留多久由人说了算 */
export const deleteTestLogRoute = {
  method: 'DELETE',
  path: '/api/gov/testbed/logs/:id',
  access: 'design',
  params: z.object({ id: z.string() }),
  output: z.object({ deleted: z.number().int() }),
} as const satisfies RouteContract;

export const clearTestLogsRoute = {
  method: 'DELETE',
  path: '/api/gov/testbed/logs',
  access: 'design',
  output: z.object({ deleted: z.number().int() }),
} as const satisfies RouteContract;

/** 全链 Trace:一条工作流的 span 树(节点 → 步骤 / 工具 / 模型 / 人卡) */
export const traceOfWorkflowRoute = {
  method: 'GET',
  path: '/api/gov/workflows/:id/trace',
  access: 'design',
  params: z.object({ id: z.string() }),
  output: z.object({
    spans: z.array(
      z.object({
        id: z.string(),
        traceId: z.string(),
        parentId: z.string().optional(),
        name: z.string(),
        kind: z.enum(['workflow', 'node', 'step', 'tool', 'model', 'human']),
        nodeId: z.string().optional(),
        taskId: z.string().optional(),
        input: z.record(z.string(), z.unknown()).optional(),
        output: z.record(z.string(), z.unknown()).optional(),
        error: z.object({ message: z.string() }).optional(),
        attributes: z.record(z.string(), z.unknown()).optional(),
        startedAt: z.string(),
        endedAt: z.string().optional(),
      }),
    ),
  }),
} as const satisfies RouteContract;

export const govWorkflowRoute = {
  method: 'GET',
  path: '/api/gov/workflows/:id',
  access: ['design', 'ops'],
  params: z.object({ id: z.string() }),
  output: z.object({
    workflow: z.object({
      id: z.string(),
      subject: z.string(),
      state: workflowStateSchema,
      packageId: z.string(),
      packageVersion: z.number().int(),
      source: z.object({ kind: z.string(), ref: z.string(), by: z.string().optional() }),
      startedAt: z.string(),
      finishedAt: z.string().optional(),
    }),
    pkg: processPackageSchema,
    instances: z.array(
      z.object({
        nodeId: z.string(),
        instance: z.number().int(),
        running: z.boolean(),
        waiting: z.boolean(),
        activated: z.boolean(),
        terminal: terminalStateSchema.optional(),
      }),
    ),
    tasks: z.array(z.object({ id: taskIdSchema, nodeId: z.string(), title: z.string(), ownerName: z.string() })),
  }),
} as const satisfies RouteContract;

/* ── 记忆管理 · 度量仪表 ──────────────────────────────────────────────── */

/**
 * 度量八指标(OS 8.3)—— 运营驾驶舱的仪表读数。
 *
 * 出参直接复用 `reportMetricsSchema`:**与工作台汇报同源同口径**。
 * 治理台若另算一套,同一个组织会读出两个自主率 —— 那时候争的就不是数,是谁的表准。
 * 自主率与纠正率**成对读**,复合为有效自主率 —— 单看自主率会奖励「猛冲后返工」。
 */
export const govMetricsRoute = {
  method: 'GET',
  path: '/api/gov/metrics',
  access: 'ops',
  /** 统计窗口 —— 不传按月;驾驶舱可切日/周/月/年 */
  query: z.object({ period: reportPeriodSchema.optional() }),
  /** `period` 原样回声:客户端不传时,由它知道服务端用的是哪个窗口 */
  output: reportMetricsSchema.extend({ taskCount: z.number().int(), period: reportPeriodSchema }),
} as const satisfies RouteContract;

/* ── 出参类型:契约自己命名,消费方不再 `z.infer` ──────────────────────── */

export type GovTasksOutput = z.infer<typeof listGovTasksRoute.output>;
export type GovWorkGroupsOutput = z.infer<typeof listWorkGroupsRoute.output>;
export type GovApprovalsOutput = z.infer<typeof listApprovalsRoute.output>;
export type GovStaffOutput = z.infer<typeof listStaffRoute.output>;
export type GovGrantsOutput = z.infer<typeof listGrantsRoute.output>;
export type GovPackagesOutput = z.infer<typeof listProcessPackagesRoute.output>;
export type GovTriggersOutput = z.infer<typeof listTriggersRoute.output>;
export type GovActivitiesOutput = z.infer<typeof listActivitiesRoute.output>;
export type GovToolsOutput = z.infer<typeof listToolsRoute.output>;
export type GovObjectsOutput = z.infer<typeof listLedgerObjectsRoute.output>;
export type GovLedgerPageOutput = z.infer<typeof browseLedgerRoute.output>;
export type GovLedgerByActivityOutput = z.infer<typeof ledgerByActivityRoute.output>;
export type GovMemoryOutput = z.infer<typeof listActivityMemoryRoute.output>;
export type GovMetricsOutput = z.infer<typeof govMetricsRoute.output>;
export type GovChannelsOutput = z.infer<typeof listChannelsRoute.output>;
export type GovLlmOutput = z.infer<typeof listLlmInstancesRoute.output>;
export type GovWorkflowOutput = z.infer<typeof govWorkflowRoute.output>;
export type GovTaskLogOutput = z.infer<typeof govTaskLogRoute.output>;