@operato/twin-kernel 0.6.12 → 0.6.14

package/dist/event-journal.d.ts

@@ -13,11 +13,20 @@ export declare class EventJournal {
     /** sim 시각(ISO eventTime) 이하 이벤트. */
     untilSimTime(iso: string): CanonicalEnvelope[];
 }
-/** 이벤트열 → 상태 재구성(시간여행). board = 마스터(토폴로지·설비). */
-export declare function replay(board: TwinModelDef, events: readonly CanonicalEnvelope[]): ProjectedState;
-/** 한 구조 아래에서 일어난 이벤트들 — 재생의 한 마디. */
+/** 이벤트열 → 상태 재구성(시간여행). `model` = 그 시점의 트윈 모델(토폴로지·자원). */
+export declare function replay(model: TwinModelDef, events: readonly CanonicalEnvelope[]): ProjectedState;
+/**
+ * 한 구조 아래에서 일어난 이벤트들 — 재생의 한 마디.
+ *
+ * 필드 이름이 `model` 인 이유: 이 값의 정체는 **트윈 모델**이다(`TwinModelDef`). 보드는 그것을 그리는
+ * 표현 중 하나일 뿐이고, 소비처는 이미 전부 `model` 로 옮겼다. 그동안 호스트가 넘길 때마다 `model` 을
+ * `board` 키로 되돌려 담는 **어휘 번역기**가 경계에 끼어 있었다 — 조용히 `model` 로 넘기면 커널이
+ * `undefined` 를 읽고 재생이 통째로 죽던 자리다. 이름을 맞추면 그 브릿지가 사라진다.
+ *
+ * 옛 키를 함께 받지 않는다: 둘 다 받으면 "어느 쪽이 정본인가" 가 남고, 그 애매함이 브릿지의 본질이다.
+ */
 export interface StructureSegment {
-    board: TwinModelDef;
+    model: TwinModelDef;
     events: readonly CanonicalEnvelope[];
 }
 /**

package/dist/event-journal.js

@@ -32,9 +32,9 @@ export class EventJournal {
         return this.events.filter(e => e.eventTime <= iso);
     }
 }
-/** 이벤트열 → 상태 재구성(시간여행). board = 마스터(토폴로지·설비). */
-export function replay(board, events) {
-    const proj = new StateProjector(board);
+/** 이벤트열 → 상태 재구성(시간여행). `model` = 그 시점의 트윈 모델(토폴로지·자원). */
+export function replay(model, events) {
+    const proj = new StateProjector(model);
     for (const e of events)
         proj.apply(e);
     return proj.snapshot();
@@ -54,12 +54,12 @@ export function replay(board, events) {
 export function replaySegments(segments) {
     if (!segments.length)
         throw new Error('재생할 마디가 없다 — 구조를 하나도 주지 않았다');
-    const proj = new StateProjector(segments[0].board);
+    const proj = new StateProjector(segments[0].model);
     const shifts = [];
     for (let i = 0; i < segments.length; i++) {
         /* 첫 마디는 생성자가 이미 그 구조로 섰다 — 두 번 세우면 관측 전 상태를 다시 덮는다. */
         if (i > 0)
-            shifts.push({ index: i, ...proj.adoptStructure(segments[i].board) });
+            shifts.push({ index: i, ...proj.adoptStructure(segments[i].model) });
         for (const e of segments[i].events)
             proj.apply(e);
     }

package/dist/observed-reducer.d.ts

@@ -79,7 +79,7 @@ export declare class ObservedReducer {
     private classDefs;
     /** 시각 해석 기준(보드 선언) — 없으면 UTC. 캘린더의 `HH:MM` 이 어느 기준인지 정한다. */
     private utcOffsetMinutes?;
-    constructor(board: TwinModelDef);
+    constructor(model: TwinModelDef);
     /**
      * **구조를 갈아탄다** — 관측된 사실은 지키고 토폴로지만 새 선언으로 바꾼다.
      *
@@ -98,7 +98,7 @@ export declare class ObservedReducer {
      * 관측으로 알게 된 자리(`origin: 'observed'`)는 **새 마스터에 없어도 남긴다** — 마스터가 모르는
      * 자리에서 물건이 실제로 보였다는 사실은 구조를 바꾼다고 사라지지 않는다.
      */
-    adoptStructure(board: TwinModelDef): StructureShift;
+    adoptStructure(model: TwinModelDef): StructureShift;
     /** 마스터 동기 — 로케이션 추가/변경/제거. */
     applyMaster(u: MasterUpdate): void;
     /**

package/dist/observed-reducer.js

@@ -71,24 +71,24 @@ export class ObservedReducer {
     classDefs = {};
     /** 시각 해석 기준(보드 선언) — 없으면 UTC. 캘린더의 `HH:MM` 이 어느 기준인지 정한다. */
     utcOffsetMinutes;
-    constructor(board) {
-        this.utcOffsetMinutes = board.utcOffsetMinutes;
-        this.classDefs = { personnel: board.personnelClasses, equipment: board.equipmentClasses, asset: board.assetClasses };
-        for (const n of readBoardLocations(board))
+    constructor(model) {
+        this.utcOffsetMinutes = model.utcOffsetMinutes;
+        this.classDefs = { personnel: model.personnelClasses, equipment: model.equipmentClasses, asset: model.assetClasses };
+        for (const n of readBoardLocations(model))
             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))
+        for (const m of readBoardEquipment(model))
             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 } : {}), ...(m.testResults ? { testResults: m.testResults } : {}), ...effectiveOf(m), origin: 'master' });
         // 사람 기준선(마스터) — person.status 델타로 갱신됨.
-        for (const p of board.persons ?? [])
+        for (const p of model.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 } : {}), ...(p.testResults ? { testResults: p.testResults } : {}), ...effectiveOf(p) });
         /* 교대 선언은 **미러도 들고 있어야 한다** — 설비 델타에는 `offShift` 자리조차 없어서, 그것 없이는
            미러의 설비가 점심 휴게 중에도 "대기" 로 보였다. */
