@things-factory/headless-twin 10.0.6 → 10.0.7

package/server/engine/kpi-target.ts

@@ -0,0 +1,226 @@
+/*
+ * 성과 목표 — **숫자를 판단으로 바꾸는 층.**
+ *
+ * ── 왜 필요한가 ─────────────────────────────────────────────────────────────
+ * 화면과 AI 는 "처리량 345건 · 작업시간 29초" 를 정확히 말한다. 그런데 **그것이 좋은지 나쁜지는 말할 수
+ * 없다.** 판단 근거가 앞 구간 비교뿐이라 "어제보다 나아졌다" 까지가 한계이고, 어제도 나빴으면 그 말은
+ * 쓸모가 없다. 목표가 붙는 순간 같은 숫자가 **정보에서 판단으로** 바뀐다.
+ *
+ * ── 층을 섞지 않는다 ────────────────────────────────────────────────────────
+ * 폴드(`kpi-fold`)는 **사실만** 낸다 — 목표를 모른다. 목표를 아는 순간 "사실을 세는 규칙" 과 "잘했나
+ * 판정하는 규칙" 이 한 함수에 섞이고, 목표가 바뀔 때마다 사실 계산을 건드리게 된다. 그래서 판정은
+ * 여기, **순수 함수**로 따로 둔다(폴드처럼 테스트가 값싸다).
+ *
+ * ── 목표의 집 (사용자 결정 2026-08-02) ──────────────────────────────────────
+ * **트윈은 운영 목표를 갖고, `@things-factory/kpi` 는 경영 목표를 갖는다.** 경계:
+ *
+ *   트윈(TwinTarget)          이 구간·이 교대·이 공간의 **즉시 판단**. 현장 관리자가 트윈 화면에서 고친다.
+ *                             값은 저널 폴드에서 **그때그때 계산**된다(저장된 값을 읽지 않는다).
+ *   packages/kpi              **기간 평가**(조직·분기·점수·가중치·알림). 값은 저장돼 있어야 한다.
+ *
+ * 이 경계를 지키는 규칙 하나: **트윈은 목표를 복제하지 않는다.** 경영 목표가 필요하면 트윈의 사실을
+ * 내보내 그쪽이 소비하고, 그쪽 목표를 여기로 베껴 오지 않는다 — 베끼는 순간 두 개의 진실이 된다.
+ */
+/*
+ * ── 운영 임계(커널 attention)와의 경계 ─────────────────────────────────────
+ *
+ * **attention 은 개체 하나의 지금 상태**다 — 앵커(설비·자리·오더)와 할 수 있는 조치를 갖는다.
+ * **target(여기)은 구간의 집계**다 — 앵커도 조치도 없고 추세를 판단한다.
+ *
+ * 그래서 창 단위 집계 판정을 attention 으로 넣지 않는다: "가동률 저하"(창 평균) attention 을 만들면
+ * `utilization.ratio` 목표와 **같은 사실을 두 층이 다른 임계로 판정**하게 된다.
+ * (design/map/performance.md §5.0-4 — 현재 다섯 attention 과 이 어휘는 겹치지 않는다.)
+ */
+import type { DurationStats, KpiResult } from './kpi-fold.js'
+
+/** 측정된 기록이 있을 때만 값으로 인정한다 — 없으면 모름(0 이 아니다). */
+const measured = (k: KpiResult, v: number): number | undefined => (k.eventsInWindow > 0 ? v : undefined)
+
+/** 분위수는 표본이 있을 때만 값이다 — `count === 0` 의 `p50Ms: 0` 은 "0 밀리초" 가 아니라 "없음" 이다. */
+const statOf = (s: DurationStats, pick: (d: DurationStats) => number): number | undefined =>
+  s.count > 0 ? pick(s) : undefined
+
+/**
+ * 지표 어휘 — **이름을 한 곳에서 정한다.**
+ *
+ * 목표와 사실이 서로 다른 이름을 쓰면 그 사이에 매핑 표가 생기고, 그 표가 곧 방언이 된다. 그래서
+ * 목표가 가리킬 수 있는 지표는 여기 열거된 것뿐이고, 값을 꺼내는 방법도 여기 함께 있다.
+ *
+ * **`direction` 은 지표의 성질이지 사용자의 선택이 아니다.** 처리량은 높을수록 좋고 대기시간은 낮을수록
+ * 좋다 — 이것을 입력으로 받으면 반대로 적은 목표가 만들어지고, 그 뒤 판정이 전부 뒤집힌다.
+ */
+export const TWIN_METRIC = {
+  /* 기록이 없는 구간은 처리량 0 이 아니라 **모름**이다 — `eventsInWindow` 가 그것을 가른다.
+     0 으로 판정하면 "측정 못 한 구간" 이 "일을 안 한 구간" 으로 보고된다. */
+  'throughput.tasks': { direction: 'higher', unit: 'count', of: (k: KpiResult) => measured(k, k.throughput.tasks) },
+  'throughput.orders': { direction: 'higher', unit: 'count', of: (k: KpiResult) => measured(k, k.throughput.orders) },
+  /* 소요시간 분위수는 `count === 0` 이면 **0 이 아니라 없다.** 이것을 0 으로 읽으면 시간 지표는
+     "낮을수록 좋다" 라서 **일이 없던 구간이 목표를 완벽히 달성한 것으로** 보고된다 — 미달을 놓치는
+     것보다 나쁘다(고칠 곳이 있는데 잘하고 있다고 말한다). 테스트가 이것을 잡았다. */
+  'leadTime.p50Ms': { direction: 'lower', unit: 'ms', of: (k: KpiResult) => statOf(k.leadTime, d => d.p50Ms) },
+  'leadTime.p90Ms': { direction: 'lower', unit: 'ms', of: (k: KpiResult) => statOf(k.leadTime, d => d.p90Ms) },
+  'workTime.p50Ms': { direction: 'lower', unit: 'ms', of: (k: KpiResult) => statOf(k.workTime, d => d.p50Ms) },
+  'waitTime.p50Ms': { direction: 'lower', unit: 'ms', of: (k: KpiResult) => statOf(k.waitTime, d => d.p50Ms) },
+  /** 자원 점유 — 개별 자원이 아니라 **창 전체의 평균 비율**(자원별은 관점 축의 일이다). */
+  'utilization.ratio': {
+    direction: 'higher',
+    unit: 'ratio',
+    of: (k: KpiResult) =>
+      k.utilization.length ? k.utilization.reduce((s, u) => s + u.ratio, 0) / k.utilization.length : undefined
+  }
+} as const
+
+export type TwinMetricId = keyof typeof TWIN_METRIC
+export const isTwinMetric = (id: string): id is TwinMetricId => id in TWIN_METRIC
+
+/**
+ * 저장된 목표 행에서 **이 범위에 걸린 목표**를 고른다 — 좁은 선언이 넓은 선언을 덮는다.
+ *
+ * **왜 순수 함수인가**: 이 규칙(공간 목표 위에 인스턴스 목표를 얹는다)은 지금까지 DB 접근 뒤에 숨어
+ * 있어서 **화면을 눌러 봐야만** 확인할 수 있었다. 그런데 이 프로젝트는 로그인 뒤 화면을 자동으로
+ * 검증할 방법이 없어, 실제로 여러 기능이 "실화면 미검증" 으로 쌓였다. 규칙을 밖으로 빼면 테스트가
+ * 값싸진다 — 조회는 행을 가져오기만 하고, **판단은 여기서** 한다.
+ */
+/**
+ * 축 목표까지 담은 목록 — 전체 목표와 **축의 한 값**에 걸린 목표를 함께 든다.
+ *
+ * 축 목표는 전체 목표를 **덮지 않는다.** 다른 질문이기 때문이다: "현장 전체가 100건" 과
+ * "용접 구역이 30건" 은 동시에 참일 수 있다. 덮게 만들면 축 하나에 목표를 거는 순간 전체 판정이
+ * 사라져 사용자가 "목표를 지웠나?" 를 묻게 된다.
+ */
+export interface ScopedTargets {
+  /** 창 전체에 걸린 목표. */
+  overall: TwinTargetSpec[]
+  /** 축 → (그 축의 값 → 목표들). 요청한 축만 채운다. */
+  byAxisKey: Record<string, TwinTargetSpec[]>
+}
+
+/**
+ * 축의 각 값에 대해 목표 대비 판정 — **그룹 항목에 그대로 붙일 형태.**
+ *
+ * 그룹의 지표는 전체보다 좁다(주문 수·자원 점유는 축 단위로 뜻이 다르거나 없다). 없는 지표에 목표가
+ * 걸려 있으면 **판정하지 않는다** — 여기서 0 으로 읽으면 시간 지표가 "완벽 달성" 으로 뒤집힌다
+ * (전체 판정에서 이미 겪은 결함이다).
+ */
+export function judgeGroupTargets(
+  group: { key: string; tasks: number; leadTime: { count: number; p50Ms: number }; workTime: { count: number; p50Ms: number }; waitTime: { count: number; p50Ms: number } },
+  targets: readonly TwinTargetSpec[] | undefined
+): TargetVerdict[] {
+  const value = (metric: TwinMetricId): number | undefined => {
+    switch (metric) {
+      case 'throughput.tasks':
+        return group.tasks
+      case 'leadTime.p50Ms':
+        return group.leadTime.count > 0 ? group.leadTime.p50Ms : undefined
+      case 'workTime.p50Ms':
+        return group.workTime.count > 0 ? group.workTime.p50Ms : undefined
+      case 'waitTime.p50Ms':
+        return group.waitTime.count > 0 ? group.waitTime.p50Ms : undefined
+      default:
+        return undefined // 축 단위로 뜻이 없는 지표(주문 수·자원 점유) — 지어내지 않는다
+    }
+  }
+  const out: TargetVerdict[] = []
+  for (const t of targets ?? []) {
+    const spec = TWIN_METRIC[t.metric]
+    const actual = value(t.metric)
+    if (!spec || typeof actual !== 'number' || !Number.isFinite(actual) || !Number.isFinite(t.target)) continue
+    out.push(verdictOf(t.metric, actual, t.target, spec.direction))
+  }
+  return out
+}
+
+export function mergeTargets(
+  rows: readonly TargetRow[],
+  scope: { spaceId?: string; instanceIds: readonly string[]; axis?: string }
+): TwinTargetSpec[] {
+  return scopedTargets(rows, scope).overall
+}
+
+/** 저장된 목표 행 — 판단에 필요한 것만(엔티티 전체를 요구하지 않는다: 테스트가 값싸진다). */
+export interface TargetRow {
+  metric: string
+  target: number
+  spaceId?: string | null
+  instanceId?: string | null
+  axis?: string | null
+  axisKey?: string | null
+}
+
+/** 전체 목표와 축 목표를 함께 고른다 — 좁은 선언(인스턴스)이 넓은 선언(공간)을 덮는 규칙은 양쪽 같다. */
+export function scopedTargets(
+  rows: readonly TargetRow[],
+  scope: { spaceId?: string; instanceIds: readonly string[]; axis?: string }
+): ScopedTargets {
+  /* 같은 자리(지표 또는 축값+지표)에 공간·인스턴스 목표가 함께 있으면 인스턴스가 이긴다. */
+  const pick = new Map<string, { target: number; fromInstance: boolean; axisKey?: string; metric: TwinMetricId }>()
+  for (const r of rows) {
+    if (!isTwinMetric(r.metric) || typeof r.target !== 'number' || !Number.isFinite(r.target)) continue
+    const inSpace = !!scope.spaceId && r.spaceId === scope.spaceId
+    const inInstance = !!r.instanceId && scope.instanceIds.includes(r.instanceId)
+    if (!inSpace && !inInstance) continue
+    if (r.axis) {
+      if (!scope.axis || r.axis !== scope.axis || !r.axisKey) continue // 지금 보는 축만
+    }
+    const slot = `${r.axis ?? ''}\u0000${r.axisKey ?? ''}\u0000${r.metric}`
+    const prev = pick.get(slot)
+    if (prev?.fromInstance && !inInstance) continue // 인스턴스 선언을 공간 선언이 덮지 않는다
+    pick.set(slot, { target: r.target, fromInstance: inInstance, axisKey: r.axisKey ?? undefined, metric: r.metric })
+  }
+  const overall: TwinTargetSpec[] = []
+  const byAxisKey: Record<string, TwinTargetSpec[]> = {}
+  for (const [slot, v] of pick) {
+    const spec = { metric: v.metric, target: v.target }
+    if (slot.startsWith('\u0000')) overall.push(spec)
+    else (byAxisKey[v.axisKey as string] ??= []).push(spec)
+  }
+  return { overall, byAxisKey }
+}
+
+/** 목표 하나 — 어느 지표를, 얼마로. 방향은 지표가 안다(§TWIN_METRIC). */
+export interface TwinTargetSpec {
+  metric: TwinMetricId
+  target: number
+}
+
+export interface TargetVerdict {
+  metric: TwinMetricId
+  /** 이 구간의 실제 값. */
+  actual: number
+  target: number
+  direction: 'higher' | 'lower'
+  /** 목표를 만족했나. */
+  met: boolean
+  /**
+   * 목표 대비 비율 — **항상 "1 이상이면 좋다"** 로 정규화한다(방향이 다른 지표를 한 화면에서 비교할 수
+   * 있게). 처리량은 `actual/target`, 시간은 `target/actual`.
+   */
+  ratio: number
+}
+
+/**
+ * 목표 대비 판정 — **목표가 없는 지표는 판정하지 않는다.**
+ *
+ * 값이 없는 지표(그 구간에 기록이 없어 `undefined`)도 판정하지 않는다. 없는 것을 0 으로 놓으면
+ * "목표 크게 미달" 이라는 **없는 사실**이 만들어지고, 사용자는 멈춘 적 없는 라인을 고치러 간다.
+ * 목표를 0 으로 준 경우도 비율을 내지 않는다(0 으로 나누지 않는다) — 만족 여부만 답한다.
+ */
+export function judgeTargets(kpi: KpiResult, targets: readonly TwinTargetSpec[] | undefined): TargetVerdict[] {
+  const out: TargetVerdict[] = []
+  for (const t of targets ?? []) {
+    const spec = TWIN_METRIC[t.metric]
+    if (!spec) continue // 모르는 지표 이름 — 짐작해 매핑하지 않는다
+    const actual = spec.of(kpi)
+    if (typeof actual !== 'number' || !Number.isFinite(actual)) continue // 값이 없다 ≠ 값이 0
+    if (!Number.isFinite(t.target)) continue
+    out.push(verdictOf(t.metric, actual, t.target, spec.direction))
+  }
+  return out
+}
+
+/** 판정 산수 한 곳 — 전체 판정과 축 판정이 **같은 규칙**을 쓴다(두 벌이면 갈라진다). */
+function verdictOf(metric: TwinMetricId, actual: number, target: number, direction: 'higher' | 'lower'): TargetVerdict {
+  const met = direction === 'higher' ? actual >= target : actual <= target
+  const ratio = direction === 'higher' ? (target > 0 ? actual / target : Number.NaN) : actual > 0 ? target / actual : Number.NaN
+  return { metric, actual, target, direction, met, ratio }
+}

