@things-factory/headless-twin 10.1.278 → 10.1.280

package/server/engine/log.ts

@@ -1,72 +0,0 @@
-/*
- * 트윈 로그의 문 — **모든 줄에 시각을 찍는다.** 순수(프레임워크 의존 없음).
- *
- * ── 왜 필요한가 (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 라
- * 초 단위로는 같은 초 안의 순서를 가릴 수 없다).
- */
-
-/** 두 자리·세 자리 0 채우기 — 형식이 흔들리면 정렬해 읽을 수 없다. */
-const p2 = (n: number) => String(n).padStart(2, '0')
-const p3 = (n: number) => String(n).padStart(3, '0')
-
-/**
- * 지역 시각 + 오프셋 — `2026-08-22T05:54:12.345+09:00`.
- *
- * UTC 로 찍지 않는다: 이 로그를 읽는 사람은 현장의 시각으로 이야기하고, 프레임워크의 다른 줄도
- * 지역 시각이다. 두 줄이 다른 기준이면 나란히 놓고 읽을 수 없다.
- */
-export function stamp(at: Date = new Date()): string {
-  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` 만 찍는다)에서 **오류 없이 사라진다.** 그래서 여기서 문자열로 편다.
- * 오류는 스택까지 — 스택이 없으면 「어디서 났나」를 잃는다.
- */
-export function line(args: unknown[]): string {
-  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`) — 같은 파일에서 걸러 읽는다. */
-export const twinLog = (...args: unknown[]): void => console.log(`${stamp()} info: ${line(args)}`)
-export const twinWarn = (...args: unknown[]): void => console.warn(`${stamp()} warn: ${line(args)}`)
-export const twinError = (...args: unknown[]): void => console.error(`${stamp()} error: ${line(args)}`)

package/server/engine/loop-lag.ts

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

package/server/engine/measured-estimator.ts

