@things-factory/headless-twin 10.1.278 → 10.1.280

package/server/engine/declared-stimulus.ts

@@ -1,66 +0,0 @@
-/*
- * **자극은 원본이 선언한다** — 트윈이 아니라.
- *
- * ── 무엇이 났나 (2026-08-19) ────────────────────────────────────────────────
- * 데모의 자극(시나리오)은 시드 코드가 **메모리에만** 실었다: `runtime.scenario.load(...)`. 그래서 트윈을
- * 재기동하면 자극이 사라지고, 구조만 서 있는 트윈이 남는다 — 작업 0·오더 0. 「살아 있는 데모」가
- * **첫 재기동까지만** 사는 것이다(오늘 서버를 여러 번 띄우는 동안 실제로 그 상태였다).
- *
- * ── 왜 트윈에 저장하지 않나 (ADR-0029 · plans/simulator-as-source.md §4) ────
- * 자극은 **원본의 거동**이다: 무엇이 들어오고 무슨 주문이 나는지는 시뮬레이터(원본)가 정하는 사실이고,
- * 트윈은 그것을 반영한다. 트윈에 새 축을 만들면 ADR-0029 가 나중에 걷어내야 하는 표면이 하나 늘고
- * (그 계획서의 §2·§5 가 이미 그 부담을 적어 두었다), 원본에 두면 그 계획의 **첫 조각 앞자리**가 된다:
- * 지금은 호스트가 읽어 커널에 싣고, 나중에 `openLiveFeed` 뒤로 옮기면 같은 선언이 그대로 쓰인다.
- *
- * 그래서 집은 `TwinReference.connectionConfig.scenario` — 어댑터별 설정 자리(이미 `simple-json`)다.
- *
- * ── 판정을 순수 함수로 (이 파일) ────────────────────────────────────────────
- * 「이 트윈에 저장된 자극을 실을 것인가」에는 사람이 틀리기 쉬운 갈림이 셋 있다: 미러에 실으면 **현실을
- * 오염**시키고, 잘못된 선언을 실으면 **다음 틱에서 서버가 내려가고**(실제로 그 이력이 있다), 시나리오
- * 엔진이 없는 런타임에 실으면 알리지 않고 아무 일도 없다. 그래서 판정을 값으로 만들고 시험한다.
- */
-
-/** 자극을 실을지 말지 — 그리고 왜. 부르는 쪽은 이 답만 보고 움직인다. */
-export type StimulusPlan =
-  /** 실어라 — 검사를 통과한 선언. */
-  | { action: 'load'; scenario: any }
-  /**
-   * 싣지 않는다 — 그 이유.
-   *  · `none`        — 원본이 자극을 선언하지 않았다(정상: 정적 구조만 반영하는 트윈)
-   *  · `mirror`      — 미러다. 외부 실물이 진실인 트윈에 우리가 자극을 만들면 그것은 현실이 아니다
-   *  · `no-engine`   — 이 런타임에 시나리오 엔진이 없다(관측 구동 커널)
-   *  · `invalid`     — 선언이 커널 규약을 어긴다. **싣지 않고 말한다**(다음 틱에서 터지게 두지 않는다)
-   */
-  | { action: 'skip'; reason: 'none' | 'observed' | 'no-engine' | 'invalid'; detail?: string }
-
-/**
- * 저장된 자극 선언을 읽어 **실을지 판정한다** — 커널 검사기를 그대로 쓴다(규칙을 두 벌로 만들지 않는다).
- *
- * `validate` 는 커널의 `validateScenario` 를 넘긴다(호스트가 커널 타입에 묶이지 않게 함수로 받는다).
- * 검사기가 없으면 **싣지 않는다**: 검사할 수 없는 선언을 태우는 것이 가장 비싼 선택이다(서버가 내려간
- * 이력이 있다).
- */
-export function planStimulus(
-  config: any,
-  runtime: { hasScenarioEngine: boolean; mode?: 'sim' | 'live' },
-  validate?: (scenario: any) => { ok: boolean; errorCode?: string; errorParams?: any } | { ok: false; errorCode: string }
-): StimulusPlan {
-  const scenario = config?.scenario
-  if (!scenario || typeof scenario !== 'object') return { action: 'skip', reason: 'none' }
-  /* 관측 트윈을 먼저 막는다 — 「엔진이 없다」로 답하면 이유가 흐려진다(애초에 실을 수 없는 트윈이다). */
-  if (runtime.mode === 'live') return { action: 'skip', reason: 'observed' }
-  if (!runtime.hasScenarioEngine) return { action: 'skip', reason: 'no-engine' }
-  if (!validate) return { action: 'skip', reason: 'invalid', detail: 'no validator available' }
-  const v = validate(scenario)
-  if (!v?.ok) return { action: 'skip', reason: 'invalid', detail: (v as any)?.errorCode ?? 'rejected' }
-  return { action: 'load', scenario }
-}
-
-/**
- * 선언을 원본 설정에 얹는다(순수) — **기존 설정을 지우지 않는다.**
- *
- * 어댑터 설정에는 접속 정보가 함께 산다. 자극을 넣으면서 그 옆을 덮으면 다음 재동기가 원본을 못 찾는다.
- */
-export function withStimulus(config: any, scenario: any): any {
-  return { ...(config ?? {}), scenario }
-}

