@things-factory/headless-twin 10.0.17 → 10.0.18

package/dist-server/engine/twin-engine.js

@@ -54,9 +54,10 @@ const attention_digest_js_1 = require("./attention-digest.js");
 const live_feed_registry_js_1 = require("./live-feed-registry.js");
 const ingest_health_js_1 = require("./ingest-health.js");
 const ingest_dedupe_js_1 = require("./ingest-dedupe.js");
-const twin_kernel_1 = require("@operato/twin-kernel");
+const ops_contract_1 = require("@operato/ops-contract");
 /* 커널 런타임 로드 — CJS 번들(dist-cjs). 타입은 위 import type 로. replay = 이벤트열→상태 재구성(복구·시간여행). */
-const { WmsKernel, YmsKernel, MesKernel, EmsKernel, TwinRuntime, StateProjector, replay, replayFrom, replayWithCheckpoint, replaySegments, readBoardLocations, readBoardEquipment, DOMAIN_CATALOG, OP_EVENT, validateScenario } = require('@operato/twin-kernel');
+const { WmsKernel, YmsKernel, MesKernel, EmsKernel, TwinRuntime, StateProjector, replay, replayFrom, replayWithCheckpoint, replaySegments } = require('@operato/twin-kernel');
+const { readBoardLocations, readBoardEquipment, DOMAIN_CATALOG, OP_EVENT, validateScenario } = require('@operato/ops-contract');
 const KERNELS = { wms: WmsKernel, yms: YmsKernel, mes: MesKernel, ems: EmsKernel };
 /**
  * 시각축을 구할 때 한 번에 띄우는 트윈 수.
@@ -1366,6 +1367,7 @@ class TwinEngine {
             return this.instances[key];
         const Kernel = kernelFor(kind);
         const kernel = new Kernel(domainId, undefined, this.productionSpecOf(model));
+        kernel.scopeId = id;
         kernel.loadTwinModel(model); // 구조만. 상태는 아래 웜스타트가 주입한다.
         this.applyOperations(kernel, model, id); // 시간·수율 명세(있으면) — 없으면 커널 기본값
         /* 추정기는 DB 조회를 포함해 비동기 — 기동을 막지 않고 붙는다(붙기 전 작업은 명세·상수로 산출). */
