@things-factory/headless-twin 10.0.11 → 10.0.12

package/server/engine/local-declarations.ts

@@ -37,7 +37,7 @@
  * **속성 어휘는 사용자가 정의하지 않는다** — 커널이 정한 속성에 값을 넣는 문이다(그래서 이름도
  * 「사용자 정의 속성」이 아니다).
  */
-import { ATTENTION_PROPERTY, EMS_PROPERTY_SPEC, OPERATION_PROPERTY } from '@operato/twin-kernel'
+import { ATTENTION_PROPERTY, EMS_PROPERTY_SPEC, OPERATION_PROPERTY, OP_PARAM } from '@operato/twin-kernel'
 
 import { EQUIPMENT_PROPERTY, SPEED_TO_MPS } from './travel-estimator.ts'
 import { declarationTargetsOf } from './property-effects.ts'
@@ -241,6 +241,28 @@ const COMMON_SPECS: DeclarablePropertySpec[] = [
     range: [0.01, 100000],
     note: 'how long this operation takes at this site — the simulation and the forecast use it instead of the built-in constant. a unit is required. history still wins where it exists.',
     uomChoices: Object.keys(DURATION_UOM_MS)
+  },
+  /*
+   * 양품률 — **퍼센트로 받는다**(80 이 80%다).
+   *
+   * 커널이 읽는 값은 0..1 이지만(ISA-95 `Parameter` 값 그대로) 사람에게 0.8 을 넣으라고 하면 SOC 에서
+   * 겪은 함정을 되풀게 된다(0.8 을 0.8% 로 쓴 일이 있다). 그래서 화면·AI 는 퍼센트로 말하고, 비율로
+   * 바꾸는 일은 얹는 자리 한 곳에서 한다.
+   */
+  {
+    id: OPERATION_PROPERTY.yield,
+    uom: '%',
+    dataType: 'xs:double',
+    range: [1, 100],
+    note: 'good-output rate of this operation as a percentage 1-100 (95 means 95%) — the kernel reads it as a ratio, and this value replaces the built-in default that also drives the high-scrap attention.'
+  },
+  /* 셋업·체인지오버 — 가동 앞에 붙는 시간. 소요시간과 같은 단위 목록을 쓴다(같은 종류의 값이다). */
+  {
+    id: OPERATION_PROPERTY.setupDuration,
+    dataType: 'xs:double',
+    range: [0.01, 100000],
+    note: 'changeover time before this operation runs — added in front of the cycle. a unit is required.',
+    uomChoices: Object.keys(DURATION_UOM_MS)
   }
 ]
 
