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

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

@@ -23,6 +23,16 @@ afterEach(() => {
 })
 
 // 헬퍼 — 카테고리 fixture
+/**
+ * 권한 축의 경고만 — 문 축(`tool-doors-undeclared`)은 자기 시험이 따로 본다.
+ *
+ * 한 시험이 두 축을 함께 세면, 한 축에 코드가 하나 늘 때마다 다른 축의 시험이 빨개진다. 그러면 고치는
+ * 사람은 자기가 건드리지 않은 시험을 고치게 되고, 그 손질이 시험을 무디게 만든다.
+ */
+function privilegeWarnings() {
+  return getToolRegistryWarnings().filter(w => w.code !== 'tool-doors-undeclared')
+}
+
 function makeCategory(name: string, specs: Partial<ToolSpec>[]): ToolCategory {
   return {
     name,
@@ -272,7 +282,7 @@ describe('registry — a tool that changes something names its door (A1, stage o
         specs: [{ kind, name: 'changesThings', description: 'd', schema: {}, builder: () => null } as any]
       })
       expect(getToolKind('changesThings')).toBe(kind)
-      expect(getToolRegistryWarnings()).toEqual([
+      expect(privilegeWarnings()).toEqual([
         expect.objectContaining({
           code: 'tool-privilege-undeclared',
           params: { category: 'no-door', tool: 'changesThings', kind }
@@ -289,12 +299,12 @@ describe('registry — a tool that changes something names its door (A1, stage o
         { kind: 'external', name: 'halfDoor', description: 'd', schema: {}, builder: () => null, privilege: { category: 'board' } } as any
       ]
     })
-    expect(getToolRegistryWarnings().map(w => w.params.tool)).toEqual(['halfDoor'])
+    expect(privilegeWarnings().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(privilegeWarnings()).toEqual([])
   })
 
   /*
@@ -304,7 +314,7 @@ describe('registry — a tool that changes something names its door (A1, stage o
   test('★ a read tool that says nothing about its door is recorded too', () => {
     registerToolCategory(makeCategory('reads', [{ name: 'r1', kind: 'read' }]))
 
-    expect(getToolRegistryWarnings()).toEqual([
+    expect(privilegeWarnings()).toEqual([
       expect.objectContaining({ code: 'tool-privilege-undeclared', params: { category: 'reads', tool: 'r1', kind: 'read' } })
     ])
   })
@@ -318,7 +328,7 @@ describe('registry — a tool that changes something names its door (A1, stage o
       ]
     })
 
-    expect(getToolRegistryWarnings()).toEqual([])
+    expect(privilegeWarnings()).toEqual([])
   })
 
   test('★ a named door with no privilege of its own is its own fact, not an omission', () => {
@@ -330,7 +340,7 @@ describe('registry — a tool that changes something names its door (A1, stage o
       ]
     })
 
-    expect(getToolRegistryWarnings()).toEqual([
+    expect(privilegeWarnings()).toEqual([
       expect.objectContaining({
         code: 'tool-door-has-no-privilege',
         params: { category: 'waiting', tool: 'twinNowTool', kind: 'read', doors: ['Query.twinNow'] }
@@ -338,13 +348,43 @@ describe('registry — a tool that changes something names its door (A1, stage o
     ])
   })
 
+  /*
+   * 문을 안 적은 도구는 그 답을 **아무도 못 읽게 만든다** — 쓴 사람 본인까지.
+   *
+   * ADR-0073 뒤로 답 행에 도구가 지난 문이 적히고, 선언이 없는 도구는 `unresolved:<도구>` 로 적혀
+   * 아무도 못 지난다. 2026-09-18 트윈 모델러에서 저작 대화의 답이 새로 고친 뒤 작성자에게
+   * 「이 답을 볼 권한이 없습니다」로 보였다.
+   *
+   * 부팅은 그때 아무 말도 안 했다. 권한 검사가 `privilege` 가 있으면 건너뛰는 자리에서 문 검사까지
+   * 함께 건너뛰었기 때문이다 — 트윈의 저작 도구 넷이 정확히 그 모양이었다(권한 있음, 문 없음).
+   */
+  test('★ a tool that declares no doors is reported even when it declares a privilege', () => {
+    registerToolCategory(
+      makeCategory('authoring', [
+        { name: 'proposeSceneEdit', kind: 'write', privilege: { category: 'board', privilege: 'mutation' } }
+      ])
+    )
+
+    const doors = getToolRegistryWarnings().filter(w => w.code === 'tool-doors-undeclared')
+    expect(doors.map(w => w.params.tool)).toEqual(['proposeSceneEdit'])
+  })
+
+  test('★ `doors: []` is a declaration — it says this tool reaches none', () => {
+    registerToolCategory(makeCategory('surface', [{ name: 'getOpenScene', kind: 'read', doors: [] }]))
+
+    expect(getToolRegistryWarnings().filter(w => w.code === 'tool-doors-undeclared')).toEqual([])
+  })
+
   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' } }] })
-    expect(getToolRegistryWarnings()).toEqual([])
+    expect(privilegeWarnings()).toEqual([])
   })
 })

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

