agentworkshop 0.7.70 → 0.8.0

package/server/services/workshop/optimization/python/worker.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python
+"""
+Optimizer Solver Worker(长驻子进程,NDJSON over stdin/stdout)。
+
+约束(plan B.9.3):
+  - stdout **只允许协议帧**;日志一律 stderr;
+  - 每进程同时只跑 1 个 solve;请求级 deadlineMs 由 TS 侧硬超时兜底;
+  - op: solve{cancel_check} / cancel / ping;
+  - 协作取消:主线程读 stdin 置位 Event;求解线程在迭代分段间检查;
+    不响应协作取消的长计算由 TS 直接终止本进程(单任务独占进程,安全兜底)。
+"""
+from __future__ import annotations
+
+import json
+import sys
+import threading
+import traceback
+from typing import Any
+
+from problems import check_finite, solve_linear_mpc, solve_steady_response
+
+PROTOCOL_VERSION = 1
+
+_event = threading.Event()
+_cancel = threading.Event()
+_busy = threading.Event()
+_active_req: dict[str, Any] = {"reqId": None}
+
+
+def emit(frame: dict[str, Any]) -> None:
+    sys.stdout.write(json.dumps(frame, ensure_ascii=False, separators=(",", ":")) + "\n")
+    sys.stdout.flush()
+
+
+def log(message: str) -> None:
+    sys.stderr.write(message + "\n")
+    sys.stderr.flush()
+
+
+def run_solve(req: dict[str, Any]) -> None:
+    req_id = str(req.get("reqId", ""))
+    _active_req["reqId"] = req_id
+    _cancel.clear()
+    payload = req.get("payload") or {}
+    ir = payload.get("problemIr")
+    try:
+        if not isinstance(ir, dict):
+            raise ValueError("payload.problemIr 必须是对象")
+        template = (ir.get("problem") or {}).get("template")
+        if template == "linear_mpc_quadratic@1":
+            result = solve_linear_mpc(ir, _cancel.is_set)
+        elif template == "steady_response@1":
+            result = solve_steady_response(ir, _cancel.is_set)
+        else:
+            result = {"status": "unsupported", "message": f"unsupported template: {template}"}
+        if not check_finite(result):
+            result = {"status": "numerical_error", "message": "solver produced NaN/Inf"}
+        emit({
+            "protocolVersion": PROTOCOL_VERSION,
+            "reqId": req_id,
+            "ok": True,
+            "result": result,
+            "diag": {"backend": result.get("backend"), "iterations": result.get("iterations")},
+        })
+    except Exception as exc:  # noqa: BLE001 - 协议层必须把任何异常变成 error 帧
+        log(traceback.format_exc())
+        emit({
+            "protocolVersion": PROTOCOL_VERSION,
+            "reqId": req_id,
+            "ok": False,
+            "error": {"code": "SOLVER_ERROR", "message": str(exc)},
+        })
+    finally:
+        _busy.clear()
+        _active_req["reqId"] = None
+
+
+def handle(req: dict[str, Any]) -> None:
+    op = req.get("op")
+    req_id = str(req.get("reqId", ""))
+    if req.get("protocolVersion") != PROTOCOL_VERSION:
+        emit({"protocolVersion": PROTOCOL_VERSION, "reqId": req_id, "ok": False, "error": {"code": "PROTOCOL_MISMATCH", "message": "protocolVersion must be 1"}})
+        return
+    if op == "ping":
+        emit({"protocolVersion": PROTOCOL_VERSION, "reqId": req_id, "ok": True, "result": {"pong": True, "busy": _busy.is_set()}})
+        return
+    if op == "cancel":
+        target = (req.get("payload") or {}).get("reqId") or req_id
+        if _active_req.get("reqId") == target:
+            _cancel.set()
+        emit({"protocolVersion": PROTOCOL_VERSION, "reqId": req_id, "ok": True, "result": {"cancelled": _cancel.is_set(), "target": target}})
+        return
+    if op == "solve":
+        if _busy.is_set():
+            emit({"protocolVersion": PROTOCOL_VERSION, "reqId": req_id, "ok": False, "error": {"code": "SOLVER_BUSY", "message": "worker 正在执行另一个 solve"}})
+            return
+        _busy.set()
+        thread = threading.Thread(target=run_solve, args=(req,), daemon=True)
+        thread.start()
+        return
+    emit({"protocolVersion": PROTOCOL_VERSION, "reqId": req_id, "ok": False, "error": {"code": "UNKNOWN_OP", "message": f"unknown op: {op}"}})
+
+
+def main() -> None:
+    emit({"protocolVersion": PROTOCOL_VERSION, "type": "ready", "diag": {"pid": __import__("os").getpid(), "python": sys.version.split()[0]}})
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            req = json.loads(line)
+        except Exception:
+            emit({"protocolVersion": PROTOCOL_VERSION, "reqId": "", "ok": False, "error": {"code": "BAD_JSON", "message": "invalid JSON frame"}})
+            continue
+        handle(req)
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,100 @@
+/**
+ * 建议生命周期(G3.7 / C10):
+ *  - 不可变、带 valid_until;
+ *  - 缺 UQ/OOD 证据 → unverified,UI/回执必须原样显示;
+ *  - 工况/配方/权限/revision 变化 → expired(不删除,保留审计)。
+ */
+import type { Recommendation, SolveCandidate } from './contracts'
+import { recommendationLabel } from './contracts'
+import { getRunRepo } from './run.repo'
+import { coverageThreshold } from './uq-evidence'
+
+export const RECOMMENDATION_TTL_MS = 15 * 60_000
+
+/** 建议 UQ 证据快照 = 工件 uq + artifactHash 锚 + 本次上下文 inputDistance(D2/D4/D5 单源) */
+export interface UqEvidence {
+  method?: 'split_conformal' | 'empirical_max'
+  qhatPerCv?: number[]
+  /** test 段实测 min_j coverage(旧字段 coverage 兼容读取) */
+  coverageTest?: number
+  coverage?: number
+  alpha?: number
+  horizon?: number
+  nValBlocks?: number
+  nValRuns?: number
+  nTestBlocks?: number
+  nTestRuns?: number
+  nUniqueTestSteps?: number
+  safetyFactor?: number
+  calibratedAt?: string
+  artifactHash?: string
+  calibrationFresh?: boolean
+  inputDistance?: number | null
+  evidenceVersion?: string
+}
+
+const OOD_DISTANCE_LIMIT = 3
+
+/** 只有显式携带完整校准证据才算 verified;缺省/不完整一律 unverified(不伪造)。 */
+export function classifyRecommendation(input: {
+  evidenceSource: 'simulation' | 'real' | 'unassessed'
+  uqEvidence: UqEvidence | null
+  candidateFeasible: boolean
+}): { status: 'verified' | 'unverified', reason: string } {
+  if (!input.candidateFeasible) return { status: 'unverified', reason: '候选未通过独立约束校验' }
+  if (input.evidenceSource !== 'simulation' && input.evidenceSource !== 'real') return { status: 'unverified', reason: '证据来源尚未评估' }
+  const uq = input.uqEvidence
+  if (!uq) return { status: 'unverified', reason: '缺工件 UQ 证据(旧工件/样本不足未发证)' }
+  const coverage = uq.coverageTest ?? uq.coverage
+  if (coverage == null || !Number.isFinite(coverage) || coverage < 0 || coverage > 1) return { status: 'unverified', reason: 'UQ coverage 必须是 [0,1] 范围内的有限数值' }
+  // D3 门限:0.8 硬底 + 分块修正;empirical_max 必须 1.0
+  const threshold = coverageThreshold({ method: uq.method ?? 'split_conformal', nTestRuns: uq.nTestRuns ?? 1 })
+  if (coverage < threshold) return { status: 'unverified', reason: `UQ coverage 不足(${coverage} < ${threshold.toFixed(3)},method=${uq.method ?? 'split_conformal'})` }
+  if (uq.calibrationFresh !== true) return { status: 'unverified', reason: 'UQ 校准已过期或未评估' }
+  if (uq.inputDistance == null) return { status: 'unverified', reason: 'inputDistance 未评估(norm 缺失/列序不符);不得按 0 乐观处理' }
+  if (!Number.isFinite(uq.inputDistance) || uq.inputDistance < 0) return { status: 'unverified', reason: 'inputDistance 必须是非负有限数值' }
+  if (uq.inputDistance > OOD_DISTANCE_LIMIT) return { status: 'unverified', reason: `当前操作点偏离训练分布(OOD):inputDistance=${uq.inputDistance.toFixed(2)} > ${OOD_DISTANCE_LIMIT}` }
+  return { status: 'verified', reason: 'UQ/OOD 证据完整(val 校准/test 实证,coverage 达 D3 门,操作点在域内)' }
+}
+
+export function createRecommendation(input: {
+  runId: string
+  candidate: SolveCandidate
+  candidateId: string
+  problemIrHash: string
+  modelArtifactHash: string
+  evidenceSource: 'simulation' | 'real' | 'unassessed'
+  uqEvidence: UqEvidence | null
+}): Recommendation {
+  const classified = classifyRecommendation({
+    evidenceSource: input.evidenceSource,
+    uqEvidence: input.uqEvidence,
+    candidateFeasible: input.candidate.feasible,
+  })
+  const id = `orec-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 7)}`
+  return getRunRepo().insertRecommendation({
+    id,
+    runId: input.runId,
+    candidateId: input.candidateId,
+    problemIrHash: input.problemIrHash,
+    modelArtifactHash: input.modelArtifactHash,
+    evidenceSource: input.evidenceSource,
+    uqEvidence: input.uqEvidence as Record<string, unknown> | null,
+    status: classified.status,
+    validUntil: new Date(Date.now() + RECOMMENDATION_TTL_MS).toISOString(),
+  })
+}
+
+export function expireRecommendations(filter: { runId?: string, bindingId?: string, problemIrHash?: string }): number {
+  return getRunRepo().expireWhere(filter)
+}
+
+export function assertRecommendationUsable(rec: Recommendation): Recommendation {
+  const expired = Date.parse(rec.validUntil) <= Date.now()
+  if (expired && rec.status !== 'expired') {
+    getRunRepo().expireWhere({ runId: rec.runId })
+    return { ...rec, status: 'expired', statusLabel: recommendationLabel('expired') }
+  }
+  if (rec.status === 'expired') return rec
+  return rec
+}

