@things-factory/headless-twin 10.1.17 → 10.1.18

package/server/service/reference/actuation-verification.ts

@@ -0,0 +1,43 @@
+/*
+ * 조치 왕복의 결과를 레퍼런스에 어떻게 적을 것인가 — **순수하게.**
+ *
+ * `actuation-routing.ts` 에 두면 시험이 그 파일을 들여야 하고, 그 파일은 엔티티를 값으로 들인다
+ * (데코레이터가 붙은 클래스). 가벼운 모듈로 떼어 두면 판단만 따로 확인할 수 있다.
+ *
+ * 여기서 들이는 것은 **타입뿐**이다 — 런타임에 남지 않는다.
+ */
+import type { ActuationFailure, ActuationState } from './twin-reference.js'
+import type { ActuationResult } from './reference-adapter.js'
+
+/** 레퍼런스에 적을 칸들. `actuationVerifiedAt` 이 없는 것은 「건드리지 않는다」는 뜻이다. */
+export interface ActuationOutcomePatch {
+  actuationState: ActuationState
+  actuationVerifiedAt?: string
+  actuationFailure: ActuationFailure | null
+}
+
+/**
+ * 결과 → 적을 것.
+ *
+ * ── 세 가지를 지킨다 ───────────────────────────────────────────────────────
+ * **받아들여지면 지난 거절을 지운다.** 남겨 두면 화면이 「됐는데 실패 사유가 있다」를 그린다.
+ *
+ * **거절은 성공 시각을 건드리지 않는다.** 「전에 한 번 닿았다」와 「이번에 안 됐다」는 둘 다 사실이고,
+ * 지우면 앞엣것이 사라진다 — 사람이 「한 번이라도 닿은 적 있나」를 물을 자리가 없어진다.
+ *
+ * **코드가 없으면 사유를 비운다.** 자리를 채우려고 `error` 문장을 옮기지 않는다. `lastError` 가 이미
+ * 겪었다 — 저장된 사람 문장은 번역도 집계도 안 되고, 커넥터가 그 문장을 고치는 날 옛 행과 새 행이
+ * 서로 다른 말을 한다. 모르는 것은 안 적는다.
+ */
+export function actuationOutcomePatch(result: ActuationResult, at: string): ActuationOutcomePatch {
+  if (result.ok) {
+    return { actuationState: 'verified', actuationVerifiedAt: at, actuationFailure: null }
+  }
+
+  return {
+    actuationState: 'failed',
+    actuationFailure: result.errorCode
+      ? { code: result.errorCode, at, ...(result.errorParams ? { params: result.errorParams } : {}) }
+      : null
+  }
+}

package/server/service/reference/connection-portability.ts

