@things-factory/ai-assistant 10.1.28 → 10.1.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-assistant",
-  "version": "10.1.28",
+  "version": "10.1.31",
   "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.28",
-    "@things-factory/auth-base": "^10.1.28",
+    "@things-factory/ai-client-base": "^10.1.31",
+    "@things-factory/auth-base": "^10.1.31",
     "@things-factory/env": "^10.1.20",
-    "@things-factory/shell": "^10.1.28",
+    "@things-factory/shell": "^10.1.31",
     "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": "3a260a0f79bc6b41a692a103955bfcc541aff60e"
+  "gitHead": "5213e6f9913b40ea2618a2111d9884b792dbaa01"
 }

package/server/door-declaration-report.test.ts

@@ -0,0 +1,53 @@
+/*
+ * 도구가 적어 둔 문이 스키마에 있는가 — ADR-0072 결정 5 의 표로 묻는다.
+ *
+ * 오타 하나가 조용하다. ADR-0073 판정 1 은 모르는 문을 닫으므로, 이름을 틀리게 적은 도구로 만든 답은
+ * **아무도 못 읽는다** — 쓴 사람까지. 부팅이 그것을 말하지 않으면 화면에서 처음 본다.
+ */
+import { doorDeclarationWarnings, formatDoorDeclarationWarnings } from './door-declaration-report'
+
+const table: Record<string, any> = {
+  'Query.jobOrders': { known: true, gate: { category: 'job-order', privilege: 'query', owner: false, super: false } },
+  'Query.twinExternalAttentions': { known: true, gate: null }
+}
+const lookup = (typeName: string, fieldName: string) => table[`${typeName}.${fieldName}`] ?? { known: false }
+
+describe('declared doors, measured against the schema', () => {
+  it('★ 스키마에 없는 문은 말한다 — 오타 하나가 그 대화의 답을 통째로 가린다', () => {
+    const found = doorDeclarationWarnings([{ name: 'findJobOrders', doors: ['Query.jobOrder'] }], lookup)
+
+    expect(found).toEqual([{ code: 'tool-door-not-in-schema', tool: 'findJobOrders', door: 'Query.jobOrder' }])
+  })
+
+  it('★ 선언이 없는 문은 사실로 말한다 — 그 문이 열려 있으니 답도 열린다', () => {
+    const found = doorDeclarationWarnings(
+      [{ name: 'listExternalAttentions', doors: ['Query.twinExternalAttentions'] }],
+      lookup
+    )
+
+    expect(found.map(w => w.code)).toEqual(['tool-door-has-no-privilege'])
+  })
+
+  it('지키는 문에는 아무 말도 하지 않는다', () => {
+    expect(doorDeclarationWarnings([{ name: 'findJobOrders', doors: ['Query.jobOrders'] }], lookup)).toEqual([])
+  })
+
+  it('문을 안 적은 도구는 이 검사의 것이 아니다 — 등록기가 따로 말한다', () => {
+    expect(doorDeclarationWarnings([{ name: 'getOpenScene' }, { name: 'quiet', doors: [] }], lookup)).toEqual([])
+  })
+
+  it('★ 문 모양이 아닌 글자도 스키마에 없는 것으로 센다', () => {
+    const found = doorDeclarationWarnings([{ name: 'odd', doors: ['jobOrders'] }], lookup)
+
+    expect(found.map(w => w.code)).toEqual(['tool-door-not-in-schema'])
+  })
+
+  it('코드마다 한 줄로 모은다', () => {
+    const lines = formatDoorDeclarationWarnings([
+      { code: 'tool-door-not-in-schema', tool: 'a', door: 'Query.x' },
+      { code: 'tool-door-not-in-schema', tool: 'b', door: 'Query.y' }
+    ])
+
+    expect(lines).toEqual(['[ai-assistant] tool-door-not-in-schema ×2: a → Query.x, b → Query.y'])
+  })
+})

package/server/door-declaration-report.ts

