@things-factory/headless-twin 10.0.8 → 10.0.10

package/dist-server/engine/index.js

@@ -4,9 +4,26 @@ const tslib_1 = require("tslib");
 tslib_1.__exportStar(require("./twin-engine.js"), exports);
 tslib_1.__exportStar(require("./canonical-ingest.js"), exports);
 tslib_1.__exportStar(require("./kpi-fold.js"), exports);
+tslib_1.__exportStar(require("./property-effects.js"), exports);
+tslib_1.__exportStar(require("./kpi-baseline.js"), exports);
+/* 지표 정본 표(TWIN_METRIC)·목표 판정 — 소비처(twin-ai 등)가 지표 이름을 다시 열거하지 않게. */
+tslib_1.__exportStar(require("./kpi-target.js"), exports);
+tslib_1.__exportStar(require("@things-factory/headless-twin/dist-shared/kpi-broadcast.js"), exports);
+/* 집약 채널 태그(접두사 + 트윈별 태그 생성) — 소비처가 문자열을 다시 적지 않게 내보낸다. */
+tslib_1.__exportStar(require("@things-factory/headless-twin/dist-shared/entity-delta.js"), exports);
+/* 공간 계층의 단계 — 씬 표현·성과 카드·AI 가 같은 목록을 쓴다. */
+tslib_1.__exportStar(require("@things-factory/headless-twin/dist-shared/twin-level.js"), exports);
+/* 부하 계기판 — 어떤 작업이 이벤트 루프를 얼마나 쓰는지. */
+tslib_1.__exportStar(require("./load-meter.js"), exports);
+/* 런타임 레지스트리 키 규약 — 소비처(다른 키 캐시·테스트)가 `:` 를 다시 적지 않게 함께 내보낸다. */
+tslib_1.__exportStar(require("./runtime-key.js"), exports);
 tslib_1.__exportStar(require("./kpi-query.js"), exports);
 tslib_1.__exportStar(require("./spec-coverage.js"), exports);
 tslib_1.__exportStar(require("./travel-estimator.js"), exports);
 tslib_1.__exportStar(require("./measured-estimator.js"), exports);
 tslib_1.__exportStar(require("./model-basis.js"), exports);
+tslib_1.__exportStar(require("./live-feed-registry.js"), exports);
+/* 로컬 선언(현장·트윈) — 소비처(twin-ai 도구)가 명세·검사 규칙을 다시 적지 않게. */
+tslib_1.__exportStar(require("./local-declarations.js"), exports);
+tslib_1.__exportStar(require("./operation-basis.js"), exports);
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../server/engine/index.ts"],"names":[],"mappings":";;;AAAA,2DAAgC;AAChC,gEAAqC;AACrC,wDAA6B;AAC7B,yDAA8B;AAC9B,6DAAkC;AAClC,gEAAqC;AACrC,kEAAuC;AACvC,2DAAgC","sourcesContent":["export * from './twin-engine.js'\nexport * from './canonical-ingest.js'\nexport * from './kpi-fold.js'\nexport * from './kpi-query.js'\nexport * from './spec-coverage.js'\nexport * from './travel-estimator.js'\nexport * from './measured-estimator.js'\nexport * from './model-basis.js'\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../server/engine/index.ts"],"names":[],"mappings":";;;AAAA,2DAAgC;AAChC,gEAAqC;AACrC,wDAA6B;AAC7B,gEAAqC;AACrC,4DAAiC;AACjC,qEAAqE;AACrE,0DAA+B;AAC/B,qGAA0E;AAC1E,0DAA0D;AAC1D,oGAAyE;AACzE,4CAA4C;AAC5C,kGAAuE;AACvE,sCAAsC;AACtC,0DAA+B;AAC/B,gEAAgE;AAChE,2DAAgC;AAChC,yDAA8B;AAC9B,6DAAkC;AAClC,gEAAqC;AACrC,kEAAuC;AACvC,2DAAgC;AAChC,kEAAuC;AACvC,yDAAyD;AACzD,kEAAuC;AACvC,+DAAoC","sourcesContent":["export * from './twin-engine.js'\nexport * from './canonical-ingest.js'\nexport * from './kpi-fold.js'\nexport * from './property-effects.js'\nexport * from './kpi-baseline.js'\n/* 지표 정본 표(TWIN_METRIC)·목표 판정 — 소비처(twin-ai 등)가 지표 이름을 다시 열거하지 않게. */\nexport * from './kpi-target.js'\nexport * from '@things-factory/headless-twin/dist-shared/kpi-broadcast.js'\n/* 집약 채널 태그(접두사 + 트윈별 태그 생성) — 소비처가 문자열을 다시 적지 않게 내보낸다. */\nexport * from '@things-factory/headless-twin/dist-shared/entity-delta.js'\n/* 공간 계층의 단계 — 씬 표현·성과 카드·AI 가 같은 목록을 쓴다. */\nexport * from '@things-factory/headless-twin/dist-shared/twin-level.js'\n/* 부하 계기판 — 어떤 작업이 이벤트 루프를 얼마나 쓰는지. */\nexport * from './load-meter.js'\n/* 런타임 레지스트리 키 규약 — 소비처(다른 키 캐시·테스트)가 `:` 를 다시 적지 않게 함께 내보낸다. */\nexport * from './runtime-key.js'\nexport * from './kpi-query.js'\nexport * from './spec-coverage.js'\nexport * from './travel-estimator.js'\nexport * from './measured-estimator.js'\nexport * from './model-basis.js'\nexport * from './live-feed-registry.js'\n/* 로컬 선언(현장·트윈) — 소비처(twin-ai 도구)가 명세·검사 규칙을 다시 적지 않게. */\nexport * from './local-declarations.js'\nexport * from './operation-basis.js'\n"]}

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

