@things-factory/headless-twin 10.0.10 → 10.0.12

package/server/engine/spec-coverage.ts

@@ -25,7 +25,19 @@ export type ForecastQualification =
   | 'calibrated'
 
 export interface SpecCoverageReport {
-  operations: { kind: string; duration: 'measured' | 'declared' | 'default'; variability?: string; parameters: string[] }[]
+  operations: {
+    kind: string
+    duration: 'measured' | 'declared' | 'default'
+    variability?: string
+    parameters: string[]
+    /**
+     * 그 모수를 **무엇으로** 읽었나(`id → measured|declared`) — 없는 id 는 코드 상수를 썼다는 뜻이다.
+     *
+     * 소요시간이 근거를 밝히듯 모수도 밝힌다(2026-08-19): 수율이 이력에서 온 값인지 사람이 적은 값인지
+     * 상수인지에 따라 「불량이 늘었다」는 화면 문장의 무게가 다르다.
+     */
+    parameterBasis?: Record<string, 'measured' | 'declared'>
+  }[]
   /** 이력·계산에서 온 소요(추정기) — 선언값보다 강한 근거. */
   measuredDurations: number
   declaredDurations: number
@@ -40,7 +52,13 @@ export interface SpecCoverageReport {
  * 관측된 작업이 하나도 없으면(`operations` 빈 배열) 판정할 근거가 없으므로 **undefined**(모른다).
  */
 export function classifySpecCoverage(cov: {
-  operations?: { kind: string; duration: 'measured' | 'declared' | 'default'; variability?: string; parameters?: string[] }[]
+  operations?: {
+    kind: string
+    duration: 'measured' | 'declared' | 'default'
+    variability?: string
+    parameters?: string[]
+    parameterBasis?: Record<string, 'measured' | 'declared'>
+  }[]
   measuredDurations?: number
   declaredDurations?: number
   defaultDurations?: number
@@ -51,7 +69,9 @@ export function classifySpecCoverage(cov: {
     kind: o.kind,
     duration: o.duration,
     ...(o.variability ? { variability: o.variability } : {}),
-    parameters: o.parameters ?? []
+    parameters: o.parameters ?? [],
+    /* 근거는 커널이 말한 것만 나른다 — 없으면 필드를 만들지 않는다(상수를 썼다는 뜻이 빈칸이다). */
+    ...(o.parameterBasis && Object.keys(o.parameterBasis).length ? { parameterBasis: o.parameterBasis } : {})
   }))
   const measuredDurations = cov.measuredDurations ?? operations.filter(o => o.duration === 'measured').length
   const declaredDurations = cov.declaredDurations ?? operations.filter(o => o.duration === 'declared').length

package/server/engine/twin-engine.ts

@@ -21,6 +21,8 @@ import { applyDeclarationLayers } from './local-declarations.js'
 import { isOfDomain, parseRuntimeKey, runtimeKey } from './runtime-key.js'
 import { routeCommand } from './command-routing.js'
 import { TwinInstance } from '../service/twin-instance/twin-instance.js'
+/* 자극의 집은 원본이다(ADR-0029) — 그 행을 읽고 쓴다. */
+import { TwinReference } from '../service/reference/twin-reference.js'
 import { TwinStructure } from '../service/twin-structure/twin-structure.js'
 import { TwinSpace } from '../service/twin-space/twin-space.js'
 import { utcOffsetOf } from '../service/reference/reference-master.js'
@@ -33,6 +35,9 @@ import { type IngestWarning, describeWarnings, unresolvedReference, projectionFa
 import { projectStructure } from '../service/twin-model/project-structure.js'
 import { buildTravelEstimator, chainEstimators } from './travel-estimator.js'
 import { buildMeasuredEstimator } from './measured-estimator.js'
+import { buildYieldEstimator } from './measured-yield.js'
+import { planStimulus, withStimulus } from './declared-stimulus.js'
+import { readRestartPolicy, type RestartPolicy } from './restart-policy.js'
 import { describeModelBasis, type ModelBasis } from './model-basis.js'
 import { computeTwinKpi } from './kpi-query.js'
 import { createHash } from 'node:crypto'
@@ -49,7 +54,7 @@ import { EMS_PROPERTY } from '@operato/twin-kernel'
 import type { TwinKernel, TwinModelDef, StructureShift, SubscriptionMessage, TwinRuntime as TwinRuntimeType, CanonicalEnvelope } from '@operato/twin-kernel'
 
 /* 커널 런타임 로드 — CJS 번들(dist-cjs). 타입은 위 import type 로. replay = 이벤트열→상태 재구성(복구·시간여행). */
-const { WmsKernel, YmsKernel, MesKernel, EmsKernel, TwinRuntime, StateProjector, replay, replayFrom, replayWithCheckpoint, replaySegments, readBoardLocations, readBoardEquipment, DOMAIN_CATALOG, OP_EVENT } = require('@operato/twin-kernel')
+const { WmsKernel, YmsKernel, MesKernel, EmsKernel, TwinRuntime, StateProjector, replay, replayFrom, replayWithCheckpoint, replaySegments, readBoardLocations, readBoardEquipment, DOMAIN_CATALOG, OP_EVENT, validateScenario } = require('@operato/twin-kernel')
 
 const KERNELS: Record<string, any> = { wms: WmsKernel, yms: YmsKernel, mes: MesKernel, ems: EmsKernel }
 
@@ -86,19 +91,19 @@ interface TwinMetrics {
 }
 
 /*
- * realityMode — 이 트윈의 "현실이 어디서 오나"(runtime-state-model §0·§1 프레임의 ① 선언).
- * 부팅 거동을 결정하는 1급 선언: mirror=외부 실물 재동기 / sim-world=생성 타임라인 지속(resume) / sim-experiment=seed 재현(reset).
- * 미선언 = 'sim-experiment'(가장 보수적 — 기존 데모 거동 보존).
+ * 재기동 정책은 **선언이고 기본값이 없다** — 정의·판정은 `engine/restart-policy.ts` 가 든다(ADR-0029 §2).
+ *
+ * 예전에는 여기에 `DEFAULT_REALITY_MODE = 'sim-experiment'` 가 있었고, 미선언이 조용히 **저널 초기화**로
+ * 떨어졌다. 그 관용은 값이 하나 어긋나는 순간 이력을 지우는 길이 된다 — 그래서 없앴다.
  */
-export type RealityMode = 'mirror' | 'sim-world' | 'sim-experiment'
-export const DEFAULT_REALITY_MODE: RealityMode = 'sim-experiment'
+export type { RestartPolicy } from './restart-policy.js'
 
 /* 인메모리 라이브 런타임 홀더(영속 엔티티 TwinInstance 와 구분). */
 interface InstanceRuntime {
   /** 부하 계기판 — 작업별 소요. 시뮬·라이브 모두 붙는다(누가 루프를 점유하는지 보려면 둘 다 필요하다). */
   load?: LoadMeter
   /** 현실 출처 선언(§0 프레임 ①). 부팅 거동(reset/resume/resync)의 근거. */
-  realityMode?: RealityMode
+  restartPolicy?: RestartPolicy
   id: string
   domainId: string
   domain?: any // 라이브 바인딩(data 채널)용 Domain 객체(subdomain 필터). start 시 비동기 해석.
@@ -400,7 +405,7 @@ export class TwinEngine {
    *
    * ── 모드를 지어내지 않는다 ──────────────────────────────────────────────────
    * 미러였던 트윈을 시뮬로 되살리면 **없던 움직임을 만들어 낸다**(관측 트윈이 스스로 물건을 옮긴다).
-   * 그래서 선언된 `realityMode` 그대로 되살린다 — 미러는 관측 구동으로, 시뮬은 시뮬로.
+   * 그래서 선언된 `restartPolicy` 그대로 되살린다 — 미러는 관측 구동으로, 시뮬은 시뮬로.
    *
    * ── 되살릴 수 없으면 그렇게 적는다 ──────────────────────────────────────────
    * 실패를 삼키면 등록부가 계속 `running` 이라 말한다 — 우리가 고치려던 그 거짓말이다. 그래서 실패한
@@ -422,7 +427,7 @@ export class TwinEngine {
     }
 
     try {
-      if (row.realityMode === 'mirror') {
+      if (row.restartPolicy === 'resync') {
         if (!row.model) throw new Error('no model')
         /* 시각 기준은 **공간**이 갖는다 — 교대의 HH:MM 을 어느 기준으로 읽나(라이브 기동과 같은 규칙). */
         this.startLive(instanceId, domainId, row.kind, await this.withSpaceTimeBase(row.model as TwinModelDef, domainId))
@@ -431,7 +436,7 @@ export class TwinEngine {
         console.log(`[twin-engine] resumed mirror "${instanceId}" — feed reattach is the reference layer's job.`)
       } else {
         await this.startFromRegistry(domainId, instanceId)
-        console.log(`[twin-engine] resumed ${row.realityMode} "${instanceId}".`)
+        console.log(`[twin-engine] resumed ${row.restartPolicy} "${instanceId}".`)
       }
     } catch (err: any) {
       await this.markStopped(row, err?.message ?? 'resume failed')
@@ -548,6 +553,22 @@ export class TwinEngine {
         }
       }
     }
+    /* 공정 모수(수율·셋업)도 같은 규율로 싣는다 — 커널이 그 창구를 갖지 않으면 그 사실을 말한다. */
+    const params = model?.localParams as Record<string, Record<string, string>> | undefined
+    if (params && Object.keys(params).length) {
+      if (typeof kernel?.declareParameters !== 'function') {
+        console.warn(
+          `[twin-engine] "${id}": this facility declared operation parameters for ${Object.keys(params).length} operation(s) but the kernel cannot consume them ` +
+            '(declareParameters missing — kernel needs publishing). Yield and setup keep running on built-in constants.'
+        )
+      } else {
+        try {
+          kernel.declareParameters(params)
+        } catch (err: any) {
+          console.warn(`[twin-engine] "${id}": declared operation parameter rejected by the kernel — ${err?.message ?? err}`)
+        }
+      }
+    }
     const ops = model?.operations
     if (!ops?.length) return
     if (typeof kernel?.loadOperations !== 'function') {
@@ -580,6 +601,35 @@ export class TwinEngine {
       return
     }
     kernel.durationEstimator = chained
+    /*
+     * **양품률도 이력에서 배운다** (2026-08-19) — 소요와 같은 자리에서 붙인다.
+     *
+     * 커널이 그 시임을 갖지 않은 버전이면(발행 이전) 조용히 넘어가지 않고 말한다: 수율이 상수로 남은
+     * 이유를 모르고 지나가면, 화면의 불량 판정이 그 현장의 사실이 아니라 우리 상수의 결과다.
+     */
+    const yields = await this.measuredYield(domainId, instanceId)
+    if (yields?.estimator) {
+      if (typeof kernel.yieldOf !== 'function') {
+        console.warn(
+          `[twin-engine] "${instanceId}": learned yield for ${Object.keys(yields.learned).length} operation kind(s) but the kernel cannot consume it ` +
+            '(yieldOf missing — kernel needs publishing). Yield keeps running on the declared value or the built-in constant.'
+        )
+      } else {
+        kernel.yieldEstimator = yields.estimator
+        console.log(
+          `[twin-engine] "${instanceId}": measured yield installed — ${Object.entries(yields.learned)
+            .map(([k, v]) => `${k}=${Math.round(v * 1000) / 10}%(${yields.samples[k].good + yields.samples[k].scrap}건)`)
+            .join(', ')}${yields.skipped.length ? ` · 표본 부족으로 뺀 종류: ${yields.skipped.map(s => `${s.kind}(${s.judged})`).join(', ')}` : ''}`
+        )
+      }
+    } else if (yields?.skipped.length) {
+      /* 배운 것이 없고 버린 것만 있으면 그 사실도 말한다 — 「이력이 없다」와 「표본이 모자라다」는 다르다. */
+      console.log(
+        `[twin-engine] "${instanceId}": no measured yield yet — samples below ${yields.minSamples}: ${yields.skipped
+          .map(s => `${s.kind}(${s.judged})`)
+          .join(', ')}`
+      )
+    }
     const learned = Object.keys(measured?.learned ?? {})
     const spread = Object.keys(measured?.spreads ?? {})
     console.log(
@@ -596,7 +646,15 @@ export class TwinEngine {
    * 거기에 KPI 조회를 그대로 달면 요청당 저널 스캔이 하나씩 붙는다 — 실측은 분 단위로 바뀌지 않으므로
    * 짧은 TTL 로 재사용한다. 캐시는 인스턴스별이고, 만료 전에는 같은 값을 쓴다(예측 간 일관성도 얻는다).
    */
-  private static measuredCache = new Map<string, { at: number; value: ReturnType<typeof buildMeasuredEstimator> | undefined }>()
+  private static measuredCache = new Map<
+    string,
+    {
+      at: number
+      value: ReturnType<typeof buildMeasuredEstimator> | undefined
+      /** 같은 폴드에서 나온 양품률 — **저널을 두 번 접지 않는다**(소요와 수율은 같은 창의 같은 사실이다). */
+      yields?: ReturnType<typeof buildYieldEstimator>
+    }
+  >()
   private static readonly MEASURED_TTL_MS = 60_000
   /**
    * 캐시 항목 상한 — **라이프사이클이 놓친 것까지 막는 두 번째 방어.**
@@ -613,22 +671,31 @@ export class TwinEngine {
    */
   private static readonly MEASURED_MAX = 5_000
 
+  /** 이 트윈이 이력에서 배운 양품률 — 소요와 **같은 폴드·같은 캐시**에서 온다(저널을 두 번 접지 않는다). */
+  private static async measuredYield(domainId: string, instanceId: string) {
+    await this.measuredEstimator(domainId, instanceId)
+    return this.measuredCache.get(runtimeKey(domainId, instanceId))?.yields
+  }
+
   private static async measuredEstimator(domainId: string, instanceId: string) {
     /* 키는 `runtimeKey` 하나로 — 손으로 조립하면 지우는 쪽과 어긋나 못 지우는 항목이 생긴다. */
     const key = runtimeKey(domainId, instanceId)
     const hit = this.measuredCache.get(key)
     if (hit && Date.now() - hit.at < this.MEASURED_TTL_MS) return hit.value
     let value: ReturnType<typeof buildMeasuredEstimator> | undefined
+    let yields: ReturnType<typeof buildYieldEstimator> | undefined
     try {
       /* 작업 종류별 실측 — 창은 넉넉히(하루) 두고 표본이 모자란 종류는 추정기가 스스로 뺀다. */
       const kpi: any = await computeTwinKpi({ domainId, instanceId, windowMinutes: 24 * 60, groupBy: 'taskKind' })
       value = buildMeasuredEstimator(kpi?.groups?.items, {})
+      /* 같은 그룹에서 양품률도 배운다 — 한 번 접은 저널을 둘이 나눠 쓴다. */
+      yields = buildYieldEstimator(kpi?.groups?.items, {})
     } catch (err) {
       console.warn(`[twin-engine] "${instanceId}": measured duration lookup failed — falling back to declared/default durations.`, (err as any)?.message)
     }
     /* 다시 넣어 **최근 쓴 것**으로 만든다 — 삽입 순서가 곧 버릴 순서이므로 이 한 줄이 LRU 를 만든다. */
     this.measuredCache.delete(key)
-    this.measuredCache.set(key, { at: Date.now(), value })
+    this.measuredCache.set(key, { at: Date.now(), value, yields })
     if (this.measuredCache.size > this.MEASURED_MAX) {
       const oldest = this.measuredCache.keys().next()
       if (!oldest.done) this.measuredCache.delete(oldest.value)
@@ -636,6 +703,68 @@ export class TwinEngine {
     return value
   }
 
+  /**
+   * **원본이 선언한 자극을 싣는다** — 재기동해도 살아 있게 (2026-08-19).
+   *
+   * ── 무엇이 났나 ────────────────────────────────────────────────────────────
+   * 데모의 시나리오는 시드 코드가 메모리에만 실었다. 그래서 트윈을 재기동하면 자극이 사라지고 구조만
+   * 서 있는 트윈이 남았다(작업 0·오더 0) — 「살아 있는 데모」가 **첫 재기동까지만** 살았다.
+   *
+   * 자극의 집은 **원본**이다(`TwinReference.connectionConfig.scenario`, ADR-0029 ·
+   * `plans/simulator-as-source.md` §4): 무엇이 들어오고 무슨 주문이 나는지는 시뮬레이터가 정하는 사실이고
+   * 트윈은 반영한다. 트윈에 새 축을 만들면 ADR-0029 가 걷어내야 할 표면이 하나 늘어난다.
+   *
+   * 판정은 순수 함수가 한다(`planStimulus`) — 미러에 싣지 않고, 검사를 통과하지 못한 선언은 태우지 않고
+   * (그 이력이 있다: 잘못된 선언 하나가 다음 틱에서 서버를 내렸다), 못 실은 이유는 **말한다.**
+   */
+  private static async installStimulus(domainId: string, instanceId: string, inst: InstanceRuntime): Promise<void> {
+    let config: any
+    try {
+      const ref = await getRepository(TwinReference).findOne({ where: { domain: { id: domainId }, source: instanceId } })
+      config = ref?.connectionConfig
+    } catch (err: any) {
+      console.warn(`[twin-engine] "${instanceId}": could not read the declared stimulus — ${err?.message ?? err}`)
+      return
+    }
+    const plan = planStimulus(config, { hasScenarioEngine: !!inst.runtime?.scenario, mode: inst.mode }, validateScenario as any)
+    if (plan.action === 'skip') {
+      /* 선언이 없는 것은 정상이므로 조용히 지난다. 나머지 셋은 **말한다** — 선언했는데 안 실린 상태다. */
+      if (plan.reason !== 'none') {
+        console.warn(
+          `[twin-engine] "${instanceId}": a stimulus is declared on its source but was not loaded (${plan.reason}${plan.detail ? `: ${plan.detail}` : ''}).` +
+            (plan.reason === 'observed' ? ' This twin runs on observation — we do not manufacture arrivals for it.' : '')
+        )
+      }
+      return
+    }
+    try {
+      inst.runtime!.scenario.load(plan.scenario)
+      inst.runtime!.scenario.start()
+      const kinds = (plan.scenario.generators ?? []).map((g: any) => g?.kind).filter(Boolean)
+      console.log(`[twin-engine] "${instanceId}": stimulus from its source started — ${kinds.length ? kinds.join(', ') : 'no generators'}.`)
+    } catch (err: any) {
+      console.warn(`[twin-engine] "${instanceId}": the declared stimulus was rejected at load — ${err?.message ?? err}`)
+    }
+  }
+
+  /**
+   * 자극을 **원본에 선언한다** — 프로비저닝·데모 시드가 부르는 문.
+   *
+   * 트윈이 아니라 원본에 적는 이유는 위와 같다(ADR-0029). 원본 행이 없으면 만들지 않는다 — 어떤 원본에서
+   * 온 트윈인지 모르는 채 자극을 지어 붙이면, 그 자극이 어디서 왔는지 아무도 되짚을 수 없다.
+   */
+  static async declareStimulus(domainId: string, instanceId: string, scenario: any): Promise<boolean> {
+    const repo = getRepository(TwinReference)
+    const ref = await repo.findOne({ where: { domain: { id: domainId }, source: instanceId } })
+    if (!ref) {
+      console.warn(`[twin-engine] "${instanceId}": no source reference — a stimulus has nowhere to be declared.`)
+      return false
+    }
+    ref.connectionConfig = withStimulus(ref.connectionConfig, scenario)
+    await repo.save(ref)
+    return true
+  }
+
   /**
    * 이 트윈이 **이력에서 시간을 배운 작업 종류들** — 재기동에도 남는 근거.
    *
@@ -769,7 +898,7 @@ export class TwinEngine {
     console.log(`[twin-engine] mirror "${id}" carried over ${carried} — observation axes come from the source.`)
   }
 
-  static start(id: string, domainId: string, kind: string, model: TwinModelDef, realityMode?: RealityMode, purpose?: string, resumeFrom?: number): InstanceRuntime {
+  static start(id: string, domainId: string, kind: string, model: TwinModelDef, restartPolicy?: RestartPolicy, purpose?: string, resumeFrom?: number): InstanceRuntime {
     const key = runtimeKey(domainId, id)
     if (this.instances[key]) return this.instances[key]
 
@@ -808,11 +937,23 @@ export class TwinEngine {
      * 실제로는 도는 커널이 옛 수를 그대로 쓰고 재기동 때 받는데, 그 사실이 답에서 사라진 것이다.
      * 규약에 기대는 대신 사실을 적는다: 「돌고 있나」를 묻는 쪽이 그 답을 받아야 한다.
      */
-    const inst: InstanceRuntime = { id, domainId, mode: 'sim', runtime, kernel, realityMode: realityMode ?? DEFAULT_REALITY_MODE, spaceId: (model as any)?.spaceId, unsub: () => {} }
+    const inst: InstanceRuntime = {
+      id,
+      domainId,
+      mode: 'sim',
+      runtime,
+      kernel,
+      /* 정책은 부르는 쪽이 선언한다 — 여기서 고르면 같은 트윈이 부르는 자리에 따라 다르게 재기동한다. */
+      restartPolicy: readRestartPolicy(restartPolicy, `start("${id}")`),
+      spaceId: (model as any)?.spaceId,
+      unsub: () => {}
+    }
     this.instances[key] = inst
     /* 다시 세웠으므로 지난 정지 이유는 사실이 아니다 — 남겨 두면 도는 트윈이 「굶겨서 멈췄다」고 말한다. */
     this.stopNotes.delete(key)
     delete this.recovered[key] // 웜스타트로 커널에 옮겨 심었다 — 이제 라이브가 진실이다.
+    /* 원본이 선언한 자극 — 기동을 막지 않는다(추정기와 같은 규율). 못 실었으면 그 사실을 말한다. */
+    this.installStimulus(domainId, id, inst).catch(err => console.warn(`[twin-engine] "${id}": stimulus install failed — ${err?.message ?? err}`))
 
     /* 라이브 바인딩(P3): data 채널 필터가 subdomain 을 보므로 Domain 객체를 1회 해석해 둔다. */
     getRepository(Domain).findOne({ where: { id: domainId } }).then(d => (inst.domain = d)).catch(() => {})
@@ -845,8 +986,8 @@ export class TwinEngine {
     })
     inst.unsub = () => sub.unsubscribe()
 
-    /* 복구 앵커: 레지스트리에 model/kind/status/realityMode 영속(재부팅 시 이게 있어야 replay·선언 거동 가능). */
-    this.register(domainId, id, kind, model, 'running', inst.realityMode).catch(err => console.error('twin register fail', err))
+    /* 복구 앵커: 레지스트리에 model/kind/status/restartPolicy 영속(재부팅 시 이게 있어야 replay·선언 거동 가능). */
+    this.register(domainId, id, kind, model, 'running', inst.restartPolicy).catch(err => console.error('twin register fail', err))
 
     /* 워커 tick — 스켈레톤은 setInterval(메인 루프). 긴 시뮬 오프-루프(worker thread)는 스케일 하드닝(향후, §host 경계). */
     inst.timer = setInterval(() => this.tickGuarded(domainId, id, runtime), this.TICK_MS)
@@ -932,7 +1073,7 @@ export class TwinEngine {
     /* `projector` 필드는 옛 이름으로 남긴다 — 소비처가 `snapshot()` 을 부르므로 얇은 어댑터로 잇는다.
      * (P3 에서 소비처를 커널 어휘로 바꾸면 사라진다.) */
     const projector = { apply: (e: CanonicalEnvelope) => kernel.apply(e), snapshot: () => kernel.getSnapshot() }
-    const inst: InstanceRuntime = { id, domainId, mode: 'live', realityMode: 'mirror', kernel, projector, oee: new OeeAccumulator(), spaceId: (model as any)?.spaceId, unsub: () => {} }
+    const inst: InstanceRuntime = { id, domainId, mode: 'live', restartPolicy: 'resync', kernel, projector, oee: new OeeAccumulator(), spaceId: (model as any)?.spaceId, unsub: () => {} }
     /*
      * ── 커널이 **판정으로 낸 사실**도 저널에 남는다 (2026-08-14 실측으로 잡음) ────
      *
@@ -960,6 +1101,8 @@ export class TwinEngine {
     this.installEstimators(kernel, domainId, id, model).catch(err => console.warn('[twin-engine] estimator install failed', err?.message))
     inst.metrics = { ingestedTotal: 0, broadcastTotal: 0, journaledTotal: 0, ingestRate: 0, broadcastRate: 0, journalRate: 0, backlog: 0, _accIngest: 0, _accBroadcast: 0, _accJournal: 0, _windowStartMs: Date.now() }
     this.instances[key] = inst
+    /* 미러에도 부른다 — 선언이 있으면 「미러에는 싣지 않는다」고 말해야 한다(조용한 무시 금지). */
+    this.installStimulus(domainId, id, inst).catch(err => console.warn(`[twin-engine] "${id}": stimulus check failed — ${err?.message ?? err}`))
     /*
      * **원천이 되풀어 주지 않는 것만 잇는다** (2026-08-18 실측으로 붙임).
      *
@@ -980,7 +1123,7 @@ export class TwinEngine {
       .findOne({ where: { domain: { id: domainId }, instanceId: id }, order: { revision: 'DESC' } })
       .then(top => (inst.revision = top?.revision ?? 0))
       .catch(() => (inst.revision = 0))
-    this.register(domainId, id, kind, model, 'running', 'mirror').catch(err => console.error('twin register fail', err))
+    this.register(domainId, id, kind, model, 'running', 'resync').catch(err => console.error('twin register fail', err))
     return inst
   }
 
@@ -1155,7 +1298,7 @@ export class TwinEngine {
     kind: string,
     model: TwinModelDef,
     status: 'running' | 'stopped' = 'running',
-    realityMode?: RealityMode,
+    restartPolicy?: RestartPolicy,
     origin?: any,
     /*
      * 사람이 부르는 이름과 **누가 했나** — 업무키를 나눠 둔 대가로 이름을 함께 실어야 한다.
@@ -1176,10 +1319,15 @@ export class TwinEngine {
         // 인스턴스↔공간 1급 링크(space #3) — model.spaceId/areaId 를 컬럼으로 승격(dual-write). model JSON 도 유지(커널·복구용).
         spaceId: (model as any)?.spaceId ?? existing?.spaceId,
         areaId: (model as any)?.areaId ?? existing?.areaId,
-        /* 현실 출처 선언(§0 ①) — 명시값 우선, 없으면 기존값 보존(재프로비전이 선언을 지우지 않게).
-           둘 다 없으면 여기서 **각인한다**. 컬럼을 비워 두면 읽는 자리마다 기본값을 고르게 되고,
-           그러면 같은 트윈이 부르는 곳에 따라 다르게 재기동한다. 선언은 저장소에서 항상 명시적이다. */
-        realityMode: realityMode ?? existing?.realityMode ?? DEFAULT_REALITY_MODE,
+        /* 재기동 정책(ADR-0029 §2) — 명시값 우선, 없으면 기존값 보존(재프로비전이 선언을 지우지 않게).
+           **둘 다 없으면 던진다**: 예전에는 여기서 기본값을 각인했는데, 그 기본값이 「저널 초기화」라서
+           선언을 빠뜨린 프로비저닝이 조용히 이력을 지우는 트윈을 만들었다. 선언은 부르는 쪽의 몫이다. */
+        restartPolicy:
+          restartPolicy ??
+          readRestartPolicy(
+            existing?.restartPolicy,
+            `register("${instanceId}") did not declare a restart policy and the stored row has none`
+          ),
         /* 용도도 각인한다. 벤치로 뒤집는 것은 `setPurpose` 하나뿐이므로 기존값을 반드시 보존한다
            — 여기서 덮으면 재프로비전이 벤치 사본을 운영 트윈으로 되돌린다. */
         purpose: existing?.purpose ?? 'operational',
@@ -1327,6 +1475,14 @@ export class TwinEngine {
     instanceId: string,
     kind: string,
     model: TwinModelDef,
+    /**
+     * **재기동 정책은 생성 시점의 선언이다**(ADR-0029 §2) — 트윈은 정책 없이 존재할 수 없다.
+     *
+     * 예전에는 이 자리가 없었고 `register` 가 기본값(`sim-experiment` = 저널 초기화)을 각인했다. 그래서
+     * 선언을 빠뜨린 프로비저닝이 **재기동마다 이력을 지우는 트윈**을 조용히 만들었다. 이제 만드는 쪽이
+     * 말해야 한다: 이 트윈이 자기 과거를 어떻게 대하는지는 만드는 사람이 아는 사실이다.
+     */
+    restartPolicy: RestartPolicy,
     comment?: string,
     origin?: any,
     /** 이름·저자 — 업무키를 나눠 둔 대가로 이름을 함께 남긴다(`register` 의 `meta` 그대로). */
@@ -1351,7 +1507,7 @@ export class TwinEngine {
      * 달고 다닌다. 재생은 구조가 바뀌는 지점에서 전환한 뒤 이어 접는다(`replaySegments`).
      */
     await this.recordStructure(domainId, instanceId, model, comment)
-    await this.register(domainId, instanceId, kind, model, existing?.status === 'running' ? 'stopped' : (existing?.status as any) ?? 'stopped', undefined, origin, meta)
+    await this.register(domainId, instanceId, kind, model, existing?.status === 'running' ? 'stopped' : (existing?.status as any) ?? 'stopped', restartPolicy, origin, meta)
   }
 
   /**
@@ -1464,7 +1620,7 @@ export class TwinEngine {
   }
 
   /** 레지스트리 model 로 기동(프로비전된 인스턴스 start). model 인자 없이 저장된 구조로 재기동. */
-  static async startFromRegistry(domainId: string, instanceId: string, realityMode?: RealityMode): Promise<InstanceRuntime> {
+  static async startFromRegistry(domainId: string, instanceId: string, restartPolicy?: RestartPolicy): Promise<InstanceRuntime> {
     const key = runtimeKey(domainId, instanceId)
     if (this.instances[key]) return this.instances[key]
     const reg = await getRepository(TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId } })
@@ -1490,7 +1646,7 @@ export class TwinEngine {
     /*
      * 저널에 남아 있는 마지막 번호 — **모드와 무관하게** 이것을 이어 센다.
      *
-     * 저널을 초기화하고 기동하는 모드(sim-experiment)라면 이 값이 0이라 아무 영향이 없다. 규칙을
+     * 저널을 초기화하고 기동하는 정책(`reset`)이라면 이 값이 0이라 아무 영향이 없다. 규칙을
      * 모드별로 구분하지 않는 이유: "저널이 비어 있지 않으면 그 뒤부터" 하나면 어느 모드에서도
      * 겹칠 수 없고, 모드가 늘어도 이 자리를 다시 손볼 일이 없다.
      */
@@ -1508,29 +1664,30 @@ export class TwinEngine {
          메웠는데, 그건 YMS/MES 트윈을 **조용히 WMS 로 부팅**시키는 길이었다 — 오류 없이 다른 공장이 뜬다. */
       reg.kind,
       reg.model as TwinModelDef,
-      realityMode ?? (reg.realityMode as RealityMode),
+      /* 저장된 값은 **엄격히** 읽는다 — 모르는 값을 기본값으로 메우면 그 트윈이 조용히 다르게 재기동한다. */
+      restartPolicy ?? readRestartPolicy(reg.restartPolicy, `twin "${instanceId}"`),
       reg.purpose,
       Number(last?.max ?? 0) || 0
     )
   }
 
   /**
-   * 선언 기반 부팅(§0 프레임 ① → 부팅 거동 매핑) — 트윈이 선언한 realityMode 에 따라 재기동 방식을 구분한다.
+   * 선언 기반 부팅(§0 프레임 ① → 부팅 거동 매핑) — 트윈이 선언한 restartPolicy 에 따라 재기동 방식을 구분한다.
    * 부팅 경로를 한 곳에 모아 "런타임 ≠ 현실" 범주오류를 코드로 강제한다.
-   *   - 'mirror'         : 현실=외부 실물 → startLive(재동기). 이벤트는 어댑터 ingest 로 유입, 커널 tick 없음.
-   *   - 'sim-world'      : 생성 타임라인 지속 → 저널 보존 + resume(현실 이어감).
+   *   - 'resync'         : 현실=외부 실물 → startLive(재동기). 이벤트는 어댑터 ingest 로 유입, 커널 tick 없음.
+   *   - 'resume'      : 생성 타임라인 지속 → 저널 보존 + resume(현실 이어감).
    *                        ⚠ GATE(§8 ②③): 커널 상태 직렬화/재개가 아직 없어 진짜 resume 불가 → 실 필요·실부하 시 구현.
    *                        그때까지는 저널을 보존하되 revision 충돌을 피하려 fresh 로 기동하고, 선언과 구현의 간극을 크게 경고한다.
-   *   - 'sim-experiment' : seed 재현 → resetJournal + fresh 기동(백지 시작이 버그가 아니라 선언된 거동).
+   *   - 'reset' : seed 재현 → resetJournal + fresh 기동(백지 시작이 버그가 아니라 선언된 거동).
    * 반환: 기동된 InstanceRuntime.
    */
-  static async bootDeclared(domainId: string, instanceId: string, mode: RealityMode = DEFAULT_REALITY_MODE): Promise<InstanceRuntime> {
-    if (mode === 'mirror') {
+  static async bootDeclared(domainId: string, instanceId: string, mode: RestartPolicy): Promise<InstanceRuntime> {
+    if (mode === 'resync') {
       const reg = await getRepository(TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId } })
       if (!reg?.model) throw new Error(`instance "${instanceId}" not provisioned (no model)`)
       return this.startLive(instanceId, domainId, reg.kind, reg.model as TwinModelDef)
     }
-    if (mode === 'sim-world') {
+    if (mode === 'resume') {
       /*
        * **이어지는 현실** — 저널을 지우지 않는다.
        *
@@ -1543,11 +1700,11 @@ export class TwinEngine {
        * 같은 씨앗에서 다시 시작하므로 자극의 패턴이 재기동 지점에서 한 번 끊긴다. 쌓인 사실과
        * 상태는 이어지고, 앞으로 일어날 일의 무작위 순서만 새로 시작한다.
        */
-      return this.startFromRegistry(domainId, instanceId, 'sim-world')
+      return this.startFromRegistry(domainId, instanceId, 'resume')
     }
-    // sim-experiment(기본): seed 재현 — 저널 초기화 후 revision 0 부터 재실행.
+    // `reset`: seed 재현 — 저널 초기화 후 revision 0 부터 재실행.
     await this.resetJournal(domainId, instanceId)
-    return this.startFromRegistry(domainId, instanceId, 'sim-experiment')
+    return this.startFromRegistry(domainId, instanceId, 'reset')
   }
 
   /**
@@ -1637,7 +1794,7 @@ export class TwinEngine {
         spaceId: r.spaceId, // co-location: 같은 spaceId 인스턴스들이 한 현장 공유 — 현장뷰 집약 키(G7)
         /* 사람이 읽는 현장 이름 — 없으면 `undefined`(화면이 "이름 없음" 을 알아볼 수 있어야 한다). */
         spaceName: (r.spaceId ? spaceNameOf.get(r.spaceId) : undefined) || undefined,
-        realityMode: r.realityMode, // 현실 출처 선언(§0 ①) — mirror/sim-world/sim-experiment. 저장 시 각인되므로 비지 않는다.
+        restartPolicy: r.restartPolicy, // 재기동 정책(ADR-0029 §2) — resync/resume/reset. 선언이므로 비어 있을 수 없다.
         purpose: r.purpose, // 운영 vs 벤치 사본(1급 구별 — 이름 접두사 아님). 저장 시 각인되므로 비지 않는다.
         copyOf: r.copyOf ?? undefined,
         running: !!this.instances[runtimeKey(domainId, r.instanceId)],
@@ -1651,7 +1808,7 @@ export class TwinEngine {
         /* 스스로 멈춘 이유 — 있으면 낸다. 재기동 뒤에는 없다(그때는 「모른다」가 사실이다). */
         stopNote: this.stopNotes.get(runtimeKey(domainId, r.instanceId)) || undefined,
         liveFeed: liveFeedStateOf({
-          realityMode: r.realityMode,
+          restartPolicy: r.restartPolicy,
           running: !!this.instances[runtimeKey(domainId, r.instanceId)],
           instanceId: r.instanceId
         }),
@@ -1744,6 +1901,8 @@ export class TwinEngine {
   static async ingestMaster(
     domainId: string,
     master: ReferenceMaster,
+    /** 만들어지는 트윈의 재기동 정책 — 원본이 정하는 것이 아니라 **만드는 쪽의 선언**이다(ADR-0029 §2). */
+    restartPolicy: RestartPolicy,
     into?: { spaceId?: string },
     /** 누가 인제스트했나 — 사람이 없는 경로(부팅)는 주지 않는다(감사 기록을 지어내지 않는다). */
     actor?: { id: string }
@@ -1914,7 +2073,7 @@ export class TwinEngine {
       warnings.push(structureAdopted(shift.rev, shift))
     } else {
       /* 사이트 이름이 곧 트윈의 이름이다 — 마스터가 이미 말했으므로 지어내지 않고 그대로 싣는다. */
-      await this.provision(domainId, master.source, master.system, model, undefined, master.origin, {
+      await this.provision(domainId, master.source, master.system, model, restartPolicy, undefined, master.origin, {
         name: master.siteName,
         description: (master as any).description,
         actor
@@ -1960,7 +2119,7 @@ export class TwinEngine {
       kind: r.kind,
       status: r.status,
       running: !!this.instances[runtimeKey(domainId, r.instanceId)],
-      realityMode: r.realityMode, // 현실 선언 — what-if 적용 가드용(mirror=예측 전용, 자극 주입 불가)
+      restartPolicy: r.restartPolicy, // 현실 선언 — what-if 적용 가드용(mirror=예측 전용, 자극 주입 불가)
       model: r.model
     }
   }
@@ -2652,7 +2811,7 @@ export class TwinEngine {
       mode: inst.mode ?? 'sim',
       domainId: inst.domainId,
       domainLabel: inst.domain?.subdomain,
-      realityMode: inst.realityMode,
+      restartPolicy: inst.restartPolicy,
       tickMs: this.TICK_MS,
       running: !!inst.timer || inst.mode === 'live',
       ...(loadSummary(inst.load, this.TICK_MS) ?? { recent: null, total: null, forksCreated: 0, overBudget: 0, budgetMs: this.TICK_MS * 0.5, loadRatio: null })

package/server/index.ts

@@ -11,7 +11,7 @@ import { resumeReferenceLiveFeeds } from './service/reference/reference-live.js'
 /*
  * 모듈 부팅 — **도는 트윈을 되살린다.**
  *
- * 두 층이 순서대로다: ① 엔진이 등록부의 `running` 행을 선언된 `realityMode` 그대로 되살리고
+ * 두 층이 순서대로다: ① 엔진이 등록부의 `running` 행을 선언된 `restartPolicy` 그대로 되살리고
  * (`bootstrap`), ② 레퍼런스 계층이 미러 트윈의 커넥터 피드를 다시 붙인다. 순서가 뒤집히면 피드가
  * 아직 없는 커널에 계측을 붓게 된다.
  *

package/server/service/reference/control-routing.ts

@@ -0,0 +1,62 @@
+/*
+ * **구동은 원본을 지난다** — 트윈을 우회하지 않는다 (ADR-0029 §8, 2026-08-19).
+ *
+ * ── 무엇이 뚫려 있었나 ──────────────────────────────────────────────────────
+ * `controlTwinScenario` 가 `TwinEngine.runtime(...).scenario` 를 **직접** 잡았다. 그래서 시뮬만 할 수 있는
+ * 일(자극·배속·정지)이 계약 밖의 지름길로 들어왔고, 실 시스템에는 그 자리가 아예 없었다 — ADR-0029 의
+ * 판정 문장에 걸리는 상태였다.
+ *
+ * 이제 길은 하나다: **트윈 → 그 트윈의 원본 → 어댑터가 선언한 `control` 능력.** 선언하지 않은 원본에는
+ * 문이 열리지 않고, 그 사실을 코드로 말한다(`not-declared`). 실 WMS 가 정지되지 않는 것은 결손이 아니다.
+ *
+ * ── 전송은 여기서 묻지 않는다 (§7) ──────────────────────────────────────────
+ * 인프로세스 시뮬레이터는 같은 계약을 인프로세스로 이행한다. 나중에 그것이 다른 프로세스로 나가도 이 경로는
+ * 바뀌지 않는다 — 「계약을 지나는가」만 보고 「네트워크를 타는가」는 묻지 않는다.
+ */
+import { getRepository } from '@things-factory/shell'
+
+import { TwinInstance } from '../twin-instance/twin-instance.js'
+import { TwinReference } from './twin-reference.js'
+import { capabilitiesOf, getAdapter, type ControlCommand, type ControlResult, type SiteDescriptor } from './reference-adapter.js'
+
+/**
+ * 이 트윈의 원본에 구동 명령을 보낸다 — **원본이 없거나 능력을 선언하지 않으면 거절한다.**
+ *
+ * 거절을 조용히 하지 않는다: 사유 코드를 돌려주고 화면이 그것을 사람 말로 옮긴다. 「아무 일도 일어나지
+ * 않았다」가 가장 비싼 답이다.
+ */
+export async function routeControl(domainId: string, instanceId: string, command: ControlCommand): Promise<ControlResult> {
+  const inst = await getRepository(TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId } })
+  if (!inst) return { ok: false, code: 'unknown-twin', detail: instanceId }
+
+  const ref = await getRepository(TwinReference).findOne({ where: { domain: { id: domainId }, source: instanceId } })
+  if (!ref) {
+    /* 원본을 모르는 트윈 — 구동할 대상이 없다. 트윈을 직접 흔드는 길은 두지 않는다(그것이 지름길이었다). */
+    return { ok: false, code: 'no-source', detail: `twin "${instanceId}" does not remember a source to drive` }
+  }
+
+  const adapter = getAdapter(ref.adapterType)
+  if (!adapter) return { ok: false, code: 'no-adapter', detail: ref.adapterType }
+  if (!capabilitiesOf(adapter).includes('control')) {
+    return {
+      ok: false,
+      code: 'not-declared',
+      detail: `source "${ref.source}" (${ref.adapterType}) does not declare the control capability — a real system is not paused or seeded, and that is a fact rather than a gap`
+    }
+  }
+
+  /*
+   * 사이트를 함께 넘긴다 — 원본 하나가 여러 사이트를 낼 수 있다(`discoverSites`). 우리가 아는 것은
+   * 이 트윈이 어느 사이트에서 왔는지이고(`origin.siteId`), 모르면 넘기지 않는다(지어내지 않는다).
+   */
+  const siteId = (inst.origin as any)?.siteId
+  const site: SiteDescriptor | undefined = siteId ? { siteId } : undefined
+  return adapter.control!(ref.connectionConfig ?? {}, site, { ...command, instanceId, domainId })
+}
+
+/** 이 트윈의 원본이 선언한 능력 — 화면이 「무엇을 할 수 있나」를 먼저 알 수 있게. */
+export async function controlCapabilityOf(domainId: string, instanceId: string): Promise<{ source?: string; adapterType?: string; capabilities: string[] }> {
+  const ref = await getRepository(TwinReference).findOne({ where: { domain: { id: domainId }, source: instanceId } })
+  if (!ref) return { capabilities: [] }
+  return { source: ref.source, adapterType: ref.adapterType, capabilities: capabilitiesOf(getAdapter(ref.adapterType)) }
+}

package/server/service/reference/index.ts

@@ -3,3 +3,4 @@ import { TwinReference } from './twin-reference.js'
 
 export const entities = [TwinReference]
 export const resolvers = [TwinReferenceResolver]
+export * from './control-routing.js'