@operato/twin-kernel 0.7.33 → 0.7.37

package/dist/face2-adapter.d.ts

@@ -2,7 +2,7 @@ import type { CanonicalEnvelope } from './contract.ts';
 import type { EpcisEvent } from './epcis.ts';
 /** 매핑 값: 리터럴, 또는 소스 필드 참조("$.field.path"). */
 export type MapValue = string;
-/** ObjectEvent 매핑 스펙(선언적). Agg/Txn 매핑은 확장 지점. */
+/** ObjectEvent 매핑 스펙(선언적). */
 export interface ObjectEventMapping {
     type: 'ObjectEvent';
     action: MapValue;
@@ -12,7 +12,41 @@ export interface ObjectEventMapping {
     readPoint?: MapValue;
     bizLocation?: MapValue;
 }
-export type EventMapping = ObjectEventMapping;
+/**
+ * AggregationEvent 매핑 스펙 — **담김의 사실**(무엇이 무엇에 실렸나).
+ *
+ * ── 왜 뒤늦게 생겼나 (2026-08-19) ───────────────────────────────────────────
+ * 이 파일은 오래 *"Agg/Txn 매핑은 확장 지점"* 이라고만 적어 두었고, 그래서 원본이 **적재를 말할 길이
+ * 없었다.** 관측 리듀서는 `AggregationEvent` 를 받으면 자식 물품에 `parent` 를 붙이도록 이미 되어 있었는데
+ * (3D 가 「이 상자가 어느 팔레트에 실렸나」를 묻는 자리) 그 사실이 문 앞에서 사라졌다 — 시뮬 원본을
+ * 붙여 돌려 보고서야 그것이 로그로 드러났다(*"is not carried to the twin"*).
+ *
+ * 자식은 **두 가지로 말할 수 있다**(표준이 그렇고 우리 커널도 둘 다 낸다):
+ *  · `childEPCs` — 개체 하나하나(상자 3개의 식별자).
+ *  · `childQuantityList` — 클래스와 수량(「이 품번 40개」). 낱개 식별자가 없는 입고·포장이 이 모양이다.
+ * 하나만 받으면 나머지 사실이 문 앞에서 사라진다 — 실제로 그렇게 사라지고 있었다(로그가 짚었다).
+ */
+export interface AggregationEventMapping {
+    type: 'AggregationEvent';
+    action: MapValue;
+    bizStep: MapValue;
+    disposition?: MapValue;
+    parentID: MapValue;
+    /** 자식 목록 참조("$.childEPCs") — 문자열 배열이어야 한다. */
+    childEPCs?: MapValue;
+    /** 수량으로 담긴 자식 참조("$.childQuantityList") — `{ epcClass, quantity, uom? }` 배열. */
+    childQuantityList?: MapValue;
+    readPoint?: MapValue;
+    bizLocation?: MapValue;
+}
+export type EventMapping = ObjectEventMapping | AggregationEventMapping;
+/**
+ * 이 품목 레코드가 **담김의 사실**인가 — 라우팅 판정을 한 곳에 둔다(소비처가 각자 짐작하지 않게).
+ *
+ * 담김은 부모와 자식으로 말한다(`parentID`·`childEPCs`). 개체 하나의 관측(`epc`)과 섞이지 않게, 부모가
+ * 있으면 담김으로 본다 — 둘 다 있으면 커넥터가 무엇을 말하려는지 알 수 없으므로 담김으로 받지 않는다.
+ */
+export declare function isAggregationRecord(record: unknown): boolean;
 /** 룰: 소스 레코드의 판별자(sourceType)로 매핑을 고른다. */
 export interface AdapterRule {
     sourceType: string;
@@ -32,7 +66,12 @@ export interface IngestResult {
     }[];
 }
 type Rec = Record<string, unknown>;
-/** 단일 레코드 → 정규 EPCIS 이벤트(매핑만; 검증은 ingest 에서). */
+/** 단일 레코드 → 정규 EPCIS 이벤트 + 매핑에서 드러난 문제(검증은 `ingest` 가 이어서 한다). */
+export declare function mapRecordChecked(record: Rec, mapping: EventMapping, eventTime: string): {
+    event: EpcisEvent;
+    errors: string[];
+};
+/** 단일 레코드 → 정규 EPCIS 이벤트(매핑만). 매핑 문제까지 보려면 `mapRecordChecked`. */
 export declare function mapRecord(record: Rec, mapping: EventMapping, eventTime: string): EpcisEvent;
 /**
  * 레거시 레코드 배열 → 정규 EPCIS 봉투. 매핑 후 검증, 실패분은 rejected(오염 차단).

package/dist/face2-adapter.js

@@ -8,32 +8,110 @@
  * 매핑 엔진은 walking-skeleton 범위에서 무의존 declarative spec 사용.
  * (jsonata/템플릿 엔진 최종 선택은 열린 결정 — face2-adapters.md. 커널 zero-dep 유지 위해 여기선 미도입.)
  */
-import { objectEvent, validateEpcisEvent } from "./epcis.js";
+import { aggregationEvent, objectEvent, validateEpcisEvent } from "./epcis.js";
+/**
+ * 이 품목 레코드가 **담김의 사실**인가 — 라우팅 판정을 한 곳에 둔다(소비처가 각자 짐작하지 않게).
+ *
+ * 담김은 부모와 자식으로 말한다(`parentID`·`childEPCs`). 개체 하나의 관측(`epc`)과 섞이지 않게, 부모가
+ * 있으면 담김으로 본다 — 둘 다 있으면 커넥터가 무엇을 말하려는지 알 수 없으므로 담김으로 받지 않는다.
+ */
+export function isAggregationRecord(record) {
+    if (!record || typeof record !== 'object')
+        return false;
+    const r = record;
+    return typeof r.parentID === 'string' && r.parentID.trim().length > 0 && r.epc === undefined;
+}
 function get(obj, path) {
     return path.split('.').reduce((o, k) => (o == null ? o : o[k]), obj);
 }
-/** 매핑 값 해석: "$.path" 는 소스 참조, 그 외는 리터럴. */
-function resolve(v, record) {
+/**
+ * 매핑 값 해석: "$.path" 는 소스 참조, 그 외는 리터럴.
+ *
+ * ── 객체를 문자열로 굳히지 않는다 (2026-08-19 실측으로 고침) ────────────────
+ * 예전에는 무엇이 오든 `String(값)` 이었다. 그래서 커널이 낸 EPCIS 의 `readPoint`(= `{ id }`)를 이 문에
+ * 그대로 실은 커넥터가 있었고, **오류 하나 없이** `readPoint: { id: "[object Object]" }` 가 저널에 쌓였다
+ * (실 앱에서 관측). 자리를 잃은 관측은 「어디 있나」에 답하지 못하는데 화면은 값이 있다고 믿는다.
+ *
+ * 그러니 객체·배열은 **매핑 오류**다. 조용히 버리지도(그러면 자리가 없어진 이유를 아무도 모른다),
+ * 문자열로 굳히지도 않고, 그 레코드를 이유와 함께 거부한다.
+ */
+function resolve(v, record, field, errors) {
     if (v === undefined)
         return undefined;
-    if (v.startsWith('$.')) {
-        const r = get(record, v.slice(2));
-        return r === undefined || r === null ? undefined : String(r);
+    if (!v.startsWith('$.'))
+        return v;
+    const r = get(record, v.slice(2));
+    if (r === undefined || r === null)
+        return undefined;
+    if (typeof r === 'object') {
+        errors.push(`${field} 가 값이 아니라 ${Array.isArray(r) ? '배열' : '객체'}로 왔다(${v}) — 커넥터가 표준 구조를 그대로 실었다: ${JSON.stringify(r).slice(0, 80)}`);
+        return undefined;
+    }
+    return String(r);
+}
+/** 목록 참조 해석 — 문자열 배열만 받는다(하나만 온 것을 배열로 지어내지 않는다). */
+function resolveList(v, record, field, errors) {
+    if (v === undefined)
+        return [];
+    const r = get(record, v.startsWith('$.') ? v.slice(2) : v);
+    if (r === undefined || r === null)
+        return [];
+    if (!Array.isArray(r) || r.some(x => typeof x !== 'string')) {
+        errors.push(`${field} 가 문자열 배열이 아니다(${v}): ${JSON.stringify(r).slice(0, 80)}`);
+        return [];
+    }
+    return r.slice();
+}
+/**
+ * 수량 목록 참조 해석 — `{ epcClass, quantity, uom? }` 배열.
+ *
+ * 값의 옳고 그름(클래스 식별자인가·수량이 양수인가)은 **검증이 본다**(`validateEpcisEvent`) — 여기서
+ * 다시 판정하면 규칙이 두 벌이 된다. 이 자리는 「배열인가·객체인가」만 지킨다.
+ */
+function resolveQuantityList(v, record, field, errors) {
+    if (v === undefined)
+        return [];
+    const r = get(record, v.startsWith('$.') ? v.slice(2) : v);
+    if (r === undefined || r === null)
+        return [];
+    if (!Array.isArray(r) || r.some(x => !x || typeof x !== 'object' || Array.isArray(x))) {
+        errors.push(`${field} 가 객체 배열이 아니다(${v}): ${JSON.stringify(r).slice(0, 80)}`);
+        return [];
+    }
+    return r.map(x => ({ ...x }));
+}
+/** 단일 레코드 → 정규 EPCIS 이벤트 + 매핑에서 드러난 문제(검증은 `ingest` 가 이어서 한다). */
+export function mapRecordChecked(record, mapping, eventTime) {
+    const errors = [];
+    const action = (resolve(mapping.action, record, 'action', errors) ?? '');
+    const bizStep = resolve(mapping.bizStep, record, 'bizStep', errors) ?? '';
+    const disposition = resolve(mapping.disposition, record, 'disposition', errors);
+    const readPoint = resolve(mapping.readPoint, record, 'readPoint', errors);
+    const bizLocation = resolve(mapping.bizLocation, record, 'bizLocation', errors);
+    if (mapping.type === 'AggregationEvent') {
+        const parentID = resolve(mapping.parentID, record, 'parentID', errors) ?? '';
+        const childEPCs = resolveList(mapping.childEPCs, record, 'childEPCs', errors);
+        const childQuantityList = resolveQuantityList(mapping.childQuantityList, record, 'childQuantityList', errors);
+        return {
+            event: aggregationEvent({
+                eventTime, action, bizStep, disposition, parentID,
+                /* 없는 쪽은 **필드를 만들지 않는다** — 빈 배열을 실으면 「자식이 없다」고 말하는 것이 된다. */
+                ...(childEPCs.length ? { childEPCs } : {}),
+                ...(childQuantityList.length ? { childQuantityList } : {}),
+                readPoint, bizLocation
+            }),
+            errors
+        };
     }
-    return v;
+    const epc = resolve(mapping.epc, record, 'epc', errors);
+    return {
+        event: objectEvent({ eventTime, action, bizStep, disposition, epcList: epc ? [epc] : [], readPoint, bizLocation }),
+        errors
+    };
 }
-/** 단일 레코드 → 정규 EPCIS 이벤트(매핑만; 검증은 ingest 에서). */
+/** 단일 레코드 → 정규 EPCIS 이벤트(매핑만). 매핑 문제까지 보려면 `mapRecordChecked`. */
 export function mapRecord(record, mapping, eventTime) {
-    const epc = resolve(mapping.epc, record);
-    return objectEvent({
-        eventTime,
-        action: (resolve(mapping.action, record) ?? ''),
-        bizStep: resolve(mapping.bizStep, record) ?? '',
-        disposition: resolve(mapping.disposition, record),
-        epcList: epc ? [epc] : [],
-        readPoint: resolve(mapping.readPoint, record),
-        bizLocation: resolve(mapping.bizLocation, record)
-    });
+    return mapRecordChecked(record, mapping, eventTime).event;
 }
 /**
  * 레거시 레코드 배열 → 정규 EPCIS 봉투. 매핑 후 검증, 실패분은 rejected(오염 차단).
@@ -50,9 +128,11 @@ export function ingest(records, rules, opts) {
             rejected.push({ record, errors: [`매칭 룰 없음: sourceType=${record['sourceType']}`] });
             continue;
         }
-        const eventTime = (opts.eventTimePath ? resolve('$.' + opts.eventTimePath, record) : undefined) ?? opts.defaultEventTime;
-        const ev = mapRecord(record, rule.mapping, eventTime);
-        const errors = validateEpcisEvent(ev);
+        const timeErrors = [];
+        const eventTime = (opts.eventTimePath ? resolve('$.' + opts.eventTimePath, record, 'eventTime', timeErrors) : undefined) ?? opts.defaultEventTime;
+        const { event: ev, errors: mapErrors } = mapRecordChecked(record, rule.mapping, eventTime);
+        /* 매핑에서 드러난 문제를 검증 위반과 **같은 자리**에 담는다 — 부르는 쪽은 이유를 한 곳에서 읽는다. */
+        const errors = [...timeErrors, ...mapErrors, ...validateEpcisEvent(ev)];
         if (errors.length) {
             rejected.push({ record, errors });
             continue;

package/dist-cjs/index.cjs

@@ -118,6 +118,7 @@ __export(index_exports, {
   ingestEnergyEquipmentRecords: () => ingestEnergyEquipmentRecords,
   ingestEnergyRecords: () => ingestEnergyRecords,
   ingestOperationalRecords: () => ingestOperationalRecords,
+  isAggregationRecord: () => isAggregationRecord,
   isElectricalLocationType: () => isElectricalLocationType,
   isEnergyEquipmentRecord: () => isEnergyEquipmentRecord,
   isEnergyRecord: () => isEnergyRecord,
@@ -129,6 +130,7 @@ __export(index_exports, {
   lgtinClass: () => lgtinClass,
   locationStatusOf: () => locationStatusOf,
   mapRecord: () => mapRecord,
+  mapRecordChecked: () => mapRecordChecked,
   meetsTests: () => meetsTests,
   minuteOfDayAt: () => minuteOfDayAt,
   monteCarloForecast: () => monteCarloForecast,
@@ -2684,28 +2686,80 @@ function foldJobResponses(rows) {
 }
 
 // src/face2-adapter.ts
+function isAggregationRecord(record) {
+  if (!record || typeof record !== "object") return false;
+  const r = record;
+  return typeof r.parentID === "string" && r.parentID.trim().length > 0 && r.epc === void 0;
+}
 function get(obj, path) {
   return path.split(".").reduce((o, k) => o == null ? o : o[k], obj);
 }
-function resolve(v, record) {
+function resolve(v, record, field, errors) {
   if (v === void 0) return void 0;
-  if (v.startsWith("$.")) {
-    const r = get(record, v.slice(2));
-    return r === void 0 || r === null ? void 0 : String(r);
+  if (!v.startsWith("$.")) return v;
+  const r = get(record, v.slice(2));
+  if (r === void 0 || r === null) return void 0;
+  if (typeof r === "object") {
+    errors.push(`${field} \uAC00 \uAC12\uC774 \uC544\uB2C8\uB77C ${Array.isArray(r) ? "\uBC30\uC5F4" : "\uAC1D\uCCB4"}\uB85C \uC654\uB2E4(${v}) \u2014 \uCEE4\uB125\uD130\uAC00 \uD45C\uC900 \uAD6C\uC870\uB97C \uADF8\uB300\uB85C \uC2E4\uC5C8\uB2E4: ${JSON.stringify(r).slice(0, 80)}`);
+    return void 0;
   }
-  return v;
+  return String(r);
+}
+function resolveList(v, record, field, errors) {
+  if (v === void 0) return [];
+  const r = get(record, v.startsWith("$.") ? v.slice(2) : v);
+  if (r === void 0 || r === null) return [];
+  if (!Array.isArray(r) || r.some((x) => typeof x !== "string")) {
+    errors.push(`${field} \uAC00 \uBB38\uC790\uC5F4 \uBC30\uC5F4\uC774 \uC544\uB2C8\uB2E4(${v}): ${JSON.stringify(r).slice(0, 80)}`);
+    return [];
+  }
+  return r.slice();
+}
+function resolveQuantityList(v, record, field, errors) {
+  if (v === void 0) return [];
+  const r = get(record, v.startsWith("$.") ? v.slice(2) : v);
+  if (r === void 0 || r === null) return [];
+  if (!Array.isArray(r) || r.some((x) => !x || typeof x !== "object" || Array.isArray(x))) {
+    errors.push(`${field} \uAC00 \uAC1D\uCCB4 \uBC30\uC5F4\uC774 \uC544\uB2C8\uB2E4(${v}): ${JSON.stringify(r).slice(0, 80)}`);
+    return [];
+  }
+  return r.map((x) => ({ ...x }));
+}
+function mapRecordChecked(record, mapping, eventTime) {
+  const errors = [];
+  const action = resolve(mapping.action, record, "action", errors) ?? "";
+  const bizStep = resolve(mapping.bizStep, record, "bizStep", errors) ?? "";
+  const disposition = resolve(mapping.disposition, record, "disposition", errors);
+  const readPoint = resolve(mapping.readPoint, record, "readPoint", errors);
+  const bizLocation = resolve(mapping.bizLocation, record, "bizLocation", errors);
+  if (mapping.type === "AggregationEvent") {
+    const parentID = resolve(mapping.parentID, record, "parentID", errors) ?? "";
+    const childEPCs = resolveList(mapping.childEPCs, record, "childEPCs", errors);
+    const childQuantityList = resolveQuantityList(mapping.childQuantityList, record, "childQuantityList", errors);
+    return {
+      event: aggregationEvent({
+        eventTime,
+        action,
+        bizStep,
+        disposition,
+        parentID,
+        /* 없는 쪽은 **필드를 만들지 않는다** — 빈 배열을 실으면 「자식이 없다」고 말하는 것이 된다. */
+        ...childEPCs.length ? { childEPCs } : {},
+        ...childQuantityList.length ? { childQuantityList } : {},
+        readPoint,
+        bizLocation
+      }),
+      errors
+    };
+  }
+  const epc = resolve(mapping.epc, record, "epc", errors);
+  return {
+    event: objectEvent({ eventTime, action, bizStep, disposition, epcList: epc ? [epc] : [], readPoint, bizLocation }),
+    errors
+  };
 }
 function mapRecord(record, mapping, eventTime) {
-  const epc = resolve(mapping.epc, record);
-  return objectEvent({
-    eventTime,
-    action: resolve(mapping.action, record) ?? "",
-    bizStep: resolve(mapping.bizStep, record) ?? "",
-    disposition: resolve(mapping.disposition, record),
-    epcList: epc ? [epc] : [],
-    readPoint: resolve(mapping.readPoint, record),
-    bizLocation: resolve(mapping.bizLocation, record)
-  });
+  return mapRecordChecked(record, mapping, eventTime).event;
 }
 function ingest(records, rules, opts) {
   const ruleByType = new Map(rules.map((r) => [r.sourceType, r]));
@@ -2718,9 +2772,10 @@ function ingest(records, rules, opts) {
       rejected.push({ record, errors: [`\uB9E4\uCE6D \uB8F0 \uC5C6\uC74C: sourceType=${record["sourceType"]}`] });
       continue;
     }
-    const eventTime = (opts.eventTimePath ? resolve("$." + opts.eventTimePath, record) : void 0) ?? opts.defaultEventTime;
-    const ev = mapRecord(record, rule.mapping, eventTime);
-    const errors = validateEpcisEvent(ev);
+    const timeErrors = [];
+    const eventTime = (opts.eventTimePath ? resolve("$." + opts.eventTimePath, record, "eventTime", timeErrors) : void 0) ?? opts.defaultEventTime;
+    const { event: ev, errors: mapErrors } = mapRecordChecked(record, rule.mapping, eventTime);
+    const errors = [...timeErrors, ...mapErrors, ...validateEpcisEvent(ev)];
     if (errors.length) {
       rejected.push({ record, errors });
       continue;
@@ -7762,6 +7817,7 @@ function retiredVocabularyIn(line) {
   ingestEnergyEquipmentRecords,
   ingestEnergyRecords,
   ingestOperationalRecords,
+  isAggregationRecord,
   isElectricalLocationType,
   isEnergyEquipmentRecord,
   isEnergyRecord,
@@ -7773,6 +7829,7 @@ function retiredVocabularyIn(line) {
   lgtinClass,
   locationStatusOf,
   mapRecord,
+  mapRecordChecked,
   meetsTests,
   minuteOfDayAt,
   monteCarloForecast,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operato/twin-kernel",
-  "version": "0.7.33",
+  "version": "0.7.37",
   "type": "module",
   "description": "Twin Domain Kernel — framework-agnostic, zero-dep (domain + sim + 3-channel contract). WMS/YMS/MES, EPCIS 2.0 · ISA-95.",
   "publishConfig": {