@things-factory/headless-twin 10.0.11 → 10.0.13

package/server/engine/integration-coverage.ts

@@ -0,0 +1,147 @@
+/*
+ * **원본의 표면 중 얼마를 분류했나** — 순수(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(', ')}`
+}

package/server/engine/integration-probes.ts

@@ -0,0 +1,144 @@
+/*
+ * 연결 적합성 하네스 — **통합을 시험 스위트처럼 돌린다.**
+ *
+ * 선언 적합성 하네스 세 벌과 같은 규율을 **연결**에 적용한다: 사실이 조용히 사라지는 것을 막는다.
+ * 다른 점은 대상이 우리 선언이 아니라 **남의 시스템**이라는 것이고, 그래서 두 규칙이 더 붙는다.
+ *
+ *  ① **돌리지 않은 프로브는 「실패」가 아니라 「모른다」다.** 실패로 접으면 사람이 그 빨간 칸을
+ *     없애려고 무엇이든 하게 되고, 모른다로 접으면 **무엇을 아직 모르는지**가 남는다. 판정
+ *     (`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

@@ -0,0 +1,95 @@
+/*
+ * 실행기 — 모은 사실을 프로브 결과로 옮기고, 단계 판정과 프로파일까지 한 번에 낸다.
+ *
+ * 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

@@ -0,0 +1,103 @@
+/*
+ * 대상 프로파일 — **스위트가 갈리는 근거.**
+ *
+ * ── 왜 프로파일이 먼저인가 ──────────────────────────────────────────────────
+ * 처음 만든 시퀀스는 직선이었다. 모든 대상에게 같은 순서를 강요했고, 그래서 두 방향으로 거짓말을
+ * 했다: 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-fold.ts

@@ -32,6 +32,7 @@ import {
   energyIntensity,
   energyOfWindows,
   foldTaskRecords,
+  isOrderTerminal,
   activeShiftAt,
   type ElectricityCost,
   type TariffDeclaration,
@@ -89,6 +90,15 @@ export interface KpiGroup {
   waitTime: DurationStats
   /** 이 축에 붙어 있던 시간의 합(자원 축에서 특히 의미 있다). */
   busyMs: number
