@things-factory/ai-client-base 10.1.28 → 10.1.31

package/server/service/assistant/registry-assistant.test.ts

@@ -51,6 +51,7 @@ beforeEach(() => {
         kind: 'read',
         name: 'listFigures',
         description: 'lists figures',
+        doors: ['Query.figures'],
         schema: { type: 'object', properties: {} },
         builder: (args: any, context: any) => {
           ran.push({ name: 'listFigures', args, context })
@@ -61,7 +62,7 @@ beforeEach(() => {
         kind: 'write',
         name: 'addComponent',
         description: 'adds a component to the document',
-        privilege: { category: 'board', privilege: 'mutation' },
+        doors: ['Mutation.updateBoard'],
         schema: { type: 'object', properties: {} },
         builder: () => {
           ran.push({ name: 'addComponent', args: {}, context: null })
@@ -79,6 +80,7 @@ beforeEach(() => {
         kind: 'read',
         name: 'readOrderState',
         description: 'reads live order state',
+        doors: ['Query.jobOrders'],
         schema: { type: 'object', properties: {} },
         builder: (args: any, context: any) => {
           ran.push({ name: 'readOrderState', args, context })
@@ -89,9 +91,8 @@ beforeEach(() => {
   } as any)
 
   /*
-   * A category whose tools change something outside the conversation, each behind the same
-   * privilege its GraphQL door uses. This is the shape of board-import's `materializeImportSession`,
-   * which creates a Board.
+   * A category whose tools change something outside the conversation, each naming the GraphQL door
+   * it reaches. This is the shape of board-import's `materializeImportSession`, which creates a Board.
    */
   registerToolCategory({
     name: 'board-import',
@@ -101,7 +102,7 @@ beforeEach(() => {
         kind: 'read',
         name: 'getImportSession',
         description: 'reads an import session',
-        privilege: { category: 'board-import', privilege: 'query' },
+        doors: ['Query.importSession'],
         schema: { type: 'object', properties: {} },
         builder: (args: any, context: any) => {
           ran.push({ name: 'getImportSession', args, context })
@@ -112,7 +113,7 @@ beforeEach(() => {
         kind: 'external',
         name: 'materializeImportSession',
         description: 'creates a board from an import session',
-        privilege: { category: 'board-import', privilege: 'mutation' },
+        doors: ['Mutation.materializeImportSession'],
         schema: { type: 'object', properties: {} },
         builder: (args: any, context: any) => {
           ran.push({ name: 'materializeImportSession', args, context })
@@ -128,6 +129,12 @@ const input = (over: any = {}) => ({
   messages: [{ role: 'user' as const, content: 'what figures do we have' }],
   systemPrompt: 'you help someone draw a figure',
   state: { domain: { id: 'dom-1' }, user: { id: 'u-1' } },
+  /*
+   * Every tool here names a door, and a door is asked of the host (ADR-0071 decision 2). A caller
+   * who passes them all is the uninteresting case, so it is the default; the tests about the gate
+   * itself pass their own check, and one passes `toolAccess: undefined` on purpose.
+   */
+  toolAccess: async () => true,
   ...over
 })
 
@@ -246,7 +253,7 @@ describe('who may use a tool (A1)', () => {
     expect(ran).toHaveLength(0)
   })
 
-  it('★ a tool that changes something outside is not offered here, even with the privilege', async () => {
+  it('★ a tool that changes something outside is not offered here, even when its door is open', async () => {
     const { client, seen } = recordingClient([okResult(undefined, [TC('materializeImportSession')]), okResult('done')])
 
     await registryAssistantChat(input({ client, toolCategories: ['board-import'], toolAccess: grantAll }))
@@ -255,7 +262,7 @@ describe('who may use a tool (A1)', () => {
     expect(ran.map(one => one.name)).not.toContain('materializeImportSession')
   })
 
-  it('★ a tool behind a privilege the caller lacks is neither offered nor run when called by name', async () => {
+  it('★ a tool whose door the caller cannot pass is neither offered nor run when called by name', async () => {
     const { client, seen } = recordingClient([okResult(undefined, [TC('getImportSession')]), okResult('done')])
 
     await registryAssistantChat(input({ client, toolCategories: ['board-import'], toolAccess: denyAll }))
@@ -264,16 +271,16 @@ describe('who may use a tool (A1)', () => {
     expect(ran.map(one => one.name)).not.toContain('getImportSession')
   })
 
-  it('★ with no access check at all, a tool behind a privilege stays closed', async () => {
+  it('★ with no access check at all, a tool that reaches a door stays closed', async () => {
     const { client, seen } = recordingClient([okResult(undefined, [TC('getImportSession')]), okResult('done')])
 
-    await registryAssistantChat(input({ client, toolCategories: ['board-import'] }))
+    await registryAssistantChat(input({ client, toolCategories: ['board-import'], toolAccess: undefined }))
 
     expect(seen[0].tools.map((t: any) => t.name)).not.toContain('getImportSession')
     expect(ran.map(one => one.name)).not.toContain('getImportSession')
   })
 
-  it('the access check is asked with the privilege the tool declares, and a grant opens the tool', async () => {
+  it('the access check is asked for the doors the tool names, and a caller holding them opens it', async () => {
     const asked: any[] = []
     const { client, seen } = recordingClient([okResult(undefined, [TC('getImportSession')]), okResult('done')])
 
@@ -281,14 +288,14 @@ describe('who may use a tool (A1)', () => {
       input({
         client,
         toolCategories: ['board-import'],
-        toolAccess: async (privilege: any) => {
-          asked.push(privilege)
-          return privilege.privilege === 'query'
+        toolAccess: async (door: string) => {
+          asked.push(door)
+          return door.startsWith('Query.')
         }
       })
     )
 
-    expect(asked).toContainEqual({ category: 'board-import', privilege: 'query' })
+    expect(asked).toContain('Query.importSession')
     expect(seen[0].tools.map((t: any) => t.name)).toContain('getImportSession')
     expect(ran.map(one => one.name)).toContain('getImportSession')
   })
@@ -307,3 +314,46 @@ describe('a client that cannot call tools', () => {
     await expect(registryAssistantChat(input({ client: {} as any }))).rejects.toThrow(/cannot call tools/)
   })
 })
+
+/*
+ * 도구가 「어느 대화에서 불렸나」를 안다 — ADR-0061 결정 3.
+ *
+ * 이 칸은 A2(모드를 서버가 등록한다)가 서기 전까지 비어 있었고 주석만 「A2 가 서면」이라고 적혀 있었다.
+ * A2 가 선 뒤에도 채우는 쪽이 없어서 도구는 계속 `host` 만 봤다 — 그것은 클라이언트가 채우는 칸이다.
+ */
+describe('the tool context carries the conversation', () => {
+  it('★ 부르는 쪽이 준 mode 가 도구에게 간다 — 서버의 값이다', async () => {
+    const { client } = recordingClient([okResult(undefined, [TC('listFigures')]), okResult('ok')])
+
+    await registryAssistantChat(
+      input({ client, toolCategories: ['figure-authoring'], mode: { kind: 'twin.space', target: 'SITE-1' } })
+    )
+
+    expect(ran[0].context.mode).toEqual({ kind: 'twin.space', target: 'SITE-1' })
+  })
+
+  it('★ 그 값은 `host` 와 섞이지 않는다 — 하나는 서버가, 하나는 클라이언트가 채운다', async () => {
+    const { client } = recordingClient([okResult(undefined, [TC('listFigures')]), okResult('ok')])
+
+    await registryAssistantChat(
+      input({
+        client,
+        toolCategories: ['figure-authoring'],
+        hostContext: { figureId: 'fig-1' },
+        mode: { kind: 'figure.modeller' }
+      })
+    )
+
+    expect(ran[0].context).toEqual(
+      toolCallContextFixture({ domainId: 'dom-1', userId: 'u-1', host: { figureId: 'fig-1' }, mode: { kind: 'figure.modeller' } })
+    )
+  })
+
+  it('mode 를 안 주면 그 칸은 없다 — 빈 값을 지어내지 않는다', async () => {
+    const { client } = recordingClient([okResult(undefined, [TC('listFigures')]), okResult('ok')])
+
+    await registryAssistantChat(input({ client, toolCategories: ['figure-authoring'] }))
+
+    expect(ran[0].context).not.toHaveProperty('mode')
+  })
+})

package/server/service/assistant/registry-assistant.ts

@@ -49,6 +49,14 @@ export interface RegistryAssistantInput {
   toolAccess?: ToolAccessCheck
   /** Passed to tools as `context.host`. Client-supplied — never used for authorization. */
   hostContext?: any
+  /**
+   * Which conversation this is — `{ kind, target }` from the registered mode (ADR-0061 decision 3).
+   *
+   * Tools see it as `context.mode`. It is the server's value, resolved from the registry before the
+   * turn runs, so a tool that behaves differently in two conversations reads it here and not from
+   * `host`, which the client fills.
+   */
+  mode?: { kind: string; target?: string }
   /** Caller's koa state (domain, user, tx). Tools that read the database need it. */
   state: any
   model?: string
@@ -106,7 +114,11 @@ export async function registryAssistantChat(input: RegistryAssistantInput): Prom
   const guidance = toolScopeGuidance(scope)
   const prompt = guidance.length > 0 ? `${systemPrompt}\n\n${guidance.join('\n\n')}` : systemPrompt
 
-  const toolContext: ToolCallContext = { state, host: hostContext ?? {} }
+  /*
+   * `mode` 는 서버의 값이다 — 등록된 모드에서 왔고, `host` 와 달리 클라이언트가 못 고친다. A2 가 서기
+   * 전에는 채울 것이 없어 비워 두었다(ADR-0061 결정 3 의 주석). 이제 부르는 쪽이 들고 있다.
+   */
+  const toolContext: ToolCallContext = { state, host: hostContext ?? {}, ...(input.mode ? { mode: input.mode } : {}) }
 
   const result = await assistantChat<ToolCallContext, unknown>({
     initialConversation: messages,

package/server/service/assistant/tool-scope.test.ts

@@ -0,0 +1,123 @@
+/**
+ * What this guards: which tools one conversation is offered, now that the **doors** decide it
+ * (ADR-0071 decision 2, added to 2026-09-18).
+ *
+ * The three states of `doors` are three different answers, and the interesting one is the third:
+ * a tool that says nothing is **left out**, not opened. Reading an absent declaration as "nothing
+ * to check" is how the board-import tool reached every conversation once already.
+ */
+import { registerToolCategory, clearToolRegistry } from '../tool-registry/registry'
+import type { ToolCategory, ToolSpec } from '../tool-registry/types'
+import { resolveToolScope, narrowToolScope, EMPTY_TOOL_SCOPE } from './tool-scope'
+
+afterEach(() => clearToolRegistry())
+
+function category(name: string, specs: Partial<ToolSpec>[]): ToolCategory {
+  return {
+    name,
+    guidance: `- fixture guidance for ${name}`,
+    specs: specs.map(s => ({
+      kind: 'read' as const,
+      name: 'unnamed',
+      description: 'desc',
+      schema: {},
+      builder: () => ({}),
+      ...s
+    })) as ToolSpec[]
+  }
+}
+
+const names = (scope: { specs: ReadonlyArray<ToolSpec> }) => scope.specs.map(s => s.name)
+
+/** A caller holding these doors and no others. */
+const holding = (...doors: string[]) => jest.fn(async (door: string) => doors.includes(door))
+
+describe('resolveToolScope — the doors decide', () => {
+  test('★ a tool that names no doors at all is left out, not let through', async () => {
+    registerToolCategory(category('mixed', [{ name: 'undeclared' }, { name: 'declared', doors: ['Query.a'] }]))
+
+    const scope = await resolveToolScope(['mixed'], holding('Query.a'))
+
+    expect(names(scope)).toEqual(['declared'])
+  })
+
+  test('★ `doors: []` passes without asking — it reaches nothing to ask about', async () => {
+    const access = holding()
+    registerToolCategory(category('surface', [{ name: 'getOpenScene', doors: [] }]))
+
+    expect(names(await resolveToolScope(['surface'], access))).toEqual(['getOpenScene'])
+    expect(access).not.toHaveBeenCalled()
+  })
+
+  test('★ several doors are AND — half of them is not enough', async () => {
+    registerToolCategory(
+      category('plant', [
+        { name: 'overview', doors: ['Query.jobOrders', 'Query.productionReports'] },
+        { name: 'findJobOrders', doors: ['Query.jobOrders'] }
+      ])
+    )
+
+    const scope = await resolveToolScope(['plant'], holding('Query.jobOrders'))
+
+    expect(names(scope)).toEqual(['findJobOrders'])
+  })
+
+  test('each door is asked once however many tools reach it', async () => {
+    const access = holding('Query.jobOrders', 'Query.productionReports')
+    registerToolCategory(
+      category('plant', [
+        { name: 'overview', doors: ['Query.jobOrders', 'Query.productionReports'] },
+        { name: 'findJobOrders', doors: ['Query.jobOrders'] },
+        { name: 'attention', doors: ['Query.jobOrders', 'Query.productionReports'] }
+      ])
+    )
+
+    await resolveToolScope(['plant'], access)
+
+    expect(access.mock.calls.map(c => c[0]).sort()).toEqual(['Query.jobOrders', 'Query.productionReports'])
+  })
+
+  test('★ no access check closes every tool that reaches a door', async () => {
+    registerToolCategory(category('plant', [{ name: 'findJobOrders', doors: ['Query.jobOrders'] }, { name: 'getOpenScene', doors: [] }]))
+
+    expect(names(await resolveToolScope(['plant']))).toEqual(['getOpenScene'])
+  })
+
+  test('a door check that throws closes that door', async () => {
+    const access = jest.fn(async () => {
+      throw new Error('auth is down')
+    })
+    registerToolCategory(category('plant', [{ name: 'findJobOrders', doors: ['Query.jobOrders'] }]))
+
+    expect(await resolveToolScope(['plant'], access)).toEqual(EMPTY_TOOL_SCOPE)
+  })
+
+  test('a category left with no usable tool drops out, so its guidance is not read to the model', async () => {
+    registerToolCategory(category('plant', [{ name: 'findJobOrders', doors: ['Query.jobOrders'] }]))
+    registerToolCategory(category('twin', [{ name: 'queryState', doors: ['Query.twinReplay'] }]))
+
+    const scope = await resolveToolScope(['plant', 'twin'], holding('Query.twinReplay'))
+
+    expect(scope.categories.map(c => c.name)).toEqual(['twin'])
+  })
+
+  test('nothing asked for is nothing offered', async () => {
+    registerToolCategory(category('plant', [{ name: 'findJobOrders', doors: [] }]))
+
+    expect(await resolveToolScope([], holding())).toEqual(EMPTY_TOOL_SCOPE)
+    expect(await resolveToolScope(undefined as any, holding())).toEqual(EMPTY_TOOL_SCOPE)
+  })
+
+  test('narrowing keeps the same reading — a surface that runs only reads', async () => {
+    registerToolCategory(
+      category('twin', [
+        { name: 'queryState', doors: ['Query.twinReplay'] },
+        { name: 'bindEntity', kind: 'write', doors: ['Query.twinReplay'] }
+      ])
+    )
+
+    const scope = await resolveToolScope(['twin'], holding('Query.twinReplay'))
+
+    expect(names(narrowToolScope(scope, spec => spec.kind === 'read'))).toEqual(['queryState'])
+  })
+})

package/server/service/assistant/tool-scope.ts

@@ -4,23 +4,32 @@
  *
  * ── Two questions, one list ───────────────────────────────────────────────────────
  *   Which categories did this surface ask for?     `toolCategories`
- *   Which of their tools may this caller use?      each spec's `privilege`, asked of `access`
+ *   Which of their tools may this caller use?      each spec's `doors`, asked of `access`
  *
  * **Nothing asked means nothing offered.** Omitting the category list used to mean "every
  * registered category"; that default is the one that opened board-import's Board-creating tool to
  * any conversation. An absent answer leans to the closed side (ADR-0047 ② · ADR-0053).
  *
- * **No access check means privileged tools stay closed.** A caller that cannot say who is asking
- * gets only the tools that need no privilege.
+ * **The doors are the gate** (ADR-0071 decision 2). A tool used to declare its own copy of what its
+ * door asks, and this asked that copy. Two declarations of one fact drift, and the looser one wins;
+ * plant's hand-written read check and its `doors` list were that pair. Now a tool names the doors it
+ * reaches and the host resolves each one against the door's own declaration, so what passes here is
+ * what passes at the door.
+ *
+ * **All the doors, not one of them.** A tool that answers from two doors hands back what is behind
+ * both, so the caller holds both (AND, the same reading as AUTH's `requiresAll`).
+ *
+ * **No access check means a tool that reaches a door stays closed.** A caller that cannot say who is
+ * asking gets only the tools that reach nothing.
  *
  * The permission check itself belongs to auth, which this package does not depend on, so the host
- * hands it in (`ai-assistant` builds it from the request state).
+ * hands it in (`ai-assistant` builds it from the request state and AUTH's field table).
  */
 import { getToolCategories, type ToolCategoryFilter } from '../tool-registry/index.js'
-import type { ToolPrivilege, ToolSpec } from '../tool-registry/types.js'
+import type { ToolSpec } from '../tool-registry/types.js'
 
-/** Answers "may this caller use a door guarded by this privilege". */
-export type ToolAccessCheck = (privilege: ToolPrivilege) => Promise<boolean>
+/** Answers "may this caller pass this door" — `'Query.jobOrders'`. */
+export type ToolAccessCheck = (door: string) => Promise<boolean>
 
 export interface ScopedCategory {
   readonly name: string
@@ -38,20 +47,28 @@ export interface ToolScope {
 
 export const EMPTY_TOOL_SCOPE: ToolScope = Object.freeze({ categories: [], specs: [] })
 
-const privilegeKey = (p: ToolPrivilege) => [p.category, p.privilege, !!p.owner, !!p.super].join('|')
-
 export async function resolveToolScope(requested: ToolCategoryFilter, access?: ToolAccessCheck): Promise<ToolScope> {
   if (!requested || requested.length === 0) return EMPTY_TOOL_SCOPE
 
-  /* One check per distinct privilege — a category of ten read tools asks once. */
+  /* One check per distinct door — five tools behind `Query.jobOrders` ask once. */
   const answers = new Map<string, Promise<boolean>>()
-  const mayUse = (spec: ToolSpec): Promise<boolean> => {
-    const privilege = spec.privilege
-    if (!privilege) return Promise.resolve(true)
-    if (!access) return Promise.resolve(false)
-    const key = privilegeKey(privilege)
-    if (!answers.has(key)) answers.set(key, access(privilege).catch(() => false))
-    return answers.get(key)!
+  const passes = (door: string): Promise<boolean> => {
+    if (!answers.has(door)) answers.set(door, access!(door).catch(() => false))
+    return answers.get(door)!
+  }
+
+  const mayUse = async (spec: ToolSpec): Promise<boolean> => {
+    /*
+     * Said nothing. Not open — left out, and the boot report names it. An answer this tool built
+     * would be readable by no one (ADR-0073), so offering it would only produce dead answers.
+     */
+    if (!Array.isArray(spec.doors)) return false
+    /* Reaches no door: it hands back what the surface itself sent. There is nothing to gate. */
+    if (spec.doors.length === 0) return true
+    if (!access) return false
+
+    const held = await Promise.all(spec.doors.map(passes))
+    return held.every(Boolean)
   }
 
   const categories: ScopedCategory[] = []

package/server/service/tool-registry/index.ts

@@ -23,7 +23,6 @@ export type { ToolCategoryFilter, ToolRegistryWarning } from './registry'
 export type {
   ToolSpec,
   ToolSpecBase,
-  ToolPrivilege,
   ReadToolSpec,
   WriteToolSpec,
   ActionToolSpec,

package/server/service/tool-registry/registry.test.ts

@@ -34,8 +34,6 @@ function makeCategory(name: string, specs: Partial<ToolSpec>[]): ToolCategory {
       description: 'desc',
       schema: {},
       builder: () => ({}),
-      /* A tool that changes something must name its door (A1). The fixture does, like guidance. */
-      ...(s.kind && s.kind !== 'read' ? { privilege: { category: 'fixture', privilege: 'mutation' } } : {}),
       ...s
     })) as ToolSpec[]
   }
@@ -176,7 +174,7 @@ describe('registry — spec 보존', () => {
           kind: 'write',
           name: 't1',
           description: 'main desc',
-          privilege: { category: 'fixture', privilege: 'mutation' },
+          doors: ['Mutation.t1'],
           themeNote: '⚠ note',
           schema: { type: 'object' },
           builder: () => null
@@ -262,89 +260,59 @@ describe('registry — 지침 없는 카테고리는 등록되지 않는다', ()
   })
 })
 
-describe('registry — a tool that changes something names its door (A1, stage one: surface)', () => {
-  test.each(['write', 'action', 'external'] as const)(
-    '★ a %s tool without a privilege registers, and the omission is recorded as a code',
-    kind => {
-      registerToolCategory({
-        name: 'no-door',
-        guidance: '- fixture guidance for no-door',
-        specs: [{ kind, name: 'changesThings', description: 'd', schema: {}, builder: () => null } as any]
-      })
-      expect(getToolKind('changesThings')).toBe(kind)
-      expect(getToolRegistryWarnings()).toEqual([
-        expect.objectContaining({
-          code: 'tool-privilege-undeclared',
-          params: { category: 'no-door', tool: 'changesThings', kind }
-        })
-      ])
-    }
-  )
-
-  test('a privilege with no privilege name is recorded the same way', () => {
+describe('registry — a tool names the doors it reaches (ADR-0071 decision 2)', () => {
+  /*
+   * 문을 안 적은 도구는 그 답을 **아무도 못 읽게 만든다** — 쓴 사람 본인까지.
+   *
+   * ADR-0073 뒤로 답 행에 도구가 지난 문이 적히고, 선언이 없는 도구는 `unresolved:<도구>` 로 적혀
+   * 아무도 못 지난다. 2026-09-18 트윈 모델러에서 저작 대화의 답이 새로 고친 뒤 작성자에게
+   * 「이 답을 볼 권한이 없습니다」로 보였다. 2026-09-18 부터는 관문도 그 도구를 내보내지 않는다 —
+   * 이 목록이 「무엇이 빠져 있나」를 말하는 유일한 자리다.
+   */
+  test.each(['read', 'write', 'action', 'external'] as const)('★ a %s tool that declares no doors is reported by name', kind => {
     registerToolCategory({
-      name: 'half-door',
-      guidance: '- fixture guidance for half-door',
-      specs: [
-        { kind: 'external', name: 'halfDoor', description: 'd', schema: {}, builder: () => null, privilege: { category: 'board' } } as any
-      ]
+      name: 'no-door',
+      guidance: '- fixture guidance for no-door',
+      specs: [{ kind, name: 'reachesSomething', description: 'd', schema: {}, builder: () => null } as any]
     })
-    expect(getToolRegistryWarnings().map(w => w.params.tool)).toEqual(['halfDoor'])
-  })
 
-  test('a declared tool leaves no warning', () => {
-    registerToolCategory(makeCategory('declared', [{ name: 'w1', kind: 'write' }]))
-    expect(getToolRegistryWarnings()).toEqual([])
+    expect(getToolKind('reachesSomething')).toBe(kind)
+    expect(getToolRegistryWarnings()).toEqual([
+      expect.objectContaining({
+        code: 'tool-doors-undeclared',
+        params: { category: 'no-door', tool: 'reachesSomething', kind }
+      })
+    ])
   })
 
-  /*
-   * 읽는 도구도 자기가 닿는 문을 말한다(ADR-0071 결정 2). 그전까지 업무 권한을 스스로 확인하는 것은
-   * plant 뿐이었고, twin · figure 의 읽는 도구는 테넌트만 봤다 — 대화 문 권한만 있으면 그 자료를 읽었다.
-   */
-  test('★ a read tool that says nothing about its door is recorded too', () => {
-    registerToolCategory(makeCategory('reads', [{ name: 'r1', kind: 'read' }]))
+  test('★ `doors: []` is a declaration — it says this tool reaches none', () => {
+    registerToolCategory(makeCategory('surface', [{ name: 'getOpenScene', kind: 'read', doors: [] }]))
 
-    expect(getToolRegistryWarnings()).toEqual([
-      expect.objectContaining({ code: 'tool-privilege-undeclared', params: { category: 'reads', tool: 'r1', kind: 'read' } })
-    ])
+    expect(getToolRegistryWarnings()).toEqual([])
   })
 
-  test('★ `doors: []` is an answer — a tool that reaches no door has nothing to gate', () => {
-    registerToolCategory({
-      name: 'surface-only',
-      guidance: '- fixture guidance for surface-only',
-      specs: [
-        { kind: 'read', name: 'getOpenScene', description: 'd', schema: {}, builder: () => null, doors: [] } as any
-      ]
-    })
+  test('a named door leaves no warning — what that door requires is asked at boot, not here', () => {
+    registerToolCategory(makeCategory('waiting', [{ name: 'twinNowTool', kind: 'read', doors: ['Query.twinNow'] }]))
 
     expect(getToolRegistryWarnings()).toEqual([])
   })
 
-  test('★ a named door with no privilege of its own is its own fact, not an omission', () => {
-    registerToolCategory({
-      name: 'waiting',
-      guidance: '- fixture guidance for waiting',
-      specs: [
-        { kind: 'read', name: 'twinNowTool', description: 'd', schema: {}, builder: () => null, doors: ['Query.twinNow'] } as any
-      ]
-    })
+  test('the message says what to write, so the person reading it does not have to look it up', () => {
+    registerToolCategory(makeCategory('no-door', [{ name: 'silent', kind: 'read' }]))
 
-    expect(getToolRegistryWarnings()).toEqual([
-      expect.objectContaining({
-        code: 'tool-door-has-no-privilege',
-        params: { category: 'waiting', tool: 'twinNowTool', kind: 'read', doors: ['Query.twinNow'] }
-      })
-    ])
+    expect(getToolRegistryWarnings()[0].message).toMatch(/doors: \[\]/)
   })
 
   test('re-registering a category replaces its warnings instead of piling them up', () => {
     const undeclared = { kind: 'write', name: 'w9', description: 'd', schema: {}, builder: () => null } as any
     registerToolCategory({ name: 'again', guidance: '- g', specs: [undeclared] })
+    const once = getToolRegistryWarnings().map(w => w.code).sort()
+
     registerToolCategory({ name: 'again', guidance: '- g', specs: [undeclared] })
-    expect(getToolRegistryWarnings()).toHaveLength(1)
+    /* 두 번 등록해도 한 번 등록한 것과 같아야 한다 — 축이 몇이든. */
+    expect(getToolRegistryWarnings().map(w => w.code).sort()).toEqual(once)
 
-    registerToolCategory({ name: 'again', guidance: '- g', specs: [{ ...undeclared, privilege: { category: 'c', privilege: 'mutation' } }] })
+    registerToolCategory({ name: 'again', guidance: '- g', specs: [{ ...undeclared, doors: [] }] })
     expect(getToolRegistryWarnings()).toEqual([])
   })
 })