@things-factory/headless-twin 10.1.278 → 10.1.280

package/server/engine/integration-probes.ts

@@ -1,144 +0,0 @@
-/*
- * 연결 적합성 하네스 — **통합을 시험 스위트처럼 돌린다.**
- *
- * 선언 적합성 하네스 세 벌과 같은 규율을 **연결**에 적용한다: 사실이 오류 없이 사라지는 것을 막는다.
- * 다른 점은 대상이 우리 선언이 아니라 **남의 시스템**이라는 것이고, 그래서 두 규칙이 더 붙는다.
- *
- *  ① **돌리지 않은 프로브는 「실패」가 아니라 「모른다」다.** 실패로 처리하면 사람이 그 빨간 칸을
- *     없애려고 무엇이든 하게 되고, 모른다로 처리하면 **무엇을 아직 모르는지**가 남는다. 판정
- *     (`assessStagePath`)이 「모른다」를 달성으로 바꾸지 않으므로 이 구분이 끝까지 살아 있다.
- *  ② **쓰기 프로브는 명시 동의 없이 돌지 않는다.** 이 스위트는 고객의 운영 시스템을 두드린다.
- *     읽기는 기본으로 돌리고, 남의 공장에 명령을 넣는 프로브는 사람이 켜야 돈다 — 켜지 않으면
- *     폐루프 칸은 「검증되지 않음」으로 남는다(그게 사실이다).
- *
- * 순수 모듈이다(전송·DB 무의존). 실행기는 이 선언을 읽어 프로브를 돌리고 `ProbeResult[]` 를 낸다.
- * 화면은 그 결과와 `assessStagePath` 의 판정을 함께 보인다 — 초록/빨강과 **그 초록이 무엇을 증명하나**.
- */
-
-import type { StageEvidence, StageId } from './stage-path.ts'
-
-export type ProbeId =
-  | 'connect'            // 붙는다
-  | 'discover'           // 사이트가 열거된다
-  | 'master'             // 구조가 들어온다
-  | 'master-warnings'    // 못 옮긴 값을 세었다
-  | 'items'              // 자리에 물품이 놓인다(비직렬 수량 포함)
-  | 'live-ingest'        // 이벤트가 들어온다
-  | 'live-removal'       // **반출이 관측된다** — 진짜 delta 의 증거
-  | 'declarations'       // 공정 선언이 실려 있다
-  | 'forecast'           // 예측이 돈다
-  | 'actuate-declared'   // 액추에이션 능력이 선언∩구현이다
-  | 'actuate-effect'     // 명령의 효과가 상관되어 돌아온다 (쓰기)
-
-export interface ProbeSpec {
-  id: ProbeId
-  /** 이 프로브가 증거를 대는 단계. */
-  stage: StageId
-  /** **무엇을 증명하나** — 언어중립 키(사람 말은 표현계층이 렌더). 「무엇을 호출하나」가 아니다. */
-  proves: string
-  /** 대상 시스템을 바꾸는가. 참이면 사람이 켜야 돈다. */
-  writes: boolean
-  /** 이 프로브가 실패하면 뒤 프로브를 돌릴 의미가 없다. */
-  gating: boolean
-}
-
-/**
- * 시퀀스 — 순서가 곧 방법론이다. 앞이 막히면 뒤는 돌리지 않는다(돌려도 답이 무의미하다).
- *
- * `master-warnings` 를 **별개 프로브**로 둔 이유: 구조가 들어오는 것과 못 옮긴 값을 세는 것은 다른
- * 사실이고, 세지 않은 인제스트는 도크를 랙으로 바꿔 놓고도 성공으로 보인다.
- */
-export const PROBE_SEQUENCE: readonly ProbeSpec[] = [
-  { id: 'connect',          stage: 'structure',   proves: 'probe.connect',         writes: false, gating: true },
-  { id: 'discover',         stage: 'structure',   proves: 'probe.discover',        writes: false, gating: true },
-  { id: 'master',           stage: 'structure',   proves: 'probe.master',          writes: false, gating: true },
-  { id: 'master-warnings',  stage: 'structure',   proves: 'probe.masterWarnings',  writes: false, gating: false },
-  { id: 'items',            stage: 'structure',   proves: 'probe.items',           writes: false, gating: false },
-  { id: 'live-ingest',      stage: 'live',        proves: 'probe.liveIngest',      writes: false, gating: true },
-  { id: 'live-removal',     stage: 'live',        proves: 'probe.liveRemoval',     writes: false, gating: false },
-  { id: 'declarations',     stage: 'forecast',    proves: 'probe.declarations',    writes: false, gating: false },
-  { id: 'forecast',         stage: 'forecast',    proves: 'probe.forecast',        writes: false, gating: false },
-  { id: 'actuate-declared', stage: 'closed-loop', proves: 'probe.actuateDeclared', writes: false, gating: true },
-  { id: 'actuate-effect',   stage: 'closed-loop', proves: 'probe.actuateEffect',   writes: true,  gating: false }
-]
-
-/** 프로브 한 건의 결과. `ran: false` = 돌리지 않았다(실패가 아니다). */
-export interface ProbeResult {
-  id: ProbeId
-  ran: boolean
-  /**
-   * 이 대상에 **해당하지 않는다**. 통과도 실패도 미측정도 아닌 네 번째 값이다.
-   *
-   * 시뮬레이션 트윈에 라이브 프로브를 들이대면 빨간 칸이 생기는데 그건 결함이 아니다 — 시뮬은 원천에서
-   * 받는 것이 없다. 레퍼런스 없이 템플릿으로 세운 트윈에는 옮겨 온 마스터가 없으므로 「못 옮긴 값」도 없다.
-   * 이걸 통과로 처리하면 없는 능력을 주장하고, 미측정으로 처리하면 영원히 배선을 기다린다.
-   */
-  applicable?: boolean
-  /** 돌렸을 때의 판정. 돌리지 않았으면 무의미하다. */
-  passed?: boolean
-  /** 센 값(자리 수·반출 건수·선언 수 등). 세지 않았으면 없다. */
-  count?: number
-  /** 선언 적재량 프로브만 — `declared`/`total`. */
-  coverage?: { declared: number; total: number }
-  /** 왜 실패했나·왜 건너뛰었나. 언어중립 코드 또는 원문 오류. */
-  detail?: string
-}
-
-const by = (rs: readonly ProbeResult[], id: ProbeId) => rs.find(r => r.id === id)
-/** 돌렸고 셌으면 그 수, 아니면 `null`(모른다). 실패한 프로브의 수를 0 으로 읽지 않는다. */
-/**
- * 센 값은 **판정과 무관한 사실**이다 — `passed` 를 요구하면 「세어서 0 을 얻었다」가 「모른다」와 구별되지 않는다.
- * 그 구분이 이 하네스의 전부이므로 여기서 잃으면 나머지가 무의미하다. 해당 없음만 `null` 이다.
- */
-const counted = (r: ProbeResult | undefined): number | null =>
-  r?.applicable === false ? null : r?.ran && r.count !== undefined ? r.count : null
-/** 돌렸고 셌으면 그 수, 아니면 0. **존재 여부**를 묻는 자리에만 쓴다(모름과 0 을 구별할 필요가 없는 축). */
-const countedOrZero = (r: ProbeResult | undefined): number => counted(r) ?? 0
-
-/**
- * 프로브 결과를 **증거**로 처리한다.
- *
- * 계산 규칙의 정수: **돌리지 않은 프로브는 `null`** 로 간다. 그러면 판정이 그 단계를 달성으로
- * 만들지 않고 `unmeasured` 로 말한다 — 스위트를 절반만 돌리고 초록을 주장할 길이 없다.
- */
-export function foldProbeResults(results: readonly ProbeResult[]): StageEvidence {
-  return {
-    locationCount: countedOrZero(by(results, 'master')),
-    itemCount: countedOrZero(by(results, 'items')),
-    masterWarnings: counted(by(results, 'master-warnings')),
-    /* 해당 없음은 **미측정이 아니다** — 물을 대상이 아닌 축을 판정에서 뺀다. */
-    masterWarningsApplicable: by(results, 'master-warnings')?.applicable !== false,
-    liveIngestTotal: countedOrZero(by(results, 'live-ingest')),
-    removalsObserved: counted(by(results, 'live-removal')),
-    forecastRan: by(results, 'forecast')?.ran === true && by(results, 'forecast')?.passed === true,
-    specCoverage: (() => {
-      const r = by(results, 'declarations')
-      return r?.ran && r.passed && r.coverage ? r.coverage : null
-    })(),
-    actuateCapability: by(results, 'actuate-declared')?.passed === true,
-    correlatedEffectObserved: counted(by(results, 'actuate-effect'))
-  }
-}
-
-/**
- * 지금 돌릴 프로브 — 게이팅과 쓰기 동의를 지킨다.
- *
- * 앞의 게이팅 프로브가 실패했으면 **거기서 멈춘다.** 뒤를 돌려 빨간 칸을 늘리는 것은 정보를 주지
- * 않는다(원인은 이미 앞에 있다). 쓰기 프로브는 `allowWrites` 없이는 목록에 들어오지 않는다.
- */
-export function plannedProbes(results: readonly ProbeResult[], opts: { allowWrites?: boolean } = {}): ProbeId[] {
-  const out: ProbeId[] = []
-  for (const spec of PROBE_SEQUENCE) {
-    if (spec.writes && !opts.allowWrites) continue
-    const prior = by(results, spec.id)
-    if (prior?.applicable === false) continue // 해당 없는 프로브는 계획하지 않는다
-    if (!prior?.ran) out.push(spec.id)
-    if (spec.gating && prior?.ran && prior.passed === false) break
-  }
-  return out
-}
-
-/** 해당 없음으로 판정된 프로브 — 화면이 「왜 회색인가」를 말할 수 있게 사유와 함께 낸다. */
-export function notApplicable(results: readonly ProbeResult[]): { id: ProbeId; detail?: string }[] {
-  return results.filter(r => r.applicable === false).map(r => ({ id: r.id, ...(r.detail ? { detail: r.detail } : {}) }))
-}

