@things-factory/headless-twin 10.0.15 → 10.0.18

package/test/runtime-key.test.ts

@@ -5,7 +5,7 @@
  * 이름을 그대로 id 로 쓰므로(`sap-ewm-1710`) 두 테넌트가 같은 벤더 시스템에 연결하면 같은 id 가 된다 —
  * 그때 남의 커널에 이벤트가 적용되거나, 웜스타트 씨앗이 남의 스냅샷이 됐다.
  *
- * 이 테스트가 지키는 것은 **키가 모호해지지 않는 것** 하나다. 모호한 키는 조용히 틀린다.
+ * 이 테스트가 지키는 것은 **키가 모호해지지 않는 것** 하나다. 모호한 키는 오류 없이 틀린 값을 낸다.
  */
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
@@ -39,8 +39,8 @@ test('인스턴스 id 안의 구분자를 보존한다 — 첫 구분자에서
   assert.equal(instanceId, weird)
 })
 
-test('도메인 id 에 구분자가 있으면 오류를 낸다 — 조용히 모호한 키를 만들지 않는다', () => {
-  /* 조용히 만들면 그게 곧 이 결함의 재발이다(어느 테넌트인지 알 수 없는 키). */
+test('도메인 id 에 구분자가 있으면 오류를 낸다 — 알리지 않고 모호한 키를 만들지 않는다', () => {
+  /* 알리지 않고 만들면 그게 곧 이 결함의 재발이다(어느 테넌트인지 알 수 없는 키). */
   assert.throws(() => runtimeKey(`a${RUNTIME_KEY_SEP}b`, 'x'), /ambiguous/)
 })
 

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

@@ -7,7 +7,8 @@
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { StateProjector, objectEvent, BIZSTEP, DISP, OP_EVENT } from '@operato/twin-kernel'
+import { StateProjector } from '@operato/twin-kernel'
+import { objectEvent, BIZSTEP, DISP, OP_EVENT } from '@operato/ops-contract'
 import { masterToTwin } from '../server/service/reference/reference-master.ts'
 import { buildEntityDeltas } from '../shared/entity-delta.ts'
 

package/test/snapshot-freshness.test.ts

@@ -1,8 +1,8 @@
 /*
  * 영속 스냅샷이 **사실을 이기지 않는다** — 쓸 수 있는 조건을 못 박는다.
  *
- * 멈춘 트윈을 조회할 때마다 저널을 전량 접고 있었다(23,731건짜리 트윈에서 4.6초). 스냅샷은 같은
- * 폴드의 결과이므로 그 뒤로 아무 일도 없었다면 다시 접어 봐야 같은 값이다 — 그래서 쓴다.
+ * 멈춘 트윈을 조회할 때마다 저널을 전량 계산하고 있었다(23,731건짜리 트윈에서 4.6초). 스냅샷은 같은
+ * 폴드의 결과이므로 그 뒤로 아무 일도 없었다면 다시 계산해 봐야 같은 값이다 — 그래서 쓴다.
  *
  * 위험은 하나다: **낡은 스냅샷을 "지금" 이라고 내는 것.** 그래서 쓰는 조건을 좁게 잡았고, 그 조건을
  * 여기서 고정한다. 엔진 본체는 DB 를 물고 있어 부를 수 없으므로 판정식만 떼어 시험한다 —
@@ -22,7 +22,7 @@ const usable = (
 const TIP = { revision: 23731, structureRev: 2 }
 const FRESH = { revision: 23731, structureRev: 2, state: { locations: [] } }
 
-test('끝에 있고 구조도 같으면 쓴다 — 다시 접어도 같은 값이다', () => {
+test('끝에 있고 구조도 같으면 쓴다 — 다시 계산해도 같은 값이다', () => {
   assert.equal(usable(FRESH, TIP, true), true)
 })
 
@@ -46,7 +46,7 @@ test('구조가 양쪽 다 없으면 그것은 같은 것이다 — 없는 것
   assert.equal(usable({ revision: 5, state: {} }, { revision: 5, structureRev: null }, true), true)
 })
 
-test('시간여행에는 쓰지 않는다 — 그 시점까지 접어야 한다', () => {
+test('시간여행에는 쓰지 않는다 — 그 시점까지 계산해야 한다', () => {
   assert.equal(usable(FRESH, TIP, false), false)
 })
 

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

@@ -2,7 +2,7 @@
  * **허락과 일어남 사이를 같은 행에 닫는다** — ADR-0029 §1 결정 C (2026-08-19).
  *
  * ── 무엇이 열려 있었나 ──────────────────────────────────────────────────────
- * 명령이 원본으로 가면 감사는 「허락했다」까지만 증명한다: 어댑터가 조용히 실패하면 원장에는 승인만 남는다.
+ * 명령이 원본으로 가면 감사는 「허락했다」까지만 증명한다: 어댑터가 오류 없이 실패하면 원장에는 승인만 남는다.
  * 그리고 구동 문(`controlTwinSource`)은 감사를 **아예 남기지 않았다** — 자극을 바꾸고 배속을 올리는 것은
  * 그 트윈의 사실을 바꾸는 행위인데, 나중에 「무엇이 이 공장을 흔들었나」에 답할 수 없었다.
  *

package/test/space-integrity.test.ts

@@ -217,7 +217,7 @@ test('정지한 트윈은 세지 않는다 — 확인하지 않은 것을 정합
   assert.equal(f.find(x => x.code === 'twin-unhandled-vocabulary'), undefined)
 })
 
-test('빈 배열은 결함이 아니다 — 받은 것이 없으면 조용하다', () => {
+test('빈 배열은 결함이 아니다 — 받은 것이 없으면 들어온 것이 없다', () => {
   const f = checkSpaceIntegrity({ ...SOUND, instances: [{ ...SOUND.instances[0], unhandled: [] }] })
   assert.equal(f.find(x => x.code === 'twin-unhandled-vocabulary'), undefined)
 })

package/test/space-representation.test.ts

@@ -0,0 +1,66 @@
+/*
+ * ★ 표현을 묶고 가른다 — 목록에 나올 것과 다른 표현에서 열리는 것.
+ *
+ * ── 왜 (2026-08-27 · 사용자 지시, UX 레인 요청) ─────────────────────────────
+ * 「각 표현이 많아지게 되면 관리가 어려우니, 그루핑과 정렬 기능도 필요하다.」
+ * 「표현 인덱스에 포함될 표현과 팝업 같은 파생 표현이 구분될 수 있어야 한다.」
+ *
+ * 칸 둘을 더한다.
+ *
+ *   group   자유 문자열. 묶는 축이 현장마다 다르다(건물별·용도별·층별)
+ *   role    index(기본) · derived. 닫힌 목록이다
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { REPRESENTATION_ROLES } from '../server/service/twin-space/representation-role.js'
+
+const dir = (...p: string[]) => join(import.meta.dirname, '..', 'server', 'service', 'twin-space', ...p)
+const entity = readFileSync(dir('twin-space-representation.ts'), 'utf8')
+const resolver = readFileSync(dir('twin-space-resolver.ts'), 'utf8')
+
+test('★ 묶는 이름은 자유 문자열이다 — 묶는 축이 현장마다 다르다', () => {
+  assert.match(entity, /group\?: string/, 'group 칸이 있어야 한다')
+  /* 고정 목록으로 두면 현장마다 맞지 않는다 — 값을 검사하지 않는다. */
+  assert.doesNotMatch(resolver, /GROUPS as readonly|REPRESENTATION_GROUPS/, '묶는 이름을 목록으로 닫지 않는다')
+})
+
+test('★ 그룹 자체의 순서는 칸으로 두지 않는다 — 그 그룹의 최소 seq 가 그 순서다', () => {
+  /* 칸을 두면 그룹 이름을 바꿀 때 두 곳을 맞춰야 하고, 어긋나면 목록 순서가 오류 없이 달라진다. */
+  assert.doesNotMatch(entity, /groupSeq|groupOrder/, '그룹 순서 칸을 만들지 않는다')
+})
+
+test('★ role 은 닫힌 목록이고, 모르는 값은 저장하지 않는다', () => {
+  assert.deepEqual([...REPRESENTATION_ROLES], ['index', 'derived'])
+  /*
+   * 모르는 값을 그냥 저장하면 화면이 그것을 어느 쪽으로도 그리지 못하고, 그 표현이 목록에서 알리지 않고
+   * 사라진다. 저장하는 자리에서 거절한다.
+   */
+  assert.match(resolver, /REPRESENTATION_ROLES as readonly string\[\]\)\.includes\(role\)/, '닫힌 목록으로 검사한다')
+  assert.match(resolver, /unknown representation role/, '거절 사유를 말한다')
+})
+
+test('★ 비어 있으면 index 다 — 흔한 쪽을 기본으로 둔다', () => {
+  assert.match(entity, /role\?: string/, 'role 은 선택 칸이다')
+  assert.match(entity, /default when absent/, '비어 있을 때의 뜻이 설명에 있어야 한다')
+  /* 공백만 있는 값은 「없음」과 같다 — 그것을 값으로 저장하면 검사를 지나며 뜻이 없는 값이 남는다. */
+  assert.match(resolver, /String\(rep\.role\)\.trim\(\) === ''/, '공백만 있는 값은 비운다')
+  assert.match(resolver, /String\(rep\.group\)\.trim\(\) === ''/, '묶는 이름도 같다')
+})
+
+test('★ isPrimary 에 얹지 않는다 — 다른 질문에 답하는 칸이다', () => {
+  /*
+   * `isPrimary` 는 「현장 현황에 나올 하나」를 정한다. `role` 은 「목록에 나오나」를 정한다. 한 칸이
+   * 두 질문에 답하면 한쪽을 고칠 때 다른 쪽이 오류 없이 바뀐다.
+   */
+  assert.match(entity, /isPrimary\?: boolean/, 'isPrimary 는 그대로 있어야 한다')
+  assert.match(entity, /Kept separate from isPrimary/, '왜 따로 두는지 설명에 있어야 한다')
+})
+
+test('★ 조회가 두 값을 실어 보낸다 — 화면이 묶을 수 있어야 한다', () => {
+  assert.match(resolver, /group: rep\.group, role: rep\.role/, '표현 목록에 두 값을 싣는다')
+  assert.match(resolver, /order: \{ group: 'ASC', seq: 'ASC' \}/, '묶은 이름 다음에 순서로 정렬한다')
+  /* 빈 값이 앞에 오는지 뒤에 오는지는 드라이버마다 다르다 — 그 순서에 기대지 않는다. */
+  assert.match(resolver, /드라이버마다\s*\n?\s*\*?\s*다르므로/, '그 순서에 기대지 않는다는 것을 적어 둔다')
+})

