@operato/twin-kernel 0.2.0 → 0.2.2

package/dist/observed-reducer.d.ts

@@ -0,0 +1,103 @@
+import type { AssetState, BoardDef, CanonicalEnvelope, NodeState, ItemState, MoverState, PersonState, TaskState, OrderState } from './contract.ts';
+/**
+ * 마스터 동기 — 선언적 로케이션 upsert/remove.
+ *
+ * 구조(로케이션·용량·구역 소속)는 이벤트가 말해 주는 것이 아니라 **원 시스템의 마스터**에서 온다.
+ * 최초 생성은 Face2 마스터 인제스트(host `ingestMaster`)가 하고, 그 뒤 현장이 바뀐 것(랙 증설·구역
+ * 재편·용량 변경)은 이 경로로 **기동 중에도** 반영된다 — 없으면 재기동해야 구조가 갱신된다.
+ */
+export interface MasterUpdate {
+    op: 'upsert' | 'remove';
+    node: {
+        id: string;
+        type?: string;
+        capacity?: number;
+        parallelism?: number;
+        parentId?: string;
+    };
+}
+export interface ProjectedState {
+    revision: number;
+    /**
+     * 받은 정정 선언들 — 상태에 반영하지 않은 것을 **밝힌다**.
+     * 비어 있지 않으면 "원 시스템이 정정을 보냈고 우리는 아직 반영하지 못했다" 는 뜻이다(조용한 무시 금지).
+     */
+    corrections?: {
+        declaredAt: string;
+        reason?: string;
+        correctiveEventIDs: string[];
+        eventID?: string;
+    }[];
+    nodes: NodeState[];
+    items: ItemState[];
+    /** 사람 — 등급·교대·투입. 인원을 선언하지 않은 트윈에서는 빈 배열. */
+    persons: PersonState[];
+    /** 물리 자산(반복사용) — 자산을 선언하지 않은 트윈에서는 빈 배열. */
+    assets: AssetState[];
+    tasks: TaskState[];
+    movers: MoverState[];
+    orders: OrderState[];
+}
+export declare class ObservedReducer {
+    /** 로케이션 마스터 — 출처를 함께 들고 있다(마스터가 말한 자리 vs 관측으로 알게 된 자리). */
+    private master;
+    private items;
+    private aggregation;
+    /** 아직 관측되지 않은 자식의 담김 — 물품을 지어내지 않고 보류했다가 등장할 때 붙인다. */
+    private pendingParent;
+    private tasks;
+    private movers;
+    private persons;
+    private assets;
+    private orders;
+    revision: number;
+    /** 받은 정정 선언 — 상태에 반영하지 않되 **버리지도 않는다**(소비처가 볼 수 있게). */
+    private corrections;
+    constructor(board: BoardDef);
+    /** 마스터 동기 — 로케이션 추가/변경/제거. */
+    applyMaster(u: MasterUpdate): void;
+    /**
+     * 관측된 로케이션을 구조로 승격 — **이벤트가 가르쳐 준 것을 구조에서 지우지 않는다.**
+     *
+     * 마스터에 없는 로케이션에서 물품이 관측되면, 예전에는 물품의 `location` 에만 남고 `nodes` 에는
+     * 나타나지 않았다. 그 결과 그 자리는 스키매틱에 없고, 점유가 집계되지 않고, 병목 주목이 뜰 수
+     * 없었다 — **사실은 들어왔는데 구조가 모르는 상태.** 이제 최소 형태로 승격한다:
+     * 종류는 모르므로 `unknown`, **용량은 비워 둔다**(발명하지 않는다), 출처는 `observed`.
+     *
+     * 출처를 표시하는 이유: 소비처가 "마스터가 말한 자리" 와 "관측으로 알게 된 자리" 를 구별해야 한다
+     * (보드에 좌표가 없고, 용량을 채워야 계획에 참여한다). 마스터 동기가 오면 `master` 로 승격된다.
+     */
+    private touchLocation;
+    /**
+     * 늦게 도착한 옛 이벤트를 걸러낸다 — **도착 순서 ≠ 발생 순서**.
+     *
+     * 실 연동에서는 순서가 뒤집힌다(재시도·큐·배치). 시각을 비교하지 않으면 **늦게 온 옛 이벤트가 최신
+     * 상태를 덮어써** 위치가 과거로 튄다. 표준이 발생(`eventTime`)과 기록(`recordTime`)을 나눠 둔 이유가
+     * 이것이므로, 대상별로 마지막으로 반영한 시각을 기억해 그보다 오래된 것은 무시한다.
+     *
+     * 판정 시각은 **발생 시각**을 쓴다(현장에서 일어난 순서가 사실). `recordTime` 은 같은 발생 시각이
+     * 겹칠 때의 보조 기준이다. 시각이 없으면 판정하지 않는다(있는 것만 가지고 판단한다).
+     */
+    private stale;
+    /** 대상별 마지막 반영 시각 — 순서 판정용(대상=EPC·작업·설비·오더 id). */
+    private lastAt;
+    /** 이벤트 1건 반영 — eventType 으로 EPCIS vs 운영 델타 분기. */
+    apply(e: CanonicalEnvelope): void;
+    private applyEpcis;
+    /**
+     * 물품 한 건 병합 — **아는 것을 잃지 않는다.** 새로 온 값이 우선, 없으면 기존 값 유지.
+     * 클래스 식별자(LGTIN/idpat)에서 품번·로트를 파생한다 — 소비처가 문자열을 자르지 않게.
+     */
+    /**
+     * 개체·로트 마스터데이터에서 만료 시각을 뽑는다 — **우리가 아는 이름일 때만.**
+     *
+     * 표준이 속성 이름을 정의하지 않으므로 모르는 이름은 해석하지 않는다(추측하지 않는다). 원문은
+     * `ilmd` 로 그대로 남으니 도메인이 자기 어휘로 읽을 수 있다.
+     */
+    private expiryOf;
+    private mergeItem;
+    /** 이탈(DELETE) — 아이템 + 조립 자식(재귀) 제거. 화물 SSCC DELETE 시 팔레트도 함께 이탈. */
+    private remove;
+    /** 현재 투영 State — 노드 점유는 아이템 위치 집계로 유도(pure projection). */
+    snapshot(): ProjectedState;
+}

