@operato/twin-kernel 0.3.0 → 0.4.0

package/dist/observed-reducer.js

@@ -19,7 +19,7 @@
  *  - 운영 델타(task/equipment/order.status) → tasks·equipment·orders (EPCIS 로 재구성 불가한 절반)
  * 마스터(로케이션)는 board 초기화 + applyMaster 로 갱신(마스터 동기).
  */
-import { OP_EVENT, locationStatusOf, readBoardEquipment, readBoardLocations, readBoardAssets } from "./contract.js";
+import { OP_EVENT, locationStatusOf, readBoardEquipment, readBoardLocations, readBoardAssets, effectivityAt, offCalendarAt, offCalendarReasonAt, activeShiftAt } from "./contract.js";
 import { ILMD_ATTR, parseEpc } from "./epcis.js";
 /**
  * 투영이 들고 있는 물품 — **계약(ItemState)을 축소하지 않는다.**
@@ -31,6 +31,13 @@ import { ILMD_ATTR, parseEpc } from "./epcis.js";
  */
 /** 종류를 모르는 로케이션 — 관측으로 알게 됐지만 마스터가 아직 말해 주지 않은 자리. */
 const UNKNOWN_TYPE = 'unknown';
+/** 선언된 유효 기간만 뽑는다 — 시뮬 쪽 `effectiveOnly` 와 같은 규칙(빈 필드를 만들지 않는다). */
+function effectiveOf(r) {
+    return {
+        ...(r?.effectiveStart ? { effectiveStart: r.effectiveStart } : {}),
+        ...(r?.effectiveEnd ? { effectiveEnd: r.effectiveEnd } : {})
+    };
+}
 export class ObservedReducer {
     /** 로케이션 마스터 — 출처를 함께 들고 있다(마스터가 말한 자리 vs 관측으로 알게 된 자리). */
     master = new Map();
@@ -46,17 +53,101 @@ export class ObservedReducer {
     revision = 0;
     /** 받은 정정 선언 — 상태에 반영하지 않되 **버리지도 않는다**(소비처가 볼 수 있게). */
     corrections = [];
+    /**
+     * 자원별 **교대 선언** — 미러가 "지금 근무 중인가" 를 스스로 판정하기 위한 재료.
+     *
+     * 상태(`EquipmentState`)에 넣지 않는다: 시뮬 스냅샷도 이것을 내보내지 않으므로 넣으면 두 구동이
+     * 갈라진다(적합성 하네스가 `mirrorOnly` 로 잡는다). 이것은 **판정의 입력**이고, 나가는 것은 판정뿐이다.
+     */
+    shifts = new Map();
+    /** 시각 해석 기준(보드 선언) — 없으면 UTC. 캘린더의 `HH:MM` 이 어느 기준인지 정한다. */
+    utcOffsetMinutes;
     constructor(board) {
+        this.utcOffsetMinutes = board.utcOffsetMinutes;
         for (const n of readBoardLocations(board))
             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 readBoardEquipment(board))
-            this.equipment.set(m.id, { id: m.id, kind: m.kind, status: 'idle', location: m.homeLocation, homeLocation: m.homeLocation, ...(m.properties ? { properties: m.properties } : {}), ...(m.testSpecificationIds ? { testSpecificationIds: m.testSpecificationIds } : {}), origin: 'master' });
+            this.equipment.set(m.id, { id: m.id, kind: m.kind, status: 'idle', location: m.homeLocation, homeLocation: m.homeLocation, ...(m.properties ? { properties: m.properties } : {}), ...(m.testSpecificationIds ? { testSpecificationIds: m.testSpecificationIds } : {}), ...effectiveOf(m), origin: 'master' });
         // 사람 기준선(마스터) — person.status 델타로 갱신됨.
         for (const p of board.persons ?? [])
-            this.persons.set(p.id, { id: p.id, personnelClassIds: p.personnelClassIds, status: 'idle', ...(p.homeLocation ? { location: p.homeLocation } : {}), ...(p.properties ? { properties: p.properties } : {}), ...(p.testSpecificationIds ? { testSpecificationIds: p.testSpecificationIds } : {}) });
+            this.persons.set(p.id, { id: p.id, personnelClassIds: p.personnelClassIds, status: 'idle', ...(p.homeLocation ? { location: p.homeLocation } : {}), ...(p.properties ? { properties: p.properties } : {}), ...(p.testSpecificationIds ? { testSpecificationIds: p.testSpecificationIds } : {}), ...effectiveOf(p) });
+        /* 교대 선언은 **미러도 들고 있어야 한다** — 설비 델타에는 `offShift` 자리조차 없어서, 그것 없이는
+           미러의 설비가 점심 휴게 중에도 "대기" 로 보였다. */
+        for (const m of readBoardEquipment(board))
+            this.rememberShift(`eq:${m.id}`, m);
+        for (const p of board.persons ?? [])
+            this.rememberShift(`person:${p.id}`, p);
         for (const a of readBoardAssets(board))
-            this.assets.set(a.id, { id: a.id, assetClassIds: a.assetClassIds, location: a.homeLocation, status: 'idle', ...(a.properties ? { properties: a.properties } : {}), ...(a.testSpecificationIds ? { testSpecificationIds: a.testSpecificationIds } : {}) });
+            this.assets.set(a.id, { id: a.id, assetClassIds: a.assetClassIds, location: a.homeLocation, status: 'idle', ...(a.properties ? { properties: a.properties } : {}), ...(a.testSpecificationIds ? { testSpecificationIds: a.testSpecificationIds } : {}), ...effectiveOf(a) });
+    }
+    /**
+     * **구조를 갈아탄다** — 관측된 사실은 지키고 토폴로지만 새 선언으로 바꾼다.
+     *
+     * 공장은 바뀐다. 도장 부스를 넷 더 놓고, 라인을 하나 접는다. 그런데 지금까지는 구조가 바뀌면
+     * **그 트윈의 저널을 통째로 지우는 것**이 유일한 길이었다 — 안 지우면 옛 이벤트를 새 공장에 대고
+     * 접게 되어 이력이 거짓말을 한다. 역사를 잃거나 거짓말을 하거나, 둘뿐이었다.
+     *
+     * 셋째 길이 이것이다: 이벤트가 **자기 구조를 달고** 다니고, 재생은 구조가 바뀌는 지점에서 여기를
+     * 불러 갈아탄 뒤 이어 접는다. 그러면 "그때 그 공장의 사실" 로 계속 읽힌다.
+     *
+     * ── 무엇을 지키고 무엇을 버리는가 ───────────────────────────────────────
+     * **관측은 지킨다** — 물품·오더·작업·집합은 구조와 무관한 사실이다(팔레트는 부스를 늘려도 그대로다).
+     * **사라진 자원은 버린다** — 없어진 설비의 상태를 계속 들고 있으면 화면이 없는 설비를 그린다.
+     * 다만 **몇 개를 버렸는지 돌려준다.** 조용히 사라지면 사용자는 수가 줄어든 것을 눈치채지 못한다.
+     *
+     * 관측으로 알게 된 자리(`origin: 'observed'`)는 **새 마스터에 없어도 남긴다** — 마스터가 모르는
+     * 자리에서 물건이 실제로 보였다는 사실은 구조를 바꾼다고 사라지지 않는다.
+     */
+    adoptStructure(board) {
+        this.utcOffsetMinutes = board.utcOffsetMinutes;
+        const locations = readBoardLocations(board);
+        const declaredLocationIds = new Set(locations.map(n => n.id));
+        let locationsAdded = 0;
+        let locationsDropped = 0;
+        for (const [id, cur] of [...this.master]) {
+            if (declaredLocationIds.has(id) || cur.origin === 'observed')
+                continue;
+            this.master.delete(id);
+            locationsDropped++;
+        }
+        for (const n of locations) {
+            if (!this.master.has(n.id))
+                locationsAdded++;
+            this.master.set(n.id, { id: n.id, type: n.type, capacity: n.capacity, parallelism: n.parallelism, parentId: n.parentId, origin: 'master' });
+        }
+        /* 자원은 **선언이 전부다** — 관측으로 생기지 않는다(설비는 이벤트가 만들어 내지 않는다).
+           그래서 새 선언에 없으면 없는 것이고, 남아 있는 것은 지금까지의 상태를 그대로 이어 간다. */
+        const equipment = readBoardEquipment(board);
+        const assets = readBoardAssets(board);
+        const persons = board.persons ?? [];
+        const dropMissing = (map, declared) => {
+            const ids = new Set(declared.map(d => d.id));
+            let dropped = 0;
+            for (const id of [...map.keys()])
+                if (!ids.has(id)) {
+                    map.delete(id);
+                    dropped++;
+                }
+            return dropped;
+        };
+        const equipmentDropped = dropMissing(this.equipment, equipment);
+        const personsDropped = dropMissing(this.persons, persons);
+        const assetsDropped = dropMissing(this.assets, assets);
+        for (const m of equipment) {
+            if (!this.equipment.has(m.id))
+                this.equipment.set(m.id, { id: m.id, kind: m.kind, status: 'idle', location: m.homeLocation, homeLocation: m.homeLocation, ...(m.properties ? { properties: m.properties } : {}), ...(m.testSpecificationIds ? { testSpecificationIds: m.testSpecificationIds } : {}), ...effectiveOf(m), origin: 'master' });
+            this.rememberShift(`eq:${m.id}`, m);
+        }
+        for (const p of persons) {
+            if (!this.persons.has(p.id))
+                this.persons.set(p.id, { id: p.id, personnelClassIds: p.personnelClassIds, status: 'idle', ...(p.homeLocation ? { location: p.homeLocation } : {}), ...(p.properties ? { properties: p.properties } : {}), ...(p.testSpecificationIds ? { testSpecificationIds: p.testSpecificationIds } : {}), ...effectiveOf(p) });
+            this.rememberShift(`person:${p.id}`, p);
+        }
+        for (const a of assets)
+            if (!this.assets.has(a.id))
+                this.assets.set(a.id, { id: a.id, assetClassIds: a.assetClassIds, location: a.homeLocation, status: 'idle', ...(a.properties ? { properties: a.properties } : {}), ...(a.testSpecificationIds ? { testSpecificationIds: a.testSpecificationIds } : {}), ...effectiveOf(a) });
+        return { locationsAdded, locationsDropped, equipmentDropped, personsDropped, assetsDropped };
     }
     /** 마스터 동기 — 로케이션 추가/변경/제거. */
     applyMaster(u) {
@@ -109,6 +200,8 @@ export class ObservedReducer {
      */
     stale(key, e) {
         const at = Date.parse(String(e.eventTime ?? ''));
+        if (Number.isFinite(at) && (this.observedAtMs === undefined || at > this.observedAtMs))
+            this.observedAtMs = at;
         if (!Number.isFinite(at))
             return false;
         const recorded = Date.parse(String(e.data?.recordTime ?? ''));
@@ -126,6 +219,14 @@ export class ObservedReducer {
     }
     /** 대상별 마지막 반영 시각 — 순서 판정용(대상=EPC·작업·설비·오더 id). */
     lastAt = new Map();
+    /**
+     * **미러의 "지금"** — 지금까지 들은 것 중 가장 늦은 발생 시각.
+     *
+     * 미러는 스스로 시간을 굴리지 않지만, 시각으로만 일어나는 사실(유효 기간 만료)을 판정하려면 기준이
+     * 필요하다. 미러의 정직한 기준은 **"내가 마지막으로 들은 시점"** 이다. 아무것도 못 들었으면
+     * 판정하지 않는다(모르면 단정하지 않는다).
+     */
+    observedAtMs;
     /** 이벤트 1건 반영 — eventType 으로 EPCIS vs 운영 델타 분기. */
     apply(e) {
         this.revision++;
@@ -149,7 +250,12 @@ export class ObservedReducer {
                     startedAtSimMs: d.startedAtSimMs,
                     ...(d.personnel?.length ? { personnel: d.personnel.slice() } : {}),
                     ...(d.assets?.length ? { assets: d.assets.slice() } : {}),
-                    ...(d.resources?.length ? { resources: d.resources.slice() } : {})
+                    ...(d.resources?.length ? { resources: d.resources.slice() } : {}),
+                    /* 실제 자재 이동 — 인원·설비와 같은 채널로 온다(실적을 한 곳에서 읽는다). */
+                    ...(d.materialActual?.length ? { materialActual: d.materialActual.map(r => ({ ...r })) } : {}),
+                    ...(d.priority !== undefined ? { priority: d.priority } : {}),
+                    ...(d.startTime ? { startTime: d.startTime } : {}),
+                    ...(d.endTime ? { endTime: d.endTime } : {})
                 });
                 break;
             }
@@ -165,7 +271,10 @@ export class ObservedReducer {
                    마스터로 알던 소속을 관측 델타 하나가 지워 버리면 그 설비가 롤업에서 통째로 빠진다.
                    소속은 자주 바뀌는 사실이 아니므로 침묵을 "소속 없음" 으로 읽지 않는다. */
                 const homeLocation = d.homeLocation ?? known?.homeLocation;
-                this.equipment.set(d.moverId, { id: d.moverId, kind: d.kind, status: d.status, location: d.location, ...(homeLocation ? { homeLocation } : {}), taskId: d.taskId, motion: d.motion, origin: known?.origin ?? 'observed' });
+                /* 유효 기간은 **마스터 사실**이므로 침묵을 "없어졌다" 로 읽지 않고 아는 값을 지킨다.
+                   판정은 여기서 하지 않는다 — `snapshot()` 이 관측 시각으로 `effectivityAt` 을 부른다. */
+                const eqPeriod = d.effectiveStart || d.effectiveEnd ? effectiveOf(d) : effectiveOf(known);
+                this.equipment.set(d.moverId, { id: d.moverId, kind: d.kind, status: d.status, location: d.location, ...(homeLocation ? { homeLocation } : {}), taskId: d.taskId, motion: d.motion, origin: known?.origin ?? 'observed', ...eqPeriod, ...(d.held ? { held: true } : {}) });
                 break;
             }
             case OP_EVENT.person: {
@@ -184,7 +293,11 @@ export class ObservedReducer {
                     ...((d.location ?? known?.location) ? { location: d.location ?? known?.location } : {}),
                     ...(known?.properties ? { properties: known.properties } : {}),
                     ...(known?.testSpecificationIds ? { testSpecificationIds: known.testSpecificationIds } : {}),
-                    ...(d.offShift ? { offShift: true } : {})
+                    /* 델타의 `offShift` 는 **선언이 없을 때만** 받는다 — 선언이 있으면 `snapshot()` 이 시각으로
+                       판정하고, 저장값을 함께 두면 교대 안으로 돌아왔을 때 옛 `true` 가 남는다(두 출처 = 갈라짐).
+                       남겨 두는 이유는 캘린더 없는 옛 저널 재생이다. */
+                    ...(d.offShift && !this.shifts.has(`person:${d.personId}`) ? { offShift: true } : {}),
+                    ...(d.effectiveStart || d.effectiveEnd ? effectiveOf(d) : effectiveOf(known))
                 });
                 break;
             }
@@ -199,7 +312,8 @@ export class ObservedReducer {
                     location: d.location ?? cur?.location,
                     status: d.status,
                     taskId: d.taskId,
-                    ...(d.carrying ? { carrying: d.carrying } : {})
+                    ...(d.carrying ? { carrying: d.carrying } : {}),
+                    ...(d.effectiveStart || d.effectiveEnd ? effectiveOf(d) : effectiveOf(cur))
                 });
                 this.touchLocation(d.location);
                 break;
@@ -216,6 +330,9 @@ export class ObservedReducer {
                     progress: d.requested ? d.fulfilled / d.requested : 0,
                     requested: d.requested, fulfilled: d.fulfilled,
                     ...(d.lines?.length ? { lines: d.lines.map(l => ({ ...l })) } : {}),
+                    ...(d.priority !== undefined ? { priority: d.priority } : {}),
+                    ...(d.startTime ? { startTime: d.startTime } : {}),
+                    ...(d.endTime ? { endTime: d.endTime } : {}),
                     held: d.held
                 });
                 break;
