@things-factory/headless-twin 10.0.9 → 10.0.10

package/dist-server/engine/kpi-target.d.ts

@@ -39,6 +39,23 @@ export declare const TWIN_METRIC: {
         readonly unit: "ms";
         readonly of: (k: KpiResult) => number;
     };
+    readonly 'energy.kWh': {
+        readonly direction: "lower";
+        readonly unit: "kWh";
+        readonly of: (k: KpiResult) => number;
+    };
+    /** 최대수요 — 계약 상한을 목표로 적는 자리다(요금의 기본요금 부분이 여기서 정해진다). */
+    readonly 'energy.peakKW': {
+        readonly direction: "lower";
+        readonly unit: "kW";
+        readonly of: (k: KpiResult) => number;
+    };
+    /** 원단위 — 완료 오더당 kWh. 답할 수 없으면(`null`) 판정하지 않는다. */
+    readonly 'energy.intensity': {
+        readonly direction: "lower";
+        readonly unit: "kWh/order";
+        readonly of: (k: KpiResult) => number;
+    };
     /** 자원 점유 — 개별 자원이 아니라 **창 전체의 평균 비율**(자원별은 관점 축의 일이다). */
     readonly 'utilization.ratio': {
         readonly direction: "higher";

package/dist-server/engine/kpi-target.js

@@ -19,7 +19,7 @@ const statOf = (s, pick) => s.count > 0 ? pick(s) : undefined;
  * 좋다 — 이것을 입력으로 받으면 반대로 적은 목표가 만들어지고, 그 뒤 판정이 전부 뒤집힌다.
  */
 exports.TWIN_METRIC = {
-    /* 기록이 없는 구간은 처리량 0 이 아니라 **모름**이다 — `eventsInWindow` 가 그것을 가른다.
+    /* 기록이 없는 구간은 처리량 0 이 아니라 **모름**이다 — `eventsInWindow` 가 그것을 구분한다.
        0 으로 판정하면 "측정 못 한 구간" 이 "일을 안 한 구간" 으로 보고된다. */
     'throughput.tasks': { direction: 'higher', unit: 'count', of: (k) => measured(k, k.throughput.tasks) },
     'throughput.orders': { direction: 'higher', unit: 'count', of: (k) => measured(k, k.throughput.orders) },
@@ -30,6 +30,28 @@ exports.TWIN_METRIC = {
     'leadTime.p90Ms': { direction: 'lower', unit: 'ms', of: (k) => statOf(k.leadTime, d => d.p90Ms) },
     'workTime.p50Ms': { direction: 'lower', unit: 'ms', of: (k) => statOf(k.workTime, d => d.p50Ms) },
     'waitTime.p50Ms': { direction: 'lower', unit: 'ms', of: (k) => statOf(k.waitTime, d => d.p50Ms) },
+    /*
+     * ── 에너지 (2026-08-17) ────────────────────────────────────────────────────
+     *
+     * 값은 폴드가 이미 내고 있었는데 **목표를 걸 수 있는 지표 목록에 없었다.** 그래서 화면은 「이번 창에
+     * 1,240kWh」를 보여 주면서도 그것이 좋은지 나쁜지는 말하지 못했다 — 에너지야말로 계약이라는 딱딱한
+     * 기준선이 있는 영역인데도 그랬다.
+     *
+     * 셋 다 방향은 **낮을수록 좋다**로 못 박는다. 「많이 쓸수록 좋다」는 에너지 목표는 없다. 산출이 늘어
+     * 전력량이 느는 경우는 원단위(`energy.intensity`)가 답할 자리이지, 방향을 뒤집을 이유가 아니다.
+     *
+     * 값이 없는 창(에너지 트윈이 아니거나 계측이 끊긴 창)은 `undefined` 로 남긴다 — 0 으로 읽으면
+     * 시간 지표에서 이미 겪은 그 결함이 그대로 재현된다(안 쓴 것이 아니라 못 잰 것인데 만점이 된다).
+     */
+    'energy.kWh': { direction: 'lower', unit: 'kWh', of: (k) => k.energy?.kWh },
+    /** 최대수요 — 계약 상한을 목표로 적는 자리다(요금의 기본요금 부분이 여기서 정해진다). */
+    'energy.peakKW': { direction: 'lower', unit: 'kW', of: (k) => k.energy?.peakKW },
+    /** 원단위 — 완료 오더당 kWh. 답할 수 없으면(`null`) 판정하지 않는다. */
+    'energy.intensity': {
+        direction: 'lower',
+        unit: 'kWh/order',
+        of: (k) => (typeof k.energy?.intensity?.value === 'number' ? k.energy.intensity.value : undefined)
+    },
     /** 자원 점유 — 개별 자원이 아니라 **창 전체의 평균 비율**(자원별은 관점 축의 일이다). */
     'utilization.ratio': {
         direction: 'higher',
@@ -128,7 +150,7 @@ function judgeTargets(kpi, targets) {
     }
     return out;
 }
-/** 판정 산수 한 곳 — 전체 판정과 축 판정이 **같은 규칙**을 쓴다(두 벌이면 갈라진다). */
+/** 판정 산수 한 곳 — 전체 판정과 축 판정이 **같은 규칙**을 쓴다(두 벌이면 어긋난다). */
 function verdictOf(metric, actual, target, direction) {
     const met = direction === 'higher' ? actual >= target : actual <= target;
     const ratio = direction === 'higher' ? (target > 0 ? actual / target : Number.NaN) : actual > 0 ? target / actual : Number.NaN;

package/dist-server/engine/kpi-target.js.map

@@ -1 +1 @@
-{"version":3,"file":"kpi-target.js","sourceRoot":"","sources":["../../server/engine/kpi-target.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * 성과 목표 — **숫자를 판단으로 바꾸는 층.**\n *\n * ── 왜 필요한가 ─────────────────────────────────────────────────────────────\n * 화면과 AI 는 \"처리량 345건 · 작업시간 29초\" 를 정확히 말한다. 그런데 **그것이 좋은지 나쁜지는 말할 수\n * 없다.** 판단 근거가 앞 구간 비교뿐이라 \"어제보다 나아졌다\" 까지가 한계이고, 어제도 나빴으면 그 말은\n * 쓸모가 없다. 목표가 붙는 순간 같은 숫자가 **정보에서 판단으로** 바뀐다.\n *\n * ── 층을 섞지 않는다 ────────────────────────────────────────────────────────\n * 폴드(`kpi-fold`)는 **사실만** 낸다 — 목표를 모른다. 목표를 아는 순간 \"사실을 세는 규칙\" 과 \"잘했나\n * 판정하는 규칙\" 이 한 함수에 섞이고, 목표가 바뀔 때마다 사실 계산을 건드리게 된다. 그래서 판정은\n * 여기, **순수 함수**로 따로 둔다(폴드처럼 테스트가 값싸다).\n *\n * ── 목표의 집 (사용자 결정 2026-08-02) ──────────────────────────────────────\n * **트윈은 운영 목표를 갖고, `@things-factory/kpi` 는 경영 목표를 갖는다.** 경계:\n *\n *   트윈(TwinTarget)          이 구간·이 교대·이 공간의 **즉시 판단**. 현장 관리자가 트윈 화면에서 고친다.\n *                             값은 저널 폴드에서 **그때그때 계산**된다(저장된 값을 읽지 않는다).\n *   packages/kpi              **기간 평가**(조직·분기·점수·가중치·알림). 값은 저장돼 있어야 한다.\n *\n * 이 경계를 지키는 규칙 하나: **트윈은 목표를 복제하지 않는다.** 경영 목표가 필요하면 트윈의 사실을\n * 내보내 그쪽이 소비하고, 그쪽 목표를 여기로 베껴 오지 않는다 — 베끼는 순간 두 개의 진실이 된다.\n */\n/*\n * ── 운영 임계(커널 attention)와의 경계 ─────────────────────────────────────\n *\n * **attention 은 개체 하나의 지금 상태**다 — 앵커(설비·자리·오더)와 할 수 있는 조치를 갖는다.\n * **target(여기)은 구간의 집계**다 — 앵커도 조치도 없고 추세를 판단한다.\n *\n * 그래서 창 단위 집계 판정을 attention 으로 넣지 않는다: \"가동률 저하\"(창 평균) attention 을 만들면\n * `utilization.ratio` 목표와 **같은 사실을 두 층이 다른 임계로 판정**하게 된다.\n * (design/map/performance.md §5.0-4 — 현재 다섯 attention 과 이 어휘는 겹치지 않는다.)\n */\nimport type { DurationStats, KpiResult } from './kpi-fold.js'\n\n/** 측정된 기록이 있을 때만 값으로 인정한다 — 없으면 모름(0 이 아니다). */\nconst measured = (k: KpiResult, v: number): number | undefined => (k.eventsInWindow > 0 ? v : undefined)\n\n/** 분위수는 표본이 있을 때만 값이다 — `count === 0` 의 `p50Ms: 0` 은 \"0 밀리초\" 가 아니라 \"없음\" 이다. */\nconst statOf = (s: DurationStats, pick: (d: DurationStats) => number): number | undefined =>\n  s.count > 0 ? pick(s) : undefined\n\n/**\n * 지표 어휘 — **이름을 한 곳에서 정한다.**\n *\n * 목표와 사실이 서로 다른 이름을 쓰면 그 사이에 매핑 표가 생기고, 그 표가 곧 방언이 된다. 그래서\n * 목표가 가리킬 수 있는 지표는 여기 열거된 것뿐이고, 값을 꺼내는 방법도 여기 함께 있다.\n *\n * **`direction` 은 지표의 성질이지 사용자의 선택이 아니다.** 처리량은 높을수록 좋고 대기시간은 낮을수록\n * 좋다 — 이것을 입력으로 받으면 반대로 적은 목표가 만들어지고, 그 뒤 판정이 전부 뒤집힌다.\n */\nexport const TWIN_METRIC = {\n  /* 기록이 없는 구간은 처리량 0 이 아니라 **모름**이다 — `eventsInWindow` 가 그것을 가른다.\n     0 으로 판정하면 \"측정 못 한 구간\" 이 \"일을 안 한 구간\" 으로 보고된다. */\n  'throughput.tasks': { direction: 'higher', unit: 'count', of: (k: KpiResult) => measured(k, k.throughput.tasks) },\n  'throughput.orders': { direction: 'higher', unit: 'count', of: (k: KpiResult) => measured(k, k.throughput.orders) },\n  /* 소요시간 분위수는 `count === 0` 이면 **0 이 아니라 없다.** 이것을 0 으로 읽으면 시간 지표는\n     \"낮을수록 좋다\" 라서 **일이 없던 구간이 목표를 완벽히 달성한 것으로** 보고된다 — 미달을 놓치는\n     것보다 나쁘다(고칠 곳이 있는데 잘하고 있다고 말한다). 테스트가 이것을 잡았다. */\n  'leadTime.p50Ms': { direction: 'lower', unit: 'ms', of: (k: KpiResult) => statOf(k.leadTime, d => d.p50Ms) },\n  'leadTime.p90Ms': { direction: 'lower', unit: 'ms', of: (k: KpiResult) => statOf(k.leadTime, d => d.p90Ms) },\n  'workTime.p50Ms': { direction: 'lower', unit: 'ms', of: (k: KpiResult) => statOf(k.workTime, d => d.p50Ms) },\n  'waitTime.p50Ms': { direction: 'lower', unit: 'ms', of: (k: KpiResult) => statOf(k.waitTime, d => d.p50Ms) },\n  /** 자원 점유 — 개별 자원이 아니라 **창 전체의 평균 비율**(자원별은 관점 축의 일이다). */\n  'utilization.ratio': {\n    direction: 'higher',\n    unit: 'ratio',\n    of: (k: KpiResult) =>\n      k.utilization.length ? k.utilization.reduce((s, u) => s + u.ratio, 0) / k.utilization.length : undefined\n  }\n} as const\n\nexport type TwinMetricId = keyof typeof TWIN_METRIC\nexport const isTwinMetric = (id: string): id is TwinMetricId => id in TWIN_METRIC\n\n/**\n * 저장된 목표 행에서 **이 범위에 걸린 목표**를 고른다 — 좁은 선언이 넓은 선언을 덮는다.\n *\n * **왜 순수 함수인가**: 이 규칙(공간 목표 위에 인스턴스 목표를 얹는다)은 지금까지 DB 접근 뒤에 숨어\n * 있어서 **화면을 눌러 봐야만** 확인할 수 있었다. 그런데 이 프로젝트는 로그인 뒤 화면을 자동으로\n * 검증할 방법이 없어, 실제로 여러 기능이 \"실화면 미검증\" 으로 쌓였다. 규칙을 밖으로 빼면 테스트가\n * 값싸진다 — 조회는 행을 가져오기만 하고, **판단은 여기서** 한다.\n */\n/**\n * 축 목표까지 담은 목록 — 전체 목표와 **축의 한 값**에 걸린 목표를 함께 든다.\n *\n * 축 목표는 전체 목표를 **덮지 않는다.** 다른 질문이기 때문이다: \"현장 전체가 100건\" 과\n * \"용접 구역이 30건\" 은 동시에 참일 수 있다. 덮게 만들면 축 하나에 목표를 거는 순간 전체 판정이\n * 사라져 사용자가 \"목표를 지웠나?\" 를 묻게 된다.\n */\nexport interface ScopedTargets {\n  /** 창 전체에 걸린 목표. */\n  overall: TwinTargetSpec[]\n  /** 축 → (그 축의 값 → 목표들). 요청한 축만 채운다. */\n  byAxisKey: Record<string, TwinTargetSpec[]>\n}\n\n/**\n * 축의 각 값에 대해 목표 대비 판정 — **그룹 항목에 그대로 붙일 형태.**\n *\n * 그룹의 지표는 전체보다 좁다(주문 수·자원 점유는 축 단위로 뜻이 다르거나 없다). 없는 지표에 목표가\n * 걸려 있으면 **판정하지 않는다** — 여기서 0 으로 읽으면 시간 지표가 \"완벽 달성\" 으로 뒤집힌다\n * (전체 판정에서 이미 겪은 결함이다).\n */\nexport function judgeGroupTargets(\n  group: { key: string; tasks: number; leadTime: { count: number; p50Ms: number }; workTime: { count: number; p50Ms: number }; waitTime: { count: number; p50Ms: number } },\n  targets: readonly TwinTargetSpec[] | undefined\n): TargetVerdict[] {\n  const value = (metric: TwinMetricId): number | undefined => {\n    switch (metric) {\n      case 'throughput.tasks':\n        return group.tasks\n      case 'leadTime.p50Ms':\n        return group.leadTime.count > 0 ? group.leadTime.p50Ms : undefined\n      case 'workTime.p50Ms':\n        return group.workTime.count > 0 ? group.workTime.p50Ms : undefined\n      case 'waitTime.p50Ms':\n        return group.waitTime.count > 0 ? group.waitTime.p50Ms : undefined\n      default:\n        return undefined // 축 단위로 뜻이 없는 지표(주문 수·자원 점유) — 지어내지 않는다\n    }\n  }\n  const out: TargetVerdict[] = []\n  for (const t of targets ?? []) {\n    const spec = TWIN_METRIC[t.metric]\n    const actual = value(t.metric)\n    if (!spec || typeof actual !== 'number' || !Number.isFinite(actual) || !Number.isFinite(t.target)) continue\n    out.push(verdictOf(t.metric, actual, t.target, spec.direction))\n  }\n  return out\n}\n\nexport function mergeTargets(\n  rows: readonly TargetRow[],\n  scope: { spaceId?: string; instanceIds: readonly string[]; axis?: string }\n): TwinTargetSpec[] {\n  return scopedTargets(rows, scope).overall\n}\n\n/** 저장된 목표 행 — 판단에 필요한 것만(엔티티 전체를 요구하지 않는다: 테스트가 값싸진다). */\nexport interface TargetRow {\n  metric: string\n  target: number\n  spaceId?: string | null\n  instanceId?: string | null\n  axis?: string | null\n  axisKey?: string | null\n}\n\n/** 전체 목표와 축 목표를 함께 고른다 — 좁은 선언(인스턴스)이 넓은 선언(공간)을 덮는 규칙은 양쪽 같다. */\nexport function scopedTargets(\n  rows: readonly TargetRow[],\n  scope: { spaceId?: string; instanceIds: readonly string[]; axis?: string }\n): ScopedTargets {\n  /* 같은 자리(지표 또는 축값+지표)에 공간·인스턴스 목표가 함께 있으면 인스턴스가 이긴다. */\n  const pick = new Map<string, { target: number; fromInstance: boolean; axisKey?: string; metric: TwinMetricId }>()\n  for (const r of rows) {\n    if (!isTwinMetric(r.metric) || typeof r.target !== 'number' || !Number.isFinite(r.target)) continue\n    const inSpace = !!scope.spaceId && r.spaceId === scope.spaceId\n    const inInstance = !!r.instanceId && scope.instanceIds.includes(r.instanceId)\n    if (!inSpace && !inInstance) continue\n    if (r.axis) {\n      if (!scope.axis || r.axis !== scope.axis || !r.axisKey) continue // 지금 보는 축만\n    }\n    const slot = `${r.axis ?? ''}\\u0000${r.axisKey ?? ''}\\u0000${r.metric}`\n    const prev = pick.get(slot)\n    if (prev?.fromInstance && !inInstance) continue // 인스턴스 선언을 공간 선언이 덮지 않는다\n    pick.set(slot, { target: r.target, fromInstance: inInstance, axisKey: r.axisKey ?? undefined, metric: r.metric })\n  }\n  const overall: TwinTargetSpec[] = []\n  const byAxisKey: Record<string, TwinTargetSpec[]> = {}\n  for (const [slot, v] of pick) {\n    const spec = { metric: v.metric, target: v.target }\n    if (slot.startsWith('\\u0000')) overall.push(spec)\n    else (byAxisKey[v.axisKey as string] ??= []).push(spec)\n  }\n  return { overall, byAxisKey }\n}\n\n/** 목표 하나 — 어느 지표를, 얼마로. 방향은 지표가 안다(§TWIN_METRIC). */\nexport interface TwinTargetSpec {\n  metric: TwinMetricId\n  target: number\n}\n\nexport interface TargetVerdict {\n  metric: TwinMetricId\n  /** 이 구간의 실제 값. */\n  actual: number\n  target: number\n  direction: 'higher' | 'lower'\n  /** 목표를 만족했나. */\n  met: boolean\n  /**\n   * 목표 대비 비율 — **항상 \"1 이상이면 좋다\"** 로 정규화한다(방향이 다른 지표를 한 화면에서 비교할 수\n   * 있게). 처리량은 `actual/target`, 시간은 `target/actual`.\n   */\n  ratio: number\n}\n\n/**\n * 목표 대비 판정 — **목표가 없는 지표는 판정하지 않는다.**\n *\n * 값이 없는 지표(그 구간에 기록이 없어 `undefined`)도 판정하지 않는다. 없는 것을 0 으로 놓으면\n * \"목표 크게 미달\" 이라는 **없는 사실**이 만들어지고, 사용자는 멈춘 적 없는 라인을 고치러 간다.\n * 목표를 0 으로 준 경우도 비율을 내지 않는다(0 으로 나누지 않는다) — 만족 여부만 답한다.\n */\nexport function judgeTargets(kpi: KpiResult, targets: readonly TwinTargetSpec[] | undefined): TargetVerdict[] {\n  const out: TargetVerdict[] = []\n  for (const t of targets ?? []) {\n    const spec = TWIN_METRIC[t.metric]\n    if (!spec) continue // 모르는 지표 이름 — 짐작해 매핑하지 않는다\n    const actual = spec.of(kpi)\n    if (typeof actual !== 'number' || !Number.isFinite(actual)) continue // 값이 없다 ≠ 값이 0\n    if (!Number.isFinite(t.target)) continue\n    out.push(verdictOf(t.metric, actual, t.target, spec.direction))\n  }\n  return out\n}\n\n/** 판정 산수 한 곳 — 전체 판정과 축 판정이 **같은 규칙**을 쓴다(두 벌이면 갈라진다). */\nfunction verdictOf(metric: TwinMetricId, actual: number, target: number, direction: 'higher' | 'lower'): TargetVerdict {\n  const met = direction === 'higher' ? actual >= target : actual <= target\n  const ratio = direction === 'higher' ? (target > 0 ? actual / target : Number.NaN) : actual > 0 ? target / actual : Number.NaN\n  return { metric, actual, target, direction, met, ratio }\n}\n"]}
+{"version":3,"file":"kpi-target.js","sourceRoot":"","sources":["../../server/engine/kpi-target.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * 성과 목표 — **숫자를 판단으로 바꾸는 층.**\n *\n * ── 왜 필요한가 ─────────────────────────────────────────────────────────────\n * 화면과 AI 는 \"처리량 345건 · 작업시간 29초\" 를 정확히 말한다. 그런데 **그것이 좋은지 나쁜지는 말할 수\n * 없다.** 판단 근거가 앞 구간 비교뿐이라 \"어제보다 나아졌다\" 까지가 한계이고, 어제도 나빴으면 그 말은\n * 쓸모가 없다. 목표가 붙는 순간 같은 숫자가 **정보에서 판단으로** 바뀐다.\n *\n * ── 층을 섞지 않는다 ────────────────────────────────────────────────────────\n * 폴드(`kpi-fold`)는 **사실만** 낸다 — 목표를 모른다. 목표를 아는 순간 \"사실을 세는 규칙\" 과 \"잘했나\n * 판정하는 규칙\" 이 한 함수에 섞이고, 목표가 바뀔 때마다 사실 계산을 건드리게 된다. 그래서 판정은\n * 여기, **순수 함수**로 따로 둔다(폴드처럼 테스트가 값싸다).\n *\n * ── 목표의 집 (사용자 결정 2026-08-02) ──────────────────────────────────────\n * **트윈은 운영 목표를 갖고, `@things-factory/kpi` 는 경영 목표를 갖는다.** 경계:\n *\n *   트윈(TwinTarget)          이 구간·이 교대·이 공간의 **즉시 판단**. 현장 관리자가 트윈 화면에서 고친다.\n *                             값은 저널 폴드에서 **그때그때 계산**된다(저장된 값을 읽지 않는다).\n *   packages/kpi              **기간 평가**(조직·분기·점수·가중치·알림). 값은 저장돼 있어야 한다.\n *\n * 이 경계를 지키는 규칙 하나: **트윈은 목표를 복제하지 않는다.** 경영 목표가 필요하면 트윈의 사실을\n * 내보내 그쪽이 소비하고, 그쪽 목표를 여기로 베껴 오지 않는다 — 베끼는 순간 두 개의 진실이 된다.\n */\n/*\n * ── 운영 임계(커널 attention)와의 경계 ─────────────────────────────────────\n *\n * **attention 은 개체 하나의 지금 상태**다 — 앵커(설비·자리·오더)와 할 수 있는 조치를 갖는다.\n * **target(여기)은 구간의 집계**다 — 앵커도 조치도 없고 추세를 판단한다.\n *\n * 그래서 창 단위 집계 판정을 attention 으로 넣지 않는다: \"가동률 저하\"(창 평균) attention 을 만들면\n * `utilization.ratio` 목표와 **같은 사실을 두 층이 다른 임계로 판정**하게 된다.\n * (design/map/performance.md §5.0-4 — 현재 다섯 attention 과 이 어휘는 겹치지 않는다.)\n */\nimport type { DurationStats, KpiResult } from './kpi-fold.js'\n\n/** 측정된 기록이 있을 때만 값으로 인정한다 — 없으면 모름(0 이 아니다). */\nconst measured = (k: KpiResult, v: number): number | undefined => (k.eventsInWindow > 0 ? v : undefined)\n\n/** 분위수는 표본이 있을 때만 값이다 — `count === 0` 의 `p50Ms: 0` 은 \"0 밀리초\" 가 아니라 \"없음\" 이다. */\nconst statOf = (s: DurationStats, pick: (d: DurationStats) => number): number | undefined =>\n  s.count > 0 ? pick(s) : undefined\n\n/**\n * 지표 어휘 — **이름을 한 곳에서 정한다.**\n *\n * 목표와 사실이 서로 다른 이름을 쓰면 그 사이에 매핑 표가 생기고, 그 표가 곧 방언이 된다. 그래서\n * 목표가 가리킬 수 있는 지표는 여기 열거된 것뿐이고, 값을 꺼내는 방법도 여기 함께 있다.\n *\n * **`direction` 은 지표의 성질이지 사용자의 선택이 아니다.** 처리량은 높을수록 좋고 대기시간은 낮을수록\n * 좋다 — 이것을 입력으로 받으면 반대로 적은 목표가 만들어지고, 그 뒤 판정이 전부 뒤집힌다.\n */\nexport const TWIN_METRIC = {\n  /* 기록이 없는 구간은 처리량 0 이 아니라 **모름**이다 — `eventsInWindow` 가 그것을 구분한다.\n     0 으로 판정하면 \"측정 못 한 구간\" 이 \"일을 안 한 구간\" 으로 보고된다. */\n  'throughput.tasks': { direction: 'higher', unit: 'count', of: (k: KpiResult) => measured(k, k.throughput.tasks) },\n  'throughput.orders': { direction: 'higher', unit: 'count', of: (k: KpiResult) => measured(k, k.throughput.orders) },\n  /* 소요시간 분위수는 `count === 0` 이면 **0 이 아니라 없다.** 이것을 0 으로 읽으면 시간 지표는\n     \"낮을수록 좋다\" 라서 **일이 없던 구간이 목표를 완벽히 달성한 것으로** 보고된다 — 미달을 놓치는\n     것보다 나쁘다(고칠 곳이 있는데 잘하고 있다고 말한다). 테스트가 이것을 잡았다. */\n  'leadTime.p50Ms': { direction: 'lower', unit: 'ms', of: (k: KpiResult) => statOf(k.leadTime, d => d.p50Ms) },\n  'leadTime.p90Ms': { direction: 'lower', unit: 'ms', of: (k: KpiResult) => statOf(k.leadTime, d => d.p90Ms) },\n  'workTime.p50Ms': { direction: 'lower', unit: 'ms', of: (k: KpiResult) => statOf(k.workTime, d => d.p50Ms) },\n  'waitTime.p50Ms': { direction: 'lower', unit: 'ms', of: (k: KpiResult) => statOf(k.waitTime, d => d.p50Ms) },\n  /*\n   * ── 에너지 (2026-08-17) ────────────────────────────────────────────────────\n   *\n   * 값은 폴드가 이미 내고 있었는데 **목표를 걸 수 있는 지표 목록에 없었다.** 그래서 화면은 「이번 창에\n   * 1,240kWh」를 보여 주면서도 그것이 좋은지 나쁜지는 말하지 못했다 — 에너지야말로 계약이라는 딱딱한\n   * 기준선이 있는 영역인데도 그랬다.\n   *\n   * 셋 다 방향은 **낮을수록 좋다**로 못 박는다. 「많이 쓸수록 좋다」는 에너지 목표는 없다. 산출이 늘어\n   * 전력량이 느는 경우는 원단위(`energy.intensity`)가 답할 자리이지, 방향을 뒤집을 이유가 아니다.\n   *\n   * 값이 없는 창(에너지 트윈이 아니거나 계측이 끊긴 창)은 `undefined` 로 남긴다 — 0 으로 읽으면\n   * 시간 지표에서 이미 겪은 그 결함이 그대로 재현된다(안 쓴 것이 아니라 못 잰 것인데 만점이 된다).\n   */\n  'energy.kWh': { direction: 'lower', unit: 'kWh', of: (k: KpiResult) => k.energy?.kWh },\n  /** 최대수요 — 계약 상한을 목표로 적는 자리다(요금의 기본요금 부분이 여기서 정해진다). */\n  'energy.peakKW': { direction: 'lower', unit: 'kW', of: (k: KpiResult) => k.energy?.peakKW },\n  /** 원단위 — 완료 오더당 kWh. 답할 수 없으면(`null`) 판정하지 않는다. */\n  'energy.intensity': {\n    direction: 'lower',\n    unit: 'kWh/order',\n    of: (k: KpiResult) => (typeof k.energy?.intensity?.value === 'number' ? k.energy.intensity.value : undefined)\n  },\n  /** 자원 점유 — 개별 자원이 아니라 **창 전체의 평균 비율**(자원별은 관점 축의 일이다). */\n  'utilization.ratio': {\n    direction: 'higher',\n    unit: 'ratio',\n    of: (k: KpiResult) =>\n      k.utilization.length ? k.utilization.reduce((s, u) => s + u.ratio, 0) / k.utilization.length : undefined\n  }\n} as const\n\nexport type TwinMetricId = keyof typeof TWIN_METRIC\nexport const isTwinMetric = (id: string): id is TwinMetricId => id in TWIN_METRIC\n\n/**\n * 저장된 목표 행에서 **이 범위에 걸린 목표**를 고른다 — 좁은 선언이 넓은 선언을 덮는다.\n *\n * **왜 순수 함수인가**: 이 규칙(공간 목표 위에 인스턴스 목표를 얹는다)은 지금까지 DB 접근 뒤에 숨어\n * 있어서 **화면을 눌러 봐야만** 확인할 수 있었다. 그런데 이 프로젝트는 로그인 뒤 화면을 자동으로\n * 검증할 방법이 없어, 실제로 여러 기능이 \"실화면 미검증\" 으로 쌓였다. 규칙을 밖으로 빼면 테스트가\n * 값싸진다 — 조회는 행을 가져오기만 하고, **판단은 여기서** 한다.\n */\n/**\n * 축 목표까지 담은 목록 — 전체 목표와 **축의 한 값**에 걸린 목표를 함께 든다.\n *\n * 축 목표는 전체 목표를 **덮지 않는다.** 다른 질문이기 때문이다: \"현장 전체가 100건\" 과\n * \"용접 구역이 30건\" 은 동시에 참일 수 있다. 덮게 만들면 축 하나에 목표를 거는 순간 전체 판정이\n * 사라져 사용자가 \"목표를 지웠나?\" 를 묻게 된다.\n */\nexport interface ScopedTargets {\n  /** 창 전체에 걸린 목표. */\n  overall: TwinTargetSpec[]\n  /** 축 → (그 축의 값 → 목표들). 요청한 축만 채운다. */\n  byAxisKey: Record<string, TwinTargetSpec[]>\n}\n\n/**\n * 축의 각 값에 대해 목표 대비 판정 — **그룹 항목에 그대로 붙일 형태.**\n *\n * 그룹의 지표는 전체보다 좁다(주문 수·자원 점유는 축 단위로 뜻이 다르거나 없다). 없는 지표에 목표가\n * 걸려 있으면 **판정하지 않는다** — 여기서 0 으로 읽으면 시간 지표가 \"완벽 달성\" 으로 뒤집힌다\n * (전체 판정에서 이미 겪은 결함이다).\n */\nexport function judgeGroupTargets(\n  group: { key: string; tasks: number; leadTime: { count: number; p50Ms: number }; workTime: { count: number; p50Ms: number }; waitTime: { count: number; p50Ms: number } },\n  targets: readonly TwinTargetSpec[] | undefined\n): TargetVerdict[] {\n  const value = (metric: TwinMetricId): number | undefined => {\n    switch (metric) {\n      case 'throughput.tasks':\n        return group.tasks\n      case 'leadTime.p50Ms':\n        return group.leadTime.count > 0 ? group.leadTime.p50Ms : undefined\n      case 'workTime.p50Ms':\n        return group.workTime.count > 0 ? group.workTime.p50Ms : undefined\n      case 'waitTime.p50Ms':\n        return group.waitTime.count > 0 ? group.waitTime.p50Ms : undefined\n      default:\n        return undefined // 축 단위로 뜻이 없는 지표(주문 수·자원 점유) — 지어내지 않는다\n    }\n  }\n  const out: TargetVerdict[] = []\n  for (const t of targets ?? []) {\n    const spec = TWIN_METRIC[t.metric]\n    const actual = value(t.metric)\n    if (!spec || typeof actual !== 'number' || !Number.isFinite(actual) || !Number.isFinite(t.target)) continue\n    out.push(verdictOf(t.metric, actual, t.target, spec.direction))\n  }\n  return out\n}\n\nexport function mergeTargets(\n  rows: readonly TargetRow[],\n  scope: { spaceId?: string; instanceIds: readonly string[]; axis?: string }\n): TwinTargetSpec[] {\n  return scopedTargets(rows, scope).overall\n}\n\n/** 저장된 목표 행 — 판단에 필요한 것만(엔티티 전체를 요구하지 않는다: 테스트가 값싸진다). */\nexport interface TargetRow {\n  metric: string\n  target: number\n  spaceId?: string | null\n  instanceId?: string | null\n  axis?: string | null\n  axisKey?: string | null\n}\n\n/** 전체 목표와 축 목표를 함께 고른다 — 좁은 선언(인스턴스)이 넓은 선언(공간)을 덮는 규칙은 양쪽 같다. */\nexport function scopedTargets(\n  rows: readonly TargetRow[],\n  scope: { spaceId?: string; instanceIds: readonly string[]; axis?: string }\n): ScopedTargets {\n  /* 같은 자리(지표 또는 축값+지표)에 공간·인스턴스 목표가 함께 있으면 인스턴스가 이긴다. */\n  const pick = new Map<string, { target: number; fromInstance: boolean; axisKey?: string; metric: TwinMetricId }>()\n  for (const r of rows) {\n    if (!isTwinMetric(r.metric) || typeof r.target !== 'number' || !Number.isFinite(r.target)) continue\n    const inSpace = !!scope.spaceId && r.spaceId === scope.spaceId\n    const inInstance = !!r.instanceId && scope.instanceIds.includes(r.instanceId)\n    if (!inSpace && !inInstance) continue\n    if (r.axis) {\n      if (!scope.axis || r.axis !== scope.axis || !r.axisKey) continue // 지금 보는 축만\n    }\n    const slot = `${r.axis ?? ''}\\u0000${r.axisKey ?? ''}\\u0000${r.metric}`\n    const prev = pick.get(slot)\n    if (prev?.fromInstance && !inInstance) continue // 인스턴스 선언을 공간 선언이 덮지 않는다\n    pick.set(slot, { target: r.target, fromInstance: inInstance, axisKey: r.axisKey ?? undefined, metric: r.metric })\n  }\n  const overall: TwinTargetSpec[] = []\n  const byAxisKey: Record<string, TwinTargetSpec[]> = {}\n  for (const [slot, v] of pick) {\n    const spec = { metric: v.metric, target: v.target }\n    if (slot.startsWith('\\u0000')) overall.push(spec)\n    else (byAxisKey[v.axisKey as string] ??= []).push(spec)\n  }\n  return { overall, byAxisKey }\n}\n\n/** 목표 하나 — 어느 지표를, 얼마로. 방향은 지표가 안다(§TWIN_METRIC). */\nexport interface TwinTargetSpec {\n  metric: TwinMetricId\n  target: number\n}\n\nexport interface TargetVerdict {\n  metric: TwinMetricId\n  /** 이 구간의 실제 값. */\n  actual: number\n  target: number\n  direction: 'higher' | 'lower'\n  /** 목표를 만족했나. */\n  met: boolean\n  /**\n   * 목표 대비 비율 — **항상 \"1 이상이면 좋다\"** 로 정규화한다(방향이 다른 지표를 한 화면에서 비교할 수\n   * 있게). 처리량은 `actual/target`, 시간은 `target/actual`.\n   */\n  ratio: number\n}\n\n/**\n * 목표 대비 판정 — **목표가 없는 지표는 판정하지 않는다.**\n *\n * 값이 없는 지표(그 구간에 기록이 없어 `undefined`)도 판정하지 않는다. 없는 것을 0 으로 놓으면\n * \"목표 크게 미달\" 이라는 **없는 사실**이 만들어지고, 사용자는 멈춘 적 없는 라인을 고치러 간다.\n * 목표를 0 으로 준 경우도 비율을 내지 않는다(0 으로 나누지 않는다) — 만족 여부만 답한다.\n */\nexport function judgeTargets(kpi: KpiResult, targets: readonly TwinTargetSpec[] | undefined): TargetVerdict[] {\n  const out: TargetVerdict[] = []\n  for (const t of targets ?? []) {\n    const spec = TWIN_METRIC[t.metric]\n    if (!spec) continue // 모르는 지표 이름 — 짐작해 매핑하지 않는다\n    const actual = spec.of(kpi)\n    if (typeof actual !== 'number' || !Number.isFinite(actual)) continue // 값이 없다 ≠ 값이 0\n    if (!Number.isFinite(t.target)) continue\n    out.push(verdictOf(t.metric, actual, t.target, spec.direction))\n  }\n  return out\n}\n\n/** 판정 산수 한 곳 — 전체 판정과 축 판정이 **같은 규칙**을 쓴다(두 벌이면 어긋난다). */\nfunction verdictOf(metric: TwinMetricId, actual: number, target: number, direction: 'higher' | 'lower'): TargetVerdict {\n  const met = direction === 'higher' ? actual >= target : actual <= target\n  const ratio = direction === 'higher' ? (target > 0 ? actual / target : Number.NaN) : actual > 0 ? target / actual : Number.NaN\n  return { metric, actual, target, direction, met, ratio }\n}\n"]}

package/dist-server/engine/live-feed-registry.d.ts

@@ -0,0 +1,25 @@
+/** 지금 피드가 붙어 있는 인스턴스 id 들 — 그 계층의 장부가 답한다. */
+export type LiveFeedProbe = () => string[];
+/** 피드 장부를 등록한다(모듈 로드 시 한 번). */
+export declare function registerLiveFeedProbe(probe: LiveFeedProbe): void;
+/**
+ * 피드가 붙어 있나 — 어느 장부든 그렇다고 하면 그렇다.
+ *
+ * 장부가 터지는 것을 이 판정 전체의 실패로 만들지 않는다: 한 계층이 답하지 못해도 다른 계층의 사실은
+ * 그대로 참이다. 다만 **조용히 넘기지 않는다** — 답하지 못한 장부는 로그에 남긴다.
+ */
+export declare function liveFeedAttached(instanceId: string): boolean;
+/**
+ * 이 트윈의 **피드 사실** — 화면이 그대로 말할 수 있는 세 값.
+ *
+ * `not-applicable` 을 `detached` 와 섞지 않는다(이 시스템이 내내 지켜 온 「없음 ≠ 해당 없음」):
+ *  · 시뮬 트윈에는 나를 피드가 **없어야 한다** — 그건 결함이 아니라 그 트윈의 성질이다.
+ *  · 멈춘 트윈에게 피드를 묻는 것은 뜻이 없다 — 사람이 멈춰 둔 것이다.
+ *  · 남는 것 하나가 우리가 보이려던 사실이다: **도는 미러인데 아무것도 오지 않는다.**
+ */
+export type LiveFeedState = 'attached' | 'detached' | 'not-applicable';
+export declare function liveFeedStateOf(args: {
+    realityMode?: string;
+    running?: boolean;
+    instanceId: string;
+}): LiveFeedState;

package/dist-server/engine/live-feed-registry.js

@@ -0,0 +1,51 @@
+"use strict";
+/*
+ * 「이 트윈에 계측이 들어오고 있나」 — **그 사실을 한 자리에서 묻는다.**
+ *
+ * ── 무엇이 보이지 않았나 (2026-08-14) ───────────────────────────────────────
+ * 미러 트윈은 커널이 돌기만 하면 「도는 중」이라 보고했다. 그런데 계측을 나르는 피드가 떨어져 있으면
+ * 그 트윈은 **아무것도 받지 않으면서 도는 중**이다 — 화면에서 두 상태가 똑같이 보였고, 사람은
+ * 「값이 안 변하네」로 뒤늦게 알게 됐다(재기동 뒤 실제로 그랬다).
+ *
+ * ── 왜 장부가 하나여야 하나 ────────────────────────────────────────────────
+ * 피드를 여는 곳이 둘이다: 커넥터 기반(`reference-live`)과 프리셋 기반(앱의 `provision-from-preset`).
+ * 한쪽만 보고 「끊김」이라 말하면 **멀쩡히 흐르는 트윈을 끊겼다고 부르게 된다** — 거짓 경보는 참 경보를
+ * 죽인다. 그래서 각 계층이 자기 장부를 여기 **등록**하고, 묻는 쪽은 이 한 자리에만 묻는다.
+ *
+ * 호스트는 어떤 어댑터·프리셋이 있는지 몰라도 된다(계층을 거꾸로 잇지 않는다).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerLiveFeedProbe = registerLiveFeedProbe;
+exports.liveFeedAttached = liveFeedAttached;
+exports.liveFeedStateOf = liveFeedStateOf;
+const probes = [];
+/** 피드 장부를 등록한다(모듈 로드 시 한 번). */
+function registerLiveFeedProbe(probe) {
+    probes.push(probe);
+}
+/**
+ * 피드가 붙어 있나 — 어느 장부든 그렇다고 하면 그렇다.
+ *
+ * 장부가 터지는 것을 이 판정 전체의 실패로 만들지 않는다: 한 계층이 답하지 못해도 다른 계층의 사실은
+ * 그대로 참이다. 다만 **조용히 넘기지 않는다** — 답하지 못한 장부는 로그에 남긴다.
+ */
+function liveFeedAttached(instanceId) {
+    for (const probe of probes) {
+        try {
+            if (probe().includes(instanceId))
+                return true;
+        }
+        catch (e) {
+            console.warn('[twin-live] a feed registry could not answer —', e?.message ?? e);
+        }
+    }
+    return false;
+}
+function liveFeedStateOf(args) {
+    if (args.realityMode !== 'mirror')
+        return 'not-applicable';
+    if (!args.running)
+        return 'not-applicable';
+    return liveFeedAttached(args.instanceId) ? 'attached' : 'detached';
+}
+//# sourceMappingURL=live-feed-registry.js.map

package/dist-server/engine/live-feed-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-feed-registry.js","sourceRoot":"","sources":["../../server/engine/live-feed-registry.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;AAQH,sDAEC;AAQD,4CASC;AAYD,0CAIC;AAtCD,MAAM,MAAM,GAAoB,EAAE,CAAA;AAElC,gCAAgC;AAChC,SAAgB,qBAAqB,CAAC,KAAoB;IACxD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;AACpB,CAAC;AAED;;;;;GAKG;AACH,SAAgB,gBAAgB,CAAC,UAAkB;IACjD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,CAAC;YACH,IAAI,KAAK,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC;gBAAE,OAAO,IAAI,CAAA;QAC/C,CAAC;QAAC,OAAO,CAAM,EAAE,CAAC;YAChB,OAAO,CAAC,IAAI,CAAC,gDAAgD,EAAE,CAAC,EAAE,OAAO,IAAI,CAAC,CAAC,CAAA;QACjF,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAYD,SAAgB,eAAe,CAAC,IAAqE;IACnG,IAAI,IAAI,CAAC,WAAW,KAAK,QAAQ;QAAE,OAAO,gBAAgB,CAAA;IAC1D,IAAI,CAAC,IAAI,CAAC,OAAO;QAAE,OAAO,gBAAgB,CAAA;IAC1C,OAAO,gBAAgB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,CAAA;AACpE,CAAC","sourcesContent":["/*\n * 「이 트윈에 계측이 들어오고 있나」 — **그 사실을 한 자리에서 묻는다.**\n *\n * ── 무엇이 보이지 않았나 (2026-08-14) ───────────────────────────────────────\n * 미러 트윈은 커널이 돌기만 하면 「도는 중」이라 보고했다. 그런데 계측을 나르는 피드가 떨어져 있으면\n * 그 트윈은 **아무것도 받지 않으면서 도는 중**이다 — 화면에서 두 상태가 똑같이 보였고, 사람은\n * 「값이 안 변하네」로 뒤늦게 알게 됐다(재기동 뒤 실제로 그랬다).\n *\n * ── 왜 장부가 하나여야 하나 ────────────────────────────────────────────────\n * 피드를 여는 곳이 둘이다: 커넥터 기반(`reference-live`)과 프리셋 기반(앱의 `provision-from-preset`).\n * 한쪽만 보고 「끊김」이라 말하면 **멀쩡히 흐르는 트윈을 끊겼다고 부르게 된다** — 거짓 경보는 참 경보를\n * 죽인다. 그래서 각 계층이 자기 장부를 여기 **등록**하고, 묻는 쪽은 이 한 자리에만 묻는다.\n *\n * 호스트는 어떤 어댑터·프리셋이 있는지 몰라도 된다(계층을 거꾸로 잇지 않는다).\n */\n\n/** 지금 피드가 붙어 있는 인스턴스 id 들 — 그 계층의 장부가 답한다. */\nexport type LiveFeedProbe = () => string[]\n\nconst probes: LiveFeedProbe[] = []\n\n/** 피드 장부를 등록한다(모듈 로드 시 한 번). */\nexport function registerLiveFeedProbe(probe: LiveFeedProbe): void {\n  probes.push(probe)\n}\n\n/**\n * 피드가 붙어 있나 — 어느 장부든 그렇다고 하면 그렇다.\n *\n * 장부가 터지는 것을 이 판정 전체의 실패로 만들지 않는다: 한 계층이 답하지 못해도 다른 계층의 사실은\n * 그대로 참이다. 다만 **조용히 넘기지 않는다** — 답하지 못한 장부는 로그에 남긴다.\n */\nexport function liveFeedAttached(instanceId: string): boolean {\n  for (const probe of probes) {\n    try {\n      if (probe().includes(instanceId)) return true\n    } catch (e: any) {\n      console.warn('[twin-live] a feed registry could not answer —', e?.message ?? e)\n    }\n  }\n  return false\n}\n\n/**\n * 이 트윈의 **피드 사실** — 화면이 그대로 말할 수 있는 세 값.\n *\n * `not-applicable` 을 `detached` 와 섞지 않는다(이 시스템이 내내 지켜 온 「없음 ≠ 해당 없음」):\n *  · 시뮬 트윈에는 나를 피드가 **없어야 한다** — 그건 결함이 아니라 그 트윈의 성질이다.\n *  · 멈춘 트윈에게 피드를 묻는 것은 뜻이 없다 — 사람이 멈춰 둔 것이다.\n *  · 남는 것 하나가 우리가 보이려던 사실이다: **도는 미러인데 아무것도 오지 않는다.**\n */\nexport type LiveFeedState = 'attached' | 'detached' | 'not-applicable'\n\nexport function liveFeedStateOf(args: { realityMode?: string; running?: boolean; instanceId: string }): LiveFeedState {\n  if (args.realityMode !== 'mirror') return 'not-applicable'\n  if (!args.running) return 'not-applicable'\n  return liveFeedAttached(args.instanceId) ? 'attached' : 'detached'\n}\n"]}

package/dist-server/engine/load-meter.d.ts

@@ -0,0 +1,181 @@
+/** 작업 이름 — 새 작업을 재기 시작하면 여기 늘린다(문자열을 자유롭게 쓰지 않는다: 오타가 새 칸이 된다). */
+export declare const LOAD_PHASES: readonly ["tick", "snapshot", "deltas", "publish", "journal", "ingest", "forecast", "forkTick"];
+export type LoadPhase = (typeof LOAD_PHASES)[number];
+export interface PhaseStats {
+    /** 잰 횟수. */
+    count: number;
+    /** 마지막 소요(ms). */
+    lastMs: number;
+    /** 가장 오래 걸린 것(ms) — 평균은 순간 정체를 가린다. */
+    maxMs: number;
+    /** 소요 합(ms). 나눗셈은 읽는 쪽에서 한다. */
+    totalMs: number;
+}
+/** 창(window) 하나의 누적 — "지금 얼마나 쓰고 있나" 를 답한다. */
+interface Window {
+    /** 창이 열린 시각. **아직 안 열렸으면 `-1`** — 0 으로 두면 시각 0 과 구별이 안 된다(검사가 잡았다). */
+    startMs: number;
+    phases: Partial<Record<LoadPhase, PhaseStats>>;
+}
+export interface LoadMeter {
+    /** **누적** — 프로세스가 뜬 뒤 전부. 총량과 최악값을 본다. */
+    phases: Partial<Record<LoadPhase, PhaseStats>>;
+    /** 지금 쌓고 있는 창. */
+    window: Window;
+    /** **마지막으로 닫힌 창** — 이것이 "실시간" 이다. 없으면 아직 한 창도 안 지났다. */
+    recent: (Window & {
+        endMs: number;
+    }) | null;
+    /** 이 트윈에서 만들어진 fork 수(누적) — 예측 한 번이 수십 개를 만든다. */
+    forksCreated: number;
+    /** 한 주기(틱)가 예산을 넘긴 횟수. */
+    overBudget: number;
+    /**
+     * 마지막 경고 시각(ms). **한 번도 안 했으면 `-Infinity`** — 0 으로 두면 "0 시점에 경고했다" 가 되어
+     * 첫 느린 틱이 조용히 지나간다(검사가 그것을 잡았다).
+     */
+    lastWarnMs: number;
+}
+export declare function newLoadMeter(): LoadMeter;
+/**
+ * 예산 — 틱 간격의 절반. 넘으면 루프의 절반을 이 트윈 하나가 쓰고 있다는 뜻이다.
+ *
+ * 절반인 이유: 트윈이 여럿이라 각자 간격을 다 쓰면 이미 포화다. 절반에서 알아야 손 쓸 틈이 있다.
+ */
+export declare const TICK_BUDGET_RATIO = 0.5;
+/** 경고를 다시 낼 때까지의 최소 간격(ms) — 느린 트윈은 매 틱 느리므로, 그대로 두면 로그가 원인을 덮는다. */
+export declare const WARN_COOLDOWN_MS = 30000;
+/**
+ * 한 작업의 소요를 기록한다. **누적만 하고 판단하지 않는다.**
+ *
+ * 음수·NaN 은 기록하지 않는다(시계가 뒤로 간 경우). 없는 값을 0 으로 세면 평균이 거짓이 된다.
+ */
+export declare function recordPhase(meter: LoadMeter, phase: LoadPhase, tookMs: number, nowMs?: number): void;
+/** fork 하나가 만들어졌다 — 예측 한 번이 수십 개를 만든다. 수를 알아야 부하의 출처를 짚는다. */
+export declare function recordFork(meter: LoadMeter, count?: number): void;
+/** 실시간 창의 길이(ms) — 이보다 길게 보려면 누적을 본다. */
+export declare const WINDOW_MS = 10000;
+/** 창이 다 찼으면 닫고 새로 연다. **닫힌 창만 "최근" 으로 읽는다** — 채우는 중인 창은 과소 집계다. */
+export declare function rollWindow(meter: LoadMeter, nowMs: number, windowMs?: number): void;
+/**
+ * 이 주기가 예산을 넘었나 — 넘었으면 세고, **말할 때인지**까지 답한다.
+ */
+export declare function judgeCycle(meter: LoadMeter, tookMs: number, tickMs: number, nowMs: number, budgetRatio?: number, cooldownMs?: number): {
+    over: boolean;
+    warn: boolean;
+    budgetMs: number;
+};
+export interface PhaseRow {
+    phase: LoadPhase;
+    count: number;
+    lastMs: number;
+    maxMs: number;
+    avgMs: number;
+    totalMs: number;
+    /** 잰 작업 전체 시간 중 이 작업의 몫(0~1). 어디를 고칠지 이 값이 정한다. */
+    share: number;
+}
+export interface LoadView {
+    phases: PhaseRow[];
+    measuredTotalMs: number;
+    /** 이 구간의 길이(ms). 누적은 프로세스 기동 이후라 알 수 없으므로 `null`. */
+    spanMs: number | null;
+    /** 구간 중 몇 %를 이 트윈이 썼나(0~1+). 구간을 모르면 `null` — **0 이 아니다.** */
+    busyRatio: number | null;
+}
+/**
+ * 읽기용 요약 — **실시간과 누적을 함께** 낸다.
+ *
+ *  · `recent` — 마지막으로 **닫힌** 창. 지금 이 트윈이 루프를 얼마나 쓰고 있나. 채우는 중인 창은
+ *    과소 집계라 쓰지 않는다.
+ *  · `total` — 기동 이후 전부. 총량과 최악값.
+ *
+ * 잰 적이 없으면 **`null` 이다.** 0 으로 채우면 "0ms 다"(= 아주 빠르다)로 읽혀, 재지 않은 것과 정반대의
+ * 뜻이 된다. 몫(`share`)도 잰 작업들 사이의 비율일 뿐 — **재지 않은 작업은 분모에 없다.**
+ */
+export declare function loadSummary(meter: LoadMeter | undefined, tickMs: number): {
+    recent: LoadView | null;
+    total: LoadView | null;
+    forksCreated: number;
+    overBudget: number;
+    budgetMs: number;
+    /** 마지막 틱이 간격을 얼마나 썼나(0~1+). 1 이면 간격을 통째로 쓴다. */
+    loadRatio: number | null;
+} | null;
+/**
+ * 경고 한 줄 — **무엇이 느린지까지 말한다.** "틱이 800ms" 만으로는 어디를 볼지 알 수 없다.
+ *
+ * 가장 무거운 작업 셋을 몫과 함께 적는다.
+ */
+export declare function slowTickMessage(instanceId: string, tookMs: number, budgetMs: number, meter: LoadMeter): string;
+/**
+ * 전체 한눈에 — **누가 루프를 점유하고 있나.**
+ *
+ * 인스턴스 목록을 받아 대수·모드별 수·fork 총수를 세고, **최근 창의 부하가 큰 순서**로 줄을 세운다.
+ * 누적이 아니라 최근으로 세우는 이유: 지금 아픈 것을 먼저 봐야 한다(누적 1위는 오래 떠 있던 것일 뿐일
+ * 수 있다).
+ */
+export declare function fleetLoad(rows: {
+    instanceId: string;
+    mode: string;
+    domainId?: string;
+    domainLabel?: string;
+    meter?: LoadMeter;
+}[], tickMs: number): {
+    instances: number;
+    byMode: Record<string, number>;
+    /**
+     * **테넌트별 몫** — 운영자가 먼저 묻는 것은 "어느 테넌트가 루프를 먹나" 다.
+     *
+     * 실측으로 필요해졌다: 한 도메인 트윈 22개가 CPU 를 110% 쓰는 동안 다른 도메인 화면은 0 이었다.
+     * 무거운 순으로 낸다. 몫은 **잰 트윈들 사이의 비율**이다(안 잰 트윈은 분모에 없다).
+     */
+    byDomain: {
+        domainId: string;
+        label: string;
+        instances: number;
+        recentBusyMs: number;
+        share: number;
+    }[];
+    forksCreated: number;
+    /** 최근 창에서 트윈들이 쓴 시간의 합(ms) — 창 길이를 넘으면 루프가 이미 밀리고 있다. */
+    recentBusyMs: number;
+    /** 그 창의 길이(ms). 창이 하나도 안 닫혔으면 `null`. */
+    recentSpanMs: number | null;
+    /** 전체가 루프를 얼마나 쓰나(0~1+). 1 을 넘으면 **한 틱 안에 다 못 끝낸다.** */
+    fleetBusyRatio: number | null;
+    slowest: {
+        instanceId: string;
+        mode: string;
+        domainId?: string;
+        domainLabel?: string;
+        recentBusyMs: number;
+        topPhase: LoadPhase | null;
+        overBudget: number;
+    }[];
+};
+/**
+ * 프로세스가 실제로 쓴 CPU — **계기판의 다른 숫자들과 뜻이 다르다.**
+ *
+ * 이 파일의 다른 값들은 트윈의 **계측된 8개 작업**만 잰 것이다. 그런데 프로세스는 그 밖에도 일한다:
+ * GraphQL·TypeORM·GC·webpack·HTTP. 그래서 "루프 점유 <1%" 인데 CPU 는 110% 일 수 있고, 실제로 그런
+ * 상태를 겪었다. 두 숫자를 나란히 두면 **트윈이 범인인지 아닌지**를 바로 가릴 수 있다.
+ *
+ * 코어 여러 개를 쓰면 1 을 넘을 수 있다(운영체제의 `%CPU` 와 같은 뜻).
+ */
+export type CpuSampler = {
+    lastMicros: number;
+    lastMs: number;
+};
+/** 첫 표본은 비교 대상이 없다 — `-1` 로 두어 "아직 모른다" 와 0 을 구별한다. */
+export declare function newCpuSampler(): CpuSampler;
+/**
+ * 두 표본 사이의 CPU 점유율. 처음 부르면 `null`(0 이 아니다 — 잰 구간이 없다).
+ *
+ * @param totalMicros `process.cpuUsage()` 의 user + system (마이크로초 누적)
+ */
+export declare function sampleCpu(s: CpuSampler, totalMicros: number, nowMs: number): {
+    ratio: number;
+    spanMs: number;
+} | null;
+export {};