@things-factory/headless-twin 10.0.8 → 10.0.10

package/dist-server/service/twin-model/twin-model-query.d.ts

@@ -0,0 +1,43 @@
+export declare class TwinModelQuery {
+    /**
+     * 이 선이 **얼마나 이어져 있나** — 그리고 **얼마나 끊겨 있나.**
+     *
+     * 선이 "선언되었고 양끝이 존재한다" 만 말하면 지도는 그림일 뿐이다. 관계에서 가장 중요한 정보는
+     * 대개 **부재**다 — 기준 자리가 비어 있는 설비 열두 대, 어느 라우트에도 안 실린 공정. 그것이
+     * 조감도에서 보여야 사람이 끊긴 데를 찾아다니지 않는다.
+     *
+     * 셋을 센다:
+     *  · `linked`   — 값이 있고 그 값이 상대편에 **실제로 있다**
+     *  · `dangling` — 값은 있는데 **가리키는 것이 없다**(끊어진 참조 — 가장 나쁜 부류)
+     *  · `missing`  — 값 자체가 없다(선택 관계면 정상, 필수 관계면 결손)
+     *
+     * 문서 어휘로 푼다 — 관계 선언의 필드 이름이 원본 문서의 어휘이기 때문이다(행은 자기 컬럼
+     * 이름을 쓴다). 그 사실을 `fillBasis` 로 함께 낸다.
+     */
+    private edgeFill;
+    twinModelSummary(instanceId: string, context: ResolverContext): Promise<any | null>;
+    /**
+     * **이 트윈에 무엇을 선언할 수 있나** — 값을 넣는 화면이 도메인의 모양을 알지 않게.
+     *
+     * 커널이 정한 명세(속성 id·단위·범위·설명)를 그대로 낸다. 화면이 「에너지 트윈이면 계약전력·요금
+     * 단가…」를 알고 있으면 도메인이 늘 때마다 화면을 고쳐야 하고 단위가 두 곳에 적힌다(ADR-0031).
+     *
+     * 지금 무엇이 선언돼 있는지도 함께 낸다(`declared`) — 화면이 두 번 묻지 않게, 그리고 「원천이 말한
+     * 값」과 「우리가 정한 값」을 한자리에서 견줄 수 있게(`PropertySource`, ADR-0034).
+     *
+     * 어휘가 없는 종류는 `properties: []` 다 — 「아직 없다」와 「아무 값이나 받는다」는 다르다.
+     */
+    twinDeclarations(instanceId: string, context: ResolverContext): Promise<any | null>;
+    /**
+     * **이 현장에 무엇을 선언할 수 있나** — 현장 값은 트윈의 것이 아니므로 트윈 없이 묻는다.
+     *
+     * ── 왜 트윈으로 묻지 않나 (2026-08-18) ─────────────────────────────────────
+     * 처음에는 트윈 화면에서 범위만 골라 현장 값을 넣게 했다. 그런데 **현장 값을 넣으려고 트윈을 골라야
+     * 하는 것**은 개념이 거꾸로다 — 트윈은 그 값을 읽는 쪽이다(사용자가 그 어긋남을 지적했다).
+     *
+     * 어휘와 대상은 **그 현장 트윈들의 합집합**이다: 한 현장에 여러 종류가 살고(에너지·창고·야드), 요금은
+     * 에너지 트윈만 읽는다. 합집합으로 내되 **어느 트윈이 그 대상을 가졌는지** 함께 낸다 — 아무 트윈도
+     * 읽지 않는 값을 넣는 일을 화면이 미리 보여 줄 수 있어야 한다.
+     */
+    spaceDeclarations(spaceId: string, context: ResolverContext): Promise<any | null>;
+}

package/dist-server/service/twin-model/twin-model-query.js

