@things-factory/headless-twin 10.0.17 → 10.0.18

package/test/canonical-ingest-vocabularies.test.ts

@@ -15,7 +15,12 @@ import assert from 'node:assert/strict'
 
 import { ingestCanonicalRecords } from '../server/engine/canonical-ingest.ts'
 
-const NOW = '2026-08-14T09:00:00.000Z'
+/*
+ * 이 파일의 **시계**. 아래 픽스처들이 8월 말을 쓰는데 시계가 8월 14일이었다 — 자기 시계보다 뒤의
+ * 사실을 표본으로 두고 있었다. 커널이 「아직 오지 않은 시각의 사실」을 거부하게 되면서 드러났다
+ * (2026-08-30). 시계를 픽스처 뒤로 옮긴다.
+ */
+const NOW = '2026-09-01T00:00:00.000Z'
 
 const epcisRecord = {
   epc: 'urn:epc:id:sgtin:0614141.107346.2017',
@@ -282,8 +287,8 @@ const usageRecord = {
   basis: 'provider'
 }
 const billRecord = {
-  from: '2026-07-31T15:00:00.000Z',
-  to: '2026-08-31T15:00:00.000Z',
+  from: '2026-06-30T15:00:00.000Z',
+  to: '2026-07-31T15:00:00.000Z',
   demandCharge: 13728000,
   currency: 'KRW',
   billingDemandKW: 1650
@@ -323,3 +328,77 @@ test('한 배치에 넷이 섞여도 각자의 문으로 간다', () => {
   assert.equal(accepted.length, 4, '넷 다 받아들인다')
   assert.equal(new Set(accepted.map(e => e.eventType)).size, 4, '넷이 서로 다른 사건이다')
 })
+
+/*
+ * ── 여덟째 어휘 — 요금 기준 (2026-08-29, 커널 0.7.76) ─────────────────────────
+ *
+ * 문이 열렸는데 유입 갈림이 또 몰랐다. 오늘 세 번째다.
+ */
+const tariffBasisRecord = {
+  from: '2026-07-31T15:00:00.000Z',
+  to: '2026-08-31T15:00:00.000Z',
+  billingDemandKW: 1650,
+  demandChargePerKW: 8320,
+  currency: 'KRW'
+}
+
+test('★ 요금 기준이 자기 문으로 들어온다', () => {
+  const { accepted, rejected } = ingestCanonicalRecords([tariffBasisRecord] as any, 't', NOW)
+  assert.deepEqual(rejected, [], JSON.stringify(rejected))
+  assert.equal(accepted.length, 1)
+  assert.equal(accepted[0].eventType, 'energy.tariff.basis')
+})
+
+test('요금 기준의 사건 시각은 기간의 시작이다 — 진행 중인 주기도 미래에 적히지 않는다', () => {
+  const { accepted } = ingestCanonicalRecords([tariffBasisRecord] as any, 't', NOW)
+  assert.equal(accepted[0].eventTime, '2026-07-31T15:00:00.000Z', '청구서와 달리 to 가 아니다')
+})
+
+test('요금 기준과 청구서를 섞어도 각자의 문으로 간다', () => {
+  const { accepted, rejected } = ingestCanonicalRecords([tariffBasisRecord, billRecord] as any, 't', NOW)
+  assert.deepEqual(rejected, [], JSON.stringify(rejected))
+  assert.deepEqual(accepted.map(e => e.eventType).sort(), ['energy.bill', 'energy.tariff.basis'])
+})
+
+test('설비의 전기 계측값은 설비 상태 문으로 간다 — 발전 출력이 없어도 받는다', () => {
+  const { accepted, rejected } = ingestCanonicalRecords(
+    [{ equipmentId: '002', dcVoltage: 469.13, dcCurrent: 68.7, acVoltage: [377.8, 379.9, 377.7], acCurrent: [37, 37.2, 37] }] as any,
+    't',
+    NOW
+  )
+  assert.deepEqual(rejected, [], JSON.stringify(rejected))
+  assert.equal(accepted[0].eventType, 'energy.equipment')
+})
+
+/* ── 발전 단가가 지나갈 길 (2026-08-30) ────────────────────────────────────
+ *
+ * ★ 오늘 다섯 번째다. 커널에 문을 열고 이 갈림에 길을 내지 않으면, 레코드가 아무 문에도
+ *   들어가지 못하고 조용히 사라진다 — 거부도 되지 않으므로 아무도 모른다.
+ */
+test('발전 단가가 그 문으로 간다', () => {
+  const r = ingestCanonicalRecords(
+    [{ from: '2026-08-29T15:00:00.000Z', to: '2026-08-30T15:00:00.000Z', unitPrice: 148.61, currency: 'KRW' }] as any,
+    't',
+    NOW
+  )
+  assert.equal(r.rejected.length, 0, `거부되면 안 된다: ${JSON.stringify(r.rejected)}`)
+  assert.equal(r.accepted.length, 1)
+  assert.equal((r.accepted[0] as any).eventType, 'energy.generation.price')
+  assert.equal((r.accepted[0] as any).eventTime, '2026-08-29T15:00:00.000Z', '사건 시각은 기간의 시작이다')
+})
+
+test('★ 단가·사용 구간·요금 기준·청구서가 한 배치에 섞여 와도 각자의 문으로 간다', () => {
+  const r = ingestCanonicalRecords(
+    [
+      { from: '2026-08-29T15:00:00.000Z', to: '2026-08-30T15:00:00.000Z', unitPrice: 148.61, currency: 'KRW' },
+      { meterId: 'incoming', from: '2026-08-29T15:00:00.000Z', to: '2026-08-29T16:00:00.000Z', kWh: 474.48 },
+      { from: '2026-07-31T15:00:00.000Z', to: '2026-08-31T15:00:00.000Z', billingDemandKW: 1650, demandChargePerKW: 8320, currency: 'KRW' },
+      { from: '2026-06-30T15:00:00.000Z', to: '2026-07-31T15:00:00.000Z', demandCharge: 13_728_000, currency: 'KRW' }
+    ] as any,
+    't',
+    NOW
+  )
+  assert.equal(r.rejected.length, 0, JSON.stringify(r.rejected))
+  const types = (r.accepted as any[]).map(e => e.eventType).sort()
+  assert.deepEqual(types, ['energy.bill', 'energy.generation.price', 'energy.tariff.basis', 'energy.usage.period'])
+})

package/test/capability-mapping.test.ts

@@ -8,7 +8,7 @@
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { DOMAIN_CATALOG, CAPABILITIES, CAPABILITY_KEYS, capabilitiesForType, stateFieldsOf } from '@operato/twin-kernel'
+import { DOMAIN_CATALOG, CAPABILITIES, CAPABILITY_KEYS, capabilitiesForType, stateFieldsOf } from '@operato/ops-contract'
 import { buildEntityDeltas } from '../shared/entity-delta.ts'
 
 const SYSTEMS = ['wms', 'yms', 'mes'] as const

package/test/contract-layer-guard.test.ts

@@ -0,0 +1,48 @@
+/*
+ * **층이 이름만 남지 않게 한다** — 계약은 계약 패키지에서 온다.
+ *
+ * ── 왜 있나 (2026-08-30) ──────────────────────────────────────────────────
+ * 어휘와 판별 함수를 `@operato/ops-contract` 로 갈라냈다. 사실을 만드는 쪽(MES · WMS · 커넥터)이
+ * 엔진을 의존하지 않게 하기 위해서다.
+ *
+ * ── 처음에는 커널이 계약을 다시 내보냈다 ──────────────────────────────────
+ * 이유는 「이 저장소를 한 줄도 안 고쳐도 되게」였다. 그것은 **관리 편의**이지 구조의 근거가 아니다.
+ * 그렇게 두면 같은 이름을 두 경로로 가져올 수 있고, 새 코드가 편한 쪽을 쓰면 계약이 커널 뒤에 숨는다.
+ *
+ * 그때는 이 파일에 **세는 시험**이 있었다 — 커널 경로로 가져오는 자리가 늘지 않는지 보는 것이다.
+ * 세는 시험은 층이 깨졌다는 것을 인정하고 빚을 재는 도구다. 재export 를 걷으면서 그 시험도 없앴다.
+ *
+ * 지금 남은 것은 **사실을 확인하는 것**뿐이다. 커널이 계약을 내보내지 않으므로 잘못된 경로는 아예
+ * 컴파일되지 않는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import * as contract from '@operato/ops-contract'
+import * as kernel from '@operato/twin-kernel'
+
+test('★ 계약 패키지가 어휘를 내보낸다', () => {
+  const names = Object.keys(contract)
+  assert.ok(names.length > 100, `계약이 내보내는 이름이 ${names.length}개뿐이다 — 설치가 잘못됐다`)
+  for (const must of ['isEnergyRecord', 'ENERGY_EVENT', 'effectivityAt', 'ingestMasterData', 'procedureViolations']) {
+    assert.ok(names.includes(must), `${must} 가 계약에 없다`)
+  }
+})
+
+test('★ 커널은 계약을 다시 내보내지 않는다 — 내보내면 어휘가 엔진 뒤에 숨는다', () => {
+  const contractNames = new Set(Object.keys(contract))
+  const leaked = Object.keys(kernel).filter(n => contractNames.has(n))
+  assert.deepEqual(
+    leaked,
+    [],
+    `커널이 계약 이름을 다시 내보낸다:\n${leaked.slice(0, 20).join(', ')}\n` +
+      '두 경로로 가져올 수 있게 되면 새 코드가 편한 쪽을 쓰고, 사실을 만들기만 하는 쪽이 엔진을 의존하게 된다.'
+  )
+})
+
+test('커널은 엔진을 내보낸다 — 걷어내다가 필요한 것까지 걷지 않았는지 본다', () => {
+  const names = Object.keys(kernel)
+  for (const must of ['EmsKernel', 'MesKernel', 'WmsKernel', 'YmsKernel', 'StateProjector']) {
+    assert.ok(names.includes(must), `${must} 가 커널에 없다`)
+  }
+})

package/test/declaration-reaches-model.test.ts

@@ -86,6 +86,8 @@ const VALUE: Record<string, unknown> = {
   level: 'WorkCenter',
   footprint: { x: 1, y: 2, w: 3, h: 4 },
   gs1Id: 'urn:epc:id:sgln:0614141.00001.0',
+  /* 설비의 정체성 — **GS1 키가 아닌 것이 정상이다**(실측: 인버터 하드웨어 식별자). */
+  identity: 'ES100000007d8d061d-1',
   homeLocationId: 'cut-station',
   mtbfMs: 600000,
   mttrMs: 60000,

package/test/equipment-identity-reaches.test.ts

@@ -0,0 +1,57 @@
+/*
+ * **선언한 설비 정체성이 투영까지 닿는가** — 선언에서 화면까지 걸어 본다.
+ *
+ * ── 무엇이 있었나 (2026-08-30) ────────────────────────────────────────────
+ * 투영이 `m.gs1Id` 를 읽고 있었는데 **선언에 그런 필드가 없었다.** 그래서 그 칸은 일곱 대 모두 영원히
+ * 비어 있었다. 오류는 나지 않았다 — `?? null` 이 늘 `null` 을 냈을 뿐이다.
+ *
+ * 값은 한 칸 옆에 있었다. 커넥터가 인버터의 하드웨어 식별자를 속성으로 이미 보내고 있었고
+ * (`properties.deviceId = ES100000007d8d061d-1`), 정체성 칸도 있었는데 **그 사이에 길이 없었다.**
+ *
+ * 이 저장소에서 가장 자주 나는 결함 부류다. 그래서 필드를 여는 것으로 끝내지 않고 **선언 → 투영**을
+ * 실제로 걸어 본다. 필드만 있고 길이 없으면 여기서 빨갛게 난다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+import type { TwinModelDef } from '@operato/ops-contract'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const src = (p: string) => readFileSync(join(here, '..', 'server', p), 'utf-8')
+
+test('★ 선언에 정체성 자리가 있다', () => {
+  /* 타입이 받아들이면 선언에 자리가 있는 것이다 — 없으면 이 파일이 컴파일되지 않는다. */
+  const model: TwinModelDef = {
+    locations: [{ id: 'incoming', type: 'incoming' }],
+    equipment: [{ id: '001', kind: 'pv-array', homeLocation: 'incoming', identity: 'ES100000007d8d061d-1' }]
+  } as any
+  assert.equal((model.equipment?.[0] as any).identity, 'ES100000007d8d061d-1')
+})
+
+test('★ 투영이 그 자리를 읽는다 — 선언에 없는 이름을 읽으면 칸이 영원히 빈다', () => {
+  const projection = src('service/twin-model/project-structure.ts')
+  assert.match(
+    projection,
+    /identity:\s*\(m as any\)\.identity/,
+    '설비 투영이 선언의 identity 를 읽어야 한다. 다른 이름을 읽으면 그 칸은 늘 null 이다.'
+  )
+  assert.doesNotMatch(
+    projection,
+    /gs1Id:\s*m\.gs1Id/,
+    '설비 선언에 gs1Id 는 없다 — 읽으면 늘 null 이 된다(2026-08-30 실측: 일곱 대 모두 비어 있었다)'
+  )
+})
+
+test('★ 저장 자리의 이름이 선언과 같다 — 두 벌이면 한쪽만 고쳐진다', () => {
+  const entity = src('service/twin-model/twin-equipment.ts')
+  assert.match(entity, /identity\?: string/, '설비 행에 identity 칸이 있어야 한다')
+  assert.doesNotMatch(entity, /gs1Id\?: string/, '설비에서는 gs1Id 를 쓰지 않는다 — 정체성이 GS1 키가 아닌 것이 정상이다')
+})
+
+test('자리(location)의 gs1Id 는 그대로 둔다 — 그쪽은 실제로 SGLN 이 온다', () => {
+  const entity = src('service/twin-model/twin-location.ts')
+  assert.match(entity, /gs1Id\?: string/, '자리는 GS1 키를 받는다 — 설비와 같은 이유로 지우면 안 된다')
+})

