agentworkshop 0.7.49 → 0.7.51

package/server/services/workshop/aml/twin/physics-spec.ts

@@ -0,0 +1,338 @@
+export const PHYSICS_SPEC_VERSION = 'physics-spec.v1' as const
+export const PHYSICS_OPERATORS = ['add', 'sub', 'mul', 'div', 'pow', 'exp', 'log', 'min', 'max', 'clamp'] as const
+export type PhysicsOperator = typeof PHYSICS_OPERATORS[number]
+
+export interface PhysicsVariableSpec {
+  id: string
+  /** Optional stable binding to a physical DAQ/DCW node. */
+  nodeId?: string
+  role: string
+  unit: string
+  physicalMeaning?: string
+  min?: number
+  max?: number
+  defaultValue?: number
+}
+
+export interface PhysicsParameterSpec {
+  id: string
+  value?: number
+  defaultValue?: number
+  min?: number
+  max?: number
+  unit?: string
+}
+
+export type PhysicsExpression
+  = | number
+    | { ref: string }
+    | { param: string }
+    | { value: number, unit?: string }
+    | { const: number, unit?: string }
+    | { literal: number, unit?: string }
+    | { op: PhysicsOperator, args: PhysicsExpression[] }
+
+export interface PhysicsEquationSpec { lhs: string, rhs: PhysicsExpression, unit?: string }
+export interface PhysicsConstraintSpec { id: string, kind?: 'hard_range' | 'max_delta' | 'rate' | 'custom', min?: number, max?: number, unit?: string }
+export interface PhysicsMonotonicitySpec { output: string, input: string, direction: 'increasing' | 'decreasing' | 'positive' | 'negative' }
+export interface PhysicsDelaySpec { variable: string, steps: number }
+export interface PhysicsSpec {
+  specVersion: typeof PHYSICS_SPEC_VERSION
+  modelId: string
+  sceneId: string
+  version?: string
+  variables: PhysicsVariableSpec[]
+  parameters: PhysicsParameterSpec[]
+  states: PhysicsEquationSpec[]
+  observations: PhysicsEquationSpec[]
+  guards?: PhysicsEquationSpec[]
+  constraints: PhysicsConstraintSpec[]
+  monotonicity?: PhysicsMonotonicitySpec[]
+  delays?: PhysicsDelaySpec[]
+  sampling?: { periodMs?: number, horizonSteps?: number }
+  solver: { method: 'discrete_state_space' | 'ode' | 'pde_reduced' | 'rom', dtSec: number, stabilityPolicy: 'reject_unstable' | 'warn_unstable' }
+  provenance: { createdBy: string, evidence?: string[], sourceDocuments?: string[], createdAt?: string }
+}
+
+export interface PhysicsSpecIssue { path: string, code: string, message: string, severity: 'error' | 'warning' }
+export interface PhysicsSpecValidationResult {
+  valid: boolean
+  ok: boolean
+  errors: string[]
+  warnings: string[]
+  issues: PhysicsSpecIssue[]
+  spec?: PhysicsSpec
+}
+
+const OPS = new Set<string>(PHYSICS_OPERATORS)
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_.:-]*$/
+const RESERVED = new Set(['__proto__', 'prototype', 'constructor'])
+const DIMENSIONLESS = new Set(['', '1', 'ratio', 'fraction', 'percent', '%'])
+const UNIT_DIMENSIONS: Record<string, string> = {
+  s: 'time', sec: 'time', ms: 'time', min: 'time', h: 'time',
+  degc: 'temperature', c: 'temperature', k: 'temperature', degf: 'temperature',
+  pa: 'pressure', kpa: 'pressure', mpa: 'pressure', bar: 'pressure', psi: 'pressure',
+  g: 'mass', kg: 'mass', mg: 'mass',
+  m: 'length', cm: 'length', mm: 'length', km: 'length',
+  a: 'current', v: 'voltage', w: 'power', j: 'energy', n: 'force',
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+}
+function finite(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value)
+}
+function idOk(value: unknown): value is string {
+  return typeof value === 'string' && IDENTIFIER.test(value) && !RESERVED.has(value)
+}
+function addIssue(issues: PhysicsSpecIssue[], path: string, code: string, message: string, severity: 'error' | 'warning' = 'error') {
+  issues.push({ path, code, message, severity })
+}
+function unitKey(unit: string | undefined): string {
+  return (unit ?? '').trim().toLowerCase().replace('°', 'deg')
+}
+function dimension(unit: string | undefined): string {
+  const key = unitKey(unit)
+  if (DIMENSIONLESS.has(key)) return 'dimensionless'
+  if (UNIT_DIMENSIONS[key]) return UNIT_DIMENSIONS[key]
+  if (key.includes('/') || key.includes('*') || key.includes('^')) return `compound:${key}`
+  return key ? `unit:${key}` : 'scalar'
+}
+function compatible(a: string, b: string): boolean {
+  return a === '*' || b === '*' || a === b || (a === 'dimensionless' && b === 'scalar') || (b === 'dimensionless' && a === 'scalar')
+}
+function normalizeExpr(value: unknown): PhysicsExpression | undefined {
+  if (finite(value)) return value
+  if (!record(value)) return undefined
+  if (finite(value.ref)) return undefined
+  if (typeof value.ref === 'string') return { ref: value.ref }
+  if (typeof value.param === 'string') return { param: value.param }
+  for (const key of ['value', 'const', 'literal']) if (finite(value[key])) return { [key]: value[key], ...(typeof value.unit === 'string' ? { unit: value.unit } : {}) } as PhysicsExpression
+  if (typeof value.op === 'string' && Array.isArray(value.args)) return { op: value.op as PhysicsOperator, args: value.args.map(item => normalizeExpr(item) ?? item) }
+  return undefined
+}
+
+interface ExprInfo { unit: string, min: number, max: number, deps: Set<string>, constant?: number }
+
+function validateExpression(value: unknown, path: string, vars: Map<string, PhysicsVariableSpec>, params: Map<string, PhysicsParameterSpec>, issues: PhysicsSpecIssue[]): ExprInfo {
+  const expr = normalizeExpr(value)
+  if (expr === undefined) {
+    addIssue(issues, path, 'AST_NODE', '表达式节点必须是数字、ref、param、literal 或白名单 op')
+    return { unit: '*', min: -Infinity, max: Infinity, deps: new Set() }
+  }
+  if (typeof expr === 'number') return { unit: '*', min: expr, max: expr, deps: new Set(), constant: expr }
+  if ('ref' in expr) {
+    const baseRef = expr.ref.endsWith('_next') ? expr.ref.slice(0, -5) : expr.ref
+    if (!idOk(expr.ref) || !vars.has(baseRef)) addIssue(issues, `${path}.ref`, 'UNKNOWN_VARIABLE', `未声明变量: ${String(expr.ref)}`)
+    const v = vars.get(baseRef)
+    return { unit: v ? dimension(v.unit) : '*', min: v?.min ?? -Infinity, max: v?.max ?? Infinity, deps: new Set([expr.ref]) }
+  }
+  if ('param' in expr) {
+    if (!idOk(expr.param) || !params.has(expr.param)) addIssue(issues, `${path}.param`, 'UNKNOWN_PARAMETER', `未声明参数: ${String(expr.param)}`)
+    const p = params.get(expr.param)
+    const value = p?.value ?? p?.defaultValue
+    return { unit: p?.unit ? dimension(p.unit) : '*', min: p?.min ?? value ?? -Infinity, max: p?.max ?? value ?? Infinity, deps: new Set() }
+  }
+  if ('value' in expr || 'const' in expr || 'literal' in expr) {
+    const n = 'value' in expr ? expr.value : 'const' in expr ? expr.const : expr.literal
+    if (!finite(n)) addIssue(issues, path, 'NON_FINITE', '常量必须是有限数字')
+    return { unit: typeof expr.unit === 'string' ? dimension(expr.unit) : '*', min: n, max: n, deps: new Set(), constant: n }
+  }
+  if (!OPS.has(expr.op)) {
+    addIssue(issues, `${path}.op`, 'OPERATOR', `不允许的算子: ${String(expr.op)}`)
+    return { unit: '*', min: -Infinity, max: Infinity, deps: new Set() }
+  }
+  const args = Array.isArray(expr.args) ? expr.args : []
+  const arity = expr.op === 'add' || expr.op === 'mul' || expr.op === 'min' || expr.op === 'max'
+    ? args.length >= 2
+    : expr.op === 'clamp'
+      ? args.length === 3
+      : args.length === 2 || ((expr.op === 'exp' || expr.op === 'log') && args.length === 1)
+  if (!arity) addIssue(issues, `${path}.args`, 'ARITY', `${expr.op} 参数个数不正确`)
+  const infos = args.map((arg, index) => validateExpression(arg, `${path}.args[${index}]`, vars, params, issues))
+  const deps = new Set<string>()
+  for (const info of infos) for (const dep of info.deps) deps.add(dep)
+  if (expr.op === 'add' || expr.op === 'sub' || expr.op === 'min' || expr.op === 'max') {
+    for (const info of infos.slice(1)) if (!compatible(infos[0]?.unit ?? '*', info.unit)) addIssue(issues, path, 'UNIT_MISMATCH', `${expr.op} 要求参数单位兼容`)
+    const min = expr.op === 'sub' ? (infos[0]?.min ?? 0) - (infos[1]?.max ?? 0) : Math.min(...infos.map(i => i.min))
+    const max = expr.op === 'sub' ? (infos[0]?.max ?? 0) - (infos[1]?.min ?? 0) : Math.max(...infos.map(i => i.max))
+    return { unit: infos.find(i => i.unit !== '*')?.unit ?? '*', min, max, deps }
+  }
+  if (expr.op === 'mul' || expr.op === 'div') {
+    const a = infos[0] ?? { unit: '*', min: -Infinity, max: Infinity, deps: new Set<string>() }
+    const b = infos[1] ?? { unit: '*', min: -Infinity, max: Infinity, deps: new Set<string>() }
+    if (expr.op === 'div' && b.min <= 0 && b.max >= 0) addIssue(issues, path, 'DIV_ZERO', '除数边界包含零')
+    const values = expr.op === 'mul' ? [a.min * b.min, a.min * b.max, a.max * b.min, a.max * b.max] : [a.min / b.min, a.min / b.max, a.max / b.min, a.max / b.max]
+    return { unit: '*', min: Math.min(...values), max: Math.max(...values), deps }
+  }
+  if (expr.op === 'pow') {
+    const base = infos[0] ?? { unit: '*', min: -Infinity, max: Infinity, deps: new Set<string>() }
+    const exponent = infos[1]
+    if (exponent && exponent.min !== exponent.max && base.unit !== '*' && base.unit !== 'scalar' && base.unit !== 'dimensionless') addIssue(issues, path, 'POW_UNIT', '非标量指数只能作用于无量纲底数')
+    if (base.min < 0 && exponent && (!Number.isInteger(exponent.min) || !Number.isInteger(exponent.max))) addIssue(issues, path, 'POW_DOMAIN', '负数底数不能使用非整数指数')
+    const e = exponent?.constant
+    const values = e !== undefined ? [Math.pow(base.min, e), Math.pow(base.max, e), Math.pow(0, e)] : [-Infinity, Infinity]
+    return { unit: '*', min: Math.min(...values), max: Math.max(...values), deps }
+  }
+  if (expr.op === 'exp' || expr.op === 'log') {
+    const input = infos[0] ?? { unit: '*', min: -Infinity, max: Infinity, deps: new Set<string>() }
+    if (input.unit !== '*' && input.unit !== 'scalar' && input.unit !== 'dimensionless') addIssue(issues, path, 'UNIT_MISMATCH', `${expr.op} 只接受无量纲输入`)
+    if (expr.op === 'log' && input.min <= 0) addIssue(issues, path, 'LOG_DOMAIN', 'log 输入必须始终大于零')
+    return { unit: 'dimensionless', min: expr.op === 'exp' ? Math.exp(input.min) : Math.log(Math.max(input.min, Number.MIN_VALUE)), max: expr.op === 'exp' ? Math.exp(input.max) : Math.log(input.max), deps }
+  }
+  const clampValue = infos[0] ?? { unit: '*', min: -Infinity, max: Infinity, deps: new Set<string>() }
+  const low = infos[1] ?? clampValue
+  const high = infos[2] ?? clampValue
+  if (!compatible(clampValue.unit, low.unit) || !compatible(clampValue.unit, high.unit)) addIssue(issues, path, 'UNIT_MISMATCH', 'clamp 参数单位必须兼容')
+  if (low.constant !== undefined && high.constant !== undefined && low.constant > high.constant) addIssue(issues, path, 'BOUND_ORDER', 'clamp 下界不能大于上界')
+  return { unit: clampValue.unit, min: Math.max(clampValue.min, low.min), max: Math.min(clampValue.max, high.max), deps }
+}
+
+export function validatePhysicsSpec(input: unknown): PhysicsSpecValidationResult {
+  const issues: PhysicsSpecIssue[] = []
+  if (!record(input)) {
+    addIssue(issues, '$', 'TYPE', 'PhysicsSpec 必须是对象')
+    return result(issues)
+  }
+  const value = input as Record<string, unknown>
+  if (value.specVersion !== PHYSICS_SPEC_VERSION) addIssue(issues, 'specVersion', 'VERSION', `specVersion 必须为 ${PHYSICS_SPEC_VERSION}`)
+  for (const key of ['modelId', 'sceneId'] as const) if (!idOk(value[key])) addIssue(issues, key, 'ID', `${key} 必须是安全标识符`)
+  const variables: PhysicsVariableSpec[] = Array.isArray(value.variables) ? value.variables as PhysicsVariableSpec[] : []
+  const parameters: PhysicsParameterSpec[] = Array.isArray(value.parameters) ? value.parameters as PhysicsParameterSpec[] : []
+  const vars = new Map<string, PhysicsVariableSpec>()
+  const params = new Map<string, PhysicsParameterSpec>()
+  if (!Array.isArray(value.variables)) addIssue(issues, 'variables', 'ARRAY', 'variables 必须是数组')
+  for (const [index, variable] of variables.entries()) {
+    if (!record(variable) || !idOk(variable.id)) {
+      addIssue(issues, `variables[${index}].id`, 'ID', '变量 id 非法')
+      continue
+    }
+    if (variable.nodeId !== undefined && !idOk(variable.nodeId)) addIssue(issues, `variables[${index}].nodeId`, 'NODE_ID', '变量 nodeId 非法')
+    if (vars.has(variable.id)) addIssue(issues, `variables[${index}].id`, 'DUPLICATE', `重复变量: ${variable.id}`)
+    if (variable.nodeId !== undefined) {
+      const owner = [...vars.entries()].find(([, v]) => v.nodeId === variable.nodeId)
+      if (owner) addIssue(issues, `variables[${index}].nodeId`, 'NODE_ID_DUPLICATE', `多个变量绑定同一节点 ${variable.nodeId}(alias 映射会互相覆盖):${owner[0]} 与 ${variable.id}`, 'warning')
+    }
+    vars.set(variable.id, variable)
+    if (typeof variable.unit !== 'string' || !variable.unit.trim()) addIssue(issues, `variables[${index}].unit`, 'UNIT', '变量必须声明单位')
+    if ((variable.min !== undefined && !finite(variable.min)) || (variable.max !== undefined && !finite(variable.max))) addIssue(issues, `variables[${index}]`, 'BOUND', '变量边界必须是有限数字')
+    if (variable.min !== undefined && variable.max !== undefined && variable.min > variable.max) addIssue(issues, `variables[${index}]`, 'BOUND_ORDER', '变量 min 不能大于 max')
+  }
+  if (!Array.isArray(value.parameters)) addIssue(issues, 'parameters', 'ARRAY', 'parameters 必须是数组')
+  for (const [index, parameter] of parameters.entries()) {
+    if (!record(parameter) || !idOk(parameter.id)) {
+      addIssue(issues, `parameters[${index}].id`, 'ID', '参数 id 非法')
+      continue
+    }
+    if (params.has(parameter.id)) addIssue(issues, `parameters[${index}].id`, 'DUPLICATE', `重复参数: ${parameter.id}`)
+    params.set(parameter.id, parameter)
+    const pv = parameter.value ?? parameter.defaultValue
+    if (!finite(pv)) addIssue(issues, `parameters[${index}]`, 'PARAMETER_VALUE', '参数必须有有限 value/defaultValue')
+    if ((parameter.min !== undefined && !finite(parameter.min)) || (parameter.max !== undefined && !finite(parameter.max))) addIssue(issues, `parameters[${index}]`, 'BOUND', '参数边界必须是有限数字')
+    if (parameter.min !== undefined && parameter.max !== undefined && parameter.min > parameter.max) addIssue(issues, `parameters[${index}]`, 'BOUND_ORDER', '参数 min 不能大于 max')
+    if (finite(pv) && ((parameter.min !== undefined && pv < parameter.min) || (parameter.max !== undefined && pv > parameter.max))) addIssue(issues, `parameters[${index}]`, 'PARAMETER_PRIOR', '参数 value 超出先验边界')
+  }
+  const equations = (key: string): PhysicsEquationSpec[] => {
+    if (!Array.isArray(value[key])) {
+      addIssue(issues, key, 'ARRAY', `${key} 必须是数组`)
+      return []
+    }
+    return value[key] as PhysicsEquationSpec[]
+  }
+  const states = equations('states')
+  const observations = equations('observations')
+  const guards = Array.isArray(value.guards) ? value.guards as PhysicsEquationSpec[] : []
+  const stateIds = new Set(variables.filter(v => v.role === 'state').map(v => v.id))
+  const checkEquations = (list: PhysicsEquationSpec[], key: string, allowed: Set<string>) => {
+    for (const [index, equation] of list.entries()) {
+      if (!record(equation) || !idOk(equation.lhs)) {
+        addIssue(issues, `${key}[${index}].lhs`, 'LHS', '方程 lhs 非法')
+        continue
+      }
+      const lhs = equation.lhs.endsWith('_next') ? equation.lhs.slice(0, -5) : equation.lhs
+      if (!allowed.has(lhs) && !vars.has(equation.lhs)) addIssue(issues, `${key}[${index}].lhs`, 'TARGET', `方程目标未声明: ${equation.lhs}`)
+      const info = validateExpression(equation.rhs, `${key}[${index}].rhs`, vars, params, issues)
+      const target = vars.get(lhs) ?? vars.get(equation.lhs)
+      if (target && !compatible(dimension(target.unit), info.unit)) addIssue(issues, `${key}[${index}].rhs`, 'UNIT_MISMATCH', `方程 ${equation.lhs} 的 rhs 单位与 lhs 不兼容`)
+      if (target && equation.unit && !compatible(dimension(target.unit), dimension(equation.unit))) addIssue(issues, `${key}[${index}].unit`, 'UNIT_MISMATCH', '方程 unit 与 lhs 不兼容')
+      if (target && info.deps.size === 0 && info.min !== -Infinity && info.max !== Infinity && target.min !== undefined && target.max !== undefined && (info.min < target.min || info.max > target.max)) {
+        const policy = record(value.solver) && value.solver.stabilityPolicy === 'warn_unstable' ? 'warning' : 'error'
+        addIssue(issues, `${key}[${index}]`, 'BOUND', `方程输出可能越过 ${target.id} 边界`, policy)
+      }
+    }
+  }
+  checkEquations(states, 'states', stateIds)
+  checkEquations(observations, 'observations', new Set(variables.filter(v => v.role === 'observation' || v.role === 'target').map(v => v.id)))
+  checkEquations(guards, 'guards', new Set(variables.filter(v => v.role === 'guard').map(v => v.id)))
+  const constraints = Array.isArray(value.constraints) ? value.constraints as PhysicsConstraintSpec[] : []
+  if (!Array.isArray(value.constraints)) addIssue(issues, 'constraints', 'ARRAY', 'constraints 必须是数组')
+  for (const [index, constraint] of constraints.entries()) {
+    if (!record(constraint) || !idOk(constraint.id)) addIssue(issues, `constraints[${index}].id`, 'ID', '约束 id 非法')
+    if ((constraint.min !== undefined && !finite(constraint.min)) || (constraint.max !== undefined && !finite(constraint.max))) addIssue(issues, `constraints[${index}]`, 'BOUND', '约束边界必须是有限数字')
+    if (constraint.min !== undefined && constraint.max !== undefined && constraint.min > constraint.max) addIssue(issues, `constraints[${index}]`, 'BOUND_ORDER', '约束 min 不能大于 max')
+    const target = vars.get(constraint.id)
+    if (target && constraint.unit && !compatible(dimension(target.unit), dimension(constraint.unit))) addIssue(issues, `constraints[${index}].unit`, 'UNIT_MISMATCH', '约束单位与变量不兼容')
+  }
+  const solver = record(value.solver) ? value.solver as Record<string, unknown> : {}
+  if (!finite(solver.dtSec) || solver.dtSec <= 0) addIssue(issues, 'solver.dtSec', 'DT', 'solver.dtSec 必须是正数')
+  if (!['discrete_state_space', 'ode', 'pde_reduced', 'rom'].includes(String(solver.method))) addIssue(issues, 'solver.method', 'METHOD', '不支持的 solver.method')
+  if (!['reject_unstable', 'warn_unstable'].includes(String(solver.stabilityPolicy))) addIssue(issues, 'solver.stabilityPolicy', 'POLICY', '不支持的 stabilityPolicy')
+  if (!record(value.provenance) || typeof value.provenance.createdBy !== 'string' || !value.provenance.createdBy.trim()) addIssue(issues, 'provenance.createdBy', 'PROVENANCE', '必须声明 provenance.createdBy')
+  const normalized = { ...value, variables, parameters, states, observations, guards, constraints, monotonicity: Array.isArray(value.monotonicity) ? value.monotonicity : [], delays: Array.isArray(value.delays) ? value.delays : [], sampling: record(value.sampling) ? value.sampling : {}, solver, provenance: value.provenance } as unknown as PhysicsSpec
+  return result(issues, normalized)
+}
+
+function result(issues: PhysicsSpecIssue[], spec?: PhysicsSpec): PhysicsSpecValidationResult {
+  const errors = issues.filter(i => i.severity === 'error').map(i => `${i.path}: ${i.message}`)
+  const warnings = issues.filter(i => i.severity === 'warning').map(i => `${i.path}: ${i.message}`)
+  return { valid: errors.length === 0, ok: errors.length === 0, errors, warnings, issues, ...(errors.length === 0 && spec ? { spec } : {}) }
+}
+
+export class PhysicsSpecValidationError extends Error {
+  constructor(public readonly validation: PhysicsSpecValidationResult) {
+    super(`Invalid PhysicsSpec: ${validation.errors.join('; ')}`)
+    this.name = 'PhysicsSpecValidationError'
+  }
+}
+export function parsePhysicsSpec(input: unknown): PhysicsSpec {
+  const checked = validatePhysicsSpec(input)
+  if (!checked.valid || !checked.spec) throw new PhysicsSpecValidationError(checked)
+  return checked.spec
+}
+export const assertValidPhysicsSpec = parsePhysicsSpec
+
+export interface ExpressionRuntimeContext { values: Record<string, number>, parameters: Record<string, number>, dtSec?: number }
+export function evaluatePhysicsExpression(expression: PhysicsExpression, context: ExpressionRuntimeContext): number {
+  if (typeof expression === 'number') return expression
+  if ('ref' in expression) return expression.ref === 'dt' || expression.ref === 'dtSec' ? context.dtSec ?? 1 : context.values[expression.ref] ?? Number.NaN
+  if ('param' in expression) return context.parameters[expression.param] ?? Number.NaN
+  if ('value' in expression || 'const' in expression || 'literal' in expression) return 'value' in expression ? expression.value : 'const' in expression ? expression.const : expression.literal
+  const args = expression.args.map(item => evaluatePhysicsExpression(item, context))
+  const arg = (index: number): number => args[index] ?? Number.NaN
+  switch (expression.op) {
+    case 'add': return args.reduce((a, b) => a + b, 0)
+    case 'sub': return arg(0) - arg(1)
+    case 'mul': return args.reduce((a, b) => a * b, 1)
+    case 'div': return arg(0) / arg(1)
+    case 'pow': return Math.pow(arg(0), arg(1))
+    case 'exp': return Math.exp(arg(0))
+    case 'log': return Math.log(arg(0))
+    case 'min': return Math.min(...args)
+    case 'max': return Math.max(...args)
+    case 'clamp': return Math.min(arg(2), Math.max(arg(1), arg(0)))
+  }
+}
+
+export function ref(id: string): PhysicsExpression {
+  return { ref: id }
+}
+export function param(id: string): PhysicsExpression {
+  return { param: id }
+}
+export function literal(value: number, unit?: string): PhysicsExpression {
+  return unit ? { value, unit } : { value }
+}
+export function op(operator: PhysicsOperator, ...args: PhysicsExpression[]): PhysicsExpression {
+  return { op: operator, args }
+}

