@things-factory/headless-twin 10.0.19 → 10.1.0

package/test/actuation-settle.test.ts

@@ -0,0 +1,164 @@
+/*
+ * **폐루프의 배선** — 관측이 들어올 때 나간 지시와 실제로 이어지는가.
+ *
+ * 판정은 `actuation-effect.test.ts` 가 지킨다. 여기서 보는 것은 **그 판정이 유입 경로에 서 있는가**다
+ * — 봉투에서 오더 보고를 골라내는가, 저장소에 적히는가, 실패해도 관측 유입이 멈추지 않는가.
+ *
+ * 마지막 것이 특히 중요하다. 효과를 적다 실패해서 유입이 멈추면 **고치는 동안 트윈이 눈을 감는다.**
+ * 효과는 다음 보고에 다시 이을 수 있고 관측은 다시 오지 않는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { OP_EVENT } from '@operato/ops-contract'
+
+import type { CommandStore, StoredCommand } from '../server/service/actuation/command-dispatcher.js'
+import { orderObservationsIn, settleEffects } from '../server/service/actuation/settle-effects.js'
+
+const DOMAIN = 'd-1'
+const AT = '2026-09-02T09:00:00.000Z'
+
+/**
+ * 실측한 봉투 모양 그대로 — 훅과 라이브가 같은 것을 낸다.
+ *
+ * `data` 를 따로 뺀다. 처음에 `...over` 를 뒤에 두었더니 병합한 `data` 를 통째로 덮어써서 `orderId`
+ * 가 사라졌고, **시험이 이을 것이 없는 봉투로 판정을 부르고 있었다.**
+ */
+const orderEnv = ({ data, ...over }: Record<string, any> = {}) => ({
+  eventId: `e-${Math.random()}`,
+  eventType: OP_EVENT.order,
+  eventTime: AT,
+  tenantId: DOMAIN,
+  ...over,
+  data: { orderId: 'WO-20260902-005', kind: 'workorder', status: 'released', ...(data ?? {}) }
+})
+
+const otherEnv = () => ({ eventId: 'x', eventType: OP_EVENT.equipment, eventTime: AT, tenantId: DOMAIN, data: {} })
+
+function makeStore(seed: Partial<StoredCommand>[] = []) {
+  const rows = seed.map(c => ({ id: 'cmd-1', instanceId: 'twin-a', type: 'production.order', state: 'acked', ...c }) as any)
+  const written: any[] = []
+  const store: CommandStore & { written: any[]; queries: string[][] } = {
+    written,
+    queries: [],
+    load: async () => null,
+    save: async () => {},
+    create: async (_d, c) => c,
+    byDispatchRef: async (_d, refs) => {
+      store.queries.push([...refs])
+      return new Map(rows.filter(r => r.dispatchRef && refs.includes(r.dispatchRef)).map(r => [r.dispatchRef, r]))
+    },
+    recordEffects: async (_d, updates) => void written.push(...updates)
+  }
+  return store
+}
+
+/* ── 봉투에서 골라낸다 ──────────────────────────────────────────────────────── */
+
+test('★ 오더 보고만 골라낸다 — 다른 어휘를 오더로 읽지 않는다', () => {
+  const out = orderObservationsIn([orderEnv(), otherEnv(), orderEnv({ data: { orderId: 'WO-2' } })])
+
+  assert.equal(out.length, 2)
+  assert.deepEqual(out.map(o => o.orderId).sort(), ['WO-2', 'WO-20260902-005'])
+})
+
+test('★ 시각은 봉투의 것을 쓴다 — 우리가 처리한 시각이 아니다', () => {
+  const out = orderObservationsIn([orderEnv({ eventTime: '2026-08-31T01:02:03.000Z' })])
+
+  assert.equal(out[0]!.at, '2026-08-31T01:02:03.000Z')
+})
+
+test('식별자 없는 보고는 골라내지 않는다 — 이을 수 없는 것을 판정에 넘기지 않는다', () => {
+  assert.deepEqual(orderObservationsIn([orderEnv({ data: { orderId: '' } })]), [])
+})
+
+test('봉투가 없어도 터지지 않는다 — 유입 경로에서 부른다', () => {
+  assert.deepEqual(orderObservationsIn(undefined as any), [])
+  assert.deepEqual(orderObservationsIn([null, undefined] as any), [])
+})
+
+/* ── 실제로 적힌다 ─────────────────────────────────────────────────────────── */
+
+test('★ 우리가 낸 지시의 보고가 저장소에 적힌다 — 이것이 폐루프가 닫히는 순간이다', async () => {
+  const store = makeStore([{ id: 'cmd-1', dispatchRef: 'WO-20260902-005' }])
+  const out = await settleEffects({ domainId: DOMAIN, envelopes: [orderEnv()], store })
+
+  assert.equal(out.recorded, 1)
+  assert.deepEqual(store.written, [{ commandId: 'cmd-1', status: 'released', at: AT, seen: 1 }])
+})
+
+test('★ 오더 보고가 없는 묶음은 저장소를 건드리지 않는다 — 유입은 초당 수천 건이 지난다', async () => {
+  const store = makeStore([{ dispatchRef: 'WO-20260902-005' }])
+  const out = await settleEffects({ domainId: DOMAIN, envelopes: [otherEnv(), otherEnv()], store })
+
+  assert.deepEqual(store.queries, [], '오더가 없는데 저장소에 물었다')
+  assert.equal(out.recorded, 0)
+})
+
+test('★ 찾아볼 식별자만 묶어서 한 번 묻는다', async () => {
+  const store = makeStore([{ dispatchRef: 'WO-1' }])
+  await settleEffects({
+    domainId: DOMAIN,
+    envelopes: [orderEnv({ data: { orderId: 'WO-1' } }), orderEnv({ data: { orderId: 'WO-1' } }), orderEnv({ data: { orderId: 'WO-2' } })],
+    store
+  })
+
+  assert.equal(store.queries.length, 1, '보고마다 질의를 붙였다')
+  assert.deepEqual(store.queries[0]!.sort(), ['WO-1', 'WO-2'])
+})
+
+test('우리가 내지 않은 오더만 온 묶음은 아무것도 적지 않는다', async () => {
+  const store = makeStore([{ dispatchRef: 'WO-우리것' }])
+  const out = await settleEffects({ domainId: DOMAIN, envelopes: [orderEnv({ data: { orderId: 'WO-남의것' } })], store })
+
+  assert.deepEqual(store.written, [])
+  assert.equal(out.unmatched, 1)
+})
+
+test('★ 이미 적힌 효과에서 이어 센다 — 저장소가 든 값을 판정에 넘긴다', async () => {
+  const store = makeStore([
+    { id: 'cmd-1', dispatchRef: 'WO-20260902-005', effect: { status: 'released', at: AT, seen: 2 } }
+  ])
+  await settleEffects({ domainId: DOMAIN, envelopes: [orderEnv({ data: { status: 'in-progress' } })], store })
+
+  assert.equal(store.written[0]!.seen, 3)
+})
+
+/* ── 관측 유입을 멈추지 않는다 ─────────────────────────────────────────────── */
+
+test('★ 저장소가 터져도 던지지 않는다 — 고치는 동안 트윈이 눈을 감으면 안 된다', async () => {
+  const store = makeStore([{ dispatchRef: 'WO-20260902-005' }])
+  store.byDispatchRef = async () => {
+    throw new Error('연결이 끊겼다')
+  }
+
+  const out = await settleEffects({ domainId: DOMAIN, envelopes: [orderEnv()], store })
+  assert.deepEqual(out, { recorded: 0, unmatched: 0 })
+})
+
+test('★ 적다가 터져도 던지지 않는다', async () => {
+  const store = makeStore([{ dispatchRef: 'WO-20260902-005' }])
+  store.recordEffects = async () => {
+    throw new Error('쓰다 실패했다')
+  }
+
+  const out = await settleEffects({ domainId: DOMAIN, envelopes: [orderEnv()], store })
+  assert.deepEqual(out, { recorded: 0, unmatched: 0 })
+})
+
+test('★ 저장소에 이을 자리가 없으면 조용히 지나지 않는다 — 영원히 모르는 상태가 된다', async () => {
+  const said: string[] = []
+  const warn = console.warn
+  console.warn = (...a: unknown[]) => void said.push(a.join(' '))
+
+  try {
+    const store = makeStore([{ dispatchRef: 'WO-20260902-005' }])
+    delete (store as any).byDispatchRef
+
+    const out = await settleEffects({ domainId: DOMAIN, envelopes: [orderEnv()], store })
+    assert.equal(out.recorded, 0)
+    assert.ok(said.join('\n').includes('byDispatchRef'), '무엇이 없어서인지 말하지 않았다')
+  } finally {
+    console.warn = warn
+  }
+})

