@things-factory/headless-twin 10.1.17 → 10.1.20

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

@@ -1,8 +1,21 @@
 import { CreateDateColumn, Entity, Index, Column, RelationId, ManyToOne, PrimaryGeneratedColumn, UpdateDateColumn } from 'typeorm'
 import { ObjectType, Field, ID, Int } from 'type-graphql'
 
+import type { RefusalCode, RefusalParams } from '@operato/ops-contract'
+
 import { Domain, ScalarObject, encryptedJsonColumn } from '@things-factory/shell'
 
+/** 조치 검증 상태 — 「아직 안 해 봤다」는 실패가 아니라 그 자체로 하나의 사실이다. */
+export type ActuationState = 'unverified' | 'verified' | 'failed'
+
+/** 마지막 거절 — 언어 중립 코드와 그 값들. 사람 문장은 담지 않는다. */
+export interface ActuationFailure {
+  code: RefusalCode
+  /** 거절된 시각 (ISO 8601). */
+  at: string
+  params?: RefusalParams
+}
+
 /*
  * TwinReference — 테넌트 스코프의 외부 소스 시스템 연결(실 또는 가상). 트윈 인스턴스가 인제스트되는 원천(Face2, ADR-0018).
  * 전역 인메모리 레퍼런스 레지스트리를 대체하는 영속·도메인별·어댑터 기반 엔티티.
@@ -95,6 +108,40 @@ export class TwinReference {
   @Field({ nullable: true, description: 'Last connection/sync error message, if any.' })
   lastError?: string
 
+  /**
+   * **조치를 이 주소로 실제로 넘겨 봤나** (ADR-0046 ②).
+   *
+   * ── 왜 세 값인가 ───────────────────────────────────────────────────────────
+   * 설정이 맞는 것과 저쪽이 받는 것은 다르다. 주소도 비밀값도 다 적혀 있는데 저쪽 프로세스가 그 값을
+   * 잃은 일이 실제로 있었다(§`actuationReadiness`). 그것은 **한 번 넘겨 봐야** 알 수 있고, 그래서
+   * 「아직 안 해 봤다」와 「해 봤고 됐다」와 「해 봤고 안 됐다」가 다른 사실이다.
+   *
+   *   unverified  아직 왕복이 없다 — 실패가 아니다. 새 연결과 설정이 바뀐 연결이 여기 선다
+   *   verified    `actuate` 가 받아들여졌다. 그 시각이 `actuationVerifiedAt`
+   *   failed      거절됐다. 사유는 `actuationFailure` 에 **코드로**
+   *
+   * `unverified` 를 `failed` 로 접지 않는다 — 안 해 본 것을 실패로 그리면 사람이 고칠 것을 찾으러
+   * 가고, 고칠 것이 없다.
+   */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: "Whether an actuation has actually reached this peer: 'unverified' | 'verified' | 'failed'. Null means the same as unverified; a connection that has never been tried is not a failed one." })
+  actuationState?: ActuationState
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'When an actuation was last accepted by the peer (ISO 8601 string; portable across DB drivers). Null while unverified.' })
+  actuationVerifiedAt?: string
+
+  /**
+   * 마지막 거절 — **코드와 값만 저장한다. 문장은 저장하지 않는다.**
+   *
+   * `lastError` 가 사람 문장을 저장해 두고 화면이 그것을 그대로 뿌렸다. 그러면 번역이 안 되고, 무엇이
+   * 몇 번 났는지 세지도 못하고, 커넥터가 문장을 고치는 날 옛 행과 새 행이 서로 다른 말을 한다.
+   * 코드는 `CommandAck.errorCode` 와 같은 낱말이다(ADR-0042 ③) — 표현층이 문장을 만든다.
+   */
+  @Column({ type: 'simple-json', nullable: true })
+  @Field(type => ScalarObject, { nullable: true, description: 'Why the last actuation was refused: { code, at, params? }. Language-neutral codes only — the presentation layer builds the sentence. Null when the last attempt was accepted or none was made.' })
+  actuationFailure?: ActuationFailure
+
   /**
    * 마지막 동기에서 **못 옮긴 값의 수**. `null` = 세지 않았다(0 과 다르다).
    *

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

@@ -17,6 +17,7 @@ import assert from 'node:assert/strict'
 import { CMD, MES_COMMANDS, type CommandTypeSpec } from '@operato/ops-contract'
 
 import {
+  SELF_APPROVAL,
   approve,
   dispatch,
   linkApproval,
@@ -233,6 +234,17 @@ test('★ 두 어휘가 겹치지 않는다 — 겹치면 어느 쪽으로 읽
 
 /* ── 낸 사람은 자기 것을 승인하지 못한다 ─────────────────────────────────── */
 
