@things-factory/headless-twin 10.0.15 → 10.0.18

package/test/event-type-split.test.ts

@@ -0,0 +1,155 @@
+/*
+ * ★ 여러 종류를 시각순으로 — 거르는 축과 정렬 축이 어긋나면 색인이 버려진다.
+ *
+ * ── 실측 (2026-08-28 · 승화푸드 저널 3,374,894행) ───────────────────────────
+ *   종류 8개 IN + 시각순 50건   SEARCH USING INDEX ix_twin_event_1 (domain, instance)   37.181초 · 0건
+ *   같은 조건 · 정렬 없음        SEARCH USING INDEX ix_twin_event_7 (…, event_type=?)     0.003초
+ *   종류 하나 + 시각순           SEARCH USING INDEX ix_twin_event_7 (…, event_type=?)     0.003초
+ *
+ * 정렬을 붙이는 순간 여러 종류의 순서를 합칠 방법이 없어 시각 색인으로 337만 행을 걸으며 행마다 종류를
+ * 확인한다. 그 트윈에 에너지 사건은 **0건**이다 — 없는 것을 찾느라 37초를 쓴다.
+ *
+ * 360 이력이 64초였던 것과 같은 부류다. 고침도 같은 성질이다: **있는 색인을 쓰게 한다.**
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { splitShape } from '../server/service/twin-journal/event-type-split-shape.js'
+
+const dir = (...p: string[]) => join(import.meta.dirname, '..', 'server', ...p)
+const split = readFileSync(dir('service', 'twin-journal', 'event-type-split.ts'), 'utf8')
+const shape = readFileSync(dir('service', 'twin-journal', 'event-type-split-shape.ts'), 'utf8')
+const journal = readFileSync(dir('service', 'twin-journal', 'twin-journal-query.ts'), 'utf8')
+
+const DESC = [{ name: 'eventTime', desc: true }]
+const ENERGY = ['energy.measured', 'energy.equipment', 'energy.demand.window', 'energy.peak']
+
+test('★ 에너지 원장이 보내는 모양이 이 갈래로 간다', () => {
+  const shape = splitShape({ filters: [{ name: 'eventType', operator: 'in', value: ENERGY }] }, DESC)
+  assert.ok(shape)
+  assert.deepEqual(shape!.eventTypes, ENERGY)
+})
+
+test('시간창이 함께 와도 간다 — 화면이 구간을 지정한다', () => {
+  const shape = splitShape(
+    {
+      filters: [
+        { name: 'eventType', operator: 'in', value: ENERGY },
+        { name: 'eventTime', operator: 'between', value: ['2026-08-01T00:00:00.000Z', '2026-08-02T00:00:00.000Z'] }
+      ]
+    },
+    DESC
+  )
+  assert.ok(shape)
+  assert.equal(shape!.fromTime?.toISOString(), '2026-08-01T00:00:00.000Z')
+  assert.equal(shape!.untilTime?.toISOString(), '2026-08-02T00:00:00.000Z')
+})
+
+test('★ 맞지 않는 물음은 일반 경로로 보낸다 — 억지로 답하면 목록이 알리지 않고 달라진다', () => {
+  const cases: [string, any, any[]][] = [
+    ['종류가 하나', { filters: [{ name: 'eventType', operator: 'in', value: ['a'] }] }, DESC],
+    ['종류가 너무 많다', { filters: [{ name: 'eventType', operator: 'in', value: Array.from({ length: 13 }, (_, i) => `t${i}`) }] }, DESC],
+    ['종류 필터가 없다', { filters: [] }, DESC],
+    ['정확일치', { filters: [{ name: 'eventType', operator: 'eq', value: 'a' }] }, DESC],
+    ['제외 목록', { filters: [{ name: 'eventType', operator: 'notin_with_null', value: ENERGY }] }, DESC],
+    ['자유 검색어', { search: '전력', filters: [{ name: 'eventType', operator: 'in', value: ENERGY }] }, DESC],
+    ['다른 필터가 섞였다', { filters: [{ name: 'eventType', operator: 'in', value: ENERGY }, { name: 'epc', operator: 'search', value: 'x' }] }, DESC],
+    ['리비전 정렬', { filters: [{ name: 'eventType', operator: 'in', value: ENERGY }] }, [{ name: 'revision', desc: true }]],
+    ['오름차순', { filters: [{ name: 'eventType', operator: 'in', value: ENERGY }] }, [{ name: 'eventTime', desc: false }]],
+    ['못 읽는 시각', { filters: [{ name: 'eventType', operator: 'in', value: ENERGY }, { name: 'eventTime', operator: 'lte', value: '어제' }] }, DESC]
+  ]
+  for (const [why, params, sortings] of cases) {
+    assert.equal(splitShape(params, sortings), null, `${why} 는 일반 경로로 가야 한다`)
+  }
+})
+
+test('★ 종류를 정확일치로 묻는다 — 이 한 줄이 색인을 쓰게 한다', () => {
+  assert.match(split, /andWhere\('e\.eventType = :eventType', \{ eventType \}\)/)
+  assert.doesNotMatch(split, /eventType IN/, '나눈 뒤에 다시 여러 값으로 묻지 않는다')
+  /* 정렬 축이 색인의 마지막 칸과 같아야 한다. */
+  assert.match(split, /orderBy\('e\.eventTime', 'DESC'\)/)
+})
+
+test('★ 한 갈래라도 못 읽으면 반쪽을 전부인 것처럼 내지 않는다', () => {
+  assert.match(split, /if \(!page\) return null/)
+})
+
+test('★ 이어 읽기 지점을 모든 갈래에 같이 건다', () => {
+  /* 갈래마다 다르게 걸면 어떤 종류는 이미 지나간 구간을 다시 낸다. */
+  assert.match(split, /e\.eventTime < :curAt OR \(e\.eventTime = :curAt AND e\.\$\{tiebreak\} < :curTie\)/)
+  assert.match(split, /if \(!cursor\) return null/, '못 읽는 커서로는 답하지 않는다')
+})
+
+test('★ 나눌 수를 제한한다 — 나누는 것이 손해가 되는 지점이 있다', () => {
+  assert.match(shape, /export const MAX_SPLIT = 24/)
+  assert.match(split, /if \(!pairs \|\| pairs > MAX_SPLIT\) return null/)
+})
+
+test('★ 화면이 부르는 자리에 붙어 있다', () => {
+  assert.match(journal, /const split = splitShape\(effective, effective\.sortings \?\? \[\]\)/)
+  assert.match(journal, /await eventTypeSplitPage\(domain\.id, instanceIds, split, limit, tiebreak, effective\.pagination\?\.after\)/)
+  /* 파생 테이블 갈래보다 뒤, 일반 저널 질의보다 앞이어야 한다. */
+  assert.ok(journal.indexOf('readModelPage(domain.id') < journal.indexOf('splitShape(effective'))
+  assert.ok(journal.indexOf('splitShape(effective') < journal.indexOf('const qb = getQueryBuilderFromListParams'))
+})
+
+test('★ 걷을 조건이 적혀 있다 — 부르는 데가 없어지면 지운다', () => {
+  /*
+   * 앱에서 종류를 여러 값으로 보내는 곳은 에너지 원장 한 곳뿐이다. 그 화면이 종류를 하나씩 고르는
+   * 모양으로 바뀌면 이 갈래는 아무도 부르지 않는다 — 그때 지워야 한다. 그 조건을 코드에 적어 두지
+   * 않으면 아무것도 하지 않는 갈래가 무언가를 받쳐 주는 것처럼 남는다.
+   */
+  assert.match(split, /이 갈래를 걷을 조건/)
+  assert.match(split, /그때 \*\*지운다\.\*\*/)
+})
+
+/* ── 공정 단계 칩 (2026-08-29) ─────────────────────────────────────────────
+ *
+ * ★ 칩을 고른 순간 이 갈래가 꺼져서, **고르지 않은 쪽이 더 빨랐다.**
+ *
+ * 원장은 종류 넷을 담아 묻고 그 위에 단계 칩을 겹친다. 앞 판은 `bizStep` 필터를 만나면 모양을
+ * 알아보지 못해 예전 경로로 떨어졌다 — 좁혀 물으면 느려지는 화면이 된다.
+ */
+
+test('공정 단계 하나로 좁혀도 갈래 경로가 답한다', () => {
+  const shape = splitShape(
+    {
+      filters: [
+        { name: 'eventType', operator: 'in', value: ['epcis.ObjectEvent', 'epcis.AggregationEvent'] },
+        { name: 'bizStep', operator: 'eq', value: 'shipping' }
+      ]
+    } as any,
+    [{ name: 'eventTime', desc: true }] as any
+  )
+  assert.ok(shape, '이 모양을 알아봐야 한다')
+  assert.equal(shape?.bizStep, 'shipping')
+  assert.deepEqual(shape?.eventTypes, ['epcis.ObjectEvent', 'epcis.AggregationEvent'])
+})
+
+test('단계를 여러 값으로 주면 답하지 않는다 — 갈래가 곱해진다', () => {
+  const shape = splitShape(
+    {
+      filters: [
+        { name: 'eventType', operator: 'in', value: ['epcis.ObjectEvent', 'epcis.AggregationEvent'] },
+        { name: 'bizStep', operator: 'in', value: ['shipping', 'receiving'] }
+      ]
+    } as any,
+    [{ name: 'eventTime', desc: true }] as any
+  )
+  assert.equal(shape, null)
+})
+
+test('빈 단계 값은 받지 않는다 — 모든 행을 뜻하는지 없는 단계를 뜻하는지 알 수 없다', () => {
+  const shape = splitShape(
+    {
+      filters: [
+        { name: 'eventType', operator: 'in', value: ['epcis.ObjectEvent', 'epcis.AggregationEvent'] },
+        { name: 'bizStep', operator: 'eq', value: '  ' }
+      ]
+    } as any,
+    [{ name: 'eventTime', desc: true }] as any
+  )
+  assert.equal(shape, null)
+})

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/fold-gap-speaks.test.ts