@@ -0,0 +1,551 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TwinModelQuery = void 0;
+const tslib_1 = require("tslib");
+const type_graphql_1 = require("type-graphql");
+const shell_1 = require("@things-factory/shell");
+const index_js_1 = require("../../engine/index.js");
+const twin_kernel_1 = require("@operato/twin-kernel");
+const twin_instance_js_1 = require("../twin-instance/twin-instance.js");
+const twin_space_js_1 = require("../twin-space/twin-space.js");
+const twin_reference_js_1 = require("../reference/twin-reference.js");
+const local_declarations_js_1 = require("../../engine/local-declarations.js");
+const operation_basis_js_1 = require("../../engine/operation-basis.js");
+const twin_location_js_1 = require("./twin-location.js");
+const twin_equipment_js_1 = require("./twin-equipment.js");
+const twin_operation_js_1 = require("./twin-operation.js");
+const standard_coverage_js_1 = require("./standard-coverage.js");
+const isa95_coverage_js_1 = require("./isa95-coverage.js");
+const iec61850_coverage_js_1 = require("./iec61850-coverage.js");
+const epcis_coverage_js_1 = require("./epcis-coverage.js");
+/**
+ * 이 공정에 선언된 시간을 **겹에서** 든다 — 좁은 겹이 이긴다(트윈 먼저, 없으면 현장).
+ *
+ * 모델에는 ISO 8601 로 구워지지만 화면에는 **사용자가 넣은 수와 단위**를 보인다: 「PT240S」를 보이면
+ * 자기가 넣은 값인지 알아볼 수 없다. 선언이 없으면 빈 배열이다(빈 값을 지어내지 않는다).
+ */
+function declaredDurationProperty(kind, instanceLayer, spaceLayer) {
+    const find = (layer) => {
+        const d = (layer ?? []).find(x => x?.target === 'operation' && String(x?.id ?? '') === kind);
+        return (d?.properties ?? []).find((p) => p?.id === 'operation.duration');
+    };
+    const p = find(instanceLayer) ?? find(spaceLayer);
+    if (!p)
+        return [];
+    return [{ id: 'operation.duration', value: String(p.value ?? ''), ...(p.uom ? { uom: String(p.uom) } : {}), source: 'local' }];
+}
+/** 표준 id → 그 표의 함수. 정책은 `standardsForKind` 가, 표는 각 파일이 가진다. */
+const COVERAGE = { isa95: isa95_coverage_js_1.isa95Coverage, epcis: epcis_coverage_js_1.epcisCoverage, iec61850: iec61850_coverage_js_1.iec61850Coverage };
+const warm_start_js_1 = require("../../engine/warm-start.js");
+/* 공유 모듈은 빌드 산출물로 참조한다 — 서버·클라이언트가 같은 규칙을 쓰는 자리다(같은 관행: entity-delta). */
+const axis_read_js_1 = require("@things-factory/headless-twin/dist-shared/axis-read.js");
+/* 커널 런타임 로드 — CJS 번들(엔진과 같은 방식). 축·관계 선언의 SSOT 다. */
+const { TWIN_AXES, TWIN_RELATIONS, axisInfo, axisSource, axisAppliesTo } = require('@operato/twin-kernel');
+/**
+ * 축 → 그 축이 이미 **행으로 옮겨졌나**. 옮겨진 축은 DB 가 세고, 아직인 축은 문서를 세어야 한다.
+ *
+ * 이 표가 곧 `ADR-0032` 이주의 진척이다 — 여기 없는 축은 아직 `TwinModelDef` 문서 안에 산다.
+ */
+const ROW_BACKED = {
+    locations: twin_location_js_1.TwinLocation,
+    equipment: twin_equipment_js_1.TwinEquipment,
+    operations: twin_operation_js_1.TwinOperation
+};
+/** `productionSpec.definition.recipes` 같은 경로를 문서에서 따라간다. */
+const at = (o, path) => path.split('.').reduce((a, k) => (a == null ? undefined : a[k]), o);
+function countInDocument(model, path) {
+    const v = at(model, path);
+    if (Array.isArray(v))
+        return v.length;
+    return v ? 1 : 0;
+}
+/*
+ * 트윈 모델 조회 — **이 트윈은 표준 모델의 어디를 채우고 있나**(`plans/twin-inspection.md` §2 ②).
+ *
+ * ── 답의 크기가 개념 수에 비례한다 ─────────────────────────────────────────
+ * 엔티티를 **절대 싣지 않는다.** 실으면 계약이 곧 무너지고, 규모가 오는 날 이 질의가 그대로
+ * 병목이 된다. 항목은 별도 질의(`twinModelEntities`)가 페이징으로 낸다.
+ *
+ * ── 개념 목록을 이 코드가 갖지 않는다 ───────────────────────────────────────
+ * 축·관계는 **커널 카탈로그가 선언**한다(`TWIN_AXES`·`TWIN_RELATIONS`). 그래서 야드의 `dock-door`
+ * 나 에너지의 계량기가 늘어도 여기 손댈 것이 없다 — 도메인마다 화면·질의가 하나씩 늘어나던
+ * 구조를 끊는 것이 이 설계의 요점이다(`ADR-0031`).
+ *
+ * ── 어떻게 셌는지 밝힌다 ───────────────────────────────────────────────────
+ * 지금은 축 셋만 행이고 나머지는 문서 안에 있다. 그 사실을 `basis` 로 **축마다** 말한다.
+ * 밝히지 않으면 "이 트윈은 3개 축뿐" 으로 읽히고, 이주가 어디까지 왔는지도 아무도 모른다.
+ */
+/** `inputs[].material` 처럼 배열을 지나는 선언 경로를 따라간다 — 배열 표기가 관계 선언의 문법이다. */
+function valuesAt(obj, field) {
+    let cur = [obj];
+    for (const seg of field.split('.')) {
+        const key = seg.endsWith('[]') ? seg.slice(0, -2) : seg;
+        const next = [];
+        for (const c of cur) {
+            if (c == null)
+                continue;
+            const v = c[key];
+            if (v == null)
+                continue;
+            if (Array.isArray(v))
+                next.push(...v);
+            else
+                next.push(v);
+        }
+        cur = next;
+    }
+    return cur.filter(v => v != null);
+}
+const idOf = (o) => (typeof o === 'string' ? o : o?.id ?? o?.key ?? o?.gtin ?? null);
+let TwinModelQuery = class TwinModelQuery {
+    /**
+     * 이 선이 **얼마나 이어져 있나** — 그리고 **얼마나 끊겨 있나.**
+     *
+     * 선이 "선언되었고 양끝이 존재한다" 만 말하면 지도는 그림일 뿐이다. 관계에서 가장 중요한 정보는
+     * 대개 **부재**다 — 기준 자리가 비어 있는 설비 열두 대, 어느 라우트에도 안 실린 공정. 그것이
+     * 조감도에서 보여야 사람이 끊긴 데를 찾아다니지 않는다.
+     *
+     * 셋을 센다:
+     *  · `linked`   — 값이 있고 그 값이 상대편에 **실제로 있다**
+     *  · `dangling` — 값은 있는데 **가리키는 것이 없다**(끊어진 참조 — 가장 나쁜 부류)
+     *  · `missing`  — 값 자체가 없다(선택 관계면 정상, 필수 관계면 결손)
+     *
+     * 문서 어휘로 푼다 — 관계 선언의 필드 이름이 원본 문서의 어휘이기 때문이다(행은 자기 컬럼
+     * 이름을 쓴다). 그 사실을 `fillBasis` 로 함께 낸다.
+     */
+    edgeFill(model, r) {
+        const fromInfo = axisInfo(r.from);
+        const toInfo = axisInfo(r.target.axis);
+        if (!fromInfo || !toInfo)
+            return {};
+        /*
+         * **문서로 셀 수 없는 관계는 세지 않는다.** 선 채움(이어짐·끊어짐·빈 것)은 두 축을 문서에서
+         * 살펴 센다. 그런데 일정·실적은 문서에 없다(관측 축) — 그 관계를 문서로 세면 언제나 0 이 나오고,
+         * 화면은 그것을 "전부 끊어졌다" 로 읽는다. 셀 수 없으면 **수를 내지 않는 편이 정직하다.**
+         */
+        if (axisSource(r.from) !== 'document' || axisSource(r.target.axis) !== 'document')
+            return {};
+        const listOf = (info) => {
+            const raw = at(model, info.path);
+            return Array.isArray(raw) ? raw : raw ? [raw] : [];
+        };
+        const targets = new Set(listOf(toInfo).map(idOf).filter(Boolean));
+        let linked = 0;
+        let dangling = 0;
+        let missing = 0;
+        for (const item of listOf(fromInfo)) {
+            const vals = valuesAt(item, r.field).map(v => (typeof v === 'object' ? idOf(v) : v)).filter(v => v != null).map(String);
+            if (!vals.length) {
+                missing++;
+                continue;
+            }
+            /* 한 항목이 여럿을 가리킬 수 있다(`steps[]`). 하나라도 끊겼으면 끊긴 쪽으로 센다 —
+               "대체로 이어져 있다" 는 진단이 아니다. */
+            if (vals.every(v => targets.has(v)))
+                linked++;
+            else
+                dangling++;
+        }
+        return { linked, dangling, missing, fillBasis: 'document' };
+    }
+    async twinModelSummary(instanceId, context) {
+        const domainId = context.state.domain.id;
+        const inst = await (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId } });
+        if (!inst)
+            return null;
+        /* 어느 원본을 반영하나 — 없을 수 있다(템플릿으로 세운 트윈). 그 사실도 사실이다. */
+        const ref = await (0, shell_1.getRepository)(twin_reference_js_1.TwinReference)
+            .findOne({ where: { domain: { id: domainId }, source: instanceId } })
+            .catch(() => null);
+        const model = inst.model ?? {};
+        /*
+         * **한 요청에 저널은 한 번만 접는다.**
+         *
+         * 관측 축(`orders`·`tasks`)은 상태에서 센다. 그 둘이 각자 `recover()` 를 부르고 있었고, 커널이
+         * 멈춰 있으면 그것은 **저널 전체를 다시 접는 일**이다(23,731건짜리 트윈에서 4.6초, 두 번이면 곱절).
+         * 트윈을 전부 멈춰도 이 화면이 5~7초 걸린 이유가 이것이다 — 부하가 아니라 같은 일을 두 번 한 것이다.
+         *
+         * 한 번만 접어 나눠 쓴다. 값이 같아지는 것은 덤이 아니라 **옳음**이다: 두 번 접으면 그 사이에
+         * 들어온 이벤트 때문에 오더와 작업이 서로 다른 시점의 사실이 될 수 있다.
+         */
+        let statePromise = null;
+        const stateOnce = () => (statePromise ??= (async () => {
+            const observing = index_js_1.TwinEngine.isRunning(domainId, instanceId);
+            let snap = observing ? (0, warm_start_js_1.unwrapState)(index_js_1.TwinEngine.snapshot(domainId, instanceId)) : null;
+            let folded = false;
+            if (!snap) {
+                try {
+                    snap = (0, warm_start_js_1.unwrapState)(await index_js_1.TwinEngine.recover(domainId, instanceId));
+                    folded = !!snap;
+                }
+                catch {
+                    /* 다시 계산할 것이 없다 — 0 으로 메우지 않는다(카드는 "모름" 을 낸다). */
+                }
+            }
+            return { snap, folded, observing };
+        })());
+        const concepts = await Promise.all(TWIN_AXES.map(async (a) => {
+            /*
+             * **이 종류에 없는 개념인가** — 「아직 없음」과 「해당 없음」은 다른 말이다.
+             *
+             * 에너지 트윈에는 옮겨 다니는 물건도, 배정할 사람도, 공정도 없다(커널이 축마다 선언한다).
+             * 그것을 「로트 0」으로 그리면 사용자는 채우러 갈 곳을 찾고, 적합성 표는 채우지 못한 것으로
+             * 센다 — 둘 다 거짓이다. 수는 `null`(모름이 아니라 셀 대상이 아님)이고 이유를 코드로 낸다.
+             *
+             * 세지도 않는다: 없는 개념을 행에서 세는 것은 질의만 늘리고 답을 바꾸지 않는다.
+             */
+            if (!axisAppliesTo(a.axis, inst.kind)) {
+                return {
+                    axis: a.axis,
+                    label: a.label,
+                    kind: a.kind,
+                    container: false,
+                    standardClass: a.standardClass,
+                    typeRole: a.typeRole ?? null,
+                    count: null,
+                    notApplicable: true,
+                    emptyBecause: 'not-applicable',
+                    basis: 'declaration'
+                };
+            }
+            const entity = ROW_BACKED[a.axis];
+            /* 문서 축만 문서로 센다 — 경로 없는 축을 세면 모델 루트를 훑는다(상태 축은 아래에서 센다). */
+            const inDocument = axisSource(a.axis) === 'document' ? countInDocument(model, a.path) : 0;
+            const inRows = entity
+                ? await (0, shell_1.getRepository)(entity).count({ where: { domain: { id: domainId }, instance: { id: inst.id } } })
+                : undefined;
+            /*
+             * **둘을 함께 세고 어긋나면 말한다.**
+             *
+             * 행으로 옮긴 축이라도 그 트윈이 투영을 거치지 않았으면 행은 0이다(인제스트 없이
+             * warm-start 된 트윈이 그렇다). 행만 보고 답하면 문서에 자리 6개가 있는데 화면은
+             * **0 이라고 말한다** — 조용한 거짓이고, 이 프로젝트가 내내 잡아 온 바로 그 부류다.
+             *
+             * 그래서 어느 하나로 메우지 않는다. 행 수를 답하되 문서 수를 함께 내고, 다르면
+             * `stale` 로 표시한다 — 그 차이 자체가 "이 트윈은 투영 이후 인제스트되지 않았다" 는 정보다.
+             */
+            const stale = entity !== undefined && inRows !== inDocument;
+            /*
+             * **그릇인가** — 문서에 객체 하나로 있는 축(`productionSpec`).
+             *
+             * `kind` 로는 갈리지 않는다: 커널은 공정·레시피·라우트도 `spec` 이라 부른다(같은 선언 부류라는
+             * 뜻이다). 그릇인지 아닌지는 **모양**이 말한다 — 목록이 되는 축은 배열이고, 한 벌뿐인 선언은
+             * 객체 하나다. 개념 지도는 개체를 세는 면이므로 그릇은 자기 면에서 통째로 읽는다.
+             */
+            const raw = axisSource(a.axis) === 'document' ? at(model, a.path) : undefined;
+            /*
+             * **관측 축은 상태가 센다**(일정·실적 — ISA-95 Part 4). 커널이 멈춰 있으면 `null` 이다:
+             * 0 으로 내면 "작업이 없는 공장" 으로 읽히고, 그건 거짓이다(관측이 없는 것과 0 건은 다르다).
+             * 이 화면이 관측 열에서 내내 지켜 온 구분을 카드에서도 지킨다.
+             */
+            if (axisSource(a.axis) === 'state') {
+                /* 스냅샷은 `{revision, state}` 봉투다 — 벗기지 않으면 축이 한 겹 안에 있어 언제나 `null` 이
+                   된다(커널은 도는데 카드가 "모름" 으로 보였다). 벗기는 규칙의 집은 `warm-start` 하나다. */
+                /*
+                 * 관측 중인지는 **런타임이 있는지**로 본다 — 캐시된 스냅샷은 관측이 아니다.
+                 *
+                 * 동작하지 않으면 저널을 접어 답한다(라이브=권위 · 히스토리=파생). 카드는 그 차이를 `basis` 로
+                 * 말한다: 파생을 권위처럼 내면 다시 계산한 수를 "지금 이만큼" 으로 읽게 된다.
+                 */
+                const { snap, folded, observing } = await stateOnce();
+                /* 축이 사는 자리는 **커널 선언이 말한다**(`path`) — 축 이름으로만 읽으면 중첩된 축이
+                   언제나 「관측 없음」이 된다(에너지의 수요 구간이 그렇다). 규칙은 `axisValueOf` 한 곳. */
+                const bucket = snap ? (0, axis_read_js_1.axisValueOf)(snap, a) ?? null : null;
+                return {
+                    axis: a.axis,
+                    label: a.label,
+                    kind: a.kind,
+                    container: false,
+                    standardClass: a.standardClass,
+                    typeRole: a.typeRole ?? null,
+                    count: Array.isArray(bucket) ? bucket.length : null,
+                    /*
+                     * **비었으면 왜 비었는지 말한다.** 0 과 `null` 만 내면 화면은 "없다" 까지만 말하고, 사용자는
+                     * "안 적어 놨나 · 아직 안 일어났나 · 못 세었나" 를 구별할 수 없다. 이 화면이 관측 열에서
+                     * 내내 지켜 온 구분(§observedAbsence)을 카드에서도 지킨다.
+                     */
+                    ...(Array.isArray(bucket) ? (bucket.length ? {} : { emptyBecause: 'none-yet' }) : { emptyBecause: 'not-observed' }),
+                    basis: folded ? 'journal' : 'state',
+                    observing,
+                    /* 선언이 아니라 관측인 축 — 화면이 "원본이 침묵했다" 로 읽지 않게 사실로 말한다. */
+                    observedOnly: true,
+                    standardUndeclared: !a.standardClass?.isa95 && !a.standardClass?.epcis && !a.standardClass?.iso55000
+                };
+            }
+            return {
+                axis: a.axis,
+                label: a.label,
+                kind: a.kind,
+                container: !Array.isArray(raw) && raw != null,
+                standardClass: a.standardClass,
+                typeRole: a.typeRole ?? null,
+                count: entity ? inRows : inDocument,
+                /*
+                 * 비었으면 왜 비었는지 — 선언 쪽은 세 갈래다.
+                 *  · `not-declared`   이 트윈의 모델이 그 축을 아예 말하지 않는다(대개 템플릿이 안 적었다)
+                 *  · `declared-empty` 선언은 있는데 목록이 비어 있다(적었다가 지운 것도 사실이다)
+                 *  · `not-projected`  문서엔 있는데 행에 없다 — 투영을 거치지 않은 트윈이다(`stale` 과 같은 사실)
+                 *
+                 * 셋을 "0" 하나로 합치면 사용자가 손볼 곳을 찾지 못한다: 첫째는 템플릿, 둘째는 원본,
+                 * 셋째는 다시 읽기다. 셋 다 다른 일이다.
+                 */
+                ...((entity ? inRows : inDocument)
+                    ? {}
+                    : {
+                        emptyBecause: entity && inDocument > 0 ? 'not-projected' : raw == null ? 'not-declared' : 'declared-empty'
+                    }),
+                /* 'rows' = DB 가 셌다(질의 가능) · 'document' = 문서를 세었다(아직 이주 전). */
+                basis: entity ? 'rows' : 'document',
+                ...(entity ? { documentCount: inDocument, stale } : {}),
+                /* 표준 투영이 없는 축은 **숨기지 않고** 그 사실을 낸다(ADR-0031). */
+                standardUndeclared: !a.standardClass?.isa95 && !a.standardClass?.epcis && !a.standardClass?.iso55000
+            };
+        }));
+        /*
+         * **원본이 모르는데 실행 중인 것** — 커널은 마스터에 없던 자원도 이벤트로 알게 되고
+         * `origin: 'observed'` 를 단다(`observed-reducer`). 그것을 표에 밀어 넣지 않는다 — 그러면
+         * 틱 루프에서 DB 로 쓰는 **두 번째 쓰기 경로**가 생기고, 실패하면 조용히 어긋난다
+         * (쓰기 경로는 인제스트 하나, ADR-0032-D).
+         *
+         * 대신 **여기서 비교해 낸다.** 이 차이는 숨겨야 할 불일치가 아니라 인스펙션이 답해야 할
+         * 질문이다 — "원본이 말한 적 없는 설비가 실제로 실행 중이다."
+         *
+         * 트윈이 안 실행 중이면 비교할 상대가 없다 — 그때는 `null` 이다(0 이 아니다. 없는 것과
+         * 세어 보지 못한 것은 다르다).
+         */
+        const snap = index_js_1.TwinEngine.snapshot(domainId, instanceId);
+        const observedOnly = snap
+            ? {
+                equipment: (snap.equipment ?? []).filter((e) => e?.origin === 'observed').map((e) => e.id),
+                locations: (snap.locations ?? []).filter((l) => l?.origin === 'observed').map((l) => l.id),
+                persons: (snap.persons ?? []).filter((p) => p?.origin === 'observed').map((p) => p.id)
+            }
+            : null;
+        /* 지도의 선 — 선언된 관계 중 **양끝이 이 트윈에 실재하는 것만**. 없는 선을 그리지 않는다. */
+        /* 선의 양끝 판정은 **문서든 행이든 있으면 있는 것**으로 본다 — 투영이 낡았다고 관계가 없어지진 않는다. */
+        const nonEmpty = new Set(concepts.filter(c => (c.count ?? 0) > 0 || (c.documentCount ?? 0) > 0).map(c => c.axis));
+        /* 선은 **얼마나 이어졌고 얼마나 끊겼는지**까지 말한다 — 관계에서 가장 중요한 정보는 대개 부재다. */
+        const edges = await Promise.all(TWIN_RELATIONS.filter((r) => r.target.kind === 'axis' && nonEmpty.has(r.from) && nonEmpty.has(r.target.axis)).map(async (r) => ({ from: r.from, to: r.target.axis, via: r.via, optional: !!r.optional, ...this.edgeFill(model, r) })));
+        return {
+            instanceId,
+            /* 사람이 부르는 이름 — 결선 줄이 업무키만 보이지 않게(업무키는 곁에 남는다). */
+            name: inst.name ?? null,
+            /*
+             * **생산 선언에서 갈 곳이 없는 두 값** — GS1 발행자와 대표 산출물.
+             *
+             * 나머지 선언(자재·레시피·라우트·공정)은 각자 개념 축이 있고, 자재의 GS1 참조는 자재가 보인다.
+             * 이 둘만 자기 축이 없다: 회사 접두사는 이 트윈의 **정체**(발행자)이고, 대표 레시피는 이 공장이
+             * 무엇을 만드는 곳인가다. 둘 다 결선 줄(어느 원본을 반영하나)과 같은 성격이라 그 줄에 둔다.
+             */
+            /*
+             * **표준 적합성** — 채운 것과 빠진 것을 함께.
+             *
+             * 이 화면은 "이 트윈이 표준 모델의 어디를 채우고 있나" 를 묻는다. 그런데 지금까지 답은 우리
+             * 축만 세었다 — 없는 것은 화면에 없으므로 아무도 묻지 않았다. 기준(표준의 목록)을 함께 내면
+             * 그 질문이 실제로 답을 갖는다(`isa95-coverage.ts` 의 머리말 참조).
+             */
+            /* 종류가 기대는 표준을 **모두** 낸다 — 하나만 말하면 그 트윈의 다른 기준이 보이지 않는다. */
+            standards: (0, standard_coverage_js_1.standardsForKind)(inst.kind).map(id => COVERAGE[id](TWIN_AXES.map(a => a.axis))),
+            production: (() => {
+                const spec = inst.model?.productionSpec;
+                if (!spec)
+                    return null;
+                const key = spec.recipeKey ?? null;
+                const material = (spec.definition?.materials ?? []).find((m) => (m.key ?? m.id) === key);
+                return {
+                    companyPrefix: spec.companyPrefix ?? null,
+                    recipeKey: key,
+                    /* 이름은 자재 선언이 말한다(i18n 키일 수 있으므로 번역은 화면의 일). */
+                    recipeLabel: material?.label ?? material?.name ?? null
+                };
+            })(),
+            description: inst.description ?? null,
+            kind: inst.kind,
+            realityMode: inst.realityMode,
+            source: ref
+                ? { referenceId: ref.source, adapterType: ref.adapterType, status: ref.status, lastSyncedAt: ref.lastSyncedAt }
+                : null,
+            /*
+             * **다시 읽을 수 있는가** — 이 트윈이 자기 원본을 기억하고 있나(`TwinInstance.origin`).
+             *
+             * 없는 트윈이 실제로 있다(이 자리가 생기기 전에 만들어진 것). 그때 화면이 버튼을 그대로
+             * 내면 누를 때마다 실패하고, 사용자는 무엇이 잘못됐는지 알 수 없다. 그래서 **할 수 있는지를
+             * 먼저 답한다** — 못 하는 것을 못 한다고 말하는 것도 이 화면의 일이다.
+             */
+            origin: inst.origin ?? null,
+            canResync: !!inst.origin?.kind,
+            concepts,
+            edges,
+            /* 원본이 모르는데 관측에는 있는 것. `null` = 트윈이 실행 중이 아니어서 비교하지 못했다. */
+            observedOnly,
+            /*
+             * 축 셋만 행이고 나머지는 문서에서 셌다는 사실. 축마다 `basis` 가 있지만 여기서도 한 번 말한다 —
+             * 화면이 "이 숫자는 무엇으로 셌나" 를 한눈에 보여야 규모 한계가 드러난다(ADR-0032 이주 압력).
+             */
+            basis: {
+                rows: Object.keys(ROW_BACKED),
+                document: TWIN_AXES.filter((a) => !ROW_BACKED[a.axis]).map((a) => a.axis),
+                /* 투영이 낡은 축 — 있으면 이 트윈은 인제스트를 한 번 더 태워야 한다. */
+                stale: concepts.filter((c) => c.stale).map((c) => c.axis)
+            }
+        };
+    }
+    /**
+     * **이 트윈에 무엇을 선언할 수 있나** — 값을 넣는 화면이 도메인의 모양을 알지 않게.
+     *
+     * 커널이 정한 명세(속성 id·단위·범위·설명)를 그대로 낸다. 화면이 「에너지 트윈이면 계약전력·요금
+     * 단가…」를 알고 있으면 도메인이 늘 때마다 화면을 고쳐야 하고 단위가 두 곳에 적힌다(ADR-0031).
+     *
+     * 지금 무엇이 선언돼 있는지도 함께 낸다(`declared`) — 화면이 두 번 묻지 않게, 그리고 「원천이 말한
+     * 값」과 「우리가 정한 값」을 한자리에서 견줄 수 있게(`PropertySource`, ADR-0034).
+     *
+     * 어휘가 없는 종류는 `properties: []` 다 — 「아직 없다」와 「아무 값이나 받는다」는 다르다.
+     */
+    async twinDeclarations(instanceId, context) {
+        const domainId = context.state.domain.id;
+        const inst = await (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId } });
+        if (!inst)
+            return null;
+        const model = (inst.model ?? {});
+        /*
+         * 겹이 둘이다 — **현장의 것과 이 트윈의 것**. 화면이 둘을 함께 봐야 「이 값이 어느 범위의 것인가」를
+         * 말할 수 있고, 철회 버튼이 어느 겹을 겨눌지 고를 수 있다(요금을 현장에 넣었는데 트윈에서 철회하려
+         * 하면 「겹에 없다」로 끝난다 — 사용자는 이유를 알 수 없다).
+         */
+        const space = inst.spaceId
+            ? await (0, shell_1.getRepository)(twin_space_js_1.TwinSpace).findOne({ where: { domain: { id: domainId }, spaceId: inst.spaceId } })
+            : null;
+        /*
+         * 돌고 있으면 커널이 「무엇으로 돌고 있나」를 스스로 답한다. 그 보고는 **작업이 새로 생길 때** 채워지
+         * 므로 재기동 직후에는 비는데, 이력에서 배운 종류는 그때도 남아 있다(실측으로 이 빈칸에 부딪혔다).
+         */
+        const operations = (0, operation_basis_js_1.operationBasis)(model, index_js_1.TwinEngine.kernel(domainId, instanceId), await index_js_1.TwinEngine.measuredOperationKinds(domainId, instanceId));
+        return {
+            instanceId,
+            kind: inst.kind,
+            spaceId: inst.spaceId,
+            spaceName: space?.name,
+            properties: (0, local_declarations_js_1.declarablePropertySpecs)(inst.kind),
+            declared: (inst.localDeclarations ?? []),
+            declaredAtSpace: (space?.localDeclarations ?? []),
+            /* 어디에 얹을 수 있나 — 모델의 자리·설비·공정. 화면이 대상을 지어내지 않게 목록으로 준다. */
+            targets: [
+                ...(model.locations ?? []).map((l) => ({ target: 'location', id: l.id, name: l.name, type: l.type, properties: l.properties ?? [] })),
+                ...((0, twin_kernel_1.readBoardEquipment)(model) ?? []).map((e) => ({ target: 'equipment', id: e.id, name: e.name, type: e.type ?? e.kind, properties: e.properties ?? [] })),
+                /*
+                 * 공정은 **자원이 아니다** — 값은 종류에 붙고, 그 종류에 명세 행이 없어도 된다(창고·야드에는 행이
+                 * 0개다). 그래서 대상 목록을 커널의 자기보고까지 합쳐 만든다(`operationBasis`).
+                 *
+                 * 지금 값은 **겹에서** 든다(사용자가 넣은 수와 단위 그대로). 모델에는 ISO 8601 로 구워지지만
+                 * 화면에 「PT240S」를 보이면 자기가 넣은 값인지 알아볼 수 없다.
+                 */
+                ...operations.map(op => ({
+                    target: 'operation',
+                    id: op.kind,
+                    name: op.label,
+                    properties: declaredDurationProperty(op.kind, inst.localDeclarations, space?.localDeclarations)
+                }))
+            ],
+            /*
+             * 이 트윈이 돌리는 공정과 **그 시간이 어디서 오나** — 선언 화면이 「무엇이 상수로 도나」를 보여야
+             * 사람이 채울 곳을 안다. `basis` 가 비면 아직 돌지 않은 것이다(공정이 없는 것이 아니다).
+             */
+            operations
+        };
+    }
+    /**
+     * **이 현장에 무엇을 선언할 수 있나** — 현장 값은 트윈의 것이 아니므로 트윈 없이 묻는다.
+     *
+     * ── 왜 트윈으로 묻지 않나 (2026-08-18) ─────────────────────────────────────
+     * 처음에는 트윈 화면에서 범위만 골라 현장 값을 넣게 했다. 그런데 **현장 값을 넣으려고 트윈을 골라야
+     * 하는 것**은 개념이 거꾸로다 — 트윈은 그 값을 읽는 쪽이다(사용자가 그 어긋남을 지적했다).
+     *
+     * 어휘와 대상은 **그 현장 트윈들의 합집합**이다: 한 현장에 여러 종류가 살고(에너지·창고·야드), 요금은
+     * 에너지 트윈만 읽는다. 합집합으로 내되 **어느 트윈이 그 대상을 가졌는지** 함께 낸다 — 아무 트윈도
+     * 읽지 않는 값을 넣는 일을 화면이 미리 보여 줄 수 있어야 한다.
+     */
+    async spaceDeclarations(spaceId, context) {
+        const domainId = context.state.domain.id;
+        const space = await (0, shell_1.getRepository)(twin_space_js_1.TwinSpace).findOne({ where: { domain: { id: domainId }, spaceId } });
+        if (!space)
+            return null;
+        const twins = await (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance).find({ where: { domain: { id: domainId }, spaceId } });
+        /* 어휘 합집합 — 같은 속성이 여러 종류에 있어도 한 번만 낸다(명세는 커널 하나에서 온다). */
+        const byId = new Map();
+        for (const t of twins)
+            for (const spec of (0, local_declarations_js_1.declarablePropertySpecs)(t.kind))
+                if (!byId.has(spec.id))
+                    byId.set(spec.id, spec);
+        /* 대상 합집합 — 같은 id 가 여러 트윈에 있으면 **그 트윈들을 함께** 든다(현장 값은 그 전부에 얹힌다). */
+        const targets = new Map();
+        for (const t of twins) {
+            const model = (t.model ?? {});
+            const add = (target, e) => {
+                const key = `${target}:${e.id}`;
+                const cur = targets.get(key);
+                if (cur) {
+                    cur.twins.push(t.instanceId);
+                    return;
+                }
+                targets.set(key, { target, id: e.id, name: e.name, type: e.type ?? e.kind, twins: [t.instanceId] });
+            };
+            for (const l of model.locations ?? [])
+                add('location', l);
+            for (const e of (0, twin_kernel_1.readBoardEquipment)(model) ?? [])
+                add('equipment', e);
+            /*
+             * 공정도 대상이다 — 「우리 현장의 적재는 4분」은 그 현장 창고 전부가 읽어야 하는 수다. 목록은 각
+             * 트윈의 것을 합집합으로 든다(돌고 있으면 커널이 스스로 답한다).
+             */
+            for (const op of (0, operation_basis_js_1.operationBasis)(model, index_js_1.TwinEngine.kernel(domainId, t.instanceId), await index_js_1.TwinEngine.measuredOperationKinds(domainId, t.instanceId)))
+                add('operation', { id: op.kind, name: op.label });
+        }
+        return {
+            spaceId,
+            spaceName: space.name,
+            properties: [...byId.values()],
+            declared: (space.localDeclarations ?? []),
+            targets: [...targets.values()],
+            /* 이 현장에 사는 트윈들 — 화면이 「누가 이 값을 읽나」를 말할 수 있게. */
+            twins: twins.map(t => ({ instanceId: t.instanceId, kind: t.kind, name: t.name }))
+        };
+    }
+};
+exports.TwinModelQuery = TwinModelQuery;
+tslib_1.__decorate([
+    (0, type_graphql_1.Query)(returns => shell_1.ScalarObject, {
+        nullable: true,
+        description: 'What this twin reflects and where it fills the standard model: per-concept counts, how each was counted, and the declared relations between concepts. Never carries entities — use twinModelEntities for items.'
+    }),
+    tslib_1.__param(0, (0, type_graphql_1.Arg)('instanceId')),
+    tslib_1.__param(1, (0, type_graphql_1.Ctx)()),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", [String, Object]),
+    tslib_1.__metadata("design:returntype", Promise)
+], TwinModelQuery.prototype, "twinModelSummary", null);
+tslib_1.__decorate([
+    (0, type_graphql_1.Query)(returns => shell_1.ScalarObject, {
+        nullable: true,
+        description: "What can be declared on this twin and what already is: the kernel's property specification (id, unit, range, note) plus the current local declarations at both scopes — this twin and its facility — each with the value it overrode. Empty properties mean this kind has no declaration vocabulary yet — not that anything goes."
+    }),
+    tslib_1.__param(0, (0, type_graphql_1.Arg)('instanceId')),
+    tslib_1.__param(1, (0, type_graphql_1.Ctx)()),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", [String, Object]),
+    tslib_1.__metadata("design:returntype", Promise)
+], TwinModelQuery.prototype, "twinDeclarations", null);
+tslib_1.__decorate([
+    (0, type_graphql_1.Query)(returns => shell_1.ScalarObject, {
+        nullable: true,
+        description: 'What can be declared for a whole facility (space) and what already is: the union of the property specifications of the twin kinds living there, the union of their declarable targets (with which twins carry each), and the current facility-scope declarations.'
+    }),
+    tslib_1.__param(0, (0, type_graphql_1.Arg)('spaceId')),
+    tslib_1.__param(1, (0, type_graphql_1.Ctx)()),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", [String, Object]),
+    tslib_1.__metadata("design:returntype", Promise)
+], TwinModelQuery.prototype, "spaceDeclarations", null);
+exports.TwinModelQuery = TwinModelQuery = tslib_1.__decorate([
+    (0, type_graphql_1.Resolver)()
+], TwinModelQuery);
+//# sourceMappingURL=twin-model-query.js.map