@things-factory/headless-twin 10.0.8 → 10.0.10

package/server/engine/attention-digest.ts

@@ -0,0 +1,102 @@
+/*
+ * 주의 신호 요약 — **순수**. "화면이 실제로 쓰는 두 가지만 값싸게 만든다."
+ *
+ * ── 왜 있나 (2026-08-05) ────────────────────────────────────────────────────
+ * 축 선택으로 리프레시를 80KB → 2KB 로 줄였는데, **신호가 많은 트윈은 거기서 막혔다**: `hatio-yard`
+ * 는 신호 397건이 108KB 라 5배 감소에 그쳤다. 그런데 화면이 그 397건으로 하는 일은 둘뿐이다.
+ *
+ *  ① 레일에 **20건**만 보여주고 나머지는 "N건 더" 라고만 말한다.
+ *  ② 자리(폴리곤)를 칠할 **자리별 최고 심각도**를 뽑는다 — 397건이 자리 7곳의 색 7개로 접힌다.
+ *
+ * 즉 전량을 내려보내 클라이언트가 접는 구조였다. 접는 것은 값싸므로 **서버가 접어서 보낸다.**
+ *
+ * ── 조용히 자르지 않는다 ────────────────────────────────────────────────────
+ * 잘랐다는 사실과 **전체 개수**를 함께 보낸다. 경고 목록에서 조용한 누락은 "괜찮은 줄 알았다" 로
+ * 이어진다 — 레일이 이미 "N건 더" 를 말하고 있었고, 그 N 은 전체 개수에서 나와야 맞다.
+ *
+ * ── 정렬을 한 곳에 둔다 ─────────────────────────────────────────────────────
+ * 상위 N 을 서버가 고르므로 **클라이언트와 같은 순서**여야 한다. 순서가 다르면 서버가 고른 20건이
+ * 화면이 고를 20건과 달라지고, 그 어긋남은 아무 데서도 오류로 드러나지 않는다.
+ * 순서 = 확인된 것은 아래로, 그다음 심각도 높은 것부터(클라이언트 정렬과 동일).
+ */
+
+/** 알람 표준(ISA-18.2) 우선순위 — 큰 값이 급하다. */
+const RANK: Record<string, number> = { low: 1, medium: 2, high: 3, critical: 4 }
+
+interface AttentionLike {
+  id?: string
+  /** 어느 트윈(렌즈)에서 온 신호인가 — 공간에서 모을 때 붙는다. */
+  instanceId?: string
+  severity?: string
+  state?: string
+  anchor?: { locationId?: string }
+}
+
+export interface AttentionDigestResult {
+  /** 상위 N — 레일이 그리는 것. */
+  attentions: AttentionLike[]
+  /** 전체 개수 — 레일의 "N건 더" 가 이 값에서 나온다(자른 사실을 밝힌다). */
+  attentionTotal: number
+  /**
+   * 자리별 최고 심각도 — **전량을 근거로** 접는다.
+   *
+   * 상위 N 만으로 접으면 20위 밖의 신호를 가진 자리가 색을 잃는다. 그것이 이 요약의 핵심 이유다:
+   * 레일은 잘라도 되지만 **지도 색은 잘라선 안 된다.**
+   */
+  severityByLocation: Record<string, string>
+}
+
+/** 화면 정렬과 같은 순서 — 확인된 것은 아래로, 그다음 심각도 내림차순. */
+export const compareAttentions = (a: AttentionLike, b: AttentionLike): number =>
+  (a.state === 'acknowledged' ? 1 : 0) - (b.state === 'acknowledged' ? 1 : 0) ||
+  (RANK[b.severity ?? ''] ?? 0) - (RANK[a.severity ?? ''] ?? 0)
+
+/**
+ * 신호를 요약한다.
+ *
+ * `limit` 이 없거나 0 이하면 **자르지 않는다** — 자르는 쪽이 기본이면 이 값을 모르는 소비처가
+ * 조용히 일부만 받는다(요약을 도입하다 만드는 전형적인 사고다).
+ */
+export function digestAttentions(attentions: readonly AttentionLike[] | undefined | null, limit?: number): AttentionDigestResult {
+  const all = Array.isArray(attentions) ? attentions : []
+
+  /* 자리 색은 전량으로 접는다 — 잘린 뒤에 접으면 색을 잃는 자리가 생긴다. */
+  const severityByLocation: Record<string, string> = {}
+  for (const a of all) {
+    const nid = a?.anchor?.locationId
+    if (!nid) continue
+    const cur = severityByLocation[nid]
+    if (!cur || (RANK[a.severity ?? ''] ?? 0) > (RANK[cur] ?? 0)) severityByLocation[nid] = a.severity ?? ''
+  }
+
+  const sorted = [...all].sort(compareAttentions)
+  const capped = limit && limit > 0 ? sorted.slice(0, limit) : sorted
+  return { attentions: capped, attentionTotal: all.length, severityByLocation }
+}
+
+/** 렌즈 하나가 낸 신호 — 어느 트윈에서 왔는지와 함께. */
+export interface LensAttentions {
+  instanceId: string
+  attentions: readonly AttentionLike[] | undefined | null
+}
+
+/**
+ * 여러 렌즈의 신호를 **한 현장의 목록으로** 모은다.
+ *
+ * 한 공장에 WMS·MES·YMS 가 함께 있으므로 "이 현장에서 봐야 할 것" 은 렌즈 하나로 답할 수 없다.
+ * 모으면서 지키는 것 셋:
+ *
+ *  ① **어느 트윈에서 왔는지 붙인다**(`instanceId`) — 조치는 결국 그 트윈에 보내야 하고, 공간에서 보면
+ *     같은 자리 id 가 렌즈마다 다른 것을 가리킬 수 있다.
+ *  ② **순서는 렌즈 순서가 아니라 급한 순서다** — 앞 렌즈의 낮은 신호가 뒤 렌즈의 심각한 신호를
+ *     밀어내면, 상위 N 만 보는 화면에서 정작 급한 것이 안 보인다.
+ *  ③ **자리 색은 렌즈를 가로질러 가장 급한 것으로** 접는다 — 두 렌즈가 같은 자리를 가리키면 그 자리는
+ *     하나의 현실이므로 더 급한 쪽이 이긴다(둘 중 하나를 임의로 고르면 색이 렌즈 순서에 따라 달라진다).
+ */
+export function mergeLensAttentions(lenses: readonly LensAttentions[], limit?: number): AttentionDigestResult {
+  const all: AttentionLike[] = []
+  for (const lens of lenses) {
+    for (const a of lens.attentions ?? []) all.push({ ...a, instanceId: lens.instanceId } as AttentionLike)
+  }
+  return digestAttentions(all, limit)
+}

