@operato/ops-contract 0.1.0

package/dist/energy-ingest.js

@@ -0,0 +1,801 @@
+/*
+ * 에너지 계측 인제스트 — **표본 레코드 → 봉투.** 설계: `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, OBSERVATION_BASIS } from "./contract.js";
+/** 이 레코드가 에너지 표본인가 — 라우팅 판정을 한 곳에 둔다(소비처가 각자 짐작하지 않게). */
+export function isEnergyRecord(record) {
+    if (!record || typeof record !== 'object')
+        return false;
+    const r = record;
+    /* 계량 지점이 있고 EPCIS 어휘가 없으면 에너지다. `epc` 가 함께 있으면 둘 중 무엇인지 알 수 없으므로
+       에너지로 받지 않는다 — 그 판단은 커넥터가 명확히 해야 한다. */
+    if (!(typeof r.meterId === 'string' && r.meterId.trim().length > 0 && r.epc === undefined))
+        return false;
+    /*
+     * ── **마감된 구간은 계량 표본이 아니다** (2026-08-29) ──────────────────────
+     *
+     * 둘 다 `meterId` 를 가지므로 이 판별이 겹쳤다. 겹친 채로 두면 갈림의 **순서**가 값을 정한다 —
+     * 순서를 잘못 두면 시간별 사용량이 계량 문으로 가고, 그 문은 `kWh` 를 적산 레지스터로 읽는다.
+     * 우리가 넣는 값은 이미 그 구간의 양이므로 **차분의 차분**이 된다.
+     *
+     * 가장 나쁜 모양이다: **거부되지 않고 값만 틀린다.** 그래서 순서에 기대지 않고 배타로 만든다
+     * (설비 상태와 발전 적산을 가를 때와 같은 규율).
+     */
+    return r.from === undefined && r.to === 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 };
+}
+/** 개폐 위치의 값 — 표준이 정한 넷. 그 밖의 낱말은 받지 않는다(뭉개면 없는 확신이 생긴다). */
+const POSITIONS = new Set(['open', 'closed', 'intermediate', 'bad']);
+/** 이 레코드가 설비 에너지 상태인가 — 라우팅 판정을 한 곳에 둔다. */
+export function isEnergyEquipmentRecord(record) {
+    if (!record || typeof record !== 'object')
+        return false;
+    const r = record;
+    /*
+     * ── **발전 적산을 밀어낸다** (2026-08-28 · 인티그레이션 레인이 걸어 보고 찾았다) ─
+     *
+     * 이 판정이 `equipmentId` 만 보아서 **발전 적산 레코드에도 참이었다.** 그래서 호스트가 설비 상태
+     * 필터를 먼저 돌리면 적산이 이 문으로 들어오고, 이 문은 「바꿀 상태가 하나도 없다」고 거부한다 —
+     * **엉뚱한 이유로 거부되고 커넥터는 보냈다고 믿는다.**
+     *
+     * 호스트가 순서로 풀 수 있지만 순서는 다음 사람이 줄을 옮기면 깨진다. 다른 어휘를 밀어내는 규율은
+     * 발전 쪽이 이미 갖고 있었다(`meterId`·`epc` 를 본다) — 이쪽만 없었다. **판정끼리 배타로 만든다.**
+     */
+    return (typeof r.equipmentId === 'string' &&
+        r.equipmentId.trim().length > 0 &&
+        r.epc === undefined &&
+        r.meterId === undefined &&
+        /* 적산을 실었으면 발전이다 — 이 문의 값은 상태이고, 적산은 자기 문이 있다. */
+        r.kWh === undefined);
+}
+/**
+ * 설비 에너지 레코드 → 봉투. 계량과 같은 규율이다: 지어낼 수 없는 것이 빠지면 받지 않고, 받지 않은 것은
+ * 이유와 함께 알린다.
+ *
+ * **값이 하나도 없는 레코드는 거부한다** — 계량과 다른 점이다. 계량은 「응답했다」는 사실 자체가
+ * 관측이지만(그래서 kW 없는 표본을 받는다), 여기서는 바꿀 상태가 없는 것을 사실로 적을 이유가 없다.
+ */
+export function ingestEnergyEquipmentRecords(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 r = record;
+        const equipmentId = String(r?.equipmentId ?? '').trim();
+        if (!equipmentId)
+            errors.push('equipmentId 없음 — 어느 설비의 상태인지 모르는 값은 실을 수 없다');
+        const at = String(r?.at ?? '').trim() || opts.defaultEventTime;
+        const atMs = at ? Date.parse(at) : Number.NaN;
+        if (!Number.isFinite(atMs))
+            errors.push('at 없음/형식 오류 — 지금 시각으로 메우면 언제의 상태인지 알 수 없다');
+        const num = (v, name, min, max) => {
+            if (v === undefined || v === null || v === '')
+                return undefined;
+            const n = Number(v);
+            if (!Number.isFinite(n)) {
+                errors.push(`${name} 가 수가 아니다: ${JSON.stringify(v)}`);
+                return undefined;
+            }
+            if (min !== undefined && n < min) {
+                errors.push(`${name} 가 ${min} 보다 작다: ${n}`);
+                return undefined;
+            }
+            if (max !== undefined && n > max) {
+                errors.push(`${name} 가 ${max} 보다 크다: ${n}`);
+                return undefined;
+            }
+            return n;
+        };
+        const generatedKW = num(r?.generatedKW, 'generatedKW', 0);
+        const exportKW = num(r?.exportKW, 'exportKW');
+        /* 충전율은 백분율이다 — 범위를 벗어난 값은 받지 않는다(단위를 잘못 매핑한 커넥터를 조용히 통과시키면
+           「배터리가 380% 찼다」가 화면에 뜬다). */
+        const soc = num(r?.soc, 'soc', 0, 100);
+        const chargeKW = num(r?.chargeKW, 'chargeKW', 0);
+        const dischargeKW = num(r?.dischargeKW, 'dischargeKW', 0);
+        const minKW = num(r?.minKW, 'minKW', 0);
+        let curtailable;
+        if (r?.curtailable !== undefined && r?.curtailable !== null) {
+            if (typeof r.curtailable !== 'boolean')
+                errors.push(`curtailable 가 참/거짓이 아니다: ${JSON.stringify(r.curtailable)}`);
+            else
+                curtailable = r.curtailable;
+        }
+        /*
+         * ── 전기 계측 (2026-08-29) ─────────────────────────────────────────────────
+         *
+         * 음수는 받지 않는다. 전압·전류의 크기는 음수가 되지 않고, 방향은 다른 축이 말한다
+         * (`chargeKW`·`dischargeKW`·`exportKW`). 음수를 받아 두면 화면이 「-380V」를 그린다.
+         *
+         * 상별 값은 **배열 그대로** 받는다. 합치거나 평균 내지 않는다 — 상 불평형은 그 자체로 사실이고,
+         * 한 수로 접으면 되돌릴 수 없다.
+         */
+        const dcVoltage = num(r?.dcVoltage, 'dcVoltage', 0);
+        const dcCurrent = num(r?.dcCurrent, 'dcCurrent', 0);
+        const phases = (raw, name) => {
+            if (raw === undefined || raw === null)
+                return undefined;
+            if (!Array.isArray(raw)) {
+                errors.push(`${name} 가 배열이 아니다 — 상별 값이라 배열로 받는다(단상이면 원소 하나): ${JSON.stringify(raw)}`);
+                return undefined;
+            }
+            if (!raw.length) {
+                errors.push(`${name} 가 빈 배열이다 — 잰 상이 없으면 그 칸을 보내지 않는다`);
+                return undefined;
+            }
+            const out = [];
+            for (const [i, v] of raw.entries()) {
+                const n = Number(v);
+                if (!Number.isFinite(n)) {
+                    errors.push(`${name}[${i}] 를 수로 읽을 수 없다: ${JSON.stringify(v)}`);
+                    return undefined;
+                }
+                if (n < 0) {
+                    errors.push(`${name}[${i}] 가 음수다(${n}) — 크기는 음수가 되지 않는다(방향은 다른 축이 말한다)`);
+                    return undefined;
+                }
+                out.push(n);
+            }
+            return out;
+        };
+        const acVoltage = phases(r?.acVoltage, 'acVoltage');
+        const acCurrent = phases(r?.acCurrent, 'acCurrent');
+        /* 상 수가 다르면 짝이 맞지 않는다 — 어느 상의 전류인지 알 수 없는 값을 받지 않는다. */
+        if (acVoltage && acCurrent && acVoltage.length !== acCurrent.length) {
+            errors.push(`acVoltage(${acVoltage.length}상)와 acCurrent(${acCurrent.length}상)의 상 수가 다르다`);
+        }
+        let position;
+        if (r?.position !== undefined && r?.position !== null && r?.position !== '') {
+            const p = String(r.position);
+            if (!POSITIONS.has(p))
+                errors.push(`position 이 표준 값이 아니다(open·closed·intermediate·bad): ${JSON.stringify(r.position)}`);
+            else
+                position = p;
+        }
+        const values = { generatedKW, exportKW, soc, chargeKW, dischargeKW, curtailable, minKW, position, dcVoltage, dcCurrent, acVoltage, acCurrent };
+        if (!errors.length && Object.values(values).every(v => v === undefined)) {
+            errors.push('바꿀 상태가 하나도 없다 — 값 없는 보고는 사실로 적을 것이 없다');
+        }
+        if (errors.length) {
+            rejected.push({ record, errors });
+            continue;
+        }
+        const eventTime = new Date(atMs).toISOString();
+        const data = {
+            equipmentId,
+            at: eventTime,
+            ...(generatedKW !== undefined ? { generatedKW } : {}),
+            ...(exportKW !== undefined ? { exportKW } : {}),
+            ...(soc !== undefined ? { soc } : {}),
+            ...(chargeKW !== undefined ? { chargeKW } : {}),
+            ...(dischargeKW !== undefined ? { dischargeKW } : {}),
+            ...(curtailable !== undefined ? { curtailable } : {}),
+            ...(minKW !== undefined ? { minKW } : {}),
+            ...(position !== undefined ? { position } : {}),
+            ...(dcVoltage !== undefined ? { dcVoltage } : {}),
+            ...(dcCurrent !== undefined ? { dcCurrent } : {}),
+            ...(acVoltage !== undefined ? { acVoltage } : {}),
+            ...(acCurrent !== undefined ? { acCurrent } : {})
+        };
+        accepted.push({
+            eventId: `${opts.tenantId}-energy-eq-${++seq}`,
+            eventType: ENERGY_EVENT.equipment,
+            eventTime,
+            tenantId: opts.tenantId,
+            data
+        });
+    }
+    return { accepted, rejected };
+}
+/** 이 레코드가 발전 적산인가 — 어느 갈래로 보낼지를 한 곳에서 정한다. */
+export function isEnergyGenerationRecord(record) {
+    /* 구간이 있으면 마감된 발전 기간이지 시점의 적산이 아니다 — 겹치면 지난 기록이 「지금」으로 읽힌다. */
+    if (record?.from !== undefined || record?.to !== undefined)
+        return false;
+    if (!record || typeof record !== 'object')
+        return false;
+    const r = record;
+    /* 설비를 말하고 적산을 실었으면 발전이다. 계량 어휘가 함께 있으면 어느 쪽인지 알 수 없어 받지 않는다. */
+    return (typeof r.equipmentId === 'string' &&
+        r.equipmentId.trim().length > 0 &&
+        r.kWh !== undefined &&
+        r.meterId === undefined &&
+        r.epc === undefined);
+}
+/**
+ * 발전 적산 레코드 → 봉투. 계량과 같은 규율이다: 지어낼 수 없는 것이 빠지면 받지 않고, 받지 않은 것은
+ * 이유와 함께 알린다.
+ *
+ * **적산이 없는 레코드는 받지 않는다** — 이 문의 값은 그것 하나다. 순시 출력은 설비 상태 문이 받는다
+ * (`EnergyEquipmentRecord.generatedKW`).
+ */
+export function ingestEnergyGenerationRecords(records, opts) {
+    const list = records === undefined || records === null ? [] : Array.isArray(records) ? records : [records];
+    const accepted = [];
+    const rejected = [];
+    let seq = 0;
+    for (const r of list) {
+        const errors = [];
+        const equipmentId = String(r?.equipmentId ?? '').trim();
+        if (!equipmentId)
+            errors.push('equipmentId 가 없다 — 어느 설비가 만든 것인지 지어낼 수 없다');
+        /*
+         * ── **한 레코드가 두 사실을 실어 오면 거부한다** (2026-08-28) ────────────────
+         *
+         * 판정을 배타로 만들면서 생긴 자리다. 적산을 실었으면 이 문으로 오는데, 그 레코드에 상태 값
+         * (`generatedKW`·`soc`·`position` …)이 함께 있으면 **그 사실이 조용히 사라진다** — 이 문은 상태를
+         * 읽지 않기 때문이다.
+         *
+         * 잃는 것보다 거부하는 편이 낫다. 커넥터가 갈라 보내면 둘 다 산다.
+         */
+        const STATE_FIELDS = ['generatedKW', 'exportKW', 'soc', 'chargeKW', 'dischargeKW', 'curtailable', 'minKW', 'position'];
+        const alsoState = STATE_FIELDS.filter(f => r?.[f] !== undefined);
+        if (alsoState.length) {
+            errors.push(`적산과 설비 상태를 한 레코드에 실었다(${alsoState.join('·')}) — 이 문은 적산만 읽으므로 그 값이 사라진다. 갈라 보낼 것`);
+        }
+        const raw = r?.kWh;
+        const kWh = Number(raw);
+        if (raw === undefined || raw === null || !Number.isFinite(kWh)) {
+            errors.push('kWh 가 없다 — 이 문이 받는 값은 적산 하나다(순시 출력은 설비 상태로 보낸다)');
+        }
+        else if (kWh < 0) {
+            /* 음수 적산은 계기가 낼 수 있는 값이 아니다. 받아 두면 그 뒤의 차분이 전부 거짓이 된다. */
+            errors.push(`kWh 가 음수다(${kWh}) — 적산은 뒤로 가더라도 음수가 되지 않는다`);
+        }
+        const eventTime = String(r?.at ?? '').trim() || opts.defaultEventTime || '';
+        if (!eventTime)
+            errors.push('at 이 없고 기본 시각도 주지 않았다 — 언제 잰 것인지 지어낼 수 없다');
+        /*
+         * 기준점은 **말했을 때만** 받는다. 형식이 틀리면 거부한다 — 못 읽는 기준점을 통과시키면 커널이
+         * 그것을 「기준점이 없다」로 읽고 다시 추론으로 떨어지는데, 커넥터는 알렸다고 믿는다.
+         */
+        let since;
+        const rawSince = r?.kWhSince;
+        if (rawSince !== undefined && rawSince !== null && String(rawSince).trim()) {
+            const text = String(rawSince).trim();
+            const at = Date.parse(text);
+            if (!Number.isFinite(at))
+                errors.push(`kWhSince 를 시각으로 읽을 수 없다: ${JSON.stringify(rawSince)}`);
+            else if (Number.isFinite(Date.parse(eventTime)) && at > Date.parse(eventTime)) {
+                /* 미래에서 쌓이기 시작한 적산은 없다 — 두 값 중 하나가 틀렸고, 어느 쪽인지 우리가 고를 수 없다. */
+                errors.push(`kWhSince(${text}) 가 잰 시각(${eventTime})보다 뒤다 — 둘 중 하나가 틀렸다`);
+            }
+            else
+                since = text;
+        }
+        /*
+         * 누적의 종류 — 아는 목록 밖의 값은 거부한다. 뭉개서 받으면 「모른다」와 「틀리게 말했다」가 같아진다.
+         */
+        const ACCUMULATIONS = ['lifetime', 'daily', 'monthly', 'billing', 'unknown'];
+        let accumulation;
+        const rawAcc = r?.kWhAccumulation;
+        if (rawAcc !== undefined && rawAcc !== null && String(rawAcc).trim()) {
+            const text = String(rawAcc).trim();
+            if (!ACCUMULATIONS.includes(text)) {
+                errors.push(`kWhAccumulation 이 아는 값이 아니다(${ACCUMULATIONS.join('·')}): ${JSON.stringify(rawAcc)}`);
+            }
+            else
+                accumulation = text;
+        }
+        if (errors.length) {
+            rejected.push({ record: r, errors });
+            continue;
+        }
+        const data = {
+            equipmentId,
+            kWh,
+            at: eventTime,
+            ...(since ? { since } : {}),
+            ...(accumulation ? { accumulation } : {})
+        };
+        accepted.push({
+            eventId: `${opts.tenantId}-generated-${++seq}`,
+            eventType: ENERGY_EVENT.generated,
+            eventTime,
+            tenantId: opts.tenantId,
+            data
+        });
+    }
+    return { accepted, rejected };
+}
+export function isEnergyUsagePeriodRecord(record) {
+    const r = record;
+    return !!r && typeof r === 'object' && r.meterId !== undefined && r.from !== undefined && r.to !== undefined && r.kWh !== undefined;
+}
+export function isEnergyGenerationPeriodRecord(record) {
+    const r = record;
+    if (!r || typeof r !== 'object')
+        return false;
+    if (r.equipmentId === undefined || r.from === undefined || r.to === undefined)
+        return false;
+    return r.kWh !== undefined;
+}
+/**
+ * 마감된 발전 기간을 봉투로 — **사건 시각은 기간의 끝**이다(그때 성립한다).
+ *
+ * 적산의 문(`ingestEnergyGenerationRecords`)과 겹치지 않는다: 그쪽은 구간이 없는 시점의 값이고
+ * 이쪽은 구간이 있는 마감된 사실이다. 겹치면 지난 기록이 「지금 적산」으로 읽혀 트윈의 시계가
+ * 과거로 끌린다.
+ */
+export function ingestEnergyGenerationPeriodRecords(records, opts) {
+    const list = records === undefined || records === null ? [] : Array.isArray(records) ? records : [records];
+    const accepted = [];
+    const rejected = [];
+    for (const r of list) {
+        const errors = [];
+        const equipmentId = String(r?.equipmentId ?? '').trim();
+        if (!equipmentId)
+            errors.push('equipmentId 가 없다 — 어느 설비가 낸 것인지 지어낼 수 없다');
+        const span = readSpan(r, errors);
+        const kWh = readAmount(r?.kWh, 'kWh', errors);
+        if (kWh === undefined && !errors.length)
+            errors.push('kWh 가 없다 — 이 문이 받는 값은 그 기간의 발전량이다');
+        const ACCUMULATIONS = ['lifetime', 'daily', 'monthly', 'billing', 'unknown'];
+        let accumulation;
+        const rawAcc = r?.accumulation;
+        if (rawAcc !== undefined && rawAcc !== null && String(rawAcc).trim()) {
+            const text = String(rawAcc).trim();
+            if (!ACCUMULATIONS.includes(text)) {
+                errors.push(`accumulation 이 아는 값이 아니다(${ACCUMULATIONS.join('·')}): ${JSON.stringify(rawAcc)}`);
+            }
+            else
+                accumulation = text;
+        }
+        /* 관측 구간은 기간 안에 있어야 한다 — 밖이면 그 값이 이 기간의 것이 아니다. */
+        const readAt = (raw, name) => {
+            if (raw === undefined || raw === null || !String(raw).trim())
+                return undefined;
+            const text = String(raw).trim();
+            if (!Number.isFinite(Date.parse(text))) {
+                errors.push(`${name} 를 시각으로 읽을 수 없다: ${JSON.stringify(raw)}`);
+                return undefined;
+            }
+            return text;
+        };
+        const observedFrom = readAt(r?.observedFrom, 'observedFrom');
+        const observedTo = readAt(r?.observedTo, 'observedTo');
+        if (errors.length || !span || kWh === undefined) {
+            rejected.push({ record: r, errors });
+            continue;
+        }
+        const data = {
+            equipmentId,
+            kWh,
+            periodStart: span.from,
+            periodEnd: span.to,
+            /* 관측 구간을 말하지 않으면 기간 전체를 잰 것으로 둔다 — 지난 기록은 그 원본이 하루를 마감해 준 값이다. */
+            observedFrom: observedFrom ?? span.from,
+            observedTo: observedTo ?? span.to,
+            accumulation: (accumulation ?? 'daily'),
+            /* 밖에서 마감되어 온 것이다 — 우리가 시각 기준으로 닫은 것이 아니다. */
+            boundary: 'declared'
+        };
+        const subj = resolveSubject('equipment', equipmentId, opts);
+        data.subject = subj.subject;
+        data.subjectBasis = subj.basis;
+        const futureError = futureFactError(span.to, opts);
+        if (futureError) {
+            rejected.push({ record: r, errors: [futureError] });
+            continue;
+        }
+        accepted.push({
+            eventId: periodFactId(opts.tenantId, ENERGY_EVENT.generationPeriod, subj.subject, span.from, span.to),
+            eventType: ENERGY_EVENT.generationPeriod,
+            eventTime: span.to,
+            tenantId: opts.tenantId,
+            data
+        });
+    }
+    return { accepted, rejected };
+}
+export function isEnergyGenerationPriceRecord(record) {
+    const r = record;
+    if (!r || typeof r !== 'object')
+        return false;
+    if (r.from === undefined || r.to === undefined)
+        return false;
+    /* 계량 지점·설비가 있으면 그 설비의 사실이지 단가가 아니다 — 문이 겹치지 않게. */
+    if (r.meterId !== undefined || r.equipmentId !== undefined)
+        return false;
+    return r.unitPrice !== undefined;
+}
+/**
+ * 발전 단가를 봉투로 — **사건 시각은 `from`** 이다(그때부터 적용된다).
+ *
+ * 제도의 가산·인증서 셈은 커넥터가 하고 여기에는 1kWh 당 얼마만 온다. 커널이 한 제도의 모양을
+ * 안으면 다른 제도에서 그 자리가 거짓이 된다.
+ */
+export function ingestEnergyGenerationPriceRecords(records, opts) {
+    const list = records === undefined || records === null ? [] : Array.isArray(records) ? records : [records];
+    const accepted = [];
+    const rejected = [];
+    for (const r of list) {
+        const errors = [];
+        const span = readSpan(r, errors);
+        const unitPrice = readAmount(r?.unitPrice, 'unitPrice', errors);
+        if (unitPrice === undefined && !errors.length)
+            errors.push('unitPrice 가 없다 — 이 문이 받는 값은 1kWh 당 값 하나다');
+        /* 단위 없는 값은 다른 금액과 더할 수 없다. */
+        const currency = String(r?.currency ?? '').trim();
+        if (!currency)
+            errors.push('currency 가 없다 — 단위 없는 값은 다른 금액과 더할 수 없다');
+        if (errors.length || !span || unitPrice === undefined) {
+            rejected.push({ record: r, errors });
+            continue;
+        }
+        const data = { from: span.from, to: span.to, unitPrice, currency };
+        accepted.push({
+            eventId: periodFactId(opts.tenantId, ENERGY_EVENT.generationPrice, '', span.from, span.to),
+            eventType: ENERGY_EVENT.generationPrice,
+            eventTime: span.from,
+            tenantId: opts.tenantId,
+            data
+        });
+    }
+    return { accepted, rejected };
+}
+export function isEnergyTariffBasisRecord(record) {
+    const r = record;
+    if (!r || typeof r !== 'object')
+        return false;
+    if (r.from === undefined || r.to === undefined)
+        return false;
+    /*
+     * ── 청구서와 배타로 (2026-08-29) ───────────────────────────────────────────
+     *
+     * 청구서가 요금적용전력을 함께 실으면 이 판별도 참이 됐다. 그때 이 문으로 가면 「금액은 받지
+     * 않는다」로 거부되어 **정산이 통째로 사라진다** — 거부는 되지만 그 사실을 잃는 것은 같다.
+     *
+     * 금액이 하나라도 있으면 그것은 정산이다. 기준은 금액을 싣지 않는다.
+     */
+    if (r.energyCharge !== undefined || r.demandCharge !== undefined || r.total !== undefined)
+        return false;
+    return r.billingDemandKW !== undefined || r.demandChargePerKW !== undefined;
+}
+/**
+ * 요금 기준을 봉투로 — **사건 시각은 `from`** 이다.
+ *
+ * 「이 시각부터 이 기준이 적용된다」이므로 주기가 끝나기 전에 성립한다. `to` 로 잡으면 아직 오지 않은
+ * 시각이 저널에 적힌다(실제로 그렇게 해서 9월 1일 사건이 8월 29일에 적힌 적이 있다).
+ */
+export function ingestEnergyTariffBasisRecords(records, opts) {
+    const list = records === undefined || records === null ? [] : Array.isArray(records) ? records : [records];
+    const accepted = [];
+    const rejected = [];
+    for (const r of list) {
+        const errors = [];
+        const span = readSpan(r, errors);
+        const billingDemandKW = readAmount(r?.billingDemandKW, 'billingDemandKW', errors);
+        const demandChargePerKW = readAmount(r?.demandChargePerKW, 'demandChargePerKW', errors);
+        if (billingDemandKW === undefined && demandChargePerKW === undefined) {
+            errors.push('요금 기준이 하나도 없다 — 적을 사실이 없는 기준은 받지 않는다');
+        }
+        /* 단가를 실었으면 통화가 있어야 한다 — 단위 없는 금액은 다른 금액과 더할 수 없다. */
+        const currency = String(r?.currency ?? '').trim() || undefined;
+        if (demandChargePerKW !== undefined && !currency)
+            errors.push('demandChargePerKW 를 실었는데 currency 가 없다');
+        /* 금액은 받지 않는다 — 두 값의 곱은 커널이 한다. 곱을 받으면 그것이 정산인 척한다. */
+        if (r?.demandCharge !== undefined || r?.total !== undefined) {
+            errors.push('금액(demandCharge·total)은 이 문이 받지 않는다 — 정산 금액은 청구서 문으로 보낸다');
+        }
+        if (errors.length || !span) {
+            rejected.push({ record: r, errors });
+            continue;
+        }
+        const data = {
+            from: span.from,
+            to: span.to,
+            ...(billingDemandKW !== undefined ? { billingDemandKW } : {}),
+            ...(demandChargePerKW !== undefined ? { demandChargePerKW } : {}),
+            ...(currency ? { currency } : {})
+        };
+        accepted.push({
+            eventId: periodFactId(opts.tenantId, ENERGY_EVENT.tariffBasis, '', span.from, span.to),
+            eventType: ENERGY_EVENT.tariffBasis,
+            /* **시작 시각**이다 — 그때부터 유효하다(§ 위 주석). */
+            eventTime: span.from,
+            tenantId: opts.tenantId,
+            data
+        });
+    }
+    return { accepted, rejected };
+}
+export function isEnergyBillRecord(record) {
+    const r = record;
+    if (!r || typeof r !== 'object')
+        return false;
+    if (r.from === undefined || r.to === undefined)
+        return false;
+    return r.energyCharge !== undefined || r.demandCharge !== undefined || r.total !== undefined;
+}
+/*
+ * ── 마감된 구간 사실의 **정체성** (2026-08-30) ───────────────────────────────
+ *
+ * 커널이 다루는 사실에는 두 종류가 있다.
+ *
+ *   시점의 관측    「이 시각에 이 값이었다」    같은 값이 두 번 오면 **두 사실**이다
+ *   마감된 구간    「이 기간에 이만큼이었다」   같은 기간이 두 번 오면 **한 사실**이다
+ *
+ * 둘째 종류는 정체성이 내용에 있다 — **종류·대상·시작·끝**이 같으면 같은 사실이다. 어느 커넥터가
+ * 어떻게 보내든, 재기동을 몇 번 하든 그렇다.
+ *
+ * 그래서 이 문들의 봉투 id 를 **순번이 아니라 내용에서** 만든다. 순번으로 만들면 같은 기간을 다시
+ * 보낼 때마다 다른 id 가 나오고, 읽는 쪽이 같은 사실인지 알 방법이 없다.
+ *
+ * **이것만으로 중복이 막히지는 않는다.** 저널은 아직 이 id 를 유일성으로 쓰지 않는다(그 판단은
+ * 호스트의 것이고 드라이버마다 다르다). 여기서 하는 일은 **막을 근거를 만드는 것**이다.
+ */
+/**
+ * 이 사실의 **주체를 무엇으로 부를까** — 선언이 있으면 그 이름, 없으면 이름표와 그 범위.
+ *
+ * 선언이 없을 때 트윈 범위를 이름에 넣는 이유는 **겹침을 숨기지 않기 위해서**다. 넣지 않으면 서로 다른
+ * 설비의 같은 날이 한 사실이 되고, 여러 현장을 함께 계산하는 곳에서 한쪽이 조용히 사라진다(실측).
+ * 넣되 `subjectBasis` 로 **이 이름이 트윈 안에서만 통한다**고 밝힌다 — 그릇으로 정한 이름을 고유한
+ * 척하지 않는다.
+ */
+/**
+ * **아직 오지 않은 시각의 사실은 받지 않는다.**
+ *
+ * ── 왜 필요한가 (2026-08-30) ──────────────────────────────────────────────
+ * 한 원본이 **끝나지 않은 이번 달**의 요금 정보를 청구서로 보냈다. 청구서의 사건 시각은 기간의 끝이라
+ * 그 사실이 **내일** 일어난 것으로 저널에 적혔다. 성과 계산은 「가장 늦은 사건」으로 구간을 잡으므로
+ * 구간 전체가 미래로 밀렸고, 그 현장의 화면에서 어제 발전량이 사라졌다. 오류는 하나도 나지 않았다.
+ *
+ * 지난 기록 채우기는 이미 이 판단을 하고 있었다(§`judgeBackfill`). 라이브 문에만 없어서 **한 종류에
+ * 규칙이 두 벌**이었다. 같은 사실이 어느 문으로 들어오느냐에 따라 받아지기도 하고 거절되기도 했다.
+ *
+ * ── 기준 선언은 이 판정을 받지 않는다 (2026-08-30, 두 번째 판단) ────────────
+ * 요금 기준·발전 단가는 **예정될 수 있다.** 한전은 다음 달 요금을 미리 공표하고, 공정 조건도 시행일을
+ * 앞두고 정해진다. 「9월부터 이 단가」는 오늘 성립하는 사실이다.
+ *
+ * 처음에는 이 둘도 거부했다. 그러면 정상적인 사실이 막힌다. 받되, **예정된 선언이 지금 것을 덮지 않게**
+ * 커널이 유효 구간으로 고른다(§`EnergyState.tariffBasisSchedule`). 받아 놓고 아무 데나 쓰면
+ * 오늘 요금이 다음 달 단가로 계산된다 — 그것이 이 문을 열기 전에 먼저 만들어야 했던 자리다.
+ */
+function futureFactError(eventTime, opts) {
+    const nowText = opts.nowISO ?? opts.defaultEventTime;
+    if (!nowText)
+        return undefined;
+    const nowMs = Date.parse(nowText);
+    const atMs = Date.parse(eventTime);
+    if (!Number.isFinite(nowMs) || !Number.isFinite(atMs) || atMs <= nowMs)
+        return undefined;
+    return `아직 오지 않은 시각의 사실이다(${eventTime}) — 끝나지 않은 기간은 마감된 사실이 아니다`;
+}
+export function resolveSubject(kind, localId, opts) {
+    const declared = opts.identityOf?.(kind, localId);
+    if (declared)
+        return { subject: declared, basis: 'declared' };
+    return { subject: opts.scopeId ? `${opts.scopeId}/${localId}` : localId, basis: 'twin-local' };
+}
+export function periodFactId(tenantId, kind, subject, from, to) {
+    /* 대상이 없는 사실(요금 기준·청구서·발전 단가)은 그 자리를 비운다 — 없는 것을 지어내지 않는다. */
+    return [tenantId, kind, subject, from, to].join('|');
+}
+/** 두 시각을 읽고 순서를 본다 — 뒤집힌 구간은 받지 않는다(합이 음수가 된다). */
+function readSpan(r, errors) {
+    const from = String(r?.from ?? '').trim();
+    const to = String(r?.to ?? '').trim();
+    const fromMs = Date.parse(from);
+    const toMs = Date.parse(to);
+    if (!from || !Number.isFinite(fromMs))
+        errors.push(`from 을 시각으로 읽을 수 없다: ${JSON.stringify(r?.from)}`);
+    if (!to || !Number.isFinite(toMs))
+        errors.push(`to 를 시각으로 읽을 수 없다: ${JSON.stringify(r?.to)}`);
+    if (Number.isFinite(fromMs) && Number.isFinite(toMs) && !(toMs > fromMs)) {
+        errors.push(`구간이 뒤집혔거나 길이가 없다(${from} → ${to}) — 어느 쪽이 틀렸는지 우리가 정할 수 없다`);
+    }
+    return errors.length ? undefined : { from, to };
+}
+/** 0 이상의 수 하나 — 없으면 `undefined`, 값인데 읽을 수 없으면 오류. */
+function readAmount(raw, name, errors) {
+    if (raw === undefined || raw === null || String(raw).trim() === '')
+        return undefined;
+    const v = Number(raw);
+    if (!Number.isFinite(v)) {
+        errors.push(`${name} 를 수로 읽을 수 없다: ${JSON.stringify(raw)}`);
+        return undefined;
+    }
+    if (v < 0) {
+        errors.push(`${name} 가 음수다(${v})`);
+        return undefined;
+    }
+    return v;
+}
+export function ingestEnergyUsagePeriodRecords(records, opts) {
+    const list = records === undefined || records === null ? [] : Array.isArray(records) ? records : [records];
+    const accepted = [];
+    const rejected = [];
+    for (const r of list) {
+        const errors = [];
+        const meterId = String(r?.meterId ?? '').trim();
+        if (!meterId)
+            errors.push('meterId 가 없다 — 어느 지점이 쓴 것인지 지어낼 수 없다');
+        const span = readSpan(r, errors);
+        const rawKWh = r?.kWh;
+        let kWh;
+        if (rawKWh === undefined || rawKWh === null || String(rawKWh).trim() === '') {
+            errors.push('kWh 가 없다 — 이 문이 받는 값은 그 구간에 쓴 양이다');
+        }
+        else {
+            kWh = readAmount(rawKWh, 'kWh', errors);
+        }
+        const maxKW = readAmount(r?.maxKW, 'maxKW', errors);
+        const unitPrice = readAmount(r?.unitPrice, 'unitPrice', errors);
+        /* 단가를 실었으면 통화도 있어야 한다 — 단위 없는 금액은 다른 값과 더할 수 없다. */
+        const currency = String(r?.currency ?? '').trim() || undefined;
+        if (unitPrice !== undefined && !currency)
+            errors.push('unitPrice 를 실었는데 currency 가 없다 — 단위 없는 금액은 더할 수 없다');
+        /* 근거는 아는 목록 안에서만 — 모르는 값을 받으면 화면이 그것을 근거로 말한다. */
+        let basis;
+        const rawBasis = r?.basis;
+        if (rawBasis !== undefined && rawBasis !== null && String(rawBasis).trim()) {
+            const text = String(rawBasis).trim();
+            if (!OBSERVATION_BASIS.includes(text)) {
+                errors.push(`basis 가 아는 값이 아니다(${OBSERVATION_BASIS.join('·')}): ${JSON.stringify(rawBasis)}`);
+            }
+            else
+                basis = text;
+        }
+        if (errors.length || !span || kWh === undefined) {
+            rejected.push({ record: r, errors });
+            continue;
+        }
+        const subj = resolveSubject('meter', meterId, opts);
+        const data = {
+            meterId,
+            subject: subj.subject,
+            subjectBasis: subj.basis,
+            from: span.from,
+            to: span.to,
+            kWh,
+            ...(maxKW !== undefined ? { maxKW } : {}),
+            ...(unitPrice !== undefined ? { unitPrice } : {}),
+            ...(currency ? { currency } : {}),
+            ...(basis ? { basis } : {})
+        };
+        const futureError = futureFactError(span.to, opts);
+        if (futureError) {
+            rejected.push({ record: r, errors: [futureError] });
+            continue;
+        }
+        accepted.push({
+            eventId: periodFactId(opts.tenantId, ENERGY_EVENT.usagePeriod, subj.subject, span.from, span.to),
+            eventType: ENERGY_EVENT.usagePeriod,
+            /* 구간의 **끝**이 이 사실이 성립한 시각이다 — 시작으로 달면 저널이 그 구간을 미리 안 것이 된다. */
+            eventTime: span.to,
+            tenantId: opts.tenantId,
+            data
+        });
+    }
+    return { accepted, rejected };
+}
+export function ingestEnergyBillRecords(records, opts) {
+    const list = records === undefined || records === null ? [] : Array.isArray(records) ? records : [records];
+    const accepted = [];
+    const rejected = [];
+    for (const r of list) {
+        const errors = [];
+        const span = readSpan(r, errors);
+        const energyCharge = readAmount(r?.energyCharge, 'energyCharge', errors);
+        const demandCharge = readAmount(r?.demandCharge, 'demandCharge', errors);
+        const total = readAmount(r?.total, 'total', errors);
+        const billingDemandKW = readAmount(r?.billingDemandKW, 'billingDemandKW', errors);
+        if (energyCharge === undefined && demandCharge === undefined && total === undefined) {
+            errors.push('금액이 하나도 없다 — 적을 사실이 없는 청구서는 받지 않는다');
+        }
+        /* 금액을 실었으면 통화가 있어야 한다. 없으면 그 수는 다른 수와 더할 수 없다. */
+        const currency = String(r?.currency ?? '').trim() || undefined;
+        if (!currency)
+            errors.push('currency 가 없다 — 단위 없는 금액은 다른 금액과 더할 수 없다');
+        /*
+         * 합계가 부분들과 다른 것은 **거부하지 않는다.** 세금·역률 요금·최소 청구액처럼 우리가 세지 않는
+         * 항목이 청구서에 있을 수 있다. 그 차이는 사실이고, 읽는 쪽이 그것을 보고 판단한다.
+         */
+        if (errors.length || !span) {
+            rejected.push({ record: r, errors });
+            continue;
+        }
+        const data = {
+            from: span.from,
+            to: span.to,
+            ...(energyCharge !== undefined ? { energyCharge } : {}),
+            ...(demandCharge !== undefined ? { demandCharge } : {}),
+            ...(total !== undefined ? { total } : {}),
+            ...(currency ? { currency } : {}),
+            ...(billingDemandKW !== undefined ? { billingDemandKW } : {})
+        };
+        const futureError = futureFactError(span.to, opts);
+        if (futureError) {
+            rejected.push({ record: r, errors: [futureError] });
+            continue;
+        }
+        accepted.push({
+            eventId: periodFactId(opts.tenantId, ENERGY_EVENT.bill, '', span.from, span.to),
+            eventType: ENERGY_EVENT.bill,
+            eventTime: span.to,
+            tenantId: opts.tenantId,
+            data
+        });
+    }
+    return { accepted, rejected };
+}