@things-factory/headless-twin 10.0.18 → 10.1.0

package/server/engine/event-time.ts

@@ -0,0 +1,96 @@
+/*
+ * **레코드가 말하는 「언제 일어났나」를 읽는다** — fact 종류마다 칸 이름이 다르다.
+ *
+ * ── 같은 defect 가 세 번째다 ────────────────────────────────────────────────
+ * `canonical-ingest.ts` 가 `eventTime ?? at` **두 이름만** 보고 있었다. 그 주석에 이미 두 번의 사고가
+ * 적혀 있다 — 처음엔 `eventTime` 하나만 봐서 energy connector 의 사실 18,150건이 polling 시각으로
+ * 찍혔고, 그 다음에 `at` 을 더했다.
+ *
+ * 세 번째는 `nonconformance.disposition` 이었다.
+ *
+ * ```
+ * [측정함 2026-09-06, mes-line-a backfill 뒤]
+ * event_time  2026-09-05 23:50:51    payload decidedAt  2026-09-01T02:50:51.832Z     5일 차이
+ * ```
+ *
+ * ── root cause: 선언과 봉투가 다른 이름을 쓴다 ──────────────────────────────
+ * 운영 레코드의 봉투 시각은 `at` 이다(`OperationalRecordEnvelopeFields`). 그런데 처분 fact 는 자기
+ * 시각을 **payload 의 `decidedAt`** 에 싣는다 — contract 가 그 자리에 required 로 선언했고 plant 도
+ * 맞게 보낸다. 읽는 쪽에 그 이름이 없어서 `defaultEventTime`(= ingest 시각)으로 떨어졌다.
+ *
+ * ── push 경로에서는 안 보인다 ───────────────────────────────────────────────
+ * 사실이 나자마자 보내면 ingest 시각과 event 시각이 몇 초 차이다. backfill 이 그 간격을 벌려서
+ * 드러냈다 — **backfill 이 만든 defect 가 아니라 원래 있던 것이 보인 것**이다.
+ *
+ * ── 이름을 늘리는 것으로는 안 끝난다 ────────────────────────────────────────
+ * 다음 fact 종류가 또 다른 이름을 쓰면 같은 자리를 밟는다. 그래서 두 가지를 함께 한다.
+ *
+ * ```
+ * 1  종류마다의 칸 이름을 한 표에 둔다     새 종류를 더할 때 여기가 눈에 띈다
+ * 2  못 읽으면 그 수를 낸다                조용히 ingest 시각으로 떨어지지 않는다
+ * ```
+ *
+ * 종류 판정은 **contract 의 것을 부른다**(`operationalKindOf`). 여기서 다시 짐작하면 두 곳이 다른
+ * 답을 내고, 그때 어느 쪽이 맞는지 아무도 모른다.
+ */
+import { operationalKindOf } from '@operato/ops-contract'
+
+/**
+ * 운영 fact 종류가 자기 시각을 싣는 칸 — 봉투의 `at` 이 없을 때 읽는다.
+ *
+ * 새 종류가 자기 시각을 payload 에 실으면 여기 한 줄을 더한다.
+ */
+export const KIND_TIME_FIELD: Record<string, string> = {
+  /* `DispositionFact.decidedAt` — contract 가 required 로 선언했다. */
+  disposition: 'decidedAt'
+}
+
+/*
+ * `equipment-period` 는 일부러 안 넣는다. 그 fact 의 봉투 시각은 **구간의 끝**이고(그때 성립한다),
+ * `recordTime` 은 「그 구간을 언제 적었나」다. 둘이 갈려 있어야 늦게 적은 구간이 늦게 일어난 것으로
+ * 읽히지 않는다 — contract 가 그 판단을 이미 적어 두었다.
+ */
+
+function iso(v: unknown): string | undefined {
+  return typeof v === 'string' && v.trim() ? v : undefined
+}
+
+/**
+ * 이 레코드가 말하는 시각. **못 읽으면 `undefined`** — 여기서 지금 시각으로 채우지 않는다.
+ *
+ * 보는 순서는 공통 이름이 먼저다. connector 가 봉투 층에서 시각을 실어 주면 그것이 그 레코드에 대한
+ * 가장 바깥의 판단이고, 종류마다의 칸은 그것이 없을 때 읽는다.
+ */
+export function factEventTime(record: unknown): string | undefined {
+  const r = record as any
+  const common = iso(r?.eventTime) ?? iso(r?.at)
+  if (common) return common
+
+  const kind = operationalKindOf(record)
+  const named = kind ? KIND_TIME_FIELD[kind] : undefined
+  return named ? iso(r?.[named]) : undefined
+}
+
+/**
+ * 시각을 못 읽은 레코드를 종류별로 센다 — **조용히 ingest 시각으로 떨어진 것들.**
+ *
+ * 오류가 아니다. 절대값 snapshot 관측은 원본의 갱신 시각이 아니라 polling 순간이 맞는 시각이라
+ * (「어제 값을 오늘 봤다」는 「어제 일어났다」가 아니다) 여기 세어지는 것이 정상이다.
+ *
+ * 다만 그 수가 어디에도 안 남으면 `event_time == created_at` 이 유일한 단서가 되고, 그것은 우연히
+ * 같은 것과 구별되지 않는다.
+ */
+export function undatedByKind(records: readonly unknown[]): Record<string, number> {
+  const out: Record<string, number> = {}
+  for (const r of records) {
+    if (factEventTime(r) !== undefined) continue
+    const kind = operationalKindOf(r) ?? ((r as any)?.type as string) ?? '(종류 모름)'
+    out[kind] = (out[kind] ?? 0) + 1
+  }
+  return out
+}
+
+/** 표에 있는 종류인데 시각을 못 읽었다 — 그것은 실제로 결함이다. */
+export function shouldHaveTime(kind: string): boolean {
+  return kind in KIND_TIME_FIELD
+}

