@things-factory/headless-twin 10.0.17 → 10.0.19

package/test/hook-sequence.test.ts

@@ -0,0 +1,333 @@
+/*
+ * **밀어 받는 길의 번호** — 빠진 것을 알아채고, 재기동을 넘어 이어받는다.
+ *
+ * ── 왜 이 시험이 있나 (2026-08-31) ────────────────────────────────────────
+ * 훅이 놓치는 것은 예외가 아니라 정상이다. 우리가 내려가 있을 때, 그쪽이 못 보냈을 때, 네트워크가
+ * 끊겼을 때. 그 대비가 드문 폴링 하나뿐이었다 — 폴링은 「놓친 것이 있나」를 값으로 알아내는 것이고,
+ * 번호는 빠진 것을 곧바로 안다.
+ *
+ * ── 왜 순수 함수 시험만으로 부족한가 ─────────────────────────────────────
+ * 번호 판정 자체는 계약 쪽에서 확인한다(`ops-contract/test/webhook-contract.test.ts`). 여기서 보는
+ * 것은 **배선**이다 — 판정이 응답이 되는가, 커서에 적히는가, 다시 세운 뒤에 읽히는가.
+ *
+ * 이 저장소에서 가장 자주 나는 결함이 「자리는 있고 길이 없다」이고, 커서가 정확히 그 모양이었다.
+ * `TwinReference.liveCursor` 는 재기동을 넘어 사는 자리인데 **훅 경로가 그것을 읽지도 쓰지도 않았다.**
+ * 쓰는 곳은 폴링 하나뿐이었다.
+ *
+ * 그래서 마지막 시험이 저장본을 그대로 두고 **핸들러를 새로 부른다.** 한 프로세스 안에서만 확인하면
+ * 「적히나」는 보이지만 「다시 세우면 읽히나」는 보이지 않는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { WEBHOOK_STATUS, webhookSenderAction } from '@operato/ops-contract'
+
+import { handleHook, type HookStore } from '../server/service/reference/reference-hook.js'
+import { registerAdapterType, getAdapter } from '../server/service/reference/reference-adapter.js'
+
+const DOMAIN = 'd-1'
+const SOURCE = 'operato-mes'
+const TWIN = 'twin-a'
+const SECRET = 'shared-secret'
+const SCOPE = 'EVENTS'
+/** 커서 열쇠에는 트윈이 함께 들어간다 — 연결 하나가 트윈 여럿을 만든다. */
+const KEY = `${TWIN}::${SCOPE}`
+
+/** 보낸 봉투를 그대로 레코드로 내는 커넥터 — 옮길 것이 없으므로 번호만 꺼낸다. */
+const ADAPTER_TYPE = 'test-numbered-push'
+if (!getAdapter(ADAPTER_TYPE)) {
+  registerAdapterType({
+    type: ADAPTER_TYPE,
+    label: 'numbered push (test)',
+    handleInbound: (_cfg: any, _site: any, body: any) => ({
+      items: body?.items ?? [{ record: { moverId: 'eq-1', kind: 'press', status: 'idle' }, seq: body?.seq }],
+      scope: body?.scope
+    })
+  } as any)
+}
+
+/** 저장본 하나 — 프로세스가 아니라 여기에 산다. 그래서 핸들러를 새로 불러도 남는다. */
+function makeStore(initial?: unknown): HookStore & { row: any } {
+  const row = {
+    id: 'ref-1',
+    source: SOURCE,
+    adapterType: ADAPTER_TYPE,
+    connectionConfig: { hookSecret: SECRET },
+    scopeSpec: { produced: [{ siteId: 'site-a', instanceId: TWIN }] },
+    liveCursor: initial
+  }
+  return {
+    row,
+    load: async (domainId: string, source: string) => (domainId === DOMAIN && source === SOURCE ? row : null),
+    saveCursor: async (refId: string, cursor: unknown) => {
+      assert.equal(refId, row.id)
+      /* 저장소를 흉내 내는 것이라 참조를 그대로 두지 않고 복사해 넣는다 — 같은 객체면 안 적혀도 통과한다. */
+      row.liveCursor = JSON.parse(JSON.stringify(cursor))
+    }
+  }
+}
+
+const applied = (_id: string, records: unknown[]) => ({ applied: records.length, duplicates: 0, rejected: [] })
+
+function push(store: HookStore, seq: number | undefined, opts: { scope?: string; ingest?: any } = {}) {
+  return handleHook({
+    domainId: DOMAIN,
+    source: SOURCE,
+    instanceId: TWIN,
+    headers: { 'x-twin-hook-secret': SECRET },
+    body: { seq, scope: 'scope' in opts ? opts.scope : SCOPE },
+    nowMs: Date.parse('2026-08-31T02:00:00.000Z'),
+    ingest: opts.ingest ?? applied,
+    store
+  })
+}
+
+test('★ 첫 봉투를 받고 그 번호를 커서에 적는다', async () => {
+  const store = makeStore()
+  const out = await push(store, 918342)
+
+  assert.equal(out.status, WEBHOOK_STATUS.ok)
+  assert.equal(out.body.sequenceChecked, true)
+  assert.equal(out.body.lastSeq, 918342)
+  assert.equal(store.row.liveCursor?.streams?.[KEY]?.seq, 918342, '커서에 적히지 않았다')
+})
+
+test('★ 건너뛴 번호는 409 로 답하고 그 앞부터 달라고 한다', async () => {
+  const store = makeStore({ streams: { [KEY]: { seq: 4 } } })
+  const out = await push(store, 7)
+
+  assert.equal(out.status, WEBHOOK_STATUS.sequenceGap)
+  assert.equal(out.body.expectedSeq, 5)
+  assert.equal(out.body.lastSeq, 4)
+  assert.equal(out.body.scope, SCOPE, '어느 줄의 번호인지 함께 말한다')
+})
+
+test('★ 구멍이 났을 때 커서를 올리지 않는다 — 올리면 그 구간이 영영 안 온다', async () => {
+  const store = makeStore({ streams: { [KEY]: { seq: 4 } } })
+  await push(store, 7)
+  assert.equal(store.row.liveCursor.streams[KEY].seq, 4)
+})
+
+test('★ 이미 본 번호는 받아들이되 커서를 뒤로 끌지 않는다 — 재전송이 정상 동작이다', async () => {
+  const store = makeStore({ streams: { [KEY]: { seq: 9 } } })
+  const out = await push(store, 9)
+
+  assert.equal(out.status, WEBHOOK_STATUS.ok)
+  assert.equal(store.row.liveCursor.streams[KEY].seq, 9)
+})
+
+test('★ 반영되지 않았으면 커서를 올리지 않는다 — 트윈이 안 도는 사이의 번호를 지나치면 그 구간이 빈다', async () => {
+  const store = makeStore({ streams: { [KEY]: { seq: 4 } } })
+  const out = await push(store, 5, { ingest: () => ({ applied: 0, duplicates: 0, rejected: [] }) })
+
+  assert.equal(out.status, WEBHOOK_STATUS.notLive)
+  assert.equal(store.row.liveCursor.streams[KEY].seq, 4, '한 건도 안 들어갔는데 번호가 올라갔다')
+})
+
+test('★ 번호를 매기지 않는 원본은 확인하지 않고, 확인하지 않았다고 말한다', async () => {
+  /* chef · ppms 가 그렇다. 「확인했고 이상 없다」와 같아 보이면 어느 연결이 지켜지는지 알 수 없다. */
+  const store = makeStore()
+  const out = await push(store, undefined, { scope: undefined })
+
+  assert.equal(out.status, WEBHOOK_STATUS.ok)
+  assert.equal(out.body.sequenceChecked, false)
+  assert.equal(store.row.liveCursor, undefined, '번호가 없으면 커서를 만들지 않는다')
+})
+
+test('★ 번호만 있고 어느 줄인지 없으면 확인하지 않는다 — 짐작한 열쇠는 줄이 늘면 어긋난다', async () => {
+  const store = makeStore()
+  const out = await push(store, 918342, { scope: undefined })
+
+  assert.equal(out.status, WEBHOOK_STATUS.ok)
+  assert.equal(out.body.sequenceChecked, false)
+})
+
+test('★ 줄마다 번호가 따로 간다 — 두 줄이 한 커서에 섞이면 끊임없이 「빠졌다」가 된다', async () => {
+  const store = makeStore()
+  await push(store, 5, { scope: 'EVENTS' })
+  await push(store, 1, { scope: 'MASTER' })
+
+  assert.equal(store.row.liveCursor.streams[`${TWIN}::EVENTS`].seq, 5)
+  assert.equal(store.row.liveCursor.streams[`${TWIN}::MASTER`].seq, 1)
+
+  /* MASTER 의 1 이 EVENTS 의 5 를 되돌리지 않았으므로 EVENTS 6 이 그대로 이어진다. */
+  assert.equal((await push(store, 6, { scope: 'EVENTS' })).status, WEBHOOK_STATUS.ok)
+})
+
+test('★ 재기동을 넘어 이어받는다 — 저장본만 남기고 핸들러를 새로 부른다', async () => {
+  const first = makeStore()
+  await push(first, 5)
+  const saved = JSON.parse(JSON.stringify(first.row.liveCursor))
+
+  /* 프로세스가 새로 선 것으로 본다 — 앞의 저장소 객체는 버리고 저장본만 물려준다. */
+  const second = makeStore(saved)
+
+  assert.equal((await push(second, 7)).status, WEBHOOK_STATUS.sequenceGap, '이어받지 못하면 7 이 그냥 통과한다')
+  assert.equal((await push(second, 6)).status, WEBHOOK_STATUS.ok)
+  assert.equal(second.row.liveCursor.streams[KEY].seq, 6)
+})
+
+test('★ 커서를 적지 못해도 이미 들어간 사실을 무르지 않는다 — 다음 번호에서 구멍으로 드러난다', async () => {
+  const store = makeStore()
+  const broken: HookStore = { load: store.load, saveCursor: async () => { throw new Error('disk full') } }
+
+  const out = await push(broken, 5)
+  assert.equal(out.status, WEBHOOK_STATUS.ok, '유입은 이미 끝났다 — 커서를 못 적은 것이 그것을 무를 이유가 아니다')
+})
+
+/* ── 한 요청에 봉투 여럿 ──────────────────────────────────────────────────── */
+
+/** 번호가 붙은 봉투 여럿을 한 요청으로 보낸다 — 밀어 주는 쪽은 한 건씩 보내지 않는다. */
+function pushBatch(store: HookStore, seqs: number[], opts: { scope?: string; ingest?: any } = {}) {
+  return handleHook({
+    domainId: DOMAIN,
+    source: SOURCE,
+    instanceId: TWIN,
+    headers: { 'x-twin-hook-secret': SECRET },
+    body: {
+      scope: 'scope' in opts ? opts.scope : SCOPE,
+      items: seqs.map(seq => ({ seq, record: { moverId: `eq-${seq}`, kind: 'press', status: 'idle' } }))
+    },
+    nowMs: Date.parse('2026-08-31T02:00:00.000Z'),
+    ingest: opts.ingest ?? applied,
+    store
+  })
+}
+
+test('★ 배치 가운데가 빠지면 그 앞까지만 받는다 — 구멍 뒤를 받으면 그 구멍이 영영 안 메워진다', async () => {
+  const store = makeStore({ streams: { [KEY]: { seq: 4 } } })
+  const taken: unknown[][] = []
+  const out = await pushBatch(store, [5, 6, 9, 10], {
+    ingest: (_id: string, records: unknown[]) => {
+      taken.push(records)
+      return { applied: records.length, duplicates: 0, rejected: [] }
+    }
+  })
+
+  assert.equal(taken[0].length, 2, '5·6 만 넣어야 한다')
+  assert.equal(out.status, WEBHOOK_STATUS.sequenceGap)
+  assert.equal(out.body.expectedSeq, 7)
+  assert.equal(out.body.lastSeq, 6, '앞의 것은 받았다는 것을 함께 말한다 — 안 그러면 5·6 을 또 보낸다')
+  assert.equal(store.row.liveCursor.streams[KEY].seq, 6)
+})
+
+test('★ 배치 전체가 이어지면 끝 번호가 커서가 된다', async () => {
+  const store = makeStore({ streams: { [KEY]: { seq: 4 } } })
+  const out = await pushBatch(store, [5, 6, 7])
+
+  assert.equal(out.status, WEBHOOK_STATUS.ok)
+  assert.equal(out.body.lastSeq, 7)
+  assert.equal(store.row.liveCursor.streams[KEY].seq, 7)
+})
+
+test('★ 첫 봉투부터 구멍이면 아무것도 넣지 않고 커서도 그대로다', async () => {
+  const store = makeStore({ streams: { [KEY]: { seq: 4 } } })
+  let called = false
+  const out = await pushBatch(store, [9, 10], {
+    ingest: () => {
+      called = true
+      return { applied: 2, duplicates: 0, rejected: [] }
+    }
+  })
+
+  assert.equal(called, false, '받을 것이 없는데 유입을 불렀다')
+  assert.equal(out.status, WEBHOOK_STATUS.sequenceGap)
+  assert.equal(out.body.expectedSeq, 5)
+  assert.equal(store.row.liveCursor.streams[KEY].seq, 4)
+})
+
+test('★ 번호가 있는 봉투와 없는 봉투를 섞으면 받지 않는다 — 반쯤 확인한 것을 확인했다고 말하지 않는다', async () => {
+  const store = makeStore()
+  const out = await handleHook({
+    domainId: DOMAIN,
+    source: SOURCE,
+    instanceId: TWIN,
+    headers: { 'x-twin-hook-secret': SECRET },
+    body: { scope: SCOPE, items: [{ seq: 1, record: {} }, { record: {} }] },
+    nowMs: Date.parse('2026-08-31T02:00:00.000Z'),
+    ingest: applied,
+    store
+  })
+
+  assert.equal(out.status, WEBHOOK_STATUS.badPayload)
+  assert.match(String(out.body.error), /mixed batch/)
+})
+
+/* ── 일부만 떨어졌을 때 ───────────────────────────────────────────────────── */
+
+const REJECT_ONE = (_id: string, records: unknown[]) => ({
+  applied: records.length - 1,
+  duplicates: 0,
+  rejected: [{ record: records[records.length - 1], errors: ['equipment: 계약에 없는 필드 — foo'] }]
+})
+
+test('★ 일부가 떨어지면 422 로 답하고 무엇이 떨어졌는지 함께 준다', async () => {
+  const store = makeStore({ streams: { [KEY]: { seq: 4 } } })
+  const out = await pushBatch(store, [5, 6], { ingest: REJECT_ONE })
+
+  assert.equal(out.status, WEBHOOK_STATUS.partial)
+  assert.equal((out.body.rejected as any[]).length, 1)
+  assert.match(String((out.body.rejected as any[])[0].errors[0]), /계약에 없는 필드/)
+})
+
+test('★ 떨어진 것이 있어도 다시 보내라고 하지 않는다 — 나머지는 이미 들어갔다', async () => {
+  assert.equal(webhookSenderAction(WEBHOOK_STATUS.partial), 'partial')
+  assert.notEqual(webhookSenderAction(WEBHOOK_STATUS.partial), 'resend-from')
+})
+
+test('★ 일부가 떨어져도 받은 데까지 커서가 간다 — 안 그러면 그 구간이 매번 다시 온다', async () => {
+  const store = makeStore({ streams: { [KEY]: { seq: 4 } } })
+  const out = await pushBatch(store, [5, 6], { ingest: REJECT_ONE })
+
+  assert.equal(out.body.lastSeq, 6)
+  assert.equal(store.row.liveCursor.streams[KEY].seq, 6)
+})
+
+test('★ 구멍과 떨어진 것이 함께 나면 한 응답에 둘 다 싣는다', async () => {
+  /* 두 소식이 갈라져 오면 보내는 쪽은 둘 중 하나만 한다. */
+  const store = makeStore({ streams: { [KEY]: { seq: 4 } } })
+  const out = await pushBatch(store, [5, 6, 9], { ingest: REJECT_ONE })
+
+  assert.equal(out.status, WEBHOOK_STATUS.sequenceGap, '연속성이 먼저다 — 그것이 다음에 무엇을 보낼지 정한다')
+  assert.equal(out.body.expectedSeq, 7)
+  assert.equal(out.body.lastSeq, 6)
+  assert.equal((out.body.rejected as any[]).length, 1, '떨어진 것도 함께 알린다')
+})
+
+test('전부 통과하면 떨어진 목록이 빈다 — 없는 것과 안 본 것이 같아 보이지 않게', async () => {
+  const store = makeStore()
+  const out = await pushBatch(store, [1, 2])
+  assert.deepEqual(out.body.rejected, [])
+})
+
+test('★ 한 연결이 만든 두 트윈이 계수기를 함께 쓰지 않는다', async () => {
+  /*
+   * 커서는 연결마다 한 행에 산다(`TwinReference.liveCursor`). 그런데 연결 하나가 트윈 여럿을 만든다.
+   * 보내는 쪽의 단위 이름만으로 열쇠를 잡으면 두 공장이 한 계수기를 쓰고, B 의 1 이 A 의 5 뒤에서
+   * 「이미 본 번호」로 버려진다.
+   */
+  const store = makeStore()
+  const other = 'twin-b'
+  store.row.scopeSpec.produced.push({ siteId: 'site-b', instanceId: other })
+
+  const send = (instanceId: string, seq: number) =>
+    handleHook({
+      domainId: DOMAIN,
+      source: SOURCE,
+      instanceId,
+      headers: { 'x-twin-hook-secret': SECRET },
+      body: { scope: SCOPE, items: [{ seq, record: { moverId: 'eq-1', kind: 'press', status: 'idle' } }] },
+      nowMs: Date.parse('2026-08-31T02:00:00.000Z'),
+      ingest: applied,
+      store
+    })
+
+  await send(TWIN, 5)
+  const first = await send(other, 1)
+  assert.equal(first.status, WEBHOOK_STATUS.ok, 'B 공장의 첫 봉투가 A 공장의 번호에 걸려 버려졌다')
+
+  assert.equal(store.row.liveCursor.streams[`${TWIN}::${SCOPE}`].seq, 5)
+  assert.equal(store.row.liveCursor.streams[`${other}::${SCOPE}`].seq, 1)
+
+  assert.equal((await send(TWIN, 6)).status, WEBHOOK_STATUS.ok, 'A 공장이 B 의 번호에 끌려갔다')
+})

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 에 더하라 — 그래야 그 어휘도 한 문으로 가는지 검사된다.'
+  )
+})