package/dist/observed-reducer.js

@@ -0,0 +1,384 @@
+/*
+ * Observed Reducer — **이벤트를 접어 상태를 만드는 단 하나의 규칙.**
+ *
+ * 이 파일은 원래 미러 전용(`StateProjector`)이었다. 그런데 커널도 이벤트로 굴러갈 수 있게 되면서
+ * (`FlowEngine.apply`, 통합 P0) **두 구동이 같은 규칙을 써야** 한다 — 규칙이 두 벌이면 반드시
+ * 갈라진다(2026-08-01 하루에 아홉 곳, 적합성 하네스가 그 뒤 넷 더). 그래서 이름을 규칙 쪽으로 옮겼다.
+ * `StateProjector` 는 같은 것의 옛 이름으로 남는다(소비처 호환).
+ *
+ * (아래는 원래 주석 — 두 모드의 계약이 같다는 설계 근거.)
+ *
+ * State Projector — 이벤트 스트림 → State 투영 (모니터링의 "수동 미러").
+ *
+ * sim 모드: 커널이 State 를 능동 생산(내부 상태 + 이벤트 방출).
+ * live 모드: 외부(실 WMS)에서 이벤트가 도착 → 이 projector 가 State 를 재구성.
+ * → "계약 동일, 데이터원만 스왑"(execution-model.md §5, ADR-0010). 같은 이벤트면 같은 State.
+ *
+ * 두 갈래 이벤트를 함께 접는다:
+ *  - EPCIS(epcis.*)      → 재고/위치/조립 (What/Where)
+ *  - 운영 델타(task/equipment/order.status) → tasks·movers·orders (EPCIS 로 재구성 불가한 절반)
+ * 마스터(로케이션)는 board 초기화 + applyMaster 로 갱신(마스터 동기).
+ */
+import { OP_EVENT, nodeStatusOf } from "./contract.js";
+import { ILMD_ATTR, parseEpc } from "./epcis.js";
+/**
+ * 투영이 들고 있는 물품 — **계약(ItemState)을 축소하지 않는다.**
+ *
+ * 예전에는 epc·gtin·location·disposition 넷만 들고 있어서, 표준 이벤트로 정확히 받은 **수량·단위·
+ * 소속 팔레트**를 버렸다(2026-08-01 감사). 그 결과 미러 트윈의 재고가 "팔레트 1개" 로 세어졌다.
+ * 로트는 LGTIN 이면 식별자에서 파생한다. 만료(expiry)는 표준 자리가 `ilmd` 인데 아직 미지원이라
+ * **꾸미지 않고 비워 둔다**(없는 것을 만들지 않는다).
+ */
+/** 종류를 모르는 로케이션 — 관측으로 알게 됐지만 마스터가 아직 말해 주지 않은 자리. */
+const UNKNOWN_TYPE = 'unknown';
+export class ObservedReducer {
+    /** 로케이션 마스터 — 출처를 함께 들고 있다(마스터가 말한 자리 vs 관측으로 알게 된 자리). */
+    master = new Map();
+    items = new Map();
+    aggregation = new Map();
+    /** 아직 관측되지 않은 자식의 담김 — 물품을 지어내지 않고 보류했다가 등장할 때 붙인다. */
+    pendingParent = new Map(); // 자식 EPC → 부모(물류단위)
+    tasks = new Map();
+    movers = new Map();
+    persons = new Map();
+    assets = new Map();
+    orders = new Map();
+    revision = 0;
+    /** 받은 정정 선언 — 상태에 반영하지 않되 **버리지도 않는다**(소비처가 볼 수 있게). */
+    corrections = [];
+    constructor(board) {
+        for (const n of board.nodes)
+            this.master.set(n.id, { id: n.id, type: n.type, capacity: n.capacity, parallelism: n.parallelism, parentId: n.parentId, origin: 'master' });
+        // 무버 기준선(마스터) — equipment.status 델타로 갱신됨.
+        for (const m of board.movers)
+            this.movers.set(m.id, { id: m.id, kind: m.kind, status: 'idle', location: m.homeNode, origin: 'master' });
+        // 사람 기준선(마스터) — person.status 델타로 갱신됨.
+        for (const p of board.persons ?? [])
+            this.persons.set(p.id, { id: p.id, personnelClass: p.personnelClass, status: 'idle' });
+        for (const a of board.assets ?? [])
+            this.assets.set(a.id, { id: a.id, assetClass: a.assetClass, location: a.homeNode, status: 'idle' });
+    }
+    /** 마스터 동기 — 로케이션 추가/변경/제거. */
+    applyMaster(u) {
+        if (u.op === 'remove') {
+            this.master.delete(u.node.id);
+            return;
+        }
+        const cur = this.master.get(u.node.id);
+        /* **모르는 용량을 0 으로 뭉개지 않는다.** 0 은 "자리가 없다" 는 사실 주장이고, 미지정은 "모른다" 다.
+         * 계약(`NodeState.capacity`)이 선택 필드로 둔 이유가 이것이며, 0 으로 채우면 포화 판정이 거짓으로
+         * 성립하고 배정 정책이 그 노드를 영구히 배제한다. 그리고 upsert 가 **구역 소속(parentId)을 지우지
+         * 않는다** — 마스터가 말하지 않은 것은 기존 값을 지키는 것이 upsert 의 뜻이다. */
+        const capacity = u.node.capacity ?? cur?.capacity;
+        const parallelism = u.node.parallelism ?? cur?.parallelism;
+        this.master.set(u.node.id, {
+            id: u.node.id,
+            type: u.node.type ?? cur?.type ?? UNKNOWN_TYPE,
+            ...(capacity === undefined ? {} : { capacity }),
+            ...(parallelism === undefined ? {} : { parallelism }),
+            ...(u.node.parentId ?? cur?.parentId ? { parentId: u.node.parentId ?? cur?.parentId } : {}),
+            /* 마스터가 말한 것은 마스터 출처다 — 관측으로 알게 된 것(origin='observed')을 덮어 승격한다. */
+            origin: 'master'
+        });
+    }
+    /**
+     * 관측된 로케이션을 구조로 승격 — **이벤트가 가르쳐 준 것을 구조에서 지우지 않는다.**
+     *
+     * 마스터에 없는 로케이션에서 물품이 관측되면, 예전에는 물품의 `location` 에만 남고 `nodes` 에는
+     * 나타나지 않았다. 그 결과 그 자리는 스키매틱에 없고, 점유가 집계되지 않고, 병목 주목이 뜰 수
+     * 없었다 — **사실은 들어왔는데 구조가 모르는 상태.** 이제 최소 형태로 승격한다:
+     * 종류는 모르므로 `unknown`, **용량은 비워 둔다**(발명하지 않는다), 출처는 `observed`.
+     *
+     * 출처를 표시하는 이유: 소비처가 "마스터가 말한 자리" 와 "관측으로 알게 된 자리" 를 구별해야 한다
+     * (보드에 좌표가 없고, 용량을 채워야 계획에 참여한다). 마스터 동기가 오면 `master` 로 승격된다.
+     */
+    touchLocation(id) {
+        if (!id || this.master.has(id))
+            return;
+        this.master.set(id, { id, type: UNKNOWN_TYPE, origin: 'observed' });
+    }
+    /**
+     * 늦게 도착한 옛 이벤트를 걸러낸다 — **도착 순서 ≠ 발생 순서**.
+     *
+     * 실 연동에서는 순서가 뒤집힌다(재시도·큐·배치). 시각을 비교하지 않으면 **늦게 온 옛 이벤트가 최신
+     * 상태를 덮어써** 위치가 과거로 튄다. 표준이 발생(`eventTime`)과 기록(`recordTime`)을 나눠 둔 이유가
+     * 이것이므로, 대상별로 마지막으로 반영한 시각을 기억해 그보다 오래된 것은 무시한다.
+     *
+     * 판정 시각은 **발생 시각**을 쓴다(현장에서 일어난 순서가 사실). `recordTime` 은 같은 발생 시각이
+     * 겹칠 때의 보조 기준이다. 시각이 없으면 판정하지 않는다(있는 것만 가지고 판단한다).
+     */
+    stale(key, e) {
+        const at = Date.parse(String(e.eventTime ?? ''));
+        if (!Number.isFinite(at))
+            return false;
+        const recorded = Date.parse(String(e.data?.recordTime ?? ''));
+        const seen = this.lastAt.get(key);
+        if (seen === undefined) {
+            this.lastAt.set(key, { at, recorded: Number.isFinite(recorded) ? recorded : undefined });
+            return false;
+        }
+        if (at < seen.at)
+            return true;
+        if (at === seen.at && Number.isFinite(recorded) && seen.recorded !== undefined && recorded < seen.recorded)
+            return true;
+        this.lastAt.set(key, { at, recorded: Number.isFinite(recorded) ? recorded : seen.recorded });
+        return false;
+    }
+    /** 대상별 마지막 반영 시각 — 순서 판정용(대상=EPC·작업·설비·오더 id). */
+    lastAt = new Map();
+    /** 이벤트 1건 반영 — eventType 으로 EPCIS vs 운영 델타 분기. */
+    apply(e) {
+        this.revision++;
+        if (e.eventType.startsWith('epcis.')) {
+            this.applyEpcis(e.data, e);
+            return;
+        }
+        switch (e.eventType) {
+            case OP_EVENT.task: {
+                const d = e.data;
+                if (this.stale(`task:${d.taskId}`, e))
+                    return;
+                /* 커널이 실어 보낸 것을 그대로 담는다 — 진척·남은 시간·의도가 있어야 이 상태를 씨앗으로
+                 * 예측을 이어 굴릴 수 있고, 무자원이 설계인지(체류) 구별할 수 있다. */
+                this.touchLocation(d.fromNode);
+                this.touchLocation(d.toNode);
+                this.tasks.set(d.taskId, {
+                    id: d.taskId, kind: d.kind, status: d.status, fromNode: d.fromNode, toNode: d.toNode,
+                    itemRefs: d.itemRefs, resourceRef: d.resourceRef, orderId: d.orderId,
+                    intent: d.intent, progress: d.progress, remainingMs: d.remainingMs, durationMs: d.durationMs,
+                    startedAtSimMs: d.startedAtSimMs,
+                    ...(d.personnel?.length ? { personnel: d.personnel.slice() } : {}),
+                    ...(d.assets?.length ? { assets: d.assets.slice() } : {}),
+                    ...(d.resources?.length ? { resources: d.resources.slice() } : {})
+                });
+                break;
+            }
+            case OP_EVENT.equipment: {
+                const d = e.data;
+                if (this.stale(`mover:${d.moverId}`, e))
+                    return;
+                /* 마스터에 없던 자원도 관측으로 자란다(예전부터 그랬다) — 이제 그 사실을 출처로 표시하고,
+                 * 자원이 있다고 말하는 자리도 구조로 승격한다(로케이션만 자라지 않던 비대칭 해소). */
+                this.touchLocation(d.location);
+                const known = this.movers.get(d.moverId);
+                this.movers.set(d.moverId, { id: d.moverId, kind: d.kind, status: d.status, location: d.location, taskId: d.taskId, motion: d.motion, origin: known?.origin ?? 'observed' });
+                break;
+            }
+            case OP_EVENT.person: {
+                const d = e.data;
+                if (this.stale(`person:${d.personId}`, e))
+                    return;
+                /* 사람도 관측으로 자란다(자원과 같은 정책) — 마스터에 없던 사람이 이벤트에 나오면 승격한다. */
+                this.persons.set(d.personId, {
+                    id: d.personId,
+                    personnelClass: d.personnelClass ?? this.persons.get(d.personId)?.personnelClass,
+                    status: d.status,
+                    taskId: d.taskId,
+                    ...(d.offShift ? { offShift: true } : {})
+                });
+                break;
+            }
+            case OP_EVENT.asset: {
+                const d = e.data;
+                if (this.stale(`asset:${d.assetId}`, e))
+                    return;
+                const cur = this.assets.get(d.assetId);
+                this.assets.set(d.assetId, {
+                    id: d.assetId,
+                    assetClass: d.assetClass ?? cur?.assetClass,
+                    location: d.location ?? cur?.location,
+                    status: d.status,
+                    taskId: d.taskId,
+                    ...(d.carrying ? { carrying: d.carrying } : {})
+                });
+                this.touchLocation(d.location);
+                break;
+            }
+            case OP_EVENT.order: {
+                const d = e.data;
+                if (this.stale(`order:${d.orderId}`, e))
+                    return;
+                /* **진척으로 압축하지 않는다.** 예전에는 progress 만 남겨서, 미러에서 예측을 세우려면 저널을
+                 * 따로 읽어 오더 원값을 되찾아야 했다. 진척은 요청·이행에서 나오는 파생이다 — 파생을 남기고
+                 * 원본을 버리면 남은 데맨드를 재계획할 수 없다. */
+                this.orders.set(d.orderId, {
+                    id: d.orderId, kind: d.kind, status: d.status,
+                    progress: d.requested ? d.fulfilled / d.requested : 0,
+                    requested: d.requested, fulfilled: d.fulfilled,
+                    ...(d.lines?.length ? { lines: d.lines.map(l => ({ ...l })) } : {}),
+                    held: d.held
+                });
+                break;
+            }
+            // 알 수 없는 eventType 은 무시(전방 호환).
+        }
+    }
+    applyEpcis(ev, envelope) {
+        /* 정정 선언이 붙은 이벤트는 **새 사실이 아니다** — 앞선 이벤트를 취소·수정하는 선언이다.
+         * 무엇을 어떻게 되돌릴지는 도메인 판단이 필요하므로(원본을 찾아 역적용) 지금은 **상태에 반영하지
+         * 않는다.** 새 사실로 받아 재고를 흔드는 것보다 반영하지 않는 것이 정직하다. 정정 목록은 남겨
+         * 소비처가 볼 수 있게 한다(조용히 버리지 않는다). */
+        if (ev.errorDeclaration) {
+            this.corrections.push({
+                declaredAt: String(ev.errorDeclaration.declarationTime ?? ''),
+                reason: ev.errorDeclaration.reason,
+                correctiveEventIDs: ev.errorDeclaration.correctiveEventIDs ?? [],
+                eventID: ev.eventID
+            });
+            return;
+        }
+        if (ev.type === 'AggregationEvent') {
+            if (ev.action === 'ADD' && ev.childEPCs?.length) {
+                this.aggregation.set(ev.parentID, [...ev.childEPCs]);
+                /* 조립 관계를 물품에도 심는다 — 예전에는 내부 맵에만 두고 밖으로 내보내지 않아, 3D 가
+                 * "이 상자가 어느 팔레트에 실렸나" 를 알 수 없었다. */
+                for (const child of ev.childEPCs) {
+                    const cur = this.items.get(child);
+                    if (cur) {
+                        this.items.set(child, { ...cur, parent: ev.parentID });
+                        continue;
+                    }
+                    /* 아직 본 적 없는 자식 — **물품을 만들어 내지 않는다.** 조립 이벤트는 *담김*을 말할 뿐
+                     * *어디 있는지*를 말하지 않는데, 예전에는 `location: ''` 로 물품을 지어냈다(빈 문자열이
+                     * "모른다" 를 대신하던 자리). 담김은 잃지 않고 보류해 두었다가, 그 자식이 실제로 관측되는
+                     * 순간 붙인다. 그때 위치는 관측이 말해 준다. */
+                    this.pendingParent.set(child, ev.parentID);
+                }
+            }
+            else if (ev.action === 'DELETE') {
+                for (const child of this.aggregation.get(ev.parentID) ?? []) {
+                    const cur = this.items.get(child);
+                    if (cur)
+                        this.items.set(child, { ...cur, parent: undefined });
+                    this.pendingParent.delete(child);
+                }
+                this.aggregation.delete(ev.parentID);
+            }
+            return;
+        }
+        if (ev.type === 'TransactionEvent')
+            return; // 거래 연결 — 오더 상태는 order.status 델타로
+        if (ev.type === 'TransformationEvent') {
+            // 변환: 입력 소비(제거) → 출력 생산(readPoint 에 등장)
+            for (const epc of ev.inputEPCList ?? [])
+                this.remove(epc);
+            const loc = ev.readPoint?.id ?? '';
+            /* 변환의 마스터데이터는 **출력**에 적용된다(§7.3.8) — 입력에 붙이면 소비되는 것에 태생을 심는 셈. */
+            this.touchLocation(loc);
+            for (const epc of ev.outputEPCList ?? []) {
+                this.items.set(epc, this.mergeItem(epc, { location: loc, disposition: ev.disposition, ilmd: ev.ilmd }));
+            }
+            return;
+        }
+        // ObjectEvent
+        if (ev.action === 'DELETE') {
+            for (const epc of ev.epcList)
+                this.remove(epc);
+            return;
+        }
+        const loc = ev.readPoint?.id;
+        /* 수량 목록은 **클래스 + 수량 + 단위**를 함께 실어 온다 — 예전에는 클래스만 꺼내고 수량·단위를
+         * 버렸다. 클래스가 LGTIN 이면 품번과 로트가 그 안에 있으므로 파서로 뜯는다(문자열을 자르지 않는다). */
+        const q = ev.quantityList?.[0];
+        this.touchLocation(loc);
+        for (const epc of ev.epcList) {
+            /* 물품별 순서 판정 — 늦게 온 옛 관측이 최신 위치를 덮지 않게. */
+            if (envelope && this.stale(`item:${epc}`, envelope))
+                continue;
+            this.items.set(epc, this.mergeItem(epc, { location: loc, disposition: ev.disposition, ilmd: ev.ilmd }, q));
+        }
+        /* 개체 없이 수량만 오는 입고(비직렬 자재) — 표준이 허용하고 검증기도 유효로 판정한다.
+         * 이 경우 클래스 식별자 자체가 물품의 키다(로트 관리 자재는 LGTIN 이라 로트별로 갈린다). */
+        if (!ev.epcList?.length) {
+            for (const qe of ev.quantityList ?? []) {
+                if (qe?.epcClass)
+                    this.items.set(qe.epcClass, this.mergeItem(qe.epcClass, { location: loc, disposition: ev.disposition, ilmd: ev.ilmd }, qe));
+            }
+        }
+    }
+    /**
+     * 물품 한 건 병합 — **아는 것을 잃지 않는다.** 새로 온 값이 우선, 없으면 기존 값 유지.
+     * 클래스 식별자(LGTIN/idpat)에서 품번·로트를 파생한다 — 소비처가 문자열을 자르지 않게.
+     */
+    /**
+     * 개체·로트 마스터데이터에서 만료 시각을 뽑는다 — **우리가 아는 이름일 때만.**
+     *
+     * 표준이 속성 이름을 정의하지 않으므로 모르는 이름은 해석하지 않는다(추측하지 않는다). 원문은
+     * `ilmd` 로 그대로 남으니 도메인이 자기 어휘로 읽을 수 있다.
+     */
+    expiryOf(ilmd) {
+        const raw = ilmd?.[ILMD_ATTR.expiry];
+        if (typeof raw === 'number' && Number.isFinite(raw))
+            return raw;
+        if (typeof raw === 'string') {
+            const t = Date.parse(raw);
+            if (Number.isFinite(t))
+                return t;
+        }
+        return undefined;
+    }
+    mergeItem(epc, patch, q) {
+        const cur = this.items.get(epc);
+        /* 클래스는 수량 목록에서 오거나, 물품 자신이 클래스 식별자일 수 있다(비직렬 입고). */
+        const parsedClass = q?.epcClass ? parseEpc(q.epcClass) : undefined;
+        const parsedSelf = parseEpc(epc);
+        /* `gtin` 은 **클래스 URI 원문**이다(오더 매칭이 이 값을 쓴다 — 뜻을 바꾸면 조용히 안 맞는다).
+         * 파서로 뜯은 품번 키·로트는 **별도 필드**로 얹는다. */
+        const classUri = q?.epcClass ?? (parsedSelf.instance ? undefined : epc);
+        return {
+            epc,
+            gtin: classUri ?? cur?.gtin,
+            gtinKey: parsedClass?.gtinKey ?? parsedSelf.gtinKey ?? cur?.gtinKey,
+            location: patch.location ?? cur?.location ?? '',
+            disposition: patch.disposition ?? cur?.disposition,
+            parent: cur?.parent ?? this.pendingParent.get(epc),
+            qty: q?.quantity ?? cur?.qty,
+            uom: q?.uom ?? cur?.uom,
+            /* 마스터데이터는 생겨날 때 한 번 정해진다 — 뒤 이벤트가 지우지 않게 기존 값을 남긴다. */
+            ilmd: patch.ilmd ?? cur?.ilmd,
+            expiry: this.expiryOf(patch.ilmd) ?? cur?.expiry,
+            /* 로트는 LGTIN(식별자)에서 오지만, 직렬 개체는 마스터데이터에 실려 온다. */
+            lot: parsedClass?.lot ?? parsedSelf.lot ?? (typeof patch.ilmd?.[ILMD_ATTR.lot] === 'string' ? patch.ilmd[ILMD_ATTR.lot] : undefined) ?? cur?.lot
+        };
+    }
+    /** 이탈(DELETE) — 아이템 + 조립 자식(재귀) 제거. 화물 SSCC DELETE 시 팔레트도 함께 이탈. */
+    remove(epc) {
+        this.items.delete(epc);
+        const children = this.aggregation.get(epc);
+        if (children) {
+            this.aggregation.delete(epc);
+            for (const c of children)
+                this.remove(c);
+        }
+    }
+    /** 현재 투영 State — 노드 점유는 아이템 위치 집계로 유도(pure projection). */
+    snapshot() {
+        const occ = new Map();
+        for (const it of this.items.values())
+            occ.set(it.location, (occ.get(it.location) ?? 0) + 1);
+        return {
+            revision: this.revision,
+            ...(this.corrections.length ? { corrections: this.corrections.map(c => ({ ...c })) } : {}),
+            nodes: [...this.master.values()].map(n => {
+                const occupancy = occ.get(n.id) ?? 0;
+                const status = nodeStatusOf({ occupancy, capacity: n.capacity });
+                return {
+                    id: n.id, type: n.type, occupancy,
+                    ...(status ? { status } : {}),
+                    /* 용량 미상은 **키를 만들지 않는다** — 0 으로 실으면 "자리 없음" 이라는 없는 사실이 생긴다. */
+                    ...(n.capacity === undefined ? {} : { capacity: n.capacity }),
+                    ...(n.parallelism === undefined ? {} : { parallelism: n.parallelism }),
+                    ...(n.parentId ? { parentId: n.parentId } : {}),
+                    origin: n.origin
+                };
+            }),
+            /* 들고 있는 것을 전부 내보낸다 — 축소하면 그 자리에서 정보가 사라진다. */
+            items: [...this.items.values()].map(i => ({ ...i })),
+            persons: [...this.persons.values()].map(p => ({ ...p })),
+            assets: [...this.assets.values()].map(a => ({ ...a })),
+            tasks: [...this.tasks.values()].map(t => ({ ...t })),
+            movers: [...this.movers.values()].map(m => ({ ...m })),
+            orders: [...this.orders.values()].map(o => ({ ...o }))
+        };
+    }
+}