@@ -1,91 +0,0 @@
-/*
- * 실측 소요 추정기 — **이력에서 배운 값이 상수·선언값을 이긴다.**
- *
- * 배경(operato-twin design/plans/simulation-spec.md §5-4): 소요시간을 명세로 받을 수 있게 됐지만
- * 명세는 선언이다 — 그 현장에서 실제로 얼마 걸리는지는 저널이 안다. `gap-analytics` 는 지표 수준의
- * 편향만 배웠고(예측값 보정), **공정별 소요를 추정기로 되먹이는 경로는 없었다.**
- *
- * 여기서 하는 일: KPI 폴드가 작업 종류별로 낸 **작업시간(착수→완료) p50** 을 그 종류의 소요로 쓴다.
- * 리드타임(생성→완료)이 아니라 작업시간을 쓰는 이유: 리드타임에는 **대기가 섞여 있고**, 대기는
- * 시뮬레이션이 자원 경합으로 스스로 만들어야 하는 값이다. 대기를 소요에 넣으면 이중 계산이 된다.
- *
- * **평균만 배우면 대기와 병목을 과소평가한다.** 소요가 늘 정확히 같으면 줄이 생기지 않는다 — 현장의
- * 줄은 흔들림에서 나온다. 그래서 p50 만이 아니라 **관측된 퍼짐(p10..p90)** 을 함께 넘기고, 표본은
- * 커널이 자기 난수로 뽑는다(fork 결정성). 양쪽 꼬리를 다 관측에서 가져오는 이유: p90 만 있으면
- * 아래쪽을 위쪽에서 거울처럼 베껴야 하는데 그건 발명이다.
- *
- * 정직 규율:
- *  - 표본이 적으면 쓰지 않는다(`minSamples`). 한두 건의 p50 은 그 현장의 값이 아니다.
- *  - 'unknown' 축은 쓰지 않는다 — 종류를 모르는 기록을 특정 종류의 근거로 삼을 수 없다.
- *  - 퍼짐이 성립하지 않으면(p10 ≥ p90, 또는 0) **퍼짐 없이 평균만** 넘긴다. 없는 흔들림을 만들지 않는다.
- *  - 무엇을 배웠고 무엇을 표본 부족으로 버렸는지 함께 낸다(알리지 않고 일부만 반영하지 않는다).
- */
-
-/** 커널 `DurationEstimate` 와 같은 모양(커널 타입에 의존하지 않기 위해 구조로 맞춘다). */
-export interface MeasuredEstimate {
-  meanMs: number
-  spread?: { distribution: 'triangular'; minMs: number; maxMs: number; modeMs: number }
-}
-
-export interface MeasuredEstimatorResult {
-  estimator?: {
-    estimate(ctx: { kind: string; fromNode: string; toNode: string; resourceKind?: string }): MeasuredEstimate | undefined
-  }
-  /** 작업 종류 → 실측 소요(ms). 추정기가 답하는 종류들. */
-  learned: Record<string, number>
-  /** 퍼짐까지 배운 종류 — 평균만 배운 것과 구별한다(변동 없는 소요는 대기를 과소평가한다). */
-  spreads: Record<string, { minMs: number; maxMs: number }>
-  /** 표본이 모자라 쓰지 않은 종류와 그 건수 — 배우지 못한 것을 밝힌다. */
-  skipped: { kind: string; count: number }[]
-  minSamples: number
-}
-
-/** 기본 표본 하한 — 이보다 적으면 그 종류는 배우지 않는다(작은 표본의 p50 을 현장 값으로 승격 금지). */
-export const DEFAULT_MIN_SAMPLES = 5
-
-/**
- * 작업 종류별 KPI 그룹에서 추정기를 만든다(순수 — DB·커널 모름).
- * `groups` 는 `computeTwinKpi({ groupBy: 'taskKind' })` 의 `groups.items` 를 그대로 넘긴다.
- */
-export function buildMeasuredEstimator(
-  groups: { key: string; workTime?: { count: number; p10Ms?: number; p50Ms: number; p90Ms?: number } }[] | undefined,
-  opts: { minSamples?: number } = {}
-): MeasuredEstimatorResult {
-  const minSamples = opts.minSamples ?? DEFAULT_MIN_SAMPLES
-  const learned: Record<string, number> = {}
-  const spreads: Record<string, { minMs: number; maxMs: number }> = {}
-  const estimates: Record<string, MeasuredEstimate> = {}
-  const skipped: { kind: string; count: number }[] = []
-  for (const g of groups ?? []) {
-    if (!g?.key || g.key === 'unknown') continue
-    const w = g.workTime
-    const count = w?.count ?? 0
-    const p50 = w?.p50Ms ?? 0
-    if (count < minSamples || !(p50 > 0)) { skipped.push({ kind: g.key, count }); continue }
-    const mean = Math.round(p50)
-    learned[g.key] = mean
-    /* 퍼짐은 **관측된 두 꼬리**로만 만든다. 한쪽이라도 없거나 구간이 성립하지 않으면 평균만 넘긴다. */
-    const lo = w?.p10Ms
-    const hi = w?.p90Ms
-    if (typeof lo === 'number' && typeof hi === 'number' && lo > 0 && hi > lo) {
-      const minMs = Math.round(lo)
-      const maxMs = Math.round(hi)
-      spreads[g.key] = { minMs, maxMs }
-      estimates[g.key] = { meanMs: mean, spread: { distribution: 'triangular', minMs, maxMs, modeMs: mean } }
-    } else {
-      estimates[g.key] = { meanMs: mean }
-    }
-  }
-  if (!Object.keys(learned).length) return { learned, spreads, skipped, minSamples }
-  return {
-    learned,
-    spreads,
-    skipped,
-    minSamples,
-    estimator: {
-      estimate(ctx) {
-        return estimates[ctx.kind]
-      }
-    }
-  }
-}

package/server/engine/measured-yield.ts