package/test/kpi-fold.test.ts

@@ -1345,3 +1345,84 @@ test('셋 다 없으면 이 칸을 만들지 않는다 — 빈 값을 지어내
   } as any)
   assert.equal(k.energy?.billingDemand, undefined)
 })
+
+test('★ 관측한 최고가 청구 기준을 넘으면 얼마나 넘었는지와 언제까지의 값인지를 낸다', () => {
+  /* 기본요금은 이 값으로 다시 정해진다 — 지금 줄여도 되돌아가지 않는다. */
+  const k = foldKpi([usagePeriod(400, 0, 1800, { maxKW: 1200 }), usagePeriod(400, 1800, 3600, { maxKW: 1700 })], WINDOW, {
+    tariff: { demandChargePerKW: 8_320, billingDemandKW: 1650, currency: 'KRW' }
+  } as any)
+  const e = k.energy?.billingDemand?.exceeded
+  assert.equal(e?.peakKW, 1700)
+  assert.equal(e?.overKW, 50)
+  assert.equal(e?.observedTo, at(3600), '이 최고값이 언제까지의 것인지')
+})
+
+test('넘지 않으면 그 칸을 만들지 않는다', () => {
+  const k = foldKpi([usagePeriod(400, 0, 3600, { maxKW: 1200 })], WINDOW, {
+    tariff: { demandChargePerKW: 8_320, billingDemandKW: 1650, currency: 'KRW' }
+  } as any)
+  assert.equal(k.energy?.billingDemand?.exceeded, undefined)
+})
+
+test('청구서가 말한 기준으로 넘었는지 본다 — 선언이 아니다', () => {
+  const k = foldKpi([usagePeriod(400, 0, 3600, { maxKW: 1300 })], WINDOW, {
+    tariff: { demandChargePerKW: 8_320, billingDemandKW: 1650, currency: 'KRW' },
+    lastBill: { to: at(-86400), billingDemandKW: 1200 }
+  } as any)
+  assert.equal(k.energy?.billingDemand?.kW, 1200)
+  assert.equal(k.energy?.billingDemand?.exceeded?.overKW, 100)
+})
+
+/* ── 이용률 (2026-08-30) ───────────────────────────────────────────────────
+ *
+ * ★ 분모가 어느 정격인지가 값의 뜻을 바꾼다. 붙어 있는 원본은 직류로 나눠 2.2% 를 보여 주는데,
+ *   교류로 나누면 4.08% 다. 같은 발전소를 두 화면에서 보는 사람이 두 배 다른 수를 본다.
+ *
+ * 그래서 커널은 교류를 먼저 쓰되(계통으로 나가는 양은 교류 정격을 넘을 수 없다) **어느 쪽으로
+ * 나눴는지를 값과 함께 낸다.**
+ */
+
+const generationPeriod = (kWh: number, fromSec: number, toSec: number): KpiEvent => ({
+  eventType: 'energy.generation.period',
+  eventTime: at(toSec),
+  payload: {
+    data: { equipmentId: 'inv-1', kWh, periodStart: at(fromSec), periodEnd: at(toSec), observedFrom: at(fromSec), observedTo: at(toSec) }
+  }
+})
+
+test('★ 이용률은 만든 양 ÷ (정격 × 그 기간의 시간)', () => {
+  /* 한 시간에 63.8kWh · 정격 127.6kW → 50% */
+  const k = foldKpi([generationPeriod(63.8, 0, 3600)], WINDOW, {
+    generationRated: { kW: 127.6, basis: 'ac', from: 'location' }
+  } as any)
+  const cf = k.energy?.generated?.capacityFactor
+  assert.equal(cf?.value, 0.5)
+  assert.equal(cf?.ratedKW, 127.6)
+  assert.equal(cf?.hours, 1)
+})
+
+test('★ 어느 정격으로 나눴는지 함께 낸다 — 두 화면의 수가 달라도 이유를 말할 수 있게', () => {
+  const k = foldKpi([generationPeriod(63.8, 0, 3600)], WINDOW, {
+    generationRated: { kW: 234.35, basis: 'dc', from: 'location' }
+  } as any)
+  assert.equal(k.energy?.generated?.capacityFactor?.basis, 'dc')
+  assert.equal(k.energy?.generated?.capacityFactor?.from, 'location')
+})
+
+test('★ 창 길이가 아니라 센 기간들의 길이로 나눈다', () => {
+  /*
+   * 한 시간짜리 기간 하나만 센 창에서 창 길이(1시간)로 나누는 것과 같지만, 기간이 창보다 짧으면
+   * 달라진다. 창 길이로 나누면 그 기간이 창 전체에 걸쳐 있었던 것처럼 작아진다.
+   */
+  const k = foldKpi([generationPeriod(63.8, 0, 1800)], WINDOW, {
+    generationRated: { kW: 127.6, basis: 'ac', from: 'location' }
+  } as any)
+  assert.equal(k.energy?.generated?.capacityFactor?.hours, 0.5)
+  assert.equal(k.energy?.generated?.capacityFactor?.value, 1, '30분에 정격만큼 만들었으면 100%다')
+})
+
+test('정격이 없으면 이용률을 내지 않는다 — 0 이나 짐작을 만들지 않는다', () => {
+  const k = foldKpi([generationPeriod(63.8, 0, 3600)], WINDOW)
+  assert.equal(k.energy?.generated?.capacityFactor, undefined)
+  assert.equal(k.energy?.generated?.kWh, 63.8, '발전량 자체는 그대로 낸다')
+})