package/server/engine/live-attentions.ts

@@ -6,10 +6,20 @@
  */
 import { deriveAttentions } from '@operato/twin-kernel'
 
-export function withLiveAttentions<S extends { movers?: any[]; nodes?: any[]; orders?: any[]; attentions?: any[] }>(state: S): S {
+export function withLiveAttentions<S extends { equipment?: any[]; locations?: any[]; orders?: any[]; tasks?: any[]; attentions?: any[]; nowTime?: string }>(
+  state: S
+): S {
   if (!state) return state
   return {
     ...state,
-    attentions: deriveAttentions({ movers: state.movers ?? [], nodes: state.nodes ?? [], orders: state.orders ?? [] })
+    /*
+     * 입력을 **시뮬 쪽과 똑같이** 넣는다. 한쪽만 빠지면 같은 공장이 한쪽에서만 막힌 것처럼 보이고,
+     * 그 어긋남은 규칙이 아니라 배선 때문이라 아무 데서도 안 잡힌다(`tasks` 를 빠뜨려 실제로 그럴 뻔했다).
+     */
+    attentions: deriveAttentions(
+      { equipment: state.equipment ?? [], locations: state.locations ?? [], orders: state.orders ?? [], tasks: state.tasks ?? [] },
+      undefined,
+      state.nowTime
+    )
   }
 }

package/server/engine/measured-estimator.ts

@@ -0,0 +1,91 @@
+/*
+ * 실측 소요 추정기 — **이력에서 배운 값이 상수·선언값을 이긴다.**
+ *
+ * 배경(operato-twin design/plans/simulation-spec.md §5-4): 소요시간을 명세로 받을 수 있게 됐지만
+ * 명세는 선언이다 — 그 현장에서 실제로 얼마 걸리는지는 저널이 안다. `gap-analytics` 는 지표 수준의
+ * 편향만 배웠고(예측값 보정), **공정별 소요를 추정기로 되먹이는 경로는 없었다.**
+ *
+ * 여기서 하는 일: KPI 폴드가 작업 종류별로 낸 **작업시간(착수→완료) p50** 을 그 종류의 소요로 쓴다.
+ * 리드타임(생성→완료)이 아니라 작업시간을 쓰는 이유: 리드타임에는 **대기가 섞여 있고**, 대기는
+ * 시뮬레이션이 자원 경합으로 스스로 만들어야 하는 값이다. 대기를 소요에 넣으면 이중 계산이 된다.
+ *
+ * **평균만 배우면 대기와 병목을 과소평가한다.** 소요가 늘 정확히 같으면 줄이 생기지 않는다 — 현장의
+ * 줄은 흔들림에서 나온다. 그래서 p50 만이 아니라 **관측된 퍼짐(p10..p90)** 을 함께 넘기고, 표본은
+ * 커널이 자기 난수로 뽑는다(fork 결정성). 양쪽 꼬리를 다 관측에서 가져오는 이유: p90 만 있으면
+ * 아래쪽을 위쪽에서 거울처럼 베껴야 하는데 그건 발명이다.
+ *
+ * 정직 규율:
+ *  - 표본이 적으면 쓰지 않는다(`minSamples`). 한두 건의 p50 은 그 현장의 값이 아니다.
+ *  - 'unknown' 축은 쓰지 않는다 — 종류를 모르는 기록을 특정 종류의 근거로 삼을 수 없다.
+ *  - 퍼짐이 성립하지 않으면(p10 ≥ p90, 또는 0) **퍼짐 없이 평균만** 넘긴다. 없는 흔들림을 만들지 않는다.
+ *  - 무엇을 배웠고 무엇을 표본 부족으로 버렸는지 함께 낸다(조용히 일부만 반영하지 않는다).
+ */
+
+/** 커널 `DurationEstimate` 와 같은 모양(커널 타입에 의존하지 않기 위해 구조로 맞춘다). */
+export interface MeasuredEstimate {
+  meanMs: number
+  spread?: { distribution: 'triangular'; minMs: number; maxMs: number; modeMs: number }
+}
+
+export interface MeasuredEstimatorResult {
+  estimator?: {
+    estimate(ctx: { kind: string; fromNode: string; toNode: string; resourceKind?: string }): MeasuredEstimate | undefined
+  }
+  /** 작업 종류 → 실측 소요(ms). 추정기가 답하는 종류들. */
+  learned: Record<string, number>
+  /** 퍼짐까지 배운 종류 — 평균만 배운 것과 구별한다(변동 없는 소요는 대기를 과소평가한다). */
+  spreads: Record<string, { minMs: number; maxMs: number }>
+  /** 표본이 모자라 쓰지 않은 종류와 그 건수 — 배우지 못한 것을 밝힌다. */
+  skipped: { kind: string; count: number }[]
+  minSamples: number
+}
+
+/** 기본 표본 하한 — 이보다 적으면 그 종류는 배우지 않는다(작은 표본의 p50 을 현장 값으로 승격 금지). */
+export const DEFAULT_MIN_SAMPLES = 5
+
+/**
+ * 작업 종류별 KPI 그룹에서 추정기를 만든다(순수 — DB·커널 모름).
+ * `groups` 는 `computeTwinKpi({ groupBy: 'taskKind' })` 의 `groups.items` 를 그대로 넘긴다.
+ */
+export function buildMeasuredEstimator(
+  groups: { key: string; workTime?: { count: number; p10Ms?: number; p50Ms: number; p90Ms?: number } }[] | undefined,
+  opts: { minSamples?: number } = {}
+): MeasuredEstimatorResult {
+  const minSamples = opts.minSamples ?? DEFAULT_MIN_SAMPLES
+  const learned: Record<string, number> = {}
+  const spreads: Record<string, { minMs: number; maxMs: number }> = {}
+  const estimates: Record<string, MeasuredEstimate> = {}
+  const skipped: { kind: string; count: number }[] = []
+  for (const g of groups ?? []) {
+    if (!g?.key || g.key === 'unknown') continue
+    const w = g.workTime
+    const count = w?.count ?? 0
+    const p50 = w?.p50Ms ?? 0
+    if (count < minSamples || !(p50 > 0)) { skipped.push({ kind: g.key, count }); continue }
+    const mean = Math.round(p50)
+    learned[g.key] = mean
+    /* 퍼짐은 **관측된 두 꼬리**로만 만든다. 한쪽이라도 없거나 구간이 성립하지 않으면 평균만 넘긴다. */
+    const lo = w?.p10Ms
+    const hi = w?.p90Ms
+    if (typeof lo === 'number' && typeof hi === 'number' && lo > 0 && hi > lo) {
+      const minMs = Math.round(lo)
+      const maxMs = Math.round(hi)
+      spreads[g.key] = { minMs, maxMs }
+      estimates[g.key] = { meanMs: mean, spread: { distribution: 'triangular', minMs, maxMs, modeMs: mean } }
+    } else {
+      estimates[g.key] = { meanMs: mean }
+    }
+  }
+  if (!Object.keys(learned).length) return { learned, spreads, skipped, minSamples }
+  return {
+    learned,
+    spreads,
+    skipped,
+    minSamples,
+    estimator: {
+      estimate(ctx) {
+        return estimates[ctx.kind]
+      }
+    }
+  }
+}

package/server/engine/model-basis.ts

@@ -0,0 +1,94 @@
+/*
+ * 모델 근거 — **배운 모델에만 보정을 적용하기 위한 비교.**
+ *
+ * 예측 출력 보정(P3.2 `twinLearnCalibration`)은 "우리 모델이 늘 이만큼 적게 본다" 를 배워 결과를
+ * 밀어 준다. 그 학습은 **그때의 모델**을 전제로 한다. 그런데 소요시간 추정기(실측·거리계산)와 공정
+ * 명세가 들어오면서 모델 자체가 바뀔 수 있게 됐다 — 모델이 이미 그 편향을 잃었는데 보정이 또 밀어
+ * 주면 **이중 보정**이 되어 정확도가 나빠진다. 학습 시점의 accAfter 도 더는 유효하지 않다.
+ *
+ * 그래서 보정 기록에 **그때 모델의 근거**를 함께 남기고, 적용 전에 지금 근거와 비교한다. 달라졌으면
+ * 적용하지 않고 **그 사실을 응답에 싣는다**(조용히 사라지면 사용자는 학습이 왜 안 듣는지 모른다).
+ *
+ * 비교는 **상대 허용오차**로 한다(양자화 지문이 아니라). 실측 p50 은 새 기록이 쌓일 때마다 1~2초씩
+ * 흔들리는데, 값을 버킷으로 뭉개 비교하면 버킷 경계에 걸린 값이 1초 드리프트로도 달라져 버린다 —
+ * "작은 드리프트로 학습을 무효화하지 않는다" 는 목적을 경계에서 못 지킨다. 비율로 비교하면 어디서든
+ * 같은 규칙이 성립한다: 10% 이내는 같은 모델, 30초→47초(57%)는 다른 모델.
+ *
+ * 재료는 호스트가 아는 것들이다(커널 API 에 의존하지 않아 발행 상태와 무관하게 동작한다):
+ *  ① 실측으로 배운 작업 종류별 소요 ② 자원 종류별 속도 ③ 선언된 공정 소요.
+ */
+
+/** 같은 모델로 볼 상대 허용오차 — 이 비율 안의 변화는 드리프트, 넘으면 다른 모델. */
+export const BASIS_TOLERANCE = 0.1
+
+export interface ModelBasis {
+  /** 작업 종류 → 실측 소요(ms). `buildMeasuredEstimator().learned`. */
+  measured?: Record<string, number>
+  /** 자원 종류 → 속도(m/s). `buildTravelEstimator().speedsByKind`. */
+  speeds?: Record<string, number>
+  /** 선언된 공정 소요 — key + ISO 8601 원문(문자열은 그대로 비교한다: 선언이 바뀌면 다른 모델). */
+  declared?: { key: string; duration?: string }[]
+}
+
+/** 뜻 있는 수만 남긴다 — 0·음수·NaN 은 모델이 아니다. */
+function clean(map?: Record<string, number>): Record<string, number> {
+  const out: Record<string, number> = {}
+  for (const [k, v] of Object.entries(map ?? {})) if (Number.isFinite(v) && v > 0) out[k] = v
+  return out
+}
+
+function declaredMap(list?: { key: string; duration?: string }[]): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const o of list ?? []) if (o?.key && o.duration) out[o.key] = o.duration
+  return out
+}
+
+/** 두 수치 지도가 실질적으로 다른가 — 키 집합이 다르거나, 값이 허용오차를 넘어 다르면 다르다. */
+function numericChanged(a: Record<string, number>, b: Record<string, number>, tol: number): boolean {
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)])
+  for (const k of keys) {
+    const x = a[k]
+    const y = b[k]
+    if (x === undefined || y === undefined) return true // 새로 배운 종류·사라진 종류 = 다른 모델
+    const base = Math.max(Math.abs(x), Math.abs(y))
+    if (base > 0 && Math.abs(x - y) / base > tol) return true
+  }
+  return false
+}
+
+/**
+ * 모델이 달라졌는가 — 보정을 적용하기 전의 관문.
+ * 한쪽 근거를 모르면 **판정하지 않는다**(false) — 모르는 것을 근거로 학습을 끊지 않는다.
+ */
+export function modelBasisChanged(before?: ModelBasis, after?: ModelBasis, tol: number = BASIS_TOLERANCE): boolean {
+  if (!before || !after) return false
+  if (numericChanged(clean(before.measured), clean(after.measured), tol)) return true
+  if (numericChanged(clean(before.speeds), clean(after.speeds), tol)) return true
+  const da = declaredMap(before.declared)
+  const db = declaredMap(after.declared)
+  const keys = new Set([...Object.keys(da), ...Object.keys(db)])
+  for (const k of keys) if (da[k] !== db[k]) return true
+  return false
+}
+
+/**
+ * 사람이 읽는 근거 요약 — **로그·진단용**(비교의 근거가 아니다).
+ * 지문으로 같음을 판정하지 않는 이유는 위 주석 참조. 두 근거가 왜 달라졌는지 눈으로 보려면 이것을 찍는다.
+ */
+export function describeModelBasis(basis?: ModelBasis): string {
+  if (!basis) return 'unknown'
+  const seg: string[] = []
+  const m = Object.entries(clean(basis.measured))
+    .map(([k, v]) => `${k}=${Math.round(v / 1000)}s`)
+    .sort()
+  if (m.length) seg.push(`measured(${m.join(',')})`)
+  const s = Object.entries(clean(basis.speeds))
+    .map(([k, v]) => `${k}=${Math.round(v * 10) / 10}m/s`)
+    .sort()
+  if (s.length) seg.push(`speed(${s.join(',')})`)
+  const d = Object.entries(declaredMap(basis.declared))
+    .map(([k, v]) => `${k}=${v}`)
+    .sort()
+  if (d.length) seg.push(`declared(${d.join(',')})`)
+  return seg.length ? seg.join(' ') : 'kernel defaults only'
+}