package/server/engine/canonical-ingest.ts

@@ -1,4 +1,6 @@
-import { ingest, type AdapterRule, type IngestResult } from '@operato/twin-kernel'
+import { ingest, ingestEnergyRecords, ingestEnergyEquipmentRecords, isEnergyRecord,
+  isEnergyEquipmentRecord, type AdapterRule, type EnergyRecord,
+  type EnergyEquipmentRecord, type IngestResult } from '@operato/twin-kernel'
 
 /*
  * 정규 레코드 → 커널 검증 ACL → CanonicalEnvelope (P1 seam 코어).
@@ -40,11 +42,41 @@ export interface CanonicalRecord {
 
 /** 정규 레코드[] → 검증된 CanonicalEnvelope[] (+ 거부분). 순수 함수. 단일→객체도 배열로 정규화. */
 export function ingestCanonicalRecords(
-  records: CanonicalRecord | CanonicalRecord[] | undefined | null,
+  records:
+    | CanonicalRecord
+    | EnergyRecord
+    | EnergyEquipmentRecord
+    | (CanonicalRecord | EnergyRecord | EnergyEquipmentRecord)[]
+    | undefined
+    | null,
   tenantId: string,
   defaultEventTime: string
 ): IngestResult {
   const arr = Array.isArray(records) ? records : records ? [records] : []
-  const tagged = arr.map(r => ({ ...r, sourceType: 'twin' }))
-  return ingest(tagged, TWIN_INGEST_RULES, { tenantId, defaultEventTime })
+  /*
+   * **어휘가 둘이다** — 물류(EPCIS)와 에너지. 예전에는 이 함수가 무조건 `ObjectEvent` 를 만들었고,
+   * 그래서 계측을 이 길로 넣으면 `epc` 가 없어 거부되거나(그나마 나은 쪽) 엉뚱한 물품 관측이 됐다.
+   *
+   * 판정은 커널이 한 곳에서 한다(`isEnergyRecord`) — 여기서 다시 짐작하면 소비처마다 답이 달라진다.
+   * 봉투는 같은 것을 쓰므로 아래 소비처(미러·저널·방송)는 이 갈림을 알 필요가 없다.
+   */
+  const energy = arr.filter(isEnergyRecord) as EnergyRecord[]
+  /* 세 번째 어휘 — 설비가 낸 자기 에너지 상태(발전·저장·감축 여지·개폐 위치). 계량과 갈라 두는
+     이유는 커널에 적혀 있다: 계량은 구간에 누적되고, 이것들은 그 설비의 지금이다. */
+  const energyEquipment = arr.filter(isEnergyEquipmentRecord) as unknown as EnergyEquipmentRecord[]
+  const epcis = arr.filter(r => !isEnergyRecord(r) && !isEnergyEquipmentRecord(r)) as CanonicalRecord[]
+
+  const epcisResult = epcis.length
+    ? ingest(epcis.map(r => ({ ...r, sourceType: 'twin' })), TWIN_INGEST_RULES, { tenantId, defaultEventTime })
+    : { accepted: [], rejected: [] }
+  const energyResult = energy.length ? ingestEnergyRecords(energy, { tenantId, defaultEventTime }) : { accepted: [], rejected: [] }
+  const equipmentResult = energyEquipment.length
+    ? ingestEnergyEquipmentRecords(energyEquipment, { tenantId, defaultEventTime })
+    : { accepted: [], rejected: [] }
+
+  /* 거부분을 합쳐 돌려준다 — 어느 어휘에서 거부됐는지는 이유 문구가 말한다. */
+  return {
+    accepted: [...epcisResult.accepted, ...energyResult.accepted, ...equipmentResult.accepted],
+    rejected: [...epcisResult.rejected, ...energyResult.rejected, ...equipmentResult.rejected]
+  }
 }