+test('★ 거절 낱말은 워크리스트와 **같은 글자**여야 한다 — 상수를 보면 이름을 바꿔도 안 걸린다', () => {
+  /*
+   * 이 줄만 글자를 적는다. 아래 시험들은 `SELF_APPROVAL` 을 읽으므로 **이름을 바꾸면 양쪽이 함께
+   * 바뀌어 초록**이다(실제로 심어 보고 알았다). 두 문이 같은 말을 하는지는 **글자**로만 잴 수 있다.
+   *
+   * 반대쪽은 `worklist/server/controllers/activity-approval/own-request.ts` 다. 거기도 자기 쪽 글자를
+   * 못 박는다 — 한쪽이 움직이면 그쪽이 빨개지고, 이 주석이 왜 그런지 말해 준다 (ADR-0052 ③).
+   */
+  assert.equal(SELF_APPROVAL, 'self-approval')
+})
+
 test('★ 낸 사람이 자기 조치를 승인하지 못한다 — 게이트가 시늉이 되는 자리', async () => {
   /*
    * 이 규칙이 왜 필요한지는 돌려 보고 알았다. 업무 목록은 결재선이 비어 있으면 스레드를 곧바로
@@ -242,7 +254,11 @@ test('★ 낸 사람이 자기 조치를 승인하지 못한다 — 게이트가
   const store = makeStore()
   await propose(store, DOMAIN, SPEC, seed())
 
-  await assert.rejects(approve(store, DOMAIN, 'cmd-1', { by: PROPOSER, at: AT }), /낸 사람이 자기 조치를 승인할 수 없다/)
+  /*
+   * **문장이 아니라 코드로 잡는다** (ADR-0052 ③). 워크리스트에도 같은 규칙이 서므로 두 문이 같은
+   * 낱말을 내야 하고, 문장을 못 박으면 문구를 고치는 날 규칙이 아니라 **문장이** 깨진다.
+   */
+  await assert.rejects(approve(store, DOMAIN, 'cmd-1', { by: PROPOSER, at: AT }), (e: any) => e.code === SELF_APPROVAL)
   assert.equal(store.rows.get('cmd-1')!.state, 'proposed')
 })
 
@@ -253,7 +269,7 @@ test('★ 결재선을 지나온 판정에도 같은 규칙이 걸린다 — Mys
 
   await assert.rejects(
     settleByApproval(store, DOMAIN, 'cmd-1', { approvalRef: REF, approved: true, by: PROPOSER, at: AT }),
-    /낸 사람이 자기 조치를 승인할 수 없다/
+    (e: any) => e.code === SELF_APPROVAL
   )
   assert.equal(store.rows.get('cmd-1')!.state, 'proposed')
 })

package/test/actuation-seam.test.ts

@@ -101,16 +101,22 @@ test('★ 구현만 있고 선언이 없으면 — 등록이 말하고, 게이
   assert.match(target.detail, /capabilities/, '게이트가 무엇을 넣어야 하는지 말하지 않았다')
 })
 