@@ -37,7 +37,7 @@ export interface ToolRegistryWarning {
    *   (twin's queries, waiting on AUTH stage two). The tool cannot be stricter than its door, so
    *   this is a different fact from saying nothing, and the report keeps the two apart.
    */
-  code: 'tool-privilege-undeclared' | 'tool-door-has-no-privilege'
+  code: 'tool-privilege-undeclared' | 'tool-door-has-no-privilege' | 'tool-doors-undeclared'
   params: { category: string; tool: string; kind: ToolSpec['kind']; doors?: string[] }
   /** For a person reading it; the code and params are what callers act on. */
   message: string
@@ -95,6 +95,30 @@ export function registerToolCategory(category: ToolCategory): void {
    * is empty across the apps, this becomes a refusal.
    */
   warnings.splice(0, warnings.length, ...warnings.filter(w => w.params.category !== category.name))
+
+  /*
+   * ── 문을 안 적은 도구는 그 답을 **아무도 못 읽게 만든다** ─────────────────
+   *
+   * ADR-0073 뒤로 어시스턴트의 답 행에는 그 답을 만든 도구들이 지난 문이 적힌다. 선언이 없는 도구는
+   * `unresolved:<도구>` 로 적히고 그 이름은 아무도 못 지난다 — **답을 쓴 본인도** 새로 고치면
+   * 「이 답을 볼 권한이 없습니다」를 본다. 2026-09-18 트윈 모델러에서 그렇게 나왔다.
+   *
+   * 이 검사를 권한 검사와 따로 도는 이유가 그것이다. 아래 고리는 `privilege` 가 있으면 건너뛰는데,
+   * 문을 안 적은 해는 권한을 적었는지와 상관이 없다. 트윈의 저작 도구 넷이 정확히 그 자리였다 —
+   * 권한은 있고 문은 없어서 부팅이 아무 말도 안 했다.
+   */
+  for (const spec of category.specs) {
+    if (Array.isArray(spec.doors)) continue
+
+    warnings.push({
+      code: 'tool-doors-undeclared',
+      params: { category: category.name, tool: spec.name, kind: spec.kind },
+      message:
+        `tool '${spec.name}' in category '${category.name}' declares no doors, so answers built with it ` +
+        'are hidden from every reader including their author — declare `doors`, or `doors: []` when it reaches none'
+    })
+  }
+
   for (const spec of category.specs) {
     const declared = Boolean(spec.privilege?.category && spec.privilege?.privilege)
     if (declared) continue
@@ -115,8 +139,9 @@ export function registerToolCategory(category: ToolCategory): void {
         code: 'tool-door-has-no-privilege',
         params: { category: category.name, tool: spec.name, kind: spec.kind, doors: spec.doors },
         message:
-          `tool '${spec.name}' reaches ${spec.doors.join(' + ')}, which declare no privilege — ` +
-          'the tool is as open as the doors it reaches until they declare one'
+          `tool '${spec.name}' reaches ${spec.doors.join(' + ')} and declares no privilege of its own — ` +
+          'whether those doors require anything is asked at boot, against the schema, not copied here ' +
+          '(ADR-0072 decision 5)'
       })
       continue
     }
@@ -125,8 +150,9 @@ export function registerToolCategory(category: ToolCategory): void {
       code: 'tool-privilege-undeclared',
       params: { category: category.name, tool: spec.name, kind: spec.kind },
       message:
-        `tool '${spec.name}' in category '${category.name}' says nothing about the doors it reaches — ` +
-        "declare `doors` with the same { category, privilege } those doors use, or `doors: []` when it reaches none"
+        `tool '${spec.name}' in category '${category.name}' declares no privilege of its own — ` +
+        'a tool that changes something says who may run it. What the doors it reaches require is a ' +
+        "separate question, answered at boot against the schema (`tool-door-not-in-schema`)."
     })
   }