@operato/twin-kernel 0.7.84 → 0.7.86

package/dist/contract.d.ts

@@ -2743,6 +2743,27 @@ export interface EnergyMeasuredData {
  * 않은 것이다. 태양광이면 대개 0 이지만 그것은 현장이 판단할 일이고, 재지 않은 것을 0 으로 적으면
  * 우리가 그 판단을 대신한 것이 된다.
  */
+/**
+ * 사실의 **주체를 무엇으로 불렀나** — 그 이름이 어디까지 통하는지가 여기서 갈린다.
+ *
+ * ── 왜 이 축이 필요한가 (2026-08-30) ──────────────────────────────────────
+ * 마감된 구간 사실은 정체성이 내용에 있다(종류·주체·시작·끝). 그런데 **주체를 설비 번호로 불렀다.**
+ * 설비 번호는 한 트윈 안에서만 통하는 이름표라, 한 도메인에 현장이 둘이면 서로 다른 설비의 같은 날이
+ * **한 사실**이 된다. 실측으로 그 일이 났다 — 두 발전소의 `002` 가 겹쳐, 여러 현장을 함께 계산하는
+ * 성과 화면에서 한쪽 발전량이 사라졌다.
+ *
+ * 고치는 방법은 두 가지였고 하나는 틀렸다. **트윈 id 를 이름에 붙이는 것은 그릇으로 정체성을 정하는
+ * 것**이라 원칙을 뒤집는다(같은 설비를 현장 트윈과 상위 집계 트윈에 두면 같은 날이 두 사실이 된다).
+ *
+ * 그래서 이름의 출처를 밝힌다.
+ *
+ *   declared    모델이 선언한 설비 정체성 — 그릇과 무관하게 고유하다
+ *   twin-local  선언이 없어 이름표를 그대로 썼다 — **이 트윈 안에서만 통한다**
+ *
+ * 커널은 없는 이름을 지어내지 않고, 겹치는 이름을 고유한 척하지도 않는다. 읽는 쪽은 `twin-local` 을
+ * 볼 때 트윈 밖에서 같다고 판정하면 안 된다.
+ */
+export type SubjectBasis = 'declared' | 'twin-local';
 export interface EnergyGenerationPeriodData {
     equipmentId: string;
     /** 이 기간에 만든 양(kWh). */
@@ -2756,6 +2777,9 @@ export interface EnergyGenerationPeriodData {
     accumulation: 'lifetime' | 'daily' | 'monthly' | 'billing';
     /** 기간의 경계가 어디서 왔나 — 원본의 기준점(`declared`)이거나 현장의 시각 기준(`offset`). */
     boundary: 'declared' | 'offset';
+    /** 이 사실이 무엇에 대한 것인가 — 정체성으로 부른 이름(§`SubjectBasis`). */
+    subject?: string;
+    subjectBasis?: SubjectBasis;
 }
 /**
  * 값이 어디서 왔나 — **관측의 근거**.
@@ -2786,6 +2810,9 @@ export interface EnergyUsagePeriodData {
     unitPrice?: number;
     currency?: string;
     basis?: ObservationBasis;
+    /** 이 사실이 무엇에 대한 것인가 — 계량 지점도 설비와 같은 문제를 갖는다(§`SubjectBasis`). */
+    subject?: string;
+    subjectBasis?: SubjectBasis;
 }
 /**
  * 청구서 — `ENERGY_EVENT.bill` 의 데이터.
@@ -3104,6 +3131,7 @@ export interface TwinModelDef {
         id: string;
         kind: string;
         homeLocation: string;
+        identity?: string;
         mtbfMs?: number;
         mttrMs?: number;
         window?: {

package/dist/ems-kernel.js

@@ -26,6 +26,8 @@
  *    **관측 시작 이후 최대**만 답하고 그 사실을 이름으로 말한다(`peakSince`). 지어내지 않는다.
  */
 import { FlowEngine } from "./flow-engine.js";
+/* 기간 사실의 이름은 유입 문과 한 규칙이다(§`periodFactId`). */
+import { periodFactId } from "./energy-ingest.js";
 import { firstFitPolicy } from "./allocation-policy.js";
 import { CMD, ENERGY_EVENT, minuteOfDayAt, localDayIndexAt, localDayStartMs } from "./contract.js";
 import { EMS_PROPERTY, METER_DIRECTION, electricalUpstreamOf, generationFractionAt } from "./ems-profile.js";
@@ -659,16 +661,27 @@ export class EmsKernel extends FlowEngine {
          */
         const total = obs.lastKWh;
         if (Number.isFinite(total) && total >= 0) {
-            this.emitOp(ENERGY_EVENT.generationPeriod, {
+            /*
+             * 이름을 **내용에서** 만든다 — 같은 하루를 커널이 닫은 것과 커넥터가 지난 기록으로 보낸 것이
+             * 한 사실이어야 한다(§`emitPeriodFact`).
+             */
+            const periodStart = new Date(startMs).toISOString();
+            const periodEnd = new Date(endMs).toISOString();
+            const subj = this.subjectOf('equipment', id);
+            this.emitPeriodFact(ENERGY_EVENT.generationPeriod, {
                 equipmentId: id,
                 kWh: total,
-                periodStart: new Date(startMs).toISOString(),
-                periodEnd: new Date(endMs).toISOString(),
+                periodStart,
+                periodEnd,
                 observedFrom: new Date(obs.fromMs).toISOString(),
                 observedTo: new Date(obs.lastMs).toISOString(),
                 accumulation: at.kind,
-                boundary
-            });
+                boundary,
+                subject: subj.subject,
+                subjectBasis: subj.basis
+            }, periodFactId(this.tenantId, ENERGY_EVENT.generationPeriod, subj.subject, periodStart, periodEnd), 
+            /* 이 사실이 성립한 것은 기간의 끝이다 — 우리가 계산한 시각이 아니다. */
+            periodEnd);
             eq.generatedKWhLastPeriod = total;
             eq.generatedKWhLastPeriodEnd = new Date(endMs).toISOString();
             /* 상태만 읽는 화면이 덜 잰 값을 온전한 값으로 읽지 않게, 관측 구간을 함께 남긴다. */

package/dist/energy-ingest.d.ts

@@ -20,6 +20,21 @@ export interface EnergyIngestOptions {
     tenantId: string;
     /** 레코드에 시각이 없을 때 쓸 값 — **주지 않으면 그 레코드를 거부한다.** */
     defaultEventTime?: string;
+    /**
+     * 자원의 **선언된 정체성**을 답한다 — 없으면 `undefined`.
+     *
+     * 마감된 구간 사실의 이름에 들어갈 주체를 이것으로 정한다(§`SubjectBasis`). 커널이 이름을
+     * 지어내지 않는 것과 같은 자세다: 모델이 선언하지 않았으면 답하지 않고, 호출부가 무엇을 할지 정한다.
+     */
+    identityOf?: (kind: 'equipment' | 'meter', localId: string) => string | undefined;
+    /**
+     * 선언된 정체성이 없을 때 이름표가 **어디까지 통하는지** — 보통 이 트윈의 id.
+     *
+     * 이름에 넣는 것이 아니라 **범위를 밝히는 데** 쓴다. 이것이 있으면 사실은 `twin-local` 로 표시되고,
+     * 읽는 쪽은 그 이름을 트윈 밖에서 같다고 판정하지 않는다. 주지 않으면 범위를 모르는 것이므로
+     * 그때도 `twin-local` 이되 범위는 비어 있다.
+     */
+    scopeId?: string;
 }
 export interface EnergyIngestResult {
     accepted: CanonicalEnvelope[];
@@ -185,5 +200,18 @@ export interface EnergyBillRecord {
     billingDemandKW?: number;
 }
 export declare function isEnergyBillRecord(record: unknown): boolean;
+/**
+ * 이 사실의 **주체를 무엇으로 부를까** — 선언이 있으면 그 이름, 없으면 이름표와 그 범위.
+ *
+ * 선언이 없을 때 트윈 범위를 이름에 넣는 이유는 **겹침을 숨기지 않기 위해서**다. 넣지 않으면 서로 다른
+ * 설비의 같은 날이 한 사실이 되고, 여러 현장을 함께 계산하는 곳에서 한쪽이 조용히 사라진다(실측).
+ * 넣되 `subjectBasis` 로 **이 이름이 트윈 안에서만 통한다**고 밝힌다 — 그릇으로 정한 이름을 고유한
+ * 척하지 않는다.
+ */
+export declare function resolveSubject(kind: 'equipment' | 'meter', localId: string, opts: EnergyIngestOptions): {
+    subject: string;
+    basis: 'declared' | 'twin-local';
+};
+export declare function periodFactId(tenantId: string, kind: string, subject: string, from: string, to: string): string;
 export declare function ingestEnergyUsagePeriodRecords(records: EnergyUsagePeriodRecord | EnergyUsagePeriodRecord[] | undefined | null, opts: EnergyIngestOptions): EnergyIngestResult;
 export declare function ingestEnergyBillRecords(records: EnergyBillRecord | EnergyBillRecord[] | undefined | null, opts: EnergyIngestOptions): EnergyIngestResult;

package/dist/energy-ingest.js

@@ -449,8 +449,11 @@ export function ingestEnergyGenerationPeriodRecords(records, opts) {
             /* 밖에서 마감되어 온 것이다 — 우리가 시각 기준으로 닫은 것이 아니다. */
             boundary: 'declared'
         };
+        const subj = resolveSubject('equipment', equipmentId, opts);
+        data.subject = subj.subject;
+        data.subjectBasis = subj.basis;
         accepted.push({
-            eventId: periodFactId(opts.tenantId, ENERGY_EVENT.generationPeriod, equipmentId, span.from, span.to),
+            eventId: periodFactId(opts.tenantId, ENERGY_EVENT.generationPeriod, subj.subject, span.from, span.to),
             eventType: ENERGY_EVENT.generationPeriod,
             eventTime: span.to,
             tenantId: opts.tenantId,
@@ -596,7 +599,21 @@ export function isEnergyBillRecord(record) {
  * **이것만으로 중복이 막히지는 않는다.** 저널은 아직 이 id 를 유일성으로 쓰지 않는다(그 판단은
  * 호스트의 것이고 드라이버마다 다르다). 여기서 하는 일은 **막을 근거를 만드는 것**이다.
  */
-function periodFactId(tenantId, kind, subject, from, to) {
+/**
+ * 이 사실의 **주체를 무엇으로 부를까** — 선언이 있으면 그 이름, 없으면 이름표와 그 범위.
+ *
+ * 선언이 없을 때 트윈 범위를 이름에 넣는 이유는 **겹침을 숨기지 않기 위해서**다. 넣지 않으면 서로 다른
+ * 설비의 같은 날이 한 사실이 되고, 여러 현장을 함께 계산하는 곳에서 한쪽이 조용히 사라진다(실측).
+ * 넣되 `subjectBasis` 로 **이 이름이 트윈 안에서만 통한다**고 밝힌다 — 그릇으로 정한 이름을 고유한
+ * 척하지 않는다.
+ */
+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('|');
 }
@@ -669,8 +686,11 @@ export function ingestEnergyUsagePeriodRecords(records, opts) {
             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,
@@ -680,7 +700,7 @@ export function ingestEnergyUsagePeriodRecords(records, opts) {
             ...(basis ? { basis } : {})
         };
         accepted.push({
-            eventId: periodFactId(opts.tenantId, ENERGY_EVENT.usagePeriod, meterId, span.from, span.to),
+            eventId: periodFactId(opts.tenantId, ENERGY_EVENT.usagePeriod, subj.subject, span.from, span.to),
             eventType: ENERGY_EVENT.usagePeriod,
             /* 구간의 **끝**이 이 사실이 성립한 시각이다 — 시작으로 달면 저널이 그 구간을 미리 안 것이 된다. */
             eventTime: span.to,

package/dist/flow-engine.d.ts

@@ -1282,6 +1282,43 @@ export declare abstract class FlowEngine implements TwinKernel {
      */
     private _correlationId?;
     protected emit(event: EpcisEvent): void;
+    /**
+     * **마감된 구간 사실**을 낸다 — 이름을 내용에서 만든다(순번이 아니다).
+     *
+     * ── 왜 따로 있나 (2026-08-30) ────────────────────────────────────────────
+     * `emitOp` 은 이름을 순번으로 붙인다(`…-evt-3`). 관측이나 전이는 그래도 된다 — 두 번 일어나면 두
+     * 사실이다. 그런데 **마감된 구간은 같은 기간이면 한 사실이다.** 같은 하루를 커널이 자정에 닫고
+     * 커넥터가 지난 기록으로도 보내면, 순번 이름으로는 그 둘이 다른 사실이 되어 **발전량이 두 배로**
+     * 잡힌다. 유입 문은 이미 내용으로 이름을 짓고 있었는데(§`periodFactId`) 커널 자신만 아니었다 —
+     * 한 종류에 규칙이 두 벌이었다.
+     *
+     * ── 시각도 내용에서 온다 ─────────────────────────────────────────────────
+     * `emitOp` 은 **지금**을 찍는다. 마감된 구간에 그것을 찍으면 「우리가 언제 계산했나」가 되고, 재기동이
+     * 늦으면 어제의 사실이 오늘 시각을 갖는다. 실제로 그렇게 났다 — 부팅에서 닫힌 8월 29일치가 22:24 를
+     * 달고 나왔고, 시각 구간으로 읽는 중복 판정이 그것을 못 봐서 같은 하루가 12줄이 되었다(이름은 6개).
+     *
+     * 이 사실이 성립하는 것은 **기간의 끝**이다. 유입 문도 그 시각을 찍는다.
+     */
+    protected emitPeriodFact(eventType: string, data: unknown, eventId: string, eventTime: string): void;
+    /**
+     * 이 트윈의 **범위 이름** — 선언된 정체성이 없을 때 이름표가 어디까지 통하는지(§`SubjectBasis`).
+     *
+     * 호스트가 세운다. 커널은 `new Kernel(domainId, …)` 으로 서므로 **자기가 어느 트윈인지 모른다** —
+     * 도메인에 현장이 둘이면 설비 번호가 겹치는데 커널만으로는 그것을 알 길이 없었다.
+     */
+    scopeId?: string;
+    /**
+     * 설비의 **선언된 정체성** — 모델이 적었으면 그 이름, 없으면 답하지 않는다.
+     *
+     * 물품과 같은 자세다(§`declaredObjectId`): 선언이 없으면 지어내지 않는다. 명시한 이름이 먼저이고,
+     * 없으면 선언된 이름공간 아래의 개체 식별자로 만든다(CBV §8.2.3·§8.2.4).
+     */
+    equipmentIdentity(equipmentId: string): string | undefined;
+    /** 유입 문과 **같은 규칙**으로 주체를 정한다 — 이름 짓는 자리가 둘이면 한쪽만 고쳐지는 날이 온다. */
+    protected subjectOf(kind: 'equipment' | 'meter', localId: string): {
+        subject: string;
+        basis: 'declared' | 'twin-local';
+    };
     protected emitOp(eventType: string, data: unknown): void;
     /**
      * 작업 전이 방출 — **커널이 아는 것을 미러도 알게** 한다.

package/dist/flow-engine.js

@@ -11,6 +11,8 @@
  */
 import { OP_EVENT, CMD, locationStatusOf, readBoardEquipment, readBoardLocations, readBoardAssets, classClosure, capabilityOf, requiredTestsFor, priorityRank, dueStatusOf, isOrderTerminal, effectivityAt, offCalendarAt, offCalendarReasonAt, minuteOfDayAt, activeShiftAt, subLotIdOf, itemKeyOf, identityGroundingOf, outsideLimit } from "./contract.js";
 import { ObservedReducer } from "./observed-reducer.js";
+/* 주체를 정하는 규칙은 유입 문과 한 벌이다 — 두 곳에 적으면 한쪽만 고쳐진다. */
+import { resolveSubject } from "./energy-ingest.js";
 import { transformationEvent, aggregationEvent, objectEvent, parseEpc, DISP, ILMD_ATTR, CBV_BIZSTEP, objectUri, bizTransactionUri, gdtiUri } from "./epcis.js";
 import { OP_PARAM } from "./domain-definition.js";
 import { parseIsoDuration } from "./iso-duration.js";
@@ -2787,6 +2789,53 @@ export class FlowEngine {
         for (const h of this.handlers)
             h(e);
     }
+    /**
+     * **마감된 구간 사실**을 낸다 — 이름을 내용에서 만든다(순번이 아니다).
+     *
+     * ── 왜 따로 있나 (2026-08-30) ────────────────────────────────────────────
+     * `emitOp` 은 이름을 순번으로 붙인다(`…-evt-3`). 관측이나 전이는 그래도 된다 — 두 번 일어나면 두
+     * 사실이다. 그런데 **마감된 구간은 같은 기간이면 한 사실이다.** 같은 하루를 커널이 자정에 닫고
+     * 커넥터가 지난 기록으로도 보내면, 순번 이름으로는 그 둘이 다른 사실이 되어 **발전량이 두 배로**
+     * 잡힌다. 유입 문은 이미 내용으로 이름을 짓고 있었는데(§`periodFactId`) 커널 자신만 아니었다 —
+     * 한 종류에 규칙이 두 벌이었다.
+     *
+     * ── 시각도 내용에서 온다 ─────────────────────────────────────────────────
+     * `emitOp` 은 **지금**을 찍는다. 마감된 구간에 그것을 찍으면 「우리가 언제 계산했나」가 되고, 재기동이
+     * 늦으면 어제의 사실이 오늘 시각을 갖는다. 실제로 그렇게 났다 — 부팅에서 닫힌 8월 29일치가 22:24 를
+     * 달고 나왔고, 시각 구간으로 읽는 중복 판정이 그것을 못 봐서 같은 하루가 12줄이 되었다(이름은 6개).
+     *
+     * 이 사실이 성립하는 것은 **기간의 끝**이다. 유입 문도 그 시각을 찍는다.
+     */
+    emitPeriodFact(eventType, data, eventId, eventTime) {
+        this.revision++;
+        const e = { eventId, eventType, eventTime, tenantId: this.tenantId, ...(this._correlationId ? { correlationId: this._correlationId } : {}), data };
+        for (const h of this.handlers)
+            h(e);
+    }
+    /**
+     * 이 트윈의 **범위 이름** — 선언된 정체성이 없을 때 이름표가 어디까지 통하는지(§`SubjectBasis`).
+     *
+     * 호스트가 세운다. 커널은 `new Kernel(domainId, …)` 으로 서므로 **자기가 어느 트윈인지 모른다** —
+     * 도메인에 현장이 둘이면 설비 번호가 겹치는데 커널만으로는 그것을 알 길이 없었다.
+     */
+    scopeId;
+    /**
+     * 설비의 **선언된 정체성** — 모델이 적었으면 그 이름, 없으면 답하지 않는다.
+     *
+     * 물품과 같은 자세다(§`declaredObjectId`): 선언이 없으면 지어내지 않는다. 명시한 이름이 먼저이고,
+     * 없으면 선언된 이름공간 아래의 개체 식별자로 만든다(CBV §8.2.3·§8.2.4).
+     */
+    equipmentIdentity(equipmentId) {
+        const decl = (this.boardDef?.equipment ?? []).find(e => e.id === equipmentId);
+        const explicit = String(decl?.identity ?? '').trim();
+        if (explicit)
+            return explicit;
+        return this.declaredObjectId(equipmentId);
+    }
+    /** 유입 문과 **같은 규칙**으로 주체를 정한다 — 이름 짓는 자리가 둘이면 한쪽만 고쳐지는 날이 온다. */
+    subjectOf(kind, localId) {
+        return resolveSubject(kind, localId, { tenantId: this.tenantId, scopeId: this.scopeId, identityOf: (k, id) => (k === 'equipment' ? this.equipmentIdentity(id) : undefined) });
+    }
     emitOp(eventType, data) {
         this.revision++;
         const e = { eventId: `${this.tenantId}-evt-${++this.eventSeq}`, eventType, eventTime: this.now(), tenantId: this.tenantId, ...(this._correlationId ? { correlationId: this._correlationId } : {}), data };

package/dist/index.d.ts

@@ -30,7 +30,7 @@ export { WmsKernel } from './kernel.ts';
 export { YmsKernel } from './yms-kernel.ts';
 export { MesKernel } from './mes-kernel.ts';
 export { EmsKernel, DEMAND_WINDOW_MS, demandWindowStart } from './ems-kernel.ts';
-export { ingestEnergyRecords, isEnergyRecord, ingestEnergyEquipmentRecords, isEnergyEquipmentRecord, ingestEnergyGenerationRecords, isEnergyGenerationRecord, ingestEnergyUsagePeriodRecords, isEnergyUsagePeriodRecord, ingestEnergyBillRecords, isEnergyBillRecord, ingestEnergyTariffBasisRecords, isEnergyTariffBasisRecord, ingestEnergyGenerationPriceRecords, isEnergyGenerationPriceRecord, ingestEnergyGenerationPeriodRecords, isEnergyGenerationPeriodRecord } from './energy-ingest.ts';
+export { ingestEnergyRecords, isEnergyRecord, ingestEnergyEquipmentRecords, isEnergyEquipmentRecord, ingestEnergyGenerationRecords, isEnergyGenerationRecord, ingestEnergyUsagePeriodRecords, isEnergyUsagePeriodRecord, ingestEnergyBillRecords, isEnergyBillRecord, ingestEnergyTariffBasisRecords, isEnergyTariffBasisRecord, ingestEnergyGenerationPriceRecords, isEnergyGenerationPriceRecord, ingestEnergyGenerationPeriodRecords, isEnergyGenerationPeriodRecord, resolveSubject, periodFactId } from './energy-ingest.ts';
 export { ingestOperationalRecords, isOperationalRecord, operationalKindOf } from './operational-ingest.ts';
 export type { OperationalKind, OperationalRecord, OperationalIngestOptions } from './operational-ingest.ts';
 export { attributeEnergy, electricityCost, energyIntensity, energyOfWindows } from './energy-attribution.ts';

package/dist/index.js

@@ -30,7 +30,7 @@ export { WmsKernel } from "./kernel.js";
 export { YmsKernel } from "./yms-kernel.js";
 export { MesKernel } from "./mes-kernel.js";
 export { EmsKernel, DEMAND_WINDOW_MS, demandWindowStart } from "./ems-kernel.js";
-export { ingestEnergyRecords, isEnergyRecord, ingestEnergyEquipmentRecords, isEnergyEquipmentRecord, ingestEnergyGenerationRecords, isEnergyGenerationRecord, ingestEnergyUsagePeriodRecords, isEnergyUsagePeriodRecord, ingestEnergyBillRecords, isEnergyBillRecord, ingestEnergyTariffBasisRecords, isEnergyTariffBasisRecord, ingestEnergyGenerationPriceRecords, isEnergyGenerationPriceRecord, ingestEnergyGenerationPeriodRecords, isEnergyGenerationPeriodRecord } from "./energy-ingest.js";
+export { ingestEnergyRecords, isEnergyRecord, ingestEnergyEquipmentRecords, isEnergyEquipmentRecord, ingestEnergyGenerationRecords, isEnergyGenerationRecord, ingestEnergyUsagePeriodRecords, isEnergyUsagePeriodRecord, ingestEnergyBillRecords, isEnergyBillRecord, ingestEnergyTariffBasisRecords, isEnergyTariffBasisRecord, ingestEnergyGenerationPriceRecords, isEnergyGenerationPriceRecord, ingestEnergyGenerationPeriodRecords, isEnergyGenerationPeriodRecord, resolveSubject, periodFactId } from "./energy-ingest.js";
 /* 운영 사실의 문 — 리듀서가 다루는 여섯이 들어오는 자리(미러가 시뮬보다 가난하지 않게). */
 export { ingestOperationalRecords, isOperationalRecord, operationalKindOf } from "./operational-ingest.js";
 export { attributeEnergy, electricityCost, energyIntensity, energyOfWindows } from "./energy-attribution.js";