@operato/ops-contract 0.9.17 → 0.9.20

package/README.md

@@ -14,6 +14,90 @@ IEC 61850 · ISO 50001    전기 계통과 성과지표
 
 여기 없는 것은 **정책과 엔진**입니다. 그 사실로 무엇을 할지는 `@operato/twin-kernel` 이 정합니다.
 
+## 제품 간 AI 분석 입력 — `OperationalAttentionV1`
+
+`OperationalAttentionV1`은 Plant·WMS·YMS·EMS가 자신이 관측한 운영 주의 사실을 Twin 또는 AI 분석기에
+보낼 때 쓰는 공통 봉투입니다. 국제 표준의 알람 포맷을 새로 만드는 것이 아닙니다. EPCIS/ISA-95 등의
+원본 사실을 **어떤 제품이, 어떤 근거로, 무엇을 분석 대상으로 열었거나 닫았는지** 안전하게 전달하는
+Operato의 제품 간 계약입니다.
+
+```ts
+import {
+  OPERATIONAL_ATTENTION_CONTRACT,
+  assertOperationalAttentionV1,
+  type OperationalAttentionV1
+} from '@operato/ops-contract'
+
+const attention: OperationalAttentionV1 = {
+  contract: OPERATIONAL_ATTENTION_CONTRACT,
+  domainId: 'factory-a',
+  attentionId: 'schedule-overdue:line-a:101',
+  dedupeKey: 'schedule-overdue:line-a:101',
+  kind: 'plant.schedule-overdue',
+  subjectLabel: 'Line A schedule 101',
+  transition: 'opened',
+  impact: 'high',
+  observedAt: '2026-09-12T01:00:00.000Z',
+  evidenceFingerprint: 'sha256:...',
+  facts: [{ system: 'operato-plant', type: 'schedule-entry', id: '101' }]
+}
+
+assertOperationalAttentionV1(attention)
+```
+
+### 공통으로 고정한 것
+
+- 식별·재전송: `attentionId`, `dedupeKey`
+- 분석 수명주기: `opened`, `changed`, `resolved`, `reopened`
+- 분석 우선순위: `medium`, `high`
+- 근거: 최소 하나 이상의 안정된 `{ system, type, id }` 원본 사실 참조와 `evidenceFingerprint`
+
+사람이 읽는 제목만 있고 원본 사실 ID가 없는 입력은 거부합니다. AI가 그럴듯한 설명을 만들더라도
+근거를 다시 열어 볼 수 없으면 운영 분석의 입력이 될 수 없기 때문입니다.
+
+### 제품별로 남기는 것
+
+`kind`와 `facts[].type`은 생산자가 소유합니다. 예를 들어 Plant는 `plant.schedule-overdue`, WMS는
+`wms.short-pick`을 쓰며 서로의 업무 모델을 흉내 내지 않습니다. 또한 `acknowledged`, `suppressed`,
+승인, 실제 조치 결과는 생산 제품의 업무 흐름에 남습니다. 이 계약은 분석에 필요한 **사실 변화**만
+전달하며, 수신자가 현장을 조치할 권한을 주지 않습니다.
+
+새 제품이 붙을 때는 공통 봉투를 넓히기 전에 그 제품의 adapter에서 자기 `kind`·사실 유형·판정 기준을
+검증합니다. 모든 제품이 실제로 공유하는 필드만 이 계약에 추가합니다.
+
+### 기존 webhook을 통한 전송
+
+새 URL은 만들지 않는다. attention도 기존 `POST /domain/{domain}/twin/hook/{source}/{instanceId}`로 보내며,
+봉투의 `lane: 'ATTENTIONS'`가 Twin의 AI inbox 경로를 고른다. `scope`는 계속 원천의 순번 흐름 이름이며
+`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';
@@ -25,3 +27,4 @@ export * from './yield.ts';
 export * from './reliability.ts';
 export * from './erp.ts';
 export * from './actuation.ts';
+export * from './operational-attention.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`). */
@@ -48,3 +50,4 @@ export * from "./yield.js";
 export * from "./reliability.js";
 export * from "./erp.js";
 export * from "./actuation.js";
+export * from "./operational-attention.js";

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-attention.d.ts

