@operato/ops-contract 0.9.19 → 0.9.20

package/README.md

@@ -72,6 +72,32 @@ assertOperationalAttentionV1(attention)
 `lane`과 합치지 않는다. `lane`을 생략한 기존 커넥터는 `FACTS`로 읽혀 기존 canonical ingest 경로를 그대로
 쓴다. 따라서 주소·서명·재시도·순번 규약은 하나이고, 사실과 attention의 저장·처리만 Twin 내부에서 갈린다.
 
+#### Webhook 봉투에서의 구분
+
+`lane`은 **전달 목적**, `scope`는 **생산자의 순번 스트림 이름**이다. 같은 값으로 쓰거나 `scope`를
+`ATTENTIONS`로 바꾸지 않는다.
+
+```ts
+const batch = {
+  lane: 'ATTENTIONS',       // 없으면 FACTS: 기존 커넥터와 호환
+  scope: 'mes-line-a',      // 이 생산자가 관리하는 순번 스트림
+  items: [{
+    eventId: 'outbox-1002',
+    seq: 1002,
+    record: attention
+  }]
+}
+```
+
+| lane | Twin 내부 목적지 | 정본 저널 반영 |
+| --- | --- | --- |
+| `FACTS` 또는 생략 | 기존 canonical ingest | 예. EPCIS/운영 사실로 유입한다. |
+| `ATTENTIONS` | 제품이 등록한 AI attention inbox | 아니오. 분석을 요청하는 근거 묶음으로 분리한다. |
+
+두 lane 모두 같은 webhook 인증·서명·순번·재시도 응답 계약을 쓴다. 수신자는 `OperationalAttentionV1`의
+도메인 일치와 원본 사실 참조를 검증하고, 같은 `domain/source/instance/attention/evidenceFingerprint`는
+중복으로 처리한다. 이 계약은 attention을 현장 명령으로 바꾸지 않는다.
+
 ## 왜 나뉘어 있나
 
 사실을 **만드는 쪽**(MES · 커넥터)은 계약만 필요하고 엔진은 필요 없습니다. 한 패키지에 두면 레코드

package/dist/command-verdict.d.ts

@@ -0,0 +1,47 @@
+import type { CommandAck, RefusalCode, RefusalParams } from './contract.ts';
+export type CommandVerdictKind = 'accepted' | 'refused' | 'unavailable';
+/** Why a command was refused, or why no preview could be made. Language-neutral (ADR-0037 ④). */
+export interface CommandVerdictReason {
+    /** Stable code — `CommandAck.errorCode` verbatim for a refusal; a host code for `unavailable`. */
+    code: RefusalCode;
+    /** Raw values the code refers to — `CommandAck.errorParams` verbatim. */
+    params?: RefusalParams;
+    /** Developer fallback in English (`CommandAck.error`). Not for viewers; hosts translate `code`. */
+    message?: string;
+}
+export type CommandVerdict = {
+    verdict: 'accepted';
+    commandId: string;
+} | {
+    verdict: 'refused';
+    commandId: string;
+    reason: CommandVerdictReason;
+} | {
+    verdict: 'unavailable';
+    reason: CommandVerdictReason;
+};
+/** The code a refusal carries when the kernel gave none — the same word the intervention log uses. */
+export declare const REFUSED_WITHOUT_CODE = "refused";
+/**
+ * Fold a kernel ack into a verdict. Pure: reads the ack, invents nothing.
+ *
+ * An ack that was not accepted and names no code still becomes `refused`, with the code the
+ * intervention log already uses for that case, so the two never disagree about what "no code" is.
+ */
+export declare function verdictOfAck(ack: CommandAck): CommandVerdict;
+/**
+ * The verdict when no preview can be made. The host decides this **before** dispatching, from what
+ * it can see: whether the runtime has `fork`, whether a checkpoint exists at that time.
+ */
+export declare function unavailableVerdict(code: RefusalCode, params?: RefusalParams, message?: string): CommandVerdict;
+/**
+ * Can this runtime preview at all? Read as a capability, not by trying and catching (ADR-0042 ②).
+ *
+ * This answers "can we look", not "can we act". A mirror twin refuses to *apply* an actuation
+ * (`actuation-not-wired` — the real system would not know), yet previewing it on a fork is fine and
+ * is exactly where a preview is worth most. Keep the two answers apart (ADR-0042 ⑤).
+ */
+export declare function canPreview(runtime: unknown): runtime is {
+    fork(): unknown;
+    dispatch(cmd: unknown): CommandAck;
+};

package/dist/command-verdict.js

