@things-factory/headless-twin 10.0.18 → 10.1.0

package/server/service/reference/reference-master.ts

@@ -142,6 +142,20 @@ export interface RefTestSpecification {
 export interface RefEquipment {
   id: string
   kind: string
+  /**
+   * 속한 **등급들** — 계약 선언의 `equipment[].equipmentClassIds` 로 그대로 간다.
+   *
+   * ── 왜 빠져 있었나 (2026-09-04) ─────────────────────────────────────────
+   * 커널에 이 축을 여는 날 모델·상태·저널·미러까지 배선했는데 **접수면이 빠졌다.** 사람과 자산은
+   * 받는데(`personnelClassIds`·`assetClassIds`) 설비만 없었다.
+   *
+   * 그래서 원본이 설비 22대에 등급을 다 채워 보냈는데 **문턱에서 버려졌다** — 거절도 경고도 없이.
+   * 등급 목록은 서고 소속은 아무도 없어서, 화면에서 등급을 골라도 설비가 안 나왔다.
+   *
+   * 소속은 이 선언과 `kind` 를 합친 것이다(§`equipmentClassMembership`) — 판정하는 쪽이 그 함수를
+   * 지난다.
+   */
+  equipmentClassIds?: string[]
   /** 사람이 부르는 이름 — 없으면 화면이 id 를 보인다(id 를 이름으로 베끼지 않는다). */
   name?: string
   /** 시험 결과 — 자격이 성립하는지는 이것이 말한다(§RefTestResult). */
@@ -273,6 +287,33 @@ export interface RefPerson {
   name?: string
   /** 시험 결과 — 자격이 성립하는지는 이것이 말한다(§RefTestResult). */
   testResults?: RefTestResult[]
+  /**
+   * **이 사람의 전역 정체성** — 커널 선언의 `personnel[].identity` 로 간다.
+   *
+   * ── 왜 필요한가 (인티그레이션 레인이 물음, 2026-09-05) ─────────────────────
+   * 설비에서 이 자리를 만든 이유가 사람에게도 그대로 걸린다: **지역 이름은 그 현장 안에서만
+   * 고유하다.** 인버터 `001` 이 두 발전소에 있어서 함께 집계하니 한쪽 발전량이 사라졌다.
+   * `E-1001` 도 다른 공장에 있을 수 있고, 여러 현장을 함께 보는 순간 같은 일이 난다.
+   *
+   * ── **여기에 개인정보를 넣지 않는다** ──────────────────────────────────────
+   * 설비와 사람이 갈리는 자리가 이것이다. 설비의 정체성은 하드웨어 일련번호이고 아무에게도 해가
+   * 없다. 사람의 「전역에서 고유한 값」은 사원번호·출입카드·주민등록처럼 **그 사람에 관한 사실**
+   * 이고, 저널은 되풀이 읽히고 미러로 복제되고 구독으로 방송된다 — 한 번 들어가면 지워지지 않는다.
+   *
+   * 그래서 이 칸이 요구하는 것은 **현장을 앞에 붙여 전역에서 고유해진 이름**이다. 그 이상이 아니다.
+   *
+   * ```
+   * 맞다    urn:hatiolab:mes-line-a:obj:E-1001      (§`objectUri` 가 만든다)
+   *         https://hatiotrailer.com/twin/obj/E-1001
+   * 아니다  카드번호 · 사원번호 원문 · 주민등록번호 · 생체 식별자
+   * ```
+   *
+   * 「이 사람이 누구인가」는 인사 시스템이 답할 물음이고 트윈의 물음이 아니다. 트윈은 **같은
+   * 사람인지 다른 사람인지**만 알면 된다 — 그 일에 개인정보는 필요 없다.
+   *
+   * 값이 없으면 비운다. 지금 원본이 그런 값을 주지 않으므로 당분간 비어 있는 것이 정상이다.
+   */
+  identity?: string
   /**
    * 속한 등급들 — **표준 `Person.PersonnelClassID`, `maxOccurs="unbounded"`**.
    * 복수인 것이 표준이고 그것이 자격 표현이다: 한 사람이 용접 자격과 지게차 자격을 함께 갖는다.
@@ -319,8 +360,21 @@ export interface RefAsset {
   assetClassIds?: string[]
   /** 기본 위치. */
   homeLocationId?: string
-  /** 정식 GS1 정체성 — 반복사용 자산=GRAI. */
-  gs1Id?: string
+  /**
+   * **이 자산의 전역 정체성** — 설비와 같은 이름이다(§`RefEquipment.identity`).
+   *
+   * ── 왜 이름을 바꿨나 (2026-09-04) ───────────────────────────────────────
+   * `gs1Id` 였다. 설비에서 그 이름을 바꾼 이유가 여기에도 그대로 적용된다 — **GS1 키가 아닌 것이
+   * 정상이다.** 자산의 실측 값도 제조번호·사내 관리번호이고, GS1 을 요구하는 이름을 두면 그것을
+   * 채우는 쪽이 없는 키를 지어내거나 칸을 비워 둔다.
+   *
+   * 그리고 마스터는 이미 `identity` 로 낸다(설비·자산 둘 다). 이 자리만 다른 이름이라 **원본이
+   * 채우는 순간 조용히 사라졌다.** 지금 자산 26대가 다 비어 있어 버려지는 값은 없었다 —
+   * 인티그레이션 레인이 그것을 재서 「누가 채우는 순간」이라고 짚었다.
+   *
+   * 자리 쪽(`RefLocation.gs1Id`)은 그대로다 — 거기는 실제로 SGLN 이 온다.
+   */
+  identity?: string
   /** 자원 속성 — 표준 `PhysicalAssetProperty`(적재 한도·규격 등). */
   properties?: RefResourceProperty[]
   /** 적격을 검증한 시험 명세들 — 표준 `TestSpecificationID`. */
@@ -747,9 +801,27 @@ export function masterToTwin(master: ReferenceMaster, catalog?: any): IngestedTw
     return { id: l.id, type: l.type, ...(l.name ? { name: l.name } : {}), ...(l.description ? { description: l.description } : {}), capacity: l.capacity ?? 0, ...(l.parallelism !== undefined ? { parallelism: l.parallelism } : {}), ...(l.level ? { level: l.level } : {}), ...(l.properties?.length ? { properties: l.properties } : {}), parentId: l.parentId, ...(l.upstreamId ? { upstreamId: l.upstreamId } : {}), gs1Id: l.gs1Id }
   })
 
+  /*
+   * ── 설비가 구역에 서 있을 수 있다 (2026-09-06) ──────────────────────────────
+   * 마스터는 자리와 구역을 **한 목록**에 담고 `role` 로 가른다(§`locationEntries` · `areaLocs`).
+   * 그래서 설비의 `homeLocationId` 가 구역을 가리킬 수 있다 — 실제로 `EQ-CAM-SHOWER-01` 이
+   * `LINE-CAM`(구역)에 서 있고, 그것이 정상이다(에어샤워는 라인 전체에 딸린다).
+   *
+   * 계약이 그 구분을 위해 `homeLocationKind` 를 두었는데(`HomeKind = 'location' | 'area'`)
+   * **아무도 안 채우고 있었다.** 그래서 인제스트가 그 참조를 「끊어졌다」고 경고했다.
+   *
+   * 짐작하지 않는다 — 마스터가 이미 `role` 로 말하고 있으므로 그것을 읽는다.
+   */
+  const areaIds = new Set(master.locations.filter(l => l.role === 'area').map(l => l.id))
+
   const equipment = (master.equipment ?? []).map(e => ({
     id: e.id, kind: e.kind, ...(e.name ? { name: e.name } : {}), ...(e.description ? { description: e.description } : {}), ...(e.testResults?.length ? { testResults: e.testResults } : {}),
-    homeLocation: e.homeLocationId, mtbfMs: e.mtbfMs, mttrMs: e.mttrMs, ...(e.identity ? { identity: e.identity } : {}),
+    /* 등급 소속 — 사람·자산과 같은 자리. 빠뜨리면 원본이 채운 등급이 문턱에서 조용히 버려진다. */
+    ...(e.equipmentClassIds?.length ? { equipmentClassIds: e.equipmentClassIds } : {}),
+    homeLocation: e.homeLocationId,
+    /* 자리면 안 적는다 — 계약의 기본값이 `location` 이고, 없는 칸을 만들면 화면이 그것을 그린다. */
+    ...(e.homeLocationId && areaIds.has(e.homeLocationId) ? { homeLocationKind: 'area' as const } : {}),
+    mtbfMs: e.mtbfMs, mttrMs: e.mttrMs, ...(e.identity ? { identity: e.identity } : {}),
     ...(e.window ? { window: e.window } : {}),
     /* 속성은 손대지 않고 통과 — 이동시간 추정기가 kind 별 속도를 여기서 읽는다(단위 코드 그대로). */
     ...(e.properties?.length ? { properties: e.properties } : {}), ...(e.workCalendar?.length ? { workCalendar: e.workCalendar } : {}), ...(e.testSpecificationIds?.length ? { testSpecificationIds: e.testSpecificationIds } : {}),
@@ -773,6 +845,18 @@ export function masterToTwin(master: ReferenceMaster, catalog?: any): IngestedTw
   if (master.space.timezone && utcOffsetMinutes === undefined) {
     warnings.push(unknownTimezone(String(master.space.timezone)))
   }
+  /*
+   * ── 이름도 함께 싣는다 (2026-09-07) ────────────────────────────────────────
+   * 위에서 푼 오프셋은 **이 순간의** 값이고, 이 모델은 저장된다. 그래서 그 수는 마스터를 받은 날의
+   * 계절로 굳는다 — `America/Tijuana`(PST −480 / PDT −420)가 자료에 있고, 지난 구간을 교대별로 접으면
+   * 그 안의 전환이 사실을 한 시간 밀어 **다른 교대로** 세게 한다. 오류는 나지 않는다.
+   *
+   * 이름이 함께 있으면 소비처가 순간마다 다시 풀 수 있다(§`shiftContext`). 커널은 이 값을 쓰지 않는다.
+   *
+   * 오프셋이 안 풀린 이름은 싣지 않는다 — 그 경우는 위에서 경고로 말했고, 풀리지 않는 이름을 실어
+   * 두면 소비처가 그것을 믿고 매번 실패한다.
+   */
+  const timezone = utcOffsetMinutes !== undefined ? master.space.timezone : undefined
   /*
    * 오퍼레이션 명세를 model 에 통과시킨다 — 커널이 `loadOperations` 로 소비한다(TwinModelDef 확장 필드,
    * 모르는 커널은 무시). 여기서 값을 손대지 않는다: 기간은 표준 표기(ISO 8601)로 커널까지 그대로 간다.
@@ -784,9 +868,9 @@ export function masterToTwin(master: ReferenceMaster, catalog?: any): IngestedTw
     }
   }
   /* 사람도 손대지 않고 통과 — 등급·교대 그대로 커널까지 간다(경계에서 어휘를 갈지 않는다). */
-  const persons = master.persons?.map(p => ({ id: p.id, ...(p.name ? { name: p.name } : {}), ...(p.testResults?.length ? { testResults: p.testResults } : {}), personnelClassIds: p.personnelClassIds, ...(p.window ? { window: p.window } : {}), ...(p.workCalendar?.length ? { workCalendar: p.workCalendar } : {}), ...(p.homeLocationId ? { homeLocation: p.homeLocationId } : {}), ...(p.properties?.length ? { properties: p.properties } : {}), ...(p.testSpecificationIds?.length ? { testSpecificationIds: p.testSpecificationIds } : {}), ...(p.effectiveStart ? { effectiveStart: p.effectiveStart } : {}), ...(p.effectiveEnd ? { effectiveEnd: p.effectiveEnd } : {}) }))
+  const persons = master.persons?.map(p => ({ id: p.id, ...(p.name ? { name: p.name } : {}), ...(p.testResults?.length ? { testResults: p.testResults } : {}), personnelClassIds: p.personnelClassIds, ...(p.identity ? { identity: p.identity } : {}), ...(p.window ? { window: p.window } : {}), ...(p.workCalendar?.length ? { workCalendar: p.workCalendar } : {}), ...(p.homeLocationId ? { homeLocation: p.homeLocationId } : {}), ...(p.properties?.length ? { properties: p.properties } : {}), ...(p.testSpecificationIds?.length ? { testSpecificationIds: p.testSpecificationIds } : {}), ...(p.effectiveStart ? { effectiveStart: p.effectiveStart } : {}), ...(p.effectiveEnd ? { effectiveEnd: p.effectiveEnd } : {}) }))
   /* 자산도 손대지 않고 통과 — 등급·자리 그대로 커널까지. */
-  const assets = master.assets?.map(a => ({ id: a.id, ...(a.name ? { name: a.name } : {}), ...(a.testResults?.length ? { testResults: a.testResults } : {}), assetClassIds: a.assetClassIds, homeLocation: a.homeLocationId, gs1Id: a.gs1Id, ...(a.properties?.length ? { properties: a.properties } : {}), ...(a.testSpecificationIds?.length ? { testSpecificationIds: a.testSpecificationIds } : {}), ...(a.effectiveStart ? { effectiveStart: a.effectiveStart } : {}), ...(a.effectiveEnd ? { effectiveEnd: a.effectiveEnd } : {}) }))
+  const assets = master.assets?.map(a => ({ id: a.id, ...(a.name ? { name: a.name } : {}), ...(a.testResults?.length ? { testResults: a.testResults } : {}), assetClassIds: a.assetClassIds, homeLocation: a.homeLocationId, ...(a.identity ? { identity: a.identity } : {}), ...(a.properties?.length ? { properties: a.properties } : {}), ...(a.testSpecificationIds?.length ? { testSpecificationIds: a.testSpecificationIds } : {}), ...(a.effectiveStart ? { effectiveStart: a.effectiveStart } : {}), ...(a.effectiveEnd ? { effectiveEnd: a.effectiveEnd } : {}) }))
   /* 품목 정의·등급도 손대지 않고 통과 — 경계에서 어휘를 갈지 않는다(환산 계수는 커널이 읽는다). */
   const materialDefinitions = master.materialDefinitions?.map(d => ({
     id: d.id,
@@ -833,6 +917,7 @@ export function masterToTwin(master: ReferenceMaster, catalog?: any): IngestedTw
     ...(materialDefinitions?.length ? { materialDefinitions } : {}),
     ...(materialClasses?.length ? { materialClasses } : {}),
     ...(utcOffsetMinutes !== undefined ? { utcOffsetMinutes } : {}),
+    ...(timezone ? { timezone } : {}),
     ...(operations?.length ? { operations } : {}),
     ...(testSpecifications?.length ? { testSpecifications } : {}),
     ...(personnelClasses?.length ? { personnelClasses } : {}),

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

@@ -1,7 +1,7 @@
 import { pubsub } from '@things-factory/shell'
 import { HOST_STEPS, type ReferenceProgress } from './reference-progress.js'
 import { assessMaster } from './reference-assessment.js'
-import { Arg, Ctx, Mutation, Query, Resolver, Directive} from 'type-graphql'
+import { Arg, Ctx, Int, Mutation, Query, Resolver, Directive } from 'type-graphql'
 
 import { ScalarObject, getRepository } from '@things-factory/shell'
 
@@ -14,6 +14,7 @@ import type { KnobDef } from './template-registry.js'
 import { knobDefaultsFilled, pickOriginSite, siteEquipmentAdopted } from './reference-master.js'
 import { TwinInstance } from '../twin-instance/twin-instance.js'
 import { TwinReference } from './twin-reference.js'
+import { runFill, seqReportOf } from './reference-fill-run.js'
 import { listReferences, getReference } from './reference-registry.js'
 import { getAdapter, listAdapterTypes, listAdapters } from './reference-adapter.js'
 import {
@@ -193,6 +194,67 @@ export class TwinReferenceResolver {
    * `origin` 이 없는 트윈(이 자리가 생기기 전에 만들어진 것)은 다시 읽을 수 없다. 짐작으로
    * 템플릿을 고르거나 첫 레퍼런스를 집지 않는다 — 엉뚱한 원본으로 현장을 덮는 것이 훨씬 나쁘다.
    */
+  /**
+   * **그 번호들이 무엇이었나** — 구멍을 만났을 때 원본에 묻는다.
+   *
+   * `fillTwinScope` 가 「418 다음이 420」이라고 멈추면, 그 419 가 무엇이었는지 알아야 다음을
+   * 정할 수 있다. 그 길이 없어서 사람이 원본 DB 를 손으로 뒤졌다.
+   *
+   * **판정하지 않는다.** 원본이 아는 것을 그대로 낸다 — `lost` 는 「번호는 나갔는데 행이 없다」이지
+   * 「포기해도 된다」가 아니다. 그 판단은 되돌릴 수 없어서(커서가 지나가면 끝이다) 사람의 몫이다.
+   */
+  /*
+   * **읽기인데 쓰기와 같은 문을 쓴다.** 이 문은 원본의 봉투를 그대로 냅니다 — 그 시스템이 무엇을
+   * 언제 보냈는지가 드러납니다. `twinConnectionBundle` 과 같은 무게이고, 이 저장소는 그 무게를
+   * 「쓰기는 GATE 하나」로 통일해 두었습니다(ADR-0027).
+   */
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
+  @Query(returns => ScalarObject, {
+    description:
+      'Ask the source what it knows about a range of sequence numbers. Each number comes back as present · lost · unissued · unknown — the source reports, the human decides.'
+  })
+  async twinSeqReport(
+    @Arg('instanceId') instanceId: string,
+    @Arg('scope') scope: string,
+    @Arg('from', type => Int) from: number,
+    @Arg('to', type => Int) to: number,
+    @Ctx() context: ResolverContext
+  ): Promise<any> {
+    return seqReportOf({ domainId: context.state.domain.id, instanceId, scope, from, to })
+  }
+
+  /**
+   * **빠진 구간을 다시 받는다** — 훅은 반드시 놓칩니다: 우리가 내려가 있을 때, 그쪽이 못 보냈을 때.
+   *
+   * ── 왜 문이 필요한가 ──────────────────────────────────────────────────────
+   * 번호가 비면 `takeInSequence` 가 알아챕니다. 그런데 **알아챈 뒤 그 사이를 채우는 길이 없었습니다.**
+   * `fillSince` 는 2026-08-31 부터 있었고 부르는 곳이 0곳이었습니다.
+   *
+   * 실제로 plant 아웃박스의 1~20 을 잃고 되찾을 방법이 없는 상태를 만났습니다.
+   *
+   * ── `from` 은 잃은 구간을 되찾을 때만 ──────────────────────────────────────
+   * 주지 않으면 커서부터 이어 받습니다. 주면 **그 번호부터 다시 묻습니다** — 이미 들어간 것은 유입
+   * 경계가 되풀이로 거르므로 두 번 앉지 않습니다.
+   *
+   * 저장된 커서를 되돌리지 않습니다. `fillSince` 는 번호 검사를 지난 만큼만 적으므로, 되찾은 뒤
+   * 커서가 원래 자리보다 앞서지 않습니다.
+   */
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
+  @Mutation(returns => ScalarObject, {
+    description:
+      'Fetch the stretch this twin missed for one scope and ingest it through the same checks as the push path. Without `from` it continues from the cursor; with `from` it asks again from that number — already-ingested facts are filtered as duplicates.'
+  })
+  async fillTwinScope(
+    @Arg('instanceId') instanceId: string,
+    @Arg('scope', { description: 'The unit the source numbers by — the same name its envelopes carry (e.g. EVENTS).' }) scope: string,
+    @Ctx() context: ResolverContext,
+    @Arg('from', type => Int, { nullable: true, description: 'Ask again from this sequence number. Omit to continue from the cursor.' })
+    from?: number,
+    @Arg('maxPages', type => Int, { nullable: true, description: 'Page limit for one run. Default 50.' }) maxPages?: number
+  ): Promise<any> {
+    return runFill({ domainId: context.state.domain.id, instanceId, scope, from: from ?? undefined, maxPages: maxPages ?? undefined })
+  }
+
   @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => ScalarObject, {
     description:
@@ -265,7 +327,20 @@ export class TwinReferenceResolver {
         await getRepository(TwinReference).update(
           { id: refRow.id },
           {
-            scopeSpec: { ...prevSpec, assessments: { ...(prevSpec.assessments ?? {}), [siteId]: assessMaster(master, siteId) } }
+            scopeSpec: { ...prevSpec, assessments: { ...(prevSpec.assessments ?? {}), [siteId]: assessMaster(master, siteId) } },
+            /*
+             * ── 읽은 시각과 경고 수도 새로 남긴다 (2026-09-06) ──────────────────
+             * 처음 연결하는 경로는 이 둘을 쓰는데(§`connectReference`) 다시 읽는 경로는 총평만
+             * 썼다. 그래서 `lastSyncedAt` 이 「처음 트윈을 만든 시각」에 머물렀다.
+             *
+             * 이것이 실제로 잘못된 판단을 만들었다. 인티그레이션 레인이 커넥터를 고치고 재동기화를
+             * 청한 뒤 이 칸으로 확인했는데, 값이 그대로여서 「안 돌았다」고 결론 내렸다. 실제로는
+             * 돌았고 품목 106건이 들어와 있었다.
+             *
+             * 경고 수도 같다. 다시 읽으면서 경고가 줄거나 늘었는데 화면은 지난 수를 보인다.
+             */
+            lastSyncedAt: new Date().toISOString(),
+            lastWarningCount: Array.isArray(res.warnings) ? res.warnings.length : null
           } as any
         )
       }

package/server/service/twin-event/twin-event-keys.ts

@@ -23,6 +23,7 @@ export interface TwinEventKeys {
   bizStep?: string
   epc?: string
   orderId?: string
+  bizTransaction?: string
   locationId?: string
   moverId?: string
 }
@@ -80,15 +81,46 @@ export function epcOf(envelope: any): string | undefined {
  * 없었다. 화면은 오더를 눌러도 「연결된 이벤트가 없습니다」를 냈고, 그 답은 질의 결과로는 정직했다 —
  * 시점을 어디로 옮겨도 0 이었다.
  *
- * 순서가 중요하다: 운영 델타가 먼저다. EPCIS 의 `bizTransactionList` 는 **거래**(PO/SO)이고 오더와
- * 같은 것이 아닐 수 있으므로, 오더를 스스로 말하는 사건은 그 말을 그대로 쓴다.
- *
  * **과거 행은 채워지지 않는다**(사용자 결정 2026-08-24, `moverId` 때와 같은 방식). 앞으로 들어오는
  * 사건부터 조회된다.
+ *
+ * ── 한 칸에 두 낱말이 들어 있었다 (2026-09-05 실측) ────────────────────────
+ * 위 주석이 이미 알고 있었다 — 「EPCIS 의 `bizTransactionList` 는 **거래**(PO/SO)이고 오더와 같은
+ * 것이 아닐 수 있다」. 그런데 그 둘을 **같은 칸에** 넣고 있었다. 그래서 이렇게 됐다.
+ *
+ *   order.status                order-1                          내부 오더 id
+ *   epcis.TransformationEvent   urn:epc:id:gdti:9521321.403.1    GS1 거래 식별자
+ *   epcis.TransactionEvent      urn:epc:id:gdti:9521321.403.1
+ *
+ * 한 오더의 이력이 **색인 안에서 두 쪽으로 갈라진다.** 어느 이름으로 물어도 절반만 나오고,
+ * 오류는 나지 않는다. 실측: 어휘가 섞인 행 10,004개.
+ *
+ * 이것이 실제로 막은 것 — 「이 개체를 어느 레시피로 만들었나」다. 답은 기록되어 있다(오더 사건이
+ * `recipeKey` 를 든다, 실측 328,021/328,021 = 100%). 변환 사건은 그 오더를 GDTI 로 가리키는데
+ * 오더 사건은 `order-1` 로 적혀 있어 **색인으로 이을 수가 없었다.**
+ *
+ * 그래서 칸을 갈랐다(사용자 결정 2026-09-05).
+ *
+ *   orderId          내부 오더 id — 읽기 모델의 이음쇠
+ *   bizTransaction   GS1 거래 식별자 — 표준이 말하는 그 거래
+ *
+ * 오더 사건은 **둘 다** 든다(`order.status` 의 payload 에 `orderId` 와 `bizTransaction` 이 함께
+ * 있다). 그래서 EPCIS 사건의 거래 식별자로 오더를 찾을 수 있다 — 이 두 칸이 그 다리다.
  */
 export function orderOf(envelope: any): string | undefined {
   const d = envelope?.data ?? envelope ?? {}
-  return d.orderId ?? d.bizTransactionList?.[0]?.bizTransaction ?? undefined
+  return d.orderId ?? undefined
+}
+
+/**
+ * **그 사건이 가리키는 거래** — EPCIS `bizTransactionList` 의 첫 항목, 또는 운영 델타가 직접 든 값.
+ *
+ * 오더가 아니다. 표준이 말하는 거래(PO/SO/생산오더)이고, 한 오더가 여러 거래에 걸릴 수도 있다.
+ * 그 구별을 지키려고 `orderId` 와 갈라 두었다 — 합치면 위 주석의 그 일이 다시 난다.
+ */
+export function bizTransactionOf(envelope: any): string | undefined {
+  const d = envelope?.data ?? envelope ?? {}
+  return d.bizTransactionList?.[0]?.bizTransaction ?? d.bizTransaction ?? undefined
 }
 
 /**
@@ -143,6 +175,7 @@ export function twinEventKeys(envelope: any): TwinEventKeys {
     bizStep: clip(bizStepOf(envelope), 'bizStep'),
     epc: clip(epcOf(envelope), 'epc'),
     orderId: clip(orderOf(envelope), 'orderId'),
+    bizTransaction: clip(bizTransactionOf(envelope), 'bizTransaction'),
     locationId: clip(locationOf(envelope), 'locationId'),
     moverId: clip(equipmentIdOf(envelope), 'moverId')
   }

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

@@ -20,6 +20,7 @@ import { Domain, ScalarObject } from '@things-factory/shell'
  *  ix_2 (domain, instanceId, eventType, revision) 타입 필터 + 정렬 동시 충족(스케줄 화면 task/equipment)
  *  ix_3 (domain, instanceId, epc)                 "이 물건의 이력" — Entity360 의 본질 질문
  *  ix_4 (domain, instanceId, orderId)             "이 오더가 어디까지 갔나"
+ *  ix_9 (domain, instanceId, bizTransaction)      "이 거래에 무슨 일이 있었나" — EPCIS↔오더의 다리
  *
  * bizStep·locationId·moverId 는 컬럼만 두고 인덱스는 두지 않는다 — 한 트윈 안에서 카디널리티가
  * 낮아(업무단계 몇 개, 위치 수백, 설비 수십) (domain,instanceId) 로 이미 좁혀진 뒤의 잔여 필터로
@@ -62,6 +63,8 @@ import { Domain, ScalarObject } from '@things-factory/shell'
  * 정리는 한 창에 2초만 쓰도록 예산이 걸려 있어서, 그 2초를 주사에 다 쓰고 44건만 지우고 멈췄다.
  */
 @Index('ix_twin_event_8', (e: TwinEvent) => [e.domain, e.instanceId, e.createdAt], { unique: false })
+/* ix_9 — "이 거래에 무슨 일이 있었나". EPCIS 사건에서 오더로 건너가는 다리(§`bizTransaction`). */
+@Index('ix_twin_event_9', (e: TwinEvent) => [e.domain, e.instanceId, e.bizTransaction], { unique: false })
 @ObjectType({ description: 'Append-only twin event journal record (EPCIS event or operational delta).' })
 export class TwinEvent {
   @PrimaryGeneratedColumn('uuid')
@@ -174,9 +177,23 @@ export class TwinEvent {
   epc?: string
 
   @Column({ length: 255, nullable: true })
-  @Field({ nullable: true, description: 'Business transaction identifier (PO / SO), promoted from the payload for indexed lookup of one order history.' })
+  @Field({ nullable: true, description: 'Internal order identifier, promoted from the payload for indexed lookup of one order history.' })
   orderId?: string
 
+  /*
+   * **거래 식별자는 오더 식별자와 다른 것이다.**
+   *
+   * 전에는 둘이 한 칸(`orderId`)에 들어갔다. 그래서 한 오더의 이력이 색인 안에서 두 쪽으로
+   * 갈라졌다 — 운영 델타는 `order-1`, EPCIS 사건은 `urn:epc:id:gdti:…` 로 적혀 어느 이름으로
+   * 물어도 절반만 나왔다(실측 2026-09-05: 어휘가 섞인 행 10,004개, 오류는 나지 않음).
+   *
+   * 오더 사건은 두 값을 다 들고 있다. 그래서 이 칸이 **EPCIS 사건에서 오더로 건너가는 다리**가
+   * 된다 — 「이 개체를 어느 레시피로 만들었나」가 그 다리로 답해진다.
+   */
+  @Column({ length: 255, nullable: true })
+  @Field({ nullable: true, description: 'Business transaction identifier (PO / SO / production order), promoted from the payload for indexed lookup of one transaction.' })
+  bizTransaction?: string
+
   @Column({ length: 255, nullable: true })
   @Field({ nullable: true, description: 'Location identifier (read point, business location, or the plain location an operational delta carries), promoted from the payload for indexed filtering.' })
   locationId?: string

package/server/service/twin-model/choose-recipe.ts

@@ -0,0 +1,31 @@
+/*
+ * **어느 레시피로 만들었나** — 판정만. 순수하다.
+ *
+ * ── 왜 따로 있나 ───────────────────────────────────────────────────────────
+ * 계보 질의는 TypeORM 과 shell 을 끌어온다. 규칙만 재려는 시험이 그것까지 들고 오면 무겁고, 이
+ * 저장소에서 그 이유로 시험이 안 서는 일을 겪었다. 판단과 배선을 나눈다 — 여기는 값만 보고 답한다.
+ */
+/**
+ * 짐작하지 않는 규칙.
+ *
+ *   order            오더가 말했다. 판이 둘이든 열이든 그것을 쓴다
+ *   only-candidate   오더는 말 안 했지만 후보가 하나다 — 고를 것이 없으면 짐작이 아니다
+ *   ambiguous        후보가 둘 이상인데 말해 주는 것이 없다 → **답하지 않는다**
+ *   said-but-undeclared  오더는 말했는데 그 레시피가 선언에 없다 — 모르는 것이 아니라 어긋난 것이다
+ *
+ * 마지막 둘을 가르는 이유: 사람이 할 일이 다르다. 어긋남은 선언이나 원본을 고칠 일이고,
+ * 모호함은 그 개체가 어느 것으로 만들어졌는지 기록이 없는 일이다.
+ */
+export function chooseRecipe(
+  recipes: any[],
+  candidates: any[],
+  saidRecipeKey: string | undefined
+): { recipe?: any; basis: 'order' | 'only-candidate' | 'ambiguous' | 'said-but-undeclared' | 'none' } {
+  if (saidRecipeKey) {
+    const said = recipes.find((r: any) => r?.key === saidRecipeKey)
+    return said ? { recipe: said, basis: 'order' } : { basis: 'said-but-undeclared' }
+  }
+  if (candidates.length === 1) return { recipe: candidates[0], basis: 'only-candidate' }
+  if (candidates.length > 1) return { basis: 'ambiguous' }
+  return { basis: 'none' }
+}

package/server/service/twin-model/external-resolver.ts

@@ -0,0 +1,161 @@
+/*
+ * **board 밖을 가리키는 관계를 푸는 자리** — 선언은 있고 코드가 0곳이던 이음새.
+ *
+ * ── 무엇이 있었나 (2026-09-05 실측) ────────────────────────────────────────
+ * 계약이 `target: { kind: 'external', entity: … }` 를 선언하고 주석에 「해소는 호스트가 한다」고
+ * 적어 두었다. 그런데 **`headless-twin/server` 어디에도 `kind === 'external'` 을 다루는 코드가
+ * 없었다**(0곳).
+ *
+ * `space.area` 가 도는 것처럼 보인 이유는 이음새가 있어서가 아니라 **호스트에서 그것이 평범한 FK
+ * 라서**다. TypeORM 메타데이터가 우연히 답해 준 것이지 선언이 길을 낸 것이 아니다.
+ *
+ * ── 왜 지금 채우나 ─────────────────────────────────────────────────────────
+ * 아침에는 「아무도 안 막혔으니 급하지 않다」로 적었다. **그 판단이 규모를 작게 잡은 것이었다.**
+ *
+ * 360(한 대상에 걸린 것을 한자리에)의 소비처는 무한히 늘어난다. 그러면 각 제품의 자기 저장소가
+ * 관계의 원천이 된다 — MES 의 실적·상태 구간·정비 계획이 그렇고, 다음 제품도 그럴 것이다.
+ *
+ * 그때 **선언은 「밖을 가리킨다」고 말하는데 푸는 길이 없으면 제품마다 자기 길을 낸다.** 그것이
+ * 정확히 「무한히 갈린다」다. 이 파일이 그 갈림을 막는다.
+ *
+ * ── 커널은 어느 표인지 모른다 ──────────────────────────────────────────────
+ * 계약은 「이 축이 밖을 가리킨다」까지만 안다. **「어느 표의 어느 칸」은 제품이 안다.** 그래서 제품이
+ * 부팅에서 해소기를 꽂는다 — 장부 기록기(`installIngestWindowWriter`)와 같은 규율이다.
+ *
+ * 커널이 표 이름을 알게 되면 한 제품의 저장 구조에 매이고, 다음 제품이 다른 표를 쓰면 커널을 또
+ * 고쳐야 한다.
+ *
+ * ── 없는 것을 숨기지 않는다 ────────────────────────────────────────────────
+ * 해소기가 없으면 **그 사실을 낸다**(`unresolved`). 링크를 지우면 화면은 「그런 관계가 없다」로
+ * 읽고, 실제로는 「아무도 답할 수 없다」다. 그 둘은 사람이 할 일이 다르다.
+ */
+
+/** 밖에 사는 대상 하나 — 화면이 이름을 보이고 갈 곳을 정할 수 있게. */
+export interface ExternalRef {
+  id: string
+  /** 사람이 읽는 이름. 없으면 화면이 id 를 보인다(지어내지 않는다). */
+  name?: string
+  /**
+   * 그 제품에서 이것을 열 수 있는 자리 — 없으면 화면이 링크를 만들지 않는다.
+   *
+   * 막다른 링크를 만들지 않는 것이 이 칸의 요점이다. 눌러서 아무 일도 안 일어나면 사람은 그것을
+   * 결함으로 읽는다.
+   */
+  href?: string
+  /** 그 id 가 실제로 있나 — **없으면 없다고 말한다.** 답에서 빼지 않는다. */
+  missing?: boolean
+}
+
+/**
+ * 밖에서 이 대상을 가리키는 것들 — 들어오는 관계 한 묶음.
+ *
+ * `tense` 를 **제품이 선언한다**(계약의 `RelationTense`). 실적·상태 구간은 지난 일이고 정비 계획·
+ * 지시는 앞의 일이다 — 「걸린 것이 열」이 두 뜻이 되는 자리이므로 묶음이 스스로 말해야 한다.
+ */
+export interface ExternalIncoming {
+  /** 관계의 이름(i18n 키) — 계약의 `via` 와 같은 규칙. 제품은 자기 접두를 쓴다. */
+  via: string
+  /** 어디서 오나 — 사람이 읽는 축 이름이 아니라 그 제품의 축 키다. */
+  from: string
+  /** 언제의 일인가. 안 주면 「선언이 말하지 않았다」다 — `standing` 으로 바꾸지 않는다. */
+  tense?: 'past' | 'future' | 'standing'
+  ids: string[]
+  /** 전체 수 — `ids` 가 잘렸어도 몇인지 말한다. */
+  total: number
+}
+
+/**
+ * 한 external 대상을 푸는 제품 쪽 구현.
+ *
+ * 둘 다 선택이다. 이름만 대 줄 수 있는 제품과 들어오는 관계만 낼 수 있는 제품이 다 있다 — 하나만
+ * 꽂아도 그만큼은 답해진다.
+ */
+export interface ExternalResolver {
+  /** 계약의 `target.entity` 와 **같은 낱말**. 다르면 아무 관계에도 안 붙는다. */
+  entity: string
+  /** 이 id 들이 무엇인가. */
+  resolve?(domainId: string, ids: readonly string[]): Promise<ExternalRef[]>
+  /** 이 대상을 가리키는 것들. */
+  incoming?(domainId: string, instanceId: string, axis: string, itemId: string): Promise<ExternalIncoming[]>
+}
+
+const resolvers = new Map<string, ExternalResolver>()
+
+/**
+ * 해소기를 꽂는다 — **부팅에서 한 번.**
+ *
+ * 같은 `entity` 를 두 번 꽂으면 뒤엣것이 이긴다. 그것이 개발 중 재적재의 정상 동작이고, 운영에서
+ * 일어나면 두 제품이 같은 대상을 자기 것이라 말하는 것이므로 **경고를 남긴다** — 조용히 덮으면
+ * 어느 쪽이 답하고 있는지 아무도 모른다.
+ */
+export function registerExternalResolver(r: ExternalResolver, warn?: (msg: string) => void): void {
+  const entity = String(r?.entity ?? '').trim()
+  if (!entity) {
+    warn?.('[external-resolver] entity 없는 해소기는 꽂지 않는다 — 아무 관계에도 안 붙는다')
+    return
+  }
+  if (resolvers.has(entity)) {
+    warn?.(`[external-resolver] '${entity}' 해소기를 덮어쓴다 — 두 제품이 같은 대상을 답하려 하면 그중 하나만 답한다`)
+  }
+  resolvers.set(entity, { ...r, entity })
+}
+
+/** 지금 꽂혀 있는 것들 — 「무엇을 풀 수 있나」를 밖에서 잴 수 있게. */
+export function externalResolverEntities(): string[] {
+  return [...resolvers.keys()].sort()
+}
+
+/** 시험이 재기동을 넣을 수 있게. */
+export function clearExternalResolvers(): void {
+  resolvers.clear()
+}
+
+/**
+ * 그 id 들을 푼다 — **못 풀면 못 푼다고 말한다.**
+ *
+ * 해소기가 터져도 360 전체를 죽이지 않는다. 한 관계가 답을 못 하는 것과 화면이 안 뜨는 것은 다른
+ * 사고이고, 뒤엣것이 훨씬 나쁘다.
+ */
+export async function resolveExternal(
+  entity: string,
+  domainId: string,
+  ids: readonly string[],
+  warn?: (msg: string) => void
+): Promise<{ refs?: ExternalRef[]; unresolved?: 'no-resolver' | 'failed' }> {
+  const r = resolvers.get(entity)
+  if (!r?.resolve) return { unresolved: 'no-resolver' }
+  try {
+    return { refs: await r.resolve(domainId, ids) }
+  } catch (e: any) {
+    warn?.(`[external-resolver] '${entity}' 해소가 실패했다 — ${String(e?.message ?? e)}`)
+    return { unresolved: 'failed' }
+  }
+}
+
+/**
+ * 밖에서 이 대상을 가리키는 것들을 모은다.
+ *
+ * 꽂힌 것이 없으면 **빈 배열이지 오류가 아니다** — 밖에서 가리키는 것이 없는 대상이 정상이다.
+ * 다만 「해소기가 없어서 모른다」와 「없다」는 다르므로, 그 구별은 `externalResolverEntities()` 로
+ * 밖에서 잰다.
+ */
+export async function externalIncoming(
+  domainId: string,
+  instanceId: string,
+  axis: string,
+  itemId: string,
+  warn?: (msg: string) => void
+): Promise<ExternalIncoming[]> {
+  const out: ExternalIncoming[] = []
+  for (const r of resolvers.values()) {
+    if (!r.incoming) continue
+    try {
+      const got = await r.incoming(domainId, instanceId, axis, itemId)
+      /* 빈 묶음은 싣지 않는다 — 여기서는 「그 제품이 이 축을 안 본다」는 뜻이고 할 말이 없다. */
+      for (const g of got ?? []) if (g && g.total > 0) out.push(g)
+    } catch (e: any) {
+      warn?.(`[external-resolver] '${r.entity}' 의 들어오는 관계 조회가 실패했다 — ${String(e?.message ?? e)}`)
+    }
+  }
+  return out
+}

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

@@ -130,10 +130,21 @@ export async function projectStructure(domainId: string, instanceId: string, mod
   const equipment: TwinEquipment[] = (model?.equipment ?? [])
     .filter((m: any) => m?.id)
     .map((m: any) => {
+      /*
+       * ── 설비는 자리에도 구역에도 설 수 있다 (2026-09-06) ─────────────────────
+       * 자리 목록에서 먼저 찾고, 없으면 구역에서 찾는다. `locations.parentId` 가 이미 같은 규율을
+       * 쓴다(§`parentIsLocation`).
+       *
+       * 실물이 있다 — `EQ-CAM-SHOWER-01`(에어샤워)이 `LINE-CAM`(구역)에 딸려 있고, 라인 전체에
+       * 붙는 설비는 자리 하나를 고를 수 없다. 그동안 자리에서만 찾아서 **끊어진 참조로 보고**했다.
+       *
+       * 마스터가 `homeLocationKind: 'area'` 로 말해 주지만 여기서는 조회로 판정한다 — 옛 트윈의
+       * model 에는 그 칸이 없고, 있는 것을 못 찾았다고 말하는 것이 더 나쁘다.
+       */
       const home = m.homeLocation ? locOf.get(m.homeLocation) : undefined
-      /* 끊어진 기준 자리는 **이름을 대고** 보고한다. 예전에는 화면이 경고할 뿐이었고
-         다른 경로로 들어온 데이터는 아무도 안 봤다. */
-      if (m.homeLocation && !home) unresolvedHome.push(`${m.id}→${m.homeLocation}`)
+      const homeArea = m.homeLocation && !home ? areaOf.get(m.homeLocation) : undefined
+      /* 끊어진 기준 자리는 **이름을 대고** 보고한다 — 자리에도 구역에도 없을 때만이다. */
+      if (m.homeLocation && !home && !homeArea) unresolvedHome.push(`${m.id}→${m.homeLocation}`)
       return eqRepo.create({
         ...scope,
         equipmentId: m.id,
@@ -147,6 +158,8 @@ export async function projectStructure(domainId: string, instanceId: string, mod
         /* 결과까지 — 참조만 있으면 "무엇으로 검증한다" 까지고, 자격 성립은 결과가 말한다. */
         testResults: m.testResults ?? null,
         homeLocation: home ? ({ id: home.id } as any) : null,
+        /* 둘 다 차는 일은 없다 — 자리에서 찾았으면 구역은 안 본다. */
+        homeArea: homeArea ? ({ id: homeArea.id } as any) : null,
         mtbfMs: m.mtbfMs ?? null,
         mttrMs: m.mttrMs ?? null,
         /* 선언된 정체성 — 예전에는 선언에 없는 `gs1Id` 를 읽어 이 칸이 늘 비어 있었다. */

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

@@ -5,6 +5,7 @@ import { Domain, ScalarObject } from '@things-factory/shell'
 
 import { TwinInstance } from '../twin-instance/twin-instance.js'
 import { TwinLocation } from './twin-location.js'
+import { TwinArea } from '../twin-space/twin-area.js'
 
 /*
  * TwinEquipment — 이 트윈이 반영하는 **설비**. ISA-95 `Equipment` / ISO 55000 `Asset` / EPCIS `GIAI`.
@@ -114,6 +115,27 @@ export class TwinEquipment {
   @RelationId((e: TwinEquipment) => e.homeLocation)
   homeLocationRowId?: string
 
+  /**
+   * 기준 **구역** — 설비가 자리가 아니라 구역에 서 있을 때.
+   *
+   * ── 왜 칸이 둘인가 (2026-09-06) ────────────────────────────────────────────
+   * 계약이 `homeLocationKind = 'location' | 'area'` 로 그 갈림을 말한다. 실물이 있다 —
+   * `EQ-CAM-SHOWER-01`(에어샤워)이 `LINE-CAM` 이라는 **구역**에 딸려 있고, 그것이 정상이다.
+   * 라인 전체에 붙는 설비는 자리 하나를 고를 수 없다.
+   *
+   * 그동안 이 칸이 없어서 인제스트가 그 참조를 **「끊어졌다」고 경고**했다. 자리 목록에서 못 찾으면
+   * 없는 것으로 봤기 때문이다.
+   *
+   * 한 칸에 두 대상을 담지 않는다 — FK 가 서로 다른 표를 가리키고, 합치면 DB 가 못 막는다.
+   * **둘 다 차는 일은 없다**(마스터의 `role` 이 하나를 정한다).
+   */
+  @ManyToOne(type => TwinArea, { nullable: true, onDelete: 'SET NULL' })
+  @Field(type => TwinArea, { nullable: true, description: 'Home area this equipment belongs to, when it stands in an area rather than a location.' })
+  homeArea?: TwinArea
+
+  @RelationId((e: TwinEquipment) => e.homeArea)
+  homeAreaRowId?: string
+
   /*
    * 고장 모델 — 원본이 선언할 때만 있다. 없으면 고장 없는 설비로 동작한다(커널 계약).
    * **관측(가동률)은 여기 두지 않는다** — 그건 트윈이 저널에서 만든 것이라 성질이 다르고,