package/server/engine/energy-topology.ts

@@ -1,189 +0,0 @@
-/*
- * 전력 계통도 — **선언된 것만 그린다.** 순수.
- *
- * ── 왜 필요한가 (2026-08-18) ────────────────────────────────────────────────
- * 분기별 막대는 「어디가 많이 쓰나」에 답하지만 **어디에 걸려 있나**에 답하지 못한다. 실제로 부딪힌
- * 세 가지가 전부 계통 질문이었다:
- *  · 「하위 계량이 덮지 않는 327 kWh」 — 그 몫이 수전 직결 부하인지, 계량 없는 구간인지 표로는 모른다.
- *  · 커넥터는 결선을 모르는 부하를 **수전에 매단다**(정직한 선택). 그런데 그 사실이 화면에 없었다.
- *  · 「계량기를 어디에 더 달아야 하나」 — 어두운 구간이 보여야 답할 수 있다.
- *
- * ── 무엇을 그리지 않나 ─────────────────────────────────────────────────────
- * **보호 계통 단선도(SLD)가 아니다.** 차단기 정격·보호 협조·상(phase)·결선 방식은 모델에 없고, 그럴듯한
- * 단선도를 그리면 갖지 않은 공학적 충실도를 주장하게 된다. 여기서 그리는 것은 **트윈이 선언한 관계**
- * (자리의 계층 + 설비의 소속)와 **계량이 실제로 덮는 범위**뿐이다. 한계는 소비처가 화면에 적는다.
- *
- * ── 알리지 않고 빠뜨리지 않는다 ─────────────────────────────────────────────────
- * 자리를 모르는 설비, 계량기가 없는 자리, 계량이 덮지 않는 몫은 **각자 자기 칸으로** 나온다. 그림에서
- * 사라지면 사용자는 자기 현장이 다 그려졌다고 믿는다.
- */
-import { EMS_LOCATION_TYPES, electricalUpstreamOf } from '@operato/ops-contract'
-
-/** 계통의 한 구간(수전·분기·구역) — 자리 하나가 곧 구간이다. */
-export interface TopologySegment {
-  id: string
-  /** 카탈로그 자리 타입(`incoming`·`feeder`·`submeter-zone`). */
-  type: string
-  label?: string
-  /** 이 자리에 달린 계량 지점 id 들 — 비어 있으면 **어두운 구간**이다(값을 알 길이 없다). */
-  meters: string[]
-  /** 이 구간의 전력량과 근거 — 폴드가 낸 것만 싣는다(우리가 다시 계산하지 않는다). */
-  kWh?: number
-  basis?: 'measured' | 'apportioned'
-  /**
-   * **피크가 찍힌 순간** 이 구간이 얼마였나(kW) — 요금이 걸린 수다.
-   *
-   * 전력량이 큰 구간과 피크를 만든 구간은 다를 수 있다(하루 종일 조금씩 쓰는 부하 vs 잠깐 크게 쓰는 부하).
-   * 그림에 둘을 함께 두면 「어느 분기를 깎아야 피크가 내려가나」가 바로 읽힌다.
-   */
-  peakKW?: number
-  /** 이 자리에 매달린 부하(설비) — 종류를 그대로 싣는다. */
-  loads: { id: string; kind: string }[]
-  /**
-   * 계통 설비(차단기·태양광·축전지) — 부하가 아니라 계통의 일부다.
-   *
-   * `live` 는 **지금 값**이다(구간 값이 아니다): 태양광이 지금 몇 kW 를 만들고, 축전지가 얼마를 내보내며
-   * 충전율이 얼마인가. 원천이 보내 주는 사실이라 우리가 만들지 않는다 — 보내지 않은 필드는 없다.
-   *
-   * 시각(`measuredAt`)을 함께 나른다: 계측이 끊기면 **멈춘 값을 지금 값으로 그리게** 되고, 그것이 화면이
-   * 낼 수 있는 가장 나쁜 거짓이다(값이 그럴듯할수록 위험하다).
-   */
-  gear: {
-    id: string
-    kind: string
-    live?: { generatedKW?: number; exportKW?: number; chargeKW?: number; dischargeKW?: number; soc?: number; measuredAt?: string }
-  }[]
-  children: TopologySegment[]
-}
-
-export interface EnergyTopology {
-  roots: TopologySegment[]
-  /**
-   * 자리를 모르는 설비 — 집이 없거나, 없는 자리를 가리킨다. 숨기면 그림의 설비 수가 모델과 달라진다.
-   */
-  unplaced: { id: string; kind: string }[]
-  /** 계량기가 없는 자리 id 들 — 「여기에 달면 무엇을 알 수 있나」의 답이 되는 목록이다. */
-  unmetered: string[]
-  /**
-   * 결선을 모르는 부하가 매달린 자리 — 커넥터가 「어느 분기가 이 설비에 전기를 주는지 모른다」고 판단해
-   * 수전에 매단 경우다. 그 자리의 몫이 분기로 내려가지 않는 이유가 이것이다.
-   */
-  loadsOnIncoming: number
-}
-
-/**
- * 이 설비의 **지금 값** — 스냅샷에서 그 설비를 찾아 에너지 축의 값만 옮긴다.
- *
- * 종류가 아는 필드만 옮긴다: 태양광에 충전율을 붙이거나 축전지에 발전량을 붙이면, 화면은 그것을 사실로
- * 그리고 사람은 그 설비가 그런 일을 한다고 읽는다(커널이 종류별로 필드를 가려 받는 것과 같은 규율).
- */
-function liveOf(
-  state: readonly any[] | undefined | null,
-  id: string,
-  kind: string
-): { live: NonNullable<TopologySegment['gear'][number]['live']> } | undefined {
-  const e = (state ?? []).find(x => String(x?.id ?? '') === id)
-  if (!e) return undefined
-  const num = (v: unknown): number | undefined => (Number.isFinite(Number(v)) ? Number(v) : undefined)
-  const live: NonNullable<TopologySegment['gear'][number]['live']> = {}
-  if (kind === 'pv-array') {
-    const g = num(e.generatedKW)
-    const x = num(e.exportKW)
-    if (g !== undefined) live.generatedKW = g
-    if (x !== undefined) live.exportKW = x
-  } else if (kind === 'battery') {
-    const soc = num(e.soc)
-    const dis = num(e.dischargeKW)
-    const cha = num(e.chargeKW)
-    if (soc !== undefined) live.soc = soc
-    if (dis !== undefined) live.dischargeKW = dis
-    if (cha !== undefined) live.chargeKW = cha
-  }
-  if (!Object.keys(live).length) return undefined
-  /* 값이 있으면 시각도 함께 — 없으면 붙이지 않는다(모르는 시각을 지금으로 만들지 않는다). */
-  if (e.measuredAt) live.measuredAt = String(e.measuredAt)
-  return { live }
-}
-
-const ELECTRICAL = new Set(EMS_LOCATION_TYPES as readonly string[])
-/** 부하가 아닌 계통 설비 — 이것들의 소비를 부하로 세면 총량이 이중으로 나뉜다. */
-const GEAR = new Set(['meter', 'breaker', 'pv-array', 'battery'])
-
-/**
- * 모델 + 폴드 결과 → 계통 트리.
- *
- * @param model     트윈 모델(자리 계층 `parentId`, 설비 소속 `homeLocation`).
- * @param energy    폴드가 낸 분기별 몫(있으면 노드에 싣는다 — 없으면 값 없이 구조만 그린다).
- */
-export function buildEnergyTopology(
-  model: { locations?: any[]; equipment?: any[] } | undefined | null,
-  energy?: { byFeeder?: { key: string; kWh: number; basis?: 'measured' | 'apportioned'; peakKW?: number }[] } | null,
-  /**
-   * 지금의 설비 상태(스냅샷의 `equipment`) — 발전·저장의 **지금 값**을 기호 옆에 적기 위해서다.
-   *
-   * 없으면 값 없이 구조만 그린다. 여기서 값을 만들지 않는다: 원천이 보내지 않은 것은 모르는 것이다.
-   */
-  equipmentState?: readonly any[] | null
-): EnergyTopology {
-  const locations: any[] = (model?.locations ?? []).filter(n => n?.id && ELECTRICAL.has(String(n.type)))
-  const byId = new Map<string, TopologySegment>()
-  for (const n of locations) {
-    byId.set(String(n.id), {
-      id: String(n.id),
-      type: String(n.type),
-      ...(n.name ? { label: String(n.name) } : {}),
-      meters: [],
-      loads: [],
-      gear: [],
-      children: []
-    })
-  }
-
-  const share = new Map((energy?.byFeeder ?? []).map(f => [f.key, f]))
-  for (const [id, segment] of byId) {
-    const s = share.get(id)
-    if (s) {
-      segment.kWh = s.kWh
-      if (s.basis) segment.basis = s.basis
-      if (typeof s.peakKW === 'number') segment.peakKW = s.peakKW
-    }
-  }
-
-  /* 설비를 자기 자리에 붙인다 — 계량기는 「이 구간을 잰다」는 뜻이라 따로 모은다. */
-  const unplaced: { id: string; kind: string }[] = []
-  let loadsOnIncoming = 0
-  for (const e of (model?.equipment ?? []) as any[]) {
-    if (!e?.id) continue
-    const kind = String(e.kind ?? '')
-    const home = String(e.homeLocation ?? e.homeLocationId ?? '')
-    const at = byId.get(home)
-    if (!at) {
-      /* 전기 계통 밖의 자리에 사는 설비도 여기서는 「자리를 모른다」로 모은다 — 이 그림의 축은 계통이다. */
-      unplaced.push({ id: String(e.id), kind })
-      continue
-    }
-    if (kind === 'meter') at.meters.push(String(e.id))
-    else if (GEAR.has(kind)) at.gear.push({ id: String(e.id), kind, ...(liveOf(equipmentState, String(e.id), kind) ?? {}) })
-    else {
-      at.loads.push({ id: String(e.id), kind })
-      if (at.type === 'incoming') loadsOnIncoming++
-    }
-  }
-
-  /*
-   * 계층을 잇는 것은 **전기 상류**다 — 공간 부모(공장·구역)는 이 축이 아니다. 상류의 뜻은 커널이 읽는다
-   * (옛 세대는 그 안에서 흡수된다) — 여기서 다시 판정하면 화면과 계산이 다른 계통을 말하게 된다.
-   */
-  const roots: TopologySegment[] = []
-  const all = model?.locations ?? []
-  for (const n of locations) {
-    const segment = byId.get(String(n.id))!
-    const up = electricalUpstreamOf(all as any, String(n.id))
-    const parent = up ? byId.get(up) : undefined
-    if (parent && parent !== segment) parent.children.push(segment)
-    else roots.push(segment)
-  }
-
-  const unmetered = [...byId.values()].filter(n => !n.meters.length).map(n => n.id)
-  return { roots, unplaced, unmetered, loadsOnIncoming }
-}

