@things-factory/headless-twin 10.0.8 → 10.0.10

package/server/service/twin-audit/command-audit.ts

@@ -0,0 +1,81 @@
+/*
+ * 커맨드 감사 기록 만들기 (순수) — **누가 무엇을 허락했고, 그래서 어떻게 됐나.**
+ *
+ * 승인 게이트가 앞을 막고, 이 기록이 뒤를 설명한다. 둘 다 있어야 "사람 손을 거쳤다" 를 증명할 수 있다.
+ *
+ * 무엇을 믿는가가 이 기록의 전부다:
+ *  · **신원·시각은 서버가 준다.** 클라이언트가 말한 신원을 그대로 적으면 위조가 자유로워 아무것도
+ *    증명하지 못한다. 세션이 아는 사용자와 서버 시각만 쓴다.
+ *  · **의도는 클라이언트가 준다** — 출처(origin)·근거(reason). 서버가 알 수 없는 정보이고,
+ *    위조되더라도 신원 증명을 훼손하지 않는다.
+ */
+
+export type CommandOrigin = 'user' | 'ai' | 'automation' | 'unknown'
+
+export type CommandAuditInput = {
+  /** 클라이언트가 실어 보낸 커맨드(신뢰하지 않는 부분을 포함한 원본). */
+  command: any
+  /** 커널 판정. */
+  ack: { accepted?: boolean; errorCode?: string; error?: string }
+  /** 세션이 아는 사용자 — **서버만 채운다.** */
+  actor?: { id?: string; email?: string; name?: string }
+  /** 서버 시각. 호출부가 주입해 테스트가 시간을 고정할 수 있게 한다. */
+  at: Date
+}
+
+/** `TwinAuditEvent` 에 그대로 넣을 수 있는 모양(엔티티를 몰라도 되게 순수하게 둔다). */
+export type CommandAuditRow = {
+  eventTime: Date
+  commandId?: string
+  commandType?: string
+  origin: CommandOrigin
+  reason?: string
+  actorId?: string
+  actorEmail?: string
+  actorName?: string
+  accepted: boolean
+  errorCode?: string
+  args?: any
+  argsTruncated: boolean
+}
+
+/** 신뢰할 수 있는 출처 표기로 정규화 — 모르는 값은 지어내지 않고 'unknown' 으로 둔다. */
+export function normalizeOrigin(v: unknown): CommandOrigin {
+  return v === 'user' || v === 'ai' || v === 'automation' ? v : 'unknown'
+}
+
+/** args 직렬화 상한(문자). 넘으면 자르되 잘랐다고 표시한다. */
+const ARGS_MAX = 4000
+
+export function buildCommandAudit(input: CommandAuditInput): CommandAuditRow {
+  const { command, ack, actor, at } = input
+  const argsText = safeJson(command?.args)
+  const truncated = argsText !== null && argsText.length > ARGS_MAX
+  return {
+    eventTime: at,
+    commandId: str(command?.commandId),
+    commandType: str(command?.type),
+    origin: normalizeOrigin(command?.origin),
+    reason: str(command?.reason),
+    /* 신원 — 세션 값만. 커맨드에 실려 온 신원 주장은 쳐다보지 않는다. */
+    actorId: str(actor?.id),
+    actorEmail: str(actor?.email),
+    actorName: str(actor?.name),
+    /* 결과 — 승인했는데 커널이 거절한 것도 감사 대상이다(무엇을 시도했는지가 남아야 한다). */
+    accepted: !!ack?.accepted,
+    errorCode: str(ack?.errorCode),
+    /* 인자는 원형 그대로. 너무 크면 잘린 문자열로 두되 잘랐다고 말한다. */
+    args: truncated ? argsText!.slice(0, ARGS_MAX) : command?.args ?? undefined,
+    argsTruncated: truncated
+  }
+}
+
+const str = (v: unknown): string | undefined => (typeof v === 'string' && v ? v : undefined)
+
+function safeJson(v: unknown): string | null {
+  try {
+    return v === undefined ? null : JSON.stringify(v)
+  } catch {
+    return null /* 순환 참조 등 — 못 재면 자르지 않는다(원본을 그대로 둔다) */
+  }
+}

