@things-factory/headless-twin 10.0.8 → 10.0.10

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

@@ -0,0 +1,59 @@
+/*
+ * 노브 기본값 적용 — **순수**. "안 준 값은 템플릿이 선언한 기본값으로."
+ *
+ * ── 왜 있나 (2026-08-05) ────────────────────────────────────────────────────
+ * 템플릿은 노브마다 기본값을 선언한다(`knobs[].default`). 그런데 그 기본값을 채우는 일을 **위자드만**
+ * 하고 있었다 — 서버는 받은 파라미터를 그대로 `build(p)` 에 넘긴다. 그래서 파라미터를 일부만 주고
+ * 부르면(AI·스크립트·API 호출자) 템플릿 안에서 `Number(p.inboundRate) || 0` 이 **0** 이 되고,
+ * 발생률 0 = 도착 없음 = **아무것도 하지 않는 트윈**이 조용히 만들어진다.
+ *
+ * 실제로 그 함정을 밟았다: 유통가공 창고를 파라미터 일부만 주고 만들었더니 이벤트가 0건이었고,
+ * 처음에는 템플릿이 깨진 것으로 오진했다. 기본값을 아는 곳이 계약(노브 스키마)인데 그것을 적용하는
+ * 곳이 화면뿐이면, 화면을 거치지 않는 모든 경로가 함정이 된다.
+ *
+ * ── 0 을 기본값으로 덮지 않는다 ─────────────────────────────────────────────
+ * 발생률 `0` 은 "도착 없음" 이라는 **뜻 있는 값**이다. 없는 것과 0 은 다르다 — falsy 로 판정해 덮으면
+ * "자극 없이 구조만 보겠다" 는 선언이 조용히 뒤집힌다. 그래서 **키가 없을 때만** 채운다.
+ * `null` 은 없는 것으로 본다(JSON·GraphQL 경로에서 "주지 않음" 이 null 로 오는 일이 흔하다).
+ *
+ * ── 선언 밖 파라미터는 손대지 않는다 ────────────────────────────────────────
+ * 템플릿은 노브에 없는 값도 읽는다(예: `geo` 대신 `lat`/`lon` 폴백). 모르는 키를 걷어내면 그 경로가
+ * 조용히 끊긴다. 그대로 통과시킨다.
+ */
+
+/** 템플릿 노브 — 기본값 적용에 필요한 만큼만 본다. */
+export interface KnobLike {
+  key?: string
+  default?: unknown
+}
+
+/**
+ * 빠진 노브를 기본값으로 채운다.
+ *
+ * @param knobs  템플릿이 선언한 노브들(없으면 파라미터를 그대로 돌려준다).
+ * @param params 호출자가 준 파라미터.
+ * @returns 새 객체 — 입력을 바꾸지 않는다(호출자의 객체가 몰래 변하면 추적이 어렵다).
+ */
+export function applyKnobDefaults(knobs: readonly KnobLike[] | undefined | null, params: Record<string, unknown> | undefined | null): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...(params ?? {}) }
+  for (const k of knobs ?? []) {
+    if (!k?.key) continue
+    if (k.default === undefined) continue // 기본값을 선언하지 않은 노브는 채울 것이 없다
+    const given = out[k.key]
+    if (given === undefined || given === null) out[k.key] = k.default
+  }
+  return out
+}
+
+/**
+ * 기본값으로 채운 노브 이름들 — 호출자에게 "무엇을 내가 정해 줬는지" 알릴 때 쓴다.
+ *
+ * 조용히 채우는 것도 조용히 비우는 것만큼 위험하다: 사용자가 준 적 없는 값으로 트윈이 만들어졌는데
+ * 아무 말이 없으면, 나중에 "왜 이 수치인가" 를 아무도 답할 수 없다.
+ */
+export function filledKnobKeys(knobs: readonly KnobLike[] | undefined | null, params: Record<string, unknown> | undefined | null): string[] {
+  const given = params ?? {}
+  return (knobs ?? [])
+    .filter(k => k?.key && k.default !== undefined && (given[k.key!] === undefined || given[k.key!] === null))
+    .map(k => k.key!)
+}

package/server/service/reference/reference-live.ts

@@ -1,5 +1,9 @@
+import { getRepository } from '@things-factory/shell'
+
 import { getAdapter, type ConnectionConfig, type SiteDescriptor } from './reference-adapter.js'
