@things-factory/headless-twin 10.0.8 → 10.0.10

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

@@ -0,0 +1,275 @@
+/*
+ * ★ 개념 안의 목록과 항목 하나 — **막다른 길을 만들지 않는다.**
+ *
+ * 개념 지도가 숫자만 내면 그 숫자가 막다른 길이다. 인스펙션의 원칙은 "화면에 보이는 모든 식별자는
+ * 그 자신의 상세로 가는 문" 이므로, 셈 다음에 **목록**과 **항목**이 있어야 그 원칙이 성립한다.
+ *
+ * 여기서 지키는 것:
+ *  · 어떻게 셌는지 밝힌다 — 행이면 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())
+})
+
+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.basis, 'rows-scanned', '아직 DB 로 내리지 않았다는 사실이 응답에 있다')
+  assert.equal(r.total, 2)
+  assert.equal(r.truncated, false, '상한에 닿지 않았으면 잘리지 않았다고 말한다')
+  assert.deepEqual(r.items.map((i: any) => i.id).sort(), ['welder-1', 'welder-2'])
+})
+
+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 === 'twin.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 === 'twin.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 === 'twin.rel.route')
+  assert.deepEqual(route.ids, ['frame-route'])
+
+  /* `inputs[].material` — 배열을 지나는 경로가 선언의 문법이고, 그것을 따르는 것이 선언을 존중하는 것이다. */
+  const input = recipe.links.out.find((l: any) => l.via === 'twin.rel.input')
+  assert.deepEqual(input.ids, ['steel'])
+  const output = recipe.links.out.find((l: any) => l.via === 'twin.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)
+
+  const sum = await new TwinModelQuery().twinModelSummary(INSTANCE, ctx)
+  const home = sum.edges.find((e: any) => e.from === 'equipment' && e.to === 'locations' && e.via === 'twin.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,
+    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)
+  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, '몇 번째 리비전까지 접었는지 함께 말한다 — 규모의 한계도 그 수가 말한다')
+})

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

