@operato/twin-kernel 0.7.67 → 0.7.68

package/dist/epcis.d.ts

@@ -94,6 +94,35 @@ export declare const CBV_BIZSTEP: {
 };
 export type EpcisEventType = 'ObjectEvent' | 'AggregationEvent' | 'TransactionEvent' | 'TransformationEvent';
 export type EpcisAction = 'ADD' | 'OBSERVE' | 'DELETE';
+/**
+ * **봉투에 실리는 EPCIS 사건 종류의 이름** — 소비처가 손으로 적지 않게 (2026-08-28).
+ *
+ * 봉투의 `eventType` 은 `epcis.<클래스>` 다(§`face2-adapter`·§`flow-engine` 이 그 접두사를 붙인다).
+ * 그 문자열을 화면·조회가 손으로 적으면 곧 방언이 되고, 클래스가 늘 때 한쪽만 고쳐진다.
+ *
+ * ── 왜 필요한가 ─────────────────────────────────────────────────────────────
+ * 「물건이 움직인 사건만 보는 목록」이 지금 **제외 목록**으로 만들어져 있다 — 운영·에너지 종류 열아홉
+ * 개를 적어 빼는 방식이다. 그 방식은 두 가지로 약하다.
+ *
+ *  ① **닫히지 않는다.** 커널이 세 번째 계열을 만들면 그 계열 전부가 오류 없이 「움직임」으로 들어온다.
+ *     실제로 그 일이 세 번 있었다(사람 상태·자산 상태·에너지).
+ *  ② **색인을 못 쓴다.** 제외 + 시각순은 색인이 듣지 않아, 그 트윈의 종류 분포가 비용을 정한다
+ *     (실측: 에너지가 0.008%인 트윈에서 같은 모양이 37초였다).
+ *
+ * 담을 것을 말하면 정의가 닫힌다 — **물건이 움직인 사건 = EPCIS 사건**이고 그 클래스는 표준이 정한다.
+ * 커널이 채널을 늘려도 이 집합은 늘지 않는다.
+ *
+ * 우리 커널이 다루는 클래스는 넷이다. 표준의 `AssociationEvent` 는 아직 만들지 않았고, 만들면 이 상수에
+ * 더한다 — 그 한 곳만 고치면 소비처가 함께 따라온다.
+ */
+export declare const EPCIS_EVENT: {
+    readonly object: "epcis.ObjectEvent";
+    readonly aggregation: "epcis.AggregationEvent";
+    readonly transaction: "epcis.TransactionEvent";
+    readonly transformation: "epcis.TransformationEvent";
+};
+/** 봉투의 `eventType` 이 EPCIS 사건인가 — 접두사 하나로 판정한다(클래스가 늘어도 그대로 산다). */
+export declare function isEpcisEventType(eventType: unknown): boolean;
 /**
  * 수량 요소 — **클래스 식별자 + 얼마나**. 표준이 세 경우를 규정한다(EPCIS 2.0 §7.3.3.1).
  *

package/dist/epcis.js

@@ -101,6 +101,37 @@ export const CBV_BIZSTEP = {
      */
     other: 'urn:epcglobal:cbv:bizstep:other'
 };
