@things-factory/headless-twin 10.0.8 → 10.0.10

package/dist-server/engine/local-declarations.js

@@ -0,0 +1,528 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasPropertyVocabulary = hasPropertyVocabulary;
+exports.hasAnyDeclarable = hasAnyDeclarable;
+exports.isoDurationOf = isoDurationOf;
+exports.declarablePropertySpecs = declarablePropertySpecs;
+exports.validateLocalDeclarations = validateLocalDeclarations;
+exports.mergeLocalDeclarations = mergeLocalDeclarations;
+exports.applyLocalDeclarations = applyLocalDeclarations;
+exports.revokeLocalDeclarations = revokeLocalDeclarations;
+exports.restoreRevoked = restoreRevoked;
+exports.applyDeclarationLayers = applyDeclarationLayers;
+/*
+ * 로컬 선언 — **구조는 원천이, 수는 우리가.**
+ *
+ * ── 낱말부터: `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% 로 서고, 그 사실을 아무도 모른 채 피크가 깎이지 않는다.
+ *
+ * **속성 어휘는 사용자가 정의하지 않는다** — 커널이 정한 속성에 값을 넣는 문이다(그래서 이름도
+ * 「사용자 정의 속성」이 아니다).
+ */
+const twin_kernel_1 = require("@operato/twin-kernel");
+const travel_estimator_ts_1 = require("./travel-estimator.js");
+const property_effects_ts_1 = require("./property-effects.js");
+/** 이 종류의 트윈에서 커널이 읽는 선언 명세. 없으면 그 종류에는 선언 어휘가 없다. */
+function specOf(kind, propertyId) {
+    /* 종류 어휘와 공용 어휘를 함께 본다 — 속도는 어느 트윈에서나 읽히므로 EMS 밖에서도 받아야 한다. */
+    return declarablePropertySpecs(kind).find(s => s.id === propertyId);
+}
+/** 이 종류의 트윈에 선언 어휘가 있나 — 없으면 검사할 근거가 없으므로 받지 않는다. */
+function hasPropertyVocabulary(kind) {
+    return kind === 'ems';
+}
+/** 이 종류에 선언할 수 있는 것이 하나라도 있나 — 공용 어휘가 있으므로 대개 참이다. */
+function hasAnyDeclarable(kind) {
+    return declarablePropertySpecs(kind).length > 0;
+}
+/**
+ * **어느 종류에나 있는 선언** — 「읽는 코드가 있는 것」만.
+ *
+ * 효과 등록부(`PROPERTY_EFFECTS`)가 그 목록의 근거다: 값이 계산을 바꾸는 속성만 여기 온다. 지금은
+ * 설비의 `speed` 하나다(이동 시간 추정이 읽는다) — 자재의 `perBaseUnit` 은 자원 축이 아니라 자재
+ * 정의에 얹히므로 이 화면의 대상이 아니다.
+ *
+ * 지어내지 않는다: 새 효과를 코드로 붙이는 사람이 등록부에 한 줄을 더하면 여기에도 따라 나온다.
+ */
+/**
+ * 시간 단위(UN/CEFACT) → ms. **목록은 여기 하나** — 화면·AI 는 명세의 `uomChoices` 로 받아 간다.
+ *
+ * 셋만 두는 이유: 현장이 공정 시간을 말할 때 쓰는 단위가 초·분·시간이다. 일 단위는 공정이 아니라 체류에
+ * 가깝고, 그때는 그 값을 넣는 사람이 시간으로 환산해 말하는 편이 오해가 없다.
+ */
+const DURATION_UOM_MS = { SEC: 1_000, MIN: 60_000, HUR: 3_600_000 };
+const COMMON_SPECS = [
+    /*
+     * 주의 판정 기준 — **경보가 소음이 되지 않게 현장이 정한다.**
+     *
+     * 혼잡 90%·불량 15%는 우리가 정한 수였다. 통로를 95%로 채워 쓰는 창고는 그 기준에서 영구히 「병목」
+     * 이고, 초기 라인은 계속 「불량 과다」로 운다 — 그때 진짜 경보도 함께 묻힌다. 선언이 없으면 기본값을
+     * 쓰되 주의가 `basis: 'default'` 로 그 사실을 밝힌다(조용히 기본값을 진실로 두지 않는다).
+     */
+    {
+        id: twin_kernel_1.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: twin_kernel_1.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: twin_kernel_1.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: travel_estimator_ts_1.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(travel_estimator_ts_1.SPEED_TO_MPS)
+    },
+    /*
+     * 공정 소요시간 — **측정이 없을 때 상수를 대신한다.**
+     *
+     * 대상은 자리·설비가 아니라 **공정 종류**(`putaway`·`pick`·`spot`…)이고, 그 종류에 명세 행이 없어도
+     * 성립한다(실측: 창고·야드 트윈에는 행이 0개다). 단위를 반드시 받는다 — 「4」만으로는 4초인지 4분인지
+     * 알 수 없고, 짐작하면 예측이 60배 틀린다.
+     */
+    {
+        id: twin_kernel_1.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 인
+ * 작업은 영원히 끝나지 않는다).
+ */
+function isoDurationOf(value, uom) {
+    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 뿐). 어휘가 없는 종류도 **빈손이
+ * 아니다**: 속도는 어느 트윈에서나 읽히므로 창고·야드·생산 트윈에서도 넣을 수 있어야 한다.
+ */
+function declarablePropertySpecs(kind) {
+    const domain = hasPropertyVocabulary(kind)
+        ? Object.entries(twin_kernel_1.EMS_PROPERTY_SPEC).map(([id, spec]) => ({
+            id,
+            ...(spec.uom ? { uom: spec.uom } : {}),
+            dataType: spec.dataType,
+            ...(spec.range ? { range: spec.range } : {}),
+            note: spec.note
+        }))
+        : [];
+    /*
+     * **어느 대상에 얹히나는 효과 등록부가 답한다** — 명세에 손으로 또 적지 않는다(두 곳에 적으면 한쪽만
+     * 바뀐다). 등록부에 없는 속성은 제한을 **모르는** 것이므로 그대로 둔다(속성은 열려 있다).
+     */
+    const all = [...COMMON_SPECS, ...domain];
+    return all.map(s => {
+        const targets = s.targets ?? (0, property_effects_ts_1.declarationTargetsOf)(s.id);
+        return targets ? { ...s, targets } : s;
+    });
+}
+/**
+ * 로컬 선언을 검사한다 — **받은 것과 받지 않은 것을 함께** 돌려준다.
+ *
+ * 조용히 걸러내지 않는 이유: 사용자는 값을 넣었다고 믿는다. 무엇이 왜 빠졌는지 말해야 고칠 수 있다.
+ */
+function validateLocalDeclarations(kind, declarations, opts) {
+    const accepted = [];
+    const rejected = [];
+    for (const d of declarations ?? []) {
+        const target = 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 = [];
+        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?.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 };
+}
+/**
+ * 겹을 합친다 — 같은 대상·같은 속성이면 **새 값이 이긴다**(현장이 값을 고치는 일은 흔하다).
+ *
+ * 대상이나 속성을 지우는 일은 여기서 하지 않는다: 지움은 「값을 모르는 상태로 되돌린다」는 뜻이고,
+ * 그것은 값을 넣는 것과 다른 결정이므로 다른 문으로 말해야 한다.
+ */
+function mergeLocalDeclarations(current, incoming) {
+    const key = (t, id) => `${t}:${id}`;
+    const out = new Map();
+    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'` 를
+ * 값에 붙인다 — 화면·감사가 「누가 말한 값인가」를 되짚을 수 있다.
+ *
+ * 모델에 없는 대상에 얹으려 하면 **조용히 버리지 않고** 그 사실을 돌려준다(구조가 바뀌어 그 설비가
+ * 사라졌을 수 있고, 그때 사용자의 선언은 갈 곳이 없다).
+ */
+function applyLocalDeclarations(model, declarations) {
+    const decls = declarations ?? [];
+    if (!decls.length)
+        return { model, missingTargets: [], unreadable: [], layer: [] };
+    const missingTargets = [];
+    const unreadable = [];
+    /* 얹으면서 **무엇을 덮었는지** 함께 적어 돌려준다 — 철회는 그 기억이 있어야 성립한다. */
+    const layer = decls.map(d => ({ ...d, properties: d.properties.map(p => ({ ...p })) }));
+    const put = (list, d, memo) => {
+        const item = (list ?? []).find(x => String(x?.id ?? '') === d.id);
+        if (!item)
+            return false;
+        const props = 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.uom ? { uom: String(p.uom) } : {}), source: 'local' };
+            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, d, memo) => {
+        for (let i = 0; i < d.properties.length; i++) {
+            const p = d.properties[i];
+            if (p.id !== twin_kernel_1.OPERATION_PROPERTY.duration) {
+                unreadable.push({ target: 'operation', id: d.id, propertyId: p.id });
+                continue;
+            }
+            const iso = isoDurationOf(p.value, String(p.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 = {
+        ...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 = 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, missingTargets, unreadable, layer };
+}
+/**
+ * 겹에서 선언을 **뺀다** — 값을 넣는 것과 다른 결정이므로 다른 문이다.
+ *
+ * 없는 것을 뺐다고 말하지 않는다: 겹에 없던 대상·속성은 `notFound` 로 돌려준다(조용히 성공하면
+ * 사용자는 지웠다고 믿고 값은 그대로 남는다 — 가장 비싼 종류의 침묵이다).
+ *
+ * 속성이 하나도 남지 않은 대상은 겹에서 사라진다(빈 껍데기를 남기지 않는다).
+ */
+function revokeLocalDeclarations(current, revocations) {
+    const layer = (current ?? []).map(d => ({ ...d, properties: d.properties.map(p => ({ ...p })) }));
+    const revoked = [];
+    const notFound = [];
+    for (const r of revocations ?? []) {
+        const target = 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` 로 말한다 — 원래 값을 지어내는 것은
+ *    잘못 넣은 값을 그대로 두는 것보다 나쁘다(다음 원천 재읽기가 그 자리를 바로잡는다).
+ */
+function restoreRevoked(model, revoked) {
+    if (!revoked.length)
+        return { model, restored: [], unknownSource: [], missingTargets: [] };
+    const next = {
+        ...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 = [];
+    const unknownSource = [];
+    const missingTargets = [];
+    for (const r of revoked) {
+        /*
+         * 공정 시간은 표에서 **뺀다** — 되돌릴 원천 값이 없는 자리다(전부 우리가 정한 값이었다).
+         * 빼면 원천 명세(있으면)나 커널 상수가 다시 답한다: 그것이 「선언 이전」의 상태다.
+         */
+        if (r.target === 'operation') {
+            const table = 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 = (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 = 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, restored, unknownSource, missingTargets };
+}
+/**
+ * 두 겹을 **순서대로** 얹는다 — 현장 먼저, 트윈이 나중.
+ *
+ * ── 왜 순서가 규율인가 (2026-08-18) ─────────────────────────────────────────
+ * 요금 단가는 현장의 계약이므로 그 현장의 트윈 전부가 같은 값을 읽어야 한다. 그런데 한 트윈만 다른
+ * 값으로 실험하는 일이 있다(인상된 단가로 what-if). 그때 현장 값을 고치게 하면 **나머지 트윈이 함께
+ * 흔들린다.** 그래서 더 좁은 선언이 이긴다 — 넓은 값은 그대로 두고 좁은 자리에서만 달라진다.
+ *
+ * 기억(`replaced`)은 각 겹이 **자기가 덮은 값**을 적는다: 트윈 겹의 기억은 「현장 값을 덮었다」가 되고,
+ * 철회하면 현장 값으로 돌아간다(원천까지 가지 않는다). 그것이 사람이 기대하는 되돌림이다.
+ */
+function applyDeclarationLayers(model, spaceLayer, instanceLayer) {
+    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', ...u })),
+            ...second.unreadable.map(u => ({ scope: 'instance', ...u }))
+        ],
+        /*
+         * **현장 겹의 「갈 곳 없음」은 오류가 아니다.**
+         *
+         * 한 현장에는 여러 종류의 트윈이 산다(창고·야드·에너지). 요금을 현장에 선언하면 그 값은 수전 자리를
+         * 가진 에너지 트윈에만 얹히고, 창고 트윈에는 얹을 자리가 없다 — 그것이 정상이다. 그래서 범위를 함께
+         * 실어 보내고, 부르는 쪽이 현장 겹의 것은 경고로 올리지 않는다.
+         */
+        missingTargets: [
+            ...first.missingTargets.map(t => ({ scope: 'space', ...t })),
+            ...second.missingTargets.map(t => ({ scope: 'instance', ...t }))
+        ]
+    };
+}
+//# sourceMappingURL=local-declarations.js.map