package/test/space-scope-includes-stopped.test.ts

@@ -0,0 +1,55 @@
+/*
+ * ★ 현장으로 물으면 멈춘 트윈의 기록도 나온다 — 저널은 기록이고, 지금 도는지는 다른 축이다.
+ *
+ * ── 무엇이 났나 (2026-08-28 실측) ───────────────────────────────────────────
+ * 대상 해소에 `running` 조건이 있었다. 그래서 현장으로 물으면 멈춘 트윈이 대상에서 빠지고, 화면은
+ * 「기록이 없습니다」라고 말했다 — 저널에는 있는데.
+ *
+ *   twinEventList(instanceId: "ems-plant-1")      1,792건
+ *   twinEventList(spaceId:    "ems-plant-1-site")     0건   ← 같은 트윈 · 같은 도메인
+ *
+ * 규모로 보면 예외가 아니라 기본값이었다: 등록된 트윈 30개 중 도는 것 2개, 멈춘 것 28개.
+ *
+ * ── 왜 지웠나 ──────────────────────────────────────────────────────────────
+ * 옛 주석이 대는 이유(「벤치 사본은 사용자가 보는 현장이 아니다」)는 벤치 제외만 설명한다. `running` 에는
+ * 근거가 적혀 있지 않았다. 그리고 바로 다음 줄이 반대 원칙을 적어 두었다 — 「정지·비등록이어도 저널은
+ * 남아 있을 수 있다」. 그 원칙이 현장 경로에만 적용되지 않고 있었다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const KPI = join(import.meta.dirname, '..', 'server', 'engine', 'kpi-query.ts')
+const src = readFileSync(KPI, 'utf8')
+
+/** 대상을 고르는 그 한 줄만 떼어 본다. */
+const targetLine = (() => {
+  const from = src.indexOf('async function resolveTargets')
+  const body = src.slice(from, from + 1200)
+  const m = /: list\.filter\(\(x: any\) => [^\n]+\)/.exec(body)
+  return m?.[0] ?? ''
+})()
+
+test('★ 현장 경로가 「지금 도는가」로 걸러내지 않는다', () => {
+  assert.ok(targetLine, '대상을 고르는 줄을 찾아야 한다')
+  assert.doesNotMatch(targetLine, /running/, '멈춘 트윈을 현장에서 빼면 화면이 거짓 「없다」를 낸다')
+})
+
+test('벤치 사본은 계속 뺀다 — 그 제외에는 근거가 있다', () => {
+  /* 부하 시험용 사본은 사용자가 보는 현장이 아니다. 이 제외는 지우지 않는다. */
+  assert.match(targetLine, /purpose !== 'bench'/)
+})
+
+test('현장과 트윈 두 경로가 같은 원칙을 쓴다 — 저널은 기록이다', () => {
+  /* 트윈을 지정한 경로는 처음부터 「정지·비등록이어도 저널은 남아 있을 수 있다」였다. */
+  assert.match(src, /정지·비등록\)? ?지정된 트윈은 그대로 조회한다|정지·비등록/)
+  /* 왜 지웠는지가 코드에 남아 있어야 한다 — 다음 사람이 성능을 이유로 되넣지 않게. */
+  assert.match(src, /「지금 도는가」로 걸러내지 않는다/)
+  assert.match(src, /1,792건/, '무엇을 재서 알았는지 적혀 있어야 한다')
+})
+
+test('★ 「지금 도는 것만」이 필요하면 이름 있는 축으로 받는다 — 여기 숨기지 않는다', () => {
+  /* 한 칸에 두 물음을 담으면 어느 화면이 무엇을 보는지 아무도 모른다. */
+  assert.match(src, /\*\*이름 있는 축\*\*으로 받는다/)
+})

