@things-factory/headless-twin 10.0.12 → 10.0.13

package/dist-server/engine/log.js

@@ -0,0 +1,80 @@
+"use strict";
+/*
+ * 트윈 로그의 문 — **모든 줄에 시각을 찍는다.** 순수(프레임워크 의존 없음).
+ *
+ * ── 왜 필요한가 (2026-08-22) ────────────────────────────────────────────────
+ * 「서버가 왜 느린가」를 조사하면서 루프가 55초 막힌 것을 계기로 알아냈는데(`loop-lag.ts`),
+ * **그 시각에 무슨 일이 있었는지 로그에서 찾을 수 없었다.** 트윈의 로그가 `console.log` 로 나가
+ * 시각이 없었기 때문이다. 프레임워크 로그(`2026-08-22T05:54:12+09:00 info: …`)와 섞여 있어서, 어느
+ * 줄이 언제 찍혔는지 앞뒤 프레임워크 줄로 짐작해야 했다.
+ *
+ * ── 왜 프레임워크 로거를 그대로 쓰지 않나 ──────────────────────────────────
+ * 재발명을 피하려고 `@things-factory/env` 의 `logger` 를 쓰려 했는데, 실측으로 막혔다: 앱 **밖**에서는
+ * 그 로거에 전송지가 하나도 없다(설정이 앱에서 주입된다). 그래서 시험·도구에서 부르면
+ *
+ *   [winston] Attempt to write logs with no transports … {"message":"…","level":"info"}
+ *
+ * 가 나오고 **메시지 자체가 사라진다.** 트윈 엔진은 시험과 CLI 도구에서도 불려 다니므로, 그 조건에서
+ * 로그가 없어지는 것은 바꿔선 안 되는 거동이다(로그가 사라지는 것이 지금 문제의 원인이었다).
+ *
+ * 그래서 **싱크는 그대로 두고**(console) 빠진 사실 하나만 채운다 — 시각. 형식은 프레임워크와 같은
+ * 모양으로 맞춰 한 파일에서 섞여 읽히게 하고, **밀리초까지** 남긴다(계기의 값이 epoch ms 라
+ * 초 단위로는 같은 초 안의 순서를 가릴 수 없다).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.twinError = exports.twinWarn = exports.twinLog = void 0;
+exports.stamp = stamp;
+exports.line = line;
+/** 두 자리·세 자리 0 채우기 — 형식이 흔들리면 정렬해 읽을 수 없다. */
+const p2 = (n) => String(n).padStart(2, '0');
+const p3 = (n) => String(n).padStart(3, '0');
+/**
+ * 지역 시각 + 오프셋 — `2026-08-22T05:54:12.345+09:00`.
+ *
+ * UTC 로 찍지 않는다: 이 로그를 읽는 사람은 현장의 시각으로 이야기하고, 프레임워크의 다른 줄도
+ * 지역 시각이다. 두 줄이 다른 기준이면 나란히 놓고 읽을 수 없다.
+ */
+function stamp(at = new Date()) {
+    const off = -at.getTimezoneOffset();
+    const sign = off >= 0 ? '+' : '-';
+    const abs = Math.abs(off);
+    return (`${at.getFullYear()}-${p2(at.getMonth() + 1)}-${p2(at.getDate())}` +
+        `T${p2(at.getHours())}:${p2(at.getMinutes())}:${p2(at.getSeconds())}.${p3(at.getMilliseconds())}` +
+        `${sign}${p2(Math.floor(abs / 60))}:${p2(abs % 60)}`);
+}
+/**
+ * 인자 여럿을 한 줄로 — **어떤 인자도 버리지 않는다.**
+ *
+ * `console.error(msg, err)` 처럼 쓰던 자리가 많다. 프레임워크 로거에 그대로 넘기면 두 번째 인자는
+ * meta 로 들어가 우리 형식(`message` 만 찍는다)에서 **조용히 사라진다.** 그래서 여기서 문자열로 편다.
+ * 오류는 스택까지 — 스택이 없으면 「어디서 났나」를 잃는다.
+ */
+function line(args) {
+    return args
+        .map(a => {
+        if (typeof a === 'string')
+            return a;
+        if (a instanceof Error)
+            return a.stack ?? a.message;
+        if (a === undefined)
+            return 'undefined';
+        if (a === null)
+            return 'null';
+        try {
+            return typeof a === 'object' ? JSON.stringify(a) : String(a);
+        }
+        catch {
+            /* 순환 참조 등 — 값을 못 적어도 **무엇이 있었다는 사실**은 남긴다. */
+            return String(a);
+        }
+    })
+        .join(' ');
+}
+/* 수준 표기는 프레임워크와 같은 낱말을 쓴다(`info`·`warn`·`error`) — 같은 파일에서 걸러 읽는다. */
+const twinLog = (...args) => console.log(`${stamp()} info: ${line(args)}`);
+exports.twinLog = twinLog;
+const twinWarn = (...args) => console.warn(`${stamp()} warn: ${line(args)}`);
+exports.twinWarn = twinWarn;
+const twinError = (...args) => console.error(`${stamp()} error: ${line(args)}`);
+exports.twinError = twinError;
+//# sourceMappingURL=log.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../../server/engine/log.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * 트윈 로그의 문 — **모든 줄에 시각을 찍는다.** 순수(프레임워크 의존 없음).\n *\n * ── 왜 필요한가 (2026-08-22) ────────────────────────────────────────────────\n * 「서버가 왜 느린가」를 조사하면서 루프가 55초 막힌 것을 계기로 알아냈는데(`loop-lag.ts`),\n * **그 시각에 무슨 일이 있었는지 로그에서 찾을 수 없었다.** 트윈의 로그가 `console.log` 로 나가\n * 시각이 없었기 때문이다. 프레임워크 로그(`2026-08-22T05:54:12+09:00 info: …`)와 섞여 있어서, 어느\n * 줄이 언제 찍혔는지 앞뒤 프레임워크 줄로 짐작해야 했다.\n *\n * ── 왜 프레임워크 로거를 그대로 쓰지 않나 ──────────────────────────────────\n * 재발명을 피하려고 `@things-factory/env` 의 `logger` 를 쓰려 했는데, 실측으로 막혔다: 앱 **밖**에서는\n * 그 로거에 전송지가 하나도 없다(설정이 앱에서 주입된다). 그래서 시험·도구에서 부르면\n *\n *   [winston] Attempt to write logs with no transports … {\"message\":\"…\",\"level\":\"info\"}\n *\n * 가 나오고 **메시지 자체가 사라진다.** 트윈 엔진은 시험과 CLI 도구에서도 불려 다니므로, 그 조건에서\n * 로그가 없어지는 것은 바꿔선 안 되는 거동이다(로그가 사라지는 것이 지금 문제의 원인이었다).\n *\n * 그래서 **싱크는 그대로 두고**(console) 빠진 사실 하나만 채운다 — 시각. 형식은 프레임워크와 같은\n * 모양으로 맞춰 한 파일에서 섞여 읽히게 하고, **밀리초까지** 남긴다(계기의 값이 epoch ms 라\n * 초 단위로는 같은 초 안의 순서를 가릴 수 없다).\n */\n\n/** 두 자리·세 자리 0 채우기 — 형식이 흔들리면 정렬해 읽을 수 없다. */\nconst p2 = (n: number) => String(n).padStart(2, '0')\nconst p3 = (n: number) => String(n).padStart(3, '0')\n\n/**\n * 지역 시각 + 오프셋 — `2026-08-22T05:54:12.345+09:00`.\n *\n * UTC 로 찍지 않는다: 이 로그를 읽는 사람은 현장의 시각으로 이야기하고, 프레임워크의 다른 줄도\n * 지역 시각이다. 두 줄이 다른 기준이면 나란히 놓고 읽을 수 없다.\n */\nexport function stamp(at: Date = new Date()): string {\n  const off = -at.getTimezoneOffset()\n  const sign = off >= 0 ? '+' : '-'\n  const abs = Math.abs(off)\n  return (\n    `${at.getFullYear()}-${p2(at.getMonth() + 1)}-${p2(at.getDate())}` +\n    `T${p2(at.getHours())}:${p2(at.getMinutes())}:${p2(at.getSeconds())}.${p3(at.getMilliseconds())}` +\n    `${sign}${p2(Math.floor(abs / 60))}:${p2(abs % 60)}`\n  )\n}\n\n/**\n * 인자 여럿을 한 줄로 — **어떤 인자도 버리지 않는다.**\n *\n * `console.error(msg, err)` 처럼 쓰던 자리가 많다. 프레임워크 로거에 그대로 넘기면 두 번째 인자는\n * meta 로 들어가 우리 형식(`message` 만 찍는다)에서 **조용히 사라진다.** 그래서 여기서 문자열로 편다.\n * 오류는 스택까지 — 스택이 없으면 「어디서 났나」를 잃는다.\n */\nexport function line(args: unknown[]): string {\n  return args\n    .map(a => {\n      if (typeof a === 'string') return a\n      if (a instanceof Error) return a.stack ?? a.message\n      if (a === undefined) return 'undefined'\n      if (a === null) return 'null'\n      try {\n        return typeof a === 'object' ? JSON.stringify(a) : String(a)\n      } catch {\n        /* 순환 참조 등 — 값을 못 적어도 **무엇이 있었다는 사실**은 남긴다. */\n        return String(a)\n      }\n    })\n    .join(' ')\n}\n\n/* 수준 표기는 프레임워크와 같은 낱말을 쓴다(`info`·`warn`·`error`) — 같은 파일에서 걸러 읽는다. */\nexport const twinLog = (...args: unknown[]): void => console.log(`${stamp()} info: ${line(args)}`)\nexport const twinWarn = (...args: unknown[]): void => console.warn(`${stamp()} warn: ${line(args)}`)\nexport const twinError = (...args: unknown[]): void => console.error(`${stamp()} error: ${line(args)}`)\n"]}