package/test/actuation-target.test.ts

@@ -0,0 +1,145 @@
+/*
+ * **승인된 조치를 어디로 보낼 수 있나** — 그 판정.
+ *
+ * 이 판정이 없어서 실제로 끊겨 있었다. 넘기는 리졸버가 어댑터를 찾지도 않고 「구현이 없습니다」를
+ * 답했고, MES 커넥터는 그때 이미 `actuate` 를 다 만들어 두었다. 답이 그럴듯해서 설계 문서에도 다른
+ * 레인에도 그대로 옮겼다.
+ *
+ * 그래서 여기서 지키는 것은 둘이다 — **보낼 수 있으면 보내는가**, 그리고 **못 보낼 때 무엇이 없어서
+ * 인지 말하는가.** 뒤엣것이 없으면 사람은 커넥터를 다시 만들려 든다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { actuationTarget, isActuationAllowed, type ActuationTargetInput } from '../server/service/reference/actuation-target.js'
+
+const input = (over: Partial<ActuationTargetInput> = {}): ActuationTargetInput => ({
+  instanceId: 'twin-a',
+  twinExists: true,
+  siteId: 'plant-a',
+  ref: { source: 'twin-a', adapterType: 'operato-plant' },
+  adapterRegistered: true,
+  capabilities: ['live', 'actuate'],
+  declaresActuate: true,
+  hasActuateImpl: true,
+  ...over
+})
+
+/** 거절 코드를 꺼낸다 — 통과했으면 시험을 세운다(캐스팅으로 덮지 않는다). */
+function refusalOf(t: ReturnType<typeof actuationTarget>): string {
+  assert.equal(isActuationAllowed(t), false, '거절해야 하는데 통과했다')
+  return (t as any).code
+}
+
+/* ── 보낼 수 있으면 어디로까지 답한다 ───────────────────────────────────────── */
+
+test('★ 선언과 구현이 다 있으면 보낼 수 있다 — 어디로까지 답한다', () => {
+  const t = actuationTarget(input())
+
+  assert.equal(isActuationAllowed(t), true)
+  assert.deepEqual(t, { ok: true, siteId: 'plant-a', adapterType: 'operato-plant', source: 'twin-a' })
+})
+
+test('사이트 이름의 앞뒤 공백은 다듬는다 — 주소에 그대로 들어가는 값이다', () => {
+  const t = actuationTarget(input({ siteId: '  plant-a  ' }))
+  assert.equal((t as any).siteId, 'plant-a')
+})
+
+/* ── 구현만 있고 선언이 없는 경우를 따로 말한다 ────────────────────────────── */
+
+test('★ 구현은 있는데 선언이 없으면 그렇게 말한다 — 커넥터를 다시 만들게 하지 않는다', () => {
+  /*
+   * 실제로 있던 상태다. `operato-plant` 가 `actuate` 를 만들어 두고 `capabilities: ['live','control']` 만
+   * 선언했다. 「이 원본은 조치를 받지 않습니다」로 뭉개면 고칠 한 줄을 못 찾는다.
+   */
+  const t = actuationTarget(input({ capabilities: ['live', 'control'], declaresActuate: false, hasActuateImpl: true }))
+
+  assert.equal(refusalOf(t), 'not-declared')
+  assert.match((t as any).detail, /capabilities/, '무엇을 고쳐야 하는지 말하지 않는다')
+})
+
+test('★ 구현도 선언도 없으면 다른 코드로 말한다 — 고칠 것이 다르다', () => {
+  const t = actuationTarget(input({ capabilities: ['live'], declaresActuate: false, hasActuateImpl: false }))
+
+  assert.equal(refusalOf(t), 'not-supported')
+  assert.match((t as any).detail, /관측만/)
+})
+
+test('★ 선언은 있는데 구현이 없으면 「관측만 냅니다」가 아니다 — 그 사람은 조치를 하겠다고 적었다', () => {
+  /*
+   * 만들다 만 커넥터다. 등록 검사는 이쪽을 **말하지 않는다** — 구현했는데 선언 안 한 반대 방향만 본다.
+   * 그러니 이 자리가 말하지 않으면 아무도 말하지 않고, 사람은 자기가 적어 둔 선언을 믿고 조치가 되는
+   * 줄로 읽는다.
+   */
+  const t = actuationTarget(input({ capabilities: ['live'], declaresActuate: true, hasActuateImpl: false }))
+
+  assert.equal(refusalOf(t), 'not-implemented')
+  assert.doesNotMatch((t as any).detail, /관측만/, '선언한 사람에게 「관측만 냅니다」라고 답했다')
+  assert.match((t as any).detail, /actuate/, '무엇을 만들어야 하는지 말하지 않는다')
+})
+
+test('낼 수 있나는 능력 판정만 본다 — 선언·구현 두 값은 이유를 말하기 위한 것이다', () => {
+  /*
+   * `capabilitiesOf` 가 선언과 구현을 함께 보고 답한 값이 판정의 근거다. 여기서 두 값으로 다시
+   * 판단하면 규칙이 두 벌이 되고, 한쪽만 고쳐지는 날이 온다.
+   */
+  const t = actuationTarget(input({ capabilities: ['actuate'], declaresActuate: false, hasActuateImpl: false }))
+  assert.equal(isActuationAllowed(t), true, '능력 판정의 결과를 신뢰하지 않고 여기서 다시 판단했다')
+})
+
+/* ── 모르면 보내지 않는다 ───────────────────────────────────────────────────── */
+
+test('★ 어느 사이트에서 왔는지 모르면 보내지 않는다 — 첫 번째 사이트로 보내지 않는다', () => {
+  /*
+   * 원본 하나가 여러 사이트를 낸다. 모르는 채로 아무 데나 보내면 **잘못된 공장이 실제로 만든다.**
+   * 구동(control)은 사이트를 몰라도 넘기지만 이쪽은 다르다.
+   */
+  assert.equal(refusalOf(actuationTarget(input({ siteId: undefined }))), 'no-site')
+  assert.equal(refusalOf(actuationTarget(input({ siteId: '   ' }))), 'no-site', '공백을 사이트 이름으로 읽었다')
+})
+
+test('★ 원본이 없는 트윈에는 보내지 않는다 — 시뮬레이션으로만 세운 트윈이다', () => {
+  assert.equal(refusalOf(actuationTarget(input({ ref: undefined }))), 'no-source')
+})
+
+test('★ 거절 문장이 어느 트윈인지 말한다 — 「모르는 트윈입니다」만으로는 찾을 수 없다', () => {
+  for (const over of [{ twinExists: false, ref: undefined }, { ref: undefined }, { siteId: undefined }]) {
+    const t = actuationTarget(input(over)) as any
+    assert.match(t.detail, /twin-a/, `${t.code} 가 어느 트윈인지 말하지 않는다`)
+  }
+})
+
+test('모르는 트윈은 원본을 묻기 전에 거절한다', () => {
+  assert.equal(refusalOf(actuationTarget(input({ twinExists: false, ref: undefined }))), 'unknown-twin')
+})
+
+test('등록되지 않은 커넥터는 능력을 묻기 전에 거절한다 — 물을 데가 없다', () => {
+  const t = actuationTarget(input({ adapterRegistered: false, capabilities: [], hasActuateImpl: false }))
+
+  assert.equal(refusalOf(t), 'no-adapter')
+  assert.match((t as any).detail, /operato-plant/, '어느 커넥터인지 말하지 않으면 찾을 수 없다')
+})
+
+/* ── 거절은 전부 코드를 갖는다 ──────────────────────────────────────────────── */
+
+test('★ 모든 거절에 코드와 문장이 함께 있다 — 화면이 다음 할 일을 가를 수 있게', () => {
+  const cases: Partial<ActuationTargetInput>[] = [
+    { twinExists: false },
+    { ref: undefined },
+    { adapterRegistered: false, capabilities: [], declaresActuate: false, hasActuateImpl: false },
+    { capabilities: ['live', 'control'], declaresActuate: false, hasActuateImpl: true },
+    { capabilities: ['live'], declaresActuate: true, hasActuateImpl: false },
+    { capabilities: ['live'], declaresActuate: false, hasActuateImpl: false },
+    { siteId: undefined }
+  ]
+
+  const codes = cases.map(over => {
+    const t = actuationTarget(input(over)) as any
+    assert.equal(t.ok, false)
+    assert.ok(t.code, '거절에 코드가 없다')
+    assert.ok(t.detail?.length > 10, '거절에 사람이 읽을 문장이 없다')
+    return t.code
+  })
+
+  assert.equal(new Set(codes).size, codes.length, '다른 원인이 같은 코드로 답했다 — 화면이 구별할 수 없다')
+})

