@operato/twin-kernel 0.7.61 → 0.7.63

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) — **사람이 한 행위**라 파생될 수 없다.
    *
@@ -1394,7 +1415,7 @@ var ObservedReducer = class {
   corrections = [];
   /** 반영하지 못한 사건의 종류별 집계 — 원문은 쌓지 않는다(저널에 이미 있다). */
   unhandled = /* @__PURE__ */ new Map();
-  /** 선언된 판정 기준(보드에서 한 번 읽는다) — 판정은 선언한 것에만 걸린다. */
+  /** 선언된 판정 기준(트윈 모델에서 한 번 읽는다) — 판정은 선언한 것에만 걸린다. */
   testSpecs = /* @__PURE__ */ new Map();
   /**
    * 자원별 **교대 선언** — 미러가 "지금 근무 중인가" 를 스스로 판정하기 위한 재료.
@@ -1410,7 +1431,7 @@ var ObservedReducer = class {
    * 통과시키는 어긋남이 생기고, 그 어긋남은 조용하다.
    */
   classDefs = {};
-  /** 시각 해석 기준(보드 선언) — 없으면 UTC. 캘린더의 `HH:MM` 이 어느 기준인지 정한다. */
+  /** 시각 해석 기준(트윈 모델 선언) — 없으면 UTC. 캘린더의 `HH:MM` 이 어느 기준인지 정한다. */
   utcOffsetMinutes;
   constructor(model) {
     this.utcOffsetMinutes = model.utcOffsetMinutes;
@@ -1514,7 +1535,7 @@ var ObservedReducer = class {
    * 종류는 모르므로 `unknown`, **용량은 비워 둔다**(발명하지 않는다), 출처는 `observed`.
    *
    * 출처를 표시하는 이유: 소비처가 "마스터가 말한 자리" 와 "관측으로 알게 된 자리" 를 구별해야 한다
-   * (보드에 좌표가 없고, 용량을 채워야 계획에 참여한다). 마스터 동기가 오면 `master` 로 승격된다.
+   * (트윈 모델에 좌표가 없고, 용량을 채워야 계획에 참여한다). 마스터 동기가 오면 `master` 로 승격된다.
    */
   touchLocation(id) {
     if (!id || this.master.has(id)) return;
@@ -1568,6 +1589,8 @@ var ObservedReducer = class {
         if (this.stale(`task:${d.taskId}`, e)) return;
         this.touchLocation(d.fromNode);
         this.touchLocation(d.toNode);
+        const prevTask = this.tasks.get(d.taskId);
+        const keptActual = d.materialActual === void 0 ? prevTask?.materialActual : void 0;
         this.tasks.set(d.taskId, {
           id: d.taskId,
           kind: d.kind,
@@ -1585,8 +1608,9 @@ var ObservedReducer = class {
           ...d.personnel?.length ? { personnel: d.personnel.slice() } : {},
           ...d.assets?.length ? { assets: d.assets.slice() } : {},
           ...d.resources?.length ? { resources: d.resources.slice() } : {},
-          /* 실제 자재 이동 — 인원·설비와 같은 채널로 온다(실적을 한 곳에서 읽는다). */
-          ...d.materialActual?.length ? { materialActual: d.materialActual.map((r) => ({ ...r })) } : {},
+          /* 실제 자재 이동 — 인원·설비와 같은 채널로 온다(실적을 한 곳에서 읽는다).
+             말하지 않았으면 **앞의 것을 지킨다**(위 주석) — 빈 배열은 「지웠다」로 말한 것이다. */
+          ...d.materialActual?.length ? { materialActual: d.materialActual.map((r) => ({ ...r })) } : keptActual?.length ? { materialActual: keptActual.map((r) => ({ ...r })) } : {},
           ...d.priority !== void 0 ? { priority: d.priority } : {},
           ...d.startTime ? { startTime: d.startTime } : {},
           ...d.endTime ? { endTime: d.endTime } : {}
@@ -1665,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);
@@ -1809,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;
@@ -1817,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 ?? []) {
@@ -1825,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);
       }
     }
   }
@@ -2062,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) })),
@@ -4078,7 +4142,7 @@ var FlowEngine = class {
   materialSpecCrossKeyOverlaps = 0;
   observedDirty = false;
   observeMode = false;
-  /** 관측 구동이 투영기를 세울 때 필요한 원본 보드(구조는 이벤트가 아니라 마스터에서 온다). */
+  /** 관측 구동이 투영기를 세울 때 필요한 원본 트윈 모델(구조는 이벤트가 아니라 마스터에서 온다). */
   boardDef;
   /** 명세 소비 기록 — 무엇을 선언값으로, 무엇을 기본값으로 계산했나(정직한 자기보고). */
   specUse = /* @__PURE__ */ new Map();
@@ -4360,7 +4424,7 @@ var FlowEngine = class {
         /* 계획 정지를 이어받는다 — 잃으면 씨앗이 **정비 중인 설비를 가용으로 놓고** 미래를 시뮬레이션한다
            (예측이 낙관 쪽으로 치우친다). 씨앗 왕복 대조가 이것을 잡았다. */
         ...m.held ? { held: true } : {},
-        /* 관측 스냅샷이 들고 있는 것은 관측을 따른다(미러가 보드에서 읽어 실어 온다). */
+        /* 관측 스냅샷이 들고 있는 것은 관측을 따른다(미러가 트윈 모델에서 읽어 실어 온다). */
         ...m.properties ? { properties: m.properties } : {},
         ...m.testSpecificationIds ? { testSpecificationIds: m.testSpecificationIds } : {},
         /* 결과도 이어받는다 — 잃으면 예측이 **자격 만료를 모르는 현장**에서 출발한다(낙관 쪽으로 치우친다). */
@@ -4775,7 +4839,7 @@ var FlowEngine = class {
         ...this.seedDanglingRefs ? { seedDanglingRefs: this.seedDanglingRefs } : {},
         ...this.materialSpecCrossKeyOverlaps ? { materialSpecCrossKeyOverlaps: this.materialSpecCrossKeyOverlaps } : {}
       } } : {},
-      /* 출처 표시 — 보드(마스터)에서 온 자리다. 미러는 관측으로 알게 된 자리를 'observed' 로 구별하는데,
+      /* 출처 표시 — 트윈 모델(마스터)에서 온 자리다. 미러는 관측으로 알게 된 자리를 'observed' 로 구별하는데,
        * 시뮬이 아무 표시도 안 하면 소비처가 두 스냅샷을 같은 규칙으로 읽지 못한다. */
       locations: [...this.locations.values()].map((n) => {
         const { status, ...rest } = n;
@@ -6485,7 +6549,7 @@ var FlowEngine = class {
   /**
    * 시뮬 시각의 분(0..1439) — 캘린더 판정의 기준.
    *
-   * **보드가 선언한 기준으로 읽는다**(`utcOffsetMinutes`). 예전에는 UTC 로 읽어서 Rosarito(UTC−7)의
+   * **트윈 모델이 선언한 기준으로 읽는다**(`utcOffsetMinutes`). 예전에는 UTC 로 읽어서 Rosarito(UTC−7)의
    * 06시 교대가 7시간 틀렸다 — 시각대만 적고 기준을 안 적으면 반드시 이렇게 된다.
    */
   minuteOfDay() {
@@ -9030,6 +9094,46 @@ var SPECS = {
       recordTime: "string"
     },
     enums: { result: ["pass", "fail"] }
+  },
+  /*
+   * **자리의 물리 관측** — 어느 자리의 어느 속성을 언제 얼마로 쟀나.
+   *
+   * 값에 **단위를 함께** 받는다(`ValueType`). 단위 없는 물리량은 판정의 재료가 못 된다 — 3 이 섭씨인지
+   * 화씨인지 모르면 어떤 기준으로도 판정할 수 없다. 다만 **요구하지는 않는다**: 단위를 비우는 실 원본이
+   * 흔하고, 요구하면 그 원본의 관측을 아예 담지 못한다(그때 판정은 커널이 거부한다 — `outsideLimit`).
+   *
+   * `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",
+    /* 자리와 속성 — 둘 중 하나가 없으면 그 관측은 아무 데도 붙지 못한다. */
+    required: ["locationId", "propertyId"],
+    fields: {
+      locationId: "string",
+      propertyId: "string",
+      value: "string",
+      dataType: "string",
+      uom: "string",
+      effectiveTime: "string",
+      effectiveEndTime: "string",
+      recordTime: "string",
+      source: "string",
+      derived: "boolean"
+    }
   }
 };
 function operationalKindOf(record) {
@@ -9043,6 +9147,8 @@ function operationalKindOf(record) {
   if (has("taskId")) return "task";
   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) {
@@ -9353,13 +9459,13 @@ var VOCABULARY_EXCEPTIONS = [
   { token: "moverId", why: "journal wire field \u2014 renaming would mix two keys for one fact across history" },
   { token: "fromNode", why: "journal wire field (task.status payload)" },
   { token: "toNode", why: "journal wire field (task.status payload)" },
-  /* ── 보드의 옛 세대 키 — 저장된 데이터라 읽어는 줘야 한다 ────────────────
+  /* ── 트윈 모델의 옛 세대 키 — 저장된 데이터라 읽어는 줘야 한다 ────────────────
    * 설비 배열의 이름은 세 세대를 거쳤다(movers → equipmentList → equipment). 저장된 보드에는
-   * 셋이 섞여 있고(실측 23개 중 13개가 `movers`), 하나라도 안 읽으면 그 보드는 **설비가 0인 공장**
+   * 셋이 섞여 있고(실측 23개 중 13개가 `movers`), 하나라도 안 읽으면 그 트윈 모델은 **설비가 0인 공장**
    * 으로 조용히 읽힌다 — 화면의 설비 수가 0이 되고 용량 판정에서 자원이 사라진다. 쓰는 곳은
    * `readBoardEquipment` 한 곳뿐이고, 거기서 새 이름으로 정규화해 내보낸다. */
   { token: "movers", why: "legacy board key (movers \u2192 equipmentList \u2192 equipment); read-only normalization in readBoardEquipment, 13 stored boards still use it" },
-  /* ── 씬 컴포넌트 타입 — 보드에 저장된 값이고, 뜻이 어긋나지도 않는다 ──────
+  /* ── 씬 컴포넌트 타입 — 트윈 모델에 저장된 값이고, 뜻이 어긋나지도 않는다 ──────
    * 보드 7개가 이 타입으로 컴포넌트를 담고 있어 개명하면 그 컴포넌트가 조용히 안 그려진다.
    * 그리고 씬에서 이 이름은 자원이 아니라 **움직임 표현**을 가리킨다(표준과 충돌 아님). */
   { token: "twin-mover", why: "scene component type persisted in boards; names a motion representation, not a resource" },

package/package.json

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