package/dist-server/engine/loop-lag.d.ts

@@ -0,0 +1,54 @@
+/** 표본 간격(ms) — 촘촘할 필요가 없다. 긴 정체를 놓치지 않는 정도면 된다. */
+export declare const LAG_SAMPLE_MS = 500;
+/** 이 값을 넘는 지체만 「정체」로 센다(ms). 사람이 화면에서 느끼기 시작하는 크기. */
+export declare const LAG_STALL_MS = 200;
+/** 창 길이(ms) — `twinLoad` 의 창과 같은 크기로 두어 나란히 읽는다. */
+export declare const LAG_WINDOW_MS = 10000;
+export interface LoopLagWindow {
+    /** 이 창에서 가장 길게 막힌 시간(ms). */
+    maxMs: number;
+    /** 정체(문턱 초과) 횟수. */
+    stalls: number;
+    /** 표본 수 — 분모다. */
+    samples: number;
+    /** 지체 합(ms) — 평균은 읽는 쪽에서 낸다. */
+    totalMs: number;
+    /** 창이 열린 시각. */
+    startMs: number;
+}
+export interface LoopLagView {
+    /** 마지막으로 닫힌 창 — 「지금 어떤가」. 아직 한 창도 안 지났으면 null. */
+    recent: (LoopLagWindow & {
+        endMs: number;
+    }) | null;
+    /** 기동 이후 누적. */
+    total: LoopLagWindow;
+    /** 기동 이후 가장 길게 막힌 시각(ms, epoch) — 언제였는지가 원인을 가리는 데 쓰인다. */
+    worstAtMs: number | null;
+    /** 표본 간격 — 읽는 쪽이 이 값보다 짧은 정체는 못 본다는 것을 알아야 한다. */
+    sampleMs: number;
+    /** 정체로 세는 문턱. */
+    stallMs: number;
+}
+export declare class LoopLagSampler {
+    private window;
+    private closed;
+    private total;
+    private worstAtMs;
+    private timer;
+    private expectedMs;
+    private sampleMs;
+    private stallMs;
+    private windowMs;
+    private now;
+    constructor(sampleMs?: number, stallMs?: number, windowMs?: number, now?: () => number);
+    /** 표본을 하나 넣는다 — 타이머가 부르고, 시험은 직접 부른다(시계를 밀어 넣어 잰다). */
+    sample(atMs?: number): number;
+    /** 계기판이 읽는 값. **한 창도 닫히지 않았으면 `recent` 는 null** — 채우는 중인 창은 과소 집계다. */
+    view(): LoopLagView;
+    /** 표본 타이머 기동(1회) — 프로세스 종료를 막지 않는다. */
+    start(): void;
+    stop(): void;
+}
+/** 프로세스 하나의 루프를 재는 것이므로 표본기도 하나다. */
+export declare const loopLag: LoopLagSampler;

package/dist-server/engine/loop-lag.js

@@ -0,0 +1,87 @@
+"use strict";
+/*
+ * 이벤트 루프 지체 — **화면이 느린 이유를 지어내지 않기 위해.** 순수(import 없음).
+ *
+ * ── 왜 필요한가 (2026-08-21) ────────────────────────────────────────────────
+ * 「UI 반응성이 느리다」를 진단하려 했는데, 있는 계기판으로는 답이 나오지 않았다. `twinLoad` 는 **트윈의
+ * 계측된 작업**만 재고, `processCpuRatio` 는 프로세스 전체를 재지만 **언제 얼마나 멈췄나**를 말하지
+ * 못한다. 밖에서 HTTP 지연을 재 보니 같은 요청이 44ms 와 5.8초로 갈라졌는데, 그 5.8초가 트윈 때문인지
+ * webpack 재빌드 때문인지 남의 재기동 때문인지 **가릴 근거가 없었다.**
+ *
+ * 근거 없이 원인을 고르면 엉뚱한 곳을 고친다. 그래서 루프가 실제로 얼마나 막혔는지를 잰다.
+ *
+ * ── 어떻게 재나 ─────────────────────────────────────────────────────────────
+ * 일정 간격으로 깨어나는 타이머를 두고, **예정 시각과 실제 시각의 차이**를 본다. 루프가 막혀 있었으면
+ * 그만큼 늦게 깨어난다. 재는 비용은 그 차이 계산 하나뿐이다(창마다 값 다섯).
+ *
+ * 이 값은 **원인을 말하지 않는다** — 「200ms 이상 막힌 일이 이 창에서 세 번, 가장 긴 것은 4.6초」까지가
+ * 사실이다. 원인은 그 시각의 트윈 부하(`twinLoad`)와 프로세스 CPU 와 나란히 놓고 사람이 가린다.
+ * 재지 않은 것을 0 으로 적지 않는다 — 한 번도 깨어나지 않았으면 `null` 이다.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loopLag = exports.LoopLagSampler = exports.LAG_WINDOW_MS = exports.LAG_STALL_MS = exports.LAG_SAMPLE_MS = void 0;
+/** 표본 간격(ms) — 촘촘할 필요가 없다. 긴 정체를 놓치지 않는 정도면 된다. */
+exports.LAG_SAMPLE_MS = 500;
+/** 이 값을 넘는 지체만 「정체」로 센다(ms). 사람이 화면에서 느끼기 시작하는 크기. */
+exports.LAG_STALL_MS = 200;
+/** 창 길이(ms) — `twinLoad` 의 창과 같은 크기로 두어 나란히 읽는다. */
+exports.LAG_WINDOW_MS = 10_000;
+const emptyWindow = (startMs) => ({ maxMs: 0, stalls: 0, samples: 0, totalMs: 0, startMs });
+class LoopLagSampler {
+    /* 생성자 파라미터 프로퍼티(`private x = …`)는 쓰지 않는다 — 시험이 소스를 그대로 실행하는데
+       (타입 제거 실행 방식) 그 문법은 지원되지 않아 파일 전체가 열리지 않는다. */
+    constructor(sampleMs = exports.LAG_SAMPLE_MS, stallMs = exports.LAG_STALL_MS, windowMs = exports.LAG_WINDOW_MS, now = Date.now) {
+        this.closed = null;
+        this.worstAtMs = null;
+        this.sampleMs = sampleMs;
+        this.stallMs = stallMs;
+        this.windowMs = windowMs;
+        this.now = now;
+        const t = this.now();
+        this.window = emptyWindow(t);
+        this.total = emptyWindow(t);
+        this.expectedMs = t + sampleMs;
+    }
+    /** 표본을 하나 넣는다 — 타이머가 부르고, 시험은 직접 부른다(시계를 밀어 넣어 잰다). */
+    sample(atMs = this.now()) {
+        const lag = Math.max(0, atMs - this.expectedMs);
+        this.expectedMs = atMs + this.sampleMs;
+        for (const w of [this.window, this.total]) {
+            w.samples += 1;
+            w.totalMs += lag;
+            if (lag > this.stallMs)
+                w.stalls += 1;
+            if (lag > w.maxMs)
+                w.maxMs = lag;
+        }
+        if (lag >= this.total.maxMs && lag > this.stallMs)
+            this.worstAtMs = atMs;
+        if (atMs - this.window.startMs >= this.windowMs) {
+            this.closed = { ...this.window, endMs: atMs };
+            this.window = emptyWindow(atMs);
+        }
+        return lag;
+    }
+    /** 계기판이 읽는 값. **한 창도 닫히지 않았으면 `recent` 는 null** — 채우는 중인 창은 과소 집계다. */
+    view() {
+        return { recent: this.closed, total: this.total, worstAtMs: this.worstAtMs, sampleMs: this.sampleMs, stallMs: this.stallMs };
+    }
+    /** 표본 타이머 기동(1회) — 프로세스 종료를 막지 않는다. */
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => this.sample(), this.sampleMs);
+        if (typeof this.timer?.unref === 'function')
+            this.timer.unref();
+    }
+    stop() {
+        if (!this.timer)
+            return;
+        clearInterval(this.timer);
+        this.timer = undefined;
+    }
+}
+exports.LoopLagSampler = LoopLagSampler;
+/** 프로세스 하나의 루프를 재는 것이므로 표본기도 하나다. */
+exports.loopLag = new LoopLagSampler();
+//# sourceMappingURL=loop-lag.js.map

