@things-factory/headless-twin 10.0.7 → 10.0.9

package/dist-server/engine/twin-level.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 성과를 접을 수 있는 단계 — 좁은 것부터.
+ *
+ * `equipment` 는 커널 축 이름으로 `resource` 다(설비·인원·자산을 아우르는 이름). 화면과 AI 는
+ * "설비" 로 말하고, 커널에 물을 때만 축 이름으로 바꾼다 — 그 변환이 아래 한 곳에 있다.
+ */
+export declare const TWIN_LEVELS: readonly ["space", "twin", "area", "location", "equipment"];
+export type TwinLevel = (typeof TWIN_LEVELS)[number];
+export declare function isTwinLevel(v: unknown): v is TwinLevel;
+/**
+ * 단계 → 커널의 나누는 축(`KpiGroupBy`). **전체를 보는 단계는 축이 없다** — 나누지 않고 통째로 접는다.
+ *
+ * `space` 와 `twin` 이 축 없이 같은 이유: 둘의 차이는 "무엇을 대상으로 삼는가"(공간 전체 대 트윈 하나)이지
+ * "어떻게 나누는가" 가 아니다. 대상은 질의의 `spaceId`/`instanceId` 가 정한다.
+ */
+export declare function kpiGroupByOfLevel(level: TwinLevel): 'area' | 'location' | 'resource' | undefined;
+/**
+ * 그 단계의 카드가 **대상 하나마다 한 장**인가.
+ *
+ * 구역·자리·설비는 여럿이라 카드가 그 수만큼 생긴다. 공간·트윈은 하나뿐이다. 보드를 자동으로 조립할 때
+ * 몇 장이 생길지 미리 알아야 한다 — 자리 200개 × 지표 4개면 800장이다.
+ */
+export declare function isPerTargetLevel(level: TwinLevel): boolean;

package/dist-server/engine/twin-level.js

@@ -0,0 +1,52 @@
+"use strict";
+/*
+ * 공간 계층의 **단계** — 성과를 어느 단위로 보는가. 순수(import 없음).
+ *
+ * ── 왜 여기 있나 ───────────────────────────────────────────────────────────
+ * 이 목록을 세 곳이 쓴다: 씬 표현이 "나는 어느 단계에 붙는다" 고 선언할 때(클라이언트), 성과 카드가
+ * "이 단계로 나눠 달라" 고 물을 때(클라이언트), AI 가 "구역별로 보여 줘" 를 제안할 때(서버).
+ * 세 곳이 각자 목록을 적으면 하나가 늘 때 나머지가 조용히 뒤처진다 — 집약 태그에서 이미 겪었다.
+ *
+ * 그래서 **한 곳**에 두고 셋이 가져다 쓴다. 이 파일은 import 가 없어 클라이언트 번들에 서버 코드를
+ * 끌고 들어가지 않는다.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TWIN_LEVELS = void 0;
+exports.isTwinLevel = isTwinLevel;
+exports.kpiGroupByOfLevel = kpiGroupByOfLevel;
+exports.isPerTargetLevel = isPerTargetLevel;
+/**
+ * 성과를 접을 수 있는 단계 — 좁은 것부터.
+ *
+ * `equipment` 는 커널 축 이름으로 `resource` 다(설비·인원·자산을 아우르는 이름). 화면과 AI 는
+ * "설비" 로 말하고, 커널에 물을 때만 축 이름으로 바꾼다 — 그 변환이 아래 한 곳에 있다.
+ */
+exports.TWIN_LEVELS = ['space', 'twin', 'area', 'location', 'equipment'];
+function isTwinLevel(v) {
+    return typeof v === 'string' && exports.TWIN_LEVELS.includes(v);
+}
+/**
+ * 단계 → 커널의 나누는 축(`KpiGroupBy`). **전체를 보는 단계는 축이 없다** — 나누지 않고 통째로 접는다.
+ *
+ * `space` 와 `twin` 이 축 없이 같은 이유: 둘의 차이는 "무엇을 대상으로 삼는가"(공간 전체 대 트윈 하나)이지
+ * "어떻게 나누는가" 가 아니다. 대상은 질의의 `spaceId`/`instanceId` 가 정한다.
+ */
+function kpiGroupByOfLevel(level) {
+    if (level === 'area')
+        return 'area';
+    if (level === 'location')
+        return 'location';
+    if (level === 'equipment')
+        return 'resource';
+    return undefined;
+}
+/**
+ * 그 단계의 카드가 **대상 하나마다 한 장**인가.
+ *
+ * 구역·자리·설비는 여럿이라 카드가 그 수만큼 생긴다. 공간·트윈은 하나뿐이다. 보드를 자동으로 조립할 때
+ * 몇 장이 생길지 미리 알아야 한다 — 자리 200개 × 지표 4개면 800장이다.
+ */
+function isPerTargetLevel(level) {
+    return kpiGroupByOfLevel(level) !== undefined;
+}
+//# sourceMappingURL=twin-level.js.map

package/dist-server/engine/twin-level.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"twin-level.js","sourceRoot":"","sources":["../../server/engine/twin-level.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAWH,kCAEC;AAQD,8CAMC;AAQD,4CAEC;AAnCD;;;;;GAKG;AACU,QAAA,WAAW,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,CAAU,CAAA;AAGtF,SAAgB,WAAW,CAAC,CAAU;IACpC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAK,mBAAiC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;AAChF,CAAC;AAED;;;;;GAKG;AACH,SAAgB,iBAAiB,CAAC,KAAgB;IAChD,IAAI,KAAK,KAAK,MAAM;QAAE,OAAO,MAAM,CAAA;IACnC,IAAI,KAAK,KAAK,UAAU;QAAE,OAAO,UAAU,CAAA;IAC3C,IAAI,KAAK,KAAK,WAAW;QAAE,OAAO,UAAU,CAAA;IAE5C,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;;;GAKG;AACH,SAAgB,gBAAgB,CAAC,KAAgB;IAC/C,OAAO,iBAAiB,CAAC,KAAK,CAAC,KAAK,SAAS,CAAA;AAC/C,CAAC","sourcesContent":["/*\n * 공간 계층의 **단계** — 성과를 어느 단위로 보는가. 순수(import 없음).\n *\n * ── 왜 여기 있나 ───────────────────────────────────────────────────────────\n * 이 목록을 세 곳이 쓴다: 씬 표현이 \"나는 어느 단계에 붙는다\" 고 선언할 때(클라이언트), 성과 카드가\n * \"이 단계로 나눠 달라\" 고 물을 때(클라이언트), AI 가 \"구역별로 보여 줘\" 를 제안할 때(서버).\n * 세 곳이 각자 목록을 적으면 하나가 늘 때 나머지가 조용히 뒤처진다 — 집약 태그에서 이미 겪었다.\n *\n * 그래서 **한 곳**에 두고 셋이 가져다 쓴다. 이 파일은 import 가 없어 클라이언트 번들에 서버 코드를\n * 끌고 들어가지 않는다.\n */\n\n/**\n * 성과를 접을 수 있는 단계 — 좁은 것부터.\n *\n * `equipment` 는 커널 축 이름으로 `resource` 다(설비·인원·자산을 아우르는 이름). 화면과 AI 는\n * \"설비\" 로 말하고, 커널에 물을 때만 축 이름으로 바꾼다 — 그 변환이 아래 한 곳에 있다.\n */\nexport const TWIN_LEVELS = ['space', 'twin', 'area', 'location', 'equipment'] as const\nexport type TwinLevel = (typeof TWIN_LEVELS)[number]\n\nexport function isTwinLevel(v: unknown): v is TwinLevel {\n  return typeof v === 'string' && (TWIN_LEVELS as readonly string[]).includes(v)\n}\n\n/**\n * 단계 → 커널의 나누는 축(`KpiGroupBy`). **전체를 보는 단계는 축이 없다** — 나누지 않고 통째로 접는다.\n *\n * `space` 와 `twin` 이 축 없이 같은 이유: 둘의 차이는 \"무엇을 대상으로 삼는가\"(공간 전체 대 트윈 하나)이지\n * \"어떻게 나누는가\" 가 아니다. 대상은 질의의 `spaceId`/`instanceId` 가 정한다.\n */\nexport function kpiGroupByOfLevel(level: TwinLevel): 'area' | 'location' | 'resource' | undefined {\n  if (level === 'area') return 'area'\n  if (level === 'location') return 'location'\n  if (level === 'equipment') return 'resource'\n\n  return undefined\n}\n\n/**\n * 그 단계의 카드가 **대상 하나마다 한 장**인가.\n *\n * 구역·자리·설비는 여럿이라 카드가 그 수만큼 생긴다. 공간·트윈은 하나뿐이다. 보드를 자동으로 조립할 때\n * 몇 장이 생길지 미리 알아야 한다 — 자리 200개 × 지표 4개면 800장이다.\n */\nexport function isPerTargetLevel(level: TwinLevel): boolean {\n  return kpiGroupByOfLevel(level) !== undefined\n}\n"]}