package/test/fact-scope-wiring.test.ts

@@ -0,0 +1,96 @@
+/*
+ * 마감된 구간 사실의 **범위 배선** — 유입을 부르는 곳은 모두 어느 트윈인지 말해야 한다.
+ *
+ * ── 왜 이 시험이 있나 (2026-08-30) ────────────────────────────────────────
+ * 커널은 `new Kernel(domainId, …)` 으로 서므로 자기가 어느 트윈인지 모른다. 설비 번호·계량 지점 번호는
+ * 트윈 안에서만 통하는 이름표라, 범위를 넘기지 않으면 **서로 다른 설비의 같은 날이 한 사실**이 된다.
+ * 실측으로 그 일이 났다 — 두 발전소의 `002` 가 겹쳐, 저널에 6줄이 있는데 서로 다른 이름은 5개였다.
+ * 여러 현장을 함께 계산하는 성과 화면은 이름으로 중복을 걷어내므로 한쪽 발전량이 사라진다.
+ *
+ * 배선은 조용히 빠진다. 인자를 안 넘겨도 컴파일되고, 시험도 초록이고, 실 서버에서 값이 하나 사라질
+ * 뿐이다. 그래서 **부르는 자리를 세어서** 지킨다 — `ingest-wiring-guard` 와 같은 부류다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+import { resolveSubject, ingestEnergyGenerationPeriodRecords } from '@operato/ops-contract'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const serverDir = join(here, '..', 'server')
+
+function allTs(dir: string, out: string[] = []): string[] {
+  for (const name of readdirSync(dir)) {
+    const full = join(dir, name)
+    if (statSync(full).isDirectory()) allTs(full, out)
+    else if (name.endsWith('.ts')) out.push(full)
+  }
+  return out
+}
+
+/**
+ * 주석을 걷어낸다 — **설명에 적힌 이름을 호출로 세지 않는다.**
+ *
+ * 처음 이 시험을 만들었을 때 `reference-live.ts` 의 흐름 설명 한 줄(`ingestCanonicalRecords(정규→봉투)`)을
+ * 배선 빠진 호출로 잡았다. 주석을 고치게 만드는 시험은 아무것도 지키지 않는다.
+ */
+function withoutComments(src: string): string {
+  return src.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/[^\n]*/g, '$1')
+}
+
+test('★ 유입을 부르는 곳은 모두 어느 트윈인지 말한다 — 안 말하면 두 현장의 같은 번호가 겹친다', () => {
+  const bad: string[] = []
+  for (const file of allTs(serverDir)) {
+    if (file.endsWith('canonical-ingest.ts')) continue // 정의하는 자리
+    const src = withoutComments(readFileSync(file, 'utf-8'))
+    let i = src.indexOf('ingestCanonicalRecords(')
+    while (i >= 0) {
+      /* 호출 하나를 괄호 균형으로 잘라 낸다 — 줄바꿈이 있어도 본다. */
+      let depth = 0
+      let j = i + 'ingestCanonicalRecords'.length
+      for (; j < src.length; j++) {
+        if (src[j] === '(') depth++
+        else if (src[j] === ')') {
+          depth--
+          if (depth === 0) break
+        }
+      }
+      const call = src.slice(i, j + 1)
+      if (!call.includes('factScope')) {
+        bad.push(`${file.slice(serverDir.length + 1)}: ${call.replace(/\s+/g, ' ').slice(0, 90)}`)
+      }
+      i = src.indexOf('ingestCanonicalRecords(', j)
+    }
+  }
+  assert.deepEqual(
+    bad,
+    [],
+    `범위를 넘기지 않는 유입 호출:\n${bad.join('\n')}\n` +
+      'TwinEngine.factScope(domainId, instanceId) 를 넷째 인자로 넘겨라 — ' +
+      '넘기지 않으면 다른 현장의 같은 설비 번호가 한 사실로 겹치고, 성과 화면에서 한쪽이 사라진다.'
+  )
+})
+
+test('★ 범위를 넘기면 두 현장의 같은 번호가 다른 사실이다', () => {
+  const rec = { equipmentId: '002', from: '2026-08-28T15:00:00.000Z', to: '2026-08-29T15:00:00.000Z', kWh: 400.6 }
+  const a = ingestEnergyGenerationPeriodRecords(rec, { tenantId: 'd', scopeId: 'twin-a' }).accepted[0]
+  const b = ingestEnergyGenerationPeriodRecords(rec, { tenantId: 'd', scopeId: 'twin-b' }).accepted[0]
+  assert.notEqual(a.eventId, b.eventId)
+})
+
+test('선언된 정체성이 있으면 범위와 무관하게 한 사실이다 — 그릇이 정체성을 정하지 않는다', () => {
+  const rec = { equipmentId: '002', from: '2026-08-28T15:00:00.000Z', to: '2026-08-29T15:00:00.000Z', kWh: 400.6 }
+  const identityOf = () => 'https://example.com/obj/inv-002'
+  const a = ingestEnergyGenerationPeriodRecords(rec, { tenantId: 'd', scopeId: 'twin-a', identityOf }).accepted[0]
+  const b = ingestEnergyGenerationPeriodRecords(rec, { tenantId: 'd', scopeId: 'twin-b', identityOf }).accepted[0]
+  assert.equal(a.eventId, b.eventId)
+  assert.equal((a.data as any).subjectBasis, 'declared')
+})
+
+test('커널이 범위를 답할 자리가 있다 — 호스트가 그것을 넘긴다', () => {
+  const r = resolveSubject('equipment', '002', { tenantId: 'd', scopeId: 'ppms-호현' })
+  assert.equal(r.basis, 'twin-local')
+  assert.equal(r.subject, 'ppms-호현/002')
+})

