@operato/twin-kernel 0.7.66 → 0.7.68

package/dist/master-data.js

@@ -0,0 +1,168 @@
+import { ILMD_ATTR } from "./epcis.js";
+/*
+ * **마스터데이터 — 변하지 않는 속성이 들어오는 문** (2026-08-28).
+ *
+ * ── 무엇이 없어서 무엇이 망가졌나 ───────────────────────────────────────────
+ * 커널에 마스터데이터라는 개념이 없었다. 그래서 유통기한 같은 값이 갈 곳이 **사건밖에** 없었고,
+ * 표준은 그 값을 `ObjectEvent(action=ADD)` 와 변환 사건에만 실을 수 있게 한다(EPCIS 2.0 §7.3.8).
+ *
+ * 그 제약이 유입 쪽에서 이렇게 나타났다. 전량을 읽는 원본(식품 제조 MES)이 재고를 다시 말할 때마다,
+ * 유통기한을 실으려고 **들어오지 않은 것을 `ADD` 라고** 말했다. 그리고 `ilmd` 는 사건 단위라서 자리별로
+ * 묶을 수도 없어 낱개로 나갔다 — 재기동 한 번에 2,665건이다.
+ *
+ * 나르는 방법의 제약이 사실의 뜻을 정한 것이고, 순서가 거꾸로였다.
+ *
+ * ── 표준이 둔 자리 ──────────────────────────────────────────────────────────
+ * 표준은 이런 값을 **어휘 요소의 속성**으로 담는 자리를 사건과 별개로 갖고 있다.
+ *
+ *   어휘 타입   urn:epcglobal:epcis:vtype:EPCClass · ReadPoint · BizLocation
+ *   어휘 요소   { id, attributes }
+ *
+ * 속성 **이름**은 EPCIS 본문이 정하지 않고 상위 문서(CBV 마스터데이터)의 몫이다(§7.3.8 이 미룬다).
+ * 그래서 이 모듈은 이름을 해석하지 않고 **그대로 보관한다** — 아는 이름만 상태 축으로 옮기고, 모르는
+ * 것은 잃지 않는다. 우리가 생산할 때 쓰는 이름은 `ILMD_ATTR` 한 곳에 모여 있고 사건 경로와 같은
+ * 상수다(이름이 바뀌면 한 곳만 고친다).
+ *
+ * ── 무엇을 이 문으로 보내지 않나 ────────────────────────────────────────────
+ * **변하는 값은 사건이다.** 수량·위치·상태·진행은 이 문으로 오지 않는다. 여기 오는 것은 그 물건의
+ * 생애 동안 같은 값뿐이고, 그래서 「그때는 얼마였나」라는 물음이 성립하지 않는다 — 시각축이 없는 값이다.
+ *
+ * 그 성질이 「지난 기록에 적지 않는다」의 근거다. 사건에서 파생되는 상태가 아니라 **선언된 것**이므로
+ * 모델·자재 선언과 같은 자리에 산다. 다만 중간 저장본에는 담는다(되세울 때 원본을 다시 읽지 않게).
+ *
+ * 설계: `operato-twin/design/plans/master-data.md`
+ */
+/** 표준 어휘 타입 — 이 세 가지가 우리 상태 축에 닿는다. 그 밖은 보관하고 알린다. */
+export const VOCABULARY_TYPE = {
+    /** 품목·로트 클래스의 속성 — 유통기한·로트번호가 여기 온다. */
+    epcClass: 'urn:epcglobal:epcis:vtype:EPCClass',
+    /** 관측 지점의 속성. */
+    readPoint: 'urn:epcglobal:epcis:vtype:ReadPoint',
+    /** 업무 자리의 속성. */
+    bizLocation: 'urn:epcglobal:epcis:vtype:BizLocation'
+};
+/** 이 레코드가 마스터데이터인가 — 갈래 판정은 **커널이 한 곳에서** 한다(어휘 넷을 가르는 방식과 같다). */
+export function isMasterDataRecord(record) {
+    if (!record || typeof record !== 'object')
+        return false;
+    const r = record;
+    return typeof r.vocabularyType === 'string' && !!r.vocabularyType && typeof r.id === 'string' && !!r.id && isPlainObject(r.attributes);
+}
+function isPlainObject(v) {
+    return !!v && typeof v === 'object' && !Array.isArray(v);
+}
+/**
+ * 마스터데이터를 받아들인다 — **거부한 것은 이유와 함께 남는다**(다른 어휘와 같은 규율).
+ *
+ * 빈 속성은 거부한다: 「이 로트에 대해 아무것도 모른다」를 보내는 것은 아무 뜻이 없고, 받아 두면
+ * 기존 값을 지우려는 것인지 아무 말도 아닌지 구별할 수 없다.
+ */
+export function ingestMasterData(records) {
+    const arr = Array.isArray(records) ? records : records ? [records] : [];
+    const accepted = [];
+    const rejected = [];
+    for (const r of arr) {
+        const errors = [];
+        if (!isMasterDataRecord(r))
+            errors.push('vocabularyType · id · attributes 가 있어야 한다');
+        else if (!Object.keys(r.attributes).length)
+            errors.push('attributes 가 비었다 — 아무 뜻이 없는 진술이다');
+        /* 값이 `null` 인 속성은 「지운다」는 뜻이므로 빈 진술이 아니다(위 검사가 이름 수를 세므로 통과한다). */
+        if (errors.length)
+            rejected.push({ record: r, errors });
+        else
+            accepted.push({ vocabularyType: r.vocabularyType, id: r.id, attributes: { ...r.attributes } });
+    }
+    return { accepted, rejected };
+}
+/**
+ * 클래스 단위 마스터 표 — 관측 리듀서가 든다.
+ *
+ * 물품은 자리마다 따로 서지만(`클래스@자리`) 이 속성은 **클래스의 것**이다. 그래서 물품마다 복사해
+ * 두지 않고 클래스로 한 번 들고, 물품을 세울 때 본다. 마스터가 관측보다 늦게 와도 값이 서는 이유다.
+ */
+export class ClassMasterTable {
+    byId = new Map();
+    /**
+     * 속성을 **합친다** — 덮지 않는다(한 번에 일부만 오는 원본이 있다). 바뀐 식별자를 돌려준다.
+     *
+     * ── 지우는 법 ───────────────────────────────────────────────────────────────
+     * 값에 `null` 을 실으면 **그 속성을 지운다**(「모름으로 되돌린다」). 합치기만 하면 원본에서 지운 값이
+     * 트윈에 영원히 남고, 그것을 표현할 방법이 없으면 「지웠다」와 「이번엔 말하지 않았다」가 같아진다.
+     *
+     * `undefined` 는 지우지 않는다 — 그것은 「이 진술에 그 속성이 없다」이고, 원본이 일부만 보내는
+     * 정상이다. 두 뜻을 갈라 둔다.
+     *
+     * 속성이 하나도 남지 않으면 그 요소를 표에서 버린다(빈 껍데기를 들고 있지 않는다).
+     */
+    merge(elements) {
+        const touched = [];
+        for (const e of elements) {
+            const next = { ...(this.byId.get(e.id) ?? {}) };
+            for (const [name, value] of Object.entries(e.attributes)) {
+                if (value === null)
+                    delete next[name];
+                else if (value !== undefined)
+                    next[name] = value;
+            }
+            if (Object.keys(next).length)
+                this.byId.set(e.id, next);
+            else
+                this.byId.delete(e.id);
+            touched.push(e.id);
+        }
+        return touched;
+    }
+    /**
+     * 그 식별자의 항목을 버린다 — **아무도 가리키지 않게 된 뒤**에만 부른다.
+     *
+     * 로트는 계속 새로 생기므로 이 표는 스스로 줄지 않는다. 하루 수백 로트면 1년에 수십만 항목이고,
+     * 그것을 아무도 지우지 않으면 재기동으로만 줄어든다(그리고 중간 저장본이 그만큼 커진다).
+     */
+    forget(id) {
+        return this.byId.delete(id);
+    }
+    attributesOf(id) {
+        return id ? this.byId.get(id) : undefined;
+    }
+    get size() {
+        return this.byId.size;
+    }
+    serialize() {
+        return Object.fromEntries(this.byId);
+    }
+    restore(saved) {
+        this.byId.clear();
+        if (!isPlainObject(saved))
+            return;
+        for (const [id, attrs] of Object.entries(saved))
+            if (isPlainObject(attrs))
+                this.byId.set(id, { ...attrs });
+    }
+    clear() {
+        this.byId.clear();
+    }
+}
+/** 마스터 속성에서 유통기한을 읽는다 — 사건의 `ilmd` 와 **같은 이름**을 본다. */
+export function expiryFromAttributes(attrs) {
+    return readEpochMs(attrs?.[ILMD_ATTR.expiry]);
+}
+/** 마스터 속성에서 로트 번호를 읽는다 — 사건의 `ilmd` 와 같은 이름. */
+export function lotFromAttributes(attrs) {
+    const v = attrs?.[ILMD_ATTR.lot];
+    return typeof v === 'string' && v.trim() ? v.trim() : undefined;
+}
+/**
+ * 시각 값을 밀리초로 — 숫자와 문자열을 모두 읽는다(원본이 둘 다 쓴다).
+ *
+ * 읽을 수 없으면 `undefined` 다. 「지금」으로 메우면 기한이 지난 재고가 멀쩡해 보이고, 0 으로 메우면
+ * 멀쩡한 재고가 기한 지난 것으로 보인다 — 둘 다 사실이 아니다.
+ */
+function readEpochMs(raw) {
+    if (typeof raw === 'number')
+        return Number.isFinite(raw) ? raw : undefined;
+    if (typeof raw !== 'string' || !raw.trim())
+        return undefined;
+    const at = Date.parse(raw);
+    return Number.isNaN(at) ? undefined : at;
+}

