@operato/twin-kernel 0.7.62 → 0.7.64

package/dist/contract.d.ts

@@ -5,6 +5,31 @@ export interface CanonicalEnvelope<T = unknown> {
     eventTime: ISOTime;
     tenantId: string;
     correlationId?: string;
+    /**
+     * **사람이 그때 적어 둔 말** — 연결된 시스템에서 온 자유 문장.
+     *
+     * ── 왜 이 자리가 필요한가 (2026-08-25) ────────────────────────────────────
+     * 재고 조정만은 **원인이 트윈의 모델 밖에 있다.** 다른 이동은 원인을 트윈이 스스로 압니다 —
+     * 꺼내 간 것은 작업 지시가 시켰고, 적치는 입고가 시켰습니다. 그런데 조정은 **사람이 판단한 것**이고,
+     * 그 이유는 그 사람이 적은 문장에만 있습니다(「실재고로 조정(192kg→198kg)」).
+     *
+     * 그 문장이 없으면 트윈은 「6kg 이 늘었다」까지만 알고 **왜인지 영원히 답하지 못합니다.**
+     *
+     * ── 왜 봉투에 두고 상태에 두지 않나 ──────────────────────────────────────
+     * 그 문장은 **지난 사건에 대한 사실**이고 지금 수량에 대한 사실이 아닙니다. 상태에 두면 조정 열 번에
+     * 문장 열 개가 쌓여 시간에 비례해 자랍니다. 지난 기록이 답하는 물음입니다.
+     *
+     * 그리고 EPCIS 사건 안에 넣지 않습니다 — 표준에 그 칸이 없고, 이름을 지어 넣으면 그 사건이
+     * 표준을 벗어납니다. 봉투는 우리 것이므로 여기가 맞고, 지난 기록에는 봉투가 그대로 남습니다.
+     *
+     * ── 커널은 읽지 않습니다 ─────────────────────────────────────────────────
+     * 자유 문장이므로 어떤 판단에도 쓰지 않습니다. 나르기만 합니다. 비어 있으면 이 칸을 만들지
+     * 않습니다 — 빈 문장은 「적지 않았다」와 다르게 보입니다.
+     *
+     * 표준 근거: ISA-95 가 거의 모든 타입에 두는 `Description`(DescriptionType). 사람의 글을 담는
+     * 표준 자리이고, EPCIS 핵심에는 없어 확장으로 갑니다.
+     */
+    description?: string;
     data: T;
 }
 /**
@@ -366,6 +391,18 @@ export interface TestResultFact extends TestResult {
     /** 무엇을 시험했나 — 표준 `TestResult.TestableObjectID`. 물품이면 EPC. */
     testableObjectId: string;
 }
+/**
+ * `OP_EVENT.complete` 의 내용 — 「이 목록이 전부다」.
+ *
+ * `axis` 를 받아 두는 이유: 지금은 물품만 이 방식이 필요하지만, 다른 목록도 같은 성질을 갖는다
+ * (연결된 시스템이 현재 목록을 통째로 말하는 것). 낱말을 닫으면 그때 계약을 또 고친다.
+ */
+export interface AxisCompleteFact {
+    /** 어느 목록인가 — 지금은 `'items'` 만 다룬다. */
+    completeAxis: string;
+    /** 그 주기를 **시작한** 시각(ISO). 이보다 오래된 것은 이 주기에 오지 않은 것이다. */
+    since: ISOTime;
+}
 /**
  * 이 시험 결과가 **이 시각에 유효한 합격인가.**
  *
@@ -2180,6 +2217,27 @@ export declare const OP_EVENT: {
      * 없고, 미러가 이어받지 못한다(§상태 ⊆ 이벤트).
      */
     readonly test: "test.result";