@@ -1,89 +0,0 @@
-/*
- * 실측 양품률 추정기 — **이력에서 배운 수율이 선언값·상수를 이긴다.**
- *
- * ── 왜 필요했나 (2026-08-19) ────────────────────────────────────────────────
- * 소요시간에는 이력 층이 있었다(`measured-estimator`): 저널이 「그 현장에서 실제로 얼마 걸렸나」를 안다.
- * 수율에는 그 층이 없었다 — 양품률의 기본값은 커널 소스의 상수(0.8)였고, **그 상수가 불량 과다 주목
- * 신호까지 만들었다.** 초기 라인이든 성숙한 라인이든 같은 수로 판정된다는 뜻이다.
- *
- * 그런데 이력을 만들 재료도 없었다: 양품/불량은 설비 누적 카운터(종류를 모른다)와 EPCIS disposition
- * (종류를 모른다)에만 남았다. 그래서 커널이 **판정을 일어난 자리(작업 완료)에 적게** 했고
- * (`TaskStatusDelta.outcome`), 폴드가 축으로 들고(`TaskFacets.outcome`), KPI 가 종류별로 센다
- * (`KpiGroup.quality`). 이 파일은 그 수를 비율로 바꿔 커널 시임에 넣는다.
- *
- * ── 정직 규율 (소요 추정기와 같은 것) ───────────────────────────────────────
- *  - **표본이 적으면 쓰지 않는다**(`minSamples`). 세 건 중 한 건 불량은 「불량률 33%」가 아니다.
- *  - `'unknown'` 축은 쓰지 않는다 — 종류를 모르는 기록을 특정 종류의 근거로 삼을 수 없다.
- *  - **판정이 없는 작업은 분모에 넣지 않는다.** KPI 가 이미 그렇게 세지만(`quality` 는 판정된 것만),
- *    여기서도 `good + scrap` 만 쓴다 — `tasks` 를 분모로 쓰면 이동·체류가 섞여 양품률이 낮게 나온다.
- *  - **0 도 사실이다.** 전부 불량이면 0 을 배운다(그 현장이 그랬다). 「값이 없다」와 구별해 다룬다 —
- *    커널이 `0` 을 받으면 전량 불량으로 굴러가고, 그것이 관측과 같은 결론이다.
- *  - 무엇을 배웠고 무엇을 표본 부족으로 버렸는지 함께 낸다(알리지 않고 일부만 반영하지 않는다).
- */
-
-/** 커널 `YieldEstimator` 와 같은 모양(커널 타입에 의존하지 않기 위해 구조로 맞춘다). */
-export interface YieldEstimatorResult {
-  estimator?: {
-    estimate(ctx: { kind: string }): number | undefined
-  }
-  /** 작업 종류 → 실측 양품률(0..1). 추정기가 답하는 종류들. */
-  learned: Record<string, number>
-  /** 종류별 표본 — 배운 값의 근거 크기(화면·로그가 「몇 건에서 배웠나」를 말할 수 있게). */
-  samples: Record<string, { good: number; scrap: number }>
-  /** 표본이 모자라 쓰지 않은 종류와 판정 건수 — 배우지 못한 것을 밝힌다. */
-  skipped: { kind: string; judged: number }[]
-  minSamples: number
-}
-
-/**
- * 기본 표본 하한 — 판정 20건 미만이면 그 종류는 배우지 않는다.
- *
- * 소요(5건)보다 높게 잡는 이유: 비율은 **드문 사건**을 재는 값이다. 불량률 5% 인 공정에서 20건을 봐도
- * 불량은 한 건이고, 그 한 건이 있고 없음으로 비율이 0% 와 5% 사이를 오간다. 낮게 잡으면 추정기가
- * 이력이라는 이름으로 잡음을 실어 보낸다.
- */
-export const DEFAULT_YIELD_MIN_SAMPLES = 20
-
-/**
- * 작업 종류별 KPI 그룹에서 양품률 추정기를 만든다(순수 — DB·커널 모름).
- * `groups` 는 `computeTwinKpi({ groupBy: 'taskKind' })` 의 `groups.items` 를 그대로 넘긴다.
- */
-export function buildYieldEstimator(
-  groups: { key: string; quality?: { good: number; scrap: number } }[] | undefined,
-  opts: { minSamples?: number } = {}
-): YieldEstimatorResult {
-  const minSamples = opts.minSamples ?? DEFAULT_YIELD_MIN_SAMPLES
-  const learned: Record<string, number> = {}
-  const samples: Record<string, { good: number; scrap: number }> = {}
-  const skipped: { kind: string; judged: number }[] = []
-
-  for (const g of groups ?? []) {
-    if (!g?.key || g.key === 'unknown') continue
-    const good = g.quality?.good ?? 0
-    const scrap = g.quality?.scrap ?? 0
-    const judged = good + scrap
-    /* 판정이 아예 없는 종류는 **건너뛴 것이 아니다** — 품질을 가리지 않는 공정(이동·체류)이 정상이다. */
-    if (judged === 0) continue
-    if (judged < minSamples) {
-      skipped.push({ kind: g.key, judged })
-      continue
-    }
-    learned[g.key] = good / judged
-    samples[g.key] = { good, scrap }
-  }
-
-  const kinds = Object.keys(learned)
-  if (!kinds.length) return { learned, samples, skipped, minSamples }
-
-  return {
-    /*
-     * 시임은 **무상태**다(커널이 fork 할 때 참조를 공유한다 — 소요 추정기와 같은 규약).
-     * 배우지 않은 종류에는 `undefined` 를 답한다: 그러면 커널이 선언값 → 상수로 내려간다.
-     */
-    estimator: { estimate: ({ kind }) => learned[kind] },
-    learned,
-    samples,
-    skipped,
-    minSamples
-  }
-}