package/server/engine/integration-runner.ts

@@ -1,95 +0,0 @@
-/*
- * 실행기 — 모은 사실을 프로브 결과로 옮기고, 단계 판정과 프로파일까지 한 번에 낸다.
- *
- * I/O 는 여기 없다(호출자가 모은다). 그래서 판정 전체가 테스트된다.
- */
-import { PROBE_SEQUENCE, foldProbeResults, notApplicable, plannedProbes, type ProbeId, type ProbeResult } from './integration-probes.ts'
-import { assessStagePath, forbiddenClaims, type StagePath } from './stage-path.ts'
-import { narrowProfile, unknownProfile, type FeedKind, type TargetProfile } from './integration-target-profile.ts'
-
-/** 호출자가 모아 오는 사실. 전부 `null` 이 「모른다」다 — 0 이나 false 로 채우지 않는다. */
-export interface SuiteFacts {
-  /** 이 트윈이 무엇인가. 시뮬은 원천에서 받는 것이 없다(라이브 프로브는 해당 없음). */
-  subject: 'live' | 'sim' | 'stopped' | 'unknown'
-  /** 레퍼런스(원천 어댑터)에서 왔나. 템플릿으로 세운 트윈은 옮겨 온 마스터가 없다. */
-  fromReference: boolean
-  /** `capabilitiesOf(adapter)` — 선언∩구현. */
-  adapterCapabilities: readonly string[]
-  connectOk: boolean | null
-  siteCount: number | null
-  locationCount: number | null
-  itemCount: number | null
-  /** 마지막 동기의 못 옮긴 값 수(`TwinReference.lastWarningCount`). */
-  lastWarningCount: number | null
-  /** 저널 누적 — 재시작에도 남는다(인메모리 계기와 다르다). */
-  journalTotal: number | null
-  /** 저널의 `action='DELETE'` 수 — **반출 관측**. 승격 전 행은 세어지지 않으므로 `null` 이 정직하다. */
-  removalsJournaled: number | null
-  specCoverage: { declared: number; total: number } | null
-  forecastRan: boolean | null
-  feed: FeedKind
-}
-
-export interface SuiteAssessment {
-  results: ProbeResult[]
-  profile: TargetProfile
-  path: StagePath
-  notApplicable: { id: ProbeId; detail?: string }[]
-  forbiddenClaims: string[]
-  /** 다음에 돌릴 프로브 — 쓰기 동의 없이는 쓰기 프로브가 빠진다. */
-  planned: ProbeId[]
-}
-
-const r = (id: ProbeId, o: Partial<ProbeResult>): ProbeResult => ({ id, ran: false, ...o })
-
-/** 값이 있으면 돌린 것으로 보고 판정한다. `null` = 안 돌렸다(실패 아님). */
-const fromNumber = (id: ProbeId, v: number | null, min = 1): ProbeResult =>
-  v === null ? r(id, { ran: false }) : r(id, { ran: true, passed: v >= min, count: v })
-
-export function assessSuite(f: SuiteFacts, opts: { allowWrites?: boolean } = {}): SuiteAssessment {
-  const liveApplies = f.subject !== 'sim'
-  const results: ProbeResult[] = [
-    f.connectOk === null ? r('connect', { ran: false }) : r('connect', { ran: true, passed: f.connectOk }),
-    fromNumber('discover', f.siteCount),
-    fromNumber('master', f.locationCount),
-    /* 레퍼런스 없이 세운 트윈에는 옮겨 온 마스터가 없다 — 「못 옮긴 값」을 물을 대상이 아니다. */
-    f.fromReference
-      ? fromNumber('master-warnings', f.lastWarningCount, 0)
-      : r('master-warnings', { ran: false, applicable: false, detail: 'not-from-reference' }),
-    fromNumber('items', f.itemCount),
-    liveApplies ? fromNumber('live-ingest', f.journalTotal) : r('live-ingest', { ran: false, applicable: false, detail: 'subject-is-simulation' }),
-    liveApplies ? fromNumber('live-removal', f.removalsJournaled, 1) : r('live-removal', { ran: false, applicable: false, detail: 'subject-is-simulation' }),
-    f.specCoverage === null
-      ? r('declarations', { ran: false })
-      : r('declarations', { ran: true, passed: f.specCoverage.declared > 0, coverage: f.specCoverage }),
-    f.forecastRan === null ? r('forecast', { ran: false }) : r('forecast', { ran: true, passed: f.forecastRan }),
-    r('actuate-declared', { ran: true, passed: f.adapterCapabilities.includes('actuate') }),
-    /* 액추에이션은 계약에 아직 없다(ADR-0036). 측정을 만들면 없는 것을 있는 척한다. */
-    r('actuate-effect', { ran: false, detail: 'actuation-not-wired' })
-  ]
-
-  /* 반출을 셌는데 0 이면 「세지 않음」과 구별해 프로브를 실패로 남긴다 — count 0 은 사실이다. */
-  const removal = results.find(x => x.id === 'live-removal')!
-  if (removal.ran && f.removalsJournaled === 0) removal.count = 0
-
-  const profile = narrowProfile(unknownProfile(), {
-    feed: f.feed,
-    multiSite: f.siteCount === null ? null : f.siteCount > 1,
-    write: f.adapterCapabilities.includes('actuate') ? 'command' : 'unknown'
-  })
-
-  const evidence = { ...foldProbeResults(results), subject: liveApplies ? ('live' as const) : ('sim' as const), feed: f.feed }
-  const path = assessStagePath(evidence)
-
-  return {
-    results,
-    profile,
-    path,
-    notApplicable: notApplicable(results),
-    forbiddenClaims: forbiddenClaims(path),
-    planned: plannedProbes(results, opts)
-  }
-}
-
-/** 시퀀스 명세 — 화면이 회색 칸의 이유(해당 없음·미실행)를 나란히 보이도록 함께 낸다. */
-export const SUITE_SPEC = PROBE_SEQUENCE