package/server/engine/command-routing.ts

@@ -0,0 +1,67 @@
+/*
+ * 커맨드 라우팅 판정 — **순수**. "이 커맨드를 누구에게 보낼 것인가" 만 정한다.
+ * 실제 dispatch·저널 기록은 엔진이 한다(`design/plans/command-routing.md` §1·§4 P0).
+ *
+ * ── 왜 떼어냈나 ─────────────────────────────────────────────────────────────
+ * 예전에는 리졸버가 `inst.runtime.dispatch(...)` 를 곧바로 불렀다. `runtime` 은 **시뮬 경로에서만**
+ * 만들어지므로 실물을 비추는 트윈(mirror)에서는 그 한 줄이 `TypeError` 로 터졌다 — 조치 채널이
+ * 통째로 닿지 않았고, 사용자에게는 이유 있는 거절이 아니라 그냥 실패였다.
+ *
+ * 판정이 코드 한가운데 있으면 이런 부류를 테스트로 못 잡는다(엔진은 DB·TypeORM 을 물고 있어 단위
+ * 테스트가 불러올 수 없다). 그래서 판정만 순수하게 떼어 둔다 — `planWarmStart` 와 같은 이유다.
+ *
+ * ── 판정 규칙 = 권위 × 성격 ─────────────────────────────────────────────────
+ * | 성격 \ 모드      | 시뮬            | 미러(현실을 비춤)                    |
+ * | 액추에이션        | 커널 런타임      | **거절**(아웃바운드 어댑터 미결선)     |
+ * | 주석(확인 ack)    | 커널 런타임      | 관측 커널                            |
+ *
+ * 미러에서 액추에이션을 그냥 허용하면 **새 거짓말이 생긴다**: 트윈은 "보류됨" 이라 말하고 실 시스템은
+ * 모른다. 조용히 커널만 바꾸지 않고, 이유를 밝혀 거절한다.
+ *
+ * 반면 확인(ack)은 액추에이션이 아니다 — 신호를 봤다는 트윈 쪽 주석이라 현실을 건드리지 않는다.
+ * 미러에서도 성립해야 하므로 관측 커널로 보낸다.
+ */
+
+/** 관측 쪽 주석 커맨드 — 현실을 바꾸지 않으므로 미러에서도 통과한다. */
+const ANNOTATION_COMMANDS = new Set<string>(['attention.ack'])
+
+/** 라우팅에 필요한 인스턴스 사실만 — 엔진 객체를 그대로 받지 않는다(순수하게 유지). */
+export interface RoutableInstance {
+  /** 'live' 면 현실을 비추는 트윈(미러). 그 외는 시뮬. */
+  mode?: string
+  /** 커널 런타임(tick/dispatch)이 붙어 있나 — 시뮬 경로에서만 만들어진다. */
+  hasRuntime: boolean
+  /** 관측 커널이 dispatch 를 받을 수 있나. */
+  hasKernelDispatch: boolean
+}
+
+export type CommandRoute =
+  /** 커널 런타임으로(시뮬 — 커널이 세계다). */
+  | { target: 'runtime' }
+  /** 관측 커널로(미러 — 주석만). 방출된 사실은 저널 큐에 실어야 한다. */
+  | { target: 'kernel' }
+  /** 보내지 않는다. 사유는 언어 중립 코드 — 화면이 `twin.cmderr.<code>` 로 사람 말을 만든다. */
+  | { target: 'reject'; errorCode: string; errorParams?: Record<string, string | number> }
+
+/** 이 커맨드가 실 프로세스를 바꾸는 것인가(= 액추에이션). */
+export const isActuation = (type: string): boolean => !ANNOTATION_COMMANDS.has(type)
+
+/**
+ * 어디로 보낼지 정한다.
+ *
+ * `inst` 가 없거나 호출자 도메인 소유가 아니면 **같은 사유로** 거절한다 — 존재 여부를 알려 주면
+ * 다른 테넌트의 인스턴스 id 를 추측할 수 있다(있음/없음이 구별되면 그것이 정보다).
+ */
+export function routeCommand(inst: RoutableInstance | undefined, ownedByCaller: boolean, type: string): CommandRoute {
+  if (!inst || !ownedByCaller) return { target: 'reject', errorCode: 'no-instance' }
+  if (!type) return { target: 'reject', errorCode: 'unknown-command' }
+
+  if (inst.mode !== 'live') {
+    /* 시뮬 — 커널이 세계다. 런타임이 없으면 예외를 던지지 않고 이유를 말한다. */
+    return inst.hasRuntime ? { target: 'runtime' } : { target: 'reject', errorCode: 'no-runtime' }
+  }
+
+  /* 미러 — 실 프로세스 변경은 아웃바운드 어댑터의 몫이고 아직 결선되지 않았다. */
+  if (isActuation(type)) return { target: 'reject', errorCode: 'actuation-not-wired', errorParams: { type } }
+  return inst.hasKernelDispatch ? { target: 'kernel' } : { target: 'reject', errorCode: 'no-runtime' }
+}

