@operato/twin-kernel 0.7.0 → 0.7.1

package/dist/contract.d.ts

@@ -1169,6 +1169,60 @@ export interface Attention {
         args?: unknown;
     };
 }
+/** 계량 지점의 마지막 관측 — 값이 없으면 **모르는 것이다**(0 이 아니다). */
+export interface MeterPointState {
+    id: string;
+    kW?: number;
+    /** 누적 전력량(원천이 준 적산값) — 우리가 적분한 값이 아니다. */
+    kWh?: number;
+    powerFactor?: number;
+    /** 마지막 표본의 시각 — 계측이 끊긴 것을 소비처가 알 수 있게. */
+    atMs?: number;
+    /** 이 구간에 받은 표본 수 — 「못 쟀다」와 「0이었다」를 구별한다. */
+    samplesInWindow: number;
+}
+export interface DemandWindowState {
+    startMs: number;
+    endMs: number;
+    /** 그 구간의 최대 순간부하 — 표본이 없으면 `undefined`(0 이 아니다). */
+    maxKW?: number;
+    /** 표본 평균 부하 — 요금 산정의 평균 수요에 대응한다. */
+    meanKW?: number;
+    /** **kW 를 실은** 표본 수 — 부하 판정의 근거 수다(받은 표본 전체가 아니다). */
+    samples: number;
+    /** 계약전력 대비 — 계약을 모르면 `undefined`(짐작하지 않는다). */
+    contractKW?: number;
+    overContract?: boolean;
+}
+export interface EnergyState {
+    points: MeterPointState[];
+    /** 지금 열려 있는 구간 — 아직 마감되지 않았다(예측은 `projectedKW`). */
+    open?: DemandWindowState & {
+        projectedKW?: number;
+        projectionBasis?: 'mean-so-far';
+    };
+    /**
+     * 마감된 구간들 — **최근 것만 들고 있다**(상태 크기가 시간에 비례하지 않게).
+     * 자른 사실을 `closedTotal` 로 함께 낸다 — 조용히 자르지 않는다.
+     */
+    closed: DemandWindowState[];
+    closedTotal: number;
+    /** 관측 시작 이후 최대 수요 — 월 경계는 여기서 정하지 않는다(위 주석). */
+    peakSince?: {
+        kW: number;
+        windowStartMs: number;
+    };
+    /** 현장이 선언한 계약전력(자리 속성) — 없으면 계약 대비 판정을 하지 않는다. */
+    contractKW?: number;
+    /**
+     * 이 커널이 받은 **물류 흐름 요청** — 에너지에는 없는 것들이다(도착·오더·배정·작업 완료).
+     * 비어 있지 않으면 배선 오류다: EMS 트윈에 물류 명령이 오고 있다. 조용히 넘기지 않는다.
+     */
+    flowRequests?: {
+        hook: string;
+        count: number;
+    }[];
+}
 /**
  * 조치방향 — code=안정 조치 키(언어 중립). command 있으면 원클릭 실행, 없으면 권고.
  * 라벨·힌트(사람 언어)는 표현계층이 code 로 렌더(커널은 문장 미보유). command 보유 조치는 code=command 문자열,
@@ -1217,6 +1271,13 @@ export interface StateSnapshot {
      * 왕복시켜야 재기동·재계산에서 확인 상태가 유지된다.
      */
     acked?: string[];
