@operato/twin-kernel 0.7.26 → 0.7.28

package/dist/event-journal.d.ts

@@ -1,5 +1,5 @@
 import type { TwinModelDef, CanonicalEnvelope, StructureShift } from './contract.ts';
-import { type ProjectedState } from './state-projector.ts';
+import { type ProjectedState, type ReducerCheckpoint } from './state-projector.ts';
 export declare class EventJournal {
     private events;
     /** 이벤트 1건 기록(추가 전용). runtime/kernel 의 onEvent 에 연결. */
@@ -15,6 +15,29 @@ export declare class EventJournal {
 }
 /** 이벤트열 → 상태 재구성(시간여행). `model` = 그 시점의 트윈 모델(토폴로지·자원). */
 export declare function replay(model: TwinModelDef, events: readonly CanonicalEnvelope[]): ProjectedState;
+/**
+ * **재개점에서 이어 접는다** — 0부터 다시 접지 않는다.
+ *
+ * ── 왜 (2026-08-18 실측) ────────────────────────────────────────────────────
+ * 저널이 27만 건인 트윈에서 과거 상태를 물으면 전부 다시 접어야 했다. 그런데 우리는 이미 주기적으로
+ * 재개점을 남기고 있다 — 그 지점부터 **뒤에 일어난 것만** 접으면 같은 답이 나온다.
+ *
+ * 「같은 답」은 말로 보장되지 않는다: 재개점이 리듀서의 **내부 상태 전부**여야 하고(보기가 아니라),
+ * 그 사실은 시험이 증명한다(0부터 접기 == 재개점 + 꼬리). 그래서 이 함수는 새 재개점도 함께 낸다 —
+ * 소비처가 그것을 저장해 다음 꼬리를 또 이어 붙일 수 있게.
+ *
+ * 구조가 바뀐 구간은 여기서 다루지 않는다(`replaySegments` 의 몫이다) — 재개점은 **한 구조 안에서**
+ * 이어 붙이는 것이다. 구조가 바뀌었으면 부르는 쪽이 그 경계에서 갈라야 한다.
+ */
+export declare function replayFrom(model: TwinModelDef, checkpoint: ReducerCheckpoint, events: readonly CanonicalEnvelope[]): {
+    state: ProjectedState;
+    checkpoint: ReducerCheckpoint;
+};
+/** 이벤트열을 접고 **재개점도 함께** 낸다 — 다음 번에 이어 붙일 수 있게. */
+export declare function replayWithCheckpoint(model: TwinModelDef, events: readonly CanonicalEnvelope[]): {
+    state: ProjectedState;
+    checkpoint: ReducerCheckpoint;
+};
 /**
  * 한 구조 아래에서 일어난 이벤트들 — 재생의 한 마디.
  *

package/dist/event-journal.js

@@ -39,6 +39,34 @@ export function replay(model, events) {
         proj.apply(e);
     return proj.snapshot();
 }
+/**
+ * **재개점에서 이어 접는다** — 0부터 다시 접지 않는다.
+ *
+ * ── 왜 (2026-08-18 실측) ────────────────────────────────────────────────────
+ * 저널이 27만 건인 트윈에서 과거 상태를 물으면 전부 다시 접어야 했다. 그런데 우리는 이미 주기적으로
+ * 재개점을 남기고 있다 — 그 지점부터 **뒤에 일어난 것만** 접으면 같은 답이 나온다.
+ *
+ * 「같은 답」은 말로 보장되지 않는다: 재개점이 리듀서의 **내부 상태 전부**여야 하고(보기가 아니라),
+ * 그 사실은 시험이 증명한다(0부터 접기 == 재개점 + 꼬리). 그래서 이 함수는 새 재개점도 함께 낸다 —
+ * 소비처가 그것을 저장해 다음 꼬리를 또 이어 붙일 수 있게.
+ *
+ * 구조가 바뀐 구간은 여기서 다루지 않는다(`replaySegments` 의 몫이다) — 재개점은 **한 구조 안에서**
+ * 이어 붙이는 것이다. 구조가 바뀌었으면 부르는 쪽이 그 경계에서 갈라야 한다.
+ */
+export function replayFrom(model, checkpoint, events) {
+    const proj = new StateProjector(model);
+    proj.restore(checkpoint);
+    for (const e of events)
+        proj.apply(e);
+    return { state: proj.snapshot(), checkpoint: proj.serialize() };
+}
+/** 이벤트열을 접고 **재개점도 함께** 낸다 — 다음 번에 이어 붙일 수 있게. */
+export function replayWithCheckpoint(model, events) {
+    const proj = new StateProjector(model);
+    for (const e of events)
+        proj.apply(e);
+    return { state: proj.snapshot(), checkpoint: proj.serialize() };
+}
 /**
  * **구조가 바뀐 이력까지 이어서 재생한다.**
  *

package/dist/flow-engine.d.ts

@@ -210,6 +210,39 @@ interface Rng {
  * FlowEngine.computeAttentions(sim) 와 live projector 미러가 **공유**하는 계산 층(face2-inbound-live §1.1):
  * sim/live 가 같은 임계값·규칙을 쓴다. good/scrap 미제공(관측 상태에 없음)이면 scrap-high 는 자연 스킵(metric 층 갭).
  */
+/**
+ * 주의 판정의 **기준값 어휘** — 현장이 정하는 수다.
+ *
+ * ── 왜 선언으로 받나 (2026-08-18) ───────────────────────────────────────────
+ * 혼잡 90%·불량 15%는 **우리가 정한 수**였다(코드 상수). 그런데 통로를 95%로 채워 쓰는 창고는 그 기준에서
+ * 영구히 「병목」이고, 초기 라인(불량 20% 예상)은 계속 「불량 과다」로 운다. 경보가 소음이 되면 사람이
+ * 경보 자체를 읽지 않는다 — 그때 진짜 경보도 함께 묻힌다.
+ *
+ * 그래서 기준을 현장이 넣을 수 있게 하고, **넣지 않으면 기본값을 쓰되 그 사실을 밝힌다**(`basis`).
+ * 조용히 기본값을 진실처럼 두지 않는다.
+ *
+ * 퍼센트다: 90 이 90%이고 0.9 는 0.9%다(SOC 에서 한 번 겪은 함정 — 명세가 그 말을 한다).
+ */
+export declare const ATTENTION_PROPERTY: {
+    /** 자리의 혼잡 판정 기준(%) — 점유/용량이 이 값을 넘으면 병목으로 본다. */
+    readonly congestionRatio: "attention.congestionRatio";
+    /** 설비의 불량률 판정 기준(%) — 이 값을 넘으면 불량 과다로 본다. */
+    readonly scrapRate: "attention.scrapRate";
+    /** 불량률을 재기 시작할 최소 표본 수 — 적은 표본의 비율은 판정 근거가 못 된다. */
+    readonly scrapMinSamples: "attention.scrapMinSamples";
+};
+/** 선언이 없을 때 쓰는 기본값 — **드러내 둔다**(코드 안에 숨은 상수가 아니라 계약의 일부다). */
+export declare const ATTENTION_DEFAULTS: {
+    readonly congestionPct: 90;
+    readonly scrapPct: 15;
+    readonly scrapMinSamples: 10;
+};
+/** 판정에 쓸 기준 — 대상별 선언이 있으면 그것, 없으면 기본값(그 사실을 함께 든다). */
+export interface AttentionThresholds {
+    congestionPctOf?: (locationId: string) => number | undefined;
+    scrapPctOf?: (equipmentId: string) => number | undefined;
+    scrapMinSamplesOf?: (equipmentId: string) => number | undefined;
+}
 export declare function deriveAttentions(view: {
     equipment: {
         id: string;
@@ -243,7 +276,13 @@ export declare function deriveAttentions(view: {
     }[];
 }, acked?: ReadonlySet<string>, 
 /** 지금(ISO) — 납기 판정에 필요하다. **주지 않으면 지연을 판정하지 않는다**(모르면 판단하지 않는다). */
-nowIso?: ISOTime): Attention[];
+nowIso?: ISOTime, 
+/**
+ * 현장이 선언한 판정 기준 — 주지 않으면 기본값으로 판정하고 그 사실을 `params.basis` 로 밝힌다.
+ *
+ * 부르는 쪽이 모델에서 뽑아 넘긴다(이 함수는 순수하게 남는다 — 모델을 읽는 규칙이 두 곳이 되지 않게).
+ */
+thresholds?: AttentionThresholds): Attention[];
 /** OEE 계측 카운터 — sim 은 tick 으로 누적, live 는 실 텔레메트리 또는 이벤트 누적기가 채운다(face2-inbound-live §1.1). */
 export interface OeeCounters {
     runMs: number;
@@ -491,6 +530,14 @@ export declare abstract class FlowEngine implements TwinKernel {
     getSnapshot(): StateSnapshot;
     protected computeAttentions(): Attention[];
     protected collectAttentions(): Attention[];
+    /**
+     * 현장이 선언한 판정 기준을 모델에서 뽑는다 — **규칙은 한 곳**(순수 함수는 모델을 읽지 않는다).
+     *
+     * 자리·설비의 속성에서 읽고, 없으면 `undefined` 를 돌려 기본값이 쓰이게 한다(그 사실은 판정 층이
+     * `basis` 로 밝힌다). 값이 수가 아니거나 범위를 벗어나면 **없는 것으로 본다** — 사람이 손으로 넣는
+     * 값이라 잘못 들어올 수 있고, 잘못된 기준으로 판정하는 것은 기본값보다 나쁘다.
+     */
+    protected attentionThresholds(): AttentionThresholds;
     /**
      * fork — 현재 상태를 정확히 복제한 새 엔진 (디지털트윈 본연: "현재로부터 예측").
      * 원본(live/sim)은 계속 진행, fork 는 what-if 를 앞으로 시뮬레이션해 forecast·발산(predicted vs actual) 검사에 쓴다.

package/dist/flow-engine.js

@@ -44,9 +44,38 @@ function mulberry32(seed) {
  * FlowEngine.computeAttentions(sim) 와 live projector 미러가 **공유**하는 계산 층(face2-inbound-live §1.1):
  * sim/live 가 같은 임계값·규칙을 쓴다. good/scrap 미제공(관측 상태에 없음)이면 scrap-high 는 자연 스킵(metric 층 갭).
  */
+/**
+ * 주의 판정의 **기준값 어휘** — 현장이 정하는 수다.
+ *
+ * ── 왜 선언으로 받나 (2026-08-18) ───────────────────────────────────────────
+ * 혼잡 90%·불량 15%는 **우리가 정한 수**였다(코드 상수). 그런데 통로를 95%로 채워 쓰는 창고는 그 기준에서
+ * 영구히 「병목」이고, 초기 라인(불량 20% 예상)은 계속 「불량 과다」로 운다. 경보가 소음이 되면 사람이
+ * 경보 자체를 읽지 않는다 — 그때 진짜 경보도 함께 묻힌다.
+ *
+ * 그래서 기준을 현장이 넣을 수 있게 하고, **넣지 않으면 기본값을 쓰되 그 사실을 밝힌다**(`basis`).
+ * 조용히 기본값을 진실처럼 두지 않는다.
+ *
+ * 퍼센트다: 90 이 90%이고 0.9 는 0.9%다(SOC 에서 한 번 겪은 함정 — 명세가 그 말을 한다).
+ */
+export const ATTENTION_PROPERTY = {
+    /** 자리의 혼잡 판정 기준(%) — 점유/용량이 이 값을 넘으면 병목으로 본다. */
+    congestionRatio: 'attention.congestionRatio',
+    /** 설비의 불량률 판정 기준(%) — 이 값을 넘으면 불량 과다로 본다. */
+    scrapRate: 'attention.scrapRate',
+    /** 불량률을 재기 시작할 최소 표본 수 — 적은 표본의 비율은 판정 근거가 못 된다. */
+    scrapMinSamples: 'attention.scrapMinSamples'
+};
+/** 선언이 없을 때 쓰는 기본값 — **드러내 둔다**(코드 안에 숨은 상수가 아니라 계약의 일부다). */
+export const ATTENTION_DEFAULTS = { congestionPct: 90, scrapPct: 15, scrapMinSamples: 10 };
 export function deriveAttentions(view, acked, 
 /** 지금(ISO) — 납기 판정에 필요하다. **주지 않으면 지연을 판정하지 않는다**(모르면 판단하지 않는다). */
-nowIso) {
+nowIso, 
+/**
+ * 현장이 선언한 판정 기준 — 주지 않으면 기본값으로 판정하고 그 사실을 `params.basis` 로 밝힌다.
+ *
+ * 부르는 쪽이 모델에서 뽑아 넘긴다(이 함수는 순수하게 남는다 — 모델을 읽는 규칙이 두 곳이 되지 않게).
+ */
+thresholds) {
     // 언어 중립: kind + params(원시값) + 조치 code 만 방출. 사람이 읽는 title/detail/rationale/라벨은
     // 표현계층(클라 i18next)이 kind/code 로 렌더한다(무방언·다국어 — design/plans/i18n.md L3).
     const out = [];
@@ -67,12 +96,19 @@ nowIso) {
     for (const n of view.locations) {
         if ((n.capacity ?? 0) > 0) {
             const r = (n.occupancy ?? 0) / n.capacity;
-            if (r >= 0.9) {
+            /* 기준은 현장이 정한다 — 없으면 기본값이고, 어느 쪽인지 함께 낸다(조용히 기본값을 진실로 두지 않는다). */
+            const declaredPct = thresholds?.congestionPctOf?.(n.id);
+            const thresholdPct = declaredPct ?? ATTENTION_DEFAULTS.congestionPct;
+            if (r * 100 >= thresholdPct) {
                 const saturated = r >= 1;
                 out.push({
                     id: `bottleneck:${n.id}`, kind: 'bottleneck', severity: saturated ? 'high' : 'medium',
                     anchor: { locationId: n.id },
-                    params: { locationId: n.id, occupancy: n.occupancy ?? 0, capacity: n.capacity ?? 0, ratioPct: Math.round(r * 100), saturated: saturated ? 1 : 0 },
+                    params: {
+                        locationId: n.id, occupancy: n.occupancy ?? 0, capacity: n.capacity ?? 0, ratioPct: Math.round(r * 100),
+                        saturated: saturated ? 1 : 0,
+                        thresholdPct, basis: declaredPct === undefined ? 'default' : 'declared'
+                    },
                     recommendedActions: [{ code: 'advice.add-resource' }, { code: 'advice.downstream-priority' }]
                     // 권고만(command 없음) — 표현계층이 advice.* 코드로 렌더
                 });
@@ -130,13 +166,21 @@ nowIso) {
     }
     for (const m of view.equipment) {
         const total = (m.goodCount ?? 0) + (m.scrapCount ?? 0);
-        if (total >= 10) {
+        const declaredMin = thresholds?.scrapMinSamplesOf?.(m.id);
+        const minSamples = declaredMin ?? ATTENTION_DEFAULTS.scrapMinSamples;
+        if (total >= minSamples) {
             const rate = (m.scrapCount ?? 0) / total;
-            if (rate >= 0.15)
+            const declaredPct = thresholds?.scrapPctOf?.(m.id);
+            const thresholdPct = declaredPct ?? ATTENTION_DEFAULTS.scrapPct;
+            /* 「높음」은 기준의 두 배에서 — 기준이 현장의 것이면 그 두 배도 현장의 것이다(상수 두 벌을 두지 않는다). */
+            if (rate * 100 >= thresholdPct)
                 out.push({
-                    id: `scrap:${m.id}`, kind: 'scrap-high', severity: rate >= 0.3 ? 'high' : 'medium',
+                    id: `scrap:${m.id}`, kind: 'scrap-high', severity: rate * 100 >= thresholdPct * 2 ? 'high' : 'medium',
                     anchor: { moverId: m.id, locationId: m.location },
-                    params: { moverId: m.id, goodCount: m.goodCount ?? 0, scrapCount: m.scrapCount ?? 0, ratePct: Math.round(rate * 100) },
+                    params: {
+                        moverId: m.id, goodCount: m.goodCount ?? 0, scrapCount: m.scrapCount ?? 0, ratePct: Math.round(rate * 100),
+                        thresholdPct, basis: declaredPct === undefined ? 'default' : 'declared'
+                    },
                     recommendedActions: [
                         { code: 'act.hold-for-inspection', command: CMD.resourceHold, args: { resourceId: m.id } },
                         { code: 'act.reset-metrics', command: CMD.resourceResetMetrics, args: { resourceId: m.id } }
@@ -1105,10 +1149,40 @@ export class FlowEngine {
             locations: [...this.locations.values()],
             orders: [...this.orders.values()],
             tasks: [...this.tasks.values()]
-        }, this._acked, now // 지연 판정의 "지금" — 관측 중이면 마지막으로 들은 시각이다(§nowMs)
-        );
+        }, this._acked, now, // 지연 판정의 "지금" — 관측 중이면 마지막으로 들은 시각이다(§nowMs)
+        this.attentionThresholds());
         return out;
     }
+    /**
+     * 현장이 선언한 판정 기준을 모델에서 뽑는다 — **규칙은 한 곳**(순수 함수는 모델을 읽지 않는다).
+     *
+     * 자리·설비의 속성에서 읽고, 없으면 `undefined` 를 돌려 기본값이 쓰이게 한다(그 사실은 판정 층이
+     * `basis` 로 밝힌다). 값이 수가 아니거나 범위를 벗어나면 **없는 것으로 본다** — 사람이 손으로 넣는
+     * 값이라 잘못 들어올 수 있고, 잘못된 기준으로 판정하는 것은 기본값보다 나쁘다.
+     */
+    attentionThresholds() {
+        const pct = (props, id) => {
+            const raw = props?.find(p => p.id === id)?.value;
+            if (raw === undefined)
+                return undefined;
+            const n = Number(raw);
+            return Number.isFinite(n) && n > 0 && n <= 100 ? n : undefined;
+        };
+        const count = (props, id) => {
+            const raw = props?.find(p => p.id === id)?.value;
+            if (raw === undefined)
+                return undefined;
+            const n = Number(raw);
+            return Number.isFinite(n) && n >= 1 ? Math.floor(n) : undefined;
+        };
+        const locProps = new Map((this.boardDef?.locations ?? []).map(l => [l.id, l.properties]));
+        const eqProps = new Map(readBoardEquipment(this.boardDef ?? {}).map(e => [e.id, e.properties]));
+        return {
+            congestionPctOf: id => pct(locProps.get(id), ATTENTION_PROPERTY.congestionRatio),
+            scrapPctOf: id => pct(eqProps.get(id), ATTENTION_PROPERTY.scrapRate),
+            scrapMinSamplesOf: id => count(eqProps.get(id), ATTENTION_PROPERTY.scrapMinSamples)
+        };
+    }
     /**
      * fork — 현재 상태를 정확히 복제한 새 엔진 (디지털트윈 본연: "현재로부터 예측").
      * 원본(live/sim)은 계속 진행, fork 는 what-if 를 앞으로 시뮬레이션해 forecast·발산(predicted vs actual) 검사에 쓴다.

package/dist/observed-reducer.d.ts

@@ -1,4 +1,22 @@
-import type { AssetState, TwinModelDef, CanonicalEnvelope, LocationState, ItemState, EquipmentState, PersonState, TaskState, OrderState, StructureShift } from './contract.ts';
+import type { AssetState, MaterialQuantity, TwinModelDef, CanonicalEnvelope, LocationState, ItemState, EquipmentState, PersonState, TaskState, OrderState, StructureShift } from './contract.ts';
+interface ProjItem {
+    epc: string;
+    /** 로트의 부분(표준 MaterialSubLot.ID) — 비직렬 로트가 자리마다 갈릴 때만. */
+    subLotId?: string;
+    gtin?: string;
+    gtinKey?: string;
+    lot?: string;
+    location: string;
+    disposition?: string;
+    parent?: string;
+    qty?: number;
+    uom?: string;
+    /** 선언된 모든 수량 — 표준 `MaterialLot.Quantity`(복수). 첫 항목만 쓰던 것을 고쳤다. */
+    quantities?: MaterialQuantity[];
+    /** 받은 개체·로트 마스터데이터 원문 — 이름을 모르는 속성도 잃지 않는다. */
+    ilmd?: Record<string, unknown>;
+    expiry?: number;
+}
 /**
  * 마스터 동기 — 선언적 로케이션 upsert/remove.
  *
@@ -63,6 +81,50 @@ export interface ProjectedState {
      */
     acked: string[];
 }
+/**
+ * 리듀서의 **완전한 재개점** — 이어 접기의 씨앗.
+ *
+ * `ProjectedState`(보기)와 구별한다: 여기에는 소비처가 보지 않는 것도 들어간다(보류된 담김·집합·
+ * 반영 못 한 사건 집계). 그것이 빠지면 「이어 접은 결과」가 「0부터 접은 결과」와 조용히 달라진다.
+ */
+export interface ReducerCheckpoint {
+    revision: number;
+    master: {
+        id: string;
+        type: string;
+        capacity?: number;
+        parallelism?: number;
+        parentId?: string;
+        origin: 'master' | 'observed';
+    }[];
+    items: ProjItem[];
+    aggregation: {
+        parent: string;
+        children: string[];
+    }[];
+    pendingParent: {
+        child: string;
+        parent: string;
+    }[];
+    tasks: TaskState[];
+    equipment: EquipmentState[];
+    persons: PersonState[];
+    assets: AssetState[];
+    orders: OrderState[];
+    acked: string[];
+    corrections: {
+        declaredAt: string;
+        reason?: string;
+        correctiveEventIDs: string[];
+        eventID?: string;
+    }[];
+    unhandled: {
+        eventType: string;
+        count: number;
+        firstAtMs?: number;
+        lastAtMs?: number;
+    }[];
+}
 export declare class ObservedReducer {
     /** 로케이션 마스터 — 출처를 함께 들고 있다(마스터가 말한 자리 vs 관측으로 알게 된 자리). */
     private master;
@@ -215,5 +277,27 @@ export declare class ObservedReducer {
      * **이벤트 없이 시각만으로** 넘어간다. 델타로 받아 두면 만료된 자격이 영원히 유효하게 남는다.
      */
     private capabilityPart;
+    /**
+     * **재개점(checkpoint)** — 스냅샷과 다르다.
+     *
+     * ── 왜 스냅샷으로는 이어 접을 수 없나 (2026-08-18) ─────────────────────────
+     * `snapshot()` 은 **소비처가 보는 값**이다(파생된 판정·정리된 목록). 그것으로 리듀서를 되세우면
+     * 보이지 않는 것들이 사라진다 — 아직 등장하지 않은 자식의 담김(`pendingParent`), 집합 관계
+     * (`aggregation`), 반영 못 한 사건 집계(`unhandled`), 정정 선언(`corrections`). 그 상태에서 뒤 이벤트를
+     * 접으면 **0부터 접은 결과와 달라진다.** 다르면 그 차이는 조용하다(오류가 없다).
+     *
+     * 그래서 재개점은 **내부 상태 전부**다. 「이어 접기」의 정합성은 시험이 증명한다:
+     * 0부터 접은 결과 == 앞부분 재개점 + 뒷부분 접기.
+     *
+     * 모델에서 오는 것(교대·등급·시간대)은 담지 않는다 — 되세울 때 같은 모델을 받기 때문이다.
+     */
+    serialize(): ReducerCheckpoint;
+    /**
+     * 재개점에서 되세운다 — **모르는 것은 지어내지 않는다**(없는 축은 비운다).
+     *
+     * 모델에서 오는 판정 입력(교대·등급·시간대)은 생성자가 이미 세웠으므로 건드리지 않는다.
+     */
+    restore(cp: ReducerCheckpoint): void;
     snapshot(): ProjectedState;
 }
+export {};

package/dist/observed-reducer.js

@@ -635,6 +635,57 @@ export class ObservedReducer {
             capability: capabilityOf({ ...r, ...(decl?.window ? { window: decl.window } : {}), ...(decl?.workCalendar ? { workCalendar: decl.workCalendar } : {}) }, { at, utcOffsetMinutes: this.utcOffsetMinutes, requiredTests: requiredTestsFor(directClassIds, defs, at) })
         };
     }
+    /**
+     * **재개점(checkpoint)** — 스냅샷과 다르다.
+     *
+     * ── 왜 스냅샷으로는 이어 접을 수 없나 (2026-08-18) ─────────────────────────
+     * `snapshot()` 은 **소비처가 보는 값**이다(파생된 판정·정리된 목록). 그것으로 리듀서를 되세우면
+     * 보이지 않는 것들이 사라진다 — 아직 등장하지 않은 자식의 담김(`pendingParent`), 집합 관계
+     * (`aggregation`), 반영 못 한 사건 집계(`unhandled`), 정정 선언(`corrections`). 그 상태에서 뒤 이벤트를
+     * 접으면 **0부터 접은 결과와 달라진다.** 다르면 그 차이는 조용하다(오류가 없다).
+     *
+     * 그래서 재개점은 **내부 상태 전부**다. 「이어 접기」의 정합성은 시험이 증명한다:
+     * 0부터 접은 결과 == 앞부분 재개점 + 뒷부분 접기.
+     *
+     * 모델에서 오는 것(교대·등급·시간대)은 담지 않는다 — 되세울 때 같은 모델을 받기 때문이다.
+     */
+    serialize() {
+        return {
+            revision: this.revision,
+            master: [...this.master.values()].map(n => ({ ...n })),
+            items: [...this.items.values()].map(i => ({ ...i })),
+            aggregation: [...this.aggregation.entries()].map(([parent, children]) => ({ parent, children: [...children] })),
+            pendingParent: [...this.pendingParent.entries()].map(([child, parent]) => ({ child, parent })),
+            tasks: [...this.tasks.values()].map(t => ({ ...t })),
+            equipment: [...this.equipment.values()].map(m => ({ ...m })),
+            persons: [...this.persons.values()].map(x => ({ ...x })),
+            assets: [...this.assets.values()].map(x => ({ ...x })),
+            orders: [...this.orders.values()].map(o => ({ ...o })),
+            acked: [...this.acked],
+            corrections: this.corrections.map(c => ({ ...c })),
+            unhandled: [...this.unhandled.entries()].map(([eventType, v]) => ({ eventType, ...v }))
+        };
+    }
+    /**
+     * 재개점에서 되세운다 — **모르는 것은 지어내지 않는다**(없는 축은 비운다).
+     *
+     * 모델에서 오는 판정 입력(교대·등급·시간대)은 생성자가 이미 세웠으므로 건드리지 않는다.
+     */
+    restore(cp) {
+        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 }]));
+        this.aggregation = new Map((cp?.aggregation ?? []).map(a => [a.parent, [...a.children]]));
+        this.pendingParent = new Map((cp?.pendingParent ?? []).map(x => [x.child, x.parent]));
+        this.tasks = new Map((cp?.tasks ?? []).map(t => [t.id, { ...t }]));
+        this.equipment = new Map((cp?.equipment ?? []).map(m => [m.id, { ...m }]));
+        this.persons = new Map((cp?.persons ?? []).map(x => [x.id, { ...x }]));
+        this.assets = new Map((cp?.assets ?? []).map(x => [x.id, { ...x }]));
+        this.orders = new Map((cp?.orders ?? []).map(o => [o.id, { ...o }]));
+        this.acked = new Set(cp?.acked ?? []);
+        this.corrections = (cp?.corrections ?? []).map(c => ({ ...c }));
+        this.unhandled = new Map((cp?.unhandled ?? []).map(({ eventType, ...v }) => [eventType, { ...v }]));
+    }
     snapshot() {
         const occ = new Map();
         for (const it of this.items.values())

package/dist/state-projector.d.ts

@@ -1,2 +1,2 @@
 export { ObservedReducer, ObservedReducer as StateProjector } from './observed-reducer.ts';
-export type { MasterUpdate, ProjectedState } from './observed-reducer.ts';
+export type { MasterUpdate, ProjectedState, ReducerCheckpoint } from './observed-reducer.ts';

package/dist-cjs/index.cjs

@@ -19,6 +19,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ATTENTION_DEFAULTS: () => ATTENTION_DEFAULTS,
+  ATTENTION_PROPERTY: () => ATTENTION_PROPERTY,
   BIZSTEP: () => BIZSTEP,
   BTT: () => BTT,
   BTT_DELIVERY: () => BTT_DELIVERY,
@@ -144,7 +146,9 @@ __export(index_exports, {
   relationsFrom: () => relationsFrom,
   relationsTo: () => relationsTo,
   replay: () => replay,
+  replayFrom: () => replayFrom,
   replaySegments: () => replaySegments,
+  replayWithCheckpoint: () => replayWithCheckpoint,
   requiredTestsFor: () => requiredTestsFor,
   retiredVocabularyIn: () => retiredVocabularyIn,
   sgtinClass: () => sgtinClass,
@@ -1584,6 +1588,57 @@ var ObservedReducer = class {
       )
     };
   }
+  /**
+   * **재개점(checkpoint)** — 스냅샷과 다르다.
+   *
+   * ── 왜 스냅샷으로는 이어 접을 수 없나 (2026-08-18) ─────────────────────────
+   * `snapshot()` 은 **소비처가 보는 값**이다(파생된 판정·정리된 목록). 그것으로 리듀서를 되세우면
+   * 보이지 않는 것들이 사라진다 — 아직 등장하지 않은 자식의 담김(`pendingParent`), 집합 관계
+   * (`aggregation`), 반영 못 한 사건 집계(`unhandled`), 정정 선언(`corrections`). 그 상태에서 뒤 이벤트를
+   * 접으면 **0부터 접은 결과와 달라진다.** 다르면 그 차이는 조용하다(오류가 없다).
+   *
+   * 그래서 재개점은 **내부 상태 전부**다. 「이어 접기」의 정합성은 시험이 증명한다:
+   * 0부터 접은 결과 == 앞부분 재개점 + 뒷부분 접기.
+   *
+   * 모델에서 오는 것(교대·등급·시간대)은 담지 않는다 — 되세울 때 같은 모델을 받기 때문이다.
+   */
+  serialize() {
+    return {
+      revision: this.revision,
+      master: [...this.master.values()].map((n) => ({ ...n })),
+      items: [...this.items.values()].map((i) => ({ ...i })),
+      aggregation: [...this.aggregation.entries()].map(([parent, children]) => ({ parent, children: [...children] })),
+      pendingParent: [...this.pendingParent.entries()].map(([child, parent]) => ({ child, parent })),
+      tasks: [...this.tasks.values()].map((t) => ({ ...t })),
+      equipment: [...this.equipment.values()].map((m) => ({ ...m })),
+      persons: [...this.persons.values()].map((x) => ({ ...x })),
+      assets: [...this.assets.values()].map((x) => ({ ...x })),
+      orders: [...this.orders.values()].map((o) => ({ ...o })),
+      acked: [...this.acked],
+      corrections: this.corrections.map((c) => ({ ...c })),
+      unhandled: [...this.unhandled.entries()].map(([eventType, v]) => ({ eventType, ...v }))
+    };
+  }
+  /**
+   * 재개점에서 되세운다 — **모르는 것은 지어내지 않는다**(없는 축은 비운다).
+   *
+   * 모델에서 오는 판정 입력(교대·등급·시간대)은 생성자가 이미 세웠으므로 건드리지 않는다.
+   */
+  restore(cp) {
+    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 }]));
+    this.aggregation = new Map((cp?.aggregation ?? []).map((a) => [a.parent, [...a.children]]));
+    this.pendingParent = new Map((cp?.pendingParent ?? []).map((x) => [x.child, x.parent]));
+    this.tasks = new Map((cp?.tasks ?? []).map((t) => [t.id, { ...t }]));
+    this.equipment = new Map((cp?.equipment ?? []).map((m) => [m.id, { ...m }]));
+    this.persons = new Map((cp?.persons ?? []).map((x) => [x.id, { ...x }]));
+    this.assets = new Map((cp?.assets ?? []).map((x) => [x.id, { ...x }]));
+    this.orders = new Map((cp?.orders ?? []).map((o) => [o.id, { ...o }]));
+    this.acked = new Set(cp?.acked ?? []);
+    this.corrections = (cp?.corrections ?? []).map((c) => ({ ...c }));
+    this.unhandled = new Map((cp?.unhandled ?? []).map(({ eventType, ...v }) => [eventType, { ...v }]));
+  }
   snapshot() {
     const occ = /* @__PURE__ */ new Map();
     for (const it of this.items.values()) occ.set(it.location, (occ.get(it.location) ?? 0) + 1);
@@ -1651,6 +1706,17 @@ function replay(model, events) {
   for (const e of events) proj.apply(e);
   return proj.snapshot();
 }
+function replayFrom(model, checkpoint, events) {
+  const proj = new ObservedReducer(model);
+  proj.restore(checkpoint);
+  for (const e of events) proj.apply(e);
+  return { state: proj.snapshot(), checkpoint: proj.serialize() };
+}
+function replayWithCheckpoint(model, events) {
+  const proj = new ObservedReducer(model);
+  for (const e of events) proj.apply(e);
+  return { state: proj.snapshot(), checkpoint: proj.serialize() };
+}
 function replaySegments(segments) {
   if (!segments.length) throw new Error("\uC7AC\uC0DD\uD560 \uB9C8\uB514\uAC00 \uC5C6\uB2E4 \u2014 \uAD6C\uC870\uB97C \uD558\uB098\uB3C4 \uC8FC\uC9C0 \uC54A\uC558\uB2E4");
   const proj = new ObservedReducer(segments[0].model);
@@ -2888,7 +2954,16 @@ function mulberry32(seed) {
   } });
   return fn;
 }
