@operato/ops-contract 0.9.3 → 0.9.4

package/dist/contract.d.ts

@@ -3269,11 +3269,26 @@ export interface QualityDelta {
  * 표준 매핑은 커널이 이미 적어 두었다 — `MaterialDefinitionID` → `definitionId`,
  * `MaterialUse` → `use`. 그 이름을 그대로 쓴다.
  */
+/**
+ * **실적의 자재 쓰임** — 표준 `MaterialUse`. 들어갔나 나왔나 둘이다.
+ *
+ * 공정 **명세**의 쓰임(`OperationMaterial.use`)은 셋이다 — 거기에는 `consumable` 이 있다(쓰이지만
+ * 제품에 남지 않는 것: 세척수·윤활유). **실적에는 그 낱말이 없다** — 일어난 일을 적는 자리이고,
+ * 소모품이 실제로 들어간 것은 `consumed` 다.
+ *
+ * 둘을 한 어휘로 묶지 않는다. 묶으면 실적에 `consumable` 이 올 수 있게 되고, 그때 그것이
+ * 「들어갔다」인지 「쓰였지만 안 남았다」인지 받는 쪽이 정해야 한다.
+ *
+ * 유입 게이트가 이 상수를 가리킨다(§`operational-ingest.ts` 의 `shapes`) — 낱말을 두 곳에 적으면
+ * 한쪽만 늘어나는 날 게이트가 계약에 없는 낱말을 통과시킨다.
+ */
+export declare const MATERIAL_ACTUAL_USE: readonly ["consumed", "produced"];
+export type MaterialActualUse = (typeof MATERIAL_ACTUAL_USE)[number];
 export interface MaterialActual {
     /** 표준 `MaterialDefinitionID`. */
     definitionId: string;
-    /** 표준 `MaterialUse`. */
-    use: 'consumed' | 'produced';
+    /** 표준 `MaterialUse` — 실적은 둘이다(§`MATERIAL_ACTUAL_USE`). */
+    use: MaterialActualUse;
     quantity: number;
     uom?: string;
     /**

package/dist/contract.js

@@ -1318,6 +1318,31 @@ export function isFailureStatus(value) {
 export function isPlannedStopStatus(value) {
     return normalizeEquipmentStatus(value) === 'planned-stop';
 }
+/**
+ * 실제로 들어가고 나온 자재 한 줄 — ISA-95 `OpMaterialActualType` 의 부분집합.
+ *
+ * ── 왜 이름 있는 타입인가 (2026-08-31) ────────────────────────────────────
+ * 같은 데이터가 네 곳에 각각 인라인으로 적혀 있었다(작업 상태 둘 · 커널 · ERP). ERP 쪽은 필드명까지
+ * 달랐다(`materialDefinitionId` · `direction`). 같은 데이터를 여러 이름으로 부르면 옮기는 코드가
+ * 생기고, 그 코드가 언젠가 어긋난다.
+ *
+ * 표준 매핑은 커널이 이미 적어 두었다 — `MaterialDefinitionID` → `definitionId`,
+ * `MaterialUse` → `use`. 그 이름을 그대로 쓴다.
+ */
+/**
+ * **실적의 자재 쓰임** — 표준 `MaterialUse`. 들어갔나 나왔나 둘이다.
+ *
+ * 공정 **명세**의 쓰임(`OperationMaterial.use`)은 셋이다 — 거기에는 `consumable` 이 있다(쓰이지만
+ * 제품에 남지 않는 것: 세척수·윤활유). **실적에는 그 낱말이 없다** — 일어난 일을 적는 자리이고,
+ * 소모품이 실제로 들어간 것은 `consumed` 다.
+ *
+ * 둘을 한 어휘로 묶지 않는다. 묶으면 실적에 `consumable` 이 올 수 있게 되고, 그때 그것이
+ * 「들어갔다」인지 「쓰였지만 안 남았다」인지 받는 쪽이 정해야 한다.
+ *
+ * 유입 게이트가 이 상수를 가리킨다(§`operational-ingest.ts` 의 `shapes`) — 낱말을 두 곳에 적으면
+ * 한쪽만 늘어나는 날 게이트가 계약에 없는 낱말을 통과시킨다.
+ */
+export const MATERIAL_ACTUAL_USE = ['consumed', 'produced'];
 // ── Command 채널 어휘 — 트윈의 "행위(act)" 면 (prescriptive/트랜잭션 프론트엔드) ──
 // 코어 공통: order.hold/resume(할당 보류). 도메인: order.release(즉시 투입) 등은 handleCommand 로.
 export const CMD = {

package/dist/epcis.d.ts

@@ -385,6 +385,24 @@ export declare function gdtiUri(companyPrefix: string, docType: string, serial:
  * Link 를 **권한다**(SHOULD) — 이 길은 프리픽스가 없을 때의 정합 경로다.
  */
 export declare function objectUri(namespace: string, objId: string | number): string | undefined;
+/**
+ * **선언된 이름공간 아래의 클래스 식별자** — SGTIN·LGTIN 을 쓰지 않는 길.
+ *
+ * 품목 등급·로트 등급처럼 「낱개가 아니라 종류」를 가리키는 자리다. 개체 쪽(`objectUri`)과 같은
+ * 사정으로 필요하다: GTIN 을 조립하려면 회사 프리픽스가 있어야 하고, 없는 현장이 그 길로 못 간다.
+ *
+ *  · CBV 2.0 §8.3.4 `http(s)://[Subdomain.]Domain/⁎⁎/class/ClassID`
+ *  · CBV 2.0 §8.3.3 `urn:URNNamespace:⁎⁎:class:ClassID`
+ *
+ * ── 왜 계약에 두나 (2026-09-04, plant 레인이 올림) ─────────────────────────
+ * 체프 커넥터가 이 URI 를 **직접 조립하고 있었다** — `productClassId` · `lotClassId` 라는 자기
+ * 이름으로. 그중 `bizTransactionId` 는 이 파일의 `bizTransactionUri` 와 **같은 것을 다르게**
+ * 만들고 있었다. `underNamespace` 는 처음부터 `'class'` 표지를 알고 있었고(그 함수 주석에
+ * §8.3.3·§8.3.4 까지 적혀 있다) **부를 문만 없었다.**
+ *
+ * 그래서 한 표준에 방언이 둘이 됐다. 문을 낸다.
+ */
+export declare function classUri(namespace: string, classId: string | number): string | undefined;
 export declare function bizTransactionUri(namespace: string, transId: string | number): string | undefined;
 /** 모든 빌더가 공통으로 받는 표준 헤더 옵션(선택) — 방출부가 필요할 때 채운다. */
 export interface EpcisHeaderOptions {

package/dist/epcis.js

@@ -263,6 +263,26 @@ export function gdtiUri(companyPrefix, docType, serial) {
 export function objectUri(namespace, objId) {
     return underNamespace(namespace, 'obj', objId);
 }
+/**
+ * **선언된 이름공간 아래의 클래스 식별자** — SGTIN·LGTIN 을 쓰지 않는 길.
+ *
+ * 품목 등급·로트 등급처럼 「낱개가 아니라 종류」를 가리키는 자리다. 개체 쪽(`objectUri`)과 같은
+ * 사정으로 필요하다: GTIN 을 조립하려면 회사 프리픽스가 있어야 하고, 없는 현장이 그 길로 못 간다.
+ *
+ *  · CBV 2.0 §8.3.4 `http(s)://[Subdomain.]Domain/⁎⁎/class/ClassID`
+ *  · CBV 2.0 §8.3.3 `urn:URNNamespace:⁎⁎:class:ClassID`
+ *
+ * ── 왜 계약에 두나 (2026-09-04, plant 레인이 올림) ─────────────────────────
+ * 체프 커넥터가 이 URI 를 **직접 조립하고 있었다** — `productClassId` · `lotClassId` 라는 자기
+ * 이름으로. 그중 `bizTransactionId` 는 이 파일의 `bizTransactionUri` 와 **같은 것을 다르게**
+ * 만들고 있었다. `underNamespace` 는 처음부터 `'class'` 표지를 알고 있었고(그 함수 주석에
+ * §8.3.3·§8.3.4 까지 적혀 있다) **부를 문만 없었다.**
+ *
+ * 그래서 한 표준에 방언이 둘이 됐다. 문을 낸다.
+ */
+export function classUri(namespace, classId) {
+    return underNamespace(namespace, 'class', classId);
+}
 export function bizTransactionUri(namespace, transId) {
     return underNamespace(namespace, 'bt', transId);
 }
@@ -271,15 +291,44 @@ export function bizTransactionUri(namespace, transId) {
  *
  * `obj`(개체 §8.2.3·§8.2.4) · `class`(클래스 §8.3.3·§8.3.4) · `bt`(거래문서 §8.5.4·§8.5.5) 가 같은
  * 모양이다. 규칙을 세 곳에 적으면 한 곳만 고쳐지는 날이 온다.
+ *
+ * ── 구분자를 계약이 부호화한다 (2026-09-04) ────────────────────────────────
+ * 전에는 구분자가 들면 **아무것도 만들지 않았다.** 그러면 부르는 쪽이 자기 손으로 부호화해서
+ * 넘기게 되고 — 실제로 그랬다 — 부르는 쪽마다 부호화가 달라진다. 방금 `classUri` 가 없어서
+ * 방언이 생긴 것과 **같은 부류**다. 표지 규칙만 계약이 갖고 부호화는 소비처에 남기면 반쪽이다.
+ *
+ * 그래서 **원문을 받아 계약이 부호화한다.** 부르는 쪽은 미리 부호화하지 않는다 — 하면 두 번
+ * 부호화되어(`A%2FB` → `A%252FB`) 다른 개체가 된다.
+ *
+ * ── 저장된 식별자를 건드리지 않는다 ────────────────────────────────────────
+ * 이 함수가 내는 값은 **저널에 남는 정체성**이다(인티그레이션 레인 실측: 47만 건 넘음). 한 글자만
+ * 달라도 이전 사실과 새 사실이 다른 개체가 된다. 그래서 **구조를 깨는 글자만** 부호화한다.
+ *
+ *   부호화한다   %  /  :  ?  #  공백    URL 경로 성분이나 URN 성분 경계를 깬다(`%` 는 부호화의
+ *                                      부호이므로 먼저 해야 뜻이 하나로 정해진다)
+ *   그대로 둔다  그 밖의 모든 글자      영숫자 · `-` · `.` · `_` · `~` 를 포함해 전부
+ *
+ * 그래서 **위 여섯 글자가 없는 값은 바이트까지 그대로다** — 지금 저장된 값은 그 집합에 들었나만
+ * 확인하면 된다(그 확인은 값을 가진 쪽이 한다). 전에 통과하던 값 중 구분자가 든 것은 없었으므로
+ * (구분자가 들면 만들지 않았다) 이 변경으로 **바뀔 수 있는 것은 공백·`%`·`?`·`#` 이 든 값뿐**이다.
  */
+const STRUCTURE_BREAKING = /[%/:?# ]/g;
+const PERCENT_ENCODED = {
+    '%': '%25',
+    '/': '%2F',
+    ':': '%3A',
+    '?': '%3F',
+    '#': '%23',
+    ' ': '%20'
+};
 function underNamespace(namespace, marker, id) {
     const ns = namespace?.trim();
     if (!ns)
         return undefined;
-    const v = String(id);
-    /* 표준이 요구하는 「성분 하나」가 깨진다 — 구분자가 든 값은 만들지 않는다. */
-    if (!v || v.includes('/') || v.includes(':'))
+    const raw = String(id);
+    if (!raw)
         return undefined;
+    const v = raw.replace(STRUCTURE_BREAKING, c => PERCENT_ENCODED[c]);
     if (/^https?:\/\/[^/\s]+/.test(ns))
         return `${ns.replace(/\/+$/, '')}/${marker}/${v}`;
     /*
@@ -447,7 +496,30 @@ const CBV_URN_CLASS = /^urn:[^:\s]+:(?:[^:\s]+:)*class:[^:\s]+$/;
  * 합계만 본다 — 프리픽스가 몇 자리인지는 GS1 이 회사마다 다르게 배정하므로 우리가 알 수 없다.
  * 합계는 키 종류가 정한다: SGTIN 13(GTIN-14 의 표시자+13자리) · SSCC 17 · GRAI 12 · GDTI 12.
  */
-const GS1_KEY_DIGITS = { sgtin: 13, sscc: 17, grai: 12, gdti: 12 };
+/*
+ * 키마다 「숫자 마디의 자릿수 합」 — 이 표에 없는 키는 아래 함수가 **아무 말도 하지 않는다.**
+ *
+ * ── lgtin 이 빠져 있었다 (2026-09-04, plant 레인 실측) ──────────────────────
+ * `urn:epc:class:lgtin:880.01.LOT-A` 는 합이 5 인데 그냥 지났고, 같은 값을 sgtin 으로 적으면
+ * 거절됐다. **하필 로트로 관리하는 자재가 쓰는 종류다** — 원자재·화학·식품이 다 여기다.
+ *
+ * 규칙은 이미 이 파일의 `lgtinClass` 주석에 적혀 있었다("두 숫자 마디의 자릿수 합은 13", EPC TDS
+ * 2.1.0 §6.4.1). 규칙을 알고, 검사도 있고, **표에 키만 없었다.**
+ *
+ * 셋째 마디(로트)는 숫자가 아니다 — 아래 함수가 앞의 두 마디만 세므로 그대로 맞다.
+ *
+ * ── sgln 도 같이 없었다 ────────────────────────────────────────────────────
+ * 로트를 찾다가 봤다. GLN 은 검사숫자를 뺀 두 마디 합이 12 라 `grai`·`gdti` 와 같은 규칙인데
+ * 표에 없었다.
+ *
+ * 값이 흐르고 있는지는 재봤다: **아직 안 흐른다.** 접수면에 자리가 있고(`RefLocation.gs1Id`)
+ * 매핑도 그것을 옮기는데, plant 마스터의 자리 표에는 그 컬럼 자체가 없다(`properties` 안에도
+ * 없다 — 0건). 그러니 이 키를 더해서 **지금 거절되는 값은 없다.** 오는 날에 맞아 있으려고 둔다.
+ *
+ * `giai`(개별 자산)는 일부러 없다 — 자산 참조 길이가 가변이어서 **합이 고정되지 않는다**(전체
+ * 30자리 이내라는 상한만 있다). 자릿수로 판정할 수 없는 키를 표에 넣으면 맞는 값을 거절한다.
+ */
+const GS1_KEY_DIGITS = { sgtin: 13, lgtin: 13, sscc: 17, grai: 12, gdti: 12, sgln: 12 };
 /**
  * 그 GS1 키의 자리 수가 맞나 — 어긋나면 왜인지 말한다.
  *

package/dist/operational-ingest.d.ts

@@ -19,6 +19,34 @@ export interface OperationalIngestOptions {
     /** 레코드에 시각이 없을 때 쓸 값 — 주지 않으면 그 레코드를 거부한다. */
     defaultEventTime?: string;
 }
+/**
+ * **객체 안쪽의 모양** — `object`·`object[]` 자리가 계약의 타입을 실제로 보게 한다.
+ *
+ * ── 왜 필요한가 (2026-09-04 실측, 인티그레이션 레인이 찾음) ────────────────
+ * `materialActual: 'object[]'` 은 **객체 배열이면 지나갔다.** 그래서 틀린 이름이 저널에 앉았다.
+ *
+ *   계약의 이름   definitionId
+ *   온 것         materialDefinitionId
+ *
+ *   적히나   예 — 저널에 그 줄이 그대로 있다
+ *   읽히나   아니오 — 계약의 타입으로 읽으면 undefined 다
+ *
+ * 거절도 경고도 없었다. **같은 계약의 ERP 경로는 이것을 잡는다**(§`erp.ts` 의 자재 줄 검사).
+ * 한 계약 안에 검사가 두 벌이고 한쪽만 봤다.
+ *
+ * 이름을 맞춰 달라고 원본에 청하는 것으로는 다음에 또 조용해진다 — 다음 원본이 `use: 'out'` 같은
+ * 것을 보내면 같은 일이 난다(실제로 그런 시드가 있었다: 계약에 `out` 이라는 낱말이 없다).
+ */
+export interface ObjectShape {
+    /** 반드시 있어야 하는 안쪽 필드 — 비어 있으면 그 줄을 거절한다. */
+    required?: readonly string[];
+    /** 안쪽 필드의 형 — 선언한 것만 본다. */
+    fields?: Readonly<Record<string, 'string' | 'number' | 'boolean'>>;
+    /** 낱말이 정해진 안쪽 필드 — 계약에 없는 낱말을 거절한다. */
+    enums?: Readonly<Record<string, readonly string[]>>;
+    /** 0 보다 커야 하는 수 — 「모른다」는 **비워서** 말한다(0 으로 말하지 않는다). */
+    positive?: readonly string[];
+}
 /**
  * 이 레코드가 어느 운영 사실인가 — **라우팅 판정을 한 곳에 둔다**(소비처가 각자 짐작하지 않게).
  *

package/dist/operational-ingest.js

@@ -34,7 +34,59 @@
  * 모르는 필드는 **조용히 버리지 않고 거부한다.** `taskID` 처럼 한 글자 틀린 이름은 통과시키면 영원히
  * 보이지 않는 손실이 된다(이 문에는 아직 옛 발신자가 없어 호환 부담도 없다).
  */
-import { OP_EVENT, DISPOSITION_DECISION } from "./contract.js";
+import { OP_EVENT, DISPOSITION_DECISION, MATERIAL_ACTUAL_USE } from "./contract.js";
+/**
+ * 객체 한 줄이 선언된 안쪽 모양을 지키나 — **선언하지 않은 자리는 보지 않는다.**
+ *
+ * 순수하다. 그래서 「어떤 줄이 거절되나」를 값만 바꿔 가며 잴 수 있다.
+ *
+ * ── 「모른다」를 0 으로 말하지 않는다 ───────────────────────────────────────
+ * `positive` 에 든 수는 0 보다 커야 한다. 라벨에 수량이 없는 것이 정상인 현장이 있는데(한 통·한
+ * 팔레트), 그때 **비워서** 말한다 — 0 으로 실으면 받는 쪽에서 「0개」와 「모른다」가 같아지고,
+ * 소요량 집계가 조용히 틀린다.
+ *
+ * 없는 필드는 `required` 가 아니면 그냥 없는 것이다. 이 함수가 채워 주지 않는다.
+ */
+function shapeErrors(where, row, shape) {
+    if (!shape)
+        return [];
+    const errors = [];
+    for (const f of shape.required ?? []) {
+        const v = row[f];
+        const empty = v === undefined || v === null || (typeof v === 'string' && !v.trim());
+        if (empty)
+            errors.push(`${where}.${f} 가 없다 — 계약이 요구하는 이름이다`);
+    }
+    for (const [f, t] of Object.entries(shape.fields ?? {})) {
+        const v = row[f];
+        if (v === undefined || v === null)
+            continue;
+        if (t === 'number' && (typeof v !== 'number' || !Number.isFinite(v))) {
+            errors.push(`${where}.${f} 가 수가 아니다: ${JSON.stringify(v)}`);
+        }
+        else if (t !== 'number' && typeof v !== t) {
+            errors.push(`${where}.${f} 가 ${t} 가 아니다: ${JSON.stringify(v)}`);
+        }
+    }
+    for (const [f, allowed] of Object.entries(shape.enums ?? {})) {
+        const v = row[f];
+        if (v === undefined || v === null)
+            continue;
+        if (!allowed.includes(String(v))) {
+            errors.push(`${where}.${f} 에 계약에 없는 낱말이 왔다: ${JSON.stringify(v)} (${allowed.join(' · ')})`);
+        }
+    }
+    for (const f of shape.positive ?? []) {
+        const v = row[f];
+        /* 없는 것은 「모른다」다 — 여기서 막지 않는다. 위 `required` 가 필요하면 거기서 막는다. */
+        if (v === undefined || v === null)
+            continue;
+        if (typeof v !== 'number' || !(v > 0)) {
+            errors.push(`${where}.${f} 가 0 이하다: ${JSON.stringify(v)} — 모르는 수량은 0 이 아니라 비워서 말한다`);
+        }
+    }
+    return errors;
+}
 /**
  * 닫아 둔 낱말과 그 이유.
  *  · 작업 상태 — 성과 폴드가 `completed`·`in-progress` 로 갈린다(`kpi-fold`).
@@ -72,6 +124,27 @@ const SPECS = {
             startedAtSimMs: 'number', outcome: 'string', priority: 'number', startTime: 'string', endTime: 'string',
             materialActual: 'object[]', recordTime: 'string'
         },
+        /*
+         * **자재 줄의 안쪽** — 계약의 `MaterialActual` 그대로다.
+         *
+         * `definitionId` 를 요구하는 이유: 이 이름이 없으면 그 줄이 무엇을 가리키는지 아무도 모른다.
+         * 실제로 `materialDefinitionId` 로 온 줄이 저널에 앉았고, 계약의 타입으로 읽으면 비어 있었다.
+         *
+         * `quantity` 를 `positive` 에 두는 이유: 「모른다」는 **비워서** 말한다. 0 으로 실으면 받는
+         * 쪽에서 「0개」와 구별되지 않고, 소요량 집계가 조용히 틀린다.
+         *
+         * `uom` 은 요구하지 않는다 — 계약에서 선택이다(§`MaterialActual`). ERP 경로는 요구하는데
+         * 그것은 **그 경로의 규칙**이다(정산에 단위 없는 수량을 쓸 수 없다). 커널이 그 규칙을 통째로
+         * 물려받으면 단위를 모르는 현장의 사실이 통째로 거절된다.
+         */
+        shapes: {
+            materialActual: {
+                required: ['definitionId', 'use'],
+                fields: { definitionId: 'string', lotId: 'string', quantity: 'number', uom: 'string' },
+                enums: { use: MATERIAL_ACTUAL_USE },
+                positive: ['quantity']
+            }
+        },
         enums: {
             status: TASK_STATUS,
             intent: ['transport', 'process', 'dwell'],
@@ -428,6 +501,7 @@ export function ingestOperationalRecords(records, opts) {
                         errors.push(`${kind}.${name} 가 객체가 아니다: ${JSON.stringify(v)}`);
                         break;
                     }
+                    errors.push(...shapeErrors(`${kind}.${name}`, v, spec.shapes?.[name]));
                     data[name] = { ...v };
                     break;
                 }
@@ -436,6 +510,7 @@ export function ingestOperationalRecords(records, opts) {
                         errors.push(`${kind}.${name} 가 객체 배열이 아니다: ${JSON.stringify(v)}`);
                         break;
                     }
+                    v.forEach((x, i) => errors.push(...shapeErrors(`${kind}.${name}[${i}]`, x, spec.shapes?.[name])));
                     data[name] = v.map(x => ({ ...x }));
                     break;
                 }

package/dist-cjs/index.cjs

@@ -50,6 +50,7 @@ __export(index_exports, {
   GUARD_PRAGMA: () => GUARD_PRAGMA,
   ILMD_ATTR: () => ILMD_ATTR,
   LOCATION_SATURATION_NEAR: () => LOCATION_SATURATION_NEAR,
+  MATERIAL_ACTUAL_USE: () => MATERIAL_ACTUAL_USE,
   MATERIAL_PROPERTY: () => MATERIAL_PROPERTY,
   MES_BIZSTEP: () => MES_BIZSTEP,
   MES_COMMANDS: () => MES_COMMANDS,
@@ -95,6 +96,7 @@ __export(index_exports, {
   checkSequenceRun: () => checkSequenceRun,
   classClosure: () => classClosure,
   classIdentifierViolation: () => classIdentifierViolation,
+  classUri: () => classUri,
   commandFromSpec: () => commandFromSpec,
   commandSpecGaps: () => commandSpecGaps,
   commandTypeOf: () => commandTypeOf,
@@ -620,8 +622,8 @@ function dueStatusOf(x, nowIso) {
   if (!Number.isFinite(due) || !Number.isFinite(now)) return void 0;
   return now > due ? "late" : "on-time";
 }
-function subLotIdOf(classUri, location) {
-  return `${classUri}@${location}`;
+function subLotIdOf(classUri2, location) {
+  return `${classUri2}@${location}`;
 }
 function itemKeyOf(item) {
   return item.subLotId ?? item.epc;
@@ -1032,6 +1034,7 @@ function isFailureStatus(value) {
 function isPlannedStopStatus(value) {
   return normalizeEquipmentStatus(value) === "planned-stop";
 }
+var MATERIAL_ACTUAL_USE = ["consumed", "produced"];
 var CMD = {
   orderHold: "order.hold",
   orderResume: "order.resume",
@@ -2791,14 +2794,27 @@ function gdtiUri(companyPrefix, docType, serial) {
 function objectUri(namespace, objId) {
   return underNamespace(namespace, "obj", objId);
 }
+function classUri(namespace, classId) {
+  return underNamespace(namespace, "class", classId);
+}
 function bizTransactionUri(namespace, transId) {
   return underNamespace(namespace, "bt", transId);
 }
+var STRUCTURE_BREAKING = /[%/:?# ]/g;
+var PERCENT_ENCODED = {
+  "%": "%25",
+  "/": "%2F",
+  ":": "%3A",
+  "?": "%3F",
+  "#": "%23",
+  " ": "%20"
+};
 function underNamespace(namespace, marker, id) {
   const ns = namespace?.trim();
   if (!ns) return void 0;
-  const v = String(id);
-  if (!v || v.includes("/") || v.includes(":")) return void 0;
+  const raw = String(id);
+  if (!raw) return void 0;
+  const v = raw.replace(STRUCTURE_BREAKING, (c) => PERCENT_ENCODED[c]);
   if (/^https?:\/\/[^/\s]+/.test(ns)) return `${ns.replace(/\/+$/, "")}/${marker}/${v}`;
   if (/^urn:epc(global)?:/.test(ns)) return void 0;
   if (/^urn:[^:\s]+/.test(ns)) return `${ns.replace(/:+$/, "")}:${marker}:${v}`;
@@ -2877,7 +2893,7 @@ var EPC_CLASS_PREFIXES = ["urn:epc:idpat:", "urn:epc:class:"];
 var DL_CANONICAL = "https://id.gs1.org/";
 var CBV_URL_CLASS = /^https?:\/\/[^/\s]+\/(?:[^/\s]+\/)*class\/[^/\s]+$/;
 var CBV_URN_CLASS = /^urn:[^:\s]+:(?:[^:\s]+:)*class:[^:\s]+$/;
-var GS1_KEY_DIGITS = { sgtin: 13, sscc: 17, grai: 12, gdti: 12 };
+var GS1_KEY_DIGITS = { sgtin: 13, lgtin: 13, sscc: 17, grai: 12, gdti: 12, sgln: 12 };
 function gs1KeyDigitViolation(uri) {
   if (!uri) return void 0;
   const m = /^urn:epc:(?:id|idpat|class):([a-z]+):([^:]+)$/.exec(uri);
@@ -3257,6 +3273,39 @@ function readEpochMs(raw) {
 }
 
 // src/operational-ingest.ts
+function shapeErrors(where, row, shape) {
+  if (!shape) return [];
+  const errors = [];
+  for (const f of shape.required ?? []) {
+    const v = row[f];
+    const empty = v === void 0 || v === null || typeof v === "string" && !v.trim();
+    if (empty) errors.push(`${where}.${f} \uAC00 \uC5C6\uB2E4 \u2014 \uACC4\uC57D\uC774 \uC694\uAD6C\uD558\uB294 \uC774\uB984\uC774\uB2E4`);
+  }
+  for (const [f, t] of Object.entries(shape.fields ?? {})) {
+    const v = row[f];
+    if (v === void 0 || v === null) continue;
+    if (t === "number" && (typeof v !== "number" || !Number.isFinite(v))) {
+      errors.push(`${where}.${f} \uAC00 \uC218\uAC00 \uC544\uB2C8\uB2E4: ${JSON.stringify(v)}`);
+    } else if (t !== "number" && typeof v !== t) {
+      errors.push(`${where}.${f} \uAC00 ${t} \uAC00 \uC544\uB2C8\uB2E4: ${JSON.stringify(v)}`);
+    }
+  }
+  for (const [f, allowed] of Object.entries(shape.enums ?? {})) {
+    const v = row[f];
+    if (v === void 0 || v === null) continue;
+    if (!allowed.includes(String(v))) {
+      errors.push(`${where}.${f} \uC5D0 \uACC4\uC57D\uC5D0 \uC5C6\uB294 \uB0B1\uB9D0\uC774 \uC654\uB2E4: ${JSON.stringify(v)} (${allowed.join(" \xB7 ")})`);
+    }
+  }
+  for (const f of shape.positive ?? []) {
+    const v = row[f];
+    if (v === void 0 || v === null) continue;
+    if (typeof v !== "number" || !(v > 0)) {
+      errors.push(`${where}.${f} \uAC00 0 \uC774\uD558\uB2E4: ${JSON.stringify(v)} \u2014 \uBAA8\uB974\uB294 \uC218\uB7C9\uC740 0 \uC774 \uC544\uB2C8\uB77C \uBE44\uC6CC\uC11C \uB9D0\uD55C\uB2E4`);
+    }
+  }
+  return errors;
+}
 var TASK_STATUS = ["created", "assigned", "in-progress", "completed"];
 var EQUIPMENT_STATUS2 = ["idle", "busy", "down", "setup", "planned-stop"];
 var PERSON_STATUS = ["idle", "busy"];
@@ -3293,6 +3342,27 @@ var SPECS = {
       materialActual: "object[]",
       recordTime: "string"
     },
+    /*
+     * **자재 줄의 안쪽** — 계약의 `MaterialActual` 그대로다.
+     *
+     * `definitionId` 를 요구하는 이유: 이 이름이 없으면 그 줄이 무엇을 가리키는지 아무도 모른다.
+     * 실제로 `materialDefinitionId` 로 온 줄이 저널에 앉았고, 계약의 타입으로 읽으면 비어 있었다.
+     *
+     * `quantity` 를 `positive` 에 두는 이유: 「모른다」는 **비워서** 말한다. 0 으로 실으면 받는
+     * 쪽에서 「0개」와 구별되지 않고, 소요량 집계가 조용히 틀린다.
+     *
+     * `uom` 은 요구하지 않는다 — 계약에서 선택이다(§`MaterialActual`). ERP 경로는 요구하는데
+     * 그것은 **그 경로의 규칙**이다(정산에 단위 없는 수량을 쓸 수 없다). 커널이 그 규칙을 통째로
+     * 물려받으면 단위를 모르는 현장의 사실이 통째로 거절된다.
+     */
+    shapes: {
+      materialActual: {
+        required: ["definitionId", "use"],
+        fields: { definitionId: "string", lotId: "string", quantity: "number", uom: "string" },
+        enums: { use: MATERIAL_ACTUAL_USE },
+        positive: ["quantity"]
+      }
+    },
     enums: {
       status: TASK_STATUS,
       intent: ["transport", "process", "dwell"],
@@ -3675,6 +3745,7 @@ function ingestOperationalRecords(records, opts) {
             errors.push(`${kind}.${name} \uAC00 \uAC1D\uCCB4\uAC00 \uC544\uB2C8\uB2E4: ${JSON.stringify(v)}`);
             break;
           }
+          errors.push(...shapeErrors(`${kind}.${name}`, v, spec.shapes?.[name]));
           data[name] = { ...v };
           break;
         }
@@ -3683,6 +3754,9 @@ function ingestOperationalRecords(records, opts) {
             errors.push(`${kind}.${name} \uAC00 \uAC1D\uCCB4 \uBC30\uC5F4\uC774 \uC544\uB2C8\uB2E4: ${JSON.stringify(v)}`);
             break;
           }
+          v.forEach(
+            (x, i) => errors.push(...shapeErrors(`${kind}.${name}[${i}]`, x, spec.shapes?.[name]))
+          );
           data[name] = v.map((x) => ({ ...x }));
           break;
         }
@@ -4233,6 +4307,7 @@ function commandSpecGaps(specs, command) {
   GUARD_PRAGMA,
   ILMD_ATTR,
   LOCATION_SATURATION_NEAR,
+  MATERIAL_ACTUAL_USE,
   MATERIAL_PROPERTY,
   MES_BIZSTEP,
   MES_COMMANDS,
@@ -4278,6 +4353,7 @@ function commandSpecGaps(specs, command) {
   checkSequenceRun,
   classClosure,
   classIdentifierViolation,
+  classUri,
   commandFromSpec,
   commandSpecGaps,
   commandTypeOf,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operato/ops-contract",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "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",