@@ -289,20 +406,33 @@ export class ObservedReducer {
         const loc = ev.readPoint?.id;
         /* 수량 목록은 **클래스 + 수량 + 단위**를 함께 실어 온다 — 예전에는 클래스만 꺼내고 수량·단위를
          * 버렸다. 클래스가 LGTIN 이면 품번과 로트가 그 안에 있으므로 파서로 뜯는다(문자열을 자르지 않는다). */
-        const q = ev.quantityList?.[0];
+        /* **전부 받는다.** 예전에는 `[0]` 만 써서 나머지를 버렸다 — 표준은 `Quantity` 를 복수로 두고,
+           실 데이터는 같은 로트를 여러 단위로 싣는다(100 EA · 250 KG). 버리면 조용히 잘린다. */
+        const all = ev.quantityList ?? [];
+        const q = all[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));
+            this.items.set(epc, this.mergeItem(epc, { location: loc, disposition: ev.disposition, ilmd: ev.ilmd }, q, all));
         }
         /* 개체 없이 수량만 오는 입고(비직렬 자재) — 표준이 허용하고 검증기도 유효로 판정한다.
          * 이 경우 클래스 식별자 자체가 물품의 키다(로트 관리 자재는 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));
+                if (!qe?.epcClass)
+                    continue;
+                /* 이 클래스에 대해 선언된 것만 모은다 — 다른 클래스의 수량을 섞으면 거짓이 된다. */
+                const mine = all.filter(x => x.epcClass === qe.epcClass);
+                /*
+                 * **자리마다 한 줄** — 표준 `MaterialSubLot`(각자 `StorageLocation`·`Quantity`).
+                 *
+                 * 예전에는 클래스 식별자 하나를 키로 써서, 같은 로트가 두 자리에 있으면 **뒤에 온 관측이 앞을
+                 * 덮었다**(rack-1 의 100개가 사라지고 합계가 60이 됐다). 로트가 나뉘어 놓이는 것은 일상이다.
+                 */
+                const subLotId = `${qe.epcClass}@${loc}`;
+                this.items.set(subLotId, this.mergeItem(qe.epcClass, { location: loc, disposition: ev.disposition, ilmd: ev.ilmd }, qe, mine, subLotId));
             }
         }
     }
