@things-factory/headless-twin 10.1.277 → 10.1.279

package/server/engine/model-gap.ts

@@ -1,168 +0,0 @@
-/*
- * **원본이 말한 적 없는 것** — 미해결 참조를 세는 한 자리. 순수(import 없음).
- *
- * ── 무엇을 답하나 ───────────────────────────────────────────────────────────
- * 원천이 우리 모델에 없는 id 를 보내면 어떻게 되나. 유입 문(`ingestCanonicalRecords`)은 **거부하지
- * 않는다** — 실측으로 확인했다(2026-08-20):
- *
- *   모르는 로케이션 「오타-99」        → 통과
- *   모르는 bizStep 「PUTAWAY_X17」   → 통과
- *   모르는 계량기 「MMXU-오타-99」    → 통과
- *
- * 거부하지 않는 것이 옳다. 원천이 모델보다 먼저 새 로케이션을 말하는 것은 정상이고(구조 갱신은 늦게 온다),
- * 거부하면 그 선행 계측을 잃는다. 그래서 커널은 **흡수하고 표시한다** — 마스터에 없던 로케이션은
- * `origin: 'observed'` 로 승격되어 스냅샷에 실린다(`ObservedReducer.touchLocation`).
- *
- * ── 왜 이 파일이 있나 ───────────────────────────────────────────────────────
- * 그 표시를 읽는 곳이 **모델 인스펙션 화면 하나**였다. 그런데 이 사실을 필요로 하는 사람은 「이 트윈이
- * 현장과 맞춰지고 있나」를 보는 사람이다 — 원천이 우리가 모르는 로케이션만 보내고 있으면 트윈은 도는데
- * 스키매틱은 비어 있고, 그것이 우리가 「빈 공장」이라 불러 온 상태다.
- *
- * 도출을 두 곳에 적으면 두 화면이 다른 수를 말하게 된다. 그래서 여기 한 벌만 둔다.
- *
- * ── 판정을 바꾸지 않는다 ────────────────────────────────────────────────────
- * 동기화 판정(`syncVerdictOf`)은 **피드**를 말한다: 오고 있나, 통과하나. 이 갭은 **모델**을 말한다:
- * 원천이 아는 것을 우리가 선언했나. 둘을 한 판정에 섞으면 「유입은 정상인데 모델이 뒤처졌다」와
- * 「유입이 막혔다」가 같은 색으로 보이고, 처방이 완전히 다르다.
- */
-
-/** 커널 스냅샷에서 우리가 읽는 것만. 나머지 필드는 알 필요가 없다. */
-export interface ModelGapSource {
-  locations?: { id?: string; origin?: string }[]
-  equipment?: { id?: string; origin?: string }[]
-  persons?: { id?: string; origin?: string }[]
-  /** 커널이 담을 줄 몰라 세어 둔 사건 — 종류별 개수와 처음·마지막 시각. */
-  unhandled?: { eventType: string; count: number; firstAtMs?: number; lastAtMs?: number }[]
-  /**
-   * EMS 상태 — **`energy` 안에 있다.**
-   *
-   * `unknownEquipment` 를 루트에서 읽고 있었다(2026-08-20에 잡음). 커널은 그것을 `EnergyState` 안에
-   * 담으므로, 루트에서 읽으면 **영원히 `null`** 이다 — 오류도 없이 「에너지 트윈이 아니다」로 읽힌다.
-   * 나만 읽는 필드를 잘못된 경로에서 읽으면 이렇게 오류 없이 사라진다.
-   *
-   * 계량 지점의 `origin` 은 **없을 수 있다**(옛 스냅샷에서 이어받은 지점). 그때는 「선언되었다」가
-   * 아니라 **모른다**다.
-   */
-  energy?: {
-    points?: { id?: string; origin?: string }[]
-    /** 모델이 모르는 설비가 에너지 상태를 보내 온 횟수. 0 이면 커널이 이 칸을 만들지 않는다. */
-    unknownEquipment?: number
-  }
-}
-
-/**
- * 화면에 내는 id 수 상한.
- *
- * 오타 하나를 찾는 데 스무 개면 충분하고, 원천이 수천 개를 보내는 경우(모델을 아예 안 맞춘 경우)에
- * 목록으로 화면을 채울 이유가 없다. **넘친 수는 함께 낸다** — 알리지 않고 자르지 않는다.
- */
-export const GAP_ID_LIMIT = 20
-
-export interface ModelGapAxis {
-  /** 관측으로만 알게 된 id 수. */
-  count: number
-  /** 그중 화면에 싣는 것(최대 `GAP_ID_LIMIT`). */
-  ids: string[]
-  /** 상한에서 밀려난 수. 0 이면 전부 실었다. */
-  more: number
-  /**
-   * 출처를 **모르는** 수 — 표시가 없는 항목.
-   *
-   * 「선언되었다」로 세지 않는다. 계량기는 이 표시가 늦게 생겼으므로 옛 스냅샷에서 이어받은 지점에는
-   * 칸이 없다(`undefined`). 그것을 마스터로 세면 오타를 놓치고, 관측으로 세면 정상을 문제로 만든다.
-   * 둘 다 틀리므로 **모른다고 센다.**
-   */
-  unknown: number
-}
-
-export interface ModelGapView {
-  locations: ModelGapAxis
-  equipment: ModelGapAxis
-  persons: ModelGapAxis
-  /**
-   * EMS 계량 지점.
-   *
-   * ── 이 축이 가장 무겁다 ────────────────────────────────────────────────────
-   * 모르는 `meterId` 는 알리지 않고 새 계량기가 되고 그 kW 가 그 현장의 **수요 구간·피크·요금 판정**에
-   * 더해진다. 오타 하나면 진짜 계량기는 멈추고 유령이 누적된다 — 숫자는 그럴듯하고 틀린다. 자리 오타는
-   * 스키매틱이 비는 것으로 드러나지만, 이건 그럴듯한 숫자로 나온다.
-   *
-   * 커널이 `origin` 을 **표본마다 다시 맞춘다** — 선언의 정본은 모델이고 모델은 채택으로 늘어나므로,
-   * 한 번 찍고 두면 나중에 선언된 계량기가 영원히 `observed` 로 남는다. 그래서 이 값은 「지금 모델에
-   * 있는가」의 답이고, 「한 번 오타였다」의 답이 아니다.
-   */
-  meters: ModelGapAxis
-  /** 세 축의 합 — 화면이 「있나 없나」를 한 번에 묻기 위한 값. */
-  total: number
-  /** 커널이 담을 줄 모른 사건들(종류별). 참조 문제와 다른 사실이므로 따로 낸다. */
-  unhandled: { eventType: string; count: number; lastAt: string | null }[]
-  /** EMS: 모델이 모르는 설비의 에너지 보고 횟수. 없으면 `null`(0 과 구별한다). */
-  unknownEquipmentReports: number | null
-  /**
-   * 아직 덮지 못하는 축 — **모르는 것을 모른다고 말한다.**
-   *
-   * 계량기는 커널 0.7.39 부터 덮인다(그 전에는 `origin` 표시가 없어 오타를 찾아 줄 수 없었다).
-   * 비어 있는 것이 정상이고, 새 축이 표시 없이 들어오면 여기에 이름을 넣는다 — 화면이 「다 찾아
-   * 준다」고 말하지 않게.
-   */
-  notCovered: string[]
-}
-
-/** 계량기 축이 아직 덮이지 않는 이유 — 화면이 그대로 말할 수 있게 이름을 여기 둔다. */
-export const NOT_COVERED_METERS = 'meters'
-
-function axisOf(rows: { id?: string; origin?: string }[] | undefined): ModelGapAxis {
-  const ids: string[] = []
-  let count = 0
-  let unknown = 0
-  for (const r of rows ?? []) {
-    if (r?.origin === 'observed') {
-      count++
-      if (ids.length < GAP_ID_LIMIT) ids.push(String(r.id ?? ''))
-    } else if (r?.origin !== 'master') {
-      /* 표시가 없다 — 마스터로도 관측으로도 세지 않는다. 모르는 것은 모른다고 센다. */
-      unknown++
-    }
-  }
-  return { count, ids, more: Math.max(0, count - ids.length), unknown }
-}
-
-/**
- * 스냅샷 → 모델 갭.
- *
- * 스냅샷이 없으면 `null` 이다 — **0 이 아니다.** 트윈이 돌지 않으면 비교할 상대가 없고, 「없다」와
- * 「세어 보지 못했다」는 다른 사실이다(모델 인스펙션이 같은 규율을 쓴다).
- */
-export function modelGapOf(snapshot: ModelGapSource | null | undefined): ModelGapView | null {
-  if (!snapshot) return null
-
-  const locations = axisOf(snapshot.locations)
-  const equipment = axisOf(snapshot.equipment)
-  const persons = axisOf(snapshot.persons)
-  const meters = axisOf(snapshot.energy?.points)
-
-  return {
-    locations,
-    equipment,
-    persons,
-    meters,
-    total: locations.count + equipment.count + persons.count + meters.count,
-    unhandled: (snapshot.unhandled ?? []).map(u => ({
-      eventType: u.eventType,
-      count: u.count,
-      /* 마지막 시각이 멈춘 종류는 이미 고쳐진 것이다. 없으면 지어내지 않는다. */
-      lastAt: Number.isFinite(u.lastAtMs) ? new Date(u.lastAtMs as number).toISOString() : null
-    })),
-    /*
-     * 커널은 0 이면 이 칸을 만들지 않는다. 그래서 「없음」은 두 뜻이다 — 에너지 트윈이 아니거나, 세었고
-     * 0 이었다. 둘을 가르려면 `energy` 자체가 있는지를 본다: 있으면 세었고 0 이다.
-     */
-    unknownEquipmentReports:
-      typeof snapshot.energy?.unknownEquipment === 'number' ? snapshot.energy.unknownEquipment : snapshot.energy ? 0 : null,
-    /*
-     * 이제 계량기도 덮는다(커널 0.7.39 가 `MeterPointState.origin` 을 낸다). 덮지 못하는 축이 생기면
-     * 다시 여기에 이름을 넣는다 — 화면이 「다 찾아 준다」고 말하지 않게.
-     */
-    notCovered: []
-  }
-}

