@things-factory/headless-twin 10.0.14 → 10.0.17

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/, '선언을 모르면 짐작하지 않고 물러난다')
+})

package/test/subject-read-model.test.ts

@@ -0,0 +1,175 @@
+/*
+ * ★ 조회용 파생 표의 규율 — 앞으로만 채우고, 담지 않은 구간을 말한다.
+ *
+ * ── 왜 이 표를 만들었나 (2026-08-27 실측) ───────────────────────────────────
+ * 360 화면의 「이 대상의 이력」이 64초다. 「무엇으로 걸러 시각순으로 정렬해 앞에서 30개」라는 모양에
+ * 맞는 목차가 저널에 없고, 얹어도 풀리지 않는다.
+ *
+ *   여러 값으로 거르면(IN) 정렬 때문에 목차를 못 쓴다 — 실측한 질의 계획
+ *   축이 늘 때마다 저널의 목차가 늘어난다 — 360 의 축 넷이면 13개
+ *   품목과 로트가 한 문자열에 붙어 있어 품목만으로는 찾을 수 없다 — 정확일치가 0건
+ *
+ * ── 이 테스트가 무엇을 지키나 ───────────────────────────────────────────────
+ * DB 를 띄우지 않는다. 지켜야 할 것은 **규율**이고 그것은 순수하게 확인할 수 있다 — 목차가 조회 모양과
+ * 같은 순서인가, 소급 채우기를 하지 않는가, 담지 않은 구간을 말하는가, 저널이 먼저인가.
+ *
+ * 설계: `operato-twin/design/plans/read-models.md`
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const dir = (...p: string[]) => join(import.meta.dirname, '..', 'server', ...p)
+const entity = readFileSync(dir('service', 'twin-subject', 'twin-subject-event.ts'), 'utf8')
+const writer = readFileSync(dir('service', 'twin-subject', 'twin-subject-writer.ts'), 'utf8')
+const query = readFileSync(dir('service', 'twin-subject', 'twin-subject-query.ts'), 'utf8')
+const resolver = readFileSync(dir('service', 'twin-subject', 'item-resolver.ts'), 'utf8')
+const engine = readFileSync(dir('engine', 'twin-engine.ts'), 'utf8')
+
+test('★ 목차 순서가 조회 모양과 같다 — 이 순서가 이 표의 존재 이유다', () => {
+  /*
+   * 「이 트윈의 이 대상의 것을 최신순으로 30개」가 빠르려면 목차가 거르는 값 다음에 시각이어야 한다.
+   * 순서가 바뀌면 다시 정렬하게 되고, 그것이 저널에서 64초가 된 바로 그 원인이다.
+   */
+  assert.match(
+    entity,
+    /ix_twin_subject_event_0'[\s\S]{0,160}?\[e\.domain, e\.instanceId, e\.subjectKind, e\.subjectId, e\.eventTime\]/,
+    '(도메인, 트윈, 종류, 식별자, 시각) 순서여야 한다'
+  )
+  /* 보관 상한을 지우는 축도 시각이 마지막이어야 한다(경계를 시각으로 찾으므로). */
+  assert.match(
+    entity,
+    /ix_twin_subject_event_1'[\s\S]{0,160}?\[e\.domain, e\.instanceId, e\.eventTime\]/,
+    '(도메인, 트윈, 시각) 목차가 있어야 한다'
+  )
+})
+
+test('★ 시각 컬럼에 드라이버 방언을 적지 않는다 — datetime 은 Postgres 가 거절한다', () => {
+  const at = entity.indexOf('eventTime: Date')
+  assert.ok(at > 0, 'eventTime 이 있어야 한다')
+  const decl = entity.slice(Math.max(0, at - 400), at)
+  assert.doesNotMatch(decl, /type: 'datetime'/, 'sqlite·MySQL 의 이름을 적지 않는다')
+  assert.doesNotMatch(decl, /type: 'timestamp'/, 'Postgres 의 이름도 적지 않는다')
+})
+
+test('★ 저널이 먼저다 — 이 표에 적다가 실패해도 저널 쓰기를 되돌리지 않는다', () => {
+  /* 사실의 원본은 저널이고 이 표는 다시 만들 수 있다. 반대로 두면 조회를 빠르게 하려고 만든 표가
+     사실을 잃는 원인이 된다. */
+  assert.match(writer, /catch \(err: any\)[\s\S]{0,200}?noteFailure/, '실패를 잡아 세어야 한다')
+  assert.match(writer, /return 0\s*\n\s*\}/, '실패해도 던지지 않는다')
+})
+
+test('★ 알리지 않고 비지 않는다 — 적지 못한 줄 수를 조회가 함께 낸다', () => {
+  /* 알리지 않고 비면 화면이 「그 대상에는 사건이 없다」고 말하게 된다. 그것이 이 부류에서 가장 나쁜 결함이다. */
+  assert.match(writer, /export function subjectWriteFailures/, '적지 못한 수를 물을 수 있어야 한다')
+  assert.match(query, /writeFailures: subjectWriteFailures\(/, '조회가 그 수를 실어 보낸다')
+  assert.match(query, /writeFailures: number/, '응답에 그 칸이 있어야 한다')
+})
+
+test('★ 담지 않은 구간을 말한다 — 앞으로만 채우므로 그 앞은 「없다」가 아니다', () => {
+  assert.match(query, /coveredFrom\?: Date/, '경계를 낼 칸이 있어야 한다')
+  assert.match(query, /orderBy\('s\.eventTime', 'ASC'\)[\s\S]{0,120}?limit\(1\)/, '가장 오래된 줄 하나로 구한다')
+  /* 저장하지 않고 조회할 때 구한다 — 저장한 값은 실제 자료와 어긋날 수 있다. */
+  assert.doesNotMatch(entity, /coveredFrom/, '경계를 표에 저장하지 않는다')
+})
+
+test('★ 종류가 닫힌 목록이고, 모르는 값은 빈 목록이 아니라 오류다', () => {
+  /* 빈 목록으로 답하면 오타가 「그 대상에는 사건이 없다」로 보인다. */
+  assert.match(query, /SUBJECT_KINDS as readonly string\[\]\)\.includes\(kind\)/, '닫힌 목록으로 검사한다')
+  assert.match(query, /throw new Error\(`unknown subjectKind/, '모르는 종류는 오류를 낸다')
+  assert.match(query, /subjectId is required/, '빈 식별자로 트윈 전체를 읽지 않는다')
+})
+
+test('★ 페이지를 시각으로 넘긴다 — 머리에 쌓이는 목록에서 건너뛰기는 본 줄을 다시 낸다', () => {
+  assert.match(query, /eventTime < :before/, '시각 커서로 넘긴다')
+  assert.doesNotMatch(query, /\.skip\(/, '건너뛰기(offset)를 쓰지 않는다')
+})
+
+test('★ 품목은 선언과 견주어 판정한다 — 문자열을 자르지 않는다', () => {
+  /*
+   * 어느 부호가 로트를 가리키는지는 연결된 시스템마다 다르고 커널 계약이 정한 적이 없다. 한 시스템의
+   * 관습(`-lot-`)을 규칙으로 굳히면 이 코드가 그 시스템 위에 서게 된다.
+   */
+  assert.match(resolver, /resolveByDeclaration\(itemRefOf\(epc\)/, '선언과 견주어 찾는다')
+  /* 주석은 그 부호를 설명으로 쓴다 — 코드에 있는지만 본다(주석 줄을 걷어 내고 검사한다). */
+  const code = resolver
+    .split('\n')
+    .filter(l => !/^\s*(\*|\/\*|\/\/)/.test(l))
+    .join('\n')
+  assert.doesNotMatch(code, /'-lot-'|"-lot-"|split\('-'\)|indexOf\('-lot/, '문자열을 자르는 규칙을 넣지 않는다')
+  /* 사건마다 부르므로 기억해 둔다. 선언이 바뀌면 세대가 달라져 다시 판정한다. */
+  assert.match(resolver, /generation !== generation|entry\.generation !== generation/, '선언 세대를 본다')
+})
+
+test('★ 저널을 쓰는 두 문이 모두 이 표에 적는다 — 한쪽만 적으면 그만큼이 화면에서 빈다', () => {
+  const carried = engine.indexOf('static async persistCarried')
+  const batch = engine.indexOf('static async persistBatch')
+  assert.ok(carried > 0 && batch > 0, '두 문이 있어야 한다')
+  assert.match(engine.slice(carried, carried + 900), /this\.writeSubjects\(/, 'persistCarried 가 적는다')
+  assert.match(engine.slice(batch, batch + 900), /this\.writeSubjects\(/, 'persistBatch 가 적는다')
+})
+
+test('★ 소급해서 채우지 않는다 — 마이그레이션이 표만 만든다', () => {
+  const migration = readFileSync(dir('migrations', '1786500000000-CreateTwinSubjectEvents.ts'), 'utf8')
+  assert.match(migration, /createTable/, '표를 만든다')
+  assert.match(migration, /createIndex/, '목차를 만든다')
+  /* 채우는 코드가 있으면 새 조회 축마다 3,128만 줄을 다시 만드는 구조가 된다. */
+  assert.doesNotMatch(migration, /INSERT|insert\(|from twin_events|TwinEvent/i, '기존 사건을 옮기지 않는다')
+  const list = readFileSync(dir('migrations', 'index.ts'), 'utf8')
+  assert.match(list, /CreateTwinSubjectEvents1786500000000/, '마이그레이션 목록에 배선돼 있어야 한다')
+})
+
+test('★ 이 표의 보관 정리는 체크포인트 상한을 보지 않는다 — 잃을 사실이 없다', () => {
+  /*
+   * 저널의 정리는 체크포인트가 반영하지 못한 사건을 지우지 않는다(그것을 지우면 사실이 사라진다).
+   * 이 표는 사건에서 파생된 값이라 지워도 사실이 사라지지 않는다 — 그 구간의 조회가 느려질 뿐이다.
+   */
+  assert.match(writer, /export async function pruneSubjectRows/, '정리 함수가 있어야 한다')
+  assert.doesNotMatch(writer, /revision <= :upTo/, '체크포인트 상한을 보지 않는다')
+  assert.match(writer, /orderBy\('s\.eventTime', 'ASC'\)/, '경계를 시각으로 찾는다 — 목차를 쓰려면 그래야 한다')
+  /* 저널 정리와 같은 창에서 돈다 — 두 표가 같은 보관 기간을 본다. */
+  assert.match(engine, /pruneSubjectRows\(/, '저널 정리 창에서 함께 부른다')
+})
+
+test('★ 어디까지 옮겼는지 이 프로세스가 든다 — 파생 테이블의 내용으로 알아내지 않는다', () => {
+  /*
+   * 저장하지 않고 파생 테이블의 내용으로 진행 지점을 알아내려 했고 세 번 틀렸다.
+   *
+   *   ① 최대 리비전 뒤부터    실시간으로 채워진 줄의 최댓값이 곧 저널의 끝이라 옮길 구간을 다 건너뛴다
+   *   ② 최소 리비전 앞까지    1부터 적으면 최솟값이 1이 되어 구간이 0으로 접힌다
+   *   ③ 최소 시각 아래로      사건이 시각순으로 오지 않는 트윈에서 곧바로 끝난다
+   *
+   * 채워진 것은 구간이 아니라 집합이다. 어느 축으로도 하나의 경계로 말할 수 없다.
+   *
+   * 그래서 알아내려 하지 않고 든다. **테이블에 적지 않는다**(사용자 판단) — 사건이 들어올 때 파생
+   * 테이블도 같이 적히므로, 옛 사건을 옮기는 일은 새 파생 테이블을 만들 때와 계산 규칙을 고쳤을 때뿐이다.
+   * 대가는 서버가 내려가면 그 몫을 다시 읽는 것이다.
+   */
+  const backfill = readFileSync(dir('service', 'twin-subject', 'twin-subject-backfill.ts'), 'utf8')
+  assert.match(backfill, /const inFlight = new Map</, '이 프로세스가 든다')
+  assert.doesNotMatch(backfill, /TwinProjectionProgress|progressRepo/, '테이블에 적지 않는다')
+  assert.doesNotMatch(backfill, /MIN\(s\.revision\)|MAX\(s\.revision\)|MIN\(s\.eventTime\)/, '파생 테이블의 내용으로 알아내지 않는다')
+  /* 목표는 처음 부를 때 한 번 정한다 — 매번 다시 재면 새 사건이 들어와 끝나지 않는다. */
+  assert.match(backfill, /targetRevision: Number\(tip\?\.max \?\? 0\)/, '목표를 한 번 정한다')
+  /* 다 옮기면 들고 있지 않는다 — 남겨 두면 다음 호출이 옛 목표를 본다. */
+  assert.match(backfill, /if \(complete\) inFlight\.delete\(key\)/, '끝나면 버린다')
+})
+
+test('★ 목록의 순서가 같은 시각에서도 정해진다 — 페이지가 본 줄을 다시 내지 않게', () => {
+  assert.match(query, /addOrderBy\('s\.revision', 'DESC'\)/, '같은 시각은 리비전으로 가른다')
+})
+
+test('★ 선언한 엔티티를 등록한다 — 선언만 하면 테이블이 만들어지지 않는다', () => {
+  /*
+   * 파생 테이블 엔티티를 만들고 `entities` 에 넣지 않은 적이 있다. 그러면 테이블이 만들어지지 않고,
+   * 그것을 쓰는 코드가 「그런 테이블 없다」로 실패한다. 파일이 있는 것과 등록된 것은 다르다.
+   */
+  const index = readFileSync(dir('service', 'twin-subject', 'index.ts'), 'utf8')
+  assert.match(index, /entities = \[TwinSubjectEvent\]/, '이 폴더의 엔티티가 등록돼 있어야 한다')
+  const services = readFileSync(dir('service', 'index.ts'), 'utf8')
+  assert.match(services, /\.\.\.TwinSubjectEntities/, '서비스 목록에도 실려야 한다')
+  /* 마이그레이션의 테이블 이름은 TypeORM 이 만든 것과 글자 그대로 같아야 한다. */
+  const migration = readFileSync(dir('migrations', '1786500000000-CreateTwinSubjectEvents.ts'), 'utf8')
+  assert.match(migration, /const TABLE = 'twin_subject_events'/, '실제 테이블 이름을 쓴다')
+})

package/test/touched-items.test.ts

@@ -5,7 +5,7 @@
  *  ① 개체를 말한 자리를 전부 읽는다 — 관측·집약(부모/자식)·변환(입력/출력).
  *  ② 부류 수량만 말한 사건은 「모른다」다 — 그 부류의 어느 개체인지 말하지 않았다.
  *  ③ 물품을 만지지 않는다고 **선언된** 사건은 빈 범위다(작업·설비·인원·자산·오더·품질·확인·에너지).
- *  ④ 낯선 낱말은 「모른다」다 — 커널이 사건을 늘렸을 때 조용히 빠뜨리지 않는다.
+ *  ④ 낯선 낱말은 「모른다」다 — 커널이 사건을 늘렸을 때 알리지 않고 빠뜨리지 않는다.
  *
  * 「모른다」(`null`)와 「하나도 없다」(빈 집합)는 **다른 사실**이다. 앞은 전부 다시 만들게 하고 뒤는
  * 물품을 건너뛰게 한다 — 둘을 같게 두면 둘 중 하나가 반드시 틀린다.
@@ -53,7 +53,7 @@ test('물품을 만지지 않는다고 선언된 사건은 빈 범위다 — 전
   assert.equal(energy!.size, 0)
 })
 
-test('낯선 낱말은 「모른다」다 — 커널이 사건을 늘렸을 때 조용히 빠뜨리지 않는다', () => {
+test('낯선 낱말은 「모른다」다 — 커널이 사건을 늘렸을 때 알리지 않고 빠뜨리지 않는다', () => {
   assert.equal(touchedItemKeys({ eventType: 'something.new', data: { epcList: ['x'] } }), null)
   assert.equal(touchedItemKeys({ data: { epcList: ['x'] } }), null, '낱말이 없으면 판정할 수 없다')
   assert.equal(touchedItemKeys(undefined), null)

package/test/twin-audit.test.ts

@@ -63,7 +63,7 @@ test('근거는 문자열일 때만 싣는다 — 객체를 그대로 넣어 화
   assert.equal(bad.reason, undefined)
 })
 
-test('args 가 지나치게 크면 자르되 잘랐다고 알린다 — 조용히 버리지 않는다', () => {
+test('args 가 지나치게 크면 자르되 잘랐다고 알린다 — 알리지 않고 버리지 않는다', () => {
   const huge = { blob: 'x'.repeat(9000) }
   const row = buildCommandAudit({ command: { type: 't', args: huge }, ack: {}, at: AT })
   assert.equal(row.argsTruncated, true)

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')
@@ -94,7 +140,7 @@ test('payload 가 data 로 감싸이지 않은 모양도 받는다', () => {
   assert.equal(epcOf({ epcList: ['urn:epc:id:sgtin:1.2.3'] }), 'urn:epc:id:sgtin:1.2.3')
 })
 
-test('상한을 넘는 값은 조용히 사라지지 않는다 — 잘리되 경고가 남는다', () => {
+test('상한을 넘는 값은 오류 없이 사라지지 않는다 — 잘리되 경고가 남는다', () => {
   const long = 'urn:epc:id:sgtin:' + 'x'.repeat(400)
   const warned: string[] = []
   const orig = console.warn

package/test/twin-model-item-db.test.ts

@@ -6,7 +6,7 @@
  *
  * 여기서 지키는 것:
  *  · 어떻게 셌는지 밝힌다 — 행이면 DB 가 페이징, 문서면 서버가 통째로 읽어 잘랐다(`basis`)
- *  · 조용히 자르지 않는다 — 총 건수가 항상 함께 오고, 훑기가 상한에 닿으면 그렇다고 말한다
+ *  · 알리지 않고 자르지 않는다 — 총 건수가 항상 함께 오고, 훑기가 상한에 닿으면 그렇다고 말한다
  *  · 모르는 축은 **거절한다** — 빈 목록으로 답하면 오타 하나가 "우리 트윈엔 그게 없다" 로 굳는다
  *  · 투영이 낡아도 항목은 열린다 — 행에 없으면 문서에서 찾는다
  *  · 이어진 것은 **양방향**이고, 선언된 관계만 따른다(선언에 없는 길은 그리지 않는다)
@@ -141,7 +141,7 @@ test('비교하지 못했으면 관측은 null 이고, 답했으면 **근거를
    * 이 픽스처에는 저널이 없다(행만 있다) — 되짚을 것이 없으므로 관측은 없다. **0 이나 빈 객체로
    * 메우면 "관측했는데 아무것도 없었다" 로 읽힌다.**
    *
-   * 예전 이 검사는 "트윈이 안 돌면 관측은 null" 이었다. 지금은 멈춘 트윈도 저널을 접어 답할 수 있고,
+   * 예전 이 검사는 "트윈이 안 돌면 관측은 null" 이었다. 지금은 멈춘 트윈도 저널을 계산해 답할 수 있고,
    * 그 답이 **자기 근거를 달고 온다**(`observedBasis`). 그래서 규율을 그 자리에 맞춰 다시 적는다:
    * 답이 없으면 null, 답이 있으면 그것이 라이브인지 되짚은 것인지 말한다. 근거 없는 답은 없다.
    */
@@ -230,10 +230,10 @@ test('지도의 선이 진단이 된다 — 이어진 것뿐 아니라 **끊긴
  * ★ 관측 열이 **자기 근거를 말한다** — 라이브인지 되짚은 것인지.
  *
  * 둘은 같은 모양의 값이라, 근거가 없으면 되짚은 값을 "지금 이렇다" 로 읽는다. 그래서 근거를 실을
- * 자리가 없던 동안에는 멈춘 트윈의 저널을 아예 접지 않았다(관측 열이 통째로 `—`). 자리를 만든 뒤의
+ * 자리가 없던 동안에는 멈춘 트윈의 저널을 아예 계산하지 않았다(관측 열이 통째로 `—`). 자리를 만든 뒤의
  * 규율은 하나다: **답하면 근거를 말한다.**
  */
-test('멈춘 트윈도 저널을 접어 답하고, 그 답은 다시 계산한 값이라고 알린다', async () => {
+test('멈춘 트윈도 저널을 계산해 답하고, 그 답은 다시 계산한 값이라고 알린다', async () => {
   const { WmsKernel, EventJournal } = req('@operato/twin-kernel')
   const model = {
     spaceId: 'journal-space',
@@ -273,5 +273,5 @@ test('멈춘 트윈도 저널을 접어 답하고, 그 답은 다시 계산한
   const it = await q.twinModelItem(INST, 'equipment', 'fk-1', ctx)
   assert.ok(it?.observed, '저널이 있으면 멈춘 트윈도 마지막으로 알던 사실을 답할 수 있다')
   assert.equal(it.observedBasis, 'journal', '라이브가 아니라 되짚은 것이라고 말해야 "지금 이렇다" 로 읽히지 않는다')
-  assert.ok(it.observedRevision > 0, '몇 번째 리비전까지 접었는지 함께 말한다 — 규모의 한계도 그 수가 말한다')
+  assert.ok(it.observedRevision > 0, '몇 번째 리비전까지 계산했는지 함께 말한다 — 규모의 한계도 그 수가 말한다')
 })

package/test/twin-model-tree-db.test.ts

@@ -7,7 +7,7 @@
  *
  * 여기서 지키는 것:
  *  · 패턴을 코드가 알지 않는다 — 선언 그래프에서 자기 축으로 돌아오는 순환을 찾는다
- *  · **조용히 고르지 않는다** — 순환이 여럿이면 후보를 내고 멈춘다(방향이 뒤집힌 전개는
+ *  · **알리지 않고 고르지 않는다** — 순환이 여럿이면 후보를 내고 멈춘다(방향이 뒤집힌 전개는
  *    틀린 답이 아니라 **반대의 답**이라 화면만 보고는 구별되지 않는다)
  *  · 수량은 곱해 내려가되, **모르면 곱하지 않는다**(1 로 메우면 윗단 합계가 통째로 거짓이 된다)
  *  · 사이클을 만나면 다시 파지 않고 말한다
@@ -153,7 +153,7 @@ test('사이클은 다시 탐색하지 않고 알린다', async () => {
   await TwinEngine.ingestMaster(domainId, master(), 'reset')
 })
 
-test('상한에서 끊기면 끊겼다고 알린다 — 조용히 자르지 않는다', async () => {
+test('상한에서 끊기면 끊겼다고 알린다 — 알리지 않고 자르지 않는다', async () => {
   const shallow = await explode('trailer', { maxDepth: 1 })
   assert.equal(shallow.truncated.depth, true)
   assert.deepEqual(shallow.items.filter((n: any) => n.depth === 2), [], '깊이 상한 아래는 안 판다')
@@ -174,3 +174,36 @@ test('선언에 없는 자재를 참조하면 그 사실이 드러난다', async
   assert.equal(child.known, false, '선언에 없다는 사실을 함께 낸다(있는 척하지 않는다)')
   await TwinEngine.ingestMaster(domainId, master(), 'reset')
 })
+
+test('★ 선언에 없는 축을 거치면 터지지 않고 **왜 못 하는지 말한다**', async () => {
+  /*
+   * ── 실측으로 터진 것 (2026-08-24) ────────────────────────────────────────
+   * 이 전개는 **트윈 모델의 선언**을 읽는다(`axisInfo(...).path` 로 모델 안을 찾아 들어간다). 그런데
+   * 커널 카탈로그의 축 중 셋은 **선언되는 것이 아니라 일어나는 것**이다 — `orders`·`tasks`·`items`
+   * 는 사건이 만들고 끝나면 사라진다. 모델이 그 목록을 가질 수 없으므로 `path` 가 비어 있다.
+   *
+   *   Cannot read properties of undefined (reading 'split')
+   *
+   * ★ **터진 것은 요청한 축이 아니라 「거쳐 가는 축」이다.** `locations` 를 물으면 그 순환이 `tasks` 를
+   * 거치는데(작업이 `from`·`at` 으로 자리를 두 번 가리킨다) 그 `tasks` 에 경로가 없다. 그래서 요청한
+   * 축만 지켜서는 막히지 않는다 — 처음에 그렇게 고쳤다가 이 시험이 잡았다.
+   *
+   * 그리고 빈 트리로 답하면 화면이 「이어진 것이 없다」로 읽는데 그것은 거짓이다 — 작업은 자리를
+   * 가리키고 있고, 다만 이 질의가 그것을 아는 곳이 아니다.
+   */
+  const q = new TwinModelTreeQuery()
+  const ctx = { state: { domain: { id: domainId } } } as any
+
+  /* 두 홉을 지정해야 순환이 하나로 정해진다 — 안 지정하면 앞 갈래(모호함)에서 답한다. */
+  const loc = await q.twinModelTree(INSTANCE, 'locations', 'st-a', ctx, 'twin.rel.from', 'twin.rel.at')
+  assert.ok(loc, 'locations: 터지지 않는다')
+  assert.deepEqual(loc.items, [], 'locations: 펼친 것이 없다')
+  assert.equal(loc.reason, 'not-declared-in-model', 'locations: 왜 못 하는지 말한다(거쳐 갈 축이 선언에 없다)')
+
+  /* 자기참조 순환이 아예 없는 축은 그 사실을 말한다 — 이유가 다르면 낱말도 달라야 한다. */
+  for (const axis of ['orders', 'tasks', 'items']) {
+    const r = await q.twinModelTree(INSTANCE, axis, 'anything', ctx)
+    assert.ok(r, `${axis}: 터지지 않는다`)
+    assert.equal(r.reason, 'no-recursive-relation', `${axis}: 순환이 없다는 사실을 말한다`)
+  }
+})

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

@@ -75,7 +75,7 @@ test('인제스트가 원천을 각인한다 — 원천이 무엇이든 한 자
 test('원천을 모르는 재프로비전이 이미 아는 것을 지우지 않는다 — 한 번 지우면 다시 못 읽는다', async () => {
   /*
    * 이 경로는 실제로 있다 — 원천을 모르는 호출자(스크립트·복구·옛 코드)가 같은 트윈을 다시
-   * 인제스트한다. 그때 `origin` 을 덮어 비우면 그 트윈은 **조용히 다시 읽을 수 없게 된다.**
+   * 인제스트한다. 그때 `origin` 을 덮어 비우면 그 트윈은 **알리지 않고 다시 읽을 수 없게 된다.**
    * 그런 종류의 손상은 다음번에 다시 읽으려 할 때까지 아무도 모른다.
    */
   await TwinEngine.ingestMaster(domainId, master(BORN, 5), 'reset')

package/test/warm-start-seam.test.ts

@@ -12,7 +12,7 @@
  *
  * ── 무엇을 단언하나 ────────────────────────────────────────────────────────
  * 스냅샷의 오더가 남은 데맨드(requested − fulfilled)로 커널에 서고, 이행이 끝난 오더는 서지 않고,
- * 원값이 없는 오더는 조용히 서지 않는다는 것. 숫자를 지어내지 않는다는 규칙이 이음매 끝까지 지켜지는가.
+ * 원값이 없는 오더는 알리지 않고 서지 않는다는 것. 숫자를 지어내지 않는다는 규칙이 이음매 끝까지 지켜지는가.
  */
 import { test } from 'node:test'
 import assert from 'node:assert/strict'