-test('★ 선언만 있고 구현이 없으면 — 등록은 조용하고, 게이트만 말한다', () => {
+test('★ 선언만 있고 구현이 없으면 — 등록도 게이트도 말한다', () => {
   /*
-   * 등록 검사는 이 방향을 보지 않는다(구현했는데 선언 안 한 쪽만 본다). 그래서 **게이트가 말하지
-   * 않으면 아무도 말하지 않는다.** 그 사람은 조치를 하겠다고 적어 두었으니 「관측만 냅니다」는
-   * 사실이 아니다.
+   * 이 시험은 2026-09-16 까지 「등록은 조용하고, 게이트만 말한다」였다. 그때 주석이 그 침묵을 이렇게
+   * 적어 두었다 — 「등록 검사는 이 방향을 보지 않는다. 그래서 **게이트가 말하지 않으면 아무도 말하지
+   * 않는다**」. 그 문장이 곧 결함의 서술이었다: 조치를 넘기는 자리까지 가 본 사람만 그 사실을 듣고,
+   * 커넥터를 만든 사람은 선언했으니 된 줄 안다.
+   *
+   * ADR-0036 ③ 개정으로 등록이 양방향을 본다. 게이트의 문장은 그대로다 — 그 사람은 조치를 하겠다고
+   * 적어 두었으니 「관측만 냅니다」는 여전히 사실이 아니다.
    */
   const before = warnings.length
   const type = register({ capabilities: ['live', 'actuate'], openLiveFeed: () => () => {} })
 
-  assert.equal(warnings.length, before, '등록이 이 방향을 말한다면 게이트의 문장도 다시 봐야 한다')
+  const said = warnings.slice(before).join('\n')
+  assert.ok(said.includes('actuate'), '등록이 증명 없는 선언을 말하지 않았다')
+  assert.ok(said.includes('declares'), '등록이 어느 방향의 어긋남인지 말하지 않았다')
   assert.deepEqual(capabilitiesOf(getAdapter(type)), ['live'], '능력 판정이 구현 없는 선언을 걸러 내지 않았다')
 
   const target = askGate(type, 'plant-a') as any

package/test/actuation-verification-state.test.ts

@@ -0,0 +1,94 @@
+/*
+ * ★ **한 번 넘겨 봤나** — 설정이 맞는 것과 저쪽이 받는 것은 다르다 (ADR-0046 ②).
+ *
+ * 주소도 비밀값도 다 적혀 있는데 저쪽 프로세스가 그 값을 잃은 일이 있었다(§`actuationReadiness`).
+ * 그것은 넘겨 봐야만 알고, 그래서 「아직 안 해 봤다」와 「해 봤고 됐다」와 「해 봤고 안 됐다」가
+ * 서로 다른 사실이다. 이 시험은 그 셋이 안 뭉개지는지 본다.
+ *
+ * ── 저장되는 것은 코드다 ────────────────────────────────────────────────────
+ * `lastError` 가 사람 문장을 저장해 두고 화면이 그것을 그대로 뿌렸다. 번역도 집계도 안 되고,
+ * 커넥터가 문장을 고치는 날 옛 행과 새 행이 다른 말을 한다. 그래서 사유는 코드로만 앉는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+
+import { actuationOutcomePatch } from '../server/service/reference/actuation-verification.js'
+
+const AT = '2026-09-16T04:05:06.000Z'
+
+test('받아들여지면 verified 로 서고 그 시각이 남는다', () => {
+  const patch = actuationOutcomePatch({ ok: true, ref: 'JO-1' }, AT)
+
+  assert.equal(patch.actuationState, 'verified')
+  assert.equal(patch.actuationVerifiedAt, AT)
+})
+
+test('★ 받아들여지면 지난 거절을 지운다 — 「됐는데 실패 사유가 있다」를 그리지 않게', () => {
+  assert.equal(actuationOutcomePatch({ ok: true }, AT).actuationFailure, null)
+})
+
+test('★ 거절되면 사유가 코드로 앉는다 — 문장이 아니라', () => {
+  const patch = actuationOutcomePatch(
+    { ok: false, error: '저쪽이 503 을 답했습니다', errorCode: 'peer-unavailable', errorParams: { status: 503 } },
+    AT
+  )
+
+  assert.equal(patch.actuationState, 'failed')
+  assert.deepEqual(patch.actuationFailure, { code: 'peer-unavailable', at: AT, params: { status: 503 } })
+
+  /* 사람 문장은 어디에도 안 실린다 — 그것이 이 칸을 만든 이유다. */
+  assert.ok(!JSON.stringify(patch).includes('503 을 답했습니다'))
+})
+
+test('★ 코드가 없으면 사유를 비운다 — 자리를 채우려고 문장을 옮기지 않는다', () => {
+  const patch = actuationOutcomePatch({ ok: false, error: '무언가 잘못됐습니다' }, AT)
+
+  assert.equal(patch.actuationState, 'failed', '코드가 없어도 실패는 실패다')
+  assert.equal(patch.actuationFailure, null, '모르는 것을 적었다')
+})
+
+test('★ 거절은 성공 시각을 지우지 않는다 — 「한 번이라도 닿은 적 있나」가 남아야 한다', () => {
+  const patch = actuationOutcomePatch({ ok: false, errorCode: 'peer-unavailable' }, AT)
+
+  assert.ok(!('actuationVerifiedAt' in patch), '실패가 지난 성공의 시각을 덮었다')
+})
+
+test('★ params 가 없으면 그 칸을 만들지 않는다 — 빈 객체와 「없다」는 다르다', () => {
+  const patch = actuationOutcomePatch({ ok: false, errorCode: 'not-declared' }, AT)
+
+  assert.deepEqual(patch.actuationFailure, { code: 'not-declared', at: AT })
+})
+
+/*
+ * 위 시험들은 **판단만** 본다. 판단이 옳아도 아무도 안 부르면 레퍼런스에는 아무것도 안 남는다 —
+ * 순수 시험은 부르는 사람을 못 본다.
+ *
+ * 값으로 재려면 DB 가 붙어야 해서, 여기서는 원문을 읽는다. 다만 **어느 함수 안에서 부르는지까지**
+ * 본다. 파일 전체에서 이름을 세면 **선언이 자기를 센다** — 실제로 호출을 지우고 돌려 봤는데 이
+ * 시험이 초록이었다. 세는 것은 주장이지 그 이웃이 아니다.
+ */
+const strip = (x: string) => x.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/[^\n]*/g, '')
+const src = strip(readFileSync(new URL('../server/service/reference/actuation-routing.ts', import.meta.url), 'utf8'))
+const bodyOf = (name: string) => {
+  const at = src.indexOf(`function ${name}(`)
+  assert.ok(at > 0, `${name} 이 없다`)
+  const next = src.slice(at + 1).search(/\nasync function |\nexport (async )?function /)
+  return next < 0 ? src.slice(at) : src.slice(at, at + 1 + next)
+}
+
+test('★ routeActuation 이 실제로 그것을 부른다 — 판단만 맞고 아무도 안 부르면 남는 것이 없다', () => {
+  const route = bodyOf('routeActuation')
+
+  assert.match(route, /recordActuationOutcome\(/, '조치 경로에서 그 기록이 불리지 않는다')
+  /* 기록이 본업을 막지 않는다 — 실패해도 조치 결과는 그대로 돌아간다. */
+  assert.match(route, /\.catch\(/, '기록이 실패하면 조치까지 함께 넘어진다')
+  assert.match(route, /return result/, '조치 결과를 돌려주지 않는다')
+})
+
+test('★ 기록하는 자리가 판단을 쓰고 그 값을 저장한다 — 자기 판단을 다시 짓지 않는다', () => {
+  const record = bodyOf('recordActuationOutcome')
+
+  assert.match(record, /actuationOutcomePatch\(/, '판단을 부르지 않는다 — 두 벌이 된다')
+  assert.match(record, /\.update\(/, '부른 결과를 저장하지 않는다')
+})

package/test/connector-capability-declaration.test.ts

@@ -122,12 +122,48 @@ test('선언과 구현이 맞으면 아무 말도 하지 않는다 — 소음이
   assert.equal(warnings.length, before)
 })
 
-test('선언했는데 구현이 없는 쪽은 판정이 이미 걸러 낸다 — 여기서 두 번 말하지 않는다', () => {
+test('★ 선언했는데 증명이 없는 쪽도 말해 준다 — 걸러 내고 조용하면 아무도 못 듣는다', () => {
+  /*
+   * 2026-09-16 에 뒤집었다(ADR-0036 ③ 개정). 이 시험은 그전까지 「여기서 두 번 말하지 않는다」였다 —
+   * 판정이 걸러 내니 경고는 반대 방향만 보면 된다는 읽기였다.
+   *
+   * 그런데 걸러 낸 사실을 **아무도 듣지 못한다.** 커넥터를 만든 사람은 선언했으니 된 줄 알고, 화면은
+   * 못 한다고 말하고, 그 사이에 오류가 하나도 없다. 한 방향만 보는 검사는 **없는 것을 있다고**
+   * (선언만 믿을 때) 또는 **있는 것을 없다고**(증명 형태가 하나뿐일 때) 말하게 된다. 둘 다 조용하다.
+   */
   const before = warnings.length
   const a = adapter({ capabilities: ['live'] })
   registerAdapterType(a)
-  assert.equal(warnings.length, before, '등록은 들어온 것이 없다')
-  assert.deepEqual(capabilitiesOf(a), [], '능력 판정이 구현 없는 선언을 걸러 낸다')
+
+  const said = warnings.slice(before).join('\n')
+  assert.ok(said.includes(a.type), '어느 커넥터인지 말한다')
+  assert.ok(said.includes('live'), '무엇이 증명되지 않았는지 말한다')
+  assert.ok(said.includes('openLiveFeed') && said.includes('handleInbound'), '무엇을 만들면 되는지 둘 다 말한다')
+  assert.deepEqual(capabilitiesOf(a), [], '판정은 그대로 걸러 낸다 — 경고는 그 사실을 들리게 할 뿐이다')
+})
+
+test('★ 밀어 넣는 원본도 라이브다 — handleInbound 가 live 를 증명한다', () => {
+  /*
+   * `operato-plant` 은 outbox 가 웹훅으로 밀어 넣는 쪽이라 `openLiveFeed` 가 없다. 증명을 그 하나로
+   * 두었을 때 **실 생산 사실을 나르는 유일한 커넥터가 판정에서 live 가 아니었다.**
+   *
+   * 당김이냐 밀림이냐는 상대 시스템의 성질이지 우리 능력의 종류가 아니다.
+   */
+  const pushed = adapter({ capabilities: ['live'], handleInbound: () => ({ records: [] }) })
+  const pulled = adapter({ capabilities: ['live'], openLiveFeed: () => () => {} })
+
+  assert.deepEqual(capabilitiesOf(pushed), ['live'], '밀어 넣는 쪽이 live 로 서지 않는다')
+  assert.deepEqual(capabilitiesOf(pulled), ['live'], '당겨 오는 쪽도 그대로')
+})
+
+test('★ handleInbound 만 있고 선언을 잊어도 말해 준다 — 증명이 둘이면 경고도 둘을 봐야 한다', () => {
+  const before = warnings.length
+  const a = adapter({ handleInbound: () => ({ records: [] }) })
+  registerAdapterType(a)
+
+  const said = warnings.slice(before).join('\n')
+  assert.ok(said.includes('live'), 'handleInbound 를 live 의 증명으로 세지 않는다')
+  assert.ok(said.includes(a.type))
 })
 
 test('★ 등록을 막지 않는다 — 커넥터 하나 때문에 호스트가 못 뜨면 안 된다', () => {
@@ -136,3 +172,24 @@ test('★ 등록을 막지 않는다 — 커넥터 하나 때문에 호스트가
   /* 등록은 되었고, 다만 그 능력은 선언되지 않았으므로 판정에서 빠진다 — 그 사실이 경고와 짝이다. */
   assert.deepEqual(capabilitiesOf(a), [])
 })
+
+test('★ 어댑터 목록이 내보내는 능력은 판정값이다 — 선언 원본이 아니다', async () => {
+  /*
+   * 이것이 없어서 `capabilitiesOf` 의 판정값을 **읽는 자리가 하나도 없었다.** `listAdapters()` 가
+   * `a.capabilities` 를 그대로 냈고, 연결 화면은 그것을 읽었다. 선언을 믿지 않으려고 만든 문을
+   * 아무도 지나지 않은 셈이다 — 구현 없이 능력을 적기만 하면 화면에서 가능한 것으로 보였다.
+   */
+  const { listAdapters } = await import('../server/service/reference/reference-adapter.js')
+
+  const lying = adapter({ capabilities: ['live', 'actuate'] })
+  const honest = adapter({ capabilities: ['live'], handleInbound: () => ({ records: [] }) })
+  registerAdapterType(lying)
+  registerAdapterType(honest)
+
+  const listed = listAdapters()
+  const byType = new Map(listed.map(one => [one.type, one.capabilities ?? []]))
+
+  assert.ok(listed.length > 0, '목록이 비어 있으면 이 시험이 아무것도 안 잰다')
+  assert.deepEqual(byType.get(lying.type), [], '증명 없는 선언이 목록에 그대로 나간다')
+  assert.deepEqual(byType.get(honest.type), ['live'], '증명된 능력은 그대로 나간다')
+})

package/test/rename-twin.test.ts

@@ -28,7 +28,15 @@ const src = readFileSync(FILE, 'utf8')
 const body = (() => {
   const at = src.indexOf('async renameTwinInstance')
   assert.ok(at > 0, '이름을 바꾸는 문이 있어야 한다')
-  return src.slice(at, src.indexOf('async deleteTwinInstance'))
+  /*
+   * **주석을 걷고 본다.** 이 조각은 다음 문(`deleteTwinInstance`)의 머리 주석까지 품는데, 그 주석은
+   * 삭제가 왜 `TwinEngine.remove` 를 부르는지 설명한다. 걷지 않으면 그 산문이 세어져, 이름 바꾸기가
+   * 런타임을 건드린다고 읽힌다 — 실제로 그렇게 빨개졌다. 세는 것은 코드지 그 옆의 글이 아니다.
+   */
+  return src
+    .slice(at, src.indexOf('async deleteTwinInstance'))
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/\/\/[^\n]*/g, '')
 })()
 
 test('★ 이름을 바꾸는 문이 있다 — 없어서 지우고 다시 세우는 것이 유일한 길이었다', () => {

package/test/save-intake-collision.test.ts

@@ -0,0 +1,91 @@
+/*
+ * ★ **화면 저장도 받는 사이트 충돌을 거부한다** (ADR-0046 ②-1, 2026-09-16)
+ *
+ * 들여오기에는 충돌 거부가 있는데 화면 저장(`saveTwinReference`)에는 없었다. `intakeEndpoint::intakeSiteId`
+ * 가 같은 연결 둘을 만들면 받는 문은 둘 다 200 으로 받고 경고가 0 이다 — 잘못된 공장이 실제로 만든다.
+ * 이 검사는 저장의 문이 쓰는 판정(`refuseIntakeCollision`)을 값으로 못 박는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+
+import { intakeCollisions, refuseIntakeCollision } from '../server/service/reference/connection-portability.js'
+
+const intake = { intakeEndpoint: 'https://plant.example/intake/', intakeSiteId: 'system' }
+const existing = [
+  { source: 'mes-line-a', siteName: 'Line A', connectionConfig: { baseUrl: 'https://plant.example', ...intake } }
+]
+
+test('★ 같은 받는 사이트를 가리키는 둘째 연결은 거부되고, 부딪힌 연결의 이름을 말한다', () => {
+  const r = refuseIntakeCollision('mes-line-b', { baseUrl: 'https://plant.example', ...intake }, existing)
+  assert.ok(r, '베낀 연결이 그대로 저장된다')
+  assert.equal(r.code, 'intake-site-taken')
+  assert.equal(r.params.site, 'system')
+  assert.equal(r.params.connection, 'Line A', '무엇과 부딪혔는지 말하지 않는다')
+})
+
+test('주소 끝의 / 하나로 비껴가지 않는다', () => {
+  const r = refuseIntakeCollision('mes-line-b', { intakeEndpoint: 'https://plant.example/intake', intakeSiteId: 'system' }, existing)
+  assert.ok(r)
+})
+
+test('자기 자신을 다시 저장하는 것은 충돌이 아니다', () => {
+  assert.equal(refuseIntakeCollision('mes-line-a', existing[0].connectionConfig, existing), null)
+})
+
+test('사이트를 고치면 저장된다 — 한 글자 고친 사람은 그 자리에서 지난다', () => {
+  assert.equal(refuseIntakeCollision('mes-line-b', { ...intake, intakeSiteId: 'line-b' }, existing), null)
+})
+
+test('조치 주소가 없는 연결은 부딪힐 것이 없다', () => {
+  assert.equal(refuseIntakeCollision('wms-x', { baseUrl: 'https://plant.example', siteId: 'system' }, existing), null)
+})
+
+test('★ 저장의 문이 그 판정을 부르고, 거부하면 쓰기 전에 돌아간다', () => {
+  const src = readFileSync(new URL('../server/service/reference/reference-resolver.ts', import.meta.url), 'utf8')
+  const body = src.slice(src.indexOf('async saveTwinReference('), src.indexOf('async deleteTwinReference('))
+  const check = body.indexOf('refuseIntakeCollision(')
+  const write = body.indexOf('repo.save(')
+  assert.ok(check > 0, 'saveTwinReference 가 충돌 판정을 부르지 않는다')
+  assert.ok(check < write, '판정이 쓰기 뒤에 있다 — 이미 저장된 뒤의 거부는 거부가 아니다')
+  assert.match(body, /errorCode: taken\.code/)
+})
+
+/*
+ * ★ **같은 충돌을 두 모양으로 건다** (ADR-0053 ②, 2026-09-16).
+ *
+ * 꾸러미는 `config`, `TwinReference` 행은 `connectionConfig` 다. 전에는 `config` 만 읽어서 행을 그대로
+ * 넘기면 `[]` 였다 — 오류도 경고도 없이 저장이 통과했다. 부르는 둘이 마침 옮겨서 부른 덕에 멀쩡했는데,
+ * 그건 계약이 아니라 우연이다(이 함수는 화면이 쓰라고 리졸버에서 다시 내보내진다).
+ *
+ * 옮기기가 다시 갈리는 날 **빨개지는 자리가 여기 하나**다. 그래서 「두 모양이 같은 답을 낸다」를
+ * 값으로 센다 — 결정의 내용이 그것이므로.
+ */
+const pair = [
+  { source: 'mes-line-a', ...intake },
+  { source: 'mes-line-b', ...intake }
+]
+
+test('★ DB 행 모양(connectionConfig)으로 걸어도 같은 충돌이 나온다 — 「없다」가 편한 답인 자리다', () => {
+  const rows = intakeCollisions(pair.map(({ source, ...cfg }) => ({ source, connectionConfig: cfg })))
+
+  assert.equal(rows.length, 1, '행 모양을 못 알아보고 조용히 넘어갔다')
+  assert.deepEqual(rows[0].sources, ['mes-line-a', 'mes-line-b'])
+})
+
+test('★ 두 모양이 같은 답을 낸다 — 옮기기가 갈리면 여기가 빨개진다', () => {
+  const asConfig = intakeCollisions(pair.map(({ source, ...cfg }) => ({ source, config: cfg })))
+  const asRow = intakeCollisions(pair.map(({ source, ...cfg }) => ({ source, connectionConfig: cfg })))
+
+  assert.deepEqual(asRow, asConfig)
+})
+
+test('섞여 들어와도 한 충돌로 본다 — 들여오기는 실제로 행과 꾸러미를 함께 넘긴다', () => {
+  const mixed = intakeCollisions([
+    { source: 'mes-line-a', connectionConfig: { ...intake } },
+    { source: 'mes-line-b', config: { ...intake } }
+  ])
+
+  assert.equal(mixed.length, 1, '섞인 목록에서 한쪽만 세었다')
+  assert.deepEqual(mixed[0].sources, ['mes-line-a', 'mes-line-b'])
+})

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

@@ -170,7 +170,17 @@ test('상한을 넘는 값은 오류 없이 사라지지 않는다 — 잘리되
 })
 
 test('빈 봉투에도 터지지 않는다', () => {
-  const empty = { action: undefined, bizStep: undefined, epc: undefined, orderId: undefined, bizTransaction: undefined, locationId: undefined, moverId: undefined }
+  /* `provenance` 도 이 목록에 있어야 한다 — 봉투가 비어도 「선언된 것인지」는 낼 칸이 있다. */
+  const empty = {
+    action: undefined,
+    bizStep: undefined,
+    epc: undefined,
+    orderId: undefined,
+    bizTransaction: undefined,
+    locationId: undefined,
+    moverId: undefined,
+    provenance: undefined
+  }
   assert.deepEqual(twinEventKeys(undefined), empty)
   assert.deepEqual(twinEventKeys({}), empty)
 })