package/server/engine/model-refusal.ts

@@ -1,31 +0,0 @@
-import { Refusal } from '@things-factory/shell'
-
-/*
- * **A twin model the kernel refuses is said by name** (ADR-0054).
- *
- * ── What went wrong (2026-10-10) ─────────────────────────────────────────────
- * The MES kernel refuses a model without a production declaration. The engine let that error through
- * as it was, so `twinReplay(miratek)` reached the screen as INTERNAL_SERVER_ERROR with the kernel's
- * English sentence in the shell's notice. The model was what was wrong, not the server.
- *
- * ── The rule ─────────────────────────────────────────────────────────────────
- * The kernel names its refusals: an error that carries a string `code` and an object `params`. The
- * kernel cannot reach the shell, so the host turns that into a shell `Refusal` here, adding which twin
- * it was. The sentence is made where the reader's language is known (`SpeakRefusals`, or the import
- * result's `refusal()`), under `error.<code>`. Anything without a name passes through untouched.
- */
-export function asModelRefusal(error: unknown, instanceId: string): unknown {
-  if (error instanceof Refusal) return error
-  const e = error as { code?: unknown; params?: unknown; message?: unknown } | null
-  if (!e || typeof e.code !== 'string' || !e.code || !e.params || typeof e.params !== 'object') return error
-  return new Refusal(e.code, { ...(e.params as Record<string, any>), instanceId }, String(e.message ?? e.code))
-}
-
-/** Run a step that loads or replays a model; a kernel refusal comes out as a `Refusal`. */
-export function refusingModel<T>(instanceId: string, step: () => T): T {
-  try {
-    return step()
-  } catch (error) {
-    throw asModelRefusal(error, instanceId)
-  }
-}

