@things-factory/headless-twin 10.0.8 → 10.0.10

package/test/local-declarations.test.ts

@@ -0,0 +1,554 @@
+/*
+ * 현장 선언 — **구조는 원천이, 수는 현장이.**
+ *
+ * 이 시험이 지키는 것: 사용자가 넣은 수가 ① 검사를 거치고(단위를 잘못 읽은 값이 조용히 들어가지 않는다)
+ * ② 원천에서 다시 그려도 살아남고 ③ 갈 곳이 없으면 그 사실이 남는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+import {
+  applyDeclarationLayers,
+  applyLocalDeclarations,
+  declarablePropertySpecs,
+  restoreRevoked,
+  revokeLocalDeclarations,
+  hasPropertyVocabulary,
+  mergeLocalDeclarations,
+  validateLocalDeclarations
+} from '../server/engine/local-declarations.ts'
+
+const emsModel = () => ({
+  locations: [{ id: 'incoming-1', type: 'incoming', properties: [{ id: 'contract.kW', value: '3500' }] }],
+  equipment: [{ id: 'ess-1', kind: 'battery' }]
+})
+
+test('커널이 읽는 속성만 받는다 — 지어낸 id 는 이유와 함께 거절한다', () => {
+  const r = validateLocalDeclarations('ems', [
+    { target: 'location', id: 'incoming-1', properties: [{ id: 'tariff.demandChargePerKW', value: 20 }, { id: 'tariff.madeUp', value: 5 }] }
+  ])
+  assert.equal(r.accepted[0].properties.length, 1)
+  assert.equal(r.rejected[0].propertyId, 'tariff.madeUp')
+  assert.equal(r.rejected[0].reason, 'unknown-property')
+})
+
+test('단위를 잘못 읽은 값은 범위에서 걸린다 — 0.8 은 80% 가 아니다', () => {
+  const r = validateLocalDeclarations('ems', [
+    { target: 'equipment', id: 'ess-1', properties: [{ id: 'storage.initialSoc', value: 120 }] }
+  ])
+  assert.equal(r.accepted.length, 0)
+  assert.equal(r.rejected[0].reason, 'out-of-range')
+  assert.match(String(r.rejected[0].expected), /0-100/)
+})
+
+test('수를 요구하는 속성에 글자가 오면 거절한다', () => {
+  const r = validateLocalDeclarations('ems', [
+    { target: 'location', id: 'incoming-1', properties: [{ id: 'contract.kW', value: '삼천오백' }] }
+  ])
+  assert.equal(r.rejected[0].reason, 'not-a-number')
+})
+
+test('통화처럼 글자인 속성은 그대로 받는다 — 수만 받는 문이 아니다', () => {
+  const r = validateLocalDeclarations('ems', [
+    { target: 'location', id: 'incoming-1', properties: [{ id: 'tariff.currency', value: 'USD' }] }
+  ])
+  assert.equal(r.accepted[0].properties[0].value, 'USD')
+})
+
+/*
+ * ── 어휘는 「읽는 코드가 있는 것」이다 (2026-08-18) ──────────────────────────
+ * 예전에는 EMS 밖에서 선언 어휘가 **아예 없었다**(그 종류에는 넣을 수 있는 것이 하나도 없다고 답했다).
+ * 그런데 설비의 `speed` 는 어느 트윈에서나 읽힌다(이동 시간 추정) — 창고·야드 트윈에서 그것을 넣지
+ * 못하는 것은 사실과 다르다. 그래서 효과 등록부에 있는 것은 종류와 무관하게 받는다.
+ */
+test('EMS 밖에도 공용 어휘가 있다 — 속도는 어느 트윈에서나 읽힌다', () => {
+  assert.equal(hasPropertyVocabulary('wms'), false, '도메인 어휘는 여전히 EMS 뿐이다')
+  const specs = declarablePropertySpecs('wms')
+  /* 읽는 코드가 있는 것만 — 판정 기준 셋(주의)과 속도. 새 효과를 붙이면 이 목록도 함께 자란다. */
+  assert.deepEqual(
+    specs.map(s => s.id).sort(),
+    ['attention.congestionRatio', 'attention.scrapMinSamples', 'attention.scrapRate', 'operation.duration', 'speed'],
+    '읽는 코드가 있는 것만'
+  )
+  /* 모르는 속성은 이제 「어휘가 없다」가 아니라 **「그 속성을 읽지 않는다」**로 거절된다(더 정확하다). */
+  const r = validateLocalDeclarations('wms', [{ target: 'location', id: 'dock-1', properties: [{ id: 'anything', value: 1 }] }])
+  assert.equal(r.accepted.length, 0)
+  assert.equal(r.rejected[0].reason, 'unknown-property')
+})
+
+test('속도는 단위 없이 받지 않는다 — 단위가 없으면 추정기가 그 설비를 버린다', () => {
+  const noUom = validateLocalDeclarations('wms', [{ target: 'equipment', id: 'fk-1', properties: [{ id: 'speed', value: '1.4' }] }])
+  assert.equal(noUom.accepted.length, 0)
+  assert.equal(noUom.rejected[0].reason, 'uom-required')
+  assert.match(String(noUom.rejected[0].expected), /MTS/, '무엇을 받는지 함께 말한다')
+})
+
+test('읽는 쪽이 모르는 단위는 거절한다 — 받아 두면 계산이 그 값을 버린다', () => {
+  const bad = validateLocalDeclarations('wms', [
+    { target: 'equipment', id: 'fk-1', properties: [{ id: 'speed', value: '1.4', uom: 'knots' }] }
+  ])
+  assert.equal(bad.rejected[0].reason, 'unknown-uom')
+})
+
+test('단위와 함께 오면 받고, 그 단위를 값에 붙여 나른다', () => {
+  const ok = validateLocalDeclarations('wms', [
+    { target: 'equipment', id: 'fk-1', properties: [{ id: 'speed', value: '1.4', uom: 'MTS' }] }
+  ])
+  assert.equal(ok.rejected.length, 0)
+  assert.deepEqual(ok.accepted[0].properties[0], { id: 'speed', value: '1.4', uom: 'MTS' })
+})
+
+test('속도 범위도 검사한다 — 사람이 손으로 넣는 값이다', () => {
+  const tooFast = validateLocalDeclarations('wms', [
+    { target: 'equipment', id: 'fk-1', properties: [{ id: 'speed', value: '900', uom: 'MTS' }] }
+  ])
+  assert.equal(tooFast.rejected[0].reason, 'out-of-range')
+})
+
+test('같은 속성을 다시 넣으면 새 값이 이긴다 — 현장이 값을 고치는 일은 흔하다', () => {
+  const first = mergeLocalDeclarations(undefined, [
+    { target: 'location', id: 'incoming-1', properties: [{ id: 'tariff.demandChargePerKW', value: '20' }] }
+  ])
+  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.deepEqual(second[0].properties.map(p => [p.id, p.value]), [
+    ['tariff.demandChargePerKW', '24'],
+    ['tariff.currency', 'USD']
+  ])
+})
+
+test('모델 위에 얹는다 — 원천 값은 남고, 현장 값에는 출처가 붙는다', () => {
+  const model = emsModel()
+  const { model: next } = applyLocalDeclarations(model, [
+    { target: 'location', id: 'incoming-1', properties: [{ id: 'tariff.demandChargePerKW', value: '20' }] },
+    { target: 'equipment', id: 'ess-1', properties: [{ id: 'storage.initialSoc', value: '80' }] }
+  ])
+  const inc: any = next.locations[0]
+  assert.equal(inc.properties.find((p: any) => p.id === 'contract.kW')?.value, '3500', '원천 값은 그대로')
+  const tariff = inc.properties.find((p: any) => p.id === 'tariff.demandChargePerKW')
+  assert.equal(tariff.value, '20')
+  assert.equal(tariff.source, 'local', '누가 말한 값인지 남는다 — 밖에서 참조해 온 값이 아니라 이 안에서 정한 값')
+  assert.equal((next.equipment[0] as any).properties[0].id, 'storage.initialSoc')
+  /* 입력 모델을 바꾸지 않는다 — 부르는 쪽의 객체가 몰래 변하면 추적이 어렵다. */
+  assert.equal((model.locations[0].properties ?? []).length, 1)
+})
+
+test('현장 값이 원천 값을 덮는다 — 고쳐 넣었다는 것은 원천이 낡았다는 뜻이다', () => {
+  const { model: next } = applyLocalDeclarations(emsModel(), [
+    { target: 'location', id: 'incoming-1', properties: [{ id: 'contract.kW', value: '4000' }] }
+  ])
+  const p: any = (next.locations[0] as any).properties.find((x: any) => x.id === 'contract.kW')
+  assert.equal(p.value, '4000')
+  assert.equal(p.source, 'local')
+})
+
+test('대상이 사라졌으면 그 사실을 낸다 — 갈 곳 없는 선언을 조용히 버리지 않는다', () => {
+  const { missingTargets } = applyLocalDeclarations(emsModel(), [
+    { target: 'equipment', id: 'ess-gone', properties: [{ id: 'storage.capacityKWh', value: '500' }] }
+  ])
+  assert.deepEqual(missingTargets, [{ target: 'equipment', id: 'ess-gone' }])
+})
+
+test('다시 그린 모델에 얹으면 값이 살아난다 — resync 가 지우지 못한다', () => {
+  /* 원천에서 새로 그린 모델(현장 값이 없다) + 보관한 겹 = 값이 돌아온다. */
+  const fresh = emsModel()
+  const layer = mergeLocalDeclarations(undefined, [
+    { target: 'location', id: 'incoming-1', properties: [{ id: 'tariff.energyChargePerKWh', value: '0.1' }] }
+  ])
+  const { model: next } = applyLocalDeclarations(fresh, layer)
+  assert.equal((next.locations[0] as any).properties.find((p: any) => p.id === 'tariff.energyChargePerKWh')?.value, '0.1')
+})
+
+/*
+ * ── 시각을 모르는 채 시각으로 판정하려 할 때 (2026-08-18) ────────────────────
+ * 발전 형상은 시각별 비율이라 시간대가 없으면 UTC 로 읽힌다 — KST 현장이면 밤 9시에 태양광 피크가 선다.
+ * 값이 그럴듯하게 나오므로 아무도 알아채지 못한다. 시간대를 지어내지 않고 그 조합을 말한다.
+ */
+import { generationWithoutTimeZone } from '../server/service/reference/reference-master.ts'
+
+test('경고 문장이 무엇을 해야 하는지 말한다 — 우리가 시간대를 짐작하지 않는다는 것까지', () => {
+  const w = generationWithoutTimeZone('plant-1-site', 'pv-1')
+  assert.equal(w.code, 'generation-without-time-zone')
+  assert.deepEqual(w.params, { spaceId: 'plant-1-site', equipmentId: 'pv-1' })
+  assert.match(w.message, /UTC/)
+  assert.match(w.message, /do not guess/)
+})
+
+/*
+ * ── 모양이 틀린 선언은 **왜 틀렸는지** 말해야 한다 (2026-08-18) ──────────────
+ * 필드 이름을 틀린 호출(예: id 대신 targetId)이 「받아준 선언이 없다」는 답만 받고 rejected 는 비어
+ * 있었다. 사용자는 값을 넣었다고 믿는데 화면은 아무것도 바뀌지 않고, 고칠 단서도 없다.
+ */
+test('대상 id 가 없으면 이유를 말한다 — 조용히 건너뛰지 않는다', () => {
+  const { accepted, rejected } = validateLocalDeclarations('ems', [
+    { properties: [{ id: 'contract.kW', value: '3500' }] } as any
+  ])
+  assert.equal(accepted.length, 0)
+  assert.equal(rejected.length, 1)
+  assert.equal(rejected[0].reason, 'no-target-id')
+})
+
+test('속성 id 가 없으면 이유를 말한다 — 대상은 알아도 무엇을 넣는지 모른다', () => {
+  const { accepted, rejected } = validateLocalDeclarations('ems', [
+    { target: 'location', id: 'incoming-1', properties: [{ value: '3500' } as any] }
+  ])
+  assert.equal(accepted.length, 0)
+  assert.equal(rejected[0].reason, 'no-property-id')
+  assert.equal(rejected[0].id, 'incoming-1', '어느 대상에서 났는지도 말한다')
+})
+
+/*
+ * ── 철회 (2026-08-18) ────────────────────────────────────────────────────────
+ * 선언은 겹에 보관되지만 **저장된 모델에 구워진다.** 그래서 겹에서 줄만 지워도 원래 값이 돌아오지
+ * 않았다 — 오타를 「원래 값을 다시 선언하는」 우회로만 고칠 수 있었고, 원래 값을 모르면 그 값이
+ * 영구히 이겼다. 그래서 겹이 무엇을 덮었는지 기억한다.
+ */
+const sourceModel = () => ({
+  locations: [
+    { id: 'incoming-1', type: 'incoming', properties: [{ id: 'contract.kW', value: '3500' }] },
+    { id: 'feeder-1', type: 'feeder' }
+  ],
+  equipment: []
+})
+
+test('얹을 때 덮은 원천 값을 기억한다 — 철회의 근거', () => {
+  const { layer } = applyLocalDeclarations(sourceModel(), [
+    { target: 'location', id: 'incoming-1', properties: [{ id: 'contract.kW', value: '600' }] }
+  ])
+  assert.equal(layer[0].properties[0].replaced, '3500')
+})
+
+test('원천에 없던 속성은 null 로 기억한다 — 철회하면 지운다', () => {
+  const { layer } = applyLocalDeclarations(sourceModel(), [
+    { target: 'location', id: 'feeder-1', properties: [{ id: 'tariff.energyChargePerKWh', value: '0.1' }] }
+  ])
+  assert.equal(layer[0].properties[0].replaced, null)
+})
+
+test('이미 우리 값이 구워진 모델에 다시 얹어도 기억을 망치지 않는다', () => {
+  const first = applyLocalDeclarations(sourceModel(), [
+    { target: 'location', id: 'incoming-1', properties: [{ id: 'contract.kW', value: '600' }] }
+  ])
+  /* 저장 모델(600 이 source:'local' 로 구워짐) 위에 값을 고쳐 얹는다 — 원천 값은 그대로 3500 이어야 한다. */
+  const second = applyLocalDeclarations(first.model, [
+    { target: 'location', id: 'incoming-1', properties: [{ id: 'contract.kW', value: '800', replaced: '3500' }] }
+  ])
+  assert.equal(second.layer[0].properties[0].replaced, '3500', '우리 값을 원천 값으로 기억하지 않는다')
+})
+
+test('철회가 원천 값을 되돌린다 — 그리고 우리 표식을 뗀다', () => {
+  const applied = applyLocalDeclarations(sourceModel(), [
+    { target: 'location', id: 'incoming-1', properties: [{ id: 'contract.kW', value: '600' }] }
+  ])
+  const { layer, revoked, notFound } = revokeLocalDeclarations(applied.layer, [
+    { target: 'location', id: 'incoming-1', propertyId: 'contract.kW' }
+  ])
+  assert.equal(layer.length, 0, '속성이 하나도 남지 않은 대상은 겹에서 사라진다')
+  assert.equal(notFound.length, 0)
+  const back = restoreRevoked(applied.model, revoked)
+  const p = (back.model.locations[0] as any).properties.find((x: any) => x.id === 'contract.kW')
+  assert.equal(p.value, '3500', '원천 값으로 돌아간다')
+  assert.equal(p.source, undefined, '현장 표식은 사라진다 — 다시 원천이 말한 값이다')
+})
+
+test('원천에 없던 속성은 철회하면 사라진다 — 0 으로 남기지 않는다', () => {
+  const applied = applyLocalDeclarations(sourceModel(), [
+    { target: 'location', id: 'feeder-1', properties: [{ id: 'tariff.energyChargePerKWh', value: '0.1' }] }
+  ])
+  const { revoked } = revokeLocalDeclarations(applied.layer, [
+    { target: 'location', id: 'feeder-1', propertyId: 'tariff.energyChargePerKWh' }
+  ])
+  const back = restoreRevoked(applied.model, revoked)
+  const props = (back.model.locations[1] as any).properties ?? []
+  assert.equal(props.find((x: any) => x.id === 'tariff.energyChargePerKWh'), undefined)
+})
+
+test('기억이 없는 옛 선언은 손대지 않고 그렇게 말한다 — 원래 값을 지어내지 않는다', () => {
+  const layerWithoutMemo = [
+    { target: 'location' as const, id: 'incoming-1', properties: [{ id: 'contract.kW', value: '600' }] }
+  ]
+  const model = applyLocalDeclarations(sourceModel(), layerWithoutMemo).model
+  const { revoked } = revokeLocalDeclarations(layerWithoutMemo, [
+    { target: 'location', id: 'incoming-1', propertyId: 'contract.kW' }
+  ])
+  const back = restoreRevoked(model, revoked)
+  assert.equal(back.restored.length, 0)
+  assert.deepEqual(back.unknownSource, [{ target: 'location', id: 'incoming-1', propertyId: 'contract.kW' }])
+  assert.equal((back.model.locations[0] as any).properties[0].value, '600', '값은 그대로다 — 다음 재읽기가 바로잡는다')
+})
+
+test('겹에 없는 것을 뺐다고 하지 않는다 — 조용한 성공이 가장 비싸다', () => {
+  const { revoked, notFound } = revokeLocalDeclarations(
+    [{ target: 'location', id: 'incoming-1', properties: [{ id: 'contract.kW', value: '600', replaced: '3500' }] }],
+    [
+      { target: 'location', id: 'incoming-1', propertyId: 'tariff.energyChargePerKWh' },
+      { target: 'equipment', id: 'pv-1', propertyId: 'generation.ratedKW' },
+      { target: 'location', id: 'incoming-1', propertyId: '' }
+    ]
+  )
+  assert.equal(revoked.length, 0)
+  assert.equal(notFound.length, 3)
+})
+
+/*
+ * ── 낱말이 되돌아가지 않게 (2026-08-18) ──────────────────────────────────────
+ *
+ * 이 겹의 이름은 오랫동안 `site*` 였다. 그런데 이 코드에서 `site` 는 **외부 시스템이 부르는 사업장**
+ * 이고(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')
+  /* 설명문(옛 이름을 왜 버렸는지)은 있어야 하므로, **코드 토큰**만 본다. */
+  const code = src
+    .split('\n')
+    .filter(line => !/^\s*(\*|\/\*|\/\/)/.test(line))
+    .join('\n')
+  assert.equal(/\bsiteDeclaration/.test(code), false, 'siteDeclaration* 은 쓰지 않는다')
+  assert.equal(/source: 'site'/.test(code), false, "표식은 source: 'local' 이다")
+  assert.equal(/\bfacilityDeclaration/.test(code), false, 'facility 는 화면의 영어이지 코드 낱말이 아니다')
+  assert.match(code, /source: 'local' as const/, '얹은 값은 local 로 표식된다')
+})
+
+test('축의 두 낱말이 계약에 선언돼 있다 — 얹혀 다니는 필드가 아니다', async () => {
+  /* 예전에는 source 표식이 커널 계약에 없는 필드로 얹혀 다녔다 — 소비처가 any 로 읽고, 상태에 정말
+     실리는지 아무도 검사할 수 없었다. */
+  const kernel: any = await import('@operato/twin-kernel')
+  const { model } = applyLocalDeclarations(
+    { locations: [{ id: 'incoming-1', type: 'incoming' }] },
+    [{ target: 'location', id: 'incoming-1', properties: [{ id: 'contract.kW', value: '3500' }] }]
+  )
+  const p = (model.locations[0] as any).properties[0]
+  /* 계약이 정한 두 값 외에는 쓰지 않는다. */
+  assert.ok(['reference', 'local'].includes(p.source), '표식은 reference|local 뿐이다')
+  assert.ok(kernel.EMS_PROPERTY, '커널 계약을 실제로 읽고 있다')
+})
+
+test('옛 표식이 구워진 값을 원천 값으로 오인하지 않는다 — 표식의 종류를 따지지 않는다', () => {
+  /* 개명 전 모델에는 source: 'site' 가 구워져 있다. 그것을 「표식 아님」으로 읽으면 우리 값을 원천
+     값으로 기억하고, 철회해도 같은 값으로 되돌아간다(고칠 길이 사라진다). */
+  const baked = {
+    locations: [{ id: 'incoming-1', type: 'incoming', properties: [{ id: 'contract.kW', value: '600', source: 'site' }] }]
+  }
+  const { layer } = applyLocalDeclarations(baked, [
+    { target: 'location', id: 'incoming-1', properties: [{ id: 'contract.kW', value: '800' }] }
+  ])
+  assert.equal(layer[0].properties[0].replaced, undefined, '맨 원천 값이 아니므로 기억하지 않는다')
+})
+
+
+/*
+ * ── 범위: 현장의 값과 트윈의 값 (2026-08-18) ─────────────────────────────────
+ * 요금 단가는 그 현장의 계약이므로 같은 수전을 보는 트윈이 둘이면 **같은 값을 두 번** 선언해야 했다.
+ * 두 번 적는 값은 반드시 갈라진다(하나만 고치는 날이 온다). 그래서 겹을 둘로 두고, **좁은 것이 이긴다**.
+ */
+const siteModel = () => ({
+  locations: [{ id: 'incoming-1', type: 'incoming', properties: [{ id: 'contract.kW', value: '3500' }] }],
+  equipment: []
+})
+
+test('현장 값이 트윈 전부에 얹힌다', () => {
+  const { model } = applyDeclarationLayers(
+    siteModel(),
+    [{ target: 'location', id: 'incoming-1', properties: [{ id: 'tariff.currency', value: 'USD' }] }],
+    []
+  )
+  const p = (model.locations[0] as any).properties.find((x: any) => x.id === 'tariff.currency')
+  assert.equal(p.value, 'USD')
+  assert.equal(p.source, 'local')
+})
+
+test('좁은 것이 이긴다 — 한 트윈만 다른 값으로 두어도 현장 값은 그대로다', () => {
+  const spaceLayer = [{ target: 'location' as const, id: 'incoming-1', properties: [{ id: 'tariff.energyChargePerKWh', value: '0.10' }] }]
+  const instLayer = [{ target: 'location' as const, id: 'incoming-1', properties: [{ id: 'tariff.energyChargePerKWh', value: '0.18' }] }]
+  const out = applyDeclarationLayers(siteModel(), spaceLayer, instLayer)
+  const p = (out.model.locations[0] as any).properties.find((x: any) => x.id === 'tariff.energyChargePerKWh')
+  assert.equal(p.value, '0.18', '트윈 값이 이긴다')
+  assert.equal(out.spaceLayerApplied[0].properties[0].value, '0.10', '현장 값은 그대로 남는다')
+})
+
+test('트윈 겹의 기억은 「현장 값을 덮었다」다 — 철회하면 현장 값으로 돌아간다', () => {
+  const spaceLayer = [{ target: 'location' as const, id: 'incoming-1', properties: [{ id: 'tariff.energyChargePerKWh', value: '0.10' }] }]
+  const instLayer = [{ target: 'location' as const, id: 'incoming-1', properties: [{ id: 'tariff.energyChargePerKWh', value: '0.18' }] }]
+  const out = applyDeclarationLayers(siteModel(), spaceLayer, instLayer)
+  /* 현장 겹이 이미 우리 표식을 붙였으므로 트윈 겹은 그것을 원천 값으로 기억하지 않는다(ADR-0034 규칙). */
+  assert.equal(out.instanceLayerApplied[0].properties[0].replaced, undefined)
+
+  /* 트윈 겹을 빼고 두 겹을 다시 얹으면 현장 값이 드러난다 — 그것이 사람이 기대하는 되돌림이다. */
+  const back = applyDeclarationLayers(siteModel(), out.spaceLayerApplied, [])
+  const p = (back.model.locations[0] as any).properties.find((x: any) => x.id === 'tariff.energyChargePerKWh')
+  assert.equal(p.value, '0.10')
+})
+
+test('현장 겹의 「갈 곳 없음」은 오류가 아니다 — 요금 자리가 없는 트윈이 정상이다', () => {
+  const out = applyDeclarationLayers(
+    { locations: [{ id: 'dock-1', type: 'dock' }], equipment: [] },
+    [{ target: 'location', id: 'incoming-1', properties: [{ id: 'tariff.currency', value: 'USD' }] }],
+    [{ target: 'location', id: 'nowhere', properties: [{ id: 'contract.kW', value: '100' }] }]
+  )
+  assert.deepEqual(
+    out.missingTargets,
+    [
+      { scope: 'space', target: 'location', id: 'incoming-1' },
+      { scope: 'instance', target: 'location', id: 'nowhere' }
+    ],
+    '범위를 함께 낸다 — 부르는 쪽이 현장 겹의 것은 경고로 올리지 않는다'
+  )
+})
+
+test('현장 겹이 원천 값을 덮으면 그 원천 값을 기억한다 — 현장 철회는 원천으로 돌아간다', () => {
+  const out = applyDeclarationLayers(
+    siteModel(),
+    [{ target: 'location', id: 'incoming-1', properties: [{ id: 'contract.kW', value: '600' }] }],
+    []
+  )
+  assert.equal(out.spaceLayerApplied[0].properties[0].replaced, '3500')
+})
+
+/*
+ * ── 같은 id 가 둘이면 그 사실을 말한다 (2026-08-18) ──────────────────────────
+ * 현장 값을 그 현장의 트윈 전부에 얹다가 한 트윈에서 투영이 터졌는데, 올라온 것은
+ * `SQLITE_CONSTRAINT: UNIQUE constraint failed …` 뿐이었다 — 무엇이 잘못됐는지 알 수 없다. 원인은 그
+ * 모델에 설비 `load-1` 이 두 번 있던 것이다. 배선이 사라지지 않게 소스 모양으로 지킨다(이 함수는 DB 를
+ * 물고 있어 단위 시험이 불러올 수 없다).
+ */
+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, '중복을 소리 없이 지우지 않는다')
+})
+
+test('얹을 때 단위도 함께 나른다 — 값만 얹으면 읽는 쪽이 그 설비를 버린다', () => {
+  const { model } = applyLocalDeclarations(
+    { locations: [], equipment: [{ id: 'fk-1', kind: 'forklift' }] },
+    [{ target: 'equipment', id: 'fk-1', properties: [{ id: 'speed', value: '1.4', uom: 'MTS' }] }]
+  )
+  const p = (model.equipment[0] as any).properties.find((x: any) => x.id === 'speed')
+  assert.equal(p.value, '1.4')
+  assert.equal(p.uom, 'MTS', '단위가 모델까지 가야 추정기가 읽는다')
+  assert.equal(p.source, 'local')
+})
+
+/*
+ * ── 공정 시간 (2026-08-18) ──────────────────────────────────────────────────
+ * 실측: 운영 중인 트윈 35개 중 **창고·야드는 공정 명세 행이 0개**였다. 그 트윈들은 `putaway`·`spot` 을
+ * 돌리는데 시간은 커널 상수에서 왔고, 「우리 창고는 적재가 4분」이라고 말할 문이 없었다.
+ *
+ * 행을 지어 만드는 길은 막혀 있다(`OperationDef` 는 `label`·`intent` 를 요구하고, 지어낸 `intent` 는
+ * 능력 계산까지 오염시킨다). 그래서 공정 시간은 **종류별 표**로 얹고 커널의 전용 창구로 실어 보낸다.
+ *
+ * 이 시험이 지키는 것:
+ *  ① 단위 없이는 받지 않는다 — 「4」는 4초인지 4분인지 알 수 없고 짐작하면 60배 틀린다.
+ *  ② 커널이 읽는 표기(ISO 8601)로 바뀌어 모델에 실린다.
+ *  ③ 축을 지킨다 — 공정 시간은 설비에, 계약전력은 공정에 얹히지 않는다.
+ *  ④ 오타 공정 이름은 확인할 수 있을 때 거절한다(모를 때는 받아 주고 모른다고 말한다).
+ *  ⑤ 철회하면 표에서 빠진다 — 그러면 원천 명세나 커널 상수가 다시 답한다.
+ */
+test('공정 시간을 단위와 함께 받아 ISO 8601 로 얹는다 — 커널은 초·분을 모른다', () => {
+  const { accepted, rejected } = validateLocalDeclarations('wms', [
+    { target: 'operation', id: 'putaway', properties: [{ id: 'operation.duration', value: '4', uom: 'MIN' }] }
+  ])
+  assert.deepEqual(rejected, [])
+  const { model, unreadable } = applyLocalDeclarations({ locations: [], equipment: [] }, accepted)
+  assert.deepEqual(unreadable, [])
+  assert.deepEqual((model as any).localDurations, { putaway: 'PT240S' })
+})
+
+test('시간 단위는 셋뿐이다 — 목록 밖 코드는 거절한다(명세가 목록을 든다)', () => {
+  const spec = declarablePropertySpecs('wms').find(s => s.id === 'operation.duration')!
+  assert.deepEqual(spec.uomChoices, ['SEC', 'MIN', 'HUR'])
+  assert.deepEqual(spec.targets, ['operation'], '공정에만 얹힌다')
+  const { rejected } = validateLocalDeclarations('wms', [
+    { target: 'operation', id: 'putaway', properties: [{ id: 'operation.duration', value: '4', uom: 'DAY' }] }
+  ])
+  assert.equal(rejected[0]?.reason, 'unknown-uom')
+})
+
+test('단위 없이 온 공정 시간은 거절한다 — 4초와 4분은 60배 다르다', () => {
+  const { accepted, rejected } = validateLocalDeclarations('wms', [
+    { target: 'operation', id: 'putaway', properties: [{ id: 'operation.duration', value: '4' }] }
+  ])
+  assert.deepEqual(accepted, [])
+  assert.equal(rejected[0]?.reason, 'uom-required')
+})
+
+test('축을 지킨다 — 공정 시간을 설비에, 계약전력을 공정에 넣지 못한다', () => {
+  const wrongEquipment = validateLocalDeclarations('wms', [
+    { target: 'equipment', id: 'fk-1', properties: [{ id: 'operation.duration', value: '4', uom: 'MIN' }] }
+  ])
+  assert.equal(wrongEquipment.rejected[0]?.reason, 'wrong-target')
+  assert.match(String(wrongEquipment.rejected[0]?.expected), /operation/)
+  const wrongOperation = validateLocalDeclarations('ems', [
+    { target: 'operation', id: 'putaway', properties: [{ id: 'contract.kW', value: '3500' }] }
+  ])
+  assert.equal(wrongOperation.rejected[0]?.reason, 'wrong-target')
+})
+
+test('지게차에 계약전력을 넣던 구멍이 막혔다 — 읽는 코드가 자리만 본다', () => {
+  const { accepted, rejected } = validateLocalDeclarations('ems', [
+    { target: 'equipment', id: 'fk-1', properties: [{ id: 'contract.kW', value: '3500' }] }
+  ])
+  assert.deepEqual(accepted, [])
+  assert.equal(rejected[0]?.reason, 'wrong-target')
+})
+
+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, [])
+  assert.equal(checked.rejected[0]?.reason, 'unknown-operation')
+  assert.match(String(checked.rejected[0]?.expected), /putaway/)
+  /* 목록이 없으면(아직 돌지 않은 트윈) 받아 준다 — 모르는 것과 없는 것은 다르다. */
+  assert.equal(validateLocalDeclarations('wms', decl).accepted.length, 1)
+})
+
+test('철회하면 표에서 빠진다 — 원천 명세나 커널 상수가 다시 답한다', () => {
+  const declared = [{ target: 'operation' as const, id: 'putaway', properties: [{ id: 'operation.duration', value: '4', uom: 'MIN' }] }]
+  const applied = applyLocalDeclarations({ locations: [], equipment: [] }, declared)
+  /* 이 창구에는 원천 값이 없다 — 기억은 언제나 「없었다」다. */
+  assert.equal(applied.layer[0].properties[0].replaced, null)
+
+  const { layer, revoked, notFound } = revokeLocalDeclarations(applied.layer, [
+    { target: 'operation', id: 'putaway', propertyId: 'operation.duration' }
+  ])
+  assert.deepEqual(notFound, [])
+  assert.deepEqual(layer, [], '속성이 없어진 대상은 겹에 남지 않는다')
+  const back = restoreRevoked(applied.model, revoked)
+  assert.equal((back.model as any).localDurations, undefined, '빈 표는 남기지 않는다')
+  assert.deepEqual(back.restored.length, 1)
+})
+
+test('없는 공정을 철회했다고 말하지 않는다 — 조용한 성공이 가장 비싸다', () => {
+  const back = restoreRevoked({ locations: [], equipment: [], localDurations: { pick: 'PT60S' } }, [
+    { target: 'operation', id: 'putaway', propertyId: 'operation.duration', replaced: null }
+  ])
+  assert.deepEqual(back.restored, [])
+  assert.deepEqual(back.missingTargets, [{ target: 'operation', id: 'putaway' }])
+  assert.deepEqual((back.model as any).localDurations, { pick: 'PT60S' }, '남의 값을 건드리지 않는다')
+})
+
+test('읽을 수 없는 값은 표에 넣지 않고 그 사실을 낸다 — 옛 겹·손으로 넣은 데이터', () => {
+  const { model, unreadable } = applyLocalDeclarations({ locations: [], equipment: [] }, [
+    { target: 'operation', id: 'putaway', properties: [{ id: 'operation.duration', value: 'four', uom: 'MIN' }] }
+  ])
+  assert.equal((model as any).localDurations, undefined)
+  assert.deepEqual(unreadable, [{ target: 'operation', id: 'putaway', propertyId: 'operation.duration' }])
+})
+
+test('두 겹이 함께 얹힌다 — 트윈 값이 현장 값을 이긴다(시간도 같은 규율)', () => {
+  const out = applyDeclarationLayers(
+    { locations: [], equipment: [] },
+    [{ target: 'operation', id: 'putaway', properties: [{ id: 'operation.duration', value: '5', uom: 'MIN' }] }],
+    [{ target: 'operation', id: 'putaway', properties: [{ id: 'operation.duration', value: '2', uom: 'MIN' }] }]
+  )
+  assert.deepEqual((out.model as any).localDurations, { putaway: 'PT120S' }, '좁은 겹이 이긴다')
+  assert.deepEqual(out.unreadable, [])
+})