@things-factory/headless-twin 10.0.19 → 10.1.0

package/server/service/index.ts

@@ -12,8 +12,10 @@ export * from './twin-state/twin-state-subscription.js'
 export * from './reference/reference-master.js'
 export * from './reference/reference-registry.js'
 export * from './reference/reference-adapter.js'
+export * from './reference/live-cadence.js'
 export * from './reference/reference-live.js'
 export * from './reference/twin-reference.js'
+export * from './reference/connection-portability.js'
 export * from './reference/template-registry.js'
 /* 커넥터 점검 하네스 — 실 원본에 붙여 무엇이 채워지고 무엇이 비는지 센다(앱을 띄우지 않는다). */
 export * from './reference/reference-probe.js'
@@ -21,6 +23,11 @@ export * from './reference/reference-probe.js'
 export * from './reference/reference-assessment.js'
 /* 도메인 어휘 카탈로그 조합(커널 SSOT 노출) — 서버측 소비자(board-ai 도구 등)가 같은 형태를 쓰도록. */
 export * from './twin-lifecycle/domain-catalog.js'
+/*
+ * 조치 — 앱이 결재선을 채우고(§`setApprovalGateway`) 판정을 옮긴다(§`settleByApproval`). 이 줄이 없으면
+ * 자리는 있는데 앱이 닿을 길이 없다.
+ */
+export * from './actuation/index.js'
 
 /* IMPORT ENTITIES AND RESOLVERS */
 import { entities as TwinEventEntities } from './twin-event/index.js'
@@ -32,7 +39,7 @@ import { entities as TwinSpaceEntities, resolvers as TwinSpaceResolvers } from '
 import { entities as TwinTargetEntities, resolvers as TwinTargetResolvers } from './twin-target/index.js'
 import { entities as TwinReferenceEntities, resolvers as TwinReferenceResolvers } from './reference/index.js'
 /* 현장에 내리는 조치 — 승인이 재기동을 넘어 살아야 하므로 표로 든다(§`actuation/twin-command.ts`). */
-import { entities as TwinActuationEntities } from './actuation/index.js'
+import { entities as TwinActuationEntities, resolvers as TwinActuationResolvers } from './actuation/index.js'
 import { resolvers as TwinStateResolvers } from './twin-state/index.js'
 import { resolvers as TwinControlResolvers } from './twin-control/index.js'
 import { entities as TwinModelEntities, resolvers as TwinModelResolvers } from './twin-model/index.js'
@@ -84,6 +91,7 @@ export const schema = {
     ...TwinSpaceResolvers,
     ...TwinTargetResolvers,
     ...TwinReferenceResolvers,
+    ...TwinActuationResolvers,
     ...TwinSubjectResolvers
   ],
   directives: {}

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