package/test/generated-not-counted.test.ts

@@ -0,0 +1,99 @@
+/*
+ * **창에 다 들어오지 않은 발전 기간을 조용히 버리지 않는다.**
+ *
+ * ── 무엇이 일어났나 (2026-08-30) ──────────────────────────────────────────
+ * 어제 발전량이 저널에 멀쩡히 있는데 화면이 비어 있었다. 발전 기간은 하루 단위이고(`08-28 15:00 →
+ * 08-29 15:00`), 성과 구간은 「지금부터 24시간 전」이라 한낮에서 시작한다(`08-29 02:53 → 08-30 02:53`).
+ * 하루 기간이 그 구간에 **온전히 들어오지 않는다.**
+ *
+ * 더하지 않는 것 자체는 맞다 — 걸친 기간을 더하면 다른 날의 값이 이 창의 값인 척한다. 틀린 것은
+ * **아무 말도 하지 않은 것**이다. 사용자는 빈 화면을 「발전량이 없다」로 읽는다. 그 둘은 완전히
+ * 다른 상황이다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { foldKpi } from '../server/engine/kpi-fold.ts'
+
+const T = (iso: string) => Date.parse(iso)
+
+/** 실측값 — 오창의 8월 29일 하루. */
+const DAY_START = '2026-08-28T15:00:00.000Z'
+const DAY_END = '2026-08-29T15:00:00.000Z'
+
+const period = (equipmentId: string, kWh: number) => ({
+  eventType: 'energy.generation.period',
+  eventTime: DAY_END,
+  payload: {
+    eventId: `id|${equipmentId}`,
+    data: {
+      equipmentId,
+      kWh,
+      periodStart: DAY_START,
+      periodEnd: DAY_END,
+      observedFrom: DAY_START,
+      observedTo: DAY_END,
+      accumulation: 'daily',
+      boundary: 'offset'
+    }
+  }
+})
+
+const EVENTS = [period('002', 127.1), period('003', 104.1), period('004', 312.4), period('005', 102.3)] as any
+
+test('★ 창이 기간을 온전히 담으면 더한다', () => {
+  const r = foldKpi(EVENTS, { fromMs: T(DAY_START), toMs: T(DAY_END) })
+  const g = r.energy?.generated
+  assert.ok(g, '발전량이 있어야 한다')
+  assert.equal(g.counted, 4)
+  assert.equal(Math.round(g.kWh * 10) / 10, 645.9)
+  assert.equal(g.notCounted, undefined, '버린 것이 없으면 말하지 않는다')
+})
+
+test('★ 창이 기간을 반만 담으면 더하지 않되 **버렸다고 말한다**', () => {
+  /* 실제로 났던 구간 — 하루 기간의 한가운데에서 시작한다. */
+  const r = foldKpi(EVENTS, { fromMs: T('2026-08-29T02:53:00.000Z'), toMs: T('2026-08-30T02:53:00.000Z') })
+  const g = r.energy?.generated
+  assert.ok(g, '값이 없다고 아무것도 내지 않으면 화면은 「발전량 없음」으로 읽는다')
+  assert.equal(g.kWh, 0, '걸친 기간은 더하지 않는다 — 더하면 다른 날 값이 섞인다')
+  assert.equal(g.counted, 0)
+  assert.ok(g.notCounted, '버린 것을 말해야 한다')
+  assert.equal(g.notCounted.periods, 4)
+  assert.equal(Math.round(g.notCounted.kWh * 10) / 10, 645.9, '얼마를 못 세었는지 말한다')
+  assert.equal(g.notCounted.earliestStart, DAY_START)
+  assert.equal(g.notCounted.latestEnd, DAY_END)
+})
+
+test('창이 기간과 아예 겹치지 않으면 말할 것이 없다 — 없는 것을 만들지 않는다', () => {
+  const r = foldKpi(EVENTS, { fromMs: T('2026-07-01T00:00:00.000Z'), toMs: T('2026-07-02T00:00:00.000Z') })
+  assert.equal(r.energy?.generated, undefined)
+})
+
+test('온전히 든 것과 걸친 것이 섞이면 더한 것과 못 센 것을 함께 낸다', () => {
+  const earlier = {
+    ...period('002', 100),
+    eventTime: '2026-08-28T15:00:00.000Z',
+    payload: {
+      eventId: 'id|earlier',
+      data: {
+        equipmentId: '002',
+        kWh: 100,
+        periodStart: '2026-08-27T15:00:00.000Z',
+        periodEnd: '2026-08-28T15:00:00.000Z',
+        observedFrom: '2026-08-27T15:00:00.000Z',
+        observedTo: '2026-08-28T15:00:00.000Z',
+        accumulation: 'daily',
+        boundary: 'offset'
+      }
+    }
+  }
+  const r = foldKpi([earlier, ...EVENTS] as any, {
+    fromMs: T('2026-08-27T15:00:00.000Z'),
+    toMs: T('2026-08-29T02:00:00.000Z')
+  })
+  const g = r.energy?.generated
+  assert.ok(g)
+  assert.equal(g.counted, 1, '27→28 하루만 온전히 들었다')
+  assert.equal(g.kWh, 100)
+  assert.equal(g.notCounted?.periods, 4, '28→29 넷은 창의 끝을 넘는다')
+})

