@operato/twin-kernel 0.11.2 → 0.11.3

package/dist/flow-engine.d.ts

@@ -1311,7 +1311,44 @@ export declare abstract class FlowEngine implements TwinKernel {
         subject: string;
         basis: 'declared' | 'twin-local';
     };
-    protected emitOp(eventType: string, data: unknown): void;
+    /**
+     * 운영 델타 방출 — **같은 사실을 다시 적지 않는다.**
+     *
+     * ── 무엇이 있었나 (2026-09-05 실측) ────────────────────────────────────────
+     * `flow-engine.ts` 의 배정 패스가 **매 틱** `created` 인 오더 전부에 `allocate` 를 건다. 자재가
+     * 모자란 오더는 그때마다 `mes-kernel` 의 「모자람을 적고 다음 틱에 다시 본다」 줄에 닿았고, 거기서
+     * **바뀐 것이 없어도 방출**했다.
+     *
+     *   hatio-mx2   오더 315개 → 세 시간에 order.status 2,433,116건 (오더당 7,700)
+     *   다른 트윈    오더당 1~2건
+     *   틱 로그      「journal 706.92ms(88%)」
+     *
+     * 다시 보는 것은 옳다(모자람은 채워질 수 있다). **다시 볼 때마다 적는 것**이 결함이다.
+     *
+     * ── 파급이 디스크가 아니다 ─────────────────────────────────────────────────
+     *   재기동      저널을 접어 상태를 세운다 — 되세우는 시간이 그만큼 는다
+     *   구독        이 사건들은 방송된다. 막힌 오더 × 매 틱 × 구독자 수
+     *   틱          시뮬 틱은 메인 이벤트 루프에서 돈다 — HTTP·구독이 함께 느려진다
+     *   지표        오더 사건을 세는 모든 것이 부푼다
+     *   진짜 문제   「오더가 자재를 못 구해 멈췄다」가 자기가 만든 소음에 묻힌다
+     *
+     * 가장 나쁜 것은 방향이다. **현장이 막힐수록 트윈이 더 무너진다** — 잘 흐르면 사건이 적고 막히면
+     * 폭증한다. 트윈이 가장 필요한 순간에 가장 약해진다.
+     *
+     * ── 왜 여기인가 ────────────────────────────────────────────────────────────
+     * 부르는 자리 하나를 막으면 다른 자리에서 같은 일이 난다 — `emitOrder` 를 부르는 곳만 열다섯이다.
+     * 그리고 `revision` 이 여기서 오르므로, 여기서 막지 않으면 **적지 않고도 판만 올라간다.**
+     *
+     * ── 무엇을 같다고 보나 ─────────────────────────────────────────────────────
+     * `data` 가 바이트까지 같으면 같다. 시각은 `data` 에 없다(여기서 붙인다) — 그래서 「같은 사실을
+     * 다른 시각에 다시 말한 것」이 정확히 걸러진다.
+     *
+     * `subject` 를 안 주면 거르지 않는다. 대상이 없는 사건(주의 등)은 반복 자체가 사실이다.
+     *
+     * 재기동하면 이 기억이 비므로 **첫 방출은 언제나 나간다** — 되세운 상태가 조용히 빠지지 않는다.
+     */
+    private lastEmitted;
+    protected emitOp(eventType: string, data: unknown, subject?: string): void;
     /**
      * 작업 전이 방출 — **커널이 아는 것을 미러도 알게** 한다.
      *

package/dist/flow-engine.js

@@ -2820,7 +2820,51 @@ export class FlowEngine {
     subjectOf(kind, localId) {
         return resolveSubject(kind, localId, { tenantId: this.tenantId, scopeId: this.scopeId, identityOf: (k, id) => (k === 'equipment' ? this.equipmentIdentity(id) : undefined) });
     }
-    emitOp(eventType, data) {
+    /**
+     * 운영 델타 방출 — **같은 사실을 다시 적지 않는다.**
+     *
+     * ── 무엇이 있었나 (2026-09-05 실측) ────────────────────────────────────────
+     * `flow-engine.ts` 의 배정 패스가 **매 틱** `created` 인 오더 전부에 `allocate` 를 건다. 자재가
+     * 모자란 오더는 그때마다 `mes-kernel` 의 「모자람을 적고 다음 틱에 다시 본다」 줄에 닿았고, 거기서
+     * **바뀐 것이 없어도 방출**했다.
+     *
+     *   hatio-mx2   오더 315개 → 세 시간에 order.status 2,433,116건 (오더당 7,700)
+     *   다른 트윈    오더당 1~2건
+     *   틱 로그      「journal 706.92ms(88%)」
+     *
+     * 다시 보는 것은 옳다(모자람은 채워질 수 있다). **다시 볼 때마다 적는 것**이 결함이다.
+     *
+     * ── 파급이 디스크가 아니다 ─────────────────────────────────────────────────
+     *   재기동      저널을 접어 상태를 세운다 — 되세우는 시간이 그만큼 는다
+     *   구독        이 사건들은 방송된다. 막힌 오더 × 매 틱 × 구독자 수
+     *   틱          시뮬 틱은 메인 이벤트 루프에서 돈다 — HTTP·구독이 함께 느려진다
+     *   지표        오더 사건을 세는 모든 것이 부푼다
+     *   진짜 문제   「오더가 자재를 못 구해 멈췄다」가 자기가 만든 소음에 묻힌다
+     *
+     * 가장 나쁜 것은 방향이다. **현장이 막힐수록 트윈이 더 무너진다** — 잘 흐르면 사건이 적고 막히면
+     * 폭증한다. 트윈이 가장 필요한 순간에 가장 약해진다.
+     *
+     * ── 왜 여기인가 ────────────────────────────────────────────────────────────
+     * 부르는 자리 하나를 막으면 다른 자리에서 같은 일이 난다 — `emitOrder` 를 부르는 곳만 열다섯이다.
+     * 그리고 `revision` 이 여기서 오르므로, 여기서 막지 않으면 **적지 않고도 판만 올라간다.**
+     *
+     * ── 무엇을 같다고 보나 ─────────────────────────────────────────────────────
+     * `data` 가 바이트까지 같으면 같다. 시각은 `data` 에 없다(여기서 붙인다) — 그래서 「같은 사실을
+     * 다른 시각에 다시 말한 것」이 정확히 걸러진다.
+     *
+     * `subject` 를 안 주면 거르지 않는다. 대상이 없는 사건(주의 등)은 반복 자체가 사실이다.
+     *
+     * 재기동하면 이 기억이 비므로 **첫 방출은 언제나 나간다** — 되세운 상태가 조용히 빠지지 않는다.
+     */
+    lastEmitted = new Map();
+    emitOp(eventType, data, subject) {
+        if (subject !== undefined) {
+            const key = `${eventType}\u0000${subject}`;
+            const json = JSON.stringify(data);
+            if (this.lastEmitted.get(key) === json)
+                return;
+            this.lastEmitted.set(key, json);
+        }
         this.revision++;
         const e = { eventId: `${this.tenantId}-evt-${++this.eventSeq}`, eventType, eventTime: this.now(), tenantId: this.tenantId, ...(this._correlationId ? { correlationId: this._correlationId } : {}), data };
         for (const h of this.handlers)
@@ -2852,14 +2896,14 @@ export class FlowEngine {
             ...(t.startTime ? { startTime: t.startTime } : {}),
             ...(t.endTime ? { endTime: t.endTime } : {}),
             ...(inProgress ? { remainingMs: t.remainingMs, startedAtSimMs: t.startedAtSimMs, progress: t.durationMs ? done / t.durationMs : undefined } : {})
-        });
+        }, t.id);
     }
     /** 사람 상태 전이 — 설비와 별개 채널(어휘가 다르다: 고장이 아니라 교대·투입). */
     emitAsset(a) {
-        this.emitOp(OP_EVENT.asset, { assetId: a.id, assetClassIds: a.assetClassIds, ...(a.ratedUsage ? { ratedUsage: a.ratedUsage } : {}), ...(a.usedUsage ? { usedUsage: a.usedUsage } : {}), status: a.status, location: a.location, taskId: a.taskId ?? undefined, carrying: a.carrying, ...effectiveOnly(a) });
+        this.emitOp(OP_EVENT.asset, { assetId: a.id, assetClassIds: a.assetClassIds, ...(a.ratedUsage ? { ratedUsage: a.ratedUsage } : {}), ...(a.usedUsage ? { usedUsage: a.usedUsage } : {}), status: a.status, location: a.location, taskId: a.taskId ?? undefined, carrying: a.carrying, ...effectiveOnly(a) }, a.id);
     }
     emitPerson(p) {
-        this.emitOp(OP_EVENT.person, { personId: p.id, personnelClassIds: p.personnelClassIds, status: p.status, taskId: p.taskId ?? undefined, ...(p.location ? { location: p.location } : {}), ...effectiveOnly(p) });
+        this.emitOp(OP_EVENT.person, { personId: p.id, personnelClassIds: p.personnelClassIds, status: p.status, taskId: p.taskId ?? undefined, ...(p.location ? { location: p.location } : {}), ...effectiveOnly(p) }, p.id);
         /* `offShift` 를 더 이상 실어 보내지 않는다 — 교대 경계는 **이벤트 없이 시각만으로** 넘어가므로
            전이 순간의 판정을 보내면 유휴로 경계를 지난 사람이 옛 값에 머문다. 미러는 같은 함수
            (`offCalendarAt`)를 자기 시각으로 부른다(유효 기간과 같은 규율). */
@@ -2867,7 +2911,7 @@ export class FlowEngine {
     /** 설비 상태 전이 — `taskId` 를 함께 싣는다(사람·자산 델타와 같은 규칙). 없으면 미러가 "이 설비가
      *  무슨 일을 하는 중인가" 를 알 수 없어 작업↔자원 연결이 한쪽에서만 성립한다. */
     emitEquipment(m, motion) {
-        this.emitOp(OP_EVENT.equipment, { moverId: m.id, kind: m.kind, ...(m.equipmentClassIds ? { equipmentClassIds: m.equipmentClassIds } : {}), status: m.status, location: m.location, ...(m.homeLocation ? { homeLocation: m.homeLocation } : {}), taskId: m.taskId ?? undefined, motion, ...(m.held ? { held: true } : {}), ...effectiveOnly(m) });
+        this.emitOp(OP_EVENT.equipment, { moverId: m.id, kind: m.kind, ...(m.equipmentClassIds ? { equipmentClassIds: m.equipmentClassIds } : {}), status: m.status, location: m.location, ...(m.homeLocation ? { homeLocation: m.homeLocation } : {}), taskId: m.taskId ?? undefined, motion, ...(m.held ? { held: true } : {}), ...effectiveOnly(m) }, m.id);
     }
     /** 오더 델타 — **라인까지 싣는다.** 라인이 빠지면 미러가 남은 데맨드를 라인별로 재계획할 수 없다. */
     emitOrder(o) {
@@ -2888,7 +2932,7 @@ export class FlowEngine {
             /* 약속해 둔 자리·시각창 — 이것이 빠져서 야드 트윈이 재기동마다 첫 틱에 죽었다(§dockDoor). */
             ...(o.dockDoor ? { dockDoor: o.dockDoor } : {}),
             ...(o.windowStartMs !== undefined ? { windowStartMs: o.windowStartMs } : {})
-        });
+        }, o.id);
     }
     // ── 내부 mechanics ─────────────────────────────────────────────────────────
     /**

package/dist-cjs/index.cjs

@@ -792,6 +792,7 @@ var ENERGY_EVENT = {
    */
   drSuggested: "energy.dr.suggested"
 };