package/server/engine/integration-target-profile.ts

@@ -1,103 +0,0 @@
-/*
- * 대상 프로파일 — **스위트가 갈리는 근거.**
- *
- * ── 왜 프로파일이 먼저인가 ──────────────────────────────────────────────────
- * 처음 만든 시퀀스는 직선이었다. 모든 대상에게 같은 순서를 강요했고, 그래서 두 방향으로 거짓말을
- * 했다: push 소스에 커서 프로브를 들이대 빨간 칸을 만들고(결함이 아닌데), 반대로 스냅샷 소스에는
- * 반출을 못 본 이유를 「아직 안 돌렸다」로 적었다(구조적으로 못 내는 것인데).
- *
- * 갈림의 근거는 **대상의 성격**이고, 그 성격은 **우리가 정하는 것이 아니라 발견하는 것**이다.
- * 그래서 프로파일의 모든 축은 `'unknown'` 에서 시작해 프로브가 좁힌다. 모르는 축으로는 라우팅하지
- * 않는다 — 모르면 그 축에 걸린 프로브는 「아직 판단할 수 없음」이고, 짐작으로 건너뛰지 않는다.
- *
- * ── 축을 고른 기준 ─────────────────────────────────────────────────────────
- * 실제로 **다른 프로브를 요구하는 것만** 축이 된다. 「벤더 이름」은 축이 아니다(같은 벤더가 REST 도
- * 파일도 준다). 아래 일곱은 각각 적어도 한 프로브의 적용 여부를 바꾼다.
- */
-
-/** 무엇으로 붙나 — 페이지·상한·질의 형태가 여기서 갈린다. */
-export type Transport = 'rest' | 'graphql' | 'db' | 'file' | 'mqtt' | 'opc' | 'unknown'
-
-/**
- * 변화를 어떻게 아나 — **라이브 단계의 성격이 통째로 이 축에 달려 있다.**
- *
- *  · `push`          원천이 밀어 준다(구독·웹훅·큐·CDC). 커서가 필요 없다.
- *  · `delta-poll`    거래 이력을 커서로 읽는다. **커서 정합이 급소다.**
- *  · `snapshot-poll` 현재 상태를 되풀어 읽는다. **반출을 원리적으로 낼 수 없다** — 라이브 단계는
- *                    「아직」이 아니라 **구조적으로 불가**이고, 그 사실을 그대로 말한다.
- *  · `none`          변화를 알 길이 없다(구조 전용 소스).
- */
-export type FeedKind = 'push' | 'delta-poll' | 'snapshot-poll' | 'none' | 'unknown'
-
-/** 물건을 무엇이라 부르나 — 발명해야 하는지가 여기서 갈린다. */
-export type IdentityKind = 'gs1' | 'local' | 'none' | 'unknown'
-
-/**
- * 양을 어떻게 세나 — **개수냐 연속량이냐.**
- *
- * 식품·화학·제약은 KG·L 로 오고, 조립 제조는 대수로 온다. 커널·미러는 둘 다 다루지만(비직렬
- * `MaterialSubLot`), **요구하는 프로브가 다르다**: 연속량이면 단위 어휘와 환산을 반드시 묻고,
- * 직렬이면 그 프로브는 해당 없음이다.
- */
-export type Quantization = 'serial' | 'continuous' | 'mixed' | 'unknown'
-
-/** 이 원천이 겸하는 버티컬 — 둘 이상이면 트윈이 여럿이고 **핸드오버 경계**를 물어야 한다. */
-export type Vertical = 'wms' | 'mes' | 'yms' | 'ems'
-
-/** 밖으로 나가는 문 — 폐루프 프로브의 적용 여부. */
-export type WriteSurface = 'none' | 'command' | 'unknown'
-
-export interface TargetProfile {
-  transport: Transport
-  feed: FeedKind
-  multiSite: boolean | null
-  identity: IdentityKind
-  quantization: Quantization
-  /** 빈 배열 = 아직 모른다(없다는 뜻이 아니다). */
-  verticals: readonly Vertical[]
-  write: WriteSurface
-}
-
-/** 아무것도 모르는 상태 — 스위트는 여기서 시작한다. */
-export function unknownProfile(): TargetProfile {
-  return { transport: 'unknown', feed: 'unknown', multiSite: null, identity: 'unknown', quantization: 'unknown', verticals: [], write: 'unknown' }
-}
-
-/** 이 축을 아직 모르나 — 모르는 축으로는 라우팅하지 않는다. */
-export function isUnknown(p: TargetProfile, axis: keyof TargetProfile): boolean {
-  const v = p[axis]
-  if (axis === 'multiSite') return v === null
-  if (axis === 'verticals') return (v as readonly Vertical[]).length === 0
-  return v === 'unknown'
-}
-
-/**
- * 프로브가 알아낸 것을 프로파일에 반영한다 — **좁히기만 한다.**
- *
- * 이미 알아낸 축을 나중 프로브가 `'unknown'` 으로 덮지 못하게 한다. 스위트는 여러 번 돌고, 뒤에
- * 돌린 프로브가 그 축을 다루지 않는다는 이유로 앞의 발견을 지우면 라우팅이 왕복한다.
- */
-export function narrowProfile(base: TargetProfile, found: Partial<TargetProfile>): TargetProfile {
-  const out: TargetProfile = { ...base }
-  for (const k of Object.keys(found) as (keyof TargetProfile)[]) {
-    const v = found[k]
-    if (v === undefined) continue
-    if (k === 'multiSite') { if (v !== null) out.multiSite = v as boolean; continue }
-    if (k === 'verticals') { const list = v as readonly Vertical[]; if (list.length) out.verticals = [...new Set([...out.verticals, ...list])]; continue }
-    if (v !== 'unknown') (out as any)[k] = v
-  }
-  return out
-}
-
-/**
- * 이 프로파일에서 **라이브가 구조적으로 가능한가.**
- *
- * `snapshot-poll` 은 불가다 — 사라진 것은 그냥 없어지고 `OBSERVE` 만 남는다. 이걸 「아직 반출을 못
- * 봤다」로 적으면 사람이 더 기다리게 되는데, 더 기다려도 오지 않는다. 방식을 바꿔야 한다는 것이 답이다.
- */
-export function liveFeasible(p: TargetProfile): { ok: boolean; reason?: string } {
-  if (p.feed === 'unknown') return { ok: false, reason: 'feed-unknown' }
-  if (p.feed === 'none') return { ok: false, reason: 'no-feed' }
-  if (p.feed === 'snapshot-poll') return { ok: false, reason: 'snapshot-only-feed' }
-  return { ok: true }
-}

package/server/engine/kpi-baseline.ts

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