@things-factory/headless-twin 10.0.18 → 10.1.0

package/test/actuation-approval-door.test.ts

@@ -0,0 +1,421 @@
+/*
+ * **승인의 문은 한 벌이다** — 결재선에 올라간 조치는 여기서 결정되지 않는다.
+ *
+ * ── 무엇이 있었나 (2026-08-31) ───────────────────────────────────────────
+ * 게이트를 세우고 승인 화면을 계획하다가 물었다 — 「무엇을 승인하는 화면인가」. 커맨드 행을 **적는
+ * 코드가 하나도 없었다.** 대기 줄은 구조적으로 비어 있었다. 자리는 있고 길이 없는 그 부류다.
+ *
+ * 그것을 채우면서 문이 둘이 되었다: 이 패키지의 직접 결정과, 업무 목록(worklist)의 결재선. 문이 둘이면
+ * 결재선에는 대기로 남아 있는데 조치는 이미 나간 상태가 만들어지고, 사고 뒤에 **어느 기록이 진짜인지**
+ * 말할 수 없다.
+ *
+ * 그래서 규칙 하나: **결재선 자리가 적힌 커맨드는 결재선에서만 결정한다.** 이 시험이 그 규칙을 지킨다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { CMD, MES_COMMANDS, type CommandTypeSpec } from '@operato/ops-contract'
+
+import {
+  approve,
+  dispatch,
+  linkApproval,
+  propose,
+  reject,
+  settleByApproval,
+  type CommandStore,
+  type StoredCommand
+} from '../server/service/actuation/command-dispatcher.js'
+
+const DOMAIN = 'd-1'
+const AT = '2026-08-31T02:00:00.000Z'
+const REF = 'activity-instance-1'
+
+/* MES 프로필의 선언을 그대로 쓴다 — 시험용 종류를 지어내면 선언과 어긋난 것을 시험이 통과시킨다. */
+const SPEC: readonly CommandTypeSpec[] = MES_COMMANDS
+const ORDER = MES_COMMANDS[0]!
+const PAYLOAD = { materialDefinitionId: 'urn:epc:idpat:sgtin:9521234.00001.*', quantity: 12, uom: 'EA' }
+
+const PROPOSER = 'line-lead@plant.example'
+const APPROVER = 'plant-manager@plant.example'
+
+const seed = (over: Partial<Parameters<typeof propose>[3]> = {}) => ({
+  id: 'cmd-1',
+  instanceId: 'twin-a',
+  type: ORDER.type,
+  origin: 'operator' as const,
+  proposedBy: PROPOSER,
+  proposedAt: AT,
+  payload: PAYLOAD,
+  ...over
+})
+
+/** 저장본 하나 — 프로세스가 아니라 여기 산다. 그래서 다시 세워도 남는다. */
+function makeStore(initial?: StoredCommand): CommandStore & { rows: Map<string, StoredCommand> } {
+  const rows = new Map<string, StoredCommand>(initial ? [[initial.id, initial]] : [])
+  const put = (command: StoredCommand) => {
+    const copy: StoredCommand = JSON.parse(JSON.stringify(command))
+    rows.set(copy.id, copy)
+    return copy
+  }
+  return {
+    rows,
+    load: async (domainId, id) => (domainId === DOMAIN ? (rows.get(id) ?? null) : null),
+    save: async (domainId, command) => {
+      assert.equal(domainId, DOMAIN)
+      put(command)
+    },
+    create: async (domainId, command) => {
+      assert.equal(domainId, DOMAIN)
+      if (rows.has(command.id)) throw new Error(`이미 있는 커맨드다 (${command.id})`)
+      return put(command)
+    }
+  }
+}
+
+const ok = async (): Promise<{ ok: boolean; ref?: string }> => ({ ok: true, ref: 'JOB-1' })
+
+/* ── 낸다 ─────────────────────────────────────────────────────────────────── */
+
+test('★ 낸 조치가 대기 줄에 남는다 — 이 길이 없어 대기 줄이 비어 있었다', async () => {
+  const store = makeStore()
+  const command = await propose(store, DOMAIN, SPEC, seed())
+
+  assert.equal(command.state, 'proposed')
+  assert.equal(store.rows.size, 1, '행이 적히지 않았다')
+  assert.equal(store.rows.get('cmd-1')!.type, ORDER.type)
+  assert.equal(store.rows.get('cmd-1')!.payload.quantity, 12, '무엇을 지시하는지가 남지 않으면 승인할 근거가 없다')
+})
+
+test('★ 선언되지 않은 종류는 낼 수 없다 — 되돌릴 수 있는지 모르는 채로 게이트를 지나게 하지 않는다', async () => {
+  const store = makeStore()
+  await assert.rejects(propose(store, DOMAIN, SPEC, seed({ type: 'line.shutdown' })), /선언되지 않은 조치 종류/)
+  assert.equal(store.rows.size, 0, '거절하면서 행을 적었다')
+})
+
+test('★ 요구하는 칸이 없으면 낼 수 없다 — 빈 지시가 대기 줄에 쌓이지 않게', async () => {
+  const store = makeStore()
+  await assert.rejects(propose(store, DOMAIN, SPEC, seed({ payload: { quantity: 12 } })), /요구하는 칸이 없다/)
+  assert.equal(store.rows.size, 0)
+})
+
+test('선언이 「되돌릴 수 없다」이면 그대로 적힌다 — 낸 쪽이 정하지 않는다', async () => {
+  const store = makeStore()
+  const command = await propose(store, DOMAIN, SPEC, seed())
+  assert.equal(command.reversible, ORDER.reversible)
+  assert.equal(command.reversible, false, 'MES 생산 지시는 되돌릴 수 없다 — 취소해도 만든 것은 남는다')
+})
+
+/* ── 문은 한 벌이다 ───────────────────────────────────────────────────────── */
+
+test('★ 결재선에 올라간 조치는 여기서 승인되지 않는다', async () => {
+  const store = makeStore()
+  await propose(store, DOMAIN, SPEC, seed())
+  await linkApproval(store, DOMAIN, 'cmd-1', REF)
+
+  await assert.rejects(approve(store, DOMAIN, 'cmd-1', { by: APPROVER, at: AT }), /결재선에 올라가 있다/)
+  await assert.rejects(reject(store, DOMAIN, 'cmd-1', { by: APPROVER, at: AT }), /결재선에 올라가 있다/)
+  assert.equal(store.rows.get('cmd-1')!.state, 'proposed', '막았다면서 상태가 움직였다')
+})
+
+test('★ 결재선을 쓰지 않는 배포에서는 직접 결정이 유일한 문이다', async () => {
+  const store = makeStore()
+  await propose(store, DOMAIN, SPEC, seed())
+
+  const approved = await approve(store, DOMAIN, 'cmd-1', { by: APPROVER, at: AT })
+  assert.equal(approved.state, 'approved')
+  assert.equal((await dispatch(store, DOMAIN, 'cmd-1', ok)).state, 'acked')
+})
+
+test('★ 올라가지 않은 커맨드에 결재선 판정을 옮기지 않는다 — 어디서 온 판정인지 알 수 없다', async () => {
+  const store = makeStore()
+  await propose(store, DOMAIN, SPEC, seed())
+
+  await assert.rejects(
+    settleByApproval(store, DOMAIN, 'cmd-1', { approvalRef: REF, approved: true, by: APPROVER, at: AT }),
+    /결재선에 올라가지 않은/
+  )
+})
+
+test('★ 다른 결재 건의 판정은 받지 않는다 — 옆 건의 승인으로 게이트가 열리지 않게', async () => {
+  const store = makeStore()
+  await propose(store, DOMAIN, SPEC, seed())
+  await linkApproval(store, DOMAIN, 'cmd-1', REF)
+
+  await assert.rejects(
+    settleByApproval(store, DOMAIN, 'cmd-1', { approvalRef: 'activity-instance-9', approved: true, by: APPROVER, at: AT }),
+    /다른 결재 건의 판정/
+  )
+  assert.equal(store.rows.get('cmd-1')!.state, 'proposed')
+})
+
+/* ── 결재선의 판정이 옮겨진다 ────────────────────────────────────────────── */
+
+test('★ 결재선이 승인하면 나갈 수 있다 — 누가 승인했는지가 커맨드에도 남는다', async () => {
+  const store = makeStore()
+  await propose(store, DOMAIN, SPEC, seed())
+  await linkApproval(store, DOMAIN, 'cmd-1', REF)
+
+  const approved = await settleByApproval(store, DOMAIN, 'cmd-1', {
+    approvalRef: REF,
+    approved: true,
+    by: APPROVER,
+    at: AT,
+    note: '야간 물량 반영'
+  })
+
+  assert.equal(approved.state, 'approved')
+  /* 커맨드 목록이 결재선을 조회하지 않고도 「누가 언제」를 보여야 한다. */
+  assert.equal(store.rows.get('cmd-1')!.approval?.by, APPROVER)
+  assert.equal(store.rows.get('cmd-1')!.approval?.note, '야간 물량 반영')
+  assert.equal((await dispatch(store, DOMAIN, 'cmd-1', ok)).state, 'acked')
+})
+
+test('★ 결재선이 거절하면 커맨드는 거기서 닫힌다 — 뒤늦은 승인이 게이트를 열지 못한다', async () => {
+  /*
+   * 업무 목록에서 「거절」은 고쳐 다시 올리라는 뜻이지만, 조치에는 고칠 것이 없다 — 지시 내용은 제안될
+   * 때 정해진다. 그래서 커맨드 쪽은 끝으로 다룬다. 그 뒤에 결재선에서 승인이 와도 계약이 막는다.
+   */
+  const store = makeStore()
+  await propose(store, DOMAIN, SPEC, seed())
+  await linkApproval(store, DOMAIN, 'cmd-1', REF)
+
+  const rejected = await settleByApproval(store, DOMAIN, 'cmd-1', {
+    approvalRef: REF,
+    approved: false,
+    by: APPROVER,
+    at: AT,
+    note: '그 라인은 정지 중이다'
+  })
+  assert.equal(rejected.state, 'rejected')
+
+  await assert.rejects(
+    settleByApproval(store, DOMAIN, 'cmd-1', { approvalRef: REF, approved: true, by: 'someone-else@plant.example', at: AT }),
+    /승인할 수 없다|승인되지 않은|rejected/
+  )
+  await assert.rejects(dispatch(store, DOMAIN, 'cmd-1', ok))
+})
+
+/* ── 자극과 조치는 다른 어휘다 ───────────────────────────────────────────── */
+
+test('★ 커널 자극을 조치로 낼 수 없다 — 모델 안의 자극이 현장 지시가 되지 않게', async () => {
+  /*
+   * 계약에 어휘가 두 벌이다.
+   *
+   *   CMD           커널 안에서 도는 자극. `resource.repair` = 모델에서 수리된 것으로 둔다
+   *   MES_COMMANDS  현장에 나가는 지시. `production.order` = 실제로 만든다
+   *
+   * 주의 신호가 권하는 것(`Attention.suggestedAction.command`)은 **앞엣것**이다. 주의를 읽어 조치를
+   * 내는 코드를 쓰다 보면 그 값을 그대로 넘기게 된다 — 실제로 그러려다 멈췄다.
+   */
+  const store = makeStore()
+  await assert.rejects(
+    propose(store, DOMAIN, SPEC, seed({ type: CMD.resourceRepair })),
+    /커널 안에서 도는 자극이다/
+  )
+  assert.equal(store.rows.size, 0)
+})
+
+test('★ 두 어휘가 겹치지 않는다 — 겹치면 어느 쪽으로 읽어야 할지 알 수 없다', () => {
+  /*
+   * 이 시험이 지키는 것은 앞의 거절이 **뜻을 갖는다**는 사실이다. 같은 문자열이 양쪽에 있으면 거절도
+   * 통과도 옳지 않게 되고, 그때 위 시험은 초록인데 규칙은 사라진다.
+   */
+  const stimuli = new Set(Object.values(CMD) as string[])
+  const overlap = MES_COMMANDS.map(s => s.type).filter(t => stimuli.has(t))
+
+  assert.deepEqual(
+    overlap,
+    [],
+    `자극과 조치에 같은 이름이 있다 (${overlap.join(', ')}) — 한 이름이 모델 상태를 바꾸기도 하고 현장에 나가기도 한다`
+  )
+})
+
+/* ── 낸 사람은 자기 것을 승인하지 못한다 ─────────────────────────────────── */
+
+test('★ 낸 사람이 자기 조치를 승인하지 못한다 — 게이트가 시늉이 되는 자리', async () => {
+  /*
+   * 이 규칙이 왜 필요한지는 돌려 보고 알았다. 업무 목록은 결재선이 비어 있으면 스레드를 곧바로
+   * 종료하고(§`submit.ts`), 그러면 콜백이 「승인됐다」로 받는다. 승인자를 지정하지 않은 도메인에서는
+   * 낸 사람이 그 자리에서 자기 조치를 승인한 것이 된다 — 오류 한 줄 없이.
+   */
+  const store = makeStore()
+  await propose(store, DOMAIN, SPEC, seed())
+
+  await assert.rejects(approve(store, DOMAIN, 'cmd-1', { by: PROPOSER, at: AT }), /낸 사람이 자기 조치를 승인할 수 없다/)
+  assert.equal(store.rows.get('cmd-1')!.state, 'proposed')
+})
+
+test('★ 결재선을 지나온 판정에도 같은 규칙이 걸린다 — Myself 를 승인자로 넣으면 같은 사람이다', async () => {
+  const store = makeStore()
+  await propose(store, DOMAIN, SPEC, seed())
+  await linkApproval(store, DOMAIN, 'cmd-1', REF)
+
+  await assert.rejects(
+    settleByApproval(store, DOMAIN, 'cmd-1', { approvalRef: REF, approved: true, by: PROPOSER, at: AT }),
+    /낸 사람이 자기 조치를 승인할 수 없다/
+  )
+  assert.equal(store.rows.get('cmd-1')!.state, 'proposed')
+})
+
+test('대소문자가 달라도 같은 사람이다 — 로그인 이름의 표기로 규칙을 비껴가지 못한다', async () => {
+  const store = makeStore()
+  await propose(store, DOMAIN, SPEC, seed())
+  await assert.rejects(approve(store, DOMAIN, 'cmd-1', { by: PROPOSER.toUpperCase(), at: AT }), /낸 사람이/)
+})
+
+test('★ 낸 사람은 자기 것을 물릴 수 있다 — 거절에는 걸지 않는다', async () => {
+  const store = makeStore()
+  await propose(store, DOMAIN, SPEC, seed())
+  const rejected = await reject(store, DOMAIN, 'cmd-1', { by: PROPOSER, at: AT, note: '잘못 냈다' })
+  assert.equal(rejected.state, 'rejected')
+})
+
+test('★ 사람이 내는데 낸 사람이 없으면 받지 않는다 — 그 한 건만 규칙을 비껴간다', async () => {
+  const store = makeStore()
+  await assert.rejects(propose(store, DOMAIN, SPEC, seed({ proposedBy: undefined })), /낸 사람이 있어야 한다/)
+  assert.equal(store.rows.size, 0)
+})
+
+test('규칙·AI 가 낸 것은 낸 사람이 없다 — 사람이 아니다', async () => {
+  const store = makeStore()
+  const command = await propose(store, DOMAIN, SPEC, seed({ origin: 'rule', proposedBy: undefined }))
+  assert.equal(command.proposedBy, undefined)
+  /* 사람이 없으니 누구든 승인할 수 있다 — 그것이 이 경로의 뜻이다. */
+  assert.equal((await approve(store, DOMAIN, 'cmd-1', { by: APPROVER, at: AT })).state, 'approved')
+})
+
+test('★ 낸 사람이 재기동을 넘어 산다 — 사라지면 자기 승인이 열린다', async () => {
+  const first = makeStore()
+  await propose(first, DOMAIN, SPEC, seed())
+  const saved: StoredCommand = JSON.parse(JSON.stringify(first.rows.get('cmd-1')))
+
+  const second = makeStore(saved)
+  assert.equal(second.rows.get('cmd-1')!.proposedBy, PROPOSER, '재기동에 낸 사람이 사라졌다')
+  await assert.rejects(approve(second, DOMAIN, 'cmd-1', { by: PROPOSER, at: AT }), /낸 사람이/)
+})
+
+test('★ 넘긴 뒤에도 낸 사람이 남는다 — 사고 뒤에 누가 냈는지 물을 자리다', async () => {
+  const store = makeStore()
+  await propose(store, DOMAIN, SPEC, seed())
+  await approve(store, DOMAIN, 'cmd-1', { by: APPROVER, at: AT })
+  const settled = await dispatch(store, DOMAIN, 'cmd-1', ok)
+
+  assert.equal(settled.proposedBy, PROPOSER)
+  assert.equal(store.rows.get('cmd-1')!.proposedBy, PROPOSER, '넘기는 사이에 낸 사람이 지워졌다')
+})
+
+/* ── 재기동 ───────────────────────────────────────────────────────────────── */
+
+test('★ 결재선 자리가 재기동을 넘어 산다 — 다시 세운 뒤 직접 결정이 열리면 우회로가 된다', async () => {
+  const first = makeStore()
+  await propose(first, DOMAIN, SPEC, seed())
+  await linkApproval(first, DOMAIN, 'cmd-1', REF)
+
+  /* 프로세스가 새로 선 것으로 본다 — 앞의 저장소 객체는 버리고 저장본만 물려준다. */
+  const saved: StoredCommand = JSON.parse(JSON.stringify(first.rows.get('cmd-1')))
+  const second = makeStore(saved)
+
+  assert.equal(second.rows.get('cmd-1')!.approvalRef, REF, '재기동에 결재선 자리가 사라졌다')
+  await assert.rejects(approve(second, DOMAIN, 'cmd-1', { by: APPROVER, at: AT }), /결재선에 올라가 있다/)
+
+  const approved = await settleByApproval(second, DOMAIN, 'cmd-1', {
+    approvalRef: REF,
+    approved: true,
+    by: APPROVER,
+    at: AT
+  })
+  assert.equal(approved.state, 'approved')
+})
+
+test('★ 넘긴 뒤에도 결재선 자리가 남는다 — 사고 뒤에 어느 결재로 나갔는지 물을 자리다', async () => {
+  const store = makeStore()
+  await propose(store, DOMAIN, SPEC, seed())
+  await linkApproval(store, DOMAIN, 'cmd-1', REF)
+  await settleByApproval(store, DOMAIN, 'cmd-1', { approvalRef: REF, approved: true, by: APPROVER, at: AT })
+
+  const settled = await dispatch(store, DOMAIN, 'cmd-1', ok)
+  assert.equal(settled.state, 'acked')
+  assert.equal(settled.approvalRef, REF)
+  assert.equal(store.rows.get('cmd-1')!.approvalRef, REF, '넘기는 사이에 결재선 자리가 지워졌다')
+})
+
+/* ── 받아들였으나 남은 것이 있다 ────────────────────────────────────────────── */
+
+test('★ 저쪽이 덧붙인 말은 실패가 아니다 — 두 답이 구별되어야 한다', async () => {
+  /*
+   * 실측(2026-09-02): MES 에 조치 둘을 넘겼더니 트윈 쪽 두 행이 완전히 같았다. 하나는 지시서가
+   * 붙었고 하나는 안 붙었는데 `state`·`dispatch_ref`·`error` 가 셋 다 같았다. 화면은 둘 다
+   * 「나갔다」로 읽는다.
+   */
+  const store = makeStore()
+  await propose(store, DOMAIN, SPEC, seed())
+  await approve(store, DOMAIN, 'cmd-1', { by: APPROVER, at: AT })
+
+  const out = await dispatch(store, DOMAIN, 'cmd-1', async () => ({
+    ok: true,
+    ref: 'WO-005',
+    note: '지시서가 붙지 않았습니다 — 사람이 MES 에서 골라야 합니다'
+  }))
+
+  assert.equal(out.state, 'acked', '덧붙인 말이 있는 것을 실패로 앉혔다')
+  assert.equal(out.dispatchRef, 'WO-005')
+  assert.match(out.dispatchNote!, /지시서가 붙지 않았습니다/)
+  assert.equal(out.error, undefined, '덧붙인 말을 오류 칸에 적었다')
+})
+
+test('덧붙인 말이 없으면 그 칸은 비어 있다 — 빈 문장을 만들지 않는다', async () => {
+  const store = makeStore()
+  await propose(store, DOMAIN, SPEC, seed())
+  await approve(store, DOMAIN, 'cmd-1', { by: APPROVER, at: AT })
+
+  const out = await dispatch(store, DOMAIN, 'cmd-1', async () => ({ ok: true, ref: 'WO-004' }))
+
+  assert.equal(out.state, 'acked')
+  assert.equal(out.dispatchNote, undefined)
+})
+
+/* ── 다시 넘길 때 지난 시도의 자국을 지운다 ────────────────────────────────── */
+
+test('★ 다시 넘겨 성공하면 지난 실패의 오류가 남지 않는다 — 한 행이 두 가지를 말하면 안 된다', async () => {
+  /*
+   * 실측(2026-09-03): `failed → dispatch` 로 다시 넘겨 성공했는데 지난 실패의 `error` 가 그대로
+   * 남아, 한 행이 「받았다(acked)」와 「저쪽이 안 받는다」를 동시에 말했다. 화면이 그 행을 그리면
+   * 어느 쪽을 믿어야 하는지 알 수 없다.
+   */
+  const store = makeStore()
+  await propose(store, DOMAIN, SPEC, seed())
+  await approve(store, DOMAIN, 'cmd-1', { by: APPROVER, at: AT })
+
+  const failed = await dispatch(store, DOMAIN, 'cmd-1', async () => ({ ok: false, error: '저쪽에 비밀값이 없습니다' }))
+  assert.equal(failed.state, 'failed')
+  assert.match(failed.error!, /비밀값/)
+
+  const retried = await dispatch(store, DOMAIN, 'cmd-1', async () => ({ ok: true, ref: 'WO-001' }))
+  assert.equal(retried.state, 'acked')
+  assert.equal(retried.dispatchRef, 'WO-001')
+  assert.equal(retried.error, undefined, '지난 실패의 오류가 성공한 행에 남았다')
+})
+
+test('★ 다시 넘겨 덧붙일 말이 없으면 옛 말이 남지 않는다 — 오류와 같은 부류다', async () => {
+  const store = makeStore()
+  await propose(store, DOMAIN, SPEC, seed())
+  await approve(store, DOMAIN, 'cmd-1', { by: APPROVER, at: AT })
+
+  /* 한 번 실패하면서 덧붙인 말이 남을 수 있는 자리를 만든다. */
+  await dispatch(store, DOMAIN, 'cmd-1', async () => ({ ok: true, ref: 'WO-1', note: '지시서를 골라야 합니다' }))
+
+  /* `acked` 는 종착이라 다시 넘길 수 없다 — 그 사실을 함께 못 박는다. */
+  await assert.rejects(() => dispatch(store, DOMAIN, 'cmd-1', async () => ({ ok: true, ref: 'WO-2' })), /넘길 수 없다/)
+})
+
+test('★ 다시 넘기다 또 실패하면 이번 사유만 남는다', async () => {
+  const store = makeStore()
+  await propose(store, DOMAIN, SPEC, seed())
+  await approve(store, DOMAIN, 'cmd-1', { by: APPROVER, at: AT })
+
+  await dispatch(store, DOMAIN, 'cmd-1', async () => ({ ok: false, error: '첫 번째 사유' }))
+  const again = await dispatch(store, DOMAIN, 'cmd-1', async () => ({ ok: false, error: '두 번째 사유' }))
+
+  assert.equal(again.error, '두 번째 사유', '두 사유가 겹쳐 남았다')
+})