package/server/engine/model-vocabulary.ts

@@ -1,82 +0,0 @@
-/*
- * 저장된 트윈 모델의 **어휘 세대를 흡수한다** — 읽는 순간 한 어휘로. 순수.
- *
- * ── 계기 (2026-08-06, 사용자 신고) ───────────────────────────────────────────
- * 트윈 모델러의 엔티티 목록이 **통째로 비어 있었다.** 오류도 없었다. 원인은 이 인스턴스의 저장된 모델가
- * 옛 어휘였고 화면과 호스트는 새 어휘(`locations`/`equipment`)를 읽었기 때문이다. 그 옛 이름들은
- * 아래 `RETIRED_KEYS` 에 있다 — 흡수할 세대의 이름을 적지 않고는 이 파일을 쓸 수 없다.
- *
- * 커널에는 이미 세대를 흡수하는 리더가 있다(`readBoardLocations`·`readBoardEquipment` — 세 세대
- * `movers`→`equipmentList`→`equipment`, 실측 주석에 "저장된 모델 23개 중 13개가 `movers`"). 그런데 **그
- * 리더를 거치는 곳이 목록뿐**이었다. 상세·구조 서명·주행 추정기·설비 동기는 컬렉션을 직접 읽어
- * **오류 없이 빈 공장**으로 읽었다:
- *
- *  · 모델러·팔레트·보드 자동생성 → 엔티티 0(사용자가 본 증상)
- *  · 구조 서명 → `N[]M[]` — **서로 다른 두 공장이 구조적으로 같아 보인다**(변경 감지가 죽는다)
- *  · 주행 추정기 → 설비 0이라 거리 기반 소요시간을 못 만든다
- *  · 설비 동기 → 아는 설비가 0이라 중복 append + 한 모델에 두 세대가 섞인다
- *
- * ── 왜 자리마다 고치지 않나 ─────────────────────────────────────────────────
- * 저장된 모델를 읽는 자리가 **27곳**이다. 자리마다 리더를 쓰게 하면 다음에 추가되는 자리가 또 빠진다 —
- * 그리고 빠진 것은 오류가 아니라 **빈 공장**이라 들어온 것이 없다. 그래서 **DB에서 읽는 순간 한 번** 정규화한다
- * (엔티티 컬럼 변환기). 그 뒤로는 코드가 세대를 알 필요가 없다.
- *
- * ── 쓰기는 건드리지 않는다 ──────────────────────────────────────────────────
- * 저장은 주는 대로 한다(새 쓰기는 이미 새 어휘다). 읽기가 정규화되므로, 저장된 옛 모델는 **다음에
- * 저장될 때 자연히 새 어휘로 옮겨간다** — 마이그레이션을 따로 실행하지 않는다.
- */
-import { readBoardLocations, readBoardEquipment } from '@operato/ops-contract'
-
-/** 흡수하고 **내보내지 않는** 옛 키 — 남겨 두면 소비처가 두 어휘를 다시 보게 된다. */
-const RETIRED_KEYS = ['nodes', 'movers', 'equipmentList'] as const // vocabulary-guard: allow — 옛 어휘를 흡수하는 것이 이 코드의 일이다(세대 이름을 적어야 흡수할 수 있다)
-
-/** 등급 축들 — 넷이 같은 모양이라 같은 규칙을 쓴다(어느 자원이든 표시명은 `name`). */
-const CLASS_KEYS = ['personnelClasses', 'equipmentClasses', 'assetClasses', 'materialClasses'] as const
-
-/**
- * 보드를 정본 어휘로 — `locations`·`equipment` 만 남는다. 새 어휘 모델에는 **아무 일도 하지 않는다**
- * (같은 값을 다시 담을 뿐이라 멱등).
- *
- * 모델이 아닌 것(없음·배열·원시값)은 **그대로 통과**시킨다 — 모양을 짐작해 고치지 않는다.
- */
-export function canonicalModel<T = any>(model: T): T {
-  if (!model || typeof model !== 'object' || Array.isArray(model)) return model
-
-  const rest: Record<string, unknown> = {}
-  for (const [k, v] of Object.entries(model as Record<string, unknown>)) {
-    if ((RETIRED_KEYS as readonly string[]).includes(k)) continue
-    rest[k] = v
-  }
-
-  /*
-   * **등급의 표시명은 `name` 이다** — 옛 모델는 `description` 에 담았다.
-   *
-   * 표준 마스터가 등급 표시명을 `description` 으로 주기 때문에 그대로 저장돼 있었고, 화면은 그것을
-   * "설명" 열에 앉혔다 — 사용자에게는 이름인데 머리글은 설명이라, 같은 것을 축마다 다른 이름으로
-   * 부르게 된다. 인제스트 문에서 이미 `name` 으로 옮기고 있지만, **이미 저장된 모델**가 그대로 남아
-   * 새 트윈만 고쳐진다. 정규화의 집은 여기 하나다(위 머리말의 이유 그대로).
-   */
-  for (const key of CLASS_KEYS) {
-    const list = rest[key]
-    if (!Array.isArray(list)) continue
-    rest[key] = list.map((c: any) =>
-      c && typeof c === 'object' && !c.name && c.description
-        ? (({ description, ...keep }) => ({ ...keep, name: description }))(c)
-        : c
-    )
-  }
-
-  /* 리더가 세대를 고른다 — 여기서 `??` 사슬을 다시 적으면 세대 규칙이 두 곳이 된다. */
-  return { ...rest, locations: readBoardLocations(model as any), equipment: readBoardEquipment(model as any) } as T
-}
-
-/**
- * 엔티티 컬럼 변환기 — **읽을 때만** 정규화한다.
- *
- * `to`(쓰기)는 손대지 않는다: 저장은 호출부가 준 그대로가 진실이고, 읽기가 정규화되므로 다음 저장에서
- * 자연히 새 어휘가 된다.
- */
-export const modelColumnTransformer = {
-  from: (value: any) => canonicalModel(value),
-  to: (value: any) => value
-}

