agentworkshop 0.7.70 → 0.7.71

package/server/services/workshop/process-model/contracts.ts

@@ -0,0 +1,344 @@
+/**
+ * Process Model Service —— 类型化契约(单一事实来源)。
+ *
+ * 设计约束(见 docs/plans/2026-10-22-optimizer-process-model-plan.md §3.1.1 / G1.2):
+ *  - 模型家族用**判别联合**(artifactKind + modelInterface),未知类型一律抛
+ *    UNSUPPORTED_ARTIFACT / UNSUPPORTED_MODEL_INTERFACE,绝不静默回落到 ONNX;
+ *  - 配置只描述"用哪个内置训练器 / 什么输入输出语义",不接受用户 Python 代码;
+ *  - 单位换算必须显式(scale/offset),不猜测补齐;
+ *  - 工况 exactly-one 匹配,重叠/无匹配在发布与运行时都要报错。
+ */
+import { AppError } from '../../../utils/errors'
+
+/** 训练/求解共用契约版本(manifest v2 起) */
+export const PROCESS_MODEL_SCHEMA_VERSION = 2 as const
+export const PROCESS_MODEL_MANIFEST_VERSION = 2 as const
+export const PROCESS_MODEL_GATE_POLICY = 'process-model.gates@1' as const
+export const FEATURE_PIPELINE_VERSION = 1 as const
+
+// ===== 工件类型判别联合 =====
+
+export const ARTIFACT_KINDS = [
+  /** 旧 ONNX 一步预测(历史兼容;不能直接绑定 OSQP) */
+  'onnx_one_step@1',
+  /** Hybrid Twin 工件(旧链;不隐式转换模型含义) */
+  'hybrid_manifest@1',
+  /** 线性 ARX 辨识出的状态空间包(A/B/C/D/缩放/偏置/延迟/残差校准) */
+  'linear_state_space@1',
+  /** 静态响应面(系数/特征展开/缩放/偏置/留出残差) */
+  'static_response@1',
+] as const
+
+export type ArtifactKind = (typeof ARTIFACT_KINDS)[number]
+
+/** 模型接口 = 平台如何把输入喂给模型。与工件类型分开,允许同工件多接口版本演进。 */
+export const MODEL_INTERFACE_IDS = [
+  'one_step',
+  'linear_state_space',
+  'static_response',
+] as const
+
+export type ModelInterfaceId = (typeof MODEL_INTERFACE_IDS)[number]
+
+export interface ArtifactDescriptor {
+  kind: ArtifactKind
+  schemaVersion: number
+  /** 工件主文件相对路径(在模型实体目录内) */
+  entryFile: string
+  /** 必需伴随文件(完整性检查清单) */
+  requiredFiles: string[]
+  artifactHash: string
+}
+
+export function isArtifactKind(value: unknown): value is ArtifactKind {
+  return typeof value === 'string' && (ARTIFACT_KINDS as readonly string[]).includes(value)
+}
+
+export function isModelInterfaceId(value: unknown): value is ModelInterfaceId {
+  return typeof value === 'string' && (MODEL_INTERFACE_IDS as readonly string[]).includes(value)
+}
+
+export function assertArtifactKind(value: unknown): ArtifactKind {
+  if (!isArtifactKind(value)) {
+    throw new AppError(422, 'UNSUPPORTED_ARTIFACT', `不支持的工件类型 artifactKind=${String(value)};允许值:${ARTIFACT_KINDS.join(', ')}`)
+  }
+  return value
+}
+
+export function assertModelInterfaceId(value: unknown): ModelInterfaceId {
+  if (!isModelInterfaceId(value)) {
+    throw new AppError(422, 'UNSUPPORTED_MODEL_INTERFACE', `不支持的模型接口 modelInterface=${String(value)};允许值:${MODEL_INTERFACE_IDS.join(', ')}`)
+  }
+  return value
+}
+
+// ===== 变量与工况 =====
+
+export const VARIABLE_ROLES = ['mv', 'cv', 'md', 'feature'] as const
+export type VariableRole = (typeof VARIABLE_ROLES)[number]
+
+/**
+ * 输入语义:
+ *  - setpoint      —— 设定值作为模型输入,实际过程量作为状态/观测(执行器滞后进响应模型);
+ *  - process_value —— 实际过程量作为模型输入;在线候选设定值必须先经执行器模型转换。
+ * 缺映射时拒绝发布(不允许"猜")。
+ */
+export const INPUT_SEMANTICS = ['setpoint', 'process_value'] as const
+export type InputSemantics = (typeof INPUT_SEMANTICS)[number]
+
+export interface VariableMap {
+  /** 用户语义变量 id(Profile/目标/约束引用它) */
+  id: string
+  /** DAQ 节点 id */
+  nodeId: string
+  role: VariableRole
+  /** 源字段(未来可扩 readback/setpoint;首版 value) */
+  field: 'value' | 'setpoint' | 'readback'
+  /** 源单位(必须与 DAQ 元数据一致或显式换算) */
+  unit: string
+  /** 模型单位(缺省 = 源单位) */
+  modelUnit?: string
+  /** 显式仿射换算:model = source * scale + offset */
+  scale: number
+  offset: number
+  /** 作用延迟(ms);对 MV 必填,0 也是显式值 */
+  delayMs?: number
+  min?: number
+  max?: number
+  maxStep?: number
+  /** SW5:MV 的下发执行节点(DCW);parse 可选(旧 spec),publish/dispatch required */
+  controlNodeId?: string
+}
+
+export interface ConditionClause {
+  /** 上下文维度:productId / recipeId / recipeVersion / stage / lineId */
+  field: 'productId' | 'recipeId' | 'recipeVersion' | 'stage' | 'lineId'
+  /** eq 精确;range 闭区间 */
+  op: 'eq' | 'range'
+  value: string | number | [number, number]
+}
+
+export interface ConditionSpec {
+  id: string
+  label?: string
+  /** 全部子句 AND;必须 exactly-one 命中 */
+  match: ConditionClause[]
+}
+
+export interface RuntimeContextInput {
+  lineId: string
+  productId: string
+  recipeId: string
+  recipeVersion: number
+  stage?: string
+}
+
+/** 返回命中的工况 id;零命中/多命中都抛错(不依赖隐式优先级)。 */
+export function matchCondition(conditions: ConditionSpec[], context: RuntimeContextInput): string {
+  const hits: string[] = []
+  for (const condition of conditions) {
+    const matched = condition.match.every((clause) => {
+      const actual = (context as unknown as Record<string, unknown>)[clause.field]
+      if (clause.op === 'eq') return String(actual ?? '') === String(clause.value)
+      if (typeof actual !== 'number') return false
+      const [lo, hi] = clause.value as [number, number]
+      return actual >= lo && actual <= hi
+    })
+    if (matched) hits.push(condition.id)
+  }
+  if (hits.length === 0) throw new AppError(422, 'CONDITION_NO_MATCH', `当前工况无匹配条件(可用:${conditions.map(c => c.id).join(', ')})`)
+  if (hits.length > 1) throw new AppError(422, 'CONDITION_OVERLAP', `当前工况命中多个条件(${hits.join(', ')});条件必须 exactly-one`)
+  return hits[0]!
+}
+
+// ===== 训练器 =====
+
+export const TRAINER_REFS = ['linear_arx@1', 'static_response@1'] as const
+export type TrainerRef = (typeof TRAINER_REFS)[number]
+
+export function isTrainerRef(value: unknown): value is TrainerRef {
+  return typeof value === 'string' && (TRAINER_REFS as readonly string[]).includes(value)
+}
+
+export const SOLVER_REFS = ['scipy_slsqp@1', 'osqp_mpc@1'] as const
+export type SolverRef = (typeof SOLVER_REFS)[number]
+
+export function isSolverRef(value: unknown): value is SolverRef {
+  return typeof value === 'string' && (SOLVER_REFS as readonly string[]).includes(value)
+}
+
+export const PROBLEM_TEMPLATE_REFS = ['linear_mpc_quadratic@1', 'steady_response@1'] as const
+export type ProblemTemplateRef = (typeof PROBLEM_TEMPLATE_REFS)[number]
+
+export function isProblemTemplateRef(value: unknown): value is ProblemTemplateRef {
+  return typeof value === 'string' && (PROBLEM_TEMPLATE_REFS as readonly string[]).includes(value)
+}
+
+// ===== 规格 =====
+
+export type ProcessModelStatus = 'draft' | 'published' | 'retired'
+
+export interface DatasetPolicy {
+  runIds?: string[]
+  fromMs?: number
+  toMs?: number
+  split: { valRatio: number, testRatio: number, seed: number }
+  cleaning?: { hampelK?: number, maxInterpMs?: number, maxDropRatio?: number }
+}
+
+export interface LinearArxTrainerConfig {
+  /** 每个 MV 的 AR 阶数 + 输入阶数(按输入显式延迟在 spec.variables.delayMs) */
+  arOrder: number
+  inputOrder: number
+  /** 岭回归正则(0 = 无正则) */
+  ridgeLambda: number
+  /** 输出归一化(以训练均值/标准差) */
+  standardize: boolean
+}
+
+export interface StaticResponseTrainerConfig {
+  /** 1 = 线性响应面;2 = 含二次项/交互项 */
+  order: 1 | 2
+  ridgeLambda: number
+  standardize: boolean
+}
+
+export interface ProcessModelTiming {
+  /** 采样节拍 */
+  beatMs: number
+  /** 历史窗口步数(ARX 阶数 >= arOrder 时用于状态初始化) */
+  historySteps: number
+  /** 预测时域步数 */
+  horizonSteps: number
+  /** 首版固定采样周期,不做通用变步长 */
+  fixedDt: true
+}
+
+export interface ModelInterfaceSpec {
+  id: ModelInterfaceId
+  version: number
+  inputSemantics: InputSemantics
+  /** 首版恒为 history[H,F] → y_next[C](一步)或线性状态空间 rollout */
+  mode: 'one_step' | 'state_space' | 'static'
+}
+
+export interface EffectiveDomain {
+  /** 训练数据覆盖的输入区间(运行时越界 → OOD) */
+  mv: Record<string, { min: number, max: number, maxStep?: number }>
+  cv?: Record<string, { min: number, max: number }>
+}
+
+export interface ProcessModelSpec {
+  schemaVersion: typeof PROCESS_MODEL_SCHEMA_VERSION
+  /** 稳定 id;发布后版本不可原地修改 */
+  id: string
+  version: number
+  lineId: string
+  productId: string
+  recipeId: string
+  recipeVersion: number
+  conditions: ConditionSpec[]
+  variables: VariableMap[]
+  timing: ProcessModelTiming
+  trainer: { ref: TrainerRef, config: LinearArxTrainerConfig | StaticResponseTrainerConfig }
+  datasetPolicy: DatasetPolicy
+  gatePolicyRef: typeof PROCESS_MODEL_GATE_POLICY
+  modelInterface: ModelInterfaceSpec
+  effectiveDomain: EffectiveDomain
+  /** 训练产物落到哪个 AML 数据集的 purpose(legacy 表沿用 mpc_surrogate 等) */
+  purpose: 'mpc_surrogate' | 'quality_predict'
+  note?: string
+  status?: ProcessModelStatus
+  createdAt?: string
+}
+
+export function artifactKindOfTrainer(ref: TrainerRef): ArtifactKind {
+  if (ref === 'linear_arx@1') return 'linear_state_space@1'
+  if (ref === 'static_response@1') return 'static_response@1'
+  throw new AppError(422, 'UNSUPPORTED_ARTIFACT', `训练器 ${String(ref)} 没有对应工件类型`)
+}
+
+export function modelInterfaceOfTrainer(ref: TrainerRef): ModelInterfaceSpec {
+  if (ref === 'linear_arx@1') return { id: 'linear_state_space', version: 1, inputSemantics: 'setpoint', mode: 'state_space' }
+  if (ref === 'static_response@1') return { id: 'static_response', version: 1, inputSemantics: 'setpoint', mode: 'static' }
+  throw new AppError(422, 'UNSUPPORTED_MODEL_INTERFACE', `训练器 ${String(ref)} 没有对应模型接口`)
+}
+
+/** 该工件类型是否能被某求解器消费(ONNX 黑箱不能直接交给 OSQP)。 */
+export function solverSupportsArtifact(solver: SolverRef, kind: ArtifactKind): boolean {
+  if (solver === 'osqp_mpc@1') return kind === 'linear_state_space@1'
+  if (solver === 'scipy_slsqp@1') return kind === 'static_response@1' || kind === 'linear_state_space@1'
+  return false
+}
+
+export function assertSolverSupportsArtifact(solver: SolverRef, kind: ArtifactKind, detail?: string): void {
+  if (!solverSupportsArtifact(solver, kind)) {
+    throw new AppError(422, 'UNSUPPORTED_MODEL_SOLVER', `求解器 ${solver} 不能消费工件 ${kind}${detail ? `(${detail})` : ''}`)
+  }
+}
+
+// ===== 资格 =====
+
+export interface EligibilityGap {
+  code: string
+  message: string
+  detail?: Record<string, unknown>
+}
+
+export interface EligibilityReport {
+  predictionEligible: boolean
+  optimizationEligible: boolean
+  scope: 'simulation' | 'real'
+  conditionId: string
+  evidenceVersion: string
+  gaps: EligibilityGap[]
+  metrics: Record<string, number | string | boolean | null>
+  createdAt: string
+}
+
+export type EvidenceSource = 'simulation' | 'real' | 'unassessed'
+
+// ===== 数据集 manifest v2 =====
+
+export interface ManifestV2 {
+  version: 2
+  dataKind: 'dynamic' | 'static'
+  specHash: string
+  contentHash: string
+  conditionId: string
+  variables: VariableMap[]
+  timing: ProcessModelTiming
+  shapes: {
+    x: [number, number, number]
+    u: [number, number, number]
+    y: [number, number, number]
+  }
+  norm: Record<string, { mean: number[], std: number[] }>
+  artifacts: {
+    x: string
+    u: string
+    y: string
+    timestamps: string
+    mask: string
+    sidecar: string
+  }
+  provenance: {
+    lineId: string
+    productId: string
+    recipeId: string
+    recipeVersion: number
+    runIds: string[]
+    recipeContentHash: string
+    evidenceSource: EvidenceSource
+    availabilityWatermark: number | null
+    capturedAt: string
+  }
+  trainerRef: TrainerRef
+  createdAt: string
+}
+
+/** 数据/模型工件内容摘要:排除生成时间/任务 id 等易变封套(同输入必须同摘要)。 */
+export function contentPayloadForHash<T extends Record<string, unknown>>(value: T): Omit<T, 'createdAt' | 'jobId' | 'runId'> {
+  const { createdAt: _createdAt, jobId: _jobId, runId: _runId, ...stable } = value
+  return stable as Omit<T, 'createdAt' | 'jobId' | 'runId'>
+}

