@things-factory/headless-twin 10.0.8 → 10.0.10

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

@@ -1,8 +1,12 @@
+import type { ReducerCheckpoint } from '@operato/twin-kernel';
+import type { OeeCheckpoint } from './oee-accumulator.js';
 import { type ReferenceMaster } from '../service/reference/reference-master.js';
+import { type IngestWarning } from '../service/reference/reference-master.js';
 import { type ModelBasis } from './model-basis.js';
+import { type LoadMeter, type LoadPhase } from './load-meter.js';
 import { type StructureDiff } from './structure-diff.js';
 import { OeeAccumulator } from './oee-accumulator.js';
-import type { BoardDef, TwinRuntime as TwinRuntimeType, CanonicalEnvelope } from '@operato/twin-kernel';
+import type { TwinModelDef, StructureShift, TwinRuntime as TwinRuntimeType, CanonicalEnvelope } from '@operato/twin-kernel';
 interface TwinMetrics {
     ingestedTotal: number;
     broadcastTotal: number;
@@ -19,6 +23,8 @@ interface TwinMetrics {
 export type RealityMode = 'mirror' | 'sim-world' | 'sim-experiment';
 export declare const DEFAULT_REALITY_MODE: RealityMode;
 interface InstanceRuntime {
+    /** 부하 계기판 — 작업별 소요. 시뮬·라이브 모두 붙는다(누가 루프를 점유하는지 보려면 둘 다 필요하다). */
+    load?: LoadMeter;
     /** 현실 출처 선언(§0 프레임 ①). 부팅 거동(reset/resume/resync)의 근거. */
     realityMode?: RealityMode;
     id: string;
@@ -27,6 +33,8 @@ interface InstanceRuntime {
     runtime?: TwinRuntimeType;
     kernel?: any;
     mode?: 'sim' | 'live';
+    /** 이 트윈이 선 현장 — 같은 현장의 트윈끼리 서로의 설비 상태를 읽을 수 있게 하는 열쇠. */
+    spaceId?: string;
     /**
      * live 의 상태 접근 어댑터 — 이제 **관측 모드 커널**을 가리킨다(`kernel` 과 같은 것).
      * 이름은 소비처 호환으로 남았고, P3 에서 커널 어휘로 정리하면 사라진다.
@@ -34,6 +42,11 @@ interface InstanceRuntime {
     projector?: any;
     oee?: OeeAccumulator;
     unsub: () => void;
+    /**
+     * 방금 인입한 봉투들 — 커널이 그것을 재방출할 때 **저널에 두 번 적지 않기** 위한 표시.
+     * 라이브만 쓴다(sim 은 커널이 스스로 낸 것만 흘린다). 약한 참조라 따로 비울 것이 없다.
+     */
+    applying?: WeakSet<object>;
     timer?: any;
     /** 엔티티별 마지막 발행 시그니처 — 값이 바뀐 엔티티만 재발행(무변화 반복 push 방지). */
     entitySigs?: Map<string, string>;
@@ -46,22 +59,93 @@ interface InstanceRuntime {
     /** live 처리량 계측(모니터, ④-1). */
     metrics?: TwinMetrics;
 }
+/**
+ * 트윈이 **스스로 멈춘 이유** — 문장이 아니라 코드다.
+ *
+ * 서버가 만든 영어 문장을 그대로 실으면 한국어·일본어 화면에 그 영어가 뜬다. 이 시스템은 거절 메시지에서
+ * 같은 결론에 이르렀다(코드+파라미터를 내고 화면이 옮긴다). `reason` 만은 원문 그대로다 — 커널·런타임이
+ * 낸 오류 문구는 옮길 수 있는 어휘가 아니고, 옮기려 들면 원인을 잃는다.
+ */
+export interface StopNote {
+    code: 'starved' | 'tick-failed';
+    params: Record<string, string | number>;
+}
 export declare class TwinEngine {
     static instances: Record<string, InstanceRuntime>;
     /** 라이브 런타임이 없을 때(복구 후 미기동) 저널에서 재구성한 상태 캐시. */
+    /** 웜스타트 씨앗 — `instances` 와 **같은 키**(겹치면 남의 스냅샷으로 재고가 섞인다). */
     static recovered: Record<string, any>;
     static TICK_MS: number;
+    /** 굶김 문턱 — 틱 간격의 배수(1초 간격이면 5초). 이 시간만큼 호스트가 멈춘다. */
+    static STARVE_FACTOR: number;
+    /** 연속 몇 번이면 멈추나 — 3번이면 15초를 굶긴 셈이고, 그건 우연이 아니다. */
+    static STARVE_STREAK: number;
+    private static starveStreak;
+    /**
+     * 왜 멈췄나 — **화면이 그대로 말할 수 있게.** 스스로 멈춘 트윈이 이유 없이 「정지」로만 보이면
+     * 사람은 자기가 멈춘 줄 안다. 메모리에만 둔다(재기동하면 사라진다 — 그때는 「모른다」가 사실이다).
+     */
+    private static stopNotes;
     static SNAPSHOT_CACHE_ID: string;
+    static CHAIN_CACHE_ID: string;
+    static CHAIN_INDEX_CACHE_ID: string;
+    static CHAIN_STRIDE: number;
+    static CHAIN_KEEP: number;
     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>;
+    /**
+     * 접기의 **재개점** — 리듀서 내부 상태 전부 + 가동 누적기.
+     *
+     * 스냅샷(`state`)은 소비처가 보는 값이라 이어 접기의 씨앗이 되지 못한다(보류된 담김·집합·반영 못 한
+     * 사건 집계가 없다 — 그 상태로 뒤를 접으면 0부터 접은 결과와 조용히 달라진다). 그래서 씨앗은 따로 든다.
+     */
+    private static readonly FOLD_NOTE;
     /** 체크포인트된 최신 스냅샷 로드(없으면 null). getFromCache 는 CacheStore 엔티티를 반환 → 페이로드는 .value. */
     static loadSnapshot(domainId: string, instanceId: string): Promise<{
         revision: number;
         state: any;
+        structureRev?: number | null;
+        fold?: {
+            reducer: ReducerCheckpoint;
+            oee: OeeCheckpoint;
+        };
     } | null>;
+    /**
+     * 접은 상태를 스냅샷으로 남긴다 — **라이브가 아니어도.**
+     *
+     * `persistSnapshot` 은 기동 중인 인스턴스에서만 뜬다(메모리가 진실이므로 옳다). 그런데 **멈춘**
+     * 트윈을 조회할 때마다 저널을 전량 다시 접고 있었다(23,731건짜리 트윈에서 4.6초). 그 폴드의 결과를
+     * 남겨 두면 **처음 한 번만 느리다.**
+     *
+     * `structureRev` 를 함께 적는다: 이벤트가 하나도 안 늘어도 구조를 갈아치우면(재프로비저닝) 그
+     * 상태는 낡은 것이다. 리비전만 보면 새 설비가 없는 옛 상태를 "지금" 으로 내게 된다.
+     */
+    static saveFoldedSnapshot(domainId: string, instanceId: string, value: {
+        revision: number;
+        state: any;
+        structureRev?: number | null;
+        fold?: {
+            reducer: ReducerCheckpoint;
+            oee: OeeCheckpoint;
+        };
+    }): Promise<void>;
+    /** 사슬 색인 — 어떤 리비전 지점을 들고 있나(최신순 아님, 오름차순). */
+    private static chainIndex;
+    /**
+     * 목표 이전의 **가장 가까운 지점**을 고른다 — 없으면 `null`(0부터 접는다).
+     *
+     * 시각으로 물었으면 그 지점의 마지막 사실 시각이 목표 이내여야 한다(리비전만 보면 목표보다 뒤의
+     * 사실이 씨앗에 섞인다). 구조가 바뀐 트윈에서는 쓰지 않는다 — 마디를 건너뛴 씨앗은 그 경계의
+     * 판정을 잃는다(그 경우는 0부터 접는 것이 옳다).
+     */
+    private static chainSeedFor;
+    /** 눈금을 넘었으면 한 지점을 남긴다 — 오래된 것은 버린다(색인도 함께 줄인다). */
+    private static keepChainPoint;
+    /** 이 트윈 저널의 끝 리비전 · 최신 구조 리비전 — 스냅샷이 지금의 사실인지 가리는 두 값. */
+    private static tipOf;
     /** 체크포인트 루프 기동(1회) — 라이브 인스턴스들의 최신 스냅샷을 주기 영속. */
     static startCheckpointLoop(): void;
     /**
@@ -70,31 +154,59 @@ export declare class TwinEngine {
      */
     static bootstrap(): Promise<void>;
     /**
-     * 웜스타트 — 기동하는 커널에 **직전 관측 상태**를 심는다.
+     * 부팅 때 **도는 트윈을 실제로 되살린다** — 「도는 중」이 사실이 되게.
+     *
+     * ── 무엇이 거짓말이었나 (2026-08-14) ────────────────────────────────────────
+     * `bootstrap()` 은 상태만 되찾아 `recovered` 에 담았고, 커널을 세우는 것은 **명시 mutation 뿐**이었다
+     * (이 파일 위쪽 주석이 「향후」라고 적어 둔 그 자리다). 그래서 서버를 한 번 재기동하면 등록부는
+     * `running` 이라 말하는데 **아무 커널도 돌지 않았다** — 화면은 도는 트윈을, 실제로는 멈춘 트윈을.
+     * 미러 트윈에서는 더 나쁘다: 계측이 조용히 끊기고, 사람은 「값이 안 변하네」로 알게 된다.
+     *
+     * ── 모드를 지어내지 않는다 ──────────────────────────────────────────────────
+     * 미러였던 트윈을 시뮬로 되살리면 **없던 움직임을 만들어 낸다**(관측 트윈이 스스로 물건을 옮긴다).
+     * 그래서 선언된 `realityMode` 그대로 되살린다 — 미러는 관측 구동으로, 시뮬은 시뮬로.
+     *
+     * ── 되살릴 수 없으면 그렇게 적는다 ──────────────────────────────────────────
+     * 실패를 삼키면 등록부가 계속 `running` 이라 말한다 — 우리가 고치려던 그 거짓말이다. 그래서 실패한
+     * 행은 `stopped` 로 적고 이유를 남긴다. 「멈췄다」는 사실이고, 「도는 중」은 사실이 아니었다.
+     */
+    private static resumeRow;
+    /** 되살리지 못한 행을 정직하게 적는다 — 「도는 중」이라 말하는 채로 두지 않는다. */
+    private static markStopped;
+    /**
+     * 웜스타트 — 기동하는 커널에 **직전 관측 상태**를 주입한다.
      *
      * ── 왜 필요한가 ─────────────────────────────────────────────────────────────
-     * `loadBoard` 는 **구조만** 싣는다(노드·무버). 상태(무엇이 어디에 얼마나)는 없다. 그래서 재기동한
+     * `loadTwinModel` 는 **구조만** 싣는다(자리·설비). 상태(무엇이 어디에 얼마나)는 없다. 그래서 재기동한
      * 트윈은 저널에 입고 540건이 남아 있어도 재고가 0 이었고, 화면은 "보유 중인 것이 없습니다" 라고
      * 말했다 — 있는 재고를 없다고 하는 셈이다(2026-07-31 hatiolab-wms 실측으로 확인).
      * `bootstrap()` 이 이미 체크포인트 캐시(없으면 저널 replay)로 상태를 복구해 `recovered` 에 담아 두는데,
      * 기동 순간 그걸 **버리고** 있었다. 반만 연결돼 있던 장치를 잇는다.
      *
-     * ── 정직한 한계 ─────────────────────────────────────────────────────────────
-     *  · **오더는 복원하지 않는다.** `hydrateObserved` 의 오더 인자는 requested/fulfilled/lines 를 요구하는데
-     *    스냅샷의 `OrderState` 에는 `progress` 밖에 없다. progress 에서 역산하면 없는 숫자를 지어내는 것이라
-     *    넘기지 않는다 — 재고·노드·무버만 복원되고 진행 중 오더는 비어서 시작한다.
-     *  · 진행 중 개별 task 의 내부 상태도 관측만으로는 복원되지 않는다(커널이 명시한 한계, 재계획에 맡김).
-     *  · 근본 해법(상태 영속 계약·revision 이어붙임)은 별도 과제.
+     * ── 반쪽이던 복구를 마무리한다 (2026-08-05) ─────────────────────────────────
+     * 재고는 살아났는데 **진행 중 주문이 통째로 사라진** 화면이 남아 있었다. 씨앗이 자리·물품·설비
+     * 셋만 넘겼기 때문이다. 그 근거는 "스냅샷 오더에 progress 밖에 없다" 였고, 그때는 맞았다 —
+     * 그러나 커널 `OrderState` 가 원값(`requested`·`fulfilled`·`lines`)을 되찾은 뒤에도 이 자리만
+     * 그대로 남았다. 오류를 내지 않는 종류라 오래 버텼다.
+     *
+     * 지금은 **관측 스냅샷 전체**를 넘긴다(오더·작업·사람·자산 포함). 시뮬은 커널 `snapshot()`,
+     * 라이브는 `StateProjector` 가 그 일곱 축을 모두 담는다. 무엇을 심을 수 있는지 판정하는 규칙
+     * (이행 완료 오더 제외·고아 작업 제외)은 커널에 있고, 호스트가 미리 골라내지 않는다.
+     *
+     * ── 남은 한계는 숨기지 않고 센다 ────────────────────────────────────────────
+     *  · 원값이 없는 오더(progress 만 있는 것)는 남은 수량을 알 수 없어 주입하지 않는다. **지어내지 않는
+     *    대신 몇 건인지 말한다** — 세지 않으면 "주문이 없다" 와 "주문을 못 심었다" 가 화면에서 같아진다.
+     *  · 진행 중 개별 작업의 내부 상태는 관측만으로 완전히 복원되지 않는다(커널이 명시한 한계, 재계획에 맡김).
      *
      * ── 벤치는 시드하지 않는다 ──────────────────────────────────────────────────
-     * 부하 벤치는 **새 시작에서 용량을 재는 것**이 목적이라 현재 상태를 심으면 측정이 오염된다.
+     * 부하 벤치는 **새 시작에서 용량을 재는 것**이 목적이라 현재 상태를 주입하면 측정이 오염된다.
      */
     private static warmStart;
-    /** 트윈 인스턴스 시작 — 커널 생성 + 보드 로드 + 직전 상태 웜스타트 + State 스트림 브리지 + 워커 tick + 레지스트리 영속. */
+    /** 트윈 인스턴스 시작 — 커널 생성 + 모델 로드 + 직전 상태 웜스타트 + State 스트림 브리지 + 워커 tick + 레지스트리 영속. */
     /**
      * 공정 명세를 커널에 싣는다 — **시뮬레이션의 시간을 데이터가 말하게 하는 마지막 한 칸.**
      *
-     * `board.operations`(마스터 인제스트가 통과시킨 ISA-95 OperationsSegment 명세)를 커널이 소비한다.
+     * `model.operations`(마스터 인제스트가 통과시킨 ISA-95 OperationsSegment 명세)를 커널이 소비한다.
      * 없으면 커널 기본 상수로 굴러가고, 커널 `specCoverage()` 가 무엇을 기본값으로 썼는지 보고한다.
      *
      * 커널이 아직 이 API 를 갖지 않은 버전이면(발행 이전) **조용히 넘어가지 않고 경고한다** — 명세를
@@ -106,14 +218,14 @@ export declare class TwinEngine {
      *
      * 커널 `durationOf` 의 우선순위는 추정기 > 명세 > 상수다. 그 추정기 자리에 두 가지를 사슬로 넣는다:
      *  ① **실측**(저널의 작업 종류별 작업시간 p50) — 그 현장에서 실제로 얼마 걸렸나. 가장 강한 근거.
-     *  ② **거리 × 속도**(board.layout + 설비 속도 속성) — 이동은 거리에 비례한다. 커널은 좌표를 모르므로
+     *  ② **거리 × 속도**(model.layout + 설비 속도 속성) — 이동은 거리에 비례한다. 커널은 좌표를 모르므로
      *     호스트가 계산해 넣는다.
      * 둘 다 못 만들면 주입하지 않는다 — 커널이 명세·상수로 굴러가고 `specCoverage()` 가 그 사실을 남긴다.
      *
      * 실측은 DB 조회라 비동기다. 그래서 이 함수는 **await 하지 않는 쪽에서도 안전**하도록 실패를 삼키되,
      * 무엇을 왜 못 넣었는지는 로그로 남긴다(조용한 무효화 금지).
      */
-    static installEstimators(kernel: any, domainId: string, instanceId: string, board: any): Promise<void>;
+    static installEstimators(kernel: any, domainId: string, instanceId: string, model: any): Promise<void>;
     /**
      * 실측 추정기 — **예측 요청마다 저널을 다시 접지 않는다.**
      *
@@ -123,7 +235,33 @@ export declare class TwinEngine {
      */
     private static measuredCache;
     private static readonly MEASURED_TTL_MS;
+    /**
+     * 캐시 항목 상한 — **라이프사이클이 놓친 것까지 막는 두 번째 방어.**
+     *
+     * 지움은 `forgetInstance` 가 한다(그것이 첫 번째 방어이고 정확한 쪽이다). 그런데 트윈이 우리 API 를
+     * 지나지 않고 사라지는 길이 있다: 도메인(테넌트)째로 지워지거나 DB 를 직접 손대는 경우다. 그때
+     * 남은 항목을 지울 주인이 없으므로 상한이 필요하다.
+     *
+     * 넘치면 **가장 오래 손대지 않은 것**부터 버린다(Map 의 삽입 순서가 곧 그 순서다 — 값을 쓸 때마다
+     * 다시 넣으므로). 버리는 것이 손해가 아닌 이유: 이 값은 캐시이고, 없으면 다시 계산한다.
+     *
+     * 수를 크게 잡는다 — 트윈 규모는 늘 크고, 항목 하나는 작업 종류별 소요 몇 줄이다. 상한이 작으면
+     * 정상 규모에서 서로 밀어내며 캐시가 무의미해진다(그게 더 나쁘다: 조용히 느려진다).
+     */
+    private static readonly MEASURED_MAX;
     private static measuredEstimator;
+    /**
+     * 이 트윈이 **이력에서 시간을 배운 작업 종류들** — 재기동에도 남는 근거.
+     *
+     * ── 왜 필요한가 (2026-08-18 실측) ────────────────────────────────────────
+     * 커널의 자기보고(`specCoverage()`)는 **작업이 새로 생길 때** 채워진다. 그래서 재기동 직후에는 이력이
+     * 풍부한 트윈에서도 목록이 비고, 「이 트윈이 무슨 공정을 돌리나」 화면이 빈칸이 된다 — 값을 채울 곳을
+     * 보여야 하는 화면이 정작 그때 아무 말도 못 한다.
+     *
+     * 그 빈칸을 이력로 메운다: 저널에서 배운 종류는 **추정기가 이미 답할 수 있는 종류**이므로, 지어내는
+     * 것이 아니라 있는 사실을 꺼내는 것이다. 같은 캐시(60초)를 쓰므로 조회마다 저널을 다시 접지 않는다.
+     */
+    static measuredOperationKinds(domainId: string, instanceId: string): Promise<string[]>;
     /**
      * 지금 이 트윈이 어떤 모델로 굴러가는가 — 예측 출력 보정이 **자기가 배운 모델**에만 적용되도록
      * 비교하는 지문. 재료는 호스트가 아는 것(실측·속도·선언 명세)이라 커널 발행 상태와 무관하다.
@@ -131,13 +269,13 @@ export declare class TwinEngine {
      */
     static modelBasis(domainId: string, instanceId: string): Promise<ModelBasis | undefined>;
     /**
-     * **이 트윈이 하루 몇 대를 낼 수 있는가** — 굴려 보지 않고 답한다.
+     * **이 트윈이 하루 몇 대를 낼 수 있는가** — 실행해 보지 않고 답한다.
      *
      * 계산은 커널이 자기 상태에서 한다(`kernel.capacity`). 여기서 하는 일은 **기준 주를 정해 주는
      * 것**뿐이다: 공휴일이 없는 평상주여야 한다 — 공휴일은 연간 가용량을 따로 깎지, 이 공장의 평상시
-     * 천장을 정하지 않는다. 커널이 임의로 고르게 두면 그 주에 공휴일이 끼었을 때 천장이 조용히 낮아진다.
+     * 상한을 정하지 않는다. 커널이 임의로 고르게 두면 그 주에 공휴일이 끼었을 때 상한이 조용히 낮아진다.
      *
-     * 트윈이 안 떠 있으면 `undefined` 다 — 0 이 아니다. 안 뜬 트윈의 천장을 0 이라고 답하면 화면은
+     * 트윈이 기동 중이 아니면 `undefined` 다 — 0 이 아니다. 기동하지 않은 트윈의 상한을 0 이라고 답하면 화면은
      * "이 공장은 아무것도 못 만든다" 고 말한다.
      */
     static capacity(domainId: string, target: {
@@ -149,7 +287,33 @@ export declare class TwinEngine {
         analysis?: any;
         reason?: 'not-running' | 'no-operations';
     }[]>;
-    static start(id: string, domainId: string, kind: string, board: BoardDef, realityMode?: RealityMode, purpose?: string, resumeFrom?: number): InstanceRuntime;
+    /**
+     * **생산 능력 보고서** — ISA-95 Part 4 `OperationsCapability`. 구간의 양을 종류로 구분한다
+     * (약정·가용·달성불가). 용량(`capacity`)은 비율을 내고 이것은 **구간의 양**을 낸다.
+     *
+     * 대상 선정·거절 사유는 `capacity` 와 **같은 규율**이다: 등록부가 대상을 정하고(안 기동 중인 것과
+     * 없는 것을 구별한다), 공정을 선언하지 않은 트윈은 판정 대상이 아니라고 말한다(0 으로 채우면
+     * "야드가 병목" 이라는 없는 사실이 생긴다).
+     */
+    static operationsCapability(domainId: string, target: {
+        instanceId?: string;
+        spaceId?: string;
+    }, unitsPerDay: number, sampleWeekStartMs: number, window: {
+        fromTime: string;
+        toTime: string;
+    }): Promise<{
+        instanceId: string;
+        kind?: string;
+        report?: any;
+        reason?: 'not-running' | 'no-operations';
+    }[]>;
+    /**
+     * 미러 기동의 연속성 씨앗 — 이어받은 것은 **말한다**(조용히 잇지 않는다).
+     *
+     * 커널이 그 문을 열어 두지 않았으면 그 사실도 말한다: 그 트윈은 재기동마다 열린 구간을 잃는다.
+     */
+    private static seedLiveContinuity;
+    static start(id: string, domainId: string, kind: string, model: TwinModelDef, realityMode?: RealityMode, purpose?: string, resumeFrom?: number): InstanceRuntime;
     /**
      * live-모드 기동 — **관측 모드 커널**로 실 이벤트를 미러한다(통합 P2).
      *
@@ -163,47 +327,77 @@ export declare class TwinEngine {
      * 실 이벤트원 = reference 어댑터 openLiveFeed → face2-adapter.ingest → CanonicalEnvelope → ingestLive().
      */
     /**
-     * 보드가 실은 **생산 정의**(레시피·라우트·바인딩)를 꺼낸다 — 커널의 정의-구동 모드 입구.
+     * 모델이 실은 **생산 정의**(레시피·라우트·바인딩)를 꺼낸다 — 커널의 정의-구동 모드 입구.
      *
      * ── 없을 때 무엇이 일어났나 ──────────────────────────────────────────────
      * 커널에는 정의-구동 MES 경로가 있는데 **호스트가 그것을 한 번도 넘기지 않았다.** 그래서 모든 MES
      * 트윈이 **하드코딩된 레거시 흐름**으로 돌았다 — 현장 레시피를 아무리 정성껏 적어도 커널은 그것을
      * 보지 못하고 토이 부품으로 토이 제품을 만들었다. 선언과 실행이 갈라져 있던 자리다.
      *
-     * 보드에 없으면 `undefined` — 레거시 경로 그대로다(기존 트윈의 거동을 바꾸지 않는다).
+     * 모델에 없으면 `undefined` — 레거시 경로 그대로다(기존 트윈의 거동을 바꾸지 않는다).
      */
-    private static mesSpecOf;
     /**
-     * 현장(공간)의 **시각 기준**을 보드에 얹는다 — 커널이 교대의 `HH:MM` 을 읽을 기준.
+     * 생산 선언을 꺼낸다 — 커널 생성자에 넘긴다.
+     *
+     * **옛 이름(`mesSpec`)은 읽지 않는다.** 그것은 계약에 선언조차 없던 필드였고(MES 커널 생성자 인자
+     * 이름이 그대로 굳은 것), 일반 기제에 한 시스템 이름이 붙어 있었기 때문에 창고 트윈이 이 자리를
+     * 쓰지 못했다. 별명으로 남겨 두면 그 혼동이 계속되므로 하나로 통일했다.
+     *
+     * 옛 이름만 가진 모델이 있으면 **조용히 생산 선언을 잃는 대신 분명히 멈춘다** — 그 트윈은 공정이
+     * 없는 채로 돌게 되고(라인이 서 있는 창고), 원인을 찾기 어렵다.
+     */
+    private static productionSpecOf;
+    /**
+     * 현장(공간)의 **시각 기준**을 모델에 얹는다 — 커널이 교대의 `HH:MM` 을 읽을 기준.
      *
      * **테넌트가 아니라 공간이 권위다.** 한 테넌트가 Rosarito(태평양)와 한국 공장을 함께 가질 수 있고,
-     * 테넌트 단위(`Domain.timezone`)로 두면 둘 중 하나는 반드시 틀린다. 그래서 인스턴스가 묶인 공간의
+     * 테넌트 단위(`Domain.timezone`)로 두면 둘 중 하나는 반드시 틀린다. 그래서 인스턴스가 연결된 공간의
      * `timezone` 을 읽는다. 공간이 말하지 않으면 **테넌트로 내려가지 않는다** — 잘못된 입자로 답하는 것이
      * 모르는 것보다 나쁘다(그때는 커널이 UTC 로 읽고, 그 기본값은 계약에 밝혀져 있다).
      *
      * 커널은 zero-dep 이라 시간대 데이터베이스를 갖지 않으므로 **분 오프셋**으로 풀어 넘긴다. 그 값은
      * 지금 계절의 것이다(일광절약시간) — 계절을 넘는 긴 예측은 한 시간 어긋난다(계약에 명시).
      */
-    static withSpaceTimeBase(board: BoardDef, domainId: string, spaceId?: string): Promise<BoardDef>;
-    static startLive(id: string, domainId: string, kind: string, board: BoardDef): InstanceRuntime;
+    static withSpaceTimeBase(model: TwinModelDef, domainId: string, spaceId?: string): Promise<TwinModelDef>;
+    static startLive(id: string, domainId: string, kind: string, model: TwinModelDef): 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;
+    static ingestLive(domainId: string, id: string, envelopes: CanonicalEnvelope[]): void;
+    /**
+     * 구간 성과 방송은 **없앴다**(2026-08-06). 카드가 `twinKpi` 를 직접 묻는다.
+     *
+     * 왜: 카드를 여러 단계(공간·트윈·구역·자리·설비)에 붙이려면 방송으로는 태그가 트윈당 1,200개가 되고,
+     * **모델에 카드를 하나도 안 놓아도** 30초마다 트윈마다 저널을 접었다. 질의로 바꾸니 보고 있는 카드
+     * 수만큼만 들고, 같은 (대상·창·축) 은 클라이언트가 하나로 합친다.
+     *
+     * 덤으로 질의만 할 수 있는 것이 둘 생겼다 — **과거 시각**(`toTime`)과 **공간 단위 합산**(여러 트윈을
+     * 한 번에 접기). 방송 루프는 트윈별이라 둘 다 못 했다.
+     *
+     * 축을 나눠도 폴드 비용이 같다는 실측이 근거다(`test/kpi-query-bench.test.ts`).
+     */
     /** 방송 병합 주기(ms) — 방송률 상한. 인제스트가 아무리 빨라도 이 주기로만 방송. */
     static BROADCAST_COALESCE_MS: number;
     private static broadcastTimer?;
     /** live 방송 coalescer — dirty 인 live 인스턴스만 주기적으로 1회 방송(entitySigs 로 변경 엔티티만). */
     private static ensureBroadcastCoalescer;
-    /** dirty live 인스턴스 방송 flush(주기 tick 또는 명시 호출). 테스트/즉시 방송용으로 public. */
+    /**
+     * dirty 인스턴스 방송 flush(주기 tick 또는 명시 호출) — **시뮬과 라이브 둘 다.**
+     *
+     * 예전에는 라이브만 봤다(`mode !== 'live'` 면 건너뜀). 시뮬은 delta 마다 곧바로 방송했고, 그것이
+     * 한 tick 에서 수백 번 반복되며 이벤트 루프를 막았다(위 `start()` 주석의 35초 틱). 방송을 모으는
+     * 규율은 모드의 성질이 아니라 **채널의 성질**이다 — 최신-상태 채널이면 중간 상태는 보낼 값이 없다.
+     */
     static flushLiveBroadcasts(): void;
     /**
      * 저널 행 한 줄 — **기록 경로가 둘이라(라이브 벌크·심 단건) 행 모양은 반드시 한 곳에서 만든다.**
      * 두 곳에 각자 적으면 승격 검색 키가 한쪽에만 채워지고, 반쯤 빈 색인은 "저널에는 있는데
      * 검색으로는 안 나오는 이벤트" 를 만든다 — 저널에서 가장 나쁜 종류의 결함이다.
      */
+    /** 저널의 시각 축은 날짜다 — 못 읽는 값은 비운다(0 이나 지금으로 위장하지 않는다). */
+    private static toEventTimeValue;
     private static journalRow;
     /**
      * 이 트윈이 지금 어느 구조로 도는가 — 이벤트에 찍을 번호. 한 번 읽고 캐시한다(쓰기마다 조회 금지).
@@ -216,33 +410,72 @@ export declare class TwinEngine {
     /** 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>;
+    static register(domainId: string, instanceId: string, kind: string, model: TwinModelDef, status?: 'running' | 'stopped', realityMode?: RealityMode, origin?: any, meta?: {
+        name?: string;
+        description?: string;
+        actor?: {
+            id: string;
+        };
+    }): Promise<void>;
     /**
-     * 라이브 구조 변이(resource.add 등)를 저장된 board 에 반영 — 런타임 커널의 무버를 registry board.equipment 에 동기.
-     * 이게 없으면 런타임엔 추가돼도(상태·저널엔 반영) 저장 board 는 원본이라 프로비저닝 편집기·재기동(loadBoard)이
-     * 추가분을 잃는다. 기존 board.equipment 항목은 보존(homeLocation 유지)하고 새 id 만 append(추가 시점 location=homeLocation).
+     * 라이브 구조 변이(resource.add 등)를 저장된 model 에 반영 — 런타임 커널의 무버를 registry model.equipment 에 동기.
+     * 이게 없으면 런타임엔 추가돼도(상태·저널엔 반영) 저장 model 는 원본이라 프로비저닝 편집기·재기동(loadTwinModel)이
+     * 추가분을 잃는다. 기존 model.equipment 항목은 보존(homeLocation 유지)하고 새 id 만 append(추가 시점 location=homeLocation).
      * 좌표(layout)만 다루는 register 와 달리 equipment 집합을 갱신하나, 재프로비전(purge)이 아니라 in-place 갱신이라
      * 저널은 보존된다(추가는 이미 equipment 델타로 저널됨 → replay 는 id-keyed upsert 라 이중계산 없음).
      */
     static syncBoardEquipment(domainId: string, instanceId: string): Promise<void>;
     /**
-     * 프로비저닝 — 레지스트리에 구조(board)를 등록만 하고 기동하지 않음(status='stopped').
+     * 프로비저닝 — 레지스트리에 구조(model)를 등록만 하고 기동하지 않음(status='stopped').
      * 재프로비전 시 구조 시그니처가 바뀌면(노드·무버 집합/속성 변경) 기존 저널을 purge 한다(ADR-0015):
-     * board 는 replay 의 마스터라 구조가 바뀌면 과거 이벤트의 전제가 깨진다. 좌표(layout)만 바뀌면 저널 보존.
+     * model 는 replay 의 마스터라 구조가 바뀌면 과거 이벤트의 전제가 깨진다. 좌표(layout)만 바뀌면 저널 보존.
+     */
+    /**
+     * 실행 중이면 구조를 교체하지 않는다 — **판정 문장을 한 곳에 둔다.**
+     *
+     * 인제스트는 전량 교체라, 이벤트를 접고 있는 커널 밑에서 바닥을 바꾸는 셈이 된다. 지금은 거절이
+     * 유일한 답이지만 최종형은 아니다(`adoptStructure` 배선). 두 곳에서 같은 문장으로 거절해야
+     * 나중에 이 규칙을 걷어낼 때 걷어낼 것이 하나로 보인다.
      */
-    static provision(domainId: string, instanceId: string, kind: string, board: BoardDef, comment?: string): Promise<void>;
+    private static assertNotRunning;
+    /**
+     * 돌면서 공장을 전환한다 — **미러 전용.**
+     *
+     * 미러가 비추는 현실은 안 멈춘다. 설비 한 대가 늘었다고 트윈을 멈췄다 세우면 그 사이의 사실을
+     * 잃고, 라이브에서 유실은 곧 거짓이다. 그래서 미러는 **동작 중에** 새 구조를 받는다.
+     *
+     * 시뮬레이션은 여기 오지 않는다. 조건이 바뀐 실험은 다른 실험이므로 멈추고 다시 세우는 것이
+     * 옳다 — 커널이 그렇게 거절한다(`FlowEngine.adoptStructure`).
+     *
+     * 세 가지가 **함께** 일어나야 한다. 하나라도 빠지면 층이 어긋난다:
+     *  ① 리비전 — 이 시점 이후의 이벤트가 새 번호를 달고 다닌다(재생이 마디를 나눌 수 있게)
+     *  ② 저장 model·구조 행 — 조회가 새 구조를 본다
+     *  ③ 커널 — 지금 접히는 이벤트가 새 구조 위에서 접힌다
+     */
+    static adoptStructure(domainId: string, instanceId: string, model: TwinModelDef, comment?: string, origin?: any): Promise<{
+        rev: number;
+    } & StructureShift>;
+    static provision(domainId: string, instanceId: string, kind: string, model: TwinModelDef, comment?: string, origin?: any, 
+    /** 이름·저자 — 업무키를 나눠 둔 대가로 이름을 함께 남긴다(`register` 의 `meta` 그대로). */
+    meta?: {
+        name?: string;
+        description?: string;
+        actor?: {
+            id: string;
+        };
+    }): Promise<void>;
     /**
      * 이 구조를 리비전으로 남기고 그 번호를 돌려준다 — **바뀌었을 때만** 새 번호가 생긴다.
      *
      * 프로비저닝은 부팅마다 다시 도는데, 그때마다 리비전이 늘면 이력이 뜻 없는 마디로 잘게 쪼개진다.
      * 그래서 **구조 서명이 같으면 있던 리비전을 그대로 쓴다.**
      */
-    static recordStructure(domainId: string, instanceId: string, board: BoardDef, comment?: string): Promise<number>;
+    static recordStructure(domainId: string, instanceId: string, model: TwinModelDef, comment?: string): Promise<number>;
     /**
      * 이 트윈이 거쳐 온 구조들 — **무엇이 언제 달라졌나.**
      *
      * 리비전은 그 시절 공장을 통째로 담지만(재생에 필요하다), 사람이 보고 싶은 것은 통째가 아니라
-     * 차이다. 보드는 빼고 **차이 요약만** 내보낸다 — 62KB 짜리 보드를 화면에 실어 보낼 이유가 없다.
+     * 차이다. 모델은 빼고 **차이 요약만** 내보낸다 — 62KB 짜리 보드를 화면에 실어 보낼 이유가 없다.
      */
     static structureHistory(domainId: string, instanceId: string): Promise<{
         rev: number;
@@ -252,7 +485,7 @@ export declare class TwinEngine {
         diff: StructureDiff;
     }[]>;
     /** 지금 쓰이는 구조 리비전 — 이벤트에 찍을 번호. 아직 없으면 기록하며 만든다. */
-    static currentStructureRev(domainId: string, instanceId: string, board?: BoardDef): Promise<number | undefined>;
+    static currentStructureRev(domainId: string, instanceId: string, model?: TwinModelDef): Promise<number | undefined>;
     /** 구조 동일성 지문 — 좌표(layout) 등 뷰 관심사는 제외하고 커널이 보는 위상·용량·무버만. */
     /**
      * 지문을 **64자로 줄인다** — 컬럼이 varchar(64) 다.
@@ -263,10 +496,10 @@ export declare class TwinEngine {
      */
     private static structureFingerprint;
     private static structureSignature;
-    /** 레지스트리 board 로 기동(프로비전된 인스턴스 start). board 인자 없이 저장된 구조로 재기동. */
+    /** 레지스트리 model 로 기동(프로비전된 인스턴스 start). model 인자 없이 저장된 구조로 재기동. */
     static startFromRegistry(domainId: string, instanceId: string, realityMode?: RealityMode): Promise<InstanceRuntime>;
     /**
-     * 선언 기반 부팅(§0 프레임 ① → 부팅 거동 매핑) — 트윈이 선언한 realityMode 에 따라 재기동 방식을 가른다.
+     * 선언 기반 부팅(§0 프레임 ① → 부팅 거동 매핑) — 트윈이 선언한 realityMode 에 따라 재기동 방식을 구분한다.
      * 부팅 경로를 한 곳에 모아 "런타임 ≠ 현실" 범주오류를 코드로 강제한다.
      *   - 'mirror'         : 현실=외부 실물 → startLive(재동기). 이벤트는 어댑터 ingest 로 유입, 커널 tick 없음.
      *   - 'sim-world'      : 생성 타임라인 지속 → 저널 보존 + resume(현실 이어감).
@@ -284,11 +517,20 @@ export declare class TwinEngine {
     static resetJournal(domainId: string, instanceId: string): Promise<void>;
     /** 삭제 — 정지 + 레지스트리 삭제 + 저널 purge(domain 스코프). */
     static remove(domainId: string, instanceId: string): Promise<void>;
+    /**
+     * 이 트윈에 대해 **메모리에 남은 것을 전부 잊는다** — 지움의 한 자리.
+     *
+     * 캐시가 라이프사이클과 어긋나 있었다: 저널·등록부는 지우면서 인스턴스별 캐시는 남겨, 삭제된 트윈의
+     * 항목이 **서버 재기동까지 살아 있었다.** 항목 하나가 하루치 KPI 그룹을 물고 있으므로 잊지 않으면
+     * 지운 트윈이 계속 메모리를 차지한다. TTL 은 값이 낡는 것을 막을 뿐 **없어진 주인을 지우지 않는다.**
+     *
+     * 잊을 것을 여기 모아 두는 이유: 캐시를 새로 만드는 사람이 지우는 자리를 찾아 헤매지 않게 한다.
+     * 새 인스턴스별 캐시를 만들면 **이 함수에 한 줄을 더한다** — 그러지 않으면 같은 누수가 다시 생긴다.
+     */
+    private static forgetInstance;
     /** 관리 목록 — domain 의 등록 인스턴스 전체(라이브 여부·최신 저널 revision·노드/무버 수 포함). */
     static list(domainId: string): Promise<any[]>;
-    /** 레거시 벤치 잔재 가드 — purpose 도입 전 만들어진 벤치/부하 공간(이름 규약)까지 걸러낸다. */
-    static isBenchSpace(spaceId?: string): boolean;
-    /** 운영 공간 목록(벤치 소스 선택기) — 이름·규모 포함, 벤치 사본·잔재 제외. */
+    /** 운영 공간 목록(벤치 소스 선택기) — 이름·규모 포함, 벤치 사본 제외. */
     static listSpaces(domainId: string): Promise<{
         spaceId: string;
         name: string;
@@ -299,17 +541,23 @@ export declare class TwinEngine {
     /** 인스턴스 목적 표식(운영/벤치) 설정 — 벤치 사본을 1급 속성으로 구별(이름 접두사 아님). */
     static setPurpose(domainId: string, instanceId: string, purpose: 'operational' | 'bench', copyOf?: string): Promise<void>;
     /**
-     * 공간 구조 판독 — 완전복제(벤치 사본)의 소스. 저장물이 board(위상)·TwinSpace.content(치수·geo·표현)·TwinArea(영역)로
+     * 공간 구조 판독 — 완전복제(벤치 사본)의 소스. 저장물이 model(위상)·TwinSpace.content(치수·geo·표현)·TwinArea(영역)로
      * 분산돼 있으므로 셋을 모아 돌려준다. 호출측이 ReferenceMaster 로 재구성 → 재식별 → ingestMaster.
      */
     static spaceStructure(domainId: string, spaceId: string): Promise<{
         name?: string;
-        content: any;
+        /** 설계 좌표계 범위(미터)와 지오레퍼런스 — 사본이 원본과 같은 자리에 서려면 함께 가야 한다. */
+        frame: {
+            extentX?: number;
+            extentY?: number;
+            geo?: any;
+            primaryRepresentationId?: string;
+        };
         areas: any[];
         instances: {
             instanceId: string;
             kind?: string;
-            board: any;
+            model: any;
         }[];
     } | null>;
     /** 공간(+표현·영역) 삭제 — 벤치 정리 등. 호출측이 바인딩 인스턴스를 먼저 제거하는 전제(가드 없음). deleteTwinSpace 리졸버와 동형. */
@@ -318,24 +566,49 @@ export declare class TwinEngine {
      * Face2 마스터 인제스트(ADR-0018) — 레퍼런스 시스템(실 또는 가상)의 마스터를 읽어 트윈을 생성.
      * 엔티티를 손배선/발명하지 않고 마스터에서 반영: 공간(Space) upsert + 인스턴스 provision(미기동).
      * 노드타입은 커널 카탈로그로 검증(warning). start 는 호출측(bootstrap/mutation)이 결정.
+     *
+     * `into.spaceId` — **이 현장에 더한다.** 한 현실을 여러 렌즈(WMS·MES·YMS)가 비추므로 새 트윈이
+     * 기존 공간으로 들어갈 수 있다. 아래 병합은 원래 그 경우를 위해 있었는데(N:1) 만드는 흐름에서
+     * 공간을 고를 방법이 없었다 — 마스터가 파생한 id 만 쓰였다. 판정은 `resolveIngestSpace`(순수).
      */
-    static ingestMaster(domainId: string, master: ReferenceMaster): Promise<{
+    static ingestMaster(domainId: string, master: ReferenceMaster, into?: {
+        spaceId?: string;
+    }, 
+    /** 누가 인제스트했나 — 사람이 없는 경로(부팅)는 주지 않는다(감사 기록을 지어내지 않는다). */
+    actor?: {
+        id: string;
+    }): Promise<{
         instanceId: string;
         spaceId: string;
-        warnings: string[];
+        warnings: IngestWarning[];
     }>;
-    /** 단건 상세 — 프로비저닝 에디터가 편집할 board(구조+layout) 포함. */
+    /** 단건 상세 — 프로비저닝 에디터가 편집할 model(구조+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 네임스페이스는 후속.
      */
+    /** 방송 실패 로그 조절 — 창마다 한 줄(막힌 구독자는 초당 수십 번 실패한다). */
+    private static publishDrops;
+    private static readonly PUBLISH_DROP_LOG_MS;
+    /**
+     * 한 번의 방송 — **구독자 하나가 호스트를 죽이지 못하게.**
+     *
+     * ── 무엇이 죽였나 (2026-08-14) ─────────────────────────────────────────────
+     * 밀린 push 가 1024를 넘으면 pubsub 이 던진다(`RepeaterOverflowError`). 그 방송은 타이머 콜백
+     * 안에서 일어나므로 예외가 잡히는 곳 없이 올라가 **프로세스가 끝났다** — 트윈 14개가 도는 호스트가
+     * 소비를 멈춘 구독자 하나 때문에 통째로.
+     *
+     * 못 보낸 것은 **사실로 남긴다**(횟수를 세고 창마다 한 줄 남긴다). 삼키면 「보냈는데 화면이 낡았다」가
+     * 되고, 그건 가장 찾기 어려운 부류다.
+     */
+    private static publishGuarded;
     static publishEntityData(inst: InstanceRuntime): void;
     static persist(domainId: string, instanceId: string, msg: any): Promise<void>;
     /**
      * 재부팅 복구 / 시간여행 — DB 저널을 replay 해 상태 재구성.
-     * board 는 레지스트리(TwinInstance)에서, 이벤트는 TwinEvent(revision ASC)에서.
+     * model 는 레지스트리(TwinInstance)에서, 이벤트는 TwinEvent(revision ASC)에서.
      * 커서 두 축(runtime-state-model §4): **시각(untilTime, 사용자 모국어·공간 공통축)** 우선, 없으면 리비전(untilRevision, 렌즈 내부).
      *   - untilTime 주면 `eventTime ≤ T` 인 이벤트만(그 시점 watermark) — 공동배치 여러 트윈을 하나의 시각 T로 통일 해소.
      *   - 둘 다 없으면 최신(라이브 인메모리 진실).
@@ -353,39 +626,127 @@ export declare class TwinEngine {
     /** 정지 훅 — 인스턴스 정지 시 부수자원 정리(예: 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;
+    static stop(domainId: string, id: string): Promise<void>;
+    /**
+     * 같은 현장 트윈들의 **설비 상태**를 커널에 넘긴다 — 커널이 요청할 때만.
+     *
+     * ── 경계 (2026-08-14) ──────────────────────────────────────────────────────
+     * 호스트가 아는 것은 **누가 같은 현장에 있는가** 하나다. 무엇을 읽고 그것을 어떻게 부하로 바꿀지는
+     * 커널이 정한다(계수는 트윈의 모델이 선언한다). 호스트가 kW 를 계산해 주면 트윈마다 다른 규칙이
+     * 생기고, 그 규칙은 어디에도 적혀 있지 않게 된다.
+     *
+     * 상태만 넘긴다. 스냅샷을 통째로 넘기면 상태 크기에 비례한 비용을 매 tick 치르게 된다 —
+     * 설비 목록은 그 트윈의 커널이 이미 들고 있는 것이라 훑는 값이 싸다.
+     */
+    private static feedPeerEquipment;
+    private static tickGuarded;
+    /**
+     * 호스트를 굶기는 트윈을 멈춘다 — **도는 척하는 것보다 멈춘 것이 낫다.**
+     *
+     * 굶김 문턱을 넘는 틱이 연속 `STARVE_STREAK` 번이면 그 트윈은 구조적으로 무겁다(우연이 아니다).
+     * 문턱 아래로 한 번만 내려와도 연속을 끊는다 — 무거운 순간 하나로 트윈을 내리지 않는다.
+     */
+    private static guardStarvation;
+    /** 멈추고 **이유를 남긴다** — 이유 없는 「정지」는 사람이 자기가 멈춘 것으로 읽는다. */
+    private static stopWithNote;
+    /** 이 트윈이 스스로 멈춘 이유(있으면) — 화면이 옮겨 말한다. */
+    static stopNoteOf(domainId: string, id: string): StopNote | undefined;
+    /**
+     * 이 트윈이 **지금 실행 중인가** — 판정의 집 하나.
+     *
+     * "스냅샷이 있나" 로는 답이 되지 않는다: 웜스타트가 되살린 상태가 캐시에 남아 있으면 멈춘 트윈도
+     * 스냅샷을 낸다. 그것을 관측 중으로 읽으면 화면이 **멈춘 트윈의 작업을 0 건이라고 단언**한다
+     * (실제로 그렇게 나왔다 — 관측이 없는 것과 0 건은 다르다는 이 프로젝트의 규율을 화면이 어겼다).
+     *
+     * 목록이 쓰는 것과 **같은 술어**다(`list()` 의 `running`) — 두 벌이면 어긋난다.
+     */
+    static isRunning(domainId: string, id: string): boolean;
+    static runtime(domainId: string, id: string): TwinRuntimeType | undefined;
+    static dispatchCommand(domainId: string, instanceId: string, command: any): Promise<{
+        accepted: boolean;
+        error?: string;
+        errorCode?: string;
+        errorParams?: Record<string, string | number>;
+    }>;
     /**
      * 도메인 소유 게이트 — 인스턴스가 이 도메인 소유일 때만 true(테넌트 격리).
      * 없거나 다른 도메인이면 false. 노출 리졸버(per-id metrics/attentions/state/stop/forecast)가
      * this.instances[id] 를 만지기 전에 반드시 이걸로 확인해야 한다. 인스턴스 id 는 추측 가능하므로
      * 검증 없이 접근하면 크로스테넌트 읽기/정지가 가능해진다.
      */
+    /**
+     * 이 런타임의 **관측 모드** — `'live'`(외부 실물을 미러) 또는 `'sim'`(커널이 실행한다). 기동 중이 아니면 없다.
+     *
+     * 소비처가 `instances[id].mode` 를 직접 읽던 자리를 대신한다. 레지스트리를 밖에 열면 도메인 확인이
+     * 자리마다 제각각이 되고, 실제로 그렇게 됐다(테넌트 격리 전수 확인, 2026-08-06).
+     */
+    static modeOf(domainId: string, id: string): 'live' | 'sim' | undefined;
     static owns(domainId: string, id: string): boolean;
     /**
      * 이 트윈이 이 테넌트 것인가 — **떠 있든 아니든.**
      *
-     * `owns()` 는 **떠 있는** 런타임만 안다. 그것을 이력 조회의 관문으로 쓰면, 꺼진 트윈의 저널을
+     * `owns()` 는 **기동 중인** 런타임만 안다. 그것을 이력 조회의 관문으로 쓰면, 꺼진 트윈의 저널을
      * 읽으려 할 때 "이 테넌트에 없다" 는 답이 돌아온다 — 두 가지가 틀렸다. 첫째, 저널은 트윈이 꺼져
      * 있을 때 **가장 필요한 것**이다(그게 이력의 존재 이유다). 둘째, 그 문장은 남의 것이라는 뜻이라
-     * 사용자가 권한 문제로 오해한다. 실제로는 그냥 안 돌고 있을 뿐이다.
+     * 사용자가 권한 문제로 오해한다. 실제로는 그냥 실행 중이 아닐 뿐이다.
      *
      * 소유는 **등록부**가 안다. 이력·집계처럼 런타임과 무관한 질문은 이쪽에 묻는다.
      */
     static ownsRegistered(domainId: string, instanceId: string): Promise<boolean>;
+    /**
+     * **이 공간의 인스턴스들** — 한 현실을 여러 렌즈가 비추므로, 공간을 물으면 그 렌즈 전부를 답한다.
+     *
+     * 화면이 이 규칙을 손으로 짜지 않게 서버가 답한다. 예측 화면은 같은 확장을 **한 파일에서 두 번**
+     * 복제하고 있었다(전체 목록을 받아 클라이언트에서 걸렀다) — 규칙이 흩어지면 한쪽만 고쳐진다.
+     *
+     * 떠 있지 않은 것도 포함한다: 공간에 무엇이 있는지는 기동 여부와 다른 사실이다.
+     */
+    static instanceIdsOfSpace(domainId: string, spaceId: string): Promise<string[]>;
+    /**
+     * **이 공간에서 봐야 할 것** — 공간의 모든 렌즈에서 신호를 모은다.
+     *
+     * 합집합이 그대로 뜻이 있는 유일한 렌즈다(예측은 합칠 수 없다 — P50 두 개를 더할 수 없다).
+     * 정렬·잘라내기는 화면과 **같은 규칙**을 쓴다(`digestAttentions`) — 서버가 고른 상위 N 이 화면이
+     * 고를 N 과 달라지면 그 어긋남은 아무 데서도 오류로 드러나지 않는다.
+     *
+     * 신호마다 어느 트윈에서 왔는지(`instanceId`)를 붙인다. 공간에서 보면 같은 자리 id 가 렌즈마다
+     * 다른 것을 가리킬 수 있고, 조치는 결국 그 트윈에 보내야 한다.
+     */
+    static attentionsOfSpace(domainId: string, spaceId: string, limit?: number): Promise<{
+        attentions: any[];
+        attentionTotal: number;
+        severityByLocation: Record<string, string>;
+    }>;
     /** 라이브 커널(ForecastTwin) — forecast/divergence 예측 연산용. */
-    static kernel(id: string): any;
+    static kernel(domainId: string, id: string): any;
     /** 라이브 처리량 계측 스냅샷(모니터, ④-1) — 내부 누적(_acc*) 제외한 공개 지표. live 아니면 null. */
-    static metrics(id: string): any;
+    static metrics(domainId: string, id: string): any;
+    /**
+     * 부하 계기판만 따로 — **시뮬 트윈도 포함한다.**
+     *
+     * `metrics()` 는 라이브 지표(`inst.metrics`)가 있어야 무언가를 돌려준다. 그런데 이벤트 루프를 점유하는
+     * 것은 주로 **시뮬 틱**이고, 시뮬 인스턴스에는 그 지표가 없어 통째로 안 보였다.
+     */
+    static load(domainId: string, id: string): any;
+    /**
+     * **한 곳에서 보는 전체 부하** — 몇 개가 실행 중이고, 누가 루프를 점유하고 있나.
+     *
+     * 시뮬 트윈도 포함한다(`metrics()` 는 라이브 지표가 있어야 답해서 시뮬이 통째로 안 보였다).
+     */
+    static fleet(domainId?: string): any;
+    /** 이 트윈에서 fork 가 만들어졌다 — 예측 한 번이 수십 개를 만든다. */
+    static countForks(domainId: string, id: string, count: number): void;
+    /** 엔진 밖(예측 질의 등)에서 무거운 작업을 잰다 — 같은 계기판에 모인다. */
+    static recordLoad(domainId: string, id: string, phase: LoadPhase, tookMs: number): void;
     /** 전체 라이브 인스턴스 계측(모니터 대시보드용). */
     static allMetrics(domainId?: string): Promise<any[]>;
     /**
      * 예측용 커널을 **임의 시각 T 기준**으로 재구성 — 과거-vantage 예측(백테스트)·"그때 서서 본 미래".
-     * recover(untilTime)로 T 시점 상태를, T 이하 오더 관측을 모아 hydrate → monteCarloForecast 가 T 에서 앞으로 굴린다.
+     * 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;
+    static snapshot(domainId: string, id: string): any;
 }
 export {};