@@ -327,8 +457,12 @@ export class ObservedReducer {
         }
         return undefined;
     }
-    mergeItem(epc, patch, q) {
-        const cur = this.items.get(epc);
+    mergeItem(epc, patch, q, 
+    /** 이 물품에 대해 선언된 수량 전부(표준 복수). 없으면 주 수량만 남는다. */
+    all, 
+    /** 로트의 부분 식별자(표준 `MaterialSubLot.ID`) — 비직렬 로트가 자리마다 갈릴 때. */
+    subLotId) {
+        const cur = this.items.get(subLotId ?? epc);
         /* 클래스는 수량 목록에서 오거나, 물품 자신이 클래스 식별자일 수 있다(비직렬 입고). */
         const parsedClass = q?.epcClass ? parseEpc(q.epcClass) : undefined;
         const parsedSelf = parseEpc(epc);
@@ -337,6 +471,7 @@ export class ObservedReducer {
         const classUri = q?.epcClass ?? (parsedSelf.instance ? undefined : epc);
         return {
             epc,
+            ...(subLotId ? { subLotId } : {}),
             gtin: classUri ?? cur?.gtin,
             gtinKey: parsedClass?.gtinKey ?? parsedSelf.gtinKey ?? cur?.gtinKey,
             location: patch.location ?? cur?.location ?? '',
@@ -344,6 +479,20 @@ export class ObservedReducer {
             parent: cur?.parent ?? this.pendingParent.get(epc),
             qty: q?.quantity ?? cur?.qty,
             uom: q?.uom ?? cur?.uom,
+            /*
+             * 선언된 수량 전부 — 값이 없는 항목은 담지 않는다(모름을 0 으로 만들지 않는다).
+             *
+             * **한 항목뿐이면 담지 않는다.** 그 하나는 `qty`/`uom` 이 이미 무손실로 들고 있고, 1개짜리
+             * 배열을 더 두면 같은 사실이 두 곳에 생긴다(그리고 시뮬은 그 배열을 만들지 않아 두 구동이
+             * 갈라진다 — 적합성 하네스가 실제로 잡았다). `quantities` 의 뜻은 **추가 단위**다.
+             * 읽을 때는 단위를 가리지 않는 `quantityIn` 을 쓴다(단일이든 복수든 같은 답).
+             */
+            quantities: (() => {
+                const declared = (all ?? []).filter(x => typeof x.quantity === 'number');
+                if (declared.length < 2)
+                    return cur?.quantities;
+                return declared.map(x => ({ value: x.quantity, ...(x.uom ? { uom: x.uom } : {}) }));
+            })(),
             /* 마스터데이터는 생겨날 때 한 번 정해진다 — 뒤 이벤트가 지우지 않게 기존 값을 남긴다. */
             ilmd: patch.ilmd ?? cur?.ilmd,
             expiry: this.expiryOf(patch.ilmd) ?? cur?.expiry,
@@ -362,6 +511,52 @@ export class ObservedReducer {
         }
     }
     /** 현재 투영 State — 자리 점유는 아이템 위치 집계로 유도(pure projection). */
+    /**
+     * 마지막으로 들은 발생 시각(ms) — **관측 구동의 "지금".**
+     *
+     * 시각으로만 바뀌는 사실(납기 초과·유효 기간·교대)을 판정하려면 기준이 필요하고, 관측 모드에는
+     * 굴러가는 시계가 없다. 정직한 기준은 "내가 마지막으로 들은 시점" 이다. 아무것도 못 들었으면
+     * `undefined` — 없는 기준으로 단정하지 않는다.
+     */
+    get lastObservedMs() {
+        return this.observedAtMs;
+    }
+    /** 선언된 교대만 기억한다 — 아무 선언이 없으면 키를 만들지 않는다(24시간 가용이 기존 거동). */
+    rememberShift(key, r) {
+        if (!r.workCalendar?.length && !r.window)
+            return;
+        this.shifts.set(key, {
+            ...(r.window ? { window: r.window } : {}),
+            ...(r.workCalendar?.length ? { workCalendar: r.workCalendar } : {})
+        });
+    }
+    /**
+     * 지금 근무 시간 밖인가 — 시뮬과 **같은 함수**(`offCalendarAt`)를 미러의 시각으로 부른다.
+     *
+     * 판정을 델타로 받지 않는 이유는 유효 기간과 같다: 교대 경계는 **이벤트 없이 시각만으로** 넘어가므로,
+     * 유휴 상태로 경계를 지난 자원은 실어 보낸 옛 판정에 머문다. 아무것도 못 들었으면 판정하지 않는다.
+     */
+    offShiftPart(key) {
+        const decl = this.shifts.get(key);
+        if (!decl || this.observedAtMs === undefined)
+            return {};
+        if (offCalendarAt(decl, this.observedAtMs, this.utcOffsetMinutes)) {
+            const why = offCalendarReasonAt(decl, this.observedAtMs, this.utcOffsetMinutes);
+            return { offShift: true, ...(why ? { offShiftReason: why } : {}) };
+        }
+        /* 근무 중이면 **어느 교대인지**도 낸다 — 시뮬과 같은 함수. 교대별 성과의 축이 여기서 나온다. */
+        const shift = activeShiftAt(decl.workCalendar, this.observedAtMs, this.utcOffsetMinutes);
+        return shift ? { shift } : {};
+    }
+    /** 유효 기간 밖이면 그 이유를 붙인다 — 미러의 시각 기준은 `observedAtMs`(마지막으로 들은 시점). */
+    effectivityPart(r) {
+        if (!r.effectiveStart && !r.effectiveEnd)
+            return {};
+        if (this.observedAtMs === undefined)
+            return {};
+        const e = effectivityAt(r, new Date(this.observedAtMs).toISOString());
+        return e ? { effectivity: e } : {};
+    }
     snapshot() {
         const occ = new Map();
         for (const it of this.items.values())
@@ -384,10 +579,12 @@ export class ObservedReducer {
             }),
             /* 들고 있는 것을 전부 내보낸다 — 축소하면 그 자리에서 정보가 사라진다. */
             items: [...this.items.values()].map(i => ({ ...i })),
-            persons: [...this.persons.values()].map(p => ({ ...p })),
-            assets: [...this.assets.values()].map(a => ({ ...a })),
+            /* 유효 기간 판정은 **저장하지 않고 여기서 낸다** — 시뮬과 **같은 함수**(`effectivityAt`)를 부른다.
+               만료는 이벤트 없이 시각만으로 일어나므로, 델타로 받아 두면 유휴 자원이 영원히 유효하게 남는다. */
+            persons: [...this.persons.values()].map(p => ({ ...p, ...this.effectivityPart(p), ...this.offShiftPart(`person:${p.id}`) })),
+            assets: [...this.assets.values()].map(a => ({ ...a, ...this.effectivityPart(a) })),
             tasks: [...this.tasks.values()].map(t => ({ ...t })),
-            equipment: [...this.equipment.values()].map(m => ({ ...m })),
+            equipment: [...this.equipment.values()].map(m => ({ ...m, ...this.effectivityPart(m), ...this.offShiftPart(`eq:${m.id}`) })),
             orders: [...this.orders.values()].map(o => ({ ...o }))
         };
     }

package/dist/yms-kernel.js

@@ -22,6 +22,16 @@ import { YARD_BIZSTEP, BTT_DELIVERY, graiUri } from "./yms-profile.js";
 const TRAVEL_MS = 20_000; // 야드 이동
 const DWELL_MS = 30_000; // 도크 체류(상·하차) — depart 이동에 folded
 const WINDOW_DELAY_MS = 40_000; // 도착 후 어포인트먼트 창까지(early arrival → 대기)
+/**
+ * 어포인트먼트 **창 길이** — 창이 열린 뒤 이만큼 안에 도크에 들어가야 한다.
+ *
+ * 표준 대조(2026-08-02): 우리 `windowStartMs` 는 `OpSegmentRequirement.EarliestStartTime` 과 **같은
+ * 개념**이고 단위만 다르다(시뮬 ms). **없던 것은 창의 끝** — `LatestEndTime` 에 해당한다. 그래서
+ * 어포인트먼트도 납기를 갖게 되고, 야드에서도 "늦었나" 를 물을 수 있다.
+ *
+ * 창 길이는 표준이 정하지 않는다(현장 계약 사항) — 데모 기본값이고, 마스터가 말해 주면 그것을 쓴다.
+ */
+const WINDOW_LENGTH_MS = 20 * 60_000;
 const CARGO_PER_TRAILER = 2; // 트레일러 적재/하역 화물(SSCC) 수
 const CP = '0614141';
 export class YmsKernel extends FlowEngine {
@@ -36,11 +46,11 @@ export class YmsKernel extends FlowEngine {
         this.mode = mode;
     }
     /** 인바운드(하차) 자극 — 화물 적재된 트레일러 도착. */
-    onArrival(_spec) { this.spawnAppointment('appointment'); }
+    onArrival(_spec) { this.spawnAppointment('appointment', _spec); }
     /** 아웃바운드(상차) 자극 — 빈 트레일러 도착(도크에서 staging 화물 적재 예정). */
-    onOrder(_spec) { this.spawnAppointment('appointment-out'); }
+    onOrder(_spec) { this.spawnAppointment('appointment-out', _spec); }
     /** 게이트-인 — 트레일러 도착 → 어포인트먼트(도크도어 배정 + 창). drop 은 야드 주차 태스크, live 는 게이트 대기. */
-    spawnAppointment(kind) {
+    spawnAppointment(kind, spec) {
         const gate = this.locationByType('gate');
         const doors = [...this.locations.values()].filter(n => n.type === 'dock-door').sort((a, b) => a.id.localeCompare(b.id));
         if (!gate || doors.length === 0)
@@ -59,7 +69,14 @@ export class YmsKernel extends FlowEngine {
         const door = doors[this.doorRR++ % doors.length];
         const id = `order-${++this.orderSeq}`;
         const appt = gdtiUri(CP, '404', ++this.soSeq);
-        const order = { id, kind, status: 'created', requested: 1, fulfilled: 0, bizTransaction: appt, allocated: [epc], picked: [], dockDoor: door.id, windowStartMs: this.clockMs + WINDOW_DELAY_MS };
+        const order = { id, kind, status: 'created', requested: 1, fulfilled: 0, bizTransaction: appt, allocated: [epc], picked: [], dockDoor: door.id,
+            /* 내부 스케줄 게이트(시뮬 ms) — 표준 `EarliestStartTime` 과 같은 개념의 우리 단위. */
+            windowStartMs: this.clockMs + WINDOW_DELAY_MS,
+            /* 표준 필드로도 함께 낸다 — 소비처(화면·집계·미러)는 표준 축으로 읽는다.
+               `startTime` = 창이 열리는 때 · `endTime` = 창이 닫히는 때(= 납기). */
+            startTime: new Date(Date.parse(this.now()) + WINDOW_DELAY_MS).toISOString(),
+            endTime: new Date(Date.parse(this.now()) + WINDOW_DELAY_MS + WINDOW_LENGTH_MS).toISOString(),
+            ...(spec?.priority !== undefined ? { priority: spec.priority } : {}) };
         this.orders.set(id, order);
         this.apptMode.set(id, this.mode);
         this.emitOrder(order);
@@ -117,7 +134,11 @@ export class YmsKernel extends FlowEngine {
     }
     /** 태스크 완료 — 목적지 타입으로 분기: yard-slot=주차, dock-door=상/하차+depart, gate=출차. */
     onTaskComplete(t) {
-        const trailer = this.items.get(t.itemEpc);
+        const trailer = this.itemByRef(t.itemEpc);
+        /* 여기 도달했다면 코어가 이미 물품을 확인했다(주체가 사라진 작업은 완료 전에 접힌다).
+           그래도 단정(`!`)은 쓰지 않는다 — 계약이 바뀌면 조용히 틀리는 대신 분명히 멈춘다. */
+        if (!trailer)
+            throw new Error(`task ${t.id}: item "${t.itemEpc}" vanished between the core check and the domain hook`);
         const from = this.locations.get(t.fromNode);
         const to = this.locations.get(t.toNode);
         from.occupancy--;