package/test/canonical-ingest-vocabularies.test.ts

@@ -63,8 +63,13 @@ test('거부분이 사라지지 않는다 — 커넥터 매핑이 틀린 것을
 })
 
 test('빈 입력에서 모든 갈래가 들어온 것이 없다 — 없는 것을 만들지 않는다', () => {
-  /* 어휘가 다섯이다 — 사건 넷과 사건이 아닌 것 하나(마스터데이터). 어느 갈래도 값을 지어내지 않는다. */
-  const none = { accepted: [], rejected: [], masterData: [] }
+  /*
+   * 어휘가 다섯이다 — 사건 넷과 사건이 아닌 것 하나(마스터데이터). 어느 갈래도 값을 지어내지 않는다.
+   *
+   * `undated` 는 `masterData` 와 같은 규칙으로 언제나 있다(빈 것이면 빈 객체). 없을 때 칸을 빼면
+   * 읽는 쪽이 「이 판이 그것을 안 센다」와 「셌는데 0이다」를 구별하지 못한다.
+   */
+  const none = { accepted: [], rejected: [], masterData: [], undated: {} }
   assert.deepEqual(ingestCanonicalRecords([], 't', NOW), none)
   assert.deepEqual(ingestCanonicalRecords(null, 't', NOW), none)
 })