package/server/engine/event-time.ts

@@ -1,96 +0,0 @@
-/*
- * **레코드가 말하는 「언제 일어났나」를 읽는다** — fact 종류마다 칸 이름이 다르다.
- *
- * ── 같은 defect 가 세 번째다 ────────────────────────────────────────────────
- * `canonical-ingest.ts` 가 `eventTime ?? at` **두 이름만** 보고 있었다. 그 주석에 이미 두 번의 사고가
- * 적혀 있다 — 처음엔 `eventTime` 하나만 봐서 energy connector 의 사실 18,150건이 polling 시각으로
- * 찍혔고, 그 다음에 `at` 을 더했다.
- *
- * 세 번째는 `nonconformance.disposition` 이었다.
- *
- * ```
- * [측정함 2026-09-06, mes-line-a backfill 뒤]
- * event_time  2026-09-05 23:50:51    payload decidedAt  2026-09-01T02:50:51.832Z     5일 차이
- * ```
- *
- * ── root cause: 선언과 봉투가 다른 이름을 쓴다 ──────────────────────────────
- * 운영 레코드의 봉투 시각은 `at` 이다(`OperationalRecordEnvelopeFields`). 그런데 처분 fact 는 자기
- * 시각을 **payload 의 `decidedAt`** 에 싣는다 — contract 가 그 자리에 required 로 선언했고 plant 도
- * 맞게 보낸다. 읽는 쪽에 그 이름이 없어서 `defaultEventTime`(= ingest 시각)으로 떨어졌다.
- *
- * ── push 경로에서는 안 보인다 ───────────────────────────────────────────────
- * 사실이 나자마자 보내면 ingest 시각과 event 시각이 몇 초 차이다. backfill 이 그 간격을 벌려서
- * 드러냈다 — **backfill 이 만든 defect 가 아니라 원래 있던 것이 보인 것**이다.
- *
- * ── 이름을 늘리는 것으로는 안 끝난다 ────────────────────────────────────────
- * 다음 fact 종류가 또 다른 이름을 쓰면 같은 자리를 밟는다. 그래서 두 가지를 함께 한다.
- *
- * ```
- * 1  종류마다의 칸 이름을 한 표에 둔다     새 종류를 더할 때 여기가 눈에 띈다
- * 2  못 읽으면 그 수를 낸다                조용히 ingest 시각으로 떨어지지 않는다
- * ```
- *
- * 종류 판정은 **contract 의 것을 부른다**(`operationalKindOf`). 여기서 다시 짐작하면 두 곳이 다른
- * 답을 내고, 그때 어느 쪽이 맞는지 아무도 모른다.
- */
-import { operationalKindOf } from '@operato/ops-contract'
-
-/**
- * 운영 fact 종류가 자기 시각을 싣는 칸 — 봉투의 `at` 이 없을 때 읽는다.
- *
- * 새 종류가 자기 시각을 payload 에 실으면 여기 한 줄을 더한다.
- */
-export const KIND_TIME_FIELD: Record<string, string> = {
-  /* `DispositionFact.decidedAt` — contract 가 required 로 선언했다. */
-  disposition: 'decidedAt'
-}
-
-/*
- * `equipment-period` 는 일부러 안 넣는다. 그 fact 의 봉투 시각은 **구간의 끝**이고(그때 성립한다),
- * `recordTime` 은 「그 구간을 언제 적었나」다. 둘이 갈려 있어야 늦게 적은 구간이 늦게 일어난 것으로
- * 읽히지 않는다 — contract 가 그 판단을 이미 적어 두었다.
- */
-
-function iso(v: unknown): string | undefined {
-  return typeof v === 'string' && v.trim() ? v : undefined
-}
-
-/**
- * 이 레코드가 말하는 시각. **못 읽으면 `undefined`** — 여기서 지금 시각으로 채우지 않는다.
- *
- * 보는 순서는 공통 이름이 먼저다. connector 가 봉투 층에서 시각을 실어 주면 그것이 그 레코드에 대한
- * 가장 바깥의 판단이고, 종류마다의 칸은 그것이 없을 때 읽는다.
- */
-export function factEventTime(record: unknown): string | undefined {
-  const r = record as any
-  const common = iso(r?.eventTime) ?? iso(r?.at)
-  if (common) return common
-
-  const kind = operationalKindOf(record)
-  const named = kind ? KIND_TIME_FIELD[kind] : undefined
-  return named ? iso(r?.[named]) : undefined
-}
-
-/**
- * 시각을 못 읽은 레코드를 종류별로 센다 — **조용히 ingest 시각으로 떨어진 것들.**
- *
- * 오류가 아니다. 절대값 snapshot 관측은 원본의 갱신 시각이 아니라 polling 순간이 맞는 시각이라
- * (「어제 값을 오늘 봤다」는 「어제 일어났다」가 아니다) 여기 세어지는 것이 정상이다.
- *
- * 다만 그 수가 어디에도 안 남으면 `event_time == created_at` 이 유일한 단서가 되고, 그것은 우연히
- * 같은 것과 구별되지 않는다.
- */
-export function undatedByKind(records: readonly unknown[]): Record<string, number> {
-  const out: Record<string, number> = {}
-  for (const r of records) {
-    if (factEventTime(r) !== undefined) continue
-    const kind = operationalKindOf(r) ?? ((r as any)?.type as string) ?? '(종류 모름)'
-    out[kind] = (out[kind] ?? 0) + 1
-  }
-  return out
-}
-
-/** 표에 있는 종류인데 시각을 못 읽었다 — 그것은 실제로 결함이다. */
-export function shouldHaveTime(kind: string): boolean {
-  return kind in KIND_TIME_FIELD
-}

