@things-factory/headless-twin 10.0.13 → 10.0.15

package/test/cursor-stall-not-read-failure.test.ts

@@ -0,0 +1,126 @@
+/*
+ * ★ **조치가 반대인 두 사실을 한 이름으로 부르면 그 이름은 정보가 아니라 오해다.**
+ *
+ * ── 무엇이 반대 방향을 가리켰나 (2026-08-24) ────────────────────────────────
+ * 2026-08-23 에 「원본에 닿지 못한다」를 트윈이 말할 수 있게 `onReadFailure` 를 만들었다. 그런데 그 문으로
+ * **다른 사실**이 함께 나가고 있었다.
+ *
+ *   원본에 닿지 못했다        접속 실패·시간 초과 → **기다리면 풀린다**
+ *   읽었는데 커서가 못 넘어간다  한 시각에 한 페이지보다 많은 행 → **기다려도 안 풀린다**
+ *
+ * 둘째는 **읽기가 성공한 실패**다. 원본은 답했고 그 답의 모양이 커서를 이겼다. 그런데 화면이
+ * 「원본에 닿지 못한다」고 말하면 사람은 원본을 의심하고 기다린다 — 실제로 필요한 조치는 페이지를
+ * 키우거나 같은 시각 안에서 순서를 정하는 것이고, 기다림으로는 영원히 풀리지 않는다.
+ *
+ * 게다가 그 문구가 스트림 이름을 꺼내는 규칙에 맞지 않아 **어느 표가 막혔는지도 남지 않았다.**
+ *
+ * ── 이 시험이 지키는 것 ─────────────────────────────────────────────────────
+ * ① 두 축이 **서로를 지우지 않는다**  ② 두 축이 **각자 뷰로 나간다**(유입이 없는 갈래에서도)
+ * ③ 「몇 번·언제부터」를 정체 쪽도 든다  ④ 넘어가면 지운다
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import {
+  clearCursorStall,
+  clearReadFailure,
+  ingestHealth,
+  newIngestLedger,
+  recordCursorStall,
+  recordIngest,
+  recordReadFailure
+} from '../server/engine/ingest-health.ts'
+
+const T0 = Date.parse('2026-08-24T06:00:00.000Z')
+
+test('정체는 읽기 실패와 **다른 칸**이다 — 서로를 지우지 않는다', () => {
+  /*
+   * ★ 한 칸을 쓰면 나중에 온 것이 앞의 것을 덮는다. 그러면 「닿지 못한다」와 「못 넘어간다」 중
+   * 마지막 것만 남고, 화면은 조치를 반대로 안내할 수 있다.
+   */
+  const l = newIngestLedger()
+  recordReadFailure(l, 'connect ETIMEDOUT', T0, 'inventory')
+  recordCursorStall(l, 'one timestamp holds more rows than a page', T0 + 1000, 'trace')
+  assert.equal(l.readFailure?.reason, 'connect ETIMEDOUT', '읽기 실패가 남아 있다')
+  assert.equal(l.cursorStall?.reason, 'one timestamp holds more rows than a page')
+  assert.equal(l.readFailure?.stream, 'inventory')
+  assert.equal(l.cursorStall?.stream, 'trace', '어느 표가 막혔나가 조치의 절반이다')
+})
+
+test('각자 지워진다 — 하나가 풀렸다고 다른 하나를 지우지 않는다', () => {
+  const l = newIngestLedger()
+  recordReadFailure(l, 'ETIMEDOUT', T0)
+  recordCursorStall(l, 'cursor cannot advance', T0)
+  clearReadFailure(l)
+  assert.equal(l.readFailure, undefined, '다시 닿았다')
+  assert.ok(l.cursorStall, '그렇다고 커서가 넘어간 것은 아니다')
+  clearCursorStall(l)
+  assert.equal(l.cursorStall, undefined, '넘어갔으면 지운다')
+})
+
+test('「몇 번·언제부터」를 정체 쪽도 든다 — 한 번 밀린 것과 사흘째는 다르다', () => {
+  const l = newIngestLedger()
+  recordCursorStall(l, 'stuck at 2026-04-15T01:49', T0)
+  recordCursorStall(l, 'stuck at 2026-04-15T01:49', T0 + 600_000)
+  recordCursorStall(l, 'stuck at 2026-04-15T01:49', T0 + 1_200_000)
+  assert.equal(l.cursorStall?.consecutive, 3)
+  assert.equal(l.cursorStall?.sinceMs, T0, '처음 막힌 시각을 지킨다')
+  assert.equal(l.cursorStall?.lastAtMs, T0 + 1_200_000)
+  /* 넘어간 뒤 다시 막히면 **새 정체**다 — 옛 시작 시각을 물려받지 않는다. */
+  clearCursorStall(l)
+  recordCursorStall(l, 'stuck again', T0 + 3_600_000)
+  assert.equal(l.cursorStall?.consecutive, 1)
+  assert.equal(l.cursorStall?.sinceMs, T0 + 3_600_000)
+})
+
+test('뷰로 나간다 — **유입이 없는 갈래에서도**', () => {
+  /*
+   * ★ 여기가 가장 조용해지기 쉬운 자리다. 커서가 막히면 유입이 0이므로 장부가 「빈 장부」 갈래를
+   * 지나고, 그 갈래에서 이 값을 떨어뜨리면 **정체가 실제로 일어나는 바로 그 상황에서** 침묵한다.
+   * `unhandled` 를 스냅샷이 떨어뜨려 정합성 검사가 영원히 조용했던 것과 같은 부류다.
+   */
+  const l = newIngestLedger()
+  recordCursorStall(l, 'one timestamp holds more rows than a page', T0, 'trace')
+  const v = ingestHealth(l, 'attached', undefined, T0 + 60_000)
+  assert.ok(v.cursorStall, '유입이 없어도 뷰에 실린다')
+  assert.equal(v.cursorStall?.consecutive, 1)
+  assert.equal(v.cursorStall?.since, new Date(T0).toISOString())
+  assert.equal(v.cursorStall?.stream, 'trace')
+  assert.equal(v.readFailure, undefined, '닿지 못한 것은 아니다 — 섞이지 않는다')
+})
+
+test('유입이 있는 갈래에서도 나간다 — 두 갈래를 다 채운다', () => {
+  /* 갈래가 둘인 함수에서 한쪽만 채우는 실수를 이 저장소가 이미 겪었다. */
+  const l = newIngestLedger()
+  recordIngest(l, 5, [], T0)
+  recordCursorStall(l, 'cursor cannot advance', T0 + 1000, 'lot')
+  const v = ingestHealth(l, 'attached', undefined, T0 + 2000)
+  assert.equal(v.total.offered, 5, '유입이 있는 갈래다 — 빈 비교로 통과하지 않는다')
+  assert.equal(v.cursorStall?.stream, 'lot')
+})
+
+test('막히지 않았으면 그 칸을 만들지 않는다 — 빈 값이 「막혔다」로 읽히지 않게', () => {
+  const l = newIngestLedger()
+  recordIngest(l, 3, [], T0)
+  assert.equal(ingestHealth(l, 'attached', undefined, T0 + 1000).cursorStall, undefined)
+})
+
+test('두 사실이 같은 문으로 나가지 않는다 — 배선을 소스로 확인한다', () => {
+  /*
+   * 장부만 시험하면 **호스트가 여전히 읽기 실패 문으로 보내도** 초록이다. 실제로 그랬던 것이 이 결함의
+   * 시작이었다.
+   */
+  const src = readFileSync(join(import.meta.dirname, '..', 'server', 'service', 'reference', 'reference-live.ts'), 'utf8')
+  const code = src.replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/(^|[^:])\/\/.*$/gm, '$1')
+  assert.match(code, /onCursorStall:/, '어댑터의 정체 통로를 잇는다')
+  assert.match(code, /recordIngestCursorStall/, '정체는 정체 장부로 간다')
+  /* 그리고 그 문구가 「닿지 못한다」와 달라야 한다 — 같은 말이면 화면이 여전히 반대로 안내한다. */
+  const at = code.indexOf('onCursorStall:')
+  const body = code.slice(at, at + 900)
+  assert.match(body, /cursor cannot advance/, '무엇이 막혔는지 말한다')
+  assert.match(body, /Waiting will not clear this/, '기다림이 답이 아니라고 말한다')
+  assert.doesNotMatch(body, /recordIngestReadFailure/, '읽기 실패 장부로 보내지 않는다')
+  /* 재부착의 자격(`status`)은 여기서도 건드리지 않는다 — 2026-08-23 에 되돌린 그 규율. */
+  assert.doesNotMatch(body, /status:/, '정체가 피드를 영구히 끄지 않는다')
+})

