@operato/twin-kernel 0.10.1 → 0.11.0

package/dist/flow-engine.d.ts

@@ -1,4 +1,4 @@
-import type { TestResult, ISOTime, MaterialQuantity, WorkCalendarEntry, EffectivePeriod, Effectivity, OffCalendarReason, ResourceProperty, ResourceClassDef, MaterialDefinition, Attention, TwinModelDef, CanonicalEnvelope, Command, CommandAck, EventHandler, EquipmentMotion, AssetState, GeneratorSpec, InterventionOutcome, OrderState, PersonState, ScenarioControl, ScenarioOverride, StateSnapshot, TwinKernel, Unsubscribe, LocationState, ItemState, EquipmentState, OrderStatusDelta, TaskState, TaskStatus, StructureShift, IdentityGroundingView, IdentityDeclaration, TestSpecificationCriterion, LocationObservation } from '@operato/ops-contract';
+import type { MaterialActual, TestResult, ISOTime, MaterialQuantity, WorkCalendarEntry, EffectivePeriod, Effectivity, OffCalendarReason, ResourceProperty, ResourceClassDef, MaterialDefinition, Attention, TwinModelDef, CanonicalEnvelope, Command, CommandAck, EventHandler, EquipmentMotion, AssetState, GeneratorSpec, InterventionOutcome, OrderState, PersonState, ScenarioControl, ScenarioOverride, StateSnapshot, TwinKernel, Unsubscribe, LocationState, ItemState, EquipmentState, OrderStatusDelta, TaskState, TaskStatus, StructureShift, IdentityGroundingView, IdentityDeclaration, TestSpecificationCriterion, LocationObservation } from '@operato/ops-contract';
 import type { VocabularyElement } from '@operato/ops-contract';
 import type { ReducerCheckpoint } from './observed-reducer.ts';
 import type { EpcisEvent, BizTransactionElement } from '@operato/ops-contract';