package/server/engine/oee-accumulator.ts

@@ -1,195 +0,0 @@
-/*
- * OEE 이벤트 누적기 (순수·근사) — live-모드 OEE 입력 생산의 한 경로(face2-inbound-live §1.1, option ②).
- *
- * 문제: OEE 공식(computeOee)은 sim/live 공유되나, 입력 카운터(runMs/downMs/…)는 미러 State·이벤트에 없다
- *   (emitEquipment 는 status/location/motion 만 방출). → live 는 카운터를 별도 생산해야 한다.
- * 이 누적기: equipment.status 전이 스트림으로 무버별 시간-in-상태를 누적해 카운터를 근사 생산.
- *
- * 정확: downMs(고장 시간 = down 구간 합) · quality(good/scrap = quality.output 델타). 근사·한계:
- *   - busyMs 를 runMs 로(setup 분리 불가 — 이벤트에 setup 없음) → performance 낙관·availability 는 setup 손실 미반영.
- *   - quality.output 이 없으면(예: WMS/YMS) quality=1(품질 개념 없음).
- * 시간축 = Date.parse(eventTime)(ms) — 구간 차분은 sim/실시간 무관하게 정확(고정 오프셋 상쇄).
- */
-/* OEE 공식은 계약에 있다 — 소비자가 셋이라(시뮬·미러·MES) 커널에 두면 밖에서 다시 쓰게 된다. */
-import { computeOee, nonWorkingMsIn } from '@operato/ops-contract'
-import type { OeeCounters, WorkCalendarEntry } from '@operato/ops-contract'
-import type { CanonicalEnvelope, OeeMetrics } from '@operato/ops-contract'
-
-interface Acc {
-  status?: string
-  lastMs: number
-  startMs: number
-  busyMs: number
-  downMs: number
-  goodCount: number
-  nonconformingCount: number
-}
-
-/** 누적기의 완전한 재개점 — 저장했다 되살릴 수 있어야 꼬리만 계산할 수 있다. */
-export interface OeeCheckpoint {
-  maxMs: number
-  acc: ({ moverId: string } & Acc)[]
-}
-
-export class OeeAccumulator {
-  private acc = new Map<string, Acc>()
-  private maxMs = 0 // 최신 이벤트 시각 — nowMs 기본값(현재 계측 시점)
-
-  /*
-   * ── 현장이 언제 도나 — **계획 조업 시간의 근거** (2026-09-07) ────────────────
-   * 이것이 없던 동안 계획 조업 시간이 「재기 시작한 뒤 흐른 시간 전부」였다. 주말도 야간도 휴일도
-   * 계획 조업으로 세었다.
-   *
-   * [산술] 8시간 × 주5일이면 168시간 중 40시간이 조업이다 — PBT 가 4.2배 크고 가동률이 그만큼 작다.
-   * 그리고 그 수가 1로 잘려 있어서(오늘 걷었다) 그럴싸하게 보였다. 두 오류가 서로를 가렸다.
-   *
-   * plant 레인이 같은 자리를 먼저 겪고 실측을 냈다 — 3교대를 물려받으면 `availability 0.4583`,
-   * 달력이 아예 없으면 **수를 안 낸다**. 트윈은 창 전체를 계획으로 쳐서 수를 냈다.
-   *
-   * ⚠ **선언이 없으면 채우지 않는다.** `nonWorkingMsIn` 이 그때 `undefined` 를 내고, 그 값을 0 으로
-   * 바꾸지 않는다 — 0 은 「달력을 봤고 쉬는 시간이 없었다」는 주장이다. 지금은 그러면 PBT 가 창 전체가
-   * 되어 예전과 같은 수가 나온다. **그것을 「안 낸다」로 바꿀지는 아직 결정되지 않았다** — 거동 변화가
-   * 크고 화면이 비는 자리라 사용자 판단을 기다린다(성숙도에 미달로 세우는 짝과 함께 가야 한다).
-   */
-  private siteCalendar?: readonly WorkCalendarEntry[]
-  private calendarByResource = new Map<string, readonly WorkCalendarEntry[]>()
-  private utcOffsetMinutes?: number
-
-  /**
-   * 모델에서 조업 달력을 읽어 얹는다 — 모델을 들고 있는 쪽(`TwinEngine`)이 부른다.
-   *
-   * ── 우선순위가 여기 있는 이유 ───────────────────────────────────────────────
-   * ```
-   * 설비의 달력    이 설비의 가동 계획 — 선언했으면 이것이 이긴다 (24시간 도는 로)
-   * 현장의 달력    이 현장의 조업일
-   * 없음          제약 없음 — 계획 조업 시간이 창 전체가 된다
-   * ```
-   * 계획 조업 시간을 내는 자리가 여기라 그 규칙도 여기 둔다. 부르는 쪽마다 고르게 하면 라이브와
-   * 히스토리가 다른 답을 낸다.
-   *
-   * ⚠ **설비의 달력은 사람의 근무조가 아니다.** 씨앗이 사람의 근무조를 설비 달력에 복사한 일이 있었고,
-   * 그때 아무도 근무하지 않는 시간이 근무 시간으로 기록됐다. 사람 쪽은 `persons[].workCalendar` 다.
-   *
-   * 세우는 자리에서 한 번만 주지 않고 따로 부르는 이유는 모델이 다시 실릴 수 있기 때문이다
-   * (재동기화 · 이관). 그때 달력만 갈아 끼우면 누적된 계측을 버리지 않는다.
-   */
-  setWorkCalendar(model?: { workCalendar?: readonly WorkCalendarEntry[]; equipment?: readonly any[]; utcOffsetMinutes?: number }): void {
-    this.siteCalendar = model?.workCalendar?.length ? model.workCalendar : undefined
-    this.utcOffsetMinutes = model?.utcOffsetMinutes
-    this.calendarByResource.clear()
-    for (const e of model?.equipment ?? []) {
-      const cal = e?.workCalendar
-      if (e?.id && Array.isArray(cal) && cal.length) this.calendarByResource.set(String(e.id), cal)
-    }
-  }
-
-  /**
-   * 이 설비의 계획 가동 달력 — 자기 것이 있으면 그것, 없으면 현장의 것.
-   *
-   * 인자 이름이 `moverId` 인 것은 **봉투의 옛 세대 필드 이름**이라 그렇다(§`apply`). 새로 만드는
-   * 이름에는 그 낱말을 쓰지 않는다 — 어휘 가드가 그것을 잡았고, 맞게 잡았다.
-   */
-  private calendarFor(moverId: string): readonly WorkCalendarEntry[] | undefined {
-    return this.calendarByResource.get(moverId) ?? this.siteCalendar
-  }
-
-  private ensure(moverId: string, t: number): Acc {
-    let a = this.acc.get(moverId)
-    if (!a) {
-      a = { lastMs: t, startMs: t, busyMs: 0, downMs: 0, goodCount: 0, nonconformingCount: 0 }
-      this.acc.set(moverId, a)
-    }
-    return a
-  }
-
-  /**
-   * **재개점** — 이 누적기의 상태 전부(이어 계산의 씨앗).
-   *
-   * ── 왜 필요한가 (2026-08-18) ────────────────────────────────────────────────
-   * 가동 이력은 원 시스템이 누적을 주지 않아 **우리가 이벤트를 적분해** 만든다. 그래서 저널을 꼬리만
-   * 계산하면 이 누적기는 꼬리분만 갖게 되고, 화면의 가용률·수율이 알리지 않고 작아진다(오류는 나지 않는다).
-   * 재개점을 함께 저장·복원해야 「이어 계산한 값」이 「0부터 계산한 값」과 같아진다.
-   */
-  serialize(): OeeCheckpoint {
-    return {
-      maxMs: this.maxMs,
-      acc: [...this.acc.entries()].map(([moverId, a]) => ({ moverId, ...a }))
-    }
-  }
-
-  /** 재개점에서 되세운다 — 모르는 것은 지어내지 않는다(없으면 빈 누적기다). */
-  restore(cp: OeeCheckpoint | undefined | null): void {
-    this.maxMs = cp?.maxMs ?? 0
-    this.acc = new Map((cp?.acc ?? []).map(({ moverId, ...a }) => [moverId, { ...a }]))
-  }
-
-  /** equipment.status(시간-in-상태) + quality.output(양품/불량) 소비. 다른 eventType 무시. */
-  apply(env: CanonicalEnvelope): void {
-    const t = Date.parse(env.eventTime)
-    if (t > this.maxMs) this.maxMs = t
-    if (env.eventType === 'quality.output') {
-      const q = env.data as { moverId?: string; goodCount?: number; nonconformingCount?: number }
-      if (!q?.moverId) return
-      const a = this.ensure(q.moverId, t)
-      a.goodCount = q.goodCount ?? a.goodCount // 누적값 최신화(good/scrap 은 무버 누적)
-      a.nonconformingCount = q.nonconformingCount ?? a.nonconformingCount
-      return
-    }
-    if (env.eventType !== 'equipment.status') return
-    const d = env.data as { moverId?: string; status?: string }
-    if (!d?.moverId) return
-    const a = this.ensure(d.moverId, t)
-    const dt = Math.max(0, t - a.lastMs)
-    if (a.status === 'busy') a.busyMs += dt
-    else if (a.status === 'down') a.downMs += dt
-    a.status = d.status
-    a.lastMs = t
-  }
-
-  /** 무버 OEE 카운터 — 마지막 상태 구간을 nowMs(기본=최신 이벤트 시각)까지 flush. busy→run 근사, setup=0. */
-  counters(moverId: string, nowMs: number = this.maxMs): OeeCounters {
-    const a = this.acc.get(moverId)
-    /*
-     * **이 설비의 이벤트를 하나도 못 봤다** — 계측 창이 없다는 뜻이고, 그것을 `0` 으로 메우면
-     * "1970년부터 재고 있었다" 가 된다. 시각이 밀리초 epoch 이므로 그 값이 곧 지금 시각이 되어,
-     * 화면에 `idleMs 1767226603000`(약 56,000년) 유휴가 섰다. 창을 **말하지 않는다** — 공식이
-     * 없음을 없음으로 다룬다(§computeOee).
-     */
-    if (!a) return { runMs: 0, setupMs: 0, downMs: 0, goodCount: 0, nonconformingCount: 0 }
-    const dt = Math.max(0, nowMs - a.lastMs)
-    let busyMs = a.busyMs
-    let downMs = a.downMs
-    if (a.status === 'busy') busyMs += dt
-    else if (a.status === 'down') downMs += dt
-    /*
-     * 계획 정지 — 계약이 이 칸에 그 뜻을 적어 뒀다(점심 · 예방보전 · 교대). 휴일과 주말이 같은
-     * 갈래다. `metricsSinceMs` 를 당겨서 같은 효과를 내지 않는다: 그 칸은 「언제부터 쟀나」라는
-     * 사실이고, 파생값을 얹으면 실제보다 늦게 재기 시작했다고 말하는 것이 된다.
-     */
-    const holdMs = nonWorkingMsIn(this.calendarFor(moverId), a.startMs, nowMs, this.utcOffsetMinutes)
-    return {
-      runMs: busyMs,
-      setupMs: 0,
-      downMs,
-      goodCount: a.goodCount,
-      nonconformingCount: a.nonconformingCount,
-      metricsSinceMs: a.startMs,
-      ...(holdMs !== undefined ? { holdMs } : {})
-    }
-  }
-
-  /** 공유 공식으로 근사 OEE 산출 — 정확한 OEE 는 실 텔레메트리(option ①). nowMs 기본=최신 이벤트 시각. */
-  oee(moverId: string, nowMs: number = this.maxMs): OeeMetrics {
-    return computeOee(this.counters(moverId, nowMs), nowMs)
-  }
-}
-
-/**
- * live State 를 OEE 로 보강 — projector 미러 State(관측)의 무버에 누적기 OEE(계산)를 채운다.
- * live-모드 publishEntityData 가 buildEntityDeltas 전에 적용 → equipment data(tag) payload 에 oee 포함
- * (sim 은 커널이 채움 — 이로써 live 도 동일 payload 형상). 순수(입력 불변, 얕은 복사).
- */
-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/operation-basis.ts

