@things-factory/headless-twin 10.1.278 → 10.1.280

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

@@ -1,315 +0,0 @@
-/*
- * ★ 구조 리비전 — **실 DB로 경계를 넘어 본다.**
- *
- * 커널의 마디 계산(`replaySegments`)는 그쪽 테스트가 지킨다. 여기서 지키는 것은 **호스트 배선**이다:
- * 리비전을 언제 새로 만드는가 · 이벤트에 번호를 찍는가 · 재생이 그 번호로 마디를 나누는가 ·
- * 컬럼이 생기기 전 행(번호 없음)을 어디에 붙이는가.
- *
- * 이 배선은 **경계를 넘어야만** 틀리는 것이 드러난다. 그런데 지금 앱의 트윈은 전부 리비전 1이라
- * 경계를 한 번도 안 넘어 봤다 — 오늘 하루에만 "테스트는 통과하는데 배선이 틀린" 경우를 셋 봤으므로,
- * 그 상태로 두지 않는다.
- *
- * 실 엔티티·실 네이밍 전략으로 만든 sqlite in-memory 스키마에 **빌드 산출물**을 그대로 실행한다.
- * 소스를 고친 뒤에는 `npm run build:server` 를 먼저 돌려야 반영된다.
- */
-import { test, before, after, beforeEach } from 'node:test'
-import assert from 'node:assert/strict'
-import { createRequire } from 'node:module'
-import type { DataSource } from 'typeorm'
-
-/*
- * **CJS 로 실어 온다.** `dist-server` 는 CJS 이고 그 안의 twin-engine 은 커널을 `require` 로 든다.
- * 그것을 ESM `import` 로 끌면 Node 의 ESM→CJS 번역기가 내부 단언에서 터진다(ERR_INTERNAL_ASSERTION).
- * 실 산출물을 그대로 시험하는 것이 이 스펙의 요점이므로, 부르는 쪽이 CJS 로 맞춘다.
- */
-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')
-const { TwinEngine } = req('../dist-server/engine/index.js')
-const { TwinEvent } = req('../dist-server/service/twin-event/twin-event.js')
-const { TwinStructure } = req('../dist-server/service/twin-structure/twin-structure.js')
-const { TwinInstance } = req('../dist-server/service/twin-instance/twin-instance.js')
-const { WmsKernel, EventJournal } = req('@operato/twin-kernel')
-const { DataSource: TypeOrmDataSource } = req('typeorm')
-
-let ds: DataSource
-let domainId: string
-const INSTANCE = 'struct-probe'
-const GTIN = 'urn:epc:idpat:sgtin:0614141.012345.*'
-
-/** 저장 자리 `bins` 개 + 지게차 `forklifts` 대 — 구조를 다이얼한다. */
-const boardWith = (bins: number, forklifts: number): any => ({
-  spaceId: 'struct-space',
-  /* 이 픽스처가 식별자를 만드는 이름공간 — **픽스처마다 다르게** 둔다(같은 접두 아래에서 서로 다른
-     시험의 번호가 부딪치면 표준의 유일성 요구를 깬다, CBV 2.0 §8.2.4). 커널은 선언 없이 팔레트·문서를
-     만들지 않는다(0.7.45 에서 날조 프리픽스를 지웠다). */
-  identity: { namespaces: ['https://twin.test/structure-revision'] },
-  utcOffsetMinutes: 0,
-  locations: [
-    { id: 'dock-recv', type: 'dock', capacity: 100 },
-    { id: 'staging', type: 'staging', capacity: 100 },
-    ...Array.from({ length: bins }, (_, i) => ({ id: `bin-${i + 1}`, type: 'storage', capacity: 20 }))
-  ],
-  equipment: Array.from({ length: forklifts }, (_, i) => ({ id: `fk-${i + 1}`, kind: 'forklift', homeLocation: 'dock-recv' }))
-})
-
-/** 커널을 실제로 굴려 봉투를 얻는다 — 손으로 지어낸 모양은 검증이 아니다. */
-function realEvents(model: any, ticks: number): any[] {
-  const journal = new EventJournal()
-  const k = new WmsKernel('struct')
-  k.onEvent((e: any) => journal.append(e))
-  k.loadTwinModel(model)
-  k.scenario.load({
-    seed: 11,
-    generators: [{ kind: 'inbound-arrival', rate: { distribution: 'constant', meanPerHour: 120 }, content: { skuMix: [{ gtin: GTIN, weight: 1 }], qtyPerLine: { min: 1, max: 1 } } }]
-  })
-  k.scenario.start()
-  for (let i = 0; i < ticks; i++) k.tick(1000)
-  return journal.all() as any[]
-}
-
-before(async () => {
-  ds = new TypeOrmDataSource({
-    type: 'sqlite',
-    database: ':memory:',
-    synchronize: true,
-    dropSchema: true,
-    namingStrategy: new NamingStrategy(),
-    entities: [...shellEntities, ...authEntities, ...twinEntities],
-    logging: false
-  })
-  await ds.initialize()
-  addDataSource('default', ds)
-  const d = await ds.getRepository(Domain).save({ name: 'struct-test', subdomain: 'struct-test' } as any)
-  domainId = d.id
-})
-
-after(async () => {
-  await ds?.destroy()
-})
-
-beforeEach(async () => {
-  for (const target of [TwinEvent, TwinStructure, TwinInstance]) await ds.query(`DELETE FROM "${ds.getMetadata(target).tableName}"`)
-  /* 엔진의 리비전 캐시도 비운다 — 스펙 간에 남으면 다음 스펙이 옛 번호를 찍는다. */
-  ;(TwinEngine as any).structureRevCache = {}
-  /* 키가 `(domainId, instanceId)` 로 바뀌었다 — id 만으로 지우면 아무것도 지워지지 않는다. */
-  delete (TwinEngine as any).recovered[`${domainId}:${INSTANCE}`]
-})
-
-test('같은 구조로 다시 프로비저닝하면 리비전이 늘지 않는다 — 부팅마다 늘면 이력이 잘게 쪼개진다', async () => {
-  const model = boardWith(2, 1)
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', model, 'reset')
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', model, 'reset')
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', JSON.parse(JSON.stringify(model)), 'reset')
-
-  const revs = await ds.getRepository(TwinStructure).find({ where: { domain: { id: domainId }, instanceId: INSTANCE } })
-  assert.equal(revs.length, 1)
-  assert.equal(revs[0].rev, 1)
-})
-
-test('구조가 바뀌면 새 리비전이 생기고 **저널은 살아남는다**', async () => {
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
-  const first = realEvents(boardWith(2, 1), 300)
-  assert.ok(first.length > 0, '이벤트가 있어야 "살아남는지" 를 물을 수 있다')
-  await TwinEngine.persistBatch(domainId, INSTANCE, first, 0)
-
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3), 'reset')
-
-  const kept = await ds.getRepository(TwinEvent).count({ where: { domain: { id: domainId }, instanceId: INSTANCE } })
-  assert.equal(kept, first.length, '구조가 바뀌었다고 이력을 지우면 안 된다 — 그것이 이 작업의 전부다')
-
-  const revs = await ds.getRepository(TwinStructure).find({ where: { domain: { id: domainId }, instanceId: INSTANCE }, order: { rev: 'ASC' } })
-  assert.deepEqual(revs.map(r => r.rev), [1, 2])
-  assert.notEqual(revs[0].signature, revs[1].signature)
-})
-
-test('이벤트가 자기 구조 번호를 달고 저장된다 — 안 달면 나중에 어느 공장인지 알 길이 없다', async () => {
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
-  await TwinEngine.persistBatch(domainId, INSTANCE, realEvents(boardWith(2, 1), 200), 0)
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3), 'reset')
-  const before = await ds.getRepository(TwinEvent).count({ where: { domain: { id: domainId }, instanceId: INSTANCE } })
-  await TwinEngine.persistBatch(domainId, INSTANCE, realEvents(boardWith(6, 3), 200), before)
-
-  const rows = await ds.getRepository(TwinEvent).find({ where: { domain: { id: domainId }, instanceId: INSTANCE } })
-  const byRev = new Map<number | undefined, number>()
-  for (const r of rows) byRev.set(r.structureRev, (byRev.get(r.structureRev) ?? 0) + 1)
-  assert.deepEqual([...byRev.keys()].sort(), [1, 2], '두 구조에서 각각 쓰인 이벤트가 있어야 한다')
-  assert.ok((byRev.get(1) ?? 0) > 0 && (byRev.get(2) ?? 0) > 0)
-})
-
-test('★ 재생이 경계를 넘는다 — 앞선 사실은 남고, 새 구조의 설비가 들어온다', async () => {
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
-  const first = realEvents(boardWith(2, 1), 300)
-  await TwinEngine.persistBatch(domainId, INSTANCE, first, 0)
-
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3), 'reset')
-  await TwinEngine.persistBatch(domainId, INSTANCE, realEvents(boardWith(6, 3), 300), first.length)
-
-  const state = await TwinEngine.recover(domainId, INSTANCE)
-  assert.ok(state.items.length > 0, '앞 마디의 물품이 사라지면 이력을 지운 것과 다를 바 없다')
-  assert.equal(state.equipment.length, 3, '새 구조의 지게차 셋이 상태에 들어와야 한다')
-  assert.equal(state.locations.filter((n: any) => n.type === 'storage').length, 6, '늘린 자리가 안 보이면 늘린 의미가 없다')
-})
-
-test('구조 번호가 없는 옛 행은 **가장 오래된 구조**로 처리한다 — 새 공장에 대고 계산하지 않는다', async () => {
-  /*
-   * 컬럼이 생기기 전에 쓰인 행은 `structureRev` 가 비어 있다. 그것을 현재 보드로 계산하면 그때 없던
-   * 설비에서 일이 있었던 것처럼 보인다 — 이 규칙이 그 행들을 제자리에 붙인다.
-   */
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
-  const legacy = realEvents(boardWith(2, 1), 300)
-  await TwinEngine.persistBatch(domainId, INSTANCE, legacy, 0)
-  /* 컬럼이 없던 시절을 흉내 낸다 — 번호를 지운다. */
-  await ds.query(`UPDATE "${ds.getMetadata(TwinEvent).tableName}" SET structure_rev = NULL`)
-
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3), 'reset')
-  const state = await TwinEngine.recover(domainId, INSTANCE)
-  assert.ok(state.items.length > 0, '번호 없는 옛 행도 읽혀야 한다 — 알리지 않고 버리지 않는다')
-  assert.equal(state.equipment.length, 3, '마지막 구조가 자원의 진실이다')
-})
-
-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)
-
-  const state = await TwinEngine.recover(domainId, INSTANCE)
-  assert.equal(state.equipment.length, 2)
-  assert.equal(state.locations.filter((n: any) => n.type === 'storage').length, 3)
-  assert.ok(state.items.length > 0)
-})
-
-test('꺼진 트윈의 이력도 읽을 수 있다 — 저널은 트윈이 꺼져 있을 때 가장 필요하다', async () => {
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
-  assert.equal(TwinEngine.owns(domainId, INSTANCE), false, '떠 있지 않다')
-  assert.equal(await TwinEngine.ownsRegistered(domainId, INSTANCE), true, '그래도 이 테넌트 것이다')
-  assert.equal(await TwinEngine.ownsRegistered(domainId, 'someone-elses-twin'), false)
-})
-
-test('시간여행은 **그때의 공장**을 보여준다 — 과거에 최신 구조를 얹으면 없던 설비가 선다', async () => {
-  /*
-   * "지금" 을 물으면 최신 구조를 얹는 것이 맞다(재프로비저닝 직후 늘린 설비가 보여야 하니까).
-   * 그런데 그 규칙을 과거 조회에도 적용하면, 그 시점에 존재하지도 않던 설비가 화면에 선다 —
-   * 이 작업이 막으려던 바로 그 거짓말이다. 규칙이 "지금" 에만 걸리는지 못박는다.
-   */
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
-  const first = realEvents(boardWith(2, 1), 300)
-  await TwinEngine.persistBatch(domainId, INSTANCE, first, 0)
-
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3), 'reset')
-
-  const now = await TwinEngine.recover(domainId, INSTANCE)
-  assert.equal(now.equipment.length, 3, '"지금" 은 늘린 설비를 보여준다')
-
-  const past = await TwinEngine.recover(domainId, INSTANCE, first.length)
-  assert.equal(past.equipment.length, 1, '그 시점에는 지게차가 하나뿐이었다')
-  assert.equal(past.locations.filter((n: any) => n.type === 'storage').length, 2, '그때는 자리도 둘이었다')
-})
-
-test('구조 이력이 **무엇이 달라졌는지** 알린다 — 보드 두 개를 눈으로 비교할 수는 없다', async () => {
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
-  const first = realEvents(boardWith(2, 1), 200)
-  await TwinEngine.persistBatch(domainId, INSTANCE, first, 0)
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(6, 3), 'reset', '도장 능력 보강')
-  await TwinEngine.persistBatch(domainId, INSTANCE, realEvents(boardWith(6, 3), 100), first.length)
-
-  const history = await TwinEngine.structureHistory(domainId, INSTANCE)
-  assert.equal(history.length, 2)
-
-  /* 최초 리비전은 비교 대상이 없다 — 전부 새로 생긴 것으로 센다. */
-  assert.equal(history[0].rev, 1)
-  assert.equal(history[0].diff.locationsAdded, 4, '자리 넷(도크·스테이징·빈 둘)')
-  assert.ok(history[0].events > 0, '그 구조 아래 일어난 일의 수를 함께 말한다')
-
-  const second = history[1]
-  assert.equal(second.rev, 2)
-  assert.equal(second.comment, '도장 능력 보강')
-  assert.equal(second.diff.locationsAdded, 4, '저장 자리 넷이 늘었다')
-  assert.equal(second.diff.equipmentAdded, 2, '지게차 둘이 늘었다')
-  assert.deepEqual(
-    second.diff.locationTypes.find(c => c.key === 'storage'),
-    { key: 'storage', before: 2, after: 6, delta: 4 },
-    '"저장 자리 2 → 6" 이라고 읽혀야 한다'
-  )
-  assert.deepEqual(second.diff.equipmentKinds.find(c => c.key === 'forklift'), { key: 'forklift', before: 1, after: 3, delta: 2 })
-})
-
-test('번호 없는 옛 행도 가장 오래된 리비전의 몫으로 센다 — 재생과 같은 규칙', async () => {
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
-  const legacy = realEvents(boardWith(2, 1), 200)
-  await TwinEngine.persistBatch(domainId, INSTANCE, legacy, 0)
-  await ds.query(`UPDATE "${ds.getMetadata(TwinEvent).tableName}" SET structure_rev = NULL`)
-  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[1].events, 0)
-})
-
-test('지문 표기가 낡았을 뿐이면 리비전을 만들지 않는다 — 계산 방식을 바꿔도 이력이 부풀지 않는다', async () => {
-  /*
-   * 실제로 당했다. 지문을 원문에서 해시로 바꾸자 저장된 문자열이 무엇과도 안 맞아, 아무것도 안
-   * 바뀐 트윈들이 재기동 한 번에 전부 "구조가 바뀌었다" 로 기록됐다. 저장된 **보드**와 비교하면
-   * 그런 일이 없다.
-   */
-  const model = boardWith(2, 1)
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', model, 'reset')
-  const table = ds.getMetadata(TwinStructure).tableName
-  await ds.query(`UPDATE "${table}" SET signature = 'old-style-signature-from-a-previous-algorithm'`)
-
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', model, 'reset')
-
-  const revs = await ds.getRepository(TwinStructure).find({ where: { domain: { id: domainId }, instanceId: INSTANCE } })
-  assert.equal(revs.length, 1, '공장은 그대로인데 리비전이 늘면 이력이 거짓으로 부푼다')
-  assert.notEqual(revs[0].signature, 'old-style-signature-from-a-previous-algorithm', '표기는 새 방식으로 고쳐 둔다')
-})
-
-/*
- * ── 이어지는 현실(sim-world) — 재기동해도 이력이 끊기지 않는다 ────────────────
- *
- * 예전에는 sim-world 선언이 저널을 지우고 fresh 로 띄웠다. 실제로 없던 것은 **번호 이어 세기
- * 하나**였다: 상태 복원은 이미 저널 재생으로 하고 있었고, 막힌 것은 커널이 0부터 다시 세어 기존
- * 행과 겹치는 문제였다. 그 겹침은 오류를 내지 않고 알리지 않고 재생 순서를 뒤섞는다.
- */
-test('sim-world 로 다시 띄워도 저널이 살아남는다 — 선언이 지키는 약속', async () => {
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
-  const first = realEvents(boardWith(2, 1), 300)
-  await TwinEngine.persistBatch(domainId, INSTANCE, first, 0)
-
-  const rt = await TwinEngine.bootDeclared(domainId, INSTANCE, 'resume')
-  try {
-    const kept = await ds.getRepository(TwinEvent).count({ where: { domain: { id: domainId }, instanceId: INSTANCE } })
-    assert.equal(kept, first.length, 'sim-world 는 이어지는 현실이다 — 지우면 선언이 거짓이 된다')
-  } finally {
-    await TwinEngine.stop(domainId, INSTANCE)
-  }
-})
-
-test('★ 재기동 후 새 이벤트는 마지막 번호 뒤에 온다 — 겹치면 재생 순서가 뒤섞인다', async () => {
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
-  const first = realEvents(boardWith(2, 1), 300)
-  await TwinEngine.persistBatch(domainId, INSTANCE, first, 0)
-
-  const rt = await TwinEngine.bootDeclared(domainId, INSTANCE, 'resume')
-  try {
-    const kernel: any = rt.kernel
-    assert.ok(kernel, '커널이 떠야 이어 세기를 물을 수 있다')
-    assert.ok(
-      kernel.getSnapshot().revision >= first.length,
-      `이어 세지 않았다 — 저널 마지막 ${first.length}, 커널 ${kernel.getSnapshot().revision}`
-    )
-  } finally {
-    await TwinEngine.stop(domainId, INSTANCE)
-  }
-})
-
-test('저널이 비어 있으면 이어 셀 것이 없다 — 새로 시작하는 트윈에 영향 없음', async () => {
-  await TwinEngine.provision(domainId, INSTANCE, 'wms', boardWith(2, 1), 'reset')
-  const rt = await TwinEngine.bootDeclared(domainId, INSTANCE, 'resume')
-  try {
-    assert.equal((rt.kernel as any).getSnapshot().revision, 0)
-  } finally {
-    await TwinEngine.stop(domainId, INSTANCE)
-  }
-})

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

@@ -1,148 +0,0 @@
-/*
- * ★ 화면이 이미 부르는 문에서 파생 테이블을 쓴다 — 그리고 못 답할 때는 물러난다.
- *
- * ── 무엇을 놓쳤던가 (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

@@ -1,175 +0,0 @@
-/*
- * ★ 조회용 파생 표의 규율 — 앞으로만 채우고, 담지 않은 구간을 말한다.
- *
- * ── 왜 이 표를 만들었나 (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'/, '실제 테이블 이름을 쓴다')
-})