@things-factory/headless-twin 10.0.17 → 10.0.19

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

@@ -18,6 +18,7 @@
 import { ingestCanonicalRecords } from './engine/canonical-ingest.js'
 import { TwinEngine } from './engine/twin-engine.js'
 import { handleHook } from './service/reference/reference-hook.js'
+import { databaseStore } from './service/reference/hook-store.js'
 
 process.on('bootstrap-module-domain-public-route' as any, (_app: any, router: any) => {
   /*
@@ -39,12 +40,23 @@ process.on('bootstrap-module-domain-public-route' as any, (_app: any, router: an
       instanceId: String(ctx.params.instanceId ?? ''),
       headers: (ctx.request?.headers ?? {}) as Record<string, unknown>,
       body: ctx.request?.body,
+      /*
+       * 받은 바이트 그대로 — 서명을 확인하려면 이것이 있어야 한다. `koa-bodyparser` 가 파싱한 본문과
+       * 함께 남겨 준다. 파싱본을 다시 문자열로 만들면 키 순서와 공백이 달라져 서명이 맞지 않는다.
+       */
+      rawBody: typeof ctx.request?.rawBody === 'string' ? ctx.request.rawBody : undefined,
+      store: databaseStore(),
       /*
        * 폴링이 쓰는 길을 그대로 쓴다 — 검증도 유입도 같은 자리다. 그래서 트윈 쪽에서는 물어서 받은
        * 것과 밀어 받은 것이 구별되지 않는다. 구별되는 것은 유입 장부의 `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')
@@ -54,7 +66,11 @@ process.on('bootstrap-module-domain-public-route' as any, (_app: any, router: an
          */
         const undelivered = Math.max(0, accepted.length - applied - duplicates)
         TwinEngine.recordIngestResult(domain.id, instanceId, records.length, rejected, Date.now(), undelivered)
-        return { applied, duplicates, rejected: rejected.length }
+        /*
+         * 떨어진 것을 **수가 아니라 목록으로** 넘긴다 — 응답에 실어야 보내는 쪽이 그것만 따로 둘 수
+         * 있다. 수만 주면 배치 전체를 다시 보내거나 전부 버리는 두 갈래밖에 없다.
+         */
+        return { applied, duplicates, rejected }
       }
     })
     ctx.status = outcome.status

package/server/service/actuation/command-dispatcher.ts