package/server/engine/model-basis.ts

@@ -1,162 +0,0 @@
-/*
- * 모델 근거 — **배운 모델에만 보정을 적용하기 위한 비교.**
- *
- * 예측 출력 보정(P3.2 `twinLearnCalibration`)은 "우리 모델이 늘 이만큼 적게 본다" 를 배워 결과를
- * 밀어 준다. 그 학습은 **그때의 모델**을 전제로 한다. 그런데 소요시간 추정기(실측·거리계산)와 공정
- * 명세가 들어오면서 모델 자체가 바뀔 수 있게 됐다 — 모델이 이미 그 편향을 잃었는데 보정이 또 밀어
- * 주면 **이중 보정**이 되어 정확도가 나빠진다. 학습 시점의 accAfter 도 더는 유효하지 않다.
- *
- * 그래서 보정 기록에 **그때 모델의 근거**를 함께 남기고, 적용 전에 지금 근거와 비교한다. 달라졌으면
- * 적용하지 않고 **그 사실을 응답에 싣는다**(오류 없이 사라지면 사용자는 학습이 왜 안 듣는지 모른다).
- *
- * 비교는 **상대 허용오차**로 한다(양자화 지문이 아니라). 실측 p50 은 새 기록이 쌓일 때마다 1~2초씩
- * 흔들리는데, 값을 버킷으로 합쳐 비교하면 버킷 경계에 걸린 값이 1초 드리프트로도 달라져 버린다 —
- * "작은 드리프트로 학습을 무효화하지 않는다" 는 목적을 경계에서 못 지킨다. 비율로 비교하면 어디서든
- * 같은 규칙이 성립한다: 10% 이내는 같은 모델, 30초→47초(57%)는 다른 모델.
- *
- * 재료는 호스트가 아는 것들이다(커널 API 에 의존하지 않아 발행 상태와 무관하게 동작한다):
- *  ① 실측으로 배운 작업 종류별 소요 ② 자원 종류별 속도 ③ 선언된 공정 소요.
- */
-
-/**
- * 허용오차의 **기본값** — 선언이 아무 말도 없을 때만 쓴다.
- *
- * 10% 는 근거에서 나온 수가 아니라 **판단값**이다(그 사실을 적어 두는 것이 이 주석의 목적이다). 그리고
- * 단일 잣대로 쓰면 틀린다 — 우리 트레일러 템플릿이 그것을 보여 준다: 용접은 변동폭을 `PT55M~PT1H35M`
- * (선언 소요 `PT1H10M` 기준 −21%~+36%)로 **스스로 선언한다.** 10% 관문은 그 공정의 **정상 변동조차**
- * "다른 모델" 로 판정해 보정을 끊는다. 반대로 1% 변동도 치명적인 공정에는 10% 가 너무 느슨하다.
- *
- * 그래서 허용오차는 **그 공정이 선언한 변동폭에서 나온다**(§toleranceOf). 선언이 있으면 선언이 이기고,
- * 없을 때만 이 값으로 떨어진다 — 도메인 설정을 새로 만들지 않는다(현장이 이미 말한 것을 읽는다).
- */
-export const BASIS_TOLERANCE = 0.1
-
-export interface ModelBasis {
-  /** 작업 종류 → 실측 소요(ms). `buildMeasuredEstimator().learned`. */
-  measured?: Record<string, number>
-  /** 자원 종류 → 속도(m/s). `buildTravelEstimator().speedsByKind`. */
-  speeds?: Record<string, number>
-  /**
-   * 선언된 공정 — key + ISO 8601 원문(문자열은 그대로 비교한다: 선언이 바뀌면 다른 모델).
-   *
-   * **변동폭도 지문에 든다.** 변동폭이 허용오차를 정하므로(§toleranceOf), 그것이 바뀌었는데 "같은 모델"
-   * 이라고 하면 판정의 잣대가 알리지 않고 바뀐 채로 학습이 이어진다.
-   */
-  declared?: DeclaredOperation[]
-}
-
-/** 선언된 공정 하나 — 소요와 변동폭(모델의 `operations` 원형에서 필요한 만큼만). */
-export interface DeclaredOperation {
-  key: string
-  duration?: string
-  variability?: { distribution?: string; min?: string; max?: string; mode?: string }
-}
-
-/** ISO 8601 기간 → 밀리초. 읽을 수 없으면 `undefined`(짐작해 고치지 않는다). */
-function isoMs(iso?: string): number | undefined {
-  if (!iso) return undefined
-  const m = /^P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:([\d.]+)S)?)?$/.exec(iso)
-  if (!m || !m.slice(1).some(Boolean)) return undefined
-  return ((Number(m[1] ?? 0) * 24 + Number(m[2] ?? 0)) * 60 + Number(m[3] ?? 0)) * 60_000 + Number(m[4] ?? 0) * 1000
-}
-
-/**
- * 작업 종류별 **허용오차** — 그 공정이 선언한 변동폭에서 나온다.
- *
- * 실측 p50 은 정상 변동 안에서 흔들린다. 그 흔들림을 "다른 모델" 로 읽으면 보정이 자꾸 끊기고, 사용자는
- * 학습이 왜 안 듣는지 모른다. 얼마나 흔들리는 것이 정상인지는 **현장이 이미 선언했다**(`variability`).
- *
- * 반폭을 쓴다(`(max − min) / 2 / 소요`) — 중앙에서 어느 쪽으로든 그만큼은 정상이라는 뜻이다.
- * 선언이 없거나 읽을 수 없으면 기본값으로 떨어진다(짐작해 만들지 않는다).
- */
-export function toleranceOf(declared?: DeclaredOperation[]): Record<string, number> {
-  const out: Record<string, number> = {}
-  for (const o of declared ?? []) {
-    if (!o?.key) continue
-    const base = isoMs(o.duration)
-    const min = isoMs(o.variability?.min)
-    const max = isoMs(o.variability?.max)
-    if (!base || min === undefined || max === undefined || !(max > min)) continue
-    const half = (max - min) / 2 / base
-    if (Number.isFinite(half) && half > 0) out[o.key] = half
-  }
-  return out
-}
-
-/** 뜻 있는 수만 남긴다 — 0·음수·NaN 은 모델이 아니다. */
-function clean(map?: Record<string, number>): Record<string, number> {
-  const out: Record<string, number> = {}
-  for (const [k, v] of Object.entries(map ?? {})) if (Number.isFinite(v) && v > 0) out[k] = v
-  return out
-}
-
-function declaredMap(list?: DeclaredOperation[]): Record<string, string> {
-  const out: Record<string, string> = {}
-  for (const o of list ?? []) {
-    if (!o?.key) continue
-    const v = o.variability
-    /* 변동폭까지 한 문장으로 — 순서를 고정해 같은 선언이 같은 문자열이 되게 한다. */
-    const spread = v ? `~${v.distribution ?? '?'}:${v.min ?? ''}..${v.max ?? ''}@${v.mode ?? ''}` : ''
-    if (o.duration || spread) out[o.key] = `${o.duration ?? ''}${spread}`
-  }
-  return out
-}
-
-/** 두 수치 지도가 실질적으로 다른가 — 키 집합이 다르거나, 값이 허용오차를 넘어 다르면 다르다. */
-function numericChanged(a: Record<string, number>, b: Record<string, number>, tolOf: (key: string) => number): boolean {
-  const keys = new Set([...Object.keys(a), ...Object.keys(b)])
-  for (const k of keys) {
-    const x = a[k]
-    const y = b[k]
-    if (x === undefined || y === undefined) return true // 새로 배운 종류·사라진 종류 = 다른 모델
-    const base = Math.max(Math.abs(x), Math.abs(y))
-    if (base > 0 && Math.abs(x - y) / base > tolOf(k)) return true
-  }
-  return false
-}
-
-/**
- * 모델이 달라졌는가 — 보정을 적용하기 전의 관문.
- * 한쪽 근거를 모르면 **판정하지 않는다**(false) — 모르는 것을 근거로 학습을 끊지 않는다.
- */
-export function modelBasisChanged(before?: ModelBasis, after?: ModelBasis, tol: number = BASIS_TOLERANCE): boolean {
-  if (!before || !after) return false
-  /*
-   * 허용오차는 **선언이 정한다** — 배운 시점과 지금의 선언이 다를 수 있으므로 둘 중 **넓은 쪽**을 쓴다.
-   * 좁은 쪽을 쓰면 선언을 넓힌 직후에 정상 변동이 "다른 모델" 로 잡힌다(그 변경 자체는 아래 선언 비교가
-   * 이미 잡으므로, 여기서 또 잡을 필요가 없다).
-   */
-  const tolBefore = toleranceOf(before.declared)
-  const tolAfter = toleranceOf(after.declared)
-  const tolOf = (key: string): number => Math.max(tolBefore[key] ?? tol, tolAfter[key] ?? tol)
-  if (numericChanged(clean(before.measured), clean(after.measured), tolOf)) return true
-  /* 속도는 자원 종류별이고 선언된 변동폭이 없다 — 기본값이 그대로 쓰인다. */
-  if (numericChanged(clean(before.speeds), clean(after.speeds), () => tol)) return true
-  const da = declaredMap(before.declared)
-  const db = declaredMap(after.declared)
-  const keys = new Set([...Object.keys(da), ...Object.keys(db)])
-  for (const k of keys) if (da[k] !== db[k]) return true
-  return false
-}
-
-/**
- * 사람이 읽는 근거 요약 — **로그·진단용**(비교의 근거가 아니다).
- * 지문으로 같음을 판정하지 않는 이유는 위 주석 참조. 두 근거가 왜 달라졌는지 눈으로 보려면 이것을 찍는다.
- */
-export function describeModelBasis(basis?: ModelBasis): string {
-  if (!basis) return 'unknown'
-  const seg: string[] = []
-  const m = Object.entries(clean(basis.measured))
-    .map(([k, v]) => `${k}=${Math.round(v / 1000)}s`)
-    .sort()
-  if (m.length) seg.push(`measured(${m.join(',')})`)
-  const s = Object.entries(clean(basis.speeds))
-    .map(([k, v]) => `${k}=${Math.round(v * 10) / 10}m/s`)
-    .sort()
-  if (s.length) seg.push(`speed(${s.join(',')})`)
-  const d = Object.entries(declaredMap(basis.declared))
-    .map(([k, v]) => `${k}=${v}`)
-    .sort()
-  if (d.length) seg.push(`declared(${d.join(',')})`)
-  return seg.length ? seg.join(' ') : 'kernel defaults only'
-}