package/dist-server/engine/loop-lag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-lag.js","sourceRoot":"","sources":["../../server/engine/loop-lag.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * 이벤트 루프 지체 — **화면이 느린 이유를 지어내지 않기 위해.** 순수(import 없음).\n *\n * ── 왜 필요한가 (2026-08-21) ────────────────────────────────────────────────\n * 「UI 반응성이 느리다」를 진단하려 했는데, 있는 계기판으로는 답이 나오지 않았다. `twinLoad` 는 **트윈의\n * 계측된 작업**만 재고, `processCpuRatio` 는 프로세스 전체를 재지만 **언제 얼마나 멈췄나**를 말하지\n * 못한다. 밖에서 HTTP 지연을 재 보니 같은 요청이 44ms 와 5.8초로 갈라졌는데, 그 5.8초가 트윈 때문인지\n * webpack 재빌드 때문인지 남의 재기동 때문인지 **가릴 근거가 없었다.**\n *\n * 근거 없이 원인을 고르면 엉뚱한 곳을 고친다. 그래서 루프가 실제로 얼마나 막혔는지를 잰다.\n *\n * ── 어떻게 재나 ─────────────────────────────────────────────────────────────\n * 일정 간격으로 깨어나는 타이머를 두고, **예정 시각과 실제 시각의 차이**를 본다. 루프가 막혀 있었으면\n * 그만큼 늦게 깨어난다. 재는 비용은 그 차이 계산 하나뿐이다(창마다 값 다섯).\n *\n * 이 값은 **원인을 말하지 않는다** — 「200ms 이상 막힌 일이 이 창에서 세 번, 가장 긴 것은 4.6초」까지가\n * 사실이다. 원인은 그 시각의 트윈 부하(`twinLoad`)와 프로세스 CPU 와 나란히 놓고 사람이 가린다.\n * 재지 않은 것을 0 으로 적지 않는다 — 한 번도 깨어나지 않았으면 `null` 이다.\n */\n\n/** 표본 간격(ms) — 촘촘할 필요가 없다. 긴 정체를 놓치지 않는 정도면 된다. */\nexport const LAG_SAMPLE_MS = 500\n/** 이 값을 넘는 지체만 「정체」로 센다(ms). 사람이 화면에서 느끼기 시작하는 크기. */\nexport const LAG_STALL_MS = 200\n/** 창 길이(ms) — `twinLoad` 의 창과 같은 크기로 두어 나란히 읽는다. */\nexport const LAG_WINDOW_MS = 10_000\n\nexport interface LoopLagWindow {\n  /** 이 창에서 가장 길게 막힌 시간(ms). */\n  maxMs: number\n  /** 정체(문턱 초과) 횟수. */\n  stalls: number\n  /** 표본 수 — 분모다. */\n  samples: number\n  /** 지체 합(ms) — 평균은 읽는 쪽에서 낸다. */\n  totalMs: number\n  /** 창이 열린 시각. */\n  startMs: number\n}\n\nexport interface LoopLagView {\n  /** 마지막으로 닫힌 창 — 「지금 어떤가」. 아직 한 창도 안 지났으면 null. */\n  recent: (LoopLagWindow & { endMs: number }) | null\n  /** 기동 이후 누적. */\n  total: LoopLagWindow\n  /** 기동 이후 가장 길게 막힌 시각(ms, epoch) — 언제였는지가 원인을 가리는 데 쓰인다. */\n  worstAtMs: number | null\n  /** 표본 간격 — 읽는 쪽이 이 값보다 짧은 정체는 못 본다는 것을 알아야 한다. */\n  sampleMs: number\n  /** 정체로 세는 문턱. */\n  stallMs: number\n}\n\nconst emptyWindow = (startMs: number): LoopLagWindow => ({ maxMs: 0, stalls: 0, samples: 0, totalMs: 0, startMs })\n\nexport class LoopLagSampler {\n  private window: LoopLagWindow\n  private closed: (LoopLagWindow & { endMs: number }) | null = null\n  private total: LoopLagWindow\n  private worstAtMs: number | null = null\n  private timer: any\n  private expectedMs: number\n\n  private sampleMs: number\n  private stallMs: number\n  private windowMs: number\n  private now: () => number\n\n  /* 생성자 파라미터 프로퍼티(`private x = …`)는 쓰지 않는다 — 시험이 소스를 그대로 실행하는데\n     (타입 제거 실행 방식) 그 문법은 지원되지 않아 파일 전체가 열리지 않는다. */\n  constructor(sampleMs = LAG_SAMPLE_MS, stallMs = LAG_STALL_MS, windowMs = LAG_WINDOW_MS, now: () => number = Date.now) {\n    this.sampleMs = sampleMs\n    this.stallMs = stallMs\n    this.windowMs = windowMs\n    this.now = now\n    const t = this.now()\n    this.window = emptyWindow(t)\n    this.total = emptyWindow(t)\n    this.expectedMs = t + sampleMs\n  }\n\n  /** 표본을 하나 넣는다 — 타이머가 부르고, 시험은 직접 부른다(시계를 밀어 넣어 잰다). */\n  sample(atMs = this.now()): number {\n    const lag = Math.max(0, atMs - this.expectedMs)\n    this.expectedMs = atMs + this.sampleMs\n    for (const w of [this.window, this.total]) {\n      w.samples += 1\n      w.totalMs += lag\n      if (lag > this.stallMs) w.stalls += 1\n      if (lag > w.maxMs) w.maxMs = lag\n    }\n    if (lag >= this.total.maxMs && lag > this.stallMs) this.worstAtMs = atMs\n    if (atMs - this.window.startMs >= this.windowMs) {\n      this.closed = { ...this.window, endMs: atMs }\n      this.window = emptyWindow(atMs)\n    }\n    return lag\n  }\n\n  /** 계기판이 읽는 값. **한 창도 닫히지 않았으면 `recent` 는 null** — 채우는 중인 창은 과소 집계다. */\n  view(): LoopLagView {\n    return { recent: this.closed, total: this.total, worstAtMs: this.worstAtMs, sampleMs: this.sampleMs, stallMs: this.stallMs }\n  }\n\n  /** 표본 타이머 기동(1회) — 프로세스 종료를 막지 않는다. */\n  start(): void {\n    if (this.timer) return\n    this.timer = setInterval(() => this.sample(), this.sampleMs)\n    if (typeof this.timer?.unref === 'function') this.timer.unref()\n  }\n\n  stop(): void {\n    if (!this.timer) return\n    clearInterval(this.timer)\n    this.timer = undefined\n  }\n}\n\n/** 프로세스 하나의 루프를 재는 것이므로 표본기도 하나다. */\nexport const loopLag = new LoopLagSampler()\n"]}

package/dist-server/engine/model-gap.d.ts

@@ -0,0 +1,108 @@
+/** 커널 스냅샷에서 우리가 읽는 것만. 나머지 필드는 알 필요가 없다. */
+export interface ModelGapSource {
+    locations?: {
+        id?: string;
+        origin?: string;
+    }[];
+    equipment?: {
+        id?: string;
+        origin?: string;
+    }[];
+    persons?: {
+        id?: string;
+        origin?: string;
+    }[];
+    /** 커널이 담을 줄 몰라 세어 둔 사건 — 종류별 개수와 처음·마지막 시각. */
+    unhandled?: {
+        eventType: string;
+        count: number;
+        firstAtMs?: number;
+        lastAtMs?: number;
+    }[];
+    /**
+     * EMS 상태 — **`energy` 안에 있다.**
+     *
+     * `unknownEquipment` 를 루트에서 읽고 있었다(2026-08-20에 잡음). 커널은 그것을 `EnergyState` 안에
+     * 담으므로, 루트에서 읽으면 **영원히 `null`** 이다 — 오류도 없이 「에너지 트윈이 아니다」로 읽힌다.
+     * 나만 읽는 필드를 잘못된 경로에서 읽으면 이렇게 조용히 사라진다.
+     *
+     * 계량 지점의 `origin` 은 **없을 수 있다**(옛 스냅샷에서 이어받은 지점). 그때는 「선언되었다」가
+     * 아니라 **모른다**다.
+     */
+    energy?: {
+        points?: {
+            id?: string;
+            origin?: string;
+        }[];
+        /** 모델이 모르는 설비가 에너지 상태를 보내 온 횟수. 0 이면 커널이 이 칸을 만들지 않는다. */
+        unknownEquipment?: number;
+    };
+}
+/**
+ * 화면에 내는 id 수 상한.
+ *
+ * 오타 하나를 찾는 데 스무 개면 충분하고, 원천이 수천 개를 보내는 경우(모델을 아예 안 맞춘 경우)에
+ * 목록으로 화면을 채울 이유가 없다. **넘친 수는 함께 낸다** — 조용히 자르지 않는다.
+ */
+export declare const GAP_ID_LIMIT = 20;
+export interface ModelGapAxis {
+    /** 관측으로만 알게 된 id 수. */
+    count: number;
+    /** 그중 화면에 싣는 것(최대 `GAP_ID_LIMIT`). */
+    ids: string[];
+    /** 상한에서 밀려난 수. 0 이면 전부 실었다. */
+    more: number;
+    /**
+     * 출처를 **모르는** 수 — 표시가 없는 항목.
+     *
+     * 「선언되었다」로 세지 않는다. 계량기는 이 표시가 늦게 생겼으므로 옛 스냅샷에서 이어받은 지점에는
+     * 칸이 없다(`undefined`). 그것을 마스터로 세면 오타를 놓치고, 관측으로 세면 정상을 문제로 만든다.
+     * 둘 다 틀리므로 **모른다고 센다.**
+     */
+    unknown: number;
+}
+export interface ModelGapView {
+    locations: ModelGapAxis;
+    equipment: ModelGapAxis;
+    persons: ModelGapAxis;
+    /**
+     * EMS 계량 지점.
+     *
+     * ── 이 축이 가장 무겁다 ────────────────────────────────────────────────────
+     * 모르는 `meterId` 는 조용히 새 계량기가 되고 그 kW 가 그 현장의 **수요 구간·피크·요금 판정**에
+     * 더해진다. 오타 하나면 진짜 계량기는 멈추고 유령이 누적된다 — 숫자는 그럴듯하고 틀린다. 자리 오타는
+     * 스키매틱이 비는 것으로 드러나지만, 이건 그럴듯한 숫자로 나온다.
+     *
+     * 커널이 `origin` 을 **표본마다 다시 맞춘다** — 선언의 정본은 모델이고 모델은 채택으로 늘어나므로,
+     * 한 번 찍고 두면 나중에 선언된 계량기가 영원히 `observed` 로 남는다. 그래서 이 값은 「지금 모델에
+     * 있는가」의 답이고, 「한 번 오타였다」의 답이 아니다.
+     */
+    meters: ModelGapAxis;
+    /** 세 축의 합 — 화면이 「있나 없나」를 한 번에 묻기 위한 값. */
+    total: number;
+    /** 커널이 담을 줄 모른 사건들(종류별). 참조 문제와 다른 사실이므로 따로 낸다. */
+    unhandled: {
+        eventType: string;
+        count: number;
+        lastAt: string | null;
+    }[];
+    /** EMS: 모델이 모르는 설비의 에너지 보고 횟수. 없으면 `null`(0 과 구별한다). */
+    unknownEquipmentReports: number | null;
+    /**
+     * 아직 덮지 못하는 축 — **모르는 것을 모른다고 말한다.**
+     *
+     * 계량기는 커널 0.7.39 부터 덮인다(그 전에는 `origin` 표시가 없어 오타를 찾아 줄 수 없었다).
+     * 비어 있는 것이 정상이고, 새 축이 표시 없이 들어오면 여기에 이름을 넣는다 — 화면이 「다 찾아
+     * 준다」고 말하지 않게.
+     */
+    notCovered: string[];
+}
+/** 계량기 축이 아직 덮이지 않는 이유 — 화면이 그대로 말할 수 있게 이름을 여기 둔다. */
+export declare const NOT_COVERED_METERS = "meters";
+/**
+ * 스냅샷 → 모델 갭.
+ *
+ * 스냅샷이 없으면 `null` 이다 — **0 이 아니다.** 트윈이 돌지 않으면 비교할 상대가 없고, 「없다」와
+ * 「세어 보지 못했다」는 다른 사실이다(모델 인스펙션이 같은 규율을 쓴다).
+ */
+export declare function modelGapOf(snapshot: ModelGapSource | null | undefined): ModelGapView | null;

