@things-factory/headless-twin 10.0.19 → 10.1.0

package/dist-server/service/twin-event/twin-event-keys.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.bizStepOf = bizStepOf;
 exports.epcOf = epcOf;
 exports.orderOf = orderOf;
+exports.bizTransactionOf = bizTransactionOf;
 exports.locationOf = locationOf;
 exports.equipmentIdOf = equipmentIdOf;
 exports.actionOf = actionOf;
@@ -58,15 +59,45 @@ function epcOf(envelope) {
  * 없었다. 화면은 오더를 눌러도 「연결된 이벤트가 없습니다」를 냈고, 그 답은 질의 결과로는 정직했다 —
  * 시점을 어디로 옮겨도 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 사건의 거래 식별자로 오더를 찾을 수 있다 — 이 두 칸이 그 다리다.
  */
 function orderOf(envelope) {
     const d = envelope?.data ?? envelope ?? {};
-    return d.orderId ?? d.bizTransactionList?.[0]?.bizTransaction ?? undefined;
+    return d.orderId ?? undefined;
+}
+/**
+ * **그 사건이 가리키는 거래** — EPCIS `bizTransactionList` 의 첫 항목, 또는 운영 델타가 직접 든 값.
+ *
+ * 오더가 아니다. 표준이 말하는 거래(PO/SO/생산오더)이고, 한 오더가 여러 거래에 걸릴 수도 있다.
+ * 그 구별을 지키려고 `orderId` 와 갈라 두었다 — 합치면 위 주석의 그 일이 다시 난다.
+ */
+function bizTransactionOf(envelope) {
+    const d = envelope?.data ?? envelope ?? {};
+    return d.bizTransactionList?.[0]?.bizTransaction ?? d.bizTransaction ?? undefined;
 }
 /**
  * 위치 — EPCIS 는 읽은 지점(readPoint) 우선, 없으면 업무 위치(bizLocation).
@@ -117,6 +148,7 @@ function twinEventKeys(envelope) {
         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/dist-server/service/twin-event/twin-event-keys.js.map

@@ -1 +1 @@
-{"version":3,"file":"twin-event-keys.js","sourceRoot":"","sources":["../../../server/service/twin-event/twin-event-keys.ts"],"names":[],"mappings":"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","sourcesContent":["import { twinWarn } from '../../engine/log.js'\n/*\n * 저널 검색 키 추출 — **순수**. 인제스트가 기록할 때 한 번 뽑아 인덱스 가능한 실컬럼으로 승격한다.\n *\n * ── 왜 승격하는가 ───────────────────────────────────────────────────────────\n * 사용자가 저널에서 실제로 찾는 것은 \"이 팔레트의 이력\", \"이 오더가 어디까지 갔나\", \"이 도크에서\n * 무슨 일이 있었나\" 다. 그런데 그 값들은 전부 `payload`(simple-json = TEXT) **안**에 있었다.\n * things-factory 는 5개 DB 드라이버를 지원해야 해서 DB별 JSON 연산자를 쓸 수 없다 —\n * 즉 승격 없이는 **어떤 방법으로도 서버에서 그 조건으로 거를 수 없었다**. 클라이언트가 받아온\n * 몇 천 건 안에서만 찾는 시늉이 최선이었고, 저널이 커질수록 그 시늉은 거짓말에 가까워진다.\n *\n * 그래서 검색 축이 되는 값만 골라 컬럼으로 꺼낸다. payload 는 그대로 둔다(정본은 여전히 payload —\n * 이건 파생 색인이지 새로운 진실이 아니다).\n *\n * ── 왜 여기(순수 모듈)인가 ──────────────────────────────────────────────────\n * 기록 경로가 둘이다(`persistBatch` 라이브 벌크 · `persist` 심 단건). 두 곳에 각자 적으면\n * 반드시 어긋나고, 어긋난 색인은 \"없는 것처럼 보이는 이벤트\" 를 만든다 — 저널에서 가장 나쁜 결함이다.\n */\n\n/** 승격된 검색 키 — 전부 선택적. 뽑히지 않으면 **빈 문자열이 아니라 undefined**(결측≠빈값). */\nexport interface TwinEventKeys {\n  action?: string\n  bizStep?: string\n  epc?: string\n  orderId?: string\n  locationId?: string\n  moverId?: string\n}\n\n/*\n * 컬럼 길이 상한. GS1 식별자(EPC URN·GDTI·SGLN)는 규격상 이보다 훨씬 짧다.\n * 넘치는 값이 오면 **알리지 않고 자르지 않고** 경고를 남긴다 — 색인이 원본과 다르면 검색 결과가 거짓이 되는데,\n * 그 사실이 어디에도 안 남으면 아무도 모른다.\n */\nconst MAX_KEY = 255\n\nfunction clip(v: unknown, field: string): string | undefined {\n  if (v === undefined || v === null) return undefined\n  const s = String(v)\n  if (!s) return undefined\n  if (s.length <= MAX_KEY) return s\n  twinWarn(\n    `[twin-event-keys] ${field} exceeds ${MAX_KEY} chars and was clipped for indexing — ` +\n      `search on this value may be incomplete. payload keeps the full value. (${s.slice(0, 60)}…)`\n  )\n  return s.slice(0, MAX_KEY)\n}\n\n/** CBV bizStep URN 의 끝마디. 없으면 이벤트 타입에서 유추(`epcis.` 접두 제거). */\nexport function bizStepOf(envelope: any): string | undefined {\n  const d = envelope?.data ?? envelope ?? {}\n  const tail = String(d.bizStep ?? '').split(':').pop()\n  return tail || String(envelope?.eventType ?? '').replace('epcis.', '') || undefined\n}\n\n/**\n * 품목 식별자 — **전체 값**을 저장한다(끝마디만 저장하지 않는다).\n *\n * 표시용 축약은 화면이 하고, 색인은 원본을 갖는다. `search` 는 부분일치(contains)라\n * 전체를 저장해 두면 끝마디(\"402.2\")로도 URN 전체로도 찾힌다. 반대로 끝마디만 저장하면\n * URN 으로 찾는 경로가 사라진다.\n */\nexport function epcOf(envelope: any): string | undefined {\n  const d = envelope?.data ?? envelope ?? {}\n  return d.epcList?.[0] ?? d.parentID ?? d.quantityList?.[0]?.epcClass ?? undefined\n}\n\n/**\n * 오더 식별자 — 운영 델타의 `orderId` 우선, EPCIS 는 `bizTransactionList`.\n *\n * ── 실측 (2026-08-24) — 이 컬럼이 **전부 비어 있었다** ──────────────────────\n * 여기가 찾던 이름이 `d.order` 였다. 그런데 커널이 내는 이름은 **`orderId`** 다\n * (`OrderStatusDelta.orderId` · `TaskStatusDelta.orderId`). `d.order` 를 내는 코드는 커널에 **한 곳도\n * 없다** — 죽은 가지였다. 그래서 운영 델타는 이 컬럼을 한 번도 채우지 못했다.\n *\n *   order.status   29,403,565 행 — order_id 비어 있음 29,403,565 (100%)\n *   task.status       191,175 행 — 비어 있음 191,175 (100%)\n *\n * 그 결과 색인 `ix_twin_event_4` 가 **자기 주석이 적어 둔 용도**(「이 오더가 어디까지 갔나」)로 쓸 수\n * 없었다. 화면은 오더를 눌러도 「연결된 이벤트가 없습니다」를 냈고, 그 답은 질의 결과로는 정직했다 —\n * 시점을 어디로 옮겨도 0 이었다.\n *\n * 순서가 중요하다: 운영 델타가 먼저다. EPCIS 의 `bizTransactionList` 는 **거래**(PO/SO)이고 오더와\n * 같은 것이 아닐 수 있으므로, 오더를 스스로 말하는 사건은 그 말을 그대로 쓴다.\n *\n * **과거 행은 채워지지 않는다**(사용자 결정 2026-08-24, `moverId` 때와 같은 방식). 앞으로 들어오는\n * 사건부터 조회된다.\n */\nexport function orderOf(envelope: any): string | undefined {\n  const d = envelope?.data ?? envelope ?? {}\n  return d.orderId ?? d.bizTransactionList?.[0]?.bizTransaction ?? undefined\n}\n\n/**\n * 위치 — EPCIS 는 읽은 지점(readPoint) 우선, 없으면 업무 위치(bizLocation).\n * 운영 델타(무버 이동 등)는 그 둘이 없고 평범한 `location` 을 쓴다 — 빠뜨리면 설비가 어디서\n * 무엇을 했는지가 위치 축에서 통째로 사라진다.\n */\nexport function locationOf(envelope: any): string | undefined {\n  const d = envelope?.data ?? envelope ?? {}\n  return d.readPoint?.id ?? d.bizLocation?.id ?? d.location ?? undefined\n}\n\n/**\n * 설비·무버 — 운영 델타(equipment.status·task.status)가 대상을 가리키는 축.\n *\n * EPCIS 어휘가 아니라서 다른 축 어디에도 안 잡힌다. 이게 없으면 \"이 지게차가 오늘 무엇을 했나\" 를\n * 서버에서 물을 방법이 없어, 화면이 저널을 통째로 받아 전수 조회하는 수밖에 없다.\n */\nexport function equipmentIdOf(envelope: any): string | undefined {\n  const d = envelope?.data ?? envelope ?? {}\n  /*\n   * ── 실측 (2026-08-24) — 두 갈래를 놓치고 있었다 ────────────────────────────\n   * 위 주석이 `task.status` 를 출처로 **적어 두었는데** 이 함수는 `d.moverId` 만 봤다. 작업이 자원을\n   * 가리키는 이름은 `resourceRef` 다(`TaskStatusDelta.resourceRef`) — 그래서 작업 191,175 행 전부\n   * 이 컬럼이 비었고, 「이 지게차가 오늘 무엇을 했나」에서 **작업이 통째로 빠졌다.**\n   *\n   * 그리고 에너지 사건은 `equipmentId` 를 쓴다(어휘가 `movers`→`equipment` 로 개명된 뒤에 생긴\n   * 채널이다). 실측 `energy.equipment` 31,079 행 전부 비어 있었다 — 「이 설비가 얼마를 먹었나」를\n   * 설비 축으로 물을 수 없었다.\n   *\n   * 셋을 함께 본다. 개명 세대가 섞여 있는 것은 저널의 성질이고, 읽는 쪽이 그것을 흡수한다.\n   */\n  return d.moverId ?? d.resourceRef ?? d.equipmentId ?? undefined\n}\n\n/**\n * EPCIS 행위 — `ADD`·`OBSERVE`·`DELETE`. 세 값이 아니면 `undefined`(원천의 잡값을 색인에 넣지 않는다).\n *\n * 이 키는 검색 축이 아니라 **판별식**이다: 되풀어 읽는 스냅샷은 원리적으로 `DELETE` 를 못 낸다.\n * 그래서 「이 트윈이 반출을 한 번이라도 계산했는가」가 진짜 delta 피드의 증거인데, payload 안에 있는\n * 동안에는 5개 드라이버 어디에서도 그 질문을 할 수 없었다. 운영 델타에는 행위가 없다 — 비운다.\n */\nexport function actionOf(envelope: any): string | undefined {\n  const a = (envelope?.data ?? envelope ?? {}).action\n  return a === 'ADD' || a === 'OBSERVE' || a === 'DELETE' ? a : undefined\n}\n\n/** 한 이벤트에서 승격 키 전부 — 기록 경로가 이 함수 하나만 부른다. */\nexport function twinEventKeys(envelope: any): TwinEventKeys {\n  return {\n    action: actionOf(envelope),\n    bizStep: clip(bizStepOf(envelope), 'bizStep'),\n    epc: clip(epcOf(envelope), 'epc'),\n    orderId: clip(orderOf(envelope), 'orderId'),\n    locationId: clip(locationOf(envelope), 'locationId'),\n    moverId: clip(equipmentIdOf(envelope), 'moverId')\n  }\n}\n"]}
+{"version":3,"file":"twin-event-keys.js","sourceRoot":"","sources":["../../../server/service/twin-event/twin-event-keys.ts"],"names":[],"mappings":"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","sourcesContent":["import { twinWarn } from '../../engine/log.js'\n/*\n * 저널 검색 키 추출 — **순수**. 인제스트가 기록할 때 한 번 뽑아 인덱스 가능한 실컬럼으로 승격한다.\n *\n * ── 왜 승격하는가 ───────────────────────────────────────────────────────────\n * 사용자가 저널에서 실제로 찾는 것은 \"이 팔레트의 이력\", \"이 오더가 어디까지 갔나\", \"이 도크에서\n * 무슨 일이 있었나\" 다. 그런데 그 값들은 전부 `payload`(simple-json = TEXT) **안**에 있었다.\n * things-factory 는 5개 DB 드라이버를 지원해야 해서 DB별 JSON 연산자를 쓸 수 없다 —\n * 즉 승격 없이는 **어떤 방법으로도 서버에서 그 조건으로 거를 수 없었다**. 클라이언트가 받아온\n * 몇 천 건 안에서만 찾는 시늉이 최선이었고, 저널이 커질수록 그 시늉은 거짓말에 가까워진다.\n *\n * 그래서 검색 축이 되는 값만 골라 컬럼으로 꺼낸다. payload 는 그대로 둔다(정본은 여전히 payload —\n * 이건 파생 색인이지 새로운 진실이 아니다).\n *\n * ── 왜 여기(순수 모듈)인가 ──────────────────────────────────────────────────\n * 기록 경로가 둘이다(`persistBatch` 라이브 벌크 · `persist` 심 단건). 두 곳에 각자 적으면\n * 반드시 어긋나고, 어긋난 색인은 \"없는 것처럼 보이는 이벤트\" 를 만든다 — 저널에서 가장 나쁜 결함이다.\n */\n\n/** 승격된 검색 키 — 전부 선택적. 뽑히지 않으면 **빈 문자열이 아니라 undefined**(결측≠빈값). */\nexport interface TwinEventKeys {\n  action?: string\n  bizStep?: string\n  epc?: string\n  orderId?: string\n  bizTransaction?: string\n  locationId?: string\n  moverId?: string\n}\n\n/*\n * 컬럼 길이 상한. GS1 식별자(EPC URN·GDTI·SGLN)는 규격상 이보다 훨씬 짧다.\n * 넘치는 값이 오면 **알리지 않고 자르지 않고** 경고를 남긴다 — 색인이 원본과 다르면 검색 결과가 거짓이 되는데,\n * 그 사실이 어디에도 안 남으면 아무도 모른다.\n */\nconst MAX_KEY = 255\n\nfunction clip(v: unknown, field: string): string | undefined {\n  if (v === undefined || v === null) return undefined\n  const s = String(v)\n  if (!s) return undefined\n  if (s.length <= MAX_KEY) return s\n  twinWarn(\n    `[twin-event-keys] ${field} exceeds ${MAX_KEY} chars and was clipped for indexing — ` +\n      `search on this value may be incomplete. payload keeps the full value. (${s.slice(0, 60)}…)`\n  )\n  return s.slice(0, MAX_KEY)\n}\n\n/** CBV bizStep URN 의 끝마디. 없으면 이벤트 타입에서 유추(`epcis.` 접두 제거). */\nexport function bizStepOf(envelope: any): string | undefined {\n  const d = envelope?.data ?? envelope ?? {}\n  const tail = String(d.bizStep ?? '').split(':').pop()\n  return tail || String(envelope?.eventType ?? '').replace('epcis.', '') || undefined\n}\n\n/**\n * 품목 식별자 — **전체 값**을 저장한다(끝마디만 저장하지 않는다).\n *\n * 표시용 축약은 화면이 하고, 색인은 원본을 갖는다. `search` 는 부분일치(contains)라\n * 전체를 저장해 두면 끝마디(\"402.2\")로도 URN 전체로도 찾힌다. 반대로 끝마디만 저장하면\n * URN 으로 찾는 경로가 사라진다.\n */\nexport function epcOf(envelope: any): string | undefined {\n  const d = envelope?.data ?? envelope ?? {}\n  return d.epcList?.[0] ?? d.parentID ?? d.quantityList?.[0]?.epcClass ?? undefined\n}\n\n/**\n * 오더 식별자 — 운영 델타의 `orderId` 우선, EPCIS 는 `bizTransactionList`.\n *\n * ── 실측 (2026-08-24) — 이 컬럼이 **전부 비어 있었다** ──────────────────────\n * 여기가 찾던 이름이 `d.order` 였다. 그런데 커널이 내는 이름은 **`orderId`** 다\n * (`OrderStatusDelta.orderId` · `TaskStatusDelta.orderId`). `d.order` 를 내는 코드는 커널에 **한 곳도\n * 없다** — 죽은 가지였다. 그래서 운영 델타는 이 컬럼을 한 번도 채우지 못했다.\n *\n *   order.status   29,403,565 행 — order_id 비어 있음 29,403,565 (100%)\n *   task.status       191,175 행 — 비어 있음 191,175 (100%)\n *\n * 그 결과 색인 `ix_twin_event_4` 가 **자기 주석이 적어 둔 용도**(「이 오더가 어디까지 갔나」)로 쓸 수\n * 없었다. 화면은 오더를 눌러도 「연결된 이벤트가 없습니다」를 냈고, 그 답은 질의 결과로는 정직했다 —\n * 시점을 어디로 옮겨도 0 이었다.\n *\n * **과거 행은 채워지지 않는다**(사용자 결정 2026-08-24, `moverId` 때와 같은 방식). 앞으로 들어오는\n * 사건부터 조회된다.\n *\n * ── 한 칸에 두 낱말이 들어 있었다 (2026-09-05 실측) ────────────────────────\n * 위 주석이 이미 알고 있었다 — 「EPCIS 의 `bizTransactionList` 는 **거래**(PO/SO)이고 오더와 같은\n * 것이 아닐 수 있다」. 그런데 그 둘을 **같은 칸에** 넣고 있었다. 그래서 이렇게 됐다.\n *\n *   order.status                order-1                          내부 오더 id\n *   epcis.TransformationEvent   urn:epc:id:gdti:9521321.403.1    GS1 거래 식별자\n *   epcis.TransactionEvent      urn:epc:id:gdti:9521321.403.1\n *\n * 한 오더의 이력이 **색인 안에서 두 쪽으로 갈라진다.** 어느 이름으로 물어도 절반만 나오고,\n * 오류는 나지 않는다. 실측: 어휘가 섞인 행 10,004개.\n *\n * 이것이 실제로 막은 것 — 「이 개체를 어느 레시피로 만들었나」다. 답은 기록되어 있다(오더 사건이\n * `recipeKey` 를 든다, 실측 328,021/328,021 = 100%). 변환 사건은 그 오더를 GDTI 로 가리키는데\n * 오더 사건은 `order-1` 로 적혀 있어 **색인으로 이을 수가 없었다.**\n *\n * 그래서 칸을 갈랐다(사용자 결정 2026-09-05).\n *\n *   orderId          내부 오더 id — 읽기 모델의 이음쇠\n *   bizTransaction   GS1 거래 식별자 — 표준이 말하는 그 거래\n *\n * 오더 사건은 **둘 다** 든다(`order.status` 의 payload 에 `orderId` 와 `bizTransaction` 이 함께\n * 있다). 그래서 EPCIS 사건의 거래 식별자로 오더를 찾을 수 있다 — 이 두 칸이 그 다리다.\n */\nexport function orderOf(envelope: any): string | undefined {\n  const d = envelope?.data ?? envelope ?? {}\n  return d.orderId ?? undefined\n}\n\n/**\n * **그 사건이 가리키는 거래** — EPCIS `bizTransactionList` 의 첫 항목, 또는 운영 델타가 직접 든 값.\n *\n * 오더가 아니다. 표준이 말하는 거래(PO/SO/생산오더)이고, 한 오더가 여러 거래에 걸릴 수도 있다.\n * 그 구별을 지키려고 `orderId` 와 갈라 두었다 — 합치면 위 주석의 그 일이 다시 난다.\n */\nexport function bizTransactionOf(envelope: any): string | undefined {\n  const d = envelope?.data ?? envelope ?? {}\n  return d.bizTransactionList?.[0]?.bizTransaction ?? d.bizTransaction ?? undefined\n}\n\n/**\n * 위치 — EPCIS 는 읽은 지점(readPoint) 우선, 없으면 업무 위치(bizLocation).\n * 운영 델타(무버 이동 등)는 그 둘이 없고 평범한 `location` 을 쓴다 — 빠뜨리면 설비가 어디서\n * 무엇을 했는지가 위치 축에서 통째로 사라진다.\n */\nexport function locationOf(envelope: any): string | undefined {\n  const d = envelope?.data ?? envelope ?? {}\n  return d.readPoint?.id ?? d.bizLocation?.id ?? d.location ?? undefined\n}\n\n/**\n * 설비·무버 — 운영 델타(equipment.status·task.status)가 대상을 가리키는 축.\n *\n * EPCIS 어휘가 아니라서 다른 축 어디에도 안 잡힌다. 이게 없으면 \"이 지게차가 오늘 무엇을 했나\" 를\n * 서버에서 물을 방법이 없어, 화면이 저널을 통째로 받아 전수 조회하는 수밖에 없다.\n */\nexport function equipmentIdOf(envelope: any): string | undefined {\n  const d = envelope?.data ?? envelope ?? {}\n  /*\n   * ── 실측 (2026-08-24) — 두 갈래를 놓치고 있었다 ────────────────────────────\n   * 위 주석이 `task.status` 를 출처로 **적어 두었는데** 이 함수는 `d.moverId` 만 봤다. 작업이 자원을\n   * 가리키는 이름은 `resourceRef` 다(`TaskStatusDelta.resourceRef`) — 그래서 작업 191,175 행 전부\n   * 이 컬럼이 비었고, 「이 지게차가 오늘 무엇을 했나」에서 **작업이 통째로 빠졌다.**\n   *\n   * 그리고 에너지 사건은 `equipmentId` 를 쓴다(어휘가 `movers`→`equipment` 로 개명된 뒤에 생긴\n   * 채널이다). 실측 `energy.equipment` 31,079 행 전부 비어 있었다 — 「이 설비가 얼마를 먹었나」를\n   * 설비 축으로 물을 수 없었다.\n   *\n   * 셋을 함께 본다. 개명 세대가 섞여 있는 것은 저널의 성질이고, 읽는 쪽이 그것을 흡수한다.\n   */\n  return d.moverId ?? d.resourceRef ?? d.equipmentId ?? undefined\n}\n\n/**\n * EPCIS 행위 — `ADD`·`OBSERVE`·`DELETE`. 세 값이 아니면 `undefined`(원천의 잡값을 색인에 넣지 않는다).\n *\n * 이 키는 검색 축이 아니라 **판별식**이다: 되풀어 읽는 스냅샷은 원리적으로 `DELETE` 를 못 낸다.\n * 그래서 「이 트윈이 반출을 한 번이라도 계산했는가」가 진짜 delta 피드의 증거인데, payload 안에 있는\n * 동안에는 5개 드라이버 어디에서도 그 질문을 할 수 없었다. 운영 델타에는 행위가 없다 — 비운다.\n */\nexport function actionOf(envelope: any): string | undefined {\n  const a = (envelope?.data ?? envelope ?? {}).action\n  return a === 'ADD' || a === 'OBSERVE' || a === 'DELETE' ? a : undefined\n}\n\n/** 한 이벤트에서 승격 키 전부 — 기록 경로가 이 함수 하나만 부른다. */\nexport function twinEventKeys(envelope: any): TwinEventKeys {\n  return {\n    action: actionOf(envelope),\n    bizStep: clip(bizStepOf(envelope), 'bizStep'),\n    epc: clip(epcOf(envelope), 'epc'),\n    orderId: clip(orderOf(envelope), 'orderId'),\n    bizTransaction: clip(bizTransactionOf(envelope), 'bizTransaction'),\n    locationId: clip(locationOf(envelope), 'locationId'),\n    moverId: clip(equipmentIdOf(envelope), 'moverId')\n  }\n}\n"]}

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

@@ -32,6 +32,7 @@ export declare class TwinEvent {
     bizStep?: string;
     epc?: string;
     orderId?: string;
+    bizTransaction?: string;
     locationId?: string;
     moverId?: string;
     payload?: any;

package/dist-server/service/twin-event/twin-event.js

@@ -22,6 +22,7 @@ const shell_1 = require("@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) 로 이미 좁혀진 뒤의 잔여 필터로
@@ -121,9 +122,14 @@ tslib_1.__decorate([
 ], TwinEvent.prototype, "epc", void 0);
 tslib_1.__decorate([
     (0, typeorm_1.Column)({ length: 255, nullable: true }),
-    (0, type_graphql_1.Field)({ nullable: true, description: 'Business transaction identifier (PO / SO), promoted from the payload for indexed lookup of one order history.' }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'Internal order identifier, promoted from the payload for indexed lookup of one order history.' }),
     tslib_1.__metadata("design:type", String)
 ], TwinEvent.prototype, "orderId", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ length: 255, nullable: true }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'Business transaction identifier (PO / SO / production order), promoted from the payload for indexed lookup of one transaction.' }),