@@ -1,131 +0,0 @@
-/*
- * 이 트윈이 **어떤 공정을 돌리고, 그 시간이 어디서 오나.**
- *
- * ── 왜 이 목록이 필요한가 (2026-08-18) ─────────────────────────────────────
- * 「측정이 없을 때의 표준 시간」을 현장이 선언하려면 먼저 **무엇에 선언할지** 보여야 한다. 그런데 공정은
- * 자리·설비와 달리 모델에 행이 없을 수 있다 — 실측: 운영 중인 트윈 35개 중 창고·야드는 공정 명세 행이
- * 0개였고(MES만 4개), 그 트윈들의 시간은 전부 커널 상수에서 왔다.
- *
- * 그래서 목록을 **지어내지 않고 네 곳에서 모은다**:
- *  ① 원천 명세 행(`model.operations`) — 원 시스템이 말한 공정.
- *  ② 커널의 자기보고(`specCoverage()`) — **실제로 돌린** 공정과 그 시간의 출처.
- *  ③ 이력에서 배운 종류(`measuredOperationKinds`) — 재기동에도 남는 근거.
- *  ④ 우리가 이미 선언한 것(`model.localDurations`·`model.localParams`) — 선언해 둔 공정이 목록에서
- *     사라지지 않게(사라지면 철회할 자리가 없다).
- *
- * ③이 필요한 이유는 실측으로 드러났다: ②는 **작업이 새로 생길 때** 채워지므로, 이력이 풍부한 창고
- * 트윈도 재기동 직후에는 목록이 비었다 — 값을 채울 곳을 보여야 하는 화면이 정작 그때 아무 말도 못 한다.
- *
- * 그래도 셋 다 비는 트윈은 있다(한 번도 돌지 않고 명세 행도 없는 새 트윈). 그때 「공정이 없다」고 말하지
- * 않는다(모르는 것이다) — 부르는 쪽이 그 사실을 그대로 화면에 옮긴다.
- */
-import { readSpecCoverage } from './spec-coverage.ts'
-
-/** 공정 한 종류 — 이름과 「지금 무엇으로 도나」. */
-export interface OperationBasisRow {
-  /** 작업 종류(`FlowTask.kind` = `OperationDef.key`) — 선언이 겨누는 id 다. */
-  kind: string
-  /** 사람이 읽는 이름 — 원천 명세 행이 있을 때만(없으면 종류 이름이 곧 이름이다). */
-  label?: string
-  /**
-   * 지금 이 종류의 시간이 어디서 오나 — 커널의 자기보고, 또는 **이력에서 배운 사실**. 없으면 모른다.
-   *  · `measured` — 이 현장의 이력에서 배운 값(가장 강한 근거). **선언보다 이긴다.**
-   *  · `declared` — 선언된 값(현장이 정한 것 또는 원천 명세 행).
-   *  · `default`  — 커널 소스의 상수. 이 목록의 존재 이유다.
-   */
-  basis?: 'measured' | 'declared' | 'default'
-  /** 원천 명세 행이 말한 시간(ISO 8601) — 있으면. 우리 선언이 이것을 이긴다. */
-  referenceDuration?: string
-  /** 우리가 선언해 둔 시간(ISO 8601) — 있으면. */
-  localDuration?: string
-  /**
-   * 우리가 선언해 둔 공정 모수 — **커널이 읽는 표기 그대로**(수율 0..1, 셋업 ISO 8601).
-   *
-   * 사람 단위(퍼센트·분)로 되돌리지 않는다: 화면은 선언 겹에서 사용자가 넣은 값을 그대로 들고 있고,
-   * 여기 있는 것은 **실제로 커널에 실린 값**이다 — 둘을 견주면 환산이 잘못된 것도 드러난다.
-   */
-  localParams?: Record<string, string>
-  /** 원천 명세 행이 말한 모수 — 있으면(우리 선언이 이것을 이긴다). */
-  referenceParams?: Record<string, string>
-  /**
-   * 모수를 **무엇으로 읽었나** — 커널의 자기보고(`id → measured|declared`) (2026-08-19).
-   *
-   * 수율이 이력에서 온 값이면 선언값은 예비로만 남는다(소요시간과 같은 규율) — 화면이 그 사실을 말해야
-   * 사람이 헛일을 하지 않는다. 커널이 아직 그 공정을 돌리지 않았으면 이 칸이 빈다(모른다).
-   */
-  paramBasis?: Record<string, 'measured' | 'declared'>
-}
-
-/**
- * 공정 목록을 모은다 — **넷의 합집합**, 순서는 원천 행 → 돌린 것 → 이력에서 배운 것 → 선언한 것.
- *
- * `kernel` 이 없으면(정지 트윈) ②가 빠지고, `measuredKinds` 를 주지 않으면 ③이 빠진다: 그 사실은
- * `basis` 가 비는 것으로 드러난다(빈칸이 곧 「모른다」다).
- */
-export function operationBasis(model: any, kernel?: any, measuredKinds?: readonly string[]): OperationBasisRow[] {
-  const rows = new Map<string, OperationBasisRow>()
-  const at = (kind: string): OperationBasisRow => {
-    const cur = rows.get(kind)
-    if (cur) return cur
-    const row: OperationBasisRow = { kind }
-    rows.set(kind, row)
-    return row
-  }
-
-  for (const o of (model?.operations ?? []) as any[]) {
-    if (!o?.key) continue
-    const row = at(String(o.key))
-    if (o.label) row.label = String(o.label)
-    if (o.duration) row.referenceDuration = String(o.duration)
-    /* 원천이 말한 모수도 함께 든다 — 우리 선언과 견줄 수 있어야 「무엇을 고쳤나」가 보인다. */
-    for (const p of (o.parameters ?? []) as any[]) {
-      if (!p?.id || p.value === undefined) continue
-      row.referenceParams = { ...(row.referenceParams ?? {}), [String(p.id)]: String(p.value) }
-    }
-  }
-
-  const coverage = kernel ? readSpecCoverage(kernel) : undefined
-  for (const o of coverage?.operations ?? []) {
-    if (!o?.kind) continue
-    const row = at(String(o.kind))
-    row.basis = o.duration
-    if (o.parameterBasis && Object.keys(o.parameterBasis).length) row.paramBasis = { ...o.parameterBasis }
-  }
-
-  /*
-   * 이력에서 배운 종류 — 커널이 아직 이 종류를 돌리지 않았어도 **추정기가 답할 수 있다**. 그래서 근거를
-   * `measured` 로 채운다: 짐작이 아니라 설치된 추정기가 그 종류에 실측값을 줄 것이라는 사실이다.
-   * 커널이 이미 보고한 종류는 **덮지 않는다** — 실제로 돌린 것이 더 강한 사실이다.
-   */
-  for (const kind of measuredKinds ?? []) {
-    if (!kind) continue
-    const row = at(String(kind))
-    if (!row.basis) row.basis = 'measured'
-  }
-
-  const declared = (model?.localDurations ?? {}) as Record<string, string>
-  for (const [kind, iso] of Object.entries(declared)) {
-    if (!kind) continue
-    at(kind).localDuration = String(iso)
-  }
-
-  const params = (model?.localParams ?? {}) as Record<string, Record<string, string>>
-  for (const [kind, entries] of Object.entries(params)) {
-    if (!kind) continue
-    const row = at(kind)
-    for (const [id, value] of Object.entries(entries ?? {})) row.localParams = { ...(row.localParams ?? {}), [id]: String(value) }
-  }
-
-  return [...rows.values()]
-}
-
-/**
- * 선언을 받아도 되는 공정 이름들 — **하나도 확인할 수 없으면 `undefined`**(모른다).
- *
- * 빈 배열로 답하지 않는 이유: 빈 배열은 「어떤 이름도 안 된다」로 읽히고, 그러면 아직 돌지 않은 트윈에는
- * 아무것도 선언할 수 없다. 모르는 것과 없는 것은 다르다 — 모를 때는 받아 주고 그 사실을 말한다.
- */
-export function knownOperationKinds(model: any, kernel?: any, measuredKinds?: readonly string[]): string[] | undefined {
-  const kinds = operationBasis(model, kernel, measuredKinds).map(r => r.kind)
-  return kinds.length ? kinds : undefined
-}