agentworkshop 0.7.66 → 0.7.71

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

@@ -0,0 +1,305 @@
+/**
+ * 资格评估(A2 / plan §3.3):
+ *   predictionEligible 与 optimizationEligible 分开,带 simulation/real 作用域。
+ *
+ * 硬规则:
+ *  - U 恒定、Y 波动再大也不能通过优化资格;
+ *  - MV 与扰动混杂 / 多输入共线 → 辨识不足,只能预测;
+ *  - 动作失败 / 仅 ACK / 时间未知 → 不能获得优化资格;
+ *  - 不足以"具体缺口 + 模拟试验建议"返回,绝不伪造激励样本。
+ */
+import type { DatabaseSync } from 'node:sqlite'
+import { AppError } from '../../../utils/errors'
+import type { EligibilityGap, EligibilityReport, ProcessModelSpec } from './contracts'
+import { getAmlRuntime } from '../aml/runtime'
+
+export type ActionEvidence = 'observed' | 'simulation_commanded' | 'ack_only' | 'failed' | 'unknown'
+
+export interface EligibilitySeries {
+  variableId: string
+  role: 'mv' | 'cv' | 'md' | 'feature'
+  values: number[]
+  states?: string[]
+}
+
+export interface EligibilityInput {
+  spec: ProcessModelSpec
+  scope: 'simulation' | 'real'
+  conditionId: string
+  series: EligibilitySeries[]
+  actionEvidence: ActionEvidence
+  /** 训练/评估产物指标(可选;缺省不评预测性能门) */
+  metrics?: { oneStepNrmse?: number, rolloutNrmse?: number, persistenceNrmse?: number }
+  sampleCount?: number
+  runCount?: number
+  evidenceVersion?: string
+}
+
+const MIN_SAMPLES = 50
+const MIN_DISTINCT_CHANGES = 3
+const MIN_VARIATION_RATIO = 0.02
+const MAX_COLLINEARITY = 0.95
+const MIN_DELAYED_CORR = 0.2
+
+function finite(values: number[]): number[] {
+  return values.filter(v => Number.isFinite(v))
+}
+
+function pearson(a: number[], b: number[]): number {
+  const n = Math.min(a.length, b.length)
+  if (n < 3) return 0
+  let ma = 0
+  let mb = 0
+  for (let i = 0; i < n; i++) {
+    ma += a[i]!
+    mb += b[i]!
+  }
+  ma /= n
+  mb /= n
+  let num = 0
+  let da = 0
+  let db = 0
+  for (let i = 0; i < n; i++) {
+    const x = a[i]! - ma
+    const y = b[i]! - mb
+    num += x * y
+    da += x * x
+    db += y * y
+  }
+  return da > 0 && db > 0 ? num / Math.sqrt(da * db) : 0
+}
+
+export function diff(values: number[]): number[] {
+  const out: number[] = []
+  for (let i = 1; i < values.length; i++) out.push(values[i]! - values[i - 1]!)
+  return out
+}
+
+/** 计划写明"变化后的可观测延迟响应":取 1..maxLag 步滞后互相关峰值。 */
+export function laggedCorrelation(input: number[], response: number[], maxLag: number): { lag: number, corr: number } {
+  const di = diff(input)
+  const dr = diff(response)
+  let best = { lag: 0, corr: 0 }
+  for (let lag = 1; lag <= maxLag; lag++) {
+    if (di.length <= lag + 2) break
+    const corr = pearson(di.slice(0, di.length - lag), dr.slice(lag))
+    if (Math.abs(corr) > Math.abs(best.corr)) best = { lag, corr }
+  }
+  return best
+}
+
+export function evaluateEligibility(input: EligibilityInput): EligibilityReport {
+  const gaps: EligibilityGap[] = []
+  const mv = input.series.filter(s => s.role === 'mv')
+  const cv = input.series.filter(s => s.role === 'cv')
+  const md = input.series.filter(s => s.role === 'md')
+  const metrics: Record<string, number | string | boolean | null> = {}
+  const evidenceVersion = input.evidenceVersion ?? `elig-${Date.now()}`
+
+  if (!mv.length) gaps.push({ code: 'NO_MV', message: '没有可调设定值(MV)变量;无法构成优化问题' })
+  if (!cv.length) gaps.push({ code: 'NO_CV', message: '没有质量目标(CV)变量;无法评价优化收益' })
+
+  const lengths = input.series.map(s => s.values.length)
+  const sampleCount = input.sampleCount ?? (lengths.length ? Math.min(...lengths) : 0)
+  metrics.sampleCount = sampleCount
+  if (sampleCount < MIN_SAMPLES) {
+    gaps.push({ code: 'INSUFFICIENT_SAMPLES', message: `有效样本 ${sampleCount} < ${MIN_SAMPLES}`, detail: { sampleCount } })
+  }
+  if (input.runCount != null && input.runCount < 1) {
+    gaps.push({ code: 'NO_RUNS', message: '没有已完结批次可用于训练/验证' })
+  }
+
+  // ---- MV 激励与覆盖 ----
+  const mvVariation: Record<string, number> = {}
+  const mvChanges: Record<string, number> = {}
+  let anyMvVaries = false
+  for (const series of mv) {
+    const vals = finite(series.values)
+    const range = input.spec.effectiveDomain.mv[series.variableId]
+    const span = range ? range.max - range.min : 0
+    const lo = vals.length ? Math.min(...vals) : 0
+    const hi = vals.length ? Math.max(...vals) : 0
+    const ratio = span > 0 ? (hi - lo) / span : 0
+    // 有效变化次数:|Δ| > max(绝对噪声下限, 1% 量程)
+    const threshold = Math.max(1e-9, span * 0.01)
+    const changes = diff(vals).filter(d => Math.abs(d) > threshold).length
+    mvVariation[series.variableId] = ratio
+    mvChanges[series.variableId] = changes
+    metrics[`mvVariation.${series.variableId}`] = Number(ratio.toFixed(6))
+    metrics[`mvChanges.${series.variableId}`] = changes
+    if (ratio >= MIN_VARIATION_RATIO && changes >= 1) anyMvVaries = true
+    if (ratio < MIN_VARIATION_RATIO) {
+      gaps.push({
+        code: 'MV_CONSTANT',
+        message: `MV ${series.variableId} 在窗口内几乎不变(覆盖 ${(ratio * 100).toFixed(1)}% 量程);恒定输入无法识别参数作用`,
+        detail: { variableId: series.variableId, variationRatio: ratio },
+      })
+    }
+    if (changes < MIN_DISTINCT_CHANGES) {
+      gaps.push({
+        code: 'MV_INSUFFICIENT_EXCITATION',
+        message: `MV ${series.variableId} 有效变化仅 ${changes} 次(< ${MIN_DISTINCT_CHANGES});建议做阶跃/多水平参数试验`,
+        detail: { variableId: series.variableId, changes },
+      })
+    }
+  }
+
+  // ---- 多输入共线 ----
+  let maxCollinearity = 0
+  for (let i = 0; i < mv.length; i++) {
+    for (let j = i + 1; j < mv.length; j++) {
+      const corr = Math.abs(pearson(diff(mv[i]!.values), diff(mv[j]!.values)))
+      maxCollinearity = Math.max(maxCollinearity, corr)
+      if (corr > MAX_COLLINEARITY) {
+        gaps.push({
+          code: 'INPUT_COLLINEAR',
+          message: `MV ${mv[i]!.variableId} 与 ${mv[j]!.variableId} 同步变化(|corr|=${corr.toFixed(3)});无法区分各自作用`,
+          detail: { a: mv[i]!.variableId, b: mv[j]!.variableId, corr },
+        })
+      }
+    }
+  }
+  metrics.maxMvCollinearity = Number(maxCollinearity.toFixed(6))
+
+  // ---- 扰动混杂 ----
+  let maxConfounding = 0
+  for (const mvSeries of mv) {
+    for (const mdSeries of md) {
+      const corr = Math.abs(pearson(diff(mvSeries.values), diff(mdSeries.values)))
+      maxConfounding = Math.max(maxConfounding, corr)
+      if (corr > 0.9) {
+        gaps.push({
+          code: 'CONFOUNDED_DISTURBANCE',
+          message: `MV ${mvSeries.variableId} 与扰动 ${mdSeries.variableId} 完全混杂(|corr|=${corr.toFixed(3)});不能把效果归因于调参`,
+          detail: { mv: mvSeries.variableId, md: mdSeries.variableId, corr },
+        })
+      }
+    }
+  }
+  metrics.maxDisturbanceConfounding = Number(maxConfounding.toFixed(6))
+
+  // ---- 延迟响应可观测 ----
+  const maxDelaySteps = Math.max(1, ...mv.map((s) => {
+    const variable = input.spec.variables.find(v => v.id === s.variableId)
+    return Math.ceil((variable?.delayMs ?? 0) / input.spec.timing.beatMs) + 3
+  }))
+  let bestResponse: { mv: string, cv: string, lag: number, corr: number } | null = null
+  for (const mvSeries of mv) {
+    for (const cvSeries of cv) {
+      const hit = laggedCorrelation(mvSeries.values, cvSeries.values, maxDelaySteps)
+      if (!bestResponse || Math.abs(hit.corr) > Math.abs(bestResponse.corr)) {
+        bestResponse = { mv: mvSeries.variableId, cv: cvSeries.variableId, lag: hit.lag, corr: hit.corr }
+      }
+    }
+  }
+  if (bestResponse) {
+    metrics.bestDelayedResponse = Number(bestResponse.corr.toFixed(6))
+    metrics.bestDelayedResponseLag = bestResponse.lag
+    metrics.bestDelayedResponsePair = `${bestResponse.mv}->${bestResponse.cv}`
+    // 延迟响应只对动态辨识是必要条件;静态响应面不需要"MV 变化后滞后可见",
+    // 用动态门槛会误杀 static_response 场景(A11 要求静态场景可资格评估/求解)。
+    if (input.spec.trainer.ref === 'linear_arx@1' && anyMvVaries && Math.abs(bestResponse.corr) < MIN_DELAYED_CORR) {
+      gaps.push({
+        code: 'NO_OBSERVABLE_DELAYED_RESPONSE',
+        message: `MV 变化后未见可观测的延迟响应(最大滞后相关 ${bestResponse.corr.toFixed(3)} < ${MIN_DELAYED_CORR})`,
+        detail: { ...bestResponse },
+      })
+    }
+  }
+
+  // ---- 动作证据 ----
+  metrics.actionEvidence = input.actionEvidence
+  if (input.actionEvidence === 'unknown') {
+    gaps.push({ code: 'ACTION_EVIDENCE_UNKNOWN', message: '历史输入缺少请求/生效/回读时间证据;不能作为优化资格样本(可继续用于预测训练)' })
+  }
+  else if (input.actionEvidence === 'ack_only') {
+    gaps.push({ code: 'ACTION_ACK_ONLY', message: '只有传输 ACK,没有生效/回读证据;不能宣称参数已生效' })
+  }
+  else if (input.actionEvidence === 'failed') {
+    gaps.push({ code: 'ACTION_FAILED', message: '关联动作失败;该窗口不能进入干预资格样本' })
+  }
+
+  // ---- 多步预测质量(有指标才评)----
+  if (input.metrics?.rolloutNrmse != null && input.metrics.persistenceNrmse != null && input.metrics.persistenceNrmse > 0) {
+    const improvement = 1 - input.metrics.rolloutNrmse / input.metrics.persistenceNrmse
+    metrics.rolloutImprovement = Number(improvement.toFixed(6))
+    if (improvement < 0.2) {
+      gaps.push({
+        code: 'POOR_MULTISTEP',
+        message: `多步 RMSE 相对持值基线仅改善 ${(improvement * 100).toFixed(1)}%(< 20%);模型不足以支撑优化`,
+        detail: { improvement },
+      })
+    }
+  }
+
+  const predictionEligible = !gaps.some(g => ['INSUFFICIENT_SAMPLES', 'NO_RUNS', 'NO_MV', 'NO_CV'].includes(g.code))
+  const optimizationEligible = predictionEligible && gaps.length === 0 && anyMvVaries
+
+  // 明确反例:U 恒定但 Y 大波动 → 只允许预测
+  if (!anyMvVaries && gaps.some(g => g.code === 'MV_CONSTANT')) {
+    gaps.push({ code: 'OPTIMIZATION_BLOCKED_BY_EXCITATION', message: '输入无有效激励(即使输出波动很大);优化资格不成立,建议先做模拟参数试验' })
+  }
+
+  return {
+    predictionEligible,
+    optimizationEligible,
+    scope: input.scope,
+    conditionId: input.conditionId,
+    evidenceVersion,
+    gaps,
+    metrics,
+    createdAt: new Date().toISOString(),
+  }
+}
+
+export function createEligibilityRepo(db: DatabaseSync) {
+  return {
+    /** D20:资格行显式携带 dataset 谱系(dataset_id+hash);latest 按谱系查询,不再裸取 spec 最新 */
+    save(specId: string, specVersion: number, report: EligibilityReport, lineage?: { datasetId: string, datasetHash: string }): string {
+      const id = `elig-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`
+      db.prepare(`INSERT INTO process_model_eligibility
+        (id, spec_id, spec_version, scope, condition_id, prediction_eligible, optimization_eligible, report_json, evidence_version, created_at, dataset_id, dataset_hash)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(id, specId, specVersion, report.scope, report.conditionId, report.predictionEligible ? 1 : 0,
+          report.optimizationEligible ? 1 : 0, JSON.stringify(report), report.evidenceVersion, report.createdAt,
+          lineage?.datasetId ?? '', lineage?.datasetHash ?? '')
+      return id
+    },
+    /** 谱系精确查询:datasetId 非空时只返回该数据集的资格报告(D20;旧数据无谱系 → 仅当 allowLegacy 才回退) */
+    latestForDataset(specId: string, datasetId: string): EligibilityReport | null {
+      const row = db.prepare(`SELECT report_json FROM process_model_eligibility
+        WHERE spec_id = ? AND dataset_id = ? ORDER BY created_at DESC LIMIT 1`).get(specId, datasetId) as { report_json: string } | undefined
+      return row ? JSON.parse(row.report_json) as EligibilityReport : null
+    },
+    latest(specId: string): EligibilityReport | null {
+      const row = db.prepare('SELECT report_json FROM process_model_eligibility WHERE spec_id = ? ORDER BY created_at DESC LIMIT 1').get(specId) as { report_json: string } | undefined
+      return row ? JSON.parse(row.report_json) as EligibilityReport : null
+    },
+    list(specId: string, limit = 20): EligibilityReport[] {
+      return (db.prepare('SELECT report_json FROM process_model_eligibility WHERE spec_id = ? ORDER BY created_at DESC LIMIT ?').all(specId, limit) as Array<{ report_json: string }>)
+        .map(r => JSON.parse(r.report_json) as EligibilityReport)
+    },
+    /** D20 撤销:删除某数据集的全部资格行(撤销传播到所有使用者) */
+    revokeForDataset(datasetId: string): number {
+      return Number(db.prepare('DELETE FROM process_model_eligibility WHERE dataset_id = ?').run(datasetId).changes)
+    },
+  }
+}
+
+export type EligibilityRepo = ReturnType<typeof createEligibilityRepo>
+
+const g = globalThis as typeof globalThis & { __processModelEligibilityRepo?: EligibilityRepo }
+
+export function getEligibilityRepo(): EligibilityRepo {
+  g.__processModelEligibilityRepo ??= createEligibilityRepo(getAmlRuntime().db)
+  return g.__processModelEligibilityRepo
+}
+
+export function assertOptimizationEligible(report: EligibilityReport | null): EligibilityReport {
+  if (!report) throw new AppError(409, 'ELIGIBILITY_MISSING', '该模型没有资格报告;先运行资格评估')
+  if (!report.optimizationEligible) {
+    const detail = report.gaps.map(g => g.message).join('; ')
+    throw new AppError(422, 'OPTIMIZATION_NOT_ELIGIBLE', `不具备优化资格:${detail}`)
+  }
+  return report
+}

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

@@ -0,0 +1,100 @@
+/**
+ * 模拟参数试验计划(G2.11 / C9 / A9):
+ *  - 只有 simulated=true 的产线可发起;真实线 → SIM_ONLY_VIOLATION;
+ *  - 计划只落 process_model_experiments;动作明细仍走既有 optimization_explorations/DCW 记录
+ *    (不制造第二套写设备账本)。
+ */
+import type { DatabaseSync } from 'node:sqlite'
+import { AppError } from '../../../utils/errors'
+import { getAmlRuntime } from '../aml/runtime'
+import { getDcwLineRepo } from '../dcw/dcw-line.repo'
+
+export interface ExperimentPlanInput {
+  lineId: string
+  specId?: string
+  /** MV → 水平序列(阶跃/多水平) */
+  levels: Record<string, number[]>
+  repeats?: number
+  settleMs?: number
+  observeMs?: number
+  randomizedOrder?: boolean
+  abortOnAlarm?: boolean
+  budget?: { maxRuns?: number, maxDurationMs?: number }
+  createdBy?: string
+}
+
+export interface ExperimentPlanRow {
+  id: string
+  lineId: string
+  planJson: string
+  status: string
+  budgetJson: string
+  createdBy: string
+  createdAt: string
+  updatedAt: string
+}
+
+export function assertSimulatedLine(lineId: string): { id: string, simSceneId?: string } {
+  const line = getDcwLineRepo().byId(lineId)
+  if (!line) throw new AppError(404, 'LINE_NOT_FOUND', `产线 ${lineId} 不存在`)
+  if (line.simulated !== true) {
+    throw new AppError(422, 'SIM_ONLY_VIOLATION', `产线「${line.name}」不是模拟产线(simulated=false);禁止在其上发起模拟参数试验(真实线首阶段仅提供建议)`)
+  }
+  return { id: line.id, simSceneId: line.simSceneId }
+}
+
+export function createExperimentPlan(input: ExperimentPlanInput): ExperimentPlanRow {
+  const line = assertSimulatedLine(input.lineId)
+  if (!Object.keys(input.levels).length) throw new AppError(422, 'EXPERIMENT_PLAN_INVALID', '至少需要 1 个 MV 的水平序列')
+  for (const [id, levels] of Object.entries(input.levels)) {
+    if (!Array.isArray(levels) || levels.length < 2) throw new AppError(422, 'EXPERIMENT_PLAN_INVALID', `MV ${id} 至少需要 2 个水平(阶跃/多水平)`)
+    if (levels.some(v => !Number.isFinite(v))) throw new AppError(422, 'EXPERIMENT_PLAN_INVALID', `MV ${id} 水平必须是有限数`)
+    if (new Set(levels).size !== levels.length) throw new AppError(422, 'EXPERIMENT_PLAN_INVALID', `MV ${id} 水平重复`)
+  }
+  const repeats = Math.max(1, Math.min(input.repeats ?? 1, 20))
+  const settleMs = Math.max(1000, input.settleMs ?? 60_000)
+  const observeMs = Math.max(1000, input.observeMs ?? 120_000)
+  const db = getAmlRuntime().db
+  const id = `pexp-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`
+  const now = new Date().toISOString()
+  const plan = {
+    version: 1,
+    lineId: input.lineId,
+    simSceneId: line.simSceneId ?? null,
+    specId: input.specId ?? null,
+    levels: input.levels,
+    repeats,
+    settleMs,
+    observeMs,
+    randomizedOrder: input.randomizedOrder !== false,
+    abortOnAlarm: input.abortOnAlarm !== false,
+    design: 'stepped_multi_level',
+    note: '动作明细写入既有 optimization_explorations/DCW 账本;本台账只保存计划与状态',
+  }
+  const budget = { maxRuns: input.budget?.maxRuns ?? 20, maxDurationMs: input.budget?.maxDurationMs ?? 4 * 3600_000 }
+  db.prepare(`INSERT INTO process_model_experiments (id, line_id, plan_json, status, budget_json, created_by, created_at, updated_at)
+    VALUES (?, ?, ?, 'planned', ?, ?, ?, ?)`)
+    .run(id, input.lineId, JSON.stringify(plan), JSON.stringify(budget), input.createdBy ?? '', now, now)
+  return this_get(db, id)!
+}
+
+function this_get(db: DatabaseSync, id: string): ExperimentPlanRow | undefined {
+  return db.prepare(`SELECT id, line_id AS lineId, plan_json AS planJson, status, budget_json AS budgetJson,
+    created_by AS createdBy, created_at AS createdAt, updated_at AS updatedAt
+    FROM process_model_experiments WHERE id = ?`).get(id) as unknown as ExperimentPlanRow | undefined
+}
+
+export function getExperimentPlan(id: string): ExperimentPlanRow | undefined {
+  return this_get(getAmlRuntime().db, id)
+}
+
+export function listExperimentPlans(lineId?: string, limit = 50): ExperimentPlanRow[] {
+  const db = getAmlRuntime().db
+  return lineId
+    ? db.prepare(`SELECT id, line_id AS lineId, plan_json AS planJson, status, budget_json AS budgetJson, created_by AS createdBy, created_at AS createdAt, updated_at AS updatedAt FROM process_model_experiments WHERE line_id = ? ORDER BY created_at DESC LIMIT ?`).all(lineId, limit) as unknown as ExperimentPlanRow[]
+    : db.prepare(`SELECT id, line_id AS lineId, plan_json AS planJson, status, budget_json AS budgetJson, created_by AS createdBy, created_at AS createdAt, updated_at AS updatedAt FROM process_model_experiments ORDER BY created_at DESC LIMIT ?`).all(limit) as unknown as ExperimentPlanRow[]
+}
+
+export function updateExperimentStatus(id: string, status: 'planned' | 'running' | 'done' | 'cancelled' | 'failed'): void {
+  getAmlRuntime().db.prepare('UPDATE process_model_experiments SET status = ?, updated_at = ? WHERE id = ?').run(status, new Date().toISOString(), id)
+}

package/server/services/workshop/process-model/spec.repo.ts

@@ -0,0 +1,127 @@
+/* eslint-disable @stylistic/max-statements-per-line */
+/**
+ * ProcessModelSpec 仓储:版本化、发布不可变、内容 hash 唯一。
+ *
+ * 发布语义(plan §3.1):
+ *  - draft 可改;published 行**禁止 UPDATE**,修改 = 新版本行;
+ *  - 同一 (line, product, recipe, recipeVersion, contentHash) 只登记一次(幂等)。
+ */
+import type { DatabaseSync } from 'node:sqlite'
+import { AppError } from '../../../utils/errors'
+import { canonicalJson, sha256 } from '../aml/twin/contracts'
+import type { ProcessModelSpec, ProcessModelStatus } from './contracts'
+import { PROCESS_MODEL_SCHEMA_VERSION } from './contracts'
+import { getAmlRuntime } from '../aml/runtime'
+
+export interface ProcessModelSpecRow {
+  id: string
+  version: number
+  lineId: string
+  productId: string
+  recipeId: string
+  recipeVersion: number
+  contentHash: string
+  specJson: string
+  status: ProcessModelStatus
+  ownerUserId: string
+  createdAt: string
+  updatedAt: string
+}
+
+const COLS = `id, version, line_id AS lineId, product_id AS productId, recipe_id AS recipeId,
+  recipe_version AS recipeVersion, content_hash AS contentHash, spec_json AS specJson, status,
+  owner_user_id AS ownerUserId, created_at AS createdAt, updated_at AS updatedAt`
+
+/** 内容 hash:稳定序列化(不含 created/status 等运行时字段),同配置必同 hash。 */
+export function specContentHash(spec: ProcessModelSpec): string {
+  const { createdAt: _createdAt, status: _status, ...stable } = spec as ProcessModelSpec & { status?: string }
+  return sha256(canonicalJson({ ...stable, schemaVersion: PROCESS_MODEL_SCHEMA_VERSION }))
+}
+
+export function createProcessModelSpecRepo(db: DatabaseSync) {
+  return {
+    insert(spec: ProcessModelSpec, opts: { ownerUserId?: string, status?: ProcessModelStatus } = {}): ProcessModelSpecRow {
+      const now = new Date().toISOString()
+      const contentHash = specContentHash(spec)
+      const existing = db.prepare(`SELECT ${COLS} FROM process_model_specs WHERE id = ? AND version = ?`).get(spec.id, spec.version) as Record<string, unknown> | undefined
+      if (existing) {
+        const row = existing as unknown as ProcessModelSpecRow
+        if (row.contentHash !== contentHash) {
+          throw new AppError(409, 'SPEC_VERSION_IMMUTABLE', `ProcessModelSpec ${spec.id}@${spec.version} 已存在且内容不同;修改必须产生新版本`)
+        }
+        return row
+      }
+      const dedup = db.prepare(`SELECT ${COLS} FROM process_model_specs WHERE line_id = ? AND product_id = ? AND recipe_id = ? AND recipe_version = ? AND content_hash = ?`)
+        .get(spec.lineId, spec.productId, spec.recipeId, spec.recipeVersion, contentHash) as Record<string, unknown> | undefined
+      if (dedup) return dedup as unknown as ProcessModelSpecRow
+      db.prepare(`INSERT INTO process_model_specs
+        (id, version, line_id, product_id, recipe_id, recipe_version, content_hash, spec_json, status, owner_user_id, created_at, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(spec.id, spec.version, spec.lineId, spec.productId, spec.recipeId, spec.recipeVersion, contentHash,
+          JSON.stringify(spec), opts.status ?? 'draft', opts.ownerUserId ?? '', now, now)
+      return this.get(spec.id, spec.version)!
+    },
+
+    get(id: string, version?: number): ProcessModelSpecRow | undefined {
+      const r = version == null
+        ? db.prepare(`SELECT ${COLS} FROM process_model_specs WHERE id = ? ORDER BY version DESC LIMIT 1`).get(id)
+        : db.prepare(`SELECT ${COLS} FROM process_model_specs WHERE id = ? AND version = ?`).get(id, version)
+      return r as unknown as ProcessModelSpecRow | undefined
+    },
+
+    list(filter: { lineId?: string, status?: string, limit?: number } = {}): ProcessModelSpecRow[] {
+      const where: string[] = []
+      const args: unknown[] = []
+      if (filter.lineId) { where.push('line_id = ?'); args.push(filter.lineId) }
+      if (filter.status) { where.push('status = ?'); args.push(filter.status) }
+      const sql = `SELECT ${COLS} FROM process_model_specs ${where.length ? `WHERE ${where.join(' AND ')}` : ''} ORDER BY created_at DESC LIMIT ?`
+      args.push(filter.limit ?? 100)
+      return db.prepare(sql).all(...(args as never[])) as unknown as ProcessModelSpecRow[]
+    },
+
+    nextVersion(id: string): number {
+      const r = db.prepare('SELECT MAX(version) AS v FROM process_model_specs WHERE id = ?').get(id) as { v: number | null }
+      return (r.v ?? 0) + 1
+    },
+
+    /** 发布:只允许 draft/validated;发布后不可再改(改 = 新版本)。 */
+    publish(id: string, version: number): ProcessModelSpecRow {
+      const row = this.get(id, version)
+      if (!row) throw new AppError(404, 'SPEC_NOT_FOUND', `ProcessModelSpec ${id}@${version} 不存在`)
+      if (row.status === 'published') return row
+      if (row.status === 'retired') throw new AppError(409, 'SPEC_RETIRED', `ProcessModelSpec ${id}@${version} 已退役,不能发布`)
+      const r = db.prepare(`UPDATE process_model_specs SET status = 'published', updated_at = ? WHERE id = ? AND version = ? AND status IN ('draft','validated')`)
+        .run(new Date().toISOString(), id, version)
+      if (Number(r.changes) === 0) throw new AppError(409, 'SPEC_RACE', 'ProcessModelSpec 状态已被并发修改')
+      return this.get(id, version)!
+    },
+
+    retire(id: string, version: number): ProcessModelSpecRow {
+      db.prepare(`UPDATE process_model_specs SET status = 'retired', updated_at = ? WHERE id = ? AND version = ?`).run(new Date().toISOString(), id, version)
+      const row = this.get(id, version)
+      if (!row) throw new AppError(404, 'SPEC_NOT_FOUND', `ProcessModelSpec ${id}@${version} 不存在`)
+      return row
+    },
+
+    removeDraft(id: string, version: number): boolean {
+      const row = this.get(id, version)
+      if (!row) return false
+      if (row.status !== 'draft') throw new AppError(409, 'SPEC_IMMUTABLE', '只有 draft 可删除;published/retired 保留谱系')
+      db.prepare('DELETE FROM process_model_specs WHERE id = ? AND version = ?').run(id, version)
+      return true
+    },
+  }
+}
+
+export type ProcessModelSpecRepo = ReturnType<typeof createProcessModelSpecRepo>
+
+const g = globalThis as typeof globalThis & { __processModelSpecRepo?: ProcessModelSpecRepo }
+
+export function getProcessModelSpecRepo(): ProcessModelSpecRepo {
+  g.__processModelSpecRepo ??= createProcessModelSpecRepo(getAmlRuntime().db)
+  return g.__processModelSpecRepo
+}
+
+export function parseSpecRow(row: ProcessModelSpecRow): ProcessModelSpec {
+  return JSON.parse(row.specJson) as ProcessModelSpec
+}