+    /**
+     * **이 목록이 전부다** — 연결된 시스템이 현재 목록을 한 바퀴 다 보낸 뒤 그것을 알린다.
+     *
+     * ── 왜 필요한가 (2026-08-25 실측) ────────────────────────────────────────
+     * 연결된 시스템은 매 주기 현재 재고를 전부 보낸다. 그런데 트윈은 그것을 낱낱의 관측으로 받아
+     * **더하기만 했다.** 「그리고 이것 말고는 없다」를 받는 곳이 없어서, 목록에서 빠진 줄은 아무 말도
+     * 오지 않은 것이 되고 트윈에 영원히 남았다.
+     *
+     * 실측: 실제 재고 1,704건인데 트윈이 10,038건을 갖고 있었다.
+     *
+     * ── 왜 「사라진 것을 알려 주기」가 아니라 이 방식인가 ──────────────────────
+     * 연결 쪽이 앞 주기와 비교해 사라진 줄을 찾아 알리는 방법도 있다. 그런데 그것은 **하나 빠뜨리면
+     * 그 줄이 영원히 남는다.** 이 방식은 주기마다 스스로 바로잡는다 — 이미 잘못 쌓인 것도 다음 주기에
+     * 사라진다.
+     *
+     * ── 보내는 쪽이 지킬 것 ─────────────────────────────────────────────────
+     * **끝까지 읽었을 때만 보낸다.** 읽다가 끊긴 주기에 이것을 보내면 **살아 있는 재고를 지운다.**
+     * 그리고 `since` 는 그 주기를 **시작한** 시각이다(끝낸 시각이 아니다) — 주기 도중에 들어온 관측이
+     * 지워지지 않아야 한다.
+     */
+    readonly complete: "axis.complete";
     /**
      * 주목 신호 확인(ack) — **사람이 한 행위**라 파생될 수 없다.
      *

package/dist/contract.js

@@ -944,6 +944,27 @@ export const OP_EVENT = {
      * 없고, 미러가 이어받지 못한다(§상태 ⊆ 이벤트).
      */
     test: 'test.result',
+    /**
+     * **이 목록이 전부다** — 연결된 시스템이 현재 목록을 한 바퀴 다 보낸 뒤 그것을 알린다.
+     *
+     * ── 왜 필요한가 (2026-08-25 실측) ────────────────────────────────────────
+     * 연결된 시스템은 매 주기 현재 재고를 전부 보낸다. 그런데 트윈은 그것을 낱낱의 관측으로 받아
+     * **더하기만 했다.** 「그리고 이것 말고는 없다」를 받는 곳이 없어서, 목록에서 빠진 줄은 아무 말도
+     * 오지 않은 것이 되고 트윈에 영원히 남았다.
+     *
+     * 실측: 실제 재고 1,704건인데 트윈이 10,038건을 갖고 있었다.
+     *
+     * ── 왜 「사라진 것을 알려 주기」가 아니라 이 방식인가 ──────────────────────
+     * 연결 쪽이 앞 주기와 비교해 사라진 줄을 찾아 알리는 방법도 있다. 그런데 그것은 **하나 빠뜨리면
+     * 그 줄이 영원히 남는다.** 이 방식은 주기마다 스스로 바로잡는다 — 이미 잘못 쌓인 것도 다음 주기에
+     * 사라진다.
+     *
+     * ── 보내는 쪽이 지킬 것 ─────────────────────────────────────────────────
+     * **끝까지 읽었을 때만 보낸다.** 읽다가 끊긴 주기에 이것을 보내면 **살아 있는 재고를 지운다.**
+     * 그리고 `since` 는 그 주기를 **시작한** 시각이다(끝낸 시각이 아니다) — 주기 도중에 들어온 관측이
+     * 지워지지 않아야 한다.
+     */
+    complete: 'axis.complete',
     /**
      * 주목 신호 확인(ack) — **사람이 한 행위**라 파생될 수 없다.
      *

package/dist/face2-adapter.js

@@ -225,11 +225,18 @@ export function ingest(records, rules, opts) {
             rejected.push({ record, errors });
             continue;
         }
+        /*
+         * 사람이 적어 둔 말은 **봉투에** 싣는다(§`CanonicalEnvelope.description`) — EPCIS 사건 안에 넣으면
+         * 그 사건이 표준을 벗어난다. 지난 기록에는 봉투가 그대로 남으므로 잃지 않는다.
+         * 비어 있으면 이 칸을 만들지 않는다 — 빈 문장은 「적지 않았다」와 다르게 보인다.
+         */
+        const note = typeof record['description'] === 'string' ? String(record['description']).trim() : '';
         accepted.push({
             eventId: `${opts.tenantId}-ingest-${++seq}`,
             eventType: `epcis.${ev.type}`,
             eventTime: ev.eventTime,
             tenantId: opts.tenantId,
+            ...(note ? { description: note } : {}),
             data: ev
         });
     }