package/dist-server/engine/model-gap.js

@@ -0,0 +1,95 @@
+"use strict";
+/*
+ * **원본이 말한 적 없는 것** — 미해결 참조를 세는 한 자리. 순수(import 없음).
+ *
+ * ── 무엇을 답하나 ───────────────────────────────────────────────────────────
+ * 원천이 우리 모델에 없는 id 를 보내면 어떻게 되나. 유입 문(`ingestCanonicalRecords`)은 **거부하지
+ * 않는다** — 실측으로 확인했다(2026-08-20):
+ *
+ *   모르는 로케이션 「오타-99」        → 통과
+ *   모르는 bizStep 「PUTAWAY_X17」   → 통과
+ *   모르는 계량기 「MMXU-오타-99」    → 통과
+ *
+ * 거부하지 않는 것이 옳다. 원천이 모델보다 먼저 새 로케이션을 말하는 것은 정상이고(구조 갱신은 늦게 온다),
+ * 거부하면 그 선행 계측을 잃는다. 그래서 커널은 **흡수하고 표시한다** — 마스터에 없던 로케이션은
+ * `origin: 'observed'` 로 승격되어 스냅샷에 실린다(`ObservedReducer.touchLocation`).
+ *
+ * ── 왜 이 파일이 있나 ───────────────────────────────────────────────────────
+ * 그 표시를 읽는 곳이 **모델 인스펙션 화면 하나**였다. 그런데 이 사실을 필요로 하는 사람은 「이 트윈이
+ * 현장과 맞춰지고 있나」를 보는 사람이다 — 원천이 우리가 모르는 로케이션만 보내고 있으면 트윈은 도는데
+ * 스키매틱은 비어 있고, 그것이 우리가 「빈 공장」이라 불러 온 상태다.
+ *
+ * 도출을 두 곳에 적으면 두 화면이 다른 수를 말하게 된다. 그래서 여기 한 벌만 둔다.
+ *
+ * ── 판정을 바꾸지 않는다 ────────────────────────────────────────────────────
+ * 동기화 판정(`syncVerdictOf`)은 **피드**를 말한다: 오고 있나, 통과하나. 이 갭은 **모델**을 말한다:
+ * 원천이 아는 것을 우리가 선언했나. 둘을 한 판정에 섞으면 「유입은 정상인데 모델이 뒤처졌다」와
+ * 「유입이 막혔다」가 같은 색으로 보이고, 처방이 완전히 다르다.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NOT_COVERED_METERS = exports.GAP_ID_LIMIT = void 0;
+exports.modelGapOf = modelGapOf;
+/**
+ * 화면에 내는 id 수 상한.
+ *
+ * 오타 하나를 찾는 데 스무 개면 충분하고, 원천이 수천 개를 보내는 경우(모델을 아예 안 맞춘 경우)에
+ * 목록으로 화면을 채울 이유가 없다. **넘친 수는 함께 낸다** — 조용히 자르지 않는다.
+ */
+exports.GAP_ID_LIMIT = 20;
+/** 계량기 축이 아직 덮이지 않는 이유 — 화면이 그대로 말할 수 있게 이름을 여기 둔다. */
+exports.NOT_COVERED_METERS = 'meters';
+function axisOf(rows) {
+    const ids = [];
+    let count = 0;
+    let unknown = 0;
+    for (const r of rows ?? []) {
+        if (r?.origin === 'observed') {
+            count++;
+            if (ids.length < exports.GAP_ID_LIMIT)
+                ids.push(String(r.id ?? ''));
+        }
+        else if (r?.origin !== 'master') {
+            /* 표시가 없다 — 마스터로도 관측으로도 세지 않는다. 모르는 것은 모른다고 센다. */
+            unknown++;
+        }
+    }
+    return { count, ids, more: Math.max(0, count - ids.length), unknown };
+}
+/**
+ * 스냅샷 → 모델 갭.
+ *
+ * 스냅샷이 없으면 `null` 이다 — **0 이 아니다.** 트윈이 돌지 않으면 비교할 상대가 없고, 「없다」와
+ * 「세어 보지 못했다」는 다른 사실이다(모델 인스펙션이 같은 규율을 쓴다).
+ */
+function modelGapOf(snapshot) {
+    if (!snapshot)
+        return null;
+    const locations = axisOf(snapshot.locations);
+    const equipment = axisOf(snapshot.equipment);
+    const persons = axisOf(snapshot.persons);
+    const meters = axisOf(snapshot.energy?.points);
+    return {
+        locations,
+        equipment,
+        persons,
+        meters,
+        total: locations.count + equipment.count + persons.count + meters.count,
+        unhandled: (snapshot.unhandled ?? []).map(u => ({
+            eventType: u.eventType,
+            count: u.count,
+            /* 마지막 시각이 멈춘 종류는 이미 고쳐진 것이다. 없으면 지어내지 않는다. */
+            lastAt: Number.isFinite(u.lastAtMs) ? new Date(u.lastAtMs).toISOString() : null
+        })),
+        /*
+         * 커널은 0 이면 이 칸을 만들지 않는다. 그래서 「없음」은 두 뜻이다 — 에너지 트윈이 아니거나, 세었고
+         * 0 이었다. 둘을 가르려면 `energy` 자체가 있는지를 본다: 있으면 세었고 0 이다.
+         */
+        unknownEquipmentReports: typeof snapshot.energy?.unknownEquipment === 'number' ? snapshot.energy.unknownEquipment : snapshot.energy ? 0 : null,
+        /*
+         * 이제 계량기도 덮는다(커널 0.7.39 가 `MeterPointState.origin` 을 낸다). 덮지 못하는 축이 생기면
+         * 다시 여기에 이름을 넣는다 — 화면이 「다 찾아 준다」고 말하지 않게.
+         */
+        notCovered: []
+    };
+}
+//# sourceMappingURL=model-gap.js.map