-        for (const m of readBoardEquipment(board))
+        for (const m of readBoardEquipment(model))
             this.rememberShift(`eq:${m.id}`, m);
-        for (const p of board.persons ?? [])
+        for (const p of model.persons ?? [])
             this.rememberShift(`person:${p.id}`, p);
-        for (const a of readBoardAssets(board))
+        for (const a of readBoardAssets(model))
             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 } : {}), ...(a.testResults ? { testResults: a.testResults } : {}), ...effectiveOf(a) });
     }
     /**
@@ -109,9 +109,9 @@ export class ObservedReducer {
      * 관측으로 알게 된 자리(`origin: 'observed'`)는 **새 마스터에 없어도 남긴다** — 마스터가 모르는
      * 자리에서 물건이 실제로 보였다는 사실은 구조를 바꾼다고 사라지지 않는다.
      */
-    adoptStructure(board) {
-        this.utcOffsetMinutes = board.utcOffsetMinutes;
-        const locations = readBoardLocations(board);
+    adoptStructure(model) {
+        this.utcOffsetMinutes = model.utcOffsetMinutes;
+        const locations = readBoardLocations(model);
         const declaredLocationIds = new Set(locations.map(n => n.id));
         let locationsAdded = 0;
         let locationsDropped = 0;
@@ -128,9 +128,9 @@ export class ObservedReducer {
         }
         /* 자원은 **선언이 전부다** — 관측으로 생기지 않는다(설비는 이벤트가 만들어 내지 않는다).
            그래서 새 선언에 없으면 없는 것이고, 남아 있는 것은 지금까지의 상태를 그대로 이어 간다. */
-        const equipment = readBoardEquipment(board);
-        const assets = readBoardAssets(board);
-        const persons = board.persons ?? [];
+        const equipment = readBoardEquipment(model);
+        const assets = readBoardAssets(model);
+        const persons = model.persons ?? [];
         const dropMissing = (map, declared) => {
             const ids = new Set(declared.map(d => d.id));
             let dropped = 0;

package/dist/operations-capability.d.ts

@@ -37,8 +37,19 @@ export interface OperationCapability {
      * `Math.max(0, …)` 하나로 덮는 일이 실제로 이 트윈에서 여러 번 있었다.
      */
     available: number | null;
-    /** 무엇이 묶고 있나 — 축과 등급(용량 분석이 이미 낸다). */
+    /** 무엇이 **천장**을 묶고 있나 — 축과 등급(용량 분석이 이미 낸다). 선언 기준이다. */
     constraint?: CapacityRequirement;
+    /**
+     * **남은 능력을 묶는 축** — 달성불가를 되찾으려면 여기부터다. `unattainable > 0` 일 때만 있다.
+     *
+     * 천장을 묶는 축과 **다를 수 있고**, 그 차이가 곧 사람이 헛걸음하는 자리다: 용접기 2대와 용접
+     * 자격자 2명이 같은 천장을 낼 때 천장은 어느 쪽으로도 묶이지만, 자격 하나가 만료돼 잃은 몫의
+     * 원인은 인원이다. 화면이 천장 쪽만 보이면 사람이 **설비를 보러 간다**(실제로 그랬다).
+     *
+     * 값은 이미 손에 있다 — 달성불가를 내려고 가용 자원 기준으로 같은 계산을 한 번 더 돌리기 때문이다.
+     * 그 계산이 묶는 축이 곧 이 답이고, 따로 판정을 만들지 않는다.
+     */
+    unattainableBy?: CapacityRequirement;
 }
 export interface OperationsCapabilityReport {
     /** 표준 `OperationsType` — 지금은 생산뿐이다(정비·품질 능력은 별도 보고서가 될 자리). */

package/dist/operations-capability.js

@@ -90,9 +90,14 @@ export function operationsCapabilityOf(input) {
          * 아닌 입력을 받은 것이므로 값을 지어내는 대신 아래 `available` 이 어긋남을 드러낸다.
          */
         let unattainable = null;
+        let unattainableBy;
         if (usable) {
-            const usableAmount = amountOf(usable.operations.find(o => o.operation === op.operation)?.perHour ?? NaN);
+            const left = usable.operations.find(o => o.operation === op.operation);
+            const usableAmount = amountOf(left?.perHour ?? NaN);
             unattainable = total != null && usableAmount != null ? Math.max(0, total - usableAmount) : null;
+            /* 잃은 몫이 있을 때만 원인을 말한다 — 잃은 것이 없는데 "여기부터" 라고 하면 없는 일을 만든다. */
+            if (unattainable != null && unattainable > 0 && left?.constraint)
+                unattainableBy = left.constraint;
         }
         const available = total == null || unattainable == null ? null : total - committed - unattainable;
         return {
@@ -101,7 +106,8 @@ export function operationsCapabilityOf(input) {
             committed,
             unattainable,
             available,
-            ...(op.constraint ? { constraint: op.constraint } : {})
+            ...(op.constraint ? { constraint: op.constraint } : {}),
+            ...(unattainableBy ? { unattainableBy } : {})
         };
     });
     return {

package/dist-cjs/index.cjs

@@ -994,15 +994,15 @@ var ObservedReducer = class {
   classDefs = {};
   /** 시각 해석 기준(보드 선언) — 없으면 UTC. 캘린더의 `HH:MM` 이 어느 기준인지 정한다. */
   utcOffsetMinutes;
-  constructor(board) {
-    this.utcOffsetMinutes = board.utcOffsetMinutes;
-    this.classDefs = { personnel: board.personnelClasses, equipment: board.equipmentClasses, asset: board.assetClasses };
-    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" });
-    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 } : {}, ...m.testResults ? { testResults: m.testResults } : {}, ...effectiveOf(m), origin: "master" });
-    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 } : {}, ...p.testResults ? { testResults: p.testResults } : {}, ...effectiveOf(p) });
-    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 } : {}, ...a.testResults ? { testResults: a.testResults } : {}, ...effectiveOf(a) });
+  constructor(model) {
+    this.utcOffsetMinutes = model.utcOffsetMinutes;
+    this.classDefs = { personnel: model.personnelClasses, equipment: model.equipmentClasses, asset: model.assetClasses };
+    for (const n of readBoardLocations(model)) this.master.set(n.id, { id: n.id, type: n.type, capacity: n.capacity, parallelism: n.parallelism, parentId: n.parentId, origin: "master" });
+    for (const m of readBoardEquipment(model)) 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 } : {}, ...m.testResults ? { testResults: m.testResults } : {}, ...effectiveOf(m), origin: "master" });
+    for (const p of model.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 } : {}, ...p.testResults ? { testResults: p.testResults } : {}, ...effectiveOf(p) });
+    for (const m of readBoardEquipment(model)) this.rememberShift(`eq:${m.id}`, m);
+    for (const p of model.persons ?? []) this.rememberShift(`person:${p.id}`, p);
+    for (const a of readBoardAssets(model)) 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 } : {}, ...a.testResults ? { testResults: a.testResults } : {}, ...effectiveOf(a) });
   }
   /**
    * **구조를 갈아탄다** — 관측된 사실은 지키고 토폴로지만 새 선언으로 바꾼다.
@@ -1022,9 +1022,9 @@ var ObservedReducer = class {
    * 관측으로 알게 된 자리(`origin: 'observed'`)는 **새 마스터에 없어도 남긴다** — 마스터가 모르는
    * 자리에서 물건이 실제로 보였다는 사실은 구조를 바꾼다고 사라지지 않는다.
    */
