agentworkshop 0.7.49 → 0.7.50

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

@@ -1,50 +1,671 @@
 import { sha256 } from './contracts'
-import { checkProviderHealth, normalizeProviderHealth, providerHashOf, providerHealthAllowsUse, validateProviderDefinition } from './provider-health'
-import type { PhysicsProviderManifest, ProviderHealth, ProviderLifecycleState, ProviderValidationResult, ScenePack, SolverAdapter, SolverAdapterManifest, TwinPhysicsProvider, TwinPluginContribution, TwinProviderDrainResult, TwinProviderFilter, TwinProviderLease, TwinProviderRegistrationResult, TwinProviderRetireResult, TwinProviderSummary, TwinProviderUnregistrationResult, TwinRegistrationSource } from './provider-contracts'
-export interface ResolveProviderOptions { generation?:number, allowDraining?:boolean, includeFailed?:boolean }
-interface ProviderRecord { provider:TwinPhysicsProvider, manifest:PhysicsProviderManifest, providerHash:string, pluginName:string, pluginVersion?:string, generation:number, state:ProviderLifecycleState, health:ProviderHealth, inFlight:number, registeredAt:string, drainingAt?:string, retiredAt?:string }
-interface GenerationRecord { pluginName:string, pluginVersion?:string, generation:number, state:ProviderLifecycleState, registeredAt:string, drainingAt?:string, retiredAt?:string, providers:Map<string,ProviderRecord>, scenePacks:Map<string,ScenePack>, solverAdapters:Map<string,SolverAdapter> }
-export class TwinProviderRegistryError extends Error{readonly code:string;constructor(code:string,message:string){super(message);this.name='TwinProviderRegistryError';this.code=code}}
-function pluginOf(s: TwinRegistrationSource|string='core'){return typeof s==='string'?s:String(s.pluginName??s.plugin??s.name??'core')}
-function verOf(s: TwinRegistrationSource|string='core'){return typeof s==='string'?undefined:s.pluginVersion??s.version}
-function key(id:string,v:string){return `${id}@${v}`}
-function normalizePack(raw:any):ScenePack{return{...raw,sceneKind:raw.sceneKind??raw.scenePackId??'unknown-scene',sceneSchemaVersion:String(raw.sceneSchemaVersion??raw.version??'1.0.0')}}
-export class TwinProviderRegistry{
- private generations=new Map<string,GenerationRecord>();private next=new Map<string,number>();private leases=0
- private allocate(plugin:string){const n=(this.next.get(plugin)??0)+1;this.next.set(plugin,n);return n}
- registerTwinPluginContribution(pluginName:string,c:TwinPluginContribution,generation?:number):TwinProviderRegistrationResult{const plugin=String(pluginName||'').trim();if(!plugin)throw new TwinProviderRegistryError('PLUGIN_NAME_MISSING','pluginName required');const g=generation??this.allocate(plugin);const gk=`${plugin}\0${g}`;let gen=this.generations.get(gk);if(gen?.state==='RETIRED'||gen?.state==='DRAINING')throw new TwinProviderRegistryError('GENERATION_UNAVAILABLE',`generation ${plugin}@${g} unavailable`);if(!gen){gen={pluginName:plugin,generation:g,state:'VALIDATED',registeredAt:new Date().toISOString(),providers:new Map(),scenePacks:new Map(),solverAdapters:new Map()};this.generations.set(gk,gen)}let added=0;for(const provider of [...(c.providers??[]),...(c.physicsProviders??[])]){const check=validateProviderDefinition(provider);if(!check.valid||!check.manifest||!check.providerHash)throw new TwinProviderRegistryError('PROVIDER_INVALID',check.errors.join(';')||'invalid provider');const k=key(check.manifest.providerId,check.manifest.version);const old=gen.providers.get(k);if(old){if(old.providerHash!==check.providerHash)throw new TwinProviderRegistryError('PROVIDER_CONFLICT',k);continue}for(const [otherKey,otherGen] of this.generations){if(otherKey===gk)continue;const oldOther=otherGen.providers.get(k);if(oldOther&&oldOther.state!=='RETIRED'&&oldOther.pluginName!==plugin)throw new TwinProviderRegistryError('PROVIDER_IDENTITY_CONFLICT',`${k} already registered by ${oldOther.pluginName}`)}gen.providers.set(k,{provider,manifest:check.manifest,providerHash:check.providerHash,pluginName:plugin,pluginVersion:verOf((c as any).source),generation:g,state:'READY',health:normalizeProviderHealth(undefined),inFlight:0,registeredAt:gen.registeredAt});added++}for(const raw of c.scenePacks??[]){const pack=normalizePack(raw);gen.scenePacks.set(`${pack.sceneKind}@${pack.sceneSchemaVersion}`,pack)}for(const adapter of c.solverAdapters??[]){const m=(adapter as any).manifest as SolverAdapterManifest;if(!m?.adapterId||typeof (adapter as any).solve!=='function')throw new TwinProviderRegistryError('SOLVER_ADAPTER_INVALID','solver adapter requires manifest.adapterId and solve()');gen.solverAdapters.set(`${m.adapterId}@${m.version}`,adapter)}gen.state='READY';for(const [k,old] of this.generations){if(old.pluginName===plugin&&k!==gk&&old.state!=='RETIRED'){this.markDraining(old)}}return{ok:true,pluginName:plugin,generation:g,providerIds:[...gen.providers.values()].map(r=>r.manifest.providerId),sceneKinds:[...gen.scenePacks.values()].map(p=>p.sceneKind),solverAdapterIds:[...gen.solverAdapters.values()].map(a=>(a as any).manifest.adapterId),state:gen.state,idempotent:added===0}}
- unregisterTwinPluginContribution(pluginName:string,generation?:number):TwinProviderUnregistrationResult{const drained:number[]=[],retired:number[]=[];for(const g of this.generations.values())if(g.pluginName===pluginName&&(generation==null||g.generation===generation)){if(g.state!=='RETIRED'){this.markDraining(g);drained.push(g.generation)}if(g.state==='RETIRED')retired.push(g.generation)}return{ok:true,pluginName:pluginName,generation,drainedGenerations:drained,retiredGenerations:retired}}
- registerPhysicsProvider(provider:TwinPhysicsProvider,source:TwinRegistrationSource|string='core',generation?:number){return this.registerTwinPluginContribution(pluginOf(source),{providers:[provider]},generation)}
- registerScenePack(pack:ScenePack,source:TwinRegistrationSource|string='core',generation?:number){return this.registerTwinPluginContribution(pluginOf(source),{scenePacks:[pack]},generation)}
- registerSolverAdapter(adapter:SolverAdapter,source:TwinRegistrationSource|string='core',generation?:number){return this.registerTwinPluginContribution(pluginOf(source),{solverAdapters:[adapter]},generation)}
- resolveProvider(providerId:string,versionOrOptions?:string|ResolveProviderOptions,maybeOptions?:ResolveProviderOptions):TwinProviderLease|undefined{const version=typeof versionOrOptions==='string'?versionOrOptions:undefined;const options=(typeof versionOrOptions==='object'?versionOrOptions:maybeOptions)??{};const rows=[...this.generations.values()].flatMap(g=>[...g.providers.values()]).filter(r=>r.manifest.providerId===providerId&&(!version||r.manifest.version===version)&&(!options.generation||r.generation===options.generation)&&r.state!=='RETIRED'&&(!options.includeFailed&&r.state==='FAILED'?false:true)&&(!options.allowDraining&&r.state==='DRAINING'?false:true)).sort((a,b)=>b.generation-a.generation);const r=rows[0];if(!r)return;return this.lease(r)}
- resolve(providerId:string,versionOrOptions?:string|ResolveProviderOptions,maybeOptions?:ResolveProviderOptions){return this.resolveProvider(providerId,versionOrOptions,maybeOptions)}
- acquireProvider(providerId:string,versionOrOptions?:string|ResolveProviderOptions,maybeOptions?:ResolveProviderOptions){return this.resolveProvider(providerId,versionOrOptions,maybeOptions)}
- listProviders(filter:TwinProviderFilter={}):TwinProviderSummary[]{return[...this.generations.values()].flatMap(g=>[...g.providers.values()]).filter(r=>(!filter.providerId||r.manifest.providerId===filter.providerId)&&(!filter.version||r.manifest.version===filter.version)&&(!filter.pluginName||r.pluginName===filter.pluginName)&&(!filter.generation||r.generation===filter.generation)&&(!filter.states?.length||filter.states.includes(r.state))&&(filter.includeDraining||r.state!=='DRAINING')&&(filter.includeRetired||r.state!=='RETIRED')&&(filter.includeFailed||r.state!=='FAILED')).map(r=>({...r,manifest:r.manifest}))}
- listTwinProviders(filter:TwinProviderFilter={}){return this.listProviders(filter)}
- listScenePacks(pluginName?:string){return[...this.generations.values()].filter(g=>(!pluginName||g.pluginName===pluginName)&&g.state!=='RETIRED').flatMap(g=>[...g.scenePacks.values()])}
- listSolverAdapters(pluginName?:string){return[...this.generations.values()].filter(g=>(!pluginName||g.pluginName===pluginName)&&g.state!=='RETIRED').flatMap(g=>[...g.solverAdapters.values()])}
- getProviderHealth(providerId:string,version?:string){return this.resolveProvider(providerId,version,{allowDraining:true,includeFailed:true})?.manifest?this.find(providerId,version)?.health:undefined}
- async checkProviderHealth(providerId:string,version?:string){const r=this.find(providerId,version);if(!r)throw new TwinProviderRegistryError('PROVIDER_NOT_FOUND',providerId);r.health=await checkProviderHealth(r.provider);if(!providerHealthAllowsUse(r.health))r.state='FAILED';return r.health}
- validateProvider(providerId:string,version?:string):ProviderValidationResult{const r=this.find(providerId,version);if(!r)return{valid:false,errors:['PROVIDER_NOT_FOUND'],warnings:[]};return validateProviderDefinition(r.provider)}
- drainGeneration(pluginName:string,generation:number):TwinProviderDrainResult{const g=this.generations.get(`${pluginName}\0${generation}`);if(!g)throw new TwinProviderRegistryError('GENERATION_NOT_FOUND',`${pluginName}@${generation}`);this.markDraining(g);return{ok:true,pluginName,generation,state:g.state,inFlight:[...g.providers.values()].reduce((a,r)=>a+r.inFlight,0),retired:g.state==='RETIRED',providerIds:[...g.providers.values()].map(r=>r.manifest.providerId)}}
- drain(pluginName:string,generation:number){return this.drainGeneration(pluginName,generation)}
- retireProvider(providerId:string,version:string,generation?:number):TwinProviderRetireResult{const r=this.find(providerId,version,generation);if(!r)throw new TwinProviderRegistryError('PROVIDER_NOT_FOUND',`${providerId}@${version}`);r.state=r.inFlight?'DRAINING':'RETIRED';if(r.state==='RETIRED')r.retiredAt=new Date().toISOString();return{ok:true,providerId,version,generation:r.generation,state:r.state,inFlight:r.inFlight,retired:r.state==='RETIRED'}}
- retire(providerId:string,version:string,generation?:number){return this.retireProvider(providerId,version,generation)}
- reloadGeneration(pluginName:string,c:TwinPluginContribution,generation?:number){return this.registerTwinPluginContribution(pluginName,c,generation??this.allocate(pluginName))}
- reloadProvider(pluginName:string,c:TwinPluginContribution,generation?:number){return this.reloadGeneration(pluginName,c,generation)}
- private find(id:string,version?:string,generation?:number){return[...this.generations.values()].flatMap(g=>[...g.providers.values()]).filter(r=>r.manifest.providerId===id&&(!version||r.manifest.version===version)&&(!generation||r.generation===generation)).sort((a,b)=>b.generation-a.generation)[0]}
- private markDraining(g:GenerationRecord){if(g.state==='RETIRED')return;g.state='DRAINING';g.drainingAt??=new Date().toISOString();for(const r of g.providers.values()){if(!r.inFlight){r.state='RETIRED';r.retiredAt??=new Date().toISOString()}else r.state='DRAINING'}if([...g.providers.values()].every(r=>r.state==='RETIRED')){g.state='RETIRED';g.retiredAt??=new Date().toISOString()}}
- private lease(r:ProviderRecord):TwinProviderLease{r.inFlight++;const refId=`twin-provider-ref-${++this.leases}`;let released=false;return{refId,provider:r.provider,manifest:r.manifest,lineage:{providerId:r.manifest.providerId,providerVersion:r.manifest.version,providerHash:r.providerHash,pluginName:r.pluginName,generation:r.generation},generation:r.generation,get released(){return released},release:()=>{if(released)return;released=true;r.inFlight=Math.max(0,r.inFlight-1);if(!r.inFlight&&r.state==='DRAINING'){r.state='RETIRED';r.retiredAt??=new Date().toISOString()}}}}
-}
-const singleton=new TwinProviderRegistry();export function getTwinProviderRegistry(){return singleton}
-export const registerTwinPluginContribution=(p:string,c:TwinPluginContribution,g?:number)=>singleton.registerTwinPluginContribution(p,c,g)
-export const unregisterTwinPluginContribution=(p:string,g?:number)=>singleton.unregisterTwinPluginContribution(p,g)
-export const listTwinProviders=(f:TwinProviderFilter={})=>singleton.listProviders(f)
-export const resolveTwinProvider=(p:string,v?:string|ResolveProviderOptions,o?:ResolveProviderOptions)=>singleton.resolveProvider(p,v,o)
-export const acquireTwinProvider=resolveTwinProvider
-export const reloadTwinProviderGeneration=(p:string,c:TwinPluginContribution,g?:number)=>singleton.reloadGeneration(p,c,g)
-export const drainTwinProviderGeneration=(p:string,g:number)=>singleton.drainGeneration(p,g)
-export const retireTwinProvider=(p:string,v:string,g?:number)=>singleton.retireProvider(p,v,g)
-export function attachTwinPluginBridge(registry:TwinProviderRegistry=singleton){const global=globalThis as any;const existing=global.__twinPluginExt;const api:any={registerPhysicsProvider:(payload:any,source:any)=>registry.registerPhysicsProvider(payload,source),registerScenePack:(payload:any,source:any)=>registry.registerScenePack({...(payload as any),sceneKind:(payload as any).sceneKind??(payload as any).scenePackId??'unknown',sceneSchemaVersion:(payload as any).sceneSchemaVersion??(payload as any).version??'1.0.0'},source),registerObjectiveProfile:()=>({ok:true}),registerTrainingAdapter:()=>({ok:true}),registerSolverAdapter:(payload:any,source:any)=>registry.registerSolverAdapter(payload,source),listProviders:(f:any)=>registry.listProviders(f),listTwinProviders:(f:any)=>registry.listProviders(f),getProviderHealth:(p:string,v?:string)=>registry.getProviderHealth(p,v),resolveProvider:(p:string,v?:string)=>registry.resolveProvider(p,v),validateProvider:(p:string,v?:string)=>registry.validateProvider(p,v),retireProvider:(p:string,v?:string)=>v?registry.retireProvider(p,v):undefined,unregisterPlugin:(s:any)=>registry.unregisterTwinPluginContribution(String(s?.plugin??s?.pluginName??s?.name??s)),removePlugin:(s:any)=>registry.unregisterTwinPluginContribution(String(s?.plugin??s?.pluginName??s?.name??s))};if(existing&&typeof existing.attach==='function'){existing.attach(api);return existing}const bridge=existing??{pending:[],register:(kind:string,payload:any,source:any)=>{const fn=api[kind];return fn?fn(payload,source):undefined},registerEntry:(e:any)=>bridge.register(e.kind,e.payload,e.source),attach:(r:any)=>{bridge.registry=r},call:(m:string,...a:any[])=>bridge.registry?.[m]?.(...a),invoke:(m:string,...a:any[])=>bridge.call(m,...a)};global.__twinPluginExt=bridge;if(Array.isArray(bridge.pending)&&bridge.pending.length){const pending=bridge.pending.splice(0);for(const e of pending){const fn=api[e.kind];if(fn)fn(e.payload,e.source)}}return bridge}
-attachTwinPluginBridge()
+import { checkProviderHealth as probeProviderHealth, normalizeProviderHealth, providerHealthAllowsUse } from './provider-health'
+import { TWIN_PROVIDER_API_VERSION } from './provider-contracts'
+import type {
+  ArtifactContract,
+  LegacyPhysicsProvider,
+  ParameterPriorMap,
+  PhysicsProviderManifest,
+  ProviderHealth,
+  ProviderLifecycleState,
+  ProviderValidationResult,
+  ScenePack,
+  SolverAdapter,
+  SolverAdapterManifest,
+  TwinPhysicsProvider,
+  TwinPluginContribution,
+  TwinProviderDrainResult,
+  TwinProviderFilter,
+  TwinProviderLease,
+  TwinProviderRegistrationResult,
+  TwinProviderRetireResult,
+  TwinProviderSummary,
+  TwinProviderUnregistrationResult,
+  TwinRegistrationSource,
+  UniversalPhysicsProvider,
+  VariableSpec,
+} from './provider-contracts'
+
+export interface ResolveProviderOptions {
+  generation?: number
+  allowDraining?: boolean
+  includeFailed?: boolean
+}
+
+export interface TwinProviderGenerationSummary {
+  pluginName: string
+  pluginVersion?: string
+  generation: number
+  state: ProviderLifecycleState
+  providerIds: string[]
+  inFlight: number
+  registeredAt: string
+  drainingAt?: string
+  retiredAt?: string
+}
+
+export class TwinProviderRegistryError extends Error {
+  readonly code: string
+  readonly details?: Record<string, unknown>
+  constructor(code: string, message: string, details?: Record<string, unknown>) {
+    super(message)
+    this.name = 'TwinProviderRegistryError'
+    this.code = code
+    this.details = details
+  }
+}
+
+interface ProviderRecord {
+  provider: TwinPhysicsProvider
+  manifest: PhysicsProviderManifest
+  providerHash: string
+  pluginName: string
+  pluginVersion?: string
+  generation: number
+  state: ProviderLifecycleState
+  health: ProviderHealth
+  inFlight: number
+  registeredAt: string
+  drainingAt?: string
+  retiredAt?: string
+}
+
+interface GenerationRecord {
+  pluginName: string
+  pluginVersion?: string
+  generation: number
+  state: ProviderLifecycleState
+  registeredAt: string
+  drainingAt?: string
+  retiredAt?: string
+  providers: Map<string, ProviderRecord>
+  scenePacks: Map<string, ScenePack>
+  solverAdapters: Map<string, SolverAdapter>
+}
+
+interface NormalizedSource { pluginName: string, pluginVersion?: string, source?: string }
+interface StagedProvider { provider: TwinPhysicsProvider, manifest: PhysicsProviderManifest, providerHash: string, key: string }
+interface StagedContribution {
+  providers: StagedProvider[]
+  scenePacks: Array<{ pack: ScenePack, key: string }>
+  solverAdapters: Array<{ adapter: SolverAdapter, manifest: SolverAdapterManifest, key: string }>
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object'
+}
+function text(value: unknown, fallback = ''): string {
+  return typeof value === 'string' && value.trim() ? value.trim() : fallback
+}
+function number(value: unknown): number | undefined {
+  return Number.isFinite(Number(value)) ? Number(value) : undefined
+}
+function key(id: string, version: string): string {
+  return `${id}@${version}`
+}
+function generationKey(pluginName: string, generation: number): string {
+  return `${pluginName}\u0000${generation}`
+}
+function readAccessor(value: unknown): unknown {
+  return typeof value === 'function' ? (value as () => unknown)() : value
+}
+
+function variables(value: unknown, fallback: unknown[] = []): VariableSpec[] {
+  const result: Array<VariableSpec | null> = []
+  for (const raw of (Array.isArray(value) ? value : fallback)) {
+    if (typeof raw === 'string') {
+      result.push({ id: raw })
+      continue
+    }
+    if (!isRecord(raw)) {
+      result.push(null)
+      continue
+    }
+    const id = text(raw.id ?? raw.name)
+    result.push(id
+      ? {
+          id,
+          unit: typeof raw.unit === 'string' ? raw.unit : undefined,
+          role: typeof raw.role === 'string' ? raw.role : undefined,
+          physicalMeaning: typeof raw.physicalMeaning === 'string' ? raw.physicalMeaning : undefined,
+          min: number(raw.min), max: number(raw.max), maxStep: number(raw.maxStep),
+          samplingPeriodMs: number(raw.samplingPeriodMs),
+          metadata: isRecord(raw.metadata) ? raw.metadata : undefined,
+        }
+      : null)
+  }
+  return result.filter((value): value is VariableSpec => value !== null)
+}
+
+function priors(value: unknown, parameters: unknown): ParameterPriorMap {
+  const source = isRecord(value) ? value : isRecord(parameters) ? parameters : {}
+  const result: ParameterPriorMap = {}
+  for (const [id, raw] of Object.entries(source)) {
+    if (!isRecord(raw)) continue
+    const min = number(raw.min)
+    const max = number(raw.max)
+    if (min == null || max == null || min > max) continue
+    result[id] = { min, max, unit: typeof raw.unit === 'string' ? raw.unit : undefined, distribution: typeof raw.distribution === 'string' ? raw.distribution : undefined, metadata: isRecord(raw.metadata) ? raw.metadata : undefined }
+  }
+  return result
+}
+
+function backend(value: unknown): PhysicsProviderManifest['backend'] {
+  const valueText = String(value ?? 'typescript')
+  return ['typescript', 'python', 'onnx', 'rom', 'external-solver', 'pytorch'].includes(valueText)
+    ? valueText as PhysicsProviderManifest['backend']
+    : 'external-solver'
+}
+
+function capabilities(provider: TwinPhysicsProvider, raw: Record<string, unknown>): PhysicsProviderManifest['capabilities'] {
+  const value = isRecord(raw.capabilities) ? raw.capabilities : {}
+  return {
+    onlineStep: typeof provider.step === 'function' && value.onlineStep !== false,
+    rollout: typeof provider.simulate === 'function' && value.rollout !== false,
+    calibration: typeof (provider as UniversalPhysicsProvider).calibrate === 'function' || value.calibration === true,
+    uncertainty: typeof (provider as UniversalPhysicsProvider).estimateUncertainty === 'function' || value.uncertainty === true,
+    externalSolver: value.externalSolver === true,
+    mpc: value.mpc === true,
+  }
+}
+
+function artifactContract(raw: Record<string, unknown>): ArtifactContract {
+  const value = isRecord(raw.artifactContract) ? raw.artifactContract : {}
+  return {
+    schemaVersion: typeof value.schemaVersion === 'string' || typeof value.schemaVersion === 'number' ? value.schemaVersion : 1,
+    requiredArtifacts: Array.isArray(value.requiredArtifacts) ? value.requiredArtifacts.map(String) : [],
+    optionalArtifacts: Array.isArray(value.optionalArtifacts) ? value.optionalArtifacts.map(String) : [],
+    formats: isRecord(value.formats) ? Object.fromEntries(Object.entries(value.formats).map(([id, format]) => [id, String(format)])) : undefined,
+    metadata: isRecord(value.metadata) ? value.metadata : undefined,
+  }
+}
+
+/** Normalise UniversalPhysicsProvider and the current PhysicsModelProvider shape. */
+export function normalizeProviderManifest(provider: TwinPhysicsProvider): PhysicsProviderManifest {
+  const raw = readAccessor((provider as unknown as { manifest?: unknown }).manifest)
+  if (!isRecord(raw)) throw new TwinProviderRegistryError('PROVIDER_MANIFEST_INVALID', 'Provider manifest must be an object')
+  const legacyId = text(raw.physicsModelId)
+  const providerId = text(raw.providerId ?? raw.id ?? legacyId)
+  const version = text(raw.version)
+  if (!providerId) throw new TwinProviderRegistryError('PROVIDER_ID_MISSING', 'Provider manifest.providerId is required')
+  if (!version) throw new TwinProviderRegistryError('PROVIDER_VERSION_MISSING', `Provider ${providerId} manifest.version is required`)
+  const sceneId = text(raw.sceneId)
+  const sceneKinds = (Array.isArray(raw.sceneKinds) ? raw.sceneKinds : sceneId ? [sceneId] : []).map(String).map(value => value.trim()).filter(Boolean)
+  if (!sceneKinds.length) throw new TwinProviderRegistryError('PROVIDER_SCENE_KIND_MISSING', `Provider ${providerId}@${version} must declare sceneKinds`)
+  const apiVersion = text(raw.apiVersion, TWIN_PROVIDER_API_VERSION)
+  if (apiVersion !== TWIN_PROVIDER_API_VERSION) throw new TwinProviderRegistryError('PROVIDER_API_VERSION_UNSUPPORTED', `Provider ${providerId}@${version} uses unsupported apiVersion=${apiVersion}`)
+  return {
+    providerId, version, apiVersion: TWIN_PROVIDER_API_VERSION, sceneKinds,
+    backend: backend(raw.backend),
+    stateVariables: variables(raw.stateVariables),
+    controlVariables: variables(raw.controlVariables),
+    disturbanceVariables: variables(raw.disturbanceVariables),
+    observationVariables: variables(raw.observationVariables ?? raw.observations),
+    parameterPriors: priors(raw.parameterPriors, raw.parameters),
+    capabilities: capabilities(provider, raw),
+    artifactContract: artifactContract(raw),
+    displayName: typeof raw.displayName === 'string' ? raw.displayName : undefined,
+    description: typeof raw.description === 'string' ? raw.description : undefined,
+    createdBy: typeof raw.createdBy === 'string' ? raw.createdBy : undefined,
+    sourceHash: typeof raw.sourceHash === 'string' ? raw.sourceHash : undefined,
+    artifactHash: typeof raw.artifactHash === 'string' ? raw.artifactHash : undefined,
+    metadata: isRecord(raw.metadata) ? raw.metadata : undefined,
+  }
+}
+
+export function providerHashOf(providerOrManifest: TwinPhysicsProvider | PhysicsProviderManifest): string {
+  const value = isRecord(providerOrManifest) && 'providerId' in providerOrManifest
+    ? providerOrManifest as PhysicsProviderManifest
+    : normalizeProviderManifest(providerOrManifest as TwinPhysicsProvider)
+  // Runtime timestamps are provenance metadata, not executable provider identity.
+  // Excluding them keeps lineage stable across provider instances/restarts.
+  const { createdAt: _createdAt, ...stable } = value as unknown as Record<string, unknown>
+  return sha256(stable)
+}
+
+export function validateProviderDefinition(provider: TwinPhysicsProvider): ProviderValidationResult {
+  const errors: string[] = []
+  const warnings: string[] = []
+  try {
+    const manifest = normalizeProviderManifest(provider)
+    for (const method of ['initialize', 'step', 'simulate', 'evaluateConstraints'] as const) {
+      if (typeof (provider as unknown as Record<string, unknown>)[method] !== 'function') errors.push(`missing method: ${method}`)
+    }
+    if (typeof (provider as UniversalPhysicsProvider).validateScene !== 'function') warnings.push('provider does not expose validateScene; registry keeps structural validation only')
+    return { valid: errors.length === 0, errors, warnings, manifest, providerHash: providerHashOf(manifest) }
+  }
+  catch (error) {
+    errors.push(error instanceof Error ? error.message : String(error))
+    return { valid: false, errors, warnings }
+  }
+}
+
+function sourceOf(pluginName: string, source?: TwinRegistrationSource): NormalizedSource {
+  if (source && typeof source === 'object') return { pluginName: text(source.pluginName, pluginName), pluginVersion: source.pluginVersion, source: source.source }
+  return { pluginName: text(pluginName, typeof source === 'string' ? source : 'core'), source: typeof source === 'string' ? source : undefined }
+}
+function solverManifest(adapter: SolverAdapter): SolverAdapterManifest {
+  const raw = readAccessor((adapter as unknown as { manifest?: unknown }).manifest)
+  if (!isRecord(raw)) throw new TwinProviderRegistryError('SOLVER_MANIFEST_INVALID', 'Solver adapter manifest must be an object')
+  const adapterId = text(raw.adapterId ?? raw.id ?? raw.name)
+  const version = text(raw.version, '0.0.0')
+  if (!adapterId) throw new TwinProviderRegistryError('SOLVER_ADAPTER_ID_MISSING', 'Solver adapter manifest.adapterId is required')
+  if (typeof adapter.solve !== 'function') throw new TwinProviderRegistryError('SOLVER_ADAPTER_INVALID', `Solver adapter ${adapterId}@${version} must expose solve()`)
+  return { adapterId, version, backend: typeof raw.backend === 'string' ? raw.backend : undefined, capabilities: isRecord(raw.capabilities)
+    ? {
+        synchronous: raw.capabilities.synchronous === true,
+        asynchronous: raw.capabilities.asynchronous !== false,
+        cancellation: raw.capabilities.cancellation === true,
+        artifacts: raw.capabilities.artifacts === true,
+      }
+    : undefined, metadata: isRecord(raw.metadata) ? raw.metadata : undefined }
+}
+
+function stageContribution(contribution: TwinPluginContribution): StagedContribution {
+  const providers = [...(contribution.providers ?? []), ...(contribution.physicsProviders ?? [])]
+  const stagedProviders: StagedProvider[] = []
+  const providerKeys = new Set<string>()
+  for (const provider of providers) {
+    const checked = validateProviderDefinition(provider)
+    if (!checked.valid || !checked.manifest || !checked.providerHash) throw new TwinProviderRegistryError('PROVIDER_INVALID', checked.errors.join('; ') || 'Provider definition is invalid')
+    const providerKey = key(checked.manifest.providerId, checked.manifest.version)
+    const duplicate = stagedProviders.find(value => value.key === providerKey)
+    if (duplicate && duplicate.providerHash !== checked.providerHash) throw new TwinProviderRegistryError('PROVIDER_CONFLICT', `Contribution contains conflicting providers for ${providerKey}`)
+    if (!providerKeys.has(providerKey)) {
+      providerKeys.add(providerKey)
+      stagedProviders.push({ provider, manifest: checked.manifest, providerHash: checked.providerHash, key: providerKey })
+    }
+  }
+  const scenePacks: StagedContribution['scenePacks'] = []
+  const sceneKeys = new Set<string>()
+  for (const pack of contribution.scenePacks ?? []) {
+    if (!isRecord(pack) || !text(pack.sceneKind) || !text(pack.sceneSchemaVersion)) throw new TwinProviderRegistryError('SCENE_PACK_INVALID', 'ScenePack requires sceneKind and sceneSchemaVersion')
+    const packValue = pack as unknown as Record<string, unknown>
+    for (const method of ['discover', 'compile'] as const) {
+      if (packValue[method] != null && typeof packValue[method] !== 'function') throw new TwinProviderRegistryError('SCENE_PACK_INVALID', `ScenePack ${pack.sceneKind}.${method} must be a function when provided`)
+    }
+    for (const field of ['objectives', 'constraints', 'datasetSchema'] as const) {
+      const value = packValue[field]
+      if (value != null && typeof value !== 'function' && !Array.isArray(value) && !isRecord(value)) throw new TwinProviderRegistryError('SCENE_PACK_INVALID', `ScenePack ${pack.sceneKind}.${field} has an unsupported shape`)
+    }
+    const sceneKey = `${pack.sceneKind}@${pack.sceneSchemaVersion}`
+    if (!sceneKeys.has(sceneKey)) {
+      sceneKeys.add(sceneKey)
+      scenePacks.push({ pack, key: sceneKey })
+    }
+  }
+  const solverAdapters: StagedContribution['solverAdapters'] = []
+  const solverKeys = new Set<string>()
+  for (const adapter of contribution.solverAdapters ?? []) {
+    const manifest = solverManifest(adapter)
+    const solverKey = key(manifest.adapterId, manifest.version)
+    if (!solverKeys.has(solverKey)) {
+      solverKeys.add(solverKey)
+      solverAdapters.push({ adapter, manifest, key: solverKey })
+    }
+  }
+  return { providers: stagedProviders, scenePacks, solverAdapters }
+}
+
+export class TwinProviderRegistry {
+  private readonly generations = new Map<string, GenerationRecord>()
+  private readonly nextGenerationByPlugin = new Map<string, number>()
+  private leaseSequence = 0
+
+  registerTwinPluginContribution(pluginName: string, contribution: TwinPluginContribution, generation?: number): TwinProviderRegistrationResult {
+    const source = sourceOf(pluginName)
+    if (!source.pluginName) throw new TwinProviderRegistryError('PLUGIN_NAME_MISSING', 'pluginName is required')
+    if (!isRecord(contribution)) throw new TwinProviderRegistryError('CONTRIBUTION_INVALID', 'Twin plugin contribution must be an object')
+    const active = this.currentGeneration(source.pluginName)
+    const requested = generation == null ? active?.generation ?? this.allocateGeneration(source.pluginName) : this.assertGeneration(generation)
+    this.nextGenerationByPlugin.set(source.pluginName, Math.max(this.nextGenerationByPlugin.get(source.pluginName) ?? 0, requested))
+    const targetKey = generationKey(source.pluginName, requested)
+    const existing = this.generations.get(targetKey)
+    if (existing?.state === 'RETIRED') throw new TwinProviderRegistryError('GENERATION_RETIRED', `Plugin ${source.pluginName} generation ${requested} is retired`)
+    if (existing?.state === 'DRAINING') throw new TwinProviderRegistryError('GENERATION_DRAINING', `Plugin ${source.pluginName} generation ${requested} is draining`)
+    const staged = stageContribution(contribution)
+    const target = existing ?? {
+      pluginName: source.pluginName, pluginVersion: source.pluginVersion, generation: requested, state: 'VALIDATED' as ProviderLifecycleState,
+      registeredAt: new Date().toISOString(), providers: new Map<string, ProviderRecord>(), scenePacks: new Map<string, ScenePack>(), solverAdapters: new Map<string, SolverAdapter>(),
+    } satisfies GenerationRecord
+    let added = 0
+    for (const item of staged.providers) {
+      const current = target.providers.get(item.key)
+      if (current) {
+        if (current.providerHash !== item.providerHash) throw new TwinProviderRegistryError('PROVIDER_CONFLICT', `Provider ${item.key} conflicts in plugin ${source.pluginName} generation ${requested}`)
+        continue
+      }
+      this.assertProviderKeyAvailable(item.key, source.pluginName, requested)
+      target.providers.set(item.key, {
+        provider: item.provider, manifest: item.manifest, providerHash: item.providerHash, pluginName: source.pluginName, pluginVersion: source.pluginVersion,
+        generation: requested, state: 'READY', health: normalizeProviderHealth(undefined), inFlight: 0, registeredAt: target.registeredAt,
+      })
+      added++
+    }
+    for (const item of staged.scenePacks) target.scenePacks.set(item.key, item.pack)
+    for (const item of staged.solverAdapters) target.solverAdapters.set(item.key, item.adapter)
+    target.pluginVersion = source.pluginVersion ?? target.pluginVersion
+    target.state = target.providers.size || target.scenePacks.size || target.solverAdapters.size ? 'READY' : 'REGISTERED'
+    this.generations.set(targetKey, target)
+    for (const record of this.generations.values()) {
+      if (record.pluginName === source.pluginName && record.generation !== requested && record.state !== 'RETIRED' && record.state !== 'FAILED') this.markGenerationDraining(record)
+    }
+    return { ok: true, pluginName: source.pluginName, generation: requested, providerIds: staged.providers.map(item => item.manifest.providerId), sceneKinds: staged.scenePacks.map(item => item.pack.sceneKind), solverAdapterIds: staged.solverAdapters.map(item => item.manifest.adapterId), state: target.state, idempotent: existing != null && added === 0 }
+  }
+
+  unregisterTwinPluginContribution(pluginName: string, generation?: number): TwinProviderUnregistrationResult {
+    const plugin = text(pluginName)
+    if (!plugin) throw new TwinProviderRegistryError('PLUGIN_NAME_MISSING', 'pluginName is required')
+    const records = [...this.generations.values()].filter(record => record.pluginName === plugin && (generation == null || record.generation === generation)).sort((a, b) => a.generation - b.generation)
+    const drainedGenerations: number[] = []
+    const retiredGenerations: number[] = []
+    for (const record of records) {
+      if (record.state !== 'RETIRED') {
+        this.markGenerationDraining(record)
+        drainedGenerations.push(record.generation)
+      }
+      if (record.state === 'RETIRED') retiredGenerations.push(record.generation)
+    }
+    return { ok: true, pluginName: plugin, generation, drainedGenerations, retiredGenerations }
+  }
+
+  registerPhysicsProvider(provider: TwinPhysicsProvider, source: TwinRegistrationSource = 'core', generation?: number): TwinProviderRegistrationResult {
+    const sourceInfo = sourceOf(typeof source === 'string' ? source : source.pluginName, source)
+    return this.registerTwinPluginContribution(sourceInfo.pluginName, { providers: [provider] }, generation)
+  }
+
+  registerScenePack(pack: ScenePack, source: TwinRegistrationSource = 'core', generation?: number): TwinProviderRegistrationResult {
+    const sourceInfo = sourceOf(typeof source === 'string' ? source : source.pluginName, source)
+    return this.registerTwinPluginContribution(sourceInfo.pluginName, { scenePacks: [pack] }, generation)
+  }
+
+  registerSolverAdapter(adapter: SolverAdapter, source: TwinRegistrationSource = 'core', generation?: number): TwinProviderRegistrationResult {
+    const sourceInfo = sourceOf(typeof source === 'string' ? source : source.pluginName, source)
+    return this.registerTwinPluginContribution(sourceInfo.pluginName, { solverAdapters: [adapter] }, generation)
+  }
+
+  reloadGeneration(pluginName: string, contribution: TwinPluginContribution, generation?: number): TwinProviderRegistrationResult
+  reloadGeneration(pluginName: string, generation: number, contribution: TwinPluginContribution): TwinProviderRegistrationResult
+  reloadGeneration(pluginName: string, contributionOrGeneration: TwinPluginContribution | number, maybeContribution?: TwinPluginContribution | number): TwinProviderRegistrationResult {
+    const contribution = typeof contributionOrGeneration === 'number' ? maybeContribution as TwinPluginContribution : contributionOrGeneration
+    const requested = typeof contributionOrGeneration === 'number' ? contributionOrGeneration : typeof maybeContribution === 'number' ? maybeContribution : this.allocateGeneration(pluginName)
+    if (!contribution) throw new TwinProviderRegistryError('CONTRIBUTION_INVALID', 'reloadGeneration requires a contribution')
+    return this.registerTwinPluginContribution(pluginName, contribution, requested)
+  }
+
+  reloadProvider(pluginName: string, contribution: TwinPluginContribution, generation?: number): TwinProviderRegistrationResult { return this.reloadGeneration(pluginName, contribution, generation) }
+
+  resolveProvider(providerId: string, versionOrOptions?: string | ResolveProviderOptions, maybeOptions?: ResolveProviderOptions): TwinProviderLease | undefined {
+    const version = typeof versionOrOptions === 'string' ? versionOrOptions : undefined
+    const options = (typeof versionOrOptions === 'object' ? versionOrOptions : maybeOptions) ?? {}
+    const record = this.findProviderRecords(providerId, version, options)[0]
+    return record ? this.createLease(record) : undefined
+  }
+
+  resolve(providerId: string, versionOrOptions?: string | ResolveProviderOptions, maybeOptions?: ResolveProviderOptions): TwinProviderLease | undefined {
+    return this.resolveProvider(providerId, versionOrOptions, maybeOptions)
+  }
+
+  acquireProvider(providerId: string, versionOrOptions?: string | ResolveProviderOptions, maybeOptions?: ResolveProviderOptions): TwinProviderLease | undefined {
+    return this.resolveProvider(providerId, versionOrOptions, maybeOptions)
+  }
+
+  listProviders(filter: TwinProviderFilter = {}): TwinProviderSummary[] {
+    const result: TwinProviderSummary[] = []
+    for (const generation of this.generations.values()) {
+      for (const record of generation.providers.values()) {
+        if (filter.providerId && record.manifest.providerId !== filter.providerId) continue
+        if (filter.version && record.manifest.version !== filter.version) continue
+        if (filter.pluginName && record.pluginName !== filter.pluginName) continue
+        if (filter.generation != null && record.generation !== filter.generation) continue
+        if (filter.states?.length && !filter.states.includes(record.state)) continue
+        if (record.state === 'DRAINING' && !filter.includeDraining) continue
+        if (record.state === 'RETIRED' && !filter.includeRetired) continue
+        if (record.state === 'FAILED' && !filter.includeFailed) continue
+        result.push(this.toSummary(record))
+      }
+    }
+    return result.sort((a, b) => b.generation - a.generation || a.providerId.localeCompare(b.providerId) || a.version.localeCompare(b.version))
+  }
+
+  listTwinProviders(filter: TwinProviderFilter = {}): TwinProviderSummary[] { return this.listProviders(filter) }
+
+  listGenerations(pluginName?: string): TwinProviderGenerationSummary[] {
+    return [...this.generations.values()]
+      .filter(record => !pluginName || record.pluginName === pluginName)
+      .map(record => ({
+        pluginName: record.pluginName, pluginVersion: record.pluginVersion, generation: record.generation,
+        state: this.generationState(record), providerIds: [...record.providers.values()].map(provider => provider.manifest.providerId),
+        inFlight: [...record.providers.values()].reduce((total, provider) => total + provider.inFlight, 0), registeredAt: record.registeredAt,
+        drainingAt: record.drainingAt, retiredAt: record.retiredAt,
+      }))
+      .sort((a, b) => b.generation - a.generation)
+  }
+
+  listScenePacks(pluginName?: string): ScenePack[] {
+    return [...this.generations.values()].filter(record => (!pluginName || record.pluginName === pluginName) && record.state !== 'RETIRED').flatMap(record => [...record.scenePacks.values()])
+  }
+
+  listSolverAdapters(pluginName?: string): SolverAdapter[] {
+    return [...this.generations.values()].filter(record => (!pluginName || record.pluginName === pluginName) && record.state !== 'RETIRED').flatMap(record => [...record.solverAdapters.values()])
+  }
+
+  getProviderHealth(providerId: string, version?: string, generation?: number): ProviderHealth | undefined {
+    return this.findProviderRecords(providerId, version, { generation, allowDraining: true, includeFailed: true })[0]?.health
+  }
+
+  async checkProviderHealth(providerId: string, version?: string, generation?: number): Promise<ProviderHealth> {
+    const record = this.findProviderRecords(providerId, version, { generation, allowDraining: true, includeFailed: true })[0]
+    if (!record) throw new TwinProviderRegistryError('PROVIDER_NOT_FOUND', `Provider ${providerId}${version ? `@${version}` : ''} is not registered`)
+    const health = await probeProviderHealth(record.provider)
+    record.health = health
+    if (health.status === 'unhealthy' && record.state !== 'RETIRED' && record.state !== 'DRAINING') record.state = 'FAILED'
+    else if (health.status !== 'unhealthy' && record.state === 'FAILED') record.state = 'READY'
+    this.updateGenerationState(this.generationOf(record))
+    return health
+  }
+
+  validateProvider(providerId: string, version?: string, generation?: number): ProviderValidationResult {
+    const record = this.findProviderRecords(providerId, version, { generation, allowDraining: true, includeFailed: true })[0]
+    if (!record) return { valid: false, errors: [`Provider ${providerId}${version ? `@${version}` : ''} is not registered`], warnings: [] }
+    const result = validateProviderDefinition(record.provider)
+    if (record.state === 'FAILED' || !providerHealthAllowsUse(record.health)) result.valid = false
+    return result
+  }
+
+  drainGeneration(pluginName: string, generation: number): TwinProviderDrainResult {
+    const record = this.generations.get(generationKey(pluginName, generation))
+    if (!record) throw new TwinProviderRegistryError('GENERATION_NOT_FOUND', `Plugin ${pluginName} generation ${generation} is not registered`)
+    this.markGenerationDraining(record)
+    const providers = [...record.providers.values()]
+    const state = this.generationState(record)
+    return { ok: true, pluginName, generation, state, inFlight: providers.reduce((total, provider) => total + provider.inFlight, 0), retired: state === 'RETIRED', providerIds: providers.map(provider => provider.manifest.providerId) }
+  }
+
+  drain(pluginName: string, generation: number): TwinProviderDrainResult { return this.drainGeneration(pluginName, generation) }
+
+  drainProvider(providerId: string, version?: string, generation?: number): TwinProviderDrainResult {
+    const record = this.findProviderRecords(providerId, version, { generation, allowDraining: true, includeFailed: true })[0]
+    if (!record) throw new TwinProviderRegistryError('PROVIDER_NOT_FOUND', `Provider ${providerId}${version ? `@${version}` : ''} is not registered`)
+    if (record.state !== 'RETIRED') {
+      record.state = record.inFlight > 0 ? 'DRAINING' : 'RETIRED'
+      record.drainingAt ??= new Date().toISOString()
+      if (record.state === 'RETIRED') record.retiredAt = new Date().toISOString()
+      this.updateGenerationState(this.generationOf(record))
+    }
+    return { ok: true, pluginName: record.pluginName, generation: record.generation, state: record.state, inFlight: record.inFlight, retired: record.state === 'RETIRED', providerIds: [record.manifest.providerId] }
+  }
+
+  retireProvider(providerId: string, version: string, generation?: number): TwinProviderRetireResult {
+    const record = this.findProviderRecords(providerId, version, { generation, allowDraining: true, includeFailed: true })[0]
+    if (!record) throw new TwinProviderRegistryError('PROVIDER_NOT_FOUND', `Provider ${providerId}@${version} is not registered`)
+    if (record.state !== 'RETIRED') {
+      record.state = record.inFlight > 0 ? 'DRAINING' : 'RETIRED'
+      record.drainingAt ??= new Date().toISOString()
+      if (record.state === 'RETIRED') record.retiredAt = new Date().toISOString()
+      this.updateGenerationState(this.generationOf(record))
+    }
+    return { ok: true, providerId, version, generation: record.generation, state: record.state, inFlight: record.inFlight, retired: record.state === 'RETIRED' }
+  }
+
+  retire(providerId: string, version: string, generation?: number): TwinProviderRetireResult { return this.retireProvider(providerId, version, generation) }
+
+  clear(): void {
+    this.generations.clear()
+    this.nextGenerationByPlugin.clear()
+    this.leaseSequence = 0
+  }
+
+  private assertProviderKeyAvailable(providerKey: string, pluginName: string, generation: number): void {
+    for (const record of this.generations.values()) {
+      if (record.pluginName === pluginName && record.generation === generation) continue
+      const provider = record.providers.get(providerKey)
+      if (provider && provider.state !== 'RETIRED') throw new TwinProviderRegistryError('PROVIDER_IDENTITY_CONFLICT', `Provider ${providerKey} is already registered by ${record.pluginName} generation ${record.generation}`)
+    }
+  }
+
+  private createLease(record: ProviderRecord): TwinProviderLease {
+    if (record.state === 'RETIRED' || record.state === 'FAILED') return undefined as never
+    record.inFlight++
+    const refId = `twin-provider-ref-${++this.leaseSequence}`
+    let released = false
+    return {
+      refId, provider: record.provider, manifest: record.manifest,
+      lineage: { providerId: record.manifest.providerId, providerVersion: record.manifest.version, providerHash: record.providerHash, pluginName: record.pluginName, generation: record.generation },
+      generation: record.generation,
+      get released() { return released },
+      release: () => {
+        if (released) return
+        released = true
+        record.inFlight = Math.max(0, record.inFlight - 1)
+        if (record.state === 'DRAINING' && record.inFlight === 0) {
+          record.state = 'RETIRED'
+          record.retiredAt = new Date().toISOString()
+        }
+        this.updateGenerationState(this.generationOf(record))
+      },
+    }
+  }
+
+  private findProviderRecords(providerId: string, version?: string, options: ResolveProviderOptions = {}): ProviderRecord[] {
+    const records: ProviderRecord[] = []
+    for (const generation of this.generations.values()) {
+      for (const record of generation.providers.values()) {
+        if (record.manifest.providerId !== providerId || (version && record.manifest.version !== version)) continue
+        if (options.generation != null && record.generation !== options.generation) continue
+        if (record.state === 'RETIRED' || (record.state === 'FAILED' && !options.includeFailed) || (record.state === 'DRAINING' && !options.allowDraining)) continue
+        records.push(record)
+      }
+    }
+    return records.sort((a, b) => b.generation - a.generation || b.registeredAt.localeCompare(a.registeredAt))
+  }
+
+  private toSummary(record: ProviderRecord): TwinProviderSummary {
+    return { providerId: record.manifest.providerId, version: record.manifest.version, providerHash: record.providerHash, pluginName: record.pluginName, pluginVersion: record.pluginVersion, generation: record.generation, state: record.state, health: record.health, inFlight: record.inFlight, registeredAt: record.registeredAt, drainingAt: record.drainingAt, retiredAt: record.retiredAt, manifest: record.manifest }
+  }
+
+  private currentGeneration(pluginName: string): GenerationRecord | undefined {
+    return [...this.generations.values()].filter(record => record.pluginName === pluginName && !['RETIRED', 'FAILED', 'DRAINING'].includes(record.state)).sort((a, b) => b.generation - a.generation)[0]
+  }
+
+  private allocateGeneration(pluginName: string): number {
+    const next = (this.nextGenerationByPlugin.get(pluginName) ?? 0) + 1
+    this.nextGenerationByPlugin.set(pluginName, next)
+    return next
+  }
+
+  private assertGeneration(value: number): number {
+    if (!Number.isInteger(value) || value <= 0) throw new TwinProviderRegistryError('GENERATION_INVALID', `generation must be a positive integer: ${value}`)
+    return value
+  }
+
+  private generationOf(provider: ProviderRecord): GenerationRecord {
+    const generation = this.generations.get(generationKey(provider.pluginName, provider.generation))
+    if (!generation) throw new TwinProviderRegistryError('GENERATION_NOT_FOUND', `Generation ${provider.pluginName}@${provider.generation} no longer exists`)
+    return generation
+  }
+
+  private markGenerationDraining(record: GenerationRecord): void {
+    if (record.state === 'RETIRED') return
+    record.drainingAt ??= new Date().toISOString()
+    for (const provider of record.providers.values()) {
+      if (provider.state === 'READY' || provider.state === 'REGISTERED' || provider.state === 'VALIDATED') {
+        provider.state = provider.inFlight > 0 ? 'DRAINING' : 'RETIRED'
+        provider.drainingAt ??= record.drainingAt
+        if (provider.state === 'RETIRED') provider.retiredAt = new Date().toISOString()
+      }
+    }
+    this.updateGenerationState(record)
+  }
+
+  private updateGenerationState(record: GenerationRecord): void {
+    const providers = [...record.providers.values()]
+    if (providers.length) {
+      if (providers.every(provider => provider.state === 'RETIRED')) {
+        record.state = 'RETIRED'
+        record.retiredAt ??= new Date().toISOString()
+        return
+      }
+      if (providers.some(provider => provider.state === 'DRAINING')) {
+        record.state = 'DRAINING'
+        return
+      }
+      if (providers.every(provider => provider.state === 'FAILED')) {
+        record.state = 'FAILED'
+        return
+      }
+      record.state = 'READY'
+      return
+    }
+    if (record.state === 'DRAINING') {
+      record.state = 'RETIRED'
+      record.retiredAt ??= new Date().toISOString()
+    }
+  }
+
+  private generationState(record: GenerationRecord): ProviderLifecycleState {
+    this.updateGenerationState(record)
+    return record.state
+  }
+}
+
+const twinProviderRegistry = new TwinProviderRegistry()
+
+export function getTwinProviderRegistry(): TwinProviderRegistry {
+  return twinProviderRegistry
+}
+export function registerTwinPluginContribution(pluginName: string, contribution: TwinPluginContribution, generation?: number): TwinProviderRegistrationResult {
+  return twinProviderRegistry.registerTwinPluginContribution(pluginName, contribution, generation)
+}
+export function unregisterTwinPluginContribution(pluginName: string, generation?: number): TwinProviderUnregistrationResult {
+  return twinProviderRegistry.unregisterTwinPluginContribution(pluginName, generation)
+}
+export function listTwinProviders(filter: TwinProviderFilter = {}): TwinProviderSummary[] {
+  return twinProviderRegistry.listProviders(filter)
+}
+export function resolveTwinProvider(providerId: string, versionOrOptions?: string | ResolveProviderOptions, maybeOptions?: ResolveProviderOptions): TwinProviderLease | undefined {
+  return twinProviderRegistry.resolveProvider(providerId, versionOrOptions, maybeOptions)
+}
+export function acquireTwinProvider(providerId: string, versionOrOptions?: string | ResolveProviderOptions, maybeOptions?: ResolveProviderOptions): TwinProviderLease | undefined {
+  return twinProviderRegistry.acquireProvider(providerId, versionOrOptions, maybeOptions)
+}
+export function reloadTwinProviderGeneration(pluginName: string, contribution: TwinPluginContribution, generation?: number): TwinProviderRegistrationResult {
+  return twinProviderRegistry.reloadGeneration(pluginName, contribution, generation)
+}
+export function drainTwinProviderGeneration(pluginName: string, generation: number): TwinProviderDrainResult {
+  return twinProviderRegistry.drainGeneration(pluginName, generation)
+}
+export function retireTwinProvider(providerId: string, version: string, generation?: number): TwinProviderRetireResult {
+  return twinProviderRegistry.retireProvider(providerId, version, generation)
+}
+export function registerTwinPhysicsProvider(provider: TwinPhysicsProvider, source: TwinRegistrationSource = 'core', generation?: number): TwinProviderRegistrationResult {
+  return twinProviderRegistry.registerPhysicsProvider(provider, source, generation)
+}
+export function registerTwinScenePack(pack: ScenePack, source: TwinRegistrationSource = 'core', generation?: number): TwinProviderRegistrationResult {
+  return twinProviderRegistry.registerScenePack(pack, source, generation)
+}
+export function registerTwinSolverAdapter(adapter: SolverAdapter, source: TwinRegistrationSource = 'core', generation?: number): TwinProviderRegistrationResult {
+  return twinProviderRegistry.registerSolverAdapter(adapter, source, generation)
+}
+
+export type { LegacyPhysicsProvider, UniversalPhysicsProvider }