package/dist/observed-reducer.d.ts

@@ -18,6 +18,14 @@ interface ProjItem {
     expiry?: number;
     /** 이 로트의 시험 결과 — **명세당 최신 하나**(상태가 계측 주기로 자라지 않게). */
     testResults?: TestResult[];
+    /**
+     * **마지막으로 관측된 시각**(ms) — 「이 목록이 전부다」를 받았을 때 무엇을 지울지 가리는 값.
+     *
+     * 물품 안에 두는 이유: 순서 판정에 쓰는 시각(`lastAt`)은 **중간 저장본에 들어가지 않는다.**
+     * 그것에 기대면 재기동 직후 첫 신호가 재고를 전부 지운다(본 적이 없는 것으로 보이므로).
+     * 물품은 중간 저장본에 들어가므로 이 값도 함께 살아남는다.
+     */
+    seenAtMs?: number;
 }
 /**
  * 마스터 동기 — 선언적 로케이션 upsert/remove.

package/dist/observed-reducer.js

@@ -435,6 +435,44 @@ export class ObservedReducer {
                 item.testResults = [...kept, next];
                 break;
             }
+            case OP_EVENT.complete: {
+                /*
+                 * ── ★ **이 목록이 전부다** (2026-08-25) ────────────────────────────────
+                 *
+                 * 연결된 시스템이 현재 목록을 한 바퀴 다 보낸 뒤 그것을 알린다. 이 주기에 오지 않은 것은
+                 * **그 시스템에 더 이상 없는 것**이므로 지운다.
+                 *
+                 * 이것이 없던 동안 트윈은 받은 것을 **더하기만 했다** — 목록에서 빠진 줄은 아무 말도 오지 않은
+                 * 것이 되어 영원히 남았다(실측: 실제 1,704건인데 트윈이 10,038건).
+                 *
+                 * ── 아무것도 못 들은 주기에는 지우지 않는다 ────────────────────────────
+                 * 그 주기에 관측이 **한 건도** 없었다면 그것은 「다 없어졌다」가 아니라 **우리가 못 들은 것**이다.
+                 * 그때 지우면 살아 있는 재고가 사라진다 — 이 저장소가 여러 번 거절한 모양이다(결측 ≠ 없음).
+                 *
+                 * 보내는 쪽의 규율은 계약에 적었다: **끝까지 읽었을 때만 보낸다.** 읽다가 끊긴 주기에 보내면
+                 * 살아 있는 재고를 지운다. 그 판단은 보내는 쪽만 할 수 있다.
+                 *
+                 * 지운 수를 `unhandled` 로 세지 않는다 — 그것은 반영하지 못한 사건을 세는 자리다. 여기서 지운
+                 * 것은 **정상적으로 반영한 결과**다.
+                 */
+                const d = e.data;
+                if (d?.completeAxis !== 'items')
+                    break;
+                const since = Date.parse(String(d.since ?? ''));
+                if (!Number.isFinite(since))
+                    break;
+                let heard = 0;
+                for (const it of this.items.values())
+                    if ((it.seenAtMs ?? -1) >= since)
+                        heard++;
+                if (!heard)
+                    break;
+                for (const [key, it] of [...this.items.entries()]) {
+                    if ((it.seenAtMs ?? -1) < since)
+                        this.remove(key);
+                }
+                break;
+            }
             case OP_EVENT.attentionAck: {
                 /* 확인한 사실만 담는다 — 그 신호가 지금도 성립하는지는 상태가 답한다(여기서 판단하지 않는다). */
                 const d = e.data;
@@ -632,6 +670,45 @@ export class ObservedReducer {
         if (ev.action === 'DELETE') {
             for (const epc of ev.epcList)
                 this.remove(epc);
+            /*
+             * ── ★ **수량으로 온 물품도 없어질 수 있어야 한다** (2026-08-25 실측) ────────
+             *
+             * 여기는 `epcList` 만 봤다. 그래서 **낱개 번호가 없는 현장에서는 재고를 지울 방법이 하나도
+             * 없었다** — 승화푸드는 모든 재고가 수량으로 오는 현장이다.
+             *
+             * 결과: 한 번 본 재고가 영원히 남았다. 연결된 시스템의 목록에서 그 줄이 없어져도 우리는
+             * 「없어졌다」를 들을 길이 없었다(있는 것만 오고, 없어진 것은 아무 말도 오지 않는다).
+             * 실측으로 실제 재고 1,704건인데 트윈이 10,038건을 갖고 있었다.
+             *
+             * ── 무엇을 지우는지는 말한 범위대로 ────────────────────────────────────
+             *   자리를 함께 말했다   그 자리의 그 로트만 지운다 (꺼내 가서 그 칸이 빈 경우)
+             *   자리를 말하지 않았다  그 로트를 모든 자리에서 지운다 (그 로트가 통째로 없어진 경우)
+             *
+             * 짐작이 아니라 **진술의 범위를 읽는 것**이다. 자리를 말했으면 그 자리를 말한 것이고,
+             * 말하지 않았으면 자리를 가리지 않고 말한 것이다.
+             *
+             * 순서 판정을 함께 지난다: 늦게 온 옛 「없어졌다」가 그 뒤에 다시 들어온 재고를 지우면 안 된다.
+             * 열쇠는 관측과 같은 것을 쓴다 — 같은 대상의 두 방향이므로 한 열쇠로 재야 한다.
+             */
+            const goneAt = ev.readPoint?.id;
+            for (const qe of ev.quantityList ?? []) {
+                if (!qe?.epcClass)
+                    continue;
+                if (goneAt) {
+                    const key = `${qe.epcClass}@${goneAt}`;
+                    if (envelope && this.stale(`item:${key}`, envelope))
+                        continue;
+                    this.remove(key);
+                    continue;
+                }
+                for (const key of [...this.items.keys()]) {
+                    if (!key.startsWith(`${qe.epcClass}@`))
+                        continue;
+                    if (envelope && this.stale(`item:${key}`, envelope))
+                        continue;
+                    this.remove(key);
+                }
+            }
             return;
         }
         const loc = ev.readPoint?.id;
@@ -646,7 +723,9 @@ export class ObservedReducer {
             /* 물품별 순서 판정 — 늦게 온 옛 관측이 최신 위치를 덮지 않게. */
             if (envelope && this.stale(`item:${epc}`, envelope))
                 continue;
-            this.items.set(epc, this.mergeItem(epc, { location: loc, disposition: ev.disposition, ilmd: ev.ilmd }, q, all));
+            const seen = this.mergeItem(epc, { location: loc, disposition: ev.disposition, ilmd: ev.ilmd }, q, all);
+            const atSeen = Date.parse(String(envelope?.eventTime ?? ''));
+            this.items.set(itemKeyOf(seen), Number.isFinite(atSeen) ? { ...seen, seenAtMs: atSeen } : seen);
         }
         /* 개체 없이 수량만 오는 입고(비직렬 자재) — 표준이 허용하고 검증기도 유효로 판정한다.
          * 이 경우 클래스 식별자 자체가 물품의 키다(로트 관리 자재는 LGTIN 이라 로트별로 갈린다). */
@@ -683,7 +762,9 @@ export class ObservedReducer {
                  */
                 if (envelope && this.stale(`item:${subLotId}`, envelope))
                     continue;
-                this.items.set(subLotId, this.mergeItem(qe.epcClass, { location: loc, disposition: ev.disposition, ilmd: ev.ilmd }, qe, mine, subLotId));
+                const seenQty = this.mergeItem(qe.epcClass, { location: loc, disposition: ev.disposition, ilmd: ev.ilmd }, qe, mine, subLotId);
+                const atQty = Date.parse(String(envelope?.eventTime ?? ''));
+                this.items.set(subLotId, Number.isFinite(atQty) ? { ...seenQty, seenAtMs: atQty } : seenQty);
             }
         }
     }
