@things-factory/headless-twin 10.1.37 → 10.1.39

package/server/engine/twin-engine.ts

@@ -24,6 +24,7 @@ import { itemResolverFor } from '../service/twin-subject/item-resolver.js'
 import { planLiveContinuity, planWarmStart, unwrapState } from './warm-start.js'
 import { applyDeclarationLayers } from './local-declarations.js'
 import { isOfDomain, parseRuntimeKey, runtimeKey } from './runtime-key.js'
+import { TWIN_STATE_TOPIC, twinStatePayload } from './twin-state-channel.js'
 import { routeCommand } from './command-routing.js'
 import { TwinInstance } from '../service/twin-instance/twin-instance.js'
 /* 자극의 집은 원본이다(ADR-0029) — 그 행을 읽고 쓴다. */
@@ -1704,8 +1705,8 @@ export class TwinEngine {
     /* State 채널: runtime.subscribe(snapshot→delta→clock) → pubsub 브로드캐스팅(구독 리졸버가 instanceId 필터). */
     const sub = runtime.subscribe((msg: SubscriptionMessage) => {
       this.publishGuarded(
-        'twin-state',
-        { twinState: { instanceId: id, kind: msg.kind, revision: (msg as any).revision, payload: msg } },
+        TWIN_STATE_TOPIC,
+        twinStatePayload(domainId, { instanceId: id, kind: msg.kind, revision: (msg as any).revision, payload: msg }),
         `twin-state:${id}`
       )
       /* 영속 + 라이브 바인딩 브리지: delta 를 저널 버퍼에 담고 + 엔티티별 data(tag:) publish → 보드 컴포넌트 라이브. */
@@ -2353,8 +2354,8 @@ export class TwinEngine {
       //    scheduleRefresh(250ms 디바운스)→pollLive 로 되물어봄. 스냅샷(O(state))은 보는 사람이 물을 때만 1회 계산.
       //    (여기서 payload 로 스냅샷을 실으면 아무도 안 읽는데 tick 마다 통째로 떠서 순수 낭비 — 신호만 보낸다.)
       this.publishGuarded(
-        'twin-state',
-        { twinState: { instanceId: inst.id, kind: 'delta', revision: inst.revision ?? 0 } },
+        TWIN_STATE_TOPIC,
+        twinStatePayload(inst.domainId, { instanceId: inst.id, kind: 'delta', revision: inst.revision ?? 0 }),
         `twin-state:${inst.id}`
       )
     }
@@ -3641,7 +3642,7 @@ export class TwinEngine {
    * 그래도 이 가드를 남기는 이유는 둘이다. `publish` 가 직접 던지는 경우(직렬화 실패 등)를 잡고,
    * 못 보낸 태그의 시그니처를 되돌린다 — 남겨 두면 그 태그가 오류 없이 영원히 낡은 값을 보인다.
    */
-  private static publishGuarded(channel: 'data' | 'twin-state', payload: any, what: string): boolean {
+  private static publishGuarded(channel: 'data' | typeof TWIN_STATE_TOPIC, payload: any, what: string): boolean {
     try {
       pubsub.publish(channel as any, payload)
       return true

package/server/engine/twin-state-channel.ts

@@ -0,0 +1,39 @@
+/*
+ * The `twin-state` channel — **a message says whose twin it is, and the filter asks.** Pure.
+ *
+ * ── What went wrong (2026-09-24) ─────────────────────────────────────────────
+ * A twin is `(domain, instanceId)` (`runtime-key.ts`), and the same instanceId in two tenants is the
+ * expected case — reference source names such as `sap-ewm-1710` are vocabulary tenants share. The
+ * channel had not caught up: publishers sent `{ twinState: { instanceId, … } }` with no domain, and the
+ * subscription filtered on instanceId alone. Ownership was checked once, when subscribing. So a tenant
+ * watching its own `sap-ewm-1710` also received the other tenant's deltas, and the snapshot sent to a
+ * new subscriber went to every subscriber of that id in every tenant.
+ *
+ * The rule is shell's `data` channel's (the message carries its domain, the filter compares it with the
+ * key), compared by id because the twin's key already is. Every sender builds its payload here, and
+ * `twin-state-channel.test.ts` fails if a sender builds one anywhere else.
+ */
+
+export const TWIN_STATE_TOPIC = 'twin-state'
+
+export interface TwinStateMessageShape {
+  instanceId: string
+  kind: string
+  revision?: number
+  payload?: unknown
+}
+
+export interface TwinStatePayload {
+  domainId: string
+  twinState: TwinStateMessageShape
+}
+
+export function twinStatePayload(domainId: string, twinState: TwinStateMessageShape): TwinStatePayload {
+  if (!domainId) throw new Error('twinStatePayload: domainId is required — a twin state message always belongs to a tenant')
+  return { domainId, twinState }
+}
+
+/** Passes only this tenant's messages about this twin. */
+export function twinStateFilter(domainId: string, instanceId: string) {
+  return (p: TwinStatePayload | undefined): boolean => !!p && p.domainId === domainId && p.twinState?.instanceId === instanceId
+}

package/server/service/reference/reference-progress-channel.ts

@@ -0,0 +1,26 @@
+/*
+ * The `twin-reference-progress` channel — **progress says whose import it is, and the filter asks.** Pure.
+ *
+ * The subscription filtered on `source` alone and checked only that the caller had some domain, so
+ * anyone who knew a source name — and names like `sap-ewm-1710` are shared between tenants — received
+ * another tenant's import progress, including its failure text. Same fix and same rule as
+ * `engine/twin-state-channel.ts`.
+ */
+
+export const REFERENCE_PROGRESS_TOPIC = 'twin-reference-progress'
+
+export interface ReferenceProgressPayload<M extends { source: string } = { source: string }> {
+  domainId: string
+  twinReferenceProgress: M
+}
+
+export function referenceProgressPayload<M extends { source: string }>(domainId: string, message: M): ReferenceProgressPayload<M> {
+  if (!domainId) throw new Error('referenceProgressPayload: domainId is required — import progress always belongs to a tenant')
+  return { domainId, twinReferenceProgress: message }
+}
+
+/** Passes only this tenant's progress for this source. */
+export function referenceProgressFilter(domainId: string, source: string) {
+  return (p: ReferenceProgressPayload | undefined): boolean =>
+    !!p && p.domainId === domainId && p.twinReferenceProgress?.source === source
+}

package/server/service/reference/reference-progress-subscription.ts

@@ -8,10 +8,12 @@
  * 낱말이 표준이므로 화면은 **단계마다 번역 하나**만 두면 모든 커넥터를 보여 준다.
  */
 import { Arg, Field, Int, ObjectType, Resolver, Root, Subscription } from 'type-graphql'
-import { pubsub } from '@things-factory/shell'
+import { assertDomainSubscribeAllowed, getRepository, pubsub } from '@things-factory/shell'
 import { filter, pipe } from 'graphql-yoga'
 
 import { REFERENCE_STEPS } from './reference-progress.js'
+import { REFERENCE_PROGRESS_TOPIC, referenceProgressFilter, type ReferenceProgressPayload } from './reference-progress-channel.js'
+import { TwinReference } from './twin-reference.js'
 
 @ObjectType({ description: 'One step of progress while a reference is being imported into twins.' })
 export class TwinReferenceProgressMessage {
@@ -52,20 +54,23 @@ export class TwinReferenceProgressMessage {
 @Resolver()
 export class TwinReferenceProgressSubscription {
   @Subscription(returns => TwinReferenceProgressMessage, {
-    subscribe: ({ args, context }) => {
+    /*
+     * Tenancy is asked twice (2026-09-24): the source must be one of the caller's references, and every
+     * message must be the caller's domain's. It used to filter on `source` alone after checking only that
+     * the caller had a domain — and source names are shared between tenants.
+     */
+    subscribe: async ({ args, context }) => {
       const { source } = args
-      const domainId = (context as any)?.state?.domain?.id
-      /* 테넌트 격리 — 도메인이 없으면 빈 구독이다(다른 테넌트의 진행을 흘리지 않는다). */
-      if (!domainId) return pipe(pubsub.subscribe('twin-reference-progress'), filter(() => false))
-      return pipe(
-        pubsub.subscribe('twin-reference-progress'),
-        filter((p: { twinReferenceProgress: TwinReferenceProgressMessage }) => p.twinReferenceProgress.source === source)
-      )
+      const { domain, user } = (context as any)?.state ?? {}
+      await assertDomainSubscribeAllowed(domain, user, (d, u) => process.superUserGranted(d, u))
+      const owned = await getRepository(TwinReference).findOne({ where: { domain: { id: domain.id }, source } })
+      if (!owned) throw new Error(`reference not found in this tenant: ${source}`)
+      return pipe(pubsub.subscribe(REFERENCE_PROGRESS_TOPIC), filter(referenceProgressFilter(domain.id, source)))
     },
     description: 'Progress while importing a reference — standard step names, so one translation per step covers every connector.'
   })
   twinReferenceProgress(
-    @Root() payload: { twinReferenceProgress: TwinReferenceProgressMessage },
+    @Root() payload: ReferenceProgressPayload<TwinReferenceProgressMessage>,
     @Arg('source') source: string
   ): TwinReferenceProgressMessage {
     return payload.twinReferenceProgress

package/server/service/reference/reference-resolver.ts

@@ -1,5 +1,6 @@
 import { pubsub } from '@things-factory/shell'
 import { HOST_STEPS, type ReferenceProgress } from './reference-progress.js'
+import { REFERENCE_PROGRESS_TOPIC, referenceProgressPayload } from './reference-progress-channel.js'
 import { assessMaster } from './reference-assessment.js'
 import { Arg, Ctx, Int, Mutation, Query, Resolver, Directive } from 'type-graphql'
 
@@ -295,9 +296,10 @@ export class TwinReferenceResolver {
       if (!progressSource) return
       lastDone = p.done
       lastStep = p.step
-      pubsub.publish('twin-reference-progress', {
-        twinReferenceProgress: { ...p, siteId, siteIndex: 0, siteCount: 1, total: p.total ?? stepTotal, source: progressSource }
-      })
+      pubsub.publish(
+        REFERENCE_PROGRESS_TOPIC,
+        referenceProgressPayload(domainId, { ...p, siteId, siteIndex: 0, siteCount: 1, total: p.total ?? stepTotal, source: progressSource })
+      )
     }
 
     try {
@@ -835,9 +837,7 @@ export class TwinReferenceResolver {
       const declared = adapter.masterSteps?.length
       const stepTotal = declared === undefined ? undefined : declared + HOST_STEPS.length
       const emit = (p: Omit<ReferenceProgress, 'siteCount'>) =>
-        pubsub.publish('twin-reference-progress', {
-          twinReferenceProgress: { ...p, siteCount: sites.length, total: p.total ?? stepTotal, source }
-        })
+        pubsub.publish(REFERENCE_PROGRESS_TOPIC, referenceProgressPayload(domainId, { ...p, siteCount: sites.length, total: p.total ?? stepTotal, source }))
 
       /*
        * **읽은 뒤의 총평을 사이트마다 남긴다** (2026-08-22).

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

@@ -99,19 +99,27 @@ export function computeSpc(errors: number[]): any {
   return { cl, ucl, lcl, sigma, n, ooc, instability, stable: !instability, biased, biasSign: cl >= 0 ? 'under' : 'over', trackingSignal }
 }
 
-/** 집계 지표 — 정확도(1−WMAPE)·편향(MPE)·예측구간 적중·FVA(예측 가치). */
+/**
+ * 집계 지표 — 정확도(1−WMAPE)·편향(MPE)·예측구간 적중·FVA(예측 가치).
+ *
+ * A percentage whose denominator is zero is **not measured**, and says so with `null` (2026-09-24).
+ * When every actual in the window is 0 — the line stood still, or the metric was not observed — WMAPE
+ * is undefined. It used to become 0, so the card read "100% accurate" beside "0 of 6 in band, mean
+ * error −20". Likewise `fvaPct` when the naive error is 0: 0 read as "the forecast adds nothing".
+ * The absolute measures (mean error, in-band count, fva) are real in that window and stay. The two
+ * neighbours below already refuse on thin evidence (`computeSpc` · `learnedCalibration`).
+ */
 export function gapMetrics(pts: GapPoint[]): any {
   const sumAbsErr = pts.reduce((s, x) => s + Math.abs(x.error), 0)
   const sumActual = pts.reduce((s, x) => s + Math.abs(x.actual), 0)
-  const wmape = sumActual ? sumAbsErr / sumActual : 0
-  const accuracy = Math.max(0, Math.round((1 - wmape) * 100))
+  const accuracy = sumActual > 0 ? Math.max(0, Math.round((1 - sumAbsErr / sumActual) * 100)) : null
   const mpe = pts.length ? pts.reduce((s, x) => s + x.error, 0) / pts.length : 0
   const coverage = pts.length ? pts.filter(x => x.inBand).length / pts.length : 0
   // 예측 가치(FVA) — "현재값 그대로"(naive) 대비 오차 감소. fva=감소 총량, fvaPct=naive 오차를 몇 % 줄였나(가치의 크기).
   const sumNaive = pts.reduce((s, x) => s + x.naiveAbsError, 0)
   const sumModel = pts.reduce((s, x) => s + x.modelAbsError, 0)
   const fva = sumNaive - sumModel
-  const fvaPct = sumNaive > 0 ? Math.round((1 - sumModel / sumNaive) * 100) : 0
+  const fvaPct = sumNaive > 0 ? Math.round((1 - sumModel / sumNaive) * 100) : null
   return { accuracy, mpe, coverage, inBandCount: pts.filter(x => x.inBand).length, total: pts.length, fva, fvaPct }
 }
 
@@ -123,8 +131,9 @@ export function learnedCalibration(pts: GapPoint[], metrics: any): any {
   const corrected = errs.map(e => e - biasShift) // 편향 제거 후 잔차
   const absC = corrected.map(Math.abs).sort((a, b) => a - b)
   const halfWidth = absC[Math.floor(absC.length * 0.8)] ?? (absC[absC.length - 1] || 1) // 80% 커버리지 밴드
-  const sumActual = pts.reduce((s, p) => s + Math.abs(p.actual), 0) || 1
-  const accAfter = Math.max(0, Math.round((1 - corrected.reduce((s, e) => s + Math.abs(e), 0) / sumActual) * 100))
+  /* The bias is learnable with every actual at 0; the accuracy before and after is not (see gapMetrics). */
+  const sumActual = pts.reduce((s, p) => s + Math.abs(p.actual), 0)
+  const accAfter = sumActual > 0 ? Math.max(0, Math.round((1 - corrected.reduce((s, e) => s + Math.abs(e), 0) / sumActual) * 100)) : null
   const covAfter = corrected.filter(e => Math.abs(e) <= halfWidth).length
   return { biasShift: Math.round(biasShift), halfWidth: Math.round(halfWidth), accBefore: metrics.accuracy, accAfter, covBefore: metrics.inBandCount, covAfter, n: pts.length }
 }

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

@@ -72,7 +72,7 @@ function metricFn(metric?: string): MetricFn | null {
    데모 트윈은 재부팅 시 저널 리셋이라 세션 스코프로 충분 — DB 영속(TwinForecastScore)은 후속. */
 const CALIBRATION = new Map<
   string,
-  { biasShift: number; halfWidth: number; at: string; samples: number; accBefore: number; accAfter: number; basis?: ModelBasis }
+  { biasShift: number; halfWidth: number; at: string; samples: number; accBefore: number | null; accAfter: number | null; basis?: ModelBasis }
 >()
 const calKey = (d: string, i: string, m: string, h: number) => `${d}:${i}:${m}:${h}`
 

package/server/service/twin-model/twin-model-item-query.ts

@@ -440,7 +440,12 @@ export class TwinModelItemQuery {
           links: { out: [], incoming: [] }, properties: propertiesOf(axis).map((pr: any) => ({ key: pr.key, label: pr.label, kind: pr.kind, uom: pr.uom ?? null, observedBy: pr.observedBy ?? null })),
           /* 어떤 속성이 **효과가 있나** — 등록부가 말한다(§property-effects). 없는 것은 표시만 된다. */
           propertyEffects: propertyEffectsOf(axis),
-          names: {}, provenance: { basis: 'state' }
+          /*
+           * 출처는 이 답의 `basis` 와 같은 규칙이다(아래 읽은 갈래도 같다). 여기를 `state` 로 박아 두어서, 커널이 멈춰
+           * 저널로 되세우려던 답이 「지금 상태에서 읽었다」고 말했다(ADR-0075 결정 3 · 결함 넘김 2026-09-24).
+           * 아무것도 못 읽었다는 사실은 `observedAbsence` 가 말한다 — 출처를 비우지 않는다(`READ_BASIS` 주석).
+           */
+          names: {}, provenance: { basis: liveItem ? 'state' : 'journal' }
         }
       }
       const names = namesFor([{ id: itemId, fields: found }], nameIndex(inst.model ?? {}))

package/server/service/twin-state/twin-state-subscription.ts

@@ -1,9 +1,10 @@
 import { filter, pipe } from 'graphql-yoga'
 import { Arg, Field, Int, ObjectType, Resolver, Root, Subscription } from 'type-graphql'
 
-import { pubsub, ScalarObject } from '@things-factory/shell'
+import { assertDomainSubscribeAllowed, pubsub, ScalarObject } from '@things-factory/shell'
 
 import { TwinEngine } from '../../engine/index.js'
+import { TWIN_STATE_TOPIC, twinStateFilter, twinStatePayload, type TwinStatePayload } from '../../engine/twin-state-channel.js'
 
 /* State 채널 메시지 — snapshot | delta | clock 멀티플렉싱(커널 SubscriptionMessage 대응). */
 @ObjectType({ description: 'Twin State channel message multiplexing snapshot | delta | clock.' })
@@ -23,37 +24,39 @@ export class TwinStateMessage {
 
 /*
  * 트윈 State 구독 — state-register/data-resolver 패턴 미러.
- * 구독 즉시 현재 snapshot 발행(process.nextTick) 후 delta/clock 스트림. instanceId 로 필터.
+ * 구독 즉시 현재 snapshot 발행(process.nextTick) 후 delta/clock 스트림.
+ *
+ * The tenant is asked while streaming, not only at subscribe time (2026-09-24). Ownership used to be
+ * checked once and the stream filtered on instanceId alone; the same id in two tenants is the normal
+ * case (`runtime-key.ts`), so other tenants' deltas came through, and the snapshot sent to a new
+ * subscriber reached every tenant subscribed to that id. Messages now carry their domain and the filter
+ * compares it (`engine/twin-state-channel.ts`). A twin the caller does not own is refused rather than
+ * given an empty stream — an empty stream cannot tell "nothing changed" from "you may not see this"
+ * (shell's `data` throws too).
  */
 @Resolver()
 export class TwinStateSubscription {
   @Subscription(returns => TwinStateMessage, {
-    subscribe: ({ args, context }) => {
+    subscribe: async ({ args, context }) => {
       const { instanceId } = args
-      const domainId = (context as any)?.state?.domain?.id
+      const { domain, user } = (context as any)?.state ?? {}
+      await assertDomainSubscribeAllowed(domain, user, (d, u) => process.superUserGranted(d, u))
 
-      /* 테넌트 격리 — 이 도메인 소유 인스턴스가 아니면 스냅샷도 스트림도 흘리지 않는다(빈 구독). */
-      if (!domainId || !TwinEngine.owns(domainId, instanceId)) {
-        return pipe(pubsub.subscribe('twin-state'), filter(() => false))
-      }
+      /* One refusal for both cases, so the answer does not reveal whether another tenant has such a twin. */
+      if (!TwinEngine.owns(domain.id, instanceId)) throw new Error(`twin instance not running in this tenant: ${instanceId}`)
 
-      /* 구독 순간 현재 상태를 먼저 발행(late 구독자도 snapshot→delta 순서 보장). */
+      /* Current state first (a late subscriber still sees snapshot → delta). It reaches this tenant's subscribers only. */
       process.nextTick(() => {
-        const snap = TwinEngine.snapshot(domainId, instanceId)
+        const snap = TwinEngine.snapshot(domain.id, instanceId)
         if (snap) {
-          pubsub.publish('twin-state', {
-            twinState: { instanceId, kind: 'snapshot', revision: snap.revision, payload: snap }
-          })
+          pubsub.publish(TWIN_STATE_TOPIC, twinStatePayload(domain.id, { instanceId, kind: 'snapshot', revision: snap.revision, payload: snap }))
         }
       })
 
-      return pipe(
-        pubsub.subscribe('twin-state'),
-        filter((payload: { twinState: TwinStateMessage }) => payload.twinState.instanceId === instanceId)
-      )
+      return pipe(pubsub.subscribe(TWIN_STATE_TOPIC), filter(twinStateFilter(domain.id, instanceId)))
     }
   })
-  twinState(@Root() payload: { twinState: TwinStateMessage }, @Arg('instanceId') instanceId: string): TwinStateMessage {
-    return payload.twinState
+  twinState(@Root() payload: TwinStatePayload, @Arg('instanceId') instanceId: string): TwinStateMessage {
+    return payload.twinState as TwinStateMessage
   }
 }

package/test/boot-resume.test.ts

@@ -177,7 +177,10 @@ test('flush 가 시뮬도 본다 — 브로드캐스팅과 저널은 둘 다, st
   assert.ok(liveOnlyAt >= 0, 'state 채널을 라이브로 가르는 자리가 없다')
   assert.ok(flushAt < liveOnlyAt, '저널 flush 가 라이브 전용 구간 뒤로 밀리면 시뮬의 사실이 쌓인 채 남는다')
   /* state 채널은 시뮬이 자기 콜백에서 이미 보낸다 — 여기서 또 보내면 같은 신호가 두 번 간다. */
-  assert.ok(body.indexOf("twinState: { instanceId: inst.id") > liveOnlyAt, 'state 채널 브로드캐스팅은 라이브 구간에 있어야 한다')
+  /* The payload is built by the channel since 2026-09-24 (it carries the domain); look for that call. */
+  const stateSendAt = body.indexOf('twinStatePayload(inst.domainId, { instanceId: inst.id')
+  assert.ok(stateSendAt >= 0, 'state 채널로 보내는 자리가 없다')
+  assert.ok(stateSendAt > liveOnlyAt, 'state 채널 브로드캐스팅은 라이브 구간에 있어야 한다')
 })
 
 test('구독자 하나가 호스트를 죽이지 못한다 — 그리고 못 보낸 것을 보낸 것으로 적지 않는다', () => {

package/test/gap-analytics.test.ts

@@ -5,7 +5,7 @@
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { computeSpc, gapMetrics, learnedCalibration, aggregatePoints } from '../dist-server/service/twin-forecast/gap-analytics.js'
+import { computeSpc, gapMetrics, learnedCalibration, aggregatePoints } from '../server/service/twin-forecast/gap-analytics.ts'
 
 const pt = (error: number, actual = 100, inBand = true) => ({
   t: 0, p50: actual - error, min: 0, max: 0, actual, error, inBand,
@@ -52,6 +52,30 @@ test('learnedCalibration — biasShift=평균오차, 편향 제거로 정확도
   assert.equal(learn.accAfter, 100, '일정 편향을 완전 제거 → 잔차 0 → 100%')
 })
 
+/*
+ * ★ Nothing to divide by is not 100% (2026-09-24). With every actual at 0 the card read
+ * "100% accurate" beside "0 of 6 in band, mean error −20" — the installed build gave exactly that.
+ */
+test('gapMetrics — a window with no actual says the percentages are not measured, and keeps what is', () => {
+  const idle = Array.from({ length: 6 }, () => ({ t: 0, p50: 20, min: 15, max: 25, actual: 0, error: -20, inBand: false, naiveAbsError: 0, modelAbsError: 20 }))
+  const m = gapMetrics(idle)
+  assert.equal(m.accuracy, null, 'WMAPE has no denominator — not 100%')
+  assert.equal(m.fvaPct, null, 'the naive error is 0 — "adds nothing" would be invented')
+  /* Measured in that window, so they stay. */
+  assert.equal(m.mpe, -20)
+  assert.equal(m.inBandCount, 0)
+  assert.equal(m.total, 6)
+  assert.equal(m.fva, -120)
+})
+
+test('learnedCalibration — the bias is still learned with no actual; only the percentages are not', () => {
+  const idle = Array.from({ length: 4 }, () => pt(-20, 0, false))
+  const learn = learnedCalibration(idle, gapMetrics(idle))
+  assert.equal(learn.biasShift, -20, 'forecasting 20 over a standing line is a bias worth removing')
+  assert.equal(learn.accBefore, null)
+  assert.equal(learn.accAfter, null, 'no denominator was made up (it used to be `|| 1`)')
+})
+
 /* 같은 격자 위의 점 — vantage 를 명시한다(예전 헬퍼는 t 를 늘 0 으로 두어 시간축을 전혀 시험하지 않았다). */
 const at = (t: number, error: number, actual = 100) => ({ ...pt(error, actual), t })
 

package/test/open-doors.test.ts

@@ -0,0 +1,197 @@
+/*
+ * Which of headless-twin's doors are open, and why each one is allowed to be.
+ *
+ * ── The thing this catches ──────────────────────────────────────────────────
+ * `@privilege` is opt-in. A root field that declares nothing is recorded as open, and that is
+ * indistinguishable from a field somebody decided to open. The list below turns the absence into a
+ * statement: anything open that is not on it fails, and the reason has to be written first.
+ * Same measure as `auth-base/tests/open-doors.test.ts`.
+ *
+ * ── The decision the reads rest on ──────────────────────────────────────────
+ * ADR-0027: the twin gates **writes** only. Reading is the product's purpose, and the boundary for a
+ * read is tenant membership — so an ungated read is correct only if its body narrows to the caller's
+ * domain. Every entry below says how it does. (The one read that crosses tenants on purpose,
+ * `twinLoad`, is super-user gated and so is not here.) A door that answers from the installation
+ * rather than from any tenant's rows says so instead.
+ *
+ * ── Why this reads the build ────────────────────────────────────────────────
+ * The schema is built from `service/index`'s own `resolverClasses`, the list the server boots from.
+ * type-graphql needs decorator metadata to build it, and Node's type stripping (how the other tests
+ * here run the source) does not emit it. So this one reads `dist-server`. A stale build would miss a
+ * door added since, and pass — hence the freshness check before anything else.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { createRequire } from 'node:module'
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const PKG = join(dirname(fileURLToPath(import.meta.url)), '..')
+const DIST = join(PKG, 'dist-server')
+
+/* Resolver sources newer than their build: the schema below would not be the one served. */
+function staleResolvers(): string[] {
+  const out: string[] = []
+  const walk = (dir: string) => {
+    for (const name of readdirSync(dir)) {
+      const p = join(dir, name)
+      if (statSync(p).isDirectory()) walk(p)
+      else if (p.endsWith('.ts') && /@(Query|Mutation|Subscription)\(/.test(readFileSync(p, 'utf8'))) {
+        const built = join(DIST, relative(join(PKG, 'server'), p)).replace(/\.ts$/, '.js')
+        if (!existsSync(built) || statSync(built).mtimeMs < statSync(p).mtimeMs) out.push(relative(PKG, p))
+      }
+    }
+  }
+  walk(join(PKG, 'server'))
+  return out
+}
+
+const INSTALLATION = 'answers from the installation, not from any tenant\'s rows'
+const DOMAIN_ROWS = 'reads rows where domain = the caller\'s'
+const DOMAIN_RUNTIME = 'reads the runtime keyed (caller\'s domain, instanceId)'
+
+/** Open on purpose (ADR-0027), each with how it stays inside the caller's tenant. */
+const OPEN_BY_DECISION: Record<'Query' | 'Subscription', Record<string, string>> = {
+  Query: {
+    /* Catalogues — what this build can do. */
+    referenceAdapterTypes: `${INSTALLATION}: registered connector type keys`,
+    referenceAdapters: `${INSTALLATION}: connector metadata and judged capabilities`,
+    twinDomainCatalog: `${INSTALLATION}: the kernel's location-type vocabulary`,
+    twinTargetMetrics: `${INSTALLATION}: the metric ids a target may name`,
+    twinTemplates: `${INSTALLATION}: registered twin templates and their knobs`,
+
+    /* Connections and references. */
+    discoverReferenceSites: `${DOMAIN_ROWS} (TwinReference by source), then asks that connection`,
+    referenceSources: `${DOMAIN_ROWS} (TwinInstance) and the caller's runtimes`,
+    twinConnection: `${DOMAIN_ROWS} (TwinReference, TwinInstance)`,
+    twinConnections: `${DOMAIN_ROWS} (TwinReference, TwinInstance)`,
+    twinReference: `${DOMAIN_ROWS} (TwinReference)`,
+    twinReferences: `${DOMAIN_ROWS} (TwinReference, TwinInstance)`,
+    twinReferenceReconciliation: `${DOMAIN_ROWS} (TwinReferenceReconciliation)`,
+    twinReferenceReconciliations: `${DOMAIN_ROWS} (TwinReferenceReconciliation)`,
+
+    /* Actuation — reading what was proposed and how it went. Acting is gated. */
+    twinActuationOpinion: 'loads the command by (caller\'s domain, id); refuses without a domain',
+    twinActuationOutcome: 'loads the command by (caller\'s domain, id); refuses without a domain',
+    twinActuationReadiness: 'loads the command by (caller\'s domain, id); refuses without a domain',
+    twinActuationRules: `${DOMAIN_ROWS} (TwinActuationRule list params with the caller's domain)`,
+    twinCommands: `${DOMAIN_ROWS} (TwinCommandRecord list params with the caller's domain)`,
+
+    /* Instances and lifecycle. */
+    twinAdoptionPath: `${DOMAIN_ROWS} after an ownership check`,
+    twinDeletionPreview: `${DOMAIN_ROWS} (TwinInstance, TwinEvent) — describes, deletes nothing`,
+    twinInstanceDetail: `${DOMAIN_ROWS} (TwinEngine.detail)`,
+    twinInstanceList: `${DOMAIN_ROWS} (TwinEngine.list)`,
+    twinInstances: `${DOMAIN_ROWS} (TwinEngine.list)`,
+    twinSourceCapability: `${DOMAIN_RUNTIME}; empty without a domain`,
+    twinSpaceInstanceIds: `${DOMAIN_ROWS} (TwinEngine.instanceIdsOfSpace)`,
+
+    /* Journal, history, time travel. */
+    twinAuditList: `${DOMAIN_ROWS} (TwinAuditEvent list params with the caller's domain)`,
+    twinCapacity: `${DOMAIN_RUNTIME} after an ownership check`,
+    twinEventList: `${DOMAIN_ROWS} (TwinEvent) for targets resolved inside the caller's domain`,
+    twinEvents: `${DOMAIN_ROWS} (TwinEvent)`,
+    twinKpi: `${DOMAIN_ROWS} after an ownership check`,
+    twinOperationsCapability: `${DOMAIN_RUNTIME} after an ownership check`,
+    twinReplay: `${DOMAIN_RUNTIME} or its journal (TwinEngine.recover)`,
+    twinStructures: `${DOMAIN_ROWS} (TwinStructure, TwinEvent) after an ownership check`,
+    twinSubjectHistory: `${DOMAIN_ROWS} (TwinSubjectEvent)`,
+    twinTimeRange: `${DOMAIN_ROWS} (TwinInstance, TwinEvent)`,
+
+    /* Model and entity views. */
+    spaceDeclarations: `${DOMAIN_ROWS} (TwinSpace, TwinInstance) and the caller's runtimes`,
+    twinDeclarations: `${DOMAIN_ROWS} (TwinInstance, TwinSpace) and the caller's runtime`,
+    twinItemLineage: `${DOMAIN_ROWS} (TwinInstance, TwinEvent)`,
+    twinModelEntities: `${DOMAIN_ROWS} (TwinInstance and the entity tables) or the caller's runtime`,
+    twinModelItem: `${DOMAIN_ROWS} (TwinInstance and the entity tables) or the caller's runtime`,
+    twinModelSummary: `${DOMAIN_ROWS} (TwinInstance, TwinReference, TwinEvent) or the caller's runtime`,
+    twinModelTree: `${DOMAIN_ROWS} (TwinInstance)`,
+
+    /* Spaces and targets. */
+    twinAreas: `${DOMAIN_ROWS} (TwinArea)`,
+    twinSpace: `${DOMAIN_ROWS} (TwinSpace, representations, areas)`,
+    twinSpaceIntegrity: `${DOMAIN_ROWS} (every space table)`,
+    twinSpaces: `${DOMAIN_ROWS} (TwinSpace, representations, TwinInstance)`,
+    twinTargets: `${DOMAIN_ROWS} (TwinTarget)`,
+
+    /* Live health and forecasting — computed from the caller's runtime. */
+    twinAttentionDigest: `${DOMAIN_RUNTIME} after an ownership check`,
+    twinAttentions: `${DOMAIN_RUNTIME} after an ownership check`,
+    twinForecast: `${DOMAIN_RUNTIME} (forks the caller's kernel)`,
+    twinForecastGapTrend: `${DOMAIN_RUNTIME} for the caller's co-located twins`,
+    twinIngestHealth: `${DOMAIN_RUNTIME} after an ownership check; raw samples need more`,
+    twinIngestHistory: `${DOMAIN_ROWS} (TwinIngestWindow) and the caller's runtime`,
+    twinMetrics: `${DOMAIN_RUNTIME} after an ownership check`,
+    twinMetricsAll: `${DOMAIN_RUNTIME} for every runtime of the caller's domain`
+  },
+  Subscription: {
+    twinState: 'the caller must own the instance to subscribe (ADR-0027 read)',
+    twinReferenceProgress: 'import progress for one source (ADR-0027 read)'
+  }
+}
+
+const req = createRequire(import.meta.url)
+let schemaPromise: Promise<any> | undefined
+
+function schema(): Promise<any> {
+  const stale = staleResolvers()
+  if (stale.length) {
+    throw new Error(
+      `dist-server is older than ${stale.length} resolver source(s), so the schema below is not the one served:\n  ` +
+        stale.join('\n  ') +
+        '\nBuild first: yarn workspace @things-factory/headless-twin build:server'
+    )
+  }
+  schemaPromise ??= (async () => {
+    req('reflect-metadata')
+    const { buildSchema } = req('type-graphql')
+    const { schema: declared } = req(join(DIST, 'service/index.js'))
+    const { privilegeDirectiveResolver } = req('@things-factory/auth-base/dist-server/service/privilege/privilege-directive.js')
+    /* Subscriptions need a PubSub to build. Nothing is published here — only the shape is read. */
+    const pubSub = { publish() {}, subscribe: () => (async function* () {})() }
+    const built = await buildSchema({ resolvers: declared.resolverClasses, validate: false, pubSub })
+    privilegeDirectiveResolver(built)
+    return built
+  })()
+  return schemaPromise
+}
+
+const privilegeOfField = (t: string, f: string) =>
+  req('@things-factory/auth-base/dist-server/service/privilege/privilege-directive.js').privilegeOfField(t, f)
+
+async function fieldsOf(typeName: 'Query' | 'Mutation' | 'Subscription'): Promise<string[]> {
+  const s = await schema()
+  const type = typeName === 'Query' ? s.getQueryType() : typeName === 'Mutation' ? s.getMutationType() : s.getSubscriptionType()
+  return Object.keys(type?.getFields() ?? {})
+}
+
+async function openFields(typeName: 'Query' | 'Mutation' | 'Subscription'): Promise<string[]> {
+  return (await fieldsOf(typeName)).filter(f => {
+    const gate = privilegeOfField(typeName, f)
+    return gate.known && gate.gate === null
+  })
+}
+
+test('every open read is one somebody chose, with how it stays in the caller\'s tenant', async () => {
+  for (const t of ['Query', 'Subscription'] as const) {
+    assert.deepEqual((await openFields(t)).sort(), Object.keys(OPEN_BY_DECISION[t]).sort(), `${t}: open fields ≠ OPEN_BY_DECISION`)
+  }
+})
+
+test('no write is open — ADR-0027 gates every mutation', async () => {
+  assert.deepEqual(await openFields('Mutation'), [])
+})
+
+test('the walk reaches the whole schema, not a handful of fields', async () => {
+  /* If the resolver list shrank to nothing, the two tests above would pass by having nothing to look at. */
+  assert.ok((await fieldsOf('Query')).length > 50)
+  assert.ok((await fieldsOf('Mutation')).length > 40)
+  assert.ok((await fieldsOf('Subscription')).length >= 2)
+})
+
+test('an undeclared field is told apart from one the schema does not have', async () => {
+  await schema()
+  /* `known: false` must never read as open — that is how a typo becomes a gate that is not there. */
+  assert.deepEqual(privilegeOfField('Query', 'noSuchField'), { known: false })
+})

package/test/twin-model-item-db.test.ts

@@ -292,3 +292,28 @@ test('멈춘 트윈도 저널을 계산해 답하고, 그 답은 다시 계산
   assert.equal(it.observedBasis, 'journal', '라이브가 아니라 되짚은 것이라고 말해야 "지금 이렇다" 로 읽히지 않는다')
   assert.ok(it.observedRevision > 0, '몇 번째 리비전까지 계산했는지 함께 말한다 — 규모의 한계도 그 수가 말한다')
 })
+
+test('★ 멈춘 트윈을 되세우지 못한 답도 출처가 제 근거와 같다 — 저널을 보러 간 답이 「지금 상태」라고 말하지 않는다', async () => {
+  /*
+   * ADR-0075 결정 3 · 결함 넘김 2026-09-24: 이 갈래만 `provenance.basis` 를 `state` 로 박아 두어, 같은 답이 `basis` 는
+   * `journal` 인데 출처는 `state` 였다. 커널이 멈춰 있고(`isRunning` false) 되세우기도 실패하는 때를 대역으로 세운다.
+   */
+  const { READ_BASIS } = req('@operato/ops-contract')
+  const isRunning = TwinEngine.isRunning
+  const recover = TwinEngine.recover
+  TwinEngine.isRunning = () => false
+  TwinEngine.recover = async () => {
+    throw new Error('nothing to rebuild')
+  }
+  try {
+    /* 상태에서 읽는 축이라야 이 갈래를 지난다(`orders` — 계약이 `source: 'state'` 로 선언). */
+    const it = await q.twinModelItem(INSTANCE, 'orders', 'order-1', ctx)
+    assert.equal(it.observedAbsence, 'not-running', '전제: 못 읽은 갈래다')
+    assert.equal(it.provenance.basis, it.basis, '출처와 근거가 같은 말을 한다')
+    assert.equal(it.provenance.basis, 'journal', '멈춘 트윈은 저널을 보러 갔다')
+    assert.ok(READ_BASIS.includes(it.provenance.basis))
+  } finally {
+    TwinEngine.isRunning = isRunning
+    TwinEngine.recover = recover
+  }
+})