@things-factory/headless-twin 10.1.278 → 10.1.280

package/server/engine/producer-guard.ts

@@ -1,64 +0,0 @@
-/*
- * **A twin made by one producer is not rebuilt by another.** Pure.
- *
- * ── What went wrong (2026-09-24) ─────────────────────────────────────────────
- * An import's instance id is the adapter's site id (`master.source`). Importing the warehouse connection
- * `wms-miratek` with site id `miratek` — the same as the plant connection's — landed on the running plant
- * mirror `miratek`, and `ingestMaster` gave it the warehouse structure as a new revision: 16 places,
- * 23 equipment, 17 people and 14 assets gone. The row already said who made it (`origin.source` was
- * `mes-miratek`); nothing asked.
- *
- * ── The rule (chief architect ruling, 2026-09-24) ────────────────────────────
- * Compare producers by identity, not by the whole origin: a reference is kind + source, a template is
- * kind + templateId. The same import carries more or fewer fields at different call sites (siteId,
- * spaceId), and a template re-run has new params — those are the same producer re-reading its own twin.
- *
- *   both declared, same producer     allowed (resync, re-import, re-run)
- *   both declared, different         refused, naming the producer that owns it
- *   prior undeclared, incoming not   refused — nobody can say who made it; delete it first to replace it
- *   prior declared, incoming not     refused — same reason, the other way
- *   neither declared                 allowed — the demo seed re-ingesting its own twin at boot. Closes when
- *                                    the seed declares a template origin.
- */
-
-export const INSTANCE_TAKEN = 'instance-taken-by-another-source'
-
-export interface ProducerRefusal {
-  code: typeof INSTANCE_TAKEN
-  params: { instance: string; producer: string }
-  message: string
-}
-
-/** Who produced a twin, as one comparable string — or undefined when the origin says nothing usable. */
-export function producerOf(origin: unknown): string | undefined {
-  if (!origin || typeof origin !== 'object') return undefined
-  const o = origin as { kind?: unknown; source?: unknown; templateId?: unknown }
-  if (o.kind === 'reference' && typeof o.source === 'string' && o.source) return `reference:${o.source}`
-  if (o.kind === 'template' && typeof o.templateId === 'string' && o.templateId) return `template:${o.templateId}`
-  /* A kind this guard does not know is still somebody — keep it distinct rather than reading it as none. */
-  if (typeof o.kind === 'string' && o.kind) return `${o.kind}:${String(o.source ?? o.templateId ?? '')}`
-  return undefined
-}
-
-function nameOf(origin: unknown): string {
-  const o = (origin ?? {}) as { source?: unknown; templateId?: unknown }
-  return String(o.source ?? o.templateId ?? '') || 'undeclared'
-}
-
-/** null when `incoming` may rebuild the twin `prior` was made by; otherwise the refusal. */
-export function refuseOverwriteByAnotherProducer(
-  instance: string,
-  priorOrigin: unknown,
-  incomingOrigin: unknown
-): ProducerRefusal | null {
-  const had = producerOf(priorOrigin)
-  const comes = producerOf(incomingOrigin)
-  if (!had && !comes) return null
-  if (had && comes && had === comes) return null
-  const producer = had ? nameOf(priorOrigin) : 'undeclared'
-  return {
-    code: INSTANCE_TAKEN,
-    params: { instance, producer },
-    message: `twin "${instance}" was made by ${producer} — delete it first, or import this site under another id`
-  }
-}

package/server/engine/property-effects.ts

