@things-factory/ai-assistant 10.1.38 → 10.1.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-assistant",
-  "version": "10.1.38",
+  "version": "10.1.40",
   "main": "dist-server/index.js",
   "things-factory": true,
   "author": "heartyoh",
@@ -29,10 +29,10 @@
     "@operato/graphql": "^10.0.0",
     "@operato/i18n": "^10.0.0",
     "@operato/styles": "^10.0.0",
-    "@things-factory/ai-client-base": "^10.1.31",
-    "@things-factory/auth-base": "^10.1.38",
+    "@things-factory/ai-client-base": "^10.1.39",
+    "@things-factory/auth-base": "^10.1.40",
     "@things-factory/env": "^10.1.20",
-    "@things-factory/shell": "^10.1.38",
+    "@things-factory/shell": "^10.1.40",
     "dompurify": "^3.0.0",
     "graphql-scalars": "^1.22.0",
     "graphql-tag": "^2.12.6",
@@ -44,5 +44,5 @@
     "copyfiles": "^2.4.1",
     "rimraf": "^5.0.0"
   },
-  "gitHead": "b947349fe1c27d11038b592ceadaba336f14785b"
+  "gitHead": "51c5d804c14ad8fcc6d4707e6ef80c9deede2766"
 }

package/server/service/chat-message/chat-message-broadcast.ts

@@ -28,39 +28,41 @@ export function chatMessageFilter(domainId: string, sessionId: string) {
 }
 
 /*
- * ── 방이 이 사람에게 열려 있나 — ADR-0073 결정 2 ────────────────────────────
+ * ── Is the room open to this person — ADR-0073 decision 2 ─────────────────────
  *
- * 공개 대화는 도메인 안 누구나, 비공개 대화는 참여자만. 저장된 길(`chatMessages`)은 그것을 묻고
- * 있었고 방송 길은 묻지 않았다 — 구독 때 도메인 소속만 보고, 필터는 도메인 + 세션만 맞췄다. 그래서
- * 비공개 세션의 id 를 가진 도메인 안 누구나 그 대화를 실시간으로 받았다.
+ * An open conversation is readable by anyone in the domain, a private one by its participants. The
+ * stored path (`chatMessages`) asked that and the broadcast path did not — subscribing checked only
+ * domain membership, and the filter matched only domain + session. So anyone in the domain holding a
+ * private session's id received that conversation as it was written.
  *
- * 규칙은 한 줄(`mayReadSession`)이고 두 길이 같은 줄을 읽는다. 여기서 다시 적으면 그날부터 두 벌이다.
+ * The rule is one line (`mayReadSession`) and both paths read that line. Writing it again here would
+ * make two copies from that day on.
  */