package/server/service/twin-audit/index.ts

@@ -0,0 +1,5 @@
+import { TwinAuditEvent } from './twin-audit-event.js'
+import { TwinAuditQuery } from './twin-audit-query.js'
+
+export const entities = [TwinAuditEvent]
+export const resolvers = [TwinAuditQuery]

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

@@ -0,0 +1,112 @@
+import { CreateDateColumn, Entity, Index, Column, RelationId, ManyToOne, PrimaryGeneratedColumn } from 'typeorm'
+import { ObjectType, Field, ID } from 'type-graphql'
+
+import { Domain, ScalarObject } from '@things-factory/shell'
+
+/*
+ * TwinAuditEvent — **사람이 무엇을 허락했는가.**
+ *
+ * ── 왜 저널(TwinEvent)이 아닌가 ───────────────────────────────────────────────
+ * 처음에는 저널에 함께 넣었다. "감사는 원장에서 하니까" 라는 이유였는데, 그건 **화면의 편의**였고
+ * 저장 구조를 정할 근거가 못 됐다. 넣자마자 예외가 넷 생겼다 — 리플레이에서 빼고, 백필에서 빼고,
+ * 원장 거래 분류에서 빼고, 원장 렌더에서 갈랐다. **예외가 넷이면 설계가 "여기 아니다" 라고 말하는 것이다.**
+ *
+ * 갈라 두면 예외가 0 이고, 오히려 얻는다:
+ *  · 행위자가 **컬럼**이 된다 — "누가 승인한 것 전부" 는 감사의 기본 질문인데 payload 안에서는 못 찾았다
+ *  · revision 이 없다. 저널에서는 그 칸을 비워 "상태가 아님" 을 뜻하게 썼는데, 없음을 종류 표시로
+ *    쓰는 것이 여러 번 문제를 냈다(백필의 `bizStep IS NULL = 옛 행` 전제가 이것 때문에 깨졌다)
+ *  · bizStep 오염이 없다 — 저널의 키 추출기는 값이 없으면 이벤트 타입으로 대체하므로,
+ *    감사 행을 태우면 CBV 표준 어휘 컬럼에 `governance.command` 가 박힌다
+ *
+ * ── 무엇을 믿는가 ────────────────────────────────────────────────────────────
+ * **신원·시각은 서버가 각인한다.** 클라이언트가 말한 신원을 그대로 적으면 위조가 자유로워 그 기록은
+ * 아무것도 증명하지 못한다. 세션이 아는 사용자와 서버 시각만 신뢰한다.
+ * 클라이언트에서 받는 것은 **의도**뿐이다 — 어디서 시작됐나(origin), 왜 하나(reason).
+ */
+@Entity()
+/* 목록 기본 정렬 — 최근 것부터. 감사는 "요즘 무슨 일이 있었나" 로 시작한다. */
+@Index('ix_twin_audit_0', (e: TwinAuditEvent) => [e.domain, e.instanceId, e.eventTime], { unique: false })
+/* 행위자로 찾기 — 저널에 있을 때는 불가능했던 질문("김현장이 승인한 것 전부"). */
+@Index('ix_twin_audit_1', (e: TwinAuditEvent) => [e.domain, e.actorEmail, e.eventTime], { unique: false })
+@ObjectType({ description: 'Audit record of a twin command: who approved what, and what the kernel answered.' })
+export class TwinAuditEvent {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(type => ID, { description: 'Unique identifier of the audit record.' })
+  readonly id: string
+
+  @ManyToOne(type => Domain)
+  @Field(type => Domain, { nullable: true, description: 'Owning tenant domain.' })
+  domain?: Domain
+
+  @RelationId((e: TwinAuditEvent) => e.domain)
+  domainId?: string
+
+  @Column()
+  @Field({ description: 'Twin runtime instance the command was aimed at.' })
+  instanceId: string
+
+  /*
+   * 서버 시각. 클라이언트 시계를 믿지 않는다 — 기록의 시간축이 단말 설정에 좌우되면 안 된다.
+   *
+   * `datetime` 을 쓴다. `timestamp` 는 **sqlite 가 지원하지 않아** 5개 드라이버 공통이 아니다
+   * (실제로 그렇게 썼다가 DB 를 쓰는 검사 33개가 한꺼번에 터졌다).
+   */
+  @Column({ type: 'datetime' })
+  @Field({ description: 'Server time when the command was dispatched.' })
+  eventTime: Date
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Client-supplied command id, for correlating with kernel logs.' })
+  commandId?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Command type (e.g. order.hold, equipment.repair).' })
+  commandType?: string
+
+  /* 'user' | 'ai' | 'automation' | 'unknown'. 모르면 unknown 이지 사람이 한 것으로 치지 않는다. */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: "Where the command originated: 'user' | 'ai' | 'automation' | 'unknown'." })
+  origin?: string
+
+  @Column({ type: 'text', nullable: true })
+  @Field({ nullable: true, description: 'Why this action — the rationale shown on the approval card.' })
+  reason?: string
+
+  /* ── 신원: 세션에서만 온다 ── */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Approving user id, stamped by the server from the session.' })
+  actorId?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Approving user email, stamped by the server from the session.' })
+  actorEmail?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Approving user name, stamped by the server from the session.' })
+  actorName?: string
+
+  /* ── 결과: 거절도 남긴다 ── */
+  @Column({ default: false })
+  @Field({ description: 'Whether the kernel accepted the command.' })
+  accepted: boolean
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Language-neutral rejection code when the kernel refused.' })
+  errorCode?: string
+
+  /**
+   * 명령 인자 — **원형 그대로.** 무엇에 대한 명령이었는지가 감사의 핵심이라 요약하지 않는다.
+   * 지나치게 크면 자르되 `argsTruncated` 로 잘랐다는 사실을 남긴다(조용히 버리지 않는다).
+   */
+  @Column({ type: 'simple-json', nullable: true })
+  @Field(type => ScalarObject, { nullable: true, description: 'Command arguments as given.' })
+  args?: any
+
+  @Column({ default: false })
+  @Field({ description: 'True when args were too large and stored truncated.' })
+  argsTruncated: boolean
+
+  @CreateDateColumn()
+  @Field({ nullable: true, description: 'Timestamp when the audit row was written.' })
+  createdAt?: Date
+}

