@things-factory/headless-twin 10.0.8 → 10.0.10

package/server/service/twin-target/twin-target-resolver.ts

@@ -11,9 +11,27 @@ import { TWIN_METRIC, isTwinMetric } from '../../engine/kpi-target.js'
  * 경영 KPI 관리메뉴가 아니라 여기인 이유: 목표가 숫자 옆에 있어야 맥락이 살고, 운영 임계는 자주
  * 조정된다. 조직 단위 기간 평가는 `@things-factory/kpi` 의 일이고 이쪽으로 베껴 오지 않는다.
  */
+/*
+ * **쓰기는 막고 읽기는 연다** (2026-08-06 · ADR-0027).
+ *
+ * 이 리졸버는 트윈 리졸버 중 **유일하게** 권한 게이트를 갖는데, 처음에는 우회 표시가 없었다
+ * (`@privilege(category:"twin", privilege:"query")`). 그러면 `twin/query`·`twin/mutation` 권한을
+ * 실제로 부여받은 사용자만 쓸 수 있는데 — **저장소 어디에도 그 권한을 만드는 곳이 없다.** 결과는
+ * 도메인 소유자도 슈퍼유저도 목표를 걸 수 없는 상태였다: 성과 화면의 목표 버튼이 "Unauthorized" 로
+ * 떨어지고, 이 관점의 최상위 기능(§5 목표 프레임)이 **아무도 쓸 수 없는 채로** 놓여 있었다.
+ *
+ * 그래서 프레임워크의 통용 관용구를 따른다 — 가장 가까운 형제인 `@things-factory/kpi`(목표·지표 관리)가
+ * 74곳 전부 `domainOwnerGranted: true, superUserGranted: true` 를 쓴다. 같은 성격의 조작(무엇을 잘한
+ * 것으로 볼지 정하는 일)이므로 같은 자세를 쓴다: **현장을 소유한 사람은 바로 쓰고**, 다른 사람에게
+ * 맡기려면 `twin` 권한을 부여한다.
+ *
+ * 이제 트윈의 **모든 변경**에 같은 게이트가 있다(ADR-0027) — 처음에는 이 리졸버 하나만 게이트를 갖는
+ * 반쪽이었다. 조회 게이트는 걷었다: 같은 판정이 `twinKpi` 로 이미 열려 있어 지키는 것이 없었다.
+ */
 @Resolver()
 export class TwinTargetResolver {
-  @Directive('@privilege(category: "twin", privilege: "query")')
+  /* 조회에는 게이트를 두지 않는다 — 같은 판정이 `twinKpi.targets` 로 이미 열려 있어(그쪽은 게이트가
+     없다) 여기만 막으면 지키는 것 없이 화면만 깨진다. 읽기의 경계는 **테넌트 소속**이다. */
   @Query(returns => [String], {
     description:
       'The metric ids a twin target may refer to. Fixed in one place so a target and the fact it judges can never drift into two names.'
@@ -22,7 +40,7 @@ export class TwinTargetResolver {
     return Object.keys(TWIN_METRIC)
   }
 
-  @Directive('@privilege(category: "twin", privilege: "query")')
+
   @Query(returns => [TwinTarget], {
     description:
       'Operational targets in scope — site-wide targets for the space plus targets bound to the given instance. Callers judge with the narrower one when both exist.'
@@ -37,7 +55,7 @@ export class TwinTargetResolver {
     return rows.filter(r => (spaceId && r.spaceId === spaceId) || (instanceId && r.instanceId === instanceId))
   }
 
-  @Directive('@privilege(category: "twin", privilege: "mutation")')
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => Boolean, {
     description:
       'Create or update one operational target. The metric must be one of twinTargetMetrics — an unknown name is rejected rather than stored, because a target nobody can evaluate reads as "no target" and hides the gap.'
@@ -79,7 +97,7 @@ export class TwinTargetResolver {
     return true
   }
 
-  @Directive('@privilege(category: "twin", privilege: "mutation")')
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => Boolean, { description: 'Remove an operational target. Removing a target removes the judgement, not the fact — the metric keeps being reported without a verdict.' })
   async deleteTwinTarget(
     @Arg('metric') metric: string,

package/shared/axis-read.ts

@@ -0,0 +1,28 @@
+/*
+ * 축의 값을 **어디서 읽나** — 규칙 한 곳. (design/profiles/ems.md §10 6.5단계)
+ *
+ * ── 왜 함수로 빼나 ─────────────────────────────────────────────────────────
+ * 개념 지도는 상태 축을 `state[축이름]` 으로 읽고 있었다. 에너지의 수요 구간은 `state.energy.closed`
+ * 에 살아서 그 규칙으로는 **언제나 `undefined`** 다 — 카드가 「관측 없음」으로 굳고, 원인은 화면도
+ * 서버도 말해 주지 않는다(축은 선언돼 있고 상태에도 값이 있는데 이름이 안 맞을 뿐이다).
+ *
+ * 커널 선언이 이미 그 자리를 말한다(`TwinAxisInfo.path`). 그래서 규칙은 한 줄이다:
+ * **경로가 있으면 그 경로로, 없으면 축 이름으로.** 리졸버 안에 두면 시험이 DB 를 물어야 하므로
+ * 순수 함수로 빼 둔다.
+ */
+
+/** 중첩 경로를 따라간다 — 중간이 없으면 `undefined`(빈 객체로 메우지 않는다). */
+export function atPath(obj: any, path: string): any {
+  return path.split('.').reduce((o: any, k: string) => (o == null ? undefined : o[k]), obj)
+}
+
+/**
+ * 그 축의 값 — 배열이면 목록, 객체면 그릇, 없으면 `undefined`.
+ *
+ * `undefined` 와 빈 배열은 **다르다**: 앞은 「모른다·아직 안 옴」이고 뒤는 「없다」다. 이 함수는 그
+ * 구별을 지우지 않는다 — 소비처가 `emptyBecause` 를 그 차이로 만든다.
+ */
+export function axisValueOf(state: any, axis: { axis: string; path?: string }): any {
+  if (!state || !axis?.axis) return undefined
+  return axis.path ? atPath(state, axis.path) : state[axis.axis]
+}

package/shared/entity-delta.ts

@@ -0,0 +1,286 @@
+/*
+ * 트윈 State 스냅샷 → 라이브 바인딩 delta 목록 (순수 매핑 — pubsub/도메인 무관 → 단위 테스트 가능).
+ * publishEntityData 가 이 목록을 엔티티별 시그니처로 dedup 후 data(tag) 채널로 발행한다.
+ *
+ * ── 규율: 레퍼런스가 아는 것은 **전부** 내보낸다 ────────────────────────────
+ * 트윈에서 사소한 속성은 없다. 소속 구역·소속 팔레트·수량·만료처럼 곁가지로 보이는 값이 실제로는
+ * 구역 롤업·적재 표현·로트 추적의 전제다. 그래서 여기서 **필드를 손으로 골라 담지 않는다.**
+ *
+ * 예전에는 엔티티마다 필요할 것 같은 필드만 열거했고, 그 결과 계약에 있는 것이 조용히 누락됐다
+ * (2026-08-01 감사: 노드 parentId 누락 · 작업 전량 누락 · 물품 전량 누락). 화이트리스트 방식은
+ * **계약이 자라도 화면이 따라오지 못한다** — 커널이 속성을 늘릴 때마다 이 파일을 고쳐야 하고, 고치는
+ * 것을 잊으면 아무 신호 없이 정보가 사라진다.
+ *
+ * 그래서 반대로 한다: **상태 객체가 가진 것을 그대로 통과**시키고, 통과시키지 **않을** 것만 이유와 함께
+ * 열거한다(EXCLUDED). 새 속성은 자동으로 화면에 도달하고, 빼려면 이유를 적어야 한다.
+ *
+ * ── 표식은 도메인 낱말을 훔치지 않는다 ─────────────────────────────────────
+ * 예전 payload 는 엔티티 종류 표식을 `kind` 로 실었다. 그런데 `kind` 는 **도메인의 낱말**이다 —
+ * 무버 kind=cutter, 작업 kind=putaway, 오더 kind=workorder. 표식이 그 이름을 차지하면 도메인 속성을
+ * 실을 자리가 없어진다(같은 병을 오늘 ox-timeline 의 `group` 에서도 고쳤다).
+ * 그래서 표식은 `entity`(우리 이름)로 옮기고 `kind` 는 도메인에 돌려준다.
+ *
+ * payload 계약(씬 컴포넌트가 소비): `entity`(표식) + 그 엔티티의 모든 속성(도메인 `kind` 포함).
+ *   entity = location · equipment · person · asset · order · task · item,
+ *   그리고 집약 태그(__orders__ · __tasks__ · __items__ · __persons__ · __assets__).
+ */
+
+export interface EntityDelta {
+  tag: string
+  data: any
+}
+
+/** 집약 고정 태그 — 클라 provider 와 일치해야 한다(런타임 생성 엔티티는 개별 배치가 불가하므로 집약 뷰). */
+/*
+ * 집약 채널의 접두사 — **실제 태그는 트윈 식별자를 붙여 만든다.**
+ *
+ * 예전에는 이 상수가 곧 태그였다. 그런데 발행 키는 (도메인, 태그)이고, **한 공간에 트윈이 여럿**
+ * 있으면(실측: 3곳 × 3개) 셋이 같은 태그로 발행해 서로 덮었다. 보드의 주문 목록판이 세 공장의 주문
+ * 중 마지막에 도착한 것을 보여 준다 — 오류 없이.
+ *
+ * 구간 성과 태그가 이미 `__kpi__:<트윈>` 으로 트윈을 붙이고 있었다(`kpi-broadcast.ts`). 같은 규약으로 맞춘다.
+ */
+export const ORDERS_TAG_PREFIX = '__orders__'
+export const TASKS_TAG_PREFIX = '__tasks__'
+export const ITEMS_TAG_PREFIX = '__items__'
+export const PERSONS_TAG_PREFIX = '__persons__'
+export const ASSETS_TAG_PREFIX = '__assets__'
+/** 에너지 집약 — 수요 구간·피크·계약은 **트윈 하나의 사실**이라 개체 태그가 없다. */
+export const ENERGY_TAG_PREFIX = '__energy__'
+
+/** 이 트윈의 집약 채널 태그. 트윈 식별자가 없으면 만들지 않는다 — 덮어쓰기의 원인이었다. */
+export function aggregateTag(prefix: string, instanceId: string): string {
+  if (!instanceId) throw new Error('aggregateTag: instanceId required — 트윈 구분이 없는 태그는 다른 트윈의 것을 덮는다')
+
+  return `${prefix}:${instanceId}`
+}
+
+export const ordersTag = (instanceId: string) => aggregateTag(ORDERS_TAG_PREFIX, instanceId)
+export const tasksTag = (instanceId: string) => aggregateTag(TASKS_TAG_PREFIX, instanceId)
+export const itemsTag = (instanceId: string) => aggregateTag(ITEMS_TAG_PREFIX, instanceId)
+export const personsTag = (instanceId: string) => aggregateTag(PERSONS_TAG_PREFIX, instanceId)
+export const assetsTag = (instanceId: string) => aggregateTag(ASSETS_TAG_PREFIX, instanceId)
+export const energyTag = (instanceId: string) => aggregateTag(ENERGY_TAG_PREFIX, instanceId)
+
+/**
+ * 통과시키지 않는 필드 — **빼는 데는 이유가 필요하다.**
+ *
+ * · `id`/`epc` — 태그로 이미 나가므로 개별 payload 에 중복해 싣지 않는다(집약 뷰에는 넣는다).
+ * · `oee` — 원시 누적(idleMs 등)이 매 delta 증가해 "무변화 생략" 을 무력화한다. shapeOee 로 정형화해 얹는다.
+ */
+const EXCLUDED = new Set(['id', 'epc', 'oee'])
+
+/**
+ * OEE 원시 비율/카운트 → 표시용 정수 퍼센트 + 카운트.
+ * 원시 누적 ms(idleMs 등)는 매 delta 증가해 무변화-생략을 무력화하므로 제외(유휴 자원의 매초 재방송 억제).
+ * oee 미측정이면 undefined.
+ */
+function shapeOee(o: any): any {
+  if (!o) return undefined
+  return {
+    overall: Math.round((o.overall ?? 0) * 100),
+    availability: Math.round((o.availability ?? 0) * 100),
+    performance: Math.round((o.performance ?? 0) * 100),
+    quality: Math.round((o.quality ?? 0) * 100),
+    good: o.goodCount ?? 0,
+    scrap: o.scrapCount ?? 0
+  }
+}
+
+/**
+ * 엔티티 하나의 payload — `entity` 표식 + 나머지 전부(도메인 `kind` 포함).
+ *
+ * `undefined` 값은 싣지 않는다(키의 유무가 시그니처를 흔들지 않게). 값이 없는 것과 키가 없는 것은
+ * 소비처에서 같으므로 안전하고, 무변화 생략이 잘 듣는다.
+ */
+function payloadOf(entityKind: string, entity: any): any {
+  /* 표식은 `entity` — 도메인의 `kind` 를 덮지 않는다. */
+  const data: any = { entity: entityKind }
+  for (const [k, v] of Object.entries(entity ?? {})) {
+    if (EXCLUDED.has(k) || v === undefined) continue
+    data[k] = v
+  }
+  return data
+}
+
+/**
+ * 집약 뷰의 항목 — 개별 payload 와 같은 내용 + 식별자.
+ * 집약은 "전체를 한 컴포넌트가 추적" 하는 용도라 식별자가 있어야 한다.
+ */
+function aggregateItem(entity: any, idKey: 'id' | 'epc'): any {
+  const out: any = { [idKey]: entity?.[idKey] }
+  for (const [k, v] of Object.entries(entity ?? {})) {
+    if (k === idKey || k === 'oee' || v === undefined) continue
+    out[k] = v
+  }
+  const shaped = shapeOee(entity?.oee)
+  if (shaped) out.oee = shaped
+  return out
+}
+
+/**
+ * 물품 집약의 상한 — 큰 현장은 물품이 수만 개라, 전량을 매 방송에 실으면 전달이 현장을 느리게 한다.
+ *
+ * **조용히 자르지 않는다**: 넘치면 `total`(전체 수)과 `truncated`(잘린 수)를 함께 실어, 소비처가
+ * "이게 전부" 라고 오해하지 않게 한다. 개별 물품은 태그별 delta 로 따로 나가고 그쪽은 시그니처 dedup
+ * 이 걸려 **변한 것만** 재방송된다.
+ */
+export const ITEMS_AGGREGATE_LIMIT = 500
+
+/**
+ * 자리별 에너지 — **그 자리의 계량기들이 잰 것**을 그 자리 태그에 실을 수 있게 모은다.
+ *
+ * ── 왜 자리에도 필요한가 (2026-08-14) ───────────────────────────────────────
+ * 카탈로그는 자리에도 `metered` 를 준다(수전·분기·구역 계량은 재는 자리다). 그런데 값은 계량기
+ * **설비** 태그로만 나갔다. 그래서 계통도의 분기 자리에 계량 컴포넌트를 놓으면 **영원히 「—」** 였다 —
+ * 능력은 「잰다」고 말하는데 값이 오지 않는 자리.
+ *
+ * 「이 구간이 얼마를 먹나」는 자리의 사실이고, 사람은 계통도의 자리에 붙여 본다.
+ *
+ * ── 계층은 여기서 문제가 되지 않는다 ────────────────────────────────────────
+ * 각 자리에는 **그 자리에 붙은 계량기만** 더한다(수전 자리에는 수전 계량기, 분기 자리에는 그 분기의
+ * 것). 커널이 부하를 뿌리로만 세는 것과 다른 층의 계산이다 — 여기서는 자리마다 자기 것을 말한다.
+ *
+ * 근거를 함께 낸다(`meters`) — 그 자리의 수가 어느 계량기에서 왔는지 되짚을 수 있어야 한다.
+ */
+function energyByLocation(state: any): Map<string, Record<string, unknown>> {
+  const out = new Map<string, Record<string, unknown>>()
+  const points = state?.energy?.points
+  if (!Array.isArray(points) || !points.length) return out
+
+  /* 계량기 → 자리. 자리를 모르는 계량기는 자리 payload 에 실을 데가 없다(설비 태그로만 나간다). */
+  const locOf = new Map<string, string>()
+  for (const e of state?.equipment ?? []) if (e?.id && e?.homeLocation) locOf.set(e.id, e.homeLocation)
+
+  for (const pt of points) {
+    const loc = pt?.id ? locOf.get(pt.id) : undefined
+    if (!loc) continue
+    const acc = out.get(loc) ?? { meters: [] as string[], samplesInWindow: 0 }
+    ;(acc.meters as string[]).push(pt.id)
+    acc.samplesInWindow = Number(acc.samplesInWindow ?? 0) + (Number(pt.samplesInWindow) || 0)
+    /* 값은 **있는 것만** 더한다 — 하나도 없으면 키를 만들지 않는다(0 은 「안 썼다」가 된다). */
+    if (Number.isFinite(Number(pt.kW))) acc.kW = Number(acc.kW ?? 0) + Number(pt.kW)
+    if (Number.isFinite(Number(pt.kWh))) acc.kWh = Number(acc.kWh ?? 0) + Number(pt.kWh)
+    /* 나이는 **가장 최근**을 쓴다 — 자리에 계량기가 여럿이면 그중 마지막 관측이 그 자리의 나이다. */
+    if (pt.atMs !== undefined) {
+      const iso = new Date(Number(pt.atMs)).toISOString()
+      if (!acc.measuredAt || String(acc.measuredAt) < iso) acc.measuredAt = iso
+    }
+    out.set(loc, acc)
+  }
+  return out
+}
+
+export function buildEntityDeltas(state: any, instanceId: string): EntityDelta[] {
+  const out: EntityDelta[] = []
+  const locEnergy = energyByLocation(state)
+
+  for (const n of state?.locations ?? []) {
+    /* 에너지는 자리 payload 에 **합친다** — 같은 태그로 두 번 보내면 뒤엣것이 앞을 덮는다. */
+    const energy = locEnergy.get(n.id)
+    out.push({ tag: n.id, data: energy ? { ...payloadOf('location', n), ...energy } : payloadOf('location', n) })
+  }
+  for (const m of state?.equipment ?? []) {
+    /* Mobile(location/motion) + Operable(status/held) + Processable(oee) — 한 payload 로.
+     * oee 만 정형화가 필요해 따로 얹는다(나머지는 통과). */
+    const data = payloadOf('equipment', m)
+    const oee = shapeOee(m?.oee)
+    if (oee) data.oee = oee
+    out.push({ tag: m.id, data })
+  }
+  /* 사람 — 설비와 별개 엔티티다. 같은 통과 규칙(가진 것을 전부 내보낸다). */
+  for (const p of state?.persons ?? []) {
+    out.push({ tag: p.id, data: payloadOf('person', p) })
+  }
+  /* 물리 자산(반복사용) — 물품도 설비도 아닌 네 번째 자원. */
+  for (const a of state?.assets ?? []) {
+    out.push({ tag: a.id, data: payloadOf('asset', a) })
+  }
+  for (const o of state?.orders ?? []) {
+    out.push({ tag: o.id, data: payloadOf('order', o) })
+  }
+  for (const t of state?.tasks ?? []) {
+    out.push({ tag: t.id, data: payloadOf('task', t) })
+  }
+  for (const it of state?.items ?? []) {
+    /* 물품의 태그는 epc(개체 식별자) — 노드·무버와 달리 id 가 아니다. */
+    if (it?.epc) out.push({ tag: it.epc, data: payloadOf('item', it) })
+  }
+
+  /* ── 집약 뷰 ──────────────────────────────────────────────────────────────
+   * 런타임에 생기고 사라지는 엔티티(오더·작업·물품)는 보드에 개별 배치할 수 없다 → 한 컴포넌트가
+   * 전체를 추적하는 집약 태그를 항상 방출한다. */
+  const orders = state?.orders ?? []
+  out.push({ tag: ordersTag(instanceId), data: { entity: 'orders', orders: orders.map((o: any) => aggregateItem(o, 'id')) } })
+
+  const tasks = state?.tasks ?? []
+  out.push({ tag: tasksTag(instanceId), data: { entity: 'tasks', tasks: tasks.map((t: any) => aggregateItem(t, 'id')) } })
+
+  /* 사람 집약 — 인원은 보드에 개별 배치할 수도 있지만(설비처럼), 전체를 한눈에 보는 소비처도 있다.
+   * 인원을 선언하지 않은 트윈에서는 빈 배열이 나간다(없음과 모름을 구별). */
+  const persons = state?.persons ?? []
+  out.push({ tag: personsTag(instanceId), data: { entity: 'persons', persons: persons.map((p: any) => aggregateItem(p, 'id')) } })
+
+  const assets = state?.assets ?? []
+  out.push({ tag: assetsTag(instanceId), data: { entity: 'assets', assets: assets.map((a: any) => aggregateItem(a, 'id')) } })
+
+  const items = state?.items ?? []
+  const shown = items.slice(0, ITEMS_AGGREGATE_LIMIT)
+  out.push({
+    tag: itemsTag(instanceId),
+    data: {
+      entity: 'items',
+      items: shown.map((it: any) => aggregateItem(it, 'epc')),
+      total: items.length,
+      /* 잘렸으면 그 사실을 말한다 — "이게 전부" 로 읽히면 재고를 과소 판단한다. */
+      ...(items.length > shown.length ? { truncated: items.length - shown.length } : {})
+    }
+  })
+
+  /*
+   * ── 에너지 (EMS) ─────────────────────────────────────────────────────────
+   *
+   * 계측은 `state.energy` 에 산다 — 자원 축(`equipment`·`locations`)이 아니다. 그래서 이 매핑이 없으면
+   * 보드에 놓은 계량기가 **아무 값도 받지 못한다**(컴포넌트는 있는데 영원히 빈 모습).
+   *
+   * 두 갈래로 낸다:
+   *  · **개체별** — 계량 지점 하나하나의 마지막 관측(kW·kWh·역률·시각). 태그는 그 설비 id 다.
+   *  · **집약** — 수요 구간·피크·계약전력. 이것은 트윈 하나의 사실이라 개체에 실을 수 없다.
+   *
+   * 값이 없으면 **키를 넣지 않는다**(0 으로 만들지 않는다) — 「못 읽었다」와 「0 이었다」는 다른 사실이고,
+   * 그 구별이 이 트윈의 값어치다.
+   */
+  const energy = state?.energy
+  if (energy) {
+    for (const pt of energy.points ?? []) {
+      if (!pt?.id) continue
+      out.push({
+        tag: pt.id,
+        data: {
+          entity: 'meter',
+          ...(pt.kW !== undefined ? { kW: pt.kW } : {}),
+          ...(pt.kWh !== undefined ? { kWh: pt.kWh } : {}),
+          ...(pt.powerFactor !== undefined ? { powerFactor: pt.powerFactor } : {}),
+          /* 마지막 표본 시각 — 계측이 끊긴 것을 화면이 스스로 알 수 있게(우리가 판정하지 않는다). */
+          ...(pt.atMs !== undefined ? { measuredAt: new Date(pt.atMs).toISOString() } : {}),
+          samplesInWindow: pt.samplesInWindow ?? 0
+        }
+      })
+    }
+    out.push({
+      tag: energyTag(instanceId),
+      data: {
+        entity: 'energy',
+        ...(energy.contractKW !== undefined ? { contractKW: energy.contractKW } : {}),
+        ...(energy.open ? { open: energy.open } : {}),
+        ...(energy.peakSince ? { peakSince: energy.peakSince } : {}),
+        /* 마감된 구간은 **최근 것만** 낸다 — 하루치를 매 방송에 실으면 채널이 그것으로 찬다.
+           전체 수는 함께 낸다(조용히 자르지 않는다). */
+        recent: (energy.closed ?? []).slice(-8),
+        closedTotal: energy.closedTotal ?? 0
+      }
+    })
+  }
+
+  return out
+}

package/shared/kpi-broadcast.ts

@@ -0,0 +1,13 @@
+/*
+ * 구간 성과 카드의 **대상 식별자**.
+ *
+ * 예전에는 이 파일이 방송 payload 도 만들었다(`shapeKpiBroadcast`). 2026-08-06 에 방송을 없애고 카드가
+ * `twinKpi` 를 직접 묻게 바꿔서, 남은 것은 팔레트가 대상을 가리킬 때 쓰는 식별자뿐이다.
+ * 왜 바꿨는지는 `twin-engine.ts` 의 주석과 `operato-twin/client/scene/twin-kpi-source.ts` 에 있다.
+ */
+export const KPI_TAG_PREFIX = '__kpi__'
+
+/** 이 트윈의 구간 성과 태그. */
+export const kpiTag = (instanceId: string) => `${KPI_TAG_PREFIX}:${instanceId}`
+
+/** 표식은 `entity` 로 — `kind` 는 도메인의 낱말이라 표식이 훔치지 않는다(`entity-delta.ts` 와 같은 규약). */

package/shared/twin-level.ts

@@ -0,0 +1,48 @@
+/*
+ * 공간 계층의 **단계** — 성과를 어느 단위로 보는가. 순수(import 없음).
+ *
+ * ── 왜 여기 있나 ───────────────────────────────────────────────────────────
+ * 이 목록을 세 곳이 쓴다: 씬 표현이 "나는 어느 단계에 붙는다" 고 선언할 때(클라이언트), 성과 카드가
+ * "이 단계로 나눠 달라" 고 물을 때(클라이언트), AI 가 "구역별로 보여 줘" 를 제안할 때(서버).
+ * 세 곳이 각자 목록을 적으면 하나가 늘 때 나머지가 조용히 뒤처진다 — 집약 태그에서 이미 겪었다.
+ *
+ * 그래서 **한 곳**에 두고 셋이 가져다 쓴다. 이 파일은 import 가 없어 클라이언트 번들에 서버 코드를
+ * 끌고 들어가지 않는다.
+ */
+
+/**
+ * 성과를 접을 수 있는 단계 — 좁은 것부터.
+ *
+ * `equipment` 는 커널 축 이름으로 `resource` 다(설비·인원·자산을 아우르는 이름). 화면과 AI 는
+ * "설비" 로 말하고, 커널에 물을 때만 축 이름으로 바꾼다 — 그 변환이 아래 한 곳에 있다.
+ */
+export const TWIN_LEVELS = ['space', 'twin', 'area', 'location', 'equipment'] as const
+export type TwinLevel = (typeof TWIN_LEVELS)[number]
+
+export function isTwinLevel(v: unknown): v is TwinLevel {
+  return typeof v === 'string' && (TWIN_LEVELS as readonly string[]).includes(v)
+}
+
+/**
+ * 단계 → 커널의 나누는 축(`KpiGroupBy`). **전체를 보는 단계는 축이 없다** — 나누지 않고 통째로 접는다.
+ *
+ * `space` 와 `twin` 이 축 없이 같은 이유: 둘의 차이는 "무엇을 대상으로 삼는가"(공간 전체 대 트윈 하나)이지
+ * "어떻게 나누는가" 가 아니다. 대상은 질의의 `spaceId`/`instanceId` 가 정한다.
+ */
+export function kpiGroupByOfLevel(level: TwinLevel): 'area' | 'location' | 'resource' | undefined {
+  if (level === 'area') return 'area'
+  if (level === 'location') return 'location'
+  if (level === 'equipment') return 'resource'
+
+  return undefined
+}
+
+/**
+ * 그 단계의 카드가 **대상 하나마다 한 장**인가.
+ *
+ * 구역·자리·설비는 여럿이라 카드가 그 수만큼 생긴다. 공간·트윈은 하나뿐이다. 보드를 자동으로 조립할 때
+ * 몇 장이 생길지 미리 알아야 한다 — 자리 200개 × 지표 4개면 800장이다.
+ */
+export function isPerTargetLevel(level: TwinLevel): boolean {
+  return kpiGroupByOfLevel(level) !== undefined
+}

package/test/adopt-structure-live.test.ts

@@ -0,0 +1,133 @@
+/*
+ * ★ 돌고 있는 미러에 새 구조를 넣는다 — **미러는 멈출 수 없다.**
+ *
+ * 미러가 비추는 현실은 24시간 돈다. 설비 한 대가 늘었다고 트윈을 멈췄다 세우면 그 사이의
+ * 사실을 잃고, 라이브에서 유실은 곧 거짓이다. 그래서 미러는 **돌면서** 갈아탄다.
+ *
+ * 갈아타기가 옳으려면 **세 층이 함께** 움직여야 한다. 하나라도 빠지면 조용히 어긋난다:
+ *  ① 리비전 — 이후의 이벤트가 새 번호를 달고 다닌다(재생이 마디를 나눌 수 있게)
+ *  ② 저장 model·구조 행 — 조회가 새 구조를 본다
+ *  ③ 커널 — 지금 접히는 이벤트가 새 구조 위에서 접힌다
+ *
+ * 커널 단위 거동(무엇을 지키고 무엇을 버리나)은 커널 쪽 `adopt-structure.test.ts` 가 지킨다.
+ * 여기서 지키는 것은 **호스트 배선** — 세 층이 같은 인제스트에서 함께 움직이는가.
+ *
+ * 실 DataSource 로 돈다. 부분 적용은 정의상 "여러 표에 걸쳐 무엇이 남았나" 이므로.
+ */
+import { test, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { createRequire } from 'node:module'
+import type { DataSource } from 'typeorm'
+
+const req = createRequire(import.meta.url)
+const { NamingStrategy, addDataSource, entities: shellEntities, Domain } = req('@things-factory/shell')
+const { entities: authEntities } = req('@things-factory/auth-base')
+const { entities: twinEntities } = req('../dist-server/service/index.js')
+const { TwinEngine } = req('../dist-server/engine/index.js')
+const { TwinInstance } = req('../dist-server/service/twin-instance/twin-instance.js')
+const { TwinStructure } = req('../dist-server/service/twin-structure/twin-structure.js')
+const { TwinLocation } = req('../dist-server/service/twin-model/twin-location.js')
+const { TwinEquipment } = req('../dist-server/service/twin-model/twin-equipment.js')
+const { DataSource: TypeOrmDataSource } = req('typeorm')
+
+let ds: DataSource
+let domainId: string
+
+const MIRROR = 'mirror-probe'
+const SIM = 'sim-probe'
+
+const master = (source: string, bins: number, forklifts: number): any => ({
+  source,
+  system: 'wms',
+  siteName: '미러 창고',
+  space: { width: 60, depth: 30, unit: 'm' },
+  locations: [
+    { id: 'dock-recv', type: 'dock', role: 'location', name: '입고 도크', capacity: 100 },
+    ...Array.from({ length: bins }, (_, i) => ({ id: `bin-${i + 1}`, type: 'storage', role: 'location', name: `빈${i + 1}`, capacity: 20 }))
+  ],
+  equipment: Array.from({ length: forklifts }, (_, i) => ({ id: `fk-${i + 1}`, kind: 'forklift', homeLocationId: 'dock-recv' }))
+})
+
+before(async () => {
+  ds = new TypeOrmDataSource({
+    type: 'sqlite',
+    database: ':memory:',
+    synchronize: true,
+    dropSchema: true,
+    namingStrategy: new NamingStrategy(),
+    entities: [...shellEntities, ...authEntities, ...twinEntities],
+    logging: false
+  })
+  await ds.initialize()
+  addDataSource('default', ds)
+  const d = await ds.getRepository(Domain).save({ name: 'adopt-test', subdomain: 'adopt-test' } as any)
+  domainId = d.id
+
+  await TwinEngine.ingestMaster(domainId, master(MIRROR, 3, 2))
+  await TwinEngine.ingestMaster(domainId, master(SIM, 3, 2))
+})
+
+after(async () => {
+  for (const id of [MIRROR, SIM]) await TwinEngine.stop(domainId, id).catch(() => {})
+  await ds?.destroy()
+})
+
+test('돌고 있는 미러는 멈추지 않고 갈아탄다 — 세 층이 함께 움직인다', async () => {
+  /* 미러 기동은 선언 기반 부팅이 가른다 — `startFromRegistry` 는 시뮬 경로다(같은 함수가 아니다). */
+  const rt = await TwinEngine.bootDeclared(domainId, MIRROR, 'mirror')
+  assert.equal(rt.mode, 'live', '미러로 떠야 이 검사가 뜻이 있다')
+
+  const res = await TwinEngine.ingestMaster(domainId, master(MIRROR, 7, 2))
+
+  /* ① 리비전 — 이후 이벤트가 달고 다닐 번호가 올라간다 */
+  const revs = await ds.getRepository(TwinStructure).find({ where: { instanceId: MIRROR }, order: { rev: 'ASC' } })
+  assert.deepEqual(revs.map((r: any) => r.rev), [1, 2], '구조가 달라졌으니 새 리비전이 남는다')
+
+  /* ② 저장 model·구조 행 — 조회가 새 구조를 본다 */
+  const inst = await ds.getRepository(TwinInstance).findOne({ where: { instanceId: MIRROR } })
+  assert.equal(inst.model.locations.length, 8, '저장 model 가 새 구조다(도크 1 + 빈 7)')
+  assert.equal(await ds.getRepository(TwinLocation).countBy({ instance: { id: inst.id } } as any), 8, '구조 행도 함께 다시 그려진다')
+
+  /* ③ 커널 — 멈추지 않은 채로 새 구조를 들고 있다 */
+  assert.equal(TwinEngine.instances[`${domainId}:${MIRROR}`]?.mode, 'live', '갈아타기가 미러를 멈추지 않는다')
+  const snap = TwinEngine.snapshot(domainId, MIRROR)
+  assert.equal(snap.locations.filter((n: any) => n.type === 'storage').length, 7, '커널도 새 자리를 들고 있다')
+
+  /* 무엇이 달라졌는지 **말한다** — 멈췄다 세우는 마디가 없으므로 말하지 않으면 조용히 지나간다 */
+  const adopted = res.warnings.find((w: any) => w.code === 'structure-adopted')
+  assert.ok(adopted, '갈아타기는 말없이 성공하지 않는다')
+  assert.equal(adopted.params.locationsAdded, 4, '자리 4개가 늘었다(빈 3→7)')
+  assert.equal(adopted.params.rev, 2)
+})
+
+test('사라진 설비를 수로 알린다 — 자리가 수천인 현장에서 직접 세어 보게 하지 않는다', async () => {
+  const res = await TwinEngine.ingestMaster(domainId, master(MIRROR, 7, 1)) // 지게차 2 → 1
+  const adopted = res.warnings.find((w: any) => w.code === 'structure-adopted')
+  assert.equal(adopted.params.equipmentDropped, 1)
+
+  const inst = await ds.getRepository(TwinInstance).findOne({ where: { instanceId: MIRROR } })
+  assert.equal(await ds.getRepository(TwinEquipment).countBy({ instance: { id: inst.id } } as any), 1, '표에서도 사라진다')
+  assert.equal(TwinEngine.snapshot(domainId, MIRROR).equipment.length, 1, '커널에서도 사라진다')
+})
+
+test('돌고 있는 시뮬레이션은 여전히 거절한다 — 조건이 바뀐 실험은 다른 실험이다', async () => {
+  await TwinEngine.bootDeclared(domainId, SIM, 'sim-experiment')
+  const before = (await ds.getRepository(TwinStructure).find({ where: { instanceId: SIM } })).length
+
+  await assert.rejects(() => TwinEngine.ingestMaster(domainId, master(SIM, 9, 2)), /is running/)
+
+  assert.equal(
+    (await ds.getRepository(TwinStructure).find({ where: { instanceId: SIM } })).length,
+    before,
+    '거절된 인제스트는 흔적을 남기지 않는다'
+  )
+})
+
+test('멈춘 미러는 구조를 전환하지 않는다 — 정지한 대상을 전환하려 하지 않는다', async () => {
+  await TwinEngine.stop(domainId, MIRROR)
+  await assert.rejects(
+    () => TwinEngine.adoptStructure(domainId, MIRROR, { locations: [], equipment: [] } as any),
+    /is not running/,
+    '멈춘 트윈은 프로비저닝으로 세우는 것이지 갈아타는 것이 아니다'
+  )
+})