@things-factory/headless-twin 10.0.14 → 10.0.17

package/server/engine/model-gap.ts

@@ -38,7 +38,7 @@ export interface ModelGapSource {
    *
    * `unknownEquipment` 를 루트에서 읽고 있었다(2026-08-20에 잡음). 커널은 그것을 `EnergyState` 안에
    * 담으므로, 루트에서 읽으면 **영원히 `null`** 이다 — 오류도 없이 「에너지 트윈이 아니다」로 읽힌다.
-   * 나만 읽는 필드를 잘못된 경로에서 읽으면 이렇게 조용히 사라진다.
+   * 나만 읽는 필드를 잘못된 경로에서 읽으면 이렇게 오류 없이 사라진다.
    *
    * 계량 지점의 `origin` 은 **없을 수 있다**(옛 스냅샷에서 이어받은 지점). 그때는 「선언되었다」가
    * 아니라 **모른다**다.
@@ -54,7 +54,7 @@ export interface ModelGapSource {
  * 화면에 내는 id 수 상한.
  *
  * 오타 하나를 찾는 데 스무 개면 충분하고, 원천이 수천 개를 보내는 경우(모델을 아예 안 맞춘 경우)에
- * 목록으로 화면을 채울 이유가 없다. **넘친 수는 함께 낸다** — 조용히 자르지 않는다.
+ * 목록으로 화면을 채울 이유가 없다. **넘친 수는 함께 낸다** — 알리지 않고 자르지 않는다.
  */
 export const GAP_ID_LIMIT = 20
 
@@ -83,7 +83,7 @@ export interface ModelGapView {
    * EMS 계량 지점.
    *
    * ── 이 축이 가장 무겁다 ────────────────────────────────────────────────────
-   * 모르는 `meterId` 는 조용히 새 계량기가 되고 그 kW 가 그 현장의 **수요 구간·피크·요금 판정**에
+   * 모르는 `meterId` 는 알리지 않고 새 계량기가 되고 그 kW 가 그 현장의 **수요 구간·피크·요금 판정**에
    * 더해진다. 오타 하나면 진짜 계량기는 멈추고 유령이 누적된다 — 숫자는 그럴듯하고 틀린다. 자리 오타는
    * 스키매틱이 비는 것으로 드러나지만, 이건 그럴듯한 숫자로 나온다.
    *

package/server/engine/model-vocabulary.ts

@@ -18,7 +18,7 @@
  *
  * ── 왜 자리마다 고치지 않나 ─────────────────────────────────────────────────
  * 저장된 모델를 읽는 자리가 **27곳**이다. 자리마다 리더를 쓰게 하면 다음에 추가되는 자리가 또 빠진다 —
- * 그리고 빠진 것은 오류가 아니라 **빈 공장**이라 조용하다. 그래서 **DB에서 읽는 순간 한 번** 정규화한다
+ * 그리고 빠진 것은 오류가 아니라 **빈 공장**이라 들어온 것이 없다. 그래서 **DB에서 읽는 순간 한 번** 정규화한다
  * (엔티티 컬럼 변환기). 그 뒤로는 코드가 세대를 알 필요가 없다.
  *
  * ── 쓰기는 건드리지 않는다 ──────────────────────────────────────────────────

package/server/engine/oee-accumulator.ts

@@ -23,7 +23,7 @@ interface Acc {
   scrapCount: number
 }
 
-/** 누적기의 완전한 재개점 — 저장했다 되살릴 수 있어야 꼬리만 접을 수 있다. */
+/** 누적기의 완전한 재개점 — 저장했다 되살릴 수 있어야 꼬리만 계산할 수 있다. */
 export interface OeeCheckpoint {
   maxMs: number
   acc: ({ moverId: string } & Acc)[]
@@ -43,12 +43,12 @@ export class OeeAccumulator {
   }
 
   /**
-   * **재개점** — 이 누적기의 상태 전부(이어 접기의 씨앗).
+   * **재개점** — 이 누적기의 상태 전부(이어 계산의 씨앗).
    *
    * ── 왜 필요한가 (2026-08-18) ────────────────────────────────────────────────
    * 가동 이력은 원 시스템이 누적을 주지 않아 **우리가 이벤트를 적분해** 만든다. 그래서 저널을 꼬리만
-   * 접으면 이 누적기는 꼬리분만 갖게 되고, 화면의 가용률·수율이 조용히 작아진다(오류는 나지 않는다).
-   * 재개점을 함께 저장·복원해야 「이어 접은 값」이 「0부터 접은 값」과 같아진다.
+   * 계산하면 이 누적기는 꼬리분만 갖게 되고, 화면의 가용률·수율이 알리지 않고 작아진다(오류는 나지 않는다).
+   * 재개점을 함께 저장·복원해야 「이어 계산한 값」이 「0부터 계산한 값」과 같아진다.
    */
   serialize(): OeeCheckpoint {
     return {

package/server/engine/property-effects.ts

@@ -47,7 +47,7 @@ export const PROPERTY_EFFECTS: PropertyEffect[] = [
    *
    * 이 값들은 **오래전부터 읽히고 있었다** — 커널이 부하·피크·배터리를 그것으로 계산하고, 호스트가
    * 금액을 그것으로 만든다. 그런데 등록부에 없어서 화면은 그 값들에 대해 「표시만 됩니다」라고 말했다.
-   * 조용한 거짓말이다: 사용자는 계약전력을 넣고도 「이 값은 아무것도 바꾸지 않는다」는 문장을 읽었다.
+   * 들어온 것이 없는 거짓말이다: 사용자는 계약전력을 넣고도 「이 값은 아무것도 바꾸지 않는다」는 문장을 읽었다.
    *
    * 효과를 새로 만든 것이 아니라 **있는 효과를 드러낸다.** `readBy` 는 실제로 읽는 자리를 가리킨다.
    */
@@ -111,7 +111,7 @@ export const PROPERTY_EFFECTS: PropertyEffect[] = [
     effect: 'twin.propeffect.genDailyProfile',
     readBy: '@operato/twin-kernel generationFractionAt (시각별 발전 비율)'
   },
-  /* 요금은 커널이 읽지 않는다 — 금액은 저널을 접는 호스트가 만든다. readBy 가 그 사실을 말한다. */
+  /* 요금은 커널이 읽지 않는다 — 금액은 저널을 계산하는 호스트가 만든다. readBy 가 그 사실을 말한다. */
   {
     id: 'tariff.demandChargePerKW',
     axes: ['locations'],

package/server/engine/read-time.ts

@@ -0,0 +1,77 @@
+import type { ObjectLiteral, Repository } from 'typeorm'
+
+/*
+ * **저장된 값을 시각으로 읽는 두 가지 물음** (2026-08-28 실측).
+ *
+ * ── 무엇이 어긋났나 ─────────────────────────────────────────────────────────
+ * `getRawOne`·`getRawMany` 는 드라이버가 준 값을 그대로 준다. sqlite 가 주는 그 값에는 **시간대가
+ * 없다**(`2026-08-27 14:37:20.049`). 그것을 `new Date()` 로 읽으면 서버의 지역 시간으로 해석해
+ * 한국에서 9시간이 밀린다. 저장된 값은 UTC 이므로 그 해석이 틀렸다.
+ *
+ * 네 자리에서 났다. 둘은 **지우는 경계**(경계가 이르게 밀리면 정리가 0건이 되어 멈춘다), 하나는
+ * 이어 읽기 지점(9시간을 건너뛰어 본 줄이 또 나왔다), 하나는 「이 목록은 언제부터 말할 수 있나」.
+ *
+ * ── 처음에 편법을 썼다 ──────────────────────────────────────────────────────
+ * 「시간대가 없으면 UTC 로 읽는다」를 직접 적었다. 그것은 **드라이버가 어떤 문자열로 저장하는지를
+ * 응용 코드가 아는 것**이고, 이 저장소의 절대 규칙(다섯 드라이버·TypeORM 관용구만)에 어긋난다.
+ *
+ * 표준 문이 이미 있다. `Driver.prepareHydratedValue(value, column)` — 엔티티 변환
+ * (`RawSqlResultsToEntityTransformer`)이 지나는 바로 그 함수다. sqlite 구현이 공백을 `T` 로 바꾸고
+ * `Z` 를 붙이고, Postgres 구현은 이미 날짜 객체인 값을 그대로 낸다. 드라이버마다 자기 구현을 갖고
+ * 있으므로 이식성이 **정의상** 보장된다.
+ *
+ * ── 두 물음을 섞지 않는다 ───────────────────────────────────────────────────
+ *   `hydratedDate`  **테이블의 컬럼** 값을 읽는다 — 드라이버에게 물어본다
+ *   `absoluteTime`  **계약이 절대시각이라고 약속한** 값을 읽는다(유입 봉투 · 우리가 만든 커서)
+ *
+ * 앞의 것에 뒤의 규칙을 쓰면 편법이 되고, 뒤의 것에 앞의 것을 쓸 수는 없다(컬럼이 아니다).
+ */
+
+/** 시간대가 적혀 있나 — `Z`·`+09:00`·`-0500`. */
+const HAS_ZONE = /([Zz]|[+-]\d{2}:?\d{2})$/
+
+/**
+ * 원시 결과에서 꺼낸 **컬럼 값** → 날짜. 읽을 수 없으면 `null`.
+ *
+ * 해석은 드라이버가 한다(`prepareHydratedValue`) — 엔티티로 받았을 때와 **같은 값**이 나온다.
+ * 그래서 속도 때문에 원시로 받는 자리와 엔티티로 받는 자리가 서로 다른 답을 낼 수 없다.
+ *
+ * 원시로 받는 이유는 그대로 유효하다: 경계 한 줄을 찾을 때 색인만 읽으면 테이블을 열지 않는다.
+ * 잃는 것은 컬럼 변환뿐이었고, 이 함수가 그것만 되돌려 준다.
+ */
+export function hydratedDate<T extends ObjectLiteral>(repository: Repository<T>, property: keyof T & string, value: unknown): Date | null {
+  if (value === null || value === undefined) return null
+  const column = repository.metadata.findColumnWithPropertyName(property)
+  if (!column) {
+    /* 컬럼을 못 찾으면 짐작하지 않는다 — 이름이 바뀌었다는 뜻이고, 그때는 값을 지어내면 안 된다. */
+    throw new Error(`[read-time] "${repository.metadata.name}" has no column for property "${property}"`)
+  }
+  const at = repository.manager.connection.driver.prepareHydratedValue(value, column)
+  return at instanceof Date && !Number.isNaN(at.getTime()) ? at : null
+}
+
+/**
+ * **계약이 절대시각이라고 약속한** 값 → 날짜. 읽을 수 없으면 `null`.
+ *
+ * 쓰는 자리는 둘이다. 유입 봉투의 `eventTime`(정규 계약이 절대시각을 요구한다)과 우리가 만든
+ * 커서(우리가 적은 것을 우리가 읽는다). 둘 다 테이블의 컬럼이 아니므로 드라이버에게 물을 수 없다.
+ *
+ * 시간대가 적혀 있지 않으면 UTC 로 읽는다 — 계약이 절대시각을 요구하므로 지역 시간으로 읽을 근거가
+ * 없다. 「지금」으로 메우지 않는다: 옛 사건이 최근으로 보이고, 경계를 정하는 자리에서는 지우면 안
+ * 되는 것을 지운다.
+ */
+export function absoluteTime(value: unknown): Date | null {
+  if (value === null || value === undefined) return null
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value
+  if (typeof value === 'number') {
+    const at = new Date(value)
+    return Number.isNaN(at.getTime()) ? null : at
+  }
+  if (typeof value !== 'string') return null
+
+  const s = value.trim()
+  if (!s) return null
+  /* 시간대가 적혀 있으면 그 말을 믿는다 — 우리가 고쳐 붙이지 않는다. */
+  const at = new Date(HAS_ZONE.test(s) ? s : `${s.replace(' ', 'T')}Z`)
+  return Number.isNaN(at.getTime()) ? null : at
+}

package/server/engine/restart-policy.ts

@@ -16,7 +16,7 @@
  *   reset  — 저널을 비우고 씨앗부터 다시 돌린다(재현 가능한 실험).
  *
  * ── 기본값을 두지 않는다 ────────────────────────────────────────────────────
- * 예전에는 미선언이 조용히 `sim-experiment`(=저널 초기화)로 떨어졌다. 그 관용은 값이 하나 어긋나는
+ * 예전에는 미선언이 알리지 않고 `sim-experiment`(=저널 초기화)로 떨어졌다. 그 관용은 값이 하나 어긋나는
  * 순간 **저널을 지우는 길**이 된다 — 개명 뒤 옛 값이 남아 있는 행을 그 길로 읽으면 재기동 한 번에
  * 이력이 사라진다. 그래서 모르는 값은 **오류를 낸다.** 부르는 쪽이 선언하게 만드는 것이 이 축의 요점이다.
  */

package/server/engine/runtime-key.ts

@@ -25,7 +25,7 @@
  * `${domainId}:${instanceId}` — 이 저장소가 이미 쓰는 모양이다(`structureRevCache`·`measuredCache`).
  * 새 모양을 만들지 않는다. 파싱은 **첫 구분자**에서 자르므로 `instanceId` 에 `:` 가 들어 있어도
  * 안전하다(레퍼런스 소스 이름에 들어갈 수 있다). 대신 `domainId` 에 구분자가 있으면 키가 모호해지므로
- * **그때는 오류를 낸다** — 조용히 잘못된 키를 만들면 그게 곧 이 결함의 재발이다.
+ * **그때는 오류를 낸다** — 알리지 않고 잘못된 키를 만들면 그게 곧 이 결함의 재발이다.
  */
 
 /** 도메인과 인스턴스 id 를 잇는 문자 — 저장소의 기존 캐시 키와 같은 모양. */

package/server/engine/spec-coverage.ts

@@ -14,13 +14,13 @@
 export type ForecastQualification =
   /** 모든 소요가 커널 기본 상수 → **상대 비교만**("자원 2대 더 넣으면 나아지나"). 절대 시각 주장 불가. */
   | 'relative'
-  /** 일부만 선언·실측 → 그 구간은 접지, 나머지는 상수. 혼합. */
+  /** 일부만 선언·실측 → 그 구간은 계산하지, 나머지는 상수. 혼합. */
   | 'partial'
   /** 소요 전부 선언 → 절대 예측 시도 가능. 단 **정확도는 이력이 확인한다**(선언 != 검증). */
   | 'absolute-capable'
   /**
    * 소요 전부가 **이 현장의 이력에서 온 값**(추정기) → 가장 강한 근거. 선언은 사람이 적은 값이고
-   * 이것은 실제로 일어난 값이다. 그래도 "정확하다" 가 아니라 "관측에 접지됐다" 는 뜻이다.
+   * 이것은 실제로 일어난 값이다. 그래도 "정확하다" 가 아니라 "관측에 계산하지됐다" 는 뜻이다.
    */
   | 'calibrated'
 
@@ -77,7 +77,7 @@ export function classifySpecCoverage(cov: {
   const declaredDurations = cov.declaredDurations ?? operations.filter(o => o.duration === 'declared').length
   const defaultDurations = cov.defaultDurations ?? operations.filter(o => o.duration === 'default').length
   const varyingDurations = operations.filter(o => o.variability && o.variability !== 'constant').length
-  /* 사다리: 전부 이력 → calibrated · 상수 없음 → absolute-capable · 접지가 하나도 없음 → relative · 나머지 → partial. */
+  /* 사다리: 전부 이력 → calibrated · 상수 없음 → absolute-capable · 계산하지가 하나도 없음 → relative · 나머지 → partial. */
   const grounded = measuredDurations + declaredDurations
   const qualification: ForecastQualification =
     grounded === 0

package/server/engine/stage-path.ts

@@ -10,7 +10,7 @@
  * 위조할 수 없다. 특히:
  *
  *  · **반출 관측**이 라이브의 판별식이다. 스냅샷을 되풀어 읽는 방식은 **원리적으로** 반출을 낼 수 없다
- *    (사라진 것은 그냥 없어질 뿐이라 `OBSERVE` 만 남는다). 그러므로 「반출을 한 번이라도 접었는가」는
+ *    (사라진 것은 그냥 없어질 뿐이라 `OBSERVE` 만 남는다). 그러므로 「반출을 한 번이라도 계산했는가」는
  *    진짜 delta 의 증거이고, 폴링을 실시간이라 부르는 것을 막는다.
  *  · **선언 적재량**이 예측의 판별식이다. 커널 기본값으로 돌아간 예측도 숫자를 내므로, 화면만 보면
  *    구별되지 않는다. 그 숫자가 무엇 위에 섰는지는 `specCoverage` 만 안다.
@@ -36,19 +36,19 @@ export interface StageEvidence {
    * 마스터를 옮기며 **못 옮긴 값의 수**. `null` = 세지 않았다.
    *
    * 0 이면 통과이고 n 이어도 통과다 — 이 판정이 요구하는 것은 「없다」가 아니라 **「말할 수 있다」**다.
-   * 못 옮긴 값을 세지 않은 구조 인제스트는 도크를 랙으로 바꿔 놓고도 조용히 성공한다.
+   * 못 옮긴 값을 세지 않은 구조 인제스트는 도크를 랙으로 바꿔 놓고도 성공이라 답하면서 아무 일도 하지 않는다.
    */
   masterWarnings: number | null
   /**
    * 이 축이 이 트윈에 **해당하나**. 레퍼런스 없이 템플릿으로 세운 트윈에는 옮겨 온 마스터가 없으므로
-   * 「못 옮긴 값」을 물을 대상이 아니다 — 그걸 미측정으로 접으면 영원히 배선을 기다린다.
+   * 「못 옮긴 값」을 물을 대상이 아니다 — 그걸 미측정으로 처리하면 영원히 배선을 기다린다.
    */
   masterWarningsApplicable?: boolean
 
   /* ── S2 라이브 ── */
   /** 인제스트 누적 건수. */
   liveIngestTotal: number
-  /** **반출(remove)을 접은 누적 건수.** `null` = 계측되지 않음. 0 = 세었으나 없었다(→ 스냅샷 의심). */
+  /** **반출(remove)을 계산한 누적 건수.** `null` = 계측되지 않음. 0 = 세었으나 없었다(→ 스냅샷 의심). */
   removalsObserved: number | null
 
   /* ── S3 예측 ── */
@@ -62,7 +62,7 @@ export interface StageEvidence {
    * 이 트윈이 **무엇인가** — 시뮬레이션은 원천에서 받는 것이 없다.
    *
    * 시뮬에 라이브를 요구하면 영원히 빨갛고, 그 빨강은 결함이 아니다. 도입 단계는 **연결된 트윈**의
-   * 축이므로 시뮬은 라이브 이후를 「해당 없음」으로 말한다(달성으로도, 미측정으로도 접지 않는다).
+   * 축이므로 시뮬은 라이브 이후를 「해당 없음」으로 말한다(달성으로도, 미측정으로도 계산하지 않는다).
    */
   subject?: 'live' | 'sim'
   /** 피드 성격 — `snapshot-poll` 이면 반출 0 은 「아직」이 아니라 **구조적으로 불가**다. */

package/server/engine/state-axes.ts

@@ -14,7 +14,7 @@
  * `twinMapState` 같은 화면 전용 질의를 만들지 않는다. 호출부가 **필요한 축을 말하고** 서버가 자른다 —
  * 새 화면이 생길 때마다 질의가 늘지 않고, 어휘도 화면 이름이 아니라 상태의 축이다(무방언).
  *
- * 모르는 축 이름은 **조용히 버리지 않고 무시하되 그 사실을 돌려준다** — 오타 하나로 화면이 빈
+ * 모르는 축 이름은 **알리지 않고 버리지 않고 무시하되 그 사실을 돌려준다** — 오타 하나로 화면이 빈
  * 채로 뜨는 것이 가장 나쁘다.
  */
 
@@ -41,7 +41,7 @@ export interface PickedAxes {
  * 요청한 축만 남긴다.
  *
  * `axes` 가 비어 있으면 **자르지 않는다** — 기본값이 "전부" 여야 기존 호출부가 그대로 동작한다
- * (자르는 쪽이 기본이면 축을 말하지 않은 화면이 조용히 비어 버린다).
+ * (자르는 쪽이 기본이면 축을 말하지 않은 화면이 알리지 않고 비어 버린다).
  */
 export function pickAxes(state: any, axes: readonly string[] | undefined | null): PickedAxes {
   if (!state || typeof state !== 'object') return { state, unknown: [] }

package/server/engine/travel-estimator.ts

@@ -20,7 +20,7 @@ import type { MeasuredEstimate } from './measured-estimator.js'
  * UN/CEFACT 권고 20 공통코드 → m/s 변환. 모르는 코드는 변환하지 않는다(발명 금지).
  *
  * **내보내는 이유**: 선언 화면·AI 가 「어떤 단위를 받나」를 말해야 하고, 그 목록이 두 곳에 적히면
- * 화면이 받아 준 단위를 추정기가 모르는 일이 생긴다(그때 공정 시간이 조용히 사라진다).
+ * 화면이 받아 준 단위를 추정기가 모르는 일이 생긴다(그때 공정 시간이 오류 없이 사라진다).
  */
 export const SPEED_TO_MPS: Record<string, number> = {
   MTS: 1, // metre per second
@@ -59,7 +59,7 @@ export interface TravelEstimatorInput {
 
 export interface TravelEstimatorResult {
   estimator?: { estimate(ctx: DurationCtx): number | undefined }
-  /** 왜 못 만들었나(만들었으면 비어 있음) — 조용히 없는 상태로 두지 않는다. */
+  /** 왜 못 만들었나(만들었으면 비어 있음) — 알리지 않고 없는 상태로 두지 않는다. */
   reasons: string[]
   /** 속도를 읽어낸 자원 종류들 — 무엇이 계산 대상인지 드러낸다. */
   speedsByKind: Record<string, number>