package/server/service/twin-audit/twin-audit-query.ts

@@ -0,0 +1,72 @@
+import { Args, Ctx, Query, Resolver } from 'type-graphql'
+
+import { ListParam, getQueryBuilderFromListParams, getRepository, ScalarObject } from '@things-factory/shell'
+
+import { TwinAuditEvent } from './twin-audit-event.js'
+
+/*
+ * 승인 기록 조회 — **감사의 기본 질문에 답한다.**
+ *
+ *   "요즘 무슨 조치가 나갔나"        → 최근순 목록
+ *   "김현장이 승인한 것 전부"        → 행위자 검색(인덱스 있음)
+ *   "AI 가 제안한 것만"              → origin 필터
+ *   "거절된 시도"                    → accepted 필터
+ *
+ * 저널에 섞여 있을 때는 이 중 어느 것도 못 했다 — 행위자가 payload JSON 안이라 인덱스를 걸 수 없었다.
+ */
+/** 시각 필터 값을 날짜로 — 못 읽는 값은 그대로 둔다(지어내지 않는다). */
+function toDateValue(v: any): any {
+  const one = (x: any) => {
+    if (x instanceof Date) return x
+    const t = typeof x === 'string' ? Date.parse(x) : NaN
+    return Number.isNaN(t) ? x : new Date(t)
+  }
+  return Array.isArray(v) ? v.map(one) : one(v)
+}
+
+@Resolver()
+export class TwinAuditQuery {
+  /* 조회 게이트는 달지 않는다 — 이 저장소의 규약이고(mutation-gate 검사가 정본을 지킨다),
+     도메인 필터가 테넌트 경계를 이미 지킨다. 테넌트를 넘어 읽는 계기판만 OPS_GATE 를 쓴다. */
+  @Query(returns => ScalarObject, {
+    nullable: true,
+    description:
+      'List twin command audit records (who approved what, and what the kernel answered) with the standard list contract, plus the total match count.'
+  })
+  async twinAuditList(
+    /* 표준 목록 계약은 `@Args` 로 펼쳐 받는다 — `@Arg` 로 받으면 type-graphql 이 입력 타입을
+       결정하지 못해 **스키마 조립 자체가 실패**한다(서버가 아예 안 뜬다). */
+    @Args(type => ListParam) params: ListParam,
+    @Ctx() context: ResolverContext
+  ): Promise<any> {
+    const domainId = context.state.domain?.id
+    if (!domainId) return { items: [], total: 0 }
+
+    const effective: ListParam = {
+      ...(params ?? ({} as ListParam)),
+      /* 기본 정렬 — 최근 것부터. 감사는 "요즘" 에서 시작한다. */
+      sortings: params?.sortings?.length ? params.sortings : [{ name: 'eventTime', desc: true }],
+      /* 시각 필터는 날짜로 옮겨서 넘긴다 — 문자열 그대로면 조용히 0건이 된다(저널과 같은 이유). */
+      filters: (params?.filters ?? []).map(f => (f.name === 'eventTime' ? { ...f, value: toDateValue(f.value) } : f))
+    }
+
+    const qb = getQueryBuilderFromListParams({
+      repository: getRepository(TwinAuditEvent),
+      params: effective,
+      domain: context.state.domain,
+      alias: 'a',
+      /*
+       * `searchables` 는 전부 **실컬럼**이다 — 프레임워크 질의 빌더는 여기 없는 컬럼의 LIKE 를
+       * 경고 후 무시한다(인덱스 없는 전체 스캔 방지). 행위자로 찾는 것이 이 테이블을 구분한 이유다.
+       */
+      searchables: ['actorEmail', 'actorName', 'commandType', 'origin', 'errorCode', 'reason'],
+      sortables: ['eventTime', 'commandType', 'actorEmail', 'origin', 'accepted'],
+      /* 감사 목록은 사람이 읽는 속도로 본다 — 크게 퍼 오는 것이 이득이 아니다. */
+      defaultLimit: 50,
+      maxLimit: 200
+    })
+
+    const [items, total] = await qb.getManyAndCount()
+    return { items, total }
+  }
+}