@@ -0,0 +1,165 @@
+/*
+ * **승인된 조치가 원본으로 나가는 길** — 판단은 `actuation-target.ts`, 여기는 배선.
+ *
+ * ── 무엇이 끊겨 있었나 (2026-09-02) ────────────────────────────────────────────
+ * MES 커넥터는 `actuate` 를 다 만들어 두었다. 서명·접수 판정·초안 상태까지 있었다. 그런데 넘기는
+ * 리졸버가 **어댑터를 찾지도 않고** 「구현이 없습니다」라고 답했다. 그 문장을 사실로 읽어서 설계
+ * 문서에도, 다른 레인에도 그렇게 알렸다 — 둘 다 틀렸다.
+ *
+ * 자리는 있고 길이 없는 상태다. 이 저장소에서 가장 자주 나는 결함 부류이고, 조치 경로에서 나면
+ * 결과가 하나다 — **승인은 쌓이는데 현장에는 아무것도 가지 않는다.**
+ *
+ * ── 왜 구동과 따로 두나 ───────────────────────────────────────────────────────
+ * 모양이 같아서 한 함수로 묶고 싶어진다. 묶지 않는다.
+ *
+ *   구동은 시뮬레이터를 움직인다      틀리면 시늉이 어긋난다
+ *   조치는 현장에 작업지시를 낸다      틀리면 만들지 않아도 될 것을 만든다
+ */
+import { getRepository } from '@things-factory/shell'
+
+import type { ApprovedCommand } from '@operato/ops-contract'
+
+import { TwinInstance } from '../twin-instance/twin-instance.js'
+
+import { TwinReference } from './twin-reference.js'
+import { capabilitiesOf, getAdapter, type ActuationReadiness, type SiteDescriptor } from './reference-adapter.js'
+import { APPROVAL_STANDS, actuationTarget, isActuationAllowed, type ActuationTarget } from './actuation-target.js'
+
+/** 어댑터가 답하는 모양 그대로 — 디스패처가 이 값을 커맨드 행에 적는다. */
+/**
+ * 조치를 낸 결과 — **어댑터가 답한 것을 좁히지 않고 그대로 나른다.**
+ *
+ * ── 왜 넓혔나 (2026-09-04, 인티그레이션 레인이 찾음) ────────────────────────
+ * 이 타입이 `ok`·`ref`·`error` 셋만 들고 있었다. 그래서 `routeActuation` 이 어댑터의 답을
+ * 그대로 되돌리는데 **타입은 `note`·`noteNext`·`retry` 를 버린다고 말했다.**
+ *
+ * 값은 흘렀다 — JS 객체가 키를 안 버리므로. 어제 `dispatch_note` 에 실제로 앉았다. 그런데
+ * **커넥터를 만드는 사람이 그 칸이 있다는 것을 알 방법이 없었다.** 우리가 어제 하루 종일
+ * 「자리는 있고 길이 없다」로 부른 것의 타입 판이다.
+ *
+ * 좁히지 않는다: 세 칸을 다 실어 `CommandAck` 와 같은 모양으로 둔다. 커널이 어느 칸을 어떻게
+ * 쓰는지는 `dispatch` 가 정하고, 이 자리는 나르기만 한다.
+ */
+export interface ActuationAck {
+  ok: boolean
+  /** 저쪽 문서·작업 식별자. 없으면 무엇을 되돌릴지 지목할 수 없다. */
+  ref?: string
+  /** 받아들였으나 저쪽이 덧붙인 말 — **실패가 아니다.** 원인 쪽 문장. */
+  note?: string
+  /** 그 말 중 다음에 할 일 한 줄 — 붙여 보내지 않는다. */
+  noteNext?: string
+  error?: string
+  /** 다시 해서 될 일인가 — 실패에만. 말하지 않으면 일꾼이 집지 않는다. */
+  retry?: 'again' | 'after-fix' | 'never'
+}
+
+/**
+ * 저장소를 **한 번만** 읽고, 판정과 함께 부를 것까지 돌려준다.
+ *
+ * 판정한 뒤 보낼 때 다시 읽으면 그 사이에 연결 설정이 바뀔 수 있다 — 판정한 커넥터와 실제로 부르는
+ * 커넥터가 달라진다. 그리고 같은 행을 두 번 읽을 이유가 없다.
+ */
+async function resolve(domainId: string, instanceId: string) {
+  const inst = await getRepository(TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId } })
+  const ref = inst
+    ? await getRepository(TwinReference).findOne({ where: { domain: { id: domainId }, source: instanceId } })
+    : null
+  const adapter = ref ? getAdapter(ref.adapterType) : undefined
+
+  const target = actuationTarget({
+    instanceId,
+    twinExists: !!inst,
+    siteId: (inst?.origin as any)?.siteId,
+    ...(ref ? { ref: { source: ref.source, adapterType: ref.adapterType } } : {}),
+    adapterRegistered: !!adapter,
+    capabilities: capabilitiesOf(adapter),
+    declaresActuate: !!adapter?.capabilities?.includes('actuate'),
+    hasActuateImpl: typeof adapter?.actuate === 'function'
+  })
+
+  return { target, ref, adapter }
+}
+
+/**
+ * 이 트윈의 원본에 승인된 조치를 보낸다.
+ *
+ * **거절할 때는 무엇이 없어서인지 말한다.** 「보내지 못했습니다」만 답하면 사람이 연결 설정을 열어야
+ * 하는지, 커넥터를 고쳐야 하는지, 트윈을 다시 만들어야 하는지 알 수 없다.
+ */
+export async function routeActuation(
+  domainId: string,
+  instanceId: string,
+  command: ApprovedCommand
+): Promise<ActuationAck> {
+  const { target, ref, adapter } = await resolve(domainId, instanceId)
+  if (!isActuationAllowed(target)) return { ok: false, error: `${target.detail}. ${APPROVAL_STANDS}` }
+
+  /*
+   * 여기까지 왔으면 판정이 그 둘의 존재를 이미 확인했다(§`actuationTarget`). 그래도 조용히 지나가지
+   * 않는다 — 판정과 배선이 어긋나면 그것이 결함이고, `!` 로 덮으면 그 결함이 「아무 일도 일어나지
+   * 않았다」로 나타난다.
+   */
+  if (!adapter?.actuate) {
+    return { ok: false, error: `커넥터를 찾았는데 조치를 보낼 자리가 없습니다 (${target.adapterType}). ${APPROVAL_STANDS}` }
+  }
+
+  const site: SiteDescriptor = { siteId: target.siteId }
+  return adapter.actuate(ref?.connectionConfig ?? {}, site, command)
+}
+
+/**
+ * 이 트윈이 조치를 받을 수 있나 — **넘기기 전에 화면이 먼저 알 수 있게.**
+ *
+ * 승인 화면이 「넘기기」를 보이기 전에 이것을 묻는다. 누를 수 없는 것을 보여 주고 눌렀을 때 거절하는
+ * 것보다, 왜 못 넘기는지 먼저 말하는 것이 낫다.
+ */
+export async function actuationTargetOf(domainId: string, instanceId: string): Promise<ActuationTarget> {
+  return (await resolve(domainId, instanceId)).target
+}
+
+/**
+ * **저쪽이 받을 준비가 됐나** — 넘기기 전에 묻는다. 화면이 사람을 헛걸음시키지 않게.
+ *
+ * ── 왜 `actuationTargetOf` 와 따로인가 ──────────────────────────────────────
+ * 그쪽은 **망을 타지 않는다.** 화면이 목록을 그릴 때마다 부를 수 있어야 하므로 그래야 한다.
+ * 이 함수는 커넥터가 저쪽에 물을 수 있고, 그래서 부르는 시점이 다르다 — 사람이 「넘기기」를
+ * 열었을 때다.
+ *
+ * ── 답이 문이 아니다 ────────────────────────────────────────────────────────
+ * **이 답으로 넘김을 막지 않는다.** 막으면 점검이 틀렸거나 잠깐 못 닿은 사이에 성공할 수 있었던
+ * 조치가 못 나간다. 화면이 미리 말하는 데까지가 이 함수의 일이다.
+ *
+ * 커넥터가 이 얼굴을 안 만들었으면 **「모른다」로 답한다** — 「준비됐다」가 아니다. 없는 확인을
+ * 통과로 읽으면 이 함수가 있으나 없으나 같아진다.
+ */
+export async function actuationReadinessOf(domainId: string, instanceId: string): Promise<ActuationReadiness> {
+  const { target, ref, adapter } = await resolve(domainId, instanceId)
+
+  /* 보낼 대상 자체가 없으면 저쪽에 물을 것도 없다 — 그 사실을 그대로 옮긴다. */
+  if (!isActuationAllowed(target)) {
+    return { checked: 'local', ready: false, reason: target.detail, code: target.code }
+  }
+
+  if (!adapter?.actuationReadiness) {
+    /* 확인할 길이 없다. 「준비됐다」로 답하지 않는다 — 그러면 화면이 없는 확인을 통과로 읽는다. */
+    return {
+      checked: 'local',
+      reason: `커넥터 "${target.adapterType}" 는 저쪽이 받을 준비가 됐는지 알려 주지 않습니다 — 넘겨 보고 알게 됩니다`,
+      code: 'not-checkable'
+    }
+  }
+
+  try {
+    return await adapter.actuationReadiness(ref?.connectionConfig ?? {}, { siteId: target.siteId })
+  } catch (e: any) {
+    /*
+     * 점검이 터진 것을 「저쪽이 죽었다」로 옮기지 않는다 — 우리 점검의 실패다. 그리고 던지지 않는다:
+     * 이 함수 때문에 승인 화면이 안 열리면, 알려 주려던 것보다 큰 것을 잃는다.
+     */
+    return {
+      checked: 'local',
+      reason: `준비 상태를 확인하다 실패했습니다 — ${String(e?.message ?? e).slice(0, 160)}`,
+      code: 'check-failed'
+    }
+  }
+}

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