package/server/engine/index.ts

@@ -1,51 +0,0 @@
-export * from './twin-engine.js'
-export * from './canonical-ingest.js'
-export * from './kpi-fold.js'
-export * from './property-effects.js'
-export * from './kpi-baseline.js'
-/* 지표 정본 표(TWIN_METRIC)·목표 판정 — 소비처(twin-ai 등)가 지표 이름을 다시 열거하지 않게. */
-export * from './kpi-target.js'
-export * from '@things-factory/headless-twin/dist-shared/kpi-broadcast.js'
-/* 집약 채널 태그(접두사 + 트윈별 태그 생성) — 소비처가 문자열을 다시 적지 않게 내보낸다. */
-export * from '@things-factory/headless-twin/dist-shared/entity-delta.js'
-/* 공간 계층의 단계 — 씬 표현·성과 카드·AI 가 같은 목록을 쓴다. */
-export * from '@things-factory/headless-twin/dist-shared/twin-level.js'
-/* 부하 계기판 — 어떤 작업이 이벤트 루프를 얼마나 쓰는지. */
-export * from './load-meter.js'
-export * from './loop-lag.js'
-/* 런타임 레지스트리 키 규약 — 소비처(다른 키 캐시·테스트)가 `:` 를 다시 적지 않게 함께 내보낸다. */
-export * from './runtime-key.js'
-export * from './kpi-query.js'
-export * from './spec-coverage.js'
-export * from './travel-estimator.js'
-export * from './measured-estimator.js'
-export * from './model-basis.js'
-export * from './live-feed-registry.js'
-/* 동기화 건강 — 「이 트윈이 현장과 맞춰지고 있나」. 판정·추이·사유·표본. */
-export * from './ingest-health.js'
-/* 로컬 선언(현장·트윈) — 소비처(twin-ai 도구)가 명세·검사 규칙을 다시 적지 않게. */
-export * from './local-declarations.js'
-export * from './operation-basis.js'
-export * from './measured-yield.js'
-export * from './declared-stimulus.js'
-export * from './integration-coverage.js'
-
-/*
- * 사실의 정체(identity)와 시각을 판단하는 함수들.
- *
- * 모듈 전체를 export 하지 않고 이 둘만 내보낸다. `FactDeduper` 같은 상태를 가진 클래스는 커널
- * 안에서만 쓰여야 하고, 밖에서 인스턴스를 따로 만들면 중복 판단 기억이 두 벌이 된다.
- *
- * 밖에서 이 둘이 필요한 이유는 하나다 — 저널에 앉은 사실이 제대로 된 정체와 시각을 가졌는지
- * 확인할 때, 유입할 때와 **똑같은 함수로** 판단해야 하기 때문이다. 확인하는 쪽이 규칙을 다시
- * 구현하면 두 규칙이 어긋나는 날 확인이 조용히 통과한다.
- */
-export { factIdentity } from './ingest-dedupe.js'
-
-/*
- * `shouldHaveTime` is the part that matters outside: it separates "this record legitimately has no
- * time of its own" (a snapshot observation — the polling moment IS the right time) from "the kind
- * declares a time field and we could not read it", which is a real defect. Anything checking the
- * journal must use this split rather than inventing its own, or it reports healthy rows as broken.
- */
-export { factEventTime, shouldHaveTime, undatedByKind } from './event-time.js'

