@things-factory/headless-twin 10.0.11 → 10.0.13

package/server/engine/kpi-query.ts

@@ -14,11 +14,12 @@
  * 상수를 앱에서 재현하지 않고(무방언), 라이브 트윈에서도 자연스럽다(마지막 기록 ≈ 지금).
  * 어떤 기준을 썼는지는 결과의 `window.basis` 로 밝힌다 — 숨기면 사용자가 숫자를 오해한다.
  */
+import { twinWarn } from './log.js'
 import { Between, In } from 'typeorm'
 
 import { hierarchyOf, levelOfLocationType, electricalUpstreamOf, EMS_LOCATION_TYPES, EMS_PROPERTY, type TariffDeclaration } from '@operato/twin-kernel'
 
-import { getRepository } from '@things-factory/shell'
+import { getReadRepository, getRepository } from '@things-factory/shell'
 
 import { TwinEvent } from '../service/twin-event/twin-event.js'
 import { TwinInstance } from '../service/twin-instance/twin-instance.js'
@@ -135,11 +136,11 @@ export interface TwinKpiOutput extends Omit<Partial<KpiResult>, 'window'> {
   /**
    * 무엇을 집계했나 — 공간이면 합쳐 접은 트윈 목록.
    *
-   * `realityModes` 는 **이 숫자가 무엇의 성과인지**를 말한다: mirror(실제 시스템을 반영) ·
-   * sim-world(가상 세계) · sim-experiment(실험 사본). 같은 "345건" 이 현실의 실적일 수도, 시뮬레이션의
+   * `restartPolicies` 는 **이 숫자가 무엇의 성과인지**를 말한다: mirror(실제 시스템을 반영) ·
+   * `resume`(이어지는 가상 세계) · `reset`(재현 실험 사본). 같은 "345건" 이 현실의 실적일 수도, 시뮬레이션의
    * 산출일 수도 있다 — 그 구별 없이 숫자만 보여주면 사용자가 시뮬 결과를 실적으로 착각한다.
    */
-  scope: { spaceId?: string; instanceIds: string[]; realityModes: string[] }
+  scope: { spaceId?: string; instanceIds: string[]; restartPolicies: string[] }
   /** 구간별 값(요청했을 때만) — 추세를 그리기 위한 최소 정보. */
   buckets?: { fromTime: string; toTime: string; tasks: number; orders: number; workP50Ms: number }[]
   /**
@@ -283,7 +284,7 @@ async function locationAreaMap(
     for (const row of rows) {
       const locations = (((row.model as any)?.locations ?? []) as any[]).filter(n => n?.id)
       if (!locations.length) continue
-      /* 순환은 hierarchyOf 가 던진다 — 한 트윈의 잘못된 계층이 다른 트윈의 집계까지 죽이지 않게 여기서 가둔다. */
+      /* 순환은 hierarchyOf 가 오류를 낸다 — 한 트윈의 잘못된 계층이 다른 트윈의 집계까지 죽이지 않게 여기서 가둔다. */
       let h
       try {
         /*
@@ -293,7 +294,7 @@ async function locationAreaMap(
          */
         h = hierarchyOf({ locations }, t => levelOfLocationType(t, row.kind))
       } catch (e: any) {
-        console.warn(`[twin-kpi] "${row.instanceId}": location hierarchy is broken — area rollup skipped for this twin: ${e?.message}`)
+        twinWarn(`[twin-kpi] "${row.instanceId}": location hierarchy is broken — area rollup skipped for this twin: ${e?.message}`)
         continue
       }
       for (const n of locations) {
@@ -483,22 +484,110 @@ async function latestEventTime(domainId: string, instanceIds: string[]): Promise
  */
 async function fetchEvents(domainId: string, instanceIds: string[], fromMs: number, toMs: number, lookbackMs: number) {
   if (instanceIds.length === 0) return { events: [] as KpiEvent[], capped: false }
-  const rows = await getRepository(TwinEvent).find({
-    where: {
-      domain: { id: domainId },
-      instanceId: In(instanceIds),
-      eventType: In(BUSINESS_EVENTS),
-      eventTime: Between(new Date(fromMs - lookbackMs), new Date(toMs))
-    },
-    order: { revision: 'ASC' },
-    take: MAX_EVENTS
-  })
+  /*
+   * ── 필요한 세 컬럼만, 그리고 **읽기 연결로** (2026-08-22 실측) ─────────────
+   * 이 읽기가 서버를 붙잡고 있었다. 실측(개발 DB 16.3GB · 저널 1,134만 행): 2만 행을 실어 오는 동안
+   * 다른 가벼운 읽기가 **47.6초** 기다렸다. 로그에서 이 자리 뒤로 사용자·도메인 조회까지 30.9초로
+   * 찍혔다 — TypeORM sqlite 드라이버는 연결을 하나만 들기 때문이다.
+   *
+   * **행 단위로 읽는 것 자체는 정당하다**: 이 폴드는 `p10·p50·p90` 을 낸다(§`kpi-fold`). 분위수는
+   * 카운터로 만들 수 없고 트윈별 사전집계로도 만들 수 없다(p90 의 평균은 p90 이 아니다). 개별 값이
+   * 있어야 한다.
+   *
+   * 정당하지 않은 것은 **읽는 방식**이었다. 세 가지를 고친다.
+   *
+   *  ① **엔티티를 만들지 않는다.** 폴드가 쓰는 것은 `eventType`·`eventTime`·`payload` 뿐인데
+   *     `find()` 는 열여섯 컬럼을 실어 엔티티로 만들고 관계 로더를 지난다. CPU 프로파일에서
+   *     `RawSqlResultsToEntityTransformer` 와 `stringToSimpleJson` 이 상위였다.
+   *  ② **읽기 연결로 보낸다**(`getReadRepository`). 순수 읽기이므로 쓰기와 순서를 다툴 것이 없다.
+   *     실측: 같은 2만 행 읽기에서 다른 읽기의 대기가 47.6초 → 2.8초.
+   *  ③ **정렬 축을 거르는 축과 맞춘다.** 여기가 이 자리의 진짜 비용이었다.
+   *
+   * ── `ORDER BY revision` 이 `LIMIT` 을 무력화했다 (실측) ────────────────────
+   * 거르는 축은 `event_time`(창)이고 정렬 축은 `revision` 이었다. 그러면 sqlite 는 창에 맞는 행을
+   * **전부** 찾아 `revision` 으로 **전부 정렬한 뒤** 상한을 적용한다 — 상한이 정렬 뒤에 걸리므로
+   * 아무것도 줄여 주지 않는다. 실측이 그것을 그대로 보였다(인스턴스 하나가 375만 행):
+   *
+   *   ORDER BY revision            LIMIT 20000 → 32.2초 · LIMIT 5000 → 28.3초 · LIMIT 2000 → 28.2초
+   *   ORDER BY eventTime, revision LIMIT 20000 →  0.41초                                     (78배)
+   *
+   * 계획도 그렇게 말한다: 앞은 `USE TEMP B-TREE FOR ORDER BY`(전체 정렬), 뒤는
+   * `USE TEMP B-TREE FOR LAST TERM OF ORDER BY` — 시각은 인덱스(`ix_twin_event_1`)에서 순서대로
+   * 나오고 **동시각만** 임시 정렬한다. 즉 범위를 훑다가 상한에서 멈춘다.
+   *
+   * ── 순서의 뜻은 **완전히 같지는 않다** (측정해서 고친 문장) ────────────────
+   * 처음에 「순서의 뜻은 같다」고 적었다. 재 보니 아니었다 — `revision` 순서와 `eventTime` 순서가
+   * 어긋나는 자리가 실재한다(hatio-mx2: 426만 행 중 **7건** · rosarito-mes: 11만 중 8건). 미러는
+   * 원본의 시각을 싣고 도착 순서로 리비전을 받으므로, 늦게 도착한 사건이 그 어긋남을 만든다.
+   *
+   * **그러나 폴드의 수치는 같다.** `foldTaskRecords`(커널 `task-fold.ts`)가 스트림 위치가 아니라
+   * **시각으로** 판정한다:
+   *
+   *   startedMs   = Math.min(startedMs, at)
+   *   completedMs = Math.max(completedMs, at)
+   *
+   * `min`·`max` 이므로 행이 어떤 순서로 와도 답이 같다. 소요시간·분위수·처리량은 순서와 무관하다.
+   *
+   * 순서에 민감한 자리는 **하나**다: 그 폴드의 `location` 이 「마지막에 본 것」이다. 같은 밀리초에 같은
+   * 작업의 자리가 두 번 바뀌면 어느 것이 남는지가 순서로 갈린다(라이브 미러가 같은 밀리초에 여러 행을
+   * 보내는 경우다). 수치가 아니라 **표시되는 자리 하나**이고, 그래서 이 바꿈의 값이 그 위험보다 크다.
+   *
+   * `revision` 을 둘째 축으로 남기는 이유도 그것이다 — 동시각의 순서가 실행마다 달라지지 않게 한다.
+   *
+   * **상한을 낮추는 것으로는 고쳐지지 않는다**(위 숫자가 그것을 말한다). 정렬 축이 원인이다.
+   *
+   * 남는 비용을 감추지 않는다: `payload` 파싱은 여전히 메인 스레드 일이고 연결을 나눠도 나뉘지 않는다
+   * (실측 평균 1.5초). 그것을 더 줄이려면 폴드가 payload 에서 무엇을 쓰는지 좁혀야 한다 — 별 건이다.
+   */
+  const raw = await getReadRepository(TwinEvent)
+    .createQueryBuilder('e')
+    .select(['e.eventType AS "eventType"', 'e.eventTime AS "eventTime"', 'e.payload AS "payload"'])
+    .where('e.domain = :domainId', { domainId })
+    .andWhere('e.instanceId IN (:...instanceIds)', { instanceIds })
+    .andWhere('e.eventType IN (:...types)', { types: BUSINESS_EVENTS })
+    .andWhere('e.eventTime BETWEEN :from AND :to', { from: new Date(fromMs - lookbackMs), to: new Date(toMs) })
+    .orderBy('e.eventTime', 'ASC')
+    .addOrderBy('e.revision', 'ASC')
+    .limit(MAX_EVENTS)
+    .getRawMany<{ eventType: string; eventTime: unknown; payload: unknown }>()
+
   /* 상한에 정확히 닿으면 **더 있었을 수 있다** — 그 사실을 돌려준다. 조용히 잘라내면 숫자가 조용히
    * 작아지고, 사용자는 그것을 성과 하락으로 읽는다(가장 나쁜 종류의 거짓이다). */
   return {
     /* 폴드는 ISO 문자열 축으로 수행된다(kpi-fold) — 경계에서 한 번만 옮긴다. */
-    events: rows.map(r => ({ eventType: r.eventType, eventTime: r.eventTime?.toISOString(), payload: r.payload })),
-    capped: rows.length >= MAX_EVENTS
+    events: raw.map(r => ({ eventType: r.eventType, eventTime: isoOf(r.eventTime), payload: jsonOf(r.payload) })),
+    capped: raw.length >= MAX_EVENTS
+  }
+}
+
+/**
+ * 원시 결과의 시각을 ISO 로 — **드라이버마다 모양이 다르다.**
+ *
+ * 엔티티 경로에서는 TypeORM 이 `Date` 로 바꿔 주지만, 원시 결과는 드라이버가 준 그대로다(sqlite 는
+ * `'2026-08-07 11:00:00.000'`, pg 는 `Date`). 경계에서 한 번 정규화한다 — 폴드는 ISO 문자열만 안다.
+ */
+function isoOf(v: unknown): string | undefined {
+  if (v == null) return undefined
+  if (v instanceof Date) return v.toISOString()
+  const s = String(v)
+  /* sqlite 의 공백 구분 형식을 ISO 로 — 그대로 `Date` 에 주면 시간대 해석이 갈린다. */
+  const d = new Date(s.includes('T') ? s : s.replace(' ', 'T') + (s.endsWith('Z') ? '' : 'Z'))
+  return Number.isNaN(d.getTime()) ? undefined : d.toISOString()
+}
+
+/**
+ * 원시 결과의 `payload` 를 객체로 — **엔티티 경로의 `simple-json` 변환을 여기서 한다.**
+ *
+ * 깨진 JSON 은 **버리지 않고 비운다**: 그 사건이 있었다는 사실은 남고, 안을 읽을 수 없다는 것만
+ * 폴드에 전해진다(폴드는 없는 필드를 건너뛴다). 던지면 창 하나가 통째로 사라진다.
+ */
+function jsonOf(v: unknown): any {
+  if (v == null) return undefined
+  if (typeof v !== 'string') return v
+  try {
+    return JSON.parse(v)
+  } catch {
+    return undefined
   }
 }
 
@@ -508,7 +597,7 @@ async function fetchEvents(domainId: string, instanceIds: string[], fromMs: numb
  * 공간이 주어지면 **가동 중이고 운영 목적인** 것만 모은다 — 벤치 사본은 사용자가 보는 현장이 아니다.
  * 트윈이 지정되면 그것 하나. 둘 다 없으면 무엇을 재야 할지 알 수 없으므로 명시 실패한다.
  */
-async function resolveTargets(input: TwinKpiInput): Promise<{ instanceIds: string[]; realityModes: string[] }> {
+async function resolveTargets(input: TwinKpiInput): Promise<{ instanceIds: string[]; restartPolicies: string[] }> {
   if (!input.instanceId && !input.spaceId) throw new Error('either instanceId or spaceId is required')
   const list = await TwinEngine.list(input.domainId)
   const rows = input.instanceId
@@ -517,8 +606,8 @@ async function resolveTargets(input: TwinKpiInput): Promise<{ instanceIds: strin
   /* 목록에서 못 찾아도(정지·비등록) 지정된 트윈은 그대로 조회한다 — 저널은 남아 있을 수 있다. */
   const instanceIds = rows.length ? rows.map((x: any) => x.instanceId as string) : input.instanceId ? [input.instanceId] : []
   /* 컬럼이 NOT NULL 이라 'unknown' 으로 메울 일이 없다 — 비면 계약이 깨진 것이지 모르는 상태가 아니다. */
-  const realityModes = [...new Set(rows.map((x: any) => String(x.realityMode)))]
-  return { instanceIds, realityModes }
+  const restartPolicies = [...new Set(rows.map((x: any) => String(x.restartPolicy)))]
+  return { instanceIds, restartPolicies }
 }
 
 /**
@@ -541,8 +630,8 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
   const minutes = Math.max(1, Math.min(24 * 60, Number(input.windowMinutes) || 60))
   const lookbackMs = Math.max(0, Math.min(24 * 60, input.lookbackMinutes ?? 60)) * 60_000
 
-  const { instanceIds, realityModes } = await resolveTargets(input)
-  const scope = { spaceId: input.spaceId, instanceIds, realityModes }
+  const { instanceIds, restartPolicies } = await resolveTargets(input)
+  const scope = { spaceId: input.spaceId, instanceIds, restartPolicies }
 
   /* 끝 시각 — 지정이 없으면 대상들의 마지막 기록. 그것도 없으면 측정할 것이 없다. */
   let basis: 'given' | 'latest-event' = 'given'
@@ -597,6 +686,31 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
     ...shiftCtx,
     groupLimit: input.groupLimit
   })
+  /*
+   * **완료로 세지 않은 오더 상태 낱말을 말한다** (2026-08-23).
+   *
+   * 폴드는 순수하다(로그를 모른다) — 그래서 부르는 쪽이 말한다. 왜 말해야 하나: 이 폴드는 오더의
+   * 완료를 **동의어 목록**으로 판정하고, 그것은 원본의 낱말에서 뜻을 추론하는 것이다. 커넥터가
+   * 자기 표로 옮기지 않으면 그 낱말이 목록에 없어 **완료가 조용히 0 으로 세어진다.**
+   *
+   * 실제로 그랬다: 첫 실 원본의 `FINISHED` 가 목록에 없어 완료 오더가 전부 0 이었고, 사람이 화면을
+   * 보고 의심해서야 드러났다(그 커넥터에는 상태 표가 정의돼 **있으면서** 오더 경로에서 쓰이지 않았다).
+   * 그때 목록에 낱말을 더한 것은 그 사실을 가린 땜빵이었다.
+   *
+   * 그러니 이 로그는 「목록을 늘려라」가 아니라 **「그 커넥터가 옮기지 않았다」**를 뜻한다. 화면을 보지
+   * 않는 사람도 알아야 하므로 로그에 남긴다 — 조용한 0 이 이 시스템에서 가장 비싼 침묵이다.
+   *
+   * 완료가 하나도 없을 때만 말한다: `picking` 처럼 완료가 아닌 낱말이 섞여 있는 것은 정상이고,
+   * 그것까지 매번 경고하면 진짜 신호가 묻힌다.
+   */
+  const notCounted = Object.entries(kpi.orderStatusNotCounted ?? {})
+  if (notCounted.length && kpi.throughput.orders === 0) {
+    twinWarn(
+      `[twin-kpi] no order counted as completed in this window, but these order status words were seen: ` +
+        `${notCounted.map(([w, n]) => `${w}×${n}`).join(' · ')} — the connector may not be translating them ` +
+        `to the kernel's vocabulary (see its own status table).`
+    )
+  }
   /*
    * 목표를 **폴드 뒤, 그룹 조립 앞**에 읽는다 — 전체 판정과 축별 판정이 같은 목록에서 나와야
    * 두 곳의 임계가 갈라지지 않는다. 폴드 자체는 목표를 모른다(사실 층과 판정 층의 분리).

package/server/engine/live-feed-registry.ts

@@ -1,3 +1,4 @@
+import { twinWarn } from './log.js'
 /*
  * 「이 트윈에 계측이 들어오고 있나」 — **그 사실을 한 자리에서 묻는다.**
  *
@@ -35,7 +36,7 @@ export function liveFeedAttached(instanceId: string): boolean {
     try {
       if (probe().includes(instanceId)) return true
     } catch (e: any) {
-      console.warn('[twin-live] a feed registry could not answer —', e?.message ?? e)
+      twinWarn('[twin-live] a feed registry could not answer —', e?.message ?? e)
     }
   }
   return false
@@ -51,8 +52,8 @@ export function liveFeedAttached(instanceId: string): boolean {
  */
 export type LiveFeedState = 'attached' | 'detached' | 'not-applicable'
 
-export function liveFeedStateOf(args: { realityMode?: string; running?: boolean; instanceId: string }): LiveFeedState {
-  if (args.realityMode !== 'mirror') return 'not-applicable'
+export function liveFeedStateOf(args: { restartPolicy?: string; running?: boolean; instanceId: string }): LiveFeedState {
+  if (args.restartPolicy !== 'resync') return 'not-applicable'
   if (!args.running) return 'not-applicable'
   return liveFeedAttached(args.instanceId) ? 'attached' : 'detached'
 }

package/server/engine/load-meter.ts

@@ -8,11 +8,11 @@
  *
  * 실제로 그런 상태를 만났다: 포트는 LISTEN 이고 webpack 은 `compiled successfully` 인데 요청이 하나도
  * 처리되지 않고 CPU 만 99% 였다. **터지면 알지만 느려지면 몰랐다** — `tickGuarded` 는 예외만 잡고
- * 시간은 재지 않았고, `TwinMetrics` 에는 라이브 지표(유입·방송·저널)뿐이라 시뮬 틱은 아무도 안 봤다.
+ * 시간은 재지 않았고, `TwinMetrics` 에는 라이브 지표(유입·브로드캐스팅·저널)뿐이라 시뮬 틱은 아무도 안 봤다.
  *
  * ── 총량만으로는 부족하다 ─────────────────────────────────────────────────
  * "틱이 800ms 걸렸다" 는 어디를 고칠지 알려 주지 않는다. 한 주기는 여러 작업으로 이뤄진다 —
- * 커널 틱 · 상태 투영(snapshot) · 방송 payload 만들기 · 발행 · 저널 기록 · 유입 흡수. 그래서
+ * 커널 틱 · 상태 투영(snapshot) · 브로드캐스팅 payload 만들기 · 발행 · 저널 기록 · 유입 흡수. 그래서
  * **작업마다 따로** 잰다. 어느 작업이 총 시간의 몇 %인지 보이면 손댈 곳이 정해진다.
  *
  * 재고 말하는 것이 먼저다. 워커 스레드로 옮기는 것은 그다음이다 — 무엇이 느린지 모른 채 옮기면
@@ -20,7 +20,16 @@
  */
 
 /** 작업 이름 — 새 작업을 재기 시작하면 여기 늘린다(문자열을 자유롭게 쓰지 않는다: 오타가 새 칸이 된다). */
-export const LOAD_PHASES = ['tick', 'snapshot', 'deltas', 'publish', 'journal', 'ingest', 'forecast', 'forkTick'] as const
+/*
+ * ── 부팅 구간을 재는 두 이름 (2026-08-22) ───────────────────────────────────
+ * 실측으로 부팅이 620~717초였고 트윈 하나를 세우는 데 15~93초였다. 그런데 **어느 작업이 그 시간을
+ * 쓰는지 아무 계기도 답하지 못했다** — 재는 이름이 도는 중의 작업(틱·브로드캐스팅·저널)뿐이었다.
+ * 짐작으로 원인을 적으면 그것이 사실로 읽히므로, 그 자리에 이름을 둔다.
+ *
+ *  · `warmStart` — 저장된 상태를 커널에 심는다(물품·오더·작업·주목 시각).
+ *  · `stimulus`  — 선언된 자극을 싣고 시작한다(실측: 큰 트윈에서 이 뒤가 29~72초였다).
+ */
+export const LOAD_PHASES = ['tick', 'snapshot', 'deltas', 'publish', 'journal', 'ingest', 'forecast', 'forkTick', 'warmStart', 'stimulus'] as const
 export type LoadPhase = (typeof LOAD_PHASES)[number]
 
 export interface PhaseStats {

package/server/engine/local-declarations.ts

@@ -37,7 +37,7 @@
  * **속성 어휘는 사용자가 정의하지 않는다** — 커널이 정한 속성에 값을 넣는 문이다(그래서 이름도
  * 「사용자 정의 속성」이 아니다).
  */
-import { ATTENTION_PROPERTY, EMS_PROPERTY_SPEC, OPERATION_PROPERTY } from '@operato/twin-kernel'
+import { ATTENTION_PROPERTY, EMS_PROPERTY_SPEC, OPERATION_PROPERTY, OP_PARAM } from '@operato/twin-kernel'
 
 import { EQUIPMENT_PROPERTY, SPEED_TO_MPS } from './travel-estimator.ts'
 import { declarationTargetsOf } from './property-effects.ts'
@@ -241,6 +241,28 @@ const COMMON_SPECS: DeclarablePropertySpec[] = [
     range: [0.01, 100000],
     note: 'how long this operation takes at this site — the simulation and the forecast use it instead of the built-in constant. a unit is required. history still wins where it exists.',
     uomChoices: Object.keys(DURATION_UOM_MS)
+  },
+  /*
+   * 양품률 — **퍼센트로 받는다**(80 이 80%다).
+   *
+   * 커널이 읽는 값은 0..1 이지만(ISA-95 `Parameter` 값 그대로) 사람에게 0.8 을 넣으라고 하면 SOC 에서
+   * 겪은 함정을 되풀게 된다(0.8 을 0.8% 로 쓴 일이 있다). 그래서 화면·AI 는 퍼센트로 말하고, 비율로
+   * 바꾸는 일은 얹는 자리 한 곳에서 한다.
+   */
+  {
+    id: OPERATION_PROPERTY.yield,
+    uom: '%',
+    dataType: 'xs:double',
+    range: [1, 100],
+    note: 'good-output rate of this operation as a percentage 1-100 (95 means 95%) — the kernel reads it as a ratio, and this value replaces the built-in default that also drives the high-scrap attention.'
+  },
+  /* 셋업·체인지오버 — 가동 앞에 붙는 시간. 소요시간과 같은 단위 목록을 쓴다(같은 종류의 값이다). */
+  {
+    id: OPERATION_PROPERTY.setupDuration,
+    dataType: 'xs:double',
+    range: [0.01, 100000],
+    note: 'changeover time before this operation runs — added in front of the cycle. a unit is required.',
+    uomChoices: Object.keys(DURATION_UOM_MS)
   }
 ]
 
@@ -250,6 +272,18 @@ const COMMON_SPECS: DeclarablePropertySpec[] = [
  * 읽을 수 없으면 `undefined` — 부르는 쪽이 그 사실을 거절 사유로 올린다(0 을 만들지 않는다: 소요 0 인
  * 작업은 영원히 끝나지 않는다).
  */
+/**
+ * 공정 모수 표에 한 칸 담는다 — **커널이 읽는 표기 그대로**(수율 0..1, 셋업 ISO 8601).
+ *
+ * 표를 통째로 새로 만들어 얹는다: 같은 모델 객체를 여러 겹이 지나므로(현장 → 트윈) 그때마다 새 객체여야
+ * 앞 겹의 것을 조용히 덮어쓰지 않는다.
+ */
+function putParam(next: any, kind: string, paramId: string, value: string): void {
+  const table = { ...(next.localParams ?? {}) }
+  table[kind] = { ...(table[kind] ?? {}), [paramId]: value }
+  next.localParams = table
+}
+
 export function isoDurationOf(value: string | number, uom: string): string | undefined {
   const n = Number(value)
   const per = DURATION_UOM_MS[String(uom ?? '').trim()]
@@ -418,7 +452,9 @@ export function mergeLocalDeclarations(
  * 모델에 없는 대상에 얹으려 하면 **조용히 버리지 않고** 그 사실을 돌려준다(구조가 바뀌어 그 설비가
  * 사라졌을 수 있고, 그때 사용자의 선언은 갈 곳이 없다).
  */
-export function applyLocalDeclarations<T extends { locations?: any[]; equipment?: any[]; localDurations?: Record<string, string> }>(
+export function applyLocalDeclarations<
+  T extends { locations?: any[]; equipment?: any[]; localDurations?: Record<string, string>; localParams?: Record<string, Record<string, string>> }
+>(
   model: T,
   declarations: readonly LocalDeclaration[] | undefined | null
 ): {
@@ -489,20 +525,37 @@ export function applyLocalDeclarations<T extends { locations?: any[]; equipment?
    * 이 표는 **전부 우리가 정한 값**이다(원천이 그리는 자리가 아니다). 그래서 기억(`replaced`)은 언제나
    * `null` 이고, 철회는 「표에서 뺀다」로 끝난다 — 그러면 원천 명세나 커널 상수가 다시 답한다.
    */
-  const putOperation = (durations: Record<string, string>, d: LocalDeclaration, memo: LocalDeclaration): void => {
+  const putOperation = (next: any, d: LocalDeclaration, memo: LocalDeclaration): void => {
     for (let i = 0; i < d.properties.length; i++) {
       const p = d.properties[i]
-      if (p.id !== OPERATION_PROPERTY.duration) {
-        unreadable.push({ target: 'operation', id: d.id, propertyId: p.id })
+      const uom = String((p as any).uom ?? '')
+      /*
+       * 값을 **커널이 읽는 표기로** 바꿔 담는다 — 시간은 ISO 8601, 수율은 비율(0..1).
+       * 바꿀 수 없으면 담지 않고 그 사실을 낸다(조용히 0 이나 빈 값으로 만들지 않는다).
+       */
+      if (p.id === OPERATION_PROPERTY.duration) {
+        const iso = isoDurationOf(p.value, uom)
+        if (!iso) { unreadable.push({ target: 'operation', id: d.id, propertyId: p.id }); continue }
+        next.localDurations = { ...(next.localDurations ?? {}), [d.id]: iso }
+        memo.properties[i].replaced = null
         continue
       }
-      const iso = isoDurationOf(p.value, String((p as any).uom ?? ''))
-      if (!iso) {
-        unreadable.push({ target: 'operation', id: d.id, propertyId: p.id })
+      if (p.id === OPERATION_PROPERTY.setupDuration) {
+        const iso = isoDurationOf(p.value, uom)
+        if (!iso) { unreadable.push({ target: 'operation', id: d.id, propertyId: p.id }); continue }
+        putParam(next, d.id, OP_PARAM.setupDuration, iso)
+        memo.properties[i].replaced = null
         continue
       }
-      durations[d.id] = iso
-      memo.properties[i].replaced = null
+      if (p.id === OPERATION_PROPERTY.yield) {
+        const pct = Number(p.value)
+        if (!Number.isFinite(pct) || pct <= 0 || pct > 100) { unreadable.push({ target: 'operation', id: d.id, propertyId: p.id }); continue }
+        /* 퍼센트 → 비율. 이 환산이 있는 자리는 여기 하나다(두 곳에서 나누면 100 배가 두 번 걸린다). */
+        putParam(next, d.id, OP_PARAM.yield, String(pct / 100))
+        memo.properties[i].replaced = null
+        continue
+      }
+      unreadable.push({ target: 'operation', id: d.id, propertyId: p.id })
     }
   }
 
@@ -511,15 +564,15 @@ export function applyLocalDeclarations<T extends { locations?: any[]; equipment?
     ...model,
     ...(model.locations ? { locations: model.locations.map(n => ({ ...n, ...(n?.properties ? { properties: [...n.properties] } : {}) })) } : {}),
     ...(model.equipment ? { equipment: model.equipment.map(e => ({ ...e, ...(e?.properties ? { properties: [...e.properties] } : {}) })) } : {}),
-    ...(model.localDurations ? { localDurations: { ...model.localDurations } } : {})
+    ...(model.localDurations ? { localDurations: { ...model.localDurations } } : {}),
+    ...(model.localParams ? { localParams: Object.fromEntries(Object.entries(model.localParams).map(([k, v]) => [k, { ...v }])) } : {})
   }
   for (let i = 0; i < decls.length; i++) {
     const d = decls[i]
     if (d.target === 'operation') {
-      /* 빈 표를 남기지 않는다 — 「선언이 있다」와 「읽을 수 있는 선언이 하나도 없다」는 다른 사실이다. */
-      const table: Record<string, string> = next.localDurations ?? {}
-      putOperation(table, d, layer[i])
-      if (Object.keys(table).length) next.localDurations = table
+      /* 빈 표를 남기지 않는다 — 「선언이 있다」와 「읽을 수 있는 선언이 하나도 없다」는 다른 사실이다
+         (`putOperation` 이 담을 것이 있을 때만 표를 만든다). */
+      putOperation(next, d, layer[i])
       continue
     }
     const ok = put(d.target === 'equipment' ? next.equipment : next.locations, d, layer[i])
@@ -585,7 +638,9 @@ export function revokeLocalDeclarations(
  *  · 기억이 없으면(옛 선언) **손대지 않고** `unknownSource` 로 말한다 — 원래 값을 지어내는 것은
  *    잘못 넣은 값을 그대로 두는 것보다 나쁘다(다음 원천 재읽기가 그 자리를 바로잡는다).
  */
-export function restoreRevoked<T extends { locations?: any[]; equipment?: any[]; localDurations?: Record<string, string> }>(
+export function restoreRevoked<
+  T extends { locations?: any[]; equipment?: any[]; localDurations?: Record<string, string>; localParams?: Record<string, Record<string, string>> }
+>(
   model: T,
   revoked: readonly RevokedDeclaration[]
 ): { model: T; restored: RevokedDeclaration[]; unknownSource: DeclarationRevocation[]; missingTargets: { target: string; id: string }[] } {
@@ -595,7 +650,8 @@ export function restoreRevoked<T extends { locations?: any[]; equipment?: any[];
     ...model,
     ...(model.locations ? { locations: model.locations.map(n => ({ ...n, ...(n?.properties ? { properties: [...n.properties] } : {}) })) } : {}),
     ...(model.equipment ? { equipment: model.equipment.map(e => ({ ...e, ...(e?.properties ? { properties: [...e.properties] } : {}) })) } : {}),
-    ...(model.localDurations ? { localDurations: { ...model.localDurations } } : {})
+    ...(model.localDurations ? { localDurations: { ...model.localDurations } } : {}),
+    ...(model.localParams ? { localParams: Object.fromEntries(Object.entries(model.localParams).map(([k, v]) => [k, { ...v }])) } : {})
   }
   const restored: RevokedDeclaration[] = []
   const unknownSource: DeclarationRevocation[] = []
@@ -607,13 +663,33 @@ export function restoreRevoked<T extends { locations?: any[]; equipment?: any[];
      * 빼면 원천 명세(있으면)나 커널 상수가 다시 답한다: 그것이 「선언 이전」의 상태다.
      */
     if (r.target === 'operation') {
+      /* 시간은 시간 표에서, 모수(수율·셋업)는 모수 표에서 뺀다 — 담긴 자리에서 빼야 실제로 빠진다. */
+      const paramId =
+        r.propertyId === OPERATION_PROPERTY.yield
+          ? OP_PARAM.yield
+          : r.propertyId === OPERATION_PROPERTY.setupDuration
+            ? OP_PARAM.setupDuration
+            : undefined
+      if (paramId) {
+        const params: Record<string, Record<string, string>> = next.localParams ?? {}
+        if (!params[r.id] || !(paramId in params[r.id])) {
+          missingTargets.push({ target: r.target, id: r.id })
+          continue
+        }
+        delete params[r.id][paramId]
+        /* 빈 껍데기를 남기지 않는다 — 「선언이 있다」와 「빈 표가 있다」가 구별되지 않는다. */
+        if (!Object.keys(params[r.id]).length) delete params[r.id]
+        if (!Object.keys(params).length) delete next.localParams
+        else next.localParams = params
+        restored.push(r)
+        continue
+      }
       const table: Record<string, string> = next.localDurations ?? {}
       if (!(r.id in table)) {
         missingTargets.push({ target: r.target, id: r.id })
         continue
       }
       delete table[r.id]
-      /* 빈 표는 남기지 않는다 — 「선언이 있다」와 「빈 표가 있다」가 구별되지 않는다. */
       if (!Object.keys(table).length) delete next.localDurations
       else next.localDurations = table
       restored.push(r)
@@ -661,7 +737,9 @@ export type DeclarationScope = 'space' | 'instance'
  * 기억(`replaced`)은 각 겹이 **자기가 덮은 값**을 적는다: 트윈 겹의 기억은 「현장 값을 덮었다」가 되고,
  * 철회하면 현장 값으로 돌아간다(원천까지 가지 않는다). 그것이 사람이 기대하는 되돌림이다.
  */
-export function applyDeclarationLayers<T extends { locations?: any[]; equipment?: any[]; localDurations?: Record<string, string> }>(
+export function applyDeclarationLayers<
+  T extends { locations?: any[]; equipment?: any[]; localDurations?: Record<string, string>; localParams?: Record<string, Record<string, string>> }
+>(
   model: T,
   spaceLayer: readonly LocalDeclaration[] | undefined | null,
   instanceLayer: readonly LocalDeclaration[] | undefined | null

package/server/engine/log.ts

@@ -0,0 +1,72 @@
+/*
+ * 트윈 로그의 문 — **모든 줄에 시각을 찍는다.** 순수(프레임워크 의존 없음).
+ *
+ * ── 왜 필요한가 (2026-08-22) ────────────────────────────────────────────────
+ * 「서버가 왜 느린가」를 조사하면서 루프가 55초 막힌 것을 계기로 알아냈는데(`loop-lag.ts`),
+ * **그 시각에 무슨 일이 있었는지 로그에서 찾을 수 없었다.** 트윈의 로그가 `console.log` 로 나가
+ * 시각이 없었기 때문이다. 프레임워크 로그(`2026-08-22T05:54:12+09:00 info: …`)와 섞여 있어서, 어느
+ * 줄이 언제 찍혔는지 앞뒤 프레임워크 줄로 짐작해야 했다.
+ *
+ * ── 왜 프레임워크 로거를 그대로 쓰지 않나 ──────────────────────────────────
+ * 재발명을 피하려고 `@things-factory/env` 의 `logger` 를 쓰려 했는데, 실측으로 막혔다: 앱 **밖**에서는
+ * 그 로거에 전송지가 하나도 없다(설정이 앱에서 주입된다). 그래서 시험·도구에서 부르면
+ *
+ *   [winston] Attempt to write logs with no transports … {"message":"…","level":"info"}
+ *
+ * 가 나오고 **메시지 자체가 사라진다.** 트윈 엔진은 시험과 CLI 도구에서도 불려 다니므로, 그 조건에서
+ * 로그가 없어지는 것은 바꿔선 안 되는 거동이다(로그가 사라지는 것이 지금 문제의 원인이었다).
+ *
+ * 그래서 **싱크는 그대로 두고**(console) 빠진 사실 하나만 채운다 — 시각. 형식은 프레임워크와 같은
+ * 모양으로 맞춰 한 파일에서 섞여 읽히게 하고, **밀리초까지** 남긴다(계기의 값이 epoch ms 라
+ * 초 단위로는 같은 초 안의 순서를 가릴 수 없다).
+ */
+
+/** 두 자리·세 자리 0 채우기 — 형식이 흔들리면 정렬해 읽을 수 없다. */
+const p2 = (n: number) => String(n).padStart(2, '0')
+const p3 = (n: number) => String(n).padStart(3, '0')
+
+/**
+ * 지역 시각 + 오프셋 — `2026-08-22T05:54:12.345+09:00`.
+ *
+ * UTC 로 찍지 않는다: 이 로그를 읽는 사람은 현장의 시각으로 이야기하고, 프레임워크의 다른 줄도
+ * 지역 시각이다. 두 줄이 다른 기준이면 나란히 놓고 읽을 수 없다.
+ */
+export function stamp(at: Date = new Date()): string {
+  const off = -at.getTimezoneOffset()
+  const sign = off >= 0 ? '+' : '-'
+  const abs = Math.abs(off)
+  return (
+    `${at.getFullYear()}-${p2(at.getMonth() + 1)}-${p2(at.getDate())}` +
+    `T${p2(at.getHours())}:${p2(at.getMinutes())}:${p2(at.getSeconds())}.${p3(at.getMilliseconds())}` +
+    `${sign}${p2(Math.floor(abs / 60))}:${p2(abs % 60)}`
+  )
+}
+
+/**
+ * 인자 여럿을 한 줄로 — **어떤 인자도 버리지 않는다.**
+ *
+ * `console.error(msg, err)` 처럼 쓰던 자리가 많다. 프레임워크 로거에 그대로 넘기면 두 번째 인자는
+ * meta 로 들어가 우리 형식(`message` 만 찍는다)에서 **조용히 사라진다.** 그래서 여기서 문자열로 편다.
+ * 오류는 스택까지 — 스택이 없으면 「어디서 났나」를 잃는다.
+ */
+export function line(args: unknown[]): string {
+  return args
+    .map(a => {
+      if (typeof a === 'string') return a
+      if (a instanceof Error) return a.stack ?? a.message
+      if (a === undefined) return 'undefined'
+      if (a === null) return 'null'
+      try {
+        return typeof a === 'object' ? JSON.stringify(a) : String(a)
+      } catch {
+        /* 순환 참조 등 — 값을 못 적어도 **무엇이 있었다는 사실**은 남긴다. */
+        return String(a)
+      }
+    })
+    .join(' ')
+}
+
+/* 수준 표기는 프레임워크와 같은 낱말을 쓴다(`info`·`warn`·`error`) — 같은 파일에서 걸러 읽는다. */
+export const twinLog = (...args: unknown[]): void => console.log(`${stamp()} info: ${line(args)}`)
+export const twinWarn = (...args: unknown[]): void => console.warn(`${stamp()} warn: ${line(args)}`)
+export const twinError = (...args: unknown[]): void => console.error(`${stamp()} error: ${line(args)}`)