@@ -1,216 +0,0 @@
-/*
- * 자원 속성의 **효과 등록부** — 이 속성이 무엇을 바꾸나.
- *
- * ── 왜 있나 ─────────────────────────────────────────────────────────────────
- * 속성은 **열려 있다**: 템플릿·마스터가 아무 id 로나 사실을 실어 보낼 수 있고, 커널은 그것을 그대로
- * 나르고 화면은 단위와 함께 보인다(표준이 속성 어휘를 정하지 않으므로 그것이 옳다).
- *
- * 그런데 **효과는 닫혀 있다**: 값이 계산·배정·판정을 바꾸려면 그 규칙을 코드가 알아야 한다. 지금
- * 효과가 있는 것은 둘뿐이다. 문제는 그 사실이 **어디에도 드러나지 않는다**는 것이었다 — 사용자는
- * 속성을 넣으면 무언가 달라질 것으로 기대하는데, 실제로는 표에 한 줄이 늘 뿐이다.
- *
- * 그래서 이 등록부는 **지어내지 않고 드러낸다**: 읽는 코드가 있는 것만 적고, 없는 것은 "표시만 된다"
- * 고 화면이 말한다. 새 효과를 코드로 붙이는 사람은 **여기 한 줄을 더한다** — 그러지 않으면 사용자는
- * 그 효과가 있는지 알 수 없다.
- *
- * ⚠️ 이 파일은 등록부이고 판정이 아니다. 값을 실제로 읽는 곳은 각자다(아래 `readBy` 가 그 자리를
- * 가리킨다) — 여기에 계산을 옮겨 오면 규칙이 두 벌이 된다.
- */
-
-/** 효과가 있는 속성 하나. */
-export interface PropertyEffect {
-  /** 속성 id — 선언에 적히는 그 이름(`ResourceProperty.id`). */
-  id: string
-  /** 어느 축의 속성인가 — 그 축의 항목에만 이 효과를 말한다. */
-  axes: string[]
-  /** 무엇을 바꾸나 — 화면이 읽는 i18n 키(언어중립: 서버는 사람 말을 만들지 않는다). */
-  effect: string
-  /** 실제로 읽는 코드 — 지어낸 효과를 등록하지 않기 위한 표식이다(없는 자리를 가리키면 리뷰가 잡는다). */
-  readBy: string
-}
-
-export const PROPERTY_EFFECTS: PropertyEffect[] = [
-  {
-    id: 'speed',
-    axes: ['equipment'],
-    effect: 'twin.propeffect.speed',
-    readBy: 'headless-twin/server/engine/travel-estimator.ts (buildTravelEstimator)'
-  },
-  {
-    id: 'perBaseUnit',
-    axes: ['materialDefinitions'],
-    effect: 'twin.propeffect.perBaseUnit',
-    readBy: '@operato/twin-kernel conversionFactorOf'
-  },
-  /*
-   * ── 에너지 속성 (2026-08-18) ──────────────────────────────────────────────
-   *
-   * 이 값들은 **오래전부터 읽히고 있었다** — 커널이 부하·피크·배터리를 그것으로 계산하고, 호스트가
-   * 금액을 그것으로 만든다. 그런데 등록부에 없어서 화면은 그 값들에 대해 「표시만 됩니다」라고 말했다.
-   * 들어온 것이 없는 거짓말이다: 사용자는 계약전력을 넣고도 「이 값은 아무것도 바꾸지 않는다」는 문장을 읽었다.
-   *
-   * 효과를 새로 만든 것이 아니라 **있는 효과를 드러낸다.** `readBy` 는 실제로 읽는 자리를 가리킨다.
-   */
-  {
-    id: 'contract.kW',
-    axes: ['locations'],
-    effect: 'twin.propeffect.contractKW',
-    readBy: '@operato/twin-kernel EmsKernel.declaredContractKW (계약 대비 판정·초과 주의)'
-  },
-  {
-    id: 'power.ratedKW',
-    axes: ['equipment'],
-    effect: 'twin.propeffect.ratedKW',
-    readBy: '@operato/twin-kernel EmsKernel.deriveEquipmentLoad (가동 중 부하)'
-  },
-  {
-    id: 'power.standbyKW',
-    axes: ['equipment'],
-    effect: 'twin.propeffect.standbyKW',
-    readBy: '@operato/twin-kernel EmsKernel.deriveEquipmentLoad (대기 중 부하)'
-  },
-  {
-    id: 'storage.capacityKWh',
-    axes: ['equipment'],
-    effect: 'twin.propeffect.capacityKWh',
-    readBy: '@operato/twin-kernel EmsKernel (축전지 방전 가능량)'
-  },
-  {
-    id: 'dispatch.dischargeAboveKW',
-    axes: ['equipment'],
-    effect: 'twin.propeffect.dischargeAboveKW',
-    readBy: '@operato/twin-kernel EmsKernel (방전 시작 문턱)'
-  },
-  {
-    id: 'dispatch.maxDischargeKW',
-    axes: ['equipment'],
-    effect: 'twin.propeffect.maxDischargeKW',
-    readBy: '@operato/twin-kernel EmsKernel (인버터 방전 상한)'
-  },
-  {
-    id: 'dispatch.reserveSoc',
-    axes: ['equipment'],
-    effect: 'twin.propeffect.reserveSoc',
-    readBy: '@operato/twin-kernel EmsKernel (이 아래로는 방전하지 않는다)'
-  },
-  {
-    id: 'storage.initialSoc',
-    axes: ['equipment'],
-    effect: 'twin.propeffect.initialSoc',
-    readBy: '@operato/twin-kernel EmsKernel (시작 충전율 — 예측·what-if 의 씨앗)'
-  },
-  {
-    id: 'generation.ratedKW',
-    axes: ['equipment'],
-    effect: 'twin.propeffect.genRatedKW',
-    readBy: '@operato/twin-kernel EmsKernel.deriveGeneration (정격 발전)'
-  },
-  {
-    id: 'generation.dailyProfile',
-    axes: ['equipment'],
-    effect: 'twin.propeffect.genDailyProfile',
-    readBy: '@operato/twin-kernel generationFractionAt (시각별 발전 비율)'
-  },
-  /* 요금은 커널이 읽지 않는다 — 금액은 저널을 계산하는 호스트가 만든다. readBy 가 그 사실을 말한다. */
-  {
-    id: 'tariff.demandChargePerKW',
-    axes: ['locations'],
-    effect: 'twin.propeffect.demandChargePerKW',
-    readBy: 'headless-twin/server/engine/kpi-query.ts (수요요금 계산)'
-  },
-  {
-    id: 'tariff.energyChargePerKWh',
-    axes: ['locations'],
-    effect: 'twin.propeffect.energyChargePerKWh',
-    readBy: 'headless-twin/server/engine/kpi-query.ts (전력량 요금 계산)'
-  },
-  /* 판정 기준 — 값이 경보의 유무를 바꾼다(가장 눈에 보이는 효과다). */
-  {
-    id: 'attention.congestionRatio',
-    axes: ['locations'],
-    effect: 'twin.propeffect.congestionRatio',
-    readBy: '@operato/twin-kernel deriveAttentions (병목 판정 기준)'
-  },
-  {
-    id: 'attention.scrapRate',
-    axes: ['equipment'],
-    effect: 'twin.propeffect.scrapRate',
-    readBy: '@operato/twin-kernel deriveAttentions (불량 과다 판정 기준)'
-  },
-  {
-    id: 'attention.scrapMinSamples',
-    axes: ['equipment'],
-    effect: 'twin.propeffect.scrapMinSamples',
-    readBy: '@operato/twin-kernel deriveAttentions (불량률을 재기 시작할 표본 수)'
-  },
-  /*
-   * ── 공정 소요시간 (2026-08-18) ────────────────────────────────────────────
-   *
-   * 실측: 운영 중인 트윈 35개 중 **창고·야드는 공정 명세 행이 0개**였다 — 그 트윈들의 시간은 전부 커널
-   * 상수에서 왔고, 예측은 「같은 조건에서의 상대 비교」에 머물렀다(절대 시각 주장 불가). 이 선언이
-   * 그 사다리를 한 칸 올린다: 실측이 없어도 **현장이 정한 시간**으로 굴러간다.
-   *
-   * 실측(이력에서 배운 값)은 여전히 이 선언을 이긴다 — 화면이 그 사실을 함께 말한다.
-   */
-  {
-    id: 'operation.duration',
-    axes: ['operations'],
-    effect: 'twin.propeffect.operationDuration',
-    readBy: '@operato/twin-kernel FlowEngine.durationOf ← declareDurations (engine/local-declarations.ts 가 실어 보낸다)'
-  },
-  /*
-   * ── 공정 모수 (2026-08-19) ────────────────────────────────────────────────
-   * 양품률의 기본값은 커널 소스의 상수(0.8)였고, **그 상수가 불량 과다 주목 신호까지 만들었다** — 초기
-   * 라인이든 성숙한 라인이든 같은 수로 판정된다. 셋업도 상수였다. 둘 다 현장이 말할 수 있어야 한다.
-   */
-  {
-    id: 'operation.yield',
-    axes: ['operations'],
-    effect: 'twin.propeffect.operationYield',
-    readBy: '@operato/twin-kernel MesKernel(OP_PARAM.yield) ← declareParameters (양품/불량 판정과 산출량)'
-  },
-  {
-    id: 'operation.setupDuration',
-    axes: ['operations'],
-    effect: 'twin.propeffect.operationSetup',
-    readBy: '@operato/twin-kernel MesKernel(OP_PARAM.setupDuration) ← declareParameters (가동 앞에 붙는 셋업)'
-  },
-  {
-    id: 'tariff.currency',
-    axes: ['locations'],
-    effect: 'twin.propeffect.currency',
-    readBy: 'headless-twin/server/engine/kpi-query.ts (금액 표기 통화)'
-  }
-]
-
-/**
- * 이 축의 속성 효과 — `속성 id → i18n 키`.
- *
- * 없는 속성은 **여기 없다**(빈 값으로 채우지 않는다) — 화면이 "등록된 효과가 없다" 를 스스로 말한다.
- */
-export function propertyEffectsOf(axis: string): Record<string, string> {
-  const out: Record<string, string> = {}
-  for (const e of PROPERTY_EFFECTS) if (e.axes.includes(axis)) out[e.id] = e.effect
-  return out
-}
-
-/** 등록부의 축 이름 → 선언이 겨누는 대상 이름. 대상이 아닌 축(자재 정의 등)은 여기 없다. */
-const AXIS_TO_TARGET: Record<string, string> = { locations: 'location', equipment: 'equipment', operations: 'operation' }
-
-/**
- * 이 속성을 **어느 대상에 얹을 수 있나** — 등록부의 축이 그대로 답한다.
- *
- * ── 왜 필요한가 (2026-08-18) ────────────────────────────────────────────────
- * 지게차에 계약전력을 선언할 수 있었다. 문은 받아 주고 화면은 「넣었습니다」라고 말하는데, 그 값을 읽는
- * 코드는 자리(수전)만 본다 — 아무 일도 일어나지 않고 그 사실이 어디에도 나오지 않았다. 효과가 어느 축의
- * 것인지는 이미 등록부가 알고 있으므로, 그 지식을 검사에 쓴다(두 곳에 적지 않는다).
- *
- * 등록부에 없는 속성은 **비어 있는 목록이 아니라 `undefined`** 다: 「어디에도 못 얹는다」와 「우리가
- * 제한을 모른다」는 다르다(후자는 받아 준다 — 속성은 열려 있다는 규약을 지킨다).
- */
-export function declarationTargetsOf(propertyId: string): string[] | undefined {
-  const e = PROPERTY_EFFECTS.find(x => x.id === propertyId)
-  if (!e) return undefined
-  const targets = e.axes.map(a => AXIS_TO_TARGET[a]).filter((t): t is string => !!t)
-  return targets.length ? targets : undefined
-}

