@operato/twin-kernel 0.6.14 → 0.7.1

package/dist/ems-kernel.js

@@ -0,0 +1,307 @@
+/*
+ * EMS 커널 — **계측 누적 → 구간 마감 → 피크 판정.** 설계: `design/profiles/ems.md` §3~§5·§10(3단계)
+ *
+ * ── 무엇이 다른가 ───────────────────────────────────────────────────────────
+ * 물류·생산 커널은 **물건이 자리 사이를 옮겨 다니는** 흐름을 굴린다. 에너지에는 옮겨 다니는 물건이
+ * 없다 — 스칼라가 시간 위에서 변한다. 그래도 `FlowEngine` 을 상속한다(§6 안 A): 저널·웜스타트·구조
+ * 전환·정합성 하네스를 그대로 얻고, 에너지에 없는 축은 **카탈로그가 「해당 없음」으로 선언**한다
+ * (`TWIN_AXES[].systems`). 상속의 대가를 축 선언으로 갚는 구조다.
+ *
+ * ── 표본을 쌓지 않는다 (§4.1 인제스트 계약) ─────────────────────────────────
+ * 계량은 멈추지 않는다(계량기 하나가 1분 주기면 하루 1,440건, 피더 100개면 14만건). 그래서 이 커널은
+ * **표본을 보관하지 않는다** — 열린 구간의 누적값만 들고 있다(최대·적산·표본 수). 상태 크기가 계측
+ * 주기와 무관해야 웜스타트·스냅샷·fork 가 그대로 성립한다.
+ *
+ * ── 우리가 내는 사실과 받은 사실을 구별한다 ─────────────────────────────────
+ * 표본(`energy.measured`)은 **원천이 준 것**이라 우리가 다시 방출하지 않는다. 구간 마감·피크 경신·
+ * 감축 제안은 **우리가 판정한 것**이라 저널에 남긴다(`emitOp`). 저널만 보고 "이건 누가 말한 것인가" 를
+ * 답할 수 있어야 한다.
+ *
+ * ── 하지 않는 것 ────────────────────────────────────────────────────────────
+ *  · **제어하지 않는다** — 차단·투입·감축 실행은 범위 밖이다(§1). `dr.suggested` 는 제안이고, 집행은
+ *    사람이 자기 시스템에서 한다. 이름이 그 사실을 말한다.
+ *  · **요금 구간 전환**(`tariff.shift`)은 아직 없다 — 요금표는 현장·계절·계약의 것이고, 그것을 지어내면
+ *    금액이 거짓이 된다. 최소 커널의 몫이 아니다(§10 의 다음 단계).
+ *  · **월 경계를 정하지 않는다** — 「월 최대 수요」는 현장 시간대와 요금제가 정하는 것이라, 여기서는
+ *    **관측 시작 이후 최대**만 답하고 그 사실을 이름으로 말한다(`peakSince`). 지어내지 않는다.
+ */
+import { FlowEngine } from "./flow-engine.js";
+import { firstFitPolicy } from "./allocation-policy.js";
+import { ENERGY_EVENT } from "./contract.js";
+import { EMS_PROPERTY } from "./ems-profile.js";
+/** 수요 구간 — 요금의 알갱이다. 15분은 한국·다수 요금제의 최대수요 산정 단위다. */
+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 {
+    points = new Map();
+    open;
+    closed = [];
+    closedTotal = 0;
+    peak;
+    /** 이 구간에서 이미 제안을 냈나 — 같은 사실을 되풀어 방송하지 않는다(라이브 브리지의 교훈). */
+    suggestedFor;
+    windowMs;
+    /**
+     * ── 세 번째 인자는 **호스트가 정한 자리**다 (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 = windowMsOf(opts);
+    }
+    /**
+     * 계약전력 — **현장이 선언한 자리 속성**에서 읽는다(`EMS_PROPERTY.contractKW`).
+     *
+     * 여러 자리가 선언하면 **가장 큰 값**을 쓴다: 수전 지점의 계약이 분기의 것보다 크고, 트윈 전체의
+     * 한계는 수전이 정한다. 선언이 없으면 `undefined` — 계약을 모르면 계약 대비 판정을 하지 않는다
+     * (기본값을 지어내면 그 뒤 모든 판정이 거짓 위에 선다).
+     */
+    declaredContractKW() {
+        let max;
+        for (const loc of this.boardDef?.locations ?? []) {
+            for (const p of loc.properties ?? []) {
+                if (p.id !== EMS_PROPERTY.contractKW)
+                    continue;
+                const v = Number(p.value);
+                if (!Number.isFinite(v) || v <= 0)
+                    continue;
+                if (max === undefined || v > max)
+                    max = v;
+            }
+        }
+        return max;
+    }
+    /**
+     * 계측 표본을 받는다 — 에너지 사건만 가로채고 나머지는 그대로 상위에 넘긴다.
+     *
+     * 가로챈 표본은 **다시 방출하지 않는다**: 원천이 이미 그 사실을 갖고 있고, 저널은 인입에서 한 번만
+     * 적는다(상위 `apply` 의 재방출 규약과 같은 이유).
+     */
+    apply(envelope) {
+        if (envelope.eventType === ENERGY_EVENT.measured) {
+            this.ingestMeasured(envelope);
+            return;
+        }
+        super.apply(envelope);
+    }
+    ingestMeasured(envelope) {
+        const d = envelope.data;
+        /* 시각은 **계측이 말한 것**이 먼저다(`data.at`) — 봉투 시각은 전달 시각일 수 있다.
+           둘 다 없으면 어느 구간의 것인지 알 수 없다: 지금 시각으로 메우면 남의 구간에 실린다. */
+        const atMs = [String(d?.at ?? ''), String(envelope.eventTime ?? '')]
+            .map(v => Date.parse(v))
+            .find(v => Number.isFinite(v));
+        if (atMs === undefined)
+            throw new Error('energy.measured has no usable time (data.at / eventTime) — cannot place it in a demand window');
+        const id = String(d?.meterId ?? '').trim();
+        if (!id)
+            throw new Error('energy.measured has no meterId — a measurement with no meter cannot be accumulated');
+        /* 이 표본이 새 구간의 것이면 앞 구간을 먼저 닫는다 — 마감이 표본보다 늦으면 최대가 섞인다. */
+        this.closeDue(atMs);
+        this.openWindow(atMs);
+        const kW = Number.isFinite(Number(d?.kW)) ? Number(d.kW) : undefined;
+        const point = this.points.get(id) ?? { id, samplesInWindow: 0 };
+        /* 늦게 온 옛 표본이 최신 관측을 덮지 않게 — 상위 커널의 `stale` 판정과 같은 규율. */
+        if (point.atMs === undefined || atMs >= point.atMs) {
+            point.atMs = atMs;
+            if (kW !== undefined)
+                point.kW = kW;
+            if (Number.isFinite(Number(d?.kWh)))
+                point.kWh = Number(d.kWh);
+            if (Number.isFinite(Number(d?.powerFactor)))
+                point.powerFactor = Number(d.powerFactor);
+        }
+        point.samplesInWindow++;
+        this.points.set(id, point);
+        const w = this.open;
+        if (kW !== undefined) {
+            /*
+             * 구간의 부하는 **지점의 합**이다(수전 하나만 계량하는 현장도, 피더를 여럿 계량하는 현장도 있다).
+             * 마지막으로 관측된 값들을 더한다 — 표본 주기가 지점마다 달라도 이것이 그 순간의 최선이다.
+             * 지점 하나가 침묵하면 그 값은 낡은 채로 더해진다: 그래서 `atMs` 를 지점마다 남겨 소비처가
+             * 「이 지점은 3시간째 조용하다」를 볼 수 있게 한다.
+             */
+            const total = [...this.points.values()].reduce((sum, p) => sum + (p.kW ?? 0), 0);
+            if (w.maxKW === undefined || total > w.maxKW)
+                w.maxKW = total;
+            w.samples++;
+            w.meanKW = (w.meanKW === undefined ? total : (w.meanKW * (w.samples - 1) + total) / w.samples);
+        }
+        this.revision++;
+        this.judgeOpenWindow(atMs);
+    }
+    openWindow(atMs) {
+        const start = demandWindowStart(atMs, this.windowMs);
+        if (this.open?.startMs === start)
+            return;
+        const contractKW = this.declaredContractKW();
+        this.open = { startMs: start, endMs: start + this.windowMs, samples: 0, ...(contractKW !== undefined ? { contractKW } : {}) };
+        /* 새 구간이면 지점별 표본 수도 새로 센다 — 구간마다 「못 쟀다」를 답할 수 있어야 한다. */
+        for (const p of this.points.values())
+            p.samplesInWindow = 0;
+        this.suggestedFor = undefined;
+    }
+    /**
+     * 지난 구간을 닫는다 — **표본이 없으면 값을 만들지 않는다.**
+     *
+     * 침묵한 구간을 「0 kW」로 닫으면 그 트윈은 「그 15분 동안 전기를 쓰지 않았다」고 말하는 것이 된다.
+     * 구간이 지난 것은 사실이고 우리가 못 쟀다는 것도 사실이므로, 구간은 남기고 값은 비운다.
+     *
+     * 표본이 오지 않으면 마감도 오지 않는다(라이브에서 계측이 끊기면 열린 구간이 그대로 남는다).
+     * 그래서 이것은 **공개**다 — 호스트가 시각을 주며 부를 수 있다(`tick` 도 이것을 부른다).
+     */
+    closeDue(nowMs) {
+        const done = [];
+        while (this.open && nowMs >= this.open.endMs) {
+            const w = this.open;
+            if (w.contractKW !== undefined && w.maxKW !== undefined)
+                w.overContract = w.maxKW > w.contractKW;
+            this.closed.push(w);
+            this.closedTotal++;
+            if (this.closed.length > KEEP_CLOSED)
+                this.closed.splice(0, this.closed.length - KEEP_CLOSED);
+            done.push(w);
+            this.emitOp(ENERGY_EVENT.demandWindow, {
+                startMs: w.startMs,
+                endMs: w.endMs,
+                ...(w.maxKW !== undefined ? { maxKW: w.maxKW } : {}),
+                ...(w.meanKW !== undefined ? { meanKW: w.meanKW } : {}),
+                samples: w.samples,
+                ...(w.contractKW !== undefined ? { contractKW: w.contractKW } : {}),
+                ...(w.overContract !== undefined ? { overContract: w.overContract } : {}),
+                /*
+                 * 부하를 셀 근거가 없었다는 사실을 코드로 낸다 — 화면이 「0 kW」와 「못 쟀다」를 구별할 수 있게.
+                 *
+                 * 이름이 조건과 정확히 같아야 한다: `samples` 는 **kW 를 실은 표본**의 수다. 표본은 왔는데
+                 * kW 를 못 읽은 경우(계기 오류·필드 누락)가 실제로 있고, 그것은 「아무것도 오지 않았다」와
+                 * 다르다. 무엇이 왔는지는 지점별 `samplesInWindow` 가 답한다.
+                 */
+                ...(w.samples === 0 ? { observedAbsence: 'no-load-samples' } : {})
+            });
+            /* 피크는 **마감된 구간**으로만 갱신한다 — 열린 구간의 최대는 아직 확정이 아니다. */
+            if (w.maxKW !== undefined && (this.peak === undefined || w.maxKW > this.peak.kW)) {
+                this.peak = { kW: w.maxKW, windowStartMs: w.startMs };
+                this.emitOp(ENERGY_EVENT.peak, { kW: w.maxKW, windowStartMs: w.startMs, ...(w.contractKW !== undefined ? { contractKW: w.contractKW } : {}) });
+            }
+            /* 다음 구간은 표본이 올 때 연다 — 미리 열면 오지 않은 구간을 존재하는 것처럼 만든다. */
+            this.open = undefined;
+        }
+        return done;
+    }
+    /**
+     * 열린 구간의 판정 — **이대로 가면 계약을 넘는가.**
+     *
+     * 예측은 「지금까지의 평균 부하가 구간 끝까지 이어진다」다. 단순하지만 그 가정을 **값과 함께 낸다**
+     * (`projectionBasis`) — 근거를 감춘 예측은 사용자가 검증할 수 없다. 남은 시간이 짧을수록 이 예측은
+     * 실제에 가까워진다(구간 초반의 경보는 성급할 수 있다는 뜻이고, 그것도 사용자가 알아야 한다).
+     *
+     * 넘을 것 같으면 **제안**을 낸다 — 무엇을 줄일 수 있는지는 모델이 선언한 감축 가능 설비가 답한다.
+     * 우리는 끄지 않는다.
+     */
+    judgeOpenWindow(atMs) {
+        const w = this.open;
+        if (!w || w.contractKW === undefined || w.meanKW === undefined)
+            return;
+        if (this.suggestedFor === w.startMs)
+            return;
+        const elapsed = Math.max(1, atMs - w.startMs);
+        const projected = (w.meanKW * elapsed + w.meanKW * (w.endMs - atMs)) / this.windowMs;
+        if (projected <= w.contractKW)
+            return;
+        this.suggestedFor = w.startMs;
+        this.emitOp(ENERGY_EVENT.drSuggested, {
+            windowStartMs: w.startMs,
+            projectedKW: projected,
+            contractKW: w.contractKW,
+            gapKW: projected - w.contractKW,
+            projectionBasis: 'mean-so-far',
+            /* 줄일 수 있는 것 — 선언된 감축 가능 설비다. 우선순위·최소 유지는 현장이 정하므로 여기서
+               고르지 않고 **후보를 있는 대로** 낸다(고르는 것은 사람의 일이다). */
+            curtailableCandidates: this.curtailableIds()
+        });
+    }
+    /** 감축 가능으로 **선언된** 설비 — 커널이 능력을 짐작하지 않는다(타입이 선언한다). */
+    curtailableIds() {
+        return (this.boardDef?.equipment ?? [])
+            .filter(e => String(e.kind ?? '') === 'curtailable-load')
+            .map(e => e.id);
+    }
+    /*
+     * ── 흐름 훅 넷 — **상속의 대가다** (§6 안 A) ─────────────────────────────
+     *
+     * `FlowEngine` 은 이 넷을 abstract 로 요구한다: 도착·오더·배정·작업 완료. 에너지에는 그 넷이 없다
+     * (물건이 도착하지 않고, 주문이 없고, 배정할 자원이 없고, 완료될 작업이 없다). 그래서 여기서
+     * **아무 일도 하지 않는다** — 그런데 조용히 넘기지 않는다: 이 커널이 그런 요청을 받았다는 것은
+     * **배선이 잘못됐다는 사실**이고(EMS 트윈에 물류 명령을 보낸 것), 조용히 넘기면 그 사실이 사라진다.
+     *
+     * 던지지도 않는다: 저널 재생 중이라면 트윈 전체가 멈춘다. 그래서 커널이 담을 줄 모르는 사건을
+     * 세는 자리(`ObservedReducer.unhandled`)와 같은 규율으로, **개수를 세어 상태로 낸다.**
+     */
+    flowRequests = new Map();
+    noteFlowRequest(hook) {
+        this.flowRequests.set(hook, (this.flowRequests.get(hook) ?? 0) + 1);
+    }
+    onArrival() {
+        this.noteFlowRequest('onArrival');
+    }
+    onOrder() {
+        this.noteFlowRequest('onOrder');
+    }
+    allocate() {
+        this.noteFlowRequest('allocate');
+    }
+    onTaskComplete() {
+        this.noteFlowRequest('onTaskComplete');
+    }
+    /** 시뮬 시간으로도 구간이 닫힌다 — 관측이 없어도 시간은 간다. */
+    tick(dtMs) {
+        super.tick(dtMs);
+        this.closeDue(this.clockMs);
+    }
+    getSnapshot() {
+        const snap = super.getSnapshot();
+        const contractKW = this.declaredContractKW();
+        const energy = {
+            points: [...this.points.values()].map(p => ({ ...p })),
+            ...(this.open
+                ? {
+                    open: {
+                        ...this.open,
+                        ...(this.open.meanKW !== undefined ? { projectedKW: this.open.meanKW, projectionBasis: 'mean-so-far' } : {})
+                    }
+                }
+                : {}),
+            closed: this.closed.map(w => ({ ...w })),
+            closedTotal: this.closedTotal,
+            ...(this.peak ? { peakSince: { ...this.peak } } : {}),
+            ...(contractKW !== undefined ? { contractKW } : {}),
+            /* 물류 흐름 요청을 받은 적이 있나 — 있으면 이 트윈에 엉뚱한 명령이 오고 있다는 사실이다. */
+            ...(this.flowRequests.size
+                ? { flowRequests: [...this.flowRequests.entries()].map(([hook, count]) => ({ hook, count })) }
+                : {})
+        };
+        return { ...snap, energy };
+    }
+}