-/** 방에 대한 두 물음. 저장소는 부르는 쪽이 준다 — 이 파일은 저장소를 모른다. */
+/** The two questions about a room. The caller supplies the storage — this file does not know it. */
 export interface ChatRoomLookup {
-  /** 그 세션의 지금 공개 범위. 이 도메인에 그런 세션이 없으면 `undefined`. */
+  /** The session's visibility now; `undefined` when this domain has no such session. */
   visibility(): Promise<string | null | undefined>
-  /** 부르는 사람이 지금 그 세션의 참여자인가. */
+  /** Whether the caller sits in that session now. */
   isParticipant(): Promise<boolean>
 }
 
 export async function mayHearRoom(room: ChatRoomLookup): Promise<boolean> {
   const visibility = await room.visibility()
 
-  /* 이 도메인에 없는 세션 — 열림으로 읽지 않는다. */
+  /* A session this domain does not have — never read as open. */
   if (visibility === undefined) return false
 
-  /* 공개 방이면 참여 여부를 묻지 않는다. 방송마다 조회가 하나 준다. */
+  /* An open room does not ask about membership — one query fewer per message. */
   if (mayReadSession(visibility, false)) return true
 
   return mayReadSession(visibility, await room.isParticipant())
 }
 
 /**
- * 같은 도메인 + 세션이고 **그 방이 지금 이 사람에게 열려 있을 때만** 통과한다.
+ * Passes only the same domain + session, and only while **that room is open to this person**.
  *
- * 방은 메시지마다 다시 묻는다 — 누가 듣고 있는 동안 세션이 비공개로 바뀔 수 있다. 사람의 대화라
- * 메시지가 드물고, 공개 방은 조회 하나로 끝난다.
+ * The room is asked again for every message — a session can be made private while someone is
+ * listening. People write these messages, so they are infrequent, and an open room costs one query.
  */
 export function chatMessageRoomFilter(domainId: string, sessionId: string, room: ChatRoomLookup) {
   const sameSession = chatMessageFilter(domainId, sessionId)

package/server/service/chat-message/chat-message-room.ts

@@ -1,10 +1,13 @@
 /*
- * 방송 길의 방 — 구독이 돌려주는 스트림과, 방을 묻는 두 조회.
+ * The room on the broadcast path — the stream the subscription returns, and the two lookups that
+ * ask about the room.
  *
- * 구독 리졸버는 파라미터 데코레이터(@Root · @Arg) 때문에 jest 가 못 읽는다. 그래서 스트림을 짜는 일을
- * 여기로 뺐다 — 시험이 리졸버가 돌려주는 것과 **같은 것**을 돌린다(`chat-message-room.test.ts`).
+ * jest cannot read the subscription resolver (parameter decorators: @Root · @Arg), so composing the
+ * stream lives here — the test runs **the same thing** the resolver returns
+ * (`chat-message-room.test.ts`).
  *
- * 저장소는 부르는 쪽이 넘긴다. 엔티티를 여기서 import 하면 이 파일도 시험에서 못 읽는다.
+ * The caller passes the storage in. Importing the entities here would make this file unreadable to
+ * the tests too.
  */
 import { filter, pipe } from 'graphql-yoga'
 import { pubsub } from '@things-factory/shell'
@@ -16,8 +19,8 @@ interface FindOne {
 }
 
 /**
- * 방을 묻는 두 조회. **둘 다 부르는 사람의 도메인 안에서** 찾는다 — 저장된 길(`chatMessages`)의 질의와
- * 같은 조건이다.
+ * The two lookups about a room. **Both search within the caller's domain** — the same condition as
+ * the stored path's query (`chatMessages`).
  */
 export function chatRoomLookup(
   repos: { sessions: FindOne; participants: FindOne },
@@ -39,7 +42,7 @@ export function chatRoomLookup(
   }
 }
 
-/** 구독이 돌려주는 스트림 — 같은 도메인 + 세션이고, 그 방이 메시지마다 이 사람에게 열려 있을 때만. */
+/** The stream the subscription returns — same domain + session, and the room open to this person at every message. */
 export function chatMessageStream(domainId: string, sessionId: string, room: ChatRoomLookup) {
   return pipe(pubsub.subscribe(CHAT_MESSAGE_TOPIC), filter(chatMessageRoomFilter(domainId, sessionId, room)))
 }

package/server/service/chat-message/chat-message-subscription.ts

@@ -45,12 +45,13 @@ export class ChatMessageSubscription {
       await assertDomainSubscribeAllowed(domain, user, (d, u) => process.superUserGranted(d, u))
 
       /*
-       * **방을 묻는다** — ADR-0073 결정 2. 공개 방은 도메인 안 누구나, 비공개 방은 참여자만. 저장된 길
-       * (`chatMessages`)은 이것을 물었고 방송 길은 묻지 않아, 비공개 세션의 id 를 가진 도메인 안 누구나
-       * 그 대화를 실시간으로 받았다.
+       * **Ask about the room** — ADR-0073 decision 2. An open room is for anyone in the domain, a private
+       * one for its participants. The stored path (`chatMessages`) asked this and the broadcast path did
+       * not, so anyone in the domain holding a private session's id received it live.
        *
-       * 못 들어오는 방은 빈 스트림을 주지 않고 거절한다. 없는 세션과 같은 말이다 — 비공개 방이 있다는
-       * 사실도 알려 주지 않는다. 구독이 선 뒤에도 방은 메시지마다 다시 묻는다(`chatMessageRoomFilter`).
+       * A room the caller cannot enter is refused rather than handed an empty stream, in the same words
+       * as a missing session — so a private room's existence is not confirmed either. Once subscribed,
+       * the room is asked again for every message (`chatMessageRoomFilter`).
        */
       const room = chatRoomLookup(
         { sessions: getRepository(ChatSession), participants: getRepository(ChatSessionParticipant) },

package/server/service/chat-session/chat-session.ts

@@ -80,7 +80,7 @@ export class ChatSession {
   @Field({
     nullable: true,
     description:
-      "What this conversation is anchored to: 'board' | 'figure' (authoring a Figure) | 'space' | 'instance' | 'domain' | 'none'. Absent on legacy rows — treated as 'board' when boardId is present."
+      "What this conversation is anchored to: 'board' | 'figure' (authoring a Figure) | 'application' | 'space' | 'instance' | 'domain' | 'subject' (one subject in a 360, '<axis>:<itemId>') | 'none'. Absent on legacy rows — treated as 'board' when boardId is present."
   })
   anchorType?: string
 

package/server/service/chat-session/session-anchor.ts

@@ -50,11 +50,15 @@
  *   space     공간 운영 대화 — 사이트와 그 공간에서 도는 트윈들
  *   instance  트윈 하나에 대한 대화
  *   domain    테넌트 전체가 주제인 대화 — 공장 전체 문답처럼 더 좁게 가리킬 것이 없을 때
+ *   subject   one subject in a 360 — `<axis>:<itemId>`: the 360 frame's axis word (ADR-0067, the shared
+ *             frame; no new words are made here) and that row's uuid. Anchoring to `domain` instead
+ *             would put every subject's conversations in one bucket and lose the per-subject list and
+ *             history boundary (ruled 2026-09-24).
  *   none      앵커로 찾을 수 없는 대화. 「아직 아무것도 고르지 않았다」는 화면 상태다
  */
 // Figure-specific history requested explicitly: reuse the existing varchar
 // anchor columns, without writing Figure ids into the legacy boardId column.
-export const SESSION_ANCHOR_TYPES = ['board', 'figure', 'application', 'space', 'instance', 'domain', 'none'] as const
+export const SESSION_ANCHOR_TYPES = ['board', 'figure', 'application', 'space', 'instance', 'domain', 'subject', 'none'] as const
 
 export type SessionAnchorType = (typeof SESSION_ANCHOR_TYPES)[number]
 
@@ -76,6 +80,25 @@ function assertAnchorType(anchorType: string | undefined, where: string): Sessio
   return type
 }
 
+/**
+ * A `subject` anchor id is `<axis>:<itemId>`, the item being that row's uuid (ruled 2026-09-24).
+ *
+ * Checked because the shape is the whole contract: a screen that passes what it shows — an EPC like
+ * `urn:epc:id:sgtin:…`, or an order's name — would store a pointer to nothing stable. A name changes
+ * and the conversation is orphaned; an EPC splits on its own colons. Refused here, on write and on
+ * read, rather than stored and never found.
+ */
+const SUBJECT_ANCHOR_ID = /^[a-z][a-z0-9-]*:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+function assertSubjectAnchorId(type: SessionAnchorType, id: string | undefined, where: string): void {
+  if (type !== 'subject' || !id || SUBJECT_ANCHOR_ID.test(id)) return
+  throw new Error(
+    `[ai-assistant/session-anchor] ${where}: '${id}' is not a subject anchor. ` +
+      "A subject anchor is '<axis>:<itemId>' — the 360 frame's axis word and the row's uuid, " +
+      "for example 'items:6f1c…'. Resolve what the screen shows (an EPC, a name) to the row's uuid first."
+  )
+}
+
 /** 앵커 → 저장할 컬럼 값. 보드 앵커는 boardId 에도 같은 값을 넣어 기존 조회가 그대로 동작하게 한다. */
 export function anchorColumns(
   anchorType: string | undefined,
@@ -91,6 +114,7 @@ export function anchorColumns(
         "Use 'none' for a conversation that is deliberately not addressable by anchor."
     )
   }
+  assertSubjectAnchorId(type, id, 'anchorColumns')
   return { anchorType: type, anchorId: id, boardId: type === 'board' ? id : undefined }
 }
 
@@ -112,6 +136,7 @@ export function anchorColumns(
  */
 export function anchorWhere(domainId: string, anchorType: string, anchorId: string, kind?: string): any {
   const type = assertAnchorType(anchorType, 'anchorWhere')
+  assertSubjectAnchorId(type, anchorId, 'anchorWhere')
   const where = type === 'board' ? { boardId: anchorId, domain: { id: domainId } } : { anchorType: type, anchorId, domain: { id: domainId } }
   return kind ? { ...where, kind } : where
 }

package/server/service/session-anchor.test.ts

@@ -12,6 +12,9 @@
  *  ③ 공간·인스턴스 앵커는 boardId 를 오염시키지 않는다(보드 조회에 섞이면 이력 경계가 무너진다).
  */
 import { anchorColumns, anchorWhere, isSessionAnchorType, SESSION_ANCHOR_TYPES } from './chat-session/session-anchor'
+import { initialVisibility } from './chat-session/session-visibility'
+
+const SUBJECT_ID = 'items:6f1c2a90-3b4d-4e5f-8a6b-7c8d9e0f1a2b'
 
 describe('앵커 저장 값 (anchorColumns)', () => {
   it('board 앵커는 anchorId 와 boardId 에 같은 값을 쓴다 — 기존 조회 하위호환', () => {
@@ -134,7 +137,9 @@ describe('앵커 조회 조건 (anchorWhere)', () => {
 
   it('모든 조회에 domain 조건이 포함된다 — 빠지면 남의 테넌트 대화가 보인다', () => {
     for (const type of SESSION_ANCHOR_TYPES) {
-      expect(anchorWhere('dom-9', type, 'X').domain).toEqual({ id: 'dom-9' })
+      /* A subject anchor has a shape of its own (below); every other type takes any id. */
+      const id = type === 'subject' ? SUBJECT_ID : 'X'
+      expect(anchorWhere('dom-9', type, id).domain).toEqual({ id: 'dom-9' })
     }
   })
 
@@ -142,3 +147,52 @@ describe('앵커 조회 조건 (anchorWhere)', () => {
     expect(anchorWhere('dom-1', 'space', 'busan').boardId).toBeUndefined()
   })
 })
+
+/*
+ * The subject anchor — one subject in a 360 (ruled 2026-09-24).
+ *
+ * `<axis>:<itemId>`: the 360 frame's axis word and that row's uuid. Tested on both sides the ruling
+ * split: without an id it throws, and with one it is stored as given and finds its own list again.
+ */
+describe('the subject anchor', () => {
+  it('★ without an id it throws — a pointer to nothing would never be found again', () => {
+    expect(() => anchorColumns('subject', '')).toThrow(/was given no id/)
+    expect(() => anchorColumns('subject', undefined)).toThrow(/was given no id/)
+  })
+
+  it('★ `<axis>:<itemId>` is stored as given, and the lookup for that subject finds it', () => {
+    const stored = anchorColumns('subject', SUBJECT_ID)
+    expect(stored).toEqual({ anchorType: 'subject', anchorId: SUBJECT_ID, boardId: undefined })
+
+    const where = anchorWhere('dom-1', 'subject', SUBJECT_ID)
+    expect(where).toEqual({ anchorType: stored.anchorType, anchorId: stored.anchorId, domain: { id: 'dom-1' } })
+  })
+
+  it("another subject, another axis or another domain is another list", () => {
+    const other = 'items:0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d'
+    const sameRowOtherAxis = SUBJECT_ID.replace('items:', 'locations:')
+
+    expect(anchorWhere('dom-1', 'subject', other)).not.toEqual(anchorWhere('dom-1', 'subject', SUBJECT_ID))
+    expect(anchorWhere('dom-1', 'subject', sameRowOtherAxis)).not.toEqual(anchorWhere('dom-1', 'subject', SUBJECT_ID))
+    expect(anchorWhere('dom-2', 'subject', SUBJECT_ID)).not.toEqual(anchorWhere('dom-1', 'subject', SUBJECT_ID))
+  })
+
+  it.each([
+    ['an EPC, as the screen shows a pallet', 'items:urn:epc:id:sgtin:0614141.107346.2017'],
+    ['a name, as the screen shows an order', 'orders:SO-A887417'],
+    ['a uuid with no axis', '6f1c2a90-3b4d-4e5f-8a6b-7c8d9e0f1a2b'],
+    ['an axis with no item', 'items:']
+  ])('★ refuses %s — on write and on read', (_what, id) => {
+    expect(() => anchorColumns('subject', id)).toThrow(/is not a subject anchor/)
+    expect(() => anchorWhere('dom-1', 'subject', id)).toThrow(/is not a subject anchor/)
+  })
+
+  it('the shape rule is the subject anchor\'s alone — other anchors keep taking the ids they take', () => {
+    expect(anchorColumns('space', 'busan').anchorId).toBe('busan')
+    expect(anchorColumns('application', 'operato-figure').anchorId).toBe('operato-figure')
+  })
+
+  it('★ a subject conversation is born open — an anchored conversation is about a shared thing (ADR-0073 decision 2)', () => {
+    expect(initialVisibility({ anchorType: 'subject' })).toBe('open')
+  })
+})

package/server/service/testing/conversation-script.test.ts

@@ -101,7 +101,7 @@ it('★ a proposal belongs to the turn that asked for it', async () => {
       {
         kind: 'read',
         name: 'proposeSceneEdit',
-        /* 저작 도구는 열린 씬만 본다 — 저장소에 닿지 않으므로 문이 없다. */
+        /* An authoring tool reads only the open scene — it reaches no storage, so it has no doors. */
         doors: [],
         description: 'propose placing a component',
         schema: {},

package/server/service/testing/mode-conformance.test.ts

@@ -26,9 +26,9 @@ beforeEach(() => {
     name: 'twin-authoring',
     guidance: 'read the scene before proposing an edit',
     specs: [
-      /* 화면이 보낸 것을 되돌려 준다 — 저장소에 안 닿는다. */
+      /* Hands back what the surface sent — reaches no storage. */
       { kind: 'read', name: 'getOpenScene', description: 'the open scene', schema: {}, doors: [], builder: () => ({}) },
-      /* 저장소를 읽는다 — 문을 적는다. 관문이 이 자리를 가른다. */
+      /* Reads storage — names its door. This is where the gate splits. */
       { kind: 'read', name: 'getTwinStructure', description: 'the twin structure', schema: {}, doors: ['Query.twinInstances'], builder: () => ({}) }
     ]
   } as any)

package/server/service/testing/mode-conformance.ts

@@ -53,11 +53,12 @@ export async function runRegisteredMode(
     maxTokens: settings.maxTokens,
     hostContext: options.hostContext,
     /*
-     * 이 하네스가 묻는 것은 **모드**다 — 「이 모드가 무엇을 여는가」이지 「이 사람이 문을 지나는가」가
-     * 아니다. 관문이 `doors` 로 옮겨간 뒤(ADR-0071 결정 2) 검사를 안 넘기면 문을 적은 도구가 전부
-     * 닫히고, 그러면 앱의 적합성 시험에서 **실제 자료를 읽는 도구만** 조용히 사라진다. 그래서 기본은
-     * 모든 문을 지나는 사람이고, 다른 쪽을 보고 싶은 앱은 `toolAccess` 를 적어 그 경우를 쓴다.
-     * 권한 축은 자기 시험이 따로 본다(`tool-access.test.ts` · `tool-scope.test.ts`).
+     * This harness asks about **the mode** — "what does this mode open", not "does this person pass the
+     * doors". Since the gate moved onto `doors` (ADR-0071 decision 2), passing no check closes every tool
+     * that names a door, and an app's conformance test would quietly lose **exactly the tools that read
+     * real data**. So the default is someone who passes every door; an app that wants the other case
+     * writes `toolAccess`. The permission axis has its own tests (`tool-access.test.ts` ·
+     * `tool-scope.test.ts`).
      */
     toolAccess: options.toolAccess ?? (async () => true),
     state: options.state ?? { domain: { id: 'dom-1' }, user: { id: 'u-1' } }

package/test/assistant-request-context.test.ts

@@ -1,7 +1,7 @@
 import assert from 'node:assert/strict'
 import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
-import { assistantAutoAskKey, assistantModelFingerprint, assistantRecentSessions } from '../client/utils/assistant-request-context.ts'
+import { assistantAutoAskKey, assistantDraftDecision, assistantModelFingerprint, assistantRecentSessions } from '../client/utils/assistant-request-context.ts'
 
 test('model signature ignores object key order but detects nested edits and array order', () => {
   assert.equal(assistantModelFingerprint({ b: 2, a: { y: 3, x: 1 } }), assistantModelFingerprint({ a: { x: 1, y: 3 }, b: 2 }))
@@ -28,3 +28,43 @@ test('send captures current context before optimistic input and attaches request
   assert.match(send, /detail: \{ actions: out.actions, sessionId: out.sessionId, requestBase \}/)
   assert.match(send, /requestContext\.hostContext/)
 })
+
+/*
+ * The draft — a sentence placed in the input for the person to edit and send (twin's "new twin → AI").
+ */
+test('★ a draft fills an empty input once per request, and a re-render does not fill it again', () => {
+  const first = assistantDraftDecision({ draft: 'make a twin of line 3', draftRequestId: 'r1', typed: '' })
+  assert.deepEqual(first, { fill: true, consumed: assistantAutoAskKey('make a twin of line 3', 'r1') })
+
+  const again = assistantDraftDecision({ draft: 'make a twin of line 3', draftRequestId: 'r1', drafted: first.consumed, typed: '' })
+  assert.equal(again.fill, false)
+
+  const next = assistantDraftDecision({ draft: 'make a twin of line 3', draftRequestId: 'r2', drafted: first.consumed, typed: '' })
+  assert.equal(next.fill, true, 'the same sentence under a new request is a new draft')
+})
+
+test('★ a draft never overwrites what the person is typing — and does not surface later', () => {
+  const out = assistantDraftDecision({ draft: 'make a twin', draftRequestId: 'r1', typed: 'how many forklifts' })
+  assert.equal(out.fill, false)
+  assert.ok(out.consumed, 'skipped, and remembered as consumed')
+})
+
+test('★ when autoAsk comes for the same request, autoAsk wins', () => {
+  const out = assistantDraftDecision({ draft: 'edit me', draftRequestId: 'r1', typed: '', autoAsk: 'send me', autoAskRequestId: 'r1' })
+  assert.equal(out.fill, false)
+
+  const otherRequest = assistantDraftDecision({ draft: 'edit me', draftRequestId: 'r2', typed: '', autoAsk: 'send me', autoAskRequestId: 'r1' })
+  assert.equal(otherRequest.fill, true)
+})
+
+test('no draft, nothing to do', () => {
+  assert.deepEqual(assistantDraftDecision({ typed: '' }), { fill: false })
+})
+
+test('the component places the draft and never sends it', () => {
+  const chat = readFileSync(join(__dirname, '../client/components/assistant-chat.ts'), 'utf8')
+  const updated = chat.slice(chat.indexOf('  updated(changed'), chat.indexOf('if (changed.has(\'subject\'))'))
+  const draftPart = updated.slice(updated.indexOf('assistantDraftDecision('))
+  assert.match(draftPart, /this\.input = this\.draft!/)
+  assert.doesNotMatch(draftPart, /this\.send\(\)/)
+})

package/test/open-doors.test.ts

@@ -0,0 +1,132 @@
+/*
+ * Which of ai-assistant'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 `worklist/tests/open-doors.test.ts` and `headless-twin/test/open-doors.test.ts`.
+ *
+ * ── What the census found (2026-09-24) ──────────────────────────────────────
+ * 27 root fields, 25 declare `ai-assistant:query` or `:mutation`. The two open ones are the
+ * subscriptions — a stream has no `@privilege` to carry, so what keeps it inside the tenant is its
+ * subscribe and its filter. Writing their reasons found one false: `chatMessageActivity` asked the
+ * domain and the session but not the room, so a private conversation streamed to anyone in the
+ * domain holding its id (ADR-0073 decision 2). Fixed in `8264dc46e7`; the reason below is true
+ * from then on, and `chat-message-room.test.ts` keeps it true.
+ *
+ * ── Why the compiled output ──────────────────────────────────────────────────
+ * type-graphql needs `emitDecoratorMetadata` to build the schema; jest's babel transform does not
+ * emit it. So this reads `dist-server` — and a build older than its sources would miss a door added
+ * since and pass, hence the freshness check before anything else.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
+import { join, relative } from 'path'
+
+import { buildSchema } from 'type-graphql'
+import type { GraphQLSchema } from 'graphql'
+
+const PKG = join(__dirname, '..')
+const DIST = join(PKG, 'dist-server')
+const AUTH_BASE_DIST = join(PKG, '..', 'auth-base', '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 path = join(dir, name)
+      if (statSync(path).isDirectory()) walk(path)
+      else if (path.endsWith('.ts') && !path.endsWith('.test.ts') && /@(Query|Mutation|Subscription)\(/.test(readFileSync(path, 'utf8'))) {
+        const built = join(DIST, relative(join(PKG, 'server'), path)).replace(/\.ts$/, '.js')
+        if (!existsSync(built) || statSync(built).mtimeMs < statSync(path).mtimeMs) out.push(relative(PKG, path))
+      }
+    }
+  }
+  walk(join(PKG, 'server'))
+  return out
+}
+
+type Root = 'Query' | 'Mutation' | 'Subscription'
+
+/** Open on purpose, each with what keeps it inside the caller's tenant — and, for a room, inside the room. */
+const OPEN_BY_DECISION: Record<Root, Record<string, string>> = {
+  Query: {},
+  Mutation: {},
+  Subscription: {
+    chatMessageActivity:
+      "subscribe: a member of the domain, and the room open to the caller — open to the domain, private to its participants " +
+      '(ADR-0073 decision 2), refused with the words of a missing session otherwise. Every message: same domain + session, ' +
+      'and the room asked again. The body is redacted by doors for each receiver (ADR-0073 ruling 1).',
+    mySessionActivity:
+      "subscribe: a member of the domain. Every message: same domain, and the caller among the payload's participants. " +
+      'Badge fields and a one-line preview only, no body.'
+  }
+}
+
+let schema: GraphQLSchema
+let privilegeOfField: (typeName: string, field: string) => { known: boolean; gate?: unknown }
+
+beforeAll(async () => {
+  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/ai-assistant build:server'
+    )
+  }
+
+  const { schema: declared } = require(join(DIST, 'service', 'index.js'))
+  const directive = require(join(AUTH_BASE_DIST, 'service', 'privilege', 'privilege-directive.js'))
+  privilegeOfField = directive.privilegeOfField
+
+  schema = await buildSchema({
+    resolvers: declared.resolverClasses,
+    validate: false,
+    /* The subscriptions name their own subscribe; the walk only needs a pubSub to accept them. */
+    pubSub: { publish() {}, subscribe() {} } as any
+  })
+  directive.privilegeDirectiveResolver(schema)
+})
+
+function fieldsOf(typeName: Root): string[] {
+  const type = typeName === 'Query' ? schema.getQueryType() : typeName === 'Mutation' ? schema.getMutationType() : schema.getSubscriptionType()
+  return Object.keys(type?.getFields() ?? {})
+}
+
+function openFields(typeName: Root): string[] {
+  return fieldsOf(typeName).filter(field => {
+    const gate = privilegeOfField(typeName, field)
+    return gate.known && gate.gate === null
+  })
+}
+
+describe('every open door has a written reason', () => {
+  it.each(['Query', 'Mutation', 'Subscription'] as const)('%s', typeName => {
+    expect(openFields(typeName).sort()).toEqual(Object.keys(OPEN_BY_DECISION[typeName]).sort())
+  })
+})
+
+describe('what the walk itself has to be true for', () => {
+  it('reaches the whole schema, not a handful of fields', () => {
+    /* If the resolver list shrank to nothing, the lists above would pass by having nothing to look at. */
+    expect(fieldsOf('Query').length).toBeGreaterThanOrEqual(10)
+    expect(fieldsOf('Mutation').length).toBeGreaterThanOrEqual(13)
+    expect(fieldsOf('Subscription')).toHaveLength(2)
+  })
+
+  it('tells an undeclared field from one the schema does not have', () => {
+    /* `known: false` must never read as open — that is how a typo becomes a gate that is not there. */
+    expect(privilegeOfField('Query', 'noSuchField')).toEqual({ known: false })
+  })
+
+  it('the census, in plain numbers', () => {
+    /* 2026-09-24: 27 root fields, 25 declared, 2 open — both streams. */
+    const all = fieldsOf('Query').length + fieldsOf('Mutation').length + fieldsOf('Subscription').length
+    const open = openFields('Query').length + openFields('Mutation').length + openFields('Subscription').length
+
+    expect(all).toBe(27)
+    expect(open).toBe(2)
+  })
+})