@things-factory/headless-twin 10.0.9 → 10.0.11

package/server/service/twin-model/twin-model-tree-query.ts

@@ -0,0 +1,180 @@
+import { Arg, Ctx, Int, Query, Resolver } from 'type-graphql'
+
+import { ScalarObject, getRepository } from '@things-factory/shell'
+
+import { TwinInstance } from '../twin-instance/twin-instance.js'
+
+const { TWIN_RELATIONS, axisInfo } = require('@operato/twin-kernel')
+
+/**
+ * 재귀 전개 — **자기 축으로 돌아오는 선언을 따라간다.**
+ *
+ * ── 왜 자재가 자재를 품지 않는가 ───────────────────────────────────────────────
+ * 다단 BOM 을 "자재 안에 자재" 로 적으면 같은 부품이 여러 완제품에 들어갈 때마다 복제되고,
+ * 수량이 어디 붙는지도 애매해진다. 표준(ISA-95)이 택한 모양은 **자재와 레시피가 번갈아 나오는
+ * 그래프**다: 완제품 ←산출— 레시피 —투입→ 부품들, 그리고 그 부품이 또 어느 레시피의 산출이면
+ * 거기서 다시 내려간다. 우리 선언(`twin.rel.input`·`twin.rel.output`)이 이미 그 두 홉이다.
+ *
+ * ── 패턴을 코드가 알지 않는다 ──────────────────────────────────────────────────
+ * "BOM 은 산출→투입" 이라고 적어 두면 그 순간 이 파일이 도메인을 알게 된다(ADR-0031 위반).
+ * 대신 **선언 그래프에서 자기 축으로 돌아오는 두 홉 순환을 찾는다.** 자재만이 아니라 앞으로
+ * 같은 모양을 갖는 어떤 축이든 그대로 펼쳐진다.
+ *
+ * ── 조용히 고르지 않는다 ───────────────────────────────────────────────────────
+ * 순환이 여럿이면 **아무거나 집지 않는다.** 후보를 돌려주고 부르는 쪽이 고르게 한다 — 한쪽을
+ * 집으면 역전개(누가 나를 쓰나)를 전개(내가 무엇으로 되나)로 보여 주고도 아무도 모른다.
+ */
+
+/** 자기 축으로 돌아오는 두 홉 — `axis ←down(via)— through —up(via)→ axis`. */
+interface WalkPattern {
+  /** 중간에 거치는 축(레시피 등). */
+  through: string
+  /** 나로 들어오는 홉 — "나를 이것의 산출로 삼는" 쪽. */
+  inVia: string
+  /** 거기서 다시 나가는 홉 — "그것이 투입하는" 쪽. */
+  outVia: string
+  inField: string
+  outField: string
+}
+
+/** 선언 그래프에서 이 축으로 돌아오는 순환들을 찾는다. */
+function patternsFor(axis: string): WalkPattern[] {
+  const toMe = TWIN_RELATIONS.filter((r: any) => r.target?.kind === 'axis' && r.target.axis === axis)
+  const out: WalkPattern[] = []
+  for (const a of toMe)
+    for (const b of toMe)
+      if (a !== b && a.from === b.from)
+        out.push({ through: a.from, inVia: a.via, outVia: b.via, inField: a.field, outField: b.field })
+  return out
+}
+
+const at = (o: any, path: string) => path.split('.').reduce((a: any, k: string) => (a == null ? undefined : a[k]), o)
+const idOf = (o: any): string | null => (typeof o === 'string' ? o : o?.id ?? o?.key ?? o?.gtin ?? null)
+
+/** `inputs[].material` — 배열을 지나는 선언 경로. 값과 **그 값을 담은 객체**를 함께 돌려준다(수량이 거기 있다). */
+function entriesAt(obj: any, field: string): { value: any; holder: any }[] {
+  let cur: { value: any; holder: any }[] = [{ value: obj, holder: obj }]
+  for (const seg of field.split('.')) {
+    const key = seg.endsWith('[]') ? seg.slice(0, -2) : seg
+    const next: { value: any; holder: any }[] = []
+    for (const c of cur) {
+      const v = c.value?.[key]
+      if (v == null) continue
+      if (Array.isArray(v)) for (const x of v) next.push({ value: x, holder: x })
+      else next.push({ value: v, holder: c.value })
+    }
+    cur = next
+  }
+  return cur
+}
+
+/** 이 홉이 실어 나르는 수량 — 선언에 있으면 쓰고, 없으면 **없다고 한다**(1 로 메우지 않는다). */
+function qtyOf(holder: any): number | null {
+  const q = holder?.qty ?? holder?.quantity
+  return typeof q === 'number' ? q : null
+}
+
+@Resolver()
+export class TwinModelTreeQuery {
+  @Query(returns => ScalarObject, {
+    nullable: true,
+    description:
+      'Recursively expand an item through a declared two-hop cycle (e.g. a multi-level BOM: product ←produced-by— recipe —consumes→ parts). The pattern is derived from the kernel relation declarations, never hardcoded. Reports the pattern used, any cycles found, and whether depth or item caps truncated the walk.'
+  })
+  async twinModelTree(
+    @Arg('instanceId') instanceId: string,
+    @Arg('axis') axis: string,
+    @Arg('itemId') itemId: string,
+    @Ctx() context: ResolverContext,
+    @Arg('inVia', { nullable: true }) inVia?: string,
+    @Arg('outVia', { nullable: true }) outVia?: string,
+    @Arg('maxDepth', type => Int, { nullable: true }) maxDepth?: number,
+    @Arg('maxItems', type => Int, { nullable: true }) maxItems?: number
+  ): Promise<any | null> {
+    const domainId = context.state.domain.id
+    const info = axisInfo(axis)
+    if (!info) throw new Error(`unknown concept axis: "${axis}" — the kernel catalog does not declare it`)
+
+    const inst = await getRepository(TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId } })
+    if (!inst) return null
+
+    const all = patternsFor(axis)
+    if (!all.length) return { axis, itemId, patterns: [], items: [], edges: [], reason: 'no-recursive-relation' }
+
+    const chosen = inVia && outVia ? all.find(p => p.inVia === inVia && p.outVia === outVia) : all.length === 1 ? all[0] : undefined
+    if (!chosen)
+      /* 여럿인데 안 고르면 **아무것도 펼치지 않는다.** 한쪽을 집으면 역전개를 전개로 보여 주고도
+         아무도 모른다 — 방향이 뒤집힌 BOM 은 틀린 답이 아니라 반대의 답이다. */
+      return { axis, itemId, patterns: all, items: [], edges: [], reason: 'ambiguous-pattern' }
+
+    const model = inst.model ?? {}
+    const throughInfo = axisInfo(chosen.through)
+    const listOf = (i: any) => {
+      const raw = i ? at(model, i.path) : undefined
+      return Array.isArray(raw) ? raw : raw ? [raw] : []
+    }
+    const throughAll = listOf(throughInfo)
+    const mineAll = listOf(info)
+    const mineIds = new Set(mineAll.map(idOf).filter(Boolean) as string[])
+
+    const depthCap = Math.min(Math.max(maxDepth ?? 6, 1), 12)
+    const itemCap = Math.min(Math.max(maxItems ?? 200, 1), 2000)
+
+    const items: any[] = [{ id: itemId, axis, depth: 0, qty: 1, known: mineIds.has(itemId) }]
+    const edges: any[] = []
+    const seen = new Set<string>([itemId])
+    const cycles: string[] = []
+    let depthTruncated = false
+    let itemTruncated = false
+
+    /* 너비 우선 — 깊이 상한에서 끊기면 **얕은 층은 온전히** 남는다(깊이 우선이면 한 가지만 깊게 파고 끊긴다). */
+    let frontier: { id: string; depth: number; qty: number | null }[] = [{ id: itemId, depth: 0, qty: 1 }]
+    while (frontier.length) {
+      const nextFrontier: typeof frontier = []
+      for (const cur of frontier) {
+        if (cur.depth >= depthCap) { depthTruncated = true; continue }
+        /* 나를 만들어 내는 중간 항목들(레시피)을 찾는다 — 선언된 홉을 따라. */
+        for (const t of throughAll) {
+          const producesMe = entriesAt(t, chosen.inField).some(e => String(idOf(e.value) ?? e.value) === cur.id)
+          if (!producesMe) continue
+          for (const e of entriesAt(t, chosen.outField)) {
+            const childId = String(idOf(e.value) ?? e.value)
+            const step = qtyOf(e.holder)
+            /* 수량을 모르면 **곱하지 않는다.** 1 로 메우면 "1개 필요" 라는 사실 주장이 되고,
+               윗단에서 곱해진 값이 전부 거짓이 된다. */
+            const qty = cur.qty != null && step != null ? cur.qty * step : null
+            edges.push({ from: cur.id, to: childId, through: idOf(t), depth: cur.depth + 1, step, qty })
+
+            if (seen.has(childId)) {
+              /* 이미 지난 항목으로 돌아왔다 — 사이클이거나 공유 부품이다. 어느 쪽이든 **다시 파지
+                 않고 말한다.** 파고 들어가면 돌아 나오지 못한다. */
+              if (edges.some(x => x.to === cur.id && x.from === childId)) cycles.push(`${cur.id} ↔ ${childId}`)
+              continue
+            }
+            if (items.length >= itemCap) { itemTruncated = true; continue }
+            seen.add(childId)
+            items.push({ id: childId, axis, depth: cur.depth + 1, qty, known: mineIds.has(childId) })
+            nextFrontier.push({ id: childId, depth: cur.depth + 1, qty })
+          }
+        }
+      }
+      frontier = nextFrontier
+    }
+
+    return {
+      axis,
+      itemId,
+      /* 어떤 순환을 따라 펼쳤는지 **밝힌다** — 방향이 뒤집힌 전개는 틀린 답이 아니라 반대의 답이라
+         화면만 보고는 구별되지 않는다. */
+      pattern: chosen,
+      patterns: all,
+      items,
+      edges,
+      /* 수량을 하나라도 모르면 아래 합계가 성립하지 않는다는 사실을 그대로 낸다. */
+      qtyIncomplete: edges.some(e => e.step == null),
+      cycles: [...new Set(cycles)],
+      truncated: { depth: depthTruncated, items: itemTruncated, depthCap, itemCap },
+      basis: 'document'
+    }
+  }
+}