+var MATERIAL_ACTUAL_USE = ["consumed", "produced"];
 var CMD = {
   orderHold: "order.hold",
   orderResume: "order.resume",
@@ -1574,13 +1575,23 @@ function objectUri(namespace, objId) {
 function bizTransactionUri(namespace, transId) {
   return underNamespace(namespace, "bt", transId);
 }
+var STRUCTURE_BREAKING = /[%/:?# ]/g;
+var PERCENT_ENCODED = {
+  "%": "%25",
+  "/": "%2F",
+  ":": "%3A",
+  "?": "%3F",
+  "#": "%23",
+  " ": "%20"
+};
 function underNamespace(namespace, marker, id) {
   const ns = namespace?.trim();
   if (!ns)
     return void 0;
-  const v = String(id);
-  if (!v || v.includes("/") || v.includes(":"))
+  const raw = String(id);
+  if (!raw)
     return void 0;
+  const v = raw.replace(STRUCTURE_BREAKING, (c) => PERCENT_ENCODED[c]);
   if (/^https?:\/\/[^/\s]+/.test(ns))
     return `${ns.replace(/\/+$/, "")}/${marker}/${v}`;
   if (/^urn:epc(global)?:/.test(ns))
@@ -1770,6 +1781,27 @@ var SPECS = {
       materialActual: "object[]",
       recordTime: "string"
     },
+    /*
+     * **자재 줄의 안쪽** — 계약의 `MaterialActual` 그대로다.
+     *
+     * `definitionId` 를 요구하는 이유: 이 이름이 없으면 그 줄이 무엇을 가리키는지 아무도 모른다.
+     * 실제로 `materialDefinitionId` 로 온 줄이 저널에 앉았고, 계약의 타입으로 읽으면 비어 있었다.
+     *
+     * `quantity` 를 `positive` 에 두는 이유: 「모른다」는 **비워서** 말한다. 0 으로 실으면 받는
+     * 쪽에서 「0개」와 구별되지 않고, 소요량 집계가 조용히 틀린다.
+     *
+     * `uom` 은 요구하지 않는다 — 계약에서 선택이다(§`MaterialActual`). ERP 경로는 요구하는데
+     * 그것은 **그 경로의 규칙**이다(정산에 단위 없는 수량을 쓸 수 없다). 커널이 그 규칙을 통째로
+     * 물려받으면 단위를 모르는 현장의 사실이 통째로 거절된다.
+     */
+    shapes: {
+      materialActual: {
+        required: ["definitionId", "use"],
+        fields: { definitionId: "string", lotId: "string", quantity: "number", uom: "string" },
+        enums: { use: MATERIAL_ACTUAL_USE },
+        positive: ["quantity"]
+      }
+    },
     enums: {
       status: TASK_STATUS,
       intent: ["transport", "process", "dwell"],
@@ -5718,7 +5750,50 @@ var FlowEngine = class {
   subjectOf(kind, localId) {
     return resolveSubject(kind, localId, { tenantId: this.tenantId, scopeId: this.scopeId, identityOf: (k, id) => k === "equipment" ? this.equipmentIdentity(id) : void 0 });
   }
-  emitOp(eventType, data) {
+  /**
+   * 운영 델타 방출 — **같은 사실을 다시 적지 않는다.**
+   *
+   * ── 무엇이 있었나 (2026-09-05 실측) ────────────────────────────────────────
+   * `flow-engine.ts` 의 배정 패스가 **매 틱** `created` 인 오더 전부에 `allocate` 를 건다. 자재가
+   * 모자란 오더는 그때마다 `mes-kernel` 의 「모자람을 적고 다음 틱에 다시 본다」 줄에 닿았고, 거기서
+   * **바뀐 것이 없어도 방출**했다.
+   *
+   *   hatio-mx2   오더 315개 → 세 시간에 order.status 2,433,116건 (오더당 7,700)
+   *   다른 트윈    오더당 1~2건
+   *   틱 로그      「journal 706.92ms(88%)」
+   *
+   * 다시 보는 것은 옳다(모자람은 채워질 수 있다). **다시 볼 때마다 적는 것**이 결함이다.
+   *
+   * ── 파급이 디스크가 아니다 ─────────────────────────────────────────────────
+   *   재기동      저널을 접어 상태를 세운다 — 되세우는 시간이 그만큼 는다
+   *   구독        이 사건들은 방송된다. 막힌 오더 × 매 틱 × 구독자 수
+   *   틱          시뮬 틱은 메인 이벤트 루프에서 돈다 — HTTP·구독이 함께 느려진다
+   *   지표        오더 사건을 세는 모든 것이 부푼다
+   *   진짜 문제   「오더가 자재를 못 구해 멈췄다」가 자기가 만든 소음에 묻힌다
+   *
+   * 가장 나쁜 것은 방향이다. **현장이 막힐수록 트윈이 더 무너진다** — 잘 흐르면 사건이 적고 막히면
+   * 폭증한다. 트윈이 가장 필요한 순간에 가장 약해진다.
+   *
+   * ── 왜 여기인가 ────────────────────────────────────────────────────────────
+   * 부르는 자리 하나를 막으면 다른 자리에서 같은 일이 난다 — `emitOrder` 를 부르는 곳만 열다섯이다.
+   * 그리고 `revision` 이 여기서 오르므로, 여기서 막지 않으면 **적지 않고도 판만 올라간다.**
+   *
+   * ── 무엇을 같다고 보나 ─────────────────────────────────────────────────────
+   * `data` 가 바이트까지 같으면 같다. 시각은 `data` 에 없다(여기서 붙인다) — 그래서 「같은 사실을
+   * 다른 시각에 다시 말한 것」이 정확히 걸러진다.
+   *
+   * `subject` 를 안 주면 거르지 않는다. 대상이 없는 사건(주의 등)은 반복 자체가 사실이다.
+   *
+   * 재기동하면 이 기억이 비므로 **첫 방출은 언제나 나간다** — 되세운 상태가 조용히 빠지지 않는다.
+   */
+  lastEmitted = /* @__PURE__ */ new Map();
+  emitOp(eventType, data, subject) {
+    if (subject !== void 0) {
+      const key = `${eventType}\0${subject}`;
+      const json = JSON.stringify(data);
+      if (this.lastEmitted.get(key) === json) return;
+      this.lastEmitted.set(key, json);
+    }
     this.revision++;
     const e = { eventId: `${this.tenantId}-evt-${++this.eventSeq}`, eventType, eventTime: this.now(), tenantId: this.tenantId, ...this._correlationId ? { correlationId: this._correlationId } : {}, data };
     for (const h of this.handlers) h(e);
@@ -5755,19 +5830,19 @@ var FlowEngine = class {
       ...t.startTime ? { startTime: t.startTime } : {},
       ...t.endTime ? { endTime: t.endTime } : {},
       ...inProgress ? { remainingMs: t.remainingMs, startedAtSimMs: t.startedAtSimMs, progress: t.durationMs ? done / t.durationMs : void 0 } : {}
-    });
+    }, t.id);
   }
   /** 사람 상태 전이 — 설비와 별개 채널(어휘가 다르다: 고장이 아니라 교대·투입). */
   emitAsset(a) {
-    this.emitOp(OP_EVENT.asset, { assetId: a.id, assetClassIds: a.assetClassIds, ...a.ratedUsage ? { ratedUsage: a.ratedUsage } : {}, ...a.usedUsage ? { usedUsage: a.usedUsage } : {}, status: a.status, location: a.location, taskId: a.taskId ?? void 0, carrying: a.carrying, ...effectiveOnly(a) });
+    this.emitOp(OP_EVENT.asset, { assetId: a.id, assetClassIds: a.assetClassIds, ...a.ratedUsage ? { ratedUsage: a.ratedUsage } : {}, ...a.usedUsage ? { usedUsage: a.usedUsage } : {}, status: a.status, location: a.location, taskId: a.taskId ?? void 0, carrying: a.carrying, ...effectiveOnly(a) }, a.id);
   }
   emitPerson(p) {
-    this.emitOp(OP_EVENT.person, { personId: p.id, personnelClassIds: p.personnelClassIds, status: p.status, taskId: p.taskId ?? void 0, ...p.location ? { location: p.location } : {}, ...effectiveOnly(p) });
+    this.emitOp(OP_EVENT.person, { personId: p.id, personnelClassIds: p.personnelClassIds, status: p.status, taskId: p.taskId ?? void 0, ...p.location ? { location: p.location } : {}, ...effectiveOnly(p) }, p.id);
   }
   /** 설비 상태 전이 — `taskId` 를 함께 싣는다(사람·자산 델타와 같은 규칙). 없으면 미러가 "이 설비가
    *  무슨 일을 하는 중인가" 를 알 수 없어 작업↔자원 연결이 한쪽에서만 성립한다. */
   emitEquipment(m, motion) {
-    this.emitOp(OP_EVENT.equipment, { moverId: m.id, kind: m.kind, ...m.equipmentClassIds ? { equipmentClassIds: m.equipmentClassIds } : {}, status: m.status, location: m.location, ...m.homeLocation ? { homeLocation: m.homeLocation } : {}, taskId: m.taskId ?? void 0, motion, ...m.held ? { held: true } : {}, ...effectiveOnly(m) });
+    this.emitOp(OP_EVENT.equipment, { moverId: m.id, kind: m.kind, ...m.equipmentClassIds ? { equipmentClassIds: m.equipmentClassIds } : {}, status: m.status, location: m.location, ...m.homeLocation ? { homeLocation: m.homeLocation } : {}, taskId: m.taskId ?? void 0, motion, ...m.held ? { held: true } : {}, ...effectiveOnly(m) }, m.id);
   }
   /** 오더 델타 — **라인까지 싣는다.** 라인이 빠지면 미러가 남은 데맨드를 라인별로 재계획할 수 없다. */
   emitOrder(o) {
@@ -5793,7 +5868,7 @@ var FlowEngine = class {
       /* 약속해 둔 자리·시각창 — 이것이 빠져서 야드 트윈이 재기동마다 첫 틱에 죽었다(§dockDoor). */
       ...o.dockDoor ? { dockDoor: o.dockDoor } : {},
       ...o.windowStartMs !== void 0 ? { windowStartMs: o.windowStartMs } : {}
-    });
+    }, o.id);
   }
   // ── 내부 mechanics ─────────────────────────────────────────────────────────
   /**

package/package.json

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