package/dist-server/engine/model-gap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-gap.js","sourceRoot":"","sources":["../../server/engine/model-gap.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;;;AA6GH,gCAgCC;AAnHD;;;;;GAKG;AACU,QAAA,YAAY,GAAG,EAAE,CAAA;AAoD9B,uDAAuD;AAC1C,QAAA,kBAAkB,GAAG,QAAQ,CAAA;AAE1C,SAAS,MAAM,CAAC,IAAoD;IAClE,MAAM,GAAG,GAAa,EAAE,CAAA;IACxB,IAAI,KAAK,GAAG,CAAC,CAAA;IACb,IAAI,OAAO,GAAG,CAAC,CAAA;IACf,KAAK,MAAM,CAAC,IAAI,IAAI,IAAI,EAAE,EAAE,CAAC;QAC3B,IAAI,CAAC,EAAE,MAAM,KAAK,UAAU,EAAE,CAAC;YAC7B,KAAK,EAAE,CAAA;YACP,IAAI,GAAG,CAAC,MAAM,GAAG,oBAAY;gBAAE,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;QAC7D,CAAC;aAAM,IAAI,CAAC,EAAE,MAAM,KAAK,QAAQ,EAAE,CAAC;YAClC,kDAAkD;YAClD,OAAO,EAAE,CAAA;QACX,CAAC;IACH,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAA;AACvE,CAAC;AAED;;;;;GAKG;AACH,SAAgB,UAAU,CAAC,QAA2C;IACpE,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAA;IAE1B,MAAM,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAA;IAC5C,MAAM,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAA;IAC5C,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;IACxC,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAE9C,OAAO;QACL,SAAS;QACT,SAAS;QACT,OAAO;QACP,MAAM;QACN,KAAK,EAAE,SAAS,CAAC,KAAK,GAAG,SAAS,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK;QACvE,SAAS,EAAE,CAAC,QAAQ,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YAC9C,SAAS,EAAE,CAAC,CAAC,SAAS;YACtB,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,8CAA8C;YAC9C,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,QAAkB,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI;SAC1F,CAAC,CAAC;QACH;;;WAGG;QACH,uBAAuB,EACrB,OAAO,QAAQ,CAAC,MAAM,EAAE,gBAAgB,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI;QACvH;;;WAGG;QACH,UAAU,EAAE,EAAE;KACf,CAAA;AACH,CAAC","sourcesContent":["/*\n * **원본이 말한 적 없는 것** — 미해결 참조를 세는 한 자리. 순수(import 없음).\n *\n * ── 무엇을 답하나 ───────────────────────────────────────────────────────────\n * 원천이 우리 모델에 없는 id 를 보내면 어떻게 되나. 유입 문(`ingestCanonicalRecords`)은 **거부하지\n * 않는다** — 실측으로 확인했다(2026-08-20):\n *\n *   모르는 로케이션 「오타-99」        → 통과\n *   모르는 bizStep 「PUTAWAY_X17」   → 통과\n *   모르는 계량기 「MMXU-오타-99」    → 통과\n *\n * 거부하지 않는 것이 옳다. 원천이 모델보다 먼저 새 로케이션을 말하는 것은 정상이고(구조 갱신은 늦게 온다),\n * 거부하면 그 선행 계측을 잃는다. 그래서 커널은 **흡수하고 표시한다** — 마스터에 없던 로케이션은\n * `origin: 'observed'` 로 승격되어 스냅샷에 실린다(`ObservedReducer.touchLocation`).\n *\n * ── 왜 이 파일이 있나 ───────────────────────────────────────────────────────\n * 그 표시를 읽는 곳이 **모델 인스펙션 화면 하나**였다. 그런데 이 사실을 필요로 하는 사람은 「이 트윈이\n * 현장과 맞춰지고 있나」를 보는 사람이다 — 원천이 우리가 모르는 로케이션만 보내고 있으면 트윈은 도는데\n * 스키매틱은 비어 있고, 그것이 우리가 「빈 공장」이라 불러 온 상태다.\n *\n * 도출을 두 곳에 적으면 두 화면이 다른 수를 말하게 된다. 그래서 여기 한 벌만 둔다.\n *\n * ── 판정을 바꾸지 않는다 ────────────────────────────────────────────────────\n * 동기화 판정(`syncVerdictOf`)은 **피드**를 말한다: 오고 있나, 통과하나. 이 갭은 **모델**을 말한다:\n * 원천이 아는 것을 우리가 선언했나. 둘을 한 판정에 섞으면 「유입은 정상인데 모델이 뒤처졌다」와\n * 「유입이 막혔다」가 같은 색으로 보이고, 처방이 완전히 다르다.\n */\n\n/** 커널 스냅샷에서 우리가 읽는 것만. 나머지 필드는 알 필요가 없다. */\nexport interface ModelGapSource {\n  locations?: { id?: string; origin?: string }[]\n  equipment?: { id?: string; origin?: string }[]\n  persons?: { id?: string; origin?: string }[]\n  /** 커널이 담을 줄 몰라 세어 둔 사건 — 종류별 개수와 처음·마지막 시각. */\n  unhandled?: { eventType: string; count: number; firstAtMs?: number; lastAtMs?: number }[]\n  /**\n   * EMS 상태 — **`energy` 안에 있다.**\n   *\n   * `unknownEquipment` 를 루트에서 읽고 있었다(2026-08-20에 잡음). 커널은 그것을 `EnergyState` 안에\n   * 담으므로, 루트에서 읽으면 **영원히 `null`** 이다 — 오류도 없이 「에너지 트윈이 아니다」로 읽힌다.\n   * 나만 읽는 필드를 잘못된 경로에서 읽으면 이렇게 조용히 사라진다.\n   *\n   * 계량 지점의 `origin` 은 **없을 수 있다**(옛 스냅샷에서 이어받은 지점). 그때는 「선언되었다」가\n   * 아니라 **모른다**다.\n   */\n  energy?: {\n    points?: { id?: string; origin?: string }[]\n    /** 모델이 모르는 설비가 에너지 상태를 보내 온 횟수. 0 이면 커널이 이 칸을 만들지 않는다. */\n    unknownEquipment?: number\n  }\n}\n\n/**\n * 화면에 내는 id 수 상한.\n *\n * 오타 하나를 찾는 데 스무 개면 충분하고, 원천이 수천 개를 보내는 경우(모델을 아예 안 맞춘 경우)에\n * 목록으로 화면을 채울 이유가 없다. **넘친 수는 함께 낸다** — 조용히 자르지 않는다.\n */\nexport const GAP_ID_LIMIT = 20\n\nexport interface ModelGapAxis {\n  /** 관측으로만 알게 된 id 수. */\n  count: number\n  /** 그중 화면에 싣는 것(최대 `GAP_ID_LIMIT`). */\n  ids: string[]\n  /** 상한에서 밀려난 수. 0 이면 전부 실었다. */\n  more: number\n  /**\n   * 출처를 **모르는** 수 — 표시가 없는 항목.\n   *\n   * 「선언되었다」로 세지 않는다. 계량기는 이 표시가 늦게 생겼으므로 옛 스냅샷에서 이어받은 지점에는\n   * 칸이 없다(`undefined`). 그것을 마스터로 세면 오타를 놓치고, 관측으로 세면 정상을 문제로 만든다.\n   * 둘 다 틀리므로 **모른다고 센다.**\n   */\n  unknown: number\n}\n\nexport interface ModelGapView {\n  locations: ModelGapAxis\n  equipment: ModelGapAxis\n  persons: ModelGapAxis\n  /**\n   * EMS 계량 지점.\n   *\n   * ── 이 축이 가장 무겁다 ────────────────────────────────────────────────────\n   * 모르는 `meterId` 는 조용히 새 계량기가 되고 그 kW 가 그 현장의 **수요 구간·피크·요금 판정**에\n   * 더해진다. 오타 하나면 진짜 계량기는 멈추고 유령이 누적된다 — 숫자는 그럴듯하고 틀린다. 자리 오타는\n   * 스키매틱이 비는 것으로 드러나지만, 이건 그럴듯한 숫자로 나온다.\n   *\n   * 커널이 `origin` 을 **표본마다 다시 맞춘다** — 선언의 정본은 모델이고 모델은 채택으로 늘어나므로,\n   * 한 번 찍고 두면 나중에 선언된 계량기가 영원히 `observed` 로 남는다. 그래서 이 값은 「지금 모델에\n   * 있는가」의 답이고, 「한 번 오타였다」의 답이 아니다.\n   */\n  meters: ModelGapAxis\n  /** 세 축의 합 — 화면이 「있나 없나」를 한 번에 묻기 위한 값. */\n  total: number\n  /** 커널이 담을 줄 모른 사건들(종류별). 참조 문제와 다른 사실이므로 따로 낸다. */\n  unhandled: { eventType: string; count: number; lastAt: string | null }[]\n  /** EMS: 모델이 모르는 설비의 에너지 보고 횟수. 없으면 `null`(0 과 구별한다). */\n  unknownEquipmentReports: number | null\n  /**\n   * 아직 덮지 못하는 축 — **모르는 것을 모른다고 말한다.**\n   *\n   * 계량기는 커널 0.7.39 부터 덮인다(그 전에는 `origin` 표시가 없어 오타를 찾아 줄 수 없었다).\n   * 비어 있는 것이 정상이고, 새 축이 표시 없이 들어오면 여기에 이름을 넣는다 — 화면이 「다 찾아\n   * 준다」고 말하지 않게.\n   */\n  notCovered: string[]\n}\n\n/** 계량기 축이 아직 덮이지 않는 이유 — 화면이 그대로 말할 수 있게 이름을 여기 둔다. */\nexport const NOT_COVERED_METERS = 'meters'\n\nfunction axisOf(rows: { id?: string; origin?: string }[] | undefined): ModelGapAxis {\n  const ids: string[] = []\n  let count = 0\n  let unknown = 0\n  for (const r of rows ?? []) {\n    if (r?.origin === 'observed') {\n      count++\n      if (ids.length < GAP_ID_LIMIT) ids.push(String(r.id ?? ''))\n    } else if (r?.origin !== 'master') {\n      /* 표시가 없다 — 마스터로도 관측으로도 세지 않는다. 모르는 것은 모른다고 센다. */\n      unknown++\n    }\n  }\n  return { count, ids, more: Math.max(0, count - ids.length), unknown }\n}\n\n/**\n * 스냅샷 → 모델 갭.\n *\n * 스냅샷이 없으면 `null` 이다 — **0 이 아니다.** 트윈이 돌지 않으면 비교할 상대가 없고, 「없다」와\n * 「세어 보지 못했다」는 다른 사실이다(모델 인스펙션이 같은 규율을 쓴다).\n */\nexport function modelGapOf(snapshot: ModelGapSource | null | undefined): ModelGapView | null {\n  if (!snapshot) return null\n\n  const locations = axisOf(snapshot.locations)\n  const equipment = axisOf(snapshot.equipment)\n  const persons = axisOf(snapshot.persons)\n  const meters = axisOf(snapshot.energy?.points)\n\n  return {\n    locations,\n    equipment,\n    persons,\n    meters,\n    total: locations.count + equipment.count + persons.count + meters.count,\n    unhandled: (snapshot.unhandled ?? []).map(u => ({\n      eventType: u.eventType,\n      count: u.count,\n      /* 마지막 시각이 멈춘 종류는 이미 고쳐진 것이다. 없으면 지어내지 않는다. */\n      lastAt: Number.isFinite(u.lastAtMs) ? new Date(u.lastAtMs as number).toISOString() : null\n    })),\n    /*\n     * 커널은 0 이면 이 칸을 만들지 않는다. 그래서 「없음」은 두 뜻이다 — 에너지 트윈이 아니거나, 세었고\n     * 0 이었다. 둘을 가르려면 `energy` 자체가 있는지를 본다: 있으면 세었고 0 이다.\n     */\n    unknownEquipmentReports:\n      typeof snapshot.energy?.unknownEquipment === 'number' ? snapshot.energy.unknownEquipment : snapshot.energy ? 0 : null,\n    /*\n     * 이제 계량기도 덮는다(커널 0.7.39 가 `MeterPointState.origin` 을 낸다). 덮지 못하는 축이 생기면\n     * 다시 여기에 이름을 넣는다 — 화면이 「다 찾아 준다」고 말하지 않게.\n     */\n    notCovered: []\n  }\n}\n"]}

