@operato/ops-contract 0.9.8 → 0.9.10

package/dist/operational-ingest.d.ts

@@ -34,7 +34,7 @@ export interface OperationalIngestOptions {
  * 거절도 경고도 없었다. **같은 계약의 ERP 경로는 이것을 잡는다**(§`erp.ts` 의 자재 줄 검사).
  * 한 계약 안에 검사가 두 벌이고 한쪽만 봤다.
  *
- * 이름을 맞춰 달라고 원본에 청하는 것으로는 다음에 또 조용해진다 — 다음 원본이 `use: 'out'` 같은
+ * 이름을 맞춰 달라고 원본에 요청하는 것으로는 다음에 또 오류보고없이 넘어간다. 다음 원본이 `use: 'out'` 같은
  * 것을 보내면 같은 일이 난다(실제로 그런 시드가 있었다: 계약에 `out` 이라는 낱말이 없다).
  */
 export interface ObjectShape {
@@ -62,6 +62,25 @@ export interface ObjectShape {
  */
 export declare function operationalKindOf(record: unknown): OperationalKind | undefined;
 /** 이 레코드가 운영 사실인가 — 호스트의 라우팅이 묻는 자리. */
+/**
+ * 그 종류의 사실을 **무엇이 가리키나** — 선언된 identity 칸의 이름.
+ *
+ * ── 왜 내보내나 (2026-09-06) ───────────────────────────────────────────────
+ * 이 선언은 여기 있는데 밖에서 읽을 수 없었다. 그래서 중복 판정(`ingest-dedupe.ts`)이 같은 목록을
+ * **손으로 옮겨** 들고 있었고, 새 종류가 생길 때마다 조용히 뒤처졌다.
+ *
+ * 실제로 두 번 그랬다.
+ *
+ * ```
+ * subjectId          처분 · 목록에 없어 정체를 아예 못 만들었다 → dedupe 밖
+ * testableObjectId   시험 · 목록에 없어 같은 명세·같은 시각의 다른 로트가 뭉칠 수 있었다
+ * ```
+ *
+ * 뒤엣것이 더 나쁘다. 중복은 눈에 보이지만 뭉친 것은 **사실 하나가 사라진 것**이고 아무 흔적이 없다.
+ *
+ * 모르는 종류에는 `undefined` 를 낸다 — 짐작으로 이름을 내지 않는다.
+ */
+export declare function operationalIdentityField(kind: OperationalKind | undefined): string | undefined;
 export declare function isOperationalRecord(record: unknown): boolean;
 /**
  * 운영 레코드들을 봉투로 — 유효한 것만 통과하고 나머지는 **이유와 함께** 남는다.

package/dist/operational-ingest.js

@@ -401,6 +401,27 @@ export function operationalKindOf(record) {
  */
 const MATCH_ORDER = Object.keys(SPECS).sort((a, b) => (SPECS[a].matchOrder ?? 1000) - (SPECS[b].matchOrder ?? 1000));
 /** 이 레코드가 운영 사실인가 — 호스트의 라우팅이 묻는 자리. */
+/**
+ * 그 종류의 사실을 **무엇이 가리키나** — 선언된 identity 칸의 이름.
+ *
+ * ── 왜 내보내나 (2026-09-06) ───────────────────────────────────────────────
+ * 이 선언은 여기 있는데 밖에서 읽을 수 없었다. 그래서 중복 판정(`ingest-dedupe.ts`)이 같은 목록을
+ * **손으로 옮겨** 들고 있었고, 새 종류가 생길 때마다 조용히 뒤처졌다.
+ *
+ * 실제로 두 번 그랬다.
+ *
+ * ```
+ * subjectId          처분 · 목록에 없어 정체를 아예 못 만들었다 → dedupe 밖
+ * testableObjectId   시험 · 목록에 없어 같은 명세·같은 시각의 다른 로트가 뭉칠 수 있었다
+ * ```
+ *
+ * 뒤엣것이 더 나쁘다. 중복은 눈에 보이지만 뭉친 것은 **사실 하나가 사라진 것**이고 아무 흔적이 없다.
+ *
+ * 모르는 종류에는 `undefined` 를 낸다 — 짐작으로 이름을 내지 않는다.
+ */
+export function operationalIdentityField(kind) {
+    return kind ? SPECS[kind]?.identity : undefined;
+}
 export function isOperationalRecord(record) {
     return operationalKindOf(record) !== undefined;
 }

package/dist/webhook.d.ts

@@ -79,7 +79,7 @@ export interface WebhookEnvelope {
 /**
  * 번호 판정 — **네 가지이고, 합치지 않는다.**
  *
- *   first    이 단위의 첫 봉투다. 받는 쪽에 커서가 없다
+ *   first    이 단위의 첫 봉투다. 받는 쪽에 커서가 없다 — 그 앞을 몇 개 못 봤는지 함께 낸다
  *   next     바로 다음 번호다
  *   behind   이미 본 번호다. 재전송이다
  *   gap      건너뛰었다. `expectedSeq` 부터 다시 받아야 한다
@@ -94,6 +94,24 @@ export interface WebhookEnvelope {
 export type SequenceVerdict = {
     kind: 'first';
     lastSeq: number;
+    /**
+     * 이 번호 아래로 몇 개가 있나 — **받은 적이 없는 개수**다(`seq - 1`).
+     *
+     * ── 왜 필요한가 (2026-09-06 실측, 인티그레이션 레인이 찾음) ──────────────
+     * plant 아웃박스의 1~20 이 400 으로 거절돼 그 연결에 커서가 없었다. 그래서 다음에 온 21번이
+     * **첫 봉투로 앉으며 커서가 21 로 뛰었다.** 커서가 0 이었다면 같은 21이 `gap` 이었다.
+     *
+     * 스무 건이 없는데 빈 구간으로도 안 세어지고, 경고도 없고, backfill 대상도 아니었다. backfill 은
+     * 커서(48)부터 묻기 때문에 영영 메워지지 않는다.
+     *
+     * ── 「잃었다」가 아니다 ────────────────────────────────────────────────
+     * 이 수가 곧 손실은 아니다. 원본이 오래 돌고 있는데 트윈을 나중에 붙이면 seq 4,712 부터 받는
+     * 것이 정상이고, 그 아래 4,711 개는 **애초에 안 받기로 한 것**이다.
+     *
+     * 계약은 둘을 구별할 수 없다. 그래서 「못 봤다」까지만 말하고 손실인지는 판정하지 않는다.
+     * 판정에 필요한 것(원본이 언제부터 보냈나)은 원본만 안다.
+     */
+    unseenBefore: number;
 } | {
     kind: 'next';
     lastSeq: number;

package/dist/webhook.js

@@ -90,7 +90,7 @@ export function checkSequence(lastSeq, seq) {
         throw new Error(`checkSequence: 번호는 1 이상의 정수여야 한다 — 받은 값 ${JSON.stringify(seq)}`);
     }
     if (lastSeq === undefined || lastSeq === null)
-        return { kind: 'first', lastSeq: seq };
+        return { kind: 'first', lastSeq: seq, unseenBefore: seq - 1 };
     if (seq <= lastSeq)
         return { kind: 'behind', lastSeq };
     if (seq === lastSeq + 1)

package/dist-cjs/index.cjs

@@ -179,6 +179,7 @@ __export(index_exports, {
   observationAt: () => observationAt,
   offCalendarAt: () => offCalendarAt,
   offCalendarReasonAt: () => offCalendarReasonAt,
+  operationalIdentityField: () => operationalIdentityField,
   operationalKindOf: () => operationalKindOf,
   operationsCapabilityOf: () => operationsCapabilityOf,
   outsideLimit: () => outsideLimit,
@@ -3700,6 +3701,9 @@ function operationalKindOf(record) {
 var MATCH_ORDER = Object.keys(SPECS).sort(
   (a, b) => (SPECS[a].matchOrder ?? 1e3) - (SPECS[b].matchOrder ?? 1e3)
 );
+function operationalIdentityField(kind) {
+  return kind ? SPECS[kind]?.identity : void 0;
+}
 function isOperationalRecord(record) {
   return operationalKindOf(record) !== void 0;
 }
@@ -4016,7 +4020,7 @@ 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 (lastSeq === void 0 || lastSeq === null) return { kind: "first", lastSeq: seq, unseenBefore: seq - 1 };
   if (seq <= lastSeq) return { kind: "behind", lastSeq };
   if (seq === lastSeq + 1) return { kind: "next", lastSeq: seq };
   return { kind: "gap", lastSeq, expectedSeq: lastSeq + 1 };
@@ -4497,6 +4501,7 @@ function commandSpecGaps(specs, command) {
   observationAt,
   offCalendarAt,
   offCalendarReasonAt,
+  operationalIdentityField,
   operationalKindOf,
   operationsCapabilityOf,
   outsideLimit,

package/package.json

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