package/server/service/twin-model/twin-operation.ts

@@ -0,0 +1,157 @@
+import { CreateDateColumn, Entity, Index, Column, RelationId, ManyToOne, PrimaryGeneratedColumn, UpdateDateColumn } from 'typeorm'
+import { ObjectType, Field, ID, Int } from 'type-graphql'
+
+import { Domain, ScalarObject } from '@things-factory/shell'
+
+import { TwinInstance } from '../twin-instance/twin-instance.js'
+
+/*
+ * TwinOperation — 이 트윈이 반영하는 **공정 명세**. ISA-95 `OperationsSegment`.
+ * 이 현장에서 각 작업이 **어디서·무엇으로·얼마나 걸리나**(선언값).
+ *
+ * ── 왜 이 표가 인스펙션의 중심인가 ──────────────────────────────────────────
+ * 인스펙션 화면의 존재 이유는 `선언 | 관측` 두 열이고(`plans/twin-inspection.md` §2.4),
+ * 그 첫 열이 여기서 온다. 둘째 열은 저널에서 접힌다(`kpi-fold.workTime`).
+ * 실적은 보이는데 기준이 안 보이면 "절단이 5분 걸렸다" 를 보고도 빠른지 느린지 알 수 없다.
+ *
+ * 자리·설비와 같은 규율 — **원본에서 온 캐시**, `sourceRef`·`ingestedAt` 필수,
+ * 쓰기 경로는 인제스트 하나(`twin-location.ts` 머리말).
+ */
+@Entity({ name: 'twin_operations' })
+@Index('ix_twin_operation_0', (e: TwinOperation) => [e.domain, e.instance, e.operationKey], { unique: true })
+@ObjectType({ description: 'An operation spec reflected into the twin (ISA-95 OperationsSegment): where it runs, with what, and how long the source says it takes.' })
+export class TwinOperation {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(type => ID)
+  readonly id: string
+
+  @ManyToOne(type => Domain)
+  @Field(type => Domain, { nullable: true, description: 'Owning tenant domain.' })
+  domain?: Domain
+
+  @RelationId((e: TwinOperation) => e.domain)
+  domainId?: string
+
+  @ManyToOne(type => TwinInstance, { onDelete: 'CASCADE' })
+  @Field(type => TwinInstance, { nullable: true, description: 'Owning twin instance.' })
+  instance?: TwinInstance
+
+  @RelationId((e: TwinOperation) => e.instance)
+  instanceRowId?: string
+
+  /** 커널 계약의 `OperationDef.key` 그대로. 라우트의 단계가 이 키로 가리킨다. */
+  @Column()
+  @Field({ description: 'Operation key as declared by the source (kernel OperationDef.key). Route steps reference this.' })
+  operationKey: string
+
+  /**
+   * **사람이 부르는 이름** — 프레임워크 엔티티 규약의 `name`/`description`.
+   *
+   * ── 왜 이것이 빠져 있었고, 무엇이 망가졌나 ────────────────────────────────────
+   * 투영이 마스터의 `name` 을 버리고 있었다. 그래서 행에는 id 만 남고, 화면은 이름을 만들 재료가
+   * 없어 `cut-station` 을 그대로 찍었다 — 그 결함이 목록·표·관계 그림마다 따로 나타나서 표면을
+   * 하나씩 고치게 만들었다. 표면의 문제가 아니라 **행에 이름이 없던 문제**다.
+   *
+   * 원본이 이름을 말하지 않으면 비운다(id 를 이름으로 베끼지 않는다 — 그러면 "이름이 있다" 는
+   * 거짓이 되고, 화면이 이름 없음을 알아볼 수 없게 된다).
+   */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Human name as declared by the source. Empty when the source does not name it (never copied from the id).' })
+  name?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Longer description when the source provides one.' })
+  description?: string
+
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: "Intent: 'transport' | 'process' | 'dwell'." })
+  intent?: string
+
+  /*
+   * 어디서·무엇으로 — 자리·설비의 **항목이 아니라 타입**을 가리킨다("절단은 cut-station 에서 수행된다").
+   * 그래서 FK 가 아니다. 화면은 이것을 "그 타입의 자리·설비 목록" 으로 푼다(관계 선언의 `type` 대상).
+   */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Location type this operation runs at (a catalog type key, not an item reference).' })
+  locationType?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Resource type that performs it (a catalog type key, not an item reference).' })
+  resourceType?: string
+
+  /**
+   * 소요시간 — **ISO 8601 기간 문자열이 정본**(`PT1H10M`).
+   *
+   * 분으로 저장하면 `PT1H10M30S` 의 초가 사라지고 그 손실은 조용하다. 사람이 읽을 분은
+   * 화면이 곁들여 보여 주고, 못 읽는 값은 `—` 로 낸다(0 으로 채우면 "즉시 끝나는 공정" 이라는 거짓).
+   */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Declared duration as an ISO 8601 period (e.g. PT1H10M). The string is canonical — storing minutes would silently drop seconds.' })
+  duration?: string
+
+  /**
+   * 변동성·파라미터(수율·셋업)는 형이 도메인마다 달라 **원형 그대로** 싣는다.
+   * 여기를 컬럼으로 펴려면 커널이 그 형을 먼저 고정해야 한다 — 아직 아니다.
+   */
+  @Column({ type: 'simple-json', nullable: true })
+  @Field(type => ScalarObject, { nullable: true, description: 'Declared variability (distribution/min/max/mode) as given by the source.' })
+  variability?: any
+
+  @Column({ type: 'simple-json', nullable: true })
+  @Field(type => ScalarObject, { nullable: true, description: 'Declared parameters (yield, setup duration…) as given by the source.' })
+  parameters?: any
+
+  /**
+   * **네 자원 명세 — 선언한 것만 제약이 된다.**
+   *
+   * ISA-95 는 한 공정이 무엇을 필요로 하는지를 넷으로 말한다: 설비(`resourceType`)·인원·자산·자재.
+   * 커널도 그 넷을 그대로 본다 — 선언이 있으면 잡아야 작업이 시작되고, 없으면 그 자원을 보지 않는다.
+   *
+   * 이 셋이 투영에서 **떨어져 있었다.** 그래서 조회 화면의 "원본이 말한 값" 열에 넷 중 하나만
+   * 나왔고, 사람이 필요한 공정을 보고도 **사람이 필요 없다고 결론 내게** 되어 있었다. 원본이 말한
+   * 것을 화면이 말하지 않으면 그 화면은 원본을 반영하는 것이 아니다.
+   *
+   * 모양은 커널 계약 그대로 싣는다 — 인제스트 경계에서 모양을 바꾸면 그 자리에서 방언이 생긴다.
+   */
+  @Column({ type: 'simple-json', nullable: true })
+  @Field(type => ScalarObject, { nullable: true, description: 'Personnel this operation requires (ISA-95 PersonnelSpecification): class + quantity. Absent means the operation runs without people.' })
+  personnelSpecification?: any
+
+  @Column({ type: 'simple-json', nullable: true })
+  @Field(type => ScalarObject, { nullable: true, description: 'Physical assets this operation requires (ISA-95 PhysicalAssetSpecification). Absent means no asset constraint — an empty pallet is never the reason a job waits.' })
+  physicalAssetSpecification?: any
+
+  @Column({ type: 'simple-json', nullable: true })
+  @Field(type => ScalarObject, { nullable: true, description: 'Materials this operation consumes or produces (ISA-95 MaterialSpecification). Absent means material shortage never shows up in the forecast for this step.' })
+  materialSpecification?: any
+
+  /** 라우트 안에서의 순서 — 라우트가 이 공정을 몇 번째로 부르나(라우트 표가 서면 그리로 옮긴다). */
+  @Column({ type: 'int', nullable: true })
+  @Field(type => Int, { nullable: true, description: 'Sequence within its route, when the source declares one.' })
+  seq?: number
+
+  /* ── 캐시라는 사실을 구조로 (ADR-0032-D) ── */
+  @Column()
+  @Field({ description: 'Which reference (source system) this row came from. Required.' })
+  sourceRef: string
+
+  /*
+   * **타입 이름을 적지 않는다** (2026-08-19 Postgres 부팅 실패로 고침).
+   *
+   * `datetime` 은 sqlite·MySQL 의 이름이고 Postgres 는 `timestamp` 만 안다 — 거꾸로 `timestamp` 는
+   * sqlite 가 모른다. **다섯 드라이버에 다 통하는 이름이 없다.** 그래서 이름 고르는 일을 TypeORM 에
+   * 맡긴다(`emitDecoratorMetadata` 가 켜져 있어 `Date` 에서 드라이버별 타입을 고른다).
+   */
+  @Column()
+  @Field({ description: 'When this row was projected from the source.' })
+  ingestedAt: Date
+
+  @CreateDateColumn()
+  @Field({ nullable: true })
+  createdAt?: Date
+
+  @UpdateDateColumn()
+  @Field({ nullable: true })
+  updatedAt?: Date
+}

