@things-factory/headless-twin 10.1.277 → 10.1.279

package/server/service/twin-event/twin-event-keys.ts

@@ -1,215 +0,0 @@
-import { bizStepName } from '@operato/ops-contract'
-
-import { twinWarn } from '../../engine/log.js'
-/*
- * 저널 검색 키 추출 — **순수**. 인제스트가 기록할 때 한 번 뽑아 인덱스 가능한 실컬럼으로 승격한다.
- *
- * ── 왜 승격하는가 ───────────────────────────────────────────────────────────
- * 사용자가 저널에서 실제로 찾는 것은 "이 팔레트의 이력", "이 오더가 어디까지 갔나", "이 도크에서
- * 무슨 일이 있었나" 다. 그런데 그 값들은 전부 `payload`(simple-json = TEXT) **안**에 있었다.
- * things-factory 는 5개 DB 드라이버를 지원해야 해서 DB별 JSON 연산자를 쓸 수 없다 —
- * 즉 승격 없이는 **어떤 방법으로도 서버에서 그 조건으로 거를 수 없었다**. 클라이언트가 받아온
- * 몇 천 건 안에서만 찾는 시늉이 최선이었고, 저널이 커질수록 그 시늉은 거짓말에 가까워진다.
- *
- * 그래서 검색 축이 되는 값만 골라 컬럼으로 꺼낸다. payload 는 그대로 둔다(정본은 여전히 payload —
- * 이건 파생 색인이지 새로운 진실이 아니다).
- *
- * ── 왜 여기(순수 모듈)인가 ──────────────────────────────────────────────────
- * 기록 경로가 둘이다(`persistBatch` 라이브 벌크 · `persist` 심 단건). 두 곳에 각자 적으면
- * 반드시 어긋나고, 어긋난 색인은 "없는 것처럼 보이는 이벤트" 를 만든다 — 저널에서 가장 나쁜 결함이다.
- */
-
-/** 승격된 검색 키 — 전부 선택적. 뽑히지 않으면 **빈 문자열이 아니라 undefined**(결측≠빈값). */
-export interface TwinEventKeys {
-  action?: string
-  bizStep?: string
-  epc?: string
-  orderId?: string
-  bizTransaction?: string
-  locationId?: string
-  moverId?: string
-  /** `'actual'`, `'simulated'`, or absent — absent means not declared, which is not `actual`. */
-  provenance?: string
-}
-
-/*
- * 컬럼 길이 상한. GS1 식별자(EPC URN·GDTI·SGLN)는 규격상 이보다 훨씬 짧다.
- * 넘치는 값이 오면 **알리지 않고 자르지 않고** 경고를 남긴다 — 색인이 원본과 다르면 검색 결과가 거짓이 되는데,
- * 그 사실이 어디에도 안 남으면 아무도 모른다.
- */
-const MAX_KEY = 255
-
-function clip(v: unknown, field: string): string | undefined {
-  if (v === undefined || v === null) return undefined
-  const s = String(v)
-  if (!s) return undefined
-  if (s.length <= MAX_KEY) return s
-  twinWarn(
-    `[twin-event-keys] ${field} exceeds ${MAX_KEY} chars and was clipped for indexing — ` +
-      `search on this value may be incomplete. payload keeps the full value. (${s.slice(0, 60)}…)`
-  )
-  return s.slice(0, MAX_KEY)
-}
-
-/**
- * bizStep 의 짧은 이름 — 자르는 규칙은 계약의 `bizStepName` 하나다(CBV URN 과 사설 이름공간 URL 둘 다).
- * 없으면 이벤트 타입에서 유추(`epcis.` 접두 제거).
- */
-export function bizStepOf(envelope: any): string | undefined {
-  const d = envelope?.data ?? envelope ?? {}
-  return bizStepName(d.bizStep) || String(envelope?.eventType ?? '').replace('epcis.', '') || undefined
-}
-
-/**
- * 품목 식별자 — **전체 값**을 저장한다(끝마디만 저장하지 않는다).
- *
- * 표시용 축약은 화면이 하고, 색인은 원본을 갖는다. `search` 는 부분일치(contains)라
- * 전체를 저장해 두면 끝마디("402.2")로도 URN 전체로도 찾힌다. 반대로 끝마디만 저장하면
- * URN 으로 찾는 경로가 사라진다.
- */
-export function epcOf(envelope: any): string | undefined {
-  const d = envelope?.data ?? envelope ?? {}
-  return d.epcList?.[0] ?? d.parentID ?? d.quantityList?.[0]?.epcClass ?? undefined
-}
-
-/**
- * 오더 식별자 — 운영 델타의 `orderId` 우선, EPCIS 는 `bizTransactionList`.
- *
- * ── 실측 (2026-08-24) — 이 컬럼이 **전부 비어 있었다** ──────────────────────
- * 여기가 찾던 이름이 `d.order` 였다. 그런데 커널이 내는 이름은 **`orderId`** 다
- * (`OrderStatusDelta.orderId` · `TaskStatusDelta.orderId`). `d.order` 를 내는 코드는 커널에 **한 곳도
- * 없다** — 죽은 가지였다. 그래서 운영 델타는 이 컬럼을 한 번도 채우지 못했다.
- *
- *   order.status   29,403,565 행 — order_id 비어 있음 29,403,565 (100%)
- *   task.status       191,175 행 — 비어 있음 191,175 (100%)
- *
- * 그 결과 색인 `ix_twin_event_4` 가 **자기 주석이 적어 둔 용도**(「이 오더가 어디까지 갔나」)로 쓸 수
- * 없었다. 화면은 오더를 눌러도 「연결된 이벤트가 없습니다」를 냈고, 그 답은 질의 결과로는 정직했다 —
- * 시점을 어디로 옮겨도 0 이었다.
- *
- * **과거 행은 채워지지 않는다**(사용자 결정 2026-08-24, `moverId` 때와 같은 방식). 앞으로 들어오는
- * 사건부터 조회된다.
- *
- * ── 한 칸에 두 낱말이 들어 있었다 (2026-09-05 실측) ────────────────────────
- * 위 주석이 이미 알고 있었다 — 「EPCIS 의 `bizTransactionList` 는 **거래**(PO/SO)이고 오더와 같은
- * 것이 아닐 수 있다」. 그런데 그 둘을 **같은 칸에** 넣고 있었다. 그래서 이렇게 됐다.
- *
- *   order.status                order-1                          내부 오더 id
- *   epcis.TransformationEvent   urn:epc:id:gdti:9521321.403.1    GS1 거래 식별자
- *   epcis.TransactionEvent      urn:epc:id:gdti:9521321.403.1
- *
- * 한 오더의 이력이 **색인 안에서 두 쪽으로 갈라진다.** 어느 이름으로 물어도 절반만 나오고,
- * 오류는 나지 않는다. 실측: 어휘가 섞인 행 10,004개.
- *
- * 이것이 실제로 막은 것 — 「이 개체를 어느 레시피로 만들었나」다. 답은 기록되어 있다(오더 사건이
- * `recipeKey` 를 든다, 실측 328,021/328,021 = 100%). 변환 사건은 그 오더를 GDTI 로 가리키는데
- * 오더 사건은 `order-1` 로 적혀 있어 **색인으로 이을 수가 없었다.**
- *
- * 그래서 칸을 갈랐다(사용자 결정 2026-09-05).
- *
- *   orderId          내부 오더 id — 읽기 모델의 이음쇠
- *   bizTransaction   GS1 거래 식별자 — 표준이 말하는 그 거래
- *
- * 오더 사건은 **둘 다** 든다(`order.status` 의 payload 에 `orderId` 와 `bizTransaction` 이 함께
- * 있다). 그래서 EPCIS 사건의 거래 식별자로 오더를 찾을 수 있다 — 이 두 칸이 그 다리다.
- */
-export function orderOf(envelope: any): string | undefined {
-  const d = envelope?.data ?? envelope ?? {}
-  return d.orderId ?? undefined
-}
-
-/**
- * **그 사건이 가리키는 거래** — EPCIS `bizTransactionList` 의 첫 항목, 또는 운영 델타가 직접 든 값.
- *
- * 오더가 아니다. 표준이 말하는 거래(PO/SO/생산오더)이고, 한 오더가 여러 거래에 걸릴 수도 있다.
- * 그 구별을 지키려고 `orderId` 와 갈라 두었다 — 합치면 위 주석의 그 일이 다시 난다.
- */
-export function bizTransactionOf(envelope: any): string | undefined {
-  const d = envelope?.data ?? envelope ?? {}
-  return d.bizTransactionList?.[0]?.bizTransaction ?? d.bizTransaction ?? undefined
-}
-
-/**
- * 위치 — EPCIS 는 읽은 지점(readPoint) 우선, 없으면 업무 위치(bizLocation).
- * 운영 델타(무버 이동 등)는 그 둘이 없고 평범한 `location` 을 쓴다 — 빠뜨리면 설비가 어디서
- * 무엇을 했는지가 위치 축에서 통째로 사라진다.
- */
-export function locationOf(envelope: any): string | undefined {
-  const d = envelope?.data ?? envelope ?? {}
-  return d.readPoint?.id ?? d.bizLocation?.id ?? d.location ?? undefined
-}
-
-/**
- * 설비·무버 — 운영 델타(equipment.status·task.status)가 대상을 가리키는 축.
- *
- * EPCIS 어휘가 아니라서 다른 축 어디에도 안 잡힌다. 이게 없으면 "이 지게차가 오늘 무엇을 했나" 를
- * 서버에서 물을 방법이 없어, 화면이 저널을 통째로 받아 전수 조회하는 수밖에 없다.
- */
-export function equipmentIdOf(envelope: any): string | undefined {
-  const d = envelope?.data ?? envelope ?? {}
-  /*
-   * ── 실측 (2026-08-24) — 두 갈래를 놓치고 있었다 ────────────────────────────
-   * 위 주석이 `task.status` 를 출처로 **적어 두었는데** 이 함수는 `d.moverId` 만 봤다. 작업이 자원을
-   * 가리키는 이름은 `resourceRef` 다(`TaskStatusDelta.resourceRef`) — 그래서 작업 191,175 행 전부
-   * 이 컬럼이 비었고, 「이 지게차가 오늘 무엇을 했나」에서 **작업이 통째로 빠졌다.**
-   *
-   * 그리고 에너지 사건은 `equipmentId` 를 쓴다(어휘가 `movers`→`equipment` 로 개명된 뒤에 생긴
-   * 채널이다). 실측 `energy.equipment` 31,079 행 전부 비어 있었다 — 「이 설비가 얼마를 먹었나」를
-   * 설비 축으로 물을 수 없었다.
-   *
-   * 셋을 함께 본다. 개명 세대가 섞여 있는 것은 저널의 성질이고, 읽는 쪽이 그것을 흡수한다.
-   */
-  return d.moverId ?? d.resourceRef ?? d.equipmentId ?? undefined
-}
-
-/**
- * EPCIS 행위 — `ADD`·`OBSERVE`·`DELETE`. 세 값이 아니면 `undefined`(원천의 잡값을 색인에 넣지 않는다).
- *
- * 이 키는 검색 축이 아니라 **판별식**이다: 되풀어 읽는 스냅샷은 원리적으로 `DELETE` 를 못 낸다.
- * 그래서 「이 트윈이 반출을 한 번이라도 계산했는가」가 진짜 delta 피드의 증거인데, payload 안에 있는
- * 동안에는 5개 드라이버 어디에서도 그 질문을 할 수 없었다. 운영 델타에는 행위가 없다 — 비운다.
- */
-export function actionOf(envelope: any): string | undefined {
-  const a = (envelope?.data ?? envelope ?? {}).action
-  return a === 'ADD' || a === 'OBSERVE' || a === 'DELETE' ? a : undefined
-}
-
-/**
- * **Whether the sender declared this fact as having actually happened** — the envelope's
- * `provenance`, promoted to a column.
- *
- * ── Why it is an indexed column (2026-09-09) ──────────────────────────────
- * The journal held 1,134 rows, all of them generator output, and there was nowhere to ask about
- * it. While the declaration sits inside `payload`, none of the five drivers can answer "count
- * these without the invented ones" — the same reason `action` was promoted.
- *
- * ── Only the two declared values are taken ────────────────────────────────
- * Anything that is not `actual` or `simulated` becomes `undefined`. A source's stray value does
- * not reach the index (the discipline in `actionOf`).
- *
- * **`undefined` means "not declared", not "it happened".** A reader has to distinguish three
- * states — declared simulated, declared actual, not declared. Folding the last two together
- * means a generator that omits the field has its output counted as production.
- */
-export function provenanceOf(envelope: any): string | undefined {
-  /*
-   * Read from the envelope only. `data` is where the source system writes, and a source that
-   * could declare its own facts actual would make this no longer the connecting side's statement.
-   */
-  const p = envelope?.provenance
-  return p === 'actual' || p === 'simulated' ? p : undefined
-}
-
-/** Every promoted key for one event — the write path calls this function and nothing else. */
-export function twinEventKeys(envelope: any): TwinEventKeys {
-  return {
-    action: actionOf(envelope),
-    bizStep: clip(bizStepOf(envelope), 'bizStep'),
-    epc: clip(epcOf(envelope), 'epc'),
-    orderId: clip(orderOf(envelope), 'orderId'),
-    bizTransaction: clip(bizTransactionOf(envelope), 'bizTransaction'),
-    locationId: clip(locationOf(envelope), 'locationId'),
-    moverId: clip(equipmentIdOf(envelope), 'moverId'),
-    provenance: provenanceOf(envelope)
-  }
-}