package/server/engine/ingest-dedupe.ts

@@ -1,24 +0,0 @@
-/*
- * Moved to `@things-factory/ingest`.
- *
- * ── Why this file is now two lines (2026-09-09) ───────────────────────────
- * When the `ingest` module was created, this judgement was reported as moved there. It was
- * copied: identical text in both places, twenty callers here and none there. A module published
- * with a copy nobody uses is the "same machine twice" this platform keeps warning other lanes
- * about, and it was mine.
- *
- * `ingest` is the home, because the module exists so that wms, yms and ems can use the same
- * judgement — that was the instruction it was built on. The file has no imports, so it lives in
- * that package's `shared/` and the flow badge on the screen reads the same one.
- *
- * ── Why the dependency in this direction is acceptable ───────────────────
- * A kernel host depending on a product module is normally the direction the approval gateway
- * exists to avoid, because that module drags an org chart and screens with it. Measured here it
- * does not: `ingest` depends on `shell` and `auth-base`, and this package already depends on
- * both. The deep specifier also means the barrel — and with it the entity and the client — is
- * never loaded.
- *
- * This re-export stays so the twenty call sites keep their import path. Its only job is to say
- * where the concept lives.
- */
-export * from '@things-factory/ingest/dist-shared/ingest-dedupe.js'

