@things-factory/headless-twin 10.0.9 → 10.0.11

package/server/engine/local-declarations.ts

@@ -0,0 +1,700 @@
+/*
+ * 로컬 선언 — **구조는 원천이, 수는 우리가.**
+ *
+ * ── 낱말부터: `reference` ↔ `local` (2026-08-18 확정) ───────────────────────
+ * 이 파일이 다루는 축은 **「이 값을 누가 말했나」** 하나다. 답은 둘뿐이다.
+ *
+ *  · `reference` — 외부 원천 시스템이 준 값(SCADA·WMS·MES 의 마스터). 우리가 고르지 않았다.
+ *  · `local`     — **이 트윈 쪽에서 정한 값.** 원천이 모르는 수를 운영 주체가 넣은 것이다.
+ *
+ * 「사람이 넣었나」가 아니라 **「권위가 어디 있나」**가 기준이다 — 앞으로 AI 가 사용자 대리로 채워도
+ * 여전히 `local` 이다. 표식은 커널 계약의 `PropertySource` 로 선언돼 있고, **표식이 없으면 모델을 그린
+ * 쪽**(참조에서 그렸으면 원천, 템플릿으로 만들었으면 그 템플릿)이다.
+ *
+ * 장소 낱말을 쓰지 않는 이유(옛 이름 `siteDeclarations` 를 버린 이유):
+ *  · `site`     — 이 코드에서는 **외부 시스템이 부르는 사업장**이다(SAP 는 `P3`, Oracle 은 `W01` 로 같은
+ *                 현장을 부른다). 여기 담기는 것은 그 시스템이 **모르는** 값이므로 이름이 내용과 정반대다.
+ *  · `facility` — 화면에 나가는 영어(현장)이고, 코드에 남은 것은 남의 API 필드뿐이다(Oracle lgfapi).
+ *  · `space`    — 「어디」에 답하는 낱말이다(트윈이 서는 그릇). 이 축은 「누가」에 답한다. 게다가 공간
+ *                 수준 선언(한 현장의 여러 트윈이 함께 읽는 요금)은 앞으로 정말 필요할 수 있어 비워 둔다.
+ *
+ * ── 왜 필요한가 ─────────────────────────────────────────────────────────────
+ * 커넥터로 만든 트윈은 구조를 원 시스템에서 읽어 온다(계통도·계량 지점·설비). 그런데 요금 단가·계약
+ * 정보·축전지 충전율은 원 시스템이 모른다 — SCADA 게이트웨이는 우리 전기 계약을 알지 못한다. 그래서 그
+ * 값들을 넣을 문이 없었고, 계량이 흐르는 트윈에서도 금액이 영원히 나오지 않았다(실제로 그 벽에 부딪혔다).
+ *
+ * ── 왜 모델에 바로 쓰지 않고 겹으로 두나 ────────────────────────────────────
+ * 모델은 **원천의 사본**이다. 다시 읽기(resync)는 그 사본을 새로 그리므로, 모델에 직접 쓴 값은 다음
+ * 다시 읽기에서 **조용히 사라진다** — 요금이 사라지면 금액도 사라지고, 사용자는 이유를 알 수 없다.
+ * 그래서 로컬 선언은 따로 보관하고, 모델을 그릴 때마다 그 위에 얹는다. 덤으로 「누가 말한 값인가」에
+ * 답할 수 있다 — 이 시스템이 근거를 값과 함께 다니게 하는 규율과 같다(`basis`·`derived` 와 한 결).
+ *
+ * ── 지어낸 속성을 받지 않는다 ───────────────────────────────────────────────
+ * 커널이 읽는 속성만 받는다. 모르는 id 를 받아 두면 사용자는 값을 넣었다고 믿고 화면은 아무것도 바뀌지
+ * 않는다 — 그 침묵이 가장 비싼 오류다. 단위·범위도 커널의 명세(`EMS_PROPERTY_SPEC`)로 검사한다:
+ * 「SOC 80%」를 `0.8` 로 넣으면 배터리가 0.8% 로 서고, 그 사실을 아무도 모른 채 피크가 깎이지 않는다.
+ *
+ * **속성 어휘는 사용자가 정의하지 않는다** — 커널이 정한 속성에 값을 넣는 문이다(그래서 이름도
+ * 「사용자 정의 속성」이 아니다).
+ */
+import { ATTENTION_PROPERTY, EMS_PROPERTY_SPEC, OPERATION_PROPERTY } from '@operato/twin-kernel'
+
+import { EQUIPMENT_PROPERTY, SPEED_TO_MPS } from './travel-estimator.ts'
+import { declarationTargetsOf } from './property-effects.ts'
+
+/** 로컬 선언이 겨눌 수 있는 대상 — 자원 둘과 **공정 종류**(자원이 아니라 명세다). */
+export type DeclarationTarget = 'location' | 'equipment' | 'operation'
+
+/** 한 대상(자리·설비·공정)에 얹을 로컬 선언. */
+export interface LocalDeclaration {
+  target: DeclarationTarget
+  /** 대상 id — 모델에 있는 그 이름. */
+  id: string
+  properties: {
+    id: string
+    value: string | number
+    /**
+     * 단위(UN/CEFACT 코드) — **어떤 값은 단위 없이는 뜻이 없다.**
+     *
+     * 속도가 그렇다: 단위가 없으면 이동 시간 추정기가 그 설비를 **거절한다**(그러면 공정 시간이 조용히
+     * 사라진다). 명세가 단위를 요구하면(`uomChoices`) 받고, 그 목록에 없는 코드는 거절한다 — 읽는 쪽이
+     * 모르는 단위를 받아 두면 화면은 넣었다고 말하고 계산은 그 값을 버린다.
+     */
+    uom?: string
+    /**
+     * 이 선언이 **덮은 원천 값** — 철회하면 이것으로 되돌린다.
+     *
+     * ── 왜 기억해야 하나 (2026-08-18) ────────────────────────────────────────
+     * 선언은 모델에 얹혀 **저장된 모델에 구워진다.** 그래서 겹에서 줄만 지워도 원래 값이 돌아오지
+     * 않는다 — 실제로 되돌릴 방법이 없어서, 잘못 넣은 값을 「원래 값을 다시 선언하는」 우회로만
+     * 고칠 수 있었다(사용자가 원래 값을 알고 있어야 한다는 뜻이다).
+     *
+     *  · 문자열 — 원천이 그 자리에 갖고 있던 값이다.
+     *  · `null`  — 원천에는 그 속성이 **없었다**(철회하면 속성을 지운다).
+     *  · 없음    — **우리가 모른다**(이 필드가 생기기 전에 선언된 것). 지어내지 않고 그렇게 말한다.
+     *
+     * 사용자가 넣는 값이 아니라 얹을 때 우리가 채우는 값이다(매 원천 재읽기마다 새로 채워져 낡지 않는다).
+     */
+    replaced?: string | null
+  }[]
+}
+
+export interface RejectedDeclaration {
+  target: string
+  id: string
+  propertyId: string
+  /**
+   * 왜 받지 않았나 — 언어중립 코드(화면이 옮긴다).
+   *  · `unknown-property`      — 커널이 읽지 않는 속성 id 다
+   *  · `out-of-range`          — 명세가 정한 범위 밖이다(단위를 잘못 읽은 값이 대개 여기 걸린다)
+   *  · `not-a-number`          — 수를 요구하는 속성에 수가 아닌 값이 왔다
+   *  · `empty-value`           — 값이 비어 있다(지우려면 그 뜻을 따로 말해야 한다)
+   *  · `no-property-vocabulary` — 이 종류의 트윈에는 선언 어휘가 아직 없다
+   *  · `no-target-id`           — 어느 대상에 얹을지 말하지 않았다(선언의 모양이 틀렸다)
+   *  · `no-property-id`         — 어느 속성인지 말하지 않았다(선언의 모양이 틀렸다)
+   *
+   * 뒤의 둘이 있는 이유: 예전에는 대상 id·속성 id 가 비면 **아무 말 없이 건너뛰었다.** 그래서 필드 이름을
+   * 틀린 호출이 「받아준 선언이 없다」는 답만 받고 `rejected` 는 비어 있었다 — 무엇이 틀렸는지 알 길이
+   * 없는 침묵이다(실제로 그 침묵에 걸렸다).
+   */
+  reason:
+    | 'unknown-property'
+    | 'out-of-range'
+    | 'not-a-number'
+    | 'empty-value'
+    | 'no-property-vocabulary'
+    | 'no-target-id'
+    | 'no-property-id'
+    /** 단위를 요구하는 속성인데 오지 않았다(그 값은 읽는 쪽이 버린다). */
+    | 'uom-required'
+    /** 읽는 쪽이 모르는 단위 코드다(명세가 받는 목록에 없다). */
+    | 'unknown-uom'
+    /**
+     * 이 속성은 그 종류의 대상에 얹히지 않는다 — 읽는 코드가 다른 축을 본다.
+     *
+     * 예전에는 지게차에 계약전력을 넣을 수 있었다(문은 받고 화면은 「넣었습니다」라고 말하는데 읽는
+     * 쪽은 자리만 본다). 어느 축의 속성인지는 효과 등록부가 이미 알고 있으므로 그것으로 거절한다.
+     */
+    | 'wrong-target'
+    /**
+     * 그 이름의 공정을 이 트윈에서 확인할 수 없다 — 커널이 돌린 적도 없고 명세 행에도 없다.
+     *
+     * 공정 선언은 자리·설비와 달리 **모델에 행이 없어도 성립한다**(창고·야드에는 행이 아예 없다).
+     * 그래서 오타를 잡아 줄 것이 이름 대조뿐이다 — 그마저 없으면 값은 조용히 아무 일도 하지 않는다.
+     */
+    | 'unknown-operation'
+  /** 무엇을 기대했나 — 사람이 고칠 수 있게(명세의 문장). */
+  expected?: string
+}
+
+/** 이 종류의 트윈에서 커널이 읽는 선언 명세. 없으면 그 종류에는 선언 어휘가 없다. */
+function specOf(kind: string | undefined, propertyId: string): DeclarablePropertySpec | undefined {
+  /* 종류 어휘와 공용 어휘를 함께 본다 — 속도는 어느 트윈에서나 읽히므로 EMS 밖에서도 받아야 한다. */
+  return declarablePropertySpecs(kind).find(s => s.id === propertyId)
+}
+
+/** 이 종류의 트윈에 선언 어휘가 있나 — 없으면 검사할 근거가 없으므로 받지 않는다. */
+export function hasPropertyVocabulary(kind: string | undefined): boolean {
+  return kind === 'ems'
+}
+
+/** 이 종류에 선언할 수 있는 것이 하나라도 있나 — 공용 어휘가 있으므로 대개 참이다. */
+export function hasAnyDeclarable(kind: string | undefined): boolean {
+  return declarablePropertySpecs(kind).length > 0
+}
+
+/**
+ * 이 종류의 트윈에 **선언할 수 있는 속성 목록** — 화면이 도메인의 모양을 알지 않게.
+ *
+ * 화면이 「에너지 트윈이면 계약전력·요금 단가…」를 알고 있으면, 도메인이 늘 때마다 화면을 고쳐야 하고
+ * 단위·범위가 두 곳에 적힌다(ADR-0031: 카탈로그가 선언하고 화면은 그린다). 그래서 커널의 명세를 그대로
+ * 낸다 — 화면은 받은 것을 렌더할 뿐이다.
+ *
+ * 어휘가 없는 종류는 **빈 목록**이다(「아직 없다」와 「아무 값이나 받는다」는 다르다).
+ */
+export interface DeclarablePropertySpec {
+  id: string
+  /** 사람이 읽는 단위(명세가 정한 것) — 값에 붙여 보인다. */
+  uom?: string
+  dataType: string
+  range?: [number, number]
+  note: string
+  /**
+   * 값과 **함께 단위를 골라야 하는** 속성 — 그 목록(UN/CEFACT 코드).
+   *
+   * 어떤 값은 단위 없이는 뜻이 없다: 속도는 단위가 없으면 추정기가 **거절한다**(「speed has no unit of
+   * measure」). 그래서 명세가 「단위를 받아야 한다」와 「무엇을 받나」를 함께 말한다 — 화면이 목록을
+   * 지어내면 화면이 받아 준 단위를 읽는 쪽이 모르는 일이 생긴다.
+   */
+  uomChoices?: string[]
+  /**
+   * 어느 종류의 대상에 얹히나(효과 등록부의 축) — 없으면 **우리가 제한을 모른다**(받아 준다).
+   *
+   * 화면은 이것으로 속성 목록을 대상에 맞게 좁힌다: 공정 시간을 설비에 넣으려는 선택지를 아예 보이지
+   * 않게 하는 것이, 넣게 하고 거절하는 것보다 낫다.
+   */
+  targets?: string[]
+}
+
+/**
+ * **어느 종류에나 있는 선언** — 「읽는 코드가 있는 것」만.
+ *
+ * 효과 등록부(`PROPERTY_EFFECTS`)가 그 목록의 근거다: 값이 계산을 바꾸는 속성만 여기 온다. 지금은
+ * 설비의 `speed` 하나다(이동 시간 추정이 읽는다) — 자재의 `perBaseUnit` 은 자원 축이 아니라 자재
+ * 정의에 얹히므로 이 화면의 대상이 아니다.
+ *
+ * 지어내지 않는다: 새 효과를 코드로 붙이는 사람이 등록부에 한 줄을 더하면 여기에도 따라 나온다.
+ */
+/**
+ * 시간 단위(UN/CEFACT) → ms. **목록은 여기 하나** — 화면·AI 는 명세의 `uomChoices` 로 받아 간다.
+ *
+ * 셋만 두는 이유: 현장이 공정 시간을 말할 때 쓰는 단위가 초·분·시간이다. 일 단위는 공정이 아니라 체류에
+ * 가깝고, 그때는 그 값을 넣는 사람이 시간으로 환산해 말하는 편이 오해가 없다.
+ */
+const DURATION_UOM_MS: Record<string, number> = { SEC: 1_000, MIN: 60_000, HUR: 3_600_000 }
+
+const COMMON_SPECS: DeclarablePropertySpec[] = [
+  /*
+   * 주의 판정 기준 — **경보가 소음이 되지 않게 현장이 정한다.**
+   *
+   * 혼잡 90%·불량 15%는 우리가 정한 수였다. 통로를 95%로 채워 쓰는 창고는 그 기준에서 영구히 「병목」
+   * 이고, 초기 라인은 계속 「불량 과다」로 운다 — 그때 진짜 경보도 함께 묻힌다. 선언이 없으면 기본값을
+   * 쓰되 주의가 `basis: 'default'` 로 그 사실을 밝힌다(조용히 기본값을 진실로 두지 않는다).
+   */
+  {
+    id: ATTENTION_PROPERTY.congestionRatio,
+    uom: '%',
+    dataType: 'xs:double',
+    range: [1, 100],
+    note: 'congestion threshold as a percentage 1-100 (95 means 95% of capacity) — above it this location is called a bottleneck. default 90.'
+  },
+  {
+    id: ATTENTION_PROPERTY.scrapRate,
+    uom: '%',
+    dataType: 'xs:double',
+    range: [1, 100],
+    note: 'scrap threshold as a percentage 1-100 (25 means 25%) — above it this equipment is called high-scrap, and twice it is severe. default 15.'
+  },
+  {
+    id: ATTENTION_PROPERTY.scrapMinSamples,
+    dataType: 'xs:double',
+    range: [1, 100000],
+    note: 'how many pieces must be counted before the scrap rate is judged at all — a ratio over few pieces is not evidence. default 10.'
+  },
+  {
+    id: EQUIPMENT_PROPERTY.speed,
+    dataType: 'xs:double',
+    range: [0.01, 50],
+    note: 'travel speed of this equipment — the estimator turns distance into duration with it. a unit is required.',
+    uomChoices: Object.keys(SPEED_TO_MPS)
+  },
+  /*
+   * 공정 소요시간 — **측정이 없을 때 상수를 대신한다.**
+   *
+   * 대상은 자리·설비가 아니라 **공정 종류**(`putaway`·`pick`·`spot`…)이고, 그 종류에 명세 행이 없어도
+   * 성립한다(실측: 창고·야드 트윈에는 행이 0개다). 단위를 반드시 받는다 — 「4」만으로는 4초인지 4분인지
+   * 알 수 없고, 짐작하면 예측이 60배 틀린다.
+   */
+  {
+    id: OPERATION_PROPERTY.duration,
+    dataType: 'xs:double',
+    range: [0.01, 100000],
+    note: 'how long this operation takes at this site — the simulation and the forecast use it instead of the built-in constant. a unit is required. history still wins where it exists.',
+    uomChoices: Object.keys(DURATION_UOM_MS)
+  }
+]
+
+/**
+ * 값 + 단위 → **ISO 8601 기간** — 커널이 읽는 표기로 바꾼다(커널은 초·분을 모른다, 표준 표기만 안다).
+ *
+ * 읽을 수 없으면 `undefined` — 부르는 쪽이 그 사실을 거절 사유로 올린다(0 을 만들지 않는다: 소요 0 인
+ * 작업은 영원히 끝나지 않는다).
+ */
+export function isoDurationOf(value: string | number, uom: string): string | undefined {
+  const n = Number(value)
+  const per = DURATION_UOM_MS[String(uom ?? '').trim()]
+  if (!Number.isFinite(n) || n <= 0 || !per) return undefined
+  return `PT${(n * per) / 1000}S`
+}
+
+/**
+ * 이 종류의 트윈에 **선언할 수 있는 속성 목록** — 화면이 도메인의 모양을 알지 않게.
+ *
+ * 종류와 무관한 것(효과 등록부에서 온다) + 그 종류의 어휘(지금은 EMS 뿐). 어휘가 없는 종류도 **빈손이
+ * 아니다**: 속도는 어느 트윈에서나 읽히므로 창고·야드·생산 트윈에서도 넣을 수 있어야 한다.
+ */
+export function declarablePropertySpecs(kind: string | undefined): DeclarablePropertySpec[] {
+  const domain = hasPropertyVocabulary(kind)
+    ? Object.entries(EMS_PROPERTY_SPEC as Record<string, any>).map(([id, spec]) => ({
+        id,
+        ...(spec.uom ? { uom: spec.uom } : {}),
+        dataType: spec.dataType,
+        ...(spec.range ? { range: spec.range as [number, number] } : {}),
+        note: spec.note
+      }))
+    : []
+  /*
+   * **어느 대상에 얹히나는 효과 등록부가 답한다** — 명세에 손으로 또 적지 않는다(두 곳에 적으면 한쪽만
+   * 바뀐다). 등록부에 없는 속성은 제한을 **모르는** 것이므로 그대로 둔다(속성은 열려 있다).
+   */
+  const all: DeclarablePropertySpec[] = [...COMMON_SPECS, ...domain]
+  return all.map(s => {
+    const targets = s.targets ?? declarationTargetsOf(s.id)
+    return targets ? { ...s, targets } : s
+  })
+}
+
+/**
+ * 로컬 선언을 검사한다 — **받은 것과 받지 않은 것을 함께** 돌려준다.
+ *
+ * 조용히 걸러내지 않는 이유: 사용자는 값을 넣었다고 믿는다. 무엇이 왜 빠졌는지 말해야 고칠 수 있다.
+ */
+export function validateLocalDeclarations(
+  kind: string | undefined,
+  declarations: readonly LocalDeclaration[] | undefined | null,
+  opts?: {
+    /**
+     * 이 트윈에서 확인된 공정 이름들 — 있으면 그 밖의 이름을 거절한다(오타를 잡는 유일한 수단이다).
+     *
+     * **모르면 넘기지 않고 모른다고 둔다**: 아직 돌지 않은 트윈은 어떤 공정을 돌릴지 알 수 없으므로
+     * 목록을 주지 않고(=undefined) 받아 준다. 부르는 쪽이 「확인하지 못했다」는 사실을 답에 싣는다.
+     */
+    knownOperations?: readonly string[]
+  }
+): { accepted: LocalDeclaration[]; rejected: RejectedDeclaration[] } {
+  const accepted: LocalDeclaration[] = []
+  const rejected: RejectedDeclaration[] = []
+  for (const d of declarations ?? []) {
+    const target: DeclarationTarget = d?.target === 'equipment' ? 'equipment' : d?.target === 'operation' ? 'operation' : 'location'
+    const id = String(d?.id ?? '').trim()
+    if (!id) {
+      /* 어느 대상인지 모르면 얹을 자리가 없다 — 그 사실을 말한다(조용히 버리지 않는다). */
+      rejected.push({ target, id: '', propertyId: '', reason: 'no-target-id' })
+      continue
+    }
+    const props: { id: string; value: string }[] = []
+    for (const p of d?.properties ?? []) {
+      const propertyId = String(p?.id ?? '').trim()
+      if (!propertyId) {
+        rejected.push({ target, id, propertyId: '', reason: 'no-property-id' })
+        continue
+      }
+      const raw = p?.value
+      if (raw === undefined || raw === null || String(raw).trim() === '') {
+        rejected.push({ target, id, propertyId, reason: 'empty-value' })
+        continue
+      }
+      if (!hasAnyDeclarable(kind)) {
+        rejected.push({ target, id, propertyId, reason: 'no-property-vocabulary' })
+        continue
+      }
+      const spec = specOf(kind, propertyId)
+      if (!spec) {
+        rejected.push({ target, id, propertyId, reason: 'unknown-property' })
+        continue
+      }
+      /*
+       * **읽는 쪽이 보는 축에만 얹는다** — 지게차에 계약전력을 넣을 수 있던 구멍을 여기서 막는다.
+       * 명세가 제한을 말하지 않으면(등록부에 없는 속성) 받아 준다: 속성은 열려 있고, 효과만 닫혀 있다.
+       */
+      if (spec.targets?.length && !spec.targets.includes(target)) {
+        rejected.push({ target, id, propertyId, reason: 'wrong-target', expected: `one of ${spec.targets.join(', ')}` })
+        continue
+      }
+      /* 공정 이름은 대조로만 걸러진다 — 모델에 행이 없어도 성립하는 선언이라 다른 안전망이 없다. */
+      if (target === 'operation' && opts?.knownOperations && !opts.knownOperations.includes(id)) {
+        rejected.push({ target, id, propertyId, reason: 'unknown-operation', expected: `one of ${[...opts.knownOperations].join(', ')}` })
+        continue
+      }
+      if (spec.dataType === 'xs:double') {
+        const n = Number(raw)
+        if (!Number.isFinite(n)) {
+          rejected.push({ target, id, propertyId, reason: 'not-a-number', expected: spec.note })
+          continue
+        }
+        if (spec.range && (n < spec.range[0] || n > spec.range[1])) {
+          rejected.push({ target, id, propertyId, reason: 'out-of-range', expected: spec.note })
+          continue
+        }
+      }
+      /*
+       * 단위를 요구하는 속성은 **단위까지 검사한다** — 값만 받아 두면 읽는 쪽이 그 설비를 건너뛴다.
+       * 목록은 명세가 든다(`uomChoices`): 화면이 목록을 지어내면 화면이 받아 준 단위를 계산이 모른다.
+       */
+      const uom = String((p as any)?.uom ?? '').trim()
+      if (spec.uomChoices?.length) {
+        if (!uom) {
+          rejected.push({ target, id, propertyId, reason: 'uom-required', expected: `one of ${spec.uomChoices.join(', ')}` })
+          continue
+        }
+        if (!spec.uomChoices.includes(uom)) {
+          rejected.push({ target, id, propertyId, reason: 'unknown-uom', expected: `one of ${spec.uomChoices.join(', ')}` })
+          continue
+        }
+      }
+      props.push({ id: propertyId, value: String(raw), ...(uom ? { uom } : {}) })
+    }
+    if (props.length) accepted.push({ target, id, properties: props })
+  }
+  return { accepted, rejected }
+}
+
+/**
+ * 겹을 합친다 — 같은 대상·같은 속성이면 **새 값이 이긴다**(현장이 값을 고치는 일은 흔하다).
+ *
+ * 대상이나 속성을 지우는 일은 여기서 하지 않는다: 지움은 「값을 모르는 상태로 되돌린다」는 뜻이고,
+ * 그것은 값을 넣는 것과 다른 결정이므로 다른 문으로 말해야 한다.
+ */
+export function mergeLocalDeclarations(
+  current: readonly LocalDeclaration[] | undefined | null,
+  incoming: readonly LocalDeclaration[]
+): LocalDeclaration[] {
+  const key = (t: string, id: string) => `${t}:${id}`
+  const out = new Map<string, LocalDeclaration>()
+  for (const d of current ?? []) out.set(key(d.target, d.id), { ...d, properties: [...d.properties] })
+  for (const d of incoming) {
+    const k = key(d.target, d.id)
+    const cur = out.get(k)
+    if (!cur) {
+      out.set(k, { ...d, properties: [...d.properties] })
+      continue
+    }
+    for (const p of d.properties) {
+      const at = cur.properties.findIndex(x => x.id === p.id)
+      if (at >= 0) cur.properties[at] = { ...p }
+      else cur.properties.push({ ...p })
+    }
+  }
+  return [...out.values()]
+}
+
+/**
+ * 모델 위에 로컬 선언을 얹는다 — **모델을 바꾸지 않고 새 모델을 돌려준다.**
+ *
+ * 원천이 같은 속성을 이미 말했으면 **로컬 값이 이긴다**: 계약전력을 게이트웨이가 말하더라도, 우리가
+ * 고쳐 넣었다는 것은 「원천의 값이 낡았다」는 뜻이다. 다만 그 사실이 보여야 하므로 `source: 'local'` 를
+ * 값에 붙인다 — 화면·감사가 「누가 말한 값인가」를 되짚을 수 있다.
+ *
+ * 모델에 없는 대상에 얹으려 하면 **조용히 버리지 않고** 그 사실을 돌려준다(구조가 바뀌어 그 설비가
+ * 사라졌을 수 있고, 그때 사용자의 선언은 갈 곳이 없다).
+ */
+export function applyLocalDeclarations<T extends { locations?: any[]; equipment?: any[]; localDurations?: Record<string, string> }>(
+  model: T,
+  declarations: readonly LocalDeclaration[] | undefined | null
+): {
+  model: T
+  missingTargets: { target: string; id: string }[]
+  /**
+   * 읽을 수 있는 값으로 바꿀 수 없었던 선언 — **조용히 버리지 않기 위한 자리.**
+   *
+   * 지금은 공정 시간에서만 난다(단위가 없거나 수가 아니면 ISO 8601 기간을 만들 수 없다). 문에서 이미
+   * 검사하므로 정상 경로에서는 비어 있고, 옛 겹이나 손으로 넣은 데이터에서 드러난다.
+   */
+  unreadable: { target: string; id: string; propertyId: string }[]
+  layer: LocalDeclaration[]
+} {
+  const decls = declarations ?? []
+  if (!decls.length) return { model, missingTargets: [], unreadable: [], layer: [] }
+
+  const missingTargets: { target: string; id: string }[] = []
+  const unreadable: { target: string; id: string; propertyId: string }[] = []
+  /* 얹으면서 **무엇을 덮었는지** 함께 적어 돌려준다 — 철회는 그 기억이 있어야 성립한다. */
+  const layer: LocalDeclaration[] = decls.map(d => ({ ...d, properties: d.properties.map(p => ({ ...p })) }))
+
+  const put = (list: any[] | undefined, d: LocalDeclaration, memo: LocalDeclaration): boolean => {
+    const item = (list ?? []).find(x => String(x?.id ?? '') === d.id)
+    if (!item) return false
+    const props: any[] = Array.isArray(item.properties) ? [...item.properties] : []
+    for (let i = 0; i < d.properties.length; i++) {
+      const p = d.properties[i]
+      const at = props.findIndex(x => String(x?.id ?? '') === p.id)
+      const noted = memo.properties[i]
+      /*
+       * 기억은 **표식이 없는 값일 때만** 갱신한다 — ADR-0034 의 규칙 그대로: 표식이 없으면 모델을 그린
+       * 쪽(대개 원천)이 말한 값이고, 표식이 있으면 **누군가 찍은 것**이므로 맨 원천 값이 아니다.
+       *
+       * 이 함수는 원천에서 새로 그린 모델에도, 이미 선언이 구워진 저장 모델에도 얹힌다. 뒤쪽에서
+       * 무턱대고 적으면 **우리 값을 원천 값으로 기억**하게 되고(600 을 원천이 말한 것으로 적는다),
+       * 철회해도 같은 값으로 되돌아간다.
+       *
+       * `!== 'local'` 로 보지 않는 이유: 옛 표식(`'site'`)이 구워진 모델이 남아 있고, 그것을 「표식
+       * 아님」으로 읽으면 바로 그 오인이 일어난다. 호환 코드를 두는 것이 아니라 **규칙을 그대로 적는
+       * 것**이다 — 표식의 종류를 따지지 않는다.
+       */
+      if (at < 0) noted.replaced = null
+      else if (props[at]?.source === undefined) noted.replaced = String(props[at]?.value ?? '')
+      /*
+       * **단위도 함께 얹는다** (2026-08-18 실측으로 고침).
+       *
+       * 겹에는 단위를 담고도 모델에 얹을 때 떨어뜨리고 있었다 — 그러면 속도를 넣어도 이동 시간 추정기가
+       * 그 설비를 **버린다**(「speed has no unit of measure」). 화면은 「넣었습니다」라고 말하고 계산은
+       * 그 값을 못 쓰는, 가장 조용한 종류의 결함이다.
+       */
+      const next = { id: p.id, value: String(p.value), ...((p as any).uom ? { uom: String((p as any).uom) } : {}), source: 'local' as const }
+      if (at >= 0) props[at] = { ...props[at], ...next }
+      else props.push(next)
+    }
+    item.properties = props
+    return true
+  }
+
+  /**
+   * 공정 시간은 **자원 속성이 아니다** — 종류별 표(`localDurations`)에 담는다.
+   *
+   * 왜 자리·설비처럼 속성으로 담지 않나: 커널의 공정 명세 행(`OperationDef`)은 `label`·`intent` 를
+   * 요구하는데(ISA-95 `OperationsSegment`) 창고·야드 트윈에는 그 행이 **아예 없다**(실측: 35개 중
+   * WMS·YMS 전부 0개). 행을 지어 만들면 지어낸 `intent` 가 능력 계산까지 오염시킨다 — 「몇 분 걸리나」를
+   * 말하려고 「무슨 작업인가」를 발명하지 않는다.
+   *
+   * 이 표는 **전부 우리가 정한 값**이다(원천이 그리는 자리가 아니다). 그래서 기억(`replaced`)은 언제나
+   * `null` 이고, 철회는 「표에서 뺀다」로 끝난다 — 그러면 원천 명세나 커널 상수가 다시 답한다.
+   */
+  const putOperation = (durations: Record<string, string>, d: LocalDeclaration, memo: LocalDeclaration): void => {
+    for (let i = 0; i < d.properties.length; i++) {
+      const p = d.properties[i]
+      if (p.id !== OPERATION_PROPERTY.duration) {
+        unreadable.push({ target: 'operation', id: d.id, propertyId: p.id })
+        continue
+      }
+      const iso = isoDurationOf(p.value, String((p as any).uom ?? ''))
+      if (!iso) {
+        unreadable.push({ target: 'operation', id: d.id, propertyId: p.id })
+        continue
+      }
+      durations[d.id] = iso
+      memo.properties[i].replaced = null
+    }
+  }
+
+  /* 얕은 복사로는 안 된다 — 자리·설비 항목을 손대므로 그 배열과 항목까지 새로 만든다. */
+  const next: any = {
+    ...model,
+    ...(model.locations ? { locations: model.locations.map(n => ({ ...n, ...(n?.properties ? { properties: [...n.properties] } : {}) })) } : {}),
+    ...(model.equipment ? { equipment: model.equipment.map(e => ({ ...e, ...(e?.properties ? { properties: [...e.properties] } : {}) })) } : {}),
+    ...(model.localDurations ? { localDurations: { ...model.localDurations } } : {})
+  }
+  for (let i = 0; i < decls.length; i++) {
+    const d = decls[i]
+    if (d.target === 'operation') {
+      /* 빈 표를 남기지 않는다 — 「선언이 있다」와 「읽을 수 있는 선언이 하나도 없다」는 다른 사실이다. */
+      const table: Record<string, string> = next.localDurations ?? {}
+      putOperation(table, d, layer[i])
+      if (Object.keys(table).length) next.localDurations = table
+      continue
+    }
+    const ok = put(d.target === 'equipment' ? next.equipment : next.locations, d, layer[i])
+    if (!ok) missingTargets.push({ target: d.target, id: d.id })
+  }
+  return { model: next as T, missingTargets, unreadable, layer }
+}
+
+/** 철회 요청 하나 — 어느 대상의 어느 속성을 원천으로 되돌리나. */
+export interface DeclarationRevocation {
+  target: DeclarationTarget
+  id: string
+  propertyId: string
+}
+
+/** 철회된 항목 — 되돌릴 값을 함께 든다(모르면 `replaced` 가 없다). */
+export interface RevokedDeclaration extends DeclarationRevocation {
+  replaced?: string | null
+}
+
+/**
+ * 겹에서 선언을 **뺀다** — 값을 넣는 것과 다른 결정이므로 다른 문이다.
+ *
+ * 없는 것을 뺐다고 말하지 않는다: 겹에 없던 대상·속성은 `notFound` 로 돌려준다(조용히 성공하면
+ * 사용자는 지웠다고 믿고 값은 그대로 남는다 — 가장 비싼 종류의 침묵이다).
+ *
+ * 속성이 하나도 남지 않은 대상은 겹에서 사라진다(빈 껍데기를 남기지 않는다).
+ */
+export function revokeLocalDeclarations(
+  current: readonly LocalDeclaration[] | undefined | null,
+  revocations: readonly DeclarationRevocation[] | undefined | null
+): { layer: LocalDeclaration[]; revoked: RevokedDeclaration[]; notFound: DeclarationRevocation[] } {
+  const layer: LocalDeclaration[] = (current ?? []).map(d => ({ ...d, properties: d.properties.map(p => ({ ...p })) }))
+  const revoked: RevokedDeclaration[] = []
+  const notFound: DeclarationRevocation[] = []
+
+  for (const r of revocations ?? []) {
+    const target: DeclarationTarget = r?.target === 'equipment' ? 'equipment' : r?.target === 'operation' ? 'operation' : 'location'
+    const id = String(r?.id ?? '').trim()
+    const propertyId = String(r?.propertyId ?? '').trim()
+    if (!id || !propertyId) {
+      notFound.push({ target, id, propertyId })
+      continue
+    }
+    const d = layer.find(x => x.target === target && x.id === id)
+    const at = d ? d.properties.findIndex(p => p.id === propertyId) : -1
+    if (!d || at < 0) {
+      notFound.push({ target, id, propertyId })
+      continue
+    }
+    const [gone] = d.properties.splice(at, 1)
+    revoked.push({ target, id, propertyId, ...('replaced' in gone ? { replaced: gone.replaced } : {}) })
+  }
+
+  return { layer: layer.filter(d => d.properties.length), revoked, notFound }
+}
+
+/**
+ * 철회한 속성을 **모델에서 원천 값으로 되돌린다** — 저장된 모델에 값이 구워져 있기 때문이다.
+ *
+ *  · 기억한 값이 있으면 그 값으로 되돌리고 `source: 'local'` 표식을 뗀다(다시 원천이 말한 값이다).
+ *  · `null` 이면 원천에 없던 속성이므로 **지운다**.
+ *  · 기억이 없으면(옛 선언) **손대지 않고** `unknownSource` 로 말한다 — 원래 값을 지어내는 것은
+ *    잘못 넣은 값을 그대로 두는 것보다 나쁘다(다음 원천 재읽기가 그 자리를 바로잡는다).
+ */
+export function restoreRevoked<T extends { locations?: any[]; equipment?: any[]; localDurations?: Record<string, string> }>(
+  model: T,
+  revoked: readonly RevokedDeclaration[]
+): { model: T; restored: RevokedDeclaration[]; unknownSource: DeclarationRevocation[]; missingTargets: { target: string; id: string }[] } {
+  if (!revoked.length) return { model, restored: [], unknownSource: [], missingTargets: [] }
+
+  const next: any = {
+    ...model,
+    ...(model.locations ? { locations: model.locations.map(n => ({ ...n, ...(n?.properties ? { properties: [...n.properties] } : {}) })) } : {}),
+    ...(model.equipment ? { equipment: model.equipment.map(e => ({ ...e, ...(e?.properties ? { properties: [...e.properties] } : {}) })) } : {}),
+    ...(model.localDurations ? { localDurations: { ...model.localDurations } } : {})
+  }
+  const restored: RevokedDeclaration[] = []
+  const unknownSource: DeclarationRevocation[] = []
+  const missingTargets: { target: string; id: string }[] = []
+
+  for (const r of revoked) {
+    /*
+     * 공정 시간은 표에서 **뺀다** — 되돌릴 원천 값이 없는 자리다(전부 우리가 정한 값이었다).
+     * 빼면 원천 명세(있으면)나 커널 상수가 다시 답한다: 그것이 「선언 이전」의 상태다.
+     */
+    if (r.target === 'operation') {
+      const table: Record<string, string> = next.localDurations ?? {}
+      if (!(r.id in table)) {
+        missingTargets.push({ target: r.target, id: r.id })
+        continue
+      }
+      delete table[r.id]
+      /* 빈 표는 남기지 않는다 — 「선언이 있다」와 「빈 표가 있다」가 구별되지 않는다. */
+      if (!Object.keys(table).length) delete next.localDurations
+      else next.localDurations = table
+      restored.push(r)
+      continue
+    }
+    const list: any[] = (r.target === 'equipment' ? next.equipment : next.locations) ?? []
+    const item = list.find(x => String(x?.id ?? '') === r.id)
+    if (!item) {
+      missingTargets.push({ target: r.target, id: r.id })
+      continue
+    }
+    if (!('replaced' in r)) {
+      unknownSource.push({ target: r.target, id: r.id, propertyId: r.propertyId })
+      continue
+    }
+    const props: any[] = Array.isArray(item.properties) ? [...item.properties] : []
+    const at = props.findIndex(x => String(x?.id ?? '') === r.propertyId)
+    if (r.replaced === null) {
+      if (at >= 0) props.splice(at, 1)
+    } else if (at >= 0) {
+      const { source: _dropped, ...rest } = props[at] ?? {}
+      props[at] = { ...rest, value: String(r.replaced) }
+    } else {
+      /* 겹은 있었는데 모델에는 없다 — 원천 값을 되살려 넣는다(우리가 지웠을 수 있다). */
+      props.push({ id: r.propertyId, value: String(r.replaced) })
+    }
+    item.properties = props
+    restored.push(r)
+  }
+
+  return { model: next as T, restored, unknownSource, missingTargets }
+}
+
+/** 선언이 어느 범위의 것인가 — 좁은 것이 이긴다(`space` 먼저, `instance` 나중). */
+export type DeclarationScope = 'space' | 'instance'
+
+/**
+ * 두 겹을 **순서대로** 얹는다 — 현장 먼저, 트윈이 나중.
+ *
+ * ── 왜 순서가 규율인가 (2026-08-18) ─────────────────────────────────────────
+ * 요금 단가는 현장의 계약이므로 그 현장의 트윈 전부가 같은 값을 읽어야 한다. 그런데 한 트윈만 다른
+ * 값으로 실험하는 일이 있다(인상된 단가로 what-if). 그때 현장 값을 고치게 하면 **나머지 트윈이 함께
+ * 흔들린다.** 그래서 더 좁은 선언이 이긴다 — 넓은 값은 그대로 두고 좁은 자리에서만 달라진다.
+ *
+ * 기억(`replaced`)은 각 겹이 **자기가 덮은 값**을 적는다: 트윈 겹의 기억은 「현장 값을 덮었다」가 되고,
+ * 철회하면 현장 값으로 돌아간다(원천까지 가지 않는다). 그것이 사람이 기대하는 되돌림이다.
+ */
+export function applyDeclarationLayers<T extends { locations?: any[]; equipment?: any[]; localDurations?: Record<string, string> }>(
+  model: T,
+  spaceLayer: readonly LocalDeclaration[] | undefined | null,
+  instanceLayer: readonly LocalDeclaration[] | undefined | null
+): {
+  model: T
+  /** 현장 겹을 얹은 결과 — 저장해야 기억이 낡지 않는다. */
+  spaceLayerApplied: LocalDeclaration[]
+  instanceLayerApplied: LocalDeclaration[]
+  /** 갈 곳이 없던 대상 — 어느 범위에서 났는지 함께 낸다(현장 겹은 그 트윈에 없을 수 있다). */
+  missingTargets: { scope: DeclarationScope; target: string; id: string }[]
+  /** 읽을 수 있는 값으로 바꿀 수 없던 선언 — 범위와 함께(조용히 버리지 않는다). */
+  unreadable: { scope: DeclarationScope; target: string; id: string; propertyId: string }[]
+} {
+  const first = applyLocalDeclarations(model, spaceLayer)
+  const second = applyLocalDeclarations(first.model, instanceLayer)
+  return {
+    model: second.model,
+    spaceLayerApplied: first.layer,
+    instanceLayerApplied: second.layer,
+    unreadable: [
+      ...first.unreadable.map(u => ({ scope: 'space' as const, ...u })),
+      ...second.unreadable.map(u => ({ scope: 'instance' as const, ...u }))
+    ],
+    /*
+     * **현장 겹의 「갈 곳 없음」은 오류가 아니다.**
+     *
+     * 한 현장에는 여러 종류의 트윈이 산다(창고·야드·에너지). 요금을 현장에 선언하면 그 값은 수전 자리를
+     * 가진 에너지 트윈에만 얹히고, 창고 트윈에는 얹을 자리가 없다 — 그것이 정상이다. 그래서 범위를 함께
+     * 실어 보내고, 부르는 쪽이 현장 겹의 것은 경고로 올리지 않는다.
+     */
+    missingTargets: [
+      ...first.missingTargets.map(t => ({ scope: 'space' as const, ...t })),
+      ...second.missingTargets.map(t => ({ scope: 'instance' as const, ...t }))
+    ]
+  }
+}