@@ -0,0 +1,78 @@
+/** 창 하나 — 폴드의 창과 같은 모양(ms). */
+export interface BaselineWindow {
+    fromMs: number;
+    toMs: number;
+}
+/** 며칠 전 같은 시간대인가, 몇 주 전 같은 요일·시간대인가. */
+export type BaselineStride = 'day' | 'week';
+/** 한 번에 볼 수 있는 과거 구간 수 — 창마다 조회가 한 번 더 붙으므로 상한을 둔다. */
+export declare const MAX_BASELINE_PERIODS = 14;
+/**
+ * 비교할 과거 창들 — 현재 창을 **같은 길이로** 하루(또는 한 주)씩 뒤로 옮긴다.
+ *
+ * 가까운 것부터 준다(어제 → 그제 → …). 화면이 시간 순서를 다시 정하지 않아도 되게.
+ *
+ * **한계를 밝힌다**: 옮기는 것은 ms 산술이다. 트윈 공간은 고정 오프셋(`utcOffsetMinutes`)을 선언하므로
+ * 현재 모델에서는 "같은 시간대" 가 정확하다. 일광절약시간을 쓰는 시간대를 나중에 지원하면 전환이 있는
+ * 주의 하루가 한 시간 밀린다 — 그때는 오프셋 기준 캘린더 산술로 바꿔야 한다(지금 지어내지 않는다).
+ */
+export declare function baselineWindows(fromMs: number, toMs: number, periods: number, stride?: BaselineStride): BaselineWindow[];
+/** 지표의 성질 — 이름과 값 꺼내기는 호출부(`TWIN_METRIC`)가 소유한다. */
+export interface MetricSpecLike {
+    direction: 'higher' | 'lower';
+    unit: string;
+}
+/** 과거 창 하나에서 꺼낸 값들 — 그 창에 기록이 없으면 값이 `undefined` 다. */
+export interface BaselineSampleInput<M extends string> {
+    fromMs: number;
+    toMs: number;
+    values: Partial<Record<M, number | undefined>>;
+}
+/** 과거 창 하나의 결과 — **결측도 남긴다**(빼면 "지난 7일" 이 거짓이 된다). */
+export interface BaselineSample {
+    fromMs: number;
+    toMs: number;
+    measured: boolean;
+    value?: number;
+}
+/** 왜 자리를 말하지 않는지. */
+export type BaselineNoPosition = 'no-current' | 'too-few-samples';
+/**
+ * 분포 안에서 현재의 자리 — **방향을 적용한 읽기.**
+ *
+ * 임의의 임계가 없다: 표본 전부보다 좋으면 `best`, 전부보다 나쁘면 `worst`, 그 사이는 중앙값을 기준으로
+ * 구분한다. `typical` 은 중앙값과 **같을 때**만이다.
+ */
+export type BaselineStanding = 'best' | 'better-than-typical' | 'typical' | 'worse-than-typical' | 'worst';
+export interface MetricBaseline<M extends string = string> {
+    metric: M;
+    direction: 'higher' | 'lower';
+    unit: string;
+    /** 지금 창의 값 — 없으면 `undefined`(0 이 아니다). */
+    current?: number;
+    /** 요청한 과거 창 전부(결측 포함, 가까운 것부터). */
+    samples: BaselineSample[];
+    /** 요청한 창 수 / 그중 실제로 측정된 수 — 둘을 함께 봐야 "지난 7일" 을 믿을 수 있다. */
+    requested: number;
+    measuredCount: number;
+    /** 측정된 표본만의 요약. 표본이 없으면 전부 `undefined`. */
+    min?: number;
+    median?: number;
+    max?: number;
+    /** 측정 표본을 오름차순으로 놓았을 때 현재 값이 몇 번째인가(1 = 가장 작음) — **방향 없는 사실**. */
+    rank?: number;
+    /** 그 순위를 셀 때의 표본 수(+현재 1). 순위만 보면 표본이 둘이었는지 열이었는지 알 수 없다. */
+    rankOf?: number;
+    /** 방향을 적용한 읽기. 말할 수 없으면 없다. */
+    standing?: BaselineStanding;
+    /** 자리를 말하지 않은 이유. */
+    noPosition?: BaselineNoPosition;
+}
+/**
+ * 지표별로 분포와 자리를 만든다.
+ *
+ * @param specs   지표 성질(방향·단위). 열거된 지표만 낸다 — 모르는 이름을 짐작하지 않는다.
+ * @param current 지금 창에서 꺼낸 값들(결측은 `undefined`).
+ * @param inputs  과거 창들에서 꺼낸 값들(가까운 것부터).
+ */
+export declare function summarizeBaseline<M extends string>(specs: Readonly<Record<M, MetricSpecLike>>, current: Partial<Record<M, number | undefined>>, inputs: readonly BaselineSampleInput<M>[]): MetricBaseline<M>[];

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