package/server/engine/energy-topology.ts

@@ -0,0 +1,189 @@
+/*
+ * 전력 계통도 — **선언된 것만 그린다.** 순수.
+ *
+ * ── 왜 필요한가 (2026-08-18) ────────────────────────────────────────────────
+ * 분기별 막대는 「어디가 많이 쓰나」에 답하지만 **어디에 걸려 있나**에 답하지 못한다. 실제로 부딪힌
+ * 세 가지가 전부 계통 질문이었다:
+ *  · 「하위 계량이 덮지 않는 327 kWh」 — 그 몫이 수전 직결 부하인지, 계량 없는 구간인지 표로는 모른다.
+ *  · 커넥터는 결선을 모르는 부하를 **수전에 매단다**(정직한 선택). 그런데 그 사실이 화면에 없었다.
+ *  · 「계량기를 어디에 더 달아야 하나」 — 어두운 구간이 보여야 답할 수 있다.
+ *
+ * ── 무엇을 그리지 않나 ─────────────────────────────────────────────────────
+ * **보호 계통 단선도(SLD)가 아니다.** 차단기 정격·보호 협조·상(phase)·결선 방식은 모델에 없고, 그럴듯한
+ * 단선도를 그리면 갖지 않은 공학적 충실도를 주장하게 된다. 여기서 그리는 것은 **트윈이 선언한 관계**
+ * (자리의 계층 + 설비의 소속)와 **계량이 실제로 덮는 범위**뿐이다. 한계는 소비처가 화면에 적는다.
+ *
+ * ── 조용히 빠뜨리지 않는다 ─────────────────────────────────────────────────
+ * 자리를 모르는 설비, 계량기가 없는 자리, 계량이 덮지 않는 몫은 **각자 자기 칸으로** 나온다. 그림에서
+ * 사라지면 사용자는 자기 현장이 다 그려졌다고 믿는다.
+ */
+import { EMS_LOCATION_TYPES, electricalUpstreamOf } from '@operato/twin-kernel'
+
+/** 계통의 한 구간(수전·분기·구역) — 자리 하나가 곧 구간이다. */
+export interface TopologySegment {
+  id: string
+  /** 카탈로그 자리 타입(`incoming`·`feeder`·`submeter-zone`). */
+  type: string
+  label?: string
+  /** 이 자리에 달린 계량 지점 id 들 — 비어 있으면 **어두운 구간**이다(값을 알 길이 없다). */
+  meters: string[]
+  /** 이 구간의 전력량과 근거 — 폴드가 낸 것만 싣는다(우리가 다시 계산하지 않는다). */
+  kWh?: number
+  basis?: 'measured' | 'apportioned'
+  /**
+   * **피크가 찍힌 순간** 이 구간이 얼마였나(kW) — 요금이 걸린 수다.
+   *
+   * 전력량이 큰 구간과 피크를 만든 구간은 다를 수 있다(하루 종일 조금씩 쓰는 부하 vs 잠깐 크게 쓰는 부하).
+   * 그림에 둘을 함께 두면 「어느 분기를 깎아야 피크가 내려가나」가 바로 읽힌다.
+   */
+  peakKW?: number
+  /** 이 자리에 매달린 부하(설비) — 종류를 그대로 싣는다. */
+  loads: { id: string; kind: string }[]
+  /**
+   * 계통 설비(차단기·태양광·축전지) — 부하가 아니라 계통의 일부다.
+   *
+   * `live` 는 **지금 값**이다(구간 값이 아니다): 태양광이 지금 몇 kW 를 만들고, 축전지가 얼마를 내보내며
+   * 충전율이 얼마인가. 원천이 보내 주는 사실이라 우리가 만들지 않는다 — 보내지 않은 필드는 없다.
+   *
+   * 시각(`measuredAt`)을 함께 나른다: 계측이 끊기면 **멈춘 값을 지금 값으로 그리게** 되고, 그것이 화면이
+   * 낼 수 있는 가장 나쁜 거짓이다(값이 그럴듯할수록 위험하다).
+   */
+  gear: {
+    id: string
+    kind: string
+    live?: { generatedKW?: number; exportKW?: number; chargeKW?: number; dischargeKW?: number; soc?: number; measuredAt?: string }
+  }[]
+  children: TopologySegment[]
+}
+
+export interface EnergyTopology {
+  roots: TopologySegment[]
+  /**
+   * 자리를 모르는 설비 — 집이 없거나, 없는 자리를 가리킨다. 숨기면 그림의 설비 수가 모델과 달라진다.
+   */
+  unplaced: { id: string; kind: string }[]
+  /** 계량기가 없는 자리 id 들 — 「여기에 달면 무엇을 알 수 있나」의 답이 되는 목록이다. */
+  unmetered: string[]
+  /**
+   * 결선을 모르는 부하가 매달린 자리 — 커넥터가 「어느 분기가 이 설비에 전기를 주는지 모른다」고 판단해
+   * 수전에 매단 경우다. 그 자리의 몫이 분기로 내려가지 않는 이유가 이것이다.
+   */
+  loadsOnIncoming: number
+}
+
+/**
+ * 이 설비의 **지금 값** — 스냅샷에서 그 설비를 찾아 에너지 축의 값만 옮긴다.
+ *
+ * 종류가 아는 필드만 옮긴다: 태양광에 충전율을 붙이거나 축전지에 발전량을 붙이면, 화면은 그것을 사실로
+ * 그리고 사람은 그 설비가 그런 일을 한다고 읽는다(커널이 종류별로 필드를 가려 받는 것과 같은 규율).
+ */
+function liveOf(
+  state: readonly any[] | undefined | null,
+  id: string,
+  kind: string
+): { live: NonNullable<TopologySegment['gear'][number]['live']> } | undefined {
+  const e = (state ?? []).find(x => String(x?.id ?? '') === id)
+  if (!e) return undefined
+  const num = (v: unknown): number | undefined => (Number.isFinite(Number(v)) ? Number(v) : undefined)
+  const live: NonNullable<TopologySegment['gear'][number]['live']> = {}
+  if (kind === 'pv-array') {
+    const g = num(e.generatedKW)
+    const x = num(e.exportKW)
+    if (g !== undefined) live.generatedKW = g
+    if (x !== undefined) live.exportKW = x
+  } else if (kind === 'battery') {
+    const soc = num(e.soc)
+    const dis = num(e.dischargeKW)
+    const cha = num(e.chargeKW)
+    if (soc !== undefined) live.soc = soc
+    if (dis !== undefined) live.dischargeKW = dis
+    if (cha !== undefined) live.chargeKW = cha
+  }
+  if (!Object.keys(live).length) return undefined
+  /* 값이 있으면 시각도 함께 — 없으면 붙이지 않는다(모르는 시각을 지금으로 만들지 않는다). */
+  if (e.measuredAt) live.measuredAt = String(e.measuredAt)
+  return { live }
+}
+
+const ELECTRICAL = new Set(EMS_LOCATION_TYPES as readonly string[])
+/** 부하가 아닌 계통 설비 — 이것들의 소비를 부하로 세면 총량이 이중으로 나뉜다. */
+const GEAR = new Set(['meter', 'breaker', 'pv-array', 'battery'])
+
+/**
+ * 모델 + 폴드 결과 → 계통 트리.
+ *
+ * @param model     트윈 모델(자리 계층 `parentId`, 설비 소속 `homeLocation`).
+ * @param energy    폴드가 낸 분기별 몫(있으면 노드에 싣는다 — 없으면 값 없이 구조만 그린다).
+ */
+export function buildEnergyTopology(
+  model: { locations?: any[]; equipment?: any[] } | undefined | null,
+  energy?: { byFeeder?: { key: string; kWh: number; basis?: 'measured' | 'apportioned'; peakKW?: number }[] } | null,
+  /**
+   * 지금의 설비 상태(스냅샷의 `equipment`) — 발전·저장의 **지금 값**을 기호 옆에 적기 위해서다.
+   *
+   * 없으면 값 없이 구조만 그린다. 여기서 값을 만들지 않는다: 원천이 보내지 않은 것은 모르는 것이다.
+   */
+  equipmentState?: readonly any[] | null
+): EnergyTopology {
+  const locations: any[] = (model?.locations ?? []).filter(n => n?.id && ELECTRICAL.has(String(n.type)))
+  const byId = new Map<string, TopologySegment>()
+  for (const n of locations) {
+    byId.set(String(n.id), {
+      id: String(n.id),
+      type: String(n.type),
+      ...(n.name ? { label: String(n.name) } : {}),
+      meters: [],
+      loads: [],
+      gear: [],
+      children: []
+    })
+  }
+
+  const share = new Map((energy?.byFeeder ?? []).map(f => [f.key, f]))
+  for (const [id, segment] of byId) {
+    const s = share.get(id)
+    if (s) {
+      segment.kWh = s.kWh
+      if (s.basis) segment.basis = s.basis
+      if (typeof s.peakKW === 'number') segment.peakKW = s.peakKW
+    }
+  }
+
+  /* 설비를 자기 자리에 붙인다 — 계량기는 「이 구간을 잰다」는 뜻이라 따로 모은다. */
+  const unplaced: { id: string; kind: string }[] = []
+  let loadsOnIncoming = 0
+  for (const e of (model?.equipment ?? []) as any[]) {
+    if (!e?.id) continue
+    const kind = String(e.kind ?? '')
+    const home = String(e.homeLocation ?? e.homeLocationId ?? '')
+    const at = byId.get(home)
+    if (!at) {
+      /* 전기 계통 밖의 자리에 사는 설비도 여기서는 「자리를 모른다」로 모은다 — 이 그림의 축은 계통이다. */
+      unplaced.push({ id: String(e.id), kind })
+      continue
+    }
+    if (kind === 'meter') at.meters.push(String(e.id))
+    else if (GEAR.has(kind)) at.gear.push({ id: String(e.id), kind, ...(liveOf(equipmentState, String(e.id), kind) ?? {}) })
+    else {
+      at.loads.push({ id: String(e.id), kind })
+      if (at.type === 'incoming') loadsOnIncoming++
+    }
+  }
+
+  /*
+   * 계층을 잇는 것은 **전기 상류**다 — 공간 부모(공장·구역)는 이 축이 아니다. 상류의 뜻은 커널이 읽는다
+   * (옛 세대는 그 안에서 흡수된다) — 여기서 다시 판정하면 화면과 계산이 다른 계통을 말하게 된다.
+   */
+  const roots: TopologySegment[] = []
+  const all = model?.locations ?? []
+  for (const n of locations) {
+    const segment = byId.get(String(n.id))!
+    const up = electricalUpstreamOf(all as any, String(n.id))
+    const parent = up ? byId.get(up) : undefined
+    if (parent && parent !== segment) parent.children.push(segment)
+    else roots.push(segment)
+  }
+
+  const unmetered = [...byId.values()].filter(n => !n.meters.length).map(n => n.id)
+  return { roots, unplaced, unmetered, loadsOnIncoming }
+}

