@operato/twin-kernel 0.7.54 → 0.7.56

package/dist/flow-engine.js

@@ -9,7 +9,7 @@
  * 통합 타입은 도메인 필드를 옵셔널로 넓혀(FlowItem.gtin?, FlowOrder.shipmentEpc? 등) 두 도메인을 담는다.
  * (roadmap Phase5 발견 → 추출. [[project_flow_single_base_vision]] FlowLocation 단일 base 방향과 정합.)
  */
-import { OP_EVENT, CMD, locationStatusOf, readBoardEquipment, readBoardLocations, readBoardAssets, classClosure, capabilityOf, requiredTestsFor, priorityRank, dueStatusOf, isOrderTerminal, effectivityAt, offCalendarAt, offCalendarReasonAt, minuteOfDayAt, activeShiftAt, subLotIdOf, itemKeyOf, identityGroundingOf } from "./contract.js";
+import { OP_EVENT, CMD, locationStatusOf, readBoardEquipment, readBoardLocations, readBoardAssets, classClosure, capabilityOf, requiredTestsFor, priorityRank, dueStatusOf, isOrderTerminal, effectivityAt, offCalendarAt, offCalendarReasonAt, minuteOfDayAt, activeShiftAt, subLotIdOf, itemKeyOf, identityGroundingOf, outsideLimit } from "./contract.js";
 import { ObservedReducer } from "./observed-reducer.js";
 import { transformationEvent, aggregationEvent, objectEvent, parseEpc, DISP, ILMD_ATTR, CBV_BIZSTEP, objectUri, bizTransactionUri, gdtiUri } from "./epcis.js";
 import { OP_PARAM } from "./domain-definition.js";
@@ -108,6 +108,56 @@ thresholds) {
         }
     }
     for (const n of view.locations) {
+        /*
+         * **관측이 한계를 벗어났다** — 판정할 수 있을 때만 낸다.
+         *
+         * ── 왜 이 자리인가 ────────────────────────────────────────────────────────
+         * 기준과 측정값을 계약에 넣어 두고 **아무도 부르지 않았다**(`outsideLimit`). 부르지 않는 판정
+         * 함수는 시험만 통과하는 코드이고, 「선언만 있는 능력은 사용자에게 거짓말이 된다」와 같은 자리다.
+         *
+         * ── 커널이 하지 않는 것 ───────────────────────────────────────────────────
+         * 표현식을 읽지 않는다. 숫자 한계가 없으면 `outsideLimit` 이 `undefined` 를 주고, 그때는 **신호를
+         * 내지 않는다** — 「판정 못 했다」를 「벗어났다」로도 「괜찮다」로도 만들지 않는다.
+         *
+         * 그 「판정 못 했다」가 조용히 사라지는 것은 다른 축이 답한다(`criterionSaysNothing` ·
+         * `testEvidenceGaps`) — 그것은 설정의 흠이고 이것은 운영의 사실이라, 한 신호에 섞지 않는다.
+         *
+         * ── 심각도를 벗어난 폭으로 가르지 않는다 ──────────────────────────────────
+         * 에너지 초과는 5%·15% 로 갈랐다(계량 오차와 구별하기 어려우므로). 여기서는 그러지 않는다:
+         * 식품 안전 한계는 **넘으면 넘은 것**이고, 「조금 넘었다」를 낮게 부르면 그 판단을 커널이 대신
+         * 하는 것이 된다. 폭은 `params` 로 함께 내고 판단은 현장이 한다.
+         */
+        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 !== undefined ? { minimum: c.limit.minimum } : {}),
+                    ...(c.limit?.maximum !== undefined ? { maximum: c.limit.maximum } : {}),
+                    /* **언제의 값인가** — 4개월 전 값으로 지금을 판정한 것인지 소비처가 알아야 한다. */
+                    effectiveTime: observed.effectiveTime,
+                    ...(observed.derived ? { derived: 'true' } : {})
+                }
+            });
+        }
         if ((n.capacity ?? 0) > 0) {
             const r = (n.occupancy ?? 0) / n.capacity;
             /* 기준은 현장이 정한다 — 없으면 기본값이고, 어느 쪽인지 함께 낸다(조용히 기본값을 진실로 두지 않는다). */
@@ -573,6 +623,47 @@ export class FlowEngine {
     localParams = 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();
+    }
     /**
      * 이 커널의 상태가 **관측에서 왔나** — 미러인가.
      *
@@ -1663,9 +1754,31 @@ export class FlowEngine {
     collectAttentions() {
         // 계산 층은 순수 함수 deriveAttentions 로 위임 — sim(여기)과 live projector 미러가 공유(face2-inbound-live §1.1).
         const now = this.now();
+        /*
+         * **자리에 걸린 기준을 여기서 푼다** — 순수 함수는 모델을 읽지 않는다(그 규율은 `attentionThresholds`
+         * 와 같다). 종류 선언(`LocationTypeDef.testSpecificationIds`) → 명세 → 기준으로 풀어 넘긴다.
+         *
+         * 선언이 없으면 빈 배열이고, 그러면 그 자리의 관측은 판정되지 않는다 — 관측은 남고 신호만 서지
+         * 않는다(「선언한 것만 제약이 된다」).
+         */
+        const specById = new Map((this.boardDef?.testSpecifications ?? []).map(sp => [sp.id, sp]));
+        const criteriaOf = 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()]
         }, this._acked, now, // 지연 판정의 "지금" — 관측 중이면 마지막으로 들은 시각이다(§nowMs)

