agentworkshop 0.7.70 → 0.7.71

package/server/services/workshop/optimization/binding.repo.ts

@@ -0,0 +1,128 @@
+/**
+ * OptimizerBinding 仓储。作用域 = (workspace, channel, channel_agent, profile)。
+ * channel_agent_id 是 channel_agents.id(实例身份),绝不是 agents.id(模板)。
+ */
+import type { DatabaseSync } from 'node:sqlite'
+import { AppError } from '../../../utils/errors'
+import type { BindingMode } from './contracts'
+import { getAmlRuntime } from '../aml/runtime'
+
+export interface BindingRow {
+  id: string
+  workspaceId: string
+  channelId: string
+  channelAgentId: string
+  profileId: string
+  profileVersionNumber: number
+  /** "profileId@version"(与 OptimizationProfile 的版本引用同格式) */
+  profileVersion: string
+  capabilities: string[]
+  mode: BindingMode
+  validFrom: string
+  validTo: string | null
+  revision: number
+  createdAt: string
+}
+
+const COLS = `id, workspace_id AS workspaceId, channel_id AS channelId, channel_agent_id AS channelAgentId,
+  profile_id AS profileId, profile_version AS profileVersionNumber, capabilities_json AS capabilitiesJson,
+  mode, valid_from AS validFrom, valid_to AS validTo, revision, created_at AS createdAt`
+
+function rowOf(r: Record<string, unknown>): BindingRow {
+  const profileId = String(r.profileId ?? '')
+  const version = Number(r.profileVersionNumber ?? 1)
+  return {
+    id: String(r.id),
+    workspaceId: String(r.workspaceId),
+    channelId: String(r.channelId),
+    channelAgentId: String(r.channelAgentId),
+    profileId,
+    profileVersionNumber: version,
+    profileVersion: `${profileId}@${version}`,
+    capabilities: JSON.parse(String(r.capabilitiesJson ?? '[]')) as string[],
+    mode: String(r.mode) as BindingMode,
+    validFrom: String(r.validFrom),
+    validTo: r.validTo == null ? null : String(r.validTo),
+    revision: Number(r.revision ?? 1),
+    createdAt: String(r.createdAt),
+  }
+}
+
+export function createBindingRepo(db: DatabaseSync) {
+  return {
+    insert(input: {
+      id: string
+      workspaceId: string
+      channelId: string
+      channelAgentId: string
+      profileId: string
+      profileVersion: number
+      capabilities: string[]
+      mode: BindingMode
+      validFrom?: string
+      validTo?: string | null
+      createdBy?: string
+    }): BindingRow {
+      const now = new Date().toISOString()
+      const validFrom = input.validFrom ?? now
+      try {
+        db.prepare(`INSERT INTO optimizer_bindings
+          (id, workspace_id, channel_id, channel_agent_id, profile_id, profile_version, capabilities_json,
+           mode, valid_from, valid_to, revision, created_by, created_at, updated_at)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, ?, ?, ?)`)
+          .run(input.id, input.workspaceId, input.channelId, input.channelAgentId, input.profileId, input.profileVersion,
+            JSON.stringify(input.capabilities), input.mode, validFrom, input.validTo ?? null, input.createdBy ?? '', now, now)
+      }
+      catch (err) {
+        if (String((err as Error).message).includes('UNIQUE')) {
+          throw new AppError(409, 'BINDING_DUPLICATE', '同一 Agent 已绑定该 Profile 版本')
+        }
+        throw err
+      }
+      return this.get(input.id)!
+    },
+
+    get(id: string): BindingRow | undefined {
+      const r = db.prepare(`SELECT ${COLS} FROM optimizer_bindings WHERE id = ?`).get(id) as Record<string, unknown> | undefined
+      return r ? rowOf(r) : undefined
+    },
+
+    listByAgent(channelAgentId: string): BindingRow[] {
+      return (db.prepare(`SELECT ${COLS} FROM optimizer_bindings WHERE channel_agent_id = ? ORDER BY created_at ASC`).all(channelAgentId) as unknown as Record<string, unknown>[]).map(rowOf)
+    },
+
+    listByChannel(channelId: string): BindingRow[] {
+      return (db.prepare(`SELECT ${COLS} FROM optimizer_bindings WHERE channel_id = ? ORDER BY created_at ASC`).all(channelId) as unknown as Record<string, unknown>[]).map(rowOf)
+    },
+
+    listAll(limit = 200): BindingRow[] {
+      return (db.prepare(`SELECT ${COLS} FROM optimizer_bindings ORDER BY created_at DESC LIMIT ?`).all(limit) as unknown as Record<string, unknown>[]).map(rowOf)
+    },
+
+    /** 撤权:删除行(revision 变化由删除时间体现);成员删除由 FK CASCADE 保证。 */
+    remove(id: string): boolean {
+      const r = db.prepare('DELETE FROM optimizer_bindings WHERE id = ?').run(id)
+      return Number(r.changes) > 0
+    },
+
+    bumpRevision(id: string): number {
+      db.prepare('UPDATE optimizer_bindings SET revision = revision + 1, updated_at = ? WHERE id = ?').run(new Date().toISOString(), id)
+      const row = this.get(id)
+      return row?.revision ?? 0
+    },
+
+    removeByAgent(channelAgentId: string): number {
+      const r = db.prepare('DELETE FROM optimizer_bindings WHERE channel_agent_id = ?').run(channelAgentId)
+      return Number(r.changes)
+    },
+  }
+}
+
+export type BindingRepo = ReturnType<typeof createBindingRepo>
+
+const g = globalThis as typeof globalThis & { __optimizerBindingRepo?: BindingRepo }
+
+export function getBindingRepo(): BindingRepo {
+  g.__optimizerBindingRepo ??= createBindingRepo(getAmlRuntime().db)
+  return g.__optimizerBindingRepo
+}

