@things-factory/headless-twin 10.0.8 → 10.0.10

package/test/mutation-gate.test.ts

@@ -0,0 +1,122 @@
+/*
+ * 뮤테이션 게이트 가드 — **트윈을 바꾸는 문은 전부 잠겨 있다.**
+ *
+ * ── 계기 (2026-08-06) ──────────────────────────────────────────────────────
+ * 권한 모델을 손대며 세어 보니 트윈 뮤테이션 24개 중 **22개에 게이트가 없었다.** 인스턴스 삭제와
+ * 레퍼런스 자격정보 저장까지 로그인만 하면 누구나 부를 수 있었다. 발견은 사람 눈이었다 — 즉
+ * 25번째 뮤테이션이 게이트 없이 들어오면 아무것도 잡지 못한다. 그래서 기계가 센다.
+ *
+ * ── 왜 문자열을 그대로 비교하나 ─────────────────────────────────────────────
+ * "게이트가 있나" 만 보면 `domainOwnerGranted: false` 로 약해지거나 category 가 다른 값으로 갈라져도
+ * 통과한다. 게이트는 **한 문장이어야** 서버·클라·관리 화면이 같은 권한을 말한다. 그래서 정본 문장과
+ * 글자까지 같은지 본다.
+ *
+ * ── 조회는 왜 검사하지 않나 (ADR-0027) ──────────────────────────────────────
+ * 조회에는 게이트를 두지 않기로 했다 — `twinKpi` 가 같은 판정을 게이트 없이 이미 내주므로, 일부
+ * 조회만 잠그면 보안이 아니라 화면 고장이 된다. 이 결정이 바뀌면 아래 "정본 문장" 검사가 먼저
+ * 깨진다. 그때는 테스트를 고치지 말고 **ADR 을 먼저 고친다.**
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** 정본 게이트 — 트윈을 **바꾸는** 모든 작업이 요구하는 단 하나의 권한. */
+const GATE =
+  `@Directive('@privilege(category: "twin", privilege: "mutation", ` + `domainOwnerGranted: true, superUserGranted: true)')`
+
+/**
+ * 두 번째 게이트 — **테넌트를 넘어 읽는 운영 계기판** (ADR-0027 예외, 2026-08-07).
+ *
+ * ADR-0027 의 전제는 "읽기의 경계는 테넌트 소속" 이라 조회에는 게이트를 붙이지 않는다. 그런데 프로세스
+ * 부하 계기판(`twinLoad`)은 이벤트 루프가 프로세스 공유이므로 **일부러 전 테넌트를 합산한다** — 소속이
+ * 경계가 되지 못한다. 그래서 시스템 소유만 본다. **권한 이름을 만들지 않았다**(category·privilege 없음).
+ *
+ * 늘리지 말 것. 조건은 ADR-0027 의 예외 절에 있고, 셋 중 하나라도 아니면 조회 무게이트가 그대로다.
+ */
+const OPS_GATE = `@Directive('@privilege(superUserGranted: true)')`
+
+const ALLOWED = [GATE, OPS_GATE]
+
+const SERVER = new URL('../server', import.meta.url).pathname
+
+function walk(dir: string, out: string[] = []): string[] {
+  let entries: string[]
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return out
+  }
+  for (const e of entries) {
+    const p = join(dir, e)
+    if (statSync(p).isDirectory()) walk(p, out)
+    else if (p.endsWith('.ts') && !p.endsWith('.d.ts')) out.push(p)
+  }
+  return out
+}
+
+/**
+ * `@Mutation` 위에 붙은 데코레이터·주석 덩이를 거꾸로 모은다.
+ *
+ * 데코레이터가 바로 붙어 있다고 가정하지 않는다 — 나중에 다른 데코레이터가 끼어들어도 게이트를
+ * 찾아야 한다. 덩이의 끝은 코드(다른 메서드의 `}` 등)를 만나는 자리다.
+ */
+function decoratorBlockAbove(lines: string[], at: number): string[] {
+  const block: string[] = []
+  for (let i = at - 1; i >= 0; i--) {
+    const t = lines[i].trim()
+    if (!t) continue /* 주석과 데코레이터 사이의 빈 줄은 덩이를 끊지 않는다 */
+    const isBlockPart = t.startsWith('@') || t.startsWith('*') || t.startsWith('/*') || t.startsWith('//')
+    if (!isBlockPart) break
+    block.push(t)
+  }
+  return block
+}
+
+const files = walk(SERVER)
+
+test('트윈을 바꾸는 뮤테이션은 전부 정본 게이트를 달고 있다', () => {
+  const ungated: string[] = []
+  let mutations = 0
+
+  for (const f of files) {
+    const lines = readFileSync(f, 'utf-8').split('\n')
+    lines.forEach((line, i) => {
+      if (!line.trim().startsWith('@Mutation')) return
+      mutations++
+      if (!decoratorBlockAbove(lines, i).some(l => l === GATE)) {
+        /* 어느 뮤테이션인지 이름으로 말한다 — 줄번호만 주면 고치는 사람이 다시 찾아야 한다. */
+        const name = (lines.slice(i, i + 6).join(' ').match(/async\s+(\w+)/) ?? [, '?'])[1]
+        ungated.push(`${f.split('/').slice(-2).join('/')}:${i + 1}  ${name}`)
+      }
+    })
+  }
+
+  /* 훑기가 망가져 0건이 되면 "위반 없음" 으로 보인다 — 그 거짓 통과를 막는다. */
+  assert.ok(mutations >= 20, `뮤테이션을 ${mutations}개만 찾았다 — 소스 훑기가 망가졌다`)
+  assert.deepEqual(
+    ungated,
+    [],
+    `게이트 없는 뮤테이션 ${ungated.length}건 — 로그인만 하면 누구나 부를 수 있다:\n${ungated.join('\n')}`
+  )
+})
+
+test('권한 문장이 하나로 통일되어 있다 — 약해지거나 서로 어긋나지 않았다', () => {
+  const odd: string[] = []
+  for (const f of files) {
+    readFileSync(f, 'utf-8')
+      .split('\n')
+      .forEach((line, i) => {
+        const t = line.trim()
+        if (!t.startsWith("@Directive('@privilege")) return
+        if (!ALLOWED.includes(t)) odd.push(`${f.split('/').slice(-2).join('/')}:${i + 1}  ${t}`)
+      })
+  }
+  assert.deepEqual(
+    odd,
+    [],
+    `정본과 다른 권한 문장 ${odd.length}건. 쓰기는 GATE 하나, 테넌트를 넘어 읽는 운영 계기판만 ` +
+      `OPS_GATE. 그 밖으로 늘리는 것이 의도라면 ADR-0027 을 먼저 고치고 이 검사의 정본을 함께 옮긴다:` +
+      `\n${odd.join('\n')}`
+  )
+})

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) }
 