@@ -0,0 +1,65 @@
+/*
+ * Preview verdict — the seam between a kernel `CommandAck` and a screen (ADR-0042).
+ *
+ * A proposal is previewed by dispatching the same command on a fork of the live kernel. Three
+ * things can come back, and a viewer has to act differently on each:
+ *
+ *   accepted     the fork took the command — the preview shows what follows
+ *   refused      the fork did not take it — **this is a successful preview**: we learned, before
+ *                anyone pressed apply, that the kernel will not do this here. Drawing it as an
+ *                error tells the viewer the preview broke, which is the opposite of what happened
+ *   unavailable  no preview could be made at all — the runtime has no `fork`, there is no
+ *                checkpoint at that time, the twin has no runtime. Decided from capability first,
+ *                never from an exception that happened to be thrown (ADR-0036 ③ · ADR-0042 ②)
+ *
+ * The reason keeps the shape ADR-0037 ④ fixed for every violation in this repo: `{ code, params,
+ * message }`. `code` and `params` are `CommandAck.errorCode` and `errorParams` **verbatim** — there
+ * is no mapping table, because a table goes stale the day the kernel emits a new code, and that
+ * day nobody notices. `message` is the developer fallback (`ack.error`), never the viewer line.
+ *
+ * Why this lives in the contract rather than as a convention: a convention holds only while the
+ * next author remembers it. A type does not need remembering.
+ */
+/** The code a refusal carries when the kernel gave none — the same word the intervention log uses. */
+export const REFUSED_WITHOUT_CODE = 'refused';
+/**
+ * Fold a kernel ack into a verdict. Pure: reads the ack, invents nothing.
+ *
+ * An ack that was not accepted and names no code still becomes `refused`, with the code the
+ * intervention log already uses for that case, so the two never disagree about what "no code" is.
+ */
+export function verdictOfAck(ack) {
+    if (ack.accepted)
+        return { verdict: 'accepted', commandId: ack.commandId };
+    const reason = { code: ack.errorCode ?? REFUSED_WITHOUT_CODE };
+    if (ack.errorParams !== undefined)
+        reason.params = ack.errorParams;
+    if (ack.error !== undefined)
+        reason.message = ack.error;
+    return { verdict: 'refused', commandId: ack.commandId, reason };
+}
+/**
+ * The verdict when no preview can be made. The host decides this **before** dispatching, from what
+ * it can see: whether the runtime has `fork`, whether a checkpoint exists at that time.
+ */
+export function unavailableVerdict(code, params, message) {
+    const reason = { code };
+    if (params !== undefined)
+        reason.params = params;
+    if (message !== undefined)
+        reason.message = message;
+    return { verdict: 'unavailable', reason };
+}
+/**
+ * Can this runtime preview at all? Read as a capability, not by trying and catching (ADR-0042 ②).
+ *
+ * This answers "can we look", not "can we act". A mirror twin refuses to *apply* an actuation
+ * (`actuation-not-wired` — the real system would not know), yet previewing it on a fork is fine and
+ * is exactly where a preview is worth most. Keep the two answers apart (ADR-0042 ⑤).
+ */
+export function canPreview(runtime) {
+    if (runtime === null || typeof runtime !== 'object')
+        return false;
+    const r = runtime;
+    return typeof r.fork === 'function' && typeof r.dispatch === 'function';
+}

package/dist/contract.d.ts