package/server/services/workshop/aml/twin/prompt-composer.ts

@@ -0,0 +1,143 @@
+/**
+ * AML 解耦 · Channel 工况提示词组装器(2026-09-26 计划 v3 Phase 1.5)。
+ *
+ * 训练/工艺优化 Channel 的 systemPromptPrefix 不再是模板静态串,而是按
+ * 「Channel profile + 模式 + goal + 绑定节点的调试元数据」动态组装:
+ *  - 工艺优化 Channel:探索模式标准词(真实激励纪律/写治理边界/数据积累目标)
+ *    或 aml 模式标准词(绑定模型身份/能力边界/孪生验证与贝叶斯寻优纪律);
+ *  - 每个 worker 的绑定节点逐块注入:名称/物理意义/单位/量程/调试范围/每步跨度
+ *    (探索模式的激励步长来源)/当前值/判读指南;
+ *  - 训练 Channel:建模纪律/数据集契约/修正训练策略/门禁解读;
+ *  - 用户场景提示(channels.scenarioPrompt)始终追加在标准词之后 —— 模式与工况
+ *    由平台保证,产线特定的知识由用户下发,两者叠加而非覆盖。
+ * 消费点:runtime-wiring 装配成员运行时(变更经 updateChannel/twin-profile PATCH
+ * 回收成员生效);mock/真实 harness 同链路。
+ */
+import { getChannelTwinProfile, type HybridChannelProfile } from './channel-profile'
+import { getAgentNodeBindingRepo, type AgentNodeBinding } from '../../agents/node-bindings.repo'
+import { getDcwController } from '../../dcw/dcw-controller'
+import { findDcwTemplate } from '../../dcw/dcw-templates'
+import { getDaqNodeRepo } from '../../daq/daq-node.repo'
+import { findDaqTemplate } from '../../daq/daq-templates'
+import { getDcwLineRepo } from '../../dcw/dcw-line.repo'
+import { getDcwRecipeRepo } from '../../dcw/dcw-recipe.repo'
+
+const EXPLORATION_RULES = `## 你是工艺优化 Channel 的探索执行者(探索模式:尚未绑定 AML 模型)
+你的职责是围绕优化目标(goal)在真实产线上做受治理的激励探索,为 AML 建模积累高质量数据:
+1. 探索纪律:用 optimization_explore 下发激励步 —— 每步严格尊重节点的「每步调试跨度」(maxStep/tuning.step),在「调试范围」内往复激励;方向依据节点的物理意义与 goal 偏差判断,并在 hypothesis 里写明本次假设。
+2. 写治理边界:所有写入都经过平台的绑定鉴权、HITL 审批与写限界;被拒绝时不要绕行,调整幅度或等待后重试。
+3. 数据积累目标:让控制输入覆盖调试范围内多个水平(而不仅是单调单向);每 3~5 步后用 daq_query 复盘目标响应趋势,形成「参数波动 ↔ 目标响应」的记录。
+4. 何时建议训练:探索记录覆盖主要工况后,建议用户在 AML 界面创建建模任务(或由训练 Channel 走 aml_training_plan_create),用探索数据+历史批次做修正训练。
+5. 明确边界:探索模式下孪生验证(twin_trial_run)、MPC(mpc_optimize)、贝叶斯寻优(twin_bayes_optimize)均不可用 —— 这是解耦设计:模型未验证前不做模型驱动寻优。`
+
+const AML_RULES = `## 你是工艺优化 Channel 的模型受控优化者(AML 模式:已绑定通过门禁的 AML 模型)
+你的职责是用绑定的 AML 模型做孪生验证与贝叶斯寻优,产出受治理的参数推荐:
+1. 模型身份:优先使用 Channel 绑定的模型(boundModelId);它的谱系(产线·配方·目标)与本 Channel 一致,能力边界见其门禁指标(G1 单步/G2 滚动 NRMSE 与 UQ 覆盖率)。预测与实际偏差大时,先用 twin_gate_evaluate 复核门禁,偏差持续扩大则建议回到探索模式积累新数据并触发修正训练。
+2. 孪生验证:任何候选参数先用 twin_trial_run 在模型 rollout 中验证(约束/UQ/OOD 全过才算候选成立),不要把未经验证的参数直接下发。
+3. 贝叶斯寻优:用 twin_bayes_optimize 做多轮收敛搜索(模型 surrogate+UCB);把它的收敛轨迹与推荐向用户解释清楚——为什么这组参数更优。
+4. 推荐治理:所有推荐都是 recommendation-only;真实写入经治理审批(HITL 或 bounded_auto 限界),写入后用 daq_query 复测并对比模型预测,偏差作为下一轮修正依据。
+5. 持续学习:复测数据回流(批次打标)会让 AML 建模任务在新批次到达时自动修正训练;当新版本模型经门禁与审批投用后,你会被切换到新模型。`
+
+const TRAINING_RULES = `## 你是 AML 训练 Channel 的建模执行者(与工艺优化解耦的训练环境)
+你的职责是把产线数据变成可复用的 AML 模型,不触碰产线控制(本 Channel 无 DCW 写与 MPC 工具):
+1. 建模路径:aml_model_find(按 产线·配方·目标 查已有模型,可复用不重训)→ aml_node_catalog 确认节点面 → aml_dataset_build(绑定数据集 IO 契约:control=DCW 设定点回读,target=目标 DAQ 量,同配方批次)→ twin_scene_* / twin_physics_spec_draft(物理骨架)→ aml_job_submit(hybrid_residual 无 code = 平台参考训练器:物理校准+残差集成+UQ)→ aml_job_status/logs 轮询 → 门禁结论。
+2. 修正训练:新批次(含工艺优化 Channel 的探索数据)到达后,用 aml_training_plan_train 触发修正训练(重建数据集含历史+新批次);实验谱系自动串联,对比新旧版本 G1/G2 再决定是否晋升。
+3. 门禁解读:G0 数据量/G1 单步/G2 滚动/G3 泛化/G4 校准覆盖/G5 物理失败率;场景级 Twin Gate(twin_gate_evaluate)是模型投用前的最后一关,未过门的模型禁止申请绑定到优化 Channel。
+4. 交付纪律:每次训练的 change_note 只改一个组件(结构/特征/超参之一),说明预期;模型 label 由平台强制携带 产线·配方·目标。`
+
+function nodeBlockOf(binding: AgentNodeBinding): string {
+  const node = getDaqNodeRepo().byId(binding.nodeId)
+  if (node) {
+    const tpl = findDaqTemplate(node.templateKey)
+    const lines = [
+      `- 数采目标 ${node.name}(${node.id})`,
+      `  物理意义:${tpl?.semantics?.slice(0, 160) ?? tpl?.ch ?? node.templateKey}`,
+      `  单位 ${node.unit} | 正常量程 ${node.min}~${node.max}${node.unit}`,
+    ]
+    if (binding.tuning?.note) lines.push(`  调试备注:${binding.tuning.note}`)
+    return lines.join('\n')
+  }
+  const dcw = getDcwController().byId(binding.nodeId)
+  if (dcw) {
+    const tpl = findDcwTemplate(dcw.templateKey)
+    const min = binding.tuning?.min ?? dcw.min
+    const max = binding.tuning?.max ?? dcw.max
+    const step = binding.tuning?.step
+    const lines = [
+      `- 数控执行 ${dcw.name}(${dcw.id})【${binding.mode === 'manual' ? '手动审批' : '自动限界'}】`,
+      `  物理意义:${dcw.semantics || tpl?.semantics?.slice(0, 160) || tpl?.ch || dcw.templateKey}`,
+      `  单位 ${dcw.unit} | 安全量程 ${dcw.min}~${dcw.max}${dcw.unit}`,
+      `  调试范围 ${min}~${max}${dcw.unit} | 每步跨度 ${step ?? '(未定义,按量程 1/20)'}${dcw.unit}`,
+      `  当前设定 ${dcw.value ?? '-'}${dcw.unit}${binding.tuning?.note ? `\n  调试备注:${binding.tuning.note}` : ''}`,
+    ]
+    return lines.join('\n')
+  }
+  return `- 节点 ${binding.nodeId}(${binding.kind})已失效(节点不存在,绑定将自动清理)`
+}
+
+function goalBlockOf(profile: HybridChannelProfile): string {
+  const goal = profile.objective as { objectiveId?: string, targets?: Record<string, number>, weights?: Record<string, number> } | undefined
+  if (!goal || Object.keys(goal).length === 0) return '- goal:(未设置 —— 请让用户在 Channel 设置中定义优化目标后再开始探索)'
+  const targets = goal.targets ?? {}
+  const weights = goal.weights ?? {}
+  return `- goal ${goal.objectiveId ?? ''}: ${Object.entries(targets).map(([k, v]) => `${k}→${v}(权重 ${weights[k] ?? 1})`).join('; ')}`
+}
+
+function lineageBlockOf(profile: HybridChannelProfile): string {
+  const lines: string[] = []
+  if (profile.sceneId) lines.push(`- 场景:${profile.sceneId}@${profile.sceneVersion ?? '(draft)'}${profile.controlPolicy ? ` | 治理档位 ${profile.controlPolicy}` : ''}`)
+  const scene = profile.sceneContract as { lineId?: string, productId?: string, recipeId?: string } | undefined
+  if (scene?.lineId) {
+    const lineName = getDcwLineRepo().byId(scene.lineId)?.name ?? scene.lineId
+    lines.push(`- 产线:${lineName}(${scene.lineId})`)
+  }
+  if (scene?.recipeId) {
+    const recipe = getDcwRecipeRepo().byId(scene.recipeId)
+    lines.push(`- 配方:${recipe?.name ?? scene.recipeId}(${scene.recipeId})`)
+  }
+  if (profile.boundModelId) lines.push(`- 绑定模型:${profile.boundModelId}(经门禁校验后投用)`)
+  return lines.join('\n')
+}
+
+/** 工艺优化 Channel 提示词(模式感知) */
+export function buildOptimizationSystemPrompt(channelId: string, agentId: string, scenarioPrompt?: string): string | null {
+  const profile = getChannelTwinProfile(channelId)
+  if (profile.profile !== 'aml_optimization') return null
+  const isAml = profile.optimizationMode === 'aml' && !!profile.boundModelId
+  const bindings = getAgentNodeBindingRepo().byAgent(agentId)
+  if (bindings.length === 0) return null
+  const nodeBlocks = bindings.map(nodeBlockOf).join('\n')
+  const section = [
+    isAml ? AML_RULES : EXPLORATION_RULES,
+    `\n## 目标与谱系`,
+    goalBlockOf(profile),
+    lineageBlockOf(profile),
+    `\n## 你绑定节点的工况(每块含物理意义/量程/调试范围/每步跨度;你的每次操作都在这些边界内)`,
+    nodeBlocks,
+    scenarioPrompt?.trim() ? `\n## 产线特定知识(用户下发,优先级最高)\n${scenarioPrompt.trim()}` : '',
+  ].filter(Boolean).join('\n')
+  return section
+}
+
+/** 训练 Channel 提示词 */
+export function buildTrainingSystemPrompt(channelId: string, agentId: string, scenarioPrompt?: string): string | null {
+  const profile = getChannelTwinProfile(channelId)
+  if (profile.profile !== 'aml_training') return null
+  const bindings = getAgentNodeBindingRepo().byAgent(agentId)
+  const nodeBlocks = bindings.length > 0 ? bindings.map(nodeBlockOf).join('\n') : '(尚未绑定数采节点 —— 数据集构建要求所用节点均有 daq 绑定)'
+  return [
+    TRAINING_RULES,
+    `\n## 谱系与可用节点`,
+    lineageBlockOf(profile) || '- (未绑定场景;可对任意授权产线建模)',
+    nodeBlocks,
+    scenarioPrompt?.trim() ? `\n## 产线特定知识(用户下发,优先级最高)\n${scenarioPrompt.trim()}` : '',
+  ].filter(Boolean).join('\n')
+}
+
+/** 统一入口:按 Channel profile 返回应注入的 systemPromptPrefix(非工业 Channel 返回 null) */
+export function composeChannelSystemPrompt(channelId: string, agentId: string, scenarioPrompt?: string): string | null {
+  const profile = getChannelTwinProfile(channelId)
+  if (profile.profile === 'aml_optimization') return buildOptimizationSystemPrompt(channelId, agentId, scenarioPrompt)
+  if (profile.profile === 'aml_training') return buildTrainingSystemPrompt(channelId, agentId, scenarioPrompt)
+  return null
+}

