@things-factory/headless-twin 10.0.17 → 10.0.18

package/server/engine/kpi-query.ts

@@ -19,7 +19,8 @@ import { mergeStreams } from '../service/twin-journal/event-type-split-shape.js'
 import { hydratedDate } from './read-time.js'
 import { Between, In } from 'typeorm'
 
-import { hierarchyOf, levelOfLocationType, electricalUpstreamOf, EMS_LOCATION_TYPES, EMS_PROPERTY, type TariffDeclaration } from '@operato/twin-kernel'
+import { type TariffDeclaration } from '@operato/twin-kernel'
+import { hierarchyOf, levelOfLocationType, electricalUpstreamOf, EMS_LOCATION_TYPES, EMS_PROPERTY } from '@operato/ops-contract'
 
 import { getReadRepository, getRepository } from '@things-factory/shell'
 
@@ -51,7 +52,7 @@ import { MAX_BASELINE_PERIODS, baselineWindows, summarizeBaseline, type Baseline
  * 나눈 값이라, 두 사실이 한 폴드에 들어와야 창이 어긋날 수 없다. 표본(`energy.measured`)은 읽지 않는다 —
  * 저널에 없고(§4.1 인제스트 계약) 여기서 필요한 것은 마감된 구간뿐이다.
  */
-const BUSINESS_EVENTS = ['task.status', 'order.status', 'energy.demand.window', 'energy.generation.period', 'energy.usage.period', 'energy.bill']
+const BUSINESS_EVENTS = ['task.status', 'order.status', 'energy.demand.window', 'energy.generation.period', 'energy.usage.period', 'energy.bill', 'energy.generation.price']
 
 /** 한 번에 계산할 이벤트 상한 — 큰 구간이 서버를 붙잡지 않게. */
 const MAX_EVENTS = 20000
@@ -63,7 +64,27 @@ const MAX_EVENTS = 20000
  * 메모리가 그만큼 든다. 셋(종류) × 둘(트윈)까지는 최악에 12만 행이고, 그 이상은 예전 한 질의로 간다 —
  * 느리지만 답은 같다.
  */
-const KPI_MAX_SPLIT = 6
+/*
+ * ── 나눠 물을 수 있는 갈래의 최대 (2026-08-30 실측) ──────────────────────────
+ *
+ * 6 이었다. 그런데 **한 현장에 트윈이 여럿인 것이 이 제품의 정상**이다(창고·공정·야드가 한 현실을
+ * 각각 본다). 트윈 3개 × 종류 6가지 = 18 이라 조건에 안 걸렸고, 한 질의로 떨어졌다.
+ *
+ * 같은 창·같은 행으로 두 모양을 쟀다(hatio-us, order.status 345만 건이 있는 하루):
+ *
+ *   한 질의(종류 IN + 시각순)   ix_twin_event_1 로 그 날 전체를 걷는다   25.987초 · 20,000건(잘림)
+ *   갈래 하나(종류 정확일치)     ix_twin_event_7 이 순서까지 준다          0.286초
+ *
+ * 91배다. 그리고 25초를 기다린 끝에 나오는 값이 **잘린 값**이다 — 사용자는 그 사실을 25초 뒤에 본다.
+ *
+ * ── 늘리는 대가 ────────────────────────────────────────────────────────────
+ * 갈래마다 상한까지 받아야 합칠 때 정확하므로(§`mergeStreams`), 갈래가 많으면 그만큼 든다.
+ * 최악은 `갈래 수 × MAX_EVENTS` 행이다. 다만 그 최악은 **모든 갈래가 창을 가득 채울 때**이고,
+ * 그때는 어차피 결과가 잘린다(그 사실은 `capped` 로 나간다).
+ *
+ * 32 는 트윈 4개 × 종류 8가지를 덮는다. 어휘가 더 늘면 이 수를 다시 재고 정한다.
+ */
+const KPI_MAX_SPLIT = 32
 
 export interface TwinKpiInput {
   domainId: string
@@ -480,6 +501,59 @@ function latestBillOf(domainId: string, instanceIds: string[]): { to: string; bi
   return best
 }
 
+/** 이 트윈들이 이어받고 있는 **발전 단가** — 창 안에 단가 사실이 없을 때 쓴다. */
+function latestGenerationPriceOf(
+  domainId: string,
+  instanceIds: string[]
+): { from: string; to: string; unitPrice: number; currency: string } | undefined {
+  let best: { from: string; to: string; unitPrice: number; currency: string } | undefined
+  for (const instanceId of instanceIds) {
+    const p = (TwinEngine.snapshot(domainId, instanceId) as any)?.energy?.generationPrice
+    if (!p?.from || !Number.isFinite(Number(p.unitPrice)) || !p.currency) continue
+    if (!best || Date.parse(p.from) > Date.parse(best.from)) {
+      best = { from: String(p.from), to: String(p.to), unitPrice: Number(p.unitPrice), currency: String(p.currency) }
+    }
+  }
+  return best
+}
+
+/**
+ * 이 트윈들의 **발전 정격** — 이용률의 분모.
+ *
+ * 커널이 고른다(설비 합 → 자리 합계, 교류 → 직류). 여러 트윈이면 합한다 — 한 현장의 발전은
+ * 트윈마다 나뉘어 있어도 같은 현장의 발전이다. 근거가 갈리면 약한 쪽(직류·자리)으로 적는다.
+ */
+function generationRatedOf(
+  domainId: string,
+  instanceIds: string[]
+): { kW: number; basis: 'ac' | 'dc'; from: 'equipment' | 'location' } | undefined {
+  let kW = 0
+  let basis: 'ac' | 'dc' = 'ac'
+  let from: 'equipment' | 'location' = 'equipment'
+  for (const instanceId of instanceIds) {
+    /* 스냅샷에서 읽는다 — 커널이 고른 값이다. 여기서 모델을 다시 뒤지면 고르는 규칙이 두 벌이 된다. */
+    const r = (TwinEngine.snapshot(domainId, instanceId) as any)?.energy?.generationRated
+    if (!r || !(Number(r.kW) > 0)) continue
+    kW += Number(r.kW)
+    if (r.basis === 'dc') basis = 'dc'
+    if (r.from === 'location') from = 'location'
+  }
+  return kW > 0 ? { kW, basis, from } : undefined
+}
+
+/** 이 트윈들이 이어받고 있는 **요금 기준** — 이 주기에 적용되는 값(청구서보다 먼저다). */
+function latestTariffBasisOf(domainId: string, instanceIds: string[]): { from: string; billingDemandKW?: number } | undefined {
+  let best: { from: string; billingDemandKW?: number } | undefined
+  for (const instanceId of instanceIds) {
+    const b = (TwinEngine.snapshot(domainId, instanceId) as any)?.energy?.tariffBasis
+    if (!b?.from) continue
+    if (!best || Date.parse(b.from) > Date.parse(best.from)) {
+      best = { from: String(b.from), ...(Number.isFinite(Number(b.billingDemandKW)) ? { billingDemandKW: Number(b.billingDemandKW) } : {}) }
+    }
+  }
+  return best
+}
+
 async function energyTopologyOf(
   domainId: string,
   instanceIds: string[],
@@ -810,7 +884,19 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
             : 'no operational events in the journal yet — there is nothing to measure (this is NOT "zero throughput").'
       }
     }
-    toMs = Date.parse(latest)
+    /*
+     * ── **미래를 성과 구간으로 삼지 않는다** (2026-08-30) ──────────────────────
+     *
+     * 마지막 기록이 미래일 수 있다. 한 원본이 **끝나지 않은 이번 달**의 요금 정보를 청구서로 보냈고,
+     * 청구서의 사건 시각은 기간의 끝이라 그 사실이 **내일** 일어난 것으로 적혔다. 그러자 구간이
+     * `내일 00:00 → 모레 00:00` 이 되어 그 현장의 화면에서 **어제 발전량이 사라졌다.** 오류는 나지
+     * 않았고 화면만 비어 있었다.
+     *
+     * 커널이 이제 그런 사실을 받지 않는다. 그래도 여기서 막는다 — **이미 적힌 것은 사라지지 않고**,
+     * 저널은 지우지 않기 때문이다. 그리고 성과는 지나간 일이다. 아직 오지 않은 구간의 성과라는 것은
+     * 없다.
+     */
+    toMs = Math.min(Date.parse(latest), Date.now())
     basis = 'latest-event'
   }
 