@@ -205,9 +205,8 @@ export function planImport(
    * 잡습니다 — 그게 실제로 더 쉽게 나는 쪽입니다(하나는 화면에서, 하나는 파일에서 생깁니다).
    */
   const after = [
-    ...existing
-      .filter(e => !seen.has(e.source))
-      .map(e => ({ source: e.source, config: (e.connectionConfig ?? {}) as Record<string, unknown> })),
+    /* 행 모양 그대로 넘긴다 — 옮기는 자리는 `intakeCollisions` 안 한 곳이다(ADR-0053 ①). */
+    ...existing.filter(e => !seen.has(e.source)),
     ...actions
       .filter((a): a is Extract<ImportAction, { connection: PortableConnection }> => a.action !== 'skip')
       .map(a => ({ source: a.connection.source, config: a.connection.config }))
@@ -267,11 +266,28 @@ export function secretEnvName(source: string, key: string): string {
  * 그대로 따라옵니다.
  */
 export function intakeCollisions(
-  connections: readonly { source: string; adapterType?: string; config?: Record<string, unknown> }[]
+  connections: readonly {
+    source: string
+    adapterType?: string
+    /** 꾸러미·계획이 쓰는 이름. */
+    config?: Record<string, unknown> | null
+    /** **DB 행이 쓰는 이름** — `TwinReference` 의 칸이다. 둘 다 받는다(ADR-0053 ①). */
+    connectionConfig?: Record<string, unknown> | null
+  }[]
 ): { intake: string; sources: string[] }[] {
   const byIntake = new Map<string, string[]>()
   for (const c of connections) {
-    const cfg = c.config ?? {}
+    /*
+     * **모양이 둘인 것을 여기서 안다** (ADR-0053 ①, 2026-09-16).
+     *
+     * 꾸러미는 `config`, `TwinReference` 행은 `connectionConfig` 다. 전에는 `config` 만 읽어서, 행을
+     * 그대로 넘기면 같은 충돌에도 `[]` 를 냈다 — 오류도 경고도 없이 **저장이 통과하고 가드는 선 채로
+     * 아무 일도 안 한다.** 부르는 쪽마다 옮기게 두면 다음 소비처가 또 밟는다(이 함수는 화면이 쓰라고
+     * 리졸버에서 다시 내보내진다).
+     *
+     * 「없다」가 편한 답인 자리라 더 위험하다 — 빨강이 아니라 **조용한 초록**으로 흐른다.
+     */
+    const cfg = c.config ?? c.connectionConfig ?? {}
     /* 받는 자리를 정하는 규칙은 커넥터의 것과 같아야 합니다 — 여기서 다시 지으면 두 벌이 됩니다. */
     const intake = String(cfg.intakeSiteId ?? cfg.siteId ?? '').trim()
     /* 조치를 낼 수 없는 연결은 부딪힐 것이 없습니다 — 주소가 없으면 아무 데도 안 갑니다. */
@@ -283,3 +299,31 @@ export function intakeCollisions(
     .filter(([, sources]) => sources.length > 1)
     .map(([intake, sources]) => ({ intake, sources: sources.sort() }))
 }
+
+/**
+ * **화면 저장의 문** — 이 연결을 이 설정으로 저장하면 다른 연결과 받는 사이트가 겹치나 (ADR-0046 ②-1).
+ *
+ * 들여오기(`planImport`)는 `intakeCollisions` 로 거부하는데 화면 저장(`saveTwinReference`)은 부르지 않아서,
+ * 연결을 베껴 이름만 바꾸면 경고 0 으로 두 트윈의 조치가 한 공장에 섰다. 판정은 같은 함수 하나로 한다.
+ * 경고가 아니라 거부이고, 사람이 그 자리에서 고치도록 **이미 그 사이트를 쓰는 연결의 이름**을 싣는다.
+ */
+export function refuseIntakeCollision(
+  source: string,
+  config: Record<string, unknown> | undefined,
+  others: readonly { source: string; siteName?: string | null; connectionConfig?: Record<string, unknown> | null }[]
+): { code: 'intake-site-taken'; message: string; params: { site: string; connection: string } } | null {
+  const rest = others.filter(o => o.source !== source)
+  /* `others` 는 DB 행이다 — 옮기지 않고 그대로 넘긴다(ADR-0053 ①). */
+  const hit = intakeCollisions([...rest, { source, config: config ?? {} }]).find(c => c.sources.includes(source))
+  if (!hit) return null
+  const connection = rest
+    .filter(o => hit.sources.includes(o.source))
+    .map(o => o.siteName || o.source)
+    .join(', ')
+  const site = String(config?.intakeSiteId ?? config?.siteId ?? '').trim()
+  return {
+    code: 'intake-site-taken',
+    message: `intake site ${site} is already used by ${connection}`,
+    params: { site, connection }
+  }
+}

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

@@ -1,4 +1,4 @@
-import type { ApprovedCommand } from '@operato/ops-contract'
+import type { ApprovedCommand, RefusalCode, RefusalParams } from '@operato/ops-contract'
 
 import type { ReferenceStep } from './reference-progress.js'
 import type { ReferenceMaster } from './reference-master.js'
@@ -482,6 +482,63 @@ export interface ActuationReadiness {
 
 import type { LiveCadence } from './live-cadence.js'
 
+/**
+ * 조치를 넘긴 결과 — **어댑터가 돌려주는 것.**
+ *
+ * 이름을 붙인 이유는 두 가지다. 익명 타입이라 소비처가 그 모양을 말할 수 없었고(`actuate` 를 감싸는
+ * 쪽이 반환형을 다시 적어야 했다), 그리고 **거절 사유를 코드로 실을 자리가 없었다** — `error` 는 사람
+ * 문장이라 저장하면 번역과 판독이 함께 굳는다.
+ *
+ * `errorCode`·`errorParams` 는 `CommandAck` 과 **같은 낱말**이다(ADR-0037 ④ · ADR-0042 ③). 셋째 이름을
+ * 만들지 않는다 — 같은 것을 세 이름으로 부르면 매핑 표가 생기고, 그 표는 커넥터가 새 코드를 내는 날
+ * 「알 수 없는 사유」로 떨어진다.
+ */
+export interface ActuationResult {
+  ok: boolean
+  ref?: string
+  /**
+   * **왜 거절됐나 — 언어 중립 코드.** 저장되는 값은 이것이고 `error` 는 아니다.
+   *
+   * `lastError` 가 사람 문장을 저장해 두고 화면이 그것을 그대로 뿌렸다. 그러면 번역도 못 하고,
+   * 무엇이 났는지 세지도 못하고, 문장을 고치는 순간 옛 행과 새 행이 달라진다.
+   */
+  errorCode?: RefusalCode
+  /** 그 코드가 가리키는 원시값들 — 표현층이 문장에 끼운다. */
+  errorParams?: RefusalParams
+  /**
+   * **받아들였으나 남은 것이 있다** — 실패가 아니다. 사람이 저쪽에서 해야 할 일이 있으면 여기 적는다.
+   *
+   * `error` 에 적지 말 것 — 실패로 읽혀 커맨드가 `failed` 로 앉고, 다시 넘기게 된다. 실제로 MES 가
+   * 「지시서를 못 붙였다」를 답했을 때 커넥터가 적을 칸이 없어 로그로만 남겼고, 트윈 쪽에서는 성공한
+   * 조치와 구별되지 않았다.
+   */
+  note?: string
+  /**
+   * 그 말 중 **다음에 할 일** 한 줄 — 원인은 위 `note` 다.
+   *
+   * 붙여 보내지 말 것. 읽는 사람은 「그래서 내가 뭘 해야 하나」를 먼저 찾고, 한 문장으로 오면
+   * **화면이 자르게 되며 자르는 규칙이 화면마다 생긴다.** 어댑터는 이미 둘로 알고 있다.
+   */
+  noteNext?: string
+  error?: string
+  /**
+   * **다시 해서 될 일인가** — 실패했을 때만.
+   *
+   *   again       그대로 다시 해 볼 만하다      못 닿았거나 저쪽이 잠깐 흔들렸다
+   *   after-fix   사람이 고친 뒤 그대로 나간다   설정 문제
+   *   never       이 조치로는 영원히 안 된다     지시 내용이 틀렸다
+   *
+   * 가르는 자리는 **「조치를 다시 낼 필요가 있나」**다. 설정이 틀린 것은 조치가 멀쩡하므로
+   * `after-fix`, 지시 내용이 틀린 것은 그 조치가 영원히 틀렸으므로 `never` 다.
+   *
+   * **문장에 담지 말 것** — 일꾼이 그것을 쓰려면 파싱해야 하고, 번역되면 깨진다.
+   *
+   * 말하지 않으면 일꾼이 **집지 않는다.** 모르는 것을 `never` 로 접으면 고칠 수 있는 것을 사람이
+   * 포기하고, `again` 으로 접으면 없는 자재를 끝없이 두드린다.
+   */
+  retry?: 'again' | 'after-fix' | 'never'
+}
+
 export interface ReferenceAdapter {
   /** 레지스트리 키 (예: 'virtual' | 'sap-ewm' | 'custom-rest'). */
   type: string
@@ -603,46 +660,7 @@ export interface ReferenceAdapter {
    * `ref` 를 **반드시** 돌려준다. 그것이 없으면 넘긴 것이 저쪽에서 무엇이 되었는지 되짚을 수 없고,
    * 되돌릴 때 무엇을 되돌릴지 말할 수 없다.
    */
-  actuate?(
-    cfg: ConnectionConfig,
-    site: SiteDescriptor,
-    command: ApprovedCommand
-  ): Promise<{
-    ok: boolean
-    ref?: string
-    /**
-     * **받아들였으나 남은 것이 있다** — 실패가 아니다. 사람이 저쪽에서 해야 할 일이 있으면 여기 적는다.
-     *
-     * `error` 에 적지 말 것 — 실패로 읽혀 커맨드가 `failed` 로 앉고, 다시 넘기게 된다. 실제로 MES 가
-     * 「지시서를 못 붙였다」를 답했을 때 커넥터가 적을 칸이 없어 로그로만 남겼고, 트윈 쪽에서는 성공한
-     * 조치와 구별되지 않았다.
-     */
-    note?: string
-    /**
-     * 그 말 중 **다음에 할 일** 한 줄 — 원인은 위 `note` 다.
-     *
-     * 붙여 보내지 말 것. 읽는 사람은 「그래서 내가 뭘 해야 하나」를 먼저 찾고, 한 문장으로 오면
-     * **화면이 자르게 되며 자르는 규칙이 화면마다 생긴다.** 어댑터는 이미 둘로 알고 있다.
-     */
-    noteNext?: string
-    error?: string
-    /**
-     * **다시 해서 될 일인가** — 실패했을 때만.
-     *
-     *   again       그대로 다시 해 볼 만하다      못 닿았거나 저쪽이 잠깐 흔들렸다
-     *   after-fix   사람이 고친 뒤 그대로 나간다   설정 문제
-     *   never       이 조치로는 영원히 안 된다     지시 내용이 틀렸다
-     *
-     * 가르는 자리는 **「조치를 다시 낼 필요가 있나」**다. 설정이 틀린 것은 조치가 멀쩡하므로
-     * `after-fix`, 지시 내용이 틀린 것은 그 조치가 영원히 틀렸으므로 `never` 다.
-     *
-     * **문장에 담지 말 것** — 일꾼이 그것을 쓰려면 파싱해야 하고, 번역되면 깨진다.
-     *
-     * 말하지 않으면 일꾼이 **집지 않는다.** 모르는 것을 `never` 로 접으면 고칠 수 있는 것을 사람이
-     * 포기하고, `again` 으로 접으면 없는 자재를 끝없이 두드린다.
-     */
-    retry?: 'again' | 'after-fix' | 'never'
-  }>
+  actuate?(cfg: ConnectionConfig, site: SiteDescriptor, command: ApprovedCommand): Promise<ActuationResult>
 
   /**
    * **저쪽이 조치를 받을 준비가 됐나** — 보내기 전에 묻는다. 선택이다.
@@ -849,19 +867,42 @@ export function groundingOf(adapter: ReferenceAdapter | undefined): {
   return { level: g.level, ...(against ? { verifiedAgainst: against } : {}) }
 }
 
-export function capabilitiesOf(adapter: ReferenceAdapter | undefined): ReferenceCapability[] {
-  if (!adapter) return []
-  const declared = new Set(adapter.capabilities ?? [])
-  const out: ReferenceCapability[] = []
-  if (declared.has('live') && typeof adapter.openLiveFeed === 'function') out.push('live')
-  if (declared.has('control') && typeof adapter.control === 'function') out.push('control')
-  if (declared.has('actuate') && typeof adapter.actuate === 'function') out.push('actuate')
+/**
+ * 능력마다 **그것을 증명하는 메서드들** — 하나라도 있으면 성립한다.
+ *
+ * ── `live` 의 증명이 왜 둘인가 (2026-09-16, ADR-0036 ③ 개정) ─────────────────
+ * 예전에는 `openLiveFeed` 하나였다. 그런데 사실이 흘러 들어오는 방식은 **상대 시스템의 성질**이지
+ * 우리 능력의 종류가 아니다 — 우리가 당겨 오면 `openLiveFeed`, 상대가 웹훅으로 밀어 넣으면
+ * `handleInbound`(계약 일급 문)다. 둘 다 「이 원본에서 사실이 계속 온다」를 증명한다.
+ *
+ * 실측: `operato-plant` 은 outbox 가 밀어 넣는 쪽이라 `openLiveFeed` 가 없다. 그래서 **실 생산
+ * 사실을 나르는 유일한 커넥터가 판정에서 live 가 아니었다.** 등록 경고는 「구현했는데 선언 안 함」
+ * 한 방향만 봐서 아무 말도 하지 않았다.
+ */
+const PROVED_BY: Record<ReferenceCapability, readonly string[]> = {
+  live: ['openLiveFeed', 'handleInbound'],
+  control: ['control'],
+  actuate: ['actuate'],
   /*
    * **선언만으로 성립한다** — 부를 메서드가 없다. 「두 번 해도 같은가」는 어댑터가 하는 일이 아니고
    * 저쪽 시스템의 성질이다. 그래서 구현 검사를 하지 않는다.
    */
-  if (declared.has('idempotent-actuation')) out.push('idempotent-actuation')
-  return out
+  'idempotent-actuation': []
+}
+
+const CAPABILITIES = Object.keys(PROVED_BY) as ReferenceCapability[]
+
+/** 그 능력을 증명하는 메서드가 실제로 붙어 있나. 증명이 필요 없는 능력은 언제나 참이다. */
+function implemented(adapter: ReferenceAdapter, capability: ReferenceCapability): boolean {
+  const methods = PROVED_BY[capability]
+  if (methods.length === 0) return true
+  return methods.some(name => typeof (adapter as any)[name] === 'function')
+}
+
+export function capabilitiesOf(adapter: ReferenceAdapter | undefined): ReferenceCapability[] {
+  if (!adapter) return []
+  const declared = new Set(adapter.capabilities ?? [])
+  return CAPABILITIES.filter(capability => declared.has(capability) && implemented(adapter, capability))
 }
 
 /* 어댑터 "타입" 레지스트리(전역·인메모리) — 레퍼런스 데이터는 DB(TwinReference), 어댑터 동작은 여기. */
@@ -888,18 +929,17 @@ const adapters = new Map<string, ReferenceAdapter>()
  */
 export function registerAdapterType(adapter: ReferenceAdapter): void {
   const declared = new Set(adapter.capabilities ?? [])
-  /* 능력 이름과 그것을 증명하는 메서드 — **한 자리에 적는다.** 두 벌이면 새 능력이 한쪽에만 늘어난다. */
-  const METHOD_OF: Record<ReferenceCapability, string> = {
-  live: 'openLiveFeed',
-  control: 'control',
-  actuate: 'actuate',
-  /* 성질 선언이라 부를 메서드가 없다 — 어댑터가 `capabilities` 에 적는 것으로 끝난다. */
-  'idempotent-actuation': ''
-}
-  const undeclared = (Object.keys(METHOD_OF) as ReferenceCapability[]).filter(
-    /* 메서드 이름이 없는 능력(선언만으로 성립하는 것)은 이 경고의 대상이 아니다. */
-    c => METHOD_OF[c] !== '' && typeof (adapter as any)[METHOD_OF[c]] === 'function' && !declared.has(c)
-  )
+
+  /*
+   * **어긋남은 양쪽으로 본다** (2026-09-16, ADR-0036 ③ 개정).
+   *
+   * 이 경고는 「구현했는데 선언 안 함」 한 방향만 봤다. 그래서 반대쪽 — 선언했는데 증명이 없는 것 —
+   * 은 `capabilitiesOf` 가 조용히 걸러 내기만 하고 아무도 그 사실을 듣지 못했다. 한 방향만 보면
+   * **있는 것을 없다고(이번 plant) 또는 없는 것을 있다고** 말하게 된다. 같은 무게로 말한다.
+   */
+  const undeclared = CAPABILITIES.filter(c => PROVED_BY[c].length > 0 && implemented(adapter, c) && !declared.has(c))
+  const unproven = CAPABILITIES.filter(c => PROVED_BY[c].length > 0 && declared.has(c) && !implemented(adapter, c))
+
   if (undeclared.length) {
     twinWarn(
       `[reference] connector "${adapter.type}" implements ${undeclared.join(' and ')} but does not declare it — ` +
@@ -907,6 +947,15 @@ export function registerAdapterType(adapter: ReferenceAdapter): void {
         'Until then the screens treat this connector as unable to do it, and a live twin cannot be created from it.'
     )
   }
+  if (unproven.length) {
+    twinWarn(
+      `[reference] connector "${adapter.type}" declares ${unproven.join(' and ')} but implements none of ` +
+        `${unproven.map(c => PROVED_BY[c].map(m => `${m}()`).join(' or ')).join(', ')} — ` +
+        'the declaration is dropped, so the screens treat this connector as unable to do it. ' +
+        'Implement one of those methods or remove the capability.'
+    )
+  }
+
   adapters.set(adapter.type, adapter)
 }
 export function getAdapter(type: string): ReferenceAdapter | undefined {
@@ -917,12 +966,20 @@ export function listAdapterTypes(): string[] {
 }
 /** 커넥터 메타데이터 목록(picker·연결 폼용). */
 /**
- * 등록된 어댑터 목록 — **선언한 능력도 함께 낸다.**
+ * 등록된 어댑터 목록 — **능력은 판정값이다. 선언 원본이 아니다.**
+ *
+ * 능력은 이 목록을 읽는 화면이 「이 원본에 무엇을 요구할 수 있나」를 판단하는 근거다.
+ *
+ * ── 왜 선언을 그대로 내지 않나 (2026-09-16, ADR-0036 ③ 개정) ────────────────
+ * 여기서 `a.capabilities` 를 그대로 냈다. 그래서 `capabilitiesOf` — 선언과 구현이 어긋나면 **없는
+ * 것으로 읽는다**는 그 문 — 의 판정값을 **읽는 자리가 하나도 없었다.** 화면은 선언을 보고 있었고,
+ * 어느 커넥터든 구현 없이 능력을 적기만 하면 가능한 것으로 보였다. 선언을 믿지 않으려고 만든 문을
+ * 아무도 지나지 않은 셈이다.
  *
- * 예전에는 `{ type, meta }` 만 냈습니다. 그런데 소비처(어댑터 목록 질의)가 `capabilities` 를 함께
- * 내보내고 있어 타입검사가 막혔고, 그 상태로는 개발 서버 빌드가 실패합니다. 능력은 이 목록을 읽는
- * 화면이 「이 원본에 무엇을 요구할 수 있나」를 판단하는 근거이므로, 빼지 않고 여기서 함께 냅니다.
+ * 커넥터 쪽에도 흔적이 남아 있었다 — `operato-plant` 주석이 「어댑터 목록은 선언한 값을 그대로
+ * 보여 주므로 남겨 두면 화면이 없는 능력을 있다고 말한다」며 선언을 손으로 줄여 두었다. 사람이
+ * 기억해서 맞추는 것은 다음 커넥터에서 끊긴다.
  */
 export function listAdapters(): { type: string; meta?: AdapterMeta; capabilities?: ReferenceCapability[] }[] {
-  return [...adapters.values()].map(a => ({ type: a.type, meta: a.meta, capabilities: a.capabilities }))
+  return [...adapters.values()].map(a => ({ type: a.type, meta: a.meta, capabilities: capabilitiesOf(a) }))
 }

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

@@ -22,6 +22,7 @@ import {
   referenceNotFound, adapterUnknown, discoveryFailed, discoveryTimedOut
 } from './discovery-result.js'
 import { refuseImportSpace } from './ingest-space.js'
+import { refuseIntakeCollision } from './connection-portability.js'
 import { startReferenceLiveFeed } from './reference-live.js'
 import { listTemplates, getTemplate } from './template-registry.js'
 
@@ -643,6 +644,21 @@ export class TwinReferenceResolver {
     const domainId = context.state.domain.id
     const repo = getRepository(TwinReference)
     const existing = await repo.findOne({ where: { domain: { id: domainId }, source } })
+    // 필드 단위 병합 — 편집 시 생략된 키(예: 마스킹된 secret)는 기존 값 유지.
+    const connectionConfig = patch.connectionConfig
+      ? { ...((existing?.connectionConfig as any) ?? {}), ...patch.connectionConfig }
+      : existing?.connectionConfig
+
+    /*
+     * 같은 받는 사이트를 가리키는 연결 둘은 **저장하는 순간 거부한다** (ADR-0046 ②-1).
+     * 들여오기(planImport)에는 있던 검사가 화면 저장에는 없어서, 연결을 베껴 이름만 바꾸면 두 트윈의
+     * 조치가 한 공장으로 갔다 — 저쪽은 200 으로 받고 실제로 만든다. 짝(intakeEndpoint·intakeSiteId)은
+     * 암호화된 칸 안에 있어 DB 유니크로 못 잡으니 여기서 잡는다(판정: connection-portability.ts).
+     */
+    const others = await repo.find({ where: { domain: { id: domainId } } })
+    const taken = refuseIntakeCollision(source, connectionConfig as any, others as any)
+    if (taken) return { ok: false, source, error: taken.message, errorCode: taken.code, errorParams: taken.params }
+
     const saved = await repo.save(
       repo.create({
         ...(existing ?? {}),
@@ -652,10 +668,7 @@ export class TwinReferenceResolver {
         siteName: patch.siteName ?? existing?.siteName,
         description: patch.description ?? existing?.description,
         adapterType: patch.adapterType ?? existing?.adapterType,
-        // 필드 단위 병합 — 편집 시 생략된 키(예: 마스킹된 secret)는 기존 값 유지.
-        connectionConfig: patch.connectionConfig
-          ? { ...((existing?.connectionConfig as any) ?? {}), ...patch.connectionConfig }
-          : existing?.connectionConfig,
+        connectionConfig,
         mappingSpec: patch.mappingSpec ?? existing?.mappingSpec,
         scopeSpec: patch.scopeSpec ?? existing?.scopeSpec,
         status: patch.status ?? existing?.status ?? 'draft'

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\(/, '부른 결과를 저장하지 않는다')
+})