package/test/live-mirror-parity.test.ts

@@ -11,7 +11,9 @@
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { WmsKernel, StateProjector, deriveAttentions, computeOee } from '@operato/twin-kernel'
+import { WmsKernel, StateProjector, deriveAttentions } from '@operato/twin-kernel'
+/* OEE 공식은 계약에 있다 — 시뮬·미러·MES 셋이 같은 것을 부른다. */
+import { computeOee } from '@operato/ops-contract'
 import { masterToTwin } from '../server/service/reference/reference-master.ts'
 import { buildEntityDeltas } from '../shared/entity-delta.ts'
 import { withLiveAttentions } from '../server/engine/live-attentions.ts'
@@ -209,12 +211,13 @@ test('★ OEE derive: 공유 공식 computeOee 가 공급된 카운터로 OEE
    * 없앴다. 이제 창을 모르면 잰 시간이 없으므로, 재생산에는 창이 함께 와야 한다. 라이브 공급자가
    * 실제로 하는 일이 그것이다(누적기는 첫 이벤트 시각을 창으로 낸다).
    */
-  const planned = o.runMs + o.setupMs + o.downMs + o.idleMs
+  const planned = o.runMs + o.setupMs + o.downMs + o.delayMs
   const derived = computeOee(
     { runMs: o.runMs, setupMs: o.setupMs, downMs: o.downMs, goodCount: o.goodCount, scrapCount: o.scrapCount, metricsSinceMs: 0 },
     planned
   )
-  const near = (a: number, b: number) => Math.abs(a - b) < 1e-6
+  /* 세 비율은 근거가 없으면 없다 — 양쪽 다 없는 것도 재생산이다(계약 0.5.0). */
+  const near = (a?: number, b?: number) => (a == null && b == null) || (a != null && b != null && Math.abs(a - b) < 1e-6)
   assert.ok(near(derived.availability, o.availability), `availability 재생산 (${derived.availability} vs ${o.availability})`)
   assert.ok(near(derived.performance, o.performance), 'performance 재생산')
   assert.ok(near(derived.quality, o.quality), 'quality 재생산')

package/test/local-declarations.test.ts

@@ -327,7 +327,8 @@ test('이 겹의 어휘는 local 이다 — site·facility 로 되돌아가지
 test('축의 두 낱말이 계약에 선언돼 있다 — 얹혀 다니는 필드가 아니다', async () => {
   /* 예전에는 source 표식이 커널 계약에 없는 필드로 얹혀 다녔다 — 소비처가 any 로 읽고, 상태에 정말
      실리는지 아무도 검사할 수 없었다. */
-  const kernel: any = await import('@operato/twin-kernel')
+  /* 속성 어휘는 계약에 있다 — 커널은 엔진만 내보낸다(2026-08-30 층 분리). */
+  const contract: any = await import('@operato/ops-contract')
   const { model } = applyLocalDeclarations(
     { locations: [{ id: 'incoming-1', type: 'incoming' }] },
     [{ target: 'location', id: 'incoming-1', properties: [{ id: 'contract.kW', value: '3500' }] }]
@@ -335,7 +336,7 @@ test('축의 두 낱말이 계약에 선언돼 있다 — 얹혀 다니는 필
   const p = (model.locations[0] as any).properties[0]
   /* 계약이 정한 두 값 외에는 쓰지 않는다. */
   assert.ok(['reference', 'local'].includes(p.source), '표식은 reference|local 뿐이다')
-  assert.ok(kernel.EMS_PROPERTY, '커널 계약을 실제로 읽고 있다')
+  assert.ok(contract.EMS_PROPERTY, '계약을 실제로 읽고 있다')
 })
 
 test('옛 표식이 구워진 값을 원천 값으로 오인하지 않는다 — 표식의 종류를 따지지 않는다', () => {