@@ -402,3 +407,45 @@ test('★ 단가·사용 구간·요금 기준·청구서가 한 배치에 섞
   const types = (r.accepted as any[]).map(e => e.eventType).sort()
   assert.deepEqual(types, ['energy.bill', 'energy.generation.price', 'energy.tariff.basis', 'energy.usage.period'])
 })
+
+/* ── fact type 마다 시각 칸 이름이 다르다 ──────────────────────────────────── */
+
+test('★ nonconformance 는 decidedAt 을 자기 시각으로 쓴다 — 세 번째로 밟은 자리다', () => {
+  /*
+   * [측정함 2026-09-06] backfill 뒤 mes-line-a 의 nonconformance 4건이 event_time == created_at
+   * 이었다. payload 의 `data.decidedAt` 은 2026-09-01 인데 저장된 시각은 2026-09-05 였다 — 5일 차이.
+   *
+   * push 경로에서는 안 보인다. 사실이 나자마자 보내니 몇 초 차이다. backfill 이 그 간격을 벌려서
+   * 드러냈다.
+   */
+  const got = ingestCanonicalRecords(
+    [{ subjectId: 'LOT-A', decision: 'scrap', decidedAt: '2026-09-01T02:50:51.832Z' }] as any,
+    't',
+    NOW
+  )
+  assert.equal(got.accepted[0]?.eventTime, '2026-09-01T02:50:51.832Z', 'ingest 시각으로 떨어졌다')
+  assert.deepEqual(got.undated, {}, '시각을 읽었으면 세지 않는다')
+})
+
+test('★ 시각을 못 읽으면 그 사실을 센다 — 조용히 지금 시각으로 떨어지지 않는다', () => {
+  /*
+   * 오류가 아니다. 절대값 snapshot 은 polling 순간이 맞는 시각이라 여기 세어지는 것이 정상이다.
+   * 다만 그 수가 어디에도 안 남으면 `event_time == created_at` 이 유일한 단서이고, 그것은 우연히
+   * 같은 것과 구별되지 않는다.
+   */
+  const got = ingestCanonicalRecords(
+    [{ subjectId: 'LOT-B', decision: 'scrap' }] as any,
+    't',
+    NOW
+  )
+  assert.deepEqual(got.undated, { disposition: 1 })
+})
+
+test('공통 이름이 있으면 그것이 이긴다 — 봉투 층의 판단이 가장 바깥이다', () => {
+  const got = ingestCanonicalRecords(
+    [{ subjectId: 'L', decision: 'scrap', at: '2026-09-03T00:00:00.000Z', decidedAt: '2026-09-01T00:00:00.000Z' }] as any,
+    't',
+    NOW
+  )
+  assert.equal(got.accepted[0]?.eventTime, '2026-09-03T00:00:00.000Z')
+})

