@operato/ops-contract 0.1.0

package/dist/epcis.js

@@ -0,0 +1,640 @@
+/*
+ * EPCIS — GS1 EPCIS 2.0 이벤트 machinery (도메인-중립). WMS/YMS/MES 모두 이 표준 위에서 방출한다.
+ * 타입 + 빌더(Object/Aggregation/Transaction/Transformation) + 무의존 구조 검증기 + GS1 URI + CBV disposition.
+ * 도메인별 어휘(bizStep/btt)는 각 프로파일(wms/yms/mes-profile)에 둔다.
+ *
+ * EPCIS 2.0 JSON 바인딩: 각 이벤트는 @context/type/eventTime/eventTimeZoneOffset 를 포함하는
+ * 자기기술적(self-describing) JSON-LD 오브젝트.
+ */
+/** EPCIS 2.0 JSON-LD 컨텍스트 — 이벤트를 자기기술적 EPCIS 오브젝트로 만든다. */
+export const EPCIS_CONTEXT = 'https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld';
+/** 커널 시계는 UTC(BASE_EPOCH) 기준 → 고정 오프셋. */
+export const UTC_OFFSET = '+00:00';
+// disposition — CBV URN (GS1 표준 상태 어휘, 전 도메인 공용).
+export const DISP = {
+    in_progress: 'urn:epcglobal:cbv:disp:in_progress',
+    sellable: 'urn:epcglobal:cbv:disp:sellable_accessible',
+    reserved: 'urn:epcglobal:cbv:disp:reserved',
+    in_transit: 'urn:epcglobal:cbv:disp:in_transit',
+    non_sellable: 'urn:epcglobal:cbv:disp:non_sellable_other', // 불량/scrap
+    /**
+     * **기한이 지났다** — CBV `expired`.
+     *
+     * ── 왜 `non_sellable` 로 계산하지 않나 (2026-08-24) ─────────────────────────────
+     * 커널의 `non_sellable` 은 CBV 의 `non_sellable_other`, 즉 **「그 밖의 이유」**다. 기한 지남을 거기
+     * 넣으면 「기한이 지나 못 판다」와 「깨져서 못 판다」가 같은 값이 되고, 화면은 회수·폐기의 사유를
+     * 구별할 수 없다. 식품에서 그 둘은 다른 조치다.
+     *
+     * 그리고 표준에 **정확한 낱말이 있다** — 합치는 것은 있는 낱말을 버리는 것이다.
+     *
+     * ── 기한 날짜와 다른 축이다 ────────────────────────────────────────────────
+     * `ItemState.expiry` 는 **날짜**이고 이것은 **상태**다. 날짜가 있으면 「지났나」는 파생이지만, 원본이
+     * 「기한 지남」을 상태로 선언하는 시스템이 있다 — 그때 이 값은 관측이다.
+     *
+     * 둘이 어긋나면(날짜는 남았는데 상태가 지남, 또는 그 반대) **어느 쪽이 맞다고 정하지 않는다** —
+     * 아직 그 판정을 세울 근거가 없다. 어긋남의 구분을 없애지 않는 것이 지금의 규율이다.
+     *
+     * ── 원문으로 확인했다 (2026-08-24) ────────────────────────────────────────
+     * 1차 출처: **CBV Standard Release 2.0, Ratified Jun 2022** §7.2.3 처분 값 표(38개). 이 객체의
+     * 다른 값들(`in_progress`·`sellable_accessible`·`reserved`·`in_transit`·`non_sellable_other`)도
+     * 그 표에 있다.
+     *
+     * **`non_sellable_expired` 를 쓰지 않는 이유**: 그 값은 CBV 1.0 의 것이고 표준이 **폐기**했다 —
+     * 「deprecated in favour of new disposition values expired, damaged, disposed, … introduced in
+     * CBV 1.1」. 폐기된 값을 쓰면 새 소비처가 읽지 못한다.
+     *
+     * 참고: GS1 어휘 등록처(`ref.gs1.org/cbv/…`)로는 확인할 수 없었다 — **없는 값에도 같은 응답**을
+     * 준다(지어낸 값의 JSON-LD 가 실재 값과 바이트까지 같았다). 그 경로를 근거로 삼지 말 것.
+     */
+    expired: 'urn:epcglobal:cbv:disp:expired',
+    /**
+     * **검사에 합격했다 / 불합격했다** — CBV `conformant` / `non_conformant`.
+     *
+     * 1차 출처(CBV 2.0 §7.2.3) 정의 그대로다.
+     *
+     *   conformant       Outcome of a successful/passed inspection in an inspecting or repairing step
+     *   non_conformant   Outcome of an unsuccessful/failed inspection in an inspecting or repairing step
+     *
+     * ── 왜 시험 결과 축을 자원에 더하지 않고 이것을 쓰나 (2026-08-24) ────────────
+     * 로트의 검사 판정을 담을 자리를 찾다가 `ItemState.testResults` 를 더하려 했다. 그런데 표준은 그
+     * 사실을 **이미 처분으로 말한다**: `bizStep: inspecting` 사건에 이 처분이 붙는다.
+     *
+     * 처분을 쓰면 두 가지가 공짜로 성립한다.
+     *   ① **상태 ⊆ 이벤트** — 처분은 이미 사건에서 온다. 상태에만 있는 축을 만들지 않는다
+     *   ② **운영에 곧 닿는다** — 「이 자재를 쓸 수 있나」가 처분으로 답해진다(판정을 따로 읽지 않는다)
+     *
+     * 시험의 **자세한 내용**(어느 명세로, 무엇을 재어)은 다른 물음이고, 표준은 그것을 `TestResult` 로
+     * 두며 결과가 대상을 가리킨다(`TestableObjectID`) — 대상이 결과를 들지 않는다. 그 축이 필요해지면
+     * 그때 열되, **판정 자체는 여기서 끝난다.**
+     */
+    conformant: 'urn:epcglobal:cbv:disp:conformant',
+    non_conformant: 'urn:epcglobal:cbv:disp:non_conformant'
+};
+/**
+ * **자재 소비·산출의 CBV 단계** — 도메인 무관하게 코어가 쓴다.
+ *
+ * 업종별 단계(입고·피킹·출하…)는 각 프로파일이 갖지만, "자재가 들어갔다/나왔다" 는 셋 다 하는 일이라
+ * 코어에 있어야 한다. 프로파일 하나에 두면 다른 업종이 그것을 가져다 쓰면서 방언이 생긴다.
+ */
+export const CBV_BIZSTEP = {
+    /** 공정에 자재가 들어갔다 — ISA-95 `MaterialUse: Consumed`. */
+    consuming: 'urn:epcglobal:cbv:bizstep:consuming',
+    /** 새 물품이 생겨 계보가 시작된다 — ISA-95 `MaterialUse: Produced`. */
+    commissioning: 'urn:epcglobal:cbv:bizstep:commissioning',
+    /**
+     * **검사** — CBV `inspecting`. 1차 출처(CBV 2.0) 정의: 「Process of reviewing objects to address
+     * potential physical or documentation defects」이고, 「표본과 달리 검사된 대상은 그대로 남는다」고
+     * 이어진다(즉 검사는 물건을 소비하지 않는다).
+     *
+     * 이 단계에 `DISP.conformant`/`DISP.non_conformant` 가 붙어 판정이 처분으로 남는다 — 입고검수·
+     * 공정 중 검사가 그 모양이다.
+     */
+    inspecting: 'urn:epcglobal:cbv:bizstep:inspecting',
+    /**
+     * **어느 단계로도 이름 붙지 않는 활동** — 원문: 「A business step not identified by any other」.
+     *
+     * 이것은 근사가 아니라 **표준이 준 낱말**이다. 그 구별이 중요하다: 재고 조정처럼 한 낱말이 두 일을
+     * 하는 원천(세어 보고 맞춘 것 · 사람이 정정한 것)을 `cycle_counting` 으로 옮기면 **일어나지 않은
+     * 계수를 기록**하게 된다. 그때 쓰는 것이 이 값이고, 무슨 일이었는지는 값으로 함께 나른다.
+     *
+     * 원문 확인: CBV Standard Release 2.0(Ratified Jun 2022) §7.1.
+     */
+    other: 'urn:epcglobal:cbv:bizstep:other'
+};
+/**
+ * **봉투에 실리는 EPCIS 사건 종류의 이름** — 소비처가 손으로 적지 않게 (2026-08-28).
+ *
+ * 봉투의 `eventType` 은 `epcis.<클래스>` 다(§`face2-adapter`·§`flow-engine` 이 그 접두사를 붙인다).
+ * 그 문자열을 화면·조회가 손으로 적으면 곧 방언이 되고, 클래스가 늘 때 한쪽만 고쳐진다.
+ *
+ * ── 왜 필요한가 ─────────────────────────────────────────────────────────────
+ * 「물건이 움직인 사건만 보는 목록」이 지금 **제외 목록**으로 만들어져 있다 — 운영·에너지 종류 열아홉
+ * 개를 적어 빼는 방식이다. 그 방식은 두 가지로 약하다.
+ *
+ *  ① **닫히지 않는다.** 커널이 세 번째 계열을 만들면 그 계열 전부가 오류 없이 「움직임」으로 들어온다.
+ *     실제로 그 일이 세 번 있었다(사람 상태·자산 상태·에너지).
+ *  ② **색인을 못 쓴다.** 제외 + 시각순은 색인이 듣지 않아, 그 트윈의 종류 분포가 비용을 정한다
+ *     (실측: 에너지가 0.008%인 트윈에서 같은 모양이 37초였다).
+ *
+ * 담을 것을 말하면 정의가 닫힌다 — **물건이 움직인 사건 = EPCIS 사건**이고 그 클래스는 표준이 정한다.
+ * 커널이 채널을 늘려도 이 집합은 늘지 않는다.
+ *
+ * 우리 커널이 다루는 클래스는 넷이다. 표준의 `AssociationEvent` 는 아직 만들지 않았고, 만들면 이 상수에
+ * 더한다 — 그 한 곳만 고치면 소비처가 함께 따라온다.
+ */
+export const EPCIS_EVENT = {
+    object: 'epcis.ObjectEvent',
+    aggregation: 'epcis.AggregationEvent',
+    transaction: 'epcis.TransactionEvent',
+    transformation: 'epcis.TransformationEvent'
+};
+/** 봉투의 `eventType` 이 EPCIS 사건인가 — 접두사 하나로 판정한다(클래스가 늘어도 그대로 산다). */
+export function isEpcisEventType(eventType) {
+    return typeof eventType === 'string' && eventType.startsWith('epcis.');
+}
+// ── GS1 EPC URI 헬퍼 (표준) ────────────────────────────────────────────────
+/** SSCC (물류단위: 팔레트/화물/트레일러) — 결정적 카운터 기반. */
+export function ssccUri(companyPrefix, serial) {
+    return `urn:epc:id:sscc:${companyPrefix}.${String(serial).padStart(10, '0')}`;
+}
+/** 비직렬 수량용 SGTIN 패턴(epcClass) — 로트를 따지지 않는 품목 클래스. quantityList 에 사용. */
+export function sgtinClass(companyPrefix, itemRef) {
+    return `urn:epc:idpat:sgtin:${companyPrefix}.${itemRef}.*`;
+}
+/**
+ * 우리가 방출하는 개체·로트 마스터데이터의 속성 이름 — **한 곳에 모은다.**
+ *
+ * 표준은 이 이름들을 정의하지 않는다(§7.3.8: 상위 문서 소관). 그래서 값을 실으려면 이름을 정해야 하는데,
+ * 흩뿌리면 곧 방언이 된다. GS1 CBV 마스터데이터 이름공간(`urn:epcglobal:cbv:mda:`)의 정식 명칭을
+ * 확인하면 **이 상수만 바꾸면 되도록** 여기 모아 둔다.
+ *
+ * ⚠ 아래 이름은 **아직 정본 확인 전**이다(CBV 마스터데이터 문서 필요). 받는 경로는 이름과 무관하게
+ * 동작하므로(받은 것을 잃지 않고 통과) 이 상수는 우리가 **생산할 때**만 쓰인다.
+ */
+export const ILMD_ATTR = {
+    /** 유통기한·만료(로트 단위). */
+    expiry: 'cbvmda:itemExpirationDate',
+    /** 로트·배치 번호(직렬 개체에 로트를 붙일 때). */
+    lot: 'cbvmda:lotNumber'
+};
+/**
+ * 품번 + 로트 클래스(LGTIN) — 낱개 일련번호가 없고 **로트로 관리**하는 자재의 표준 식별자.
+ *
+ * 원자재·화학·식품이 이 경우다. 로트가 식별자의 한 마디로 들어가므로 "로트별 재고" 가 별도 필드 없이
+ * epcClass 별 집계가 된다. 개체가 아니라 클래스이므로 `epcList` 가 아니라 `quantityList` 에 쓴다.
+ *
+ * 문법(EPC Tag Data Standard 2.1.0 §6.4.1):
+ *   urn:epc:class:lgtin:CompanyPrefix.ItemRefAndIndicator.Lot
+ *   예) urn:epc:class:lgtin:4012345.012345.998877
+ * 두 숫자 마디의 자릿수 합은 13(점 제외), Lot 은 GS3A3Component(URI 이스케이프 허용).
+ */
+export function lgtinClass(companyPrefix, itemRefAndIndicator, lot) {
+    return `urn:epc:class:lgtin:${companyPrefix}.${itemRefAndIndicator}.${encodeURIComponent(lot)}`;
+}
+/**
+ * EPC/클래스 식별자 파서 — **표준 지식이라 커널이 소유한다.**
+ *
+ * 소비처가 `uri.split(':').pop()` 으로 자르면 규칙이 어긋난다(실제로 화면이 LGTIN 의 마지막 마디인
+ * 로트를 SKU 이름으로 표시할 위험이 있었다). 뜯는 일은 여기 한 곳에서 한다.
+ */
+export function parseEpc(uri) {
+    const raw = String(uri ?? '');
+    /*
+     * ── CBV 형식을 먼저 읽는다 (2026-08-21) ──────────────────────────────────
+     * GS1 프리픽스가 없는 현장은 선언된 이름공간 아래에서 식별자를 만든다(CBV 2.0 §8.2.3·§8.2.4 개체
+     * `obj` · §8.3.3·§8.3.4 클래스 `class`). 그 형식을 모르면 `scheme: 'unknown'` · `instance: false` 가
+     * 되고, 소비처가 **개체를 클래스로 읽는다** — 미러가 트레일러의 개체 URI 를 그 물품의 품번으로 적었다
+     * (적합성 대조가 「미러만 아는 것=[gtin]」으로 잡았다).
+     *
+     * 표지가 종류를 말한다. 그것이 이 형식의 설계이고(그래서 표지가 필수다) 여기서 그대로 읽는다.
+     */
+    if (/(?:\/obj\/|:obj:)[^/:\s]+$/.test(raw))
+        return { scheme: 'unknown', instance: true, uri: raw };
+    if (/(?:\/class\/|:class:)[^/:\s]+$/.test(raw))
+        return { scheme: 'unknown', instance: false, uri: raw };
+    const cls = raw.match(/^urn:epc:class:lgtin:(.+)$/);
+    if (cls) {
+        const seg = cls[1].split('.');
+        /* LGTIN 은 숫자 두 마디 + 로트. 로트에 점이 들어갈 수 있으므로 앞 둘만 떼고 나머지를 로트로. */
+        const lot = seg.slice(2).join('.');
+        return {
+            scheme: 'lgtin',
+            instance: false,
+            gtinKey: seg.slice(0, 2).join('.'),
+            lot: lot ? decodeURIComponent(lot) : undefined,
+            uri: raw
+        };
+    }
+    const pat = raw.match(/^urn:epc:idpat:sgtin:(.+)$/);
+    if (pat) {
+        const seg = pat[1].split('.');
+        return { scheme: 'idpat', instance: false, gtinKey: seg.slice(0, 2).join('.'), uri: raw };
+    }
+    const id = raw.match(/^urn:epc:id:([a-z]+):(.+)$/);
+    if (id) {
+        const scheme = id[1];
+        const seg = id[2].split('.');
+        const known = ['sgtin', 'sscc', 'gdti', 'grai', 'giai', 'sgln'].includes(scheme);
+        return {
+            scheme: known ? scheme : 'unknown',
+            instance: true,
+            ...(scheme === 'sgtin' ? { gtinKey: seg.slice(0, 2).join('.'), serial: seg[2] } : { serial: seg.slice(1).join('.') }),
+            uri: raw
+        };
+    }
+    return { scheme: 'unknown', instance: false, uri: raw };
+}
+/** 거래문서 식별자 = GDTI (PO/SO/WO/어포인트먼트 등). */
+export function gdtiUri(companyPrefix, docType, serial) {
+    return `urn:epc:id:gdti:${companyPrefix}.${docType}.${serial}`;
+}
+/**
+ * **선언된 이름공간 아래의 거래 문서 식별자** — GDTI 를 쓰지 않는 길.
+ *
+ * ── 왜 이 길이 필요한가 (2026-08-21) ───────────────────────────────────────
+ * GDTI 는 `회사 프리픽스 + 문서 타입 + 일련번호`이고 **문서 타입은 회사가 배정한다**(GS1 이 공표하는
+ * 목록이 아니다). 그런데 커널이 `'403'`(작업지시)·`'401'`·`'402'`·`'404'` 를 스스로 정하고 있었다.
+ *
+ * 표준은 거래 문서 식별자에 GDTI 만 요구하지 않는다. CBV 2.0 이 세 형태를 더 정한다:
+ *  · §8.5.5 `http(s)://[Subdomain.]Domain/⁎⁎/bt/transID` — 그 도메인 소유자가 배정
+ *  · §8.5.4 `urn:URNNamespace:⁎⁎:bt:transID` — URN 이름공간 소유자가 배정
+ *  · §8.5.3 `urn:epcglobal:cbv:bt:gln:transID` — GLN 소유자가 배정
+ *
+ * `bt` 표지가 **필수**이고, `transID` 는 경로 성분 **하나**다(「only one URI path component SHALL
+ * follow the /bt/」). 그래서 회사가 **도메인만 있으면** 문서 타입을 정할 일이 없다 — 이것이 GDTI 보다
+ * 진입장벽이 낮은 길이다.
+ *
+ * 이름공간의 모양으로 URL 형태와 URN 형태를 가른다. 판정할 수 없는 모양이면 **답하지 않는다**(지어내지
+ * 않는다) — 호출부가 다른 길을 고르게 한다.
+ */
+/**
+ * **선언된 이름공간 아래의 개체 식별자** — SSCC·GRAI 를 쓰지 않는 길.
+ *
+ * 팔레트(SSCC)·트레일러(GRAI)는 개체 식별자이고, 그 조립에는 GS1 회사 프리픽스가 필요하다. 프리픽스가
+ * 없는 현장은 그 길로 갈 수 없다 — 그런데 커널이 프리픽스를 지어내면 저널에 남의 번호가 영구히 남는다.
+ *
+ * 표준이 다른 길을 정해 두었다.
+ *  · CBV 2.0 §8.2.4 `http(s)://[Subdomain.]Domain/⁎⁎/obj/Objid` — 그 도메인 소유자가 배정
+ *  · CBV 2.0 §8.2.3 `urn:URNNamespace:⁎⁎:obj:Objid` — URN 이름공간 소유자가 배정
+ *
+ * `obj` 표지가 필수다(클래스의 `class`·거래문서의 `bt` 와 같은 구조다). 다만 표준은 EPC URI 나 Digital
+ * Link 를 **권한다**(SHOULD) — 이 길은 프리픽스가 없을 때의 정합 경로다.
+ */
+export function objectUri(namespace, objId) {
+    return underNamespace(namespace, 'obj', objId);
+}
+export function bizTransactionUri(namespace, transId) {
+    return underNamespace(namespace, 'bt', transId);
+}
+/**
+ * 선언된 이름공간 아래에 표지를 붙여 식별자를 만든다 — 표지만 다르고 규칙은 같다.
+ *
+ * `obj`(개체 §8.2.3·§8.2.4) · `class`(클래스 §8.3.3·§8.3.4) · `bt`(거래문서 §8.5.4·§8.5.5) 가 같은
+ * 모양이다. 규칙을 세 곳에 적으면 한 곳만 고쳐지는 날이 온다.
+ */
+function underNamespace(namespace, marker, id) {
+    const ns = namespace?.trim();
+    if (!ns)
+        return undefined;
+    const v = String(id);
+    /* 표준이 요구하는 「성분 하나」가 깨진다 — 구분자가 든 값은 만들지 않는다. */
+    if (!v || v.includes('/') || v.includes(':'))
+        return undefined;
+    if (/^https?:\/\/[^/\s]+/.test(ns))
+        return `${ns.replace(/\/+$/, '')}/${marker}/${v}`;
+    /*
+     * **GS1 이 소유한 URN 공간에는 우리가 표지를 만들 수 없다.** `urn:epc:`·`urn:epcglobal:` 의 소유
+     * 권한자는 GS1 이고(EPCIS §6.4), 그 안의 형태는 표준이 정해 둔 것만 유효하다. 그 공간을 이름공간으로
+     * 선언한 현장은 GS1 키(SSCC·GRAI·GDTI)를 쓰는 쪽으로 가야 한다.
+     */
+    if (/^urn:epc(global)?:/.test(ns))
+        return undefined;
+    if (/^urn:[^:\s]+/.test(ns))
+        return `${ns.replace(/:+$/, '')}:${marker}:${v}`;
+    return undefined;
+}
+function header(type, eventTime, bizStep, opts) {
+    const h = {
+        '@context': EPCIS_CONTEXT,
+        type,
+        eventTime,
+        eventTimeZoneOffset: UTC_OFFSET,
+        bizStep
+    };
+    /* 값이 없으면 키를 만들지 않는다 — 표준 이벤트에 빈 필드를 싣지 않기 위해. */
+    if (opts?.eventID)
+        h.eventID = opts.eventID;
+    if (opts?.recordTime)
+        h.recordTime = opts.recordTime;
+    if (opts?.errorDeclaration)
+        h.errorDeclaration = opts.errorDeclaration;
+    if (opts?.ilmd)
+        h.ilmd = opts.ilmd;
+    if (opts?.sourceList)
+        h.sourceList = opts.sourceList;
+    if (opts?.destinationList)
+        h.destinationList = opts.destinationList;
+    if (opts?.persistentDisposition)
+        h.persistentDisposition = opts.persistentDisposition;
+    if (opts?.sensorElementList)
+        h.sensorElementList = opts.sensorElementList;
+    if (opts?.certificationInfo)
+        h.certificationInfo = opts.certificationInfo;
+    return h;
+}
+function common(type, eventTime, action, bizStep, opts) {
+    return { ...header(type, eventTime, bizStep, opts), action };
+}
+export function objectEvent(p) {
+    const e = { ...common('ObjectEvent', p.eventTime, p.action, p.bizStep, p), epcList: p.epcList };
+    if (p.disposition)
+        e.disposition = p.disposition;
+    if (p.quantityList)
+        e.quantityList = p.quantityList;
+    if (p.readPoint)
+        e.readPoint = { id: p.readPoint };
+    if (p.bizLocation)
+        e.bizLocation = { id: p.bizLocation };
+    if (p.bizTransactionList)
+        e.bizTransactionList = p.bizTransactionList;
+    return e;
+}
+export function aggregationEvent(p) {
+    const e = { ...common('AggregationEvent', p.eventTime, p.action, p.bizStep, p), parentID: p.parentID };
+    if (p.disposition)
+        e.disposition = p.disposition;
+    if (p.childEPCs)
+        e.childEPCs = p.childEPCs;
+    if (p.childQuantityList)
+        e.childQuantityList = p.childQuantityList;
+    if (p.readPoint)
+        e.readPoint = { id: p.readPoint };
+    if (p.bizLocation)
+        e.bizLocation = { id: p.bizLocation };
+    return e;
+}
+export function transactionEvent(p) {
+    const e = {
+        ...common('TransactionEvent', p.eventTime, p.action, p.bizStep, p),
+        bizTransactionList: p.bizTransactionList
+    };
+    if (p.disposition)
+        e.disposition = p.disposition;
+    if (p.parentID)
+        e.parentID = p.parentID;
+    if (p.epcList)
+        e.epcList = p.epcList;
+    if (p.quantityList)
+        e.quantityList = p.quantityList;
+    if (p.readPoint)
+        e.readPoint = { id: p.readPoint };
+    if (p.bizLocation)
+        e.bizLocation = { id: p.bizLocation };
+    return e;
+}
+/** 변환(제조) — 입력 EPC/수량 소비 → 출력 EPC/수량 생산. action 없음. */
+export function transformationEvent(p) {
+    const e = header('TransformationEvent', p.eventTime, p.bizStep, p);
+    if (p.disposition)
+        e.disposition = p.disposition;
+    if (p.inputEPCList)
+        e.inputEPCList = p.inputEPCList;
+    if (p.inputQuantityList)
+        e.inputQuantityList = p.inputQuantityList;
+    if (p.outputEPCList)
+        e.outputEPCList = p.outputEPCList;
+    if (p.outputQuantityList)
+        e.outputQuantityList = p.outputQuantityList;
+    if (p.transformationID)
+        e.transformationID = p.transformationID;
+    if (p.readPoint)
+        e.readPoint = { id: p.readPoint };
+    if (p.bizLocation)
+        e.bizLocation = { id: p.bizLocation };
+    if (p.bizTransactionList)
+        e.bizTransactionList = p.bizTransactionList;
+    return e;
+}
+// ── 구조 검증기 (무의존 — 커널 zero-dep 원칙) ──────────────────────────────
+// EPCIS 2.0 이벤트의 필수 필드·형태를 검증. 위반 목록을 반환(빈 배열 = 유효).
+// JSON Schema 파일 파생은 후속 — 이 함수가 제약의 SoT.
+const ISO_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+const TZ_RE = /^[+-]\d{2}:\d{2}$/;
+const ACTIONS = ['ADD', 'OBSERVE', 'DELETE'];
+/*
+ * ★ 클래스 식별자 판정 — **표준이 요구하는 것은 GS1 발급이 아니라 「소유 권한」이다.**
+ *
+ * ── 무엇이 틀렸나 (2026-08-20) ──────────────────────────────────────────────
+ * 예전에는 `urn:epc:idpat:` · `urn:epc:class:` **둘만** 통과시켰다. 그래서 GS1 회사 프리픽스가 없는
+ * 현장은 **통과할 길이 없었고**, 통과시키려면 프리픽스를 지어내야 했다. 커널의 `0614141`(GS1 이 예제로
+ * 쓰다 버린 값, 실 배정 대역)이 그 압력의 산물이다. **막는 쪽이 위조의 원인이었다.**
+ *
+ * ── 원문 (Release 2.0, Ratified Jun 2022) ──────────────────────────────────
+ * EPCIS 2.0 §6.4: "The types of URIs admissible as Vocabulary Elements are those URIs **for which
+ * there is an owning authority.**" — EPC URI · 절대 URL(도메인 소유자) · PEN 기반 `oid` URN ·
+ * `epc`/`epcglobal` URN · GS1 Digital Link.
+ * EPCIS 2.0 §6.2: `epcClass`(Object Class) 는 **User Vocabulary** 다.
+ *
+ * CBV 2.0 이 클래스 식별자의 **모양**을 규정한다:
+ *  · §8.3.3 `urn:URNNamespace:**:class:ObjClassid` — URN 이름공간 소유자가 배정
+ *  · §8.3.4 `http(s)://[Subdomain.]Domain/⁎⁎/class/ObjClassid` — 그 인터넷 도메인 소유자가 배정
+ *    (`ObjClassid` 에 `/` 불가 — "only one URI path component SHALL follow the /class/")
+ *
+ * `class` 표지가 **필수**다. 그냥 절대 URL 이면 되는 것이 아니다 —
+ * `https://chef.example.com/product/<uuid>` 는 **부적합**이고 `.../class/<uuid>` 가 적합이다.
+ *
+ * ── 아직 판정하지 않는 것 (좁힘을 드러내 둔다) ──────────────────────────────
+ * **비정규형 GS1 Digital Link**(§8.3.2 의 `https://example.com/some/path/info/8003/…` 류)는 거절한다.
+ * 정규형(`https://id.gs1.org/…`)만 받는다. 판정에 GS1 Application Identifier 지식이 필요하고 지금
+ * 소비처가 없다. **표준보다 좁은 것을 알고 있다** — Digital Link 를 쓰는 원천이 붙는 날 이 절을 연다.
+ */
+const EPC_CLASS_PREFIXES = ['urn:epc:idpat:', 'urn:epc:class:'];
+/** CBV §8.3.2 정규형 Digital Link. 비정규형은 위 주석대로 아직 판정하지 않는다. */
+const DL_CANONICAL = 'https://id.gs1.org/';
+/** CBV §8.3.4 — 도메인 소유자가 배정. `ObjClassid` 는 경로 성분 **하나**(RFC3986 segment-nz). */
+const CBV_URL_CLASS = /^https?:\/\/[^/\s]+\/(?:[^/\s]+\/)*class\/[^/\s]+$/;
+/** CBV §8.3.3 — URN 이름공간 소유자가 배정. `ObjClassid` 에 콜론 불가. */
+const CBV_URN_CLASS = /^urn:[^:\s]+:(?:[^:\s]+:)*class:[^:\s]+$/;
+/** 위반 문구, 또는 통과면 `undefined`. */
+/**
+ * **GS1 키의 자리 수 규약** — TDS 가 정한 합계다(회사 프리픽스 + 참조 = 고정 자리).
+ *
+ * ── 왜 여기서 보는가 (2026-08-22) ──────────────────────────────────────────
+ * 검증기가 모양(`urn:epc:idpat:sgtin:`)만 보고 **자리 수를 보지 않았다.** 실측: 12자리·14자리 SGTIN 이
+ * 전부 통과했다. 프리픽스를 바꾸는 작업에서 품목참조 자리 수를 맞추지 않으면 **조용히 어긋난
+ * 식별자가 저널에 영구히 남고**, 어느 화면도 그것을 말해 주지 않는다.
+ *
+ * 합계만 본다 — 프리픽스가 몇 자리인지는 GS1 이 회사마다 다르게 배정하므로 우리가 알 수 없다.
+ * 합계는 키 종류가 정한다: SGTIN 13(GTIN-14 의 표시자+13자리) · SSCC 17 · GRAI 12 · GDTI 12.
+ */
+const GS1_KEY_DIGITS = { sgtin: 13, sscc: 17, grai: 12, gdti: 12 };
+/**
+ * 그 GS1 키의 자리 수가 맞나 — 어긋나면 왜인지 말한다.
+ *
+ * `urn:epc:{id,idpat,class}:<키>:<프리픽스>.<참조>[.<직렬>]` 모양만 본다. 그 밖의 형식(도메인 기반
+ * 식별자 등)은 이 규약의 대상이 아니므로 아무 말도 하지 않는다.
+ */
+export function gs1KeyDigitViolation(uri) {
+    if (!uri)
+        return undefined;
+    const m = /^urn:epc:(?:id|idpat|class):([a-z]+):([^:]+)$/.exec(uri);
+    if (!m)
+        return undefined;
+    const want = GS1_KEY_DIGITS[m[1]];
+    if (!want)
+        return undefined;
+    const parts = m[2].split('.');
+    if (parts.length < 2)
+        return `${m[1]} 형식 오류: ${uri} — 회사 프리픽스와 참조가 '.' 로 갈려야 한다`;
+    const [prefix, ref] = parts;
+    /* 패턴의 `*` 는 자리 수를 말하지 않는다 — 참조 자리가 `*` 면 합계를 셀 수 없으므로 넘어간다. */
+    if (ref === '*')
+        return undefined;
+    if (!/^\d+$/.test(prefix) || !/^\d+$/.test(ref)) {
+        return `${m[1]} 형식 오류: ${uri} — 회사 프리픽스와 참조는 숫자다`;
+    }
+    const got = prefix.length + ref.length;
+    if (got === want)
+        return undefined;
+    return (`${m[1]} 자리 수 오류: ${uri} — 회사 프리픽스(${prefix.length}) + 참조(${ref.length}) = ${got} 이지만 ` +
+        `${want} 여야 한다(GS1 TDS). 프리픽스를 바꾸면 참조 자리 수를 함께 맞춰야 한다.`);
+}
+export function classIdentifierViolation(epcClass) {
+    if (!epcClass)
+        return `quantity epcClass 부정: ${epcClass}`;
+    const digits = gs1KeyDigitViolation(epcClass);
+    if (digits)
+        return `quantity epcClass 부정: ${digits}`;
+    if (EPC_CLASS_PREFIXES.some(p => epcClass.startsWith(p)))
+        return undefined;
+    if (epcClass.startsWith(DL_CANONICAL))
+        return undefined;
+    if (CBV_URL_CLASS.test(epcClass) || CBV_URN_CLASS.test(epcClass))
+        return undefined;
+    return (`quantity epcClass 부정: ${epcClass} — 클래스 식별자는 소유 권한을 말할 수 있는 모양이어야 한다 ` +
+        `(EPC 클래스 urn:epc:idpat:/urn:epc:class: · CBV §8.3.4 http(s)://<도메인>/**/class/<id> · ` +
+        `CBV §8.3.3 urn:<이름공간>:**:class:<id>)`);
+}
+export function validateEpcisEvent(e) {
+    const v = [];
+    /*
+     * ── 개체 식별자의 자리 수도 본다 (2026-08-22) ──────────────────────────────
+     * 클래스만 보고 개체를 보지 않으면, 같은 어긋남이 `epcList` 를 타고 그대로 저널에 들어간다. 판정은
+     * 한 규칙이므로 실리는 모든 자리에 같이 댄다(§`gs1KeyDigitViolation`).
+     */
+    for (const [field, list] of [
+        ['epcList', e.epcList],
+        ['childEPCs', e.childEPCs],
+        ['inputEPCList', e.inputEPCList],
+        ['outputEPCList', e.outputEPCList],
+        ['parentID', e.parentID ? [e.parentID] : undefined]
+    ]) {
+        for (const epc of list ?? []) {
+            const bad = gs1KeyDigitViolation(epc);
+            if (bad)
+                v.push(`${field}: ${bad}`);
+        }
+    }
+    if (e['@context'] !== EPCIS_CONTEXT)
+        v.push('@context 누락/불일치');
+    if (!['ObjectEvent', 'AggregationEvent', 'TransactionEvent', 'TransformationEvent'].includes(e.type))
+        v.push(`알 수 없는 type: ${e.type}`);
+    if (typeof e.eventTime !== 'string' || !ISO_RE.test(e.eventTime))
+        v.push('eventTime ISO8601 아님');
+    if (typeof e.eventTimeZoneOffset !== 'string' || !TZ_RE.test(e.eventTimeZoneOffset))
+        v.push('eventTimeZoneOffset 형식 오류');
+    if (typeof e.bizStep !== 'string' || !e.bizStep)
+        v.push('bizStep 누락');
+    /* 선택 헤더 — 있으면 형식을 지킨다(없는 것은 위반이 아니다). */
+    if (e.eventID !== undefined && (typeof e.eventID !== 'string' || !e.eventID))
+        v.push('eventID 가 빈 문자열');
+    if (e.recordTime !== undefined && (typeof e.recordTime !== 'string' || !ISO_RE.test(e.recordTime))) {
+        v.push('recordTime ISO8601 아님');
+    }
+    /* 개체·로트 마스터데이터는 **생겨나는 순간에만** 실린다(§7.3.8) — ObjectEvent(ADD) · Transformation.
+     * 아무 이벤트에나 허용하면 "생애 동안 정적" 이라는 성질이 깨지고 이벤트마다 값이 어긋난다. */
+    if (e.ilmd !== undefined) {
+        const allowed = (e.type === 'ObjectEvent' && e.action === 'ADD') || e.type === 'TransformationEvent';
+        if (!allowed)
+            v.push('ilmd 는 ObjectEvent(action=ADD) 또는 TransformationEvent 에만 실을 수 있다');
+    }
+    /* 이전 당사자 — 종류와 당사자가 둘 다 있어야 뜻이 된다(한쪽만 있으면 누가/무엇이 빈다). */
+    for (const sd of e.sourceList ?? []) {
+        if (!sd?.type || !sd?.source)
+            v.push('sourceList 항목에 type 또는 source 누락');
+    }
+    for (const sd of e.destinationList ?? []) {
+        if (!sd?.type || !sd?.destination)
+            v.push('destinationList 항목에 type 또는 destination 누락');
+    }
+    /* 지속 상태 — 같은 조건을 동시에 설정하고 해제하면 뜻이 모순된다. */
+    if (e.persistentDisposition !== undefined) {
+        const set = e.persistentDisposition.set ?? [];
+        const unset = e.persistentDisposition.unset ?? [];
+        if (!set.length && !unset.length)
+            v.push('persistentDisposition 이 set·unset 둘 다 비어있음');
+        const both = set.filter(x => unset.includes(x));
+        if (both.length)
+            v.push(`persistentDisposition 이 같은 값을 set·unset 동시 지정: ${both.join(', ')}`);
+    }
+    /* 센서 — 관측 보고가 하나 이상 있어야 한다(표준: SHALL contain one or more sensorReport). */
+    for (const se of e.sensorElementList ?? []) {
+        if (!Array.isArray(se?.sensorReport) || se.sensorReport.length === 0) {
+            v.push('sensorElement 에 sensorReport 가 하나도 없음');
+        }
+    }
+    if (e.errorDeclaration !== undefined) {
+        const d = e.errorDeclaration;
+        /* 정정인데 언제 정정했는지 모르면 정정 순서를 판정할 수 없다 → 표준 필수. */
+        if (typeof d?.declarationTime !== 'string' || !ISO_RE.test(d.declarationTime)) {
+            v.push('errorDeclaration.declarationTime ISO8601 아님/누락');
+        }
+        if (d?.correctiveEventIDs !== undefined) {
+            if (!Array.isArray(d.correctiveEventIDs))
+                v.push('errorDeclaration.correctiveEventIDs 배열 아님');
+            else if (d.correctiveEventIDs.some(x => typeof x !== 'string' || !x)) {
+                v.push('errorDeclaration.correctiveEventIDs 에 빈 값');
+            }
+        }
+    }
+    if (e.type === 'ObjectEvent') {
+        if (!ACTIONS.includes(e.action))
+            v.push(`action 부정: ${e.action}`);
+        if (!Array.isArray(e.epcList))
+            v.push('ObjectEvent.epcList 누락');
+        else if (e.epcList.length === 0 && !e.quantityList?.length)
+            v.push('ObjectEvent: epcList/quantityList 둘 다 비어있음');
+    }
+    else if (e.type === 'AggregationEvent') {
+        if (!ACTIONS.includes(e.action))
+            v.push(`action 부정: ${e.action}`);
+        if (!e.parentID)
+            v.push('AggregationEvent.parentID 누락');
+        if (!e.childEPCs?.length && !e.childQuantityList?.length)
+            v.push('AggregationEvent: childEPCs/childQuantityList 둘 다 비어있음');
+    }
+    else if (e.type === 'TransactionEvent') {
+        if (!ACTIONS.includes(e.action))
+            v.push(`action 부정: ${e.action}`);
+        if (!Array.isArray(e.bizTransactionList) || e.bizTransactionList.length === 0)
+            v.push('TransactionEvent.bizTransactionList 누락');
+    }
+    else if (e.type === 'TransformationEvent') {
+        if (!e.inputEPCList?.length && !e.inputQuantityList?.length)
+            v.push('TransformationEvent: input 비어있음');
+        if (!e.outputEPCList?.length && !e.outputQuantityList?.length)
+            v.push('TransformationEvent: output 비어있음');
+    }
+    // 참조 무결성(경량): 모든 수량 리스트의 epcClass 는 idpat/class
+    const qtyLists = [
+        'quantityList' in e ? e.quantityList : undefined,
+        'childQuantityList' in e ? e.childQuantityList : undefined,
+        'inputQuantityList' in e ? e.inputQuantityList : undefined,
+        'outputQuantityList' in e ? e.outputQuantityList : undefined
+    ];
+    for (const list of qtyLists)
+        for (const q of list ?? []) {
+            /* 클래스 식별자만 — 개체(urn:epc:id:)는 epcList 의 몫이다. */
+            const bad = classIdentifierViolation(q.epcClass);
+            if (bad)
+                v.push(bad);
+            /* 세 경우(EPCIS 2.0 §7.3.3.1) — 느슨하게 통과시키면 "모름" 과 "0" 이 섞인다. */
+            const hasQty = q.quantity !== undefined && q.quantity !== null;
+            if (!hasQty) {
+                /* 수량 미지정 = "모른다". 그때 단위만 남아 있으면 뜻이 없다 → 표준은 생략을 요구한다. */
+                if (q.uom !== undefined)
+                    v.push('quantity 없으면 uom 도 없어야 한다(수량 미지정)');
+                continue;
+            }
+            if (typeof q.quantity !== 'number' || !Number.isFinite(q.quantity) || q.quantity <= 0) {
+                v.push('quantity 는 양수여야 한다(모르면 생략)');
+                continue;
+            }
+            /* uom 없으면 개수 → 정수여야 한다. uom 있으면 물리량 → 소수 허용. */
+            if (q.uom === undefined && !Number.isInteger(q.quantity))
+                v.push('uom 없는 quantity 는 정수(개수)여야 한다');
+            if (q.uom !== undefined && !/^[A-Z0-9]{2,3}$/.test(q.uom))
+                v.push(`uom 형식 부정(UN/CEFACT 권고 20 의 2~3자 코드): ${q.uom}`);
+        }
+    return v;
+}