@@ -0,0 +1,53 @@
+/*
+ * ★ 저장본 뒤의 사건 — 계산했든 못 했든 **말한다**.
+ *
+ * ── 무엇이 침묵했나 (2026-08-28 실측) ───────────────────────────────────────
+ * 미러는 저장본에서 상태를 되세우고 그 뒤의 사건만 따라 계산한다. 그 자리가 이랬다.
+ *
+ *   10:34:37  found cached state → revision 3372228
+ *   10:34:37  resumed from the stored fold seed at revision 3372228 — items 2665 · orders 4794
+ *
+ * 그 시각 저널의 머리는 3,374,894였다. 2,666건이 저장본보다 앞서 있었는데 **계산했다는 줄도, 못
+ * 했다는 줄도 없었다.** 갈래가 셋인데 말하는 갈래가 하나뿐이었기 때문이다.
+ *
+ *   ① 계산해서 나아갔다        → 말한다
+ *   ② 계산이 오류로 실패했다    → 말한다
+ *   ③ 오류 없이 끝났는데 그대로  → **아무 말도 없었다** ← 여기
+ *   ④ 저널 머리를 못 읽었다     → **아무 말도 없었다** ← 여기
+ *
+ * ③④에서 트윈은 그 사건들의 결과 없이 뜨고, 화면은 그것을 「없는 사실」로 그린다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const engine = readFileSync(join(import.meta.dirname, '..', 'server', 'engine', 'twin-engine.ts'), 'utf8')
+
+test('★ 저널 머리를 못 읽었으면 그 사실을 말하고 그대로 뜬다', () => {
+  assert.match(engine, /if \(!tip\) \{/, '못 읽은 갈래가 있어야 한다')
+  assert.match(engine, /could not read the journal tip/, '무엇을 못 했는지 말해야 한다')
+  assert.match(engine, /without folding what came after it/, '무엇을 잃는지 말해야 한다')
+})
+
+test('★ 계산이 아무 일도 하지 않았으면 그것도 말한다', () => {
+  assert.match(engine, /\} else if \(!failed\) \{/, '오류가 아닌데 나아가지 않은 갈래가 있어야 한다')
+  assert.match(engine, /left the seed at revision/)
+  /* 오류로 실패한 것을 두 번 말하지 않는다 — 이미 위에서 말했다. */
+  assert.match(engine, /let failed: string \| undefined/)
+})
+
+test('★ 부팅마다 부르는 질의를 관계로 묻지 않는다 — 이 파일이 스스로 금지한 모양이다', () => {
+  /*
+   * `findOne({ where: { domain: { id } } })` 는 안쪽에 상한이 없는 두 단계 질의가 된다(실측 12초,
+   * 저널 375만 행). `tipOf` 는 부팅마다 트윈마다 불리므로 그 한 번이 부팅을 붙잡는다.
+   */
+  const from = engine.indexOf('private static async tipOf')
+  assert.ok(from > 0, 'tipOf 가 있어야 한다')
+  const tipOf = engine.slice(from, from + 2600)
+  /* 주석에 인용된 나쁜 모양과 헷갈리지 않게, 실제 코드 모양만 본다. */
+  assert.doesNotMatch(tipOf, /findOne\(\{ where: \{ domain: \{ id: domainId \}/, '관계로 묻는 모양이 남아 있다')
+  assert.match(tipOf, /createQueryBuilder\('e'\)/)
+  assert.match(tipOf, /orderBy\('e\.revision', 'DESC'\)/)
+  assert.match(tipOf, /\.limit\(1\)/)
+})

package/test/forecast-metrics.test.ts

@@ -1,7 +1,7 @@
 /*
  * 예측 지표 — **스냅샷에서 무엇을 세는가.**
  *
- * 여기서 틀리면 예측 그래프가 조용히 다른 것을 그린다(오류 없이 곡선이 나온다). 특히 에너지 지표는
+ * 여기서 틀리면 예측 그래프가 알리지 않고 다른 것을 그린다(오류 없이 곡선이 나온다). 특히 에너지 지표는
  * 「없음」과 「0」이 같은 그림이 되기 쉬워서, 그 경계를 명시로 잡아 둔다.
  */
 import { test } from 'node:test'

package/test/forecast-tuning.test.ts

@@ -1,7 +1,7 @@
 /*
  * 예측 틱 크기 — **지평선이 정하고, 양끝은 묶인다.**
  *
- * 이 규칙이 틀리면 예측이 조용히 비싸지거나(1초 고정 시절 9,000틱·28.5초) 조용히 성글어진다
+ * 이 규칙이 틀리면 예측이 알리지 않고 비싸지거나(1초 고정 시절 9,000틱·28.5초) 알리지 않고 성글어진다
  * (짧은 작업이 한 틱에 삼켜진다). 둘 다 화면에는 그럴듯한 숫자로 나오므로 시험이 지킨다.
  */
 import { test } from 'node:test'

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-health-engine.test.ts

@@ -5,7 +5,7 @@
  * 실제로 받는 판정은 그 앞에 한 층이 더 있다: **피드 사실을 어디서 얻는가**(`liveFeedStateOf` — 이 트윈이
  * 미러인가 시뮬인가, 지금 도는가) 그리고 **장부를 어느 트윈의 것으로 찾는가**(도메인+인스턴스 키).
  *
- * 그 층이 틀리면 순수 시험은 전부 초록인 채로 화면만 거짓말한다. 실제로 두 가지가 조용히 틀릴 수 있다:
+ * 그 층이 틀리면 순수 시험은 전부 초록인 채로 화면만 거짓말한다. 실제로 두 가지가 알리지 않고 틀릴 수 있다:
  *  ① 시뮬 트윈이 「연결 안 됨」으로 보인다 — 거짓 경보이고, 거짓 경보는 참 경보를 죽인다
  *  ② 남의 도메인 장부를 집는다 — 키를 도메인 없이 만들면 그렇게 된다
  *
@@ -206,7 +206,7 @@ test('멈춘 미러는 「해당 없음」이다 — 고치려고 멈춰 둔 트
 
 test('멈춘 트윈에 계속 들어오면 「버려지는 중」이라 말한다 — 실제로 겪은 거짓 안심', async () => {
   /*
-   * 겪은 모습: 트윈이 멈췄는데 피드는 살아 레코드를 나르고, 커널은 조용히 버렸다. 화면은 「해당 없음 ·
+   * 겪은 모습: 트윈이 멈췄는데 피드는 살아 레코드를 나르고, 커널은 알리지 않고 버렸다. 화면은 「해당 없음 ·
    * 150 통과 · 100%」였다. 여기서는 그 상황을 그대로 만들어 판정과 수치를 확인한다.
    */
   /* 사람이 트윈을 멈춘다 — 그런데 피드는 남는다. 그 조합이 사실을 잃게 만든다. */

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

@@ -4,7 +4,7 @@
  * ── 왜 기계가 지켜야 하나 ───────────────────────────────────────────────────
  * 피드를 여는 경로가 둘이다(커넥터 `openLiveFeed` · 시나리오 `twin-ingest` 태스크). 한쪽만 장부에
  * 적으면 그 경로로 먹이는 트윈이 **「한 번도 받지 않은 것」**으로 보인다. 그 판정은 `unknown` 이고,
- * `unknown` 은 화면에서 「정상」과 구별되지 않는다 — 즉 **조용히 틀린 답**이 된다.
+ * `unknown` 은 화면에서 「정상」과 구별되지 않는다 — 즉 **오류 없이 틀린 답**이 된다.
  *
  * 세 번째 경로가 생길 때 사람이 이 사실을 기억할 것이라고 믿지 않는다. 인제스트를 부르는 자리를
  * 소스에서 찾아 장부 기록이 함께 있는지 본다.
@@ -86,7 +86,7 @@ test('검사가 실제로 경로를 보고 있다 — 대상이 사라지면 초
 
 test('유입 경로는 커널이 실제로 받은 수를 견준다 — 버려진 것을 통과로 세지 않게', () => {
   /*
-   * 겪은 일: 트윈이 멈춘 뒤에도 피드는 레코드를 나르고 커널은 조용히 버렸는데, 장부는 그것을 「통과」로
+   * 겪은 일: 트윈이 멈춘 뒤에도 피드는 레코드를 나르고 커널은 알리지 않고 버렸는데, 장부는 그것을 「통과」로
    * 셌다. 화면은 멈춘 트윈 옆에 「150 통과 · 100%」라고 적었다 — 사실이 사라지는 동안 안심시킨 것이다.
    *
    * 고친 방법은 `ingestLive` 가 **넣은 수를 돌려주는** 것이다. 새 경로가 그 반환을 안 쓰고 0 을 넘기면
@@ -100,9 +100,11 @@ test('유입 경로는 커널이 실제로 받은 수를 견준다 — 버려진
     missing,
     [],
     `커널이 받은 수를 견주지 않는 유입 경로 ${missing.length}곳:\n  ${missing.join('\n  ')}\n\n` +
-      `TwinEngine.ingestLive(...) 의 반환(넣은 수)을 받아 accepted.length 와의 차이를 ` +
-      `recordIngestResult(..., nowMs, undelivered) 로 넘긴다. 그러지 않으면 트윈이 멈춘 사이 ` +
-      `버려진 레코드가 「통과」로 집계되어 화면이 100% 라고 말한다.`
+      `TwinEngine.ingestLive(...) 또는 ingestLiveResult(...) 의 반환(넣은 수)을 받아 accepted.length 와의 ` +
+      `차이를 undelivered 라는 이름으로 recordIngestResult(..., nowMs, undelivered) 에 넘긴다. ` +
+      `그러지 않으면 트윈이 멈춘 사이 버려진 레코드가 「통과」로 집계되어 화면이 100% 라고 말한다.\n\n` +
+      `이 검사는 **그 이름이 있는지**만 본다(소스를 글자로 본다). 이름을 적고 0 을 넘기면 통과한다 — ` +
+      `그 경우는 사람이 보는 수밖에 없다.`
   )
 })
 

package/test/ingest-health.test.ts

@@ -53,7 +53,7 @@ test('오래 끊긴 피드는 건강했던 옛 창으로 초록을 내지 않는
   assert.equal(
     syncVerdictOf({ feedState: 'attached', recent: healthy, lastAtMs: 0, nowMs: STALE_AFTER_MS }),
     'syncing',
-    '경계까지는 아직 조용하다고 하지 않는다'
+    '경계까지는 아직 들어온 것이 없다고 하지 않는다'
   )
 })
 
@@ -73,7 +73,7 @@ test('붙었지만 한 번도 받지 않은 것을 「유입 없음」이라 단
   )
 })
 
-test('시뮬 트윈은 오래 조용해도 「유입 없음」이 아니다', () => {
+test('시뮬 트윈은 오래 들어온 것이 없어도 「유입 없음」이 아니다', () => {
   assert.equal(
     syncVerdictOf({ feedState: 'not-applicable', recent: null, lastAtMs: -1, nowMs: STALE_AFTER_MS * 100 }),
     'not-applicable'
@@ -82,7 +82,7 @@ test('시뮬 트윈은 오래 조용해도 「유입 없음」이 아니다', ()
 
 test('들어오는데 트윈이 안 돌면 「버려지는 중」이다 — 「해당 없음」으로 안심시키지 않는다', () => {
   /*
-   * 실제로 겪었다: 트윈이 멈춘 뒤에도 피드는 남아 레코드를 나르고, 커널은 그것을 조용히 버렸다.
+   * 실제로 겪었다: 트윈이 멈춘 뒤에도 피드는 남아 레코드를 나르고, 커널은 그것을 알리지 않고 버렸다.
    * 그런데 화면은 「해당 없음 · 150 통과 · 100%」였다 — 사실이 사라지는 동안 화면이 안심시킨 것이다.
    *
    * 멈춘 트윈의 피드 사실은 `not-applicable` 이므로, 미전달을 **그보다 먼저** 봐야 이 상태가 드러난다.
@@ -141,7 +141,7 @@ test('채우는 중인 창을 「최근」이라 부르지 않는다', () => {
   recordIngest(l, 100, [], 0)
   recordIngest(l, 100, [], 1000)
 
-  /* 읽는 시각을 넘긴다 — 넘기지 않으면 벽시계와 견주어 「오래 조용함」으로 읽힌다(1970년 장부이므로). */
+  /* 읽는 시각을 넘긴다 — 넘기지 않으면 벽시계와 견주어 「오래 들어온 것이 없음」으로 읽힌다(1970년 장부이므로). */
   const v = ingestHealth(l, 'attached', undefined, 1000)
   assert.equal(v.recent, null, '창이 아직 닫히지 않았다')
   assert.equal(v.verdict, 'unknown', '그래서 판정도 모름이다')
@@ -167,7 +167,7 @@ test('추이 상한을 넘으면 오래된 창이 밀려나고, 밀려난 수를
 
   const v = ingestHealth(l, 'attached')
   assert.equal(v.trend.length, TREND_LIMIT)
-  assert.ok(v.trendDropped > 0, `밀려난 창을 조용히 버리지 않는다 — 실제 ${v.trendDropped}`)
+  assert.ok(v.trendDropped > 0, `밀려난 창을 알리지 않고 버리지 않는다 — 실제 ${v.trendDropped}`)
 })
 
 /* ── ③ 0 과 없음 ────────────────────────────────────────────────────────── */
@@ -213,7 +213,7 @@ test('사유 종류가 무한히 자라지 않는다 — 문구에 변수가 섞
   assert.equal(v.reasonsCapped, true, '접혔다는 사실을 말한다')
   assert.ok(
     v.reasons.some(r => r.reason === OTHER_REASON),
-    '접힌 것들이 갈 칸이 있다'
+    '모은 것들이 갈 칸이 있다'
   )
   assert.equal(v.total.rejected, REASON_LIMIT * 5, '건수는 하나도 잃지 않는다')
 })

package/test/ingest-history.test.ts

@@ -12,7 +12,7 @@
  *    거짓이 된다. 겹치면 메모리 쪽을 쓴다(같은 사실의 원본이다).
  * ② 어디서부터 메모리인지 밝힌다(`liveFrom`) — 화면이 근거를 말할 수 있게. 재기동 직후에는 `null`
  *    이고, 그때 보이는 것은 전부 표에서 온 것이다.
- * ③ **조용히 자르지 않는다** — 상한에서 밀려난 창 수와, 물은 기간이 잘렸다는 사실을 함께 낸다.
+ * ③ **알리지 않고 자르지 않는다** — 상한에서 밀려난 창 수와, 물은 기간이 잘렸다는 사실을 함께 낸다.
  * ④ 남의 도메인·남의 트윈의 창을 집지 않는다.
  * ⑤ 제시가 0 인 창의 통과율은 `null` 이다 — 빈 창은 완벽한 창이 아니다.
  */
@@ -157,7 +157,7 @@ test('기간 상한을 넘겨 물으면 자르고, 자른 사실을 낸다', asy
   const r = await ask(TWIN, HISTORY_HOURS_MAX + 100)
 
   assert.equal(r.hours, HISTORY_HOURS_MAX, '상한까지만 본다')
-  assert.equal(r.hoursClamped, HISTORY_HOURS_MAX + 100, '얼마를 물었는지 밝힌다 — 조용히 자르지 않는다')
+  assert.equal(r.hoursClamped, HISTORY_HOURS_MAX + 100, '얼마를 물었는지 밝힌다 — 알리지 않고 자르지 않는다')
 })
 
 test('상한 안에서는 잘렸다고 말하지 않는다 — 없는 문제를 만들지 않는다', async () => {