@@ -159,12 +159,7 @@ export interface FlowTask {
      * 명세(계획)가 아니라 **일어난 일**이다. 투입 인원·설비가 이미 작업 델타에 타고 있으니 자재도 같은
      * 채널에 실어야 실적을 **한 곳에서** 읽는다(EPCIS 이벤트에서 다시 계산하려면 작업과 잇는 끈이 없다).
      */
-    materialActual?: {
-        definitionId: string;
-        use: 'consumed' | 'produced';
-        quantity: number;
-        uom?: string;
-    }[];
+    materialActual?: MaterialActual[];
     itemEpc: string;
     fromNode: string;
     toNode: string;

package/dist/flow-engine.js

@@ -3237,7 +3237,8 @@ export class FlowEngine {
                 if (n)
                     n.occupancy++;
             }
-            this.recordMaterialActual(t, gtin, 'produced', qty, spec.uom);
+            /* 산출 로트의 식별자 — 비직렬 로트는 클래스 식별자가 곧 로트의 이름이다. */
+            this.recordMaterialActual(t, gtin, 'produced', qty, spec.uom, gtin);
             this.emit(objectEvent({
                 eventTime: this.now(), action: 'ADD', bizStep: CBV_BIZSTEP.commissioning, disposition: DISP.in_progress,
                 epcList: [], quantityList: [{ epcClass: gtin, quantity: total, ...(spec.uom ? { uom: spec.uom } : {}) }],
@@ -3327,15 +3328,26 @@ export class FlowEngine {
      * 실제 자재 이동을 작업에 적어 둔다 — ISA-95 `JobResponse.MaterialActual`.
      * 같은 품목·같은 쓰임은 **한 줄로 합친다**(줄을 늘리면 실적을 세는 쪽이 중복을 걷어내야 한다).
      */
-    recordMaterialActual(t, definitionId, use, quantity, uom) {
+    recordMaterialActual(t, definitionId, use, quantity, uom, 
+    /**
+     * 어느 로트인가 — 표준 `MaterialLotID`. **식별자**이고 로트 번호 문자열이 아니다.
+     *
+     * 이 값이 있어야 「이 로트로 무엇을 만들었나」가 이어진다. 불합격 로트의 이동 제한과 계보가 그 위에
+     * 선다. 모르면 넣지 않는다 — 지어내면 다른 로트의 실적이 된다.
+     */
+    lotId) {
         if (!definitionId || !(quantity > 0))
             return;
         const rows = (t.materialActual ??= []);
-        const hit = rows.find(r => r.definitionId === definitionId && r.use === use && r.uom === uom);
+        /*
+         * **로트가 다르면 다른 줄이다.** 합치면 어느 로트를 얼마나 썼는지 사라지고, 그것이 이 필드를 만든
+         * 이유 자체다. 같은 품목·같은 쓰임·같은 로트만 한 줄로 합친다.
+         */
+        const hit = rows.find(r => r.definitionId === definitionId && r.use === use && r.uom === uom && r.lotId === lotId);
         if (hit)
             hit.quantity += quantity;
         else
-            rows.push({ definitionId, use, quantity, ...(uom ? { uom } : {}) });
+            rows.push({ definitionId, use, quantity, ...(uom ? { uom } : {}), ...(lotId ? { lotId } : {}) });
     }
     /** 확보한 자재를 **작업 시작 시점에 소비**한다 — 수량이 0 이 되면 물품 자체가 사라진다. */
     consumeMaterials(t, taken) {
@@ -3352,7 +3364,7 @@ export class FlowEngine {
             const left = (it.qty ?? 1) - take;
             if (left > 0) {
                 it.qty = left;
-                this.recordMaterialActual(t, it.definitionId ?? it.gtin, 'consumed', take, it.uom);
+                this.recordMaterialActual(t, it.definitionId ?? it.gtin, 'consumed', take, it.uom, it.epc);
                 /* 남은 수량을 그대로 알린다 — 관측 경로가 그 자리의 사실을 갱신한다(§quantityList). */
                 this.emit(objectEvent({
                     eventTime: this.now(), action: 'OBSERVE', bizStep: CBV_BIZSTEP.consuming, disposition: DISP.in_progress,
@@ -3361,7 +3373,7 @@ export class FlowEngine {
                 }));
                 continue;
             }
-            this.recordMaterialActual(t, it.definitionId ?? it.gtin, 'consumed', take, it.uom);
+            this.recordMaterialActual(t, it.definitionId ?? it.gtin, 'consumed', take, it.uom, it.epc);
             whole.push(epc);
         }
         if (!whole.length)

package/dist/job-response.d.ts

@@ -1,4 +1,4 @@
-import type { ISOTime } from '@operato/ops-contract';
+import type { ISOTime, MaterialActual } from '@operato/ops-contract';
 import { type TaskDeltaRow } from './task-fold.ts';
 /** 표준 `JobState` — 우리 작업 상태를 표준 낱말로 옮긴다. */
 export type JobState = 'ready' | 'running' | 'completed';
@@ -9,15 +9,7 @@ export interface ResourceActual {
     /** 표준 `Quantity`. 우리는 개체를 지목하므로 언제나 1이다(등급 단위 집계는 소비처의 일). */
     quantity: number;
 }
-/** 자재 실적 한 줄 — 표준 `OpMaterialActualType` 의 우리 부분집합. */
-export interface MaterialActual {
-    /** 표준 `MaterialDefinitionID`. */
-    definitionId: string;
-    /** 표준 `MaterialUse`. */
-    use: 'consumed' | 'produced';
-    quantity: number;
-    uom?: string;
-}
+export type { MaterialActual };
 export interface JobResponse {
     /** 표준 `ID` — 작업 식별자. */
     id: string;
@@ -56,4 +48,3 @@ type Row = TaskDeltaRow;
  * 자원·자재 실적은 전이가 실어 온 값에서 모은다. **마지막에 본 값**이 사실이다(재전송이면 나중 것).
  */
 export declare function foldJobResponses(rows: readonly Row[]): JobResponse[];
-export {};

package/dist/mes-kernel.d.ts

@@ -37,6 +37,18 @@ export declare class MesKernel extends FlowEngine {
      *
      * 런타임에 조용히 어긋나는 것보다 기동이 실패하는 편이 낫다.
      */
+    /**
+     * 라우트의 **절차 계층**이 단계와 어긋나지 않는가 (ISA-88).
+     *
+     * ── 왜 이제야 부르나 (2026-08-31) ─────────────────────────────────────────
+     * 계약이 `procedureViolations` 를 갖고 있었는데 **아무도 부르지 않았다** — 계약의 자기 시험만
+     * 불렀다. 그래서 절차를 선언해도 어긋난 것이 그냥 지나갔고, 화면은 잘못된 트리를 오류 없이 보였다.
+     *
+     * 선언을 읽는 곳이 있는지 보는 하네스가 이것을 잡았다(§`declaration-is-read.test.ts`).
+     *
+     * 판정은 계약이 한다 — 여기서 다시 만들면 규칙이 두 벌이 되고, 화면도 같은 판정을 해야 한다.
+     */
+    private assertRouteProcedures;
     private assertRecipeOperationTags;
     /**
      * **레시피 모드에서는 MES 가 산출을 소유한다** — 코어는 비켜선다(§`producesOwnOutputs`).

package/dist/mes-kernel.js

@@ -8,7 +8,7 @@
  *  ③ 셋업/체인지오버 = work-center 가 제품 전환 시 셋업(changeoverKey=제품 gtin) → OEE Availability.
  *  ④ OEE = base 가 설비(설비)별 계측(가동/셋업/기아/품질). cut=cutter·weld=welder 이종 자원.
  */
-import { identityGroundingOf } from '@operato/ops-contract';
+import { identityGroundingOf, procedureViolations } from '@operato/ops-contract';
 import { firstFitPolicy } from "./allocation-policy.js";
 import { FlowEngine } from "./flow-engine.js";
 import { DISP, objectEvent, transactionEvent, gdtiUri, sgtinClass, bizTransactionUri } from '@operato/ops-contract';
@@ -76,6 +76,7 @@ export class MesKernel extends FlowEngine {
             this.assertNoDoubleProduction(productionSpec.definition.operations);
         }
         this.assertRecipeOperationTags();
+        this.assertRouteProcedures();
     }
     /**
      * **산출을 두 곳에서 만들지 않는다** — 기동 때 막는다.
@@ -131,6 +132,26 @@ export class MesKernel extends FlowEngine {
      *
      * 런타임에 조용히 어긋나는 것보다 기동이 실패하는 편이 낫다.
      */
+    /**
+     * 라우트의 **절차 계층**이 단계와 어긋나지 않는가 (ISA-88).
+     *
+     * ── 왜 이제야 부르나 (2026-08-31) ─────────────────────────────────────────
+     * 계약이 `procedureViolations` 를 갖고 있었는데 **아무도 부르지 않았다** — 계약의 자기 시험만
+     * 불렀다. 그래서 절차를 선언해도 어긋난 것이 그냥 지나갔고, 화면은 잘못된 트리를 오류 없이 보였다.
+     *
+     * 선언을 읽는 곳이 있는지 보는 하네스가 이것을 잡았다(§`declaration-is-read.test.ts`).
+     *
+     * 판정은 계약이 한다 — 여기서 다시 만들면 규칙이 두 벌이 되고, 화면도 같은 판정을 해야 한다.
+     */
+    assertRouteProcedures() {
+        const routes = this.productionSpec?.definition?.routes ?? [];
+        const bad = routes.flatMap(r => procedureViolations(r).map(v => `route '${r.key}': ${v}`));
+        if (bad.length) {
+            throw new Error(`declared procedure hierarchy does not match the route steps:\n - ${bad.join('\n - ')}\n` +
+                'The steps are the source of truth for execution order; the hierarchy only names them. ' +
+                'A mismatch would show a tree on screen that the twin never executes.');
+        }
+    }
     assertRecipeOperationTags() {
         const def = this.productionSpec?.definition;
         if (!def?.recipes?.length)
@@ -458,9 +479,33 @@ export class MesKernel extends FlowEngine {
                 throw new Error(`recipe '${key}' is not declared. Declared: [${(d.recipes ?? []).map(r => r.key).join(', ') || '(none)'}]. ` +
                     `The kernel does not substitute another recipe — that would make this order produce a different item.`);
             }
+            /*
+             * **지목한 것은 유효 기간으로 거르지 않는다** (2026-08-31).
+             *
+             * 지난 실적을 뒤늦게 올릴 때 **그때 쓰던 레시피**를 가리켜야 한다. 그 레시피는 이미 끝난 것일 수
+             * 있고, 그것이 사실이다. 「지금 무엇을 쓸 수 있나」와 「그때 무엇을 썼나」는 다른 물음이다.
+             */
             return found;
         }
-        return d.recipes[0];
+        /*
+         * **지목이 없으면 지금 유효한 것 중에서 고른다** (2026-08-31).
+         *
+         * 예전에는 선언 순서의 첫 번째를 그대로 썼다. 그래서 첫 레시피가 개정으로 끝난 뒤에도 그것으로
+         * 만들었고, 그 산출이 무엇인지 계보에서 잃었다. 유효 기간이 계약에 열린 것은 이 판정을 하기 위한
+         * 것인데 읽는 쪽이 없었다.
+         *
+         * 여럿이 유효하면 첫 번째다 — 그 모호함은 예전부터 있었고 여기서 정할 일이 아니다(어느 것으로
+         * 만들지는 오더의 `recipeKey` 가 말한다). 하나도 유효하지 않으면 **던진다**: 끝난 레시피로 만드는
+         * 것이 멈추는 것보다 나쁘다.
+         */
+        const usable = (d.recipes ?? []).filter(r => !this.effectivityOf(r));
+        if (!usable.length) {
+            const when = (d.recipes ?? []).map(r => `${r.key}(${this.effectivityOf(r)})`).join(', ');
+            throw new Error(`no declared recipe is in effect now. Declared: [${when || '(none)'}]. ` +
+                `The kernel does not fall back to a retired recipe — that would make this order produce an item whose ` +
+                `bill of materials no longer holds. Name a recipe on the order, or extend the effective period.`);
+        }
+        return usable[0];
     }
     /** 자재 키 → 구체 gtin 클래스(idpat). 구체 식별은 바인딩+prefix 로 인스턴스가 주입. */
     /**

package/dist-cjs/index.cjs

@@ -1354,6 +1354,32 @@ var OP_PARAM = {
    *  현재 커널은 작업에 붙는 셋업으로 다루므로 모수로 받는다. */
   setupDuration: "setupDuration"
 };
+function procedureViolations(route) {
+  const elements = route.procedure ?? [];
+  if (!elements.length)
+    return [];
+  const errors = [];
+  const byKey = new Map(elements.map((e) => [e.key, e]));
+  const hasChild = new Set(elements.map((e) => e.parent).filter((k) => !!k));
+  const stepSet = new Set(route.steps ?? []);
+  const seenStep = /* @__PURE__ */ new Map();
+  for (const n of elements) {
+    if (n.parent && !byKey.has(n.parent))
+      errors.push(`${n.key}: \uC0C1\uC704 '${n.parent}' \uAC00 \uC774 \uC808\uCC28\uC5D0 \uC5C6\uB2E4`);
+    if (n.step === void 0)
+      continue;
+    if (hasChild.has(n.key))
+      errors.push(`${n.key}: \uC544\uB798 \uC694\uC18C\uAC00 \uC788\uB294\uB370 \uB2E8\uACC4\uB97C \uB4E0\uB2E4 \u2014 \uC2E4\uD589\uB418\uB294 \uAC83\uC740 \uC78E\uBFD0\uC774\uB2E4`);
+    if (!stepSet.has(n.step))
+      errors.push(`${n.key}: \uBAA8\uB974\uB294 \uB2E8\uACC4 '${n.step}' \u2014 steps \uC5D0 \uC5C6\uB2E4`);
+    const already = seenStep.get(n.step);
+    if (already)
+      errors.push(`\uB2E8\uACC4 '${n.step}' \uAC00 '${already}' \uC640 '${n.key}' \uB458\uC5D0 \uC2E4\uB838\uB2E4 \u2014 \uC808\uCC28 \uC5B4\uB514\uC778\uC9C0 \uB9D0\uD560 \uC218 \uC5C6\uB2E4`);
+    else
+      seenStep.set(n.step, n.key);
+  }
+  return errors;
+}
 
 // ../ops-contract/dist/energy-ingest.js
 function resolveSubject(kind, localId, opts) {
@@ -5999,7 +6025,7 @@ var FlowEngine = class {
         const n = this.locations.get(at);
         if (n) n.occupancy++;
       }
-      this.recordMaterialActual(t, gtin, "produced", qty, spec.uom);
+      this.recordMaterialActual(t, gtin, "produced", qty, spec.uom, gtin);
       this.emit(objectEvent({
         eventTime: this.now(),
         action: "ADD",
@@ -6077,12 +6103,12 @@ var FlowEngine = class {
    * 실제 자재 이동을 작업에 적어 둔다 — ISA-95 `JobResponse.MaterialActual`.
    * 같은 품목·같은 쓰임은 **한 줄로 합친다**(줄을 늘리면 실적을 세는 쪽이 중복을 걷어내야 한다).
    */
-  recordMaterialActual(t, definitionId, use, quantity, uom) {
+  recordMaterialActual(t, definitionId, use, quantity, uom, lotId) {
     if (!definitionId || !(quantity > 0)) return;
     const rows = t.materialActual ??= [];
-    const hit = rows.find((r) => r.definitionId === definitionId && r.use === use && r.uom === uom);
+    const hit = rows.find((r) => r.definitionId === definitionId && r.use === use && r.uom === uom && r.lotId === lotId);
     if (hit) hit.quantity += quantity;
-    else rows.push({ definitionId, use, quantity, ...uom ? { uom } : {} });
+    else rows.push({ definitionId, use, quantity, ...uom ? { uom } : {}, ...lotId ? { lotId } : {} });
   }
   /** 확보한 자재를 **작업 시작 시점에 소비**한다 — 수량이 0 이 되면 물품 자체가 사라진다. */
   consumeMaterials(t, taken) {
@@ -6094,7 +6120,7 @@ var FlowEngine = class {
       const left = (it.qty ?? 1) - take;
       if (left > 0) {
         it.qty = left;
-        this.recordMaterialActual(t, it.definitionId ?? it.gtin, "consumed", take, it.uom);
+        this.recordMaterialActual(t, it.definitionId ?? it.gtin, "consumed", take, it.uom, it.epc);
         this.emit(objectEvent({
           eventTime: this.now(),
           action: "OBSERVE",
@@ -6107,7 +6133,7 @@ var FlowEngine = class {
         }));
         continue;
       }
-      this.recordMaterialActual(t, it.definitionId ?? it.gtin, "consumed", take, it.uom);
+      this.recordMaterialActual(t, it.definitionId ?? it.gtin, "consumed", take, it.uom, it.epc);
       whole.push(epc);
     }
     if (!whole.length) return;
@@ -7228,6 +7254,7 @@ var MesKernel = class extends FlowEngine {
       this.assertNoDoubleProduction(productionSpec.definition.operations);
     }
     this.assertRecipeOperationTags();
+    this.assertRouteProcedures();
   }
   /**
    * **산출을 두 곳에서 만들지 않는다** — 기동 때 막는다.
@@ -7269,6 +7296,28 @@ var MesKernel = class extends FlowEngine {
    *
    * 런타임에 조용히 어긋나는 것보다 기동이 실패하는 편이 낫다.
    */
+  /**
+   * 라우트의 **절차 계층**이 단계와 어긋나지 않는가 (ISA-88).
+   *
+   * ── 왜 이제야 부르나 (2026-08-31) ─────────────────────────────────────────
+   * 계약이 `procedureViolations` 를 갖고 있었는데 **아무도 부르지 않았다** — 계약의 자기 시험만
+   * 불렀다. 그래서 절차를 선언해도 어긋난 것이 그냥 지나갔고, 화면은 잘못된 트리를 오류 없이 보였다.
+   *
+   * 선언을 읽는 곳이 있는지 보는 하네스가 이것을 잡았다(§`declaration-is-read.test.ts`).
+   *
+   * 판정은 계약이 한다 — 여기서 다시 만들면 규칙이 두 벌이 되고, 화면도 같은 판정을 해야 한다.
+   */
+  assertRouteProcedures() {
+    const routes = this.productionSpec?.definition?.routes ?? [];
+    const bad = routes.flatMap((r) => procedureViolations(r).map((v) => `route '${r.key}': ${v}`));
+    if (bad.length) {
+      throw new Error(
+        `declared procedure hierarchy does not match the route steps:
+ - ${bad.join("\n - ")}
+The steps are the source of truth for execution order; the hierarchy only names them. A mismatch would show a tree on screen that the twin never executes.`
+      );
+    }
+  }
   assertRecipeOperationTags() {
     const def = this.productionSpec?.definition;
     if (!def?.recipes?.length) return;
@@ -7564,7 +7613,14 @@ var MesKernel = class extends FlowEngine {
       }
       return found;
     }
-    return d.recipes[0];
+    const usable = (d.recipes ?? []).filter((r) => !this.effectivityOf(r));
+    if (!usable.length) {
+      const when = (d.recipes ?? []).map((r) => `${r.key}(${this.effectivityOf(r)})`).join(", ");
+      throw new Error(
+        `no declared recipe is in effect now. Declared: [${when || "(none)"}]. The kernel does not fall back to a retired recipe \u2014 that would make this order produce an item whose bill of materials no longer holds. Name a recipe on the order, or extend the effective period.`
+      );
+    }
+    return usable[0];
   }
   /** 자재 키 → 구체 gtin 클래스(idpat). 구체 식별은 바인딩+prefix 로 인스턴스가 주입. */
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operato/twin-kernel",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "type": "module",
   "description": "Twin Domain Kernel — framework-agnostic, zero-dep (domain + sim + 3-channel contract). WMS/YMS/MES, EPCIS 2.0 · ISA-95.",
   "publishConfig": {
@@ -28,6 +28,6 @@
     "test": "node --test test/*.test.ts"
   },
   "dependencies": {
-    "@operato/ops-contract": "^0.8.0"
+    "@operato/ops-contract": "^0.9.0"
   }
 }