package/server/engine/read-time.ts

@@ -1,77 +0,0 @@
-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

@@ -1,55 +0,0 @@
-/*
- * **재기동 정책** — 이 트윈은 다시 세워질 때 자기 과거를 어떻게 대하나.
- *
- * ── 왜 이 이름인가 (ADR-0029 · plans/simulator-as-source.md §2) ─────────────
- * 옛 이름은 `realityMode` 였고 값은 `mirror`·`sim-world`·`sim-experiment` 였다. 그 축은 「현실이 어디서
- * 오나」를 말하는 것처럼 보였지만, 코드가 그것으로 가른 것은 **재기동 거동 하나**였다. 그리고 「현실이
- * 어디서 오나」는 ADR-0029 가 **원본의 종류**로 옮긴 물음이다(`TwinReference.adapterType`) — 트윈은 한
- * 종류이고 언제나 원본을 반영한다.
- *
- * 그래서 이 축은 사라지지 않고 **트윈에 남아 이름을 바꿨다.** 남는 이유: 「자기 저널을 잇는가」는 원본의
- * 성질이 아니라 **트윈과 자기 과거의 관계**다. 같은 시뮬레이터 원본을 보는 두 트윈이 하나는 이어가고
- * 하나는 매번 처음부터 재현할 수 있다 — 원본은 그 둘을 구별하지 못한다.
- *
- *   resync — 외부 실물에서 다시 읽는다(원본이 진실이므로 우리 과거를 이어 붙이지 않는다).
- *   resume — 저널을 이어 세운다(이 트윈이 낳은 타임라인이 곧 사실이다).
- *   reset  — 저널을 비우고 씨앗부터 다시 돌린다(재현 가능한 실험).
- *
- * ── 기본값을 두지 않는다 ────────────────────────────────────────────────────
- * 예전에는 미선언이 알리지 않고 `sim-experiment`(=저널 초기화)로 떨어졌다. 그 관용은 값이 하나 어긋나는
- * 순간 **저널을 지우는 길**이 된다 — 개명 뒤 옛 값이 남아 있는 행을 그 길로 읽으면 재기동 한 번에
- * 이력이 사라진다. 그래서 모르는 값은 **오류를 낸다.** 부르는 쪽이 선언하게 만드는 것이 이 축의 요점이다.
- */
-
-/** 재기동 정책 — 셋뿐이다. */
-export type RestartPolicy = 'resync' | 'resume' | 'reset'
-
-export const RESTART_POLICIES: readonly RestartPolicy[] = ['resync', 'resume', 'reset'] as const
-
-/**
- * 저장된 값을 정책으로 읽는다 — **모르면 오류를 낸다**(기본값으로 메우지 않는다).
- *
- * 옛 어휘(`mirror`·`sim-world`·`sim-experiment`)를 여기서 번역하지 않는다: 번역을 두면 옛 값이 살아남고,
- * 그 값이 다시 어딘가에 저장된다. 저장된 값은 **한 번 옮기고**(데이터 이관) 코드는 새 어휘만 안다.
- * 그래서 이 함수는 옛 값에 대해서도 오류를 내며, 무엇으로 옮겨야 하는지 문장으로 말한다.
- */
-export function readRestartPolicy(raw: unknown, where: string): RestartPolicy {
-  const value = typeof raw === 'string' ? raw.trim() : ''
-  if ((RESTART_POLICIES as readonly string[]).includes(value)) return value as RestartPolicy
-  const legacy: Record<string, RestartPolicy> = { mirror: 'resync', 'sim-world': 'resume', 'sim-experiment': 'reset' }
-  if (legacy[value]) {
-    throw new Error(
-      `${where}: restart policy "${value}" is the old vocabulary — move the stored value to "${legacy[value]}" ` +
-        '(ADR-0029 · plans/simulator-as-source.md §2). Nothing is translated at read time on purpose: a translation would keep the old value alive.'
-    )
-  }
-  throw new Error(
-    `${where}: restart policy ${value ? `"${value}"` : 'is missing'} — declare one of ${RESTART_POLICIES.join(' | ')}. ` +
-      'There is no default: an unspecified policy used to fall through to "reset", which erases the journal on the next reboot.'
-  )
-}
-
-/** 이 값이 정책인가 — 오류를 내지 않고 묻는 자리(화면·검사)를 위해. */
-export function isRestartPolicy(raw: unknown): raw is RestartPolicy {
-  return typeof raw === 'string' && (RESTART_POLICIES as readonly string[]).includes(raw)
-}