package/server/services/workshop/optimization/binding.service.ts

@@ -0,0 +1,128 @@
+/**
+ * 绑定服务(G4.1/G4.2):
+ *  - 实例身份纪律:只接受 channel_agents.id;传 templates(agents.id)明确拒绝;
+ *  - 作用域校验:channel 必须属于 workspace,agent 必须属于该 channel;
+ *  - 多绑定:solve 未带 bindingId → BINDING_AMBIGUOUS;带他人 binding → BINDING_NOT_OWNED;
+ *  - 逐次重校验:有效期/profile 状态/模型阶段/成员存在 → BINDING_STALE。
+ */
+import { AppError } from '../../../utils/errors'
+import { getAmlRuntime } from '../aml/runtime'
+import type { BindingMode } from './contracts'
+import { BINDING_ERRORS, OPTIMIZER_CAPABILITIES } from './contracts'
+import { getBindingRepo, type BindingRow } from './binding.repo'
+import { getProfileRepo } from './profile.repo'
+import { acquireModelLease, type ModelLease } from '../aml/model-references'
+
+export interface CreateBindingInput {
+  workspaceId: string
+  channelId: string
+  /** channel_agents.id(实例);传 agents.id(模板)会被拒绝 */
+  agentInstanceId: string
+  profileId: string
+  profileVersion: number
+  capabilities?: string[]
+  mode?: BindingMode
+  validTo?: string | null
+  createdBy?: string
+}
+
+export interface ResolvedBinding {
+  binding: BindingRow
+  profileId: string
+  profileVersion: number
+  lease: ModelLease
+}
+
+function db() {
+  return getAmlRuntime().db
+}
+
+/** 实例身份解析:拒绝模板 id;返回 channel_agents 行。 */
+export function requireAgentInstance(agentId: string): { id: string, channelId: string, name: string } {
+  const row = db().prepare('SELECT id, channel_id AS channelId, name FROM channel_agents WHERE id = ?').get(agentId) as { id: string, channelId: string, name: string } | undefined
+  if (row) return row
+  const template = db().prepare('SELECT id FROM agents WHERE id = ?').get(agentId) as { id: string } | undefined
+  if (template) {
+    throw new AppError(422, BINDING_ERRORS.TEMPLATE_ID,
+      `传入的是 Agent 模板 id(${agentId});绑定必须使用 Channel 实例 id(channel_agents.id)。可用:SELECT id, name FROM channel_agents WHERE channel_id = ?`)
+  }
+  throw new AppError(404, BINDING_ERRORS.NOT_FOUND, `Agent 实例 ${agentId} 不存在`)
+}
+
+export function createBinding(input: CreateBindingInput): BindingRow {
+  const instance = requireAgentInstance(input.agentInstanceId)
+  if (instance.channelId !== input.channelId) {
+    throw new AppError(422, BINDING_ERRORS.CHANNEL_MISMATCH, `Agent 实例属于 Channel ${instance.channelId},与绑定 Channel ${input.channelId} 不一致`)
+  }
+  const wsChannel = db().prepare('SELECT 1 AS ok FROM workspace_channels WHERE workspace_id = ? AND channel_id = ?').get(input.workspaceId, input.channelId)
+  if (!wsChannel) {
+    throw new AppError(422, BINDING_ERRORS.WORKSPACE_MISMATCH, `Channel ${input.channelId} 不属于 workspace ${input.workspaceId}`)
+  }
+  const profile = getProfileRepo().get(input.profileId, input.profileVersion)
+  if (!profile) throw new AppError(404, 'PROFILE_NOT_FOUND', `Profile ${input.profileId}@${input.profileVersion} 不存在`)
+  if (profile.status !== 'published') throw new AppError(409, 'PROFILE_NOT_PUBLISHED', `Profile ${input.profileId}@${input.profileVersion} 状态为 ${profile.status};绑定只接受 published`)
+  const capabilities = input.capabilities?.length ? input.capabilities : [...OPTIMIZER_CAPABILITIES]
+  const invalid = capabilities.filter(c => !(OPTIMIZER_CAPABILITIES as readonly string[]).includes(c))
+  if (invalid.length) throw new AppError(422, 'BINDING_CAPABILITY_INVALID', `未知能力:${invalid.join(', ')}`)
+  const id = `ob-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 7)}`
+  return getBindingRepo().insert({
+    id, workspaceId: input.workspaceId, channelId: input.channelId, channelAgentId: input.agentInstanceId,
+    profileId: input.profileId, profileVersion: input.profileVersion, capabilities,
+    mode: input.mode ?? 'recommendation', validTo: input.validTo ?? null, createdBy: input.createdBy ?? '',
+  })
+}
+
+export function listBindingsForAgent(agentId: string): BindingRow[] {
+  return getBindingRepo().listByAgent(agentId)
+}
+
+/**
+ * 解析本次调用的绑定:
+ *  - 无 bindingId 且仅 1 个 → 默认;多个 → BINDING_AMBIGUOUS;
+ *  - bindingId 不属于该实例 → BINDING_NOT_OWNED;
+ *  - 过期/profile 退役/模型阶段不合格 → BINDING_STALE。
+ * 返回的 lease 必须由调用方 release(阻止工件 GC)。
+ */
+export function resolveBinding(agentId: string, bindingId?: string): ResolvedBinding {
+  const bindings = listBindingsForAgent(agentId)
+  if (!bindings.length) throw new AppError(409, BINDING_ERRORS.NOT_FOUND, '该 Agent 未绑定任何优化器 Profile;先在 Channel 设置里绑定')
+  const selected: BindingRow | undefined = bindingId
+    ? bindings.find(b => b.id === bindingId)
+    : bindings.length === 1 ? bindings[0] : undefined
+  if (!selected) {
+    if (bindingId) throw new AppError(403, BINDING_ERRORS.NOT_OWNED, `binding ${bindingId} 不属于当前 Agent(${agentId})`)
+    throw new AppError(409, BINDING_ERRORS.AMBIGUOUS, `该 Agent 有 ${bindings.length} 个绑定;调用必须显式传 binding_id(${bindings.map(b => b.id).join(', ')})`)
+  }
+  const binding: BindingRow = selected
+
+  const now = Date.now()
+  if (binding.validFrom && Date.parse(binding.validFrom) > now) {
+    throw new AppError(409, BINDING_ERRORS.STALE, `binding ${binding.id} 尚未生效(validFrom=${binding.validFrom})`)
+  }
+  if (binding.validTo && Date.parse(binding.validTo) <= now) {
+    throw new AppError(409, BINDING_ERRORS.STALE, `binding ${binding.id} 已过有效期(validTo=${binding.validTo})`)
+  }
+  const profile = getProfileRepo().get(binding.profileId, binding.profileVersionNumber)
+  if (!profile || profile.status === 'retired') {
+    throw new AppError(409, BINDING_ERRORS.STALE, `binding ${binding.id} 引用的 Profile 已退役或不存在`)
+  }
+  const model = db().prepare('SELECT stage FROM aml_models WHERE id = ?').get(profile.modelRef) as { stage: string } | undefined
+  if (!model || model.stage === 'retired') {
+    throw new AppError(409, BINDING_ERRORS.STALE, `binding ${binding.id} 引用的模型 ${profile.modelRef} 不存在或已退役`)
+  }
+  const instance = db().prepare('SELECT 1 AS ok FROM channel_agents WHERE id = ?').get(agentId)
+  if (!instance) throw new AppError(409, BINDING_ERRORS.STALE, '当前 Agent 实例已被删除')
+  const lease = acquireModelLease(profile.modelRef, `binding:${binding.id}`)
+  return { binding, profileId: binding.profileId, profileVersion: binding.profileVersionNumber, lease }
+}
+
+export function revokeBinding(bindingId: string, actor: string, actorName = actor): boolean {
+  const row = getBindingRepo().get(bindingId)
+  if (!row) return false
+  getBindingRepo().remove(bindingId)
+  void import('../ops/ops').then(({ recordOps }) => recordOps({
+    actor, actorName, actorKind: 'user', action: 'optimizer.binding.revoke', kind: 'write',
+    summary: `撤销优化器绑定 ${bindingId}(profile ${row.profileVersion})`, targetKind: 'optimizer_binding', targetId: bindingId,
+  })).catch(() => {})
+  return true
+}

