@operato/ops-contract 0.9.3 → 0.9.5

package/dist/contract.d.ts

@@ -3172,6 +3172,38 @@ export declare const EQUIPMENT_STATUS: readonly ["busy", "setup", "down", "idle"
 export type EquipmentStatus = (typeof EQUIPMENT_STATUS)[number];
 /** 선언된 상태인가. */
 export declare function isEquipmentStatus(value: unknown): value is EquipmentStatus;
+/**
+ * **ISA-95 의 네 자원** — 「무엇이 자원인가」를 한 자리에서 말한다.
+ *
+ * ── 왜 필요한가 (MES 레인이 물음, 2026-09-05) ──────────────────────────────
+ * 계약이 네 자원을 여러 곳에서 다루는데, **넷이라고 말하는 값이 없었다.** 그래서 소비처가 저마다
+ * 손으로 든다 — 자원 하나에 걸린 것을 한자리에 보이는 화면(360)이 종류마다 무엇을 물을지 정하려면
+ * 그 목록이 필요하고, 지금은 화면마다 적게 된다.
+ *
+ * 이미 갈라지기 시작했다: `CapacityAxis`(§`capacity.ts`)가 넷을 손으로 들고 있다.
+ * `EQUIPMENT_STATUS` 가 정확히 같은 자리였다 — 계약에 있는데 소비처가 따로 선언하고 있었다.
+ *
+ * ── 왜 넷만인가 ────────────────────────────────────────────────────────────
+ * 표준이 넷이라고 말한다(ISA-95 Part 1 §5: Personnel · Equipment · Material · Physical Asset).
+ * 자리·공정·로트를 여기 섞고 싶은 힘이 있는데 — 화면이 그것들도 보여 주므로 — **섞으면 이 상수가
+ * ISA-95 를 말하지 않게 된다.** 그러면 다음 사람이 이것을 근거로 쓸 수 없다.
+ *
+ *   자리   자원을 **담는 곳**이다. 자원이 아니다
+ *   로트   자재의 **개체**다. 자재 종류와 다른 층이다
+ *   공정   자원을 **쓰는 일**이다
+ *
+ * 화면이 그 셋도 필요하면 다른 이름으로 든다. 이 목록은 「무엇이 자원인가」에만 답한다.
+ *
+ * ── `CapacityAxis` 와 다르다 ───────────────────────────────────────────────
+ * 그것은 **제약이 걸린 축**이고(무엇을 늘려야 하는가), 자리가 들어간다 — 자리가 모자라도 못 돌기
+ * 때문이다. 자재는 없다(늘린다고 지금 나오는 것이 아니다). 둘은 겹치지만 같지 않다.
+ *
+ * 합치면 한 값이 두 물음에 답하게 되고, 그러면 어느 쪽 뜻으로 읽어야 하는지 알 수 없다.
+ */
+export declare const RESOURCE_KIND: readonly ["equipment", "personnel", "material", "asset"];
+export type ResourceKind = (typeof RESOURCE_KIND)[number];
+/** 선언된 자원 종류인가. */
+export declare function isResourceKind(value: unknown): value is ResourceKind;
 /**
  * 원본의 낱말을 우리 상태로 옮긴다 — **모르면 `undefined` 다.**
  *
@@ -3269,11 +3301,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

@@ -1276,6 +1276,39 @@ export const EQUIPMENT_STATUS = ['busy', 'setup', 'down', 'idle', 'planned-stop'
 export function isEquipmentStatus(value) {
     return typeof value === 'string' && EQUIPMENT_STATUS.includes(value);
 }
+/**
+ * **ISA-95 의 네 자원** — 「무엇이 자원인가」를 한 자리에서 말한다.
+ *
+ * ── 왜 필요한가 (MES 레인이 물음, 2026-09-05) ──────────────────────────────
+ * 계약이 네 자원을 여러 곳에서 다루는데, **넷이라고 말하는 값이 없었다.** 그래서 소비처가 저마다
+ * 손으로 든다 — 자원 하나에 걸린 것을 한자리에 보이는 화면(360)이 종류마다 무엇을 물을지 정하려면
+ * 그 목록이 필요하고, 지금은 화면마다 적게 된다.
+ *
+ * 이미 갈라지기 시작했다: `CapacityAxis`(§`capacity.ts`)가 넷을 손으로 들고 있다.
+ * `EQUIPMENT_STATUS` 가 정확히 같은 자리였다 — 계약에 있는데 소비처가 따로 선언하고 있었다.
+ *
+ * ── 왜 넷만인가 ────────────────────────────────────────────────────────────
+ * 표준이 넷이라고 말한다(ISA-95 Part 1 §5: Personnel · Equipment · Material · Physical Asset).
+ * 자리·공정·로트를 여기 섞고 싶은 힘이 있는데 — 화면이 그것들도 보여 주므로 — **섞으면 이 상수가
+ * ISA-95 를 말하지 않게 된다.** 그러면 다음 사람이 이것을 근거로 쓸 수 없다.
+ *
+ *   자리   자원을 **담는 곳**이다. 자원이 아니다
+ *   로트   자재의 **개체**다. 자재 종류와 다른 층이다
+ *   공정   자원을 **쓰는 일**이다
+ *
+ * 화면이 그 셋도 필요하면 다른 이름으로 든다. 이 목록은 「무엇이 자원인가」에만 답한다.
+ *
+ * ── `CapacityAxis` 와 다르다 ───────────────────────────────────────────────
+ * 그것은 **제약이 걸린 축**이고(무엇을 늘려야 하는가), 자리가 들어간다 — 자리가 모자라도 못 돌기
+ * 때문이다. 자재는 없다(늘린다고 지금 나오는 것이 아니다). 둘은 겹치지만 같지 않다.
+ *
+ * 합치면 한 값이 두 물음에 답하게 되고, 그러면 어느 쪽 뜻으로 읽어야 하는지 알 수 없다.
+ */
+export const RESOURCE_KIND = ['equipment', 'personnel', 'material', 'asset'];
+/** 선언된 자원 종류인가. */
+export function isResourceKind(value) {
+    return typeof value === 'string' && RESOURCE_KIND.includes(value);
+}
 /**
  * 원본의 낱말을 우리 상태로 옮긴다 — **모르면 `undefined` 다.**
  *
@@ -1318,6 +1351,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/domain-catalog.d.ts

@@ -170,6 +170,25 @@ export type TwinRelationTarget = {
     kind: 'external';
     entity: string;
 };
+/**
+ * **그 관계가 가리키는 것이 언제의 일인가** — 화면의 판단이 여기서 갈린다.
+ *
+ * ── 왜 필요한가 (MES 레인이 실측으로 올림, 2026-09-05) ─────────────────────
+ * 설비 하나에 걸린 것을 한자리에 보이면, 들어오는 관계라도 뜻이 갈린다.
+ *
+ *   past       이미 일어났다 — 세워도 안 바뀐다        실적 · 상태 구간
+ *   future     아직이다 — 세우면 이것이 걸린다          정비 계획 · 지시
+ *   standing   시간이 없는 사실                        등급 · 붙박인 자리 · 종류
+ *
+ * 한 묶음에 담으면 **「걸린 것이 열」인데 아홉이 지난 일인 경우와 아홉이 앞의 일인 경우가 같아
+ * 보인다.** 「이 설비를 세워도 되나」의 답이 정반대인 두 상황이다.
+ *
+ * ── 왜 `via` 로 가르면 안 되나 ──────────────────────────────────────────────
+ * `via` 는 i18n 키다. **「이것이 지난 일인가」를 말하지 않는다.** 화면이 키 이름을 보고 짐작하게
+ * 되고, 축이 하나 늘 때 한 화면만 따라간다. 읽는 곳은 제품마다여도 **무엇을 아는지는 한 벌**이어야
+ * 한다.
+ */
+export type RelationTense = 'past' | 'future' | 'standing';
 export interface TwinRelationInfo {
     /** 출발 축. */
     from: string;
@@ -183,7 +202,27 @@ export interface TwinRelationInfo {
     via: string;
     /** 없을 수 있는 참조인가. `false` 인데 비면 **끊어진 참조**로 보고한다. */
     optional?: boolean;
+    /**
+     * 언제의 일인가. **없으면 「선언이 말하지 않았다」** — `standing` 이 아니다.
+     *
+     * 기본값을 두고 싶은 힘이 있는데 두면 거짓이 된다. 예를 들어 `tasks.resourceRef → equipment` 는
+     * **그 작업이 끝났는지에 따라** 과거이기도 미래이기도 하다. 선언이 답할 수 없는 자리이고, 거기
+     * `standing` 을 씌우면 「시간이 없는 사실」이라고 잘못 말하게 된다.
+     *
+     * 그러니 말할 수 있는 관계만 말한다. 안 말한 것을 화면이 시간으로 묶으려 하면 안 된다.
+     */
+    tense?: RelationTense;
 }
+/**
+ * 그 관계가 언제의 일인가 — **모르면 `undefined`.**
+ *
+ * 소비처가 저마다 `?? 'standing'` 을 적지 않게 한 자리에 둔다. 그리고 그 기본값을 **주지 않는
+ * 것**이 이 함수의 요점이다 — 선언이 말하지 않은 것을 「시간이 없는 사실」로 바꾸면 화면이 모르는
+ * 것을 아는 척한다.
+ *
+ * 시간으로 묶는 화면은 `undefined` 인 것을 **묶지 않고 그대로 둔다.**
+ */
+export declare function tenseOf(r: Pick<TwinRelationInfo, 'tense'> | undefined): RelationTense | undefined;
 /** 관계 전체 — 지도의 선과 항목의 이웃이 여기서 나온다(화면은 이 목록을 갖지 않는다). */
 export declare const TWIN_RELATIONS: TwinRelationInfo[];
 export type TwinObservationKind = 

package/dist/domain-catalog.js

@@ -149,6 +149,18 @@ export const TWIN_AXES = [
     { axis: 'demandWindows', path: 'energy.closed', idField: 'startMs', label: 'twin.axis.demandWindows', kind: 'instance',
         source: 'state', historical: true, standardClass: {}, systems: ['ems'] }
 ];
+/**
+ * 그 관계가 언제의 일인가 — **모르면 `undefined`.**
+ *
+ * 소비처가 저마다 `?? 'standing'` 을 적지 않게 한 자리에 둔다. 그리고 그 기본값을 **주지 않는
+ * 것**이 이 함수의 요점이다 — 선언이 말하지 않은 것을 「시간이 없는 사실」로 바꾸면 화면이 모르는
+ * 것을 아는 척한다.
+ *
+ * 시간으로 묶는 화면은 `undefined` 인 것을 **묶지 않고 그대로 둔다.**
+ */
+export function tenseOf(r) {
+    return r?.tense;
+}
 /** 관계 전체 — 지도의 선과 항목의 이웃이 여기서 나온다(화면은 이 목록을 갖지 않는다). */
 export const TWIN_RELATIONS = [
     /* 자리가 속한 구역 — **board 밖**(호스트의 `TwinArea`). 해소는 호스트가 한다. */

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/reliability.d.ts

@@ -42,3 +42,38 @@ export interface Mtbf {
  * 사라지고, 그러면 이 수가 실제보다 좋아진다 — 자료가 나쁠수록 수가 좋아지는 쪽은 두지 않는다.
  */
 export declare function computeMtbf(input: MtbfInput): Mtbf;
+export interface MttrInput {
+    /** 어느 설비의. */
+    equipmentId: string;
+    /** 그 설비의 상태 구간들. 순서는 상관없다 — 여기서 시각으로 세운다. */
+    periods: readonly ReliabilityPeriod[];
+}
+/** 낼 수 없는 이유 — 「0」이나 「무한」으로 답하지 않는다. */
+export type MttrMissing = 
+/** 고장이 없다 — 나눌 수가 0이다. 고칠 일이 없었던 것이지 복구가 빠른 것이 아니다. */
+'no-failure'
+/** 모르는 상태 낱말이 있다 — 조용히 빼면 고장이 사라진다. */
+ | 'unknown-status'
+/** 길이가 없거나 시각을 읽을 수 없는 구간이 있다. */
+ | 'invalid-period';
+export interface Mttr {
+    equipmentId: string;
+    /** 평균 복구 시간(ms). **낼 수 없으면 없다.** */
+    mttrMs?: number;
+    /** 분자 — `down` 구간 길이의 합. */
+    downMs: number;
+    /** 분모 — **고장으로 들어간 횟수**(이어진 `down` 은 한 번). MTBF 와 같은 수다. */
+    failures: number;
+    /** 받은 `down` 구간의 수 — `failures` 와 다르면 이어진 것이 있었다. */
+    downPeriods: number;
+    /** 옮길 수 없던 상태 낱말들 — 무엇이 왔는지 말한다. */
+    unknownStatuses: string[];
+    missing: MttrMissing[];
+}
+/**
+ * 이 설비의 MTTR.
+ *
+ * **모르는 상태를 만나면 답하지 않는다.** MTBF 와 같은 이유다 — 그 구간이 고장이었다면 빼는 순간
+ * 복구 시간이 짧아 보인다. 자료가 나쁠수록 수가 좋아지는 쪽은 두지 않는다.
+ */
+export declare function computeMttr(input: MttrInput): Mttr;

package/dist/reliability.js

@@ -1,5 +1,8 @@
 /*
- * **MTBF** — ISO 22400-2. 고장 사이에 얼마나 돌았나.
+ * **MTBF · MTTR** — ISO 22400-2. 고장 사이에 얼마나 돌았나 · 고치는 데 얼마나 걸렸나.
+ *
+ * 표준이 둘을 **짝으로** 정의한다. 한쪽만 두면 소비처가 나머지를 자기 식으로 짓고, 그러면 같은
+ * 설비가 화면마다 다른 수를 갖는다 — 이 파일이 애초에 존재하는 이유가 그것이다.
  *
  * ── 왜 구간을 받나 (집계 값이 아니라) ────────────────────────────────────────
  * `computeMtbf(가동시간, 고장횟수)` 로 두면 **「고장 횟수」를 부르는 쪽이 센다.** 그러면 세는 방법이
@@ -42,15 +45,22 @@ const at = (t) => (typeof t === 'string' ? Date.parse(t) : NaN);
  * **모르는 상태를 만나면 답하지 않는다.** 빼고 계산하면 그 구간이 고장이었을 때 고장이 조용히
  * 사라지고, 그러면 이 수가 실제보다 좋아진다 — 자료가 나쁠수록 수가 좋아지는 쪽은 두지 않는다.
  */
-export function computeMtbf(input) {
-    const { equipmentId } = input;
-    const missing = [];
+/**
+ * 구간을 한 번 훑어 두 산출식이 쓸 것을 다 센다.
+ *
+ * **두 함수가 따로 걸으면 안 된다** — 「이어진 `down` 은 한 번」 규칙이 두 곳에 살게 되고, 한 곳만
+ * 고쳐지는 날 같은 설비의 MTBF 와 MTTR 이 서로 어긋난다. 그 둘은 같은 고장 횟수로 나눈 값이므로
+ * 어긋나면 둘 중 하나가 반드시 틀렸는데, 어느 쪽인지 아무도 모른다.
+ */
+function scanPeriods(periods) {
     const unknown = new Set();
     /* 시각으로 세운다 — 받은 순서를 믿지 않는다. 이어짐 판정이 순서에 걸린다. */
-    const sorted = [...(input.periods ?? [])]
+    const sorted = [...(periods ?? [])]
         .map(p => ({ status: normalizeEquipmentStatus(p?.status), said: String(p?.status ?? ''), from: at(p?.from), to: at(p?.to) }))
         .sort((a, b) => a.from - b.from);
     let operatingMs = 0;
+    /** 고친 시간의 합 — MTTR 의 분자. */
+    let downMs = 0;
     let failures = 0;
     let downPeriods = 0;
     let invalid = false;
@@ -74,6 +84,7 @@ export function computeMtbf(input) {
         if (p.status === 'busy')
             operatingMs += p.to - p.from;
         if (p.status === 'down') {
+            downMs += p.to - p.from;
             downPeriods++;
             if (!wasDown)
                 failures++;
@@ -83,23 +94,61 @@ export function computeMtbf(input) {
             wasDown = false;
         }
     }
-    if (invalid)
+    return { operatingMs, downMs, failures, downPeriods, unknownStatuses: [...unknown], invalid };
+}
+/**
+ * 이 설비의 MTBF.
+ *
+ * **모르는 상태를 만나면 답하지 않는다.** 빼고 계산하면 그 구간이 고장이었을 때 고장이 조용히
+ * 사라지고, 그러면 이 수가 실제보다 좋아진다 — 자료가 나쁠수록 수가 좋아지는 쪽은 두지 않는다.
+ */
+export function computeMtbf(input) {
+    const s = scanPeriods(input.periods);
+    const missing = [];
+    if (s.invalid)
         missing.push('invalid-period');
-    if (unknown.size)
+    if (s.unknownStatuses.length)
         missing.push('unknown-status');
-    if (operatingMs <= 0)
+    if (s.operatingMs <= 0)
         missing.push('no-operating-time');
-    if (failures === 0)
+    if (s.failures === 0)
+        missing.push('no-failure');
+    const out = {
+        equipmentId: input.equipmentId,
+        operatingMs: s.operatingMs,
+        failures: s.failures,
+        downPeriods: s.downPeriods,
+        unknownStatuses: s.unknownStatuses,
+        missing
+    };
+    if (missing.length)
+        return out;
+    return { ...out, mtbfMs: s.operatingMs / s.failures };
+}
+/**
+ * 이 설비의 MTTR.
+ *
+ * **모르는 상태를 만나면 답하지 않는다.** MTBF 와 같은 이유다 — 그 구간이 고장이었다면 빼는 순간
+ * 복구 시간이 짧아 보인다. 자료가 나쁠수록 수가 좋아지는 쪽은 두지 않는다.
+ */
+export function computeMttr(input) {
+    const s = scanPeriods(input.periods);
+    const missing = [];
+    if (s.invalid)
+        missing.push('invalid-period');
+    if (s.unknownStatuses.length)
+        missing.push('unknown-status');
+    if (s.failures === 0)
         missing.push('no-failure');
     const out = {
-        equipmentId,
-        operatingMs,
-        failures,
-        downPeriods,
-        unknownStatuses: [...unknown],
+        equipmentId: input.equipmentId,
+        downMs: s.downMs,
+        failures: s.failures,
+        downPeriods: s.downPeriods,
+        unknownStatuses: s.unknownStatuses,
         missing
     };
     if (missing.length)
         return out;
-    return { ...out, mtbfMs: operatingMs / failures };
+    return { ...out, mttrMs: s.downMs / s.failures };
 }

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,
@@ -61,6 +62,7 @@ __export(index_exports, {
   OP_PARAM: () => OP_PARAM,
   ORDER_TERMINAL_STATUS: () => ORDER_TERMINAL_STATUS,
   PRIORITY_UNSET: () => PRIORITY_UNSET,
+  RESOURCE_KIND: () => RESOURCE_KIND,
   RETIRED_VOCABULARY: () => RETIRED_VOCABULARY,
   SCHEDULE_STATUS: () => SCHEDULE_STATUS,
   TWIN_AXES: () => TWIN_AXES,
@@ -95,12 +97,14 @@ __export(index_exports, {
   checkSequenceRun: () => checkSequenceRun,
   classClosure: () => classClosure,
   classIdentifierViolation: () => classIdentifierViolation,
+  classUri: () => classUri,
   commandFromSpec: () => commandFromSpec,
   commandSpecGaps: () => commandSpecGaps,
   commandTypeOf: () => commandTypeOf,
   commandsOf: () => commandsOf,
   computeFirstPassYield: () => computeFirstPassYield,
   computeMtbf: () => computeMtbf,
+  computeMttr: () => computeMttr,
   computeOee: () => computeOee,
   conversionFactorOf: () => conversionFactorOf,
   criterionSaysNothing: () => criterionSaysNothing,
@@ -149,6 +153,7 @@ __export(index_exports, {
   isOperationalRecord: () => isOperationalRecord,
   isOrderTerminal: () => isOrderTerminal,
   isPlannedStopStatus: () => isPlannedStopStatus,
+  isResourceKind: () => isResourceKind,
   isTransformationRecord: () => isTransformationRecord,
   isoDurationHours: () => isoDurationHours,
   itemKeyOf: () => itemKeyOf,
@@ -201,6 +206,7 @@ __export(index_exports, {
   ssccUri: () => ssccUri,
   stateFieldsOf: () => stateFieldsOf,
   subLotIdOf: () => subLotIdOf,
+  tenseOf: () => tenseOf,
   testEvidenceGaps: () => testEvidenceGaps,
   testPassedAt: () => testPassedAt,
   transactionEvent: () => transactionEvent,
@@ -620,8 +626,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;
@@ -1022,6 +1028,10 @@ var EQUIPMENT_STATUS = ["busy", "setup", "down", "idle", "planned-stop"];
 function isEquipmentStatus(value) {
   return typeof value === "string" && EQUIPMENT_STATUS.includes(value);
 }
+var RESOURCE_KIND = ["equipment", "personnel", "material", "asset"];
+function isResourceKind(value) {
+  return typeof value === "string" && RESOURCE_KIND.includes(value);
+}
 function normalizeEquipmentStatus(value) {
   const said = typeof value === "string" ? value.trim().toLowerCase() : "";
   return isEquipmentStatus(said) ? said : void 0;
@@ -1032,6 +1042,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",
@@ -1857,6 +1868,9 @@ var TWIN_AXES = [
     systems: ["ems"]
   }
 ];
+function tenseOf(r) {
+  return r?.tense;
+}
 var TWIN_RELATIONS = [
   /* 자리가 속한 구역 — **board 밖**(호스트의 `TwinArea`). 해소는 호스트가 한다. */
   { from: "locations", field: "parentId", target: { kind: "external", entity: "space.area" }, via: "twin.rel.area", optional: true },
@@ -2791,14 +2805,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 +2904,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 +3284,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 +3353,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 +3756,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 +3765,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;
         }
@@ -3996,12 +4081,11 @@ function rolledThroughputYield(steps) {
 
 // src/reliability.ts
 var at = (t) => typeof t === "string" ? Date.parse(t) : NaN;
-function computeMtbf(input) {
-  const { equipmentId } = input;
-  const missing = [];
+function scanPeriods(periods) {
   const unknown = /* @__PURE__ */ new Set();
-  const sorted = [...input.periods ?? []].map((p) => ({ status: normalizeEquipmentStatus(p?.status), said: String(p?.status ?? ""), from: at(p?.from), to: at(p?.to) })).sort((a, b) => a.from - b.from);
+  const sorted = [...periods ?? []].map((p) => ({ status: normalizeEquipmentStatus(p?.status), said: String(p?.status ?? ""), from: at(p?.from), to: at(p?.to) })).sort((a, b) => a.from - b.from);
   let operatingMs = 0;
+  let downMs = 0;
   let failures = 0;
   let downPeriods = 0;
   let invalid = false;
@@ -4018,6 +4102,7 @@ function computeMtbf(input) {
     }
     if (p.status === "busy") operatingMs += p.to - p.from;
     if (p.status === "down") {
+      downMs += p.to - p.from;
       downPeriods++;
       if (!wasDown) failures++;
       wasDown = true;
@@ -4025,20 +4110,42 @@ function computeMtbf(input) {
       wasDown = false;
     }
   }
-  if (invalid) missing.push("invalid-period");
-  if (unknown.size) missing.push("unknown-status");
-  if (operatingMs <= 0) missing.push("no-operating-time");
-  if (failures === 0) missing.push("no-failure");
+  return { operatingMs, downMs, failures, downPeriods, unknownStatuses: [...unknown], invalid };
+}
+function computeMtbf(input) {
+  const s = scanPeriods(input.periods);
+  const missing = [];
+  if (s.invalid) missing.push("invalid-period");
+  if (s.unknownStatuses.length) missing.push("unknown-status");
+  if (s.operatingMs <= 0) missing.push("no-operating-time");
+  if (s.failures === 0) missing.push("no-failure");
+  const out = {
+    equipmentId: input.equipmentId,
+    operatingMs: s.operatingMs,
+    failures: s.failures,
+    downPeriods: s.downPeriods,
+    unknownStatuses: s.unknownStatuses,
+    missing
+  };
+  if (missing.length) return out;
+  return { ...out, mtbfMs: s.operatingMs / s.failures };
+}
+function computeMttr(input) {
+  const s = scanPeriods(input.periods);
+  const missing = [];
+  if (s.invalid) missing.push("invalid-period");
+  if (s.unknownStatuses.length) missing.push("unknown-status");
+  if (s.failures === 0) missing.push("no-failure");
   const out = {
-    equipmentId,
-    operatingMs,
-    failures,
-    downPeriods,
-    unknownStatuses: [...unknown],
+    equipmentId: input.equipmentId,
+    downMs: s.downMs,
+    failures: s.failures,
+    downPeriods: s.downPeriods,
+    unknownStatuses: s.unknownStatuses,
     missing
   };
   if (missing.length) return out;
-  return { ...out, mtbfMs: operatingMs / failures };
+  return { ...out, mttrMs: s.downMs / s.failures };
 }
 
 // src/erp.ts
@@ -4233,6 +4340,7 @@ function commandSpecGaps(specs, command) {
   GUARD_PRAGMA,
   ILMD_ATTR,
   LOCATION_SATURATION_NEAR,
+  MATERIAL_ACTUAL_USE,
   MATERIAL_PROPERTY,
   MES_BIZSTEP,
   MES_COMMANDS,
@@ -4244,6 +4352,7 @@ function commandSpecGaps(specs, command) {
   OP_PARAM,
   ORDER_TERMINAL_STATUS,
   PRIORITY_UNSET,
+  RESOURCE_KIND,
   RETIRED_VOCABULARY,
   SCHEDULE_STATUS,
   TWIN_AXES,
@@ -4278,12 +4387,14 @@ function commandSpecGaps(specs, command) {
   checkSequenceRun,
   classClosure,
   classIdentifierViolation,
+  classUri,
   commandFromSpec,
   commandSpecGaps,
   commandTypeOf,
   commandsOf,
   computeFirstPassYield,
   computeMtbf,
+  computeMttr,
   computeOee,
   conversionFactorOf,
   criterionSaysNothing,
@@ -4332,6 +4443,7 @@ function commandSpecGaps(specs, command) {
   isOperationalRecord,
   isOrderTerminal,
   isPlannedStopStatus,
+  isResourceKind,
   isTransformationRecord,
   isoDurationHours,
   itemKeyOf,
@@ -4384,6 +4496,7 @@ function commandSpecGaps(specs, command) {
   ssccUri,
   stateFieldsOf,
   subLotIdOf,
+  tenseOf,
   testEvidenceGaps,
   testPassedAt,
   transactionEvent,

package/package.json

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