@things-factory/headless-twin 10.0.14 → 10.0.17

package/test/connector-capability-declaration.test.ts

@@ -0,0 +1,88 @@
+/*
+ * ★ 구현했는데 선언하지 않은 능력을 아무도 말해 주지 않았다.
+ *
+ * ── 무엇이 났나 (2026-08-25) ────────────────────────────────────────────────
+ * 능력 판정은 **한 방향만** 본다. 선언했는데 구현이 없는 것은 걸러 내고, 구현했는데 선언이 없는 것은
+ * 들어온 것이 없다. 그래서 태양광 발전소를 붙이던 사람이 이렇게 막혔다.
+ *
+ *   커넥터가 openLiveFeed 를 구현했다 · capabilities: ['live'] 를 잊었다
+ *   → 연결 화면이 「이 원본은 라이브를 못 낸다」로 읽는다
+ *   → 재기동 정책을 정할 수 없어 트윈 생성이 거절된다
+ *   → 화면에 보이는 것은 「재기동 정책이 없습니다」뿐이다
+ *
+ * 원인을 찾는 데 코드를 뒤져야 했다. 지금 저장소에 같은 상태인 커넥터가 일곱이다.
+ *
+ * ── 막지 않고 알린다 ────────────────────────────────────────────────────────
+ * 등록에서 던지면 커넥터 하나 때문에 호스트가 못 뜬다. 만들다 만 커넥터를 들고 있는 사람이 아무것도
+ * 못 하게 된다. 이 어긋남은 고칠 수 있는 것이지 위험한 것이 아니다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+/* `twinWarn` 은 `console.warn` 으로 나간다 — 모듈을 바꿔치지 않고 그 자리에서 받는다. */
+const warnings: string[] = []
+const originalWarn = console.warn
+console.warn = (...args: unknown[]) => {
+  warnings.push(args.join(' '))
+}
+process.on('exit', () => (console.warn = originalWarn))
+
+const { registerAdapterType, capabilitiesOf } = await import('../server/service/reference/reference-adapter.js')
+
+const adapter = (over: Record<string, unknown> = {}) =>
+  ({
+    type: `probe-${Math.round(performance.now() * 1000)}-${warnings.length}`,
+    async fetchMaster() {
+      return {} as any
+    },
+    ...over
+  }) as any
+
+test('★ 라이브를 구현하고 선언하지 않으면 말해 준다 — 이것이 없어서 화면이 다른 말을 했다', () => {
+  const before = warnings.length
+  const a = adapter({ openLiveFeed: () => () => {} })
+  registerAdapterType(a)
+  const said = warnings.slice(before).join('\n')
+  assert.ok(said.includes(a.type), '어느 커넥터인지 말한다')
+  assert.ok(said.includes('live'), '무엇이 빠졌는지 말한다')
+  assert.ok(said.includes('capabilities'), '무엇을 하면 되는지 말한다')
+  /* 그리고 지금 화면이 어떻게 읽는지도 말한다 — 사람이 겪은 증상과 이어져야 원인으로 읽힌다. */
+  assert.ok(/live twin cannot be created/.test(said))
+})
+
+test('★ 조치를 구현하고 선언하지 않아도 말해 준다 — 같은 규율이다', () => {
+  const before = warnings.length
+  const a = adapter({ control: async () => ({ ok: true }) })
+  registerAdapterType(a)
+  assert.ok(warnings.slice(before).join('\n').includes('control'))
+})
+
+test('둘 다 어긋나면 둘 다 말한다 — 하나만 말하면 고친 뒤 또 막힌다', () => {
+  const before = warnings.length
+  const a = adapter({ openLiveFeed: () => () => {}, control: async () => ({ ok: true }) })
+  registerAdapterType(a)
+  const said = warnings.slice(before).join('\n')
+  assert.ok(said.includes('live') && said.includes('control'))
+})
+
+test('선언과 구현이 맞으면 아무 말도 하지 않는다 — 소음이 되면 아무도 읽지 않는다', () => {
+  const before = warnings.length
+  registerAdapterType(adapter({ openLiveFeed: () => () => {}, capabilities: ['live'] }))
+  registerAdapterType(adapter({}))
+  assert.equal(warnings.length, before)
+})
+
+test('선언했는데 구현이 없는 쪽은 판정이 이미 걸러 낸다 — 여기서 두 번 말하지 않는다', () => {
+  const before = warnings.length
+  const a = adapter({ capabilities: ['live'] })
+  registerAdapterType(a)
+  assert.equal(warnings.length, before, '등록은 들어온 것이 없다')
+  assert.deepEqual(capabilitiesOf(a), [], '능력 판정이 구현 없는 선언을 걸러 낸다')
+})
+
+test('★ 등록을 막지 않는다 — 커넥터 하나 때문에 호스트가 못 뜨면 안 된다', () => {
+  const a = adapter({ openLiveFeed: () => () => {} })
+  assert.doesNotThrow(() => registerAdapterType(a))
+  /* 등록은 되었고, 다만 그 능력은 선언되지 않았으므로 판정에서 빠진다 — 그 사실이 경고와 짝이다. */
+  assert.deepEqual(capabilitiesOf(a), [])
+})

package/test/control-capability.test.ts

@@ -12,7 +12,7 @@
  * 이 시험이 지키는 것:
  *  ① 선언과 구현이 **함께** 있어야 능력이다 — 선언만 있으면 화면이 거짓말을 하고, 구현만 있으면 닫아 둔
  *    문을 여는 것이다(선언이 권위다).
