@things-factory/headless-twin 10.1.278 → 10.1.279

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

@@ -1,171 +0,0 @@
-/*
- * **연결을 배포 사이로 옮기는 문 셋** — 몸통은 `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 }

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

@@ -1,329 +0,0 @@
-/*
- * **연결을 내보내고 다시 들여옵니다** — 실제 셋업을 파일로 보관하고 되세웁니다.
- *
- * ── 이것은 데모가 아니라 제품 기능입니다 (2026-09-05) ───────────────────────
- * 데모 시드(`seed-demo-twins.ts`)와 **다른 것**입니다. 그쪽은 내장 가상 마스터로 보여 줄 트윈을
- * 만들고 `TWIN_PROVISION_DEMO` 뒤에 숨습니다. 이것은 **실제로 붙인 연결을 옮기는 길**이라
- * 데모 스위치 뒤에 두지 않습니다 — 백업·이관·복구가 데모일 수 없습니다.
- *
- * 그래서 특정 공장을 제품 코드에 적지 않습니다. 적으면 배포마다 남의 공장이 하나씩 따라가고,
- * 데모 시드 머리말이 적어 둔 「프로덕션 배포는 **트윈 0** 에서 시작한다」가 깨집니다. 무엇을 세울지는
- * **파일이 말하고 코드는 그 파일을 읽을 줄만 압니다.**
- *
- * ── 왜 필요했나 ────────────────────────────────────────────────────────────
- * 실 MES 두 공장을 트윈에 세웠는데(`mes-line-a` · `mes-miratek`) **그 셋업이 한 데이터베이스
- * 안에만 있었습니다.** 잃으면 다시 손으로 만들어야 하고, 다른 배포에 옮길 길도 없었습니다.
- *
- * ── 담는 것과 안 담는 것 ────────────────────────────────────────────────────
- *
- *   담는다     연결 선언 — 주소 · 도메인 · 사이트 · 치수 · 이름공간 · 받는 자리
- *   안 담는다   비밀값 — 토큰 · 웹훅 서명값 · 받는 쪽 비밀값
- *   안 담는다   사실(저널) — 원본이 다시 보내면 된다. 담으면 **가짜 과거가 배포마다 복제된다**
- *   안 담는다   마스터에서 온 트윈 모델 — 연결이 있으면 재동기화가 다시 만든다
- *
- * **비밀값은 이름만 적습니다.** 어느 칸이 채워져 있었는지는 알려 주되 값은 안 나갑니다 — 파일은
- * 주고받는 물건이고, 한 번 나간 비밀값은 되돌릴 수 없습니다. 들여올 때 「이 셋이 없다」고 말하고
- * 사람이 연결 화면에서 채웁니다.
- *
- * ── 왜 사실을 안 담나 ───────────────────────────────────────────────────────
- * 저널은 되풀이 읽히고 미러로 복제되고 구독으로 방송됩니다. 내보낸 사실을 다른 배포에 들여오면
- * **일어나지 않은 일이 그 공장의 지난 기록에 섭니다.** 커서만 옮겨 두면 원본이 그 뒤부터 다시
- * 보내 주므로, 사실은 원본에서 오는 것이 맞습니다.
- */
-
-/** 값이 아니라 **채워져 있었다는 사실**만 나가는 칸들. */
-export const SECRET_KEYS = ['token', 'hookSecret', 'intakeSecret', 'password', 'apiKey'] as const
-
-export interface PortableConnection {
-  source: string
-  system?: string
-  siteName?: string
-  adapterType: string
-  /** 비밀값을 뺀 연결 설정. */
-  config: Record<string, unknown>
-  /** 내보낼 때 채워져 있던 비밀 칸 이름 — 값은 없습니다. */
-  secretsRequired: string[]
-  /** 이 연결이 무엇을 세우나. */
-  scope?: unknown
-}
-
-export interface ConnectionBundle {
-  kind: 'operato-twin/connections'
-  version: 1
-  exportedAt: string
-  /** 어디서 내보냈나 — 사람이 나중에 「이게 어느 배포 것인가」를 물을 때 답합니다. */
-  exportedFrom?: { domain?: string; note?: string }
-  connections: PortableConnection[]
-}
-
-/**
- * 무엇을 세우나 **선언만** 남깁니다 — 지난 동기화의 **측정값은 뺍니다.**
- *
- * `scopeSpec` 에는 `produced`(선언) 옆에 `assessments`(그때 몇 개가 섰나) · `lastFailures` 가 함께
- * 삽니다. 그것까지 내보내면 새 배포가 **다른 기계에서 잰 수**를 자기 것으로 보입니다 — 「설비 42」가
- * 아무것도 안 세운 배포의 화면에 서고, 그 수가 어디서 왔는지 아무도 모릅니다.
- *
- * 재는 것은 그 배포에서 다시 재야 합니다. 오늘 「설정을 고쳤다」와 「모델이 다시 섰다」를 가른 것과
- * 같은 구별입니다.
- */
-function producedOf(scopeSpec: any): { produced: unknown } | undefined {
-  const produced = scopeSpec?.produced
-  return Array.isArray(produced) && produced.length ? { produced } : undefined
-}
-
-const isSecret = (key: string): boolean =>
-  (SECRET_KEYS as readonly string[]).includes(key) || /secret|token|password|apikey/i.test(key)
-
-/**
- * 연결 행들을 옮길 수 있는 모양으로 — **비밀값을 빼고**.
- *
- * 빼는 판정을 이름으로 합니다. 목록으로만 하면 커넥터가 새 비밀 칸을 더할 때 그 값이 조용히
- * 파일로 나갑니다 — 이름 규칙을 함께 두어 **새 칸이 기본으로 안 나가게** 합니다.
- */
-export function exportConnections(
-  rows: readonly { source: string; system?: string; siteName?: string; adapterType: string; connectionConfig?: any; scopeSpec?: any }[],
-  meta: { at: string; domain?: string; note?: string }
-): ConnectionBundle {
-  return {
-    kind: 'operato-twin/connections',
-    version: 1,
-    exportedAt: meta.at,
-    ...(meta.domain || meta.note ? { exportedFrom: { ...(meta.domain ? { domain: meta.domain } : {}), ...(meta.note ? { note: meta.note } : {}) } } : {}),
-    connections: rows.map(r => {
-      const cfg = (r.connectionConfig ?? {}) as Record<string, unknown>
-      const kept: Record<string, unknown> = {}
-      const secrets: string[] = []
-      for (const [k, v] of Object.entries(cfg)) {
-        if (isSecret(k)) {
-          /* 비어 있던 칸은 적지 않습니다 — 「채워야 한다」와 「이 커넥터에 그런 칸이 있다」는 다릅니다. */
-          if (String(v ?? '').trim()) secrets.push(k)
-          continue
-        }
-        kept[k] = v
-      }
-      return {
-        source: r.source,
-        ...(r.system ? { system: r.system } : {}),
-        ...(r.siteName ? { siteName: r.siteName } : {}),
-        adapterType: r.adapterType,
-        config: kept,
-        secretsRequired: secrets.sort(),
-        ...(producedOf(r.scopeSpec) ? { scope: producedOf(r.scopeSpec) } : {})
-      }
-    })
-  }
-}
-
-export type ImportAction =
-  | { action: 'create'; connection: PortableConnection; missingSecrets: string[] }
-  | { action: 'update'; connection: PortableConnection; missingSecrets: string[]; keptSecrets: string[] }
-  | { action: 'skip'; source: string; why: string }
-
-export interface ImportPlan {
-  actions: ImportAction[]
-  /** 사람이 연결 화면에서 채워야 하는 것 — 이것이 비어야 「시드만으로 끝」입니다. */
-  /**
-   * 사람이 환경에 넣어야 하는 비밀값.
-   *
-   * `env` 를 함께 냅니다 — **그 이름을 사람이 손으로 적기 때문**입니다. 화면이 이름을 따로 만들면
-   * 규칙이 두 곳에 살고, 갈리는 날 「넣었는데 안 읽힌다」가 됩니다. 실제로 났습니다(2026-09-06):
-   * 화면이 `TWIN_SECRET__MES-MIRATEK__HOOKSECRET` 을 알려 줬는데 서버가 읽는 이름은
-   * `TWIN_SECRET__MES_MIRATEK__HOOK_SECRET` 이었습니다. 하이픈과 낙타 경계 둘 다 달랐습니다.
-   *
-   * `keys` 와 순서가 같습니다 — `keys[i]` 의 이름이 `env[i]` 입니다.
-   */
-  needsHuman: { source: string; keys: string[]; env: string[] }[]
-  /** 들여온 **뒤에** 두 연결이 같은 곳에 조치를 내게 되나 — 있으면 들여오면 안 됩니다. */
-  collisions: { intake: string; sources: string[] }[]
-  errors: string[]
-}
-
-/**
- * 들여오기 **계획**을 먼저 냅니다 — 쓰기 전에 무엇이 일어날지 사람이 봅니다.
- *
- * ── 이미 있는 연결을 덮지 않습니다 ──────────────────────────────────────────
- * 같은 이름이 이미 있으면 **선언만 갱신하고 비밀값은 그대로 둡니다.** 사람이 화면에서 넣은 값을
- * 파일이 지우면, 파일 하나 들여왔다가 도는 연결이 멈춥니다. 데모 시드도 같은 규율을 적어 두었습니다
- * (「옆 설정을 지우지 않는다 — 시드는 자기가 아는 것만 채운다」).
- *
- * ── 없는 비밀값을 지어내지 않습니다 ─────────────────────────────────────────
- * 빈 값으로 채워 두면 연결이 서고 **동기화할 때 처음 실패합니다.** 그때는 무엇이 없어서인지 화면에서
- * 멉니다. 여기서 이름을 대고 멈추는 것이 낫습니다.
- */
-export function planImport(
-  bundle: unknown,
-  existing: readonly { source: string; connectionConfig?: any }[],
-  /** 지금 환경이 줄 수 있는 비밀값 이름들 — 값은 안 받습니다(이 함수는 값을 만지지 않습니다). */
-  availableSecrets: (source: string, key: string) => boolean = () => false
-): ImportPlan {
-  const errors: string[] = []
-  const b = bundle as ConnectionBundle
-  if (!b || typeof b !== 'object') return { actions: [], needsHuman: [], collisions: [], errors: ['들여올 것이 객체가 아닙니다'] }
-  if (b.kind !== 'operato-twin/connections') {
-    return { actions: [], needsHuman: [], collisions: [], errors: [`이 파일은 연결 설정 파일가 아닙니다(kind: ${JSON.stringify((b as any).kind ?? null)})`] }
-  }
-  if (b.version !== 1) errors.push(`모르는 버전입니다(version: ${JSON.stringify((b as any).version)}) — 읽을 수 있는 것만 읽습니다`)
-  if (!Array.isArray(b.connections)) return { actions: [], needsHuman: [], collisions: [], errors: [...errors, 'connections 가 목록이 아닙니다'] }
-
-  const have = new Map(existing.map(e => [e.source, e]))
-  const seen = new Set<string>()
-  const actions: ImportAction[] = []
-  const needsHuman: { source: string; keys: string[]; env: string[] }[] = []
-
-  for (const c of b.connections) {
-    const source = String(c?.source ?? '').trim()
-    if (!source) {
-      errors.push('이름 없는 연결이 있습니다 — 건너뜁니다')
-      continue
-    }
-    if (seen.has(source)) {
-      actions.push({ action: 'skip', source, why: '같은 이름이 파일에 두 번 있습니다' })
-      continue
-    }
-    seen.add(source)
-    if (!String(c?.adapterType ?? '').trim()) {
-      actions.push({ action: 'skip', source, why: '커넥터 종류가 없습니다 — 무엇으로 붙일지 모릅니다' })
-      continue
-    }
-
-    const cur = have.get(source)
-    const curCfg = (cur?.connectionConfig ?? {}) as Record<string, unknown>
-    const wanted = Array.isArray(c.secretsRequired) ? c.secretsRequired.map(String) : []
-    const kept = wanted.filter(k => String(curCfg[k] ?? '').trim())
-    const missing = wanted.filter(k => !kept.includes(k) && !availableSecrets(source, k))
-
-    if (missing.length) needsHuman.push({ source, keys: missing, env: missing.map(k => secretEnvName(source, k)) })
-    actions.push(
-      cur
-        ? { action: 'update', connection: c, missingSecrets: missing, keptSecrets: kept }
-        : { action: 'create', connection: c, missingSecrets: missing }
-    )
-  }
-
-  /*
-   * **들여온 뒤의 모습으로 봅니다.** 파일 안에서만 보면 「이미 있는 연결과 부딪히는 것」을 못
-   * 잡습니다 — 그게 실제로 더 쉽게 나는 쪽입니다(하나는 화면에서, 하나는 파일에서 생깁니다).
-   */
-  const after = [
-    /* 행 모양 그대로 넘긴다 — 옮기는 자리는 `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 }))
-  ]
-  return { actions, needsHuman, collisions: intakeCollisions(after), errors }
-}
-
-/** 사람이 읽는 한 줄 — 화면과 로그가 같은 문장을 쓰게. */
-export function sayPlan(plan: ImportPlan): string {
-  const n = (a: ImportAction['action']) => plan.actions.filter(x => x.action === a).length
-  const head = `연결 ${plan.actions.length}개 — 새로 ${n('create')} · 갱신 ${n('update')} · 건너뜀 ${n('skip')}`
-  /* 부딪힘을 먼저 말합니다 — 비밀값이 없는 것은 안 도는 것이고, 부딪히는 것은 **잘못 도는 것**입니다. */
-  if (plan.collisions.length) {
-    const who = plan.collisions.map(c => `${c.sources.join(' · ')} → ${c.intake}`).join(', ')
-    return `${head}. ⚠ **두 연결이 같은 곳에 조치를 냅니다** — ${who}. 다른 공장의 작업지시가 한 공장에 섭니다`
-  }
-  if (!plan.needsHuman.length) return `${head}. 비밀값은 다 있습니다`
-  const who = plan.needsHuman.map(h => `${h.source}(${h.keys.join(' · ')})`).join(', ')
-  return `${head}. **비밀값을 사람이 넣어야 합니다** — ${who}. 연결 화면에서 채우면 그때부터 돕니다`
-}
-
-/**
- * 비밀값이 사는 **환경 변수 이름** — `mes-miratek` · `hookSecret` → `TWIN_SECRET__MES_MIRATEK__HOOK_SECRET`.
- *
- * 패키지에는 비밀 칸의 이름만 있고 값은 환경에서 옵니다. 그 이름을 **사람이 손으로 적으므로** 규칙이
- * 흔들리면 「넣었는데 안 읽힌다」가 됩니다 — 오늘 종일 잡은 「양쪽 다 초록인데 안 간다」의 설정 쪽
- * 버전입니다. 그래서 이 규칙을 한 곳에 두고 시험으로 못 박습니다.
- *
- * 낙타 이름의 경계를 밑줄로 가릅니다 — 안 그러면 `HOOKSECRET` 과 `HOOK_SECRET` 이 갈려 한쪽만 읽힙니다.
- */
-export function secretEnvName(source: string, key: string): string {
-  const up = (x: string) =>
-    x
-      .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
-      .replace(/[^A-Za-z0-9]+/g, '_')
-      .replace(/^_+|_+$/g, '')
-      .toUpperCase()
-  return `TWIN_SECRET__${up(source)}__${up(key)}`
-}
-
-/**
- * **두 연결이 같은 곳에 조치를 내지 않나** — 같으면 다른 공장의 작업지시가 한 공장에 섭니다.
- *
- * ── 왜 이 검사가 생겼나 (2026-09-05) ────────────────────────────────────────
- * `mes-miratek` 이 서면서 한 커넥터가 처음으로 **공장 둘**을 달았습니다. 조치가 나가는 주소는
- * `intakeSiteId` 가 정하는데(`operato-plant.ts:389`), 그 값이 트윈의 사이트 이름을 **이깁니다** —
- * 트윈에서는 `mes-line-a` 인데 MES 의 도메인은 `system` 이라 그 override 가 필요합니다.
- *
- * 그래서 **연결을 베껴 만들고 그 칸만 안 고치면** 두 트윈의 조치가 같은 공장으로 갑니다. 오류가
- * 안 납니다 — 저쪽은 정상적인 작업지시로 받고 **실제로 만듭니다.**
- *
- * 게이트에 이미 「사이트를 모르면 보내지 않는다」가 있는데(`no-site`), 그 이유가 적혀 있는 문장이
- * **「잘못된 공장이 실제로 만든다」** 입니다. 이것은 그 둘째 길입니다 — 사이트를 아는데 **틀린
- * 사이트를 압니다.**
- *
- * 파일로 연결을 만들 수 있게 되면서 더 쉬워졌습니다: 패키지를 베껴 이름만 바꾸면 받는 자리가
- * 그대로 따라옵니다.
- */
-export function intakeCollisions(
-  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) {
-    /*
-     * **모양이 둘인 것을 여기서 안다** (ADR-0053 ①, 2026-09-16).
-     *
-     * 패키지는 `config`, `TwinReference` 행은 `connectionConfig` 다. 전에는 `config` 만 읽어서, 행을
-     * 그대로 넘기면 같은 충돌에도 `[]` 를 냈다 — 오류도 경고도 없이 **저장이 통과하고 가드는 선 채로
-     * 아무 일도 안 한다.** 부르는 쪽마다 옮기게 두면 다음 소비처가 또 밟는다(이 함수는 화면이 쓰라고
-     * 리졸버에서 다시 내보내진다).
-     *
-     * 「없다」가 편한 답인 자리라 더 위험하다 — 빨강이 아니라 **조용한 초록**으로 흐른다.
-     */
-    const cfg = c.config ?? c.connectionConfig ?? {}
-    /* 받는 자리를 정하는 규칙은 커넥터의 것과 같아야 합니다 — 여기서 다시 지으면 두 벌이 됩니다. */
-    const intake = String(cfg.intakeSiteId ?? cfg.siteId ?? '').trim()
-    /* 조치를 낼 수 없는 연결은 부딪힐 것이 없습니다 — 주소가 없으면 아무 데도 안 갑니다. */
-    if (!intake || !String(cfg.intakeEndpoint ?? '').trim()) continue
-    const key = `${String(cfg.intakeEndpoint).trim().replace(/\/$/, '')}::${intake}`
-    byIntake.set(key, [...(byIntake.get(key) ?? []), c.source])
-  }
-  return [...byIntake.entries()]
-    .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/control-routing.ts

@@ -1,62 +0,0 @@
-/*
- * **구동은 원본을 지난다** — 트윈을 우회하지 않는다 (ADR-0029 §8, 2026-08-19).
- *
- * ── 무엇이 뚫려 있었나 ──────────────────────────────────────────────────────
- * `controlTwinScenario` 가 `TwinEngine.runtime(...).scenario` 를 **직접** 잡았다. 그래서 시뮬만 할 수 있는
- * 일(자극·배속·정지)이 계약 밖의 지름길로 들어왔고, 실 시스템에는 그 자리가 아예 없었다 — ADR-0029 의
- * 판정 문장에 걸리는 상태였다.
- *
- * 이제 길은 하나다: **트윈 → 그 트윈의 원본 → 어댑터가 선언한 `control` 능력.** 선언하지 않은 원본에는
- * 문이 열리지 않고, 그 사실을 코드로 말한다(`not-declared`). 실 WMS 가 정지되지 않는 것은 결손이 아니다.
- *
- * ── 전송은 여기서 묻지 않는다 (§7) ──────────────────────────────────────────
- * 인프로세스 시뮬레이터는 같은 계약을 인프로세스로 이행한다. 나중에 그것이 다른 프로세스로 나가도 이 경로는
- * 바뀌지 않는다 — 「계약을 지나는가」만 보고 「네트워크를 타는가」는 묻지 않는다.
- */
-import { getRepository } from '@things-factory/shell'
-
-import { TwinInstance } from '../twin-instance/twin-instance.js'
-import { TwinReference } from './twin-reference.js'
-import { capabilitiesOf, getAdapter, type ControlCommand, type ControlResult, type SiteDescriptor } from './reference-adapter.js'
-
-/**
- * 이 트윈의 원본에 구동 명령을 보낸다 — **원본이 없거나 능력을 선언하지 않으면 거절한다.**
- *
- * 거절을 알리지 않고 하지 않는다: 사유 코드를 돌려주고 화면이 그것을 사람 말로 옮긴다. 「아무 일도 일어나지
- * 않았다」가 가장 비싼 답이다.
- */
-export async function routeControl(domainId: string, instanceId: string, command: ControlCommand): Promise<ControlResult> {
-  const inst = await getRepository(TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId } })
-  if (!inst) return { ok: false, code: 'unknown-twin', detail: instanceId }
-
-  const ref = await getRepository(TwinReference).findOne({ where: { domain: { id: domainId }, source: instanceId } })
-  if (!ref) {
-    /* 원본을 모르는 트윈 — 구동할 대상이 없다. 트윈을 직접 흔드는 길은 두지 않는다(그것이 지름길이었다). */
-    return { ok: false, code: 'no-source', detail: `twin "${instanceId}" does not remember a source to drive` }
-  }
-
-  const adapter = getAdapter(ref.adapterType)
-  if (!adapter) return { ok: false, code: 'no-adapter', detail: ref.adapterType }
-  if (!capabilitiesOf(adapter).includes('control')) {
-    return {
-      ok: false,
-      code: 'not-declared',
-      detail: `source "${ref.source}" (${ref.adapterType}) does not declare the control capability — a real system is not paused or seeded, and that is a fact rather than a gap`
-    }
-  }
-
-  /*
-   * 사이트를 함께 넘긴다 — 원본 하나가 여러 사이트를 낼 수 있다(`discoverSites`). 우리가 아는 것은
-   * 이 트윈이 어느 사이트에서 왔는지이고(`origin.siteId`), 모르면 넘기지 않는다(지어내지 않는다).
-   */
-  const siteId = (inst.origin as any)?.siteId
-  const site: SiteDescriptor | undefined = siteId ? { siteId } : undefined
-  return adapter.control!(ref.connectionConfig ?? {}, site, { ...command, instanceId, domainId })
-}
-
-/** 이 트윈의 원본이 선언한 능력 — 화면이 「무엇을 할 수 있나」를 먼저 알 수 있게. */
-export async function controlCapabilityOf(domainId: string, instanceId: string): Promise<{ source?: string; adapterType?: string; capabilities: string[] }> {
-  const ref = await getRepository(TwinReference).findOne({ where: { domain: { id: domainId }, source: instanceId } })
-  if (!ref) return { capabilities: [] }
-  return { source: ref.source, adapterType: ref.adapterType, capabilities: capabilitiesOf(getAdapter(ref.adapterType)) }
-}