package/dist/ems-profile.d.ts

@@ -0,0 +1,16 @@
+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", "utility", "curtailable-load"];
+/**
+ * 커널이 **읽는** 자리 속성 — 뜻을 코드 한가운데 숨기지 않는다.
+ *
+ * 속성 자체는 열려 있고(`ResourceProperty`) 어휘는 표준이 정하지 않는다. 그래서 커널이 판정에 쓰는
+ * 것만 여기 이름으로 못 박는다 — 이 목록에 없는 속성은 커널이 나르기만 하고 해석하지 않는다.
+ */
+export declare const EMS_PROPERTY: {
+    /** 계약전력(kW) — 수전·분기 자리에 선언한다. 없으면 계약 대비 판정을 하지 않는다. */
+    readonly contractKW: "contract.kW";
+};
+export declare const EMS_TYPES: TwinTypeInfo[];

package/dist/ems-profile.js

@@ -0,0 +1,133 @@
+/** 로케이션(수동) 타입 키 — 배전 계통의 구간. */
+export const EMS_LOCATION_TYPES = ['incoming', 'feeder', 'submeter-zone'];
+/** 설비(능동) 타입 키 — 계량 지점과 에너지 자원. */
+export const EMS_EQUIPMENT_TYPES = ['meter', 'breaker', 'pv-array', 'battery', 'utility', 'curtailable-load'];
+/**
+ * 커널이 **읽는** 자리 속성 — 뜻을 코드 한가운데 숨기지 않는다.
+ *
+ * 속성 자체는 열려 있고(`ResourceProperty`) 어휘는 표준이 정하지 않는다. 그래서 커널이 판정에 쓰는
+ * 것만 여기 이름으로 못 박는다 — 이 목록에 없는 속성은 커널이 나르기만 하고 해석하지 않는다.
+ */
+export const EMS_PROPERTY = {
+    /** 계약전력(kW) — 수전·분기 자리에 선언한다. 없으면 계약 대비 판정을 하지 않는다. */
+    contractKW: 'contract.kW'
+};
+export const EMS_TYPES = [
+    /* ── 자리: 전기적 구간 ─────────────────────────────────────────────────── */
+    {
+        key: 'incoming',
+        role: 'location',
+        /* 전기 계통의 구간은 **설비 계층의 단이 아니다** — 표준의 탈출구(`Other`)를 쓴다(아래 주석). */
+        level: 'Other',
+        label: 'twin.type.incoming',
+        /* 수전 지점 — 계약전력이 걸리는 자리이고, 요금의 근거가 되는 수요는 여기서 잰다.
+           ISO 50001 의 「에너지 유입」 경계이기도 하다(조직의 에너지 검토가 여기서 시작한다). */
+        standardClass: { iec61850: 'MMTR', iso50001: 'EnergyInput' },
+        identity: { scheme: 'kernel:id' },
+        capabilities: ['metered']
+    },
+    {
+        key: 'feeder',
+        role: 'location',
+        /* 전기 계통의 구간은 **설비 계층의 단이 아니다** — 표준의 탈출구(`Other`)를 쓴다(아래 주석). */
+        level: 'Other',
+        label: 'twin.type.feeder',
+        /* 분기 회로 — 부하 분해의 단위. 계약전력의 하위 배분이 여기서 정해진다. */
+        standardClass: { iec61850: 'Feeder', iso50001: 'EnergyUse' },
+        identity: { scheme: 'kernel:id' },
+        capabilities: ['metered']
+    },
+    {
+        key: 'submeter-zone',
+        role: 'location',
+        /* 전기 계통의 구간은 **설비 계층의 단이 아니다** — 표준의 탈출구(`Other`)를 쓴다(아래 주석). */
+        level: 'Other',
+        label: 'twin.type.submeter-zone',
+        /*
+         * 구역 계량 — 여러 부하를 한 계량기로 묶어 재는 자리(공조·조명처럼 개별 계량이 없는 것들).
+         *
+         * ISO 50001 의 **SEU**(유의 에너지 사용처)가 대개 이 알갱이다. 개별 설비까지 재지 못하는 현장이
+         * 많고, 그것을 「모른다」로 두는 대신 **묶음으로 아는 것**이 정직하다.
+         */
+        standardClass: { iec61850: 'MMXU', iso50001: 'SEU' },
+        identity: { scheme: 'kernel:id' },
+        capabilities: ['metered']
+    },
+    /* ── 설비: 계량 지점과 에너지 자원 ──────────────────────────────────────── */
+    {
+        key: 'meter',
+        role: 'equipment',
+        label: 'twin.type.meter',
+        /* 계량기 — 측정 논리 노드(MMXU=측정단위, MMTR=적산). 자산으로도 하나다(ISO 55000). */
+        standardClass: { iec61850: 'MMXU', iso55000: 'Asset', iso50001: 'MeasurementPoint' },
+        identity: { scheme: 'kernel:id' },
+        capabilities: ['metered', 'operable']
+    },
+    {
+        key: 'breaker',
+        role: 'equipment',
+        label: 'twin.type.breaker',
+        /*
+         * 차단기 — IEC 61850 `XCBR`. **우리는 이것을 조작하지 않는다**(안전 계통은 범위 밖: ems.md §1).
+         * 상태를 읽어 계통 구성을 알 뿐이다 — 그래서 능력은 `operable` 만이고 `curtailable` 이 아니다.
+         */
+        standardClass: { iec61850: 'XCBR', iso55000: 'Asset' },
+        identity: { scheme: 'kernel:id' },
+        capabilities: ['operable']
+    },
+    {
+        key: 'pv-array',
+        role: 'equipment',
+        label: 'twin.type.pv-array',
+        /* 태양광 어레이 — IEC 61850-7-420(분산자원)의 `DPVA`. 발전과 계량은 다른 능력이다. */
+        standardClass: { iec61850: 'DPVA', iso55000: 'Asset', iso50001: 'RenewableSupply' },
+        identity: { scheme: 'kernel:id' },
+        capabilities: ['generating', 'metered', 'operable']
+    },
+    {
+        key: 'battery',
+        role: 'equipment',
+        label: 'twin.type.battery',
+        /* 축전지(ESS) — `ZBAT`. 충전·방전을 나눠 재고, 저장은 보관(`storable`)이 아니다(물건이 아니다). */
+        standardClass: { iec61850: 'ZBAT', iso55000: 'Asset' },
+        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',
+        label: 'twin.type.curtailable-load',
+        /*
+         * 감축 가능 부하 — 줄일 수 있는 소비처(공조·충전기·비상시 미가동 라인).
+         *
+         * 표준에 이 이름은 없다: IEC 61850 은 설비를 종류로 부르고 「감축 가능」은 **운영 정책**이다.
+         * 그래서 `iec61850` 칸을 비우고 ISO 50001 의 SEU 로만 대응한다 — 억지로 논리 노드를 적으면
+         * 적합성 표가 거짓을 말한다.
+         */
+        standardClass: { iso50001: 'SEU' },
+        identity: { scheme: 'kernel:id' },
+        capabilities: ['curtailable', 'metered', 'operable']
+    }
+];

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;