@things-factory/headless-twin 10.0.11 → 10.0.13

package/server/engine/loop-lag.ts

@@ -0,0 +1,120 @@
+/*
+ * 이벤트 루프 지체 — **화면이 느린 이유를 지어내지 않기 위해.** 순수(import 없음).
+ *
+ * ── 왜 필요한가 (2026-08-21) ────────────────────────────────────────────────
+ * 「UI 반응성이 느리다」를 진단하려 했는데, 있는 계기판으로는 답이 나오지 않았다. `twinLoad` 는 **트윈의
+ * 계측된 작업**만 재고, `processCpuRatio` 는 프로세스 전체를 재지만 **언제 얼마나 멈췄나**를 말하지
+ * 못한다. 밖에서 HTTP 지연을 재 보니 같은 요청이 44ms 와 5.8초로 갈라졌는데, 그 5.8초가 트윈 때문인지
+ * webpack 재빌드 때문인지 남의 재기동 때문인지 **가릴 근거가 없었다.**
+ *
+ * 근거 없이 원인을 고르면 엉뚱한 곳을 고친다. 그래서 루프가 실제로 얼마나 막혔는지를 잰다.
+ *
+ * ── 어떻게 재나 ─────────────────────────────────────────────────────────────
+ * 일정 간격으로 깨어나는 타이머를 두고, **예정 시각과 실제 시각의 차이**를 본다. 루프가 막혀 있었으면
+ * 그만큼 늦게 깨어난다. 재는 비용은 그 차이 계산 하나뿐이다(창마다 값 다섯).
+ *
+ * 이 값은 **원인을 말하지 않는다** — 「200ms 이상 막힌 일이 이 창에서 세 번, 가장 긴 것은 4.6초」까지가
+ * 사실이다. 원인은 그 시각의 트윈 부하(`twinLoad`)와 프로세스 CPU 와 나란히 놓고 사람이 가린다.
+ * 재지 않은 것을 0 으로 적지 않는다 — 한 번도 깨어나지 않았으면 `null` 이다.
+ */
+
+/** 표본 간격(ms) — 촘촘할 필요가 없다. 긴 정체를 놓치지 않는 정도면 된다. */
+export const LAG_SAMPLE_MS = 500
+/** 이 값을 넘는 지체만 「정체」로 센다(ms). 사람이 화면에서 느끼기 시작하는 크기. */
+export const LAG_STALL_MS = 200
+/** 창 길이(ms) — `twinLoad` 의 창과 같은 크기로 두어 나란히 읽는다. */
+export const LAG_WINDOW_MS = 10_000
+
+export interface LoopLagWindow {
+  /** 이 창에서 가장 길게 막힌 시간(ms). */
+  maxMs: number
+  /** 정체(문턱 초과) 횟수. */
+  stalls: number
+  /** 표본 수 — 분모다. */
+  samples: number
+  /** 지체 합(ms) — 평균은 읽는 쪽에서 낸다. */
+  totalMs: number
+  /** 창이 열린 시각. */
+  startMs: number
+}
+
+export interface LoopLagView {
+  /** 마지막으로 닫힌 창 — 「지금 어떤가」. 아직 한 창도 안 지났으면 null. */
+  recent: (LoopLagWindow & { endMs: number }) | null
+  /** 기동 이후 누적. */
+  total: LoopLagWindow
+  /** 기동 이후 가장 길게 막힌 시각(ms, epoch) — 언제였는지가 원인을 가리는 데 쓰인다. */
+  worstAtMs: number | null
+  /** 표본 간격 — 읽는 쪽이 이 값보다 짧은 정체는 못 본다는 것을 알아야 한다. */
+  sampleMs: number
+  /** 정체로 세는 문턱. */
+  stallMs: number
+}
+
+const emptyWindow = (startMs: number): LoopLagWindow => ({ maxMs: 0, stalls: 0, samples: 0, totalMs: 0, startMs })
+
+export class LoopLagSampler {
+  private window: LoopLagWindow
+  private closed: (LoopLagWindow & { endMs: number }) | null = null
+  private total: LoopLagWindow
+  private worstAtMs: number | null = null
+  private timer: any
+  private expectedMs: number
+
+  private sampleMs: number
+  private stallMs: number
+  private windowMs: number
+  private now: () => number
+
+  /* 생성자 파라미터 프로퍼티(`private x = …`)는 쓰지 않는다 — 시험이 소스를 그대로 실행하는데
+     (타입 제거 실행 방식) 그 문법은 지원되지 않아 파일 전체가 열리지 않는다. */
+  constructor(sampleMs = LAG_SAMPLE_MS, stallMs = LAG_STALL_MS, windowMs = LAG_WINDOW_MS, now: () => number = Date.now) {
+    this.sampleMs = sampleMs
+    this.stallMs = stallMs
+    this.windowMs = windowMs
+    this.now = now
+    const t = this.now()
+    this.window = emptyWindow(t)
+    this.total = emptyWindow(t)
+    this.expectedMs = t + sampleMs
+  }
+
+  /** 표본을 하나 넣는다 — 타이머가 부르고, 시험은 직접 부른다(시계를 밀어 넣어 잰다). */
+  sample(atMs = this.now()): number {
+    const lag = Math.max(0, atMs - this.expectedMs)
+    this.expectedMs = atMs + this.sampleMs
+    for (const w of [this.window, this.total]) {
+      w.samples += 1
+      w.totalMs += lag
+      if (lag > this.stallMs) w.stalls += 1
+      if (lag > w.maxMs) w.maxMs = lag
+    }
+    if (lag >= this.total.maxMs && lag > this.stallMs) this.worstAtMs = atMs
+    if (atMs - this.window.startMs >= this.windowMs) {
+      this.closed = { ...this.window, endMs: atMs }
+      this.window = emptyWindow(atMs)
+    }
+    return lag
+  }
+
+  /** 계기판이 읽는 값. **한 창도 닫히지 않았으면 `recent` 는 null** — 채우는 중인 창은 과소 집계다. */
+  view(): LoopLagView {
+    return { recent: this.closed, total: this.total, worstAtMs: this.worstAtMs, sampleMs: this.sampleMs, stallMs: this.stallMs }
+  }
+
+  /** 표본 타이머 기동(1회) — 프로세스 종료를 막지 않는다. */
+  start(): void {
+    if (this.timer) return
+    this.timer = setInterval(() => this.sample(), this.sampleMs)
+    if (typeof this.timer?.unref === 'function') this.timer.unref()
+  }
+
+  stop(): void {
+    if (!this.timer) return
+    clearInterval(this.timer)
+    this.timer = undefined
+  }
+}
+
+/** 프로세스 하나의 루프를 재는 것이므로 표본기도 하나다. */
+export const loopLag = new LoopLagSampler()