package/server/services/workshop/optimization/contracts.ts

@@ -0,0 +1,346 @@
+/**
+ * Optimizer Manager —— 类型化契约(单一事实来源)。
+ *
+ * 边界(plan §4 / G1.2):
+ *  - Profile 冻结"模型精确版本 + 问题模板 + 求解器版本",发布后不可原地修改;
+ *  - ProblemIR 是 Solver / Twin / baseline 共用的**同一问题定义**,三者必须在其上重算代价;
+ *  - 候选/建议是运行时产物,不进入配置;建议永不等于设备执行授权。
+ */
+import { canonicalJson, sha256 } from '../aml/twin/contracts'
+import type { ArtifactKind, ModelInterfaceId, ProblemTemplateRef, SolverRef } from '../process-model/contracts'
+import { assertSolverSupportsArtifact } from '../process-model/contracts'
+import { AppError } from '../../../utils/errors'
+
+export const OPTIMIZATION_SCHEMA_VERSION = 1 as const
+export const PROBLEM_IR_VERSION = 1 as const
+
+// ===== Profile =====
+
+export type ProfileStatus = 'draft' | 'validated' | 'published' | 'retired'
+
+export interface ModelRef {
+  modelId: string
+  artifactKind: ArtifactKind
+  artifactHash: string
+  modelInterface: ModelInterfaceId
+  /** 模型发布阶段(candidate 可求解但建议不可信;production 才作为推荐依据) */
+  stage: 'candidate' | 'shadow' | 'production' | 'retired'
+}
+
+export interface LinearMpcConfig {
+  /** 相对设定值的跟踪权重(CV) */
+  cvWeights: Record<string, number>
+  /** 输入移动惩罚 Δu */
+  duWeights: Record<string, number>
+  /** 终端代价权重(相对 cvWeights 的倍数) */
+  terminalWeight: number
+  /** CV 设定值(工程/模型单位,按 spec.variables 的 modelUnit) */
+  targets: Record<string, number>
+  /** 软约束惩罚(硬约束之外的越界惩罚) */
+  slackPenalty?: number
+}
+
+export interface SteadyResponseConfig {
+  /** 经济代价目标:对 MV 的线性权重(可为负 = 越大越好) */
+  economicWeights: Record<string, number>
+  /** CV 目标跟踪权重 */
+  cvWeights: Record<string, number>
+  /** CV 目标值 */
+  targets: Record<string, number>
+}
+
+export interface ProblemConfig {
+  linear_mpc_quadratic?: LinearMpcConfig
+  steady_response?: SteadyResponseConfig
+}
+
+export interface OptimizationProfile {
+  schemaVersion: typeof OPTIMIZATION_SCHEMA_VERSION
+  id: string
+  version: number
+  name?: string
+  modelRef: ModelRef
+  problemTemplateRef: ProblemTemplateRef
+  problemConfig: ProblemConfig
+  solverRef: SolverRef
+  solverVersion: string
+  /** ProcessModelSpec 精确版本("id@version");运行期据此装配变量/延迟/有效域 */
+  processSpecRef: string
+  /** 允许的工况 id(空 = 该模型所有工况) */
+  conditionIds: string[]
+  status: ProfileStatus
+  ownerUserId?: string
+  /** 发布时冻结的问题结构 hash */
+  problemIrHash?: string
+  createdAt?: string
+}
+
+export function assertProfileSolverCompatible(profile: Pick<OptimizationProfile, 'solverRef' | 'modelRef' | 'problemTemplateRef'>): void {
+  assertSolverSupportsArtifact(profile.solverRef, profile.modelRef.artifactKind, `profile model=${profile.modelRef.modelId}`)
+  if (profile.solverRef === 'osqp_mpc@1' && profile.problemTemplateRef !== 'linear_mpc_quadratic@1') {
+    throw new AppError(422, 'PROFILE_INCOMPATIBLE', 'osqp_mpc@1 只能使用 linear_mpc_quadratic@1 模板')
+  }
+  if (profile.solverRef === 'scipy_slsqp@1' && profile.problemTemplateRef !== 'steady_response@1') {
+    // D21 solverRef×template 分派矩阵:worker 按模板分派,线性模板固定走 OSQP;
+    // scipy+linear 会在运行时静默误派 → 发布期显式拒绝(SW6/MP-A8)
+    throw new AppError(422, 'SOLVER_TEMPLATE_UNSUPPORTED', 'scipy_slsqp@1 只能使用 steady_response@1 模板(线性模板由 osqp_mpc@1 求解)')
+  }
+}
+
+// ===== Binding =====
+
+export type BindingMode = 'shadow' | 'recommendation'
+
+export interface OptimizerBinding {
+  id: string
+  workspaceId: string
+  channelId: string
+  /** channel_agents.id(实例身份;绝不接受 agents.id 模板 id) */
+  channelAgentId: string
+  profileVersion: string
+  capabilities: string[]
+  mode: BindingMode
+  validFrom: string
+  validTo?: string | null
+  revision: number
+  createdAt: string
+}
+
+export const OPTIMIZER_CAPABILITIES = ['solve', 'status', 'cancel', 'plan_get', 'capabilities'] as const
+export type OptimizerCapability = (typeof OPTIMIZER_CAPABILITIES)[number]
+
+// ===== ProblemIR =====
+
+export interface ProblemScaling {
+  /** 变量名 → 缩放(模型单位 → 规划单位) */
+  mv: Record<string, { scale: number, offset: number }>
+  cv: Record<string, { scale: number, offset: number }>
+}
+
+export interface LinearDynamics {
+  /** 状态数 */
+  stateDim: number
+  /** A 行主序 [stateDim x stateDim] */
+  A: number[]
+  /** B 行主序 [stateDim x (mvCount)] —— 已含延迟扩充状态时的输入矩阵 */
+  B: number[]
+  /** C 行主序 [cvCount x stateDim] */
+  C: number[]
+  /** D 行主序 [cvCount x mvCount] */
+  D: number[]
+  /** 每 MV 的输入延迟(步);调度器/模型已按此索引,ProblemIR 只记录不重复施加 */
+  delays: Record<string, number>
+  /** 初始状态(历史寄存器展开) */
+  x0: number[]
+  /** 状态偏置(x' = A x + B u + bias);缺省全 0 */
+  bias?: number[]
+}
+
+export interface ProblemBounds {
+  min?: number
+  max?: number
+  /** 相对上一时刻的最大变化率(≤) */
+  maxStep?: number
+}
+
+export interface LinearMpcProblem {
+  template: 'linear_mpc_quadratic@1'
+  dynamics: LinearDynamics
+  /** CV 设定值(模型单位) */
+  cvSetpoints: number[]
+  /** CV 的软约束/有效域 */
+  cvBounds: ProblemBounds[]
+  /** MV 变量名顺序(= dynamics 输入顺序) */
+  mvOrder: string[]
+  cvOrder: string[]
+  mvBounds: ProblemBounds[]
+  /** 上一时刻已生效输入(Δu 基准,模型单位) */
+  uPrev: number[]
+}
+
+export interface StaticResponseProblem {
+  template: 'steady_response@1'
+  mvOrder: string[]
+  cvOrder: string[]
+  /** 响应面系数:cv → [1, mv..., mv_i*mv_j...](与特征展开顺序一致) */
+  coefficients: Record<string, number[]>
+  featureOrder: string[]
+  cvTargets: number[]
+  mvBounds: ProblemBounds[]
+  cvBounds: ProblemBounds[]
+  uPrev: number[]
+}
+
+export interface ProblemIRBase {
+  irVersion: typeof PROBLEM_IR_VERSION
+  profileRef: string
+  modelRef: ModelRef
+  solverRef: SolverRef
+  conditions: { conditionId: string, lineId: string, productId: string, recipeId: string, recipeVersion: number }
+  horizon: number
+  beatMs: number
+  scaling: ProblemScaling
+  weights: {
+    cv: Record<string, number>
+    du: Record<string, number>
+    terminal: number
+    economic?: Record<string, number>
+    slack?: number
+  }
+  context: {
+    capturedAt: string
+    /** 事件时间上界(本次求解允许使用的历史末点) */
+    eventAsOf: number
+    /** 平台入库水位(= max(ingested_at));null = unknown,不能作严格在线回放 */
+    availabilityWatermark: number | null
+    evidenceSource: 'simulation' | 'real' | 'unassessed'
+  }
+  /** 稳定 hash(不含 context.capturedAt,避免同问题每次求解变更身份) */
+  hash: string
+}
+
+export type ProblemIR = (ProblemIRBase & { problem: LinearMpcProblem | StaticResponseProblem })
+
+/**
+ * 计算 ProblemIR **结构** hash:固定变量序/时间索引/缩放/目标与约束语义。
+ * 排除运行期实例量(capturedAt/eventAsOf/watermark/x0/uPrev)——否则同一 Profile
+ * 每次求解都会得到不同 hash,发布时冻结的 hash 永远失配。
+ */
+export function computeProblemIrHash(ir: Omit<ProblemIR, 'hash'> | ProblemIR): string {
+  const { hash: _hash, context: _context, ...rest } = ir as ProblemIR
+  const problem = rest.problem
+  const structuralProblem = problem.template === 'linear_mpc_quadratic@1'
+    ? { ...problem, dynamics: { ...problem.dynamics, x0: [] }, uPrev: [] }
+    : { ...problem, uPrev: [] }
+  return sha256(canonicalJson({ ...rest, problem: structuralProblem }))
+}
+
+// ===== 求解结果 =====
+
+export const SOLVE_STATUSES = [
+  'optimal',
+  'feasible',
+  'infeasible',
+  'unbounded',
+  'timeout',
+  'cancelled',
+  'numerical_error',
+  'unsupported',
+] as const
+
+export type SolveStatus = (typeof SOLVE_STATUSES)[number]
+
+export interface ConstraintReport {
+  id: string
+  kind: 'bound' | 'rate' | 'dynamic' | 'domain'
+  satisfied: boolean
+  residual: number
+  tolerance: number
+}
+
+export interface SolveCandidate {
+  seq: number
+  /** MV 轨迹 [[t][mv]] (模型单位 → 已按 scaling 还原为工程单位) */
+  controls: number[][]
+  /** CV 预测轨迹 [[t][cv]] */
+  predicted: number[][]
+  /** 全时域代价(ProblemIR 定义) */
+  cost: number
+  constraints: ConstraintReport[]
+  feasible: boolean
+}
+
+export interface SolveResult {
+  runId: string
+  status: SolveStatus
+  candidates: SolveCandidate[]
+  /** 首步建议(MPC 只应用首步) */
+  firstMove: Record<string, number> | null
+  /** 独立复算的代价(Solver 自报之外) */
+  independentCost: number | null
+  diagnostics: {
+    backend: string
+    solverVersion: string
+    iterations?: number
+    elapsedMs: number
+    problemIrHash: string
+    message?: string
+    workerPid?: number
+  }
+  createdAt: string
+}
+
+export type RecommendationStatus = 'verified' | 'unverified' | 'expired'
+
+export interface Recommendation {
+  id: string
+  runId: string
+  candidateId: string
+  problemIrHash: string
+  modelArtifactHash: string
+  evidenceSource: 'simulation' | 'real' | 'unassessed'
+  uqEvidence: Record<string, unknown> | null
+  status: RecommendationStatus
+  /** 人读状态;未验证时后端/前端都必须原样展示 */
+  statusLabel: string
+  validUntil: string
+  createdAt: string
+}
+
+export function recommendationLabel(status: RecommendationStatus): string {
+  if (status === 'verified') return '已验证推荐'
+  if (status === 'unverified') return '未验证(缺 UQ/OOD 证据)'
+  return '已失效'
+}
+
+// ===== Solve options / worker protocol =====
+
+export interface SolveOptions {
+  /** 固定问题步长的兼容字段;Manager 只接受与发布配置一致的值,Worker 使用 ProblemIR.horizon。 */
+  horizon?: number
+  /** 应用的 binding revision(逐次重校验) */
+  bindingRevision?: number
+  timeoutMs?: number
+  requestId?: string
+}
+
+export interface SolverRequestFrame {
+  /** SW6/D21:1|2(v2 增 payload.solverRef 按 ref 分派;worker 兼容 v1,feature flag 关闭时 Manager 发 v1) */
+  protocolVersion: 1 | 2
+  reqId: string
+  op: 'solve' | 'cancel' | 'ping'
+  payload?: unknown
+  deadlineMs?: number
+}
+
+export interface SolverResponseFrame {
+  protocolVersion: 1 | 2
+  reqId: string
+  ok: boolean
+  result?: unknown
+  error?: { code: string, message: string, detail?: Record<string, unknown> }
+  diag?: Record<string, unknown>
+}
+
+export interface SolverEventFrame {
+  protocolVersion: 1 | 2
+  type: 'ready' | 'heartbeat' | 'log'
+  detail?: Record<string, unknown>
+  /** worker ready 帧携带的进程诊断(pid/python 版本);与 detail 并存以兼容两代帧形状 */
+  diag?: Record<string, unknown>
+  message?: string
+}
+
+/**
+ * 绑定解析错误码。工具面/dispatch/verify 三处共用同一套码,
+ * 保证"未绑定/绑定歧义/越权/过期"在回执里可区分(不是笼统 403)。
+ */
+export const BINDING_ERRORS = {
+  NOT_FOUND: 'BINDING_NOT_FOUND',
+  AMBIGUOUS: 'BINDING_AMBIGUOUS',
+  NOT_OWNED: 'BINDING_NOT_OWNED',
+  STALE: 'BINDING_STALE',
+  TEMPLATE_ID: 'AGENT_TEMPLATE_ID_NOT_ALLOWED',
+  CHANNEL_MISMATCH: 'BINDING_CHANNEL_MISMATCH',
+  WORKSPACE_MISMATCH: 'BINDING_WORKSPACE_MISMATCH',
+} as const