@@ -936,8 +1017,16 @@ export class ObservedReducer {
                     origin: n.origin
                 };
             }),
-            /* 들고 있는 것을 전부 내보낸다 — 축소하면 그 자리에서 정보가 사라진다. */
-            items: [...this.items.values()].map(i => ({ ...i })),
+            /*
+             * 갖고 있는 것을 전부 내보낸다 — 줄이면 그 자리에서 정보가 사라진다.
+             *
+             * **`seenAtMs` 는 뺀다.** 그것은 물품에 대한 사실이 아니라 **우리가 언제 들었나**이고, 「이 목록이
+             * 전부다」를 받았을 때 무엇을 지울지 가리는 데만 쓴다. 화면이 알 필요가 없고, 상태에 내보내면
+             * 자체 구동에는 없는 값이라 두 구동이 어긋난다(적합성 검사가 그것을 잡았다).
+             *
+             * 중간 저장본에는 남는다 — 재기동 뒤에도 무엇을 지울지 가릴 수 있어야 한다.
+             */
+            items: [...this.items.values()].map(({ seenAtMs: _seen, ...i }) => ({ ...i })),
             /* 유효 기간 판정은 **저장하지 않고 여기서 낸다** — 시뮬과 **같은 함수**(`effectivityAt`)를 부른다.
                만료는 이벤트 없이 시각만으로 일어나므로, 델타로 받아 두면 유휴 자원이 영원히 유효하게 남는다. */
             persons: [...this.persons.values()].map(p => ({ ...p, ...this.effectivityPart(p), ...this.offShiftPart(`person:${p.id}`), ...this.capabilityPart(p, `person:${p.id}`, p.personnelClassIds, this.classDefs.personnel) })),