package/server/services/workshop/process-model/dataset.ts

@@ -0,0 +1,144 @@
+/**
+ * Process Model 数据集构建(G2.6/G2.9):
+ *   spec(变量/单位/延迟/窗口/工况) → 复用 AML buildDataset → manifest v2(可追溯)。
+ *
+ * 不复制 AML 数据集实现;只在规格映射与 v2 元数据上扩展。取数走 queryTaggedPage
+ * (dataset-builder 内部,C7),不使用 EDA 图表的最多 2000 点展示数据。
+ */
+import { AppError } from '../../../utils/errors'
+import { getTsdb } from '../daq/storage'
+import { getDaqNodeRepo } from '../daq/daq-node.repo'
+import { getDcwRecipeRepo } from '../dcw/dcw-recipe.repo'
+import { getDcwLineRepo } from '../dcw/dcw-line.repo'
+import type { AmlDatasetSpec } from '../aml/spec'
+import { buildDataset, type ProcessDatasetExtras } from '../aml/dataset-builder'
+import type { ProcessModelSpec } from './contracts'
+import { parseProcessModelSpec } from './spec'
+import { recipeContentHash, getContextSegmentRepo } from './context-segments.repo'
+import { computeWatermark } from './watermark'
+
+export interface BuildProcessDatasetResult {
+  datasetId: string
+  rowCount: number
+  sha256: string
+  path: string
+  evidenceSource: 'simulation' | 'real' | 'unassessed'
+  availabilityWatermark: number | null
+  recipeVersion: number
+  runIds: string[]
+  /** D18:1 = 每 run 均有已确认 segment 且版本匹配;0 = 存在 unknown/排除(模型禁优化资格) */
+  lineageVerified: number
+  runLineage: { verified: string[], unknown: string[], excluded: Array<{ runId: string, reason: string }> }
+}
+
+/** ProcessModelSpec → 旧 AML 数据集规格(节点角色/窗口/切分/清洗一一映射)。 */
+export function toAmlDatasetSpec(spec: ProcessModelSpec): AmlDatasetSpec {
+  const nodes = spec.variables.map(variable => ({
+    nodeId: variable.nodeId,
+    role: variable.role === 'mv' ? 'control' as const : variable.role === 'cv' ? 'target' as const : 'feature' as const,
+  }))
+  if (!nodes.some(n => n.role === 'target')) {
+    throw new AppError(422, 'SPEC_INVALID', 'ProcessModelSpec 至少需要 1 个 CV(target)节点')
+  }
+  return {
+    lineId: spec.lineId,
+    productId: spec.productId,
+    recipeId: spec.recipeId,
+    runIds: spec.datasetPolicy.runIds,
+    fromMs: spec.datasetPolicy.fromMs,
+    toMs: spec.datasetPolicy.toMs,
+    nodes,
+    beatMs: spec.timing.beatMs,
+    window: { historySteps: spec.timing.historySteps, horizonSteps: spec.timing.horizonSteps },
+    cleaning: spec.datasetPolicy.cleaning,
+    split: spec.datasetPolicy.split,
+    purpose: spec.purpose,
+    note: spec.note ?? '',
+  }
+}
+
+export async function buildProcessModelDataset(raw: unknown, by: { id: string, kind: 'user' | 'agent' }): Promise<BuildProcessDatasetResult> {
+  const spec = parseProcessModelSpec(raw)
+  // 节点必须属于该产线(隔离硬约束;逐节点再核一次,给可定位错误)
+  const nodeRepo = getDaqNodeRepo()
+  for (const variable of spec.variables) {
+    const node = nodeRepo.byId(variable.nodeId)
+    if (!node) throw new AppError(404, 'PROCESS_NODE_MISSING', `变量 ${variable.id} 映射的节点 ${variable.nodeId} 不存在`)
+    if (node.lineId !== spec.lineId) throw new AppError(403, 'PROCESS_NODE_LINE_MISMATCH', `节点 ${variable.nodeId} 属于产线 ${node.lineId},与规格产线 ${spec.lineId} 不一致`)
+  }
+  const recipe = getDcwRecipeRepo().byId(spec.recipeId)
+  if (!recipe) throw new AppError(404, 'PROCESS_RECIPE_MISSING', `配方 ${spec.recipeId} 不存在`)
+  if (recipe.version !== undefined && spec.recipeVersion !== 0 && recipe.version !== spec.recipeVersion) {
+    throw new AppError(409, 'PROCESS_RECIPE_VERSION_MISMATCH', `配方当前版本 v${recipe.version} 与规格冻结版本 v${spec.recipeVersion} 不一致;请基于当前版本重建规格`)
+  }
+  const runs = getDcwRecipeRepo().listRuns().filter(r => r.recipeId === spec.recipeId && !!r.endedAt)
+  if (!runs.length) throw new AppError(422, 'PROCESS_NO_RUNS', '该配方没有已完结批次;先在产线跑完一批(或执行模拟试验)')
+  // D18 逐 run 版本归属:以已确认 context segment 为准,不用当前配方版本倒填历史。
+  //   - 段已确认且版本/内容 hash 与规格冻结一致 → verified
+  //   - 段版本不一致 → 该 run 排除(防止 v1 批次被 v2 规格冒名收编)
+  //   - 无任何段 → unknown(数据保留但 lineage_verified=0,模型禁优化资格)
+  const segmentRepo = getContextSegmentRepo()
+  const segmentsByRun = new Map<string, Array<{ confirmed: number, recipeId: string, recipeVersion: number, recipeContentHash: string }>>()
+  try {
+    for (const seg of segmentRepo.listByLine(spec.lineId)) {
+      const list = segmentsByRun.get(seg.runId) ?? []
+      list.push({ confirmed: seg.confirmed, recipeId: seg.recipeId, recipeVersion: seg.recipeVersion, recipeContentHash: seg.recipeContentHash })
+      segmentsByRun.set(seg.runId, list)
+    }
+  }
+  catch { /* 段表未初始化(单测)→ 全部按 unknown 处理 */ }
+  const frozenHash = recipeContentHash(recipe)
+  const verifiedRunIds: string[] = []
+  const unknownRunIds: string[] = []
+  const excludedRuns: Array<{ runId: string, reason: string }> = []
+  for (const r of runs) {
+    const segs = segmentsByRun.get(r.id) ?? []
+    if (!segs.length) {
+      unknownRunIds.push(r.id)
+      continue
+    }
+    const ok = segs.some(s => s.confirmed === 1
+      && s.recipeId === spec.recipeId
+      && (spec.recipeVersion === 0 || s.recipeVersion === spec.recipeVersion)
+      && s.recipeContentHash === frozenHash)
+    if (ok) verifiedRunIds.push(r.id)
+    else excludedRuns.push({ runId: r.id, reason: `context segment 版本与规格冻结版本 v${spec.recipeVersion || recipe.version} 不一致` })
+  }
+  const keptRuns = runs.filter(r => !excludedRuns.some(e => e.runId === r.id))
+  if (!keptRuns.length) throw new AppError(422, 'PROCESS_NO_RUNS', '全部历史批次的 context segment 与规格冻结版本不一致;请基于对应版本重建规格')
+  // 来源由产线性质决定:模拟线不能把数据标成 real(反之亦然)。
+  const line = getDcwLineRepo().byId(spec.lineId)
+  const evidenceSource: 'simulation' | 'real' | 'unassessed' = line?.simulated === true ? 'simulation' : 'real'
+  const availabilityWatermark = await computeWatermark(getTsdb(), spec, runs.map(r => r.id))
+
+  const amlSpec = toAmlDatasetSpec(spec)
+  // D18:被排除的 run 不进数据集(builder 按 runIds 过滤)
+  amlSpec.runIds = keptRuns.map(r => r.id)
+  const extras: ProcessDatasetExtras = {
+    specRef: spec.id,
+    specVersion: spec.version,
+    trainerRef: spec.trainer.ref,
+    conditionId: spec.conditions[0]?.id ?? '',
+    recipeVersion: spec.recipeVersion || recipe.version || 0,
+    recipeContentHash: recipeContentHash(recipe),
+    evidenceSource,
+    variables: spec.variables.map(v => ({
+      id: v.id, nodeId: v.nodeId, role: v.role, unit: v.unit, modelUnit: v.modelUnit, scale: v.scale, offset: v.offset, delayMs: v.delayMs,
+    })),
+    availabilityWatermark,
+    runLineage: { verified: verifiedRunIds, unknown: unknownRunIds, excluded: excludedRuns },
+  }
+  const built = await buildDataset(amlSpec, by, extras)
+  return {
+    datasetId: built.dataset.id,
+    rowCount: built.dataset.rowCount,
+    sha256: built.dataset.sha256,
+    path: built.dataset.path,
+    evidenceSource,
+    availabilityWatermark,
+    recipeVersion: extras.recipeVersion,
+    runIds: built.dataset.runIds,
+    lineageVerified: extras.runLineage ? (unknownRunIds.length === 0 && excludedRuns.length === 0 && verifiedRunIds.length > 0 ? 1 : 0) : 0,
+    runLineage: extras.runLineage ?? { verified: [], unknown: [], excluded: [] },
+  }
+}