@@ -0,0 +1,130 @@
+/*
+ * **승인을 지난 커맨드만 어댑터에 넘긴다** — 게이트가 서는 자리.
+ *
+ * ── 왜 이 자리인가 (2026-08-31) ──────────────────────────────────────────
+ * 설계가 「기본 = propose-only」를 정해 두었는데 코드에 그 규율이 없었다. 인티그레이션 레인이 어댑터에
+ * 조치를 붙이려다 그것을 보고 멈췄다 — 게이트 없이 붙이면 트윈이 사람 승인 없이 현장에 작업지시를
+ * 내린다. 작업지시는 취소해도 이미 만든 것이 남는다.
+ *
+ * ── 확인을 여기서 한 번만 한다 ───────────────────────────────────────────
+ * 어댑터는 승인을 확인하지 않는다. 그 확인은 이 파일이 했고 **타입이 그것을 증명한다**
+ * (`ApprovedCommand` 는 `approveCommand`·`asApproved` 로만 만들어진다). 어댑터가 또 확인하면 규칙이
+ * 두 벌이 되고, 한쪽만 고쳐지는 날이 온다.
+ *
+ * ── 저장소에 닿는 자리를 밖으로 낸다 ─────────────────────────────────────
+ * 훅에서와 같은 이유다(§`HookStore`). 시험이 **재기동을 넣을 수 있어야** 한다 — 승인이 프로세스 안에만
+ * 살아 있으면 「승인된다」는 보이지만 「다시 세운 뒤에도 승인이 남아 있나」는 보이지 않는다.
+ */
+import {
+  approveCommand,
+  asApproved,
+  nextCommandState,
+  passThroughReversible,
+  requiresApproval,
+  type ApprovedCommand,
+  type CommandApproval,
+  type TwinCommand
+} from '@operato/ops-contract'
+
+/** 조치의 결과 — 어댑터가 돌려준다. */
+export interface CommandAck {
+  ok: boolean
+  /** 저쪽 문서 · 작업 식별자. 되돌릴 때 무엇을 되돌릴지 말하려면 이것이 있어야 한다. */
+  ref?: string
+  error?: string
+}
+
+/** 커맨드가 사는 자리 — 재기동을 넘어야 한다. */
+export interface CommandStore {
+  load(domainId: string, id: string): Promise<TwinCommand | null>
+  save(domainId: string, command: TwinCommand): Promise<void>
+}
+
+/**
+ * 승인한다.
+ *
+ * 승인할 수 없는 상태면 계약이 던진다 — 여기서 답으로 돌려주지 않는 이유는, 실패를 답으로 주면 부르는
+ * 쪽이 그것을 무시할 수 있기 때문이다.
+ */
+export async function approve(
+  store: CommandStore,
+  domainId: string,
+  id: string,
+  approval: CommandApproval
+): Promise<TwinCommand> {
+  const command = await store.load(domainId, id)
+  if (!command) throw new Error(`모르는 커맨드다 (${id})`)
+
+  const approved = approveCommand(command, approval)
+  await store.save(domainId, approved)
+  return approved
+}
+
+/** 거절한다 — 여기서 끝난다. 되살아나지 않는다. */
+export async function reject(
+  store: CommandStore,
+  domainId: string,
+  id: string,
+  approval: CommandApproval
+): Promise<TwinCommand> {
+  const command = await store.load(domainId, id)
+  if (!command) throw new Error(`모르는 커맨드다 (${id})`)
+
+  const to = nextCommandState(command.state, 'reject')
+  if (!to) throw new Error(`${command.state} 상태의 커맨드는 거절할 수 없다 (${id})`)
+
+  const next: TwinCommand = { ...command, state: to, approval }
+  await store.save(domainId, next)
+  return next
+}
+
+/**
+ * 어댑터에 넘긴다 — **승인을 지나지 않은 것은 여기서 막힌다.**
+ *
+ * `actuate` 는 `ApprovedCommand` 만 받으므로, 승인 없이 이 함수를 지나가는 길이 없다. 저장소에서
+ * 되세운 커맨드는 타입이 지워진 채로 오므로 `asApproved` 로 다시 확인한다 — 확인 없이 표식을 붙이면
+ * **재기동이 게이트를 여는 길**이 된다.
+ *
+ * 되돌릴 수 있는 커맨드는 사람 없이 지난다(시뮬·what-if). 그 판단도 계약이 한다.
+ */
+export async function dispatch(
+  store: CommandStore,
+  domainId: string,
+  id: string,
+  actuate: (command: ApprovedCommand) => Promise<CommandAck>
+): Promise<TwinCommand> {
+  const command = await store.load(domainId, id)
+  if (!command) throw new Error(`모르는 커맨드다 (${id})`)
+
+  /*
+   * 되돌릴 수 있는 것은 제안 상태에서 바로 지난다. 되돌릴 수 없는 것은 승인 기록이 있어야 하고,
+   * 없으면 여기서 던진다 — 조용히 건너뛰면 그 커맨드가 승인 없이 나간 것이 된다.
+   */
+  const approved: ApprovedCommand =
+    command.state === 'proposed' && !requiresApproval(command) ? passThroughReversible(command) : asApproved(command)
+
+  const to = nextCommandState(approved.state, 'dispatch')
+  if (!to) throw new Error(`${approved.state} 상태의 커맨드는 넘길 수 없다 (${id})`)
+
+  /*
+   * **넘기기 전에 「넘기는 중」을 먼저 적는다.** 넘기고 나서 적으면, 그 사이에 프로세스가 죽었을 때
+   * 저쪽은 받았는데 우리는 안 보낸 줄 알고 다시 보낸다. 현장이 두 번 움직인다.
+   */
+  const dispatching: TwinCommand = { ...approved, state: to }
+  await store.save(domainId, dispatching)
+
+  let ack: CommandAck
+  try {
+    ack = await actuate(approved)
+  } catch (e: any) {
+    const failed: TwinCommand = { ...dispatching, state: 'failed', error: String(e?.message ?? e) }
+    await store.save(domainId, failed)
+    return failed
+  }
+
+  const settled: TwinCommand = ack?.ok
+    ? { ...dispatching, state: 'acked', dispatchRef: ack.ref }
+    : { ...dispatching, state: 'failed', error: ack?.error ?? '어댑터가 이유를 말하지 않았다' }
+  await store.save(domainId, settled)
+  return settled
+}