package/server/service/reference/discovery-result.ts

@@ -1,95 +0,0 @@
-/*
- * 사이트 발견 결과 — **"못 찾았다" 와 "없다" 를 구분한다.** 순수.
- *
- * ── 왜 있나 (2026-08-06) ────────────────────────────────────────────────────
- * 실 시스템을 연결해 "거기 있는 것" 으로 트윈을 만드는 경로에서, 발견이 실패하면 화면이
- * **"사이트를 찾지 못했습니다"** 라고만 말했다. 네 가지가 그 한 문장에 섞여 있었다.
- *
- *  ① 그 레퍼런스가 등록돼 있지 않다        (`!ref → []`)
- *  ② 어댑터 종류를 모른다                  (`!adapter → []`)
- *  ③ 연결·조회가 실패했다                  (`catch { return [] }`)
- *  ④ 정말로 사이트가 없다                  (빈 배열)
- *
- * ①②③ 은 **고칠 수 있는 문제**이고 ④ 는 사실이다. 그런데 화면이 같은 말을 하므로 사용자는 자격이
- * 틀렸는지, 주소가 틀렸는지, 정말 공장이 없는지 알 수 없다 — 실 시스템 연결에서 가장 자주 막히는
- * 자리인데 거기서 아무 단서도 주지 않았다.
- *
- * ── 왜 문장이 아니라 코드인가 ───────────────────────────────────────────────
- * 이 프로젝트가 이미 쓰는 규약을 따른다(주의 신호·커맨드 거절·인제스트 경고와 같은 모양):
- * `code`(언어 중립) + `params`(문장에 끼울 값) + `message`(영어 canonical, 로그·폴백).
- * 화면은 `twin.connect.discover.<code>` 로 사람 말을 만든다.
- *
- * ── 원 시스템의 오류 문장을 감추지 않는다 ────────────────────────────────────
- * 어댑터가 준 사유(자격 거부·타임아웃·404)는 **그 시스템만 아는 사실**이라 우리가 다시 쓸 수 없다.
- * `detail` 로 그대로 실어 보내 화면이 보조 문장으로 보인다 — 원문이 있으면 사용자가 자기 관리자에게
- * 물어볼 수 있고, 없으면 우리 짐작만 남는다.
- */
-
-/** 발견이 왜 아무것도 주지 못했나 — 언어 중립 코드. */
-export type DiscoveryErrorCode = 'reference-not-found' | 'adapter-unknown' | 'discovery-failed' | 'discovery-timeout'
-
-export interface DiscoveryError {
-  code: DiscoveryErrorCode
-  params?: Record<string, string | number>
-  /** 영어 canonical — 로그에 남고, 번역이 없으면 그대로 보인다. */
-  message: string
-}
-
-export interface DiscoveryResult<S = unknown> {
-  /** 발견된 사이트들. 실패했으면 빈 배열이고 `error` 가 이유를 말한다. */
-  sites: S[]
-  /** 실패 사유. **없으면 성공이다** — 빈 배열 + 사유 없음 = "연결은 됐지만 사이트가 없다". */
-  error?: DiscoveryError
-}
-
-/** 등록된 레퍼런스가 없다 — 목록이 낡았거나 다른 테넌트의 것이다. */
-export const referenceNotFound = (source: string): DiscoveryError => ({
-  code: 'reference-not-found',
-  params: { source },
-  message: `reference "${source}" is not registered in this tenant`
-})
-
-/** 어댑터 종류를 모른다 — 배포에 그 커넥터가 없다(패키지 미설치·오타). */
-export const adapterUnknown = (adapterType: string, source: string): DiscoveryError => ({
-  code: 'adapter-unknown',
-  params: { adapterType, source },
-  message: `no connector of type "${adapterType}" is available for reference "${source}"`
-})
-
-/** 연결·조회가 실패했다 — 원 시스템이 준 사유를 그대로 싣는다. */
-export const discoveryFailed = (source: string, detail: string): DiscoveryError => ({
-  code: 'discovery-failed',
-  params: { source, detail },
-  message: `could not read sites from "${source}": ${detail}`
-})
-
-/** 기다려도 답이 없었다 — 무한히 도는 화면보다 사유가 낫다. */
-export const discoveryTimedOut = (source: string, seconds: number): DiscoveryError => ({
-  code: 'discovery-timeout',
-  params: { source, seconds },
-  message: `"${source}" did not answer within ${seconds}s`
-})
-
-/**
- * 어댑터가 준 것을 결과로 처리한다.
- *
- * **사이트가 없는 것을 실패로 만들지 않는다** — 연결이 되고 조회가 성공했는데 공장이 하나도 없는
- * 시스템은 있을 수 있다(권한이 좁거나 아직 등록되지 않은 경우). 그것은 사실이고, 화면은 "없다" 고
- * 말해야 한다. 실패로 합치면 사용자가 있지도 않은 문제를 찾는다.
- */
-export function discovered<S>(sites: readonly S[] | undefined | null): DiscoveryResult<S> {
-  return { sites: Array.isArray(sites) ? [...sites] : [] }
-}
-
-/** 실패를 결과로 처리한다 — 사이트는 비어 있다(반쪽 목록을 성공처럼 보이게 하지 않는다). */
-export function failed<S>(error: DiscoveryError): DiscoveryResult<S> {
-  return { sites: [], error }
-}
-
-/** 어댑터가 오류를 낸 것에서 사람이 읽을 사유를 뽑는다 — 형태를 가정하지 않는다. */
-export function detailOf(e: unknown): string {
-  if (e instanceof Error && e.message) return e.message
-  if (typeof e === 'string' && e) return e
-  /* 무엇이 왔는지 모르면 그렇게 말한다 — 빈 문장으로 "이유 없음" 처럼 보이게 하지 않는다. */
-  return 'the connector failed without a message'
-}