-import { TwinEngine, ingestCanonicalRecords, type CanonicalRecord } from '../../engine/index.js'
+import { TwinEngine, ingestCanonicalRecords, registerLiveFeedProbe, type CanonicalRecord } from '../../engine/index.js'
+import { TwinInstance } from '../twin-instance/twin-instance.js'
+import { TwinReference } from './twin-reference.js'
 
 /*
  * 커넥터 기반 라이브 피드 결선(reference → live, §0 프레임 ① realityMode='mirror').
@@ -27,20 +31,31 @@ export async function startReferenceLiveFeed(
   if (!adapter?.openLiveFeed) return false
 
   const det = await TwinEngine.detail(domainId, instanceId)
-  if (!det?.board) throw new Error(`instance "${instanceId}" not provisioned (no board) — ingest master before live start`)
+  if (!det?.model) throw new Error(`instance "${instanceId}" not provisioned (no model) — ingest master before live start`)
 
   // mirror 모드 기동 — 커널 tick 없이 projector 가 실 이벤트를 미러(startLive 가 realityMode='mirror' 설정).
   // 시각 기준은 **공간**이 갖는다(테넌트 아님) — 교대의 HH:MM 을 어느 기준으로 읽나.
-  TwinEngine.startLive(instanceId, domainId, det.kind ?? 'wms', await TwinEngine.withSpaceTimeBase(det.board, domainId))
+  TwinEngine.startLive(instanceId, domainId, det.kind, await TwinEngine.withSpaceTimeBase(det.model, domainId))
 
   stopReferenceLiveFeed(instanceId) // 재기동 시 이전 피드 정리
   const unsubscribe = adapter.openLiveFeed(cfg, site, (records: unknown[]) => {
-    if (!TwinEngine.instances[instanceId]) {
+    if (!TwinEngine.owns(domainId, instanceId)) {
       stopReferenceLiveFeed(instanceId) // 인스턴스 사라지면 자가 정지(안전망)
       return
     }
-    const { accepted } = ingestCanonicalRecords(records as CanonicalRecord[], domainId, new Date().toISOString())
-    if (accepted.length) TwinEngine.ingestLive(instanceId, accepted)
+    const { accepted, rejected } = ingestCanonicalRecords(records as CanonicalRecord[], domainId, new Date().toISOString())
+    if (accepted.length) TwinEngine.ingestLive(domainId, instanceId, accepted)
+    /*
+     * **거부한 것을 조용히 버리지 않는다.** 예전에는 `rejected` 를 받지도 않았다 — 커넥터의 매핑이
+     * 틀리면 트윈은 「아무 일도 일어나지 않는」 모습이 되고, 로그에도 아무 흔적이 없었다.
+     *
+     * 지금은 이유와 함께 남긴다. 화면까지 나르는 것은 다음 일이다(라이브 계측은 초당 여러 건이라
+     * 건마다 방송하면 그 자체가 부하가 된다 — 집계해 낼 자리가 필요하다).
+     */
+    if (rejected.length) {
+      const why = rejected[0]?.errors?.join(' · ') ?? 'unknown'
+      console.warn(`[twin-live] "${instanceId}": ${rejected.length} record(s) rejected — e.g. ${why}`)
+    }
   })
   feeds.set(instanceId, unsubscribe)
   return true
@@ -60,5 +75,105 @@ export function listReferenceLiveFeeds(): string[] {
   return [...feeds.keys()]
 }
 
