@things-factory/headless-twin 10.0.9 → 10.0.10

package/server/service/twin-forecast/twin-forecast-query.ts

@@ -7,9 +7,39 @@ import { readSpecCoverage } from '../../engine/spec-coverage.js'
 import { describeModelBasis, modelBasisChanged, type ModelBasis } from '../../engine/model-basis.js'
 import { TwinEvent } from '../twin-event/twin-event.js'
 import { GAP_SAMPLES, aggregatePoints, computeSpc, gapMetrics, learnedCalibration, type GapPoint } from './gap-analytics.js'
+import { FORECAST_METRICS, type MetricFn } from './forecast-metrics.js'
+import { forecastStepMs } from './forecast-tuning.js'
 
 /* 커널 예측 함수 — CJS require(twin-engine 과 동일 방식). */
-const { monteCarloForecast } = require('@operato/twin-kernel')
+const { monteCarloForecastAsync } = require('@operato/twin-kernel')
+
+/**
+ * 이벤트 루프에 자리를 내주는 방법 — **커널이 아니라 여기가 안다.**
+ *
+ * `setImmediate` 는 대기 중인 I/O 다음 차례에 돌아온다. 마이크로태스크(`Promise.resolve()`)로는
+ * 자리가 가지 않는다 — 그러면 예측이 도는 동안 라이브 틱도 HTTP 도 여전히 멈춘다.
+ *
+ * ── 내준 시간은 **부하가 아니다** ───────────────────────────────────────────
+ * 부하 계기는 「이 트윈이 루프를 얼마나 붙잡았나」를 재는 자다. 양보를 넣은 뒤로 벽시계 시간에는
+ * 남에게 넘긴 시간이 섞이는데, 그것까지 부하로 적으면 계기가 거짓말을 한다 — 하필 이 문제를 짚어낸
+ * 그 계기다. 그래서 내준 시간을 따로 세어 빼고 적는다.
+ */
+function breather() {
+  let yieldedMs = 0
+  return {
+    fn: () =>
+      new Promise<void>(resolve => {
+        const t = performance.now()
+        setImmediate(() => {
+          yieldedMs += performance.now() - t
+          resolve()
+        })
+      }),
+    get ms() {
+      return yieldedMs
+    }
+  }
+}
 
 /*
  * 트윈 예측 채널 — 상향 query. 트윈의 "예측(predict)" 면(설계 §3.5, ADR-0009).
@@ -23,14 +53,16 @@ const DEFAULT_SCENARIO = {
     { kind: 'inbound-arrival', rate: { distribution: 'poisson', meanPerHour: 60 }, content: { skuMix: [{ gtin: GTIN, weight: 1 }], qtyPerLine: { min: 4, max: 12 } } }
   ]
 }
-const METRICS: Record<string, (s: any) => number> = {
-  items: s => (s.items || []).length,
-  occupancy: s => (s.locations || []).reduce((a: number, n: any) => a + (n.occupancy || 0), 0),
-  tasks: s => (s.tasks || []).length,
-  orders: s => (s.orders || []).length,
-  // 이행 지표 — 라이브 예측의 핵심 질문("언제 다 나가나·백로그 언제 풀리나").
-  shipped: s => (s.orders || []).filter((o: any) => o.status === 'shipped').length,
-  backlog: s => (s.orders || []).filter((o: any) => o.status !== 'shipped' && o.status !== 'cancelled').length
+/*
+ * 지표 표는 `forecast-metrics.ts` 가 소유한다 — 여기 있던 것을 옮겼다(시험이 이 파일을 불러올 수 없다).
+ *
+ * **모르는 지표를 `items` 로 갈음하지 않는다.** 예전에는 `METRICS[metric] ?? METRICS.items` 였다.
+ * 에너지 트윈에서 `peakKW` 를 물으면 재고 곡선이 그려지고, 재고가 없으니 **0 이 평평하게** 나왔다 —
+ * 화면은 그것을 「피크가 0」으로 읽는다. 지어낸 답보다 모른다고 말하는 편이 낫다.
+ */
+function metricFn(metric?: string): MetricFn | null {
+  if (!metric) return FORECAST_METRICS.items
+  return FORECAST_METRICS[metric] ?? null
 }
 
 /* 학습된 보정 저장(P3.2, 인메모리) — key=domain:instance:metric:horizon → {biasShift, halfWidth, …}.
@@ -42,25 +74,40 @@ const CALIBRATION = new Map<
 >()
 const calKey = (d: string, i: string, m: string, h: number) => `${d}:${i}:${m}:${h}`
 
-/* 갭 point 계산(공용) — N개 과거 vantage 각각 forecast-at-T vs actual-at-T+H(결정적 백테스트). gapTrend query·learn mutation 공용. */
-async function gapPoints(domainId: string, instanceId: string, m: (s: any) => number, H: number, N: number, scen: any): Promise<any[]> {
+/**
+ * 이 트윈이 백테스트할 수 있는 구간 — [첫 이벤트, 마지막 이벤트 − H].
+ * 지평 H 만큼 앞을 봐야 "그때 예측한 것"과 "실제로 벌어진 것"을 맞대 볼 수 있으므로 끝에서 H 를 뺀다.
+ */
+async function gapWindow(domainId: string, instanceId: string, H: number): Promise<{ t0: number; lastVantage: number } | null> {
   const where = { domain: { id: domainId }, instanceId }
   const repo = getRepository(TwinEvent)
   const first = await repo.findOne({ where, order: { eventTime: 'ASC' } })
   const last = await repo.findOne({ where, order: { eventTime: 'DESC' } })
-  if (!first || !last) return []
-  const t0 = Date.parse(first.eventTime)
-  const lastVantage = Date.parse(last.eventTime) - H
-  if (!(lastVantage > t0)) return []
-  const points: any[] = []
-  for (let i = 0; i < N; i++) {
-    const T = t0 + ((lastVantage - t0) * i) / (N - 1)
+  if (!first?.eventTime || !last?.eventTime) return null
+  const t0 = first.eventTime.getTime()
+  const lastVantage = last.eventTime.getTime() - H
+  return lastVantage > t0 ? { t0, lastVantage } : null
+}
+
+/**
+ * 갭 point 계산(공용) — 주어진 vantage 각각에서 forecast-at-T vs actual-at-T+H(결정적 백테스트).
+ *
+ * **vantage 는 밖에서 준다.** 예전에는 이 함수가 자기 저널의 첫·마지막 이벤트로 격자를 스스로 만들었다.
+ * 그러면 트윈마다 격자가 달라져, 공동배치 합산에서 `points[3]` 끼리 더할 때 **서로 다른 시각의 값**이
+ * 더해졌다(자세한 사연은 `aggregatePoints` 주석).
+ *
+ * 반환 배열은 격자와 **같은 길이**이고, 그 vantage 를 재지 못했으면 그 자리에 `null` 을 둔다.
+ * 건너뛰고 밀어 담으면 배열 인덱스가 시간축이기를 그만둔다.
+ */
+async function gapPoints(domainId: string, instanceId: string, m: (s: any) => number, H: number, grid: number[], scen: any): Promise<(any | null)[]> {
+  const points: (any | null)[] = []
+  for (const T of grid) {
     const k = await TwinEngine.buildForecastKernelAt(domainId, instanceId, new Date(T).toISOString()).catch(() => null)
-    if (!k) continue
-    const dist = monteCarloForecast(k, { runs: 12, horizonMs: H, scenario: scen, tickMs: 1000, metric: m })
+    if (!k) { points.push(null); continue }
+    const dist = await monteCarloForecastAsync(k, { runs: 12, horizonMs: H, scenario: scen, tickMs: forecastStepMs(H), metric: m, yieldFn: breather().fn })
     const naive = m(k.getSnapshot())
     const st = await TwinEngine.recover(domainId, instanceId, undefined, new Date(T + H).toISOString()).catch(() => null)
-    if (!st) continue
+    if (!st) { points.push(null); continue }
     const a = m(st)
     const p50 = dist?.p50 ?? naive
     points.push({ t: T, p50, min: dist?.min ?? p50, max: dist?.max ?? p50, actual: a, error: a - p50, inBand: a >= (dist?.min ?? -Infinity) && a <= (dist?.max ?? Infinity), naiveAbsError: Math.abs(a - naive), modelAbsError: Math.abs(a - p50) })
@@ -68,6 +115,21 @@ async function gapPoints(domainId: string, instanceId: string, m: (s: any) => nu
   return points
 }
 
+/**
+ * 여러 트윈이 **함께** 백테스트할 수 있는 구간과 그 위의 vantage 격자.
+ *
+ * 겹치는 구간은 각자의 구간을 교집합한 것 — 시작은 가장 늦은 t0, 끝은 가장 이른 lastVantage.
+ * 한 트윈이라도 그 시각에 저널이 없으면 공장 총량을 말할 수 없기 때문이다.
+ * 겹치는 구간이 없으면 `null` — "0" 이 아니라 "잴 수 없음" 이다.
+ */
+function sharedGrid(windows: { t0: number; lastVantage: number }[], N: number): number[] | null {
+  if (!windows.length || N < 2) return null
+  const t0 = Math.max(...windows.map(w => w.t0))
+  const lastVantage = Math.min(...windows.map(w => w.lastVantage))
+  if (!(lastVantage > t0)) return null
+  return Array.from({ length: N }, (_, i) => t0 + ((lastVantage - t0) * i) / (N - 1))
+}
+
 @Resolver()
 export class TwinForecastQuery {
   @Query(returns => ScalarObject, {
@@ -94,14 +156,29 @@ export class TwinForecastQuery {
         : undefined
     if (!k) return null
 
-    const m = METRICS[metric] ?? METRICS.items
+    const m = metricFn(metric)
+    /* 이 트윈이 못 세는 지표 — 빈 예측이 아니라 「그 지표는 여기 없다」고 말한다. */
+    if (!m) return { metric, unsupportedMetric: true, distribution: null, trajectory: [] }
     const H = horizonMs ?? 300000
     const R = runs ?? 30
-    const step = 1000
+    /*
+     * 틱 크기는 **지평선이 정한다**(`forecast-tuning`). 1초 고정이던 시절 5분 지평선이 회차마다
+     * 300틱이었고, 30회차면 9,000틱·28.5초였다 — 실측으로 5초 단위와 답이 같다.
+     */
+    const step = forecastStepMs(H)
     const scen = scenario ?? DEFAULT_SCENARIO
 
-    /* 분포: N개 확률적 미래 표본(fork 마다 seed 변주, 원본 보존). */
-    const distribution = monteCarloForecast(k, { runs: R, horizonMs: H, scenario: scen, tickMs: step, metric: m })
+    /*
+     * 분포: N개 확률적 미래 표본(fork 마다 seed 변주, 원본 보존).
+     *
+     * **이것이 요청 처리 중 메인 이벤트 루프에서 동기로 수행된다.** 기본값으로 fork 30개 × 300틱 = 9,000틱.
+     * 계기판에 남겨 두지 않으면 "왜 서버가 굳었나" 를 나중에 짚을 수 없다(실제로 한 번 겪었다).
+     */
+    const tMc = performance.now()
+    const mcBreath = breather()
+    const distribution = await monteCarloForecastAsync(k, { runs: R, horizonMs: H, scenario: scen, tickMs: step, metric: m, yieldFn: mcBreath.fn })
+    TwinEngine.recordLoad(domainId, instanceId, 'forecast', performance.now() - tMc - mcBreath.ms)
+    TwinEngine.countForks(domainId, instanceId, R)
 
     /* 학습된 보정 상시 적용(P3.2) — twinLearnCalibration 이 저장한 편향·밴드가 있으면 예측을 현실로 보정(라이브가 실제로 나아짐).
        갭트렌드(gapPoints)는 raw 모델을 그대로 측정(학습 신호 보존) — 보정은 표시용 forecast 에만. */
@@ -121,15 +198,57 @@ export class TwinForecastQuery {
           ` learned on: ${describeModelBasis(stored!.basis)} / now: ${describeModelBasis(basis)}`
       )
     }
+    /*
+     * 분위수 — 표본에서 직접 뽑는다.
+     *
+     * 커널이 표본 배열을 그대로 돌려주므로(forecast.ts) 여기서 정렬해 p05·p95 를 낸다. 이것이 없으면
+     * 화면이 보여 줄 수 있는 폭은 관측 **최소·최대** 뿐인데, 그건 신뢰구간이 아니라 극단값 두 개다.
+     * "운이 나쁜 5% 에서는 이만큼" 이라고 말하려면 분위수여야 한다. 표본이 적으면(runs 가 작으면)
+     * 분위수도 거칠다 — 그래서 표본 수를 함께 싣는다(sampleCount). 숫자만 주고 근거를 감추지 않는다.
+     */
+    if (distribution) {
+      const samples: number[] = Array.isArray(distribution.samples) ? distribution.samples : []
+      if (samples.length) {
+        const sorted = [...samples].sort((a, b) => a - b)
+        const pct = (p: number) => sorted[Math.min(sorted.length - 1, Math.floor(p * sorted.length))]
+        distribution.p05 = pct(0.05)
+        distribution.p95 = pct(0.95)
+      }
+      distribution.sampleCount = samples.length
+    }
+
     const cal = stored && !stale ? stored : undefined
     if (cal && distribution) {
-      const p50c = (distribution.p50 ?? 0) + cal.biasShift
+      /*
+       * `p50` 은 커널 계약상 항상 있다(`MonteCarloResult.p50: number`). 그래도 메우지 않는다 —
+       * 예전에는 `?? 0` 이었는데, 만약 비면 보정된 p50 이 **편향값 그 자체**가 되고 min·max 는
+       * 그 둘레로 그려진다. 예측이 아닌 숫자가 예측의 자리에 앉는데 아무 신호가 없다.
+       */
+      if (typeof distribution.p50 !== 'number') throw new Error('forecast distribution has no p50 — kernel contract broken')
+      const p50c = distribution.p50 + cal.biasShift
       distribution.p50 = Math.round(p50c)
       distribution.min = Math.round(p50c - cal.halfWidth)
       distribution.max = Math.round(p50c + cal.halfWidth)
+      /*
+       * 분위수는 **옮기기만** 한다. 보정이 배운 것은 "모델이 이만큼 치우쳐 있다"(위치)이지 분포의
+       * 모양이 아니다. p50 처럼 밀어 두어야 p05~p95 폭이 표본이 말한 그대로 남는다.
+       * (min·max 는 위에서 학습 밴드로 대체된다 — 보정이 걸리면 그 둘의 뜻이 '관측 극단' 에서
+       *  '학습 밴드' 로 바뀐다는 뜻이다. 화면이 둘을 같은 것으로 그리면 안 된다.)
+       */
+      if (distribution.p05 !== undefined) distribution.p05 = Math.round(distribution.p05 + cal.biasShift)
+      if (distribution.p95 !== undefined) distribution.p95 = Math.round(distribution.p95 + cal.biasShift)
+      if (distribution.p90 !== undefined) distribution.p90 = Math.round(distribution.p90 + cal.biasShift)
+      distribution.calibrated = true
     }
 
-    /* 예측 궤적(예측선): 단일 fork 를 horizon 까지 굴리며 지표 기록. */
+    /*
+     * 예측 궤적(예측선): 단일 fork 를 horizon 까지 실행하며 지표 기록. 이것도 잰다.
+     *
+     * 여기도 자리를 내준다 — 실측으로 이 한 회차가 1.3초였다(300틱 + 스냅샷 300번). 분포만큼은
+     * 아니지만, 라이브 틱 간격(1초)보다 길게 붙잡으면 그 사이 트윈들이 한 박자씩 밀린다.
+     */
+    const tTraj = performance.now()
+    const trajBreath = breather()
     const fc = k.fork()
     fc.scenario.load({ ...scen, seed: 1 })
     fc.scenario.start()
@@ -137,8 +256,13 @@ export class TwinForecastQuery {
     for (let t = 0; t < H; t += step) {
       fc.tick(step)
       trajectory.push({ t: t + step, value: m(fc.getSnapshot()) })
+      /* 틱마다 내주면 양보 자체가 비용이 된다 — 라이브 틱 간격보다 훨씬 짧은 단위로 끊는다. */
+      if (trajectory.length % 25 === 0) await trajBreath.fn()
     }
 
+    TwinEngine.recordLoad(domainId, instanceId, 'forkTick', performance.now() - tTraj - trajBreath.ms)
+    TwinEngine.countForks(domainId, instanceId, 1)
+
     const current = m(k.getSnapshot()) // vantage T 의 실제값(= naive '그대로 유지' 예측의 기준)
 
     /* 실측 오버레이 + 채점(P1) — vantage 가 과거(at)일 때만: T 이후 실제로 일어난 metric 을 T→min(now,T+H) 로 샘플.
@@ -173,15 +297,36 @@ export class TwinForecastQuery {
     }
 
     /*
-     * 시뮬 명세 자기보고를 함께 낸다 — **상수로 굴린 예측과 현장 명세로 굴린 예측이 화면에서 같아
+     * 시뮬 명세 자기보고를 함께 낸다 — **상수로 계산한 예측과 현장 명세로 계산한 예측이 화면에서 같아
      * 보이지 않게.** 코드·수치만 싣고 사람이 읽는 문장은 클라가 만든다(언어 중립).
      * 커널이 이 API 를 갖지 않은 버전이면 키를 만들지 않는다(모르는 것을 "전부 기본값" 이라 단정 금지).
      */
-    /* 보고는 **실제로 굴린 fork** 에서 읽는다 — 부모 커널(k)은 tick 하지 않으므로(예측은 fork 에서
-     * 돈다) 부모에서 읽으면 씨앗으로 세운 예측에서는 늘 비어 있다. 숫자를 낸 주체가 보고해야 한다. */
+    /* 보고는 **실제로 실행한 fork** 에서 읽는다 — 부모 커널(k)은 tick 하지 않으므로(예측은 fork 에서
+     * 수행된다) 부모에서 읽으면 씨앗으로 세운 예측에서는 늘 비어 있다. 숫자를 낸 주체가 보고해야 한다. */
     const specCoverage = readSpecCoverage(fc) ?? readSpecCoverage(k)
     return {
       metric: metric ?? 'items', horizonMs: H, runs: R, current, distribution, trajectory, actual, scored,
+      /* 얼마나 잘게 굴렸나 — 숫자만 주고 근거를 감추지 않는다(같은 규율로 `specCoverage` 도 싣는다). */
+      tickMs: step,
+      /*
+       * **가정이 어떻게 됐나** — 걸린 개입·거절된 개입·덮어쓴 선언.
+       *
+       * 이것을 감추면 두 가지가 조용해진다: 걸리지 않은 가정(「걸었는데 왜 안 바뀌나」)과, 덮어쓴
+       * 선언(사용자가 what-if 결과를 트윈의 현재 상태로 읽는다). 실제로 실행한 fork(`fc`)에서 읽는다 —
+       * 가정을 겪은 것은 그쪽이다.
+       */
+      ...(typeof (fc as any).interventionOutcomes === 'function'
+        ? (() => {
+            const outcomes = (fc as any).interventionOutcomes()
+            return outcomes.length ? { interventions: outcomes } : {}
+          })()
+        : {}),
+      ...(typeof (fc as any).declarationOverrides === 'function'
+        ? (() => {
+            const overrides = (fc as any).declarationOverrides()
+            return overrides.length ? { overrides } : {}
+          })()
+        : {}),
       calibrated: !!cal,
       /* 학습해 뒀지만 모델이 바뀌어 적용하지 않았다 — 사용자가 다시 배울 수 있게 알린다. */
       ...(stale ? { calibrationStale: true } : {}),
@@ -209,18 +354,39 @@ export class TwinForecastQuery {
     @Arg('instanceIds', type => [String], { nullable: true }) instanceIds?: string[]
   ): Promise<any> {
     const domainId = context.state.domain.id
-    const m = METRICS[metric] ?? METRICS.items
+    const m = metricFn(metric)
     const H = horizonMs ?? 300000
+    if (!m) return { metric, unsupportedMetric: true, horizonMs: H, samples: 0, points: [], spc: computeSpc([]), metrics: null, learn: null }
     const N = Math.min(30, Math.max(2, samples ?? GAP_SAMPLES)) // 표본은 서버가 관장(SPC 신뢰 하한 ~20).
     const scen = scenario ?? DEFAULT_SCENARIO
     // 공동배치(co-located) 집계도 서버에서 — 공장 단위 진단이 canonical. 미지정 시 단건.
     const ids = instanceIds?.length ? instanceIds : [instanceId]
-    const per = await Promise.all(ids.map(id => gapPoints(domainId, id, m, H, N, scen)))
-    const points = aggregatePoints(per as GapPoint[][])
+
+    /*
+     * 격자를 **먼저 하나** 만든다. 트윈마다 자기 저널로 격자를 만들면 같은 인덱스가 서로 다른
+     * 시각이 되어, 합산이 다른 시점의 값을 더한다(`aggregatePoints` 주석 참조).
+     *
+     * 저널이 없거나 지평 H 를 담을 만큼 길지 않은 트윈은 **백테스트에 참여할 수 없다.** 그런 트윈은
+     * 빼되 누구를 뺐는지 돌려준다 — 조용히 빼면 화면은 그 트윈까지 포함한 공장 총량으로 읽는다.
+     */
+    const windows = await Promise.all(ids.map(async id => ({ id, w: await gapWindow(domainId, id, H) })))
+    const usable = windows.filter(x => x.w)
+    const excluded = windows.filter(x => !x.w).map(x => x.id)
+    const grid = sharedGrid(usable.map(x => x.w!), N)
+    if (!grid) {
+      /* 겹치는 구간이 없다 — 잴 수 없는 것이지 정확도가 0 인 것이 아니다. */
+      return { metric: metric ?? 'items', horizonMs: H, samples: N, points: [], spc: computeSpc([]), metrics: null, learn: null,
+        coverage: { instances: ids.length, measured: 0, excluded, vantages: N, used: 0, dropped: 0, reason: 'no-common-window' } }
+    }
+
+    const per = await Promise.all(usable.map(x => gapPoints(domainId, x.id, m, H, grid, scen)))
+    const { points, droppedVantages } = aggregatePoints(per as (GapPoint | null)[][])
     const metrics = points.length ? gapMetrics(points) : null
     const spc = computeSpc(points.map(p => p.error))
     const learn = metrics ? learnedCalibration(points, metrics) : null
-    return { metric: metric ?? 'items', horizonMs: H, samples: N, points, spc, metrics, learn }
+    return { metric: metric ?? 'items', horizonMs: H, samples: N, points, spc, metrics, learn,
+      /* 이 숫자가 **무엇으로 계산됐는지**. 24점 중 18점이면 화면이 그렇게 말해야 한다. */
+      coverage: { instances: ids.length, measured: usable.length, excluded, vantages: N, used: points.length, dropped: droppedVantages } }
   }
 
   /*
@@ -239,7 +405,8 @@ export class TwinForecastQuery {
   ): Promise<any> {
     const domainId = context.state.domain.id
     if (!TwinEngine.owns(domainId, instanceId)) return { ok: false } // 테넌트 격리
-    const m = METRICS[metric] ?? METRICS.items
+    const m = metricFn(metric)
+    if (!m) return { ok: false, reason: 'unsupported-metric', metric }
     const H = horizonMs ?? 300000
     // 보정 해제 — 저장된 calibration 제거(이후 예측은 raw 로 복귀). 학습을 되돌리는 정직한 off 스위치.
     if (clear) {
@@ -247,7 +414,12 @@ export class TwinForecastQuery {
       return { ok: true, cleared: true, metric: metric ?? 'items', horizonMs: H }
     }
     // 표본·계산을 gap-analytics 로 일원화(gapTrend 진단과 동일 N·동일 수식 → 카드 예상치와 실제 보정 일치).
-    const pts = await gapPoints(domainId, instanceId, m, H, GAP_SAMPLES, DEFAULT_SCENARIO)
+    /* 학습은 단건이라 격자도 이 트윈의 구간 하나다. 저널이 지평 H 를 담을 만큼 길지 않으면 배울 것이 없다. */
+    const w = await gapWindow(domainId, instanceId, H)
+    const grid = w ? sharedGrid([w], GAP_SAMPLES) : null
+    if (!grid) return { ok: false, reason: 'insufficient-history' }
+    /* 못 잰 vantage 는 `null` 로 온다 — 0 으로 세면 편향 학습이 그만큼 끌려간다. */
+    const pts = (await gapPoints(domainId, instanceId, m, H, grid, DEFAULT_SCENARIO)).filter(Boolean) as GapPoint[]
     if (pts.length < 3) return { ok: false, reason: 'insufficient-history' }
     const learn = learnedCalibration(pts, gapMetrics(pts))
     /* 학습한 모델의 지문을 함께 남긴다 — 이후 모델이 바뀌면 이 보정은 적용되지 않는다. */

package/server/service/twin-instance/twin-instance.ts

@@ -1,20 +1,21 @@
 import { CreateDateColumn, Entity, Index, Column, RelationId, ManyToOne, PrimaryGeneratedColumn, UpdateDateColumn } from 'typeorm'
-import { ObjectType, Field, ID, Int } from 'type-graphql'
+import { ObjectType, Field, ID } from 'type-graphql'
 
 import { Domain, ScalarObject } from '@things-factory/shell'
-import { boardColumnTransformer } from '../../engine/board-vocabulary.js'
+import { User } from '@things-factory/auth-base'
+import { modelColumnTransformer } from '../../engine/model-vocabulary.js'
 
 /*
  * TwinInstance — 트윈 인스턴스 레지스트리(재부팅 복구의 앵커).
- * 복구(DB→replay)는 board(마스터 청사진)가 있어야 이벤트를 상태로 되짚을 수 있다 → board·kind 를 영속.
- * 이벤트(TwinEvent)와 달리 가변(status/revision 갱신) — 인스턴스의 "현재 등록 상태".
- * board 는 simple-json(멀티DB 이식 — postgres/mysql/sqlite/mssql/oracle 공통).
+ * 복구(DB→replay)는 model(마스터 청사진)가 있어야 이벤트를 상태로 다시 계산할 수 있다 → model·kind 를 영속.
+ * 이벤트(TwinEvent)와 달리 가변(status 갱신) — 인스턴스의 "현재 등록 상태".
+ * model 는 simple-json(멀티DB 이식 — postgres/mysql/sqlite/mssql/oracle 공통).
  * (CLAUDE.md: 모든 @ObjectType/@Field 는 영문 description 필수.)
  */
 @Entity()
 @Index('ix_twin_instance_0', (e: TwinInstance) => [e.domain, e.instanceId], { unique: true })
 @Index('ix_twin_instance_1', (e: TwinInstance) => [e.domain, e.spaceId]) // 공간→인스턴스 1급 질의(공간 중심 존재론)
-@ObjectType({ description: 'Registry of a hosted twin runtime instance — anchors reboot recovery (board + kind).' })
+@ObjectType({ description: 'Registry of a hosted twin runtime instance — anchors reboot recovery (model + kind).' })
 export class TwinInstance {
   @PrimaryGeneratedColumn('uuid')
   @Field(type => ID, { description: 'Unique identifier of the registry record.' })
@@ -31,34 +32,82 @@ export class TwinInstance {
   @Field({ description: 'Twin runtime instance id (unique within a domain).' })
   instanceId: string
 
+  /**
+   * **사람이 부르는 이름** — 업무키(`instanceId`)와 나란히 두는 표시명(프레임워크 엔티티 규약).
+   *
+   * ── 왜 업무키와 이름을 나눠 두나 ─────────────────────────────────────────────
+   * `instanceId` 는 URL·저널·구독이 전부 쓰는 **계약**이라 바꿀 수 없다. 반대로 이름은 바뀌고,
+   * 중복되고(사이트 둘에 "도장" 이 있는 것이 정상), 언어마다 다르다. 둘을 한 컬럼에 담으면 개명이
+   * 곧 다른 트윈이 되고 재동기가 끊긴다 — 그래서 나눈다(이 저장소에서 식별자가 밖에서 오는 것은
+   * 전부 이 규약을 쓴다: `spaceId`·`locationId`·`equipmentId`·`operationKey`).
+   *
+   * 나눴으면 **이름을 반드시 함께 둬야 한다.** 이 자리가 없던 동안 사이트 이름은 model 안에만 있어서
+   * 목록이 `crew-two` 만 보였다 — 나누기만 하고 절반을 빼먹으면 화면에는 id 만 남는다.
+   *
+   * 원본이 이름을 말하지 않으면 비운다(id 를 베끼지 않는다).
+   */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Human name of this twin (the site name from its master). Empty when the source does not name it — never copied from instanceId.' })
+  name?: string
+
   @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Domain kernel kind: wms | yms | mes.' })
-  kind?: string
+  @Field({ nullable: true, description: 'Longer description when the source provides one.' })
+  description?: string
+
+  /* 어느 도메인 커널이 이 트윈을 운영하는가. 커널 없는 트윈은 없으므로 비어 있을 수 없다
+     (`TwinEngine.start`·`register` 모두 필수 인자로 받는다). */
+  @Column()
+  @Field({ description: 'Domain kernel kind: wms | yms | mes.' })
+  kind: string
 
   /*
    * realityMode — 이 트윈의 현실이 어디서 오는가(runtime-state-model §0·§1 "지속 현실 하나 + 여러 렌즈"의 ① 선언).
    * 'mirror'         = 현실은 외부 실물 시스템. 트윈=순수 렌즈, 재기동 시 실물서 재동기(startLive).
    * 'sim-world'      = 트윈이 낳은 타임라인이 곧 진실이며 이어진다 → 재기동 시 저널서 resume(현실 지속).
    * 'sim-experiment' = seed 재현형. 재기동 = 같은 우주 재실행(저널 reset, revision 0) — 백지 시작이 버그가 아니라 선언된 거동.
-   * 미선언(레거시)은 'sim-experiment'로 간주(가장 보수적 — 기존 데모 거동 보존).
+   *
+   * **비어 있을 수 없다.** 이 값은 재기동 거동을 구분하는 선언이고, 없으면 읽는 쪽마다 각자
+   * 기본값을 고르게 된다 — 같은 트윈이 부르는 자리에 따라 다르게 재기동하는 길이다.
+   * 선언을 생략한 프로비저닝은 `register` 가 `DEFAULT_REALITY_MODE` 로 **각인해서 저장한다**.
+   * 즉 "미선언" 이라는 상태 자체를 저장소에 두지 않는다.
    */
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: "Reality source declaration: 'mirror' (external system is truth, resync on reboot) | 'sim-world' (generated timeline is truth and persists, resume on reboot) | 'sim-experiment' (seed-reproducible, resets on reboot). Absent ⇒ treated as sim-experiment." })
-  realityMode?: string
+  @Column()
+  @Field({ description: "Reality source declaration: 'mirror' (external system is truth, resync on reboot) | 'sim-world' (generated timeline is truth and persists, resume on reboot) | 'sim-experiment' (seed-reproducible, resets on reboot)." })
+  realityMode: string
 
   /* 읽을 때 어휘 세대를 흡수한다(`nodes`/`movers`/`equipmentList` → `locations`/`equipment`).  (vocabulary-guard: allow — 세대 이름 없이는 설명할 수 없다.)
      자리마다 리더를 쓰게 하면 다음에 추가되는 자리가 또 빠지고, 빠진 것은 오류가 아니라 **빈 공장**이라
-     조용하다(2026-08-06: 모델러 엔티티 목록이 통째로 비었다). 상세 `engine/board-vocabulary.ts`. */
-  @Column({ type: 'simple-json', nullable: true, transformer: boardColumnTransformer })
-  @Field(type => ScalarObject, { nullable: true, description: 'BoardDef blueprint (locations/equipment) required to replay events into state. Older stored boards used nodes/movers/equipmentList; they are normalised on read so consumers see one vocabulary.' }) // vocabulary-guard: allow — 옛 어휘를 흡수하는 것이 이 코드의 일이다(세대 이름을 적어야 흡수할 수 있다)
-  board?: any
+     조용하다(2026-08-06: 모델러 엔티티 목록이 통째로 비었다). 상세 `engine/model-vocabulary.ts`. */
+  @Column({ type: 'simple-json', nullable: true, transformer: modelColumnTransformer })
+  @Field(type => ScalarObject, { nullable: true, description: 'TwinModelDef blueprint (locations/equipment) required to replay events into state. Older stored boards used nodes/movers/equipmentList; they are normalised on read so consumers see one vocabulary.' }) // vocabulary-guard: allow — 옛 어휘를 흡수하는 것이 이 코드의 일이다(세대 이름을 적어야 흡수할 수 있다)
+  model?: any
+
+  /*
+   * 로컬 선언 겹 — **구조는 원천이, 수는 우리가.**
+   *
+   * 요금 단가·계약 정보·축전지 충전율처럼 원 시스템이 모르는 값을 넣는 자리다. `model` 에 직접 쓰지
+   * 않는 이유는 그것이 **원천의 사본**이기 때문이다: 다시 읽기가 사본을 새로 그리면 직접 쓴 값은 조용히
+   * 사라진다(요금이 사라지면 금액도 사라지고, 사용자는 이유를 알 수 없다).
+   *
+   * 그래서 여기 남기고, 모델을 그릴 때마다 그 위에 얹는다(`engine/local-declarations`). 얹힌 값에는
+   * `source: 'local'` 이 붙는다 — 커널 계약의 `PropertySource` 축(`reference` ↔ `local`)이고, 「밖에서
+   * 참조해 온 값이냐, 이 안에서 정한 값이냐」에 답한다.
+   *
+   * **이름에 장소 낱말을 쓰지 않는다**(옛 이름 `siteDeclarations`): 이 코드에서 `site` 는 **외부
+   * 시스템이 부르는 사업장**이고(SAP `P3`·Oracle `W01` 이 같은 현장), 여기 담기는 것은 그 외부 시스템이
+   * **모르는** 값이다 — 이름이 내용과 정반대였다. `space` 도 아니다: 그것은 「어디」에 답하고 이 축은
+   * 「누가 말했나」에 답한다.
+   */
+  @Column({ type: 'simple-json', nullable: true })
+  @Field(type => ScalarObject, { nullable: true, description: "Locally-declared values layered on top of the reference-derived model (tariff, contract, state of charge) — values whose authority sits here, not in the source system. Kept apart from `model` so a resync cannot silently drop them." })
+  localDeclarations?: any
 
   @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Owning space id (co-location anchor). Promoted from board.spaceId — first-class "space → its twins" query (space-centered ontology).' })
+  @Field({ nullable: true, description: 'Owning space id (co-location anchor). Promoted from model.spaceId — first-class "space → its twins" query (space-centered ontology).' })
   spaceId?: string
 
   @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Owning area id within the space (optional scope). Promoted from board.areaId.' })
+  @Field({ nullable: true, description: 'Owning area id within the space (optional scope). Promoted from model.areaId.' })
   areaId?: string
 
   @Column({ nullable: true })
@@ -68,19 +117,49 @@ export class TwinInstance {
   /*
    * purpose — 이 인스턴스가 운영 트윈인지, 격리된 벤치 사본인지 1급 선언(이름 접두사가 아니라 속성으로 구별).
    * 'bench' 는 규모/부하 실험용 격리 사본 — 목록·정리·안전 가드가 이 속성을 키로 동작(운영 트윈 무오염 보장).
-   * 미선언(레거시)은 'operational' 로 간주.
+   *
+   * **비어 있을 수 없다.** 프로비저닝이 `register` 에서 'operational' 로 각인하고, 벤치 사본만
+   * `setPurpose` 로 뒤집는다. 예전에는 비워 둔 채 읽는 쪽에서 메웠는데, 그러면 "운영이라고 선언된 것"
+   * 과 "아무도 말하지 않은 것" 이 같은 값으로 보여서 벤치 격리가 추측에 기대게 된다.
    */
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: "Instance purpose: 'operational' (real twin) | 'bench' (isolated copy for scale/load experiments). Absent ⇒ operational." })
-  purpose?: string
+  @Column()
+  @Field({ description: "Instance purpose: 'operational' (real twin) | 'bench' (isolated copy for scale/load experiments)." })
+  purpose: string
 
   @Column({ nullable: true })
   @Field({ nullable: true, description: 'For a bench copy: the source spaceId it was copied from (provenance).' })
   copyOf?: string
 
-  @Column({ type: 'int', nullable: true })
-  @Field(type => Int, { nullable: true, description: 'Last persisted state revision observed for this instance.' })
-  revision?: number
+  /**
+   * **이 트윈을 다시 읽는 방법** — 어떤 원본에서 나왔나(`MasterOrigin`).
+   *
+   * 트윈은 원본을 비출 뿐이므로(ADR-0028) 원본이 달라지면 다시 읽어야 한다. 그런데 이 자리가 없던
+   * 동안 트윈은 **자기가 무엇에서 나왔는지 몰랐다** — 어댑터로 들어온 트윈은 `TwinReference` 행이
+   * 있었지만 템플릿으로 세운 트윈에는 아무 표식도 없었고, 그래서 첫날의 모습에 영원히 머무는
+   * 트윈이 만들어졌다. 원천이 무엇이든 여기 한 자리에 남긴다.
+   *
+   * **비어 있을 수 있다** — 이 자리가 생기기 전에 만들어진 트윈이 그렇다. 그때는 "다시 읽을 수
+   * 없다" 가 사실이므로 화면이 그대로 말한다(짐작해 채우지 않는다).
+   */
+  @Column({ type: 'simple-json', nullable: true })
+  @Field(type => ScalarObject, {
+    nullable: true,
+    description:
+      "How this twin's master can be produced again — {kind:'reference', source} or {kind:'template', templateId, params}. Absent means this twin cannot be re-read from its source."
+  })
+  origin?: any
+
+  /*
+   * `revision` 컬럼은 **없앴다**(2026-08-08).
+   *
+   * `ADR-0015` 가 "정의만 있고 write 안 됨 — 프로비저닝에서 최신 저널 revision 을 반영하도록
+   * 채운다" 고 적어 두었는데, 채우지 않는 편이 맞다. 저널의 최신 번호는 **저널이 아는 사실**이고
+   * (`TwinEngine.list` 가 `MAX(revision)` 으로 낸다), 여기 복제하면 **같은 사실의 집이 둘**이 된다.
+   * 이 세션에만 그 부류를 셋 겪었다(`model.operations` 두 집 · `materials` 두 집 · tenantId 중복).
+   *
+   * 복제한 값은 반드시 어긋난다 — 저널은 틱마다 늘고 이 컬럼은 저장할 때만 갱신되므로, 화면이
+   * 어느 쪽을 읽느냐로 다른 숫자가 나온다. 그 조용한 어긋남을 만들 이유가 없다.
+   */
 
   @CreateDateColumn()
   @Field({ nullable: true, description: 'Timestamp when the instance was first registered.' })
@@ -89,4 +168,26 @@ export class TwinInstance {
   @UpdateDateColumn()
   @Field({ nullable: true, description: 'Timestamp when the instance registry row was last updated.' })
   updatedAt?: Date
+
+  /*
+   * 누가 만들고 누가 고쳤나 — **이 행은 사람이 만든다**(프로비저닝은 사용자 행위)이므로 규약의
+   * 풀세트를 갖는다. 투영 행(자리·설비·공정)은 반대로 인제스트가 그린 것이라 저자가 사람이 아니고,
+   * 그 저자는 `sourceRef`+`ingestedAt` 이 이미 말한다 — 그래서 그쪽에는 두지 않는다.
+   *
+   * 비어 있을 수 있다: 부팅 자동 프로비저닝처럼 **사람이 없는 경로**로 만들어진 행이 그렇다.
+   * 그때 아무 사용자를 적어 넣으면 감사 기록이 거짓이 된다.
+   */
+  @ManyToOne(type => User, { nullable: true })
+  @Field(type => User, { nullable: true, description: 'The user who first provisioned this twin. Empty when it was created by a system path (boot provisioning).' })
+  creator?: User
+
+  @RelationId((e: TwinInstance) => e.creator)
+  creatorId?: string
+
+  @ManyToOne(type => User, { nullable: true })
+  @Field(type => User, { nullable: true, description: 'The user who last changed this twin registry row.' })
+  updater?: User
+
+  @RelationId((e: TwinInstance) => e.updater)
+  updaterId?: string
 }