@@ -0,0 +1,43 @@
+import type { ISOTime } from './contract.ts';
+/**
+ * Product-neutral evidence for an operational concern that another product's
+ * Twin/AI may analyse. It is not an alarm protocol and never authorises work.
+ *
+ * A producer owns how it detects and manages an attention. Consumers receive
+ * only its evidence-backed lifecycle change; acknowledgement, suppression,
+ * approval, and outcome remain in the producer's workflow.
+ */
+export declare const OPERATIONAL_ATTENTION_CONTRACT: "operational.attention.v1";
+export declare const OPERATIONAL_ATTENTION_TRANSITIONS: readonly ["opened", "changed", "resolved", "reopened"];
+export declare const OPERATIONAL_ATTENTION_IMPACTS: readonly ["medium", "high"];
+export type OperationalAttentionTransition = (typeof OPERATIONAL_ATTENTION_TRANSITIONS)[number];
+export type OperationalAttentionImpact = (typeof OPERATIONAL_ATTENTION_IMPACTS)[number];
+/** Stable reference to a fact held by the producing product. */
+export interface OperationalFactReference {
+    /** Product/system that owns the source fact, e.g. operato-plant or operato-wms. */
+    system: string;
+    /** Producer-owned entity vocabulary, e.g. schedule-entry or inventory. */
+    type: string;
+    id: string;
+    observedAt?: ISOTime;
+    label?: string;
+}
+export interface OperationalAttentionV1 {
+    contract: typeof OPERATIONAL_ATTENTION_CONTRACT;
+    domainId: string;
+    /** Stable producer identifier; unchanged across lifecycle updates. */
+    attentionId: string;
+    dedupeKey: string;
+    /** Producer-owned, namespaced reason code (for example plant.schedule-overdue). */
+    kind: string;
+    subjectLabel: string;
+    transition: OperationalAttentionTransition;
+    impact: OperationalAttentionImpact;
+    observedAt: ISOTime;
+    /** Deterministic hash of the evidence used for this particular observation. */
+    evidenceFingerprint: string;
+    /** At least one stable producer fact is mandatory; labels alone are not evidence. */
+    facts: OperationalFactReference[];
+}
+export declare function isOperationalAttentionV1(value: unknown): value is OperationalAttentionV1;
+export declare function assertOperationalAttentionV1(value: unknown): asserts value is OperationalAttentionV1;

package/dist/operational-attention.js

@@ -0,0 +1,35 @@
+/**
+ * Product-neutral evidence for an operational concern that another product's
+ * Twin/AI may analyse. It is not an alarm protocol and never authorises work.
+ *
+ * A producer owns how it detects and manages an attention. Consumers receive
+ * only its evidence-backed lifecycle change; acknowledgement, suppression,
+ * approval, and outcome remain in the producer's workflow.
+ */
+export const OPERATIONAL_ATTENTION_CONTRACT = 'operational.attention.v1';
+export const OPERATIONAL_ATTENTION_TRANSITIONS = ['opened', 'changed', 'resolved', 'reopened'];
+export const OPERATIONAL_ATTENTION_IMPACTS = ['medium', 'high'];
+export function isOperationalAttentionV1(value) {
+    const one = value;
+    return !!one && typeof one === 'object' &&
+        one.contract === OPERATIONAL_ATTENTION_CONTRACT &&
+        nonEmpty(one.domainId) && nonEmpty(one.attentionId) && nonEmpty(one.dedupeKey) &&
+        nonEmpty(one.kind) && nonEmpty(one.subjectLabel) && nonEmpty(one.observedAt) && nonEmpty(one.evidenceFingerprint) &&
+        OPERATIONAL_ATTENTION_TRANSITIONS.includes(one.transition) &&
+        OPERATIONAL_ATTENTION_IMPACTS.includes(one.impact) &&
+        Array.isArray(one.facts) && one.facts.length > 0 && one.facts.every(isOperationalFactReference);
+}
+export function assertOperationalAttentionV1(value) {
+    if (!isOperationalAttentionV1(value)) {
+        throw new Error('invalid operational.attention.v1: lifecycle fields and stable source-fact references are required');
+    }
+}
+function isOperationalFactReference(value) {
+    const one = value;
+    return !!one && typeof one === 'object' && nonEmpty(one.system) && nonEmpty(one.type) && nonEmpty(one.id) &&
+        (one.observedAt === undefined || nonEmpty(one.observedAt)) &&
+        (one.label === undefined || nonEmpty(one.label));
+}
+function nonEmpty(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}

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/webhook.d.ts

@@ -30,6 +30,18 @@ export declare const WEBHOOK_STATUS: {
     readonly notLive: 503;
 };
 export type WebhookStatus = (typeof WEBHOOK_STATUS)[keyof typeof WEBHOOK_STATUS];