package/server/service/twin-event/twin-event-type.ts

@@ -1,68 +0,0 @@
-import { Field, Int, ObjectType } from 'type-graphql'
-
-import { TwinEvent } from './twin-event.js'
-
-/*
- * 저널 목록 반환형 — things-factory 표준 `{ items, total }`(AttributeSetList·DomainList 등과 동형).
- *
- * `total` 이 이 타입의 존재 이유다. 기존 `twinEvents` 는 배열만 돌려줘서 **화면이 자기가 전체를 받은
- * 건지 잘린 건지 알 방법이 없었다** — 그래서 리스트가 알리지 않고 잘린 채로 "이게 전부" 처럼 보였다.
- * 총건수를 함께 주면 화면은 "48 / 12,904" 라고 정직하게 말할 수 있고, 사용자는 좁혀야 한다는 걸 안다.
- */
-@ObjectType({ description: 'A page of twin journal events together with the total number of matching records.' })
-export class TwinEventList {
-  @Field(type => [TwinEvent], { description: 'The events on this page, ordered by the requested sorting (revision descending by default).' })
-  items: TwinEvent[]
-
-  /*
-   * 전체 수 — **상한을 넘으면 비운다.**
-   *
-   * 세는 데도 값이 든다(2026-08-22 실측: 저널 358만 행인 트윈에서 전량 세기 5.32초 · 상한 1만까지
-   * 0.04초). 그래서 상한까지만 세고, 넘으면 「모른다」로 둔다. 그때 상한값을 전체로 적으면 화면이
-   * 거짓을 말한다 — 없는 것과 모르는 것을 가르는 것이 이 필드의 규율이다.
-   */
-  @Field(type => Int, {
-    nullable: true,
-    description:
-      'Total number of events matching the filters, ignoring pagination. Lets the caller show an honest "shown of total" count instead of silently truncating. NULL when the server stopped counting at countCap: the exact total is then unknown, and capped says so — do not render the cap as if it were the total.'
-  })
-  total?: number
-
-  @Field({
-    nullable: true,
-    description:
-      'True when there are more matching events than countCap, so total could not be established. The caller should say "first N shown" and offer narrowing rather than implying it received everything.'
-  })
-  capped?: boolean
-
-  @Field(type => Int, {
-    nullable: true,
-    description: 'The counting limit the server applied. Reported so the screen can say how far the count is trustworthy instead of guessing.'
-  })
-  countCap?: number
-
-  /*
-   * 다음 페이지 커서. 저널은 **머리에 계속 쌓이는 목록**이라 offset 으로 뒤를 읽으면
-   * 읽는 사이 들어온 이벤트만큼 밀려 본 행이 또 나오거나 못 본 행이 사라진다.
-   * 이 값을 그대로 다음 요청의 `pagination.after` 로 돌려주면 그 문제가 없다.
-   */
-  @Field({ nullable: true, description: 'Opaque cursor for the next page. Pass it back as pagination.after to continue exactly where this page ended, without the duplicate or skipped rows that offset paging produces on a journal that keeps growing at the head. Null when this page is the last one.' })
-  nextCursor?: string
-
-  /*
-   * **앞부분이 지워졌다** — 보관 기간 정리가 이 트윈의 오래된 사건을 지운 경우 (2026-08-27).
-   *
-   * 정리는 선언된 보관 기간(기본 7일)보다 오래된 사건을 지운다. 그러면 이 목록의 첫 페이지 뒤로 더
-   * 내려가도 어느 지점에서 기록이 끝난다. 화면이 그것을 말하지 않으면 사람은 「이 트윈은 그때부터
-   * 시작했다」로 읽는다. 없었던 것과 지워진 것은 다른 사실이다.
-   *
-   * 값은 저장하지 않고 조회할 때 구한다(남아 있는 가장 작은 리비전). 저장하면 실제 데이터와 어긋날 수
-   * 있고, 어긋나면 어느 쪽이 사실인지 알 수 없다.
-   */
-  @Field(type => Int, {
-    nullable: true,
-    description:
-      'The oldest revision still stored for this twin. When it is greater than 1, older events were deleted by the journal retention policy: the screen must say the record starts here rather than implying the twin began at this point. NULL when the caller asked for more than one twin (the axis is per twin) or when nothing is stored.'
-  })
-  oldestRevision?: number
-}