+/**
+ * 부팅 때 **끊어진 피드를 다시 붙인다** — 도는 미러 트윈에 계측이 계속 들어오게.
+ *
+ * ── 무엇이 조용히 끊겼나 (2026-08-14) ───────────────────────────────────────
+ * `startReferenceLiveFeed` 를 부르는 곳은 `importTwinReference` **하나뿐**이었다. 그래서 서버를 한 번
+ * 재기동하면 미러 트윈은 「도는 중」이라 말하면서 아무 계측도 받지 않았다 — 오류도 로그도 없이,
+ * 사람은 「값이 안 변하네」로 알게 된다. 실 배포에서 재기동 한 번에 계측이 멈추는 셈이다.
+ *
+ * ── 되살릴 재료는 이미 영속돼 있다 ─────────────────────────────────────────
+ * `TwinReference` 가 어댑터 종류·접속 설정·그 레퍼런스가 만든 인스턴스(`scopeSpec.produced`)를 들고 있다.
+ * 사이트 서술자만 없는데(`hint` 는 남기지 않았다) **다시 찾아서** 얻는다(`discoverSites`) — 인제스트가
+ * 걷는 것과 같은 길이므로 규칙이 갈라지지 않는다. 되살릴 인스턴스가 없으면 그 호출도 하지 않는다.
+ *
+ * 재개 대상은 **등록부가 도는 미러라고 말하는 것**뿐이다: 멈춘 트윈을 되살리면 사람이 멈춘 것을
+ * 우리가 다시 켜는 것이고, 시뮬 트윈에 실 계측을 부으면 두 현실이 섞인다.
+ */
+export async function resumeReferenceLiveFeeds(): Promise<{ resumed: string[]; failed: { instanceId: string; error: string }[] }> {
+  const resumed: string[] = []
+  const failed: { instanceId: string; error: string }[] = []
+  /*
+   * **한 트윈에 피드는 하나다** (2026-08-18).
+   *
+   * 같은 사이트를 두 레퍼런스가 각각 인제스트하면 둘 다 그 인스턴스를 자기가 만든 것(`produced`)으로
+   * 들고 있다. 기동 때 그 목록을 그대로 돌면 같은 트윈에 피드를 두 번 붙이는데, 붙이는 함수가 미러를
+   * 다시 세우므로(`startLive`) **먼저 쌓인 수요 구간이 리셋된다** — 실제로 그렇게 났다
+   * (로그: `reattached 2 feed(s): ems-plant-1, ems-plant-1`).
+   *
+   * 그러니 한 번만 붙이고, **두 레퍼런스가 같은 트윈을 주장한다는 사실은 말한다** — 조용히 하나를
+   * 고르면 어느 접속이 그 트윈을 먹이고 있는지 아무도 모르게 된다.
+   */
+  const attached = new Map<string, string>() // instanceId → 먼저 붙인 레퍼런스
+  try {
+    const refs = await getRepository(TwinReference).find({ where: { status: 'connected' }, relations: ['domain'] })
+    for (const ref of refs) {
+      const domainId = (ref as any).domain?.id ?? (ref as any).domainId
+      const adapter = getAdapter(ref.adapterType)
+      if (!domainId || !adapter?.openLiveFeed) continue // 관측만 하는 어댑터에는 되살릴 피드가 없다
+
+      const produced: any[] = ((ref.scopeSpec as any)?.produced ?? []).filter((p: any) => p?.instanceId && p?.siteId)
+      if (!produced.length) continue
+
+      /* 등록부가 「도는 미러」라고 말하는 것만 고른다. */
+      const rows = await getRepository(TwinInstance).find({
+        where: produced.map((p: any) => ({ domain: { id: domainId }, instanceId: p.instanceId })) as any
+      })
+      const live = produced.filter((p: any) =>
+        rows.some(r => r.instanceId === p.instanceId && r.status === 'running' && r.realityMode === 'mirror')
+      )
+      if (!live.length) continue
+
+      let sites: SiteDescriptor[]
+      try {
+        sites = await adapter.discoverSites(ref.connectionConfig ?? {})
+      } catch (e: any) {
+        /* 원 시스템이 아직 안 떴을 수 있다 — 지어내지 않고 그렇게 적는다(트윈은 계속 「도는 미러」다). */
+        for (const p of live) failed.push({ instanceId: p.instanceId, error: `discover failed: ${e?.message ?? 'unknown'}` })
+        continue
+      }
+
+      for (const p of live) {
+        const site = sites.find(s => s.siteId === p.siteId)
+        if (!site) {
+          failed.push({ instanceId: p.instanceId, error: `site "${p.siteId}" no longer discoverable` })
+          continue
+        }
+        const owner = attached.get(p.instanceId)
+        if (owner) {
+          /* 두 접속이 같은 트윈을 주장한다 — 먼저 붙은 것을 지키고, 그 사실을 남긴다(둘 다 붙이면 미러가 리셋된다). */
+          failed.push({
+            instanceId: p.instanceId,
+            error: `also claimed by reference "${ref.source}" — kept the feed from "${owner}" (two connections feeding one twin would reset the mirror)`
+          })
+          continue
+        }
+        attached.set(p.instanceId, ref.source)
+        try {
+          const ok = await startReferenceLiveFeed(domainId, ref.adapterType, ref.connectionConfig ?? {}, site, p.instanceId)
+          if (ok) resumed.push(p.instanceId)
+          else failed.push({ instanceId: p.instanceId, error: 'adapter has no openLiveFeed' })
+        } catch (e: any) {
+          failed.push({ instanceId: p.instanceId, error: e?.message ?? 'reattach failed' })
+        }
+      }
+    }
+  } catch (e: any) {
+    console.error('[twin-live] feed resume scan failed', e?.message)
+  }
+
+  if (resumed.length) console.log(`[twin-live] reattached ${resumed.length} feed(s): ${resumed.join(', ')}`)
+  /* **조용히 넘기지 않는다** — 붙지 않은 미러는 「도는데 아무것도 오지 않는」 트윈이다. */
+  for (const f of failed) console.warn(`[twin-live] "${f.instanceId}" feed NOT reattached — ${f.error}`)
+  return { resumed, failed }
+}
+
+/*
+ * 이 계층의 피드 장부를 등록한다 — 화면이 「끊김」을 말할 근거는 **묻는 자리 하나**여야 한다.
+ * (프리셋 기반 피드는 앱이 자기 장부를 따로 등록한다. 한쪽만 보면 흐르는 트윈을 끊겼다고 부른다.)
+ */
+registerLiveFeedProbe(() => [...feeds.keys()])
+
 /* 인스턴스 정지 시 피드 자동 정리(생명주기 대칭). */
 TwinEngine.onStop(instanceId => stopReferenceLiveFeed(instanceId))