+/**
+ * A webhook lane says what the envelope is for; it is deliberately separate
+ * from `scope`, which names the producer's sequence stream.
+ *
+ * Omitting it means FACTS so every existing connector remains compatible.
+ */
+export declare const WEBHOOK_LANE: {
+    readonly facts: "FACTS";
+    readonly attentions: "ATTENTIONS";
+};
+export type WebhookLane = (typeof WEBHOOK_LANE)[keyof typeof WEBHOOK_LANE];
+export declare function webhookLaneOf(value: unknown): WebhookLane | undefined;
 /**
  * 그 응답을 받은 뒤 보내는 쪽이 할 일.
  *
@@ -217,6 +229,11 @@ export interface WebhookEnvelope {
     seq: number;
     /** 번호를 매기는 단위의 이름. 보내는 쪽이 정하고 받는 쪽은 열쇠로만 다룬다. */
     scope: string;
+    /**
+     * Delivery purpose. `scope` remains the source-owned numbering stream;
+     * `lane` selects the receiver path. Missing means `FACTS` for compatibility.
+     */
+    lane?: WebhookLane;
     /** 멱등 키. 같은 값이 두 번 와도 결과가 같아야 한다. */
     eventId?: string;
     /** 사실이 일어난 시각. */

package/dist/webhook.js

@@ -45,6 +45,23 @@ export const WEBHOOK_STATUS = {
     unsupported: 501,
     notLive: 503
 };
