@things-factory/headless-twin 10.0.15 → 10.0.18

package/server/engine/canonical-ingest.ts

@@ -1,6 +1,5 @@
-import { ingest, ingestEnergyRecords, ingestEnergyEquipmentRecords, ingestOperationalRecords, isAggregationRecord, isTransformationRecord,
-  isEnergyRecord, isEnergyEquipmentRecord, isOperationalRecord, type AdapterRule, type EnergyRecord,
-  type EnergyEquipmentRecord, type OperationalRecord, type IngestResult } from '@operato/twin-kernel'
+import { type CanonicalRecord, type CanonicalAggregationRecord, type CanonicalTransformationRecord, type AdapterRule, type EnergyRecord, type EnergyEquipmentRecord, type EnergyGenerationRecord, type EnergyUsagePeriodRecord, type EnergyBillRecord, type EnergyTariffBasisRecord, type EnergyGenerationPriceRecord, type EnergyGenerationPeriodRecord, type OperationalRecord, type IngestResult, type MasterDataRecord } from '@operato/ops-contract'
+import { ingest, ingestEnergyRecords, ingestEnergyEquipmentRecords, ingestEnergyGenerationRecords, ingestEnergyUsagePeriodRecords, ingestEnergyBillRecords, ingestEnergyTariffBasisRecords, ingestEnergyGenerationPriceRecords, ingestEnergyGenerationPeriodRecords, ingestOperationalRecords, isAggregationRecord, isTransformationRecord, isEnergyRecord, isEnergyEquipmentRecord, isEnergyGenerationRecord, isEnergyUsagePeriodRecord, isEnergyBillRecord, isEnergyTariffBasisRecord, isEnergyGenerationPriceRecord, isEnergyGenerationPeriodRecord, isOperationalRecord, isMasterDataRecord, ingestMasterData } from '@operato/ops-contract'
 
 /*
  * 정규 레코드 → 커널 검증 ACL → CanonicalEnvelope (P1 seam 코어).
@@ -9,6 +8,9 @@ import { ingest, ingestEnergyRecords, ingestEnergyEquipmentRecords, ingestOperat
  * 여기 도착하는 레코드는 이미 정규 필드다 — 어휘마다 자기 필드 이름이 계약이다:
  *   EPCIS 품목 { epc, action, bizStep, disposition?, readPoint?, bizLocation? }
  *   에너지 계량 { meterId, kW?, kWh?, … } · 설비 에너지 { equipmentId, generatedKW?, soc?, … }
+ *   발전 적산   { equipmentId, kWh, kWhSince?, … }
+ *   사용 구간   { meterId, from, to, kWh, unitPrice?, basis?, … }  · 청구서 { from, to, total?, … }
+ *   요금 기준   { from, to, billingDemandKW?, demandChargePerKW?, currency }
  *   담김(적재) { parentID, childEPCs[] | childQuantityList[], action, bizStep, … }
  *   운영 사실 { taskId | moverId | personId | assetId | orderId, status, … }  // vocabulary-guard: allow 저널 와이어 필드
  * 커널은 objectEvent 구성 + EPCIS 검증(위반=오염 차단) + 봉투 래핑만(방언 없음).
@@ -38,10 +40,25 @@ const TWIN_INGEST_RULES: AdapterRule[] = [
        * 재고 950건·59,785kg 이 어디에도 나타나지 않았고, 빈 화면이 「이상 없음」으로 읽혔다.
        *
        * ★ **표준이 `action: 'ADD'` 일 때만 허용한다**(또는 변환). 마스터데이터는 로트가 **생길 때**
-       * 말하는 사실이고, 주기 관측마다 실으면 커널이 거부한다 — 조용히 통과시키지 않는 것이 옳다
+       * 말하는 사실이고, 주기 관측마다 실으면 커널이 거부한다 — 알리지 않고 통과시키지 않는 것이 옳다
        * (커넥터가 첫 목격에 `ADD`, 그 뒤로 `OBSERVE` 를 내야 한다).
        */
       ilmd: '$.ilmd',
+      /*
+       * **정정 선언** — 「이 사건은 없던 일이 되었다」(커널 0.7.65 에서 이 자리가 열렸다).
+       *
+       * 세 값이 함께여야 뜻이 있어 묶음으로 온다. 커널이 선언 시각을 요구하고, 없으면 사건 시각으로
+       * 메우지 않고 이유와 함께 돌려준다 — 「언제 정정했나」와 「언제 일어났나」가 같아지면 둘을 다시
+       * 갈라낼 수 없다.
+       *
+       * 상태는 이것으로 흔들리지 않는다. 커널은 정정을 목록에 적고 재고를 그대로 둔다 — 무엇을 어떻게
+       * 되돌릴지는 도메인 판단이고, 참 재고는 그 뒤의 잔량 관측이 다시 말해 준다.
+       */
+      errorDeclaration: {
+        declarationTime: '$.errorDeclaration.declarationTime',
+        reason: '$.errorDeclaration.reason',
+        correctiveEventIDs: '$.errorDeclaration.correctiveEventIDs'
+      },
       readPoint: '$.readPoint',
       bizLocation: '$.bizLocation'
     }