package/dist/operational-ingest.d.ts

@@ -1,6 +1,6 @@
 import type { IngestResult } from './face2-adapter.ts';
 /** 이 문이 받는 여섯 가지 — 리듀서가 접는 것과 같은 목록(주목 확인은 우리 안의 행위라 제외). */
-export type OperationalKind = 'task' | 'equipment' | 'person' | 'asset' | 'order' | 'quality' | 'test' | 'observation';
+export type OperationalKind = 'task' | 'equipment' | 'person' | 'asset' | 'order' | 'quality' | 'test' | 'observation' | 'complete';
 /**
  * 정규 운영 레코드 — **델타의 필드 이름 + 시각(`at`)**.
  *

package/dist/operational-ingest.js

@@ -151,6 +151,18 @@ const SPECS = {
      * `effectiveTime` 도 요구하지 않는다. 없으면 봉투의 시각이 그 자리를 대신한다(§`resolve`) — 원본이
      * 시각을 말하지 않는 수기 점검이 실재하고, 그때 지어낸 시각보다 폴링 시각이 정직하다.
      */
+    /*
+     * **이 목록이 전부다** — 연결된 시스템이 현재 목록을 한 바퀴 다 보낸 뒤 알린다.
+     *
+     * 둘 다 요구한다: 어느 목록인지와 그 주기를 **시작한** 시각. 시각이 없으면 무엇을 지울지 가릴 수
+     * 없고, 그때 지우면 전부 지운다 — 받지 않는 것이 옳다.
+     */
+    complete: {
+        eventType: OP_EVENT.complete,
+        identity: 'completeAxis',
+        required: ['completeAxis', 'since'],
+        fields: { completeAxis: 'string', since: 'string', recordTime: 'string' }
+    },
     observation: {
         eventType: OP_EVENT.observation,
         identity: 'locationId',
@@ -223,6 +235,9 @@ export function operationalKindOf(record) {
      */
     if (has('locationId') && has('propertyId'))
         return 'observation';
+    /* 「이 목록이 전부다」 — 어느 목록인지를 스스로 말하므로 다른 사실과 섞이지 않는다. */
+    if (has('completeAxis'))
+        return 'complete';
     return undefined;
 }
 /** 이 레코드가 운영 사실인가 — 호스트의 라우팅이 묻는 자리. */
@@ -252,8 +267,15 @@ export function ingestOperationalRecords(records, opts) {
         const spec = SPECS[kind];
         const r = record;
         const errors = [];
-        /* 모르는 이름은 거부한다 — 한 글자 틀린 필드가 조용히 사라지는 것을 막는다. */
-        const unknown = Object.keys(r).filter(k => k !== 'at' && spec.fields[k] === undefined);
+        /*
+         * 모르는 이름은 거부한다 — 한 글자 틀린 필드가 오류 없이 사라지는 것을 막는다.
+         *
+         * 둘은 뺀다. **사실의 칸이 아니라 봉투의 칸**이다: `at` 은 그 사실이 일어난 시각이고,
+         * `description` 은 사람이 그때 적어 둔 말이다(§`CanonicalEnvelope.description`). 사실 칸으로
+         * 검사하면 명세마다 같은 두 줄을 적어야 하고, 한 곳을 빠뜨리면 그 통로만 거부한다.
+         */
+        const ENVELOPE_FIELDS = ['at', 'description'];
+        const unknown = Object.keys(r).filter(k => !ENVELOPE_FIELDS.includes(k) && spec.fields[k] === undefined);
         if (unknown.length)
             errors.push(`${kind}: 계약에 없는 필드 — ${unknown.join(', ')}`);
         for (const name of spec.required) {
@@ -342,11 +364,14 @@ export function ingestOperationalRecords(records, opts) {
             rejected.push({ record, errors });
             continue;
         }
+        /* 사람이 적어 둔 말 — 봉투에 싣는다(§`CanonicalEnvelope.description`). 물류 쪽과 같은 자리다. */
+        const note = typeof r.description === 'string' ? String(r.description).trim() : '';
         accepted.push({
             eventId: `${opts.tenantId}-op-${kind}-${++seq}`,
             eventType: spec.eventType,
             eventTime: new Date(atMs).toISOString(),
             tenantId: opts.tenantId,
+            ...(note ? { description: note } : {}),
             data
         });
     }

package/dist-cjs/index.cjs

@@ -614,6 +614,27 @@ var OP_EVENT = {
    * 없고, 미러가 이어받지 못한다(§상태 ⊆ 이벤트).
    */
   test: "test.result",
+  /**
+   * **이 목록이 전부다** — 연결된 시스템이 현재 목록을 한 바퀴 다 보낸 뒤 그것을 알린다.
+   *
+   * ── 왜 필요한가 (2026-08-25 실측) ────────────────────────────────────────
+   * 연결된 시스템은 매 주기 현재 재고를 전부 보낸다. 그런데 트윈은 그것을 낱낱의 관측으로 받아
+   * **더하기만 했다.** 「그리고 이것 말고는 없다」를 받는 곳이 없어서, 목록에서 빠진 줄은 아무 말도
+   * 오지 않은 것이 되고 트윈에 영원히 남았다.
+   *
+   * 실측: 실제 재고 1,704건인데 트윈이 10,038건을 갖고 있었다.
+   *
+   * ── 왜 「사라진 것을 알려 주기」가 아니라 이 방식인가 ──────────────────────
+   * 연결 쪽이 앞 주기와 비교해 사라진 줄을 찾아 알리는 방법도 있다. 그런데 그것은 **하나 빠뜨리면
+   * 그 줄이 영원히 남는다.** 이 방식은 주기마다 스스로 바로잡는다 — 이미 잘못 쌓인 것도 다음 주기에
+   * 사라진다.
+   *
+   * ── 보내는 쪽이 지킬 것 ─────────────────────────────────────────────────
+   * **끝까지 읽었을 때만 보낸다.** 읽다가 끊긴 주기에 이것을 보내면 **살아 있는 재고를 지운다.**
+   * 그리고 `since` 는 그 주기를 **시작한** 시각이다(끝낸 시각이 아니다) — 주기 도중에 들어온 관측이
+   * 지워지지 않아야 한다.
+   */
+  complete: "axis.complete",
   /**
    * 주목 신호 확인(ack) — **사람이 한 행위**라 파생될 수 없다.
    *
@@ -1668,6 +1689,19 @@ var ObservedReducer = class {
         item.testResults = [...kept, next];
         break;
       }
+      case OP_EVENT.complete: {
+        const d = e.data;
+        if (d?.completeAxis !== "items") break;
+        const since = Date.parse(String(d.since ?? ""));
+        if (!Number.isFinite(since)) break;
+        let heard = 0;
+        for (const it of this.items.values()) if ((it.seenAtMs ?? -1) >= since) heard++;
+        if (!heard) break;
+        for (const [key, it] of [...this.items.entries()]) {
+          if ((it.seenAtMs ?? -1) < since) this.remove(key);
+        }
+        break;
+      }
       case OP_EVENT.attentionAck: {
         const d = e.data;
         if (d?.id) this.acked.add(d.id);
@@ -1812,6 +1846,21 @@ var ObservedReducer = class {
     }
     if (ev.action === "DELETE") {
       for (const epc of ev.epcList) this.remove(epc);
+      const goneAt = ev.readPoint?.id;
+      for (const qe of ev.quantityList ?? []) {
+        if (!qe?.epcClass) continue;
+        if (goneAt) {
+          const key = `${qe.epcClass}@${goneAt}`;
+          if (envelope && this.stale(`item:${key}`, envelope)) continue;
+          this.remove(key);
+          continue;
+        }
+        for (const key of [...this.items.keys()]) {
+          if (!key.startsWith(`${qe.epcClass}@`)) continue;
+          if (envelope && this.stale(`item:${key}`, envelope)) continue;
+          this.remove(key);
+        }
+      }
       return;
     }
     const loc = ev.readPoint?.id;
@@ -1820,7 +1869,9 @@ var ObservedReducer = class {
     this.touchLocation(loc);
     for (const epc of ev.epcList) {
       if (envelope && this.stale(`item:${epc}`, envelope)) continue;
-      this.items.set(epc, this.mergeItem(epc, { location: loc, disposition: ev.disposition, ilmd: ev.ilmd }, q, all));
+      const seen = this.mergeItem(epc, { location: loc, disposition: ev.disposition, ilmd: ev.ilmd }, q, all);
+      const atSeen = Date.parse(String(envelope?.eventTime ?? ""));
+      this.items.set(itemKeyOf(seen), Number.isFinite(atSeen) ? { ...seen, seenAtMs: atSeen } : seen);
     }
     if (!ev.epcList?.length) {
       for (const qe of ev.quantityList ?? []) {
@@ -1828,7 +1879,9 @@ var ObservedReducer = class {
         const mine = all.filter((x) => x.epcClass === qe.epcClass);
         const subLotId = `${qe.epcClass}@${loc}`;
         if (envelope && this.stale(`item:${subLotId}`, envelope)) continue;
-        this.items.set(subLotId, this.mergeItem(qe.epcClass, { location: loc, disposition: ev.disposition, ilmd: ev.ilmd }, qe, mine, subLotId));
+        const seenQty = this.mergeItem(qe.epcClass, { location: loc, disposition: ev.disposition, ilmd: ev.ilmd }, qe, mine, subLotId);
+        const atQty = Date.parse(String(envelope?.eventTime ?? ""));
+        this.items.set(subLotId, Number.isFinite(atQty) ? { ...seenQty, seenAtMs: atQty } : seenQty);
       }
     }
   }
@@ -2065,8 +2118,16 @@ var ObservedReducer = class {
           origin: n.origin
         };
       }),
-      /* 들고 있는 것을 전부 내보낸다 — 축소하면 그 자리에서 정보가 사라진다. */
-      items: [...this.items.values()].map((i) => ({ ...i })),
+      /*
+       * 갖고 있는 것을 전부 내보낸다 — 줄이면 그 자리에서 정보가 사라진다.
+       *
+       * **`seenAtMs` 는 뺀다.** 그것은 물품에 대한 사실이 아니라 **우리가 언제 들었나**이고, 「이 목록이
+       * 전부다」를 받았을 때 무엇을 지울지 가리는 데만 쓴다. 화면이 알 필요가 없고, 상태에 내보내면
+       * 자체 구동에는 없는 값이라 두 구동이 어긋난다(적합성 검사가 그것을 잡았다).
+       *
+       * 중간 저장본에는 남는다 — 재기동 뒤에도 무엇을 지울지 가릴 수 있어야 한다.
+       */
+      items: [...this.items.values()].map(({ seenAtMs: _seen, ...i }) => ({ ...i })),
       /* 유효 기간 판정은 **저장하지 않고 여기서 낸다** — 시뮬과 **같은 함수**(`effectivityAt`)를 부른다.
          만료는 이벤트 없이 시각만으로 일어나므로, 델타로 받아 두면 유휴 자원이 영원히 유효하게 남는다. */
       persons: [...this.persons.values()].map((p) => ({ ...p, ...this.effectivityPart(p), ...this.offShiftPart(`person:${p.id}`), ...this.capabilityPart(p, `person:${p.id}`, p.personnelClassIds, this.classDefs.personnel) })),
@@ -3316,11 +3377,13 @@ function ingest(records, rules, opts) {
       rejected.push({ record, errors });
       continue;
     }
+    const note = typeof record["description"] === "string" ? String(record["description"]).trim() : "";
     accepted.push({
       eventId: `${opts.tenantId}-ingest-${++seq}`,
       eventType: `epcis.${ev.type}`,
       eventTime: ev.eventTime,
       tenantId: opts.tenantId,
+      ...note ? { description: note } : {},
       data: ev
     });
   }
@@ -9044,6 +9107,18 @@ var SPECS = {
    * `effectiveTime` 도 요구하지 않는다. 없으면 봉투의 시각이 그 자리를 대신한다(§`resolve`) — 원본이
    * 시각을 말하지 않는 수기 점검이 실재하고, 그때 지어낸 시각보다 폴링 시각이 정직하다.
    */
+  /*
+   * **이 목록이 전부다** — 연결된 시스템이 현재 목록을 한 바퀴 다 보낸 뒤 알린다.
+   *
+   * 둘 다 요구한다: 어느 목록인지와 그 주기를 **시작한** 시각. 시각이 없으면 무엇을 지울지 가릴 수
+   * 없고, 그때 지우면 전부 지운다 — 받지 않는 것이 옳다.
+   */
+  complete: {
+    eventType: OP_EVENT.complete,
+    identity: "completeAxis",
+    required: ["completeAxis", "since"],
+    fields: { completeAxis: "string", since: "string", recordTime: "string" }
+  },
   observation: {
     eventType: OP_EVENT.observation,
     identity: "locationId",
@@ -9075,6 +9150,7 @@ function operationalKindOf(record) {
   if (has("orderId")) return "order";
   if (has("testableObjectId")) return "test";
   if (has("locationId") && has("propertyId")) return "observation";
+  if (has("completeAxis")) return "complete";
   return void 0;
 }
 function isOperationalRecord(record) {
@@ -9098,7 +9174,8 @@ function ingestOperationalRecords(records, opts) {
     const spec = SPECS[kind];
     const r = record;
     const errors = [];
-    const unknown = Object.keys(r).filter((k) => k !== "at" && spec.fields[k] === void 0);
+    const ENVELOPE_FIELDS = ["at", "description"];
+    const unknown = Object.keys(r).filter((k) => !ENVELOPE_FIELDS.includes(k) && spec.fields[k] === void 0);
     if (unknown.length) errors.push(`${kind}: \uACC4\uC57D\uC5D0 \uC5C6\uB294 \uD544\uB4DC \u2014 ${unknown.join(", ")}`);
     for (const name of spec.required) {
       const v = r[name];
@@ -9182,11 +9259,13 @@ function ingestOperationalRecords(records, opts) {
       rejected.push({ record, errors });
       continue;
     }
+    const note = typeof r.description === "string" ? String(r.description).trim() : "";
     accepted.push({
       eventId: `${opts.tenantId}-op-${kind}-${++seq}`,
       eventType: spec.eventType,
       eventTime: new Date(atMs).toISOString(),
       tenantId: opts.tenantId,
+      ...note ? { description: note } : {},
       data
     });
   }

package/package.json

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