package/server/service/twin-control/twin-control-mutation.ts

@@ -1,8 +1,14 @@
-import { Arg, Ctx, Mutation, Resolver } from 'type-graphql'
+import { Arg, Ctx, Mutation, Resolver, Directive} from 'type-graphql'
+
+import { validateScenario } from '@operato/twin-kernel'
 
 import { ScalarObject } from '@things-factory/shell'
 
+import { getRepository } from '@things-factory/shell'
+
 import { TwinEngine } from '../../engine/index.js'
+import { TwinAuditEvent } from '../twin-audit/twin-audit-event.js'
+import { buildCommandAudit } from '../twin-audit/command-audit.js'
 
 /*
  * 트윈 Command·Scenario 채널 — 상향 mutation.
@@ -15,27 +21,48 @@ import { TwinEngine } from '../../engine/index.js'
 @Resolver()
 export class TwinControlMutation {
   /** Command 채널 — 오더 hold/resume/release 등. 커널 dispatch 로 위임, ack{accepted,error} 반환. */
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => ScalarObject, { description: 'dispatch a twin command (order.hold/resume/release …). Returns {accepted, error?}.' })
   async dispatchTwinCommand(
     @Arg('instanceId') instanceId: string,
     @Arg('command', type => ScalarObject) command: any,
     @Ctx() context: ResolverContext
-  ): Promise<{ accepted: boolean; error?: string }> {
+  ): Promise<{ accepted: boolean; error?: string; errorCode?: string; errorParams?: Record<string, string | number> }> {
     const domainId = context.state.domain?.id
-    const inst = TwinEngine.instances[instanceId]
-    if (!inst || inst.domainId !== domainId) {
-      return { accepted: false, error: 'instance not found in your domain' }
-    }
-    /* tenantId 를 호출자 도메인으로 각인(감사·무결성) — 클라 위조 방지. */
-    const ack = inst.runtime.dispatch({ ...command, tenantId: domainId })
-    /* 라이브 구조 변이(resource.add)는 저장 board 에도 반영 — 프로비저닝 편집기·재기동이 추가분을 잃지 않게. */
+    if (!domainId) return { accepted: false, error: 'no-domain', errorCode: 'no-domain' }
+    /*
+     * 라우팅은 엔진이 한다 — 예전에는 여기서 `inst.runtime.dispatch` 를 곧바로 불렀고, `runtime` 이
+     * 시뮬에만 있어서 미러 트윈에서는 이 한 줄이 TypeError 로 터졌다(깔끔한 거절이 아니라 실패).
+     * 권위(모드) × 성격(주석/액추에이션) 판정은 한 곳에만 둔다.
+     */
+    /* 원본을 그대로 감사에 넘긴다 — 무엇이 들어왔는지가 기록의 대상이다(정규화는 감사 모듈이 한다). */
+    const cmdWithOrigin = command
+    const ack = await TwinEngine.dispatchCommand(domainId, instanceId, command)
+    /* 라이브 구조 변이(resource.add)는 저장 model 에도 반영 — 프로비저닝 편집기·재기동이 추가분을 잃지 않게. */
     if (ack?.accepted && command?.type === 'resource.add') {
       await TwinEngine.syncBoardEquipment(domainId, instanceId).catch(err => console.error('twin syncBoardEquipment fail', err))
     }
-    return { accepted: !!ack?.accepted, error: ack?.error }
+    /*
+     * 감사 기록 — 승인 게이트가 앞을 막고, 이 줄이 뒤를 설명한다. 둘 다 있어야 "사람 손을 거쳤다" 를
+     * 증명할 수 있다. 커널이 거절한 것도 남긴다 — 무엇을 시도했는지가 감사의 절반이다.
+     *
+     * 기록이 실패해도 커맨드 결과는 그대로 돌려준다. 감사가 본업을 막으면 안 되지만, 실패를 삼키지도
+     * 않는다(로그에 남긴다) — 조용히 안 남으면 나중에 "기록이 없다" 와 "일이 없었다" 를 구분 못 한다.
+     */
+    try {
+      const audit = buildCommandAudit({ command: cmdWithOrigin, ack, actor: context.state.user, at: new Date() })
+      const repo = getRepository(TwinAuditEvent)
+      await repo.save(repo.create({ domain: context.state.domain, instanceId, ...audit }))
+    } catch (err) {
+      console.error(`[twin-control] command audit not recorded for "${instanceId}"`, err)
+    }
+
+    /* 거절 사유는 **언어 중립 코드**로 함께 돌려준다 — 화면이 `twin.cmderr.<code>` 로 사람 말을 만든다. */
+    return { accepted: !!ack?.accepted, error: ack?.error, errorCode: ack?.errorCode, errorParams: ack?.errorParams }
   }
 
   /** Scenario 채널 — 생성기 시나리오 제어(load/start/pause/setSpeed). */