@@ -842,6 +928,10 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
    * **커널 상태에 이어져 있는 마지막 청구서**를 함께 넘긴다(§`EnergyState.lastBill`).
    */
   const lastBill = latestBillOf(input.domainId, instanceIds)
+  const tariffBasis = latestTariffBasisOf(input.domainId, instanceIds)
+  /* 이용률의 분모 — 커널이 모델의 선언에서 고른다(설비 합 → 자리 합계, 교류 → 직류). */
+  const generationRated = generationRatedOf(input.domainId, instanceIds)
+  const generationPrice = latestGenerationPriceOf(input.domainId, instanceIds)
   const kpi = foldKpi(events, { fromMs, toMs }, {
     groupBy: input.groupBy,
     locationArea: areaMap.locationArea,
@@ -849,6 +939,9 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
     meterFeeder: feederMap.meterFeeder,
     ...(tariffFound.tariff ? { tariff: tariffFound.tariff } : {}),
     ...(lastBill ? { lastBill } : {}),
+    ...(tariffBasis ? { tariffBasis } : {}),
+    ...(generationRated ? { generationRated } : {}),
+    ...(generationPrice ? { generationPrice } : {}),
     ...shiftCtx,
     groupLimit: input.groupLimit
   })

package/server/engine/local-declarations.ts

