@things-factory/headless-twin 10.0.11 → 10.0.13

package/test/live-cursor-wiring.test.ts

@@ -0,0 +1,87 @@
+/*
+ * ★ 읽기 커서는 **부르는 쪽이 자리를 가리켜야** 이어진다 — 커넥터는 그 이름을 알 수 없다.
+ *
+ * ── 무엇이 조용히 끊겨 있었나 (2026-08-23) ──────────────────────────────────
+ * 커서를 저장할 컬럼과 계약을 만들고 배선까지 했는데, **한 번도 저장되지 않았다.** 저장할 자리를
+ * `cfg`·`site` 에서 찾으려 했기 때문이다.
+ *
+ *   cfg    사람이 화면에서 입력한 접속 설정 — endpoint · token · subdomain · liveLookbackDays
+ *   site   커넥터가 원본에서 발견한 것 — { siteId, name }
+ *
+ * **둘 다 그 값을 가질 수 없다.** 레퍼런스의 이름(`TwinReference.source`)은 **호스트가 붙이는 것**이고
+ * 원본은 그것을 모른다. 커넥터가 채울 수 없는 값을 커넥터에서 읽으려 한 것이 잘못이었다.
+ *
+ * 그리고 그 실패는 **로그로는 말했다** — 「this feed does not say which reference it reads from」.
+ * 그 한 줄로 다른 레인이 바로 짚었다(조용히 넘기지 않은 것이 값을 했다). 그러나 로그는 사람이 볼 때만
+ * 값이 있다. 배선이 다시 끊기면 이 시험이 먼저 말한다.
+ *
+ * ── 왜 「늘었나」로 확인하면 안 되나 ────────────────────────────────────────
+ * 재기동 뒤 수가 늘어도 그것은 커서가 이어진 증거가 아니다 — 실제로 같은 판에 다른 변경(공정별 전이)이
+ * 들어가 작업 수가 배로 늘었고, 그 사이 커서는 여전히 매번 새로 만들어졌다. 확인할 것은 **배선**이다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const DIR = join(import.meta.dirname, '..', 'server', 'service', 'reference')
+const LIVE = readFileSync(join(DIR, 'reference-live.ts'), 'utf8')
+const RESOLVER = readFileSync(join(DIR, 'reference-resolver.ts'), 'utf8')
+
+/** 주석을 걷어낸 코드만 — 「쓰지 않는다」를 적어 둔 근거가 가드를 뒤집지 않게. */
+function codeOf(src: string): string {
+  return src.replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/(^|[^:])\/\/.*$/gm, '$1')
+}
+
+test('커서를 저장할 자리는 부르는 쪽이 가리킨다 — cfg·site 에서 짐작하지 않는다', () => {
+  const code = codeOf(LIVE)
+  /* 커넥터가 채울 수 없는 값을 커넥터의 인자에서 읽지 않는다. */
+  assert.doesNotMatch(code, /cfg as any\)\?\.source/, 'cfg 에서 레퍼런스 이름을 찾지 않는다')
+  assert.doesNotMatch(code, /site as any\)\?\.source/, 'site 에서 레퍼런스 이름을 찾지 않는다')
+  /* 대신 인자로 받는다. */
+  assert.match(code, /loadLiveCursor\(domainId, instanceId, source\)/, '받은 이름으로 커서를 찾는다')
+  /* 가드가 스스로를 증명한다 — 주석을 걷어낸 코드가 비어 버리지 않았다. */
+  assert.match(code, /startReferenceLiveFeed/, '대상 함수가 남아 있다')
+})
+
+test('모든 호출처가 그 이름을 넘긴다 — 한 곳만 빠져도 그 경로는 조용히 창이 미끄러진다', () => {
+  /*
+   * 호출처가 둘이고 **둘 다** `TwinReference` 를 들고 있다(부팅 재개 · 인제스트 직후 기동).
+   * 하나만 넘기면 그 경로로 세워진 트윈만 커서를 잃고, 그 차이는 오류 없이 조용하다.
+   */
+  const calls = [...codeOf(LIVE).matchAll(/startReferenceLiveFeed\(([^)]*)\)/g)].map(m => m[1])
+  const resolverCalls = [...codeOf(RESOLVER).matchAll(/startReferenceLiveFeed\([\s\S]{0,200}?\)/g)].map(m => m[0])
+  const all = [...calls.filter(a => !a.includes('domainId: string')), ...resolverCalls]
+  assert.ok(all.length >= 2, `호출처를 찾지 못했다 (${all.length}) — 이 가드가 아무것도 지키지 않는다`)
+  for (const call of all) {
+    assert.match(call, /ref\.source/, `이 호출처가 레퍼런스 이름을 넘기지 않는다: ${call.replace(/\s+/g, ' ')}`)
+  }
+})
+
+test('이름이 없으면 조용히 돌지 않는다 — 말한다', () => {
+  /*
+   * 커서 없이 도는 것은 「창이 매번 미끄러진다」는 뜻이고, 그 손실은 오류 없이 사라진다. 그래서 그
+   * 사실을 로그로 말한다 — 실제로 그 한 줄이 이 결함을 찾아냈다.
+   */
+  const code = codeOf(LIVE)
+  assert.match(code, /if \(!source\)[\s\S]{0,200}twinWarn/, '이름이 없으면 경고한다')
+  assert.match(code, /did not say which reference/, '무엇이 없어서 못 이었는지 말한다')
+  /* 행을 못 찾은 경우도 따로 말한다 — 이름은 왔는데 그 레퍼런스가 없는 것은 다른 사실이다. */
+  assert.match(code, /no reference row for source/, '레퍼런스 행이 없는 경우를 가려 말한다')
+})
+
+test('커서는 레퍼런스의 것이다 — 인스턴스마다 두지 않는다', () => {
+  /*
+   * 한 레퍼런스가 여러 인스턴스를 낳고(`scopeSpec.produced`) 원본을 읽는 것은 한 번이다.
+   * 인스턴스마다 커서를 두면 같은 표를 여러 번 읽는다.
+   */
+  const code = codeOf(LIVE)
+  assert.match(code, /getRepository\(TwinReference\)/, '레퍼런스 행에 저장한다')
+  assert.match(code, /liveCursor: next/, '어댑터가 준 모양을 그대로 적는다')
+  assert.doesNotMatch(code, /liveCursor[\s\S]{0,40}instanceId/, '인스턴스로 커서를 가르지 않는다')
+})
+
+test('저장 실패를 삼키지 않는다', () => {
+  /* 조용히 실패하면 다음 재기동에서 창이 다시 미끄러지고, 이 컬럼을 만든 이유가 사라진다. */
+  assert.match(codeOf(LIVE), /live cursor not saved/, '저장 실패를 말한다')
+})

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