package/server/services/workshop/optimization/rest-auth.ts

@@ -0,0 +1,61 @@
+/**
+ * Optimizer REST 授权:登录 + 角色只是入口,必须再核验"该用户可支配该 Agent 实例"。
+ * 口径与 agent-tools/invoke 一致:admin 放行;其余必须是该 Channel 的成员/owner。
+ *
+ * 直接读 globalThis.__workshopManager(插件启动时装配):避免静态 import plugins/workshop
+ * 把 Nitro `#imports` 拖进本模块,便于单测注入假管理器。
+ */
+import { AppError } from '../../../utils/errors'
+import { getAmlRuntime } from '../aml/runtime'
+import type { ResolvedUser } from '../../../api/workshop/caller'
+import { getBindingRepo } from './binding.repo'
+import { revokeBinding } from './binding.service'
+import { getRunRepo } from './run.repo'
+
+interface ManagerLike {
+  deps: { repos: { channelAgents: { findById(id: string): { channelId: string } | undefined } } }
+  channelPermissionsOf(channelId: string, user: ResolvedUser): { isMember: boolean, canManage?: boolean }
+}
+
+export function assertAgentAccess(user: ResolvedUser, agentInstanceId: string, options: { manage?: boolean } = {}): { channelId: string } {
+  const manager = (globalThis as { __workshopManager?: ManagerLike }).__workshopManager
+  if (!manager) throw new AppError(503, 'WORKSHOP_NOT_READY', 'workshop 未就绪')
+  const row = manager.deps.repos.channelAgents.findById(agentInstanceId)
+  if (!row) {
+    // 模板 id(channel_agents 之外、agents 表内)给出可行动的具体错误,
+    // 而不是笼统的 404 —— 调用方需要知道"改用实例 id"。
+    let template: unknown
+    try {
+      template = getAmlRuntime().db.prepare('SELECT id FROM agents WHERE id = ?').get(agentInstanceId)
+    }
+    catch {
+      // AML 未初始化(单测/插件未启动)→ 保持既有 404 语义
+      template = undefined
+    }
+    if (template) {
+      throw new AppError(422, 'AGENT_TEMPLATE_ID_NOT_ALLOWED',
+        `传入的是 Agent 模板 id(${agentInstanceId});必须使用 Channel 实例 id(channel_agents.id)`)
+    }
+    throw new AppError(404, 'AGENT_NOT_FOUND', `Agent 实例 ${agentInstanceId} 不存在`)
+  }
+  if (user.role === 'admin') return { channelId: row.channelId }
+  const permissions = manager.channelPermissionsOf(row.channelId, user)
+  if (!permissions.isMember) {
+    throw new AppError(403, 'SCOPE_VIOLATION', '该 Agent 不属于当前用户所在 Channel,无权读取/代调用其优化器')
+  }
+  if (options.manage && !permissions.canManage) {
+    throw new AppError(403, 'SCOPE_VIOLATION', '无权管理该 Agent 所属 Channel 的优化器绑定')
+  }
+  return { channelId: row.channelId }
+}
+
+/** 管理授权通过后才撤权,避免拒绝请求使他人的建议失效。 */
+export function revokeBindingForUser(user: ResolvedUser, bindingId: string): void {
+  const binding = getBindingRepo().get(bindingId)
+  if (!binding) throw new AppError(404, 'BINDING_NOT_FOUND', `绑定 ${bindingId} 不存在`)
+  assertAgentAccess(user, binding.channelAgentId, { manage: true })
+  getRunRepo().expireWhere({ bindingId })
+  if (!revokeBinding(bindingId, user.id, user.name)) {
+    throw new AppError(404, 'BINDING_NOT_FOUND', `绑定 ${bindingId} 不存在`)
+  }
+}

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