package/server/engine/ingest-health.ts

@@ -1,24 +0,0 @@
-/*
- * Moved to `@things-factory/ingest`.
- *
- * ── Why this file is now two lines (2026-09-09) ───────────────────────────
- * When the `ingest` module was created, this judgement was reported as moved there. It was
- * copied: identical text in both places, twenty callers here and none there. A module published
- * with a copy nobody uses is the "same machine twice" this platform keeps warning other lanes
- * about, and it was mine.
- *
- * `ingest` is the home, because the module exists so that wms, yms and ems can use the same
- * judgement — that was the instruction it was built on. The file has no imports, so it lives in
- * that package's `shared/` and the flow badge on the screen reads the same one.
- *
- * ── Why the dependency in this direction is acceptable ───────────────────
- * A kernel host depending on a product module is normally the direction the approval gateway
- * exists to avoid, because that module drags an org chart and screens with it. Measured here it
- * does not: `ingest` depends on `shell` and `auth-base`, and this package already depends on
- * both. The deep specifier also means the barrel — and with it the entity and the client — is
- * never loaded.
- *
- * This re-export stays so the twenty call sites keep their import path. Its only job is to say
- * where the concept lives.
- */
-export * from '@things-factory/ingest/dist-shared/ingest-health.js'

package/server/engine/integration-coverage.ts