package/dist/observed-reducer.d.ts

@@ -1,4 +1,5 @@
 import type { AssetState, TestResult, MaterialQuantity, TwinModelDef, CanonicalEnvelope, LocationState, ItemState, LocationObservation, EquipmentState, PersonState, TaskState, OrderState, StructureShift } from './contract.ts';
+import { type VocabularyElement } from './master-data.ts';
 interface ProjItem {
     epc: string;
     /** 로트의 부분(표준 MaterialSubLot.ID) — 비직렬 로트가 자리마다 갈릴 때만. */
@@ -168,6 +169,25 @@ export interface ReducerCheckpoint {
         atMs: number;
         longestGapMs?: number;
     }[];
+    /**
+     * 도메인 커널이 따로 드는 상태 — 이 리듀서는 내용을 보지 않고 그대로 실어 보낸다 (2026-08-27).
+     *
+     * ── 왜 필요한가 ─────────────────────────────────────────────────────────────
+     * 에너지 커널은 이 리듀서 밖에 자기 상태를 든다(계량 지점 · 열린 수요 구간 · 닫힌 구간들 · 월 최고).
+     * 그 값들은 계측을 모아 **트윈이 만든 것**이라, 연결된 시스템이 되풀어 주지 않는다. 재개점에 담기지
+     * 않으면 중간 저장본에서 이어 처리할 때 그만큼이 조용히 사라진다.
+     *
+     * 내용을 여기서 정의하지 않는 이유: 도메인마다 다르고, 이 리듀서가 그것을 알면 도메인 규칙이
+     * 공통 코드로 새어 든다. 그대로 담아 두고 되돌려 줄 뿐이다.
+     */
+    domain?: unknown;
+    /**
+     * **클래스 단위 마스터데이터** — 변하지 않는 속성(유통기한·로트번호)이 사는 자리(§`master-data`).
+     *
+     * 지난 기록에 적지 않는 값이므로 여기 담지 않으면 되세울 때 빈다. 변하지 않는 값이라 어느 시점의
+     * 저장본에서 꺼내도 같은 답이다.
+     */
+    classMaster?: Record<string, Record<string, unknown>>;
 }
 export declare class ObservedReducer {
     /** 로케이션 마스터 — 출처를 함께 들고 있다(마스터가 말한 자리 vs 관측으로 알게 된 자리). */
@@ -186,6 +206,13 @@ export declare class ObservedReducer {
      */
     private heard;
     private items;
+    /**
+     * **클래스 단위 마스터 표** — 변하지 않는 속성이 사는 자리(§`master-data`).
+     *
+     * 물품은 자리마다 따로 서지만(`클래스@자리`) 유통기한·로트번호는 **클래스의 것**이다. 그래서 물품마다
+     * 복사해 두지 않고 클래스로 한 번 들고, 물품을 세울 때 본다 — 마스터가 관측보다 늦게 와도 값이 선다.
+     */
+    private classMaster;
     private aggregation;
     /** 아직 관측되지 않은 자식의 담김 — 물품을 지어내지 않고 보류했다가 등장할 때 붙인다. */
     private pendingParent;
@@ -334,6 +361,24 @@ export declare class ObservedReducer {
      * 표준이 속성 이름을 정의하지 않으므로 모르는 이름은 해석하지 않는다(추측하지 않는다). 원문은
      * `ilmd` 로 그대로 남으니 도메인이 자기 어휘로 읽을 수 있다.
      */
+    /**
+     * 이 물품에 해당하는 마스터 속성 — **클래스로 찾고, 없으면 물품 자신의 식별자로** 찾는다.
+     *
+     * 비직렬 재고는 물품의 키가 곧 클래스 식별자다. 직렬 개체는 클래스가 따로 있다. 두 모양이 다 오므로
+     * 둘 다 본다 — 한쪽만 보면 그 원본에서는 값이 조용히 비어 있게 된다.
+     */
+    private masterAttributesOf;
+    /**
+     * **마스터데이터를 받는다** — 어휘 요소의 속성을 상태에 세운다(§`master-data`).
+     *
+     * 받은 것을 표에 합치고, **그 배치에 든 식별자의 물품만** 다시 세운다. 전부를 훑지 않는 이유는
+     * 재고가 수만 건일 수 있고 마스터는 자주 오기 때문이다.
+     *
+     * 이 값은 지난 기록에 적지 않는다 — 변하지 않는 값이므로 시각축이 없다. 호스트가 그 갈래를 정한다.
+     */
+    applyMasterData(elements: readonly VocabularyElement[]): number;
+    /** 지금 든 마스터 항목 수 — 화면이 「무엇을 알고 있나」를 말할 수 있게. */
+    get masterDataSize(): number;
     private expiryOf;
     private mergeItem;
     /** 이탈(DELETE) — 아이템 + 조립 자식(재귀) 제거. 화물 SSCC DELETE 시 팔레트도 함께 이탈. */

package/dist/observed-reducer.js

@@ -21,6 +21,7 @@
  */
 import { OP_EVENT, capabilityOf, itemKeyOf, judgeAgainstSpec, requiredTestsFor, locationStatusOf, readBoardEquipment, readBoardLocations, readBoardAssets, effectivityAt, offCalendarAt, offCalendarReasonAt, activeShiftAt } from "./contract.js";
 import { ILMD_ATTR, parseEpc } from "./epcis.js";
+import { ClassMasterTable, expiryFromAttributes, lotFromAttributes } from "./master-data.js";
 /**
  * 투영이 들고 있는 물품 — **계약(ItemState)을 축소하지 않는다.**
  *
@@ -55,6 +56,13 @@ export class ObservedReducer {
      */
     heard = new Map();
     items = new Map();
+    /**
+     * **클래스 단위 마스터 표** — 변하지 않는 속성이 사는 자리(§`master-data`).
+     *
+     * 물품은 자리마다 따로 서지만(`클래스@자리`) 유통기한·로트번호는 **클래스의 것**이다. 그래서 물품마다
+     * 복사해 두지 않고 클래스로 한 번 들고, 물품을 세울 때 본다 — 마스터가 관측보다 늦게 와도 값이 선다.
+     */
+    classMaster = new ClassMasterTable();
     aggregation = new Map();
     /** 아직 관측되지 않은 자식의 담김 — 물품을 지어내지 않고 보류했다가 등장할 때 붙인다. */
     pendingParent = new Map(); // 자식 EPC → 부모(물류단위)
@@ -838,6 +846,56 @@ export class ObservedReducer {
      * 표준이 속성 이름을 정의하지 않으므로 모르는 이름은 해석하지 않는다(추측하지 않는다). 원문은
      * `ilmd` 로 그대로 남으니 도메인이 자기 어휘로 읽을 수 있다.
      */
+    /**
+     * 이 물품에 해당하는 마스터 속성 — **클래스로 찾고, 없으면 물품 자신의 식별자로** 찾는다.
+     *
+     * 비직렬 재고는 물품의 키가 곧 클래스 식별자다. 직렬 개체는 클래스가 따로 있다. 두 모양이 다 오므로
+     * 둘 다 본다 — 한쪽만 보면 그 원본에서는 값이 조용히 비어 있게 된다.
+     */
+    masterAttributesOf(classUri, epc) {
+        return this.classMaster.attributesOf(classUri) ?? this.classMaster.attributesOf(epc);
+    }
+    /**
+     * **마스터데이터를 받는다** — 어휘 요소의 속성을 상태에 세운다(§`master-data`).
+     *
+     * 받은 것을 표에 합치고, **그 배치에 든 식별자의 물품만** 다시 세운다. 전부를 훑지 않는 이유는
+     * 재고가 수만 건일 수 있고 마스터는 자주 오기 때문이다.
+     *
+     * 이 값은 지난 기록에 적지 않는다 — 변하지 않는 값이므로 시각축이 없다. 호스트가 그 갈래를 정한다.
+     */
+    applyMasterData(elements) {
+        if (!elements.length)
+            return 0;
+        const touched = new Set(this.classMaster.merge(elements));
+        for (const [key, item] of this.items) {
+            /* 클래스로 든 것과 물품 자신의 식별자, 둘 중 하나가 이 배치에 들었으면 다시 세운다. */
+            if (!touched.has(item.gtin ?? '') && !touched.has(item.epc))
+                continue;
+            const attrs = this.masterAttributesOf(item.gtin, item.epc);
+            /*
+             * **물품이 설 때와 같은 순서로** 세운다(§`mergeItem`).
+             *
+             *   식별자에서 뽑은 것 → 사건의 `ilmd` → 마스터 → 기존값
+             *
+             * 여기서 「기존값이 마스터를 이긴다」로 적었더니 값이 **들어온 순서에 따라 달라졌다**: 마스터가
+             * 먼저 오면 마스터 값, 늦게 오면 옛 값. 같은 사실에 두 답이 생기는 자리다.
+             */
+            const fromId = parseEpc(item.gtin ?? item.epc).lot ?? parseEpc(item.epc).lot;
+            this.items.set(key, {
+                ...item,
+                expiry: this.expiryOf(item.ilmd) ?? expiryFromAttributes(attrs) ?? item.expiry,
+                lot: fromId ??
+                    (typeof item.ilmd?.[ILMD_ATTR.lot] === 'string' ? item.ilmd[ILMD_ATTR.lot] : undefined) ??
+                    lotFromAttributes(attrs) ??
+                    item.lot
+            });
+        }
+        return elements.length;
+    }
+    /** 지금 든 마스터 항목 수 — 화면이 「무엇을 알고 있나」를 말할 수 있게. */
+    get masterDataSize() {
+        return this.classMaster.size;
+    }
     expiryOf(ilmd) {
         const raw = ilmd?.[ILMD_ATTR.expiry];
         if (typeof raw === 'number' && Number.isFinite(raw))
@@ -894,14 +952,50 @@ export class ObservedReducer {
             })(),
             /* 마스터데이터는 생겨날 때 한 번 정해진다 — 뒤 이벤트가 지우지 않게 기존 값을 남긴다. */
             ilmd: patch.ilmd ?? cur?.ilmd,
-            expiry: this.expiryOf(patch.ilmd) ?? cur?.expiry,
+            /*
+             * ── 보는 순서 (2026-08-28) ─────────────────────────────────────────────
+             *   ① 사건에 실려 온 `ilmd`        표준의 생성 시점 진술 — 가장 강하다
+             *   ② 그 클래스의 마스터 표        마스터데이터 통로로 들어온 것(§`master-data`)
+             *   ③ 이미 갖고 있던 값            뒤 사건이 지우지 않는다
+             *
+             * ②가 없던 동안, 전량을 읽는 원본은 유통기한을 실으려고 **들어오지 않은 것을 `ADD`** 라고
+             * 말해야 했다. 그 값이 갈 자리를 만든 것이 이 줄이다.
+             */
+            expiry: this.expiryOf(patch.ilmd) ?? expiryFromAttributes(this.masterAttributesOf(classUri, epc)) ?? cur?.expiry,
             /* 로트는 LGTIN(식별자)에서 오지만, 직렬 개체는 마스터데이터에 실려 온다. */
-            lot: parsedClass?.lot ?? parsedSelf.lot ?? (typeof patch.ilmd?.[ILMD_ATTR.lot] === 'string' ? patch.ilmd[ILMD_ATTR.lot] : undefined) ?? cur?.lot
+            lot: parsedClass?.lot ??
+                parsedSelf.lot ??
+                (typeof patch.ilmd?.[ILMD_ATTR.lot] === 'string' ? patch.ilmd[ILMD_ATTR.lot] : undefined) ??
+                lotFromAttributes(this.masterAttributesOf(classUri, epc)) ??
+                cur?.lot
         };
     }
     /** 이탈(DELETE) — 아이템 + 조립 자식(재귀) 제거. 화물 SSCC DELETE 시 팔레트도 함께 이탈. */
     remove(epc) {
+        const gone = this.items.get(epc);
         this.items.delete(epc);
+        /*
+         * ── 마스터 표도 함께 줄인다 (2026-08-28) ───────────────────────────────────
+         *
+         * 로트는 계속 새로 생기므로 이 표는 스스로 줄지 않는다. 하루 수백 로트면 1년에 수십만 항목이고,
+         * 중간 저장본이 그만큼 커진다. 그래서 **아무 물품도 가리키지 않게 된 식별자**를 버린다.
+         *
+         * 이탈이 일어난 자리에서만 검사한다. 마스터가 먼저 오고 물품이 아직 없는 것은 **정상**이므로
+         * (순서를 보장할 수 없다) 그때 「가리키는 물품이 없다」로 지우면 방금 받은 값을 버린다.
+         */
+        for (const id of [gone?.gtin, epc]) {
+            if (!id || !this.classMaster.attributesOf(id))
+                continue;
+            let stillUsed = false;
+            for (const it of this.items.values()) {
+                if (it.gtin === id || it.epc === id) {
+                    stillUsed = true;
+                    break;
+                }
+            }
+            if (!stillUsed)
+                this.classMaster.forget(id);
+        }
         const children = this.aggregation.get(epc);
         if (children) {
             this.aggregation.delete(epc);
@@ -1024,8 +1118,13 @@ export class ObservedReducer {
             acked: [...this.acked],
             corrections: this.corrections.map(c => ({ ...c })),
             unhandled: [...this.unhandled.entries()].map(([eventType, v]) => ({ eventType, ...v })),
-            /* 마지막으로 들은 시각 — 이어받지 않으면 재기동 뒤에 침묵의 길이를 말할 수 없다. */
-            heard: [...this.heard.entries()].map(([id, v]) => ({ id, ...v }))
+            /* 마지막으로 들은 시각 — 이어받지 않으면 재기동 뒤에 아무 말이 없던 길이를 말할 수 없다. */
+            heard: [...this.heard.entries()].map(([id, v]) => ({ id, ...v })),
+            /*
+             * 마스터데이터도 담는다 — 지난 기록에 없는 값이므로, 담지 않으면 되세울 때 유통기한이 빈다.
+             * 변하지 않는 값이라 어느 시점의 저장본에서 꺼내도 같은 답이다.
+             */
+            classMaster: this.classMaster.serialize()
         };
     }
     /**
@@ -1039,6 +1138,7 @@ export class ObservedReducer {
         this.master = new Map((cp?.master ?? []).map(n => [n.id, { ...n }]));
         this.heard = new Map((cp?.heard ?? []).map(h => [h.id, { atMs: h.atMs, ...(h.longestGapMs !== undefined ? { longestGapMs: h.longestGapMs } : {}) }]));
         this.items = new Map((cp?.items ?? []).map(i => [i.epc, { ...i }]));
+        this.classMaster.restore(cp?.classMaster);
         this.aggregation = new Map((cp?.aggregation ?? []).map(a => [a.parent, [...a.children]]));
         this.pendingParent = new Map((cp?.pendingParent ?? []).map(x => [x.child, x.parent]));
         this.qtyAggregation = new Map((cp?.qtyAggregation ?? []).map(x => [x.parent, x.quantities]));