package/server/service/twin-event/twin-event.ts

@@ -1,250 +0,0 @@
-import { CreateDateColumn, Entity, Index, Column, RelationId, ManyToOne, PrimaryGeneratedColumn } from 'typeorm'
-import { ObjectType, Field, ID, Int } from 'type-graphql'
-
-import { Domain, ScalarObject } from '@things-factory/shell'
-
-/*
- * TwinEvent — append-only 트윈 이벤트 저널(EPCIS 이벤트 + 운영 델타).
- * 커널 EventJournal 의 영속 대응 — 상태=이벤트열의 함수(재부팅 시 DB→replay 재구성).
- * append-only 이므로 updater/deletedAt 없음(이력 CRUD 가 아니라 불변 이벤트 스트림).
- * payload 는 simple-json(멀티DB 이식 — postgres/mysql/sqlite/mssql/oracle 공통, DB-specific JSON 타입 금지).
- * (CLAUDE.md: 모든 @ObjectType/@Field 는 영문 description 필수.)
- */
-/*
- * ── 인덱스 설계 (2026-07-31) ────────────────────────────────────────────────
- * 이 표는 **인제스트 경로의 뜨거운 append-only 테이블**이다. 인덱스 하나하나가 쓰기 증폭이므로
- * "있으면 좋을" 인덱스를 붙이지 않는다. 실제 질의 패턴에 대응하는 것만 둔다.
- *
- *  ix_0 (domain, instanceId, revision)            원장 기본 정렬·커서 페이징·replay(ASC 주사)
- *  ix_1 (domain, instanceId, eventTime)           시각 커서(untilTime)·시간창 KPI — 거의 모든 조회가 탄다
- *  ix_2 (domain, instanceId, eventType, revision) 타입 필터 + 정렬 동시 충족(스케줄 화면 task/equipment)
- *  ix_3 (domain, instanceId, epc)                 "이 물건의 이력" — Entity360 의 본질 질문
- *  ix_4 (domain, instanceId, orderId)             "이 오더가 어디까지 갔나"
- *  ix_9 (domain, instanceId, bizTransaction)      "이 거래에 무슨 일이 있었나" — EPCIS↔오더의 다리
- *
- * bizStep·locationId·moverId 는 컬럼만 두고 인덱스는 두지 않는다 — 한 트윈 안에서 카디널리티가
- * 낮아(업무단계 몇 개, 위치 수백, 설비 수십) (domain,instanceId) 로 이미 좁혀진 뒤의 잔여 필터로
- * 충분하고, 뜨거운 표에 인덱스를 더 얹을 가치가 없다. 저널 하나가 아주 커져서 이 축들의 조회가
- * 느려지면 그때 측정을 근거로 인덱스를 추가할 일이지, 지레 얹어 쓰기를 무겁게 할 일은 아니다.
- */
-@Entity()
-@Index('ix_twin_event_0', (e: TwinEvent) => [e.domain, e.instanceId, e.revision], { unique: false })
-@Index('ix_twin_event_1', (e: TwinEvent) => [e.domain, e.instanceId, e.eventTime], { unique: false })
-@Index('ix_twin_event_2', (e: TwinEvent) => [e.domain, e.instanceId, e.eventType, e.revision], { unique: false })
-@Index('ix_twin_event_3', (e: TwinEvent) => [e.domain, e.instanceId, e.epc], { unique: false })
-@Index('ix_twin_event_4', (e: TwinEvent) => [e.domain, e.instanceId, e.orderId], { unique: false })
-/* ix_5 — "이 지시가 무엇을 일으켰나". 감사 기록의 commandId 로 저널을 다시 계산하는 축. */
-@Index('ix_twin_event_5', (e: TwinEvent) => [e.domain, e.correlationId], { unique: false })
-/* ix_6 — "반출을 한 번이라도 계산했나". 없으면 그 질문이 인스턴스 저널 전량 주사가 된다. */
-@Index('ix_twin_event_6', (e: TwinEvent) => [e.domain, e.instanceId, e.action], { unique: false })
-/*
- * ix_7 — **"이 종류의 사실을 시각순으로"** (2026-08-25 실측으로 추가)
- *
- * 이 축이 없어서 공정 타임라인이 22초였다. 종류로 거르고 시각으로 정렬하는 조회가 갈 곳이 없었다:
- *
- *   ix_2 (…, eventType, revision)   종류는 걸러지고 정렬이 **적힌 순서**다 → 4월 사실을 최근으로 그렸다
- *   ix_1 (…, eventTime)             정렬은 맞고 **종류를 못 거른다** → 행마다 테이블을 열어 확인한다
- *
- * 뒤쪽으로 걸으면 그 트윈에서 찾는 종류가 멈춘 시점까지의 모든 행을 읽고 버린다. 승화푸드에서 작업
- * 사실은 8월 22일에 멈춰 있고 그 뒤로 리비전이 110만 늘었으므로, 200건에 닿기까지 110만 행을 열었다.
- *
- * 위 주석이 「측정을 근거로 추가할 일이지 지레 얹을 일은 아니다」라고 적어 두었다. 그 측정이 나왔다.
- */
-@Index('ix_twin_event_7', (e: TwinEvent) => [e.domain, e.instanceId, e.eventType, e.eventTime], { unique: false })
-/*
- * ix_8 — **"이 트윈의 오래된 기록"** (2026-08-27 실측으로 추가)
- *
- * 보관 기간 정리가 `created_at` 으로 자르는데(보관은 저장 나이의 문제다) 그 축에 인덱스가 없었다.
- * 그래서 정리가 매 배치마다 그 트윈의 저널을 전량 주사했다.
- *
- *   hatio-mx2 의 7일 밖 행을 세기      208초   ← 1,029만 행을 전부 읽는다(7일 밖은 2,446건뿐이다)
- *   revision 으로 한 행 짚기           0.004초
- *
- * 정리는 한 창에 2초만 쓰도록 예산이 걸려 있어서, 그 2초를 주사에 다 쓰고 44건만 지우고 멈췄다.
- */
-@Index('ix_twin_event_8', (e: TwinEvent) => [e.domain, e.instanceId, e.createdAt], { unique: false })
-/* ix_9 — "이 거래에 무슨 일이 있었나". EPCIS 사건에서 오더로 건너가는 다리(§`bizTransaction`). */
-@Index('ix_twin_event_9', (e: TwinEvent) => [e.domain, e.instanceId, e.bizTransaction], { unique: false })
-@ObjectType({ description: 'Append-only twin event journal record (EPCIS event or operational delta).' })
-export class TwinEvent {
-  @PrimaryGeneratedColumn('uuid')
-  @Field(type => ID, { description: 'Unique identifier of the event record.' })
-  readonly id: string
-
-  @ManyToOne(type => Domain)
-  @Field(type => Domain, { nullable: true, description: 'Owning tenant domain.' })
-  domain?: Domain
-
-  @RelationId((e: TwinEvent) => e.domain)
-  domainId?: string
-
-  /*
-   * 이 사실을 낸 트윈. **빌 수 없다** — 저널 행을 만드는 곳은 `journalRow` 하나뿐이고 거기서
-   * 필수 인자로 받는다. nullable 로 두면 읽는 쪽이 매번 `?? ''` 를 달게 되고, 그 방어가 실제로는
-   * 일어나지 않는 경우를 대비하느라 "빈 인스턴스의 이벤트" 라는 없는 개념을 코드에 남긴다.
-   */
-  @Column()
-  @Field({ description: 'Twin runtime instance id that emitted the event.' })
-  instanceId: string
-
-  /* 커널 봉투의 필수 필드(`CanonicalEnvelope.eventType`)라 빌 수 없다 — 계약을 그대로 옮긴다. */
-  @Column()
-  @Field({ description: 'Event type: epcis.* | task.status | equipment.status | order.status.' })
-  eventType: string
-
-  @Column({ type: 'int', nullable: true })
-  @Field(type => Int, { nullable: true, description: 'Monotonic state revision at which the event was emitted.' })
-  revision?: number
-
-  /**
-   * 이 사실이 **어느 공장에서** 일어났나 — `TwinStructure.rev`.
-   *
-   * 이것이 없던 시절에는 구조가 바뀌면 저널을 통째로 지우는 것이 유일한 길이었다(안 지우면 옛
-   * 이벤트를 새 공장에 대고 계산해 이력이 거짓말을 한다). 이 한 칸이 셋째 길을 연다 — 재생이
-   * 구조가 바뀌는 지점에서 전환한 뒤 이어서 계산한다.
-   *
-   * **비어 있을 수 있다**: 컬럼이 생기기 전에 쓰인 행이다. 그 행들은 **가장 오래된 리비전**에
-   * 속한다(0 을 채워 넣지 않는다 — 0 은 "모름" 이 아니라 유효한 번호처럼 보인다).
-   */
-  @Column({ type: 'int', nullable: true })
-  @Field(type => Int, { nullable: true, description: 'Structure revision (TwinStructure.rev) in force when this event happened. Absent on rows written before structure revisions existed; those belong to the oldest revision.' })
-  structureRev?: number
-
-  /*
-   * 이 사실이 일어난 시각(트윈의 시계). **날짜 타입이다.**
-   *
-   * 예전에는 문자열이었다. 읽을 때마다 `Date.parse` 했고, 정렬은 UTC ISO 만 들어온다는 전제 위에서
-   * 사전식 비교가 우연히 맞았다 — `+09:00` 오프셋 표기가 하나 섞이면 알리지 않고 순서가 틀린다.
-   * 그 전제는 컬럼 어디에도 적혀 있지 않았다.
-   *
-   * **타입 이름을 적지 않는다** (2026-08-19 Postgres 부팅 실패로 고침).
-   *
-   * `datetime` 을 적었더니 Postgres 가 부팅 중에 거절했다(`DataTypeNotSupportedError`) — 그 이름은
-   * sqlite·MySQL 의 것이고 Postgres 는 `timestamp` 만 안다. 거꾸로 `timestamp` 는 sqlite 가 모른다:
-   * **다섯 드라이버에 다 통하는 이름이 아예 없다.**
-   *
-   * 그래서 이름을 고르는 일을 TypeORM 에 맡긴다. `emitDecoratorMetadata` 가 켜져 있으므로 이 속성의
-   * TS 타입(`Date`)에서 드라이버별 타입을 스스로 고른다(Postgres `timestamp` · sqlite·MySQL `datetime`).
-   * 이 레포의 다중 DB 규약이 요구하는 것이 바로 그것이다 — 드라이버 방언을 코드에 적지 않는다.
-   */
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Time at which the fact happened on the twin clock.' })
-  eventTime?: Date
-
-  /*
-   * ── 승격된 검색 축 ────────────────────────────────────────────────────────
-   * payload 안에 있던 값을 인제스트 시점에 꺼내 실컬럼으로 둔다(`twin-event-keys.ts` 가 단독 소유).
-   * payload 가 여전히 정본이고 이것들은 **파생 색인**이다 — 새로운 진실이 아니라 찾을 수 있게 하는 장치.
-   * simple-json(TEXT) 안의 값은 5개 DB 드라이버 공통으로 거를 방법이 없어서(멀티DB 호환 규칙상
-   * DB별 JSON 연산자 금지) 승격 외의 선택지가 없다.
-   * 길이 상한 255 는 GS1 식별자 규격 대비 충분하며, 넘치는 값은 알리지 않고 잘리지 않고 경고를 남긴다.
-   *
-   * ── 축을 새로 추가할 때 ──────────────────────────────────────────────────
-   * 새 승격 컬럼을 만들면 **이미 쌓인 행은 비어 있다.** 그 행들은 새 축으로 검색되지 않고,
-   * 사용자에게는 "과거가 없는 것" 으로 보인다(알리지 않고 빠진 데이터).
-   *
-   * 예전에는 기동 훅이 매번 테이블을 살펴 채웠다. 그건 두 가지로 틀렸다 — 저널이 커질수록 부팅이
-   * 느려지고, "bizStep 이 비었으면 옛 행" 이라는 전제를 코드에 고정해 그 전제가 깨지는 순간
-   * (감사 행처럼 업무 단계가 없는 행) 매 부팅마다 헛돌았다. 그래서 걷어냈다(git: backfill-keys.ts).
-   *
-   * 채우는 일은 **마이그레이션 한 번**이 맞다(`yarn migration`). 그 컬럼에 맞는 것을 그때 쓴다 —
-   * 범용 스캐너를 되살리지 말 것. 개발 데이타라면 그냥 버리는 것도 답이다.
-   */
-  /**
-   * 이 사실을 일으킨 **지시** — 커널이 커맨드에서 이어 준 상관값(기본은 commandId).
-   *
-   * 이것이 감사 기록(TwinAuditEvent.commandId)과 저널을 잇는 유일한 다리다. 없으면 승인 기록은
-   * "사람이 허락했다" 까지이고, 그 뒤 공장이 실제로 어떻게 움직였는지와 이어지지 않는다.
-   *
-   * **대부분의 행은 비어 있다** — 커맨드가 아니라 시뮬 시간이 낳은 사실이기 때문이다. 그것이 정상이고,
-   * 비어 있다고 "덜 채워진 옛 행" 으로 보면 안 된다(같은 오해를 bizStep 에서 이미 한 번 했다).
-   */
-  @Column({ length: 255, nullable: true })
-  @Field({ nullable: true, description: 'Id of the command that caused this fact (kernel correlation id; defaults to the commandId). Empty for facts that simulation time produced rather than a command.' })
-  correlationId?: string
-
-  /* 옛 행은 비어 있다 — 승격 전에 기록된 것이라 **모른다**(0 이나 OBSERVE 로 위장하지 않는다). */
-  @Column({ length: 16, nullable: true })
-  @Field({ nullable: true, description: 'EPCIS action (ADD / OBSERVE / DELETE), promoted from the payload. Empty for operational deltas, and for rows journaled before this column existed.' })
-  action?: string
-
-  @Column({ length: 255, nullable: true })
-  @Field({ nullable: true, description: 'Business step (CBV bizStep tail), promoted from the payload for indexed filtering.' })
-  bizStep?: string
-
-  @Column({ length: 255, nullable: true })
-  @Field({ nullable: true, description: 'Item identifier (EPC / EPC class / parent id), promoted from the payload for indexed lookup of one item history.' })
-  epc?: string
-
-  @Column({ length: 255, nullable: true })
-  @Field({ nullable: true, description: 'Internal order identifier, promoted from the payload for indexed lookup of one order history.' })
-  orderId?: string
-
-  /*
-   * **거래 식별자는 오더 식별자와 다른 것이다.**
-   *
-   * 전에는 둘이 한 칸(`orderId`)에 들어갔다. 그래서 한 오더의 이력이 색인 안에서 두 쪽으로
-   * 갈라졌다 — 운영 델타는 `order-1`, EPCIS 사건은 `urn:epc:id:gdti:…` 로 적혀 어느 이름으로
-   * 물어도 절반만 나왔다(실측 2026-09-05: 어휘가 섞인 행 10,004개, 오류는 나지 않음).
-   *
-   * 오더 사건은 두 값을 다 들고 있다. 그래서 이 칸이 **EPCIS 사건에서 오더로 건너가는 다리**가
-   * 된다 — 「이 개체를 어느 레시피로 만들었나」가 그 다리로 답해진다.
-   */
-  @Column({ length: 255, nullable: true })
-  @Field({ nullable: true, description: 'Business transaction identifier (PO / SO / production order), promoted from the payload for indexed lookup of one transaction.' })
-  bizTransaction?: string
-
-  @Column({ length: 255, nullable: true })
-  @Field({ nullable: true, description: 'Location identifier (read point, business location, or the plain location an operational delta carries), promoted from the payload for indexed filtering.' })
-  locationId?: string
-
-  @Column({ length: 255, nullable: true })
-  @Field({ nullable: true, description: 'Equipment identifier carried by operational deltas, promoted from the payload so one machine history can be asked for on the server. The column keeps the legacy name `moverId`: the journal is append-only history and mixing two names for the same fact across time is worse than an outdated name. Renaming belongs with event-schema versioning.' })
-  moverId?: string
-
-  /**
-   * **Whether the sender declared this fact as having actually happened** — the envelope's
-   * `provenance`, promoted here.
-   *
-   * ── Why a column (measured 2026-09-09) ──────────────────────────────────
-   * This table held 1,134 rows, all of them generator output, and **there was nowhere to ask
-   * about it**:
-   *
-   * ```
-   * select count(*) from twin_events                      1134
-   * select count(*) where payload like '%SIM-%'           1134
-   * select count(*) where order_id like 'WO-SIM-%'         558   <- half of them
-   * ```
-   *
-   * The only signal was the sender's naming convention (`SIM-`), and the column that convention
-   * reaches was empty on half the rows. While it sits inside `payload`, none of the five drivers
-   * can answer "count these without the invented ones" — the same reason `action` was promoted.
-   *
-   * ── Three states, kept apart ────────────────────────────────────────────
-   * ```
-   * 'simulated'   the sender said it was invented
-   * 'actual'      the sender said it happened
-   * null          **not declared** — which is not `actual`
-   * ```
-   *
-   * Folding the last two together means a generator that omits the declaration has its output
-   * counted as production, and nothing says so. Hence no default: an absent declaration is not
-   * disguised as a valid-looking value (the discipline of `structureRev` and `lastWarningCount`).
-   *
-   * ── No index ────────────────────────────────────────────────────────────
-   * Three possible values is low cardinality within one twin — the judgement already made for
-   * `bizStep` and `locationId`. Performance folds arrive already narrowed by domain, instance and
-   * time, so filtering after that is cheap.
-   */
-  @Column({ length: 16, nullable: true })
-  @Field({ nullable: true, description: 'Whether the sending side declared this fact as actually having happened. Either "actual" or "simulated"; null means it was not declared, which is not the same as actual — a generator that omits it must not be counted as production.' })
-  provenance?: string
-
-  @Column({ type: 'simple-json', nullable: true })
-  @Field(type => ScalarObject, { nullable: true, description: 'Raw canonical envelope (EPCIS event or operational delta) as JSON.' })
-  payload?: any
-
-  @CreateDateColumn()
-  @Field({ nullable: true, description: 'Wall-clock timestamp when the record was persisted.' })
-  createdAt?: Date
-}