+/**
+ * **봉투에 실리는 EPCIS 사건 종류의 이름** — 소비처가 손으로 적지 않게 (2026-08-28).
+ *
+ * 봉투의 `eventType` 은 `epcis.<클래스>` 다(§`face2-adapter`·§`flow-engine` 이 그 접두사를 붙인다).
+ * 그 문자열을 화면·조회가 손으로 적으면 곧 방언이 되고, 클래스가 늘 때 한쪽만 고쳐진다.
+ *
+ * ── 왜 필요한가 ─────────────────────────────────────────────────────────────
+ * 「물건이 움직인 사건만 보는 목록」이 지금 **제외 목록**으로 만들어져 있다 — 운영·에너지 종류 열아홉
+ * 개를 적어 빼는 방식이다. 그 방식은 두 가지로 약하다.
+ *
+ *  ① **닫히지 않는다.** 커널이 세 번째 계열을 만들면 그 계열 전부가 오류 없이 「움직임」으로 들어온다.
+ *     실제로 그 일이 세 번 있었다(사람 상태·자산 상태·에너지).
+ *  ② **색인을 못 쓴다.** 제외 + 시각순은 색인이 듣지 않아, 그 트윈의 종류 분포가 비용을 정한다
+ *     (실측: 에너지가 0.008%인 트윈에서 같은 모양이 37초였다).
+ *
+ * 담을 것을 말하면 정의가 닫힌다 — **물건이 움직인 사건 = EPCIS 사건**이고 그 클래스는 표준이 정한다.
+ * 커널이 채널을 늘려도 이 집합은 늘지 않는다.
+ *
+ * 우리 커널이 다루는 클래스는 넷이다. 표준의 `AssociationEvent` 는 아직 만들지 않았고, 만들면 이 상수에
+ * 더한다 — 그 한 곳만 고치면 소비처가 함께 따라온다.
+ */
+export const EPCIS_EVENT = {
+    object: 'epcis.ObjectEvent',
+    aggregation: 'epcis.AggregationEvent',
+    transaction: 'epcis.TransactionEvent',
+    transformation: 'epcis.TransformationEvent'
+};
+/** 봉투의 `eventType` 이 EPCIS 사건인가 — 접두사 하나로 판정한다(클래스가 늘어도 그대로 산다). */
+export function isEpcisEventType(eventType) {
+    return typeof eventType === 'string' && eventType.startsWith('epcis.');
+}
 // ── GS1 EPC URI 헬퍼 (표준) ────────────────────────────────────────────────
 /** SSCC (물류단위: 팔레트/화물/트레일러) — 결정적 카운터 기반. */
 export function ssccUri(companyPrefix, serial) {

package/dist/flow-engine.d.ts

@@ -1,4 +1,5 @@
 import type { TestResult, ISOTime, MaterialQuantity, WorkCalendarEntry, EffectivePeriod, Effectivity, OffCalendarReason, ResourceProperty, ResourceClassDef, MaterialDefinition, Attention, TwinModelDef, CanonicalEnvelope, Command, CommandAck, EventHandler, EquipmentMotion, OeeMetrics, AssetState, GeneratorSpec, InterventionOutcome, OrderState, PersonState, ScenarioControl, ScenarioOverride, StateSnapshot, TwinKernel, Unsubscribe, LocationState, ItemState, EquipmentState, OrderStatusDelta, TaskState, TaskStatus, StructureShift, IdentityGroundingView, IdentityDeclaration, TestSpecificationCriterion, LocationObservation } from './contract.ts';
+import type { VocabularyElement } from './master-data.ts';
 import type { ReducerCheckpoint } from './observed-reducer.ts';
 import type { EpcisEvent, BizTransactionElement } from './epcis.ts';
 import type { AllocationPolicy, SlotView } from './allocation-policy.ts';
@@ -964,6 +965,16 @@ export declare abstract class FlowEngine implements TwinKernel {
      *
      * `tick` 과 섞어 쓰지 않는다 — 섞으면 무엇이 진실인지 알 수 없다(관측이 시뮬을 덮어쓴다).
      */
+    /**
+     * **마스터데이터를 받는다** — 변하지 않는 속성을 상태에 세운다(§`master-data`).
+     *
+     * 사건이 아니다. 그래서 구독자에게 흘리지 않고(저널에 적히지 않게) 상태만 세운다. 유통기한·로트번호가
+     * 이 문으로 온다 — 그 값이 갈 자리가 없어서 전량을 읽는 원본은 「들어오지 않은 것을 들어왔다」고
+     * 말해야 했다.
+     *
+     * 관측 모드가 아니면 아무 일도 하지 않는다(시뮬은 자기 상태를 자기가 만든다) — 그 사실을 수로 낸다.
+     */
+    applyMasterData(elements: readonly VocabularyElement[]): number;
     apply(envelope: CanonicalEnvelope): void;
     /** 관측분을 커널 상태로 옮긴다 — 필요할 때 한 번만(같은 규칙, 같은 씨앗 경로). */
     private settleObserved;

package/dist/flow-engine.js

@@ -2094,6 +2094,27 @@ export class FlowEngine {
      *
      * `tick` 과 섞어 쓰지 않는다 — 섞으면 무엇이 진실인지 알 수 없다(관측이 시뮬을 덮어쓴다).
      */
+    /**
+     * **마스터데이터를 받는다** — 변하지 않는 속성을 상태에 세운다(§`master-data`).
+     *
+     * 사건이 아니다. 그래서 구독자에게 흘리지 않고(저널에 적히지 않게) 상태만 세운다. 유통기한·로트번호가
+     * 이 문으로 온다 — 그 값이 갈 자리가 없어서 전량을 읽는 원본은 「들어오지 않은 것을 들어왔다」고
+     * 말해야 했다.
+     *
+     * 관측 모드가 아니면 아무 일도 하지 않는다(시뮬은 자기 상태를 자기가 만든다) — 그 사실을 수로 낸다.
+     */
+    applyMasterData(elements) {
+        if (!elements.length)
+            return 0;
+        if (!this.observer) {
+            this.observer = new ObservedReducer(this.boardDef ?? { locations: [], equipment: [] });
+            this.observeMode = true;
+        }
+        const n = this.observer.applyMasterData(elements);
+        /* 상태가 바뀌었으므로 다음 스냅샷·fork 에서 옮겨져야 한다 — 관측 반영과 같은 규율이다. */
+        this.observedDirty = true;
+        return n;
+    }
     apply(envelope) {
         if (!this.observer) {
             this.observer = new ObservedReducer(this.boardDef ?? { locations: [], equipment: [] });

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export * from './counterfactual.ts';
 export * from './forecast.ts';
 export * from './twin-observer.ts';
 export * from './event-journal.ts';
+export * from './master-data.ts';
 export * from './divergence.ts';
 export * from './epcis.ts';
 export * from './wms-profile.ts';

package/dist/index.js

@@ -5,6 +5,7 @@ export * from "./counterfactual.js";
 export * from "./forecast.js";
 export * from "./twin-observer.js";
 export * from "./event-journal.js";
+export * from "./master-data.js";
 export * from "./divergence.js";
 export * from "./epcis.js";
 export * from "./wms-profile.js";

package/dist/master-data.d.ts

@@ -0,0 +1,80 @@
+/** 표준 어휘 타입 — 이 세 가지가 우리 상태 축에 닿는다. 그 밖은 보관하고 알린다. */
+export declare const VOCABULARY_TYPE: {
+    /** 품목·로트 클래스의 속성 — 유통기한·로트번호가 여기 온다. */
+    readonly epcClass: "urn:epcglobal:epcis:vtype:EPCClass";
+    /** 관측 지점의 속성. */
+    readonly readPoint: "urn:epcglobal:epcis:vtype:ReadPoint";
+    /** 업무 자리의 속성. */
+    readonly bizLocation: "urn:epcglobal:epcis:vtype:BizLocation";
+};
+export type VocabularyType = (typeof VOCABULARY_TYPE)[keyof typeof VOCABULARY_TYPE];
+/** 어휘 요소 하나 — 표준의 모양. */
+export interface VocabularyElement {
+    /** 그 어휘에서의 식별자(클래스 식별자·자리 식별자). */
+    id: string;
+    /** 속성 — 이름을 해석하지 않고 그대로 든다. */
+    attributes: Record<string, unknown>;
+}
+/**
+ * 원본이 보내는 마스터데이터 한 건 — 어휘 타입과 함께 온다.
+ *
+ * 타입을 **받는다.** 로트 전용 문을 만들지 않는 이유는 자리·품목이 같은 통로로 들어와야 하고, 표준이
+ * 이미 타입으로 갈라 두었기 때문이다.
+ */
+export interface MasterDataRecord extends VocabularyElement {
+    vocabularyType: string;
+}
+/** 이 레코드가 마스터데이터인가 — 갈래 판정은 **커널이 한 곳에서** 한다(어휘 넷을 가르는 방식과 같다). */
+export declare function isMasterDataRecord(record: unknown): record is MasterDataRecord;
+export interface MasterDataResult {
+    accepted: MasterDataRecord[];
+    rejected: {
+        record: unknown;
+        errors: string[];
+    }[];
+}
+/**
+ * 마스터데이터를 받아들인다 — **거부한 것은 이유와 함께 남는다**(다른 어휘와 같은 규율).
+ *
+ * 빈 속성은 거부한다: 「이 로트에 대해 아무것도 모른다」를 보내는 것은 아무 뜻이 없고, 받아 두면
+ * 기존 값을 지우려는 것인지 아무 말도 아닌지 구별할 수 없다.
+ */
+export declare function ingestMasterData(records: MasterDataRecord | MasterDataRecord[] | undefined | null): MasterDataResult;
+/**
+ * 클래스 단위 마스터 표 — 관측 리듀서가 든다.
+ *
+ * 물품은 자리마다 따로 서지만(`클래스@자리`) 이 속성은 **클래스의 것**이다. 그래서 물품마다 복사해
+ * 두지 않고 클래스로 한 번 들고, 물품을 세울 때 본다. 마스터가 관측보다 늦게 와도 값이 서는 이유다.
+ */
+export declare class ClassMasterTable {
+    private byId;
+    /**
+     * 속성을 **합친다** — 덮지 않는다(한 번에 일부만 오는 원본이 있다). 바뀐 식별자를 돌려준다.
+     *
+     * ── 지우는 법 ───────────────────────────────────────────────────────────────
+     * 값에 `null` 을 실으면 **그 속성을 지운다**(「모름으로 되돌린다」). 합치기만 하면 원본에서 지운 값이
+     * 트윈에 영원히 남고, 그것을 표현할 방법이 없으면 「지웠다」와 「이번엔 말하지 않았다」가 같아진다.
+     *
+     * `undefined` 는 지우지 않는다 — 그것은 「이 진술에 그 속성이 없다」이고, 원본이 일부만 보내는
+     * 정상이다. 두 뜻을 갈라 둔다.
+     *
+     * 속성이 하나도 남지 않으면 그 요소를 표에서 버린다(빈 껍데기를 들고 있지 않는다).
+     */
+    merge(elements: readonly VocabularyElement[]): string[];
+    /**
+     * 그 식별자의 항목을 버린다 — **아무도 가리키지 않게 된 뒤**에만 부른다.
+     *
+     * 로트는 계속 새로 생기므로 이 표는 스스로 줄지 않는다. 하루 수백 로트면 1년에 수십만 항목이고,
+     * 그것을 아무도 지우지 않으면 재기동으로만 줄어든다(그리고 중간 저장본이 그만큼 커진다).
+     */
+    forget(id: string): boolean;
+    attributesOf(id: string | undefined): Record<string, unknown> | undefined;
+    get size(): number;
+    serialize(): Record<string, Record<string, unknown>>;
+    restore(saved: unknown): void;
+    clear(): void;
+}
+/** 마스터 속성에서 유통기한을 읽는다 — 사건의 `ilmd` 와 **같은 이름**을 본다. */
+export declare function expiryFromAttributes(attrs: Record<string, unknown> | undefined): number | undefined;
+/** 마스터 속성에서 로트 번호를 읽는다 — 사건의 `ilmd` 와 같은 이름. */
+export declare function lotFromAttributes(attrs: Record<string, unknown> | undefined): string | undefined;

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) — 비직렬 로트가 자리마다 갈릴 때만. */
@@ -180,6 +181,13 @@ export interface ReducerCheckpoint {
      * 공통 코드로 새어 든다. 그대로 담아 두고 되돌려 줄 뿐이다.
      */
     domain?: unknown;
+    /**
+     * **클래스 단위 마스터데이터** — 변하지 않는 속성(유통기한·로트번호)이 사는 자리(§`master-data`).
+     *
+     * 지난 기록에 적지 않는 값이므로 여기 담지 않으면 되세울 때 빈다. 변하지 않는 값이라 어느 시점의
+     * 저장본에서 꺼내도 같은 답이다.
+     */
+    classMaster?: Record<string, Record<string, unknown>>;
 }
 export declare class ObservedReducer {
     /** 로케이션 마스터 — 출처를 함께 들고 있다(마스터가 말한 자리 vs 관측으로 알게 된 자리). */
@@ -198,6 +206,13 @@ export declare class ObservedReducer {
      */
     private heard;
     private items;
+    /**
+     * **클래스 단위 마스터 표** — 변하지 않는 속성이 사는 자리(§`master-data`).
+     *
+     * 물품은 자리마다 따로 서지만(`클래스@자리`) 유통기한·로트번호는 **클래스의 것**이다. 그래서 물품마다
+     * 복사해 두지 않고 클래스로 한 번 들고, 물품을 세울 때 본다 — 마스터가 관측보다 늦게 와도 값이 선다.
+     */
+    private classMaster;
     private aggregation;
     /** 아직 관측되지 않은 자식의 담김 — 물품을 지어내지 않고 보류했다가 등장할 때 붙인다. */
     private pendingParent;
@@ -346,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]));

package/dist-cjs/index.cjs

@@ -29,6 +29,7 @@ __export(index_exports, {
   CAPABILITY_KEYS: () => CAPABILITY_KEYS,
   CBV_BIZSTEP: () => CBV_BIZSTEP,
   CMD: () => CMD,
+  ClassMasterTable: () => ClassMasterTable,
   DEMAND_WINDOW_MS: () => DEMAND_WINDOW_MS,
   DISP: () => DISP,
   DOMAIN_CATALOG: () => DOMAIN_CATALOG,
@@ -40,6 +41,7 @@ __export(index_exports, {
   EMS_TYPES: () => EMS_TYPES,
   ENERGY_EVENT: () => ENERGY_EVENT,
   EPCIS_CONTEXT: () => EPCIS_CONTEXT,
+  EPCIS_EVENT: () => EPCIS_EVENT,
   EQUIPMENT_LEVEL: () => EQUIPMENT_LEVEL,
   EmsKernel: () => EmsKernel,
   EventJournal: () => EventJournal,
@@ -70,6 +72,7 @@ __export(index_exports, {
   TwinRuntime: () => TwinRuntime,
   UTC_OFFSET: () => UTC_OFFSET,
   VOCABULARY_EXCEPTIONS: () => VOCABULARY_EXCEPTIONS,
+  VOCABULARY_TYPE: () => VOCABULARY_TYPE,
   WMS_LOCATION_TYPES: () => WMS_LOCATION_TYPES,
   WMS_TYPES: () => WMS_TYPES,
   WmsKernel: () => WmsKernel,
@@ -107,6 +110,7 @@ __export(index_exports, {
   electricityCost: () => electricityCost,
   energyIntensity: () => energyIntensity,
   energyOfWindows: () => energyOfWindows,
+  expiryFromAttributes: () => expiryFromAttributes,
   fefoPolicy: () => fefoPolicy,
   firstFitPolicy: () => firstFitPolicy,
   foldJobResponses: () => foldJobResponses,
@@ -123,13 +127,16 @@ __export(index_exports, {
   ingestEnergyEquipmentRecords: () => ingestEnergyEquipmentRecords,
   ingestEnergyGenerationRecords: () => ingestEnergyGenerationRecords,
   ingestEnergyRecords: () => ingestEnergyRecords,
+  ingestMasterData: () => ingestMasterData,
   ingestOperationalRecords: () => ingestOperationalRecords,
   isAggregationRecord: () => isAggregationRecord,
   isElectricalLocationType: () => isElectricalLocationType,
   isEnergyEquipmentRecord: () => isEnergyEquipmentRecord,
   isEnergyGenerationRecord: () => isEnergyGenerationRecord,
   isEnergyRecord: () => isEnergyRecord,
+  isEpcisEventType: () => isEpcisEventType,
   isEquipmentLevel: () => isEquipmentLevel,
+  isMasterDataRecord: () => isMasterDataRecord,
   isOperationalRecord: () => isOperationalRecord,
   isOrderTerminal: () => isOrderTerminal,
   isTransformationRecord: () => isTransformationRecord,
@@ -140,6 +147,7 @@ __export(index_exports, {
   levelOfLocationType: () => levelOfLocationType,
   lgtinClass: () => lgtinClass,
   locationStatusOf: () => locationStatusOf,
+  lotFromAttributes: () => lotFromAttributes,
   mapRecord: () => mapRecord,
   mapRecordChecked: () => mapRecordChecked,
   meetsTests: () => meetsTests,
@@ -1115,6 +1123,15 @@ var CBV_BIZSTEP = {
    */
   other: "urn:epcglobal:cbv:bizstep:other"
 };
+var EPCIS_EVENT = {
+  object: "epcis.ObjectEvent",
+  aggregation: "epcis.AggregationEvent",
+  transaction: "epcis.TransactionEvent",
+  transformation: "epcis.TransformationEvent"
+};
+function isEpcisEventType(eventType) {
+  return typeof eventType === "string" && eventType.startsWith("epcis.");
+}
 function ssccUri(companyPrefix, serial) {
   return `urn:epc:id:sscc:${companyPrefix}.${String(serial).padStart(10, "0")}`;
 }
@@ -1380,6 +1397,105 @@ function validateEpcisEvent(e) {
   return v;
 }
 
+// src/master-data.ts
+var VOCABULARY_TYPE = {
+  /** 품목·로트 클래스의 속성 — 유통기한·로트번호가 여기 온다. */
+  epcClass: "urn:epcglobal:epcis:vtype:EPCClass",
+  /** 관측 지점의 속성. */
+  readPoint: "urn:epcglobal:epcis:vtype:ReadPoint",
+  /** 업무 자리의 속성. */
+  bizLocation: "urn:epcglobal:epcis:vtype:BizLocation"
+};
+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);
+}
+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 \xB7 id \xB7 attributes \uAC00 \uC788\uC5B4\uC57C \uD55C\uB2E4");
+    else if (!Object.keys(r.attributes).length) errors.push("attributes \uAC00 \uBE44\uC5C8\uB2E4 \u2014 \uC544\uBB34 \uB73B\uC774 \uC5C6\uB294 \uC9C4\uC220\uC774\uB2E4");
+    if (errors.length) rejected.push({ record: r, errors });
+    else accepted.push({ vocabularyType: r.vocabularyType, id: r.id, attributes: { ...r.attributes } });
+  }
+  return { accepted, rejected };
+}
+var ClassMasterTable = class {
+  byId = /* @__PURE__ */ 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 !== void 0) 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) : void 0;
+  }
+  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();
+  }
+};
+function expiryFromAttributes(attrs) {
+  return readEpochMs(attrs?.[ILMD_ATTR.expiry]);
+}
+function lotFromAttributes(attrs) {
+  const v = attrs?.[ILMD_ATTR.lot];
+  return typeof v === "string" && v.trim() ? v.trim() : void 0;
+}
+function readEpochMs(raw) {
+  if (typeof raw === "number") return Number.isFinite(raw) ? raw : void 0;
+  if (typeof raw !== "string" || !raw.trim()) return void 0;
+  const at = Date.parse(raw);
+  return Number.isNaN(at) ? void 0 : at;
+}
+
 // src/observed-reducer.ts
 var UNKNOWN_TYPE = "unknown";
 function effectiveOf(r) {
@@ -1405,6 +1521,13 @@ var ObservedReducer = class {
    */
   heard = /* @__PURE__ */ new Map();
   items = /* @__PURE__ */ new Map();
+  /**
+   * **클래스 단위 마스터 표** — 변하지 않는 속성이 사는 자리(§`master-data`).
+   *
+   * 물품은 자리마다 따로 서지만(`클래스@자리`) 유통기한·로트번호는 **클래스의 것**이다. 그래서 물품마다
+   * 복사해 두지 않고 클래스로 한 번 들고, 물품을 세울 때 본다 — 마스터가 관측보다 늦게 와도 값이 선다.
+   */
+  classMaster = new ClassMasterTable();
   aggregation = /* @__PURE__ */ new Map();
   /** 아직 관측되지 않은 자식의 담김 — 물품을 지어내지 않고 보류했다가 등장할 때 붙인다. */
   pendingParent = /* @__PURE__ */ new Map();
@@ -1953,6 +2076,42 @@ var ObservedReducer = class {
    * 표준이 속성 이름을 정의하지 않으므로 모르는 이름은 해석하지 않는다(추측하지 않는다). 원문은
    * `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);
+      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] : void 0) ?? 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)) return raw;
@@ -1997,14 +2156,35 @@ var ObservedReducer = class {
       })(),
       /* 마스터데이터는 생겨날 때 한 번 정해진다 — 뒤 이벤트가 지우지 않게 기존 값을 남긴다. */
       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] : void 0) ?? cur?.lot
+      lot: parsedClass?.lot ?? parsedSelf.lot ?? (typeof patch.ilmd?.[ILMD_ATTR.lot] === "string" ? patch.ilmd[ILMD_ATTR.lot] : void 0) ?? lotFromAttributes(this.masterAttributesOf(classUri, epc)) ?? cur?.lot
     };
   }
   /** 이탈(DELETE) — 아이템 + 조립 자식(재귀) 제거. 화물 SSCC DELETE 시 팔레트도 함께 이탈. */
   remove(epc) {
+    const gone = this.items.get(epc);
     this.items.delete(epc);
+    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);
@@ -2122,8 +2302,13 @@ var ObservedReducer = class {
       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()
     };
   }
   /**
@@ -2139,6 +2324,7 @@ var ObservedReducer = class {
     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 !== void 0 ? { 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]));
@@ -4241,6 +4427,25 @@ var FlowEngine = class {
    *
    * `tick` 과 섞어 쓰지 않는다 — 섞으면 무엇이 진실인지 알 수 없다(관측이 시뮬을 덮어쓴다).
    */
+  /**
+   * **마스터데이터를 받는다** — 변하지 않는 속성을 상태에 세운다(§`master-data`).
+   *
+   * 사건이 아니다. 그래서 구독자에게 흘리지 않고(저널에 적히지 않게) 상태만 세운다. 유통기한·로트번호가
+   * 이 문으로 온다 — 그 값이 갈 자리가 없어서 전량을 읽는 원본은 「들어오지 않은 것을 들어왔다」고
+   * 말해야 했다.
+   *
+   * 관측 모드가 아니면 아무 일도 하지 않는다(시뮬은 자기 상태를 자기가 만든다) — 그 사실을 수로 낸다.
+   */
+  applyMasterData(elements) {
+    if (!elements.length) return 0;
+    if (!this.observer) {
+      this.observer = new ObservedReducer(this.boardDef ?? { locations: [], equipment: [] });
+      this.observeMode = true;
+    }
+    const n = this.observer.applyMasterData(elements);
+    this.observedDirty = true;
+    return n;
+  }
   apply(envelope) {
     if (!this.observer) {
       this.observer = new ObservedReducer(this.boardDef ?? { locations: [], equipment: [] });
@@ -9840,6 +10045,7 @@ function retiredVocabularyIn(line) {
   CAPABILITY_KEYS,
   CBV_BIZSTEP,
   CMD,
+  ClassMasterTable,
   DEMAND_WINDOW_MS,
   DISP,
   DOMAIN_CATALOG,
@@ -9851,6 +10057,7 @@ function retiredVocabularyIn(line) {
   EMS_TYPES,
   ENERGY_EVENT,
   EPCIS_CONTEXT,
+  EPCIS_EVENT,
   EQUIPMENT_LEVEL,
   EmsKernel,
   EventJournal,
@@ -9881,6 +10088,7 @@ function retiredVocabularyIn(line) {
   TwinRuntime,
   UTC_OFFSET,
   VOCABULARY_EXCEPTIONS,
+  VOCABULARY_TYPE,
   WMS_LOCATION_TYPES,
   WMS_TYPES,
   WmsKernel,
@@ -9918,6 +10126,7 @@ function retiredVocabularyIn(line) {
   electricityCost,
   energyIntensity,
   energyOfWindows,
+  expiryFromAttributes,
   fefoPolicy,
   firstFitPolicy,
   foldJobResponses,
@@ -9934,13 +10143,16 @@ function retiredVocabularyIn(line) {
   ingestEnergyEquipmentRecords,
   ingestEnergyGenerationRecords,
   ingestEnergyRecords,
+  ingestMasterData,
   ingestOperationalRecords,
   isAggregationRecord,
   isElectricalLocationType,
   isEnergyEquipmentRecord,
   isEnergyGenerationRecord,
   isEnergyRecord,
+  isEpcisEventType,
   isEquipmentLevel,
+  isMasterDataRecord,
   isOperationalRecord,
   isOrderTerminal,
   isTransformationRecord,
@@ -9951,6 +10163,7 @@ function retiredVocabularyIn(line) {
   levelOfLocationType,
   lgtinClass,
   locationStatusOf,
+  lotFromAttributes,
   mapRecord,
   mapRecordChecked,
   meetsTests,

package/package.json

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