@things-factory/headless-twin 10.0.15 → 10.0.18

package/test/local-declarations.test.ts

@@ -1,7 +1,7 @@
 /*
  * 현장 선언 — **구조는 원천이, 수는 현장이.**
  *
- * 이 시험이 지키는 것: 사용자가 넣은 수가 ① 검사를 거치고(단위를 잘못 읽은 값이 조용히 들어가지 않는다)
+ * 이 시험이 지키는 것: 사용자가 넣은 수가 ① 검사를 거치고(단위를 잘못 읽은 값이 알리지 않고 들어가지 않는다)
  * ② 원천에서 다시 그려도 살아남고 ③ 갈 곳이 없으면 그 사실이 남는다.
  */
 import { test } from 'node:test'
@@ -122,7 +122,7 @@ test('같은 속성을 다시 넣으면 새 값이 이긴다 — 현장이 값
   const second = mergeLocalDeclarations(first, [
     { target: 'location', id: 'incoming-1', properties: [{ id: 'tariff.demandChargePerKW', value: '24' }, { id: 'tariff.currency', value: 'USD' }] }
   ])
-  assert.equal(second.length, 1, '같은 대상은 한 줄로 접힌다')
+  assert.equal(second.length, 1, '같은 대상은 한 줄로 합쳐진다')
   assert.deepEqual(second[0].properties.map(p => [p.id, p.value]), [
     ['tariff.demandChargePerKW', '24'],
     ['tariff.currency', 'USD']
@@ -154,7 +154,7 @@ test('현장 값이 원천 값을 덮는다 — 고쳐 넣었다는 것은 원
   assert.equal(p.source, 'local')
 })
 
-test('대상이 사라졌으면 그 사실을 낸다 — 갈 곳 없는 선언을 조용히 버리지 않는다', () => {
+test('대상이 사라졌으면 그 사실을 낸다 — 갈 곳 없는 선언을 알리지 않고 버리지 않는다', () => {
   const { missingTargets } = applyLocalDeclarations(emsModel(), [
     { target: 'equipment', id: 'ess-gone', properties: [{ id: 'storage.capacityKWh', value: '500' }] }
   ])
@@ -191,7 +191,7 @@ test('경고 문장이 무엇을 해야 하는지 말한다 — 우리가 시간
  * 필드 이름을 틀린 호출(예: id 대신 targetId)이 「받아준 선언이 없다」는 답만 받고 rejected 는 비어
  * 있었다. 사용자는 값을 넣었다고 믿는데 화면은 아무것도 바뀌지 않고, 고칠 단서도 없다.
  */
-test('대상 id 가 없으면 이유를 말한다 — 조용히 건너뛰지 않는다', () => {
+test('대상 id 가 없으면 이유를 말한다 — 알리지 않고 건너뛰지 않는다', () => {
   const { accepted, rejected } = validateLocalDeclarations('ems', [
     { properties: [{ id: 'contract.kW', value: '3500' }] } as any
   ])
@@ -289,7 +289,7 @@ test('기억이 없는 옛 선언은 손대지 않고 그렇게 말한다 —
   assert.equal((back.model.locations[0] as any).properties[0].value, '600', '값은 그대로다 — 다음 재읽기가 바로잡는다')
 })
 
-test('겹에 없는 것을 뺐다고 하지 않는다 — 조용한 성공이 가장 비싸다', () => {
+test('겹에 없는 것을 뺐다고 하지 않는다 — 성공이라 답하면서 아무 일도 하지 않는 것이 가장 비싸다', () => {
   const { revoked, notFound } = revokeLocalDeclarations(
     [{ target: 'location', id: 'incoming-1', properties: [{ id: 'contract.kW', value: '600', replaced: '3500' }] }],
     [
@@ -309,7 +309,7 @@ test('겹에 없는 것을 뺐다고 하지 않는다 — 조용한 성공이
  * 이고(SAP 는 `P3`, Oracle 은 `W01` 로 같은 현장을 부른다), 여기 담기는 것은 그 시스템이 **모르는**
  * 값이다 — 이름이 내용과 정반대였다. 축은 「누가 말했나」이고 답은 `reference` ↔ `local` 둘이다.
  *
- * 낱말은 조용히 되돌아간다(복사·자동완성·옛 문서). 그래서 검사로 못 박는다.
+ * 낱말은 알리지 않고 되돌아간다(복사·자동완성·옛 문서). 그래서 검사로 못 박는다.
  */
 test('이 겹의 어휘는 local 이다 — site·facility 로 되돌아가지 않는다', () => {
   const src = readFileSync(fileURLToPath(new URL('../server/engine/local-declarations.ts', import.meta.url)), 'utf-8')
@@ -327,7 +327,8 @@ test('이 겹의 어휘는 local 이다 — site·facility 로 되돌아가지
 test('축의 두 낱말이 계약에 선언돼 있다 — 얹혀 다니는 필드가 아니다', async () => {
   /* 예전에는 source 표식이 커널 계약에 없는 필드로 얹혀 다녔다 — 소비처가 any 로 읽고, 상태에 정말
      실리는지 아무도 검사할 수 없었다. */
-  const kernel: any = await import('@operato/twin-kernel')
+  /* 속성 어휘는 계약에 있다 — 커널은 엔진만 내보낸다(2026-08-30 층 분리). */
+  const contract: any = await import('@operato/ops-contract')
   const { model } = applyLocalDeclarations(
     { locations: [{ id: 'incoming-1', type: 'incoming' }] },
     [{ target: 'location', id: 'incoming-1', properties: [{ id: 'contract.kW', value: '3500' }] }]
@@ -335,7 +336,7 @@ test('축의 두 낱말이 계약에 선언돼 있다 — 얹혀 다니는 필
   const p = (model.locations[0] as any).properties[0]
   /* 계약이 정한 두 값 외에는 쓰지 않는다. */
   assert.ok(['reference', 'local'].includes(p.source), '표식은 reference|local 뿐이다')
-  assert.ok(kernel.EMS_PROPERTY, '커널 계약을 실제로 읽고 있다')
+  assert.ok(contract.EMS_PROPERTY, '계약을 실제로 읽고 있다')
 })
 
 test('옛 표식이 구워진 값을 원천 값으로 오인하지 않는다 — 표식의 종류를 따지지 않는다', () => {
@@ -430,7 +431,7 @@ test('구조 투영이 중복 id 를 이름으로 말한다 — 제약 위반
   const src = readFileSync(fileURLToPath(new URL('../server/service/twin-model/project-structure.ts', import.meta.url)), 'utf-8')
   assert.match(src, /has two \$\{what\} with id/, '무엇이 겹쳤는지 이름으로 말한다')
   assert.match(src, /ids must be unique within a twin/, '규칙도 함께 말한다')
-  /* 조용히 하나만 남기지 않는다 — 어느 쪽이 맞는지 우리는 모른다. */
+  /* 알리지 않고 하나만 남기지 않는다 — 어느 쪽이 맞는지 우리는 모른다. */
   assert.equal(/dedupe|distinctBy/.test(src), false, '중복을 소리 없이 지우지 않는다')
 })
 
@@ -508,7 +509,7 @@ test('지게차에 계약전력을 넣던 구멍이 막혔다 — 읽는 코드
   assert.equal(rejected[0]?.reason, 'wrong-target')
 })
 
-test('확인할 수 있으면 오타 공정 이름을 거절한다 — 조용히 아무 일도 안 하지 않게', () => {
+test('확인할 수 있으면 오타 공정 이름을 거절한다 — 알리지 않고 아무 일도 안 하지 않게', () => {
   const decl = [{ target: 'operation' as const, id: 'put-away', properties: [{ id: 'operation.duration', value: '4', uom: 'MIN' }] }]
   const checked = validateLocalDeclarations('wms', decl, { knownOperations: ['putaway', 'pick'] })
   assert.deepEqual(checked.accepted, [])
@@ -534,7 +535,7 @@ test('철회하면 표에서 빠진다 — 원천 명세나 커널 상수가 다
   assert.deepEqual(back.restored.length, 1)
 })
 
-test('없는 공정을 철회했다고 말하지 않는다 — 조용한 성공이 가장 비싸다', () => {
+test('없는 공정을 철회했다고 말하지 않는다 — 성공이라 답하면서 아무 일도 하지 않는 것이 가장 비싸다', () => {
   const back = restoreRevoked({ locations: [], equipment: [], localDurations: { pick: 'PT60S' } }, [
     { target: 'operation', id: 'putaway', propertyId: 'operation.duration', replaced: null }
   ])
@@ -642,7 +643,7 @@ test('모수 철회는 모수 표에서 뺀다 — 시간 선언은 그대로
   assert.deepEqual((back.model as any).localDurations, { weld: 'PT180S' }, '시간은 그대로')
 })
 
-test('없는 모수를 철회했다고 말하지 않는다 — 조용한 성공이 가장 비싸다', () => {
+test('없는 모수를 철회했다고 말하지 않는다 — 성공이라 답하면서 아무 일도 하지 않는 것이 가장 비싸다', () => {
   const back = restoreRevoked({ locations: [], equipment: [], localParams: { weld: { yield: '0.9' } } }, [
     { target: 'operation', id: 'weld', propertyId: 'operation.setupDuration', replaced: null }
   ])

package/test/log-stamp.test.ts

@@ -34,7 +34,7 @@ test('오류는 스택까지 남는다 — 「어디서 났나」를 잃지 않
   assert.ok(out.includes('log-stamp.test'), '스택이 있어야 어느 자리에서 났는지 알 수 있다')
 })
 
-test('값이 없어도 있었다는 사실은 남긴다 — 조용히 지우지 않는다', () => {
+test('값이 없어도 있었다는 사실은 남긴다 — 알리지 않고 지우지 않는다', () => {
   assert.equal(line(['a', undefined, null, 0]), 'a undefined null 0')
   const circular: any = { name: 'ㄱ' }
   circular.self = circular

package/test/master-to-twin.test.ts

@@ -7,7 +7,7 @@ import { test } from 'node:test'
 import assert from 'node:assert/strict'
 
 import { masterToTwin } from '../server/service/reference/reference-master.ts'
-import { DOMAIN_CATALOG } from '@operato/twin-kernel'
+import { DOMAIN_CATALOG } from '@operato/ops-contract'
 
 /** WMS 단위적재 템플릿이 내는 것과 동형인 현실적 master(coordinate-free). */
 const wmsMaster = () => ({
@@ -30,7 +30,7 @@ test('locations role → 노드/영역 분기, equipment → 무버', () => {
   assert.deepEqual(model.locations.map((n: any) => n.id).sort(), ['dock-recv', 'dock-ship', 'rack-1', 'rack-2'], '노드=role location')
   assert.equal(spaceContent.areas.length, 1, '영역=role area')
   assert.equal(spaceContent.areas[0].id, 'a-dc')
-  assert.deepEqual(model.equipment, [{ id: 'fk-1', kind: 'forklift', homeLocation: 'dock-recv', mtbfMs: undefined, mttrMs: undefined, gs1Id: undefined }], '마스터 equipment→보드 equipment(homeLocationId→homeLocation, gs1Id 통과)')
+  assert.deepEqual(model.equipment, [{ id: 'fk-1', kind: 'forklift', homeLocation: 'dock-recv', mtbfMs: undefined, mttrMs: undefined }], '마스터 equipment→보드 equipment(homeLocationId→homeLocation, identity 통과)')
   assert.equal(model.locations.find((n: any) => n.id === 'rack-1').capacity, 60, 'capacity 전달')
   assert.equal(model.locations.find((n: any) => n.id === 'dock-recv').parentId, undefined, 'parentId 없으면 undefined')
 })

package/test/measured-yield.test.ts

@@ -11,7 +11,7 @@
  *  ② 표본이 모자라면 **배우지 않는다** — 비율은 드문 사건을 재는 값이라 작은 표본이 잡음을 만든다.
  *  ③ 0 도 사실이다 — 전량 불량이면 0 을 배운다(「값이 없다」와 다르다).
  *  ④ 모르는 종류에는 `undefined` — 그러면 커널이 선언값·상수로 내려간다.
- *  ⑤ 배우지 못한 것을 **밝힌다** — 조용히 일부만 반영하지 않는다.
+ *  ⑤ 배우지 못한 것을 **밝힌다** — 알리지 않고 일부만 반영하지 않는다.
  */
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
@@ -84,7 +84,7 @@ test('사슬 넷이 이어져 있다 — 판정→축→집계→비율', () =>
   assert.match(hostSrc('engine/kpi-fold.ts'), /facets\.outcome/, 'KPI 가 판정 축을 읽는다')
   assert.match(hostSrc('engine/kpi-fold.ts'), /quality\?: \{ good: number; scrap: number \}/, '종류별로 센다')
   const engine = hostSrc('engine/twin-engine.ts')
-  assert.match(engine, /buildYieldEstimator\(kpi\?\.groups\?\.items/, '같은 폴드에서 배운다(두 번 접지 않는다)')
+  assert.match(engine, /buildYieldEstimator\(kpi\?\.groups\?\.items/, '같은 폴드에서 배운다(두 번 계산하지 않는다)')
   assert.match(engine, /kernel\.yieldEstimator = yields\.estimator/, '커널 시임에 넣는다')
   assert.match(engine, /yieldOf missing/, '옛 커널이면 그 사실을 말한다')
 })

package/test/merge-streams.test.ts

@@ -0,0 +1,70 @@
+/*
+ * ★ 나눠 묻고 합치는 규율 — 갈래마다 상한까지 받아야 합친 결과가 정확하다.
+ *
+ * ── 왜 이 시험이 있나 (2026-08-28) ──────────────────────────────────────────
+ * 「종류 IN + 시각순」은 색인을 못 쓴다. 그래서 종류를 하나씩 정확일치로 묻고 합치는데, 그때 함정이
+ * 하나 있다 — UX 레인이 구현 전에 짚어 주었다.
+ *
+ *   「갈래마다 상한을 걸면 합친 결과가 시각순으로 온전하지 않다.
+ *     종류 A 의 마지막이 종류 B 의 첫째보다 이를 수 있다.」
+ *
+ * 그 지적은 **갈래마다 상한보다 적게 받을 때** 참이다. 상한까지 받으면 성질이 선다: 어떤 갈래에서 빠진
+ * 행은 그 갈래의 상한 번째보다 뒤이고, 우리는 전체에서 상한 개만 취하므로 그 행이 이 페이지에 들어올 수
+ * 없다. 이 시험이 그 성질을 못박는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { mergeStreams } from '../server/service/twin-journal/event-type-split-shape.js'
+
+const byN = (a: { n: number }, b: { n: number }) => a.n - b.n
+const seq = (from: number, count: number) => Array.from({ length: count }, (_, i) => ({ n: from + i }))
+
+test('★ 한 갈래가 앞을 다 차지해도 전체에서 앞 limit 개가 나온다 — 짚어 준 그 경우다', () => {
+  /*
+   * A 가 1~5, B 가 100~104. limit 3 이면 답은 A 의 1,2,3 이다. B 는 한 건도 들어오지 않는 것이 맞다.
+   */
+  const r = mergeStreams([seq(1, 5), seq(100, 5)], 3, byN)
+  assert.deepEqual(r.items.map(x => x.n), [1, 2, 3])
+  assert.equal(r.capped, true, '더 있었다는 사실을 말해야 한다')
+})
+
+test('★ 갈래를 섞어도 시각순이 유지된다', () => {
+  const a = [{ n: 1 }, { n: 4 }, { n: 7 }]
+  const b = [{ n: 2 }, { n: 5 }, { n: 8 }]
+  const c = [{ n: 3 }, { n: 6 }, { n: 9 }]
+  const r = mergeStreams([a, b, c], 9, byN)
+  assert.deepEqual(r.items.map(x => x.n), [1, 2, 3, 4, 5, 6, 7, 8, 9])
+  assert.equal(r.capped, false, '상한에 닿지 않았으면 잘리지 않았다')
+})
+
+test('★ 상한에 닿은 갈래가 있으면 잘렸다고 말한다 — 숫자가 알리지 않고 작아지지 않게', () => {
+  /* 한 갈래가 정확히 상한만큼 받아 왔으면 그 갈래에 더 있었을 수 있다. */
+  const r = mergeStreams([seq(1, 3), seq(10, 1)], 3, byN)
+  assert.equal(r.items.length, 3)
+  assert.equal(r.capped, true)
+})
+
+test('상한에 못 닿았고 합쳐도 상한 미만이면 잘리지 않았다', () => {
+  const r = mergeStreams([seq(1, 2), seq(10, 2)], 10, byN)
+  assert.deepEqual(r.items.map(x => x.n), [1, 2, 10, 11])
+  assert.equal(r.capped, false)
+})
+
+test('빈 갈래가 섞여도 답이 같다 — 그 종류가 그 구간에 없는 것은 정상이다', () => {
+  const r = mergeStreams([[], seq(5, 2), []], 10, byN)
+  assert.deepEqual(r.items.map(x => x.n), [5, 6])
+  assert.equal(r.capped, false)
+})
+
+test('★ 갈래가 상한보다 많이 받아 오면 그 사실을 말한다 — 있을 수 없는 일이다', () => {
+  /* 부르는 쪽이 상한을 잘못 걸었다는 뜻이고, 그 상태로 답하면 합친 결과를 믿을 수 없다. */
+  const r = mergeStreams([seq(1, 5)], 3, byN)
+  assert.equal(r.underfilled, true)
+})
+
+test('갈래가 하나면 그냥 앞에서 자른 것과 같다', () => {
+  const r = mergeStreams([seq(1, 5)], 5, byN)
+  assert.deepEqual(r.items.map(x => x.n), [1, 2, 3, 4, 5])
+  assert.equal(r.underfilled, false)
+})

package/test/mirror-resumes-from-checkpoint.test.ts

@@ -1,24 +1,24 @@
 /*
- * ★ **재기동이 저널을 처음부터 다시 접지 않는다** — 미러가 저장된 재개점에서 이어 선다.
+ * ★ **재기동이 저널을 처음부터 다시 계산하지 않는다** — 미러가 저장된 재개점에서 이어 선다.
  *
  * ── 무엇이 오래 잘못돼 있었나 (2026-08-24 실측) ─────────────────────────────
- * 재개점을 **읽는** 쪽은 다 있었다: `recover` 는 `fold` 가 있으면 꼬리만 접고, 없으면 저널을 0부터
- * 접는다. 그런데 **쓰는 쪽이 없었다** — `persistSnapshot` 은 `{revision, state, structureRev}` 만
+ * 재개점을 **읽는** 쪽은 다 있었다: `recover` 는 `fold` 가 있으면 꼬리만 계산하고, 없으면 저널을 0부터
+ * 계산한다. 그런데 **쓰는 쪽이 없었다** — `persistSnapshot` 은 `{revision, state, structureRev}` 만
  * 적었다. 실측으로 저장된 스냅샷 34건 전부 `fold` 가 비어 있었고, 저널은 2,960만 줄이었다.
  *
  * 그래서 두 가지가 함께 일어났다.
  *
- *   ① 켤 때마다 처음부터 접었다 — 규모 기준(엔티티 10만·품목 100만)에서 느린 것이 아니라 못 하는 것이다
+ *   ① 켤 때마다 처음부터 계산했다 — 규모 기준(엔티티 10만·품목 100만)에서 느린 것이 아니라 못 하는 것이다
  *   ② 미러는 되찾은 상태를 **버렸다**(`startLive`). 「다음 계측이 정정한다」는 전제였는데, 원본이 커서
- *      증분으로 말하는 현장에서는 그 정정이 오지 않는다 — 미러가 영구히 빈 채로 남고 화면은 조용했다
+ *      증분으로 말하는 현장에서는 그 정정이 오지 않는다 — 미러가 영구히 빈 채로 남고 화면은 들어온 것이 없었다
  *
  * ── 왜 커널 시험만으로 충분하지 않나 ────────────────────────────────────────
- * 커널은 「재개점 + 꼬리 == 0부터 접기」를 증명한다(`observed-checkpoint.test.ts`). 그것이 참이어도
+ * 커널은 「재개점 + 꼬리 == 0부터 계산하기」를 증명한다(`observed-checkpoint.test.ts`). 그것이 참이어도
  * 호스트가 재개점을 **적지 않거나 되세우지 않으면** 아무 일도 일어나지 않는다 — 이 저장소가 실제로
  * 넉 달 동안 그 상태였다. 그래서 여기서 DB 를 물고 실제로 걷는다.
  *
  * ── 결정적인 단정 ───────────────────────────────────────────────────────────
- * 재기동 전에 **저널을 지운다.** 그래도 상태가 돌아오면 그것은 저널을 접어 온 것이 **아니다** —
+ * 재기동 전에 **저널을 지운다.** 그래도 상태가 돌아오면 그것은 저널을 계산해 온 것이 **아니다** —
  * 저장된 재개점에서 온 것이다. 그리고 그 상황은 가정이 아니라 설계된 거동이다: 보존 정책이 체크포인트
  * 리비전 이하의 행을 지운다(「그 앞은 스냅샷이 대신한다」).
  */
@@ -31,7 +31,7 @@ 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')
-/* 체크포인트는 `cache-service` 표에 앉는다 — 그 엔티티를 빼면 저장이 조용히 실패한다(스냅샷도 씨앗도). */
+/* 체크포인트는 `cache-service` 표에 앉는다 — 그 엔티티를 빼면 저장이 알리지 않고 실패한다(스냅샷도 씨앗도). */
 const { entities: cacheEntities } = req('@things-factory/cache-service/dist-server/service/index.js')
 const { TwinEngine } = req('../dist-server/engine/index.js')
 const { TwinEvent } = req('../dist-server/service/twin-event/twin-event.js')
@@ -56,7 +56,7 @@ const master = (): any => ({
   equipment: [{ id: 'fk-1', kind: 'forklift', homeLocationId: 'dock' }]
 })
 
-/** 원본이 말한 사실 — 오더와 작업. 미러는 이것을 접어 상태를 만든다. */
+/** 원본이 말한 사실 — 오더와 작업. 미러는 이것을 계산해 상태를 만든다. */
 function facts(n: number): any[] {
   const out: any[] = []
   for (let i = 1; i <= n; i++) {
@@ -112,7 +112,7 @@ after(async () => {
   await ds?.destroy()
 })
 
-test('체크포인트가 **이어 접을 씨앗을 함께 적는다** — 이 줄이 없어서 넉 달 동안 처음부터 접었다', async () => {
+test('체크포인트가 **이어 계산할 씨앗을 함께 적는다** — 이 줄이 없어서 넉 달 동안 처음부터 계산했다', async () => {
   const rt = await TwinEngine.bootDeclared(domainId, INSTANCE, 'resync')
   assert.equal(rt.mode, 'live', '미러로 떠야 이 검사가 뜻이 있다')
 
@@ -124,14 +124,14 @@ test('체크포인트가 **이어 접을 씨앗을 함께 적는다** — 이
   await TwinEngine.persistSnapshot(domainId, INSTANCE)
   const stored = await TwinEngine.loadSnapshot(domainId, INSTANCE)
   assert.ok(stored, '스냅샷이 저장됐다')
-  assert.ok(stored.fold?.reducer, '★ 재개점이 함께 적혀야 한다 — 없으면 다음 기동이 저널을 0부터 접는다')
+  assert.ok(stored.fold?.reducer, '★ 재개점이 함께 적혀야 한다 — 없으면 다음 기동이 저널을 0부터 계산한다')
   assert.ok(stored.fold?.oee, '가동 누적기도 함께 — 상태만 되돌리면 가동률이 부팅 이후로만 잡힌다')
   /* 씨앗이 실제로 사실을 들었는지 — 빈 껍데기를 적어 두고 초록이 되지 않게. */
   assert.ok((stored.fold.reducer as any).orders?.length, '씨앗에 오더가 담겨 있다')
   assert.ok((stored.fold.reducer as any).tasks?.length, '씨앗에 작업이 담겨 있다')
 })
 
-test('★ 저널을 지워도 미러가 상태를 들고 다시 선다 — 그러므로 저널을 접은 것이 아니다', async () => {
+test('★ 저널을 지워도 미러가 상태를 들고 다시 선다 — 그러므로 저널을 계산한 것이 아니다', async () => {
   /*
    * 이 단정이 이 축의 전부다. 저널이 없는데 상태가 돌아오면 그 상태는 **저장된 재개점**에서 온 것이다.
    * 그리고 이 상황은 가정이 아니다 — 보존 정책이 체크포인트 리비전 이하의 행을 실제로 지운다.
@@ -145,7 +145,7 @@ test('★ 저널을 지워도 미러가 상태를 들고 다시 선다 — 그
   assert.equal(
     await ds.getRepository(TwinEvent).countBy({ domain: { id: domainId } as any, instanceId: INSTANCE } as any),
     0,
-    '저널이 비었다 — 이제 접을 것이 없다'
+    '저널이 비었다 — 이제 계산할 것이 없다'
   )
 
   await TwinEngine.bootDeclared(domainId, INSTANCE, 'resync')

package/test/model-basis.test.ts

@@ -131,11 +131,11 @@ test('선언이 침묵하면 기본값으로 떨어진다 — 없는 것을 지
   assert.equal(modelBasisChanged(quiet(base), quiet(base * 1.3)), true, '기본 10% 밖')
 })
 
-test('변동폭이 바뀌면 다른 모델이다 — 판정의 잣대가 조용히 바뀌지 않게', () => {
+test('변동폭이 바뀌면 다른 모델이다 — 판정의 잣대가 알리지 않고 바뀌지 않게', () => {
   const a = weld(70 * 60_000)
   const b = {
     measured: { weld: 70 * 60_000 },
     declared: [{ key: 'weld', duration: 'PT1H10M', variability: { distribution: 'triangular', min: 'PT30M', max: 'PT3H', mode: 'PT1H5M' } }]
   }
-  assert.equal(modelBasisChanged(a, b), true, '변동폭 선언이 바뀌었는데 같은 모델이라고 하면 잣대가 조용히 바뀐다')
+  assert.equal(modelBasisChanged(a, b), true, '변동폭 선언이 바뀌었는데 같은 모델이라고 하면 잣대가 오류 없이 바뀐다')
 })

package/test/model-gap.test.ts

@@ -20,7 +20,7 @@
  * ── 지키는 것 ───────────────────────────────────────────────────────────────
  * ① 마스터가 말한 것과 관측으로 알게 된 것을 섞지 않는다
  * ② 트윈이 안 돌면 `null` — 「없다」와 「세어 보지 못했다」는 다르다
- * ③ 조용히 자르지 않는다 — 상한에서 밀려난 수를 함께 낸다
+ * ③ 알리지 않고 자르지 않는다 — 상한에서 밀려난 수를 함께 낸다
  * ④ 덮지 못하는 축을 밝힌다 — 계량기는 커널이 표시를 달지 않아 이 화면이 못 찾아 준다
  */
 import { test } from 'node:test'
@@ -68,7 +68,7 @@ test('돌지만 관측 갭이 없으면 0 이다 — 이건 「없음」과 다
   assert.equal(g!.total, 0, '세어 보니 없었다')
 })
 
-test('id 를 조용히 자르지 않는다 — 밀려난 수를 함께 낸다', () => {
+test('id 를 알리지 않고 자르지 않는다 — 밀려난 수를 함께 낸다', () => {
   const many = Array.from({ length: GAP_ID_LIMIT + 7 }, (_, i) => loc(`ghost-${i}`, 'observed'))
   const g = modelGapOf({ locations: many })
 
@@ -95,7 +95,7 @@ test('모르는 설비의 에너지 보고는 「없음」과 0 을 가른다
   /*
    * 이 값을 **루트에서 읽고 있었다**(2026-08-20에 잡음). 커널은 `EnergyState` 안에 담으므로 루트에서
    * 읽으면 영원히 `null` 이고, 오류 없이 「에너지 트윈이 아니다」로 읽힌다. 나만 읽는 필드를 잘못된
-   * 경로에서 읽으면 이렇게 조용히 사라진다.
+   * 경로에서 읽으면 이렇게 오류 없이 사라진다.
    *
    * 그리고 커널은 0 이면 그 칸을 만들지 않는다. 그래서 `energy` 자체가 있는지로 「세었고 0」과
    * 「에너지 트윈이 아님」을 가른다.
@@ -112,7 +112,7 @@ test('모르는 설비의 에너지 보고는 「없음」과 0 을 가른다
 
 test('계량기도 덮는다 — 이 축이 가장 무겁다', () => {
   /*
-   * 모르는 `meterId` 는 조용히 새 계량기가 되고 그 kW 가 그 현장의 수요·피크·요금 판정에 더해진다.
+   * 모르는 `meterId` 는 알리지 않고 새 계량기가 되고 그 kW 가 그 현장의 수요·피크·요금 판정에 더해진다.
    * 로케이션 오타는 스키매틱이 비는 것으로 드러나지만, 이건 **그럴듯한 숫자**로 나온다.
    * 커널 0.7.39 가 `MeterPointState.origin` 을 내면서 덮을 수 있게 됐다.
    */

package/test/model-vocabulary.test.ts

@@ -4,7 +4,7 @@
  * ── 계기 (2026-08-06, 사용자 신고) ───────────────────────────────────────────
  * 모델러의 엔티티 목록이 통째로 비어 있었다. **오류는 없었다.** 저장된 모델가 옛 어휘(`nodes`/`movers`)
  * 인데 화면과 호스트가 새 어휘를 읽었기 때문이다. 같은 원인이 구조 서명(`N[]M[]` — 서로 다른 두 공장이
- * 같아 보인다)·주행 추정기·설비 동기까지 조용히 망가뜨리고 있었다.
+ * 같아 보인다)·주행 추정기·설비 동기까지 알리지 않고 망가뜨리고 있었다.
  *
  * 그래서 **DB에서 읽는 순간** 한 번 정규화한다. 이 테스트가 지키는 것은 그 정규화가 ① 세 세대를 다
  * 흡수하고 ② 나머지 속성을 하나도 잃지 않고 ③ 새 모델에는 아무 일도 하지 않는 것이다.
@@ -101,7 +101,7 @@ test('두 옛 모델이 구조적으로 구별된다 — 서명이 빈 문자열
 })
 
 test('보드를 저장하는 엔티티가 **변환기를 달고 있다** — 결선이 빠지면 순수 모듈은 그린인데 화면은 빈다', () => {
-  /* 이 결함이 정확히 그랬다: 리더는 커널에 있었고 목록만 그것을 거쳤다. 결선은 조용히 빠질 수 있으므로
+  /* 이 결함이 정확히 그랬다: 리더는 커널에 있었고 목록만 그것을 거쳤다. 결선은 알리지 않고 빠질 수 있으므로
      기계가 지킨다. 새 엔티티가 보드를 담게 되면 여기 함께 올린다. */
   const owners = ['server/service/twin-instance/twin-instance.ts', 'server/service/twin-structure/twin-structure.ts']
 

package/test/move-space.test.ts

@@ -25,7 +25,7 @@ test('잃을 것이 없으면 경고도 없다 — 정상 경로를 시끄럽게
   assert.deepEqual(j.warnings, [])
 })
 
-test('없는 현장으로는 옮기지 않는다 — 조용히 새 공간을 만들지 않는다', () => {
+test('없는 현장으로는 옮기지 않는다 — 알리지 않고 새 공간을 만들지 않는다', () => {
   const j = judgeMoveTwinSpace({ ...CLEAN, toSpaceExists: false })
   assert.equal(j.refusal?.code, 'space-not-found')
   assert.equal(j.refusal?.params?.spaceId, 'rosarito-site')

package/test/oee-accumulator.test.ts

@@ -64,9 +64,24 @@ test('★ OEE 누적기: downMs 정확 · busyMs=run+setup · 근사 OEE 유효'
 
   // 근사 OEE 유효 + 한계 명시.
   const oee = acc.oee('fk-1', nowMs)
-  assert.ok(oee.overall >= 0 && oee.overall <= 1, 'OEE overall ∈ [0,1]')
-  assert.ok(oee.availability >= 0 && oee.availability <= 1, 'availability ∈ [0,1]')
-  assert.equal(oee.quality, 1, 'WMS 는 quality.output 없음(품질 개념 없음) → quality=1')
+  /*
+   * 총합은 **없을 수 있다.** 표준 시간(PRI)이 없으면 성능률이 안 나오고, 그러면 곱도 안 나온다
+   * (계약 0.5.0, ISO 22400 대조). 누적기는 사건에서 표준 시간을 알 수 없으므로 여기서는 없는 것이 정상이다.
+   *
+   * 예전에는 근거 없이 1 을 내서 총합이 늘 값을 가졌다. 그때 이 단언은 아무것도 지키지 않았다.
+   */
+  if (oee.overall === undefined) {
+    assert.ok(oee.missing?.includes('planned-run-time-per-item'), `총합이 없으면 이유가 있어야 한다: ${JSON.stringify(oee.missing)}`)
+  } else {
+    assert.ok(oee.overall >= 0 && oee.overall <= 1, 'OEE overall ∈ [0,1]')
+  }
+  assert.ok((oee.availability as number) >= 0 && (oee.availability as number) <= 1, 'availability ∈ [0,1]')
+  /*
+   * WMS 는 품질 개념이 없어 산출을 기록하지 않는다. 만든 것이 없으면 양품률은 **모름**이다.
+   * 예전에는 1 을 냈고, 그래서 품질을 재지도 않는 창고 설비가 「품질 100%」로 보였다.
+   */
+  assert.equal(oee.quality, undefined, 'WMS 는 산출 기록이 없으므로 양품률은 모름이다')
+  assert.ok(oee.missing?.includes('produced-quantity'))
 })
 
 test('★ OEE 누적기: quality.output 델타 소비 → quality 정확 (good/scrap 도출)', () => {
@@ -108,7 +123,7 @@ test('★ withLiveOee: projector 미러(oee 없음) + 누적기 → live 설비
 /*
  * ── 되짚은 화면에도 가동 이력이 있어야 한다 (2026-08-05) ────────────────────
  * OEE 는 원 시스템이 누적을 보내 주지 않아 호스트가 상태 전이를 적분해 만든다. 그런데 그 누적기는
- * **라이브에서만** 돌았고, 저널을 접는 경로는 그 계산을 하지 않았다 — 과거를 되짚으면 모든 설비가
+ * **라이브에서만** 돌았고, 저널을 계산하는 경로는 그 계산을 하지 않았다 — 과거를 되짚으면 모든 설비가
  * "가동 이력이 전혀 없음" 으로 보였다(실 저널: `rosarito-mes` 18대, `hatiolab-wms` 22대가 그랬다).
  *
  * 없는 것은 데이터가 아니라 계산이다: 입력은 저널에 다 있다. 그래서 같은 누적기에 같은 이벤트를
@@ -174,7 +189,7 @@ test('★ 계측 시점을 벽시계로 재지 않는다 — 과거 화면의
  *
  * 예전에는 `metricsSinceMs: 0` 을 돌려줬다. 시각이 epoch 밀리초라서 그 창은 곧 "1970년부터" 가 되고,
  * 공식의 분모가 지금 시각 전체가 된다 — 화면에 `idleMs 1767226603000`(약 56,000년) 유휴가 섰다.
- * 그 값은 availability·overall 의 분모이기도 해서 **성과 숫자 전체가 조용히 거짓**이 됐다.
+ * 그 값은 availability·overall 의 분모이기도 해서 **성과 숫자 전체가 알리지 않고 거짓**이 됐다.
  */
 test('이벤트를 못 본 설비는 계측 창을 만들지 않는다 — epoch 를 창으로 삼지 않는다', () => {
   const acc = new OeeAccumulator()

package/test/operational-vocabulary.test.ts

@@ -56,7 +56,7 @@ test('거부는 이유와 함께 남는다 — 유효한 것은 함께 통과한
   const { accepted, rejected } = ingestCanonicalRecords(
     [
       { taskId: 'tk-1', kind: 'pick', status: 'completed' },
-      { taskId: 'tk-2', kind: 'pick', status: 'FINISHED' } // 커널이 접을 수 없는 낱말
+      { taskId: 'tk-2', kind: 'pick', status: 'FINISHED' } // 커널이 다룰 수 없는 낱말
     ] as any,
     'domain-1',
     AT
@@ -66,7 +66,7 @@ test('거부는 이유와 함께 남는다 — 유효한 것은 함께 통과한
   assert.ok(rejected[0].errors.join(' ').length > 0)
 })
 
-test('피드 결선이 거부를 조용히 버리지 않는다 — 이유를 사람에게 말한다', () => {
+test('피드 결선이 거부를 알리지 않고 버리지 않는다 — 이유를 사람에게 말한다', () => {
   const src = readFileSync(fileURLToPath(new URL('../server/service/reference/reference-live.ts', import.meta.url)), 'utf-8')
   assert.match(src, /record\(s\) rejected/, '거부 수와 이유를 남긴다')
 })

package/test/project-structure-db.test.ts

@@ -12,7 +12,7 @@
  *  · 끊어진 참조는 **이름을 대고 보고**되고, 행 자체는 남는다(막지 않되 침묵하지 않는다)
  *  · **전량 교체** — 두 번 돌려도 늘지 않고, 원본에서 사라진 것은 행에서도 사라진다
  *  · 원본 표식(`sourceRef`·`ingestedAt`) 없는 행은 만들 수 없다(캐시라는 사실이 구조로 지켜진다)
- *  · 소요시간은 ISO 8601 **문자열 그대로** 남는다(분으로 접으면 초가 조용히 사라진다)
+ *  · 소요시간은 ISO 8601 **문자열 그대로** 남는다(분으로 줄이면 초가 오류 없이 사라진다)
  */
 import { test, before, after, beforeEach } from 'node:test'
 import assert from 'node:assert/strict'
@@ -161,7 +161,7 @@ test('원본 표식 없는 행은 만들 수 없다 — 캐시라는 사실이
   )
 })
 
-test('소요시간은 ISO 8601 문자열 그대로 — 분으로 접으면 초가 조용히 사라진다', async () => {
+test('소요시간은 ISO 8601 문자열 그대로 — 분으로 줄이면 초가 오류 없이 사라진다', async () => {
   const op = await ds.getRepository(TwinOperation).findOne({ where: { operationKey: 'cut' } })
   assert.equal(op?.duration, 'PT1H10M30S')
   /* 변동성·파라미터는 도메인마다 형이 달라 원형 그대로 싣는다. */

package/test/projection-reaches-screen.test.ts

@@ -16,7 +16,7 @@
  * 것은 "이 사실이 여기 앉는다" 는 선언이고, 앉을 자리를 만들어 두고 안 채우면 그 컬럼은 영원히 빈다.
  *
  * 그래서 컬럼마다 셋을 요구한다:
- *   ① 픽스처가 모델에 그 값을 싣는다(값을 줄 방법을 모르면 **검사가 실패한다** — 조용히 건너뛰면
+ *   ① 픽스처가 모델에 그 값을 싣는다(값을 줄 방법을 모르면 **검사가 실패한다** — 알리지 않고 건너뛰면
  *      그 컬럼은 아무도 안 보는 컬럼이 된다)
  *   ② 투영을 지나 행에 남는다
  *   ③ 조회 응답에 나온다(화면이 읽는 자리)
@@ -72,6 +72,11 @@ const VALUE: Record<string, unknown> = {
   parallelism: 2,
   level: 'WorkCenter',
   gs1Id: 'urn:epc:id:sgln:0614141.00001.0',
+  /*
+   * 설비의 정체성 — **GS1 키가 아닌 것이 정상이다.** 실측한 값은 인버터의 하드웨어 식별자다
+   * (`ES100000007d8d061d-1`). 자리의 `gs1Id`(SGLN)와 다른 축이라 이름도 다르다.
+   */
+  identity: 'ES100000007d8d061d-1',
   homeLocation: 'cut-station',
   mtbfMs: 600000,
   mttrMs: 60000,
@@ -131,7 +136,7 @@ function master(): any {
       assert.ok(
         col in VALUE,
         `픽스처가 "${c.axis}.${col}" 에 실을 값을 모른다 — VALUE 에 하나 적어라(모델의 사실이 아니면 NOT_FROM_MODEL 에 이유와 함께).\n` +
-          '조용히 건너뛰면 그 컬럼은 아무도 안 보는 컬럼이 되고, 그것이 이 하네스가 막으려는 실패다.'
+          '알리지 않고 건너뛰면 그 컬럼은 아무도 안 보는 컬럼이 되고, 그것이 이 하네스가 막으려는 실패다.'
       )
       o[col] = VALUE[col]
     }

package/test/projection-reads-declared.test.ts

@@ -0,0 +1,109 @@
+/*
+ * **투영이 읽는 이름이 선언에 실재하는가.**
+ *
+ * ── 무엇이 있었나 (2026-08-30) ────────────────────────────────────────────
+ * 설비 투영이 `m.gs1Id` 를 읽고 있었는데 **선언에 그런 필드가 없었다.** 그래서 그 칸은 일곱 대 모두
+ * 영원히 비어 있었다. 오류는 나지 않았다 — `?? null` 이 늘 `null` 을 냈을 뿐이다.
+ *
+ * 값은 한 칸 옆에 있었다. 커넥터가 인버터의 하드웨어 식별자를 이미 보내고 있었고, 정체성 칸도
+ * 있었는데 그 사이에 길이 없었다. 인티그레이션 레인이 「값이 한 칸 옆에 있다」고 알려 와서 찾았다.
+ *
+ * ── 왜 다른 시험이 못 잡았나 ─────────────────────────────────────────────
+ * `projection-reaches-screen` 은 **마스터 → 행 → 화면**을 걷는다. 그 길은 멀쩡했다 — 참조 계층이
+ * `gs1Id` 를 실어 보내고 있었기 때문이다. 끊긴 것은 **선언 → 행** 쪽이었고, 아무도 그 길을 걷지
+ * 않았다.
+ *
+ * 이 시험은 이름만 본다. 값이 흐르는지는 저 시험이 보고, 여기서는 **읽는 이름이 실재하는지**만 본다.
+ * 둘이 함께 있어야 「자리는 있고 길이 없다」가 막힌다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const req = createRequire(import.meta.url)
+
+const projection = readFileSync(join(here, '..', 'server', 'service', 'twin-model', 'project-structure.ts'), 'utf-8')
+
+/** 계약이 배포한 선언 타입 원문 — 이름이 실재하는지 여기서 확인한다. */
+const contractTypes = readFileSync(join(dirname(req.resolve('@operato/ops-contract')), '..', 'dist', 'contract.d.ts'), 'utf-8')
+const domainTypes = readFileSync(
+  join(dirname(req.resolve('@operato/ops-contract')), '..', 'dist', 'domain-definition.d.ts'),
+  'utf-8'
+)
+const declared = contractTypes + '\n' + domainTypes
+
+/**
+ * 투영 안의 변수 이름 → 그 변수가 무엇의 선언인가.
+ *
+ * 이름을 손으로 적는다. 투영이 변수를 바꾸면 이 목록이 낡는데, 그때 아래 「대상이 실재한다」 검사가
+ * 먼저 빨갛게 난다 — 낡은 채로 초록이 되지 않는다.
+ */
+const SUBJECTS: { varName: string; what: string }[] = [
+  { varName: 'l', what: '자리' },
+  { varName: 'm', what: '설비' },
+  { varName: 'o', what: '공정' }
+]
+
+/** 선언에서 오지 않는 이름 — 투영이 스스로 만드는 값이다. 이유를 함께 적는다. */
+const NOT_FROM_DECLARATION: Record<string, string> = {
+  sourceRef: '투영이 붙인다 — 어느 참조에서 왔나',
+  ingestedAt: '투영이 붙인다 — 언제 채웠나',
+  domain: '테넌트 — 호출부가 준다',
+  instanceId: '어느 트윈인가 — 호출부가 준다'
+}
+
+/**
+ * 그 변수에서 읽는 필드들.
+ *
+ * **형 단언을 지나서 본다** — `(m as any).x` 도 읽는 것이다. 처음에는 `m.x` 만 봤고, 그래서
+ * 유령 이름을 넣어도 잡지 못했다(2026-08-30). 실제 코드가 그 모양을 쓰고 있었으므로 그 자리를
+ * 통째로 놓치고 있었다.
+ *
+ * 단언을 쓰는 자리가 특히 위험하다 — 타입 검사가 이미 꺼져 있어서 컴파일러도 안 잡는다.
+ */
+function readsOf(varName: string): { field: string; line: number }[] {
+  const out: { field: string; line: number }[] = []
+  const plain = new RegExp(`(?<![A-Za-z0-9_.)])${varName}\\.([a-zA-Z][A-Za-z0-9]*)`, 'g')
+  const cast = new RegExp(`\\(\\s*${varName}\\s+as\\s+[^)]*\\)\\.([a-zA-Z][A-Za-z0-9]*)`, 'g')
+  projection.split('\n').forEach((text, i) => {
+    for (const re of [plain, cast]) for (const m of text.matchAll(re)) out.push({ field: m[1], line: i + 1 })
+  })
+  return out
+}
+
+test('★ 검사할 대상이 실재한다 — 없으면 이 시험은 아무것도 지키지 않는다', () => {
+  assert.ok(declared.length > 10_000, '계약 선언 원문을 못 읽었다')
+  for (const s of SUBJECTS) {
+    assert.ok(readsOf(s.varName).length > 0, `${s.what}(${s.varName}) 를 읽는 자리가 없다 — 투영이 바뀌었다`)
+  }
+})
+
+test('★ 투영이 읽는 이름이 선언에 실재한다 — 없는 이름을 읽으면 그 칸은 영원히 빈다', () => {
+  const ghosts: string[] = []
+  for (const s of SUBJECTS) {
+    for (const { field, line } of readsOf(s.varName)) {
+      if (field in NOT_FROM_DECLARATION) continue
+      /* 선언 어딘가에 그 이름이 필드로 있는가 — 타입을 가리지 않고 이름만 본다. */
+      if (!new RegExp(`\\b${field}\\??:`).test(declared)) {
+        ghosts.push(`project-structure.ts:${line}  ${s.what}.${field}`)
+      }
+    }
+  }
+  assert.deepEqual(
+    [...new Set(ghosts)],
+    [],
+    `선언에 없는 이름을 읽는다:\n${[...new Set(ghosts)].join('\n')}\n\n` +
+      '그 칸은 늘 null 이 되고 오류는 나지 않는다. 선언에 그 필드를 열거나, 투영이 읽는 이름을 고쳐라.\n' +
+      '선언에서 오는 값이 아니면 NOT_FROM_DECLARATION 에 이유와 함께 올려라.'
+  )
+})
+
+test('선언에서 오지 않는 이름에 이유가 적혀 있다', () => {
+  for (const [name, why] of Object.entries(NOT_FROM_DECLARATION)) {
+    assert.ok(why.trim().length > 5, `${name} 에 이유가 없다 — 이유 없이 올리면 이 시험이 아무것도 지키지 않는다`)
+  }
+})