package/server/engine/index.ts

@@ -1,8 +1,25 @@
 export * from './twin-engine.js'
 export * from './canonical-ingest.js'
 export * from './kpi-fold.js'
+export * from './property-effects.js'
+export * from './kpi-baseline.js'
+/* 지표 정본 표(TWIN_METRIC)·목표 판정 — 소비처(twin-ai 등)가 지표 이름을 다시 열거하지 않게. */
+export * from './kpi-target.js'
+export * from '@things-factory/headless-twin/dist-shared/kpi-broadcast.js'
+/* 집약 채널 태그(접두사 + 트윈별 태그 생성) — 소비처가 문자열을 다시 적지 않게 내보낸다. */
+export * from '@things-factory/headless-twin/dist-shared/entity-delta.js'
+/* 공간 계층의 단계 — 씬 표현·성과 카드·AI 가 같은 목록을 쓴다. */
+export * from '@things-factory/headless-twin/dist-shared/twin-level.js'
+/* 부하 계기판 — 어떤 작업이 이벤트 루프를 얼마나 쓰는지. */
+export * from './load-meter.js'
+/* 런타임 레지스트리 키 규약 — 소비처(다른 키 캐시·테스트)가 `:` 를 다시 적지 않게 함께 내보낸다. */
+export * from './runtime-key.js'
 export * from './kpi-query.js'
 export * from './spec-coverage.js'
 export * from './travel-estimator.js'
 export * from './measured-estimator.js'
 export * from './model-basis.js'
