@things-factory/headless-twin 10.0.11 → 10.0.13

package/test/resolve-ts-siblings.mjs

@@ -0,0 +1,52 @@
+/*
+ * ★ 소스 시험이 형제 모듈을 부를 수 있게 한다 — **`operato-twin` 의 같은 규칙을 이 패키지에도 둔다** — **`.js` 로 적힌 상대 경로를 `.ts` 로 되짚는다.**
+ *
+ * ── 무엇이 서고 있었나 (2026-08-22) ─────────────────────────────────────────
+ * 이 패키지의 `npm test` 는 `node --test test/*.test.ts` 로 **소스를 그대로 실행**한다. 그런데 서버
+ * 소스는 tsc 로 빌드되는 코드이므로 상대 import 를 `'./x.js'` 로 적는다(그것이 빌드 산출물에서 맞는
+ * 경로다). 타입만 지우는 실행은 그 `.js` 를 `.ts` 로 바꿔 주지 않는다.
+ *
+ * 그래서 **소스 모듈이 형제 모듈을 값으로 참조하는 순간** 그 모듈 그래프를 부르는 시험이 전부 선다.
+ * 실측으로 하루에 네 종류가 이 벽에 걸렸다: `identity/namespace.js`(정체성 이름공간) ·
+ * `engine/log.js`(로그 문) · `isa95-coverage.js`(적합성 판정) · `journal-count.js`(저널 세기). 늘 같은 오류다.
+ *
+ *   Cannot find module '…/server/identity/namespace.js' imported from '…/templates/wms-unit-load.ts'
+ *
+ * ── 왜 이 방식인가 ──────────────────────────────────────────────────────────
+ * 고르던 길이 둘 있었다.
+ *
+ *  ① 그 시험들을 **빌드 산출물**(`dist-server`)로 돌린다 — 이 패키지에 전례가 있다. 그러나 시험마다
+ *     그 배선을 적어야 하고, 걸리는 시험이 늘 때마다 같은 일을 다시 한다. 그리고 산출물이 낡으면
+ *     **고친 코드가 아닌 것이 돌면서 초록으로 보인다.**
+ *  ② 상수를 쓰는 파일 안으로 옮긴다 — 값 참조가 사라지지만 **정본이 흩어진다.** 그것이 이 상수를 한
+ *     자리에 모은 이유와 정면으로 어긋난다.
+ *
+ * 둘 다 증상을 피하는 것이고, 원인은 **해석 규칙 하나**다. 그래서 규칙을 고친다: 상대 경로 `.js` 가
+ * 없고 같은 이름의 `.ts` 가 있으면 그것을 쓴다. 한 자리에 두므로 걸리는 시험이 늘어도 할 일이 없다.
+ *
+ * ── 무엇을 하지 않는가 ─────────────────────────────────────────────────────
+ * **패키지 이름(`@things-factory/…`)은 손대지 않는다.** 그것은 의존 패키지의 산출물을 가리키는
+ * 것이고 실제로 `.js` 가 있다. 되짚는 것은 **상대 경로**뿐이고, 그것도 `.ts` 가 실제로 있을 때만이다 —
+ * 없으면 원래 오류가 그대로 난다(없는 것을 지어내지 않는다).
+ */
+import { registerHooks } from 'node:module'
+import { existsSync } from 'node:fs'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+registerHooks({
+  resolve(specifier, context, nextResolve) {
+    /* 상대 경로의 `.js` 만 본다 — 패키지 이름과 그 밖의 확장자는 그대로 둔다. */
+    if (!specifier.startsWith('.') || !specifier.endsWith('.js')) return nextResolve(specifier, context)
+
+    try {
+      return nextResolve(specifier, context)
+    } catch (err) {
+      /* 해석이 실패한 그때만 `.ts` 를 본다 — 성공하는 경로의 뜻을 바꾸지 않는다. */
+      const parent = context?.parentURL
+      if (!parent) throw err
+      const asTs = new URL(specifier.slice(0, -3) + '.ts', parent)
+      if (!existsSync(fileURLToPath(asTs))) throw err
+      return { url: pathToFileURL(fileURLToPath(asTs)).href, shortCircuit: true, format: 'module-typescript' }
+    }
+  }
+})

package/test/restart-policy.test.ts