@@ -1,147 +0,0 @@
-/*
- * **원본의 표면 중 얼마를 분류했나** — 순수(import 없음).
- *
- * ── 왜 이 축이 생겼나 (2026-08-20) ──────────────────────────────────────────
- * 탐침 열한 개는 「이 단계가 되나」를 묻는다. `live-ingest` 는 **레코드 한 건이 통과하면 초록**이다.
- * 그래서 재고만 읽는 커넥터에도 「라이브 통과」가 나왔고, 그 사이 원본의 `production_input`(무엇으로
- * 무엇을 만들었나 · 실제 투입량 · 선언된 필요량)과 오더 네 종류와 팔레트가 읽히지 않고 있었다.
- *
- * 그것들은 대화에서 하나씩 「아차」로 드러났다. 그 방식은 반복된다 — 빠진 것을 기억으로 찾기 때문이다.
- * 그래서 축을 하나 더 둔다: **원본이 내놓는 표면을 세고, 그 각각을 커넥터가 무엇으로 처리하는지 적는다.**
- *
- * ── 규율 ────────────────────────────────────────────────────────────────────
- * 표면 목록은 **원본에서 얻는다**(GraphQL 인트로스펙션 등). 커넥터가 손으로 적은 목록으로 세면 같은
- * 눈먼 자리를 그대로 물려받는다 — 내가 잊은 표는 목록에도 없다.
- *
- * 「읽지 않는다」는 결론은 **정당할 수 있다.** 파생 표(집계·추적)나 우리 어휘에 자리가 없는 것을 읽지
- * 않는 것은 결함이 아니다. 결함은 **분류하지 않은 것**이다 — 그것은 생각한 적이 없다는 뜻이다.
- *
- * 그래서 판정은 「전부 읽었나」가 아니라 **「전부 판단했나」** 다.
- */
-
-/**
- * 표면 하나를 커넥터가 무엇으로 처리하는가 — **각 낱말에 적용 가능한 기준과 조치할 사람이 있다.**
- * 기준이 없으면 분류가 느낌이 되고, 조치자가 없으면 표를 읽어도 누가 움직일지 알 수 없다.
- *
- *  · `read`      — **지금 커넥터가 질의한다.** 기준: 커넥터 코드에 그 질의 이름이 있다(확인 가능).
- *                  조치자: 없음(완료분).
- *
- *  · `todo`      — **실려야 하는 사실인데 아직 안 읽는다.** 기준 셋을 다 만족: ① 원본에 읽을 길이
- *                  있다 ② 우리 어휘에 담을 자리가 있다 ③ 아직 안 읽는다. 조치자: **커넥터**.
- *
- *  · `blocked`   — **실려야 하고 담을 자리도 있는데 원본이 읽을 길을 주지 않는다.** 기준: 목록 질의가
- *                  없거나, 있어도 필수 인자 때문에 전역으로 읽을 수 없다. 조치자: **원본 쪽**.
- *                  `todo` 와 한 칸에 두지 않는 이유가 이것이다 — 움직여야 하는 사람이 다르다.
- *
- *  · `no-home`   — **원본에 길은 있는데 그 사실이 상태로 남을 자리가 없다.** 기준은 어휘가 아니라
- *                  **상태에 반영하는 것**이다 — 이벤트 어휘에 통과할 자리가 있어도 상태에 반영되지
- *                  않으면 사실은 남지
- *                  않는다(오히려 더 나쁘다: 검증을 통과하므로 실은 줄 알고 잃는다).
- *                  조치자: **커널·아키텍처** — 반영할 것인지 판단해야 한다.
- *                  냉장 온도가 그 예다. EPCIS `SensorElement`·`sensorReport` 는 이미 있고 검증기도
- *                  본다. **소비하는 곳이 0 이다.** 그러므로 「어휘에 자리가 없다」가 아니라 「상태에
- *                  반영하는 곳이 없다」가 정확하고, 할 일도 자리 만들기가 아니라 그 반영이다.
- *                  **「중요하지 않다」가 아니다.** 오히려 중요한데 못 담는다는 뜻이고, 그래서 판단이
- *                  필요하다. 냉장 온도가 그 예다 — 식품에서 일급 사실인데 계량 어휘가 에너지 전용이다.
- *
- *  · `derived`   — **원본이 다른 표에서 계산해 내놓는 값.** 기준: 그 질의의 결과가 우리가 읽는(또는
- *                  읽을) 사실로부터 계산된다. 읽으면 **같은 수를 두 곳에서 만들게 되고**, 두 수가
- *                  갈리면 어느 것을 믿을지 알 수 없다. 조치자: 없음 — 읽지 않는 것이 정답.
- *
- *  · `duplicate` — **같은 사실을 다른 문으로 내놓는 것.** 기준: 목록 질의로 이미 읽는(또는 읽을) 그
- *                  사실의 단건 드릴다운이다. 계산된 값이 아니므로 `derived` 와 다르고, 관심 밖이
- *                  아니므로 `out-of-scope` 와도 다르다. 조치자: 없음.
- *
- *  · `out-of-scope` — **공장의 상태나 활동이 아니다.** 기준: 그 사실이 자리·물건·설비·사람·작업·
- *                  오더 어디에도 해당하지 않는다(사용자 계정·세무·거래처 마스터). 조치자: 없음.
- *
- * 「읽지 않는다」는 결론은 정당할 수 있다(`derived`·`duplicate`·`out-of-scope`). 결함은 **분류하지
- * 않은 것**이다 — 그것은 생각한 적이 없다는 뜻이다. 그래서 판정은 「전부 읽었나」가 아니라
- * **「전부 판단했나」** 다.
- */
-export type Disposition = 'read' | 'derived' | 'duplicate' | 'no-home' | 'out-of-scope' | 'blocked' | 'todo'
-
-/** 표면 하나에 대한 판단 — **이유가 필수다.** 이유 없는 분류는 분류한 척이다. */
-export interface SurfaceRuling {
-  disposition: Disposition
-  /** 왜 그렇게 정했나. 사람이 읽는 한 문장. */
-  why: string
-}
-
-export interface CoverageInput {
-  /** 원본이 실제로 내놓는 표면 — **원본에서 얻은 것.** 커넥터가 적은 목록이 아니다. */
-  sourceSurface: readonly string[]
-  /** 커넥터의 판단표. */
-  rulings: Readonly<Record<string, SurfaceRuling>>
-}
-
-export interface CoverageReport {
-  /** 원본 표면 수. */
-  total: number
-  /** 분류된 수. */
-  classified: number
-  /** **분류하지 않은 표면** — 생각한 적 없는 것. 이 목록이 비어야 한다. */
-  unclassified: string[]
-  /** 판단표에는 있는데 원본에 없는 것 — 원본이 바뀌었거나 이름을 잘못 적었다. */
-  stale: string[]
-  byDisposition: Record<Disposition, string[]>
-  /** 실어야 하는데 아직 아닌 것. 초록을 막지는 않지만 **세어 보여야** 한다. */
-  todo: string[]
-  /** 원본이 길을 주지 않아 막힌 것 — 이 목록이 곧 **원본 쪽 선결 과제**다. */
-  blocked: string[]
-}
-
-const DISPOSITIONS: Disposition[] = ['read', 'derived', 'duplicate', 'no-home', 'out-of-scope', 'blocked', 'todo']
-
-export function assessCoverage(input: CoverageInput): CoverageReport {
-  const surface = [...new Set(input.sourceSurface)].sort()
-  const byDisposition = DISPOSITIONS.reduce(
-    (acc, d) => ((acc[d] = []), acc),
-    {} as Record<Disposition, string[]>
-  )
-  const unclassified: string[] = []
-
-  for (const name of surface) {
-    const r = input.rulings[name]
-    /* 이유가 없으면 분류로 세지 않는다 — 낱말만 채운 것을 판단으로 세면 이 축이 무의미해진다. */
-    if (!r || !DISPOSITIONS.includes(r.disposition) || !r.why?.trim()) {
-      unclassified.push(name)
-      continue
-    }
-    byDisposition[r.disposition].push(name)
-  }
-
-  const known = new Set(surface)
-  const stale = Object.keys(input.rulings)
-    .filter(k => !known.has(k))
-    .sort()
-
-  return {
-    total: surface.length,
-    classified: surface.length - unclassified.length,
-    unclassified,
-    stale,
-    byDisposition,
-    todo: byDisposition.todo,
-    blocked: byDisposition.blocked
-  }
-}
-
-/**
- * 한 줄 요약 — 화면과 로그가 같은 문장을 쓰도록.
- *
- * **「전부 읽었다」고 말하지 않는다.** 말하는 것은 「전부 판단했다」다. 그리고 분류하지 않은 것이 남아
- * 있으면 그 수를 앞세운다 — 그것이 이 축의 유일한 목적이다.
- */
-export function coverageLine(r: CoverageReport): string {
-  if (r.unclassified.length) {
-    const head = r.unclassified.slice(0, 5).join(', ')
-    const more = r.unclassified.length > 5 ? ` +${r.unclassified.length - 5}` : ''
-    return `${r.unclassified.length}/${r.total} surface(s) not yet judged — ${head}${more}`
-  }
-  const read = r.byDisposition.read.length
-  const parts = [`${read} read`]
-  if (r.todo.length) parts.push(`${r.todo.length} still to carry`)
-  if (r.blocked.length) parts.push(`${r.blocked.length} blocked at the source`)
-  return `all ${r.total} surface(s) judged; ${parts.join(', ')}`
-}