@things-factory/headless-twin 10.0.6 → 10.0.7

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

@@ -3,6 +3,8 @@ import { Arg, Ctx, Int, Mutation, Query, Resolver } from 'type-graphql'
 import { getRepository, ScalarObject } from '@things-factory/shell'
 
 import { TwinEngine } from '../../engine/index.js'
+import { readSpecCoverage } from '../../engine/spec-coverage.js'
+import { describeModelBasis, modelBasisChanged, type ModelBasis } from '../../engine/model-basis.js'
 import { TwinEvent } from '../twin-event/twin-event.js'
 import { GAP_SAMPLES, aggregatePoints, computeSpc, gapMetrics, learnedCalibration, type GapPoint } from './gap-analytics.js'
 
@@ -23,7 +25,7 @@ const DEFAULT_SCENARIO = {
 }
 const METRICS: Record<string, (s: any) => number> = {
   items: s => (s.items || []).length,
-  occupancy: s => (s.nodes || []).reduce((a: number, n: any) => a + (n.occupancy || 0), 0),
+  occupancy: s => (s.locations || []).reduce((a: number, n: any) => a + (n.occupancy || 0), 0),
   tasks: s => (s.tasks || []).length,
   orders: s => (s.orders || []).length,
   // 이행 지표 — 라이브 예측의 핵심 질문("언제 다 나가나·백로그 언제 풀리나").
@@ -34,7 +36,10 @@ const METRICS: Record<string, (s: any) => number> = {
 /* 학습된 보정 저장(P3.2, 인메모리) — key=domain:instance:metric:horizon → {biasShift, halfWidth, …}.
    twinLearnCalibration 이 갭에서 학습해 저장하고, twinForecast 가 있으면 예측에 상시 적용(라이브 보정).
    데모 트윈은 재부팅 시 저널 리셋이라 세션 스코프로 충분 — DB 영속(TwinForecastScore)은 후속. */
-const CALIBRATION = new Map<string, { biasShift: number; halfWidth: number; at: string; samples: number; accBefore: number; accAfter: number }>()
+const CALIBRATION = new Map<
+  string,
+  { biasShift: number; halfWidth: number; at: string; samples: number; accBefore: number; accAfter: number; basis?: ModelBasis }
+>()
 const calKey = (d: string, i: string, m: string, h: number) => `${d}:${i}:${m}:${h}`
 
 /* 갭 point 계산(공용) — N개 과거 vantage 각각 forecast-at-T vs actual-at-T+H(결정적 백테스트). gapTrend query·learn mutation 공용. */
@@ -78,12 +83,15 @@ export class TwinForecastQuery {
     @Arg('at', { nullable: true }) at: string,
     @Ctx() context: ResolverContext
   ): Promise<any> {
-    /* vantage(at) 기준 예측 — 히스토리 노브가 과거 T 면 "그때 서서 본 미래"(백테스트, forecast-accuracy-gap 플랜 P0).
-       at 있으면 T 시점 커널 재구성(저널 기반, 도메인 스코프). 없으면 지금: 라이브 커널 직접(도메인 소유 시) / buildForecastKernel. */
+    /* vantage(at) 기준 예측 — 히스토리 노브가 과거 T 면 "그때 서서 본 미래"(백테스트).
+       at 있으면 T 시점 커널을 저널로 재구성한다(그건 우회가 아니라 시간여행의 본질).
+       없으면 **지금 그 커널**을 쓴다 — sim 이든 live 든 인스턴스가 커널이다(통합 P2). */
     const domainId = context.state.domain.id
     const k = at
       ? await TwinEngine.buildForecastKernelAt(domainId, instanceId, at)
-      : (TwinEngine.owns(domainId, instanceId) ? TwinEngine.kernel(instanceId) : undefined) ?? (await TwinEngine.buildForecastKernel(domainId, instanceId))
+      : TwinEngine.owns(domainId, instanceId)
+        ? TwinEngine.kernel(instanceId)
+        : undefined
     if (!k) return null
 
     const m = METRICS[metric] ?? METRICS.items
@@ -97,7 +105,23 @@ export class TwinForecastQuery {
 
     /* 학습된 보정 상시 적용(P3.2) — twinLearnCalibration 이 저장한 편향·밴드가 있으면 예측을 현실로 보정(라이브가 실제로 나아짐).
        갭트렌드(gapPoints)는 raw 모델을 그대로 측정(학습 신호 보존) — 보정은 표시용 forecast 에만. */
-    const cal = CALIBRATION.get(calKey(domainId, instanceId, metric ?? 'items', H))
+    const stored = CALIBRATION.get(calKey(domainId, instanceId, metric ?? 'items', H))
+    /*
+     * **배운 모델에만 적용한다.** 보정은 "그때 모델이 이만큼 치우쳐 있다" 를 배운 것이다. 소요시간
+     * 추정기(실측·거리)나 공정 명세가 바뀌어 모델이 달라지면 그 편향은 더 이상 사실이 아니고, 그대로
+     * 밀어 주면 이중 보정이 된다. 그래서 지문을 비교하고, 다르면 적용하지 않되 **그 사실을 응답에
+     * 싣는다** — 조용히 사라지면 사용자는 학습이 왜 안 듣는지 알 수 없다(다시 배우면 된다).
+     * 지문을 알 수 없을 때는 비교하지 않는다(모르는 것을 근거로 보정을 끊지 않는다).
+     */
+    const basis = await TwinEngine.modelBasis(domainId, instanceId)
+    const stale = !!stored && modelBasisChanged(stored.basis, basis)
+    if (stale) {
+      console.log(
+        `[twin-forecast] "${instanceId}": calibration not applied — model changed since it was learned.` +
+          ` learned on: ${describeModelBasis(stored!.basis)} / now: ${describeModelBasis(basis)}`
+      )
+    }
+    const cal = stored && !stale ? stored : undefined
     if (cal && distribution) {
       const p50c = (distribution.p50 ?? 0) + cal.biasShift
       distribution.p50 = Math.round(p50c)
@@ -148,7 +172,21 @@ export class TwinForecastQuery {
       }
     }
 
-    return { metric: metric ?? 'items', horizonMs: H, runs: R, current, distribution, trajectory, actual, scored, calibrated: !!cal }
+    /*
+     * 시뮬 명세 자기보고를 함께 낸다 — **상수로 굴린 예측과 현장 명세로 굴린 예측이 화면에서 같아
+     * 보이지 않게.** 코드·수치만 싣고 사람이 읽는 문장은 클라가 만든다(언어 중립).
+     * 커널이 이 API 를 갖지 않은 버전이면 키를 만들지 않는다(모르는 것을 "전부 기본값" 이라 단정 금지).
+     */
+    /* 보고는 **실제로 굴린 fork** 에서 읽는다 — 부모 커널(k)은 tick 하지 않으므로(예측은 fork 에서
+     * 돈다) 부모에서 읽으면 씨앗으로 세운 예측에서는 늘 비어 있다. 숫자를 낸 주체가 보고해야 한다. */
+    const specCoverage = readSpecCoverage(fc) ?? readSpecCoverage(k)
+    return {
+      metric: metric ?? 'items', horizonMs: H, runs: R, current, distribution, trajectory, actual, scored,
+      calibrated: !!cal,
+      /* 학습해 뒀지만 모델이 바뀌어 적용하지 않았다 — 사용자가 다시 배울 수 있게 알린다. */
+      ...(stale ? { calibrationStale: true } : {}),
+      ...(specCoverage ? { specCoverage } : {})
+    }
   }
 
   /*
@@ -211,7 +249,17 @@ export class TwinForecastQuery {
     const pts = await gapPoints(domainId, instanceId, m, H, GAP_SAMPLES, DEFAULT_SCENARIO)
     if (pts.length < 3) return { ok: false, reason: 'insufficient-history' }
     const learn = learnedCalibration(pts, gapMetrics(pts))
-    const cal = { biasShift: learn.biasShift, halfWidth: learn.halfWidth, at: '', samples: pts.length, accBefore: learn.accBefore, accAfter: learn.accAfter }
+    /* 학습한 모델의 지문을 함께 남긴다 — 이후 모델이 바뀌면 이 보정은 적용되지 않는다. */
+    const basis = await TwinEngine.modelBasis(domainId, instanceId)
+    const cal = {
+      biasShift: learn.biasShift,
+      halfWidth: learn.halfWidth,
+      at: '',
+      samples: pts.length,
+      accBefore: learn.accBefore,
+      accAfter: learn.accAfter,
+      ...(basis ? { basis } : {})
+    }
     CALIBRATION.set(calKey(domainId, instanceId, metric ?? 'items', H), cal)
     return { ok: true, metric: metric ?? 'items', horizonMs: H, biasShift: cal.biasShift, halfWidth: cal.halfWidth, samples: pts.length, accBefore: cal.accBefore, accAfter: cal.accAfter }
   }

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

@@ -46,7 +46,7 @@ export class TwinInstance {
   realityMode?: string
 
   @Column({ type: 'simple-json', nullable: true })
-  @Field(type => ScalarObject, { nullable: true, description: 'BoardDef blueprint (nodes/movers) required to replay events into state.' })
+  @Field(type => ScalarObject, { nullable: true, description: 'BoardDef blueprint (locations/equipment) required to replay events into state.' })
   board?: any
 
   @Column({ nullable: true })

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

@@ -1,5 +1,5 @@
 import { Between, LessThanOrEqual, MoreThanOrEqual } from 'typeorm'
-import { Arg, Args, Ctx, Int, Query, Resolver } from 'type-graphql'
+import { Arg, Args, Ctx, Float, Int, Query, Resolver } from 'type-graphql'
 
 import { buildNextCursor, cursorSortings, getQueryBuilderFromListParams, getRepository, ListParam, ScalarObject } from '@things-factory/shell'
 
@@ -74,7 +74,7 @@ export class TwinJournalQuery {
     if (!instanceId && !spaceId) throw new Error('either instanceId or spaceId is required')
     /* 테넌트 격리 — twinKpi 와 같은 규약. 남의 트윈은 빈 결과가 아니라 명시 실패로 알린다
      * (조용한 빈 목록은 "권한 없음" 과 "데이터 없음" 을 구분할 수 없게 만든다). */
-    if (instanceId && !TwinEngine.owns(domain.id, instanceId)) {
+    if (instanceId && !(await TwinEngine.ownsRegistered(domain.id, instanceId))) {
       throw new Error(`twin instance not found in this tenant: ${instanceId}`)
     }
 
@@ -126,7 +126,7 @@ export class TwinJournalQuery {
    */
   @Query(returns => ScalarObject, {
     description:
-      'Windowed business KPI folded from the event journal, for one space (every running twin in it, folded together — averaging per-twin percentiles would be wrong) or one twin: throughput (completed tasks / orders), lead / work / wait time distributions (p50·p90), and per-resource busy ratio. Distinct from twinMetrics, which reports infrastructure throughput (events per second). When toTime is omitted the window ends at the twin\'s own last recorded event time, not wall clock — a simulated twin lives on its own clock, so asking for \'the last hour\' in real time would always find nothing. The basis used is reported in window.basis. Pass groupBy (resource | taskKind | node | order | area) to break the same window down by that perspective — per-group numbers use the same rules as the totals, so group counts sum to the total, and groups beyond groupLimit are reported as groups.truncated (how many groups) and groups.truncatedTasks (how much work those groups held) rather than silently dropped. Pass compareTo (previous | yesterday) to fold the same-length window shifted back and get comparison.delta (current minus that window); when the comparison window has no records, comparison.measured is false and no delta is produced rather than reporting zero change. Passing groupBy together with compareTo crosses the two: each group carries prevTasks / deltaTasks / deltaWorkP50Ms, groups absent from the comparison window are flagged isNew (no delta, so growth is not implied), and groups that had work before but none now are returned in groups.disappeared so a stopped area is never silently missing from the table. Area breakdown needs board nodes to carry a parent area; when they do not, groups.note says so instead of implying there was no work. When the journal read hits its row cap, eventsCapped is true and every number is a lower bound — narrow the window and ask again rather than reading the smaller figures as a drop in performance. Completions are counted in the window they complete; starts are looked up before the window, and any completion whose start was not found is reported in `unpaired` rather than silently dropped.'
+      'Windowed business KPI folded from the event journal, for one space (every running twin in it, folded together — averaging per-twin percentiles would be wrong) or one twin: throughput (completed tasks / orders), lead / work / wait time distributions (p50·p90), and per-resource busy ratio. Distinct from twinMetrics, which reports infrastructure throughput (events per second). When toTime is omitted the window ends at the twin\'s own last recorded event time, not wall clock — a simulated twin lives on its own clock, so asking for \'the last hour\' in real time would always find nothing. The basis used is reported in window.basis. Pass groupBy (resource | taskKind | location | order | area | shift) to break the same window down by that perspective. The shift axis is **computed, not stored**: the journal records only times, and the shift is derived from each completion\'s time plus the declared site shifts and time zone — so correcting a shift definition re-counts history correctly instead of leaving it frozen under the old boundaries. Sites that declare no shifts report every group as unknown rather than inventing shift names — per-group numbers use the same rules as the totals, so group counts sum to the total, and groups beyond groupLimit are reported as groups.truncated (how many groups) and groups.truncatedTasks (how much work those groups held) rather than silently dropped. Pass compareTo (previous | yesterday) to fold the same-length window shifted back and get comparison.delta (current minus that window); when the comparison window has no records, comparison.measured is false and no delta is produced rather than reporting zero change. Passing groupBy together with compareTo crosses the two: each group carries prevTasks / deltaTasks / deltaWorkP50Ms, groups absent from the comparison window are flagged isNew (no delta, so growth is not implied), and groups that had work before but none now are returned in groups.disappeared so a stopped area is never silently missing from the table. Area breakdown needs board locations to carry a parent area; when they do not, groups.note says so instead of implying there was no work. When the journal read hits its row cap, eventsCapped is true and every number is a lower bound — narrow the window and ask again rather than reading the smaller figures as a drop in performance. When operational targets are set for the space or instance, `targets` carries the verdicts [{metric, actual, target, direction, met, ratio}] — ratio is normalised so that 1 or more is always good, letting throughput and duration metrics be compared on one scale. A metric with no target, or with no measurement in the window, is absent from `targets` rather than reported as a miss, because a period with no work would otherwise read as a perfect score on duration metrics. Completions are counted in the window they complete; starts are looked up before the window, and any completion whose start was not found is reported in `unpaired` rather than silently dropped.'
   })
   async twinKpi(
     @Ctx() context: ResolverContext,
@@ -151,7 +151,7 @@ export class TwinJournalQuery {
   ): Promise<any> {
     /* 테넌트 격리 — 트윈 지정이면 소속을 확인한다. 공간 지정이면 대상 해소가 도메인 목록에서
      * 이뤄지므로(computeTwinKpi) 남의 트윈이 섞이지 않는다. 조용한 빈 결과가 아니라 명시 실패. */
-    if (instanceId && !TwinEngine.owns(context.state.domain.id, instanceId)) {
+    if (instanceId && !(await TwinEngine.ownsRegistered(context.state.domain.id, instanceId))) {
       throw new Error(`twin instance not found in this tenant: ${instanceId}`)
     }
     if (!instanceId && !spaceId) throw new Error('either spaceId or instanceId is required')
@@ -185,6 +185,54 @@ export class TwinJournalQuery {
     return TwinEngine.recover(context.state.domain.id, instanceId, untilRevision ?? undefined, untilTime ?? undefined)
   }
 
+  @Query(returns => ScalarObject, {
+    nullable: true,
+    description:
+      'Steady-state capacity of a twin against a declared demand: per-operation supply vs required across equipment, personnel, physical assets and locations, plus the binding constraint and the daily ceiling. Answers "can this plant meet the target?" without running a simulation. Null when the twin is not running.'
+  })
+  async twinCapacity(
+    @Arg('instanceId', { nullable: true }) instanceId: string,
+    @Arg('spaceId', { nullable: true }) spaceId: string,
+    /** 하루 몇 대를 낼 것인가 — 화면이 보고 있는 목표에서 나온다(선언된 수요). */
+    @Arg('unitsPerDay', type => Float) unitsPerDay: number,
+    /**
+     * 가용 시간을 잴 기준 주의 시작(ISO, 월요일). 공휴일이 없는 평상주여야 한다 —
+     * 공휴일은 연간 가용량을 따로 깎지, 이 공장의 평상시 천장을 정하지 않는다.
+     */
+    @Arg('sampleWeekStart', { nullable: true }) sampleWeekStart: string,
+    @Ctx() context: ResolverContext
+  ): Promise<any> {
+    if (instanceId && !(await TwinEngine.ownsRegistered(context.state.domain.id, instanceId))) {
+      throw new Error(`twin instance not found in this tenant: ${instanceId}`)
+    }
+    if (!instanceId && !spaceId) throw new Error('either spaceId or instanceId is required')
+    if (!(unitsPerDay > 0)) throw new Error('unitsPerDay must be greater than zero')
+
+    /*
+     * 기준 주를 안 주면 **이번 주 월요일**을 쓴다. 그 주에 공휴일이 끼면 천장이 조금 낮게 나오는데,
+     * 그것은 조용한 오류가 아니라 **이번 주의 실제 가용 시간**이라 답으로서 정직하다. 평상시 천장을
+     * 보려는 호출자는 평상주를 지정한다.
+     */
+    const base = sampleWeekStart ? Date.parse(sampleWeekStart) : Date.now()
+    if (Number.isNaN(base)) throw new Error(`sampleWeekStart is not a valid ISO time: ${sampleWeekStart}`)
+    const d = new Date(base)
+    const monday = Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate() - ((d.getUTCDay() + 6) % 7))
+
+    return TwinEngine.capacity(context.state.domain.id, { instanceId, spaceId }, unitsPerDay, monday)
+  }
+
+  @Query(returns => ScalarObject, {
+    description:
+      "Structural revisions a twin has been through, newest last: when each took effect, how many journal events happened under it, and what changed from the previous one (counts by location type and equipment kind). The board itself is not returned — a revision holds the whole plant, but what a person wants is the difference."
+  })
+  async twinStructures(@Arg('instanceId') instanceId: string, @Ctx() context: ResolverContext): Promise<any> {
+    /* 이력 질문이므로 **등록부**에 소유를 묻는다 — 꺼진 트윈의 이력도 읽을 수 있어야 한다. */
+    if (!(await TwinEngine.ownsRegistered(context.state.domain.id, instanceId))) {
+      throw new Error(`twin instance not found in this tenant: ${instanceId}`)
+    }
+    return TwinEngine.structureHistory(context.state.domain.id, instanceId)
+  }
+
   @Query(returns => ScalarObject, {
     description: 'Event time range (min/max ISO) across all co-located twins of a space — the history scrubber time axis.'
   })

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

@@ -43,7 +43,8 @@ export class TwinLifecycleMutation {
     @Arg('board', type => ScalarObject, { nullable: true }) board?: any
   ): Promise<boolean> {
     const domainId = context.state.domain.id
-    if (board) TwinEngine.start(instanceId, domainId, kind ?? 'wms', board as BoardDef)
+    // 시각 기준은 **공간**이 갖는다(테넌트 아님) — 교대의 HH:MM 을 어느 기준으로 읽나.
+    if (board) TwinEngine.start(instanceId, domainId, kind ?? 'wms', await TwinEngine.withSpaceTimeBase(board as BoardDef, domainId))
     else await TwinEngine.startFromRegistry(domainId, instanceId)
     return true
   }
@@ -86,10 +87,10 @@ export class TwinLifecycleMutation {
   }
 
   /**
-   * 도메인 어휘 카탈로그 — 커널(레퍼런스) SSOT 를 그대로 노출. { wms:{label,nodeTypes[]}, yms:…, mes:… }.
+   * 도메인 어휘 카탈로그 — 커널(레퍼런스) SSOT 를 그대로 노출. { wms:{label,locationTypes[]}, yms:…, mes:… }.
    * 프로비저닝 UI 는 이걸 소싱해 노드 타입/시스템을 채운다(앱 내 하드코딩 금지).
    */
-  @Query(returns => ScalarObject, { description: 'Domain vocabulary catalog (per-system location node types) sourced from the twin kernel — SSOT for provisioning UI.' })
+  @Query(returns => ScalarObject, { description: 'Domain vocabulary catalog (per-system location location types) sourced from the twin kernel — SSOT for provisioning UI.' })
   twinDomainCatalog(): any {
     return domainCatalog()
   }

package/server/service/twin-space/twin-space-area.ts

@@ -49,7 +49,7 @@ export class TwinSpaceArea {
   drillTo?: any
 
   @Column({ type: 'simple-json', nullable: true })
-  @Field(type => ScalarObject, { nullable: true, description: 'Twin binding { nodeId?|entityId?|tag? } for live state.' })
+  @Field(type => ScalarObject, { nullable: true, description: 'Twin binding { locationId?|entityId?|tag? } for live state.' })
   binding?: any
 
   @Column({ type: 'simple-json', nullable: true })

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

@@ -27,7 +27,7 @@ export class TwinSpaceResolver {
       const benchInst = insts.find(i => (i as any).purpose === 'bench')
       const bench = !!benchInst
       const copyOf = benchInst?.copyOf
-      out.push({ spaceId: r.spaceId, name: r.name, description: r.description, geo: r.geo, primaryRepresentationId: r.primaryRepresentationId, content: r.content, representationCount, bench, copyOf })
+      out.push({ spaceId: r.spaceId, name: r.name, description: r.description, geo: r.geo, timezone: r.timezone, primaryRepresentationId: r.primaryRepresentationId, content: r.content, representationCount, bench, copyOf })
     }
     return out
   }
@@ -44,10 +44,10 @@ export class TwinSpaceResolver {
       const areas = await getRepository(TwinSpaceArea).find({ where: { domain: { id: domainId }, representation: { id: rep.id } }, order: { createdAt: 'ASC' } })
       representations.push({ id: rep.id, type: rep.type, name: rep.name, seq: rep.seq, isPrimary: rep.isPrimary, config: rep.config, areas: areas.map(a => ({ id: a.id, name: a.name, type: a.type, geometry: a.geometry, drillTo: a.drillTo, binding: a.binding, style: a.style })) })
     }
-    return { spaceId: r.spaceId, name: r.name, description: r.description, geo: r.geo, primaryRepresentationId: r.primaryRepresentationId, content: r.content, representations }
+    return { spaceId: r.spaceId, name: r.name, description: r.description, geo: r.geo, timezone: r.timezone, primaryRepresentationId: r.primaryRepresentationId, content: r.content, representations }
   }
 
-  @Mutation(returns => Boolean, { description: 'Create or update a Space (name/description/geo/primaryRepresentationId).' })
+  @Mutation(returns => Boolean, { description: 'Create or update a Space (name/description/geo/timezone/primaryRepresentationId).' })
   async saveTwinSpace(
     @Arg('spaceId') spaceId: string,
     @Arg('patch', type => ScalarObject) patch: any,

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

@@ -42,6 +42,20 @@ export class TwinSpace {
   @Field(type => ScalarObject, { nullable: true, description: 'Site georeference { lat, lon, rotation, unit } — aligns representations.' })
   geo?: any
 
+  /**
+   * 이 현장의 시각 기준 — IANA 이름(`'America/Tijuana'`).
+   *
+   * **테넌트가 아니라 공간이 갖는다.** 한 테넌트가 Rosarito(태평양)와 한국 공장을 함께 가질 수 있고,
+   * 테넌트 단위(`Domain.timezone`)로 두면 둘 중 하나는 반드시 틀린다. 교대가 "06시" 라고 할 때 그것이
+   * 어느 06시인가는 **물리 현장의 성질**이다.
+   *
+   * 오프셋 숫자가 아니라 이름으로 둔다: 숫자로는 일광절약시간을 표현할 수 없고, 나중에 절대 구간
+   * (표준 `StartDateTime`)으로 옮길 때도 이름이 있어야 계산할 수 있다.
+   */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'IANA time zone of this physical site (e.g. America/Tijuana) — the base for reading shift times. Belongs to the space, not the tenant, because one tenant can run plants in different zones.' })
+  timezone?: string
+
   @Column({ nullable: true })
   @Field({ nullable: true, description: 'Id of the primary representation shown on the home/monitor.' })
   primaryRepresentationId?: string

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

@@ -0,0 +1,3 @@
+import { TwinStructure } from './twin-structure.js'
+
+export const entities = [TwinStructure]

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

@@ -0,0 +1,93 @@
+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'
+import { User } from '@things-factory/auth-base'
+
+/*
+ * TwinStructure — **한 트윈이 거쳐 온 공장 구조들.** 리비전 하나가 그 시절의 공장이다.
+ *
+ * ── 왜 필요한가: 역사를 잃거나 거짓말을 하거나 ──────────────────────────────
+ * 공장은 바뀐다. 도장 부스를 넷 더 놓고, 라인을 하나 접는다. 그런데 지금까지는 구조 서명이 바뀌면
+ * **그 트윈의 저널을 통째로 지우는 것**이 유일한 길이었다. 안 지우면 옛 이벤트를 새 공장에 대고
+ * 접게 되어 이력이 거짓말을 하기 때문이다 — 부스가 둘이던 시절의 사실을 여섯 개짜리 공장에 접으면
+ * 그때 없던 부스에서 일이 있었던 것처럼 보인다.
+ *
+ * 그래서 선택지가 둘뿐이었다: **역사를 잃거나, 거짓말을 하거나.**
+ *
+ * 셋째 길이 이 표다. 이벤트가 `structureRev` 로 자기 구조를 달고 다니고, 재생은 구조가 바뀌는
+ * 지점에서 갈아탄 뒤 이어 접는다(`replaySegments`). 이력은 "그때 그 공장의 사실" 로 계속 읽힌다.
+ *
+ * ── 왜 board 를 통째로 담나 ─────────────────────────────────────────────────
+ * 재생하려면 **그때의 토폴로지 전체**가 필요하다. 차이(diff)만 담으면 리비전 1부터 되짚어 쌓아야
+ * 하고, 그 되짚기 자체가 또 하나의 규칙이 되어 갈라진다. 구조는 이벤트에 비해 드물게 바뀌므로
+ * 스냅샷을 통째로 두는 편이 싸고 정직하다(보드 이력 `BoardHistory` 와 같은 선택).
+ *
+ * ── audit 컬럼을 다 두지 않는 이유 ──────────────────────────────────────────
+ * 리비전은 **한 번 쓰이면 바뀌지 않는다** — 그 시절의 사실이라 고칠 수가 없다. 그래서 updater·
+ * deletedAt 이 없다(TwinEvent 와 같은 규율). 대신 **누가 구조를 바꿨는지**는 남긴다.
+ *
+ * (CLAUDE.md: 모든 @ObjectType/@Field 는 영문 description 필수.)
+ */
+@Entity()
+@Index('ix_twin_structure_0', (e: TwinStructure) => [e.domain, e.instanceId, e.rev], { unique: true })
+@ObjectType({
+  description:
+    'One structural revision of a twin — the plant as it stood for a stretch of its journal. Events carry the revision they were produced under, so history can be replayed against the structure that was actually in force instead of being deleted when the plant changes.'
+})
+export class TwinStructure {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(type => ID, { description: 'Unique identifier of the structure revision record.' })
+  readonly id: string
+
+  @ManyToOne(type => Domain)
+  @Field(type => Domain, { nullable: true, description: 'Owning tenant domain.' })
+  domain?: Domain
+
+  @RelationId((e: TwinStructure) => e.domain)
+  domainId?: string
+
+  @Column()
+  @Field({ description: 'Twin runtime instance this structure belongs to.' })
+  instanceId: string
+
+  /**
+   * 리비전 번호 — 1부터. 이벤트의 `structureRev` 가 이것을 가리킨다.
+   *
+   * 0 을 안 쓰는 이유: 컬럼이 없던 시절의 행은 `structureRev` 가 비어 있고, 그 행들은 **가장 오래된
+   * 리비전**에 속한다. 0 을 유효 번호로 쓰면 "모름" 과 "1번 구조" 가 같은 값이 된다.
+   */
+  @Column({ type: 'int' })
+  @Field(type => Int, { description: 'Revision number, starting at 1. Events reference it via structureRev; absent on rows written before structure revisions existed, which belong to the oldest revision.' })
+  rev: number
+
+  /**
+   * 구조 서명 — 이 리비전이 앞 리비전과 **정말 다른지** 판정한 근거.
+   *
+   * 서명이 같으면 새 리비전을 만들지 않는다. 프로비저닝은 자주 다시 도는데(부팅마다) 그때마다
+   * 리비전이 하나씩 늘면 이력이 뜻 없는 마디로 잘게 쪼개진다.
+   */
+  @Column({ length: 64 })
+  @Field({ description: 'Short hash of the structural signature (locations + equipment). A re-provision with the same signature does not create a new revision — otherwise every reboot would slice the history into meaningless segments.' })
+  signature: string
+
+  @Column({ type: 'simple-json' })
+  @Field(type => ScalarObject, { description: 'The full BoardDef as it stood for this revision. Stored whole rather than as a diff: replay needs the entire topology, and rebuilding it from diffs would be a second rule that can drift.' })
+  board: any
+
+  /** 왜 바뀌었나 — 사람이 남기는 한 줄. 없을 수 있다(자동 프로비저닝은 이유를 모른다). */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Why the structure changed — a human note, absent for automatic provisioning.' })
+  comment?: string
+
+  @ManyToOne(type => User, { nullable: true })
+  @Field(type => User, { nullable: true, description: 'Who changed the structure, when known.' })
+  creator?: User
+
+  @RelationId((e: TwinStructure) => e.creator)
+  creatorId?: string
+
+  @CreateDateColumn()
+  @Field({ nullable: true, description: 'When this revision took effect.' })
+  createdAt?: Date
+}

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

@@ -0,0 +1,5 @@
+import { TwinTarget } from './twin-target.js'
+import { TwinTargetResolver } from './twin-target-resolver.js'
+
+export const entities = [TwinTarget]
+export const resolvers = [TwinTargetResolver]

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

@@ -0,0 +1,124 @@
+import { Arg, Ctx, Directive, Float, Mutation, Query, Resolver } from 'type-graphql'
+
+import { getRepository } from '@things-factory/shell'
+
+import { TwinTarget } from './twin-target.js'
+import { TWIN_METRIC, isTwinMetric } from '../../engine/kpi-target.js'
+
+/*
+ * 운영 목표 조회·편집 — **현장 관리자가 트윈 화면에서** 고친다(사용자 결정 2026-08-02).
+ *
+ * 경영 KPI 관리메뉴가 아니라 여기인 이유: 목표가 숫자 옆에 있어야 맥락이 살고, 운영 임계는 자주
+ * 조정된다. 조직 단위 기간 평가는 `@things-factory/kpi` 의 일이고 이쪽으로 베껴 오지 않는다.
+ */
+@Resolver()
+export class TwinTargetResolver {
+  @Directive('@privilege(category: "twin", privilege: "query")')
+  @Query(returns => [String], {
+    description:
+      'The metric ids a twin target may refer to. Fixed in one place so a target and the fact it judges can never drift into two names.'
+  })
+  async twinTargetMetrics(): Promise<string[]> {
+    return Object.keys(TWIN_METRIC)
+  }
+
+  @Directive('@privilege(category: "twin", privilege: "query")')
+  @Query(returns => [TwinTarget], {
+    description:
+      'Operational targets in scope — site-wide targets for the space plus targets bound to the given instance. Callers judge with the narrower one when both exist.'
+  })
+  async twinTargets(
+    @Ctx() context: ResolverContext,
+    @Arg('spaceId', { nullable: true }) spaceId?: string,
+    @Arg('instanceId', { nullable: true }) instanceId?: string
+  ): Promise<TwinTarget[]> {
+    const domainId = context.state.domain.id
+    const rows = await getRepository(TwinTarget).find({ where: { domain: { id: domainId } } })
+    return rows.filter(r => (spaceId && r.spaceId === spaceId) || (instanceId && r.instanceId === instanceId))
+  }
+
+  @Directive('@privilege(category: "twin", privilege: "mutation")')
+  @Mutation(returns => Boolean, {
+    description:
+      'Create or update one operational target. The metric must be one of twinTargetMetrics — an unknown name is rejected rather than stored, because a target nobody can evaluate reads as "no target" and hides the gap.'
+  })
+  async saveTwinTarget(
+    @Arg('metric') metric: string,
+    @Arg('target', type => Float) target: number,
+    @Ctx() context: ResolverContext,
+    @Arg('spaceId', { nullable: true }) spaceId?: string,
+    @Arg('instanceId', { nullable: true }) instanceId?: string,
+    @Arg('axis', { nullable: true }) axis?: string,
+    @Arg('axisKey', { nullable: true }) axisKey?: string
+  ): Promise<boolean> {
+    if (!isTwinMetric(metric)) throw new Error(`unknown twin metric "${metric}" — see twinTargetMetrics`)
+    if (!Number.isFinite(target)) throw new Error('target must be a finite number')
+    if (!spaceId && !instanceId) throw new Error('a target must be scoped to a space or an instance')
+    /* 축만 있고 값이 없으면 **어디에 거는 목표인지 알 수 없다** — 조용히 전체 목표로 만들지 않는다
+       (그러면 사용자는 구역 목표를 걸었다고 믿는데 전체가 바뀐다). */
+    if (axis && !axisKey) throw new Error('axisKey is required when axis is given')
+    if (!axis && axisKey) throw new Error('axis is required when axisKey is given')
+    const domainId = context.state.domain.id
+    const repo = getRepository(TwinTarget)
+    const existing = await repo.findOne({
+      where: { domain: { id: domainId }, spaceId: spaceId ?? null, instanceId: instanceId ?? null, metric, axis: axis ?? null, axisKey: axisKey ?? null } as any
+    })
+    await repo.save(
+      repo.create({
+        ...(existing ?? {}),
+        domain: { id: domainId } as any,
+        spaceId: spaceId ?? null as any,
+        instanceId: instanceId ?? null as any,
+        axis: axis ?? null as any,
+        axisKey: axisKey ?? null as any,
+        metric,
+        target,
+        ...(existing ? { updater: context.state.user } : { creator: context.state.user, updater: context.state.user })
+      })
+    )
+    return true
+  }
+
+  @Directive('@privilege(category: "twin", privilege: "mutation")')
+  @Mutation(returns => Boolean, { description: 'Remove an operational target. Removing a target removes the judgement, not the fact — the metric keeps being reported without a verdict.' })
+  async deleteTwinTarget(
+    @Arg('metric') metric: string,
+    @Ctx() context: ResolverContext,
+    @Arg('spaceId', { nullable: true }) spaceId?: string,
+    @Arg('instanceId', { nullable: true }) instanceId?: string,
+    @Arg('axis', { nullable: true }) axis?: string,
+    @Arg('axisKey', { nullable: true }) axisKey?: string
+  ): Promise<boolean> {
+    const domainId = context.state.domain.id
+    const repo = getRepository(TwinTarget)
+
+    /*
+     * **찾아서 그 행만 지운다.** 예전에는 조건 객체를 `delete()` 에 그대로 넘겼는데 **아무 행도
+     * 안 지워지면서 `true` 를 돌려줬다.** 사용자는 목표를 지웠다고 믿고 화면을 떠나는데 판정은 그대로
+     * 남는다(실화면에서 그렇게 당했다).
+     *
+     * 무엇이 조건을 깨뜨렸는지는 단정하지 않는다 — 이 조건에는 `domain` 관계 객체와 `null` 값들이
+     * 함께 들어 있었고(`instanceId`·`axis`·`axisKey`), 둘 다 `delete()` 의 조건 해석에서 흔한 함정이다.
+     * 같은 관계-객체 패턴을 쓰는 `resetJournal` 은 실제로 잘 지우므로 관계 객체 하나만으로 설명되지
+     * 않는다. `null` 조건이 `IS NULL` 이 아니라 `= NULL` 로 나갔을 가능성이 크다.
+     *
+     * 그래서 조건을 고쳐 맞추는 대신 **행을 찾아 id 로 지운다**: 저장 경로와 **같은 조회 규칙**을
+     * 쓰므로 규칙이 갈라지지 않고(`findOne` 은 `null` 을 제대로 다룬다), 지우는 대상이 정확히 한
+     * 행이라 넓게 지울 위험도 없다.
+     */
+    const row = await repo.findOne({
+      where: {
+        domain: { id: domainId },
+        spaceId: spaceId ?? null,
+        instanceId: instanceId ?? null,
+        axis: axis ?? null,
+        axisKey: axisKey ?? null,
+        metric
+      } as any
+    })
+    /* 지울 것이 없으면 **없었다고 답한다.** 지우지 않고 true 를 주면 위와 같은 거짓말이 된다. */
+    if (!row) return false
+    await repo.delete(row.id)
+    return true
+  }
+}

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

@@ -0,0 +1,97 @@
+import { CreateDateColumn, Entity, Index, Column, RelationId, ManyToOne, PrimaryGeneratedColumn, UpdateDateColumn } from 'typeorm'
+import { ObjectType, Field, ID, Float } from 'type-graphql'
+
+import { Domain } from '@things-factory/shell'
+import { User } from '@things-factory/auth-base'
+
+/*
+ * TwinTarget — **운영 목표.** "이 구간의 처리량이 목표에 닿았나" 를 판단하는 기준선.
+ *
+ * ── 왜 트윈이 갖나 (사용자 결정 2026-08-02) ─────────────────────────────────
+ * `@things-factory/kpi` 와 **경계를 나눈다**:
+ *   트윈(여기)      이 구간·이 교대·이 공간의 **즉시 판단**. 현장 관리자가 트윈 화면에서 고친다.
+ *                   값은 저널 폴드에서 그때그때 계산된다(저장된 값을 읽지 않는다).
+ *   packages/kpi    **기간 평가**(조직·분기·점수·가중치·알림). 값이 저장돼 있어야 도는 체계다.
+ *
+ * 지키는 규칙 하나: **트윈은 경영 목표를 복제하지 않는다.** 조직 단위 평가가 필요하면 트윈의 사실을
+ * 내보내 그쪽이 소비하고, 그쪽 목표를 여기로 베껴 오지 않는다 — 베끼는 순간 두 개의 진실이 된다.
+ *
+ * ── 범위 (scope) ───────────────────────────────────────────────────────────
+ * `spaceId` 로 현장 전체에, `instanceId` 로 트윈 하나에 건다. 둘 다 있으면 **인스턴스가 이긴다**
+ * (좁은 선언이 넓은 선언을 덮는다 — 예외를 표현할 수 있어야 한다).
+ *
+ * 관점 축별 목표(구역마다 다른 목표)는 **아직 아니다** — 축 교차는 목표가 화면에서 쓰이기 시작한 뒤의
+ * 일이고, 처음부터 넣으면 쓰이지 않는 구조가 먼저 굳는다(performance.md §5.4-5).
+ *
+ * (CLAUDE.md: 모든 @ObjectType/@Field 영문 description 필수.)
+ */
+@Entity()
+@Index('ix_twin_target_0', (e: TwinTarget) => [e.domain, e.spaceId, e.instanceId, e.metric, e.axis, e.axisKey], { unique: true })
+@ObjectType({
+  description:
+    'An operational performance target for a twin metric — the line that turns a measured number into a judgement. Scoped to a space or to a single instance (instance wins over space, so an exception can be expressed). Distinct from @things-factory/kpi targets, which evaluate organizations over periods; twin targets are for immediate, on-site judgement and are never copied from the management KPI system.'
+})
+export class TwinTarget {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(type => ID, { description: 'Unique identifier of the target record.' })
+  readonly id: string
+
+  @ManyToOne(type => Domain)
+  @Field(type => Domain, { nullable: true, description: 'Owning tenant domain.' })
+  domain?: Domain
+
+  @RelationId((e: TwinTarget) => e.domain)
+  domainId?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Space this target applies to (site-wide). Empty when the target is bound to a single instance.' })
+  spaceId?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Instance this target applies to. When both space and instance match, the instance target wins so an exception can be expressed.' })
+  instanceId?: string
+
+  /**
+   * 관점 축과 그 값 — **"이 구역만", "이 교대만" 목표가 다르다.**
+   *
+   * 둘 다 비어 있으면 **전체 목표**다(창 전체의 집계를 판정한다). 축 목표는 전체 목표를 덮지 않는다 —
+   * 다른 질문이기 때문이다: "현장 전체가 100건" 과 "용접 구역이 30건" 은 동시에 참일 수 있다.
+   */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Perspective axis this target applies to (area, shift, resource, taskKind, location, order). Empty means the target judges the window total. An axis target does not override the total — "the site does 100" and "the weld area does 30" are both true at once.' })
+  axis?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'The value on that axis (an area id, a shift name…). Required when axis is set.' })
+  axisKey?: string
+
+  @Column()
+  @Field({ description: 'Metric id from the twin metric vocabulary (throughput.tasks, workTime.p50Ms, …). Names are fixed in one place so target and fact never drift into two dialects.' })
+  metric: string
+
+  @Column({ type: 'float' })
+  @Field(type => Float, { description: 'The target value, in the metric\'s own unit (count, milliseconds, ratio). Whether higher or lower is better is a property of the metric, not of this record — so a target can never be declared in the wrong direction.' })
+  target: number
+
+  @ManyToOne(type => User, { nullable: true })
+  @Field(type => User, { nullable: true, description: 'User who created this target.' })
+  creator?: User
+
+  @RelationId((e: TwinTarget) => e.creator)
+  creatorId?: string
+
+  @ManyToOne(type => User, { nullable: true })
+  @Field(type => User, { nullable: true, description: 'User who last updated this target.' })
+  updater?: User
+
+  @RelationId((e: TwinTarget) => e.updater)
+  updaterId?: string
+
+  @CreateDateColumn()
+  @Field({ nullable: true, description: 'Timestamp when the target was created.' })
+  createdAt?: Date
+
+  @UpdateDateColumn()
+  @Field({ nullable: true, description: 'Timestamp when the target was last updated.' })
+  updatedAt?: Date
+}