@@ -0,0 +1,61 @@
+/*
+ * 도구가 적어 둔 문이 **스키마에 있는 문인가** — 부팅에서 한 번 묻는다.
+ *
+ * ── 왜 등록기가 아니라 여기인가 ───────────────────────────────────────────
+ * 이 물음은 AUTH 의 필드→권한 표(`privilegeOfField`, ADR-0072 결정 5)가 있어야 답할 수 있고, 그 표는
+ * **스키마를 지은 뒤에** 찬다. 등록기는 모듈이 올라오는 동안 도니 그때는 표가 비어 있다. 부팅 보고는
+ * 모든 모듈이 등록을 마치고 스키마가 선 뒤에 도는 자리다.
+ *
+ * ── 무엇을 가르나 ─────────────────────────────────────────────────────────
+ *   `tool-door-not-in-schema`    그런 루트 필드가 없다. 도구가 이름을 틀리게 적은 것이다 — 그 도구로
+ *                                만든 답은 **아무도 못 읽는다**(ADR-0073 판정 1 은 모르는 문을 닫는다).
+ *                                오타 하나가 그 대화의 답을 통째로 가린다.
+ *   `tool-door-has-no-privilege` 필드는 있고 아무것도 선언하지 않았다. 그 문이 열려 있으므로 그 답도
+ *                                도메인 안에서 열린다. 결함이 아니라 **사실**이고, 문의 차례다.
+ *
+ * 등록기의 같은 이름 경고와 묻는 것이 다르다. 등록기는 「도구가 문의 권한을 베껴 적었나」를 물었고,
+ * 그 베끼기는 표가 서면서 없어진다(ADR-0072 결정 5). 여기서는 **문에 직접** 묻는다.
+ */
+import { getAllToolSpecs } from '@things-factory/ai-client-base'
+import { privilegeOfField } from '@things-factory/auth-base'
+
+export interface DoorDeclarationWarning {
+  code: 'tool-door-not-in-schema' | 'tool-door-has-no-privilege'
+  tool: string
+  door: string
+}
+
+/** 등록된 도구들이 적어 둔 문을 스키마에 대어 본다. 스키마가 선 뒤에만 뜻이 있다. */
+export function doorDeclarationWarnings(
+  specs: ReadonlyArray<any> = getAllToolSpecs(),
+  lookup: (typeName: string, fieldName: string) => { known: false } | { known: true; gate: unknown } = privilegeOfField
+): DoorDeclarationWarning[] {
+  const out: DoorDeclarationWarning[] = []
+
+  for (const spec of specs) {
+    for (const door of spec?.doors ?? []) {
+      const match = /^(Query|Mutation|Subscription)\.([A-Za-z_][A-Za-z0-9_]*)$/.exec(String(door))
+      if (!match) {
+        out.push({ code: 'tool-door-not-in-schema', tool: spec.name, door: String(door) })
+        continue
+      }
+
+      const asked = lookup(match[1], match[2])
+      if (!asked.known) out.push({ code: 'tool-door-not-in-schema', tool: spec.name, door })
+      else if (asked.gate === null) out.push({ code: 'tool-door-has-no-privilege', tool: spec.name, door })
+    }
+  }
+
+  return out
+}
+
+/** 코드마다 한 줄 — 몇이고 어느 도구의 어느 문인가. */
+export function formatDoorDeclarationWarnings(warnings: ReadonlyArray<DoorDeclarationWarning>): string[] {
+  const byCode = new Map<string, string[]>()
+  for (const warning of warnings) {
+    const found = byCode.get(warning.code) ?? []
+    found.push(`${warning.tool} → ${warning.door}`)
+    byCode.set(warning.code, found)
+  }
+  return [...byCode].map(([code, found]) => `[ai-assistant] ${code} ×${found.length}: ${found.join(', ')}`)
+}

package/server/service/assistant-chat-resolver.ts

@@ -49,6 +49,7 @@ import { activityPatch, autoSessionName } from './chat-session/session-inbox.js'
 import { toolAccessFor } from './tool-access.js'
 import { ChatSessionParticipant } from './chat-session-participant/chat-session-participant.js'
 import { doorsForAnswer } from './chat-message/message-doors.js'
+import { judgeSessionKind } from './chat-session/session-kind.js'
 import { readerGate } from './chat-message/reader-gate.js'
 import { inviteMentionedUsers } from './chat-session-participant/mention-invite.js'
 import { buildInviteNotification } from './chat-session-participant/invite-notification.js'
@@ -238,6 +239,24 @@ export class AssistantChatResolver {
           })
         )
       }