package/server/service/twin-forecast/forecast-metrics.ts

@@ -1,106 +0,0 @@
-/*
- * 예측 지표 — **스냅샷에서 수 하나를 뽑는 규칙.**
- *
- * ── 왜 순수 모듈인가 (2026-08-15) ───────────────────────────────────────────
- * 이 표가 리졸버 안에 있어서 시험이 불러올 수 없었다(type-graphql·shell 을 물고 있다). 그런데 여기서
- * 틀리면 예측 그래프 전체가 알리지 않고 다른 것을 그린다 — 오류 없이. 규칙은 시험이 닿는 자리에 둔다.
- *
- * ── 에너지 지표를 더한 이유 ─────────────────────────────────────────────────
- * 예측 화면의 지표가 물류 여섯(재고·점유·작업·오더·출고·백로그)으로 고정돼 있어서, 에너지 트윈을
- * 고르면 **남의 질문에 답하는 그래프**가 떴다. 에너지 트윈에는 재고도 오더도 없으므로 그 값들은
- * 전부 0 이고, 0 은 「없다」가 아니라 「이 트윈의 질문이 아니다」이다.
- *
- * 여기 더한 셋은 **커널이 이미 상태로 들고 있는 것**이다 — 새 계산을 만들지 않았다. 특히 부하 합은
- * 커널이 뿌리 계량기로만 세는데(계층 계량의 이중 계상 방지), 그 규칙을 여기서 다시 쓰면 두 벌이 된다.
- * 그래서 지점을 직접 더하지 않고 **구간 값**을 읽는다.
- */
-
-import { isFlowOrder, isOrderTerminal } from '@operato/ops-contract'
-
-/*
- * ── Folded orders are counted too (ADR-0092 decision 3, ruling 2026-09-24) ─────────────
- *
- * A twin folds finished orders out of its hot list at checkpoint time and keeps only their counts
- * (`foldedOrders.counts`, kind × terminal status, never trimmed). Counting the hot list alone would drop
- * `orders` and `shipped` the moment a fold happens — and "the increase since the fork" alone would still
- * break `twinForecastGapTrend`, whose actual at T+h is read from recovered state: a fold between T and
- * T+h makes the actual increase negative. So both metrics are cumulative including the folded side, and
- * an increase is the difference of the same number. Which folded kinds are flow orders is asked of the
- * contract's `isFlowOrder`, the same as the hot list; `shipped` uses the same word on both sides.
- */
-function foldedFlowOrders(s: any, status?: string): number {
-  let n = 0
-  for (const [kind, byStatus] of Object.entries((s?.foldedOrders?.counts ?? {}) as Record<string, Record<string, number>>)) {
-    if (!isFlowOrder({ kind })) continue
-    if (status) n += Number(byStatus?.[status]) || 0
-    else for (const c of Object.values(byStatus ?? {})) n += Number(c) || 0
-  }
-  return n
-}
-
-/** 스냅샷 → 수 하나. 값이 없으면 0 이 아니라 **그 지표를 그릴 수 없다**는 뜻이지만, 그래프 계약이
- *  수를 요구하므로 0 을 낸다 — 그래서 에너지 지표는 「없음」이 0 과 헷갈리지 않는 것만 골랐다. */
-export type MetricFn = (s: any) => number
-
-export const FORECAST_METRICS: Record<string, MetricFn> = {
-  items: s => (s?.items || []).length,
-  occupancy: s => (s?.locations || []).reduce((a: number, n: any) => a + (n.occupancy || 0), 0),
-  tasks: s => (s?.tasks || []).length,
-  /*
-   * ── 세는 것은 **흐름 오더**다 (2026-09-19, ADR-0076 보탬 ⑥) ────────────────
-   *
-   * 받는 오더(입고 · 반품 입고)는 도착이 세우고 도착이 이행한다. 그대로 세면 「나간 것」이 받을 때마다
-   * 한 건씩 늘고 백로그는 영영 안 줄어든다 — 예측 그래프가 있지도 않은 일을 그린다. 무엇이 흐름
-   * 오더인지는 계약의 `isFlowOrder` 한 곳이 정한다(여기서 `kind` 를 다시 적지 않는다).
-   */
-  orders: s => (s?.orders || []).filter(isFlowOrder).length + foldedFlowOrders(s),
-  // 이행 지표 — 라이브 예측의 핵심 질문("언제 다 나가나·백로그 언제 풀리나").
-  shipped: s => (s?.orders || []).filter(isFlowOrder).filter((o: any) => o.status === 'shipped').length + foldedFlowOrders(s, 'shipped'),
-  /*
-   * ── 백로그는 **「종결인가」**로 묻는다 (2026-09-19) ─────────────────────────
-   *
-   * 낱말 둘(`shipped`·`cancelled`)로 물으면 **원본이 다른 낱말을 쓰는 미러에서 끝난 오더가 영영
-   * 백로그에 남는다.** `status` 는 열린 축이고(표준도 `RequestState` 를 열거하지 않는다) 실 시스템은
-   * `completed`·`FINISHED` 를 쓴다 — 그 트윈의 백로그 곡선은 내려가지 않는다. 종결 판정은 커널이
-   * 한 곳에서 한다(`isOrderTerminal` — 낱말이 아니라 **양**을 1차 근거로 본다).
-   *
-   * `shipped` 한 낱말은 남는다. 그것은 이 커널이 **자기가 쓰는 말**이고(WMS 의 출하 완료), 계약의
-   * 종결 목록(`completed` · `cancelled`)에는 없다. 양을 말하지 않는 스냅샷에서 그 오더가 백로그로
-   * 되돌아오지 않게 둘을 함께 본다 — 빼는 쪽이라 이 셈이 전보다 커지는 일은 없다. 커널의 낱말이
-   * 계약의 종결 목록에 들어오는 날 이 줄이 지워진다(아키텍트에게 올림).
-   */
-  backlog: s =>
-    (s?.orders || [])
-      .filter(isFlowOrder)
-      .filter((o: any) => !isOrderTerminal(o) && o.status !== 'shipped').length,
-
-  /*
-   * ── 에너지 ────────────────────────────────────────────────────────────────
-   * `peakKW` 는 **마감된 구간의 최대**다 — 단조 증가라 지평선 위에서 「최대수요가 어디까지 오르나」로
-   * 읽힌다. 열린 구간은 넣지 않는다(아직 확정이 아니다 — 커널이 지키는 규율을 여기서도 지킨다).
-   */
-  peakKW: s => Number(s?.energy?.peakSince?.kW) || 0,
-  /*
-   * 이번 구간이 이대로 가면 얼마로 마감되나 — 커널이 낸 투영(`mean-so-far`)을 그대로 읽는다.
-   * 우리가 다시 계산하지 않는다: 투영 규칙이 두 벌이 되면 화면과 판정이 다른 말을 한다.
-   */
-  projectedKW: s => Number(s?.energy?.open?.projectedKW ?? s?.energy?.open?.meanKW) || 0,
-  /*
-   * 계약을 넘긴 구간 수 — 「몇 번 넘나」는 요금이 걸린 질문이라 최대치와 따로 본다.
-   * 계약을 모르는 트윈에서는 늘 0 이다(넘김을 판정할 근거가 없다 — 지어내지 않는다).
-   */
-  overWindows: s => (s?.energy?.closed || []).filter((w: any) => w?.overContract === true).length
-}
-
-/** 이 지표가 그 종류의 트윈에서 뜻이 있나 — 화면이 목록을 고를 때 쓴다. */
-export const ENERGY_METRICS = ['projectedKW', 'peakKW', 'overWindows'] as const
-export const FLOW_METRICS = ['items', 'occupancy', 'tasks', 'orders', 'shipped', 'backlog'] as const
-
-/**
- * 트윈 종류에 맞는 지표 목록 — **한 곳에서 정한다.**
- *
- * 화면이 각자 목록을 들고 있으면 종류가 늘 때 어느 화면이 뒤처졌는지 알 수 없다.
- */
-export function metricsForKind(kind?: string): string[] {
-  return kind === 'ems' ? [...ENERGY_METRICS] : [...FLOW_METRICS]
-}