package/server/services/workshop/process-model/eligibility-service.ts

@@ -0,0 +1,83 @@
+/**
+ * 资格评估编排:从已构建的 manifest v2 数据集重建各变量序列 → evaluateEligibility → 落库。
+ * 不接受 Agent 自报指标;序列来自不可变数据集工件。
+ */
+import { AppError } from '../../../utils/errors'
+import { getAmlRuntime } from '../aml/runtime'
+import { readDataset, pvX, pvY } from './trainers/dataset-reader'
+import { evaluateEligibility, getEligibilityRepo, type ActionEvidence, type EligibilitySeries } from './eligibility'
+import { getProcessModelSpecRepo, parseSpecRow } from './spec.repo'
+import type { EligibilityReport } from './contracts'
+import { getDcwLineRepo } from '../dcw/dcw-line.repo'
+
+export interface EvaluateEligibilityInput {
+  specId: string
+  specVersion?: number
+  datasetId: string
+  scope?: 'simulation' | 'real'
+  evidenceVersion?: string
+}
+
+export function evaluateEligibilityFromDataset(input: EvaluateEligibilityInput): EligibilityReport {
+  const specRow = getProcessModelSpecRepo().get(input.specId, input.specVersion)
+  if (!specRow) throw new AppError(404, 'SPEC_NOT_FOUND', `ProcessModelSpec ${input.specId} 不存在`)
+  const spec = parseSpecRow(specRow)
+  if (!spec) throw new AppError(404, 'SPEC_NOT_FOUND', `ProcessModelSpec ${input.specId} 不存在`)
+  const dataset = getAmlRuntime().repo.dataset.get(input.datasetId)
+  if (!dataset) throw new AppError(404, 'DATASET_NOT_FOUND', `数据集 ${input.datasetId} 不存在`)
+  if (dataset.lineId !== spec.lineId || dataset.recipeId !== spec.recipeId) {
+    throw new AppError(403, 'DATASET_LINEAGE_MISMATCH', '数据集与 ProcessModelSpec 的产线/配方谱系不一致')
+  }
+  const scope = input.scope ?? 'real'
+  // 作用域不能自报且必须与产线性质一致(双向):模拟线只能有 simulation 资格,
+  // 真实线只能有 real 资格;否则「real 报告」会被当成可授权真实线的最新资格。
+  const line = getDcwLineRepo().byId(spec.lineId)
+  if (!line) throw new AppError(404, 'LINE_NOT_FOUND', `产线 ${spec.lineId} 不存在`)
+  if (scope === 'simulation' && line.simulated !== true) {
+    throw new AppError(422, 'ELIGIBILITY_SCOPE_MISMATCH', '该产线不是模拟产线,不能生成 simulation 作用域资格')
+  }
+  if (scope === 'real' && line.simulated === true) {
+    throw new AppError(422, 'ELIGIBILITY_SCOPE_MISMATCH', '模拟产线的数据只能生成 simulation 作用域资格;real 作用域需要真实产线')
+  }
+  let ds
+  try {
+    ds = readDataset(dataset.path)
+  }
+  catch (err) {
+    throw new AppError(422, 'DATASET_READ_FAILED', `数据集读取失败(需要 manifest v2):${err instanceof Error ? err.message : String(err)}`)
+  }
+  if (ds.manifest.version !== 2) throw new AppError(422, 'DATASET_NOT_V2', '资格评估需要 manifest v2 数据集(由 Process Model 构建)')
+  const variables = spec.variables
+  const series: EligibilitySeries[] = []
+  for (const variable of variables) {
+    const idx = ds.allNodes.indexOf(variable.nodeId)
+    if (idx < 0) continue
+    const values: number[] = []
+    // 逐窗口取**同一时点对齐**的值(MV=历史末拍,CV=未来首拍),避免把历史+未来
+    // 拼接成一条序列后做滞后相关(会把延迟抹平/错位)。
+    for (let n = 0; n < ds.N; n++) {
+      if (variable.role === 'cv') {
+        const targetIndex = Math.max(0, ds.targetNodes.indexOf(variable.nodeId))
+        values.push(pvY(ds, n, 0, Math.min(targetIndex, ds.nTgt - 1)))
+      }
+      else {
+        values.push(pvX(ds, n, ds.H - 1, idx))
+      }
+    }
+    series.push({ variableId: variable.id, role: variable.role, values })
+  }
+  // 动作证据不从调用方读取:模拟产线视为 simulation_commanded;真实线在动作账本
+  // 接入前保持 unknown(fail-closed,不允许 Agent 自报 observed)。
+  const actionEvidence: ActionEvidence = scope === 'simulation' ? 'simulation_commanded' : 'unknown'
+  const report = evaluateEligibility({
+    spec, scope, conditionId: spec.conditions[0]?.id ?? '',
+    series,
+    actionEvidence,
+    sampleCount: dataset.rowCount,
+    runCount: dataset.runIds.length,
+    evidenceVersion: input.evidenceVersion ?? `ds:${dataset.id}:${dataset.sha256.slice(0, 12)}`,
+  })
+  // D20:资格行携带 dataset 谱系(dataset_id+hash),solve 按"模型的训练数据集"精确取用
+  const id = getEligibilityRepo().save(spec.id, spec.version, report, { datasetId: dataset.id, datasetHash: dataset.sha256 })
+  return { ...report, evidenceVersion: report.evidenceVersion || id }
+}