@things-factory/headless-twin 10.0.9 → 10.0.10

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

@@ -4,7 +4,11 @@ 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.
@@ -31,11 +35,28 @@ export class TwinControlMutation {
      * 시뮬에만 있어서 미러 트윈에서는 이 한 줄이 TypeError 로 터졌다(깔끔한 거절이 아니라 실패).
      * 권위(모드) × 성격(주석/액추에이션) 판정은 한 곳에만 둔다.
      */
+    /* 원본을 그대로 감사에 넘긴다 — 무엇이 들어왔는지가 기록의 대상이다(정규화는 감사 모듈이 한다). */
+    const cmdWithOrigin = command
     const ack = await TwinEngine.dispatchCommand(domainId, instanceId, command)
-    /* 라이브 구조 변이(resource.add)는 저장 board 에도 반영 — 프로비저닝 편집기·재기동이 추가분을 잃지 않게. */
+    /* 라이브 구조 변이(resource.add)는 저장 model 에도 반영 — 프로비저닝 편집기·재기동이 추가분을 잃지 않게. */
     if (ack?.accepted && command?.type === 'resource.add') {
       await TwinEngine.syncBoardEquipment(domainId, instanceId).catch(err => console.error('twin syncBoardEquipment fail', err))
     }
+    /*
+     * 감사 기록 — 승인 게이트가 앞을 막고, 이 줄이 뒤를 설명한다. 둘 다 있어야 "사람 손을 거쳤다" 를
+     * 증명할 수 있다. 커널이 거절한 것도 남긴다 — 무엇을 시도했는지가 감사의 절반이다.
+     *
+     * 기록이 실패해도 커맨드 결과는 그대로 돌려준다. 감사가 본업을 막으면 안 되지만, 실패를 삼키지도
+     * 않는다(로그에 남긴다) — 조용히 안 남으면 나중에 "기록이 없다" 와 "일이 없었다" 를 구분 못 한다.
+     */
+    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 }
   }

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))
+}

package/server/service/twin-forecast/gap-analytics.ts

@@ -23,19 +23,58 @@ export interface GapPoint {
   modelAbsError: number
 }
 
-/** 공동배치(co-located) 트윈들의 per-instance 점 배열을 공장 단위 한 시계열로 합산(index-wise, 동일 부팅 → vantage 정렬 가정). */
-export function aggregatePoints(per: GapPoint[][]): GapPoint[] {
+/** 합산 결과 + **무엇을 못 넣었는지.** 조용히 줄이지 않는다. */
+export interface AggregateResult {
+  points: GapPoint[]
+  /** 한 트윈이라도 재지 못해 통째로 뺀 vantage 수. */
+  droppedVantages: number
+}
+
+/**
+ * 공동배치(co-located) 트윈들의 점 배열을 공장 단위 한 시계열로 합산.
+ *
+ * ── 예전에 무엇이 어긋나 있었나 (2026-08-08) ─────────────────────────────────
+ * "동일 부팅 → vantage 정렬" 을 **가정**하고 배열 인덱스끼리 더했다. 그 가정은 세 곳에서 깨졌다:
+ *
+ *  ① 격자를 트윈마다 자기 저널의 첫·마지막 이벤트로 만들었다. 저널 구간이 다르면 같은 인덱스가
+ *    서로 다른 시각이다. **부팅이 같아도** 어긋난다.
+ *  ② 한 vantage 를 못 재면 `continue` 로 건너뛰고 밀어 담았다. 그 순간부터 인덱스가 한 칸씩 밀린다.
+ *  ③ 길이를 `max` 로 잡아, 뒤쪽 인덱스는 남은 트윈만 더해졌다 — 공장 합계 곡선이 꼬리에서
+ *    아래로 꺾인다. 공장과 아무 상관 없는 이유로.
+ *
+ * 셋 다 오류를 내지 않았다. 그럴듯한 곡선이 나오고, 그 곡선으로 예측 정확도를 판정했다.
+ *
+ * ── 지금 ────────────────────────────────────────────────────────────────────
+ * 격자는 밖에서 하나를 만들어 모두에게 같은 것을 주고(`sharedGrid`), 못 잰 자리는 `null` 로
+ * 남긴다. 여기서는 **모든 트윈이 값을 가진 vantage 만** 더한다. 하나라도 비면 그 시각의
+ * 공장 총량은 알 수 없는 것이지, 그 트윈이 0 을 낸 것이 아니다.
+ *
+ * 뺀 개수는 돌려준다 — 화면이 "24점 중 18점" 이라고 말할 수 있어야 한다.
+ */
+export function aggregatePoints(per: (GapPoint | null)[][]): AggregateResult {
+  if (!per.length) return { points: [], droppedVantages: 0 }
   const n = Math.max(0, ...per.map(pts => pts.length))
   const out: GapPoint[] = []
+  let droppedVantages = 0
   for (let i = 0; i < n; i++) {
-    let t = 0, p50 = 0, min = 0, max = 0, actual = 0, na = 0, ma = 0, has = false
-    for (const pts of per) {
-      const pt = pts[i]
-      if (pt) { has = true; t = pt.t; p50 += pt.p50 || 0; min += pt.min || 0; max += pt.max || 0; actual += pt.actual || 0; na += pt.naiveAbsError || 0; ma += pt.modelAbsError || 0 }
-    }
-    if (has) out.push({ t, p50, min, max, actual, error: actual - p50, inBand: actual >= min && actual <= max, naiveAbsError: na, modelAbsError: ma })
+    const slot = per.map(pts => pts[i])
+    if (slot.some(pt => !pt)) { droppedVantages++; continue }
+    const pts = slot as GapPoint[]
+    const sum = (f: (p: GapPoint) => number) => pts.reduce((a, p) => a + f(p), 0)
+    const p50 = sum(p => p.p50)
+    const min = sum(p => p.min)
+    const max = sum(p => p.max)
+    const actual = sum(p => p.actual)
+    out.push({
+      t: pts[0].t, // 격자가 하나이므로 어느 트윈에서 읽어도 같다.
+      p50, min, max, actual,
+      error: actual - p50,
+      inBand: actual >= min && actual <= max,
+      naiveAbsError: sum(p => p.naiveAbsError),
+      modelAbsError: sum(p => p.modelAbsError)
+    })
   }
-  return out
+  return { points: out, droppedVantages }
 }
 
 /** 안정성 축 + 편향 축 판정(관리도). errors = 실제−예측 시계열. */