package/server/engine/runtime-key.ts

@@ -1,58 +0,0 @@
-/*
- * 런타임 레지스트리 키 — **트윈의 정체성은 `(도메인, 인스턴스 id)` 다.** 순수.
- *
- * ── 왜 있나 (2026-08-06 테넌트 격리 전수 확인) ───────────────────────────────
- * `TwinEngine.instances` 와 `recovered` 가 **`instanceId` 하나로** 키를 잡고 있었다. 그런데 DB 유일성은
- * `[domain, instanceId]` 이고(`TwinInstance` 인덱스) 트윈의 정체성도 그쪽이다. 즉 런타임 맵만 **전역
- * 이름 공간**이었다.
- *
- * **충돌은 이론이 아니다.** 레퍼런스 경로가 `instanceId` 로 **레퍼런스 소스 이름**을 쓴다
- * (`sap-ewm-1710`). 벤더 시스템 이름은 테넌트가 **공유하는 어휘**라, 두 테넌트가 같은 시스템에
- * 연결하면 같은 id 가 된다 — 드문 사고가 아니라 예상되는 경우다.
- *
- * 그래서 무엇이 어긋났나:
- *  · `startLive` 의 조기 반환이 A 의 런타임을 B 에게 돌려주고 `ingestLive` 는 도메인을 확인하지 않아
- *    **B 의 라이브 이벤트가 A 의 커널에 적용**될 수 있었다.
- *  · `recovered` 가 겹치면 웜스타트 씨앗이 **남의 스냅샷**이 되어 재고가 섞인다.
- *  · `start`/`stop` 이 남의 런타임을 집으므로 B 는 "기동됨" 을 받고도 이후 전부 거부됐다.
- *
- * 이 부류는 **이미 한 번 물었다** — `twin-lifecycle-mutation.ts` 주석이 증언한다: "과거엔
- * `Object.keys(TwinEngine.instances)` 로 전역 반환 → 다른 도메인 트윈이 새던 버그." 그 자리만 고쳤다.
- * 그래서 이번에는 가드를 더 붙이지 않고 **키를 고친다** — 저수준 메서드가 `domainId` 를 받게 되는 것이
- * 요점이다. "누구의 트윈인가" 를 말하지 않고는 만질 수 없다.
- *
- * ── 구분자 규약 ─────────────────────────────────────────────────────────────
- * `${domainId}:${instanceId}` — 이 저장소가 이미 쓰는 모양이다(`structureRevCache`·`measuredCache`).
- * 새 모양을 만들지 않는다. 파싱은 **첫 구분자**에서 자르므로 `instanceId` 에 `:` 가 들어 있어도
- * 안전하다(레퍼런스 소스 이름에 들어갈 수 있다). 대신 `domainId` 에 구분자가 있으면 키가 모호해지므로
- * **그때는 오류를 낸다** — 알리지 않고 잘못된 키를 만들면 그게 곧 이 결함의 재발이다.
- */
-
-/** 도메인과 인스턴스 id 를 잇는 문자 — 저장소의 기존 캐시 키와 같은 모양. */
-export const RUNTIME_KEY_SEP = ':'
-
-/**
- * 런타임 레지스트리 키.
- *
- * @throws 도메인 id 가 비었거나 구분자를 담고 있으면(키가 모호해진다). 인스턴스 id 가 비었으면.
- */
-export function runtimeKey(domainId: string, instanceId: string): string {
-  if (!domainId) throw new Error('runtimeKey: domainId is required — a twin runtime always belongs to a tenant')
-  if (!instanceId) throw new Error('runtimeKey: instanceId is required')
-  if (domainId.includes(RUNTIME_KEY_SEP)) {
-    throw new Error(`runtimeKey: domainId must not contain "${RUNTIME_KEY_SEP}" (would make the key ambiguous)`)
-  }
-  return `${domainId}${RUNTIME_KEY_SEP}${instanceId}`
-}
-
-/** 키를 되돌린다 — 첫 구분자에서 자른다(인스턴스 id 안의 구분자는 보존). */
-export function parseRuntimeKey(key: string): { domainId: string; instanceId: string } {
-  const at = key.indexOf(RUNTIME_KEY_SEP)
-  if (at <= 0 || at === key.length - 1) throw new Error(`parseRuntimeKey: "${key}" is not a runtime key`)
-  return { domainId: key.slice(0, at), instanceId: key.slice(at + 1) }
-}
-
-/** 이 키가 이 테넌트의 것인가 — 레지스트리를 조회할 때 도메인으로 걸러낸다. */
-export function isOfDomain(key: string, domainId: string): boolean {
-  return !!domainId && key.startsWith(`${domainId}${RUNTIME_KEY_SEP}`)
-}