@@ -58,6 +75,11 @@ const TWIN_INGEST_RULES: AdapterRule[] = [
       outputEPCList: '$.outputEPCList',
       outputQuantityList: '$.outputQuantityList',
       transformationID: '$.transformationID',
+      errorDeclaration: {
+        declarationTime: '$.errorDeclaration.declarationTime',
+        reason: '$.errorDeclaration.reason',
+        correctiveEventIDs: '$.errorDeclaration.correctiveEventIDs'
+      },
       readPoint: '$.readPoint',
       bizLocation: '$.bizLocation'
     }
@@ -78,84 +100,27 @@ const TWIN_INGEST_RULES: AdapterRule[] = [
       childEPCs: '$.childEPCs',
       /* 낱개 식별자 없이 **수량으로** 담긴 자식(「이 품번 40개」) — 입고·포장이 이 모양으로 온다. */
       childQuantityList: '$.childQuantityList',
+      errorDeclaration: {
+        declarationTime: '$.errorDeclaration.declarationTime',
+        reason: '$.errorDeclaration.reason',
+        correctiveEventIDs: '$.errorDeclaration.correctiveEventIDs'
+      },
       readPoint: '$.readPoint',
       bizLocation: '$.bizLocation'
     }
   }
 ]
 
-/** 개체 관측 — 물건 하나가 어디서 무엇이 됐나. */
-export interface CanonicalRecord {
-  /**
-   * 개체 하나의 식별자. **`quantityList` 를 쓰면 없어도 된다** — 낱개 번호가 없는 자재(밀가루 3.5kg)는
-   * 개체가 없다. 둘 다 없으면 무엇을 관측했는지 말하지 않은 것이므로 커널 매핑이 거부한다.
-   */
-  epc?: string
-  /**
-   * 클래스와 수량 — `{ epcClass, quantity, uom? }`. **잔량 절대값을 싣는다**(「얼마 뺐다」가 아니라
-   * 「얼마 남았다」). 그래야 사건 하나를 놓쳐도 다음 사건이 정답을 다시 말해 주고 오차가 쌓이지 않는다.
-   *
-   * 담김(`childQuantityList`)이 하루 먼저 이 자리를 받았다 — 그때와 같은 이유다. 원본이 비직렬 수량을
-   * 말할 길이 없어서, 그것이 주된 경로인 시스템(식품 제조 MES)은 라이브를 낼 수 없었다. 커널의
-   * 관측 리듀서는 처음부터 이 값을 읽었고 문만 없었다.
-   */
-  quantityList?: { epcClass: string; quantity?: number; uom?: string }[]
-  action: string // ADD | OBSERVE | DELETE
-  bizStep: string
-  disposition?: string
-  readPoint?: string
-  bizLocation?: string
-}
-
-/**
- * 담김 관측 — **부모와 자식**으로 말한다. 자리 필드는 개체 관측과 같은 이름이다(문자열).
- *
- * 이름은 표준의 것을 그대로 쓴다(`parentID`·`childEPCs`) — 여기서 다시 지으면 매핑이 번역이 되고,
- * 같은 사실에 두 어휘가 생긴다.
- */
-/**
- * 변환 관측 — **무엇으로 무엇이 되었나.** 입력과 출력이 **한 사실에 함께** 있어야 계보가 남는다.
- *
- * 따로 보내면(「이 로트가 없어졌다」와 「이 제품이 생겼다」) 그 둘을 이을 근거가 없다. 그래서 표준이
- * 한 사건에 둘을 담고, 우리 레코드도 같은 모양이다.
- *
- * 이름은 **표준의 것을 그대로** 쓴다(`inputQuantityList` 등). 갈래 판정이 이 이름으로 이루어지므로
- * 커넥터 낱말(`consumed`·`produced`)로 담으면 판정되지 않는다 — 커넥터가 정규 이름으로 담아 보내고
- * 매핑은 그 안에서 값을 고른다.
+/*
+ * 정규 레코드 셋(`CanonicalRecord` · `CanonicalTransformationRecord` · `CanonicalAggregationRecord`)은
+ * **계약으로 옮겼다**(2026-08-30, `@operato/ops-contract` 0.2.0).
  *
- * **없는 쪽은 필드를 만들지 않는다.** 빈 배열을 실으면 「없다」고 말하는 것이 된다. 소실(N→0)과
- * 생성(0→N)도 표준이 인정하는 변환이다.
+ * 여기 있던 이유는 소비 방식 때문이었다 — EPCIS 는 커널의 범용 어댑터를 지나서 타입을 요구하지 않았다.
+ * 그런데 모양 자체는 EPCIS 2.0 의 필드 이름이고 호스트의 것이 아니다. 이제 MES 가 이 모양 그대로
+ * 보낸다.
  *
- * `transformationID` 가 한 오더의 여러 단계를 잇는다 — 소비를 먼저 알고 산출을 나중에 알게 되는 원본에서
- * 그 둘을 묶는 유일한 자리다.
+ * **매핑 룰(`TWIN_INGEST_RULES`)은 여기 남는다** — 이 모양을 EPCIS 사건으로 옮기는 정책이지 모양이 아니다.
  */