@@ -0,0 +1,163 @@
+/*
+ * **조치를 어디로 보낼 수 있나** — 판단만. 저장소도 어댑터 호출도 여기 없다.
+ *
+ * 배선(§`actuation-routing.ts`)에서 갈라 두는 이유는 규칙 쪽과 같다(§`rule-evaluate.ts`). 이 파일을
+ * 부르는 시험이 TypeORM 데코레이터를 지나면 시험이 서지 않고, 그러면 **거절 판정을 아무 시험도 걷지
+ * 않는다.** 조치 경로에서 그것은 승인이 쌓이는데 현장에 아무것도 안 가는 상태로 나타난다.
+ */
+import type { ReferenceCapability } from './reference-adapter.js'
+
+/** 판단에 필요한 것만 — 엔티티 전체를 받지 않는다. */
+export interface ActuationTargetInput {
+  /** 어느 트윈인가 — **거절 문장이 이것을 말한다.** 「모르는 트윈입니다」만으로는 찾을 수 없다. */
+  instanceId: string
+  /** 트윈이 있나. 없으면 `undefined`. */
+  twinExists: boolean
+  /** 이 트윈이 어느 사이트에서 왔나 — `TwinInstance.origin.siteId`. */
+  siteId?: string
+  /** 연결된 원본. 없으면 `undefined`(시뮬레이션으로만 세운 트윈). */
+  ref?: { source: string; adapterType: string }
+  /** 커넥터가 등록되어 있나. */
+  adapterRegistered: boolean
+  /**
+   * 그 커넥터가 실제로 낼 수 있는 능력 — `capabilitiesOf` 가 판정한 값.
+   *
+   * **낼 수 있나는 이 값만 본다.** 아래 둘은 못 낼 때 무엇을 고쳐야 하는지 말하기 위한 것이고,
+   * 판정을 다시 만들지 않는다.
+   */
+  capabilities: readonly ReferenceCapability[]
+  /** 커넥터가 `capabilities` 에 조치를 적었나. */
+  declaresActuate: boolean
+  /** 커넥터에 `actuate` 함수가 있나. */
+  hasActuateImpl: boolean
+}
+
+/** 보낼 수 있다 — 어디로까지 정해진 상태. */
+export interface ActuationAllowed {
+  ok: true
+  siteId: string
+  adapterType: string
+  source: string
+}
+
+/** 보낼 수 없다 — 왜인지 코드와 문장으로. */
+export interface ActuationRefused {
+  ok: false
+  code: ActuationRefusal
+  detail: string
+}
+
+export type ActuationTarget = ActuationAllowed | ActuationRefused
+
+/**
+ * 보낼 수 있나 — **타입 가드로 둔다.**
+ *
+ * 이 저장소는 기본 설정이 `strict: false` 이고(`packages/tsconfig-base.json`), 그 상태에서는 `ok` 가
+ * `true`·`false` 로 갈린 유니온이 `if (!t.ok)` 로 좁혀지지 않는다. 부르는 쪽마다 캐스팅을 넣으면 그
+ * 캐스팅이 언젠가 틀린 쪽을 가리킨다. 판정을 여기 한 자리에 둔다.
+ */
+export function isActuationAllowed(target: ActuationTarget): target is ActuationAllowed {
+  return target.ok === true
+}
+
+/**
+ * 왜 못 보내나 — **코드로 답한다.**
+ *
+ * 화면이 이 코드로 다음 할 일을 가른다. 문장만 주면 화면은 그것을 그대로 띄우는 것밖에 못 하고,
+ * 사람은 연결 설정을 열어야 하는지 커넥터를 고쳐야 하는지 모른다.
+ */
+export type ActuationRefusal =
+  | 'unknown-twin'
+  | 'no-source' /* 원본이 없는 트윈 — 보낼 곳이 없다 */
+  | 'no-adapter' /* 커넥터가 등록되지 않았다 */
+  | 'not-declared' /* 구현은 있는데 선언이 없다 — 한 줄 넣으면 된다 */
+  | 'not-implemented' /* 선언은 있는데 구현이 없다 — 만들다 만 커넥터다 */
+  | 'not-supported' /* 선언도 구현도 없다 — 이 커넥터는 관측만 낸다 */
+  | 'no-site' /* 어느 사이트로 낼지 모른다 */
+
+/**
+ * 보낼 수 있나 — 보낼 수 있으면 **어디로**까지 답한다.
+ *
+ * 순서가 뜻을 갖는다. 앞의 것이 없으면 뒤를 물을 수 없다 — 원본을 모르면 능력을 물을 데가 없다.
+ */
+export function actuationTarget(input: ActuationTargetInput): ActuationTarget {
+  if (!input.twinExists) {
+    return { ok: false, code: 'unknown-twin', detail: `모르는 트윈입니다 (${input.instanceId})` }
+  }
+
+  if (!input.ref) {
+    /*
+     * 시뮬레이션으로만 세운 트윈이 이 경우다. 규칙 경로가 시뮬 트윈을 이미 막지만
+     * (§`rule-runner.ts`), 사람이 손으로 낸 조치는 그 문을 지나지 않는다. 막는 지점이 두 경로에
+     * 각각 있는 것이고, 같은 판정을 두 벌 만든 것이 아니다.
+     */
+    return {
+      ok: false,
+      code: 'no-source',
+      detail: `트윈 "${input.instanceId}" 에는 연결된 원본이 없습니다 — 보낼 곳이 없습니다`
+    }
+  }
+
+  if (!input.adapterRegistered) {
+    return { ok: false, code: 'no-adapter', detail: `등록되지 않은 커넥터입니다 (${input.ref.adapterType})` }
+  }
+
+  if (!input.capabilities.includes('actuate')) {
+    /*
+     * **왜 못 내는지를 셋으로 가른다** — 고칠 것이 셋 다 다르다.
+     *
+     *   선언 없음 · 구현 있음    한 줄 넣으면 된다
+     *   선언 있음 · 구현 없음    만들다 만 커넥터다. 등록 검사는 이쪽을 말하지 않는다
+     *   선언도 구현도 없음        이 커넥터는 조치를 받지 않는다
+     *
+     * 뭉개면 한 줄로 끝날 일에 커넥터를 다시 만들려 들거나, 반대로 「관측만 냅니다」를 믿고 조치를
+     * 포기한다. 가운데 것을 「관측만 냅니다」로 답하는 것은 **사실이 아니다** — 그 사람은 조치를
+     * 하겠다고 적어 두었다.
+     */
+    const { adapterType, source } = input.ref
+    if (input.hasActuateImpl && !input.declaresActuate) {
+      return {
+        ok: false,
+        code: 'not-declared',
+        detail:
+          `커넥터 "${adapterType}" 가 조치를 보내는 구현은 있는데 능력으로 선언하지 않았습니다 — ` +
+          "connector 의 capabilities 에 'actuate' 를 넣어야 합니다"
+      }
+    }
+    if (input.declaresActuate && !input.hasActuateImpl) {
+      return {
+        ok: false,
+        code: 'not-implemented',
+        detail:
+          `커넥터 "${adapterType}" 가 조치를 보낸다고 선언했는데 그 구현이 없습니다 — ` +
+          'actuate 를 만들거나 선언을 지워야 합니다'
+      }
+    }
+    return {
+      ok: false,
+      code: 'not-supported',
+      detail: `원본 "${source}" (${adapterType}) 는 조치를 받지 않습니다 — 이 커넥터는 관측만 냅니다`
+    }
+  }
+
+  /*
+   * 사이트를 **지어내지 않는다.** 원본 하나가 여러 사이트를 낼 수 있다(`discoverSites`).
+   *
+   * 구동(§`control-routing.ts`)은 사이트를 몰라도 넘긴다 — 시늉을 멈추는 일에는 대상이 하나다.
+   * 조치는 안 된다. 어느 공장에 낼지 모르는 작업지시를 첫 번째 사이트로 보내면 **잘못된 공장이
+   * 실제로 만든다.**
+   */
+  const siteId = String(input.siteId ?? '').trim()
+  if (!siteId) {
+    return {
+      ok: false,
+      code: 'no-site',
+      detail: `트윈 "${input.instanceId}" 이 어느 사이트에서 왔는지 알 수 없습니다 — 조치를 보낼 대상을 정할 수 없습니다`
+    }
+  }
+
+  return { ok: true, siteId, adapterType: input.ref.adapterType, source: input.ref.source }
+}
+
+/** 승인은 남는다는 것을 함께 말한다 — 원인을 고친 뒤 다시 넘길 수 있다. */
+export const APPROVAL_STANDS = '승인은 그대로 남아 있습니다 — 고친 뒤 다시 넘길 수 있습니다'

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