package/test/capability-mapping.test.ts

@@ -81,7 +81,7 @@ test('★ 스트림라인 브릿지: 능력의 상태필드가 라이브 payload
 test('시임 문서화 · processable output(양품/불량)은 payload oee.good/scrap 으로 표면화', () => {
   // 계약 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 } }]
+    equipment: [{ id: 'c', kind: 'cutter', status: 'busy', oee: { overall: 0.8, availability: 0.9, performance: 0.9, quality: 0.98, goodCount: 10, nonconformingCount: 1 } }]
   }, 't1').find(x => x.tag === 'c')!.data
   assert.ok(d.oee, 'processable → payload.oee 존재')
   assert.equal(d.oee.good, 10, 'output.good = oee.good')

package/test/choose-recipe.test.ts

@@ -0,0 +1,117 @@
+/*
+ * ★ **어느 레시피로 만들었나 — 짐작하지 않는다.**
+ *
+ * ── 무엇이 있었나 (2026-09-05) ─────────────────────────────────────────────
+ * 계보 진단이 자재로 되짚어 `recipes.find(...)` 로 **먼저 걸리는 하나**를 골랐다. 배열 순서가 답을
+ * 정한다는 뜻이다. 그리고 한 자재에 레시피가 둘인 경우가 이미 있다 — plant 마스터 실측:
+ *
+ *   BOLT-M8  →  RCP-BOLT-STD    유효시작 2026-09-01 09:25:29.447
+ *               RCP-BOLT-FAST   유효시작 2026-09-01 09:25:29.510
+ *
+ * 빠른 방식으로 만든 볼트인데 표준 방식과 견주고 「설계와 다릅니다」가 나온다. 사람은 라인에
+ * 문제가 있다고 믿고 확인하러 간다. **틀린 답이 확신에 찬 얼굴로 나오는 것**이 그 상태였다.
+ *
+ * ── 답은 적혀 있었다 ───────────────────────────────────────────────────────
+ * 만들 때 정해지는 사실이고 커널이 오더에 싣는다(`FlowOrder.recipeKey`). 변환 사건은 그 오더를
+ * 거래 식별자로 가리키고, 계보 함수는 그 값을 이미 꺼내 놓고도 쓰지 않았다.
+ *
+ * 세 자리가 다 있었고 **마지막 연결만 없었다.**
+ *
+ * ── 왜 순수 함수인가 ───────────────────────────────────────────────────────
+ * 규칙만 따로 재려면 DB 도 트윈도 필요 없어야 한다. 여기서 값으로 못 박아 두면 다음에 「하나쯤
+ * 골라 주는 게 친절하지 않나」가 올라올 때 그 줄이 빨개진다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { chooseRecipe } from '../server/service/twin-model/choose-recipe.js'
+
+const STD = { key: 'RCP-BOLT-STD', outputs: [{ material: 'BOLT-M8' }] }
+const FAST = { key: 'RCP-BOLT-FAST', outputs: [{ material: 'BOLT-M8' }] }
+const OTHER = { key: 'RCP-CT-BLANK', outputs: [{ material: 'CT-BLANK' }] }
+
+const ALL = [STD, FAST, OTHER]
+
+/* ── 오더가 말하면 그것을 쓴다 ───────────────────────────────────────────── */
+
+test('★ 오더가 말한 레시피를 쓴다 — 판이 둘이어도 고민하지 않는다', () => {
+  const r = chooseRecipe(ALL, [STD, FAST], 'RCP-BOLT-FAST')
+
+  assert.equal(r.recipe, FAST, '오더가 말했는데 다른 것을 골랐다')
+  assert.equal(r.basis, 'order')
+})
+
+test('★ 배열 순서가 답을 바꾸지 않는다 — 옛 결함의 핵심이 이것이었다', () => {
+  const forward = chooseRecipe([STD, FAST], [STD, FAST], 'RCP-BOLT-FAST')
+  const reversed = chooseRecipe([FAST, STD], [FAST, STD], 'RCP-BOLT-FAST')
+
+  assert.equal(forward.recipe, reversed.recipe, '순서를 뒤집으니 답이 달라졌다')
+  assert.equal(forward.recipe?.key, 'RCP-BOLT-FAST')
+})
+
+/* ── 오더가 말 안 할 때 ─────────────────────────────────────────────────── */
+
+test('★ 후보가 하나면 쓴다 — 고를 것이 없으면 짐작이 아니다', () => {
+  const r = chooseRecipe(ALL, [OTHER], undefined)
+
+  assert.equal(r.recipe, OTHER)
+  assert.equal(r.basis, 'only-candidate')
+})
+
+test('★ 후보가 둘 이상이면 답하지 않는다 — 여기가 옛 결함의 자리다', () => {
+  /*
+   * 옛 코드: `recipes.find(...)` — 이 자리에서 STD 를 돌려줬다. 그 답이 틀릴 확률이 절반이고,
+   * 틀렸다는 사실은 아무 데도 안 남았다.
+   */
+  const r = chooseRecipe(ALL, [STD, FAST], undefined)
+
+  assert.equal(r.recipe, undefined, '어느 것으로 만들었는지 모르는 채로 하나를 골랐다')
+  assert.equal(r.basis, 'ambiguous')
+})
+
+/* ── 어긋남과 모름을 가른다 ─────────────────────────────────────────────── */
+
+test('★ 오더가 말한 레시피가 선언에 없으면 「모른다」가 아니라 「어긋났다」', () => {
+  /*
+   * 사람이 할 일이 다르다. 어긋남은 선언이나 원본을 고칠 일이고, 모호함은 그 개체의 기록이 없는
+   * 일이다. 한 낱말로 합치면 화면이 둘 중 어느 쪽인지 말할 수 없다.
+   */
+  const r = chooseRecipe(ALL, [STD, FAST], 'RCP-사라진것')
+
+  assert.equal(r.recipe, undefined)
+  assert.equal(r.basis, 'said-but-undeclared')
+})
+
+test('★ 후보가 아예 없으면 none — 「이 자재를 내는 레시피가 없다」', () => {
+  const r = chooseRecipe(ALL, [], undefined)
+
+  assert.equal(r.recipe, undefined)
+  assert.equal(r.basis, 'none')
+})
+
+/* ── 무너지지 않는다 ────────────────────────────────────────────────────── */
+
+test('빈 목록·빈 값에도 터지지 않는다', () => {
+  assert.equal(chooseRecipe([], [], undefined).basis, 'none')
+  assert.equal(chooseRecipe([], [], 'X').basis, 'said-but-undeclared')
+  assert.equal(chooseRecipe(ALL, [STD], '').basis, 'only-candidate', '빈 문자열은 「말했다」가 아니다')
+})
+
+/* ── 검사가 실제로 무언가를 재나 ─────────────────────────────────────────── */
+
+test('★ 이 검사가 실제로 무언가를 잰다 — 견준 것이 0이면 빨강', () => {
+  /* 네 판정이 다 나오는지. 하나라도 안 나오면 위 검사들이 같은 가지만 밟고 있는 것이다. */
+  const bases = new Set([
+    chooseRecipe(ALL, [STD, FAST], 'RCP-BOLT-FAST').basis,
+    chooseRecipe(ALL, [OTHER], undefined).basis,
+    chooseRecipe(ALL, [STD, FAST], undefined).basis,
+    chooseRecipe(ALL, [STD], 'RCP-없음').basis,
+    chooseRecipe(ALL, [], undefined).basis
+  ])
+
+  assert.deepEqual(
+    [...bases].sort(),
+    ['ambiguous', 'none', 'only-candidate', 'order', 'said-but-undeclared'],
+    `판정이 다 나오지 않는다: ${[...bases].join(' · ')}`
+  )
+})

package/test/command-store-writes-columns.test.ts

@@ -0,0 +1,126 @@
+/*
+ * ★ **칸이 있으면 쓰는 길도 있어야 한다** — `save` 가 손으로 든 목록이라 새 칸을 빠뜨린다.
+ *
+ * ── 무엇이 있었나 (2026-09-04) ──────────────────────────────────────────────
+ * 일꾼에 네 칸을 더했다 — `dispatch_note_next` · `retry` · `attempts` · `next_attempt_at`.
+ * 엔티티에 선언하고 마이그레이션까지 걸었는데 **`save` 가 그 칸을 안 썼다.** 그 함수는 쓸 칸을
+ * 손으로 들고 있고, 새 칸이 그 목록에 없었다.
+ *
+ * 그래서 일꾼이 물러섬을 계산해 넘겼는데 표에는 아무것도 안 남았다. 재기동하면 물러서던 것이
+ * 전부 즉시 재시도가 되고, 목록의 「몇 번 해 봤나」가 영원히 비어 있다. **오류는 나지 않는다.**
+ *
+ * 30분을 뒤진 끝에 찾았고, 이 저장소에서 하루 종일 「자리는 있고 길이 없다」로 부른 것과 같다 —
+ * 이번에는 **칸과 쓰는 길** 사이였다.
+ *
+ * ── 무엇을 검사하나 ────────────────────────────────────────────────────────
+ * 엔티티가 칸을 가진 필드는 `save` 가 쓰거나, 안 쓰는 이유가 아래 표에 있어야 한다. 목록을
+ * 소스에서 읽는다 — 손으로 적으면 새 칸이 조용히 빠지고 그것이 바로 이 검사가 막으려는 실패다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+
+const bare = (p: string): string =>
+  readFileSync(new URL(p, import.meta.url), 'utf8')
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/\/\/[^\n]*/g, '')
+
+const ENTITY = bare('../server/service/actuation/twin-command.ts')
+const STORE = bare('../server/service/actuation/command-store.ts')
+
+/**
+ * `save` 가 일부러 안 쓰는 칸 — 이유와 함께.
+ *
+ * 비어 있는 것이 정상이 아니다: 이 표는 「고치는 경로가 다른 칸」을 든다. 채울 때 그 이유가
+ * 「다른 함수가 쓴다」인지 「읽기 전용」인지 적어야 한다.
+ */
+const NOT_BY_SAVE: { column: string; why: string }[] = [
+  { column: 'domain', why: '열쇠 — 테넌트로 좁히는 조건이다' },
+  { column: 'instanceId', why: '낼 때 정해지고 바뀌지 않는다(create)' },
+  { column: 'type', why: '낼 때 정해지고 바뀌지 않는다(create)' },
+  { column: 'payload', why: '낼 때 정해지고 바뀌지 않는다 — 지시 내용은 제안될 때 굳는다' },
+  { column: 'origin', why: '낼 때 정해지고 바뀌지 않는다(create)' },
+  { column: 'proposedBy', why: '낼 때 정해지고 바뀌지 않는다(create)' },
+  { column: 'reversible', why: '명세에서 온다 — 낼 때 굳는다(create)' },
+  { column: 'causeRef', why: '낼 때 정해진다 — 규칙이 낸 근거(create)' },
+  { column: 'ruleRef', why: '낼 때 정해진다(create)' },
+  { column: 'effectStatus', why: '유입 경로가 `recordEffects` 로만 적는다 — 관측이 조치의 수명에 손대지 않게' },
+  { column: 'effectAt', why: '같음 — `recordEffects`' },
+  { column: 'effectSeen', why: '같음 — `recordEffects`' },
+  { column: 'createdAt', why: 'TypeORM 이 넣는다' },
+  { column: 'updatedAt', why: 'TypeORM 이 넣는다' }
+]
+
+/** 엔티티가 컬럼을 선언한 속성 이름들 — 데코레이터 다음 줄의 필드를 읽는다. */
+function entityColumns(): string[] {
+  const out: string[] = []
+  const lines = ENTITY.split('\n')
+  for (let i = 0; i < lines.length; i++) {
+    if (!/@(Column|CreateDateColumn|UpdateDateColumn|ManyToOne)\(/.test(lines[i])) continue
+    /* 데코레이터가 여럿 붙는다(@Column + @Field) — 다음 필드 줄까지 내려간다. */
+    for (let j = i + 1; j < Math.min(i + 6, lines.length); j++) {
+      const m = lines[j].match(/^\s{2}([a-zA-Z][\w]*)\??:/)
+      if (m) {
+        out.push(m[1])
+        break
+      }
+    }
+  }
+  return [...new Set(out)]
+}
+
+/** `save` 가 실제로 쓰는 속성 — 그 함수 본문에서만 읽는다. */
+function savedColumns(): string[] {
+  const start = STORE.indexOf('save: async')
+  assert.ok(start > 0, '`save` 를 못 찾았다 — 이 검사가 따라가야 한다')
+  const body = STORE.slice(start, STORE.indexOf('create: async', start))
+  return [...new Set([...body.matchAll(/^\s{10}([a-zA-Z][\w]*):/gm)].map(m => m[1]))]
+}
+
+test('★ 엔티티가 든 칸은 save 가 쓰거나 안 쓰는 이유가 적혀 있다', () => {
+  const excused = new Set(NOT_BY_SAVE.map(e => e.column))
+  const written = new Set(savedColumns())
+
+  const orphans = entityColumns().filter(c => !written.has(c) && !excused.has(c))
+
+  assert.deepEqual(
+    orphans,
+    [],
+    '엔티티에 칸이 있는데 `save` 가 안 쓴다. 값이 계산되고 표에는 안 남는다 — 오류는 나지 않는다:\n  ' +
+      orphans.join('\n  ') +
+      '\n쓰게 하거나, 다른 경로로 쓴다면 NOT_BY_SAVE 에 이유를 적는다.'
+  )
+})
+
+test('★ 이 검사가 실제로 무언가를 잰다 — 견준 것이 0이면 빨강', () => {
+  /*
+   * 정규식이 엔티티 모양을 못 따라가면 목록이 비고, 그러면 위 검사가 **초록인데 아무것도 안 재는
+   * 상태**가 된다. 오늘 이 저장소의 다른 검사가 그렇게 났다.
+   */
+  const columns = entityColumns()
+  const written = savedColumns()
+
+  assert.ok(columns.length > 15, `엔티티 칸을 ${columns.length}개만 읽었다 — 정규식이 모양을 놓쳤다`)
+  assert.ok(written.length > 5, `save 가 쓰는 칸을 ${written.length}개만 읽었다`)
+
+  /* 예외 표가 낡지 않았나 — 지워진 칸이 남아 있으면 검사를 넓혀 주는 척만 한다. */
+  const known = new Set(columns)
+  const stale = NOT_BY_SAVE.map(e => e.column).filter(c => !known.has(c))
+  assert.deepEqual(stale, [], `예외 표에 있는데 엔티티에 없다:\n  ${stale.join('\n  ')}`)
+
+  /* 이유 없는 예외는 예외가 아니다. */
+  const mute = NOT_BY_SAVE.filter(e => !e.why?.trim()).map(e => e.column)
+  assert.deepEqual(mute, [], `이유 없이 예외로 올렸다:\n  ${mute.join('\n  ')}`)
+})
+
+test('★ 일꾼이 쓰는 네 칸이 실제로 save 를 지난다', () => {
+  /*
+   * 위 검사는 목록 대조라 예외 표에 올리면 통과한다. 이 넷은 **물러섬이 표에 남는 근거**여서
+   * 예외가 될 수 없다 — 이름으로 못 박는다.
+   */
+  const written = new Set(savedColumns())
+
+  for (const c of ['dispatchNoteNext', 'retry', 'attempts', 'nextAttemptAt']) {
+    assert.ok(written.has(c), `save 가 ${c} 를 안 쓴다 — 물러섬이 재기동에 사라진다`)
+  }
+})