@operato/ops-contract 0.1.0 → 0.3.0

package/dist/canonical-record.d.ts

@@ -0,0 +1,86 @@
+/** 개체 관측 — 물건 하나가 어디서 무엇이 됐나. */
+export interface CanonicalRecord {
+    /**
+     * 개체 하나의 식별자. **`quantityList` 를 쓰면 없어도 된다** — 낱개 번호가 없는 자재(밀가루 3.5kg)는
+     * 개체가 없다. 둘 다 없으면 무엇을 관측했는지 말하지 않은 것이므로 커널 매핑이 거부한다.
+     */
+    epc?: string;
+    /**
+     * 클래스와 수량 — `{ epcClass, quantity, uom? }`. **잔량 절대값을 싣는다**(「얼마 뺐다」가 아니라
+     * 「얼마 남았다」). 그래야 사건 하나를 놓쳐도 다음 사건이 정답을 다시 말해 주고 오차가 쌓이지 않는다.
+     *
+     * 담김(`childQuantityList`)이 하루 먼저 이 자리를 받았다 — 그때와 같은 이유다. 원본이 비직렬 수량을
+     * 말할 길이 없어서, 그것이 주된 경로인 시스템(식품 제조 MES)은 라이브를 낼 수 없었다. 커널의
+     * 관측 리듀서는 처음부터 이 값을 읽었고 문만 없었다.
+     */
+    quantityList?: {
+        epcClass: string;
+        quantity?: number;
+        uom?: string;
+    }[];
+    action: string;
+    bizStep: string;
+    disposition?: string;
+    readPoint?: string;
+    bizLocation?: string;
+}
+/**
+ * 담김 관측 — **부모와 자식**으로 말한다. 자리 필드는 개체 관측과 같은 이름이다(문자열).
+ *
+ * 이름은 표준의 것을 그대로 쓴다(`parentID`·`childEPCs`) — 여기서 다시 지으면 매핑이 번역이 되고,
+ * 같은 사실에 두 어휘가 생긴다.
+ */
+/**
+ * 변환 관측 — **무엇으로 무엇이 되었나.** 입력과 출력이 **한 사실에 함께** 있어야 계보가 남는다.
+ *
+ * 따로 보내면(「이 로트가 없어졌다」와 「이 제품이 생겼다」) 그 둘을 이을 근거가 없다. 그래서 표준이
+ * 한 사건에 둘을 담고, 우리 레코드도 같은 모양이다.
+ *
+ * 이름은 **표준의 것을 그대로** 쓴다(`inputQuantityList` 등). 갈래 판정이 이 이름으로 이루어지므로
+ * 커넥터 낱말(`consumed`·`produced`)로 담으면 판정되지 않는다 — 커넥터가 정규 이름으로 담아 보내고
+ * 매핑은 그 안에서 값을 고른다.
+ *
+ * **없는 쪽은 필드를 만들지 않는다.** 빈 배열을 실으면 「없다」고 말하는 것이 된다. 소실(N→0)과
+ * 생성(0→N)도 표준이 인정하는 변환이다.
+ *
+ * `transformationID` 가 한 오더의 여러 단계를 잇는다 — 소비를 먼저 알고 산출을 나중에 알게 되는 원본에서
+ * 그 둘을 묶는 유일한 자리다.
+ */
+export interface CanonicalTransformationRecord {
+    /** 개체로 소비된 것. */
+    inputEPCList?: string[];
+    /** 클래스와 수량으로 소비된 것 — 로트 단위 소비가 이 자리다. */
+    inputQuantityList?: {
+        epcClass: string;
+        quantity?: number;
+        uom?: string;
+    }[];
+    outputEPCList?: string[];
+    outputQuantityList?: {
+        epcClass: string;
+        quantity?: number;
+        uom?: string;
+    }[];
+    /** 한 오더의 여러 단계를 잇는 식별자. */
+    transformationID?: string;
+    bizStep: string;
+    disposition?: string;
+    readPoint?: string;
+    bizLocation?: string;
+}
+export interface CanonicalAggregationRecord {
+    parentID: string;
+    /** 개체로 담긴 자식. 수량으로만 담겼으면 없다(둘 중 하나는 있어야 한다). */
+    childEPCs?: string[];
+    /** 수량으로 담긴 자식 — `{ epcClass, quantity, uom? }`. 값의 옳고 그름은 커널 검증이 본다. */
+    childQuantityList?: {
+        epcClass: string;
+        quantity?: number;
+        uom?: string;
+    }[];
+    action: string;
+    bizStep: string;
+    disposition?: string;
+    readPoint?: string;
+    bizLocation?: string;
+}

