@operato/ops-contract 0.9.17 → 0.9.19

package/README.md

@@ -14,6 +14,64 @@ 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 내부에서 갈린다.
+
 ## 왜 나뉘어 있나
 
 사실을 **만드는 쪽**(MES · 커넥터)은 계약만 필요하고 엔진은 필요 없습니다. 한 패키지에 두면 레코드

package/dist/index.d.ts

@@ -25,3 +25,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

@@ -48,3 +48,4 @@ export * from "./yield.js";
 export * from "./reliability.js";
 export * from "./erp.js";
 export * from "./actuation.js";
+export * from "./operational-attention.js";

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/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,6 +58,9 @@ __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,
@@ -72,6 +75,7 @@ __export(index_exports, {
   UTC_OFFSET: () => UTC_OFFSET,
   VOCABULARY_EXCEPTIONS: () => VOCABULARY_EXCEPTIONS,
   VOCABULARY_TYPE: () => VOCABULARY_TYPE,
+  WEBHOOK_LANE: () => WEBHOOK_LANE,
   WEBHOOK_SECRET_BASE: () => WEBHOOK_SECRET_BASE,
   WEBHOOK_SECRET_NAME_SHAPE: () => WEBHOOK_SECRET_NAME_SHAPE,
   WEBHOOK_STATUS: () => WEBHOOK_STATUS,
@@ -88,6 +92,7 @@ __export(index_exports, {
   analyzeCapacity: () => analyzeCapacity,
   approveCommand: () => approveCommand,
   asApproved: () => asApproved,
+  assertOperationalAttentionV1: () => assertOperationalAttentionV1,
   axesOfSystem: () => axesOfSystem,
   axisAppliesTo: () => axisAppliesTo,
   axisInfo: () => axisInfo,
@@ -154,6 +159,7 @@ __export(index_exports, {
   isEquipmentStatus: () => isEquipmentStatus,
   isFailureStatus: () => isFailureStatus,
   isMasterDataRecord: () => isMasterDataRecord,
+  isOperationalAttentionV1: () => isOperationalAttentionV1,
   isOperationalRecord: () => isOperationalRecord,
   isOrderTerminal: () => isOrderTerminal,
   isPlannedStopStatus: () => isPlannedStopStatus,
@@ -222,6 +228,7 @@ __export(index_exports, {
   validateEpcisEvent: () => validateEpcisEvent,
   validatePerformance: () => validatePerformance,
   validateScenario: () => validateScenario,
+  webhookLaneOf: () => webhookLaneOf,
   webhookSecretCandidates: () => webhookSecretCandidates,
   webhookSecretEnvName: () => webhookSecretEnvName,
   webhookSecretFrom: () => webhookSecretFrom,
@@ -4050,6 +4057,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:
@@ -4453,6 +4467,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,6 +4529,9 @@ 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,
@@ -4508,6 +4546,7 @@ function commandSpecGaps(specs, command) {
   UTC_OFFSET,
   VOCABULARY_EXCEPTIONS,
   VOCABULARY_TYPE,
+  WEBHOOK_LANE,
   WEBHOOK_SECRET_BASE,
   WEBHOOK_SECRET_NAME_SHAPE,
   WEBHOOK_STATUS,
@@ -4524,6 +4563,7 @@ function commandSpecGaps(specs, command) {
   analyzeCapacity,
   approveCommand,
   asApproved,
+  assertOperationalAttentionV1,
   axesOfSystem,
   axisAppliesTo,
   axisInfo,
@@ -4590,6 +4630,7 @@ function commandSpecGaps(specs, command) {
   isEquipmentStatus,
   isFailureStatus,
   isMasterDataRecord,
+  isOperationalAttentionV1,
   isOperationalRecord,
   isOrderTerminal,
   isPlannedStopStatus,
@@ -4658,6 +4699,7 @@ function commandSpecGaps(specs, command) {
   validateEpcisEvent,
   validatePerformance,
   validateScenario,
+  webhookLaneOf,
   webhookSecretCandidates,
   webhookSecretEnvName,
   webhookSecretFrom,

package/package.json

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