package/test/actuation-dispatch.test.ts

@@ -0,0 +1,209 @@
+/*
+ * **승인을 지나지 않은 조치는 현장에 나가지 못한다** — 배선.
+ *
+ * ── 왜 배선을 따로 보나 (2026-08-31) ─────────────────────────────────────
+ * 승인 판정 자체는 계약이 지킨다(`ops-contract/test/actuation-gate.test.ts`). 여기서 보는 것은
+ * **그 판정이 실제 경로에 서 있는가**다 — 어댑터가 불렸는가, 상태가 적혔는가, 다시 세운 뒤에도 승인이
+ * 남아 있는가.
+ *
+ * 이 저장소에서 가장 자주 나는 결함이 「자리는 있고 길이 없다」이고, 게이트가 그 부류로 나면 결과가
+ * 현장의 작업지시다. 그래서 마지막 시험이 **저장본만 남기고 다시 세운다.**
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import type { TwinCommand } from '@operato/ops-contract'
+
+import {
+  approve,
+  dispatch,
+  reject,
+  type CommandAck,
+  type CommandStore,
+  type StoredCommand
+} from '../server/service/actuation/command-dispatcher.js'
+
+const DOMAIN = 'd-1'
+const AT = '2026-08-31T02:00:00.000Z'
+const APPROVAL = { by: 'line-lead', at: AT }
+
+const irreversible = (over: Partial<TwinCommand> = {}): TwinCommand => ({
+  id: 'cmd-1',
+  instanceId: 'twin-a',
+  type: 'order.hold',
+  origin: 'ai',
+  proposedAt: AT,
+  state: 'proposed',
+  ...over
+})
+
+/** 저장본 하나 — 프로세스가 아니라 여기 산다. 그래서 다시 세워도 남는다. */
+function makeStore(initial: StoredCommand): CommandStore & { rows: Map<string, StoredCommand> } {
+  const rows = new Map<string, StoredCommand>([[initial.id, initial]])
+  return {
+    rows,
+    load: async (domainId, id) => (domainId === DOMAIN ? (rows.get(id) ?? null) : null),
+    /* 저장소를 흉내 내는 것이라 복사해 넣는다 — 같은 객체면 안 적혀도 통과한다. */
+    save: async (domainId, command) => {
+      assert.equal(domainId, DOMAIN)
+      rows.set(command.id, JSON.parse(JSON.stringify(command)))
+    },
+    create: async (domainId, command) => {
+      assert.equal(domainId, DOMAIN)
+      const copy = JSON.parse(JSON.stringify(command))
+      rows.set(command.id, copy)
+      return copy
+    }
+  }
+}
+
+const ok = (ref = 'JOB-1') => async (): Promise<CommandAck> => ({ ok: true, ref })
+
+/* ── 승인 없이는 나가지 못한다 ────────────────────────────────────────────── */
+
+test('★ 승인하지 않은 조치는 어댑터에 닿지 않는다', async () => {
+  const store = makeStore(irreversible())
+  let called = false
+
+  await assert.rejects(
+    dispatch(store, DOMAIN, 'cmd-1', async () => {
+      called = true
+      return { ok: true }
+    }),
+    /승인되지 않은/
+  )
+  assert.equal(called, false, '어댑터가 불렸다 — 게이트가 서지 않았다')
+  assert.equal(store.rows.get('cmd-1')!.state, 'proposed', '상태가 움직였다')
+})
+
+test('★ 상태만 approved 로 적고 승인 기록이 없으면 막는다 — 저장본을 손으로 고쳐도 열리지 않는다', async () => {
+  const store = makeStore(irreversible({ state: 'approved' }))
+  let called = false
+  await assert.rejects(
+    dispatch(store, DOMAIN, 'cmd-1', async () => {
+      called = true
+      return { ok: true }
+    }),
+    /승인 기록이 없는/
+  )
+  assert.equal(called, false)
+})
+
+test('★ 승인하면 나간다 — 어댑터가 돌려준 것이 남는다', async () => {
+  const store = makeStore(irreversible())
+  await approve(store, DOMAIN, 'cmd-1', APPROVAL)
+  const settled = await dispatch(store, DOMAIN, 'cmd-1', ok('JOB-77'))
+
+  assert.equal(settled.state, 'acked')
+  assert.equal(settled.dispatchRef, 'JOB-77', '되돌릴 때 무엇을 되돌릴지 말할 수 없게 된다')
+  assert.equal(store.rows.get('cmd-1')!.approval?.by, 'line-lead')
+})
+
+test('★ 넘기기 전에 「넘기는 중」을 먼저 적는다 — 그 사이에 죽으면 현장이 두 번 움직인다', async () => {
+  const store = makeStore(irreversible())
+  await approve(store, DOMAIN, 'cmd-1', APPROVAL)
+
+  let seenWhileDispatching: string | undefined
+  await dispatch(store, DOMAIN, 'cmd-1', async () => {
+    seenWhileDispatching = store.rows.get('cmd-1')!.state
+    return { ok: true, ref: 'x' }
+  })
+  assert.equal(seenWhileDispatching, 'dispatched', '어댑터를 부르는 동안 저장본이 아직 approved 였다')
+})
+
+/* ── 되돌릴 수 있는 것의 다른 문 ─────────────────────────────────────────── */
+
+test('★ 되돌릴 수 있는 조치는 사람 없이 지난다 — 시뮬과 what-if 가 이 길이다', async () => {
+  const store = makeStore(irreversible({ reversible: true }))
+  const settled = await dispatch(store, DOMAIN, 'cmd-1', ok())
+  assert.equal(settled.state, 'acked')
+})
+
+test('★ 되돌릴 수 있다고 적지 않은 것은 그 문으로 못 간다 — 모름을 통과로 읽지 않는다', async () => {
+  const store = makeStore(irreversible({ reversible: false }))
+  await assert.rejects(dispatch(store, DOMAIN, 'cmd-1', ok()))
+})
+
+/* ── 실패와 되풀이 ────────────────────────────────────────────────────────── */
+
+test('★ 어댑터가 던지면 실패로 남고 이유가 적힌다', async () => {
+  const store = makeStore(irreversible())
+  await approve(store, DOMAIN, 'cmd-1', APPROVAL)
+  const settled = await dispatch(store, DOMAIN, 'cmd-1', async () => {
+    throw new Error('MES 가 응답하지 않는다')
+  })
+
+  assert.equal(settled.state, 'failed')
+  assert.match(String(settled.error), /응답하지 않는다/)
+})
+
+test('어댑터가 이유 없이 실패해도 빈 칸으로 두지 않는다', async () => {
+  const store = makeStore(irreversible())
+  await approve(store, DOMAIN, 'cmd-1', APPROVAL)
+  const settled = await dispatch(store, DOMAIN, 'cmd-1', async () => ({ ok: false }))
+  assert.ok(String(settled.error).length > 0)
+})
+
+test('★ 실패한 것은 다시 넘길 수 있다 — 승인을 다시 받지 않는다', async () => {
+  const store = makeStore(irreversible())
+  await approve(store, DOMAIN, 'cmd-1', APPROVAL)
+  await dispatch(store, DOMAIN, 'cmd-1', async () => ({ ok: false, error: '잠시 끊겼다' }))
+
+  const retried = await dispatch(store, DOMAIN, 'cmd-1', ok('JOB-9'))
+  assert.equal(retried.state, 'acked')
+  assert.equal(retried.dispatchRef, 'JOB-9')
+})
+
+test('★ 이미 답을 받은 것은 다시 나가지 않는다 — 두 번 나가면 현장이 두 번 움직인다', async () => {
+  const store = makeStore(irreversible())
+  await approve(store, DOMAIN, 'cmd-1', APPROVAL)
+  await dispatch(store, DOMAIN, 'cmd-1', ok())
+
+  await assert.rejects(dispatch(store, DOMAIN, 'cmd-1', ok()), /넘길 수 없다/)
+})
+
+/* ── 거절 ─────────────────────────────────────────────────────────────────── */
+
+test('★ 거절하면 끝이다 — 되살아나지 않는다', async () => {
+  const store = makeStore(irreversible())
+  await reject(store, DOMAIN, 'cmd-1', { by: 'line-lead', at: AT, note: '지금 그 라인은 정지 중' })
+
+  assert.equal(store.rows.get('cmd-1')!.state, 'rejected')
+  await assert.rejects(approve(store, DOMAIN, 'cmd-1', APPROVAL))
+  await assert.rejects(dispatch(store, DOMAIN, 'cmd-1', ok()))
+})
+
+test('승인을 기다리는 중에도 거절할 수 있다', async () => {
+  const store = makeStore(irreversible())
+  await approve(store, DOMAIN, 'cmd-1', APPROVAL)
+  await reject(store, DOMAIN, 'cmd-1', { by: 'plant-manager', at: AT })
+  assert.equal(store.rows.get('cmd-1')!.state, 'rejected')
+})
+
+/* ── 재기동 ───────────────────────────────────────────────────────────────── */
+
+test('★ 승인이 재기동을 넘어 산다 — 사람이 승인한 것이 사라지면 안 된다', async () => {
+  const first = makeStore(irreversible())
+  await approve(first, DOMAIN, 'cmd-1', APPROVAL)
+  const saved: TwinCommand = JSON.parse(JSON.stringify(first.rows.get('cmd-1')))
+
+  /* 프로세스가 새로 선 것으로 본다 — 앞의 저장소 객체는 버리고 저장본만 물려준다. */
+  const second = makeStore(saved)
+  const settled = await dispatch(second, DOMAIN, 'cmd-1', ok('JOB-3'))
+
+  assert.equal(settled.state, 'acked', '이어받지 못하면 승인이 사라져 던진다')
+  assert.equal(settled.approval?.by, 'line-lead')
+})
+
+test('★ 재기동이 게이트를 열지 않는다 — 되세운 것도 같은 문을 지난다', async () => {
+  /* JSON 에는 승인 표식이 없다. 되세울 때 표식을 그냥 붙이면 재기동이 곧 우회로가 된다. */
+  const saved: TwinCommand = JSON.parse(JSON.stringify(irreversible()))
+  const store = makeStore(saved)
+  await assert.rejects(dispatch(store, DOMAIN, 'cmd-1', ok()), /승인되지 않은/)
+})
+
+test('모르는 커맨드는 조용히 넘어가지 않는다', async () => {
+  const store = makeStore(irreversible())
+  await assert.rejects(dispatch(store, DOMAIN, 'nope', ok()), /모르는 커맨드/)
+  await assert.rejects(approve(store, DOMAIN, 'nope', APPROVAL), /모르는 커맨드/)
+})