package/test/item-ref.test.ts

@@ -8,12 +8,12 @@
  * ── 그리고 고치는 방향을 한 번 더 고쳤다 ────────────────────────────────────
  * 처음에는 「`@` 뒤는 개체다」를 규칙으로 넣었다. 그것은 **한 원본(chef)의 관행**이고, 커널 계약이 그
  * 구분자를 정한 적이 없다 — 사용자가 「이 화면이 특정 레거시를 기준으로 해서는 안 된다」고 짚었다.
- * 그래서 자르는 판단을 걷고, **그 트윈의 선언과 견주어** 답한다.
+ * 그래서 자르는 판단을 걷고, **그 트윈의 선언과 비교해** 답한다.
  *
  * 이 시험이 지키는 것:
  *  ① SGTIN 은 표준이 정한 자리에서 품목 참조를 꺼낸다.
  *  ② 그 밖의 모양은 **손대지 않는다**(구분자를 모른다).
- *  ③ 선언과 견줄 때는 두 방향을 본다 — 관측이 선언을 확장한 경우, 화면이 짧게 줄인 경우.
+ *  ③ 선언과 비교할 때는 두 방향을 본다 — 관측이 선언을 확장한 경우, 화면이 짧게 줄인 경우.
  *  ④ 후보가 둘 이상이면 **답하지 않는다**(모르는 것이 틀린 답보다 낫다).
  */
 import { test } from 'node:test'
@@ -64,7 +64,7 @@ test('화면이 짧게 줄인 경우 — 선언이 그것으로 끝난다', () =
   assert.equal(resolveByDeclaration('product-M0000438', DECLARED), 'M0000438')
 })
 