+  /**
+   * **품질 판정이 있었던 건수만** 센다 (2026-08-19).
+   *
+   * 판정이 없는 작업(이동·체류·중간 스테이션)은 어느 쪽에도 세지 않는다 — 모름을 양품으로 세면 양품률이
+   * 조용히 100% 로 올라간다. 그래서 `good + scrap` 은 `tasks` 보다 작을 수 있고, 그것이 정상이다.
+   *
+   * 판정이 하나도 없으면 **필드를 만들지 않는다**(0/0 을 「양품률 0%」로 읽히게 두지 않는다).
+   */
+  quality?: { good: number; scrap: number }
 }
 
 export interface KpiResult {
@@ -215,6 +225,33 @@ export interface KpiResult {
    * 조회 구간이 짧아 시작이 잘렸거나 저널이 유실된 경우다. 이 값을 숨기면 평균이 조용히 거짓이 된다.
    */
   unpaired: { leadTime: number; workTime: number }
+  /**
+   * **완료로 세지 않은 오더 상태 낱말의 인구조사** — 낱말 → 창 안에서 그 낱말로 본 건수.
+   *
+   * 「못 읽었다」가 **아니다.** `picking` 처럼 완료가 아닌 낱말이 여기 오는 것은 정상이다. 이 값은
+   * 판정이 아니라 **재료**다: 완료가 0 인데 여기 `{ finished: 2780 }` 이 있으면 원인이 곧 보인다.
+   *
+   * ── 왜 필요한가, 그리고 무엇의 대체가 아닌가 ────────────────────────────────
+   * 이 폴드는 완료를 **동의어 목록**으로 판정한다(`completed`·`fulfilled`·`done`·`finished`). 그 방식은
+   * 원본의 낱말에서 뜻을 **추론**하는 것이고, 이 저장소가 다른 자리에서 거절하는 그것이다
+   * (「선언이 있으면 변환이지만 없으면 발명이다」).
+   *
+   * 실제로 그 대가를 치렀다: `finished` 가 목록에 없어 첫 실 시스템의 완료 오더가 전부 0 이었다.
+   * 그런데 **빈 자리는 이 목록이 아니라 커넥터였다** — 그 커넥터에 상태 표(`WORK_ORDER_STATE`)가
+   * 정의돼 있으면서 오더 경로에서 쓰이지 않았고(로트 경로는 썼다), 원본 낱말이 그대로 흘렀다.
+   * 목록에 `finished` 를 더한 것은 그 사실을 가린 땜빵이었다.
+   *
+   * **정석은 커넥터가 자기 표로 옮기고, 옮길 수 없는 낱말은 세고 넣지 않는 것이다**(재고 처분이 이미
+   * 그 규율로 선다: 「표현할 길이 없는 것은 넣지 않는다」). 그러면 이 폴드는 추론하지 않아도 된다.
+   *
+   * 그러므로 이 값은 **동의어 목록을 늘리는 근거가 아니다.** 목록은 커넥터들이 옮기기 시작하면
+   * 닫힌 어휘로 좁혀야 하고, 그때까지 이 값이 어긋남을 말해 준다. 순서가 중요하다 — 목록을 먼저
+   * 좁히면 아직 옮기지 않는 원본의 완료가 그 순간 0 이 된다.
+   *
+   * 상태를 말하지 않은 사건은 여기 오지 않는다. 그것은 「모르는 낱말」이 아니라 다른 결함이고
+   * (유입 문이 상태를 필수로 받는다) 그 진단은 그 문의 몫이다.
+   */
+  orderStatusNotCounted: Record<string, number>
   /**
    * 소비한 이벤트 수 — **넘겨받은 배열 전체**(창 앞 lookback 포함). 진단용이다.
    *
@@ -517,6 +554,24 @@ function facetKey(rec: CompletionRecord, options: KpiFoldOptions): string {
   }
 }
 
+/**
+ * 이 축의 품질 — **판정이 있었던 것만** 센다(없으면 필드를 만들지 않는다).
+ *
+ * 양품률의 이력이 여기서 나온다: 커널이 작업 완료에 결과를 적고(`TaskStatusDelta.outcome`), 폴드가 축으로
+ * 들고(`TaskFacets.outcome`), 여기서 종류별로 센다. 그 사슬이 없으면 「이 공정의 양품률」은 저널에
+ * 남지 않는다(설비 누적 카운터는 종류를 모른다).
+ */
+function qualityOf(rows: CompletionRecord[]): { quality?: { good: number; scrap: number } } {
+  let good = 0
+  let scrap = 0
+  for (const r of rows) {
+    const o = r.facets.outcome
+    if (o === 'good') good++
+    else if (o === 'scrap') scrap++
+  }
+  return good + scrap > 0 ? { quality: { good, scrap } } : {}
+}
+
 /**
  * 기록을 축으로 묶어 축별 통계를 낸다 — **전체와 같은 규칙**으로(같은 stats 함수, 같은 창).
  *
@@ -543,7 +598,8 @@ function groupRecords(
       leadTime: stats(rows.map(r => r.leadMs).filter((v): v is number => v !== undefined)),
       workTime: stats(rows.map(r => r.workMs).filter((v): v is number => v !== undefined)),
       waitTime: stats(rows.map(r => r.waitMs).filter((v): v is number => v !== undefined)),
-      busyMs: rows.reduce((a, r) => a + (r.workMs ?? 0), 0)
+      busyMs: rows.reduce((a, r) => a + (r.workMs ?? 0), 0),
+      ...qualityOf(rows)
     }))
     .sort((a, b) => b.tasks - a.tasks || (a.key < b.key ? -1 : 1))
 
@@ -601,6 +657,10 @@ export function foldKpi(events: KpiEvent[], window: KpiWindow, options: KpiFoldO
   /* 작업 짝맞춤은 **커널 규칙**으로(중복 구현 금지 — 두 곳에 적으면 같은 저널로 다른 답이 나온다). */
   const { records: tasks } = foldTaskRecords(events.filter(e => e.eventType === 'task.status'))
   let completedOrders = 0
+  /* 완료로 읽지 못한 오더 상태 낱말 → 건수(§`orderStatusNotCounted`). */
+  const orderStatusNotCounted = new Map<string, number>()
+  /* 이미 완료로 센 오더 — 폴링 원본이 같은 종결을 다시 보내도 한 번만 센다. */
+  const completedOrderIds = new Set<string>()
   let seen = 0
   let inWindow = 0
 
@@ -612,11 +672,45 @@ export function foldKpi(events: KpiEvent[], window: KpiWindow, options: KpiFoldO
     const d = e.payload?.data ?? e.payload ?? {}
 
     if (e.eventType === 'order.status') {
-      /* 오더 완료 어휘는 도메인 소유다 — 코어가 강제하지 않는다. 그래서 이름을 하나로 못 박지 않고
-       * 완료로 읽히는 표현을 넓게 받는다(그 밖은 세지 않는다). */
+      /*
+       * **끝났나는 커널이 답한다** (2026-08-23) — `isOrderTerminal`.
+       *
+       * 예전에는 여기서 **동의어 목록**으로 추론했다(`completed`·`fulfilled`·`done`·`finished`).
+       * 그 방식이 낸 대가가 둘이었고 둘 다 조용했다.
+       *
+       *  ① 원본의 낱말이 목록에 없으면 완료가 0 이 된다. 실제로 그랬다 — 첫 실 시스템의 `FINISHED`
+       *     가 빠져 있었고, 그때 목록에 낱말을 더한 것은 진짜 빈 자리(그 커넥터가 자기 상태 표를
+       *     안 쓰고 있었다)를 가린 땜빵이었다.
+       *  ② **시뮬 트윈에서는 언제나 0 이었다.** 시뮬은 오더를 이행하며 `fulfilled` 만 올리고
+       *     `status` 는 바꾸지 않는다 — 낱말로 묻는 판정은 시뮬의 완료를 한 건도 세지 못했다.
+       *
+       * 표준이 그 축을 갈라 두었다: `orders.status` ↔ `RequestState`(표준도 열거하지 않는다)이고,
+       * 「됐나」는 **실적**에서 읽는다(`JobResponse`, 요구는 `SegmentRequirement.Quantity`). 그래서
+       * 판정의 1차 근거는 **양**이고 낱말은 양으로 말할 수 없는 종결(취소·중도 종료)에만 쓴다.
+       */
       const status = String(d.status ?? '').toLowerCase()
-      if (at >= window.fromMs && at <= window.toMs && (status === 'completed' || status === 'fulfilled' || status === 'done')) {
-        completedOrders++
+      const done = isOrderTerminal({ status: d.status, requested: d.requested, fulfilled: d.fulfilled })
+      if (at >= window.fromMs && at <= window.toMs) {
+        /*
+         * **오더당 한 번만 센다.** 폴링하는 원본은 같은 오더의 종결을 여러 주기에 걸쳐 다시 보낼 수
+         * 있고(그것은 결함이 아니라 폴링의 성질이다), 사건마다 세면 처리량이 조용히 부풀려진다.
+         * 작업 쪽은 커널의 짝맞춤이 이미 그 규율을 갖고 있다(「완료는 작업당 하나」) — 오더만 없었다.
+         */
+        if (done) {
+          const id = String(d.orderId ?? '')
+          if (id && !completedOrderIds.has(id)) {
+            completedOrderIds.add(id)
+            completedOrders++
+          } else if (!id) completedOrders++ // 정체를 모르면 셈에서 빼지 않는다(조용히 줄이지 않는다)
+        }
+        /*
+         * **완료로 세지 않은 낱말의 인구조사.** 「못 읽었다」가 아니다 — `picking` 처럼 완료가 아닌
+         * 낱말이 여기 오는 것은 정상이다. 완료가 0 인데 여기 낱말이 쌓여 있으면 원인이 곧 보인다.
+         *
+         * 빈 낱말은 세지 않는다: 상태를 말하지 않은 사건은 다른 결함이고(유입 문이 상태를 필수로
+         * 받는다) 여기서 섞으면 이 값의 뜻이 흐려진다.
+         */
+        else if (status) orderStatusNotCounted.set(status, (orderStatusNotCounted.get(status) ?? 0) + 1)
       }
     }
   }
@@ -729,6 +823,8 @@ export function foldKpi(events: KpiEvent[], window: KpiWindow, options: KpiFoldO
     waitTime: stats(waits),
     utilization,
     unpaired: { leadTime: unpairedLead, workTime: unpairedWork },
+    /* 못 읽은 오더 상태 낱말 — 비면 빈 객체다(§`orderStatusNotCounted`). */
+    orderStatusNotCounted: Object.fromEntries(orderStatusNotCounted),
     eventsSeen: seen,
     eventsInWindow: inWindow,
     ...(options.groupBy ? { groups: groupRecords(records, options) } : {})