@@ -0,0 +1,111 @@
+/*
+ * **재기동 정책** — 개명(ADR-0029 §2)과 그 규율 둘.
+ *
+ * ── 무엇을 바꿨나 ───────────────────────────────────────────────────────────
+ * `realityMode`(`mirror`·`sim-world`·`sim-experiment`) → `restartPolicy`(`resync`·`resume`·`reset`).
+ * 「현실이 어디서 오나」는 ADR-0029 가 **원본의 종류**로 옮긴 물음이고, 코드가 이 축으로 실제로 가른 것은
+ * **재기동 거동 하나**였다 — 그것은 원본의 성질이 아니라 트윈과 자기 과거의 관계다. 그래서 축은 남고
+ * 이름이 바뀌었다.
+ *
+ * ── 지키는 규율 둘 (계획서 §6) ──────────────────────────────────────────────
+ * ① **모르는 값은 오류를 낸다.** 예전에는 미선언이 조용히 `sim-experiment`(=저널 초기화)로 떨어졌다 — 값이
+ *    하나 어긋나는 순간 이력을 지우는 길이다. 기본값을 없앴다.
+ * ② **옛 어휘를 번역하지 않는다.** 번역을 두면 옛 값이 살아남고 다시 저장된다. 저장된 값은 한 번
+ *    옮기고(데이터 이관), 코드는 새 어휘만 안다 — 다만 무엇으로 옮겨야 하는지는 오류 문장이 말한다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { join } from 'node:path'
+
+import { readRestartPolicy, isRestartPolicy, RESTART_POLICIES } from '../server/engine/restart-policy.ts'
+
+test('셋뿐이다 — 그리고 그 셋을 읽는다', () => {
+  assert.deepEqual([...RESTART_POLICIES], ['resync', 'resume', 'reset'])
+  for (const p of RESTART_POLICIES) assert.equal(readRestartPolicy(p, 'test'), p)
+  assert.equal(readRestartPolicy('  resume  ', 'test'), 'resume', '공백은 다듬는다')
+})
+
+test('미선언은 오류를 낸다 — 기본값으로 메우면 저널이 지워지는 길이 열린다', () => {
+  for (const raw of [undefined, null, '', '   ', 42, {}]) {
+    assert.throws(() => readRestartPolicy(raw, 'twin "x"'), /twin "x": restart policy/)
+  }
+  /* 무엇을 해야 하는지 문장이 말한다 — 코드를 그대로 오류를 내지 않는다. */
+  try {
+    readRestartPolicy(undefined, 'twin "x"')
+    assert.fail('오류를 내어야 한다')
+  } catch (e: any) {
+    assert.match(e.message, /resync \| resume \| reset/)
+    assert.match(e.message, /no default/)
+  }
+})
+
+test('옛 어휘도 오류를 낸다 — 다만 무엇으로 옮길지 말한다(번역해 주지 않는다)', () => {
+  const cases: [string, string][] = [
+    ['mirror', 'resync'],
+    ['sim-world', 'resume'],
+    ['sim-experiment', 'reset']
+  ]
+  for (const [old, next] of cases) {
+    try {
+      readRestartPolicy(old, 'twin "x"')
+      assert.fail(`${old} 은 오류를 내어야 한다`)
+    } catch (e: any) {
+      assert.match(e.message, /old vocabulary/)
+      assert.match(e.message, new RegExp(`"${next}"`), '옮길 값을 말한다')
+    }
+  }
+})
+
+test('묻는 자리도 있다 — 화면·검사는 오류를 내지 않고 판별한다', () => {
+  assert.equal(isRestartPolicy('resume'), true)
+  assert.equal(isRestartPolicy('sim-world'), false)
+  assert.equal(isRestartPolicy(undefined), false)
+})
+
+/*
+ * ── 옛 어휘가 코드로 되돌아오지 않게 (계획서 §6 의 검사) ────────────────────
+ * ADR-0034 의 `local-declarations.test.ts` 가 `site*` 에 대해 하는 것과 같은 방식이다. 개명은 저장값·타입·
+ * 화면에 걸쳐 있어서, 한 곳만 되돌아와도 그 자리가 조용히 다르게 재기동한다.
+ */
+const OLD_TOKENS = [/\brealityMode\b/, /\bRealityMode\b/, /'sim-world'/, /'sim-experiment'/, /DEFAULT_REALITY_MODE/]
+
+function sources(root: string): { file: string; src: string }[] {
+  const base = fileURLToPath(new URL(root, import.meta.url))
+  const out: { file: string; src: string }[] = []
+  const walk = (dir: string) => {
+    for (const name of readdirSync(dir)) {
+      if (name === 'node_modules' || name.startsWith('dist')) continue
+      const path = join(dir, name)
+      if (statSync(path).isDirectory()) { walk(path); continue }
+      if (name.endsWith('.ts')) out.push({ file: path.slice(base.length + 1), src: readFileSync(path, 'utf-8') })
+    }
+  }
+  walk(base)
+  return out
+}
+
+test('옛 어휘가 코드에 없다 — 이력을 설명하는 주석만 예외다', () => {
+  const offenders: string[] = []
+  for (const { file, src } of [...sources('../server'), ...sources('../test')]) {
+    /* 이력 설명(「예전에는 …」)과 이관 안내(restart-policy.ts)는 남아야 한다 — 그것이 개명의 근거다. */
+    if (file.endsWith('restart-policy.ts') || file.endsWith('restart-policy.test.ts')) continue
+    for (const line of src.split('\n')) {
+      const isComment = /^\s*(\*|\/\/|\/\*)/.test(line)
+      if (isComment) continue
+      if (OLD_TOKENS.some(re => re.test(line))) offenders.push(`${file}: ${line.trim().slice(0, 80)}`)
+    }
+  }
+  assert.deepEqual(offenders, [], `옛 어휘가 코드로 돌아왔다:\n${offenders.join('\n')}`)
+})
+
+test('기본값 상수가 없다 — 미선언을 우리가 고르지 않는다', () => {
+  const engine = readFileSync(fileURLToPath(new URL('../server/engine/twin-engine.ts', import.meta.url)), 'utf-8')
+  const code = engine
+    .split('\n')
+    .filter(line => !/^\s*(\*|\/\/|\/\*)/.test(line))
+    .join('\n')
+  assert.equal(/DEFAULT_RESTART_POLICY/.test(code), false, '기본값 상수가 되살아나면 미선언이 다시 조용해진다')
+  assert.match(code, /readRestartPolicy\(/, '읽는 자리는 엄격한 리더를 지난다')
+})

package/test/resync-origin-site.test.ts

@@ -73,5 +73,11 @@ test('프로비저닝이 고른 현장을 origin 에 남기고, 다시 읽기가
     .join('\n')
   assert.match(code, /kind: 'template', templateId, params: effective, \.\.\.\(spaceId \? \{ spaceId \} : \{\}\)/, '템플릿 트윈이 현장을 기억한다')
   assert.match(code, /const keepSpace = origin\.spaceId \|\| inst\.spaceId/, '기억이 없으면 지금 있는 현장을 지킨다')
-  assert.match(code, /ingestMaster\(domainId, master, keepSpace \? \{ spaceId: keepSpace \} : undefined/, '다시 읽기가 그 현장으로 넣는다')
+  /* 인자 사이에 재기동 정책이 끼었다(ADR-0029 §2) — 현장을 넘기는 인자는 그대로여야 한다. */
+  assert.match(code, /keepSpace \? \{ spaceId: keepSpace \} : undefined/, '다시 읽기가 그 현장으로 넣는다')
+  assert.match(
+    code,
+    /readRestartPolicy\(inst\.restartPolicy, `resync of twin/,
+    '다시 읽기는 그 트윈의 정책을 그대로 지킨다(구조만 새로 그린다)'
+  )
 })

package/test/revision-axis.test.ts

@@ -0,0 +1,93 @@
+/*
+ * ★ 리비전은 **두 셈**이고, 둘이 같은 것을 세지 않는다 — 그 사실을 코드가 지키는지 본다.
+ *
+ * ── 무엇이 어긋나 있었나 (2026-08-23 실측) ──────────────────────────────────
+ * 포천 미러의 체크포인트가 뜻이 다른 두 수를 나란히 적었다.
+ *
+ *   바깥 revision   12,972   저널에 적힌 줄 번호
+ *   state.revision   6,478   커널이 처리한 봉투 수
+ *
+ * 차이 6,494 는 그 트윈을 **다시 세운 시각**(09:11)에 저널이 이미 갖고 있던 줄 수와 정확히 같았다
+ * (줄 6494 = 08:23:59 · 줄 6495 = 09:11:13). 산수가 맞았으니 결함은 「수가 틀렸다」가 아니다.
+ *
+ * 결함은 **비대칭**이었다. 재기동 경로(`start` → `resumeRevision`)는 커널에 저널 머리를 알려 주는데
+ * 미러를 세우는 경로(`startLive`)는 알려 주지 않았다. 그래서 같은 저장물을 읽는 사람이 같은 이름의 두
+ * 수를 같은 축으로 견주게 되고, 실제로 그렇게 읽혔다(반나절이 그 오독에서 나갔다).
+ *
+ * ── 왜 알려 주어야 하나 ─────────────────────────────────────────────────────
+ * 커널의 계약이 그 이유를 적어 두었다(`resumeRevision`): 「저널이 비어 있지 않은데 0부터 다시 세면 같은
+ * 트윈에 같은 리비전이 둘 생기고, 재생 순서가 뒤섞이며, 시간여행이 엉뚱한 시점을 답한다 — 오류는 안 난다.」
+ * 조용히 깨지는 종류이므로 시험이 지킨다.
+ *
+ * ── 이 시험이 무엇을 재는가 ─────────────────────────────────────────────────
+ * DB 도 커널도 띄우지 않는다. 이 규율은 **어느 경로가 무엇을 부르나**에 있고 그것은 소스에서 확인된다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const ENGINE = join(import.meta.dirname, '..', 'server', 'engine', 'twin-engine.ts')
+const src = readFileSync(ENGINE, 'utf8')
+
+/**
+ * 그 함수 본문만 — 다른 경로의 호출이 섞여 판정이 흐려지지 않게.
+ *
+ * 끝은 **다음 멤버 선언**으로 자른다. 글자 수로 자르면 주석이 늘어난 날 조용히 짧아져서, 있는 것을
+ * 없다고 말한다(거짓 빨강을 내는 가드는 없는 것보다 나쁘다).
+ */
+function bodyOf(signature: string): string {
+  const at = src.indexOf(signature)
+  assert.ok(at > 0, `${signature} 이 있어야 한다`)
+  const rest = src.slice(at + signature.length)
+  const end = rest.search(/\n  (?:static|private static|\/\*\*)/)
+  const body = end === -1 ? rest : rest.slice(0, end)
+  /* 잘라낸 본문이 비면 판정이 성립하지 않는다 — 그것을 통과로 읽지 않는다. */
+  assert.ok(body.length > 200, `${signature} 본문을 잘라내지 못했다(${body.length}자)`)
+  return body
+}
+
+test('미러를 세우는 경로도 커널에 저널 머리를 알려 준다', () => {
+  const body = bodyOf('static startLive(')
+  /* 저널 머리를 읽는다 — 이 조회는 예전부터 있었다(inst.revision 시드용). */
+  assert.match(body, /order: \{ revision: 'DESC' \}/, '저널 머리를 읽어야 한다')
+  /* 그리고 **커널에도** 알려 준다 — 이 한 줄이 없어서 두 수가 갈렸다. */
+  assert.match(body, /resumeRevision\(head\)/, '커널에도 그 번호를 알려 준다')
+})
+
+test('재기동 경로는 예전부터 알려 주고 있었다 — 두 경로가 같아졌는지 본다', () => {
+  /*
+   * 이 단정은 「고쳤다」가 아니라 **두 경로가 대칭인지**를 지킨다. 한쪽만 남으면 같은 결함이 다른
+   * 문으로 되살아난다.
+   */
+  const body = bodyOf('static start(')
+  assert.match(body, /resumeRevision\(resumeFrom\)/, '재기동 경로도 알려 준다')
+})
+
+test('저널이 비어 있으면 알려 주지 않는다 — 새 트윈은 0 부터 세는 것이 맞다', () => {
+  const body = bodyOf('static startLive(')
+  assert.match(body, /if \(!head \|\| typeof/, '머리가 0 이면 아무 일도 하지 않는다')
+})
+
+test('뒤로 되돌리려는 거절을 삼키지 않는다', () => {
+  /*
+   * 조회가 비동기라 그 사이에 이벤트가 들어와 있을 수 있다. 그때 커널은 뒤로 가기를 거절한다(겹치는
+   * 번호를 막는 그 판정이다). 그 거절을 조용히 버리면 「왜 두 수가 아직 다르지」를 답할 계기가 없다.
+   */
+  const body = bodyOf('static startLive(')
+  assert.match(body, /catch \(err[^)]*\)[\s\S]{0,200}twinWarn/, '거절을 로그에 남긴다')
+  assert.match(body, /is behind the kernel/, '무엇이 어긋났는지 말한다')
+})
+
+test('체크포인트는 두 수를 나란히 적는다 — 그 사실 자체는 옳다', () => {
+  /*
+   * 바깥은 저널 줄 번호(이어 쓸 자리), 안쪽은 커널이 접은 봉투 수다. **둘을 하나로 합치지 않는다** —
+   * 합치면 「어디까지 적었나」와 「어디까지 반영했나」를 구별할 수 없고, 그 구별이 미러의 정직성이다.
+   * 두 경로가 대칭이면 값이 같아지지만, **자리는 둘이어야 한다.**
+   */
+  const at = src.indexOf('static async persistSnapshot')
+  assert.ok(at > 0, 'persistSnapshot 이 있어야 한다')
+  const body = src.slice(at, at + 1200)
+  assert.match(body, /inst\.revision \?\? state\.revision/, '바깥은 저널 줄 번호를 먼저 쓴다')
+  assert.match(body, /\{ revision, state/, '두 수를 나란히 싣는다')
+})

package/test/runtime-key.test.ts

@@ -39,7 +39,7 @@ test('인스턴스 id 안의 구분자를 보존한다 — 첫 구분자에서
   assert.equal(instanceId, weird)
 })
 
-test('도메인 id 에 구분자가 있으면 던진다 — 조용히 모호한 키를 만들지 않는다', () => {
+test('도메인 id 에 구분자가 있으면 오류를 낸다 — 조용히 모호한 키를 만들지 않는다', () => {
   /* 조용히 만들면 그게 곧 이 결함의 재발이다(어느 테넌트인지 알 수 없는 키). */
   assert.throws(() => runtimeKey(`a${RUNTIME_KEY_SEP}b`, 'x'), /ambiguous/)
 })
@@ -49,7 +49,7 @@ test('빈 값은 키가 될 수 없다 — 테넌트 없는 런타임은 없다'
   assert.throws(() => runtimeKey(D1, ''), /instanceId is required/)
 })
 
-test('키가 아닌 것을 되돌리려 하면 던진다', () => {
+test('키가 아닌 것을 되돌리려 하면 오류를 낸다', () => {
   for (const bad of ['', 'no-separator', `${RUNTIME_KEY_SEP}leading`, `trailing${RUNTIME_KEY_SEP}`]) {
     assert.throws(() => parseRuntimeKey(bad), /is not a runtime key/, `입력: "${bad}"`)
   }

package/test/scale-twin-bench.test.ts

@@ -1,7 +1,7 @@
 /*
  * 스케일 테스트 트윈 벤치 — 미국 공장(WMS+MES+YMS) 형태를 대규모로 스케일업, 5종 동기 엔티티 전부 부하.
  * 동기 엔티티 = locations·items(재고)·equipment·tasks·orders (노드/무버뿐이 아님). area 는 계층(건물>층>존).
- * 측정(가정 아닌 실측): masterToTwin(구조 생성)·apply(혼합 이벤트 처리량)·snapshot(전체 투영)·buildEntityDeltas(방송, 't1')·heap.
+ * 측정(가정 아닌 실측): masterToTwin(구조 생성)·apply(혼합 이벤트 처리량)·snapshot(전체 투영)·buildEntityDeltas(브로드캐스팅, 't1')·heap.
  * 순수 커널+호스트 매핑(shell·DB 무관) → node:test. area 는 공간층(projector State 밖)이라 처리량엔 무영향 — 구조 생성 비용에만.
  */
 import { test } from 'node:test'
@@ -87,7 +87,7 @@ for (const [name, tier] of Object.entries(TIERS)) {
     const tSnap = (performance.now() - t) / iters
     console.log(`  [${name}] snapshot: ${tSnap.toFixed(2)}ms/call (items ${s.items.length.toLocaleString()}·locations ${s.locations.length.toLocaleString()}·equipment ${s.equipment.length}·tasks ${s.tasks.length}·orders ${s.orders.length}) → 최대 ${Math.round(1000 / tSnap).toLocaleString()} snap/s`)
 
-    // 4) 방송 payload(buildEntityDeltas)
+    // 4) 브로드캐스팅 payload(buildEntityDeltas)
     t = performance.now()
     for (let k = 0; k < iters; k++) buildEntityDeltas(s, 't1')
     const tDelta = (performance.now() - t) / iters

package/test/source-outcome-audit.test.ts

@@ -0,0 +1,104 @@
+/*
+ * **허락과 일어남 사이를 같은 행에 닫는다** — ADR-0029 §1 결정 C (2026-08-19).
+ *
+ * ── 무엇이 열려 있었나 ──────────────────────────────────────────────────────
+ * 명령이 원본으로 가면 감사는 「허락했다」까지만 증명한다: 어댑터가 조용히 실패하면 원장에는 승인만 남는다.
+ * 그리고 구동 문(`controlTwinSource`)은 감사를 **아예 남기지 않았다** — 자극을 바꾸고 배속을 올리는 것은
+ * 그 트윈의 사실을 바꾸는 행위인데, 나중에 「무엇이 이 공장을 흔들었나」에 답할 수 없었다.
+ *
+ * ── 세 값을 구별한다 ────────────────────────────────────────────────────────
+ *  · 칸이 **없음** — 원본에 묻지 않았다(커널이 받은 명령).
+ *  · `unknown` — 물었는데 답이 없다. **성공으로 적지 않는다.**
+ *  · `applied`·`refused` — 원본이 답했다(둘 다 사실이다).
+ *
+ * 셋을 뭉개면 둘 중 하나가 된다: 일어난 일을 없던 일로 만들거나, 없던 일을 일어난 일로 만든다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+import { buildCommandAudit, sourceOutcomeOf } from '../server/service/twin-audit/command-audit.ts'
+
+const at = new Date('2026-08-19T05:00:00.000Z')
+
+test('묻지 않았으면 칸을 만들지 않는다 — 커널이 받은 명령이 그렇다', () => {
+  const row = buildCommandAudit({ command: { type: 'order.hold', origin: 'user' }, ack: { accepted: true }, at })
+  assert.equal('sourceOutcome' in row, false, '없음은 「모른다」가 아니라 「묻지 않았다」다')
+  assert.equal('sourceCode' in row, false)
+})
+
+test('물었는데 답이 없으면 unknown — 성공으로 적지 않는다', () => {
+  const row = buildCommandAudit({
+    command: { type: 'source.stimulus', origin: 'user' },
+    ack: { accepted: true },
+    source: { answered: false },
+    at
+  })
+  assert.equal(row.sourceOutcome, 'unknown')
+})
+
+test('답이 있으면 그대로 적는다 — 거절도 사실이다', () => {
+  const applied = buildCommandAudit({ command: {}, ack: { accepted: true }, source: { answered: true, ok: true }, at })
+  assert.equal(applied.sourceOutcome, 'applied')
+  const refused = buildCommandAudit({
+    command: {},
+    ack: { accepted: true },
+    source: { answered: true, ok: false, code: 'not-declared' },
+    at
+  })
+  assert.equal(refused.sourceOutcome, 'refused')
+  assert.equal(refused.sourceCode, 'not-declared', '원본이 준 사유를 그대로 적는다')
+})
+
+test('사유가 없으면 사유 칸도 없다 — 지어내지 않는다', () => {
+  const row = buildCommandAudit({ command: {}, ack: { accepted: true }, source: { answered: true, ok: true }, at })
+  assert.equal('sourceCode' in row, false)
+})
+
+test('판정 함수가 세 값만 낸다 — ok 가 참/거짓이 아니면 모른다', () => {
+  assert.equal(sourceOutcomeOf({ answered: true, ok: true }), 'applied')
+  assert.equal(sourceOutcomeOf({ answered: true, ok: false }), 'refused')
+  assert.equal(sourceOutcomeOf({ answered: false }), 'unknown')
+  assert.equal(sourceOutcomeOf({ answered: true }), 'unknown', '답했다고 하면서 값이 없으면 모르는 것이다')
+  assert.equal(sourceOutcomeOf({ answered: true, ok: undefined as any }), 'unknown')
+})
+
+test('신원은 여전히 서버만 채운다 — 원본의 답이 그 규율을 흔들지 않는다', () => {
+  const row = buildCommandAudit({
+    command: { type: 'source.pause', origin: 'user', actorId: 'forged', actorEmail: 'forged@x' },
+    ack: { accepted: true },
+    source: { answered: true, ok: true },
+    at,
+    actor: { id: 'u1', email: 'real@x' }
+  })
+  assert.equal(row.actorId, 'u1')
+  assert.equal(row.actorEmail, 'real@x')
+})
+
+/*
+ * ── 구동 문이 실제로 남기는지 (소스로 지킨다) ───────────────────────────────
+ * 순수 함수만 시험하면 「기록을 만들 수 있다」까지만 지킨다. 남기지 않으면 그 함수는 아무 일도 하지 않는다.
+ */
+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')
+  /* 게이트는 남는다(결정 C 의 절반). */
+  const gates = code.match(/@privilege\(category: "twin", privilege: "mutation"/g) ?? []
+  assert.ok(gates.length >= 2, `구동 문에도 게이트가 있어야 한다(발견 ${gates.length})`)
+  /* 원본의 답을 같은 행에 닫는다. */
+  assert.match(code, /source: \{ answered: typeof result\?\.ok === 'boolean', ok: result\?\.ok, code: result\?\.code \}/)
+  assert.match(code, /type: `source\.\$\{action\}`/, '커맨드 채널과 같은 어휘로 적는다')
+  /* 기록 실패를 삼키지 않는다. */
+  assert.match(code, /source control audit not recorded/)
+})
+
+test('엔티티가 그 두 칸을 든다 — 비어 있음이 뜻을 갖는다', () => {
+  const src = readFileSync(fileURLToPath(new URL('../server/service/twin-audit/twin-audit-event.ts', import.meta.url)), 'utf-8')
+  assert.match(src, /sourceOutcome\?: string/)
+  assert.match(src, /sourceCode\?: string/)
+  assert.match(src, /the source was not asked/, '비어 있음의 뜻을 필드 설명이 말한다')
+})

package/test/spec-coverage.test.ts

@@ -61,7 +61,7 @@ test('커널이 보고 API 를 갖지 않으면 undefined — "전부 기본값"
   assert.equal(readSpecCoverage(undefined), undefined)
 })
 
-test('커널 보고가 던져도 예측을 깨지 않는다', () => {
+test('커널 보고가 오류를 내어도 예측을 깨지 않는다', () => {
   assert.equal(readSpecCoverage({ specCoverage: () => { throw new Error('boom') } }), undefined)
 })
 

package/test/stage-path.test.ts

@@ -0,0 +1,95 @@
+/*
+ * ★ 단계 판정 — **체크리스트가 아니라 증거로 센다.**
+ *
+ * 이 테스트가 지키는 것:
+ *  ① **「모른다」는 달성이 아니다.** 계측되지 않은 신호(`null`)를 0 으로 대체하면 「반출 0건」과
+ *     「반출을 세지 않았다」가 같아진다. 배선하지 않은 계측으로 단계를 주장할 길을 남기지 않는다.
+ *  ② **반출을 세었는데 없으면 라이브가 아니다.** 되풀어 읽는 스냅샷은 원리적으로 반출을 못 낸다 —
+ *     이 판별식이 폴링을 「실시간」이라 부르는 것을 막는다.
+ *  ③ **선언이 비면 예측이 아니다.** 커널 기본값 위에 선 숫자도 화면에서는 예측처럼 보인다.
+ *  ④ **앞을 건너뛸 수 없다.** 뒤 단계는 자기 조건을 따지지 않고 `prerequisite` 으로 막는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { assessStagePath, forbiddenClaims, type StageEvidence } from '../server/engine/stage-path.ts'
+
+/** 전부 달성한 증거 — 각 시험은 여기서 한 축만 무너뜨린다(무엇이 판정을 바꿨는지 분명해진다). */
+const full = (): StageEvidence => ({
+  locationCount: 12,
+  itemCount: 340,
+  masterWarnings: 3,
+  liveIngestTotal: 1200,
+  removalsObserved: 17,
+  forecastRan: true,
+  specCoverage: { declared: 6, total: 8 },
+  actuateCapability: true,
+  correlatedEffectObserved: 2
+})
+
+test('전부 증거가 있으면 폐루프까지 도달하고 금지 표현이 없다', () => {
+  const p = assessStagePath(full())
+  assert.deepEqual(p.stages.map(s => s.achieved), [true, true, true, true])
+  assert.equal(p.reached, 'closed-loop')
+  assert.equal(p.next, null)
+  assert.deepEqual(forbiddenClaims(p), [])
+})
+
+test('못 옮긴 값을 세지 않았으면 구조도 달성이 아니다 — 0 이라고 우기지 않는다', () => {
+  const p = assessStagePath({ ...full(), masterWarnings: null })
+  const s1 = p.stages[0]
+  assert.equal(s1.achieved, false)
+  assert.deepEqual(s1.unmeasured, ['master-warnings'])
+  assert.deepEqual(s1.blockedBy, [], '자리와 물품은 있으므로 막힌 것이 아니라 모르는 것이다')
+  assert.equal(p.reached, null, '첫 칸을 못 밟았으면 서 있는 칸이 없다')
+})
+
+test('못 옮긴 값이 3건이어도 구조는 달성이다 — 요구는 「없다」가 아니라 「말할 수 있다」', () => {
+  assert.equal(assessStagePath({ ...full(), masterWarnings: 3 }).stages[0].achieved, true)
+  assert.equal(assessStagePath({ ...full(), masterWarnings: 0 }).stages[0].achieved, true)
+})
+
+test('반출을 세었는데 0 이면 라이브가 아니다 — 스냅샷 되풀어 읽기의 징표', () => {
+  const p = assessStagePath({ ...full(), removalsObserved: 0 })
+  assert.equal(p.stages[1].achieved, false)
+  assert.deepEqual(p.stages[1].blockedBy, ['no-removal-observed'])
+  assert.equal(p.reached, 'structure')
+  assert.ok(forbiddenClaims(p).includes('claim.realtime'), '실시간이라고 말할 수 없다')
+})
+
+test('반출이 계측되지 않으면 「없다」가 아니라 「모른다」로 막힌다', () => {
+  const p = assessStagePath({ ...full(), removalsObserved: null })
+  assert.deepEqual(p.stages[1].unmeasured, ['removals'])
+  assert.deepEqual(p.stages[1].blockedBy, [], '인제스트는 있으므로 막힌 것이 아니다')
+})
+
+test('선언이 비면 예측이 아니다 — 기본값 위에 선 숫자도 숫자로 보인다', () => {
+  const p = assessStagePath({ ...full(), specCoverage: { declared: 0, total: 8 } })
+  assert.equal(p.stages[2].achieved, false)
+  assert.deepEqual(p.stages[2].blockedBy, ['declarations-empty'])
+  assert.equal(p.reached, 'live')
+  assert.ok(forbiddenClaims(p).includes('claim.prediction'))
+})
+
+test('접수만으로는 폐루프가 아니다 — 효과가 관측으로 돌아와야 닫힌다', () => {
+  const p = assessStagePath({ ...full(), correlatedEffectObserved: 0 })
+  assert.deepEqual(p.stages[3].blockedBy, ['effect-not-observed'])
+  assert.equal(p.reached, 'forecast')
+})
+
+test('앞이 막히면 뒤는 자기 조건을 따지지 않는다 — 순서를 건너뛸 수 없다', () => {
+  const p = assessStagePath({ ...full(), locationCount: 0, itemCount: 0 })
+  assert.deepEqual(p.stages[0].blockedBy, ['no-locations', 'no-items'])
+  for (const later of p.stages.slice(1)) assert.deepEqual(later.blockedBy, ['prerequisite'])
+  assert.deepEqual(p.next, { stage: 'structure', blockedBy: ['no-locations', 'no-items'], unmeasured: [] })
+})
+
+test('다음 걸음은 목록이 아니라 하나다', () => {
+  const p = assessStagePath({ ...full(), removalsObserved: 0, specCoverage: null, actuateCapability: false })
+  assert.equal(p.next?.stage, 'live', '뒤쪽 결손을 함께 들이밀지 않는다')
+})
+
+test('비직렬 수량 물품만 있어도 구조는 달성이다 — 식품·화학은 개수로 오지 않는다', () => {
+  /* itemCount 는 「자리에 놓인 물품 수」이고, 비직렬 수량 물품(subLot)도 한 줄로 센다. */
+  assert.equal(assessStagePath({ ...full(), itemCount: 1 }).stages[0].achieved, true)
+})

package/test/standard-coverage.test.ts

@@ -11,9 +11,21 @@
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { standardsForKind } from '../server/service/twin-model/standard-coverage.ts'
-import { iec61850Coverage } from '../server/service/twin-model/iec61850-coverage.ts'
-import { epcisCoverage } from '../server/service/twin-model/epcis-coverage.ts'
+/*
+ * **빌드 산출물을 부른다** — 소스를 직접 실행하지 않는다.
+ *
+ * 이 모듈들은 서로를 값으로 참조한다(축 어긋남 판정을 한 곳에 두었다). 그 참조는 계약대로 `.js` 로
+ * 적히고, 타입만 지우고 소스를 실행하는 방식은 그 경로를 `.ts` 로 바꿔 주지 않는다. 그래서 소스를
+ * 부르면 「모듈을 찾을 수 없다」로 선다.
+ *
+ * **소스를 고친 뒤에는 `npm run build:server` 를 먼저 돌린다.**
+ */
+import { createRequire } from 'node:module'
+
+const req = createRequire(import.meta.url)
+const { standardsForKind } = req('../dist-server/service/twin-model/standard-coverage.js')
+const { iec61850Coverage } = req('../dist-server/service/twin-model/iec61850-coverage.js')
+const { epcisCoverage } = req('../dist-server/service/twin-model/epcis-coverage.js')
 import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 

package/test/status-tally.test.ts

@@ -0,0 +1,55 @@
+/*
+ * 상태별 내림 — **수 하나가 뜻을 바꾸지 않게** (2026-08-23).
+ *
+ * 커널이 관측 흡수에서 완료된 작업을 떨어뜨리지 않게 고쳐진 뒤, 개념 지도의 작업 카드가 0 에서 2,820 이
+ * 되었다. 카드는 상태의 인구조사이므로 그 수가 맞지만, 사람은 「지금 할 일 2,820건」으로 읽는다.
+ * 수를 줄여 맞는 척하게 만들지 않고, 무엇으로 이루어진 수인지 함께 낸다.
+ *
+ * 이 시험이 지키는 것:
+ *  ① 상태별로 갈라 세고, **많은 것부터** 낸다(카드가 한 줄로 보이므로 순서가 뜻을 만든다).
+ *  ② 낱말은 커널의 것 그대로 — 여기서 묶거나 고쳐 부르지 않는다.
+ *  ③ 상태를 말하지 않는 축은 **필드를 만들지 않는다**(빈 표는 「상태 없음」과 「못 읽음」을 뭉갠다).
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { statusTally } from '../server/service/twin-model/status-tally.ts'
+
+test('상태별로 갈라 세고 많은 것부터 낸다', () => {
+  const r = statusTally([
+    { id: 'a', status: 'completed' },
+    { id: 'b', status: 'in-progress' },
+    { id: 'c', status: 'completed' },
+    { id: 'd', status: 'completed' }
+  ])
+  assert.deepEqual(r.statusCounts, [
+    { status: 'completed', count: 3 },
+    { status: 'in-progress', count: 1 }
+  ])
+})
+
+test('낱말은 커널의 것 그대로 — 묶거나 고쳐 부르지 않는다', () => {
+  const r = statusTally([{ status: 'assigned' }, { status: 'created' }])
+  assert.deepEqual(
+    r.statusCounts?.map(s => s.status).sort(),
+    ['assigned', 'created'],
+    '「대기」처럼 앱의 낱말로 바꾸면 커널이 늘린 낱말을 화면이 조용히 잘못 부른다'
+  )
+})
+
+test('상태를 말하지 않는 축은 필드를 만들지 않는다', () => {
+  assert.deepEqual(statusTally([{ id: 'loc-1' }, { id: 'loc-2' }]), {}, '빈 표를 내지 않는다')
+  assert.deepEqual(statusTally([]), {})
+  assert.deepEqual(statusTally(null), {})
+  assert.deepEqual(statusTally({ id: 'not-a-list' }), {}, '목록이 아니면 셀 것이 없다')
+})
+
+test('상태를 말하는 것만 센다 — 없는 것을 「모름」이라는 갈래로 만들지 않는다', () => {
+  const r = statusTally([{ status: 'completed' }, { id: 'x' }, { status: '' }, { status: 7 }])
+  assert.deepEqual(r.statusCounts, [{ status: 'completed', count: 1 }])
+})
+
+test('한 갈래뿐이면 그대로 한 갈래다 — 화면이 그때는 내림을 감춘다', () => {
+  const r = statusTally([{ status: 'completed' }, { status: 'completed' }])
+  assert.deepEqual(r.statusCounts, [{ status: 'completed', count: 2 }], '판단은 화면이 하고, 사실은 그대로 낸다')
+})