@things-factory/headless-twin 10.0.9 → 10.0.11

package/test/instance-cache-lifecycle.test.ts

@@ -0,0 +1,110 @@
+/*
+ * ★ 인스턴스별 캐시는 **트윈과 함께 사라진다.**
+ *
+ * ── 왜 이 검사가 필요한가 ─────────────────────────────────────────────────────
+ * 엔진은 트윈마다 메모리에 몇 가지를 들고 있다(실측 추정기·구조 리비전·복구 표식). 지움은 저널과
+ * 등록부까지 갔는데 **캐시는 남았다** — 삭제된 트윈의 항목이 서버 재기동까지 살아 있었다. 항목 하나가
+ * 하루치 KPI 그룹을 물고 있으므로, 트윈을 만들고 지우는 일이 반복되는 현장에서는 그것이 곧 누수다.
+ *
+ * TTL 은 이것을 막지 못한다: TTL 은 **값이 낡는 것**을 막을 뿐 **없어진 주인**을 지우지 않는다.
+ *
+ * 그래서 규율은 둘이다.
+ *  ① 트윈이 사라지면 그 트윈에 대한 메모리를 **전부** 잊는다(정확한 쪽).
+ *  ② 우리 API 를 지나지 않고 사라지는 길(도메인째 삭제·DB 직접 조작)에는 **상한**이 막는다(방어).
+ *
+ * 사설(private) 필드를 들여다보는 검사인 것을 안다. 그런데 여기서 지켜야 하는 것은 겉으로 드러나는
+ * 값이 아니라 **메모리가 자라지 않는다**는 사실이고, 그것은 안을 봐야 볼 수 있다.
+ */
+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 { DataSource: TypeOrmDataSource } = req('typeorm')
+
+let ds: DataSource
+let domainId: string
+
+const INSTANCE = 'cache-probe'
+
+const master = (): any => ({
+  source: INSTANCE,
+  system: 'wms',
+  siteName: '캐시 창고',
+  space: { spaceId: 'cache-site', 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' }]
+})
+
+/** 캐시 안을 본다 — 겉으로는 안 보이는 사실을 지키는 검사이므로. */
+const caches = () => ({
+  measured: (TwinEngine as any).measuredCache as Map<string, unknown>,
+  structureRev: (TwinEngine as any).structureRevCache as Record<string, number>,
+  recovered: (TwinEngine as any).recovered as Record<string, unknown>
+})
+const keyOf = (id: string) => `${domainId}:${id}`
+
+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: 'cache-test', subdomain: 'cache-test' } as any)
+  domainId = d.id
+})
+
+after(async () => {
+  await TwinEngine.stop(domainId, INSTANCE).catch(() => {})
+  await ds?.destroy()
+})
+
+test('지운 트윈의 캐시는 남지 않는다 — TTL 은 없어진 주인을 지우지 않는다', async () => {
+  await TwinEngine.ingestMaster(domainId, master())
+  /* 캐시를 실제로 채운다 — 손으로 넣으면 "채우는 경로" 가 바뀌어도 검사가 통과한다. */
+  await TwinEngine.structureRevOf(domainId, INSTANCE)
+  const { measured, structureRev } = caches()
+  assert.ok(keyOf(INSTANCE) in structureRev, '구조 리비전이 캐시에 올라와야 이 검사가 뜻이 있다')
+
+  await TwinEngine.remove(domainId, INSTANCE)
+
+  const after = caches()
+  assert.equal(keyOf(INSTANCE) in after.structureRev, false, '지운 트윈의 구조 리비전이 남았다')
+  assert.equal(after.measured.has(keyOf(INSTANCE)), false, '지운 트윈의 실측 캐시가 남았다')
+  assert.equal(keyOf(INSTANCE) in after.recovered, false, '지운 트윈의 복구 표식이 남았다')
+  assert.equal(measured, after.measured, '캐시 객체를 갈아치우는 것이 아니라 항목을 지운다')
+})
+
+test('상한을 넘으면 가장 오래 손대지 않은 것부터 버린다 — 주인 없이 사라진 트윈까지 막는다', async () => {
+  const { measured } = caches()
+  measured.clear()
+  const MAX = (TwinEngine as any).MEASURED_MAX as number
+  assert.ok(MAX > 0, '상한이 선언되어 있어야 방어가 성립한다')
+
+  /*
+   * 상한 + 2 개를 넣고, 넣는 경로(`measuredEstimator`)를 그대로 쓴다. 트윈이 등록되어 있지 않으면
+   * KPI 조회가 빈 값을 내고 캐시에는 `undefined` 가 들어간다 — **그 자체도 캐시할 값이다**(없다는
+   * 사실을 알고 있는 것과 매번 다시 묻는 것은 다르다).
+   */
+  const call = (TwinEngine as any).measuredEstimator.bind(TwinEngine)
+  for (let i = 0; i < MAX + 2; i++) await call(domainId, `ghost-${i}`)
+
+  assert.ok(measured.size <= MAX, `상한을 넘어 자랐다(${measured.size} > ${MAX})`)
+  assert.equal(measured.has(`${domainId}:ghost-0`), false, '가장 오래된 항목이 남아 있다 — 버릴 순서가 어긋났다')
+  assert.ok(measured.has(`${domainId}:ghost-${MAX + 1}`), '가장 최근 항목은 남아야 한다')
+  measured.clear()
+})

package/test/kernel-kind-guard.test.ts