package/test/spec-coverage.test.ts

@@ -32,7 +32,7 @@ test('전부 선언되면 절대 예측 시도 가능 — 단 정확도는 별
   assert.equal(r!.varyingDurations, 2)
 })
 
-test('섞이면 partial — 한쪽만 접지된 사실을 감추지 않는다', () => {
+test('섞이면 partial — 한쪽만 계산하지된 사실을 감추지 않는다', () => {
   const r = classifySpecCoverage({
     operations: [
       { kind: 'cut', duration: 'declared' },

package/test/standard-coverage.test.ts

@@ -76,7 +76,7 @@ test('개폐·발전·저장이 세 층 모두 올라갔다 — 값이 먼저,
   assert.equal(iec.totals.behavior, 5, '다섯 논리 노드가 모두 실제로 돈다')
 })
 
-test('커널 축이 사라지면 구조가 없는 것으로 떨어진다 — 오타·개명이 조용히 통과하지 않게', () => {
+test('커널 축이 사라지면 구조가 없는 것으로 떨어진다 — 오타·개명이 알리지 않고 통과하지 않게', () => {
   const iec = iec61850Coverage(['equipment']) // demandWindows 축이 없는 세상
   const mmxu = iec.concepts.find(c => c.std === 'MMXU')!
   assert.equal(mmxu.structure, 'none')
@@ -106,21 +106,17 @@ test('계측은 EPCIS 센서 필드로 오지 않는다 — 그 사실을 표가
   assert.ok(sensor.note, '에너지가 다른 층으로 들어온다는 사실을 근거로 적는다')
 })
 
-test('★ 「어디서 보이나」가 화면 등급과 어긋나지 않는다 — 표가 없는 화면으로 사람을 보내지 않게', () => {
+test('★ 자기 축이 없는 개념은 **어디에 속하는지** 말한다 — 「어디에도 없다」로 읽히지 않게', () => {
   /*
-   * ── 무엇이 틀려 있었나 (2026-08-24 실측) ──────────────────────────────────
-   * `shownOn` 은 「그 사실이 어느 축에 **담겨 있나**」가 아니라 「**어디서 보이나**」다. 화면이 그것을
-   * 「해당 축 항목에 표시됩니다」로 읽어 내므로, `surface: 'none'` 인 줄에 갈 곳이 적혀 있으면 표가
-   * **거짓을 말한다** — 사람을 그 개념이 보이지 않는 화면으로 보낸다.
+   * ── 사용자 지적 (2026-08-24) ──────────────────────────────────────────────
+   * 화면이 그런 줄을 「개념 축이 없습니다」로만 냈다. 자재 로트·자원 속성·로케이션 관측 기록이 그렇게
+   * 보였는데, 셋 다 **어디엔가 속해 있다** — 로트는 물품 목록이고, 속성은 설비·사람·자산 안에 붙고,
+   * 관측은 로케이션에 붙는다. 「축이 없다」는 사실이지만 사용자에게는 **없는 것**으로 읽힌다.
    *
-   * 같은 날 넷이 그랬다. 셋은 새로 넣으면서(`TestResult`·`OperationsEvent`), 하나는 오래(`errorDeclaration`
-   * — 그 줄의 `note` 는 「화면에 보이는 곳은 아직 없습니다」라고 말하는데 배지는 반대를 말했다).
+   * 그래서 `shownOn` 의 뜻을 고쳤다 — 「어디서 보이나」가 아니라 **「어디에 속하나」**다. 화면에
+   * 그려지는지는 `surface` 가 따로 답하고, 둘은 다른 물음이다.
    *
-   * 반대 방향도 본다: 화면에 보이는데 축도 갈 곳도 주석도 없으면 그 줄은 **「진짜 빈칸」으로 읽힌다**
-   * (`shownOn` 주석이 정한 규칙이다). `MaterialSublot` 이 그랬다 — 물품 이름으로 보이는데 갈 곳이 비어
-   * 있었다.
-   *
-   * 사람이 눈으로 보고 잡았다. 그래서 기계가 잡게 한다.
+   * (그리고 화면의 「해당 축 항목에 표시됩니다」 문장은 걷었다 — 칩이 이미 갈 곳을 보인다.)
    */
   const AXES = [
     'items', 'locations', 'equipment', 'persons', 'assets', 'tasks', 'orders', 'operations', 'recipes',
@@ -133,18 +129,20 @@ test('★ 「어디서 보이나」가 화면 등급과 어긋나지 않는다
     ['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}`)
+      const lives = c.structure !== 'none' || c.behavior !== 'none' || c.surface !== 'none'
+      if (lives && !c.axis && !c.shownOn?.length) mute.push(`${name}/${c.std}`)
     }
   }
-  assert.deepEqual(lies, [], `화면이 없는데 갈 곳을 적은 줄 — 없는 화면으로 사람을 보낸다:\n${lies.join('\n')}`)
-  assert.deepEqual(mute, [], `화면에 보이는데 갈 곳도 주석도 없는 줄 — 「진짜 빈칸」으로 읽힌다:\n${mute.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})`)
+  /* 빈 비교로 통과하지 않게 — 실제로 그런 줄이 여럿 있다(자재 로트·서브로트·속성·관측·시험 결과). */
+  const attached = tables.flatMap(([, t]) => t.concepts).filter(c => !c.axis && c.shownOn?.length)
+  assert.ok(attached.length >= 4, `속해 있다고 말하는 줄이 실제로 있어야 한다 (실제 ${attached.length})`)
 })

package/test/status-tally.test.ts

@@ -33,7 +33,7 @@ test('낱말은 커널의 것 그대로 — 묶거나 고쳐 부르지 않는다
   assert.deepEqual(
     r.statusCounts?.map(s => s.status).sort(),
     ['assigned', 'created'],
-    '「대기」처럼 앱의 낱말로 바꾸면 커널이 늘린 낱말을 화면이 조용히 잘못 부른다'
+    '「대기」처럼 앱의 낱말로 바꾸면 커널이 늘린 낱말을 화면이 알리지 않고 잘못 부른다'
   )
 })
 

package/test/structure-revision-db.test.ts

@@ -1,7 +1,7 @@
 /*
  * ★ 구조 리비전 — **실 DB로 경계를 넘어 본다.**
  *
- * 커널의 마디 접기(`replaySegments`)는 그쪽 테스트가 지킨다. 여기서 지키는 것은 **호스트 배선**이다:
+ * 커널의 마디 계산(`replaySegments`)는 그쪽 테스트가 지킨다. 여기서 지키는 것은 **호스트 배선**이다:
  * 리비전을 언제 새로 만드는가 · 이벤트에 번호를 찍는가 · 재생이 그 번호로 마디를 나누는가 ·
  * 컬럼이 생기기 전 행(번호 없음)을 어디에 붙이는가.
  *
@@ -152,9 +152,9 @@ test('★ 재생이 경계를 넘는다 — 앞선 사실은 남고, 새 구조
   assert.equal(state.locations.filter((n: any) => n.type === 'storage').length, 6, '늘린 자리가 안 보이면 늘린 의미가 없다')
 })
 
-test('구조 번호가 없는 옛 행은 **가장 오래된 구조**로 접는다 — 새 공장에 대고 접지 않는다', async () => {
+test('구조 번호가 없는 옛 행은 **가장 오래된 구조**로 처리한다 — 새 공장에 대고 계산하지 않는다', async () => {
   /*
-   * 컬럼이 생기기 전에 쓰인 행은 `structureRev` 가 비어 있다. 그것을 현재 보드로 접으면 그때 없던
+   * 컬럼이 생기기 전에 쓰인 행은 `structureRev` 가 비어 있다. 그것을 현재 보드로 계산하면 그때 없던
    * 설비에서 일이 있었던 것처럼 보인다 — 이 규칙이 그 행들을 제자리에 붙인다.
    */
   await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
@@ -165,11 +165,11 @@ test('구조 번호가 없는 옛 행은 **가장 오래된 구조**로 접는
 
   await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3), 'reset')
   const state = await TwinEngine.recover(domainId, INSTANCE)
-  assert.ok(state.items.length > 0, '번호 없는 옛 행도 읽혀야 한다 — 조용히 버리지 않는다')
+  assert.ok(state.items.length > 0, '번호 없는 옛 행도 읽혀야 한다 — 알리지 않고 버리지 않는다')
   assert.equal(state.equipment.length, 3, '마지막 구조가 자원의 진실이다')
 })
 
-test('리비전이 하나뿐이면 예전과 똑같이 접는다 — 구조 전환이 결과를 바꾸지 않는다', async () => {
+test('리비전이 하나뿐이면 예전과 똑같이 계산한다 — 구조 전환이 결과를 바꾸지 않는다', async () => {
   await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(3, 2), 'reset')
   const events = realEvents(boardWith(3, 2), 300)
   await TwinEngine.persistBatch(domainId, INSTANCE, events, 0)
@@ -243,7 +243,7 @@ test('번호 없는 옛 행도 가장 오래된 리비전의 몫으로 센다
   await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3), 'reset')
 
   const history = await TwinEngine.structureHistory(domainId, INSTANCE)
-  assert.equal(history[0].events, legacy.length, '재생이 rev 1 로 접는 행들을 세는 쪽만 빠뜨리면 두 화면이 다른 말을 한다')
+  assert.equal(history[0].events, legacy.length, '재생이 rev 1 로 계산하는 행들을 세는 쪽만 빠뜨리면 두 화면이 다른 말을 한다')
   assert.equal(history[1].events, 0)
 })
 
@@ -270,7 +270,7 @@ test('지문 표기가 낡았을 뿐이면 리비전을 만들지 않는다 —
  *
  * 예전에는 sim-world 선언이 저널을 지우고 fresh 로 띄웠다. 실제로 없던 것은 **번호 이어 세기
  * 하나**였다: 상태 복원은 이미 저널 재생으로 하고 있었고, 막힌 것은 커널이 0부터 다시 세어 기존
- * 행과 겹치는 문제였다. 그 겹침은 오류를 내지 않고 조용히 재생 순서를 뒤섞는다.
+ * 행과 겹치는 문제였다. 그 겹침은 오류를 내지 않고 알리지 않고 재생 순서를 뒤섞는다.
  */
 test('sim-world 로 다시 띄워도 저널이 살아남는다 — 선언이 지키는 약속', async () => {
   await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')

package/test/subject-fast-path.test.ts

@@ -0,0 +1,148 @@
+/*
+ * ★ 화면이 이미 부르는 문에서 파생 테이블을 쓴다 — 그리고 못 답할 때는 물러난다.
+ *
+ * ── 무엇을 놓쳤던가 (2026-08-28) ────────────────────────────────────────────
+ * 대상별 사건 목록을 만들고 8,382,017줄을 채웠는데, 360 화면은 예전부터 `twinEventList` 를 부르고
+ * 있었다. 그래서 조회는 그대로 64초였다. **자리는 있고 길이 없었다** — 가장 자주 나는 결함이다.
+ *
+ * 이 시험이 지키는 것은 그 길이다.
+ *   ① 어떤 물음이 파생 테이블로 가는가 — 좁게, 그리고 그 판단이 순수한가
+ *   ② 못 답하는 물음에 억지로 답하지 않는가
+ *   ③ 답할 수 없는 구간을 「사건이 없다」로 그리게 만들지 않는가
+ *   ④ 화면이 부르는 자리에 실제로 붙어 있는가
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { readModelShape, AXIS_KIND } from '../server/service/twin-subject/subject-query-shape.js'
+
+const dir = (...p: string[]) => join(import.meta.dirname, '..', 'server', ...p)
+const fastPath = readFileSync(dir('service', 'twin-subject', 'twin-subject-fast-path.ts'), 'utf8')
+const journal = readFileSync(dir('service', 'twin-journal', 'twin-journal-query.ts'), 'utf8')
+
+/** 360 화면이 실제로 보내는 모양(§`loadTwinEventPage`) — 축 하나를 부분일치로, 시각 내림차순. */
+const panelParams = (axis: string, value: string, extra: any[] = []) => ({
+  filters: [{ name: axis, operator: 'search', value }, ...extra],
+  sortings: [{ name: 'eventTime', desc: true }]
+})
+
+const DESC = [{ name: 'eventTime', desc: true }]
+
+test('★ 360 화면이 보내는 네 축이 모두 파생 테이블로 간다', () => {
+  /* 이것이 이 작업의 목적이다. 하나라도 빠지면 그 축의 이력은 여전히 64초다. */
+  const expected: Record<string, string> = { epc: 'item', orderId: 'order', locationId: 'location', moverId: 'equipment' }
+  for (const [axis, kind] of Object.entries(expected)) {
+    const shape = readModelShape(panelParams(axis, 'V-1'), DESC)
+    assert.ok(shape, `${axis} 축이 파생 테이블로 가야 한다`)
+    assert.equal(shape!.kind, kind)
+    assert.equal(shape!.value, 'V-1')
+  }
+  assert.deepEqual(Object.keys(AXIS_KIND).sort(), ['epc', 'locationId', 'moverId', 'orderId'])
+})
+
+test('시각 상한(시간여행)이 함께 와도 간다 — 화면이 과거를 볼 때 보내는 모양', () => {
+  const shape = readModelShape(panelParams('epc', 'ITEM-1', [{ name: 'eventTime', operator: 'lte', value: '2026-08-01T00:00:00.000Z' }]), DESC)
+  assert.ok(shape)
+  assert.equal(shape!.untilTime?.toISOString(), '2026-08-01T00:00:00.000Z')
+})
+
+test('구간으로 물으면 두 끝을 모두 읽는다', () => {
+  const shape = readModelShape(
+    panelParams('locationId', 'BUFFER-CK1', [
+      { name: 'eventTime', operator: 'between', value: ['2026-08-01T00:00:00.000Z', '2026-08-02T00:00:00.000Z'] }
+    ]),
+    DESC
+  )
+  assert.ok(shape)
+  assert.equal(shape!.fromTime?.toISOString(), '2026-08-01T00:00:00.000Z')
+  assert.equal(shape!.untilTime?.toISOString(), '2026-08-02T00:00:00.000Z')
+})
+
+test('★ 맞지 않는 물음은 답하지 않고 저널로 보낸다 — 억지로 답하면 목록이 알리지 않고 달라진다', () => {
+  const cases: [string, any, any[]][] = [
+    ['자유 검색어', { ...panelParams('epc', 'ITEM-1'), search: '냉동' }, DESC],
+    ['종류 필터', panelParams('epc', 'ITEM-1', [{ name: 'eventType', operator: 'in', value: ['task.status'] }]), DESC],
+    ['상관 식별자', panelParams('epc', 'ITEM-1', [{ name: 'correlationId', operator: 'eq', value: 'C1' }]), DESC],
+    ['축 둘', { filters: [{ name: 'epc', operator: 'eq', value: 'A' }, { name: 'orderId', operator: 'eq', value: 'B' }], sortings: DESC }, DESC],
+    ['축 없음', { filters: [], sortings: DESC }, DESC],
+    ['여러 값(in)', panelParams('epc', 'A').filters && { filters: [{ name: 'epc', operator: 'in', value: ['A', 'B'] }], sortings: DESC }, DESC],
+    ['리비전 정렬', panelParams('epc', 'ITEM-1'), [{ name: 'revision', desc: true }]],
+    ['오름차순 정렬', panelParams('epc', 'ITEM-1'), [{ name: 'eventTime', desc: false }]],
+    ['정렬 둘', panelParams('epc', 'ITEM-1'), [{ name: 'eventTime', desc: true }, { name: 'revision', desc: true }]],
+    ['시각 하한만', panelParams('epc', 'ITEM-1', [{ name: 'eventTime', operator: 'gte', value: '2026-08-01T00:00:00.000Z' }]), DESC],
+    ['못 읽는 시각', panelParams('epc', 'ITEM-1', [{ name: 'eventTime', operator: 'lte', value: '어제' }]), DESC],
+    ['빈 축 값', panelParams('epc', '   '), DESC]
+  ]
+  for (const [why, params, sortings] of cases) {
+    assert.equal(readModelShape(params, sortings), null, `${why} 는 저널로 가야 한다`)
+  }
+})
+
+test('★ 적지 못한 줄이 있으면 이 경로를 쓰지 않는다 — 그 창에는 구멍이 있다', () => {
+  assert.match(
+    fastPath,
+    /subjectWriteFailures\(domainId, instanceId\) > 0\) return null/,
+    '실패가 세어져 있으면 온전한 쪽(저널)으로 보내야 한다'
+  )
+})
+
+test('★ 원시 값을 직접 날짜로 읽지 않는다 — 시간대가 어긋난다', () => {
+  /*
+   * sqlite 가 주는 값은 시간대가 없는 문자열이고, `new Date()` 로 읽으면 한국 시간으로 해석해 UTC 로
+   * 9시간을 뺀다. 실측: 커서의 시각이 9시간 이르게 나가 이어 읽기가 구간을 건너뛰고 본 줄이 또 나왔다
+   * (120건 중 15건). 그래서 경계는 엔티티로 받고, 커서의 시각은 저널 줄에서 가져온다.
+   */
+  /* 경계는 엔티티로 받는다 — 숫자(리비전)는 원시 값이어도 뜻이 변하지 않으므로 날짜에만 걸린다. */
+  assert.doesNotMatch(fastPath, /getRawOne<\{ at:/, '날짜를 원시 값으로 받던 자리가 남아 있다')
+  assert.match(fastPath, /sub\?\.eventTime instanceof Date/)
+  assert.match(fastPath, /journal\?\.eventTime instanceof Date/)
+  assert.match(fastPath, /row\?\.eventTime instanceof Date/, '커서의 시각은 저널 줄의 날짜여야 한다')
+})
+
+test('★ 담지 못한 구간을 「사건이 없다」로 그리게 만들지 않는다', () => {
+  /* 경계 아래를 물으면 물러난다. */
+  assert.match(fastPath, /cursor\.at\.getTime\(\) <= cov\.from\.getTime\(\)\) return null/)
+  assert.match(fastPath, /shape\.untilTime\.getTime\(\) < cov\.from\.getTime\(\)\) return null/)
+  /*
+   * 이 대상의 줄을 다 냈을 때가 가장 위험한 자리다. 커서를 내지 않으면 화면은 「여기서 끝」으로 읽고,
+   * 경계 아래에 저널만 아는 사건이 있으면 그것이 거짓이 된다.
+   */
+  assert.match(fastPath, /boundaryCursor\(cov\.from\)/, '짧게 끝난 페이지는 경계 아래를 읽을 커서를 내야 한다')
+  assert.match(fastPath, /function boundaryCursor/, '그 커서를 만드는 곳이 있어야 한다')
+  /* 저널의 처음까지 덮을 때만 끝이다. */
+  assert.match(fastPath, /cov\.full\s*\n?\s*\?\s*undefined/, '덮고 있을 때만 커서를 내지 않는다')
+})
+
+test('★ 전체 건수와 「더 있나」를 함께 정직하게 낸다 — 화면은 건수를 모를 때 capped 로 판단한다', () => {
+  /*
+   * 화면의 `hasMore` 는 전체 건수를 모르면 `capped` 를 본다. 그래서 「모른다」면서 `capped` 를 내리면
+   * 목록이 알리지 않고 끝난 것처럼 보인다. 두 칸이 한 판단에서 나와야 한다.
+   */
+  assert.match(fastPath, /const capped = total === undefined/)
+  assert.match(fastPath, /if \(page\.fullyCovered\)/, '덮고 있을 때만 정확한 건수를 낸다')
+})
+
+test('★ 화면이 부르는 자리에 붙어 있다 — 새 문을 열어 두고 기다리지 않는다', () => {
+  /* 이 한 줄이 없으면 테이블은 채워지고도 쓰이지 않는다(2026-08-27 에 실제로 그랬다). */
+  assert.match(journal, /const fast = await readModelPage\(domain\.id, instanceIds\[0\], effective, limit\)/)
+  assert.match(journal, /if \(fast\) return fast/)
+  /* 붙는 자리가 저널 질의를 만들기 **전**이어야 한다 — 뒤에 두면 느린 질의를 이미 치른 뒤다. */
+  assert.ok(
+    journal.indexOf('readModelPage(domain.id') < journal.indexOf('const qb = getQueryBuilderFromListParams'),
+    '저널 질의를 만들기 전에 물어야 한다'
+  )
+  /* 트윈 하나일 때만 — 여러 트윈을 합친 목록은 이 테이블의 물음이 아니다. */
+  assert.match(journal, /if \(instanceIds\.length === 1\) \{\s*\n\s*const fast = await readModelPage/)
+})
+
+test('품목만 식별자를 되돌린다 — 적는 쪽과 같은 함수로', () => {
+  /*
+   * 화면은 짧게 줄인 품목 식별자를 들고 있고(`net/class/product-M1`) 저장된 것은 전체 식별자다.
+   * 되돌림을 두 벌로 적으면 어느 날 서로 다른 답을 내고, 그때 이력이 빈다.
+   */
+  assert.match(fastPath, /if \(kind !== 'item'\) return value/)
+  assert.match(fastPath, /itemResolverFor\(domainId, instanceId, det\.model\)/)
+  assert.match(fastPath, /if \(!itemOf\) return null/, '선언을 모르면 짐작하지 않고 물러난다')
+})