package/server/engine/oee-accumulator.ts

@@ -2,7 +2,7 @@
  * OEE 이벤트 누적기 (순수·근사) — live-모드 OEE 입력 생산의 한 경로(face2-inbound-live §1.1, option ②).
  *
  * 문제: OEE 공식(computeOee)은 sim/live 공유되나, 입력 카운터(runMs/downMs/…)는 미러 State·이벤트에 없다
- *   (emitMover 는 status/location/motion 만 방출). → live 는 카운터를 별도 생산해야 한다.
+ *   (emitEquipment 는 status/location/motion 만 방출). → live 는 카운터를 별도 생산해야 한다.
  * 이 누적기: equipment.status 전이 스트림으로 무버별 시간-in-상태를 누적해 카운터를 근사 생산.
  *
  * 정확: downMs(고장 시간 = down 구간 합) · quality(good/scrap = quality.output 델타). 근사·한계:
@@ -79,10 +79,10 @@ export class OeeAccumulator {
 
 /**
  * live State 를 OEE 로 보강 — projector 미러 State(관측)의 무버에 누적기 OEE(계산)를 채운다.
- * live-모드 publishEntityData 가 buildEntityDeltas 전에 적용 → mover data(tag) payload 에 oee 포함
+ * live-모드 publishEntityData 가 buildEntityDeltas 전에 적용 → equipment data(tag) payload 에 oee 포함
  * (sim 은 커널이 채움 — 이로써 live 도 동일 payload 형상). 순수(입력 불변, 얕은 복사).
  */
-export function withLiveOee<S extends { movers?: any[] }>(state: S, acc: OeeAccumulator, nowMs?: number): S {
-  if (!state?.movers) return state
-  return { ...state, movers: state.movers.map(m => ({ ...m, oee: acc.oee(m.id, nowMs) })) }
+export function withLiveOee<S extends { equipment?: any[] }>(state: S, acc: OeeAccumulator, nowMs?: number): S {
+  if (!state?.equipment) return state
+  return { ...state, equipment: state.equipment.map(m => ({ ...m, oee: acc.oee(m.id, nowMs) })) }
 }

package/server/engine/spec-coverage.ts

@@ -0,0 +1,85 @@
+/*
+ * 시뮬 명세 자기보고 — **"이 예측으로 무엇을 말할 수 있나" 를 예측과 함께 내보낸다.**
+ *
+ * 배경(operato-twin design/plans/simulation-spec.md): 공정 소요·수율이 커널 소스의 상수였다. 이제
+ * 마스터가 명세를 실어 오면 커널이 그것으로 굴리고, `specCoverage()` 가 무엇을 선언값으로 무엇을
+ * 기본값으로 썼는지 보고한다. 그 보고를 **예측 응답에 붙이지 않으면** 받는 쪽은 상수로 굴린 숫자와
+ * 현장 명세로 굴린 숫자를 구별할 수 없다 — 똑같이 "p50 168" 로 보인다.
+ *
+ * 언어 중립: 여기서는 **코드와 수치만** 낸다(`qualification` + 카운트). 사람이 읽는 문장은 표현
+ * 계층(클라 i18next / AI 답변)이 만든다 — attention 과 같은 규율.
+ */
+
+/** 예측 자격 — 선언된 명세가 얼마나 덮는지에 따라 이 예측으로 정당하게 말할 수 있는 범위가 달라진다. */
+export type ForecastQualification =
+  /** 모든 소요가 커널 기본 상수 → **상대 비교만**("자원 2대 더 넣으면 나아지나"). 절대 시각 주장 불가. */
+  | 'relative'
+  /** 일부만 선언·실측 → 그 구간은 접지, 나머지는 상수. 혼합. */
+  | 'partial'
+  /** 소요 전부 선언 → 절대 예측 시도 가능. 단 **정확도는 이력이 확인한다**(선언 != 검증). */
+  | 'absolute-capable'
+  /**
+   * 소요 전부가 **이 현장의 이력에서 온 값**(추정기) → 가장 강한 근거. 선언은 사람이 적은 값이고
+   * 이것은 실제로 일어난 값이다. 그래도 "정확하다" 가 아니라 "관측에 접지됐다" 는 뜻이다.
+   */
+  | 'calibrated'
+
+export interface SpecCoverageReport {
+  operations: { kind: string; duration: 'measured' | 'declared' | 'default'; variability?: string; parameters: string[] }[]
+  /** 이력·계산에서 온 소요(추정기) — 선언값보다 강한 근거. */
+  measuredDurations: number
+  declaredDurations: number
+  defaultDurations: number
+  /** 변동(분포)을 가진 작업 종류 수. **0 이면 모든 소요가 고정값**이라 대기·병목이 과소평가된다. */
+  varyingDurations: number
+  qualification: ForecastQualification
+}
+
+/**
+ * 명세 자격 판정(순수) — 커널 보고를 받아 분류한다. 커널을 모르므로 테스트가 쉽다.
+ * 관측된 작업이 하나도 없으면(`operations` 빈 배열) 판정할 근거가 없으므로 **undefined**(모른다).
+ */
+export function classifySpecCoverage(cov: {
+  operations?: { kind: string; duration: 'measured' | 'declared' | 'default'; variability?: string; parameters?: string[] }[]
+  measuredDurations?: number
+  declaredDurations?: number
+  defaultDurations?: number
+}): SpecCoverageReport | undefined {
+  const ops = cov?.operations
+  if (!ops?.length) return undefined
+  const operations = ops.map(o => ({
+    kind: o.kind,
+    duration: o.duration,
+    ...(o.variability ? { variability: o.variability } : {}),
+    parameters: o.parameters ?? []
+  }))
+  const measuredDurations = cov.measuredDurations ?? operations.filter(o => o.duration === 'measured').length
+  const declaredDurations = cov.declaredDurations ?? operations.filter(o => o.duration === 'declared').length
+  const defaultDurations = cov.defaultDurations ?? operations.filter(o => o.duration === 'default').length
+  const varyingDurations = operations.filter(o => o.variability && o.variability !== 'constant').length
+  /* 사다리: 전부 이력 → calibrated · 상수 없음 → absolute-capable · 접지가 하나도 없음 → relative · 나머지 → partial. */
+  const grounded = measuredDurations + declaredDurations
+  const qualification: ForecastQualification =
+    grounded === 0
+      ? 'relative'
+      : defaultDurations > 0
+        ? 'partial'
+        : declaredDurations === 0
+          ? 'calibrated'
+          : 'absolute-capable'
+  return { operations, measuredDurations, declaredDurations, defaultDurations, varyingDurations, qualification }
+}
+
+/**
+ * 커널에서 읽는다 — **아직 이 API 가 없는 커널(발행 이전)이면 undefined.**
+ * 그때 `undefined` 는 "명세가 없다" 가 아니라 "모른다" 다. 소비처가 그 둘을 섞지 않도록 주석을 남긴다:
+ * 없는 것을 "전부 기본값" 이라고 단정하지 않는다(단정하려면 커널이 말해 줘야 한다).
+ */
+export function readSpecCoverage(kernel: any): SpecCoverageReport | undefined {
+  if (typeof kernel?.specCoverage !== 'function') return undefined
+  try {
+    return classifySpecCoverage(kernel.specCoverage())
+  } catch {
+    return undefined
+  }
+}

package/server/engine/structure-diff.ts

@@ -0,0 +1,88 @@
+/*
+ * 구조 이력의 **차이** — "2번째에 도장 부스가 넷 늘었다" 를 말할 수 있게.
+ *
+ * 리비전은 그 시절 공장을 통째로 담는다(재생하려면 전체 위상이 필요하다). 그런데 사람이 보고 싶은
+ * 것은 통째가 아니라 **무엇이 달라졌나** 다 — 62KB 짜리 보드 두 개를 나란히 놓고 눈으로 비교할 수는
+ * 없다. 그 한 줄을 여기서 만든다.
+ *
+ * 순수 함수인 이유: 같은 문장을 화면과 AI 가 함께 써야 한다. 한쪽에서만 계산하면 둘이 다른 말을 한다.
+ */
+
+/** 종류별 증감 — "paint-booth +4" 처럼 읽힌다. */
+export interface StructureCountChange {
+  key: string
+  before: number
+  after: number
+  delta: number
+}
+
+export interface StructureDiff {
+  /** 자리 종류별 증감(0 인 것은 빼고). */
+  locationTypes: StructureCountChange[]
+  /** 설비 종류별 증감(0 인 것은 빼고). */
+  equipmentKinds: StructureCountChange[]
+  locationsAdded: number
+  locationsRemoved: number
+  equipmentAdded: number
+  equipmentRemoved: number
+  /** 개수는 같은데 내용이 바뀐 경우(용량 조정·자리 이동 등)가 있는가. */
+  changedInPlace: boolean
+}
+
+const countBy = <T>(rows: readonly T[] | undefined, key: (r: T) => string | undefined): Map<string, number> => {
+  const out = new Map<string, number>()
+  for (const r of rows ?? []) {
+    const k = key(r)
+    if (k) out.set(k, (out.get(k) ?? 0) + 1)
+  }
+  return out
+}
+
+const idsOf = (rows: readonly { id?: string }[] | undefined): Set<string> => new Set((rows ?? []).map(r => r.id).filter((x): x is string => !!x))
+
+function changes(before: Map<string, number>, after: Map<string, number>): StructureCountChange[] {
+  const keys = [...new Set([...before.keys(), ...after.keys()])].sort()
+  return keys
+    .map(key => ({ key, before: before.get(key) ?? 0, after: after.get(key) ?? 0, delta: (after.get(key) ?? 0) - (before.get(key) ?? 0) }))
+    .filter(c => c.delta !== 0)
+}
+
+/**
+ * 두 구조의 차이. `before` 가 없으면 **최초 리비전**이라 비교 대상이 없다 — 전부 새로 생긴 것으로 센다.
+ *
+ * 아이디는 **집합으로** 비교한다(수만 세면 넷이 사라지고 넷이 생긴 교체를 "변화 없음" 으로 답한다).
+ */
+export function diffStructures(before: any | undefined, after: any): StructureDiff {
+  const beforeLocations = before?.locations ?? []
+  const beforeEquipment = before?.equipment ?? []
+  const afterLocations = after?.locations ?? []
+  const afterEquipment = after?.equipment ?? []
+
+  const beforeLocationIds = idsOf(beforeLocations)
+  const afterLocationIds = idsOf(afterLocations)
+  const beforeEquipmentIds = idsOf(beforeEquipment)
+  const afterEquipmentIds = idsOf(afterEquipment)
+
+  const added = <T>(a: Set<T>, b: Set<T>) => [...b].filter(x => !a.has(x)).length
+  const locationsAdded = added(beforeLocationIds, afterLocationIds)
+  const locationsRemoved = added(afterLocationIds, beforeLocationIds)
+  const equipmentAdded = added(beforeEquipmentIds, afterEquipmentIds)
+  const equipmentRemoved = added(afterEquipmentIds, beforeEquipmentIds)
+
+  /*
+   * 아이디는 그대로인데 속성이 바뀐 경우 — 용량을 늘렸거나 설비를 옮겼다. 지문이 달라 새 리비전이
+   * 생겼는데 증감이 전부 0 이면, 화면이 "바뀐 게 없다" 고 답하게 된다. 그런 침묵을 막는다.
+   */
+  const changedInPlace =
+    !locationsAdded && !locationsRemoved && !equipmentAdded && !equipmentRemoved && !!before
+
+  return {
+    locationTypes: changes(countBy(beforeLocations, (n: any) => n.type), countBy(afterLocations, (n: any) => n.type)),
+    equipmentKinds: changes(countBy(beforeEquipment, (m: any) => m.kind), countBy(afterEquipment, (m: any) => m.kind)),
+    locationsAdded,
+    locationsRemoved,
+    equipmentAdded,
+    equipmentRemoved,
+    changedInPlace
+  }
+}