package/dist-server/engine/restart-policy.d.ts

@@ -2,12 +2,12 @@
 export type RestartPolicy = 'resync' | 'resume' | 'reset';
 export declare const RESTART_POLICIES: readonly RestartPolicy[];
 /**
- * 저장된 값을 정책으로 읽는다 — **모르면 던진다**(기본값으로 메우지 않는다).
+ * 저장된 값을 정책으로 읽는다 — **모르면 오류를 낸다**(기본값으로 메우지 않는다).
  *
  * 옛 어휘(`mirror`·`sim-world`·`sim-experiment`)를 여기서 번역하지 않는다: 번역을 두면 옛 값이 살아남고,
  * 그 값이 다시 어딘가에 저장된다. 저장된 값은 **한 번 옮기고**(데이터 이관) 코드는 새 어휘만 안다.
- * 그래서 이 함수는 옛 값에 대해서도 던지며, 무엇으로 옮겨야 하는지 문장으로 말한다.
+ * 그래서 이 함수는 옛 값에 대해서도 오류를 내며, 무엇으로 옮겨야 하는지 문장으로 말한다.
  */
 export declare function readRestartPolicy(raw: unknown, where: string): RestartPolicy;
-/** 이 값이 정책인가 — 던지지 않고 묻는 자리(화면·검사)를 위해. */
+/** 이 값이 정책인가 — 오류를 내지 않고 묻는 자리(화면·검사)를 위해. */
 export declare function isRestartPolicy(raw: unknown): raw is RestartPolicy;

package/dist-server/engine/restart-policy.js

@@ -19,7 +19,7 @@
  * ── 기본값을 두지 않는다 ────────────────────────────────────────────────────
  * 예전에는 미선언이 조용히 `sim-experiment`(=저널 초기화)로 떨어졌다. 그 관용은 값이 하나 어긋나는
  * 순간 **저널을 지우는 길**이 된다 — 개명 뒤 옛 값이 남아 있는 행을 그 길로 읽으면 재기동 한 번에