+      /*
+       * 이 세션이 **이 대화의** 세션인가 — ADR-0072 결정 3. 다른 대화의 세션에 말을 붙이면 그 이력이
+       * 이 대화의 프롬프트로 들어가고, 화면은 줄이 사라져 새 대화처럼 보이므로 보낸 사람은 모른다.
+       */
+      const verdict = judgeSessionKind((found as any).kind, input.mode.kind)
+      if (verdict.action === 'refuse') {
+        throw new Error(
+          t('ai-assistant.text.session-kind-mismatch', {
+            ...verdict.params,
+            defaultValue: 'this conversation is {sessionKind}, and you are writing as {requested}. open the conversation you mean.'
+          })
+        )
+      }
+      if (verdict.action === 'stamp') {
+        /* 칸이 서기 전에 난 세션 — 요청한 대화로 한 번 찍는다. 다음부터는 위 규칙 하나만 남는다. */
+        await sessionRepo.update(found.id!, { kind: verdict.kind } as any)
+        ;(found as any).kind = verdict.kind
+      }
       session = found
     }
 
@@ -389,6 +408,8 @@ export class AssistantChatResolver {
       messages: conversation as any,
       systemPrompt: settings.systemPrompt,
       toolCategories: settings.toolCategories,
+      /* 도구가 「어느 대화에서 불렸나」를 안다 — 서버의 값이다(ADR-0061 결정 3). */
+      mode: { kind: input.mode.kind, ...(input.mode.target ? { target: input.mode.target } : {}) },
       toolAccess: toolAccessFor(context),
       /* The stop notice is a sentence a person reads — the server writes it in their language (ADR-0054). */
       t,

package/server/service/assistant-mode/assistant-mode-resolver.ts

@@ -44,6 +44,12 @@ class AssistantModeView {
   @Field({ nullable: true, description: 'What the empty input says — what this conversation is for.' })
   placeholder?: string
 
+  @Field(() => GraphQLJSON, { nullable: true, description: 'Title and one line for an empty conversation.' })
+  intro?: { title: string; subtitle: string }
+
+  @Field(() => GraphQLJSON, { nullable: true, description: 'Example sentences this conversation can actually answer.' })
+  examples?: Array<{ label: string; items: string[] }>
+
   @Field({ nullable: true, description: 'The line under an empty conversation.' })
   footerNotice?: string
 

package/server/service/assistant-mode/index.ts

@@ -1,7 +1,7 @@
 /**
  * Modes — what each conversation is, declared by the app server that owns the screen.
  *
- * Design: ADR-0061 decision 7 (`operato-twin/design/04-decisions.md`) and the AI standard's A2.
+ * Design: ADR-0061 decision 7 (`operato-application/adr/ADR-0061.md`) and the AI standard's A2.
  */
 export {
   registerAssistantMode,

package/server/service/assistant-mode/resolve.test.ts

@@ -76,3 +76,45 @@ it('a mode that declares no wording gets empty lists, not undefined holes', () =
   expect(view.catalogEntries).toEqual([])
   expect(view.footerNotice).toBeUndefined()
 })
+
+/*
+ * 빈 대화가 무엇을 말하는가 — ADR-0061 결정 7.
+ *
+ * 자리표와 `/` 는 대화를 따라가는데 이 블록만 host 속성에 남아 있었다. 그래서 머리에는 「이 도형
+ * 고치기」가 서 있고 본문은 「만들 Figure 를 설명하세요」라고 적혀 있었다(2026-09-18, :3300).
+ */
+describe('the empty conversation says what this conversation is', () => {
+  it('★ 대화가 자기 제목과 한 줄을 갖고, 서버가 요청의 말로 옮겨 낸다', () => {
+    clearAssistantModes()
+    registerAssistantMode({
+      kind: 'figure.modeller',
+      systemPrompt: 'you edit the open figure',
+      introKeys: { title: 'figure.text.revise-title', subtitle: 'figure.text.revise-subtitle' }
+    })
+
+    expect(assistantModeView('figure.modeller', t).intro).toEqual({
+      title: 't(figure.text.revise-title)',
+      subtitle: 't(figure.text.revise-subtitle)'
+    })
+  })
+
+  it('★ 예시도 대화를 따라간다 — 이 대화가 못 하는 말을 예시로 두면 빈 화면이 거짓을 가르친다', () => {
+    clearAssistantModes()
+    registerAssistantMode({
+      kind: 'figure.modeller',
+      systemPrompt: 'you edit the open figure',
+      exampleKeys: [{ labelKey: 'figure.label.revise', itemKeys: ['figure.text.ex-revise', 'figure.text.ex-inspect'] }]
+    })
+
+    expect(assistantModeView('figure.modeller', t).examples).toEqual([
+      { label: 't(figure.label.revise)', items: ['t(figure.text.ex-revise)', 't(figure.text.ex-inspect)'] }
+    ])
+  })
+
+  it('선언이 없으면 안 낸다 — host 가 주던 글이 그대로 선다', () => {
+    const view = assistantModeView('twin.space', t)
+
+    expect(view.intro).toBeUndefined()
+    expect(view.examples).toBeUndefined()
+  })
+})

package/server/service/assistant-mode/resolve.ts

@@ -71,6 +71,10 @@ export interface AssistantModeView {
   catalogEntries: any[]
   proposalChoices: any[]
   placeholder?: string
+  /** 빈 대화의 제목과 한 줄 — 이 대화가 무엇을 하는 자리인지. */
+  intro?: { title: string; subtitle: string }
+  /** 빈 대화의 예시 — 이 대화에서 실제로 할 수 있는 말. */
+  examples?: Array<{ label: string; items: string[] }>
   footerNotice?: string
   stagedNotice?: string
 }
@@ -90,6 +94,11 @@ export function assistantModeView(kind: string, t: Translate): AssistantModeView
     catalogEntries: mode.catalogEntries ?? [],
     proposalChoices: mode.proposalChoices ?? [],
     placeholder: mode.placeholderKey ? t(mode.placeholderKey) : undefined,
+    intro: mode.introKeys ? { title: t(mode.introKeys.title), subtitle: t(mode.introKeys.subtitle) } : undefined,
+    examples: mode.exampleKeys?.map(group => ({
+      label: t(group.labelKey),
+      items: group.itemKeys.map(key => t(key))
+    })),
     footerNotice: mode.footerNoticeKey ? t(mode.footerNoticeKey) : undefined,
     stagedNotice: mode.stagedNoticeKey ? t(mode.stagedNoticeKey) : undefined
   }

package/server/service/assistant-mode/types.ts

@@ -76,6 +76,24 @@ export interface AssistantModeSpec {
    * "describe the figure you want" while the person was there to change the figure already open.
    */
   placeholderKey?: string
+
+  /**
+   * 빈 대화가 무엇을 말하는가 — 제목과 한 줄 (ADR-0061 결정 7).
+   *
+   * 자리표와 `/` 는 대화를 따라가는데 이 블록만 host 속성에 남아 있었다. 그래서 머리에는 「이 도형
+   * 고치기」가 서 있고 본문은 「만들 Figure 를 설명하세요」라고 적혀 있었다(2026-09-18, Figure 레인
+   * :3300). 한 대화가 화면에 무엇을 말하는가는 한 자리에서 나와야 한다.
+   */
+  introKeys?: { title: string; subtitle: string }
+
+  /**
+   * 빈 대화의 예시 — 「이 대화에서 할 수 있는 말」.
+   *
+   * 예시는 그 도구로 **실제로 할 수 있는 말**이어야 한다. 할 수 없는 것을 예시로 두면 빈 화면이 거짓을
+   * 가르친다. 대화마다 열리는 도구가 다르므로 예시도 대화를 따라간다.
+   */
+  exampleKeys?: Array<{ labelKey: string; itemKeys: string[] }>
+
   /** i18n key for the line under an empty conversation. */
   footerNoticeKey?: string
   /** i18n key for the line shown once the host reports a proposal staged. */

package/server/service/chat-message/carried-turns.test.ts

@@ -34,8 +34,19 @@ it("'ai' is the same as 'assistant' — the same rule applies to both spellings"
   expect(planCarriedTurns([{ role: 'ai', content: '답' }])[0].role).toBe('system')
 })
 
-it('an unknown role is a system row, and empty content is dropped', () => {
-  expect(planCarriedTurns([{ role: 'note', content: '메모' }])[0]).toEqual({ role: 'system', content: '메모' })
+/*
+ * ADR-0070 결정 ③ — 이 문은 사람의 말과 어시스턴트의 답만 옮긴다.
+ *
+ * 2026-09-18 까지는 그 밖의 역할을 `system` 행으로 그대로 적었다. 모델은 `[system]` 을 사람의 말보다
+ * 무겁게 읽으므로, 클라이언트가 「이것은 시스템이 한 말」이라고 적을 수 있었다 — 역할은 서버가 쓴다는
+ * 결정이 그 자리에서 무너진다. 사람이 친 것이 아닌 맥락은 `appendSessionNote` 가 자리다.
+ */
+it('★ 클라이언트가 지어낸 역할은 거절한다 — `system` 은 서버가 쓰는 자리다', () => {
+  expect(() => planCarriedTurns([{ role: 'note', content: '메모' }])).toThrow(/appendSessionNote/)
+  expect(() => planCarriedTurns([{ role: 'system', content: '화면에서 승격함' }])).toThrow(/cannot be carried/)
+})
+
+it('빈 내용은 조용히 빠진다 — 옮길 말이 없는 줄이다', () => {
   expect(planCarriedTurns([{ role: 'user', content: '   ' }])).toEqual([])
 })
 

package/server/service/chat-message/carried-turns.ts

@@ -46,7 +46,22 @@ export function planCarriedTurns(turns: CarriedTurn[]): PlannedRow[] {
     const content = (turn?.content ?? '').trim().slice(0, CARRIED_CONTENT_LIMIT)
     if (!content) continue
 
-    const role = turn?.role === 'ai' || turn?.role === 'assistant' ? 'assistant' : turn?.role === 'user' ? 'user' : 'system'
+    /*
+     * 이 문은 **사람의 말과 어시스턴트의 답**만 옮긴다(ADR-0070 결정 ③). 그 밖의 역할은 받지 않는다 —
+     * `system` 행은 서버가 쓰는 자리이고, 모델은 그 줄을 사람의 말보다 무겁게 읽는다. 클라이언트가
+     * 「이것은 시스템이 한 말」이라고 적을 수 있으면 역할을 서버가 쓴다는 결정이 무너진다.
+     *
+     * 사람이 친 것이 아닌 맥락은 `appendSessionNote` 가 자리다 — 그 문은 서버가 `system` 으로 적는다.
+     */
+    const asked = turn?.role === 'ai' ? 'assistant' : turn?.role
+    if (asked !== 'assistant' && asked !== 'user') {
+      throw new Error(
+        `[ai-assistant/carried-turns] role '${String(turn?.role)}' cannot be carried. This door carries what ` +
+          "people said and what the assistant answered. Context that nobody typed goes through `appendSessionNote`, " +
+          'which writes the system row itself.'
+      )
+    }
+    const role = asked
 
     if (role === 'user') {
       planned.push({ role: 'user', content, addressee: 'room' })
@@ -65,8 +80,6 @@ export function planCarriedTurns(turns: CarriedTurn[]): PlannedRow[] {
       }
       continue
     }
-
-    planned.push({ role: 'system', content })
   }
 
   return planned.slice(-CARRIED_TURN_LIMIT)

package/server/service/chat-message/door-access.test.ts

@@ -0,0 +1,72 @@
+/*
+ * ADR-0072 결정 5 — 문이 묻는 것을 AUTH 의 표에서 읽는다.
+ *
+ * 표가 주는 답은 셋이고 서로 다르다. 가운데 하나만 열림이다 — 나머지 둘을 열림으로 읽으면 못 볼 값이
+ * 나간다. 그리고 「없는 필드」를 열림으로 읽는 것이 가장 하기 쉬운 잘못이다: 도구가 문 이름을 틀리게
+ * 적었을 때 검사가 붙는 대신 조용히 빠진다.
+ */
+import { doorCheck, doorField, isKnownDoor, type FieldLookup } from './door-access'
+
+const table: Record<string, any> = {
+  'Query.open': { known: true, gate: null },
+  'Query.guarded': { known: true, gate: { category: 'job-order', privilege: 'query', owner: false, super: false } }
+}
+const lookup: FieldLookup = (typeName, fieldName) => table[`${typeName}.${fieldName}`] ?? { known: false }
+
+describe('door access', () => {
+  it('★ 선언이 없는 필드는 열려 있다 — 그 문으로 아무나 읽으므로 이 행도 읽는다', async () => {
+    const check = doorCheck({ lookup, permits: async () => false })
+
+    expect(await check('Query.open')).toBe(true)
+  })
+
+  it('★ 없는 필드는 닫는다 — 도구가 이름을 틀리게 적은 것이지 열린 문이 아니다', async () => {
+    const check = doorCheck({ lookup, permits: async () => true })
+
+    expect(await check('Query.doesNotExist')).toBe(false)
+  })
+
+  it('★ 선언이 있는 필드는 AUTH 에게 묻는다 — 여기서 규칙을 다시 쓰지 않는다', async () => {
+    const asked: any[] = []
+    const check = doorCheck({
+      lookup,
+      permits: async gate => {
+        asked.push(gate)
+        return false
+      }
+    })
+
+    expect(await check('Query.guarded')).toBe(false)
+    expect(asked).toEqual([{ category: 'job-order', privilege: 'query', owner: false, super: false }])
+  })
+
+  it('AUTH 가 통과시키면 지난다', async () => {
+    expect(await doorCheck({ lookup, permits: async () => true })('Query.guarded')).toBe(true)
+  })
+
+  it('★ 문 모양이 아니면 아무도 못 지난다 — 표를 묻지도 않는다', async () => {
+    const asked: string[] = []
+    const watching: FieldLookup = (typeName, fieldName) => {
+      asked.push(`${typeName}.${fieldName}`)
+      return { known: false }
+    }
+    const check = doorCheck({ lookup: watching, permits: async () => true })
+
+    for (const bad of ['jobOrders', 'Query.', 'Query.a.b', '', 'unresolved:getStationScreen']) {
+      expect(await check(bad)).toBe(false)
+    }
+    expect(asked).toEqual([])
+  })
+
+  it('문 이름을 타입과 필드로 가른다', () => {
+    expect(doorField('Mutation.proposeFigure')).toEqual({ typeName: 'Mutation', fieldName: 'proposeFigure' })
+    expect(doorField('Subscription.chatMessageActivity')?.typeName).toBe('Subscription')
+    expect(doorField('Query.a.b')).toBeUndefined()
+  })
+
+  it('스키마에 있는 문인지 따로 답한다 — 부팅 보고가 이것으로 틀린 선언을 말한다', () => {
+    expect(isKnownDoor('Query.open', lookup)).toBe(true)
+    expect(isKnownDoor('Query.guarded', lookup)).toBe(true)
+    expect(isKnownDoor('Query.doesNotExist', lookup)).toBe(false)
+  })
+})

package/server/service/chat-message/door-access.ts

@@ -1,33 +1,49 @@
 /*
  * 문 → 그 문을 지키는 권한 — ADR-0073 판정 1 의 관문을 세우는 자리.
  *
- * ── 왜 도구 등록기에서 찾나 ───────────────────────────────────────────────
+ * ── 정본은 AUTH 의 표다 ───────────────────────────────────────────────────
  * 행에 적힌 것은 문 이름(`Query.jobOrders`)이고, 사람이 가진 것은 권한(`job-order:query`)이다. 둘을
- * 잇는 정본은 AUTH 의 필드→권한 표이고, 그 표는 아직 없다(ADR-0072 결정 2 (b) — 수석 아키텍트가 청하기로
- * 되어 있다). 그때까지는 도구 명세가 이미 들고 있는 짝을 쓴다: 그 문에 닿는다고 선언한 도구가 자기
- * 권한도 함께 적어 두었다.
+ * 잇는 것은 `privilegeOfField(typeName, fieldName)` 이다(ADR-0072 결정 5). 스키마를 지을 때 모든 루트
+ * 필드가 기록되므로, 이 표는 **그 문이 실제로 무엇을 묻는지**를 그대로 답한다.
  *
- * **이것은 사본이다.** 표가 서면 `doorPrivilege` 하나만 그 표를 보게 바꾸고 나머지는 그대로 둔다.
+ * 그 전에는 도구 명세가 들고 있는 짝을 베껴 썼다. 베낀 값은 문이 선언을 바꾸면 조용히 어긋나고,
+ * 어긋나면 느슨한 쪽이 이긴다. 표가 서면서 그 사본을 걷었다.
  *
- * ── 모르는 문은 닫는다 ────────────────────────────────────────────────────
- * 어느 도구도 그 문을 선언하지 않았으면 무엇이 그 문을 지키는지 알 수 없다. 모를 때 열면, 도구가 사라진
- * 뒤에 남은 옛 답이 전부 공개된다 — 지우는 일이 여는 일이 된다. 닫는 쪽으로 넘어뜨린다.
+ * ── 판정하지 않고 AUTH 에게 묻는다 ────────────────────────────────────────
+ * 표가 주는 gate 는 `checkPermission` 이 받는 넷(category · privilege · owner · super)과 같은 모양이고,
+ * 그대로 `checkPermission` 에 넘긴다. 여기서 「category 가 없으면 소유권만 본다」 같은 규칙을 다시 쓰면
+ * 그 순간 AUTH 와 이 파일이 두 벌이 된다. 문에서 통하는 것이 여기서도 통해야 한다.
+ *
+ * ── 셋 중 둘은 닫는다 ─────────────────────────────────────────────────────
+ *   `{ known: false }`          그런 루트 필드가 없다. 도구가 문 이름을 틀리게 적은 것이다 —
+ *                               **열림으로 읽지 않는다.** 부팅 보고가 따로 말한다.
+ *   `{ known: true, gate: null }`  필드는 있고 선언이 없다. 그 문은 열려 있으므로 이 행도 열린다.
+ *   `{ known: true, gate }`     그 문이 묻는 것을 이 사람이 가졌는지 AUTH 에게 묻는다.
+ *
+ * 스키마를 짓기 전에는 표가 비어 있어 모든 문이 `known: false` 로 답한다 — 가려지는 쪽이다.
  */
-import type { ToolPrivilege, ToolSpec } from '@things-factory/ai-client-base'
+import type { FieldGate } from '@things-factory/auth-base'
 
-/** 이 문을 지키는 권한 — 그 문에 닿는다고 선언한 도구에서 가져온다. */
-export function doorPrivilege(door: string, specs: readonly ToolSpec[]): ToolPrivilege | undefined {
-  for (const spec of specs) {
-    if (((spec as any).doors ?? []).includes(door)) return (spec as any).privilege
-  }
-  return undefined
-}
+/** `privilegeOfField` 와 같은 모양 — 이 파일은 표를 **읽기만** 하고 어디서 오는지는 모른다. */
+export type FieldLookup = (typeName: string, fieldName: string) => { known: false } | { known: true; gate: FieldGate | null }
 
 export interface DoorCheckDeps {
-  /** 등록된 도구 명세 전부 — 문→권한을 찾는 표 노릇. */
-  specs: readonly ToolSpec[]
-  /** AUTH 조회. `User.hasPrivilege` 를 그대로 싸서 넘긴다. */
-  hasPrivilege(privilege: ToolPrivilege): Promise<boolean>
+  /** AUTH 의 필드→권한 표. 운영에서는 `privilegeOfField` 가 들어온다(`reader-gate.ts`). */
+  lookup: FieldLookup
+  /** `checkPermission` 을 그대로 싸서 넘긴다 — 판정은 AUTH 가 한다. */
+  permits(gate: FieldGate): Promise<boolean>
+}
+
+/** `Query.jobOrders` 를 타입과 필드로 가른다. 모양이 아니면 undefined — 아무도 못 지난다. */
+export function doorField(door: string): { typeName: string; fieldName: string } | undefined {
+  const match = /^(Query|Mutation|Subscription)\.([A-Za-z_][A-Za-z0-9_]*)$/.exec(door ?? '')
+  return match ? { typeName: match[1], fieldName: match[2] } : undefined
+}
+
+/** 이 문이 스키마에 있는가 — 없으면 선언이 틀린 것이고, 부팅 보고가 그것을 말한다. */
+export function isKnownDoor(door: string, lookup: FieldLookup): boolean {
+  const field = doorField(door)
+  return !!field && lookup(field.typeName, field.fieldName).known
 }
 
 /**
@@ -37,9 +53,13 @@ export interface DoorCheckDeps {
  */
 export function doorCheck(deps: DoorCheckDeps): (door: string) => Promise<boolean> {
   return async (door: string) => {
-    const privilege = doorPrivilege(door, deps.specs)
-    if (!privilege) return false
+    const field = doorField(door)
+    if (!field) return false
+
+    const asked = deps.lookup(field.typeName, field.fieldName)
+    if (!asked.known) return false
+    if (asked.gate === null) return true
 
-    return await deps.hasPrivilege(privilege)
+    return await deps.permits(asked.gate)
   }
 }