package/server/engine/measured-yield.ts

@@ -0,0 +1,89 @@
+/*
+ * 실측 양품률 추정기 — **이력에서 배운 수율이 선언값·상수를 이긴다.**
+ *
+ * ── 왜 필요했나 (2026-08-19) ────────────────────────────────────────────────
+ * 소요시간에는 이력 층이 있었다(`measured-estimator`): 저널이 「그 현장에서 실제로 얼마 걸렸나」를 안다.
+ * 수율에는 그 층이 없었다 — 양품률의 기본값은 커널 소스의 상수(0.8)였고, **그 상수가 불량 과다 주목
+ * 신호까지 만들었다.** 초기 라인이든 성숙한 라인이든 같은 수로 판정된다는 뜻이다.
+ *
+ * 그런데 이력을 만들 재료도 없었다: 양품/불량은 설비 누적 카운터(종류를 모른다)와 EPCIS disposition
+ * (종류를 모른다)에만 남았다. 그래서 커널이 **판정을 일어난 자리(작업 완료)에 적게** 했고
+ * (`TaskStatusDelta.outcome`), 폴드가 축으로 들고(`TaskFacets.outcome`), KPI 가 종류별로 센다
+ * (`KpiGroup.quality`). 이 파일은 그 수를 비율로 바꿔 커널 시임에 넣는다.
+ *
+ * ── 정직 규율 (소요 추정기와 같은 것) ───────────────────────────────────────
+ *  - **표본이 적으면 쓰지 않는다**(`minSamples`). 세 건 중 한 건 불량은 「불량률 33%」가 아니다.
+ *  - `'unknown'` 축은 쓰지 않는다 — 종류를 모르는 기록을 특정 종류의 근거로 삼을 수 없다.
+ *  - **판정이 없는 작업은 분모에 넣지 않는다.** KPI 가 이미 그렇게 세지만(`quality` 는 판정된 것만),
+ *    여기서도 `good + scrap` 만 쓴다 — `tasks` 를 분모로 쓰면 이동·체류가 섞여 양품률이 낮게 나온다.
+ *  - **0 도 사실이다.** 전부 불량이면 0 을 배운다(그 현장이 그랬다). 「값이 없다」와 구별해 다룬다 —
+ *    커널이 `0` 을 받으면 전량 불량으로 굴러가고, 그것이 관측과 같은 결론이다.
+ *  - 무엇을 배웠고 무엇을 표본 부족으로 버렸는지 함께 낸다(조용히 일부만 반영하지 않는다).
+ */
+
+/** 커널 `YieldEstimator` 와 같은 모양(커널 타입에 의존하지 않기 위해 구조로 맞춘다). */
+export interface YieldEstimatorResult {
+  estimator?: {
+    estimate(ctx: { kind: string }): number | undefined
+  }
+  /** 작업 종류 → 실측 양품률(0..1). 추정기가 답하는 종류들. */
+  learned: Record<string, number>
+  /** 종류별 표본 — 배운 값의 근거 크기(화면·로그가 「몇 건에서 배웠나」를 말할 수 있게). */
+  samples: Record<string, { good: number; scrap: number }>
+  /** 표본이 모자라 쓰지 않은 종류와 판정 건수 — 배우지 못한 것을 밝힌다. */
+  skipped: { kind: string; judged: number }[]
+  minSamples: number
+}
+
+/**
+ * 기본 표본 하한 — 판정 20건 미만이면 그 종류는 배우지 않는다.
+ *
+ * 소요(5건)보다 높게 잡는 이유: 비율은 **드문 사건**을 재는 값이다. 불량률 5% 인 공정에서 20건을 봐도
+ * 불량은 한 건이고, 그 한 건이 있고 없음으로 비율이 0% 와 5% 사이를 오간다. 낮게 잡으면 추정기가
+ * 이력이라는 이름으로 잡음을 실어 보낸다.
+ */
+export const DEFAULT_YIELD_MIN_SAMPLES = 20
+
+/**
+ * 작업 종류별 KPI 그룹에서 양품률 추정기를 만든다(순수 — DB·커널 모름).
+ * `groups` 는 `computeTwinKpi({ groupBy: 'taskKind' })` 의 `groups.items` 를 그대로 넘긴다.
+ */
+export function buildYieldEstimator(
+  groups: { key: string; quality?: { good: number; scrap: number } }[] | undefined,
+  opts: { minSamples?: number } = {}
+): YieldEstimatorResult {
+  const minSamples = opts.minSamples ?? DEFAULT_YIELD_MIN_SAMPLES
+  const learned: Record<string, number> = {}
+  const samples: Record<string, { good: number; scrap: number }> = {}
+  const skipped: { kind: string; judged: number }[] = []
+
+  for (const g of groups ?? []) {
+    if (!g?.key || g.key === 'unknown') continue
+    const good = g.quality?.good ?? 0
+    const scrap = g.quality?.scrap ?? 0
+    const judged = good + scrap
+    /* 판정이 아예 없는 종류는 **건너뛴 것이 아니다** — 품질을 가리지 않는 공정(이동·체류)이 정상이다. */
+    if (judged === 0) continue
+    if (judged < minSamples) {
+      skipped.push({ kind: g.key, judged })
+      continue
+    }
+    learned[g.key] = good / judged
+    samples[g.key] = { good, scrap }
+  }
+
+  const kinds = Object.keys(learned)
+  if (!kinds.length) return { learned, samples, skipped, minSamples }
+
+  return {
+    /*
+     * 시임은 **무상태**다(커널이 fork 할 때 참조를 공유한다 — 소요 추정기와 같은 규약).
+     * 배우지 않은 종류에는 `undefined` 를 답한다: 그러면 커널이 선언값 → 상수로 내려간다.
+     */
+    estimator: { estimate: ({ kind }) => learned[kind] },
+    learned,
+    samples,
+    skipped,
+    minSamples
+  }
+}