package/dist/state-projector.d.ts

@@ -1,100 +1,2 @@
-import type { AssetState, BoardDef, CanonicalEnvelope, NodeState, ItemState, MoverState, PersonState, TaskState, OrderState } from './contract.ts';
-/**
- * 마스터 동기 — 선언적 로케이션 upsert/remove.
- *
- * 구조(로케이션·용량·구역 소속)는 이벤트가 말해 주는 것이 아니라 **원 시스템의 마스터**에서 온다.
- * 최초 생성은 Face2 마스터 인제스트(host `ingestMaster`)가 하고, 그 뒤 현장이 바뀐 것(랙 증설·구역
- * 재편·용량 변경)은 이 경로로 **기동 중에도** 반영된다 — 없으면 재기동해야 구조가 갱신된다.
- */
-export interface MasterUpdate {
-    op: 'upsert' | 'remove';
-    node: {
-        id: string;
-        type?: string;
-        capacity?: number;
-        parentId?: string;
-    };
-}
-export interface ProjectedState {
-    revision: number;
-    /**
-     * 받은 정정 선언들 — 상태에 반영하지 않은 것을 **밝힌다**.
-     * 비어 있지 않으면 "원 시스템이 정정을 보냈고 우리는 아직 반영하지 못했다" 는 뜻이다(조용한 무시 금지).
-     */
-    corrections?: {
-        declaredAt: string;
-        reason?: string;
-        correctiveEventIDs: string[];
-        eventID?: string;
-    }[];
-    nodes: NodeState[];
-    items: ItemState[];
-    /** 사람 — 등급·교대·투입. 인원을 선언하지 않은 트윈에서는 빈 배열. */
-    persons: PersonState[];
-    /** 물리 자산(반복사용) — 자산을 선언하지 않은 트윈에서는 빈 배열. */
-    assets: AssetState[];
-    tasks: TaskState[];
-    movers: MoverState[];
-    orders: OrderState[];
-}
-export declare class StateProjector {
-    /** 로케이션 마스터 — 출처를 함께 들고 있다(마스터가 말한 자리 vs 관측으로 알게 된 자리). */
-    private master;
-    private items;
-    private aggregation;
-    private tasks;
-    private movers;
-    private persons;
-    private assets;
-    private orders;
-    revision: number;
-    /** 받은 정정 선언 — 상태에 반영하지 않되 **버리지도 않는다**(소비처가 볼 수 있게). */
-    private corrections;
-    constructor(board: BoardDef);
-    /** 마스터 동기 — 로케이션 추가/변경/제거. */
-    applyMaster(u: MasterUpdate): void;
-    /**
-     * 관측된 로케이션을 구조로 승격 — **이벤트가 가르쳐 준 것을 구조에서 지우지 않는다.**
-     *
-     * 마스터에 없는 로케이션에서 물품이 관측되면, 예전에는 물품의 `location` 에만 남고 `nodes` 에는
-     * 나타나지 않았다. 그 결과 그 자리는 스키매틱에 없고, 점유가 집계되지 않고, 병목 주목이 뜰 수
-     * 없었다 — **사실은 들어왔는데 구조가 모르는 상태.** 이제 최소 형태로 승격한다:
-     * 종류는 모르므로 `unknown`, **용량은 비워 둔다**(발명하지 않는다), 출처는 `observed`.
-     *
-     * 출처를 표시하는 이유: 소비처가 "마스터가 말한 자리" 와 "관측으로 알게 된 자리" 를 구별해야 한다
-     * (보드에 좌표가 없고, 용량을 채워야 계획에 참여한다). 마스터 동기가 오면 `master` 로 승격된다.
-     */
-    private touchLocation;
-    /**
-     * 늦게 도착한 옛 이벤트를 걸러낸다 — **도착 순서 ≠ 발생 순서**.
-     *
-     * 실 연동에서는 순서가 뒤집힌다(재시도·큐·배치). 시각을 비교하지 않으면 **늦게 온 옛 이벤트가 최신
-     * 상태를 덮어써** 위치가 과거로 튄다. 표준이 발생(`eventTime`)과 기록(`recordTime`)을 나눠 둔 이유가
-     * 이것이므로, 대상별로 마지막으로 반영한 시각을 기억해 그보다 오래된 것은 무시한다.
-     *
-     * 판정 시각은 **발생 시각**을 쓴다(현장에서 일어난 순서가 사실). `recordTime` 은 같은 발생 시각이
-     * 겹칠 때의 보조 기준이다. 시각이 없으면 판정하지 않는다(있는 것만 가지고 판단한다).
-     */
-    private stale;
-    /** 대상별 마지막 반영 시각 — 순서 판정용(대상=EPC·작업·설비·오더 id). */
-    private lastAt;
-    /** 이벤트 1건 반영 — eventType 으로 EPCIS vs 운영 델타 분기. */
-    apply(e: CanonicalEnvelope): void;
-    private applyEpcis;
-    /**
-     * 물품 한 건 병합 — **아는 것을 잃지 않는다.** 새로 온 값이 우선, 없으면 기존 값 유지.
-     * 클래스 식별자(LGTIN/idpat)에서 품번·로트를 파생한다 — 소비처가 문자열을 자르지 않게.
-     */
-    /**
-     * 개체·로트 마스터데이터에서 만료 시각을 뽑는다 — **우리가 아는 이름일 때만.**
-     *
-     * 표준이 속성 이름을 정의하지 않으므로 모르는 이름은 해석하지 않는다(추측하지 않는다). 원문은
-     * `ilmd` 로 그대로 남으니 도메인이 자기 어휘로 읽을 수 있다.
-     */
-    private expiryOf;
-    private mergeItem;
-    /** 이탈(DELETE) — 아이템 + 조립 자식(재귀) 제거. 화물 SSCC DELETE 시 팔레트도 함께 이탈. */
-    private remove;
-    /** 현재 투영 State — 노드 점유는 아이템 위치 집계로 유도(pure projection). */
-    snapshot(): ProjectedState;
-}
+export { ObservedReducer, ObservedReducer as StateProjector } from './observed-reducer.ts';
+export type { MasterUpdate, ProjectedState } from './observed-reducer.ts';