package/server/service/twin-space/move-space.ts

@@ -0,0 +1,262 @@
+/*
+ * 이미 있는 트윈을 다른 현장으로 옮긴다 — **판정만**. 순수.
+ *
+ * ── 왜 있나 (2026-08-13) ────────────────────────────────────────────────────
+ * 트윈↔현장 연결은 **만들 때만** 정할 수 있었다(템플릿 위자드·import 의 `spaceId`). 잘못 넣었거나,
+ * 나중에 "이 창고는 사실 저 공장과 같은 부지다" 를 알게 되면 지우고 다시 만드는 것이 유일한 길이었다 —
+ * 다시 만들면 그 트윈의 저널(일어난 일)이 사라진다. 고칠 수 있는 실수를 데이터 손실로 갚게 하는 설계다.
+ *
+ * ── 옮기는 것이 무엇을 옮기나 (엔티티 키를 보고 정했다) ──────────────────────
+ * 무엇이 트윈에 매여 있고 무엇이 공간에 매여 있는지가 답을 정한다:
+ *
+ *  · `TwinEvent`         `(domain, instanceId, …)`  → **따라온다.** 저널을 다시 쓰지 않는다.
+ *  · `TwinLocation/Equipment/Operation`  `(domain, instance, …)`  → **따라온다.**
+ *  · `TwinArea`          `(domain, space, areaId)`  → **남는다.** 구역은 공간의 것이다.
+ *  · `TwinSpaceRepresentation`(지도·이미지·보드)     → **남는다.** 표현도 공간의 것이다.
+ *
+ * 그래서 옮기기는 이력 이전이 아니라 **소속 갱신**이다(`instance.spaceId` + `model.spaceId`).
+ * 대신 공간에 매인 것들과의 연결이 끊길 수 있고, 그것을 **조용히 넘기지 않는 것**이 이 모듈의 일이다.
+ *
+ * ── 거절과 경고를 가른다 ────────────────────────────────────────────────────
+ * 거절: 되돌릴 수 없거나 뜻이 성립하지 않는 것(없는 공간·같은 공간·벤치 사본).
+ * 경고: 사용자가 알고 나면 정당할 수 있는 것(구역 소속이 끊긴다·시간대가 다르다·옛 표현이 남는다).
+ * 경고를 거절로 올리면 정당한 이전을 막고, 거절을 경고로 낮추면 조용한 사고가 된다.
+ */
+
+/** 옮길 수 없는 이유 — 언어 중립 코드(발견 오류·인제스트 거절과 같은 규약). */
+export type MoveSpaceRefusalCode = 'twin-not-found' | 'space-not-found' | 'same-space' | 'bench-copy'
+
+/** 옮겨도 되지만 알아야 하는 것 — 같은 규약. */
+export type MoveSpaceWarningCode = 'areas-left-behind' | 'timezone-differs' | 'representations-left-behind' | 'running'
+
+export interface MoveSpaceNote<C extends string> {
+  code: C
+  params?: Record<string, string | number>
+  /** 영어 canonical — 로그에 남고, 번역이 없으면 그대로 보인다. */
+  message: string
+}
+
+export type MoveSpaceRefusal = MoveSpaceNote<MoveSpaceRefusalCode>
+export type MoveSpaceWarning = MoveSpaceNote<MoveSpaceWarningCode>
+
+export interface MoveSpaceInput {
+  /** 옮길 트윈. 없으면 거절한다. */
+  instanceId?: string
+  /** 지금 속한 공간(없을 수 있다 — 옛 트윈). */
+  fromSpaceId?: string
+  /** 옮겨 갈 공간. */
+  toSpaceId: string
+  /** 그 공간이 이 테넌트에 실제로 있나(호출측이 조회해 넘긴다). */
+  toSpaceExists: boolean
+  /** 운영 트윈인가 벤치 사본인가 — 사본은 원본의 공간을 따라야 하므로 옮기지 않는다. */
+  purpose?: string
+  /** 지금 실행 중인가 — 시간대 변화는 재기동 뒤에 커널에 실린다. */
+  running?: boolean
+  /** 두 공간의 시간대(IANA). 다르면 앞으로의 시각 해석이 달라진다. */
+  fromTimezone?: string
+  toTimezone?: string
+  /** 이 트윈의 로케이션들이 소속으로 가리키는 구역 id 들(중복 포함 가능). */
+  areaRefs?: readonly (string | undefined | null)[]
+  /** 옮겨 갈 공간에 있는 구역 id 들. */
+  toAreaIds?: readonly string[]
+  /** 옛 공간의 표현 수 — 그 표현의 폴리곤이 이 트윈을 가리키고 있었을 수 있다. */
+  fromRepresentationCount?: number
+}
+
+export interface MoveSpaceJudgement {
+  /** 있으면 옮기지 않는다. */
+  refusal?: MoveSpaceRefusal
+  /** 옮기되 함께 알린다. 비어 있으면 잃는 것이 없다. */
+  warnings: MoveSpaceWarning[]
+}
+
+/** 옮겨도 되나 — 되면 무엇을 알려야 하나. */
+export function judgeMoveTwinSpace(input: MoveSpaceInput): MoveSpaceJudgement {
+  const to = (input.toSpaceId ?? '').trim()
+  const from = (input.fromSpaceId ?? '').trim()
+
+  if (!input.instanceId) {
+    return {
+      refusal: { code: 'twin-not-found', message: 'no such twin in this tenant' },
+      warnings: []
+    }
+  }
+  if (!to || !input.toSpaceExists) {
+    return {
+      refusal: {
+        code: 'space-not-found',
+        params: { spaceId: to },
+        message: `space "${to}" not found — cannot move a twin into a space that does not exist`
+      },
+      warnings: []
+    }
+  }
+  if (from && from === to) {
+    return {
+      refusal: {
+        code: 'same-space',
+        params: { spaceId: to },
+        message: `twin "${input.instanceId}" is already in space "${to}"`
+      },
+      warnings: []
+    }
+  }
+  /* 벤치 사본은 "이 공장이 이만큼 커지면" 을 재는 사본이라 원본의 현장에 매여 있다. 옮기면 그 측정이
+     무엇의 측정인지 말할 수 없게 된다 — 사본을 옮기는 대신 원본을 옮기고 사본을 다시 뜬다. */
+  if (input.purpose === 'bench') {
+    return {
+      refusal: {
+        code: 'bench-copy',
+        params: { instanceId: input.instanceId },
+        message: `twin "${input.instanceId}" is a bench copy — move its source twin instead`
+      },
+      warnings: []
+    }
+  }
+
+  const warnings: MoveSpaceWarning[] = []
+
+  /* 로케이션의 구역 소속 — 구역은 공간의 것이라 새 공간에 같은 id 가 없으면 소속이 끊긴다.
+     막지는 않는다(새 공간에서 구역을 다시 그리는 것이 정상 경로다). 다만 몇 개가 끊기는지 말한다. */
+  const refs = [...new Set((input.areaRefs ?? []).filter((x): x is string => !!x && !!x.trim()))]
+  const have = new Set(input.toAreaIds ?? [])
+  const orphaned = refs.filter(r => !have.has(r)).sort()
+  if (orphaned.length) {
+    warnings.push({
+      code: 'areas-left-behind',
+      params: { count: orphaned.length, areas: orphaned.slice(0, 5).join(', ') },
+      message: `${orphaned.length} area reference(s) do not exist in the target space — those locations lose their grouping: ${orphaned
+        .slice(0, 5)
+        .join(', ')}`
+    })
+  }
+
+  /* 시간대 — 공간이 정하고 커널이 분 오프셋으로 받는다. 다르면 같은 저널이 다른 시각으로 읽힌다. */
+  const tzFrom = (input.fromTimezone ?? '').trim()
+  const tzTo = (input.toTimezone ?? '').trim()
+  if (tzFrom !== tzTo) {
+    warnings.push({
+      code: 'timezone-differs',
+      params: { from: tzFrom || '—', to: tzTo || '—' },
+      message: `time zone changes from "${tzFrom || 'unset'}" to "${tzTo || 'unset'}" — shift boundaries and day buckets will read differently`
+    })
+  }
+
+  /* 옛 공간의 표현 — 폴리곤 바인딩이 이 트윈의 로케이션·그룹을 가리키고 있었을 수 있다. 표현은
+     공간에 남으므로, 그 화면에서 이 트윈이 사라진다. 몇 개가 남는지 말해 두면 사람이 찾아갈 수 있다. */
+  if ((input.fromRepresentationCount ?? 0) > 0) {
+    warnings.push({
+      code: 'representations-left-behind',
+      params: { count: input.fromRepresentationCount as number, spaceId: from || '—' },
+      message: `${input.fromRepresentationCount} representation(s) stay with space "${from}" — bindings that pointed at this twin will no longer resolve there`
+    })
+  }
+
+  /* 실행 중 — 소속은 즉시 바뀌지만 시간대는 커널을 세울 때 실린다. 시간대가 같으면 말할 것이 없다. */
+  if (input.running && tzFrom !== tzTo) {
+    warnings.push({
+      code: 'running',
+      params: { instanceId: input.instanceId },
+      message: `twin "${input.instanceId}" is running — the new time zone applies after it is restarted`
+    })
+  }
+
+  return { warnings }
+}
+
+/*
+ * ── 현장에서 떼기 (2026-08-13) ──────────────────────────────────────────────
+ *
+ * 더하기·옮기기만 있으면 잘못 넣은 것을 되돌릴 수 없다. 떼기는 "어느 현장에도 속하지 않음" 으로
+ * 되돌리는 일이고, 데이터 모델이 그 상태를 이미 허용한다(`TwinInstance.spaceId` 는 선택 컬럼).
+ *
+ * 떼면 무엇이 달라지나 — 옮기기와 같은 규칙이지만 **갈 곳이 없다**는 점이 다르다:
+ *  · 저널·로케이션·설비는 그대로 트윈에 남는다(잃는 것 없음).
+ *  · 구역·표현은 옛 현장에 남는다 → 그 화면에서 이 트윈이 사라진다.
+ *  · **볼 무대가 없어진다** — 현장 현황(지도·보드)은 현장의 표현으로 그리므로, 뗀 트윈은 목록과
+ *    조회 화면에서만 보인다. 이것을 말하지 않으면 사용자는 트윈이 고장 났다고 읽는다.
+ *  · 시간 기준(`utcOffsetMinutes`)은 **옛 현장의 것으로 남는다.** 지우면 조용히 UTC 로 읽히므로
+ *    그쪽이 더 위험하다 — 남기고 그 사실을 말한다.
+ */
+
+/** 뗄 수 없는 이유 — 언어 중립 코드. */
+export type DetachSpaceRefusalCode = 'twin-not-found' | 'no-space' | 'bench-copy'
+
+/** 떼도 되지만 알아야 하는 것. */
+export type DetachSpaceWarningCode = 'no-stage' | 'representations-left-behind' | 'timebase-kept'
+
+export type DetachSpaceRefusal = MoveSpaceNote<DetachSpaceRefusalCode>
+export type DetachSpaceWarning = MoveSpaceNote<DetachSpaceWarningCode>
+
+export interface DetachSpaceInput {
+  instanceId?: string
+  /** 지금 속한 공간 — 없으면 뗄 것이 없다. */
+  fromSpaceId?: string
+  purpose?: string
+  /** 옛 공간의 표현 수. */
+  fromRepresentationCount?: number
+  /** 옛 공간의 시간대 — 있으면 그 기준이 model 에 남는다. */
+  fromTimezone?: string
+}
+
+export interface DetachSpaceJudgement {
+  refusal?: DetachSpaceRefusal
+  warnings: DetachSpaceWarning[]
+}
+
+/** 떼도 되나 — 되면 무엇을 알려야 하나. */
+export function judgeDetachTwinSpace(input: DetachSpaceInput): DetachSpaceJudgement {
+  const from = (input.fromSpaceId ?? '').trim()
+
+  if (!input.instanceId) {
+    return { refusal: { code: 'twin-not-found', message: 'no such twin in this tenant' }, warnings: [] }
+  }
+  if (!from) {
+    return {
+      refusal: {
+        code: 'no-space',
+        params: { instanceId: input.instanceId },
+        message: `twin "${input.instanceId}" is not on any site — nothing to detach`
+      },
+      warnings: []
+    }
+  }
+  /* 벤치 사본은 원본의 현장을 따라야 측정이 무엇의 측정인지 말할 수 있다(옮기기와 같은 이유). */
+  if (input.purpose === 'bench') {
+    return {
+      refusal: {
+        code: 'bench-copy',
+        params: { instanceId: input.instanceId },
+        message: `twin "${input.instanceId}" is a bench copy — it must stay on the site it measures`
+      },
+      warnings: []
+    }
+  }
+
+  const warnings: DetachSpaceWarning[] = [
+    {
+      code: 'no-stage',
+      params: { instanceId: input.instanceId },
+      message: `twin "${input.instanceId}" will have no site to be drawn on — it stays visible in lists and inspection only`
+    }
+  ]
+
+  if ((input.fromRepresentationCount ?? 0) > 0) {
+    warnings.push({
+      code: 'representations-left-behind',
+      params: { count: input.fromRepresentationCount as number, spaceId: from },
+      message: `${input.fromRepresentationCount} representation(s) stay with space "${from}" — bindings that pointed at this twin will no longer resolve there`
+    })
+  }
+
+  const tz = (input.fromTimezone ?? '').trim()
+  if (tz) {
+    warnings.push({
+      code: 'timebase-kept',
+      params: { timezone: tz },
+      message: `the time base stays as "${tz}" (the site it came from) — clearing it would silently read times as UTC`
+    })
+  }
+
+  return { warnings }
+}