@operato/twin-kernel 0.7.54 → 0.7.56

package/dist-cjs/index.cjs

@@ -96,6 +96,7 @@ __export(index_exports, {
   constantDuration: () => constantDuration,
   conversionFactorOf: () => conversionFactorOf,
   counterfactualAt: () => counterfactualAt,
+  criterionSaysNothing: () => criterionSaysNothing,
   demandWindowStart: () => demandWindowStart,
   deriveAttentions: () => deriveAttentions,
   documentPath: () => documentPath,
@@ -142,10 +143,12 @@ __export(index_exports, {
   monteCarloForecastAsync: () => monteCarloForecastAsync,
   objectEvent: () => objectEvent,
   objectUri: () => objectUri,
+  observationAt: () => observationAt,
   offCalendarAt: () => offCalendarAt,
   offCalendarReasonAt: () => offCalendarReasonAt,
   operationalKindOf: () => operationalKindOf,
   operationsCapabilityOf: () => operationsCapabilityOf,
+  outsideLimit: () => outsideLimit,
   parseEpc: () => parseEpc,
   parseIsoDuration: () => parseIsoDuration,
   partialFitPolicy: () => partialFitPolicy,
@@ -290,6 +293,28 @@ function meetsTests(required, results, at) {
   }
   return true;
 }
+function criterionSaysNothing(c) {
+  if (c?.expression?.trim()) return false;
+  const l = c?.limit;
+  return !(typeof l?.minimum === "number" || typeof l?.maximum === "number");
+}
+function outsideLimit(criterion, observed) {
+  const l = criterion?.limit;
+  if (!l) return void 0;
+  const hasMin = typeof l.minimum === "number";
+  const hasMax = typeof l.maximum === "number";
+  if (!hasMin && !hasMax) return void 0;
+  const raw = observed?.value;
+  if (raw === void 0 || raw === null || String(raw).trim() === "") return void 0;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return void 0;
+  const lu = l.uom?.trim();
+  const ou = observed?.uom?.trim();
+  if (lu && ou && lu !== ou) return void 0;
+  if (hasMin && n < l.minimum) return true;
+  if (hasMax && n > l.maximum) return true;
+  return false;
+}
 function testEvidenceGaps(spec, result) {
   const criteria = spec?.criteria ?? [];
   const measurements = result?.propertyMeasurements ?? [];
@@ -532,6 +557,26 @@ function capabilityOf(r, ctx) {
   if (r.status && r.status !== "idle" && r.status !== "available") return { available: false, reason: "working" };
   return { available: true, reason: "available" };
 }
+function observationAt(observations, propertyId, at) {
+  const t = parsedMs(at);
+  if (!(t >= 0)) return void 0;
+  let best;
+  let bestStart = -1;
+  for (const o of observations ?? []) {
+    if (o.propertyId !== propertyId) continue;
+    const from = parsedMs(o.effectiveTime);
+    if (!(from >= 0) || from > t) continue;
+    if (o.effectiveEndTime) {
+      const to = parsedMs(o.effectiveEndTime);
+      if (to >= 0 && to < t) continue;
+    }
+    if (from > bestStart) {
+      best = o;
+      bestStart = from;
+    }
+  }
+  return best;
+}
 var OP_EVENT = {
   task: "task.status",
   equipment: "equipment.status",
@@ -554,7 +599,19 @@ var OP_EVENT = {
    * "확인해라"(요청)이고 이벤트는 "확인했다"(사실)다. 같은 문자열을 쓰면 저널에서 요청과 사실이
    * 구별되지 않는다.
    */
-  attentionAck: "attention.acked"
+  attentionAck: "attention.acked",
+  /**
+   * **자리에서 관측된 물리량** — 냉장실 온도·습도, 세척수 유량 같은 것(§`LocationObservation`).
+   *
+   * ── 왜 채널이 필요한가 ────────────────────────────────────────────────────
+   * `LocationState.observations` 를 상태에 두었는데 그것을 낳는 사건이 없었다. 그러면 **상태 ⊆ 이벤트**
+   * 가 깨진다: 채워도 재기동에서 사라지고, 폴드가 되살릴 수 없고, 미러가 이어받을 수도 없다. 상태에만
+   * 있는 축은 조용히 사라지는 축이다.
+   *
+   * 이름을 `energy.measured` 와 같은 결로 둔다 — 그쪽이 에너지 계량의 도착이고 이쪽이 그 일반형이다.
+   * 두 채널을 합치지 않는 이유는 에너지 쪽이 **구간에 누적되는 표본**이라 처리가 다르기 때문이다.
+   */
+  observation: "location.measured"
 };
 var ENERGY_EVENT = {
   /** 계량 도착 — 그 시점의 유효전력·누적량. 15분 수요 구간에 누적된다. */
@@ -825,13 +882,16 @@ function clockOf2(twin) {
 function monteCarloForecast(twin, opts) {
   const now = clockOf2(twin);
   const samples = [];
+  let gaps = 0;
   for (let i = 0; i < opts.runs; i++) {
     const { fc, step, target } = startRun(twin, opts, now, i);
     let guard = 0;
     while (clockOf2(fc) < target && guard++ < 1e6) fc.tick(step);
-    samples.push(opts.metric(fc.getSnapshot()));
+    const snap = fc.getSnapshot();
+    gaps = Math.max(gaps, snap.stepsWithoutMaterial ?? 0);
+    samples.push(opts.metric(snap));
   }
-  return summarize(opts.runs, samples);
+  return summarize(opts.runs, samples, gaps);
 }
 function startRun(twin, opts, nowMs, i) {
   const fc = twin.fork();
@@ -844,6 +904,7 @@ async function monteCarloForecastAsync(twin, opts) {
   const yieldFn = opts.yieldFn ?? (() => Promise.resolve());
   const everyTicks = Math.max(1, opts.yieldEveryTicks ?? 50);
   const samples = [];
+  let gaps = 0;
   for (let i = 0; i < opts.runs; i++) {
     const { fc, step, target } = startRun(twin, opts, now, i);
     let guard = 0;
@@ -855,16 +916,28 @@ async function monteCarloForecastAsync(twin, opts) {
         await yieldFn();
       }
     }
-    samples.push(opts.metric(fc.getSnapshot()));
+    const snap = fc.getSnapshot();
+    gaps = Math.max(gaps, snap.stepsWithoutMaterial ?? 0);
+    samples.push(opts.metric(snap));
     if (i < opts.runs - 1) await yieldFn();
   }
-  return summarize(opts.runs, samples);
+  return summarize(opts.runs, samples, gaps);
 }
-function summarize(runs, samples) {
+function summarize(runs, samples, stepsWithoutMaterial = 0) {
   const sorted = [...samples].sort((a, b) => a - b);
   const pct = (p) => sorted[Math.min(sorted.length - 1, Math.floor(p * sorted.length))];
   const mean = samples.reduce((a, b) => a + b, 0) / (samples.length || 1);
-  return { runs, samples, min: sorted[0], max: sorted[sorted.length - 1], mean, p50: pct(0.5), p90: pct(0.9) };
+  return {
+    runs,
+    samples,
+    min: sorted[0],
+    max: sorted[sorted.length - 1],
+    mean,
+    p50: pct(0.5),
+    p90: pct(0.9),
+    /* 0 은 싣지 않는다 — 「구멍이 없다」와 「이 축을 모른다」를 화면이 구별할 수 있게. */
+    ...stepsWithoutMaterial > 0 ? { stepsWithoutMaterial } : {}
+  };
 }
 
 // src/twin-observer.ts
@@ -910,14 +983,75 @@ var DISP = {
   sellable: "urn:epcglobal:cbv:disp:sellable_accessible",
   reserved: "urn:epcglobal:cbv:disp:reserved",
   in_transit: "urn:epcglobal:cbv:disp:in_transit",
-  non_sellable: "urn:epcglobal:cbv:disp:non_sellable_other"
+  non_sellable: "urn:epcglobal:cbv:disp:non_sellable_other",
   // 불량/scrap
+  /**
+   * **기한이 지났다** — CBV `expired`.
+   *
+   * ── 왜 `non_sellable` 로 접지 않나 (2026-08-24) ─────────────────────────────
+   * 커널의 `non_sellable` 은 CBV 의 `non_sellable_other`, 즉 **「그 밖의 이유」**다. 기한 지남을 거기
+   * 넣으면 「기한이 지나 못 판다」와 「깨져서 못 판다」가 같은 값이 되고, 화면은 회수·폐기의 사유를
+   * 구별할 수 없다. 식품에서 그 둘은 다른 조치다.
+   *
+   * 그리고 표준에 **정확한 낱말이 있다** — 접는 것은 있는 낱말을 버리는 것이다.
+   *
+   * ── 기한 날짜와 다른 축이다 ────────────────────────────────────────────────
+   * `ItemState.expiry` 는 **날짜**이고 이것은 **상태**다. 날짜가 있으면 「지났나」는 파생이지만, 원본이
+   * 「기한 지남」을 상태로 선언하는 시스템이 있다 — 그때 이 값은 관측이다.
+   *
+   * 둘이 어긋나면(날짜는 남았는데 상태가 지남, 또는 그 반대) **어느 쪽이 맞다고 정하지 않는다** —
+   * 아직 그 판정을 세울 근거가 없다. 어긋남의 구분을 없애지 않는 것이 지금의 규율이다.
+   *
+   * ── 원문으로 확인했다 (2026-08-24) ────────────────────────────────────────
+   * 1차 출처: **CBV Standard Release 2.0, Ratified Jun 2022** §7.2.3 처분 값 표(38개). 이 객체의
+   * 다른 값들(`in_progress`·`sellable_accessible`·`reserved`·`in_transit`·`non_sellable_other`)도
+   * 그 표에 있다.
+   *
+   * **`non_sellable_expired` 를 쓰지 않는 이유**: 그 값은 CBV 1.0 의 것이고 표준이 **폐기**했다 —
+   * 「deprecated in favour of new disposition values expired, damaged, disposed, … introduced in
+   * CBV 1.1」. 폐기된 값을 쓰면 새 소비처가 읽지 못한다.
+   *
+   * 참고: GS1 어휘 등록처(`ref.gs1.org/cbv/…`)로는 확인할 수 없었다 — **없는 값에도 같은 응답**을
+   * 준다(지어낸 값의 JSON-LD 가 실재 값과 바이트까지 같았다). 그 경로를 근거로 삼지 말 것.
+   */
+  expired: "urn:epcglobal:cbv:disp:expired",
+  /**
+   * **검사에 합격했다 / 불합격했다** — CBV `conformant` / `non_conformant`.
+   *
+   * 1차 출처(CBV 2.0 §7.2.3) 정의 그대로다.
+   *
+   *   conformant       Outcome of a successful/passed inspection in an inspecting or repairing step
+   *   non_conformant   Outcome of an unsuccessful/failed inspection in an inspecting or repairing step
+   *
+   * ── 왜 시험 결과 축을 자원에 더하지 않고 이것을 쓰나 (2026-08-24) ────────────
+   * 로트의 검사 판정을 담을 자리를 찾다가 `ItemState.testResults` 를 더하려 했다. 그런데 표준은 그
+   * 사실을 **이미 처분으로 말한다**: `bizStep: inspecting` 사건에 이 처분이 붙는다.
+   *
+   * 처분을 쓰면 두 가지가 공짜로 성립한다.
+   *   ① **상태 ⊆ 이벤트** — 처분은 이미 사건에서 온다. 상태에만 있는 축을 만들지 않는다
+   *   ② **운영에 곧 닿는다** — 「이 자재를 쓸 수 있나」가 처분으로 답해진다(판정을 따로 읽지 않는다)
+   *
+   * 시험의 **자세한 내용**(어느 명세로, 무엇을 재어)은 다른 물음이고, 표준은 그것을 `TestResult` 로
+   * 두며 결과가 대상을 가리킨다(`TestableObjectID`) — 대상이 결과를 들지 않는다. 그 축이 필요해지면
+   * 그때 열되, **판정 자체는 여기서 끝난다.**
+   */
+  conformant: "urn:epcglobal:cbv:disp:conformant",
+  non_conformant: "urn:epcglobal:cbv:disp:non_conformant"
 };
 var CBV_BIZSTEP = {
   /** 공정에 자재가 들어갔다 — ISA-95 `MaterialUse: Consumed`. */
   consuming: "urn:epcglobal:cbv:bizstep:consuming",
   /** 새 물품이 생겨 계보가 시작된다 — ISA-95 `MaterialUse: Produced`. */
-  commissioning: "urn:epcglobal:cbv:bizstep:commissioning"
+  commissioning: "urn:epcglobal:cbv:bizstep:commissioning",
+  /**
+   * **검사** — CBV `inspecting`. 1차 출처(CBV 2.0) 정의: 「Process of reviewing objects to address
+   * potential physical or documentation defects」이고, 「표본과 달리 검사된 대상은 그대로 남는다」고
+   * 이어진다(즉 검사는 물건을 소비하지 않는다).
+   *
+   * 이 단계에 `DISP.conformant`/`DISP.non_conformant` 가 붙어 판정이 처분으로 남는다 — 입고검수·
+   * 공정 중 검사가 그 모양이다.
+   */
+  inspecting: "urn:epcglobal:cbv:bizstep:inspecting"
 };
 function ssccUri(companyPrefix, serial) {
   return `urn:epc:id:sscc:${companyPrefix}.${String(serial).padStart(10, "0")}`;
@@ -1195,6 +1329,8 @@ function effectiveOf(r) {
 var ObservedReducer = class {
   /** 로케이션 마스터 — 출처를 함께 들고 있다(마스터가 말한 자리 vs 관측으로 알게 된 자리). */
   master = /* @__PURE__ */ new Map();
+  /** 자리별 · 속성별 **마지막 관측** — 이력이 아니다(§`OP_EVENT.observation`). */
+  observations = /* @__PURE__ */ new Map();
   items = /* @__PURE__ */ new Map();
   aggregation = /* @__PURE__ */ new Map();
   /** 아직 관측되지 않은 자식의 담김 — 물품을 지어내지 않고 보류했다가 등장할 때 붙인다. */
@@ -1463,6 +1599,16 @@ var ObservedReducer = class {
         this.touchLocation(d.location);
         break;
       }
+      case OP_EVENT.observation: {
+        const d = e.data;
+        if (!d?.locationId || !d?.propertyId) break;
+        if (this.stale(`observation:${d.locationId}:${d.propertyId}`, e)) return;
+        this.touchLocation(d.locationId);
+        const bin = this.observations.get(d.locationId) ?? /* @__PURE__ */ new Map();
+        bin.set(d.propertyId, { ...d });
+        this.observations.set(d.locationId, bin);
+        break;
+      }
       case OP_EVENT.attentionAck: {
         const d = e.data;
         if (d?.id) this.acked.add(d.id);
@@ -1785,6 +1931,8 @@ var ObservedReducer = class {
    */
   serialize() {
     return {
+      /* 관측도 재개점에 든다 — 없으면 이어 접기가 그 축을 0부터 다시 만든다. */
+      observations: [...this.observations.entries()].map(([id, bin]) => ({ id, values: [...bin.values()] })),
       revision: this.revision,
       master: [...this.master.values()].map((n) => ({ ...n })),
       items: [...this.items.values()].map((i) => ({ ...i })),
@@ -1809,6 +1957,9 @@ var ObservedReducer = class {
    * 모델에서 오는 판정 입력(교대·등급·시간대)은 생성자가 이미 세웠으므로 건드리지 않는다.
    */
   restore(cp) {
+    this.observations = new Map(
+      (cp?.observations ?? []).map((o) => [o.id, new Map((o.values ?? []).map((v) => [v.propertyId, { ...v }]))])
+    );
     this.revision = cp?.revision ?? 0;
     this.master = new Map((cp?.master ?? []).map((n) => [n.id, { ...n }]));
     this.items = new Map((cp?.items ?? []).map((i) => [i.epc, { ...i }]));
@@ -1844,6 +1995,11 @@ var ObservedReducer = class {
           ...n.capacity === void 0 ? {} : { capacity: n.capacity },
           ...n.parallelism === void 0 ? {} : { parallelism: n.parallelism },
           ...n.parentId ? { parentId: n.parentId } : {},
+          /* 관측된 물리량 — 없으면 **키를 만들지 않는다**(빈 배열은 「센서가 없다」와 「못 들었다」를 같게 만든다). */
+          ...(() => {
+            const bin = this.observations.get(n.id);
+            return bin?.size ? { observations: [...bin.values()] } : {};
+          })(),
           origin: n.origin
         };
       }),
@@ -3360,6 +3516,34 @@ function deriveAttentions(view, acked, nowIso, thresholds) {
     }
   }
   for (const n of view.locations) {
+    for (const c of n.criteria ?? []) {
+      const propertyId = c.evaluatedPropertyId;
+      if (!propertyId) continue;
+      const observed = (n.observations ?? []).find((o) => o.propertyId === propertyId);
+      if (!observed) continue;
+      if (outsideLimit(c, observed) !== true) continue;
+      out.push({
+        /* 자리·기준마다 하나 — 같은 방의 온도와 습도가 한 신호로 뭉치지 않는다. */
+        id: `observation-out-of-limit:${n.id}:${c.id}`,
+        kind: "observation-out-of-limit",
+        severity: "high",
+        anchor: { locationId: n.id },
+        /* 언어중립 원시값만 — 문장은 표현계층이 kind 로 골라 렌더한다. */
+        params: {
+          locationId: n.id,
+          criterionId: c.id,
+          propertyId,
+          /* 값이 없으면 판정이 서지 않으므로 여기 오지 않는다 — 그래도 타입을 좁혀 둔다. */
+          value: observed.value ?? "",
+          ...observed.uom ? { uom: observed.uom } : {},
+          ...c.limit?.minimum !== void 0 ? { minimum: c.limit.minimum } : {},
+          ...c.limit?.maximum !== void 0 ? { maximum: c.limit.maximum } : {},
+          /* **언제의 값인가** — 4개월 전 값으로 지금을 판정한 것인지 소비처가 알아야 한다. */
+          effectiveTime: observed.effectiveTime,
+          ...observed.derived ? { derived: "true" } : {}
+        }
+      });
+    }
     if ((n.capacity ?? 0) > 0) {
       const r = (n.occupancy ?? 0) / n.capacity;
       const declaredPct = thresholds?.congestionPctOf?.(n.id);
@@ -3740,6 +3924,47 @@ var FlowEngine = class {
   localParams = /* @__PURE__ */ new Map();
   /** 관측 구동(P0) — 이벤트를 접는 투영기와 그 사실. tick 과 섞이지 않게 명시적으로 들고 있다. */
   observer;
+  /**
+   * **관측 리듀서의 재개점을 꺼낸다** — 호스트가 저장해 다음 기동에서 되돌릴 수 있게.
+   *
+   * ── 무엇이 문제였나 (2026-08-24 실측) ──────────────────────────────────────
+   * 미러는 재기동마다 저널을 **0부터** 다시 집계했다. 실측으로 저널이 2,960만 줄이고, 그 때문에 기동
+   * 직후 몇 분간 상태가 비어 있었다. 계측처럼 경계 없이 자라는 흐름이 들어오면 그 몇 분이 몇십 분이
+   * 된다 — 불편이 아니라 벽이다.
+   *
+   * 재개점 자체는 오래전부터 있었다(`serialize`/`restore`). 조회 경로는 그것을 쓰는데
+   * (`replayFrom`) **라이브 경로에는 꺼낼 문이 없었다.** 그래서 호스트가 저장할 수 없었다.
+   *
+   * ── 상태 스냅샷으로는 대신할 수 없다 ──────────────────────────────────────
+   * 리듀서는 소비처가 보는 값 말고도 든다: 부모를 기다리는 담김·집계 중인 수량·담을 줄 몰라 세어 둔
+   * 사건. 상태만 되돌리고 이어 집계하면 **0부터 집계한 결과와 조용히 달라진다**(§`ReducerCheckpoint`).
+   *
+   * 관측 구동이 아니면 `undefined` — 시뮬은 리듀서를 갖지 않는다(저장할 것이 없다).
+   */
+  observedCheckpoint() {
+    return this.observer?.serialize();
+  }
+  /**
+   * **재개점에서 관측 리듀서를 되세운다** — 저널을 0부터 다시 집계하지 않게.
+   *
+   * 리듀서가 아직 없으면 만든다: 미러는 첫 봉투가 올 때 리듀서를 만드는데(§`apply`), 되돌리기는 그보다
+   * 먼저 일어나야 한다(그러지 않으면 첫 봉투가 빈 리듀서를 만들고 되돌린 것을 덮는다).
+   *
+   * 되돌린 뒤 상태로 옮긴다 — 그러지 않으면 첫 스냅샷이 빈 상태를 보인다.
+   *
+   * **구조가 다르면 되돌리지 않는다**: 재개점은 그 모델 위에서 만들어진 것이고, 다른 공장의 재개점을
+   * 얹으면 없는 자리·설비가 생긴다. 판단은 부르는 쪽이 한다(`structureRev` 를 아는 것은 호스트다) —
+   * 여기서는 받은 것을 그대로 세운다.
+   */
+  restoreObserved(cp) {
+    if (!this.observer) {
+      this.observer = new ObservedReducer(this.boardDef ?? { locations: [], equipment: [] });
+      this.observeMode = true;
+    }
+    this.observer.restore(cp);
+    this.observedDirty = true;
+    this.settleObserved();
+  }
   /**
    * 이 커널의 상태가 **관측에서 왔나** — 미러인가.
    *
@@ -4639,10 +4864,23 @@ var FlowEngine = class {
    */
   collectAttentions() {
     const now = this.now();
+    const specById = new Map((this.boardDef?.testSpecifications ?? []).map((sp) => [sp.id, sp]));
+    const criteriaOf = /* @__PURE__ */ new Map();
+    if (specById.size) {
+      for (const n of readBoardLocations(this.boardDef ?? {})) {
+        const ids = n.testSpecificationIds;
+        if (!ids?.length) continue;
+        const cs = ids.flatMap((id) => specById.get(id)?.criteria ?? []);
+        if (cs.length) criteriaOf.set(n.id, cs);
+      }
+    }
     const out = deriveAttentions(
       {
         equipment: [...this.equipment.values()],
-        locations: [...this.locations.values()],
+        locations: [...this.locations.values()].map((n) => {
+          const criteria = criteriaOf.get(n.id);
+          return criteria?.length ? { ...n, criteria } : n;
+        }),
         orders: [...this.orders.values()],
         tasks: [...this.tasks.values()]
       },
@@ -9126,6 +9364,7 @@ function retiredVocabularyIn(line) {
   constantDuration,
   conversionFactorOf,
   counterfactualAt,
+  criterionSaysNothing,
   demandWindowStart,
   deriveAttentions,
   documentPath,
@@ -9172,10 +9411,12 @@ function retiredVocabularyIn(line) {
   monteCarloForecastAsync,
   objectEvent,
   objectUri,
+  observationAt,
   offCalendarAt,
   offCalendarReasonAt,
   operationalKindOf,
   operationsCapabilityOf,
+  outsideLimit,
   parseEpc,
   parseIsoDuration,
   partialFitPolicy,

package/package.json

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