@things-factory/headless-twin 10.0.5 → 10.0.7

package/server/engine/kpi-query.ts

@@ -16,12 +16,16 @@
  */
 import { Between, In } from 'typeorm'
 
+import { hierarchyOf } from '@operato/twin-kernel'
+
 import { getRepository } from '@things-factory/shell'
 
 import { TwinEvent } from '../service/twin-event/twin-event.js'
 import { TwinInstance } from '../service/twin-instance/twin-instance.js'
 import { TwinArea } from '../service/twin-space/twin-area.js'
 import { TwinSpace } from '../service/twin-space/twin-space.js'
+import { TwinTarget } from '../service/twin-target/twin-target.js'
+import { judgeTargets, judgeGroupTargets, scopedTargets, type ScopedTargets, type TargetVerdict } from './kpi-target.js'
 import { TwinEngine } from './twin-engine.js'
 import {
   crossGroups,
@@ -118,6 +122,14 @@ export interface TwinKpiOutput extends Omit<Partial<KpiResult>, 'window'> {
   scope: { spaceId?: string; instanceIds: string[]; realityModes: string[] }
   /** 구간별 값(요청했을 때만) — 추세를 그리기 위한 최소 정보. */
   buckets?: { fromTime: string; toTime: string; tasks: number; orders: number; workP50Ms: number }[]
+  /**
+   * **목표 대비 판정** — 숫자를 판단으로 바꾸는 값(§kpi-target).
+   *
+   * 목표가 걸린 지표만 들어온다. 목표가 없거나 그 구간에 값이 없는 지표는 **여기 나타나지 않는다** —
+   * 전부 "목표 없음" 으로 채우면 화면이 회색 노이즈가 되고, 없는 값을 0 으로 놓으면 "목표 크게 미달"
+   * 이라는 없는 사실이 만들어진다.
+   */
+  targets?: TargetVerdict[]
   /**
    * 비교 구간(요청했을 때만) — 같은 규칙·같은 길이로 접은 앞 구간과의 차이.
    *
@@ -159,24 +171,94 @@ type KpiGroupOut = NonNullable<KpiResult['groups']>['items'][number] &
   Partial<Pick<CrossedGroup, 'prevTasks' | 'deltaTasks' | 'deltaWorkP50Ms' | 'isNew'>>
 
 /**
- * 노드 → 구역 지도. **저널에는 구역이 없다**(노드까지만 있다) — 보드 정의의 `nodes[].parentId` 가
- * 마스터 계층에서 온 소속 구역이다. 기동하지 않은 트윈도 보드는 남아 있어 이 경로가 가장 튼튼하다.
+ * 노드 → 구역 지도. **저널에는 구역이 없다**(노드까지만 있다) — 보드 정의의 `locations[].parentId` 가
+ * 마스터 계층에서 온 소속이다. 기동하지 않은 트윈도 보드는 남아 있어 이 경로가 가장 튼튼하다.
+ *
+ * **한 홉만 보면 안 된다.** `parentId` 는 구역일 수도 있고 중간 단(라인·셀)일 수도 있다. 라인이 끼면
+ * 한 홉짜리 코드는 "구역이 LINE-1" 이라고 답하고, 그 id 는 구역 목록에 없으므로 그 아래 스테이션이
+ * **집계에서 조용히 빠진다**(에러 없이 틀린 숫자). 그래서 커널 `hierarchyOf` 로 사슬을 끝까지 걷는다 —
+ * 걷는 규칙은 커널에 한 벌뿐이고 소비처는 그것만 부른다.
+ */
+/**
+ * 교대 축의 재료 — **교대 선언과 현장의 시각 기준.**
+ *
+ * 저널에는 시각만 있고 교대가 없다(일부러 그렇게 뒀다 — 교대는 파생이라 찍어 두면 나중에 교대 시간을
+ * 고쳤을 때 과거가 옛 구분으로 굳는다). 그래서 폴드가 계산할 재료를 여기서 모은다.
+ *
+ * 선언의 출처는 **보드의 설비**다. 여러 설비가 서로 다른 교대를 가질 수 있지만, 축은 하나여야 하므로
+ * **가장 많이 쓰이는 선언 한 벌**을 쓴다 — 3교대 공장은 전 설비가 같은 교대이므로 이것이 곧 정답이고,
+ * 자원마다 교대가 다른 현장에서는 이 축이 거칠다는 뜻이다(그 사실을 여기 적어 둔다).
  *
- * 구역 이름은 `TwinArea` 에 따로 있다 — id 만 보여주면 사용자가 무엇인지 모른다.
+ * 시각 기준은 보드에 실려 있다(`utcOffsetMinutes` — 공간이 갖는 값을 기동 시 호스트가 풀어 넣는다).
+ * 없으면 UTC 로 읽고, 그 기본값은 커널 계약에 밝혀져 있다.
  */
-async function nodeAreaMap(
+/**
+ * 이 범위에 걸린 운영 목표 — **좁은 선언이 넓은 선언을 덮는다.**
+ *
+ * 공간 전체 목표 위에 인스턴스 목표를 얹을 수 있어야 예외를 표현할 수 있다("이 라인만 다르다").
+ * 같은 지표에 둘 다 있으면 인스턴스가 이긴다.
+ */
+async function loadTargets(
+  domainId: string,
+  spaceId: string | undefined,
+  instanceIds: string[],
+  axis?: string
+): Promise<ScopedTargets> {
+  /* 조회는 **가져오기만** 한다 — 어느 목표가 이기는지는 순수 함수(`scopedTargets`)가 정한다.
+     그 규칙이 DB 접근 뒤에 있으면 화면을 눌러 봐야만 확인된다(그리고 실제로 확인되지 않았다). */
+  const rows = await getRepository(TwinTarget).find({ where: { domain: { id: domainId } } }).catch(() => [])
+  return scopedTargets(rows, { spaceId, instanceIds, axis })
+}
+
+async function shiftContext(
+  domainId: string,
+  instanceIds: string[]
+): Promise<{ shifts?: any[]; utcOffsetMinutes?: number }> {
+  if (!instanceIds.length) return {}
+  const rows = await getRepository(TwinInstance).find({ where: { domain: { id: domainId }, instanceId: In(instanceIds) } })
+  const tally = new Map<string, { decl: any[]; n: number }>()
+  let utcOffsetMinutes: number | undefined
+  for (const row of rows) {
+    const board = row.board as any
+    if (utcOffsetMinutes === undefined && typeof board?.utcOffsetMinutes === 'number') utcOffsetMinutes = board.utcOffsetMinutes
+    for (const e of (board?.equipment ?? []) as any[]) {
+      const decl = e?.workCalendar
+      if (!Array.isArray(decl) || !decl.length) continue
+      const key = JSON.stringify(decl)
+      const hit = tally.get(key)
+      if (hit) hit.n++
+      else tally.set(key, { decl, n: 1 })
+    }
+  }
+  let best: { decl: any[]; n: number } | undefined
+  for (const v of tally.values()) if (!best || v.n > best.n) best = v
+  return { ...(best ? { shifts: best.decl } : {}), ...(utcOffsetMinutes !== undefined ? { utcOffsetMinutes } : {}) }
+}
+
+async function locationAreaMap(
   domainId: string,
   instanceIds: string[],
   spaceId?: string
-): Promise<{ nodeArea: Record<string, string>; labels: Record<string, string> }> {
-  const nodeArea: Record<string, string> = {}
+): Promise<{ locationArea: Record<string, string>; labels: Record<string, string> }> {
+  const locationArea: Record<string, string> = {}
   if (instanceIds.length) {
     const rows = await getRepository(TwinInstance).find({
       where: { domain: { id: domainId }, instanceId: In(instanceIds) }
     })
     for (const row of rows) {
-      for (const n of ((row.board as any)?.nodes ?? []) as any[]) {
-        if (n?.id && n?.parentId) nodeArea[String(n.id)] = String(n.parentId)
+      const locations = (((row.board as any)?.locations ?? []) as any[]).filter(n => n?.id)
+      if (!locations.length) continue
+      /* 순환은 hierarchyOf 가 던진다 — 한 트윈의 잘못된 계층이 다른 트윈의 집계까지 죽이지 않게 여기서 가둔다. */
+      let h
+      try {
+        h = hierarchyOf({ locations })
+      } catch (e: any) {
+        console.warn(`[twin-kpi] "${row.instanceId}": location hierarchy is broken — area rollup skipped for this twin: ${e?.message}`)
+        continue
+      }
+      for (const n of locations) {
+        const area = h.rollupOf(String(n.id))
+        if (area) locationArea[String(n.id)] = area // 구역 미상은 넣지 않는다 — 없는 구역을 만들지 않는다
       }
     }
   }
@@ -192,7 +274,7 @@ async function nodeAreaMap(
       for (const a of areas) if (a.areaId && a.name) labels[a.areaId] = a.name
     }
   }
-  return { nodeArea, labels }
+  return { locationArea, labels }
 }
 
 /** 이 대상들의 마지막 업무 기록 시각(ISO). 기록이 없으면 null. */
@@ -249,6 +331,17 @@ async function resolveTargets(input: TwinKpiInput): Promise<{ instanceIds: strin
   return { instanceIds, realityModes }
 }
 
+/**
+ * 대상 해소 공개 창구 — **저널 목록 질의도 KPI 와 같은 규칙을 써야 한다.**
+ *
+ * 화면에서 "이 공간" 은 하나의 뜻이어야 한다. 성과 화면과 원장 화면이 각자 co-located 트윈을
+ * 추리면 같은 공간을 보면서 다른 대상 집합을 세게 되고, 두 숫자가 어긋나는 이유를 아무도 설명하지 못한다.
+ */
+export async function resolveTwinTargets(domainId: string, instanceId?: string, spaceId?: string): Promise<string[]> {
+  const { instanceIds } = await resolveTargets({ domainId, instanceId, spaceId } as TwinKpiInput)
+  return instanceIds
+}
+
 /**
  * 시간창 업무 KPI. 창 해소 → 저널 조회 → 순수 폴드.
  *
@@ -294,14 +387,24 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
 
   const { events, capped } = await fetchEvents(input.domainId, instanceIds, fromMs, toMs, lookbackMs)
 
-  /* 구역 축만 이벤트 밖의 지식을 필요로 한다 — 다른 축은 payload 에서 바로 나온다. */
+  /* 구역·교대 축은 **이벤트 밖의 지식**을 필요로 한다 — 다른 축은 payload 에서 바로 나온다. */
   const areaMap =
-    input.groupBy === 'area' ? await nodeAreaMap(input.domainId, instanceIds, input.spaceId) : { nodeArea: {}, labels: {} }
+    input.groupBy === 'area' ? await locationAreaMap(input.domainId, instanceIds, input.spaceId) : { locationArea: {}, labels: {} }
+  const shiftCtx = input.groupBy === 'shift' ? await shiftContext(input.domainId, instanceIds) : {}
   const kpi = foldKpi(events, { fromMs, toMs }, {
     groupBy: input.groupBy,
-    nodeArea: areaMap.nodeArea,
+    locationArea: areaMap.locationArea,
+    ...shiftCtx,
     groupLimit: input.groupLimit
   })
+  /*
+   * 목표를 **폴드 뒤, 그룹 조립 앞**에 읽는다 — 전체 판정과 축별 판정이 같은 목록에서 나와야
+   * 두 곳의 임계가 갈라지지 않는다. 폴드 자체는 목표를 모른다(사실 층과 판정 층의 분리).
+   */
+  const scoped = await loadTargets(input.domainId, input.spaceId, instanceIds, input.groupBy)
+  const verdicts = judgeTargets(kpi, scoped.overall)
+  const groupTargets = scoped.byAxisKey
+
   const window = {
     fromTime: new Date(fromMs).toISOString(),
     toTime: new Date(toMs).toISOString(),
@@ -350,7 +453,8 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
      * 있는데 없다고 말하게 된다). */
     const prev = foldKpi(prevEvents, w, {
       groupBy: input.groupBy,
-      nodeArea: areaMap.nodeArea,
+      locationArea: areaMap.locationArea,
+      ...shiftCtx, // 비교 구간도 **같은 교대 정의**로 접는다(정의가 다르면 축이 어긋난다)
       groupLimit: input.groupBy ? 100 : undefined
     })
     prevCappedFlag = prevCapped
@@ -386,10 +490,16 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
   const groups = kpi.groups
     ? {
         by: kpi.groups.by,
-        items: (crossed?.items ?? kpi.groups.items).map(g => ({
-          ...g,
-          ...(areaMap.labels[g.key] ? { label: areaMap.labels[g.key] } : {})
-        })),
+        items: (crossed?.items ?? kpi.groups.items).map(g => {
+          /* 축의 이 값에 목표가 걸려 있으면 판정을 함께 낸다 — "이 구역만 목표가 다르다" 를
+             표에서 바로 볼 수 있게. 목표가 없는 축값에는 필드를 만들지 않는다. */
+          const gt = judgeGroupTargets(g as any, groupTargets[g.key])
+          return {
+            ...g,
+            ...(areaMap.labels[g.key] ? { label: areaMap.labels[g.key] } : {}),
+            ...(gt.length ? { targets: gt } : {})
+          }
+        }),
         ...(crossed?.disappeared.length
           ? {
               disappeared: crossed.disappeared.map(d => ({
@@ -402,13 +512,23 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
           ? { truncated: kpi.groups.truncated, truncatedTasks: kpi.groups.truncatedTasks ?? 0 }
           : {}),
         ...(input.groupBy === 'area' &&
-        Object.keys(areaMap.nodeArea).length === 0 &&
+        Object.keys(areaMap.locationArea).length === 0 &&
         kpi.groups.items.some(g => g.key === 'unknown')
-          ? { note: 'nodes carry no area (parentId) in this twin — cannot break down by area. this is NOT "no work in areas".' }
+          ? { note: 'locations carry no area (parentId) in this twin — cannot break down by area. this is NOT "no work in areas".' }
           : {})
       }
     : undefined
 
+  /*
+   * 목표 대비 판정 — **사실 계산 뒤에 얹는다.**
+   *
+   * 폴드는 목표를 모른다(사실만 낸다). 목표를 아는 순간 "세는 규칙" 과 "잘했나 판정하는 규칙" 이
+   * 한 함수에 섞이고, 목표가 바뀔 때마다 사실 계산을 건드리게 된다. 그래서 조회 층에서 목표를
+   * 실어 오고, 판정은 순수 함수(`judgeTargets`)가 한다.
+   *
+   * **목표가 없으면 판정하지 않는다** — 필드 자체를 만들지 않는다. 전부 "목표 없음" 으로 채우면
+   * 화면이 회색 노이즈가 되고, 목표가 있는 지표가 묻힌다.
+   */
   /* 폴드가 돌려준 raw 창(ms)은 버린다 — 위의 ISO 창이 사람이 읽을 정본이다. */
   const { window: _rawWindow, groups: _rawGroups, ...rest } = kpi
   return {
@@ -419,6 +539,7 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
     ...rest,
     ...(buckets ? { buckets } : {}),
     ...(groups ? { groups } : {}),
+    ...(verdicts.length ? { targets: verdicts } : {}),
     ...(comparison ? { comparison } : {})
   }
 }

package/server/engine/kpi-target.ts

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

package/server/engine/live-attentions.ts

@@ -6,10 +6,20 @@
  */
 import { deriveAttentions } from '@operato/twin-kernel'
 
-export function withLiveAttentions<S extends { movers?: any[]; nodes?: any[]; orders?: any[]; attentions?: any[] }>(state: S): S {
+export function withLiveAttentions<S extends { equipment?: any[]; locations?: any[]; orders?: any[]; tasks?: any[]; attentions?: any[]; nowTime?: string }>(
+  state: S
+): S {
   if (!state) return state
   return {
     ...state,
-    attentions: deriveAttentions({ movers: state.movers ?? [], nodes: state.nodes ?? [], orders: state.orders ?? [] })
+    /*
+     * 입력을 **시뮬 쪽과 똑같이** 넣는다. 한쪽만 빠지면 같은 공장이 한쪽에서만 막힌 것처럼 보이고,
+     * 그 어긋남은 규칙이 아니라 배선 때문이라 아무 데서도 안 잡힌다(`tasks` 를 빠뜨려 실제로 그럴 뻔했다).
+     */
+    attentions: deriveAttentions(
+      { equipment: state.equipment ?? [], locations: state.locations ?? [], orders: state.orders ?? [], tasks: state.tasks ?? [] },
+      undefined,
+      state.nowTime
+    )
   }
 }

package/server/engine/measured-estimator.ts

@@ -0,0 +1,91 @@
+/*
+ * 실측 소요 추정기 — **이력에서 배운 값이 상수·선언값을 이긴다.**
+ *
+ * 배경(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]
+      }
+    }
+  }
+}