@things-factory/headless-twin 10.1.37 → 10.1.38

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-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-state-channel.test.ts

@@ -0,0 +1,111 @@
+/*
+ * ★ Two tenants, one twin name — each subscriber receives its own tenant's messages and nothing else.
+ *
+ * The same instanceId (and the same reference source) in two tenants is the expected case: source
+ * names such as `sap-ewm-1710` are vocabulary tenants share (`runtime-key.ts`). Until 2026-09-24 both
+ * channels filtered on that name alone, so tenant B's subscriber received A's deltas, and the snapshot
+ * sent when A subscribed went to B as well.
+ *
+ * This counts what arrives. A filter test alone would not see a sender that builds its own payload
+ * without a domain, so the last two tests read the source: every sender goes through the channel's
+ * payload builder, and nothing else names the topic.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { TWIN_STATE_TOPIC, twinStateFilter, twinStatePayload } from '../server/engine/twin-state-channel.ts'
+import {
+  REFERENCE_PROGRESS_TOPIC,
+  referenceProgressFilter,
+  referenceProgressPayload
+} from '../server/service/reference/reference-progress-channel.ts'
+
+const A = 'domain-a'
+const B = 'domain-b'
+const SHARED = 'sap-ewm-1710'
+
+/* A pubsub reduced to what matters here: every published payload, and a subscriber's filter over them. */
+function bus() {
+  const sent: { topic: string; payload: any }[] = []
+  return {
+    publish: (topic: string, payload: any) => void sent.push({ topic, payload }),
+    received: (topic: string, keep: (p: any) => boolean) => sent.filter(m => m.topic === topic).map(m => m.payload).filter(keep)
+  }
+}
+
+test('twin-state: B receives none of A\'s snapshot or deltas for a twin of the same name', () => {
+  const b = bus()
+  /* A subscribes (its snapshot goes out), then both tenants' twins tick. */
+  b.publish(TWIN_STATE_TOPIC, twinStatePayload(A, { instanceId: SHARED, kind: 'snapshot', revision: 7, payload: { owner: 'A' } }))
+  b.publish(TWIN_STATE_TOPIC, twinStatePayload(A, { instanceId: SHARED, kind: 'delta', revision: 8 }))
+  b.publish(TWIN_STATE_TOPIC, twinStatePayload(B, { instanceId: SHARED, kind: 'delta', revision: 3 }))
+  b.publish(TWIN_STATE_TOPIC, twinStatePayload(B, { instanceId: 'other-twin', kind: 'delta', revision: 1 }))
+
+  const toB = b.received(TWIN_STATE_TOPIC, twinStateFilter(B, SHARED))
+  assert.deepEqual(toB.map(p => [p.domainId, p.twinState.kind, p.twinState.revision]), [[B, 'delta', 3]])
+
+  const toA = b.received(TWIN_STATE_TOPIC, twinStateFilter(A, SHARED))
+  assert.deepEqual(toA.map(p => [p.twinState.kind, p.twinState.revision]), [['snapshot', 7], ['delta', 8]])
+})
+
+test('twin-reference-progress: B receives none of A\'s import progress for a source of the same name', () => {
+  const b = bus()
+  b.publish(REFERENCE_PROGRESS_TOPIC, referenceProgressPayload(A, { source: SHARED, step: 'master', done: 1, error: 'A: connection refused' }))
+  b.publish(REFERENCE_PROGRESS_TOPIC, referenceProgressPayload(B, { source: SHARED, step: 'master', done: 2 }))
+
+  const toB = b.received(REFERENCE_PROGRESS_TOPIC, referenceProgressFilter(B, SHARED))
+  assert.deepEqual(toB.map(p => [p.domainId, p.twinReferenceProgress.done]), [[B, 2]])
+})
+
+test('a payload cannot be built without a domain', () => {
+  assert.throws(() => twinStatePayload('', { instanceId: SHARED, kind: 'delta' }), /domainId is required/)
+  assert.throws(() => referenceProgressPayload('', { source: SHARED }), /domainId is required/)
+})
+
+/* ── every sender goes through the channel ────────────────────────────────── */
+
+const SERVER = join(dirname(fileURLToPath(import.meta.url)), '..', 'server')
+const CHANNELS = new Set(['engine/twin-state-channel.ts', 'service/reference/reference-progress-channel.ts'])
+
+function serverSources(): { path: string; code: string }[] {
+  const out: { path: string; code: 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')) {
+        /* Comments describe the old shape; count code only. */
+        const code = readFileSync(p, 'utf8').replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1')
+        out.push({ path: relative(SERVER, p), code })
+      }
+    }
+  }
+  walk(SERVER)
+  return out
+}
+
+test('no sender builds a channel payload by hand, and nothing names the topics but the channels', () => {
+  const offenders: string[] = []
+  for (const { path, code } of serverSources()) {
+    if (CHANNELS.has(path)) continue
+    if (/\btwinState\s*:\s*\{/.test(code)) offenders.push(`${path}: builds { twinState: … } by hand`)
+    if (/\btwinReferenceProgress\s*:\s*\{/.test(code)) offenders.push(`${path}: builds { twinReferenceProgress: … } by hand`)
+    if (/['"`]twin-state['"`]/.test(code)) offenders.push(`${path}: names 'twin-state'`)
+    if (/['"`]twin-reference-progress['"`]/.test(code)) offenders.push(`${path}: names 'twin-reference-progress'`)
+  }
+  assert.deepEqual(offenders, [])
+})
+
+test('the senders are really there — the scan above is not passing by finding nothing', () => {
+  const callers = serverSources()
+    .filter(s => !CHANNELS.has(s.path))
+    .map(s => s.code)
+    .join('\n')
+  /* engine: runtime subscription + flush; the subscription's first snapshot. */
+  assert.equal((callers.match(/twinStatePayload\(/g) ?? []).length, 3, 'twinStatePayload call sites')
+  /* resync and import. */
+  assert.equal((callers.match(/referenceProgressPayload\(/g) ?? []).length, 2, 'referenceProgressPayload call sites')
+})