@things-factory/headless-twin 10.0.15 → 10.0.18

package/test/connector-capability-declaration.test.ts

@@ -0,0 +1,88 @@
+/*
+ * ★ 구현했는데 선언하지 않은 능력을 아무도 말해 주지 않았다.
+ *
+ * ── 무엇이 났나 (2026-08-25) ────────────────────────────────────────────────
+ * 능력 판정은 **한 방향만** 본다. 선언했는데 구현이 없는 것은 걸러 내고, 구현했는데 선언이 없는 것은
+ * 들어온 것이 없다. 그래서 태양광 발전소를 붙이던 사람이 이렇게 막혔다.
+ *
+ *   커넥터가 openLiveFeed 를 구현했다 · capabilities: ['live'] 를 잊었다
+ *   → 연결 화면이 「이 원본은 라이브를 못 낸다」로 읽는다
+ *   → 재기동 정책을 정할 수 없어 트윈 생성이 거절된다
+ *   → 화면에 보이는 것은 「재기동 정책이 없습니다」뿐이다
+ *
+ * 원인을 찾는 데 코드를 뒤져야 했다. 지금 저장소에 같은 상태인 커넥터가 일곱이다.
+ *
+ * ── 막지 않고 알린다 ────────────────────────────────────────────────────────
+ * 등록에서 던지면 커넥터 하나 때문에 호스트가 못 뜬다. 만들다 만 커넥터를 들고 있는 사람이 아무것도
+ * 못 하게 된다. 이 어긋남은 고칠 수 있는 것이지 위험한 것이 아니다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+/* `twinWarn` 은 `console.warn` 으로 나간다 — 모듈을 바꿔치지 않고 그 자리에서 받는다. */
+const warnings: string[] = []
+const originalWarn = console.warn
+console.warn = (...args: unknown[]) => {
+  warnings.push(args.join(' '))
+}
+process.on('exit', () => (console.warn = originalWarn))
+
+const { registerAdapterType, capabilitiesOf } = await import('../server/service/reference/reference-adapter.js')
+
+const adapter = (over: Record<string, unknown> = {}) =>
+  ({
+    type: `probe-${Math.round(performance.now() * 1000)}-${warnings.length}`,
+    async fetchMaster() {
+      return {} as any
+    },
+    ...over
+  }) as any
+
+test('★ 라이브를 구현하고 선언하지 않으면 말해 준다 — 이것이 없어서 화면이 다른 말을 했다', () => {
+  const before = warnings.length
+  const a = adapter({ openLiveFeed: () => () => {} })
+  registerAdapterType(a)
+  const said = warnings.slice(before).join('\n')
+  assert.ok(said.includes(a.type), '어느 커넥터인지 말한다')
+  assert.ok(said.includes('live'), '무엇이 빠졌는지 말한다')
+  assert.ok(said.includes('capabilities'), '무엇을 하면 되는지 말한다')
+  /* 그리고 지금 화면이 어떻게 읽는지도 말한다 — 사람이 겪은 증상과 이어져야 원인으로 읽힌다. */
+  assert.ok(/live twin cannot be created/.test(said))
+})
+
+test('★ 조치를 구현하고 선언하지 않아도 말해 준다 — 같은 규율이다', () => {
+  const before = warnings.length
+  const a = adapter({ control: async () => ({ ok: true }) })
+  registerAdapterType(a)
+  assert.ok(warnings.slice(before).join('\n').includes('control'))
+})
+
+test('둘 다 어긋나면 둘 다 말한다 — 하나만 말하면 고친 뒤 또 막힌다', () => {
+  const before = warnings.length
+  const a = adapter({ openLiveFeed: () => () => {}, control: async () => ({ ok: true }) })
+  registerAdapterType(a)
+  const said = warnings.slice(before).join('\n')
+  assert.ok(said.includes('live') && said.includes('control'))
+})
+
+test('선언과 구현이 맞으면 아무 말도 하지 않는다 — 소음이 되면 아무도 읽지 않는다', () => {
+  const before = warnings.length
+  registerAdapterType(adapter({ openLiveFeed: () => () => {}, capabilities: ['live'] }))
+  registerAdapterType(adapter({}))
+  assert.equal(warnings.length, before)
+})
+
+test('선언했는데 구현이 없는 쪽은 판정이 이미 걸러 낸다 — 여기서 두 번 말하지 않는다', () => {
+  const before = warnings.length
+  const a = adapter({ capabilities: ['live'] })
+  registerAdapterType(a)
+  assert.equal(warnings.length, before, '등록은 들어온 것이 없다')
+  assert.deepEqual(capabilitiesOf(a), [], '능력 판정이 구현 없는 선언을 걸러 낸다')
+})
+
+test('★ 등록을 막지 않는다 — 커넥터 하나 때문에 호스트가 못 뜨면 안 된다', () => {
+  const a = adapter({ openLiveFeed: () => () => {} })
+  assert.doesNotThrow(() => registerAdapterType(a))
+  /* 등록은 되었고, 다만 그 능력은 선언되지 않았으므로 판정에서 빠진다 — 그 사실이 경고와 짝이다. */
+  assert.deepEqual(capabilitiesOf(a), [])
+})

