@operato/twin-kernel 0.4.2 → 0.4.3

package/dist/flow-engine.d.ts

@@ -376,6 +376,7 @@ export declare abstract class FlowEngine implements TwinKernel {
     /** 주목 신호가 **처음 성립한 시각**(id → ISO). 조건이 사라지면 지운다 — 재발은 새 시작이다. */
     private _attentionSince;
     dispatch(cmd: Command): CommandAck;
+    private dispatchInner;
     /** 도메인 커맨드 처리(order.release 등). 기본은 거절 — 도메인이 override. */
     protected handleCommand(cmd: Command): CommandAck;
     readonly scenario: ScenarioControl;
@@ -617,6 +618,17 @@ export declare abstract class FlowEngine implements TwinKernel {
     private oeeOf;
     /** 정책에 넘길 특정 타입 자리의 관측 뷰 — 예약(그 자리로 향하는 in-flight task) 포함. */
     protected slotViews(locationType: string): SlotView[];
+    /**
+     * 지금 처리 중인 커맨드의 상관값 — **디스패치 동안에만 있다.**
+     *
+     * 커맨드가 낳은 이벤트에 이 값을 실어야 "이 지시가 실제로 무엇을 일으켰나" 를 나중에 물을 수 있다.
+     * 그게 없으면 승인 기록은 "허락했다" 까지이고, 그 뒤 공장이 어떻게 움직였는지와 이어지지 않는다.
+     *
+     * **한계를 밝힌다**: 여기서 잇는 것은 그 자리에서 방출된 이벤트뿐이다. 나중 틱에 일어나는 후속
+     * (예: resourceDown 이 정한 수리 완료)은 시뮬 시간의 결과라 이어지지 않는다. 즉시 인과만 잇는다 —
+     * 먼 인과까지 같은 값으로 묶으면 "이 승인 때문"이라는 말이 사실보다 넓어진다.
+     */
+    private _correlationId?;
     protected emit(event: EpcisEvent): void;
     protected emitOp(eventType: string, data: unknown): void;
     /**

package/dist/flow-engine.js

@@ -546,6 +546,20 @@ export class FlowEngine {
     /** 주목 신호가 **처음 성립한 시각**(id → ISO). 조건이 사라지면 지운다 — 재발은 새 시작이다. */
     _attentionSince = new Map(); // 확인(ack)된 주목 신호 id — 조건 지속돼도 acknowledged 로 표시(재발 시 재활성)
     dispatch(cmd) {
+        /*
+         * 이 커맨드가 낳는 이벤트에 상관값을 단다. 명시값이 없으면 **commandId 를 쓴다** — 호출자가
+         * 따로 챙기지 않아도 모든 지시가 자기 결과와 이어진다(감사 기록이 commandId 를 이미 갖고 있다).
+         * finally 로 반드시 걷는다: 남겨 두면 그 뒤 틱에서 일어난 무관한 일까지 이 커맨드 탓이 된다.
+         */
+        this._correlationId = cmd.correlationId ?? cmd.commandId;
+        try {
+            return this.dispatchInner(cmd);
+        }
+        finally {
+            this._correlationId = undefined;
+        }
+    }
+    dispatchInner(cmd) {
         const ok = () => ({ commandId: cmd.commandId, accepted: true });
         // 거절 사유 = 언어 중립 코드 + 원시 파라미터. error 는 영어 폴백(로그·개발자용).
         const fail = (errorCode, errorParams) => ({ commandId: cmd.commandId, accepted: false, errorCode, errorParams, error: errorCode });
@@ -1282,15 +1296,26 @@ export class FlowEngine {
                 views.push({ id: n.id, capacity: n.capacity, occupancy: n.occupancy, reserved: reserved.get(n.id) ?? 0 });
         return views;
     }
+    /**
+     * 지금 처리 중인 커맨드의 상관값 — **디스패치 동안에만 있다.**
+     *
+     * 커맨드가 낳은 이벤트에 이 값을 실어야 "이 지시가 실제로 무엇을 일으켰나" 를 나중에 물을 수 있다.
+     * 그게 없으면 승인 기록은 "허락했다" 까지이고, 그 뒤 공장이 어떻게 움직였는지와 이어지지 않는다.
+     *
+     * **한계를 밝힌다**: 여기서 잇는 것은 그 자리에서 방출된 이벤트뿐이다. 나중 틱에 일어나는 후속
+     * (예: resourceDown 이 정한 수리 완료)은 시뮬 시간의 결과라 이어지지 않는다. 즉시 인과만 잇는다 —
+     * 먼 인과까지 같은 값으로 묶으면 "이 승인 때문"이라는 말이 사실보다 넓어진다.
+     */
+    _correlationId;
     emit(event) {
         this.revision++;
-        const e = { eventId: `${this.tenantId}-evt-${++this.eventSeq}`, eventType: `epcis.${event.type}`, eventTime: event.eventTime, tenantId: this.tenantId, data: event };
+        const e = { eventId: `${this.tenantId}-evt-${++this.eventSeq}`, eventType: `epcis.${event.type}`, eventTime: event.eventTime, tenantId: this.tenantId, ...(this._correlationId ? { correlationId: this._correlationId } : {}), data: event };
         for (const h of this.handlers)
             h(e);
     }
     emitOp(eventType, data) {
         this.revision++;
-        const e = { eventId: `${this.tenantId}-evt-${++this.eventSeq}`, eventType, eventTime: this.now(), tenantId: this.tenantId, data };
+        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);
     }

package/dist-cjs/index.cjs

@@ -2353,6 +2353,14 @@ var FlowEngine = class {
   _attentionSince = /* @__PURE__ */ new Map();
   // 확인(ack)된 주목 신호 id — 조건 지속돼도 acknowledged 로 표시(재발 시 재활성)
   dispatch(cmd) {
+    this._correlationId = cmd.correlationId ?? cmd.commandId;
+    try {
+      return this.dispatchInner(cmd);
+    } finally {
+      this._correlationId = void 0;
+    }
+  }
+  dispatchInner(cmd) {
     const ok = () => ({ commandId: cmd.commandId, accepted: true });
     const fail = (errorCode, errorParams) => ({ commandId: cmd.commandId, accepted: false, errorCode, errorParams, error: errorCode });
     switch (cmd.type) {
@@ -3014,14 +3022,25 @@ var FlowEngine = class {
     for (const n of this.locations.values()) if (n.type === locationType) views.push({ id: n.id, capacity: n.capacity, occupancy: n.occupancy, reserved: reserved.get(n.id) ?? 0 });
     return views;
   }
+  /**
+   * 지금 처리 중인 커맨드의 상관값 — **디스패치 동안에만 있다.**
+   *
+   * 커맨드가 낳은 이벤트에 이 값을 실어야 "이 지시가 실제로 무엇을 일으켰나" 를 나중에 물을 수 있다.
+   * 그게 없으면 승인 기록은 "허락했다" 까지이고, 그 뒤 공장이 어떻게 움직였는지와 이어지지 않는다.
+   *
+   * **한계를 밝힌다**: 여기서 잇는 것은 그 자리에서 방출된 이벤트뿐이다. 나중 틱에 일어나는 후속
+   * (예: resourceDown 이 정한 수리 완료)은 시뮬 시간의 결과라 이어지지 않는다. 즉시 인과만 잇는다 —
+   * 먼 인과까지 같은 값으로 묶으면 "이 승인 때문"이라는 말이 사실보다 넓어진다.
+   */
+  _correlationId;
   emit(event) {
     this.revision++;
-    const e = { eventId: `${this.tenantId}-evt-${++this.eventSeq}`, eventType: `epcis.${event.type}`, eventTime: event.eventTime, tenantId: this.tenantId, data: event };
+    const e = { eventId: `${this.tenantId}-evt-${++this.eventSeq}`, eventType: `epcis.${event.type}`, eventTime: event.eventTime, tenantId: this.tenantId, ...this._correlationId ? { correlationId: this._correlationId } : {}, data: event };
     for (const h of this.handlers) h(e);
   }
   emitOp(eventType, data) {
     this.revision++;
-    const e = { eventId: `${this.tenantId}-evt-${++this.eventSeq}`, eventType, eventTime: this.now(), tenantId: this.tenantId, data };
+    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);
   }
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operato/twin-kernel",
-  "version": "0.4.2",
+  "version": "0.4.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": {