package/server/engine/spec-coverage.ts

@@ -1,105 +0,0 @@
-/*
- * 시뮬 명세 자기보고 — **"이 예측으로 무엇을 말할 수 있나" 를 예측과 함께 내보낸다.**
- *
- * 배경(operato-twin design/plans/simulation-spec.md): 공정 소요·수율이 커널 소스의 상수였다. 이제
- * 마스터가 명세를 실어 오면 커널이 그것으로 실행하고, `specCoverage()` 가 무엇을 선언값으로 무엇을
- * 기본값으로 썼는지 보고한다. 그 보고를 **예측 응답에 붙이지 않으면** 받는 쪽은 상수로 계산한 숫자와
- * 현장 명세로 계산한 숫자를 구별할 수 없다 — 똑같이 "p50 168" 로 보인다.
- *
- * 언어 중립: 여기서는 **코드와 수치만** 낸다(`qualification` + 카운트). 사람이 읽는 문장은 표현
- * 계층(클라 i18next / AI 답변)이 만든다 — attention 과 같은 규율.
- */
-
-/** 예측 자격 — 선언된 명세가 얼마나 덮는지에 따라 이 예측으로 정당하게 말할 수 있는 범위가 달라진다. */
-export type ForecastQualification =
-  /** 모든 소요가 커널 기본 상수 → **상대 비교만**("자원 2대 더 넣으면 나아지나"). 절대 시각 주장 불가. */
-  | 'relative'
-  /** 일부만 선언·실측 → 그 구간은 계산하지, 나머지는 상수. 혼합. */
-  | 'partial'
-  /** 소요 전부 선언 → 절대 예측 시도 가능. 단 **정확도는 이력이 확인한다**(선언 != 검증). */
-  | 'absolute-capable'
-  /**
-   * 소요 전부가 **이 현장의 이력에서 온 값**(추정기) → 가장 강한 근거. 선언은 사람이 적은 값이고
-   * 이것은 실제로 일어난 값이다. 그래도 "정확하다" 가 아니라 "관측에 계산하지됐다" 는 뜻이다.
-   */
-  | 'calibrated'
-
-export interface SpecCoverageReport {
-  operations: {
-    kind: string
-    duration: 'measured' | 'declared' | 'default'
-    variability?: string
-    parameters: string[]
-    /**
-     * 그 모수를 **무엇으로** 읽었나(`id → measured|declared`) — 없는 id 는 코드 상수를 썼다는 뜻이다.
-     *
-     * 소요시간이 근거를 밝히듯 모수도 밝힌다(2026-08-19): 수율이 이력에서 온 값인지 사람이 적은 값인지
-     * 상수인지에 따라 「불량이 늘었다」는 화면 문장의 무게가 다르다.
-     */
-    parameterBasis?: Record<string, 'measured' | 'declared'>
-  }[]
-  /** 이력·계산에서 온 소요(추정기) — 선언값보다 강한 근거. */
-  measuredDurations: number
-  declaredDurations: number
-  defaultDurations: number
-  /** 변동(분포)을 가진 작업 종류 수. **0 이면 모든 소요가 고정값**이라 대기·병목이 과소평가된다. */
-  varyingDurations: number
-  qualification: ForecastQualification
-}
-
-/**
- * 명세 자격 판정(순수) — 커널 보고를 받아 분류한다. 커널을 모르므로 테스트가 쉽다.
- * 관측된 작업이 하나도 없으면(`operations` 빈 배열) 판정할 근거가 없으므로 **undefined**(모른다).
- */
-export function classifySpecCoverage(cov: {
-  operations?: {
-    kind: string
-    duration: 'measured' | 'declared' | 'default'
-    variability?: string
-    parameters?: string[]
-    parameterBasis?: Record<string, 'measured' | 'declared'>
-  }[]
-  measuredDurations?: number
-  declaredDurations?: number
-  defaultDurations?: number
-}): SpecCoverageReport | undefined {
-  const ops = cov?.operations
-  if (!ops?.length) return undefined
-  const operations = ops.map(o => ({
-    kind: o.kind,
-    duration: o.duration,
-    ...(o.variability ? { variability: o.variability } : {}),
-    parameters: o.parameters ?? [],
-    /* 근거는 커널이 말한 것만 나른다 — 없으면 필드를 만들지 않는다(상수를 썼다는 뜻이 빈칸이다). */
-    ...(o.parameterBasis && Object.keys(o.parameterBasis).length ? { parameterBasis: o.parameterBasis } : {})
-  }))
-  const measuredDurations = cov.measuredDurations ?? operations.filter(o => o.duration === 'measured').length
-  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. */
-  const grounded = measuredDurations + declaredDurations
-  const qualification: ForecastQualification =
-    grounded === 0
-      ? 'relative'
-      : defaultDurations > 0
-        ? 'partial'
-        : declaredDurations === 0
-          ? 'calibrated'
-          : 'absolute-capable'
-  return { operations, measuredDurations, declaredDurations, defaultDurations, varyingDurations, qualification }
-}
-
-/**
- * 커널에서 읽는다 — **아직 이 API 가 없는 커널(발행 이전)이면 undefined.**
- * 그때 `undefined` 는 "명세가 없다" 가 아니라 "모른다" 다. 소비처가 그 둘을 섞지 않도록 주석을 남긴다:
- * 없는 것을 "전부 기본값" 이라고 단정하지 않는다(단정하려면 커널이 말해 줘야 한다).
- */
-export function readSpecCoverage(kernel: any): SpecCoverageReport | undefined {
-  if (typeof kernel?.specCoverage !== 'function') return undefined
-  try {
-    return classifySpecCoverage(kernel.specCoverage())
-  } catch {
-    return undefined
-  }
-}