@@ -0,0 +1,176 @@
+/*
+ * ★ 다단 전개(BOM) — **자재가 자재를 품는 트리가 아니다.**
+ *
+ * 표준(ISA-95)이 택한 모양은 자재와 레시피가 번갈아 나오는 그래프다:
+ * 완제품 ←산출— 레시피 —투입→ 부품, 그리고 그 부품이 또 어느 레시피의 산출이면 거기서 다시 내려간다.
+ * 우리 선언(`twin.rel.input`·`twin.rel.output`)이 이미 그 두 홉이므로 **새 선언 없이** 재귀가 된다.
+ *
+ * 여기서 지키는 것:
+ *  · 패턴을 코드가 알지 않는다 — 선언 그래프에서 자기 축으로 돌아오는 순환을 찾는다
+ *  · **조용히 고르지 않는다** — 순환이 여럿이면 후보를 내고 멈춘다(방향이 뒤집힌 전개는
+ *    틀린 답이 아니라 **반대의 답**이라 화면만 보고는 구별되지 않는다)
+ *  · 수량은 곱해 내려가되, **모르면 곱하지 않는다**(1 로 메우면 윗단 합계가 통째로 거짓이 된다)
+ *  · 사이클을 만나면 다시 파지 않고 말한다
+ *  · 상한에서 끊기면 끊겼다고 말한다
+ */
+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 { TwinModelTreeQuery } = req('../dist-server/service/twin-model/twin-model-tree-query.js')
+const { DataSource: TypeOrmDataSource } = req('typeorm')
+
+let ds: DataSource
+let domainId: string
+let q: any
+let ctx: any
+
+const INSTANCE = 'bom-probe'
+
+/**
+ * 3단 BOM — 완제품 → 하위조립 → 원자재.
+ *   trailer  ← trailer-line  ← { frame ×1, axle ×2 }
+ *   frame    ← frame-line    ← { steel ×4 }
+ */
+const master = (extra: any = {}): any => ({
+  source: INSTANCE,
+  system: 'mes',
+  siteName: 'BOM 공장',
+  space: { width: 60, depth: 30, unit: 'm' },
+  locations: [{ id: 'line', type: 'weld-station', role: 'location', capacity: 10 }],
+  equipment: [{ id: 'welder-1', kind: 'welder', homeLocationId: 'line' }],
+  productionSpec: {
+    definition: {
+      materials: [{ id: 'trailer' }, { id: 'frame' }, { id: 'axle' }, { id: 'steel' }],
+      recipes: [
+        { key: 'trailer-line', label: '트레일러', inputs: [{ material: 'frame', qty: 1 }, { material: 'axle', qty: 2 }], outputs: [{ material: 'trailer', qty: 1 }] },
+        { key: 'frame-line', label: '프레임', inputs: [{ material: 'steel', qty: 4 }], outputs: [{ material: 'frame', qty: 1 }] }
+      ],
+      ...extra
+    }
+  }
+})
+
+const explode = (itemId: string, opts: any = {}) =>
+  q.twinModelTree(INSTANCE, 'materials', itemId, ctx, 'twin.rel.output', 'twin.rel.input', opts.maxDepth, opts.maxItems)
+
+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: 'bom-test', subdomain: 'bom-test' } as any)
+  domainId = d.id
+  q = new TwinModelTreeQuery()
+  ctx = { state: { domain: { id: domainId } } }
+  await TwinEngine.ingestMaster(domainId, master())
+})
+
+after(async () => {
+  await TwinEngine.stop(domainId, INSTANCE).catch(() => {})
+  await ds?.destroy()
+})
+
+test('다단으로 내려간다 — 자재가 자재를 품지 않아도 전개된다', async () => {
+  const t = await explode('trailer')
+  const byDepth = (n: number) => t.items.filter((x: any) => x.depth === n).map((x: any) => x.id).sort()
+
+  assert.deepEqual(byDepth(0), ['trailer'])
+  assert.deepEqual(byDepth(1), ['axle', 'frame'], '레시피를 거쳐 1단이 나온다')
+  assert.deepEqual(byDepth(2), ['steel'], '프레임이 또 어느 레시피의 산출이므로 거기서 더 내려간다')
+})
+
+test('수량을 곱해 내려간다 — 그리고 모르면 곱하지 않는다', async () => {
+  const t = await explode('trailer')
+  const qty = (id: string) => t.items.find((n: any) => n.id === id)?.qty
+  assert.equal(qty('frame'), 1)
+  assert.equal(qty('axle'), 2)
+  assert.equal(qty('steel'), 4, '프레임 1개당 강재 4 → 트레일러 1대당 4')
+  assert.equal(t.qtyIncomplete, false)
+
+  /* 수량이 빠진 선언이 섞이면 그 아래 합계는 성립하지 않는다 — 1 로 메우지 않고 그렇게 말한다. */
+  const noQty = master({
+    recipes: [
+      { key: 'trailer-line', label: 't', inputs: [{ material: 'frame' }], outputs: [{ material: 'trailer', qty: 1 }] },
+      { key: 'frame-line', label: 'f', inputs: [{ material: 'steel', qty: 4 }], outputs: [{ material: 'frame', qty: 1 }] }
+    ]
+  })
+  await TwinEngine.ingestMaster(domainId, noQty)
+  const t2 = await explode('trailer')
+  assert.equal(t2.items.find((n: any) => n.id === 'frame').qty, null, '모르는 수량을 1 로 메우지 않는다')
+  assert.equal(t2.items.find((n: any) => n.id === 'steel').qty, null, '모르는 값 아래는 전부 모르는 값이다')
+  assert.equal(t2.qtyIncomplete, true, '합계가 성립하지 않는다는 사실을 낸다')
+
+  await TwinEngine.ingestMaster(domainId, master())
+})
+
+test('역전개도 같은 선언으로 — 방향만 뒤집는다', async () => {
+  /* "이 강재를 쓰는 것은 무엇인가" — 투입으로 들어와 산출로 나간다. */
+  const up = await q.twinModelTree(INSTANCE, 'materials', 'steel', ctx, 'twin.rel.input', 'twin.rel.output')
+  assert.deepEqual(up.items.filter((n: any) => n.depth === 1).map((n: any) => n.id), ['frame'])
+  assert.deepEqual(up.items.filter((n: any) => n.depth === 2).map((n: any) => n.id), ['trailer'])
+})
+
+test('방향을 안 고르면 아무것도 펼치지 않는다 — 뒤집힌 전개는 틀린 답이 아니라 반대의 답이다', async () => {
+  const t = await q.twinModelTree(INSTANCE, 'materials', 'trailer', ctx)
+  assert.equal(t.reason, 'ambiguous-pattern')
+  assert.equal(t.items.length, 0, '한쪽을 집으면 아무도 모른 채 반대 답을 본다')
+  assert.ok(t.patterns.length >= 2, '고를 수 있게 후보를 낸다')
+})
+
+test('어떤 순환을 따라 펼쳤는지 밝힌다 — 화면만 보고는 방향을 구별할 수 없다', async () => {
+  const t = await explode('trailer')
+  assert.equal(t.pattern.inVia, 'twin.rel.output')
+  assert.equal(t.pattern.outVia, 'twin.rel.input')
+  assert.equal(t.pattern.through, 'recipes')
+})
+
+test('사이클은 다시 탐색하지 않고 알린다', async () => {
+  /* 강재가 트레일러에서 나온다고 선언하면(재활용) 그래프가 순환한다. 파고 들면 돌아 나오지 못한다. */
+  const loop = master({
+    recipes: [
+      { key: 'trailer-line', label: 't', inputs: [{ material: 'frame', qty: 1 }], outputs: [{ material: 'trailer', qty: 1 }] },
+      { key: 'frame-line', label: 'f', inputs: [{ material: 'trailer', qty: 1 }], outputs: [{ material: 'frame', qty: 1 }] }
+    ]
+  })
+  await TwinEngine.ingestMaster(domainId, loop)
+  const t = await explode('trailer')
+  assert.ok(t.items.length < 10, '무한히 자라지 않는다')
+  assert.ok(t.cycles.length > 0, '사이클을 만났다는 사실을 말한다')
+  await TwinEngine.ingestMaster(domainId, master())
+})
+
+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), [], '깊이 상한 아래는 안 판다')
+  /* 너비 우선이라 **얕은 층은 온전하다** — 깊이 우선이면 한 가지만 깊게 파고 끊긴다. */
+  assert.deepEqual(shallow.items.filter((n: any) => n.depth === 1).map((n: any) => n.id).sort(), ['axle', 'frame'])
+})
+
+test('선언에 없는 자재를 참조하면 그 사실이 드러난다', async () => {
+  const ghost = master({
+    recipes: [
+      { key: 'trailer-line', label: 't', inputs: [{ material: 'no-such-part', qty: 1 }], outputs: [{ material: 'trailer', qty: 1 }] }
+    ]
+  })
+  await TwinEngine.ingestMaster(domainId, ghost)
+  const t = await explode('trailer')
+  const child = t.items.find((n: any) => n.id === 'no-such-part')
+  assert.ok(child, '가리켜진 것은 그리되')
+  assert.equal(child.known, false, '선언에 없다는 사실을 함께 낸다(있는 척하지 않는다)')
+  await TwinEngine.ingestMaster(domainId, master())
+})

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

