agentworkshop 0.7.70 → 0.8.0

package/server/services/workshop/aml/gates.ts

@@ -1,121 +1,163 @@
-/**
- * AML 评测门(平台判定,不采信 Agent 自报;阈值来自 amlSettings().gates,live 可调)。
- *  - mpc_surrogate:G1 单步 NRMSE / G2 多步滚动 NRMSE / G3 泛化差 / G4 数据覆盖 / G5 工件完整
- *  - quality_predict:G1/G3/G4/G5(无滚动语义)
- */
-import { existsSync, statSync } from 'node:fs'
-import { join } from 'node:path'
-import { amlSettings } from '../settings'
-import type { AmlManifest } from './dataset-builder'
-import type { AmlDatasetRow } from './aml.repo'
-
-export interface PlatformMetrics {
-  oneStepVal?: { windows: number, nrmse: number } | null
-  oneStepTest?: { windows: number, nrmse: number } | null
-  rolloutTest?: { windows: number, nrmse: number, horizon: number } | null
-}
-
-export interface GateCheck {
-  id: string
-  name: string
-  value: number | null
-  threshold: number | null
-  pass: boolean
-  detail: string
-}
-
-export interface GateReport {
-  passed: boolean
-  checks: GateCheck[]
-}
-
-export function evaluateGates(
-  purpose: string,
-  dataset: Pick<AmlDatasetRow, 'rowCount' | 'runIds'>,
-  manifest: Pick<AmlManifest, 'split'>,
-  metrics: PlatformMetrics | undefined,
-  artifactsDir: string,
-): GateReport {
-  const g = amlSettings().gates
-  const checks: GateCheck[] = []
-
-  const testNrmse = metrics?.oneStepTest?.nrmse
-  checks.push({
-    id: 'G1',
-    name: '单步精度(测试集 NRMSE)',
-    value: numOrNull(testNrmse),
-    threshold: g.nrmse,
-    pass: testNrmse !== undefined && testNrmse !== null && testNrmse <= g.nrmse,
-    detail: testNrmse == null ? 'metrics 缺少 platform.oneStepTest(评估器未产出)' : `实测 ${testNrmse.toFixed(4)} / 上限 ${g.nrmse}`,
-  })
-
-  if (purpose === 'mpc_surrogate') {
-    const roll = metrics?.rolloutTest?.nrmse
-    checks.push({
-      id: 'G2',
-      name: `多步滚动精度(horizon=${metrics?.rolloutTest?.horizon ?? '?'} NRMSE)`,
-      value: numOrNull(roll),
-      threshold: g.rolloutNrmse,
-      pass: roll !== undefined && roll !== null && roll <= g.rolloutNrmse,
-      detail: roll == null ? 'metrics 缺少 platform.rolloutTest' : `实测 ${roll.toFixed(4)} / 上限 ${g.rolloutNrmse}`,
-    })
-  }
-
-  const val = metrics?.oneStepVal?.nrmse
-  // mpc_surrogate 下 G3 恒入列:val 缺失/切分为空一律不通过(防 valRatio:0 静默绕过泛化门)
-  if (purpose === 'mpc_surrogate' || (val != null && testNrmse != null)) {
-    const gap = val != null && testNrmse != null && val > 1e-9
-      ? Math.abs(testNrmse - val) / Math.abs(val)
-      : null
-    checks.push({
-      id: 'G3',
-      name: '泛化一致(|test−val|/val)',
-      value: numOrNull(gap),
-      threshold: g.valTestGap,
-      pass: gap != null && gap <= g.valTestGap,
-      detail: gap == null
-        ? (manifest.split.val === 0 ? 'val 切分为空(批次数不足或 valRatio=0,无法校验泛化)' : 'metrics 缺少 val 指标')
-        : `实测 ${(gap * 100).toFixed(1)}% / 上限 ${(g.valTestGap * 100).toFixed(0)}%`,
-    })
-  }
-
-  const runsOk = dataset.runIds.length >= g.minRuns
-  checks.push({
-    id: 'G4',
-    name: '数据覆盖(行数/批次数)',
-    value: dataset.runIds.length,
-    threshold: g.minRuns,
-    pass: dataset.rowCount >= g.minRows && runsOk,
-    detail: `${dataset.rowCount} 行(≥${g.minRows});${dataset.runIds.length} 批次(≥${g.minRuns})`,
-  })
-
-  // G5:契约工件存在(模型文件或 STUB 标记);加载验证由注册时 predictor 深检兜底
-  const onnxPath = join(artifactsDir, 'model.onnx')
-  const stubPath = join(artifactsDir, 'STUB')
-  const hasOnnx = existsSync(onnxPath)
-  let g5pass = false
-  let g5detail: string
-  if (hasOnnx) {
-    let size = 0
-    try {
-      size = statSync(onnxPath).size
-    }
-    catch { /* 探测失败按缺失 */ }
-    g5pass = size > 0
-    g5detail = g5pass ? `model.onnx(${(size / 1024).toFixed(1)}KB)` : 'model.onnx 为空文件'
-  }
-  else if (existsSync(stubPath)) {
-    g5pass = true
-    g5detail = 'STUB 存根工件(无真实模型,不可用于预测服务)'
-  }
-  else {
-    g5detail = 'artifacts/model.onnx 缺失'
-  }
-  checks.push({ id: 'G5', name: '工件完整(契约 ONNX)', value: null, threshold: null, pass: g5pass, detail: g5detail })
-
-  return { passed: checks.every(c => c.pass), checks }
-}
-
-function numOrNull(v: unknown): number | null {
-  return typeof v === 'number' && Number.isFinite(v) ? v : null
-}
+/**
+ * AML 评测门(平台判定,不采信 Agent 自报;阈值来自 amlSettings().gates,live 可调)。
+ *  - mpc_surrogate:G1 单步 NRMSE / G2 多步滚动 NRMSE / G3 泛化差 / G4 数据覆盖 / G5 工件完整
+ *  - quality_predict:G1/G3/G4/G5(无滚动语义)
+ */
+import { existsSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { amlSettings } from '../settings'
+import type { AmlManifest } from './dataset-builder'
+import type { AmlDatasetRow } from './aml.repo'
+
+export interface PlatformMetrics {
+  oneStepVal?: { windows: number, nrmse: number } | null
+  oneStepTest?: { windows: number, nrmse: number } | null
+  rolloutTest?: { windows: number, nrmse: number, horizon: number } | null
+  /** 新工件类型分派(G1.2):linear_state_space@1 / static_response@1 / onnx_one_step@1 / hybrid_manifest@1 */
+  artifactKind?: string
+  modelKind?: string
+  /** 多步相对持值基线改善(A3:新模型 ≥20%) */
+  rolloutImprovement?: number
+  persistenceNrmse?: number
+}
+
+export interface GateCheck {
+  id: string
+  name: string
+  value: number | null
+  threshold: number | null
+  pass: boolean
+  detail: string
+}
+
+export interface GateReport {
+  passed: boolean
+  checks: GateCheck[]
+}
+
+export function evaluateGates(
+  purpose: string,
+  dataset: Pick<AmlDatasetRow, 'rowCount' | 'runIds'>,
+  manifest: Pick<AmlManifest, 'split'>,
+  metrics: PlatformMetrics | undefined,
+  artifactsDir: string,
+): GateReport {
+  const g = amlSettings().gates
+  const checks: GateCheck[] = []
+  const artifactKind = metrics?.artifactKind ?? (existsSync(join(artifactsDir, 'model.json')) ? 'linear_state_space@1' : 'onnx_one_step@1')
+  const isStatic = artifactKind === 'static_response@1'
+  const isLinear = artifactKind === 'linear_state_space@1'
+
+  const testNrmse = metrics?.oneStepTest?.nrmse
+  const hasTest = manifest.split.test > 0 && (metrics?.oneStepTest?.windows ?? 0) > 0 && numOrNull(testNrmse) != null && testNrmse! >= 0
+  checks.push({
+    id: 'G1',
+    name: '单步精度(测试集 NRMSE)',
+    value: numOrNull(testNrmse),
+    threshold: g.nrmse,
+    pass: hasTest && testNrmse! <= g.nrmse,
+    detail: !hasTest ? '缺少非空独立测试集或有效 platform.oneStepTest 指标' : `实测 ${testNrmse!.toFixed(4)} / 上限 ${g.nrmse}(${artifactKind})`,
+  })
+
+  if (isLinear) {
+    // 新模型:多步相对持值基线改善(A3 ≥20%),而不是旧 NN 的绝对 0.25 阈值。
+    const improvement = metrics?.rolloutImprovement
+    const roll = metrics?.rolloutTest?.nrmse
+    checks.push({
+      id: 'G2',
+      name: `多步相对持值基线改善(horizon=${metrics?.rolloutTest?.horizon ?? '?'})`,
+      value: numOrNull(improvement),
+      threshold: 0.2,
+      pass: hasTest && (metrics?.rolloutTest?.windows ?? 0) > 0 && numOrNull(roll) != null && roll! >= 0 && numOrNull(improvement) != null && improvement! >= 0.2,
+      detail: improvement == null
+        ? 'metrics 缺少 rolloutImprovement'
+        : `改善 ${(improvement * 100).toFixed(1)}% / 下限 20%(rollout=${roll?.toFixed(4) ?? '?'}, 持值=${metrics?.persistenceNrmse?.toFixed(4) ?? '?'})`,
+    })
+  }
+  else if (purpose === 'mpc_surrogate' && !isStatic) {
+    const roll = metrics?.rolloutTest?.nrmse
+    checks.push({
+      id: 'G2',
+      name: `多步滚动精度(horizon=${metrics?.rolloutTest?.horizon ?? '?'} NRMSE)`,
+      value: numOrNull(roll),
+      threshold: g.rolloutNrmse,
+      pass: hasTest && (metrics?.rolloutTest?.windows ?? 0) > 0 && numOrNull(roll) != null && roll! >= 0 && roll! <= g.rolloutNrmse,
+      detail: roll == null ? 'metrics 缺少 platform.rolloutTest' : `实测 ${roll.toFixed(4)} / 上限 ${g.rolloutNrmse}`,
+    })
+  }
+
+  const val = metrics?.oneStepVal?.nrmse
+  // 静态模型按"独立稳定段/批次"评估留出误差,不做 val/test 泛化差(计划 §3.5)
+  if (!isStatic && (purpose === 'mpc_surrogate' || (val != null && testNrmse != null))) {
+    const gap = hasTest && manifest.split.val > 0 && (metrics?.oneStepVal?.windows ?? 0) > 0 && val != null && numOrNull(val) != null && val >= 0 && testNrmse != null
+      ? Math.abs(testNrmse - val) / Math.max(1e-9, Math.abs(val))
+      : null
+    checks.push({
+      id: 'G3',
+      name: '泛化一致(|test−val|/val)',
+      value: numOrNull(gap),
+      threshold: g.valTestGap,
+      pass: gap != null && gap <= g.valTestGap,
+      detail: gap == null
+        ? (manifest.split.val === 0 ? 'val 切分为空(批次数不足或 valRatio=0,无法校验泛化)' : 'metrics 缺少 val 指标')
+        : `实测 ${(gap * 100).toFixed(1)}% / 上限 ${(g.valTestGap * 100).toFixed(0)}%`,
+    })
+  }
+
+  // G4:数据覆盖。单长 run 用合法隔离时间切分时,以 train/val/test 三段非空替代批次门
+  // (计划 §3.5:不能把重叠窗口当独立试验,也不能用旧 minRuns 误杀合法切分)。
+  const isolatedSplit = (isLinear || isStatic) && manifest.split.train > 0 && manifest.split.val > 0 && manifest.split.test > 0
+  const runsOk = dataset.runIds.length >= g.minRuns || isolatedSplit
+  checks.push({
+    id: 'G4',
+    name: '数据覆盖(行数/批次数)',
+    value: dataset.runIds.length,
+    threshold: g.minRuns,
+    pass: dataset.rowCount >= g.minRows && runsOk,
+    detail: `${dataset.rowCount} 行(≥${g.minRows});${dataset.runIds.length} 批次(≥${g.minRuns}${isolatedSplit ? ',单长 run 隔离切分已生效' : ''})`,
+  })
+
+  // G5:契约工件存在(按 artifactKind 分派;加载验证由注册时深检兜底)
+  const onnxPath = join(artifactsDir, 'model.onnx')
+  const jsonPath = join(artifactsDir, 'model.json')
+  const stubPath = join(artifactsDir, 'STUB')
+  let g5pass = false
+  let g5detail: string
+  if (isLinear || isStatic) {
+    if (existsSync(jsonPath)) {
+      let size = 0
+      try {
+        size = statSync(jsonPath).size
+      }
+      catch { /* 探测失败按缺失 */ }
+      g5pass = size > 0
+      g5detail = `model.json(${(size / 1024).toFixed(1)}KB,${artifactKind})`
+    }
+    else {
+      g5detail = `artifacts/model.json 缺失(${artifactKind})`
+    }
+  }
+  else if (existsSync(onnxPath)) {
+    let size = 0
+    try {
+      size = statSync(onnxPath).size
+    }
+    catch { /* 探测失败按缺失 */ }
+    g5pass = size > 0
+    g5detail = g5pass ? `model.onnx(${(size / 1024).toFixed(1)}KB)` : 'model.onnx 为空文件'
+  }
+  else if (existsSync(stubPath)) {
+    g5pass = true
+    g5detail = 'STUB 存根工件(无真实模型,不可用于预测服务)'
+  }
+  else {
+    g5detail = 'artifacts/model.onnx 缺失'
+  }
+  checks.push({ id: 'G5', name: '工件完整(按工件类型)', value: null, threshold: null, pass: g5pass, detail: g5detail })
+
+  return { passed: checks.every(c => c.pass), checks }
+}
+
+function numOrNull(v: unknown): number | null {
+  return typeof v === 'number' && Number.isFinite(v) ? v : null
+}

package/server/services/workshop/aml/job-orchestrator/stages.ts

@@ -68,30 +68,51 @@ export function concludeJob(run: RunningJob, artifactsDir: string): void {
   const gates = evaluateGates(run.row.purpose, dataset, manifest, metrics, artifactsDir)
   const gatesJson = JSON.stringify(gates)
   const metricsJson = JSON.stringify(metrics ?? {})
-  rt.repo.job.finish(run.row.id, gates.passed ? 'done' : 'failed', metricsJson, gatesJson, artifactsDir, new Date().toISOString())
+  // 实验行先落(谱系在,作业状态随后定)
+  let registeredModelId: string | undefined
+  let registrationError: string | null = null
   if (!gates.passed) {
+    // 直接用 fail():它同时写 status + error(先 finish(failed) 会让 error 写不进去)
     rt.repo.job.fail(run.row.id, 'failed', `评测门未通过:${gates.checks.filter(c => !c.pass).map(c => `${c.id} ${c.detail}`).join('; ')}`, new Date().toISOString())
-    // 门禁未过=实验记录 gates_failed(非作业错误语义,但作业 fail 承载原因)
-  }
-  // 实验与模型登记(实验 id = job id 首跑对应;重试复用)
-  let registeredModelId: string | undefined
-  try {
-    registeredModelId = registerModelFromJob(run.row.id, gates, metricsJson).modelId
   }
-  catch (err) {
-    log.warn(`[aml-job] ${run.row.id} 模型登记失败:${err instanceof Error ? err.message : String(err)}`)
+  else {
+    // C11 两阶段收口:工件校验/rename(文件)→ 单事务 INSERT model + UPDATE job done/model_id。
+    // 注册失败 = 明确失败(可幂等重试),绝不出现"训练成功、模型不存在"。
+    try {
+      rt.db.exec('BEGIN')
+      try {
+        registeredModelId = registerModelFromJob(run.row.id, gates, metricsJson).modelId
+        if (!registeredModelId) throw new Error('注册未返回 modelId')
+        const ok = rt.repo.job.finish(run.row.id, 'done', metricsJson, gatesJson, artifactsDir, new Date().toISOString(), registeredModelId)
+        if (!ok) throw new Error('作业终态写入失败(状态竞争或已终态)')
+        rt.db.exec('COMMIT')
+      }
+      catch (err) {
+        try {
+          rt.db.exec('ROLLBACK')
+        }
+        catch { /* 事务已终结 */ }
+        throw err
+      }
+    }
+    catch (err) {
+      registrationError = err instanceof Error ? err.message : String(err)
+      log.error(`[aml-job] ${run.row.id} 工件注册失败:${registrationError}`)
+      rt.repo.job.fail(run.row.id, 'failed', `工件注册失败(可重试):${registrationError}`, new Date().toISOString())
+    }
   }
+  const succeeded = Boolean(registeredModelId) && !registrationError
   // 建模任务收口:该作业若由 aml_training_plans 派生,回写 plan 终态与模型 id。
   void import('../twin/training-plans')
-    .then(m => m.settleTrainingPlanByJob(run.row.id, gates.passed ? 'done' : 'failed', registeredModelId, gates.checks.filter(c => !c.pass).map(c => `${c.id} ${c.detail}`).join('; ')))
+    .then(m => m.settleTrainingPlanByJob(run.row.id, succeeded ? 'done' : 'failed', registeredModelId, gates.checks.filter(c => !c.pass).map(c => `${c.id} ${c.detail}`).join('; ') || registrationError || ''))
     .catch(() => { /* plan 模块不可用不阻断作业收口 */ })
   // 持续校准 worker 收口:该作业若由 twin_update_runs 派生,更新其终态(成功/失败)。
   // 动态 import 规避 stages ↔ calibration-worker ↔ job-orchestrator 的循环装载。
   void import('../twin/calibration-worker')
     .then(m => m.markTwinUpdateRunFinished(
       run.row.id,
-      gates.passed,
-      gates.checks.filter(c => !c.pass).map(c => `${c.id} ${c.detail}`).join('; '),
+      succeeded,
+      gates.checks.filter(c => !c.pass).map(c => `${c.id} ${c.detail}`).join('; ') || registrationError || '',
     ))
     .catch(() => { /* worker 不可用不阻断作业收口 */ })
   const datasetFresh = rt.repo.dataset.get(run.row.datasetId)
@@ -100,7 +121,7 @@ export function concludeJob(run: RunningJob, artifactsDir: string): void {
   recordOps({
     actor: run.row.agentId || 'aml', actorName: run.row.agentId || 'AML', actorKind,
     action: 'aml.job.finish', kind: 'system',
-    summary: `作业 ${run.row.id} 结束:门禁${gates.passed ? '全部通过' : '未通过'}`,
+    summary: `作业 ${run.row.id} 结束:${succeeded ? '门禁通过且模型已登记' : gates.passed ? `工件注册失败(${registrationError ?? 'unknown'})` : '门禁未通过'}`,
     targetKind: 'aml_job', targetId: run.row.id,
     lineId: datasetFresh?.lineId, productId: datasetFresh?.productId, recipeId: datasetFresh?.recipeId,
   })
@@ -119,10 +140,10 @@ export function concludeJob(run: RunningJob, artifactsDir: string): void {
       agentId: run.row.agentId,
       ...(run.row.channelId ? { channelId: run.row.channelId } : {}),
       ...(run.row.taskId ? { taskId: run.row.taskId } : {}),
-      ok: gates.passed,
+      ok: succeeded,
       title: `训练作业 ${run.row.id}`,
       summary: [
-        `门禁${gates.passed ? '全部通过,模型已登记可用' : '未通过'}。`,
+        gates.passed ? (succeeded ? '门禁全部通过,模型已登记可用。' : `门禁通过但工件注册失败:${registrationError ?? '未知原因'}(可重试)。`) : '门禁未通过。',
         metricsLine,
         registeredModelId ? `model_id=${registeredModelId}` : '',
         gates.passed ? '' : (failedChecks ? `未过项:${failedChecks}` : run.row.error ? `错误:${run.row.error.slice(0, 200)}` : ''),

package/server/services/workshop/aml/job-orchestrator/start-job.ts

@@ -15,6 +15,7 @@ import { join } from 'node:path'
 import { runPython } from './process'
 import { state } from './shared'
 import { wsStage } from './broadcast'
+import { isTrainerRef, type ProcessModelSpec } from '../../process-model/contracts'
 
 const log = createLogger('aml.job')
 
@@ -37,6 +38,49 @@ export async function startJob(row: AmlJobRow): Promise<void> {
   const artifacts = join(jobDir, 'artifacts')
   mkdirSync(workspace, { recursive: true })
   mkdirSync(artifacts, { recursive: true })
+  const earlyBudget = safeParse(row.budget) as Record<string, unknown>
+
+  // ===== 内置训练器分支(G2.8):配置驱动、无用户 Python 代码 =====
+  // 训练在 TS 侧完成(线性辨识/响应面),不要求 model.onnx,也不走 aml_eval.py;
+  // 评估/gate/注册仍走平台权威链(concludeJob → evaluateGates → registerModelFromJob)。
+  if (isTrainerRef(earlyBudget.trainerRef)) {
+    const run: RunningJob = {
+      row, jobDir, child: null, startedAt: Date.now(), lastProtocolAt: Date.now(), lastWsAt: 0,
+      logLines: [], protocolBadLines: 0, killed: false,
+    }
+    st.running.set(row.id, run)
+    try {
+      if (process.env.AML_STUB === '1') {
+        await runStub(run, artifacts)
+        return
+      }
+      rt.repo.job.setState(row.id, 'training', 'train', 10)
+      wsStage(row, 'train')
+      const spec = earlyBudget.processModelSpec as ProcessModelSpec | undefined
+      if (!spec || typeof spec !== 'object') {
+        rt.repo.job.fail(row.id, 'failed', '内置训练器作业缺少 processModelSpec(提交契约缺失,永久错误)', new Date().toISOString())
+        finishRun(run)
+        return
+      }
+      const { runBuiltinTraining } = await import('../../process-model/trainers')
+      const result = runBuiltinTraining(earlyBudget.trainerRef, { datasetDir: dataset.path, spec, jobDir })
+      if (run.killed) return
+      rt.repo.job.setState(row.id, 'evaluating', 'evaluate', 80)
+      wsStage(row, 'evaluate')
+      log.info(`[aml-job] ${row.id} 内置训练器 ${earlyBudget.trainerRef} 完成(${result.artifactKind}),进入平台评估`)
+      concludeJob(run, artifacts)
+    }
+    catch (err) {
+      if (!run.killed) {
+        const msg = err instanceof Error ? err.message : String(err)
+        rt.repo.job.fail(row.id, 'failed', `内置训练失败:${msg}(永久错误不重试)`, new Date().toISOString())
+        experimentFail(run, msg)
+        finishRun(run)
+      }
+    }
+    return
+  }
+
   let trainFile = existsSync(join(workspace, 'train.py')) ? 'train.py' : null
   if (!trainFile) {
     // REST 内联代码路径:预算袋携带 inlineCode 时落盘(≤500KB,提交入口已限)

package/server/services/workshop/aml/job-orchestrator/submit.ts

@@ -46,6 +46,10 @@ export interface SubmitJobInput {
   modelName?: string
   /** 建模意图描述(注册时落模型 description;缺省派生自谱系) */
   modelDescription?: string
+  /** 内置训练器(G2.8):linear_arx@1 / static_response@1;配置驱动,无需 train.py */
+  trainerRef?: 'linear_arx@1' | 'static_response@1'
+  /** ProcessModelSpec(内置训练器的完整规格;随 budget 冻结) */
+  processModelSpec?: Record<string, unknown>
 }
 
 export function submitJob(input: SubmitJobInput): AmlJobRow {
@@ -120,6 +124,8 @@ export function submitJob(input: SubmitJobInput): AmlJobRow {
       providerGeneration: input.providerGeneration ?? null,
       modelName: input.modelName?.trim().slice(0, 80) || null,
       modelDescription: input.modelDescription?.trim().slice(0, 500) || null,
+      trainerRef: input.trainerRef ?? null,
+      processModelSpec: input.processModelSpec ?? null,
     },
     metricsJson: null,
     gatesJson: null,

package/server/services/workshop/aml/model-references.ts

@@ -0,0 +1,83 @@
+/**
+ * 模型引用保护(C13/A19):删除模型前扫描所有引用面,命中任一即 409 并列出引用者。
+ *
+ * 覆盖:
+ *  - aml_channel_profiles.bound_model_id(优化 Channel 绑定)
+ *  - aml_training_plans.last_model_id(训练计划最近产物)
+ *  - optimizer_profiles.model_ref(Optimizer Profile;retired 不算占用)
+ *  - 在途训练/Solver 租约(进程内台账,跨介质事务不存在,只能进程内保证)
+ *
+ * 说明:retention 清理工件前也调用同一函数,避免"台账行还在、工件被 GC"。
+ */
+import type { DatabaseSync } from 'node:sqlite'
+import { AppError } from '../../../utils/errors'
+
+export interface ModelReference {
+  kind: 'channel_profile' | 'training_plan' | 'optimizer_profile' | 'lease'
+  id: string
+  detail?: string
+}
+
+/** 在途模型租约台账(Solver/Training 使用期间阻止工件 GC)。 */
+const leases = new Map<string, { count: number, holders: Set<string> }>()
+
+export interface ModelLease {
+  modelId: string
+  holder: string
+  release(): void
+}
+
+export function acquireModelLease(modelId: string, holder: string): ModelLease {
+  const cur = leases.get(modelId) ?? { count: 0, holders: new Set<string>() }
+  cur.count++
+  cur.holders.add(holder)
+  leases.set(modelId, cur)
+  let released = false
+  return {
+    modelId,
+    holder,
+    release() {
+      if (released) return
+      released = true
+      const row = leases.get(modelId)
+      if (!row) return
+      row.count = Math.max(0, row.count - 1)
+      row.holders.delete(holder)
+      if (row.count === 0) leases.delete(modelId)
+    },
+  }
+}
+
+export function inFlightModelLeases(): Array<{ modelId: string, count: number, holders: string[] }> {
+  return [...leases.entries()].map(([modelId, v]) => ({ modelId, count: v.count, holders: [...v.holders] }))
+}
+
+function tableExists(db: DatabaseSync, table: string): boolean {
+  return Boolean(db.prepare('SELECT name FROM sqlite_master WHERE type = \'table\' AND name = ?').get(table))
+}
+
+export function modelReferences(db: DatabaseSync, modelId: string): ModelReference[] {
+  const refs: ModelReference[] = []
+  if (tableExists(db, 'aml_channel_profiles')) {
+    const rows = db.prepare('SELECT channel_id FROM aml_channel_profiles WHERE bound_model_id = ?').all(modelId) as Array<{ channel_id: string }>
+    for (const row of rows) refs.push({ kind: 'channel_profile', id: row.channel_id, detail: '优化 Channel 绑定' })
+  }
+  if (tableExists(db, 'aml_training_plans')) {
+    const rows = db.prepare('SELECT id FROM aml_training_plans WHERE last_model_id = ?').all(modelId) as Array<{ id: string }>
+    for (const row of rows) refs.push({ kind: 'training_plan', id: row.id, detail: '训练计划最近产物' })
+  }
+  if (tableExists(db, 'optimizer_profiles')) {
+    const rows = db.prepare('SELECT id, version, status FROM optimizer_profiles WHERE model_ref = ? AND status != \'retired\'').all(modelId) as Array<{ id: string, version: number, status: string }>
+    for (const row of rows) refs.push({ kind: 'optimizer_profile', id: `${row.id}@${row.version}`, detail: `Profile 状态 ${row.status}` })
+  }
+  const lease = leases.get(modelId)
+  if (lease) refs.push({ kind: 'lease', id: modelId, detail: `在途租约 ${lease.count}(${[...lease.holders].join(', ')})` })
+  return refs
+}
+
+export function assertModelNotReferenced(db: DatabaseSync, modelId: string): void {
+  const refs = modelReferences(db, modelId)
+  if (!refs.length) return
+  const detail = refs.map(r => `${r.kind}:${r.id}${r.detail ? `(${r.detail})` : ''}`).join('; ')
+  throw new AppError(409, 'MODEL_IN_USE', `模型 ${modelId} 仍被引用,拒绝删除:${detail}`)
+}