@things-factory/headless-twin 10.1.278 → 10.1.280

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

@@ -1,193 +0,0 @@
-/*
- * ★ 저널 검색 키 승격 검증 — payload(JSON) 안의 값을 인덱스 가능한 실컬럼으로 꺼내는 규칙.
- *
- * 이 규칙이 틀리면 "저널에는 있는데 검색으로는 안 나오는 이벤트" 가 생긴다. 화면에서는 그냥
- * **없는 것으로 보인다** — 저널에서 가장 나쁜 결함이라 규칙을 테스트로 고정한다.
- */
-import { test } from 'node:test'
-import assert from 'node:assert/strict'
-
-/*
- * **빌드 산출물을 부른다** — 이 모듈은 로그 문(`engine/log.js`)을 값으로 참조하고, 타입만 지우고 소스를
- * 실행하는 방식은 그 `.js` 경로를 `.ts` 로 바꿔 주지 않는다. 소스를 부르면 「모듈을 찾을 수 없다」로 선다.
- * **소스를 고친 뒤에는 `npm run build:server` 를 먼저 돌린다.**
- */
-import { createRequire } from 'node:module'
-
-const req = createRequire(import.meta.url)
-const { bizStepOf, epcOf, orderOf, bizTransactionOf, locationOf, equipmentIdOf, twinEventKeys } = req('../dist-server/service/twin-event/twin-event-keys.js')
-
-/** EPCIS ObjectEvent 한 건(입고) — 실제 인제스트가 싣는 모양. */
-const EPCIS_OBJECT = {
-  eventType: 'epcis.ObjectEvent',
-  eventTime: '2026-07-31T02:10:00.000Z',
-  data: {
-    bizStep: 'urn:epcglobal:cbv:bizstep:receiving',
-    disposition: 'urn:epcglobal:cbv:disp:in_progress',
-    epcList: ['urn:epc:id:sgtin:0614141.107346.2018'],
-    readPoint: { id: 'urn:epc:id:sgln:0614141.00777.DOCK-3' },
-    bizLocation: { id: 'urn:epc:id:sgln:0614141.00888.0' },
-    bizTransactionList: [{ type: 'urn:epcglobal:cbv:btt:po', bizTransaction: 'urn:epc:id:gdti:0614141.402.2' }]
-  }
-}
-
-test('EPCIS 이벤트에서 축이 모두 뽑히고, 거래는 거래 칸에 든다', () => {
-  const k = twinEventKeys(EPCIS_OBJECT)
-  assert.equal(k.bizStep, 'receiving')
-  assert.equal(k.epc, 'urn:epc:id:sgtin:0614141.107346.2018')
-  assert.equal(k.locationId, 'urn:epc:id:sgln:0614141.00777.DOCK-3')
-  /*
-   * ── 이 기대가 옮겨졌다 (2026-09-05 사용자 결정) ────────────────────────────
-   * 전에는 이 GDTI 가 `orderId` 로 뽑혔다. 그래서 한 오더의 이력이 색인 안에서 두 쪽으로
-   * 갈라졌다 — 운영 델타는 `order-1`, EPCIS 는 GDTI. 이제 칸이 둘이다.
-   */
-  assert.equal(k.bizTransaction, 'urn:epc:id:gdti:0614141.402.2')
-  assert.equal(k.orderId, undefined, '거래 식별자가 오더 칸에 앉았다')
-})
-
-test('식별자는 끝마디가 아니라 전체를 저장한다 — 부분일치 검색이 양방향으로 성립해야 한다', () => {
-  const k = twinEventKeys(EPCIS_OBJECT)
-  /* 화면은 '2018' 로 축약해 보여주지만 색인은 원본을 갖는다. contains 검색이라
-   * 끝마디로도 URN 전체로도 찾힌다 — 끝마디만 저장하면 URN 경로가 사라진다. */
-  assert.ok(k.epc!.includes('2018'), '끝마디로 찾을 수 있어야 한다')
-  assert.ok(k.epc!.startsWith('urn:epc:id:sgtin'), 'URN 전체로도 찾을 수 있어야 한다')
-})
-
-test('readPoint 가 없으면 bizLocation 으로 내려간다', () => {
-  const ev = { ...EPCIS_OBJECT, data: { ...EPCIS_OBJECT.data, readPoint: undefined } }
-  assert.equal(locationOf(ev), 'urn:epc:id:sgln:0614141.00888.0')
-})
-
-test('bizStep 이 없으면 이벤트 타입에서 유추한다 — 운영 델타도 단계를 말할 수 있어야 한다', () => {
-  assert.equal(bizStepOf({ eventType: 'task.status', data: { task: 't1' } }), 'task.status')
-  assert.equal(bizStepOf({ eventType: 'epcis.AggregationEvent', data: {} }), 'AggregationEvent')
-})
-
-test('a private business step is indexed by its short name, like a CBV one', () => {
-  /* `split(':')` on `https://hatiolab.com/voc/bizstep/consuming` kept `//hatiolab.com/voc/bizstep/consuming` — a journal
-     search for `consuming` found nothing. The rule is the contract's bizStepName. */
-  assert.equal(bizStepOf({ data: { bizStep: 'https://hatiolab.com/voc/bizstep/consuming' } }), 'consuming')
-  assert.equal(bizStepOf({ data: { bizStep: 'urn:epcglobal:cbv:bizstep:shipping' } }), 'shipping')
-})
-
-test('집합 이벤트는 parentID 를, 수량 이벤트는 epcClass 를 품목으로 쓴다', () => {
-  assert.equal(epcOf({ data: { parentID: 'urn:epc:id:sscc:0614141.1234567890' } }), 'urn:epc:id:sscc:0614141.1234567890')
-  assert.equal(epcOf({ data: { quantityList: [{ epcClass: 'urn:epc:idpat:sgtin:0614141.107346.*', quantity: 40 }] } }), 'urn:epc:idpat:sgtin:0614141.107346.*')
-})
-
-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'
-  )
-  /*
-   * ── 이 줄이 뒤집혔다 (2026-09-05 사용자 결정) ──────────────────────────────
-   * 전에는 오더를 말하지 않는 EPCIS 가 **거래로 내려갔다.** 그래서 한 칸에 두 낱말이 들었고,
-   * 한 오더의 이력이 색인 안에서 두 쪽으로 갈라졌다(실측: 어휘가 섞인 행 10,004개).
-   *
-   * 바로 위 줄이 그 위험을 이미 알고 있었다 — 「거래와 오더는 같은 것이 아닐 수 있다」. 알면서
-   * 같은 칸에 넣고 있었다. 이제 갈라 든다.
-   */
-  assert.equal(orderOf({ data: { bizTransactionList: [{ bizTransaction: 'PO-9' }] } }), undefined)
-  assert.equal(bizTransactionOf({ 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 — 결측과 빈값을 섞지 않는다', () => {
-  const k = twinEventKeys({ eventType: 'equipment.status', data: { equipment: 'fork-1', status: 'idle' } })
-  assert.equal(k.epc, undefined)
-  assert.equal(k.orderId, undefined)
-  assert.equal(k.locationId, undefined)
-  assert.equal(k.moverId, undefined)
-  /* bizStep 은 이벤트 타입에서 유추되므로 남는다 — 이건 결측이 아니다. */
-  assert.equal(k.bizStep, 'equipment.status')
-})
-
-test('설비·무버 축 — 운영 델타의 moverId 를 뽑는다', () => {
-  const ev = { eventType: 'equipment.status', data: { moverId: 'fork-3', status: 'down', location: 'rack-1' } }
-  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')
-})
-
-test('EPCIS 의 readPoint 는 운영 델타의 location 보다 우선한다', () => {
-  assert.equal(locationOf({ data: { readPoint: { id: 'DOCK-1' }, location: 'rack-9' } }), 'DOCK-1')
-})
-
-test('payload 가 data 로 감싸이지 않은 모양도 받는다', () => {
-  assert.equal(epcOf({ epcList: ['urn:epc:id:sgtin:1.2.3'] }), 'urn:epc:id:sgtin:1.2.3')
-})
-
-test('상한을 넘는 값은 오류 없이 사라지지 않는다 — 잘리되 경고가 남는다', () => {
-  const long = 'urn:epc:id:sgtin:' + 'x'.repeat(400)
-  const warned: string[] = []
-  const orig = console.warn
-  console.warn = (...a: unknown[]) => void warned.push(String(a[0]))
-  try {
-    const k = twinEventKeys({ data: { epcList: [long] } })
-    assert.equal(k.epc!.length, 255)
-    assert.equal(warned.length, 1, '잘렸다는 사실이 어딘가에는 남아야 한다')
-    assert.ok(warned[0].includes('epc'))
-  } finally {
-    console.warn = orig
-  }
-})
-
-test('빈 봉투에도 터지지 않는다', () => {
-  /* `provenance` 도 이 목록에 있어야 한다 — 봉투가 비어도 「선언된 것인지」는 낼 칸이 있다. */
-  const empty = {
-    action: undefined,
-    bizStep: undefined,
-    epc: undefined,
-    orderId: undefined,
-    bizTransaction: undefined,
-    locationId: undefined,
-    moverId: undefined,
-    provenance: undefined
-  }
-  assert.deepEqual(twinEventKeys(undefined), empty)
-  assert.deepEqual(twinEventKeys({}), empty)
-})

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

@@ -1,319 +0,0 @@
-/*
- * ★ 개념 안의 목록과 항목 하나 — **막다른 길을 만들지 않는다.**
- *
- * 개념 지도가 숫자만 내면 그 숫자가 막다른 길이다. 인스펙션의 원칙은 "화면에 보이는 모든 식별자는
- * 그 자신의 상세로 가는 문" 이므로, 셈 다음에 **목록**과 **항목**이 있어야 그 원칙이 성립한다.
- *
- * 여기서 지키는 것:
- *  · 어떻게 셌는지 밝힌다 — 행이면 DB 가 페이징, 문서면 서버가 통째로 읽어 잘랐다(`basis`)
- *  · 알리지 않고 자르지 않는다 — 총 건수가 항상 함께 오고, 훑기가 상한에 닿으면 그렇다고 말한다
- *  · 모르는 축은 **거절한다** — 빈 목록으로 답하면 오타 하나가 "우리 트윈엔 그게 없다" 로 굳는다
- *  · 투영이 낡아도 항목은 열린다 — 행에 없으면 문서에서 찾는다
- *  · 이어진 것은 **양방향**이고, 선언된 관계만 따른다(선언에 없는 길은 그리지 않는다)
- *  · 관측이 없는 것과 견주지 못한 것을 구별한다(`observed: null`)
- */
-import { test, before, after } from 'node:test'
-import assert from 'node:assert/strict'
-import { createRequire } from 'node:module'
-import type { DataSource } from 'typeorm'
-
-const req = createRequire(import.meta.url)
-const { NamingStrategy, addDataSource, entities: shellEntities, Domain } = req('@things-factory/shell')
-const { entities: authEntities } = req('@things-factory/auth-base')
-const { entities: twinEntities } = req('../dist-server/service/index.js')
-const { TwinEngine } = req('../dist-server/engine/index.js')
-const { TwinModelItemQuery } = req('../dist-server/service/twin-model/twin-model-item-query.js')
-const { TwinModelQuery } = req('../dist-server/service/twin-model/twin-model-query.js')
-const { TwinSpace } = req('../dist-server/service/twin-space/twin-space.js')
-const { TwinArea } = req('../dist-server/service/twin-space/twin-area.js')
-const { DataSource: TypeOrmDataSource } = req('typeorm')
-
-let ds: DataSource
-let domainId: string
-let q: any
-let ctx: any
-
-const INSTANCE = 'item-probe'
-
-/** MES 마스터 — 자리·설비·공정에 더해 **문서에만 사는 축**(레시피·라우트)까지 있는 모양. */
-const master = (): any => ({
-  source: INSTANCE,
-  system: 'mes',
-  siteName: '항목 공장',
-  space: { width: 80, depth: 40, unit: 'm' },
-  locations: [
-    { id: 'a-floor', type: 'production-line', role: 'area', name: '생산 플로어' },
-    { id: 'cut-station', type: 'cut-station', role: 'location', name: '절단', parentId: 'a-floor', capacity: 20 },
-    { id: 'weld-station', type: 'weld-station', role: 'location', name: '용접', parentId: 'a-floor', capacity: 20 }
-  ],
-  equipment: [
-    { id: 'cutter-1', kind: 'cutter', homeLocationId: 'cut-station', mtbfMs: 3600000 },
-    { id: 'welder-1', kind: 'welder', homeLocationId: 'weld-station' },
-    { id: 'welder-2', kind: 'welder', homeLocationId: 'weld-station' }
-  ],
-  operations: [
-    { key: 'cut', label: '절단', intent: 'process', locationType: 'cut-station', resourceType: 'cutter', duration: 'PT10M' },
-    { key: 'weld', label: '용접', intent: 'process', locationType: 'weld-station', resourceType: 'welder', duration: 'PT20M' }
-  ],
-  productionSpec: {
-    definition: {
-      materials: [{ id: 'steel' }, { id: 'frame' }],
-      routes: [{ key: 'frame-route', steps: ['cut', 'weld'] }],
-      recipes: [{ key: 'frame-recipe', route: 'frame-route', inputs: [{ material: 'steel' }], outputs: [{ material: 'frame' }] }],
-      operations: [
-        { key: 'cut', label: '절단', intent: 'process', locationType: 'cut-station', resourceType: 'cutter', duration: 'PT10M' },
-        { key: 'weld', label: '용접', intent: 'process', locationType: 'weld-station', resourceType: 'welder', duration: 'PT20M' }
-      ]
-    }
-  }
-})
-
-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: 'item-test', subdomain: 'item-test' } as any)
-  domainId = d.id
-  q = new TwinModelItemQuery()
-  ctx = { state: { domain: { id: domainId } } }
-
-  await TwinEngine.ingestMaster(domainId, master(), 'reset')
-})
-
-after(async () => {
-  await TwinEngine.stop(domainId, INSTANCE).catch(() => {})
-  await ds?.destroy()
-})
-
-test('행으로 옮긴 축은 DB 가 페이징하고 그 사실을 밝힌다', async () => {
-  const page1 = await q.twinModelEntities(INSTANCE, 'equipment', ctx, undefined, 0, 2)
-  assert.equal(page1.basis, 'rows', 'DB 가 셌다는 사실이 응답에 있어야 한다')
-  assert.equal(page1.total, 3, '총 건수는 페이지 크기와 무관하게 사실이다')
-  assert.equal(page1.items.length, 2)
-
-  const page2 = await q.twinModelEntities(INSTANCE, 'equipment', ctx, undefined, 2, 2)
-  assert.equal(page2.items.length, 1, '이어 읽을 수 있다')
-  const seen = [...page1.items, ...page2.items].map((i: any) => i.id).sort()
-  assert.deepEqual(seen, ['cutter-1', 'welder-1', 'welder-2'], '두 페이지가 전건을 덮는다')
-})
-
-test('아직 문서에 사는 축도 열린다 — 이주 전이라고 안 보이면 안 된다', async () => {
-  const r = await q.twinModelEntities(INSTANCE, 'recipes', ctx)
-  assert.equal(r.basis, 'document', '문서를 읽어 잘랐다는 사실을 밝힌다(규모 한계가 드러나야 한다)')
-  assert.equal(r.total, 1)
-  assert.deepEqual(r.items.map((i: any) => i.id), ['frame-recipe'])
-})
-
-test('검색이 전수 조회라는 사실을 드러낸다 — 감추면 한계를 아무도 모른다', async () => {
-  const r = await q.twinModelEntities(INSTANCE, 'equipment', ctx, 'weld')
-  assert.equal(r.total, 2)
-  /* 훑어 걸렀다는 사실은 **이 두 칸이** 말한다(근거가 아니라 셈의 한계다). */
-  assert.equal(typeof r.scanned, 'number', '몇 줄을 읽었는지 말하지 않는다')
-  assert.equal(r.truncated, false, '상한에 닿지 않았으면 잘리지 않았다고 말한다')
-  assert.deepEqual(r.items.map((i: any) => i.id).sort(), ['welder-1', 'welder-2'])
-})
-
-test('★ 근거는 계약이 닫아 둔 다섯 안에서만 답한다', async () => {
-  /*
-   * 2026-09-18 판정(ADR-0075 결정 3 을 코드에 대어 본 결과): 검색 갈래가 `'rows-scanned'` 를 냈다.
-   * 그것은 출처가 아니라 우리가 어떻게 셌나이고, 목록 소비자는 계약에 없는 값을 만난다. 출처는
-   * 훑었든 DB 가 골랐든 같은 행이므로 `rows` 다.
-   */
-  const { READ_BASIS } = req('@operato/ops-contract')
-  const answers = [
-    await q.twinModelEntities(INSTANCE, 'equipment', ctx, 'weld'),
-    await q.twinModelEntities(INSTANCE, 'equipment', ctx),
-    await q.twinModelEntities(INSTANCE, 'recipes', ctx)
-  ]
-  for (const a of answers) assert.ok(READ_BASIS.includes(a.basis), `계약 밖의 근거 '${a.basis}'`)
-  assert.equal(answers[0].basis, 'rows', '훑어 세도 값이 온 곳은 행이다')
-})
-
-test('모르는 축은 거절한다 — 빈 목록은 "없다" 로 읽힌다', async () => {
-  await assert.rejects(() => q.twinModelEntities(INSTANCE, 'nosuch', ctx), /unknown concept axis/)
-  await assert.rejects(() => q.twinModelItem(INSTANCE, 'nosuch', 'x', ctx), /unknown concept axis/)
-})
-
-test('항목 하나 — 정체는 카탈로그에서, 선언은 원본에서, 출처가 함께 온다', async () => {
-  const it = await q.twinModelItem(INSTANCE, 'equipment', 'cutter-1', ctx)
-  assert.ok(it, '있는 항목은 열려야 한다')
-  assert.equal(it.identity.typeRole, 'equipment', '표준 역할은 커널 카탈로그가 말한다')
-  assert.equal(it.declared.kind, 'cutter')
-  assert.equal(it.declared.mtbfMs, 3600000)
-  assert.equal(it.provenance.basis, 'rows')
-  assert.equal(it.provenance.sourceRef, INSTANCE, '어느 원본에서 왔는지가 항목에 붙어 있다')
-})
-
-test('비교하지 못했으면 관측은 null 이고, 답했으면 **근거를 알린다**', async () => {
-  const it = await q.twinModelItem(INSTANCE, 'equipment', 'cutter-1', ctx)
-  /*
-   * 이 픽스처에는 저널이 없다(행만 있다) — 되짚을 것이 없으므로 관측은 없다. **0 이나 빈 객체로
-   * 메우면 "관측했는데 아무것도 없었다" 로 읽힌다.**
-   *
-   * 예전 이 검사는 "트윈이 안 돌면 관측은 null" 이었다. 지금은 멈춘 트윈도 저널을 계산해 답할 수 있고,
-   * 그 답이 **자기 근거를 달고 온다**(`observedBasis`). 그래서 규율을 그 자리에 맞춰 다시 적는다:
-   * 답이 없으면 null, 답이 있으면 그것이 라이브인지 되짚은 것인지 말한다. 근거 없는 답은 없다.
-   */
-  assert.equal(it.observed, null, '되짚을 저널이 없으면 관측은 없다')
-  assert.equal(it.observedBasis, undefined, '답이 없으면 근거도 말하지 않는다(빈 답에 근거를 붙이면 견준 것처럼 보인다)')
-})
-
-test('이어진 것은 양방향이고 선언된 관계만 따른다', async () => {
-  const loc = await q.twinModelItem(INSTANCE, 'locations', 'weld-station', ctx)
-
-  /* 들어오는 쪽 — 이 자리를 기준으로 삼는 설비 둘. 선언(`equipment.homeLocation`)이 알려 준다. */
-  const home = loc.links.incoming.find((l: any) => l.via === 'ops.rel.home' && l.from === 'equipment')
-  assert.ok(home, '나를 가리키는 관계가 보여야 한 걸음씩 걸을 수 있다')
-  assert.deepEqual(home.ids.sort(), ['welder-1', 'welder-2'])
-  assert.equal(home.total, 2)
-
-  /* 나가는 쪽 — 자리는 구역을 가리킨다. 대상이 **축 밖**(공간의 구역)이라는 사실을 그대로 낸다. */
-  const area = loc.links.out.find((l: any) => l.via === 'ops.rel.area')
-  assert.ok(area, '커널이 "밖" 이라 부른 참조도 이어진 것으로 낸다')
-  assert.equal(area.target.kind, 'external', '갈 곳이 다르므로 화면이 링크를 만들지 말지 알 수 있어야 한다')
-})
-
-test('문서에만 사는 항목의 관계도 선언대로 이어진다', async () => {
-  const recipe = await q.twinModelItem(INSTANCE, 'recipes', 'frame-recipe', ctx)
-  assert.equal(recipe.provenance.basis, 'document')
-
-  const route = recipe.links.out.find((l: any) => l.via === 'ops.rel.route')
-  assert.deepEqual(route.ids, ['frame-route'])
-
-  /* `inputs[].material` — 배열을 지나는 경로가 선언의 문법이고, 그것을 따르는 것이 선언을 존중하는 것이다. */
-  const input = recipe.links.out.find((l: any) => l.via === 'ops.rel.input')
-  assert.deepEqual(input.ids, ['steel'])
-  const output = recipe.links.out.find((l: any) => l.via === 'ops.rel.output')
-  assert.deepEqual(output.ids, ['frame'])
-})
-
-test('없는 항목은 null — 빈 껍데기를 내주지 않는다', async () => {
-  assert.equal(await q.twinModelItem(INSTANCE, 'equipment', 'no-such-machine', ctx), null)
-})
-
-test('내부 배관은 새어 나가지 않는다 — 사용자가 볼 것은 현장의 사실이지 우리 스키마가 아니다', async () => {
-  /*
-   * 실제로 새었다: `domainId`·`instanceRowId` 같은 내부 UUID 가 속성 패널까지 갔다.
-   * 손으로 제외 목록을 두면 컬럼이 늘 때마다 잊는다 — 관계와 조인 컬럼은 엔티티 메타데이터가 안다.
-   */
-  const INTERNAL = /^(id|domainId?|instanceRowId|areaRowId|homeLocationRowId|createdAt|updatedAt|creator|updater|creatorId|updaterId)$/
-
-  const list = await q.twinModelEntities(INSTANCE, 'locations', ctx)
-  for (const it of list.items)
-    for (const k of Object.keys(it.fields))
-      assert.ok(!INTERNAL.test(k), `목록에 내부 컬럼이 새었다: ${k}`)
-
-  const item = await q.twinModelItem(INSTANCE, 'locations', 'weld-station', ctx)
-  for (const k of Object.keys(item.declared))
-    assert.ok(!INTERNAL.test(k), `속성 패널에 내부 컬럼이 새었다: ${k}`)
-
-  /* 식별자도 두 번 보이지 않는다 — 이미 itemId 로 나간다. */
-  assert.ok(!('locationId' in item.declared), '항목 자신의 id 를 속성으로 또 내지 않는다')
-  /* 출처는 속성이 아니라 근거다. */
-  assert.ok(!('sourceRef' in item.declared) && !('ingestedAt' in item.declared))
-  assert.equal(item.provenance.sourceRef, INSTANCE)
-})
-
-test('지도의 선이 진단이 된다 — 이어진 것뿐 아니라 **끊긴 것**을 센다', async () => {
-  /*
-   * 선이 "선언되었고 양끝이 존재한다" 만 말하면 지도는 그림일 뿐이다. 관계에서 가장 중요한 정보는
-   * 대개 부재다 — 기준 자리가 비어 있는 설비, 없는 자리를 가리키는 설비.
-   */
-  const bad = master()
-  bad.equipment.push({ id: 'ghost-1', kind: 'welder', homeLocationId: 'no-such-station' }) // 끊어진 참조
-  bad.equipment.push({ id: 'floater-1', kind: 'welder' })                                   // 기준 자리 없음
-  await TwinEngine.ingestMaster(domainId, bad, 'reset')
-
-  const sum = await new TwinModelQuery().twinModelSummary(INSTANCE, ctx)
-  const home = sum.edges.find((e: any) => e.from === 'equipment' && e.to === 'locations' && e.via === 'ops.rel.home')
-  assert.ok(home, '설비→자리 선이 있어야 한다')
-  assert.equal(home.linked, 3, '제대로 이어진 설비 셋')
-  assert.equal(home.dangling, 1, '없는 자리를 가리키는 설비 하나 — 가장 나쁜 부류이므로 따로 센다')
-  assert.equal(home.missing, 1, '기준 자리를 말하지 않은 설비 하나')
-
-  /* 선택 관계인지도 함께 온다 — `missing` 이 결손인지 정상인지는 그것으로 갈린다. */
-  assert.equal(home.optional, true)
-})
-
-/*
- * ★ 관측 열이 **자기 근거를 말한다** — 라이브인지 되짚은 것인지.
- *
- * 둘은 같은 모양의 값이라, 근거가 없으면 되짚은 값을 "지금 이렇다" 로 읽는다. 그래서 근거를 실을
- * 자리가 없던 동안에는 멈춘 트윈의 저널을 아예 계산하지 않았다(관측 열이 통째로 `—`). 자리를 만든 뒤의
- * 규율은 하나다: **답하면 근거를 말한다.**
- */
-test('멈춘 트윈도 저널을 계산해 답하고, 그 답은 다시 계산한 값이라고 알린다', async () => {
-  const { WmsKernel, EventJournal } = req('@operato/twin-kernel')
-  const model = {
-    spaceId: 'journal-space',
-    utcOffsetMinutes: 0,
-    /* 커널은 선언 없이 팔레트·문서를 만들지 않는다 — 픽스처 자기 이름공간을 준다. */
-    identity: { namespaces: ['https://twin.test/twin-model-item/journal'] },
-    locations: [
-      { id: 'dock-recv', type: 'dock', capacity: 100 },
-      { id: 'bin-1', type: 'storage', capacity: 20 }
-    ],
-    equipment: [{ id: 'fk-1', kind: 'forklift', homeLocation: 'dock-recv' }]
-  }
-  /* 커널을 실제로 굴려 봉투를 얻는다 — 손으로 지어낸 모양은 검증이 아니다. */
-  const journal = new EventJournal()
-  const k = new WmsKernel('journal-probe')
-  k.onEvent((e: any) => journal.append(e))
-  k.loadTwinModel(model)
-  k.scenario.load({
-    seed: 7,
-    generators: [
-      {
-        kind: 'inbound-arrival',
-        rate: { distribution: 'constant', meanPerHour: 240 },
-        content: { skuMix: [{ gtin: 'urn:epc:idpat:sgtin:0614141.012345.*', weight: 1 }], qtyPerLine: { min: 1, max: 1 } }
-      }
-    ]
-  })
-  k.scenario.start()
-  for (let i = 0; i < 200; i++) k.tick(1000)
-
-  const INST = 'journal-probe'
-  await TwinEngine.provision(domainId, INST, 'wms', model, 'reset')
-  await TwinEngine.persistBatch(domainId, INST, journal.all(), 0)
-  await TwinEngine.stop(domainId, INST).catch(() => {})
-  delete (TwinEngine as any).recovered[`${domainId}:${INST}`]
-
-  const it = await q.twinModelItem(INST, 'equipment', 'fk-1', ctx)
-  assert.ok(it?.observed, '저널이 있으면 멈춘 트윈도 마지막으로 알던 사실을 답할 수 있다')
-  assert.equal(it.observedBasis, 'journal', '라이브가 아니라 되짚은 것이라고 말해야 "지금 이렇다" 로 읽히지 않는다')
-  assert.ok(it.observedRevision > 0, '몇 번째 리비전까지 계산했는지 함께 말한다 — 규모의 한계도 그 수가 말한다')
-})
-
-test('★ 멈춘 트윈을 되세우지 못한 답도 출처가 제 근거와 같다 — 저널을 보러 간 답이 「지금 상태」라고 말하지 않는다', async () => {
-  /*
-   * ADR-0075 결정 3 · 결함 넘김 2026-09-24: 이 갈래만 `provenance.basis` 를 `state` 로 박아 두어, 같은 답이 `basis` 는
-   * `journal` 인데 출처는 `state` 였다. 커널이 멈춰 있고(`isRunning` false) 되세우기도 실패하는 때를 대역으로 세운다.
-   */
-  const { READ_BASIS } = req('@operato/ops-contract')
-  const isRunning = TwinEngine.isRunning
-  const recover = TwinEngine.recover
-  TwinEngine.isRunning = () => false
-  TwinEngine.recover = async () => {
-    throw new Error('nothing to rebuild')
-  }
-  try {
-    /* 상태에서 읽는 축이라야 이 갈래를 지난다(`orders` — 계약이 `source: 'state'` 로 선언). */
-    const it = await q.twinModelItem(INSTANCE, 'orders', 'order-1', ctx)
-    assert.equal(it.observedAbsence, 'not-running', '전제: 못 읽은 갈래다')
-    assert.equal(it.provenance.basis, it.basis, '출처와 근거가 같은 말을 한다')
-    assert.equal(it.provenance.basis, 'journal', '멈춘 트윈은 저널을 보러 갔다')
-    assert.ok(READ_BASIS.includes(it.provenance.basis))
-  } finally {
-    TwinEngine.isRunning = isRunning
-    TwinEngine.recover = recover
-  }
-})