@@ -37,7 +37,8 @@
  * **속성 어휘는 사용자가 정의하지 않는다** — 커널이 정한 속성에 값을 넣는 문이다(그래서 이름도
  * 「사용자 정의 속성」이 아니다).
  */
-import { ATTENTION_PROPERTY, EMS_PROPERTY_SPEC, OPERATION_PROPERTY, OP_PARAM } from '@operato/twin-kernel'
+import { ATTENTION_PROPERTY, OPERATION_PROPERTY } from '@operato/twin-kernel'
+import { EMS_PROPERTY_SPEC, OP_PARAM } from '@operato/ops-contract'
 
 import { EQUIPMENT_PROPERTY, SPEED_TO_MPS } from './travel-estimator.ts'
 import { declarationTargetsOf } from './property-effects.ts'

package/server/engine/model-vocabulary.ts

@@ -25,7 +25,7 @@
  * 저장은 주는 대로 한다(새 쓰기는 이미 새 어휘다). 읽기가 정규화되므로, 저장된 옛 모델는 **다음에
  * 저장될 때 자연히 새 어휘로 옮겨간다** — 마이그레이션을 따로 실행하지 않는다.
  */
-import { readBoardLocations, readBoardEquipment } from '@operato/twin-kernel'
+import { readBoardLocations, readBoardEquipment } from '@operato/ops-contract'
 
 /** 흡수하고 **내보내지 않는** 옛 키 — 남겨 두면 소비처가 두 어휘를 다시 보게 된다. */
 const RETIRED_KEYS = ['nodes', 'movers', 'equipmentList'] as const // vocabulary-guard: allow — 옛 어휘를 흡수하는 것이 이 코드의 일이다(세대 이름을 적어야 흡수할 수 있다)

package/server/engine/oee-accumulator.ts

@@ -10,8 +10,10 @@
  *   - quality.output 이 없으면(예: WMS/YMS) quality=1(품질 개념 없음).
  * 시간축 = Date.parse(eventTime)(ms) — 구간 차분은 sim/실시간 무관하게 정확(고정 오프셋 상쇄).
  */