@@ -0,0 +1,171 @@
+/*
+ * **연결을 배포 사이로 옮기는 문 셋** — 몸통은 `connection-portability.ts` 의 순수 함수들이다.
+ *
+ * ── 무엇을 옮기나 (사용자와 맞춘 개념, 2026-09-05) ─────────────────────────
+ * **옮기는 것은 「붙는 법」이지 「붙은 결과」가 아니다.**
+ *
+ *   옮긴다     연결 선언 — 주소 · 도메인 · 라인 크기 · 자재 이름공간
+ *   안 옮긴다   마스터        원본에서 다시 읽으면 된다
+ *   안 옮긴다   사실(저널)     원본이 다시 보내면 된다
+ *   안 옮긴다   잰 값          그 서버에서 다시 세면 된다
+ *   안 옮긴다   비밀값         그 환경의 것이지 셋업이 아니다
+ *
+ * **꾸러미는 정본이 아니라 운반 수단이다.** 정본은 언제나 그 배포의 DB 이고, 꾸러미는 쓰고 버린다.
+ *
+ * ── 주체는 받는 쪽이다 ─────────────────────────────────────────────────────
+ * 운영이 개발에서 **당겨온다.** 개발이 운영으로 밀면 개발 환경에 운영 자격이 살고, 그 통로는 실수로도
+ * 열린다. 그래서 `pullTwinConnectionsFrom` 이 본래 원하던 문이고, 나머지 둘은 저쪽에 못 닿을 때의
+ * 길이다.
+ *
+ * ── 쓰기 전에 계획을 보인다 ────────────────────────────────────────────────
+ * `planImport` 가 새로/갱신/건너뜀과 **사람이 채울 비밀값**을 먼저 낸다. 부딪힘(두 연결이 같은 공장에
+ * 조치를 내는 것)이 하나라도 있으면 **아무것도 쓰지 않는다** — 반만 적용된 연결 설정은 어느 쪽이
+ * 참인지 아무도 모른다.
+ */
+import { Arg, Ctx, Directive, Mutation, Query, Resolver } from 'type-graphql'
+import { ScalarObject, getRepository } from '@things-factory/shell'
+
+import { TwinReference } from './twin-reference.js'
+import { exportConnections, intakeCollisions, planImport, sayPlan, secretEnvName } from './connection-portability.js'
+
+/** 그 환경이 이 비밀값을 줄 수 있나 — **값은 읽지 않는다.** 이름의 존재만 본다. */
+function hasSecret(source: string, key: string): boolean {
+  const name = secretEnvName(source, key)
+  const v = process.env[name]
+  return typeof v === 'string' && v.trim().length > 0
+}
+
+@Resolver()
+export class ConnectionPortabilityResolver {
+  /**
+   * 지금 연결을 꾸러미로 낸다 — **비밀값은 안 나간다.**
+   *
+   * 이름 규칙으로 걸러서 **새 비밀 칸도 기본으로 안 나간다**(`SECRET_KEYS`). 나가지 않은 것은
+   * 꾸러미가 이름으로 말하고, 받는 쪽이 그 이름을 사람에게 보인다.
+   */
+  /*
+   * **읽기인데 쓰기와 같은 문을 쓴다.** 이 꾸러미는 연결 주소·도메인과 **비밀 칸의 이름**까지 낸다 —
+   * 그 이름만으로도 그 배포가 무엇에 붙어 있는지 드러난다. 권한 가드가 「쓰기는 GATE 하나」로
+   * 통일해 두었고, 이 문은 읽기지만 그 무게가 쓰기 쪽이다(ADR-0027).
+   */
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
+  @Query(returns => ScalarObject, {
+    description:
+      'Export this deployment’s twin connection declarations as a portable bundle. Secrets are never included — the bundle names them so the receiving side can ask a human.'
+  })
+  async twinConnectionBundle(
+    @Ctx() context: ResolverContext,
+    @Arg('note', { nullable: true, description: 'Free note carried in the bundle (why this export was made).' }) note?: string
+  ): Promise<any> {
+    const domain = context.state.domain
+    const rows = await getRepository(TwinReference).find({ where: { domain: { id: domain.id } } })
+    return exportConnections(rows as any, { at: new Date().toISOString(), domain: domain.subdomain ?? domain.name, ...(note ? { note } : {}) })
+  }
+
+  /**
+   * 꾸러미를 받아 적용한다 — **`dryRun` 이 기본이다.**
+   *
+   * 쓰기가 기본이면 「무엇이 바뀌나」를 보기 위해 쓰게 된다. 계획을 먼저 보고 사람이 정하는 것이
+   * 이 문의 요점이고, 그래서 적용은 명시해야 일어난다.
+   */
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
+  @Mutation(returns => ScalarObject, {
+    description:
+      'Apply a connection bundle. Returns the plan (new / updated / skipped, secrets a human must supply, collisions). Defaults to dryRun — pass apply:true to write.'
+  })
+  async importTwinConnections(
+    @Arg('bundle', type => ScalarObject) bundle: any,
+    @Ctx() context: ResolverContext,
+    @Arg('apply', { nullable: true, description: 'Write the plan. Omit or false to only see what would happen.' }) apply?: boolean
+  ): Promise<any> {
+    const domainId = context.state.domain.id
+    const repo = getRepository(TwinReference)
+    const existing = await repo.find({ where: { domain: { id: domainId } } })
+
+    const plan = planImport(bundle, existing as any, hasSecret)
+    const said = sayPlan(plan)
+
+    /*
+     * 부딪힘이 있으면 **아무것도 쓰지 않는다.** 두 연결이 같은 공장에 조치를 내면 어느 쪽이 그 라인의
+     * 주인인지 정할 수 없고, 반만 적용하면 그 물음이 조용히 남는다.
+     */
+    if (plan.collisions.length || plan.errors.length) {
+      return { ok: false, applied: 0, plan, said, refused: plan.collisions.length ? 'intake-collision' : 'bundle-error' }
+    }
+    if (!apply) return { ok: true, applied: 0, plan, said, dryRun: true }
+
+    let applied = 0
+    for (const a of plan.actions) {
+      /* 건너뛴 것은 이유가 계획에 남아 있다 — 여기서 다시 판정하지 않는다. */
+      if (a.action === 'skip') continue
+
+      const c = a.connection
+      /*
+       * **비밀값을 빈 값으로 안 채운다.** 꾸러미에 비밀값이 없고, `planImport` 가 그 이름을
+       * `missingSecrets`·`needsHuman` 으로 이미 냈다. 여기서 그 칸을 `undefined` 로 쓰면 사람이
+       * 화면에서 넣어 둔 값을 파일 하나가 지운다.
+       *
+       * 그래서 갱신은 **선언 칸만** 건드린다. 이미 있는 연결의 `connectionConfig` 는 꾸러미가 든
+       * 것만 덮어쓰고 나머지 키는 그대로 남긴다.
+       */
+      const found = await repo.findOne({ where: { domain: { id: domainId }, source: c.source } })
+      const declared = {
+        ...(c.system ? { system: c.system } : {}),
+        ...(c.siteName ? { siteName: c.siteName } : {}),
+        adapterType: c.adapterType,
+        ...(c.scope ? { scopeSpec: c.scope } : {})
+      } as any
+
+      if (found) {
+        const merged = { ...((found as any).connectionConfig ?? {}), ...(c.config ?? {}) }
+        await repo.update({ id: (found as any).id }, { ...declared, connectionConfig: merged } as any)
+      } else {
+        await repo.save(repo.create({ source: c.source, ...declared, connectionConfig: c.config ?? {}, domain: { id: domainId } as any }))
+      }
+      applied++
+    }
+    return { ok: true, applied, plan, said }
+  }
+
+  /**
+   * 저쪽 배포에서 당겨와 적용한다 — **본래 원한 문.**
+   *
+   * 받는 쪽이 주체다. 저쪽의 `twinConnectionBundle` 을 불러 이 배포에 적용한다 — 위 두 문을 잇는
+   * 얇은 층이고, 판정과 쓰기는 `importTwinConnections` 와 같은 규칙을 쓴다.
+   *
+   * **자격은 부르는 사람이 준다.** 이 서버가 저쪽 자격을 들고 있으면 그 통로가 상시로 열려 있게 되고,
+   * 그것은 옮기는 일에 필요한 것보다 넓다.
+   */
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
+  @Mutation(returns => ScalarObject, {
+    description:
+      'Pull connection declarations from another deployment and apply them here. The caller supplies that deployment’s URL and token — this server does not keep them.'
+  })
+  async pullTwinConnectionsFrom(
+    @Arg('endpoint', { description: 'That deployment’s GraphQL endpoint.' }) endpoint: string,
+    @Ctx() context: ResolverContext,
+    @Arg('token', { nullable: true, description: 'Bearer token for that deployment. Not stored.' }) token?: string,
+    @Arg('apply', { nullable: true }) apply?: boolean
+  ): Promise<any> {
+    let bundle: any
+    try {
+      const res = await fetch(endpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', ...(token ? { Authorization: `Bearer ${token}` } : {}) },
+        body: JSON.stringify({ query: '{ twinConnectionBundle }' })
+      })
+      const json: any = await res.json()
+      /* 저쪽이 오류를 냈으면 그 말을 그대로 올린다 — 여기서 다시 지으면 원인이 흐려진다. */
+      if (json?.errors?.length) return { ok: false, applied: 0, refused: 'remote-error', remote: json.errors.map((e: any) => e?.message) }
+      bundle = json?.data?.twinConnectionBundle
+    } catch (e: any) {
+      return { ok: false, applied: 0, refused: 'unreachable', remote: [String(e?.message ?? e)] }
+    }
+    if (!bundle) return { ok: false, applied: 0, refused: 'empty-bundle' }
+
+    return this.importTwinConnections(bundle, context, apply)
+  }
+}
+
+/** 이 리졸버가 다루는 부딪힘 판정 — 화면이 같은 함수를 쓸 수 있게 다시 내보낸다. */
+export { intakeCollisions }