@things-factory/headless-twin 10.0.0-zeta.8 → 10.0.3

package/dist-server/engine/canonical-ingest.d.ts

@@ -0,0 +1,11 @@
+import { type IngestResult } from '@operato/twin-kernel';
+export interface CanonicalRecord {
+    epc: string;
+    action: string;
+    bizStep: string;
+    disposition?: string;
+    readPoint?: string;
+    bizLocation?: string;
+}
+/** 정규 레코드[] → 검증된 CanonicalEnvelope[] (+ 거부분). 순수 함수. 단일→객체도 배열로 정규화. */
+export declare function ingestCanonicalRecords(records: CanonicalRecord | CanonicalRecord[] | undefined | null, tenantId: string, defaultEventTime: string): IngestResult;

package/dist-server/engine/canonical-ingest.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ingestCanonicalRecords = ingestCanonicalRecords;
+const twin_kernel_1 = require("@operato/twin-kernel");
+/*
+ * 정규 레코드 → 커널 검증 ACL → CanonicalEnvelope (P1 seam 코어).
+ * 순수(커널만 의존; shell·integration-base 무의존 → node:test 검증 가능).
+ * 매핑(레거시 스키마 → 정규)은 이 앞 단계(jsonata step 또는 커넥터 openLiveFeed)가 끝낸다.
+ * 여기 도착하는 레코드는 이미 정규 필드다: { epc, action, bizStep, disposition?, readPoint?, bizLocation? }
+ * 커널은 objectEvent 구성 + EPCIS 검증(위반=오염 차단) + 봉투 래핑만(방언 없음).
+ *
+ * 두 소비처가 이 단일 코어를 공유(중복 금지):
+ *   - sim/scenario 경로: operato-twin twin-ingest 태스크(http-get→jsonata→여기).
+ *   - live 커넥터 경로: reference-live(어댑터 openLiveFeed→여기).
+ * SoT: design/integration/face2-adapters.md §5(seam)·§7(매핑=밖, 검증=커널).
+ */
+/** 고정 정규 매핑(방언 아님 — 필드명 자체가 정규 계약). sourceType='twin' 으로 매칭. */
+const TWIN_INGEST_RULES = [
+    {
+        sourceType: 'twin',
+        mapping: {
+            type: 'ObjectEvent',
+            action: '$.action',
+            bizStep: '$.bizStep',
+            disposition: '$.disposition',
+            epc: '$.epc',
+            readPoint: '$.readPoint',
+            bizLocation: '$.bizLocation'
+        }
+    }
+];
+/** 정규 레코드[] → 검증된 CanonicalEnvelope[] (+ 거부분). 순수 함수. 단일→객체도 배열로 정규화. */
+function ingestCanonicalRecords(records, tenantId, defaultEventTime) {
+    const arr = Array.isArray(records) ? records : records ? [records] : [];
+    const tagged = arr.map(r => ({ ...r, sourceType: 'twin' }));
+    return (0, twin_kernel_1.ingest)(tagged, TWIN_INGEST_RULES, { tenantId, defaultEventTime });
+}
+//# sourceMappingURL=canonical-ingest.js.map