package/test/twin-model-parent-relation-db.test.ts

@@ -1,125 +0,0 @@
-/*
- * A location's parent is another location or an area — the item panel splits them by lookup.
- *
- * Contract 0.9.24 (ops-contract `00a346f`) declares `locations.parentId` as `axis-or-external`: the parent is
- * another location (line · cell · zone) or, when no location has that id, an area of the space. Before this, the
- * declaration said "area" only, so a bin under a zone could not walk to its zone, and a zone could not see the
- * bins under it.
- *
- * What is held here:
- *  - a parent that is a location becomes a link to that location, and nothing of it is sent to the area resolver;
- *  - a parent that is not a location is resolved as an area — only those ids reach the resolver;
- *  - a parent id found nowhere comes back as the resolver answers it (missing), not as an empty relation;
- *  - a zone sees the locations under it as incoming, counted from the document (rows carry no parent location).
- */
-import { test, before, after } from 'node:test'
-import assert from 'node:assert/strict'
-import { createRequire } from 'node:module'
-import type { DataSource } from 'typeorm'
-
-const req = createRequire(import.meta.url)
-const { NamingStrategy, addDataSource, entities: shellEntities, Domain } = req('@things-factory/shell')
-const { entities: authEntities } = req('@things-factory/auth-base')
-const { entities: twinEntities } = req('../dist-server/service/index.js')
-const { TwinEngine } = req('../dist-server/engine/index.js')
-const { TwinModelItemQuery } = req('../dist-server/service/twin-model/twin-model-item-query.js')
-const { registerExternalResolver, clearExternalResolvers } = req('../dist-server/service/twin-model/external-resolver.js')
-const { DataSource: TypeOrmDataSource } = req('typeorm')
-
-let ds: DataSource
-let domainId: string
-let q: any
-let ctx: any
-const asked: string[][] = []
-
-const INSTANCE = 'parent-probe'
-
-const master = (): any => ({
-  source: INSTANCE,
-  system: 'wms',
-  siteName: 'parent site',
-  space: { width: 80, depth: 40, unit: 'm' },
-  locations: [
-    { id: 'hall-a', type: 'storage', role: 'area', name: 'Hall A' },
-    { id: 'zone-1', type: 'storage', role: 'location', name: 'Zone 1', parentId: 'hall-a' },
-    { id: 'bin-1', type: 'storage', role: 'location', name: 'Bin 1', parentId: 'zone-1', capacity: 10 },
-    { id: 'bin-2', type: 'storage', role: 'location', name: 'Bin 2', parentId: 'zone-1', capacity: 10 },
-    { id: 'bin-x', type: 'storage', role: 'location', name: 'Bin X', parentId: 'nowhere', capacity: 10 }
-  ],
-  equipment: [{ id: 'fk-1', kind: 'forklift', homeLocationId: 'zone-1' }]
-})
-
-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: 'parent-test', subdomain: 'parent-test' } as any)
-  domainId = d.id
-  q = new TwinModelItemQuery()
-  ctx = { state: { domain: { id: domainId } } }
-
-  /* A stand-in for the host's area resolver: it records what it was asked and knows one area. */
-  registerExternalResolver({
-    entity: 'space.area',
-    resolve: async (_domainId: string, ids: string[]) => {
-      asked.push([...ids])
-      return ids.map(id => (id === 'hall-a' ? { id, name: 'Hall A' } : { id, missing: true }))
-    }
-  })
-
-  await TwinEngine.ingestMaster(domainId, master(), 'reset')
-})
-
-after(async () => {
-  clearExternalResolvers()
-  await TwinEngine.stop(domainId, INSTANCE).catch(() => {})
-  await ds?.destroy()
-})
-
-const parentLinks = (item: any) => item.links.out.filter((l: any) => l.field === 'parentId')
-
-test('a parent that is a location is a link to that location — none of it goes to the area resolver', async () => {
-  asked.length = 0
-  const bin = await q.twinModelItem(INSTANCE, 'locations', 'bin-1', ctx)
-  const links = parentLinks(bin)
-  assert.equal(links.length, 1, `expected one parent line, got ${JSON.stringify(links)}`)
-  assert.deepEqual(links[0].target, { kind: 'axis', axis: 'locations' })
-  assert.equal(links[0].declaredTarget.kind, 'axis-or-external')
-  assert.deepEqual(links[0].ids, ['zone-1'])
-  assert.deepEqual(asked, [], 'a location parent was sent to the area resolver')
-})
-
-test('a parent that is not a location is resolved as an area — only that id reaches the resolver', async () => {
-  asked.length = 0
-  const zone = await q.twinModelItem(INSTANCE, 'locations', 'zone-1', ctx)
-  const links = parentLinks(zone)
-  assert.equal(links.length, 1)
-  assert.deepEqual(links[0].target, { kind: 'external', entity: 'space.area' })
-  assert.deepEqual(links[0].refs, [{ id: 'hall-a', name: 'Hall A' }])
-  assert.deepEqual(asked, [['hall-a']])
-})
-
-test('a parent found nowhere is said to be missing — not an empty relation', async () => {
-  const bin = await q.twinModelItem(INSTANCE, 'locations', 'bin-x', ctx)
-  const links = parentLinks(bin)
-  assert.equal(links.length, 1)
-  assert.equal(links[0].target.kind, 'external')
-  assert.equal(links[0].total, 1)
-  assert.deepEqual(links[0].refs, [{ id: 'nowhere', missing: true }])
-})
-
-test('a zone sees the locations under it as incoming — counted from the document', async () => {
-  const zone = await q.twinModelItem(INSTANCE, 'locations', 'zone-1', ctx)
-  const under = zone.links.incoming.find((l: any) => l.from === 'locations' && l.field === 'parentId')
-  assert.ok(under, `no incoming parent relation on the zone: ${JSON.stringify(zone.links.incoming.map((l: any) => [l.from, l.field]))}`)
-  assert.deepEqual([...under.ids].sort(), ['bin-1', 'bin-2'])
-  assert.equal(under.total, 2)
-})