+export * from './live-feed-registry.js'
+/* 로컬 선언(현장·트윈) — 소비처(twin-ai 도구)가 명세·검사 규칙을 다시 적지 않게. */
+export * from './local-declarations.js'
+export * from './operation-basis.js'

package/server/engine/kpi-baseline.ts

@@ -0,0 +1,202 @@
+/*
+ * 여러 구간 동시 비교 — **"어제보다 나아졌다" 를 넘어선다.** 순수.
+ *
+ * ── 왜 필요한가 (성과 맵 ③) ─────────────────────────────────────────────────
+ * 지금 비교 축은 **한 구간**만 본다(직전 구간 또는 하루 전). 그래서 판단이 딱 한 문장에서 멈춘다:
+ * "어제보다 나아졌다." **어제도 나빴으면 그 말은 쓸모가 없다.** 목표(`kpi-target`)가 그 한계를 한쪽에서
+ * 풀지만, 목표를 아직 걸지 않은 현장은 여전히 자기 숫자가 평소와 같은지도 알 수 없다.
+ *
+ * 최근 며칠의 **같은 시간대**를 함께 접으면 목표 없이도 말할 수 있다 — "오늘 이 시간대는 지난 7일 중
+ * 가장 낮다." 그것이 이 파일이 만드는 것이다: 창 여러 개의 **분포**와 그 안에서 현재의 **자리**.
+ *
+ * ── 이 파일이 하지 않는 것 ──────────────────────────────────────────────────
+ * · **지표 어휘를 모른다.** 이름·방향·값 꺼내는 법은 `kpi-target.ts` 의 `TWIN_METRIC` 이 소유한다. 여기는
+ *   **이미 꺼낸 값**만 받는다 — 어휘가 두 곳에 생기면 그 사이에 매핑 표가 자라고 그것이 곧 방언이다.
+ *   (덤으로: 이 모듈은 런타임 import 가 없어 테스트가 소스를 그대로 든다.)
+ * · **DB·조회를 모른다.** 창 목록만 계산하고, 그 창을 읽는 것은 호출부의 일이다.
+ * · **좋고 나쁨의 임계를 발명하지 않는다.** "평소보다 나쁘다" 는 중앙값과의 비교로만 말한다 — 임의의
+ *   퍼센트 임계를 두면 그 숫자가 곧 숨은 목표가 된다.
+ *
+ * ── 정직성 규율 (이 도메인의 핵심) ──────────────────────────────────────────
+ *  ① **결측 창을 조용히 빼지 않는다.** 요청한 창 전부를 `measured` 와 함께 돌려주고, 분포는 측정된
+ *     것만으로 만든다. 빼고 말하면 "지난 7일" 이 실제로는 3일이었다는 것을 아무도 모른다.
+ *  ② **표본이 둘 미만이면 자리를 말하지 않는다.** 하나를 분포라 부를 수 없다.
+ *  ③ **현재 값이 없으면 자리를 말하지 않는다.** 결측을 0 으로 읽으면 시간 지표는 "낮을수록 좋다" 라서
+ *     **일이 없던 구간이 최고 성적**으로 보고된다(목표 판정에서 이미 겪은 결함이다).
+ *  ④ 왜 말하지 않는지를 `reason` 으로 밝힌다 — 조용히 빈 값을 주면 화면이 "분포 없음" 을 "평범함" 으로
+ *     그린다.
+ */
+
+/** 창 하나 — 폴드의 창과 같은 모양(ms). */
+export interface BaselineWindow {
+  fromMs: number
+  toMs: number
+}
+
+/** 며칠 전 같은 시간대인가, 몇 주 전 같은 요일·시간대인가. */
+export type BaselineStride = 'day' | 'week'
+
+/** 한 번에 볼 수 있는 과거 구간 수 — 창마다 조회가 한 번 더 붙으므로 상한을 둔다. */
+export const MAX_BASELINE_PERIODS = 14
+
+const MS_DAY = 24 * 60 * 60_000
+
+/**
+ * 비교할 과거 창들 — 현재 창을 **같은 길이로** 하루(또는 한 주)씩 뒤로 옮긴다.
+ *
+ * 가까운 것부터 준다(어제 → 그제 → …). 화면이 시간 순서를 다시 정하지 않아도 되게.
+ *
+ * **한계를 밝힌다**: 옮기는 것은 ms 산술이다. 트윈 공간은 고정 오프셋(`utcOffsetMinutes`)을 선언하므로
+ * 현재 모델에서는 "같은 시간대" 가 정확하다. 일광절약시간을 쓰는 시간대를 나중에 지원하면 전환이 있는
+ * 주의 하루가 한 시간 밀린다 — 그때는 오프셋 기준 캘린더 산술로 바꿔야 한다(지금 지어내지 않는다).
+ */
+export function baselineWindows(
+  fromMs: number,
+  toMs: number,
+  periods: number,
+  stride: BaselineStride = 'day'
+): BaselineWindow[] {
+  if (!Number.isFinite(fromMs) || !Number.isFinite(toMs) || toMs <= fromMs) return []
+  const count = Math.max(0, Math.min(MAX_BASELINE_PERIODS, Math.floor(periods)))
+  const step = stride === 'week' ? 7 * MS_DAY : MS_DAY
+
+  return Array.from({ length: count }, (_, i) => ({
+    fromMs: fromMs - step * (i + 1),
+    toMs: toMs - step * (i + 1)
+  }))
+}
+
+/** 지표의 성질 — 이름과 값 꺼내기는 호출부(`TWIN_METRIC`)가 소유한다. */
+export interface MetricSpecLike {
+  direction: 'higher' | 'lower'
+  unit: string
+}
+
+/** 과거 창 하나에서 꺼낸 값들 — 그 창에 기록이 없으면 값이 `undefined` 다. */
+export interface BaselineSampleInput<M extends string> {
+  fromMs: number
+  toMs: number
+  values: Partial<Record<M, number | undefined>>
+}
+
+/** 과거 창 하나의 결과 — **결측도 남긴다**(빼면 "지난 7일" 이 거짓이 된다). */
+export interface BaselineSample {
+  fromMs: number
+  toMs: number
+  measured: boolean
+  value?: number
+}
+
+/** 왜 자리를 말하지 않는지. */
+export type BaselineNoPosition = 'no-current' | 'too-few-samples'
+
+/**
+ * 분포 안에서 현재의 자리 — **방향을 적용한 읽기.**
+ *
+ * 임의의 임계가 없다: 표본 전부보다 좋으면 `best`, 전부보다 나쁘면 `worst`, 그 사이는 중앙값을 기준으로
+ * 구분한다. `typical` 은 중앙값과 **같을 때**만이다.
+ */
+export type BaselineStanding = 'best' | 'better-than-typical' | 'typical' | 'worse-than-typical' | 'worst'
+
+export interface MetricBaseline<M extends string = string> {
+  metric: M
+  direction: 'higher' | 'lower'
+  unit: string
+  /** 지금 창의 값 — 없으면 `undefined`(0 이 아니다). */
+  current?: number
+  /** 요청한 과거 창 전부(결측 포함, 가까운 것부터). */
+  samples: BaselineSample[]
+  /** 요청한 창 수 / 그중 실제로 측정된 수 — 둘을 함께 봐야 "지난 7일" 을 믿을 수 있다. */
+  requested: number
+  measuredCount: number
+  /** 측정된 표본만의 요약. 표본이 없으면 전부 `undefined`. */
+  min?: number
+  median?: number
+  max?: number
+  /** 측정 표본을 오름차순으로 놓았을 때 현재 값이 몇 번째인가(1 = 가장 작음) — **방향 없는 사실**. */
+  rank?: number
+  /** 그 순위를 셀 때의 표본 수(+현재 1). 순위만 보면 표본이 둘이었는지 열이었는지 알 수 없다. */
+  rankOf?: number
+  /** 방향을 적용한 읽기. 말할 수 없으면 없다. */
+  standing?: BaselineStanding
+  /** 자리를 말하지 않은 이유. */
+  noPosition?: BaselineNoPosition
+}
+
+/** 중앙값 — 짝수 개면 가운데 둘의 평균(폴드의 분위수 규약과 달리 여기 표본은 아주 작다). */
+function medianOf(sorted: readonly number[]): number | undefined {
+  if (!sorted.length) return undefined
+  const mid = sorted.length >> 1
+  return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2
+}
+
+/**
+ * 지표별로 분포와 자리를 만든다.
+ *
+ * @param specs   지표 성질(방향·단위). 열거된 지표만 낸다 — 모르는 이름을 짐작하지 않는다.
+ * @param current 지금 창에서 꺼낸 값들(결측은 `undefined`).
+ * @param inputs  과거 창들에서 꺼낸 값들(가까운 것부터).
+ */
+export function summarizeBaseline<M extends string>(
+  specs: Readonly<Record<M, MetricSpecLike>>,
+  current: Partial<Record<M, number | undefined>>,
+  inputs: readonly BaselineSampleInput<M>[]
+): MetricBaseline<M>[] {
+  const out: MetricBaseline<M>[] = []
+
+  for (const metric of Object.keys(specs) as M[]) {
+    const spec = specs[metric]
+    const samples: BaselineSample[] = inputs.map(s => {
+      const v = s.values[metric]
+      const measured = typeof v === 'number' && Number.isFinite(v)
+      return measured ? { fromMs: s.fromMs, toMs: s.toMs, measured: true, value: v as number } : { fromMs: s.fromMs, toMs: s.toMs, measured: false }
+    })
+
+    const values = samples.filter(s => s.measured).map(s => s.value as number)
+    const sorted = [...values].sort((a, b) => a - b)
+    const cur = current[metric]
+    const hasCurrent = typeof cur === 'number' && Number.isFinite(cur)
+
+    const row: MetricBaseline<M> = {
+      metric,
+      direction: spec.direction,
+      unit: spec.unit,
+      ...(hasCurrent ? { current: cur as number } : {}),
+      samples,
+      requested: inputs.length,
+      measuredCount: values.length,
+      ...(sorted.length ? { min: sorted[0], median: medianOf(sorted), max: sorted[sorted.length - 1] } : {})
+    }
+
+    /* 자리를 말할 수 없는 두 경우 — 이유를 밝힌다(조용한 빈 값이 "평범함" 으로 읽힌다). */
+    if (!hasCurrent) row.noPosition = 'no-current'
+    else if (sorted.length < 2) row.noPosition = 'too-few-samples'
+    else {
+      const value = cur as number
+      const median = medianOf(sorted) as number
+      /* 오름차순에서 몇 번째인가 — 같은 값은 뒤에 놓는다(동률이면 "더 큰 쪽" 으로 세지 않는다). */
+      row.rank = sorted.filter(v => v < value).length + 1
+      row.rankOf = sorted.length + 1
+
+      const higherIsBetter = spec.direction === 'higher'
+      const beatsAll = higherIsBetter ? value > sorted[sorted.length - 1] : value < sorted[0]
+      const losesToAll = higherIsBetter ? value < sorted[0] : value > sorted[sorted.length - 1]
+      /* 중앙값보다 큰 것이 "좋은" 쪽인가 — 방향을 여기 한 번만 적용한다. */
+      const aboveMedianIsBetter = higherIsBetter === value > median
+
+      row.standing = beatsAll
+        ? 'best'
+        : losesToAll
+          ? 'worst'
+          : value === median
+            ? 'typical'
+            : aboveMedianIsBetter
+              ? 'better-than-typical'
+              : 'worse-than-typical'
+    }
+
+    out.push(row)
+  }
+
+  return out
+}