- *  ② 능력 없는 원본은 **사유 코드로** 거절한다(조용한 실패 금지).
+ *  ② 능력 없는 원본은 **사유 코드로** 거절한다(들어온 것이 없는 실패 금지).
  *  ③ 없는 기능을 있는 것처럼 답하지 않는다(내장 시뮬은 아직 재씨앗을 못 한다).
  */
 import { test } from 'node:test'

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

@@ -76,9 +76,9 @@ test('「몇 번·언제부터」를 정체 쪽도 든다 — 한 번 밀린 것
 
 test('뷰로 나간다 — **유입이 없는 갈래에서도**', () => {
   /*
-   * ★ 여기가 가장 조용해지기 쉬운 자리다. 커서가 막히면 유입이 0이므로 장부가 「빈 장부」 갈래를
+   * ★ 여기가 아무 신호도 나지 않기 가장 쉬운 자리다. 커서가 막히면 유입이 0이므로 장부가 「빈 장부」 갈래를
    * 지나고, 그 갈래에서 이 값을 떨어뜨리면 **정체가 실제로 일어나는 바로 그 상황에서** 침묵한다.
-   * `unhandled` 를 스냅샷이 떨어뜨려 정합성 검사가 영원히 조용했던 것과 같은 부류다.
+   * `unhandled` 를 스냅샷이 떨어뜨려 정합성 검사가 영원히 아무 신호도 내지 않았던 것과 같은 부류다.
    */
   const l = newIngestLedger()
   recordCursorStall(l, 'one timestamp holds more rows than a page', T0, 'trace')

package/test/declaration-reaches-model.test.ts

@@ -5,7 +5,7 @@
  * 커널 쪽에는 같은 이름의 하네스가 있다(kernel/test/declaration-in-state: 선언 ⊆ 상태). 그런데 사실이
  * 새던 자리는 그 앞에도 있었다: **레퍼런스 마스터 → 커널 모델** 이라는 문 하나(`masterToTwin`).
  *
- * 여기서 새면 아무도 모른다. 원본은 말했고, 화면은 조용히 id 를 보인다. 실제로 그렇게 잃었다 —
+ * 여기서 새면 아무도 모른다. 원본은 말했고, 화면은 알리지 않고 id 를 보인다. 실제로 그렇게 잃었다 —
  * 자리의 이름(화면이 `cut-station` 을 찍었다), 사람의 이름, GS1 참조, 자원 속성, 시험 명세 참조,
  * 사람·설비의 시험 결과. 하루 사이에 여섯 번이고, 전부 **한 줄에서 필드 하나가 빠진** 것이었다.
  *
@@ -21,7 +21,7 @@
  * 셋 중 어느 것도 아니면 실패한다 — 새 필드를 추가한 사람이 그때 분류해야 한다. 분류를 강제하는 것이
  * 이 검사의 전부다: 잊는 것이 기본값이면 잊는다.
  *
- * 필드 목록은 **소스에서 읽는다**(손으로 적지 않는다). 손으로 적으면 새 필드가 조용히 빠지고, 그것이
+ * 필드 목록은 **소스에서 읽는다**(손으로 적지 않는다). 손으로 적으면 새 필드가 알리지 않고 빠지고, 그것이
  * 바로 이 검사가 막으려는 실패다.
  */
 import { test } from 'node:test'
@@ -70,7 +70,7 @@ const ELSEWHERE: Record<string, string> = {
   footprint: '좌표는 `model.layout`(중심점)과 구역 기하로 간다 — 자리 줄에 실리는 값이 아니다.'
 }
 
-/** 모든 필드에 값을 실은 원본 — 값을 모르는 필드가 나오면 이 하네스는 실패한다(조용히 건너뛰지 않는다). */
+/** 모든 필드에 값을 실은 원본 — 값을 모르는 필드가 나오면 이 하네스는 실패한다(알리지 않고 건너뛰지 않는다). */
 const VALUE: Record<string, unknown> = {
   id: '__ID__',
   type: 'cut-station',
@@ -122,7 +122,7 @@ function build(c: Case): any {
     assert.ok(
       f in VALUE,
       `픽스처가 "${c.iface}.${f}" 에 실을 값을 모른다 — VALUE 에 하나 적어라.\n` +
-        '조용히 건너뛰면 그 필드는 아무도 안 보는 필드가 되고, 그것이 이 하네스가 막으려는 실패다.'
+        '알리지 않고 건너뛰면 그 필드는 아무도 안 보는 필드가 되고, 그것이 이 하네스가 막으려는 실패다.'
     )
     o[f] = f === 'id' ? c.id : VALUE[f]
   }
@@ -171,7 +171,7 @@ for (const c of CASES) {
       { lost, mangled },
       { lost: [], mangled: [] },
       `${c.iface}: 잃은 사실=[${lost}] · 옮기다 값이 바뀐 사실=[${mangled}]\n` +
-        '원본이 말한 것을 문에서 버리면 아무도 모른다 — 화면은 조용히 id 를 보인다.\n' +
+        '원본이 말한 것을 문에서 버리면 아무도 모른다 — 화면은 알리지 않고 id 를 보인다.\n' +
         '일부러 다른 길로 보내는 것이면 ELSEWHERE 에 그 길을 적어라(이름만 바뀌는 것은 RENAMED).'
     )
   })

package/test/declared-stimulus.test.ts

@@ -12,7 +12,7 @@
  * 첫 조각(`openLiveFeed`)이 같은 선언을 그대로 읽는다.
  *
  * 이 시험이 지키는 것:
- *  ① 선언이 없으면 조용히 지난다(정적 구조만 반영하는 트윈이 정상이다).
+ *  ① 선언이 없으면 알리지 않고 지난다(정적 구조만 반영하는 트윈이 정상이다).
  *  ② **미러에는 싣지 않는다** — 외부 실물이 진실인 트윈에 도착을 지어 주면 그것은 현실이 아니다.
  *  ③ 검사를 통과하지 못한 선언은 **태우지 않고** 이유를 남긴다(잘못된 선언 하나가 서버를 내린 이력이 있다).
  *  ④ 검사기가 없으면 싣지 않는다 — 검사할 수 없는 선언을 태우는 것이 가장 비싼 선택이다.
@@ -30,7 +30,7 @@ const ok = () => ({ ok: true as const })
 const bad = () => ({ ok: false as const, errorCode: 'scenario-sku-mix-required' })
 const sim = { hasScenarioEngine: true, mode: 'sim' as const }
 
-test('선언이 없으면 조용히 지난다 — 구조만 반영하는 트윈이 정상이다', () => {
+test('선언이 없으면 알리지 않고 지난다 — 구조만 반영하는 트윈이 정상이다', () => {
   assert.deepEqual(planStimulus(undefined, sim, ok), { action: 'skip', reason: 'none' })
   assert.deepEqual(planStimulus({ endpoint: 'x' }, sim, ok), { action: 'skip', reason: 'none' })
   /* 시나리오 자리에 객체가 아닌 것이 오면 선언이 아니다(문자열을 시나리오로 읽지 않는다). */
@@ -42,7 +42,7 @@ test('관측으로 도는 트윈에는 싣지 않는다 — 현실을 지어내
   assert.deepEqual(plan, { action: 'skip', reason: 'observed' })
 })
 
-test('시나리오 엔진이 없으면 싣지 않는다 — 조용히 아무 일도 없게 두지 않는다', () => {
+test('시나리오 엔진이 없으면 싣지 않는다 — 알리지 않고 아무 일도 없게 두지 않는다', () => {
   const plan = planStimulus({ scenario }, { hasScenarioEngine: false, mode: 'sim' }, ok)
   assert.deepEqual(plan, { action: 'skip', reason: 'no-engine' })
 })
@@ -73,7 +73,7 @@ test('선언을 얹으면서 접속 정보를 지우지 않는다', () => {
 /*
  * ── 배선 (소스로 지킨다) ────────────────────────────────────────────────────
  * 판정은 순수 함수가 하지만, 그것을 **기동 때 부르지 않으면** 아무 일도 일어나지 않는다. 그리고 못 실은
- * 이유는 말해야 한다 — 「선언했는데 안 실렸다」가 조용하면 사용자는 트윈이 고장 난 줄로 읽는다.
+ * 이유는 말해야 한다 — 「선언했는데 안 실렸다」를 말하지 않으면 사용자는 트윈이 고장 난 줄로 읽는다.
  */
 test('두 기동 경로에서 부른다 — 시뮬은 싣고, 미러는 그 사실을 말한다', () => {
   const src = readFileSync(fileURLToPath(new URL('../server/engine/twin-engine.ts', import.meta.url)), 'utf-8')

package/test/discovery-result.test.ts

@@ -2,7 +2,7 @@
  * 사이트 발견 결과 — **"못 찾았다" 를 "없다" 로 말하지 않게.**
  *
  * 실 시스템을 연결해 트윈을 만드는 경로에서, 발견이 실패하면 화면이 "사이트를 찾지 못했습니다" 라고만
- * 말했다. 레퍼런스 미등록·어댑터 미상·조회 실패·정말 0건이 그 한 문장으로 접혀 있었다 — 자격이
+ * 말했다. 레퍼런스 미등록·어댑터 미상·조회 실패·정말 0건이 그 한 문장에 섞여 있었다 — 자격이
  * 틀렸는지 주소가 틀렸는지 알 수 없었다.
  */
 import { test } from 'node:test'
@@ -50,7 +50,7 @@ test('네 가지 사유가 서로 구별된다 — 이것이 이 작업의 요
     discoveryTimedOut('s', 15).code
   ]
   assert.deepEqual(codes, ['reference-not-found', 'adapter-unknown', 'discovery-failed', 'discovery-timeout'])
-  assert.equal(new Set(codes).size, 4, '넷이 한 코드로 접히지 않는다')
+  assert.equal(new Set(codes).size, 4, '넷이 한 코드로 합쳐지지 않는다')
 })
 
 test('원 시스템이 준 사유를 감추지 않는다 — 사용자가 관리자에게 물어볼 수 있게', () => {

package/test/entity-delta.test.ts

@@ -3,10 +3,10 @@
  *
  * 지키는 것(2026-08-01 재편):
  *  ① **레퍼런스가 아는 것은 전부 나간다** — 필드를 손으로 골라 담지 않는다. 화이트리스트였을 때
- *     노드 parentId·작업 전량·물품 전량이 조용히 누락됐다. 계약에 속성이 생기면 자동으로 도달해야 한다.
+ *     노드 parentId·작업 전량·물품 전량이 오류 없이 빠졌다. 계약에 속성이 생기면 자동으로 도달해야 한다.
  *  ② **표식은 도메인 낱말을 훔치지 않는다** — 엔티티 종류 표식은 `entity`, `kind` 는 도메인 것
  *     (무버 cutter · 작업 putaway · 오더 workorder).
- *  ③ **조용히 자르지 않는다** — 물품 집약이 상한에 걸리면 total·truncated 로 밝힌다.
+ *  ③ **알리지 않고 자르지 않는다** — 물품 집약이 상한에 걸리면 total·truncated 로 밝힌다.
  */
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
@@ -111,7 +111,7 @@ test('물품: 개별(태그=epc) + 집약으로 나간다 — 수량·소속 팔
   assert.equal(agg.truncated, undefined, '상한 안이면 truncated 없음')
 })
 
-test('물품 집약: 상한을 넘으면 잘린 사실을 밝힌다 — 조용한 절단 금지', () => {
+test('물품 집약: 상한을 넘으면 잘린 사실을 밝힌다 — 들어온 것이 없는 절단 금지', () => {
   const items = Array.from({ length: ITEMS_AGGREGATE_LIMIT + 7 }, (_, i) => ({ epc: `e${i}`, location: 'rack-1' }))
   const d = buildEntityDeltas({ items }, 't1')
   const agg = byTag(d, itemsTag('t1')).data
@@ -236,7 +236,7 @@ test('수요 구간·피크·계약은 집약 태그로 나간다 — 개체의
   assert.equal(agg.data.peakSince.kW, 4200)
   /* 하루치를 매 브로드캐스팅에 실으면 채널이 그것으로 찬다 — 최근 것만 내고 전체 수를 함께 낸다. */
   assert.equal(agg.data.recent.length, 8)
-  assert.equal(agg.data.closedTotal, 137, '자른 사실을 조용히 두지 않는다')
+  assert.equal(agg.data.closedTotal, 137, '자른 사실을 알리지 않고 두지 않는다')
 })
 
 test('에너지가 없는 트윈은 에너지 태그를 내지 않는다 — 없는 것을 만들지 않는다', () => {

package/test/event-subjects.test.ts

@@ -0,0 +1,147 @@
+/*
+ * ★ 사건 하나가 무엇을 가리키는지 뽑는다 — 360 이력이 64초인 원인을 없애는 첫 조각.
+ *
+ * ── 왜 이 모양인가 (2026-08-27 실측) ────────────────────────────────────────
+ * 「이 품목의 이력」 조회가 64초다. 저장된 식별자에 품목과 로트가 한 문자열로 붙어 있어서, 품목만으로는
+ * 찾을 방법이 없다.
+ *
+ *   https://seunghwa.net/class/product-M0000618-lot-L2604100071
+ *
+ * 문자열을 자르는 규칙을 여기에 넣지 않는다 — 어느 부호가 로트를 가리키는지 연결된 시스템마다 다르고,
+ * chef 의 `-lot-` 을 굳히면 이 파일이 그 시스템 위에 서게 된다. 대신 대상마다 한 줄을 적고, 품목이
+ * 무엇인지는 그 트윈의 선언과 견주어 부르는 쪽이 답한다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { subjectsOf, SUBJECT_KINDS } from '../server/service/twin-subject/event-subjects.js'
+
+const objectEvent = (over: any = {}) => ({
+  eventType: 'epcis.ObjectEvent',
+  eventTime: '2026-08-27T05:00:00.000Z',
+  data: {
+    epcList: ['https://seunghwa.net/class/product-M0000438-lot-L2403090386'],
+    bizLocation: { id: 'M2R0001' },
+    action: 'OBSERVE',
+    ...over
+  }
+})
+
+const find = (subjects: any[], kind: string) => subjects.filter(s => s.kind === kind).map(s => s.id)
+
+test('★ 품목과 로트를 두 줄로 적는다 — 문자열을 자르지 않고도 품목으로 찾을 수 있다', () => {
+  const subjects = subjectsOf(objectEvent(), {
+    /* 선언과 견주어 품목을 찾는 일은 부르는 쪽이 한다 — 그 트윈의 선언을 아는 것이 그쪽이다. */
+    itemOf: epc => (epc.includes('product-M0000438') ? 'M0000438' : null)
+  })
+  assert.deepEqual(find(subjects, 'lot'), ['https://seunghwa.net/class/product-M0000438-lot-L2403090386'])
+  assert.deepEqual(find(subjects, 'item'), ['M0000438'])
+})
+
+test('★ 품목을 찾지 못하면 품목 줄을 만들지 않는다 — 짐작으로 이으면 남의 이력에 섞인다', () => {
+  const subjects = subjectsOf(objectEvent(), { itemOf: () => null })
+  assert.equal(find(subjects, 'lot').length, 1, '개체는 그대로 적는다')
+  assert.deepEqual(find(subjects, 'item'), [], '품목은 비운다')
+})
+
+test('★ 찾은 값이 개체 식별자와 같으면 품목이 아니다 — itemRefOf 는 URI 를 그대로 돌려준다', () => {
+  /*
+   * `itemRefOf` 는 SGTIN 이 아닌 모양에서 문자열을 그대로 낸다(자르는 판단을 하지 않으므로). 그 값을
+   * 품목으로 적으면 로트와 같은 줄이 두 종류로 생기고, 품목 이력이 로트 이력과 같아진다.
+   */
+  const epc = 'https://seunghwa.net/class/product-M0000438-lot-L2403090386'
+  const subjects = subjectsOf(objectEvent(), { itemOf: () => epc })
+  assert.deepEqual(find(subjects, 'item'), [])
+})
+
+test('★ 한 사건이 여러 대상을 가리킨다 — 자리·설비·오더·작업', () => {
+  const subjects = subjectsOf({
+    eventType: 'task.status',
+    eventTime: '2026-08-27T05:00:00.000Z',
+    data: { taskId: 'tk-1', moverId: 'mixer-1', toNode: 'M2R0001', orderId: 'ORD-9' }
+  })
+  assert.deepEqual(find(subjects, 'task'), ['tk-1'])
+  assert.deepEqual(find(subjects, 'equipment'), ['mixer-1'])
+  assert.deepEqual(find(subjects, 'order'), ['ORD-9'])
+  assert.ok(find(subjects, 'location').length <= 1, '자리는 한 줄이다')
+})
+
+test('★ 가리키는 것이 없으면 빈 배열이다 — 없는 대상을 만들지 않는다', () => {
+  const subjects = subjectsOf({ eventType: 'energy.demand.window', data: { maxKW: 3 } })
+  assert.deepEqual(subjects, [])
+})
+
+test('★ 작업이 오간 두 자리를 다 적는다 — 승격 컬럼은 둘 중 하나만 담을 수 있어 비워 둔다', () => {
+  /*
+   * `locationOf` 는 EPCIS 자리만 읽는다. 작업이 A→B 로 갈 때 컬럼 하나에 둘을 넣을 수 없으므로
+   * 아무것도 넣지 않는다. 이 표는 자리마다 줄이 하나라서 둘을 함께 담는다.
+   */
+  const subjects = subjectsOf({
+    eventType: 'task.status',
+    data: { taskId: 'tk-1', fromNode: 'M2R0001', toNode: 'M2R0002' }
+  })
+  assert.deepEqual(find(subjects, 'location'), ['M2R0001', 'M2R0002'])
+})
+
+test('★ 같은 대상을 두 번 적지 않는다 — 출발지와 도착지가 같을 수 있다', () => {
+  const subjects = subjectsOf({
+    eventType: 'task.status',
+    data: { taskId: 'tk-1', fromNode: 'M2R0001', toNode: 'M2R0001' }
+  })
+  assert.deepEqual(find(subjects, 'location'), ['M2R0001'])
+})
+
+test('종류 목록이 닫혀 있다 — 열어 두면 넣는 쪽마다 다른 이름을 쓴다', () => {
+  assert.deepEqual([...SUBJECT_KINDS], ['item', 'lot', 'order', 'location', 'equipment', 'task'])
+})
+
+test('너무 긴 식별자는 적지 않는다 — 자르면 그 줄이 다른 대상을 가리킨다', () => {
+  const long = 'x'.repeat(300)
+  const subjects = subjectsOf({ eventType: 'task.status', data: { taskId: long } })
+  assert.deepEqual(find(subjects, 'task'), [], '알리지 않고 자르지 않고 아예 만들지 않는다')
+})
+
+test('빈 값과 공백은 대상이 아니다 — 결측을 대상으로 만들지 않는다', () => {
+  const subjects = subjectsOf({ eventType: 'task.status', data: { taskId: '   ', moverId: '' } })
+  assert.deepEqual(subjects, [])
+})
+
+test('★ 클래스로 온 사건은 품목 줄만 만든다 — 개체가 없는 사건이다', () => {
+  /*
+   * 실측한 chef 의 사건이다. 무게로 담는 현장이라 개체 목록이 비어 있고 수량 목록에 클래스가 있다.
+   * 그것을 로트로 적으면 뜻이 틀린다 — 개체가 아니라 품목이다.
+   */
+  const subjects = subjectsOf({
+    eventType: 'epcis.ObjectEvent',
+    data: {
+      epcList: [],
+      quantityList: [{ epcClass: 'https://seunghwa.net/class/product-M0000879', quantity: 11797.6, uom: 'KGM' }],
+      bizLocation: { id: 'P2F0001' }
+    }
+  })
+  assert.deepEqual(find(subjects, 'lot'), [], '개체 줄을 만들지 않는다')
+  assert.deepEqual(find(subjects, 'item'), ['https://seunghwa.net/class/product-M0000879'])
+  assert.deepEqual(find(subjects, 'location'), ['P2F0001'])
+})
+
+test('★ 클래스도 선언과 견주어 품목 코드로 줄인다 — 선언이 답하면 그것을 쓴다', () => {
+  const subjects = subjectsOf(
+    {
+      eventType: 'epcis.ObjectEvent',
+      data: { epcList: [], quantityList: [{ epcClass: 'https://seunghwa.net/class/product-M0000879' }] }
+    },
+    { itemOf: epc => (epc.includes('M0000879') ? 'M0000879' : null) }
+  )
+  assert.deepEqual(find(subjects, 'item'), ['M0000879'])
+})
+
+test('개체와 클래스가 함께 오면 둘 다 적는다 — 한 사건이 둘을 가리킬 수 있다', () => {
+  const subjects = subjectsOf({
+    eventType: 'epcis.ObjectEvent',
+    data: {
+      epcList: ['https://seunghwa.net/class/product-M0000438-lot-L1'],
+      quantityList: [{ epcClass: 'https://seunghwa.net/class/product-M0000879' }]
+    }
+  })
+  assert.deepEqual(find(subjects, 'lot'), ['https://seunghwa.net/class/product-M0000438-lot-L1'])
+  assert.deepEqual(find(subjects, 'item'), ['https://seunghwa.net/class/product-M0000879'])
+})

package/test/event-time-column.test.ts

@@ -5,9 +5,9 @@
  * 예전에는 문자열 컬럼이었고, "UTC ISO 만 들어오니 사전식 비교가 맞는다" 는 전제 위에서 정렬·범위
  * 질의가 돌았다. 그 전제는 컬럼 어디에도 적혀 있지 않았다.
  *
- * 날짜 컬럼으로 바꾸면서 **조용한 함정**이 하나 드러났다: sqlite 는 datetime 을 공백 구분 형식
+ * 날짜 컬럼으로 바꾸면서 **들어온 것이 없는 함정**이 하나 드러났다: sqlite 는 datetime 을 공백 구분 형식
  * (`2026-08-07 11:00:00.000`)으로 저장하는데, 화면은 ISO 문자열(`…T11:00:00.000Z`)을 보낸다.
- * 문자열 그대로 비교하면 사전식으로 어긋나 **오류 없이 0건**이 나온다 — 원장 시간창이 조용히
+ * 문자열 그대로 비교하면 사전식으로 어긋나 **오류 없이 0건**이 나온다 — 원장 시간창이 알리지 않고
  * 비어 버리고, 사용자는 "그 시간에 아무 일도 없었다" 로 읽는다.
  *
  * 그래서 두 가지를 못 박는다: 저장 형식이 실제로 그렇다는 것과, 경계에서 날짜로 옮기면 걸린다는 것.
@@ -48,7 +48,7 @@ test('sqlite 는 datetime 을 공백 구분 형식으로 저장한다 — ISO
   await ds.destroy()
 })
 
-test('ISO 문자열을 그대로 넘기면 **조용히 0건** — 오류가 아니라 빈 결과라 더 위험하다', async () => {
+test('ISO 문자열을 그대로 넘기면 **알리지 않고 0건** — 오류가 아니라 빈 결과라 더 위험하다', async () => {
   const { ds, repo } = await seeded()
   const rows = await repo.find({
     where: { eventTime: Between('2026-08-07T10:00:00.000Z', '2026-08-07T12:00:00.000Z') }

package/test/event-type-split.test.ts

@@ -0,0 +1,155 @@
+/*
+ * ★ 여러 종류를 시각순으로 — 거르는 축과 정렬 축이 어긋나면 색인이 버려진다.
+ *
+ * ── 실측 (2026-08-28 · 승화푸드 저널 3,374,894행) ───────────────────────────
+ *   종류 8개 IN + 시각순 50건   SEARCH USING INDEX ix_twin_event_1 (domain, instance)   37.181초 · 0건
+ *   같은 조건 · 정렬 없음        SEARCH USING INDEX ix_twin_event_7 (…, event_type=?)     0.003초
+ *   종류 하나 + 시각순           SEARCH USING INDEX ix_twin_event_7 (…, event_type=?)     0.003초
+ *
+ * 정렬을 붙이는 순간 여러 종류의 순서를 합칠 방법이 없어 시각 색인으로 337만 행을 걸으며 행마다 종류를
+ * 확인한다. 그 트윈에 에너지 사건은 **0건**이다 — 없는 것을 찾느라 37초를 쓴다.
+ *
+ * 360 이력이 64초였던 것과 같은 부류다. 고침도 같은 성질이다: **있는 색인을 쓰게 한다.**
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { splitShape } from '../server/service/twin-journal/event-type-split-shape.js'
+
+const dir = (...p: string[]) => join(import.meta.dirname, '..', 'server', ...p)
+const split = readFileSync(dir('service', 'twin-journal', 'event-type-split.ts'), 'utf8')
+const shape = readFileSync(dir('service', 'twin-journal', 'event-type-split-shape.ts'), 'utf8')
+const journal = readFileSync(dir('service', 'twin-journal', 'twin-journal-query.ts'), 'utf8')
+
+const DESC = [{ name: 'eventTime', desc: true }]
+const ENERGY = ['energy.measured', 'energy.equipment', 'energy.demand.window', 'energy.peak']
+
+test('★ 에너지 원장이 보내는 모양이 이 갈래로 간다', () => {
+  const shape = splitShape({ filters: [{ name: 'eventType', operator: 'in', value: ENERGY }] }, DESC)
+  assert.ok(shape)
+  assert.deepEqual(shape!.eventTypes, ENERGY)
+})
+
+test('시간창이 함께 와도 간다 — 화면이 구간을 지정한다', () => {
+  const shape = splitShape(
+    {
+      filters: [
+        { name: 'eventType', operator: 'in', value: ENERGY },
+        { 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[]][] = [
+    ['종류가 하나', { filters: [{ name: 'eventType', operator: 'in', value: ['a'] }] }, DESC],
+    ['종류가 너무 많다', { filters: [{ name: 'eventType', operator: 'in', value: Array.from({ length: 13 }, (_, i) => `t${i}`) }] }, DESC],
+    ['종류 필터가 없다', { filters: [] }, DESC],
+    ['정확일치', { filters: [{ name: 'eventType', operator: 'eq', value: 'a' }] }, DESC],
+    ['제외 목록', { filters: [{ name: 'eventType', operator: 'notin_with_null', value: ENERGY }] }, DESC],
+    ['자유 검색어', { search: '전력', filters: [{ name: 'eventType', operator: 'in', value: ENERGY }] }, DESC],
+    ['다른 필터가 섞였다', { filters: [{ name: 'eventType', operator: 'in', value: ENERGY }, { name: 'epc', operator: 'search', value: 'x' }] }, DESC],
+    ['리비전 정렬', { filters: [{ name: 'eventType', operator: 'in', value: ENERGY }] }, [{ name: 'revision', desc: true }]],
+    ['오름차순', { filters: [{ name: 'eventType', operator: 'in', value: ENERGY }] }, [{ name: 'eventTime', desc: false }]],
+    ['못 읽는 시각', { filters: [{ name: 'eventType', operator: 'in', value: ENERGY }, { name: 'eventTime', operator: 'lte', value: '어제' }] }, DESC]
+  ]
+  for (const [why, params, sortings] of cases) {
+    assert.equal(splitShape(params, sortings), null, `${why} 는 일반 경로로 가야 한다`)
+  }
+})
+
+test('★ 종류를 정확일치로 묻는다 — 이 한 줄이 색인을 쓰게 한다', () => {
+  assert.match(split, /andWhere\('e\.eventType = :eventType', \{ eventType \}\)/)
+  assert.doesNotMatch(split, /eventType IN/, '나눈 뒤에 다시 여러 값으로 묻지 않는다')
+  /* 정렬 축이 색인의 마지막 칸과 같아야 한다. */
+  assert.match(split, /orderBy\('e\.eventTime', 'DESC'\)/)
+})
+
+test('★ 한 갈래라도 못 읽으면 반쪽을 전부인 것처럼 내지 않는다', () => {
+  assert.match(split, /if \(!page\) return null/)
+})
+
+test('★ 이어 읽기 지점을 모든 갈래에 같이 건다', () => {
+  /* 갈래마다 다르게 걸면 어떤 종류는 이미 지나간 구간을 다시 낸다. */
+  assert.match(split, /e\.eventTime < :curAt OR \(e\.eventTime = :curAt AND e\.\$\{tiebreak\} < :curTie\)/)
+  assert.match(split, /if \(!cursor\) return null/, '못 읽는 커서로는 답하지 않는다')
+})
+
+test('★ 나눌 수를 제한한다 — 나누는 것이 손해가 되는 지점이 있다', () => {
+  assert.match(shape, /export const MAX_SPLIT = 24/)
+  assert.match(split, /if \(!pairs \|\| pairs > MAX_SPLIT\) return null/)
+})
+
+test('★ 화면이 부르는 자리에 붙어 있다', () => {
+  assert.match(journal, /const split = splitShape\(effective, effective\.sortings \?\? \[\]\)/)
+  assert.match(journal, /await eventTypeSplitPage\(domain\.id, instanceIds, split, limit, tiebreak, effective\.pagination\?\.after\)/)
+  /* 파생 테이블 갈래보다 뒤, 일반 저널 질의보다 앞이어야 한다. */
+  assert.ok(journal.indexOf('readModelPage(domain.id') < journal.indexOf('splitShape(effective'))
+  assert.ok(journal.indexOf('splitShape(effective') < journal.indexOf('const qb = getQueryBuilderFromListParams'))
+})
+
+test('★ 걷을 조건이 적혀 있다 — 부르는 데가 없어지면 지운다', () => {
+  /*
+   * 앱에서 종류를 여러 값으로 보내는 곳은 에너지 원장 한 곳뿐이다. 그 화면이 종류를 하나씩 고르는
+   * 모양으로 바뀌면 이 갈래는 아무도 부르지 않는다 — 그때 지워야 한다. 그 조건을 코드에 적어 두지
+   * 않으면 아무것도 하지 않는 갈래가 무언가를 받쳐 주는 것처럼 남는다.
+   */
+  assert.match(split, /이 갈래를 걷을 조건/)
+  assert.match(split, /그때 \*\*지운다\.\*\*/)
+})
+
+/* ── 공정 단계 칩 (2026-08-29) ─────────────────────────────────────────────
+ *
+ * ★ 칩을 고른 순간 이 갈래가 꺼져서, **고르지 않은 쪽이 더 빨랐다.**
+ *
+ * 원장은 종류 넷을 담아 묻고 그 위에 단계 칩을 겹친다. 앞 판은 `bizStep` 필터를 만나면 모양을
+ * 알아보지 못해 예전 경로로 떨어졌다 — 좁혀 물으면 느려지는 화면이 된다.
+ */
+
+test('공정 단계 하나로 좁혀도 갈래 경로가 답한다', () => {
+  const shape = splitShape(
+    {
+      filters: [
+        { name: 'eventType', operator: 'in', value: ['epcis.ObjectEvent', 'epcis.AggregationEvent'] },
+        { name: 'bizStep', operator: 'eq', value: 'shipping' }
+      ]
+    } as any,
+    [{ name: 'eventTime', desc: true }] as any
+  )
+  assert.ok(shape, '이 모양을 알아봐야 한다')
+  assert.equal(shape?.bizStep, 'shipping')
+  assert.deepEqual(shape?.eventTypes, ['epcis.ObjectEvent', 'epcis.AggregationEvent'])
+})
+
+test('단계를 여러 값으로 주면 답하지 않는다 — 갈래가 곱해진다', () => {
+  const shape = splitShape(
+    {
+      filters: [
+        { name: 'eventType', operator: 'in', value: ['epcis.ObjectEvent', 'epcis.AggregationEvent'] },
+        { name: 'bizStep', operator: 'in', value: ['shipping', 'receiving'] }
+      ]
+    } as any,
+    [{ name: 'eventTime', desc: true }] as any
+  )
+  assert.equal(shape, null)
+})
+
+test('빈 단계 값은 받지 않는다 — 모든 행을 뜻하는지 없는 단계를 뜻하는지 알 수 없다', () => {
+  const shape = splitShape(
+    {
+      filters: [
+        { name: 'eventType', operator: 'in', value: ['epcis.ObjectEvent', 'epcis.AggregationEvent'] },
+        { name: 'bizStep', operator: 'eq', value: '  ' }
+      ]
+    } as any,
+    [{ name: 'eventTime', desc: true }] as any
+  )
+  assert.equal(shape, null)
+})

package/test/fold-gap-speaks.test.ts

@@ -0,0 +1,53 @@
+/*
+ * ★ 저장본 뒤의 사건 — 계산했든 못 했든 **말한다**.
+ *
+ * ── 무엇이 침묵했나 (2026-08-28 실측) ───────────────────────────────────────
+ * 미러는 저장본에서 상태를 되세우고 그 뒤의 사건만 따라 계산한다. 그 자리가 이랬다.
+ *
+ *   10:34:37  found cached state → revision 3372228
+ *   10:34:37  resumed from the stored fold seed at revision 3372228 — items 2665 · orders 4794
+ *
+ * 그 시각 저널의 머리는 3,374,894였다. 2,666건이 저장본보다 앞서 있었는데 **계산했다는 줄도, 못
+ * 했다는 줄도 없었다.** 갈래가 셋인데 말하는 갈래가 하나뿐이었기 때문이다.
+ *
+ *   ① 계산해서 나아갔다        → 말한다
+ *   ② 계산이 오류로 실패했다    → 말한다
+ *   ③ 오류 없이 끝났는데 그대로  → **아무 말도 없었다** ← 여기
+ *   ④ 저널 머리를 못 읽었다     → **아무 말도 없었다** ← 여기
+ *
+ * ③④에서 트윈은 그 사건들의 결과 없이 뜨고, 화면은 그것을 「없는 사실」로 그린다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const engine = readFileSync(join(import.meta.dirname, '..', 'server', 'engine', 'twin-engine.ts'), 'utf8')
+
+test('★ 저널 머리를 못 읽었으면 그 사실을 말하고 그대로 뜬다', () => {
+  assert.match(engine, /if \(!tip\) \{/, '못 읽은 갈래가 있어야 한다')
+  assert.match(engine, /could not read the journal tip/, '무엇을 못 했는지 말해야 한다')
+  assert.match(engine, /without folding what came after it/, '무엇을 잃는지 말해야 한다')
+})
+
+test('★ 계산이 아무 일도 하지 않았으면 그것도 말한다', () => {
+  assert.match(engine, /\} else if \(!failed\) \{/, '오류가 아닌데 나아가지 않은 갈래가 있어야 한다')
+  assert.match(engine, /left the seed at revision/)
+  /* 오류로 실패한 것을 두 번 말하지 않는다 — 이미 위에서 말했다. */
+  assert.match(engine, /let failed: string \| undefined/)
+})
+
+test('★ 부팅마다 부르는 질의를 관계로 묻지 않는다 — 이 파일이 스스로 금지한 모양이다', () => {
+  /*
+   * `findOne({ where: { domain: { id } } })` 는 안쪽에 상한이 없는 두 단계 질의가 된다(실측 12초,
+   * 저널 375만 행). `tipOf` 는 부팅마다 트윈마다 불리므로 그 한 번이 부팅을 붙잡는다.
+   */
+  const from = engine.indexOf('private static async tipOf')
+  assert.ok(from > 0, 'tipOf 가 있어야 한다')
+  const tipOf = engine.slice(from, from + 2600)
+  /* 주석에 인용된 나쁜 모양과 헷갈리지 않게, 실제 코드 모양만 본다. */
+  assert.doesNotMatch(tipOf, /findOne\(\{ where: \{ domain: \{ id: domainId \}/, '관계로 묻는 모양이 남아 있다')
+  assert.match(tipOf, /createQueryBuilder\('e'\)/)
+  assert.match(tipOf, /orderBy\('e\.revision', 'DESC'\)/)
+  assert.match(tipOf, /\.limit\(1\)/)
+})

package/test/forecast-metrics.test.ts

@@ -1,7 +1,7 @@
 /*
  * 예측 지표 — **스냅샷에서 무엇을 세는가.**
  *
- * 여기서 틀리면 예측 그래프가 조용히 다른 것을 그린다(오류 없이 곡선이 나온다). 특히 에너지 지표는
+ * 여기서 틀리면 예측 그래프가 알리지 않고 다른 것을 그린다(오류 없이 곡선이 나온다). 특히 에너지 지표는
  * 「없음」과 「0」이 같은 그림이 되기 쉬워서, 그 경계를 명시로 잡아 둔다.
  */
 import { test } from 'node:test'

package/test/forecast-tuning.test.ts

@@ -1,7 +1,7 @@
 /*
  * 예측 틱 크기 — **지평선이 정하고, 양끝은 묶인다.**
  *
- * 이 규칙이 틀리면 예측이 조용히 비싸지거나(1초 고정 시절 9,000틱·28.5초) 조용히 성글어진다
+ * 이 규칙이 틀리면 예측이 알리지 않고 비싸지거나(1초 고정 시절 9,000틱·28.5초) 알리지 않고 성글어진다
  * (짧은 작업이 한 틱에 삼켜진다). 둘 다 화면에는 그럴듯한 숫자로 나오므로 시험이 지킨다.
  */
 import { test } from 'node:test'