@operato/twin-kernel 0.7.26 → 0.7.27

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/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

@@ -144,7 +144,9 @@ __export(index_exports, {
   relationsFrom: () => relationsFrom,
   relationsTo: () => relationsTo,
   replay: () => replay,
+  replayFrom: () => replayFrom,
   replaySegments: () => replaySegments,
+  replayWithCheckpoint: () => replayWithCheckpoint,
   requiredTestsFor: () => requiredTestsFor,
   retiredVocabularyIn: () => retiredVocabularyIn,
   sgtinClass: () => sgtinClass,
@@ -1584,6 +1586,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 +1704,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);
@@ -7236,7 +7300,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.27",
   "type": "module",
   "description": "Twin Domain Kernel — framework-agnostic, zero-dep (domain + sim + 3-channel contract). WMS/YMS/MES, EPCIS 2.0 · ISA-95.",
   "publishConfig": {