package/server/engine/model-gap.ts

@@ -0,0 +1,168 @@
+/*
+ * **원본이 말한 적 없는 것** — 미해결 참조를 세는 한 자리. 순수(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/operation-basis.ts

@@ -10,7 +10,8 @@
  *  ① 원천 명세 행(`model.operations`) — 원 시스템이 말한 공정.
  *  ② 커널의 자기보고(`specCoverage()`) — **실제로 돌린** 공정과 그 시간의 출처.
  *  ③ 이력에서 배운 종류(`measuredOperationKinds`) — 재기동에도 남는 근거.
- *  ④ 우리가 이미 선언한 것(`model.localDurations`) — 선언해 둔 공정이 목록에서 사라지지 않게.
+ *  ④ 우리가 이미 선언한 것(`model.localDurations`·`model.localParams`) — 선언해 둔 공정이 목록에서
+ *     사라지지 않게(사라지면 철회할 자리가 없다).
  *
  * ③이 필요한 이유는 실측으로 드러났다: ②는 **작업이 새로 생길 때** 채워지므로, 이력이 풍부한 창고
  * 트윈도 재기동 직후에는 목록이 비었다 — 값을 채울 곳을 보여야 하는 화면이 정작 그때 아무 말도 못 한다.
@@ -37,6 +38,22 @@ export interface OperationBasisRow {
   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'>
 }
 
 /**
@@ -60,12 +77,19 @@ export function operationBasis(model: any, kernel?: any, measuredKinds?: readonl
     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
-    at(String(o.kind)).basis = o.duration
+    const row = at(String(o.kind))
+    row.basis = o.duration
+    if (o.parameterBasis && Object.keys(o.parameterBasis).length) row.paramBasis = { ...o.parameterBasis }
   }
 
   /*
@@ -85,6 +109,13 @@ export function operationBasis(model: any, kernel?: any, measuredKinds?: readonl
     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()]
 }
 

package/server/engine/property-effects.ts

@@ -158,6 +158,23 @@ export const PROPERTY_EFFECTS: PropertyEffect[] = [
     effect: 'twin.propeffect.operationDuration',
     readBy: '@operato/twin-kernel FlowEngine.durationOf ← declareDurations (engine/local-declarations.ts 가 실어 보낸다)'
   },
+  /*
+   * ── 공정 모수 (2026-08-19) ────────────────────────────────────────────────
+   * 양품률의 기본값은 커널 소스의 상수(0.8)였고, **그 상수가 불량 과다 주목 신호까지 만들었다** — 초기
+   * 라인이든 성숙한 라인이든 같은 수로 판정된다. 셋업도 상수였다. 둘 다 현장이 말할 수 있어야 한다.
+   */
+  {
+    id: 'operation.yield',
+    axes: ['operations'],
+    effect: 'twin.propeffect.operationYield',
+    readBy: '@operato/twin-kernel MesKernel(OP_PARAM.yield) ← declareParameters (양품/불량 판정과 산출량)'
+  },
+  {
+    id: 'operation.setupDuration',
+    axes: ['operations'],
+    effect: 'twin.propeffect.operationSetup',
+    readBy: '@operato/twin-kernel MesKernel(OP_PARAM.setupDuration) ← declareParameters (가동 앞에 붙는 셋업)'
+  },
   {
     id: 'tariff.currency',
     axes: ['locations'],

package/server/engine/restart-policy.ts

@@ -0,0 +1,55 @@
+/*
+ * **재기동 정책** — 이 트윈은 다시 세워질 때 자기 과거를 어떻게 대하나.
+ *
+ * ── 왜 이 이름인가 (ADR-0029 · plans/simulator-as-source.md §2) ─────────────
+ * 옛 이름은 `realityMode` 였고 값은 `mirror`·`sim-world`·`sim-experiment` 였다. 그 축은 「현실이 어디서
+ * 오나」를 말하는 것처럼 보였지만, 코드가 그것으로 가른 것은 **재기동 거동 하나**였다. 그리고 「현실이
+ * 어디서 오나」는 ADR-0029 가 **원본의 종류**로 옮긴 물음이다(`TwinReference.adapterType`) — 트윈은 한
+ * 종류이고 언제나 원본을 반영한다.
+ *
+ * 그래서 이 축은 사라지지 않고 **트윈에 남아 이름을 바꿨다.** 남는 이유: 「자기 저널을 잇는가」는 원본의
+ * 성질이 아니라 **트윈과 자기 과거의 관계**다. 같은 시뮬레이터 원본을 보는 두 트윈이 하나는 이어가고
+ * 하나는 매번 처음부터 재현할 수 있다 — 원본은 그 둘을 구별하지 못한다.
+ *
+ *   resync — 외부 실물에서 다시 읽는다(원본이 진실이므로 우리 과거를 이어 붙이지 않는다).
+ *   resume — 저널을 이어 세운다(이 트윈이 낳은 타임라인이 곧 사실이다).
+ *   reset  — 저널을 비우고 씨앗부터 다시 돌린다(재현 가능한 실험).
+ *
+ * ── 기본값을 두지 않는다 ────────────────────────────────────────────────────
+ * 예전에는 미선언이 조용히 `sim-experiment`(=저널 초기화)로 떨어졌다. 그 관용은 값이 하나 어긋나는
+ * 순간 **저널을 지우는 길**이 된다 — 개명 뒤 옛 값이 남아 있는 행을 그 길로 읽으면 재기동 한 번에
+ * 이력이 사라진다. 그래서 모르는 값은 **오류를 낸다.** 부르는 쪽이 선언하게 만드는 것이 이 축의 요점이다.
+ */
+
+/** 재기동 정책 — 셋뿐이다. */
+export type RestartPolicy = 'resync' | 'resume' | 'reset'
+
+export const RESTART_POLICIES: readonly RestartPolicy[] = ['resync', 'resume', 'reset'] as const
+
+/**
+ * 저장된 값을 정책으로 읽는다 — **모르면 오류를 낸다**(기본값으로 메우지 않는다).
+ *
+ * 옛 어휘(`mirror`·`sim-world`·`sim-experiment`)를 여기서 번역하지 않는다: 번역을 두면 옛 값이 살아남고,
+ * 그 값이 다시 어딘가에 저장된다. 저장된 값은 **한 번 옮기고**(데이터 이관) 코드는 새 어휘만 안다.
+ * 그래서 이 함수는 옛 값에 대해서도 오류를 내며, 무엇으로 옮겨야 하는지 문장으로 말한다.
+ */
+export function readRestartPolicy(raw: unknown, where: string): RestartPolicy {
+  const value = typeof raw === 'string' ? raw.trim() : ''
+  if ((RESTART_POLICIES as readonly string[]).includes(value)) return value as RestartPolicy
+  const legacy: Record<string, RestartPolicy> = { mirror: 'resync', 'sim-world': 'resume', 'sim-experiment': 'reset' }
+  if (legacy[value]) {
+    throw new Error(
+      `${where}: restart policy "${value}" is the old vocabulary — move the stored value to "${legacy[value]}" ` +
+        '(ADR-0029 · plans/simulator-as-source.md §2). Nothing is translated at read time on purpose: a translation would keep the old value alive.'
+    )
+  }
+  throw new Error(
+    `${where}: restart policy ${value ? `"${value}"` : 'is missing'} — declare one of ${RESTART_POLICIES.join(' | ')}. ` +
+      'There is no default: an unspecified policy used to fall through to "reset", which erases the journal on the next reboot.'
+  )
+}
+
+/** 이 값이 정책인가 — 오류를 내지 않고 묻는 자리(화면·검사)를 위해. */
+export function isRestartPolicy(raw: unknown): raw is RestartPolicy {
+  return typeof raw === 'string' && (RESTART_POLICIES as readonly string[]).includes(raw)
+}

package/server/engine/runtime-key.ts

@@ -25,7 +25,7 @@
  * `${domainId}:${instanceId}` — 이 저장소가 이미 쓰는 모양이다(`structureRevCache`·`measuredCache`).
  * 새 모양을 만들지 않는다. 파싱은 **첫 구분자**에서 자르므로 `instanceId` 에 `:` 가 들어 있어도
  * 안전하다(레퍼런스 소스 이름에 들어갈 수 있다). 대신 `domainId` 에 구분자가 있으면 키가 모호해지므로
- * **그때는 던진다** — 조용히 잘못된 키를 만들면 그게 곧 이 결함의 재발이다.
+ * **그때는 오류를 낸다** — 조용히 잘못된 키를 만들면 그게 곧 이 결함의 재발이다.
  */
 
 /** 도메인과 인스턴스 id 를 잇는 문자 — 저장소의 기존 캐시 키와 같은 모양. */

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