@things-factory/headless-twin 10.0.15 → 10.0.18

package/server/engine/local-declarations.ts

@@ -25,7 +25,7 @@
  *
  * ── 왜 모델에 바로 쓰지 않고 겹으로 두나 ────────────────────────────────────
  * 모델은 **원천의 사본**이다. 다시 읽기(resync)는 그 사본을 새로 그리므로, 모델에 직접 쓴 값은 다음
- * 다시 읽기에서 **조용히 사라진다** — 요금이 사라지면 금액도 사라지고, 사용자는 이유를 알 수 없다.
+ * 다시 읽기에서 **오류 없이 사라진다** — 요금이 사라지면 금액도 사라지고, 사용자는 이유를 알 수 없다.
  * 그래서 로컬 선언은 따로 보관하고, 모델을 그릴 때마다 그 위에 얹는다. 덤으로 「누가 말한 값인가」에
  * 답할 수 있다 — 이 시스템이 근거를 값과 함께 다니게 하는 규율과 같다(`basis`·`derived` 와 한 결).
  *
@@ -37,7 +37,8 @@
  * **속성 어휘는 사용자가 정의하지 않는다** — 커널이 정한 속성에 값을 넣는 문이다(그래서 이름도
  * 「사용자 정의 속성」이 아니다).
  */
-import { ATTENTION_PROPERTY, EMS_PROPERTY_SPEC, OPERATION_PROPERTY, OP_PARAM } from '@operato/twin-kernel'
+import { ATTENTION_PROPERTY, OPERATION_PROPERTY } from '@operato/twin-kernel'
+import { EMS_PROPERTY_SPEC, OP_PARAM } from '@operato/ops-contract'
 
 import { EQUIPMENT_PROPERTY, SPEED_TO_MPS } from './travel-estimator.ts'
 import { declarationTargetsOf } from './property-effects.ts'