package/test/contract-layer-guard.test.ts

@@ -0,0 +1,48 @@
+/*
+ * **층이 이름만 남지 않게 한다** — 계약은 계약 패키지에서 온다.
+ *
+ * ── 왜 있나 (2026-08-30) ──────────────────────────────────────────────────
+ * 어휘와 판별 함수를 `@operato/ops-contract` 로 갈라냈다. 사실을 만드는 쪽(MES · WMS · 커넥터)이
+ * 엔진을 의존하지 않게 하기 위해서다.
+ *
+ * ── 처음에는 커널이 계약을 다시 내보냈다 ──────────────────────────────────
+ * 이유는 「이 저장소를 한 줄도 안 고쳐도 되게」였다. 그것은 **관리 편의**이지 구조의 근거가 아니다.
+ * 그렇게 두면 같은 이름을 두 경로로 가져올 수 있고, 새 코드가 편한 쪽을 쓰면 계약이 커널 뒤에 숨는다.
+ *
+ * 그때는 이 파일에 **세는 시험**이 있었다 — 커널 경로로 가져오는 자리가 늘지 않는지 보는 것이다.
+ * 세는 시험은 층이 깨졌다는 것을 인정하고 빚을 재는 도구다. 재export 를 걷으면서 그 시험도 없앴다.
+ *
+ * 지금 남은 것은 **사실을 확인하는 것**뿐이다. 커널이 계약을 내보내지 않으므로 잘못된 경로는 아예
+ * 컴파일되지 않는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import * as contract from '@operato/ops-contract'
+import * as kernel from '@operato/twin-kernel'
+
+test('★ 계약 패키지가 어휘를 내보낸다', () => {
+  const names = Object.keys(contract)
+  assert.ok(names.length > 100, `계약이 내보내는 이름이 ${names.length}개뿐이다 — 설치가 잘못됐다`)
+  for (const must of ['isEnergyRecord', 'ENERGY_EVENT', 'effectivityAt', 'ingestMasterData', 'procedureViolations']) {
+    assert.ok(names.includes(must), `${must} 가 계약에 없다`)
+  }
+})
+
+test('★ 커널은 계약을 다시 내보내지 않는다 — 내보내면 어휘가 엔진 뒤에 숨는다', () => {
+  const contractNames = new Set(Object.keys(contract))
+  const leaked = Object.keys(kernel).filter(n => contractNames.has(n))
+  assert.deepEqual(
+    leaked,
+    [],
+    `커널이 계약 이름을 다시 내보낸다:\n${leaked.slice(0, 20).join(', ')}\n` +
+      '두 경로로 가져올 수 있게 되면 새 코드가 편한 쪽을 쓰고, 사실을 만들기만 하는 쪽이 엔진을 의존하게 된다.'
+  )
+})
+
+test('커널은 엔진을 내보낸다 — 걷어내다가 필요한 것까지 걷지 않았는지 본다', () => {
+  const names = Object.keys(kernel)
+  for (const must of ['EmsKernel', 'MesKernel', 'WmsKernel', 'YmsKernel', 'StateProjector']) {
+    assert.ok(names.includes(must), `${must} 가 커널에 없다`)
+  }
+})

package/test/control-capability.test.ts

@@ -12,7 +12,7 @@
  * 이 시험이 지키는 것:
  *  ① 선언과 구현이 **함께** 있어야 능력이다 — 선언만 있으면 화면이 거짓말을 하고, 구현만 있으면 닫아 둔
  *    문을 여는 것이다(선언이 권위다).
- *  ② 능력 없는 원본은 **사유 코드로** 거절한다(조용한 실패 금지).
+ *  ② 능력 없는 원본은 **사유 코드로** 거절한다(들어온 것이 없는 실패 금지).
  *  ③ 없는 기능을 있는 것처럼 답하지 않는다(내장 시뮬은 아직 재씨앗을 못 한다).
  */
 import { test } from 'node:test'

package/test/cursor-stall-not-read-failure.test.ts