package/dist-server/engine/warm-start.d.ts

@@ -1,15 +1,42 @@
-/** 커널에 심을 관측 상태 — 구조가 아니라 "무엇이 어디에 얼마나". */
+/**
+ * 커널에 심을 관측 상태 — 구조가 아니라 "무엇이 어디에 얼마나".
+ *
+ * 커널 `hydrateObserved` 가 받는 스냅샷 모양을 그대로 따른다. 여기서 골라 담지 않는 이유: 무엇을
+ * 심을 수 있는지는 커널이 알고, 그 규칙(고아 작업 제외·이행 완료 오더 제외 등)도 커널에 있다.
+ * 호스트가 미리 골라내면 규칙이 두 곳으로 갈린다.
+ */
 export interface ObservedSeed {
     locations: unknown[];
     items: unknown[];
     equipment: unknown[];
+    persons?: unknown[];
+    assets?: unknown[];
+    tasks?: unknown[];
+    orders?: unknown[];
+    /** 확인해 둔 주목 신호 id — 상태에서 파생되지 않는 유일한 축이라 반드시 함께 넘긴다. */
+    acked?: string[];
 }
-export type WarmStartPlan = {
-    action: 'hydrate';
-    seed: ObservedSeed;
+/** 심은 것의 내역 — 로그와 테스트가 같은 숫자를 본다. */
+export interface WarmStartCounts {
     itemCount: number;
     equipmentCount: number;
+    personCount: number;
+    assetCount: number;
+    taskCount: number;
+    /** 원값(requested)이 있어 커널이 실제로 심을 수 있는 오더. */
+    orderCount: number;
+    /** 이어받은 확인 처리 수 — 잃으면 확인해 둔 신호가 다시 빨개진다. */
+    ackedCount: number;
+    /**
+     * 원값이 없어 심지 못하는 오더 — **0 이 아니면 반드시 말한다.**
+     * progress 만 있는 오더는 남은 수량을 알 수 없어 재계획의 근거가 되지 못한다. 지어내지 않고 뺀다.
+     */
+    ordersWithoutDemand: number;
 }
+export type WarmStartPlan = ({
+    action: 'hydrate';
+    seed: ObservedSeed;
+} & WarmStartCounts)
 /** 벤치 트윈 — 새 시작에서 용량을 재는 게 목적이라 현재 상태를 심으면 측정이 오염된다. */
  | {
     action: 'skip';
@@ -25,15 +52,34 @@ export type WarmStartPlan = {
     action: 'skip';
     reason: 'unsupported';
 };
+/** 스냅샷이 들고 올 수 있는 관측 축 — 어느 것이든 있으면 심을 값어치가 있다. */
+interface ObservedState {
+    locations?: unknown[];
+    items?: unknown[];
+    equipment?: unknown[];
+    persons?: unknown[];
+    assets?: unknown[];
+    tasks?: unknown[];
+    orders?: unknown[];
+    acked?: string[];
+}
+/**
+ * 봉투를 벗긴다 — **체크포인트가 겹포장돼 복원이 조용히 죽던 자리.**
+ *
+ * `TwinEngine.snapshot()` 은 라이브에서는 상태를, 시뮬에서는 `runtime.resync()` 봉투(`{revision,state}`)를
+ * 돌려준다. 그 봉투를 다시 `{revision, state}` 로 감싸 캐시에 넣었으므로, 꺼낸 `state` 는 축이 하나도
+ * 없는 껍데기였다 → `planWarmStart` 가 "심을 것이 없다" 로 판정하고 **조용히** 넘어갔다. 저널에 수천 건이
+ * 있고 캐시도 최신인데 트윈이 빈 채로 떴다(오류도 로그도 없다).
+ *
+ * 반환 모양을 통일하는 것이 뿌리 수정이지만, 그 값은 State 구독 페이로드로도 나가므로 클라이언트 계약을
+ * 건드린다. 그래서 **복원 경로에서만** 벗긴다. 겹겹이 싸여 있어도 벗긴다(과거에 저장된 값이 남아 있다).
+ */
+export declare function unwrapState(x: any, depth?: number): any;
 /**
  * 무엇을 할지 정한다.
  *
- * **오더는 의도적으로 심지 않는다.** 커널의 관측 주입은 오더에 requested/fulfilled/lines 를 요구하는데
- * 스냅샷의 오더에는 `progress` 밖에 없다. progress 에서 역산하면 없는 숫자를 지어내는 것이므로
- * 넘기지 않는다 — 재고·노드·무버만 복원되고 진행 중 오더는 비어서 시작하는 편이 정직하다.
+ * 오더·작업·사람·자산도 함께 심는다. 골라내는 규칙은 커널이 들고 있고(이행 완료 오더, 고아 작업),
+ * 여기서는 **심을 수 없는 오더의 수만 센다** — 호출부가 그 사실을 말할 수 있어야 하기 때문이다.
  */
-export declare function planWarmStart(state: {
-    locations?: unknown[];
-    items?: unknown[];
-    equipment?: unknown[];
-} | null | undefined, purpose: string | undefined, canHydrate: boolean): WarmStartPlan;
+export declare function planWarmStart(state: ObservedState | null | undefined, purpose: string | undefined, canHydrate: boolean): WarmStartPlan;
+export {};

package/dist-server/engine/warm-start.js

@@ -7,15 +7,54 @@
  * 이 판정이 틀리면 증상이 정반대 두 방향으로 나온다: 심어야 할 때 안 심으면 **있는 재고가 0 으로**
  * 보이고(2026-07-31 hatiolab-wms: 저널에 입고 540·출고 94 인데 재고 화면이 비어 있었다), 심지
  * 말아야 할 벤치에 심으면 **용량 측정이 오염된다.** 둘 다 조용히 틀리는 종류라 규칙을 고정한다.
+ *
+ * ── 오더를 버리던 전제가 낡았다 (2026-08-05) ────────────────────────────────
+ * 예전 주석은 "스냅샷의 오더에는 progress 밖에 없어서 역산하면 없는 숫자를 지어내는 셈이므로
+ * 넘기지 않는다" 였다. 그때는 맞았다. 그러나 커널 `OrderState` 가 **원값을 되찾은 뒤**
+ * (`requested`·`fulfilled`·`lines`) 이 판정만 그대로 남아, 재기동하면 재고는 맞는데 **진행 중
+ * 주문이 통째로 사라진** 화면이 나왔다. 오류는 나지 않는다 — 그래서 오래 남아 있었다.
+ *
+ * 두 스냅샷 생산 경로가 모두 원값을 담는다: 시뮬은 커널 `snapshot()`, 라이브(미러)는
+ * `StateProjector` 다. 사람·자산·작업도 같은 스냅샷에 있고 커널이 심을 수 있는데 넘기지 않고 있었다.
+ * 그래서 씨앗을 **관측 스냅샷 전체**로 넓힌다.
+ *
+ * 다만 넓히면서 **조용한 누락을 만들지 않는다.** 원값이 없는 오더는 커널이 걸러 내므로(지어내지
+ * 않는다), 그 수를 여기서 세어 호출부가 말할 수 있게 한다. 세지 않으면 "주문이 없다" 와 "주문을
+ * 못 심었다" 가 화면에서 같아진다.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.unwrapState = unwrapState;
 exports.planWarmStart = planWarmStart;
+/** 관측 상태가 실려 있는지 — 축 하나라도 있으면 상태다(봉투에는 없다). */
+const looksLikeState = (x) => !!x && typeof x === 'object' && ['locations', 'items', 'equipment', 'orders', 'tasks', 'persons', 'assets', 'acked'].some(k => k in x);
+/**
+ * 봉투를 벗긴다 — **체크포인트가 겹포장돼 복원이 조용히 죽던 자리.**
+ *
+ * `TwinEngine.snapshot()` 은 라이브에서는 상태를, 시뮬에서는 `runtime.resync()` 봉투(`{revision,state}`)를
+ * 돌려준다. 그 봉투를 다시 `{revision, state}` 로 감싸 캐시에 넣었으므로, 꺼낸 `state` 는 축이 하나도
+ * 없는 껍데기였다 → `planWarmStart` 가 "심을 것이 없다" 로 판정하고 **조용히** 넘어갔다. 저널에 수천 건이
+ * 있고 캐시도 최신인데 트윈이 빈 채로 떴다(오류도 로그도 없다).
+ *
+ * 반환 모양을 통일하는 것이 뿌리 수정이지만, 그 값은 State 구독 페이로드로도 나가므로 클라이언트 계약을
+ * 건드린다. 그래서 **복원 경로에서만** 벗긴다. 겹겹이 싸여 있어도 벗긴다(과거에 저장된 값이 남아 있다).
+ */
+function unwrapState(x, depth = 4) {
+    if (!x || typeof x !== 'object')
+        return x;
+    if (looksLikeState(x))
+        return x;
+    if (depth > 0 && x.state && typeof x.state === 'object')
+        return unwrapState(x.state, depth - 1);
+    return x;
+}
+const arr = (v) => (Array.isArray(v) ? v : []);
+/** 원값이 있는 오더인가 — 커널 `hydrateObserved` 의 판정(`requested !== undefined`)과 같은 기준. */
+const hasDemand = (o) => !!o && typeof o === 'object' && o.requested !== undefined;
 /**
  * 무엇을 할지 정한다.
  *
- * **오더는 의도적으로 심지 않는다.** 커널의 관측 주입은 오더에 requested/fulfilled/lines 를 요구하는데
- * 스냅샷의 오더에는 `progress` 밖에 없다. progress 에서 역산하면 없는 숫자를 지어내는 것이므로
- * 넘기지 않는다 — 재고·노드·무버만 복원되고 진행 중 오더는 비어서 시작하는 편이 정직하다.
+ * 오더·작업·사람·자산도 함께 심는다. 골라내는 규칙은 커널이 들고 있고(이행 완료 오더, 고아 작업),
+ * 여기서는 **심을 수 없는 오더의 수만 센다** — 호출부가 그 사실을 말할 수 있어야 하기 때문이다.
  */
 function planWarmStart(state, purpose, canHydrate) {
     /* 벤치 판정이 먼저다 — 상태가 있든 없든 벤치에는 심지 않는다는 사실이 바뀌지 않는다. */
@@ -23,15 +62,47 @@ function planWarmStart(state, purpose, canHydrate) {
         return { action: 'skip', reason: 'bench' };
     if (!state)
         return { action: 'skip', reason: 'no-state' };
-    const locations = state.locations ?? [];
-    const items = state.items ?? [];
-    const equipment = state.equipment ?? [];
-    /* 셋 다 비었으면 심을 것이 없다 — 빈 주입으로 로그만 남기지 않는다. */
-    if (locations.length === 0 && items.length === 0 && equipment.length === 0)
+    /* 봉투가 들어오면 스스로 벗는다 — 호출부가 한 곳이라도 잊으면 그 경로가 조용히 죽는다(실제로 그랬다). */
+    state = unwrapState(state);
+    const locations = arr(state.locations);
+    const items = arr(state.items);
+    const equipment = arr(state.equipment);
+    const persons = arr(state.persons);
+    const assets = arr(state.assets);
+    const tasks = arr(state.tasks);
+    const orders = arr(state.orders);
+    /* 확인 처리는 문자열 id 목록이다 — 배열이 아니면 없는 것으로 본다(지어내지 않는다). */
+    const acked = Array.isArray(state.acked) ? state.acked.filter((x) => typeof x === 'string') : [];
+    /* 어느 축도 없으면 심을 것이 없다 — 빈 주입으로 로그만 남기지 않는다. */
+    if (!locations.length && !items.length && !equipment.length && !persons.length && !assets.length && !tasks.length && !orders.length && !acked.length) {
         return { action: 'skip', reason: 'no-state' };
+    }
     /* 지원 여부는 마지막에 본다 — 심을 게 있는데 못 심는 상황이라야 경고할 값어치가 있다. */
     if (!canHydrate)
         return { action: 'skip', reason: 'unsupported' };
-    return { action: 'hydrate', seed: { locations, items, equipment }, itemCount: items.length, equipmentCount: equipment.length };
+    const seedable = orders.filter(hasDemand);
+    return {
+        action: 'hydrate',
+        seed: {
+            locations,
+            items,
+            equipment,
+            ...(persons.length ? { persons } : {}),
+            ...(assets.length ? { assets } : {}),
+            ...(tasks.length ? { tasks } : {}),
+            /* 원값 없는 오더는 넘기지 않는다 — 커널도 걸러 내지만, 넘기지 않으면 세어 둔 수와 어긋날 일이 없다. */
+            ...(seedable.length ? { orders: seedable } : {}),
+            /* 확인 처리는 조건이 사라진 id 가 섞여 있어도 해롭지 않다 — 그 신호가 없으면 표시할 대상이 없다. */
+            ...(acked.length ? { acked } : {})
+        },
+        itemCount: items.length,
+        equipmentCount: equipment.length,
+        personCount: persons.length,
+        assetCount: assets.length,
+        taskCount: tasks.length,
+        orderCount: seedable.length,
+        ordersWithoutDemand: orders.length - seedable.length,
+        ackedCount: acked.length
+    };
 }
 //# sourceMappingURL=warm-start.js.map

package/dist-server/engine/warm-start.js.map

@@ -1 +1 @@
-{"version":3,"file":"warm-start.js","sourceRoot":"","sources":["../../server/engine/warm-start.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AAyBH,sCAmBC;AA1BD;;;;;;GAMG;AACH,SAAgB,aAAa,CAC3B,KAA6F,EAC7F,OAA2B,EAC3B,UAAmB;IAEnB,sDAAsD;IACtD,IAAI,OAAO,KAAK,OAAO;QAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAA;IACnE,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,CAAA;IAEzD,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,IAAI,EAAE,CAAA;IACvC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,EAAE,CAAA;IAC/B,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,IAAI,EAAE,CAAA;IACvC,6CAA6C;IAC7C,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,CAAA;IAEzH,uDAAuD;IACvD,IAAI,CAAC,UAAU;QAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,CAAA;IAEjE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,SAAS,EAAE,KAAK,CAAC,MAAM,EAAE,cAAc,EAAE,SAAS,CAAC,MAAM,EAAE,CAAA;AAChI,CAAC","sourcesContent":["/*\n * 웜스타트 판정 — **순수**. \"기동하는 커널에 직전 상태를 심을 것인가, 심는다면 무엇을\" 만 정한다.\n * 실제 주입(hydrateObserved 호출)과 로그는 엔진이 한다.\n *\n * ── 왜 떼어냈나 ─────────────────────────────────────────────────────────────\n * 이 판정이 틀리면 증상이 정반대 두 방향으로 나온다: 심어야 할 때 안 심으면 **있는 재고가 0 으로**\n * 보이고(2026-07-31 hatiolab-wms: 저널에 입고 540·출고 94 인데 재고 화면이 비어 있었다), 심지\n * 말아야 할 벤치에 심으면 **용량 측정이 오염된다.** 둘 다 조용히 틀리는 종류라 규칙을 고정한다.\n */\n\n/** 커널에 심을 관측 상태 — 구조가 아니라 \"무엇이 어디에 얼마나\". */\nexport interface ObservedSeed {\n  locations: unknown[]\n  items: unknown[]\n  equipment: unknown[]\n}\n\nexport type WarmStartPlan =\n  | { action: 'hydrate'; seed: ObservedSeed; itemCount: number; equipmentCount: number }\n  /** 벤치 트윈 — 새 시작에서 용량을 재는 게 목적이라 현재 상태를 심으면 측정이 오염된다. */\n  | { action: 'skip'; reason: 'bench' }\n  /** 심을 상태가 없다 — 처음 만든 트윈이거나 저널·체크포인트가 비었다. 정상이다. */\n  | { action: 'skip'; reason: 'no-state' }\n  /** 커널이 관측 주입을 지원하지 않는다 — 구조만으로 시작하므로 보유량은 0 으로 읽힌다(알려야 한다). */\n  | { action: 'skip'; reason: 'unsupported' }\n\n/**\n * 무엇을 할지 정한다.\n *\n * **오더는 의도적으로 심지 않는다.** 커널의 관측 주입은 오더에 requested/fulfilled/lines 를 요구하는데\n * 스냅샷의 오더에는 `progress` 밖에 없다. progress 에서 역산하면 없는 숫자를 지어내는 것이므로\n * 넘기지 않는다 — 재고·노드·무버만 복원되고 진행 중 오더는 비어서 시작하는 편이 정직하다.\n */\nexport function planWarmStart(\n  state: { locations?: unknown[]; items?: unknown[]; equipment?: unknown[] } | null | undefined,\n  purpose: string | undefined,\n  canHydrate: boolean\n): WarmStartPlan {\n  /* 벤치 판정이 먼저다 — 상태가 있든 없든 벤치에는 심지 않는다는 사실이 바뀌지 않는다. */\n  if (purpose === 'bench') return { action: 'skip', reason: 'bench' }\n  if (!state) return { action: 'skip', reason: 'no-state' }\n\n  const locations = state.locations ?? []\n  const items = state.items ?? []\n  const equipment = state.equipment ?? []\n  /* 셋 다 비었으면 심을 것이 없다 — 빈 주입으로 로그만 남기지 않는다. */\n  if (locations.length === 0 && items.length === 0 && equipment.length === 0) return { action: 'skip', reason: 'no-state' }\n\n  /* 지원 여부는 마지막에 본다 — 심을 게 있는데 못 심는 상황이라야 경고할 값어치가 있다. */\n  if (!canHydrate) return { action: 'skip', reason: 'unsupported' }\n\n  return { action: 'hydrate', seed: { locations, items, equipment }, itemCount: items.length, equipmentCount: equipment.length }\n}\n"]}
+{"version":3,"file":"warm-start.js","sourceRoot":"","sources":["../../server/engine/warm-start.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * 웜스타트 판정 — **순수**. \"기동하는 커널에 직전 상태를 심을 것인가, 심는다면 무엇을\" 만 정한다.\n * 실제 주입(hydrateObserved 호출)과 로그는 엔진이 한다.\n *\n * ── 왜 떼어냈나 ─────────────────────────────────────────────────────────────\n * 이 판정이 틀리면 증상이 정반대 두 방향으로 나온다: 심어야 할 때 안 심으면 **있는 재고가 0 으로**\n * 보이고(2026-07-31 hatiolab-wms: 저널에 입고 540·출고 94 인데 재고 화면이 비어 있었다), 심지\n * 말아야 할 벤치에 심으면 **용량 측정이 오염된다.** 둘 다 조용히 틀리는 종류라 규칙을 고정한다.\n *\n * ── 오더를 버리던 전제가 낡았다 (2026-08-05) ────────────────────────────────\n * 예전 주석은 \"스냅샷의 오더에는 progress 밖에 없어서 역산하면 없는 숫자를 지어내는 셈이므로\n * 넘기지 않는다\" 였다. 그때는 맞았다. 그러나 커널 `OrderState` 가 **원값을 되찾은 뒤**\n * (`requested`·`fulfilled`·`lines`) 이 판정만 그대로 남아, 재기동하면 재고는 맞는데 **진행 중\n * 주문이 통째로 사라진** 화면이 나왔다. 오류는 나지 않는다 — 그래서 오래 남아 있었다.\n *\n * 두 스냅샷 생산 경로가 모두 원값을 담는다: 시뮬은 커널 `snapshot()`, 라이브(미러)는\n * `StateProjector` 다. 사람·자산·작업도 같은 스냅샷에 있고 커널이 심을 수 있는데 넘기지 않고 있었다.\n * 그래서 씨앗을 **관측 스냅샷 전체**로 넓힌다.\n *\n * 다만 넓히면서 **조용한 누락을 만들지 않는다.** 원값이 없는 오더는 커널이 걸러 내므로(지어내지\n * 않는다), 그 수를 여기서 세어 호출부가 말할 수 있게 한다. 세지 않으면 \"주문이 없다\" 와 \"주문을\n * 못 심었다\" 가 화면에서 같아진다.\n */\n\n/**\n * 커널에 심을 관측 상태 — 구조가 아니라 \"무엇이 어디에 얼마나\".\n *\n * 커널 `hydrateObserved` 가 받는 스냅샷 모양을 그대로 따른다. 여기서 골라 담지 않는 이유: 무엇을\n * 심을 수 있는지는 커널이 알고, 그 규칙(고아 작업 제외·이행 완료 오더 제외 등)도 커널에 있다.\n * 호스트가 미리 골라내면 규칙이 두 곳으로 갈린다.\n */\nexport interface ObservedSeed {\n  locations: unknown[]\n  items: unknown[]\n  equipment: unknown[]\n  persons?: unknown[]\n  assets?: unknown[]\n  tasks?: unknown[]\n  orders?: unknown[]\n  /** 확인해 둔 주목 신호 id — 상태에서 파생되지 않는 유일한 축이라 반드시 함께 넘긴다. */\n  acked?: string[]\n}\n\n/** 심은 것의 내역 — 로그와 테스트가 같은 숫자를 본다. */\nexport interface WarmStartCounts {\n  itemCount: number\n  equipmentCount: number\n  personCount: number\n  assetCount: number\n  taskCount: number\n  /** 원값(requested)이 있어 커널이 실제로 심을 수 있는 오더. */\n  orderCount: number\n  /** 이어받은 확인 처리 수 — 잃으면 확인해 둔 신호가 다시 빨개진다. */\n  ackedCount: number\n  /**\n   * 원값이 없어 심지 못하는 오더 — **0 이 아니면 반드시 말한다.**\n   * progress 만 있는 오더는 남은 수량을 알 수 없어 재계획의 근거가 되지 못한다. 지어내지 않고 뺀다.\n   */\n  ordersWithoutDemand: number\n}\n\nexport type WarmStartPlan =\n  | ({ action: 'hydrate'; seed: ObservedSeed } & WarmStartCounts)\n  /** 벤치 트윈 — 새 시작에서 용량을 재는 게 목적이라 현재 상태를 심으면 측정이 오염된다. */\n  | { action: 'skip'; reason: 'bench' }\n  /** 심을 상태가 없다 — 처음 만든 트윈이거나 저널·체크포인트가 비었다. 정상이다. */\n  | { action: 'skip'; reason: 'no-state' }\n  /** 커널이 관측 주입을 지원하지 않는다 — 구조만으로 시작하므로 보유량은 0 으로 읽힌다(알려야 한다). */\n  | { action: 'skip'; reason: 'unsupported' }\n\n/** 스냅샷이 들고 올 수 있는 관측 축 — 어느 것이든 있으면 심을 값어치가 있다. */\ninterface ObservedState {\n  locations?: unknown[]\n  items?: unknown[]\n  equipment?: unknown[]\n  persons?: unknown[]\n  assets?: unknown[]\n  tasks?: unknown[]\n  orders?: unknown[]\n  acked?: string[]\n}\n\n/** 관측 상태가 실려 있는지 — 축 하나라도 있으면 상태다(봉투에는 없다). */\nconst looksLikeState = (x: any): boolean =>\n  !!x && typeof x === 'object' && ['locations', 'items', 'equipment', 'orders', 'tasks', 'persons', 'assets', 'acked'].some(k => k in x)\n\n/**\n * 봉투를 벗긴다 — **체크포인트가 겹포장돼 복원이 조용히 죽던 자리.**\n *\n * `TwinEngine.snapshot()` 은 라이브에서는 상태를, 시뮬에서는 `runtime.resync()` 봉투(`{revision,state}`)를\n * 돌려준다. 그 봉투를 다시 `{revision, state}` 로 감싸 캐시에 넣었으므로, 꺼낸 `state` 는 축이 하나도\n * 없는 껍데기였다 → `planWarmStart` 가 \"심을 것이 없다\" 로 판정하고 **조용히** 넘어갔다. 저널에 수천 건이\n * 있고 캐시도 최신인데 트윈이 빈 채로 떴다(오류도 로그도 없다).\n *\n * 반환 모양을 통일하는 것이 뿌리 수정이지만, 그 값은 State 구독 페이로드로도 나가므로 클라이언트 계약을\n * 건드린다. 그래서 **복원 경로에서만** 벗긴다. 겹겹이 싸여 있어도 벗긴다(과거에 저장된 값이 남아 있다).\n */\nexport function unwrapState(x: any, depth = 4): any {\n  if (!x || typeof x !== 'object') return x\n  if (looksLikeState(x)) return x\n  if (depth > 0 && x.state && typeof x.state === 'object') return unwrapState(x.state, depth - 1)\n  return x\n}\n\nconst arr = (v: unknown[] | undefined): unknown[] => (Array.isArray(v) ? v : [])\n\n/** 원값이 있는 오더인가 — 커널 `hydrateObserved` 의 판정(`requested !== undefined`)과 같은 기준. */\nconst hasDemand = (o: unknown): boolean =>\n  !!o && typeof o === 'object' && (o as { requested?: unknown }).requested !== undefined\n\n/**\n * 무엇을 할지 정한다.\n *\n * 오더·작업·사람·자산도 함께 심는다. 골라내는 규칙은 커널이 들고 있고(이행 완료 오더, 고아 작업),\n * 여기서는 **심을 수 없는 오더의 수만 센다** — 호출부가 그 사실을 말할 수 있어야 하기 때문이다.\n */\nexport function planWarmStart(state: ObservedState | null | undefined, purpose: string | undefined, canHydrate: boolean): WarmStartPlan {\n  /* 벤치 판정이 먼저다 — 상태가 있든 없든 벤치에는 심지 않는다는 사실이 바뀌지 않는다. */\n  if (purpose === 'bench') return { action: 'skip', reason: 'bench' }\n  if (!state) return { action: 'skip', reason: 'no-state' }\n  /* 봉투가 들어오면 스스로 벗는다 — 호출부가 한 곳이라도 잊으면 그 경로가 조용히 죽는다(실제로 그랬다). */\n  state = unwrapState(state)\n\n  const locations = arr(state.locations)\n  const items = arr(state.items)\n  const equipment = arr(state.equipment)\n  const persons = arr(state.persons)\n  const assets = arr(state.assets)\n  const tasks = arr(state.tasks)\n  const orders = arr(state.orders)\n  /* 확인 처리는 문자열 id 목록이다 — 배열이 아니면 없는 것으로 본다(지어내지 않는다). */\n  const acked = Array.isArray(state.acked) ? state.acked.filter((x): x is string => typeof x === 'string') : []\n\n  /* 어느 축도 없으면 심을 것이 없다 — 빈 주입으로 로그만 남기지 않는다. */\n  if (!locations.length && !items.length && !equipment.length && !persons.length && !assets.length && !tasks.length && !orders.length && !acked.length) {\n    return { action: 'skip', reason: 'no-state' }\n  }\n\n  /* 지원 여부는 마지막에 본다 — 심을 게 있는데 못 심는 상황이라야 경고할 값어치가 있다. */\n  if (!canHydrate) return { action: 'skip', reason: 'unsupported' }\n\n  const seedable = orders.filter(hasDemand)\n\n  return {\n    action: 'hydrate',\n    seed: {\n      locations,\n      items,\n      equipment,\n      ...(persons.length ? { persons } : {}),\n      ...(assets.length ? { assets } : {}),\n      ...(tasks.length ? { tasks } : {}),\n      /* 원값 없는 오더는 넘기지 않는다 — 커널도 걸러 내지만, 넘기지 않으면 세어 둔 수와 어긋날 일이 없다. */\n      ...(seedable.length ? { orders: seedable } : {}),\n      /* 확인 처리는 조건이 사라진 id 가 섞여 있어도 해롭지 않다 — 그 신호가 없으면 표시할 대상이 없다. */\n      ...(acked.length ? { acked } : {})\n    },\n    itemCount: items.length,\n    equipmentCount: equipment.length,\n    personCount: persons.length,\n    assetCount: assets.length,\n    taskCount: tasks.length,\n    orderCount: seedable.length,\n    ordersWithoutDemand: orders.length - seedable.length,\n    ackedCount: acked.length\n  }\n}\n"]}

package/dist-server/service/reference/discovery-result.d.ts

@@ -0,0 +1,34 @@
+/** 발견이 왜 아무것도 주지 못했나 — 언어 중립 코드. */
+export type DiscoveryErrorCode = 'reference-not-found' | 'adapter-unknown' | 'discovery-failed' | 'discovery-timeout';
+export interface DiscoveryError {
+    code: DiscoveryErrorCode;
+    params?: Record<string, string | number>;
+    /** 영어 canonical — 로그에 남고, 번역이 없으면 그대로 보인다. */
+    message: string;
+}
+export interface DiscoveryResult<S = unknown> {
+    /** 발견된 사이트들. 실패했으면 빈 배열이고 `error` 가 이유를 말한다. */
+    sites: S[];
+    /** 실패 사유. **없으면 성공이다** — 빈 배열 + 사유 없음 = "연결은 됐지만 사이트가 없다". */
+    error?: DiscoveryError;
+}
+/** 등록된 레퍼런스가 없다 — 목록이 낡았거나 다른 테넌트의 것이다. */
+export declare const referenceNotFound: (source: string) => DiscoveryError;
+/** 어댑터 종류를 모른다 — 배포에 그 커넥터가 없다(패키지 미설치·오타). */
+export declare const adapterUnknown: (adapterType: string, source: string) => DiscoveryError;
+/** 연결·조회가 실패했다 — 원 시스템이 준 사유를 그대로 싣는다. */
+export declare const discoveryFailed: (source: string, detail: string) => DiscoveryError;
+/** 기다려도 답이 없었다 — 무한히 도는 화면보다 사유가 낫다. */
+export declare const discoveryTimedOut: (source: string, seconds: number) => DiscoveryError;
+/**
+ * 어댑터가 준 것을 결과로 접는다.
+ *
+ * **사이트가 없는 것을 실패로 만들지 않는다** — 연결이 되고 조회가 성공했는데 공장이 하나도 없는
+ * 시스템은 있을 수 있다(권한이 좁거나 아직 등록되지 않은 경우). 그것은 사실이고, 화면은 "없다" 고
+ * 말해야 한다. 실패로 뭉개면 사용자가 있지도 않은 문제를 찾는다.
+ */
+export declare function discovered<S>(sites: readonly S[] | undefined | null): DiscoveryResult<S>;
+/** 실패를 결과로 접는다 — 사이트는 비어 있다(반쪽 목록을 성공처럼 보이게 하지 않는다). */
+export declare function failed<S>(error: DiscoveryError): DiscoveryResult<S>;
+/** 어댑터가 던진 것에서 사람이 읽을 사유를 뽑는다 — 형태를 가정하지 않는다. */
+export declare function detailOf(e: unknown): string;

package/dist-server/service/reference/discovery-result.js

@@ -0,0 +1,84 @@
+"use strict";
+/*
+ * 사이트 발견 결과 — **"못 찾았다" 와 "없다" 를 가른다.** 순수.
+ *
+ * ── 왜 있나 (2026-08-06) ────────────────────────────────────────────────────
+ * 실 시스템을 연결해 "거기 있는 것" 으로 트윈을 만드는 경로에서, 발견이 실패하면 화면이
+ * **"사이트를 찾지 못했습니다"** 라고만 말했다. 네 가지가 그 한 문장으로 접혀 있었다.
+ *
+ *  ① 그 레퍼런스가 등록돼 있지 않다        (`!ref → []`)
+ *  ② 어댑터 종류를 모른다                  (`!adapter → []`)
+ *  ③ 연결·조회가 실패했다                  (`catch { return [] }`)
+ *  ④ 정말로 사이트가 없다                  (빈 배열)
+ *
+ * ①②③ 은 **고칠 수 있는 문제**이고 ④ 는 사실이다. 그런데 화면이 같은 말을 하므로 사용자는 자격이
+ * 틀렸는지, 주소가 틀렸는지, 정말 공장이 없는지 알 수 없다 — 실 시스템 연결에서 가장 자주 막히는
+ * 자리인데 거기서 아무 단서도 주지 않았다.
+ *
+ * ── 왜 문장이 아니라 코드인가 ───────────────────────────────────────────────
+ * 이 프로젝트가 이미 쓰는 규약을 따른다(주의 신호·커맨드 거절·인제스트 경고와 같은 모양):
+ * `code`(언어 중립) + `params`(문장에 끼울 값) + `message`(영어 canonical, 로그·폴백).
+ * 화면은 `twin.connect.discover.<code>` 로 사람 말을 만든다.
+ *
+ * ── 원 시스템의 오류 문장을 감추지 않는다 ────────────────────────────────────
+ * 어댑터가 준 사유(자격 거부·타임아웃·404)는 **그 시스템만 아는 사실**이라 우리가 다시 쓸 수 없다.
+ * `detail` 로 그대로 실어 보내 화면이 보조 문장으로 보인다 — 원문이 있으면 사용자가 자기 관리자에게
+ * 물어볼 수 있고, 없으면 우리 짐작만 남는다.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discoveryTimedOut = exports.discoveryFailed = exports.adapterUnknown = exports.referenceNotFound = void 0;
+exports.discovered = discovered;
+exports.failed = failed;
+exports.detailOf = detailOf;
+/** 등록된 레퍼런스가 없다 — 목록이 낡았거나 다른 테넌트의 것이다. */
+const referenceNotFound = (source) => ({
+    code: 'reference-not-found',
+    params: { source },
+    message: `reference "${source}" is not registered in this tenant`
+});
+exports.referenceNotFound = referenceNotFound;
+/** 어댑터 종류를 모른다 — 배포에 그 커넥터가 없다(패키지 미설치·오타). */
+const adapterUnknown = (adapterType, source) => ({
+    code: 'adapter-unknown',
+    params: { adapterType, source },
+    message: `no connector of type "${adapterType}" is available for reference "${source}"`
+});
+exports.adapterUnknown = adapterUnknown;
+/** 연결·조회가 실패했다 — 원 시스템이 준 사유를 그대로 싣는다. */
+const discoveryFailed = (source, detail) => ({
+    code: 'discovery-failed',
+    params: { source, detail },
+    message: `could not read sites from "${source}": ${detail}`
+});
+exports.discoveryFailed = discoveryFailed;
+/** 기다려도 답이 없었다 — 무한히 도는 화면보다 사유가 낫다. */
+const discoveryTimedOut = (source, seconds) => ({
+    code: 'discovery-timeout',
+    params: { source, seconds },
+    message: `"${source}" did not answer within ${seconds}s`
+});
+exports.discoveryTimedOut = discoveryTimedOut;
+/**
+ * 어댑터가 준 것을 결과로 접는다.
+ *
+ * **사이트가 없는 것을 실패로 만들지 않는다** — 연결이 되고 조회가 성공했는데 공장이 하나도 없는
+ * 시스템은 있을 수 있다(권한이 좁거나 아직 등록되지 않은 경우). 그것은 사실이고, 화면은 "없다" 고
+ * 말해야 한다. 실패로 뭉개면 사용자가 있지도 않은 문제를 찾는다.
+ */
+function discovered(sites) {
+    return { sites: Array.isArray(sites) ? [...sites] : [] };
+}
+/** 실패를 결과로 접는다 — 사이트는 비어 있다(반쪽 목록을 성공처럼 보이게 하지 않는다). */
+function failed(error) {
+    return { sites: [], error };
+}
+/** 어댑터가 던진 것에서 사람이 읽을 사유를 뽑는다 — 형태를 가정하지 않는다. */
+function detailOf(e) {
+    if (e instanceof Error && e.message)
+        return e.message;
+    if (typeof e === 'string' && e)
+        return e;
+    /* 무엇이 왔는지 모르면 그렇게 말한다 — 빈 문장으로 "이유 없음" 처럼 보이게 하지 않는다. */
+    return 'the connector failed without a message';
+}
+//# sourceMappingURL=discovery-result.js.map

package/dist-server/service/reference/discovery-result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery-result.js","sourceRoot":"","sources":["../../../server/service/reference/discovery-result.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;;;AAsDH,gCAEC;AAGD,wBAEC;AAGD,4BAKC;AAlDD,2CAA2C;AACpC,MAAM,iBAAiB,GAAG,CAAC,MAAc,EAAkB,EAAE,CAAC,CAAC;IACpE,IAAI,EAAE,qBAAqB;IAC3B,MAAM,EAAE,EAAE,MAAM,EAAE;IAClB,OAAO,EAAE,cAAc,MAAM,oCAAoC;CAClE,CAAC,CAAA;AAJW,QAAA,iBAAiB,qBAI5B;AAEF,+CAA+C;AACxC,MAAM,cAAc,GAAG,CAAC,WAAmB,EAAE,MAAc,EAAkB,EAAE,CAAC,CAAC;IACtF,IAAI,EAAE,iBAAiB;IACvB,MAAM,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE;IAC/B,OAAO,EAAE,yBAAyB,WAAW,iCAAiC,MAAM,GAAG;CACxF,CAAC,CAAA;AAJW,QAAA,cAAc,kBAIzB;AAEF,0CAA0C;AACnC,MAAM,eAAe,GAAG,CAAC,MAAc,EAAE,MAAc,EAAkB,EAAE,CAAC,CAAC;IAClF,IAAI,EAAE,kBAAkB;IACxB,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE;IAC1B,OAAO,EAAE,8BAA8B,MAAM,MAAM,MAAM,EAAE;CAC5D,CAAC,CAAA;AAJW,QAAA,eAAe,mBAI1B;AAEF,wCAAwC;AACjC,MAAM,iBAAiB,GAAG,CAAC,MAAc,EAAE,OAAe,EAAkB,EAAE,CAAC,CAAC;IACrF,IAAI,EAAE,mBAAmB;IACzB,MAAM,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE;IAC3B,OAAO,EAAE,IAAI,MAAM,2BAA2B,OAAO,GAAG;CACzD,CAAC,CAAA;AAJW,QAAA,iBAAiB,qBAI5B;AAEF;;;;;;GAMG;AACH,SAAgB,UAAU,CAAI,KAAsC;IAClE,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAA;AAC1D,CAAC;AAED,wDAAwD;AACxD,SAAgB,MAAM,CAAI,KAAqB;IAC7C,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,CAAA;AAC7B,CAAC;AAED,iDAAiD;AACjD,SAAgB,QAAQ,CAAC,CAAU;IACjC,IAAI,CAAC,YAAY,KAAK,IAAI,CAAC,CAAC,OAAO;QAAE,OAAO,CAAC,CAAC,OAAO,CAAA;IACrD,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC;QAAE,OAAO,CAAC,CAAA;IACxC,yDAAyD;IACzD,OAAO,wCAAwC,CAAA;AACjD,CAAC","sourcesContent":["/*\n * 사이트 발견 결과 — **\"못 찾았다\" 와 \"없다\" 를 가른다.** 순수.\n *\n * ── 왜 있나 (2026-08-06) ────────────────────────────────────────────────────\n * 실 시스템을 연결해 \"거기 있는 것\" 으로 트윈을 만드는 경로에서, 발견이 실패하면 화면이\n * **\"사이트를 찾지 못했습니다\"** 라고만 말했다. 네 가지가 그 한 문장으로 접혀 있었다.\n *\n *  ① 그 레퍼런스가 등록돼 있지 않다        (`!ref → []`)\n *  ② 어댑터 종류를 모른다                  (`!adapter → []`)\n *  ③ 연결·조회가 실패했다                  (`catch { return [] }`)\n *  ④ 정말로 사이트가 없다                  (빈 배열)\n *\n * ①②③ 은 **고칠 수 있는 문제**이고 ④ 는 사실이다. 그런데 화면이 같은 말을 하므로 사용자는 자격이\n * 틀렸는지, 주소가 틀렸는지, 정말 공장이 없는지 알 수 없다 — 실 시스템 연결에서 가장 자주 막히는\n * 자리인데 거기서 아무 단서도 주지 않았다.\n *\n * ── 왜 문장이 아니라 코드인가 ───────────────────────────────────────────────\n * 이 프로젝트가 이미 쓰는 규약을 따른다(주의 신호·커맨드 거절·인제스트 경고와 같은 모양):\n * `code`(언어 중립) + `params`(문장에 끼울 값) + `message`(영어 canonical, 로그·폴백).\n * 화면은 `twin.connect.discover.<code>` 로 사람 말을 만든다.\n *\n * ── 원 시스템의 오류 문장을 감추지 않는다 ────────────────────────────────────\n * 어댑터가 준 사유(자격 거부·타임아웃·404)는 **그 시스템만 아는 사실**이라 우리가 다시 쓸 수 없다.\n * `detail` 로 그대로 실어 보내 화면이 보조 문장으로 보인다 — 원문이 있으면 사용자가 자기 관리자에게\n * 물어볼 수 있고, 없으면 우리 짐작만 남는다.\n */\n\n/** 발견이 왜 아무것도 주지 못했나 — 언어 중립 코드. */\nexport type DiscoveryErrorCode = 'reference-not-found' | 'adapter-unknown' | 'discovery-failed' | 'discovery-timeout'\n\nexport interface DiscoveryError {\n  code: DiscoveryErrorCode\n  params?: Record<string, string | number>\n  /** 영어 canonical — 로그에 남고, 번역이 없으면 그대로 보인다. */\n  message: string\n}\n\nexport interface DiscoveryResult<S = unknown> {\n  /** 발견된 사이트들. 실패했으면 빈 배열이고 `error` 가 이유를 말한다. */\n  sites: S[]\n  /** 실패 사유. **없으면 성공이다** — 빈 배열 + 사유 없음 = \"연결은 됐지만 사이트가 없다\". */\n  error?: DiscoveryError\n}\n\n/** 등록된 레퍼런스가 없다 — 목록이 낡았거나 다른 테넌트의 것이다. */\nexport const referenceNotFound = (source: string): DiscoveryError => ({\n  code: 'reference-not-found',\n  params: { source },\n  message: `reference \"${source}\" is not registered in this tenant`\n})\n\n/** 어댑터 종류를 모른다 — 배포에 그 커넥터가 없다(패키지 미설치·오타). */\nexport const adapterUnknown = (adapterType: string, source: string): DiscoveryError => ({\n  code: 'adapter-unknown',\n  params: { adapterType, source },\n  message: `no connector of type \"${adapterType}\" is available for reference \"${source}\"`\n})\n\n/** 연결·조회가 실패했다 — 원 시스템이 준 사유를 그대로 싣는다. */\nexport const discoveryFailed = (source: string, detail: string): DiscoveryError => ({\n  code: 'discovery-failed',\n  params: { source, detail },\n  message: `could not read sites from \"${source}\": ${detail}`\n})\n\n/** 기다려도 답이 없었다 — 무한히 도는 화면보다 사유가 낫다. */\nexport const discoveryTimedOut = (source: string, seconds: number): DiscoveryError => ({\n  code: 'discovery-timeout',\n  params: { source, seconds },\n  message: `\"${source}\" did not answer within ${seconds}s`\n})\n\n/**\n * 어댑터가 준 것을 결과로 접는다.\n *\n * **사이트가 없는 것을 실패로 만들지 않는다** — 연결이 되고 조회가 성공했는데 공장이 하나도 없는\n * 시스템은 있을 수 있다(권한이 좁거나 아직 등록되지 않은 경우). 그것은 사실이고, 화면은 \"없다\" 고\n * 말해야 한다. 실패로 뭉개면 사용자가 있지도 않은 문제를 찾는다.\n */\nexport function discovered<S>(sites: readonly S[] | undefined | null): DiscoveryResult<S> {\n  return { sites: Array.isArray(sites) ? [...sites] : [] }\n}\n\n/** 실패를 결과로 접는다 — 사이트는 비어 있다(반쪽 목록을 성공처럼 보이게 하지 않는다). */\nexport function failed<S>(error: DiscoveryError): DiscoveryResult<S> {\n  return { sites: [], error }\n}\n\n/** 어댑터가 던진 것에서 사람이 읽을 사유를 뽑는다 — 형태를 가정하지 않는다. */\nexport function detailOf(e: unknown): string {\n  if (e instanceof Error && e.message) return e.message\n  if (typeof e === 'string' && e) return e\n  /* 무엇이 왔는지 모르면 그렇게 말한다 — 빈 문장으로 \"이유 없음\" 처럼 보이게 하지 않는다. */\n  return 'the connector failed without a message'\n}\n"]}

package/dist-server/service/reference/ingest-space.d.ts

@@ -0,0 +1,30 @@
+/** 공간 판정 결과. */
+export interface IngestSpaceChoice {
+    /** 실제로 쓸 공간 id. */
+    spaceId: string;
+    /** 사용자가 기존 현장에 합치기를 골랐나(마스터가 파생한 공간과 다른 곳으로 들어가나). */
+    joined: boolean;
+}
+/** 거절 사유 — 호출측이 문장을 만들 때 쓴다(언어 중립 코드). */
+export declare const INGEST_SPACE_NOT_FOUND = "space-not-found";
+/**
+ * 요청받은 공간과 마스터가 파생한 공간 중 무엇으로 들어갈지 정한다.
+ *
+ * @param masterSpaceId 마스터에서 파생된 공간 id(요청이 없을 때의 기본).
+ * @param requested     사용자가 고른 기존 공간 id. 없으면 빈 값/undefined.
+ * @param requestedExists 그 공간이 이 테넌트에 실제로 있나(호출측이 조회해 넘긴다).
+ * @throws 요청한 공간이 없으면 — 조용히 새로 만들지 않는다.
+ */
+export declare function resolveIngestSpace(masterSpaceId: string, requested: string | undefined | null, requestedExists: boolean): IngestSpaceChoice;
+/** 구역·랜드마크처럼 id 로 합쳐지는 것들. */
+interface Identified {
+    id?: string;
+}
+/**
+ * 합치는 쪽과 기존 쪽이 같은 id 를 쓰는 것들을 찾아 경고 문장을 만든다.
+ *
+ * 정당한 경우(같은 현장의 같은 구역)와 사고(서로 다른 구역이 우연히 같은 이름)를 기계가 가릴 수는
+ * 없다. 가릴 수 없는 것을 고르지 않고, **무엇이 합쳐졌는지 말한다.**
+ */
+export declare function collidingIds(existing: readonly Identified[] | undefined | null, incoming: readonly Identified[] | undefined | null): string[];
+export {};

package/dist-server/service/reference/ingest-space.js

@@ -0,0 +1,63 @@
+"use strict";
+/*
+ * 인제스트가 어느 공간으로 들어갈지 정한다 — **순수**.
+ *
+ * ── 왜 있나 (2026-08-05) ────────────────────────────────────────────────────
+ * 한 현실(공장·물류센터)을 여러 렌즈가 비춘다: 창고(WMS)·공정(MES)·야드(YMS) 가 같은 부지에 있다.
+ * 엔진은 이미 그것을 지원한다 — 같은 `spaceId` 로 들어오면 공간 content 를 병합하고 기존 값을 이긴다.
+ *
+ * 그런데 **만드는 흐름에 그 선택이 없었다.** 템플릿은 `space.spaceId` 를 정하지 않으므로 항상
+ * `<source>-site` 로 파생돼, 새 트윈은 늘 새 현장처럼 생겼다. 데이터로는 가능한 일이 저작으로는
+ * 불가능했다.
+ *
+ * ── 없는 공간에 조용히 새 공간을 만들지 않는다 ────────────────────────────────
+ * "이 현장에 더한다" 는 요청이 오타·낡은 목록으로 빗나갔을 때 새 공간을 만들어 주면, 사용자는
+ * 합쳤다고 믿고 화면에서는 따로 놀게 된다 — 나중에 두 현장을 손으로 합쳐야 하고, 그때는 이미
+ * 이벤트가 양쪽에 쌓여 있다. 그래서 **모르는 공간이면 거절한다.**
+ *
+ * ── 같은 id 를 쓰는 구역은 조용히 합쳐지므로 알린다 ──────────────────────────
+ * 공간 content 의 구역·랜드마크는 id 로 합집합을 만든다(`unionById`). 두 렌즈가 우연히 같은 구역
+ * id(`a-yard` 따위)를 쓰면 서로 다른 구역이 하나로 접힌다. 막을 일은 아니다(같은 현장의 같은 구역을
+ * 가리키는 정당한 경우가 많다) — 다만 **모르고 지나가지 않게** 경고로 돌려준다.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INGEST_SPACE_NOT_FOUND = void 0;
+exports.resolveIngestSpace = resolveIngestSpace;
+exports.collidingIds = collidingIds;
+/** 거절 사유 — 호출측이 문장을 만들 때 쓴다(언어 중립 코드). */
+exports.INGEST_SPACE_NOT_FOUND = 'space-not-found';
+/**
+ * 요청받은 공간과 마스터가 파생한 공간 중 무엇으로 들어갈지 정한다.
+ *
+ * @param masterSpaceId 마스터에서 파생된 공간 id(요청이 없을 때의 기본).
+ * @param requested     사용자가 고른 기존 공간 id. 없으면 빈 값/undefined.
+ * @param requestedExists 그 공간이 이 테넌트에 실제로 있나(호출측이 조회해 넘긴다).
+ * @throws 요청한 공간이 없으면 — 조용히 새로 만들지 않는다.
+ */
+function resolveIngestSpace(masterSpaceId, requested, requestedExists) {
+    const want = (requested ?? '').trim();
+    if (!want)
+        return { spaceId: masterSpaceId, joined: false };
+    if (!requestedExists) {
+        const e = new Error(`space "${want}" not found — cannot co-locate into a space that does not exist`);
+        e.code = exports.INGEST_SPACE_NOT_FOUND;
+        throw e;
+    }
+    /* 마스터가 이미 그 공간을 가리키면 합치기가 아니다 — 같은 공간의 재인제스트다. */
+    return { spaceId: want, joined: want !== masterSpaceId };
+}
+/**
+ * 합치는 쪽과 기존 쪽이 같은 id 를 쓰는 것들을 찾아 경고 문장을 만든다.
+ *
+ * 정당한 경우(같은 현장의 같은 구역)와 사고(서로 다른 구역이 우연히 같은 이름)를 기계가 가릴 수는
+ * 없다. 가릴 수 없는 것을 고르지 않고, **무엇이 합쳐졌는지 말한다.**
+ */
+function collidingIds(existing, incoming) {
+    const have = new Set((existing ?? []).map(x => x?.id).filter(Boolean));
+    const hits = new Set();
+    for (const x of incoming ?? [])
+        if (x?.id && have.has(x.id))
+            hits.add(x.id);
+    return [...hits].sort();
+}
+//# sourceMappingURL=ingest-space.js.map

package/dist-server/service/reference/ingest-space.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest-space.js","sourceRoot":"","sources":["../../../server/service/reference/ingest-space.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAqBH,gDAUC;AAaD,oCAKC;AAvCD,0CAA0C;AAC7B,QAAA,sBAAsB,GAAG,iBAAiB,CAAA;AAEvD;;;;;;;GAOG;AACH,SAAgB,kBAAkB,CAAC,aAAqB,EAAE,SAAoC,EAAE,eAAwB;IACtH,MAAM,IAAI,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;IACrC,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,CAAA;IAC3D,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,MAAM,CAAC,GAAG,IAAI,KAAK,CAAC,UAAU,IAAI,iEAAiE,CAAC,CACnG;QAAC,CAAS,CAAC,IAAI,GAAG,8BAAsB,CAAA;QACzC,MAAM,CAAC,CAAA;IACT,CAAC;IACD,kDAAkD;IAClD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,KAAK,aAAa,EAAE,CAAA;AAC1D,CAAC;AAOD;;;;;GAKG;AACH,SAAgB,YAAY,CAAC,QAAkD,EAAE,QAAkD;IACjI,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAa,CAAC,CAAA;IAClF,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IAC9B,KAAK,MAAM,CAAC,IAAI,QAAQ,IAAI,EAAE;QAAE,IAAI,CAAC,EAAE,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;IAC3E,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,EAAE,CAAA;AACzB,CAAC","sourcesContent":["/*\n * 인제스트가 어느 공간으로 들어갈지 정한다 — **순수**.\n *\n * ── 왜 있나 (2026-08-05) ────────────────────────────────────────────────────\n * 한 현실(공장·물류센터)을 여러 렌즈가 비춘다: 창고(WMS)·공정(MES)·야드(YMS) 가 같은 부지에 있다.\n * 엔진은 이미 그것을 지원한다 — 같은 `spaceId` 로 들어오면 공간 content 를 병합하고 기존 값을 이긴다.\n *\n * 그런데 **만드는 흐름에 그 선택이 없었다.** 템플릿은 `space.spaceId` 를 정하지 않으므로 항상\n * `<source>-site` 로 파생돼, 새 트윈은 늘 새 현장처럼 생겼다. 데이터로는 가능한 일이 저작으로는\n * 불가능했다.\n *\n * ── 없는 공간에 조용히 새 공간을 만들지 않는다 ────────────────────────────────\n * \"이 현장에 더한다\" 는 요청이 오타·낡은 목록으로 빗나갔을 때 새 공간을 만들어 주면, 사용자는\n * 합쳤다고 믿고 화면에서는 따로 놀게 된다 — 나중에 두 현장을 손으로 합쳐야 하고, 그때는 이미\n * 이벤트가 양쪽에 쌓여 있다. 그래서 **모르는 공간이면 거절한다.**\n *\n * ── 같은 id 를 쓰는 구역은 조용히 합쳐지므로 알린다 ──────────────────────────\n * 공간 content 의 구역·랜드마크는 id 로 합집합을 만든다(`unionById`). 두 렌즈가 우연히 같은 구역\n * id(`a-yard` 따위)를 쓰면 서로 다른 구역이 하나로 접힌다. 막을 일은 아니다(같은 현장의 같은 구역을\n * 가리키는 정당한 경우가 많다) — 다만 **모르고 지나가지 않게** 경고로 돌려준다.\n */\n\n/** 공간 판정 결과. */\nexport interface IngestSpaceChoice {\n  /** 실제로 쓸 공간 id. */\n  spaceId: string\n  /** 사용자가 기존 현장에 합치기를 골랐나(마스터가 파생한 공간과 다른 곳으로 들어가나). */\n  joined: boolean\n}\n\n/** 거절 사유 — 호출측이 문장을 만들 때 쓴다(언어 중립 코드). */\nexport const INGEST_SPACE_NOT_FOUND = 'space-not-found'\n\n/**\n * 요청받은 공간과 마스터가 파생한 공간 중 무엇으로 들어갈지 정한다.\n *\n * @param masterSpaceId 마스터에서 파생된 공간 id(요청이 없을 때의 기본).\n * @param requested     사용자가 고른 기존 공간 id. 없으면 빈 값/undefined.\n * @param requestedExists 그 공간이 이 테넌트에 실제로 있나(호출측이 조회해 넘긴다).\n * @throws 요청한 공간이 없으면 — 조용히 새로 만들지 않는다.\n */\nexport function resolveIngestSpace(masterSpaceId: string, requested: string | undefined | null, requestedExists: boolean): IngestSpaceChoice {\n  const want = (requested ?? '').trim()\n  if (!want) return { spaceId: masterSpaceId, joined: false }\n  if (!requestedExists) {\n    const e = new Error(`space \"${want}\" not found — cannot co-locate into a space that does not exist`)\n    ;(e as any).code = INGEST_SPACE_NOT_FOUND\n    throw e\n  }\n  /* 마스터가 이미 그 공간을 가리키면 합치기가 아니다 — 같은 공간의 재인제스트다. */\n  return { spaceId: want, joined: want !== masterSpaceId }\n}\n\n/** 구역·랜드마크처럼 id 로 합쳐지는 것들. */\ninterface Identified {\n  id?: string\n}\n\n/**\n * 합치는 쪽과 기존 쪽이 같은 id 를 쓰는 것들을 찾아 경고 문장을 만든다.\n *\n * 정당한 경우(같은 현장의 같은 구역)와 사고(서로 다른 구역이 우연히 같은 이름)를 기계가 가릴 수는\n * 없다. 가릴 수 없는 것을 고르지 않고, **무엇이 합쳐졌는지 말한다.**\n */\nexport function collidingIds(existing: readonly Identified[] | undefined | null, incoming: readonly Identified[] | undefined | null): string[] {\n  const have = new Set((existing ?? []).map(x => x?.id).filter(Boolean) as string[])\n  const hits = new Set<string>()\n  for (const x of incoming ?? []) if (x?.id && have.has(x.id)) hits.add(x.id)\n  return [...hits].sort()\n}\n"]}

package/dist-server/service/reference/knob-defaults.d.ts

@@ -0,0 +1,20 @@
+/** 템플릿 노브 — 기본값 적용에 필요한 만큼만 본다. */
+export interface KnobLike {
+    key?: string;
+    default?: unknown;
+}
+/**
+ * 빠진 노브를 기본값으로 채운다.
+ *
+ * @param knobs  템플릿이 선언한 노브들(없으면 파라미터를 그대로 돌려준다).
+ * @param params 호출자가 준 파라미터.
+ * @returns 새 객체 — 입력을 바꾸지 않는다(호출자의 객체가 몰래 변하면 추적이 어렵다).
+ */
+export declare function applyKnobDefaults(knobs: readonly KnobLike[] | undefined | null, params: Record<string, unknown> | undefined | null): Record<string, unknown>;
+/**
+ * 기본값으로 채운 노브 이름들 — 호출자에게 "무엇을 내가 정해 줬는지" 알릴 때 쓴다.
+ *
+ * 조용히 채우는 것도 조용히 비우는 것만큼 위험하다: 사용자가 준 적 없는 값으로 트윈이 만들어졌는데
+ * 아무 말이 없으면, 나중에 "왜 이 수치인가" 를 아무도 답할 수 없다.
+ */
+export declare function filledKnobKeys(knobs: readonly KnobLike[] | undefined | null, params: Record<string, unknown> | undefined | null): string[];