@@ -0,0 +1,114 @@
+/*
+ * ★ 트윈은 자기 원본을 기억한다 — **기억하지 않으면 다시 읽을 수 없다.**
+ *
+ * 트윈은 원본을 비출 뿐이므로(ADR-0028) 원본이 달라지면 다시 읽어야 한다. 그런데 트윈은
+ * "내가 무엇에서 나왔나" 를 남기지 않았다 — 어댑터로 들어온 트윈에는 `TwinReference` 행이
+ * 있었지만 템플릿으로 세운 트윈에는 아무 표식도 없었다. 그 트윈은 **첫날의 모습에 영원히
+ * 머문다.** 실제로 이 앱의 트윈 둘이 그 상태였다(`twinReferences` 도 비었고 `source` 도 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 { TwinInstance } = req('../dist-server/service/twin-instance/twin-instance.js')
+const { DataSource: TypeOrmDataSource } = req('typeorm')
+
+let ds: DataSource
+let domainId: string
+
+const BORN = 'origin-probe'
+const ORPHAN = 'orphan-probe'
+
+const master = (source: string, bins: number, origin?: any): any => ({
+  source,
+  system: 'wms',
+  siteName: '원천 창고',
+  space: { width: 40, depth: 20, unit: 'm' },
+  locations: [
+    { id: 'dock-recv', type: 'dock', role: 'location', name: '입고 도크', capacity: 100 },
+    ...Array.from({ length: bins }, (_, i) => ({ id: `bin-${i + 1}`, type: 'storage', role: 'location', name: `빈${i + 1}`, capacity: 20 }))
+  ],
+  equipment: [{ id: 'fk-1', kind: 'forklift', homeLocationId: 'dock-recv' }],
+  ...(origin ? { origin } : {})
+})
+
+const originOf = async (instanceId: string) =>
+  (await ds.getRepository(TwinInstance).findOne({ where: { instanceId } }))?.origin
+
+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: 'origin-test', subdomain: 'origin-test' } as any)
+  domainId = d.id
+})
+
+after(async () => {
+  for (const id of [BORN, ORPHAN]) await TwinEngine.stop(domainId, id).catch(() => {})
+  await ds?.destroy()
+})
+
+test('인제스트가 원천을 각인한다 — 원천이 무엇이든 한 자리에', async () => {
+  await TwinEngine.ingestMaster(domainId, master(BORN, 3, { kind: 'template', templateId: 'wh-unit-load', params: { bins: 3 } }))
+  assert.deepEqual(await originOf(BORN), { kind: 'template', templateId: 'wh-unit-load', params: { bins: 3 } })
+})
+
+test('원천을 모르는 재프로비전이 이미 아는 것을 지우지 않는다 — 한 번 지우면 다시 못 읽는다', async () => {
+  /*
+   * 이 경로는 실제로 있다 — 원천을 모르는 호출자(스크립트·복구·옛 코드)가 같은 트윈을 다시
+   * 인제스트한다. 그때 `origin` 을 덮어 비우면 그 트윈은 **조용히 다시 읽을 수 없게 된다.**
+   * 그런 종류의 손상은 다음번에 다시 읽으려 할 때까지 아무도 모른다.
+   */
+  await TwinEngine.ingestMaster(domainId, master(BORN, 5))
+  assert.deepEqual(
+    await originOf(BORN),
+    { kind: 'template', templateId: 'wh-unit-load', params: { bins: 3 } },
+    '원천을 말하지 않은 인제스트는 기존 원천을 보존한다'
+  )
+
+  const inst = await ds.getRepository(TwinInstance).findOne({ where: { instanceId: BORN } })
+  assert.equal(inst.model.locations.length, 6, '구조 자체는 새 마스터로 갱신된다(도크 1 + 빈 5)')
+})
+
+test('새 원천을 말하면 갱신된다 — 보존은 침묵에만 적용된다', async () => {
+  await TwinEngine.ingestMaster(domainId, master(BORN, 5, { kind: 'reference', source: 'oracle-wms' }))
+  assert.deepEqual(await originOf(BORN), { kind: 'reference', source: 'oracle-wms' })
+})
+
+test('원천 없이 태어난 트윈은 원천이 없다 — 짐작해 채우지 않는다', async () => {
+  await TwinEngine.ingestMaster(domainId, master(ORPHAN, 2))
+  assert.equal(await originOf(ORPHAN), null, '모르는 것을 아는 척하면 엉뚱한 원본으로 현장을 덮는다')
+})
+
+test('조회가 다시 읽을 수 있는지를 먼저 답한다 — 못 하는 것을 못 한다고 알린다', async () => {
+  const { TwinModelQuery } = req('../dist-server/service/twin-model/twin-model-query.js')
+  const q = new TwinModelQuery()
+  const ctx = { state: { domain: { id: domainId } } } as any
+
+  const born = await q.twinModelSummary(BORN, ctx)
+  assert.equal(born.canResync, true)
+  assert.deepEqual(born.origin, { kind: 'reference', source: 'oracle-wms' })
+
+  const orphan = await q.twinModelSummary(ORPHAN, ctx)
+  assert.equal(orphan.canResync, false, '버튼을 그대로 내면 누를 때마다 실패한다')
+  assert.equal(orphan.origin, null)
+})