package/server/services/workshop/aml/twin/provider-contracts.ts

@@ -1,34 +1,98 @@
-import type { PhysicsModelProvider } from './physics-runtime'
-import type { PhysicsModelManifest, SceneContract, ObjectiveProfile } from './contracts'
-export const TWIN_PROVIDER_API_VERSION='twin-provider.v1' as const
-export type ProviderLifecycleState='DISCOVERED'|'VALIDATED'|'REGISTERED'|'READY'|'DRAINING'|'RETIRED'|'FAILED'
-export type TwinProviderLifecycle=ProviderLifecycleState
-export interface VariableSpec { id:string, unit?:string, role?:string, physicalMeaning?:string, min?:number, max?:number, maxStep?:number, samplingPeriodMs?:number, metadata?:Record<string,unknown> }
-export type ParameterPriorMap=Record<string,{min:number,max:number,unit?:string,distribution?:string,metadata?:Record<string,unknown>}>
-export interface ArtifactContract { schemaVersion?:string|number, requiredArtifacts?:string[], optionalArtifacts?:string[], formats?:Record<string,string>, metadata?:Record<string,unknown> }
-export interface PhysicsProviderManifest { providerId:string, version:string, apiVersion:typeof TWIN_PROVIDER_API_VERSION, sceneKinds:string[], backend:'typescript'|'pytorch'|'python'|'onnx'|'rom'|'external-solver', stateVariables:VariableSpec[], controlVariables:VariableSpec[], disturbanceVariables:VariableSpec[], observationVariables?:VariableSpec[], parameterPriors:ParameterPriorMap, capabilities?:Record<string,boolean>, artifactContract?:ArtifactContract, displayName?:string, description?:string, createdBy?:string, sourceHash?:string, artifactHash?:string, metadata?:Record<string,unknown> }
-export type ProviderHealthStatus='healthy'|'unhealthy'|'degraded'|'unknown'
-export interface ProviderHealth { status:ProviderHealthStatus, checkedAt?:string, detail?:string, message?:string, latencyMs?:number, errors?:string[], [key:string]:unknown }
-export interface ProviderValidationResult { valid:boolean, errors:string[], warnings:string[], manifest?:PhysicsProviderManifest, providerHash?:string }
-export interface UniversalPhysicsProvider extends PhysicsModelProvider { readonly manifest:any, validateScene?(scene:SceneContract):unknown, calibrate?(input:unknown):Promise<unknown>|unknown, designSafeExperiment?(input:unknown):unknown, estimateUncertainty?(input:unknown):Promise<unknown>|unknown, exportArtifacts?():Promise<unknown>|unknown, health?():Promise<ProviderHealth>|ProviderHealth }
-export type TwinPhysicsProvider=UniversalPhysicsProvider
-export type LegacyPhysicsProvider=PhysicsModelProvider
-export interface ScenePack { sceneKind:string, sceneSchemaVersion:string, discover?(input:unknown):Promise<unknown>|unknown, compile?(input:unknown):Promise<SceneContract>|SceneContract, objectives?:ObjectiveProfile[], constraints?:unknown[], datasetSchema?:Record<string,unknown>, metadata?:Record<string,unknown> }
-export interface TwinScenePack extends ScenePack { scenePackId?:string, version?:string, sceneKinds?:string[] }
-export interface SolverAdapterManifest { adapterId:string, version:string, backend?:string, capabilities?:Record<string,unknown>, inputSchema?:Record<string,unknown>, outputSchema?:Record<string,unknown>, metadata?:Record<string,unknown> }
-export interface SolverAdapter { manifest:SolverAdapterManifest, solve(input:unknown,limits?:Record<string,unknown>):Promise<unknown>|unknown, cancel?(runId:string):Promise<void>, health?():Promise<ProviderHealth>|ProviderHealth }
-export interface TwinPluginContribution { providers?:TwinPhysicsProvider[], physicsProviders?:TwinPhysicsProvider[], scenePacks?:ScenePack[], objectiveProfiles?:ObjectiveProfile[], solverAdapters?:SolverAdapter[] }
-export type TwinRegistrationSource=string | { pluginName:string, pluginVersion?:string, source?:string, scope?:string, version?:string, plugin?:string, name?:string, [key:string]:unknown }
-export interface TwinProviderFilter { providerId?:string, version?:string, pluginName?:string, generation?:number, states?:ProviderLifecycleState[], includeDraining?:boolean, includeRetired?:boolean, includeFailed?:boolean, sceneKind?:string, [key:string]:unknown }
-export interface TwinProviderSummary { providerId:string, version:string, providerHash:string, pluginName:string, pluginVersion?:string, generation:number, state:ProviderLifecycleState, health:ProviderHealth, inFlight:number, registeredAt:string, drainingAt?:string, retiredAt?:string, manifest:PhysicsProviderManifest }
-export interface TwinProviderLease { refId:string, provider:TwinPhysicsProvider, manifest:PhysicsProviderManifest, lineage:{providerId:string,providerVersion:string,providerHash:string,pluginName:string,generation:number}, generation:number, released?:boolean, release():void }
-export interface TwinProviderRegistrationResult { ok:boolean, pluginName:string, generation:number, providerIds:string[], sceneKinds:string[], solverAdapterIds:string[], state:ProviderLifecycleState, idempotent?:boolean }
-export interface TwinProviderUnregistrationResult { ok:boolean, pluginName:string, generation?:number, drainedGenerations:number[], retiredGenerations:number[] }
-export interface TwinProviderDrainResult { ok:boolean, pluginName:string, generation:number, state:ProviderLifecycleState, inFlight:number, retired:boolean, providerIds:string[] }
-export interface TwinProviderRetireResult { ok:boolean, providerId:string, version:string, generation:number, state:ProviderLifecycleState, inFlight:number, retired:boolean }
-export type TwinProviderRef={providerId:string,providerVersion?:string,providerHash?:string,generation?:number}
-export type TwinPluginBridgeOperation={op:'register',pluginName:string,contribution:TwinPluginContribution,generation?:number}|{op:'unregister',pluginName:string,generation?:number}
-export interface TwinPluginExtBridge { pending:TwinPluginBridgeOperation[], _drain?:()=>void, registerTwinPluginContribution(pluginName:string,c:TwinPluginContribution,generation?:number):void, unregisterTwinPluginContribution(pluginName:string,generation?:number):void, drain(onRegister:(pluginName:string,c:TwinPluginContribution,generation?:number)=>unknown,onUnregister?:(pluginName:string,generation?:number)=>unknown):void, listTwinProviders?:(filter?:TwinProviderFilter)=>TwinProviderSummary[], [key:string]:unknown }
-
-export type ProviderManifestAccessor=PhysicsProviderManifest|(()=>PhysicsProviderManifest)
-export interface TwinProviderHealth { providerId?:string, providerVersion?:string, status:string, checkedAt:string, detail?:string, errors?:string[], [key:string]:unknown }
+import type { PhysicsModelProvider, PhysicsTrajectory } from './physics-runtime'
+import type { PhysicsModelManifest, SceneContract, TwinSnapshot, ObjectiveProfile } from './contracts'
+
+export const TWIN_PROVIDER_API_VERSION = 'twin-provider.v1' as const
+export type ProviderLifecycleState = 'DISCOVERED' | 'VALIDATED' | 'REGISTERED' | 'READY' | 'DRAINING' | 'RETIRED' | 'FAILED'
+export type TwinProviderLifecycle = ProviderLifecycleState
+export type TwinProviderBackend = 'typescript' | 'pytorch' | 'python' | 'onnx' | 'rom' | 'external-solver'
+export type ProviderManifestAccessor = PhysicsProviderManifest | (() => PhysicsProviderManifest)
+export type LegacyPhysicsProvider = PhysicsModelProvider
+
+export interface VariableSpec { id: string, unit?: string, role?: string, physicalMeaning?: string, min?: number, max?: number, maxStep?: number, samplingPeriodMs?: number, metadata?: Record<string, unknown> }
+export type ParameterPriorMap = Record<string, { min: number, max: number, unit?: string, distribution?: string, metadata?: Record<string, unknown> }>
+export interface ArtifactContract { schemaVersion?: string | number, requiredArtifacts?: string[], optionalArtifacts?: string[], formats?: Record<string, string>, metadata?: Record<string, unknown> }
+export interface PhysicsProviderManifest {
+  providerId: string
+  version: string
+  apiVersion: typeof TWIN_PROVIDER_API_VERSION
+  sceneKinds: string[]
+  backend: TwinProviderBackend
+  stateVariables: VariableSpec[]
+  controlVariables: VariableSpec[]
+  disturbanceVariables: VariableSpec[]
+  observationVariables?: VariableSpec[]
+  parameterPriors: ParameterPriorMap
+  capabilities?: { onlineStep?: boolean, rollout?: boolean, calibration?: boolean, uncertainty?: boolean, externalSolver?: boolean, mpc?: boolean }
+  artifactContract?: ArtifactContract
+  displayName?: string
+  description?: string
+  createdBy?: string
+  sourceHash?: string
+  artifactHash?: string
+  metadata?: Record<string, unknown>
+}
+export type ProviderHealthStatus = 'healthy' | 'unhealthy' | 'degraded' | 'unknown'
+export interface ProviderHealth { status: ProviderHealthStatus, checkedAt?: string, detail?: string, message?: string, latencyMs?: number, errors?: string[], checks?: Array<{ id: string, status: ProviderHealthStatus, message?: string, latencyMs?: number, details?: Record<string, unknown> }>, [key: string]: unknown }
+export interface ProviderValidationResult { valid: boolean, errors: string[], warnings: string[], manifest?: PhysicsProviderManifest, providerHash?: string }
+// 老接口(PhysicsModelProvider)的 manifest 是 PhysicsModelManifest,SDK 面用的是
+// PhysicsProviderManifest —— 两者字段集不同。这里用**交叉类型**而不是 any:
+//   · 对老代码仍可赋值/调用(交叉类型可赋给其中任一支,保证 twin-tools 的
+//     `provider: PhysicsModelProvider` 返回位不变);
+//   · 对 SDK 消费者给出 SDK 清单字段的类型保护(any 会全部丢失,lint 也会拦)。
+export type UniversalPhysicsProvider = PhysicsModelProvider & {
+  readonly manifest: PhysicsProviderManifest
+  validateScene?(scene: SceneContract): { ok?: boolean, valid?: boolean, errors?: string[], warnings?: string[] }
+  calibrate?(input: unknown): Promise<unknown> | unknown
+  designSafeExperiment?(input: unknown): unknown
+  estimateUncertainty?(input: unknown): Promise<unknown> | unknown
+  exportArtifacts?(): Promise<unknown> | unknown
+  health?(): Promise<ProviderHealth> | ProviderHealth
+}
+export type TwinPhysicsProvider = UniversalPhysicsProvider
+export type TwinProviderManifest = PhysicsProviderManifest
+
+export interface ScenePack { sceneKind: string, sceneSchemaVersion: string, discover?(input: { lineId: string, boundDaqNodes: unknown[], boundDcwNodes: unknown[] }): Promise<unknown> | unknown, compile?(input: { userPrompt?: string, nodeCatalog: unknown[], lineContext?: unknown }): Promise<SceneContract> | SceneContract, objectives?: ObjectiveProfile[], constraints?: unknown[], datasetSchema?: Record<string, unknown>, metadata?: Record<string, unknown> }
+export interface TwinScenePack extends ScenePack { scenePackId?: string, version?: string, sceneKinds?: string[] }
+export interface SolverAdapterManifest { adapterId: string, version: string, backend?: string, capabilities?: Record<string, unknown>, inputSchema?: Record<string, unknown>, outputSchema?: Record<string, unknown>, metadata?: Record<string, unknown> }
+export interface SolverAdapter { manifest: SolverAdapterManifest, solve(input: unknown, limits?: Record<string, unknown>): Promise<unknown> | unknown, cancel?(runId: string): Promise<void>, health?(): Promise<ProviderHealth> | ProviderHealth }
+export interface TwinSolverAdapter extends SolverAdapter { solverId?: string }
+export interface TwinPluginContribution { providers?: TwinPhysicsProvider[], scenePacks?: ScenePack[], objectiveProfiles?: ObjectiveProfile[], solverAdapters?: SolverAdapter[] }
+export type TwinRegistrationSource = string | { pluginName: string, pluginVersion?: string, source?: string, scope?: string, version?: string, plugin?: string, name?: string, [key: string]: unknown }
+export interface TwinProviderFilter { providerId?: string, version?: string, pluginName?: string, generation?: number, states?: ProviderLifecycleState[], includeDraining?: boolean, includeRetired?: boolean, includeFailed?: boolean, sceneKind?: string, [key: string]: unknown }
+export interface TwinProviderSummary { providerId: string, version: string, providerHash: string, pluginName: string, pluginVersion?: string, generation: number, state: ProviderLifecycleState, health: ProviderHealth, inFlight: number, registeredAt: string, drainingAt?: string, retiredAt?: string, manifest: PhysicsProviderManifest }
+export interface TwinProviderLease { refId: string, provider: TwinPhysicsProvider, manifest: PhysicsProviderManifest, lineage: { providerId: string, providerVersion: string, providerHash: string, pluginName: string, generation: number }, generation: number, released?: boolean, release(): void }
+export interface TwinProviderRegistrationResult { ok: boolean, pluginName: string, generation: number, providerIds: string[], sceneKinds: string[], solverAdapterIds: string[], state: ProviderLifecycleState, idempotent?: boolean }
+export interface TwinProviderUnregistrationResult { ok: boolean, pluginName: string, generation?: number, drainedGenerations: number[], retiredGenerations: number[] }
+export interface TwinProviderDrainResult { ok: boolean, pluginName: string, generation: number, state: ProviderLifecycleState, inFlight: number, retired: boolean, providerIds: string[] }
+export interface TwinProviderRetireResult { ok: boolean, providerId: string, version: string, generation: number, state: ProviderLifecycleState, inFlight: number, retired: boolean }
+export type TwinProviderRef = { providerId: string, providerVersion?: string, providerHash?: string, generation?: number }
+
+export type TwinRegistrationKind = 'registerPhysicsProvider' | 'registerScenePack' | 'registerObjectiveProfile' | 'registerTrainingAdapter' | 'registerSolverAdapter'
+export type TwinPluginBridgeOperation = { op: 'register', pluginName: string, contribution: TwinPluginContribution, generation?: number } | { op: 'unregister', pluginName: string, generation?: number }
+export interface TwinPluginExtBridge {
+  pending: TwinPluginBridgeOperation[]
+  _drain?: (() => void)
+  registerTwinPluginContribution(pluginName: string, contribution: TwinPluginContribution, generation?: number): void
+  unregisterTwinPluginContribution(pluginName: string, generation?: number): void
+  drain(onRegister: (pluginName: string, contribution: TwinPluginContribution, generation?: number) => unknown, onUnregister?: (pluginName: string, generation?: number) => unknown): void
+  listTwinProviders?: (filter?: TwinProviderFilter) => TwinProviderSummary[]
+  [key: string]: unknown
+}
+
+// Compatibility aliases used by early Core AML code.
+export type TwinProviderBackendLegacy = PhysicsModelManifest['backend']
+export type TwinProviderCapabilities = PhysicsProviderManifest['capabilities']
+export type TwinVariableSpec = VariableSpec
+export type TwinArtifactContract = ArtifactContract
+export interface TwinValidationResult { ok: boolean, errors?: string[], warnings?: string[] }
+export interface TwinCalibrationInput { datasetId?: string, rows?: number, snapshot?: TwinSnapshot, priors?: Record<string, unknown>, options?: Record<string, unknown> }
+export interface TwinCalibrationResult { ok: boolean, parameters?: Record<string, number>, metrics?: Record<string, number | string | boolean>, artifact?: Record<string, unknown>, errors?: string[] }
+export interface TwinExperimentDesignInput { scene: SceneContract, baselineControls: Record<string, number>, objective?: ObjectiveProfile, modelReady?: boolean, limits?: Record<string, unknown> }
+export interface TwinExperimentPlan { mode: 'safe_small_step' | 'precise_search', candidates: Array<Record<string, number>>, rationale?: string }
+export interface TwinUncertaintyInput { snapshot?: TwinSnapshot, trajectory?: PhysicsTrajectory, input?: Record<string, number> }
+export interface TwinUncertaintyResult { coverage: number, accepted: boolean, maxStd?: number, distance?: number, disagreement?: number, rejectCode?: string }
+export interface TwinArtifactManifest { providerId: string, providerVersion: string, providerHash?: string, files: string[], root?: string, metadata?: Record<string, unknown> }
+export interface TwinProviderHealth { providerId?: string, providerVersion?: string, status: string, checkedAt: string, detail?: string, errors?: string[], [key: string]: unknown }
+
+/** Optional explicit alias accepted by the global plugin bridge. */
+export interface TwinPluginContribution { physicsProviders?: TwinPhysicsProvider[] }