@operato/twin-kernel 0.11.20 → 0.11.22

package/dist/flow-engine.d.ts

@@ -1,4 +1,4 @@
-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, DispositionFact, AllocatedQuantity, MaterialLotUse } from '@operato/ops-contract';
+import type { MaterialActual, RecipeExecutionBasis, 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, DispositionFact, AllocatedQuantity, MaterialLotUse } from '@operato/ops-contract';
 import { type RatedUsage, type UsedUsage } from '@operato/ops-contract';
 import type { VocabularyElement } from '@operato/ops-contract';
 import type { ReducerCheckpoint } from './observed-reducer.ts';
@@ -271,6 +271,7 @@ export declare function allocatedQty(rows: readonly AllocatedQuantity[] | undefi
 /** 잡아 둔 줄들의 식별자 — EPCIS 이벤트가 싣는 것은 열쇠뿐이다. */
 export declare function allocatedEpcs(rows: readonly AllocatedQuantity[] | undefined): string[];
 export interface FlowOrder {
+    recipeBasis?: RecipeExecutionBasis;
     id: string;
     kind: string;
     status: string;

package/dist/flow-engine.js

@@ -1241,6 +1241,7 @@ export class FlowEngine {
                 ...(o.allocated?.length ? { allocated: o.allocated } : {}),
                 ...(o.gtin ? { gtin: o.gtin } : {}),
                 ...(o.recipeKey ? { recipeKey: o.recipeKey } : {}),
+                ...(o.recipeBasis ? { recipeBasis: structuredClone(o.recipeBasis) } : {}),
                 ...(o.bizTransaction ? { bizTransaction: o.bizTransaction } : {}),
                 ...(o.dockDoor ? { dockDoor: o.dockDoor } : {}),
                 ...(o.windowStartMs !== undefined ? { windowStartMs: o.windowStartMs } : {})
@@ -1303,6 +1304,7 @@ export class FlowEngine {
                 /* 레시피도 함께 — 품목만 이어받으면 되살아난 오더가 「무엇으로」를 모르고, 그 오더의
                    남은 공정·소요가 다른 레시피 기준으로 계산된다(같은 품목에 대체 레시피가 있다). */
                 ...(o.recipeKey ? { recipeKey: o.recipeKey } : {}),
+                ...(o.recipeBasis ? { recipeBasis: structuredClone(o.recipeBasis) } : {}),
                 bizTransaction: o.bizTransaction ?? '', allocated: resolved.kept, picked: [], shipmentEpc: null,
                 /* 라인도 같다 — 씨앗은 남은 양만 남기고, 미러는 원본이 말한 요청·이행을 그대로 든다. */
                 lines: observing ? (o.lines ?? []).map(l => ({ ...l })) : lines,
@@ -1820,6 +1822,7 @@ export class FlowEngine {
                 ...(o.gtin ? { gtin: o.gtin } : {}),
                 /* **어느 레시피로 만드나** — 품목만으로는 「무엇으로」가 안 남는다(같은 품목의 대체 레시피가 있다). */
                 ...(o.recipeKey ? { recipeKey: o.recipeKey } : {}),
+                ...(o.recipeBasis ? { recipeBasis: structuredClone(o.recipeBasis) } : {}),
                 /* 씨앗이 다 심지 못했다는 사실 — 조용히 자르지 않는다(그 오더의 답은 부족한 씨앗 위에 있다). */
                 ...(o.seedIncomplete ? { seedIncomplete: true } : {}),
                 /* 왜 대기하는지 — 없으면 화면은 「running」만 보여 주고 사람은 원인을 찾을 자리가 없다. */
@@ -2989,6 +2992,7 @@ export class FlowEngine {
             /* 어느 레시피로 만드는가 — 품목만 보내면 미러는 「무엇으로」를 알 수 없다(같은 품목에 대체
                레시피가 있다). 시뮬만 아는 사실이 남으면 두 스냅샷을 같은 규칙으로 읽을 수 없다. */
             ...(o.recipeKey ? { recipeKey: o.recipeKey } : {}),
+            ...(o.recipeBasis ? { recipeBasis: structuredClone(o.recipeBasis) } : {}),
             ...(o.allocated?.length ? { allocated: o.allocated.slice() } : {}),
             ...(o.bizTransaction ? { bizTransaction: o.bizTransaction } : {}),
             /* 약속해 둔 자리·시각창 — 이것이 빠져서 야드 트윈이 재기동마다 첫 틱에 죽었다(§dockDoor). */

package/dist/mes-kernel.js

@@ -8,7 +8,7 @@
  *  ③ 셋업/체인지오버 = work-center 가 제품 전환 시 셋업(changeoverKey=제품 gtin) → OEE Availability.
  *  ④ OEE = base 가 설비(설비)별 계측(가동/셋업/기아/품질). cut=cutter·weld=welder 이종 자원.
  */
-import { identityGroundingOf, procedureViolations } from '@operato/ops-contract';
+import { identityGroundingOf, procedureViolations, isRecipeExecutionBasis } from '@operato/ops-contract';
 import { firstFitPolicy } from "./allocation-policy.js";
 import { FlowEngine, allocatedEpcs, allocatedQty } from "./flow-engine.js";
 import { DISP, objectEvent, transactionEvent, gdtiUri, sgtinClass, bizTransactionUri } from '@operato/ops-contract';
@@ -472,6 +472,11 @@ export class MesKernel extends FlowEngine {
      * 그 뒤 계보·재고·수율이 전부 엉뚱한 품목에 붙는다.
      */
     recipeDef(order) {
+        if (order?.recipeBasis !== undefined) {
+            if (!isRecipeExecutionBasis(order.recipeBasis) || (order.recipeKey && order.recipeKey !== order.recipeBasis.recipe.key))
+                throw new Error('Invalid pinned recipe evidence; refusing to substitute the current master.');
+            return order.recipeBasis.recipe;
+        }
         const d = this.productionSpec.definition;
         const key = order?.recipeKey ?? this.productionSpec.recipeKey;
         if (key) {
@@ -658,7 +663,10 @@ export class MesKernel extends FlowEngine {
     /** recipe.route → 오퍼레이션 시퀀스 해소. 오더가 자기 레시피를 들면 그 라우트다. */
     routeOps(order) {
         const d = this.productionSpec.definition;
-        const route = d.routes?.find(r => r.key === this.recipeDef(order).route);
+        const recipe = this.recipeDef(order);
+        const route = order?.recipeBasis ? order.recipeBasis.route : d.routes?.find(r => r.key === recipe.route);
+        if (order?.recipeBasis && route?.steps.some(key => !d.operations?.some(operation => operation.key === key)))
+            throw new Error('A captured recipe route references an unavailable operation; refusing a shortened route.');
         return (route?.steps ?? []).map(sk => d.operations?.find(o => o.key === sk)).filter((o) => !!o);
     }
     /** 정의 모드 수령 — skuMix gtin 이 레시피 입력 자재면 **그 자재가 선언한 자리**에 생성. */

package/dist/observed-reducer.js

@@ -722,6 +722,7 @@ export class ObservedReducer {
                     ...(d.gtin ? { gtin: d.gtin } : {}),
                     /* 어느 레시피로 만드는가 — 품목만으로는 「무엇으로」가 남지 않는다(같은 품목에 대체 레시피). */
                     ...(d.recipeKey ? { recipeKey: d.recipeKey } : {}),
+                    ...(d.recipeBasis ? { recipeBasis: structuredClone(d.recipeBasis) } : {}),
                     ...(d.allocated?.length ? { allocated: d.allocated.slice() } : {}),
                     ...(d.bizTransaction ? { bizTransaction: d.bizTransaction } : {}),
                     /* 이행하는 계획 — 「이 계획이 얼마나 됐나」를 이 값으로 묶어 답한다(§`OrderState.operationsRequestId`). */

package/dist-cjs/index.cjs

@@ -328,8 +328,36 @@ function outsideLimit(criterion, observed) {
     return true;
   return false;
 }
+function isTestSpecificationBasis(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return false;
+  const basis = value;
+  if (!["id", "revisionId", "planId", "contentHash", "businessTime"].every((key) => typeof basis[key] === "string" && basis[key].trim()))
+    return false;
+  if (!Number.isFinite(Date.parse(basis.businessTime)))
+    return false;
+  return Array.isArray(basis.criteria) && basis.criteria.every((c) => {
+    if (!c || typeof c !== "object" || Array.isArray(c) || typeof c.id !== "string" || !c.id.trim())
+      return false;
+    if (["description", "expression", "evaluatedPropertyId"].some((key) => c[key] !== void 0 && typeof c[key] !== "string"))
+      return false;
+    if (c.limit === void 0)
+      return true;
+    const limit = c.limit;
+    if (!limit || typeof limit !== "object" || Array.isArray(limit))
+      return false;
+    if (["minimum", "maximum"].some((key) => limit[key] !== void 0 && (typeof limit[key] !== "number" || !Number.isFinite(limit[key]))))
+      return false;
+    if (limit.uom !== void 0 && typeof limit.uom !== "string")
+      return false;
+    return !(limit.minimum !== void 0 && limit.maximum !== void 0 && limit.minimum > limit.maximum);
+  });
+}
 function judgeAgainstSpec(spec, result) {
-  const criteria = (spec?.criteria ?? []).filter((c) => !criterionSaysNothing(c));
+  const basis = result?.specificationBasis;
+  if (basis !== void 0 && !isTestSpecificationBasis(basis))
+    return void 0;
+  const criteria = (basis ? basis.criteria : spec?.criteria ?? []).filter((c) => !criterionSaysNothing(c));
   if (!criteria.length)
     return void 0;
   const measurements = result?.propertyMeasurements ?? [];
@@ -607,6 +635,14 @@ function capabilityOf(r, ctx) {
     return { available: false, reason: "working" };
   return { available: true, reason: "available" };
 }
+function isRecipeExecutionBasis(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const v = value;
+  const text = (x) => typeof x === "string" && x.trim().length > 0;
+  const lines = (x) => Array.isArray(x) && x.length > 0 && x.every((row) => row && text(row.material) && typeof row.qty === "number" && Number.isFinite(row.qty) && row.qty > 0 && (row.operation === void 0 || text(row.operation)));
+  return [v.basisId, v.recipeId, v.revisionId, v.planId, v.contentHash, v.businessTime].every(text) && /(?:Z|[+-]\d{2}:\d{2})$/.test(v.businessTime) && Number.isFinite(Date.parse(v.businessTime)) && !!v.recipe && text(v.recipe.key) && text(v.recipe.label) && lines(v.recipe.inputs) && lines(v.recipe.outputs) && (v.recipe.route === void 0 ? v.route === void 0 && v.recipe.inputs.every((line) => !line.operation) : text(v.recipe.route) && !!v.route && v.route.key === v.recipe.route && Array.isArray(v.route.steps) && v.route.steps.every(text) && v.recipe.inputs.every((line) => !line.operation || v.route.steps.includes(line.operation)));
+}
 var OP_EVENT = {
   task: "task.status",
   equipment: "equipment.status",
@@ -1986,13 +2022,19 @@ var SPECS = {
        *
        * 새 어휘가 아니다 — 계약이 `recipeKey` 를 네 자리에서 이미 쓴다. 오더 관측에만 자리가 없었다.
        */
-      recipeKey: "string"
+      recipeKey: "string",
+      recipeBasis: "object"
     },
     /*
      * 확보분의 안쪽을 본다 — 열쇠와 수 둘이다(§`AllocatedQuantity`). 안 보면 틀린 이름이 조용히
      * 지나가고(`epcs`·`quantity` 따위), 미러는 잡힌 수를 0 으로 읽는다.
      */
     shapes: {
+      recipeBasis: {
+        required: ["basisId", "recipeId", "revisionId", "planId", "contentHash", "businessTime", "recipe"],
+        fields: { basisId: "string", recipeId: "string", revisionId: "string", planId: "string", contentHash: "string", businessTime: "string" }
+        // Owned composition and captured route are additionally checked by isRecipeExecutionBasis below.
+      },
       allocated: {
         required: ["epc", "qty"],
         fields: { epc: "string", qty: "number" },
@@ -2156,8 +2198,15 @@ var SPECS = {
       expiresAt: "string",
       derived: "boolean",
       propertyMeasurements: "object[]",
+      specificationBasis: "object",
       recordTime: "string"
     },
+    shapes: {
+      specificationBasis: {
+        required: ["id", "revisionId", "planId", "contentHash", "businessTime", "criteria"],
+        fields: { id: "string", revisionId: "string", planId: "string", contentHash: "string", businessTime: "string" }
+      }
+    },
     enums: { result: ["pass", "fail"] }
   },
   /*
@@ -3062,6 +3111,7 @@ var ObservedReducer = class {
           ...d.gtin ? { gtin: d.gtin } : {},
           /* 어느 레시피로 만드는가 — 품목만으로는 「무엇으로」가 남지 않는다(같은 품목에 대체 레시피). */
           ...d.recipeKey ? { recipeKey: d.recipeKey } : {},
+          ...d.recipeBasis ? { recipeBasis: structuredClone(d.recipeBasis) } : {},
           ...d.allocated?.length ? { allocated: d.allocated.slice() } : {},
           ...d.bizTransaction ? { bizTransaction: d.bizTransaction } : {},
           /* 이행하는 계획 — 「이 계획이 얼마나 됐나」를 이 값으로 묶어 답한다(§`OrderState.operationsRequestId`). */
@@ -4637,6 +4687,7 @@ var FlowEngine = class {
       ...o.allocated?.length ? { allocated: o.allocated } : {},
       ...o.gtin ? { gtin: o.gtin } : {},
       ...o.recipeKey ? { recipeKey: o.recipeKey } : {},
+      ...o.recipeBasis ? { recipeBasis: structuredClone(o.recipeBasis) } : {},
       ...o.bizTransaction ? { bizTransaction: o.bizTransaction } : {},
       ...o.dockDoor ? { dockDoor: o.dockDoor } : {},
       ...o.windowStartMs !== void 0 ? { windowStartMs: o.windowStartMs } : {}
@@ -4661,6 +4712,7 @@ var FlowEngine = class {
         /* 레시피도 함께 — 품목만 이어받으면 되살아난 오더가 「무엇으로」를 모르고, 그 오더의
            남은 공정·소요가 다른 레시피 기준으로 계산된다(같은 품목에 대체 레시피가 있다). */
         ...o.recipeKey ? { recipeKey: o.recipeKey } : {},
+        ...o.recipeBasis ? { recipeBasis: structuredClone(o.recipeBasis) } : {},
         bizTransaction: o.bizTransaction ?? "",
         allocated: resolved.kept,
         picked: [],
@@ -5094,6 +5146,7 @@ var FlowEngine = class {
         ...o.gtin ? { gtin: o.gtin } : {},
         /* **어느 레시피로 만드나** — 품목만으로는 「무엇으로」가 안 남는다(같은 품목의 대체 레시피가 있다). */
         ...o.recipeKey ? { recipeKey: o.recipeKey } : {},
+        ...o.recipeBasis ? { recipeBasis: structuredClone(o.recipeBasis) } : {},
         /* 씨앗이 다 심지 못했다는 사실 — 조용히 자르지 않는다(그 오더의 답은 부족한 씨앗 위에 있다). */
         ...o.seedIncomplete ? { seedIncomplete: true } : {},
         /* 왜 대기하는지 — 없으면 화면은 「running」만 보여 주고 사람은 원인을 찾을 자리가 없다. */
@@ -6128,6 +6181,7 @@ var FlowEngine = class {
       /* 어느 레시피로 만드는가 — 품목만 보내면 미러는 「무엇으로」를 알 수 없다(같은 품목에 대체
          레시피가 있다). 시뮬만 아는 사실이 남으면 두 스냅샷을 같은 규칙으로 읽을 수 없다. */
       ...o.recipeKey ? { recipeKey: o.recipeKey } : {},
+      ...o.recipeBasis ? { recipeBasis: structuredClone(o.recipeBasis) } : {},
       ...o.allocated?.length ? { allocated: o.allocated.slice() } : {},
       ...o.bizTransaction ? { bizTransaction: o.bizTransaction } : {},
       /* 약속해 둔 자리·시각창 — 이것이 빠져서 야드 트윈이 재기동마다 첫 틱에 죽었다(§dockDoor). */
@@ -8039,6 +8093,11 @@ The steps are the source of truth for execution order; the hierarchy only names
    * 그 뒤 계보·재고·수율이 전부 엉뚱한 품목에 붙는다.
    */
   recipeDef(order) {
+    if (order?.recipeBasis !== void 0) {
+      if (!isRecipeExecutionBasis(order.recipeBasis) || order.recipeKey && order.recipeKey !== order.recipeBasis.recipe.key)
+        throw new Error("Invalid pinned recipe evidence; refusing to substitute the current master.");
+      return order.recipeBasis.recipe;
+    }
     const d = this.productionSpec.definition;
     const key = order?.recipeKey ?? this.productionSpec.recipeKey;
     if (key) {
@@ -8201,7 +8260,10 @@ The steps are the source of truth for execution order; the hierarchy only names
   /** recipe.route → 오퍼레이션 시퀀스 해소. 오더가 자기 레시피를 들면 그 라우트다. */
   routeOps(order) {
     const d = this.productionSpec.definition;
-    const route = d.routes?.find((r) => r.key === this.recipeDef(order).route);
+    const recipe = this.recipeDef(order);
+    const route = order?.recipeBasis ? order.recipeBasis.route : d.routes?.find((r) => r.key === recipe.route);
+    if (order?.recipeBasis && route?.steps.some((key) => !d.operations?.some((operation) => operation.key === key)))
+      throw new Error("A captured recipe route references an unavailable operation; refusing a shortened route.");
     return (route?.steps ?? []).map((sk) => d.operations?.find((o) => o.key === sk)).filter((o) => !!o);
   }
   /** 정의 모드 수령 — skuMix gtin 이 레시피 입력 자재면 **그 자재가 선언한 자리**에 생성. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operato/twin-kernel",
-  "version": "0.11.20",
+  "version": "0.11.22",
   "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.9.30"
+    "@operato/ops-contract": "^0.9.32"
   }
 }