@operato/ops-contract 0.6.0 → 0.7.1

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;

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/operational-ingest.js

@@ -144,7 +144,16 @@ const SPECS = {
         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`).

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

@@ -27,7 +27,6 @@ __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,
@@ -61,6 +60,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 +78,8 @@ __export(index_exports, {
   bizTransactionUri: () => bizTransactionUri,
   capabilitiesForType: () => capabilitiesForType,
   capabilityOf: () => capabilityOf,
+  checkSequence: () => checkSequence,
+  checkSequenceRun: () => checkSequenceRun,
   classClosure: () => classClosure,
   classIdentifierViolation: () => classIdentifierViolation,
   commandsOf: () => commandsOf,
@@ -171,6 +174,7 @@ __export(index_exports, {
   validateDomainDefinition: () => validateDomainDefinition,
   validateEpcisEvent: () => validateEpcisEvent,
   validateScenario: () => validateScenario,
+  webhookSenderAction: () => webhookSenderAction,
   weekdayAt: () => weekdayAt,
   workingHoursBetween: () => workingHoursBetween,
   workingTimeOfWeek: () => workingTimeOfWeek
@@ -3307,7 +3311,16 @@ var SPECS = {
     /* 누적 카운터가 없으면 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
   },
   /*
@@ -3757,8 +3770,60 @@ function retiredVocabularyIn(line) {
   return hits;
 }
 
-// src/version.ts
-var CONTRACT_VERSION = "0.5.0";
+// 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/oee.ts
 function computeOee(c, nowMs) {
@@ -3798,7 +3863,6 @@ function computeOee(c, nowMs) {
   CAPABILITY_KEYS,
   CBV_BIZSTEP,
   CMD,
-  CONTRACT_VERSION,
   DISP,
   DISPOSITION_DECISION,
   DOMAIN_CATALOG,
@@ -3832,6 +3896,8 @@ function computeOee(c, nowMs) {
   UTC_OFFSET,
   VOCABULARY_EXCEPTIONS,
   VOCABULARY_TYPE,
+  WEBHOOK_STATUS,
+  WEBHOOK_TOO_MANY,
   WMS_LOCATION_TYPES,
   WMS_TYPES,
   YARD_BIZSTEP,
@@ -3848,6 +3914,8 @@ function computeOee(c, nowMs) {
   bizTransactionUri,
   capabilitiesForType,
   capabilityOf,
+  checkSequence,
+  checkSequenceRun,
   classClosure,
   classIdentifierViolation,
   commandsOf,
@@ -3942,6 +4010,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.6.0",
+  "version": "0.7.1",
   "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"
+      ]
+    }
   }
 }