-function deriveAttentions(view, acked, nowIso) {
+var ATTENTION_PROPERTY = {
+  /** 자리의 혼잡 판정 기준(%) — 점유/용량이 이 값을 넘으면 병목으로 본다. */
+  congestionRatio: "attention.congestionRatio",
+  /** 설비의 불량률 판정 기준(%) — 이 값을 넘으면 불량 과다로 본다. */
+  scrapRate: "attention.scrapRate",
+  /** 불량률을 재기 시작할 최소 표본 수 — 적은 표본의 비율은 판정 근거가 못 된다. */
+  scrapMinSamples: "attention.scrapMinSamples"
+};
+var ATTENTION_DEFAULTS = { congestionPct: 90, scrapPct: 15, scrapMinSamples: 10 };
+function deriveAttentions(view, acked, nowIso, thresholds) {
   const out = [];
   for (const m of view.equipment) {
     if (m.status === "down") {
@@ -2909,14 +2984,24 @@ function deriveAttentions(view, acked, nowIso) {
   for (const n of view.locations) {
     if ((n.capacity ?? 0) > 0) {
       const r = (n.occupancy ?? 0) / n.capacity;
-      if (r >= 0.9) {
+      const declaredPct = thresholds?.congestionPctOf?.(n.id);
+      const thresholdPct = declaredPct ?? ATTENTION_DEFAULTS.congestionPct;
+      if (r * 100 >= thresholdPct) {
         const saturated = r >= 1;
         out.push({
           id: `bottleneck:${n.id}`,
           kind: "bottleneck",
           severity: saturated ? "high" : "medium",
           anchor: { locationId: n.id },
-          params: { locationId: n.id, occupancy: n.occupancy ?? 0, capacity: n.capacity ?? 0, ratioPct: Math.round(r * 100), saturated: saturated ? 1 : 0 },
+          params: {
+            locationId: n.id,
+            occupancy: n.occupancy ?? 0,
+            capacity: n.capacity ?? 0,
+            ratioPct: Math.round(r * 100),
+            saturated: saturated ? 1 : 0,
+            thresholdPct,
+            basis: declaredPct === void 0 ? "default" : "declared"
+          },
           recommendedActions: [{ code: "advice.add-resource" }, { code: "advice.downstream-priority" }]
           // 권고만(command 없음) — 표현계층이 advice.* 코드로 렌더
         });
@@ -2949,14 +3034,25 @@ function deriveAttentions(view, acked, nowIso) {
   }
   for (const m of view.equipment) {
     const total = (m.goodCount ?? 0) + (m.scrapCount ?? 0);
-    if (total >= 10) {
+    const declaredMin = thresholds?.scrapMinSamplesOf?.(m.id);
+    const minSamples = declaredMin ?? ATTENTION_DEFAULTS.scrapMinSamples;
+    if (total >= minSamples) {
       const rate = (m.scrapCount ?? 0) / total;
-      if (rate >= 0.15) out.push({
+      const declaredPct = thresholds?.scrapPctOf?.(m.id);
+      const thresholdPct = declaredPct ?? ATTENTION_DEFAULTS.scrapPct;
+      if (rate * 100 >= thresholdPct) out.push({
         id: `scrap:${m.id}`,
         kind: "scrap-high",
-        severity: rate >= 0.3 ? "high" : "medium",
+        severity: rate * 100 >= thresholdPct * 2 ? "high" : "medium",
         anchor: { moverId: m.id, locationId: m.location },
-        params: { moverId: m.id, goodCount: m.goodCount ?? 0, scrapCount: m.scrapCount ?? 0, ratePct: Math.round(rate * 100) },
+        params: {
+          moverId: m.id,
+          goodCount: m.goodCount ?? 0,
+          scrapCount: m.scrapCount ?? 0,
+          ratePct: Math.round(rate * 100),
+          thresholdPct,
+          basis: declaredPct === void 0 ? "default" : "declared"
+        },
         recommendedActions: [
           { code: "act.hold-for-inspection", command: CMD.resourceHold, args: { resourceId: m.id } },
           { code: "act.reset-metrics", command: CMD.resourceResetMetrics, args: { resourceId: m.id } }
@@ -3821,11 +3917,44 @@ var FlowEngine = class {
         tasks: [...this.tasks.values()]
       },
       this._acked,
-      now
+      now,
       // 지연 판정의 "지금" — 관측 중이면 마지막으로 들은 시각이다(§nowMs)
+      this.attentionThresholds()
     );
     return out;
   }
+  /**
+   * 현장이 선언한 판정 기준을 모델에서 뽑는다 — **규칙은 한 곳**(순수 함수는 모델을 읽지 않는다).
+   *
+   * 자리·설비의 속성에서 읽고, 없으면 `undefined` 를 돌려 기본값이 쓰이게 한다(그 사실은 판정 층이
+   * `basis` 로 밝힌다). 값이 수가 아니거나 범위를 벗어나면 **없는 것으로 본다** — 사람이 손으로 넣는
+   * 값이라 잘못 들어올 수 있고, 잘못된 기준으로 판정하는 것은 기본값보다 나쁘다.
+   */
+  attentionThresholds() {
+    const pct = (props, id) => {
+      const raw = props?.find((p) => p.id === id)?.value;
+      if (raw === void 0) return void 0;
+      const n = Number(raw);
+      return Number.isFinite(n) && n > 0 && n <= 100 ? n : void 0;
+    };
+    const count = (props, id) => {
+      const raw = props?.find((p) => p.id === id)?.value;
+      if (raw === void 0) return void 0;
+      const n = Number(raw);
+      return Number.isFinite(n) && n >= 1 ? Math.floor(n) : void 0;
+    };
+    const locProps = new Map(
+      (this.boardDef?.locations ?? []).map((l) => [l.id, l.properties])
+    );
+    const eqProps = new Map(
+      readBoardEquipment(this.boardDef ?? {}).map((e) => [e.id, e.properties])
+    );
+    return {
+      congestionPctOf: (id) => pct(locProps.get(id), ATTENTION_PROPERTY.congestionRatio),
+      scrapPctOf: (id) => pct(eqProps.get(id), ATTENTION_PROPERTY.scrapRate),
+      scrapMinSamplesOf: (id) => count(eqProps.get(id), ATTENTION_PROPERTY.scrapMinSamples)
+    };
+  }
   /**
    * fork — 현재 상태를 정확히 복제한 새 엔진 (디지털트윈 본연: "현재로부터 예측").
    * 원본(live/sim)은 계속 진행, fork 는 what-if 를 앞으로 시뮬레이션해 forecast·발산(predicted vs actual) 검사에 쓴다.
@@ -7111,6 +7240,8 @@ function retiredVocabularyIn(line) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ATTENTION_DEFAULTS,
+  ATTENTION_PROPERTY,
   BIZSTEP,
   BTT,
   BTT_DELIVERY,
@@ -7236,7 +7367,9 @@ function retiredVocabularyIn(line) {
   relationsFrom,
   relationsTo,
   replay,
+  replayFrom,
   replaySegments,
+  replayWithCheckpoint,
   requiredTestsFor,
   retiredVocabularyIn,
   sgtinClass,

package/package.json

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