+    /**
+     * 에너지 — **에너지 트윈만 채운다**(계량 지점·수요 구간·피크). 다른 종류에서는 없다.
+     *
+     * 없는 것과 빈 것을 구별한다: 필드가 아예 없으면 그 트윈은 에너지를 재지 않는 것이고,
+     * `points: []` 는 「아직 표본이 없다」다.
+     */
+    energy?: EnergyState;
 }
 export interface Command<T = unknown> {
     commandId: string;

package/dist/domain-catalog.d.ts

@@ -87,8 +87,12 @@ export interface TwinAxisInfo {
      * board 안에서의 자리. 최상위면 `axis` 와 같고, 중첩이면 경로다
      * (`productionSpec.definition.recipes`).
      *
-     * **`source: 'document'` 일 때만 있다.** 상태·저널 축에는 board 안의 자리가 없다 — 빈 문자열로
-     * 두면 소비처가 board 루트를 읽고 통째로 잘못된 답을 만든다.
+     * **`source` 가 가리키는 자료 안의 경로다** — 예전에는 「`document` 일 때만 있다」고 못 박았는데,
+     * 상태 축도 중첩될 수 있다는 것이 에너지에서 드러났다(수요 구간은 `state.energy.closed` 에 산다).
+     * 그때 축 이름을 상태의 최상위 키로 맞추려면 같은 배열을 두 자리에 실어야 했다(방송이 그만큼 커진다).
+     *
+     * 규칙은 하나다: **경로가 있으면 그 경로로 읽고, 없으면 축 이름으로 읽는다.** 빈 문자열로 두지
+     * 않는다 — 소비처가 자료의 뿌리를 읽고 통째로 잘못된 답을 만든다.
      *
      * **레시피·라우트는 저장상 `productionSpec` 안에 있지만 개념으로는 1급**이다 — 사람은
      * "레시피" 를 찾지 "생산 정의 안의 레시피" 를 찾지 않는다. 저장 위치가 개념을 가두면

package/dist/domain-catalog.js

@@ -96,7 +96,27 @@ export const TWIN_AXES = [
     { axis: 'orders', label: 'twin.axis.orders', kind: 'instance', source: 'state', historical: true,
         standardClass: { isa95: 'OperationsRequest', epcis: 'TransactionEvent' }, systems: LOGISTICS },
     { axis: 'tasks', label: 'twin.axis.tasks', kind: 'instance', source: 'state', historical: true,
-        standardClass: { isa95: 'SegmentResponse', epcis: 'TransformationEvent' }, systems: LOGISTICS }
+        standardClass: { isa95: 'SegmentResponse', epcis: 'TransformationEvent' }, systems: LOGISTICS },
+    /*
+     * ── 에너지가 더하는 개념은 **하나**다 (2026-08-14, §10 6.5단계) ──────────────
+     *
+     * 에너지 트윈의 개체 대부분은 **이미 있는 축**이 답한다: 전기 구간은 `locations`, 계량기·차단기·
+     * 태양광·축전지·감축 부하는 `equipment` 다(카탈로그가 그 타입들을 그 역할로 선언한다). 그것들을
+     * 새 축으로 다시 세우면 같은 것이 두 곳에서 세어진다 — 개념 지도가 계량기를 두 번 보여 준다.
+     *
+     * 정말로 새로운 것은 **수요 구간**이다: 자원이 아니고, 선언이 아니고, 15분마다 닫히는 **사실**이다.
+     * 그것이 요금의 알갱이이고 피크의 근거다(피크는 마감된 구간의 최대이므로 파생이다 — 축이 아니다).
+     *
+     * ── 표준 칸을 비운다 ──────────────────────────────────────────────────────
+     * 15분 수요 구간은 **요금 제도의 알갱이**다(계약·TOU). ISO 50001 은 경영 체계를, IEC 61850 은 설비
+     * 데이터 모델을 말하고, 둘 다 이 구간을 정의하지 않는다. 가까운 이름을 적으면 적합성 표가 거짓을
+     * 말하므로 비워 둔다 — 「표준에 자리가 없으면 빈 객체」라는 이 선언의 규율 그대로다.
+     *
+     * 아직 세우지 않은 것: **요금 구간**(TariffPeriod)과 **원단위**(EnPI). 둘 다 아직 아무도 만들지
+     * 않는다 — 선언만 하면 개념 지도가 언제나 0 을 보여 주고, 그것은 결손처럼 읽힌다(§10 7단계의 일).
+     */
+    { axis: 'demandWindows', path: 'energy.closed', label: 'twin.axis.demandWindows', kind: 'instance',
+        source: 'state', historical: true, standardClass: {}, systems: ['ems'] }
 ];
 /** 관계 전체 — 지도의 선과 항목의 이웃이 여기서 나온다(화면은 이 목록을 갖지 않는다). */
 export const TWIN_RELATIONS = [

package/dist/ems-kernel.d.ts

@@ -1,64 +1,10 @@
 import { FlowEngine } from './flow-engine.ts';
 import { type AllocationPolicy } from './allocation-policy.ts';
-import { type CanonicalEnvelope, type StateSnapshot } from './contract.ts';
+import { type CanonicalEnvelope, type DemandWindowState, type StateSnapshot } from './contract.ts';
 /** 수요 구간 — 요금의 알갱이다. 15분은 한국·다수 요금제의 최대수요 산정 단위다. */
 export declare const DEMAND_WINDOW_MS: number;
 /** 그 시각이 속한 구간의 시작 — 벽시계 경계(00·15·30·45분)에 맞춘다. */
 export declare const demandWindowStart: (atMs: number, windowMs?: number) => number;
-/** 계량 지점의 마지막 관측 — 값이 없으면 **모르는 것이다**(0 이 아니다). */
-export interface MeterPointState {
-    id: string;
-    kW?: number;
-    /** 누적 전력량(원천이 준 적산값) — 우리가 적분한 값이 아니다. */
-    kWh?: number;
-    powerFactor?: number;
-    /** 마지막 표본의 시각 — 계측이 끊긴 것을 소비처가 알 수 있게. */
-    atMs?: number;
-    /** 이 구간에 받은 표본 수 — 「못 쟀다」와 「0이었다」를 구별한다. */
-    samplesInWindow: number;
-}
-export interface DemandWindowState {
-    startMs: number;
-    endMs: number;
-    /** 그 구간의 최대 순간부하 — 표본이 없으면 `undefined`(0 이 아니다). */
-    maxKW?: number;
-    /** 표본 평균 부하 — 요금 산정의 평균 수요에 대응한다. */
-    meanKW?: number;
-    /** **kW 를 실은** 표본 수 — 부하 판정의 근거 수다(받은 표본 전체가 아니다). */
-    samples: number;
-    /** 계약전력 대비 — 계약을 모르면 `undefined`(짐작하지 않는다). */
-    contractKW?: number;
-    overContract?: boolean;
-}
-export interface EnergyState {
-    points: MeterPointState[];
-    /** 지금 열려 있는 구간 — 아직 마감되지 않았다(예측은 `projectedKW`). */
-    open?: DemandWindowState & {
-        projectedKW?: number;
-        projectionBasis?: 'mean-so-far';
-    };
-    /**
-     * 마감된 구간들 — **최근 것만 들고 있다**(상태 크기가 시간에 비례하지 않게).
-     * 자른 사실을 `closedTotal` 로 함께 낸다 — 조용히 자르지 않는다.
-     */
-    closed: DemandWindowState[];
-    closedTotal: number;
-    /** 관측 시작 이후 최대 수요 — 월 경계는 여기서 정하지 않는다(위 주석). */
-    peakSince?: {
-        kW: number;
-        windowStartMs: number;
-    };
-    /** 현장이 선언한 계약전력(자리 속성) — 없으면 계약 대비 판정을 하지 않는다. */
-    contractKW?: number;
-    /**
-     * 이 커널이 받은 **물류 흐름 요청** — 에너지에는 없는 것들이다(도착·오더·배정·작업 완료).
-     * 비어 있지 않으면 배선 오류다: EMS 트윈에 물류 명령이 오고 있다. 조용히 넘기지 않는다.
-     */
-    flowRequests?: {
-        hook: string;
-        count: number;
-    }[];
-}
 export declare class EmsKernel extends FlowEngine {
     private points;
     private open?;
@@ -68,7 +14,23 @@ export declare class EmsKernel extends FlowEngine {
     /** 이 구간에서 이미 제안을 냈나 — 같은 사실을 되풀어 방송하지 않는다(라이브 브리지의 교훈). */
     private suggestedFor?;
     private windowMs;
-    constructor(tenantId: string, policy?: AllocationPolicy, windowMs?: number);
+    /**
+     * ── 세 번째 인자는 **호스트가 정한 자리**다 (2026-08-14 실측으로 고침) ──────
+     *
+     * 호스트는 모든 커널을 한 모양으로 세운다: `new Kernel(tenantId, undefined, productionSpecOf(model))`.
+     * 즉 세 번째 인자는 **도메인 옵션 슬롯**이고 커널마다 뜻이 다르다(야드는 모드, 생산은 명세).
+     *
+     * 처음에 이 자리를 `windowMs: number` 로 받았다가, 라이브에서 **모든 수요 구간이 깨졌다** —
+     * 생산 명세 객체가 창 길이로 들어와 `startMs: null`·`endMs: NaN` 이 됐다. 내 시험은 커널을
+     * `new EmsKernel('t')` 로 직접 세웠기 때문에 그것을 잡지 못했다(호스트와 다른 방식으로 세운 것이
+     * 그 자체로 결함이었다).
+     *
+     * 그래서 **쓸 수 있는 것만 읽는다**: 수면 창 길이로 쓰고, 객체면 `windowMs` 를 찾고, 없으면 기본값
+     * (15분)이다. 모르는 것을 창 길이로 삼지 않는다.
+     */
+    constructor(tenantId: string, policy?: AllocationPolicy, opts?: number | {
+        windowMs?: number;
+    } | unknown);
     /**
      * 계약전력 — **현장이 선언한 자리 속성**에서 읽는다(`EMS_PROPERTY.contractKW`).
      *

package/dist/ems-kernel.js

@@ -33,6 +33,15 @@ import { EMS_PROPERTY } from "./ems-profile.js";
 export const DEMAND_WINDOW_MS = 15 * 60 * 1000;
 /** 그 시각이 속한 구간의 시작 — 벽시계 경계(00·15·30·45분)에 맞춘다. */
 export const demandWindowStart = (atMs, windowMs = DEMAND_WINDOW_MS) => Math.floor(atMs / windowMs) * windowMs;
+/**
+ * 세 번째 생성 인자에서 **쓸 수 있는 창 길이만** 뽑는다 — 나머지는 무시하고 기본값을 쓴다.
+ * 0·음수·객체·문자열을 창 길이로 삼으면 구간 경계가 `NaN` 이 되고 그 트윈의 모든 마감이 거짓이 된다.
+ */
+function windowMsOf(opts) {
+    const raw = typeof opts === 'number' ? opts : opts?.windowMs;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : DEMAND_WINDOW_MS;
+}
 /** 상태에 남기는 마감 구간 수 — 하루치(15분 × 96). 그 앞은 저널이 답한다. */
 const KEEP_CLOSED = 96;
 export class EmsKernel extends FlowEngine {
@@ -44,9 +53,23 @@ export class EmsKernel extends FlowEngine {
     /** 이 구간에서 이미 제안을 냈나 — 같은 사실을 되풀어 방송하지 않는다(라이브 브리지의 교훈). */
     suggestedFor;
     windowMs;
-    constructor(tenantId, policy = firstFitPolicy, windowMs = DEMAND_WINDOW_MS) {
+    /**
+     * ── 세 번째 인자는 **호스트가 정한 자리**다 (2026-08-14 실측으로 고침) ──────
+     *
+     * 호스트는 모든 커널을 한 모양으로 세운다: `new Kernel(tenantId, undefined, productionSpecOf(model))`.
+     * 즉 세 번째 인자는 **도메인 옵션 슬롯**이고 커널마다 뜻이 다르다(야드는 모드, 생산은 명세).
+     *
+     * 처음에 이 자리를 `windowMs: number` 로 받았다가, 라이브에서 **모든 수요 구간이 깨졌다** —
+     * 생산 명세 객체가 창 길이로 들어와 `startMs: null`·`endMs: NaN` 이 됐다. 내 시험은 커널을
+     * `new EmsKernel('t')` 로 직접 세웠기 때문에 그것을 잡지 못했다(호스트와 다른 방식으로 세운 것이
+     * 그 자체로 결함이었다).
+     *
+     * 그래서 **쓸 수 있는 것만 읽는다**: 수면 창 길이로 쓰고, 객체면 `windowMs` 를 찾고, 없으면 기본값
+     * (15분)이다. 모르는 것을 창 길이로 삼지 않는다.
+     */
+    constructor(tenantId, policy = firstFitPolicy, opts) {
         super(tenantId, policy);
-        this.windowMs = windowMs;
+        this.windowMs = windowMsOf(opts);
     }
     /**
      * 계약전력 — **현장이 선언한 자리 속성**에서 읽는다(`EMS_PROPERTY.contractKW`).

package/dist/ems-profile.d.ts

@@ -2,7 +2,7 @@ import type { TwinTypeInfo } from './domain-catalog.ts';
 /** 로케이션(수동) 타입 키 — 배전 계통의 구간. */
 export declare const EMS_LOCATION_TYPES: readonly ["incoming", "feeder", "submeter-zone"];
 /** 설비(능동) 타입 키 — 계량 지점과 에너지 자원. */
-export declare const EMS_EQUIPMENT_TYPES: readonly ["meter", "breaker", "pv-array", "battery", "curtailable-load"];
+export declare const EMS_EQUIPMENT_TYPES: readonly ["meter", "breaker", "pv-array", "battery", "utility", "curtailable-load"];
 /**
  * 커널이 **읽는** 자리 속성 — 뜻을 코드 한가운데 숨기지 않는다.
  *

package/dist/ems-profile.js

@@ -1,7 +1,7 @@
 /** 로케이션(수동) 타입 키 — 배전 계통의 구간. */
 export const EMS_LOCATION_TYPES = ['incoming', 'feeder', 'submeter-zone'];
 /** 설비(능동) 타입 키 — 계량 지점과 에너지 자원. */
-export const EMS_EQUIPMENT_TYPES = ['meter', 'breaker', 'pv-array', 'battery', 'curtailable-load'];
+export const EMS_EQUIPMENT_TYPES = ['meter', 'breaker', 'pv-array', 'battery', 'utility', 'curtailable-load'];
 /**
  * 커널이 **읽는** 자리 속성 — 뜻을 코드 한가운데 숨기지 않는다.
  *
@@ -93,6 +93,28 @@ export const EMS_TYPES = [
         identity: { scheme: 'kernel:id' },
         capabilities: ['storing', 'metered', 'operable']
     },
+    {
+        key: 'utility',
+        role: 'equipment',
+        label: 'twin.type.utility',
+        /*
+         * 공통 설비 — 공조·컴프레서·칠러·조명·폐수처리처럼 **어느 공정에도 귀속되지 않는** 소비처.
+         *
+         * ── 왜 따로 있나 (2026-08-14) ────────────────────────────────────────────
+         * 물류·생산 트윈에서 이런 것들은 **설비가 아니다**(공정에 매핑되지 않으므로 자원 축에 없다).
+         * 그런데 에너지에서는 소비의 절반을 차지하고 감축 후보 1순위다 — 담을 자리가 반드시 있어야 한다.
+         *
+         * 처음에는 `curtailable-load` 하나로 받으려 했다. 그런데 그 이름은 **「줄일 수 있다」고 주장**한다:
+         * 폐수처리·방폭 환기·서버실 냉방은 공통이지만 줄일 수 없고, 그것을 감축 가능으로 두면 트윈이
+         * 「이걸 줄이면 됩니다」라는 거짓 제안을 한다. 공통성과 감축 가능성은 **다른 축**이다.
+         *
+         * 표준: IEC 61850 에 「공통 설비」라는 논리 노드는 없다(설비 종류마다 다른 노드다) — 비운다.
+         * ISO 50001 의 SEU 는 이 부류를 가장 많이 가리킨다(유의 에너지 사용처).
+         */
+        standardClass: { iso50001: 'SEU', iso55000: 'Asset' },
+        identity: { scheme: 'kernel:id' },
+        capabilities: ['metered', 'operable']
+    },
     {
         key: 'curtailable-load',
         role: 'equipment',

package/dist/energy-attribution.d.ts

@@ -0,0 +1,208 @@
+/** 몫의 근거 — 값과 **반드시 함께** 다닌다. */
+export type AttributionBasis = 'measured' | 'apportioned' | 'unattributed';
+/** 무엇으로 나눴나 — 배분일 때만 뜻이 있다. */
+export type WeightKind = 'runtimeMs' | 'output' | 'ratedKW' | 'equal';
+export interface EnergyConsumer {
+    /** 소비처 — 설비·오더·구역 무엇이든 id 하나로 가리킨다. */
+    id: string;
+    /** 이 소비처를 **전용으로** 재는 계량기. 있으면 그 풀은 통째로 이 소비처의 것이다. */
+    meterId?: string;
+    /**
+     * 나눌 때의 몫 — 뜻은 `weightKind` 가 정한다(가동시간 ms · 산출 수량 · 정격 kW).
+     * 없거나 0 이면 **그 소비처는 배분에서 빠진다**(0 으로 세지 않는다 — 몫을 모르는 것이다).
+     */
+    weight?: number;
+}
+/** 한 계량기가 잰 구간 에너지와, 그것이 덮는 소비처들. */
+export interface EnergyPool {
+    meterId: string;
+    /** 그 구간에 잰 전력량. */
+    kWh: number;
+    /** 이 계량기가 덮는 소비처 id 들 — 현장이 선언한다(우리가 추론하지 않는다). */
+    consumerIds: string[];
+    /**
+     * **공통(간접) 소비인가** — 공조·컴프레서·칠러·조명·폐수처리처럼 어느 공정·오더에도 직접
+     * 귀속되지 않는 부하(카탈로그의 `utility` 타입).
+     *
+     * ── 왜 표시가 필요한가 (2026-08-14) ──────────────────────────────────────
+     * 이것을 「미귀속」과 같은 칸에 담으면 **정상 상태가 결함처럼** 보인다. 공통 설비의 전기는 직접
+     * 귀속되지 않는 것이 옳고, 사람이 채워야 할 결손(몫이 없다·덮는 대상이 없다)과는 다른 사실이다.
+     *
+     * 공정에 배부하고 싶으면 **명시적으로 요청한다**(`overheadAllocation`) — 원가회계의 간접비 배부와
+     * 같은 규율이고, 그 결과는 배분(`apportioned`)이며 `overhead: true` 로 표시된다.
+     */
+    overhead?: boolean;
+}
+export interface EnergyShare {
+    consumerId: string;
+    kWh: number;
+    basis: Exclude<AttributionBasis, 'unattributed'>;
+    /** 어느 계량기에서 왔나 — 되짚을 수 있어야 한다. */
+    poolMeterId: string;
+    /** 배분일 때만: 무엇으로 나눴나. */
+    weightKind?: WeightKind;
+    /** 배분일 때만: 그 소비처의 몫이 전체의 얼마였나(근거의 투명성). */
+    weightShare?: number;
+    /**
+     * 이 몫이 **공통 설비에서 배부된 것**인가 — 직접 소비와 같은 무게로 읽히지 않게.
+     * 「제품 1대당 kWh」를 직접분·공통분으로 갈라 말할 수 있는 근거다.
+     */
+    overhead?: boolean;
+}
+export interface Unattributed {
+    poolMeterId: string;
+    kWh: number;
+    /**
+     * 왜 나누지 못했나 — **언어중립 코드**(화면이 옮긴다).
+     *  · `no-consumers` — 이 계량기가 무엇을 덮는지 선언되지 않았다
+     *  · `no-weights`   — 소비처는 있는데 나눌 몫이 없다(가동시간·산출량 어느 것도)
+     */
+    reason: 'no-consumers' | 'no-weights';
+    /** 몫을 못 정한 소비처들 — 사람이 무엇을 채워야 할지 알 수 있게. */
+    consumerIds?: string[];
+}
+export interface AttributionResult {
+    shares: EnergyShare[];
+    unattributed: Unattributed[];
+    /**
+     * 배분에서 **빠진** 소비처들 — 조용히 빼지 않는다.
+     *
+     * 몫이 0 이면(그 구간에 돌지 않았다) 그 소비처에 `0 kWh` 를 주지 않는다: 그것은 「우리가 재어 보니
+     * 0 이었다」는 **지어낸 사실**이고, 대기전력이 있는 설비에서는 곧 거짓이다. 대신 빠졌다는 사실을 낸다 —
+     * 그러면 사람이 「이 설비는 정말 안 돌았나」를 확인할 수 있다.
+     */
+    excluded: {
+        consumerId: string;
+        poolMeterId: string;
+        reason: 'zero-weight';
+    }[];
+    /**
+     * **공통(간접) 에너지** — 배부하지 않았다. 결손이 아니라 **정상**이다(위 `EnergyPool.overhead`).
+     * 배부를 요청하면 이 바구니가 비고 그만큼 `shares` 로 간다(그때는 `overhead: true` 가 붙는다).
+     */
+    overhead: {
+        poolMeterId: string;
+        kWh: number;
+    }[];
+    totals: {
+        measuredKWh: number;
+        attributedKWh: number;
+        unattributedKWh: number;
+        /** 공통으로 남은 양 — 원단위를 직접분·공통분으로 갈라 말할 수 있게. */
+        overheadKWh: number;
+    };
+}
+/**
+ * 구간 에너지를 소비처에 귀속시킨다 — **나눌 수 없으면 나누지 않는다.**
+ *
+ * @param weightKind 배분에 쓸 몫의 뜻. **`equal` 은 호출자가 명시적으로 고를 때만** 쓰인다(위 주석).
+ */
+export declare function attributeEnergy(opts: {
+    pools: readonly EnergyPool[];
+    consumers: readonly EnergyConsumer[];
+    weightKind?: WeightKind;
+    /**
+     * 공통(간접) 에너지를 **배부할 것인가** — 기본은 배부하지 않는다.
+     *
+     * 배부는 원가회계의 간접비 배부와 같다: 숫자는 나오지만 그것은 **측정이 아니다.** 기본값으로 두면
+     * 아무도 그것이 배부인 줄 모르므로, 호출자가 몫의 종류를 말할 때만 한다.
+     * 대상은 공통 풀이 덮는 소비처가 아니라 **`processConsumerIds` 로 지목한 공정 소비처들**이다
+     * (공통 계량기는 공정을 덮지 않는다 — 그것이 공통인 이유다).
+     */
+    overheadAllocation?: {
+        weightKind: WeightKind;
+        processConsumerIds: readonly string[];
+    };
+}): AttributionResult;
+/** 분모의 종류 — 무엇당 에너지인가. 단위가 뜻을 정한다. */
+export type IntensityDenominator = 'output' | 'runtimeHours' | 'area';
+export interface IntensityInput {
+    /** 분자 — 그 구간의 전력량. 모르면 `undefined`(0 이 아니다). */
+    kWh?: number;
+    /** 분자가 덮는 구간. */
+    energyWindow?: {
+        startMs: number;
+        endMs: number;
+    };
+    denominator: {
+        kind: IntensityDenominator;
+        /** 값 — 모르면 `undefined`. */
+        value?: number;
+        /** 분모가 덮는 구간 — 분자와 같아야 한다(아래 판정). */
+        window?: {
+            startMs: number;
+            endMs: number;
+        };
+    };
+}
+export type IntensityResult = {
+    value: number;
+    unit: string;
+    kWh: number;
+    denominator: number;
+    window: {
+        startMs: number;
+        endMs: number;
+    };
+} | {
+    value: null;
+    /**
+     * 왜 답하지 못했나 — **언어중립 코드**.
+     *  · `no-energy`        — 분자를 모른다
+     *  · `no-denominator`   — 분모를 모른다(생산량을 못 읽었다)
+     *  · `zero-denominator` — 분모가 0 이다(그 구간에 아무것도 만들지 않았다 → 원단위가 정의되지 않는다)
+     *  · `window-mismatch`  — 분자와 분모가 **다른 구간**의 사실이다
+     */
+    reason: 'no-energy' | 'no-denominator' | 'zero-denominator' | 'window-mismatch';
+};
+/**
+ * 원단위 — **답할 수 없으면 답하지 않는다.**
+ *
+ * ── 왜 구간을 맞대어 보나 ───────────────────────────────────────────────────
+ * 분자는 에너지 트윈이, 분모는 생산 트윈이 낸다. 두 트윈은 각자의 시계로 돌고, 라이브와 히스토리가
+ * 섞이기도 한다. 다른 구간의 두 사실을 나누면 숫자는 나오지만 **아무것도 뜻하지 않는다** — 야간의
+ * 전력을 주간의 산출로 나눈 값이 그렇다. 그래서 구간이 어긋나면 거절한다(호출자가 맞춰서 다시 묻는다).
+ *
+ * ── 왜 0 을 무한으로 만들지 않나 ────────────────────────────────────────────
+ * 그 구간에 아무것도 만들지 않았다면 「대당 에너지」는 **정의되지 않는다.** `Infinity` 를 내면 화면이
+ * 그것을 큰 수로 그리고, 사용자는 최악의 원단위를 본 것으로 읽는다.
+ */
+export declare function energyIntensity(input: IntensityInput): IntensityResult;
+export interface WindowedEnergy {
+    /** 그 범위의 전력량 — 셀 수 있는 구간이 하나도 없으면 `undefined`(0 이 아니다). */
+    kWh?: number;
+    /**
+     * 어떻게 얻었나 — **파생임을 숨기지 않는다.**
+     *  · `mean-kw` — 구간 평균부하 × 구간 길이. 표본의 평균이므로 **추정**이다.
+     *
+     * 계기 적산값(`kWh`)의 차분이 더 정확하지만, 그러려면 구간마다 적산 스냅샷을 남겨야 한다
+     * (아직 하지 않는다 — 남기게 되면 근거가 `meter-delta` 로 바뀐다).
+     */
+    basis: 'mean-kw';
+    /** 센 구간 수. */
+    counted: number;
+    /**
+     * 못 센 구간 수 — 표본이 없어 평균부하를 모르는 구간이다. **조용히 빼지 않는다**:
+     * 이 수가 크면 위 `kWh` 는 그 범위의 전부가 아니라 **일부의 합**이다.
+     */
+    skipped: number;
+    /** 실제로 센 범위 — 요청 범위와 다를 수 있다(구간 경계에 맞춘다). */
+    window?: {
+        startMs: number;
+        endMs: number;
+    };
+}
+/**
+ * 마감된 수요 구간들에서 그 범위의 전력량을 만든다 — **파생의 근거를 함께.**
+ *
+ * 범위에 **걸친** 구간은 세지 않는다(부분을 비례로 자르면 그 비례가 또 하나의 추정이 된다).
+ * 온전히 들어오는 구간만 센다 — 그래서 실제로 센 범위를 함께 낸다.
+ */
+export declare function energyOfWindows(windows: readonly {
+    startMs: number;
+    endMs: number;
+    meanKW?: number;
+}[], range?: {
+    startMs: number;
+    endMs: number;
+}): WindowedEnergy;

package/dist/energy-attribution.js

@@ -0,0 +1,229 @@
+/*
+ * 에너지 귀속 — **이 kWh 는 누구의 것인가.** 설계: `design/profiles/ems.md` §8·§10(7단계)
+ *
+ * ── 왜 규칙이 따로 필요한가 ─────────────────────────────────────────────────
+ * 에너지의 값은 대개 「이 라인이 얼마 썼나」·「이 오더 한 대에 몇 kWh 들었나」로 쓰인다. 그런데 현장의
+ * **계량 알갱이는 대개 소비처보다 굵다** — 구역 계량기 하나가 공조·조명·컨베이어를 함께 잰다
+ * (ISO 50001 의 SEU 가 그 알갱이다). 그래서 개체별 kWh 는 **측정이 아니라 배분**인 경우가 많다.
+ *
+ * 그 사실을 값에 실어 보내지 않으면, 배분한 숫자가 측정한 숫자와 같은 무게로 읽힌다 — 그것이 CBAM·
+ * ESG 보고에서 첫 질문에 깨지는 지점이다. 그래서 이 모듈이 내는 모든 몫은 **근거(basis)를 함께** 갖는다.
+ *
+ * ── 세 가지 근거 ────────────────────────────────────────────────────────────
+ *  · `measured`     — 그 소비처에 **전용 계량기**가 있다(1:1). 가장 강하다.
+ *  · `apportioned`  — 알갱이가 굵어 **나눈 것**이다. 무엇으로 나눴는지(`weightKind`)를 함께 낸다.
+ *  · `unattributed` — 나눌 근거가 없다. **그대로 남긴다.**
+ *
+ * ── 균등 분배를 기본값으로 두지 않는다 ──────────────────────────────────────
+ * 몫이 없을 때 인원수로 나누듯 균등하게 나누면 숫자는 나오지만 그것은 **짐작**이다. 기본값이 되면
+ * 아무도 그것이 짐작인 줄 모른다. 그래서 균등(`equal`)은 **호출자가 명시적으로 고를 때만** 쓴다.
+ *
+ * ── 합은 보존된다 ───────────────────────────────────────────────────────────
+ * 배분한 합 + 미귀속 합 = 측정한 합. 이 불변식이 깨지면 어딘가에서 전기가 사라지거나 생겨난 것이고,
+ * 그 위의 모든 원단위가 거짓이 된다. 시험이 그것을 지킨다.
+ */
+/** 부동소수 비교 — kWh 는 소수점이 있고, 합 보존을 정수로 요구하면 거짓 실패가 난다. */
+const near = (a, b, eps = 1e-9) => Math.abs(a - b) <= eps;
+/**
+ * 구간 에너지를 소비처에 귀속시킨다 — **나눌 수 없으면 나누지 않는다.**
+ *
+ * @param weightKind 배분에 쓸 몫의 뜻. **`equal` 은 호출자가 명시적으로 고를 때만** 쓰인다(위 주석).
+ */
+export function attributeEnergy(opts) {
+    const byId = new Map(opts.consumers.map(c => [c.id, c]));
+    /* 전용 계량기 색인 — 소비처가 「이 계량기는 내 것」이라고 선언한 경우. */
+    const dedicated = new Map();
+    for (const c of opts.consumers)
+        if (c.meterId)
+            dedicated.set(c.meterId, c);
+    const shares = [];
+    const unattributed = [];
+    const excluded = [];
+    const overhead = [];
+    for (const pool of opts.pools) {
+        const kWh = Number(pool.kWh);
+        if (!Number.isFinite(kWh))
+            continue; // 값이 아닌 것은 귀속의 대상이 아니다(0 으로 만들지 않는다)
+        /* ① 전용 계량기 — 통째로 그 소비처의 것이다. 가장 강한 근거이므로 먼저 본다. */
+        const own = dedicated.get(pool.meterId);
+        if (own) {
+            shares.push({ consumerId: own.id, kWh, basis: 'measured', poolMeterId: pool.meterId });
+            continue;
+        }
+        /*
+         * ①-b **공통(간접) 풀** — 직접 귀속되지 않는 것이 정상이다.
+         *
+         * 배부를 요청하지 않았으면 공통 바구니에 그대로 둔다(결손 칸에 담지 않는다 — 정상을 결함으로
+         * 보이게 만들지 않는다). 요청했으면 지목된 공정 소비처들에 나누고 `overhead: true` 를 붙인다.
+         */
+        if (pool.overhead) {
+            const alloc = opts.overheadAllocation;
+            const targets = (alloc?.processConsumerIds ?? []).map(id => byId.get(id)).filter((c) => !!c);
+            const wOf = (c) => alloc?.weightKind === 'equal' ? 1 : Number.isFinite(Number(c.weight)) && Number(c.weight) > 0 ? Number(c.weight) : 0;
+            const sharing = alloc?.weightKind === 'equal' ? targets : targets.filter(c => wOf(c) > 0);
+            const ws = sharing.map(wOf);
+            const total = ws.reduce((a, b) => a + b, 0);
+            if (!alloc || total <= 0) {
+                overhead.push({ poolMeterId: pool.meterId, kWh });
+                continue;
+            }
+            let done = 0;
+            sharing.forEach((c, i) => {
+                const share = ws[i] / total;
+                const amount = i === sharing.length - 1 ? kWh - done : kWh * share;
+                done += amount;
+                shares.push({
+                    consumerId: c.id,
+                    kWh: amount,
+                    basis: 'apportioned',
+                    poolMeterId: pool.meterId,
+                    weightKind: alloc.weightKind,
+                    weightShare: share,
+                    overhead: true
+                });
+            });
+            continue;
+        }
+        /* ② 덮는 소비처가 선언되지 않았다 — 나눌 대상이 없다. */
+        const covered = (pool.consumerIds ?? []).map(id => byId.get(id)).filter((c) => !!c);
+        if (!covered.length) {
+            unattributed.push({ poolMeterId: pool.meterId, kWh, reason: 'no-consumers' });
+            continue;
+        }
+        /* ③ 하나뿐이면 그것도 측정이다 — 그 계량기가 그 소비처만 덮는다는 선언이므로. */
+        if (covered.length === 1) {
+            shares.push({ consumerId: covered[0].id, kWh, basis: 'measured', poolMeterId: pool.meterId });
+            continue;
+        }
+        /* ④ 여럿이면 몫이 필요하다. `equal` 은 호출자가 고른 경우에만 몫을 만든다. */
+        const kind = opts.weightKind;
+        const weightOf = (c) => kind === 'equal' ? 1 : Number.isFinite(Number(c.weight)) && Number(c.weight) > 0 ? Number(c.weight) : 0;
+        /*
+         * 몫이 0 인 소비처는 **배분에서 뺀다**(그리고 뺐다는 사실을 낸다) — 0 을 주면 「재어 보니 0」이라는
+         * 주장이 되고, 대기전력이 있는 설비에서 그것은 거짓이다.
+         */
+        const sharing = kind === 'equal' ? covered : covered.filter(c => weightOf(c) > 0);
+        if (kind && sharing.length < covered.length) {
+            for (const c of covered)
+                if (weightOf(c) <= 0)
+                    excluded.push({ consumerId: c.id, poolMeterId: pool.meterId, reason: 'zero-weight' });
+        }
+        const weights = sharing.map(weightOf);
+        const sum = weights.reduce((a, b) => a + b, 0);
+        if (!kind || sum <= 0) {
+            unattributed.push({
+                poolMeterId: pool.meterId,
+                kWh,
+                reason: 'no-weights',
+                consumerIds: covered.map(c => c.id)
+            });
+            continue;
+        }
+        /*
+         * 비례 배분 — 마지막 소비처가 **나머지를 받는다**(합 보존).
+         *
+         * 각자 반올림하면 합이 원값과 어긋나고, 그 차이는 원단위·보고로 전파된다. 반올림은 표현의 일이고
+         * 여기서는 하지 않는다.
+         */
+        let given = 0;
+        sharing.forEach((c, i) => {
+            const share = weights[i] / sum;
+            const amount = i === sharing.length - 1 ? kWh - given : kWh * share;
+            given += amount;
+            shares.push({
+                consumerId: c.id,
+                kWh: amount,
+                basis: 'apportioned',
+                poolMeterId: pool.meterId,
+                weightKind: kind,
+                weightShare: share
+            });
+        });
+    }
+    const measuredKWh = opts.pools.reduce((a, p) => a + (Number.isFinite(Number(p.kWh)) ? Number(p.kWh) : 0), 0);
+    const attributedKWh = shares.reduce((a, s) => a + s.kWh, 0);
+    const unattributedKWh = unattributed.reduce((a, u) => a + u.kWh, 0);
+    const overheadKWh = overhead.reduce((a, o) => a + o.kWh, 0);
+    /* 합 보존은 이 모듈의 존재 이유다 — 깨지면 그 위의 모든 원단위가 거짓이 된다. */
+    if (!near(attributedKWh + unattributedKWh + overheadKWh, measuredKWh, 1e-6)) {
+        throw new Error(`energy attribution lost or created energy: measured=${measuredKWh} attributed=${attributedKWh} unattributed=${unattributedKWh} overhead=${overheadKWh}`);
+    }
+    return { shares, unattributed, excluded, overhead, totals: { measuredKWh, attributedKWh, unattributedKWh, overheadKWh } };
+}
+const UNIT = {
+    output: 'kWh/unit',
+    runtimeHours: 'kW',
+    area: 'kWh/m2'
+};
+/**
+ * 원단위 — **답할 수 없으면 답하지 않는다.**
+ *
+ * ── 왜 구간을 맞대어 보나 ───────────────────────────────────────────────────
+ * 분자는 에너지 트윈이, 분모는 생산 트윈이 낸다. 두 트윈은 각자의 시계로 돌고, 라이브와 히스토리가
+ * 섞이기도 한다. 다른 구간의 두 사실을 나누면 숫자는 나오지만 **아무것도 뜻하지 않는다** — 야간의
+ * 전력을 주간의 산출로 나눈 값이 그렇다. 그래서 구간이 어긋나면 거절한다(호출자가 맞춰서 다시 묻는다).
+ *
+ * ── 왜 0 을 무한으로 만들지 않나 ────────────────────────────────────────────
+ * 그 구간에 아무것도 만들지 않았다면 「대당 에너지」는 **정의되지 않는다.** `Infinity` 를 내면 화면이
+ * 그것을 큰 수로 그리고, 사용자는 최악의 원단위를 본 것으로 읽는다.
+ */
+export function energyIntensity(input) {
+    const kWh = Number(input.kWh);
+    if (!Number.isFinite(kWh))
+        return { value: null, reason: 'no-energy' };
+    const den = Number(input.denominator?.value);
+    if (!Number.isFinite(den))
+        return { value: null, reason: 'no-denominator' };
+    const ew = input.energyWindow;
+    const dw = input.denominator?.window;
+    /* 두 구간을 다 알 때만 맞대어 본다 — 하나를 모르면 어긋남을 주장할 수 없다(모름은 거절의 근거가 아니다). */
+    if (ew && dw && (ew.startMs !== dw.startMs || ew.endMs !== dw.endMs))
+        return { value: null, reason: 'window-mismatch' };
+    if (den === 0)
+        return { value: null, reason: 'zero-denominator' };
+    const window = ew ?? dw;
+    return {
+        value: kWh / den,
+        unit: UNIT[input.denominator.kind] ?? 'kWh',
+        kWh,
+        denominator: den,
+        ...(window ? { window } : { window: { startMs: 0, endMs: 0 } })
+    };
+}
+/**
+ * 마감된 수요 구간들에서 그 범위의 전력량을 만든다 — **파생의 근거를 함께.**
+ *
+ * 범위에 **걸친** 구간은 세지 않는다(부분을 비례로 자르면 그 비례가 또 하나의 추정이 된다).
+ * 온전히 들어오는 구간만 센다 — 그래서 실제로 센 범위를 함께 낸다.
+ */
+export function energyOfWindows(windows, range) {
+    const inRange = (w) => !range || (w.startMs >= range.startMs && w.endMs <= range.endMs);
+    let kWh = 0;
+    let counted = 0;
+    let skipped = 0;
+    let first;
+    let last;
+    for (const w of windows ?? []) {
+        if (!inRange(w))
+            continue;
+        const mean = Number(w.meanKW);
+        const hours = (Number(w.endMs) - Number(w.startMs)) / 3_600_000;
+        if (!Number.isFinite(mean) || !Number.isFinite(hours) || hours <= 0) {
+            skipped++;
+            continue;
+        }
+        kWh += mean * hours;
+        counted++;
+        if (first === undefined || w.startMs < first)
+            first = w.startMs;
+        if (last === undefined || w.endMs > last)
+            last = w.endMs;
+    }
+    return {
+        ...(counted > 0 ? { kWh } : {}),
+        basis: 'mean-kw',
+        counted,
+        skipped,
+        ...(first !== undefined && last !== undefined ? { window: { startMs: first, endMs: last } } : {})
+    };
+}

package/dist/energy-ingest.d.ts

@@ -0,0 +1,39 @@
+import { type CanonicalEnvelope } from './contract.ts';
+/**
+ * 정규 에너지 표본 — **커넥터가 이 모양으로 맞춰 준다.**
+ *
+ * 필드 이름은 계약이다(`EnergyMeasuredData` 와 같은 이름). 원 시스템의 낱말(`ActivePower`·`P_kW`·
+ * `MMXU.TotW`)을 여기서 받지 않는다 — 그 번역이 커넥터의 일이고, 커널까지 방언이 들어오면
+ * 소비처마다 다른 이름을 알아야 한다.
+ */
+export interface EnergyRecord {
+    meterId: string;
+    /** 유효전력(kW) — 그 계량 주기의 평균. 없으면 「못 읽었다」이고 0 이 아니다. */
+    kW?: number;
+    /** 계기 적산값(kWh) — 차분은 소비처가 한다(계기 교체·리셋을 지어내지 않는다). */
+    kWh?: number;
+    powerFactor?: number;
+    /** 계측 시각(ISO) — **지어낼 수 없는 값**이다. */
+    at?: string;
+}
+export interface EnergyIngestOptions {
+    tenantId: string;
+    /** 레코드에 시각이 없을 때 쓸 값 — **주지 않으면 그 레코드를 거부한다.** */
+    defaultEventTime?: string;
+}
+export interface EnergyIngestResult {
+    accepted: CanonicalEnvelope[];
+    rejected: {
+        record: unknown;
+        errors: string[];
+    }[];
+}
+/** 이 레코드가 에너지 표본인가 — 라우팅 판정을 한 곳에 둔다(소비처가 각자 짐작하지 않게). */
+export declare function isEnergyRecord(record: unknown): boolean;
+/**
+ * 표본 레코드들을 봉투로 — 유효한 것만 통과하고 나머지는 이유와 함께 남는다.
+ *
+ * `eventTime` 은 **계측이 말한 시각**(`at`)이 먼저다. 봉투와 페이로드에 같은 값을 싣는다: 커널은
+ * 페이로드를 먼저 보고, 저널·시간여행은 봉투를 본다 — 둘이 다르면 같은 사실이 두 시각을 갖는다.
+ */
+export declare function ingestEnergyRecords(records: EnergyRecord | EnergyRecord[] | undefined | null, opts: EnergyIngestOptions): EnergyIngestResult;

package/dist/energy-ingest.js

@@ -0,0 +1,91 @@
+/*
+ * 에너지 계측 인제스트 — **표본 레코드 → 봉투.** 설계: `design/profiles/ems.md` §4.1
+ *
+ * ── 왜 따로 있나 (2026-08-14) ───────────────────────────────────────────────
+ * 라이브 인제스트 경로는 **EPCIS 하나만 알았다.** 호스트의 정규 레코드 룰이 모든 레코드를
+ * `type: 'ObjectEvent'` 로 만들었기 때문이다(`canonical-ingest.ts`). 그 길로 계측을 넣으면 둘 중
+ * 하나가 된다: `epc` 가 없어 검증에서 거부되거나, 엉뚱하게 **물품 관측**으로 읽힌다.
+ *
+ * 에너지는 물(物)의 계보가 아니므로 EPCIS 어휘를 쓰지 않는다(§4). 그래서 정규 레코드의 **종류를
+ * 하나 더 인정**한다 — 봉투는 같은 것을 쓰고(저널·리플레이·시간여행을 그대로 얻는다) 어휘만 자기 것이다.
+ *
+ * ── 검증은 커널의 일이다 ────────────────────────────────────────────────────
+ * 매핑(원 시스템 스키마 → 정규 레코드)은 커넥터의 몫이고, **무엇이 유효한 사실인가**는 커널이 정한다
+ * (`face2-adapters.md` §7 의 규율: 매핑=밖, 검증=커널). 그래서 이 판정이 여기 있다.
+ *
+ * ── 무엇을 거부하나 ─────────────────────────────────────────────────────────
+ * 지어낼 수 없는 것이 빠지면 거부한다 — 계량 지점(`meterId`)과 시각(`at`)이다. 지금 시각으로 메우면
+ * 남의 구간에 실리고, 지점을 지어내면 어디의 소비인지 모르는 값이 누적된다. **거부한 것은 이유와 함께
+ * 돌려준다**(조용히 버리지 않는다 — 소비처가 그 수를 세어 사람에게 말할 수 있어야 한다).
+ *
+ * 값(`kW`)이 없는 표본은 **거부하지 않는다**: 계량기가 살아 있다는 사실 자체가 관측이고, 커널이
+ * 「받았지만 부하를 못 읽었다」를 구별해 낸다(`observedAbsence: 'no-load-samples'`).
+ */
+import { ENERGY_EVENT } from "./contract.js";
+/** 이 레코드가 에너지 표본인가 — 라우팅 판정을 한 곳에 둔다(소비처가 각자 짐작하지 않게). */
+export function isEnergyRecord(record) {
+    if (!record || typeof record !== 'object')
+        return false;
+    const r = record;
+    /* 계량 지점이 있고 EPCIS 어휘가 없으면 에너지다. `epc` 가 함께 있으면 둘 중 무엇인지 알 수 없으므로
+       에너지로 받지 않는다 — 그 판단은 커넥터가 명확히 해야 한다. */
+    return typeof r.meterId === 'string' && r.meterId.trim().length > 0 && r.epc === undefined;
+}
+/**
+ * 표본 레코드들을 봉투로 — 유효한 것만 통과하고 나머지는 이유와 함께 남는다.
+ *
+ * `eventTime` 은 **계측이 말한 시각**(`at`)이 먼저다. 봉투와 페이로드에 같은 값을 싣는다: 커널은
+ * 페이로드를 먼저 보고, 저널·시간여행은 봉투를 본다 — 둘이 다르면 같은 사실이 두 시각을 갖는다.
+ */
+export function ingestEnergyRecords(records, opts) {
+    const arr = Array.isArray(records) ? records : records ? [records] : [];
+    const accepted = [];
+    const rejected = [];
+    let seq = 0;
+    for (const record of arr) {
+        const errors = [];
+        const meterId = String(record?.meterId ?? '').trim();
+        if (!meterId)
+            errors.push('meterId 없음 — 어디의 소비인지 모르는 값은 누적할 수 없다');
+        const at = String(record?.at ?? '').trim() || opts.defaultEventTime;
+        const atMs = at ? Date.parse(at) : Number.NaN;
+        if (!Number.isFinite(atMs))
+            errors.push('at 없음/형식 오류 — 지금 시각으로 메우면 남의 수요 구간에 실린다');
+        /* 값이 있으면 수여야 한다 — 문자열·NaN 을 그대로 흘리면 커널이 합에서 조용히 빠뜨린다. */
+        const num = (v, name) => {
+            if (v === undefined || v === null || v === '')
+                return undefined;
+            const n = Number(v);
+            if (!Number.isFinite(n)) {
+                errors.push(`${name} 가 수가 아니다: ${JSON.stringify(v)}`);
+                return undefined;
+            }
+            return n;
+        };
+        const kW = num(record?.kW, 'kW');
+        const kWh = num(record?.kWh, 'kWh');
+        const powerFactor = num(record?.powerFactor, 'powerFactor');
+        if (errors.length) {
+            rejected.push({ record, errors });
+            continue;
+        }
+        const eventTime = new Date(atMs).toISOString();
+        const data = {
+            meterId,
+            /* 계약은 `kW` 를 필수로 두지만 **못 읽은 표본도 사실**이다 — 그 경우 값을 비우고 보낸다.
+               커널이 「받았지만 부하를 못 읽었다」로 세고, 구간 마감에 그 이유를 싣는다. */
+            ...(kW !== undefined ? { kW } : {}),
+            ...(kWh !== undefined ? { kWh } : {}),
+            ...(powerFactor !== undefined ? { powerFactor } : {}),
+            at: eventTime
+        };
+        accepted.push({
+            eventId: `${opts.tenantId}-energy-${++seq}`,
+            eventType: ENERGY_EVENT.measured,
+            eventTime,
+            tenantId: opts.tenantId,
+            data
+        });
+    }
+    return { accepted, rejected };
+}

package/dist/index.d.ts

@@ -29,5 +29,8 @@ export { WmsKernel } from './kernel.ts';
 export { YmsKernel } from './yms-kernel.ts';
 export { MesKernel, MES_PART_GTINS, MES_PRODUCT_GTINS, MES_PRODUCTS } from './mes-kernel.ts';
 export { EmsKernel, DEMAND_WINDOW_MS, demandWindowStart } from './ems-kernel.ts';
-export type { EnergyState, DemandWindowState, MeterPointState } from './ems-kernel.ts';
+export { ingestEnergyRecords, isEnergyRecord } from './energy-ingest.ts';
+export { attributeEnergy, energyIntensity, energyOfWindows } from './energy-attribution.ts';
+export type { AttributionBasis, AttributionResult, EnergyConsumer, EnergyPool, EnergyShare, IntensityInput, IntensityResult, IntensityDenominator, WeightKind, WindowedEnergy } from './energy-attribution.ts';
+export type { EnergyRecord, EnergyIngestOptions, EnergyIngestResult } from './energy-ingest.ts';
 export * from './vocabulary.ts';

package/dist/index.js

@@ -29,4 +29,7 @@ export { WmsKernel } from "./kernel.js";
 export { YmsKernel } from "./yms-kernel.js";
 export { MesKernel, MES_PART_GTINS, MES_PRODUCT_GTINS, MES_PRODUCTS } from "./mes-kernel.js";
 export { EmsKernel, DEMAND_WINDOW_MS, demandWindowStart } from "./ems-kernel.js";
+export { ingestEnergyRecords, isEnergyRecord } from "./energy-ingest.js";
+export { attributeEnergy, energyIntensity, energyOfWindows } from "./energy-attribution.js";
+/* 에너지 상태 타입은 **계약**에 있다(상태의 모양은 계약이다) — contract 의 `export *` 가 이미 낸다. */
 export * from "./vocabulary.js";

package/dist-cjs/index.cjs

@@ -77,6 +77,7 @@ __export(index_exports, {
   activeShiftOf: () => activeShiftOf,
   aggregationEvent: () => aggregationEvent,
   analyzeCapacity: () => analyzeCapacity,
+  attributeEnergy: () => attributeEnergy,
   axesOfSystem: () => axesOfSystem,
   axisAppliesTo: () => axisAppliesTo,
   axisInfo: () => axisInfo,
@@ -94,6 +95,8 @@ __export(index_exports, {
   documentPath: () => documentPath,
   dueStatusOf: () => dueStatusOf,
   effectivityAt: () => effectivityAt,
+  energyIntensity: () => energyIntensity,
+  energyOfWindows: () => energyOfWindows,
   fefoPolicy: () => fefoPolicy,
   firstFitPolicy: () => firstFitPolicy,
   foldJobResponses: () => foldJobResponses,
@@ -104,6 +107,8 @@ __export(index_exports, {
   inWorkCalendar: () => inWorkCalendar,
   inWorkCalendarAt: () => inWorkCalendarAt,
   ingest: () => ingest,
+  ingestEnergyRecords: () => ingestEnergyRecords,
+  isEnergyRecord: () => isEnergyRecord,
   isEquipmentLevel: () => isEquipmentLevel,
   isoDurationHours: () => isoDurationHours,
   itemKeyOf: () => itemKeyOf,
@@ -1598,7 +1603,7 @@ var WMS_TYPES = [
 
 // src/ems-profile.ts
 var EMS_LOCATION_TYPES = ["incoming", "feeder", "submeter-zone"];
-var EMS_EQUIPMENT_TYPES = ["meter", "breaker", "pv-array", "battery", "curtailable-load"];
+var EMS_EQUIPMENT_TYPES = ["meter", "breaker", "pv-array", "battery", "utility", "curtailable-load"];
 var EMS_PROPERTY = {
   /** 계약전력(kW) — 수전·분기 자리에 선언한다. 없으면 계약 대비 판정을 하지 않는다. */
   contractKW: "contract.kW"
@@ -1684,6 +1689,28 @@ var EMS_TYPES = [
     identity: { scheme: "kernel:id" },
     capabilities: ["storing", "metered", "operable"]
   },
+  {
+    key: "utility",
+    role: "equipment",
+    label: "twin.type.utility",
+    /*
+     * 공통 설비 — 공조·컴프레서·칠러·조명·폐수처리처럼 **어느 공정에도 귀속되지 않는** 소비처.
+     *
+     * ── 왜 따로 있나 (2026-08-14) ────────────────────────────────────────────
+     * 물류·생산 트윈에서 이런 것들은 **설비가 아니다**(공정에 매핑되지 않으므로 자원 축에 없다).
+     * 그런데 에너지에서는 소비의 절반을 차지하고 감축 후보 1순위다 — 담을 자리가 반드시 있어야 한다.
+     *
+     * 처음에는 `curtailable-load` 하나로 받으려 했다. 그런데 그 이름은 **「줄일 수 있다」고 주장**한다:
+     * 폐수처리·방폭 환기·서버실 냉방은 공통이지만 줄일 수 없고, 그것을 감축 가능으로 두면 트윈이
+     * 「이걸 줄이면 됩니다」라는 거짓 제안을 한다. 공통성과 감축 가능성은 **다른 축**이다.
+     *
+     * 표준: IEC 61850 에 「공통 설비」라는 논리 노드는 없다(설비 종류마다 다른 노드다) — 비운다.
+     * ISO 50001 의 SEU 는 이 부류를 가장 많이 가리킨다(유의 에너지 사용처).
+     */
+    standardClass: { iso50001: "SEU", iso55000: "Asset" },
+    identity: { scheme: "kernel:id" },
+    capabilities: ["metered", "operable"]
+  },
   {
     key: "curtailable-load",
     role: "equipment",
@@ -2030,6 +2057,34 @@ var TWIN_AXES = [
     historical: true,
     standardClass: { isa95: "SegmentResponse", epcis: "TransformationEvent" },
     systems: LOGISTICS
+  },
+  /*
+   * ── 에너지가 더하는 개념은 **하나**다 (2026-08-14, §10 6.5단계) ──────────────
+   *
+   * 에너지 트윈의 개체 대부분은 **이미 있는 축**이 답한다: 전기 구간은 `locations`, 계량기·차단기·
+   * 태양광·축전지·감축 부하는 `equipment` 다(카탈로그가 그 타입들을 그 역할로 선언한다). 그것들을
+   * 새 축으로 다시 세우면 같은 것이 두 곳에서 세어진다 — 개념 지도가 계량기를 두 번 보여 준다.
+   *
+   * 정말로 새로운 것은 **수요 구간**이다: 자원이 아니고, 선언이 아니고, 15분마다 닫히는 **사실**이다.
+   * 그것이 요금의 알갱이이고 피크의 근거다(피크는 마감된 구간의 최대이므로 파생이다 — 축이 아니다).
+   *
+   * ── 표준 칸을 비운다 ──────────────────────────────────────────────────────
+   * 15분 수요 구간은 **요금 제도의 알갱이**다(계약·TOU). ISO 50001 은 경영 체계를, IEC 61850 은 설비
+   * 데이터 모델을 말하고, 둘 다 이 구간을 정의하지 않는다. 가까운 이름을 적으면 적합성 표가 거짓을
+   * 말하므로 비워 둔다 — 「표준에 자리가 없으면 빈 객체」라는 이 선언의 규율 그대로다.
+   *
+   * 아직 세우지 않은 것: **요금 구간**(TariffPeriod)과 **원단위**(EnPI). 둘 다 아직 아무도 만들지
+   * 않는다 — 선언만 하면 개념 지도가 언제나 0 을 보여 주고, 그것은 결손처럼 읽힌다(§10 7단계의 일).
+   */
+  {
+    axis: "demandWindows",
+    path: "energy.closed",
+    label: "twin.axis.demandWindows",
+    kind: "instance",
+    source: "state",
+    historical: true,
+    standardClass: {},
+    systems: ["ems"]
   }
 ];
 var TWIN_RELATIONS = [
@@ -5521,6 +5576,11 @@ var MesKernel = class extends FlowEngine {
 // src/ems-kernel.ts
 var DEMAND_WINDOW_MS = 15 * 60 * 1e3;
 var demandWindowStart = (atMs, windowMs = DEMAND_WINDOW_MS) => Math.floor(atMs / windowMs) * windowMs;
+function windowMsOf(opts) {
+  const raw = typeof opts === "number" ? opts : opts?.windowMs;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : DEMAND_WINDOW_MS;
+}
 var KEEP_CLOSED = 96;
 var EmsKernel = class extends FlowEngine {
   points = /* @__PURE__ */ new Map();
@@ -5531,9 +5591,23 @@ var EmsKernel = class extends FlowEngine {
   /** 이 구간에서 이미 제안을 냈나 — 같은 사실을 되풀어 방송하지 않는다(라이브 브리지의 교훈). */
   suggestedFor;
   windowMs;
-  constructor(tenantId, policy = firstFitPolicy, windowMs = DEMAND_WINDOW_MS) {
+  /**
+   * ── 세 번째 인자는 **호스트가 정한 자리**다 (2026-08-14 실측으로 고침) ──────
+   *
+   * 호스트는 모든 커널을 한 모양으로 세운다: `new Kernel(tenantId, undefined, productionSpecOf(model))`.
+   * 즉 세 번째 인자는 **도메인 옵션 슬롯**이고 커널마다 뜻이 다르다(야드는 모드, 생산은 명세).
+   *
+   * 처음에 이 자리를 `windowMs: number` 로 받았다가, 라이브에서 **모든 수요 구간이 깨졌다** —
+   * 생산 명세 객체가 창 길이로 들어와 `startMs: null`·`endMs: NaN` 이 됐다. 내 시험은 커널을
+   * `new EmsKernel('t')` 로 직접 세웠기 때문에 그것을 잡지 못했다(호스트와 다른 방식으로 세운 것이
+   * 그 자체로 결함이었다).
+   *
+   * 그래서 **쓸 수 있는 것만 읽는다**: 수면 창 길이로 쓰고, 객체면 `windowMs` 를 찾고, 없으면 기본값
+   * (15분)이다. 모르는 것을 창 길이로 삼지 않는다.
+   */
+  constructor(tenantId, policy = firstFitPolicy, opts) {
     super(tenantId, policy);
-    this.windowMs = windowMs;
+    this.windowMs = windowMsOf(opts);
   }
   /**
    * 계약전력 — **현장이 선언한 자리 속성**에서 읽는다(`EMS_PROPERTY.contractKW`).
@@ -5733,6 +5807,211 @@ var EmsKernel = class extends FlowEngine {
   }
 };
 
+// src/energy-ingest.ts
+function isEnergyRecord(record) {
+  if (!record || typeof record !== "object") return false;
+  const r = record;
+  return typeof r.meterId === "string" && r.meterId.trim().length > 0 && r.epc === void 0;
+}
+function ingestEnergyRecords(records, opts) {
+  const arr = Array.isArray(records) ? records : records ? [records] : [];
+  const accepted = [];
+  const rejected = [];
+  let seq = 0;
+  for (const record of arr) {
+    const errors = [];
+    const meterId = String(record?.meterId ?? "").trim();
+    if (!meterId) errors.push("meterId \uC5C6\uC74C \u2014 \uC5B4\uB514\uC758 \uC18C\uBE44\uC778\uC9C0 \uBAA8\uB974\uB294 \uAC12\uC740 \uB204\uC801\uD560 \uC218 \uC5C6\uB2E4");
+    const at = String(record?.at ?? "").trim() || opts.defaultEventTime;
+    const atMs = at ? Date.parse(at) : Number.NaN;
+    if (!Number.isFinite(atMs)) errors.push("at \uC5C6\uC74C/\uD615\uC2DD \uC624\uB958 \u2014 \uC9C0\uAE08 \uC2DC\uAC01\uC73C\uB85C \uBA54\uC6B0\uBA74 \uB0A8\uC758 \uC218\uC694 \uAD6C\uAC04\uC5D0 \uC2E4\uB9B0\uB2E4");
+    const num = (v, name) => {
+      if (v === void 0 || v === null || v === "") return void 0;
+      const n = Number(v);
+      if (!Number.isFinite(n)) {
+        errors.push(`${name} \uAC00 \uC218\uAC00 \uC544\uB2C8\uB2E4: ${JSON.stringify(v)}`);
+        return void 0;
+      }
+      return n;
+    };
+    const kW = num(record?.kW, "kW");
+    const kWh = num(record?.kWh, "kWh");
+    const powerFactor = num(record?.powerFactor, "powerFactor");
+    if (errors.length) {
+      rejected.push({ record, errors });
+      continue;
+    }
+    const eventTime = new Date(atMs).toISOString();
+    const data = {
+      meterId,
+      /* 계약은 `kW` 를 필수로 두지만 **못 읽은 표본도 사실**이다 — 그 경우 값을 비우고 보낸다.
+         커널이 「받았지만 부하를 못 읽었다」로 세고, 구간 마감에 그 이유를 싣는다. */
+      ...kW !== void 0 ? { kW } : {},
+      ...kWh !== void 0 ? { kWh } : {},
+      ...powerFactor !== void 0 ? { powerFactor } : {},
+      at: eventTime
+    };
+    accepted.push({
+      eventId: `${opts.tenantId}-energy-${++seq}`,
+      eventType: ENERGY_EVENT.measured,
+      eventTime,
+      tenantId: opts.tenantId,
+      data
+    });
+  }
+  return { accepted, rejected };
+}
+
+// src/energy-attribution.ts
+var near = (a, b, eps = 1e-9) => Math.abs(a - b) <= eps;
+function attributeEnergy(opts) {
+  const byId = new Map(opts.consumers.map((c) => [c.id, c]));
+  const dedicated = /* @__PURE__ */ new Map();
+  for (const c of opts.consumers) if (c.meterId) dedicated.set(c.meterId, c);
+  const shares = [];
+  const unattributed = [];
+  const excluded = [];
+  const overhead = [];
+  for (const pool of opts.pools) {
+    const kWh = Number(pool.kWh);
+    if (!Number.isFinite(kWh)) continue;
+    const own = dedicated.get(pool.meterId);
+    if (own) {
+      shares.push({ consumerId: own.id, kWh, basis: "measured", poolMeterId: pool.meterId });
+      continue;
+    }
+    if (pool.overhead) {
+      const alloc = opts.overheadAllocation;
+      const targets = (alloc?.processConsumerIds ?? []).map((id) => byId.get(id)).filter((c) => !!c);
+      const wOf = (c) => alloc?.weightKind === "equal" ? 1 : Number.isFinite(Number(c.weight)) && Number(c.weight) > 0 ? Number(c.weight) : 0;
+      const sharing2 = alloc?.weightKind === "equal" ? targets : targets.filter((c) => wOf(c) > 0);
+      const ws = sharing2.map(wOf);
+      const total = ws.reduce((a, b) => a + b, 0);
+      if (!alloc || total <= 0) {
+        overhead.push({ poolMeterId: pool.meterId, kWh });
+        continue;
+      }
+      let done = 0;
+      sharing2.forEach((c, i) => {
+        const share = ws[i] / total;
+        const amount = i === sharing2.length - 1 ? kWh - done : kWh * share;
+        done += amount;
+        shares.push({
+          consumerId: c.id,
+          kWh: amount,
+          basis: "apportioned",
+          poolMeterId: pool.meterId,
+          weightKind: alloc.weightKind,
+          weightShare: share,
+          overhead: true
+        });
+      });
+      continue;
+    }
+    const covered = (pool.consumerIds ?? []).map((id) => byId.get(id)).filter((c) => !!c);
+    if (!covered.length) {
+      unattributed.push({ poolMeterId: pool.meterId, kWh, reason: "no-consumers" });
+      continue;
+    }
+    if (covered.length === 1) {
+      shares.push({ consumerId: covered[0].id, kWh, basis: "measured", poolMeterId: pool.meterId });
+      continue;
+    }
+    const kind = opts.weightKind;
+    const weightOf = (c) => kind === "equal" ? 1 : Number.isFinite(Number(c.weight)) && Number(c.weight) > 0 ? Number(c.weight) : 0;
+    const sharing = kind === "equal" ? covered : covered.filter((c) => weightOf(c) > 0);
+    if (kind && sharing.length < covered.length) {
+      for (const c of covered) if (weightOf(c) <= 0) excluded.push({ consumerId: c.id, poolMeterId: pool.meterId, reason: "zero-weight" });
+    }
+    const weights = sharing.map(weightOf);
+    const sum = weights.reduce((a, b) => a + b, 0);
+    if (!kind || sum <= 0) {
+      unattributed.push({
+        poolMeterId: pool.meterId,
+        kWh,
+        reason: "no-weights",
+        consumerIds: covered.map((c) => c.id)
+      });
+      continue;
+    }
+    let given = 0;
+    sharing.forEach((c, i) => {
+      const share = weights[i] / sum;
+      const amount = i === sharing.length - 1 ? kWh - given : kWh * share;
+      given += amount;
+      shares.push({
+        consumerId: c.id,
+        kWh: amount,
+        basis: "apportioned",
+        poolMeterId: pool.meterId,
+        weightKind: kind,
+        weightShare: share
+      });
+    });
+  }
+  const measuredKWh = opts.pools.reduce((a, p) => a + (Number.isFinite(Number(p.kWh)) ? Number(p.kWh) : 0), 0);
+  const attributedKWh = shares.reduce((a, s) => a + s.kWh, 0);
+  const unattributedKWh = unattributed.reduce((a, u) => a + u.kWh, 0);
+  const overheadKWh = overhead.reduce((a, o) => a + o.kWh, 0);
+  if (!near(attributedKWh + unattributedKWh + overheadKWh, measuredKWh, 1e-6)) {
+    throw new Error(
+      `energy attribution lost or created energy: measured=${measuredKWh} attributed=${attributedKWh} unattributed=${unattributedKWh} overhead=${overheadKWh}`
+    );
+  }
+  return { shares, unattributed, excluded, overhead, totals: { measuredKWh, attributedKWh, unattributedKWh, overheadKWh } };
+}
+var UNIT = {
+  output: "kWh/unit",
+  runtimeHours: "kW",
+  area: "kWh/m2"
+};
+function energyIntensity(input) {
+  const kWh = Number(input.kWh);
+  if (!Number.isFinite(kWh)) return { value: null, reason: "no-energy" };
+  const den = Number(input.denominator?.value);
+  if (!Number.isFinite(den)) return { value: null, reason: "no-denominator" };
+  const ew = input.energyWindow;
+  const dw = input.denominator?.window;
+  if (ew && dw && (ew.startMs !== dw.startMs || ew.endMs !== dw.endMs)) return { value: null, reason: "window-mismatch" };
+  if (den === 0) return { value: null, reason: "zero-denominator" };
+  const window = ew ?? dw;
+  return {
+    value: kWh / den,
+    unit: UNIT[input.denominator.kind] ?? "kWh",
+    kWh,
+    denominator: den,
+    ...window ? { window } : { window: { startMs: 0, endMs: 0 } }
+  };
+}
+function energyOfWindows(windows, range) {
+  const inRange = (w) => !range || w.startMs >= range.startMs && w.endMs <= range.endMs;
+  let kWh = 0;
+  let counted = 0;
+  let skipped = 0;
+  let first;
+  let last;
+  for (const w of windows ?? []) {
+    if (!inRange(w)) continue;
+    const mean = Number(w.meanKW);
+    const hours = (Number(w.endMs) - Number(w.startMs)) / 36e5;
+    if (!Number.isFinite(mean) || !Number.isFinite(hours) || hours <= 0) {
+      skipped++;
+      continue;
+    }
+    kWh += mean * hours;
+    counted++;
+    if (first === void 0 || w.startMs < first) first = w.startMs;
+    if (last === void 0 || w.endMs > last) last = w.endMs;
+  }
+  return {
+    ...counted > 0 ? { kWh } : {},
+    basis: "mean-kw",
+    counted,
+    skipped,
+    ...first !== void 0 && last !== void 0 ? { window: { startMs: first, endMs: last } } : {}
+  };
+}
+
 // src/vocabulary.ts
 var RETIRED_VOCABULARY = ["mover", "Mover", "MOVER", "node", "Node", "NODE"];
 var VOCABULARY_EXCEPTIONS = [
@@ -5835,6 +6114,7 @@ function retiredVocabularyIn(line) {
   activeShiftOf,
   aggregationEvent,
   analyzeCapacity,
+  attributeEnergy,
   axesOfSystem,
   axisAppliesTo,
   axisInfo,
@@ -5852,6 +6132,8 @@ function retiredVocabularyIn(line) {
   documentPath,
   dueStatusOf,
   effectivityAt,
+  energyIntensity,
+  energyOfWindows,
   fefoPolicy,
   firstFitPolicy,
   foldJobResponses,
@@ -5862,6 +6144,8 @@ function retiredVocabularyIn(line) {
   inWorkCalendar,
   inWorkCalendarAt,
   ingest,
+  ingestEnergyRecords,
+  isEnergyRecord,
   isEquipmentLevel,
   isoDurationHours,
   itemKeyOf,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operato/twin-kernel",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "type": "module",
   "description": "Twin Domain Kernel — framework-agnostic, zero-dep (domain + sim + 3-channel contract). WMS/YMS/MES, EPCIS 2.0 · ISA-95.",
   "publishConfig": {