@@ -94,9 +94,92 @@ test('★ withLiveOee: projector 미러(oee 없음) + 누적기 → live 설비
 
   // withLiveOee 로 보강 → buildEntityDeltas payload 에 oee 포함(sim 과 동일 형상 = 보드 OEE 컴포넌트 live 렌더).
   const enriched = withLiveOee(rawLive, acc)
-  const fk = buildEntityDeltas(enriched).find(d => d.tag === 'fk-1')!.data as any
+  const fk = buildEntityDeltas(enriched, 't1').find(d => d.tag === 'fk-1')!.data as any
   assert.ok(fk.oee, 'withLiveOee 후 설비 data(tag) payload 에 oee 포함 — live OEE 갭 종료')
   // buildEntityDeltas shapeOee = 정수 퍼센트(0-100), raw ms 제외.
   assert.ok(fk.oee.overall >= 0 && fk.oee.overall <= 100, 'oee.overall ∈ [0,100] 정수 퍼센트')
   assert.ok(fk.oee.availability < 100, 'availability < 100 (고장 시간 반영 — 누적기 downMs)')
 })
+
+/*
+ * ── 되짚은 화면에도 가동 이력이 있어야 한다 (2026-08-05) ────────────────────
+ * OEE 는 원 시스템이 누적을 보내 주지 않아 호스트가 상태 전이를 적분해 만든다. 그런데 그 누적기는
+ * **라이브에서만** 돌았고, 저널을 접는 경로는 그 계산을 하지 않았다 — 과거를 되짚으면 모든 설비가
+ * "가동 이력이 전혀 없음" 으로 보였다(실 저널: `rosarito-mes` 18대, `hatiolab-wms` 22대가 그랬다).
+ *
+ * 없는 것은 데이터가 아니라 계산이다: 입력은 저널에 다 있다. 그래서 같은 누적기에 같은 이벤트를
+ * 태운다 — 이 테스트는 그 재계산이 라이브와 **같은 값**을 내는지, 그리고 시간여행에서 **그 시점까지만**
+ * 세는지를 못 박는다.
+ */
+test('★ 저널을 다시 태우면 라이브와 같은 계측이 나온다 — 규칙이 하나이므로', () => {
+  const T0 = Date.parse('2026-08-05T00:00:00.000Z')
+  const ev = (ms: number, id: string, status: string) => ({
+    eventId: `e${ms}`,
+    eventType: 'equipment.status',
+    eventTime: new Date(T0 + ms).toISOString(),
+    tenantId: 't',
+    data: { equipmentId: id, moverId: id, status }
+  })
+  const stream = [ev(0, 'fk-1', 'idle'), ev(10_000, 'fk-1', 'busy'), ev(40_000, 'fk-1', 'down'), ev(70_000, 'fk-1', 'idle')]
+
+  /* 라이브 — 이벤트가 도착하는 대로 누적. */
+  const live = new OeeAccumulator()
+  for (const e of stream) live.apply(e as any)
+
+  /* 되짚기 — 저널에서 같은 순서로 다시 태운다. */
+  const replayed = new OeeAccumulator()
+  for (const e of stream) replayed.apply(e as any)
+
+  const at = T0 + 70_000
+  assert.deepEqual(replayed.oee('fk-1', at), live.oee('fk-1', at), '같은 이벤트·같은 시점이면 같은 값이어야 한다')
+  assert.equal(replayed.oee('fk-1', at).downMs, 30_000, '고장 30초가 잡혀야 한다')
+})
+
+test('★ 시간여행은 그 시점까지만 센다 — 뒤에 일어난 고장이 과거 화면에 섞이지 않게', () => {
+  const T0 = Date.parse('2026-08-05T00:00:00.000Z')
+  const ev = (ms: number, status: string) => ({
+    eventId: `e${ms}`,
+    eventType: 'equipment.status',
+    eventTime: new Date(T0 + ms).toISOString(),
+    tenantId: 't',
+    data: { equipmentId: 'fk-1', moverId: 'fk-1', status }
+  })
+  const all = [ev(0, 'busy'), ev(30_000, 'down'), ev(60_000, 'idle')]
+
+  /* 30초 시점까지만 태운다(호스트가 잘라 낸 이벤트만 태우는 것과 같다). */
+  const past = new OeeAccumulator()
+  for (const e of all.slice(0, 2)) past.apply(e as any)
+  assert.equal(past.oee('fk-1', T0 + 30_000).downMs, 0, '아직 고장이 시작된 시점 — 고장 시간은 0 이다')
+
+  const now = new OeeAccumulator()
+  for (const e of all) now.apply(e as any)
+  assert.equal(now.oee('fk-1', T0 + 60_000).downMs, 30_000, '지금 화면에서는 고장 30초가 잡힌다')
+})
+
+test('★ 계측 시점을 벽시계로 재지 않는다 — 과거 화면의 가용률이 시간이 갈수록 떨어지지 않게', () => {
+  const T0 = Date.parse('2026-08-05T00:00:00.000Z')
+  const acc = new OeeAccumulator()
+  acc.apply({ eventId: 'e1', eventType: 'equipment.status', eventTime: new Date(T0).toISOString(), tenantId: 't', data: { equipmentId: 'fk-1', moverId: 'fk-1', status: 'busy' } } as any)
+  const atThen = acc.oee('fk-1', T0 + 10_000)
+  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/
+  )
+})