@things-factory/headless-twin 10.0.15 → 10.0.18

package/server/service/twin-subject/twin-subject-writer.ts

@@ -0,0 +1,189 @@
+import { getRepository } from '@things-factory/shell'
+
+import { twinError, twinWarn } from '../../engine/log.js'
+import { absoluteTime, hydratedDate } from '../../engine/read-time.js'
+import { TwinSubjectEvent } from './twin-subject-event.js'
+import { subjectsOf, type ItemResolver } from './event-subjects.js'
+
+/*
+ * **대상별 사건 목록에 적는 쪽** — 저널을 쓸 때 함께 적는다.
+ *
+ * ── 왜 저널 쓰기와 같은 자리인가 ────────────────────────────────────────────
+ * 저널을 쓰는 문은 하나다(`flushJournal` → `persistBatch`·`persistCarried`). 그 자리에서 함께 적으면
+ * 두 표가 어긋나지 않는다. 다른 자리에서 나중에 적으면 「저널에는 있고 이 표에는 없는 사건」이 생기고,
+ * 그것은 화면에서 오류 없이 빠진 사건이 된다.
+ *
+ * ── 저널이 먼저다 ──────────────────────────────────────────────────────────
+ * 이 표에 적다가 실패해도 저널 쓰기를 되돌리지 않는다. 사실의 원본은 저널이고, 이 표는 다시 만들 수
+ * 있다. 반대로 두면 조회를 빠르게 하려고 만든 표가 사실을 잃는 원인이 된다.
+ *
+ * **그러나 알리지 않고 넘기지 않는다.** 실패를 세어 창마다 한 줄 남긴다 — 알리지 않고 비면 화면이 「그 대상에는
+ * 사건이 없다」고 말하게 된다.
+ *
+ * ── 앞으로만 채운다 ────────────────────────────────────────────────────────
+ * 이미 저장된 사건을 소급해서 채우지 않는다. 이 표가 만들어진 뒤 들어오는 사건만 적힌다. 그래서 새
+ * 조회 축이 필요할 때 3,128만 줄을 다시 만들지 않는다. 준비되지 않은 구간은 조회하는 쪽이 말한다
+ * (§`twin-subject-query` 의 `coveredFrom`).
+ *
+ * 설계: `operato-twin/design/plans/read-models.md`
+ */
+
+/** 한 번에 넣는 줄 수 — 저널 쓰기와 같은 규율(드라이버 파라미터 상한). */
+const CHUNK = 500
+
+/** 적다가 실패한 것을 센다 — 트윈마다. 알리지 않고 비는 것을 막는 유일한 신호다. */
+const failures = new Map<string, { count: number; lastLogMs: number; lastError: string }>()
+
+/** 같은 실패를 매번 적지 않는다 — 로그가 그 자체로 부하가 된다. */
+const FAIL_LOG_MS = 60_000
+
+export interface SubjectWriteEntry {
+  envelope: any
+  revision: number
+  /** 저널 줄의 id — 알면 함께 둔다. 벌크 저장에서는 모를 수 있다(그때는 비운다). */
+  eventId?: string
+}
+
+/**
+ * 이 배치의 사건들이 가리키는 대상을 적는다 — 적은 줄 수를 돌려준다.
+ *
+ * `itemOf` 는 개체 식별자에서 선언된 품목을 찾아 주는 함수다. 없으면 품목 줄을 만들지 않는다 —
+ * 짐작으로 이으면 남의 품목 이력에 이 사건이 섞인다(§`event-subjects`).
+ */
+export async function writeSubjectRows(
+  domainId: string,
+  instanceId: string,
+  entries: readonly SubjectWriteEntry[],
+  itemOf?: ItemResolver
+): Promise<number> {
+  if (!entries.length) return 0
+
+  const rows: any[] = []
+  for (const { envelope, revision, eventId } of entries) {
+    const eventTime = timeOf(envelope)
+    /*
+     * 시각을 모르는 사건은 이 표에 넣지 않는다. 이 표의 유일한 쓸모가 「시각순 목록」이고, 시각이 없는
+     * 줄은 그 목록의 어디에도 놓을 수 없다. 넣고 「지금」으로 메우면 그 사건이 최근으로 보인다.
+     */
+    if (!eventTime) continue
+    const eventType = String(envelope?.eventType ?? '').trim()
+    if (!eventType) continue
+
+    for (const s of subjectsOf(envelope, { itemOf })) {
+      rows.push({
+        domain: { id: domainId },
+        instanceId,
+        subjectKind: s.kind,
+        subjectId: s.id,
+        eventTime,
+        revision,
+        eventType,
+        ...(eventId ? { eventId } : {})
+      })
+    }
+  }
+  if (!rows.length) return 0
+
+  try {
+    const repo = getRepository(TwinSubjectEvent)
+    for (let i = 0; i < rows.length; i += CHUNK) await repo.insert(rows.slice(i, i + CHUNK))
+    return rows.length
+  } catch (err: any) {
+    noteFailure(domainId, instanceId, rows.length, err?.message ?? String(err))
+    return 0
+  }
+}
+
+/** 사건의 시각 — 봉투가 말하는 값만 쓴다. 없으면 `null`(지금으로 메우지 않는다). */
+function timeOf(envelope: any): Date | null {
+  /* 봉투는 컬럼이 아니다 — 정규 계약이 절대시각을 요구하므로 그 규칙으로 읽는다(§`absoluteTime`). */
+  return absoluteTime(envelope?.eventTime ?? envelope?.data?.at)
+}
+
+function noteFailure(domainId: string, instanceId: string, rows: number, message: string): void {
+  const key = `${domainId}:${instanceId}`
+  const f = failures.get(key) ?? { count: 0, lastLogMs: 0, lastError: '' }
+  f.count += rows
+  f.lastError = message
+  const now = Date.now()
+  if (now - f.lastLogMs >= FAIL_LOG_MS) {
+    f.lastLogMs = now
+    twinWarn(
+      `[twin-subject] "${instanceId}" 대상 목록에 적지 못했다 — 지금까지 ${f.count}줄. ` +
+        `저널에는 그 사건이 있으므로 사실은 잃지 않았지만, 이 트윈의 이력 화면에 그만큼이 비어 있다: ${message}`
+    )
+  }
+  failures.set(key, f)
+}
+
+/** 적지 못한 줄 수 — 조회하는 쪽이 「이 표가 온전한가」를 말할 수 있게. */
+export function subjectWriteFailures(domainId: string, instanceId: string): number {
+  return failures.get(`${domainId}:${instanceId}`)?.count ?? 0
+}
+
+/** 시험이 쓰는 초기화 — 프로세스 안의 셈이므로 시험마다 비운다. */
+export function resetSubjectWriteFailures(): void {
+  failures.clear()
+}
+
+/**
+ * 보관 상한 — 이 트윈에서 이 시각보다 오래된 줄을 지운다.
+ *
+ * 이 표는 **버릴 수 있는 값**이다. 지우면 그 구간의 이력 조회가 느려지고(저널로 답한다) 사실은 사라지지
+ * 않는다. 그래서 저널보다 짧게 둘 수 있고, 그러는 편이 낫다 — 화면은 최근을 본다.
+ *
+ * 저널 정리와 같은 창에서 돌린다(§`TwinEngine.pruneJournal`). 나눠서 지우는 규율도 같다.
+ */
+export async function pruneSubjectRows(
+  domainId: string,
+  instanceId: string,
+  cutoff: Date,
+  budgetMs: number,
+  batch: number
+): Promise<number> {
+  let deleted = 0
+  const startedMs = Date.now()
+  for (;;) {
+    /*
+     * 경계를 시각으로 찾는다 — 목차가 `(domain, instance, eventTime)` 이므로 그 순서로 물어야 쓴다.
+     * 저널 정리에서 같은 것을 실측으로 배웠다(리비전 순으로 물으면 목차를 못 쓴다).
+     */
+    const edge = await getRepository(TwinSubjectEvent)
+      .createQueryBuilder('s')
+      .select('s.eventTime', 'eventTime')
+      .where('s.domain = :domainId', { domainId })
+      .andWhere('s.instanceId = :instanceId', { instanceId })
+      .andWhere('s.eventTime < :cutoff', { cutoff })
+      .orderBy('s.eventTime', 'ASC')
+      .offset(batch - 1)
+      .limit(1)
+      .getRawOne<{ eventTime: unknown }>()
+      .catch(() => null)
+
+    /* 원시 결과의 컬럼 값은 드라이버에게 해석시킨다(§`hydratedDate`). */
+    const upTo = hydratedDate(getRepository(TwinSubjectEvent), 'eventTime', edge?.eventTime)
+
+    const del = getRepository(TwinSubjectEvent)
+      .createQueryBuilder()
+      .delete()
+      .from(TwinSubjectEvent)
+      .where('domain_id = :domainId', { domainId })
+      .andWhere('instance_id = :instanceId', { instanceId })
+    const res = await (upTo
+      ? del.andWhere('event_time <= :upTo', { upTo })
+      : del.andWhere('event_time < :cutoff', { cutoff })
+    )
+      .execute()
+      .catch(err => {
+        twinError('[twin-subject] prune fail', err?.message ?? err)
+        return { affected: 0 }
+      })
+
+    const n = res.affected ?? 0
+    deleted += n
+    if (!n) break
+    if (Date.now() - startedMs >= budgetMs) break
+    await new Promise(resolve => setImmediate(resolve))
+  }
+  return deleted
+}