package/dist-server/engine/canonical-ingest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-ingest.js","sourceRoot":"","sources":["../../server/engine/canonical-ingest.ts"],"names":[],"mappings":";;AAyCA,wDAQC;AAjDD,sDAAkF;AAElF;;;;;;;;;;;GAWG;AAEH,gEAAgE;AAChE,MAAM,iBAAiB,GAAkB;IACvC;QACE,UAAU,EAAE,MAAM;QAClB,OAAO,EAAE;YACP,IAAI,EAAE,aAAa;YACnB,MAAM,EAAE,UAAU;YAClB,OAAO,EAAE,WAAW;YACpB,WAAW,EAAE,eAAe;YAC5B,GAAG,EAAE,OAAO;YACZ,SAAS,EAAE,aAAa;YACxB,WAAW,EAAE,eAAe;SAC7B;KACF;CACF,CAAA;AAWD,yEAAyE;AACzE,SAAgB,sBAAsB,CACpC,OAA+D,EAC/D,QAAgB,EAChB,gBAAwB;IAExB,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;IACvE,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,CAAA;IAC3D,OAAO,IAAA,oBAAM,EAAC,MAAM,EAAE,iBAAiB,EAAE,EAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAC,CAAA;AAC1E,CAAC","sourcesContent":["import { ingest, type AdapterRule, type IngestResult } from '@operato/twin-kernel'\n\n/*\n * 정규 레코드 → 커널 검증 ACL → CanonicalEnvelope (P1 seam 코어).\n * 순수(커널만 의존; shell·integration-base 무의존 → node:test 검증 가능).\n * 매핑(레거시 스키마 → 정규)은 이 앞 단계(jsonata step 또는 커넥터 openLiveFeed)가 끝낸다.\n * 여기 도착하는 레코드는 이미 정규 필드다: { epc, action, bizStep, disposition?, readPoint?, bizLocation? }\n * 커널은 objectEvent 구성 + EPCIS 검증(위반=오염 차단) + 봉투 래핑만(방언 없음).\n *\n * 두 소비처가 이 단일 코어를 공유(중복 금지):\n *   - sim/scenario 경로: operato-twin twin-ingest 태스크(http-get→jsonata→여기).\n *   - live 커넥터 경로: reference-live(어댑터 openLiveFeed→여기).\n * SoT: design/integration/face2-adapters.md §5(seam)·§7(매핑=밖, 검증=커널).\n */\n\n/** 고정 정규 매핑(방언 아님 — 필드명 자체가 정규 계약). sourceType='twin' 으로 매칭. */\nconst TWIN_INGEST_RULES: AdapterRule[] = [\n  {\n    sourceType: 'twin',\n    mapping: {\n      type: 'ObjectEvent',\n      action: '$.action',\n      bizStep: '$.bizStep',\n      disposition: '$.disposition',\n      epc: '$.epc',\n      readPoint: '$.readPoint',\n      bizLocation: '$.bizLocation'\n    }\n  }\n]\n\nexport interface CanonicalRecord {\n  epc: string\n  action: string // ADD | OBSERVE | DELETE\n  bizStep: string\n  disposition?: string\n  readPoint?: string\n  bizLocation?: string\n}\n\n/** 정규 레코드[] → 검증된 CanonicalEnvelope[] (+ 거부분). 순수 함수. 단일→객체도 배열로 정규화. */\nexport function ingestCanonicalRecords(\n  records: CanonicalRecord | CanonicalRecord[] | undefined | null,\n  tenantId: string,\n  defaultEventTime: string\n): IngestResult {\n  const arr = Array.isArray(records) ? records : records ? [records] : []\n  const tagged = arr.map(r => ({ ...r, sourceType: 'twin' }))\n  return ingest(tagged, TWIN_INGEST_RULES, { tenantId, defaultEventTime })\n}\n"]}

package/dist-server/engine/entity-delta.d.ts

@@ -0,0 +1,7 @@
+export interface EntityDelta {
+    tag: string;
+    data: any;
+}
+/** 오더 집약 고정 태그 — 클라 provider(ORDERS_TAG)와 일치. */
+export declare const ORDERS_TAG = "__orders__";
+export declare function buildEntityDeltas(state: any): EntityDelta[];

package/dist-server/engine/entity-delta.js

@@ -0,0 +1,47 @@
+"use strict";
+/*
+ * 트윈 State 스냅샷 → 라이브 바인딩 delta 목록 (순수 매핑 — pubsub/도메인 무관 → 단위 테스트 가능).
+ * publishEntityData 가 이 목록을 엔티티별 시그니처로 dedup 후 data(tag) 채널로 발행한다.
+ * payload 계약은 씬 컴포넌트가 소비(twin-storage·mover·equipment·trend·order-tracker·resource-control):
+ *   node: occupancy/capacity/status/type · mover: location/motion/status/held/oee(정수 퍼센트) ·
+ *   order: status/progress/held · __orders__: 전체 오더 집약(Trackable 뷰).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ORDERS_TAG = void 0;
+exports.buildEntityDeltas = buildEntityDeltas;
+/** 오더 집약 고정 태그 — 클라 provider(ORDERS_TAG)와 일치. */
+exports.ORDERS_TAG = '__orders__';
+/** OEE 원시 비율/카운트 → 표시용 정수 퍼센트 + 카운트. 원시 누적 ms(idleMs 등)는 매 delta 증가해
+ *  무변화-생략을 무력화하므로 제외(idle 자원의 매초 재방송 억제). oee 미측정이면 undefined. */
+function shapeOee(o) {
+    if (!o)
+        return undefined;
+    return {
+        overall: Math.round((o.overall ?? 0) * 100),
+        availability: Math.round((o.availability ?? 0) * 100),
+        performance: Math.round((o.performance ?? 0) * 100),
+        quality: Math.round((o.quality ?? 0) * 100),
+        good: o.goodCount ?? 0,
+        scrap: o.scrapCount ?? 0
+    };
+}
+function buildEntityDeltas(state) {
+    const out = [];
+    for (const n of state?.nodes ?? []) {
+        out.push({ tag: n.id, data: { kind: 'node', occupancy: n.occupancy, capacity: n.capacity, status: n.status, type: n.type } });
+    }
+    for (const m of state?.movers ?? []) {
+        // Mobile(location/motion) + Operable(status/held) + Processable(oee) 를 한 payload 로.
+        out.push({ tag: m.id, data: { kind: 'mover', location: m.location, motion: m.motion, status: m.status, held: m.held, oee: shapeOee(m.oee) } });
+    }
+    for (const o of state?.orders ?? []) {
+        out.push({ tag: o.id, data: { kind: 'order', status: o.status, progress: o.progress, held: o.held } });
+    }
+    // 집약(Trackable) — 오더는 런타임 생성이라 개별 배치 불가 → 한 컴포넌트가 전체 추적(집약 N:M). 항상 방출.
+    out.push({
+        tag: exports.ORDERS_TAG,
+        data: { kind: 'orders', orders: (state?.orders ?? []).map((o) => ({ id: o.id, kind: o.kind, status: o.status, progress: o.progress, held: o.held })) }
+    });
+    return out;
+}
+//# sourceMappingURL=entity-delta.js.map

package/dist-server/engine/entity-delta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-delta.js","sourceRoot":"","sources":["../../server/engine/entity-delta.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * 트윈 State 스냅샷 → 라이브 바인딩 delta 목록 (순수 매핑 — pubsub/도메인 무관 → 단위 테스트 가능).\n * publishEntityData 가 이 목록을 엔티티별 시그니처로 dedup 후 data(tag) 채널로 발행한다.\n * payload 계약은 씬 컴포넌트가 소비(twin-storage·mover·equipment·trend·order-tracker·resource-control):\n *   node: occupancy/capacity/status/type · mover: location/motion/status/held/oee(정수 퍼센트) ·\n *   order: status/progress/held · __orders__: 전체 오더 집약(Trackable 뷰).\n */\n\nexport interface EntityDelta {\n  tag: string\n  data: any\n}\n\n/** 오더 집약 고정 태그 — 클라 provider(ORDERS_TAG)와 일치. */\nexport const ORDERS_TAG = '__orders__'\n\n/** OEE 원시 비율/카운트 → 표시용 정수 퍼센트 + 카운트. 원시 누적 ms(idleMs 등)는 매 delta 증가해\n *  무변화-생략을 무력화하므로 제외(idle 자원의 매초 재방송 억제). oee 미측정이면 undefined. */\nfunction shapeOee(o: any): any {\n  if (!o) return undefined\n  return {\n    overall: Math.round((o.overall ?? 0) * 100),\n    availability: Math.round((o.availability ?? 0) * 100),\n    performance: Math.round((o.performance ?? 0) * 100),\n    quality: Math.round((o.quality ?? 0) * 100),\n    good: o.goodCount ?? 0,\n    scrap: o.scrapCount ?? 0\n  }\n}\n\nexport function buildEntityDeltas(state: any): EntityDelta[] {\n  const out: EntityDelta[] = []\n  for (const n of state?.nodes ?? []) {\n    out.push({ tag: n.id, data: { kind: 'node', occupancy: n.occupancy, capacity: n.capacity, status: n.status, type: n.type } })\n  }\n  for (const m of state?.movers ?? []) {\n    // Mobile(location/motion) + Operable(status/held) + Processable(oee) 를 한 payload 로.\n    out.push({ tag: m.id, data: { kind: 'mover', location: m.location, motion: m.motion, status: m.status, held: m.held, oee: shapeOee(m.oee) } })\n  }\n  for (const o of state?.orders ?? []) {\n    out.push({ tag: o.id, data: { kind: 'order', status: o.status, progress: o.progress, held: o.held } })\n  }\n  // 집약(Trackable) — 오더는 런타임 생성이라 개별 배치 불가 → 한 컴포넌트가 전체 추적(집약 N:M). 항상 방출.\n  out.push({\n    tag: ORDERS_TAG,\n    data: { kind: 'orders', orders: (state?.orders ?? []).map((o: any) => ({ id: o.id, kind: o.kind, status: o.status, progress: o.progress, held: o.held })) }\n  })\n  return out\n}\n"]}

package/dist-server/engine/index.d.ts

@@ -1 +1,2 @@
 export * from './twin-engine.js';
+export * from './canonical-ingest.js';

package/dist-server/engine/index.js

@@ -2,4 +2,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 tslib_1.__exportStar(require("./twin-engine.js"), exports);
+tslib_1.__exportStar(require("./canonical-ingest.js"), exports);
 //# sourceMappingURL=index.js.map

package/dist-server/engine/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../server/engine/index.ts"],"names":[],"mappings":";;;AAAA,2DAAgC","sourcesContent":["export * from './twin-engine.js'\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../server/engine/index.ts"],"names":[],"mappings":";;;AAAA,2DAAgC;AAChC,gEAAqC","sourcesContent":["export * from './twin-engine.js'\nexport * from './canonical-ingest.js'\n"]}

package/dist-server/engine/live-attentions.d.ts

@@ -0,0 +1,6 @@
+export declare function withLiveAttentions<S extends {
+    movers?: any[];
+    nodes?: any[];
+    orders?: any[];
+    attentions?: any[];
+}>(state: S): S;

package/dist-server/engine/live-attentions.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withLiveAttentions = withLiveAttentions;
+/*
+ * live State attention 보강 — projector 미러 State(관측)에 커널 deriveAttentions(계산)를 채운다.
+ * live 스냅샷이 sim 동형(attentions 포함)이 되어 attention 질의/스트림이 live 에서도 신호를 준다.
+ * 순수(입력 불변). face2-inbound-live §1.1 "State-순수 파생"(입력이 미러 State 에 있어 재적용 가능).
+ * deriveAttentions 는 커널 공유 공식(sim/live 동일 임계값·규칙).
+ */
+const twin_kernel_1 = require("@operato/twin-kernel");
+function withLiveAttentions(state) {
+    if (!state)
+        return state;
+    return {
+        ...state,
+        attentions: (0, twin_kernel_1.deriveAttentions)({ movers: state.movers ?? [], nodes: state.nodes ?? [], orders: state.orders ?? [] })
+    };
+}
+//# sourceMappingURL=live-attentions.js.map

package/dist-server/engine/live-attentions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-attentions.js","sourceRoot":"","sources":["../../server/engine/live-attentions.ts"],"names":[],"mappings":";;AAQA,gDAMC;AAdD;;;;;GAKG;AACH,sDAAuD;AAEvD,SAAgB,kBAAkB,CAAkF,KAAQ;IAC1H,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAA;IACxB,OAAO;QACL,GAAG,KAAK;QACR,UAAU,EAAE,IAAA,8BAAgB,EAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;KACnH,CAAA;AACH,CAAC","sourcesContent":["/*\n * live State attention 보강 — projector 미러 State(관측)에 커널 deriveAttentions(계산)를 채운다.\n * live 스냅샷이 sim 동형(attentions 포함)이 되어 attention 질의/스트림이 live 에서도 신호를 준다.\n * 순수(입력 불변). face2-inbound-live §1.1 \"State-순수 파생\"(입력이 미러 State 에 있어 재적용 가능).\n * deriveAttentions 는 커널 공유 공식(sim/live 동일 임계값·규칙).\n */\nimport { deriveAttentions } from '@operato/twin-kernel'\n\nexport function withLiveAttentions<S extends { movers?: any[]; nodes?: any[]; orders?: any[]; attentions?: any[] }>(state: S): S {\n  if (!state) return state\n  return {\n    ...state,\n    attentions: deriveAttentions({ movers: state.movers ?? [], nodes: state.nodes ?? [], orders: state.orders ?? [] })\n  }\n}\n"]}

package/dist-server/engine/oee-accumulator.d.ts

@@ -0,0 +1,20 @@
+import type { CanonicalEnvelope, OeeCounters, OeeMetrics } from '@operato/twin-kernel';
+export declare class OeeAccumulator {
+    private acc;
+    private maxMs;
+    private ensure;
+    /** equipment.status(시간-in-상태) + quality.output(양품/불량) 소비. 다른 eventType 무시. */
+    apply(env: CanonicalEnvelope): void;
+    /** 무버 OEE 카운터 — 마지막 상태 구간을 nowMs(기본=최신 이벤트 시각)까지 flush. busy→run 근사, setup=0. */
+    counters(moverId: string, nowMs?: number): OeeCounters;
+    /** 공유 공식으로 근사 OEE 산출 — 정확한 OEE 는 실 텔레메트리(option ①). nowMs 기본=최신 이벤트 시각. */
+    oee(moverId: string, nowMs?: number): OeeMetrics;
+}
+/**
+ * live State 를 OEE 로 보강 — projector 미러 State(관측)의 무버에 누적기 OEE(계산)를 채운다.
+ * live-모드 publishEntityData 가 buildEntityDeltas 전에 적용 → mover data(tag) payload 에 oee 포함
+ * (sim 은 커널이 채움 — 이로써 live 도 동일 payload 형상). 순수(입력 불변, 얕은 복사).
+ */
+export declare function withLiveOee<S extends {
+    movers?: any[];
+}>(state: S, acc: OeeAccumulator, nowMs?: number): S;

package/dist-server/engine/oee-accumulator.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OeeAccumulator = void 0;
+exports.withLiveOee = withLiveOee;
+/*
+ * OEE 이벤트 누적기 (순수·근사) — live-모드 OEE 입력 생산의 한 경로(face2-inbound-live §1.1, option ②).
+ *
+ * 문제: OEE 공식(computeOee)은 sim/live 공유되나, 입력 카운터(runMs/downMs/…)는 미러 State·이벤트에 없다
+ *   (emitMover 는 status/location/motion 만 방출). → live 는 카운터를 별도 생산해야 한다.
+ * 이 누적기: equipment.status 전이 스트림으로 무버별 시간-in-상태를 누적해 카운터를 근사 생산.
+ *
+ * 정확: downMs(고장 시간 = down 구간 합) · quality(good/scrap = quality.output 델타). 근사·한계:
+ *   - busyMs 를 runMs 로(setup 분리 불가 — 이벤트에 setup 없음) → performance 낙관·availability 는 setup 손실 미반영.
+ *   - quality.output 이 없으면(예: WMS/YMS) quality=1(품질 개념 없음).
+ * 시간축 = Date.parse(eventTime)(ms) — 구간 차분은 sim/실시간 무관하게 정확(고정 오프셋 상쇄).
+ */
+const twin_kernel_1 = require("@operato/twin-kernel");
+class OeeAccumulator {
+    constructor() {
+        this.acc = new Map();
+        this.maxMs = 0; // 최신 이벤트 시각 — nowMs 기본값(현재 계측 시점)
+    }
+    ensure(moverId, t) {
+        let a = this.acc.get(moverId);
+        if (!a) {
+            a = { lastMs: t, startMs: t, busyMs: 0, downMs: 0, goodCount: 0, scrapCount: 0 };
+            this.acc.set(moverId, a);
+        }
+        return a;
+    }
+    /** equipment.status(시간-in-상태) + quality.output(양품/불량) 소비. 다른 eventType 무시. */
+    apply(env) {
+        const t = Date.parse(env.eventTime);
+        if (t > this.maxMs)
+            this.maxMs = t;
+        if (env.eventType === 'quality.output') {
+            const q = env.data;
+            if (!q?.moverId)
+                return;
+            const a = this.ensure(q.moverId, t);
+            a.goodCount = q.goodCount ?? a.goodCount; // 누적값 최신화(good/scrap 은 무버 누적)
+            a.scrapCount = q.scrapCount ?? a.scrapCount;
+            return;
+        }
+        if (env.eventType !== 'equipment.status')
+            return;
+        const d = env.data;
+        if (!d?.moverId)
+            return;
+        const a = this.ensure(d.moverId, t);
+        const dt = Math.max(0, t - a.lastMs);
+        if (a.status === 'busy')
+            a.busyMs += dt;
+        else if (a.status === 'down')
+            a.downMs += dt;
+        a.status = d.status;
+        a.lastMs = t;
+    }
+    /** 무버 OEE 카운터 — 마지막 상태 구간을 nowMs(기본=최신 이벤트 시각)까지 flush. busy→run 근사, setup=0. */
+    counters(moverId, nowMs = this.maxMs) {
+        const a = this.acc.get(moverId);
+        if (!a)
+            return { runMs: 0, setupMs: 0, downMs: 0, goodCount: 0, scrapCount: 0, metricsSinceMs: 0 };
+        const dt = Math.max(0, nowMs - a.lastMs);
+        let busyMs = a.busyMs;
+        let downMs = a.downMs;
+        if (a.status === 'busy')
+            busyMs += dt;
+        else if (a.status === 'down')
+            downMs += dt;
+        return { runMs: busyMs, setupMs: 0, downMs, goodCount: a.goodCount, scrapCount: a.scrapCount, metricsSinceMs: a.startMs };
+    }
+    /** 공유 공식으로 근사 OEE 산출 — 정확한 OEE 는 실 텔레메트리(option ①). nowMs 기본=최신 이벤트 시각. */
+    oee(moverId, nowMs = this.maxMs) {
+        return (0, twin_kernel_1.computeOee)(this.counters(moverId, nowMs), nowMs);
+    }
+}
+exports.OeeAccumulator = OeeAccumulator;
+/**
+ * live State 를 OEE 로 보강 — projector 미러 State(관측)의 무버에 누적기 OEE(계산)를 채운다.
+ * live-모드 publishEntityData 가 buildEntityDeltas 전에 적용 → mover data(tag) payload 에 oee 포함
+ * (sim 은 커널이 채움 — 이로써 live 도 동일 payload 형상). 순수(입력 불변, 얕은 복사).
+ */
+function withLiveOee(state, acc, nowMs) {
+    if (!state?.movers)
+        return state;
+    return { ...state, movers: state.movers.map(m => ({ ...m, oee: acc.oee(m.id, nowMs) })) };
+}
+//# sourceMappingURL=oee-accumulator.js.map

package/dist-server/engine/oee-accumulator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oee-accumulator.js","sourceRoot":"","sources":["../../server/engine/oee-accumulator.ts"],"names":[],"mappings":";;;AAoFA,kCAGC;AAvFD;;;;;;;;;;;GAWG;AACH,sDAAiD;AAajD,MAAa,cAAc;IAA3B;QACU,QAAG,GAAG,IAAI,GAAG,EAAe,CAAA;QAC5B,UAAK,GAAG,CAAC,CAAA,CAAC,kCAAkC;IAkDtD,CAAC;IAhDS,MAAM,CAAC,OAAe,EAAE,CAAS;QACvC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;QAC7B,IAAI,CAAC,CAAC,EAAE,CAAC;YACP,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,CAAA;YAChF,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;QAC1B,CAAC;QACD,OAAO,CAAC,CAAA;IACV,CAAC;IAED,8EAA8E;IAC9E,KAAK,CAAC,GAAsB;QAC1B,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;QACnC,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK;YAAE,IAAI,CAAC,KAAK,GAAG,CAAC,CAAA;QAClC,IAAI,GAAG,CAAC,SAAS,KAAK,gBAAgB,EAAE,CAAC;YACvC,MAAM,CAAC,GAAG,GAAG,CAAC,IAAqE,CAAA;YACnF,IAAI,CAAC,CAAC,EAAE,OAAO;gBAAE,OAAM;YACvB,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;YACnC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,SAAS,CAAA,CAAC,8BAA8B;YACvE,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,UAAU,CAAA;YAC3C,OAAM;QACR,CAAC;QACD,IAAI,GAAG,CAAC,SAAS,KAAK,kBAAkB;YAAE,OAAM;QAChD,MAAM,CAAC,GAAG,GAAG,CAAC,IAA6C,CAAA;QAC3D,IAAI,CAAC,CAAC,EAAE,OAAO;YAAE,OAAM;QACvB,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;QACnC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAA;QACpC,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM;YAAE,CAAC,CAAC,MAAM,IAAI,EAAE,CAAA;aAClC,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM;YAAE,CAAC,CAAC,MAAM,IAAI,EAAE,CAAA;QAC5C,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAA;QACnB,CAAC,CAAC,MAAM,GAAG,CAAC,CAAA;IACd,CAAC;IAED,iFAAiF;IACjF,QAAQ,CAAC,OAAe,EAAE,QAAgB,IAAI,CAAC,KAAK;QAClD,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;QAC/B,IAAI,CAAC,CAAC;YAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,CAAA;QAClG,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC,CAAA;QACxC,IAAI,MAAM,GAAG,CAAC,CAAC,MAAM,CAAA;QACrB,IAAI,MAAM,GAAG,CAAC,CAAC,MAAM,CAAA;QACrB,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM;YAAE,MAAM,IAAI,EAAE,CAAA;aAChC,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM;YAAE,MAAM,IAAI,EAAE,CAAA;QAC1C,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,UAAU,EAAE,CAAC,CAAC,UAAU,EAAE,cAAc,EAAE,CAAC,CAAC,OAAO,EAAE,CAAA;IAC3H,CAAC;IAED,2EAA2E;IAC3E,GAAG,CAAC,OAAe,EAAE,QAAgB,IAAI,CAAC,KAAK;QAC7C,OAAO,IAAA,wBAAU,EAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,KAAK,CAAC,CAAA;IACzD,CAAC;CACF;AApDD,wCAoDC;AAED;;;;GAIG;AACH,SAAgB,WAAW,CAA+B,KAAQ,EAAE,GAAmB,EAAE,KAAc;IACrG,IAAI,CAAC,KAAK,EAAE,MAAM;QAAE,OAAO,KAAK,CAAA;IAChC,OAAO,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,CAAA;AAC3F,CAAC","sourcesContent":["/*\n * OEE 이벤트 누적기 (순수·근사) — live-모드 OEE 입력 생산의 한 경로(face2-inbound-live §1.1, option ②).\n *\n * 문제: OEE 공식(computeOee)은 sim/live 공유되나, 입력 카운터(runMs/downMs/…)는 미러 State·이벤트에 없다\n *   (emitMover 는 status/location/motion 만 방출). → live 는 카운터를 별도 생산해야 한다.\n * 이 누적기: equipment.status 전이 스트림으로 무버별 시간-in-상태를 누적해 카운터를 근사 생산.\n *\n * 정확: downMs(고장 시간 = down 구간 합) · quality(good/scrap = quality.output 델타). 근사·한계:\n *   - busyMs 를 runMs 로(setup 분리 불가 — 이벤트에 setup 없음) → performance 낙관·availability 는 setup 손실 미반영.\n *   - quality.output 이 없으면(예: WMS/YMS) quality=1(품질 개념 없음).\n * 시간축 = Date.parse(eventTime)(ms) — 구간 차분은 sim/실시간 무관하게 정확(고정 오프셋 상쇄).\n */\nimport { computeOee } from '@operato/twin-kernel'\nimport type { CanonicalEnvelope, OeeCounters, OeeMetrics } from '@operato/twin-kernel'\n\ninterface Acc {\n  status?: string\n  lastMs: number\n  startMs: number\n  busyMs: number\n  downMs: number\n  goodCount: number\n  scrapCount: number\n}\n\nexport class OeeAccumulator {\n  private acc = new Map<string, Acc>()\n  private maxMs = 0 // 최신 이벤트 시각 — nowMs 기본값(현재 계측 시점)\n\n  private ensure(moverId: string, t: number): Acc {\n    let a = this.acc.get(moverId)\n    if (!a) {\n      a = { lastMs: t, startMs: t, busyMs: 0, downMs: 0, goodCount: 0, scrapCount: 0 }\n      this.acc.set(moverId, a)\n    }\n    return a\n  }\n\n  /** equipment.status(시간-in-상태) + quality.output(양품/불량) 소비. 다른 eventType 무시. */\n  apply(env: CanonicalEnvelope): void {\n    const t = Date.parse(env.eventTime)\n    if (t > this.maxMs) this.maxMs = t\n    if (env.eventType === 'quality.output') {\n      const q = env.data as { moverId?: string; goodCount?: number; scrapCount?: number }\n      if (!q?.moverId) return\n      const a = this.ensure(q.moverId, t)\n      a.goodCount = q.goodCount ?? a.goodCount // 누적값 최신화(good/scrap 은 무버 누적)\n      a.scrapCount = q.scrapCount ?? a.scrapCount\n      return\n    }\n    if (env.eventType !== 'equipment.status') return\n    const d = env.data as { moverId?: string; status?: string }\n    if (!d?.moverId) return\n    const a = this.ensure(d.moverId, t)\n    const dt = Math.max(0, t - a.lastMs)\n    if (a.status === 'busy') a.busyMs += dt\n    else if (a.status === 'down') a.downMs += dt\n    a.status = d.status\n    a.lastMs = t\n  }\n\n  /** 무버 OEE 카운터 — 마지막 상태 구간을 nowMs(기본=최신 이벤트 시각)까지 flush. busy→run 근사, setup=0. */\n  counters(moverId: string, nowMs: number = this.maxMs): OeeCounters {\n    const a = this.acc.get(moverId)\n    if (!a) return { runMs: 0, setupMs: 0, downMs: 0, goodCount: 0, scrapCount: 0, metricsSinceMs: 0 }\n    const dt = Math.max(0, nowMs - a.lastMs)\n    let busyMs = a.busyMs\n    let downMs = a.downMs\n    if (a.status === 'busy') busyMs += dt\n    else if (a.status === 'down') downMs += dt\n    return { runMs: busyMs, setupMs: 0, downMs, goodCount: a.goodCount, scrapCount: a.scrapCount, metricsSinceMs: a.startMs }\n  }\n\n  /** 공유 공식으로 근사 OEE 산출 — 정확한 OEE 는 실 텔레메트리(option ①). nowMs 기본=최신 이벤트 시각. */\n  oee(moverId: string, nowMs: number = this.maxMs): OeeMetrics {\n    return computeOee(this.counters(moverId, nowMs), nowMs)\n  }\n}\n\n/**\n * live State 를 OEE 로 보강 — projector 미러 State(관측)의 무버에 누적기 OEE(계산)를 채운다.\n * live-모드 publishEntityData 가 buildEntityDeltas 전에 적용 → mover data(tag) payload 에 oee 포함\n * (sim 은 커널이 채움 — 이로써 live 도 동일 payload 형상). 순수(입력 불변, 얕은 복사).\n */\nexport function withLiveOee<S extends { movers?: any[] }>(state: S, acc: OeeAccumulator, nowMs?: number): S {\n  if (!state?.movers) return state\n  return { ...state, movers: state.movers.map(m => ({ ...m, oee: acc.oee(m.id, nowMs) })) }\n}\n"]}

package/dist-server/engine/twin-engine.d.ts

@@ -1,22 +1,228 @@
-import type { BoardDef, TwinRuntime as TwinRuntimeType } from '@operato/twin-kernel';
-interface TwinInstance {
+import { type ReferenceMaster } from '../service/reference/reference-master.js';
+import { OeeAccumulator } from './oee-accumulator.js';
+import type { BoardDef, TwinRuntime as TwinRuntimeType, CanonicalEnvelope } from '@operato/twin-kernel';
+interface TwinMetrics {
+    ingestedTotal: number;
+    broadcastTotal: number;
+    journaledTotal: number;
+    ingestRate: number;
+    broadcastRate: number;
+    journalRate: number;
+    backlog: number;
+    _accIngest: number;
+    _accBroadcast: number;
+    _accJournal: number;
+    _windowStartMs: number;
+}
+export type RealityMode = 'mirror' | 'sim-world' | 'sim-experiment';
+export declare const DEFAULT_REALITY_MODE: RealityMode;
+interface InstanceRuntime {
+    /** 현실 출처 선언(§0 프레임 ①). 부팅 거동(reset/resume/resync)의 근거. */
+    realityMode?: RealityMode;
     id: string;
     domainId: string;
-    runtime: TwinRuntimeType;
+    domain?: any;
+    runtime?: TwinRuntimeType;
+    kernel?: any;
+    mode?: 'sim' | 'live';
+    projector?: any;
+    oee?: OeeAccumulator;
     unsub: () => void;
     timer?: any;
+    /** 엔티티별 마지막 발행 시그니처 — 값이 바뀐 엔티티만 재발행(무변화 반복 push 방지). */
+    entitySigs?: Map<string, string>;
+    /** live 방송 병합(ingest-scale §4.4) — ingest 마다 방송하지 않고 dirty 표시 → coalescer tick 이 주기 방송. */
+    dirty?: boolean;
+    /** live 저널 결선 — ingest 이벤트를 모았다가 coalescer tick 에서 배치 기록(이벤트마다 DB write 금지). */
+    pendingJournal?: any[];
+    /** live 저널 revision 카운터(sim 의 delta revision 대응 — 시간여행·히스토리 노브 앵커). */
+    revision?: number;
+    /** live 처리량 계측(모니터, ④-1). */
+    metrics?: TwinMetrics;
 }
 export declare class TwinEngine {
-    static instances: Record<string, TwinInstance>;
+    static instances: Record<string, InstanceRuntime>;
+    /** 라이브 런타임이 없을 때(복구 후 미기동) 저널에서 재구성한 상태 캐시. */
+    static recovered: Record<string, any>;
     static TICK_MS: number;
-    /** 부팅 훅 — 영속 인스턴스 복구(DB→replay)는 향후. 지금은 명시 start 로 인스턴스 생성. */
+    static SNAPSHOT_CACHE_ID: string;
+    static SNAPSHOT_TTL_S: number;
+    static CHECKPOINT_MS: number;
+    private static checkpointTimer?;
+    /** 최신 스냅샷을 cache-service 에 체크포인트(도메인+instanceId 키). display-only·비차단·오류흡수. */
+    static persistSnapshot(domainId: string, instanceId: string): Promise<void>;
+    /** 체크포인트된 최신 스냅샷 로드(없으면 null). getFromCache 는 CacheStore 엔티티를 반환 → 페이로드는 .value. */
+    static loadSnapshot(domainId: string, instanceId: string): Promise<{
+        revision: number;
+        state: any;
+    } | null>;
+    /** 체크포인트 루프 기동(1회) — 라이브 인스턴스들의 최신 스냅샷을 주기 영속. */
+    static startCheckpointLoop(): void;
+    /**
+     * 부팅 훅 — DB 에 status='running' 으로 남은 인스턴스를 저널에서 상태 재구성(DB→replay).
+     * 라이브 tick 재개(sim 결정적 re-run / live 인제스트 지속)는 후속. 여기선 상태 복원 + 노출.
+     */
     static bootstrap(): Promise<void>;
-    /** 트윈 인스턴스 시작 — 커널 생성 + 보드 로드 + State 스트림 브리지 + 워커 tick. */
-    static start(id: string, domainId: string, kind: string, board: BoardDef): TwinInstance;
+    /** 트윈 인스턴스 시작 — 커널 생성 + 보드 로드 + State 스트림 브리지 + 워커 tick + 레지스트리 영속. */
+    static start(id: string, domainId: string, kind: string, board: BoardDef, realityMode?: RealityMode): InstanceRuntime;
+    /**
+     * live-모드 기동(face2-inbound-live §1.1) — 커널 tick 대신 StateProjector 로 실 이벤트를 미러.
+     * 관측 상태(점유·위치·아이템)는 projector 가 재구성 → sim 과 동일 data(tag) payload → **보드 컴포넌트 동일 렌더**
+     * (live-mirror-parity 로 payload 층 검증됨). 계산 층(attentions·OEE)은 이벤트에 없어 부재 — derive 층은 후속.
+     * 실 이벤트원 = reference 어댑터 openLiveFeed → face2-adapter.ingest → CanonicalEnvelope → ingestLive().
+     */
+    static startLive(id: string, domainId: string, kind: string, board: BoardDef): InstanceRuntime;
+    /**
+     * live 이벤트 인제스트 — projector 구동 + data(tag) 방송(폐루프의 인바운드 도착 지점, command-routing §8.2).
+     * reference 어댑터가 낸 records → 커널 face2-adapter.ingest → CanonicalEnvelope 를 여기로 밀어넣는다.
+     * (State 채널 델타/저널 결선은 후속 — 스켈레톤은 data(tag) 미러 중심.)
+     */
+    static ingestLive(id: string, envelopes: CanonicalEnvelope[]): void;
+    /** 방송 병합 주기(ms) — 방송률 상한. 인제스트가 아무리 빨라도 이 주기로만 방송. */
+    static BROADCAST_COALESCE_MS: number;
+    private static broadcastTimer?;
+    /** live 방송 coalescer — dirty 인 live 인스턴스만 주기적으로 1회 방송(entitySigs 로 변경 엔티티만). */
+    private static ensureBroadcastCoalescer;
+    /** dirty live 인스턴스 방송 flush(주기 tick 또는 명시 호출). 테스트/즉시 방송용으로 public. */
+    static flushLiveBroadcasts(): void;
+    /** live 저널 배치 기록 — 모아둔 CanonicalEnvelope 들에 startRevision+1.. 을 부여해 벌크 저장(coalescer tick 당 1회). */
+    static persistBatch(domainId: string, instanceId: string, envelopes: any[], startRevision: number): Promise<void>;
+    /** 레지스트리 upsert(도메인+instanceId 유니크). status 인자로 provision(stopped)/start(running) 공용. */
+    static register(domainId: string, instanceId: string, kind: string, board: BoardDef, status?: 'running' | 'stopped', realityMode?: RealityMode): Promise<void>;
+    /**
+     * 라이브 구조 변이(resource.add 등)를 저장된 board 에 반영 — 런타임 커널의 무버를 registry board.movers 에 동기.
+     * 이게 없으면 런타임엔 추가돼도(상태·저널엔 반영) 저장 board 는 원본이라 프로비저닝 편집기·재기동(loadBoard)이
+     * 추가분을 잃는다. 기존 board.movers 항목은 보존(homeNode 유지)하고 새 id 만 append(추가 시점 location=homeNode).
+     * 좌표(layout)만 다루는 register 와 달리 movers 집합을 갱신하나, 재프로비전(purge)이 아니라 in-place 갱신이라
+     * 저널은 보존된다(추가는 이미 equipment 델타로 저널됨 → replay 는 id-keyed upsert 라 이중계산 없음).
+     */
+    static syncBoardMovers(domainId: string, instanceId: string): Promise<void>;
+    /**
+     * 프로비저닝 — 레지스트리에 구조(board)를 등록만 하고 기동하지 않음(status='stopped').
+     * 재프로비전 시 구조 시그니처가 바뀌면(노드·무버 집합/속성 변경) 기존 저널을 purge 한다(ADR-0015):
+     * board 는 replay 의 마스터라 구조가 바뀌면 과거 이벤트의 전제가 깨진다. 좌표(layout)만 바뀌면 저널 보존.
+     */
+    static provision(domainId: string, instanceId: string, kind: string, board: BoardDef): Promise<void>;
+    /** 구조 동일성 지문 — 좌표(layout) 등 뷰 관심사는 제외하고 커널이 보는 위상·용량·무버만. */
+    private static structureSignature;
+    /** 레지스트리 board 로 기동(프로비전된 인스턴스 start). board 인자 없이 저장된 구조로 재기동. */
+    static startFromRegistry(domainId: string, instanceId: string, realityMode?: RealityMode): Promise<InstanceRuntime>;
+    /**
+     * 선언 기반 부팅(§0 프레임 ① → 부팅 거동 매핑) — 트윈이 선언한 realityMode 에 따라 재기동 방식을 가른다.
+     * 부팅 경로를 한 곳에 모아 "런타임 ≠ 현실" 범주오류를 코드로 강제한다.
+     *   - 'mirror'         : 현실=외부 실물 → startLive(재동기). 이벤트는 어댑터 ingest 로 유입, 커널 tick 없음.
+     *   - 'sim-world'      : 생성 타임라인 지속 → 저널 보존 + resume(현실 이어감).
+     *                        ⚠ GATE(§8 ②③): 커널 상태 직렬화/재개가 아직 없어 진짜 resume 불가 → 실 필요·실부하 시 구현.
+     *                        그때까지는 저널을 보존하되 revision 충돌을 피하려 fresh 로 기동하고, 선언과 구현의 간극을 크게 경고한다.
+     *   - 'sim-experiment' : seed 재현 → resetJournal + fresh 기동(백지 시작이 버그가 아니라 선언된 거동).
+     * 반환: 기동된 InstanceRuntime.
+     */
+    static bootDeclared(domainId: string, instanceId: string, mode?: RealityMode): Promise<InstanceRuntime>;
+    /**
+     * 저널 초기화 — 인스턴스 이벤트 저널 purge(레지스트리·상태는 유지).
+     * 데모 fresh-start 용: 매 부팅 seed 부터 새로 실행하는 데모에서, 복구본 폐기 후 revision 0 부터 재실행하면
+     * 옛 런과 revision 이 겹쳐 저널이 오염된다 → start 전에 호출해 현재 런만 남긴다.
+     */
+    static resetJournal(domainId: string, instanceId: string): Promise<void>;
+    /** 삭제 — 정지 + 레지스트리 삭제 + 저널 purge(domain 스코프). */
+    static remove(domainId: string, instanceId: string): Promise<void>;
+    /** 관리 목록 — domain 의 등록 인스턴스 전체(라이브 여부·최신 저널 revision·노드/무버 수 포함). */
+    static list(domainId: string): Promise<any[]>;
+    /** 레거시 벤치 잔재 가드 — purpose 도입 전 만들어진 벤치/부하 공간(이름 규약)까지 걸러낸다. */
+    static isBenchSpace(spaceId?: string): boolean;
+    /** 운영 공간 목록(벤치 소스 선택기) — 이름·규모 포함, 벤치 사본·잔재 제외. */
+    static listSpaces(domainId: string): Promise<{
+        spaceId: string;
+        name: string;
+        instances: number;
+        nodes: number;
+        movers: number;
+    }[]>;
+    /** 인스턴스 목적 표식(운영/벤치) 설정 — 벤치 사본을 1급 속성으로 구별(이름 접두사 아님). */
+    static setPurpose(domainId: string, instanceId: string, purpose: 'operational' | 'bench', copyOf?: string): Promise<void>;
+    /**
+     * 공간 구조 판독 — 완전복제(벤치 사본)의 소스. 저장물이 board(위상)·TwinSpace.content(치수·geo·표현)·TwinArea(영역)로
+     * 분산돼 있으므로 셋을 모아 돌려준다. 호출측이 ReferenceMaster 로 재구성 → 재식별 → ingestMaster.
+     */
+    static spaceStructure(domainId: string, spaceId: string): Promise<{
+        name?: string;
+        content: any;
+        areas: any[];
+        instances: {
+            instanceId: string;
+            kind?: string;
+            board: any;
+        }[];
+    } | null>;
+    /** 공간(+표현·영역) 삭제 — 벤치 정리 등. 호출측이 바인딩 인스턴스를 먼저 제거하는 전제(가드 없음). deleteTwinSpace 리졸버와 동형. */
+    static deleteSpace(domainId: string, spaceId: string): Promise<void>;
+    /**
+     * Face2 마스터 인제스트(ADR-0018) — 레퍼런스 시스템(실 또는 가상)의 마스터를 읽어 트윈을 생성.
+     * 엔티티를 손배선/발명하지 않고 마스터에서 반영: 공간(Space) upsert + 인스턴스 provision(미기동).
+     * 노드타입은 커널 카탈로그로 검증(warning). start 는 호출측(bootstrap/mutation)이 결정.
+     */
+    static ingestMaster(domainId: string, master: ReferenceMaster): Promise<{
+        instanceId: string;
+        spaceId: string;
+        warnings: string[];
+    }>;
+    /** 단건 상세 — 프로비저닝 에디터가 편집할 board(구조+layout) 포함. */
+    static detail(domainId: string, instanceId: string): Promise<any | null>;
+    /**
+     * 라이브 바인딩 브리지(P3, ADR-0018) — 트윈 엔티티 상태를 `data(tag=엔티티id)` 채널로 publish.
+     * 보드 컴포넌트가 tag 로 구독(board-ui provider)해 `component.data` 로 라이브 갱신. delta 시에만(희소).
+     * tag=엔티티 id(데모=단일 인스턴스). 멀티 인스턴스/보드 재사용 시 tag 네임스페이스는 후속.
+     */
+    static publishEntityData(inst: InstanceRuntime): void;
     static persist(domainId: string, instanceId: string, msg: any): Promise<void>;
-    static stop(id: string): void;
+    /**
+     * 재부팅 복구 / 시간여행 — DB 저널을 replay 해 상태 재구성.
+     * board 는 레지스트리(TwinInstance)에서, 이벤트는 TwinEvent(revision ASC)에서.
+     * 커서 두 축(runtime-state-model §4): **시각(untilTime, 사용자 모국어·공간 공통축)** 우선, 없으면 리비전(untilRevision, 렌즈 내부).
+     *   - untilTime 주면 `eventTime ≤ T` 인 이벤트만(그 시점 watermark) — 공동배치 여러 트윈을 하나의 시각 T로 통일 해소.
+     *   - 둘 다 없으면 최신(라이브 인메모리 진실).
+     * 이벤트는 항상 revision ASC(인과 순서)로 적용 — 시각 필터는 컷오프 집합만 정한다.
+     */
+    static recover(domainId: string, instanceId: string, untilRevision?: number, untilTime?: string): Promise<any>;
+    /**
+     * 공간(공동배치) 시각 범위 — 스크러버 앵커(runtime-state-model §4·§6). 그 공간 전 인스턴스 저널의 min/max eventTime.
+     * 반환 {minTime, maxTime}(ISO) — 이벤트/시각 없으면 null. 클라 히스토리 스크러버가 이 범위를 시각축으로 그린다.
+     */
+    static timeRange(domainId: string, spaceId: string): Promise<{
+        minTime: string | null;
+        maxTime: string | null;
+    }>;
+    /** 정지 훅 — 인스턴스 정지 시 부수자원 정리(예: reference-live 피드 unsubscribe). 순환 임포트 없이 결선. */
+    static stopHooks: ((id: string) => void)[];
+    static onStop(fn: (id: string) => void): void;
+    static stop(id: string): Promise<void>;
     static runtime(id: string): TwinRuntimeType | undefined;
-    /** 현재 전체 스냅샷(구독 즉시 발행·resync 용). */
+    /**
+     * 도메인 소유 게이트 — 인스턴스가 이 도메인 소유일 때만 true(테넌트 격리).
+     * 없거나 다른 도메인이면 false. 노출 리졸버(per-id metrics/attentions/state/stop/forecast)가
+     * this.instances[id] 를 만지기 전에 반드시 이걸로 확인해야 한다. 인스턴스 id 는 추측 가능하므로
+     * 검증 없이 접근하면 크로스테넌트 읽기/정지가 가능해진다.
+     */
+    static owns(domainId: string, id: string): boolean;
+    /** 라이브 커널(ForecastTwin) — forecast/divergence 예측 연산용. */
+    static kernel(id: string): any;
+    /** 라이브 처리량 계측 스냅샷(모니터, ④-1) — 내부 누적(_acc*) 제외한 공개 지표. live 아니면 null. */
+    static metrics(id: string): any;
+    /** 전체 라이브 인스턴스 계측(모니터 대시보드용). */
+    static allMetrics(domainId?: string): Promise<any[]>;
+    /**
+     * 라이브 예측용 임시 커널(kernel-unification P1) — 라이브는 projector 미러라 커널이 없어 예측을 못 한다.
+     * 관측 스냅샷(재고·무버·노드) + 저널의 오더 원값·라인을 hydrate 해 예측 가능한 임시 커널을 만든다.
+     * 라이브 런타임은 무간섭(이 커널은 fork 대상 임시본, instances 에 넣지 않음). sim 인스턴스면 null(그쪽은 kernel() 사용).
+     */
+    static buildForecastKernel(domainId: string, instanceId: string): Promise<any | null>;
+    /**
+     * 예측용 커널을 **임의 시각 T 기준**으로 재구성 — 과거-vantage 예측(백테스트)·"그때 서서 본 미래".
+     * recover(untilTime)로 T 시점 상태를, T 이하 오더 관측을 모아 hydrate → monteCarloForecast 가 T 에서 앞으로 굴린다.
+     * sim/live 무관(저널 기반 재구성). untilTime 생략 시 최신. 도메인 스코프(reg·journal 조회가 domainId).
+     */
+    static buildForecastKernelAt(domainId: string, instanceId: string, untilTime?: string): Promise<any | null>;
+    /** 현재 전체 스냅샷 — 라이브 우선, 없으면 저널 복구 캐시. */
     static snapshot(id: string): any;
 }
 export {};