package/dist/forecast.d.ts

@@ -22,6 +22,23 @@ export interface MonteCarloResult {
     mean: number;
     p50: number;
     p90: number;
+    /**
+     * **계보를 잇지 못한 채 넘어간 횟수** — 회차들 중 **최대값**(§`StateSnapshot.stepsWithoutMaterial`).
+     *
+     * ── 왜 예측 결과에 실어야 하나 (2026-08-24) ──────────────────────────────────
+     * 미러의 오더는 확보분을 갖지 않는다(원본이 「어느 개체가 잡혀 있나」를 말하지 않는 것이 그 시스템의
+     * 정상이다). 그래서 예측이 공정을 넘을 때 개체를 이을 수 없고, 커널은 **넘기되 세어 둔다.**
+     *
+     * 그런데 예측은 **회차마다 fork 를 만들고 버린다.** 그 카운터가 사본 안에만 있으면 아무에게도 닿지
+     * 않는다 — 이 저장소가 이미 그 실수를 겪었다(리듀서가 오래 세어 온 값을 스냅샷이 떨어뜨려, 그것을
+     * 읽도록 쓰인 검사가 영원히 조용했다). **세어 놓고 내보내지 않으면 안 센 것과 같다.**
+     *
+     * 왜 합이 아니라 최대인가: 회차는 **같은 미래의 표본들**이다. 서른 번 굴려 각 회차가 열 칸을
+     * 비웠으면 사실은 「열 칸」이고 300이 아니다. 합을 내면 회차 수를 늘리는 것만으로 숫자가 커진다.
+     *
+     * 0 이면 **싣지 않는다** — 0 을 정보처럼 보이게 하지 않는다.
+     */
+    stepsWithoutMaterial?: number;
 }
 export interface MonteCarloOptions {
     runs: number;

package/dist/forecast.js

@@ -19,14 +19,17 @@ function clockOf(twin) {
 export function monteCarloForecast(twin, opts) {
     const now = clockOf(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 (clockOf(fc) < target && guard++ < 1_000_000)
             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);
 }
 /**
  * 한 회차의 **출발점** — fork(현재 보존) + 그 회차의 미래(seed 변주).
@@ -66,6 +69,7 @@ export async function monteCarloForecastAsync(twin, opts) {
      */
     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;
@@ -77,15 +81,27 @@ export 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 } : {})
+    };
 }

package/dist/observed-reducer.d.ts