@@ -0,0 +1,96 @@
+/*
+ * 커널 선택 가드 — **모르는 종류로는 뜨지 않는다.**
+ *
+ * ── 무엇이 있었나 (2026-08-08) ───────────────────────────────────────────────
+ * 커널을 고르는 자리 셋이 모두 이랬다:
+ *
+ *     const Kernel = KERNELS[reg.kind ?? 'wms'] ?? WmsKernel
+ *
+ * 폴백이 둘 겹쳐 있었다. ①은 컬럼이 비었을 때, ②는 표에 없는 값일 때. 그리고 `kind` 는
+ * 검증 없는 자유 문자열이다(`@Arg('kind') kind: string` — enum 도 화이트리스트도 없다).
+ * 그래서 오타 하나·대소문자 하나로 **야드/생산 트윈이 조용히 창고 커널로 돌았다.**
+ * 오류가 없으니 화면에는 트윈이 정상으로 보이고, 안에서 도는 규칙만 다른 도메인의 것이다.
+ * 예측 경로가 가장 나빴다 — 야드의 미래를 창고 규칙으로 굴려 놓고 숫자만 뜬다.
+ *
+ * ── 왜 검사로 남기나 ────────────────────────────────────────────────────────
+ * 자리를 고치는 것만으로는 부족하다. 커널 종류가 늘 때(다음은 TMS 든 무엇이든) 새 자리가
+ * 생기고, `?? WmsKernel` 은 "안전한 기본값" 처럼 보여서 다시 자란다. 실제로 세 자리에
+ * 똑같이 자라 있었다. 틀린 공장을 조용히 띄우는 것보다 뜨지 않는 편이 낫다.
+ *
+ * 이 검사가 막는 것은 **표를 밖에서 직접 색인하는 것**이다. 종류→커널 해소는 `kernelFor`
+ * 하나만 한다. 새 자리를 쓸 때 이 검사가 걸리면, 폴백을 붙이지 말고 `kernelFor` 를 부를 것.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+const ENGINE = new URL('../server/engine/twin-engine.ts', import.meta.url).pathname
+const MUTATION = new URL('../server/service/twin-lifecycle/twin-lifecycle-mutation.ts', import.meta.url).pathname
+
+/*
+ * 종류 폴백은 **한 패키지에 갇혀 있지 않다.** 처음에 twin-engine 두 자리만 고쳤더니, 라이브 미러를
+ * 띄우는 호출자 넷(operato-twin 의 벤치·부하시험·프리셋 프로비저닝, headless 의 reference-live)이
+ * `det.kind ?? 'wms'` 로 **엔진이 던지기 전에 먼저 이기고** 있었다. 커넥터 spec 도 마찬가지였다.
+ * 그래서 두 패키지의 서버 코드를 함께 훑는다.
+ */
+const ROOTS = [new URL('../server', import.meta.url).pathname, new URL('../../operato-twin/server', import.meta.url).pathname]
+
+/**
+ * 코드만 본다 — 주석은 **과거를 설명하느라 옛 코드를 그대로 인용한다**(바로 위 머리말이 그렇다).
+ * 줄 단위로 `*`·`//` 만 걸러내면 여러 줄 주석의 둘째 줄부터 새어 나오므로 블록을 통째로 지운다.
+ */
+function codeOf(path: string): string[] {
+  return readFileSync(path, 'utf-8')
+    .replace(/\/\*[\s\S]*?\*\//g, '') // 블록 주석
+    .split('\n')
+    .map(l => l.replace(/\/\/.*$/, '')) // 줄 주석
+    .filter(l => l.trim())
+}
+
+test('커널 폴백이 없다 — 모르는 종류는 창고로 떨어지지 않는다', () => {
+  const offenders = codeOf(ENGINE).filter(l => /\?\?\s*WmsKernel|\|\|\s*WmsKernel/.test(l))
+  assert.deepEqual(offenders, [], '커널 선택에 폴백이 다시 생겼다 — kernelFor 로 던지게 할 것')
+})
+
+test('종류→커널 해소는 kernelFor 한 곳만 한다', () => {
+  /* 표를 직접 색인하는 줄. 정의부(`const KERNELS: Record…`)와 kernelFor 내부는 제외. */
+  const indexing = codeOf(ENGINE).filter(l => /KERNELS\[/.test(l) && !/const K = KERNELS\[kind\]/.test(l))
+  assert.deepEqual(indexing, [], 'KERNELS 를 밖에서 색인하고 있다 — kernelFor(kind) 를 쓸 것')
+})
+
+test('kernelFor 는 모르는 종류에 던진다 — 조용히 고르지 않는다', () => {
+  const src = readFileSync(ENGINE, 'utf-8')
+  const fn = src.slice(src.indexOf('function kernelFor'))
+  assert.match(fn.slice(0, 300), /throw new Error/, 'kernelFor 가 던지지 않으면 이 계약이 무너진다')
+})
+
+test("board 를 주는 기동은 kind 를 요구한다 — `kind ?? 'wms'` 로 메우지 않는다", () => {
+  const offenders = codeOf(MUTATION).filter(l => /kind\s*\?\?\s*['"]/.test(l))
+  assert.deepEqual(offenders, [], '종류를 빠뜨린 프로비저닝이 다시 창고로 기동한다')
+})
+
+/** 두 패키지의 서버 .ts 전부. */
+function serverFiles(): string[] {
+  const out: string[] = []
+  const walk = (dir: string) => {
+    for (const e of readdirSync(dir)) {
+      const p = join(dir, e)
+      if (statSync(p).isDirectory()) walk(p)
+      else if (p.endsWith('.ts') && !p.endsWith('.d.ts')) out.push(p)
+    }
+  }
+  for (const r of ROOTS) walk(r)
+  return out
+}
+
+test('어느 서버 코드도 커널 종류를 리터럴로 메우지 않는다 — 호출자가 엔진의 검증을 앞질렀다', () => {
+  /* 예시 JSON 안의 `system: 'wms'` 는 필드를 보여 주는 것이라 대상이 아니다 — 폴백 연산자만 본다. */
+  const offenders: string[] = []
+  for (const f of serverFiles()) {
+    codeOf(f).forEach(l => {
+      if (/(\?\?|\|\|)\s*['"](wms|yms|mes)['"]/.test(l)) offenders.push(`${f.split('/packages/')[1]}: ${l.trim().slice(0, 90)}`)
+    })
+  }
+  assert.deepEqual(offenders, [], '종류 폴백이 다시 생겼다 — 선언이 없으면 메우지 말고 던질 것')
+})

package/test/kpi-baseline-db.test.ts

@@ -90,8 +90,10 @@ before(async () => {
     domain: { id: domainId },
     instanceId: INSTANCE,
     kind: 'wms',
+    realityMode: 'sim-experiment', /* 선언은 이제 필수 — 비워 두면 읽는 자리마다 기본값을 고른다 */
+    purpose: 'operational',
     status: 'stopped',
-    board: { locations: [{ id: 'dock', type: 'dock', capacity: 10 }], equipment: [{ id: 'fk-1', kind: 'forklift', homeLocation: 'dock' }] }
+    model: { locations: [{ id: 'dock', type: 'dock', capacity: 10 }], equipment: [{ id: 'fk-1', kind: 'forklift', homeLocation: 'dock' }] }
   } as any)
 
   /*

package/test/kpi-baseline.test.ts

@@ -86,7 +86,7 @@ test('분포는 측정된 표본만으로 만들되, **결측 창도 남긴다**
   assert.deepEqual([row.min, row.median, row.max], [40, 60, 80])
 })
 
-test('현재 값이 없으면 자리를 말하지 않는다 — 결측을 0 으로 읽으면 최고 성적으로 뒤집힌다', () => {
+test('현재 값이 없으면 순위를 내지 않는다 — 결측을 0 으로 읽으면 최고 성적으로 뒤집힌다', () => {
   /* 시간 지표는 "낮을수록 좋다" 라서 결측을 0 으로 놓으면 **일이 없던 구간이 1등**이 된다. */
   const [row] = summarizeBaseline({ 'workTime.p50Ms': SPECS['workTime.p50Ms'] }, {}, [
     sample(1, { 'workTime.p50Ms': 30_000 }),
@@ -101,7 +101,7 @@ test('현재 값이 없으면 자리를 말하지 않는다 — 결측을 0 으
   assert.deepEqual([row.min, row.max], [30_000, 40_000])
 })
 
-test('표본이 둘 미만이면 자리를 말하지 않는다 — 하나를 분포라 부를 수 없다', () => {
+test('표본이 둘 미만이면 순위를 내지 않는다 — 하나를 분포라 부를 수 없다', () => {
   const one = summarizeBaseline({ 'throughput.tasks': SPECS['throughput.tasks'] }, { 'throughput.tasks': 10 }, [
     sample(1, { 'throughput.tasks': 40 })
   ])[0]
@@ -150,7 +150,7 @@ test('중앙값과 같으면 typical — 임의의 임계를 만들지 않는다
   assert.equal(row.standing, 'typical')
 })
 
-test('중앙값 양쪽을 방향대로 가른다', () => {
+test('중앙값 양쪽을 방향에 따라 구분한다', () => {
   const past = [sample(1, { 'throughput.tasks': 40 }), sample(2, { 'throughput.tasks': 60 }), sample(3, { 'throughput.tasks': 80 })]
   const spec = { 'throughput.tasks': SPECS['throughput.tasks'] }
 

package/test/kpi-fold.test.ts

@@ -552,7 +552,7 @@ test('방향은 지표의 성질이다 — 사용자가 반대로 적을 수 없
   assert.equal(faster.met, true, '실제 30초 ≤ 목표 60초')
 })
 
-test('미달을 미달이라 말한다', () => {
+test('미달을 미달로 판정한다', () => {
   const kpi = kpiOf([...doneAtHour('t1', 7)])
   const [v] = judgeTargets(kpi, [{ metric: 'throughput.tasks', target: 5 }])
   assert.equal(v.met, false)
@@ -572,7 +572,7 @@ test('목표가 없으면 판정하지 않는다', () => {
   assert.deepEqual(judgeTargets(kpiOf([...doneAtHour('t1', 7)]), undefined), [])
 })
 
-test('값이 없는 지표는 판정하지 않는다 — 0 으로 놓으면 반대로 거짓말한다', () => {
+test('값이 없는 지표는 판정하지 않는다 — 0 으로 놓으면 판정이 반대로 뒤집힌다', () => {
   const empty = foldKpi([], DAY)
   /* 이 테스트가 실제로 결함을 잡았다: 분위수는 표본이 없으면 p50Ms: 0 으로 나온다. 그것을 값으로 읽으면
      시간 지표는 "낮을수록 좋다" 라서 **일이 없던 구간이 목표를 완벽히 달성한 것으로** 보고된다 —
@@ -696,3 +696,394 @@ test('축 항목별로 판정한다 — 값이 없는 지표는 판정하지 않
     '대기시간은 표본이 없어 판정 안 함 · 자원 점유는 축 단위로 뜻이 없어 판정 안 함'
   )
 })
+
+/*
+ * ── 에너지 원단위 (§10 7단계) ───────────────────────────────────────────────
+ *
+ * 원단위는 분자(전력량)와 분모(산출)를 **같은 창**에서 나눈 값이다. 그래서 별도 질의가 아니라 이 폴드
+ * 안에 있다 — 창이 하나뿐이면 어긋날 수 없다.
+ *
+ * 분자는 저널의 **구간 마감 사건**에서 온다(커널 상태가 아니라 저널이므로 멈춘 트윈·과거 구간에도
+ * 답한다). 그 값이 파생임을 `basis` 가 말하고, 못 센 구간 수를 함께 낸다.
+ */
+const T = Date.parse('2026-08-14T00:00:00.000Z')
+const q = 15 * 60_000
+const win = (startMs: number, endMs: number, meanKW?: number) => ({
+  eventType: 'energy.demand.window',
+  eventTime: new Date(endMs).toISOString(),
+  payload: { data: { startMs, endMs, ...(meanKW !== undefined ? { meanKW } : {}) } }
+})
+const orderDone = (atMs: number) => ({
+  eventType: 'order.status',
+  eventTime: new Date(atMs).toISOString(),
+  payload: { data: { status: 'completed' } }
+})
+
+test('에너지 사건이 없으면 에너지 블록을 내지 않는다 — 없는 것을 만들지 않는다', () => {
+  const r = foldKpi([orderDone(T + 60_000)], { fromMs: T, toMs: T + q })
+  assert.equal(r.energy, undefined)
+})
+
+test('구간 마감에서 전력량과 대당 원단위를 낸다 — 같은 창이므로 어긋날 수 없다', () => {
+  const r = foldKpi(
+    [win(T, T + q, 400), win(T + q, T + 2 * q, 400), orderDone(T + 60_000), orderDone(T + q + 60_000)],
+    { fromMs: T, toMs: T + 2 * q }
+  )
+  assert.equal(r.energy?.kWh, 200, '400kW × 0.25h × 2구간')
+  assert.equal(r.energy?.basis, 'mean-kw', '파생임을 밝힌다')
+  assert.equal(r.energy?.counted, 2)
+  assert.equal(r.energy?.intensity.value, 100, '200kWh ÷ 완료 2건')
+  assert.equal(r.energy?.intensity.unit, 'kWh/unit')
+})
+
+test('그 창에 완료가 없으면 원단위는 정의되지 않는다 — 전력량은 그대로 낸다', () => {
+  const r = foldKpi([win(T, T + q, 400)], { fromMs: T, toMs: T + q })
+  assert.equal(r.energy?.kWh, 100, '전력량은 사실이다')
+  assert.equal(r.energy?.intensity.value, null)
+  assert.equal(r.energy?.intensity.reason, 'zero-denominator', '무한으로 내지 않는다')
+})
+
+test('계측이 끊긴 구간은 세지 않고 몇 개를 못 셌는지 말한다', () => {
+  const r = foldKpi([win(T, T + q, 400), win(T + q, T + 2 * q), orderDone(T + 60_000)], { fromMs: T, toMs: T + 2 * q })
+  assert.equal(r.energy?.counted, 1)
+  assert.equal(r.energy?.skipped, 1, '조용히 빼면 이 합이 그 창의 전부인 줄 읽는다')
+})
+
+test('창에 걸친 구간은 세지 않는다 — 부분을 비례로 자르면 추정이 하나 더 생긴다', () => {
+  const r = foldKpi([win(T, T + q, 400), win(T + q, T + 2 * q, 400)], { fromMs: T, toMs: T + q + 60_000 })
+  assert.equal(r.energy?.counted, 1)
+  assert.equal(r.energy?.kWh, 100)
+})
+
+/*
+ * ── 창의 최대수요 (2026-08-17) ──────────────────────────────────────────────
+ *
+ * 전력량은 요금의 사용량 부분이고, 최대수요는 **기본요금과 계약 위반**을 정한다. 평균으로 갈음하면
+ * 계약을 넘긴 창이 「안 넘겼다」로 보고된다 — 15분 평균 400kW 인 창의 최대가 1,200kW 일 수 있다.
+ */
+const winMax = (startMs: number, endMs: number, meanKW: number, maxKW: number) => ({
+  eventType: 'energy.demand.window',
+  eventTime: new Date(endMs).toISOString(),
+  payload: { data: { startMs, endMs, meanKW, maxKW } }
+})
+
+test('창의 최대수요는 구간 최대들 중 가장 큰 값이다 — 평균으로 갈음하지 않는다', () => {
+  const r = foldKpi([winMax(T, T + q, 400, 620), winMax(T + q, T + 2 * q, 400, 1180)], { fromMs: T, toMs: T + 2 * q })
+  assert.equal(r.energy?.kWh, 200)
+  assert.equal(r.energy?.peakKW, 1180)
+  assert.equal(r.energy?.peakStartMs, T + q, '언제였는지도 답할 수 있어야 한다')
+})
+
+test('구간이 최대를 싣지 않으면 최대수요는 없다 — 0 도 평균도 아니다', () => {
+  const r = foldKpi([win(T, T + q, 400)], { fromMs: T, toMs: T + q })
+  assert.equal(r.energy?.kWh, 100)
+  assert.equal(r.energy?.peakKW, undefined)
+})
+
+/*
+ * ── 에너지 목표 (2026-08-17) ────────────────────────────────────────────────
+ *
+ * 값은 폴드가 내고 있었는데 목표를 걸 수 있는 어휘에 없었다 — 그래서 화면은 「1,240kWh」를 보이면서도
+ * 그것이 계약 안쪽인지 말하지 못했다. 방향은 셋 다 「낮을수록 좋다」로 못 박혀 있다.
+ */
+test('최대수요 목표 — 계약 상한을 넘겼는지 판정한다', () => {
+  const kpi = foldKpi([winMax(T, T + q, 400, 1180)], { fromMs: T, toMs: T + q })
+  const [v] = judgeTargets(kpi, [{ metric: 'energy.peakKW', target: 800 }])
+  assert.equal(v.direction, 'lower', '많이 쓸수록 좋은 에너지 목표는 없다')
+  assert.equal(v.actual, 1180)
+  assert.equal(v.met, false, '계약 800kW 를 넘겼다')
+})
+
+test('전력량·원단위에도 목표를 건다', () => {
+  const kpi = foldKpi([win(T, T + q, 400), orderDone(T + 60_000)], { fromMs: T, toMs: T + q })
+  const [kwh] = judgeTargets(kpi, [{ metric: 'energy.kWh', target: 120 }])
+  assert.equal(kwh.actual, 100)
+  assert.equal(kwh.met, true)
+  const [per] = judgeTargets(kpi, [{ metric: 'energy.intensity', target: 80 }])
+  assert.equal(per.actual, 100, '100kWh ÷ 완료 1건')
+  assert.equal(per.met, false)
+})
+
+test('에너지를 못 잰 창은 판정하지 않는다 — 0 으로 읽으면 안 쓴 것이 만점이 된다', () => {
+  const kpi = foldKpi([orderDone(T + 60_000)], { fromMs: T, toMs: T + q })
+  assert.equal(judgeTargets(kpi, [{ metric: 'energy.kWh', target: 120 }]).length, 0)
+  assert.equal(judgeTargets(kpi, [{ metric: 'energy.peakKW', target: 800 }]).length, 0)
+  /* 원단위는 분모가 없어 `null` 로 온다 — 그것도 판정 대상이 아니다. */
+  const noOrders = foldKpi([win(T, T + q, 400)], { fromMs: T, toMs: T + q })
+  assert.equal(noOrders.energy?.intensity.value, null)
+  assert.equal(judgeTargets(noOrders, [{ metric: 'energy.intensity', target: 80 }]).length, 0)
+})
+
+/*
+ * ── 분기별 몫 (2026-08-17) ──────────────────────────────────────────────────
+ *
+ * 저널의 에너지 사실은 **현장 총량 한 줄**이다. 그래서 자리별 몫은 잰 것이 아니라 **나눈 것**이고,
+ * 그 사실을 값과 함께 내야 한다. 이 검사가 지키는 것: 합 보존 · 근거 표시 · 모르는 자리를 지어내지
+ * 않기 · 선언이 없으면 분해하지 않기.
+ */
+const runs = (taskId: string, resource: string, fromSec: number, toSec: number) => [
+  { eventType: 'task.status', eventTime: new Date(T + fromSec * 1000).toISOString(), payload: { data: { taskId, status: 'in-progress', resourceRef: resource } } },
+  { eventType: 'task.status', eventTime: new Date(T + toSec * 1000).toISOString(), payload: { data: { taskId, status: 'completed', resourceRef: resource } } }
+]
+
+test('분기별 몫 — 가동시간에 비례해 나누고, 합은 총량을 지킨다', () => {
+  /* press 300초 · weld 100초 → 3:1. 총량 100kWh. */
+  const events = [win(T, T + q, 400), ...runs('t1', 'press-1', 0, 300), ...runs('t2', 'weld-1', 0, 100)]
+  const r = foldKpi(events, { fromMs: T, toMs: T + q }, { resourceFeeder: { 'press-1': 'feeder-press', 'weld-1': 'feeder-weld' } })
+  assert.equal(r.energy?.kWh, 100)
+  const by = r.energy?.byFeeder ?? []
+  assert.equal(by.length, 2)
+  const press = by.find(x => x.key === 'feeder-press')!
+  const weld = by.find(x => x.key === 'feeder-weld')!
+  assert.ok(Math.abs(press.kWh - 75) < 1e-6, `press ${press.kWh}`)
+  assert.ok(Math.abs(weld.kWh - 25) < 1e-6, `weld ${weld.kWh}`)
+  /* 합 보존 — 이것이 깨지면 어딘가에서 전기가 사라지거나 생겨난 것이고, 그 위 모든 원단위가 거짓이다. */
+  const sum = by.reduce((a, x) => a + x.kWh, 0) + (r.energy?.unattributedKWh ?? 0)
+  assert.ok(Math.abs(sum - 100) < 1e-6, `합 ${sum}`)
+})
+
+test('몫에는 근거가 붙는다 — 여럿을 나눈 것이면 배분이라고 말한다', () => {
+  const events = [win(T, T + q, 400), ...runs('t1', 'press-1', 0, 300), ...runs('t2', 'weld-1', 0, 100)]
+  const r = foldKpi(events, { fromMs: T, toMs: T + q }, { resourceFeeder: { 'press-1': 'feeder-press', 'weld-1': 'feeder-weld' } })
+  const row = r.energy!.byFeeder![0]
+  assert.equal(row.basis, 'apportioned')
+  assert.equal(row.weightKind, 'runtimeMs')
+  assert.ok(row.weightShare > 0)
+})
+
+/*
+ * 선언된 부하가 **하나뿐인** 현장 — 커널은 「그 계량기는 그것만 잰다」고 읽는다(모델이 그렇게 말했다).
+ * 우리가 그것을 배분으로 낙인찍지 않는다: 처음에는 하드코딩으로 그렇게 했고, 그건 커널이 판정한 것을
+ * 화면에서 바꿔 말하는 짓이었다. 반대로 「돌아간 자원만 덮는다」고 거짓 선언을 넘기면 여럿인 현장에서도
+ * 이 경로로 빠져 배분이 측정으로 보고된다 — 그것이 실제로 처음의 결함이었다.
+ */
+test('선언된 부하가 하나면 커널의 판정을 그대로 옮긴다', () => {
+  const events = [win(T, T + q, 400), ...runs('t1', 'press-1', 0, 300)]
+  const r = foldKpi(events, { fromMs: T, toMs: T + q }, { resourceFeeder: { 'press-1': 'feeder-press' } })
+  assert.equal(r.energy!.byFeeder![0].basis, 'measured')
+})
+
+test('돌지 않은 설비는 0kWh 를 받지 않고, 몇 대가 빠졌는지 센다', () => {
+  const events = [win(T, T + q, 400), ...runs('t1', 'press-1', 0, 300)]
+  const r = foldKpi(events, { fromMs: T, toMs: T + q }, {
+    resourceFeeder: { 'press-1': 'feeder-press', 'weld-1': 'feeder-weld', 'paint-1': 'feeder-paint' }
+  })
+  const keys = (r.energy!.byFeeder ?? []).map(x => x.key)
+  assert.deepEqual(keys, ['feeder-press'], '가동 기록이 없는 자리는 행을 만들지 않는다(0 을 지어내지 않는다)')
+  assert.equal(r.energy!.excludedResources, 2, '빠진 설비 수를 밝힌다')
+})
+
+test('자리를 모르는 자원은 unknown 으로 모인다 — 빼지도, 아무 분기에 넣지도 않는다', () => {
+  const events = [win(T, T + q, 400), ...runs('t1', 'press-1', 0, 200), ...runs('t2', 'ghost-1', 0, 200)]
+  const r = foldKpi(events, { fromMs: T, toMs: T + q }, { resourceFeeder: { 'press-1': 'feeder-press' } })
+  const by = r.energy!.byFeeder!
+  assert.ok(by.some(x => x.key === 'unknown'), '모르는 자리를 지어내지 않는다')
+  const sum = by.reduce((a, x) => a + x.kWh, 0)
+  assert.ok(Math.abs(sum - 100) < 1e-6, '모르는 몫까지 합해 총량을 지킨다')
+})
+
+test('선언이 없으면 분해하지 않는다 — 자리를 모르는 채 나눈 숫자는 아무 것의 몫도 아니다', () => {
+  const events = [win(T, T + q, 400), ...runs('t1', 'press-1', 0, 300)]
+  const r = foldKpi(events, { fromMs: T, toMs: T + q })
+  assert.equal(r.energy?.byFeeder, undefined)
+  assert.equal(r.energy?.kWh, 100, '총량은 그대로 낸다')
+})
+
+test('그 창에 아무도 돌지 않았으면 나누지 않고 이유를 낸다', () => {
+  /* 부하가 둘 이상 선언된 현장 — 나눌 대상은 있는데 몫이 없다. */
+  const r = foldKpi([win(T, T + q, 400)], { fromMs: T, toMs: T + q }, {
+    resourceFeeder: { 'press-1': 'feeder-press', 'weld-1': 'feeder-weld' }
+  })
+  assert.equal(r.energy?.byFeeder, undefined, '가동 기록이 없으면 나눌 근거가 없다')
+  assert.equal(r.energy?.unattributedReason, 'no-weights')
+  assert.equal(r.energy?.unattributedKWh, 100, '나누지 못한 양은 그대로 남는다(0 으로 만들지 않는다)')
+  assert.equal(r.energy?.kWh, 100)
+})
+
+/*
+ * ── 금액 (2026-08-17) ───────────────────────────────────────────────────────
+ *
+ * 트윈은 「최대수요 328kW」까지 말하고 멈춰 있었다. 피크를 깎는 일이 돈이 되는 이유가 요금의 구조에
+ * 있으므로(사용량 + 기본요금) 단가를 선언하면 금액이 나온다. 계산은 커널이 하고 폴드는 나른다 —
+ * 이 검사는 **같은 창의 값에서 나오는지**와 **단가가 없을 때 지어내지 않는지**를 본다.
+ */
+test('단가를 선언하면 이 창의 금액이 나온다 — 전력량과 최대수요 각각에서', () => {
+  const r = foldKpi([winMax(T, T + q, 400, 1000)], { fromMs: T, toMs: T + q }, {
+    tariff: { energyChargePerKWh: 0.1, demandChargePerKW: 20, currency: 'USD' }
+  })
+  assert.equal(r.energy?.kWh, 100)
+  assert.equal(r.energy?.peakKW, 1000)
+  const c: any = r.energy?.cost
+  assert.equal(c.energyCharge, 10, '100kWh × 0.1')
+  assert.equal(c.demandCharge, 20_000, '1,000kW × 20')
+  assert.equal(c.currency, 'USD')
+  assert.equal(c.demandBasis, 'window-peak-as-period-peak', '기본요금의 조건이 값과 함께 온다')
+})
+
+test('단가를 선언하지 않으면 금액을 만들지 않는다', () => {
+  const r = foldKpi([winMax(T, T + q, 400, 1000)], { fromMs: T, toMs: T + q })
+  assert.equal(r.energy?.cost, undefined)
+})
+
+test('최대수요를 못 잰 창은 기본요금을 지어내지 않는다', () => {
+  const r = foldKpi([win(T, T + q, 400)], { fromMs: T, toMs: T + q }, { tariff: { demandChargePerKW: 20, energyChargePerKWh: 0.1 } })
+  const c: any = r.energy?.cost
+  assert.equal(c.energyCharge, 10)
+  assert.equal(c.demandCharge, undefined)
+})
+
+test('에너지 사실이 없는 창에는 금액도 없다 — 0 원이라고 말하지 않는다', () => {
+  const r = foldKpi([orderDone(T + 1000)], { fromMs: T, toMs: T + q }, { tariff: { demandChargePerKW: 20 } })
+  assert.equal(r.energy, undefined)
+})
+
+/*
+ * ── 깎인 양 (2026-08-17) ────────────────────────────────────────────────────
+ *
+ * 요금은 계통 수요로 매겨지고, 그 수요를 만든 것은 설비 부하다. 두 수의 간격이 곧 태양광·배터리가
+ * 덜어낸 몫이다 — 그것이 피크 셰이빙의 값이다. **같은 구간의 두 수**여야 차이가 뜻을 갖는다.
+ */
+const winNet = (startMs: number, endMs: number, meanKW: number, maxKW: number, grossMaxKW?: number) => ({
+  eventType: 'energy.demand.window',
+  eventTime: new Date(endMs).toISOString(),
+  payload: { data: { startMs, endMs, meanKW, maxKW, ...(grossMaxKW !== undefined ? { grossMaxKW } : {}) } }
+})
+
+test('피크 구간의 총부하와 깎인 양을 낸다', () => {
+  const r = foldKpi([winNet(T, T + q, 300, 400, 600), winNet(T + q, T + 2 * q, 500, 900, 1200)], { fromMs: T, toMs: T + 2 * q })
+  assert.equal(r.energy?.peakKW, 900)
+  assert.equal(r.energy?.peakGrossKW, 1200)
+  assert.equal(r.energy?.shavedKW, 300, '1,200 − 900 — 그 순간 계통에서 덜어낸 몫')
+})
+
+test('깎인 것이 없으면 그 값을 만들지 않는다 — 0 을 성과로 적지 않는다', () => {
+  const r = foldKpi([winNet(T, T + q, 300, 400, 400)], { fromMs: T, toMs: T + q })
+  assert.equal(r.energy?.peakGrossKW, 400)
+  assert.equal(r.energy?.shavedKW, undefined)
+})
+
+test('총부하를 싣지 않은 옛 구간은 그대로 — 순수요와 같다고 단정하지 않는다', () => {
+  const r = foldKpi([winMax(T, T + q, 400, 900)], { fromMs: T, toMs: T + q })
+  assert.equal(r.energy?.peakKW, 900)
+  assert.equal(r.energy?.peakGrossKW, undefined)
+  assert.equal(r.energy?.shavedKW, undefined)
+})
+
+/*
+ * ── 분기 계량이 있으면 배분하지 않는다 (2026-08-18) ───────────────────────────
+ * 실 게이트웨이는 분기마다 계량기를 보낸다. 그런데 화면은 「나누지 못함」으로 답했다 — 폴드에 가동시간
+ * 배분 경로만 있었기 때문이다. 미러 트윈에는 설비 가동 기록조차 없어(원천이 계량만 준다) 그 경로로는
+ * 분기별 값이 영원히 나오지 않았다.
+ */
+const windowFact = (startMs: number, points: { id: string; kWh: number; root?: boolean }[], meanKW = 400) => ({
+  eventType: 'energy.demand.window',
+  eventTime: new Date(startMs + 900_000).toISOString(),
+  instanceId: 'ems-1',
+  payload: {
+    data: {
+      startMs,
+      endMs: startMs + 900_000,
+      meanKW,
+      maxKW: meanKW,
+      samples: 30,
+      points: points.map(p => ({ id: p.id, kWh: p.kWh, ...(p.root ? { root: true } : {}) }))
+    }
+  }
+})
+
+test('분기별 값이 계량에서 온다 — 근거는 measured, 가동시간 이야기를 하지 않는다', () => {
+  const t0 = Date.parse('2026-08-18T00:00:00.000Z')
+  const r = foldKpi([windowFact(t0, [
+    { id: 'meter-incoming', kWh: 100, root: true },
+    { id: 'meter-a', kWh: 40 },
+    { id: 'meter-b', kWh: 30 }
+  ]) as any], { fromMs: t0, toMs: t0 + 900_000 }, {
+    meterFeeder: { 'meter-a': 'feeder-a', 'meter-b': 'feeder-b' }
+  })
+  const e = r.energy!
+  const byKey = new Map((e.byFeeder ?? []).map(f => [f.key, f]))
+  assert.equal(byKey.get('feeder-a')?.kWh, 40)
+  assert.equal(byKey.get('feeder-a')?.basis, 'measured')
+  assert.equal(byKey.get('feeder-a')?.weightKind, undefined, '나누지 않았으니 무엇으로 나눴다고 말하지 않는다')
+  assert.equal(byKey.get('feeder-b')?.kWh, 30)
+})
+
+test('하위 계량이 덮지 않는 나머지를 남긴다 — 어느 분기에 얹지 않는다', () => {
+  const t0 = Date.parse('2026-08-18T01:00:00.000Z')
+  /* 구간 평균 400kW × 0.25h = 100kWh 가 총량이고, 분기 합은 70 이다. */
+  const r = foldKpi([windowFact(t0, [{ id: 'meter-a', kWh: 40 }, { id: 'meter-b', kWh: 30 }]) as any],
+    { fromMs: t0, toMs: t0 + 900_000 }, { meterFeeder: { 'meter-a': 'feeder-a', 'meter-b': 'feeder-b' } })
+  const e = r.energy!
+  assert.equal(Math.round(e.kWh!), 100)
+  assert.equal(Math.round(e.unattributedKWh!), 30)
+  assert.equal(e.unattributedReason, 'not-submetered', '「선언이 없다」가 아니라 「계량이 덮지 않는다」')
+  const sum = (e.byFeeder ?? []).reduce((s, f) => s + f.kWh, 0) + (e.unattributedKWh ?? 0)
+  assert.ok(Math.abs(sum - e.kWh!) < 1e-6, `합이 보존된다(${sum} vs ${e.kWh})`)
+})
+
+test('분기 합이 뿌리를 넘으면 그 사실을 낸다 — 깎아 맞추지 않는다', () => {
+  const t0 = Date.parse('2026-08-18T02:00:00.000Z')
+  const r = foldKpi([windowFact(t0, [{ id: 'meter-a', kWh: 90 }, { id: 'meter-b', kWh: 30 }]) as any],
+    { fromMs: t0, toMs: t0 + 900_000 }, { meterFeeder: { 'meter-a': 'feeder-a', 'meter-b': 'feeder-b' } })
+  const e = r.energy!
+  assert.equal(Math.round(e.submeterExcessKWh!), 20, '120 − 100')
+  assert.equal(e.byFeeder?.find(f => f.key === 'feeder-a')?.kWh, 90, '계량값은 그대로 남는다')
+})
+
+test('계량 지도가 없으면 예전 배분 경로 그대로 — 거동을 바꾸지 않는다', () => {
+  const t0 = Date.parse('2026-08-18T03:00:00.000Z')
+  const r = foldKpi([windowFact(t0, [{ id: 'meter-a', kWh: 40 }]) as any],
+    { fromMs: t0, toMs: t0 + 900_000 }, { resourceFeeder: { 'press-1': 'feeder-a', 'press-2': 'feeder-b' } })
+  const e = r.energy!
+  /* 선언된 부하가 둘인데 가동 기록이 없으니 나눌 몫이 없다 — 총량은 그대로 남고 이유가 붙는다(예전 거동). */
+  assert.equal(e.unattributedReason, 'no-weights')
+  assert.equal(e.byFeeder, undefined, '계량 경로를 타지 않았다')
+})
+
+test('피크를 만든 분기를 그 순간의 kW 로 답한다 — 전력량 큰 분기와 다를 수 있다', () => {
+  const t0 = Date.parse('2026-08-18T06:00:00.000Z')
+  const t1 = t0 + 900_000
+  /* 두 구간: 앞 구간이 전력량은 크지만(a 가 꾸준히), 피크는 뒤 구간에서 b 가 만든다. */
+  const w0 = {
+    eventType: 'energy.demand.window',
+    eventTime: new Date(t1).toISOString(),
+    instanceId: 'ems-1',
+    payload: { data: { startMs: t0, endMs: t1, meanKW: 400, maxKW: 500, samples: 30,
+      points: [{ id: 'meter-a', kWh: 80 }, { id: 'meter-b', kWh: 20 }],
+      pointsAtPeak: [{ id: 'meter-a', kW: 450 }, { id: 'meter-b', kW: 50 }] } }
+  }
+  const w1 = {
+    eventType: 'energy.demand.window',
+    eventTime: new Date(t1 + 900_000).toISOString(),
+    instanceId: 'ems-1',
+    payload: { data: { startMs: t1, endMs: t1 + 900_000, meanKW: 300, maxKW: 900, samples: 30,
+      points: [{ id: 'meter-a', kWh: 40 }, { id: 'meter-b', kWh: 35 }],
+      pointsAtPeak: [{ id: 'meter-a', kW: 300 }, { id: 'meter-b', kW: 600 }] } }
+  }
+  const r = foldKpi([w0, w1] as any, { fromMs: t0, toMs: t1 + 900_000 }, {
+    meterFeeder: { 'meter-a': 'feeder-a', 'meter-b': 'feeder-b' }
+  })
+  const byKey = new Map((r.energy?.byFeeder ?? []).map(f => [f.key, f]))
+  assert.equal(byKey.get('feeder-a')?.kWh, 120, '전력량은 a 가 크다')
+  /* 피크 값은 **최대수요를 낸 구간 하나**에서 온다 — 두 구간을 섞으면 다른 순간의 값을 더하는 것이다. */
+  assert.equal(byKey.get('feeder-b')?.peakKW, 600, '피크를 만든 것은 b 다')
+  assert.equal(byKey.get('feeder-a')?.peakKW, 300)
+})
+
+test('피크 구간에 표본이 없던 분기는 피크 값을 만들지 않는다', () => {
+  const t0 = Date.parse('2026-08-18T07:00:00.000Z')
+  const w = {
+    eventType: 'energy.demand.window',
+    eventTime: new Date(t0 + 900_000).toISOString(),
+    instanceId: 'ems-1',
+    payload: { data: { startMs: t0, endMs: t0 + 900_000, meanKW: 200, maxKW: 300, samples: 10,
+      points: [{ id: 'meter-a', kWh: 40 }, { id: 'meter-b', kWh: 10 }],
+      pointsAtPeak: [{ id: 'meter-a', kW: 300 }] } }
+  }
+  const r = foldKpi([w] as any, { fromMs: t0, toMs: t0 + 900_000 }, {
+    meterFeeder: { 'meter-a': 'feeder-a', 'meter-b': 'feeder-b' }
+  })
+  const byKey = new Map((r.energy?.byFeeder ?? []).map(f => [f.key, f]))
+  assert.equal(byKey.get('feeder-a')?.peakKW, 300)
+  assert.equal(byKey.get('feeder-b')?.peakKW, undefined, '그 순간 값을 모르면 만들지 않는다')
+})