package/server/service/twin-target/twin-target-resolver.ts

@@ -72,7 +72,7 @@ export class TwinTargetResolver {
     if (!isTwinMetric(metric)) throw new Error(`unknown twin metric "${metric}" — see twinTargetMetrics`)
     if (!Number.isFinite(target)) throw new Error('target must be a finite number')
     if (!spaceId && !instanceId) throw new Error('a target must be scoped to a space or an instance')
-    /* 축만 있고 값이 없으면 **어디에 거는 목표인지 알 수 없다** — 조용히 전체 목표로 만들지 않는다
+    /* 축만 있고 값이 없으면 **어디에 거는 목표인지 알 수 없다** — 알리지 않고 전체 목표로 만들지 않는다
        (그러면 사용자는 구역 목표를 걸었다고 믿는데 전체가 바뀐다). */
     if (axis && !axisKey) throw new Error('axisKey is required when axis is given')
     if (!axis && axisKey) throw new Error('axis is required when axisKey is given')

package/shared/entity-delta.ts

@@ -6,7 +6,7 @@
  * 트윈에서 사소한 속성은 없다. 소속 구역·소속 팔레트·수량·만료처럼 곁가지로 보이는 값이 실제로는
  * 구역 롤업·적재 표현·로트 추적의 전제다. 그래서 여기서 **필드를 손으로 골라 담지 않는다.**
  *
- * 예전에는 엔티티마다 필요할 것 같은 필드만 열거했고, 그 결과 계약에 있는 것이 조용히 누락됐다
+ * 예전에는 엔티티마다 필요할 것 같은 필드만 열거했고, 그 결과 계약에 있는 것이 오류 없이 빠졌다
  * (2026-08-01 감사: 노드 parentId 누락 · 작업 전량 누락 · 물품 전량 누락). 화이트리스트 방식은
  * **계약이 자라도 화면이 따라오지 못한다** — 커널이 속성을 늘릴 때마다 이 파일을 고쳐야 하고, 고치는
  * 것을 잊으면 아무 신호 없이 정보가 사라진다.
@@ -50,7 +50,7 @@ export const ENERGY_TAG_PREFIX = '__energy__'
 
 /** 이 트윈의 집약 채널 태그. 트윈 식별자가 없으면 만들지 않는다 — 덮어쓰기의 원인이었다. */
 export function aggregateTag(prefix: string, instanceId: string): string {
-  if (!instanceId) throw new Error('aggregateTag: instanceId required — 트윈 구분이 없는 태그는 다른 트윈의 것을 덮는다')
+  if (!instanceId) throw new Error('aggregateTag: instanceId required — tags without instanceId overwrite other twin states across tenants')
 
   return `${prefix}:${instanceId}`
 }
@@ -121,7 +121,7 @@ function aggregateItem(entity: any, idKey: 'id' | 'epc'): any {
 /**
  * 물품 집약의 상한 — 큰 현장은 물품이 수만 개라, 전량을 매 브로드캐스팅에 실으면 전달이 현장을 느리게 한다.
  *
- * **조용히 자르지 않는다**: 넘치면 `total`(전체 수)과 `truncated`(잘린 수)를 함께 실어, 소비처가
+ * **알리지 않고 자르지 않는다**: 넘치면 `total`(전체 수)과 `truncated`(잘린 수)를 함께 실어, 소비처가
  * "이게 전부" 라고 오해하지 않게 한다. 개별 물품은 태그별 delta 로 따로 나가고 그쪽은 시그니처 dedup
  * 이 걸려 **변한 것만** 재브로드캐스팅된다.
  */
@@ -299,7 +299,7 @@ export function buildEntityDeltas(state: any, instanceId: string, scope?: Entity
         ...(energy.open ? { open: energy.open } : {}),
         ...(energy.peakSince ? { peakSince: energy.peakSince } : {}),
         /* 마감된 구간은 **최근 것만** 낸다 — 하루치를 매 브로드캐스팅에 실으면 채널이 그것으로 찬다.
-           전체 수는 함께 낸다(조용히 자르지 않는다). */
+           전체 수는 함께 낸다(알리지 않고 자르지 않는다). */
         recent: (energy.closed ?? []).slice(-8),
         closedTotal: energy.closedTotal ?? 0
       }

package/shared/touched-items.ts

@@ -12,7 +12,7 @@
  *
  * ── 모르면 전부다 ───────────────────────────────────────────────────────────
  * 이 함수가 `null` 을 돌려주면 「이 사건이 어느 물품을 건드렸는지 말할 수 없다」는 뜻이고, 그때 호출자는
- * **전부 다시 만든다**(지금까지의 거동). 낯선 어휘가 오면 조용히 빠뜨리는 것이 아니라 비싸게 안전한
+ * **전부 다시 만든다**(지금까지의 거동). 낯선 어휘가 오면 알리지 않고 빠뜨리는 것이 아니라 비싸게 안전한
  * 쪽으로 떨어진다 — 화면이 낡는 것보다 계산을 한 번 더 하는 것이 낫다.
  */
 
@@ -25,7 +25,7 @@ function push(out: Set<string>, v: unknown): void {
  * 물품을 건드리지 않는다고 **선언된** 사건들 — 커널의 운영 델타와 에너지 사건.
  *
  * 이 목록은 커널 계약(`OP_EVENT`·`ENERGY_EVENT`)에서 왔다. 여기 없는 낱말이 오면 「모른다」로 떨어져
- * 전부 다시 만든다 — 커널이 사건을 늘렸을 때 조용히 빠뜨리는 대신 비싸게 안전한 쪽을 고른다.
+ * 전부 다시 만든다 — 커널이 사건을 늘렸을 때 알리지 않고 빠뜨리는 대신 비싸게 안전한 쪽을 고른다.
  *
  * 근거: 미러의 리듀서에서 이 사건들은 작업·설비·인원·자산·오더·계량만 바꾼다(물품 축을 만지지 않는다).
  * 자리 점유는 이 사건들도 바꾸지만, 자리는 **어차피 매번 전부 다시 만든다**(위 주석).

package/shared/twin-level.ts

@@ -4,7 +4,7 @@
  * ── 왜 여기 있나 ───────────────────────────────────────────────────────────
  * 이 목록을 세 곳이 쓴다: 씬 표현이 "나는 어느 단계에 붙는다" 고 선언할 때(클라이언트), 성과 카드가
  * "이 단계로 나눠 달라" 고 물을 때(클라이언트), AI 가 "구역별로 보여 줘" 를 제안할 때(서버).
- * 세 곳이 각자 목록을 적으면 하나가 늘 때 나머지가 조용히 뒤처진다 — 집약 태그에서 이미 겪었다.
+ * 세 곳이 각자 목록을 적으면 하나가 늘 때 나머지가 알리지 않고 뒤처진다 — 집약 태그에서 이미 겪었다.
  *
  * 그래서 **한 곳**에 두고 셋이 가져다 쓴다. 이 파일은 import 가 없어 클라이언트 번들에 서버 코드를
  * 끌고 들어가지 않는다.

package/test/adopt-structure-live.test.ts

@@ -4,10 +4,10 @@
  * 미러가 비추는 현실은 24시간 돈다. 설비 한 대가 늘었다고 트윈을 멈췄다 세우면 그 사이의
  * 사실을 잃고, 라이브에서 유실은 곧 거짓이다. 그래서 미러는 **돌면서** 갈아탄다.
  *
- * 갈아타기가 옳으려면 **세 층이 함께** 움직여야 한다. 하나라도 빠지면 조용히 어긋난다:
+ * 갈아타기가 옳으려면 **세 층이 함께** 움직여야 한다. 하나라도 빠지면 알리지 않고 어긋난다:
  *  ① 리비전 — 이후의 이벤트가 새 번호를 달고 다닌다(재생이 마디를 나눌 수 있게)
  *  ② 저장 model·구조 행 — 조회가 새 구조를 본다
- *  ③ 커널 — 지금 접히는 이벤트가 새 구조 위에서 접힌다
+ *  ③ 커널 — 지금 계산에 들어가는 이벤트가 새 구조 위에서 계산된다
  *
  * 커널 단위 거동(무엇을 지키고 무엇을 버리나)은 커널 쪽 `adopt-structure.test.ts` 가 지킨다.
  * 여기서 지키는 것은 **호스트 배선** — 세 층이 같은 인제스트에서 함께 움직이는가.
@@ -93,7 +93,7 @@ test('돌고 있는 미러는 멈추지 않고 갈아탄다 — 세 층이 함
   const snap = TwinEngine.snapshot(domainId, MIRROR)
   assert.equal(snap.locations.filter((n: any) => n.type === 'storage').length, 7, '커널도 새 자리를 들고 있다')
 
-  /* 무엇이 달라졌는지 **말한다** — 멈췄다 세우는 마디가 없으므로 말하지 않으면 조용히 지나간다 */
+  /* 무엇이 달라졌는지 **말한다** — 멈췄다 세우는 마디가 없으므로 말하지 않으면 알리지 않고 지나간다 */
   const adopted = res.warnings.find((w: any) => w.code === 'structure-adopted')
   assert.ok(adopted, '갈아타기는 말없이 성공하지 않는다')
   assert.equal(adopted.params.locationsAdded, 4, '자리 4개가 늘었다(빈 3→7)')

package/test/aggregate-not-findone.test.ts

@@ -0,0 +1,112 @@
+/*
+ * ★ 수 하나가 필요하면 **집계로 묻는다** — `findOne(order: …)` 으로 흉내내지 않는다.
+ *
+ * ── 왜 이 검사가 필요한가 (2026-08-28 전수 조사) ────────────────────────────
+ * 「가장 늦은 사건」·「저널 머리」·「첫 사건」처럼 **한 줄만** 필요한 자리에서 이런 모양을 썼다.
+ *
+ *   findOne({ where: { domain: { id }, … }, order: { revision: 'DESC' } })
+ *
+ * 관계를 가진 엔티티에서 `find`·`findOne` 은 두 단계 질의가 되고 **안쪽에 상한이 없다** — 조건에 맞는
+ * 행을 전부 만든 뒤 밖에서 한 줄을 고른다. 이 파일이 지키는 저장소에서 실측한 값이다.
+ *
+ *   twinEvents 의 같은 모양      0.024초 대 12초 (저널 375만 행)
+ *   현장 성과(`latestEventTime`)  7.2초 — 업무 사실 97만 행을 payload 까지 만든 뒤 한 줄
+ *   백테스트 구간(`gapWindow`)    같은 모양을 두 번(첫 사건·마지막 사건)
+ *
+ * **답은 맞고 비용만 틀리다.** 그래서 사람 리뷰가 잡지 못한다 — 기계에 맡긴다.
+ * (같은 이유로 만든 검사가 하나 더 있다: `journal-read-discipline`. 그것은 「통째로 읽는 자리」를 보고,
+ *  이 검사는 「한 줄만 필요한데 통째로 읽는 자리」를 본다.)
+ *
+ * ── 규율 ────────────────────────────────────────────────────────────────────
+ * 큰 표에서 한 줄·한 수가 필요하면 질의 빌더로 `MIN`·`MAX`·`COUNT` 를 묻는다. 색인의 끝을 집으므로
+ * 행을 만들지 않는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+const ROOT = join(import.meta.dirname, '..', 'server')
+
+/** 이 검사가 보는 큰 표 — 행이 수백만이 될 수 있는 것들. */
+const BIG_TABLES = ['TwinEvent', 'TwinSubjectEvent']
+
+/**
+ * 예외 — **이유와 함께** 적는다. 이유가 없으면 예외가 아니다.
+ *
+ * 지금은 비어 있다. 예외를 더할 때는 왜 한 줄이 아니라 여러 행이 필요한지, 그리고 없어질 조건을 함께 적는다.
+ */
+const ALLOWED: { file: string; why: string }[] = []
+
+function sites(): { file: string; line: number; snippet: string }[] {
+  const out: { file: string; line: number; snippet: string }[] = []
+  const walk = (dir: string) => {
+    for (const name of readdirSync(dir)) {
+      const p = join(dir, name)
+      if (statSync(p).isDirectory()) { walk(p); continue }
+      if (!name.endsWith('.ts')) continue
+      const src = readFileSync(p, 'utf8')
+      /*
+       * 큰 표의 저장소에서 `findOne` 을 부르면서 `order:` 를 주는 모양을 찾는다. 정렬을 준다는 것은
+       * 「끝에서 한 줄」을 원한다는 뜻이고, 그것이 곧 집계다.
+       *
+       * 변수에 담아 부르는 형태도 본다 — 그러지 않으면 이름만 바꿔 이 검사를 지나칠 수 있다.
+       */
+      for (const table of BIG_TABLES) {
+        const vars = new Set<string>()
+        for (const m of src.matchAll(new RegExp(`const\\s+(\\w+)\\s*=\\s*getRe(?:ad)?Repository\\(${table}\\)`, 'g'))) {
+          vars.add(m[1])
+        }
+        const receivers = [`getRepository(${table})`, `getReadRepository(${table})`, ...[...vars]]
+        for (const recv of receivers) {
+          let at = src.indexOf(recv)
+          while (at >= 0) {
+            const after = src.slice(at + recv.length, at + recv.length + 400)
+            const call = /^\s*\n?\s*\.findOne\(\s*\{([\s\S]{0,320})/.exec(after)
+            if (call && /order\s*:/.test(call[1])) {
+              out.push({
+                file: p.slice(ROOT.length + 1),
+                line: src.slice(0, at).split('\n').length,
+                snippet: call[1].replace(/\s+/g, ' ').slice(0, 90)
+              })
+            }
+            at = src.indexOf(recv, at + 1)
+          }
+        }
+      }
+    }
+  }
+  walk(ROOT)
+  return out
+}
+
+test('★ 큰 표에서 한 줄을 원하면 집계로 묻는다 — findOne(order) 으로 흉내내지 않는다', () => {
+  const found = sites().filter(s => !ALLOWED.some(a => a.file === s.file))
+  assert.deepEqual(
+    found.map(s => `${s.file}:${s.line} — ${s.snippet}`),
+    [],
+    '이 모양은 조건에 맞는 행을 전부 만든 뒤 한 줄을 고른다. 질의 빌더로 MIN·MAX·COUNT 를 묻는다.\n' +
+      '정말 여러 행이 필요하면 ALLOWED 에 이유와 없어질 조건을 함께 적는다.'
+  )
+})
+
+test('예외 목록에는 반드시 이유가 붙는다 — 이름만 적어 지나가지 않게', () => {
+  for (const a of ALLOWED) assert.ok(a.why.trim().length > 20, `${a.file} 의 예외에 이유가 없다`)
+})
+
+test('★ 고친 자리들이 실제로 집계를 쓴다 — 되돌아가지 않게 이름으로 못박는다', () => {
+  /*
+   * 이름으로 못박는 이유: 되돌아가도 **답은 맞기 때문에** 결과를 보는 시험으로는 잡히지 않는다.
+   */
+  const kpi = readFileSync(join(ROOT, 'engine', 'kpi-query.ts'), 'utf8')
+  assert.match(kpi, /select\('MAX\(e\.eventTime\)', 'at'\)/, '마지막 업무 기록 시각은 집계로 묻는다')
+
+  const engine = readFileSync(join(ROOT, 'engine', 'twin-engine.ts'), 'utf8')
+  assert.match(engine, /select\('MAX\(e\.revision\)', 'max'\)/, '저널 머리는 집계로 묻는다')
+
+  const forecast = readFileSync(join(ROOT, 'service', 'twin-forecast', 'twin-forecast-query.ts'), 'utf8')
+  assert.match(forecast, /\$\{agg\}\(e\.eventTime\)/, '백테스트 구간의 양 끝은 집계로 묻는다')
+
+  const model = readFileSync(join(ROOT, 'service', 'twin-model', 'twin-model-query.ts'), 'utf8')
+  assert.match(model, /select\('MAX\(e\.revision\)', 'max'\)/, '모델 요약의 저널 끝도 집계로 묻는다')
+})

package/test/attention-digest.test.ts

@@ -7,8 +7,8 @@
  * 둘뿐이다 — 레일에 20건만 그리고, 자리 7곳의 색을 뽑는다.
  *
  * ── 이 테스트가 지키는 것 ───────────────────────────────────────────────────
- *  ① **자리 색은 전량을 근거로** 접힌다. 상위 N 으로 접으면 20위 밖의 신호를 가진 자리가 색을 잃는다.
- *  ② **조용히 자르지 않는다.** 전체 개수를 함께 보내야 레일이 "N건 더" 를 말할 수 있다.
+ *  ① **자리 색은 전량을 근거로** 계산된다. 상위 N 으로 줄이면 20위 밖의 신호를 가진 자리가 색을 잃는다.
+ *  ② **알리지 않고 자르지 않는다.** 전체 개수를 함께 보내야 레일이 "N건 더" 를 말할 수 있다.
  *  ③ **순서가 화면과 같다.** 서버가 고른 20건이 화면이 고를 20건과 달라지면 아무 데서도 안 드러난다.
  */
 import { test } from 'node:test'
@@ -18,15 +18,15 @@ import { digestAttentions, compareAttentions, mergeLensAttentions } from '../ser
 
 const attn = (id: string, severity: string, locationId?: string, state?: string) => ({ id, severity, state, anchor: locationId ? { locationId } : undefined })
 
-test('상위 N 만 남기고 전체 개수를 함께 낸다 — 조용히 자르지 않는다', () => {
+test('상위 N 만 남기고 전체 개수를 함께 낸다 — 알리지 않고 자르지 않는다', () => {
   const all = Array.from({ length: 50 }, (_, i) => attn(`a${i}`, 'low', `loc-${i % 3}`))
   const d = digestAttentions(all, 20)
   assert.equal(d.attentions.length, 20)
   assert.equal(d.attentionTotal, 50, '전체 개수가 없으면 화면이 "괜찮아졌다" 로 읽는다')
 })
 
-test('자리 색은 전량을 근거로 접는다 — 상위 N 밖의 자리도 색을 갖는다', () => {
-  /* 앞 20건은 loc-hot 에, 21번째 한 건만 loc-cold 에 — 잘린 뒤에 접으면 loc-cold 가 색을 잃는다. */
+test('자리 색은 전량을 근거로 처리한다 — 상위 N 밖의 자리도 색을 갖는다', () => {
+  /* 앞 20건은 loc-hot 에, 21번째 한 건만 loc-cold 에 — 잘린 뒤에 계산하면 loc-cold 가 색을 잃는다. */
   const all = [...Array.from({ length: 20 }, (_, i) => attn(`hot${i}`, 'high', 'loc-hot')), attn('cold', 'critical', 'loc-cold')]
   const d = digestAttentions(all, 20)
   assert.equal(d.attentions.length, 20)
@@ -81,7 +81,7 @@ test('정렬 함수는 원본을 바꾸지 않는다 — 스냅샷을 제자리
  * 한 공장에 WMS·MES·YMS 가 함께 있으므로 "이 현장에서 봐야 할 것" 은 렌즈 하나로 답할 수 없다.
  * 예전에는 화면이 인스턴스마다 물어 손으로 합쳤고, 그러면 정렬 규칙이 화면마다 갈린다.
  *
- * 모으면서 조용히 틀릴 수 있는 자리 셋을 여기서 못 박는다.
+ * 모으면서 알리지 않고 틀릴 수 있는 자리 셋을 여기서 못 박는다.
  */
 test('★ 어느 트윈에서 온 신호인지 붙는다 — 조치는 결국 그 트윈에 보내야 한다', () => {
   const d = mergeLensAttentions([

package/test/axis-read.test.ts

@@ -20,7 +20,7 @@ test('경로가 없는 축은 이름으로 읽는다 — 지금까지의 거동'
   assert.deepEqual(axisValueOf(state, { axis: 'tasks' }), [], '빈 배열은 「없다」다 — 모른다가 아니다')
 })
 
-test('경로가 있으면 그 경로로 읽는다 — 중첩된 축이 조용히 사라지지 않게', () => {
+test('경로가 있으면 그 경로로 읽는다 — 중첩된 축이 오류 없이 사라지지 않게', () => {
   const state = { energy: { closed: [{ startMs: 1 }, { startMs: 2 }] } }
   const value = axisValueOf(state, { axis: 'demandWindows', path: 'energy.closed' })
   assert.equal(Array.isArray(value), true)
@@ -48,10 +48,11 @@ test('경로 따라가기는 중간 부재에서 멈춘다 — 오류를 내지
 
 test('커널 선언과 상태의 모양이 맞는다 — 선언한 경로에 정말 값이 있다', async () => {
   /*
-   * 선언(`path`)과 실제 상태의 모양이 어긋나면 이 배선은 조용히 빈 카드를 만든다. 그래서 **커널이 낸
+   * 선언(`path`)과 실제 상태의 모양이 어긋나면 이 배선은 알리지 않고 빈 카드를 만든다. 그래서 **커널이 낸
    * 상태로** 확인한다 — 선언을 읽는 쪽과 값을 만드는 쪽이 같은 모양을 쓰는지 보는 것이 요점이다.
    */
-  const { EmsKernel, axisInfo, ENERGY_EVENT, DEMAND_WINDOW_MS } = await import('@operato/twin-kernel')
+  const { EmsKernel, DEMAND_WINDOW_MS } = await import('@operato/twin-kernel')
+const { axisInfo, ENERGY_EVENT } = await import('@operato/ops-contract')
   const info = axisInfo('demandWindows')!
   assert.ok(info, '커널이 그 축을 선언해야 한다')
   assert.equal(info.path, 'energy.closed')
@@ -134,7 +135,7 @@ test('축을 이름으로 읽는 자리가 없다 — 선언된 경로를 지나
 test('수요 구간은 실제로 중첩된 축이다 — 이 가드가 지키는 대상이 있다', () => {
   /* 가드가 지킬 것이 없으면 그 가드는 초록으로 거짓을 말한다. 대상이 실재하는지 함께 본다. */
   const req = createRequire(import.meta.url)
-  const { TWIN_AXES } = req('@operato/twin-kernel')
+  const { TWIN_AXES } = req('@operato/ops-contract')
   const nested = (TWIN_AXES as any[]).filter(a => a.path)
 
   assert.ok(nested.length > 0, '경로를 가진 축이 하나도 없으면 이 가드는 의미가 없다')
@@ -156,7 +157,7 @@ test('수요 구간은 실제로 중첩된 축이다 — 이 가드가 지키는
  */
 test('id 가 없는 상태 축은 무엇이 항목을 가리키는지 선언한다', () => {
   const req2 = createRequire(import.meta.url)
-  const { TWIN_AXES } = req2('@operato/twin-kernel')
+  const { TWIN_AXES } = req2('@operato/ops-contract')
   const dw = (TWIN_AXES as any[]).find(a => a.axis === 'demandWindows')
 
   assert.ok(dw, '수요 구간 축이 있어야 한다')

package/test/backfill-shape.test.ts

@@ -0,0 +1,89 @@
+/*
+ * 지난 기록 채우기의 판단 — **무엇을 받고 무엇을 거절하나.**
+ *
+ * ── 왜 저널에만 쓰나 (2026-08-30) ──────────────────────────────────────────
+ * 커널의 상태는 「지금」이다. 늦게 온 옛 표본은 가드가 막는다(그렇게 만들었다). 지난 기록을 라이브
+ * 문으로 넣으면 가드에 막히거나 트윈의 시계가 과거로 끌린다. 그래서 이 길은 저널에만 쓰고,
+ * **상태를 바꾸는 사실은 아예 받지 않는다.**
+ *
+ * ── 보존 안에서만 (사용자 결정) ────────────────────────────────────────────
+ * 보존보다 오래된 것을 채우면 다음 정리에서 지워진다. 조용히 넣고 지워지면 아무도 모르므로
+ * 거절하고 이유를 말한다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { judgeBackfill, splitAlreadyThere, PERIOD_FACTS } from '../server/service/twin-backfill/backfill-shape.ts'
+
+const NOW = Date.parse('2026-08-30T00:00:00.000Z')
+const env = (eventType: string, eventTime: string, eventId = `${eventType}|${eventTime}`) => ({ eventType, eventTime, eventId })
+
+test('★ 마감된 구간 사실을 받는다', () => {
+  const r = judgeBackfill([env('energy.usage.period', '2026-08-29T00:00:00.000Z')], { nowMs: NOW, retentionDays: 7 })
+  assert.equal(r.keep.length, 1)
+  assert.equal(r.refused.length, 0)
+})
+
+test('★ 상태를 바꾸는 사실은 받지 않는다 — 저널에만 넣으면 상태와 저널이 갈라진다', () => {
+  const r = judgeBackfill(
+    [env('energy.measured', '2026-08-29T00:00:00.000Z'), env('energy.generated', '2026-08-29T00:00:00.000Z')],
+    { nowMs: NOW, retentionDays: 7 }
+  )
+  assert.equal(r.keep.length, 0)
+  assert.equal(r.refused.length, 2)
+  assert.match(r.refused[0].reason, /라이브 문으로 보내라/)
+})
+
+test('★ 보존보다 오래된 것은 거절하고 이유를 말한다 — 넣어도 지워진다', () => {
+  const r = judgeBackfill([env('energy.usage.period', '2026-08-01T00:00:00.000Z')], { nowMs: NOW, retentionDays: 7 })
+  assert.equal(r.keep.length, 0)
+  assert.match(r.refused[0].reason, /보존 기간\(7일\)보다 오래됐다/)
+  assert.match(r.refused[0].reason, /보존 기간을 늘려야 한다/, '무엇을 해야 하는지 함께 말한다')
+})
+
+test('보존 안쪽 경계는 받는다', () => {
+  const justInside = new Date(NOW - 7 * 86_400_000 + 1000).toISOString()
+  const r = judgeBackfill([env('energy.usage.period', justInside)], { nowMs: NOW, retentionDays: 7 })
+  assert.equal(r.keep.length, 1)
+})
+
+test('보존 정책이 없으면 오래됨을 판정하지 않는다 — 없는 기준으로 거절하지 않는다', () => {
+  const r = judgeBackfill([env('energy.usage.period', '2020-01-01T00:00:00.000Z')], { nowMs: NOW })
+  assert.equal(r.keep.length, 1)
+})
+
+test('★ 아직 오지 않은 시각은 거절한다 — 지난 기록이 아니다', () => {
+  const r = judgeBackfill([env('energy.usage.period', '2026-09-01T00:00:00.000Z')], { nowMs: NOW, retentionDays: 7 })
+  assert.equal(r.keep.length, 0)
+  assert.match(r.refused[0].reason, /아직 오지 않은 시각/)
+})
+
+test('시각을 읽을 수 없으면 거절한다', () => {
+  const r = judgeBackfill([env('energy.usage.period', 'n/a')], { nowMs: NOW, retentionDays: 7 })
+  assert.equal(r.keep.length, 0)
+  assert.match(r.refused[0].reason, /읽을 수 없다/)
+})
+
+test('받는 종류 다섯이 모두 마감된 구간 사실이다', () => {
+  for (const t of PERIOD_FACTS) {
+    const r = judgeBackfill([env(t, '2026-08-29T00:00:00.000Z')], { nowMs: NOW, retentionDays: 7 })
+    assert.equal(r.keep.length, 1, `${t} 를 받아야 한다`)
+  }
+})
+
+/* ── 같은 기간을 두 번 넣지 않는다 ────────────────────────────────────────── */
+
+test('★ 이미 있는 것은 건너뛴다 — 다시 읽어도 중복이 쌓이지 않는다', () => {
+  const a = env('energy.usage.period', '2026-08-29T00:00:00.000Z')
+  const b = env('energy.usage.period', '2026-08-29T01:00:00.000Z')
+  const r = splitAlreadyThere([a, b], new Set([a.eventId]))
+  assert.equal(r.fresh.length, 1)
+  assert.equal(r.fresh[0].eventId, b.eventId)
+  assert.equal(r.skipped, 1)
+})
+
+test('id 가 없으면 넣지 않는다 — 같은 사실인지 판단할 근거가 없다', () => {
+  const r = splitAlreadyThere([{ eventType: 'energy.usage.period', eventTime: '2026-08-29T00:00:00.000Z' }], new Set())
+  assert.equal(r.fresh.length, 0)
+  assert.equal(r.skipped, 1)
+})

package/test/boot-resume.test.ts

@@ -5,7 +5,7 @@
  * 서버를 한 번 재기동하면 등록부는 `running` 이라 말하는데 **아무 커널도 돌지 않았다**.
  * `bootstrap()` 은 상태만 되찾아 `recovered` 에 담았고, 커널을 세우는 것은 명시 mutation 뿐이었다.
  * 미러 트윈에서는 계측까지 끊겼다 — `startReferenceLiveFeed` 를 부르는 곳이 `importTwinReference`
- * 하나뿐이어서, 붙어 있던 커넥터가 조용히 떨어졌다(오류도 로그도 없이).
+ * 하나뿐이어서, 붙어 있던 커넥터가 알리지 않고 떨어졌다(오류도 로그도 없이).
  *
  * 이 시험이 지키는 것 넷:
  *  ① 부팅이 런타임까지 되살린다(상태 복구만으로는 도는 트윈이 아니다)
@@ -106,9 +106,9 @@ test('정책을 다시 선언하는 문이 있다 — 없으면 선언과 쓰임
     'utf-8'
   )
   assert.match(src, /async setTwinRestartPolicy\(/, '만든 뒤에 고칠 길이 있어야 한다')
-  /* 값은 엄격히 읽는다 — 모르는 말을 기본값으로 메우면 그 트윈의 이력이 남을지가 조용히 결정된다. */
+  /* 값은 엄격히 읽는다 — 모르는 말을 기본값으로 메우면 그 트윈의 이력이 남을지가 알리지 않고 결정된다. */
   assert.match(src, /readRestartPolicy\(restartPolicy, /)
-  /* 도는 런타임을 조용히 갈아 끼우지 않는다 — 다르다는 사실을 답에 담는다. */
+  /* 도는 런타임을 알리지 않고 갈아 끼우지 않는다 — 다르다는 사실을 답에 담는다. */
   assert.match(src, /appliesAtNextStart/)
 })
 
@@ -130,7 +130,7 @@ test('피드 재개는 등록부가 「도는 미러」라고 말하는 것만
   assert.match(live, /export async function resumeReferenceLiveFeeds/, '재개 함수가 있어야 한다')
   assert.match(live, /r\.status === 'running' && r\.restartPolicy === 'resync'/, '도는 미러만 골라야 한다')
   assert.match(live, /discoverSites/, '사이트 서술자는 다시 찾아서 얻는다(hint 를 남기지 않았다)')
-  /* 붙지 않은 미러는 「도는데 아무것도 오지 않는」 트윈이다 — 조용히 넘기지 않는다. */
+  /* 붙지 않은 미러는 「도는데 아무것도 오지 않는」 트윈이다 — 알리지 않고 넘기지 않는다. */
   assert.match(live, /NOT reattached/, '못 붙인 것은 이유와 함께 남겨야 한다')
 })
 
@@ -159,7 +159,11 @@ test('시뮬 브로드캐스팅도 모아서 한 번 — delta 마다 전 상태
 })
 
 test('flush 가 시뮬도 본다 — 브로드캐스팅과 저널은 둘 다, state 채널은 라이브만', () => {
-  const body = methodOf(engine, 'flushLiveBroadcasts')
+  /*
+   * 창의 본문은 `flushBroadcastWindow` 로 옮겼다(2026-08-27). `flushLiveBroadcasts` 는 겹쳐 도는 것을
+   * 막는 문만 남았다 — 발행이 청크로 나뉘어 한 창이 주기를 넘길 수 있게 됐기 때문이다.
+   */
+  const body = methodOf(engine, 'flushBroadcastWindow')
   assert.equal(/mode !== 'live'\) continue/.test(body), false, '시뮬을 건너뛰는 모양으로 되돌아갔다')
   assert.match(body, /const isLive = inst\.mode === 'live'/, '모드는 가르되 둘 다 브로드캐스팅해야 한다')
   /*
@@ -181,7 +185,16 @@ test('구독자 하나가 호스트를 죽이지 못한다 — 그리고 못 보
   const guardBody = methodOf(engine, 'publishGuarded')
   assert.equal((engine.match(/pubsub\.publish\(/g) ?? []).length, 1, '가드를 거치지 않는 직접 브로드캐스팅이 남아 있다')
   assert.match(guardBody, /pubsub\.publish\(/, '그 하나는 가드 안에 있어야 한다')
-  assert.match(guardBody, /catch/, '브로드캐스팅 실패를 잡아야 한다(타이머 콜백에서 오류가 나면 프로세스가 끝난다)')
+  /*
+   * ── 이 가드가 무엇을 못 하는지 (2026-08-27 측정으로 확인) ───────────────────
+   * 이 try/catch 는 **대기열 넘침을 막지 못한다.** 그 예외는 `EventTarget` 이 부른 리스너 안에서 나고
+   * 런타임은 그것을 호출자에게 주지 않는다(uncaughtException 으로 간다). 그것을 막는 것은 한 차례에
+   * 발행하는 수를 상한 아래로 두는 것이고, 그 규율은 `broadcast-queue-overflow.test.ts` 가 지킨다.
+   *
+   * 그래도 남긴다: 직렬화 실패처럼 `publish` 가 직접 던지는 경우를 잡고, 못 보낸 태그의 시그니처를
+   * 되돌린다(남겨 두면 그 태그가 오류 없이 영원히 낡는다).
+   */
+  assert.match(guardBody, /catch/, 'publish 가 직접 던지는 경우는 잡아야 한다')
   assert.match(guardBody, /twinWarn/, '못 보낸 사실은 남아야 한다(삼키면 「보냈는데 낡았다」가 된다)')
   /* 시그니처를 남겨 두면 다음 주기에 「무변화」로 건너뛰고 그 태그는 영원히 낡는다. */
   assert.match(engine, /if \(!this\.publishGuarded\('data'[\s\S]{0,80}sigs\.delete\(tag\)/, '실패한 태그의 시그니처를 되돌려야 한다')
@@ -204,7 +217,7 @@ test('굶김은 예산과 다른 문턱으로 판정한다 — 조금 느린 트
 test('한 번으로 내리지 않고, 한 번 내려오면 연속이 끊긴다', () => {
   const body = methodOf(engine, 'guardStarvation')
   assert.match(body, /streak < this\.STARVE_STREAK\) return/, '연속이 차기 전에는 멈추지 않는다')
-  /* 웜스타트 직후 첫 틱은 원래 무겁다(복구한 상태를 처음 접는다) — 그것으로 내리면 재개가 무의미해진다. */
+  /* 웜스타트 직후 첫 틱은 원래 무겁다(복구한 상태를 처음 계산한다) — 그것으로 내리면 재개가 무의미해진다. */
   assert.match(body, /this\.starveStreak\.delete\(key\)[\s\S]{0,40}return/, '문턱 아래면 연속을 끊어야 한다')
 })