-import { computeOee } from '@operato/twin-kernel'
-import type { CanonicalEnvelope, OeeCounters, OeeMetrics } from '@operato/twin-kernel'
+/* OEE 공식은 계약에 있다 — 소비자가 셋이라(시뮬·미러·MES) 커널에 두면 밖에서 다시 쓰게 된다. */
+import { computeOee } from '@operato/ops-contract'
+import type { OeeCounters } from '@operato/ops-contract'
+import type { CanonicalEnvelope, OeeMetrics } from '@operato/ops-contract'
 
 interface Acc {
   status?: string

package/server/engine/twin-engine.ts

@@ -14,7 +14,8 @@ import { pubsub, getRepository, Domain } from '@things-factory/shell'
 import { And, IsNull, LessThanOrEqual, MoreThan } from 'typeorm'
 import { cacheService } from '@things-factory/cache-service'
 
-import type { ReducerCheckpoint, VocabularyElement } from '@operato/twin-kernel'
+import type { ReducerCheckpoint } from '@operato/twin-kernel'
+import type { VocabularyElement } from '@operato/ops-contract'
 import type { OeeCheckpoint } from './oee-accumulator.js'
 import { TwinEvent } from '../service/twin-event/twin-event.js'
 import { twinEventKeys } from '../service/twin-event/twin-event-keys.js'
@@ -76,11 +77,13 @@ import {
   type IngestWindow
 } from './ingest-health.js'
 import { FactDeduper } from './ingest-dedupe.js'
-import { EMS_PROPERTY } from '@operato/twin-kernel'
-import type { TwinKernel, TwinModelDef, StructureShift, SubscriptionMessage, TwinRuntime as TwinRuntimeType, CanonicalEnvelope } from '@operato/twin-kernel'
+import { EMS_PROPERTY } from '@operato/ops-contract'
+import type { SubscriptionMessage, TwinRuntime as TwinRuntimeType } from '@operato/twin-kernel'
+import type { TwinKernel, TwinModelDef, StructureShift, CanonicalEnvelope } from '@operato/ops-contract'
 
 /* 커널 런타임 로드 — CJS 번들(dist-cjs). 타입은 위 import type 로. replay = 이벤트열→상태 재구성(복구·시간여행). */
-const { WmsKernel, YmsKernel, MesKernel, EmsKernel, TwinRuntime, StateProjector, replay, replayFrom, replayWithCheckpoint, replaySegments, readBoardLocations, readBoardEquipment, DOMAIN_CATALOG, OP_EVENT, validateScenario } = require('@operato/twin-kernel')
+const { WmsKernel, YmsKernel, MesKernel, EmsKernel, TwinRuntime, StateProjector, replay, replayFrom, replayWithCheckpoint, replaySegments } = require('@operato/twin-kernel')
+const { readBoardLocations, readBoardEquipment, DOMAIN_CATALOG, OP_EVENT, validateScenario } = require('@operato/ops-contract')
 
 const KERNELS: Record<string, any> = { wms: WmsKernel, yms: YmsKernel, mes: MesKernel, ems: EmsKernel }
 
@@ -1609,6 +1612,8 @@ export class TwinEngine {
 
     const Kernel = kernelFor(kind)
     const kernel: TwinKernel = new Kernel(domainId, undefined, this.productionSpecOf(model))
+    /* 커널은 도메인으로 선다 — 어느 트윈인지는 여기서만 알려 줄 수 있다(§`factScope`). */
+    ;(kernel as any).scopeId = id
     kernel.loadTwinModel(model) // 구조만. 상태는 아래 웜스타트가 주입한다.
     this.applyOperations(kernel, model, id) // 시간·수율 명세(있으면) — 없으면 커널 기본값
     /* 추정기는 DB 조회를 포함해 비동기 — 기동을 막지 않고 붙는다(붙기 전 작업은 명세·상수로 산출). */
@@ -1814,6 +1819,8 @@ export class TwinEngine {
     if (this.instances[key]) return this.instances[key]
     const Kernel = kernelFor(kind)
     const kernel: any = new Kernel(domainId, undefined, this.productionSpecOf(model))
+    /* 커널은 도메인으로 선다 — 어느 트윈인지는 여기서만 알려 줄 수 있다(§`factScope`). */
+    ;(kernel as any).scopeId = id
     kernel.loadTwinModel(model)
     /* **세우는 쪽이 아는 사실은 세울 때 말한다.** 예전에는 첫 이벤트가 도착해야 커널이 스스로를
        관측 구동으로 여겼고, 그래서 아직 아무것도 못 받은 미러는 시뮬레이션 취급을 받았다. */
@@ -2416,9 +2423,24 @@ export class TwinEngine {
 
     if (carried.length) jobs.push(this.persistCarried(inst.domainId, inst.id, carried))
     if (plain.length && inst.revision != null) {
+      /*
+       * ── 마감된 구간 사실은 한 번만 적는다 (2026-08-30) ───────────────────────
+       *
+       * 이미 있는 것을 걸러낸 뒤에 번호를 매긴다. 걸러내기 전에 매기면 **쓰지 않은 번호가 비고**,
+       * 그 구멍이 저널의 리비전 연속성을 끊는다.
+       */
+      /*
+       * 번호는 **먼저 잡는다**(동기). 걸러낸 뒤에 잡으면 두 flush 가 겹칠 때 같은 번호를 두 번 쓴다.
+       * 걸러진 만큼 번호가 비지만, 그 구멍은 해롭지 않다 — 리비전은 같은 시각을 가리는 데만 쓰고
+       * 이어짐을 요구하지 않는다(저널 머리는 최대값이다).
+       */
       const start = inst.revision
       inst.revision = start + plain.length
-      jobs.push(this.persistBatch(inst.domainId, inst.id, plain, start))
+      jobs.push(
+        this.dropAlreadyWritten(inst.domainId, inst.id, plain).then(fresh =>
+          fresh.length ? this.persistBatch(inst.domainId, inst.id, fresh, start) : undefined
+        )
+      )
     }
     if (!jobs.length) return Promise.resolve()
     /*
@@ -2445,6 +2467,76 @@ export class TwinEngine {
    * 예전에는 이 경로가 **델타마다 한 행씩** 저장했다(그리고 행마다 구조 리비전을 물었다). 규모에서 그것이
    * 호스트를 먹었다(§7.1 실측). 여기서 구조 리비전은 **한 번만** 묻는다.
    */
+  /**
+   * **마감된 구간 사실은 한 번만 적는다** — 같은 사실이 두 번 오면 한 사실이다 (2026-08-30).
+   *
+   * ── 왜 쓰는 자리에서 막나 ──────────────────────────────────────────────────
+   * 커널이 그 사실들의 정체성을 내용에서 만든다(종류·대상·시작·끝). 그런데 저널의 기본키는 새로
+   * 만드는 uuid 라, **id 가 글자 하나까지 같아도 행이 따로 쌓였다.**
+   *
+   * 실측(2026-08-30): 발전 단가가 행 7개·서로 다른 id 4개였다. 8월 27일 단가가 세 벌 있었고,
+   * 그 구간의 수익이 세 번 세어진다.
+   *
+   * 커넥터가 커서로 막는 것이 첫 방어선이고 그쪽도 고쳤다. 그런데 **커넥터가 한 번 실수하면 저널이
+   * 부풀고 그 위의 모든 합이 틀린다.** 정체성은 커널이 선언한 사실이므로, 어느 문으로 들어오든
+   * 지켜져야 한다 — 채우기 경로에만 있으면 그 보증은 「어느 문으로 왔느냐」에 걸린다.
+   *
+   * ── 값이 싼 이유 ───────────────────────────────────────────────────────────
+   * 마감된 구간 사실만 본다(시점의 관측은 그대로 지난다 — 반복이 뜻을 가진다). 그것들은 드물어서
+   * (한 시간에 한 줄) 한 묶음에 몇 개뿐이고, 그 구간의 그 종류만 색인으로 읽는다.
+   */
+  private static readonly PERIOD_FACT_TYPES = new Set([
+    'energy.usage.period',
+    'energy.generation.period',
+    'energy.generation.price',
+    'energy.tariff.basis',
+    'energy.bill'
+  ])
+
+  static async dropAlreadyWritten(domainId: string, instanceId: string, envelopes: any[]): Promise<any[]> {
+    const periodFacts = envelopes.filter(e => this.PERIOD_FACT_TYPES.has(String(e?.eventType)) && typeof e?.eventId === 'string')
+    if (!periodFacts.length) return envelopes
+
+    const times = periodFacts.map(e => Date.parse(String(e.eventTime))).filter(n => Number.isFinite(n))
+    if (!times.length) return envelopes
+    const types = [...new Set(periodFacts.map(e => String(e.eventType)))]
+
+    const existing = await getRepository(TwinEvent)
+      .createQueryBuilder('e')
+      .select(['e.payload AS "payload"'])
+      .where('e.domain = :domainId', { domainId })
+      .andWhere('e.instanceId = :instanceId', { instanceId })
+      .andWhere('e.eventType IN (:...types)', { types })
+      .andWhere('e.eventTime BETWEEN :fromAt AND :toAt', { fromAt: new Date(Math.min(...times)), toAt: new Date(Math.max(...times)) })
+      .getRawMany<{ payload: unknown }>()
+      .catch(() => [] as { payload: unknown }[])
+
+    const seen = new Set<string>()
+    for (const row of existing) {
+      let p: any = row.payload
+      if (typeof p === 'string') {
+        try {
+          p = JSON.parse(p)
+        } catch {
+          p = undefined
+        }
+      }
+      if (typeof p?.eventId === 'string' && p.eventId) seen.add(p.eventId)
+    }
+    /* 한 묶음 안에 같은 것이 둘 있어도 하나만 적는다. */
+    const kept: any[] = []
+    for (const e of envelopes) {
+      if (!this.PERIOD_FACT_TYPES.has(String(e?.eventType)) || typeof e?.eventId !== 'string') {
+        kept.push(e)
+        continue
+      }
+      if (seen.has(e.eventId)) continue
+      seen.add(e.eventId)
+      kept.push(e)
+    }
+    return kept
+  }
+
   static async persistCarried(domainId: string, instanceId: string, items: { event: any; revision: number }[]): Promise<void> {
     const repo = getRepository(TwinEvent)
     const structureRev = await this.structureRevOf(domainId, instanceId)
@@ -2580,6 +2672,23 @@ export class TwinEngine {
   }
 
   /**
+   * ── **트윈은 설비의 마스터가 아니다** (사용자 결정 2026-08-30) ─────────────
+   *
+   * 인원·설비·자산의 마스터는 `@things-factory/ops-master` 다. 트윈은 그것을 **당겨 와** 모델에
+   * 반영하고, 여기 남는 것은 그 결과의 캐시다.
+   *
+   * 그래서 이 함수가 하는 일에 선이 있다.
+   *
+   *   트윈 안에서 사람이 더한 설비   가정·시뮬레이션의 사실이다 — 트윈이 든다 (지금 이 함수)
+   *   현장에 실제로 있는 설비        마스터의 사실이다 — 트윈이 만들지 않는다
+   *
+   * 이 함수는 **트윈 제어 명령**(`resource.add`) 뒤에만 불린다. 관측에서 설비가 생기는 경로가 아니다.
+   * 관측으로 모르는 설비가 들어오면 그것은 **마스터에 없는 것**이고, 트윈이 조용히 만들어 주면 두
+   * 곳이 서로 다른 설비 목록을 갖게 된다. 그때는 만들지 말고 「모르는 설비가 왔다」로 세어야 한다.
+   *
+   * 당겨 오는 길이 붙으면 이 주석의 위쪽 절반만 남는다.
+   *
+   * ── 원래 설명 ─────────────────────────────────────────────────────────────
    * 라이브 구조 변이(resource.add 등)를 저장된 model 에 반영 — 런타임 커널의 무버를 registry model.equipment 에 동기.
    * 이게 없으면 런타임엔 추가돼도(상태·저널엔 반영) 저장 model 는 원본이라 프로비저닝 편집기·재기동(loadTwinModel)이
    * 추가분을 잃는다. 기존 model.equipment 항목은 보존(homeLocation 유지)하고 새 id 만 append(추가 시점 location=homeLocation).
@@ -4372,6 +4481,55 @@ export class TwinEngine {
    * `offered` 는 **제시된 레코드 수**다(거부 여부 무관). 통과율을 서로 다른 두 계수기에서 나눠 계산하면
    * 분모와 분자가 다른 것을 세게 되므로, 한자리에서 본 수를 그대로 넘긴다.
    */
+  /**
+   * 이 트윈의 저널이 지금 몇 번까지 적혔나 — **접근자로 낸다.**
+   *
+   * 레지스트리를 밖에서 직접 색인하지 않게 하는 것이 이 저장소의 규율이다(§`engine-registry-access`).
+   * 지난 기록을 채우는 길이 다음 번호를 알아야 해서 열었다.
+   *
+   * 트윈이 도는 중이 아니면 0 이다 — 그때는 저널만 있고 이어 붙일 번호를 커널이 들고 있지 않다.
+   */
+  /**
+   * 마감된 구간 사실의 **이름을 지을 때 쓸 범위와 선언** — 유입 문에 넘긴다.
+   *
+   * ── 왜 호스트가 주나 (2026-08-30) ────────────────────────────────────────
+   * 커널은 `new Kernel(domainId, …)` 으로 서므로 **자기가 어느 트윈인지 모른다.** 그런데 설비 번호는
+   * 트윈 안에서만 통하는 이름표라, 한 도메인에 현장이 둘이면 서로 다른 설비의 같은 날이 한 사실이
+   * 된다. 실측으로 그 일이 났다 — 두 발전소의 `002` 가 겹쳐, 여러 현장을 함께 계산하는 성과 화면에서
+   * 한쪽 발전량이 사라진다.
+   *
+   * 선언된 정체성은 **커널이 답한다**(§`FlowEngine.equipmentIdentity`) — 판정을 두 곳에 두지 않는다.
+   * 트윈이 돌고 있지 않으면 선언을 물을 곳이 없으므로 범위만 넘긴다(그때도 겹치지는 않는다).
+   */
+  static factScope(
+    domainId: string,
+    instanceId: string
+  ): { scopeId: string; identityOf?: (kind: 'equipment' | 'meter', localId: string) => string | undefined } {
+    const inst = this.instances[runtimeKey(domainId, instanceId)]
+    const kernel: any = inst?.kernel
+    if (typeof kernel?.equipmentIdentity !== 'function') return { scopeId: instanceId }
+    return {
+      scopeId: instanceId,
+      identityOf: (kind, localId) => (kind === 'equipment' ? kernel.equipmentIdentity(localId) : undefined)
+    }
+  }
+
+  static journalHead(domainId: string, instanceId: string): number {
+    const inst = this.instances[runtimeKey(domainId, instanceId)]
+    return Number(inst?.revision ?? 0)
+  }
+
+  /**
+   * 저널에 그만큼 적었으니 번호를 밀어 준다.
+   *
+   * 밀어 주지 않으면 다음에 라이브가 **같은 번호를 다시 쓴다** — 같은 시각의 두 사실을 가릴 수 없게 된다.
+   */
+  static advanceJournalHead(domainId: string, instanceId: string, by: number): void {
+    const inst = this.instances[runtimeKey(domainId, instanceId)]
+    if (!inst || !(by > 0)) return
+    inst.revision = Number(inst.revision ?? 0) + by
+  }
+
   static recordIngestResult(
     domainId: string,
     instanceId: string,

package/server/routes.ts

@@ -44,7 +44,12 @@ process.on('bootstrap-module-domain-public-route' as any, (_app: any, router: an
        * 것과 밀어 받은 것이 구별되지 않는다. 구별되는 것은 유입 장부의 `sources` 한 줄뿐이다.
        */
       ingest: (instanceId, records) => {
-        const { accepted, rejected, masterData } = ingestCanonicalRecords(records as any, domain.id, new Date().toISOString())
+        const { accepted, rejected, masterData } = ingestCanonicalRecords(
+          records as any,
+          domain.id,
+          new Date().toISOString(),
+          TwinEngine.factScope(domain.id, instanceId)
+        )
         /* 사건이 아닌 것은 상태만 세운다 — 밀어 받는 길도 같은 규율이다(§`applyMasterData`). */
         if (masterData.length) TwinEngine.applyMasterData(domain.id, instanceId, masterData)
         const { applied, duplicates } = TwinEngine.ingestLiveResult(domain.id, instanceId, accepted, 'hook')

package/server/service/index.ts

@@ -42,6 +42,8 @@ import { resolvers as TwinForecastResolvers } from './twin-forecast/index.js'
 import { resolvers as TwinAttentionResolvers } from './twin-attention/index.js'
 import { resolvers as TwinMetricsResolvers } from './twin-metrics/index.js'
 import { resolvers as TwinReadinessResolvers } from './twin-readiness/index.js'
+/* 지난 기록 채우기 — 저널에만 쓰는 문. 라이브 유입과 판단이 달라 문을 따로 둔다. */
+import { resolvers as TwinBackfillResolvers } from './twin-backfill/index.js'
 
 export const entities = [
   /* ENTITIES */
@@ -73,6 +75,7 @@ export const schema = {
     ...TwinAttentionResolvers,
     ...TwinMetricsResolvers,
     ...TwinReadinessResolvers,
+    ...TwinBackfillResolvers,
     ...TwinIngestWindowResolvers,
     ...TwinModelResolvers,
     ...TwinSpaceResolvers,

package/server/service/reference/reference-live.ts

@@ -2,7 +2,8 @@ import { twinLog, twinWarn, twinError } from '../../engine/log.js'
 import { getRepository } from '@things-factory/shell'
 
 import { getAdapter, type ConnectionConfig, type LiveFeedContinuity, type ObservedItemFact, type SiteDescriptor } from './reference-adapter.js'
-import { TwinEngine, ingestCanonicalRecords, registerLiveFeedProbe, type CanonicalRecord } from '../../engine/index.js'
+import { TwinEngine, ingestCanonicalRecords, registerLiveFeedProbe } from '../../engine/index.js'
+import { type CanonicalRecord } from '@operato/ops-contract'
 import { TwinInstance } from '../twin-instance/twin-instance.js'
 import { TwinReference } from './twin-reference.js'
 
@@ -77,7 +78,12 @@ export async function startReferenceLiveFeed(
       return
     }
     const offered = Array.isArray(records) ? records.length : records ? 1 : 0
-    const { accepted, rejected, masterData } = ingestCanonicalRecords(records as CanonicalRecord[], domainId, new Date().toISOString())
+    const { accepted, rejected, masterData } = ingestCanonicalRecords(
+      records as CanonicalRecord[],
+      domainId,
+      new Date().toISOString(),
+      TwinEngine.factScope(domainId, instanceId)
+    )
     /*
      * ── **사건이 아닌 것은 상태만 세운다** (2026-08-28) ─────────────────────────
      *

package/server/service/reference/reference-master.ts

@@ -7,7 +7,7 @@
  * 좌표·representations 는 트윈 공간층(보완/추가). 실 시스템이 좌표를 안 주면 layout 없이 위상만 인제스트.
  */
 
-import type { DomainSystem, EquipmentLevel, TestSpecificationCriterion, WorkCalendarEntry } from '@operato/twin-kernel'
+import type { DomainSystem, EquipmentLevel, TestSpecificationCriterion, WorkCalendarEntry } from '@operato/ops-contract'
 
 export interface RefLocation {
   id: string
@@ -150,7 +150,16 @@ export interface RefEquipment {
   homeLocationId: string
   mtbfMs?: number // 평균 고장 간격(확률적 고장) — 지정 시 커널이 breakdown 시뮬 → 주목(고장) 발생
   mttrMs?: number // 평균 수리 시간
-  gs1Id?: string // 정식 GS1 정체성(§J) — 설비=GIAI.
+  /**
+   * **이 설비의 전역 정체성** — 커널 선언의 `equipment[].identity` 로 그대로 간다.
+   *
+   * 예전 이름은 `gs1Id` 였다. 그런데 **GS1 키가 아닌 것이 정상이다** — 실측한 값은 인버터의
+   * 하드웨어 식별자(`ES100000007d8d061d-1`)이고, 원본이 GIAI 를 주면 그것도 여기 들어온다.
+   * 이름이 한 종류만 가리키면 다른 종류가 들어올 때 그 자리를 못 쓴다.
+   *
+   * 자리(`RefLocation.gs1Id`)는 그대로다 — 그쪽은 실제로 SGLN 이 온다.
+   */
+  identity?: string
   /**
    * 교대(가동시간) — 이 시간대에만 배정된다. `startHour <= endHour` 면 같은 날, 넘어가면 야간(22→6).
    * 미지정=24시간 가용. 교대 밖 자원은 고장·계획정지와 **구별되는 이유**로 쉰다(상태에 드러난다).
@@ -740,7 +749,7 @@ export function masterToTwin(master: ReferenceMaster, catalog?: any): IngestedTw
 
   const equipment = (master.equipment ?? []).map(e => ({
     id: e.id, kind: e.kind, ...(e.name ? { name: e.name } : {}), ...(e.description ? { description: e.description } : {}), ...(e.testResults?.length ? { testResults: e.testResults } : {}),
-    homeLocation: e.homeLocationId, mtbfMs: e.mtbfMs, mttrMs: e.mttrMs, gs1Id: e.gs1Id,
+    homeLocation: e.homeLocationId, mtbfMs: e.mtbfMs, mttrMs: e.mttrMs, ...(e.identity ? { identity: e.identity } : {}),
     ...(e.window ? { window: e.window } : {}),
     /* 속성은 손대지 않고 통과 — 이동시간 추정기가 kind 별 속도를 여기서 읽는다(단위 코드 그대로). */
     ...(e.properties?.length ? { properties: e.properties } : {}), ...(e.workCalendar?.length ? { workCalendar: e.workCalendar } : {}), ...(e.testSpecificationIds?.length ? { testSpecificationIds: e.testSpecificationIds } : {}),

package/server/service/reference/reference-resolver.ts

@@ -7,7 +7,7 @@ import { ScalarObject, getRepository } from '@things-factory/shell'
 
 import { TwinEngine } from '../../engine/index.js'
 import { readRestartPolicy } from '../../engine/restart-policy.js'
-import { readBoardEquipment } from '@operato/twin-kernel'
+import { readBoardEquipment } from '@operato/ops-contract'
 
 import { applyKnobDefaults, filledKnobKeys } from './knob-defaults.js'
 import type { KnobDef } from './template-registry.js'

package/server/service/reference/template-registry.ts

@@ -4,7 +4,7 @@
  * 둘 다 같은 인제스트 경로(ingestMaster)로 흐른다 — 원천이 고정이냐 합성이냐만 다르다(board-authoring §10).
  * 앱(operato-twin)이 bootstrap 에서 자기 아키타입을 registerTemplate 한다. 표현(map/image/model) 무관.
  */
-import type { DomainSystem } from '@operato/twin-kernel'
+import type { DomainSystem } from '@operato/ops-contract'
 
 import type { ReferenceMaster } from './reference-master.js'