-test('후보가 둘 이상이면 답하지 않는다 — 남의 레시피와 견주지 않게', () => {
+test('후보가 둘 이상이면 답하지 않는다 — 남의 레시피와 비교하지 않게', () => {
   const ambiguous = new Map<string, string>([
     ['https://a.net/class/product-1', 'A1'],
     ['https://b.net/class/product-1', 'B1']

package/test/mirror-resumes-from-checkpoint.test.ts

@@ -0,0 +1,192 @@
+/*
+ * ★ **재기동이 저널을 처음부터 다시 접지 않는다** — 미러가 저장된 재개점에서 이어 선다.
+ *
+ * ── 무엇이 오래 잘못돼 있었나 (2026-08-24 실측) ─────────────────────────────
+ * 재개점을 **읽는** 쪽은 다 있었다: `recover` 는 `fold` 가 있으면 꼬리만 접고, 없으면 저널을 0부터
+ * 접는다. 그런데 **쓰는 쪽이 없었다** — `persistSnapshot` 은 `{revision, state, structureRev}` 만
+ * 적었다. 실측으로 저장된 스냅샷 34건 전부 `fold` 가 비어 있었고, 저널은 2,960만 줄이었다.
+ *
+ * 그래서 두 가지가 함께 일어났다.
+ *
+ *   ① 켤 때마다 처음부터 접었다 — 규모 기준(엔티티 10만·품목 100만)에서 느린 것이 아니라 못 하는 것이다
+ *   ② 미러는 되찾은 상태를 **버렸다**(`startLive`). 「다음 계측이 정정한다」는 전제였는데, 원본이 커서
+ *      증분으로 말하는 현장에서는 그 정정이 오지 않는다 — 미러가 영구히 빈 채로 남고 화면은 조용했다
+ *
+ * ── 왜 커널 시험만으로 충분하지 않나 ────────────────────────────────────────
+ * 커널은 「재개점 + 꼬리 == 0부터 접기」를 증명한다(`observed-checkpoint.test.ts`). 그것이 참이어도
+ * 호스트가 재개점을 **적지 않거나 되세우지 않으면** 아무 일도 일어나지 않는다 — 이 저장소가 실제로
+ * 넉 달 동안 그 상태였다. 그래서 여기서 DB 를 물고 실제로 걷는다.
+ *
+ * ── 결정적인 단정 ───────────────────────────────────────────────────────────
+ * 재기동 전에 **저널을 지운다.** 그래도 상태가 돌아오면 그것은 저널을 접어 온 것이 **아니다** —
+ * 저장된 재개점에서 온 것이다. 그리고 그 상황은 가정이 아니라 설계된 거동이다: 보존 정책이 체크포인트
+ * 리비전 이하의 행을 지운다(「그 앞은 스냅샷이 대신한다」).
+ */
+import { test, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { createRequire } from 'node:module'
+import type { DataSource } from 'typeorm'
+
+const req = createRequire(import.meta.url)
+const { NamingStrategy, addDataSource, entities: shellEntities, Domain } = req('@things-factory/shell')
+const { entities: authEntities } = req('@things-factory/auth-base')
+const { entities: twinEntities } = req('../dist-server/service/index.js')
+/* 체크포인트는 `cache-service` 표에 앉는다 — 그 엔티티를 빼면 저장이 조용히 실패한다(스냅샷도 씨앗도). */
+const { entities: cacheEntities } = req('@things-factory/cache-service/dist-server/service/index.js')
+const { TwinEngine } = req('../dist-server/engine/index.js')
+const { TwinEvent } = req('../dist-server/service/twin-event/twin-event.js')
+const { DataSource: TypeOrmDataSource } = req('typeorm')
+
+let ds: DataSource
+let domainId: string
+
+const INSTANCE = 'resume-probe'
+
+/** 미러 하나 — 원본이 사실을 말해 주는 트윈이므로 시나리오도 레시피도 필요 없다. */
+const master = (): any => ({
+  source: INSTANCE,
+  system: 'wms',
+  siteName: '재개점 창고',
+  origin: { kind: 'reference' }, // 현실 출처 선언 — 이것이 미러로 뜨는 근거다
+  space: { width: 40, depth: 20, unit: 'm' },
+  locations: [
+    { id: 'dock', type: 'dock', role: 'location', capacity: 100 },
+    { id: 'bin-1', type: 'storage', role: 'location', capacity: 100 }
+  ],
+  equipment: [{ id: 'fk-1', kind: 'forklift', homeLocationId: 'dock' }]
+})
+
+/** 원본이 말한 사실 — 오더와 작업. 미러는 이것을 접어 상태를 만든다. */
+function facts(n: number): any[] {
+  const out: any[] = []
+  for (let i = 1; i <= n; i++) {
+    out.push({
+      eventId: `o-${i}`,
+      eventType: 'order.status',
+      eventTime: '2026-08-24T01:00:00.000Z',
+      tenantId: domainId,
+      data: { orderId: `WO-${i}`, kind: 'workorder', status: 'in-progress', requested: 10, fulfilled: 3 }
+    })
+    out.push({
+      eventId: `t-${i}`,
+      eventType: 'task.status',
+      eventTime: '2026-08-24T01:00:01.000Z',
+      tenantId: domainId,
+      data: {
+        taskId: `TK-${i}`,
+        kind: 'putaway',
+        status: 'in-progress',
+        orderId: `WO-${i}`,
+        fromNode: 'dock',
+        toNode: 'bin-1',
+        intent: 'transport',
+        durationMs: 60000,
+        remainingMs: 30000
+      }
+    })
+  }
+  return out
+}
+
+const observed = (s: any): number => (s?.items?.length ?? 0) + (s?.orders?.length ?? 0) + (s?.tasks?.length ?? 0)
+
+before(async () => {
+  ds = new TypeOrmDataSource({
+    type: 'sqlite',
+    database: ':memory:',
+    synchronize: true,
+    dropSchema: true,
+    namingStrategy: new NamingStrategy(),
+    entities: [...shellEntities, ...authEntities, ...twinEntities, ...cacheEntities],
+    logging: false
+  })
+  await ds.initialize()
+  addDataSource('default', ds)
+  const d = await ds.getRepository(Domain).save({ name: 'resume-test', subdomain: 'resume-test' } as any)
+  domainId = d.id
+  await TwinEngine.ingestMaster(domainId, master(), 'reset')
+})
+
+after(async () => {
+  await TwinEngine.stop(domainId, INSTANCE).catch(() => {})
+  await ds?.destroy()
+})
+
+test('체크포인트가 **이어 접을 씨앗을 함께 적는다** — 이 줄이 없어서 넉 달 동안 처음부터 접었다', async () => {
+  const rt = await TwinEngine.bootDeclared(domainId, INSTANCE, 'resync')
+  assert.equal(rt.mode, 'live', '미러로 떠야 이 검사가 뜻이 있다')
+
+  const applied = TwinEngine.ingestLive(domainId, INSTANCE, facts(5))
+  assert.equal(applied, 10, '원본이 말한 사실이 커널에 들어갔다')
+  const before = TwinEngine.snapshot(domainId, INSTANCE)
+  assert.ok(observed(before) > 0, `상태에 사실이 있어야 이 검사가 뜻이 있다 (실제 ${observed(before)})`)
+
+  await TwinEngine.persistSnapshot(domainId, INSTANCE)
+  const stored = await TwinEngine.loadSnapshot(domainId, INSTANCE)
+  assert.ok(stored, '스냅샷이 저장됐다')
+  assert.ok(stored.fold?.reducer, '★ 재개점이 함께 적혀야 한다 — 없으면 다음 기동이 저널을 0부터 접는다')
+  assert.ok(stored.fold?.oee, '가동 누적기도 함께 — 상태만 되돌리면 가동률이 부팅 이후로만 잡힌다')
+  /* 씨앗이 실제로 사실을 들었는지 — 빈 껍데기를 적어 두고 초록이 되지 않게. */
+  assert.ok((stored.fold.reducer as any).orders?.length, '씨앗에 오더가 담겨 있다')
+  assert.ok((stored.fold.reducer as any).tasks?.length, '씨앗에 작업이 담겨 있다')
+})
+
+test('★ 저널을 지워도 미러가 상태를 들고 다시 선다 — 그러므로 저널을 접은 것이 아니다', async () => {
+  /*
+   * 이 단정이 이 축의 전부다. 저널이 없는데 상태가 돌아오면 그 상태는 **저장된 재개점**에서 온 것이다.
+   * 그리고 이 상황은 가정이 아니다 — 보존 정책이 체크포인트 리비전 이하의 행을 실제로 지운다.
+   */
+  const before = observed(TwinEngine.snapshot(domainId, INSTANCE))
+  assert.ok(before > 0, '멈추기 전에 상태가 있어야 이 검사가 뜻이 있다')
+
+  await TwinEngine.stop(domainId, INSTANCE)
+  /* 이 인스턴스의 저널만 — 정확한 소유 표식으로 지운다. */
+  await ds.getRepository(TwinEvent).delete({ domain: { id: domainId } as any, instanceId: INSTANCE } as any)
+  assert.equal(
+    await ds.getRepository(TwinEvent).countBy({ domain: { id: domainId } as any, instanceId: INSTANCE } as any),
+    0,
+    '저널이 비었다 — 이제 접을 것이 없다'
+  )
+
+  await TwinEngine.bootDeclared(domainId, INSTANCE, 'resync')
+  const after = TwinEngine.snapshot(domainId, INSTANCE)
+  assert.equal(observed(after), before, '★ 사실이 그대로 돌아왔다 — 저널 없이')
+  assert.equal(after.orders.length, 5, '오더 다섯이 그대로다')
+  assert.equal(after.tasks.length, 5, '작업 다섯이 그대로다')
+})
+
+test('되세운 뒤 들어온 사실이 앞의 것을 덮지 않는다 — 더해진다', async () => {
+  /*
+   * 미러는 첫 봉투가 올 때 리듀서를 만든다. 되돌리기가 그보다 먼저 서지 않으면 첫 봉투가 **빈 리듀서**를
+   * 만들고 되세운 것을 덮는다 — 오류 없이 상태가 사라진다.
+   */
+  const before = observed(TwinEngine.snapshot(domainId, INSTANCE))
+  TwinEngine.ingestLive(domainId, INSTANCE, [
+    {
+      eventId: 'o-new',
+      eventType: 'order.status',
+      eventTime: '2026-08-24T02:00:00.000Z',
+      tenantId: domainId,
+      data: { orderId: 'WO-NEW', kind: 'workorder', status: 'in-progress', requested: 1, fulfilled: 0 }
+    } as any
+  ])
+  const after = TwinEngine.snapshot(domainId, INSTANCE)
+  assert.equal(observed(after), before + 1, '앞의 것이 남고 새 것이 더해진다')
+  assert.ok(after.orders.some((o: any) => o.id === 'WO-1'), '되세운 오더가 남아 있다')
+  assert.ok(after.orders.some((o: any) => o.id === 'WO-NEW'), '새 오더도 있다')
+})
+
+test('씨앗이 없으면 지어내지 않는다 — 전과 같이 빈 채로 시작한다', async () => {
+  /*
+   * 처음 뜨는 트윈에는 씨앗이 없다. 여기서 무엇이든 심으면 없던 재고가 생긴다 — 그것은 이 작업이
+   * 고치려던 것보다 나쁘다.
+   */
+  const FRESH = 'resume-probe-fresh'
+  await TwinEngine.ingestMaster(domainId, { ...master(), source: FRESH }, 'reset')
+  try {
+    await TwinEngine.bootDeclared(domainId, FRESH, 'resync')
+    assert.equal(observed(TwinEngine.snapshot(domainId, FRESH)), 0, '아무것도 듣지 못했으므로 비어 있다')
+  } finally {
+    await TwinEngine.stop(domainId, FRESH).catch(() => {})
+  }
+})

package/test/revision-axis.test.ts

@@ -87,7 +87,18 @@ test('체크포인트는 두 수를 나란히 적는다 — 그 사실 자체는
    */
   const at = src.indexOf('static async persistSnapshot')
   assert.ok(at > 0, 'persistSnapshot 이 있어야 한다')
-  const body = src.slice(at, at + 1200)
+  /*
+   * 창을 넓혀 왔다 — 이 함수 앞쪽에 「빈 상태로 좋은 스냅샷을 덮지 않는다」 가드가 들어오고(§
+   * `checkpoint-refuses-empty`), 뒤쪽에 「이어 접을 씨앗을 함께 적는다」가 들어왔다(§
+   * `mirror-resumes-from-checkpoint`). 검사하는 **사실은 그대로**다.
+   *
+   * 그리고 **줄 모양이 아니라 두 자리를 검사한다**: 예전에는 `{ revision, state` 라는 한 줄 모양을
+   * 봤는데, 저장 인자가 여러 줄로 나뉘자 사실이 그대로인데도 빨강이 됐다. 서식이 검사를 깨면 다음
+   * 사람이 검사를 지우게 된다 — 그래서 이름 둘이 함께 실리는지만 본다.
+   */
+  const body = src.slice(at, at + 5000)
   assert.match(body, /inst\.revision \?\? state\.revision/, '바깥은 저널 줄 번호를 먼저 쓴다')
-  assert.match(body, /\{ revision, state/, '두 수를 나란히 싣는다')
+  const call = body.slice(body.indexOf('setInCache'))
+  assert.match(call, /revision/, '저널 줄 번호를 싣는다')
+  assert.match(call, /state/, '커널이 접은 상태를 함께 싣는다 — 두 자리를 하나로 합치지 않는다')
 })

package/test/standard-coverage.test.ts

@@ -26,6 +26,7 @@ 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')
+const { isa95Coverage } = req('../dist-server/service/twin-model/isa95-coverage.js')
 import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
@@ -104,3 +105,46 @@ test('계측은 EPCIS 센서 필드로 오지 않는다 — 그 사실을 표가
   assert.equal(sensor.behavior, 'none')
   assert.ok(sensor.note, '에너지가 다른 층으로 들어온다는 사실을 근거로 적는다')
 })
+
+test('★ 「어디서 보이나」가 화면 등급과 어긋나지 않는다 — 표가 없는 화면으로 사람을 보내지 않게', () => {
+  /*
+   * ── 무엇이 틀려 있었나 (2026-08-24 실측) ──────────────────────────────────
+   * `shownOn` 은 「그 사실이 어느 축에 **담겨 있나**」가 아니라 「**어디서 보이나**」다. 화면이 그것을
+   * 「해당 축 항목에 표시됩니다」로 읽어 내므로, `surface: 'none'` 인 줄에 갈 곳이 적혀 있으면 표가
+   * **거짓을 말한다** — 사람을 그 개념이 보이지 않는 화면으로 보낸다.
+   *
+   * 같은 날 넷이 그랬다. 셋은 새로 넣으면서(`TestResult`·`OperationsEvent`), 하나는 오래(`errorDeclaration`
+   * — 그 줄의 `note` 는 「화면에 보이는 곳은 아직 없습니다」라고 말하는데 배지는 반대를 말했다).
+   *
+   * 반대 방향도 본다: 화면에 보이는데 축도 갈 곳도 주석도 없으면 그 줄은 **「진짜 빈칸」으로 읽힌다**
+   * (`shownOn` 주석이 정한 규칙이다). `MaterialSublot` 이 그랬다 — 물품 이름으로 보이는데 갈 곳이 비어
+   * 있었다.
+   *
+   * 사람이 눈으로 보고 잡았다. 그래서 기계가 잡게 한다.
+   */
+  const AXES = [
+    'items', 'locations', 'equipment', 'persons', 'assets', 'tasks', 'orders', 'operations', 'recipes',
+    'testSpecifications', 'materialDefinitions', 'materialClasses', 'personnelClasses', 'equipmentClasses',
+    'assetClasses', 'productionSpec', 'demandWindows', 'meters'
+  ]
+  const tables: [string, { concepts: any[] }][] = [
+    ['ISA-95', isa95Coverage(AXES)],
+    ['EPCIS', epcisCoverage(AXES)],
+    ['IEC 61850', iec61850Coverage(AXES)]
+  ]
+
+  const lies: string[] = []
+  const mute: string[] = []
+  for (const [name, table] of tables) {
+    for (const c of table.concepts) {
+      if (c.surface === 'none' && c.shownOn?.length) lies.push(`${name}/${c.std} → ${c.shownOn.join(',')}`)
+      if (c.surface !== 'none' && !c.axis && !c.shownOn?.length && !c.note) mute.push(`${name}/${c.std}`)
+    }
+  }
+  assert.deepEqual(lies, [], `화면이 없는데 갈 곳을 적은 줄 — 없는 화면으로 사람을 보낸다:\n${lies.join('\n')}`)
+  assert.deepEqual(mute, [], `화면에 보이는데 갈 곳도 주석도 없는 줄 — 「진짜 빈칸」으로 읽힌다:\n${mute.join('\n')}`)
+
+  /* 빈 비교로 통과하지 않게 — 표가 실제로 여러 줄을 들고 있다. */
+  const total = tables.reduce((n, [, t]) => n + t.concepts.length, 0)
+  assert.ok(total > 30, `표 셋에 줄이 실제로 있어야 한다 (실제 ${total})`)
+})

package/test/status-tally.test.ts

@@ -6,16 +6,16 @@
  * 수를 줄여 맞는 척하게 만들지 않고, 무엇으로 이루어진 수인지 함께 낸다.
  *
  * 이 시험이 지키는 것:
- *  ① 상태별로 갈라 세고, **많은 것부터** 낸다(카드가 한 줄로 보이므로 순서가 뜻을 만든다).
+ *  ① 상태별로 구분해 세고, **많은 것부터** 낸다(카드가 한 줄로 보이므로 순서가 뜻을 만든다).
  *  ② 낱말은 커널의 것 그대로 — 여기서 묶거나 고쳐 부르지 않는다.
- *  ③ 상태를 말하지 않는 축은 **필드를 만들지 않는다**(빈 표는 「상태 없음」과 「못 읽음」을 뭉갠다).
+ *  ③ 상태를 말하지 않는 축은 **필드를 만들지 않는다**(빈 표는 「상태 없음」과 「못 읽음」을 구분하지 못한다).
  */
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
 
 import { statusTally } from '../server/service/twin-model/status-tally.ts'
 
-test('상태별로 갈라 세고 많은 것부터 낸다', () => {
+test('상태별로 구분해 세고 많은 것부터 낸다', () => {
   const r = statusTally([
     { id: 'a', status: 'completed' },
     { id: 'b', status: 'in-progress' },

package/test/twin-event-keys.test.ts

@@ -62,8 +62,50 @@ test('집합 이벤트는 parentID 를, 수량 이벤트는 epcClass 를 품목
   assert.equal(epcOf({ data: { quantityList: [{ epcClass: 'urn:epc:idpat:sgtin:0614141.107346.*', quantity: 40 }] } }), 'urn:epc:idpat:sgtin:0614141.107346.*')
 })
 
-test('운영 델타의 오더는 bizTransactionList 가 아니라 order 필드에 있다', () => {
-  assert.equal(orderOf({ eventType: 'order.status', data: { order: 'SO-10021', status: 'released' } }), 'SO-10021')
+test('★ 운영 델타의 오더는 `orderId` 다 — 이 시험이 결함을 고정하고 있었다', () => {
+  /*
+   * ── 무엇이 잘못돼 있었나 (2026-08-24 실측) ────────────────────────────────
+   * 이 시험은 `data: { order: 'SO-10021' }` 를 단정했다. **커널은 그런 모양을 낸 적이 없다** —
+   * 오더는 `orderId` 다(`OrderStatusDelta.orderId` · `TaskStatusDelta.orderId`). 픽스처가 실제 델타
+   * 대신 **스스로 지어낸 모양**을 썼고, 추출기도 같은 이름을 찾고 있었으니 둘이 나란히 초록이었다.
+   *
+   * 그동안 실 저널에서:
+   *   order.status  29,403,565 행 — order_id 100% 비어 있음
+   *   task.status      191,175 행 — 100% 비어 있음
+   *
+   * 색인 `ix_twin_event_4`(「이 오더가 어디까지 갔나」)가 자기 용도로 못 쓰였고, 화면은 오더를 눌러도
+   * 「연결된 이벤트가 없습니다」를 냈다.
+   *
+   * **교훈**: 승격 키의 픽스처는 **커널이 실제로 내는 델타**여야 한다. 지어낸 모양으로 검사하면
+   * 추출기와 시험이 함께 틀린 채로 영원히 초록이다.
+   */
+  assert.equal(orderOf({ eventType: 'order.status', data: { orderId: 'WO-260410-0133', status: 'in-progress' } }), 'WO-260410-0133')
+  assert.equal(orderOf({ eventType: 'task.status', data: { taskId: 'TK-1', orderId: 'WO-1' } }), 'WO-1')
+  /* 오더를 스스로 말하면 그 말이 이긴다 — 거래(PO/SO)와 오더는 같은 것이 아닐 수 있다. */
+  assert.equal(
+    orderOf({ data: { orderId: 'WO-1', bizTransactionList: [{ bizTransaction: 'urn:epc:id:gdti:0614141.402.2' }] } }),
+    'WO-1'
+  )
+  /* 오더를 말하지 않는 EPCIS 는 거래로 내려간다(전과 같다). */
+  assert.equal(orderOf({ data: { bizTransactionList: [{ bizTransaction: 'PO-9' }] } }), 'PO-9')
+})
+
+test('★ 승격 키는 **커널이 실제로 내는 델타 모양**으로 검사한다', () => {
+  /*
+   * 위 결함의 부류는 「추출기가 찾는 이름을 발신자가 쓰지 않는다」이고, 지어낸 픽스처로는 절대 잡히지
+   * 않는다. 그래서 실 저널에서 뜬 payload 모양을 그대로 놓고 단정한다 — 세 축이 실제로 채워지는지.
+   */
+  const orderDelta = { eventType: 'order.status', data: { orderId: 'order-1', kind: 'workorder', status: 'in-progress' } }
+  const taskDelta = {
+    eventType: 'task.status',
+    data: { taskId: 'task-1', orderId: 'order-1', kind: 'cut', status: 'in-progress', resourceRef: 'cutter-1', fromNode: 'st-a', toNode: 'st-b' }
+  }
+  const energyEq = { eventType: 'energy.equipment', data: { equipmentId: 'pv-roof', at: '2026-08-17T10:45:20.664Z', generatedKW: 426 } }
+
+  assert.equal(twinEventKeys(orderDelta).orderId, 'order-1', '오더 사건이 오더 축을 채운다')
+  assert.equal(twinEventKeys(taskDelta).orderId, 'order-1', '작업도 자기 오더를 채운다 — 오더의 이력에 작업이 실린다')
+  assert.equal(twinEventKeys(taskDelta).moverId, 'cutter-1', '작업이 쓴 자원이 설비 축에 실린다(`resourceRef`)')
+  assert.equal(twinEventKeys(energyEq).moverId, 'pv-roof', '에너지 사건의 설비가 설비 축에 실린다(`equipmentId`)')
 })
 
 test('없는 값은 빈 문자열이 아니라 undefined — 결측과 빈값을 섞지 않는다', () => {
@@ -81,6 +123,10 @@ test('설비·무버 축 — 운영 델타의 moverId 를 뽑는다', () => {
   assert.equal(equipmentIdOf(ev), 'fork-3')
   const k = twinEventKeys(ev)
   assert.equal(k.moverId, 'fork-3')
+  /* 개명 세대가 섞인다 — 읽는 쪽이 흡수한다(`moverId` 옛 채널 · `resourceRef` 작업 · `equipmentId` 에너지). */
+  assert.equal(equipmentIdOf({ data: { resourceRef: 'cutter-1' } }), 'cutter-1')
+  assert.equal(equipmentIdOf({ data: { equipmentId: 'pv-roof' } }), 'pv-roof')
+  assert.equal(equipmentIdOf({ data: { moverId: 'fork-1', resourceRef: 'x' } }), 'fork-1', '앞의 이름이 이긴다')
   /* 운영 델타는 readPoint/bizLocation 이 없다 — 평범한 location 을 위치로 받는다.
    * 빠뜨리면 "이 설비가 어디서 무엇을 했나" 가 위치 축에서 통째로 사라진다. */
   assert.equal(k.locationId, 'rack-1')

package/test/withheld-door.test.ts

@@ -0,0 +1,95 @@
+/*
+ * ★ **원본에 있는데 세우지 않은 것** — 그 사실이 스쳐 지나가지 않게.
+ *
+ * ── 무엇이 조용했나 (2026-08-24) ────────────────────────────────────────────
+ * 커넥터가 원본의 사실 일부를 **일부러 받지 않는 일이 정상이다**(입자가 안 맞는다 · 받으면 상태가
+ * 거짓이 된다 · 커널 어휘로 옮길 수 없다). 그때 경고를 내는데, 그 경고의 유일한 소비처가 **프로비저닝
+ * 마법사**였다 — 트윈을 만드는 동안만 뜨는 화면이다.
+ *
+ * 그래서 「지시되지 않은 생산계획 8건을 세우지 않았다」가 **한 번 스쳐 지나갈 뿐**이었고, 나중에
+ * 사용자가 「원본보다 계획이 적다」를 물으면 답이 어디에도 없었다.
+ *
+ * 그 사실은 한 번의 사건이 아니라 **상태의 성질**이다 — 세우지 않은 것은 **지금도** 트윈에 없다.
+ *
+ * ── `unhandled` 의 형제다 ──────────────────────────────────────────────────
+ *   `unhandled`   리듀서가 **받았는데** 담을 자리를 몰랐다
+ *   여기          커넥터가 **보지만 일부러 보내지 않았다** — 이유와 함께
+ *
+ * ── 그래서 문에서 조회까지 걷는다 ───────────────────────────────────────────
+ * 오늘 「계약에 자리는 있고 그 자리로 가는 길이 없다」를 여섯 번 만났다. 장부만 검사하면 어댑터가
+ * 부를 문이 없는 것을 못 잡는다 — 그것이 그 결함들이 살아남은 방식이다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+
+const req = createRequire(import.meta.url)
+const { newIngestLedger, recordWithheld, ingestHealth } = req('../dist-server/engine/ingest-health.js')
+
+const REASON = '아직 지시되지 않은 생산계획을 세우지 않았다 — 커널의 created 는 「할당해도 되는 오더」를 뜻한다'
+
+test('★ 세우지 않은 것이 조회에 나온다 — 유입이 한 건도 없어도', () => {
+  /*
+   * 이 갈래가 중요하다: 원본이 말하는데 **전부** 안 받는 경우가 있고, 그때 유입은 0 이다.
+   * 유입 있는 갈래에서만 내면 바로 그 상황에서 조용해진다.
+   */
+  const l = newIngestLedger()
+  recordWithheld(l, REASON, 8, Date.parse('2026-08-24T11:19:16.000Z'))
+  const view: any = ingestHealth(l)
+  assert.equal(view.withheld?.length, 1)
+  assert.equal(view.withheld[0].reason, REASON)
+  assert.equal(view.withheld[0].count, 8)
+  assert.equal(view.withheld[0].lastAt, '2026-08-24T11:19:16.000Z', '언제 그랬는지 함께 — 「지금도 그런가」를 사람이 판정한다')
+})
+
+test('주기마다 불러도 부풀지 않는다 — 누적이 아니라 **지금 세우지 않은 수**다', () => {
+  /* 8건이 매 주기 다시 보고되면 8 이어야 한다. 더해서 800 이 되면 거짓이다. */
+  const l = newIngestLedger()
+  for (let i = 0; i < 100; i++) recordWithheld(l, REASON, 8, 1000 + i)
+  assert.equal(l.withheld.length, 1)
+  assert.equal(l.withheld[0].count, 8)
+  assert.equal(l.withheld[0].lastAtMs, 1099, '마지막 시각으로 움직인다')
+})
+
+test('수가 달라지면 마지막 수로 덮는다 — 낡은 수가 남지 않게', () => {
+  const l = newIngestLedger()
+  recordWithheld(l, REASON, 8, 1000)
+  recordWithheld(l, REASON, 3, 2000)
+  assert.equal(l.withheld[0].count, 3)
+})
+
+test('이유가 여럿이면 각자 한 줄 — 다른 사실을 한 줄로 뭉치지 않는다', () => {
+  const l = newIngestLedger()
+  recordWithheld(l, REASON, 8, 1000)
+  recordWithheld(l, '사람이 올린 문서라 자재와 이어지지 않는다', 46, 1000)
+  assert.equal((ingestHealth(l) as any).withheld.length, 2)
+})
+
+test('말하지 않은 것은 만들지 않는다 — 빈 목록을 「세우지 않은 것이 있다」로 읽히게 하지 않는다', () => {
+  const l = newIngestLedger()
+  assert.equal((ingestHealth(l) as any).withheld, undefined, '키 자체가 없다')
+  recordWithheld(l, REASON, 0, 1000)
+  assert.equal(l.withheld, undefined, '0 은 적지 않는다')
+  recordWithheld(l, '', 5, 1000)
+  assert.equal(l.withheld, undefined, '이유 없는 것은 적지 않는다')
+})
+
+test('★ 어댑터가 부를 문이 있고, 그 문이 장부에 닿는다', () => {
+  /*
+   * 이 단정이 오늘 여섯 번 만난 부류를 막는다. 장부만 검사하면 **어댑터가 부를 통로가 없는 것**을
+   * 못 잡고, 그러면 보내는 쪽에는 「알렸다」로 보이고 화면에는 「없다」로 보인다.
+   */
+  const adapter = readFileSync(new URL('../server/service/reference/reference-adapter.ts', import.meta.url), 'utf-8')
+  assert.match(adapter, /onWithheld\?: \(info: \{ reason: string; count: number \}\) => void/, '계약에 통로가 있다')
+
+  const live = readFileSync(new URL('../server/service/reference/reference-live.ts', import.meta.url), 'utf-8')
+  const wired = live.slice(live.indexOf('onWithheld'), live.indexOf('onWithheld') + 260)
+  assert.match(wired, /recordIngestWithheld/, '그 통로가 장부로 이어진다')
+
+  const engine = readFileSync(new URL('../server/engine/twin-engine.ts', import.meta.url), 'utf-8')
+  const fn = engine.slice(engine.indexOf('static recordIngestWithheld'))
+  assert.match(fn.slice(0, 700), /recordWithheld\(ledger/, '엔진이 장부에 적는다')
+  /* 실패로 적지 않는다 — 어댑터의 옳은 판단이고, 오류로 적으면 화면이 원본을 의심한다. */
+  assert.doesNotMatch(fn.slice(0, 700), /lastError|status:/, '오류로 적지 않는다')
+})