+/**
+ * A webhook lane says what the envelope is for; it is deliberately separate
+ * from `scope`, which names the producer's sequence stream.
+ *
+ * Omitting it means FACTS so every existing connector remains compatible.
+ */
+export const WEBHOOK_LANE = {
+    facts: 'FACTS',
+    attentions: 'ATTENTIONS'
+};
+export function webhookLaneOf(value) {
+    return value === undefined || value === WEBHOOK_LANE.facts
+        ? WEBHOOK_LANE.facts
+        : value === WEBHOOK_LANE.attentions
+            ? WEBHOOK_LANE.attentions
+            : undefined;
+}
 /**
  * 응답 코드 → 보내는 쪽의 행동. **모르는 코드도 답을 낸다.**
  *

package/dist-cjs/index.cjs

@@ -58,13 +58,18 @@ __export(index_exports, {
   MES_TYPES: () => MES_TYPES,
   METER_DIRECTION: () => METER_DIRECTION,
   OBSERVATION_BASIS: () => OBSERVATION_BASIS,
+  OPERATIONAL_ATTENTION_CONTRACT: () => OPERATIONAL_ATTENTION_CONTRACT,
+  OPERATIONAL_ATTENTION_IMPACTS: () => OPERATIONAL_ATTENTION_IMPACTS,
+  OPERATIONAL_ATTENTION_TRANSITIONS: () => OPERATIONAL_ATTENTION_TRANSITIONS,
   OP_EVENT: () => OP_EVENT,
   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,
@@ -72,6 +77,8 @@ __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,
   WEBHOOK_STATUS: () => WEBHOOK_STATUS,
@@ -88,11 +95,13 @@ __export(index_exports, {
   analyzeCapacity: () => analyzeCapacity,
   approveCommand: () => approveCommand,
   asApproved: () => asApproved,
+  assertOperationalAttentionV1: () => assertOperationalAttentionV1,
   axesOfSystem: () => axesOfSystem,
   axisAppliesTo: () => axisAppliesTo,
   axisInfo: () => axisInfo,
   axisSource: () => axisSource,
   bizTransactionUri: () => bizTransactionUri,
+  canPreview: () => canPreview,
   capabilitiesForType: () => capabilitiesForType,
   capabilityOf: () => capabilityOf,
   checkSequence: () => checkSequence,
@@ -154,11 +163,13 @@ __export(index_exports, {
   isEquipmentStatus: () => isEquipmentStatus,
   isFailureStatus: () => isFailureStatus,
   isMasterDataRecord: () => isMasterDataRecord,
+  isOperationalAttentionV1: () => isOperationalAttentionV1,
   isOperationalRecord: () => isOperationalRecord,
   isOrderTerminal: () => isOrderTerminal,
   isPlannedStopStatus: () => isPlannedStopStatus,
   isResourceKind: () => isResourceKind,
   isTransformationRecord: () => isTransformationRecord,
+  isWebhookDeliveryCode: () => isWebhookDeliveryCode,
   isWebhookSecretSegment: () => isWebhookSecretSegment,
   isoDurationHours: () => isoDurationHours,
   itemKeyOf: () => itemKeyOf,
@@ -218,10 +229,13 @@ __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,
   webhookSecretFrom: () => webhookSecretFrom,
@@ -895,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",
   /**
    * **이 목록이 전부다** — 연결된 시스템이 현재 목록을 한 바퀴 다 보낸 뒤 그것을 알린다.
    *
@@ -1286,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) {
@@ -3674,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"],
@@ -4038,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,
@@ -4050,6 +4146,13 @@ var WEBHOOK_STATUS = {
   unsupported: 501,
   notLive: 503
 };
+var WEBHOOK_LANE = {
+  facts: "FACTS",
+  attentions: "ATTENTIONS"
+};
+function webhookLaneOf(value) {
+  return value === void 0 || value === WEBHOOK_LANE.facts ? WEBHOOK_LANE.facts : value === WEBHOOK_LANE.attentions ? WEBHOOK_LANE.attentions : void 0;
+}
 function webhookSenderAction(status) {
   switch (status) {
     case WEBHOOK_STATUS.ok:
@@ -4125,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 });
@@ -4453,6 +4556,27 @@ function commandSpecGaps(specs, command) {
   }
   return gaps;
 }
+
+// src/operational-attention.ts
+var OPERATIONAL_ATTENTION_CONTRACT = "operational.attention.v1";
+var OPERATIONAL_ATTENTION_TRANSITIONS = ["opened", "changed", "resolved", "reopened"];
+var OPERATIONAL_ATTENTION_IMPACTS = ["medium", "high"];
+function isOperationalAttentionV1(value) {
+  const one = value;
+  return !!one && typeof one === "object" && one.contract === OPERATIONAL_ATTENTION_CONTRACT && nonEmpty(one.domainId) && nonEmpty(one.attentionId) && nonEmpty(one.dedupeKey) && nonEmpty(one.kind) && nonEmpty(one.subjectLabel) && nonEmpty(one.observedAt) && nonEmpty(one.evidenceFingerprint) && OPERATIONAL_ATTENTION_TRANSITIONS.includes(one.transition) && OPERATIONAL_ATTENTION_IMPACTS.includes(one.impact) && Array.isArray(one.facts) && one.facts.length > 0 && one.facts.every(isOperationalFactReference);
+}
+function assertOperationalAttentionV1(value) {
+  if (!isOperationalAttentionV1(value)) {
+    throw new Error("invalid operational.attention.v1: lifecycle fields and stable source-fact references are required");
+  }
+}
+function isOperationalFactReference(value) {
+  const one = value;
+  return !!one && typeof one === "object" && nonEmpty(one.system) && nonEmpty(one.type) && nonEmpty(one.id) && (one.observedAt === void 0 || nonEmpty(one.observedAt)) && (one.label === void 0 || nonEmpty(one.label));
+}
+function nonEmpty(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BIZSTEP,
@@ -4494,13 +4618,18 @@ function commandSpecGaps(specs, command) {
   MES_TYPES,
   METER_DIRECTION,
   OBSERVATION_BASIS,
+  OPERATIONAL_ATTENTION_CONTRACT,
+  OPERATIONAL_ATTENTION_IMPACTS,
+  OPERATIONAL_ATTENTION_TRANSITIONS,
   OP_EVENT,
   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,
@@ -4508,6 +4637,8 @@ function commandSpecGaps(specs, command) {
   UTC_OFFSET,
   VOCABULARY_EXCEPTIONS,
   VOCABULARY_TYPE,
+  WEBHOOK_DELIVERY_CODES,
+  WEBHOOK_LANE,
   WEBHOOK_SECRET_BASE,
   WEBHOOK_SECRET_NAME_SHAPE,
   WEBHOOK_STATUS,
@@ -4524,11 +4655,13 @@ function commandSpecGaps(specs, command) {
   analyzeCapacity,
   approveCommand,
   asApproved,
+  assertOperationalAttentionV1,
   axesOfSystem,
   axisAppliesTo,
   axisInfo,
   axisSource,
   bizTransactionUri,
+  canPreview,
   capabilitiesForType,
   capabilityOf,
   checkSequence,
@@ -4590,11 +4723,13 @@ function commandSpecGaps(specs, command) {
   isEquipmentStatus,
   isFailureStatus,
   isMasterDataRecord,
+  isOperationalAttentionV1,
   isOperationalRecord,
   isOrderTerminal,
   isPlannedStopStatus,
   isResourceKind,
   isTransformationRecord,
+  isWebhookDeliveryCode,
   isWebhookSecretSegment,
   isoDurationHours,
   itemKeyOf,
@@ -4654,10 +4789,13 @@ function commandSpecGaps(specs, command) {
   testPassedAt,
   transactionEvent,
   transformationEvent,
+  unavailableVerdict,
   validateDomainDefinition,
   validateEpcisEvent,
   validatePerformance,
   validateScenario,
+  verdictOfAck,
+  webhookLaneOf,
   webhookSecretCandidates,
   webhookSecretEnvName,
   webhookSecretFrom,

package/package.json

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