@things-factory/headless-twin 10.0.18 → 10.1.0

package/test/reference-hook.test.ts

@@ -12,7 +12,18 @@
  */
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
-import { HOOK_STATUS, secretFromHeaders, secretMatches, producedInstance } from '../server/service/reference/hook-contract.js'
+
+import { WEBHOOK_STATUS, webhookSenderAction } from '@operato/ops-contract'
+import { signWebhook, WEBHOOK_HEADER } from '@operato/ops-contract/webhook'
+
+import {
+  authorizeHook,
+  producedInstance,
+  secretFromHeaders,
+  secretMatches,
+  seqOf,
+  withSeq
+} from '../server/service/reference/hook-contract.js'
 
 test('★ 비밀값을 두 가지 방식으로 받는다 — 밀어 주는 쪽의 관습이 갈린다', () => {
   assert.equal(secretFromHeaders({ 'x-twin-hook-secret': 'abc' }), 'abc')
@@ -54,33 +65,113 @@ test('★ 그 연결이 만든 트윈만 받는다 — 남의 트윈에 밀어
   assert.equal(producedInstance({}, 'twin-a'), undefined)
 })
 
-test('★ 응답 코드가 재시도로 풀리는 것과 그렇지 않은 것을 가른다', () => {
+test('★ 응답 코드 표가 계약에 있다 — 여기에 두 번째 벌을 만들지 않는다', () => {
   /*
-   * 재시도해도 같은 것: 비밀값이 다르다 · 모르는 대상 · 옮길 수 없는 본문 · 커넥터가 훅을 모른다
-   * 사람이 손대야 하는 것: 트윈이 돌지 않는다
-   * 재시도하면 될 수 있는 것: 우리 쪽 오류
+   * 예전에는 이 표가 훅 규약 파일에 있었고 보내는 쪽(operato-plant)에도 있었다. 그래서 같은 409 를 양쪽이
+   * 다른 뜻으로 썼다 — 여기서는 「트윈이 안 돈다」, 저쪽에서는 「번호가 비었다」였다.
+   *
+   * 값을 여기서 다시 단정하지 않는다. 계약이 정본이고 그 시험은 계약 쪽에 있다. 여기서 지키는 것은
+   * **이 파일이 계약을 쓰고 있는가**다.
    */
-  assert.equal(HOOK_STATUS.ok, 200)
-  assert.equal(HOOK_STATUS.badPayload, 400)
-  assert.equal(HOOK_STATUS.badSecret, 401)
-  assert.equal(HOOK_STATUS.unknownTarget, 404)
-  assert.equal(HOOK_STATUS.notLive, 409)
-  assert.equal(HOOK_STATUS.failed, 500)
-  assert.equal(HOOK_STATUS.unsupported, 501)
-
-  /* 재시도해도 같은 것에 5xx 를 주면 안 된다 — 그쪽이 영원히 다시 보낸다. */
-  for (const code of [HOOK_STATUS.badPayload, HOOK_STATUS.badSecret, HOOK_STATUS.unknownTarget, HOOK_STATUS.notLive]) {
-    assert.ok(code < 500, `${code} 는 4xx 여야 한다`)
-  }
-  /* 우리 쪽 문제에는 5xx 를 준다 — 그쪽이 다시 보내야 그 사실이 살아남는다. */
-  assert.ok(HOOK_STATUS.failed >= 500)
+  assert.equal(WEBHOOK_STATUS.sequenceGap, 409, '409 는 번호가 비었다는 뜻이다')
+  assert.equal(WEBHOOK_STATUS.notLive, 503, '트윈이 안 도는 것은 503 이다')
 })
 
 test('★ 트윈이 돌지 않으면 200 을 주지 않는다 — 그쪽이 그 사실을 버린다', () => {
   /*
-   * 200 은 「받아서 반영했다」는 뜻입니다. 트윈이 실시간으로 돌지 않아 한 건도 반영되지 않았는데
-   * 200 을 주면, 밀어 주는 쪽은 전달된 줄 알고 그 사실을 버립니다. 다시 보내 주지도 않습니다.
+   * 200 은 「받아서 반영했다」는 뜻이다. 트윈이 실시간으로 돌지 않아 한 건도 반영되지 않았는데 200 을
+   * 주면, 밀어 주는 쪽은 전달된 줄 알고 그 사실을 버린다.
+   *
+   * 그렇다고 4xx 를 주면 「보낸 요청이 잘못됐다」는 뜻이라 그쪽이 포기할 근거가 된다. 트윈은 누가
+   * 띄우면 다시 도므로 들고 기다리는 것이 맞다.
+   */
+  assert.notEqual(WEBHOOK_STATUS.notLive, WEBHOOK_STATUS.ok)
+  assert.equal(webhookSenderAction(WEBHOOK_STATUS.notLive), 'wait')
+})
+
+/* ── 인증 — 비밀값과 서명 ─────────────────────────────────────────────────── */
+
+const SECRET = 'shared-secret'
+const NOW = Date.parse('2026-08-31T02:00:00.000Z')
+const TS = '2026-08-31T02:00:00.000Z'
+const BODY = '{"batch":[{"seq":1,"scope":"EVENTS","record":{}}]}'
+
+test('★ 서명이 오면 서명을 본다', () => {
+  const headers = {
+    [WEBHOOK_HEADER.timestamp]: TS,
+    [WEBHOOK_HEADER.signature]: signWebhook(SECRET, TS, BODY)
+  }
+  assert.deepEqual(authorizeHook({ headers, rawBody: BODY, secret: SECRET, nowMs: NOW }), {
+    ok: true,
+    method: 'signature'
+  })
+})
+
+test('★ 서명이 없으면 비밀값을 본다 — 이미 붙어 있는 커넥터가 그 방식이다', () => {
+  const got = authorizeHook({ headers: { 'x-twin-hook-secret': SECRET }, rawBody: BODY, secret: SECRET, nowMs: NOW })
+  assert.deepEqual(got, { ok: true, method: 'secret' })
+})
+
+test('★ 서명이 왔는데 받은 바이트가 없으면 거절한다 — 확인할 수 없는 것을 통과시키지 않는다', () => {
+  /*
+   * 파싱한 객체를 다시 문자열로 만들어 확인하고 싶어지는데, 키 순서와 공백이 달라져 어차피 맞지 않는다.
+   * 맞지 않는 것을 통과시키면 서명이 있으나 마나 한 것이 된다.
    */
-  assert.notEqual(HOOK_STATUS.notLive, HOOK_STATUS.ok)
-  assert.equal(HOOK_STATUS.notLive, 409)
+  const headers = {
+    [WEBHOOK_HEADER.timestamp]: TS,
+    [WEBHOOK_HEADER.signature]: signWebhook(SECRET, TS, BODY)
+  }
+  const got = authorizeHook({ headers, rawBody: undefined, secret: SECRET, nowMs: NOW })
+  assert.equal(got.ok, false)
+  assert.match((got as any).reason, /raw body/)
+})
+
+test('★ 서명이 왔으면 비밀값 헤더로 넘어가지 않는다 — 맞는 비밀값을 함께 실어도 서명이 틀리면 거절이다', () => {
+  const headers = {
+    'x-twin-hook-secret': SECRET,
+    [WEBHOOK_HEADER.timestamp]: TS,
+    [WEBHOOK_HEADER.signature]: 'deadbeef'
+  }
+  const got = authorizeHook({ headers, rawBody: BODY, secret: SECRET, nowMs: NOW })
+  assert.equal(got.ok, false)
+})
+
+test('거절 사유가 무엇을 고칠지 말한다', () => {
+  const stale = new Date(NOW - 10 * 60_000).toISOString()
+  const headers = {
+    [WEBHOOK_HEADER.timestamp]: stale,
+    [WEBHOOK_HEADER.signature]: signWebhook(SECRET, stale, BODY)
+  }
+  const got = authorizeHook({ headers, rawBody: BODY, secret: SECRET, nowMs: NOW })
+  assert.deepEqual(got, { ok: false, reason: 'signature expired' })
+})
+
+/* ── 커서에 번호를 적는 자리 ──────────────────────────────────────────────── */
+
+test('★ 번호는 폴링이 쓰는 커서와 같은 자리에 산다 — 진행 위치를 두 벌로 두지 않는다', () => {
+  const before = { streams: { EVENTS: { since: '2026-08-30T00:00:00.000Z', seen: ['a'] } }, firstAttachedAt: 'x' }
+  const after = withSeq(before, 'EVENTS', 918342)
+
+  assert.equal(seqOf(after, 'EVENTS'), 918342)
+  assert.equal((after as any).streams.EVENTS.since, before.streams.EVENTS.since, 'since 를 지우지 않는다')
+  assert.deepEqual((after as any).streams.EVENTS.seen, ['a'], 'seen 을 지우지 않는다')
+  assert.equal((after as any).firstAttachedAt, 'x', '커서의 다른 항목을 지우지 않는다')
+})
+
+test('★ 다른 흐름의 번호를 건드리지 않는다 — 한 단위를 올리면서 다른 단위를 되돌리면 그 구간이 다시 온다', () => {
+  const before = { streams: { EVENTS: { seq: 10 }, MASTER: { seq: 4 } } }
+  const after = withSeq(before, 'EVENTS', 11)
+  assert.equal(seqOf(after, 'EVENTS'), 11)
+  assert.equal(seqOf(after, 'MASTER'), 4)
+})
+
+test('번호가 없는 흐름은 「모른다」다 — 0 으로 메우지 않는다', () => {
+  assert.equal(seqOf(undefined, 'EVENTS'), undefined)
+  assert.equal(seqOf({}, 'EVENTS'), undefined)
+  assert.equal(seqOf({ streams: {} }, 'EVENTS'), undefined)
+  assert.equal(seqOf({ streams: { EVENTS: { since: 'x' } } }, 'EVENTS'), undefined)
+})
+
+test('커서가 없던 연결에도 번호를 적을 수 있다', () => {
+  assert.equal(seqOf(withSeq(undefined, 'EVENTS', 1), 'EVENTS'), 1)
 })

package/test/reference-links.test.ts

@@ -0,0 +1,56 @@
+/*
+ * 원본에만 있는 관계를 화면에 낼 수 있는지 판정하는 부분.
+ *
+ * 조회 자체는 DB 와 어댑터를 물어야 돌아가므로 테스트가 다루지 않는다. 여기서 확인하는 것은
+ * 원본이 준 값을 그대로 믿지 않는다는 것이다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { usableLinkGroups } from '../server/service/reference/reference-link-groups.js'
+
+test('정상 그룹은 그대로 남는다', () => {
+  const got = usableLinkGroups([
+    { via: 'mes.rel.report', from: 'productionReports', tense: 'past', ids: ['PR-1'], total: 2 }
+  ])
+  assert.equal(got.length, 1)
+  assert.equal(got[0].tense, 'past')
+})
+
+test('★ 전체 수가 없는 그룹은 버린다 — 화면이 목록 길이를 전체 수로 쓰게 된다', () => {
+  /*
+   * 원본이 20개만 보내고 전체 수를 빼면, 실제 200건이 화면에 20건으로 표시된다. 오류가 나지
+   * 않으므로 아무도 알아채지 못한다.
+   */
+  const got = usableLinkGroups([{ via: 'mes.rel.report', from: 'x', ids: ['a', 'b'] } as any])
+  assert.equal(got.length, 0)
+})
+
+test('전체 수가 0 인 그룹은 버린다 — 원본이 그 축을 취급하지 않는다는 뜻이다', () => {
+  assert.equal(usableLinkGroups([{ via: 'v', from: 'f', ids: [], total: 0 }]).length, 0)
+})
+
+test('이름이 없는 그룹은 버린다 — 화면에 이름 없는 줄이 된다', () => {
+  const got = usableLinkGroups([
+    { via: '', from: 'f', ids: ['a'], total: 1 },
+    { via: '   ', from: 'f', ids: ['a'], total: 1 },
+    { from: 'f', ids: ['a'], total: 1 } as any
+  ])
+  assert.equal(got.length, 0)
+})
+
+test('원본이 아무것도 안 주거나 목록에 빈 값이 섞여도 견딘다', () => {
+  assert.deepEqual(usableLinkGroups(undefined), [])
+  assert.deepEqual(usableLinkGroups(null), [])
+  assert.equal(usableLinkGroups([null as any, undefined as any]).length, 0)
+})
+
+test('★ 이 테스트가 실제로 무언가를 확인한다 — 통과와 탈락이 둘 다 있어야 한다', () => {
+  const got = usableLinkGroups([
+    { via: 'ok', from: 'f', ids: ['a'], total: 1 },
+    { via: 'no-total', from: 'f', ids: ['a'] } as any,
+    { via: '', from: 'f', ids: ['a'], total: 5 }
+  ])
+  assert.equal(got.length, 1, '통과한 것이 하나여야 한다')
+  assert.equal(got[0].via, 'ok')
+})

package/test/retry-plan.test.ts

@@ -0,0 +1,139 @@
+/*
+ * ★ **다시 넘길 것인가, 언제인가** — 일꾼의 판단 전부.
+ *
+ * ── 왜 이 판단이 필요한가 (2026-09-04) ─────────────────────────────────────
+ * 승인 직후에 한 번 보내는 것만 있었다. 그래서 **커밋과 발신 사이에 프로세스가 죽으면** 그
+ * 조치는 `approved` 로 남고 스스로 나가지 않았다. 그리고 실패한 것을 다시 보내는 것은 사람이
+ * 시켜야 했다.
+ *
+ * ── 실패가 다 같지 않다 (2026-09-02 실측) ──────────────────────────────────
+ * 저쪽 인증 정보가 없어 503 이었던 것(고치면 됨)과 `ITEM-1` 이 400 이었던 것(고쳐도 이 조치로는
+ * 안 됨)이 같은 모양이었다. 다 다시 하면 없는 자재를 끝없이 두드리고, 다 포기하면 저쪽을 고쳐
+ * 놓고도 안 나간다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  AFTER_FIX_PERIOD_MS,
+  AGAIN_BACKOFF_MS,
+  retryDecisionOf
+} from '../server/service/actuation/retry-plan.js'
+
+const NOW = 1_800_000_000_000
+const at = (over: Record<string, unknown> = {}) =>
+  retryDecisionOf({ state: 'failed', dispatchable: true, nowMs: NOW, ...over } as any)
+
+/* ── 첫 시도 — 승인 직후 발신이 놓친 것을 줍는다 ─────────────────────────── */
+
+test('★ 승인됐는데 한 번도 안 나간 것은 바로 집는다 — 그 창이 이 일꾼의 존재 이유다', () => {
+  const d = at({ state: 'approved', attempts: 0 })
+
+  assert.equal(d.take, true)
+  assert.equal(d.attempt, 1)
+})
+
+test('★ 첫 시도는 멱등을 묻지 않는다 — 한 번뿐이라 두 건이 설 수 없다', () => {
+  assert.equal(at({ state: 'approved', attempts: 0, idempotent: false }).take, true)
+})
+
+test('★ 첫 시도는 어댑터의 답을 묻지 않는다 — 아직 아무 답도 하지 않았다', () => {
+  assert.equal(at({ state: 'approved' }).take, true)
+})
+
+/* ── 재시도 — 모르면 넘기지 않는다 ──────────────────────────────────────── */
+
+test('★ 어댑터가 다시 될 일인지 말하지 않았으면 집지 않는다 — 「never」로 접지도 않는다', () => {
+  /*
+   * 모르는 것을 `never` 로 접으면 고칠 수 있는 것을 사람이 포기한다. 그래서 집지 않고 목록에
+   * 「모름」으로 남긴다 — 사람이 보고 정한다.
+   */
+  const d = at({ attempts: 1, idempotent: true })
+
+  assert.equal(d.take, false)
+  assert.equal(d.skip, 'outlook-unknown')
+})
+
+test('★ 멱등을 선언하지 않은 커넥터는 재시도하지 않는다 — 현장에 지시가 두 건 서면 안 된다', () => {
+  const d = at({ attempts: 1, retry: 'again' })
+
+  assert.equal(d.take, false)
+  assert.equal(d.skip, 'not-idempotent')
+})
+
+test('★ 영원히 안 될 것은 집지 않는다 — 사람이 새 조치를 내야 한다', () => {
+  const d = at({ attempts: 1, retry: 'never', idempotent: true })
+
+  assert.equal(d.take, false)
+  assert.equal(d.skip, 'never', '우리 쪽에 고칠 것이 없다는 뜻이다')
+})
+
+/* ── `again` — 짧게 세 번, 그다음 접는다 ────────────────────────────────── */
+
+test('★ 물러서면서 세 번 한다', () => {
+  for (const [i, expected] of AGAIN_BACKOFF_MS.entries()) {
+    const d = at({ attempts: i, retry: 'again', idempotent: true, state: i === 0 ? 'approved' : 'failed' })
+
+    assert.equal(d.take, true, `${i + 1}번째를 안 했다`)
+    assert.equal(d.attempt, i + 1)
+    assert.equal(Date.parse(d.nextAttemptAt!) - NOW, expected, `${i + 1}번째 물러섬이 다르다`)
+  }
+})
+
+test('★ 세 번을 다 쓰면 접는다 — 끝없이 두드리는 것은 소음이다', () => {
+  const d = at({ attempts: AGAIN_BACKOFF_MS.length, retry: 'again', idempotent: true })
+
+  assert.equal(d.take, false)
+  assert.equal(d.skip, 'attempts-spent')
+})
+
+/* ── `after-fix` — 접지 않는다. 이 파일에서 가장 중요한 것 ──────────────── */
+
+test('★ 설정 문제는 횟수로 접지 않는다 — 고쳐 놓고도 손으로 눌러야 하면 안 된다', () => {
+  /*
+   * 2026-09-02 사고가 그 모양이었다: 저쪽이 고쳐진 뒤 사람이 손으로 다시 넘겨서 나갔다.
+   * `after-fix` 는 재시도가 아니라 **기다리는 것**이다.
+   */
+  for (const attempts of [1, 3, 10, 100]) {
+    const d = at({ attempts, retry: 'after-fix', idempotent: true })
+
+    assert.equal(d.take, true, `${attempts}번째에 접었다`)
+    assert.equal(Date.parse(d.nextAttemptAt!) - NOW, AFTER_FIX_PERIOD_MS, '간격이 늘어났다')
+  }
+})
+
+/* ── 물러섬을 표에서 읽는다 ─────────────────────────────────────────────── */
+
+test('★ 아직 이르면 기다린다', () => {
+  const d = at({ attempts: 1, retry: 'again', idempotent: true, nextAttemptAt: new Date(NOW + 10_000).toISOString() })
+
+  assert.equal(d.take, false)
+  assert.equal(d.skip, 'backing-off')
+})
+
+test('★ 때가 되면 집는다', () => {
+  const d = at({ attempts: 1, retry: 'again', idempotent: true, nextAttemptAt: new Date(NOW - 1).toISOString() })
+
+  assert.equal(d.take, true)
+})
+
+test('★ 읽을 수 없는 시각으로 막지 않는다 — 막으면 그 조치가 표에 갇힌다', () => {
+  const d = at({ attempts: 1, retry: 'again', idempotent: true, nextAttemptAt: '언젠가' })
+
+  assert.equal(d.take, true)
+})
+
+/* ── 넘길 수 없는 상태 ──────────────────────────────────────────────────── */
+
+test('★ 종착이면 아무것도 하지 않는다', () => {
+  const d = at({ state: 'acked', dispatchable: false, attempts: 1, retry: 'again', idempotent: true })
+
+  assert.equal(d.take, false)
+  assert.equal(d.skip, 'not-dispatchable')
+})
+
+test('넘길 수 없으면 다른 어떤 값도 그것을 뒤집지 않는다', () => {
+  for (const retry of ['again', 'after-fix', 'never', undefined]) {
+    assert.equal(at({ dispatchable: false, attempts: 0, retry, idempotent: true }).skip, 'not-dispatchable')
+  }
+})

package/test/sweep-dispatch.test.ts

@@ -0,0 +1,191 @@
+/*
+ * ★ **그물이 실제로 줍는가** — 배선.
+ *
+ * 판단은 순수 함수가 지킨다(`retry-plan.test.ts`). 여기서 보는 것은 **그 답이 실제 경로에 서
+ * 있는가**다: 표를 읽었나, 어댑터를 불렀나, 시도 횟수와 다음 시각을 적었나, 한 조치가 터져도
+ * 다음을 보나.
+ *
+ * 이 저장소에서 가장 자주 나는 결함이 「자리는 있고 길이 없다」이고, 오늘 하루 그 부류를 여러 번
+ * 고쳤다. 그물이 그 부류로 나면 **승인된 조치가 조용히 안 나간다.**
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { sweepPendingDispatch } from '../server/service/actuation/sweep-dispatch.js'
+import type { CommandStore, StoredCommand } from '../server/service/actuation/command-dispatcher.js'
+
+const DOMAIN = 'd-1'
+const AT = '2026-09-04T02:00:00.000Z'
+
+const cmd = (over: Partial<StoredCommand> = {}): StoredCommand =>
+  ({
+    id: 'cmd-1',
+    instanceId: 'twin-a',
+    kind: 'production.release',
+    origin: 'rule',
+    state: 'approved',
+    reversible: false,
+    /* 되돌릴 수 없는 조치는 **승인 기록**이 있어야 넘어간다(§`asApproved`) — 그 모양이 이것이다. */
+    approval: { by: 'lead', at: AT },
+    ...over
+  }) as StoredCommand
+
+/**
+ * 표 하나와 가짜 커넥터 — `save` 가 무엇을 적었는지 본다.
+ *
+ * 의존을 인자로 받는 서명이라 여기서 다 흉내낼 수 있다. 직접 부르는 서명이었을 때는 이 시험이
+ * DB·모듈 부팅을 끌어와 아예 뜨지 않았다 — 그것이 이 파일을 그 모양으로 바꾼 이유다.
+ */
+function bench(rows: StoredCommand[], over: Record<string, unknown> = {}) {
+  const table = new Map(rows.map(r => [r.id, { ...r }]))
+  const saves: StoredCommand[] = []
+  const store: CommandStore = {
+    load: async (_d, id) => (table.has(id) ? { ...table.get(id)! } : null),
+    save: async (_d, c) => {
+      saves.push({ ...c })
+      table.set(c.id, { ...c })
+    },
+    pendingDispatch: async () => [...table.values()]
+  } as any
+
+  const calls: string[] = []
+  const deps = {
+    store,
+    /* 어댑터가 늘 받아 준다 — 「집었나」를 보는 시험이라 저쪽 사정은 다른 파일이 지킨다. */
+    actuate: async (c: any) => {
+      calls.push(c.id)
+      return { ok: true, ref: `WO-${c.id}` }
+    },
+    idempotent: async () => false,
+    ...over
+  } as any
+  return { store, table, saves, deps, calls }
+}
+
+/* ── 첫 시도를 줍는다 ─────────────────────────────────────────────────────── */
+
+test('★ 승인만 되고 안 나간 것을 줍는다 — 승인 직후 발신이 놓친 그 창이다', async () => {
+  const { table, deps, calls } = bench([cmd()])
+
+  const report = await sweepPendingDispatch(DOMAIN, deps)
+  /* 어댑터가 없으므로 `routeActuation` 이 거절한다 — 그래도 **집었다**는 것이 이 시험의 주제다. */
+  assert.equal(report.seen, 1)
+  assert.equal(table.get('cmd-1')!.state !== 'approved', true, '집지 않아 상태가 그대로다')
+})
+
+test('★ 시도 횟수와 다음 시각을 적는다 — 메모리에 두면 재기동에 사라진다', async () => {
+  const { table, deps, calls } = bench([cmd()])
+
+  await sweepPendingDispatch(DOMAIN, deps)
+  const after = table.get('cmd-1')!
+
+  assert.equal(after.attempts, 1, '첫 시도가 1로 적혀야 한다')
+  assert.ok(after.nextAttemptAt, '다음 시각이 없으면 물러섬이 재기동에 사라진다')
+  assert.ok(Date.parse(after.nextAttemptAt!) > Date.now(), '다음 시각이 과거다')
+})
+
+/* ── 집지 않는 것들 ───────────────────────────────────────────────────────── */
+
+test('★ 종착은 집지 않는다', async () => {
+  const { saves, deps } = bench([cmd({ state: 'acked', attempts: 1 })])
+
+  const report = await sweepPendingDispatch(DOMAIN, deps)
+
+  assert.equal(report.dispatched, 0)
+  assert.equal(report.skipped['not-dispatchable'], 1)
+  assert.deepEqual(saves, [], '집지 않았는데 표를 고쳤다')
+})
+
+test('★ 어댑터가 다시 될 일인지 말하지 않았으면 집지 않는다 — 목록에 「모름」으로 남는다', async () => {
+  const { deps, store } = bench([cmd({ state: 'failed', attempts: 1, error: '저쪽이 안 받았습니다' })])
+
+  const report = await sweepPendingDispatch(DOMAIN, deps)
+
+  assert.equal(report.skipped['outlook-unknown'], 1)
+  assert.equal(report.dispatched, 0)
+})
+
+test('★ 멱등을 선언하지 않은 커넥터는 재시도하지 않는다', async () => {
+  const { deps, store } = bench([cmd({ state: 'failed', attempts: 1, retry: 'again' })])
+
+  const report = await sweepPendingDispatch(DOMAIN, deps)
+
+  assert.equal(report.skipped['not-idempotent'], 1)
+})
+
+test('★ 영원히 안 될 것은 집지 않는다', async () => {
+  const { deps, store } = bench([cmd({ state: 'failed', attempts: 1, retry: 'never' })])
+
+  assert.equal((await sweepPendingDispatch(DOMAIN, deps)).skipped['never'], 1)
+})
+
+test('★ 물러섬이 안 끝났으면 기다린다', async () => {
+  const later = new Date(Date.now() + 300_000).toISOString()
+  const { saves, deps } = bench([cmd({ state: 'failed', attempts: 1, retry: 'again', nextAttemptAt: later })])
+
+  const report = await sweepPendingDispatch(DOMAIN, deps)
+
+  /* 멱등 선언이 없어 그쪽에서 먼저 걸린다 — 어느 이유든 **집지 않았고 표를 안 고쳤다**가 핵심이다. */
+  assert.equal(report.dispatched, 0)
+  assert.deepEqual(saves, [])
+})
+
+/* ── 저장소가 못 내면 아무것도 하지 않는다 ──────────────────────────────── */
+
+test('★ 대기 줄을 못 내는 저장소에서는 아무것도 하지 않는다 — 옛 거동이 깨지지 않게', async () => {
+  const deps = { store: { load: async () => null, save: async () => {} }, actuate: async () => ({ ok: true }), idempotent: async () => false } as any
+
+  const report = await sweepPendingDispatch(DOMAIN, deps)
+
+  assert.deepEqual(report, { seen: 0, dispatched: 0, skipped: {} })
+})
+
+test('★ 표 읽기가 터져도 그물이 죽지 않는다', async () => {
+  const deps = {
+    store: {
+      load: async () => null,
+      save: async () => {},
+      pendingDispatch: async () => {
+        throw new Error('DB 가 없다')
+      }
+    },
+    actuate: async () => ({ ok: true }),
+    idempotent: async () => false
+  } as any
+
+  const report = await sweepPendingDispatch(DOMAIN, deps)
+  assert.equal(report.seen, 0)
+})
+
+/* ── 한 조치가 터져도 다음을 본다 ───────────────────────────────────────── */
+
+test('★ 한 조치에서 터져도 다음 조치를 본다 — 그물이 한 건에 멈추면 뒤가 다 막힌다', async () => {
+  const { deps, store } = bench([cmd({ id: 'a' }), cmd({ id: 'b' })])
+  const original = store.save
+  let first = true
+  ;(store as any).save = async (d: string, c: StoredCommand) => {
+    if (first) {
+      first = false
+      throw new Error('첫 저장이 터졌다')
+    }
+    return original!(d, c)
+  }
+
+  const report = await sweepPendingDispatch(DOMAIN, deps)
+
+  assert.equal(report.seen, 2, '둘 다 읽었다')
+  /* 하나가 터졌어도 바퀴가 끝났다 — 던지면 이 단정에 오지 못한다. */
+  assert.ok(report.dispatched + Object.values(report.skipped).reduce((a, b) => a + b, 0) >= 1)
+})
+
+/* ── 한 바퀴 상한 ─────────────────────────────────────────────────────────── */
+
+test('★ 대기 줄이 커도 한 주기를 독차지하지 않는다', async () => {
+  const many = Array.from({ length: 120 }, (_, i) => cmd({ id: `c-${i}`, state: 'acked', attempts: 1 }))
+  const { deps, store } = bench(many)
+
+  const report = await sweepPendingDispatch(DOMAIN, deps)
+
+  assert.equal(report.seen, 120, '표는 다 읽는다')
+  assert.equal(report.skipped['not-dispatchable'], 50, '한 바퀴에 보는 것은 상한까지다')
+})

