@operato/ops-contract 0.3.0 → 0.5.0

package/dist/contract.d.ts

@@ -1379,17 +1379,43 @@ export interface EquipmentMotion {
  * → OEE=(run/planned)×quality. 세 인자가 손실 위치(셋업·기아·불량)를 분해해 드러낸다.
  */
 export interface OeeMetrics {
-    availability: number;
-    performance: number;
-    quality: number;
-    overall: number;
+    /**
+     * ── 세 비율은 **없을 수 있다** (2026-08-30) ──────────────────────────────
+     *
+     * 예전에는 근거가 없을 때 `1` 을 냈다. 잰 구간이 없는데 「가동률 100%」가 되고, 만든 것이 하나도
+     * 없는데 「양품률 100%」가 된다. **없는 근거로 좋은 숫자를 만드는 것**이고, 사용자는 그것으로
+     * 판단한다.
+     *
+     * 없으면 답하지 않는다. 무엇이 없어서인지는 `missing` 이 말한다.
+     */
+    availability?: number;
+    performance?: number;
+    quality?: number;
+    overall?: number;
+    /** 값이 없는 이유 — 비면 셋 다 나왔다는 뜻이다. */
+    missing?: OeeMissing[];
     runMs: number;
     setupMs: number;
     downMs: number;
-    idleMs: number;
+    delayMs: number;
     goodCount: number;
     scrapCount: number;
 }
+/**
+ * OEE 값이 없는 이유.
+ *
+ * 「모름」과 「0」은 다르다. 계획 조업 시간을 모르면 가동률을 낼 수 없고, 그때 0 을 내면 설비가
+ * 놀고 있는 것처럼 보이고 1 을 내면 완벽한 것처럼 보인다. 둘 다 거짓이다.
+ */
+export type OeeMissing = 
+/** 계획 조업 시간(PBT)을 모른다 — 아직 아무것도 재지 않았거나 근무 캘린더가 없다. */
+'planned-busy-time'
+/** 품목당 표준 시간(PRI)이 선언되지 않았다 — 성능률의 분자를 만들 수 없다. */
+ | 'planned-run-time-per-item'
+/** 만든 것이 없다 — 양품률을 낼 대상이 없다. */
+ | 'produced-quantity'
+/** 실 생산 시간이 0 이다 — 성능률의 분모가 없다. */
+ | 'actual-production-time';
 export interface EquipmentState extends EffectivePeriod {
     id: string;
     kind: string;
@@ -2513,6 +2539,15 @@ export declare const OP_EVENT: {
      * 이 채널이 없으면 시험 결과는 **상태에만 있는 축**이 된다 — 재기동에서 사라지고, 폴드가 되살릴 수
      * 없고, 미러가 이어받지 못한다(§상태 ⊆ 이벤트).
      */
+    /**
+     * **마감된 설비 상태 구간** — 이 설비가 이 구간 동안 이 상태였다.
+     *
+     * 시점의 전이(`equipment.status`)와 다른 사실이다. 전이는 설비가 내고, 이것은 **사람이 나중에
+     * 적는다.** 자재 대기처럼 신호를 내지 않는 정지는 이 길로만 들어온다.
+     *
+     * ISO 22400-2 의 가동률 계산이 이 구간들을 읽는다.
+     */
+    readonly equipmentPeriod: "equipment.state.period";
     readonly test: "test.result";
     /**
      * **부적합 처분** — 재고 판정을 받은 것을 어떻게 하기로 정했나(재작업 · 특채 · 폐기 · 반품).

package/dist/contract.js

@@ -986,6 +986,15 @@ export const OP_EVENT = {
      * 이 채널이 없으면 시험 결과는 **상태에만 있는 축**이 된다 — 재기동에서 사라지고, 폴드가 되살릴 수
      * 없고, 미러가 이어받지 못한다(§상태 ⊆ 이벤트).
      */
+    /**
+     * **마감된 설비 상태 구간** — 이 설비가 이 구간 동안 이 상태였다.
+     *
+     * 시점의 전이(`equipment.status`)와 다른 사실이다. 전이는 설비가 내고, 이것은 **사람이 나중에
+     * 적는다.** 자재 대기처럼 신호를 내지 않는 정지는 이 길로만 들어온다.
+     *
+     * ISO 22400-2 의 가동률 계산이 이 구간들을 읽는다.
+     */
+    equipmentPeriod: 'equipment.state.period',
     test: 'test.result',
     /**
      * **부적합 처분** — 재고 판정을 받은 것을 어떻게 하기로 정했나(재작업 · 특채 · 폐기 · 반품).

package/dist/index.d.ts

@@ -18,3 +18,4 @@ export * from './wms-profile.ts';
 export * from './yms-profile.ts';
 export * from './canonical-record.ts';
 export * from './version.ts';
+export * from './oee.ts';

package/dist/index.js

@@ -39,3 +39,4 @@ export * from "./wms-profile.js";
 export * from "./yms-profile.js";
 export * from "./canonical-record.js";
 export * from "./version.js";
+export * from "./oee.js";

package/dist/oee.d.ts

@@ -0,0 +1,54 @@
+import type { OeeMetrics } from './contract.ts';
+/**
+ * OEE 계측 카운터 — 시뮬은 틱으로, 라이브는 텔레메트리나 사건 누적기가 채운다.
+ *
+ * 이름은 ISO 22400-2 의 시간 항목을 따른다.
+ */
+export interface OeeCounters {
+    /** 실 생산 시간(APT) — 실제로 만들고 있던 시간. 준비·대기·고장은 여기 들어가지 않는다. */
+    runMs: number;
+    /** 준비(AUST). */
+    setupMs: number;
+    /** 고장(ADOT). */
+    downMs: number;
+    goodCount: number;
+    scrapCount: number;
+    /** 계획정지 — 계획 조업 시간에서 뺀다(점심·예방보전·교대). */
+    holdMs?: number;
+    /** 언제부터 쟀나. 없으면 잰 구간이 없는 것이고, 그때는 가동률을 낼 수 없다. */
+    metricsSinceMs?: number;
+    /**
+     * **품목당 표준 시간**(PRI) — 성능률의 분자를 만든다.
+     *
+     * 없으면 성능률을 내지 않는다. 이 값이 없는데 실 가동 시간으로 대신 나누면 「얼마나 빨리
+     * 만들었나」가 아니라 「얼마나 쉬지 않았나」가 되고, 이름만 성능률이 된다.
+     */
+    plannedRunTimePerItemMs?: number;
+}
+/**
+ * **OEE** — ISO 22400-2 의 정의를 따른다.
+ *
+ * ```
+ * PBT           계획 조업 시간 = 잰 구간 − 계획정지
+ * APT           실 생산 시간 = runMs
+ * availability  APT / PBT
+ * effectiveness PRI × PQ / APT          PQ = 양품 + 불량
+ * quality       GQ / PQ
+ * overall       셋의 곱
+ * ```
+ *
+ * ── 예전 식과 무엇이 달랐나 (2026-08-30 대조) ────────────────────────────
+ * 예전에는 가동률의 분자가 `PBT − 준비 − 고장` 이었다. **대기가 분자에 남아 있었다.** 표준은
+ * `AOET = APT + AUST + ADET + ADOT` 로 대기도 실 생산 시간에서 뺀다.
+ *
+ * 총합은 같았다(가동률 × 성능률이 양쪽 다 `runMs / PBT` 로 떨어진다). 다른 것은 두 값을 따로 볼
+ * 때다. 자재를 기다린 시간이 성능률로 넘어가 있어서, **자재 문제를 설비 성능 문제로 읽게 했다.**
+ * 공장이 손 쓰는 방법이 그 둘에서 갈린다 — 가동률이 낮으면 보전·자재를 보고, 성능률이 낮으면
+ * 사이클 타임을 본다.
+ *
+ * 성능률도 달랐다. 표준은 품목당 표준 시간으로 재는데 우리는 실 가동 시간의 비율을 냈다.
+ *
+ * 대조는 원문이 아니라 그 표준을 구현한 규격에서 했다(OPC Foundation MachineTool §C.2). ISO 22400-2
+ * 원문은 유료라 읽지 못했다 — 이 주석이 근거의 한계를 함께 말한다.
+ */
+export declare function computeOee(c: OeeCounters, nowMs: number): OeeMetrics;

package/dist/oee.js

@@ -0,0 +1,62 @@
+/**
+ * **OEE** — ISO 22400-2 의 정의를 따른다.
+ *
+ * ```
+ * PBT           계획 조업 시간 = 잰 구간 − 계획정지
+ * APT           실 생산 시간 = runMs
+ * availability  APT / PBT
+ * effectiveness PRI × PQ / APT          PQ = 양품 + 불량
+ * quality       GQ / PQ
+ * overall       셋의 곱
+ * ```
+ *
+ * ── 예전 식과 무엇이 달랐나 (2026-08-30 대조) ────────────────────────────
+ * 예전에는 가동률의 분자가 `PBT − 준비 − 고장` 이었다. **대기가 분자에 남아 있었다.** 표준은
+ * `AOET = APT + AUST + ADET + ADOT` 로 대기도 실 생산 시간에서 뺀다.
+ *
+ * 총합은 같았다(가동률 × 성능률이 양쪽 다 `runMs / PBT` 로 떨어진다). 다른 것은 두 값을 따로 볼
+ * 때다. 자재를 기다린 시간이 성능률로 넘어가 있어서, **자재 문제를 설비 성능 문제로 읽게 했다.**
+ * 공장이 손 쓰는 방법이 그 둘에서 갈린다 — 가동률이 낮으면 보전·자재를 보고, 성능률이 낮으면
+ * 사이클 타임을 본다.
+ *
+ * 성능률도 달랐다. 표준은 품목당 표준 시간으로 재는데 우리는 실 가동 시간의 비율을 냈다.
+ *
+ * 대조는 원문이 아니라 그 표준을 구현한 규격에서 했다(OPC Foundation MachineTool §C.2). ISO 22400-2
+ * 원문은 유료라 읽지 못했다 — 이 주석이 근거의 한계를 함께 말한다.
+ */
+export function computeOee(c, nowMs) {
+    const missing = [];
+    /* 계획 조업 시간 — 잰 구간을 모르면 없다. 0 으로 메우면 「1970년부터 재고 있었다」가 된다. */
+    const planned = c.metricsSinceMs == null ? 0 : Math.max(0, nowMs - c.metricsSinceMs - (c.holdMs ?? 0));
+    if (planned <= 0)
+        missing.push('planned-busy-time');
+    /* 대기는 남는 시간이다 — 계획 조업에서 생산·준비·고장을 뺀 것. 따로 재지 않아도 나온다. */
+    const delayMs = Math.max(0, planned - c.runMs - c.setupMs - c.downMs);
+    const availability = planned > 0 ? Math.min(1, c.runMs / planned) : undefined;
+    const produced = c.goodCount + c.scrapCount;
+    if (produced <= 0)
+        missing.push('produced-quantity');
+    const quality = produced > 0 ? c.goodCount / produced : undefined;
+    /* 성능률 — 표준 시간이 없으면 내지 않는다. 실 생산 시간이 0 이어도 나눌 수 없다. */
+    if (c.plannedRunTimePerItemMs == null)
+        missing.push('planned-run-time-per-item');
+    else if (c.runMs <= 0)
+        missing.push('actual-production-time');
+    const performance = c.plannedRunTimePerItemMs != null && c.runMs > 0
+        ? Math.min(1, (c.plannedRunTimePerItemMs * produced) / c.runMs)
+        : undefined;
+    const overall = availability != null && performance != null && quality != null ? availability * performance * quality : undefined;
+    return {
+        ...(availability != null ? { availability } : {}),
+        ...(performance != null ? { performance } : {}),
+        ...(quality != null ? { quality } : {}),
+        ...(overall != null ? { overall } : {}),
+        ...(missing.length ? { missing } : {}),
+        runMs: c.runMs,
+        setupMs: c.setupMs,
+        downMs: c.downMs,
+        delayMs,
+        goodCount: c.goodCount,
+        scrapCount: c.scrapCount
+    };
+}

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' | 'disposition' | 'observation' | 'complete';
+export type OperationalKind = 'task' | 'equipment' | 'equipment-period' | 'person' | 'asset' | 'order' | 'quality' | 'test' | 'disposition' | 'observation' | 'complete';
 /**
  * 정규 운영 레코드 — **델타의 필드 이름 + 시각(`at`)**.
  *

package/dist/operational-ingest.js

@@ -42,7 +42,19 @@ import { OP_EVENT, DISPOSITION_DECISION } from "./contract.js";
  *  · 사람·자산 상태 — 배정이 `idle` 을 찾는다. 다른 낱말이면 있는 자원이 없는 것이 된다.
  */
 const TASK_STATUS = ['created', 'assigned', 'in-progress', 'completed'];
-const EQUIPMENT_STATUS = ['idle', 'busy', 'down'];
+/*
+ * 설비 상태 — **ISO 22400-2 의 시간 모델에 하나씩 대응한다**(2026-08-30).
+ *
+ *   busy           actual production time      가동률·성능률의 분자
+ *   setup          actual unit setup time      준비. 가동에서 빼되 계획 조업에는 남는다
+ *   down           actual unit down time       고장. 가동률을 깎는다
+ *   idle           actual unit delay time      대기(자재·앞공정·인원). 가동률을 깎는다
+ *   planned-stop   계획 조업 시간에서 제외      점심·예방보전·교대. 깎지 않는다
+ *
+ * `down` 과 `idle` 은 22400 에서 다른 항목이고 공장이 손 쓰는 방법도 다르다(고장은 보전, 대기는
+ * 자재·일정). 처음부터 갈라 두었던 것이 맞았고, 여기에 둘을 더해 22400 의 시간 모델을 덮는다.
+ */
+const EQUIPMENT_STATUS = ['idle', 'busy', 'down', 'setup', 'planned-stop'];
 const PERSON_STATUS = ['idle', 'busy'];
 const ASSET_STATUS = ['idle', 'in-use'];
 const SPECS = {
@@ -72,6 +84,8 @@ const SPECS = {
         fields: {
             moverId: 'string', kind: 'string', status: 'string', location: 'string', homeLocation: 'string', // vocabulary-guard: allow
             taskId: 'string', held: 'boolean', effectiveStart: 'string', effectiveEnd: 'string', recordTime: 'string',
+            /* 왜 이 상태가 됐나 — 설비가 알려 주면 싣는다. 사람이 나중에 정하는 사유는 구간 사실에 적는다. */
+            reasonCode: 'string',
             /* 이동 구간 — 실 시스템도 줄 수 있는 사실이다(AGV·RTLS 가 출발·도착·소요를 낸다). 안쪽 필드까지
                재검사하지는 않는다: 그 모양은 `EquipmentMotion` 계약이고, 여기서 두 번 지키면 두 벌이 된다. */
             motion: 'object'
@@ -130,6 +144,41 @@ const SPECS = {
      * `propertyMeasurements` 안쪽은 재검사하지 않는다 — 그 모양은 `PropertyMeasurement` 계약이고,
      * 여기서 두 번 지키면 두 벌이 된다(설비 `motion` 과 같은 규율).
      */
+    /*
+     * **마감된 설비 상태 구간** — 이 설비가 이 구간 동안 이 상태였다.
+     *
+     * ── 전이만으로는 안 되는 이유 (2026-08-30) ───────────────────────────────
+     * 세 가지다. 셋째가 결정적이다.
+     *
+     *   사유가 붙을 자리가 없다   기계가 서는 순간에는 왜 섰는지 아무도 모른다. 작업자가 라인이 다시
+     *                            돈 뒤에 적는다. 그 사이에 전이가 더 있으면 어느 전이에 붙일지 정할 수 없다
+     *   계획·비계획을 나중에 정한다  ISO 22400 은 계획정지를 계획 조업 시간에서 빼고 고장은 빼지 않는다.
+     *                            그 분류는 전이가 일어난 순간에 모른다
+     *   전이를 내지 않는 정지가 많다  자재 대기 · 앞 공정 대기 · 작업자 부재. 기계는 전원이 켜진 채 `idle`
+     *                            이고 신호가 하나도 안 나온다. OEE 에서 가장 크게 깎이는 것이 보통 이 시간이다
+     *
+     * 마지막이 감시 시스템과 MES 가 갈리는 자리이기도 하다. 설비가 말하는 것만 모으면 감시이고,
+     * **설비가 말하지 못하는 것을 사람이 적어 넣는 자리**가 MES 다.
+     *
+     * ── 이름이 `downtime` 이 아닌 이유 ────────────────────────────────────────
+     * 이 구간은 `setup` 과 `planned-stop` 도 나른다. 그 둘은 정지가 아니다. 담는 것은 **상태 구간**이고,
+     * 어느 상태인지는 `status` 가 말한다.
+     *
+     * ── 되돌아가 적는 사실이다 ───────────────────────────────────────────────
+     * 봉투의 사건 시각은 **구간의 끝**(그때 성립한다)이고, 적은 시각은 `recordTime` 이다. 둘이 갈려 있어야
+     * 「언제 일어났나」와 「언제 알았나」를 구별할 수 있다.
+     */
+    'equipment-period': {
+        eventType: OP_EVENT.equipmentPeriod,
+        identity: 'moverId', // vocabulary-guard: allow 저널 와이어 필드 — 전이와 같은 이름을 쓴다
+        required: ['moverId', 'status', 'from', 'to'], // vocabulary-guard: allow 위와 같은 이유
+        fields: {
+            moverId: 'string', status: 'string', from: 'string', to: 'string', // vocabulary-guard: allow
+            /* 사람이 정한 사유 — 없을 수 있다(적지 않은 것과 사유가 없는 것은 다르므로 지어내지 않는다). */
+            reasonCode: 'string', decidedBy: 'string', recordTime: 'string'
+        },
+        enums: { status: EQUIPMENT_STATUS }
+    },
     /*
      * **부적합 처분** — 재고 판정을 받은 것을 어떻게 하기로 정했나.
      *
@@ -223,6 +272,12 @@ export function operationalKindOf(record) {
         return undefined;
     const has = (k) => typeof r[k] === 'string' && r[k].trim().length > 0;
     /* vocabulary-guard: allow 저널 와이어 필드로 가른다 */
+    /*
+     * 구간이 있으면 **마감된 상태 구간**이지 시점의 전이가 아니다. 전이보다 먼저 본다 — 뒤에 두면
+     * 사람이 되돌아가 적은 구간이 「지금 이 상태다」로 읽혀 트윈의 상태가 과거로 끌린다.
+     */
+    if (has('moverId') && has('from') && has('to'))
+        return 'equipment-period';
     if (has('moverId'))
         return r.good !== undefined ? 'quality' : 'equipment';
     if (has('personId'))
@@ -389,12 +444,28 @@ export function ingestOperationalRecords(records, opts) {
                 }
             }
         }
-        const at = String(r.at ?? '').trim() || opts.defaultEventTime;
+        /*
+         * **마감된 구간은 구간의 끝에 성립한다.** 사람이 되돌아가 적는 사실이라 `at` 을 쓰면 「적은 때」가
+         * 사건 시각이 되고, 그러면 어제 있었던 정지가 오늘 일어난 것으로 저널에 적힌다. 적은 때는
+         * `recordTime` 에 남는다.
+         */
+        const closedPeriodEnd = kind === 'equipment-period' ? String(r.to ?? '').trim() : '';
+        const at = closedPeriodEnd || String(r.at ?? '').trim() || opts.defaultEventTime;
         const atMs = at ? Date.parse(at) : Number.NaN;
         if (!Number.isFinite(atMs)) {
             /* 시각이 없으면 순서를 판정할 수 없다 — 늦게 온 옛 사실이 최신 상태를 덮어써 위치가 과거로 튄다. */
             errors.push(`${kind}: at 없음/형식 오류 — 시각 없이는 늦게 온 옛 사실을 걸러낼 수 없다`);
         }
+        /*
+         * 아직 오지 않은 구간은 마감된 사실이 아니다 — 에너지의 마감된 구간과 같은 규칙이다. 받으면
+         * 성과 계산의 구간이 미래로 밀리고, 그 현장의 화면이 오류 없이 비어 보인다(2026-08-30 실측).
+         */
+        if (closedPeriodEnd && opts.defaultEventTime) {
+            const nowMs = Date.parse(opts.defaultEventTime);
+            if (Number.isFinite(nowMs) && Number.isFinite(atMs) && atMs > nowMs) {
+                errors.push(`${kind}: 아직 오지 않은 시각의 사실이다(${closedPeriodEnd}) — 끝나지 않은 구간은 마감된 사실이 아니다`);
+            }
+        }
         if (errors.length) {
             rejected.push({ record, errors });
             continue;

package/dist/version.d.ts

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

package/dist/version.js

@@ -11,4 +11,4 @@
  *
  * **정본은 `package.json` 이다.** 이 값이 그것과 같은지는 시험이 지킨다(§`version-matches`).
  */
-export const CONTRACT_VERSION = '0.3.0';
+export const CONTRACT_VERSION = '0.5.0';

package/dist-cjs/index.cjs

@@ -80,6 +80,7 @@ __export(index_exports, {
   classClosure: () => classClosure,
   classIdentifierViolation: () => classIdentifierViolation,
   commandsOf: () => commandsOf,
+  computeOee: () => computeOee,
   conversionFactorOf: () => conversionFactorOf,
   criterionSaysNothing: () => criterionSaysNothing,
   documentPath: () => documentPath,
@@ -775,6 +776,15 @@ var OP_EVENT = {
    * 이 채널이 없으면 시험 결과는 **상태에만 있는 축**이 된다 — 재기동에서 사라지고, 폴드가 되살릴 수
    * 없고, 미러가 이어받지 못한다(§상태 ⊆ 이벤트).
    */
+  /**
+   * **마감된 설비 상태 구간** — 이 설비가 이 구간 동안 이 상태였다.
+   *
+   * 시점의 전이(`equipment.status`)와 다른 사실이다. 전이는 설비가 내고, 이것은 **사람이 나중에
+   * 적는다.** 자재 대기처럼 신호를 내지 않는 정지는 이 길로만 들어온다.
+   *
+   * ISO 22400-2 의 가동률 계산이 이 구간들을 읽는다.
+   */
+  equipmentPeriod: "equipment.state.period",
   test: "test.result",
   /**
    * **부적합 처분** — 재고 판정을 받은 것을 어떻게 하기로 정했나(재작업 · 특채 · 폐기 · 반품).
@@ -3149,7 +3159,7 @@ function readEpochMs(raw) {
 
 // src/operational-ingest.ts
 var TASK_STATUS = ["created", "assigned", "in-progress", "completed"];
-var EQUIPMENT_STATUS = ["idle", "busy", "down"];
+var EQUIPMENT_STATUS = ["idle", "busy", "down", "setup", "planned-stop"];
 var PERSON_STATUS = ["idle", "busy"];
 var ASSET_STATUS = ["idle", "in-use"];
 var SPECS = {
@@ -3207,6 +3217,8 @@ var SPECS = {
       effectiveStart: "string",
       effectiveEnd: "string",
       recordTime: "string",
+      /* 왜 이 상태가 됐나 — 설비가 알려 주면 싣는다. 사람이 나중에 정하는 사유는 구간 사실에 적는다. */
+      reasonCode: "string",
       /* 이동 구간 — 실 시스템도 줄 수 있는 사실이다(AGV·RTLS 가 출발·도착·소요를 낸다). 안쪽 필드까지
          재검사하지는 않는다: 그 모양은 `EquipmentMotion` 계약이고, 여기서 두 번 지키면 두 벌이 된다. */
       motion: "object"
@@ -3296,6 +3308,49 @@ var SPECS = {
    * `propertyMeasurements` 안쪽은 재검사하지 않는다 — 그 모양은 `PropertyMeasurement` 계약이고,
    * 여기서 두 번 지키면 두 벌이 된다(설비 `motion` 과 같은 규율).
    */
+  /*
+   * **마감된 설비 상태 구간** — 이 설비가 이 구간 동안 이 상태였다.
+   *
+   * ── 전이만으로는 안 되는 이유 (2026-08-30) ───────────────────────────────
+   * 세 가지다. 셋째가 결정적이다.
+   *
+   *   사유가 붙을 자리가 없다   기계가 서는 순간에는 왜 섰는지 아무도 모른다. 작업자가 라인이 다시
+   *                            돈 뒤에 적는다. 그 사이에 전이가 더 있으면 어느 전이에 붙일지 정할 수 없다
+   *   계획·비계획을 나중에 정한다  ISO 22400 은 계획정지를 계획 조업 시간에서 빼고 고장은 빼지 않는다.
+   *                            그 분류는 전이가 일어난 순간에 모른다
+   *   전이를 내지 않는 정지가 많다  자재 대기 · 앞 공정 대기 · 작업자 부재. 기계는 전원이 켜진 채 `idle`
+   *                            이고 신호가 하나도 안 나온다. OEE 에서 가장 크게 깎이는 것이 보통 이 시간이다
+   *
+   * 마지막이 감시 시스템과 MES 가 갈리는 자리이기도 하다. 설비가 말하는 것만 모으면 감시이고,
+   * **설비가 말하지 못하는 것을 사람이 적어 넣는 자리**가 MES 다.
+   *
+   * ── 이름이 `downtime` 이 아닌 이유 ────────────────────────────────────────
+   * 이 구간은 `setup` 과 `planned-stop` 도 나른다. 그 둘은 정지가 아니다. 담는 것은 **상태 구간**이고,
+   * 어느 상태인지는 `status` 가 말한다.
+   *
+   * ── 되돌아가 적는 사실이다 ───────────────────────────────────────────────
+   * 봉투의 사건 시각은 **구간의 끝**(그때 성립한다)이고, 적은 시각은 `recordTime` 이다. 둘이 갈려 있어야
+   * 「언제 일어났나」와 「언제 알았나」를 구별할 수 있다.
+   */
+  "equipment-period": {
+    eventType: OP_EVENT.equipmentPeriod,
+    identity: "moverId",
+    // vocabulary-guard: allow 저널 와이어 필드 — 전이와 같은 이름을 쓴다
+    required: ["moverId", "status", "from", "to"],
+    // vocabulary-guard: allow 위와 같은 이유
+    fields: {
+      moverId: "string",
+      status: "string",
+      from: "string",
+      to: "string",
+      // vocabulary-guard: allow
+      /* 사람이 정한 사유 — 없을 수 있다(적지 않은 것과 사유가 없는 것은 다르므로 지어내지 않는다). */
+      reasonCode: "string",
+      decidedBy: "string",
+      recordTime: "string"
+    },
+    enums: { status: EQUIPMENT_STATUS }
+  },
   /*
    * **부적합 처분** — 재고 판정을 받은 것을 어떻게 하기로 정했나.
    *
@@ -3392,6 +3447,7 @@ function operationalKindOf(record) {
   const r = record;
   if (r.epc !== void 0 || r.meterId !== void 0 || r.equipmentId !== void 0) return void 0;
   const has = (k) => typeof r[k] === "string" && r[k].trim().length > 0;
+  if (has("moverId") && has("from") && has("to")) return "equipment-period";
   if (has("moverId")) return r.good !== void 0 ? "quality" : "equipment";
   if (has("personId")) return "person";
   if (has("assetId")) return "asset";
@@ -3500,11 +3556,18 @@ function ingestOperationalRecords(records, opts) {
         }
       }
     }
-    const at = String(r.at ?? "").trim() || opts.defaultEventTime;
+    const closedPeriodEnd = kind === "equipment-period" ? String(r.to ?? "").trim() : "";
+    const at = closedPeriodEnd || String(r.at ?? "").trim() || opts.defaultEventTime;
     const atMs = at ? Date.parse(at) : Number.NaN;
     if (!Number.isFinite(atMs)) {
       errors.push(`${kind}: at \uC5C6\uC74C/\uD615\uC2DD \uC624\uB958 \u2014 \uC2DC\uAC01 \uC5C6\uC774\uB294 \uB2A6\uAC8C \uC628 \uC61B \uC0AC\uC2E4\uC744 \uAC78\uB7EC\uB0BC \uC218 \uC5C6\uB2E4`);
     }
+    if (closedPeriodEnd && opts.defaultEventTime) {
+      const nowMs = Date.parse(opts.defaultEventTime);
+      if (Number.isFinite(nowMs) && Number.isFinite(atMs) && atMs > nowMs) {
+        errors.push(`${kind}: \uC544\uC9C1 \uC624\uC9C0 \uC54A\uC740 \uC2DC\uAC01\uC758 \uC0AC\uC2E4\uC774\uB2E4(${closedPeriodEnd}) \u2014 \uB05D\uB098\uC9C0 \uC54A\uC740 \uAD6C\uAC04\uC740 \uB9C8\uAC10\uB41C \uC0AC\uC2E4\uC774 \uC544\uB2C8\uB2E4`);
+      }
+    }
     if (errors.length) {
       rejected.push({ record, errors });
       continue;
@@ -3671,7 +3734,36 @@ function retiredVocabularyIn(line) {
 }
 
 // src/version.ts
-var CONTRACT_VERSION = "0.3.0";
+var CONTRACT_VERSION = "0.5.0";
+
+// src/oee.ts
+function computeOee(c, nowMs) {
+  const missing = [];
+  const planned = c.metricsSinceMs == null ? 0 : Math.max(0, nowMs - c.metricsSinceMs - (c.holdMs ?? 0));
+  if (planned <= 0) missing.push("planned-busy-time");
+  const delayMs = Math.max(0, planned - c.runMs - c.setupMs - c.downMs);
+  const availability = planned > 0 ? Math.min(1, c.runMs / planned) : void 0;
+  const produced = c.goodCount + c.scrapCount;
+  if (produced <= 0) missing.push("produced-quantity");
+  const quality = produced > 0 ? c.goodCount / produced : void 0;
+  if (c.plannedRunTimePerItemMs == null) missing.push("planned-run-time-per-item");
+  else if (c.runMs <= 0) missing.push("actual-production-time");
+  const performance = c.plannedRunTimePerItemMs != null && c.runMs > 0 ? Math.min(1, c.plannedRunTimePerItemMs * produced / c.runMs) : void 0;
+  const overall = availability != null && performance != null && quality != null ? availability * performance * quality : void 0;
+  return {
+    ...availability != null ? { availability } : {},
+    ...performance != null ? { performance } : {},
+    ...quality != null ? { quality } : {},
+    ...overall != null ? { overall } : {},
+    ...missing.length ? { missing } : {},
+    runMs: c.runMs,
+    setupMs: c.setupMs,
+    downMs: c.downMs,
+    delayMs,
+    goodCount: c.goodCount,
+    scrapCount: c.scrapCount
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BIZSTEP,
@@ -3735,6 +3827,7 @@ var CONTRACT_VERSION = "0.3.0";
   classClosure,
   classIdentifierViolation,
   commandsOf,
+  computeOee,
   conversionFactorOf,
   criterionSaysNothing,
   documentPath,

package/package.json

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