@@ -56,7 +57,7 @@ export interface LocalDeclaration {
     /**
      * 단위(UN/CEFACT 코드) — **어떤 값은 단위 없이는 뜻이 없다.**
      *
-     * 속도가 그렇다: 단위가 없으면 이동 시간 추정기가 그 설비를 **거절한다**(그러면 공정 시간이 조용히
+     * 속도가 그렇다: 단위가 없으면 이동 시간 추정기가 그 설비를 **거절한다**(그러면 공정 시간이 알리지 않고
      * 사라진다). 명세가 단위를 요구하면(`uomChoices`) 받고, 그 목록에 없는 코드는 거절한다 — 읽는 쪽이
      * 모르는 단위를 받아 두면 화면은 넣었다고 말하고 계산은 그 값을 버린다.
      */
@@ -120,7 +121,7 @@ export interface RejectedDeclaration {
      * 그 이름의 공정을 이 트윈에서 확인할 수 없다 — 커널이 돌린 적도 없고 명세 행에도 없다.
      *
      * 공정 선언은 자리·설비와 달리 **모델에 행이 없어도 성립한다**(창고·야드에는 행이 아예 없다).
-     * 그래서 오타를 잡아 줄 것이 이름 대조뿐이다 — 그마저 없으면 값은 조용히 아무 일도 하지 않는다.
+     * 그래서 오타를 잡아 줄 것이 이름 대조뿐이다 — 그마저 없으면 값은 알리지 않고 아무 일도 하지 않는다.
      */
     | 'unknown-operation'
   /** 무엇을 기대했나 — 사람이 고칠 수 있게(명세의 문장). */
@@ -199,7 +200,7 @@ const COMMON_SPECS: DeclarablePropertySpec[] = [
    *
    * 혼잡 90%·불량 15%는 우리가 정한 수였다. 통로를 95%로 채워 쓰는 창고는 그 기준에서 영구히 「병목」
    * 이고, 초기 라인은 계속 「불량 과다」로 운다 — 그때 진짜 경보도 함께 묻힌다. 선언이 없으면 기본값을
-   * 쓰되 주의가 `basis: 'default'` 로 그 사실을 밝힌다(조용히 기본값을 진실로 두지 않는다).
+   * 쓰되 주의가 `basis: 'default'` 로 그 사실을 밝힌다(알리지 않고 기본값을 진실로 두지 않는다).
    */
   {
     id: ATTENTION_PROPERTY.congestionRatio,
@@ -276,7 +277,7 @@ const COMMON_SPECS: DeclarablePropertySpec[] = [
  * 공정 모수 표에 한 칸 담는다 — **커널이 읽는 표기 그대로**(수율 0..1, 셋업 ISO 8601).
  *
  * 표를 통째로 새로 만들어 얹는다: 같은 모델 객체를 여러 겹이 지나므로(현장 → 트윈) 그때마다 새 객체여야
- * 앞 겹의 것을 조용히 덮어쓰지 않는다.
+ * 앞 겹의 것을 알리지 않고 덮어쓰지 않는다.
  */
 function putParam(next: any, kind: string, paramId: string, value: string): void {
   const table = { ...(next.localParams ?? {}) }
@@ -321,7 +322,7 @@ export function declarablePropertySpecs(kind: string | undefined): DeclarablePro
 /**
  * 로컬 선언을 검사한다 — **받은 것과 받지 않은 것을 함께** 돌려준다.
  *
- * 조용히 걸러내지 않는 이유: 사용자는 값을 넣었다고 믿는다. 무엇이 왜 빠졌는지 말해야 고칠 수 있다.
+ * 알리지 않고 걸러내지 않는 이유: 사용자는 값을 넣었다고 믿는다. 무엇이 왜 빠졌는지 말해야 고칠 수 있다.
  */
 export function validateLocalDeclarations(
   kind: string | undefined,
@@ -342,7 +343,7 @@ export function validateLocalDeclarations(
     const target: DeclarationTarget = d?.target === 'equipment' ? 'equipment' : d?.target === 'operation' ? 'operation' : 'location'
     const id = String(d?.id ?? '').trim()
     if (!id) {
-      /* 어느 대상인지 모르면 얹을 자리가 없다 — 그 사실을 말한다(조용히 버리지 않는다). */
+      /* 어느 대상인지 모르면 얹을 자리가 없다 — 그 사실을 말한다(알리지 않고 버리지 않는다). */
       rejected.push({ target, id: '', propertyId: '', reason: 'no-target-id' })
       continue
     }
@@ -449,7 +450,7 @@ export function mergeLocalDeclarations(
  * 고쳐 넣었다는 것은 「원천의 값이 낡았다」는 뜻이다. 다만 그 사실이 보여야 하므로 `source: 'local'` 를
  * 값에 붙인다 — 화면·감사가 「누가 말한 값인가」를 되짚을 수 있다.
  *
- * 모델에 없는 대상에 얹으려 하면 **조용히 버리지 않고** 그 사실을 돌려준다(구조가 바뀌어 그 설비가
+ * 모델에 없는 대상에 얹으려 하면 **알리지 않고 버리지 않고** 그 사실을 돌려준다(구조가 바뀌어 그 설비가
  * 사라졌을 수 있고, 그때 사용자의 선언은 갈 곳이 없다).
  */
 export function applyLocalDeclarations<
@@ -461,7 +462,7 @@ export function applyLocalDeclarations<
   model: T
   missingTargets: { target: string; id: string }[]
   /**
-   * 읽을 수 있는 값으로 바꿀 수 없었던 선언 — **조용히 버리지 않기 위한 자리.**
+   * 읽을 수 있는 값으로 바꿀 수 없었던 선언 — **알리지 않고 버리지 않기 위한 자리.**
    *
    * 지금은 공정 시간에서만 난다(단위가 없거나 수가 아니면 ISO 8601 기간을 만들 수 없다). 문에서 이미
    * 검사하므로 정상 경로에서는 비어 있고, 옛 겹이나 손으로 넣은 데이터에서 드러난다.
@@ -504,7 +505,7 @@ export function applyLocalDeclarations<
        *
        * 겹에는 단위를 담고도 모델에 얹을 때 떨어뜨리고 있었다 — 그러면 속도를 넣어도 이동 시간 추정기가
        * 그 설비를 **버린다**(「speed has no unit of measure」). 화면은 「넣었습니다」라고 말하고 계산은
-       * 그 값을 못 쓰는, 가장 조용한 종류의 결함이다.
+       * 그 값을 못 쓰는, 가장 들어온 것이 없는 종류의 결함이다.
        */
       const next = { id: p.id, value: String(p.value), ...((p as any).uom ? { uom: String((p as any).uom) } : {}), source: 'local' as const }
       if (at >= 0) props[at] = { ...props[at], ...next }
@@ -531,7 +532,7 @@ export function applyLocalDeclarations<
       const uom = String((p as any).uom ?? '')
       /*
        * 값을 **커널이 읽는 표기로** 바꿔 담는다 — 시간은 ISO 8601, 수율은 비율(0..1).
-       * 바꿀 수 없으면 담지 않고 그 사실을 낸다(조용히 0 이나 빈 값으로 만들지 않는다).
+       * 바꿀 수 없으면 담지 않고 그 사실을 낸다(알리지 않고 0 이나 빈 값으로 만들지 않는다).
        */
       if (p.id === OPERATION_PROPERTY.duration) {
         const iso = isoDurationOf(p.value, uom)
@@ -596,7 +597,7 @@ export interface RevokedDeclaration extends DeclarationRevocation {
 /**
  * 겹에서 선언을 **뺀다** — 값을 넣는 것과 다른 결정이므로 다른 문이다.
  *
- * 없는 것을 뺐다고 말하지 않는다: 겹에 없던 대상·속성은 `notFound` 로 돌려준다(조용히 성공하면
+ * 없는 것을 뺐다고 말하지 않는다: 겹에 없던 대상·속성은 `notFound` 로 돌려준다(알리지 않고 성공하면
  * 사용자는 지웠다고 믿고 값은 그대로 남는다 — 가장 비싼 종류의 침묵이다).
  *
  * 속성이 하나도 남지 않은 대상은 겹에서 사라진다(빈 껍데기를 남기지 않는다).
@@ -750,7 +751,7 @@ export function applyDeclarationLayers<
   instanceLayerApplied: LocalDeclaration[]
   /** 갈 곳이 없던 대상 — 어느 범위에서 났는지 함께 낸다(현장 겹은 그 트윈에 없을 수 있다). */
   missingTargets: { scope: DeclarationScope; target: string; id: string }[]
-  /** 읽을 수 있는 값으로 바꿀 수 없던 선언 — 범위와 함께(조용히 버리지 않는다). */
+  /** 읽을 수 있는 값으로 바꿀 수 없던 선언 — 범위와 함께(알리지 않고 버리지 않는다). */
   unreadable: { scope: DeclarationScope; target: string; id: string; propertyId: string }[]
 } {
   const first = applyLocalDeclarations(model, spaceLayer)

package/server/engine/log.ts

@@ -46,7 +46,7 @@ export function stamp(at: Date = new Date()): string {
  * 인자 여럿을 한 줄로 — **어떤 인자도 버리지 않는다.**
  *
  * `console.error(msg, err)` 처럼 쓰던 자리가 많다. 프레임워크 로거에 그대로 넘기면 두 번째 인자는
- * meta 로 들어가 우리 형식(`message` 만 찍는다)에서 **조용히 사라진다.** 그래서 여기서 문자열로 편다.
+ * meta 로 들어가 우리 형식(`message` 만 찍는다)에서 **오류 없이 사라진다.** 그래서 여기서 문자열로 편다.
  * 오류는 스택까지 — 스택이 없으면 「어디서 났나」를 잃는다.
  */
 export function line(args: unknown[]): string {

package/server/engine/measured-estimator.ts

@@ -18,7 +18,7 @@
  *  - 표본이 적으면 쓰지 않는다(`minSamples`). 한두 건의 p50 은 그 현장의 값이 아니다.
  *  - 'unknown' 축은 쓰지 않는다 — 종류를 모르는 기록을 특정 종류의 근거로 삼을 수 없다.
  *  - 퍼짐이 성립하지 않으면(p10 ≥ p90, 또는 0) **퍼짐 없이 평균만** 넘긴다. 없는 흔들림을 만들지 않는다.
- *  - 무엇을 배웠고 무엇을 표본 부족으로 버렸는지 함께 낸다(조용히 일부만 반영하지 않는다).
+ *  - 무엇을 배웠고 무엇을 표본 부족으로 버렸는지 함께 낸다(알리지 않고 일부만 반영하지 않는다).
  */
 
 /** 커널 `DurationEstimate` 와 같은 모양(커널 타입에 의존하지 않기 위해 구조로 맞춘다). */

package/server/engine/measured-yield.ts

@@ -18,7 +18,7 @@
  *    여기서도 `good + scrap` 만 쓴다 — `tasks` 를 분모로 쓰면 이동·체류가 섞여 양품률이 낮게 나온다.
  *  - **0 도 사실이다.** 전부 불량이면 0 을 배운다(그 현장이 그랬다). 「값이 없다」와 구별해 다룬다 —
  *    커널이 `0` 을 받으면 전량 불량으로 굴러가고, 그것이 관측과 같은 결론이다.
- *  - 무엇을 배웠고 무엇을 표본 부족으로 버렸는지 함께 낸다(조용히 일부만 반영하지 않는다).
+ *  - 무엇을 배웠고 무엇을 표본 부족으로 버렸는지 함께 낸다(알리지 않고 일부만 반영하지 않는다).
  */
 
 /** 커널 `YieldEstimator` 와 같은 모양(커널 타입에 의존하지 않기 위해 구조로 맞춘다). */

package/server/engine/model-basis.ts

@@ -7,7 +7,7 @@
  * 주면 **이중 보정**이 되어 정확도가 나빠진다. 학습 시점의 accAfter 도 더는 유효하지 않다.
  *
  * 그래서 보정 기록에 **그때 모델의 근거**를 함께 남기고, 적용 전에 지금 근거와 비교한다. 달라졌으면
- * 적용하지 않고 **그 사실을 응답에 싣는다**(조용히 사라지면 사용자는 학습이 왜 안 듣는지 모른다).
+ * 적용하지 않고 **그 사실을 응답에 싣는다**(오류 없이 사라지면 사용자는 학습이 왜 안 듣는지 모른다).
  *
  * 비교는 **상대 허용오차**로 한다(양자화 지문이 아니라). 실측 p50 은 새 기록이 쌓일 때마다 1~2초씩
  * 흔들리는데, 값을 버킷으로 합쳐 비교하면 버킷 경계에 걸린 값이 1초 드리프트로도 달라져 버린다 —
@@ -40,7 +40,7 @@ export interface ModelBasis {
    * 선언된 공정 — key + ISO 8601 원문(문자열은 그대로 비교한다: 선언이 바뀌면 다른 모델).
    *
    * **변동폭도 지문에 든다.** 변동폭이 허용오차를 정하므로(§toleranceOf), 그것이 바뀌었는데 "같은 모델"
-   * 이라고 하면 판정의 잣대가 조용히 바뀐 채로 학습이 이어진다.
+   * 이라고 하면 판정의 잣대가 알리지 않고 바뀐 채로 학습이 이어진다.
    */
   declared?: DeclaredOperation[]
 }

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,14 +18,14 @@
  *
  * ── 왜 자리마다 고치지 않나 ─────────────────────────────────────────────────
  * 저장된 모델를 읽는 자리가 **27곳**이다. 자리마다 리더를 쓰게 하면 다음에 추가되는 자리가 또 빠진다 —
- * 그리고 빠진 것은 오류가 아니라 **빈 공장**이라 조용하다. 그래서 **DB에서 읽는 순간 한 번** 정규화한다
+ * 그리고 빠진 것은 오류가 아니라 **빈 공장**이라 들어온 것이 없다. 그래서 **DB에서 읽는 순간 한 번** 정규화한다
  * (엔티티 컬럼 변환기). 그 뒤로는 코드가 세대를 알 필요가 없다.
  *
  * ── 쓰기는 건드리지 않는다 ──────────────────────────────────────────────────
  * 저장은 주는 대로 한다(새 쓰기는 이미 새 어휘다). 읽기가 정규화되므로, 저장된 옛 모델는 **다음에
  * 저장될 때 자연히 새 어휘로 옮겨간다** — 마이그레이션을 따로 실행하지 않는다.
  */
-import { readBoardLocations, readBoardEquipment } from '@operato/twin-kernel'
+import { readBoardLocations, readBoardEquipment } from '@operato/ops-contract'
 
 /** 흡수하고 **내보내지 않는** 옛 키 — 남겨 두면 소비처가 두 어휘를 다시 보게 된다. */
 const RETIRED_KEYS = ['nodes', 'movers', 'equipmentList'] as const // vocabulary-guard: allow — 옛 어휘를 흡수하는 것이 이 코드의 일이다(세대 이름을 적어야 흡수할 수 있다)

package/server/engine/oee-accumulator.ts

@@ -10,8 +10,10 @@
  *   - quality.output 이 없으면(예: WMS/YMS) quality=1(품질 개념 없음).
  * 시간축 = Date.parse(eventTime)(ms) — 구간 차분은 sim/실시간 무관하게 정확(고정 오프셋 상쇄).
  */
-import { computeOee } from '@operato/twin-kernel'
-import type { CanonicalEnvelope, OeeCounters, OeeMetrics } from '@operato/twin-kernel'
+/* OEE 공식은 계약에 있다 — 소비자가 셋이라(시뮬·미러·MES) 커널에 두면 밖에서 다시 쓰게 된다. */
+import { computeOee } from '@operato/ops-contract'
+import type { OeeCounters } from '@operato/ops-contract'
+import type { CanonicalEnvelope, OeeMetrics } from '@operato/ops-contract'
 
 interface Acc {
   status?: string
@@ -23,7 +25,7 @@ interface Acc {
   scrapCount: number
 }
 
-/** 누적기의 완전한 재개점 — 저장했다 되살릴 수 있어야 꼬리만 접을 수 있다. */
+/** 누적기의 완전한 재개점 — 저장했다 되살릴 수 있어야 꼬리만 계산할 수 있다. */
 export interface OeeCheckpoint {
   maxMs: number
   acc: ({ moverId: string } & Acc)[]
@@ -43,12 +45,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>