@things-factory/headless-twin 10.0.12 → 10.0.14

package/test/ingest-history.test.ts

@@ -0,0 +1,247 @@
+/*
+ * ★ 인제스트 이력 — **재기동 뒤에도 추이가 이어진다.**
+ *
+ * ── 무엇이 미완이었나 (2026-08-20) ──────────────────────────────────────────
+ * 닫힌 창을 표로 남기기 시작했는데 **읽는 코드가 없었다.** 21행이 쌓여 있고 아무도 보지 않았다 —
+ * 이 프로젝트가 결함으로 보는 상태다(「필드만 만들고 아무도 읽지 않는다」). 표를 만든 이유가
+ * 「메모리 장부는 재기동에 사라지고 6시간까지인데 추이는 그보다 오래 봐야 한다」였으니 목적이
+ * 절반만 서 있었다.
+ *
+ * ── 지키는 것 ───────────────────────────────────────────────────────────────
+ * ① 표와 메모리를 이어 붙이되 **겹친 창을 두 번 내지 않는다** — 같은 구간이 두 번 그려지면 추이가
+ *    거짓이 된다. 겹치면 메모리 쪽을 쓴다(같은 사실의 원본이다).
+ * ② 어디서부터 메모리인지 밝힌다(`liveFrom`) — 화면이 근거를 말할 수 있게. 재기동 직후에는 `null`
+ *    이고, 그때 보이는 것은 전부 표에서 온 것이다.
+ * ③ **조용히 자르지 않는다** — 상한에서 밀려난 창 수와, 물은 기간이 잘렸다는 사실을 함께 낸다.
+ * ④ 남의 도메인·남의 트윈의 창을 집지 않는다.
+ * ⑤ 제시가 0 인 창의 통과율은 `null` 이다 — 빈 창은 완벽한 창이 아니다.
+ */
+import { test, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { createRequire } from 'node:module'
+import type { DataSource } from 'typeorm'
+
+const req = createRequire(import.meta.url)
+const { NamingStrategy, addDataSource, entities: shellEntities, Domain } = req('@things-factory/shell')
+const { entities: authEntities } = req('@things-factory/auth-base')
+const { entities: twinEntities } = req('../dist-server/service/index.js')
+const { TwinEngine } = req('../dist-server/engine/index.js')
+const { INGEST_WINDOW_MS } = req('../dist-server/engine/ingest-health.js')
+const { TwinIngestWindow } = req('../dist-server/service/twin-ingest-window/twin-ingest-window.js')
+const { TwinIngestWindowQuery, HISTORY_WINDOW_LIMIT, HISTORY_HOURS_MAX } = req(
+  '../dist-server/service/twin-ingest-window/twin-ingest-window-query.js'
+)
+const { TwinInstance } = req('../dist-server/service/twin-instance/twin-instance.js')
+const { DataSource: TypeOrmDataSource } = req('typeorm')
+
+let ds: DataSource
+let domainId: string
+let otherDomainId: string
+
+const TWIN = 'hist-twin'
+const HOUR = 3_600_000
+
+const resolver = new TwinIngestWindowQuery()
+const ask = (instanceId: string, hours?: number, domain = domainId) =>
+  resolver.twinIngestHistory(instanceId, hours, { state: { domain: { id: domain } } } as any)
+
+/** 표에 닫힌 창 하나 — 시각은 「몇 시간 전」으로 준다. */
+async function storedWindow(instanceId: string, hoursAgo: number, offered: number, rejected = 0, domain = domainId) {
+  const closed = new Date(Date.now() - hoursAgo * HOUR)
+  const opened = new Date(closed.getTime() - 600_000)
+  const repo = ds.getRepository(TwinIngestWindow)
+  await repo.save(
+    repo.create({
+      domain: { id: domain } as any,
+      instanceId,
+      openedAt: opened,
+      closedAt: closed,
+      offered,
+      rejected,
+      undelivered: 0,
+      journaledRows: 0,
+      journalFlushes: 0,
+      ...(offered > 0 ? { acceptedRatio: (offered - rejected) / offered } : {})
+    } as any)
+  )
+  return opened.toISOString()
+}
+
+async function instance(instanceId: string, domain = domainId) {
+  const repo = ds.getRepository(TwinInstance)
+  await repo.save(
+    repo.create({
+      domain: { id: domain } as any,
+      instanceId,
+      spaceId: 'hist-space',
+      kind: 'wms',
+      status: 'stopped',
+      restartPolicy: 'reset',
+      purpose: 'operational'
+    } as any)
+  )
+}
+
+before(async () => {
+  ds = new TypeOrmDataSource({
+    type: 'sqlite',
+    database: ':memory:',
+    synchronize: true,
+    dropSchema: true,
+    namingStrategy: new NamingStrategy(),
+    entities: [...shellEntities, ...authEntities, ...twinEntities],
+    logging: false
+  })
+  await ds.initialize()
+  addDataSource('default', ds)
+
+  domainId = (await ds.getRepository(Domain).save({ name: 'hist', subdomain: 'hist' } as any)).id
+  otherDomainId = (await ds.getRepository(Domain).save({ name: 'hist-other', subdomain: 'hist-other' } as any)).id
+  await instance(TWIN)
+})
+
+after(async () => {
+  await ds?.destroy()
+})
+
+test('표에 남은 창을 읽어 온다 — 재기동으로 메모리가 비어도 추이가 있다', async () => {
+  await storedWindow(TWIN, 5, 100, 4)
+  await storedWindow(TWIN, 3, 200, 0)
+
+  const r = await ask(TWIN)
+  assert.equal(r.windows.length, 2)
+  assert.equal(r.storedCount, 2)
+  assert.equal(r.liveCount, 0, '메모리에는 닫힌 창이 없다(이 트윈은 이 프로세스에서 받은 적이 없다)')
+  assert.equal(r.liveFrom, null, '그래서 「여기서부터 메모리」가 없다 — 0 이나 지금으로 채우지 않는다')
+})
+
+test('오래된 것이 앞, 최신이 뒤 — 추이는 시간순이어야 그림이 된다', async () => {
+  const r = await ask(TWIN)
+  const times = r.windows.map((w: any) => Date.parse(w.from))
+  assert.deepEqual(times, [...times].sort((a, b) => a - b), '오름차순')
+})
+
+test('통과는 트윈에 닿은 것만 — 표의 통과율을 그대로 쓴다', async () => {
+  const r = await ask(TWIN)
+  const w = r.windows.find((x: any) => x.offered === 100)
+  assert.equal(w.rejected, 4)
+  assert.equal(w.accepted, 96)
+  assert.equal(w.acceptedRatio, 0.96)
+})
+
+test('제시가 0 인 창의 통과율은 「없음」이다 — 빈 창은 완벽한 창이 아니다', async () => {
+  await storedWindow(TWIN, 2, 0, 0)
+
+  const r = await ask(TWIN)
+  const empty = r.windows.find((x: any) => x.offered === 0)
+  assert.equal(empty.acceptedRatio, null)
+})
+
+test('물은 기간 밖의 창은 오지 않는다', async () => {
+  await storedWindow(TWIN, 40, 999, 0) // 40시간 전
+
+  const r = await ask(TWIN, 24)
+  assert.ok(
+    !r.windows.some((w: any) => w.offered === 999),
+    '24시간을 물었으면 40시간 전 창은 안 온다'
+  )
+
+  const wide = await ask(TWIN, 48)
+  assert.ok(
+    wide.windows.some((w: any) => w.offered === 999),
+    '48시간을 물으면 온다'
+  )
+})
+
+test('기간 상한을 넘겨 물으면 자르고, 자른 사실을 낸다', async () => {
+  const r = await ask(TWIN, HISTORY_HOURS_MAX + 100)
+
+  assert.equal(r.hours, HISTORY_HOURS_MAX, '상한까지만 본다')
+  assert.equal(r.hoursClamped, HISTORY_HOURS_MAX + 100, '얼마를 물었는지 밝힌다 — 조용히 자르지 않는다')
+})
+
+test('상한 안에서는 잘렸다고 말하지 않는다 — 없는 문제를 만들지 않는다', async () => {
+  const r = await ask(TWIN, 24)
+  assert.equal(r.hoursClamped, undefined)
+  assert.equal(r.storedDropped, 0)
+})
+
+test('창 수 상한에서 밀려난 수를 센다', async () => {
+  const many = 'hist-many'
+  await instance(many)
+  /* 상한 + 5개를 심는다. 10분 간격이므로 상한을 넘기려면 그만큼의 창이 필요하다. */
+  for (let i = 0; i < HISTORY_WINDOW_LIMIT + 5; i++) await storedWindow(many, 1 + i * 0.01, 10, 0)
+
+  const r = await ask(many, HISTORY_HOURS_MAX)
+  assert.equal(r.windows.length, HISTORY_WINDOW_LIMIT, '상한까지만 낸다')
+  assert.equal(r.storedDropped, 5, '밀려난 수를 말한다')
+})
+
+test('남의 도메인 창을 집지 않는다', async () => {
+  await instance('hist-shared', otherDomainId)
+  await storedWindow('hist-shared', 1, 777, 0, otherDomainId)
+
+  /* 같은 instanceId 를 내 도메인에서 물어도 남의 창이 오면 안 된다. */
+  await instance('hist-shared')
+  const mine = await ask('hist-shared')
+  assert.ok(
+    !mine.windows.some((w: any) => w.offered === 777),
+    '남의 도메인 창이 새지 않는다'
+  )
+})
+
+test('내 도메인에 없는 트윈은 「없음」이다 — 남의 것이라 말하지 않는다', async () => {
+  assert.equal(await ask('does-not-exist'), null)
+})
+
+test('겹친 창을 두 번 내지 않는다 — 같은 구간이 두 번 그려지면 추이가 거짓이 된다', async () => {
+  /*
+   * 프로세스가 살아 있는 동안 닫힌 창은 **표와 메모리에 둘 다** 있다(영속 훅이 창이 닫힐 때 쓴다).
+   * 정리하지 않으면 그 구간이 추이에 두 번 들어가 유입이 두 배로 보인다.
+   */
+  const twin = 'hist-overlap'
+  await instance(twin)
+
+  /* 메모리에 닫힌 창 하나를 만든다 — 창은 다음 유입이 있을 때 닫힌다. */
+  const t0 = Date.now() - Math.floor(INGEST_WINDOW_MS * 1.4)
+  TwinEngine.recordIngestResult(domainId, twin, 50, [], t0)
+  TwinEngine.recordIngestResult(domainId, twin, 1, [], t0 + INGEST_WINDOW_MS + 1)
+
+  const live = TwinEngine.ingestHealthOf(domainId, twin).trend
+  assert.equal(live.length, 1, '메모리에 닫힌 창 하나')
+
+  /* 같은 창을 표에도 심는다(영속 훅이 했을 일). 값은 일부러 다르게 두어 어느 쪽이 이겼는지 본다. */
+  const repo = ds.getRepository(TwinIngestWindow)
+  await repo.save(
+    repo.create({
+      domain: { id: domainId } as any,
+      instanceId: twin,
+      openedAt: new Date(Date.parse(live[0].from)),
+      closedAt: new Date(Date.parse(live[0].to)),
+      offered: 999,
+      rejected: 0,
+      undelivered: 0,
+      journaledRows: 0,
+      journalFlushes: 0,
+      acceptedRatio: 1
+    } as any)
+  )
+
+  const r = await ask(twin)
+  const sameStart = r.windows.filter((w: any) => Date.parse(w.from) === Date.parse(live[0].from))
+  assert.equal(sameStart.length, 1, '한 번만 낸다')
+  assert.equal(sameStart[0].source, 'live', '겹치면 메모리 쪽 — 같은 사실의 원본이다')
+  assert.equal(sameStart[0].offered, 50, '표의 999 가 아니라 메모리의 50')
+  assert.equal(r.liveFrom, live[0].from, '어디서부터 메모리인지 밝힌다')
+})
+
+test('겹치지 않는 표의 창은 메모리 앞에 이어 붙는다', async () => {
+  const twin = 'hist-overlap'
+  /* 메모리 창보다 오래된 것 — 이건 표에서만 온다. */
+  await storedWindow(twin, 6, 30, 1)
+
+  const r = await ask(twin)
+  assert.equal(r.windows.length, 2, '표 하나 + 메모리 하나')
+  assert.equal(r.windows[0].source, 'stored', '오래된 것이 앞')
+  assert.equal(r.windows[1].source, 'live')
+})

package/test/integration-probes.test.ts

@@ -0,0 +1,103 @@
+/*
+ * ★ 연결 적합성 하네스 — **절반만 돌린 스위트가 초록을 주장하지 못하게.**
+ *
+ * 지키는 것:
+ *  ① 돌리지 않은 프로브는 **「모른다」**로 접힌다 → 판정이 그 단계를 달성으로 만들지 않는다.
+ *  ② **실패한 프로브의 수를 0 으로 읽지 않는다.** 「0건이었다」와 「세지 못했다」는 다른 사실이다.
+ *  ③ **쓰기 프로브는 동의 없이 계획에 들어오지 않는다** — 남의 운영 시스템에 명령을 넣는 일이다.
+ *  ④ **게이팅 실패 뒤는 돌리지 않는다** — 빨간 칸을 늘리는 것은 원인을 알려 주지 않는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { PROBE_SEQUENCE, foldProbeResults, plannedProbes, type ProbeResult } from '../server/engine/integration-probes.ts'
+import { assessStagePath, forbiddenClaims } from '../server/engine/stage-path.ts'
+
+const pass = (id: any, count?: number, coverage?: { declared: number; total: number }): ProbeResult =>
+  ({ id, ran: true, passed: true, ...(count !== undefined ? { count } : {}), ...(coverage ? { coverage } : {}) })
+
+/** 읽기 프로브 전부 통과 — 반출까지 관측된 상태. */
+const readOnlyAllPass = (): ProbeResult[] => [
+  pass('connect'), pass('discover', 1), pass('master', 12), pass('master-warnings', 3), pass('items', 340),
+  pass('live-ingest', 1200), pass('live-removal', 17),
+  pass('declarations', undefined, { declared: 6, total: 8 }), pass('forecast'),
+  pass('actuate-declared')
+]
+
+test('시퀀스는 읽기부터 시작하고 쓰기 프로브는 하나뿐이다', () => {
+  assert.equal(PROBE_SEQUENCE[0].id, 'connect')
+  assert.deepEqual(PROBE_SEQUENCE.filter(p => p.writes).map(p => p.id), ['actuate-effect'])
+})
+
+test('아무것도 돌리지 않았으면 첫 칸부터 「모른다」다 — 실패로 접지 않는다', () => {
+  const p = assessStagePath(foldProbeResults([]))
+  assert.equal(p.reached, null)
+  assert.deepEqual(p.next?.stage, 'structure')
+  assert.ok(p.stages[0].blockedBy.includes('no-locations'))
+  assert.ok(p.stages[0].unmeasured.includes('master-warnings'), '세지 않은 것은 모르는 것이다')
+})
+
+test('읽기만 전부 통과하면 예측까지 도달하고 폐루프는 「검증되지 않음」으로 남는다', () => {
+  const p = assessStagePath(foldProbeResults(readOnlyAllPass()))
+  assert.equal(p.reached, 'forecast')
+  assert.deepEqual(p.stages[3].unmeasured, ['correlated-effect'])
+  assert.deepEqual(p.stages[3].blockedBy, [], '능력은 선언∩구현이므로 막힌 것이 아니라 안 돌린 것이다')
+  assert.deepEqual(forbiddenClaims(p), ['claim.automatic-control'])
+})
+
+test('쓰기 프로브를 돌려 효과가 관측되면 폐루프가 닫힌다', () => {
+  const p = assessStagePath(foldProbeResults([...readOnlyAllPass(), pass('actuate-effect', 2)]))
+  assert.equal(p.reached, 'closed-loop')
+  assert.deepEqual(forbiddenClaims(p), [])
+})
+
+test('측정하지 못한 프로브는 수를 들지 않는다 — 0 을 지어내지 않는다', () => {
+  /*
+   * 규칙은 「실패면 모른다」가 아니다 — **센 값은 판정과 무관한 사실**이다(0건도 사실이다).
+   * 측정 자체를 못 한 프로브(타임아웃 등)는 `count` 를 **비운다**. 0 을 채우면 「세어 보니 없었다」로
+   * 읽히고, 그건 스냅샷 피드를 delta 로 오인하게 만드는 정반대의 결론을 낳는다.
+   */
+  const rs: ProbeResult[] = [...readOnlyAllPass().filter(r => r.id !== 'live-removal'),
+    { id: 'live-removal', ran: true, passed: false, detail: 'timeout' }]
+  const e = foldProbeResults(rs)
+  assert.equal(e.removalsObserved, null, '측정하지 못했으면 모른다')
+  assert.deepEqual(assessStagePath(e).stages[1].unmeasured, ['removals'])
+})
+
+test('세어서 0 을 얻은 것은 사실이다 — 모른다로 접지 않는다', () => {
+  const rs: ProbeResult[] = [...readOnlyAllPass().filter(r => r.id !== 'live-removal'),
+    { id: 'live-removal', ran: true, passed: false, count: 0 }]
+  const e = foldProbeResults(rs)
+  assert.equal(e.removalsObserved, 0)
+  assert.deepEqual(assessStagePath(e).stages[1].blockedBy, ['no-removal-observed'])
+})
+
+test('반출을 세었는데 0 이면 라이브가 막힌다 — 스냅샷 되풀어 읽기', () => {
+  const rs: ProbeResult[] = [...readOnlyAllPass().filter(r => r.id !== 'live-removal'), pass('live-removal', 0)]
+  const p = assessStagePath(foldProbeResults(rs))
+  assert.deepEqual(p.stages[1].blockedBy, ['no-removal-observed'])
+  assert.equal(p.reached, 'structure')
+  assert.ok(forbiddenClaims(p).includes('claim.realtime'))
+})
+
+test('쓰기 프로브는 동의 없이 계획에 들어오지 않는다', () => {
+  assert.ok(!plannedProbes([]).includes('actuate-effect'))
+  assert.ok(plannedProbes([], { allowWrites: true }).includes('actuate-effect'))
+})
+
+test('게이팅 프로브가 실패하면 그 뒤는 계획하지 않는다', () => {
+  const planned = plannedProbes([{ id: 'connect', ran: true, passed: false, detail: '401' }])
+  assert.deepEqual(planned, [], '붙지 못했으면 뒤를 두드릴 이유가 없다')
+})
+
+test('통과한 프로브는 다시 계획하지 않고, 남은 것만 계획한다', () => {
+  const planned = plannedProbes([pass('connect'), pass('discover', 1)])
+  assert.equal(planned[0], 'master')
+  assert.ok(!planned.includes('connect'))
+})
+
+test('게이팅이 아닌 프로브의 실패는 뒤를 멈추지 않는다', () => {
+  const planned = plannedProbes([pass('connect'), pass('discover', 1), pass('master', 12),
+    { id: 'master-warnings', ran: true, passed: false, detail: 'not-counted' }])
+  assert.ok(planned.includes('items'), '못 옮긴 값을 세지 못한 것이 구조 확인을 멈추지는 않는다')
+})

package/test/integration-runner.test.ts

@@ -0,0 +1,95 @@
+/*
+ * ★ 실행기 — **회색 칸이 빨간 칸으로 위장되지 않게.**
+ *
+ *  ① 시뮬 트윈에 라이브를 요구하지 않는다(해당 없음). 그 빨강은 결함이 아니다.
+ *  ② 템플릿으로 세운 트윈에는 옮겨 온 마스터가 없다 — 「못 옮긴 값」을 물을 대상이 아니다.
+ *  ③ 반출 0 의 처방이 둘로 갈린다: 스냅샷이면 방식을 바꿔야 하고, 아니면 더 기다릴 수 있다.
+ *  ④ 액추에이션은 계약에 없다 — 측정을 만들지 않고 미실행으로 남긴다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { assessSuite, type SuiteFacts } from '../server/engine/integration-runner.ts'
+
+const live = (): SuiteFacts => ({
+  subject: 'live',
+  fromReference: true,
+  adapterCapabilities: ['live'],
+  connectOk: true,
+  siteCount: 3,
+  locationCount: 12,
+  itemCount: 340,
+  lastWarningCount: 2,
+  journalTotal: 1200,
+  removalsJournaled: 17,
+  specCoverage: { declared: 6, total: 8 },
+  forecastRan: true,
+  feed: 'delta-poll'
+})
+
+test('라이브 전부 갖추면 예측까지 도달하고, 폐루프는 능력이 없어 막힌다', () => {
+  const a = assessSuite(live())
+  assert.equal(a.path.reached, 'forecast')
+  assert.deepEqual(a.path.stages[3].blockedBy, ['no-actuate-capability'])
+  assert.deepEqual(a.forbiddenClaims, ['claim.automatic-control'])
+  assert.equal(a.profile.multiSite, true)
+})
+
+test('시뮬 트윈은 라이브가 해당 없음이고, 그 사유를 말한다', () => {
+  const a = assessSuite({ ...live(), subject: 'sim', journalTotal: null, removalsJournaled: null })
+  assert.deepEqual(a.notApplicable.map(n => n.id), ['live-ingest', 'live-removal'])
+  assert.deepEqual(a.path.stages[1].blockedBy, ['subject-is-simulation'])
+  assert.deepEqual(a.path.stages[1].unmeasured, [], '해당 없음을 미측정으로 접지 않는다')
+  assert.equal(a.path.reached, 'structure')
+  assert.ok(!a.planned.includes('live-removal'), '해당 없는 프로브는 계획하지 않는다')
+})
+
+test('템플릿으로 세운 트윈은 못 옮긴 값을 물을 대상이 아니다', () => {
+  const a = assessSuite({ ...live(), fromReference: false, lastWarningCount: null })
+  assert.deepEqual(a.notApplicable.map(n => n.id), ['master-warnings'])
+  assert.equal(a.path.stages[0].achieved, true, '해당 없음이 구조 달성을 막지 않는다')
+})
+
+test('반출 0 — 스냅샷이면 방식을 바꿔야 한다고 말한다', () => {
+  const a = assessSuite({ ...live(), removalsJournaled: 0, feed: 'snapshot-poll' })
+  assert.deepEqual(a.path.stages[1].blockedBy, ['snapshot-only-feed'])
+  assert.ok(a.forbiddenClaims.includes('claim.realtime'))
+})
+
+test('반출 0 — 스냅샷이 아니면 아직 일어나지 않은 것일 수 있다', () => {
+  const a = assessSuite({ ...live(), removalsJournaled: 0, feed: 'delta-poll' })
+  assert.deepEqual(a.path.stages[1].blockedBy, ['no-removal-observed'])
+})
+
+test('승격 전 저널은 반출을 셀 수 없다 — 「없다」가 아니라 「모른다」', () => {
+  const a = assessSuite({ ...live(), removalsJournaled: null })
+  assert.deepEqual(a.path.stages[1].unmeasured, ['removals'])
+  assert.deepEqual(a.path.stages[1].blockedBy, [])
+})
+
+test('액추에이션 효과는 측정을 만들지 않고 미실행으로 남긴다', () => {
+  const a = assessSuite({ ...live(), adapterCapabilities: ['live', 'actuate'] })
+  const eff = a.results.find(r => r.id === 'actuate-effect')!
+  assert.equal(eff.ran, false)
+  assert.equal(eff.detail, 'actuation-not-wired')
+  assert.deepEqual(a.path.stages[3].unmeasured, ['correlated-effect'])
+})
+
+test('쓰기 프로브는 동의 없이 계획에 들어오지 않는다', () => {
+  const able = { ...live(), adapterCapabilities: ['live', 'actuate'] }
+  assert.ok(!assessSuite(able).planned.includes('actuate-effect'))
+  assert.ok(assessSuite(able, { allowWrites: true }).planned.includes('actuate-effect'))
+})
+
+test('액추에이션 능력이 없으면 쓰기 동의가 있어도 계획하지 않는다 — 보낼 문이 없다', () => {
+  assert.ok(!assessSuite(live(), { allowWrites: true }).planned.includes('actuate-effect'))
+})
+
+test('접속을 안 돌렸으면 구조부터 미측정이 아니라 미실행으로 남고, 계획의 첫 칸이 된다', () => {
+  const a = assessSuite({ ...live(), connectOk: null })
+  assert.equal(a.planned[0], 'connect')
+})
+
+test('못 옮긴 값이 0 이어도 세었으므로 통과다', () => {
+  assert.equal(assessSuite({ ...live(), lastWarningCount: 0 }).path.stages[0].achieved, true)
+})

package/test/item-ref.test.ts

@@ -0,0 +1,78 @@
+/*
+ * 개체 → 품목 참조 — **정체성 모양이 하나가 아니고, 구분자는 우리가 정하지 않는다** (2026-08-23).
+ *
+ * ── 무엇이 조용히 비어 있었나 ───────────────────────────────────────────────
+ * 화면이 「이 개체는 선언된 자재가 아닙니다」라고 말했다. 그런데 그 품목은 원본의 선언에 이름까지 있었고
+ * (「냉동그린빈스」), 대응 표도 멀쩡했다. 원인은 참조를 꺼내는 규칙이 GS1 SGTIN 하나만 알았던 것이다.
+ *
+ * ── 그리고 고치는 방향을 한 번 더 고쳤다 ────────────────────────────────────
+ * 처음에는 「`@` 뒤는 개체다」를 규칙으로 넣었다. 그것은 **한 원본(chef)의 관행**이고, 커널 계약이 그
+ * 구분자를 정한 적이 없다 — 사용자가 「이 화면이 특정 레거시를 기준으로 해서는 안 된다」고 짚었다.
+ * 그래서 자르는 판단을 걷고, **그 트윈의 선언과 비교해** 답한다.
+ *
+ * 이 시험이 지키는 것:
+ *  ① SGTIN 은 표준이 정한 자리에서 품목 참조를 꺼낸다.
+ *  ② 그 밖의 모양은 **손대지 않는다**(구분자를 모른다).
+ *  ③ 선언과 비교할 때는 두 방향을 본다 — 관측이 선언을 확장한 경우, 화면이 짧게 줄인 경우.
+ *  ④ 후보가 둘 이상이면 **답하지 않는다**(모르는 것이 틀린 답보다 낫다).
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { itemRefOf, resolveByDeclaration } from '../server/service/twin-model/item-ref.ts'
+
+test('GS1 SGTIN 은 품목 참조 숫자다 — 표준이 자리를 정해 두었다', () => {
+  assert.equal(itemRefOf('urn:epc:id:sgtin:0614141.077101.42'), '077101')
+  assert.equal(itemRefOf('urn:epc:idpat:sgtin:0614141.078101.*'), '078101')
+})
+
+test('그 밖의 정체성은 손대지 않는다 — 어느 부호가 개체인지 우리가 정하지 않는다', () => {
+  assert.equal(itemRefOf('https://x.net/class/product-M1@M2R0001'), 'https://x.net/class/product-M1@M2R0001')
+  assert.equal(itemRefOf('https://x.net/class/product-M1'), 'https://x.net/class/product-M1')
+  assert.equal(itemRefOf('  https://x.net/class/p-1  '), 'https://x.net/class/p-1', '앞뒤 공백만 다듬는다')
+})
+
+test('읽을 수 없는 값은 null 이다', () => {
+  assert.equal(itemRefOf(''), null)
+  assert.equal(itemRefOf('   '), null)
+  assert.equal(itemRefOf(null), null)
+  assert.equal(itemRefOf(undefined), null)
+  assert.equal(itemRefOf(42), null)
+})
+
+const DECLARED = new Map<string, string>([
+  ['https://x.net/class/product-M0000438', 'M0000438'],
+  ['https://x.net/class/product-B0000033', 'B0000033']
+])
+
+test('그대로 같으면 그것이다', () => {
+  assert.equal(resolveByDeclaration('https://x.net/class/product-M0000438', DECLARED), 'M0000438')
+})
+
+test('관측이 선언을 확장한 경우 — 개체는 자기 클래스로 시작한다(부호를 모른다)', () => {
+  for (const sep of ['@', '#', '/', ':', '']) {
+    assert.equal(
+      resolveByDeclaration(`https://x.net/class/product-M0000438${sep}M2R0001`, DECLARED),
+      'M0000438',
+      `구분자 「${sep}」 에서도 같은 답이어야 한다`
+    )
+  }
+})
+
+test('화면이 짧게 줄인 경우 — 선언이 그것으로 끝난다', () => {
+  assert.equal(resolveByDeclaration('net/class/product-B0000033', DECLARED), 'B0000033')
+  assert.equal(resolveByDeclaration('product-M0000438', DECLARED), 'M0000438')
+})
+
+test('후보가 둘 이상이면 답하지 않는다 — 남의 레시피와 비교하지 않게', () => {
+  const ambiguous = new Map<string, string>([
+    ['https://a.net/class/product-1', 'A1'],
+    ['https://b.net/class/product-1', 'B1']
+  ])
+  assert.equal(resolveByDeclaration('class/product-1', ambiguous), undefined)
+})
+
+test('선언에 없으면 없는 것이다 — 비슷한 것을 이어 주지 않는다', () => {
+  assert.equal(resolveByDeclaration('https://x.net/class/product-ZZZ', DECLARED), undefined)
+  assert.equal(resolveByDeclaration(null, DECLARED), undefined)
+})