+  @Directive('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)')
   @Mutation(returns => Boolean, { description: 'control twin scenario (load|start|pause|setSpeed)' })
   async controlTwinScenario(
     @Arg('instanceId') instanceId: string,
@@ -44,14 +71,27 @@ export class TwinControlMutation {
     @Arg('scenario', type => ScalarObject, { nullable: true }) scenario?: any
   ): Promise<boolean> {
     const domainId = context.state.domain?.id
-    const inst = TwinEngine.instances[instanceId]
-    if (!inst || inst.domainId !== domainId) return false
-    const runtime = inst.runtime
+    /* 테넌트 격리 — 레지스트리를 직접 색인하지 않는다(키에 도메인이 들어 있다). */
+    if (!TwinEngine.owns(domainId, instanceId)) return false
+    const runtime = TwinEngine.runtime(domainId, instanceId)
     /*
      * 자극 주입 가드 — mirror 트윈(외부 실물이 진실)은 커널 시나리오 엔진이 없다(startLive=projector, runtime 없음).
      * what-if 를 여기에 주입하면 현실을 오염시키므로 거부한다(sim-experiment/sim-world 만 자극 가능). silent throw 방지.
      */
     if (!runtime?.scenario) return false
+    /*
+     * **잘못된 선언은 문 앞에서 막는다.** 예전에는 검증 없이 실었고, 다음 tick 에서 `rate.meanPerHour`
+     * 를 읽다 터져 **서버 프로세스가 내려갔다**(클라이언트가 보낸 값 하나로 앱 전체가 죽었다).
+     * 규칙은 커널이 들고 있다(계약의 주인) — 호스트가 따로 만들면 방언이 생긴다.
+     */
+    if (action === 'load') {
+      const v = validateScenario(scenario)
+      if (v.ok === false) {
+        /* 사유를 로그로 남긴다 — 이 뮤테이션의 반환은 Boolean 계약이라 사유를 실어 보낼 자리가 없다. */
+        console.warn(`[twin] scenario rejected for "${instanceId}": ${v.errorCode} ${JSON.stringify(v.errorParams ?? {})}`)
+        return false
+      }
+    }
     if (action === 'load' && scenario) runtime.scenario.load(scenario)
     else if (action === 'start') runtime.scenario.start()
     else if (action === 'pause') runtime.scenario.pause()

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

@@ -83,7 +83,7 @@ export function locationOf(envelope: any): string | undefined {
  * 설비·무버 — 운영 델타(equipment.status·task.status)가 대상을 가리키는 축.
  *
  * EPCIS 어휘가 아니라서 다른 축 어디에도 안 잡힌다. 이게 없으면 "이 지게차가 오늘 무엇을 했나" 를
- * 서버에서 물을 방법이 없어, 화면이 저널을 통째로 받아 훑는 수밖에 없다.
+ * 서버에서 물을 방법이 없어, 화면이 저널을 통째로 받아 전수 조회하는 수밖에 없다.
  */
 export function equipmentIdOf(envelope: any): string | undefined {
   const d = envelope?.data ?? envelope ?? {}

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

@@ -23,7 +23,7 @@ import { Domain, ScalarObject } from '@things-factory/shell'
  *
  * bizStep·locationId·moverId 는 컬럼만 두고 인덱스는 두지 않는다 — 한 트윈 안에서 카디널리티가
  * 낮아(업무단계 몇 개, 위치 수백, 설비 수십) (domain,instanceId) 로 이미 좁혀진 뒤의 잔여 필터로
- * 충분하고, 뜨거운 표에 인덱스를 더 얹을 값어치가 없다. 저널 하나가 아주 커져서 이 축들의 조회가
+ * 충분하고, 뜨거운 표에 인덱스를 더 얹을 가치가 없다. 저널 하나가 아주 커져서 이 축들의 조회가
  * 느려지면 그때 측정을 근거로 인덱스를 추가할 일이지, 지레 얹어 쓰기를 무겁게 할 일은 아니다.
  */
 @Entity()
@@ -32,6 +32,8 @@ import { Domain, ScalarObject } from '@things-factory/shell'
 @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 })
 @ObjectType({ description: 'Append-only twin event journal record (EPCIS event or operational delta).' })
 export class TwinEvent {
   @PrimaryGeneratedColumn('uuid')
@@ -45,17 +47,19 @@ export class TwinEvent {
   @RelationId((e: TwinEvent) => e.domain)
   domainId?: string
 
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Twin runtime instance id that emitted the event.' })
-  instanceId?: string
-
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Kernel tenant id carried on the canonical envelope.' })
-  tenantId?: string
+  /*
+   * 이 사실을 낸 트윈. **빌 수 없다** — 저널 행을 만드는 곳은 `journalRow` 하나뿐이고 거기서
+   * 필수 인자로 받는다. nullable 로 두면 읽는 쪽이 매번 `?? ''` 를 달게 되고, 그 방어가 실제로는
+   * 일어나지 않는 경우를 대비하느라 "빈 인스턴스의 이벤트" 라는 없는 개념을 코드에 남긴다.
+   */
+  @Column()
+  @Field({ description: 'Twin runtime instance id that emitted the event.' })
+  instanceId: string
 
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Event type: epcis.* | task.status | equipment.status | order.status.' })
-  eventType?: 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.' })
@@ -66,7 +70,7 @@ export class TwinEvent {
    *
    * 이것이 없던 시절에는 구조가 바뀌면 저널을 통째로 지우는 것이 유일한 길이었다(안 지우면 옛
    * 이벤트를 새 공장에 대고 접어 이력이 거짓말을 한다). 이 한 칸이 셋째 길을 연다 — 재생이
-   * 구조가 바뀌는 지점에서 갈아탄 뒤 이어 접는다.
+   * 구조가 바뀌는 지점에서 전환한 뒤 이어 접는다.
    *
    * **비어 있을 수 있다**: 컬럼이 생기기 전에 쓰인 행이다. 그 행들은 **가장 오래된 리비전**에
    * 속한다(0 을 채워 넣지 않는다 — 0 은 "모름" 이 아니라 유효한 번호처럼 보인다).
@@ -75,9 +79,18 @@ export class TwinEvent {
   @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
 
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Simulation event time (ISO 8601).' })
-  eventTime?: string
+  /*
+   * 이 사실이 일어난 시각(트윈의 시계). **날짜 타입이다.**
+   *
+   * 예전에는 문자열이었다. 읽을 때마다 `Date.parse` 했고, 정렬은 UTC ISO 만 들어온다는 전제 위에서
+   * 사전식 비교가 우연히 맞았다 — `+09:00` 오프셋 표기가 하나 섞이면 조용히 순서가 틀린다.
+   * 그 전제는 컬럼 어디에도 적혀 있지 않았다.
+   *
+   * `datetime` 을 쓴다. `timestamp` 는 sqlite 가 지원하지 않아 5개 드라이버 공통이 아니다.
+   */
+  @Column({ type: 'datetime', nullable: true })
+  @Field({ nullable: true, description: 'Time at which the fact happened on the twin clock.' })
+  eventTime?: Date
 
   /*
    * ── 승격된 검색 축 ────────────────────────────────────────────────────────
@@ -86,7 +99,31 @@ export class TwinEvent {
    * 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
+
   @Column({ length: 255, nullable: true })
   @Field({ nullable: true, description: 'Business step (CBV bizStep tail), promoted from the payload for indexed filtering.' })
   bizStep?: string

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

@@ -0,0 +1,60 @@
+/*
+ * 예측 지표 — **스냅샷에서 수 하나를 뽑는 규칙.**
+ *
+ * ── 왜 순수 모듈인가 (2026-08-15) ───────────────────────────────────────────
+ * 이 표가 리졸버 안에 있어서 시험이 불러올 수 없었다(type-graphql·shell 을 물고 있다). 그런데 여기서
+ * 틀리면 예측 그래프 전체가 조용히 다른 것을 그린다 — 오류 없이. 규칙은 시험이 닿는 자리에 둔다.
+ *
+ * ── 에너지 지표를 더한 이유 ─────────────────────────────────────────────────
+ * 예측 화면의 지표가 물류 여섯(재고·점유·작업·오더·출고·백로그)으로 고정돼 있어서, 에너지 트윈을
+ * 고르면 **남의 질문에 답하는 그래프**가 떴다. 에너지 트윈에는 재고도 오더도 없으므로 그 값들은
+ * 전부 0 이고, 0 은 「없다」가 아니라 「이 트윈의 질문이 아니다」이다.
+ *
+ * 여기 더한 셋은 **커널이 이미 상태로 들고 있는 것**이다 — 새 계산을 만들지 않았다. 특히 부하 합은
+ * 커널이 뿌리 계량기로만 세는데(계층 계량의 이중 계상 방지), 그 규칙을 여기서 다시 쓰면 두 벌이 된다.
+ * 그래서 지점을 직접 더하지 않고 **구간 값**을 읽는다.
+ */
+
+/** 스냅샷 → 수 하나. 값이 없으면 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,
+  orders: s => (s?.orders || []).length,
+  // 이행 지표 — 라이브 예측의 핵심 질문("언제 다 나가나·백로그 언제 풀리나").
+  shipped: s => (s?.orders || []).filter((o: any) => o.status === 'shipped').length,
+  backlog: s => (s?.orders || []).filter((o: any) => o.status !== 'shipped' && o.status !== 'cancelled').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]
+}

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

@@ -0,0 +1,40 @@
+/*
+ * 예측을 얼마나 잘게 굴릴 것인가 — **한 회차의 틱 수를 묶는다.**
+ *
+ * ── 왜 필요한가 (2026-08-17 실측) ───────────────────────────────────────────
+ * 예측 비용의 거의 전부가 틱이다. 트윈 하나의 예측 한 번이 30회차 × 300틱 = 9,000틱, 한 틱 3.2ms →
+ * 28.5초였다. 그런데 몬테카를로는 지평선 **끝에서** 지표를 한 번 읽는다 — 중간을 1초 단위로 볼 이유가
+ * 없다면 성글게 굴려도 답이 같다.
+ *
+ * 정말 같은지는 재서 확인했다(`operato-twin/test/fork-cost.test.ts`, 10회차·지평선 5분):
+ *
+ *   step  1s → 3,048ms · 재고 p50 325 · 완료작업 8 · 완료오더 0
+ *   step  5s →   628ms · 재고 p50 325 · 완료작업 8 · 완료오더 0   ← 답이 같고 5배 싸다
+ *   step 10s →   286ms · 재고 p50 326 · …                        ← 여기서부터 흔들린다
+ *
+ * ── 왜 고정 step 이 아니라 틱 수 상한인가 ───────────────────────────────────
+ * step 을 5초로 못 박으면 1분짜리 지평선은 12틱이 되어 너무 성글고, 2시간짜리는 1,440틱이라 여전히
+ * 비싸다. 묶어야 하는 것은 step 이 아니라 **한 회차가 도는 횟수**다.
+ *
+ * 상한(10초)을 따로 두는 이유: 지평선이 길다고 무한정 성글게 굴리면 짧은 작업(초 단위 피킹)이 통째로
+ * 한 틱에 삼켜진다. 그 지점을 넘지 않는다.
+ */
+
+/** 한 회차가 도는 틱 수의 목표 — 이보다 잘게 굴려야 할 이유가 생기면 여기를 고친다. */
+export const TARGET_TICKS_PER_RUN = 60
+/** 아무리 지평선이 길어도 이보다 성글게 굴리지 않는다 — 짧은 작업이 한 틱에 삼켜진다. */
+export const MAX_STEP_MS = 10_000
+/** 커널의 시각 단위 — 이보다 잘게 굴릴 이유는 없다. */
+export const MIN_STEP_MS = 1_000
+
+/**
+ * 이 지평선을 굴릴 틱 크기.
+ *
+ * 초 단위로 떨어뜨린다 — 3,333ms 같은 값은 사람이 읽을 수도, 화면이 설명할 수도 없다.
+ */
+export function forecastStepMs(horizonMs: number): number {
+  if (!Number.isFinite(horizonMs) || horizonMs <= 0) return MIN_STEP_MS
+  const raw = horizonMs / TARGET_TICKS_PER_RUN
+  const rounded = Math.round(raw / MIN_STEP_MS) * MIN_STEP_MS
+  return Math.min(MAX_STEP_MS, Math.max(MIN_STEP_MS, rounded))
+}