@things-factory/ai-assistant 10.1.38 → 10.1.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-assistant",
-  "version": "10.1.38",
+  "version": "10.1.39",
   "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.39",
     "@things-factory/env": "^10.1.20",
-    "@things-factory/shell": "^10.1.38",
+    "@things-factory/shell": "^10.1.39",
     "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": "fe5257ad8995fe7e79275e287f36e95b5fd32d1c"
 }

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