@@ -1,4 +1,4 @@
-import type { AssetState, MaterialQuantity, TwinModelDef, CanonicalEnvelope, LocationState, ItemState, EquipmentState, PersonState, TaskState, OrderState, StructureShift } from './contract.ts';
+import type { AssetState, MaterialQuantity, TwinModelDef, CanonicalEnvelope, LocationState, ItemState, LocationObservation, EquipmentState, PersonState, TaskState, OrderState, StructureShift } from './contract.ts';
 interface ProjItem {
     epc: string;
     /** 로트의 부분(표준 MaterialSubLot.ID) — 비직렬 로트가 자리마다 갈릴 때만. */
@@ -141,10 +141,17 @@ export interface ReducerCheckpoint {
         firstAtMs?: number;
         lastAtMs?: number;
     }[];
+    /** 자리별 · 속성별 마지막 관측 — 이어 접기가 이 축을 0부터 다시 만들지 않게. */
+    observations?: {
+        id: string;
+        values: LocationObservation[];
+    }[];
 }
 export declare class ObservedReducer {
     /** 로케이션 마스터 — 출처를 함께 들고 있다(마스터가 말한 자리 vs 관측으로 알게 된 자리). */
     private master;
+    /** 자리별 · 속성별 **마지막 관측** — 이력이 아니다(§`OP_EVENT.observation`). */
+    private observations;
     private items;
     private aggregation;
     /** 아직 관측되지 않은 자식의 담김 — 물품을 지어내지 않고 보류했다가 등장할 때 붙인다. */

package/dist/observed-reducer.js

@@ -41,6 +41,8 @@ function effectiveOf(r) {
 export class ObservedReducer {
     /** 로케이션 마스터 — 출처를 함께 들고 있다(마스터가 말한 자리 vs 관측으로 알게 된 자리). */
     master = new Map();
+    /** 자리별 · 속성별 **마지막 관측** — 이력이 아니다(§`OP_EVENT.observation`). */
+    observations = new Map();
     items = new Map();
     aggregation = new Map();
     /** 아직 관측되지 않은 자식의 담김 — 물품을 지어내지 않고 보류했다가 등장할 때 붙인다. */
@@ -339,6 +341,27 @@ export class ObservedReducer {
                 this.touchLocation(d.location);
                 break;
             }
+            case OP_EVENT.observation: {
+                /*
+                 * **자리의 물리 관측** — 속성마다 마지막 값 하나만 든다(§`LocationState.observations`).
+                 *
+                 * 이력을 들지 않는 이유: 상태가 **시간에 비례해 자라지 않게**. 「그때 몇 도였나」는 저널이
+                 * 답하는 물음이고, 상태가 답하는 것은 「지금 몇 도냐」다.
+                 *
+                 * 늦게 온 옛 관측이 최신을 덮지 않게 `stale` 을 지난다 — 대상 키에 속성을 넣는다(온도가 늦게
+                 * 와도 습도의 최신은 지켜져야 한다).
+                 */
+                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) ?? new Map();
+                bin.set(d.propertyId, { ...d });
+                this.observations.set(d.locationId, bin);
+                break;
+            }
             case OP_EVENT.attentionAck: {
                 /* 확인한 사실만 담는다 — 그 신호가 지금도 성립하는지는 상태가 답한다(여기서 판단하지 않는다). */
                 const d = e.data;
@@ -747,6 +770,8 @@ export class ObservedReducer {
      */
     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 })),
@@ -771,6 +796,7 @@ export class ObservedReducer {
      * 모델에서 오는 판정 입력(교대·등급·시간대)은 생성자가 이미 세웠으므로 건드리지 않는다.
      */
     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 }]));
@@ -807,6 +833,11 @@ export class ObservedReducer {
                     ...(n.capacity === undefined ? {} : { capacity: n.capacity }),
                     ...(n.parallelism === undefined ? {} : { parallelism: n.parallelism }),
                     ...(n.parentId ? { parentId: n.parentId } : {}),
+                    /* 관측된 물리량 — 없으면 **키를 만들지 않는다**(빈 배열은 「센서가 없다」와 「못 들었다」를 같게 만든다). */
+                    ...(() => {
+                        const bin = this.observations.get(n.id);
+                        return bin?.size ? { observations: [...bin.values()] } : {};
+                    })(),
                     origin: n.origin
                 };
             }),