@operato/twin-kernel 0.7.0 → 0.7.2

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`).
@@ -5554,6 +5628,45 @@ var EmsKernel = class extends FlowEngine {
     }
     return max;
   }
+  /**
+   * **뿌리 계량기** — 조상 중에 계량된 자리가 없는 계량 지점들.
+   *
+   * 계층 계량(수전 ⊃ 분기)에서 전부 더하면 이중 계상이 된다. 뿌리만 더하면 현장의 실제 부하가 된다.
+   * 모델이 그 계량기의 자리를 모르면 뿌리로 본다(모르는 것을 빼면 부하가 조용히 작아진다 — 그것이
+   * 「계약 안쪽」이라는 더 위험한 거짓을 만든다).
+   */
+  rootMeterIds() {
+    const locOf = /* @__PURE__ */ new Map();
+    for (const e of this.boardDef?.equipment ?? []) locOf.set(e.id, e.homeLocation);
+    const parentOf = /* @__PURE__ */ new Map();
+    for (const l of this.boardDef?.locations ?? []) parentOf.set(l.id, l.parentId);
+    const meteredLocs = /* @__PURE__ */ new Set();
+    for (const id of this.points.keys()) {
+      const loc = locOf.get(id);
+      if (loc) meteredLocs.add(loc);
+    }
+    const out = /* @__PURE__ */ new Set();
+    for (const id of this.points.keys()) {
+      const loc = locOf.get(id);
+      if (!loc) {
+        out.add(id);
+        continue;
+      }
+      let cur = parentOf.get(loc);
+      let root = true;
+      const seen = /* @__PURE__ */ new Set([loc]);
+      while (cur && !seen.has(cur)) {
+        if (meteredLocs.has(cur)) {
+          root = false;
+          break;
+        }
+        seen.add(cur);
+        cur = parentOf.get(cur);
+      }
+      if (root) out.add(id);
+    }
+    return out;
+  }
   /**
    * 계측 표본을 받는다 — 에너지 사건만 가로채고 나머지는 그대로 상위에 넘긴다.
    *
@@ -5587,7 +5700,8 @@ var EmsKernel = class extends FlowEngine {
     this.points.set(id, point);
     const w = this.open;
     if (kW !== void 0) {
-      const total = [...this.points.values()].reduce((sum, p) => sum + (p.kW ?? 0), 0);
+      const roots = this.rootMeterIds();
+      const total = [...this.points.values()].reduce((sum, p) => sum + (roots.has(p.id) ? p.kW ?? 0 : 0), 0);
       if (w.maxKW === void 0 || total > w.maxKW) w.maxKW = total;
       w.samples++;
       w.meanKW = w.meanKW === void 0 ? total : (w.meanKW * (w.samples - 1) + total) / w.samples;
@@ -5733,6 +5847,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 +6154,7 @@ function retiredVocabularyIn(line) {
   activeShiftOf,
   aggregationEvent,
   analyzeCapacity,
+  attributeEnergy,
   axesOfSystem,
   axisAppliesTo,
   axisInfo,
@@ -5852,6 +6172,8 @@ function retiredVocabularyIn(line) {
   documentPath,
   dueStatusOf,
   effectivityAt,
+  energyIntensity,
+  energyOfWindows,
   fefoPolicy,
   firstFitPolicy,
   foldJobResponses,
@@ -5862,6 +6184,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.2",
   "type": "module",
   "description": "Twin Domain Kernel — framework-agnostic, zero-dep (domain + sim + 3-channel contract). WMS/YMS/MES, EPCIS 2.0 · ISA-95.",
   "publishConfig": {