@operato/twin-kernel 0.3.0 → 0.4.1

package/dist/contract.js

@@ -127,6 +127,30 @@ export function hierarchyOf(s) {
         }
     };
 }
+/**
+ * 이 시각에 유효 기간 밖인가 — **한 규칙**으로 개체·등급·설비↔자산 매핑을 모두 판정한다.
+ *
+ * **표준은 날짜만 정하고 "밖이면 어떻게 되는가" 는 정하지 않는다.** 그 판단은 우리 것이므로 여기 밝힌다:
+ * 기간 밖이면 **그 자원은 그 시각의 모델에 참여하지 않는다**(배정되지 않고, 가용 분모에 들지 않는다).
+ * 지우지는 않는다 — 이유를 달아 남긴다. 조용히 사라지면 "왜 없어졌나" 를 아무도 답할 수 없다.
+ *
+ * `at` 를 주지 않으면 **판단하지 않는다**(`undefined`). 모르는 시각으로 폐기를 단정하면, 시각을 안 넘긴
+ * 소비처 전부가 자원을 잃는다. 파싱 불가한 시각도 같다 — 짐작해 고치지 않는다.
+ */
+export function effectivityAt(p, at) {
+    if (!p || !at)
+        return undefined;
+    const atMs = Date.parse(at);
+    if (!Number.isFinite(atMs))
+        return undefined;
+    const from = p.effectiveStart ? Date.parse(p.effectiveStart) : NaN;
+    if (Number.isFinite(from) && atMs < from)
+        return 'not-yet';
+    const to = p.effectiveEnd ? Date.parse(p.effectiveEnd) : NaN;
+    if (Number.isFinite(to) && atMs > to)
+        return 'expired';
+    return undefined;
+}
 /**
  * 등급 소속을 **상속을 타고 닫는다** — "이 개체가 이 등급으로 통하는가".
  *
@@ -137,18 +161,7 @@ export function hierarchyOf(s) {
  */
 export function classClosure(directIds, defs, at) {
     const byId = new Map((defs ?? []).map(d => [d.id, d]));
-    const atMs = at ? Date.parse(at) : NaN;
-    const inWindow = (d) => {
-        if (!d || !Number.isFinite(atMs))
-            return true;
-        const from = d.effectiveStart ? Date.parse(d.effectiveStart) : NaN;
-        const to = d.effectiveEnd ? Date.parse(d.effectiveEnd) : NaN;
-        if (Number.isFinite(from) && atMs < from)
-            return false;
-        if (Number.isFinite(to) && atMs > to)
-            return false;
-        return true;
-    };
+    const inWindow = (d) => !d || effectivityAt(d, at) === undefined;
     const out = new Set();
     const stack = [...(directIds ?? [])];
     while (stack.length) {
@@ -165,6 +178,313 @@ export function classClosure(directIds, defs, at) {
     }
     return out;
 }
+/**
+ * 우선순위 — **ISA-95 `Priority`**(`JobOrderType`·`OperationsRequestType`, 타입은 `PriorityType` =
+ * `NumericType` 제한). 즉 표준은 **숫자라는 것만 정하고 방향은 정하지 않는다.**
+ *
+ * **그래서 방향은 우리가 정한다: 작은 값이 급하다(1 = 가장 급함).** 흔한 관행이고, 무엇보다
+ * 한쪽으로 못 박아 두지 않으면 소비처마다 반대로 읽는다. 우리가 정한 규약이라는 사실을 여기 밝힌다.
+ *
+ * 미지정은 **0 이 아니라 "우선순위 없음"** 이다 — 선언한 것들 뒤에 선다(0 으로 채우면 미지정이
+ * 가장 급한 것이 된다).
+ */
+export const PRIORITY_UNSET = Number.POSITIVE_INFINITY;
+/** 정렬 키 — 미지정을 맨 뒤로 보낸다. 같은 우선순위는 **입력 순서**를 지킨다(결정성). */
+export function priorityRank(p) {
+    return typeof p === 'number' && Number.isFinite(p) ? p : PRIORITY_UNSET;
+}
+/**
+ * 납기 대비 상태 — **파생**이다(저장하지 않는다). `locationStatusOf` 와 같은 규율.
+ *
+ * 예정 창(`endTime`)이 없으면 `undefined` — **"늦지 않았다" 가 아니라 "판단할 수 없다"** 다.
+ * 납기가 없는데 정시라고 말하면 그건 없는 사실을 만드는 것이다.
+ */
+export function dueStatusOf(x, nowIso) {
+    if (!x.endTime || !nowIso)
+        return undefined;
+    const due = Date.parse(x.endTime);
+    const now = Date.parse(nowIso);
+    if (!Number.isFinite(due) || !Number.isFinite(now))
+        return undefined;
+    return now > due ? 'late' : 'on-time';
+}
+/**
+ * 선언된 단위로 수량을 읽는다 — **환산하지 않는다.**
+ *
+ * 없으면 `undefined`: "0" 이 아니고 "계산한 값" 도 아니다. 환산 계수를 모르는데 값을 만들면
+ * 그 뒤 모든 계산이 거짓 위에 선다.
+ */
+/**
+ * 로트의 부분 식별자를 **한 규칙으로** 만든다 — 표준 `MaterialSubLot.ID`.
+ *
+ * 시뮬(생산)과 미러(관측)가 각자 만들면 같은 부분이 다른 이름을 갖고, 두 구동이 갈라진다
+ * (적합성 하네스가 실제로 잡았다). 부분을 가르는 것은 **자리**다.
+ */
+/**
+ * 물품을 구별하는 키 — 직렬 물품은 `epc`, 로트의 부분은 `subLotId`(표준 `MaterialSubLot.ID`).
+ *
+ * **한 곳에서 정한다.** 소비처마다 `epc` 로 키를 잡으면 같은 로트의 두 부분이 하나로 접히고,
+ * 그 순간 재고가 조용히 줄어든다(실제로 그랬다 — §ItemState.subLotId).
+ */
+export function subLotIdOf(classUri, location) {
+    return `${classUri}@${location}`;
+}
+export function itemKeyOf(item) {
+    return item.subLotId ?? item.epc;
+}
+export function quantityIn(item, uom, definitions) {
+    const hit = item.quantities?.find(q => (q.uom ?? undefined) === (uom ?? undefined));
+    if (hit)
+        return hit.value;
+    /* 주 수량이 그 단위면 그것을 답한다 — `quantities` 를 안 실은 물품도 답이 나오게. */
+    if ((item.uom ?? undefined) === (uom ?? undefined))
+        return item.qty;
+    /* **선언된 계수가 있으면** 환산한다 — 여전히 지어내지는 않는다(§conversionFactorOf). */
+    return convertQuantity(item, uom, definitions);
+}
+/**
+ * **우리가 정한 품목 속성 이름** — 표준은 자리만 정하고 이름을 정하지 않는다.
+ *
+ * `perBaseUnit`: 값은 **기준 단위 하나당 그 단위의 양**이고, 단위는 속성의 `uom` 이 말한다.
+ * 예) 한 개(EA)가 2.5 kg 이면 `{ id: 'perBaseUnit', value: 2.5, uom: 'KGM' }`.
+ *
+ * **왜 이 모양인가**: 임의의 단위쌍 환산표(CS↔KGM↔EA…)는 품목마다 다르고 연쇄가 필요해 금세
+ * 커진다. 현장에서 실제로 필요한 것은 **"세는 단위에서 다른 단위로"** 이므로, 기준 단위를 축으로
+ * 두면 선언 한 줄로 끝난다. 기준 단위가 아닌 수량에서 출발하는 환산은 **하지 않는다**(§convertQuantity).
+ */
+export const MATERIAL_PROPERTY = {
+    /** 기준 단위 하나당 이 단위의 양. `uom` 이 대상 단위. */
+    perBaseUnit: 'perBaseUnit'
+};
+/**
+ * 이 품목에서 `uom` 으로 가는 계수 — **선언된 것만.** 없으면 `undefined`(추정하지 않는다).
+ */
+export function conversionFactorOf(def, uom) {
+    if (!def || !uom)
+        return undefined;
+    for (const p of def.properties ?? []) {
+        if (p.id !== MATERIAL_PROPERTY.perBaseUnit || p.uom !== uom)
+            continue;
+        const n = typeof p.value === 'number' ? p.value : Number(p.value);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return undefined;
+}
+/**
+ * 선언된 계수로 환산한다 — **기준 수량에서만 출발한다.**
+ *
+ * 기준 수량(`qty`)은 품목을 세는 단위다(EPCIS 는 단위 미지정이면 개수로 읽는다). 그것이 아닌 수량에서
+ * 출발하려면 그 단위→기준 단위 역계수가 또 필요한데, 그것을 짐작하면 오차가 곱으로 쌓인다.
+ * 그래서 **기준 수량이 없거나 이미 다른 단위로 선언돼 있으면 환산하지 않는다.**
+ */
+function convertQuantity(item, uom, definitions) {
+    if (!definitions || !uom)
+        return undefined;
+    if (typeof item.qty !== 'number' || !Number.isFinite(item.qty))
+        return undefined;
+    if (item.uom)
+        return undefined; // 기준 단위가 아닌 수량 — 역계수를 지어내지 않는다
+    const def = definitions.get(item.definitionId ?? item.gtin ?? '');
+    const factor = conversionFactorOf(def, uom);
+    return factor === undefined ? undefined : item.qty * factor;
+}
+/** `HH:MM` → 자정 이후 분. 형식이 아니면 `undefined`(짐작해 고치지 않는다). */
+function minutesOfDay(hhmm) {
+    const m = /^(\d{1,2}):(\d{2})$/.exec(hhmm ?? '');
+    if (!m)
+        return undefined;
+    const h = Number(m[1]);
+    const mi = Number(m[2]);
+    if (h > 23 || mi > 59)
+        return undefined;
+    return h * 60 + mi;
+}
+/**
+ * 이 시각이 근무 시간인가 — **비근무가 근무를 이긴다.**
+ *
+ * 표준은 구간과 종류를 정하지만 **겹칠 때 무엇이 이기는지는 정하지 않는다.** 그래서 우리가 정했다:
+ * 휴일·정비(비근무)는 교대(근무) 위에 얹힌다. 반대로 두면 휴일 선언이 무의미해진다.
+ *
+ * 캘린더가 비어 있으면 `true` — **24시간 가용이 기존 거동**이고, 선언하지 않은 것을 쉬는 것으로
+ * 읽으면 아무 일도 일어나지 않는 트윈이 된다.
+ */
+/** 절대 구간을 쓰는 항목인가 — 되풀이(`HH:MM`)와 판정 방법이 다르다. */
+const isAbsolute = (e) => !!(e.startDateTime || e.finishDateTime);
+/** **날짜를 알아야** 판정할 수 있는 항목인가 — 절대 구간이거나 요일이 걸린 것. */
+const needsDate = (e) => isAbsolute(e) || !!e.daysOfWeek?.length;
+/**
+ * 이 구간이 **선언된 요일에 시작한 것**인가 — 자정을 넘는 교대를 바르게 세기 위한 규칙.
+ *
+ * 22:00→06:00 교대에 월~금을 주면 뜻은 "월~금에 **시작**한다" 이다. 그래서 토요일 새벽 2시는
+ * **금요일에 시작한 교대**의 일부이고(포함), 월요일 새벽 2시는 일요일 밤에 서지 않은 교대이므로
+ * 제외된다. 순간의 요일로 세면 이 둘이 정확히 반대로 틀린다.
+ */
+function onDeclaredDay(e, minuteOfDay, weekday) {
+    if (!e.daysOfWeek?.length)
+        return true;
+    const from = minutesOfDay(e.fromTime);
+    const to = minutesOfDay(e.toTime);
+    const crosses = from !== undefined && to !== undefined && from > to;
+    /* 자정을 넘는 구간의 **뒷조각**(자정~종료)은 어제 시작한 것이다. */
+    const startedDay = crosses && minuteOfDay < to ? (weekday + 6) % 7 : weekday;
+    return e.daysOfWeek.includes(startedDay);
+}
+/** 선언된 기준의 요일(0 일요일 … 6 토요일). */
+export function weekdayAt(ms, utcOffsetMinutes) {
+    return new Date(ms + (utcOffsetMinutes ?? 0) * 60_000).getUTCDay();
+}
+/**
+ * 절대 구간이 그 시각을 덮는가 — 한쪽만 있으면 그쪽만 본다(열린 구간).
+ * 깨진 시각으로는 판정하지 않는다(짐작해 고치지 않는다).
+ */
+function coversInstant(e, atMs) {
+    const from = e.startDateTime ? Date.parse(e.startDateTime) : NaN;
+    const to = e.finishDateTime ? Date.parse(e.finishDateTime) : NaN;
+    if (!Number.isFinite(from) && !Number.isFinite(to))
+        return false;
+    if (Number.isFinite(from) && atMs < from)
+        return false;
+    if (Number.isFinite(to) && atMs >= to)
+        return false;
+    return true;
+}
+/** 이 구간이 그 분을 덮는가 — `inWorkCalendar` 와 `activeShiftOf` 가 **같은 규칙**을 쓴다. */
+function coversMinute(e, minuteOfDay) {
+    const from = minutesOfDay(e.fromTime);
+    const to = minutesOfDay(e.toTime);
+    if (from === undefined || to === undefined)
+        return false; // 깨진 선언으로 판정하지 않는다
+    /* 자정을 넘는 구간(22:00→06:00)은 두 조각으로 읽는다 — 날짜 오프셋이 그것을 명시할 때도 같다. */
+    return from <= to ? minuteOfDay >= from && minuteOfDay < to : minuteOfDay >= from || minuteOfDay < to;
+}
+export function inWorkCalendar(entries, minuteOfDay) {
+    /* 되풀이만 본다 — 절대 구간은 분(minute)만으로 판정할 수 없다(어느 날인지 모른다).
+       시각(ms)을 가진 소비처는 `inWorkCalendarAt` 을 쓴다. */
+    return judgeCalendar(entries, e => coversMinute(e, minuteOfDay), false);
+}
+/**
+ * 이 **시각**이 근무 시간인가 — 되풀이(`HH:MM`)와 **한 번뿐인 구간**(휴일·정비창)을 함께 본다.
+ *
+ * 절대 구간은 시각 기준이 필요 없다(ISO 시각에 이미 들어 있다). 되풀이는 **선언된 기준**으로 읽는다.
+ * 겹치면 규칙은 하나다 — **비근무가 근무를 이긴다**(휴일이 교대 위에 얹힌다).
+ */
+export function inWorkCalendarAt(entries, atMs, utcOffsetMinutes) {
+    const minute = minuteOfDayAt(atMs, utcOffsetMinutes);
+    const day = weekdayAt(atMs, utcOffsetMinutes);
+    const covers = (e) => {
+        if (isAbsolute(e))
+            return coversInstant(e, atMs);
+        if (!coversMinute(e, minute))
+            return false;
+        /* 요일이 걸려 있으면 **그 구간이 시작한 날**로 센다(자정을 넘는 교대). */
+        return onDeclaredDay(e, minute, day);
+    };
+    return judgeCalendar(entries, covers, true);
+}
+/**
+ * 근무/비근무 판정의 **한 규칙** — 덮는 방법만 다르고 우선순위는 같다.
+ *
+ * `withAbsolute` 가 false 면 절대 구간 항목은 **없는 셈 친다**(판정할 재료가 없다). 그것을 근무로도
+ * 비근무로도 세면 둘 다 거짓이 된다 — 모르면 판단하지 않는다.
+ */
+function judgeCalendar(entries, covers, withAbsolute) {
+    if (!entries?.length)
+        return true;
+    const usable = withAbsolute ? entries : entries.filter(e => !needsDate(e));
+    if (!usable.length)
+        return true;
+    const working = usable.filter(e => (e.entryType ?? 'working') === 'working');
+    const off = usable.filter(e => e.entryType === 'non-working');
+    if (off.some(covers))
+        return false; // 비근무가 이긴다
+    if (!working.length)
+        return true; // 비근무만 선언했다면 그 밖은 근무다
+    return working.some(covers);
+}
+/**
+ * 지금 어느 교대인가 — **근무 구간의 이름**(표준 `WorkCalendarEntryType.ID`).
+ *
+ * 비근무가 이기는 규칙은 여기서도 같다: 휴게·정비 중이면 **어느 교대도 아니다**(`undefined`).
+ * 이름 없는 구간은 이름을 지어내지 않는다 — 교대를 나눠 놓지 않은 현장에서 `'1'` 같은 값을
+ * 만들어 붙이면, 그 뒤 모든 교대별 집계가 없는 구분 위에 선다.
+ *
+ * 겹치는 근무 구간이 여럿이면 **먼저 선언된 것**을 답한다(선언 순서가 현장의 우선순위다).
+ */
+export function activeShiftOf(entries, minuteOfDay) {
+    if (!entries?.length)
+        return undefined;
+    if (!inWorkCalendar(entries, minuteOfDay))
+        return undefined; // 비근무 중 — 어느 교대도 아니다
+    for (const e of entries) {
+        if (needsDate(e) || (e.entryType ?? 'working') !== 'working' || !e.id)
+            continue;
+        if (coversMinute(e, minuteOfDay))
+            return e.id;
+    }
+    return undefined;
+}
+/**
+ * 이 **시각**에 어느 교대인가 — 휴일까지 반영한다.
+ *
+ * 휴일에 일어난 일은 **어느 교대에도 속하지 않는다**(그날 교대는 서지 않았다). 되풀이만 보는
+ * `activeShiftOf` 로는 그것을 알 수 없어, 휴일에 찍힌 기록이 평소 교대로 집계됐다.
+ */
+export function activeShiftAt(entries, atMs, utcOffsetMinutes) {
+    if (!entries?.length)
+        return undefined;
+    if (!inWorkCalendarAt(entries, atMs, utcOffsetMinutes))
+        return undefined;
+    const minute = minuteOfDayAt(atMs, utcOffsetMinutes);
+    const day = weekdayAt(atMs, utcOffsetMinutes);
+    for (const e of entries) {
+        if (isAbsolute(e) || (e.entryType ?? 'working') !== 'working' || !e.id)
+            continue;
+        if (!coversMinute(e, minute))
+            continue;
+        if (!onDeclaredDay(e, minute, day))
+            continue; // 그날 서지 않은 교대(시작한 날로 센다)
+        return e.id;
+    }
+    return undefined;
+}
+/**
+ * 절대 시각(ms) → **선언된 기준의** 하루 중 분(0..1439).
+ *
+ * `HH:MM` 만으로는 "어느 기준의 06시" 인지 알 수 없다. 예전에 이것을 UTC 로 읽어 Rosarito(UTC−7)의
+ * 06시 교대가 **7시간 틀렸다.** 선언이 없으면 UTC 이고, 그 기본값을 숨기지 않고 밝힌다.
+ */
+export function minuteOfDayAt(ms, utcOffsetMinutes) {
+    const d = new Date(ms + (utcOffsetMinutes ?? 0) * 60_000);
+    return d.getUTCHours() * 60 + d.getUTCMinutes();
+}
+export function offCalendarReasonAt(r, ms, utcOffsetMinutes) {
+    if (!offCalendarAt(r, ms, utcOffsetMinutes))
+        return undefined;
+    const entries = r.workCalendar;
+    if (!entries?.length)
+        return 'off-hours'; // 옛 `window` 경로 — 구간 선언이 없다
+    const minute = minuteOfDayAt(ms, utcOffsetMinutes);
+    const day = weekdayAt(ms, utcOffsetMinutes);
+    for (const e of entries) {
+        if (e.entryType !== 'non-working')
+            continue;
+        const covered = isAbsolute(e) ? coversInstant(e, ms) : coversMinute(e, minute) && onDeclaredDay(e, minute, day);
+        if (covered)
+            return 'non-working';
+    }
+    return 'off-hours';
+}
+export function offCalendarAt(r, ms, utcOffsetMinutes) {
+    const minute = minuteOfDayAt(ms, utcOffsetMinutes);
+    if (r.workCalendar?.length)
+        return !inWorkCalendarAt(r.workCalendar, ms, utcOffsetMinutes);
+    const w = r.window;
+    if (!w)
+        return false;
+    const h = Math.floor(minute / 60);
+    return !(w.startHour <= w.endHour ? h >= w.startHour && h < w.endHour : h >= w.startHour || h < w.endHour);
+}
 // ── 운영 델타(비-EPCIS) — State 채널의 나머지 절반 ──────────────────────────
 // EPCIS 이벤트는 재고/위치만 재구성 가능. tasks·equipment·orders 의 운영 상태는
 // 이 델타로 미러한다. envelope.eventType = 'task.status' | 'equipment.status' | 'order.status'.
@@ -221,8 +541,12 @@ export function readBoardLocations(def) {
     return d.locations ?? d.nodes ?? []; // vocabulary-guard: allow — 옛 키 흡수
 }
 export function readBoardEquipment(def) {
+    /* `movers` 는 개명 **이전의 이름**이다(movers → equipmentList → equipment). 저장된 보드에는 세 세대가
+       섞여 있어(실측: 23개 중 13개가 `movers`) 하나라도 빠뜨리면 그 보드는 **설비가 0인 공장**으로 읽힌다 —
+       오류 없이. 실제로 그랬다: 화면의 설비 수가 0이고, 용량 판정에 자원이 없고, 카탈로그 통합 테스트가
+       "완제품 0" 으로 떨어졌다. 셋 다 원인이 이 한 줄이었다. */
     const d = def; // vocabulary-guard: allow — 옛 키를 읽어야 하는 자리
-    const list = d.equipment ?? d.equipmentList ?? []; // vocabulary-guard: allow — 옛 키 흡수
+    const list = d.equipment ?? d.equipmentList ?? d.movers ?? []; // vocabulary-guard: allow — 옛 키 흡수
     /* 소속 자리 키도 함께 정규화한다 — `homeNode → homeLocation` 개명 전 보드가 23개 있다.  (vocabulary-guard: allow — 옛 키 정규화 설명)
        배열만 흡수하고 안쪽 키를 놓치면 설비는 나타나지만 **소속이 전부 비어** 롤업이 통째로 사라진다. */
     return list.map(e => normalizeHomeLocation(e));

package/dist/divergence.js

@@ -5,6 +5,7 @@
  * 상태를 같은 시점에 비교해 **드리프트(모델과 현실의 이탈)** 를 탐지한다. 발산 = 이상/개입 신호.
  * (fork 로 예측 → 관측으로 실제 → 여기서 대조. execution-model.md 시뮬↔모니터링 커플링.)
  */
+import { itemKeyOf } from "./contract.js";
 function diffBy(predicted, actual, idOf, valOf) {
     const p = new Map(predicted.map(e => [idOf(e), valOf(e)]));
     const a = new Map(actual.map(e => [idOf(e), valOf(e)]));
@@ -19,8 +20,10 @@ function diffBy(predicted, actual, idOf, valOf) {
 }
 /** predicted(fork forecast)와 actual(관측) 스냅샷을 대조. 같은 sim 시점에 호출하는 것이 의미 있음. */
 export function compareStates(predicted, actual) {
-    const itemLocation = diffBy(predicted.items, actual.items, i => i.epc, i => i.location);
-    const itemDisposition = diffBy(predicted.items, actual.items, i => i.epc, i => i.disposition);
+    /* 키는 **한 규칙**으로 잡는다(`itemKeyOf`) — 같은 로트의 두 부분을 `epc` 로 접으면 발산 비교가
+       "같은 물품이 두 곳에 있다" 를 자기 오류로 착각한다. */
+    const itemLocation = diffBy(predicted.items, actual.items, itemKeyOf, i => i.location);
+    const itemDisposition = diffBy(predicted.items, actual.items, itemKeyOf, i => i.disposition);
     const locationOccupancy = diffBy(predicted.locations, actual.locations, n => n.id, n => n.occupancy);
     const orderStatus = diffBy(predicted.orders, actual.orders, o => o.id, o => o.status);
     const hasDrift = itemLocation.length > 0 || itemDisposition.length > 0 || locationOccupancy.length > 0 || orderStatus.length > 0;

package/dist/domain-definition.d.ts

@@ -139,6 +139,51 @@ export interface OperationDef {
         equipmentClass?: string;
         quantity: number;
     }[];
+    /**
+     * 필요·산출 자재 — **ISA-95 `OperationsSegment.MaterialSpecification`**(`OpMaterialSpecificationType`).
+     *
+     * ── 4대 자원 중 자재만 빠져 있었다 ────────────────────────────────────────
+     * 인원·설비·자산 셋은 공정이 "등급 + 수량" 으로 요구하는데 **자재만 그 자리가 없었다.** 그래서
+     * 트레일러 조립 공장을 모델링해도 *"차축 하나에 바퀴 둘"* 을 말할 방법이 없고, 부품이 없어서
+     * 라인이 서는 상황이 **예측에 아예 나타나지 않는다** — 자재는 현장에서 사람만큼 자주 부족하다.
+     *
+     * ── BOM 은 어디 있나 (1차 출처 확인) ─────────────────────────────────────
+     * `MaterialDefinition.AssemblyDefinition` 은 **재귀 구조**(무엇이 무엇으로 이루어지나)일 뿐
+     * **수량이 없다.** 수량은 공정 쪽 `MaterialSpecification` 이 든다(`Quantity` + `MaterialUse`).
+     * 즉 표준에서 **BOM 의 "몇 개" 는 공정의 사실**이다 — 같은 부품이라도 공정마다 소요가 다르다.
+     *
+     * `use` 는 표준 `MaterialUse` 를 소문자로 쓴다(우리 어휘 규약). 지금 커널이 소비하는 것은
+     * `consumed`(작업이 시작되려면 있어야 하고 시작 시 빠진다)뿐이고, 나머지는 **선언만 받아 둔다** —
+     * 자리가 없으면 사실이 들어오지 못한다.
+     */
+    materialSpecification?: OpMaterialSpecification[];
+}
+/**
+ * 공정 하나의 자재 명세 — **ISA-95 `OpMaterialSpecificationType`** 의 우리 부분집합.
+ *
+ * 1차 출처: `ID` · `MaterialClassID*` · `MaterialDefinitionID*` · `MaterialLotID*` · `MaterialSubLotID*` ·
+ * `Description*` · **`MaterialUse`** · `HierarchyScope` · `StorageLocation` · `SpatialDefinition` ·
+ * **`Quantity*`** · `AssemblySpecification*`(재귀) · `AssemblyType` · `AssemblyRelationship` ·
+ * `MaterialSpecificationProperty*` · `TestSpecificationID*`.
+ *
+ * 우리는 **요구를 표현하는 데 필요한 것**만 든다(인원·자산 명세와 같은 모양). 로트·하위로트 지목,
+ * 재귀 조립 명세, 저장 위치 한정은 아직 없다 — 필요해질 때 표준 이름 그대로 얹는다.
+ */
+export interface OpMaterialSpecification {
+    /** 표준 `ID` — 명세를 가리키는 이름(선택). */
+    id?: string;
+    /** 품목 등급으로 요구 — 표준 `MaterialClassID`. */
+    materialClass?: string;
+    /** 특정 품목으로 요구 — 표준 `MaterialDefinitionID`. 등급과 함께 주면 품목이 좁은 쪽이다. */
+    materialDefinition?: string;
+    /**
+     * 이 공정에서의 쓰임 — 표준 `MaterialUse`.
+     * `consumed` 없어지며 들어간다 · `produced` 만들어져 나온다 · `consumable` 쓰이지만 제품에 남지 않는다.
+     */
+    use: 'consumed' | 'produced' | 'consumable';
+    /** 수량 — 표준 `Quantity`. 단위 미지정이면 개수(EPCIS 규약과 같다). */
+    quantity: number;
+    uom?: string;
 }
 /** 라우트(오퍼레이션 시퀀스) — ISA-95 ProcessSegment 연결. */
 export interface RouteDef {

package/dist/epcis.d.ts

@@ -9,6 +9,18 @@ export declare const DISP: {
     readonly in_transit: "urn:epcglobal:cbv:disp:in_transit";
     readonly non_sellable: "urn:epcglobal:cbv:disp:non_sellable_other";
 };
+/**
+ * **자재 소비·산출의 CBV 단계** — 도메인 무관하게 코어가 쓴다.
+ *
+ * 업종별 단계(입고·피킹·출하…)는 각 프로파일이 갖지만, "자재가 들어갔다/나왔다" 는 셋 다 하는 일이라
+ * 코어에 있어야 한다. 프로파일 하나에 두면 다른 업종이 그것을 가져다 쓰면서 방언이 생긴다.
+ */
+export declare const CBV_BIZSTEP: {
+    /** 공정에 자재가 들어갔다 — ISA-95 `MaterialUse: Consumed`. */
+    readonly consuming: "urn:epcglobal:cbv:bizstep:consuming";
+    /** 새 물품이 생겨 계보가 시작된다 — ISA-95 `MaterialUse: Produced`. */
+    readonly commissioning: "urn:epcglobal:cbv:bizstep:commissioning";
+};
 export type EpcisEventType = 'ObjectEvent' | 'AggregationEvent' | 'TransactionEvent' | 'TransformationEvent';
 export type EpcisAction = 'ADD' | 'OBSERVE' | 'DELETE';
 /**

package/dist/epcis.js

@@ -18,6 +18,18 @@ export const DISP = {
     in_transit: 'urn:epcglobal:cbv:disp:in_transit',
     non_sellable: 'urn:epcglobal:cbv:disp:non_sellable_other' // 불량/scrap
 };
+/**
+ * **자재 소비·산출의 CBV 단계** — 도메인 무관하게 코어가 쓴다.
+ *
+ * 업종별 단계(입고·피킹·출하…)는 각 프로파일이 갖지만, "자재가 들어갔다/나왔다" 는 셋 다 하는 일이라
+ * 코어에 있어야 한다. 프로파일 하나에 두면 다른 업종이 그것을 가져다 쓰면서 방언이 생긴다.
+ */
+export const CBV_BIZSTEP = {
+    /** 공정에 자재가 들어갔다 — ISA-95 `MaterialUse: Consumed`. */
+    consuming: 'urn:epcglobal:cbv:bizstep:consuming',
+    /** 새 물품이 생겨 계보가 시작된다 — ISA-95 `MaterialUse: Produced`. */
+    commissioning: 'urn:epcglobal:cbv:bizstep:commissioning'
+};
 // ── GS1 EPC URI 헬퍼 (표준) ────────────────────────────────────────────────
 /** SSCC (물류단위: 팔레트/화물/트레일러) — 결정적 카운터 기반. */
 export function ssccUri(companyPrefix, serial) {

package/dist/event-journal.d.ts

@@ -15,3 +15,33 @@ export declare class EventJournal {
 }
 /** 이벤트열 → 상태 재구성(시간여행). board = 마스터(토폴로지·설비). */
 export declare function replay(board: BoardDef, events: readonly CanonicalEnvelope[]): ProjectedState;
+/** 한 구조 아래에서 일어난 이벤트들 — 재생의 한 마디. */
+export interface StructureSegment {
+    board: BoardDef;
+    events: readonly CanonicalEnvelope[];
+}
+/** 구조가 바뀐 지점마다 무엇이 사라졌는지. 조용히 넘어가지 않는다. */
+export interface StructureShift {
+    index: number;
+    locationsAdded: number;
+    locationsDropped: number;
+    equipmentDropped: number;
+    personsDropped: number;
+    assetsDropped: number;
+}
+/**
+ * **구조가 바뀐 이력까지 이어서 재생한다.**
+ *
+ * 공장은 바뀐다. 지금까지는 구조가 바뀌면 저널을 지우는 것이 유일한 길이었다 — 안 지우면 옛 이벤트를
+ * 새 공장에 대고 접게 되어 이력이 거짓말을 하기 때문이다(도장 부스가 둘이던 시절의 사실을 여섯 개짜리
+ * 공장에 접는다). 역사를 잃거나 거짓말을 하거나, 둘뿐이었다.
+ *
+ * 셋째 길이 이것이다: 마디마다 **그때의 구조**로 접고, 경계에서 구조만 갈아탄다(관측된 사실은 이어
+ * 간다). 그러면 이력이 "그때 그 공장의 사실" 로 계속 읽힌다.
+ *
+ * 경계에서 사라진 자원은 결과에 실어 보낸다 — 수가 줄어든 것을 사용자가 눈치채지 못하면 안 된다.
+ */
+export declare function replaySegments(segments: readonly StructureSegment[]): {
+    state: ProjectedState;
+    shifts: StructureShift[];
+};

package/dist/event-journal.js

@@ -39,3 +39,29 @@ export function replay(board, events) {
         proj.apply(e);
     return proj.snapshot();
 }
+/**
+ * **구조가 바뀐 이력까지 이어서 재생한다.**
+ *
+ * 공장은 바뀐다. 지금까지는 구조가 바뀌면 저널을 지우는 것이 유일한 길이었다 — 안 지우면 옛 이벤트를
+ * 새 공장에 대고 접게 되어 이력이 거짓말을 하기 때문이다(도장 부스가 둘이던 시절의 사실을 여섯 개짜리
+ * 공장에 접는다). 역사를 잃거나 거짓말을 하거나, 둘뿐이었다.
+ *
+ * 셋째 길이 이것이다: 마디마다 **그때의 구조**로 접고, 경계에서 구조만 갈아탄다(관측된 사실은 이어
+ * 간다). 그러면 이력이 "그때 그 공장의 사실" 로 계속 읽힌다.
+ *
+ * 경계에서 사라진 자원은 결과에 실어 보낸다 — 수가 줄어든 것을 사용자가 눈치채지 못하면 안 된다.
+ */
+export function replaySegments(segments) {
+    if (!segments.length)
+        throw new Error('재생할 마디가 없다 — 구조를 하나도 주지 않았다');
+    const proj = new StateProjector(segments[0].board);
+    const shifts = [];
+    for (let i = 0; i < segments.length; i++) {
+        /* 첫 마디는 생성자가 이미 그 구조로 섰다 — 두 번 세우면 관측 전 상태를 다시 덮는다. */
+        if (i > 0)
+            shifts.push({ index: i, ...proj.adoptStructure(segments[i].board) });
+        for (const e of segments[i].events)
+            proj.apply(e);
+    }
+    return { state: proj.snapshot(), shifts };
+}