-export interface CanonicalTransformationRecord {
-  /** 개체로 소비된 것. */
-  inputEPCList?: string[]
-  /** 클래스와 수량으로 소비된 것 — 로트 단위 소비가 이 자리다. */
-  inputQuantityList?: { epcClass: string; quantity?: number; uom?: string }[]
-  outputEPCList?: string[]
-  outputQuantityList?: { epcClass: string; quantity?: number; uom?: string }[]
-  /** 한 오더의 여러 단계를 잇는 식별자. */
-  transformationID?: string
-  bizStep: string
-  disposition?: string
-  readPoint?: string
-  bizLocation?: string
-}
-
-export interface CanonicalAggregationRecord {
-  parentID: string
-  /** 개체로 담긴 자식. 수량으로만 담겼으면 없다(둘 중 하나는 있어야 한다). */
-  childEPCs?: string[]
-  /** 수량으로 담긴 자식 — `{ epcClass, quantity, uom? }`. 값의 옳고 그름은 커널 검증이 본다. */
-  childQuantityList?: { epcClass: string; quantity?: number; uom?: string }[]
-  action: string // ADD(담다) | DELETE(풀다) | OBSERVE
-  bizStep: string
-  disposition?: string
-  readPoint?: string
-  bizLocation?: string
-}
 
 /** 정규 레코드[] → 검증된 CanonicalEnvelope[] (+ 거부분). 순수 함수. 단일→객체도 배열로 정규화. */
 export function ingestCanonicalRecords(
@@ -166,13 +131,50 @@ export function ingestCanonicalRecords(
     | EnergyRecord
     | EnergyEquipmentRecord
     | OperationalRecord
-    | (CanonicalRecord | CanonicalAggregationRecord | CanonicalTransformationRecord | EnergyRecord | EnergyEquipmentRecord | OperationalRecord)[]
+    /* 다섯째 어휘 — 사건이 아닌 것(변하지 않는 속성). 저널로 가지 않는다(§`CanonicalIngestResult`). */
+    | MasterDataRecord
+    | (
+        | CanonicalRecord
+        | CanonicalAggregationRecord
+        | CanonicalTransformationRecord
+        | EnergyRecord
+        | EnergyEquipmentRecord
+        | OperationalRecord
+        | MasterDataRecord
+      )[]
     | undefined
     | null,
   tenantId: string,
-  defaultEventTime: string
-): IngestResult {
+  defaultEventTime: string,
+  /**
+   * **이 사실들이 어느 트윈의 것인가** — 마감된 구간 사실의 이름에 쓰인다(커널 §`SubjectBasis`).
+   *
+   * 커널은 도메인으로 서므로 자기가 어느 트윈인지 모른다. 그런데 설비 번호·계량 지점 번호는 트윈
+   * 안에서만 통하는 이름표라, 한 도메인에 현장이 둘이면 서로 다른 설비의 같은 날이 한 사실이 된다.
+   * 실측으로 그 일이 났다 — 두 발전소의 `002` 가 겹쳤다.
+   *
+   * 주지 않으면 이름표를 그대로 쓰고 `twin-local` 로 표시된다 — 겹칠 수 있다는 뜻이다.
+   */
+  scope?: { scopeId?: string; identityOf?: (kind: 'equipment' | 'meter', localId: string) => string | undefined }
+): CanonicalIngestResult {
   const arr = Array.isArray(records) ? records : records ? [records] : []
+  /*
+   * ── **다섯째 어휘는 사건이 아니다** (2026-08-28) ────────────────────────────
+   *
+   * 마스터데이터 — 변하지 않는 속성(유통기한·로트번호·자리의 성질). 표준은 이것을 사건이 아니라
+   * **어휘 요소의 속성**으로 담고, 커널에 그 자리가 없어서 지금까지 사건에 실려 왔다.
+   *
+   * 그 결과가 유입에서 이렇게 났다. 전량을 읽는 원본이 유통기한을 실으려고 **들어오지 않은 것을
+   * `ADD`** 라고 말했고, `ilmd` 가 사건 단위라 자리별로 묶을 수도 없어 낱개로 나갔다 — 재기동 한 번에
+   * 2,665건이다.
+   *
+   * 그래서 여기서 갈라 낸다. 이것은 봉투가 되지 않고 저널에도 적히지 않는다(시각축이 없는 값이다).
+   * 갈래 판정은 커널의 것을 부른다 — 다른 넷과 같은 규율이다.
+   *
+   * 설계: `operato-twin/design/plans/master-data.md`
+   */
+  const masterCandidates = arr.filter(isMasterDataRecord)
+  const master = masterCandidates.length ? ingestMasterData(masterCandidates) : { accepted: [], rejected: [] }
   /*
    * **어휘가 넷이다** — 물류(EPCIS)·에너지 계량·설비 에너지·운영 사실. 예전에는 이 함수가 무조건
    * `ObjectEvent` 를 만들었고, 그래서 계측을 이 길로 넣으면 `epc` 가 없어 거부되거나(그나마 나은 쪽)
@@ -184,17 +186,79 @@ export function ingestCanonicalRecords(
    * 소비처마다 답이 달라진다. 봉투는 같은 것을 쓰므로 아래 소비처(미러·저널·브로드캐스팅)는 이 갈림을 알
    * 필요가 없다.
    */
-  const energy = arr.filter(isEnergyRecord) as EnergyRecord[]
+  /*
+   * 여섯째·일곱째 어휘 — **마감된 사용 구간**과 **청구서**. 커널 0.7.72 가 이 문들을 열었다.
+   *
+   * ── ★ 사용 구간을 계량보다 **먼저** 가른다 ─────────────────────────────────
+   * `isEnergyRecord` 는 `meterId` 가 있으면 참이므로 사용 구간에도 참이다. 순서를 정하지 않으면
+   * 시간별 사용량이 계량 표본으로 들어가고, 그 문은 `kWh` 를 **적산 레지스터**로 읽는다. 그러면
+   * 커널이 구간 전력량을 차분으로 구하는데 우리가 넣은 값이 이미 구간의 양이다 — 차분의 차분이 되어
+   * 값이 조용히 틀린다. 거부되지도 않는다.
+   */
+  const usagePeriods = arr.filter(isEnergyUsagePeriodRecord) as unknown as EnergyUsagePeriodRecord[]
+  const bills = arr.filter(isEnergyBillRecord) as unknown as EnergyBillRecord[]
+  /*
+   * 여덟째 어휘 — **그 주기에 적용되는 요금 기준**. 커널 0.7.76 이 이 문을 열었다.
+   *
+   * ★ 청구서와 겹친다. 청구서가 `billingDemandKW` 를 실을 수 있고, 그러면 두 판정이 다 참이다.
+   * 그때 요금 기준 문으로 보내면 「금액은 이 문이 받지 않는다」로 거부된다 — 정산이 통째로
+   * 사라진다. 그래서 청구서인 것을 뺀다. 커널에서 배타로 만들어 달라고 올렸다.
+   */
+  const tariffBases = arr.filter(r => isEnergyTariffBasisRecord(r) && !isEnergyBillRecord(r)) as unknown as EnergyTariffBasisRecord[]
+  /*
+   * 아홉째 어휘 — **발전 단가**. 낸 것에 매겨지는 1kWh 당 값이고 날마다 바뀐다(커널 0.7.79).
+   *
+   * 다른 문과 겹치지 않는다: 계량 지점이나 설비 id 가 있으면 이 문이 아니고(커널이 배타로 막는다),
+   * 요금적용전력·기본요금 단가가 없으므로 요금 기준도 아니다.
+   */
+  const generationPrices = arr.filter(isEnergyGenerationPriceRecord) as unknown as EnergyGenerationPriceRecord[]
+  /* 마감된 발전 기간 — 지난 기록 채우기가 쓴다. 적산의 문과 배타다(구간이 있으면 이쪽). */
+  const generationPeriods = arr.filter(isEnergyGenerationPeriodRecord) as unknown as EnergyGenerationPeriodRecord[]
+  const energy = arr.filter(r => isEnergyRecord(r) && !isEnergyUsagePeriodRecord(r)) as EnergyRecord[]
   /* 세 번째 어휘 — 설비가 낸 자기 에너지 상태(발전·저장·감축 여지·개폐 위치). 계량과 갈라 두는
      이유는 커널에 적혀 있다: 계량은 구간에 누적되고, 이것들은 그 설비의 지금이다. */
-  const energyEquipment = arr.filter(isEnergyEquipmentRecord) as unknown as EnergyEquipmentRecord[]
+  /*
+   * 다섯 번째 어휘 — **발전 적산**(설비가 지금까지 만든 양). 커널 0.7.69 가 이 문을 열었다.
+   *
+   * ── ★ 설비 상태보다 **먼저** 가른다 ──────────────────────────────────────────
+   * 두 판정이 겹친다. `isEnergyEquipmentRecord` 는 `equipmentId` 가 있고 물류·계량 어휘가 아니면
+   * 참이므로 발전 적산도 함께 참이다. 그래서 순서가 갈림을 정한다.
+   *
+   * 순서를 잘못 두면 조용히 사라지는 것이 아니라 **엉뚱한 이유로 거부된다**: 설비 상태 문은 적산을
+   * 값으로 세지 않아 「바꿀 상태가 하나도 없다」로 돌려보낸다. 커넥터는 보냈다고 믿고, 화면에는
+   * 발전량이 없다.
+   */
+  const energyGeneration = arr.filter(isEnergyGenerationRecord) as unknown as EnergyGenerationRecord[]
+  const energyEquipment = arr.filter(r => isEnergyEquipmentRecord(r) && !isEnergyGenerationRecord(r)) as unknown as EnergyEquipmentRecord[]
   /*
    * 네 번째 어휘 — **운영 사실**(작업·설비·사람·자산·오더·품질). 관측 리듀서는 이것을 오래전부터
-   * 접었는데 **들어올 문이 없었다**: 원본이 「이 작업이 끝났다」를 말할 길이 없어 시뮬 커널만 그것을
+   * 계산했는데 **들어올 문이 없었다**: 원본이 「이 작업이 끝났다」를 말할 길이 없어 시뮬 커널만 그것을
    * 아는 상태가 남았다(같은 화면이 두 구동에서 다른 것을 말한다).
    */
   const operational = arr.filter(isOperationalRecord) as OperationalRecord[]
-  const epcis = arr.filter(r => !isEnergyRecord(r) && !isEnergyEquipmentRecord(r) && !isOperationalRecord(r)) as (CanonicalRecord | CanonicalAggregationRecord | CanonicalTransformationRecord)[]
+  /*
+   * ── 이 목록은 **어휘를 더할 때마다 함께 늘어야 한다** (2026-08-30) ─────────
+   *
+   * EPCIS 갈래는 「나머지 전부」다. 새 어휘를 빼 주지 않으면 그 레코드가 제 문으로 가면서
+   * **EPCIS 문으로도 들어가** 거부된다. 받아들여지기도 하고 거부되기도 하는 상태가 되어,
+   * 유입 장부의 거부 수가 늘고 사람이 그것을 진짜 결함으로 읽는다.
+   *
+   * 실제로 발전 단가를 더할 때 그렇게 됐다. 목록을 손으로 지키는 대신 시험이 지킨다
+   * (§`canonical-ingest-vocabularies` — 어휘마다 한 문으로만 가는지).
+   */
+  const epcis = arr.filter(
+    r =>
+      !isEnergyRecord(r) &&
+      !isEnergyEquipmentRecord(r) &&
+      !isEnergyGenerationRecord(r) &&
+      !isEnergyUsagePeriodRecord(r) &&
+      !isEnergyBillRecord(r) &&
+      !isEnergyTariffBasisRecord(r) &&
+      !isEnergyGenerationPriceRecord(r) &&
+      !isEnergyGenerationPeriodRecord(r) &&
+      !isOperationalRecord(r) &&
+      !isMasterDataRecord(r)
+  ) as (CanonicalRecord | CanonicalAggregationRecord | CanonicalTransformationRecord)[]
 
   /* 품목 어휘 안에서도 갈림이 있다(개체 관측 / 담김) — 그 판정도 커널의 것을 부른다. */
   const epcisResult = epcis.length
@@ -232,30 +296,81 @@ export function ingestCanonicalRecords(
          * **레코드가 시각을 말하면 그것을 쓴다** (2026-08-23).
          *
          * `eventTimePath` 를 주지 않던 동안 이 경로는 **언제나 폴링 시각**을 썼다(`defaultEventTime`).
-         * 그래서 커넥터가 이미 싣고 있던 `eventTime`(변환 레코드의 `finishedAt` 등)이 **조용히
+         * 그래서 커넥터가 이미 싣고 있던 `eventTime`(변환 레코드의 `finishedAt` 등)이 **알리지 않고
          * 무시됐다** — 커넥터를 붙인 쪽은 그것이 먹는다고 믿고 있었고, 어디에도 오류가 나지 않았다.
          *
          * 무엇이 걸렸나: 계보(변환)의 시각이다. 4월에 만든 로트가 8월에 만들어진 것으로 저널에 남았다.
          * 그리고 실측 소요를 재는 폴드가 봉투 시각을 쓰므로(§`kpi-fold`: `workMs = 완료 − 첫 착수`),
          * 폴링 간격을 작업시간으로 배울 수 있었다 — 못 배우는 것보다 나쁘다.
          *
-         * 레코드에 `eventTime` 이 없으면 커널이 조용히 기본값으로 떨어진다(§`resolve` — 없는 값은
+         * 레코드에 `eventTime` 이 없으면 커널이 알리지 않고 기본값으로 떨어진다(§`resolve` — 없는 값은
          * 오류가 아니다). 그래서 이 한 줄이 기존 경로를 막지 않는다: 시각을 말하는 레코드만 사실이 된다.
          */
         { tenantId, defaultEventTime, eventTimePath: 'eventTime' }
       )
     : { accepted: [], rejected: [] }
-  const energyResult = energy.length ? ingestEnergyRecords(energy, { tenantId, defaultEventTime }) : { accepted: [], rejected: [] }
+  const energyResult = energy.length ? ingestEnergyRecords(energy, { tenantId, defaultEventTime, ...scope }) : { accepted: [], rejected: [] }
   const equipmentResult = energyEquipment.length
-    ? ingestEnergyEquipmentRecords(energyEquipment, { tenantId, defaultEventTime })
+    ? ingestEnergyEquipmentRecords(energyEquipment, { tenantId, defaultEventTime, ...scope })
+    : { accepted: [], rejected: [] }
+  const usageResult = usagePeriods.length
+    ? ingestEnergyUsagePeriodRecords(usagePeriods, { tenantId, defaultEventTime, ...scope })
+    : { accepted: [], rejected: [] }
+  const billResult = bills.length ? ingestEnergyBillRecords(bills, { tenantId, defaultEventTime, ...scope }) : { accepted: [], rejected: [] }
+  const tariffBasisResult = tariffBases.length
+    ? ingestEnergyTariffBasisRecords(tariffBases, { tenantId, defaultEventTime, ...scope })
+    : { accepted: [], rejected: [] }
+  const generationPeriodResult = generationPeriods.length
+    ? ingestEnergyGenerationPeriodRecords(generationPeriods, { tenantId, defaultEventTime, ...scope })
+    : { accepted: [], rejected: [] }
+  const generationPriceResult = generationPrices.length
+    ? ingestEnergyGenerationPriceRecords(generationPrices, { tenantId, defaultEventTime, ...scope })
+    : { accepted: [], rejected: [] }
+  const generationResult = energyGeneration.length
+    ? ingestEnergyGenerationRecords(energyGeneration, { tenantId, defaultEventTime, ...scope })
     : { accepted: [], rejected: [] }
   const operationalResult = operational.length
-    ? ingestOperationalRecords(operational, { tenantId, defaultEventTime })
+    ? ingestOperationalRecords(operational, { tenantId, defaultEventTime, ...scope })
     : { accepted: [], rejected: [] }
 
   /* 거부분을 합쳐 돌려준다 — 어느 어휘에서 거부됐는지는 이유 문구가 말한다. */
   return {
-    accepted: [...epcisResult.accepted, ...energyResult.accepted, ...equipmentResult.accepted, ...operationalResult.accepted],
-    rejected: [...epcisResult.rejected, ...energyResult.rejected, ...equipmentResult.rejected, ...operationalResult.rejected]
+    accepted: [
+      ...epcisResult.accepted,
+      ...energyResult.accepted,
+      ...equipmentResult.accepted,
+      ...generationResult.accepted,
+      ...usageResult.accepted,
+      ...generationPriceResult.accepted,
+      ...generationPeriodResult.accepted,
+      ...billResult.accepted,
+      ...tariffBasisResult.accepted,
+      ...operationalResult.accepted
+    ],
+    rejected: [
+      ...epcisResult.rejected,
+      ...energyResult.rejected,
+      ...equipmentResult.rejected,
+      ...generationResult.rejected,
+      ...usageResult.rejected,
+      ...billResult.rejected,
+      ...tariffBasisResult.rejected,
+      ...generationPriceResult.rejected,
+      ...generationPeriodResult.rejected,
+      ...operationalResult.rejected,
+      ...master.rejected
+    ],
+    /* 사건이 아닌 것은 따로 낸다 — 부르는 쪽이 상태 세우는 문으로 보낸다(저널로 가지 않게). */
+    masterData: master.accepted
   }
 }
+
+/**
+ * 유입 결과 — 사건(봉투)과 **사건이 아닌 것**을 갈라 낸다.
+ *
+ * 마스터데이터를 `accepted` 에 섞지 않는 이유: 부르는 쪽이 그것을 저널에 적게 되고, 시각축이 없는 값이
+ * 「그때 일어난 일」로 남는다. 갈래를 타입으로 갈라 두면 그 실수를 할 수 없다.
+ */
+export interface CanonicalIngestResult extends IngestResult {
+  masterData: MasterDataRecord[]
+}

package/server/engine/command-routing.ts

@@ -16,7 +16,7 @@
  * | 주석(확인 ack)    | 커널 런타임      | 관측 커널                            |
  *
  * 미러에서 액추에이션을 그냥 허용하면 **새 거짓말이 생긴다**: 트윈은 "보류됨" 이라 말하고 실 시스템은
- * 모른다. 조용히 커널만 바꾸지 않고, 이유를 밝혀 거절한다.
+ * 모른다. 알리지 않고 커널만 바꾸지 않고, 이유를 밝혀 거절한다.
  *
  * 반면 확인(ack)은 액추에이션이 아니다 — 신호를 봤다는 트윈 쪽 주석이라 현실을 건드리지 않는다.
  * 미러에서도 성립해야 하므로 관측 커널로 보낸다.

package/server/engine/declared-stimulus.ts

@@ -17,7 +17,7 @@
  * ── 판정을 순수 함수로 (이 파일) ────────────────────────────────────────────
  * 「이 트윈에 저장된 자극을 실을 것인가」에는 사람이 틀리기 쉬운 갈림이 셋 있다: 미러에 실으면 **현실을
  * 오염**시키고, 잘못된 선언을 실으면 **다음 틱에서 서버가 내려가고**(실제로 그 이력이 있다), 시나리오
- * 엔진이 없는 런타임에 실으면 조용히 아무 일도 없다. 그래서 판정을 값으로 만들고 시험한다.
+ * 엔진이 없는 런타임에 실으면 알리지 않고 아무 일도 없다. 그래서 판정을 값으로 만들고 시험한다.
  */
 
 /** 자극을 실을지 말지 — 그리고 왜. 부르는 쪽은 이 답만 보고 움직인다. */

package/server/engine/energy-topology.ts

@@ -13,11 +13,11 @@
  * 단선도를 그리면 갖지 않은 공학적 충실도를 주장하게 된다. 여기서 그리는 것은 **트윈이 선언한 관계**
  * (자리의 계층 + 설비의 소속)와 **계량이 실제로 덮는 범위**뿐이다. 한계는 소비처가 화면에 적는다.
  *
- * ── 조용히 빠뜨리지 않는다 ─────────────────────────────────────────────────
+ * ── 알리지 않고 빠뜨리지 않는다 ─────────────────────────────────────────────────
  * 자리를 모르는 설비, 계량기가 없는 자리, 계량이 덮지 않는 몫은 **각자 자기 칸으로** 나온다. 그림에서
  * 사라지면 사용자는 자기 현장이 다 그려졌다고 믿는다.
  */
-import { EMS_LOCATION_TYPES, electricalUpstreamOf } from '@operato/twin-kernel'
+import { EMS_LOCATION_TYPES, electricalUpstreamOf } from '@operato/ops-contract'
 
 /** 계통의 한 구간(수전·분기·구역) — 자리 하나가 곧 구간이다. */
 export interface TopologySegment {

package/server/engine/ingest-dedupe.ts

@@ -0,0 +1,149 @@
+/*
+ * 같은 사실을 두 번 받으면 한 번만 반영한다 — **유입 경계 한 곳에서.**
+ *
+ * ── 왜 필요한가 (2026-08-26) ────────────────────────────────────────────────
+ * 지금 중복을 막는 것은 커넥터마다 각자 하고 있다. 그래서 커넥터가 그것을 잊으면 트윈이 그대로 두 번
+ * 센다. 실제로 그랬다: 태양광 커넥터가 10초마다 물으면서 10분마다 바뀌는 값을 매번 다시 보냈고,
+ * 한 주기에 76건이 되풀이됐다(커넥터에서 고쳐서 2건이 됐다).
+ *
+ * 그리고 이것은 웹훅으로 받을 때 더 자주 난다. 밀어 주는 방식은 재전송이 정상이다 — 그쪽이 응답을
+ * 못 받으면 같은 것을 다시 보낸다.
+ *
+ * ── 무엇이 두 번 세어지나 ──────────────────────────────────────────────────
+ * 절대값으로 말하는 사실은 여러 번 반영해도 결과가 같다(잔량 · 상태 · 적산 · 순간 kW). 그런데 세는
+ * 값은 그렇지 않다.
+ *
+ *   구간의 표본 수 · 평균 부하(표본 수로 나눈다) · OEE 카운터 · 유입 계수
+ *   그리고 지난 기록에 같은 사실이 두 줄로 남는다 — 나중에 그 기록으로 다시 계산하면 또 두 번 센다
+ *
+ * ── 정체를 무엇으로 보나 ────────────────────────────────────────────────────
+ * 봉투의 `eventId` 로는 판단할 수 없다. 보낸 쪽이 매번 새로 만드는 순번이고(`…-energy-1` 처럼 호출마다
+ * 1부터 다시 시작한다), 같은 사실을 두 번 보내면 다른 번호가 붙는다. 다른 사실에 같은 번호가 붙는 일도
+ * 생긴다.
+ *
+ * 그래서 **사실 자체로** 판단한다.
+ *
+ *   무엇에 대한 것인가   설비 · 계량 지점 · 물품 · 작업 · 오더 · 자리
+ *   어떤 종류인가        사건 종류(eventType)
+ *   언제 잰 것인가       연결된 시스템이 준 시각
+ *
+ * 이 셋이 같으면 같은 사실이다. 태양광 커넥터가 `collectedAt` 으로 판단한 것과 같은 방식이고, 그것을
+ * 커넥터마다 하지 않도록 여기로 올린다.
+ *
+ * ── 정확히 같은 것만 버린다 ─────────────────────────────────────────────────
+ * 늦게 도착한 옛 사실은 버리지 않는다. 그것이 왔다는 것 자체가 사실이고, 상태에 반영되지 않는 것은
+ * 커널의 순서 판단이 이미 맡는다. 여기서 버리는 것은 **정체가 완전히 같은 것**뿐이다.
+ */
+
+/** 시각을 밀리초로 — 연결된 시스템이 준 시각이 먼저, 없으면 봉투의 시각. */
+function timeOf(envelope: any): number | undefined {
+  for (const v of [envelope?.data?.at, envelope?.data?.eventTime, envelope?.eventTime]) {
+    const t = Date.parse(String(v ?? ''))
+    if (Number.isFinite(t)) return t
+  }
+  return undefined
+}
+
+/**
+ * 이 봉투가 말하는 대상 — 어휘마다 이름이 다르므로 아는 이름을 모두 본다.
+ *
+ * 순서가 뜻을 갖는다: 주체를 먼저 본다. 설비 사실은 「지금 붙어 있는 작업」을 함께 싣고, 작업 사실은
+ * 「소속 오더」를 함께 싣는다. 아무 이름이나 먼저 보면 참조를 주체로 읽는다(승격 키에서 겪은 것과 같다).
+ */
+function targetOf(envelope: any): string | undefined {
+  const d = envelope?.data ?? {}
+  const first = (...vals: unknown[]) => {
+    for (const v of vals) {
+      const s = String(v ?? '').trim()
+      if (s) return s
+    }
+    return undefined
+  }
+  return first(
+    d.meterId,
+    d.equipmentId,
+    d.moverId,
+    d.taskId,
+    d.orderId,
+    d.personId,
+    d.assetId,
+    d.locationId,
+    d.epcList?.[0],
+    d.parentID,
+    d.quantityList?.[0]?.epcClass,
+    d.transformationID
+  )
+}
+
+/**
+ * 이 봉투가 말하는 사실의 정체 — 같으면 같은 사실이다.
+ *
+ * 대상이나 시각을 알 수 없으면 **정체를 만들지 않는다**(`undefined`). 그때는 거르지 않고 통과시킨다 —
+ * 모르는 것을 같다고 판단하면 서로 다른 사실이 하나로 합쳐진다. 알리지 않고 잃는 것보다 두 번 세는 것이 낫다.
+ */
+export function factIdentity(envelope: any): string | undefined {
+  const type = String(envelope?.eventType ?? '').trim()
+  if (!type) return undefined
+  const target = targetOf(envelope)
+  if (!target) return undefined
+  const at = timeOf(envelope)
+  if (at === undefined) return undefined
+  return `${type}|${target}|${at}`
+}
+
+/**
+ * 최근에 본 정체를 기억한다 — **크기에 상한을 둔다.**
+ *
+ * 전부 기억할 수는 없다(트윈 하나가 수천만 사건을 갖는다). 창을 넘으면 오래된 것부터 잊는다. 창 밖의
+ * 재전송은 다시 통과하는데, 그것은 절대값 사실이라 상태에 해가 없고 지난 기록에 한 줄 더 남는다.
+ * 창을 크게 잡으면 그만큼 메모리를 쓴다 — 그 값을 여기서 이름으로 못 박는다.
+ *
+ * **재기동을 건너지 못한다.** 프로세스가 새로 뜨면 기억이 비어 있으므로, 재기동 직후 첫 주기가 같은
+ * 값을 다시 보내면 걸러지지 않는다. 그것을 막으려면 이 기억이 저장돼야 하고, 그것은 다음 걸음이다.
+ * 지금은 그 사실을 여기 적어 둔다 — 적어 두지 않으면 「중복은 이제 없다」로 읽힌다.
+ */
+export class FactDeduper {
+  /** 기억하는 정체의 수 — 창. */
+  static WINDOW = 20_000
+
+  private seen = new Set<string>()
+  private order: string[] = []
+
+  /** 이 사실을 본 적이 있나 — 없으면 기억하고 `false`. */
+  private known(identity: string): boolean {
+    if (this.seen.has(identity)) return true
+    this.seen.add(identity)
+    this.order.push(identity)
+    if (this.order.length > FactDeduper.WINDOW) {
+      const gone = this.order.splice(0, this.order.length - FactDeduper.WINDOW)
+      for (const g of gone) this.seen.delete(g)
+    }
+    return false
+  }
+
+  /**
+   * 처음 보는 것만 돌려준다 — 그리고 몇 개를 버렸는지 함께 낸다.
+   *
+   * 버린 수를 함께 내는 이유: 알리지 않고 버리면 「보낸 수」와 「반영된 수」가 어긋나는데 아무도 그
+   * 이유를 모른다. 그 수가 크면 보내는 쪽이 되풀이 보내고 있다는 뜻이고, 그것은 고칠 일이다.
+   */
+  filter<T>(envelopes: readonly T[]): { fresh: T[]; duplicates: number } {
+    const fresh: T[] = []
+    let duplicates = 0
+    for (const e of envelopes) {
+      const id = factIdentity(e)
+      if (id === undefined) {
+        fresh.push(e)
+        continue
+      }
+      if (this.known(id)) duplicates++
+      else fresh.push(e)
+    }
+    return { fresh, duplicates }
+  }
+
+  /** 기억하고 있는 정체의 수 — 계기가 읽는다. */
+  size(): number {
+    return this.seen.size
+  }
+}