- * 이력이 사라진다. 그래서 모르는 값은 **던진다.** 부르는 쪽이 선언하게 만드는 것이 이 축의 요점이다.
+ * 이력이 사라진다. 그래서 모르는 값은 **오류를 낸다.** 부르는 쪽이 선언하게 만드는 것이 이 축의 요점이다.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RESTART_POLICIES = void 0;
@@ -27,11 +27,11 @@ exports.readRestartPolicy = readRestartPolicy;
 exports.isRestartPolicy = isRestartPolicy;
 exports.RESTART_POLICIES = ['resync', 'resume', 'reset'];
 /**
- * 저장된 값을 정책으로 읽는다 — **모르면 던진다**(기본값으로 메우지 않는다).
+ * 저장된 값을 정책으로 읽는다 — **모르면 오류를 낸다**(기본값으로 메우지 않는다).
  *
  * 옛 어휘(`mirror`·`sim-world`·`sim-experiment`)를 여기서 번역하지 않는다: 번역을 두면 옛 값이 살아남고,
  * 그 값이 다시 어딘가에 저장된다. 저장된 값은 **한 번 옮기고**(데이터 이관) 코드는 새 어휘만 안다.
- * 그래서 이 함수는 옛 값에 대해서도 던지며, 무엇으로 옮겨야 하는지 문장으로 말한다.
+ * 그래서 이 함수는 옛 값에 대해서도 오류를 내며, 무엇으로 옮겨야 하는지 문장으로 말한다.
  */
 function readRestartPolicy(raw, where) {
     const value = typeof raw === 'string' ? raw.trim() : '';
@@ -45,7 +45,7 @@ function readRestartPolicy(raw, where) {
     throw new Error(`${where}: restart policy ${value ? `"${value}"` : 'is missing'} — declare one of ${exports.RESTART_POLICIES.join(' | ')}. ` +
         'There is no default: an unspecified policy used to fall through to "reset", which erases the journal on the next reboot.');
 }
-/** 이 값이 정책인가 — 던지지 않고 묻는 자리(화면·검사)를 위해. */
+/** 이 값이 정책인가 — 오류를 내지 않고 묻는 자리(화면·검사)를 위해. */
 function isRestartPolicy(raw) {
     return typeof raw === 'string' && exports.RESTART_POLICIES.includes(raw);
 }

package/dist-server/engine/restart-policy.js.map

@@ -1 +1 @@
-{"version":3,"file":"restart-policy.js","sourceRoot":"","sources":["../../server/engine/restart-policy.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;;AAcH,8CAcC;AAGD,0CAEC;AA5BY,QAAA,gBAAgB,GAA6B,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAU,CAAA;AAEhG;;;;;;GAMG;AACH,SAAgB,iBAAiB,CAAC,GAAY,EAAE,KAAa;IAC3D,MAAM,KAAK,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;IACvD,IAAK,wBAAsC,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAsB,CAAA;IAC1F,MAAM,MAAM,GAAkC,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,gBAAgB,EAAE,OAAO,EAAE,CAAA;IACpH,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CACb,GAAG,KAAK,qBAAqB,KAAK,uDAAuD,MAAM,CAAC,KAAK,CAAC,IAAI;YACxG,4IAA4I,CAC/I,CAAA;IACH,CAAC;IACD,MAAM,IAAI,KAAK,CACb,GAAG,KAAK,oBAAoB,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,YAAY,qBAAqB,wBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI;QAClH,0HAA0H,CAC7H,CAAA;AACH,CAAC;AAED,2CAA2C;AAC3C,SAAgB,eAAe,CAAC,GAAY;IAC1C,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAK,wBAAsC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAA;AACzF,CAAC","sourcesContent":["/*\n * **재기동 정책** — 이 트윈은 다시 세워질 때 자기 과거를 어떻게 대하나.\n *\n * ── 왜 이 이름인가 (ADR-0029 · plans/simulator-as-source.md §2) ─────────────\n * 옛 이름은 `realityMode` 였고 값은 `mirror`·`sim-world`·`sim-experiment` 였다. 그 축은 「현실이 어디서\n * 오나」를 말하는 것처럼 보였지만, 코드가 그것으로 가른 것은 **재기동 거동 하나**였다. 그리고 「현실이\n * 어디서 오나」는 ADR-0029 가 **원본의 종류**로 옮긴 물음이다(`TwinReference.adapterType`) — 트윈은 한\n * 종류이고 언제나 원본을 반영한다.\n *\n * 그래서 이 축은 사라지지 않고 **트윈에 남아 이름을 바꿨다.** 남는 이유: 「자기 저널을 잇는가」는 원본의\n * 성질이 아니라 **트윈과 자기 과거의 관계**다. 같은 시뮬레이터 원본을 보는 두 트윈이 하나는 이어가고\n * 하나는 매번 처음부터 재현할 수 있다 — 원본은 그 둘을 구별하지 못한다.\n *\n *   resync — 외부 실물에서 다시 읽는다(원본이 진실이므로 우리 과거를 이어 붙이지 않는다).\n *   resume — 저널을 이어 세운다(이 트윈이 낳은 타임라인이 곧 사실이다).\n *   reset  — 저널을 비우고 씨앗부터 다시 돌린다(재현 가능한 실험).\n *\n * ── 기본값을 두지 않는다 ────────────────────────────────────────────────────\n * 예전에는 미선언이 조용히 `sim-experiment`(=저널 초기화)로 떨어졌다. 그 관용은 값이 하나 어긋나는\n * 순간 **저널을 지우는 길**이 된다 — 개명 뒤 옛 값이 남아 있는 행을 그 길로 읽으면 재기동 한 번에\n * 이력이 사라진다. 그래서 모르는 값은 **던진다.** 부르는 쪽이 선언하게 만드는 것이 이 축의 요점이다.\n */\n\n/** 재기동 정책 — 셋뿐이다. */\nexport type RestartPolicy = 'resync' | 'resume' | 'reset'\n\nexport const RESTART_POLICIES: readonly RestartPolicy[] = ['resync', 'resume', 'reset'] as const\n\n/**\n * 저장된 값을 정책으로 읽는다 — **모르면 던진다**(기본값으로 메우지 않는다).\n *\n * 옛 어휘(`mirror`·`sim-world`·`sim-experiment`)를 여기서 번역하지 않는다: 번역을 두면 옛 값이 살아남고,\n * 그 값이 다시 어딘가에 저장된다. 저장된 값은 **한 번 옮기고**(데이터 이관) 코드는 새 어휘만 안다.\n * 그래서 이 함수는 옛 값에 대해서도 던지며, 무엇으로 옮겨야 하는지 문장으로 말한다.\n */\nexport function readRestartPolicy(raw: unknown, where: string): RestartPolicy {\n  const value = typeof raw === 'string' ? raw.trim() : ''\n  if ((RESTART_POLICIES as readonly string[]).includes(value)) return value as RestartPolicy\n  const legacy: Record<string, RestartPolicy> = { mirror: 'resync', 'sim-world': 'resume', 'sim-experiment': 'reset' }\n  if (legacy[value]) {\n    throw new Error(\n      `${where}: restart policy \"${value}\" is the old vocabulary — move the stored value to \"${legacy[value]}\" ` +\n        '(ADR-0029 · plans/simulator-as-source.md §2). Nothing is translated at read time on purpose: a translation would keep the old value alive.'\n    )\n  }\n  throw new Error(\n    `${where}: restart policy ${value ? `\"${value}\"` : 'is missing'} — declare one of ${RESTART_POLICIES.join(' | ')}. ` +\n      'There is no default: an unspecified policy used to fall through to \"reset\", which erases the journal on the next reboot.'\n  )\n}\n\n/** 이 값이 정책인가 — 던지지 않고 묻는 자리(화면·검사)를 위해. */\nexport function isRestartPolicy(raw: unknown): raw is RestartPolicy {\n  return typeof raw === 'string' && (RESTART_POLICIES as readonly string[]).includes(raw)\n}\n"]}
+{"version":3,"file":"restart-policy.js","sourceRoot":"","sources":["../../server/engine/restart-policy.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;;AAcH,8CAcC;AAGD,0CAEC;AA5BY,QAAA,gBAAgB,GAA6B,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAU,CAAA;AAEhG;;;;;;GAMG;AACH,SAAgB,iBAAiB,CAAC,GAAY,EAAE,KAAa;IAC3D,MAAM,KAAK,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;IACvD,IAAK,wBAAsC,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAsB,CAAA;IAC1F,MAAM,MAAM,GAAkC,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,gBAAgB,EAAE,OAAO,EAAE,CAAA;IACpH,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CACb,GAAG,KAAK,qBAAqB,KAAK,uDAAuD,MAAM,CAAC,KAAK,CAAC,IAAI;YACxG,4IAA4I,CAC/I,CAAA;IACH,CAAC;IACD,MAAM,IAAI,KAAK,CACb,GAAG,KAAK,oBAAoB,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,YAAY,qBAAqB,wBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI;QAClH,0HAA0H,CAC7H,CAAA;AACH,CAAC;AAED,8CAA8C;AAC9C,SAAgB,eAAe,CAAC,GAAY;IAC1C,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAK,wBAAsC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAA;AACzF,CAAC","sourcesContent":["/*\n * **재기동 정책** — 이 트윈은 다시 세워질 때 자기 과거를 어떻게 대하나.\n *\n * ── 왜 이 이름인가 (ADR-0029 · plans/simulator-as-source.md §2) ─────────────\n * 옛 이름은 `realityMode` 였고 값은 `mirror`·`sim-world`·`sim-experiment` 였다. 그 축은 「현실이 어디서\n * 오나」를 말하는 것처럼 보였지만, 코드가 그것으로 가른 것은 **재기동 거동 하나**였다. 그리고 「현실이\n * 어디서 오나」는 ADR-0029 가 **원본의 종류**로 옮긴 물음이다(`TwinReference.adapterType`) — 트윈은 한\n * 종류이고 언제나 원본을 반영한다.\n *\n * 그래서 이 축은 사라지지 않고 **트윈에 남아 이름을 바꿨다.** 남는 이유: 「자기 저널을 잇는가」는 원본의\n * 성질이 아니라 **트윈과 자기 과거의 관계**다. 같은 시뮬레이터 원본을 보는 두 트윈이 하나는 이어가고\n * 하나는 매번 처음부터 재현할 수 있다 — 원본은 그 둘을 구별하지 못한다.\n *\n *   resync — 외부 실물에서 다시 읽는다(원본이 진실이므로 우리 과거를 이어 붙이지 않는다).\n *   resume — 저널을 이어 세운다(이 트윈이 낳은 타임라인이 곧 사실이다).\n *   reset  — 저널을 비우고 씨앗부터 다시 돌린다(재현 가능한 실험).\n *\n * ── 기본값을 두지 않는다 ────────────────────────────────────────────────────\n * 예전에는 미선언이 조용히 `sim-experiment`(=저널 초기화)로 떨어졌다. 그 관용은 값이 하나 어긋나는\n * 순간 **저널을 지우는 길**이 된다 — 개명 뒤 옛 값이 남아 있는 행을 그 길로 읽으면 재기동 한 번에\n * 이력이 사라진다. 그래서 모르는 값은 **오류를 낸다.** 부르는 쪽이 선언하게 만드는 것이 이 축의 요점이다.\n */\n\n/** 재기동 정책 — 셋뿐이다. */\nexport type RestartPolicy = 'resync' | 'resume' | 'reset'\n\nexport const RESTART_POLICIES: readonly RestartPolicy[] = ['resync', 'resume', 'reset'] as const\n\n/**\n * 저장된 값을 정책으로 읽는다 — **모르면 오류를 낸다**(기본값으로 메우지 않는다).\n *\n * 옛 어휘(`mirror`·`sim-world`·`sim-experiment`)를 여기서 번역하지 않는다: 번역을 두면 옛 값이 살아남고,\n * 그 값이 다시 어딘가에 저장된다. 저장된 값은 **한 번 옮기고**(데이터 이관) 코드는 새 어휘만 안다.\n * 그래서 이 함수는 옛 값에 대해서도 오류를 내며, 무엇으로 옮겨야 하는지 문장으로 말한다.\n */\nexport function readRestartPolicy(raw: unknown, where: string): RestartPolicy {\n  const value = typeof raw === 'string' ? raw.trim() : ''\n  if ((RESTART_POLICIES as readonly string[]).includes(value)) return value as RestartPolicy\n  const legacy: Record<string, RestartPolicy> = { mirror: 'resync', 'sim-world': 'resume', 'sim-experiment': 'reset' }\n  if (legacy[value]) {\n    throw new Error(\n      `${where}: restart policy \"${value}\" is the old vocabulary — move the stored value to \"${legacy[value]}\" ` +\n        '(ADR-0029 · plans/simulator-as-source.md §2). Nothing is translated at read time on purpose: a translation would keep the old value alive.'\n    )\n  }\n  throw new Error(\n    `${where}: restart policy ${value ? `\"${value}\"` : 'is missing'} — declare one of ${RESTART_POLICIES.join(' | ')}. ` +\n      'There is no default: an unspecified policy used to fall through to \"reset\", which erases the journal on the next reboot.'\n  )\n}\n\n/** 이 값이 정책인가 — 오류를 내지 않고 묻는 자리(화면·검사)를 위해. */\nexport function isRestartPolicy(raw: unknown): raw is RestartPolicy {\n  return typeof raw === 'string' && (RESTART_POLICIES as readonly string[]).includes(raw)\n}\n"]}

package/dist-server/engine/runtime-key.js

@@ -26,7 +26,7 @@
  * `${domainId}:${instanceId}` — 이 저장소가 이미 쓰는 모양이다(`structureRevCache`·`measuredCache`).
  * 새 모양을 만들지 않는다. 파싱은 **첫 구분자**에서 자르므로 `instanceId` 에 `:` 가 들어 있어도
  * 안전하다(레퍼런스 소스 이름에 들어갈 수 있다). 대신 `domainId` 에 구분자가 있으면 키가 모호해지므로
- * **그때는 던진다** — 조용히 잘못된 키를 만들면 그게 곧 이 결함의 재발이다.
+ * **그때는 오류를 낸다** — 조용히 잘못된 키를 만들면 그게 곧 이 결함의 재발이다.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RUNTIME_KEY_SEP = void 0;

package/dist-server/engine/runtime-key.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-key.js","sourceRoot":"","sources":["../../server/engine/runtime-key.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;;;AAUH,gCAOC;AAGD,0CAIC;AAGD,gCAEC;AA3BD,kDAAkD;AACrC,QAAA,eAAe,GAAG,GAAG,CAAA;AAElC;;;;GAIG;AACH,SAAgB,UAAU,CAAC,QAAgB,EAAE,UAAkB;IAC7D,IAAI,CAAC,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,8EAA8E,CAAC,CAAA;IAC9G,IAAI,CAAC,UAAU;QAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAA;IACtE,IAAI,QAAQ,CAAC,QAAQ,CAAC,uBAAe,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,0CAA0C,uBAAe,kCAAkC,CAAC,CAAA;IAC9G,CAAC;IACD,OAAO,GAAG,QAAQ,GAAG,uBAAe,GAAG,UAAU,EAAE,CAAA;AACrD,CAAC;AAED,iDAAiD;AACjD,SAAgB,eAAe,CAAC,GAAW;IACzC,MAAM,EAAE,GAAG,GAAG,CAAC,OAAO,CAAC,uBAAe,CAAC,CAAA;IACvC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,GAAG,wBAAwB,CAAC,CAAA;IACvG,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,UAAU,EAAE,GAAG,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAA;AACtE,CAAC;AAED,iDAAiD;AACjD,SAAgB,UAAU,CAAC,GAAW,EAAE,QAAgB;IACtD,OAAO,CAAC,CAAC,QAAQ,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,QAAQ,GAAG,uBAAe,EAAE,CAAC,CAAA;AACtE,CAAC","sourcesContent":["/*\n * 런타임 레지스트리 키 — **트윈의 정체성은 `(도메인, 인스턴스 id)` 다.** 순수.\n *\n * ── 왜 있나 (2026-08-06 테넌트 격리 전수 확인) ───────────────────────────────\n * `TwinEngine.instances` 와 `recovered` 가 **`instanceId` 하나로** 키를 잡고 있었다. 그런데 DB 유일성은\n * `[domain, instanceId]` 이고(`TwinInstance` 인덱스) 트윈의 정체성도 그쪽이다. 즉 런타임 맵만 **전역\n * 이름 공간**이었다.\n *\n * **충돌은 이론이 아니다.** 레퍼런스 경로가 `instanceId` 로 **레퍼런스 소스 이름**을 쓴다\n * (`sap-ewm-1710`). 벤더 시스템 이름은 테넌트가 **공유하는 어휘**라, 두 테넌트가 같은 시스템에\n * 연결하면 같은 id 가 된다 — 드문 사고가 아니라 예상되는 경우다.\n *\n * 그래서 무엇이 어긋났나:\n *  · `startLive` 의 조기 반환이 A 의 런타임을 B 에게 돌려주고 `ingestLive` 는 도메인을 확인하지 않아\n *    **B 의 라이브 이벤트가 A 의 커널에 적용**될 수 있었다.\n *  · `recovered` 가 겹치면 웜스타트 씨앗이 **남의 스냅샷**이 되어 재고가 섞인다.\n *  · `start`/`stop` 이 남의 런타임을 집으므로 B 는 \"기동됨\" 을 받고도 이후 전부 거부됐다.\n *\n * 이 부류는 **이미 한 번 물었다** — `twin-lifecycle-mutation.ts` 주석이 증언한다: \"과거엔\n * `Object.keys(TwinEngine.instances)` 로 전역 반환 → 다른 도메인 트윈이 새던 버그.\" 그 자리만 고쳤다.\n * 그래서 이번에는 가드를 더 붙이지 않고 **키를 고친다** — 저수준 메서드가 `domainId` 를 받게 되는 것이\n * 요점이다. \"누구의 트윈인가\" 를 말하지 않고는 만질 수 없다.\n *\n * ── 구분자 규약 ─────────────────────────────────────────────────────────────\n * `${domainId}:${instanceId}` — 이 저장소가 이미 쓰는 모양이다(`structureRevCache`·`measuredCache`).\n * 새 모양을 만들지 않는다. 파싱은 **첫 구분자**에서 자르므로 `instanceId` 에 `:` 가 들어 있어도\n * 안전하다(레퍼런스 소스 이름에 들어갈 수 있다). 대신 `domainId` 에 구분자가 있으면 키가 모호해지므로\n * **그때는 던진다** — 조용히 잘못된 키를 만들면 그게 곧 이 결함의 재발이다.\n */\n\n/** 도메인과 인스턴스 id 를 잇는 문자 — 저장소의 기존 캐시 키와 같은 모양. */\nexport const RUNTIME_KEY_SEP = ':'\n\n/**\n * 런타임 레지스트리 키.\n *\n * @throws 도메인 id 가 비었거나 구분자를 담고 있으면(키가 모호해진다). 인스턴스 id 가 비었으면.\n */\nexport function runtimeKey(domainId: string, instanceId: string): string {\n  if (!domainId) throw new Error('runtimeKey: domainId is required — a twin runtime always belongs to a tenant')\n  if (!instanceId) throw new Error('runtimeKey: instanceId is required')\n  if (domainId.includes(RUNTIME_KEY_SEP)) {\n    throw new Error(`runtimeKey: domainId must not contain \"${RUNTIME_KEY_SEP}\" (would make the key ambiguous)`)\n  }\n  return `${domainId}${RUNTIME_KEY_SEP}${instanceId}`\n}\n\n/** 키를 되돌린다 — 첫 구분자에서 자른다(인스턴스 id 안의 구분자는 보존). */\nexport function parseRuntimeKey(key: string): { domainId: string; instanceId: string } {\n  const at = key.indexOf(RUNTIME_KEY_SEP)\n  if (at <= 0 || at === key.length - 1) throw new Error(`parseRuntimeKey: \"${key}\" is not a runtime key`)\n  return { domainId: key.slice(0, at), instanceId: key.slice(at + 1) }\n}\n\n/** 이 키가 이 테넌트의 것인가 — 레지스트리를 조회할 때 도메인으로 걸러낸다. */\nexport function isOfDomain(key: string, domainId: string): boolean {\n  return !!domainId && key.startsWith(`${domainId}${RUNTIME_KEY_SEP}`)\n}\n"]}
+{"version":3,"file":"runtime-key.js","sourceRoot":"","sources":["../../server/engine/runtime-key.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;;;AAUH,gCAOC;AAGD,0CAIC;AAGD,gCAEC;AA3BD,kDAAkD;AACrC,QAAA,eAAe,GAAG,GAAG,CAAA;AAElC;;;;GAIG;AACH,SAAgB,UAAU,CAAC,QAAgB,EAAE,UAAkB;IAC7D,IAAI,CAAC,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,8EAA8E,CAAC,CAAA;IAC9G,IAAI,CAAC,UAAU;QAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAA;IACtE,IAAI,QAAQ,CAAC,QAAQ,CAAC,uBAAe,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,0CAA0C,uBAAe,kCAAkC,CAAC,CAAA;IAC9G,CAAC;IACD,OAAO,GAAG,QAAQ,GAAG,uBAAe,GAAG,UAAU,EAAE,CAAA;AACrD,CAAC;AAED,iDAAiD;AACjD,SAAgB,eAAe,CAAC,GAAW;IACzC,MAAM,EAAE,GAAG,GAAG,CAAC,OAAO,CAAC,uBAAe,CAAC,CAAA;IACvC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,GAAG,wBAAwB,CAAC,CAAA;IACvG,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,UAAU,EAAE,GAAG,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAA;AACtE,CAAC;AAED,iDAAiD;AACjD,SAAgB,UAAU,CAAC,GAAW,EAAE,QAAgB;IACtD,OAAO,CAAC,CAAC,QAAQ,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,QAAQ,GAAG,uBAAe,EAAE,CAAC,CAAA;AACtE,CAAC","sourcesContent":["/*\n * 런타임 레지스트리 키 — **트윈의 정체성은 `(도메인, 인스턴스 id)` 다.** 순수.\n *\n * ── 왜 있나 (2026-08-06 테넌트 격리 전수 확인) ───────────────────────────────\n * `TwinEngine.instances` 와 `recovered` 가 **`instanceId` 하나로** 키를 잡고 있었다. 그런데 DB 유일성은\n * `[domain, instanceId]` 이고(`TwinInstance` 인덱스) 트윈의 정체성도 그쪽이다. 즉 런타임 맵만 **전역\n * 이름 공간**이었다.\n *\n * **충돌은 이론이 아니다.** 레퍼런스 경로가 `instanceId` 로 **레퍼런스 소스 이름**을 쓴다\n * (`sap-ewm-1710`). 벤더 시스템 이름은 테넌트가 **공유하는 어휘**라, 두 테넌트가 같은 시스템에\n * 연결하면 같은 id 가 된다 — 드문 사고가 아니라 예상되는 경우다.\n *\n * 그래서 무엇이 어긋났나:\n *  · `startLive` 의 조기 반환이 A 의 런타임을 B 에게 돌려주고 `ingestLive` 는 도메인을 확인하지 않아\n *    **B 의 라이브 이벤트가 A 의 커널에 적용**될 수 있었다.\n *  · `recovered` 가 겹치면 웜스타트 씨앗이 **남의 스냅샷**이 되어 재고가 섞인다.\n *  · `start`/`stop` 이 남의 런타임을 집으므로 B 는 \"기동됨\" 을 받고도 이후 전부 거부됐다.\n *\n * 이 부류는 **이미 한 번 물었다** — `twin-lifecycle-mutation.ts` 주석이 증언한다: \"과거엔\n * `Object.keys(TwinEngine.instances)` 로 전역 반환 → 다른 도메인 트윈이 새던 버그.\" 그 자리만 고쳤다.\n * 그래서 이번에는 가드를 더 붙이지 않고 **키를 고친다** — 저수준 메서드가 `domainId` 를 받게 되는 것이\n * 요점이다. \"누구의 트윈인가\" 를 말하지 않고는 만질 수 없다.\n *\n * ── 구분자 규약 ─────────────────────────────────────────────────────────────\n * `${domainId}:${instanceId}` — 이 저장소가 이미 쓰는 모양이다(`structureRevCache`·`measuredCache`).\n * 새 모양을 만들지 않는다. 파싱은 **첫 구분자**에서 자르므로 `instanceId` 에 `:` 가 들어 있어도\n * 안전하다(레퍼런스 소스 이름에 들어갈 수 있다). 대신 `domainId` 에 구분자가 있으면 키가 모호해지므로\n * **그때는 오류를 낸다** — 조용히 잘못된 키를 만들면 그게 곧 이 결함의 재발이다.\n */\n\n/** 도메인과 인스턴스 id 를 잇는 문자 — 저장소의 기존 캐시 키와 같은 모양. */\nexport const RUNTIME_KEY_SEP = ':'\n\n/**\n * 런타임 레지스트리 키.\n *\n * @throws 도메인 id 가 비었거나 구분자를 담고 있으면(키가 모호해진다). 인스턴스 id 가 비었으면.\n */\nexport function runtimeKey(domainId: string, instanceId: string): string {\n  if (!domainId) throw new Error('runtimeKey: domainId is required — a twin runtime always belongs to a tenant')\n  if (!instanceId) throw new Error('runtimeKey: instanceId is required')\n  if (domainId.includes(RUNTIME_KEY_SEP)) {\n    throw new Error(`runtimeKey: domainId must not contain \"${RUNTIME_KEY_SEP}\" (would make the key ambiguous)`)\n  }\n  return `${domainId}${RUNTIME_KEY_SEP}${instanceId}`\n}\n\n/** 키를 되돌린다 — 첫 구분자에서 자른다(인스턴스 id 안의 구분자는 보존). */\nexport function parseRuntimeKey(key: string): { domainId: string; instanceId: string } {\n  const at = key.indexOf(RUNTIME_KEY_SEP)\n  if (at <= 0 || at === key.length - 1) throw new Error(`parseRuntimeKey: \"${key}\" is not a runtime key`)\n  return { domainId: key.slice(0, at), instanceId: key.slice(at + 1) }\n}\n\n/** 이 키가 이 테넌트의 것인가 — 레지스트리를 조회할 때 도메인으로 걸러낸다. */\nexport function isOfDomain(key: string, domainId: string): boolean {\n  return !!domainId && key.startsWith(`${domainId}${RUNTIME_KEY_SEP}`)\n}\n"]}