@@ -11,7 +11,15 @@
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { registerLiveFeedProbe, liveFeedAttached, liveFeedStateOf } from '../server/engine/live-feed-registry.ts'
+/*
+ * **빌드 산출물을 부른다** — 이 모듈은 로그 문(`engine/log.js`)을 값으로 참조하고, 타입만 지우고 소스를
+ * 실행하는 방식은 그 `.js` 경로를 `.ts` 로 바꿔 주지 않는다. 소스를 부르면 「모듈을 찾을 수 없다」로 선다.
+ * **소스를 고친 뒤에는 `npm run build:server` 를 먼저 돌린다.**
+ */
+import { createRequire } from 'node:module'
+
+const req = createRequire(import.meta.url)
+const { registerLiveFeedProbe, liveFeedAttached, liveFeedStateOf } = req('../dist-server/engine/live-feed-registry.js')
 
 /* 두 계층의 장부를 흉내낸다 — 커넥터 기반과 프리셋 기반. */
 const connectorFeeds = new Set<string>()
@@ -41,15 +49,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 +71,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/live-kernel-facts.test.ts

@@ -57,26 +57,26 @@ test('식별자가 아니라 **객체 동일성**으로 가른다 — 어댑터
   assert.equal(/applying\.has\(e\.eventId\)/.test(start), false, 'id 비교로 되돌아갔다')
 })
 
