@things-factory/headless-twin 10.0.9 → 10.0.11

package/test/oee-accumulator.test.ts

@@ -8,7 +8,7 @@ import assert from 'node:assert/strict'
 
 import { WmsKernel, StateProjector } from '@operato/twin-kernel'
 import { masterToTwin } from '../server/service/reference/reference-master.ts'
-import { buildEntityDeltas } from '../server/engine/entity-delta.ts'
+import { buildEntityDeltas } from '../shared/entity-delta.ts'
 import { OeeAccumulator, withLiveOee } from '../server/engine/oee-accumulator.ts'
 
 const BASE_EPOCH = Date.parse('2026-01-01T00:00:00Z') // 커널 now() 고정 오프셋(flow-engine BASE_EPOCH)
@@ -28,15 +28,15 @@ function runSimCollect() {
     ],
     equipment: [{ id: 'fk-1', kind: 'forklift', homeLocationId: 'dock-recv', mtbfMs: 5000, mttrMs: 8000 }]
   }
-  const board = masterToTwin(m).board
+  const model = masterToTwin(m).model
   const k = new WmsKernel('t')
   const events: any[] = []
   k.onEvent((e: any) => events.push(e))
-  k.loadBoard(board)
+  k.loadTwinModel(model)
   k.scenario.load({ seed: 9, generators: [{ kind: 'inbound-arrival', rate: { distribution: 'constant', meanPerHour: 300 }, content: { skuMix: [{ gtin: GTIN, weight: 1 }], qtyPerLine: { min: 1, max: 1 } } }] })
   k.scenario.start()
   for (let i = 0; i < 200; i++) k.tick(TICK)
