@things-factory/headless-twin 10.0.9 → 10.0.11

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

@@ -7,29 +7,64 @@ import { TwinSpaceRepresentation } from './twin-space-representation.js'
 import { TwinSpaceArea } from './twin-space-area.js'
 import { TwinArea } from './twin-area.js'
 import { TwinInstance } from '../twin-instance/twin-instance.js'
+import { TwinAuditEvent } from '../twin-audit/twin-audit-event.js'
+import { TwinEngine } from '../../engine/index.js'
+import { judgeMoveTwinSpace, judgeDetachTwinSpace } from './move-space.js'
+import { checkSpaceIntegrity, sortFindings, type IntegrityPolygon } from './space-integrity.js'
 
 /*
  * 공간 구성 채널(design/ui/space-composition.md) — Site(Space) + 복수 표현(Representation) + 영역(Area).
- * board 내용은 board-service Board 에(표현 config.boardId 참조, 중복 저장 금지). 모두 domain 스코프.
+ * model 내용은 board-service Board 에(표현 config.boardId 참조, 중복 저장 금지). 모두 domain 스코프.
  */
 @Resolver()
 export class TwinSpaceResolver {
   /* ── Space(Site) ────────────────────────────────────────────────── */
+  /**
+   * 이 테넌트의 현장 목록.
+   *
+   * ── 세 번만 묻는다 (2026-08-13) ──────────────────────────────────────────
+   * 예전에는 현장마다 표현 수를 세고 인스턴스를 조회했다 — 현장 13곳이면 **질의 27번**이고, 첫
+   * 호출이 2.4초였다(헤더가 뜰 때마다 이 목록을 읽는다). 규모가 커지면 그대로 자란다.
+   *
+   * 이제 세 번 묻고 메모리에서 맞춘다: 현장 · 표현(공간 id 만) · 인스턴스(필요한 컬럼만).
+   * 표현은 **id 만 실어 온다**(`loadRelationIds`) — 설정 blob 을 읽어 세는 것은 낭비다.
+   */
   @Query(returns => [ScalarObject], { description: 'List tenant Spaces (Sites) in the current domain.' })
   async twinSpaces(@Ctx() context: ResolverContext): Promise<any[]> {
     const domainId = context.state.domain.id
-    const rows = await getRepository(TwinSpace).find({ where: { domain: { id: domainId } }, order: { createdAt: 'ASC' } })
-    const out: any[] = []
-    for (const r of rows) {
-      const representationCount = await getRepository(TwinSpaceRepresentation).count({ where: { domain: { id: domainId } as any, space: { id: r.id } as any } })
-      // 벤치 여부·원본 참조 — 인스턴스 purpose 근거(1급). 사본 공간을 헤더 선택기에서 구별·선택 가능하게.
-      const insts = await getRepository(TwinInstance).find({ where: { domain: { id: domainId } as any, spaceId: r.spaceId } })
-      const benchInst = insts.find(i => (i as any).purpose === 'bench')
-      const bench = !!benchInst
-      const copyOf = benchInst?.copyOf
-      out.push({ spaceId: r.spaceId, name: r.name, description: r.description, geo: r.geo, timezone: r.timezone, primaryRepresentationId: r.primaryRepresentationId, content: r.content, representationCount, bench, copyOf })
+    const [rows, reps, insts] = await Promise.all([
+      getRepository(TwinSpace).find({ where: { domain: { id: domainId } }, order: { createdAt: 'ASC' } }),
+      /* 관계를 **조인해서** 읽는다 — `loadRelationIds`+`select` 조합은 관계 자리를 비워 두어
+         표현 수가 전부 0 이 됐다(2026-08-13 실측으로 잡음). 조인 한 번이 현장마다 세는 것보다 싸다. */
+      getRepository(TwinSpaceRepresentation).find({ where: { domain: { id: domainId } }, relations: { space: true } }),
+      getRepository(TwinInstance).find({ where: { domain: { id: domainId } }, select: { instanceId: true, spaceId: true, purpose: true, copyOf: true } })
+    ])
+
+    const repCount = new Map<string, number>()
+    for (const rep of reps) {
+      const sid = rep.space?.id
+      if (sid) repCount.set(sid, (repCount.get(sid) ?? 0) + 1)
     }
-    return out
+    /* 벤치 여부·원본 참조 — 인스턴스 purpose 근거(1급). 사본 현장을 헤더 선택기에서 구별·선택 가능하게. */
+    const benchOf = new Map<string, { copyOf?: string }>()
+    for (const i of insts) if ((i as any).purpose === 'bench' && i.spaceId && !benchOf.has(i.spaceId)) benchOf.set(i.spaceId, { copyOf: i.copyOf ?? undefined })
+
+    return rows.map(r => {
+      const bench = benchOf.get(r.spaceId)
+      return {
+        spaceId: r.spaceId,
+        name: r.name,
+        description: r.description,
+        geo: r.geo,
+        timezone: r.timezone,
+        primaryRepresentationId: r.primaryRepresentationId,
+        extentX: r.extentX,
+        extentY: r.extentY,
+        representationCount: repCount.get(r.id) ?? 0,
+        bench: !!bench,
+        copyOf: bench?.copyOf
+      }
+    })
   }
 
   /** 단건 — 표현(+영역) 트리 포함. */
@@ -44,7 +79,7 @@ export class TwinSpaceResolver {
       const areas = await getRepository(TwinSpaceArea).find({ where: { domain: { id: domainId }, representation: { id: rep.id } }, order: { createdAt: 'ASC' } })
       representations.push({ id: rep.id, type: rep.type, name: rep.name, seq: rep.seq, isPrimary: rep.isPrimary, config: rep.config, areas: areas.map(a => ({ id: a.id, name: a.name, type: a.type, geometry: a.geometry, drillTo: a.drillTo, binding: a.binding, style: a.style })) })
     }
-    return { spaceId: r.spaceId, name: r.name, description: r.description, geo: r.geo, timezone: r.timezone, primaryRepresentationId: r.primaryRepresentationId, content: r.content, representations }
+    return { spaceId: r.spaceId, name: r.name, description: r.description, geo: r.geo, timezone: r.timezone, primaryRepresentationId: r.primaryRepresentationId, extentX: r.extentX, extentY: r.extentY, representations }
   }
 
   @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
@@ -63,17 +98,34 @@ export class TwinSpaceResolver {
     return true
   }
 
+  /**
+   * 공간 삭제 — **이 공간의 트윈이 있으면 거절한다.** 그래서 트윈이 현장을 잃는 일은 없다.
+   *
+   * ── 왜 모양을 바꿨나 (2026-08-13) ────────────────────────────────────────
+   * 예전에는 `Boolean` 을 돌려주고 거절은 **한국어 문장을 던졌다.** 두 가지가 틀렸다:
+   *  ① 서버가 화면의 말을 정했다 — 일본어·스페인어 사용자에게 한국어가 새어 나간다.
+   *  ② 던진 예외를 화면이 받지 않아 **아무 일도 없는 것처럼** 보였다. 사용자는 삭제를 눌렀고
+   *     화면은 그대로였다. 거절을 조용히 하는 것은 실패보다 나쁘다.
+   * 이제 `{ok, errorCode, errorParams}` 로 낸다 — 화면이 `twin.compose.del.<code>` 로 말을 만든다.
+   */
   @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
-  @Mutation(returns => Boolean, { description: 'Delete a Space and its representations/areas.' })
-  async deleteTwinSpace(@Arg('spaceId') spaceId: string, @Ctx() context: ResolverContext): Promise<boolean> {
+  @Mutation(returns => ScalarObject, {
+    description:
+      'Delete a Space and its representations/areas. Refused while twins still live in it (a twin never loses its site this way). Returns {ok, errorCode, errorParams}.'
+  })
+  async deleteTwinSpace(@Arg('spaceId') spaceId: string, @Ctx() context: ResolverContext): Promise<any> {
     const domainId = context.state.domain.id
     // 라이프사이클 가드 — 이 공간에 바인딩된 트윈 인스턴스가 있으면 삭제 차단(dangling 방지).
     // spaceId 컬럼(space #3) 로 직접 질의 — 전 인스턴스 로드+JS필터 제거(효율·1급 질의).
     const bound = await getRepository(TwinInstance).find({ where: { domain: { id: domainId }, spaceId } })
     if (bound.length) {
-      throw new Error(
-        `공간 "${spaceId}" 에 트윈 인스턴스 ${bound.length}개가 바인딩돼 있어 삭제할 수 없습니다. 먼저 트윈을 제거하세요 (${bound.map(i => i.instanceId).join(', ')}).`
-      )
+      const twins = bound.map(i => i.name || i.instanceId)
+      return {
+        ok: false,
+        errorCode: 'space-has-twins',
+        errorParams: { spaceId, count: bound.length, twins: twins.slice(0, 5).join(', ') },
+        error: `space "${spaceId}" still has ${bound.length} twin(s) — remove or move them first (${twins.join(', ')})`
+      }
     }
     const space = await getRepository(TwinSpace).findOne({ where: { domain: { id: domainId }, spaceId } })
     if (space) {
@@ -83,7 +135,289 @@ export class TwinSpaceResolver {
       await getRepository(TwinArea).delete({ domain: { id: domainId } as any, space: { id: space.id } as any }) // 논리 area 도 함께 정리
     }
     await getRepository(TwinSpace).delete({ domain: { id: domainId } as any, spaceId })
-    return true
+    return { ok: true }
+  }
+
+  /**
+   * 이미 있는 트윈을 이 현장으로 가져온다 — **소속 갱신**(이력 이전이 아니다).
+   *
+   * 저널·투영 행은 `instanceId` 로 매여 있어 트윈을 따라오고, 구역·표현은 공간의 것이라 남는다
+   * (근거·판정: `move-space.ts`). 그래서 이 뮤테이션이 쓰는 것은 두 곳뿐이다 —
+   * 레지스트리의 `spaceId` 와 저장된 model 의 `spaceId`(커널·보드가 같은 공간을 가리켜야 한다).
+   * 새 공간의 시간대로 `utcOffsetMinutes` 도 다시 파생한다(공간이 시간의 기준이다).
+   *
+   * `dryRun` 은 **같은 판정을 미리** 보여 준다 — 화면이 잃을 것을 먼저 말하고 사용자가 정한다.
+   * 판정을 두 벌로 두면 미리보기와 실제가 어긋나므로 한 함수를 두 번 부른다.
+   */
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
+  @Mutation(returns => ScalarObject, {
+    description:
+      'Move an existing twin into a space (co-locate it as another lens). The journal and projected rows follow the twin; areas and representations stay with the old space. dryRun returns the same judgement without writing. Returns {ok, warnings, errorCode}.'
+  })
+  async moveTwinToSpace(
+    @Arg('instanceId') instanceId: string,
+    @Arg('spaceId') spaceId: string,
+    @Ctx() context: ResolverContext,
+    @Arg('dryRun', { nullable: true, description: 'Judge only — report refusal/warnings without moving.' }) dryRun?: boolean
+  ): Promise<any> {
+    const domainId = context.state.domain.id
+    const instRepo = getRepository(TwinInstance)
+    const spaceRepo = getRepository(TwinSpace)
+
+    const inst = await instRepo.findOne({ where: { domain: { id: domainId }, instanceId } })
+    const from = inst?.spaceId ? await spaceRepo.findOne({ where: { domain: { id: domainId }, spaceId: inst.spaceId } }) : null
+    const to = await spaceRepo.findOne({ where: { domain: { id: domainId }, spaceId } })
+
+    /* 판정에 필요한 사실만 모아 넘긴다 — 판정 자체는 순수 모듈이 한다. */
+    const toAreaIds = to
+      ? (await getRepository(TwinArea).find({ where: { domain: { id: domainId } as any, space: { id: to.id } as any } })).map(a => a.areaId)
+      : []
+    const fromRepresentationCount = from
+      ? await getRepository(TwinSpaceRepresentation).count({ where: { domain: { id: domainId } as any, space: { id: from.id } as any } })
+      : 0
+    const model: any = inst?.model ?? {}
+    const areaRefs: (string | undefined)[] = (model.locations ?? []).map((l: any) => l?.parentId)
+
+    const judgement = judgeMoveTwinSpace({
+      instanceId: inst?.instanceId,
+      fromSpaceId: inst?.spaceId,
+      toSpaceId: spaceId,
+      toSpaceExists: !!to,
+      purpose: (inst as any)?.purpose,
+      running: !!inst && !!TwinEngine.runtime(domainId, instanceId),
+      fromTimezone: from?.timezone ?? undefined,
+      toTimezone: to?.timezone ?? undefined,
+      areaRefs,
+      toAreaIds,
+      fromRepresentationCount
+    })
+    if (judgement.refusal) {
+      const r = judgement.refusal
+      return { ok: false, error: r.message, errorCode: r.code, errorParams: r.params, warnings: [] }
+    }
+    if (dryRun) return { ok: true, dryRun: true, warnings: judgement.warnings }
+
+    /* 두 곳을 함께 쓴다 — 레지스트리와 model 이 다른 공간을 가리키면 보드·커널이 갈라진다. */
+    const moved = { ...model, spaceId }
+    const withTime = await TwinEngine.withSpaceTimeBase(moved, domainId, spaceId)
+    await instRepo.save(instRepo.create({ ...(inst as any), spaceId, model: withTime }))
+
+    /*
+     * 감사 기록 — 소속을 바꾼 것은 사람의 결정이고, 나중에 "왜 이 트윈이 저 현장에 있나" 를 묻게 된다.
+     * 기록이 실패해도 이전 결과는 돌려준다(감사가 본업을 막지 않는다). 다만 삼키지 않고 로그에 남긴다.
+     */
+    try {
+      const repo = getRepository(TwinAuditEvent)
+      await repo.save(
+        repo.create({
+          domain: context.state.domain,
+          instanceId,
+          commandType: 'twin.moveToSpace',
+          accepted: true,
+          origin: 'user',
+          actorId: context.state.user?.id,
+          args: { from: inst?.spaceId ?? null, to: spaceId, warnings: judgement.warnings.map(w => w.code) }
+        } as any)
+      )
+    } catch (err) {
+      console.error(`[twin-space] move audit not recorded for "${instanceId}"`, err)
+    }
+
+    return { ok: true, warnings: judgement.warnings }
+  }
+
+  /**
+   * 트윈을 현장에서 뗀다 — **어느 현장에도 속하지 않음**으로 되돌린다.
+   *
+   * 더하기·옮기기만 있으면 잘못 넣은 것을 되돌릴 수 없다. 떼도 저널·로케이션·설비는 트윈에 남고
+   * (`instanceId` 로 매여 있다), 구역·표현은 옛 현장에 남는다. 잃는 것은 **볼 무대**다 —
+   * 판정이 그것을 말한다(`judgeDetachTwinSpace`). `dryRun` 은 같은 판정을 미리 낸다.
+   */
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
+  @Mutation(returns => ScalarObject, {
+    description:
+      'Detach a twin from its space (it ends up on no site). The journal and projected rows stay with the twin; areas and representations stay with the space. dryRun returns the same judgement without writing. Returns {ok, warnings, errorCode}.'
+  })
+  async detachTwinFromSpace(
+    @Arg('instanceId') instanceId: string,
+    @Ctx() context: ResolverContext,
+    @Arg('dryRun', { nullable: true, description: 'Judge only — report refusal/warnings without detaching.' }) dryRun?: boolean
+  ): Promise<any> {
+    const domainId = context.state.domain.id
+    const instRepo = getRepository(TwinInstance)
+    const inst = await instRepo.findOne({ where: { domain: { id: domainId }, instanceId } })
+    const from = inst?.spaceId
+      ? await getRepository(TwinSpace).findOne({ where: { domain: { id: domainId }, spaceId: inst.spaceId } })
+      : null
+    const fromRepresentationCount = from
+      ? await getRepository(TwinSpaceRepresentation).count({ where: { domain: { id: domainId } as any, space: { id: from.id } as any } })
+      : 0
+
+    const judgement = judgeDetachTwinSpace({
+      instanceId: inst?.instanceId,
+      fromSpaceId: inst?.spaceId,
+      purpose: (inst as any)?.purpose,
+      fromRepresentationCount,
+      fromTimezone: from?.timezone ?? undefined
+    })
+    if (judgement.refusal) {
+      const r = judgement.refusal
+      return { ok: false, error: r.message, errorCode: r.code, errorParams: r.params, warnings: [] }
+    }
+    if (dryRun) return { ok: true, dryRun: true, warnings: judgement.warnings }
+
+    /* 두 곳을 함께 비운다 — 레지스트리와 model 이 어긋나면 어느 쪽이 사실인지 알 수 없다.
+       시간 기준(utcOffsetMinutes)은 **남긴다**: 지우면 조용히 UTC 로 읽힌다(판정이 그렇게 말했다). */
+    const { spaceId: _dropped, ...model } = (inst?.model as any) ?? {}
+    await instRepo.update({ id: (inst as any).id }, { spaceId: null as any, model })
+
+    try {
+      const repo = getRepository(TwinAuditEvent)
+      await repo.save(
+        repo.create({
+          domain: context.state.domain,
+          instanceId,
+          commandType: 'twin.detachFromSpace',
+          accepted: true,
+          origin: 'user',
+          actorId: context.state.user?.id,
+          args: { from: inst?.spaceId ?? null, warnings: judgement.warnings.map(w => w.code) }
+        } as any)
+      )
+    } catch (err) {
+      console.error(`[twin-space] detach audit not recorded for "${instanceId}"`, err)
+    }
+
+    return { ok: true, warnings: judgement.warnings }
+  }
+
+  /**
+   * 공간 ↔ 트윈 ↔ 가시화 정합성 점검 — **사실을 모아 순수 판정에 넘긴다.**
+   *
+   * 세 축은 서로를 id 로만 가리키고 DB 가 그 참조를 지켜 주지 않는다. 트윈을 옮기거나 떼거나 원본을
+   * 다시 읽으면 아무 오류 없이 **가리킬 것이 없는 도형**과 **소속 없는 로케이션**이 남는다. 사람이
+   * 눈으로 대조하던 일을 기계가 한다(판정·근거: `space-integrity.ts`).
+   *
+   * `spaceId` 를 주면 그 현장만, 없으면 테넌트 전체를 본다.
+   */
+  @Query(returns => [ScalarObject], {
+    description:
+      'Check space ↔ twin ↔ visualization integrity: dangling site refs, registry/model mismatch, polygons binding areas or entities that are not there, primary representation, unbound board representations. Pass spaceId to check one site.'
+  })
+  async twinSpaceIntegrity(
+    @Ctx() context: ResolverContext,
+    @Arg('spaceId', { nullable: true }) spaceId?: string
+  ): Promise<any[]> {
+    const domainId = context.state.domain.id
+    const spaceRows = await getRepository(TwinSpace).find({ where: { domain: { id: domainId } } })
+    const instRows = await getRepository(TwinInstance).find({ where: { domain: { id: domainId } } })
+    const repRows = await getRepository(TwinSpaceRepresentation).find({ where: { domain: { id: domainId } }, relations: ['space'] })
+    const areaRows = await getRepository(TwinArea).find({ where: { domain: { id: domainId } }, relations: ['space'] })
+    const polyRows = await getRepository(TwinSpaceArea).find({ where: { domain: { id: domainId } }, relations: ['representation'] })
+
+    const areasBySpace: Record<string, string[]> = {}
+    for (const a of areaRows) {
+      const sid = (a as any).space?.spaceId
+      if (!sid) continue
+      ;(areasBySpace[sid] ??= []).push(a.areaId)
+    }
+
+    /*
+     * 폴리곤 바인딩의 실제 모양은 `{ groupId?, locationId?, locationIds? }` 다(지도 저작기 기준).
+     * 여러 로케이션을 묶은 도형은 **각각을 따로** 본다 — 하나만 끊겨도 그 도형은 반쯤 거짓이 된다.
+     */
+    const polysByRep: Record<string, IntegrityPolygon[]> = {}
+    for (const p of polyRows) {
+      const rid = (p as any).representation?.id
+      if (!rid) continue
+      const b: any = p.binding ?? {}
+      const list = polysByRep[rid] ??= []
+      if (b.groupId) list.push({ id: p.id, groupId: b.groupId })
+      const targets: string[] = [...(b.locationId ? [b.locationId] : []), ...(Array.isArray(b.locationIds) ? b.locationIds : [])]
+      for (const t of targets) list.push({ id: p.id, targetKind: 'location', targetId: t })
+    }
+
+    /* 보드 id 는 표현 config 가 들고 있다 — 존재 확인은 보드 서비스의 일이므로, 여기서는 표현이
+       가리키는 값이 있는지만 본다(없는 보드까지 보려면 board-service 를 물어야 한다: 아래 주석). */
+    const boardIds = repRows.map(r => (r.config as any)?.boardId).filter(Boolean) as string[]
+
+    const findings = checkSpaceIntegrity({
+      spaces: spaceRows.map(s => ({ spaceId: s.spaceId, primaryRepresentationId: s.primaryRepresentationId })),
+      instances: instRows.map(i => {
+        const model: any = i.model ?? {}
+        /*
+         * 어휘가 맞는지는 **실행 중인 트윈만** 답할 수 있다 — 커널이 무엇을 버렸는지는 런타임의 사실이다.
+         * 정지한 트윈은 `undefined`(모른다)로 둔다. 저널을 다시 접어 알아내지는 않는다: 이 질의는
+         * 테넌트 전체를 훑으므로 트윈마다 폴드를 걸면 정합성 점검이 가장 무거운 질의가 된다.
+         */
+        const live: any = TwinEngine.isRunning(domainId, i.instanceId)
+          ? TwinEngine.snapshot(domainId, i.instanceId)
+          : undefined
+        return {
+          instanceId: i.instanceId,
+          spaceId: i.spaceId,
+          modelSpaceId: model.spaceId,
+          purpose: (i as any).purpose,
+          locationIds: (model.locations ?? []).map((l: any) => l?.id).filter(Boolean),
+          equipmentIds: (model.equipment ?? []).map((e: any) => e?.id).filter(Boolean),
+          areaRefs: (model.locations ?? []).map((l: any) => l?.parentId),
+          ...(Array.isArray(live?.unhandled) ? { unhandled: live.unhandled } : {})
+        }
+      }),
+      representations: repRows.map(r => ({
+        id: r.id,
+        spaceId: (r as any).space?.spaceId ?? '',
+        type: r.type,
+        boardId: (r.config as any)?.boardId ?? null,
+        polygons: polysByRep[r.id] ?? []
+      })),
+      areasBySpace,
+      boardIds
+    })
+
+    const scoped = spaceId ? findings.filter(f => f.spaceId === spaceId || (!f.spaceId && !spaceId)) : findings
+    return sortFindings(scoped)
+  }
+
+  /**
+   * 기계적으로 고칠 수 있는 어긋남만 고친다 — **사람의 판단이 필요한 것은 손대지 않는다.**
+   *
+   * 지금 고치는 것은 하나다: **대표 표현 포인터**. 공간이 없는 표현 id 를 가리키고 있으면, 행의
+   * `isPrimary` 가 켜진 표현(없으면 첫 표현)으로 다시 가리키고, 표현이 없으면 비운다. 근거가 있고
+   * 답이 하나뿐인 부류라 자동으로 고쳐도 사실을 바꾸지 않는다.
+   *
+   * 폴리곤이 없는 구역·개체를 가리키는 것은 **고치지 않는다.** 그 도형을 지워야 하는지, 트윈을 다시
+   * 데려와야 하는지, 구역을 다시 그려야 하는지는 사람이 정할 일이다 — 기계가 고르면 사용자가 그린
+   * 도형이 조용히 사라진다.
+   */
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
+  @Mutation(returns => ScalarObject, {
+    description:
+      'Repair mechanically fixable space integrity findings (currently: a primary representation pointer that points nowhere). Dangling polygon bindings are left alone — that is a human decision. Returns {repaired:[{spaceId, code}], skipped}.'
+  })
+  async repairTwinSpaceIntegrity(
+    @Ctx() context: ResolverContext,
+    @Arg('spaceId', { nullable: true }) spaceId?: string
+  ): Promise<any> {
+    const domainId = context.state.domain.id
+    const spaceRepo = getRepository(TwinSpace)
+    const repRepo = getRepository(TwinSpaceRepresentation)
+    const spaces = await spaceRepo.find({
+      where: spaceId ? { domain: { id: domainId }, spaceId } : { domain: { id: domainId } }
+    })
+    const repaired: any[] = []
+    for (const space of spaces) {
+      const reps = await repRepo.find({ where: { domain: { id: domainId } as any, space: { id: space.id } as any }, order: { seq: 'ASC' } })
+      const pointer = (space.primaryRepresentationId ?? '').trim()
+      if (pointer && reps.some(r => r.id === pointer)) continue /* 이미 옳다 */
+      const primary = reps.find(r => r.isPrimary) ?? reps[0]
+      const next = primary?.id ?? null
+      if (pointer === (next ?? '')) continue
+      await spaceRepo.save(spaceRepo.create({ ...space, primaryRepresentationId: next }))
+      if (primary) for (const r of reps) if (!!r.isPrimary !== (r.id === primary.id)) await repRepo.save(repRepo.create({ ...r, isPrimary: r.id === primary.id }))
+      repaired.push({ spaceId: space.spaceId, code: 'primary-representation-missing', from: pointer || null, to: next })
+    }
+    return { ok: true, repaired, count: repaired.length }
   }
 
   /* ── Area(논리 구역, 표현 무관·공유·계층) — area 단일화 space #2 ─────── */
@@ -151,7 +485,7 @@ export class TwinSpaceResolver {
 
   /* ── Representation ─────────────────────────────────────────────── */
   @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
-  @Mutation(returns => ScalarObject, { description: 'Create/update a representation (map|image|board). Returns {id}.' })
+  @Mutation(returns => ScalarObject, { description: 'Create/update a representation (map|image|model). Returns {id}.' })
   async saveSpaceRepresentation(
     @Arg('spaceId') spaceId: string,
     @Arg('rep', type => ScalarObject) rep: any,
@@ -191,7 +525,7 @@ export class TwinSpaceResolver {
 
   /* ── Area (map/image 폴리곤) ────────────────────────────────────── */
   @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
-  @Mutation(returns => ScalarObject, { description: 'Create/update a polygon area (geometry + drillTo board + binding). Returns {id}.' })
+  @Mutation(returns => ScalarObject, { description: 'Create/update a polygon area (geometry + drillTo model + binding). Returns {id}.' })
   async saveSpaceArea(
     @Arg('representationId') representationId: string,
     @Arg('area', type => ScalarObject) area: any,

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

@@ -5,8 +5,8 @@ import { Domain, ScalarObject } from '@things-factory/shell'
 
 /*
  * TwinSpace — 테넌트 1급 공간(Site) 정의(ADR-0016). 트윈보다 먼저 세우는 몰입의 무대.
- * 공간이 보이는 방식(레이아웃·배경·영역)은 정규화됨: TwinSpaceRepresentation(map|image|board —
- *   이미지 배경은 attachment-base 참조 `config.imageUrl`) + TwinSpaceArea. 인스턴스는 board.spaceId 로 바인딩.
+ * 공간이 보이는 방식(레이아웃·배경·영역)은 정규화됨: TwinSpaceRepresentation(map|image|model —
+ *   이미지 배경은 attachment-base 참조 `config.imageUrl`) + TwinSpaceArea. 인스턴스는 model.spaceId 로 바인딩.
  *  - geo = 사이트 지오레퍼런스, primaryRepresentationId = 홈/모니터 대표 표현.
  *  - content(simple-json) 는 정규화 이전 레거시 단일 blob(@deprecated, P6 제거) — 신규 저작은 representation/area 로.
  * (CLAUDE.md: 모든 @ObjectType/@Field 영문 description 필수.)
@@ -39,9 +39,30 @@ export class TwinSpace {
   description?: string
 
   @Column({ type: 'simple-json', nullable: true })
-  @Field(type => ScalarObject, { nullable: true, description: 'Site georeference { lat, lon, rotation, unit } — aligns representations.' })
+  @Field(type => ScalarObject, { nullable: true, description: 'Site georeference { lat, lon, rotation } — pins the design frame to the earth so every representation lands in the same place. `rotation` is degrees clockwise from true north (bearing convention: 0 = north, 90 = east) by which the design frame is turned.' })
   geo?: any
 
+  /*
+   * 설계 좌표계의 범위 — **미터**. `geo` 와 한 쌍이다.
+   *
+   * 구역(TwinArea.layout)은 표현 중립 설계 좌표 `{x, y, w, h}` 로 놓인다. 그 좌표가 어디까지인지를
+   * 이 둘이 정하고, `geo` 가 그것을 지구에 붙인다 — 지도로 보든 도면 이미지로 보든 보드로 보든
+   * 구역이 같은 자리에 있어야 하므로, 범위도 지오레퍼런스도 **표현이 아니라 공간**이 갖는다.
+   *
+   *   설계 좌표 (x, y) ──[extentX/extentY 로 중심 이동]──▶ 미터 오프셋 ──[geo]──▶ 위경도
+   *
+   * `width`/`depth` 라 부르지 않는 이유: 컴포넌트 속성의 `depth` 는 높이 축(z)이다. 같은 화면에서
+   * 한 낱말이 두 축을 가리키면 읽는 사람이 매번 어느 쪽인지 물어야 한다.
+   * 단위 필드는 두지 않는다 — 미터로 고정이고, 있으면 "단위를 지원한다" 는 거짓 신호가 된다.
+   */
+  @Column({ type: 'float', nullable: true })
+  @Field({ nullable: true, description: 'Extent of the design frame along the east-west axis, in metres. Area layouts are placed within this frame.' })
+  extentX?: number
+
+  @Column({ type: 'float', nullable: true })
+  @Field({ nullable: true, description: 'Extent of the design frame along the north-south axis, in metres. Area layouts are placed within this frame.' })
+  extentY?: number
+
   /**
    * 이 현장의 시각 기준 — IANA 이름(`'America/Tijuana'`).
    *
@@ -60,10 +81,23 @@ export class TwinSpace {
   @Field({ nullable: true, description: 'Id of the primary representation shown on the home/monitor.' })
   primaryRepresentationId?: string
 
-  /* @deprecated 전환기 — 정규화(representation/area) 전 단일 content. P6 에서 제거. */
+  /**
+   * 이 **현장**의 로컬 선언 겹 — 요금처럼 **트윈이 아니라 현장이 정하는 수**.
+   *
+   * ── 왜 트윈에 두면 안 되나 (2026-08-18) ────────────────────────────────────
+   * 요금 단가·통화는 그 현장의 계약이므로, 같은 수전을 보는 EMS 트윈이 둘이면 **같은 값을 두 번**
+   * 선언해야 했다. 두 번 적는 값은 반드시 갈라진다(하나만 고치는 날이 온다) — 그때 두 트윈이 다른
+   * 금액을 말하고, 어느 쪽이 맞는지 화면으로는 알 수 없다.
+   *
+   * 적용 순서는 **현장 먼저, 트윈이 나중**이다. 더 좁은 선언이 이긴다 — 한 현장 안에서 특정 트윈만
+   * 다른 값으로 실험하는 일이 있고(예: 인상된 단가로 what-if), 그때 현장 값을 고치게 만들면 나머지
+   * 트윈이 함께 흔들린다.
+   *
+   * 모양은 트윈 겹과 같다(`LocalDeclaration`) — 같은 규칙(검사·기억·철회)을 두 벌로 만들지 않는다.
+   */
   @Column({ type: 'simple-json', nullable: true })
-  @Field(type => ScalarObject, { nullable: true, description: '[deprecated] legacy single-blob content; superseded by normalized representations/areas.' })
-  content?: any
+  @Field(type => ScalarObject, { nullable: true, description: "Locally-declared values that belong to this facility rather than to one twin (tariff, currency). Applied to every twin in the space before the twin's own declarations, which win when both name the same property." })
+  localDeclarations?: any
 
   @CreateDateColumn()
   @Field({ nullable: true, description: 'Timestamp when the space was created.' })

package/server/service/twin-structure/twin-structure.ts

@@ -3,7 +3,7 @@ import { ObjectType, Field, ID, Int } from 'type-graphql'
 
 import { Domain, ScalarObject } from '@things-factory/shell'
 import { User } from '@things-factory/auth-base'
-import { boardColumnTransformer } from '../../engine/board-vocabulary.js'
+import { modelColumnTransformer } from '../../engine/model-vocabulary.js'
 
 /*
  * TwinStructure — **한 트윈이 거쳐 온 공장 구조들.** 리비전 하나가 그 시절의 공장이다.
@@ -17,11 +17,11 @@ import { boardColumnTransformer } from '../../engine/board-vocabulary.js'
  * 그래서 선택지가 둘뿐이었다: **역사를 잃거나, 거짓말을 하거나.**
  *
  * 셋째 길이 이 표다. 이벤트가 `structureRev` 로 자기 구조를 달고 다니고, 재생은 구조가 바뀌는
- * 지점에서 갈아탄 뒤 이어 접는다(`replaySegments`). 이력은 "그때 그 공장의 사실" 로 계속 읽힌다.
+ * 지점에서 전환한 뒤 이어 접는다(`replaySegments`). 이력은 "그때 그 공장의 사실" 로 계속 읽힌다.
  *
- * ── 왜 board 를 통째로 담나 ─────────────────────────────────────────────────
- * 재생하려면 **그때의 토폴로지 전체**가 필요하다. 차이(diff)만 담으면 리비전 1부터 되짚어 쌓아야
- * 하고, 그 되짚기 자체가 또 하나의 규칙이 되어 갈라진다. 구조는 이벤트에 비해 드물게 바뀌므로
+ * ── 왜 model 를 통째로 담나 ─────────────────────────────────────────────────
+ * 재생하려면 **그때의 토폴로지 전체**가 필요하다. 차이(diff)만 담으면 리비전 1부터 다시 계산해 쌓아야
+ * 하고, 그 재계산 자체가 또 하나의 규칙이 되어 어긋난다. 구조는 이벤트에 비해 드물게 바뀌므로
  * 스냅샷을 통째로 두는 편이 싸고 정직하다(보드 이력 `BoardHistory` 와 같은 선택).
  *
  * ── audit 컬럼을 다 두지 않는 이유 ──────────────────────────────────────────
@@ -72,11 +72,11 @@ export class TwinStructure {
   @Field({ description: 'Short hash of the structural signature (locations + equipment). A re-provision with the same signature does not create a new revision — otherwise every reboot would slice the history into meaningless segments.' })
   signature: string
 
-  /* 읽을 때 어휘 세대를 흡수한다 — 옛 리비전의 보드로 지문을 다시 계산할 때 빈 공장으로 읽히면
-     구조 변경 감지가 죽는다(`engine/board-vocabulary.ts`). */
-  @Column({ type: 'simple-json', transformer: boardColumnTransformer })
-  @Field(type => ScalarObject, { description: 'The full BoardDef as it stood for this revision. Stored whole rather than as a diff: replay needs the entire topology, and rebuilding it from diffs would be a second rule that can drift.' })
-  board: any
+  /* 읽을 때 어휘 세대를 흡수한다 — 옛 리비전의 모델로 지문을 다시 계산할 때 빈 공장으로 읽히면
+     구조 변경 감지가 죽는다(`engine/model-vocabulary.ts`). */
+  @Column({ type: 'simple-json', transformer: modelColumnTransformer })
+  @Field(type => ScalarObject, { description: 'The full TwinModelDef as it stood for this revision. Stored whole rather than as a diff: replay needs the entire topology, and rebuilding it from diffs would be a second rule that can drift.' })
+  model: any
 
   /** 왜 바뀌었나 — 사람이 남기는 한 줄. 없을 수 있다(자동 프로비저닝은 이유를 모른다). */
   @Column({ nullable: true })

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]
+}