@operato/twin-kernel 0.7.0 → 0.7.2

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";