@things-factory/headless-twin 10.0.11 → 10.0.12

package/test/control-capability.test.ts

@@ -0,0 +1,103 @@
+/*
+ * **구동은 선언된 능력이다** — 그리고 원본을 지난다 (ADR-0029 §8, 2026-08-19).
+ *
+ * ── 무엇이 뚫려 있었나 ──────────────────────────────────────────────────────
+ * `controlTwinScenario` 가 트윈의 커널 런타임(`runtime.scenario`)을 **직접** 잡았다. 시뮬만 할 수 있는 일
+ * (자극·배속·정지)이 계약 밖의 지름길로 들어온 셈이고, 실 시스템에는 그 자리가 아예 없었다. ADR-0029 의
+ * 판정 문장(*"실물이 같은 계약으로 할 수 있는가"*)을 그대로 대면 그 통제면은 영원히 「규약의 결손」이 된다.
+ *
+ * 뒤집는다: 통제는 **선언된 어댑터 능력**이다. 선언하지 않은 원본에는 문이 열리지 않고, 그 사실이 결손이
+ * 아니라 사실이다(실 WMS 는 정지되지 않는다).
+ *
+ * 이 시험이 지키는 것:
+ *  ① 선언과 구현이 **함께** 있어야 능력이다 — 선언만 있으면 화면이 거짓말을 하고, 구현만 있으면 닫아 둔
+ *    문을 여는 것이다(선언이 권위다).
+ *  ② 능력 없는 원본은 **사유 코드로** 거절한다(조용한 실패 금지).
+ *  ③ 없는 기능을 있는 것처럼 답하지 않는다(내장 시뮬은 아직 재씨앗을 못 한다).
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+import { capabilitiesOf, type ReferenceAdapter } from '../server/service/reference/reference-adapter.ts'
+
+const base: ReferenceAdapter = {
+  type: 'probe',
+  async testConnection() {
+    return { ok: true }
+  },
+  async discoverSites() {
+    return []
+  },
+  async fetchMaster() {
+    return { source: 'p', system: 'wms', space: { spaceId: 'p-site' }, locations: [] } as any
+  }
+}
+
+test('선언도 구현도 없으면 아무 능력이 없다 — 구조만 주는 원본이 정상이다', () => {
+  assert.deepEqual(capabilitiesOf(base), [])
+})
+
+test('선언만 있으면 능력이 아니다 — 화면이 「할 수 있다」고 말한 뒤 아무 일도 없게 두지 않는다', () => {
+  assert.deepEqual(capabilitiesOf({ ...base, capabilities: ['control'] }), [])
+  assert.deepEqual(capabilitiesOf({ ...base, capabilities: ['live'] }), [])
+})
+
+test('구현만 있으면 능력이 아니다 — 선언이 권위다(닫아 둔 문을 열지 않는다)', () => {
+  assert.deepEqual(capabilitiesOf({ ...base, control: async () => ({ ok: true }) }), [])
+  assert.deepEqual(capabilitiesOf({ ...base, openLiveFeed: () => () => {} }), [])
+})
+
+test('선언과 구현이 함께 있으면 그 능력이다', () => {
+  assert.deepEqual(capabilitiesOf({ ...base, capabilities: ['control'], control: async () => ({ ok: true }) }), ['control'])
+  assert.deepEqual(
+    capabilitiesOf({
+      ...base,
+      capabilities: ['live', 'control'],
+      openLiveFeed: () => () => {},
+      control: async () => ({ ok: true })
+    }),
+    ['live', 'control']
+  )
+})
+
+test('어댑터가 없으면 빈손이다 — 지어내지 않는다', () => {
+  assert.deepEqual(capabilitiesOf(undefined), [])
+})
+
+/*
+ * ── 길이 하나뿐인지 (소스로 지킨다) ────────────────────────────────────────
+ * 지름길이 남아 있으면 이 결정은 문서상의 것이 된다. 그래서 ① 구동 문이 라우터를 지나고 ② 라우터가 능력을
+ * 보고 ③ 트윈 런타임을 직접 잡는 옛 경로가 사라졌는지 본다.
+ */
+test('구동 문이 원본을 지난다 — 트윈 런타임을 직접 잡지 않는다', () => {
+  const src = readFileSync(fileURLToPath(new URL('../server/service/twin-control/twin-control-mutation.ts', import.meta.url)), 'utf-8')
+  const code = src
+    .split('\n')
+    .filter(line => !/^\s*(\*|\/\/|\/\*)/.test(line))
+    .join('\n')
+  assert.match(code, /routeControl\(domainId, instanceId/, '구동은 라우터를 지난다')
+  assert.equal(/runtime\.scenario\./.test(code), false, '트윈의 시나리오 엔진을 직접 잡는 지름길이 없다')
+  assert.equal(/controlTwinScenario/.test(code), false, '옛 문이 남아 있지 않다')
+  assert.match(code, /twinSourceCapability/, '화면이 먼저 물을 자리가 있다')
+})
+
+test('라우터가 선언을 본다 — 없으면 사유 코드로 거절한다', () => {
+  const src = readFileSync(fileURLToPath(new URL('../server/service/reference/control-routing.ts', import.meta.url)), 'utf-8')
+  assert.match(src, /capabilitiesOf\(adapter\)\.includes\('control'\)/)
+  assert.match(src, /'not-declared'/)
+  assert.match(src, /'no-source'/, '원본을 모르는 트윈은 구동 대상이 아니다')
+})
+
+test('내장 시뮬은 자기가 못 하는 것을 못 한다고 말한다 — 재씨앗은 아직 없다', () => {
+  const src = readFileSync(
+    fileURLToPath(new URL('../../operato-twin/server/board/virtual-adapter.ts', import.meta.url)),
+    'utf-8'
+  )
+  /* §4 이후 이 원본은 둘을 선언한다(`live`·`control`) — 순서가 아니라 **있음**을 본다. */
+  assert.match(src, /capabilities: \[[^\]]*'control'[^\]]*\]/, '구동 능력을 선언한다')
+  assert.match(src, /capabilities: \[[^\]]*'live'[^\]]*\]/, '피드 능력도 선언한다(§4)')
+  assert.match(src, /cannot re-seed itself yet/, '없는 기능을 있는 것처럼 답하지 않는다')
+  assert.match(src, /not-running/, '아직 서지 않은 트윈에는 자극을 지어 싣지 않는다')
+})

