@things-factory/headless-twin 10.0.7 → 10.0.9

package/server/service/twin-state/twin-state-subscription.ts

@@ -39,7 +39,7 @@ export class TwinStateSubscription {
 
       /* 구독 순간 현재 상태를 먼저 발행(late 구독자도 snapshot→delta 순서 보장). */
       process.nextTick(() => {
-        const snap = TwinEngine.snapshot(instanceId)
+        const snap = TwinEngine.snapshot(domainId, instanceId)
         if (snap) {
           pubsub.publish('twin-state', {
             twinState: { instanceId, kind: 'snapshot', revision: snap.revision, payload: snap }

package/server/service/twin-structure/twin-structure.ts

@@ -3,6 +3,7 @@ import { ObjectType, Field, ID, Int } from 'type-graphql'
 
 import { Domain, ScalarObject } from '@things-factory/shell'
 import { User } from '@things-factory/auth-base'
+import { boardColumnTransformer } from '../../engine/board-vocabulary.js'
 
 /*
  * TwinStructure — **한 트윈이 거쳐 온 공장 구조들.** 리비전 하나가 그 시절의 공장이다.
@@ -71,7 +72,9 @@ export class TwinStructure {
   @Field({ description: 'Short hash of the structural signature (locations + equipment). A re-provision with the same signature does not create a new revision — otherwise every reboot would slice the history into meaningless segments.' })
   signature: string
 
-  @Column({ type: 'simple-json' })
+  /* 읽을 때 어휘 세대를 흡수한다 — 옛 리비전의 보드로 지문을 다시 계산할 때 빈 공장으로 읽히면
+     구조 변경 감지가 죽는다(`engine/board-vocabulary.ts`). */
+  @Column({ type: 'simple-json', transformer: boardColumnTransformer })
   @Field(type => ScalarObject, { description: 'The full BoardDef as it stood for this revision. Stored whole rather than as a diff: replay needs the entire topology, and rebuilding it from diffs would be a second rule that can drift.' })
   board: any
 

package/server/service/twin-target/twin-target-resolver.ts

@@ -11,9 +11,27 @@ import { TWIN_METRIC, isTwinMetric } from '../../engine/kpi-target.js'
  * 경영 KPI 관리메뉴가 아니라 여기인 이유: 목표가 숫자 옆에 있어야 맥락이 살고, 운영 임계는 자주
  * 조정된다. 조직 단위 기간 평가는 `@things-factory/kpi` 의 일이고 이쪽으로 베껴 오지 않는다.
  */
+/*
+ * **쓰기는 막고 읽기는 연다** (2026-08-06 · ADR-0027).
+ *
+ * 이 리졸버는 트윈 리졸버 중 **유일하게** 권한 게이트를 갖는데, 처음에는 우회 표시가 없었다
+ * (`@privilege(category:"twin", privilege:"query")`). 그러면 `twin/query`·`twin/mutation` 권한을
+ * 실제로 부여받은 사용자만 쓸 수 있는데 — **저장소 어디에도 그 권한을 만드는 곳이 없다.** 결과는
+ * 도메인 소유자도 슈퍼유저도 목표를 걸 수 없는 상태였다: 성과 화면의 목표 버튼이 "Unauthorized" 로
+ * 떨어지고, 이 관점의 최상위 기능(§5 목표 프레임)이 **아무도 쓸 수 없는 채로** 놓여 있었다.
+ *
+ * 그래서 프레임워크의 통용 관용구를 따른다 — 가장 가까운 형제인 `@things-factory/kpi`(목표·지표 관리)가
+ * 74곳 전부 `domainOwnerGranted: true, superUserGranted: true` 를 쓴다. 같은 성격의 조작(무엇을 잘한
+ * 것으로 볼지 정하는 일)이므로 같은 자세를 쓴다: **현장을 소유한 사람은 바로 쓰고**, 다른 사람에게
+ * 맡기려면 `twin` 권한을 부여한다.
+ *
+ * 이제 트윈의 **모든 변경**에 같은 게이트가 있다(ADR-0027) — 처음에는 이 리졸버 하나만 게이트를 갖는
+ * 반쪽이었다. 조회 게이트는 걷었다: 같은 판정이 `twinKpi` 로 이미 열려 있어 지키는 것이 없었다.
+ */
 @Resolver()
 export class TwinTargetResolver {
-  @Directive('@privilege(category: "twin", privilege: "query")')
+  /* 조회에는 게이트를 두지 않는다 — 같은 판정이 `twinKpi.targets` 로 이미 열려 있어(그쪽은 게이트가
+     없다) 여기만 막으면 지키는 것 없이 화면만 깨진다. 읽기의 경계는 **테넌트 소속**이다. */
   @Query(returns => [String], {
     description:
       'The metric ids a twin target may refer to. Fixed in one place so a target and the fact it judges can never drift into two names.'
@@ -22,7 +40,7 @@ export class TwinTargetResolver {
     return Object.keys(TWIN_METRIC)
   }
 
-  @Directive('@privilege(category: "twin", privilege: "query")')
+
   @Query(returns => [TwinTarget], {
     description:
       'Operational targets in scope — site-wide targets for the space plus targets bound to the given instance. Callers judge with the narrower one when both exist.'
@@ -37,7 +55,7 @@ export class TwinTargetResolver {
     return rows.filter(r => (spaceId && r.spaceId === spaceId) || (instanceId && r.instanceId === instanceId))
   }
 
-  @Directive('@privilege(category: "twin", privilege: "mutation")')
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => Boolean, {
     description:
       'Create or update one operational target. The metric must be one of twinTargetMetrics — an unknown name is rejected rather than stored, because a target nobody can evaluate reads as "no target" and hides the gap.'
@@ -79,7 +97,7 @@ export class TwinTargetResolver {
     return true
   }
 
-  @Directive('@privilege(category: "twin", privilege: "mutation")')
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => Boolean, { description: 'Remove an operational target. Removing a target removes the judgement, not the fact — the metric keeps being reported without a verdict.' })
   async deleteTwinTarget(
     @Arg('metric') metric: string,

package/test/attention-digest.test.ts

@@ -0,0 +1,135 @@
+/*
+ * ★ 주의 신호 요약 — 신호가 많은 트윈의 전송량.
+ *
+ * ── 계기 ────────────────────────────────────────────────────────────────────
+ * 축 선택으로 리프레시를 80KB → 2KB 로 줄였는데 **신호가 많은 트윈은 거기서 막혔다**:
+ * `hatio-yard` 는 신호 397건이 108KB 라 5배 감소에 그쳤다. 그런데 화면이 그 397건으로 하는 일은
+ * 둘뿐이다 — 레일에 20건만 그리고, 자리 7곳의 색을 뽑는다.
+ *
+ * ── 이 테스트가 지키는 것 ───────────────────────────────────────────────────
+ *  ① **자리 색은 전량을 근거로** 접힌다. 상위 N 으로 접으면 20위 밖의 신호를 가진 자리가 색을 잃는다.
+ *  ② **조용히 자르지 않는다.** 전체 개수를 함께 보내야 레일이 "N건 더" 를 말할 수 있다.
+ *  ③ **순서가 화면과 같다.** 서버가 고른 20건이 화면이 고를 20건과 달라지면 아무 데서도 안 드러난다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { digestAttentions, compareAttentions, mergeLensAttentions } from '../server/engine/attention-digest.ts'
+
+const attn = (id: string, severity: string, locationId?: string, state?: string) => ({ id, severity, state, anchor: locationId ? { locationId } : undefined })
+
+test('상위 N 만 남기고 전체 개수를 함께 낸다 — 조용히 자르지 않는다', () => {
+  const all = Array.from({ length: 50 }, (_, i) => attn(`a${i}`, 'low', `loc-${i % 3}`))
+  const d = digestAttentions(all, 20)
+  assert.equal(d.attentions.length, 20)
+  assert.equal(d.attentionTotal, 50, '전체 개수가 없으면 화면이 "괜찮아졌다" 로 읽는다')
+})
+
+test('자리 색은 전량을 근거로 접는다 — 상위 N 밖의 자리도 색을 갖는다', () => {
+  /* 앞 20건은 loc-hot 에, 21번째 한 건만 loc-cold 에 — 잘린 뒤에 접으면 loc-cold 가 색을 잃는다. */
+  const all = [...Array.from({ length: 20 }, (_, i) => attn(`hot${i}`, 'high', 'loc-hot')), attn('cold', 'critical', 'loc-cold')]
+  const d = digestAttentions(all, 20)
+  assert.equal(d.attentions.length, 20)
+  assert.equal(d.severityByLocation['loc-cold'], 'critical', '상위 N 밖의 신호도 자리 색에는 반영돼야 한다')
+  assert.equal(d.severityByLocation['loc-hot'], 'high')
+})
+
+test('자리마다 가장 급한 심각도가 남는다', () => {
+  const d = digestAttentions([attn('a', 'low', 'n1'), attn('b', 'critical', 'n1'), attn('c', 'medium', 'n1')])
+  assert.equal(d.severityByLocation['n1'], 'critical')
+})
+
+test('순서는 화면과 같다 — 확인된 것은 아래로, 그다음 심각도순', () => {
+  const all = [attn('acked-crit', 'critical', 'n1', 'acknowledged'), attn('low', 'low', 'n2'), attn('high', 'high', 'n3')]
+  const d = digestAttentions(all, 2)
+  assert.deepEqual(d.attentions.map(a => a.id), ['high', 'low'], '확인된 critical 보다 확인 안 된 것이 먼저다')
+  assert.equal(d.attentionTotal, 3)
+})
+
+test('한도를 말하지 않으면 자르지 않는다 — 이 값을 모르는 소비처가 일부만 받으면 안 된다', () => {
+  const all = Array.from({ length: 30 }, (_, i) => attn(`a${i}`, 'low'))
+  assert.equal(digestAttentions(all).attentions.length, 30)
+  assert.equal(digestAttentions(all, 0).attentions.length, 30)
+  assert.equal(digestAttentions(all, -5).attentions.length, 30)
+})
+
+test('자리에 붙지 않은 신호는 색 요약에 들어가지 않는다 — 없는 자리를 만들지 않는다', () => {
+  const d = digestAttentions([attn('orphan', 'critical'), attn('anchored', 'low', 'n1')])
+  assert.deepEqual(Object.keys(d.severityByLocation), ['n1'])
+  assert.equal(d.attentionTotal, 2, '색에 안 들어가도 개수에는 든다')
+})
+
+test('신호가 없으면 빈 요약 — 없는 것을 만들지 않는다', () => {
+  for (const v of [undefined, null, []]) {
+    const d = digestAttentions(v as any, 20)
+    assert.deepEqual(d.attentions, [])
+    assert.equal(d.attentionTotal, 0)
+    assert.deepEqual(d.severityByLocation, {})
+  }
+})
+
+test('정렬 함수는 원본을 바꾸지 않는다 — 스냅샷을 제자리에서 흔들면 다른 소비처가 영향받는다', () => {
+  const all = [attn('low', 'low'), attn('crit', 'critical')]
+  const before = all.map(a => a.id)
+  digestAttentions(all, 1)
+  assert.deepEqual(all.map(a => a.id), before)
+  assert.equal(compareAttentions(all[1], all[0]) < 0, true, 'critical 이 앞이다')
+})
+
+/*
+ * ── 여러 렌즈를 한 현장으로 모으기 (2026-08-05) ────────────────────────────
+ * 한 공장에 WMS·MES·YMS 가 함께 있으므로 "이 현장에서 봐야 할 것" 은 렌즈 하나로 답할 수 없다.
+ * 예전에는 화면이 인스턴스마다 물어 손으로 합쳤고, 그러면 정렬 규칙이 화면마다 갈린다.
+ *
+ * 모으면서 조용히 틀릴 수 있는 자리 셋을 여기서 못 박는다.
+ */
+test('★ 어느 트윈에서 온 신호인지 붙는다 — 조치는 결국 그 트윈에 보내야 한다', () => {
+  const d = mergeLensAttentions([
+    { instanceId: 'wms', attentions: [attn('a', 'high', 'dock-1')] },
+    { instanceId: 'yms', attentions: [attn('b', 'low', 'gate-1')] }
+  ])
+  assert.deepEqual(d.attentions.map(a => [a.id, (a as any).instanceId]), [['a', 'wms'], ['b', 'yms']])
+})
+
+test('★ 순서는 렌즈 순서가 아니라 급한 순서다 — 뒤 렌즈의 심각한 신호가 밀려나면 안 된다', () => {
+  const d = mergeLensAttentions(
+    [
+      { instanceId: 'wms', attentions: [attn('low-1', 'low'), attn('low-2', 'low')] },
+      { instanceId: 'mes', attentions: [attn('crit', 'critical')] }
+    ],
+    1
+  )
+  assert.deepEqual(d.attentions.map(a => a.id), ['crit'], '상위 1건은 뒤 렌즈의 critical 이어야 한다')
+  assert.equal(d.attentionTotal, 3)
+})
+
+test('★ 두 렌즈가 같은 자리를 가리키면 더 급한 쪽이 색을 정한다 — 하나의 현실이므로', () => {
+  const d = mergeLensAttentions([
+    { instanceId: 'wms', attentions: [attn('a', 'low', 'dock-1')] },
+    { instanceId: 'yms', attentions: [attn('b', 'critical', 'dock-1')] }
+  ])
+  assert.equal(d.severityByLocation['dock-1'], 'critical')
+  /* 렌즈 순서를 뒤집어도 같아야 한다 — 색이 순서에 따라 달라지면 화면이 새로고침마다 바뀐다. */
+  const flipped = mergeLensAttentions([
+    { instanceId: 'yms', attentions: [attn('b', 'critical', 'dock-1')] },
+    { instanceId: 'wms', attentions: [attn('a', 'low', 'dock-1')] }
+  ])
+  assert.equal(flipped.severityByLocation['dock-1'], 'critical')
+})
+
+test('★ 신호가 없는 렌즈는 아무것도 보태지 않는다 — 빈 렌즈가 개수를 늘리지 않게', () => {
+  const d = mergeLensAttentions([
+    { instanceId: 'wms', attentions: [attn('a', 'low')] },
+    { instanceId: 'mes', attentions: [] },
+    { instanceId: 'yms', attentions: undefined }
+  ])
+  assert.equal(d.attentionTotal, 1)
+  assert.deepEqual(d.attentions.map(a => a.id), ['a'])
+})
+
+test('★ 렌즈가 하나도 없으면 빈 요약 — 공간에 떠 있는 트윈이 없을 때', () => {
+  const d = mergeLensAttentions([], 20)
+  assert.deepEqual(d.attentions, [])
+  assert.equal(d.attentionTotal, 0)
+  assert.deepEqual(d.severityByLocation, {})
+})

package/test/board-vocabulary.test.ts

@@ -0,0 +1,114 @@
+/*
+ * 저장된 보드의 어휘 세대 흡수 — **빈 공장으로 읽히지 않게.**
+ *
+ * ── 계기 (2026-08-06, 사용자 신고) ───────────────────────────────────────────
+ * 모델러의 엔티티 목록이 통째로 비어 있었다. **오류는 없었다.** 저장된 보드가 옛 어휘(`nodes`/`movers`)
+ * 인데 화면과 호스트가 새 어휘를 읽었기 때문이다. 같은 원인이 구조 서명(`N[]M[]` — 서로 다른 두 공장이
+ * 같아 보인다)·주행 추정기·설비 동기까지 조용히 망가뜨리고 있었다.
+ *
+ * 그래서 **DB에서 읽는 순간** 한 번 정규화한다. 이 테스트가 지키는 것은 그 정규화가 ① 세 세대를 다
+ * 흡수하고 ② 나머지 속성을 하나도 잃지 않고 ③ 새 보드에는 아무 일도 하지 않는 것이다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { readFileSync } from 'node:fs'
+
+import { boardColumnTransformer, canonicalBoard } from '../server/engine/board-vocabulary.ts'
+
+const LOC = [{ id: 'dock', type: 'dock', capacity: 10 }]
+const EQ = [{ id: 'fk-1', kind: 'forklift', homeLocation: 'dock' }]
+
+test('가장 오래된 세대(nodes·movers)를 흡수한다 — 사용자가 본 증상의 원인', () => {
+  const out = canonicalBoard({ nodes: LOC, movers: EQ, spaceId: 'site-1' })
+
+  assert.deepEqual(out.locations, LOC)
+  assert.deepEqual(out.equipment, EQ)
+})
+
+test('중간 세대(equipmentList)도 흡수한다 — 세 세대가 저장돼 있다', () => {
+  const out = canonicalBoard({ nodes: LOC, equipmentList: EQ })
+
+  assert.deepEqual(out.equipment, EQ)
+})
+
+test('옛 키를 **내보내지 않는다** — 소비처가 두 어휘를 다시 보지 않게', () => {
+  const out: any = canonicalBoard({ nodes: LOC, movers: EQ, equipmentList: [] })
+
+  for (const k of ['nodes', 'movers', 'equipmentList']) assert.equal(k in out, false, `${k} 가 남았다`)
+})
+
+test('나머지 속성을 하나도 잃지 않는다 — 곁가지로 보이는 값이 전제다', () => {
+  /* 이 도메인에서 사소한 속성은 없다: 좌표·시각기준·명세는 소요시간·교대·생산의 전제다. */
+  const board = {
+    nodes: LOC,
+    movers: EQ,
+    spaceId: 'site-1',
+    areaId: 'zone-a',
+    layout: { dock: { x: 1, y: 2 } },
+    utcOffsetMinutes: 540,
+    unit: 'm',
+    productionSpec: { definition: { operations: [] } },
+    operations: [{ id: 'op-1' }]
+  }
+  const out: any = canonicalBoard(board)
+
+  for (const k of ['spaceId', 'areaId', 'layout', 'utcOffsetMinutes', 'unit', 'productionSpec', 'operations']) {
+    assert.deepEqual(out[k], (board as any)[k], `${k} 가 사라졌다`)
+  }
+})
+
+test('새 어휘 보드에는 아무 일도 하지 않는다 — 멱등', () => {
+  const board = { locations: LOC, equipment: EQ, spaceId: 'site-1' }
+
+  const once: any = canonicalBoard(board)
+  const twice: any = canonicalBoard(once)
+
+  assert.deepEqual(once, board)
+  assert.deepEqual(twice, once)
+})
+
+test('컬렉션이 없으면 빈 배열이 된다 — 소비처가 `?? []` 를 다시 적지 않게', () => {
+  const out = canonicalBoard({ spaceId: 'site-1' })
+
+  assert.deepEqual(out.locations, [])
+  assert.deepEqual(out.equipment, [])
+})
+
+test('보드가 아닌 것은 그대로 통과시킨다 — 모양을 짐작해 고치지 않는다', () => {
+  for (const v of [null, undefined, 0, '', 'board', [1, 2]]) {
+    assert.deepEqual(canonicalBoard(v as any), v as any, JSON.stringify(v))
+  }
+})
+
+test('변환기는 **읽을 때만** 정규화한다 — 쓰기는 준 그대로', () => {
+  const old = { nodes: LOC, movers: EQ }
+
+  assert.deepEqual(boardColumnTransformer.from(old).equipment, EQ)
+  /* 쓰기를 손대면 "저장된 것" 과 "준 것" 이 달라져 추적이 어려워진다. 읽기가 정규화되므로 다음 저장에서
+     자연히 새 어휘가 된다. */
+  assert.equal(boardColumnTransformer.to(old), old)
+})
+
+test('두 옛 보드가 구조적으로 구별된다 — 서명이 빈 문자열로 뭉개지지 않는다', () => {
+  /* 정규화 전에는 둘 다 `locations: undefined` 라 서명이 `N[]M[]` 로 같았다(변경 감지가 죽는다). */
+  const a = canonicalBoard({ nodes: [{ id: 'a', type: 'dock', capacity: 1 }], movers: [] })
+  const b = canonicalBoard({ nodes: [{ id: 'b', type: 'storage', capacity: 9 }], movers: [] })
+
+  assert.notDeepEqual(a.locations, b.locations)
+  assert.equal(a.locations.length, 1)
+  assert.equal(b.locations.length, 1)
+})
+
+test('보드를 저장하는 엔티티가 **변환기를 달고 있다** — 결선이 빠지면 순수 모듈은 그린인데 화면은 빈다', () => {
+  /* 이 결함이 정확히 그랬다: 리더는 커널에 있었고 목록만 그것을 거쳤다. 결선은 조용히 빠질 수 있으므로
+     기계가 지킨다. 새 엔티티가 보드를 담게 되면 여기 함께 올린다. */
+  const owners = ['server/service/twin-instance/twin-instance.ts', 'server/service/twin-structure/twin-structure.ts']
+
+  for (const rel of owners) {
+    const src = readFileSync(new URL('../' + rel, import.meta.url).pathname, 'utf-8')
+    const boardColumn = src.split('\n').find(l => l.includes('@Column') && l.includes('transformer'))
+    assert.ok(boardColumn, `${rel}: board 컬럼에 transformer 가 없다`)
+    assert.match(boardColumn as string, /boardColumnTransformer/, `${rel}: 다른 변환기가 달려 있다`)
+  }
+})

package/test/capability-mapping.test.ts

@@ -63,17 +63,17 @@ test('능력 소싱 구조: 4 자원/위치 능력은 카탈로그 타입에서,
 
 test('★ 스트림라인 브릿지: 능력의 상태필드가 라이브 payload 에 실림 (커널→보드 도달)', () => {
   // storable 노드 → occupancy/capacity (+ operable status)
-  const nodeD: any = buildEntityDeltas({ locations: [{ id: 'n', type: 'storage', occupancy: 2, capacity: 9, status: 'idle' }] })[0].data
+  const nodeD: any = buildEntityDeltas({ locations: [{ id: 'n', type: 'storage', occupancy: 2, capacity: 9, status: 'idle' }] }, 't1')[0].data
   for (const f of stateFieldsOf(['storable'])) assert.ok(f in nodeD, `storable payload.${f}`)
   assert.ok('status' in nodeD, 'operable(노드 status) payload')
 
   // mobile+operable 무버 → location/motion/status
-  const equipmentD: any = buildEntityDeltas({ equipment: [{ id: 'm', kind: 'forklift', location: 'n', status: 'busy', motion: { toNode: 'n2', progress: 0.3 } }] }).find(x => x.tag === 'm')!.data
+  const equipmentD: any = buildEntityDeltas({ equipment: [{ id: 'm', kind: 'forklift', location: 'n', status: 'busy', motion: { toNode: 'n2', progress: 0.3 } }] }, 't1').find(x => x.tag === 'm')!.data
   for (const f of stateFieldsOf(['mobile'])) assert.ok(f in equipmentD, `mobile payload.${f}`)
   for (const f of stateFieldsOf(['operable'])) assert.ok(f in equipmentD, `operable payload.${f}`)
 
   // trackable 오더 → progress/held (lifecycle 은 payload 에서 'status' 로 표면화 — 이름-매핑 시임)
-  const orderD: any = buildEntityDeltas({ orders: [{ id: 'o', status: 'picking', progress: 0.5, held: false }] }).find(x => x.tag === 'o')!.data
+  const orderD: any = buildEntityDeltas({ orders: [{ id: 'o', status: 'picking', progress: 0.5, held: false }] }, 't1').find(x => x.tag === 'o')!.data
   assert.ok('progress' in orderD && 'held' in orderD, 'trackable progress/held payload')
   assert.ok('status' in orderD, 'trackable lifecycle → payload.status (이름-매핑)')
 })
@@ -82,7 +82,7 @@ test('시임 문서화 · processable output(양품/불량)은 payload oee.good/
   // 계약 stateField = 'output' 이나, 라이브 payload 는 이를 oee(정수%+good/scrap)로 집약해 표면화.
   const d: any = buildEntityDeltas({
     equipment: [{ id: 'c', kind: 'cutter', status: 'busy', oee: { overall: 0.8, availability: 0.9, performance: 0.9, quality: 0.98, goodCount: 10, scrapCount: 1 } }]
-  }).find(x => x.tag === 'c')!.data
+  }, 't1').find(x => x.tag === 'c')!.data
   assert.ok(d.oee, 'processable → payload.oee 존재')
   assert.equal(d.oee.good, 10, 'output.good = oee.good')
   assert.equal(d.oee.scrap, 1, 'output.scrap = oee.scrap')

package/test/command-routing.test.ts

@@ -0,0 +1,61 @@
+/*
+ * ★ 커맨드 라우팅 판정 — 권위(모드) × 성격(주석/액추에이션).
+ *
+ * ── 무엇이 문제였나 ─────────────────────────────────────────────────────────
+ * 리졸버가 `inst.runtime.dispatch(...)` 를 곧바로 불렀다. 그런데 `runtime` 은 **시뮬 경로에서만**
+ * 만들어진다. 실물을 비추는 트윈(mirror)에서는 그 한 줄이 `TypeError` 로 터져 조치 채널이 통째로
+ * 닿지 않았다 — 사용자에게는 이유 있는 거절이 아니라 그냥 실패였다.
+ *
+ * ── 그냥 열면 안 되는 이유 ──────────────────────────────────────────────────
+ * 미러에서 액추에이션을 허용하면 **새 거짓말이 생긴다**: 트윈은 "보류됨" 이라 말하고 실 시스템은
+ * 모른다. 그래서 실 프로세스를 바꾸는 커맨드는 아웃바운드 어댑터가 붙기 전까지 이유를 밝혀 거절한다
+ * (`design/plans/command-routing.md` P0). 확인(ack)은 트윈 쪽 주석이라 미러에서도 통과한다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { routeCommand, isActuation } from '../server/engine/command-routing.ts'
+
+const sim = { hasRuntime: true, hasKernelDispatch: true }
+const mirror = { mode: 'live', hasRuntime: false, hasKernelDispatch: true }
+
+test('시뮬 — 커맨드는 커널 런타임으로 간다(현행 경로 그대로)', () => {
+  assert.deepEqual(routeCommand(sim, true, 'order.hold'), { target: 'runtime' })
+  assert.deepEqual(routeCommand(sim, true, 'attention.ack'), { target: 'runtime' })
+})
+
+test('미러 — 확인(ack)은 관측 커널로 간다. 현실을 건드리지 않는 주석이다', () => {
+  assert.deepEqual(routeCommand(mirror, true, 'attention.ack'), { target: 'kernel' })
+})
+
+test('미러 — 실 프로세스를 바꾸는 커맨드는 이유를 밝히고 거절한다', () => {
+  for (const type of ['order.hold', 'order.resume', 'order.release', 'resource.down', 'resource.repair', 'resource.add']) {
+    const r = routeCommand(mirror, true, type)
+    assert.equal(r.target, 'reject', `${type} 은 미러에서 통과하면 안 된다`)
+    if (r.target !== 'reject') return
+    assert.equal(r.errorCode, 'actuation-not-wired')
+    assert.equal(r.errorParams?.type, type, '어느 커맨드였는지 함께 알려야 한다')
+  }
+})
+
+test('없는 인스턴스와 다른 도메인은 같은 사유로 거절한다 — 있음/없음이 구별되면 그것이 정보다', () => {
+  assert.deepEqual(routeCommand(undefined, false, 'attention.ack'), { target: 'reject', errorCode: 'no-instance' })
+  assert.deepEqual(routeCommand(sim, false, 'attention.ack'), { target: 'reject', errorCode: 'no-instance' })
+})
+
+test('런타임이 없는 시뮬 — 터뜨리지 않고 이유를 말한다', () => {
+  assert.deepEqual(routeCommand({ hasRuntime: false, hasKernelDispatch: true }, true, 'order.hold'), { target: 'reject', errorCode: 'no-runtime' })
+})
+
+test('커널이 커맨드를 못 받는 미러 — 확인도 이유를 말하고 멈춘다', () => {
+  assert.deepEqual(routeCommand({ mode: 'live', hasRuntime: false, hasKernelDispatch: false }, true, 'attention.ack'), { target: 'reject', errorCode: 'no-runtime' })
+})
+
+test('빈 커맨드 종류는 거절한다 — 무엇을 하라는지 모르는 것을 보내지 않는다', () => {
+  assert.deepEqual(routeCommand(sim, true, ''), { target: 'reject', errorCode: 'unknown-command' })
+})
+
+test('성격 판정 — 확인만 주석이고 나머지는 액추에이션이다', () => {
+  assert.equal(isActuation('attention.ack'), false)
+  for (const t of ['order.hold', 'resource.add', 'order.release']) assert.equal(isActuation(t), true, t)
+})

package/test/discovery-result.test.ts

@@ -0,0 +1,75 @@
+/*
+ * 사이트 발견 결과 — **"못 찾았다" 를 "없다" 로 말하지 않게.**
+ *
+ * 실 시스템을 연결해 트윈을 만드는 경로에서, 발견이 실패하면 화면이 "사이트를 찾지 못했습니다" 라고만
+ * 말했다. 레퍼런스 미등록·어댑터 미상·조회 실패·정말 0건이 그 한 문장으로 접혀 있었다 — 자격이
+ * 틀렸는지 주소가 틀렸는지 알 수 없었다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  discovered, failed, detailOf,
+  referenceNotFound, adapterUnknown, discoveryFailed, discoveryTimedOut
+} from '../server/service/reference/discovery-result.ts'
+
+test('사이트가 없는 것은 실패가 아니다 — 사유 없는 빈 목록이 "없다" 를 뜻한다', () => {
+  /* 권한이 좁거나 아직 등록되지 않아 공장이 하나도 없는 시스템은 있을 수 있다. 그것은 사실이므로
+     실패로 뭉개면 사용자가 있지도 않은 문제를 찾는다. */
+  const r = discovered([])
+  assert.deepEqual(r, { sites: [] })
+  assert.equal(r.error, undefined, '사유가 없다 = 성공')
+})
+
+test('찾은 것을 그대로 돌려주되 입력을 붙들지 않는다', () => {
+  const src = [{ siteId: 'PL1' }, { siteId: 'PL2' }]
+  const r = discovered(src)
+  assert.deepEqual(r.sites, src)
+  src.push({ siteId: 'PL3' })
+  assert.equal(r.sites.length, 2, '나중에 바뀐 원본이 결과를 바꾸지 않는다')
+})
+
+test('없는 목록·null 도 견딘다', () => {
+  assert.deepEqual(discovered(null), { sites: [] })
+  assert.deepEqual(discovered(undefined), { sites: [] })
+})
+
+test('실패는 사유와 함께, 사이트는 비워서 — 반쪽 목록을 성공처럼 보이지 않게', () => {
+  const r = failed(referenceNotFound('sap-ewm-1710'))
+  assert.deepEqual(r.sites, [])
+  assert.equal(r.error?.code, 'reference-not-found')
+  assert.equal(r.error?.params?.source, 'sap-ewm-1710')
+  assert.match(r.error!.message, /not registered/, '영어 canonical 문장이 로그·폴백으로 남는다')
+})
+
+test('네 가지 사유가 서로 구별된다 — 이것이 이 작업의 요점이다', () => {
+  const codes = [
+    referenceNotFound('s').code,
+    adapterUnknown('sap-ewm', 's').code,
+    discoveryFailed('s', '401 Unauthorized').code,
+    discoveryTimedOut('s', 15).code
+  ]
+  assert.deepEqual(codes, ['reference-not-found', 'adapter-unknown', 'discovery-failed', 'discovery-timeout'])
+  assert.equal(new Set(codes).size, 4, '넷이 한 코드로 접히지 않는다')
+})
+
+test('원 시스템이 준 사유를 감추지 않는다 — 사용자가 관리자에게 물어볼 수 있게', () => {
+  const e = discoveryFailed('sap-ewm-1710', '401 Unauthorized')
+  assert.equal(e.params?.detail, '401 Unauthorized')
+  assert.match(e.message, /401 Unauthorized/)
+})
+
+test('타임아웃은 초 단위로 말한다 — 얼마를 기다렸는지 알 수 있게', () => {
+  const e = discoveryTimedOut('s', 15)
+  assert.equal(e.params?.seconds, 15)
+  assert.match(e.message, /15s/)
+})
+
+test('어댑터가 던진 것에서 사유를 뽑는다 — 형태를 가정하지 않는다', () => {
+  assert.equal(detailOf(new Error('ECONNREFUSED')), 'ECONNREFUSED')
+  assert.equal(detailOf('404 Not Found'), '404 Not Found')
+  /* 무엇이 왔는지 모르면 그렇게 말한다 — 빈 문장으로 "이유 없음" 처럼 보이게 하지 않는다. */
+  for (const weird of [undefined, null, {}, 0, new Error('')]) {
+    assert.match(detailOf(weird), /without a message/, `이상한 입력: ${JSON.stringify(weird)}`)
+  }
+})