+    tslib_1.__metadata("design:type", String)
+], TwinEvent.prototype, "bizTransaction", void 0);
 tslib_1.__decorate([
     (0, typeorm_1.Column)({ length: 255, nullable: true }),
     (0, type_graphql_1.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.' }),
@@ -184,7 +190,10 @@ exports.TwinEvent = TwinEvent = tslib_1.__decorate([
      * 정리는 한 창에 2초만 쓰도록 예산이 걸려 있어서, 그 2초를 주사에 다 쓰고 44건만 지우고 멈췄다.
      */
     ,
-    (0, typeorm_1.Index)('ix_twin_event_8', (e) => [e.domain, e.instanceId, e.createdAt], { unique: false }),
+    (0, typeorm_1.Index)('ix_twin_event_8', (e) => [e.domain, e.instanceId, e.createdAt], { unique: false })
+    /* ix_9 — "이 거래에 무슨 일이 있었나". EPCIS 사건에서 오더로 건너가는 다리(§`bizTransaction`). */
+    ,
+    (0, typeorm_1.Index)('ix_twin_event_9', (e) => [e.domain, e.instanceId, e.bizTransaction], { unique: false }),
     (0, type_graphql_1.ObjectType)({ description: 'Append-only twin event journal record (EPCIS event or operational delta).' })
 ], TwinEvent);
 //# sourceMappingURL=twin-event.js.map

package/dist-server/service/twin-event/twin-event.js.map

@@ -1 +1 @@
-{"version":3,"file":"twin-event.js","sourceRoot":"","sources":["../../../server/service/twin-event/twin-event.ts"],"names":[],"mappings":"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","sourcesContent":["import { CreateDateColumn, Entity, Index, Column, RelationId, ManyToOne, PrimaryGeneratedColumn } from 'typeorm'\nimport { ObjectType, Field, ID, Int } from 'type-graphql'\n\nimport { Domain, ScalarObject } from '@things-factory/shell'\n\n/*\n * TwinEvent — append-only 트윈 이벤트 저널(EPCIS 이벤트 + 운영 델타).\n * 커널 EventJournal 의 영속 대응 — 상태=이벤트열의 함수(재부팅 시 DB→replay 재구성).\n * append-only 이므로 updater/deletedAt 없음(이력 CRUD 가 아니라 불변 이벤트 스트림).\n * payload 는 simple-json(멀티DB 이식 — postgres/mysql/sqlite/mssql/oracle 공통, DB-specific JSON 타입 금지).\n * (CLAUDE.md: 모든 @ObjectType/@Field 는 영문 description 필수.)\n */\n/*\n * ── 인덱스 설계 (2026-07-31) ────────────────────────────────────────────────\n * 이 표는 **인제스트 경로의 뜨거운 append-only 테이블**이다. 인덱스 하나하나가 쓰기 증폭이므로\n * \"있으면 좋을\" 인덱스를 붙이지 않는다. 실제 질의 패턴에 대응하는 것만 둔다.\n *\n *  ix_0 (domain, instanceId, revision)            원장 기본 정렬·커서 페이징·replay(ASC 주사)\n *  ix_1 (domain, instanceId, eventTime)           시각 커서(untilTime)·시간창 KPI — 거의 모든 조회가 탄다\n *  ix_2 (domain, instanceId, eventType, revision) 타입 필터 + 정렬 동시 충족(스케줄 화면 task/equipment)\n *  ix_3 (domain, instanceId, epc)                 \"이 물건의 이력\" — Entity360 의 본질 질문\n *  ix_4 (domain, instanceId, orderId)             \"이 오더가 어디까지 갔나\"\n *\n * bizStep·locationId·moverId 는 컬럼만 두고 인덱스는 두지 않는다 — 한 트윈 안에서 카디널리티가\n * 낮아(업무단계 몇 개, 위치 수백, 설비 수십) (domain,instanceId) 로 이미 좁혀진 뒤의 잔여 필터로\n * 충분하고, 뜨거운 표에 인덱스를 더 얹을 가치가 없다. 저널 하나가 아주 커져서 이 축들의 조회가\n * 느려지면 그때 측정을 근거로 인덱스를 추가할 일이지, 지레 얹어 쓰기를 무겁게 할 일은 아니다.\n */\n@Entity()\n@Index('ix_twin_event_0', (e: TwinEvent) => [e.domain, e.instanceId, e.revision], { unique: false })\n@Index('ix_twin_event_1', (e: TwinEvent) => [e.domain, e.instanceId, e.eventTime], { unique: false })\n@Index('ix_twin_event_2', (e: TwinEvent) => [e.domain, e.instanceId, e.eventType, e.revision], { unique: false })\n@Index('ix_twin_event_3', (e: TwinEvent) => [e.domain, e.instanceId, e.epc], { unique: false })\n@Index('ix_twin_event_4', (e: TwinEvent) => [e.domain, e.instanceId, e.orderId], { unique: false })\n/* ix_5 — \"이 지시가 무엇을 일으켰나\". 감사 기록의 commandId 로 저널을 다시 계산하는 축. */\n@Index('ix_twin_event_5', (e: TwinEvent) => [e.domain, e.correlationId], { unique: false })\n/* ix_6 — \"반출을 한 번이라도 계산했나\". 없으면 그 질문이 인스턴스 저널 전량 주사가 된다. */\n@Index('ix_twin_event_6', (e: TwinEvent) => [e.domain, e.instanceId, e.action], { unique: false })\n/*\n * ix_7 — **\"이 종류의 사실을 시각순으로\"** (2026-08-25 실측으로 추가)\n *\n * 이 축이 없어서 공정 타임라인이 22초였다. 종류로 거르고 시각으로 정렬하는 조회가 갈 곳이 없었다:\n *\n *   ix_2 (…, eventType, revision)   종류는 걸러지고 정렬이 **적힌 순서**다 → 4월 사실을 최근으로 그렸다\n *   ix_1 (…, eventTime)             정렬은 맞고 **종류를 못 거른다** → 행마다 테이블을 열어 확인한다\n *\n * 뒤쪽으로 걸으면 그 트윈에서 찾는 종류가 멈춘 시점까지의 모든 행을 읽고 버린다. 승화푸드에서 작업\n * 사실은 8월 22일에 멈춰 있고 그 뒤로 리비전이 110만 늘었으므로, 200건에 닿기까지 110만 행을 열었다.\n *\n * 위 주석이 「측정을 근거로 추가할 일이지 지레 얹을 일은 아니다」라고 적어 두었다. 그 측정이 나왔다.\n */\n@Index('ix_twin_event_7', (e: TwinEvent) => [e.domain, e.instanceId, e.eventType, e.eventTime], { unique: false })\n/*\n * ix_8 — **\"이 트윈의 오래된 기록\"** (2026-08-27 실측으로 추가)\n *\n * 보관 기간 정리가 `created_at` 으로 자르는데(보관은 저장 나이의 문제다) 그 축에 인덱스가 없었다.\n * 그래서 정리가 매 배치마다 그 트윈의 저널을 전량 주사했다.\n *\n *   hatio-mx2 의 7일 밖 행을 세기      208초   ← 1,029만 행을 전부 읽는다(7일 밖은 2,446건뿐이다)\n *   revision 으로 한 행 짚기           0.004초\n *\n * 정리는 한 창에 2초만 쓰도록 예산이 걸려 있어서, 그 2초를 주사에 다 쓰고 44건만 지우고 멈췄다.\n */\n@Index('ix_twin_event_8', (e: TwinEvent) => [e.domain, e.instanceId, e.createdAt], { unique: false })\n@ObjectType({ description: 'Append-only twin event journal record (EPCIS event or operational delta).' })\nexport class TwinEvent {\n  @PrimaryGeneratedColumn('uuid')\n  @Field(type => ID, { description: 'Unique identifier of the event record.' })\n  readonly id: string\n\n  @ManyToOne(type => Domain)\n  @Field(type => Domain, { nullable: true, description: 'Owning tenant domain.' })\n  domain?: Domain\n\n  @RelationId((e: TwinEvent) => e.domain)\n  domainId?: string\n\n  /*\n   * 이 사실을 낸 트윈. **빌 수 없다** — 저널 행을 만드는 곳은 `journalRow` 하나뿐이고 거기서\n   * 필수 인자로 받는다. nullable 로 두면 읽는 쪽이 매번 `?? ''` 를 달게 되고, 그 방어가 실제로는\n   * 일어나지 않는 경우를 대비하느라 \"빈 인스턴스의 이벤트\" 라는 없는 개념을 코드에 남긴다.\n   */\n  @Column()\n  @Field({ description: 'Twin runtime instance id that emitted the event.' })\n  instanceId: string\n\n  /* 커널 봉투의 필수 필드(`CanonicalEnvelope.eventType`)라 빌 수 없다 — 계약을 그대로 옮긴다. */\n  @Column()\n  @Field({ description: 'Event type: epcis.* | task.status | equipment.status | order.status.' })\n  eventType: string\n\n  @Column({ type: 'int', nullable: true })\n  @Field(type => Int, { nullable: true, description: 'Monotonic state revision at which the event was emitted.' })\n  revision?: number\n\n  /**\n   * 이 사실이 **어느 공장에서** 일어났나 — `TwinStructure.rev`.\n   *\n   * 이것이 없던 시절에는 구조가 바뀌면 저널을 통째로 지우는 것이 유일한 길이었다(안 지우면 옛\n   * 이벤트를 새 공장에 대고 계산해 이력이 거짓말을 한다). 이 한 칸이 셋째 길을 연다 — 재생이\n   * 구조가 바뀌는 지점에서 전환한 뒤 이어서 계산한다.\n   *\n   * **비어 있을 수 있다**: 컬럼이 생기기 전에 쓰인 행이다. 그 행들은 **가장 오래된 리비전**에\n   * 속한다(0 을 채워 넣지 않는다 — 0 은 \"모름\" 이 아니라 유효한 번호처럼 보인다).\n   */\n  @Column({ type: 'int', nullable: true })\n  @Field(type => Int, { nullable: true, description: 'Structure revision (TwinStructure.rev) in force when this event happened. Absent on rows written before structure revisions existed; those belong to the oldest revision.' })\n  structureRev?: number\n\n  /*\n   * 이 사실이 일어난 시각(트윈의 시계). **날짜 타입이다.**\n   *\n   * 예전에는 문자열이었다. 읽을 때마다 `Date.parse` 했고, 정렬은 UTC ISO 만 들어온다는 전제 위에서\n   * 사전식 비교가 우연히 맞았다 — `+09:00` 오프셋 표기가 하나 섞이면 알리지 않고 순서가 틀린다.\n   * 그 전제는 컬럼 어디에도 적혀 있지 않았다.\n   *\n   * **타입 이름을 적지 않는다** (2026-08-19 Postgres 부팅 실패로 고침).\n   *\n   * `datetime` 을 적었더니 Postgres 가 부팅 중에 거절했다(`DataTypeNotSupportedError`) — 그 이름은\n   * sqlite·MySQL 의 것이고 Postgres 는 `timestamp` 만 안다. 거꾸로 `timestamp` 는 sqlite 가 모른다:\n   * **다섯 드라이버에 다 통하는 이름이 아예 없다.**\n   *\n   * 그래서 이름을 고르는 일을 TypeORM 에 맡긴다. `emitDecoratorMetadata` 가 켜져 있으므로 이 속성의\n   * TS 타입(`Date`)에서 드라이버별 타입을 스스로 고른다(Postgres `timestamp` · sqlite·MySQL `datetime`).\n   * 이 레포의 다중 DB 규약이 요구하는 것이 바로 그것이다 — 드라이버 방언을 코드에 적지 않는다.\n   */\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'Time at which the fact happened on the twin clock.' })\n  eventTime?: Date\n\n  /*\n   * ── 승격된 검색 축 ────────────────────────────────────────────────────────\n   * payload 안에 있던 값을 인제스트 시점에 꺼내 실컬럼으로 둔다(`twin-event-keys.ts` 가 단독 소유).\n   * payload 가 여전히 정본이고 이것들은 **파생 색인**이다 — 새로운 진실이 아니라 찾을 수 있게 하는 장치.\n   * simple-json(TEXT) 안의 값은 5개 DB 드라이버 공통으로 거를 방법이 없어서(멀티DB 호환 규칙상\n   * DB별 JSON 연산자 금지) 승격 외의 선택지가 없다.\n   * 길이 상한 255 는 GS1 식별자 규격 대비 충분하며, 넘치는 값은 알리지 않고 잘리지 않고 경고를 남긴다.\n   *\n   * ── 축을 새로 추가할 때 ──────────────────────────────────────────────────\n   * 새 승격 컬럼을 만들면 **이미 쌓인 행은 비어 있다.** 그 행들은 새 축으로 검색되지 않고,\n   * 사용자에게는 \"과거가 없는 것\" 으로 보인다(알리지 않고 빠진 데이터).\n   *\n   * 예전에는 기동 훅이 매번 테이블을 살펴 채웠다. 그건 두 가지로 틀렸다 — 저널이 커질수록 부팅이\n   * 느려지고, \"bizStep 이 비었으면 옛 행\" 이라는 전제를 코드에 고정해 그 전제가 깨지는 순간\n   * (감사 행처럼 업무 단계가 없는 행) 매 부팅마다 헛돌았다. 그래서 걷어냈다(git: backfill-keys.ts).\n   *\n   * 채우는 일은 **마이그레이션 한 번**이 맞다(`yarn migration`). 그 컬럼에 맞는 것을 그때 쓴다 —\n   * 범용 스캐너를 되살리지 말 것. 개발 데이타라면 그냥 버리는 것도 답이다.\n   */\n  /**\n   * 이 사실을 일으킨 **지시** — 커널이 커맨드에서 이어 준 상관값(기본은 commandId).\n   *\n   * 이것이 감사 기록(TwinAuditEvent.commandId)과 저널을 잇는 유일한 다리다. 없으면 승인 기록은\n   * \"사람이 허락했다\" 까지이고, 그 뒤 공장이 실제로 어떻게 움직였는지와 이어지지 않는다.\n   *\n   * **대부분의 행은 비어 있다** — 커맨드가 아니라 시뮬 시간이 낳은 사실이기 때문이다. 그것이 정상이고,\n   * 비어 있다고 \"덜 채워진 옛 행\" 으로 보면 안 된다(같은 오해를 bizStep 에서 이미 한 번 했다).\n   */\n  @Column({ length: 255, nullable: true })\n  @Field({ nullable: true, description: 'Id of the command that caused this fact (kernel correlation id; defaults to the commandId). Empty for facts that simulation time produced rather than a command.' })\n  correlationId?: string\n\n  /* 옛 행은 비어 있다 — 승격 전에 기록된 것이라 **모른다**(0 이나 OBSERVE 로 위장하지 않는다). */\n  @Column({ length: 16, nullable: true })\n  @Field({ nullable: true, description: 'EPCIS action (ADD / OBSERVE / DELETE), promoted from the payload. Empty for operational deltas, and for rows journaled before this column existed.' })\n  action?: string\n\n  @Column({ length: 255, nullable: true })\n  @Field({ nullable: true, description: 'Business step (CBV bizStep tail), promoted from the payload for indexed filtering.' })\n  bizStep?: string\n\n  @Column({ length: 255, nullable: true })\n  @Field({ nullable: true, description: 'Item identifier (EPC / EPC class / parent id), promoted from the payload for indexed lookup of one item history.' })\n  epc?: string\n\n  @Column({ length: 255, nullable: true })\n  @Field({ nullable: true, description: 'Business transaction identifier (PO / SO), promoted from the payload for indexed lookup of one order history.' })\n  orderId?: string\n\n  @Column({ length: 255, nullable: true })\n  @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.' })\n  locationId?: string\n\n  @Column({ length: 255, nullable: true })\n  @Field({ nullable: true, description: 'Equipment identifier carried by operational deltas, promoted from the payload so one machine history can be asked for on the server. The column keeps the legacy name `moverId`: the journal is append-only history and mixing two names for the same fact across time is worse than an outdated name. Renaming belongs with event-schema versioning.' })\n  moverId?: string\n\n  @Column({ type: 'simple-json', nullable: true })\n  @Field(type => ScalarObject, { nullable: true, description: 'Raw canonical envelope (EPCIS event or operational delta) as JSON.' })\n  payload?: any\n\n  @CreateDateColumn()\n  @Field({ nullable: true, description: 'Wall-clock timestamp when the record was persisted.' })\n  createdAt?: Date\n}\n"]}
+{"version":3,"file":"twin-event.js","sourceRoot":"","sources":["../../../server/service/twin-event/twin-event.ts"],"names":[],"mappings":"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","sourcesContent":["import { CreateDateColumn, Entity, Index, Column, RelationId, ManyToOne, PrimaryGeneratedColumn } from 'typeorm'\nimport { ObjectType, Field, ID, Int } from 'type-graphql'\n\nimport { Domain, ScalarObject } from '@things-factory/shell'\n\n/*\n * TwinEvent — append-only 트윈 이벤트 저널(EPCIS 이벤트 + 운영 델타).\n * 커널 EventJournal 의 영속 대응 — 상태=이벤트열의 함수(재부팅 시 DB→replay 재구성).\n * append-only 이므로 updater/deletedAt 없음(이력 CRUD 가 아니라 불변 이벤트 스트림).\n * payload 는 simple-json(멀티DB 이식 — postgres/mysql/sqlite/mssql/oracle 공통, DB-specific JSON 타입 금지).\n * (CLAUDE.md: 모든 @ObjectType/@Field 는 영문 description 필수.)\n */\n/*\n * ── 인덱스 설계 (2026-07-31) ────────────────────────────────────────────────\n * 이 표는 **인제스트 경로의 뜨거운 append-only 테이블**이다. 인덱스 하나하나가 쓰기 증폭이므로\n * \"있으면 좋을\" 인덱스를 붙이지 않는다. 실제 질의 패턴에 대응하는 것만 둔다.\n *\n *  ix_0 (domain, instanceId, revision)            원장 기본 정렬·커서 페이징·replay(ASC 주사)\n *  ix_1 (domain, instanceId, eventTime)           시각 커서(untilTime)·시간창 KPI — 거의 모든 조회가 탄다\n *  ix_2 (domain, instanceId, eventType, revision) 타입 필터 + 정렬 동시 충족(스케줄 화면 task/equipment)\n *  ix_3 (domain, instanceId, epc)                 \"이 물건의 이력\" — Entity360 의 본질 질문\n *  ix_4 (domain, instanceId, orderId)             \"이 오더가 어디까지 갔나\"\n *  ix_9 (domain, instanceId, bizTransaction)      \"이 거래에 무슨 일이 있었나\" — EPCIS↔오더의 다리\n *\n * bizStep·locationId·moverId 는 컬럼만 두고 인덱스는 두지 않는다 — 한 트윈 안에서 카디널리티가\n * 낮아(업무단계 몇 개, 위치 수백, 설비 수십) (domain,instanceId) 로 이미 좁혀진 뒤의 잔여 필터로\n * 충분하고, 뜨거운 표에 인덱스를 더 얹을 가치가 없다. 저널 하나가 아주 커져서 이 축들의 조회가\n * 느려지면 그때 측정을 근거로 인덱스를 추가할 일이지, 지레 얹어 쓰기를 무겁게 할 일은 아니다.\n */\n@Entity()\n@Index('ix_twin_event_0', (e: TwinEvent) => [e.domain, e.instanceId, e.revision], { unique: false })\n@Index('ix_twin_event_1', (e: TwinEvent) => [e.domain, e.instanceId, e.eventTime], { unique: false })\n@Index('ix_twin_event_2', (e: TwinEvent) => [e.domain, e.instanceId, e.eventType, e.revision], { unique: false })\n@Index('ix_twin_event_3', (e: TwinEvent) => [e.domain, e.instanceId, e.epc], { unique: false })\n@Index('ix_twin_event_4', (e: TwinEvent) => [e.domain, e.instanceId, e.orderId], { unique: false })\n/* ix_5 — \"이 지시가 무엇을 일으켰나\". 감사 기록의 commandId 로 저널을 다시 계산하는 축. */\n@Index('ix_twin_event_5', (e: TwinEvent) => [e.domain, e.correlationId], { unique: false })\n/* ix_6 — \"반출을 한 번이라도 계산했나\". 없으면 그 질문이 인스턴스 저널 전량 주사가 된다. */\n@Index('ix_twin_event_6', (e: TwinEvent) => [e.domain, e.instanceId, e.action], { unique: false })\n/*\n * ix_7 — **\"이 종류의 사실을 시각순으로\"** (2026-08-25 실측으로 추가)\n *\n * 이 축이 없어서 공정 타임라인이 22초였다. 종류로 거르고 시각으로 정렬하는 조회가 갈 곳이 없었다:\n *\n *   ix_2 (…, eventType, revision)   종류는 걸러지고 정렬이 **적힌 순서**다 → 4월 사실을 최근으로 그렸다\n *   ix_1 (…, eventTime)             정렬은 맞고 **종류를 못 거른다** → 행마다 테이블을 열어 확인한다\n *\n * 뒤쪽으로 걸으면 그 트윈에서 찾는 종류가 멈춘 시점까지의 모든 행을 읽고 버린다. 승화푸드에서 작업\n * 사실은 8월 22일에 멈춰 있고 그 뒤로 리비전이 110만 늘었으므로, 200건에 닿기까지 110만 행을 열었다.\n *\n * 위 주석이 「측정을 근거로 추가할 일이지 지레 얹을 일은 아니다」라고 적어 두었다. 그 측정이 나왔다.\n */\n@Index('ix_twin_event_7', (e: TwinEvent) => [e.domain, e.instanceId, e.eventType, e.eventTime], { unique: false })\n/*\n * ix_8 — **\"이 트윈의 오래된 기록\"** (2026-08-27 실측으로 추가)\n *\n * 보관 기간 정리가 `created_at` 으로 자르는데(보관은 저장 나이의 문제다) 그 축에 인덱스가 없었다.\n * 그래서 정리가 매 배치마다 그 트윈의 저널을 전량 주사했다.\n *\n *   hatio-mx2 의 7일 밖 행을 세기      208초   ← 1,029만 행을 전부 읽는다(7일 밖은 2,446건뿐이다)\n *   revision 으로 한 행 짚기           0.004초\n *\n * 정리는 한 창에 2초만 쓰도록 예산이 걸려 있어서, 그 2초를 주사에 다 쓰고 44건만 지우고 멈췄다.\n */\n@Index('ix_twin_event_8', (e: TwinEvent) => [e.domain, e.instanceId, e.createdAt], { unique: false })\n/* ix_9 — \"이 거래에 무슨 일이 있었나\". EPCIS 사건에서 오더로 건너가는 다리(§`bizTransaction`). */\n@Index('ix_twin_event_9', (e: TwinEvent) => [e.domain, e.instanceId, e.bizTransaction], { unique: false })\n@ObjectType({ description: 'Append-only twin event journal record (EPCIS event or operational delta).' })\nexport class TwinEvent {\n  @PrimaryGeneratedColumn('uuid')\n  @Field(type => ID, { description: 'Unique identifier of the event record.' })\n  readonly id: string\n\n  @ManyToOne(type => Domain)\n  @Field(type => Domain, { nullable: true, description: 'Owning tenant domain.' })\n  domain?: Domain\n\n  @RelationId((e: TwinEvent) => e.domain)\n  domainId?: string\n\n  /*\n   * 이 사실을 낸 트윈. **빌 수 없다** — 저널 행을 만드는 곳은 `journalRow` 하나뿐이고 거기서\n   * 필수 인자로 받는다. nullable 로 두면 읽는 쪽이 매번 `?? ''` 를 달게 되고, 그 방어가 실제로는\n   * 일어나지 않는 경우를 대비하느라 \"빈 인스턴스의 이벤트\" 라는 없는 개념을 코드에 남긴다.\n   */\n  @Column()\n  @Field({ description: 'Twin runtime instance id that emitted the event.' })\n  instanceId: string\n\n  /* 커널 봉투의 필수 필드(`CanonicalEnvelope.eventType`)라 빌 수 없다 — 계약을 그대로 옮긴다. */\n  @Column()\n  @Field({ description: 'Event type: epcis.* | task.status | equipment.status | order.status.' })\n  eventType: string\n\n  @Column({ type: 'int', nullable: true })\n  @Field(type => Int, { nullable: true, description: 'Monotonic state revision at which the event was emitted.' })\n  revision?: number\n\n  /**\n   * 이 사실이 **어느 공장에서** 일어났나 — `TwinStructure.rev`.\n   *\n   * 이것이 없던 시절에는 구조가 바뀌면 저널을 통째로 지우는 것이 유일한 길이었다(안 지우면 옛\n   * 이벤트를 새 공장에 대고 계산해 이력이 거짓말을 한다). 이 한 칸이 셋째 길을 연다 — 재생이\n   * 구조가 바뀌는 지점에서 전환한 뒤 이어서 계산한다.\n   *\n   * **비어 있을 수 있다**: 컬럼이 생기기 전에 쓰인 행이다. 그 행들은 **가장 오래된 리비전**에\n   * 속한다(0 을 채워 넣지 않는다 — 0 은 \"모름\" 이 아니라 유효한 번호처럼 보인다).\n   */\n  @Column({ type: 'int', nullable: true })\n  @Field(type => Int, { nullable: true, description: 'Structure revision (TwinStructure.rev) in force when this event happened. Absent on rows written before structure revisions existed; those belong to the oldest revision.' })\n  structureRev?: number\n\n  /*\n   * 이 사실이 일어난 시각(트윈의 시계). **날짜 타입이다.**\n   *\n   * 예전에는 문자열이었다. 읽을 때마다 `Date.parse` 했고, 정렬은 UTC ISO 만 들어온다는 전제 위에서\n   * 사전식 비교가 우연히 맞았다 — `+09:00` 오프셋 표기가 하나 섞이면 알리지 않고 순서가 틀린다.\n   * 그 전제는 컬럼 어디에도 적혀 있지 않았다.\n   *\n   * **타입 이름을 적지 않는다** (2026-08-19 Postgres 부팅 실패로 고침).\n   *\n   * `datetime` 을 적었더니 Postgres 가 부팅 중에 거절했다(`DataTypeNotSupportedError`) — 그 이름은\n   * sqlite·MySQL 의 것이고 Postgres 는 `timestamp` 만 안다. 거꾸로 `timestamp` 는 sqlite 가 모른다:\n   * **다섯 드라이버에 다 통하는 이름이 아예 없다.**\n   *\n   * 그래서 이름을 고르는 일을 TypeORM 에 맡긴다. `emitDecoratorMetadata` 가 켜져 있으므로 이 속성의\n   * TS 타입(`Date`)에서 드라이버별 타입을 스스로 고른다(Postgres `timestamp` · sqlite·MySQL `datetime`).\n   * 이 레포의 다중 DB 규약이 요구하는 것이 바로 그것이다 — 드라이버 방언을 코드에 적지 않는다.\n   */\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'Time at which the fact happened on the twin clock.' })\n  eventTime?: Date\n\n  /*\n   * ── 승격된 검색 축 ────────────────────────────────────────────────────────\n   * payload 안에 있던 값을 인제스트 시점에 꺼내 실컬럼으로 둔다(`twin-event-keys.ts` 가 단독 소유).\n   * payload 가 여전히 정본이고 이것들은 **파생 색인**이다 — 새로운 진실이 아니라 찾을 수 있게 하는 장치.\n   * simple-json(TEXT) 안의 값은 5개 DB 드라이버 공통으로 거를 방법이 없어서(멀티DB 호환 규칙상\n   * DB별 JSON 연산자 금지) 승격 외의 선택지가 없다.\n   * 길이 상한 255 는 GS1 식별자 규격 대비 충분하며, 넘치는 값은 알리지 않고 잘리지 않고 경고를 남긴다.\n   *\n   * ── 축을 새로 추가할 때 ──────────────────────────────────────────────────\n   * 새 승격 컬럼을 만들면 **이미 쌓인 행은 비어 있다.** 그 행들은 새 축으로 검색되지 않고,\n   * 사용자에게는 \"과거가 없는 것\" 으로 보인다(알리지 않고 빠진 데이터).\n   *\n   * 예전에는 기동 훅이 매번 테이블을 살펴 채웠다. 그건 두 가지로 틀렸다 — 저널이 커질수록 부팅이\n   * 느려지고, \"bizStep 이 비었으면 옛 행\" 이라는 전제를 코드에 고정해 그 전제가 깨지는 순간\n   * (감사 행처럼 업무 단계가 없는 행) 매 부팅마다 헛돌았다. 그래서 걷어냈다(git: backfill-keys.ts).\n   *\n   * 채우는 일은 **마이그레이션 한 번**이 맞다(`yarn migration`). 그 컬럼에 맞는 것을 그때 쓴다 —\n   * 범용 스캐너를 되살리지 말 것. 개발 데이타라면 그냥 버리는 것도 답이다.\n   */\n  /**\n   * 이 사실을 일으킨 **지시** — 커널이 커맨드에서 이어 준 상관값(기본은 commandId).\n   *\n   * 이것이 감사 기록(TwinAuditEvent.commandId)과 저널을 잇는 유일한 다리다. 없으면 승인 기록은\n   * \"사람이 허락했다\" 까지이고, 그 뒤 공장이 실제로 어떻게 움직였는지와 이어지지 않는다.\n   *\n   * **대부분의 행은 비어 있다** — 커맨드가 아니라 시뮬 시간이 낳은 사실이기 때문이다. 그것이 정상이고,\n   * 비어 있다고 \"덜 채워진 옛 행\" 으로 보면 안 된다(같은 오해를 bizStep 에서 이미 한 번 했다).\n   */\n  @Column({ length: 255, nullable: true })\n  @Field({ nullable: true, description: 'Id of the command that caused this fact (kernel correlation id; defaults to the commandId). Empty for facts that simulation time produced rather than a command.' })\n  correlationId?: string\n\n  /* 옛 행은 비어 있다 — 승격 전에 기록된 것이라 **모른다**(0 이나 OBSERVE 로 위장하지 않는다). */\n  @Column({ length: 16, nullable: true })\n  @Field({ nullable: true, description: 'EPCIS action (ADD / OBSERVE / DELETE), promoted from the payload. Empty for operational deltas, and for rows journaled before this column existed.' })\n  action?: string\n\n  @Column({ length: 255, nullable: true })\n  @Field({ nullable: true, description: 'Business step (CBV bizStep tail), promoted from the payload for indexed filtering.' })\n  bizStep?: string\n\n  @Column({ length: 255, nullable: true })\n  @Field({ nullable: true, description: 'Item identifier (EPC / EPC class / parent id), promoted from the payload for indexed lookup of one item history.' })\n  epc?: string\n\n  @Column({ length: 255, nullable: true })\n  @Field({ nullable: true, description: 'Internal order identifier, promoted from the payload for indexed lookup of one order history.' })\n  orderId?: string\n\n  /*\n   * **거래 식별자는 오더 식별자와 다른 것이다.**\n   *\n   * 전에는 둘이 한 칸(`orderId`)에 들어갔다. 그래서 한 오더의 이력이 색인 안에서 두 쪽으로\n   * 갈라졌다 — 운영 델타는 `order-1`, EPCIS 사건은 `urn:epc:id:gdti:…` 로 적혀 어느 이름으로\n   * 물어도 절반만 나왔다(실측 2026-09-05: 어휘가 섞인 행 10,004개, 오류는 나지 않음).\n   *\n   * 오더 사건은 두 값을 다 들고 있다. 그래서 이 칸이 **EPCIS 사건에서 오더로 건너가는 다리**가\n   * 된다 — 「이 개체를 어느 레시피로 만들었나」가 그 다리로 답해진다.\n   */\n  @Column({ length: 255, nullable: true })\n  @Field({ nullable: true, description: 'Business transaction identifier (PO / SO / production order), promoted from the payload for indexed lookup of one transaction.' })\n  bizTransaction?: string\n\n  @Column({ length: 255, nullable: true })\n  @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.' })\n  locationId?: string\n\n  @Column({ length: 255, nullable: true })\n  @Field({ nullable: true, description: 'Equipment identifier carried by operational deltas, promoted from the payload so one machine history can be asked for on the server. The column keeps the legacy name `moverId`: the journal is append-only history and mixing two names for the same fact across time is worse than an outdated name. Renaming belongs with event-schema versioning.' })\n  moverId?: string\n\n  @Column({ type: 'simple-json', nullable: true })\n  @Field(type => ScalarObject, { nullable: true, description: 'Raw canonical envelope (EPCIS event or operational delta) as JSON.' })\n  payload?: any\n\n  @CreateDateColumn()\n  @Field({ nullable: true, description: 'Wall-clock timestamp when the record was persisted.' })\n  createdAt?: Date\n}\n"]}

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

@@ -0,0 +1,15 @@
+/**
+ * 짐작하지 않는 규칙.
+ *
+ *   order            오더가 말했다. 판이 둘이든 열이든 그것을 쓴다
+ *   only-candidate   오더는 말 안 했지만 후보가 하나다 — 고를 것이 없으면 짐작이 아니다
+ *   ambiguous        후보가 둘 이상인데 말해 주는 것이 없다 → **답하지 않는다**
+ *   said-but-undeclared  오더는 말했는데 그 레시피가 선언에 없다 — 모르는 것이 아니라 어긋난 것이다
+ *
+ * 마지막 둘을 가르는 이유: 사람이 할 일이 다르다. 어긋남은 선언이나 원본을 고칠 일이고,
+ * 모호함은 그 개체가 어느 것으로 만들어졌는지 기록이 없는 일이다.
+ */
+export declare function chooseRecipe(recipes: any[], candidates: any[], saidRecipeKey: string | undefined): {
+    recipe?: any;
+    basis: 'order' | 'only-candidate' | 'ambiguous' | 'said-but-undeclared' | 'none';
+};

package/dist-server/service/twin-model/choose-recipe.js

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

package/dist-server/service/twin-model/choose-recipe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"choose-recipe.js","sourceRoot":"","sources":["../../../server/service/twin-model/choose-recipe.ts"],"names":[],"mappings":";;AAkBA,oCAYC;AA9BD;;;;;;GAMG;AACH;;;;;;;;;;GAUG;AACH,SAAgB,YAAY,CAC1B,OAAc,EACd,UAAiB,EACjB,aAAiC;IAEjC,IAAI,aAAa,EAAE,CAAC;QAClB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,aAAa,CAAC,CAAA;QAC/D,OAAO,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,qBAAqB,EAAE,CAAA;IACnF,CAAC;IACD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,gBAAgB,EAAE,CAAA;IACtF,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,CAAA;IACxD,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAA;AAC1B,CAAC","sourcesContent":["/*\n * **어느 레시피로 만들었나** — 판정만. 순수하다.\n *\n * ── 왜 따로 있나 ───────────────────────────────────────────────────────────\n * 계보 질의는 TypeORM 과 shell 을 끌어온다. 규칙만 재려는 시험이 그것까지 들고 오면 무겁고, 이\n * 저장소에서 그 이유로 시험이 안 서는 일을 겪었다. 판단과 배선을 나눈다 — 여기는 값만 보고 답한다.\n */\n/**\n * 짐작하지 않는 규칙.\n *\n *   order            오더가 말했다. 판이 둘이든 열이든 그것을 쓴다\n *   only-candidate   오더는 말 안 했지만 후보가 하나다 — 고를 것이 없으면 짐작이 아니다\n *   ambiguous        후보가 둘 이상인데 말해 주는 것이 없다 → **답하지 않는다**\n *   said-but-undeclared  오더는 말했는데 그 레시피가 선언에 없다 — 모르는 것이 아니라 어긋난 것이다\n *\n * 마지막 둘을 가르는 이유: 사람이 할 일이 다르다. 어긋남은 선언이나 원본을 고칠 일이고,\n * 모호함은 그 개체가 어느 것으로 만들어졌는지 기록이 없는 일이다.\n */\nexport function chooseRecipe(\n  recipes: any[],\n  candidates: any[],\n  saidRecipeKey: string | undefined\n): { recipe?: any; basis: 'order' | 'only-candidate' | 'ambiguous' | 'said-but-undeclared' | 'none' } {\n  if (saidRecipeKey) {\n    const said = recipes.find((r: any) => r?.key === saidRecipeKey)\n    return said ? { recipe: said, basis: 'order' } : { basis: 'said-but-undeclared' }\n  }\n  if (candidates.length === 1) return { recipe: candidates[0], basis: 'only-candidate' }\n  if (candidates.length > 1) return { basis: 'ambiguous' }\n  return { basis: 'none' }\n}\n"]}

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

@@ -0,0 +1,76 @@
+/** 밖에 사는 대상 하나 — 화면이 이름을 보이고 갈 곳을 정할 수 있게. */
+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[]>;
+}
+/**
+ * 해소기를 꽂는다 — **부팅에서 한 번.**
+ *
+ * 같은 `entity` 를 두 번 꽂으면 뒤엣것이 이긴다. 그것이 개발 중 재적재의 정상 동작이고, 운영에서
+ * 일어나면 두 제품이 같은 대상을 자기 것이라 말하는 것이므로 **경고를 남긴다** — 조용히 덮으면
+ * 어느 쪽이 답하고 있는지 아무도 모른다.
+ */
+export declare function registerExternalResolver(r: ExternalResolver, warn?: (msg: string) => void): void;
+/** 지금 꽂혀 있는 것들 — 「무엇을 풀 수 있나」를 밖에서 잴 수 있게. */
+export declare function externalResolverEntities(): string[];
+/** 시험이 재기동을 넣을 수 있게. */
+export declare function clearExternalResolvers(): void;
+/**
+ * 그 id 들을 푼다 — **못 풀면 못 푼다고 말한다.**
+ *
+ * 해소기가 터져도 360 전체를 죽이지 않는다. 한 관계가 답을 못 하는 것과 화면이 안 뜨는 것은 다른
+ * 사고이고, 뒤엣것이 훨씬 나쁘다.
+ */
+export declare function resolveExternal(entity: string, domainId: string, ids: readonly string[], warn?: (msg: string) => void): Promise<{
+    refs?: ExternalRef[];
+    unresolved?: 'no-resolver' | 'failed';
+}>;
+/**
+ * 밖에서 이 대상을 가리키는 것들을 모은다.
+ *
+ * 꽂힌 것이 없으면 **빈 배열이지 오류가 아니다** — 밖에서 가리키는 것이 없는 대상이 정상이다.
+ * 다만 「해소기가 없어서 모른다」와 「없다」는 다르므로, 그 구별은 `externalResolverEntities()` 로
+ * 밖에서 잰다.
+ */
+export declare function externalIncoming(domainId: string, instanceId: string, axis: string, itemId: string, warn?: (msg: string) => void): Promise<ExternalIncoming[]>;

package/dist-server/service/twin-model/external-resolver.js

@@ -0,0 +1,109 @@
+"use strict";
+/*
+ * **board 밖을 가리키는 관계를 푸는 자리** — 선언은 있고 코드가 0곳이던 이음새.
+ *
+ * ── 무엇이 있었나 (2026-09-05 실측) ────────────────────────────────────────
+ * 계약이 `target: { kind: 'external', entity: … }` 를 선언하고 주석에 「해소는 호스트가 한다」고
+ * 적어 두었다. 그런데 **`headless-twin/server` 어디에도 `kind === 'external'` 을 다루는 코드가
+ * 없었다**(0곳).
+ *
+ * `space.area` 가 도는 것처럼 보인 이유는 이음새가 있어서가 아니라 **호스트에서 그것이 평범한 FK
+ * 라서**다. TypeORM 메타데이터가 우연히 답해 준 것이지 선언이 길을 낸 것이 아니다.
+ *
+ * ── 왜 지금 채우나 ─────────────────────────────────────────────────────────
+ * 아침에는 「아무도 안 막혔으니 급하지 않다」로 적었다. **그 판단이 규모를 작게 잡은 것이었다.**
+ *
+ * 360(한 대상에 걸린 것을 한자리에)의 소비처는 무한히 늘어난다. 그러면 각 제품의 자기 저장소가
+ * 관계의 원천이 된다 — MES 의 실적·상태 구간·정비 계획이 그렇고, 다음 제품도 그럴 것이다.
+ *
+ * 그때 **선언은 「밖을 가리킨다」고 말하는데 푸는 길이 없으면 제품마다 자기 길을 낸다.** 그것이
+ * 정확히 「무한히 갈린다」다. 이 파일이 그 갈림을 막는다.
+ *
+ * ── 커널은 어느 표인지 모른다 ──────────────────────────────────────────────
+ * 계약은 「이 축이 밖을 가리킨다」까지만 안다. **「어느 표의 어느 칸」은 제품이 안다.** 그래서 제품이
+ * 부팅에서 해소기를 꽂는다 — 장부 기록기(`installIngestWindowWriter`)와 같은 규율이다.
+ *
+ * 커널이 표 이름을 알게 되면 한 제품의 저장 구조에 매이고, 다음 제품이 다른 표를 쓰면 커널을 또
+ * 고쳐야 한다.
+ *
+ * ── 없는 것을 숨기지 않는다 ────────────────────────────────────────────────
+ * 해소기가 없으면 **그 사실을 낸다**(`unresolved`). 링크를 지우면 화면은 「그런 관계가 없다」로
+ * 읽고, 실제로는 「아무도 답할 수 없다」다. 그 둘은 사람이 할 일이 다르다.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerExternalResolver = registerExternalResolver;
+exports.externalResolverEntities = externalResolverEntities;
+exports.clearExternalResolvers = clearExternalResolvers;
+exports.resolveExternal = resolveExternal;
+exports.externalIncoming = externalIncoming;
+const resolvers = new Map();
+/**
+ * 해소기를 꽂는다 — **부팅에서 한 번.**
+ *
+ * 같은 `entity` 를 두 번 꽂으면 뒤엣것이 이긴다. 그것이 개발 중 재적재의 정상 동작이고, 운영에서
+ * 일어나면 두 제품이 같은 대상을 자기 것이라 말하는 것이므로 **경고를 남긴다** — 조용히 덮으면
+ * 어느 쪽이 답하고 있는지 아무도 모른다.
+ */
+function registerExternalResolver(r, warn) {
+    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 });
+}
+/** 지금 꽂혀 있는 것들 — 「무엇을 풀 수 있나」를 밖에서 잴 수 있게. */
+function externalResolverEntities() {
+    return [...resolvers.keys()].sort();
+}
+/** 시험이 재기동을 넣을 수 있게. */
+function clearExternalResolvers() {
+    resolvers.clear();
+}
+/**
+ * 그 id 들을 푼다 — **못 풀면 못 푼다고 말한다.**
+ *
+ * 해소기가 터져도 360 전체를 죽이지 않는다. 한 관계가 답을 못 하는 것과 화면이 안 뜨는 것은 다른
+ * 사고이고, 뒤엣것이 훨씬 나쁘다.
+ */
+async function resolveExternal(entity, domainId, ids, warn) {
+    const r = resolvers.get(entity);
+    if (!r?.resolve)
+        return { unresolved: 'no-resolver' };
+    try {
+        return { refs: await r.resolve(domainId, ids) };
+    }
+    catch (e) {
+        warn?.(`[external-resolver] '${entity}' 해소가 실패했다 — ${String(e?.message ?? e)}`);
+        return { unresolved: 'failed' };
+    }
+}
+/**
+ * 밖에서 이 대상을 가리키는 것들을 모은다.
+ *
+ * 꽂힌 것이 없으면 **빈 배열이지 오류가 아니다** — 밖에서 가리키는 것이 없는 대상이 정상이다.
+ * 다만 「해소기가 없어서 모른다」와 「없다」는 다르므로, 그 구별은 `externalResolverEntities()` 로
+ * 밖에서 잰다.
+ */
+async function externalIncoming(domainId, instanceId, axis, itemId, warn) {
+    const out = [];
+    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) {
+            warn?.(`[external-resolver] '${r.entity}' 의 들어오는 관계 조회가 실패했다 — ${String(e?.message ?? e)}`);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=external-resolver.js.map

package/dist-server/service/twin-model/external-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-resolver.js","sourceRoot":"","sources":["../../../server/service/twin-model/external-resolver.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;;AA4DH,4DAUC;AAGD,4DAEC;AAGD,wDAEC;AAQD,0CAcC;AASD,4CAmBC;AA/ED,MAAM,SAAS,GAAG,IAAI,GAAG,EAA4B,CAAA;AAErD;;;;;;GAMG;AACH,SAAgB,wBAAwB,CAAC,CAAmB,EAAE,IAA4B;IACxF,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,EAAE,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;IAC7C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,IAAI,EAAE,CAAC,2DAA2D,CAAC,CAAA;QACnE,OAAM;IACR,CAAC;IACD,IAAI,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,IAAI,EAAE,CAAC,wBAAwB,MAAM,8CAA8C,CAAC,CAAA;IACtF,CAAC;IACD,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC,CAAA;AACzC,CAAC;AAED,8CAA8C;AAC9C,SAAgB,wBAAwB;IACtC,OAAO,CAAC,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;AACrC,CAAC;AAED,wBAAwB;AACxB,SAAgB,sBAAsB;IACpC,SAAS,CAAC,KAAK,EAAE,CAAA;AACnB,CAAC;AAED;;;;;GAKG;AACI,KAAK,UAAU,eAAe,CACnC,MAAc,EACd,QAAgB,EAChB,GAAsB,EACtB,IAA4B;IAE5B,MAAM,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IAC/B,IAAI,CAAC,CAAC,EAAE,OAAO;QAAE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,CAAA;IACrD,IAAI,CAAC;QACH,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE,CAAA;IACjD,CAAC;IAAC,OAAO,CAAM,EAAE,CAAC;QAChB,IAAI,EAAE,CAAC,wBAAwB,MAAM,gBAAgB,MAAM,CAAC,CAAC,EAAE,OAAO,IAAI,CAAC,CAAC,EAAE,CAAC,CAAA;QAC/E,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAA;IACjC,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACI,KAAK,UAAU,gBAAgB,CACpC,QAAgB,EAChB,UAAkB,EAClB,IAAY,EACZ,MAAc,EACd,IAA4B;IAE5B,MAAM,GAAG,GAAuB,EAAE,CAAA;IAClC,KAAK,MAAM,CAAC,IAAI,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC;QACnC,IAAI,CAAC,CAAC,CAAC,QAAQ;YAAE,SAAQ;QACzB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,QAAQ,CAAC,QAAQ,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,CAAC,CAAA;YAChE,yDAAyD;YACzD,KAAK,MAAM,CAAC,IAAI,GAAG,IAAI,EAAE;gBAAE,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC;oBAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QAC9D,CAAC;QAAC,OAAO,CAAM,EAAE,CAAC;YAChB,IAAI,EAAE,CAAC,wBAAwB,CAAC,CAAC,MAAM,0BAA0B,MAAM,CAAC,CAAC,EAAE,OAAO,IAAI,CAAC,CAAC,EAAE,CAAC,CAAA;QAC7F,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC","sourcesContent":["/*\n * **board 밖을 가리키는 관계를 푸는 자리** — 선언은 있고 코드가 0곳이던 이음새.\n *\n * ── 무엇이 있었나 (2026-09-05 실측) ────────────────────────────────────────\n * 계약이 `target: { kind: 'external', entity: … }` 를 선언하고 주석에 「해소는 호스트가 한다」고\n * 적어 두었다. 그런데 **`headless-twin/server` 어디에도 `kind === 'external'` 을 다루는 코드가\n * 없었다**(0곳).\n *\n * `space.area` 가 도는 것처럼 보인 이유는 이음새가 있어서가 아니라 **호스트에서 그것이 평범한 FK\n * 라서**다. TypeORM 메타데이터가 우연히 답해 준 것이지 선언이 길을 낸 것이 아니다.\n *\n * ── 왜 지금 채우나 ─────────────────────────────────────────────────────────\n * 아침에는 「아무도 안 막혔으니 급하지 않다」로 적었다. **그 판단이 규모를 작게 잡은 것이었다.**\n *\n * 360(한 대상에 걸린 것을 한자리에)의 소비처는 무한히 늘어난다. 그러면 각 제품의 자기 저장소가\n * 관계의 원천이 된다 — MES 의 실적·상태 구간·정비 계획이 그렇고, 다음 제품도 그럴 것이다.\n *\n * 그때 **선언은 「밖을 가리킨다」고 말하는데 푸는 길이 없으면 제품마다 자기 길을 낸다.** 그것이\n * 정확히 「무한히 갈린다」다. 이 파일이 그 갈림을 막는다.\n *\n * ── 커널은 어느 표인지 모른다 ──────────────────────────────────────────────\n * 계약은 「이 축이 밖을 가리킨다」까지만 안다. **「어느 표의 어느 칸」은 제품이 안다.** 그래서 제품이\n * 부팅에서 해소기를 꽂는다 — 장부 기록기(`installIngestWindowWriter`)와 같은 규율이다.\n *\n * 커널이 표 이름을 알게 되면 한 제품의 저장 구조에 매이고, 다음 제품이 다른 표를 쓰면 커널을 또\n * 고쳐야 한다.\n *\n * ── 없는 것을 숨기지 않는다 ────────────────────────────────────────────────\n * 해소기가 없으면 **그 사실을 낸다**(`unresolved`). 링크를 지우면 화면은 「그런 관계가 없다」로\n * 읽고, 실제로는 「아무도 답할 수 없다」다. 그 둘은 사람이 할 일이 다르다.\n */\n\n/** 밖에 사는 대상 하나 — 화면이 이름을 보이고 갈 곳을 정할 수 있게. */\nexport interface ExternalRef {\n  id: string\n  /** 사람이 읽는 이름. 없으면 화면이 id 를 보인다(지어내지 않는다). */\n  name?: string\n  /**\n   * 그 제품에서 이것을 열 수 있는 자리 — 없으면 화면이 링크를 만들지 않는다.\n   *\n   * 막다른 링크를 만들지 않는 것이 이 칸의 요점이다. 눌러서 아무 일도 안 일어나면 사람은 그것을\n   * 결함으로 읽는다.\n   */\n  href?: string\n  /** 그 id 가 실제로 있나 — **없으면 없다고 말한다.** 답에서 빼지 않는다. */\n  missing?: boolean\n}\n\n/**\n * 밖에서 이 대상을 가리키는 것들 — 들어오는 관계 한 묶음.\n *\n * `tense` 를 **제품이 선언한다**(계약의 `RelationTense`). 실적·상태 구간은 지난 일이고 정비 계획·\n * 지시는 앞의 일이다 — 「걸린 것이 열」이 두 뜻이 되는 자리이므로 묶음이 스스로 말해야 한다.\n */\nexport interface ExternalIncoming {\n  /** 관계의 이름(i18n 키) — 계약의 `via` 와 같은 규칙. 제품은 자기 접두를 쓴다. */\n  via: string\n  /** 어디서 오나 — 사람이 읽는 축 이름이 아니라 그 제품의 축 키다. */\n  from: string\n  /** 언제의 일인가. 안 주면 「선언이 말하지 않았다」다 — `standing` 으로 바꾸지 않는다. */\n  tense?: 'past' | 'future' | 'standing'\n  ids: string[]\n  /** 전체 수 — `ids` 가 잘렸어도 몇인지 말한다. */\n  total: number\n}\n\n/**\n * 한 external 대상을 푸는 제품 쪽 구현.\n *\n * 둘 다 선택이다. 이름만 대 줄 수 있는 제품과 들어오는 관계만 낼 수 있는 제품이 다 있다 — 하나만\n * 꽂아도 그만큼은 답해진다.\n */\nexport interface ExternalResolver {\n  /** 계약의 `target.entity` 와 **같은 낱말**. 다르면 아무 관계에도 안 붙는다. */\n  entity: string\n  /** 이 id 들이 무엇인가. */\n  resolve?(domainId: string, ids: readonly string[]): Promise<ExternalRef[]>\n  /** 이 대상을 가리키는 것들. */\n  incoming?(domainId: string, instanceId: string, axis: string, itemId: string): Promise<ExternalIncoming[]>\n}\n\nconst resolvers = new Map<string, ExternalResolver>()\n\n/**\n * 해소기를 꽂는다 — **부팅에서 한 번.**\n *\n * 같은 `entity` 를 두 번 꽂으면 뒤엣것이 이긴다. 그것이 개발 중 재적재의 정상 동작이고, 운영에서\n * 일어나면 두 제품이 같은 대상을 자기 것이라 말하는 것이므로 **경고를 남긴다** — 조용히 덮으면\n * 어느 쪽이 답하고 있는지 아무도 모른다.\n */\nexport function registerExternalResolver(r: ExternalResolver, warn?: (msg: string) => void): void {\n  const entity = String(r?.entity ?? '').trim()\n  if (!entity) {\n    warn?.('[external-resolver] entity 없는 해소기는 꽂지 않는다 — 아무 관계에도 안 붙는다')\n    return\n  }\n  if (resolvers.has(entity)) {\n    warn?.(`[external-resolver] '${entity}' 해소기를 덮어쓴다 — 두 제품이 같은 대상을 답하려 하면 그중 하나만 답한다`)\n  }\n  resolvers.set(entity, { ...r, entity })\n}\n\n/** 지금 꽂혀 있는 것들 — 「무엇을 풀 수 있나」를 밖에서 잴 수 있게. */\nexport function externalResolverEntities(): string[] {\n  return [...resolvers.keys()].sort()\n}\n\n/** 시험이 재기동을 넣을 수 있게. */\nexport function clearExternalResolvers(): void {\n  resolvers.clear()\n}\n\n/**\n * 그 id 들을 푼다 — **못 풀면 못 푼다고 말한다.**\n *\n * 해소기가 터져도 360 전체를 죽이지 않는다. 한 관계가 답을 못 하는 것과 화면이 안 뜨는 것은 다른\n * 사고이고, 뒤엣것이 훨씬 나쁘다.\n */\nexport async function resolveExternal(\n  entity: string,\n  domainId: string,\n  ids: readonly string[],\n  warn?: (msg: string) => void\n): Promise<{ refs?: ExternalRef[]; unresolved?: 'no-resolver' | 'failed' }> {\n  const r = resolvers.get(entity)\n  if (!r?.resolve) return { unresolved: 'no-resolver' }\n  try {\n    return { refs: await r.resolve(domainId, ids) }\n  } catch (e: any) {\n    warn?.(`[external-resolver] '${entity}' 해소가 실패했다 — ${String(e?.message ?? e)}`)\n    return { unresolved: 'failed' }\n  }\n}\n\n/**\n * 밖에서 이 대상을 가리키는 것들을 모은다.\n *\n * 꽂힌 것이 없으면 **빈 배열이지 오류가 아니다** — 밖에서 가리키는 것이 없는 대상이 정상이다.\n * 다만 「해소기가 없어서 모른다」와 「없다」는 다르므로, 그 구별은 `externalResolverEntities()` 로\n * 밖에서 잰다.\n */\nexport async function externalIncoming(\n  domainId: string,\n  instanceId: string,\n  axis: string,\n  itemId: string,\n  warn?: (msg: string) => void\n): Promise<ExternalIncoming[]> {\n  const out: ExternalIncoming[] = []\n  for (const r of resolvers.values()) {\n    if (!r.incoming) continue\n    try {\n      const got = await r.incoming(domainId, instanceId, axis, itemId)\n      /* 빈 묶음은 싣지 않는다 — 여기서는 「그 제품이 이 축을 안 본다」는 뜻이고 할 말이 없다. */\n      for (const g of got ?? []) if (g && g.total > 0) out.push(g)\n    } catch (e: any) {\n      warn?.(`[external-resolver] '${r.entity}' 의 들어오는 관계 조회가 실패했다 — ${String(e?.message ?? e)}`)\n    }\n  }\n  return out\n}\n"]}

package/dist-server/service/twin-model/project-structure.js

@@ -104,10 +104,21 @@ async function projectStructure(domainId, instanceId, model, sourceRef) {
     const equipment = (model?.equipment ?? [])
         .filter((m) => m?.id)
         .map((m) => {
+        /*
+         * ── 설비는 자리에도 구역에도 설 수 있다 (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)
+        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,
@@ -122,6 +133,8 @@ async function projectStructure(domainId, instanceId, model, sourceRef) {
             /* 결과까지 — 참조만 있으면 "무엇으로 검증한다" 까지고, 자격 성립은 결과가 말한다. */
             testResults: m.testResults ?? null,
             homeLocation: home ? { id: home.id } : null,
+            /* 둘 다 차는 일은 없다 — 자리에서 찾았으면 구역은 안 본다. */
+            homeArea: homeArea ? { id: homeArea.id } : null,
             mtbfMs: m.mtbfMs ?? null,
             mttrMs: m.mttrMs ?? null,
             /* 선언된 정체성 — 예전에는 선언에 없는 `gs1Id` 를 읽어 이 칸이 늘 비어 있었다. */