@things-factory/headless-twin 10.0.19 → 10.1.0

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
+
   /*
    * 고장 모델 — 원본이 선언할 때만 있다. 없으면 고장 없는 설비로 동작한다(커널 계약).
    * **관측(가동률)은 여기 두지 않는다** — 그건 트윈이 저널에서 만든 것이라 성질이 다르고,

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

@@ -3,6 +3,7 @@ import { Arg, Ctx, Int, Query, Resolver } from 'type-graphql'
 import { ScalarObject, getRepository } from '@things-factory/shell'
 
 import { itemRefOf, resolveByDeclaration } from './item-ref.js'
+import { chooseRecipe } from './choose-recipe.js'
 
 import { TwinInstance } from '../twin-instance/twin-instance.js'
 import { TwinEvent } from '../twin-event/twin-event.js'
@@ -133,7 +134,39 @@ export class TwinLineageQuery {
 
     const myMaterial = materialOf(epc)
     const recipes: any[] = spec?.definition?.recipes ?? []
-    const recipe = myMaterial ? recipes.find((r: any) => (r.outputs ?? []).some((o: any) => o.material === myMaterial)) : undefined
+
+    /*
+     * ── 「무엇으로 만들었나」는 **적혀 있다** (2026-09-05) ───────────────────────
+     *
+     * 예전에는 이 자리가 자재로 되짚어 `recipes.find(...)` 로 **먼저 걸리는 하나**를 골랐다. 배열
+     * 순서가 답을 정한다는 뜻이고, 한 자재에 레시피가 둘이면 틀린 답이 확신에 찬 얼굴로 나온다.
+     * 실제로 그런 자재가 있다 — `BOLT-M8` 에 `RCP-BOLT-STD` · `RCP-BOLT-FAST` 둘이다.
+     *
+     * 그런데 답은 이미 기록되어 있다. 만들 때 정해지는 사실이고 커널이 오더에 싣는다
+     * (`FlowOrder.recipeKey`). 변환 사건은 그 오더를 거래 식별자로 가리키고(`bizTransactionList`),
+     * 이 함수는 그 값을 이미 `tx` 로 꺼내 놓고도 쓰지 않았다.
+     *
+     * 세 자리가 다 있었고 마지막 연결만 없었다. 「가릴 수 없다」가 아니라 **안 읽고 있었다.**
+     *
+     * ── 규칙 셋 — 짐작하지 않는다 ───────────────────────────────────────────────
+     *   오더가 말한다        그것을 쓴다. 판이 둘이든 열이든 상관없다
+     *   오더가 말 안 하고
+     *     후보가 하나        그것을 쓴다 — 고를 것이 없으면 짐작이 아니다
+     *     후보가 둘 이상     **답하지 않는다.** 어느 것인지 모르는 채로 견주면 거짓 진단이 된다
+     *
+     * 마지막 줄이 이 함수가 식별자 되찾기에 이미 적용하던 규율이다(「후보가 둘 이상이면 답하지
+     * 않는다」). 두 줄 위에서만 안 지키고 있었다.
+     */
+    const candidates = myMaterial
+      ? recipes.filter((r: any) => (r.outputs ?? []).some((o: any) => o.material === myMaterial))
+      : []
+
+    /* 이 개체를 만든 변환이 가리키는 거래 — 그 오더가 레시피를 말한다. */
+    const madeTx = (madeBy.get(epc) ?? []).map(s => s.tx).find(Boolean)
+    const saidRecipeKey = madeTx ? await recipeKeyOfTransaction(domainId, instanceId, String(madeTx)) : undefined
+
+    const chosen = chooseRecipe(recipes, candidates, saidRecipeKey)
+    const recipe = chosen.recipe
 
     /*
      * ── 「모르는 개체」와 「대응이 없는 개체」는 다른 사실이다 (2026-08-23) ──────
@@ -164,6 +197,16 @@ export class TwinLineageQuery {
       }
     } else if (!myMaterial) {
       conformance = { comparable: false, reason: 'item-not-bound' }
+    } else if (chosen.basis === 'said-but-undeclared') {
+      /* 오더는 말했는데 그 레시피가 모델의 선언에 없다 — 원본과 선언이 어긋난 것이지 모르는 것이 아니다. */
+      conformance = { comparable: false, reason: 'recipe-not-declared', recipe: saidRecipeKey }
+    } else if (chosen.basis === 'ambiguous') {
+      /* 짐작하지 않는다 — 어느 것으로 만들었는지 말해 주는 사실이 없다. 후보를 밝혀 사람이 판단하게 한다. */
+      conformance = {
+        comparable: false,
+        reason: 'many-recipes-for-material',
+        recipes: candidates.map((r: any) => r.key).sort()
+      }
     } else if (!recipe) {
       conformance = { comparable: false, reason: 'no-recipe-for-material' }
     } else {
@@ -205,6 +248,8 @@ export class TwinLineageQuery {
         comparable: true,
         material: myMaterial,
         recipe: recipe.key,
+        /* 그 레시피를 **어떻게 알았나** — 화면이 「기록으로 안다」와 「하나뿐이라 안다」를 구별할 수 있게. */
+        recipeBasis: chosen.basis,
         /* 자재마다 선언·관측을 나란히. 어느 한쪽에만 있는 것도 사실이다(빠뜨리지 않는다). */
         lines: keys.map(m => ({
           material: m,
@@ -231,3 +276,39 @@ export class TwinLineageQuery {
     }
   }
 }
+
+/**
+ * 그 거래를 가리키는 오더가 **어느 레시피로** 만들었다고 말하는가.
+ *
+ * ── 왜 거래 식별자로 묻나 ───────────────────────────────────────────────────
+ * EPCIS 변환 사건에는 레시피가 없다 — 표준에 그 자리가 없고, 대신 생산 오더를 거래로 가리킨다
+ * (`bizTransactionList`). 오더 사건은 `recipeKey` 와 그 거래 식별자를 **둘 다** 든다. 그래서 이
+ * 두 칸이 EPCIS 에서 오더로 건너가는 다리다(§`twin-event-keys.ts`).
+ *
+ * ── 색인을 탄다 ─────────────────────────────────────────────────────────────
+ * `ix_twin_event_9 (domain, instanceId, bizTransaction)` 로 좁힌다. 이 칸이 없던 때는 payload 를
+ * 문자열로 훑어야 했고 32만 행에 3분이 걸렸다 — 화면이 기다릴 비용이 아니다.
+ *
+ * ── 못 찾으면 **답하지 않는다** ──────────────────────────────────────────────
+ * 옛 행에는 이 칸이 비어 있다(과거 행은 채우지 않는다는 규율). 그때는 `undefined` 를 내고, 부르는
+ * 쪽이 후보 수로 판단한다 — 여기서 아무거나 고르면 예전과 같은 결함이 된다.
+ */
+async function recipeKeyOfTransaction(
+  domainId: string,
+  instanceId: string,
+  bizTransaction: string
+): Promise<string | undefined> {
+  const row = await getRepository(TwinEvent)
+    .createQueryBuilder('e')
+    .where('e.domain = :domainId', { domainId })
+    .andWhere('e.instanceId = :instanceId', { instanceId })
+    .andWhere('e.bizTransaction = :tx', { tx: bizTransaction })
+    .andWhere('e.eventType = :eventType', { eventType: 'order.status' })
+    /* 어느 줄이든 같은 오더를 말하므로 하나면 된다 — 가장 이른 것이 그 오더가 선 순간이다. */
+    .orderBy('e.eventTime', 'ASC')
+    .limit(1)
+    .getOne()
+
+  const said = (row?.payload as any)?.data?.recipeKey
+  return typeof said === 'string' && said ? said : undefined
+}

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

@@ -1,3 +1,4 @@
+import { twinWarn } from '../../engine/log.js'
 import { Arg, Ctx, Int, Query, Resolver } from 'type-graphql'
 
 import { ScalarObject, getRepository } from '@things-factory/shell'
@@ -17,7 +18,9 @@ import { TwinArea } from '../twin-space/twin-area.js'
 import { at, idOf, nameIndex, namesFor } from './name-index.js'
 
 /* 커널 런타임 로드 — 축·관계·속성 선언의 SSOT. 이 파일은 도메인 모양을 알지 않는다. */
-const { TWIN_AXES, TWIN_RELATIONS, axisInfo, axisSource, documentPath, relationsFrom, relationsTo, propertiesOf } = require('@operato/ops-contract')
+const { TWIN_AXES, TWIN_RELATIONS, axisInfo, axisSource, documentPath, isCacheableTense, relationsFrom, relationsTo, propertiesOf, tenseOf } =
+  require('@operato/ops-contract')
+import { externalIncoming, resolveExternal } from './external-resolver.js'
 
 /**
  * 축 → 그 축이 이미 **행으로 옮겨졌나**, 그리고 행의 어느 컬럼이 id 인가.
@@ -31,6 +34,32 @@ const ROW_BACKED: Record<string, { entity: any; idColumn: string; order: any }>
   operations: { entity: TwinOperation, idColumn: 'operationKey', order: { seq: 'ASC' } }
 }
 
+/*
+ * `productionSpec.binding` 의 키가 사는 축 — 자재가 둘로 갈려 있다.
+ *
+ *   materials            productionSpec.definition.materials    레시피의 투입 자재
+ *   materialDefinitions  materialDefinitions                    마스터 품목 목록
+ *
+ * 예전에는 `materials` 하나만 봤다. 커넥터에 따라 `binding` 키가 어느 축의 id 인지 달라서, MES 연결
+ * 둘은 품목이 자기 GS1 참조를 한 건도 답하지 못했다. 오류는 안 나고 칸이 비어서 나온다.
+ *
+ * 실측(2026-09-06, 인티그레이션 레인이 찾음):
+ *
+ *   트윈                      binding   def.materials 맞음   materialDefinitions 맞음
+ *   mes-miratek                 106            0                    106
+ *   mes-line-a                   21            0                     21
+ *   operato-chef-v1-pocheon    2789         1789                      0
+ *   rosarito-mes                 20           20                      0
+ *
+ * **두 축이 동시에 맞는 트윈은 없다**(양쪽 id 에 다 있으면서 binding 키인 것 0개). 그래서 두 축에
+ * 다 걸어도 어느 쪽을 붙일지 모호해지지 않는다. 조회가 판정한다 — `binding[id]` 는 키가 아닌 축에서
+ * 그냥 없다.
+ *
+ * 두 축을 한 이름으로 합치지 않는다. 레시피 투입 자재와 마스터 품목은 서로 다른 것이고, 합치면
+ * 둘 다 있는 트윈(chef)에서 어느 쪽 목록인지 알 수 없게 된다.
+ */
+const BINDING_AXES = new Set(['materials', 'materialDefinitions'])
+
 
 /** 검색 — 항목의 값 어디든 걸리면 맞는 것으로 본다. 축마다 검색 컬럼을 정해 두면 축이 늘 때마다 여기를 고쳐야 한다. */
 function matches(o: any, q: string): boolean {
@@ -272,7 +301,7 @@ export class TwinModelItemQuery {
    * 값을 복제해 두면 두 곳이 어긋나고, 어긋난 쪽을 아무도 모른다.
    */
   private withBinding(axis: string, model: any, fields: any): any {
-    if (axis !== 'materials' || !fields || typeof fields !== 'object') return fields
+    if (!BINDING_AXES.has(axis) || !fields || typeof fields !== 'object') return fields
     const binding: Record<string, string> = model?.productionSpec?.binding ?? {}
     const ref = binding[fields.key ?? fields.id]
     /* 없으면 키를 만들지 않는다 — 빈 값이 있는 것과 선언되지 않은 것은 다르다. */
@@ -746,13 +775,55 @@ export class TwinModelItemQuery {
         /* 대상이 축이면 그 축의 항목으로 갈 수 있다. 타입·외부(구역)면 **갈 곳이 다르다** —
            화면이 링크를 만들지 말지 알아야 하므로 대상 종류를 그대로 낸다(막다른 링크 금지). */
         target: r.target,
+        /*
+         * ── 언제의 일인가, 그리고 담아 둬도 되나 (2026-09-06) ────────────────
+         * 판정을 계약이 낸다. 화면이 `standing` 을 보고 스스로 정하면 값이 하나 늘 때 한 화면만
+         * 따라간다. UX 레인이 이 칸을 요청했고, 그쪽에 있던 규칙은 걷었다.
+         *
+         * `tense` 가 없는 관계도 `cacheable: false` 다. 모를 때는 다시 조회하는 쪽이 낫다 —
+         * 낡은 값을 자신 있게 보여 주는 것이 비어 있는 것보다 나쁘다. 그래서 `tense` 는 없을 수
+         * 있고 `cacheable` 은 언제나 있다.
+         */
+        tense: tenseOf(r),
+        cacheable: isCacheableTense(tenseOf(r)),
         ids: ids.slice(0, NEIGHBOR_MAX),
         total: ids.length
       }
-    }).filter((l: any) => l.total > 0)
+    })
+
+    /*
+     * ── 밖을 가리키는 관계를 푼다 (2026-09-05) ─────────────────────────────────
+     * 계약이 `kind: 'external'` 을 선언하며 「해소는 호스트가 한다」고 적어 두었는데 **부르는 곳이
+     * 0이었다.** 그래서 화면은 id 만 받고 그것이 무엇인지, 갈 수 있는지 몰랐다.
+     *
+     * 못 풀면 **못 푼다고 말한다** — 링크를 지우면 화면이 「그런 관계가 없다」로 읽고, 실제로는
+     * 「아무도 답할 수 없다」다. 사람이 할 일이 다르다.
+     */
+    for (const l of out) {
+      if (l.target?.kind !== 'external' || !l.ids.length) continue
+      const got = await resolveExternal(l.target.entity, domainId, l.ids, m => twinWarn(m))
+      if (got.refs) (l as any).refs = got.refs
+      else (l as any).unresolved = got.unresolved
+    }
+
+    /*
+     * **비어 있는 관계도 낸다.** 예전에는 `total > 0` 만 냈다 — 그러면 사람은 없다는 것조차 모른다.
+     *
+     * 실측으로 그 값이 드러났다(2026-09-05): 설비 64대에 시험 규격이 전부 비어 있는 것을 「빈 묶음」
+     * 으로 세워 두니 **「이 설비에 검사 기준이 없다」와 「화면이 그것을 안 본다」가 구별됐다.** 지우면
+     * 그 구별이 사라진다.
+     *
+     * 선택이 아닌 관계(`optional: false`)가 비어 있으면 그것은 **끊어진 참조**이고, 그 사실이 화면에
+     * 닿아야 한다.
+     */
 
     /* 들어오는 쪽 — 나를 가리키는 항목들. 그 축이 행이면 DB 가 세고, 문서면 문서를 전수 조회한다. */
     const incoming: any[] = []
+    /*
+     * 밖에서 오는 것을 함께 싣는다 — 제품이 자기 저장소에서 모은다(커널은 그 표를 모른다).
+     * 꽂힌 해소기가 없으면 빈 배열이고 그것은 정상이다.
+     */
+    incoming.push(...(await externalIncoming(domainId, inst.instanceId, axis, itemId, m => twinWarn(m))))
     for (const r of relationsTo(axis)) {
       const fromInfo = axisInfo(r.from)
       if (!fromInfo) continue
@@ -799,7 +870,27 @@ export class TwinModelItemQuery {
           if (id) hits.push(id)
         }
       }
-      if (hits.length) incoming.push({ via: r.via, from: r.from, field: r.field, ids: hits.slice(0, NEIGHBOR_MAX), total: hits.length })
+      /*
+       * **들어오는 쪽도 빈 것을 낸다** — 나가는 쪽과 같은 이유다(위 주석).
+       *
+       * 「이 설비를 가리키는 작업이 없다」는 사실이고, 그것을 지우면 화면은 그 물음을 물어보지도
+       * 못한다. 축당 들어오는 관계는 0~8개다(실측 2026-09-05: 시험규격 8 · 자리 6 · 나머지 2 이하)
+       * — 다 내도 읽을 수 있는 분량이다.
+       *
+       * 값도 안 든다. 행 축은 0을 알아내려면 이미 `find` 를 돌렸고, 그 0을 말하는 비용은 없다.
+       *
+       * `externalIncoming` 은 여기서 예외다 — 그쪽의 빈 묶음은 「그 제품이 이 축을 안 본다」는
+       * 뜻이고 우리 선언에 없는 관계이므로 할 말이 없다.
+       */
+      incoming.push({
+        via: r.via,
+        from: r.from,
+        field: r.field,
+        tense: tenseOf(r),
+        cacheable: isCacheableTense(tenseOf(r)),
+        ids: hits.slice(0, NEIGHBOR_MAX),
+        total: hits.length
+      })
     }
 
     return { out, incoming }

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

@@ -14,7 +14,7 @@ const { TWIN_RELATIONS, axisInfo } = require('@operato/ops-contract')
  * 다단 BOM 을 "자재 안에 자재" 로 적으면 같은 부품이 여러 완제품에 들어갈 때마다 복제되고,
  * 수량이 어디 붙는지도 애매해진다. 표준(ISA-95)이 택한 모양은 **자재와 레시피가 번갈아 나오는
  * 그래프**다: 완제품 ←산출— 레시피 —투입→ 부품들, 그리고 그 부품이 또 어느 레시피의 산출이면
- * 거기서 다시 내려간다. 우리 선언(`twin.rel.input`·`twin.rel.output`)이 이미 그 두 홉이다.
+ * 거기서 다시 내려간다. 우리 선언(`ops.rel.input`·`ops.rel.output`)이 이미 그 두 홉이다.
  *
  * ── 패턴을 코드가 알지 않는다 ──────────────────────────────────────────────────
  * "BOM 은 산출→투입" 이라고 적어 두면 그 순간 이 파일이 도메인을 알게 된다(ADR-0031 위반).

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

@@ -77,6 +77,45 @@ export class TwinSpace {
   @Field({ nullable: true, description: 'IANA time zone of this physical site (e.g. America/Tijuana) — the base for reading shift times. Belongs to the space, not the tenant, because one tenant can run plants in different zones.' })
   timezone?: string
 
+  /**
+   * **이 현장이 언제 도나** — 표준 `WorkCalendarEntry`(복수). 휴일 · 주말 · 정기보수가 여기 든다.
+   *
+   * ── 왜 공간에 있나 (2026-09-07) ──────────────────────────────────────────
+   * 이 칸이 없던 동안 설비와 사람만 달력을 가질 수 있었다. 그래서 **현장이 언제 쉬는지가 어디에도
+   * 없었고**, 계획 조업 시간이 「재기 시작한 뒤 흐른 시간 전부」였다 — 주말도 야간도 휴일도 계획 조업으로
+   * 세었다. [산술] 8시간 × 주5일이면 168시간 중 40시간이 조업이니 그 수가 4.2배 크다.
+   *
+   * 시간대와 같은 축이라 같은 자리에 둔다. 「이 현장의 06:00 이 언제인가」와 「이 현장이 언제 도나」는
+   * 둘 다 현장이 갖는 값이고, 테넌트가 아니다 — 한 테넌트가 다른 시간대·다른 조업일의 공장을 함께 가진다.
+   *
+   * `withSpaceTimeBase` 가 이 값을 모델에 얹고, 거기서 OEE 누적기가 계획 정지를 낸다. 얹는 자리를
+   * 시간대와 하나로 둔 이유는 **한쪽만 채워진 상태**를 만들지 않기 위해서다.
+   *
+   * 없으면 아무것도 가정하지 않는다 — 종일 가동으로 보는 것은 「제약이 없다」가 아니라 「선언되지
+   * 않았다」이고, 그 사실은 세어져야 한다(안 그러면 사람이 수를 되살리려고 아무 달력이나 채운다).
+   */
+  @Column({ type: 'simple-json', nullable: true })
+  @Field(type => ScalarObject, {
+    nullable: true,
+    description:
+      'When this site runs — standard WorkCalendarEntry list (holidays, weekends, planned maintenance). Absent means undeclared, not unrestricted: planned busy time then counts the whole window.'
+  })
+  workCalendar?: any
+
+  /**
+   * 현장의 **우편 주소** — 사람이 읽고 서류에 적는 값.
+   *
+   * ── 왜 좌표와 따로 두나 (2026-09-07) ────────────────────────────────────
+   * `geo` 는 도면을 지구에 붙이는 값이고 화면이 쓴다. 주소는 **사람과 서류의 값**이다 — 납품·통관·
+   * 감사에 그 문자열이 그대로 들어가고, 좌표에서 되돌려 만들 수 없다(같은 좌표에 여러 주소가 있고
+   * 동·호가 좌표에 없다).
+   *
+   * 고객이 준 것을 그대로 적는다. 우편번호·동·호를 우리가 지어내거나 좌표에서 유추하지 않는다.
+   */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Postal address of this site as the customer states it. Kept apart from `geo`: a floor or unit number has no coordinate, and paperwork carries this string verbatim.' })
+  address?: string
+
   @Column({ nullable: true })
   @Field({ nullable: true, description: 'Id of the primary representation shown on the home/monitor.' })
   primaryRepresentationId?: string

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

@@ -46,8 +46,10 @@ import { twinEventKeys } from '../twin-event/twin-event-keys.js'
  *   location    자리
  *   equipment   설비
  *   task        작업
+ *   transaction 거래(PO/SO/생산오더) — 오더와 다르다. 전에는 오더 칸에 섞여 들어와 한 오더의
+ *               이력이 두 쪽으로 갈라졌다(2026-09-05)
  */
-export const SUBJECT_KINDS = ['item', 'lot', 'order', 'location', 'equipment', 'task'] as const
+export const SUBJECT_KINDS = ['item', 'lot', 'order', 'location', 'equipment', 'task', 'transaction'] as const
 export type SubjectKind = (typeof SUBJECT_KINDS)[number]
 
 export interface EventSubject {
@@ -133,6 +135,11 @@ export function subjectsOf(envelope: any, opts?: { itemOf?: ItemResolver }): Eve
     put(out, 'item', item || classEpc)
   }
   put(out, 'order', keys.orderId)
+  /*
+   * 거래는 오더가 아니다 — 갈라 적는다. 합쳐 적으면 EPCIS 사건의 GDTI 가 오더 이름으로 앉고,
+   * 그러면 한 오더의 이력이 두 쪽이 된다(`twin-event-keys.ts` 의 그 실측).
+   */
+  put(out, 'transaction', keys.bizTransaction)
   put(out, 'location', keys.locationId)
   put(out, 'equipment', keys.moverId)
 

package/shared/entity-delta.ts

@@ -83,7 +83,7 @@ function shapeOee(o: any): any {
     performance: Math.round((o.performance ?? 0) * 100),
     quality: Math.round((o.quality ?? 0) * 100),
     good: o.goodCount ?? 0,
-    scrap: o.scrapCount ?? 0
+    scrap: o.nonconformingCount ?? 0
   }
 }
 

package/test/ack-shape-alignment.test.ts

@@ -0,0 +1,97 @@
+/*
+ * ★ **답의 모양이 세 곳에서 같아야 한다** — 어댑터가 답한 칸이 중간에서 사라지지 않게.
+ *
+ * ── 무엇이 있었나 (2026-09-04, 인티그레이션 레인이 찾음) ────────────────────
+ * 조치의 답이 세 타입을 지난다.
+ *
+ *   ReferenceAdapter.actuate 반환   커넥터가 만든다
+ *   ActuationAck                   routeActuation 이 되돌린다
+ *   CommandAck                     dispatch 가 받아 표에 적는다
+ *
+ * 가운데가 `ok`·`ref`·`error` 셋만 들고 있었다. 그래서 **타입은 `note`·`noteNext`·`retry` 를
+ * 버린다고 말했다.** 값은 흘렀다 — JS 객체가 키를 안 버리므로. 실제로 `dispatch_note` 에 앉았다.
+ *
+ * 그런데 **커넥터를 만드는 사람이 그 칸이 있다는 것을 알 방법이 없었다.** 이 저장소에서 하루
+ * 종일 「자리는 있고 길이 없다」로 부른 것의 타입 판이다 — 동작은 하고 계약이 안 알려 준다.
+ *
+ * ── 왜 원문을 읽나 ──────────────────────────────────────────────────────────
+ * 타입은 런타임에 없다. 그래서 「세 모양이 같은가」를 값으로 잴 수 없고, 원문에서 읽는 것이
+ * 지금 할 수 있는 최선이다. 이 검사가 막으려는 것은 **한 곳에만 칸을 더하는 일**이다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+
+/** 주석 속 낱말이 세어지지 않게 — 오늘 두 번 그 함정에 걸렸다. */
+const bare = (p: string): string =>
+  readFileSync(new URL(p, import.meta.url), 'utf8')
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/\/\/[^\n]*/g, '')
+
+/** 답이 반드시 나를 칸 — 하나라도 중간에서 사라지면 커넥터가 적은 것이 버려진다. */
+const CARRIED = ['note', 'noteNext', 'retry'] as const
+
+const SOURCES = {
+  '어댑터 actuate 반환': '../server/service/reference/reference-adapter.ts',
+  ActuationAck: '../server/service/reference/actuation-routing.ts',
+  CommandAck: '../server/service/actuation/command-dispatcher.ts'
+} as const
+
+test('★ 세 타입이 같은 칸을 든다 — 한 곳에만 더하면 값이 중간에서 버려진다', () => {
+  const missing: string[] = []
+
+  for (const [label, path] of Object.entries(SOURCES)) {
+    const src = bare(path)
+    for (const field of CARRIED) {
+      /* `field?:` 로 선언된 자리를 찾는다 — 이름만 스치는 것은 세지 않는다. */
+      if (!new RegExp(`\\b${field}\\?:`).test(src)) missing.push(`${label} 에 ${field} 없음`)
+    }
+  }
+
+  assert.deepEqual(
+    missing,
+    [],
+    '조치의 답이 지나는 세 타입 중 한 곳이 칸을 버린다. 값은 흐르지만 커넥터를 만드는 사람은\n' +
+      '그 칸이 있다는 것을 알 수 없다:\n  ' + missing.join('\n  ')
+  )
+})
+
+test('★ 갈래 셋은 한 곳에서 정의되고 나머지는 그것을 가리킨다 — 반복하면 갈라진다', () => {
+  /*
+   * `again`·`after-fix`·`never` 는 어댑터가 고르고 일꾼이 판정한다. 세 곳에 낱말을 각각 적으면
+   * 한쪽만 늘어나는 날 다른 쪽이 **모르는 값을 「말하지 않은 것」으로 읽어 조용히 집지 않는다.**
+   *
+   * 처음에 이 검사를 「세 곳에 낱말이 다 있는가」로 뒀다. 그것이 곧 **반복을 요구하는 검사**였고,
+   * 반복이 바로 갈라짐의 원인이다. 그래서 규칙을 바꿨다: 정의는 한 곳, 나머지는 그 이름을 가리킨다.
+   */
+  const outlooks = ['again', 'after-fix', 'never'] as const
+
+  /* 정의하는 자리 — 셋을 다 안다. */
+  const plan = bare('../server/service/actuation/retry-plan.ts')
+  assert.match(plan, /export type RetryOutlook/, '갈래를 정의하는 자리가 없다')
+  for (const o of outlooks) assert.ok(plan.includes(`'${o}'`), `정의가 갈래 '${o}' 를 모른다`)
+
+  /* 선언하는 자리는 낱말을 다 적거나 그 이름을 가리켜야 한다. */
+  const loose: string[] = []
+  for (const [label, path] of Object.entries(SOURCES)) {
+    const src = bare(path)
+    if (!/\bretry\?:/.test(src)) continue
+
+    const namesType = /retry\?:\s*RetryOutlook/.test(src)
+    const listsAll = outlooks.every(o => src.includes(`'${o}'`))
+    if (!namesType && !listsAll) loose.push(`${label} 이 갈래를 좁히지 않는다`)
+  }
+
+  assert.deepEqual(
+    loose,
+    [],
+    '갈래를 문자열로 열어 두면 커넥터가 모르는 낱말을 보내도 타입이 통과시킨다:\n  ' + loose.join('\n  ')
+  )
+})
+
+test('★ 이 검사가 실제로 무언가를 잰다 — 원문을 못 읽으면 빨강', () => {
+  for (const [label, path] of Object.entries(SOURCES)) {
+    const src = bare(path)
+    assert.ok(src.length > 1000, `${label} 원문이 ${src.length}자다 — 경로가 틀렸다`)
+  }
+})