@operato/twin-kernel 0.2.3 → 0.4.0

package/dist/contract.js

@@ -5,22 +5,488 @@
 /**
  * 자리의 상태 — **포화도에서 파생한다.** 저장하는 값이 아니다.
  *
- * 예전에는 시뮬이 `'idle'` 로 두고 한 번도 바꾸지 않았고(변경 지점 0), 미러에는 노드 상태 채널이
+ * 예전에는 시뮬이 `'idle'` 로 두고 한 번도 바꾸지 않았고(변경 지점 0), 미러에는 자리 상태 채널이
  * 없어 비어 있었다. 화면은 그 값을 그대로 보여 주고 있었다 — **정보처럼 보이는데 정보가 아니었다.**
  *
  * 문턱은 병목 주목(`deriveAttentions`)이 쓰는 것과 **같다**: 90% 이상이면 임박, 100% 이상이면 포화.
  * 규칙이 둘이면 화면과 주목이 다른 말을 한다. 용량을 모르면 상태도 모른다(undefined — 꾸미지 않는다).
  */
-export const NODE_SATURATION_NEAR = 0.9;
-export function nodeStatusOf(n) {
+export const LOCATION_SATURATION_NEAR = 0.9;
+export function locationStatusOf(n) {
     const cap = n.capacity;
     if (!(typeof cap === 'number' && cap > 0))
         return undefined;
     const r = (n.occupancy ?? 0) / cap;
-    return r >= 1 ? 'full' : r >= NODE_SATURATION_NEAR ? 'near-full' : 'available';
+    return r >= 1 ? 'full' : r >= LOCATION_SATURATION_NEAR ? 'near-full' : 'available';
+}
+/**
+ * 설비 계층 단계 — **ISA-95 표준 어휘.** 1차 출처: B2MML `B2MML-Common.xsd` /
+ * `EquipmentLevel1Type` 열거값 + `EquipmentLevelType` 주석("role based equipment hierarchy level
+ * as defined in ISA 95").
+ *
+ * 우리가 단의 이름을 발명하지 않는다. "라인" 은 `ProductionLine`, "존" 은 `StorageZone` 으로
+ * 표준이 이미 정해 뒀다. 발명하면 그 순간 방언이 되고, 연동 상대와 매핑 표가 필요해진다.
+ *
+ * **`Other` 는 탈출구다** — 표준도 열거값 밖을 인정한다(`OtherValue` 속성). 억지로 끼워 맞추는 대신
+ * `Other` 로 두고 현장의 낱말은 `type` 에 남긴다.
+ *
+ * `StorageZone`·`StorageUnit` 도 이 계층 안에 있다. 다만 **자리 자체는 다른 축**이다 —
+ * ISA-95 는 `OperationalLocation`("자원이 놓이거나 놓일 것으로 예상되는 논리적·물리적 장소",
+ * `B2MML-OperationalLocation.xsd`)을 별도 스키마로 두고, `Equipment` 가 자기 위치를 그것으로 가리킨다.
+ * 우리 `locations` 가 그 개념이다(2026-08-01 개명 — `plans/isa95-coverage.md` §3-1).
+ */
+export const EQUIPMENT_LEVEL = [
+    'Enterprise',
+    'Site',
+    'Area',
+    'ProcessCell',
+    'Unit',
+    'ProductionLine',
+    'WorkCell',
+    'ProductionUnit',
+    'StorageZone',
+    'StorageUnit',
+    'WorkCenter',
+    'WorkUnit',
+    'EquipmentModule',
+    'ControlModule',
+    'Other'
+];
+/** 표준 열거값인지 — 상류에서 들어온 값을 조용히 통과시키지 않고 확인하는 용도. */
+export function isEquipmentLevel(v) {
+    return typeof v === 'string' && EQUIPMENT_LEVEL.includes(v);
+}
+/**
+ * 계층 색인을 만든다. **순환은 만들 때 잡고 던진다** — 렌더 도중에 터지는 대신 여기서 한 번에.
+ * 순환을 조용히 잘라 내면 롤업이 틀린 값을 내고, 그건 이 함수가 막으려는 바로 그 실패다.
+ */
+export function hierarchyOf(s) {
+    const push = (m, k, v) => {
+        const cur = m.get(k);
+        if (cur)
+            cur.push(v);
+        else
+            m.set(k, [v]);
+    };
+    const parent = new Map();
+    const kids = new Map();
+    const known = new Set(s.locations.map(n => n.id));
+    for (const n of s.locations) {
+        if (!n.parentId || n.parentId === n.id)
+            continue; // 자기 부모는 선언 오류 — 사슬에 넣지 않는다
+        parent.set(n.id, n.parentId);
+        if (known.has(n.parentId))
+            push(kids, n.parentId, n.id);
+    }
+    /* 순환 검출 — 자리마다 사슬을 끝까지 밀어 본다. 방문한 자리를 다시 만나면 그 경로를 그대로 알린다. */
+    for (const start of known) {
+        const seen = [start];
+        for (let at = parent.get(start); at !== undefined; at = parent.get(at)) {
+            if (seen.includes(at))
+                throw new Error(`location hierarchy has a cycle: ${[...seen, at].join(' → ')}`);
+            seen.push(at);
+            if (!known.has(at))
+                break; // 구역에 닿았다 — 사슬 끝
+        }
+    }
+    const homes = new Map();
+    for (const m of s.equipment ?? [])
+        if (m.homeLocation)
+            push(homes, m.homeLocation, m.id);
+    const ancestorsOf = (id) => {
+        const out = [];
+        for (let at = parent.get(id); at !== undefined; at = parent.get(at)) {
+            out.push(at);
+            if (!known.has(at))
+                break;
+        }
+        return out;
+    };
+    const descendantsOf = (id) => {
+        const out = [];
+        const stack = [...(kids.get(id) ?? [])];
+        while (stack.length) {
+            const cur = stack.pop();
+            out.push(cur);
+            stack.push(...(kids.get(cur) ?? []));
+        }
+        return out;
+    };
+    const typeOf = new Map(s.locations.map(n => [n.id, n.type]));
+    const levelOf = new Map(s.locations.map(n => [n.id, n.level]));
+    return {
+        childrenOf: id => [...(kids.get(id) ?? [])],
+        ancestorsOf,
+        descendantsOf,
+        rollupOf: id => ancestorsOf(id).find(a => !known.has(a)),
+        ancestorOfLevel: (id, level) => ancestorsOf(id).find(a => known.has(a) && levelOf.get(a) === level),
+        ancestorOfType: (id, type) => ancestorsOf(id).find(a => known.has(a) && typeOf.get(a) === type),
+        equipmentOf: (id, opts) => {
+            const scope = opts?.deep ? [id, ...descendantsOf(id)] : [id];
+            return scope.flatMap(n => homes.get(n) ?? []);
+        }
+    };
+}
+/**
+ * 이 시각에 유효 기간 밖인가 — **한 규칙**으로 개체·등급·설비↔자산 매핑을 모두 판정한다.
+ *
+ * **표준은 날짜만 정하고 "밖이면 어떻게 되는가" 는 정하지 않는다.** 그 판단은 우리 것이므로 여기 밝힌다:
+ * 기간 밖이면 **그 자원은 그 시각의 모델에 참여하지 않는다**(배정되지 않고, 가용 분모에 들지 않는다).
+ * 지우지는 않는다 — 이유를 달아 남긴다. 조용히 사라지면 "왜 없어졌나" 를 아무도 답할 수 없다.
+ *
+ * `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;
+}
+/**
+ * 등급 소속을 **상속을 타고 닫는다** — "이 개체가 이 등급으로 통하는가".
+ *
+ * 순환은 방문 집합으로 끊는다(잘못된 마스터가 무한 루프를 만들지 않게). 등급 정의가 없으면 소속
+ * 그대로만 본다 — 정의를 요구하지 않는다(정의를 싣지 않은 트윈이 그대로 돌아야 한다).
+ *
+ * `at` 를 주면 **유효 기간 밖의 등급은 제외**한다. 안 주면 기간을 보지 않는다(모르면 판단하지 않는다).
+ */
+export function classClosure(directIds, defs, at) {
+    const byId = new Map((defs ?? []).map(d => [d.id, d]));
+    const inWindow = (d) => !d || effectivityAt(d, at) === undefined;
+    const out = new Set();
+    const stack = [...(directIds ?? [])];
+    while (stack.length) {
+        const id = stack.pop();
+        if (out.has(id))
+            continue;
+        const def = byId.get(id);
+        if (!inWindow(def))
+            continue; // 만료된 등급은 자기도, 그 상위도 타지 않는다
+        out.add(id);
+        for (const b of def?.baseIds ?? [])
+            if (!out.has(b))
+                stack.push(b);
+    }
+    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·movers(equipment)·orders 의 운영 상태는
+// EPCIS 이벤트는 재고/위치만 재구성 가능. tasks·equipment·orders 의 운영 상태는
 // 이 델타로 미러한다. envelope.eventType = 'task.status' | 'equipment.status' | 'order.status'.
 // (execution-model.md §5, roadmap 발견 gap: 운영 델타 이벤트화)
 export const OP_EVENT = {
@@ -40,11 +506,57 @@ export const CMD = {
     orderResume: 'order.resume',
     orderRelease: 'order.release',
     attentionAck: 'attention.ack', // 주목 신호 확인(OPC UA A&C acknowledge) — args:{id}
-    // Operable 코어 — 모든 operable 자원(설비·이동무버) 공통. args:{resourceId}. capability-keyed(무방언, equipment.* 아님).
+    // Operable 코어 — 모든 operable 자원(설비·이동설비) 공통. args:{resourceId}. capability-keyed(무방언, equipment.* 아님).
     resourceHold: 'resource.hold', // 계획 정지(정비/오프라인) — 배정 스킵
     resourceResume: 'resource.resume', // 계획 정지 해제
     resourceDown: 'resource.down', // 비계획 고장 주입 — args:{resourceId, durationMs?}
     resourceRepair: 'resource.repair', // 즉시 수리
     resourceResetMetrics: 'resource.reset-metrics', // OEE 계측 창 리셋
-    resourceAdd: 'resource.add' // 라이브 자원(무버) 추가 — args:{kind, homeNode, count?}. 런타임 구조 변이(what-if 아닌 실제 act)
+    resourceAdd: 'resource.add' // 라이브 자원(설비) 추가 — args:{kind, homeLocation, count?}. 런타임 구조 변이(what-if 아닌 실제 act)
 };
+// ── 보드 청사진 바인딩 (최소) ──────────────────────────────────────────────
+/**
+ * **저장된 보드를 읽는 단 하나의 입구.**
+ *
+ * `equipment` 로 개명하기 전에 저장된 보드는 `movers` 키를 갖고 있다(개명 시점 23개 인스턴스).  (vocabulary-guard: allow — 읽기 호환 설명)
+ * 저장물을 다시 쓰지 않고 **읽을 때 흡수**한다 — 마이그레이션은 되돌리기 어렵고, 읽기 호환은 값싸다.
+ *
+ * 규율 둘:
+ *  - 이 함수를 **거치지 않고** `def.equipment` 를 직접 읽는 코드를 두지 않는다. 하나라도 남으면
+ *    그 경로에서만 옛 보드의 설비가 조용히 사라진다(빈 배열).
+ *  - **쓸 때는 새 이름만** 쓴다. 두 이름으로 쓰기 시작하면 저장물에 두 벌이 영구히 섞인다.
+ *
+ * 제거 시점: 저장된 보드가 모두 `equipment` 키로 바뀐 것이 확인되면(운영 데이터 점검 후) 이 함수는
+ * 사라진다. 그때까지 남겨 두는 이유를 여기 적어 두는 것이 주석의 일이다.
+ */
+/**
+ * **저장된 보드의 자리를 읽는 단 하나의 입구.** `readBoardEquipment` 와 같은 규율.
+ *
+ * `nodes` → `locations` 개명(2026-08-01) 전에 저장된 보드는 `nodes` 키를 갖고 있다(개명 시점 23개).  (vocabulary-guard: allow — 읽기 호환 설명)
+ * 이 함수를 거치지 않고 `def.locations` 를 직접 읽는 코드를 두지 않는다 — 하나라도 남으면 그 경로에서만
+ * 옛 보드의 자리가 조용히 사라진다(빈 배열 = 자리 없는 트윈 = 아무 일도 일어나지 않는다).
+ */
+export function readBoardLocations(def) {
+    const d = def; // vocabulary-guard: allow — 옛 키 캐스트
+    return d.locations ?? d.nodes ?? []; // vocabulary-guard: allow — 옛 키 흡수
+}
+export function readBoardEquipment(def) {
+    const d = def; // vocabulary-guard: allow — 옛 키를 읽어야 하는 자리
+    const list = d.equipment ?? d.equipmentList ?? []; // vocabulary-guard: allow — 옛 키 흡수
+    /* 소속 자리 키도 함께 정규화한다 — `homeNode → homeLocation` 개명 전 보드가 23개 있다.  (vocabulary-guard: allow — 옛 키 정규화 설명)
+       배열만 흡수하고 안쪽 키를 놓치면 설비는 나타나지만 **소속이 전부 비어** 롤업이 통째로 사라진다. */
+    return list.map(e => normalizeHomeLocation(e));
+}
+/** 소속 자리 키 정규화 — 설비·자산이 같은 규칙을 쓴다(둘 다 옛 이름이 저장돼 있다). */
+function normalizeHomeLocation(entry) {
+    const legacy = entry.homeNode; // vocabulary-guard: allow — 옛 키를 읽어야 하는 자리
+    if (legacy === undefined || entry.homeLocation !== undefined)
+        return entry;
+    const { homeNode: _drop, ...rest } = entry; // vocabulary-guard: allow — 옛 키 제거
+    return { ...rest, homeLocation: legacy };
+}
+/** 저장된 보드의 반복사용 자산 — 설비와 같은 정규화를 거친다. */
+export function readBoardAssets(def) {
+    const list = (def.assets ?? []);
+    return list.map(a => normalizeHomeLocation(a));
+}

package/dist/divergence.d.ts

@@ -8,7 +8,7 @@ export interface StateDivergence {
     hasDrift: boolean;
     itemLocation: FieldDiff<string>[];
     itemDisposition: FieldDiff<string>[];
-    nodeOccupancy: FieldDiff<number>[];
+    locationOccupancy: FieldDiff<number>[];
     orderStatus: FieldDiff<string>[];
 }
 /** predicted(fork forecast)와 actual(관측) 스냅샷을 대조. 같은 sim 시점에 호출하는 것이 의미 있음. */

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,10 +20,12 @@ 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);
-    const nodeOccupancy = diffBy(predicted.nodes, actual.nodes, n => n.id, n => n.occupancy);
+    /* 키는 **한 규칙**으로 잡는다(`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 || nodeOccupancy.length > 0 || orderStatus.length > 0;
-    return { hasDrift, itemLocation, itemDisposition, nodeOccupancy, orderStatus };
+    const hasDrift = itemLocation.length > 0 || itemDisposition.length > 0 || locationOccupancy.length > 0 || orderStatus.length > 0;
+    return { hasDrift, itemLocation, itemDisposition, locationOccupancy, orderStatus };
 }

package/dist/domain-catalog.d.ts

@@ -4,7 +4,7 @@ export interface TwinTypeInfo {
     /** 커널 권위 키 (예: 'storage', 'forklift'). */
     key: string;
     /** 로케이션(수동) vs 자원(능동). */
-    role: 'node' | 'mover';
+    role: 'location' | 'equipment';
     label: string;
     /** ① 표준 온톨로지 투영(03-reference-standards). 열린 문자열 — 하드코딩 enum 금지. */
     standardClass: {
@@ -22,10 +22,10 @@ export interface TwinTypeInfo {
 export interface DomainProfileInfo {
     system: DomainSystem;
     label: string;
-    /** 노드+무버 트윈 타입 — board·UI 팔레트 소싱 SSOT. */
+    /** 자리+설비 트윈 타입 — board·UI 팔레트 소싱 SSOT. */
     types: TwinTypeInfo[];
-    /** 로케이션 노드 타입 키(하위호환 파생 뷰 = types 중 role==='node'). 신규 소싱은 types 사용. */
-    nodeTypes: readonly string[];
+    /** 로케이션 자리 타입 키(하위호환 파생 뷰 = types 중 role==='location'). 신규 소싱은 types 사용. */
+    locationTypes: readonly string[];
 }
 export declare const DOMAIN_CATALOG: Record<DomainSystem, DomainProfileInfo>;
 export declare const DOMAIN_SYSTEMS: DomainSystem[];

package/dist/domain-catalog.js

@@ -1,12 +1,12 @@
 import { WMS_TYPES } from "./wms-profile.js";
 import { YMS_TYPES } from "./yms-profile.js";
 import { MES_TYPES } from "./mes-profile.js";
-const nodeKeys = (types) => types.filter(t => t.role === 'node').map(t => t.key);
+const locationKeys = (types) => types.filter(t => t.role === 'location').map(t => t.key);
 export const DOMAIN_CATALOG = {
     // label 은 언어 중립 i18n 키(twin.system.<code>) — 사람 언어는 표현계층이 렌더(L2).
-    wms: { system: 'wms', label: 'twin.system.wms', types: WMS_TYPES, nodeTypes: nodeKeys(WMS_TYPES) },
-    yms: { system: 'yms', label: 'twin.system.yms', types: YMS_TYPES, nodeTypes: nodeKeys(YMS_TYPES) },
-    mes: { system: 'mes', label: 'twin.system.mes', types: MES_TYPES, nodeTypes: nodeKeys(MES_TYPES) }
+    wms: { system: 'wms', label: 'twin.system.wms', types: WMS_TYPES, locationTypes: locationKeys(WMS_TYPES) },
+    yms: { system: 'yms', label: 'twin.system.yms', types: YMS_TYPES, locationTypes: locationKeys(YMS_TYPES) },
+    mes: { system: 'mes', label: 'twin.system.mes', types: MES_TYPES, locationTypes: locationKeys(MES_TYPES) }
 };
 export const DOMAIN_SYSTEMS = ['wms', 'yms', 'mes'];
 /** 타입 키 → 능력 프로파일(커널 SSOT). 호스트가 라이브 페이로드에 투영, 컴포넌트가 능력을 렌더. */