package/server/service/actuation/command-store.ts

@@ -0,0 +1,62 @@
+/*
+ * 커맨드가 저장소에 닿는 두 자리 — 찾는 것과 적는 것.
+ *
+ * 디스패처가 엔티티를 직접 가져오면 그 파일을 부르는 시험이 TypeORM 데코레이터를 지나게 되고, 시험이
+ * 서지 않는다. 그러면 **게이트의 배선을 아무 시험도 걷지 않게 된다** — 훅에서 이미 겪은 부류다
+ * (§`hook-store.ts`).
+ */
+import { getRepository } from '@things-factory/shell'
+
+import type { TwinCommand } from '@operato/ops-contract'
+
+import { hydratedDate } from '../../engine/read-time.js'
+
+import { TwinCommandRecord } from './twin-command.js'
+import type { CommandStore } from './command-dispatcher.js'
+
+/**
+ * 행 → 커맨드. 상태 어휘는 계약이 정한 문자열 그대로다.
+ *
+ * `createdAt` 은 드라이버가 준 값이라 **직접 날짜로 만들지 않는다** — 드라이버마다 모양이 다르고,
+ * 문자열로 오는 드라이버에서는 시간대가 없는 값이 된다. `hydratedDate` 가 그 컬럼의 정의를 보고 푼다.
+ */
+function toCommand(repo: any, row: TwinCommandRecord): TwinCommand {
+  return {
+    id: row.id,
+    instanceId: row.instanceId,
+    type: row.type,
+    ...(row.payload ? { payload: row.payload } : {}),
+    origin: row.origin as TwinCommand['origin'],
+    proposedAt: hydratedDate(repo, 'createdAt', row.createdAt)?.toISOString() ?? '',
+    /* 없는 것을 거짓으로 채우지 않는다 — 비어 있음이 「되돌릴 수 없다」의 뜻이다. */
+    ...(row.reversible === null || row.reversible === undefined ? {} : { reversible: row.reversible }),
+    state: row.state as TwinCommand['state'],
+    ...(row.decidedBy ? { approval: { by: row.decidedBy, at: row.decidedAt ?? '', ...(row.decisionNote ? { note: row.decisionNote } : {}) } } : {}),
+    ...(row.dispatchRef ? { dispatchRef: row.dispatchRef } : {}),
+    ...(row.error ? { error: row.error } : {})
+  }
+}
+
+/** 실제 저장소를 쓰는 구현 — 리졸버가 이것을 넣는다. */
+export function databaseCommandStore(): CommandStore {
+  return {
+    load: async (domainId: string, id: string) => {
+      const repo = await getRepository(TwinCommandRecord)
+      const row = await repo.findOne({ where: { domain: { id: domainId }, id } }).catch(() => null)
+      return row ? toCommand(repo, row) : null
+    },
+    save: async (domainId: string, command: TwinCommand) => {
+      await getRepository(TwinCommandRecord).update(
+        { id: command.id, domain: { id: domainId } },
+        {
+          state: command.state,
+          decidedBy: command.approval?.by ?? null,
+          decidedAt: command.approval?.at ?? null,
+          decisionNote: command.approval?.note ?? null,
+          dispatchRef: command.dispatchRef ?? null,
+          error: command.error ?? null
+        } as any
+      )
+    }
+  }
+}

package/server/service/actuation/index.ts

@@ -0,0 +1,8 @@
+import { TwinCommandRecord } from './twin-command.js'
+
+export const entities = [TwinCommandRecord]
+export const resolvers = []
+
+export * from './twin-command.js'
+export * from './command-dispatcher.js'
+export * from './command-store.js'