package/test/ingest-bench.test.ts

@@ -7,7 +7,8 @@
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { StateProjector, objectEvent, BIZSTEP, DISP } from '@operato/twin-kernel'
+import { StateProjector } from '@operato/twin-kernel'
+import { objectEvent, BIZSTEP, DISP } from '@operato/ops-contract'
 import { buildEntityDeltas } from '../shared/entity-delta.ts'
 
 const T0 = '2026-07-19T00:00:00.000Z'

package/test/ingest-wiring-guard.test.ts

@@ -0,0 +1,197 @@
+/*
+ * 유입 배선 감시 — **커널이 문을 열었는데 그 문으로 가는 길이 없는 것**을 잡는다.
+ *
+ * ── 왜 있나 (2026-08-30) ────────────────────────────────────────────────────
+ * 2026-08-29 하루에 이 부류가 다섯 번 났다. 커널에 새 어휘의 문을 만들고, 정규 유입의 갈림에
+ * 그 길을 내지 않은 것이다. 그때마다 레코드는 **거부되지도 않고 아무 문에도 들어가지 못한 채**
+ * 사라졌다 — 커넥터는 보냈다고 믿고, 화면은 값이 없다고 말한다. 사람이 하나씩 찾아냈다.
+ *
+ * 다음 날 같은 부류의 **두 번째 얼굴**이 드러났다. EPCIS 갈래는 「나머지 전부」라, 새 어휘를 그
+ * 목록에서 빼 주지 않으면 레코드가 제 문으로 가면서 **EPCIS 문으로도 들어가 거부된다.** 받아들여
+ * 지기도 하고 거부되기도 하는 상태가 되어, 유입 장부의 거부 수가 늘고 사람이 그것을 진짜 결함으로
+ * 읽는다.
+ *
+ * ── 무엇을 지키나 ──────────────────────────────────────────────────────────
+ *   ① 커널의 유입 함수마다 부르는 곳이 있다
+ *   ② 어휘마다 **정확히 한 문**으로 간다 — 어느 문에도 못 가거나 두 문에 걸치지 않는다
+ *
+ * ── 목록을 손으로 적지 않는다 ──────────────────────────────────────────────
+ * 커널이 내보내는 이름에서 읽는다. 커널이 문을 늘리면 이 시험이 먼저 빨갛게 난다. 손 목록을 두면
+ * 늘어난 것을 모른다 — 이 저장소가 이미 그 실패를 겪었다(`vocabulary-labels` 의 주석).
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+/* 유입 문과 판별 함수는 계약에 있다 — 커널은 엔진만 내보낸다(2026-08-30 층 분리). */
+import * as kernel from '@operato/ops-contract'
+import { ingestCanonicalRecords } from '../server/engine/canonical-ingest.ts'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const routerSource = readFileSync(join(here, '..', 'server', 'engine', 'canonical-ingest.ts'), 'utf-8')
+
+/**
+ * 정규 유입이 부르지 **않아도 되는** 것 — 각각 이유가 있다.
+ *
+ * 이 목록에 올릴 때는 이유를 함께 적는다. 이유 없이 올리면 이 시험은 아무것도 지키지 않는다.
+ */
+const NOT_ROUTED: Record<string, string> = {
+  /* 물류 어휘의 진입점 자체다 — 갈림이 이것을 부른다(이름이 `ingest` 하나뿐이라 규칙에 안 걸린다). */
+  ingest: 'EPCIS 어휘의 진입점. 갈림이 직접 부른다',
+  /* 마스터 데이터는 사건이 아니라 어휘 갱신이라 다른 경로로 간다. */
+  ingestMasterData: '사건이 아니라 어휘 갱신 — 참조 계층이 부른다'
+}
+
+test('★ 커널의 유입 함수마다 부르는 곳이 있다', () => {
+  const ingests = Object.keys(kernel).filter(n => /^ingest/.test(n))
+  assert.ok(ingests.length >= 8, `유입 함수를 못 읽었다(${ingests.length}개) — 커널을 다시 읽어야 한다`)
+
+  const unrouted = ingests.filter(n => !NOT_ROUTED[n] && !routerSource.includes(n))
+  assert.deepEqual(
+    unrouted,
+    [],
+    `커널이 문을 열었는데 정규 유입에 길이 없다:\n${unrouted.join('\n')}\n` +
+      '그 문으로 보내는 레코드는 거부되지도 않고 사라진다.\n' +
+      '갈림에 길을 내거나, 부르지 않아도 되는 이유를 NOT_ROUTED 에 적어라.'
+  )
+})
+
+test('부르지 않아도 되는 목록에 이유가 적혀 있다', () => {
+  for (const [name, why] of Object.entries(NOT_ROUTED)) {
+    assert.ok(why.trim().length > 5, `${name} 에 이유가 없다`)
+  }
+})
+
+/**
+ * 어휘마다 대표 레코드 하나 — **그 문으로만 가야 한다.**
+ *
+ * 값은 실제로 오는 모양에서 가져왔다(2026-08-29 실측). 지어낸 모양으로 검사하면 실제 레코드가
+ * 다른 문으로 가는 것을 놓친다.
+ */
+const NOW = '2026-08-30T00:00:00.000Z'
+const SAMPLES: { vocabulary: string; eventType: string; record: Record<string, unknown> }[] = [
+  {
+    vocabulary: '물품 관측(EPCIS)',
+    eventType: 'epcis.ObjectEvent',
+    record: {
+      epc: 'urn:epc:id:sgtin:0614141.107346.2017',
+      action: 'OBSERVE',
+      bizStep: 'urn:epcglobal:cbv:bizstep:storing',
+      readPoint: 'rack-1'
+    }
+  },
+  { vocabulary: '계량 표본', eventType: 'energy.measured', record: { meterId: 'incoming', kW: 100, at: NOW } },
+  {
+    vocabulary: '설비 상태',
+    eventType: 'energy.equipment',
+    record: { equipmentId: 'inv-1', generatedKW: 24.6, dcVoltage: 469.13, at: NOW }
+  },
+  { vocabulary: '발전 적산', eventType: 'energy.generated', record: { equipmentId: 'inv-1', kWh: 174, at: NOW } },
+  {
+    vocabulary: '마감된 사용 구간',
+    eventType: 'energy.usage.period',
+    record: {
+      meterId: 'incoming',
+      from: '2026-08-29T15:00:00.000Z',
+      to: '2026-08-29T16:00:00.000Z',
+      kWh: 474.48,
+      maxKW: 478.08,
+      unitPrice: 87.3,
+      currency: 'KRW',
+      basis: 'provider'
+    }
+  },
+  {
+    vocabulary: '요금 기준',
+    eventType: 'energy.tariff.basis',
+    record: {
+      /* 기준 선언은 **끝나지 않은 달**이 정상이다 — 사건 시각이 기간의 시작이라 미래에 적히지 않는다. */
+      from: '2026-07-31T15:00:00.000Z',
+      to: '2026-08-31T15:00:00.000Z',
+      billingDemandKW: 1650,
+      demandChargePerKW: 8320,
+      currency: 'KRW'
+    }
+  },
+  {
+    vocabulary: '청구서',
+    eventType: 'energy.bill',
+    record: {
+      /*
+       * 청구서는 **마감된 달**이다. 처음 이 표본은 끝나지 않은 8월을 담고 있었는데, 그것은 실제로
+       * 들어와 있던 잘못된 데이터를 그대로 베낀 것이었다(2026-08-30). 그 데이터 때문에 한 현장의
+       * 성과 구간이 미래로 밀려 화면이 비어 있었다. 표본이 결함을 베끼면 시험이 결함을 지킨다.
+       */
+      from: '2026-06-30T15:00:00.000Z',
+      to: '2026-07-31T15:00:00.000Z',
+      demandCharge: 13_728_000,
+      currency: 'KRW',
+      billingDemandKW: 1650
+    }
+  },
+  {
+    vocabulary: '발전 단가',
+    eventType: 'energy.generation.price',
+    record: { from: '2026-08-29T15:00:00.000Z', to: '2026-08-30T15:00:00.000Z', unitPrice: 148.61, currency: 'KRW' }
+  },
+  {
+    /*
+     * 라이브에서는 커널이 스스로 마감해 내지만, **지난 기록을 채울 때**는 밖에서 들어온다.
+     * 구간이 있으므로 적산의 문(`energy.generated`)이 아니라 이쪽으로 가야 한다 — 겹치면 지난
+     * 기록이 「지금 적산」으로도 읽혀 트윈의 시계가 과거로 끌린다.
+     */
+    vocabulary: '마감된 발전 기간',
+    eventType: 'energy.generation.period',
+    record: {
+      equipmentId: '001',
+      from: '2026-08-28T15:00:00.000Z',
+      to: '2026-08-29T15:00:00.000Z',
+      kWh: 394.3,
+      accumulation: 'daily'
+    }
+  }
+]
+
+test('★ 어휘마다 정확히 한 문으로 간다 — 사라지지도, 두 문에 걸치지도 않는다', () => {
+  const wrong: string[] = []
+  for (const s of SAMPLES) {
+    const r = ingestCanonicalRecords([s.record] as any, 't', NOW)
+    const accepted = (r.accepted as any[]).map(e => e.eventType)
+    if (r.rejected.length) {
+      wrong.push(`${s.vocabulary}: 거부됐다 — ${JSON.stringify(r.rejected[0]?.errors)}`)
+      continue
+    }
+    if (accepted.length !== 1) {
+      wrong.push(`${s.vocabulary}: 봉투가 ${accepted.length}개다(${accepted.join(', ')}) — 한 문으로만 가야 한다`)
+      continue
+    }
+    if (accepted[0] !== s.eventType) wrong.push(`${s.vocabulary}: ${s.eventType} 이어야 하는데 ${accepted[0]} 로 갔다`)
+  }
+  assert.deepEqual(wrong, [], `\n${wrong.join('\n')}`)
+})
+
+test('★ 한 배치에 모든 어휘가 섞여 와도 각자의 문으로 간다', () => {
+  const r = ingestCanonicalRecords(SAMPLES.map(s => s.record) as any, 't', NOW)
+  assert.deepEqual(r.rejected, [], `거부가 없어야 한다: ${JSON.stringify(r.rejected)}`)
+  assert.deepEqual(
+    (r.accepted as any[]).map(e => e.eventType).sort(),
+    SAMPLES.map(s => s.eventType).sort()
+  )
+})
+
+test('커널이 어휘를 늘리면 이 시험이 먼저 안다', () => {
+  /*
+   * 판별 함수의 수와 위 표본의 수가 어긋나면, 커널에 어휘가 늘었는데 여기 표본이 없다는 뜻이다.
+   * (EPCIS 안의 갈림 둘(담김·변환)은 한 어휘로 센다 — 같은 문으로 간다.)
+   */
+  const gates = Object.keys(kernel).filter(n => /^is.*Record$/.test(n))
+  const counted = gates.filter(n => !['isAggregationRecord', 'isTransformationRecord', 'isMasterDataRecord'].includes(n))
+  assert.equal(
+    counted.length,
+    SAMPLES.length,
+    `커널의 어휘는 ${counted.length}개인데 표본은 ${SAMPLES.length}개다:\n${counted.join(' ')}\n` +
+      '늘어난 어휘의 표본을 SAMPLES 에 더하라 — 그래야 그 어휘도 한 문으로 가는지 검사된다.'
+  )
+})