-  return { events, snap: k.getSnapshot() as any, board }
+  return { events, snap: k.getSnapshot() as any, model }
 }
 
 test('★ OEE 누적기: downMs 정확 · busyMs=run+setup · 근사 OEE 유효', () => {
@@ -83,8 +83,8 @@ test('★ OEE 누적기: quality.output 델타 소비 → quality 정확 (good/s
 })
 
 test('★ withLiveOee: projector 미러(oee 없음) + 누적기 → live 설비 payload 에 oee 포함 (원 갭 종료)', () => {
-  const { events, board } = runSimCollect()
-  const proj = new StateProjector(board)
+  const { events, model } = runSimCollect()
+  const proj = new StateProjector(model)
   const acc = new OeeAccumulator()
   for (const e of events) { proj.apply(e); acc.apply(e) }
 
@@ -111,7 +111,7 @@ test('★ withLiveOee: projector 미러(oee 없음) + 누적기 → live 설비
  * 태운다 — 이 테스트는 그 재계산이 라이브와 **같은 값**을 내는지, 그리고 시간여행에서 **그 시점까지만**
  * 세는지를 못 박는다.
  */
-test('★ 저널을 다시 태우면 라이브와 같은 계측이 나온다 — 규칙이 한 벌이므로', () => {
+test('★ 저널을 다시 태우면 라이브와 같은 계측이 나온다 — 규칙이 하나이므로', () => {
   const T0 = Date.parse('2026-08-05T00:00:00.000Z')
   const ev = (ms: number, id: string, status: string) => ({
     eventId: `e${ms}`,
@@ -164,3 +164,22 @@ test('★ 계측 시점을 벽시계로 재지 않는다 — 과거 화면의
   const atMuchLater = acc.oee('fk-1', T0 + 10_000_000)
   assert.notDeepEqual(atThen, atMuchLater, '시점을 넘기면 값이 달라진다 — 그래서 그 화면의 시각을 넘겨야 한다')
 })
+
+/*
+ * ★ 못 본 설비의 계측 창 — **없으면 없다고 한다.**
+ *
+ * 예전에는 `metricsSinceMs: 0` 을 돌려줬다. 시각이 epoch 밀리초라서 그 창은 곧 "1970년부터" 가 되고,
+ * 공식의 분모가 지금 시각 전체가 된다 — 화면에 `idleMs 1767226603000`(약 56,000년) 유휴가 섰다.
+ * 그 값은 availability·overall 의 분모이기도 해서 **성과 숫자 전체가 조용히 거짓**이 됐다.
+ */
+test('이벤트를 못 본 설비는 계측 창을 만들지 않는다 — epoch 를 창으로 삼지 않는다', () => {
+  const acc = new OeeAccumulator()
+  const c = acc.counters('never-seen', Date.parse('2026-01-01T00:00:00.000Z'))
+  assert.equal(c.metricsSinceMs, undefined, '모르는 창을 0 으로 메우면 1970년부터 쟀다는 말이 된다')
+
+  /*
+   * 그다음(창이 없을 때 유휴는 0)은 **공식의 책임**이고 공식은 커널에 있다 — 커널의
+   * `test/oee-window` 가 못 박는다. 여기서 그 결과까지 단정하면 이 검사는 커널 발행 시점에
+   * 묶이고, 남의 책임을 자기 검사에 넣은 것이 된다.
+   */
+})

package/test/operation-basis.test.ts

@@ -0,0 +1,100 @@
+/*
+ * 공정 목록 — **무엇을 돌리고, 그 시간이 어디서 오나.**
+ *
+ * ── 왜 이 목록이 필요한가 (2026-08-18) ─────────────────────────────────────
+ * 「측정이 없을 때의 표준 시간」을 현장이 선언하려면 먼저 무엇에 선언할지 보여야 한다. 그런데 실측으로
+ * 운영 중인 트윈 35개 중 **창고·야드는 공정 명세 행이 0개**였다 — 모델만 보면 「공정이 없다」로 읽힌다.
+ * 실제로는 `putaway`·`spot` 을 돌리고 있고, 그 사실은 **커널만 안다**(`specCoverage`).
+ *
+ * 그래서 이 모듈이 지키는 것:
+ *  ① 목록을 지어내지 않는다 — 원천 행·커널 보고·우리 선언, 세 곳에서만 모은다.
+ *  ② 돌지 않은 트윈에서 「공정이 없다」고 말하지 않는다 — `basis` 가 비는 것으로 모름을 드러낸다.
+ *  ③ 선언해 둔 공정이 목록에서 사라지지 않는다(그러면 철회할 자리가 없어진다).
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+import { operationBasis, knownOperationKinds } from '../server/engine/operation-basis.ts'
+
+/** 커널 흉내 — 자기보고만 낸다(이 모듈이 커널에서 읽는 것은 그것뿐이다). */
+const kernelReporting = (ops: { kind: string; duration: 'measured' | 'declared' | 'default' }[]) => ({
+  specCoverage: () => ({
+    operations: ops.map(o => ({ ...o, parameters: [] })),
+    measuredDurations: ops.filter(o => o.duration === 'measured').length,
+    declaredDurations: ops.filter(o => o.duration === 'declared').length,
+    defaultDurations: ops.filter(o => o.duration === 'default').length
+  })
+})
+
+test('행이 없는 트윈에서도 돌린 공정이 나온다 — 창고·야드가 바로 그 경우다', () => {
+  const rows = operationBasis({ locations: [], equipment: [] }, kernelReporting([{ kind: 'putaway', duration: 'default' }]))
+  assert.deepEqual(rows, [{ kind: 'putaway', basis: 'default' }])
+})
+
+test('원천 명세 행은 이름과 시간을 함께 든다 — 우리 선언이 그것을 이긴다', () => {
+  const model = { operations: [{ key: 'weld', label: 'Welding', intent: 'process', duration: 'PT90S' }], localDurations: { weld: 'PT60S' } }
+  const rows = operationBasis(model, kernelReporting([{ kind: 'weld', duration: 'declared' }]))
+  assert.deepEqual(rows, [{ kind: 'weld', label: 'Welding', referenceDuration: 'PT90S', basis: 'declared', localDuration: 'PT60S' }])
+})
+
+test('정지 트윈은 basis 가 빈다 — 「공정이 없다」가 아니라 「모른다」다', () => {
+  const rows = operationBasis({ operations: [{ key: 'pick', label: 'Pick' }] }, undefined)
+  assert.deepEqual(rows, [{ kind: 'pick', label: 'Pick' }])
+  assert.equal(rows[0].basis, undefined)
+})
+
+test('선언해 둔 공정은 커널이 아직 돌리지 않아도 목록에 남는다 — 철회할 자리가 사라지지 않게', () => {
+  const rows = operationBasis({ localDurations: { spot: 'PT300S' } }, kernelReporting([]))
+  assert.deepEqual(rows, [{ kind: 'spot', localDuration: 'PT300S' }])
+})
+
+test('아무 근거도 없으면 목록을 지어내지 않는다 — 빈 배열이다', () => {
+  assert.deepEqual(operationBasis({}, undefined), [])
+})
+
+test('확인 목록은 하나도 없을 때 undefined 다 — 빈 배열은 「아무것도 안 된다」로 읽힌다', () => {
+  assert.equal(knownOperationKinds({}, undefined), undefined)
+  assert.deepEqual(knownOperationKinds({}, kernelReporting([{ kind: 'putaway', duration: 'default' }])), ['putaway'])
+})
+
+test('커널이 보고하지 못해도 터지지 않는다 — 옛 커널에서도 목록은 나온다', () => {
+  const rows = operationBasis({ operations: [{ key: 'pick', label: 'Pick' }] }, { tick: () => {} })
+  assert.deepEqual(rows, [{ kind: 'pick', label: 'Pick' }])
+})
+
+/*
+ * ── 재기동 직후의 빈칸 (2026-08-18 실측) ────────────────────────────────────
+ * 커널의 자기보고는 **작업이 새로 생길 때** 채워진다. 그래서 이력이 풍부한 창고 트윈(pick·putaway 를
+ * 이미 배운 트윈)도 재기동 직후에는 목록이 비었다 — 값을 채울 곳을 보여야 하는 화면이 그때 아무 말도
+ * 못 한다. 이력에서 배운 종류를 넷째 근거로 넣어 그 빈칸을 메운다.
+ */
+test('이력에서 배운 종류가 목록에 나온다 — 재기동 직후에도 빈칸이 아니다', () => {
+  const rows = operationBasis({}, kernelReporting([]), ['pick', 'putaway'])
+  assert.deepEqual(rows, [{ kind: 'pick', basis: 'measured' }, { kind: 'putaway', basis: 'measured' }])
+})
+
+test('커널이 실제로 돌린 사실이 이력 목록을 덮지 않는다 — 더 강한 사실이 이긴다', () => {
+  const rows = operationBasis({}, kernelReporting([{ kind: 'putaway', duration: 'default' }]), ['putaway'])
+  assert.deepEqual(rows, [{ kind: 'putaway', basis: 'default' }], '지금 상수로 돌고 있으면 그렇게 말한다')
+})
+
+test('이력 목록은 선언 대조에도 쓰인다 — 오타를 그때부터 잡는다', () => {
+  assert.deepEqual(knownOperationKinds({}, undefined, ['pick']), ['pick'])
+})
+
+/*
+ * ── 도는 시뮬레이션은 「저장했다」가 아니다 (2026-08-18 실측) ────────────────
+ * 시뮬 기동 경로가 `mode` 를 비워 두어(「미지정=sim」 규약에 기대) `modeOf()` 가 도는 트윈에 undefined 를
+ * 답했다. 그래서 선언·철회의 답이 「저장했다」로 나갔다 — 실제로는 도는 커널이 옛 수를 쓰고 재기동 때
+ * 받는데, 사용자는 지금 화면의 수가 새 값으로 계산된 줄로 읽는다. 사실을 적는 쪽으로 고쳤다.
+ */
+test('시뮬 기동이 모드를 적는다 — 「돌고 있나」를 묻는 쪽이 답을 받아야 한다', () => {
+  const src = readFileSync(fileURLToPath(new URL('../server/engine/twin-engine.ts', import.meta.url)), 'utf-8')
+  assert.match(src, /id, domainId, mode: 'sim', runtime/, '시뮬 런타임도 모드를 든다')
+  /* 답이 갈리는 자리 — 도는 트윈이면 「재기동 때 받는다」로 말해야 한다. */
+  const mut = readFileSync(fileURLToPath(new URL('../server/service/twin-model/twin-model-mutation.ts', import.meta.url)), 'utf-8')
+  assert.match(mut, /running \? 'on-restart' : 'stored'/)
+})

package/test/operations-capability-db.test.ts

@@ -0,0 +1,165 @@
+/*
+ * ★ 생산 능력 질의 — **트윈 하나를 두고 "지금 더 받을 수 있나" 를 물을 길.**
+ *
+ * 커널이 계산과 표준 등식을 지킨다(kernel/test/operations-capability). 이 검사가 지키는 것은 그 앞의
+ * 배선이다 — 그리고 여기서 지켜야 할 규율은 `twinCapacity` 와 같다:
+ *
+ *  · **대상은 등록부가 정한다** — 떠 있는 런타임만 훑으면 "안 떠 있어서 안 보이는 것" 과 "없는 것" 이
+ *    구별되지 않는다. 화면은 그 둘을 다르게 말해야 한다.
+ *  · **공정을 선언하지 않은 트윈은 판정 대상이 아니다** — 0 으로 채우면 "야드가 병목" 이라는 없는
+ *    사실이 생긴다.
+ *  · **구간은 부르는 쪽이 말한다** — 기본값을 두면 화면마다 다른 구간을 보면서 같은 값으로 읽는다.
+ */
+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 { TwinJournalQuery } = req('../dist-server/service/twin-journal/twin-journal-query.js')
+const { DataSource: TypeOrmDataSource } = req('typeorm')
+
+let ds: DataSource
+let domainId: string
+let q: any
+let ctx: any
+
+const MES = 'cap-mes'
+const WMS = 'cap-wms'
+const WINDOW = { fromTime: '2026-01-05T00:00:00.000Z', toTime: '2026-01-06T00:00:00.000Z' }
+
+/** 절단 하나 — 설비 2대·사람 2명, 사이클 1시간. 24시간 창이면 상한 48대. */
+const mesMaster = (): any => ({
+  source: MES,
+  system: 'mes',
+  siteName: '능력 공장',
+  space: { spaceId: 'cap-site', width: 60, depth: 40, unit: 'm' },
+  locations: [
+    { id: 'raw-store', type: 'raw-store', role: 'location', name: '자재 보관', capacity: 100 },
+    { id: 'cut-station', type: 'cut-station', role: 'location', name: '절단', capacity: 10 },
+    { id: 'fg-store', type: 'fg-store', role: 'location', name: '완제품', capacity: 100 }
+  ],
+  equipment: [
+    { id: 'cutter-1', kind: 'cutter', homeLocationId: 'cut-station' },
+    { id: 'cutter-2', kind: 'cutter', homeLocationId: 'cut-station' }
+  ],
+  personnelClasses: [{ id: 'cutter-op', description: '절단 작업자' }],
+  persons: [
+    { id: 'c-1', personnelClassIds: ['cutter-op'], homeLocationId: 'cut-station' },
+    { id: 'c-2', personnelClassIds: ['cutter-op'], homeLocationId: 'cut-station' }
+  ],
+  operations: [
+    {
+      key: 'cut', label: '절단', intent: 'process', locationType: 'cut-station', resourceType: 'cutter',
+      duration: 'PT1H',
+      equipmentSpecification: [{ equipmentClass: 'cutter', quantity: 1 }],
+      personnelSpecification: [{ personnelClass: 'cutter-op', quantity: 1 }]
+    }
+  ],
+  productionSpec: {
+    /* 레시피 생산은 자재 키를 GS1 로 풀 수 있어야 한다 — 커널이 없으면 기동을 거절한다(정확한 거절이다). */
+    companyPrefix: '0614141',
+    binding: { steel: '077101', frame: '078101' },
+    definition: {
+      materials: [{ id: 'steel' }, { id: 'frame' }],
+      routes: [{ key: 'r', steps: ['cut'] }],
+      recipes: [{ key: 'rc', label: '프레임', route: 'r', inputs: [{ material: 'steel', qty: 1 }], outputs: [{ material: 'frame', qty: 1 }] }]
+    }
+  }
+})
+
+/** 공정을 선언하지 않는 창고 — 판정 대상이 아님을 확인하는 대조군. */
+const wmsMaster = (): any => ({
+  source: WMS,
+  system: 'wms',
+  siteName: '능력 창고',
+  space: { spaceId: 'cap-wh', width: 40, depth: 30, unit: 'm' },
+  locations: [
+    { id: 'dock', type: 'dock', role: 'location', name: '도크', capacity: 50 },
+    { id: 'bin-1', type: 'storage', role: 'location', name: '빈1', capacity: 20 }
+  ],
+  equipment: [{ id: 'fk-1', kind: 'forklift', homeLocationId: 'dock' }]
+})
+
+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: 'cap-test', subdomain: 'cap-test' } as any)
+  domainId = d.id
+  q = new TwinJournalQuery()
+  ctx = { state: { domain: { id: domainId } } }
+
+  await TwinEngine.ingestMaster(domainId, mesMaster())
+  await TwinEngine.ingestMaster(domainId, wmsMaster())
+})
+
+after(async () => {
+  for (const id of [MES, WMS]) await TwinEngine.stop(domainId, id).catch(() => {})
+  await ds?.destroy()
+})
+
+const ask = (instanceId: string) =>
+  q.twinOperationsCapability(instanceId, undefined, 24, WINDOW.fromTime, WINDOW.toTime, WINDOW.fromTime, ctx)
+
+test('실행 중이 아니면 그 사실을 알린다 — "없는 것" 과 구별된다', async () => {
+  const rows = await ask(MES)
+  assert.equal(rows.length, 1, '등록부에 있으면 목록에 선다(떠 있지 않아도)')
+  assert.equal(rows[0].reason, 'not-running')
+  assert.equal(rows[0].report, undefined, '값을 지어내지 않는다')
+})
+
+test('돌고 있으면 구간의 양을 종류로 갈라 낸다 — 표준 등식이 성립한다', async () => {
+  await TwinEngine.startFromRegistry(domainId, MES, 'sim-experiment')
+  const rows = await ask(MES)
+  assert.equal(rows[0].reason, undefined)
+
+  const report = rows[0].report
+  assert.equal(report.operationsType, 'Production', '표준 열거값을 그대로 낸다')
+  assert.equal(report.window.fromTime, WINDOW.fromTime)
+  assert.equal(report.window.workingHours, 24, '캘린더 선언이 없으면 종일 가동으로 본다')
+
+  const cut = report.perOperation.find((o: any) => o.operation === 'cut')
+  assert.ok(cut, '선언한 공정이 보고서에 있어야 한다')
+  assert.equal(cut.total, 48, '설비 2대·사람 2명·사이클 1시간 → 하루 48대')
+  assert.equal(cut.total, cut.committed + cut.available + cut.unattainable, 'Total = Committed + Available + Unattainable')
+})
+
+test('공정을 선언하지 않은 트윈은 판정 대상이 아니다 — 0 으로 채우면 없는 병목이 생긴다', async () => {
+  await TwinEngine.startFromRegistry(domainId, WMS, 'sim-experiment')
+  const rows = await q.twinOperationsCapability(WMS, undefined, 24, WINDOW.fromTime, WINDOW.toTime, WINDOW.fromTime, ctx)
+  assert.equal(rows[0].reason, 'no-operations')
+  assert.equal(rows[0].report, undefined)
+})
+
+test('구간은 호출하는 쪽이 지정한다 — 뒤집힌 구간·잘못된 시각은 거절한다', async () => {
+  await assert.rejects(
+    () => q.twinOperationsCapability(MES, undefined, 24, WINDOW.toTime, WINDOW.fromTime, undefined, ctx),
+    /inverted/
+  )
+  await assert.rejects(
+    () => q.twinOperationsCapability(MES, undefined, 24, 'not-a-time', WINDOW.toTime, undefined, ctx),
+    /valid ISO time/
+  )
+  await assert.rejects(() => q.twinOperationsCapability(MES, undefined, 0, WINDOW.fromTime, WINDOW.toTime, undefined, ctx))
+})
+
+test('남의 테넌트 트윈은 열리지 않는다 — 능력은 현장의 사실이다', async () => {
+  const other = { state: { domain: { id: 'no-such-domain' } } }
+  await assert.rejects(
+    () => q.twinOperationsCapability(MES, undefined, 24, WINDOW.fromTime, WINDOW.toTime, undefined, other),
+    /not found in this tenant/
+  )
+})

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

@@ -0,0 +1,226 @@
+/*
+ * 구조 투영 — `TwinModelDef`(커널 입력 문서) → **표준 엔티티 행**(ADR-0032).
+ *
+ * ── 왜 DB 검사인가 ─────────────────────────────────────────────────────────
+ * 이 코드의 값어치는 **DB 가 대신 지켜 주는 것**에 있다 — 끊어진 참조를 FK 가 막고, 원본 없는 행을
+ * NOT NULL 이 막는다. 순수 함수 검사로는 그게 하나도 확인되지 않는다. 그래서 실제 DataSource 를
+ * 세운다(멀티DB 규약상 sqlite 로 도는 것이 5개 드라이버 공통의 최소선이기도 하다).
+ *
+ * ── 이 검사가 지키는 것 ────────────────────────────────────────────────────
+ *  · 문서의 세 축이 행으로 선다
+ *  · 설비→자리가 **진짜 FK** 로 이어진다(문자열 대조가 아니라)
+ *  · 끊어진 참조는 **이름을 대고 보고**되고, 행 자체는 남는다(막지 않되 침묵하지 않는다)
+ *  · **전량 교체** — 두 번 돌려도 늘지 않고, 원본에서 사라진 것은 행에서도 사라진다
+ *  · 원본 표식(`sourceRef`·`ingestedAt`) 없는 행은 만들 수 없다(캐시라는 사실이 구조로 지켜진다)
+ *  · 소요시간은 ISO 8601 **문자열 그대로** 남는다(분으로 접으면 초가 조용히 사라진다)
+ */
+import { test, before, after, beforeEach } 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 { projectStructure } = req('../dist-server/service/twin-model/project-structure.js')
+const { TwinInstance } = req('../dist-server/service/twin-instance/twin-instance.js')
+const { TwinSpace } = req('../dist-server/service/twin-space/twin-space.js')
+const { TwinArea } = req('../dist-server/service/twin-space/twin-area.js')
+const { TwinLocation } = req('../dist-server/service/twin-model/twin-location.js')
+const { TwinEquipment } = req('../dist-server/service/twin-model/twin-equipment.js')
+const { TwinOperation } = req('../dist-server/service/twin-model/twin-operation.js')
+const { DataSource: TypeOrmDataSource } = req('typeorm')
+
+let ds: DataSource
+let domainId: string
+
+const INSTANCE = 'projection-probe'
+const SOURCE = 'projection-probe'
+
+/** 실제 트레일러 트윈과 같은 모양의 문서(축소판). */
+const model = () => ({
+  locations: [
+    { id: 'cut-station', type: 'cut-station', name: '프레임 절단', capacity: 20, parentId: 'a-floor' },
+    { id: 'weld-station', type: 'weld-station', capacity: 20, parentId: 'a-floor' },
+    { id: 'orphan-bin', type: 'storage', capacity: 5, parentId: 'no-such-area' }
+  ],
+  equipment: [
+    { id: 'cutter-1', kind: 'cutter', name: '절단기 1호', homeLocation: 'cut-station', mtbfMs: 3600000,
+      properties: [{ id: 'speed', value: '1.2', dataType: 'xs:double', uom: 'MTS' }] },
+    { id: 'welder-1', kind: 'welder', homeLocation: 'weld-station' },
+    { id: 'ghost-1', kind: 'welder', homeLocation: 'no-such-location' }
+  ],
+  operations: [
+    { key: 'cut', label: 'twin.tpl.x.cut', intent: 'process', locationType: 'cut-station', resourceType: 'cutter',
+      duration: 'PT1H10M30S', variability: { distribution: 'triangular', min: 'PT1H', max: 'PT1H30M' },
+      parameters: [{ id: 'yield', value: '0.995' }],
+      /* 네 자원 명세 — 설비는 `resourceType`, 나머지 셋은 아래. */
+      personnelSpecification: [{ personnelClass: 'cutter-op', quantity: 1 }],
+      physicalAssetSpecification: [{ assetClass: 'jig', quantity: 1 }],
+      materialSpecification: [{ materialDefinition: 'steel', use: 'consumed', quantity: 2 }] }
+  ]
+})
+
+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: 'projection-test', subdomain: 'projection-test' } as any)
+  domainId = d.id
+
+  await ds.getRepository(TwinInstance).save({
+    domain: { id: domainId },
+    instanceId: INSTANCE,
+    kind: 'mes',
+    realityMode: 'sim-experiment',
+    purpose: 'operational',
+    status: 'stopped',
+    model: {}
+  } as any)
+
+  /* 구역은 model 밖(호스트 개념) — 자리가 FK 로 이걸 가리킨다. */
+  const space = await ds.getRepository(TwinSpace).save({ domain: { id: domainId }, spaceId: 'sp-1', name: '공장' } as any)
+  await ds.getRepository(TwinArea).save({ domain: { id: domainId }, space: { id: space.id }, areaId: 'a-floor', name: '생산 플로어' } as any)
+})
+
+after(async () => {
+  await ds?.destroy()
+})
+
+beforeEach(async () => {
+  await projectStructure(domainId, INSTANCE, model(), SOURCE)
+})
+
+test('문서의 세 축이 행으로 선다', async () => {
+  assert.equal(await ds.getRepository(TwinLocation).count(), 3)
+  assert.equal(await ds.getRepository(TwinEquipment).count(), 3)
+  assert.equal(await ds.getRepository(TwinOperation).count(), 1)
+})
+
+test('설비→자리가 진짜 FK 로 이어진다 — 문자열 대조가 아니다', async () => {
+  const eq = await ds.getRepository(TwinEquipment).findOne({ where: { equipmentId: 'cutter-1' }, relations: ['homeLocation'] })
+  assert.equal(eq?.homeLocation?.locationId, 'cut-station', 'FK 로 자리를 따라갈 수 있어야 한다')
+  /* 자리 쪽에서도 같은 행이다 — 문자열이었으면 같은 값이지만 같은 행은 아니다. */
+  const loc = await ds.getRepository(TwinLocation).findOne({ where: { locationId: 'cut-station' } })
+  assert.equal(eq?.homeLocation?.id, loc?.id)
+})
+
+test('자리→구역이 FK 로 이어진다 — 커널이 "밖" 이라 부른 참조가 호스트에서는 평범한 FK 다', async () => {
+  const loc = await ds.getRepository(TwinLocation).findOne({ where: { locationId: 'cut-station' }, relations: ['area'] })
+  assert.equal(loc?.area?.areaId, 'a-floor')
+})
+
+test('끊어진 참조는 이름을 대고 보고된다 — 막지 않되 침묵하지 않는다', async () => {
+  const report = await projectStructure(domainId, INSTANCE, model(), SOURCE)
+  assert.deepEqual(report.unresolvedHome, ['ghost-1→no-such-location'])
+  assert.deepEqual(report.unresolvedArea, ['orphan-bin→no-such-area'])
+
+  /* 행 자체는 남는다 — 참조 하나 때문에 설비가 통째로 사라지면 그게 더 나쁜 거짓말이다. */
+  const ghost = await ds.getRepository(TwinEquipment).findOne({ where: { equipmentId: 'ghost-1' }, relations: ['homeLocation'] })
+  assert.ok(ghost, '끊어진 참조를 가진 설비도 행으로 남는다')
+  assert.equal(ghost?.homeLocation, null, '이을 수 없는 참조는 비운다(엉뚱한 자리에 붙이지 않는다)')
+})
+
+test('전량 교체 — 두 번 돌려도 늘지 않는다', async () => {
+  await projectStructure(domainId, INSTANCE, model(), SOURCE)
+  await projectStructure(domainId, INSTANCE, model(), SOURCE)
+  assert.equal(await ds.getRepository(TwinLocation).count(), 3)
+  assert.equal(await ds.getRepository(TwinEquipment).count(), 3)
+})
+
+test('원본에서 사라진 것은 행에서도 사라진다 — 캐시는 원본을 따라간다', async () => {
+  const shrunk = model()
+  shrunk.locations = shrunk.locations.filter(l => l.id !== 'weld-station')
+  shrunk.equipment = shrunk.equipment.filter(m => m.id !== 'welder-1')
+  await projectStructure(domainId, INSTANCE, shrunk, SOURCE)
+  assert.equal(await ds.getRepository(TwinLocation).count(), 2)
+  assert.equal(await ds.getRepository(TwinEquipment).count(), 2)
+  assert.equal(await ds.getRepository(TwinLocation).countBy({ locationId: 'weld-station' } as any), 0)
+})
+
+test('원본 표식 없는 행은 만들 수 없다 — 캐시라는 사실이 구조로 지켜진다', async () => {
+  await assert.rejects(
+    () =>
+      ds.getRepository(TwinLocation).save({
+        domain: { id: domainId },
+        locationId: 'no-origin',
+        type: 'storage'
+        /* sourceRef · ingestedAt 없음 */
+      } as any),
+    /NOT NULL|constraint/i,
+    '출처 없는 행이 들어가면 "원본에서 온 캐시" 라는 규율이 구조로는 안 지켜지는 것이다'
+  )
+})
+
+test('소요시간은 ISO 8601 문자열 그대로 — 분으로 접으면 초가 조용히 사라진다', async () => {
+  const op = await ds.getRepository(TwinOperation).findOne({ where: { operationKey: 'cut' } })
+  assert.equal(op?.duration, 'PT1H10M30S')
+  /* 변동성·파라미터는 도메인마다 형이 달라 원형 그대로 싣는다. */
+  assert.equal(op?.variability?.distribution, 'triangular')
+  assert.deepEqual(op?.parameters, [{ id: 'yield', value: '0.995' }])
+})
+
+test('등록되지 않은 트윈에는 투영하지 않는다 — 주인 없는 행을 만들지 않는다', async () => {
+  await assert.rejects(() => projectStructure(domainId, 'not-registered', model(), SOURCE), /not registered/)
+})
+
+test('네 자원 명세가 함께 옮겨진다 — 선언한 것만 제약이 되므로 빠지면 화면이 거짓이 된다', async () => {
+  /*
+   * ISA-95 는 공정이 무엇을 필요로 하는지를 넷으로 말한다: 설비·인원·자산·자재. 셋이 투영에서
+   * 떨어져 있어서, 조회 화면이 "원본이 말한 값" 이라 적고도 넷 중 하나만 보였다 — 사람이 필요한
+   * 공정을 보고 **사람이 필요 없다고 결론 내게** 되어 있었다.
+   */
+  const op = await ds.getRepository(TwinOperation).findOne({ where: { operationKey: 'cut' } })
+  assert.deepEqual(op?.personnelSpecification, [{ personnelClass: 'cutter-op', quantity: 1 }], '인원 명세가 행에 남아야 한다')
+  assert.deepEqual(op?.physicalAssetSpecification, [{ assetClass: 'jig', quantity: 1 }], '자산 명세도 남아야 한다')
+  assert.deepEqual(op?.materialSpecification, [{ materialDefinition: 'steel', use: 'consumed', quantity: 2 }], '자재 명세도 남아야 한다')
+})
+
+test('이름이 행까지 온다 — 이름이 없으면 화면에 id 만 남는다', async () => {
+  /*
+   * 투영이 마스터의 `name` 을 버리고 있었다. 행에 이름이 없으면 어떤 화면도 이름을 만들 수 없어서
+   * 목록·표·관계 그림이 모두 `cut-station` 을 찍었다 — 표면마다 따로 보이지만 결함은 여기 하나다.
+   */
+  const loc = await ds.getRepository(TwinLocation).findOne({ where: { domain: { id: domainId } as any, locationId: 'cut-station' } as any })
+  assert.equal(loc!.name, '프레임 절단', '자리의 이름이 행에 실려야 한다')
+
+  const eq = await ds.getRepository(TwinEquipment).findOne({ where: { domain: { id: domainId } as any, equipmentId: 'cutter-1' } as any })
+  assert.equal(eq!.name, '절단기 1호', '설비의 이름이 행에 실려야 한다')
+
+  /* 공정은 마스터가 `label` 로 말한다 — 행에서는 규약의 이름으로 둔다(어휘를 하나로). */
+  const op = await ds.getRepository(TwinOperation).findOne({ where: { domain: { id: domainId } as any, operationKey: 'cut' } as any })
+  assert.equal(op!.name, 'twin.tpl.x.cut', '공정의 이름이 행에 실려야 한다')
+
+  /* **이름 없는 원본은 이름 없이 남는다** — id 를 이름으로 베끼면 "이름이 있다" 는 거짓이 되고,
+     화면은 이름 없음을 알아볼 수 없게 된다. */
+  const noname = await ds.getRepository(TwinLocation).findOne({ where: { domain: { id: domainId } as any, locationId: 'weld-station' } as any })
+  assert.equal(noname!.name ?? null, null, '원본이 이름을 말하지 않았으면 비어 있어야 한다')
+})
+
+test('자원 속성이 행까지 온다 — 소비처가 실제로 읽는 사실이다(주행 속도)', async () => {
+  /*
+   * 모델에는 있는데 행에 자리가 없어 투영이 흘리고 있었다. 그러면 조회 화면은 "원본이 말한 값" 이라
+   * 적고도 속성을 못 보인다 — 이름이 같은 식으로 사라졌던 것과 같은 부류다.
+   *
+   * 단위를 값과 함께 담는지도 본다: 단위 없는 "1.2" 는 초속인지 시속인지 말하지 않는다.
+   */
+  const eq = await ds.getRepository(TwinEquipment).findOne({ where: { domain: { id: domainId } as any, equipmentId: 'cutter-1' } as any })
+  const props = (eq!.properties ?? []) as any[]
+  assert.equal(props.length, 1, '선언한 속성이 행에 실려야 한다')
+  assert.equal(props[0].id, 'speed')
+  assert.equal(props[0].value, '1.2')
+  assert.equal(props[0].uom, 'MTS', '단위가 값과 함께 남아야 한다')
+
+  /* 선언하지 않은 자원은 **비어 있다** — 빈 배열로 "선언했다" 고 말하지 않는다. */
+  const noneProps = await ds.getRepository(TwinEquipment).findOne({ where: { domain: { id: domainId } as any, equipmentId: 'welder-1' } as any })
+  assert.equal(noneProps!.properties ?? null, null)
+})