@@ -1463,6 +1463,12 @@ export interface ItemState {
      * 「이 로트가 지금 어떤 것이냐」다. 시험 결과를 명세당 하나만 든 것과 같은 규율이다.
      */
     nonconformance?: DispositionFact;
+    /**
+     * **로트 상태** — 표준 `MaterialLot.Status`. `nonconformance`(표준 `Disposition`)와 다른 칸이다: 처분은
+     * 부적합을 어떻게 하나, 상태는 이 로트가 지금 어떤 것이냐(released · quarantine · on-hold …). 낱말은 도메인의
+     * 것(열림). 마지막 하나만 든다 — 이력은 저널이 답한다(§`OP_EVENT.materialLot`).
+     */
+    status?: string;
     /** 소속 물류단위(팔레트 SSCC 등) — AggregationEvent 로 맺어진다. 3D 적재 표현의 재료. */
     parent?: string;
     /**
@@ -2559,6 +2565,17 @@ export interface Command<T = unknown> {
     correlationId?: string;
     args: T;
 }
+/**
+ * 거절 사유의 **낱말 하나** — 커맨드가 낸 언어 중립 코드(`resource-not-found` 꼴, kebab-case).
+ *
+ * 같은 값이 세 자리에 실린다: `CommandAck.errorCode`(조치 ack) · `InterventionOutcome.refusedCode`(시나리오
+ * 개입 로그) · 구동 검증의 실패 코드(호스트가 저장). 칸 이름은 자리마다 다르지만 **값은 하나**이고, 그 사실을
+ * 이 타입이 말한다 — 이름이 셋이면 어딘가에 매핑 표가 생기고, 그것이 ADR-0042 ③ 이 금지한 것이다.
+ * 칸 이름을 하나로 줄이는 개명은 저장되는 개입 로그에 닿아 따로 결정한다(ADR-0042 「하지 않는 결정」).
+ */
+export type RefusalCode = string;
+/** `RefusalCode` 가 가리키는 원시값들 — 사람 언어가 아니라 값이다. 표현층이 문장에 끼운다. */
+export type RefusalParams = Record<string, string | number>;
 export interface CommandAck {
     commandId: string;
     accepted: boolean;
@@ -2566,8 +2583,8 @@ export interface CommandAck {
      * 거절 사유 — 언어 중립. errorCode(안정 코드) + errorParams(원시값)로 방출하고 사람 언어는
      * 표현계층(클라 i18next)이 렌더한다(무방언·다국어, attention 과 동형). error 는 개발자/로그용 영어 폴백.
      */
-    errorCode?: string;
-    errorParams?: Record<string, string | number>;
+    errorCode?: RefusalCode;
+    errorParams?: RefusalParams;
     error?: string;
 }
 /**
@@ -2699,8 +2716,8 @@ export interface InterventionOutcome {
     kind: string;
     args?: Record<string, unknown>;
     applied: boolean;
-    /** 거절 이유(커맨드가 낸 코드). 걸렸으면 없다. */
-    refusedCode?: string;
+    /** 거절 이유 — `CommandAck.errorCode` 와 **같은 값**(`RefusalCode`). 걸렸으면 없다. */
+    refusedCode?: RefusalCode;
 }
 export interface ScenarioControl {
     load(def: ScenarioDef): void;
@@ -2758,6 +2775,22 @@ export declare const OP_EVENT: {
      * 이것은 **결정**이다. 누가·언제·왜 그렇게 정했는지의 자리는 그쪽에 없다.
      */
     readonly disposition: "nonconformance.disposition";
+    /**
+     * **로트 상태** — ISA-95 `MaterialLot.Status`(B2MML-Material.xsd). 「이 로트가 지금 어떤 것이냐」의 결정.
+     *
+     * ── `nonconformance.disposition` 과 다른 사실이다 (2026-09-16) ──────────────
+     * 그것은 표준 `Disposition` — **부적합을 어떻게 처리하나**(재작업·특채·폐기). 이것은 표준 `Status` — 적합한
+     * 로트에도 붙는 상태(released · quarantine · on-hold …). 출하 승인(batch release)이 이 축이다. 처분에 실으면
+     * 정상 출하가 전부 부적합 이력이 된다 — 진짜 term 을 틀린 뜻으로 쓰는 것이 자리가 없는 것보다 나쁘다.
+     *
+     * ── 낱말은 열려 있다 ──────────────────────────────────────────────────────
+     * 오더 상태와 같은 규율 — 커널이 이 낱말로 무엇을 계산하지 않으므로 닫을 근거가 없다. 도메인이 소유한다.
+     *
+     * ── 출발과 다른 사실이다 ─────────────────────────────────────────────────
+     * 승인은 자재를 움직이지 않는다. 자재가 트윈 밖으로 나가는 것은 EPCIS `shipping` 사건이다. 둘을 한 사건으로
+     * 접지 않는다 — 승인됐는데 안 나간 배치가 트윈이 보여야 할 상태다.
+     */
+    readonly materialLot: "material-lot.status";
     /**
      * **이 목록이 전부다** — 연결된 시스템이 현재 목록을 한 바퀴 다 보낸 뒤 그것을 알린다.
      *

package/dist/contract.js

@@ -1097,6 +1097,22 @@ export const OP_EVENT = {
      * 이것은 **결정**이다. 누가·언제·왜 그렇게 정했는지의 자리는 그쪽에 없다.
      */
     disposition: 'nonconformance.disposition',
+    /**
+     * **로트 상태** — ISA-95 `MaterialLot.Status`(B2MML-Material.xsd). 「이 로트가 지금 어떤 것이냐」의 결정.
+     *
+     * ── `nonconformance.disposition` 과 다른 사실이다 (2026-09-16) ──────────────
+     * 그것은 표준 `Disposition` — **부적합을 어떻게 처리하나**(재작업·특채·폐기). 이것은 표준 `Status` — 적합한
+     * 로트에도 붙는 상태(released · quarantine · on-hold …). 출하 승인(batch release)이 이 축이다. 처분에 실으면
+     * 정상 출하가 전부 부적합 이력이 된다 — 진짜 term 을 틀린 뜻으로 쓰는 것이 자리가 없는 것보다 나쁘다.
+     *
+     * ── 낱말은 열려 있다 ──────────────────────────────────────────────────────
+     * 오더 상태와 같은 규율 — 커널이 이 낱말로 무엇을 계산하지 않으므로 닫을 근거가 없다. 도메인이 소유한다.
+     *
+     * ── 출발과 다른 사실이다 ─────────────────────────────────────────────────
+     * 승인은 자재를 움직이지 않는다. 자재가 트윈 밖으로 나가는 것은 EPCIS `shipping` 사건이다. 둘을 한 사건으로
+     * 접지 않는다 — 승인됐는데 안 나간 배치가 트윈이 보여야 할 상태다.
+     */
+    materialLot: 'material-lot.status',
     /**
      * **이 목록이 전부다** — 연결된 시스템이 현재 목록을 한 바퀴 다 보낸 뒤 그것을 알린다.
      *

package/dist/index.d.ts

@@ -17,6 +17,8 @@ export * from './vocabulary.ts';
 export * from './wms-profile.ts';
 export * from './yms-profile.ts';
 export * from './canonical-record.ts';
+export * from './command-verdict.ts';
+export * from './webhook-delivery.ts';
 export * from './webhook.ts';
 export * from './webhook-secret.ts';
 export * from './oee.ts';

package/dist/index.js

@@ -38,6 +38,8 @@ export * from "./vocabulary.js";
 export * from "./wms-profile.js";
 export * from "./yms-profile.js";
 export * from "./canonical-record.js";
+export * from "./command-verdict.js";
+export * from "./webhook-delivery.js";
 /* `webhook-signature.ts` 는 여기 없다 — `node:crypto` 를 쓰므로 `@operato/ops-contract/webhook` 으로만 나간다. */
 export * from "./webhook.js";
 /* 비밀값 **이름** 규약 — 값을 읽지 않으므로 여기서 나간다(§`webhook-secret`). */

package/dist/mes-profile.d.ts

@@ -4,6 +4,12 @@ export declare const MES_BIZSTEP: {
     readonly receiving: "urn:epcglobal:cbv:bizstep:receiving";
     readonly producing: "urn:epcglobal:cbv:bizstep:commissioning";
     readonly storing: "urn:epcglobal:cbv:bizstep:storing";
+    /**
+     * **출하** — CBV `shipping`: 물품이 시설을 떠난다. 자재를 트윈 밖으로 내는 것은 이 사건이다(disposition
+     * `in_transit`, readPoint = 출하 dock). 출하 **승인**은 이 사건이 아니라 로트 상태(`OP_EVENT.materialLot`)다 —
+     * 승인됐는데 안 나간 배치가 보여야 한다(2026-09-16, ADR-0046 곁).
+     */
+    readonly shipping: "urn:epcglobal:cbv:bizstep:shipping";
 };
 /** 작업지시(Work Order) = 생산 오더 거래 유형. */
 export declare const BTT_PRODORDER = "urn:epcglobal:cbv:btt:prodorder";

package/dist/mes-profile.js

@@ -2,7 +2,13 @@
 export const MES_BIZSTEP = {
     receiving: 'urn:epcglobal:cbv:bizstep:receiving', // 원자재 수령
     producing: 'urn:epcglobal:cbv:bizstep:commissioning', // 생산(제품 최초 생성)
-    storing: 'urn:epcglobal:cbv:bizstep:storing' // 완제품 저장
+    storing: 'urn:epcglobal:cbv:bizstep:storing', // 완제품 저장
+    /**
+     * **출하** — CBV `shipping`: 물품이 시설을 떠난다. 자재를 트윈 밖으로 내는 것은 이 사건이다(disposition
+     * `in_transit`, readPoint = 출하 dock). 출하 **승인**은 이 사건이 아니라 로트 상태(`OP_EVENT.materialLot`)다 —
+     * 승인됐는데 안 나간 배치가 보여야 한다(2026-09-16, ADR-0046 곁).
+     */
+    shipping: 'urn:epcglobal:cbv:bizstep:shipping'
 };
 /** 작업지시(Work Order) = 생산 오더 거래 유형. */
 export const BTT_PRODORDER = 'urn:epcglobal:cbv:btt:prodorder';

package/dist/operational-ingest.d.ts

@@ -1,6 +1,10 @@
 import type { IngestResult } from './face2-adapter.ts';
-/** 이 문이 받는 여섯 가지 — 리듀서가 다루는 것과 같은 목록(주목 확인은 우리 안의 행위라 제외). */
-export type OperationalKind = 'task' | 'equipment' | 'equipment-period' | 'person' | 'asset' | 'order' | 'quality' | 'test' | 'disposition' | 'observation' | 'complete';
+/**
+ * 이 문이 받는 종류 — **아래 union 이 정본이고 수를 여기 적지 않는다**(2026-08-19 에 여섯이었고 이제 열하나다.
+ * 주석의 수가 union 보다 오래 살아 읽는 사람이 여섯에서 멈췄다). 리듀서가 다루는 것과 같은 목록이다(주목 확인은 우리 안의
+ * 행위라 제외).
+ */
+export type OperationalKind = 'task' | 'equipment' | 'equipment-period' | 'person' | 'asset' | 'order' | 'quality' | 'test' | 'disposition' | 'material-lot' | 'observation' | 'complete';
 /**
  * 정규 운영 레코드 — **델타의 필드 이름 + 시각(`at`)**.
  *

package/dist/operational-ingest.js

@@ -320,6 +320,21 @@ const SPECS = {
         },
         enums: { decision: DISPOSITION_DECISION }
     },
+    /*
+     * **로트 상태** — ISA-95 `MaterialLot.Status`. 출하 승인(batch release)이 들어오는 문(§`OP_EVENT.materialLot`).
+     *
+     * `disposition`(subjectId + decision) 과 필드가 겹치지 않는다 — 여기는 `epc` + `status`. 상태 낱말은 열려
+     * 있어 enum 이 없다(오더 상태와 같은 규율). 로트 전체의 사실이므로 `subLotId` 는 받지 않는다 — 부분마다 다른
+     * 상태가 필요해지면 그것은 다른 사실이다.
+     */
+    'material-lot': {
+        eventType: OP_EVENT.materialLot,
+        match: ['epc', 'status'],
+        matchOrder: 85,
+        identity: 'epc',
+        required: ['epc', 'status'],
+        fields: { epc: 'string', status: 'string', decidedBy: 'string', reason: 'string', decidedAt: 'string', recordTime: 'string' }
+    },
     test: {
         eventType: OP_EVENT.test,
         match: ['testableObjectId'],

package/dist/webhook-delivery.d.ts

@@ -0,0 +1,42 @@
+import type { RefusalParams } from './contract.ts';
+export declare const WEBHOOK_DELIVERY_CODES: {
+    /** The peer received and verified the envelope, then declined the job order itself (200, accepted=false). */
+    readonly jobOrderRefused: "job-order-refused";
+    /** The envelope does not match the specification — retry never helps until the sender changes (400). */
+    readonly envelopeInvalid: "envelope-invalid";
+    /** The signature did not verify (401). `params.reason` is `mismatch` or `expired`. */
+    readonly signatureRejected: "signature-rejected";
+    /** The peer has no such site (404). */
+    readonly siteUnknown: "site-unknown";
+    /** The peer has no verify key under the name the sender used (503). `params.peer` names that peer — never the env var. */
+    readonly verifySecretMissing: "verify-secret-missing";
+    /** No HTTP answer at all — DNS, connection refused, timeout. */
+    readonly peerUnreachable: "peer-unreachable";
+    /** The peer verified the envelope and then failed on its own side — storing, for instance (500). Retrying may help. */
+    readonly peerInternalFailure: "peer-internal-failure";
+    /** An answer came back that fits none of the above — the code is the honest "unclassified", not a guess. */
+    readonly responseUnrecognised: "response-unrecognised";
+};
+export type WebhookDeliveryCode = (typeof WEBHOOK_DELIVERY_CODES)[keyof typeof WEBHOOK_DELIVERY_CODES];
+/** Reasons a signature can be rejected — the only two the verifier can tell apart. */
+export declare const SIGNATURE_REJECTED_REASONS: readonly ["mismatch", "expired"];
+export type SignatureRejectedReason = (typeof SIGNATURE_REJECTED_REASONS)[number];
+/** Is this string one of the delivery codes? For the host that stores what a connector hands it. */
+export declare function isWebhookDeliveryCode(code: string): code is WebhookDeliveryCode;
+/**
+ * What a receiving door answers when it does not take the envelope (any non-2xx).
+ *
+ * The **receiver** names the fact as a code; the sender's connector passes it on verbatim and never
+ * parses the sentence. Two connectors reading one door then cannot invent two spellings, and a door
+ * that rewords its sentence cannot silently blank the code. `error` stays for people and logs.
+ *
+ * `params` is scalar only (`RefusalParams`): a list such as the specification checks a 400 failed is
+ * not a parameter of the code, it is detail — it rides in its own field of the body and is not stored
+ * by the host.
+ */
+export interface WebhookIntakeRefusal {
+    code: WebhookDeliveryCode;
+    params?: RefusalParams;
+    /** Developer sentence in English. Never the thing a screen translates from. */
+    error: string;
+}

package/dist/webhook-delivery.js

@@ -0,0 +1,40 @@
+/*
+ * Webhook delivery outcome codes — what a sender records when an envelope did not land.
+ *
+ * The connector that delivers a job order to a peer (twin → plant intake) sees an HTTP status and a
+ * body. Neither is what gets stored: a status number is the transport's word, and the body sentence
+ * is a person's language (the intake writes Korean today). What the host records on the connection
+ * (ADR: actuation verification axis — `actuationFailure.code`) is a `RefusalCode`, the same kind of
+ * word a kernel refusal carries, so one vocabulary reaches the screen through one door.
+ *
+ * Spelling follows the kernel's refusal codes: kebab-case, a noun phrase naming the fact, no HTTP
+ * number in the word. The number is how the connector *learned* the fact; the code is the fact.
+ *
+ * The mapping from status → code is the connector's, not the contract's: a 401 can mean two
+ * different facts (signature mismatch, replay expired) and only the connector reading the body knows
+ * which. The contract fixes the words so two connectors never invent two spellings for one fact.
+ */
+export const WEBHOOK_DELIVERY_CODES = {
+    /** The peer received and verified the envelope, then declined the job order itself (200, accepted=false). */
+    jobOrderRefused: 'job-order-refused',
+    /** The envelope does not match the specification — retry never helps until the sender changes (400). */
+    envelopeInvalid: 'envelope-invalid',
+    /** The signature did not verify (401). `params.reason` is `mismatch` or `expired`. */
+    signatureRejected: 'signature-rejected',
+    /** The peer has no such site (404). */
+    siteUnknown: 'site-unknown',
+    /** The peer has no verify key under the name the sender used (503). `params.peer` names that peer — never the env var. */
+    verifySecretMissing: 'verify-secret-missing',
+    /** No HTTP answer at all — DNS, connection refused, timeout. */
+    peerUnreachable: 'peer-unreachable',
+    /** The peer verified the envelope and then failed on its own side — storing, for instance (500). Retrying may help. */
+    peerInternalFailure: 'peer-internal-failure',
+    /** An answer came back that fits none of the above — the code is the honest "unclassified", not a guess. */
+    responseUnrecognised: 'response-unrecognised'
+};
+/** Reasons a signature can be rejected — the only two the verifier can tell apart. */
+export const SIGNATURE_REJECTED_REASONS = ['mismatch', 'expired'];
+/** Is this string one of the delivery codes? For the host that stores what a connector hands it. */
+export function isWebhookDeliveryCode(code) {
+    return Object.values(WEBHOOK_DELIVERY_CODES).includes(code);
+}

package/dist/webhook-secret.d.ts

@@ -81,18 +81,6 @@ export interface WebhookSecretLookup {
      * 받되, 열리면 부르는 쪽이 한 번 알린다 — 조용히 되면 아무도 새 이름으로 옮기지 않는다.
      */
     legacyBases?: readonly string[];
-    /**
-     * **검증 쪽에서 넓은 칸까지 내려가는 것을 허락한다.** 기본은 거짓이고, 그것이 ③ 규칙이다.
-     *
-     * 이 인자를 참으로 주려면 부르는 쪽이 **그 도메인에 상대가 하나뿐임을 확인**해야 한다. 둘이면
-     * 둘이 같은 키로 풀리고, 그 순간 주소가 「이 사실이 누구 것인가」를 정하는데 아무도 그것을
-     * 검사하지 않는다 — 상대 A 가 제대로 서명한 봉투를 상대 B 의 주소에 앉힐 수 있다
-     * (§`webhook-signature` 의 불변식: 주소는 키가 이미 고정한 것만 정할 수 있다).
-     *
-     * 그리고 그 상태는 **두 번째 상대가 붙는 날 아무 경고 없이 끝난다.** 이름을 명시적으로 주게 한
-     * 이유가 그것이다 — 코드에서 찾을 수 있어야 한다.
-     */
-    allowSinglePeerFallback?: boolean;
 }
 /**
  * ③ 사다리 — 찾아볼 이름을 순서대로.

package/dist/webhook-secret.js

@@ -104,15 +104,16 @@ export function webhookSecretEnvName(base, domain, peer) {
  * 상태이고, 뒤엣것은 사람이 볼 수 없다.
  */
 export function webhookSecretCandidates(lookup) {
-    const { purpose, domain, peer, legacyBases = [], allowSinglePeerFallback = false } = lookup;
+    const { purpose, domain, peer, legacyBases = [] } = lookup;
     const base = WEBHOOK_SECRET_BASE[purpose];
     const out = [
         { name: webhookSecretEnvName(base, domain, peer), pins: 'peer', compatibility: false }
     ];
-    /* 검증은 여기서 멈춘다 — 확인한 사람이 명시적으로 열지 않는 한. */
-    if (purpose === 'verify' && !allowSinglePeerFallback)
+    /* 검증은 여기서 멈춘다 — 여는 인자가 없다. 넓어지면 아무 상대나 통과한다. */
+    if (purpose === 'verify')
         return out;
-    out.push({ name: webhookSecretEnvName(base, domain), pins: 'domain', compatibility: purpose === 'verify' });
+    /* 여기부터는 서명 쪽만이다 — 도메인 칸은 서명이 원래 내려가는 칸이라 「호환」이 아니다. */
+    out.push({ name: webhookSecretEnvName(base, domain), pins: 'domain', compatibility: false });
     for (const legacy of legacyBases) {
         out.push({ name: webhookSecretEnvName(legacy, domain), pins: 'domain', compatibility: true });
         out.push({ name: legacy, pins: 'installation', compatibility: true });

package/dist-cjs/index.cjs

@@ -65,9 +65,11 @@ __export(index_exports, {
   OP_PARAM: () => OP_PARAM,
   ORDER_TERMINAL_STATUS: () => ORDER_TERMINAL_STATUS,
   PRIORITY_UNSET: () => PRIORITY_UNSET,
+  REFUSED_WITHOUT_CODE: () => REFUSED_WITHOUT_CODE,
   RESOURCE_KIND: () => RESOURCE_KIND,
   RETIRED_VOCABULARY: () => RETIRED_VOCABULARY,
   SCHEDULE_STATUS: () => SCHEDULE_STATUS,
+  SIGNATURE_REJECTED_REASONS: () => SIGNATURE_REJECTED_REASONS,
   TWIN_AXES: () => TWIN_AXES,
   TWIN_PROPERTIES: () => TWIN_PROPERTIES,
   TWIN_RELATIONS: () => TWIN_RELATIONS,
@@ -75,6 +77,7 @@ __export(index_exports, {
   UTC_OFFSET: () => UTC_OFFSET,
   VOCABULARY_EXCEPTIONS: () => VOCABULARY_EXCEPTIONS,
   VOCABULARY_TYPE: () => VOCABULARY_TYPE,
+  WEBHOOK_DELIVERY_CODES: () => WEBHOOK_DELIVERY_CODES,
   WEBHOOK_LANE: () => WEBHOOK_LANE,
   WEBHOOK_SECRET_BASE: () => WEBHOOK_SECRET_BASE,
   WEBHOOK_SECRET_NAME_SHAPE: () => WEBHOOK_SECRET_NAME_SHAPE,
@@ -98,6 +101,7 @@ __export(index_exports, {
   axisInfo: () => axisInfo,
   axisSource: () => axisSource,
   bizTransactionUri: () => bizTransactionUri,
+  canPreview: () => canPreview,
   capabilitiesForType: () => capabilitiesForType,
   capabilityOf: () => capabilityOf,
   checkSequence: () => checkSequence,
@@ -165,6 +169,7 @@ __export(index_exports, {
   isPlannedStopStatus: () => isPlannedStopStatus,
   isResourceKind: () => isResourceKind,
   isTransformationRecord: () => isTransformationRecord,
+  isWebhookDeliveryCode: () => isWebhookDeliveryCode,
   isWebhookSecretSegment: () => isWebhookSecretSegment,
   isoDurationHours: () => isoDurationHours,
   itemKeyOf: () => itemKeyOf,
@@ -224,10 +229,12 @@ __export(index_exports, {
   testPassedAt: () => testPassedAt,
   transactionEvent: () => transactionEvent,
   transformationEvent: () => transformationEvent,
+  unavailableVerdict: () => unavailableVerdict,
   validateDomainDefinition: () => validateDomainDefinition,
   validateEpcisEvent: () => validateEpcisEvent,
   validatePerformance: () => validatePerformance,
   validateScenario: () => validateScenario,
+  verdictOfAck: () => verdictOfAck,
   webhookLaneOf: () => webhookLaneOf,
   webhookSecretCandidates: () => webhookSecretCandidates,
   webhookSecretEnvName: () => webhookSecretEnvName,
@@ -902,6 +909,22 @@ var OP_EVENT = {
    * 이것은 **결정**이다. 누가·언제·왜 그렇게 정했는지의 자리는 그쪽에 없다.
    */
   disposition: "nonconformance.disposition",
+  /**
+   * **로트 상태** — ISA-95 `MaterialLot.Status`(B2MML-Material.xsd). 「이 로트가 지금 어떤 것이냐」의 결정.
+   *
+   * ── `nonconformance.disposition` 과 다른 사실이다 (2026-09-16) ──────────────
+   * 그것은 표준 `Disposition` — **부적합을 어떻게 처리하나**(재작업·특채·폐기). 이것은 표준 `Status` — 적합한
+   * 로트에도 붙는 상태(released · quarantine · on-hold …). 출하 승인(batch release)이 이 축이다. 처분에 실으면
+   * 정상 출하가 전부 부적합 이력이 된다 — 진짜 term 을 틀린 뜻으로 쓰는 것이 자리가 없는 것보다 나쁘다.
+   *
+   * ── 낱말은 열려 있다 ──────────────────────────────────────────────────────
+   * 오더 상태와 같은 규율 — 커널이 이 낱말로 무엇을 계산하지 않으므로 닫을 근거가 없다. 도메인이 소유한다.
+   *
+   * ── 출발과 다른 사실이다 ─────────────────────────────────────────────────
+   * 승인은 자재를 움직이지 않는다. 자재가 트윈 밖으로 나가는 것은 EPCIS `shipping` 사건이다. 둘을 한 사건으로
+   * 접지 않는다 — 승인됐는데 안 나간 배치가 트윈이 보여야 할 상태다.
+   */
+  materialLot: "material-lot.status",
   /**
    * **이 목록이 전부다** — 연결된 시스템이 현재 목록을 한 바퀴 다 보낸 뒤 그것을 알린다.
    *
@@ -1293,8 +1316,14 @@ var MES_BIZSTEP = {
   // 원자재 수령
   producing: "urn:epcglobal:cbv:bizstep:commissioning",
   // 생산(제품 최초 생성)
-  storing: "urn:epcglobal:cbv:bizstep:storing"
+  storing: "urn:epcglobal:cbv:bizstep:storing",
   // 완제품 저장
+  /**
+   * **출하** — CBV `shipping`: 물품이 시설을 떠난다. 자재를 트윈 밖으로 내는 것은 이 사건이다(disposition
+   * `in_transit`, readPoint = 출하 dock). 출하 **승인**은 이 사건이 아니라 로트 상태(`OP_EVENT.materialLot`)다 —
+   * 승인됐는데 안 나간 배치가 보여야 한다(2026-09-16, ADR-0046 곁).
+   */
+  shipping: "urn:epcglobal:cbv:bizstep:shipping"
 };
 var BTT_PRODORDER = "urn:epcglobal:cbv:btt:prodorder";
 function sgtinUri(companyPrefix, itemRef, serial) {
@@ -3681,6 +3710,21 @@ var SPECS = {
     },
     enums: { decision: DISPOSITION_DECISION }
   },
+  /*
+   * **로트 상태** — ISA-95 `MaterialLot.Status`. 출하 승인(batch release)이 들어오는 문(§`OP_EVENT.materialLot`).
+   *
+   * `disposition`(subjectId + decision) 과 필드가 겹치지 않는다 — 여기는 `epc` + `status`. 상태 낱말은 열려
+   * 있어 enum 이 없다(오더 상태와 같은 규율). 로트 전체의 사실이므로 `subLotId` 는 받지 않는다 — 부분마다 다른
+   * 상태가 필요해지면 그것은 다른 사실이다.
+   */
+  "material-lot": {
+    eventType: OP_EVENT.materialLot,
+    match: ["epc", "status"],
+    matchOrder: 85,
+    identity: "epc",
+    required: ["epc", "status"],
+    fields: { epc: "string", status: "string", decidedBy: "string", reason: "string", decidedAt: "string", recordTime: "string" }
+  },
   test: {
     eventType: OP_EVENT.test,
     match: ["testableObjectId"],
@@ -4045,6 +4089,51 @@ function retiredVocabularyIn(line) {
   return hits;
 }
 
+// src/command-verdict.ts
+var REFUSED_WITHOUT_CODE = "refused";
+function verdictOfAck(ack) {
+  if (ack.accepted) return { verdict: "accepted", commandId: ack.commandId };
+  const reason = { code: ack.errorCode ?? REFUSED_WITHOUT_CODE };
+  if (ack.errorParams !== void 0) reason.params = ack.errorParams;
+  if (ack.error !== void 0) reason.message = ack.error;
+  return { verdict: "refused", commandId: ack.commandId, reason };
+}
+function unavailableVerdict(code, params, message) {
+  const reason = { code };
+  if (params !== void 0) reason.params = params;
+  if (message !== void 0) reason.message = message;
+  return { verdict: "unavailable", reason };
+}
+function canPreview(runtime) {
+  if (runtime === null || typeof runtime !== "object") return false;
+  const r = runtime;
+  return typeof r.fork === "function" && typeof r.dispatch === "function";
+}
+
+// src/webhook-delivery.ts
+var WEBHOOK_DELIVERY_CODES = {
+  /** The peer received and verified the envelope, then declined the job order itself (200, accepted=false). */
+  jobOrderRefused: "job-order-refused",
+  /** The envelope does not match the specification — retry never helps until the sender changes (400). */
+  envelopeInvalid: "envelope-invalid",
+  /** The signature did not verify (401). `params.reason` is `mismatch` or `expired`. */
+  signatureRejected: "signature-rejected",
+  /** The peer has no such site (404). */
+  siteUnknown: "site-unknown",
+  /** The peer has no verify key under the name the sender used (503). `params.peer` names that peer — never the env var. */
+  verifySecretMissing: "verify-secret-missing",
+  /** No HTTP answer at all — DNS, connection refused, timeout. */
+  peerUnreachable: "peer-unreachable",
+  /** The peer verified the envelope and then failed on its own side — storing, for instance (500). Retrying may help. */
+  peerInternalFailure: "peer-internal-failure",
+  /** An answer came back that fits none of the above — the code is the honest "unclassified", not a guess. */
+  responseUnrecognised: "response-unrecognised"
+};
+var SIGNATURE_REJECTED_REASONS = ["mismatch", "expired"];
+function isWebhookDeliveryCode(code) {
+  return Object.values(WEBHOOK_DELIVERY_CODES).includes(code);
+}
+
 // src/webhook.ts
 var WEBHOOK_STATUS = {
   ok: 200,
@@ -4139,13 +4228,13 @@ function webhookSecretEnvName(base, domain, peer) {
   return [base, ...segments.map((s) => s.toUpperCase().replace(/-/g, "_"))].join("__");
 }
 function webhookSecretCandidates(lookup) {
-  const { purpose, domain, peer, legacyBases = [], allowSinglePeerFallback = false } = lookup;
+  const { purpose, domain, peer, legacyBases = [] } = lookup;
   const base = WEBHOOK_SECRET_BASE[purpose];
   const out = [
     { name: webhookSecretEnvName(base, domain, peer), pins: "peer", compatibility: false }
   ];
-  if (purpose === "verify" && !allowSinglePeerFallback) return out;
-  out.push({ name: webhookSecretEnvName(base, domain), pins: "domain", compatibility: purpose === "verify" });
+  if (purpose === "verify") return out;
+  out.push({ name: webhookSecretEnvName(base, domain), pins: "domain", compatibility: false });
   for (const legacy of legacyBases) {
     out.push({ name: webhookSecretEnvName(legacy, domain), pins: "domain", compatibility: true });
     out.push({ name: legacy, pins: "installation", compatibility: true });
@@ -4536,9 +4625,11 @@ function nonEmpty(value) {
   OP_PARAM,
   ORDER_TERMINAL_STATUS,
   PRIORITY_UNSET,
+  REFUSED_WITHOUT_CODE,
   RESOURCE_KIND,
   RETIRED_VOCABULARY,
   SCHEDULE_STATUS,
+  SIGNATURE_REJECTED_REASONS,
   TWIN_AXES,
   TWIN_PROPERTIES,
   TWIN_RELATIONS,
@@ -4546,6 +4637,7 @@ function nonEmpty(value) {
   UTC_OFFSET,
   VOCABULARY_EXCEPTIONS,
   VOCABULARY_TYPE,
+  WEBHOOK_DELIVERY_CODES,
   WEBHOOK_LANE,
   WEBHOOK_SECRET_BASE,
   WEBHOOK_SECRET_NAME_SHAPE,
@@ -4569,6 +4661,7 @@ function nonEmpty(value) {
   axisInfo,
   axisSource,
   bizTransactionUri,
+  canPreview,
   capabilitiesForType,
   capabilityOf,
   checkSequence,
@@ -4636,6 +4729,7 @@ function nonEmpty(value) {
   isPlannedStopStatus,
   isResourceKind,
   isTransformationRecord,
+  isWebhookDeliveryCode,
   isWebhookSecretSegment,
   isoDurationHours,
   itemKeyOf,
@@ -4695,10 +4789,12 @@ function nonEmpty(value) {
   testPassedAt,
   transactionEvent,
   transformationEvent,
+  unavailableVerdict,
   validateDomainDefinition,
   validateEpcisEvent,
   validatePerformance,
   validateScenario,
+  verdictOfAck,
   webhookLaneOf,
   webhookSecretCandidates,
   webhookSecretEnvName,

package/package.json

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