-  adoptStructure(board) {
-    this.utcOffsetMinutes = board.utcOffsetMinutes;
-    const locations = readBoardLocations(board);
+  adoptStructure(model) {
+    this.utcOffsetMinutes = model.utcOffsetMinutes;
+    const locations = readBoardLocations(model);
     const declaredLocationIds = new Set(locations.map((n) => n.id));
     let locationsAdded = 0;
     let locationsDropped = 0;
@@ -1037,9 +1037,9 @@ var ObservedReducer = class {
       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 equipment = readBoardEquipment(model);
+    const assets = readBoardAssets(model);
+    const persons = model.persons ?? [];
     const dropMissing = (map, declared) => {
       const ids = new Set(declared.map((d) => d.id));
       let dropped = 0;
@@ -1494,17 +1494,17 @@ var EventJournal = class {
     return this.events.filter((e) => e.eventTime <= iso2);
   }
 };
-function replay(board, events) {
-  const proj = new ObservedReducer(board);
+function replay(model, events) {
+  const proj = new ObservedReducer(model);
   for (const e of events) proj.apply(e);
   return proj.snapshot();
 }
 function replaySegments(segments) {
   if (!segments.length) throw new Error("\uC7AC\uC0DD\uD560 \uB9C8\uB514\uAC00 \uC5C6\uB2E4 \u2014 \uAD6C\uC870\uB97C \uD558\uB098\uB3C4 \uC8FC\uC9C0 \uC54A\uC558\uB2E4");
-  const proj = new ObservedReducer(segments[0].board);
+  const proj = new ObservedReducer(segments[0].model);
   const shifts = [];
   for (let i = 0; i < segments.length; i++) {
-    if (i > 0) shifts.push({ index: i, ...proj.adoptStructure(segments[i].board) });
+    if (i > 0) shifts.push({ index: i, ...proj.adoptStructure(segments[i].model) });
     for (const e of segments[i].events) proj.apply(e);
   }
   return { state: proj.snapshot(), shifts };
@@ -2276,9 +2276,12 @@ function operationsCapabilityOf(input) {
     const total = amountOf(op.perHour);
     const committed = committedOf(op.operation);
     let unattainable = null;
+    let unattainableBy;
     if (usable) {
-      const usableAmount = amountOf(usable.operations.find((o) => o.operation === op.operation)?.perHour ?? NaN);
+      const left = usable.operations.find((o) => o.operation === op.operation);
+      const usableAmount = amountOf(left?.perHour ?? NaN);
       unattainable = total != null && usableAmount != null ? Math.max(0, total - usableAmount) : null;
+      if (unattainable != null && unattainable > 0 && left?.constraint) unattainableBy = left.constraint;
     }
     const available = total == null || unattainable == null ? null : total - committed - unattainable;
     return {
@@ -2287,7 +2290,8 @@ function operationsCapabilityOf(input) {
       committed,
       unattainable,
       available,
-      ...op.constraint ? { constraint: op.constraint } : {}
+      ...op.constraint ? { constraint: op.constraint } : {},
+      ...unattainableBy ? { unattainableBy } : {}
     };
   });
   return {

package/package.json

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