agentworkshop 0.7.70 → 0.8.0

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

@@ -0,0 +1,202 @@
+/**
+ * Runtime Context(plan §3.2 / G2.6):
+ *   getRuntimeContext(spec, asOf) → 真实 history + timestamps + dt + qualityMask
+ *   + 当前实际输入 + 状态估计 + availabilityWatermark。
+ *
+ * 铁律:历史不足明确拒绝;不复制单快照伪造历史(旧 model-backed-provider 的缺陷);
+ * watermark = max(ingested_at),全部为 NULL 时 = unknown(不得用于严格在线回放)。
+ */
+import { AppError } from '../../../utils/errors'
+import { toModel as sharedToModel } from '@/shared/units'
+import { getTsdb } from '../daq/storage'
+import type { TsdbPoint } from '../daq/storage/tsdb-port'
+import { getDcwRecipeRepo } from '../dcw/dcw-recipe.repo'
+import type { VariableMap, ProcessModelSpec } from './contracts'
+import { matchCondition } from './contracts'
+import { fetchNodeSeries } from '../aml/dataset-builder'
+import { getContextSegmentRepo, recipeContentHash } from './context-segments.repo'
+
+export interface ContextSnapshot {
+  lineId: string
+  productId: string
+  recipeId: string
+  recipeVersion: number
+  conditionId: string
+  capturedAt: string
+  /** 历史末点的事件时间(允许使用的最后观测) */
+  eventAsOf: number
+  /** 平台入库水位(= max(ingested_at));null = unknown */
+  availabilityWatermark: number | null
+  dtMs: number
+  variables: VariableMap[]
+  /** [H][F],按 spec.variables 顺序,已换算到模型单位 */
+  history: number[][]
+  timestamps: number[]
+  /** [H][F],state=ok 且值有限 */
+  qualityMask: boolean[][]
+  /** 当前 MV 实际值(模型单位) */
+  currentInputs: Record<string, number>
+  /** 最近一次 CV 观测(模型单位) */
+  currentOutputs: Record<string, number>
+  /** 数据来源(由资格作用域决定;缺省 unassessed) */
+  evidenceSource: 'simulation' | 'real' | 'unassessed'
+}
+
+function toModel(value: number, variable: VariableMap): number {
+  // D23 唯一换算边界:spec parse 已强制 scale/offset 有限(scale≠0);此处缺失/非法 = 契约破坏,fail-closed
+  return sharedToModel(value, { scale: variable.scale as number, offset: variable.offset as number }, `变量 ${variable.id}`)
+}
+
+/** 从点列取最后一个 ≤ t 的值;过期/非 ok 一律视为缺失(不拿坏点当历史)。 */
+function valueAt(points: TsdbPoint[], t: number, maxAgeMs: number): { value: number, state: string } | null {
+  let best: TsdbPoint | null = null
+  for (const p of points) {
+    if (p.at <= t && (!best || p.at > best.at)) best = p
+  }
+  if (!best || best.value === undefined || !Number.isFinite(best.value)) return null
+  if (t - best.at > maxAgeMs) return null
+  return { value: best.value, state: best.state ?? 'unknown' }
+}
+
+export async function getRuntimeContext(spec: ProcessModelSpec, asOfMs?: number): Promise<ContextSnapshot> {
+  const asOf = asOfMs ?? Date.now()
+  const beat = spec.timing.beatMs
+  const H = spec.timing.historySteps
+  const maxDelay = Math.max(0, ...spec.variables.filter(v => v.role === 'mv').map(v => v.delayMs ?? 0))
+  const fromMs = asOf - (H * beat + maxDelay + beat * 5)
+  const tsdb = getTsdb()
+  const pointsByVariable = new Map<string, TsdbPoint[]>()
+  for (const variable of spec.variables) {
+    const points = await fetchNodeSeries(tsdb, variable.nodeId, {
+      lineId: spec.lineId, productId: spec.productId, recipeId: spec.recipeId,
+      fromMs, toMs: asOf,
+    })
+    if (!points.length) {
+      throw new AppError(422, 'CONTEXT_INSUFFICIENT', `变量 ${variable.id}(节点 ${variable.nodeId})在 ${new Date(fromMs).toISOString()} ~ ${new Date(asOf).toISOString()} 无样本`)
+    }
+    pointsByVariable.set(variable.id, points)
+  }
+
+  const history: number[][] = []
+  const timestamps: number[] = []
+  const qualityMask: boolean[][] = []
+  const watermarks: number[] = []
+  let anyIngest = false
+  for (let i = H - 1; i >= 0; i--) {
+    const t = asOf - i * beat
+    const row: number[] = []
+    const mask: boolean[] = []
+    for (const variable of spec.variables) {
+      const points = pointsByVariable.get(variable.id) ?? []
+      const hit = valueAt(points, t, beat * 1.5)
+      if (hit && hit.state === 'ok') {
+        row.push(toModel(hit.value, variable))
+        mask.push(true)
+        const ingested = points.filter(p => p.at === t && p.ingestedAt != null).map(p => p.ingestedAt as number)
+        if (ingested.length) {
+          anyIngest = true
+          watermarks.push(Math.max(...ingested))
+        }
+      }
+      else {
+        // 坏点/过期点不进入历史(否则常量持值会伪装成观测)
+        row.push(Number.NaN)
+        mask.push(false)
+      }
+    }
+    history.push(row)
+    timestamps.push(t)
+    qualityMask.push(mask)
+  }
+
+  // 历史末行必须全部可观测(MV/CV 都不允许 NaN);否则明确拒绝,不用持值/复制伪造
+  const lastRow = history[history.length - 1] ?? []
+  const missing = spec.variables.filter((v, idx) => !Number.isFinite(lastRow[idx]))
+  if (missing.length) {
+    throw new AppError(422, 'CONTEXT_INSUFFICIENT', `历史末点缺少可观测变量:${missing.map(v => v.id).join(', ')}`)
+  }
+
+  const conditionId = requireCondition(spec, asOf)
+  const currentInputs: Record<string, number> = {}
+  const currentOutputs: Record<string, number> = {}
+  for (let idx = 0; idx < spec.variables.length; idx++) {
+    const variable = spec.variables[idx]!
+    const value = lastRow[idx]!
+    if (variable.role === 'mv') {
+      const domain = spec.effectiveDomain.mv[variable.id]
+      if (domain && (value < domain.min - 1e-9 || value > domain.max + 1e-9)) {
+        throw new AppError(422, 'CONTEXT_OOD', `当前 MV ${variable.id}=${value} 超出模型有效域[${domain.min}, ${domain.max}];拒绝用域外状态求解`)
+      }
+      currentInputs[variable.id] = value
+    }
+    if (variable.role === 'cv') {
+      const domain = spec.effectiveDomain.cv?.[variable.id]
+      if (domain && (value < domain.min - 1e-9 || value > domain.max + 1e-9)) {
+        throw new AppError(422, 'CONTEXT_OOD', `当前 CV ${variable.id}=${value} 超出模型有效域[${domain.min}, ${domain.max}]`)
+      }
+      currentOutputs[variable.id] = value
+    }
+  }
+
+  return {
+    lineId: spec.lineId,
+    productId: spec.productId,
+    recipeId: spec.recipeId,
+    recipeVersion: spec.recipeVersion,
+    conditionId,
+    capturedAt: new Date().toISOString(),
+    eventAsOf: asOf,
+    availabilityWatermark: anyIngest ? Math.max(...watermarks) : null,
+    dtMs: beat,
+    variables: spec.variables,
+    history,
+    timestamps,
+    qualityMask,
+    currentInputs,
+    currentOutputs,
+    evidenceSource: 'unassessed',
+  }
+}
+
+function requireCondition(spec: ProcessModelSpec, _asOf: number): string {
+  // 运行时用声明身份 exactly-one 命中(exactly-one 由 matchCondition 强制);
+  // 批次谱系段版本不一致 → 旧计划失效。
+  const segment = getContextSegmentRepo().at(spec.lineId, _asOf)
+  if (segment && segment.confirmed === 1) {
+    if (segment.recipeId !== spec.recipeId) {
+      throw new AppError(409, 'CONDITION_MISMATCH', `运行批次已切换到配方 ${segment.recipeId},与模型规格 ${spec.recipeId} 不一致;旧计划失效`)
+    }
+    if (segment.recipeVersion !== 0 && segment.recipeVersion !== spec.recipeVersion) {
+      throw new AppError(409, 'CONDITION_MISMATCH', `运行批次配方版本 v${segment.recipeVersion} 与模型规格 v${spec.recipeVersion} 不一致;旧计划失效`)
+    }
+  }
+  return matchCondition(spec.conditions, {
+    lineId: spec.lineId, productId: spec.productId, recipeId: spec.recipeId, recipeVersion: spec.recipeVersion,
+  })
+}
+
+/** 运行批次开段(线开跑时调用):冻结配方内容 hash 与版本。 */
+export function openContextSegment(run: { id: string, lineId: string, recipeId: string, startedAt: string, recipeVersion?: number, paramsSnapshot?: unknown }): void {
+  const recipe = getDcwRecipeRepo().byId(run.recipeId)
+  const version = run.recipeVersion ?? recipe?.version ?? 0
+  const hash = recipe
+    ? recipeContentHash(recipe, run.paramsSnapshot)
+    : recipeContentHash({ id: run.recipeId, version })
+  getContextSegmentRepo().insert({
+    lineId: run.lineId,
+    runId: run.id,
+    fromTs: Date.parse(run.startedAt),
+    toTs: null,
+    recipeId: run.recipeId,
+    recipeVersion: version,
+    recipeContentHash: hash,
+    conditionId: '',
+    source: 'line_run',
+    confirmed: true,
+  })
+}
+
+/** 运行批次关段(线停止时调用)。 */
+export function closeContextSegment(runId: string, atMs?: number): void {
+  getContextSegmentRepo().close(runId, atMs ?? Date.now())
+}

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: [] },
+  }
+}