package/server/engine/index.ts

@@ -29,3 +29,23 @@ export * from './operation-basis.js'
 export * from './measured-yield.js'
 export * from './declared-stimulus.js'
 export * from './integration-coverage.js'
+
+/*
+ * 사실의 정체(identity)와 시각을 판단하는 함수들.
+ *
+ * 모듈 전체를 export 하지 않고 이 둘만 내보낸다. `FactDeduper` 같은 상태를 가진 클래스는 커널
+ * 안에서만 쓰여야 하고, 밖에서 인스턴스를 따로 만들면 중복 판단 기억이 두 벌이 된다.
+ *
+ * 밖에서 이 둘이 필요한 이유는 하나다 — 저널에 앉은 사실이 제대로 된 정체와 시각을 가졌는지
+ * 확인할 때, 유입할 때와 **똑같은 함수로** 판단해야 하기 때문이다. 확인하는 쪽이 규칙을 다시
+ * 구현하면 두 규칙이 어긋나는 날 확인이 조용히 통과한다.
+ */
+export { factIdentity } from './ingest-dedupe.js'
+
+/*
+ * `shouldHaveTime` is the part that matters outside: it separates "this record legitimately has no
+ * time of its own" (a snapshot observation — the polling moment IS the right time) from "the kind
+ * declares a time field and we could not read it", which is a real defect. Anything checking the
+ * journal must use this split rather than inventing its own, or it reports healthy rows as broken.
+ */
+export { factEventTime, shouldHaveTime, undatedByKind } from './event-time.js'

package/server/engine/ingest-dedupe.ts

@@ -45,34 +45,162 @@ function timeOf(envelope: any): number | undefined {
 }
 
 /**
- * 이 봉투가 말하는 대상 — 어휘마다 이름이 다르므로 아는 이름을 모두 본다.
+ * 이 봉투가 말하는 것을 **가르는 값들** — 하나라도 다르면 다른 사실이다.
  *
- * 순서가 뜻을 갖는다: 주체를 먼저 본다. 설비 사실은 「지금 붙어 있는 작업」을 함께 싣고, 작업 사실은
- * 「소속 오더」를 함께 싣는다. 아무 이름이나 먼저 보면 참조를 주체로 읽는다(승격 키에서 겪은 것과 같다).
+ * ── 예전에는 하나만 골랐다 (2026-09-05 실측) ───────────────────────────────
+ * 아는 이름을 순서대로 보고 **먼저 걸리는 하나**를 대상으로 삼았다. 「주체를 먼저 본다」는 판단
+ * 자체는 옳다 — 설비 사실은 「지금 붙어 있는 작업」을 참조로 싣는다. 그런데 **고르고 나머지를
+ * 버린 것**이 결함이었다.
+ *
+ * 실제로 난 일: plant 이 실적 둘을 보냈는데 한 건이 저널에 안 남았다.
+ *
+ *   seq 36   quality.output   moverId EQ-CT-MWELD-01 · taskId PR-CT-WIRE-01 · goodCount 12
+ *   seq 41   quality.output   moverId EQ-CT-MWELD-01 · taskId PR-CT-WIRE-02 · goodCount  9
+ *
+ * 두 실적의 시각이 같았고(원본이 끝시각을 복사) `moverId` 가 `taskId` 보다 먼저라 **둘이 한 사실이
+ * 됐다.** 거부가 아니라 되풀이로 세어졌다 — `offered 5 · rejected 0 · journaled 3`.
+ *
+ * **구별할 값이 이미 봉투 안에 있었는데 판정이 그것을 안 봤다.**
+ *
+ * ── 그리고 EPCIS 도 같았다 ─────────────────────────────────────────────────
+ * 저널 246만 건에 현재 규칙을 다시 걸어 보니 겹치는 묶음이 여섯이었고, 전부 이 모양이다.
+ *
+ *   같은 EPC · 같은 밀리초
+ *     ① bizStep receiving      action ADD      disposition sellable_accessible
+ *     ② bizStep commissioning  action OBSERVE  disposition reserved
+ *
+ * **한 개체의 서로 다른 관측**이다. EPCIS 에서 이상한 일이 아닌데 규칙이 그 셋을 안 봤다.
+ *
+ * ── 왜 넓히는 쪽이 맞나 ────────────────────────────────────────────────────
+ * 이 파일이 스스로 적어 둔 값이 그것이다 — 「알리지 않고 잃는 것보다 두 번 세는 것이 낫다」.
+ * 지금 거동은 **알리지 않고 잃는 쪽**이었다.
+ *
+ * 넓혀도 되풀이는 그대로 걸린다: 같은 봉투를 다시 보내면 **이 값들이 전부 같다.** 넓히는 것은
+ * 「다른 사실을 합치지 않는다」만 강해지고 「되풀이를 잡는다」는 안 약해진다.
  */
