@operato/ops-contract 0.5.0 → 0.7.0

package/dist/contract.d.ts

@@ -1333,6 +1333,26 @@ export interface ItemState {
      * 자리의 관측을 속성당 하나만 든 것과 같은 규율이다(§`LocationState.observations`).
      */
     testResults?: TestResult[];
+    /**
+     * **부적합 처분** — 이 로트를 어떻게 하기로 정했나(폐기 · 재작업 · 특채 · 보류…).
+     *
+     * ── 이름이 `disposition` 이 아닌 이유 ─────────────────────────────────────
+     * 바로 위의 `disposition` 은 **EPCIS 의 것**이다(`urn:epcglobal:cbv:disp:…` — 이 물품이 지금 어떤
+     * 처지인가). 이것은 **ISA-95 의 것**이다(부적합을 어떻게 할지 사람이 정한 결정). 두 표준이 같은
+     * 낱말을 다른 뜻으로 쓴다.
+     *
+     * 한 이름에 두 뜻을 담으면 어느 표준을 말하는지 읽는 쪽이 알 수 없다. 사건 이름이 이미
+     * `nonconformance.disposition` 이므로 그 앞머리를 쓴다.
+     *
+     * ── 표준에서 왜 여기인가 ──────────────────────────────────────────────────
+     * `MaterialLotType`(B2MML-Material.xsd)이 로트 안에 `Disposition` 을 든다. 시험 결과와 달리 이것은
+     * 표준에서도 로트의 속성이다 — 판정은 대상을 가리키는 별개 기록이고, 처분은 그 대상이 지금 무엇이
+     * 되었나이기 때문이다.
+     *
+     * **마지막 하나만 든다.** 「언제 무엇으로 정했는지」의 이력은 저널이 답하고, 상태가 답하는 것은
+     * 「이 로트가 지금 어떤 것이냐」다. 시험 결과를 명세당 하나만 든 것과 같은 규율이다.
+     */
+    nonconformance?: DispositionFact;
     /** 소속 물류단위(팔레트 SSCC 등) — AggregationEvent 로 맺어진다. 3D 적재 표현의 재료. */
     parent?: string;
     /**
@@ -3048,12 +3068,39 @@ export interface AssetStatusDelta extends EffectivePeriod {
     taskId?: string;
     carrying?: string;
 }
+/**
+ * **마감된 설비 상태 구간** — 이 설비가 이 구간 동안 이 상태였다.
+ *
+ * 시점의 전이(`EquipmentStatusDelta`)와 다른 사실이다. 전이는 「지금 이 상태로 바뀌었다」이고 이것은
+ * 「그 구간 동안 그 상태였다」다. 되돌아가 적는 사실이라 사건 시각이 `to` 다.
+ *
+ * 셋을 전이로 담을 수 없다 — 사유가 붙을 자리가 없고(기계가 서는 순간에는 왜 섰는지 아무도 모른다),
+ * 계획·비계획을 나중에 정하며, 전이를 내지 않는 정지(자재 대기 · 작업자 부재)가 많다.
+ */
+export interface EquipmentStatePeriodFact {
+    moverId: string;
+    /** `busy` · `setup` · `down` · `idle` · `planned-stop` — ISO 22400 의 시간 모델을 덮는다. */
+    status: string;
+    from: ISOTime;
+    to: ISOTime;
+    /** 사람이 정한 사유. 없을 수 있다 — 적지 않은 것과 사유가 없는 것은 다르므로 지어내지 않는다. */
+    reasonCode?: string;
+    decidedBy?: string;
+    recordTime?: ISOTime;
+}
 /** 품질 산출 델타 — recordOutput(양품/불량) 시 방출. goodCount/scrapCount 는 설비 누적값. */
 export interface QualityDelta {
     moverId: string;
     good: boolean;
     goodCount: number;
     scrapCount: number;
+    /**
+     * 이 산출이 어느 작업의 것인가 — **귀속이고, 수량의 뜻을 바꾸지 않는다**(설비 누적 그대로).
+     *
+     * 현장에서 실적을 올리는 단위는 작업인데 이 갈래의 정체는 설비다. 귀속이 없으면 두 사실이 만나는
+     * 자리가 없어 「이 작업에서 몇 개 나왔나」를 저널에서 되짚을 수 없다.
+     */
+    taskId?: string;
 }
 export interface TaskStatusDelta {
     taskId: string;
@@ -3256,6 +3303,8 @@ export interface TwinModelDef {
     /** parallelism = 동시 처리 수(LocationState.parallelism 참조). capacity 는 저장 용량. */
     locations: (EffectivePeriod & {
         id: string;
+        name?: string;
+        gs1Id?: string;
         type: string;
         capacity: number;
         parallelism?: number;
@@ -3269,6 +3318,7 @@ export interface TwinModelDef {
      */
     equipment: (EffectivePeriod & {
         id: string;
+        name?: string;
         kind: string;
         homeLocation: string;
         identity?: string;

package/dist/domain-definition.d.ts

@@ -133,6 +133,7 @@ export interface DurationVariability {
 export interface OperationDef extends EffectivePeriod {
     key: string;
     label: string;
+    name?: string;
     intent: OperationIntent;
     /** 오퍼레이션이 수행되는 자리 타입(LocationTypeDef.key). 커널이 locationByType 로 위치 해소. */
     locationType?: string;

package/dist/index.d.ts

@@ -17,5 +17,6 @@ export * from './vocabulary.ts';
 export * from './wms-profile.ts';
 export * from './yms-profile.ts';
 export * from './canonical-record.ts';
+export * from './webhook.ts';
 export * from './version.ts';
 export * from './oee.ts';

package/dist/index.js

@@ -38,5 +38,7 @@ export * from "./vocabulary.js";
 export * from "./wms-profile.js";
 export * from "./yms-profile.js";
 export * from "./canonical-record.js";
+/* `webhook-signature.ts` 는 여기 없다 — `node:crypto` 를 쓰므로 `@operato/ops-contract/webhook` 으로만 나간다. */
+export * from "./webhook.js";
 export * from "./version.js";
 export * from "./oee.js";

package/dist/operational-ingest.js

@@ -60,6 +60,8 @@ const ASSET_STATUS = ['idle', 'in-use'];
 const SPECS = {
     task: {
         eventType: OP_EVENT.task,
+        match: ['taskId'],
+        matchOrder: 50,
         identity: 'taskId',
         /* 종류가 없으면 성과를 종류별로 모을 수 없고(선언된 시간·수율이 종류로 붙는다) 지어낼 수도 없다. */
         required: ['taskId', 'kind', 'status'],
@@ -79,6 +81,8 @@ const SPECS = {
     },
     equipment: {
         eventType: OP_EVENT.equipment,
+        match: ['moverId'],
+        matchOrder: 20,
         identity: 'moverId', // vocabulary-guard: allow 저널 와이어 필드(델타의 이름이 계약이다)
         required: ['moverId', 'kind', 'status'], // vocabulary-guard: allow 위와 같은 이유
         fields: {
@@ -94,6 +98,8 @@ const SPECS = {
     },
     person: {
         eventType: OP_EVENT.person,
+        match: ['personId'],
+        matchOrder: 30,
         identity: 'personId',
         required: ['personId', 'status'],
         fields: {
@@ -104,6 +110,8 @@ const SPECS = {
     },
     asset: {
         eventType: OP_EVENT.asset,
+        match: ['assetId'],
+        matchOrder: 40,
         identity: 'assetId',
         required: ['assetId', 'status'],
         fields: {
@@ -114,6 +122,8 @@ const SPECS = {
     },
     order: {
         eventType: OP_EVENT.order,
+        match: ['orderId'],
+        matchOrder: 60,
         identity: 'orderId',
         /*
          * 요청량·이행량을 **함께** 받는다. 없으면 리듀서가 진척을 0 으로 적는데(`requested ? … : 0`),
@@ -129,10 +139,21 @@ const SPECS = {
     },
     quality: {
         eventType: OP_EVENT.quality,
+        match: ['moverId', 'good'],
+        matchOrder: 15,
         identity: 'moverId', // vocabulary-guard: allow 저널 와이어 필드
         /* 누적 카운터가 없으면 OEE 가 양품률을 못 센다 — 판정 하나만으로는 비율이 나오지 않는다. */
         required: ['moverId', 'good', 'goodCount', 'scrapCount'], // vocabulary-guard: allow
-        fields: { moverId: 'string', good: 'boolean', goodCount: 'number', scrapCount: 'number', recordTime: 'string' } // vocabulary-guard: allow
+        /*
+         * `taskId` 는 **귀속**이다 — 이 산출이 어느 작업의 것인가. 수량의 뜻은 바뀌지 않는다(설비 누적).
+         *
+         * 왜 필요한가: 작업자가 올리는 실적은 작업 단위인데 이 갈래의 정체는 설비뿐이라, 두 사실이 만나는
+         * 자리가 없었다. 귀속이 없으면 「이 작업에서 몇 개 나왔나」를 저널에서 되짚을 방법이 없다.
+         *
+         * 정체를 `taskId` 로 바꾸지 않는 이유는 OEE 가 설비 단위여서다. 정체를 옮기면 설비 누적을 셀 수
+         * 없어진다.
+         */
+        fields: { moverId: 'string', good: 'boolean', goodCount: 'number', scrapCount: 'number', taskId: 'string', recordTime: 'string' } // vocabulary-guard: allow
     },
     /*
      * **시험 결과** — 대상을 가리켜 들어온다(표준 `TestResult.TestableObjectID`).
@@ -170,6 +191,8 @@ const SPECS = {
      */
     'equipment-period': {
         eventType: OP_EVENT.equipmentPeriod,
+        match: ['moverId', 'status', 'from', 'to'],
+        matchOrder: 10,
         identity: 'moverId', // vocabulary-guard: allow 저널 와이어 필드 — 전이와 같은 이름을 쓴다
         required: ['moverId', 'status', 'from', 'to'], // vocabulary-guard: allow 위와 같은 이유
         fields: {
@@ -196,6 +219,8 @@ const SPECS = {
      */
     disposition: {
         eventType: OP_EVENT.disposition,
+        match: ['subjectId', 'decision'],
+        matchOrder: 80,
         identity: 'subjectId',
         /* 무엇을 어떻게 하기로 했나 — 둘 중 하나가 없으면 그 결정은 아무 데도 붙지 못한다. */
         required: ['subjectId', 'decision'],
@@ -207,6 +232,8 @@ const SPECS = {
     },
     test: {
         eventType: OP_EVENT.test,
+        match: ['testableObjectId'],
+        matchOrder: 70,
         identity: 'testableObjectId',
         /* 무엇을 어느 기준으로 시험했나 — 둘 중 하나가 없으면 그 결과는 아무 데도 붙지 못한다. */
         required: ['testableObjectId', 'specId'],
@@ -234,12 +261,16 @@ const SPECS = {
      */
     complete: {
         eventType: OP_EVENT.complete,
+        match: ['completeAxis'],
+        matchOrder: 100,
         identity: 'completeAxis',
         required: ['completeAxis', 'since'],
         fields: { completeAxis: 'string', since: 'string', recordTime: 'string' }
     },
     observation: {
         eventType: OP_EVENT.observation,
+        match: ['locationId', 'propertyId'],
+        matchOrder: 90,
         identity: 'locationId',
         /* 자리와 속성 — 둘 중 하나가 없으면 그 관측은 아무 데도 붙지 못한다. */
         required: ['locationId', 'propertyId'],
@@ -268,68 +299,34 @@ export function operationalKindOf(record) {
     if (!record || typeof record !== 'object')
         return undefined;
     const r = record;
-    if (r.epc !== undefined || r.meterId !== undefined || r.equipmentId !== undefined)
-        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'))
-        return 'person';
-    if (has('assetId'))
-        return 'asset';
-    if (has('taskId'))
-        return 'task'; // 작업이 든 `orderId` 는 소속(참조)이다
-    if (has('orderId'))
-        return 'order';
-    /*
-     * ── ★ **채널을 열고 들어오는 길을 내지 않았다** (2026-08-24) ─────────────────
-     * `OP_EVENT.test` 를 계약에 냈는데 이 라우팅이 `testableObjectId` 를 보지 않았다. 그래서 커넥터의
-     * 시험 결과가 **어느 통도 아니어서 조용히 버려졌다** — 거부 목록에도 남지 않았다(운영 경로를 아예
-     * 지나지 않으므로).
-     *
-     * 같은 부류가 하루에 세 번 났다: `ilmd`(매핑에 자리 없음) · 사건 시각(이름 어긋남) · 그리고 이것.
-     * **계약에 자리를 만드는 것과 그 자리로 가는 길을 내는 것은 다른 일이다.** 앞의 것만 하면 보내는
-     * 쪽에는 「실었다」로 보이고 화면에는 「없다」로 보인다.
-     *
-     * 순서상 뒤에 둔다 — 시험 결과가 작업·오더를 함께 가리킬 수 있고, 그때 그것은 **그 작업의 사실**이다.
-     */
-    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`)와 조회
-     * (`observationAt`)까지 붙였는데 **이 라우팅이 `locationId` 를 보지 않았다.** 커넥터가 방의 온습도를
-     * 실어 보내면 「어느 운영 사실인지 모른다」로 거부됐다.
-     *
-     * 같은 부류를 하루에 일곱 번 만났다. 다만 이번엔 **거부되고 이유가 남았다** — 시험 결과 때는 어느
-     * 통도 아니어서 조용히 사라졌다. 그 차이가 이것을 5분 만에 찾게 했다(§`isOperationalRecord`).
-     *
-     * **둘을 함께 요구한다.** `locationId` 만으로는 자리를 말하는 다른 사실과 섞인다. 관측은 「어느
-     * 자리의 **무엇**을 쟀나」이므로 속성 없이는 담을 곳이 없다 — 그때는 받지 않는 것이 옳다.
+     * EPCIS·에너지와 겹치지 않게 본다: `epc`·`meterId` 가 있으면 그쪽 어휘이고, `equipmentId` 는 설비
+     * **에너지** 상태의 이름이다(운영 설비는 `moverId`).
      */
-    if (has('locationId') && has('propertyId'))
-        return 'observation';
-    /* 「이 목록이 전부다」 — 어느 목록인지를 스스로 말하므로 다른 사실과 섞이지 않는다. */
-    if (has('completeAxis'))
-        return 'complete';
+    if (r.epc !== undefined || r.meterId !== undefined || r.equipmentId !== undefined)
+        return undefined;
+    /* 문자열은 비어 있으면 없는 것으로 본다 — 공백만 실은 필드는 말한 것이 아니다. */
+    const present = (k) => {
+        const v = r[k];
+        if (v === undefined || v === null)
+            return false;
+        return typeof v === 'string' ? v.trim().length > 0 : true;
+    };
+    for (const kind of MATCH_ORDER) {
+        const spec = SPECS[kind];
+        const fields = spec.match ?? [spec.identity];
+        if (fields.every(present))
+            return kind;
+    }
     return undefined;
 }
+/**
+ * 판정 순서 — 표의 `matchOrder` 에서 한 번만 만든다.
+ *
+ * 좁은 것이 먼저다. 그리고 자원(설비·사람·자산)을 작업보다, 작업을 오더보다 먼저 본다 — 정체 필드는
+ * 하나만 오지 않고, 아무거나 먼저 보면 **참조를 주체로 읽는다**(설비 델타가 든 `taskId` 는 소속이다).
+ */
+const MATCH_ORDER = Object.keys(SPECS).sort((a, b) => (SPECS[a].matchOrder ?? 1000) - (SPECS[b].matchOrder ?? 1000));
 /** 이 레코드가 운영 사실인가 — 호스트의 라우팅이 묻는 자리. */
 export function isOperationalRecord(record) {
     return operationalKindOf(record) !== undefined;

package/dist/version.d.ts

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

package/dist/version.js

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

package/dist/webhook-signature.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 헤더 이름.
+ *
+ * `mes` 가 아니라 `ops` 인 이유는 이 계약이 한 제품의 것이 아니기 때문이다 — operato-wms 가 같은
+ * 아웃박스를 쓰게 되어 있고, 커넥터도 제품을 가리지 않는다. 패키지 이름에 `twin` 이 없는 것과 같은
+ * 이유다.
+ */
+export declare const WEBHOOK_HEADER: {
+    /** 보내는 쪽이 누구인가. 사람이 로그에서 읽는 용도이고, 어디로 갈지는 주소가 정한다. */
+    readonly source: "x-ops-source";
+    /** 서명에 들어간 시각(RFC 3339). */
+    readonly timestamp: "x-ops-timestamp";
+    /** HMAC-SHA256 hex. */
+    readonly signature: "x-ops-signature";
+};
+/** 서명 창 기본값 — 5분. 양쪽 시계 차이와 재전송을 함께 감당하는 폭이다. */
+export declare const WEBHOOK_TOLERANCE_MS: number;
+/**
+ * 서명 대상 문자열 — **시각과 본문을 점 하나로 잇는다.**
+ *
+ * 본문만 서명하면 같은 요청을 나중에 그대로 다시 보낼 수 있다. 시각을 함께 서명해야 창 밖의 요청을
+ * 거절할 수 있다.
+ */
+export declare function webhookSigningInput(timestamp: string, body: string): string;
+/** 서명을 만든다 — hex. */
+export declare function signWebhook(secret: string, timestamp: string, body: string): string;
+/** 서명이 맞지 않는 이유 — 401 을 받은 쪽이 무엇을 고쳐야 하는지 알 수 있게 나눈다. */
+export type WebhookSignatureFailure = 'no-secret' | 'no-signature' | 'no-timestamp' | 'bad-timestamp' | 'expired' | 'mismatch';
+export type WebhookSignatureVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    reason: WebhookSignatureFailure;
+};
+/**
+ * 서명을 확인한다.
+ *
+ * `nowMs` 를 인자로 받는다 — 안에서 현재 시각을 읽으면 시험이 시계에 매인다.
+ *
+ * **본문은 받은 바이트 그대로여야 한다.** 파싱한 객체를 다시 문자열로 만들면 키 순서와 공백이 달라져
+ * 서명이 맞지 않는다. 받은 바이트를 들고 있지 않으면 확인할 수 없고, 그때는 확인한 척하지 말고
+ * 거절해야 한다.
+ */
+export declare function verifyWebhookSignature(args: {
+    secret: string;
+    timestamp: string;
+    signature: string;
+    body: string;
+    nowMs: number;
+    toleranceMs?: number;
+}): WebhookSignatureVerdict;

package/dist/webhook-signature.js

@@ -0,0 +1,81 @@
+/*
+ * **밀어 주는 연동의 서명** — 보내는 쪽과 받는 쪽이 같은 문자열에 서명해야 한다.
+ *
+ * ── 왜 계약에 있나 (2026-08-31) ──────────────────────────────────────────
+ * 서명은 양쪽이 **한 글자까지 같은 규칙**을 써야 성립한다. 한쪽이 이어붙이는 순서를 바꾸면 다른 쪽은
+ * 401 만 보고 이유를 알 수 없다. 그래서 만드는 함수와 확인하는 함수가 한 파일에 있어야 한다.
+ *
+ * 실제로 operato-mes 안에 `sign` 과 `verifySignature` 가 함께 있었는데, `verifySignature` 는 저장소
+ * 어디에서도 불리지 않았다 — 확인할 수신부가 없었기 때문이다. 확인하는 쪽이 생기면서 그 함수의 자리가
+ * 여기가 됐다.
+ *
+ * ── 왜 색인에 없나 ───────────────────────────────────────────────────────
+ * `node:crypto` 를 쓴다. 색인(`index.ts`)에 실으면 이 패키지를 쓰는 브라우저 번들이 `node:crypto` 를
+ * 묶으려다 실패한다. 그래서 `@operato/ops-contract/webhook` 으로만 나간다.
+ *
+ * ── 왜 평문 비밀값만으로는 부족한가 ─────────────────────────────────────
+ * 헤더에 비밀값을 그대로 실으면 그 요청을 그대로 다시 보내는 것을 막을 수 없다. 시각을 서명에 넣고
+ * 창 밖의 시각을 거절하면 그 재사용이 막힌다.
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+/**
+ * 헤더 이름.
+ *
+ * `mes` 가 아니라 `ops` 인 이유는 이 계약이 한 제품의 것이 아니기 때문이다 — operato-wms 가 같은
+ * 아웃박스를 쓰게 되어 있고, 커넥터도 제품을 가리지 않는다. 패키지 이름에 `twin` 이 없는 것과 같은
+ * 이유다.
+ */
+export const WEBHOOK_HEADER = {
+    /** 보내는 쪽이 누구인가. 사람이 로그에서 읽는 용도이고, 어디로 갈지는 주소가 정한다. */
+    source: 'x-ops-source',
+    /** 서명에 들어간 시각(RFC 3339). */
+    timestamp: 'x-ops-timestamp',
+    /** HMAC-SHA256 hex. */
+    signature: 'x-ops-signature'
+};
+/** 서명 창 기본값 — 5분. 양쪽 시계 차이와 재전송을 함께 감당하는 폭이다. */
+export const WEBHOOK_TOLERANCE_MS = 5 * 60_000;
+/**
+ * 서명 대상 문자열 — **시각과 본문을 점 하나로 잇는다.**
+ *
+ * 본문만 서명하면 같은 요청을 나중에 그대로 다시 보낼 수 있다. 시각을 함께 서명해야 창 밖의 요청을
+ * 거절할 수 있다.
+ */
+export function webhookSigningInput(timestamp, body) {
+    return `${timestamp}.${body}`;
+}
+/** 서명을 만든다 — hex. */
+export function signWebhook(secret, timestamp, body) {
+    return createHmac('sha256', secret).update(webhookSigningInput(timestamp, body)).digest('hex');
+}
+/**
+ * 서명을 확인한다.
+ *
+ * `nowMs` 를 인자로 받는다 — 안에서 현재 시각을 읽으면 시험이 시계에 매인다.
+ *
+ * **본문은 받은 바이트 그대로여야 한다.** 파싱한 객체를 다시 문자열로 만들면 키 순서와 공백이 달라져
+ * 서명이 맞지 않는다. 받은 바이트를 들고 있지 않으면 확인할 수 없고, 그때는 확인한 척하지 말고
+ * 거절해야 한다.
+ */
+export function verifyWebhookSignature(args) {
+    const { secret, timestamp, signature, body, nowMs } = args;
+    const toleranceMs = args.toleranceMs ?? WEBHOOK_TOLERANCE_MS;
+    if (!secret)
+        return { ok: false, reason: 'no-secret' };
+    if (!signature)
+        return { ok: false, reason: 'no-signature' };
+    if (!timestamp)
+        return { ok: false, reason: 'no-timestamp' };
+    const at = Date.parse(timestamp);
+    if (Number.isNaN(at))
+        return { ok: false, reason: 'bad-timestamp' };
+    /* 양쪽 모두를 본다 — 미래로 적힌 시각도 창 밖이면 거절한다. */
+    if (Math.abs(nowMs - at) > toleranceMs)
+        return { ok: false, reason: 'expired' };
+    const expected = Buffer.from(signWebhook(secret, timestamp, body), 'utf-8');
+    const given = Buffer.from(signature, 'utf-8');
+    /* 길이가 다르면 `timingSafeEqual` 이 던진다 — 길이 자체는 비밀이 아니므로 먼저 본다. */
+    if (expected.length !== given.length)
+        return { ok: false, reason: 'mismatch' };
+    return timingSafeEqual(expected, given) ? { ok: true } : { ok: false, reason: 'mismatch' };
+}

package/dist/webhook.d.ts

@@ -0,0 +1,129 @@
+/**
+ * 응답 코드 — **보내는 쪽이 무엇을 할지가 코드에서 나온다.**
+ *
+ * 코드마다 보내는 쪽의 행동이 하나로 정해져야 한다. 두 뜻을 한 코드에 담으면 보내는 쪽은 본문을 읽고
+ * 갈라야 하고, 본문 모양은 원본마다 다르다.
+ *
+ *   200  받아서 반영했다
+ *   400  본문을 레코드로 옮길 수 없다        그쪽 모양이 바뀐 것이다
+ *   401  비밀값 또는 서명이 맞지 않는다
+ *   404  모르는 연결이거나 모르는 트윈
+ *   409  번호가 비었다                       `expectedSeq` 부터 다시 보낸다
+ *   422  일부가 검증에서 떨어졌다             떨어진 것만 따로 두고 나머지는 보냄으로 표시한다
+ *   500  받는 쪽 오류                        다시 보내면 될 수 있다
+ *   501  그 커넥터가 밀어 주기를 받을 줄 모른다
+ *   503  그 트윈이 지금 실시간으로 돌지 않는다  들고 기다렸다가 다시 보낸다
+ *
+ * **503 인 이유.** 예전에는 409 였고 「재시도해도 같은 것」으로 분류했다. 그런데 트윈이 안 도는 것은
+ * 누가 띄우면 풀린다. 4xx 는 「보낸 요청이 잘못됐다」는 뜻이라, 그것을 받은 쪽이 포기하면 그 사실이
+ * 사라진다. 보내는 쪽이 해야 할 일은 사실을 들고 기다렸다 다시 보내는 것이므로 5xx 다.
+ */
+export declare const WEBHOOK_STATUS: {
+    readonly ok: 200;
+    readonly badPayload: 400;
+    readonly badSecret: 401;
+    readonly unknownTarget: 404;
+    readonly sequenceGap: 409;
+    readonly partial: 422;
+    readonly failed: 500;
+    readonly unsupported: 501;
+    readonly notLive: 503;
+};
+export type WebhookStatus = (typeof WEBHOOK_STATUS)[keyof typeof WEBHOOK_STATUS];
+/**
+ * 그 응답을 받은 뒤 보내는 쪽이 할 일.
+ *
+ *   accepted     보냄으로 표시한다(`lastSeq` 까지)
+ *   partial      `lastSeq` 까지 보냄으로 표시하되, 응답이 든 `rejected` 는 따로 둔다. 다시 보내지 않는다
+ *   resend-from  `expectedSeq` 부터 다시 보낸다
+ *   wait         그대로 들고 쉬었다가 다시 보낸다. 버리지 않는다
+ *   retry        다시 보낸다. 받는 쪽 오류다
+ *   stop         보내지 말고 사람을 부른다. 다시 보내도 같다
+ */
+export type WebhookSenderAction = 'accepted' | 'partial' | 'resend-from' | 'wait' | 'retry' | 'stop';
+/**
+ * 응답 코드 → 보내는 쪽의 행동. **모르는 코드도 답을 낸다.**
+ *
+ * 표에 없는 코드가 오는 일이 있다(프록시의 502, 게이트웨이의 504). 그때 「모른다」로 두면 보내는 쪽이
+ * 각자 정하고, 한 곳은 버리고 다른 곳은 되풀이한다. 5xx 는 받는 쪽 사정이므로 다시 보내고, 나머지는
+ * 보낸 것이 잘못이므로 멈춘다.
+ */
+export declare function webhookSenderAction(status: number): WebhookSenderAction;
+/** 429 를 함께 쓰는 곳이 있다 — 받는 쪽이 따라가지 못한다는 뜻이고, 행동은 503 과 같다. */
+export declare const WEBHOOK_TOO_MANY = 429;
+/**
+ * 봉투 하나 — 번호와 사실을 함께 든다.
+ *
+ * `scope` 가 **번호를 매기는 단위**다. 이것이 없으면 받는 쪽은 그 번호가 어느 줄의 번호인지 모르고,
+ * 커서를 무엇으로 잡을지 짐작해야 한다. 실제로 operato-mes 가 `[domain, channel]` 마다 번호를 매기면서
+ * 봉투에는 `channel` 을 싣지 않고 있었다 — 두 채널이 흐르기 시작하면 두 줄의 번호가 한 커서에 섞여
+ * 연속성 검사가 끊임없이 「비었다」로 답한다.
+ *
+ * **주소에서 유추하지 않는다.** 「이 문으로 왔으니 이 단위겠지」로 잡으면, 같은 문에 두 번째 단위를
+ * 붙이는 날 오류 없이 연속성이 깨진다. 주소는 어디로 갈지를 정하고 `scope` 는 어느 줄인지를 정한다.
+ */
+export interface WebhookEnvelope {
+    /** 이 단위 안에서 1씩 증가한다. */
+    seq: number;
+    /** 번호를 매기는 단위의 이름. 보내는 쪽이 정하고 받는 쪽은 열쇠로만 다룬다. */
+    scope: string;
+    /** 멱등 키. 같은 값이 두 번 와도 결과가 같아야 한다. */
+    eventId?: string;
+    /** 사실이 일어난 시각. */
+    eventTime?: string;
+    /** 보내는 쪽에 기록된 시각. `eventTime` 과 구별한다. */
+    recordTime?: string;
+    /** 정규 레코드 하나. */
+    record: unknown;
+}
+/**
+ * 번호 판정 — **네 가지이고, 합치지 않는다.**
+ *
+ *   first    이 단위의 첫 봉투다. 받는 쪽에 커서가 없다
+ *   next     바로 다음 번호다
+ *   behind   이미 본 번호다. 재전송이다
+ *   gap      건너뛰었다. `expectedSeq` 부터 다시 받아야 한다
+ *
+ * `first` 를 `next` 와 나누는 이유는 **아무 번호나 받아들인 것**이기 때문이다. 커서가 없으면 앞에
+ * 무엇이 있었는지 알 방법이 없으므로 거절할 근거도 없다. 그것을 `next` 로 뭉치면 「이어받았다」와
+ * 「처음부터 시작했다」가 같아 보이고, 커서를 잃은 재기동이 정상으로 읽힌다.
+ *
+ * `behind` 를 오류로 만들지 않는 이유는 재전송이 이 방식의 정상 동작이기 때문이다. 같은 사실이 두 번
+ * 들어오는 것은 유입 경계가 거른다.
+ */
+export type SequenceVerdict = {
+    kind: 'first';
+    lastSeq: number;
+} | {
+    kind: 'next';
+    lastSeq: number;
+} | {
+    kind: 'behind';
+    lastSeq: number;
+} | {
+    kind: 'gap';
+    lastSeq: number;
+    expectedSeq: number;
+};
+/**
+ * 번호를 이어 볼 수 있는가.
+ *
+ * @param lastSeq 이 단위에서 마지막으로 받아들인 번호. 받은 적이 없으면 `undefined`
+ * @param seq     이번 봉투의 번호
+ */
+export declare function checkSequence(lastSeq: number | undefined, seq: number): SequenceVerdict;
+/**
+ * 배치 하나를 이어 본다 — **첫 구멍에서 멈춘다.**
+ *
+ * 구멍 뒤의 봉투를 받아들이면 그 구멍이 영영 메워지지 않는다. 보내는 쪽이 `expectedSeq` 부터 다시
+ * 보내면 뒤엣것은 함께 온다.
+ *
+ * 번호가 오름차순이 아닌 배치는 그 자체가 보내는 쪽의 결함이므로 구멍과 같게 다룬다.
+ */
+export declare function checkSequenceRun(lastSeq: number | undefined, seqs: number[]): {
+    accepted: number;
+    lastSeq: number;
+    gap?: {
+        expectedSeq: number;
+    };
+};

package/dist/webhook.js

@@ -0,0 +1,119 @@
+/*
+ * **밀어 주는 연동의 계약** — 보내는 쪽과 받는 쪽이 같은 뜻으로 읽어야 하는 것.
+ *
+ * ── 왜 계약에 있나 (2026-08-31) ──────────────────────────────────────────
+ * 보내는 쪽은 응답 코드 하나로 「다시 보낼 것인가 · 기다릴 것인가 · 사람을 부를 것인가」를 정한다.
+ * 그 판단표가 양쪽에 따로 있으면 한쪽만 바뀌는 날이 온다. 실제로 그렇게 되어 있었다 — 트윈은 409 를
+ * 「그 트윈이 실시간으로 돌지 않는다」로 쓰고 operato-mes 는 409 를 「번호가 비었다」로 읽었다.
+ * 붙였다면 트윈이 「안 돈다」고 답하는 것을 MES 가 「번호가 비었다」로 읽어 같은 구간을 되풀이 보냈다.
+ *
+ * 계약 층의 기준이 「만드는 쪽과 읽는 쪽이 합의해야 하는가」이고, 응답 코드와 번호 규칙이 그것이다.
+ *
+ * ── 서명은 여기 없다 ─────────────────────────────────────────────────────
+ * `./webhook-signature.ts` 에 있고 `@operato/ops-contract/webhook` 으로만 나간다. `node:crypto` 를
+ * 쓰기 때문이다. 이 파일(색인에 실리는 것)에 넣으면 계약을 쓰는 브라우저 번들이 `node:crypto` 를
+ * 묶으려다 실패한다 — operato-twin 클라이언트가 이 패키지를 쓴다.
+ */
+/**
+ * 응답 코드 — **보내는 쪽이 무엇을 할지가 코드에서 나온다.**
+ *
+ * 코드마다 보내는 쪽의 행동이 하나로 정해져야 한다. 두 뜻을 한 코드에 담으면 보내는 쪽은 본문을 읽고
+ * 갈라야 하고, 본문 모양은 원본마다 다르다.
+ *
+ *   200  받아서 반영했다
+ *   400  본문을 레코드로 옮길 수 없다        그쪽 모양이 바뀐 것이다
+ *   401  비밀값 또는 서명이 맞지 않는다
+ *   404  모르는 연결이거나 모르는 트윈
+ *   409  번호가 비었다                       `expectedSeq` 부터 다시 보낸다
+ *   422  일부가 검증에서 떨어졌다             떨어진 것만 따로 두고 나머지는 보냄으로 표시한다
+ *   500  받는 쪽 오류                        다시 보내면 될 수 있다
+ *   501  그 커넥터가 밀어 주기를 받을 줄 모른다
+ *   503  그 트윈이 지금 실시간으로 돌지 않는다  들고 기다렸다가 다시 보낸다
+ *
+ * **503 인 이유.** 예전에는 409 였고 「재시도해도 같은 것」으로 분류했다. 그런데 트윈이 안 도는 것은
+ * 누가 띄우면 풀린다. 4xx 는 「보낸 요청이 잘못됐다」는 뜻이라, 그것을 받은 쪽이 포기하면 그 사실이
+ * 사라진다. 보내는 쪽이 해야 할 일은 사실을 들고 기다렸다 다시 보내는 것이므로 5xx 다.
+ */
+export const WEBHOOK_STATUS = {
+    ok: 200,
+    badPayload: 400,
+    badSecret: 401,
+    unknownTarget: 404,
+    sequenceGap: 409,
+    partial: 422,
+    failed: 500,
+    unsupported: 501,
+    notLive: 503
+};
+/**
+ * 응답 코드 → 보내는 쪽의 행동. **모르는 코드도 답을 낸다.**
+ *
+ * 표에 없는 코드가 오는 일이 있다(프록시의 502, 게이트웨이의 504). 그때 「모른다」로 두면 보내는 쪽이
+ * 각자 정하고, 한 곳은 버리고 다른 곳은 되풀이한다. 5xx 는 받는 쪽 사정이므로 다시 보내고, 나머지는
+ * 보낸 것이 잘못이므로 멈춘다.
+ */
+export function webhookSenderAction(status) {
+    switch (status) {
+        case WEBHOOK_STATUS.ok:
+            return 'accepted';
+        case WEBHOOK_STATUS.sequenceGap:
+            return 'resend-from';
+        case WEBHOOK_STATUS.partial:
+            /*
+             * **다시 보내면 안 된다.** 떨어진 것은 모양이 틀린 것이라 같은 것을 다시 보내도 또 떨어지고,
+             * 함께 간 나머지는 이미 들어갔으므로 두 번 들어간다. 떨어진 것만 따로 두고 나아간다.
+             */
+            return 'partial';
+        case WEBHOOK_STATUS.notLive:
+            return 'wait';
+        case WEBHOOK_STATUS.failed:
+            return 'retry';
+        case WEBHOOK_STATUS.badPayload:
+        case WEBHOOK_STATUS.badSecret:
+        case WEBHOOK_STATUS.unknownTarget:
+        case WEBHOOK_STATUS.unsupported:
+            return 'stop';
+        default:
+            return status >= 500 ? 'retry' : 'stop';
+    }
+}
+/** 429 를 함께 쓰는 곳이 있다 — 받는 쪽이 따라가지 못한다는 뜻이고, 행동은 503 과 같다. */
+export const WEBHOOK_TOO_MANY = 429;
+/**
+ * 번호를 이어 볼 수 있는가.
+ *
+ * @param lastSeq 이 단위에서 마지막으로 받아들인 번호. 받은 적이 없으면 `undefined`
+ * @param seq     이번 봉투의 번호
+ */
+export function checkSequence(lastSeq, seq) {
+    if (!Number.isInteger(seq) || seq < 1) {
+        throw new Error(`checkSequence: 번호는 1 이상의 정수여야 한다 — 받은 값 ${JSON.stringify(seq)}`);
+    }
+    if (lastSeq === undefined || lastSeq === null)
+        return { kind: 'first', lastSeq: seq };
+    if (seq <= lastSeq)
+        return { kind: 'behind', lastSeq };
+    if (seq === lastSeq + 1)
+        return { kind: 'next', lastSeq: seq };
+    return { kind: 'gap', lastSeq, expectedSeq: lastSeq + 1 };
+}
+/**
+ * 배치 하나를 이어 본다 — **첫 구멍에서 멈춘다.**
+ *
+ * 구멍 뒤의 봉투를 받아들이면 그 구멍이 영영 메워지지 않는다. 보내는 쪽이 `expectedSeq` 부터 다시
+ * 보내면 뒤엣것은 함께 온다.
+ *
+ * 번호가 오름차순이 아닌 배치는 그 자체가 보내는 쪽의 결함이므로 구멍과 같게 다룬다.
+ */
+export function checkSequenceRun(lastSeq, seqs) {
+    let cursor = lastSeq;
+    let accepted = 0;
+    for (const seq of seqs) {
+        const verdict = checkSequence(cursor, seq);
+        if (verdict.kind === 'gap')
+            return { accepted, lastSeq: verdict.lastSeq, gap: { expectedSeq: verdict.expectedSeq } };
+        cursor = verdict.lastSeq;
+        accepted++;
+    }
+    return { accepted, lastSeq: cursor };
+}

package/dist-cjs/index.cjs

@@ -61,6 +61,8 @@ __export(index_exports, {
   UTC_OFFSET: () => UTC_OFFSET,
   VOCABULARY_EXCEPTIONS: () => VOCABULARY_EXCEPTIONS,
   VOCABULARY_TYPE: () => VOCABULARY_TYPE,
+  WEBHOOK_STATUS: () => WEBHOOK_STATUS,
+  WEBHOOK_TOO_MANY: () => WEBHOOK_TOO_MANY,
   WMS_LOCATION_TYPES: () => WMS_LOCATION_TYPES,
   WMS_TYPES: () => WMS_TYPES,
   YARD_BIZSTEP: () => YARD_BIZSTEP,
@@ -77,6 +79,8 @@ __export(index_exports, {
   bizTransactionUri: () => bizTransactionUri,
   capabilitiesForType: () => capabilitiesForType,
   capabilityOf: () => capabilityOf,
+  checkSequence: () => checkSequence,
+  checkSequenceRun: () => checkSequenceRun,
   classClosure: () => classClosure,
   classIdentifierViolation: () => classIdentifierViolation,
   commandsOf: () => commandsOf,
@@ -171,6 +175,7 @@ __export(index_exports, {
   validateDomainDefinition: () => validateDomainDefinition,
   validateEpcisEvent: () => validateEpcisEvent,
   validateScenario: () => validateScenario,
+  webhookSenderAction: () => webhookSenderAction,
   weekdayAt: () => weekdayAt,
   workingHoursBetween: () => workingHoursBetween,
   workingTimeOfWeek: () => workingTimeOfWeek
@@ -3165,6 +3170,8 @@ var ASSET_STATUS = ["idle", "in-use"];
 var SPECS = {
   task: {
     eventType: OP_EVENT.task,
+    match: ["taskId"],
+    matchOrder: 50,
     identity: "taskId",
     /* 종류가 없으면 성과를 종류별로 모을 수 없고(선언된 시간·수율이 종류로 붙는다) 지어낼 수도 없다. */
     required: ["taskId", "kind", "status"],
@@ -3201,6 +3208,8 @@ var SPECS = {
   },
   equipment: {
     eventType: OP_EVENT.equipment,
+    match: ["moverId"],
+    matchOrder: 20,
     identity: "moverId",
     // vocabulary-guard: allow 저널 와이어 필드(델타의 이름이 계약이다)
     required: ["moverId", "kind", "status"],
@@ -3227,6 +3236,8 @@ var SPECS = {
   },
   person: {
     eventType: OP_EVENT.person,
+    match: ["personId"],
+    matchOrder: 30,
     identity: "personId",
     required: ["personId", "status"],
     fields: {
@@ -3244,6 +3255,8 @@ var SPECS = {
   },
   asset: {
     eventType: OP_EVENT.asset,
+    match: ["assetId"],
+    matchOrder: 40,
     identity: "assetId",
     required: ["assetId", "status"],
     fields: {
@@ -3261,6 +3274,8 @@ var SPECS = {
   },
   order: {
     eventType: OP_EVENT.order,
+    match: ["orderId"],
+    matchOrder: 60,
     identity: "orderId",
     /*
      * 요청량·이행량을 **함께** 받는다. 없으면 리듀서가 진척을 0 으로 적는데(`requested ? … : 0`),
@@ -3290,12 +3305,23 @@ var SPECS = {
   },
   quality: {
     eventType: OP_EVENT.quality,
+    match: ["moverId", "good"],
+    matchOrder: 15,
     identity: "moverId",
     // vocabulary-guard: allow 저널 와이어 필드
     /* 누적 카운터가 없으면 OEE 가 양품률을 못 센다 — 판정 하나만으로는 비율이 나오지 않는다. */
     required: ["moverId", "good", "goodCount", "scrapCount"],
     // vocabulary-guard: allow
-    fields: { moverId: "string", good: "boolean", goodCount: "number", scrapCount: "number", recordTime: "string" }
+    /*
+     * `taskId` 는 **귀속**이다 — 이 산출이 어느 작업의 것인가. 수량의 뜻은 바뀌지 않는다(설비 누적).
+     *
+     * 왜 필요한가: 작업자가 올리는 실적은 작업 단위인데 이 갈래의 정체는 설비뿐이라, 두 사실이 만나는
+     * 자리가 없었다. 귀속이 없으면 「이 작업에서 몇 개 나왔나」를 저널에서 되짚을 방법이 없다.
+     *
+     * 정체를 `taskId` 로 바꾸지 않는 이유는 OEE 가 설비 단위여서다. 정체를 옮기면 설비 누적을 셀 수
+     * 없어진다.
+     */
+    fields: { moverId: "string", good: "boolean", goodCount: "number", scrapCount: "number", taskId: "string", recordTime: "string" }
     // vocabulary-guard: allow
   },
   /*
@@ -3334,6 +3360,8 @@ var SPECS = {
    */
   "equipment-period": {
     eventType: OP_EVENT.equipmentPeriod,
+    match: ["moverId", "status", "from", "to"],
+    matchOrder: 10,
     identity: "moverId",
     // vocabulary-guard: allow 저널 와이어 필드 — 전이와 같은 이름을 쓴다
     required: ["moverId", "status", "from", "to"],
@@ -3368,6 +3396,8 @@ var SPECS = {
    */
   disposition: {
     eventType: OP_EVENT.disposition,
+    match: ["subjectId", "decision"],
+    matchOrder: 80,
     identity: "subjectId",
     /* 무엇을 어떻게 하기로 했나 — 둘 중 하나가 없으면 그 결정은 아무 데도 붙지 못한다. */
     required: ["subjectId", "decision"],
@@ -3386,6 +3416,8 @@ var SPECS = {
   },
   test: {
     eventType: OP_EVENT.test,
+    match: ["testableObjectId"],
+    matchOrder: 70,
     identity: "testableObjectId",
     /* 무엇을 어느 기준으로 시험했나 — 둘 중 하나가 없으면 그 결과는 아무 데도 붙지 못한다. */
     required: ["testableObjectId", "specId"],
@@ -3419,12 +3451,16 @@ var SPECS = {
    */
   complete: {
     eventType: OP_EVENT.complete,
+    match: ["completeAxis"],
+    matchOrder: 100,
     identity: "completeAxis",
     required: ["completeAxis", "since"],
     fields: { completeAxis: "string", since: "string", recordTime: "string" }
   },
   observation: {
     eventType: OP_EVENT.observation,
+    match: ["locationId", "propertyId"],
+    matchOrder: 90,
     identity: "locationId",
     /* 자리와 속성 — 둘 중 하나가 없으면 그 관측은 아무 데도 붙지 못한다. */
     required: ["locationId", "propertyId"],
@@ -3446,19 +3482,21 @@ function operationalKindOf(record) {
   if (!record || typeof record !== "object") return void 0;
   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";
-  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";
+  const present = (k) => {
+    const v = r[k];
+    if (v === void 0 || v === null) return false;
+    return typeof v === "string" ? v.trim().length > 0 : true;
+  };
+  for (const kind of MATCH_ORDER) {
+    const spec = SPECS[kind];
+    const fields = spec.match ?? [spec.identity];
+    if (fields.every(present)) return kind;
+  }
   return void 0;
 }
+var MATCH_ORDER = Object.keys(SPECS).sort(
+  (a, b) => (SPECS[a].matchOrder ?? 1e3) - (SPECS[b].matchOrder ?? 1e3)
+);
 function isOperationalRecord(record) {
   return operationalKindOf(record) !== void 0;
 }
@@ -3733,8 +3771,63 @@ function retiredVocabularyIn(line) {
   return hits;
 }
 
+// src/webhook.ts
+var WEBHOOK_STATUS = {
+  ok: 200,
+  badPayload: 400,
+  badSecret: 401,
+  unknownTarget: 404,
+  sequenceGap: 409,
+  partial: 422,
+  failed: 500,
+  unsupported: 501,
+  notLive: 503
+};
+function webhookSenderAction(status) {
+  switch (status) {
+    case WEBHOOK_STATUS.ok:
+      return "accepted";
+    case WEBHOOK_STATUS.sequenceGap:
+      return "resend-from";
+    case WEBHOOK_STATUS.partial:
+      return "partial";
+    case WEBHOOK_STATUS.notLive:
+      return "wait";
+    case WEBHOOK_STATUS.failed:
+      return "retry";
+    case WEBHOOK_STATUS.badPayload:
+    case WEBHOOK_STATUS.badSecret:
+    case WEBHOOK_STATUS.unknownTarget:
+    case WEBHOOK_STATUS.unsupported:
+      return "stop";
+    default:
+      return status >= 500 ? "retry" : "stop";
+  }
+}
+var WEBHOOK_TOO_MANY = 429;
+function checkSequence(lastSeq, seq) {
+  if (!Number.isInteger(seq) || seq < 1) {
+    throw new Error(`checkSequence: \uBC88\uD638\uB294 1 \uC774\uC0C1\uC758 \uC815\uC218\uC5EC\uC57C \uD55C\uB2E4 \u2014 \uBC1B\uC740 \uAC12 ${JSON.stringify(seq)}`);
+  }
+  if (lastSeq === void 0 || lastSeq === null) return { kind: "first", lastSeq: seq };
+  if (seq <= lastSeq) return { kind: "behind", lastSeq };
+  if (seq === lastSeq + 1) return { kind: "next", lastSeq: seq };
+  return { kind: "gap", lastSeq, expectedSeq: lastSeq + 1 };
+}
+function checkSequenceRun(lastSeq, seqs) {
+  let cursor = lastSeq;
+  let accepted = 0;
+  for (const seq of seqs) {
+    const verdict = checkSequence(cursor, seq);
+    if (verdict.kind === "gap") return { accepted, lastSeq: verdict.lastSeq, gap: { expectedSeq: verdict.expectedSeq } };
+    cursor = verdict.lastSeq;
+    accepted++;
+  }
+  return { accepted, lastSeq: cursor };
+}
+
 // src/version.ts
-var CONTRACT_VERSION = "0.5.0";
+var CONTRACT_VERSION = "0.7.0";
 
 // src/oee.ts
 function computeOee(c, nowMs) {
@@ -3808,6 +3901,8 @@ function computeOee(c, nowMs) {
   UTC_OFFSET,
   VOCABULARY_EXCEPTIONS,
   VOCABULARY_TYPE,
+  WEBHOOK_STATUS,
+  WEBHOOK_TOO_MANY,
   WMS_LOCATION_TYPES,
   WMS_TYPES,
   YARD_BIZSTEP,
@@ -3824,6 +3919,8 @@ function computeOee(c, nowMs) {
   bizTransactionUri,
   capabilitiesForType,
   capabilityOf,
+  checkSequence,
+  checkSequenceRun,
   classClosure,
   classIdentifierViolation,
   commandsOf,
@@ -3918,6 +4015,7 @@ function computeOee(c, nowMs) {
   validateDomainDefinition,
   validateEpcisEvent,
   validateScenario,
+  webhookSenderAction,
   weekdayAt,
   workingHoursBetween,
   workingTimeOfWeek

package/dist-cjs/webhook-signature.cjs

@@ -0,0 +1,66 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/webhook-signature.ts
+var webhook_signature_exports = {};
+__export(webhook_signature_exports, {
+  WEBHOOK_HEADER: () => WEBHOOK_HEADER,
+  WEBHOOK_TOLERANCE_MS: () => WEBHOOK_TOLERANCE_MS,
+  signWebhook: () => signWebhook,
+  verifyWebhookSignature: () => verifyWebhookSignature,
+  webhookSigningInput: () => webhookSigningInput
+});
+module.exports = __toCommonJS(webhook_signature_exports);
+var import_node_crypto = require("node:crypto");
+var WEBHOOK_HEADER = {
+  /** 보내는 쪽이 누구인가. 사람이 로그에서 읽는 용도이고, 어디로 갈지는 주소가 정한다. */
+  source: "x-ops-source",
+  /** 서명에 들어간 시각(RFC 3339). */
+  timestamp: "x-ops-timestamp",
+  /** HMAC-SHA256 hex. */
+  signature: "x-ops-signature"
+};
+var WEBHOOK_TOLERANCE_MS = 5 * 6e4;
+function webhookSigningInput(timestamp, body) {
+  return `${timestamp}.${body}`;
+}
+function signWebhook(secret, timestamp, body) {
+  return (0, import_node_crypto.createHmac)("sha256", secret).update(webhookSigningInput(timestamp, body)).digest("hex");
+}
+function verifyWebhookSignature(args) {
+  const { secret, timestamp, signature, body, nowMs } = args;
+  const toleranceMs = args.toleranceMs ?? WEBHOOK_TOLERANCE_MS;
+  if (!secret) return { ok: false, reason: "no-secret" };
+  if (!signature) return { ok: false, reason: "no-signature" };
+  if (!timestamp) return { ok: false, reason: "no-timestamp" };
+  const at = Date.parse(timestamp);
+  if (Number.isNaN(at)) return { ok: false, reason: "bad-timestamp" };
+  if (Math.abs(nowMs - at) > toleranceMs) return { ok: false, reason: "expired" };
+  const expected = Buffer.from(signWebhook(secret, timestamp, body), "utf-8");
+  const given = Buffer.from(signature, "utf-8");
+  if (expected.length !== given.length) return { ok: false, reason: "mismatch" };
+  return (0, import_node_crypto.timingSafeEqual)(expected, given) ? { ok: true } : { ok: false, reason: "mismatch" };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WEBHOOK_HEADER,
+  WEBHOOK_TOLERANCE_MS,
+  signWebhook,
+  verifyWebhookSignature,
+  webhookSigningInput
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operato/ops-contract",
-  "version": "0.5.0",
+  "version": "0.7.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",
@@ -10,6 +10,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist-cjs/index.cjs"
+    },
+    "./webhook": {
+      "types": "./dist/webhook-signature.d.ts",
+      "import": "./dist/webhook-signature.js",
+      "require": "./dist-cjs/webhook-signature.cjs"
     }
   },
   "files": [
@@ -19,12 +24,19 @@
   "scripts": {
     "build": "npm run build:esm && npm run build:cjs",
     "build:esm": "tsc -p tsconfig.build.json",
-    "build:cjs": "esbuild src/index.ts --bundle --platform=node --format=cjs --outfile=dist-cjs/index.cjs",
+    "build:cjs": "esbuild src/index.ts --bundle --platform=node --format=cjs --outfile=dist-cjs/index.cjs && esbuild src/webhook-signature.ts --bundle --platform=node --format=cjs --outfile=dist-cjs/webhook-signature.cjs",
     "typecheck": "tsc -p tsconfig.check.json",
     "test": "node --test test/*.test.ts"
   },
   "license": "MIT",
   "publishConfig": {
     "access": "public"
+  },
+  "typesVersions": {
+    "*": {
+      "webhook": [
+        "./dist/webhook-signature.d.ts"
+      ]
+    }
   }
 }