package/dist/canonical-record.js

@@ -0,0 +1 @@
+export {};

package/dist/contract.d.ts

@@ -394,7 +394,7 @@ export interface TestResult {
  * 함께 움직인다. 열린 문자열로 두지 않는 이유는, 처분이 **자원에 효과를 주기** 때문이다 — 커널이 모르는
  * 결정을 받으면 무엇을 해야 할지 알 수 없고, 그때 조용히 아무것도 하지 않는 것이 가장 나쁘다.
  */
-export declare const DISPOSITION_DECISION: readonly ["rework", "use-as-is", "scrap", "return-to-supplier", "hold"];
+export declare const DISPOSITION_DECISION: readonly ["rework", "repair", "use-as-is", "regrade", "scrap", "return-to-supplier", "hold"];
 export type DispositionDecision = (typeof DISPOSITION_DECISION)[number];
 /**
  * **부적합 처분** — `OP_EVENT.disposition` 의 데이터.
@@ -555,7 +555,7 @@ export interface TestSpecificationCriterion {
     /** 표준 `EvaluatedPropertyID` — 이 기준이 **무엇을 재어** 판정하나. 측정값과 짝을 맞추는 키다. */
     evaluatedPropertyId?: string;
 }
-export interface TestSpecification {
+export interface TestSpecification extends EffectivePeriod {
     /** 표준 `ID` — 자원의 `testSpecificationIds` 가 이 값을 가리킨다. */
     id: string;
     /** 표준 `Description`. i18n 키일 수 있다(사람 언어는 표현 계층이 렌더한다). */
@@ -3219,7 +3219,7 @@ export interface TwinModelDef {
      */
     identity?: IdentityDeclaration;
     /** parallelism = 동시 처리 수(LocationState.parallelism 참조). capacity 는 저장 용량. */
-    locations: {
+    locations: (EffectivePeriod & {
         id: string;
         type: string;
         capacity: number;
@@ -3227,7 +3227,7 @@ export interface TwinModelDef {
         parentId?: string;
         properties?: ResourceProperty[];
         testSpecificationIds?: TestSpecificationRefs;
-    }[];
+    })[];
     /**
      * 설비(설비). mtbfMs/mttrMs 지정 시 확률적 고장 모델 참여(OEE Availability 손실). 미지정=고장 없음.
      * `window` 지정 시 그 시간대에만 일한다(교대·가동시간) — 미지정이면 24시간 가용(기존 거동).

package/dist/contract.js

@@ -226,7 +226,32 @@ levelOfType) {
  * 함께 움직인다. 열린 문자열로 두지 않는 이유는, 처분이 **자원에 효과를 주기** 때문이다 — 커널이 모르는
  * 결정을 받으면 무엇을 해야 할지 알 수 없고, 그때 조용히 아무것도 하지 않는 것이 가장 나쁘다.
  */
-export const DISPOSITION_DECISION = ['rework', 'use-as-is', 'scrap', 'return-to-supplier', 'hold'];
+export const DISPOSITION_DECISION = [
+    /** 원 규격으로 되돌린다 — 공정에 다시 들어가고, 산출물은 원 품목이다. */
+    'rework',
+    /**
+     * 쓸 수 있게 만들되 **원 규격은 아니다** — 공정에 다시 들어가지만 산출물이 원 품목이 아니다.
+     *
+     * `rework` 와 나눈 이유는 이름이 아니라 **효과**다. 되돌린 것과 고쳐 쓴 것은 산출물의 정체성이
+     * 다르고, 그것을 한 낱말로 묶으면 계보가 「원 품목을 만들었다」고 거짓을 말한다.
+     */
+    'repair',
+    /** 그대로 쓴다 — 공정도 정체성도 바뀌지 않는다. */
+    'use-as-is',
+    /**
+     * **등급을 내려 다른 품목으로 판다** — 공정에 다시 들어가지 않고, 그 자리에서 품목 정의가 바뀐다.
+     *
+     * 다른 넷과 축이 다르다. 폐기도 특채도 아니고 **자재의 품목 자체가 달라진다**(GTIN 이 바뀐다).
+     * 식품·철강·섬유에서 일상이다.
+     */
+    'regrade',
+    /** 재고에서 뺀다. */
+    'scrap',
+    /** 공급자에게 돌려보낸다 — 재고에서 빠지되 폐기와 다른 사실이다. */
+    'return-to-supplier',
+    /** 아직 정하지 않았다 — 묶어 두고 쓰지 않는다. */
+    'hold'
+];
 /**
  * 이 시험 결과가 **이 시각에 유효한 합격인가.**
  *

package/dist/domain-definition.d.ts

@@ -1,3 +1,4 @@
+import type { EffectivePeriod } from './contract.ts';
 /** 표준 온톨로지 투영(열린 문자열 — 하드코딩 enum 금지). */
 /**
  * 표준 온톨로지 투영 — 이 개념을 각 표준이 무엇이라 부르나.
@@ -129,7 +130,7 @@ export interface DurationVariability {
  * 걸리나·얼마나 성공하나" 는 커널 소스의 상수(30·20·40초, 수율 0.8)였다. 그래서 현장마다 다른 값을
  * 데이터로 줄 방법이 없었고, 그 상수가 주목 신호(불량률 높음)까지 만들어 냈다.
  */
-export interface OperationDef {
+export interface OperationDef extends EffectivePeriod {
     key: string;
     label: string;
     intent: OperationIntent;

package/dist/domain-definition.js

@@ -3,7 +3,8 @@
  * 커널이 "무엇이 있고 어떻게 흐르나"(타입 + 공정 route/BOM)를 **데이터로** 받는 형식. zero-dep(자기 타입).
  *
  * 특정 공정이 커널 코드에 하드코딩되던 것을 이 데이터 계약으로 대체한다(design/plans/domain-catalog-layering.md).
- * 스토어 패키지 `@operato/twin-catalog` 가 이 타입을 import 해 스토어 메타(version/supplier)를 얹어 배포한다(catalog → kernel 의존).
+ * 스토어 패키지 `@operato/twin-catalog` 가 이 타입을 import type { EffectivePeriod } from './contract.ts'
+import 해 스토어 메타(version/supplier)를 얹어 배포한다(catalog → kernel 의존).
  * 표준 앵커: GS1 EPCIS 2.0(bizStep) · ISA-95(WorkCenter·OperationsDefinition·BOM) · ISO 55000(Asset).
  */
 /**

package/dist/index.d.ts

@@ -16,3 +16,5 @@ export * from './scenario-validate.ts';
 export * from './vocabulary.ts';
 export * from './wms-profile.ts';
 export * from './yms-profile.ts';
+export * from './canonical-record.ts';
+export * from './version.ts';

package/dist/index.js

@@ -37,3 +37,5 @@ export * from "./scenario-validate.js";
 export * from "./vocabulary.js";
 export * from "./wms-profile.js";
 export * from "./yms-profile.js";
+export * from "./canonical-record.js";
+export * from "./version.js";

package/dist/operational-ingest.d.ts

@@ -1,6 +1,6 @@
 import type { IngestResult } from './face2-adapter.ts';
 /** 이 문이 받는 여섯 가지 — 리듀서가 다루는 것과 같은 목록(주목 확인은 우리 안의 행위라 제외). */
-export type OperationalKind = 'task' | 'equipment' | 'person' | 'asset' | 'order' | 'quality' | 'test' | 'observation' | 'complete';
+export type OperationalKind = 'task' | 'equipment' | 'person' | 'asset' | 'order' | 'quality' | 'test' | 'disposition' | 'observation' | 'complete';
 /**
  * 정규 운영 레코드 — **델타의 필드 이름 + 시각(`at`)**.
  *

package/dist/operational-ingest.js

@@ -34,7 +34,7 @@
  * 모르는 필드는 **조용히 버리지 않고 거부한다.** `taskID` 처럼 한 글자 틀린 이름은 통과시키면 영원히
  * 보이지 않는 손실이 된다(이 문에는 아직 옛 발신자가 없어 호환 부담도 없다).
  */
-import { OP_EVENT } from "./contract.js";
+import { OP_EVENT, DISPOSITION_DECISION } from "./contract.js";
 /**
  * 닫아 둔 낱말과 그 이유.
  *  · 작업 상태 — 성과 폴드가 `completed`·`in-progress` 로 갈린다(`kpi-fold`).
@@ -130,6 +130,32 @@ const SPECS = {
      * `propertyMeasurements` 안쪽은 재검사하지 않는다 — 그 모양은 `PropertyMeasurement` 계약이고,
      * 여기서 두 번 지키면 두 벌이 된다(설비 `motion` 과 같은 규율).
      */
+    /*
+     * **부적합 처분** — 재고 판정을 받은 것을 어떻게 하기로 정했나.
+     *
+     * ── 이 통이 늦게 생긴 이유 (2026-08-30) ──────────────────────────────────
+     * 사건 이름(`OP_EVENT.disposition`)과 모양(`DispositionFact`)을 먼저 만들고 **여기로 오는 길을
+     * 내지 않았다.** 그래서 처분 사실을 보내면 어느 통도 아니어서 떨어진 목록에도 남지 않고 사라졌다.
+     * MES 전문가가 소스를 읽다 찾았다.
+     *
+     * 이 파일의 위 주석이 말한 부류 그대로다 — `OP_EVENT.test` 와 `OP_EVENT.observation` 이 같은 일을
+     * 겪었고 이번이 셋째다. **계약에 자리를 만드는 것과 그 자리로 가는 길을 내는 것은 다른 일이다.**
+     *
+     * ── 판정과 다른 사실이다 ─────────────────────────────────────────────────
+     * 근거가 된 판정(`specId`)을 가리킬 수 있지만 **필수가 아니다** — 판정 없이 현장 재량으로 빼는 일이
+     * 정상이다. 그래서 정체성은 처분 대상(`subjectId`)이다.
+     */
+    disposition: {
+        eventType: OP_EVENT.disposition,
+        identity: 'subjectId',
+        /* 무엇을 어떻게 하기로 했나 — 둘 중 하나가 없으면 그 결정은 아무 데도 붙지 못한다. */
+        required: ['subjectId', 'decision'],
+        fields: {
+            subjectId: 'string', decision: 'string', quantity: 'number', uom: 'string',
+            specId: 'string', decidedBy: 'string', reason: 'string', decidedAt: 'string', recordTime: 'string'
+        },
+        enums: { decision: DISPOSITION_DECISION }
+    },
     test: {
         eventType: OP_EVENT.test,
         identity: 'testableObjectId',
@@ -221,6 +247,15 @@ export function operationalKindOf(record) {
      */
     if (has('testableObjectId'))
         return 'test';
+    /*
+     * **처분** — 같은 부류가 또 났다(2026-08-30). `OP_EVENT.disposition` 을 계약에 내고 여기로 오는 길을
+     * 내지 않아, MES 가 보내면 어느 통도 아니어서 사라졌다. 위 주석이 적은 것이 **셋째**다.
+     *
+     * 시험 결과 뒤에 둔다 — 처분은 판정을 가리킬 수 있고(`specId`), 그때 정체성은 처분 대상이지
+     * 시험 대상이 아니다. 앞에 두면 판정에 딸린 처분이 시험으로 읽힌다.
+     */
+    if (has('subjectId') && has('decision'))
+        return 'disposition';
     /*
      * ── ★ **채널을 열고 또 길을 내지 않았다** (2026-08-24) ──────────────────────
      * `OP_EVENT.observation`(`location.measured`)을 내고 상태(`LocationState.observations`)와 조회

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const CONTRACT_VERSION = "0.3.0";

package/dist/version.js

@@ -0,0 +1,14 @@
+/*
+ * 이 계약의 **판**.
+ *
+ * ── 왜 내보내나 (2026-08-30) ─────────────────────────────────────────────
+ * 소비처가 「내가 어느 판의 계약을 지키고 있나」를 사실로 남겨야 한다. MES 의 아웃박스가 그 값을
+ * 레코드에 싣는데, 계약이 내보내지 않아 **상수로 손으로 적고 있었다.** `exports` 맵이 `package.json`
+ * 을 막아 런타임에 읽을 수도 없다.
+ *
+ * 손으로 적은 판은 계약이 올라갈 때 같이 올라가지 않는다. 그러면 그 값은 「지킨다고 말한 판」이지
+ * 「실제로 지킨 판」이 아니게 되고, 그것이 어긋난 날 아무도 모른다.
+ *
+ * **정본은 `package.json` 이다.** 이 값이 그것과 같은지는 시험이 지킨다(§`version-matches`).
+ */
+export const CONTRACT_VERSION = '0.3.0';

package/dist-cjs/index.cjs

@@ -27,6 +27,7 @@ __export(index_exports, {
   CAPABILITY_KEYS: () => CAPABILITY_KEYS,
   CBV_BIZSTEP: () => CBV_BIZSTEP,
   CMD: () => CMD,
+  CONTRACT_VERSION: () => CONTRACT_VERSION,
   DISP: () => DISP,
   DISPOSITION_DECISION: () => DISPOSITION_DECISION,
   DOMAIN_CATALOG: () => DOMAIN_CATALOG,
@@ -408,7 +409,32 @@ function hierarchyOf(s, levelOfType) {
     }
   };
 }
-var DISPOSITION_DECISION = ["rework", "use-as-is", "scrap", "return-to-supplier", "hold"];
+var DISPOSITION_DECISION = [
+  /** 원 규격으로 되돌린다 — 공정에 다시 들어가고, 산출물은 원 품목이다. */
+  "rework",
+  /**
+   * 쓸 수 있게 만들되 **원 규격은 아니다** — 공정에 다시 들어가지만 산출물이 원 품목이 아니다.
+   *
+   * `rework` 와 나눈 이유는 이름이 아니라 **효과**다. 되돌린 것과 고쳐 쓴 것은 산출물의 정체성이
+   * 다르고, 그것을 한 낱말로 묶으면 계보가 「원 품목을 만들었다」고 거짓을 말한다.
+   */
+  "repair",
+  /** 그대로 쓴다 — 공정도 정체성도 바뀌지 않는다. */
+  "use-as-is",
+  /**
+   * **등급을 내려 다른 품목으로 판다** — 공정에 다시 들어가지 않고, 그 자리에서 품목 정의가 바뀐다.
+   *
+   * 다른 넷과 축이 다르다. 폐기도 특채도 아니고 **자재의 품목 자체가 달라진다**(GTIN 이 바뀐다).
+   * 식품·철강·섬유에서 일상이다.
+   */
+  "regrade",
+  /** 재고에서 뺀다. */
+  "scrap",
+  /** 공급자에게 돌려보낸다 — 재고에서 빠지되 폐기와 다른 사실이다. */
+  "return-to-supplier",
+  /** 아직 정하지 않았다 — 묶어 두고 쓰지 않는다. */
+  "hold"
+];
 function testPassedAt(r, at) {
   if (r.result !== "pass") return false;
   if (!r.expiresAt || !at) return r.result === "pass";
@@ -3270,6 +3296,39 @@ var SPECS = {
    * `propertyMeasurements` 안쪽은 재검사하지 않는다 — 그 모양은 `PropertyMeasurement` 계약이고,
    * 여기서 두 번 지키면 두 벌이 된다(설비 `motion` 과 같은 규율).
    */
+  /*
+   * **부적합 처분** — 재고 판정을 받은 것을 어떻게 하기로 정했나.
+   *
+   * ── 이 통이 늦게 생긴 이유 (2026-08-30) ──────────────────────────────────
+   * 사건 이름(`OP_EVENT.disposition`)과 모양(`DispositionFact`)을 먼저 만들고 **여기로 오는 길을
+   * 내지 않았다.** 그래서 처분 사실을 보내면 어느 통도 아니어서 떨어진 목록에도 남지 않고 사라졌다.
+   * MES 전문가가 소스를 읽다 찾았다.
+   *
+   * 이 파일의 위 주석이 말한 부류 그대로다 — `OP_EVENT.test` 와 `OP_EVENT.observation` 이 같은 일을
+   * 겪었고 이번이 셋째다. **계약에 자리를 만드는 것과 그 자리로 가는 길을 내는 것은 다른 일이다.**
+   *
+   * ── 판정과 다른 사실이다 ─────────────────────────────────────────────────
+   * 근거가 된 판정(`specId`)을 가리킬 수 있지만 **필수가 아니다** — 판정 없이 현장 재량으로 빼는 일이
+   * 정상이다. 그래서 정체성은 처분 대상(`subjectId`)이다.
+   */
+  disposition: {
+    eventType: OP_EVENT.disposition,
+    identity: "subjectId",
+    /* 무엇을 어떻게 하기로 했나 — 둘 중 하나가 없으면 그 결정은 아무 데도 붙지 못한다. */
+    required: ["subjectId", "decision"],
+    fields: {
+      subjectId: "string",
+      decision: "string",
+      quantity: "number",
+      uom: "string",
+      specId: "string",
+      decidedBy: "string",
+      reason: "string",
+      decidedAt: "string",
+      recordTime: "string"
+    },
+    enums: { decision: DISPOSITION_DECISION }
+  },
   test: {
     eventType: OP_EVENT.test,
     identity: "testableObjectId",
@@ -3339,6 +3398,7 @@ function operationalKindOf(record) {
   if (has("taskId")) return "task";
   if (has("orderId")) return "order";
   if (has("testableObjectId")) return "test";
+  if (has("subjectId") && has("decision")) return "disposition";
   if (has("locationId") && has("propertyId")) return "observation";
   if (has("completeAxis")) return "complete";
   return void 0;
@@ -3609,6 +3669,9 @@ function retiredVocabularyIn(line) {
   }
   return hits;
 }
+
+// src/version.ts
+var CONTRACT_VERSION = "0.3.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BIZSTEP,
@@ -3619,6 +3682,7 @@ function retiredVocabularyIn(line) {
   CAPABILITY_KEYS,
   CBV_BIZSTEP,
   CMD,
+  CONTRACT_VERSION,
   DISP,
   DISPOSITION_DECISION,
   DOMAIN_CATALOG,

package/package.json

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