@@ -0,0 +1,123 @@
+"use strict";
+/*
+ * 여러 구간 동시 비교 — **"어제보다 나아졌다" 를 넘어선다.** 순수.
+ *
+ * ── 왜 필요한가 (성과 맵 ③) ─────────────────────────────────────────────────
+ * 지금 비교 축은 **한 구간**만 본다(직전 구간 또는 하루 전). 그래서 판단이 딱 한 문장에서 멈춘다:
+ * "어제보다 나아졌다." **어제도 나빴으면 그 말은 쓸모가 없다.** 목표(`kpi-target`)가 그 한계를 한쪽에서
+ * 풀지만, 목표를 아직 걸지 않은 현장은 여전히 자기 숫자가 평소와 같은지도 알 수 없다.
+ *
+ * 최근 며칠의 **같은 시간대**를 함께 접으면 목표 없이도 말할 수 있다 — "오늘 이 시간대는 지난 7일 중
+ * 가장 낮다." 그것이 이 파일이 만드는 것이다: 창 여러 개의 **분포**와 그 안에서 현재의 **자리**.
+ *
+ * ── 이 파일이 하지 않는 것 ──────────────────────────────────────────────────
+ * · **지표 어휘를 모른다.** 이름·방향·값 꺼내는 법은 `kpi-target.ts` 의 `TWIN_METRIC` 이 소유한다. 여기는
+ *   **이미 꺼낸 값**만 받는다 — 어휘가 두 곳에 생기면 그 사이에 매핑 표가 자라고 그것이 곧 방언이다.
+ *   (덤으로: 이 모듈은 런타임 import 가 없어 테스트가 소스를 그대로 든다.)
+ * · **DB·조회를 모른다.** 창 목록만 계산하고, 그 창을 읽는 것은 호출부의 일이다.
+ * · **좋고 나쁨의 임계를 발명하지 않는다.** "평소보다 나쁘다" 는 중앙값과의 비교로만 말한다 — 임의의
+ *   퍼센트 임계를 두면 그 숫자가 곧 숨은 목표가 된다.
+ *
+ * ── 정직성 규율 (이 도메인의 핵심) ──────────────────────────────────────────
+ *  ① **결측 창을 조용히 빼지 않는다.** 요청한 창 전부를 `measured` 와 함께 돌려주고, 분포는 측정된
+ *     것만으로 만든다. 빼고 말하면 "지난 7일" 이 실제로는 3일이었다는 것을 아무도 모른다.
+ *  ② **표본이 둘 미만이면 자리를 말하지 않는다.** 하나를 분포라 부를 수 없다.
+ *  ③ **현재 값이 없으면 자리를 말하지 않는다.** 결측을 0 으로 읽으면 시간 지표는 "낮을수록 좋다" 라서
+ *     **일이 없던 구간이 최고 성적**으로 보고된다(목표 판정에서 이미 겪은 결함이다).
+ *  ④ 왜 말하지 않는지를 `reason` 으로 밝힌다 — 조용히 빈 값을 주면 화면이 "분포 없음" 을 "평범함" 으로
+ *     그린다.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_BASELINE_PERIODS = void 0;
+exports.baselineWindows = baselineWindows;
+exports.summarizeBaseline = summarizeBaseline;
+/** 한 번에 볼 수 있는 과거 구간 수 — 창마다 조회가 한 번 더 붙으므로 상한을 둔다. */
+exports.MAX_BASELINE_PERIODS = 14;
+const MS_DAY = 24 * 60 * 60_000;
+/**
+ * 비교할 과거 창들 — 현재 창을 **같은 길이로** 하루(또는 한 주)씩 뒤로 옮긴다.
+ *
+ * 가까운 것부터 준다(어제 → 그제 → …). 화면이 시간 순서를 다시 정하지 않아도 되게.
+ *
+ * **한계를 밝힌다**: 옮기는 것은 ms 산술이다. 트윈 공간은 고정 오프셋(`utcOffsetMinutes`)을 선언하므로
+ * 현재 모델에서는 "같은 시간대" 가 정확하다. 일광절약시간을 쓰는 시간대를 나중에 지원하면 전환이 있는
+ * 주의 하루가 한 시간 밀린다 — 그때는 오프셋 기준 캘린더 산술로 바꿔야 한다(지금 지어내지 않는다).
+ */
+function baselineWindows(fromMs, toMs, periods, stride = 'day') {
+    if (!Number.isFinite(fromMs) || !Number.isFinite(toMs) || toMs <= fromMs)
+        return [];
+    const count = Math.max(0, Math.min(exports.MAX_BASELINE_PERIODS, Math.floor(periods)));
+    const step = stride === 'week' ? 7 * MS_DAY : MS_DAY;
+    return Array.from({ length: count }, (_, i) => ({
+        fromMs: fromMs - step * (i + 1),
+        toMs: toMs - step * (i + 1)
+    }));
+}
+/** 중앙값 — 짝수 개면 가운데 둘의 평균(폴드의 분위수 규약과 달리 여기 표본은 아주 작다). */
+function medianOf(sorted) {
+    if (!sorted.length)
+        return undefined;
+    const mid = sorted.length >> 1;
+    return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+/**
+ * 지표별로 분포와 자리를 만든다.
+ *
+ * @param specs   지표 성질(방향·단위). 열거된 지표만 낸다 — 모르는 이름을 짐작하지 않는다.
+ * @param current 지금 창에서 꺼낸 값들(결측은 `undefined`).
+ * @param inputs  과거 창들에서 꺼낸 값들(가까운 것부터).
+ */
+function summarizeBaseline(specs, current, inputs) {
+    const out = [];
+    for (const metric of Object.keys(specs)) {
+        const spec = specs[metric];
+        const samples = inputs.map(s => {
+            const v = s.values[metric];
+            const measured = typeof v === 'number' && Number.isFinite(v);
+            return measured ? { fromMs: s.fromMs, toMs: s.toMs, measured: true, value: v } : { fromMs: s.fromMs, toMs: s.toMs, measured: false };
+        });
+        const values = samples.filter(s => s.measured).map(s => s.value);
+        const sorted = [...values].sort((a, b) => a - b);
+        const cur = current[metric];
+        const hasCurrent = typeof cur === 'number' && Number.isFinite(cur);
+        const row = {
+            metric,
+            direction: spec.direction,
+            unit: spec.unit,
+            ...(hasCurrent ? { current: cur } : {}),
+            samples,
+            requested: inputs.length,
+            measuredCount: values.length,
+            ...(sorted.length ? { min: sorted[0], median: medianOf(sorted), max: sorted[sorted.length - 1] } : {})
+        };
+        /* 자리를 말할 수 없는 두 경우 — 이유를 밝힌다(조용한 빈 값이 "평범함" 으로 읽힌다). */
+        if (!hasCurrent)
+            row.noPosition = 'no-current';
+        else if (sorted.length < 2)
+            row.noPosition = 'too-few-samples';
+        else {
+            const value = cur;
+            const median = medianOf(sorted);
+            /* 오름차순에서 몇 번째인가 — 같은 값은 뒤에 놓는다(동률이면 "더 큰 쪽" 으로 세지 않는다). */
+            row.rank = sorted.filter(v => v < value).length + 1;
+            row.rankOf = sorted.length + 1;
+            const higherIsBetter = spec.direction === 'higher';
+            const beatsAll = higherIsBetter ? value > sorted[sorted.length - 1] : value < sorted[0];
+            const losesToAll = higherIsBetter ? value < sorted[0] : value > sorted[sorted.length - 1];
+            /* 중앙값보다 큰 것이 "좋은" 쪽인가 — 방향을 여기 한 번만 적용한다. */
+            const aboveMedianIsBetter = higherIsBetter === value > median;
+            row.standing = beatsAll
+                ? 'best'
+                : losesToAll
+                    ? 'worst'
+                    : value === median
+                        ? 'typical'
+                        : aboveMedianIsBetter
+                            ? 'better-than-typical'
+                            : 'worse-than-typical';
+        }
+        out.push(row);
+    }
+    return out;
+}
+//# sourceMappingURL=kpi-baseline.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"kpi-baseline.js","sourceRoot":"","sources":["../../server/engine/kpi-baseline.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * 여러 구간 동시 비교 — **\"어제보다 나아졌다\" 를 넘어선다.** 순수.\n *\n * ── 왜 필요한가 (성과 맵 ③) ─────────────────────────────────────────────────\n * 지금 비교 축은 **한 구간**만 본다(직전 구간 또는 하루 전). 그래서 판단이 딱 한 문장에서 멈춘다:\n * \"어제보다 나아졌다.\" **어제도 나빴으면 그 말은 쓸모가 없다.** 목표(`kpi-target`)가 그 한계를 한쪽에서\n * 풀지만, 목표를 아직 걸지 않은 현장은 여전히 자기 숫자가 평소와 같은지도 알 수 없다.\n *\n * 최근 며칠의 **같은 시간대**를 함께 접으면 목표 없이도 말할 수 있다 — \"오늘 이 시간대는 지난 7일 중\n * 가장 낮다.\" 그것이 이 파일이 만드는 것이다: 창 여러 개의 **분포**와 그 안에서 현재의 **자리**.\n *\n * ── 이 파일이 하지 않는 것 ──────────────────────────────────────────────────\n * · **지표 어휘를 모른다.** 이름·방향·값 꺼내는 법은 `kpi-target.ts` 의 `TWIN_METRIC` 이 소유한다. 여기는\n *   **이미 꺼낸 값**만 받는다 — 어휘가 두 곳에 생기면 그 사이에 매핑 표가 자라고 그것이 곧 방언이다.\n *   (덤으로: 이 모듈은 런타임 import 가 없어 테스트가 소스를 그대로 든다.)\n * · **DB·조회를 모른다.** 창 목록만 계산하고, 그 창을 읽는 것은 호출부의 일이다.\n * · **좋고 나쁨의 임계를 발명하지 않는다.** \"평소보다 나쁘다\" 는 중앙값과의 비교로만 말한다 — 임의의\n *   퍼센트 임계를 두면 그 숫자가 곧 숨은 목표가 된다.\n *\n * ── 정직성 규율 (이 도메인의 핵심) ──────────────────────────────────────────\n *  ① **결측 창을 조용히 빼지 않는다.** 요청한 창 전부를 `measured` 와 함께 돌려주고, 분포는 측정된\n *     것만으로 만든다. 빼고 말하면 \"지난 7일\" 이 실제로는 3일이었다는 것을 아무도 모른다.\n *  ② **표본이 둘 미만이면 자리를 말하지 않는다.** 하나를 분포라 부를 수 없다.\n *  ③ **현재 값이 없으면 자리를 말하지 않는다.** 결측을 0 으로 읽으면 시간 지표는 \"낮을수록 좋다\" 라서\n *     **일이 없던 구간이 최고 성적**으로 보고된다(목표 판정에서 이미 겪은 결함이다).\n *  ④ 왜 말하지 않는지를 `reason` 으로 밝힌다 — 조용히 빈 값을 주면 화면이 \"분포 없음\" 을 \"평범함\" 으로\n *     그린다.\n */\n\n/** 창 하나 — 폴드의 창과 같은 모양(ms). */\nexport interface BaselineWindow {\n  fromMs: number\n  toMs: number\n}\n\n/** 며칠 전 같은 시간대인가, 몇 주 전 같은 요일·시간대인가. */\nexport type BaselineStride = 'day' | 'week'\n\n/** 한 번에 볼 수 있는 과거 구간 수 — 창마다 조회가 한 번 더 붙으므로 상한을 둔다. */\nexport const MAX_BASELINE_PERIODS = 14\n\nconst MS_DAY = 24 * 60 * 60_000\n\n/**\n * 비교할 과거 창들 — 현재 창을 **같은 길이로** 하루(또는 한 주)씩 뒤로 옮긴다.\n *\n * 가까운 것부터 준다(어제 → 그제 → …). 화면이 시간 순서를 다시 정하지 않아도 되게.\n *\n * **한계를 밝힌다**: 옮기는 것은 ms 산술이다. 트윈 공간은 고정 오프셋(`utcOffsetMinutes`)을 선언하므로\n * 현재 모델에서는 \"같은 시간대\" 가 정확하다. 일광절약시간을 쓰는 시간대를 나중에 지원하면 전환이 있는\n * 주의 하루가 한 시간 밀린다 — 그때는 오프셋 기준 캘린더 산술로 바꿔야 한다(지금 지어내지 않는다).\n */\nexport function baselineWindows(\n  fromMs: number,\n  toMs: number,\n  periods: number,\n  stride: BaselineStride = 'day'\n): BaselineWindow[] {\n  if (!Number.isFinite(fromMs) || !Number.isFinite(toMs) || toMs <= fromMs) return []\n  const count = Math.max(0, Math.min(MAX_BASELINE_PERIODS, Math.floor(periods)))\n  const step = stride === 'week' ? 7 * MS_DAY : MS_DAY\n\n  return Array.from({ length: count }, (_, i) => ({\n    fromMs: fromMs - step * (i + 1),\n    toMs: toMs - step * (i + 1)\n  }))\n}\n\n/** 지표의 성질 — 이름과 값 꺼내기는 호출부(`TWIN_METRIC`)가 소유한다. */\nexport interface MetricSpecLike {\n  direction: 'higher' | 'lower'\n  unit: string\n}\n\n/** 과거 창 하나에서 꺼낸 값들 — 그 창에 기록이 없으면 값이 `undefined` 다. */\nexport interface BaselineSampleInput<M extends string> {\n  fromMs: number\n  toMs: number\n  values: Partial<Record<M, number | undefined>>\n}\n\n/** 과거 창 하나의 결과 — **결측도 남긴다**(빼면 \"지난 7일\" 이 거짓이 된다). */\nexport interface BaselineSample {\n  fromMs: number\n  toMs: number\n  measured: boolean\n  value?: number\n}\n\n/** 왜 자리를 말하지 않는지. */\nexport type BaselineNoPosition = 'no-current' | 'too-few-samples'\n\n/**\n * 분포 안에서 현재의 자리 — **방향을 적용한 읽기.**\n *\n * 임의의 임계가 없다: 표본 전부보다 좋으면 `best`, 전부보다 나쁘면 `worst`, 그 사이는 중앙값을 기준으로\n * 구분한다. `typical` 은 중앙값과 **같을 때**만이다.\n */\nexport type BaselineStanding = 'best' | 'better-than-typical' | 'typical' | 'worse-than-typical' | 'worst'\n\nexport interface MetricBaseline<M extends string = string> {\n  metric: M\n  direction: 'higher' | 'lower'\n  unit: string\n  /** 지금 창의 값 — 없으면 `undefined`(0 이 아니다). */\n  current?: number\n  /** 요청한 과거 창 전부(결측 포함, 가까운 것부터). */\n  samples: BaselineSample[]\n  /** 요청한 창 수 / 그중 실제로 측정된 수 — 둘을 함께 봐야 \"지난 7일\" 을 믿을 수 있다. */\n  requested: number\n  measuredCount: number\n  /** 측정된 표본만의 요약. 표본이 없으면 전부 `undefined`. */\n  min?: number\n  median?: number\n  max?: number\n  /** 측정 표본을 오름차순으로 놓았을 때 현재 값이 몇 번째인가(1 = 가장 작음) — **방향 없는 사실**. */\n  rank?: number\n  /** 그 순위를 셀 때의 표본 수(+현재 1). 순위만 보면 표본이 둘이었는지 열이었는지 알 수 없다. */\n  rankOf?: number\n  /** 방향을 적용한 읽기. 말할 수 없으면 없다. */\n  standing?: BaselineStanding\n  /** 자리를 말하지 않은 이유. */\n  noPosition?: BaselineNoPosition\n}\n\n/** 중앙값 — 짝수 개면 가운데 둘의 평균(폴드의 분위수 규약과 달리 여기 표본은 아주 작다). */\nfunction medianOf(sorted: readonly number[]): number | undefined {\n  if (!sorted.length) return undefined\n  const mid = sorted.length >> 1\n  return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2\n}\n\n/**\n * 지표별로 분포와 자리를 만든다.\n *\n * @param specs   지표 성질(방향·단위). 열거된 지표만 낸다 — 모르는 이름을 짐작하지 않는다.\n * @param current 지금 창에서 꺼낸 값들(결측은 `undefined`).\n * @param inputs  과거 창들에서 꺼낸 값들(가까운 것부터).\n */\nexport function summarizeBaseline<M extends string>(\n  specs: Readonly<Record<M, MetricSpecLike>>,\n  current: Partial<Record<M, number | undefined>>,\n  inputs: readonly BaselineSampleInput<M>[]\n): MetricBaseline<M>[] {\n  const out: MetricBaseline<M>[] = []\n\n  for (const metric of Object.keys(specs) as M[]) {\n    const spec = specs[metric]\n    const samples: BaselineSample[] = inputs.map(s => {\n      const v = s.values[metric]\n      const measured = typeof v === 'number' && Number.isFinite(v)\n      return measured ? { fromMs: s.fromMs, toMs: s.toMs, measured: true, value: v as number } : { fromMs: s.fromMs, toMs: s.toMs, measured: false }\n    })\n\n    const values = samples.filter(s => s.measured).map(s => s.value as number)\n    const sorted = [...values].sort((a, b) => a - b)\n    const cur = current[metric]\n    const hasCurrent = typeof cur === 'number' && Number.isFinite(cur)\n\n    const row: MetricBaseline<M> = {\n      metric,\n      direction: spec.direction,\n      unit: spec.unit,\n      ...(hasCurrent ? { current: cur as number } : {}),\n      samples,\n      requested: inputs.length,\n      measuredCount: values.length,\n      ...(sorted.length ? { min: sorted[0], median: medianOf(sorted), max: sorted[sorted.length - 1] } : {})\n    }\n\n    /* 자리를 말할 수 없는 두 경우 — 이유를 밝힌다(조용한 빈 값이 \"평범함\" 으로 읽힌다). */\n    if (!hasCurrent) row.noPosition = 'no-current'\n    else if (sorted.length < 2) row.noPosition = 'too-few-samples'\n    else {\n      const value = cur as number\n      const median = medianOf(sorted) as number\n      /* 오름차순에서 몇 번째인가 — 같은 값은 뒤에 놓는다(동률이면 \"더 큰 쪽\" 으로 세지 않는다). */\n      row.rank = sorted.filter(v => v < value).length + 1\n      row.rankOf = sorted.length + 1\n\n      const higherIsBetter = spec.direction === 'higher'\n      const beatsAll = higherIsBetter ? value > sorted[sorted.length - 1] : value < sorted[0]\n      const losesToAll = higherIsBetter ? value < sorted[0] : value > sorted[sorted.length - 1]\n      /* 중앙값보다 큰 것이 \"좋은\" 쪽인가 — 방향을 여기 한 번만 적용한다. */\n      const aboveMedianIsBetter = higherIsBetter === value > median\n\n      row.standing = beatsAll\n        ? 'best'\n        : losesToAll\n          ? 'worst'\n          : value === median\n            ? 'typical'\n            : aboveMedianIsBetter\n              ? 'better-than-typical'\n              : 'worse-than-typical'\n    }\n\n    out.push(row)\n  }\n\n  return out\n}\n"]}

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

@@ -1,4 +1,4 @@
-import { type WorkCalendarEntry } from '@operato/twin-kernel';
+import { type ElectricityCost, type TariffDeclaration, type WorkCalendarEntry } from '@operato/twin-kernel';
 /** 저널 한 줄 — 필요한 것만(엔티티·typeorm 비의존). */
 export interface KpiEvent {
     eventType?: string;
@@ -56,6 +56,117 @@ export interface KpiResult {
         tasks: number;
         orders: number;
     };
+    /**
+     * 에너지 — **이 창의 전력량과 원단위.** 에너지 트윈이 없으면 `undefined`(0 이 아니다).
+     *
+     * ── 왜 KPI 폴드 안에 있나 (2026-08-14, §10 7단계) ─────────────────────────
+     * 원단위는 분자(전력량)와 분모(산출)를 **같은 창**에서 나눈 값이다. 질의를 따로 두면 두 창을 맞추는
+     * 일이 소비처의 몫이 되고, 어긋난 두 사실을 나눈 숫자는 아무것도 뜻하지 않는다(커널의 규칙이 그것을
+     * 거절한다). 같은 폴드 안에 두면 창이 하나뿐이라 어긋날 수 없다.
+     *
+     * 분자는 **저널의 구간 마감 사건**에서 온다(`energy.demand.window`) — 커널 상태가 아니라 저널이므로
+     * 멈춘 트윈·과거 구간에도 답할 수 있다.
+     */
+    energy?: {
+        /** 이 창의 전력량. 셀 수 있는 구간이 없으면 `undefined`. */
+        kWh?: number;
+        /**
+         * 이 창의 **최대수요**(kW)와 그것이 난 구간의 시작.
+         *
+         * 전력량과 다른 질문이다: 전력량은 요금의 사용량 부분이고, 최대수요는 **기본요금**과 계약 위반을
+         * 정한다. 평균으로 갈음할 수 없어서 커널이 구간의 최대들 중 가장 큰 값을 따로 낸다.
+         */
+        peakKW?: number;
+        peakStartMs?: number;
+        /**
+         * 그 피크 구간에서 **설비가 끌어당긴** 최대(발전·방전 차감 전)와 그 차이(깎인 양).
+         *
+         * 요금은 계통 수요(`peakKW`)로 매겨지지만, 「무엇이 그 수요를 만들었나」와 「무엇이 덜어냈나」는
+         * 이 두 수의 간격이 답한다. 발전·축전을 선언하지 않은 현장에서는 없다(차감할 것이 없다).
+         */
+        peakGrossKW?: number;
+        shavedKW?: number;
+        /** 파생의 근거 — 구간 평균부하 × 길이(`mean-kw`). */
+        basis: string;
+        /** 센 구간 수 · 못 센 구간 수(계측이 끊긴 구간) — 조용히 자르지 않는다. */
+        counted: number;
+        skipped: number;
+        /** 완료 오더당 전력량 — 답할 수 없으면 `null` 과 이유. */
+        intensity: {
+            value: number | null;
+            unit?: string;
+            reason?: string;
+        };
+        /**
+         * 배전 계통의 **자리별 몫** — 「이 분기가 얼마 썼나」.
+         *
+         * ── 이것은 측정이 아니라 배분이다 ──────────────────────────────────────
+         * 저널에 있는 에너지 사실은 **현장 총량 한 줄**이다(뿌리 계량기 합). 계량기별 구간 사실이 없으므로
+         * 자리별 몫은 **나눈 것**이고, 무엇으로 나눴는지(`weightKind`)를 값과 함께 낸다. 근거를 감추면
+         * 나눈 숫자가 잰 숫자와 같은 무게로 읽힌다 — CBAM·ESG 보고에서 첫 질문에 깨지는 지점이다.
+         *
+         * 가중치는 **작업 가동시간**이다. 정격(kW)으로 나누지 않는다: 시뮬 트윈의 총부하가 정격의 합으로
+         * 파생되므로, 그 총량을 다시 정격으로 나누면 넣은 값이 그대로 나오는 동어반복이 된다.
+         *
+         * 그래서 이 값에는 **가정이 하나 실려 있다**: 전기가 가동시간에 비례한다. 공조·조명처럼 공정에
+         * 붙지 않는 부하도 그 비율에 섞인다 — 화면이 그 문장을 함께 말해야 한다.
+         */
+        byFeeder?: {
+            /** 자리(분기·수전) id. 자리를 모르는 자원은 `unknown` 으로 모인다(조용히 버리지 않는다). */
+            key: string;
+            kWh: number;
+            /**
+             * 이 몫의 근거 — **커널이 정한다.**
+             *
+             * 선언된 부하가 여럿이면 배분(`apportioned`)이다. 선언된 부하가 **하나뿐인** 현장에서는 커널이
+             * 「그 계량기는 그것만 잰다」고 읽어 `measured` 를 낸다 — 모델이 그렇게 말했으므로 그것도 사실이다.
+             * 우리가 어느 쪽으로도 낙인찍지 않는다.
+             */
+            basis: 'apportioned' | 'measured';
+            /**
+             * 무엇으로 나눴나 — **배분일 때만** 있다.
+             *
+             * 분기마다 계량기가 있는 현장에서는 나누지 않는다(그 값이 곧 계량이다). 그때 이 칸을
+             * `runtimeMs` 로 채우면 「가동시간으로 나눴다」는 없는 사실을 말하게 된다.
+             */
+            weightKind?: 'runtimeMs';
+            /** 이 자리의 몫이 전체의 얼마였나 — 배분일 때만. */
+            weightShare?: number;
+            /**
+             * **피크가 찍힌 순간** 이 분기가 얼마였나(kW) — 요금이 걸린 수다.
+             *
+             * 창의 평균이나 합이 아니다: 최대수요를 낸 구간의 그 순간 값이다(다른 순간을 섞으면 「어느 분기를
+             * 깎아야 피크가 내려가나」의 답이 흐려진다). 그 구간에 이 분기의 표본이 없었으면 **없다**.
+             */
+            peakKW?: number;
+        }[];
+        /**
+         * 나누지 못한 양과 그 이유 — **조용히 0 으로 만들지 않는다.**
+         * `no-weights` = 그 창에 돌아간 자원이 없다(가동시간이 전부 0). 그러면 총량은 그대로 남는다.
+         */
+        unattributedKWh?: number;
+        /**
+         * 왜 나누지 못했나(커널 코드) — `no-weights`(가동시간이 전부 0) · `no-consumers`(덮는 대상 미선언) ·
+         * `not-submetered`(뿌리에서 재었으나 하위 계량이 덮지 않는 부분 — 결손이 아니라 계량 범위의 사실).
+         */
+        unattributedReason?: string;
+        /**
+         * 분기 계량의 합이 뿌리 계량보다 **큰** 양 — 두 계량기의 회계가 다르다는 사실이다.
+         *
+         * 값을 깎아 맞추지 않는다: 그것은 계량을 우리가 고쳐 쓰는 일이고, 어느 쪽이 맞는지는 현장이 안다.
+         */
+        submeterExcessKWh?: number;
+        /**
+         * 배분에서 **빠진 자원 수** — 그 창에 가동 기록이 없는 설비다. 0kWh 를 주지 않는 대신 몇 대가
+         * 빠졌는지 센다(대기전력이 있는 설비에서 0 은 곧 거짓이다).
+         */
+        excludedResources?: number;
+        /**
+         * 이 창의 전기요금 — **청구서가 아니다.** 계산과 그 한계(TOU·래칫·최소청구액 미모델)는 커널
+         * (`electricityCost`)이 갖고 여기서는 나른다. 단가가 없으면 `reason: 'no-tariff'` 로 온다.
+         */
+        cost?: ElectricityCost;
+    };
     /** 리드타임 — 생성(created)에서 완료까지. 사용자가 체감하는 소요 시간. */
     leadTime: DurationStats;
     /** 작업시간 — 착수(in-progress)에서 완료까지. 대기를 뺀 실작업. */
@@ -106,6 +217,31 @@ export interface KpiFoldOptions {
      * 호출부가 넘긴다. 없으면 구역 축은 'unknown' 으로 모인다(조용히 다른 축으로 바꾸지 않는다).
      */
     locationArea?: Record<string, string>;
+    /**
+     * 자원 → **배전 계통의 자리**(분기·수전) 지도.
+     *
+     * ── 왜 밖에서 오나 ───────────────────────────────────────────────────────
+     * 이벤트에는 전기 계통이 없다. 「이 설비가 어느 분기에서 먹는가」는 에너지 트윈의 모델이 아는
+     * 선언이고(설비 하나에 사실 둘 — 공장에서는 자원, 전기에서는 부하), 그 선언을 읽는 것은 호출부의 일이다.
+     *
+     * 없으면 분기 분해를 **하지 않는다** — 자리를 모르는 채 나누면 그 숫자는 아무 것의 몫도 아니다.
+     */
+    resourceFeeder?: Record<string, string>;
+    /**
+     * **계량 지점 → 그것이 재는 분기** 지도.
+     *
+     * 있으면 분기별 전력량을 계량으로 읽는다(배분보다 강한 근거). 이 지도는 모델의 선언에서 오고
+     * (계량기의 자리), 그것을 읽는 것은 호출부의 일이다 — 폴드는 저널만 본다.
+     */
+    meterFeeder?: Record<string, string>;
+    /**
+     * 선언된 **전기요금 단가** — 수를 금액으로 바꾸는 유일한 입력.
+     *
+     * 이벤트에는 요금이 없다. 단가는 현장의 계약이고(에너지 트윈 모델의 수전 자리에 선언한다), 그것을
+     * 읽는 것은 호출부의 일이다. 없으면 금액을 만들지 않는다 — 짐작한 단가로 낸 금액은 숫자가 있다는
+     * 것만으로 사람을 결정으로 밀어붙인다.
+     */
+    tariff?: TariffDeclaration;
     /**
      * 교대 선언 — **이벤트에는 교대가 없다**(시각만 있다). 현장 마스터가 아는 값이라 호출부가 넘긴다.
      * 없으면 교대 축은 'unknown' 으로 모인다(다른 축으로 조용히 바꾸지 않는다).