@@ -1559,6 +1561,7 @@ class TwinEngine {
             return this.instances[key];
         const Kernel = kernelFor(kind);
         const kernel = new Kernel(domainId, undefined, this.productionSpecOf(model));
+        kernel.scopeId = id;
         kernel.loadTwinModel(model);
         /* **세우는 쪽이 아는 사실은 세울 때 말한다.** 예전에는 첫 이벤트가 도착해야 커널이 스스로를
            관측 구동으로 여겼고, 그래서 아직 아무것도 못 받은 미러는 시뮬레이션 취급을 받았다. */
@@ -2164,9 +2167,20 @@ class TwinEngine {
         if (carried.length)
             jobs.push(this.persistCarried(inst.domainId, inst.id, carried));
         if (plain.length && inst.revision != null) {
+            /*
+             * ── 마감된 구간 사실은 한 번만 적는다 (2026-08-30) ───────────────────────
+             *
+             * 이미 있는 것을 걸러낸 뒤에 번호를 매긴다. 걸러내기 전에 매기면 **쓰지 않은 번호가 비고**,
+             * 그 구멍이 저널의 리비전 연속성을 끊는다.
+             */
+            /*
+             * 번호는 **먼저 잡는다**(동기). 걸러낸 뒤에 잡으면 두 flush 가 겹칠 때 같은 번호를 두 번 쓴다.
+             * 걸러진 만큼 번호가 비지만, 그 구멍은 해롭지 않다 — 리비전은 같은 시각을 가리는 데만 쓰고
+             * 이어짐을 요구하지 않는다(저널 머리는 최대값이다).
+             */
             const start = inst.revision;
             inst.revision = start + plain.length;
-            jobs.push(this.persistBatch(inst.domainId, inst.id, plain, start));
+            jobs.push(this.dropAlreadyWritten(inst.domainId, inst.id, plain).then(fresh => fresh.length ? this.persistBatch(inst.domainId, inst.id, fresh, start) : undefined));
         }
         if (!jobs.length)
             return Promise.resolve();
@@ -2193,6 +2207,76 @@ class TwinEngine {
      * 예전에는 이 경로가 **델타마다 한 행씩** 저장했다(그리고 행마다 구조 리비전을 물었다). 규모에서 그것이
      * 호스트를 먹었다(§7.1 실측). 여기서 구조 리비전은 **한 번만** 묻는다.
      */
+    /**
+     * **마감된 구간 사실은 한 번만 적는다** — 같은 사실이 두 번 오면 한 사실이다 (2026-08-30).
+     *
+     * ── 왜 쓰는 자리에서 막나 ──────────────────────────────────────────────────
+     * 커널이 그 사실들의 정체성을 내용에서 만든다(종류·대상·시작·끝). 그런데 저널의 기본키는 새로
+     * 만드는 uuid 라, **id 가 글자 하나까지 같아도 행이 따로 쌓였다.**
+     *
+     * 실측(2026-08-30): 발전 단가가 행 7개·서로 다른 id 4개였다. 8월 27일 단가가 세 벌 있었고,
+     * 그 구간의 수익이 세 번 세어진다.
+     *
+     * 커넥터가 커서로 막는 것이 첫 방어선이고 그쪽도 고쳤다. 그런데 **커넥터가 한 번 실수하면 저널이
+     * 부풀고 그 위의 모든 합이 틀린다.** 정체성은 커널이 선언한 사실이므로, 어느 문으로 들어오든
+     * 지켜져야 한다 — 채우기 경로에만 있으면 그 보증은 「어느 문으로 왔느냐」에 걸린다.
+     *
+     * ── 값이 싼 이유 ───────────────────────────────────────────────────────────
+     * 마감된 구간 사실만 본다(시점의 관측은 그대로 지난다 — 반복이 뜻을 가진다). 그것들은 드물어서
+     * (한 시간에 한 줄) 한 묶음에 몇 개뿐이고, 그 구간의 그 종류만 색인으로 읽는다.
+     */
+    static { this.PERIOD_FACT_TYPES = new Set([
+        'energy.usage.period',
+        'energy.generation.period',
+        'energy.generation.price',
+        'energy.tariff.basis',
+        'energy.bill'
+    ]); }
+    static async dropAlreadyWritten(domainId, instanceId, envelopes) {
+        const periodFacts = envelopes.filter(e => this.PERIOD_FACT_TYPES.has(String(e?.eventType)) && typeof e?.eventId === 'string');
+        if (!periodFacts.length)
+            return envelopes;
+        const times = periodFacts.map(e => Date.parse(String(e.eventTime))).filter(n => Number.isFinite(n));
+        if (!times.length)
+            return envelopes;
+        const types = [...new Set(periodFacts.map(e => String(e.eventType)))];
+        const existing = await (0, shell_1.getRepository)(twin_event_js_1.TwinEvent)
+            .createQueryBuilder('e')
+            .select(['e.payload AS "payload"'])
+            .where('e.domain = :domainId', { domainId })
+            .andWhere('e.instanceId = :instanceId', { instanceId })
+            .andWhere('e.eventType IN (:...types)', { types })
+            .andWhere('e.eventTime BETWEEN :fromAt AND :toAt', { fromAt: new Date(Math.min(...times)), toAt: new Date(Math.max(...times)) })
+            .getRawMany()
+            .catch(() => []);
+        const seen = new Set();
+        for (const row of existing) {
+            let p = row.payload;
+            if (typeof p === 'string') {
+                try {
+                    p = JSON.parse(p);
+                }
+                catch {
+                    p = undefined;
+                }
+            }
+            if (typeof p?.eventId === 'string' && p.eventId)
+                seen.add(p.eventId);
+        }
+        /* 한 묶음 안에 같은 것이 둘 있어도 하나만 적는다. */
+        const kept = [];
+        for (const e of envelopes) {
+            if (!this.PERIOD_FACT_TYPES.has(String(e?.eventType)) || typeof e?.eventId !== 'string') {
+                kept.push(e);
+                continue;
+            }
+            if (seen.has(e.eventId))
+                continue;
+            seen.add(e.eventId);
+            kept.push(e);
+        }
+        return kept;
+    }
     static async persistCarried(domainId, instanceId, items) {
         const repo = (0, shell_1.getRepository)(twin_event_js_1.TwinEvent);
         const structureRev = await this.structureRevOf(domainId, instanceId);
@@ -2301,6 +2385,23 @@ class TwinEngine {
         }));
     }
     /**
+     * ── **트윈은 설비의 마스터가 아니다** (사용자 결정 2026-08-30) ─────────────
+     *
+     * 인원·설비·자산의 마스터는 `@things-factory/ops-master` 다. 트윈은 그것을 **당겨 와** 모델에
+     * 반영하고, 여기 남는 것은 그 결과의 캐시다.
+     *
+     * 그래서 이 함수가 하는 일에 선이 있다.
+     *
+     *   트윈 안에서 사람이 더한 설비   가정·시뮬레이션의 사실이다 — 트윈이 든다 (지금 이 함수)
+     *   현장에 실제로 있는 설비        마스터의 사실이다 — 트윈이 만들지 않는다
+     *
+     * 이 함수는 **트윈 제어 명령**(`resource.add`) 뒤에만 불린다. 관측에서 설비가 생기는 경로가 아니다.
+     * 관측으로 모르는 설비가 들어오면 그것은 **마스터에 없는 것**이고, 트윈이 조용히 만들어 주면 두
+     * 곳이 서로 다른 설비 목록을 갖게 된다. 그때는 만들지 말고 「모르는 설비가 왔다」로 세어야 한다.
+     *
+     * 당겨 오는 길이 붙으면 이 주석의 위쪽 절반만 남는다.
+     *
+     * ── 원래 설명 ─────────────────────────────────────────────────────────────
      * 라이브 구조 변이(resource.add 등)를 저장된 model 에 반영 — 런타임 커널의 무버를 registry model.equipment 에 동기.
      * 이게 없으면 런타임엔 추가돼도(상태·저널엔 반영) 저장 model 는 원본이라 프로비저닝 편집기·재기동(loadTwinModel)이
      * 추가분을 잃는다. 기존 model.equipment 항목은 보존(homeLocation 유지)하고 새 id 만 append(추가 시점 location=homeLocation).
@@ -3104,7 +3205,7 @@ class TwinEngine {
              */
             if (model?.utcOffsetMinutes === undefined) {
                 for (const e of (model?.equipment ?? [])) {
-                    const hasProfile = (e?.properties ?? []).some(p => String(p?.id) === twin_kernel_1.EMS_PROPERTY.genDailyProfile && String(p?.value ?? '').trim());
+                    const hasProfile = (e?.properties ?? []).some(p => String(p?.id) === ops_contract_1.EMS_PROPERTY.genDailyProfile && String(p?.value ?? '').trim());
                     if (hasProfile)
                         warnings.push((0, reference_master_js_3.generationWithoutTimeZone)(String(model?.spaceId ?? ''), String(e.id)));
                 }
@@ -4003,6 +4104,51 @@ class TwinEngine {
      * `offered` 는 **제시된 레코드 수**다(거부 여부 무관). 통과율을 서로 다른 두 계수기에서 나눠 계산하면
      * 분모와 분자가 다른 것을 세게 되므로, 한자리에서 본 수를 그대로 넘긴다.
      */
+    /**
+     * 이 트윈의 저널이 지금 몇 번까지 적혔나 — **접근자로 낸다.**
+     *
+     * 레지스트리를 밖에서 직접 색인하지 않게 하는 것이 이 저장소의 규율이다(§`engine-registry-access`).
+     * 지난 기록을 채우는 길이 다음 번호를 알아야 해서 열었다.
+     *
+     * 트윈이 도는 중이 아니면 0 이다 — 그때는 저널만 있고 이어 붙일 번호를 커널이 들고 있지 않다.
+     */
+    /**
+     * 마감된 구간 사실의 **이름을 지을 때 쓸 범위와 선언** — 유입 문에 넘긴다.
+     *
+     * ── 왜 호스트가 주나 (2026-08-30) ────────────────────────────────────────
+     * 커널은 `new Kernel(domainId, …)` 으로 서므로 **자기가 어느 트윈인지 모른다.** 그런데 설비 번호는
+     * 트윈 안에서만 통하는 이름표라, 한 도메인에 현장이 둘이면 서로 다른 설비의 같은 날이 한 사실이
+     * 된다. 실측으로 그 일이 났다 — 두 발전소의 `002` 가 겹쳐, 여러 현장을 함께 계산하는 성과 화면에서
+     * 한쪽 발전량이 사라진다.
+     *
+     * 선언된 정체성은 **커널이 답한다**(§`FlowEngine.equipmentIdentity`) — 판정을 두 곳에 두지 않는다.
+     * 트윈이 돌고 있지 않으면 선언을 물을 곳이 없으므로 범위만 넘긴다(그때도 겹치지는 않는다).
+     */
+    static factScope(domainId, instanceId) {
+        const inst = this.instances[(0, runtime_key_js_1.runtimeKey)(domainId, instanceId)];
+        const kernel = inst?.kernel;
+        if (typeof kernel?.equipmentIdentity !== 'function')
+            return { scopeId: instanceId };
+        return {
+            scopeId: instanceId,
+            identityOf: (kind, localId) => (kind === 'equipment' ? kernel.equipmentIdentity(localId) : undefined)
+        };
+    }
+    static journalHead(domainId, instanceId) {
+        const inst = this.instances[(0, runtime_key_js_1.runtimeKey)(domainId, instanceId)];
+        return Number(inst?.revision ?? 0);
+    }
+    /**
+     * 저널에 그만큼 적었으니 번호를 밀어 준다.
+     *
+     * 밀어 주지 않으면 다음에 라이브가 **같은 번호를 다시 쓴다** — 같은 시각의 두 사실을 가릴 수 없게 된다.
+     */
+    static advanceJournalHead(domainId, instanceId, by) {
+        const inst = this.instances[(0, runtime_key_js_1.runtimeKey)(domainId, instanceId)];
+        if (!inst || !(by > 0))
+            return;
+        inst.revision = Number(inst.revision ?? 0) + by;
+    }
     static recordIngestResult(domainId, instanceId, offered, rejected, nowMs = Date.now(), 
     /**
      * 매핑은 통과했는데 **커널이 받지 않은** 수(`ingestLive` 의 반환과 견주어 얻는다).