@operato/ops-contract 0.8.0 → 0.9.0

package/dist/contract.d.ts

@@ -1798,12 +1798,7 @@ export interface TaskState {
      * **실제로 들어가고 나온 자재** — ISA-95 `JobResponse.MaterialActual`(`OpMaterialActualType`).
      * 명세(계획)가 아니라 일어난 일이다. 투입 인원·설비와 같은 채널에 실어 실적을 한 곳에서 읽는다.
      */
-    materialActual?: {
-        definitionId: string;
-        use: 'consumed' | 'produced';
-        quantity: number;
-        uom?: string;
-    }[];
+    materialActual?: MaterialActual[];
 }
 /**
  * 오더 하나의 관측 상태 — **ISA-95 `OperationsRequest`**(Part 4, 일정).
@@ -3102,6 +3097,39 @@ export interface QualityDelta {
      */
     taskId?: string;
 }
+/**
+ * 실제로 들어가고 나온 자재 한 줄 — ISA-95 `OpMaterialActualType` 의 부분집합.
+ *
+ * ── 왜 이름 있는 타입인가 (2026-08-31) ────────────────────────────────────
+ * 같은 데이터가 네 곳에 각각 인라인으로 적혀 있었다(작업 상태 둘 · 커널 · ERP). ERP 쪽은 필드명까지
+ * 달랐다(`materialDefinitionId` · `direction`). 같은 데이터를 여러 이름으로 부르면 옮기는 코드가
+ * 생기고, 그 코드가 언젠가 어긋난다.
+ *
+ * 표준 매핑은 커널이 이미 적어 두었다 — `MaterialDefinitionID` → `definitionId`,
+ * `MaterialUse` → `use`. 그 이름을 그대로 쓴다.
+ */
+export interface MaterialActual {
+    /** 표준 `MaterialDefinitionID`. */
+    definitionId: string;
+    /** 표준 `MaterialUse`. */
+    use: 'consumed' | 'produced';
+    quantity: number;
+    uom?: string;
+    /**
+     * 어느 로트를 썼는가 — 표준 `MaterialLotID`.
+     *
+     * ── 값은 식별자다 (2026-08-31, MES 레인 요청) ─────────────────────────────
+     * 로트 번호 문자열이 아니라 **식별자**를 넣는다. GS1 로 식별되는 로트는
+     * `urn:epc:class:lgtin:<프리픽스>.<품번>.<로트>` 이고, 그렇지 않으면 원본 시스템의 로트 식별자다.
+     *
+     * 문자열을 기준값으로 두면 이것을 쓰는 네 곳에서 각각 식별자를 다시 조립해야 한다 — 불합격 로트의
+     * 이동 제한, EPCIS `TransformationEvent` 의 입력·출력 목록, 현장 자재 스캔, 로트 엔티티. 조립
+     * 규칙이 네 곳에 생기면 그중 하나가 달라지는 날 그 경로에서만 로트가 맞지 않고 오류는 발생하지 않는다.
+     *
+     * 사람이 읽는 로트 번호는 식별자에서 파생한다 — `ItemState.lot` 이 이미 그 방식이다.
+     */
+    lotId?: string;
+}
 export interface TaskStatusDelta {
     taskId: string;
     /** 착수 시각(절대 sim-clock) — 보간 앵커. TaskState 와 같은 뜻. */
@@ -3158,12 +3186,7 @@ export interface TaskStatusDelta {
      * **실제로 들어가고 나온 자재** — ISA-95 `JobResponse.MaterialActual`(`OpMaterialActualType`).
      * 명세(계획)가 아니라 일어난 일이다. 투입 인원·설비와 같은 채널에 실어 실적을 한 곳에서 읽는다.
      */
-    materialActual?: {
-        definitionId: string;
-        use: 'consumed' | 'produced';
-        quantity: number;
-        uom?: string;
-    }[];
+    materialActual?: MaterialActual[];
 }
 export interface EquipmentStatusDelta extends EffectivePeriod {
     moverId: string;

package/dist/domain-definition.d.ts

@@ -239,7 +239,13 @@ export interface OpMaterialSpecification {
     uom?: string;
 }
 /** 라우트(오퍼레이션 시퀀스) — ISA-95 ProcessSegment 연결. */
-export interface RouteDef {
+/**
+ * 공정을 지나는 순서.
+ *
+ * 유효 기간은 레시피와 같은 이유로 있다 — 라우트도 개정되고, 지난 실적이 어느 경로로 만든 것인지
+ * 잃으면 추적이 성립하지 않는다(§`RecipeDef`).
+ */
+export interface RouteDef extends EffectivePeriod {
     key: string;
     label: string;
     /** OperationDef.key 순서. */
@@ -323,8 +329,20 @@ export interface RecipePart {
      */
     operation?: string;
 }
-/** BOM/레시피 — ISA-95 Material Consumed/Produced · EPCIS TransformationEvent(input→output). */
-export interface RecipeDef {
+/**
+ * BOM/레시피 — ISA-95 Material Consumed/Produced · EPCIS TransformationEvent(input→output).
+ *
+ * ── 유효 기간을 왜 여기 두나 (2026-08-31) ────────────────────────────────
+ * **레시피는 개정된다.** 그런데 이 타입에 그 자리가 없어서, 마스터가 `effectiveStart`·`effectiveEnd` 를
+ * 채워 보내도 커널이 오류 없이 지나쳤다 — 값을 넣어도 트윈에 닿지 않았다.
+ *
+ * 그것이 없으면 **지난 실적이 어느 배합으로 만든 것인지 잃는다.** 정산과 추적이 그 위에 선다.
+ * 마스터가 행을 지우지 않고 이 칸을 채우는 이유도 그것이다.
+ *
+ * 선언 적합성 하네스가 잡았다(`ops-master/test/declaration-reaches-contract.test.ts`) — 마스터가
+ * 내보내는 칸이 계약에 실재하는지 보는 시험이다.
+ */
+export interface RecipeDef extends EffectivePeriod {
     key: string;
     label: string;
     inputs: RecipePart[];

package/dist/erp.d.ts

@@ -1,4 +1,4 @@
-import type { ISOTime } from './contract.ts';
+import type { ISOTime, MaterialActual } from './contract.ts';
 /**
  * **무엇을 얼마나 만들라** — 이 사실을 나르는 자리가 둘이고, 어휘는 하나다.
  *
@@ -106,7 +106,12 @@ export interface ProductionPerformanceEntry {
     to: ISOTime;
     /** 누가 했나 — ERP 의 인사번호. 「누가 적었나」는 여기 오지 않는다(MES 의 감사 추적이다). */
     personId?: string;
-    /** 쓴 자재 — 소비 문서가 된다. 없으면 자재 소비를 올리지 않는다(0 으로 채우지 않는다). */
+    /**
+     * 쓴 자재 — 소비 문서가 된다. 없으면 자재 소비를 올리지 않는다(0 으로 채우지 않는다).
+     *
+     * 모양은 커널과 같은 `MaterialActual` 이다. 처음에는 여기에 따로 적었고 필드명이 달랐다
+     * (`materialDefinitionId` · `direction`) — 같은 데이터를 두 이름으로 부르면 옮기는 코드가 생긴다.
+     */
     materialActual?: MaterialActual[];
     /**
      * **이것이 이 지시의 마지막 실적인가** — ERP 가 이 값으로 오더를 닫는다.
@@ -117,16 +122,6 @@ export interface ProductionPerformanceEntry {
     final?: boolean;
     recordTime?: ISOTime;
 }
-/** 실제로 들어가고 나온 자재 한 줄. */
-export interface MaterialActual {
-    /** 마스터의 `MaterialDefinition` 식별자 — 지시와 같은 이름을 쓴다. */
-    materialDefinitionId: string;
-    quantity: number;
-    uom: string;
-    /** `consumed` 소비 · `produced` 산출. 부호로 구별하지 않는다 — 음수는 되돌림과 섞인다. */
-    direction: 'consumed' | 'produced';
-    lot?: string;
-}
 /**
  * 실적의 **멱등 키** — 같은 실적이 두 번 올라가지 않게.
  *

package/dist/erp.js

@@ -88,14 +88,14 @@ export function validatePerformance(e, nowMs) {
             errors.push('아직 오지 않은 시각까지의 실적이다');
     }
     for (const m of e?.materialActual ?? []) {
-        if (!String(m?.materialDefinitionId ?? '').trim())
-            errors.push('자재 줄에 materialDefinitionId 가 없다');
+        if (!String(m?.definitionId ?? '').trim())
+            errors.push('자재 줄에 definitionId 가 없다');
         if (!String(m?.uom ?? '').trim())
-            errors.push(`${m?.materialDefinitionId}: uom 없음 — 단위는 ERP 의 사실이므로 지어내지 않는다`);
+            errors.push(`${m?.definitionId}: uom 없음 — 단위는 ERP 의 사실이므로 지어내지 않는다`);
         if (typeof m?.quantity !== 'number' || !(m.quantity > 0))
-            errors.push(`${m?.materialDefinitionId}: 수량이 0 이하다`);
-        if (m?.direction !== 'consumed' && m?.direction !== 'produced') {
-            errors.push(`${m?.materialDefinitionId}: direction 이 consumed · produced 가 아니다`);
+            errors.push(`${m?.definitionId}: 수량이 0 이하다`);
+        if (m?.use !== 'consumed' && m?.use !== 'produced') {
+            errors.push(`${m?.definitionId}: use 가 consumed · produced 가 아니다`);
         }
     }
     return errors;

package/dist-cjs/index.cjs

@@ -3930,11 +3930,11 @@ function validatePerformance(e, nowMs) {
     if (to > nowMs) errors.push("\uC544\uC9C1 \uC624\uC9C0 \uC54A\uC740 \uC2DC\uAC01\uAE4C\uC9C0\uC758 \uC2E4\uC801\uC774\uB2E4");
   }
   for (const m of e?.materialActual ?? []) {
-    if (!String(m?.materialDefinitionId ?? "").trim()) errors.push("\uC790\uC7AC \uC904\uC5D0 materialDefinitionId \uAC00 \uC5C6\uB2E4");
-    if (!String(m?.uom ?? "").trim()) errors.push(`${m?.materialDefinitionId}: uom \uC5C6\uC74C \u2014 \uB2E8\uC704\uB294 ERP \uC758 \uC0AC\uC2E4\uC774\uBBC0\uB85C \uC9C0\uC5B4\uB0B4\uC9C0 \uC54A\uB294\uB2E4`);
-    if (typeof m?.quantity !== "number" || !(m.quantity > 0)) errors.push(`${m?.materialDefinitionId}: \uC218\uB7C9\uC774 0 \uC774\uD558\uB2E4`);
-    if (m?.direction !== "consumed" && m?.direction !== "produced") {
-      errors.push(`${m?.materialDefinitionId}: direction \uC774 consumed \xB7 produced \uAC00 \uC544\uB2C8\uB2E4`);
+    if (!String(m?.definitionId ?? "").trim()) errors.push("\uC790\uC7AC \uC904\uC5D0 definitionId \uAC00 \uC5C6\uB2E4");
+    if (!String(m?.uom ?? "").trim()) errors.push(`${m?.definitionId}: uom \uC5C6\uC74C \u2014 \uB2E8\uC704\uB294 ERP \uC758 \uC0AC\uC2E4\uC774\uBBC0\uB85C \uC9C0\uC5B4\uB0B4\uC9C0 \uC54A\uB294\uB2E4`);
+    if (typeof m?.quantity !== "number" || !(m.quantity > 0)) errors.push(`${m?.definitionId}: \uC218\uB7C9\uC774 0 \uC774\uD558\uB2E4`);
+    if (m?.use !== "consumed" && m?.use !== "produced") {
+      errors.push(`${m?.definitionId}: use \uAC00 consumed \xB7 produced \uAC00 \uC544\uB2C8\uB2E4`);
     }
   }
   return errors;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operato/ops-contract",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Operations domain contract — the standard vocabulary that producers and readers agree on (EPCIS 2.0/GS1, ISA-95, IEC 61850/ISO 50001). Types, guards, validation. No state, no engine.",
   "type": "module",
   "main": "./dist-cjs/index.cjs",