@operato/twin-kernel 0.7.17 → 0.7.18

package/dist/ems-profile.d.ts

@@ -37,8 +37,33 @@ export declare const EMS_PROPERTY: {
      * 「SOC 를 모르면 방전하지 않는다」는 규율에 걸려 **배터리가 아무 일도 하지 못했다** — 정책을 선언해도
      * 피크가 한 톨도 깎이지 않았다(실화면에서 그렇게 났다).
      *
-     * 이것은 상태의 씨앗이지 계측이 아니다. 그래서 계측이 들어오는 순간 그것이 이깁니다.
+     * 이것은 상태의 씨앗이지 계측이 아니다. 그래서 계측이 들어오는 순간 그것이 이긴다.
      */
     readonly initialSoc: "storage.initialSoc";
 };
+/**
+ * 이 선언들의 **단위와 범위** — 값을 읽는 쪽이 아니라 **주는 쪽**을 위한 표다.
+ *
+ * ── 왜 커널이 단위를 말해야 하나 (2026-08-17) ────────────────────────────────
+ * 사용자가 「현재 SOC 80%」라고 말했고, 저작 AI 는 `storage.initialSoc = 0.8` 을 썼다. 커널은 이 값을
+ * **퍼센트**로 읽으므로(`(soc - reserve) / 100`) 그 배터리는 0.8% 로 선언됐다 — 쓸 수 있는 에너지가
+ * 사실상 없는 상태이고, **경고 하나 없이** 그렇게 됐다. 실화면에서 그렇게 났다.
+ *
+ * 잘못은 값을 준 쪽이 아니라 **단위를 말하지 않은 쪽**에 있다. 타입을 지어내지 못하게 카탈로그를 주면서
+ * 속성은 id 만 줬으니, 값을 만드는 쪽은 단위를 짐작할 수밖에 없었다.
+ *
+ * 표를 커널에 두는 이유: 이 단위는 **커널의 셈법이 정하는 것**이다(퍼센트로 나누는 코드가 여기 있다).
+ * 소비처마다 적으면 두 벌이 되고, 두 벌은 갈라진다 — 갈라지는 순간 이 결함이 그대로 돌아온다.
+ */
+export interface EmsPropertySpec {
+    /** 단위 — 사람이 읽는 표기(kW·kWh·% 등). 무차원이면 없다. */
+    uom?: string;
+    /** 값의 종류 — GS1 dataType 표기(`xs:double`·`xs:string`). */
+    dataType: 'xs:double' | 'xs:string';
+    /** 허용 범위 [min, max] — 밖의 값은 받는 쪽이 거절할 수 있다(있는 것만 적는다). */
+    range?: [number, number];
+    /** 무엇을 뜻하나 — 영어 canonical(표현 계층이 사용자 언어로 옮긴다). */
+    note: string;
+}
+export declare const EMS_PROPERTY_SPEC: Record<string, EmsPropertySpec>;
 export declare const EMS_TYPES: TwinTypeInfo[];

package/dist/ems-profile.js

@@ -69,10 +69,24 @@ export const EMS_PROPERTY = {
      * 「SOC 를 모르면 방전하지 않는다」는 규율에 걸려 **배터리가 아무 일도 하지 못했다** — 정책을 선언해도
      * 피크가 한 톨도 깎이지 않았다(실화면에서 그렇게 났다).
      *
-     * 이것은 상태의 씨앗이지 계측이 아니다. 그래서 계측이 들어오는 순간 그것이 이깁니다.
+     * 이것은 상태의 씨앗이지 계측이 아니다. 그래서 계측이 들어오는 순간 그것이 이긴다.
      */
     initialSoc: 'storage.initialSoc'
 };