@@ -250,6 +272,18 @@ const COMMON_SPECS: DeclarablePropertySpec[] = [
  * 읽을 수 없으면 `undefined` — 부르는 쪽이 그 사실을 거절 사유로 올린다(0 을 만들지 않는다: 소요 0 인
  * 작업은 영원히 끝나지 않는다).
  */
+/**
+ * 공정 모수 표에 한 칸 담는다 — **커널이 읽는 표기 그대로**(수율 0..1, 셋업 ISO 8601).
+ *
+ * 표를 통째로 새로 만들어 얹는다: 같은 모델 객체를 여러 겹이 지나므로(현장 → 트윈) 그때마다 새 객체여야
+ * 앞 겹의 것을 조용히 덮어쓰지 않는다.
+ */
+function putParam(next: any, kind: string, paramId: string, value: string): void {
+  const table = { ...(next.localParams ?? {}) }
+  table[kind] = { ...(table[kind] ?? {}), [paramId]: value }
+  next.localParams = table
+}
+
 export function isoDurationOf(value: string | number, uom: string): string | undefined {
   const n = Number(value)
   const per = DURATION_UOM_MS[String(uom ?? '').trim()]
@@ -418,7 +452,9 @@ export function mergeLocalDeclarations(
  * 모델에 없는 대상에 얹으려 하면 **조용히 버리지 않고** 그 사실을 돌려준다(구조가 바뀌어 그 설비가
  * 사라졌을 수 있고, 그때 사용자의 선언은 갈 곳이 없다).
  */
-export function applyLocalDeclarations<T extends { locations?: any[]; equipment?: any[]; localDurations?: Record<string, string> }>(
+export function applyLocalDeclarations<
+  T extends { locations?: any[]; equipment?: any[]; localDurations?: Record<string, string>; localParams?: Record<string, Record<string, string>> }
+>(
   model: T,
   declarations: readonly LocalDeclaration[] | undefined | null
 ): {
@@ -489,20 +525,37 @@ export function applyLocalDeclarations<T extends { locations?: any[]; equipment?
    * 이 표는 **전부 우리가 정한 값**이다(원천이 그리는 자리가 아니다). 그래서 기억(`replaced`)은 언제나
    * `null` 이고, 철회는 「표에서 뺀다」로 끝난다 — 그러면 원천 명세나 커널 상수가 다시 답한다.
    */
-  const putOperation = (durations: Record<string, string>, d: LocalDeclaration, memo: LocalDeclaration): void => {
+  const putOperation = (next: any, d: LocalDeclaration, memo: LocalDeclaration): void => {
     for (let i = 0; i < d.properties.length; i++) {
       const p = d.properties[i]
-      if (p.id !== OPERATION_PROPERTY.duration) {
-        unreadable.push({ target: 'operation', id: d.id, propertyId: p.id })
+      const uom = String((p as any).uom ?? '')
+      /*
+       * 값을 **커널이 읽는 표기로** 바꿔 담는다 — 시간은 ISO 8601, 수율은 비율(0..1).
+       * 바꿀 수 없으면 담지 않고 그 사실을 낸다(조용히 0 이나 빈 값으로 만들지 않는다).
+       */
+      if (p.id === OPERATION_PROPERTY.duration) {
+        const iso = isoDurationOf(p.value, uom)
+        if (!iso) { unreadable.push({ target: 'operation', id: d.id, propertyId: p.id }); continue }
+        next.localDurations = { ...(next.localDurations ?? {}), [d.id]: iso }
+        memo.properties[i].replaced = null
         continue
       }
-      const iso = isoDurationOf(p.value, String((p as any).uom ?? ''))
-      if (!iso) {
-        unreadable.push({ target: 'operation', id: d.id, propertyId: p.id })
+      if (p.id === OPERATION_PROPERTY.setupDuration) {
+        const iso = isoDurationOf(p.value, uom)
+        if (!iso) { unreadable.push({ target: 'operation', id: d.id, propertyId: p.id }); continue }
+        putParam(next, d.id, OP_PARAM.setupDuration, iso)
+        memo.properties[i].replaced = null
         continue
       }
-      durations[d.id] = iso
-      memo.properties[i].replaced = null
+      if (p.id === OPERATION_PROPERTY.yield) {
+        const pct = Number(p.value)
+        if (!Number.isFinite(pct) || pct <= 0 || pct > 100) { unreadable.push({ target: 'operation', id: d.id, propertyId: p.id }); continue }
+        /* 퍼센트 → 비율. 이 환산이 있는 자리는 여기 하나다(두 곳에서 나누면 100 배가 두 번 걸린다). */
+        putParam(next, d.id, OP_PARAM.yield, String(pct / 100))
+        memo.properties[i].replaced = null
+        continue
+      }
+      unreadable.push({ target: 'operation', id: d.id, propertyId: p.id })
     }
   }
 
@@ -511,15 +564,15 @@ export function applyLocalDeclarations<T extends { locations?: any[]; equipment?
     ...model,
     ...(model.locations ? { locations: model.locations.map(n => ({ ...n, ...(n?.properties ? { properties: [...n.properties] } : {}) })) } : {}),
     ...(model.equipment ? { equipment: model.equipment.map(e => ({ ...e, ...(e?.properties ? { properties: [...e.properties] } : {}) })) } : {}),
-    ...(model.localDurations ? { localDurations: { ...model.localDurations } } : {})
+    ...(model.localDurations ? { localDurations: { ...model.localDurations } } : {}),
+    ...(model.localParams ? { localParams: Object.fromEntries(Object.entries(model.localParams).map(([k, v]) => [k, { ...v }])) } : {})
   }
   for (let i = 0; i < decls.length; i++) {
     const d = decls[i]
     if (d.target === 'operation') {
-      /* 빈 표를 남기지 않는다 — 「선언이 있다」와 「읽을 수 있는 선언이 하나도 없다」는 다른 사실이다. */
-      const table: Record<string, string> = next.localDurations ?? {}
-      putOperation(table, d, layer[i])
-      if (Object.keys(table).length) next.localDurations = table
+      /* 빈 표를 남기지 않는다 — 「선언이 있다」와 「읽을 수 있는 선언이 하나도 없다」는 다른 사실이다
+         (`putOperation` 이 담을 것이 있을 때만 표를 만든다). */
+      putOperation(next, d, layer[i])
       continue
     }
     const ok = put(d.target === 'equipment' ? next.equipment : next.locations, d, layer[i])
@@ -585,7 +638,9 @@ export function revokeLocalDeclarations(
  *  · 기억이 없으면(옛 선언) **손대지 않고** `unknownSource` 로 말한다 — 원래 값을 지어내는 것은
  *    잘못 넣은 값을 그대로 두는 것보다 나쁘다(다음 원천 재읽기가 그 자리를 바로잡는다).
  */
-export function restoreRevoked<T extends { locations?: any[]; equipment?: any[]; localDurations?: Record<string, string> }>(
+export function restoreRevoked<
+  T extends { locations?: any[]; equipment?: any[]; localDurations?: Record<string, string>; localParams?: Record<string, Record<string, string>> }
+>(
   model: T,
   revoked: readonly RevokedDeclaration[]
 ): { model: T; restored: RevokedDeclaration[]; unknownSource: DeclarationRevocation[]; missingTargets: { target: string; id: string }[] } {
@@ -595,7 +650,8 @@ export function restoreRevoked<T extends { locations?: any[]; equipment?: any[];
     ...model,
     ...(model.locations ? { locations: model.locations.map(n => ({ ...n, ...(n?.properties ? { properties: [...n.properties] } : {}) })) } : {}),
     ...(model.equipment ? { equipment: model.equipment.map(e => ({ ...e, ...(e?.properties ? { properties: [...e.properties] } : {}) })) } : {}),
-    ...(model.localDurations ? { localDurations: { ...model.localDurations } } : {})
+    ...(model.localDurations ? { localDurations: { ...model.localDurations } } : {}),
+    ...(model.localParams ? { localParams: Object.fromEntries(Object.entries(model.localParams).map(([k, v]) => [k, { ...v }])) } : {})
   }
   const restored: RevokedDeclaration[] = []
   const unknownSource: DeclarationRevocation[] = []
@@ -607,13 +663,33 @@ export function restoreRevoked<T extends { locations?: any[]; equipment?: any[];
      * 빼면 원천 명세(있으면)나 커널 상수가 다시 답한다: 그것이 「선언 이전」의 상태다.
      */
     if (r.target === 'operation') {
+      /* 시간은 시간 표에서, 모수(수율·셋업)는 모수 표에서 뺀다 — 담긴 자리에서 빼야 실제로 빠진다. */
+      const paramId =
+        r.propertyId === OPERATION_PROPERTY.yield
+          ? OP_PARAM.yield
+          : r.propertyId === OPERATION_PROPERTY.setupDuration
+            ? OP_PARAM.setupDuration
+            : undefined
+      if (paramId) {
+        const params: Record<string, Record<string, string>> = next.localParams ?? {}
+        if (!params[r.id] || !(paramId in params[r.id])) {
+          missingTargets.push({ target: r.target, id: r.id })
+          continue
+        }
+        delete params[r.id][paramId]
+        /* 빈 껍데기를 남기지 않는다 — 「선언이 있다」와 「빈 표가 있다」가 구별되지 않는다. */
+        if (!Object.keys(params[r.id]).length) delete params[r.id]
+        if (!Object.keys(params).length) delete next.localParams
+        else next.localParams = params
+        restored.push(r)
+        continue
+      }
       const table: Record<string, string> = next.localDurations ?? {}
       if (!(r.id in table)) {
         missingTargets.push({ target: r.target, id: r.id })
         continue
       }
       delete table[r.id]
-      /* 빈 표는 남기지 않는다 — 「선언이 있다」와 「빈 표가 있다」가 구별되지 않는다. */
       if (!Object.keys(table).length) delete next.localDurations
       else next.localDurations = table
       restored.push(r)
@@ -661,7 +737,9 @@ export type DeclarationScope = 'space' | 'instance'
  * 기억(`replaced`)은 각 겹이 **자기가 덮은 값**을 적는다: 트윈 겹의 기억은 「현장 값을 덮었다」가 되고,
  * 철회하면 현장 값으로 돌아간다(원천까지 가지 않는다). 그것이 사람이 기대하는 되돌림이다.
  */
-export function applyDeclarationLayers<T extends { locations?: any[]; equipment?: any[]; localDurations?: Record<string, string> }>(
+export function applyDeclarationLayers<
+  T extends { locations?: any[]; equipment?: any[]; localDurations?: Record<string, string>; localParams?: Record<string, Record<string, string>> }
+>(
   model: T,
   spaceLayer: readonly LocalDeclaration[] | undefined | null,
   instanceLayer: readonly LocalDeclaration[] | undefined | null

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/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/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