@operato/twin-kernel 0.11.22 → 0.11.23

package/dist/flow-engine.d.ts

@@ -1,4 +1,4 @@
-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 { MaterialActual, RecipeExecutionBasis, MaterialExecutionBasis, 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';
@@ -197,6 +197,7 @@ export interface FlowTask {
      * 채널에 실어야 실적을 **한 곳에서** 읽는다(EPCIS 이벤트에서 다시 계산하려면 작업과 잇는 끈이 없다).
      */
     materialActual?: MaterialActual[];
+    workShiftBasis?: import('@operato/ops-contract').WorkShiftExecutionBasis;
     itemEpc: string;
     fromNode: string;
     toNode: string;
@@ -271,6 +272,7 @@ export declare function allocatedQty(rows: readonly AllocatedQuantity[] | undefi
 /** 잡아 둔 줄들의 식별자 — EPCIS 이벤트가 싣는 것은 열쇠뿐이다. */
 export declare function allocatedEpcs(rows: readonly AllocatedQuantity[] | undefined): string[];
 export interface FlowOrder {
+    materialBasis?: MaterialExecutionBasis[];
     recipeBasis?: RecipeExecutionBasis;
     id: string;
     kind: string;

package/dist/flow-engine.js

@@ -9,6 +9,7 @@
  * 통합 타입은 도메인 필드를 옵셔널로 넓혀(FlowItem.gtin?, FlowOrder.shipmentEpc? 등) 두 도메인을 담는다.
  * (roadmap Phase5 발견 → 추출. [[project_flow_single_base_vision]] FlowLocation 단일 base 방향과 정합.)
  */
+import { isWorkShiftExecutionBasis } from '@operato/ops-contract';
 import { OP_EVENT, CMD, USE_UOM, locationStatusOf, readBoardEquipment, equipmentClassMembership, readBoardLocations, readBoardAssets, classClosure, capabilityOf, requiredTestsFor, priorityRank, dueStatusOf, isOrderTerminal, effectivityAt, offCalendarAt, offCalendarReasonAt, minuteOfDayAt, activeShiftAt, subLotIdOf, itemKeyOf, identityGroundingOf, outsideLimit, computeOee } from '@operato/ops-contract';
 import { ObservedReducer } from "./observed-reducer.js";
 /* 주체를 정하는 규칙은 유입 문과 한 벌이다 — 두 곳에 적으면 한쪽만 고쳐진다. */
@@ -1050,6 +1051,10 @@ export class FlowEngine {
      * 그래서 규칙을 둘로 쪼개지 않고 **목적을 밝힌다.** 같은 함수, 같은 주입 경로, 다른 판정 하나다.
      */
     purpose = 'seed') {
+        for (const task of snap.tasks ?? []) {
+            if (task.workShiftBasis !== undefined && !isWorkShiftExecutionBasis(task.workShiftBasis))
+                throw new Error('Invalid pinned work shift evidence');
+        }
         /* 확인 처리를 먼저 이어받는다 — 아래에서 상태를 주입하면 곧바로 주목 신호가 계산되므로, 늦게
          * 이어받으면 그 한 번은 확인 안 된 것으로 계산된다(화면이 잠깐 빨개진다). */
         for (const id of snap.acked ?? [])
@@ -1242,6 +1247,7 @@ export class FlowEngine {
                 ...(o.gtin ? { gtin: o.gtin } : {}),
                 ...(o.recipeKey ? { recipeKey: o.recipeKey } : {}),
                 ...(o.recipeBasis ? { recipeBasis: structuredClone(o.recipeBasis) } : {}),
+                ...(o.materialBasis ? { materialBasis: structuredClone(o.materialBasis) } : {}),
                 ...(o.bizTransaction ? { bizTransaction: o.bizTransaction } : {}),
                 ...(o.dockDoor ? { dockDoor: o.dockDoor } : {}),
                 ...(o.windowStartMs !== undefined ? { windowStartMs: o.windowStartMs } : {})
@@ -1305,6 +1311,7 @@ export class FlowEngine {
                    남은 공정·소요가 다른 레시피 기준으로 계산된다(같은 품목에 대체 레시피가 있다). */
                 ...(o.recipeKey ? { recipeKey: o.recipeKey } : {}),
                 ...(o.recipeBasis ? { recipeBasis: structuredClone(o.recipeBasis) } : {}),
+                ...(o.materialBasis ? { materialBasis: structuredClone(o.materialBasis) } : {}),
                 bizTransaction: o.bizTransaction ?? '', allocated: resolved.kept, picked: [], shipmentEpc: null,
                 /* 라인도 같다 — 씨앗은 남은 양만 남기고, 미러는 원본이 말한 요청·이행을 그대로 든다. */
                 lines: observing ? (o.lines ?? []).map(l => ({ ...l })) : lines,
@@ -1368,6 +1375,7 @@ export class FlowEngine {
                 status: purpose === 'observe' ? t.status : known && t.status === 'in-progress' ? 'in-progress' : 'created',
                 /* 이미 일어난 자재 이동은 **씨앗에도 남는다** — 잃으면 실적이 재기동마다 지워진다. */
                 ...(t.materialActual?.length ? { materialActual: t.materialActual.map(r => ({ ...r })) } : {}),
+                ...(t.workShiftBasis ? { workShiftBasis: structuredClone(t.workShiftBasis) } : {}),
                 itemEpc: t.itemRefs?.[0] ?? '',
                 fromNode: t.fromNode ?? '', toNode: t.toNode ?? '',
                 /*
@@ -1802,6 +1810,7 @@ export class FlowEngine {
                 ...(t.assets?.length ? { assets: t.assets.slice() } : {}),
                 ...(t.resources?.length ? { resources: t.resources.slice() } : {}),
                 ...(t.materialActual?.length ? { materialActual: t.materialActual.map(r => ({ ...r })) } : {}),
+                ...(t.workShiftBasis ? { workShiftBasis: structuredClone(t.workShiftBasis) } : {}),
                 ...(t.priority !== undefined ? { priority: t.priority } : {}),
                 ...(t.startTime ? { startTime: t.startTime } : {}),
                 ...(t.endTime ? { endTime: t.endTime } : {})
@@ -1823,6 +1832,7 @@ export class FlowEngine {
                 /* **어느 레시피로 만드나** — 품목만으로는 「무엇으로」가 안 남는다(같은 품목의 대체 레시피가 있다). */
                 ...(o.recipeKey ? { recipeKey: o.recipeKey } : {}),
                 ...(o.recipeBasis ? { recipeBasis: structuredClone(o.recipeBasis) } : {}),
+                ...(o.materialBasis ? { materialBasis: structuredClone(o.materialBasis) } : {}),
                 /* 씨앗이 다 심지 못했다는 사실 — 조용히 자르지 않는다(그 오더의 답은 부족한 씨앗 위에 있다). */
                 ...(o.seedIncomplete ? { seedIncomplete: true } : {}),
                 /* 왜 대기하는지 — 없으면 화면은 「running」만 보여 주고 사람은 원인을 찾을 자리가 없다. */
@@ -2954,6 +2964,7 @@ export class FlowEngine {
             ...(t.resources?.length ? { resources: t.resources.slice() } : {}),
             /* 실제 자재 이동 — 인원·설비와 같은 채널(실적을 한 곳에서 읽는다). */
             ...(t.materialActual?.length ? { materialActual: t.materialActual.map(r => ({ ...r })) } : {}),
+            ...(t.workShiftBasis ? { workShiftBasis: structuredClone(t.workShiftBasis) } : {}),
             ...(t.durationMs ? { durationMs: t.durationMs } : {}),
             /* 품질 판정이 있었으면 **그 자리에서** 실어 보낸다 — 없으면 필드를 만들지 않는다(모름≠양품). */
             ...(t.outcome ? { outcome: t.outcome } : {}),
@@ -2993,6 +3004,7 @@ export class FlowEngine {
                레시피가 있다). 시뮬만 아는 사실이 남으면 두 스냅샷을 같은 규칙으로 읽을 수 없다. */
             ...(o.recipeKey ? { recipeKey: o.recipeKey } : {}),
             ...(o.recipeBasis ? { recipeBasis: structuredClone(o.recipeBasis) } : {}),
+            ...(o.materialBasis ? { materialBasis: structuredClone(o.materialBasis) } : {}),
             ...(o.allocated?.length ? { allocated: o.allocated.slice() } : {}),
             ...(o.bizTransaction ? { bizTransaction: o.bizTransaction } : {}),
             /* 약속해 둔 자리·시각창 — 이것이 빠져서 야드 트윈이 재기동마다 첫 틱에 죽었다(§dockDoor). */
@@ -3197,7 +3209,7 @@ export class FlowEngine {
             for (const it of this.items.at(at)) {
                 if (remaining <= 0)
                     break;
-                if (!this.materialMatches(it, req))
+                if (!this.materialMatches(it, req, t.orderId))
                     continue;
                 /*
                  * 변환 중인 것은 잡지 않는다 — 어떤 공정이 이미 먹어 그 단계의 산출로 바뀔 물품이다
@@ -3221,12 +3233,13 @@ export class FlowEngine {
         return picked;
     }
     /** 이 물품이 명세를 만족하나 — 품목 지목이 우선, 없으면 등급(상속을 타고 닫는다). */
-    materialMatches(it, req) {
+    materialMatches(it, req, orderId) {
         const defId = it.definitionId ?? it.gtin;
         if (req.materialDefinition)
             return defId === req.materialDefinition;
         if (req.materialClass) {
-            const def = defId ? this.materialDefs.get(defId) : undefined;
+            const basis = orderId ? this.orders.get(orderId)?.materialBasis : undefined;
+            const def = basis !== undefined ? basis.find(b => b.material.id === defId)?.material : defId ? this.materialDefs.get(defId) : undefined;
             return classClosure(def?.materialClassIds, this.classDefs.material, this.now()).has(req.materialClass);
         }
         return true; // 지목도 등급도 없으면 아무 자재나(명세가 그렇게 느슨하면 그대로 따른다)

package/dist/observed-reducer.js

@@ -19,7 +19,7 @@
  *  - 운영 델타(task/equipment/order.status) → tasks·equipment·orders (EPCIS 로 재구성 불가한 절반)
  * 마스터(로케이션)는 board 초기화 + applyMaster 로 갱신(마스터 동기).
  */
-import { computeOee } from '@operato/ops-contract';
+import { computeOee, isWorkShiftExecutionBasis } from '@operato/ops-contract';
 import { OP_EVENT, capabilityOf, itemKeyOf, judgeAgainstSpec, requiredTestsFor, locationStatusOf, readBoardEquipment, readBoardLocations, readBoardAssets, effectivityAt, offCalendarAt, offCalendarReasonAt, activeShiftAt } from '@operato/ops-contract';
 import { ILMD_ATTR, parseEpc } from '@operato/ops-contract';
 import { expiryFromAttributes, lotFromAttributes } from '@operato/ops-contract';
@@ -345,6 +345,8 @@ export class ObservedReducer {
         switch (e.eventType) {
             case OP_EVENT.task: {
                 const d = e.data;
+                if (d.workShiftBasis !== undefined && !isWorkShiftExecutionBasis(d.workShiftBasis))
+                    throw new Error('Invalid pinned work shift evidence');
                 if (this.stale(`task:${d.taskId}`, e))
                     return;
                 /* 커널이 실어 보낸 것을 그대로 담는다 — 진척·남은 시간·의도가 있어야 이 상태를 씨앗으로
@@ -387,6 +389,7 @@ export class ObservedReducer {
                     ...(d.resources?.length ? { resources: d.resources.slice() } : {}),
                     /* 실제 자재 이동 — 인원·설비와 같은 채널로 온다(실적을 한 곳에서 읽는다).
                        말하지 않았으면 **앞의 것을 지킨다**(위 주석) — 빈 배열은 「지웠다」로 말한 것이다. */
+                    ...(d.workShiftBasis ? { workShiftBasis: structuredClone(d.workShiftBasis) } : prevTask?.workShiftBasis ? { workShiftBasis: structuredClone(prevTask.workShiftBasis) } : {}),
                     ...(d.materialActual?.length
                         ? { materialActual: d.materialActual.map(r => ({ ...r })) }
                         : keptActual?.length
@@ -509,6 +512,8 @@ export class ObservedReducer {
                  * **지금 상태를 바꾸지 않는다.** 어제의 구간이 오늘의 상태가 되면 안 된다.
                  */
                 const d = e.data;
+                if (d.workShiftBasis !== undefined && !isWorkShiftExecutionBasis(d.workShiftBasis))
+                    throw new Error('Invalid pinned work shift evidence');
                 if (!d?.moverId || !d?.from || !d?.to)
                     break;
                 const from = Date.parse(d.from);
@@ -723,6 +728,7 @@ export class ObservedReducer {
                     /* 어느 레시피로 만드는가 — 품목만으로는 「무엇으로」가 남지 않는다(같은 품목에 대체 레시피). */
                     ...(d.recipeKey ? { recipeKey: d.recipeKey } : {}),
                     ...(d.recipeBasis ? { recipeBasis: structuredClone(d.recipeBasis) } : {}),
+                    ...(d.materialBasis ? { materialBasis: structuredClone(d.materialBasis) } : {}),
                     ...(d.allocated?.length ? { allocated: d.allocated.slice() } : {}),
                     ...(d.bizTransaction ? { bizTransaction: d.bizTransaction } : {}),
                     /* 이행하는 계획 — 「이 계획이 얼마나 됐나」를 이 값으로 묶어 답한다(§`OrderState.operationsRequestId`). */
@@ -1321,7 +1327,7 @@ export class ObservedReducer {
             /* 수량으로 담긴 것도 이어받는다 — 되풀어 주지 않는 축이다(원천은 담김을 다시 말해 주지 않는다). */
             qtyAggregation: [...this.qtyAggregation.entries()].map(([parent, quantities]) => ({ parent, quantities })),
             pendingQuantities: [...this.pendingQuantities.entries()].map(([parent, quantities]) => ({ parent, quantities })),
-            tasks: [...this.tasks.values()].map(t => ({ ...t })),
+            tasks: [...this.tasks.values()].map(t => structuredClone(t)),
             equipment: [...this.equipment.values()].map(m => ({ ...m })),
             persons: [...this.persons.values()].map(x => ({ ...x })),
             assets: [...this.assets.values()].map(x => ({ ...x })),
@@ -1349,6 +1355,10 @@ export class ObservedReducer {
      * 모델에서 오는 판정 입력(교대·등급·시간대)은 생성자가 이미 세웠으므로 건드리지 않는다.
      */
     restore(cp) {
+        for (const task of cp?.tasks ?? []) {
+            if (task.workShiftBasis !== undefined && !isWorkShiftExecutionBasis(task.workShiftBasis))
+                throw new Error('Invalid pinned work shift evidence');
+        }
         this.observations = new Map((cp?.observations ?? []).map(o => [o.id, new Map((o.values ?? []).map(v => [v.propertyId, { ...v }]))]));
         this.revision = cp?.revision ?? 0;
         this.master = new Map((cp?.master ?? []).map(n => [n.id, { ...n }]));
@@ -1359,7 +1369,7 @@ export class ObservedReducer {
         this.pendingParent = new Map((cp?.pendingParent ?? []).map(x => [x.child, x.parent]));
         this.qtyAggregation = new Map((cp?.qtyAggregation ?? []).map(x => [x.parent, x.quantities]));
         this.pendingQuantities = new Map((cp?.pendingQuantities ?? []).map(x => [x.parent, x.quantities]));
-        this.tasks = new Map((cp?.tasks ?? []).map(t => [t.id, { ...t }]));
+        this.tasks = new Map((cp?.tasks ?? []).map(t => [t.id, structuredClone(t)]));
         this.equipment = new Map((cp?.equipment ?? []).map(m => [m.id, { ...m }]));
         this.oeeCounters = new Map((cp?.oeeCounters ?? []).map((c) => [String(c.id), { ...emptyOeeCounters(), ...c, id: undefined }]));
         this.persons = new Map((cp?.persons ?? []).map(x => [x.id, { ...x }]));
@@ -1412,7 +1422,7 @@ export class ObservedReducer {
                만료는 이벤트 없이 시각만으로 일어나므로, 델타로 받아 두면 유휴 자원이 영원히 유효하게 남는다. */
             persons: [...this.persons.values()].map(p => ({ ...p, ...this.effectivityPart(p), ...this.offShiftPart(`person:${p.id}`), ...this.capabilityPart(p, `person:${p.id}`, p.personnelClassIds, this.classDefs.personnel) })),
             assets: [...this.assets.values()].map(a => ({ ...a, ...this.effectivityPart(a), ...this.capabilityPart(a, `asset:${a.id}`, a.assetClassIds, this.classDefs.asset) })),
-            tasks: [...this.tasks.values()].map(t => ({ ...t })),
+            tasks: [...this.tasks.values()].map(t => structuredClone(t)),
             equipment: [...this.equipment.values()].map(m => ({ ...m, ...this.oeePart(m.id), ...this.effectivityPart(m), ...this.offShiftPart(`eq:${m.id}`), ...this.capabilityPart(m, `eq:${m.id}`, m.kind ? [m.kind] : [], this.classDefs.equipment) })),
             orders: [...this.orders.values()].map(o => ({ ...o })),
             acked: [...this.acked]

package/dist-cjs/index.cjs

@@ -1846,6 +1846,43 @@ function readEpochMs(raw) {
   return Number.isNaN(at) ? void 0 : at;
 }
 
+// ../ops-contract/dist/work-shift-basis.js
+var instant = (value) => typeof value === "string" && /(?:Z|[+-]\d{2}:\d{2})$/.test(value) && Number.isFinite(Date.parse(value));
+var nonempty = (value) => typeof value === "string" && !!value.trim();
+var clock = (value) => typeof value === "string" && /^(?:[01]\d|2[0-3]):[0-5]\d$/.test(value);
+function isWorkShiftExecutionBasis(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return false;
+  const b = value;
+  if (![b.basisId, b.arrangementId, b.revisionId, b.planId, b.contentHash].every(nonempty) || !Number.isSafeInteger(b.revisionNumber) || b.revisionNumber < 1 || !instant(b.businessTime) || !nonempty(b.timezone))
+    return false;
+  try {
+    new Intl.DateTimeFormat("en", { timeZone: b.timezone }).format(0);
+  } catch {
+    return false;
+  }
+  if (typeof b.workDate !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(b.workDate) || !Number.isFinite(Date.parse(b.workDate)) || new Date(b.workDate).toISOString().slice(0, 10) !== b.workDate)
+    return false;
+  if (!Array.isArray(b.shifts) || !b.shifts.length || b.shifts.length > 64)
+    return false;
+  const names = /* @__PURE__ */ new Set();
+  for (const s of b.shifts) {
+    if (!s || typeof s !== "object" || !nonempty(s.name) || names.has(s.name) || s.description !== void 0 && typeof s.description !== "string" || ![-1, 0, 1].includes(s.fromDate) || ![-1, 0, 1].includes(s.toDate) || !clock(s.fromTime) || !clock(s.toTime) || typeof s.daysOfWeek !== "string" || !/^(?:[0-6](?:,[0-6])*)?$/.test(s.daysOfWeek))
+      return false;
+    const minutes = (time) => Number(time.slice(0, 2)) * 60 + Number(time.slice(3));
+    const duration = (s.toDate - s.fromDate) * 1440 + minutes(s.toTime) - minutes(s.fromTime);
+    if (duration <= 0 || duration > 1440)
+      return false;
+    names.add(s.name);
+  }
+  if (b.shiftName === void 0)
+    return b.occurrence === void 0;
+  if (!nonempty(b.shiftName) || !names.has(b.shiftName) || !b.occurrence || !instant(b.occurrence.from) || !instant(b.occurrence.to))
+    return false;
+  const at = Date.parse(b.businessTime);
+  return Date.parse(b.occurrence.from) <= at && at < Date.parse(b.occurrence.to);
+}
+
 // ../ops-contract/dist/operational-ingest.js
 var TASK_STATUS = ["created", "assigned", "in-progress", "completed"];
 var EQUIPMENT_STATUS = ["idle", "busy", "down", "setup", "planned-stop"];
@@ -1881,7 +1918,8 @@ var SPECS = {
       startTime: "string",
       endTime: "string",
       materialActual: "object[]",
-      recordTime: "string"
+      recordTime: "string",
+      workShiftBasis: "object"
     },
     /*
      * **자재 줄의 안쪽** — 계약의 `MaterialActual` 그대로다.
@@ -1897,6 +1935,11 @@ var SPECS = {
      * 물려받으면 단위를 모르는 현장의 사실이 통째로 거절된다.
      */
     shapes: {
+      workShiftBasis: {
+        required: ["basisId", "arrangementId", "revisionId", "revisionNumber", "planId", "contentHash", "businessTime", "timezone", "shifts", "workDate"],
+        fields: { basisId: "string", arrangementId: "string", revisionId: "string", revisionNumber: "number", planId: "string", contentHash: "string", businessTime: "string", timezone: "string", workDate: "string" }
+        // Full nested content and selected occurrence are checked by isWorkShiftExecutionBasis below.
+      },
       materialActual: {
         required: ["definitionId", "use"],
         fields: { definitionId: "string", lotId: "string", quantity: "number", uom: "string" },
@@ -2023,13 +2066,19 @@ var SPECS = {
        * 새 어휘가 아니다 — 계약이 `recipeKey` 를 네 자리에서 이미 쓴다. 오더 관측에만 자리가 없었다.
        */
       recipeKey: "string",
-      recipeBasis: "object"
+      recipeBasis: "object",
+      materialBasis: "object[]"
     },
     /*
      * 확보분의 안쪽을 본다 — 열쇠와 수 둘이다(§`AllocatedQuantity`). 안 보면 틀린 이름이 조용히
      * 지나가고(`epcs`·`quantity` 따위), 미러는 잡힌 수를 0 으로 읽는다.
      */
     shapes: {
+      materialBasis: {
+        required: ["basisId", "materialId", "revisionId", "revisionNumber", "planId", "contentHash", "businessTime", "material"],
+        fields: { basisId: "string", materialId: "string", revisionId: "string", revisionNumber: "number", planId: "string", contentHash: "string", businessTime: "string" }
+        // Recursive material properties and reference lists are checked by isMaterialExecutionBasis.
+      },
       recipeBasis: {
         required: ["basisId", "recipeId", "revisionId", "planId", "contentHash", "businessTime", "recipe"],
         fields: { basisId: "string", recipeId: "string", revisionId: "string", planId: "string", contentHash: "string", businessTime: "string" }
@@ -2115,7 +2164,14 @@ var SPECS = {
       /* 사람이 정한 사유 — 없을 수 있다(적지 않은 것과 사유가 없는 것은 다르므로 지어내지 않는다). */
       reasonCode: "string",
       decidedBy: "string",
-      recordTime: "string"
+      recordTime: "string",
+      workShiftBasis: "object"
+    },
+    shapes: {
+      workShiftBasis: {
+        required: ["basisId", "arrangementId", "revisionId", "revisionNumber", "planId", "contentHash", "businessTime", "timezone", "shifts", "workDate"],
+        fields: { basisId: "string", arrangementId: "string", revisionId: "string", revisionNumber: "number", planId: "string", contentHash: "string", businessTime: "string", timezone: "string", workDate: "string" }
+      }
     },
     enums: { status: EQUIPMENT_STATUS }
   },
@@ -2898,6 +2954,7 @@ var ObservedReducer = class {
     switch (e.eventType) {
       case OP_EVENT.task: {
         const d = e.data;
+        if (d.workShiftBasis !== void 0 && !isWorkShiftExecutionBasis(d.workShiftBasis)) throw new Error("Invalid pinned work shift evidence");
         if (this.stale(`task:${d.taskId}`, e)) return;
         this.touchLocation(d.fromNode);
         this.touchLocation(d.toNode);
@@ -2922,6 +2979,7 @@ var ObservedReducer = class {
           ...d.resources?.length ? { resources: d.resources.slice() } : {},
           /* 실제 자재 이동 — 인원·설비와 같은 채널로 온다(실적을 한 곳에서 읽는다).
              말하지 않았으면 **앞의 것을 지킨다**(위 주석) — 빈 배열은 「지웠다」로 말한 것이다. */
+          ...d.workShiftBasis ? { workShiftBasis: structuredClone(d.workShiftBasis) } : prevTask?.workShiftBasis ? { workShiftBasis: structuredClone(prevTask.workShiftBasis) } : {},
           ...d.materialActual?.length ? { materialActual: d.materialActual.map((r) => ({ ...r })) } : keptActual?.length ? { materialActual: keptActual.map((r) => ({ ...r })) } : {},
           ...d.priority !== void 0 ? { priority: d.priority } : {},
           ...d.startTime ? { startTime: d.startTime } : {},
@@ -3003,6 +3061,7 @@ var ObservedReducer = class {
       }
       case OP_EVENT.equipmentPeriod: {
         const d = e.data;
+        if (d.workShiftBasis !== void 0 && !isWorkShiftExecutionBasis(d.workShiftBasis)) throw new Error("Invalid pinned work shift evidence");
         if (!d?.moverId || !d?.from || !d?.to) break;
         const from = Date.parse(d.from);
         const to = Date.parse(d.to);
@@ -3112,6 +3171,7 @@ var ObservedReducer = class {
           /* 어느 레시피로 만드는가 — 품목만으로는 「무엇으로」가 남지 않는다(같은 품목에 대체 레시피). */
           ...d.recipeKey ? { recipeKey: d.recipeKey } : {},
           ...d.recipeBasis ? { recipeBasis: structuredClone(d.recipeBasis) } : {},
+          ...d.materialBasis ? { materialBasis: structuredClone(d.materialBasis) } : {},
           ...d.allocated?.length ? { allocated: d.allocated.slice() } : {},
           ...d.bizTransaction ? { bizTransaction: d.bizTransaction } : {},
           /* 이행하는 계획 — 「이 계획이 얼마나 됐나」를 이 값으로 묶어 답한다(§`OrderState.operationsRequestId`). */
@@ -3536,7 +3596,7 @@ var ObservedReducer = class {
       /* 수량으로 담긴 것도 이어받는다 — 되풀어 주지 않는 축이다(원천은 담김을 다시 말해 주지 않는다). */
       qtyAggregation: [...this.qtyAggregation.entries()].map(([parent, quantities]) => ({ parent, quantities })),
       pendingQuantities: [...this.pendingQuantities.entries()].map(([parent, quantities]) => ({ parent, quantities })),
-      tasks: [...this.tasks.values()].map((t) => ({ ...t })),
+      tasks: [...this.tasks.values()].map((t) => structuredClone(t)),
       equipment: [...this.equipment.values()].map((m) => ({ ...m })),
       persons: [...this.persons.values()].map((x) => ({ ...x })),
       assets: [...this.assets.values()].map((x) => ({ ...x })),
@@ -3564,6 +3624,9 @@ var ObservedReducer = class {
    * 모델에서 오는 판정 입력(교대·등급·시간대)은 생성자가 이미 세웠으므로 건드리지 않는다.
    */
   restore(cp) {
+    for (const task of cp?.tasks ?? []) {
+      if (task.workShiftBasis !== void 0 && !isWorkShiftExecutionBasis(task.workShiftBasis)) throw new Error("Invalid pinned work shift evidence");
+    }
     this.observations = new Map(
       (cp?.observations ?? []).map((o) => [o.id, new Map((o.values ?? []).map((v) => [v.propertyId, { ...v }]))])
     );
@@ -3576,7 +3639,7 @@ var ObservedReducer = class {
     this.pendingParent = new Map((cp?.pendingParent ?? []).map((x) => [x.child, x.parent]));
     this.qtyAggregation = new Map((cp?.qtyAggregation ?? []).map((x) => [x.parent, x.quantities]));
     this.pendingQuantities = new Map((cp?.pendingQuantities ?? []).map((x) => [x.parent, x.quantities]));
-    this.tasks = new Map((cp?.tasks ?? []).map((t) => [t.id, { ...t }]));
+    this.tasks = new Map((cp?.tasks ?? []).map((t) => [t.id, structuredClone(t)]));
     this.equipment = new Map((cp?.equipment ?? []).map((m) => [m.id, { ...m }]));
     this.oeeCounters = new Map(
       (cp?.oeeCounters ?? []).map((c) => [String(c.id), { ...emptyOeeCounters(), ...c, id: void 0 }])
@@ -3630,7 +3693,7 @@ var ObservedReducer = class {
          만료는 이벤트 없이 시각만으로 일어나므로, 델타로 받아 두면 유휴 자원이 영원히 유효하게 남는다. */
       persons: [...this.persons.values()].map((p) => ({ ...p, ...this.effectivityPart(p), ...this.offShiftPart(`person:${p.id}`), ...this.capabilityPart(p, `person:${p.id}`, p.personnelClassIds, this.classDefs.personnel) })),
       assets: [...this.assets.values()].map((a) => ({ ...a, ...this.effectivityPart(a), ...this.capabilityPart(a, `asset:${a.id}`, a.assetClassIds, this.classDefs.asset) })),
-      tasks: [...this.tasks.values()].map((t) => ({ ...t })),
+      tasks: [...this.tasks.values()].map((t) => structuredClone(t)),
       equipment: [...this.equipment.values()].map((m) => ({ ...m, ...this.oeePart(m.id), ...this.effectivityPart(m), ...this.offShiftPart(`eq:${m.id}`), ...this.capabilityPart(m, `eq:${m.id}`, m.kind ? [m.kind] : [], this.classDefs.equipment) })),
       orders: [...this.orders.values()].map((o) => ({ ...o })),
       acked: [...this.acked]
@@ -4527,6 +4590,9 @@ var FlowEngine = class {
     return { kept, dropped };
   }
   hydrateObserved(snap, orders = [], purpose = "seed") {
+    for (const task of snap.tasks ?? []) {
+      if (task.workShiftBasis !== void 0 && !isWorkShiftExecutionBasis(task.workShiftBasis)) throw new Error("Invalid pinned work shift evidence");
+    }
     for (const id of snap.acked ?? []) this._acked.add(id);
     for (const e of snap.attentionSince ?? []) if (e?.id && e.since) this._attentionSince.set(e.id, e.since);
     for (const n of snap.locations) {
@@ -4688,6 +4754,7 @@ var FlowEngine = class {
       ...o.gtin ? { gtin: o.gtin } : {},
       ...o.recipeKey ? { recipeKey: o.recipeKey } : {},
       ...o.recipeBasis ? { recipeBasis: structuredClone(o.recipeBasis) } : {},
+      ...o.materialBasis ? { materialBasis: structuredClone(o.materialBasis) } : {},
       ...o.bizTransaction ? { bizTransaction: o.bizTransaction } : {},
       ...o.dockDoor ? { dockDoor: o.dockDoor } : {},
       ...o.windowStartMs !== void 0 ? { windowStartMs: o.windowStartMs } : {}
@@ -4713,6 +4780,7 @@ var FlowEngine = class {
            남은 공정·소요가 다른 레시피 기준으로 계산된다(같은 품목에 대체 레시피가 있다). */
         ...o.recipeKey ? { recipeKey: o.recipeKey } : {},
         ...o.recipeBasis ? { recipeBasis: structuredClone(o.recipeBasis) } : {},
+        ...o.materialBasis ? { materialBasis: structuredClone(o.materialBasis) } : {},
         bizTransaction: o.bizTransaction ?? "",
         allocated: resolved.kept,
         picked: [],
@@ -4766,6 +4834,7 @@ var FlowEngine = class {
         status: purpose === "observe" ? t.status : known && t.status === "in-progress" ? "in-progress" : "created",
         /* 이미 일어난 자재 이동은 **씨앗에도 남는다** — 잃으면 실적이 재기동마다 지워진다. */
         ...t.materialActual?.length ? { materialActual: t.materialActual.map((r) => ({ ...r })) } : {},
+        ...t.workShiftBasis ? { workShiftBasis: structuredClone(t.workShiftBasis) } : {},
         itemEpc: t.itemRefs?.[0] ?? "",
         fromNode: t.fromNode ?? "",
         toNode: t.toNode ?? "",
@@ -5123,6 +5192,7 @@ var FlowEngine = class {
         ...t.assets?.length ? { assets: t.assets.slice() } : {},
         ...t.resources?.length ? { resources: t.resources.slice() } : {},
         ...t.materialActual?.length ? { materialActual: t.materialActual.map((r) => ({ ...r })) } : {},
+        ...t.workShiftBasis ? { workShiftBasis: structuredClone(t.workShiftBasis) } : {},
         ...t.priority !== void 0 ? { priority: t.priority } : {},
         ...t.startTime ? { startTime: t.startTime } : {},
         ...t.endTime ? { endTime: t.endTime } : {}
@@ -5147,6 +5217,7 @@ var FlowEngine = class {
         /* **어느 레시피로 만드나** — 품목만으로는 「무엇으로」가 안 남는다(같은 품목의 대체 레시피가 있다). */
         ...o.recipeKey ? { recipeKey: o.recipeKey } : {},
         ...o.recipeBasis ? { recipeBasis: structuredClone(o.recipeBasis) } : {},
+        ...o.materialBasis ? { materialBasis: structuredClone(o.materialBasis) } : {},
         /* 씨앗이 다 심지 못했다는 사실 — 조용히 자르지 않는다(그 오더의 답은 부족한 씨앗 위에 있다). */
         ...o.seedIncomplete ? { seedIncomplete: true } : {},
         /* 왜 대기하는지 — 없으면 화면은 「running」만 보여 주고 사람은 원인을 찾을 자리가 없다. */
@@ -6141,6 +6212,7 @@ var FlowEngine = class {
       ...t.resources?.length ? { resources: t.resources.slice() } : {},
       /* 실제 자재 이동 — 인원·설비와 같은 채널(실적을 한 곳에서 읽는다). */
       ...t.materialActual?.length ? { materialActual: t.materialActual.map((r) => ({ ...r })) } : {},
+      ...t.workShiftBasis ? { workShiftBasis: structuredClone(t.workShiftBasis) } : {},
       ...t.durationMs ? { durationMs: t.durationMs } : {},
       /* 품질 판정이 있었으면 **그 자리에서** 실어 보낸다 — 없으면 필드를 만들지 않는다(모름≠양품). */
       ...t.outcome ? { outcome: t.outcome } : {},
@@ -6182,6 +6254,7 @@ var FlowEngine = class {
          레시피가 있다). 시뮬만 아는 사실이 남으면 두 스냅샷을 같은 규칙으로 읽을 수 없다. */
       ...o.recipeKey ? { recipeKey: o.recipeKey } : {},
       ...o.recipeBasis ? { recipeBasis: structuredClone(o.recipeBasis) } : {},
+      ...o.materialBasis ? { materialBasis: structuredClone(o.materialBasis) } : {},
       ...o.allocated?.length ? { allocated: o.allocated.slice() } : {},
       ...o.bizTransaction ? { bizTransaction: o.bizTransaction } : {},
       /* 약속해 둔 자리·시각창 — 이것이 빠져서 야드 트윈이 재기동마다 첫 틱에 죽었다(§dockDoor). */
@@ -6356,7 +6429,7 @@ var FlowEngine = class {
       if (!remaining) continue;
       for (const it of this.items.at(at)) {
         if (remaining <= 0) break;
-        if (!this.materialMatches(it, req)) continue;
+        if (!this.materialMatches(it, req, t.orderId)) continue;
         if (it.disposition === DISP.in_progress) continue;
         const already = takenSoFar.get(it.epc) ?? 0;
         const avail = Math.max(0, (it.qty ?? 1) - already);
@@ -6371,11 +6444,12 @@ var FlowEngine = class {
     return picked;
   }
   /** 이 물품이 명세를 만족하나 — 품목 지목이 우선, 없으면 등급(상속을 타고 닫는다). */
-  materialMatches(it, req) {
+  materialMatches(it, req, orderId) {
     const defId = it.definitionId ?? it.gtin;
     if (req.materialDefinition) return defId === req.materialDefinition;
     if (req.materialClass) {
-      const def = defId ? this.materialDefs.get(defId) : void 0;
+      const basis = orderId ? this.orders.get(orderId)?.materialBasis : void 0;
+      const def = basis !== void 0 ? basis.find((b) => b.material.id === defId)?.material : defId ? this.materialDefs.get(defId) : void 0;
       return classClosure(def?.materialClassIds, this.classDefs.material, this.now()).has(req.materialClass);
     }
     return true;

package/package.json

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