@@ -0,0 +1,158 @@
+/**
+ * OptimizationRun / Candidate / Recommendation / Outcome 仓储(不可变运行台账)。
+ */
+/* eslint-disable @stylistic/max-statements-per-line, @stylistic/member-delimiter-style */
+import type { DatabaseSync } from 'node:sqlite'
+import { getAmlRuntime } from '../aml/runtime'
+import type { ProblemIR, Recommendation, RecommendationStatus, SolveCandidate, SolveResult } from './contracts'
+import { recommendationLabel } from './contracts'
+
+export interface RunRow {
+  id: string
+  bindingId: string
+  bindingRevision: number
+  profileId: string
+  profileVersion: number
+  problemIrHash: string
+  status: string
+  independentCost: number | null
+  startedAt: string
+  finishedAt: string | null
+  problemIrJson: string
+  diagnosticsJson: string
+}
+
+const RUN_COLS = `id, binding_id AS bindingId, binding_revision AS bindingRevision, profile_id AS profileId,
+  profile_version AS profileVersion, problem_ir_hash AS problemIrHash, status, independent_cost AS independentCost,
+  started_at AS startedAt, finished_at AS finishedAt, problem_ir_json AS problemIrJson, diagnostics_json AS diagnosticsJson`
+
+export function createRunRepo(db: DatabaseSync) {
+  return {
+    insertRun(input: { id: string, bindingId: string, bindingRevision: number, profileId: string, profileVersion: number, ir: ProblemIR, context: unknown, startedAt: string }): void {
+      db.prepare(`INSERT INTO optimizer_runs
+        (id, binding_id, binding_revision, profile_id, profile_version, problem_ir_hash, context_snapshot_json,
+         problem_ir_json, status, diagnostics_json, started_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'running', '{}', ?)`)
+        .run(input.id, input.bindingId, input.bindingRevision, input.profileId, input.profileVersion,
+          input.ir.hash, JSON.stringify(input.context ?? {}), JSON.stringify(input.ir), input.startedAt)
+    },
+
+    finishRun(id: string, result: SolveResult): void {
+      db.prepare(`UPDATE optimizer_runs SET status = ?, diagnostics_json = ?, independent_cost = ?, finished_at = ? WHERE id = ? AND status = 'running'`)
+        .run(result.status, JSON.stringify(result.diagnostics ?? {}), result.independentCost, new Date().toISOString(), id)
+    },
+
+    getRun(id: string): RunRow | undefined {
+      return db.prepare(`SELECT ${RUN_COLS} FROM optimizer_runs WHERE id = ?`).get(id) as unknown as RunRow | undefined
+    },
+
+    listRuns(filter: { bindingId?: string, limit?: number } = {}): RunRow[] {
+      const where = filter.bindingId ? 'WHERE binding_id = ?' : ''
+      const args: unknown[] = filter.bindingId ? [filter.bindingId, filter.limit ?? 50] : [filter.limit ?? 50]
+      return db.prepare(`SELECT ${RUN_COLS} FROM optimizer_runs ${where} ORDER BY started_at DESC LIMIT ?`).all(...(args as never[])) as unknown as RunRow[]
+    },
+
+    insertCandidates(runId: string, candidates: SolveCandidate[], modelId?: string): string[] {
+      const ids: string[] = []
+      for (const candidate of candidates) {
+        const id = `oc-${runId.slice(3)}-${candidate.seq}`
+        ids.push(id)
+        db.prepare(`INSERT INTO optimizer_candidates
+          (id, run_id, seq, controls_json, predicted_json, cost, constraints_json, verified, verify_report_json, model_id)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+          .run(id, runId, candidate.seq, JSON.stringify(candidate.controls), JSON.stringify(candidate.predicted),
+            candidate.cost, JSON.stringify(candidate.constraints), candidate.feasible ? 1 : 0, JSON.stringify({ feasible: candidate.feasible }), modelId ?? '')
+      }
+      return ids
+    },
+
+    getCandidate(id: string): { id: string, runId: string, seq: number, controls: number[][], predicted: number[][], cost: number | null, constraints: unknown[], verified: number } | undefined {
+      const r = db.prepare('SELECT id, run_id AS runId, seq, controls_json AS controls, predicted_json AS predicted, cost, constraints_json AS constraints, verified FROM optimizer_candidates WHERE id = ?').get(id) as Record<string, unknown> | undefined
+      if (!r) return undefined
+      return {
+        id: String(r.id),
+        runId: String(r.runId),
+        seq: Number(r.seq),
+        controls: JSON.parse(String(r.controls)) as number[][],
+        predicted: JSON.parse(String(r.predicted)) as number[][],
+        cost: r.cost == null ? null : Number(r.cost),
+        constraints: JSON.parse(String(r.constraints)) as unknown[],
+        verified: Number(r.verified ?? 0),
+      }
+    },
+
+    listCandidates(runId: string): Array<{ id: string, seq: number, cost: number | null }> {
+      return db.prepare('SELECT id, seq, cost FROM optimizer_candidates WHERE run_id = ? ORDER BY seq ASC').all(runId) as Array<{ id: string, seq: number, cost: number | null }>
+    },
+
+    insertRecommendation(input: {
+      id: string, runId: string, candidateId: string, problemIrHash: string, modelArtifactHash: string
+      evidenceSource: 'simulation' | 'real' | 'unassessed', uqEvidence: Record<string, unknown> | null
+      status: RecommendationStatus, validUntil: string
+    }): Recommendation {
+      const now = new Date().toISOString()
+      const label = recommendationLabel(input.status)
+      db.prepare(`INSERT INTO optimizer_recommendations
+        (id, run_id, candidate_id, problem_ir_hash, model_artifact_hash, evidence_source, uq_evidence_json,
+         status, status_label, legacy, valid_until, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, '', ?, ?)`)
+        .run(input.id, input.runId, input.candidateId, input.problemIrHash, input.modelArtifactHash,
+          input.evidenceSource, input.uqEvidence ? JSON.stringify(input.uqEvidence) : null,
+          input.status, label, input.validUntil, now)
+      return this.getRecommendation(input.id)!
+    },
+
+    getRecommendation(id: string): Recommendation | undefined {
+      const r = db.prepare(`SELECT id, run_id AS runId, candidate_id AS candidateId, problem_ir_hash AS problemIrHash,
+        model_artifact_hash AS modelArtifactHash, evidence_source AS evidenceSource, uq_evidence_json AS uqEvidenceJson,
+        status, status_label AS statusLabel, valid_until AS validUntil, created_at AS createdAt
+        FROM optimizer_recommendations WHERE id = ?`).get(id) as Record<string, unknown> | undefined
+      if (!r) return undefined
+      return {
+        id: String(r.id), runId: String(r.runId), candidateId: String(r.candidateId),
+        problemIrHash: String(r.problemIrHash), modelArtifactHash: String(r.modelArtifactHash),
+        evidenceSource: String(r.evidenceSource) as Recommendation['evidenceSource'],
+        uqEvidence: r.uqEvidenceJson ? JSON.parse(String(r.uqEvidenceJson)) as Record<string, unknown> : null,
+        status: String(r.status) as RecommendationStatus, statusLabel: String(r.statusLabel || recommendationLabel(String(r.status) as RecommendationStatus)),
+        validUntil: String(r.validUntil), createdAt: String(r.createdAt),
+      }
+    },
+
+    latestRecommendationForRun(runId: string): Recommendation | undefined {
+      const r = db.prepare('SELECT id FROM optimizer_recommendations WHERE run_id = ? ORDER BY created_at DESC LIMIT 1').get(runId) as { id: string } | undefined
+      return r ? this.getRecommendation(r.id) : undefined
+    },
+
+    /** 失效:工况/配方/权限/revison 变化 → 旧建议 expired(不删除,保留审计)。 */
+    expireWhere(filter: { bindingId?: string, runId?: string, problemIrHash?: string }): number {
+      const where: string[] = ['status != \'expired\'']
+      const args: unknown[] = []
+      if (filter.runId) { where.push('run_id = ?'); args.push(filter.runId) }
+      if (filter.problemIrHash) { where.push('problem_ir_hash = ?'); args.push(filter.problemIrHash) }
+      if (filter.bindingId) { where.push('run_id IN (SELECT id FROM optimizer_runs WHERE binding_id = ?)'); args.push(filter.bindingId) }
+      const r = db.prepare(`UPDATE optimizer_recommendations SET status = 'expired', status_label = ? WHERE ${where.join(' AND ')}`)
+        .run(recommendationLabel('expired'), ...(args as never[]))
+      return Number(r.changes)
+    },
+
+    insertOutcome(input: { id: string, recommendationId: string, appliedAt: string | null, observed: Record<string, unknown>, delta: Record<string, unknown>, verdict: string }): void {
+      db.prepare(`INSERT INTO optimizer_outcomes (id, recommendation_id, applied_at, observed_json, delta_json, verdict, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?)`)
+        .run(input.id, input.recommendationId, input.appliedAt, JSON.stringify(input.observed), JSON.stringify(input.delta), input.verdict, new Date().toISOString())
+    },
+
+    listOutcomes(recommendationId: string): Array<{ id: string, verdict: string, delta: Record<string, unknown>, appliedAt: string | null }> {
+      return (db.prepare('SELECT id, verdict, delta_json AS delta, applied_at AS appliedAt FROM optimizer_outcomes WHERE recommendation_id = ? ORDER BY created_at ASC').all(recommendationId) as Array<{ id: string, verdict: string, delta: string, appliedAt: string | null }>)
+        .map(r => ({ id: r.id, verdict: r.verdict, delta: JSON.parse(r.delta) as Record<string, unknown>, appliedAt: r.appliedAt }))
+    },
+  }
+}
+
+export type RunRepo = ReturnType<typeof createRunRepo>
+
+const g = globalThis as typeof globalThis & { __optimizerRunRepo?: RunRepo }
+
+export function getRunRepo(): RunRepo {
+  g.__optimizerRunRepo ??= createRunRepo(getAmlRuntime().db)
+  return g.__optimizerRunRepo
+}

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

@@ -0,0 +1,3 @@
+/** 问题模板常量(与 Twin Registry 的 ObjectiveAdapter ref 同名)。 */
+export const LINEAR_MPC_TEMPLATE = 'linear_mpc_quadratic@1' as const
+export const STEADY_RESPONSE_TEMPLATE = 'steady_response@1' as const

package/server/services/workshop/optimization/uq-evidence.ts

@@ -0,0 +1,144 @@
+/**
+ * UQ 证据(D2/D3/D4/D5)——工件级、块级 conformal,唯一证据源。
+ *
+ * 统计量 = h 步 rollout 残差在块内最大值(逐 CV,模型单位);h = 训练时 ds.P(static 固定 1)。
+ * 校准段(val)定 qhat,检验段(test)实测 coverage —— 两段不相交。
+ * 两种模式:
+ *   - split_conformal:nValBlocks≥9 ∧ nValRuns≥2,分位数 ⌈(n+1)(1−α)⌉/n(α=0.1)
+ *   - empirical_max:2≤nValBlocks≤8,qhat = max(val)×1.25(预注册安全系数),coverage 必须 =1
+ * emit 条件:nUniqueTestSteps≥120 ∧ nTestRuns≥2;不足不发证(fail-closed)。
+ * verified 门限(D3):coverage ≥ max(0.8, 0.9−3√(0.09/nTestRuns));empirical_max → 1.0。
+ */
+import { amlUqFreshDays } from '../settings'
+
+export interface ArtifactUq {
+  method: 'split_conformal' | 'empirical_max'
+  qhatPerCv: number[]
+  coverageTest: number
+  alpha: number
+  horizon: number
+  nValBlocks: number
+  nValRuns: number
+  nValUniqueSteps: number
+  nTestBlocks: number
+  nTestRuns: number
+  nUniqueTestSteps: number
+  safetyFactor?: number
+  calibratedAt: string
+}
+
+export interface BlockUqInput {
+  /** val 段逐块逐 CV 的 max|h 步残差|(模型单位) */
+  valScoresPerCv: Array<number[]>
+  testScoresPerCv: Array<number[]>
+  nValRuns: number
+  nTestRuns: number
+  nUniqueTestSteps: number
+  horizon: number
+  alpha?: number
+  calibratedAt?: string
+}
+
+/** ⌈(n+1)(1−α)⌉ 阶统计量(split conformal;rank 超界时取 max) */
+function conformalQuantile(scores: number[], alpha: number): number {
+  const n = scores.length
+  if (!n) return Number.POSITIVE_INFINITY
+  const rank = Math.min(n, Math.ceil((n + 1) * (1 - alpha)))
+  const sorted = [...scores].sort((a, b) => a - b)
+  return sorted[rank - 1] ?? sorted[n - 1] ?? Number.POSITIVE_INFINITY
+}
+
+export function computeBlockUq(input: BlockUqInput): { uq: ArtifactUq | null, reason: string } {
+  const alpha = input.alpha ?? 0.1
+  const nValBlocks = input.valScoresPerCv.length
+  const nTestBlocks = input.testScoresPerCv.length
+  // emit 条件(D2):样本量不足不发 uq → 维持 unverified(fail-closed)
+  if (input.nUniqueTestSteps < 120 || input.nTestRuns < 2 || nTestBlocks < 1) {
+    return { uq: null, reason: `样本量不足(nUniqueTestSteps=${input.nUniqueTestSteps}<120 或 nTestRuns=${input.nTestRuns}<2);不发 UQ 证据` }
+  }
+  if (nValBlocks < 2 || input.nValRuns < 1) {
+    return { uq: null, reason: `校准块不足(nValBlocks=${nValBlocks}<2);不发 UQ 证据` }
+  }
+  const cvCount = input.valScoresPerCv[0]?.length ?? 0
+  if (!cvCount) return { uq: null, reason: '无 CV 校准分数' }
+
+  const useConformal = nValBlocks >= 9 && input.nValRuns >= 2
+  const qhatPerCv: number[] = []
+  for (let j = 0; j < cvCount; j++) {
+    const valScores = input.valScoresPerCv.map(r => r[j] ?? Number.POSITIVE_INFINITY).filter(Number.isFinite)
+    if (valScores.length !== nValBlocks) return { uq: null, reason: `CV ${j} 校准分数含非有限值;不发 UQ 证据` }
+    qhatPerCv.push(useConformal ? conformalQuantile(valScores, alpha) : Math.max(...valScores) * 1.25)
+  }
+  // test 段实测 coverage(逐 CV 命中块数/测试块数;门取 min_j)
+  let minCoverage = 1
+  for (let j = 0; j < cvCount; j++) {
+    const testScores = input.testScoresPerCv.map(r => r[j] ?? Number.POSITIVE_INFINITY)
+    const hits = testScores.filter(s => Number.isFinite(s) && s <= (qhatPerCv[j] ?? Number.POSITIVE_INFINITY)).length
+    minCoverage = Math.min(minCoverage, nTestBlocks ? hits / nTestBlocks : 0)
+  }
+  return {
+    uq: {
+      method: useConformal ? 'split_conformal' : 'empirical_max',
+      qhatPerCv: qhatPerCv.map(q => Number(q.toFixed(9))),
+      coverageTest: Number(minCoverage.toFixed(6)),
+      alpha,
+      horizon: input.horizon,
+      nValBlocks,
+      nValRuns: input.nValRuns,
+      nValUniqueSteps: 0,
+      nTestBlocks,
+      nTestRuns: input.nTestRuns,
+      nUniqueTestSteps: input.nUniqueTestSteps,
+      ...(useConformal ? {} : { safetyFactor: 1.25 }),
+      calibratedAt: input.calibratedAt ?? new Date().toISOString(),
+    },
+    reason: useConformal ? 'split_conformal' : 'empirical_max(经验界,非 conformal)',
+  }
+}
+
+/** D3 verified 门限:0.8 硬底(裸公式在小样本塌缩到 0.264);empirical_max 必须 1.0 */
+export function coverageThreshold(uq: Pick<ArtifactUq, 'method' | 'nTestRuns'>): number {
+  if (uq.method === 'empirical_max') return 1.0
+  const n = Math.max(1, uq.nTestRuns)
+  return Math.max(0.8, 0.9 - 3 * Math.sqrt(0.09 / n))
+}
+
+/** D4 inputDistance = MV+CV 双偏移(σ 取工件 norm;σ≈0 → ∞;列数不符 → null,不伪造) */
+export function inputDistance(input: {
+  currentU: Array<number | undefined>
+  currentY: Array<number | undefined>
+  normU: { mean: number[], std: number[] }
+  normY: { mean: number[], std: number[] }
+}): number | null {
+  const dev = (values: Array<number | undefined>, norm: { mean: number[], std: number[] }): number | null => {
+    if (values.length !== norm.std.length || values.length !== norm.mean.length) return null
+    let max = 0
+    for (let i = 0; i < values.length; i++) {
+      const v = values[i]
+      if (v === undefined || !Number.isFinite(v)) return null
+      const sigma = Math.abs(norm.std[i] ?? 0)
+      if (sigma < 1e-9) return Number.POSITIVE_INFINITY
+      max = Math.max(max, Math.abs((v - (norm.mean[i] ?? 0)) / sigma))
+    }
+    return max
+  }
+  const du = dev(input.currentU, input.normU)
+  if (du === null) return null
+  const dy = dev(input.currentY, input.normY)
+  if (dy === null) return null
+  return Math.max(du, dy)
+}
+
+/** UQ 保鲜(D2):calibratedAt 超过 aml.uq.freshDays → 过期 */
+export function isUqFresh(uq: Pick<ArtifactUq, 'calibratedAt'>, now = Date.now()): boolean {
+  const t = Date.parse(uq.calibratedAt)
+  if (!Number.isFinite(t)) return false
+  return now - t <= amlUqFreshDays() * 86_400_000
+}
+
+/** 建议 UQ 证据快照(进 recommendation 行;含 artifactHash 锚,杜绝双证据路径) */
+export interface RecommendationUqEvidence extends ArtifactUq {
+  artifactHash: string
+  calibrationFresh: boolean
+  inputDistance: number | null
+}