@operato/ops-contract 0.9.1 → 0.9.3

package/dist/contract.d.ts

@@ -1,3 +1,4 @@
+import { type RatedUsage, type UsedUsage } from './rated-usage.ts';
 export type ISOTime = string;
 export interface CanonicalEnvelope<T = unknown> {
     eventId: string;
@@ -476,6 +477,8 @@ export type CapabilityReason =
  | 'resting'
 /** 요구된 시험의 결과가 만료·불합격 — 자격이 성립하지 않는다(§TestResult). */
  | 'test-expired'
+/** 정격 사용량을 다 썼다 — 교체할 일이다(§`RatedUsage`). 고장(`down`)과 다르다: 고쳐서 쓰지 않는다. */
+ | 'worn-out'
 /** 지금 다른 일을 하고 있다 — 능력은 있고 여유가 없다. */
  | 'working'
 /** 쓸 수 있다. */
@@ -748,6 +751,41 @@ export interface ResourceClassDef extends EffectivePeriod {
     testSpecificationIds?: TestSpecificationRefs;
 }
 export declare function classClosure(directIds: readonly string[] | undefined, defs: readonly ResourceClassDef[] | undefined, at?: ISOTime): Set<string>;
+/**
+ * 설비의 **등급 소속** — 선언한 등급들과 `kind` 를 합친 것.
+ *
+ * ── 왜 설비만 함수가 있나 ────────────────────────────────────────────────────
+ * 사람과 자산은 소속이 `personnelClassIds`·`assetClassIds` 하나뿐이라 부르는 쪽이 그 필드를 그대로
+ * 넘긴다. 설비는 소속이 **두 곳에서 온다** — 선언한 `equipmentClassIds` 와, 예전부터 소속 노릇을 해 온
+ * `kind`. 그 합침을 부르는 쪽마다 손으로 쓰면 한 곳이 빠진 날 그 설비는 **거기서만 등급을 잃는다.**
+ *
+ * 실제로 그 자리가 여섯이다: 스냅샷·가용 개수·배정 고르기·재수화·op 이벤트·관측 축소. 여섯이 같은
+ * 답을 내야 하므로 규칙이 한 자리에 있다(`requiredTestsFor` 가 계약에 있는 것과 같은 이유).
+ *
+ * ── `kind` 를 왜 소속으로 세나 (2026-09-03, 재고 결정) ──────────────────────
+ * 처음에는 설비 소속이 `kind` **하나**였다. 그것을 복수로 넓히면서 `kind` 를 뺄지 재 봤다.
+ *
+ * ```
+ * 저장된 트윈 32개 · kind 19종(cutter welder painter assembler hostler forklift meter pv-array …)
+ * equipmentClasses 를 선언한 트윈    0
+ * 설비를 이름으로 부르는 공정        52   그 이름이 전부 kind (cutter · welder · painter · assembler)
+ * ```
+ *
+ * **`kind` 는 지금 하중을 받고 있다.** 빼면 그 52 공정이 설비를 못 찾고, 요구가 채워지지 않아 라인이
+ * 굶는다 — 오류는 안 난다. 그리고 표준에서도 `EquipmentClass` 는 "정해진 목적으로 묶은 설비 무리" 이니
+ * 설비의 종류는 그 자체로 등급이다. 그래서 뺄 이유가 없고, **선언한 것에 더한다.**
+ *
+ * 합치는 것이 위험한 경우는 하나다 — 선언한 등급 id 가 어떤 `kind` 와 우연히 같을 때. 그때는 그 설비가
+ * 뜻하지 않은 요구를 만족한다. 다만 등급 id 는 사람이 일부러 짓는 이름이고 `kind` 도 그렇다. 같은
+ * 이름을 지었다면 같은 것을 뜻한 것으로 본다.
+ *
+ * 순서는 **선언한 것이 먼저**다 — 부르는 쪽이 첫 값을 대표 등급으로 쓸 때 종류가 아니라 선언이 대표가
+ * 된다. 중복은 접는다.
+ */
+export declare function equipmentClassMembership(e: {
+    kind?: string;
+    equipmentClassIds?: readonly string[];
+}): string[];
 /**
  * 우선순위 — **ISA-95 `Priority`**(`JobOrderType`·`OperationsRequestType`, 타입은 `PriorityType` =
  * `NumericType` 제한). 즉 표준은 **숫자라는 것만 정하고 방향은 정하지 않는다.**
@@ -1079,6 +1117,9 @@ export declare function capabilityOf(r: {
     };
     workCalendar?: WorkCalendarEntry[];
     testResults?: TestResult[];
+    /** 정격 사용량과 쓴 양 — 소모 공구만 든다(§`RatedUsage`). 없으면 이 축으로 막지 않는다. */
+    ratedUsage?: RatedUsage;
+    usedUsage?: UsedUsage;
 } & EffectivePeriod, ctx?: {
     at?: ISOTime;
     utcOffsetMinutes?: number;
@@ -1419,7 +1460,7 @@ export interface OeeMetrics {
     downMs: number;
     delayMs: number;
     goodCount: number;
-    scrapCount: number;
+    nonconformingCount: number;
 }
 /**
  * OEE 값이 없는 이유.
@@ -1439,6 +1480,16 @@ export type OeeMissing =
 export interface EquipmentState extends EffectivePeriod {
     id: string;
     kind: string;
+    /**
+     * 속한 **등급들** — 표준 `EquipmentClassID`(복수). 사람·자산의 상태가 등급을 싣는 것과 같다.
+     *
+     * 스냅샷과 op 이벤트가 이것을 실어야 **재기동한 미러가 소속을 이어받는다** — 실지 않으면 되살린
+     * 트윈에서 등급이 비고, 등급으로 부르는 요구(`equipmentSpecification`)가 채워지지 않아 라인이 굶는다.
+     * 오류는 나지 않는다.
+     *
+     * 판정은 `equipmentClassMembership` 을 거친다 — 이 선언과 `kind` 를 합치는 규칙은 한 자리에 있다.
+     */
+    equipmentClassIds?: string[];
     /** **지금 어디에 있나.** 운반 작업이 끝나면 도착 자리로 옮겨진다(제자리 작업은 안 움직인다). */
     location?: string;
     /**
@@ -1712,6 +1763,18 @@ export interface AssetState extends EffectivePeriod {
      * 비어 있으면 빈 팔레트다(회수 대상이자 다음 출고의 재료).
      */
     carrying?: string;
+    /**
+     * **정격 사용량** — 이만큼 쓰면 교체한다(§`RatedUsage`).
+     *
+     * 자산에 두는 이유: 닳는 것은 개체다. 등급에 두면 「메탈마스크는 5만 번」은 말할 수 있어도
+     * **「지금 걸려 있는 이 한 장이 4만 7천 번째다」**를 말할 수 없고, 교체해야 하는 것은 그 한 장이다.
+     *
+     * 속성(`properties`)에 두지 않는 이유: 이 값은 **막는 데 쓴다.** 속성 배열을 뒤져 읽으면 오타
+     * 하나가 오류 보고 없이 「정격 없음」이 된다(§`ResourceProperty` — 속성은 열림, 효과는 닫힘).
+     */
+    ratedUsage?: RatedUsage;
+    /** 지금까지 쓴 양 — 정격과 **같은 단위**여야 견준다(§`UsedUsage`). 없으면 0이 아니라 모르는 것이다. */
+    usedUsage?: UsedUsage;
     /** 자원 속성 — 표준 `PhysicalAssetProperty`(§ResourceProperty). */
     properties?: ResourceProperty[];
     /** 적격을 검증한 시험 명세들 — 표준 `PhysicalAsset.TestSpecificationID`(§TestSpecificationRefs). */
@@ -3058,6 +3121,15 @@ export interface PersonStatusDelta extends EffectivePeriod {
 export interface AssetStatusDelta extends EffectivePeriod {
     assetId: string;
     assetClassIds?: string[];
+    /**
+     * 정격과 쓴 양 — **상태에 있으면 델타에도 있어야 한다**(상태⊆이벤트).
+     *
+     * 특히 쓴 양은 시뮬이 작업마다 올리는 값이라 나가지 않으면 미러가 영원히 처음 값을 들고 있고,
+     * 「이 공구가 언제 소진되나」에 답할 수 없다. 정격은 선언이라 잘 안 바뀌지만 함께 낸다 —
+     * 미러가 정격 없이 쓴 양만 받으면 견줄 것이 없다.
+     */
+    ratedUsage?: RatedUsage;
+    usedUsage?: UsedUsage;
     status: string;
     location?: string;
     taskId?: string;
@@ -3151,12 +3223,33 @@ export interface EquipmentStatePeriodFact {
     decidedBy?: string;
     recordTime?: ISOTime;
 }
-/** 품질 산출 델타 — recordOutput(양품/불량) 시 방출. goodCount/scrapCount 는 설비 누적값. */
+/**
+ * 품질 산출 델타 — recordOutput(양품/부적합) 시 방출. 두 수는 설비 누적값이다.
+ *
+ * ── 이름을 `scrapCount` 에서 바꾼 이유 (2026-09-03) — vocabulary-guard: allow (옛 이름을 글로 남긴다)
+ * 이 수는 **검사에서 떨어진 것 전부**다. 재작업으로 되살아날 것도 든다. 그런데 이름이
+ * `scrapCount` 였고(vocabulary-guard: allow), 처분 어휘의 `scrap` 은 **「폐기」 하나**다(§`DISPOSITION_DECISION`) — 되돌리지 않고 버리는
+ * 것. 같은 낱말이 두 뜻이었다.
+ *
+ * **그리고 ISO 22400-2 의 SQ(scrap quantity)가 아니다.** 표준은 셋을 가른다: GQ(양품) · SQ(폐기,
+ * 재작업할 수 없는 것) · RQ(재작업). 이 수는 `SQ + RQ` 다.
+ *
+ * 비율 계산은 지금도 맞다 — 품질률은 `GQ / (GQ + SQ + RQ)` 이므로 `goodCount / (goodCount +
+ * nonconformingCount)` 가 정확히 그것이다. **틀린 것은 이름뿐이었고**, 그래서 새로 붙이는 쪽이
+ * 이것을 폐기 수로 읽고 폐기 원가를 세거나 재작업 수를 따로 더해 분모를 두 번 셀 위험이 있었다.
+ *
+ * 낱말은 `nonconforming` 으로 정했다 — `reject` 도 검사에서 「떨어뜨려 버린다」는 결정을 뜻해 같은
+ * 모호함을 남긴다. 계약이 이미 `nonconformance.disposition`·`FirstPassInput.nonconforming` 을 쓰고
+ * 있으니 세 번째 낱말을 만들지 않는다. **화면은 「불량 / reject」로 남는다** — 현장이 쓰는 말이고,
+ * 국문이 이미 「불량 수」와 「부적합 처분」을 갈라 쓴다.
+ */
 export interface QualityDelta {
     moverId: string;
     good: boolean;
+    /** 처음에 통과한 수가 아니다 — 재작업해서 통과한 것이 여기 더해지면 직행수율이 품질률이 된다(§`FIRST_PASS_RULE`). */
     goodCount: number;
-    scrapCount: number;
+    /** **부적합 전체**(폐기 + 재작업 + 특채 …). ISO 22400 의 SQ 가 아니라 `SQ + RQ` 다 — 위 머리말. */
+    nonconformingCount: number;
     /**
      * 이 산출이 어느 작업의 것인가 — **귀속이고, 수량의 뜻을 바꾸지 않는다**(설비 누적 그대로).
      *
@@ -3259,6 +3352,14 @@ export interface TaskStatusDelta {
 export interface EquipmentStatusDelta extends EffectivePeriod {
     moverId: string;
     kind: string;
+    /**
+     * 속한 **등급들**(`EquipmentState.equipmentClassIds`). 나가지 않으면 미러가 소속을 영영 모른다 —
+     * 상태⊆이벤트. 사람·자산 델타가 등급을 싣는 것과 같은 자리다.
+     *
+     * 그러면 등급으로 부르는 요구(`equipmentSpecification`)가 미러에서 채워지지 않고, **라인이 굶는데
+     * 오류는 나지 않는다.**
+     */
+    equipmentClassIds?: string[];
     status: string;
     location?: string;
     /** 붙박인 자리(`EquipmentState.homeLocation`). 나가지 않으면 미러가 소속을 영영 모른다 — 상태⊆이벤트. */
@@ -3404,13 +3505,18 @@ export interface TwinModelDef {
         testSpecificationIds?: TestSpecificationRefs;
     })[];
     /**
-     * 설비(설비). mtbfMs/mttrMs 지정 시 확률적 고장 모델 참여(OEE Availability 손실). 미지정=고장 없음.
-     * `window` 지정 시 그 시간대에만 일한다(교대·가동시간) — 미지정이면 24시간 가용(기존 거동).
+     * 설비 — ISA-95 `Equipment`. mtbfMs/mttrMs 지정 시 확률적 고장 모델 참여(OEE Availability 손실).
+     * 미지정=고장 없음. `window` 지정 시 그 시간대에만 일한다(교대·가동시간) — 미지정이면 24시간 가용.
+     *
+     * `equipmentClassIds` 로 **속한 등급들**을 밝힌다(복수가 표준 — 사람·자산과 같은 규칙). 선언하지
+     * 않으면 `kind` 하나가 소속이다(기존 거동). 판정은 늘 `equipmentClassMembership` 을 거친다 —
+     * 선언과 종류를 합치는 규칙이 한 자리에 있다.
      */
     equipment: (EffectivePeriod & {
         id: string;
         name?: string;
         kind: string;
+        equipmentClassIds?: string[];
         homeLocation: string;
         identity?: string;
         mtbfMs?: number;
@@ -3446,6 +3552,8 @@ export interface TwinModelDef {
     assets?: (EffectivePeriod & {
         id: string;
         assetClassIds?: string[];
+        ratedUsage?: RatedUsage;
+        usedUsage?: UsedUsage;
         homeLocation?: string;
         properties?: ResourceProperty[];
         testSpecificationIds?: TestSpecificationRefs;

package/dist/contract.js

@@ -32,6 +32,7 @@
  * 지키는 하네스: `derived-not-input` · `actuals-come-from-transitions` · `accumulators-survive-restart` ·
  * `purpose-conformance`.
  */
+import { ratedUsageOf } from "./rated-usage.js";
 /** 오더가 **종결 상태**로 인정되는 낱말 — 이 밖은 진행 중이다(§`isOrderTerminal`). */
 export const ORDER_TERMINAL_STATUS = ['completed', 'cancelled'];
 /**
@@ -503,6 +504,46 @@ export function classClosure(directIds, defs, at) {
     }
     return out;
 }
+/**
+ * 설비의 **등급 소속** — 선언한 등급들과 `kind` 를 합친 것.
+ *
+ * ── 왜 설비만 함수가 있나 ────────────────────────────────────────────────────
+ * 사람과 자산은 소속이 `personnelClassIds`·`assetClassIds` 하나뿐이라 부르는 쪽이 그 필드를 그대로
+ * 넘긴다. 설비는 소속이 **두 곳에서 온다** — 선언한 `equipmentClassIds` 와, 예전부터 소속 노릇을 해 온
+ * `kind`. 그 합침을 부르는 쪽마다 손으로 쓰면 한 곳이 빠진 날 그 설비는 **거기서만 등급을 잃는다.**
+ *
+ * 실제로 그 자리가 여섯이다: 스냅샷·가용 개수·배정 고르기·재수화·op 이벤트·관측 축소. 여섯이 같은
+ * 답을 내야 하므로 규칙이 한 자리에 있다(`requiredTestsFor` 가 계약에 있는 것과 같은 이유).
+ *
+ * ── `kind` 를 왜 소속으로 세나 (2026-09-03, 재고 결정) ──────────────────────
+ * 처음에는 설비 소속이 `kind` **하나**였다. 그것을 복수로 넓히면서 `kind` 를 뺄지 재 봤다.
+ *
+ * ```
+ * 저장된 트윈 32개 · kind 19종(cutter welder painter assembler hostler forklift meter pv-array …)
+ * equipmentClasses 를 선언한 트윈    0
+ * 설비를 이름으로 부르는 공정        52   그 이름이 전부 kind (cutter · welder · painter · assembler)
+ * ```
+ *
+ * **`kind` 는 지금 하중을 받고 있다.** 빼면 그 52 공정이 설비를 못 찾고, 요구가 채워지지 않아 라인이
+ * 굶는다 — 오류는 안 난다. 그리고 표준에서도 `EquipmentClass` 는 "정해진 목적으로 묶은 설비 무리" 이니
+ * 설비의 종류는 그 자체로 등급이다. 그래서 뺄 이유가 없고, **선언한 것에 더한다.**
+ *
+ * 합치는 것이 위험한 경우는 하나다 — 선언한 등급 id 가 어떤 `kind` 와 우연히 같을 때. 그때는 그 설비가
+ * 뜻하지 않은 요구를 만족한다. 다만 등급 id 는 사람이 일부러 짓는 이름이고 `kind` 도 그렇다. 같은
+ * 이름을 지었다면 같은 것을 뜻한 것으로 본다.
+ *
+ * 순서는 **선언한 것이 먼저**다 — 부르는 쪽이 첫 값을 대표 등급으로 쓸 때 종류가 아니라 선언이 대표가
+ * 된다. 중복은 접는다.
+ */
+export function equipmentClassMembership(e) {
+    const out = [];
+    for (const id of e?.equipmentClassIds ?? [])
+        if (id && !out.includes(id))
+            out.push(id);
+    if (e?.kind && !out.includes(e.kind))
+        out.push(e.kind);
+    return out;
+}
 /**
  * 우선순위 — **ISA-95 `Priority`**(`JobOrderType`·`OperationsRequestType`, 타입은 `PriorityType` =
  * `NumericType` 제한). 즉 표준은 **숫자라는 것만 정하고 방향은 정하지 않는다.**
@@ -910,6 +951,17 @@ export function capabilityOf(r, ctx) {
         return { available: false, reason: 'held' };
     if (r.status === 'down')
         return { available: false, reason: 'down' };
+    /*
+     * 다 쓴 자원 — **고장보다 뒤, 교대보다 앞.**
+     *
+     * 고장이 먼저인 이유: 고장 난 것을 「수명 끝」이라고 말하면 고치러 가지 않는다. 교대보다 앞인
+     * 이유: 다 쓴 공구는 다음 교대가 와도 돌아오지 않는다 — 기다릴 일이 아니라 바꿀 일이다.
+     *
+     * **판정할 수 없으면 막지 않는다.** 정격을 선언하지 않았거나 쓴 양이 안 왔으면 `exhausted` 가
+     * 비어 있고, 그때 막으면 선언하지 않은 현장의 라인이 통째로 굶는다.
+     */
+    if (ratedUsageOf(r).exhausted === true)
+        return { available: false, reason: 'worn-out' };
     if (at) {
         const ms = parsedMs(at);
         if (Number.isFinite(ms)) {

package/dist/index.d.ts

@@ -19,6 +19,7 @@ export * from './yms-profile.ts';
 export * from './canonical-record.ts';
 export * from './webhook.ts';
 export * from './oee.ts';
+export * from './rated-usage.ts';
 export * from './yield.ts';
 export * from './reliability.ts';
 export * from './erp.ts';

package/dist/index.js

@@ -41,6 +41,7 @@ export * from "./canonical-record.js";
 /* `webhook-signature.ts` 는 여기 없다 — `node:crypto` 를 쓰므로 `@operato/ops-contract/webhook` 으로만 나간다. */
 export * from "./webhook.js";
 export * from "./oee.js";
+export * from "./rated-usage.js";
 export * from "./yield.js";
 export * from "./reliability.js";
 export * from "./erp.js";

package/dist/oee.d.ts

@@ -11,8 +11,15 @@ export interface OeeCounters {
     setupMs: number;
     /** 고장(ADOT). */
     downMs: number;
+    /** 양품(GQ). */
     goodCount: number;
-    scrapCount: number;
+    /**
+     * **부적합 전체**(GQ 가 아닌 것 전부) — ISO 22400 의 **SQ 가 아니고 `SQ + RQ`** 다.
+     *
+     * 품질률 `GQ / (GQ + SQ + RQ)` 의 분모가 `goodCount + nonconformingCount` 로 정확히 맞는다.
+     * 예전 이름은 `scrapCount` 였고 폐기 수로 읽혔다 — §`QualityDelta`. vocabulary-guard: allow
+     */
+    nonconformingCount: number;
     /** 계획정지 — 계획 조업 시간에서 뺀다(점심·예방보전·교대). */
     holdMs?: number;
     /** 언제부터 쟀나. 없으면 잰 구간이 없는 것이고, 그때는 가동률을 낼 수 없다. */

package/dist/oee.js

@@ -33,7 +33,7 @@ export function computeOee(c, nowMs) {
     /* 대기는 남는 시간이다 — 계획 조업에서 생산·준비·고장을 뺀 것. 따로 재지 않아도 나온다. */
     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;
+    const produced = c.goodCount + c.nonconformingCount;
     if (produced <= 0)
         missing.push('produced-quantity');
     const quality = produced > 0 ? c.goodCount / produced : undefined;
@@ -57,6 +57,6 @@ export function computeOee(c, nowMs) {
         downMs: c.downMs,
         delayMs,
         goodCount: c.goodCount,
-        scrapCount: c.scrapCount
+        nonconformingCount: c.nonconformingCount
     };
 }

package/dist/operational-ingest.js

@@ -143,7 +143,7 @@ const SPECS = {
         matchOrder: 15,
         identity: 'moverId', // vocabulary-guard: allow 저널 와이어 필드
         /* 누적 카운터가 없으면 OEE 가 양품률을 못 센다 — 판정 하나만으로는 비율이 나오지 않는다. */
-        required: ['moverId', 'good', 'goodCount', 'scrapCount'], // vocabulary-guard: allow
+        required: ['moverId', 'good', 'goodCount', 'nonconformingCount'], // vocabulary-guard: allow
         /*
          * `taskId` 는 **귀속**이다 — 이 산출이 어느 작업의 것인가. 수량의 뜻은 바뀌지 않는다(설비 누적).
          *
@@ -153,7 +153,7 @@ const SPECS = {
          * 정체를 `taskId` 로 바꾸지 않는 이유는 OEE 가 설비 단위여서다. 정체를 옮기면 설비 누적을 셀 수
          * 없어진다.
          */
-        fields: { moverId: 'string', good: 'boolean', goodCount: 'number', scrapCount: 'number', taskId: 'string', recordTime: 'string' } // vocabulary-guard: allow
+        fields: { moverId: 'string', good: 'boolean', goodCount: 'number', nonconformingCount: 'number', taskId: 'string', recordTime: 'string' } // vocabulary-guard: allow
     },
     /*
      * **시험 결과** — 대상을 가리켜 들어온다(표준 `TestResult.TestableObjectID`).
@@ -400,7 +400,7 @@ export function ingestOperationalRecords(records, opts) {
                         errors.push(`${kind}.progress 는 0~1 비율이다: ${n}`);
                         break;
                     }
-                    if ((name === 'requested' || name === 'fulfilled' || name === 'goodCount' || name === 'scrapCount') && n < 0) {
+                    if ((name === 'requested' || name === 'fulfilled' || name === 'goodCount' || name === 'nonconformingCount') && n < 0) {
                         errors.push(`${kind}.${name} 가 음수다: ${n}`);
                         break;
                     }

package/dist/rated-usage.d.ts

@@ -0,0 +1,59 @@
+/** UN/CEFACT 권고 20 에서 **무차원 「하나」** — 「몇 번 썼나」의 단위. */
+export declare const USE_UOM = "C62";
+/** 정격 사용량 — 「얼마」와 「무엇으로」. */
+export interface RatedUsage {
+    /** 이만큼 쓰면 교체한다. 0 이나 음수는 정격이 아니다(§`ratedUsageOf`). */
+    limit: number;
+    /** 단위 — UN/CEFACT 권고 20. 「번」은 `USE_UOM`(`C62`), 길이는 `MTR` 등. */
+    uom: string;
+}
+/** 지금까지 쓴 양 — 정격과 **같은 단위여야** 견줄 수 있다. */
+export interface UsedUsage {
+    value: number;
+    uom: string;
+    /**
+     * 언제부터 센 것인가(ISO). 교정·오버홀이 자산을 처음 상태로 되돌리면 그 시각부터 다시 센다 —
+     * 되돌린 뒤에도 예전 양을 계속 세면 멀쩡한 지그가 정격 초과로 잠긴다.
+     *
+     * 없으면 「도입 이후 전체」로 읽는다. 그것은 짐작이 아니라 이 필드의 정의다.
+     */
+    since?: string;
+}
+/** 정격으로 판정할 수 없는 이유 — 「남은 것 0」으로 답하지 않는다. */
+export type RatedUsageMissing = 
+/** 정격을 선언하지 않았다. **무한이 아니라 모르는 것**이다 — 화면이 「제한 없음」으로 그리면 안 된다. */
+'not-declared'
+/** 정격이 0 이나 음수다 — 마스터가 잘못 적혔다. */
+ | 'invalid-limit'
+/** 쓴 양이 아직 없다 — 원천이 보내 주지 않았거나 아직 안 썼다. 둘을 여기서 가리지 않는다. */
+ | 'usage-unknown'
+/**
+ * 단위가 다르다 — **견주지 않는다.**
+ *
+ * 50미터 정격에 「120번 썼다」가 오면 답할 수 있는 것이 없다. 숫자만 견주면 120 > 50 이라
+ * 「수명 끝」이라고 말하는데, 그것은 참일 수도 거짓일 수도 있다.
+ */
+ | 'uom-mismatch';
+export interface RatedUsageStatus {
+    /** 정격 그대로. 없으면 없다. */
+    rated?: RatedUsage;
+    /** 쓴 양 그대로. 없으면 없다. */
+    used?: UsedUsage;
+    /** 남은 양 — **낼 수 없으면 없다.** */
+    remaining?: number;
+    /** 다 썼나 — 판정할 수 없으면 없다(`false` 가 아니다: 「아니다」와 「모른다」는 다르다). */
+    exhausted?: boolean;
+    /** 커널이 스스로 셀 수 있는 정격인가 — 「번」이면 참, 그 밖이면 거짓(§머리말). */
+    countable: boolean;
+    missing: RatedUsageMissing[];
+}
+/**
+ * 이 자원의 정격 사용 상태.
+ *
+ * **모르면 답하지 않는다.** 정격이 없으면 「무제한」이 아니고, 쓴 양이 없으면 「0」이 아니다. 둘 중
+ * 하나만 없어도 남은 양과 초과 여부를 내지 않는다 — 그때 화면은 「모른다」를 그려야 한다.
+ */
+export declare function ratedUsageOf(r: {
+    ratedUsage?: RatedUsage;
+    usedUsage?: UsedUsage;
+}): RatedUsageStatus;

package/dist/rated-usage.js

@@ -0,0 +1,60 @@
+/*
+ * **정격 사용량** — 소모 공구가 얼마를 쓰면 교체되나.
+ *
+ * ── 왜 필요한가 (2026-09-03, 미라텍 관리계획서) ─────────────────────────────
+ * 고객의 관리계획서가 공구마다 수명을 못 박아 둔다. 메탈마스크 5만 번, 스퀴즈 10만 번, EOL 프로브
+ * 핀 5만 번, 카메라 실리콘 패킹 10만 번, OQC 케이블 3만 번, **라우터 비트 50미터.**
+ *
+ * 트윈에 그 숫자를 담을 자리가 없었다. 그래서 정비 계획은 그것을 날수로 바꿔서 들고 있었다 —
+ * 「핀 5만 번 ÷ 하루 69대 = 720일」. 그 환산은 **생산량이 바뀌는 순간 틀리고**, 틀렸다는 것을
+ * 아무도 모른다. 라인을 증설하면 실제 수명은 반으로 줄지만 계획은 여전히 720일을 말한다.
+ *
+ * ── 단위를 함께 드는 이유 ────────────────────────────────────────────────────
+ * 여섯 중 다섯은 「번」이고 하나는 「미터」다. 숫자만 담는 칸에 라우터 비트를 넣으면 **50미터가
+ * 50번이 된다.** 한 번에 0.2미터를 깎는 공정이라면 실제 수명의 250분의 1에서 교체하라고 말하는
+ * 셈이다. 그래서 정격은 늘 「얼마」와 「무엇으로」 둘을 든다.
+ *
+ * 단위 어휘는 다른 자리와 같다 — UN/CEFACT 권고 20(§`MaterialQuantity.uom`).
+ *
+ * ── 커널이 스스로 셀 수 있는 경우와 없는 경우 ────────────────────────────────
+ * 정격이 「번」이면 작업이 끝날 때마다 하나 늘리면 된다. **「미터」면 늘릴 수 없다** — 그 작업이
+ * 몇 미터를 깎았는지는 공정이 말해 줘야 하는 사실이고, 커널이 「한 번이니 1미터」로 놓으면 그것은
+ * 지어낸 값이다.
+ *
+ * 그래서 커널은 셀 수 있는 것만 세고, 못 세는 것은 **못 센다고 말한다**(`countable`). 값이 오지
+ * 않으면 사용량은 비어 있고, 비어 있는 것은 0이 아니다.
+ */
+/** UN/CEFACT 권고 20 에서 **무차원 「하나」** — 「몇 번 썼나」의 단위. */
+export const USE_UOM = 'C62';
+const num = (n) => typeof n === 'number' && Number.isFinite(n);
+/**
+ * 이 자원의 정격 사용 상태.
+ *
+ * **모르면 답하지 않는다.** 정격이 없으면 「무제한」이 아니고, 쓴 양이 없으면 「0」이 아니다. 둘 중
+ * 하나만 없어도 남은 양과 초과 여부를 내지 않는다 — 그때 화면은 「모른다」를 그려야 한다.
+ */
+export function ratedUsageOf(r) {
+    const rated = r?.ratedUsage;
+    const used = r?.usedUsage;
+    const missing = [];
+    /* 셀 수 있는지는 정격의 단위만으로 정해진다 — 쓴 양이 아직 없어도 답할 수 있다. */
+    const countable = rated?.uom === USE_UOM;
+    if (!rated)
+        missing.push('not-declared');
+    else if (!num(rated.limit) || rated.limit <= 0)
+        missing.push('invalid-limit');
+    if (!used || !num(used.value))
+        missing.push('usage-unknown');
+    if (rated && used && rated.uom !== used.uom)
+        missing.push('uom-mismatch');
+    const out = {
+        ...(rated ? { rated } : {}),
+        ...(used ? { used } : {}),
+        countable,
+        missing
+    };
+    if (missing.length)
+        return out;
+    const remaining = Math.max(0, rated.limit - used.value);
+    return { ...out, remaining, exhausted: used.value >= rated.limit };
+}

package/dist/vocabulary.d.ts

@@ -8,7 +8,7 @@
  * (문서 쪽은 `test/doc-vocabulary-guard.test.ts` 가 **자기 목록**으로 본다 — 이 목록의 `node`·`mover` 는
  *  ADR 기록이 없어 문서의 개념 명사에까지 들이대지 않는다.)
  */
-export declare const RETIRED_VOCABULARY: readonly ["mover", "Mover", "MOVER", "node", "Node", "NODE", "BoardDef", "loadBoard"];
+export declare const RETIRED_VOCABULARY: readonly ["mover", "Mover", "MOVER", "node", "Node", "NODE", "BoardDef", "loadBoard", "scrapCount"];
 /**
  * 예외 — 남아 있는 것이 **정당한** 토큰. 각 항목에 이유가 붙는다.
  *

package/dist/vocabulary.js

@@ -20,7 +20,7 @@
  * (문서 쪽은 `test/doc-vocabulary-guard.test.ts` 가 **자기 목록**으로 본다 — 이 목록의 `node`·`mover` 는
  *  ADR 기록이 없어 문서의 개념 명사에까지 들이대지 않는다.)
  */
-export const RETIRED_VOCABULARY = ['mover', 'Mover', 'MOVER', 'node', 'Node', 'NODE', 'BoardDef', 'loadBoard'];
+export const RETIRED_VOCABULARY = ['mover', 'Mover', 'MOVER', 'node', 'Node', 'NODE', 'BoardDef', 'loadBoard', 'scrapCount'];
 /**
  * 예외 — 남아 있는 것이 **정당한** 토큰. 각 항목에 이유가 붙는다.
  *

package/dist-cjs/index.cjs

@@ -66,6 +66,7 @@ __export(index_exports, {
   TWIN_AXES: () => TWIN_AXES,
   TWIN_PROPERTIES: () => TWIN_PROPERTIES,
   TWIN_RELATIONS: () => TWIN_RELATIONS,
+  USE_UOM: () => USE_UOM,
   UTC_OFFSET: () => UTC_OFFSET,
   VOCABULARY_EXCEPTIONS: () => VOCABULARY_EXCEPTIONS,
   VOCABULARY_TYPE: () => VOCABULARY_TYPE,
@@ -107,6 +108,7 @@ __export(index_exports, {
   dueStatusOf: () => dueStatusOf,
   effectivityAt: () => effectivityAt,
   electricalUpstreamOf: () => electricalUpstreamOf,
+  equipmentClassMembership: () => equipmentClassMembership,
   erpCapabilityGaps: () => erpCapabilityGaps,
   expiryFromAttributes: () => expiryFromAttributes,
   gdtiUri: () => gdtiUri,
@@ -182,6 +184,7 @@ __export(index_exports, {
   procedureViolations: () => procedureViolations,
   propertiesOf: () => propertiesOf,
   quantityIn: () => quantityIn,
+  ratedUsageOf: () => ratedUsageOf,
   readBoardAssets: () => readBoardAssets,
   readBoardEquipment: () => readBoardEquipment,
   readBoardLocations: () => readBoardLocations,
@@ -352,6 +355,29 @@ function commandsOf(caps) {
   return [...out];
 }
 
+// src/rated-usage.ts
+var USE_UOM = "C62";
+var num = (n) => typeof n === "number" && Number.isFinite(n);
+function ratedUsageOf(r) {
+  const rated = r?.ratedUsage;
+  const used = r?.usedUsage;
+  const missing = [];
+  const countable = rated?.uom === USE_UOM;
+  if (!rated) missing.push("not-declared");
+  else if (!num(rated.limit) || rated.limit <= 0) missing.push("invalid-limit");
+  if (!used || !num(used.value)) missing.push("usage-unknown");
+  if (rated && used && rated.uom !== used.uom) missing.push("uom-mismatch");
+  const out = {
+    ...rated ? { rated } : {},
+    ...used ? { used } : {},
+    countable,
+    missing
+  };
+  if (missing.length) return out;
+  const remaining = Math.max(0, rated.limit - used.value);
+  return { ...out, remaining, exhausted: used.value >= rated.limit };
+}
+
 // src/contract.ts
 var ORDER_TERMINAL_STATUS = ["completed", "cancelled"];
 function isOrderTerminal(o) {
@@ -577,6 +603,12 @@ function classClosure(directIds, defs, at2) {
   }
   return out;
 }
+function equipmentClassMembership(e) {
+  const out = [];
+  for (const id of e?.equipmentClassIds ?? []) if (id && !out.includes(id)) out.push(id);
+  if (e?.kind && !out.includes(e.kind)) out.push(e.kind);
+  return out;
+}
 var PRIORITY_UNSET = Number.POSITIVE_INFINITY;
 function priorityRank(p) {
   return typeof p === "number" && Number.isFinite(p) ? p : PRIORITY_UNSET;
@@ -757,6 +789,7 @@ function capabilityOf(r, ctx) {
   if (eff === "expired") return { available: false, reason: "retired" };
   if (r.held) return { available: false, reason: "held" };
   if (r.status === "down") return { available: false, reason: "down" };
+  if (ratedUsageOf(r).exhausted === true) return { available: false, reason: "worn-out" };
   if (at2) {
     const ms = parsedMs(at2);
     if (Number.isFinite(ms)) {
@@ -2070,7 +2103,7 @@ function ingestEnergyRecords(records, opts) {
     const at2 = String(record?.at ?? "").trim() || opts.defaultEventTime;
     const atMs = at2 ? Date.parse(at2) : Number.NaN;
     if (!Number.isFinite(atMs)) errors.push("at \uC5C6\uC74C/\uD615\uC2DD \uC624\uB958 \u2014 \uC9C0\uAE08 \uC2DC\uAC01\uC73C\uB85C \uBA54\uC6B0\uBA74 \uB0A8\uC758 \uC218\uC694 \uAD6C\uAC04\uC5D0 \uC2E4\uB9B0\uB2E4");
-    const num = (v, name) => {
+    const num2 = (v, name) => {
       if (v === void 0 || v === null || v === "") return void 0;
       const n = Number(v);
       if (!Number.isFinite(n)) {
@@ -2079,9 +2112,9 @@ function ingestEnergyRecords(records, opts) {
       }
       return n;
     };
-    const kW = num(record?.kW, "kW");
-    const kWh = num(record?.kWh, "kWh");
-    const powerFactor = num(record?.powerFactor, "powerFactor");
+    const kW = num2(record?.kW, "kW");
+    const kWh = num2(record?.kWh, "kWh");
+    const powerFactor = num2(record?.powerFactor, "powerFactor");
     if (errors.length) {
       rejected.push({ record, errors });
       continue;
@@ -2126,7 +2159,7 @@ function ingestEnergyEquipmentRecords(records, opts) {
     const at2 = String(r?.at ?? "").trim() || opts.defaultEventTime;
     const atMs = at2 ? Date.parse(at2) : Number.NaN;
     if (!Number.isFinite(atMs)) errors.push("at \uC5C6\uC74C/\uD615\uC2DD \uC624\uB958 \u2014 \uC9C0\uAE08 \uC2DC\uAC01\uC73C\uB85C \uBA54\uC6B0\uBA74 \uC5B8\uC81C\uC758 \uC0C1\uD0DC\uC778\uC9C0 \uC54C \uC218 \uC5C6\uB2E4");
-    const num = (v, name, min, max) => {
+    const num2 = (v, name, min, max) => {
       if (v === void 0 || v === null || v === "") return void 0;
       const n = Number(v);
       if (!Number.isFinite(n)) {
@@ -2143,19 +2176,19 @@ function ingestEnergyEquipmentRecords(records, opts) {
       }
       return n;
     };
-    const generatedKW = num(r?.generatedKW, "generatedKW", 0);
-    const exportKW = num(r?.exportKW, "exportKW");
-    const soc = num(r?.soc, "soc", 0, 100);
-    const chargeKW = num(r?.chargeKW, "chargeKW", 0);
-    const dischargeKW = num(r?.dischargeKW, "dischargeKW", 0);
-    const minKW = num(r?.minKW, "minKW", 0);
+    const generatedKW = num2(r?.generatedKW, "generatedKW", 0);
+    const exportKW = num2(r?.exportKW, "exportKW");
+    const soc = num2(r?.soc, "soc", 0, 100);
+    const chargeKW = num2(r?.chargeKW, "chargeKW", 0);
+    const dischargeKW = num2(r?.dischargeKW, "dischargeKW", 0);
+    const minKW = num2(r?.minKW, "minKW", 0);
     let curtailable;
     if (r?.curtailable !== void 0 && r?.curtailable !== null) {
       if (typeof r.curtailable !== "boolean") errors.push(`curtailable \uAC00 \uCC38/\uAC70\uC9D3\uC774 \uC544\uB2C8\uB2E4: ${JSON.stringify(r.curtailable)}`);
       else curtailable = r.curtailable;
     }
-    const dcVoltage = num(r?.dcVoltage, "dcVoltage", 0);
-    const dcCurrent = num(r?.dcCurrent, "dcCurrent", 0);
+    const dcVoltage = num2(r?.dcVoltage, "dcVoltage", 0);
+    const dcCurrent = num2(r?.dcCurrent, "dcCurrent", 0);
     const phases = (raw, name) => {
       if (raw === void 0 || raw === null) return void 0;
       if (!Array.isArray(raw)) {
@@ -3371,7 +3404,7 @@ var SPECS = {
     identity: "moverId",
     // vocabulary-guard: allow 저널 와이어 필드
     /* 누적 카운터가 없으면 OEE 가 양품률을 못 센다 — 판정 하나만으로는 비율이 나오지 않는다. */
-    required: ["moverId", "good", "goodCount", "scrapCount"],
+    required: ["moverId", "good", "goodCount", "nonconformingCount"],
     // vocabulary-guard: allow
     /*
      * `taskId` 는 **귀속**이다 — 이 산출이 어느 작업의 것인가. 수량의 뜻은 바뀌지 않는다(설비 누적).
@@ -3382,7 +3415,7 @@ var SPECS = {
      * 정체를 `taskId` 로 바꾸지 않는 이유는 OEE 가 설비 단위여서다. 정체를 옮기면 설비 누적을 셀 수
      * 없어진다.
      */
-    fields: { moverId: "string", good: "boolean", goodCount: "number", scrapCount: "number", taskId: "string", recordTime: "string" }
+    fields: { moverId: "string", good: "boolean", goodCount: "number", nonconformingCount: "number", taskId: "string", recordTime: "string" }
     // vocabulary-guard: allow
   },
   /*
@@ -3614,7 +3647,7 @@ function ingestOperationalRecords(records, opts) {
             errors.push(`${kind}.progress \uB294 0~1 \uBE44\uC728\uC774\uB2E4: ${n}`);
             break;
           }
-          if ((name === "requested" || name === "fulfilled" || name === "goodCount" || name === "scrapCount") && n < 0) {
+          if ((name === "requested" || name === "fulfilled" || name === "goodCount" || name === "nonconformingCount") && n < 0) {
             errors.push(`${kind}.${name} \uAC00 \uC74C\uC218\uB2E4: ${n}`);
             break;
           }
@@ -3790,7 +3823,7 @@ function validateScenario(def) {
 }
 
 // src/vocabulary.ts
-var RETIRED_VOCABULARY = ["mover", "Mover", "MOVER", "node", "Node", "NODE", "BoardDef", "loadBoard"];
+var RETIRED_VOCABULARY = ["mover", "Mover", "MOVER", "node", "Node", "NODE", "BoardDef", "loadBoard", "scrapCount"];
 var VOCABULARY_EXCEPTIONS = [
   /* ── 저널 와이어 필드 — append-only 역사이므로 이름을 바꾸지 않는다 ───────
    * 같은 사실이 시점에 따라 다른 키로 들어가면 낡은 이름보다 나쁘다. 개명은 이벤트 스키마
@@ -3894,7 +3927,7 @@ function computeOee(c, nowMs) {
   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;
+  const produced = c.goodCount + c.nonconformingCount;
   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");
@@ -3912,7 +3945,7 @@ function computeOee(c, nowMs) {
     downMs: c.downMs,
     delayMs,
     goodCount: c.goodCount,
-    scrapCount: c.scrapCount
+    nonconformingCount: c.nonconformingCount
   };
 }
 
@@ -4216,6 +4249,7 @@ function commandSpecGaps(specs, command) {
   TWIN_AXES,
   TWIN_PROPERTIES,
   TWIN_RELATIONS,
+  USE_UOM,
   UTC_OFFSET,
   VOCABULARY_EXCEPTIONS,
   VOCABULARY_TYPE,
@@ -4257,6 +4291,7 @@ function commandSpecGaps(specs, command) {
   dueStatusOf,
   effectivityAt,
   electricalUpstreamOf,
+  equipmentClassMembership,
   erpCapabilityGaps,
   expiryFromAttributes,
   gdtiUri,
@@ -4332,6 +4367,7 @@ function commandSpecGaps(specs, command) {
   procedureViolations,
   propertiesOf,
   quantityIn,
+  ratedUsageOf,
   readBoardAssets,
   readBoardEquipment,
   readBoardLocations,

package/package.json

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