-function targetOf(envelope: any): string | undefined {
+function discriminatorsOf(envelope: any): string[] {
   const d = envelope?.data ?? {}
-  const first = (...vals: unknown[]) => {
-    for (const v of vals) {
-      const s = String(v ?? '').trim()
-      if (s) return s
-    }
-    return undefined
+  const out: string[] = []
+  const put = (name: string, v: unknown) => {
+    const t = String(v ?? '').trim()
+    if (t) out.push(`${name}=${t}`)
   }
-  return first(
-    d.meterId,
-    d.equipmentId,
-    d.moverId,
-    d.taskId,
-    d.orderId,
-    d.personId,
-    d.assetId,
-    d.locationId,
-    d.epcList?.[0],
-    d.parentID,
-    d.quantityList?.[0]?.epcClass,
-    d.transformationID
-  )
+
+  /*
+   * 주체·참조를 **다 적는다.** 순서는 값이 아니라 이름으로 고정되므로 봉투마다 흔들리지 않는다.
+   *
+   * ⚠ **이 목록은 계약의 `identity` 선언을 손으로 옮긴 것이다.** 계약이 kind 마다 무엇이 그 사실을
+   * 가리키는지 이미 선언하는데(`operational-ingest.ts` 의 `SPECS[kind].identity`), 그것을 내보내지
+   * 않아서 여기가 따로 들고 있다.
+   *
+   * 그래서 새 kind 가 생기면 여기가 조용히 뒤처진다. 실제로 두 번 그랬다 — `subjectId`(처분)와
+   * `testableObjectId`(시험)가 빠져 있었고, 그동안 그 두 종류는 정체를 못 만들거나 서로 다른 사실이
+   * 뭉칠 수 있었다.
+   *
+   * 계약이 `operationalIdentityField(kind)` 를 내보내면 이 목록을 지운다. 그 문을 열어 두었고
+   * 배포를 기다린다.
+   */
+  put('meter', d.meterId)
+  put('equipment', d.equipmentId)
+  put('mover', d.moverId) // vocabulary-guard: allow — 봉투의 옛 세대 필드 이름(저장된 계약)
+  put('task', d.taskId)
+  put('order', d.orderId)
+  put('person', d.personId)
+  put('asset', d.assetId)
+  put('location', d.locationId) // vocabulary-guard: allow — 같음
+  put('epc', d.epcList?.[0])
+  put('parent', d.parentID)
+  put('class', d.quantityList?.[0]?.epcClass)
+  put('transformation', d.transformationID)
+  /*
+   * ── 주체가 `subjectId` 인 사실이 있다 (2026-09-06 측정) ──────────────────────
+   * 부적합 처분과 시험 결과는 **표준 `TestableObjectID` 와 같은 자리**를 쓴다(로트 · 설비 · 자리에
+   * 두루 쓰는 하나의 이름). 그 이름이 여기 없어서 두 종류가 **정체를 못 만들었다** —
+   * `parts` 가 비면 `factIdentity` 가 `undefined` 를 내고, 그러면 dedupe 밖이다.
+   *
+   * 실제로 그랬다. `fillTwinScope` 를 두 번 돌릴 때마다 그 둘이 7건씩 다시 앉았다(처분 4 · 시험 3).
+   * 나머지 34건은 걸러졌는데 이 둘만 계속 늘었다.
+   */
+  put('subject', d.subjectId)
+  put('spec', d.specId)
+  /*
+   * 시험 결과의 주체는 `testableObjectId` 다 — 표준 `TestableObjectID` 의 이름을 그대로 쓴다.
+   *
+   * 이 이름이 없어서 **같은 명세로 같은 시각에 잰 서로 다른 로트가 한 사실로 뭉쳤다.** 중복이 생기는
+   * 것보다 나쁘다 — 두 로트의 시험 결과 중 하나가 사라진다.
+   *
+   * 실제로 `mes-miratek` 에 같은 시험 결과가 10건 있었다(2026-09-06 확인). 그것은 뭉친 것이 아니라
+   * 반대로 dedupe 를 못 지난 것인데, 같은 자리에서 뭉치는 쪽도 열려 있었다.
+   */
+  put('object', d.testableObjectId)
+  /* 완료 선언의 주체 — 「이 축은 여기까지가 전부다」를 말하는 축 이름. */
+  put('axis', d.completeAxis)
+
+  /*
+   * EPCIS 는 「무엇을 말하는 관측인가」가 이 셋으로 갈린다. 한 개체가 한 순간에 두 관측을 갖는
+   * 것은 표준에서 정상이고, 이것을 안 보면 뒤엣것이 사라진다.
+   */
+  put('bizStep', d.bizStep)
+  put('action', d.action)
+  put('disposition', d.disposition)
+
+  /*
+   * ── 변환은 **무엇이 무엇으로 되었나**로 갈린다 (2026-09-07 측정) ─────────────
+   * 이 자리가 없어서 **사실 하나가 없어졌습니다.** 거절이 아니라 되풀이로 세어져서 경고도 없었습니다.
+   *
+   * ```
+   * plant outbox seq 37   in LOT-CT-SIDE-001 24개  →  out LOT-CT-MAIN-003 12개
+   * plant outbox seq 42   in LOT-CT-SIDE-001 18개  →  out LOT-CT-MAIN-004  9개
+   *                       transformationID · bizStep · 초까지 전부 같다
+   * 저널에 남은 것        LOT-CT-MAIN-003 하나
+   * ```
+   *
+   * `LOT-CT-MAIN-004` 를 어느 패널로 만들었는지 트윈이 답하지 못하는 상태였습니다.
+   *
+   * 그리고 **구별할 값이 봉투 안에 이미 있었습니다** — `outputQuantityList[0].epcClass` 가 서로
+   * 다릅니다. 이 파일 머리말이 적어 둔 그 모양 그대로입니다: 판정이 그것을 안 봤습니다.
+   *
+   * 산출만 보지 않고 **입력도 봅니다.** 같은 로트를 같은 초에 두 번 소비하면서 산출 이름이 같은
+   * 경우(수량만 다른 분할)가 남고, 그때 입력 수량이 유일한 차이입니다. 수량까지 넣는 이유가 그것입니다.
+   */
+  put('inClass', classOf(d.inputQuantityList))
+  put('inEpc', d.inputEPCList?.[0])
+  put('inQty', qtyOf(d.inputQuantityList))
+  put('outClass', classOf(d.outputQuantityList))
+  put('outEpc', d.outputEPCList?.[0])
+  put('outQty', qtyOf(d.outputQuantityList))
+  /*
+   * 담김의 자식도 같은 이유로 본다 — 한 팔레트에 서로 다른 묶음을 같은 초에 두 번 실으면 뒤엣것이
+   * 사라진다. 위 변환에서 실제로 그렇게 잃었으니 여기도 함께 막는다(한 종류만 고치면 나머지에 남는다).
+   */
+  put('childEpc', d.childEPCs?.[0])
+  put('childClass', classOf(d.childQuantityList))
+  put('childQty', qtyOf(d.childQuantityList))
+  /*
+   * 어느 오더의 사실인가도 정체의 일부다. 같은 공정을 같은 초에 두 오더로 돌리는 것은 정상이고,
+   * 이것을 안 보면 뒤엣것이 사라진다.
+   */
+  put('tx', d.bizTransactionList?.[0]?.bizTransaction)
+
+  return out
+}
+
+/** 수량 목록의 첫 종류 — 목록이 비면 `undefined`(빈 문자열을 넣지 않는다). */
+function classOf(list: unknown): string | undefined {
+  const first = Array.isArray(list) ? (list[0] as any) : undefined
+  const v = first?.epcClass
+  return typeof v === 'string' && v.trim() ? v : undefined
+}
+
+/**
+ * 수량 목록을 수까지 적는다 — 종류가 같고 수량만 다른 사실을 가른다.
+ *
+ * 목록 전체를 적는다. 첫 원소만 보면 「같은 것 둘 + 다른 것 하나」가 첫 원소로는 구별되지 않는다.
+ */
+function qtyOf(list: unknown): string | undefined {
+  if (!Array.isArray(list) || !list.length) return undefined
+  const parts = list.map((x: any) => `${x?.epcClass ?? ''}:${x?.quantity ?? ''}${x?.uom ? '/' + x.uom : ''}`)
+  return parts.join('|')
 }
 
 /**
@@ -81,14 +209,41 @@ function targetOf(envelope: any): string | undefined {
  * 대상이나 시각을 알 수 없으면 **정체를 만들지 않는다**(`undefined`). 그때는 거르지 않고 통과시킨다 —
  * 모르는 것을 같다고 판단하면 서로 다른 사실이 하나로 합쳐진다. 알리지 않고 잃는 것보다 두 번 세는 것이 낫다.
  */
+/**
+ * 정체를 못 만든 사실을 **종류별로** 센다 — dedupe 밖으로 나간 것들.
+ *
+ * 이 수가 0이 아니면 그 종류는 다시 받을 때마다 저널에 다시 앉는다. 그 종류의 주체 이름을
+ * `discriminatorsOf` 에 더해야 한다.
+ */
+const unidentified: Record<string, number> = {}
+
+/** 지금까지 정체를 못 만든 것 — 종류별. 읽고 비운다. */
+export function takeUnidentified(): Record<string, number> {
+  const out = { ...unidentified }
+  for (const k of Object.keys(unidentified)) delete unidentified[k]
+  return out
+}
+
 export function factIdentity(envelope: any): string | undefined {
   const type = String(envelope?.eventType ?? '').trim()
   if (!type) return undefined
-  const target = targetOf(envelope)
-  if (!target) return undefined
+  const parts = discriminatorsOf(envelope)
+  /*
+   * **정체를 못 만들면 dedupe 밖이다** — 그 사실은 다시 받을 때마다 새로 앉는다.
+   *
+   * 오늘 그것으로 저널이 부풀었다(처분·시험이 `subjectId` 를 주체로 쓰는데 그 이름이 위 목록에
+   * 없었다). 조용히 `undefined` 를 내면 다음 종류에서 또 나고 그때도 아무 흔적이 없다.
+   *
+   * 그래서 무엇이 정체를 못 만들었는지 센다(`unidentified`). 세는 것이지 막는 것이 아니다 —
+   * 정체를 못 만든다고 사실을 버리면 그것이 더 나쁘다.
+   */
+  if (!parts.length) {
+    unidentified[type] = (unidentified[type] ?? 0) + 1
+    return undefined
+  }
   const at = timeOf(envelope)
   if (at === undefined) return undefined
-  return `${type}|${target}|${at}`
+  return `${type}|${parts.join('&')}|${at}`
 }
 
 /**
@@ -109,6 +264,27 @@ export class FactDeduper {
   private seen = new Set<string>()
   private order: string[] = []
 
+  /**
+   * 이미 아는 것으로 **미리 기억한다** — 저널에서 읽어 채울 때.
+   *
+   * ── 왜 필요한가 (2026-09-06 측정) ─────────────────────────────────────────
+   * 이 기억은 프로세스 안에만 있다. 재기동하면 비워지고, 그 뒤 backfill 을 돌리면 **이미 저널에
+   * 있는 사실도 「처음 본 것」**이 된다.
+   *
+   * 실제로 그랬다. `mes-line-a` 를 재기동 뒤 backfill 하니 39건이 전부 다시 앉아 저널이
+   * 44 → 83건이 되고 44가지가 중복이 됐다.
+   *
+   * push 경로에서는 안 보인다. 재전송이 몇 분 안에 오므로 창 안에서 걸린다. **backfill 이 그 전제를
+   * 깬다** — 몇 달 전 사실을 지금 받으니 재기동 한 번이면 그 구간이 통째로 다시 앉는다.
+   *
+   * 그래서 backfill 이 부르기 전에 그 구간의 정체를 저널에서 읽어 여기 넣는다.
+   */
+  remember(identities: readonly string[]): number {
+    let added = 0
+    for (const id of identities) if (id && !this.seen.has(id)) { this.known(id); added++ }
+    return added
+  }
+
   /** 이 사실을 본 적이 있나 — 없으면 기억하고 `false`. */
   private known(identity: string): boolean {
     if (this.seen.has(identity)) return true

package/server/engine/ingest-health.ts

@@ -63,6 +63,8 @@ export interface IngestWindow {
    * 세면 그 개선도, 되돌아가는 것도 보이지 않는다.
    */
   flushes: number
+  /** 이 창에서 저널에 안 간 어휘 요소의 수 — 사라진 것이 아니라 저널로 가지 않는 것이다. */
+  vocabulary: number
 }
 
 /** 거부 표본 하나 — 매핑을 고치려면 실제 모양을 봐야 한다. */
@@ -85,6 +87,17 @@ export interface IngestLedger {
   /** 누적 제시·거부·미전달. */
   offered: number
   rejected: number
+  /**
+   * **저널에 안 가는 어휘 요소의 수** — 로트 번호·소비기한처럼 시각축이 없는 값.
+   *
+   * ── 왜 세나 (2026-09-05, 인티그레이션 레인이 셈으로 찾음) ─────────────────
+   * 어휘는 일부러 저널로 안 간다(§`canonical-ingest`) — 그것이 옳다. 그런데 **그 수를 빼 주는
+   * 자리가 없어서** 「보낸 것 − 앉은 것」이 안 맞고, 그 차이를 「사라졌다」로 읽게 된다.
+   *
+   * 실제로 그랬다: 커서 20 · 저널 17 · 어휘 1 → 사람이 손으로 세서 「둘이 빈다」를 찾았다. 그
+   * 뺄셈을 코드가 하려면 이 항이 있어야 한다.
+   */
+  vocabulary: number
   undelivered: number
   /** 누적 — 적힌 행과 두드린 횟수. */
   rows: number
@@ -323,6 +336,21 @@ export function recordIngestSource(ledger: IngestLedger, source: string, count:
 }
 
 /** 같은 사실이 두 번 와서 버린 수 — 알리지 않고 버리지 않는다. */
+/**
+ * **저널에 안 간 어휘 요소를 센다** — 없어진 것이 아니라 저널로 가지 않는 것이다.
+ *
+ * 어휘(로트 번호·소비기한 등)는 시각축이 없어 일부러 저널로 안 간다. 그런데 그 수를 빼 주는 자리가
+ * 없으면 「보낸 것 − 앉은 것」이 안 맞고, 그 차이를 **사라진 것으로 읽게 된다.**
+ *
+ * 창을 굴리지 않는다 — 부르는 쪽(`recordIngest`)이 이미 굴린 뒤에 부른다. 여기서 또 굴리면 한
+ * 유입이 두 창에 걸친다.
+ */
+export function recordVocabulary(ledger: IngestLedger, count: number): void {
+  if (!Number.isFinite(count) || count <= 0) return
+  ledger.vocabulary += count
+  ledger.window.vocabulary += count
+}
+
 export function recordDuplicates(ledger: IngestLedger, count: number, nowMs: number): void {
   if (count <= 0) return
   ledger.duplicates += count
@@ -398,7 +426,7 @@ export const HEALTHY_ACCEPTED_RATIO = 0.95
 
 export function newIngestLedger(): IngestLedger {
   return {
-    window: { startMs: -1, endMs: -1, offered: 0, rejected: 0, undelivered: 0, rows: 0, flushes: 0 },
+    window: { startMs: -1, endMs: -1, offered: 0, rejected: 0, vocabulary: 0, undelivered: 0, rows: 0, flushes: 0 },
     trend: [],
     trendDropped: 0,
     offered: 0,
@@ -410,6 +438,7 @@ export function newIngestLedger(): IngestLedger {
     lastUndeliveredAtMs: -1,
     bySource: {},
     duplicates: 0,
+    vocabulary: 0,
     lastDuplicateAtMs: -1,
     byReason: {},
     reasonsCapped: false,
@@ -447,7 +476,7 @@ export function rollIngestWindow(
 
   const closed: IngestWindow = { ...ledger.window, endMs: nowMs }
   ledger.trend.push(closed)
-  ledger.window = { startMs: nowMs, endMs: -1, offered: 0, rejected: 0, undelivered: 0, rows: 0, flushes: 0 }
+  ledger.window = { startMs: nowMs, endMs: -1, offered: 0, rejected: 0, vocabulary: 0, undelivered: 0, rows: 0, flushes: 0 }
 
   if (ledger.trend.length > TREND_LIMIT) {
     const drop = ledger.trend.length - TREND_LIMIT
@@ -614,6 +643,21 @@ export type SyncVerdict =
   | 'no-traffic' /** 피드는 붙었는데 제시가 0 — 원천·망을 본다 */
   | 'not-connected' /** 피드 자체가 없다 — 결선한다 */
   | 'not-applicable' /** 원본이 먹이지 않는 트윈(시뮬)·멈춘 트윈 — 물을 대상이 아니다 */
+  /**
+   * **지금은 조용한 것이 정상이다** — 원천이 지금 시각에 내놓지 않는다.
+   *
+   * ── 왜 초록도 빨강도 아닌가 (2026-09-04) ─────────────────────────────────
+   * 태양광은 밤에 발전하지 않고, 업무시간만 도는 원천은 저녁에 아무것도 내지 않는다. 그 침묵을
+   * `no-traffic` 으로 부르면 **정상인 밤마다 절반이 빨갛게 난다.** 거짓 빨강이 쌓이면 진짜 빨강도
+   * 같이 안 읽힌다 — 오늘 UX 레인이 「늘 참인 경고는 벽지가 된다」고 한 것과 같은 부류다.
+   *
+   * 그렇다고 `syncing` 도 아니다. 지금 받고 있는 것이 아니고, 초록으로 칠하면 **밤에 정말 끊긴
+   * 원천**을 아침까지 아무도 모른다.
+   *
+   * 그래서 셋째 값이다: 「지금은 안 오는 것이 맞다」. 화면은 이것을 회색으로 그리고, 다음에 올
+   * 시각을 함께 말할 수 있다.
+   */
+  | 'expected-quiet'
   | 'unknown' /** 한 번도 받지 않았거나 창이 아직 닫히지 않았다 — 기다린다 */
 
 export function syncVerdictOf(args: {
@@ -627,6 +671,27 @@ export function syncVerdictOf(args: {
   nowMs?: number
   /** 마지막으로 **버려진** 시각. 한 번도 없으면 `-1`. */
   lastUndeliveredAtMs?: number
+  /**
+   * **이 원천은 이만큼 조용해도 정상이다** — 긷는 주기를 원천 쪽이 선언한 값.
+   *
+   * 없으면 창 하나(`STALE_AFTER_MS`)로 견준다(지금까지의 거동). 15분마다 긷는 원천은 그 값을
+   * 선언해야 하고, 안 하면 긷는 사이마다 「유입 없음」으로 보인다 — 이 파일이 아래에서 그 한계를
+   * 스스로 적어 두고 있었다.
+   *
+   * 장부는 원천의 주기를 알 수 없다. **선언만이 그것을 아는 유일한 길이다.**
+   */
+  expectedSilenceMs?: number
+  /**
+   * **지금이 그 원천의 조용한 시간인가** — 근무 달력 판정의 결과만 받는다.
+   *
+   * 달력 자체를 여기서 보지 않는다: 이 함수는 순수하고, 달력·시간대·시각 해석은 계약이 이미
+   * 한 자리에서 한다(`inWorkCalendar`·`offCalendarAt`). 부르는 쪽이 그것을 불러 참·거짓만 준다 —
+   * `capabilityOf` 가 `requiredTests` 를 받는 것과 같은 규율이다.
+   *
+   * **모르면 주지 않는다.** `false` 로 채우면 「지금은 활동 시간이다」를 단언하는 것이 되고, 달력을
+   * 선언하지 않은 원천이 전부 그렇게 읽힌다.
+   */
+  quietNow?: boolean
   /**
    * 지금까지 제시된 누적 수 — **「받고 있는 중」과 「오는 것이 없다」를 가르는 사실**이다.
    *
@@ -672,9 +737,28 @@ export function syncVerdictOf(args: {
    * 한계 — 한 창(10분)보다 **느리게 긷는 원천**은 긷는 사이에 「유입 없음」으로 보인다. 장부는 원천의
    * 주기를 모르므로 이보다 정확히 답할 수 없다. 주기를 알게 되면 그 값으로 견주는 것이 맞다.
    */
+  /*
+   * 견줄 길이는 **원천이 선언한 값이 있으면 그것**이다(§`expectedSilenceMs`). 없으면 창 하나 —
+   * 위 한계 문단이 말하는 그대로다.
+   */
+  const silenceLimitMs = typeof args.expectedSilenceMs === 'number' && args.expectedSilenceMs > 0
+    ? args.expectedSilenceMs
+    : STALE_AFTER_MS
+
   if (typeof args.lastAtMs === 'number' && typeof args.nowMs === 'number') {
-    if (args.lastAtMs < 0) return 'unknown' /* 붙었지만 한 번도 받지 않았다 — 기다린다 */
-    if (args.nowMs - args.lastAtMs > STALE_AFTER_MS) return 'no-traffic'
+    if (args.lastAtMs < 0) {
+      /* 한 번도 받지 않았는데 지금이 조용한 시간이면 「기다린다」가 아니라 「지금은 맞다」다. */
+      return args.quietNow === true ? 'expected-quiet' : 'unknown'
+    }
+    if (args.nowMs - args.lastAtMs > silenceLimitMs) {
+      /*
+       * 오래 조용하다. **지금이 그 원천의 조용한 시간이면 그것이 정상이다.**
+       *
+       * 이 갈래를 위쪽(버려지는 중·피드 없음)보다 뒤에 두는 이유: 사실이 사라지고 있거나 결선이
+       * 없는 것은 **몇 시든 문제**다. 밤이라고 덮으면 밤새 새는 것을 아침에 안다.
+       */
+      return args.quietNow === true ? 'expected-quiet' : 'no-traffic'
+    }
   }
 
   /*
@@ -698,9 +782,10 @@ export function syncVerdictOf(args: {
   if (!args.recent) {
     const touched = typeof args.lastAtMs === 'number' && args.lastAtMs >= 0
     const nothingOffered = (args.offeredTotal ?? 0) <= 0
-    return touched && nothingOffered ? 'no-traffic' : 'unknown'
+    if (touched && nothingOffered) return args.quietNow === true ? 'expected-quiet' : 'no-traffic'
+    return 'unknown'
   }
-  if (args.recent.offered <= 0) return 'no-traffic'
+  if (args.recent.offered <= 0) return args.quietNow === true ? 'expected-quiet' : 'no-traffic'
 
   const ratio = (args.recent.offered - args.recent.rejected) / args.recent.offered
   return ratio >= (args.threshold ?? HEALTHY_ACCEPTED_RATIO) ? 'syncing' : 'mapping-blocked'

package/server/engine/kpi-fold.ts

@@ -915,8 +915,27 @@ export interface KpiFoldOptions {
   /**
    * 현장의 시각 기준(분) — 교대 축이 `HH:MM` 을 어느 기준으로 읽을지. **공간이 갖는 값**이다
    * (테넌트가 아니다: 한 테넌트가 다른 시간대의 공장을 함께 가질 수 있다). 없으면 UTC.
+   *
+   * ⚠ 한 수다. 접기는 지난 구간을 훑으므로 **일광절약시간 전환을 넘을 수 없다** — 그때는
+   * `offsetAt` 을 넘긴다.
    */
   utcOffsetMinutes?: number
+  /**
+   * 그 순간의 시각 기준을 푸는 함수 — **`utcOffsetMinutes` 보다 먼저 본다**.
+   *
+   * ── 왜 수가 아니라 함수인가 (2026-09-07) ─────────────────────────────────
+   * 접기는 지난 구간을 훑는다. 1년치를 교대별로 접으면 그 1년 안에 일광절약시간 전환이 두 번 들어
+   * 있는데, 고정 오프셋 하나로 읽으면 전환 뒤의 사실이 **한 시간 밀려 다른 교대로 세어진다.**
+   * 오류가 나지 않으므로 교대별 성과가 조용히 거짓이 된다. `America/Tijuana`(PST −480 / PDT −420)가
+   * 이미 자료에 있다.
+   *
+   * 이 파일은 시간대 데이터를 들지 않는다(커널과 같은 자세다) — 부르는 쪽이 푸는 법을 준다. 그래서
+   * 이 인자가 함수이고, 시험은 여전히 평범한 값으로 돈다.
+   *
+   * `undefined` 를 돌려주면 그 순간은 기준을 모르는 것이다 — 0(UTC)으로 채우지 않고
+   * `utcOffsetMinutes` 로 떨어진다.
+   */
+  offsetAt?: (atMs: number) => number | undefined
   /**
    * 축의 상한(기본 20). 넘치면 잘라내고 **잘린 축의 수와 그 안의 건수를 함께 알린다**.
    *
@@ -970,7 +989,11 @@ function facetKey(rec: CompletionRecord, options: KpiFoldOptions): string {
       if (!options.shifts?.length) return 'unknown'
       /* 시각까지 넘긴다 — **휴일에 일어난 일은 어느 교대에도 속하지 않는다.** 되풀이만 보면 그날 서지도
          않은 교대에 집계돼, 교대별 성과가 알리지 않고 거짓이 된다. */
-      return activeShiftAt(options.shifts, rec.at, options.utcOffsetMinutes) ?? 'unknown'
+      /* 그 순간의 기준을 먼저 묻는다 — 없으면 한 수로 떨어진다(§`offsetAt`). */
+      const atMs = typeof rec.at === 'number' ? rec.at : Date.parse(String(rec.at))
+      const offset =
+        (Number.isFinite(atMs) ? options.offsetAt?.(atMs) : undefined) ?? options.utcOffsetMinutes
+      return activeShiftAt(options.shifts, rec.at, offset) ?? 'unknown'
     default:
       return 'unknown'
   }

package/server/engine/kpi-query.ts

@@ -17,6 +17,8 @@
 import { twinWarn } from './log.js'
 import { mergeStreams } from '../service/twin-journal/event-type-split-shape.js'
 import { hydratedDate } from './read-time.js'
+/* 시간대 이름을 순간마다 푸는 함수 — engine 이 service 를 들이는 것은 이 파일들의 관행이다(§`twin-engine.ts`). */
+import { utcOffsetOf } from '../service/reference/reference-master.js'
 import { Between, In } from 'typeorm'
 
 import { type TariffDeclaration } from '@operato/twin-kernel'
@@ -257,8 +259,12 @@ type KpiGroupOut = NonNullable<KpiResult['groups']>['items'][number] &
  * **가장 많이 쓰이는 선언 한 벌**을 쓴다 — 3교대 공장은 전 설비가 같은 교대이므로 이것이 곧 정답이고,
  * 자원마다 교대가 다른 현장에서는 이 축이 거칠다는 뜻이다(그 사실을 여기 적어 둔다).
  *
- * 시각 기준은 모델에 실려 있다(`utcOffsetMinutes` — 공간이 갖는 값을 기동 시 호스트가 풀어 넣는다).
- * 없으면 UTC 로 읽고, 그 기본값은 커널 계약에 밝혀져 있다.
+ * 시각 기준은 모델에 실려 있다(공간이 갖는 값을 기동 시 호스트가 풀어 넣는다). 없으면 UTC 로 읽고,
+ * 그 기본값은 커널 계약에 밝혀져 있다.
+ *
+ * **이름이 있으면 이름을 쓴다**(`timezone`). 접기는 지난 구간을 훑으므로 고정 오프셋으로는 일광절약시간
+ * 전환을 넘을 수 없다 — 1년치를 한 오프셋으로 읽으면 그 안의 전환 두 번이 사실을 다른 교대로 세게 하고,
+ * 그 어긋남은 오류를 내지 않는다(2026-09-07).
  */
 /**
  * 이 범위에 걸린 운영 목표 — **좁은 선언이 넓은 선언을 덮는다.**
@@ -281,14 +287,16 @@ async function loadTargets(
 async function shiftContext(
   domainId: string,
   instanceIds: string[]
-): Promise<{ shifts?: any[]; utcOffsetMinutes?: number }> {
+): Promise<{ shifts?: any[]; utcOffsetMinutes?: number; offsetAt?: (atMs: number) => number | undefined }> {
   if (!instanceIds.length) return {}
   const rows = await getRepository(TwinInstance).find({ where: { domain: { id: domainId }, instanceId: In(instanceIds) } })
   const tally = new Map<string, { decl: any[]; n: number }>()
   let utcOffsetMinutes: number | undefined
+  let timezone: string | undefined
   for (const row of rows) {
     const model = row.model as any
     if (utcOffsetMinutes === undefined && typeof model?.utcOffsetMinutes === 'number') utcOffsetMinutes = model.utcOffsetMinutes
+    if (timezone === undefined && typeof model?.timezone === 'string' && model.timezone) timezone = model.timezone
     for (const e of (model?.equipment ?? []) as any[]) {
       const decl = e?.workCalendar
       if (!Array.isArray(decl) || !decl.length) continue
@@ -300,7 +308,18 @@ async function shiftContext(
   }
   let best: { decl: any[]; n: number } | undefined
   for (const v of tally.values()) if (!best || v.n > best.n) best = v
-  return { ...(best ? { shifts: best.decl } : {}), ...(utcOffsetMinutes !== undefined ? { utcOffsetMinutes } : {}) }
+  /*
+   * 이름이 있으면 **푸는 함수**로 바꿔 넘긴다. 접기가 레코드마다 부르므로 그 순간의 오프셋이 나오고,
+   * 일광절약시간 전환이 든 구간도 맞게 세어진다(§`FoldOptions.offsetAt`).
+   *
+   * 수(`utcOffsetMinutes`)도 함께 남긴다 — 이름이 없는 공간에서는 그것이 유일한 답이고, 이름이 있어도
+   * 그 순간을 못 푸는 경우의 마지막 기댈 자리다.
+   */
+  return {
+    ...(best ? { shifts: best.decl } : {}),
+    ...(utcOffsetMinutes !== undefined ? { utcOffsetMinutes } : {}),
+    ...(timezone ? { offsetAt: (atMs: number) => utcOffsetOf(timezone, new Date(atMs)) } : {})
+  }
 }
 
 async function locationAreaMap(