@operato/twin-kernel 0.7.63 → 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;
 }
 /**

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/operational-ingest.js

@@ -267,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) {
@@ -357,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

@@ -3377,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
     });
   }
@@ -9172,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];
@@ -9256,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.63",
+  "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": {