@things-factory/headless-twin 10.0.15 → 10.0.18

package/dist-server/service/reference/reference-master.d.ts

@@ -1,4 +1,4 @@
-import type { DomainSystem, EquipmentLevel, TestSpecificationCriterion, WorkCalendarEntry } from '@operato/twin-kernel';
+import type { DomainSystem, EquipmentLevel, TestSpecificationCriterion, WorkCalendarEntry } from '@operato/ops-contract';
 export interface RefLocation {
     id: string;
     type: string;
@@ -109,7 +109,7 @@ export interface RefTestResult {
     specId: string;
     result: 'pass' | 'fail';
     at?: string;
-    /** 없으면 무기한 — 짐작으로 기한을 만들면 멀쩡한 자격자가 조용히 사라진다. */
+    /** 없으면 무기한 — 짐작으로 기한을 만들면 멀쩡한 자격자가 오류 없이 사라진다. */
     expiresAt?: string;
 }
 export interface RefTestSpecification {
@@ -139,7 +139,16 @@ export interface RefEquipment {
     homeLocationId: string;
     mtbfMs?: number;
     mttrMs?: number;
-    gs1Id?: string;
+    /**
+     * **이 설비의 전역 정체성** — 커널 선언의 `equipment[].identity` 로 그대로 간다.
+     *
+     * 예전 이름은 `gs1Id` 였다. 그런데 **GS1 키가 아닌 것이 정상이다** — 실측한 값은 인버터의
+     * 하드웨어 식별자(`ES100000007d8d061d-1`)이고, 원본이 GIAI 를 주면 그것도 여기 들어온다.
+     * 이름이 한 종류만 가리키면 다른 종류가 들어올 때 그 자리를 못 쓴다.
+     *
+     * 자리(`RefLocation.gs1Id`)는 그대로다 — 그쪽은 실제로 SGLN 이 온다.
+     */
+    identity?: string;
     /**
      * 교대(가동시간) — 이 시간대에만 배정된다. `startHour <= endHour` 면 같은 날, 넘어가면 야간(22→6).
      * 미지정=24시간 가용. 교대 밖 자원은 고장·계획정지와 **구별되는 이유**로 쉰다(상태에 드러난다).
@@ -169,7 +178,7 @@ export interface RefEquipment {
      *
      * 없으면 **폐기한 것이 영구히 살아 있다**: 배정 대상에 남고, 가용 수에 들어가고, 화면에 뜬다.
      * 도입 예정인 것은 반대로 오늘부터 있는 것처럼 보인다. 기간 밖이면 커널이 그 시각의 모델에서
-     * 빼고 **이유를 달아 남긴다**(`effectivity: 'not-yet' | 'expired'`) — 조용히 지우지 않는다.
+     * 빼고 **이유를 달아 남긴다**(`effectivity: 'not-yet' | 'expired'`) — 알리지 않고 지우지 않는다.
      */
     effectiveStart?: string;
     effectiveEnd?: string;
@@ -214,7 +223,7 @@ export interface RefOperationVariability {
  *
  * **이것이 없으면 시뮬레이션의 시간은 우리가 코드에 고정한 상수다.** 원 시스템(또는 가상 레퍼런스)이
  * 공정별 소요·변동·수율을 말해 줘야 예측이 그 현장의 예측이 된다. 주지 않으면 커널 기본값으로
- * 굴러가고, **기본값을 썼다는 사실은 커널 `specCoverage()` 가 밝힌다**(조용히 넘어가지 않는다).
+ * 굴러가고, **기본값을 썼다는 사실은 커널 `specCoverage()` 가 밝힌다**(알리지 않고 넘어가지 않는다).
  */
 export interface RefOperation {
     /** 작업 종류 키 — 커널 `FlowTask.kind` 와 같은 값이어야 명세가 그 작업에 붙는다. */
@@ -364,7 +373,7 @@ export type MasterOrigin =
 /**
  * 템플릿 + 노브로 합성했다 — 다시 읽기 = 같은 노브로 다시 짓는다(합성은 결정적이다).
  *
- * `spaceId` 는 **만들 때 고른 현장**이다(합쳐 넣기). 기억하지 않으면 다시 읽을 때 트윈이 조용히 자기
+ * `spaceId` 는 **만들 때 고른 현장**이다(합쳐 넣기). 기억하지 않으면 다시 읽을 때 트윈이 알리지 않고 자기
  * 현장을 떠난다 — 템플릿이 낸 기본 공간으로 돌아가기 때문이다. 그러면 그 현장의 값(요금 등)도 함께
  * 잃는다(2026-08-18 실측: 한 현장에 합쳐 둔 EMS 트윈 여덟이 재동기 뒤 각자 공간으로 흩어졌다).
  */
@@ -471,7 +480,7 @@ export interface ReferenceMaster {
      * 여기에 담아 보낸다 — 그러면 `masterToTwin` 의 경고와 한 줄기로 합쳐져 화면까지 간다.
      *
      * 이 자리가 없던 동안 커넥터는 할 말이 있어도 **말할 곳이 없었다.** 그래서 도크를 랙으로 바꿔
-     * 놓고도 조용히 성공했다. 옮기는 사람만 아는 사실은 옮기는 자리에서 실어야 한다.
+     * 놓고도 알리지 않고 성공했다. 옮기는 사람만 아는 사실은 옮기는 자리에서 실어야 한다.
      */
     warnings?: IngestWarning[];
     /**
@@ -510,7 +519,7 @@ export interface IngestedTwin {
  * 호스트가 절대 구간(`StartDateTime`/`FinishDateTime`)을 계산해 넣는 것이고, 그때 이 함수는 사라진다.
  *
  * 모르는 이름에는 **0 을 답하지 않는다**(`undefined`) — 0 은 "UTC 라고 선언했다" 는 뜻이고, 모르는 것을
- * 그렇게 바꾸면 판정이 조용히 틀린다.
+ * 그렇게 바꾸면 판정이 오류 없이 틀린 값을 낸다.
  */
 export declare function utcOffsetOf(timezone?: string, at?: Date): number | undefined;
 /** 인제스트가 알리는 한 가지. */
@@ -531,7 +540,7 @@ export interface IngestWarning {
  * 형상은 **시각별 비율**이라, 시간대가 없으면 현장 정오가 아니라 UTC 정오에 피크가 선다(KST 현장이면
  * 밤 9시). 값이 그럴듯하게 나오므로 아무도 알아채지 못한다.
  *
- * 그래서 시간대를 **지어내지 않고**(서버 로컬이나 임의 기본값을 넣으면 그 트윈의 모든 시각 판정이 조용히
+ * 그래서 시간대를 **지어내지 않고**(서버 로컬이나 임의 기본값을 넣으면 그 트윈의 모든 시각 판정이 알리지 않고
  * 그 가정 위에 선다) 대신 **그 조합을 말한다** — 공간에 시간대를 선언하면 사라지는 경고다.
  */
 export declare const generationWithoutTimeZone: (spaceId: string, equipmentId: string) => IngestWarning;
@@ -553,7 +562,7 @@ export declare const unknownLocationType: (system: string, type: string, id: str
  * 되어 모든 자리가 경고를 받는다(없는 것과 못 읽은 것은 다르다).
  */
 export declare function declaredLocationTypes(productionSpec: unknown): string[] | undefined;
-/** 시간대 문자열을 못 읽었다 — 시각 해석이 UTC 로 떨어진다(조용히 현지 시각으로 가정하지 않는다). */
+/** 시간대 문자열을 못 읽었다 — 시각 해석이 UTC 로 떨어진다(알리지 않고 현지 시각으로 가정하지 않는다). */
 export declare const unknownTimezone: (timezone: string) => IngestWarning;
 /** 작업 정의에 소요시간·파라미터가 없다 — 커널 기본값으로 동작한다. */
 export declare const operationWithoutDuration: (operation: string) => IngestWarning;
@@ -564,7 +573,7 @@ export declare const noViewableRepresentation: () => IngestWarning;
  *
  * 예전에는 이런 참조가 model JSON 안의 맨 문자열이라 화면만 경고할 수 있었고, 다른 경로로 들어온
  * 데이터는 아무도 안 봤다. 이제 행으로 풀면서 **인제스트가 직접 안다** — 그러니 인제스트가 말한다.
- * 막지는 않는다(트윈은 model 로 이미 동작한다). 다만 조용히 넘기지 않는다.
+ * 막지는 않는다(트윈은 model 로 이미 동작한다). 다만 알리지 않고 넘기지 않는다.
  */
 export declare const unresolvedReference: (field: string, ref: string) => IngestWarning;
 /**
@@ -576,7 +585,7 @@ export declare const projectionFailed: (reason: string) => IngestWarning;
  * **동작 중에 공장을 전환했다** — 미러는 멈추지 않으므로, 무엇이 사라졌는지 여기서 말한다.
  *
  * 멈췄다 세우는 구조 전환이라면 사용자가 "다시 세웠다" 는 것을 안다. 미러는 그 마디가 없어서
- * 자리 하나·설비 한 대가 조용히 없어질 수 있다 — 자리가 수천인 현장에서 화면의 수를 세어
+ * 자리 하나·설비 한 대가 알리지 않고 없어질 수 있다 — 자리가 수천인 현장에서 화면의 수를 세어
  * 눈치채기를 기대할 수는 없다. 늘어난 것도 함께 말한다(무엇이 반영되었나가 곧 인제스트의 답이다).
  */
 export declare const structureAdopted: (rev: number, shift: {
@@ -591,7 +600,7 @@ export declare const structureAdopted: (rev: number, shift: {
  *
  * 예: Oracle WMS 가 우리 표에 없는 `locn_type` 을 주면 그 자리는 `storage` 가 된다 — 도크가 랙으로
  * 모델링되는 것이다. 인제스트를 통째로 실패시킬 일은 아니지만(로케이션 하나 때문에 현장 전체가
- * 안 들어오는 편이 더 나쁘다), **조용히 넘어가면 안 된다.** 트윈이 실물과 다르게 생겼는데
+ * 안 들어오는 편이 더 나쁘다), **알리지 않고 넘어가면 안 된다.** 트윈이 실물과 다르게 생겼는데
  * 아무도 그 사실을 모른 채 그 위에서 흐름을 논하게 된다.
  *
  * 값을 나열하는 이유: "3건" 만으로는 커넥터 매핑에 무엇을 더해야 하는지 알 수 없다.
@@ -602,12 +611,12 @@ export declare const describeWarnings: (warnings: readonly IngestWarning[]) => s
 /**
  * 서버가 기본값으로 채운 노브들 — 사용자가 준 적 없는 값으로 트윈이 만들어졌음을 알린다.
  *
- * 조용히 채우면 나중에 "왜 이 수치인가" 를 아무도 답할 수 없다. 막을 일은 아니다(기본값은 템플릿이
+ * 알리지 않고 채우면 나중에 "왜 이 수치인가" 를 아무도 답할 수 없다. 막을 일은 아니다(기본값은 템플릿이
  * 확신을 갖고 선언한 값이다) — 다만 밝힌다.
  */
 export declare const knobDefaultsFilled: (keys: readonly string[]) => IngestWarning;
 /**
- * 이 현장의 설비를 노브 값으로 채웠다 — **조용히 채우지 않는다.**
+ * 이 현장의 설비를 노브 값으로 채웠다 — **알리지 않고 채우지 않는다.**
  *
  * 에너지 트윈의 부하를 이웃 설비 id 로 선언할 때 쓴다. 몇 개를 가져왔는지 말해 주지 않으면, 사용자는
  * 자기가 고르지 않은 설비들이 부하로 잡힌 것을 나중에 화면에서야 알게 된다.
@@ -618,7 +627,7 @@ export declare function masterToTwin(master: ReferenceMaster, catalog?: any): In
  * 다시 읽을 사이트를 고른다 — **기억해 둔 사이트 하나만**.
  *
  * 못 찾으면 **첫 사이트로 때우지 않는다**: 다른 현장의 구조를 이 트윈에 덮어쓰는 일이고, 그것은 오류가
- * 아니라 **조용히 틀린 공장**으로 나타난다. 기억이 없는 옛 트윈은 `undefined` 를 돌려주고, 부르는 쪽이
+ * 아니라 **오류 없이 틀린 공장**으로 나타난다. 기억이 없는 옛 트윈은 `undefined` 를 돌려주고, 부르는 쪽이
  * 마스터의 정체(`source` = 인스턴스 id)로 찾는 길을 택한다.
  */
 export declare function pickOriginSite<T extends {

package/dist-server/service/reference/reference-master.js

@@ -28,7 +28,7 @@ exports.pickOriginSite = pickOriginSite;
  * 호스트가 절대 구간(`StartDateTime`/`FinishDateTime`)을 계산해 넣는 것이고, 그때 이 함수는 사라진다.
  *
  * 모르는 이름에는 **0 을 답하지 않는다**(`undefined`) — 0 은 "UTC 라고 선언했다" 는 뜻이고, 모르는 것을
- * 그렇게 바꾸면 판정이 조용히 틀린다.
+ * 그렇게 바꾸면 판정이 오류 없이 틀린 값을 낸다.
  */
 function utcOffsetOf(timezone, at = new Date()) {
     if (!timezone)
@@ -57,7 +57,7 @@ function utcOffsetOf(timezone, at = new Date()) {
  * 형상은 **시각별 비율**이라, 시간대가 없으면 현장 정오가 아니라 UTC 정오에 피크가 선다(KST 현장이면
  * 밤 9시). 값이 그럴듯하게 나오므로 아무도 알아채지 못한다.
  *
- * 그래서 시간대를 **지어내지 않고**(서버 로컬이나 임의 기본값을 넣으면 그 트윈의 모든 시각 판정이 조용히
+ * 그래서 시간대를 **지어내지 않고**(서버 로컬이나 임의 기본값을 넣으면 그 트윈의 모든 시각 판정이 알리지 않고
  * 그 가정 위에 선다) 대신 **그 조합을 말한다** — 공간에 시간대를 선언하면 사라지는 경고다.
  */
 const generationWithoutTimeZone = (spaceId, equipmentId) => ({
@@ -79,8 +79,19 @@ exports.generationWithoutTimeZone = generationWithoutTimeZone;
 const unknownLocationType = (system, type, id) => ({
     code: 'unknown-location-type',
     params: { system, type, id },
+    /*
+     * ── 무슨 일이 벌어지는지 말한다 (2026-08-25) ────────────────────────────────
+     * 예전 문장은 「흐름에 참여하지 못할 수 있다」였다. 물건이 흐르는 도메인에서는 맞는 말인데,
+     * 에너지 트윈에는 흐름이 없어서 그 문장이 아무것도 알려 주지 않았다(실제로 태양광 발전소를
+     * 붙이면서 이 경고를 받은 사람이 「이 경고가 뜻이 있는가」를 되물었다).
+     *
+     * 종류를 모르면 실제로 일어나는 일은 하나다: **그 자리에 능력이 붙지 않는다.** 능력이 없으면
+     * 상태 필드도 없고, 롤업에도 들어가지 않고, 저작면 팔레트에도 서지 않는다. 도메인을 가리지 않고
+     * 참인 문장이므로 이것을 적는다.
+     */
     message: `"${type}" is declared nowhere for ${system} (${id}) — neither in the master's own locationTypes nor in the built-in ` +
-        `catalog, so the kernel may not include this location in the flow`
+        `catalog. A location whose type is unknown gets no capabilities, so it carries no state, joins no rollup, ` +
+        `and (in domains that move things) may be left out of the flow.`
 });
 exports.unknownLocationType = unknownLocationType;
 /**
@@ -97,7 +108,7 @@ function declaredLocationTypes(productionSpec) {
     const keys = list.map((t) => (typeof t === 'string' ? t : t?.key)).filter((k) => typeof k === 'string' && k);
     return keys.length ? keys : undefined;
 }
-/** 시간대 문자열을 못 읽었다 — 시각 해석이 UTC 로 떨어진다(조용히 현지 시각으로 가정하지 않는다). */
+/** 시간대 문자열을 못 읽었다 — 시각 해석이 UTC 로 떨어진다(알리지 않고 현지 시각으로 가정하지 않는다). */
 const unknownTimezone = (timezone) => ({
     code: 'unknown-timezone',
     params: { timezone },
@@ -122,7 +133,7 @@ exports.noViewableRepresentation = noViewableRepresentation;
  *
  * 예전에는 이런 참조가 model JSON 안의 맨 문자열이라 화면만 경고할 수 있었고, 다른 경로로 들어온
  * 데이터는 아무도 안 봤다. 이제 행으로 풀면서 **인제스트가 직접 안다** — 그러니 인제스트가 말한다.
- * 막지는 않는다(트윈은 model 로 이미 동작한다). 다만 조용히 넘기지 않는다.
+ * 막지는 않는다(트윈은 model 로 이미 동작한다). 다만 알리지 않고 넘기지 않는다.
  */
 const unresolvedReference = (field, ref) => ({
     code: 'unresolved-reference',
@@ -144,7 +155,7 @@ exports.projectionFailed = projectionFailed;
  * **동작 중에 공장을 전환했다** — 미러는 멈추지 않으므로, 무엇이 사라졌는지 여기서 말한다.
  *
  * 멈췄다 세우는 구조 전환이라면 사용자가 "다시 세웠다" 는 것을 안다. 미러는 그 마디가 없어서
- * 자리 하나·설비 한 대가 조용히 없어질 수 있다 — 자리가 수천인 현장에서 화면의 수를 세어
+ * 자리 하나·설비 한 대가 알리지 않고 없어질 수 있다 — 자리가 수천인 현장에서 화면의 수를 세어
  * 눈치채기를 기대할 수는 없다. 늘어난 것도 함께 말한다(무엇이 반영되었나가 곧 인제스트의 답이다).
  */
 const structureAdopted = (rev, shift) => ({
@@ -160,7 +171,7 @@ exports.structureAdopted = structureAdopted;
  *
  * 예: Oracle WMS 가 우리 표에 없는 `locn_type` 을 주면 그 자리는 `storage` 가 된다 — 도크가 랙으로
  * 모델링되는 것이다. 인제스트를 통째로 실패시킬 일은 아니지만(로케이션 하나 때문에 현장 전체가
- * 안 들어오는 편이 더 나쁘다), **조용히 넘어가면 안 된다.** 트윈이 실물과 다르게 생겼는데
+ * 안 들어오는 편이 더 나쁘다), **알리지 않고 넘어가면 안 된다.** 트윈이 실물과 다르게 생겼는데
  * 아무도 그 사실을 모른 채 그 위에서 흐름을 논하게 된다.
  *
  * 값을 나열하는 이유: "3건" 만으로는 커넥터 매핑에 무엇을 더해야 하는지 알 수 없다.
@@ -177,7 +188,7 @@ exports.describeWarnings = describeWarnings;
 /**
  * 서버가 기본값으로 채운 노브들 — 사용자가 준 적 없는 값으로 트윈이 만들어졌음을 알린다.
  *
- * 조용히 채우면 나중에 "왜 이 수치인가" 를 아무도 답할 수 없다. 막을 일은 아니다(기본값은 템플릿이
+ * 알리지 않고 채우면 나중에 "왜 이 수치인가" 를 아무도 답할 수 없다. 막을 일은 아니다(기본값은 템플릿이
  * 확신을 갖고 선언한 값이다) — 다만 밝힌다.
  */
 const knobDefaultsFilled = (keys) => ({
@@ -187,7 +198,7 @@ const knobDefaultsFilled = (keys) => ({
 });
 exports.knobDefaultsFilled = knobDefaultsFilled;
 /**
- * 이 현장의 설비를 노브 값으로 채웠다 — **조용히 채우지 않는다.**
+ * 이 현장의 설비를 노브 값으로 채웠다 — **알리지 않고 채우지 않는다.**
  *
  * 에너지 트윈의 부하를 이웃 설비 id 로 선언할 때 쓴다. 몇 개를 가져왔는지 말해 주지 않으면, 사용자는
  * 자기가 고르지 않은 설비들이 부하로 잡힌 것을 나중에 화면에서야 알게 된다.
@@ -220,13 +231,13 @@ function masterToTwin(master, catalog) {
         /*
          * **속성도 통과시킨다** — 설비와 같은 규율(손대지 않고 나른다). 여기가 없으면 자리에 실은 값이
          * 커널에 닿지 않는다: 에너지의 계약전력(`contract.kW`)이 그 경로이고, 통과하지 않으면 커널이
-         * 계약을 모르는 채로 서서 **판정을 아예 하지 않는다**(오류 없이 조용히).
+         * 계약을 모르는 채로 서서 **판정을 아예 하지 않는다**(오류 없이 알리지 않고).
          */
         return { id: l.id, type: l.type, ...(l.name ? { name: l.name } : {}), ...(l.description ? { description: l.description } : {}), capacity: l.capacity ?? 0, ...(l.parallelism !== undefined ? { parallelism: l.parallelism } : {}), ...(l.level ? { level: l.level } : {}), ...(l.properties?.length ? { properties: l.properties } : {}), parentId: l.parentId, ...(l.upstreamId ? { upstreamId: l.upstreamId } : {}), gs1Id: l.gs1Id };
     });
     const equipment = (master.equipment ?? []).map(e => ({
         id: e.id, kind: e.kind, ...(e.name ? { name: e.name } : {}), ...(e.description ? { description: e.description } : {}), ...(e.testResults?.length ? { testResults: e.testResults } : {}),
-        homeLocation: e.homeLocationId, mtbfMs: e.mtbfMs, mttrMs: e.mttrMs, gs1Id: e.gs1Id,
+        homeLocation: e.homeLocationId, mtbfMs: e.mtbfMs, mttrMs: e.mttrMs, ...(e.identity ? { identity: e.identity } : {}),
         ...(e.window ? { window: e.window } : {}),
         /* 속성은 손대지 않고 통과 — 이동시간 추정기가 kind 별 속도를 여기서 읽는다(단위 코드 그대로). */
         ...(e.properties?.length ? { properties: e.properties } : {}), ...(e.workCalendar?.length ? { workCalendar: e.workCalendar } : {}), ...(e.testSpecificationIds?.length ? { testSpecificationIds: e.testSpecificationIds } : {}),
@@ -326,10 +337,21 @@ function masterToTwin(master, catalog) {
     // 표현을 안 줘도 geo 만 있으면 위성 지도로 착지. (area 폴리곤 물질화는 좌표 투영 필요 → space #3.)
     const geo = master.space.geo;
     const givenReps = master.space.representations ?? [];
+    /*
+     * ── 이름을 지어내지 않는다 (2026-08-26) ────────────────────────────────────
+     * 여기가 합성한 표현에 `name: '위성 지도'` 를 넣고 있었다. 이 층은 언어 중립이어야 하는데 한국어가
+     * 그대로 저장됐다.
+     *
+     * 낱말 열쇠(`twin.representation.map` 같은 것)를 넣는 길도 있는데 택하지 않았다. **표현의 이름은
+     * 사람이 바꿀 수 있는 값**이고, 바꿀 수 있는 값 안에 열쇠가 들어 있으면 사람이 한 번 고치는 순간
+     * 그 자리만 열쇠가 아니게 되어 규칙이 둘이 된다.
+     *
+     * 그래서 이름을 넣지 않는다. 화면이 종류(`map`)로 부르고, 사람이 붙이면 그때부터 그 이름이다.
+     */
     const representations = givenReps.length > 0
         ? givenReps
         : geo
-            ? [{ id: 'r-map', type: 'map', name: '위성 지도', primary: true, center: { lat: geo.lat, lon: geo.lon }, zoom: 17 }]
+            ? [{ id: 'r-map', type: 'map', primary: true, center: { lat: geo.lat, lon: geo.lon }, zoom: 17 }]
             : [];
     if (representations.length === 0) {
         warnings.push((0, exports.noViewableRepresentation)());
@@ -345,7 +367,7 @@ function masterToTwin(master, catalog) {
  * 다시 읽을 사이트를 고른다 — **기억해 둔 사이트 하나만**.
  *
  * 못 찾으면 **첫 사이트로 때우지 않는다**: 다른 현장의 구조를 이 트윈에 덮어쓰는 일이고, 그것은 오류가
- * 아니라 **조용히 틀린 공장**으로 나타난다. 기억이 없는 옛 트윈은 `undefined` 를 돌려주고, 부르는 쪽이
+ * 아니라 **오류 없이 틀린 공장**으로 나타난다. 기억이 없는 옛 트윈은 `undefined` 를 돌려주고, 부르는 쪽이
  * 마스터의 정체(`source` = 인스턴스 id)로 찾는 길을 택한다.
  */
 function pickOriginSite(sites, origin) {