package/test/declared-stimulus.test.ts

@@ -0,0 +1,88 @@
+/*
+ * 자극은 **원본이 선언한다** — 그리고 재기동에도 살아 있다.
+ *
+ * ── 무엇이 났나 (2026-08-19) ────────────────────────────────────────────────
+ * 데모의 시나리오는 시드 코드가 **메모리에만** 실었다(`runtime.scenario.load`). 그래서 트윈을 재기동하면
+ * 자극이 사라지고 구조만 서 있는 트윈이 남았다 — 작업 0·오더 0. 「살아 있는 데모」가 첫 재기동까지만
+ * 살았고, 오늘 서버를 여러 번 띄우는 동안 데모 트윈들이 실제로 그 상태였다.
+ *
+ * ── 집을 트윈이 아니라 원본으로 (ADR-0029 · plans/simulator-as-source.md §4) ─
+ * 무엇이 들어오고 무슨 주문이 나는지는 **시뮬레이터(원본)가 정하는 사실**이고 트윈은 반영한다. 트윈에
+ * 축을 만들면 ADR-0029 가 나중에 걷어내야 하고, 원본(`TwinReference.connectionConfig`)에 두면 그 계획의
+ * 첫 조각(`openLiveFeed`)이 같은 선언을 그대로 읽는다.
+ *
+ * 이 시험이 지키는 것:
+ *  ① 선언이 없으면 조용히 지난다(정적 구조만 반영하는 트윈이 정상이다).
+ *  ② **미러에는 싣지 않는다** — 외부 실물이 진실인 트윈에 도착을 지어 주면 그것은 현실이 아니다.
+ *  ③ 검사를 통과하지 못한 선언은 **태우지 않고** 이유를 남긴다(잘못된 선언 하나가 서버를 내린 이력이 있다).
+ *  ④ 검사기가 없으면 싣지 않는다 — 검사할 수 없는 선언을 태우는 것이 가장 비싼 선택이다.
+ *  ⑤ 선언을 얹을 때 **옆 설정을 지우지 않는다**(접속 정보가 같은 자리에 산다).
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+import { planStimulus, withStimulus } from '../server/engine/declared-stimulus.ts'
+
+const scenario = { seed: 1, generators: [{ kind: 'inbound-arrival', rate: { distribution: 'constant', meanPerHour: 60 }, content: {} }] }
+const ok = () => ({ ok: true as const })
+const bad = () => ({ ok: false as const, errorCode: 'scenario-sku-mix-required' })
+const sim = { hasScenarioEngine: true, mode: 'sim' as const }
+
+test('선언이 없으면 조용히 지난다 — 구조만 반영하는 트윈이 정상이다', () => {
+  assert.deepEqual(planStimulus(undefined, sim, ok), { action: 'skip', reason: 'none' })
+  assert.deepEqual(planStimulus({ endpoint: 'x' }, sim, ok), { action: 'skip', reason: 'none' })
+  /* 시나리오 자리에 객체가 아닌 것이 오면 선언이 아니다(문자열을 시나리오로 읽지 않는다). */
+  assert.deepEqual(planStimulus({ scenario: 'daily' }, sim, ok), { action: 'skip', reason: 'none' })
+})
+
+test('관측으로 도는 트윈에는 싣지 않는다 — 현실을 지어내지 않는다', () => {
+  const plan = planStimulus({ scenario }, { hasScenarioEngine: true, mode: 'live' }, ok)
+  assert.deepEqual(plan, { action: 'skip', reason: 'observed' })
+})
+
+test('시나리오 엔진이 없으면 싣지 않는다 — 조용히 아무 일도 없게 두지 않는다', () => {
+  const plan = planStimulus({ scenario }, { hasScenarioEngine: false, mode: 'sim' }, ok)
+  assert.deepEqual(plan, { action: 'skip', reason: 'no-engine' })
+})
+
+test('검사를 통과하지 못한 선언은 태우지 않는다 — 사유를 든다', () => {
+  const plan = planStimulus({ scenario }, sim, bad)
+  assert.deepEqual(plan, { action: 'skip', reason: 'invalid', detail: 'scenario-sku-mix-required' })
+})
+
+test('검사기가 없으면 싣지 않는다 — 검사할 수 없는 선언이 가장 위험하다', () => {
+  const plan = planStimulus({ scenario }, sim, undefined)
+  assert.equal(plan.action, 'skip')
+  assert.equal((plan as any).reason, 'invalid')
+})
+
+test('통과한 선언은 그대로 싣는다 — 값을 손대지 않는다', () => {
+  const plan = planStimulus({ scenario }, sim, ok)
+  assert.deepEqual(plan, { action: 'load', scenario })
+})
+
+test('선언을 얹으면서 접속 정보를 지우지 않는다', () => {
+  const merged = withStimulus({ endpoint: 'https://sim', token: 't' }, scenario)
+  assert.deepEqual(merged, { endpoint: 'https://sim', token: 't', scenario })
+  /* 설정이 없던 원본에도 얹힌다(빈 객체에서 시작). */
+  assert.deepEqual(withStimulus(undefined, scenario), { scenario })
+})
+
+/*
+ * ── 배선 (소스로 지킨다) ────────────────────────────────────────────────────
+ * 판정은 순수 함수가 하지만, 그것을 **기동 때 부르지 않으면** 아무 일도 일어나지 않는다. 그리고 못 실은
+ * 이유는 말해야 한다 — 「선언했는데 안 실렸다」가 조용하면 사용자는 트윈이 고장 난 줄로 읽는다.
+ */
+test('두 기동 경로에서 부른다 — 시뮬은 싣고, 미러는 그 사실을 말한다', () => {
+  const src = readFileSync(fileURLToPath(new URL('../server/engine/twin-engine.ts', import.meta.url)), 'utf-8')
+  const calls = src.match(/this\.installStimulus\(domainId, id, inst\)/g) ?? []
+  assert.equal(calls.length, 2, `기동 경로 둘에서 불러야 한다(발견 ${calls.length})`)
+  assert.match(src, /planStimulus\(config, \{ hasScenarioEngine/, '판정은 순수 함수에 맡긴다')
+  assert.match(src, /validateScenario/, '커널 검사기를 그대로 쓴다(규칙을 두 벌로 만들지 않는다)')
+  assert.match(src, /a stimulus is declared on its source but was not loaded/, '못 실은 이유를 말한다')
+  /* 선언을 적는 문도 있어야 한다 — 읽기만 있으면 아무도 선언할 수 없다. */
+  assert.match(src, /static async declareStimulus/)
+  assert.match(src, /no source reference — a stimulus has nowhere to be declared/, '원본이 없으면 지어 만들지 않는다')
+})

package/test/ingest-running-guard.test.ts

@@ -86,7 +86,7 @@ before(async () => {
   const d = await ds.getRepository(Domain).save({ name: 'guard-test', subdomain: 'guard-test' } as any)
   domainId = d.id
 
-  await TwinEngine.ingestMaster(domainId, master(3, '서울 창고', '보관 구역'))
+  await TwinEngine.ingestMaster(domainId, master(3, '서울 창고', '보관 구역'), 'reset')
 })
 
 after(async () => {
@@ -95,7 +95,7 @@ after(async () => {
 })
 
 test('멈춰 있으면 재인제스트가 통한다 — 막는 것은 가동 중일 때뿐이다', async () => {
-  await TwinEngine.ingestMaster(domainId, master(5, '서울 창고', '보관 구역'))
+  await TwinEngine.ingestMaster(domainId, master(5, '서울 창고', '보관 구역'), 'reset')
   const t = await trace()
   assert.equal(t.boardLocations, 6, '자리 6개(도크 1 + 빈 5)로 갱신된다')
   assert.deepEqual(t.revs, [1, 2], '구조가 달라졌으니 리비전이 하나 늘어난다')
@@ -103,7 +103,7 @@ test('멈춰 있으면 재인제스트가 통한다 — 막는 것은 가동 중
 })
 
 test('가동 중이면 거절하고 — **아무것도 바꾸지 않는다**', async () => {
-  await TwinEngine.startFromRegistry(domainId, INSTANCE, 'sim-experiment')
+  await TwinEngine.startFromRegistry(domainId, INSTANCE, 'reset')
   const before = await trace()
 
   /*
@@ -111,7 +111,7 @@ test('가동 중이면 거절하고 — **아무것도 바꾸지 않는다**', a
    * 부분 쓰기는 앞쪽(공간·구역)에서 일어났으므로, 구조만 확인하면 예전 결함을 못 잡는다.
    */
   await assert.rejects(
-    () => TwinEngine.ingestMaster(domainId, master(9, '부산 창고', '다른 구역')),
+    () => TwinEngine.ingestMaster(domainId, master(9, '부산 창고', '다른 구역'), 'reset'),
     /is running/,
     '가동 중에는 거절해야 한다'
   )
@@ -121,7 +121,7 @@ test('가동 중이면 거절하고 — **아무것도 바꾸지 않는다**', a
 
 test('멈추면 다시 통한다 — 거절은 잠금이 아니라 순서다', async () => {
   await TwinEngine.stop(domainId, INSTANCE)
-  await TwinEngine.ingestMaster(domainId, master(9, '부산 창고', '다른 구역'))
+  await TwinEngine.ingestMaster(domainId, master(9, '부산 창고', '다른 구역'), 'reset')
 
   const t = await trace()
   assert.equal(t.boardLocations, 10, '아까 거절당한 그 구조가 이제 들어간다')

package/test/instance-cache-lifecycle.test.ts

@@ -74,7 +74,7 @@ after(async () => {
 })
 
 test('지운 트윈의 캐시는 남지 않는다 — TTL 은 없어진 주인을 지우지 않는다', async () => {
-  await TwinEngine.ingestMaster(domainId, master())
+  await TwinEngine.ingestMaster(domainId, master(), 'reset')
   /* 캐시를 실제로 채운다 — 손으로 넣으면 "채우는 경로" 가 바뀌어도 검사가 통과한다. */
   await TwinEngine.structureRevOf(domainId, INSTANCE)
   const { measured, structureRev } = caches()

package/test/kpi-baseline-db.test.ts

@@ -90,7 +90,7 @@ before(async () => {
     domain: { id: domainId },
     instanceId: INSTANCE,
     kind: 'wms',
-    realityMode: 'sim-experiment', /* 선언은 이제 필수 — 비워 두면 읽는 자리마다 기본값을 고른다 */
+    restartPolicy: 'reset', /* 선언은 이제 필수 — 비워 두면 읽는 자리마다 기본값을 고른다 */
     purpose: 'operational',
     status: 'stopped',
     model: { locations: [{ id: 'dock', type: 'dock', capacity: 10 }], equipment: [{ id: 'fk-1', kind: 'forklift', homeLocation: 'dock' }] }

package/test/kpi-query-bench.test.ts

@@ -93,7 +93,7 @@ before(async () => {
     domain: { id: domainId },
     instanceId: INSTANCE,
     kind: 'wms',
-    realityMode: 'sim-experiment', /* 선언은 이제 필수 — 비워 두면 읽는 자리마다 기본값을 고른다 */
+    restartPolicy: 'reset', /* 선언은 이제 필수 — 비워 두면 읽는 자리마다 기본값을 고른다 */
     purpose: 'operational',
     status: 'stopped',
     model: { locations, equipment: [{ id: 'fk-1', kind: 'forklift', homeLocation: 'loc-0' }] }

package/test/lineage-survives-restart.test.ts

@@ -124,7 +124,7 @@ before(async () => {
   addDataSource('default', ds)
   const d = await ds.getRepository(Domain).save({ name: 'lineage-test', subdomain: 'lineage-test' } as any)
   domainId = d.id
-  await TwinEngine.ingestMaster(domainId, master())
+  await TwinEngine.ingestMaster(domainId, master(), 'reset')
 })
 
 after(async () => {
@@ -134,7 +134,7 @@ after(async () => {
 
 test('재기동을 건너도 계보에 입력이 실린다 — 웜스타트가 확보분을 잃지 않는다', async () => {
   /* ① 한 번 굴려 진행 중 할당을 만든다. */
-  await TwinEngine.startFromRegistry(domainId, INSTANCE, 'sim-world')
+  await TwinEngine.startFromRegistry(domainId, INSTANCE, 'resume')
   drive()
   tick(200)
   const workingBefore = orders().filter(o => (o.allocated ?? []).length)
@@ -142,7 +142,7 @@ test('재기동을 건너도 계보에 입력이 실린다 — 웜스타트가
 
   /* ② 멈추고 **저널을 재생해** 다시 세운다 — 호스트의 웜스타트 경로 그대로. */
   await TwinEngine.stop(domainId, INSTANCE)
-  await TwinEngine.startFromRegistry(domainId, INSTANCE, 'sim-world')
+  await TwinEngine.startFromRegistry(domainId, INSTANCE, 'resume')
 
   const revived = orders().filter(o => (o.allocated ?? []).length)
   assert.ok(revived.length, '되살아난 오더가 확보분을 들고 있어야 한다 — 잃으면 계보의 입력이 빈다')

package/test/live-feed-registry.test.ts

@@ -41,15 +41,15 @@ test('답하지 못하는 장부가 다른 계층의 사실을 죽이지 않는
 
 test('「없음」과 「해당 없음」을 섞지 않는다', () => {
   /* 도는 미러 — 이 둘이 우리가 보이려던 구별이다. */
-  assert.equal(liveFeedStateOf({ realityMode: 'mirror', running: true, instanceId: 'ems-plant-1' }), 'attached')
-  assert.equal(liveFeedStateOf({ realityMode: 'mirror', running: true, instanceId: 'ems-plant-2' }), 'detached')
+  assert.equal(liveFeedStateOf({ restartPolicy: 'resync', running: true, instanceId: 'ems-plant-1' }), 'attached')
+  assert.equal(liveFeedStateOf({ restartPolicy: 'resync', running: true, instanceId: 'ems-plant-2' }), 'detached')
 
   /* 시뮬 트윈에는 나를 피드가 **없어야 한다** — 결함이 아니라 그 트윈의 성질이다. */
-  assert.equal(liveFeedStateOf({ realityMode: 'sim-world', running: true, instanceId: 'hatio-us' }), 'not-applicable')
-  assert.equal(liveFeedStateOf({ realityMode: 'sim-experiment', running: true, instanceId: 'trailer-new' }), 'not-applicable')
+  assert.equal(liveFeedStateOf({ restartPolicy: 'resume', running: true, instanceId: 'hatio-us' }), 'not-applicable')
+  assert.equal(liveFeedStateOf({ restartPolicy: 'reset', running: true, instanceId: 'trailer-new' }), 'not-applicable')
 
   /* 사람이 멈춰 둔 트윈에게 피드를 묻는 것은 뜻이 없다. */
-  assert.equal(liveFeedStateOf({ realityMode: 'mirror', running: false, instanceId: 'ems-plant-1' }), 'not-applicable')
+  assert.equal(liveFeedStateOf({ restartPolicy: 'resync', running: false, instanceId: 'ems-plant-1' }), 'not-applicable')
 
   /* 선언이 없으면 미러라고 짐작하지 않는다(짐작으로 경보를 울리지 않는다). */
   assert.equal(liveFeedStateOf({ running: true, instanceId: 'ems-plant-1' }), 'not-applicable')
@@ -63,5 +63,5 @@ test('목록이 그 사실을 함께 낸다 — 화면이 따로 물어야 하
   assert.ok(at >= 0, 'list() 가 없다 — 이름이 바뀌었으면 이 검사도 함께 고친다')
   const body = src.slice(at, src.indexOf('\n  /** 운영 공간 목록', at))
   assert.match(body, /liveFeed: liveFeedStateOf\(/, '관리 목록 행에 피드 사실이 실려야 한다')
-  assert.match(body, /realityMode: r\.realityMode/, '선언된 모드를 넘겨야 한다(짐작하지 않는다)')
+  assert.match(body, /restartPolicy: r\.restartPolicy/, '선언된 모드를 넘겨야 한다(짐작하지 않는다)')
 })

package/test/local-declarations.test.ts

@@ -69,7 +69,15 @@ test('EMS 밖에도 공용 어휘가 있다 — 속도는 어느 트윈에서나
   /* 읽는 코드가 있는 것만 — 판정 기준 셋(주의)과 속도. 새 효과를 붙이면 이 목록도 함께 자란다. */
   assert.deepEqual(
     specs.map(s => s.id).sort(),
-    ['attention.congestionRatio', 'attention.scrapMinSamples', 'attention.scrapRate', 'operation.duration', 'speed'],
+    [
+      'attention.congestionRatio',
+      'attention.scrapMinSamples',
+      'attention.scrapRate',
+      'operation.duration',
+      'operation.setupDuration',
+      'operation.yield',
+      'speed'
+    ],
     '읽는 코드가 있는 것만'
   )
   /* 모르는 속성은 이제 「어휘가 없다」가 아니라 **「그 속성을 읽지 않는다」**로 거절된다(더 정확하다). */
@@ -552,3 +560,102 @@ test('두 겹이 함께 얹힌다 — 트윈 값이 현장 값을 이긴다(시
   assert.deepEqual((out.model as any).localDurations, { putaway: 'PT120S' }, '좁은 겹이 이긴다')
   assert.deepEqual(out.unreadable, [])
 })
+
+/*
+ * ── 공정 모수: 수율·셋업 (2026-08-19) ───────────────────────────────────────
+ * 양품률 기본값은 커널 소스의 상수(0.8)였고 **그 상수가 불량 과다 주목 신호까지 만들었다.** 현장이 자기
+ * 수를 말할 자리를 준다. 사람은 퍼센트로 말하고(80=80%), 커널은 비율(0..1)을 읽는다 — 환산은 한 곳에서.
+ */
+test('수율은 퍼센트로 받아 비율로 얹는다 — 80 이 0.8 이다(한 곳에서만 나눈다)', () => {
+  const { accepted, rejected } = validateLocalDeclarations('mes', [
+    { target: 'operation', id: 'weld', properties: [{ id: 'operation.yield', value: '95' }] }
+  ])
+  assert.deepEqual(rejected, [])
+  const { model, unreadable } = applyLocalDeclarations({ locations: [], equipment: [] }, accepted)
+  assert.deepEqual(unreadable, [])
+  assert.deepEqual((model as any).localParams, { weld: { yield: '0.95' } })
+  assert.equal((model as any).localDurations, undefined, '모수는 시간 표를 건드리지 않는다')
+})
+
+test('수율은 퍼센트 범위를 지킨다 — 0.8 을 넣으면 걸린다(SOC 에서 겪은 함정)', () => {
+  const low = validateLocalDeclarations('mes', [
+    { target: 'operation', id: 'weld', properties: [{ id: 'operation.yield', value: '0.8' }] }
+  ])
+  assert.equal(low.rejected[0]?.reason, 'out-of-range')
+  const high = validateLocalDeclarations('mes', [
+    { target: 'operation', id: 'weld', properties: [{ id: 'operation.yield', value: '150' }] }
+  ])
+  assert.equal(high.rejected[0]?.reason, 'out-of-range')
+})
+
+test('셋업은 단위와 함께 받아 ISO 8601 로 얹는다 — 시간 표가 아니라 모수 표에', () => {
+  const { accepted } = validateLocalDeclarations('mes', [
+    { target: 'operation', id: 'paint', properties: [{ id: 'operation.setupDuration', value: '7.5', uom: 'MIN' }] }
+  ])
+  const { model } = applyLocalDeclarations({ locations: [], equipment: [] }, accepted)
+  assert.deepEqual((model as any).localParams, { paint: { setupDuration: 'PT450S' } })
+})
+
+test('셋업도 단위 없이 받지 않는다 — 7 초와 7 분은 60배 다르다', () => {
+  const { rejected } = validateLocalDeclarations('mes', [
+    { target: 'operation', id: 'paint', properties: [{ id: 'operation.setupDuration', value: '7' }] }
+  ])
+  assert.equal(rejected[0]?.reason, 'uom-required')
+})
+
+test('한 공정에 시간·수율·셋업을 함께 얹는다 — 서로 덮지 않는다', () => {
+  const { accepted } = validateLocalDeclarations('mes', [
+    {
+      target: 'operation',
+      id: 'weld',
+      properties: [
+        { id: 'operation.duration', value: '3', uom: 'MIN' },
+        { id: 'operation.yield', value: '92' },
+        { id: 'operation.setupDuration', value: '30', uom: 'SEC' }
+      ]
+    }
+  ])
+  const { model } = applyLocalDeclarations({ locations: [], equipment: [] }, accepted)
+  assert.deepEqual((model as any).localDurations, { weld: 'PT180S' })
+  assert.deepEqual((model as any).localParams, { weld: { yield: '0.92', setupDuration: 'PT30S' } })
+})
+
+test('모수 철회는 모수 표에서 뺀다 — 시간 선언은 그대로 남는다', () => {
+  const declared = [
+    {
+      target: 'operation' as const,
+      id: 'weld',
+      properties: [
+        { id: 'operation.duration', value: '3', uom: 'MIN' },
+        { id: 'operation.yield', value: '92' }
+      ]
+    }
+  ]
+  const applied = applyLocalDeclarations({ locations: [], equipment: [] }, declared)
+  const { layer, revoked, notFound } = revokeLocalDeclarations(applied.layer, [
+    { target: 'operation', id: 'weld', propertyId: 'operation.yield' }
+  ])
+  assert.deepEqual(notFound, [])
+  assert.deepEqual(layer[0].properties.map(p => p.id), ['operation.duration'], '시간 선언은 겹에 남는다')
+  const back = restoreRevoked(applied.model, revoked)
+  assert.equal((back.model as any).localParams, undefined, '빈 껍데기를 남기지 않는다')
+  assert.deepEqual((back.model as any).localDurations, { weld: 'PT180S' }, '시간은 그대로')
+})
+
+test('없는 모수를 철회했다고 말하지 않는다 — 조용한 성공이 가장 비싸다', () => {
+  const back = restoreRevoked({ locations: [], equipment: [], localParams: { weld: { yield: '0.9' } } }, [
+    { target: 'operation', id: 'weld', propertyId: 'operation.setupDuration', replaced: null }
+  ])
+  assert.deepEqual(back.restored, [])
+  assert.deepEqual(back.missingTargets, [{ target: 'operation', id: 'weld' }])
+  assert.deepEqual((back.model as any).localParams, { weld: { yield: '0.9' } }, '남의 값을 건드리지 않는다')
+})
+
+test('두 겹이 함께 얹혀도 모수가 섞이지 않는다 — 좁은 겹이 이긴다', () => {
+  const out = applyDeclarationLayers(
+    { locations: [], equipment: [] },
+    [{ target: 'operation', id: 'weld', properties: [{ id: 'operation.yield', value: '80' }] }],
+    [{ target: 'operation', id: 'weld', properties: [{ id: 'operation.yield', value: '95' }] }]
+  )
+  assert.deepEqual((out.model as any).localParams, { weld: { yield: '0.95' } })
+})

package/test/measured-yield.test.ts

@@ -0,0 +1,90 @@
+/*
+ * 실측 양품률 — **이력에서 배운 수율이 선언값·상수를 이긴다.**
+ *
+ * ── 왜 (2026-08-19) ─────────────────────────────────────────────────────────
+ * 소요시간에는 이력 층이 있었는데 수율에는 없었다. 양품률 기본값은 커널 소스의 상수(0.8)였고 **그 상수가
+ * 불량 과다 주목 신호까지 만들었다.** 이제 커널이 판정을 작업 완료에 적고(`outcome`), 폴드가 축으로 들고,
+ * KPI 가 종류별로 세고(`quality`), 이 모듈이 비율로 바꿔 커널 시임에 넣는다.
+ *
+ * 이 시험이 지키는 것:
+ *  ① 분모는 **판정된 것만** — 이동·체류를 섞으면 양품률이 낮게 나온다.
+ *  ② 표본이 모자라면 **배우지 않는다** — 비율은 드문 사건을 재는 값이라 작은 표본이 잡음을 만든다.
+ *  ③ 0 도 사실이다 — 전량 불량이면 0 을 배운다(「값이 없다」와 다르다).
+ *  ④ 모르는 종류에는 `undefined` — 그러면 커널이 선언값·상수로 내려간다.
+ *  ⑤ 배우지 못한 것을 **밝힌다** — 조용히 일부만 반영하지 않는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+import { buildYieldEstimator, DEFAULT_YIELD_MIN_SAMPLES } from '../server/engine/measured-yield.ts'
+
+const group = (key: string, good: number, scrap: number) => ({ key, quality: { good, scrap } })
+
+test('판정된 것만 분모다 — 이동·체류가 섞이지 않는다', () => {
+  /* tasks 는 1000 건이어도 판정은 40 건뿐인 종류가 정상이다(중간 스테이션은 품질을 가리지 않는다). */
+  const r = buildYieldEstimator([{ key: 'assembly', tasks: 1000, quality: { good: 36, scrap: 4 } } as any])
+  assert.equal(r.learned.assembly, 0.9, '36/40 = 0.9')
+  assert.deepEqual(r.samples.assembly, { good: 36, scrap: 4 })
+})
+
+test('표본이 모자라면 배우지 않고 그 사실을 낸다 — 세 건 중 한 건 불량은 33% 가 아니다', () => {
+  const r = buildYieldEstimator([group('weld', 2, 1)])
+  assert.deepEqual(r.learned, {})
+  assert.deepEqual(r.skipped, [{ kind: 'weld', judged: 3 }])
+  assert.equal(r.estimator, undefined, '배운 것이 없으면 시임을 만들지 않는다')
+  assert.equal(r.minSamples, DEFAULT_YIELD_MIN_SAMPLES)
+})
+
+test('하한은 소요보다 높다 — 비율은 드문 사건을 재는 값이다', () => {
+  /* 불량률 5% 인 공정은 20건에서 불량이 한 건이다 — 그 아래로 내려가면 이력이 잡음이 된다. */
+  assert.ok(DEFAULT_YIELD_MIN_SAMPLES >= 20, `하한이 ${DEFAULT_YIELD_MIN_SAMPLES} 이면 비율에 너무 낮다`)
+})
+
+test('전량 불량은 0 을 배운다 — 「값이 없다」와 구별한다', () => {
+  const r = buildYieldEstimator([group('paint', 0, 25)])
+  assert.equal(r.learned.paint, 0)
+  assert.equal(r.estimator!.estimate({ kind: 'paint' }), 0, '0 을 답한다(undefined 로 뭉개지 않는다)')
+})
+
+test('판정이 아예 없는 종류는 건너뛴 것이 아니다 — 품질을 가리지 않는 공정이 정상이다', () => {
+  const r = buildYieldEstimator([{ key: 'putaway', tasks: 500 } as any])
+  assert.deepEqual(r.learned, {})
+  assert.deepEqual(r.skipped, [], '표본 부족으로 세지 않는다')
+})
+
+test('모르는 종류에는 undefined — 커널이 선언값·상수로 내려갈 수 있게', () => {
+  const r = buildYieldEstimator([group('weld', 30, 2)])
+  assert.equal(r.estimator!.estimate({ kind: 'weld' }), 30 / 32)
+  assert.equal(r.estimator!.estimate({ kind: 'paint' }), undefined)
+})
+
+test("'unknown' 축은 쓰지 않는다 — 종류를 모르는 기록을 특정 종류의 근거로 삼지 않는다", () => {
+  const r = buildYieldEstimator([group('unknown', 100, 5)])
+  assert.deepEqual(r.learned, {})
+})
+
+test('빈 입력에도 답을 만든다 — 부르는 쪽이 조건문을 두 벌 갖지 않게', () => {
+  for (const input of [undefined, []]) {
+    const r = buildYieldEstimator(input as any)
+    assert.deepEqual(r.learned, {})
+    assert.equal(r.estimator, undefined)
+  }
+})
+
+/*
+ * ── 사슬이 이어져 있나 (소스로 지킨다) ──────────────────────────────────────
+ * 이 층은 넷이 이어져야 뜻이 있다: 커널이 판정을 적고 → 폴드가 축으로 들고 → KPI 가 세고 → 여기서 비율.
+ * 한 칸만 빠져도 화면은 「이력에서 배운 값」이라고 말하면서 상수로 돈다. 실 앱에서 관측하려면 라인이
+ * 한 바퀴 돌아야 하므로(판정은 완료에서 일어난다), 경로는 여기서 지킨다.
+ */
+test('사슬 넷이 이어져 있다 — 판정→축→집계→비율', () => {
+  const hostSrc = (f: string) => readFileSync(fileURLToPath(new URL(`../server/${f}`, import.meta.url)), 'utf-8')
+  assert.match(hostSrc('engine/kpi-fold.ts'), /facets\.outcome/, 'KPI 가 판정 축을 읽는다')
+  assert.match(hostSrc('engine/kpi-fold.ts'), /quality\?: \{ good: number; scrap: number \}/, '종류별로 센다')
+  const engine = hostSrc('engine/twin-engine.ts')
+  assert.match(engine, /buildYieldEstimator\(kpi\?\.groups\?\.items/, '같은 폴드에서 배운다(두 번 접지 않는다)')
+  assert.match(engine, /kernel\.yieldEstimator = yields\.estimator/, '커널 시임에 넣는다')
+  assert.match(engine, /yieldOf missing/, '옛 커널이면 그 사실을 말한다')
+})

package/test/operation-basis.test.ts

@@ -93,8 +93,35 @@ test('이력 목록은 선언 대조에도 쓰인다 — 오타를 그때부터
  */
 test('시뮬 기동이 모드를 적는다 — 「돌고 있나」를 묻는 쪽이 답을 받아야 한다', () => {
   const src = readFileSync(fileURLToPath(new URL('../server/engine/twin-engine.ts', import.meta.url)), 'utf-8')
-  assert.match(src, /id, domainId, mode: 'sim', runtime/, '시뮬 런타임도 모드를 든다')
+  assert.match(src, /mode: 'sim',\s*\n\s*runtime/, '시뮬 런타임도 모드를 든다')
   /* 답이 갈리는 자리 — 도는 트윈이면 「재기동 때 받는다」로 말해야 한다. */
   const mut = readFileSync(fileURLToPath(new URL('../server/service/twin-model/twin-model-mutation.ts', import.meta.url)), 'utf-8')
   assert.match(mut, /running \? 'on-restart' : 'stored'/)
 })
+
+/*
+ * ── 공정 모수도 목록에 실린다 (2026-08-19) ──────────────────────────────────
+ * 수율·셋업은 시간과 다른 표에 담긴다(`localParams`). 목록이 그것을 함께 들지 않으면 선언해 둔 값이
+ * 화면에서 사라지고, 그러면 철회할 자리도 없어진다. 원천이 말한 모수도 함께 들어 견줄 수 있게 한다.
+ */
+test('선언한 모수와 원천 모수를 함께 든다 — 무엇을 고쳤나가 보인다', () => {
+  const model = {
+    operations: [{ key: 'weld', label: 'Welding', intent: 'process', parameters: [{ id: 'yield', value: '0.7' }] }],
+    localParams: { weld: { yield: '0.92', setupDuration: 'PT30S' } }
+  }
+  const rows = operationBasis(model, kernelReporting([{ kind: 'weld', duration: 'declared' }]))
+  assert.deepEqual(rows, [
+    {
+      kind: 'weld',
+      label: 'Welding',
+      referenceParams: { yield: '0.7' },
+      basis: 'declared',
+      localParams: { yield: '0.92', setupDuration: 'PT30S' }
+    }
+  ])
+})
+
+test('모수만 선언한 공정도 목록에 남는다 — 커널이 아직 돌리지 않았어도', () => {
+  const rows = operationBasis({ localParams: { inspect: { yield: '0.99' } } }, undefined)
+  assert.deepEqual(rows, [{ kind: 'inspect', localParams: { yield: '0.99' } }])
+})