-test('커널이 낸 사실도 방송을 예약한다 — 피크·마감은 상태를 바꾼다', () => {
+test('커널이 낸 사실도 브로드캐스팅을 예약한다 — 피크·마감은 상태를 바꾼다', () => {
   const body = methodOf('startLive')
-  assert.match(body, /inst\.dirty = true/, '상태가 바뀌었으므로 다음 주기에 방송해야 한다')
-  assert.match(body, /ensureBroadcastCoalescer\(\)/, '방송은 주기로 합친다(사건마다 방송하면 폭발한다)')
+  assert.match(body, /inst\.dirty = true/, '상태가 바뀌었으므로 다음 주기에 브로드캐스팅해야 한다')
+  assert.match(body, /ensureBroadcastCoalescer\(\)/, '브로드캐스팅은 주기로 합친다(사건마다 브로드캐스팅하면 폭발한다)')
 })
 
 /*
- * ── 구조 전환도 방송한다 (2026-08-18) ───────────────────────────────────────
+ * ── 구조 전환도 브로드캐스팅한다 (2026-08-18) ───────────────────────────────────────
  * 화면이 보는 것 상당수가 구조에서 파생된다(계약 대비 판정·주목 신호·자리 색). 구조 전환이 조용히
  * 끝나면 지도 레일은 다음 계측 표본이 올 때까지 옛 화면을 들고 있고, 헤더 배지는 폴링으로 먼저 알아
  * 「배지엔 있고 목록엔 없는」 어긋난 화면이 된다(실화면에서 봤다).
  */
-test('구조 전환은 상태 방송을 예약한다 — 다음 표본까지 화면이 옛것을 들고 있지 않게', () => {
+test('구조 전환은 상태 브로드캐스팅을 예약한다 — 다음 표본까지 화면이 옛것을 들고 있지 않게', () => {
   const body = methodOf('adoptStructure')
   assert.match(body, /inst\.dirty = true/, '구조가 바뀐 순간이 상태가 바뀐 순간이다')
   assert.match(body, /ensureBroadcastCoalescer\(\)/, '새 경로가 아니라 있는 병합 규율에 얹는다')
-  /* 커널 전환보다 먼저 방송하면 구독자가 옛 스냅샷을 되물어 간다 — 순서가 규율이다. */
+  /* 커널 전환보다 먼저 브로드캐스팅하면 구독자가 옛 스냅샷을 되물어 간다 — 순서가 규율이다. */
   assert.ok(
     body.indexOf('inst.kernel.adoptStructure(model)') < body.indexOf('inst.dirty = true'),
-    '커널을 갈고 나서 방송한다'
+    '커널을 갈고 나서 브로드캐스팅한다'
   )
 })
 

package/test/live-mirror-parity.test.ts

@@ -22,6 +22,10 @@ const master = () => ({
   source: 'mirror',
   system: 'wms' as const,
   siteName: 'M',
+  /* 이 픽스처가 식별자를 만드는 이름공간 — **픽스처마다 다르게** 둔다(같은 접두 아래에서 서로 다른
+     시험의 번호가 부딪치면 표준의 유일성 요구를 깬다, CBV 2.0 §8.2.4). 커널은 선언 없이 팔레트·문서를
+     만들지 않는다(0.7.45 에서 날조 프리픽스를 지웠다). */
+  identity: { namespaces: ['https://twin.test/live-mirror-parity'] },
   space: { width: 90, depth: 40, unit: 'm' },
   locations: [
     { id: 'a-dc', type: 'warehouse', role: 'area' as const, name: '창고' },
@@ -99,6 +103,8 @@ test('★ 라이브 미러: 핵심 관측 상태(점유·용량·위치·아이
 function runSimRich() {
   const m = {
     source: 'rich', system: 'wms' as const, siteName: 'R',
+    /* 같은 파일이라도 픽스처가 다르면 이름공간도 다르다 — 두 픽스처의 번호가 한 공간에서 겹치지 않게. */
+    identity: { namespaces: ['https://twin.test/live-mirror-parity/rich'] },
     space: { width: 90, depth: 40, unit: 'm' },
     locations: [
       { id: 'a', type: 'warehouse', role: 'area' as const, name: '창고' },

package/test/load-meter.test.ts

@@ -11,21 +11,7 @@
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
 
-import {
-  fleetLoad,
-  newCpuSampler,
-  sampleCpu,
-  judgeCycle,
-  loadSummary,
-  newLoadMeter,
-  recordFork,
-  recordPhase,
-  rollWindow,
-  slowTickMessage,
-  TICK_BUDGET_RATIO,
-  WARN_COOLDOWN_MS,
-  WINDOW_MS
-} from '../server/engine/load-meter.ts'
+import { LOAD_PHASES, fleetLoad, newCpuSampler, sampleCpu, judgeCycle, loadSummary, newLoadMeter, recordFork, recordPhase, rollWindow, slowTickMessage, TICK_BUDGET_RATIO, WARN_COOLDOWN_MS, WINDOW_MS } from '../server/engine/load-meter.ts'
 
 const TICK = 1000
 
@@ -312,3 +298,31 @@ test('시계가 뒤로 가거나 구간이 0 이면 비율을 지어내지 않
   assert.equal(sampleCpu(s, 1_200_000, 1000), null, '구간 0')
   assert.equal(sampleCpu(newCpuSampler(), 5, 5), null)
 })
+
+/*
+ * ── 부팅 구간도 재는 이름을 갖는다 (2026-08-22) ─────────────────────────────
+ * 실측으로 부팅이 620~717초였고 트윈 하나를 세우는 데 15~93초였는데, **어느 작업이 그 시간을 쓰는지
+ * 답할 이름이 없었다** — 재는 이름이 도는 중의 작업뿐이었다. 그래서 짐작으로 원인을 적을 수밖에
+ * 없었고, 그것은 이 프로젝트가 금하는 일이다.
+ */
+test('부팅 구간을 재는 이름이 있다 — 웜스타트와 자극 시작', () => {
+  assert.ok(LOAD_PHASES.includes('warmStart' as any), '상태 심기를 재는 이름이 있어야 한다')
+  assert.ok(LOAD_PHASES.includes('stimulus' as any), '자극 시작을 재는 이름이 있어야 한다')
+
+  /* 계기가 그 값을 실제로 들고 답한다 — 이름만 있고 담기지 않으면 화면이 빈칸을 보인다. */
+  const m = newLoadMeter()
+  recordPhase(m, 'warmStart', 93_000, 1_000)
+  recordPhase(m, 'stimulus', 72_000, 1_000)
+  assert.equal(m.phases.warmStart?.maxMs, 93_000)
+  assert.equal(m.phases.stimulus?.maxMs, 72_000)
+})
+
+test('부팅 구간은 틱 예산으로 판정하지 않는다 — 한 번뿐인 일이다', () => {
+  /*
+   * 웜스타트는 트윈을 세울 때 한 번이고 몇십 초가 정상일 수 있다. 그것을 틱 예산(간격의 절반)으로
+   * 재면 부팅마다 「느린 주기」가 쏟아진다 — 거짓 경보는 참 경보를 죽인다. 판정은 틱만 받는다.
+   */
+  const m = newLoadMeter()
+  recordPhase(m, 'warmStart', 93_000, 1_000)
+  assert.equal(m.overBudget, 0, '기록만으로는 판정하지 않는다')
+})

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'
+    ],
     '읽는 코드가 있는 것만'
   )
   /* 모르는 속성은 이제 「어휘가 없다」가 아니라 **「그 속성을 읽지 않는다」**로 거절된다(더 정확하다). */
@@ -418,7 +426,7 @@ test('현장 겹이 원천 값을 덮으면 그 원천 값을 기억한다 —
  * 모델에 설비 `load-1` 이 두 번 있던 것이다. 배선이 사라지지 않게 소스 모양으로 지킨다(이 함수는 DB 를
  * 물고 있어 단위 시험이 불러올 수 없다).
  */
-test('구조 투영이 중복 id 를 이름으로 말한다 — 제약 위반 문구를 사용자에게 던지지 않는다', () => {
+test('구조 투영이 중복 id 를 이름으로 말한다 — 제약 위반 문구를 사용자에게 보이지 않는다', () => {
   const src = readFileSync(fileURLToPath(new URL('../server/service/twin-model/project-structure.ts', import.meta.url)), 'utf-8')
   assert.match(src, /has two \$\{what\} with id/, '무엇이 겹쳤는지 이름으로 말한다')
   assert.match(src, /ids must be unique within a twin/, '규칙도 함께 말한다')
@@ -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/log-stamp.test.ts

@@ -0,0 +1,59 @@
+/*
+ * 로그에 **시각이 있다** — 그리고 어떤 인자도 버리지 않는다 (2026-08-22).
+ *
+ * 루프가 55초 막힌 것을 계기로 알아냈는데 그 시각에 무슨 일이 있었는지 로그에서 찾을 수 없었다.
+ * 트윈의 줄이 `console.log` 로 나가 시각이 없었기 때문이다. 이 시험이 지키는 것:
+ *  ① 형식 — 프레임워크 줄과 같은 모양, **밀리초까지**(계기의 값이 epoch ms 다)
+ *  ② 지역 시각 — 프레임워크의 다른 줄과 같은 기준(UTC 로 찍으면 나란히 읽을 수 없다)
+ *  ③ 인자를 버리지 않는다 — 오류는 스택까지(`console.error(msg, err)` 로 쓰던 자리가 많다)
+ *  ④ 트윈 소스에 `console.` 직접 호출이 남지 않는다 — 하나라도 남으면 그 줄만 시각이 없다
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync, readdirSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+import { line, stamp } from '../server/engine/log.ts'
+
+test('시각은 밀리초와 오프셋까지 적는다 — 같은 초 안의 순서를 가릴 수 있게', () => {
+  const s = stamp(new Date(2026, 7, 22, 5, 54, 12, 345))
+  assert.match(s, /^2026-08-22T05:54:12\.345[+-]\d\d:\d\d$/, `형식이 다르다: ${s}`)
+})
+
+test('지역 시각으로 적는다 — 프레임워크의 다른 줄과 같은 기준', () => {
+  const at = new Date(2026, 0, 2, 3, 4, 5, 6)
+  const s = stamp(at)
+  assert.ok(s.startsWith('2026-01-02T03:04:05.006'), `지역 시각이 아니다: ${s}`)
+})
+
+test('오류는 스택까지 남는다 — 「어디서 났나」를 잃지 않게', () => {
+  const err = new Error('불이 났다')
+  const out = line(['[twin-engine] 저장 실패', err])
+  assert.ok(out.includes('[twin-engine] 저장 실패'))
+  assert.ok(out.includes('불이 났다'))
+  assert.ok(out.includes('log-stamp.test'), '스택이 있어야 어느 자리에서 났는지 알 수 있다')
+})
+
+test('값이 없어도 있었다는 사실은 남긴다 — 조용히 지우지 않는다', () => {
+  assert.equal(line(['a', undefined, null, 0]), 'a undefined null 0')
+  const circular: any = { name: 'ㄱ' }
+  circular.self = circular
+  assert.ok(line(['보고', circular]).startsWith('보고 '), '순환 참조에도 줄이 남아야 한다')
+})
+
+test('트윈 소스에 console 직접 호출이 남아 있지 않다 — 한 줄이라도 남으면 그 줄만 시각이 없다', () => {
+  const root = fileURLToPath(new URL('../server/', import.meta.url))
+  const offenders: string[] = []
+  const walk = (dir: string) => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const p = dir + e.name
+      if (e.isDirectory()) walk(p + '/')
+      else if (e.name.endsWith('.ts') && e.name !== 'log.ts') {
+        const src = readFileSync(p, 'utf-8')
+        for (const m of src.matchAll(/console\.(log|warn|error)\(/g)) offenders.push(`${p.slice(root.length)}  console.${m[1]}`)
+      }
+    }
+  }
+  walk(root)
+  assert.deepEqual(offenders, [], `시각 없는 로그가 남아 있다 — twinLog·twinWarn·twinError 를 쓴다:\n  ${offenders.join('\n  ')}`)
+})

package/test/loop-lag.test.ts

@@ -0,0 +1,82 @@
+/*
+ * 루프 지체 계기 — **원인을 지어내지 않기 위한 값**이 정확한지 본다 (2026-08-21).
+ *
+ * 지키는 것:
+ *  ① 늦게 깨어난 만큼만 지체다 — 제때 깨어난 표본은 0 이고, 0 을 정체로 세지 않는다.
+ *  ② 창이 닫히기 전에는 `recent` 가 **null** 이다(채우는 중인 창을 「지금」으로 읽으면 과소 집계다).
+ *  ③ 가장 길게 막힌 **시각**을 든다 — 언제였는지가 원인을 가리는 근거다.
+ *  ④ 문턱 이하의 흔들림은 정체로 세지 않는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { LoopLagSampler } from '../server/engine/loop-lag.ts'
+
+/** 시계를 손으로 밀어 넣는다 — 실제 타이머로 재면 기계 상태가 결과를 정한다. */
+function sampler(sampleMs = 500, stallMs = 200, windowMs = 10_000) {
+  let now = 1_000_000
+  const s = new LoopLagSampler(sampleMs, stallMs, windowMs, () => now)
+  return { s, advance: (ms: number) => (now += ms), at: () => now }
+}
+
+test('제때 깨어난 표본은 지체가 0 이고 정체로 세지 않는다', () => {
+  const { s, advance, at } = sampler()
+  for (let i = 0; i < 4; i++) {
+    advance(500)
+    assert.equal(s.sample(at()), 0)
+  }
+  assert.equal(s.view().total.stalls, 0)
+  assert.equal(s.view().total.maxMs, 0)
+  assert.equal(s.view().total.samples, 4)
+})
+
+test('늦게 깨어난 만큼이 지체다 — 그 초과분만', () => {
+  const { s, advance, at } = sampler()
+  advance(500)
+  s.sample(at())
+  advance(4_600) // 예정보다 4,100ms 늦게
+  assert.equal(s.sample(at()), 4_100)
+  assert.equal(s.view().total.maxMs, 4_100)
+  assert.equal(s.view().total.stalls, 1)
+})
+
+test('문턱 이하의 흔들림은 정체가 아니다 — 값은 남기고 세지는 않는다', () => {
+  const { s, advance, at } = sampler(500, 200)
+  advance(650) // 150ms 지체 — 문턱 200 미만
+  s.sample(at())
+  const v = s.view()
+  assert.equal(v.total.maxMs, 150)
+  assert.equal(v.total.stalls, 0, '문턱 이하를 세면 정상 상태가 정체로 보인다')
+})
+
+test('창이 닫히기 전에는 recent 가 null 이다 — 채우는 중인 창을 「지금」으로 읽지 않는다', () => {
+  const { s, advance, at } = sampler(500, 200, 2_000)
+  advance(500)
+  s.sample(at())
+  assert.equal(s.view().recent, null)
+
+  /* 창 길이를 넘기면 그 창이 닫혀 `recent` 가 된다. */
+  advance(2_000)
+  s.sample(at())
+  const v = s.view()
+  assert.ok(v.recent, '창 길이를 넘겼으면 닫힌 창이 있어야 한다')
+  assert.equal(v.recent!.stalls, 1, '1,500ms 지체는 정체 한 번이다')
+})
+
+test('가장 길게 막힌 시각을 든다 — 언제였는지가 원인을 가린다', () => {
+  const { s, advance, at } = sampler()
+  advance(500)
+  s.sample(at())
+  advance(3_000)
+  const worst = at()
+  s.sample(worst)
+  advance(500)
+  s.sample(at())
+  assert.equal(s.view().worstAtMs, worst)
+})
+
+test('한 번도 재지 않았으면 정체 시각은 null 이다 — 0 으로 적지 않는다', () => {
+  const { s } = sampler()
+  assert.equal(s.view().worstAtMs, null)
+  assert.equal(s.view().recent, null)
+})

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/, '옛 커널이면 그 사실을 말한다')
+})