+export const EMS_PROPERTY_SPEC = {
+    [EMS_PROPERTY.contractKW]: { uom: 'kW', dataType: 'xs:double', note: 'contracted power at the metering point, in kW.' },
+    [EMS_PROPERTY.ratedKW]: { uom: 'kW', dataType: 'xs:double', note: 'power drawn while running, in kW.' },
+    [EMS_PROPERTY.standbyKW]: { uom: 'kW', dataType: 'xs:double', note: 'power drawn while idle, in kW.' },
+    [EMS_PROPERTY.demandChargePerKW]: { dataType: 'xs:double', note: 'demand charge per kW of billing-period peak, in the declared currency.' },
+    [EMS_PROPERTY.energyChargePerKWh]: { dataType: 'xs:double', note: 'energy charge per kWh, in the declared currency.' },
+    [EMS_PROPERTY.currency]: { dataType: 'xs:string', note: 'ISO 4217 currency code, e.g. USD or KRW.' },
+    [EMS_PROPERTY.capacityKWh]: { uom: 'kWh', dataType: 'xs:double', note: 'usable energy of the storage, in kWh.' },
+    [EMS_PROPERTY.dischargeAboveKW]: { uom: 'kW', dataType: 'xs:double', note: 'net demand above which the storage discharges, in kW.' },
+    [EMS_PROPERTY.maxDischargeKW]: { uom: 'kW', dataType: 'xs:double', note: 'inverter limit on discharge rate, in kW.' },
+    /* 퍼센트다 — 0.8 은 0.8% 이고 80% 가 아니다. 이 한 줄이 없어서 배터리가 조용히 비어 있었다. */
+    [EMS_PROPERTY.reserveSoc]: { uom: '%', dataType: 'xs:double', range: [0, 100], note: 'reserve state of charge as a percentage 0-100 (20 means 20%), never discharged below.' },
+    [EMS_PROPERTY.initialSoc]: { uom: '%', dataType: 'xs:double', range: [0, 100], note: 'starting state of charge as a percentage 0-100 (80 means 80%, not 0.8).' }
+};
 export const EMS_TYPES = [
     /* ── 자리: 전기적 구간 ─────────────────────────────────────────────────── */
     {

package/dist-cjs/index.cjs

@@ -34,6 +34,7 @@ __export(index_exports, {
   EMS_EQUIPMENT_TYPES: () => EMS_EQUIPMENT_TYPES,
   EMS_LOCATION_TYPES: () => EMS_LOCATION_TYPES,
   EMS_PROPERTY: () => EMS_PROPERTY,
+  EMS_PROPERTY_SPEC: () => EMS_PROPERTY_SPEC,
   EMS_TYPES: () => EMS_TYPES,
   ENERGY_EVENT: () => ENERGY_EVENT,
   EPCIS_CONTEXT: () => EPCIS_CONTEXT,
@@ -1733,10 +1734,24 @@ var EMS_PROPERTY = {
    * 「SOC 를 모르면 방전하지 않는다」는 규율에 걸려 **배터리가 아무 일도 하지 못했다** — 정책을 선언해도
    * 피크가 한 톨도 깎이지 않았다(실화면에서 그렇게 났다).
    *
-   * 이것은 상태의 씨앗이지 계측이 아니다. 그래서 계측이 들어오는 순간 그것이 이깁니다.
+   * 이것은 상태의 씨앗이지 계측이 아니다. 그래서 계측이 들어오는 순간 그것이 이긴다.
    */
   initialSoc: "storage.initialSoc"
 };
+var EMS_PROPERTY_SPEC = {
+  [EMS_PROPERTY.contractKW]: { uom: "kW", dataType: "xs:double", note: "contracted power at the metering point, in kW." },
+  [EMS_PROPERTY.ratedKW]: { uom: "kW", dataType: "xs:double", note: "power drawn while running, in kW." },
+  [EMS_PROPERTY.standbyKW]: { uom: "kW", dataType: "xs:double", note: "power drawn while idle, in kW." },
+  [EMS_PROPERTY.demandChargePerKW]: { dataType: "xs:double", note: "demand charge per kW of billing-period peak, in the declared currency." },
+  [EMS_PROPERTY.energyChargePerKWh]: { dataType: "xs:double", note: "energy charge per kWh, in the declared currency." },
+  [EMS_PROPERTY.currency]: { dataType: "xs:string", note: "ISO 4217 currency code, e.g. USD or KRW." },
+  [EMS_PROPERTY.capacityKWh]: { uom: "kWh", dataType: "xs:double", note: "usable energy of the storage, in kWh." },
+  [EMS_PROPERTY.dischargeAboveKW]: { uom: "kW", dataType: "xs:double", note: "net demand above which the storage discharges, in kW." },
+  [EMS_PROPERTY.maxDischargeKW]: { uom: "kW", dataType: "xs:double", note: "inverter limit on discharge rate, in kW." },
+  /* 퍼센트다 — 0.8 은 0.8% 이고 80% 가 아니다. 이 한 줄이 없어서 배터리가 조용히 비어 있었다. */
+  [EMS_PROPERTY.reserveSoc]: { uom: "%", dataType: "xs:double", range: [0, 100], note: "reserve state of charge as a percentage 0-100 (20 means 20%), never discharged below." },
+  [EMS_PROPERTY.initialSoc]: { uom: "%", dataType: "xs:double", range: [0, 100], note: "starting state of charge as a percentage 0-100 (80 means 80%, not 0.8)." }
+};
 var EMS_TYPES = [
   /* ── 자리: 전기적 구간 ─────────────────────────────────────────────────── */
   {
@@ -6782,6 +6797,7 @@ function retiredVocabularyIn(line) {
   EMS_EQUIPMENT_TYPES,
   EMS_LOCATION_TYPES,
   EMS_PROPERTY,
+  EMS_PROPERTY_SPEC,
   EMS_TYPES,
   ENERGY_EVENT,
   EPCIS_CONTEXT,

package/package.json

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