package/test/twin-event-keys.test.ts

@@ -15,7 +15,7 @@ import assert from 'node:assert/strict'
 import { createRequire } from 'node:module'
 
 const req = createRequire(import.meta.url)
-const { bizStepOf, epcOf, orderOf, locationOf, equipmentIdOf, twinEventKeys } = req('../dist-server/service/twin-event/twin-event-keys.js')
+const { bizStepOf, epcOf, orderOf, bizTransactionOf, locationOf, equipmentIdOf, twinEventKeys } = req('../dist-server/service/twin-event/twin-event-keys.js')
 
 /** EPCIS ObjectEvent 한 건(입고) — 실제 인제스트가 싣는 모양. */
 const EPCIS_OBJECT = {
@@ -31,12 +31,18 @@ const EPCIS_OBJECT = {
   }
 }
 
-test('EPCIS 이벤트에서 네 축이 모두 뽑힌다', () => {
+test('EPCIS 이벤트에서 축이 모두 뽑히고, 거래는 거래 칸에 든다', () => {
   const k = twinEventKeys(EPCIS_OBJECT)
   assert.equal(k.bizStep, 'receiving')
   assert.equal(k.epc, 'urn:epc:id:sgtin:0614141.107346.2018')
-  assert.equal(k.orderId, 'urn:epc:id:gdti:0614141.402.2')
   assert.equal(k.locationId, 'urn:epc:id:sgln:0614141.00777.DOCK-3')
+  /*
+   * ── 이 기대가 옮겨졌다 (2026-09-05 사용자 결정) ────────────────────────────
+   * 전에는 이 GDTI 가 `orderId` 로 뽑혔다. 그래서 한 오더의 이력이 색인 안에서 두 쪽으로
+   * 갈라졌다 — 운영 델타는 `order-1`, EPCIS 는 GDTI. 이제 칸이 둘이다.
+   */
+  assert.equal(k.bizTransaction, 'urn:epc:id:gdti:0614141.402.2')
+  assert.equal(k.orderId, undefined, '거래 식별자가 오더 칸에 앉았다')
 })
 
 test('식별자는 끝마디가 아니라 전체를 저장한다 — 부분일치 검색이 양방향으로 성립해야 한다', () => {
@@ -86,8 +92,16 @@ test('★ 운영 델타의 오더는 `orderId` 다 — 이 시험이 결함을
     orderOf({ data: { orderId: 'WO-1', bizTransactionList: [{ bizTransaction: 'urn:epc:id:gdti:0614141.402.2' }] } }),
     'WO-1'
   )
-  /* 오더를 말하지 않는 EPCIS 는 거래로 내려간다(전과 같다). */
-  assert.equal(orderOf({ data: { bizTransactionList: [{ bizTransaction: 'PO-9' }] } }), 'PO-9')
+  /*
+   * ── 이 줄이 뒤집혔다 (2026-09-05 사용자 결정) ──────────────────────────────
+   * 전에는 오더를 말하지 않는 EPCIS 가 **거래로 내려갔다.** 그래서 한 칸에 두 낱말이 들었고,
+   * 한 오더의 이력이 색인 안에서 두 쪽으로 갈라졌다(실측: 어휘가 섞인 행 10,004개).
+   *
+   * 바로 위 줄이 그 위험을 이미 알고 있었다 — 「거래와 오더는 같은 것이 아닐 수 있다」. 알면서
+   * 같은 칸에 넣고 있었다. 이제 갈라 든다.
+   */
+  assert.equal(orderOf({ data: { bizTransactionList: [{ bizTransaction: 'PO-9' }] } }), undefined)
+  assert.equal(bizTransactionOf({ data: { bizTransactionList: [{ bizTransaction: 'PO-9' }] } }), 'PO-9')
 })
 
 test('★ 승격 키는 **커널이 실제로 내는 델타 모양**으로 검사한다', () => {
@@ -156,7 +170,7 @@ test('상한을 넘는 값은 오류 없이 사라지지 않는다 — 잘리되
 })
 
 test('빈 봉투에도 터지지 않는다', () => {
-  const empty = { action: undefined, bizStep: undefined, epc: undefined, orderId: undefined, locationId: undefined, moverId: undefined }
+  const empty = { action: undefined, bizStep: undefined, epc: undefined, orderId: undefined, bizTransaction: undefined, locationId: undefined, moverId: undefined }
   assert.deepEqual(twinEventKeys(undefined), empty)
   assert.deepEqual(twinEventKeys({}), empty)
 })

package/test/twin-model-item-db.test.ts

@@ -153,13 +153,13 @@ test('이어진 것은 양방향이고 선언된 관계만 따른다', async ()
   const loc = await q.twinModelItem(INSTANCE, 'locations', 'weld-station', ctx)
 
   /* 들어오는 쪽 — 이 자리를 기준으로 삼는 설비 둘. 선언(`equipment.homeLocation`)이 알려 준다. */
-  const home = loc.links.incoming.find((l: any) => l.via === 'twin.rel.home' && l.from === 'equipment')
+  const home = loc.links.incoming.find((l: any) => l.via === 'ops.rel.home' && l.from === 'equipment')
   assert.ok(home, '나를 가리키는 관계가 보여야 한 걸음씩 걸을 수 있다')
   assert.deepEqual(home.ids.sort(), ['welder-1', 'welder-2'])
   assert.equal(home.total, 2)
 
   /* 나가는 쪽 — 자리는 구역을 가리킨다. 대상이 **축 밖**(공간의 구역)이라는 사실을 그대로 낸다. */
-  const area = loc.links.out.find((l: any) => l.via === 'twin.rel.area')
+  const area = loc.links.out.find((l: any) => l.via === 'ops.rel.area')
   assert.ok(area, '커널이 "밖" 이라 부른 참조도 이어진 것으로 낸다')
   assert.equal(area.target.kind, 'external', '갈 곳이 다르므로 화면이 링크를 만들지 말지 알 수 있어야 한다')
 })
@@ -168,13 +168,13 @@ test('문서에만 사는 항목의 관계도 선언대로 이어진다', async
   const recipe = await q.twinModelItem(INSTANCE, 'recipes', 'frame-recipe', ctx)
   assert.equal(recipe.provenance.basis, 'document')
 
-  const route = recipe.links.out.find((l: any) => l.via === 'twin.rel.route')
+  const route = recipe.links.out.find((l: any) => l.via === 'ops.rel.route')
   assert.deepEqual(route.ids, ['frame-route'])
 
   /* `inputs[].material` — 배열을 지나는 경로가 선언의 문법이고, 그것을 따르는 것이 선언을 존중하는 것이다. */
-  const input = recipe.links.out.find((l: any) => l.via === 'twin.rel.input')
+  const input = recipe.links.out.find((l: any) => l.via === 'ops.rel.input')
   assert.deepEqual(input.ids, ['steel'])
-  const output = recipe.links.out.find((l: any) => l.via === 'twin.rel.output')
+  const output = recipe.links.out.find((l: any) => l.via === 'ops.rel.output')
   assert.deepEqual(output.ids, ['frame'])
 })
 
@@ -216,7 +216,7 @@ test('지도의 선이 진단이 된다 — 이어진 것뿐 아니라 **끊긴
   await TwinEngine.ingestMaster(domainId, bad, 'reset')
 
   const sum = await new TwinModelQuery().twinModelSummary(INSTANCE, ctx)
-  const home = sum.edges.find((e: any) => e.from === 'equipment' && e.to === 'locations' && e.via === 'twin.rel.home')
+  const home = sum.edges.find((e: any) => e.from === 'equipment' && e.to === 'locations' && e.via === 'ops.rel.home')
   assert.ok(home, '설비→자리 선이 있어야 한다')
   assert.equal(home.linked, 3, '제대로 이어진 설비 셋')
   assert.equal(home.dangling, 1, '없는 자리를 가리키는 설비 하나 — 가장 나쁜 부류이므로 따로 센다')