@operato/twin-kernel 0.7.33 → 0.7.38

package/dist/contract.d.ts

@@ -1397,6 +1397,19 @@ export interface StateSnapshot {
     tasks: TaskState[];
     orders: OrderState[];
     attentions?: Attention[];
+    /**
+     * **담을 줄 몰라 반영하지 못한 사실** — 종류별 수(관측 구동에서만 나온다).
+     *
+     * 관측 리듀서는 오래전부터 이것을 세어 왔다. 그런데 **스냅샷이 그 값을 떨어뜨렸다** — 그래서
+     * 이미 그것을 읽도록 쓰여 있던 정합성 검사(`twin-unhandled-vocabulary`)는 미러에서 영원히
+     * 조용했다(2026-08-19 실측). 세기만 하고 아무도 못 보는 값은 없는 것과 같다.
+     */
+    unhandled?: {
+        eventType: string;
+        count: number;
+        firstAtMs?: number;
+        lastAtMs?: number;
+    }[];
     /**
      * 확인(ack)해 둔 주목 신호 id — **상태에서 파생되지 않는 유일한 축.**
      *

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/flow-engine.js

@@ -1086,6 +1086,11 @@ export class FlowEngine {
             /* 스냅샷이 **델타보다 가난하면 안 된다** — 예전에는 소요·남은 시간을 빼고 내보내서, 이 스냅샷으로
              * 다른 커널을 주입하면(hydrateObserved) 진행 중이던 작업을 이어 굴릴 수 없었다(미러 스냅샷은
              * 델타에서 왔으므로 갖고 있었다 — 같은 계약을 두 구동이 다르게 채우던 자리). */
+            /* 관측이 담지 못한 사실을 그대로 내보낸다 — 리듀서가 세고 있어도 여기서 떨어뜨리면 아무도 못 본다. */
+            ...(() => {
+                const u = this.observer?.snapshot?.().unhandled;
+                return u?.length ? { unhandled: u } : {};
+            })(),
             tasks: [...this.tasks.values()].map(t => ({
                 id: t.id, kind: t.kind, status: t.status, itemRefs: [t.itemEpc],
                 fromNode: t.fromNode, toNode: t.toNode, resourceRef: t.resource ?? undefined, orderId: t.orderId,

package/dist/observed-reducer.d.ts

@@ -106,6 +106,23 @@ export interface ReducerCheckpoint {
         child: string;
         parent: string;
     }[];
+    /** 수량으로 담긴 내용 — 채워 넣은 것과, 팔레트를 아직 못 본 채 보류한 것. */
+    qtyAggregation?: {
+        parent: string;
+        quantities: {
+            epcClass?: string;
+            quantity?: number;
+            uom?: string;
+        }[];
+    }[];
+    pendingQuantities?: {
+        parent: string;
+        quantities: {
+            epcClass?: string;
+            quantity?: number;
+            uom?: string;
+        }[];
+    }[];
     tasks: TaskState[];
     equipment: EquipmentState[];
     persons: PersonState[];
@@ -132,6 +149,15 @@ export declare class ObservedReducer {
     private aggregation;
     /** 아직 관측되지 않은 자식의 담김 — 물품을 지어내지 않고 보류했다가 등장할 때 붙인다. */
     private pendingParent;
+    /**
+     * 팔레트가 **담고 있는 것**(클래스 + 수량) — 바코드 없이 수량만 실린 담김.
+     *
+     *  · `qtyAggregation`    — 우리가 그 팔레트 물품에 채워 넣은 내용(풀릴 때 되돌릴 근거).
+     *  · `pendingQuantities` — 담김이 먼저 오고 그 팔레트를 아직 관측하지 못한 경우. 물품을 지어내지
+     *                          않고 보류해 두었다가, 관측되는 순간 붙인다(`pendingParent` 와 같은 규율).
+     */
+    private qtyAggregation;
+    private pendingQuantities;
     private tasks;
     private equipment;
     private persons;
@@ -217,8 +243,21 @@ export declare class ObservedReducer {
     private observedAtMs?;
     /** 이벤트 1건 반영 — eventType 으로 EPCIS vs 운영 델타 분기. */
     apply(e: CanonicalEnvelope): void;
-    /** 반영하지 못한 사건을 종류별로 센다 — 처음·마지막 시각을 함께 남겨 「언제부터」에 답한다. */
+    /**
+     * 반영하지 못한 사건을 종류별로 센다 — 처음·마지막 시각을 함께 남겨 「언제부터」에 답한다.
+     *
+     * `key` 를 주면 그 이름으로 센다: 종류 전체를 못 다룬 것과 **그 종류의 어떤 모양만** 못 다룬 것은
+     * 다른 사실이다(예: 담김은 반영하는데 품번이 섞인 팔레트만 못 담는다).
+     */
     private noteUnhandled;
+    /**
+     * 팔레트 물품에 **담고 있는 것**을 채운다 — 이미 아는 값을 덮지 않는다.
+     *
+     * 팔레트가 자기 품번·수량을 이미 들고 있으면(관측이 그렇게 말했으면) 담김 선언이 그것을 밀어내지
+     * 않는다. 비어 있던 자리만 채운다 — 「모른다」를 채우는 것이 이 작업의 목적이고, 아는 것을 바꾸는
+     * 것은 아니다.
+     */
+    private withContainedQuantity;
     private applyEpcis;
     /**
      * 물품 한 건 병합 — **아는 것을 잃지 않는다.** 새로 온 값이 우선, 없으면 기존 값 유지.

package/dist/observed-reducer.js

@@ -45,6 +45,15 @@ export class ObservedReducer {
     aggregation = new Map();
     /** 아직 관측되지 않은 자식의 담김 — 물품을 지어내지 않고 보류했다가 등장할 때 붙인다. */
     pendingParent = new Map(); // 자식 EPC → 부모(물류단위)
+    /**
+     * 팔레트가 **담고 있는 것**(클래스 + 수량) — 바코드 없이 수량만 실린 담김.
+     *
+     *  · `qtyAggregation`    — 우리가 그 팔레트 물품에 채워 넣은 내용(풀릴 때 되돌릴 근거).
+     *  · `pendingQuantities` — 담김이 먼저 오고 그 팔레트를 아직 관측하지 못한 경우. 물품을 지어내지
+     *                          않고 보류해 두었다가, 관측되는 순간 붙인다(`pendingParent` 와 같은 규율).
+     */
+    qtyAggregation = new Map();
+    pendingQuantities = new Map();
     tasks = new Map();
     equipment = new Map();
     persons = new Map();
@@ -371,10 +380,16 @@ export class ObservedReducer {
                 this.noteUnhandled(e);
         }
     }
-    /** 반영하지 못한 사건을 종류별로 센다 — 처음·마지막 시각을 함께 남겨 「언제부터」에 답한다. */
-    noteUnhandled(e) {
+    /**
+     * 반영하지 못한 사건을 종류별로 센다 — 처음·마지막 시각을 함께 남겨 「언제부터」에 답한다.
+     *
+     * `key` 를 주면 그 이름으로 센다: 종류 전체를 못 다룬 것과 **그 종류의 어떤 모양만** 못 다룬 것은
+     * 다른 사실이다(예: 담김은 반영하는데 품번이 섞인 팔레트만 못 담는다).
+     */
+    noteUnhandled(e, key) {
         const at = Date.parse(String(e.eventTime ?? ''));
-        const cur = this.unhandled.get(e.eventType) ?? { count: 0 };
+        const name = key ?? e.eventType;
+        const cur = this.unhandled.get(name) ?? { count: 0 };
         cur.count++;
         if (Number.isFinite(at)) {
             if (cur.firstAtMs === undefined || at < cur.firstAtMs)
@@ -382,7 +397,29 @@ export class ObservedReducer {
             if (cur.lastAtMs === undefined || at > cur.lastAtMs)
                 cur.lastAtMs = at;
         }
-        this.unhandled.set(e.eventType, cur);
+        this.unhandled.set(name, cur);
+    }
+    /**
+     * 팔레트 물품에 **담고 있는 것**을 채운다 — 이미 아는 값을 덮지 않는다.
+     *
+     * 팔레트가 자기 품번·수량을 이미 들고 있으면(관측이 그렇게 말했으면) 담김 선언이 그것을 밀어내지
+     * 않는다. 비어 있던 자리만 채운다 — 「모른다」를 채우는 것이 이 작업의 목적이고, 아는 것을 바꾸는
+     * 것은 아니다.
+     */
+    withContainedQuantity(cur, q, all) {
+        const parsed = q.epcClass ? parseEpc(q.epcClass) : undefined;
+        const declared = all.filter(x => typeof x.quantity === 'number');
+        return {
+            ...cur,
+            gtin: cur.gtin ?? q.epcClass,
+            gtinKey: cur.gtinKey ?? parsed?.gtinKey,
+            /* 관측이 준 수량이 있으면 그대로 둔다. 없으면(팔레트 하나로 세어 `1` 이던 자리) 내용의 수량이 답이다. */
+            qty: cur.qty !== undefined && cur.qty !== 1 ? cur.qty : q.quantity,
+            uom: cur.uom ?? q.uom,
+            /* 단위가 여럿일 때만 목록을 든다(하나면 `qty`/`uom` 이 무손실로 들고 있다 — 위 `upsert` 와 같은 규율). */
+            quantities: cur.quantities ?? (declared.length >= 2 ? declared.map(x => ({ value: x.quantity, ...(x.uom ? { uom: x.uom } : {}) })) : undefined),
+            lot: cur.lot ?? parsed?.lot
+        };
     }
     applyEpcis(ev, envelope) {
         /* 정정 선언이 붙은 이벤트는 **새 사실이 아니다** — 앞선 이벤트를 취소·수정하는 선언이다.
@@ -399,6 +436,46 @@ export class ObservedReducer {
             return;
         }
         if (ev.type === 'AggregationEvent') {
+            /*
+             * ── 바코드 없이 **수량만** 실린 담김 (2026-08-19) ────────────────────────
+             * 실제 창고는 박스마다 바코드를 붙이지 않는다. 팔레트 하나에 「이 품번 40개」로 입고하는 것이
+             * 훨씬 흔하고, 표준도 그 자리를 둔다(`childQuantityList`: 클래스 + 수량).
+             *
+             * 그런데 여기는 **낱개 자식만** 반영했다. 그래서 미러는 그 팔레트를 `{epc, location, qty: 1}` 로
+             * 들었다 — 실측: 품번도 없고 40개도 없다. 화면에는 「팔레트 1개」만 보이고 그 안의 40개는 재고
+             * 집계에서 통째로 빠진다. 실 WMS 를 붙이면 바로 부딪히는 자리다.
+             *
+             * **어떻게 담나**: 시뮬 커널이 같은 입고를 다루는 방식과 맞춘다 — 그쪽은 팔레트 물품 자신에
+             * 품번과 수량을 싣는다(`items.set(epc, { epc, gtin, qty … })`). 그래서 여기서도 팔레트 물품에
+             * 채운다. 새 필드를 만들지 않으므로 **기존 재고 집계가 그대로 센다**(필드만 만들고 아무도 읽지
+             * 않는 상태를 이 프로젝트는 결함으로 본다). 두 구동이 같은 모양을 들게 되는 것이 덤이다.
+             *
+             * **못 하는 경우는 밝힌다**: 한 팔레트에 품번이 둘 이상이면 이 모양으로 표현할 수 없다(하나를
+             * 골라 채우면 나머지를 지우는 것이다). 그때는 채우지 않고 `unhandled` 로 센다 — 조용히 버리지
+             * 않는다. 그 어휘를 담으려면 상태에 「담고 있는 것들」이 따로 필요하고, 그것은 별 결정이다.
+             */
+            if (ev.action === 'ADD' && ev.childQuantityList?.length) {
+                const classes = new Set(ev.childQuantityList.map(q => q.epcClass));
+                if (classes.size > 1) {
+                    /* 여러 품번이 한 팔레트에 — 지금 상태로는 표현할 수 없다. 세어서 드러낸다. */
+                    if (envelope)
+                        this.noteUnhandled(envelope, 'aggregation-mixed-classes');
+                }
+                else {
+                    const q = ev.childQuantityList[0];
+                    const cur = this.items.get(ev.parentID);
+                    /*
+                     * **관측하지 못한 팔레트를 지어내지 않는다** — 담김은 *어디 있는지*를 말하지 않는다.
+                     * 그 팔레트가 관측되면(ObjectEvent) 그때 위치와 함께 서고, 담김은 보류해 두었다가 붙인다.
+                     */
+                    if (!cur)
+                        this.pendingQuantities.set(ev.parentID, [...ev.childQuantityList]);
+                    else {
+                        this.items.set(cur.subLotId ?? cur.epc, this.withContainedQuantity(cur, q, ev.childQuantityList));
+                        this.qtyAggregation.set(ev.parentID, [...ev.childQuantityList]);
+                    }
+                }
+            }
             if (ev.action === 'ADD' && ev.childEPCs?.length) {
                 this.aggregation.set(ev.parentID, [...ev.childEPCs]);
                 /* 조립 관계를 물품에도 주입한다 — 예전에는 내부 맵에만 두고 밖으로 내보내지 않아, 3D 가
@@ -424,6 +501,16 @@ export class ObservedReducer {
                     this.pendingParent.delete(child);
                 }
                 this.aggregation.delete(ev.parentID);
+                /* 수량으로 담겼던 것을 풀면 그 팔레트는 **비게 된다** — 우리가 채운 것만 되돌린다(원래
+                   팔레트 자신의 수량이었다면 건드리지 않는다). */
+                if (this.qtyAggregation.delete(ev.parentID)) {
+                    const cur = this.items.get(ev.parentID);
+                    if (cur) {
+                        const { gtin, gtinKey, qty, uom, quantities, lot, ...rest } = cur;
+                        this.items.set(cur.subLotId ?? cur.epc, { ...rest, qty: 1 });
+                    }
+                }
+                this.pendingQuantities.delete(ev.parentID);
             }
             return;
         }
@@ -512,7 +599,9 @@ export class ObservedReducer {
         const parsedSelf = parseEpc(epc);
         /* `gtin` 은 **클래스 URI 원문**이다(오더 매칭이 이 값을 쓴다 — 뜻을 바꾸면 조용히 안 맞는다).
          * 파서로 뜯은 품번 키·로트는 **별도 필드**로 얹는다. */
-        const classUri = q?.epcClass ?? (parsedSelf.instance ? undefined : epc);
+        /* 담김이 먼저 온 팔레트는 그 내용의 클래스가 곧 이 물품의 품번이다(시뮬이 같은 입고를 그렇게 든다). */
+        const pendingQty = this.pendingQuantities.get(epc);
+        const classUri = q?.epcClass ?? pendingQty?.[0]?.epcClass ?? (parsedSelf.instance ? undefined : epc);
         return {
             epc,
             ...(subLotId ? { subLotId } : {}),
@@ -521,8 +610,12 @@ export class ObservedReducer {
             location: patch.location ?? cur?.location ?? '',
             disposition: patch.disposition ?? cur?.disposition,
             parent: cur?.parent ?? this.pendingParent.get(epc),
-            qty: q?.quantity ?? cur?.qty,
-            uom: q?.uom ?? cur?.uom,
+            /*
+             * 관측이 수량을 말하지 않았는데 **담김이 먼저 와 있었다면** 그 내용이 답이다(바코드 없이 수량만
+             * 실린 팔레트). 보류해 둔 것을 여기서 붙인다 — 위 `parent` 와 같은 규율이다.
+             */
+            qty: q?.quantity ?? this.pendingQuantities.get(epc)?.[0]?.quantity ?? cur?.qty,
+            uom: q?.uom ?? this.pendingQuantities.get(epc)?.[0]?.uom ?? cur?.uom,
             /*
              * 선언된 수량 전부 — 값이 없는 항목은 담지 않는다(모름을 0 으로 만들지 않는다).
              *
@@ -656,6 +749,9 @@ export class ObservedReducer {
             items: [...this.items.values()].map(i => ({ ...i })),
             aggregation: [...this.aggregation.entries()].map(([parent, children]) => ({ parent, children: [...children] })),
             pendingParent: [...this.pendingParent.entries()].map(([child, parent]) => ({ child, parent })),
+            /* 수량으로 담긴 것도 이어받는다 — 되풀어 주지 않는 축이다(원천은 담김을 다시 말해 주지 않는다). */
+            qtyAggregation: [...this.qtyAggregation.entries()].map(([parent, quantities]) => ({ parent, quantities })),
+            pendingQuantities: [...this.pendingQuantities.entries()].map(([parent, quantities]) => ({ parent, quantities })),
             tasks: [...this.tasks.values()].map(t => ({ ...t })),
             equipment: [...this.equipment.values()].map(m => ({ ...m })),
             persons: [...this.persons.values()].map(x => ({ ...x })),
@@ -677,6 +773,8 @@ export class ObservedReducer {
         this.items = new Map((cp?.items ?? []).map(i => [i.epc, { ...i }]));
         this.aggregation = new Map((cp?.aggregation ?? []).map(a => [a.parent, [...a.children]]));
         this.pendingParent = new Map((cp?.pendingParent ?? []).map(x => [x.child, x.parent]));
+        this.qtyAggregation = new Map((cp?.qtyAggregation ?? []).map(x => [x.parent, x.quantities]));
+        this.pendingQuantities = new Map((cp?.pendingQuantities ?? []).map(x => [x.parent, x.quantities]));
         this.tasks = new Map((cp?.tasks ?? []).map(t => [t.id, { ...t }]));
         this.equipment = new Map((cp?.equipment ?? []).map(m => [m.id, { ...m }]));
         this.persons = new Map((cp?.persons ?? []).map(x => [x.id, { ...x }]));

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,
@@ -1089,6 +1091,15 @@ var ObservedReducer = class {
   /** 아직 관측되지 않은 자식의 담김 — 물품을 지어내지 않고 보류했다가 등장할 때 붙인다. */
   pendingParent = /* @__PURE__ */ new Map();
   // 자식 EPC → 부모(물류단위)
+  /**
+   * 팔레트가 **담고 있는 것**(클래스 + 수량) — 바코드 없이 수량만 실린 담김.
+   *
+   *  · `qtyAggregation`    — 우리가 그 팔레트 물품에 채워 넣은 내용(풀릴 때 되돌릴 근거).
+   *  · `pendingQuantities` — 담김이 먼저 오고 그 팔레트를 아직 관측하지 못한 경우. 물품을 지어내지
+   *                          않고 보류해 두었다가, 관측되는 순간 붙인다(`pendingParent` 와 같은 규율).
+   */
+  qtyAggregation = /* @__PURE__ */ new Map();
+  pendingQuantities = /* @__PURE__ */ new Map();
   tasks = /* @__PURE__ */ new Map();
   equipment = /* @__PURE__ */ new Map();
   persons = /* @__PURE__ */ new Map();
@@ -1379,16 +1390,44 @@ var ObservedReducer = class {
         this.noteUnhandled(e);
     }
   }
-  /** 반영하지 못한 사건을 종류별로 센다 — 처음·마지막 시각을 함께 남겨 「언제부터」에 답한다. */
-  noteUnhandled(e) {
+  /**
+   * 반영하지 못한 사건을 종류별로 센다 — 처음·마지막 시각을 함께 남겨 「언제부터」에 답한다.
+   *
+   * `key` 를 주면 그 이름으로 센다: 종류 전체를 못 다룬 것과 **그 종류의 어떤 모양만** 못 다룬 것은
+   * 다른 사실이다(예: 담김은 반영하는데 품번이 섞인 팔레트만 못 담는다).
+   */
+  noteUnhandled(e, key) {
     const at = Date.parse(String(e.eventTime ?? ""));
-    const cur = this.unhandled.get(e.eventType) ?? { count: 0 };
+    const name = key ?? e.eventType;
+    const cur = this.unhandled.get(name) ?? { count: 0 };
     cur.count++;
     if (Number.isFinite(at)) {
       if (cur.firstAtMs === void 0 || at < cur.firstAtMs) cur.firstAtMs = at;
       if (cur.lastAtMs === void 0 || at > cur.lastAtMs) cur.lastAtMs = at;
     }
-    this.unhandled.set(e.eventType, cur);
+    this.unhandled.set(name, cur);
+  }
+  /**
+   * 팔레트 물품에 **담고 있는 것**을 채운다 — 이미 아는 값을 덮지 않는다.
+   *
+   * 팔레트가 자기 품번·수량을 이미 들고 있으면(관측이 그렇게 말했으면) 담김 선언이 그것을 밀어내지
+   * 않는다. 비어 있던 자리만 채운다 — 「모른다」를 채우는 것이 이 작업의 목적이고, 아는 것을 바꾸는
+   * 것은 아니다.
+   */
+  withContainedQuantity(cur, q, all) {
+    const parsed = q.epcClass ? parseEpc(q.epcClass) : void 0;
+    const declared = all.filter((x) => typeof x.quantity === "number");
+    return {
+      ...cur,
+      gtin: cur.gtin ?? q.epcClass,
+      gtinKey: cur.gtinKey ?? parsed?.gtinKey,
+      /* 관측이 준 수량이 있으면 그대로 둔다. 없으면(팔레트 하나로 세어 `1` 이던 자리) 내용의 수량이 답이다. */
+      qty: cur.qty !== void 0 && cur.qty !== 1 ? cur.qty : q.quantity,
+      uom: cur.uom ?? q.uom,
+      /* 단위가 여럿일 때만 목록을 든다(하나면 `qty`/`uom` 이 무손실로 들고 있다 — 위 `upsert` 와 같은 규율). */
+      quantities: cur.quantities ?? (declared.length >= 2 ? declared.map((x) => ({ value: x.quantity, ...x.uom ? { uom: x.uom } : {} })) : void 0),
+      lot: cur.lot ?? parsed?.lot
+    };
   }
   applyEpcis(ev, envelope) {
     if (ev.errorDeclaration) {
@@ -1401,6 +1440,20 @@ var ObservedReducer = class {
       return;
     }
     if (ev.type === "AggregationEvent") {
+      if (ev.action === "ADD" && ev.childQuantityList?.length) {
+        const classes = new Set(ev.childQuantityList.map((q2) => q2.epcClass));
+        if (classes.size > 1) {
+          if (envelope) this.noteUnhandled(envelope, "aggregation-mixed-classes");
+        } else {
+          const q2 = ev.childQuantityList[0];
+          const cur = this.items.get(ev.parentID);
+          if (!cur) this.pendingQuantities.set(ev.parentID, [...ev.childQuantityList]);
+          else {
+            this.items.set(cur.subLotId ?? cur.epc, this.withContainedQuantity(cur, q2, ev.childQuantityList));
+            this.qtyAggregation.set(ev.parentID, [...ev.childQuantityList]);
+          }
+        }
+      }
       if (ev.action === "ADD" && ev.childEPCs?.length) {
         this.aggregation.set(ev.parentID, [...ev.childEPCs]);
         for (const child of ev.childEPCs) {
@@ -1418,6 +1471,14 @@ var ObservedReducer = class {
           this.pendingParent.delete(child);
         }
         this.aggregation.delete(ev.parentID);
+        if (this.qtyAggregation.delete(ev.parentID)) {
+          const cur = this.items.get(ev.parentID);
+          if (cur) {
+            const { gtin, gtinKey, qty, uom, quantities, lot, ...rest } = cur;
+            this.items.set(cur.subLotId ?? cur.epc, { ...rest, qty: 1 });
+          }
+        }
+        this.pendingQuantities.delete(ev.parentID);
       }
       return;
     }
@@ -1475,7 +1536,8 @@ var ObservedReducer = class {
     const cur = this.items.get(subLotId ?? epc);
     const parsedClass = q?.epcClass ? parseEpc(q.epcClass) : void 0;
     const parsedSelf = parseEpc(epc);
-    const classUri = q?.epcClass ?? (parsedSelf.instance ? void 0 : epc);
+    const pendingQty = this.pendingQuantities.get(epc);
+    const classUri = q?.epcClass ?? pendingQty?.[0]?.epcClass ?? (parsedSelf.instance ? void 0 : epc);
     return {
       epc,
       ...subLotId ? { subLotId } : {},
@@ -1484,8 +1546,12 @@ var ObservedReducer = class {
       location: patch.location ?? cur?.location ?? "",
       disposition: patch.disposition ?? cur?.disposition,
       parent: cur?.parent ?? this.pendingParent.get(epc),
-      qty: q?.quantity ?? cur?.qty,
-      uom: q?.uom ?? cur?.uom,
+      /*
+       * 관측이 수량을 말하지 않았는데 **담김이 먼저 와 있었다면** 그 내용이 답이다(바코드 없이 수량만
+       * 실린 팔레트). 보류해 둔 것을 여기서 붙인다 — 위 `parent` 와 같은 규율이다.
+       */
+      qty: q?.quantity ?? this.pendingQuantities.get(epc)?.[0]?.quantity ?? cur?.qty,
+      uom: q?.uom ?? this.pendingQuantities.get(epc)?.[0]?.uom ?? cur?.uom,
       /*
        * 선언된 수량 전부 — 값이 없는 항목은 담지 않는다(모름을 0 으로 만들지 않는다).
        *
@@ -1613,6 +1679,9 @@ var ObservedReducer = class {
       items: [...this.items.values()].map((i) => ({ ...i })),
       aggregation: [...this.aggregation.entries()].map(([parent, children]) => ({ parent, children: [...children] })),
       pendingParent: [...this.pendingParent.entries()].map(([child, parent]) => ({ child, parent })),
+      /* 수량으로 담긴 것도 이어받는다 — 되풀어 주지 않는 축이다(원천은 담김을 다시 말해 주지 않는다). */
+      qtyAggregation: [...this.qtyAggregation.entries()].map(([parent, quantities]) => ({ parent, quantities })),
+      pendingQuantities: [...this.pendingQuantities.entries()].map(([parent, quantities]) => ({ parent, quantities })),
       tasks: [...this.tasks.values()].map((t) => ({ ...t })),
       equipment: [...this.equipment.values()].map((m) => ({ ...m })),
       persons: [...this.persons.values()].map((x) => ({ ...x })),
@@ -1634,6 +1703,8 @@ var ObservedReducer = class {
     this.items = new Map((cp?.items ?? []).map((i) => [i.epc, { ...i }]));
     this.aggregation = new Map((cp?.aggregation ?? []).map((a) => [a.parent, [...a.children]]));
     this.pendingParent = new Map((cp?.pendingParent ?? []).map((x) => [x.child, x.parent]));
+    this.qtyAggregation = new Map((cp?.qtyAggregation ?? []).map((x) => [x.parent, x.quantities]));
+    this.pendingQuantities = new Map((cp?.pendingQuantities ?? []).map((x) => [x.parent, x.quantities]));
     this.tasks = new Map((cp?.tasks ?? []).map((t) => [t.id, { ...t }]));
     this.equipment = new Map((cp?.equipment ?? []).map((m) => [m.id, { ...m }]));
     this.persons = new Map((cp?.persons ?? []).map((x) => [x.id, { ...x }]));
@@ -2684,28 +2755,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 +2841,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;
@@ -3861,6 +3985,11 @@ var FlowEngine = class {
       /* 스냅샷이 **델타보다 가난하면 안 된다** — 예전에는 소요·남은 시간을 빼고 내보내서, 이 스냅샷으로
        * 다른 커널을 주입하면(hydrateObserved) 진행 중이던 작업을 이어 굴릴 수 없었다(미러 스냅샷은
        * 델타에서 왔으므로 갖고 있었다 — 같은 계약을 두 구동이 다르게 채우던 자리). */
+      /* 관측이 담지 못한 사실을 그대로 내보낸다 — 리듀서가 세고 있어도 여기서 떨어뜨리면 아무도 못 본다. */
+      ...(() => {
+        const u = this.observer?.snapshot?.().unhandled;
+        return u?.length ? { unhandled: u } : {};
+      })(),
       tasks: [...this.tasks.values()].map((t) => ({
         id: t.id,
         kind: t.kind,
@@ -7762,6 +7891,7 @@ function retiredVocabularyIn(line) {
   ingestEnergyEquipmentRecords,
   ingestEnergyRecords,
   ingestOperationalRecords,
+  isAggregationRecord,
   isElectricalLocationType,
   isEnergyEquipmentRecord,
   isEnergyRecord,
@@ -7773,6 +7903,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.38",
   "type": "module",
   "description": "Twin Domain Kernel — framework-agnostic, zero-dep (domain + sim + 3-channel contract). WMS/YMS/MES, EPCIS 2.0 · ISA-95.",
   "publishConfig": {