@@ -76,9 +76,9 @@ test('「몇 번·언제부터」를 정체 쪽도 든다 — 한 번 밀린 것
 
 test('뷰로 나간다 — **유입이 없는 갈래에서도**', () => {
   /*
-   * ★ 여기가 가장 조용해지기 쉬운 자리다. 커서가 막히면 유입이 0이므로 장부가 「빈 장부」 갈래를
+   * ★ 여기가 아무 신호도 나지 않기 가장 쉬운 자리다. 커서가 막히면 유입이 0이므로 장부가 「빈 장부」 갈래를
    * 지나고, 그 갈래에서 이 값을 떨어뜨리면 **정체가 실제로 일어나는 바로 그 상황에서** 침묵한다.
-   * `unhandled` 를 스냅샷이 떨어뜨려 정합성 검사가 영원히 조용했던 것과 같은 부류다.
+   * `unhandled` 를 스냅샷이 떨어뜨려 정합성 검사가 영원히 아무 신호도 내지 않았던 것과 같은 부류다.
    */
   const l = newIngestLedger()
   recordCursorStall(l, 'one timestamp holds more rows than a page', T0, 'trace')

package/test/declaration-reaches-model.test.ts

@@ -5,7 +5,7 @@
  * 커널 쪽에는 같은 이름의 하네스가 있다(kernel/test/declaration-in-state: 선언 ⊆ 상태). 그런데 사실이
  * 새던 자리는 그 앞에도 있었다: **레퍼런스 마스터 → 커널 모델** 이라는 문 하나(`masterToTwin`).
  *
- * 여기서 새면 아무도 모른다. 원본은 말했고, 화면은 조용히 id 를 보인다. 실제로 그렇게 잃었다 —
+ * 여기서 새면 아무도 모른다. 원본은 말했고, 화면은 알리지 않고 id 를 보인다. 실제로 그렇게 잃었다 —
  * 자리의 이름(화면이 `cut-station` 을 찍었다), 사람의 이름, GS1 참조, 자원 속성, 시험 명세 참조,
  * 사람·설비의 시험 결과. 하루 사이에 여섯 번이고, 전부 **한 줄에서 필드 하나가 빠진** 것이었다.
  *
@@ -21,7 +21,7 @@
  * 셋 중 어느 것도 아니면 실패한다 — 새 필드를 추가한 사람이 그때 분류해야 한다. 분류를 강제하는 것이
  * 이 검사의 전부다: 잊는 것이 기본값이면 잊는다.
  *
- * 필드 목록은 **소스에서 읽는다**(손으로 적지 않는다). 손으로 적으면 새 필드가 조용히 빠지고, 그것이
+ * 필드 목록은 **소스에서 읽는다**(손으로 적지 않는다). 손으로 적으면 새 필드가 알리지 않고 빠지고, 그것이
  * 바로 이 검사가 막으려는 실패다.
  */
 import { test } from 'node:test'
@@ -70,7 +70,7 @@ const ELSEWHERE: Record<string, string> = {
   footprint: '좌표는 `model.layout`(중심점)과 구역 기하로 간다 — 자리 줄에 실리는 값이 아니다.'
 }
 
-/** 모든 필드에 값을 실은 원본 — 값을 모르는 필드가 나오면 이 하네스는 실패한다(조용히 건너뛰지 않는다). */
+/** 모든 필드에 값을 실은 원본 — 값을 모르는 필드가 나오면 이 하네스는 실패한다(알리지 않고 건너뛰지 않는다). */
 const VALUE: Record<string, unknown> = {
   id: '__ID__',
   type: 'cut-station',
@@ -86,6 +86,8 @@ const VALUE: Record<string, unknown> = {
   level: 'WorkCenter',
   footprint: { x: 1, y: 2, w: 3, h: 4 },
   gs1Id: 'urn:epc:id:sgln:0614141.00001.0',
+  /* 설비의 정체성 — **GS1 키가 아닌 것이 정상이다**(실측: 인버터 하드웨어 식별자). */
+  identity: 'ES100000007d8d061d-1',
   homeLocationId: 'cut-station',
   mtbfMs: 600000,
   mttrMs: 60000,
@@ -122,7 +124,7 @@ function build(c: Case): any {
     assert.ok(
       f in VALUE,
       `픽스처가 "${c.iface}.${f}" 에 실을 값을 모른다 — VALUE 에 하나 적어라.\n` +
-        '조용히 건너뛰면 그 필드는 아무도 안 보는 필드가 되고, 그것이 이 하네스가 막으려는 실패다.'
+        '알리지 않고 건너뛰면 그 필드는 아무도 안 보는 필드가 되고, 그것이 이 하네스가 막으려는 실패다.'
     )
     o[f] = f === 'id' ? c.id : VALUE[f]
   }
@@ -171,7 +173,7 @@ for (const c of CASES) {
       { lost, mangled },
       { lost: [], mangled: [] },
       `${c.iface}: 잃은 사실=[${lost}] · 옮기다 값이 바뀐 사실=[${mangled}]\n` +
-        '원본이 말한 것을 문에서 버리면 아무도 모른다 — 화면은 조용히 id 를 보인다.\n' +
+        '원본이 말한 것을 문에서 버리면 아무도 모른다 — 화면은 알리지 않고 id 를 보인다.\n' +
         '일부러 다른 길로 보내는 것이면 ELSEWHERE 에 그 길을 적어라(이름만 바뀌는 것은 RENAMED).'
     )
   })

package/test/declared-stimulus.test.ts

@@ -12,7 +12,7 @@
  * 첫 조각(`openLiveFeed`)이 같은 선언을 그대로 읽는다.
  *
  * 이 시험이 지키는 것:
- *  ① 선언이 없으면 조용히 지난다(정적 구조만 반영하는 트윈이 정상이다).
+ *  ① 선언이 없으면 알리지 않고 지난다(정적 구조만 반영하는 트윈이 정상이다).
  *  ② **미러에는 싣지 않는다** — 외부 실물이 진실인 트윈에 도착을 지어 주면 그것은 현실이 아니다.
  *  ③ 검사를 통과하지 못한 선언은 **태우지 않고** 이유를 남긴다(잘못된 선언 하나가 서버를 내린 이력이 있다).
  *  ④ 검사기가 없으면 싣지 않는다 — 검사할 수 없는 선언을 태우는 것이 가장 비싼 선택이다.
@@ -30,7 +30,7 @@ const ok = () => ({ ok: true as const })
 const bad = () => ({ ok: false as const, errorCode: 'scenario-sku-mix-required' })
 const sim = { hasScenarioEngine: true, mode: 'sim' as const }
 
-test('선언이 없으면 조용히 지난다 — 구조만 반영하는 트윈이 정상이다', () => {
+test('선언이 없으면 알리지 않고 지난다 — 구조만 반영하는 트윈이 정상이다', () => {
   assert.deepEqual(planStimulus(undefined, sim, ok), { action: 'skip', reason: 'none' })
   assert.deepEqual(planStimulus({ endpoint: 'x' }, sim, ok), { action: 'skip', reason: 'none' })
   /* 시나리오 자리에 객체가 아닌 것이 오면 선언이 아니다(문자열을 시나리오로 읽지 않는다). */
@@ -42,7 +42,7 @@ test('관측으로 도는 트윈에는 싣지 않는다 — 현실을 지어내
   assert.deepEqual(plan, { action: 'skip', reason: 'observed' })
 })
 
-test('시나리오 엔진이 없으면 싣지 않는다 — 조용히 아무 일도 없게 두지 않는다', () => {
+test('시나리오 엔진이 없으면 싣지 않는다 — 알리지 않고 아무 일도 없게 두지 않는다', () => {
   const plan = planStimulus({ scenario }, { hasScenarioEngine: false, mode: 'sim' }, ok)
   assert.deepEqual(plan, { action: 'skip', reason: 'no-engine' })
 })
@@ -73,7 +73,7 @@ test('선언을 얹으면서 접속 정보를 지우지 않는다', () => {
 /*
  * ── 배선 (소스로 지킨다) ────────────────────────────────────────────────────
  * 판정은 순수 함수가 하지만, 그것을 **기동 때 부르지 않으면** 아무 일도 일어나지 않는다. 그리고 못 실은
- * 이유는 말해야 한다 — 「선언했는데 안 실렸다」가 조용하면 사용자는 트윈이 고장 난 줄로 읽는다.
+ * 이유는 말해야 한다 — 「선언했는데 안 실렸다」를 말하지 않으면 사용자는 트윈이 고장 난 줄로 읽는다.
  */
 test('두 기동 경로에서 부른다 — 시뮬은 싣고, 미러는 그 사실을 말한다', () => {
   const src = readFileSync(fileURLToPath(new URL('../server/engine/twin-engine.ts', import.meta.url)), 'utf-8')

package/test/discovery-result.test.ts

@@ -2,7 +2,7 @@
  * 사이트 발견 결과 — **"못 찾았다" 를 "없다" 로 말하지 않게.**
  *
  * 실 시스템을 연결해 트윈을 만드는 경로에서, 발견이 실패하면 화면이 "사이트를 찾지 못했습니다" 라고만
- * 말했다. 레퍼런스 미등록·어댑터 미상·조회 실패·정말 0건이 그 한 문장으로 접혀 있었다 — 자격이
+ * 말했다. 레퍼런스 미등록·어댑터 미상·조회 실패·정말 0건이 그 한 문장에 섞여 있었다 — 자격이
  * 틀렸는지 주소가 틀렸는지 알 수 없었다.
  */
 import { test } from 'node:test'
@@ -50,7 +50,7 @@ test('네 가지 사유가 서로 구별된다 — 이것이 이 작업의 요
     discoveryTimedOut('s', 15).code
   ]
   assert.deepEqual(codes, ['reference-not-found', 'adapter-unknown', 'discovery-failed', 'discovery-timeout'])
-  assert.equal(new Set(codes).size, 4, '넷이 한 코드로 접히지 않는다')
+  assert.equal(new Set(codes).size, 4, '넷이 한 코드로 합쳐지지 않는다')
 })
 
 test('원 시스템이 준 사유를 감추지 않는다 — 사용자가 관리자에게 물어볼 수 있게', () => {

package/test/entity-delta.test.ts

@@ -3,10 +3,10 @@
  *
  * 지키는 것(2026-08-01 재편):
  *  ① **레퍼런스가 아는 것은 전부 나간다** — 필드를 손으로 골라 담지 않는다. 화이트리스트였을 때
- *     노드 parentId·작업 전량·물품 전량이 조용히 누락됐다. 계약에 속성이 생기면 자동으로 도달해야 한다.
+ *     노드 parentId·작업 전량·물품 전량이 오류 없이 빠졌다. 계약에 속성이 생기면 자동으로 도달해야 한다.
  *  ② **표식은 도메인 낱말을 훔치지 않는다** — 엔티티 종류 표식은 `entity`, `kind` 는 도메인 것
  *     (무버 cutter · 작업 putaway · 오더 workorder).
- *  ③ **조용히 자르지 않는다** — 물품 집약이 상한에 걸리면 total·truncated 로 밝힌다.
+ *  ③ **알리지 않고 자르지 않는다** — 물품 집약이 상한에 걸리면 total·truncated 로 밝힌다.
  */
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
@@ -111,7 +111,7 @@ test('물품: 개별(태그=epc) + 집약으로 나간다 — 수량·소속 팔
   assert.equal(agg.truncated, undefined, '상한 안이면 truncated 없음')
 })
 
-test('물품 집약: 상한을 넘으면 잘린 사실을 밝힌다 — 조용한 절단 금지', () => {
+test('물품 집약: 상한을 넘으면 잘린 사실을 밝힌다 — 들어온 것이 없는 절단 금지', () => {
   const items = Array.from({ length: ITEMS_AGGREGATE_LIMIT + 7 }, (_, i) => ({ epc: `e${i}`, location: 'rack-1' }))
   const d = buildEntityDeltas({ items }, 't1')
   const agg = byTag(d, itemsTag('t1')).data
@@ -236,7 +236,7 @@ test('수요 구간·피크·계약은 집약 태그로 나간다 — 개체의
   assert.equal(agg.data.peakSince.kW, 4200)
   /* 하루치를 매 브로드캐스팅에 실으면 채널이 그것으로 찬다 — 최근 것만 내고 전체 수를 함께 낸다. */
   assert.equal(agg.data.recent.length, 8)
-  assert.equal(agg.data.closedTotal, 137, '자른 사실을 조용히 두지 않는다')
+  assert.equal(agg.data.closedTotal, 137, '자른 사실을 알리지 않고 두지 않는다')
 })
 
 test('에너지가 없는 트윈은 에너지 태그를 내지 않는다 — 없는 것을 만들지 않는다', () => {

package/test/equipment-identity-reaches.test.ts

@@ -0,0 +1,57 @@
+/*
+ * **선언한 설비 정체성이 투영까지 닿는가** — 선언에서 화면까지 걸어 본다.
+ *
+ * ── 무엇이 있었나 (2026-08-30) ────────────────────────────────────────────
+ * 투영이 `m.gs1Id` 를 읽고 있었는데 **선언에 그런 필드가 없었다.** 그래서 그 칸은 일곱 대 모두 영원히
+ * 비어 있었다. 오류는 나지 않았다 — `?? null` 이 늘 `null` 을 냈을 뿐이다.
+ *
+ * 값은 한 칸 옆에 있었다. 커넥터가 인버터의 하드웨어 식별자를 속성으로 이미 보내고 있었고
+ * (`properties.deviceId = ES100000007d8d061d-1`), 정체성 칸도 있었는데 **그 사이에 길이 없었다.**
+ *
+ * 이 저장소에서 가장 자주 나는 결함 부류다. 그래서 필드를 여는 것으로 끝내지 않고 **선언 → 투영**을
+ * 실제로 걸어 본다. 필드만 있고 길이 없으면 여기서 빨갛게 난다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+import type { TwinModelDef } from '@operato/ops-contract'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const src = (p: string) => readFileSync(join(here, '..', 'server', p), 'utf-8')
+
+test('★ 선언에 정체성 자리가 있다', () => {
+  /* 타입이 받아들이면 선언에 자리가 있는 것이다 — 없으면 이 파일이 컴파일되지 않는다. */
+  const model: TwinModelDef = {
+    locations: [{ id: 'incoming', type: 'incoming' }],
+    equipment: [{ id: '001', kind: 'pv-array', homeLocation: 'incoming', identity: 'ES100000007d8d061d-1' }]
+  } as any
+  assert.equal((model.equipment?.[0] as any).identity, 'ES100000007d8d061d-1')
+})
+
+test('★ 투영이 그 자리를 읽는다 — 선언에 없는 이름을 읽으면 칸이 영원히 빈다', () => {
+  const projection = src('service/twin-model/project-structure.ts')
+  assert.match(
+    projection,
+    /identity:\s*\(m as any\)\.identity/,
+    '설비 투영이 선언의 identity 를 읽어야 한다. 다른 이름을 읽으면 그 칸은 늘 null 이다.'
+  )
+  assert.doesNotMatch(
+    projection,
+    /gs1Id:\s*m\.gs1Id/,
+    '설비 선언에 gs1Id 는 없다 — 읽으면 늘 null 이 된다(2026-08-30 실측: 일곱 대 모두 비어 있었다)'
+  )
+})
+
+test('★ 저장 자리의 이름이 선언과 같다 — 두 벌이면 한쪽만 고쳐진다', () => {
+  const entity = src('service/twin-model/twin-equipment.ts')
+  assert.match(entity, /identity\?: string/, '설비 행에 identity 칸이 있어야 한다')
+  assert.doesNotMatch(entity, /gs1Id\?: string/, '설비에서는 gs1Id 를 쓰지 않는다 — 정체성이 GS1 키가 아닌 것이 정상이다')
+})
+
+test('자리(location)의 gs1Id 는 그대로 둔다 — 그쪽은 실제로 SGLN 이 온다', () => {
+  const entity = src('service/twin-model/twin-location.ts')
+  assert.match(entity, /gs1Id\?: string/, '자리는 GS1 키를 받는다 — 설비와 같은 이유로 지우면 안 된다')
+})

package/test/event-subjects.test.ts

@@ -0,0 +1,147 @@
+/*
+ * ★ 사건 하나가 무엇을 가리키는지 뽑는다 — 360 이력이 64초인 원인을 없애는 첫 조각.
+ *
+ * ── 왜 이 모양인가 (2026-08-27 실측) ────────────────────────────────────────
+ * 「이 품목의 이력」 조회가 64초다. 저장된 식별자에 품목과 로트가 한 문자열로 붙어 있어서, 품목만으로는
+ * 찾을 방법이 없다.
+ *
+ *   https://seunghwa.net/class/product-M0000618-lot-L2604100071
+ *
+ * 문자열을 자르는 규칙을 여기에 넣지 않는다 — 어느 부호가 로트를 가리키는지 연결된 시스템마다 다르고,
+ * chef 의 `-lot-` 을 굳히면 이 파일이 그 시스템 위에 서게 된다. 대신 대상마다 한 줄을 적고, 품목이
+ * 무엇인지는 그 트윈의 선언과 견주어 부르는 쪽이 답한다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { subjectsOf, SUBJECT_KINDS } from '../server/service/twin-subject/event-subjects.js'
+
+const objectEvent = (over: any = {}) => ({
+  eventType: 'epcis.ObjectEvent',
+  eventTime: '2026-08-27T05:00:00.000Z',
+  data: {
+    epcList: ['https://seunghwa.net/class/product-M0000438-lot-L2403090386'],
+    bizLocation: { id: 'M2R0001' },
+    action: 'OBSERVE',
+    ...over
+  }
+})
+
+const find = (subjects: any[], kind: string) => subjects.filter(s => s.kind === kind).map(s => s.id)
+
+test('★ 품목과 로트를 두 줄로 적는다 — 문자열을 자르지 않고도 품목으로 찾을 수 있다', () => {
+  const subjects = subjectsOf(objectEvent(), {
+    /* 선언과 견주어 품목을 찾는 일은 부르는 쪽이 한다 — 그 트윈의 선언을 아는 것이 그쪽이다. */
+    itemOf: epc => (epc.includes('product-M0000438') ? 'M0000438' : null)
+  })
+  assert.deepEqual(find(subjects, 'lot'), ['https://seunghwa.net/class/product-M0000438-lot-L2403090386'])
+  assert.deepEqual(find(subjects, 'item'), ['M0000438'])
+})
+
+test('★ 품목을 찾지 못하면 품목 줄을 만들지 않는다 — 짐작으로 이으면 남의 이력에 섞인다', () => {
+  const subjects = subjectsOf(objectEvent(), { itemOf: () => null })
+  assert.equal(find(subjects, 'lot').length, 1, '개체는 그대로 적는다')
+  assert.deepEqual(find(subjects, 'item'), [], '품목은 비운다')
+})
+
+test('★ 찾은 값이 개체 식별자와 같으면 품목이 아니다 — itemRefOf 는 URI 를 그대로 돌려준다', () => {
+  /*
+   * `itemRefOf` 는 SGTIN 이 아닌 모양에서 문자열을 그대로 낸다(자르는 판단을 하지 않으므로). 그 값을
+   * 품목으로 적으면 로트와 같은 줄이 두 종류로 생기고, 품목 이력이 로트 이력과 같아진다.
+   */
+  const epc = 'https://seunghwa.net/class/product-M0000438-lot-L2403090386'
+  const subjects = subjectsOf(objectEvent(), { itemOf: () => epc })
+  assert.deepEqual(find(subjects, 'item'), [])
+})
+
+test('★ 한 사건이 여러 대상을 가리킨다 — 자리·설비·오더·작업', () => {
+  const subjects = subjectsOf({
+    eventType: 'task.status',
+    eventTime: '2026-08-27T05:00:00.000Z',
+    data: { taskId: 'tk-1', moverId: 'mixer-1', toNode: 'M2R0001', orderId: 'ORD-9' }
+  })
+  assert.deepEqual(find(subjects, 'task'), ['tk-1'])
+  assert.deepEqual(find(subjects, 'equipment'), ['mixer-1'])
+  assert.deepEqual(find(subjects, 'order'), ['ORD-9'])
+  assert.ok(find(subjects, 'location').length <= 1, '자리는 한 줄이다')
+})
+
+test('★ 가리키는 것이 없으면 빈 배열이다 — 없는 대상을 만들지 않는다', () => {
+  const subjects = subjectsOf({ eventType: 'energy.demand.window', data: { maxKW: 3 } })
+  assert.deepEqual(subjects, [])
+})
+
+test('★ 작업이 오간 두 자리를 다 적는다 — 승격 컬럼은 둘 중 하나만 담을 수 있어 비워 둔다', () => {
+  /*
+   * `locationOf` 는 EPCIS 자리만 읽는다. 작업이 A→B 로 갈 때 컬럼 하나에 둘을 넣을 수 없으므로
+   * 아무것도 넣지 않는다. 이 표는 자리마다 줄이 하나라서 둘을 함께 담는다.
+   */
+  const subjects = subjectsOf({
+    eventType: 'task.status',
+    data: { taskId: 'tk-1', fromNode: 'M2R0001', toNode: 'M2R0002' }
+  })
+  assert.deepEqual(find(subjects, 'location'), ['M2R0001', 'M2R0002'])
+})
+
+test('★ 같은 대상을 두 번 적지 않는다 — 출발지와 도착지가 같을 수 있다', () => {
+  const subjects = subjectsOf({
+    eventType: 'task.status',
+    data: { taskId: 'tk-1', fromNode: 'M2R0001', toNode: 'M2R0001' }
+  })
+  assert.deepEqual(find(subjects, 'location'), ['M2R0001'])
+})
+
+test('종류 목록이 닫혀 있다 — 열어 두면 넣는 쪽마다 다른 이름을 쓴다', () => {
+  assert.deepEqual([...SUBJECT_KINDS], ['item', 'lot', 'order', 'location', 'equipment', 'task'])
+})
+
+test('너무 긴 식별자는 적지 않는다 — 자르면 그 줄이 다른 대상을 가리킨다', () => {
+  const long = 'x'.repeat(300)
+  const subjects = subjectsOf({ eventType: 'task.status', data: { taskId: long } })
+  assert.deepEqual(find(subjects, 'task'), [], '알리지 않고 자르지 않고 아예 만들지 않는다')
+})
+
+test('빈 값과 공백은 대상이 아니다 — 결측을 대상으로 만들지 않는다', () => {
+  const subjects = subjectsOf({ eventType: 'task.status', data: { taskId: '   ', moverId: '' } })
+  assert.deepEqual(subjects, [])
+})
+
+test('★ 클래스로 온 사건은 품목 줄만 만든다 — 개체가 없는 사건이다', () => {
+  /*
+   * 실측한 chef 의 사건이다. 무게로 담는 현장이라 개체 목록이 비어 있고 수량 목록에 클래스가 있다.
+   * 그것을 로트로 적으면 뜻이 틀린다 — 개체가 아니라 품목이다.
+   */
+  const subjects = subjectsOf({
+    eventType: 'epcis.ObjectEvent',
+    data: {
+      epcList: [],
+      quantityList: [{ epcClass: 'https://seunghwa.net/class/product-M0000879', quantity: 11797.6, uom: 'KGM' }],
+      bizLocation: { id: 'P2F0001' }
+    }
+  })
+  assert.deepEqual(find(subjects, 'lot'), [], '개체 줄을 만들지 않는다')
+  assert.deepEqual(find(subjects, 'item'), ['https://seunghwa.net/class/product-M0000879'])
+  assert.deepEqual(find(subjects, 'location'), ['P2F0001'])
+})
+
+test('★ 클래스도 선언과 견주어 품목 코드로 줄인다 — 선언이 답하면 그것을 쓴다', () => {
+  const subjects = subjectsOf(
+    {
+      eventType: 'epcis.ObjectEvent',
+      data: { epcList: [], quantityList: [{ epcClass: 'https://seunghwa.net/class/product-M0000879' }] }
+    },
+    { itemOf: epc => (epc.includes('M0000879') ? 'M0000879' : null) }
+  )
+  assert.deepEqual(find(subjects, 'item'), ['M0000879'])
+})
+
+test('개체와 클래스가 함께 오면 둘 다 적는다 — 한 사건이 둘을 가리킬 수 있다', () => {
+  const subjects = subjectsOf({
+    eventType: 'epcis.ObjectEvent',
+    data: {
+      epcList: ['https://seunghwa.net/class/product-M0000438-lot-L1'],
+      quantityList: [{ epcClass: 'https://seunghwa.net/class/product-M0000879' }]
+    }
+  })
+  assert.deepEqual(find(subjects, 'lot'), ['https://seunghwa.net/class/product-M0000438-lot-L1'])
+  assert.deepEqual(find(subjects, 'item'), ['https://seunghwa.net/class/product-M0000879'])
+})

package/test/event-time-column.test.ts

@@ -5,9 +5,9 @@
  * 예전에는 문자열 컬럼이었고, "UTC ISO 만 들어오니 사전식 비교가 맞는다" 는 전제 위에서 정렬·범위
  * 질의가 돌았다. 그 전제는 컬럼 어디에도 적혀 있지 않았다.
  *
- * 날짜 컬럼으로 바꾸면서 **조용한 함정**이 하나 드러났다: sqlite 는 datetime 을 공백 구분 형식
+ * 날짜 컬럼으로 바꾸면서 **들어온 것이 없는 함정**이 하나 드러났다: sqlite 는 datetime 을 공백 구분 형식
  * (`2026-08-07 11:00:00.000`)으로 저장하는데, 화면은 ISO 문자열(`…T11:00:00.000Z`)을 보낸다.
- * 문자열 그대로 비교하면 사전식으로 어긋나 **오류 없이 0건**이 나온다 — 원장 시간창이 조용히
+ * 문자열 그대로 비교하면 사전식으로 어긋나 **오류 없이 0건**이 나온다 — 원장 시간창이 알리지 않고
  * 비어 버리고, 사용자는 "그 시간에 아무 일도 없었다" 로 읽는다.
  *
  * 그래서 두 가지를 못 박는다: 저장 형식이 실제로 그렇다는 것과, 경계에서 날짜로 옮기면 걸린다는 것.
@@ -48,7 +48,7 @@ test('sqlite 는 datetime 을 공백 구분 형식으로 저장한다 — ISO
   await ds.destroy()
 })
 
-test('ISO 문자열을 그대로 넘기면 **조용히 0건** — 오류가 아니라 빈 결과라 더 위험하다', async () => {
+test('ISO 문자열을 그대로 넘기면 **알리지 않고 0건** — 오류가 아니라 빈 결과라 더 위험하다', async () => {
   const { ds, repo } = await seeded()
   const rows = await repo.find({
     where: { eventTime: Between('2026-08-07T10:00:00.000Z', '2026-08-07T12:00:00.000Z') }