@things-factory/ai-assistant 10.1.28 → 10.1.31

package/server/service/chat-message/fold-history-window.test.ts

@@ -0,0 +1,184 @@
+/*
+ * ★ 요약 접기는 **필요한 만큼만 읽는다** — 그러면서 앞부분을 잃지 않는다.
+ *
+ * ── 무엇을 겪었나 (2026-08-20) ──────────────────────────────────────────────
+ * `_foldHistorySummary` 는 **메시지를 보낼 때마다** 그 세션의 대화를 처음부터 끝까지 읽었다
+ * (`creator` 조인까지). 정작 쓰는 것은 두 조각뿐이다: 마지막 `maxTurns`개와, 요약 워터마크
+ * 뒤부터의 미반영분. 대화가 2,000개면 매 메시지마다 2,000행을 읽어 수십 행을 쓴 셈이다.
+ *
+ * 같은 종류의 결함을 트윈 쪽에서 먼저 잡았다(`timeRange` — min/max 두 수를 구하려고 저널 27만
+ * 행을 4초마다 읽었다). 사람 리뷰가 그것을 못 잡은 이유는 **코드가 맞았기 때문**이다. 여기도 같다:
+ * 답은 맞고 비용만 틀렸다. 그래서 이 시험은 답과 함께 **어디까지 읽어야 하는가**를 못 박는다.
+ *
+ * ── 지키는 것 ───────────────────────────────────────────────────────────────
+ * ① 창으로 읽어 왔으면 밀려난 것이 곧 미반영분이다 — 워터마크로 또 자르지 않는다.
+ * ② 전체를 읽어 왔으면 워터마크로 자른다 — 이미 요약에 담은 것을 두 번 담지 않는다.
+ * ③ 두 경로가 **같은 답**을 낸다. 읽는 범위를 바꾼 것이 요약 내용을 바꾸면 안 된다.
+ * ④ 워터마크 행이 사라졌으면 전부 미반영으로 본다 — 빠뜨리는 쪽보다 다시 요약하는 쪽이 안전하다.
+ *
+ * ── 왜 여기로 왔나 (2026-09-18) ────────────────────────────────────────────
+ * 요약 접기를 `board-ai` 에서 이 꾸러미로 옮기면서(`4257583d1b`) 이 시험만 board-ai 에 남았다. 읽는
+ * 파일이 사라졌으니 board-ai 의 `npm test` 가 그날부터 실패했다 — 옮긴 사람이 시험을 두고 온 것이다.
+ * 여기 오면서 `dist-server` 를 거치지 않고 소스를 바로 읽는다.
+ */
+
+import { foldHistorySummary } from './fold-history'
+import { pendingForSummary, splitByCap } from './history-summary'
+
+const MAX_TURNS = 5
+const THRESHOLD = 3
+
+/** 메시지 n개 — id 는 `m1`.. 로 두어 어디까지 담겼는지 눈으로 읽을 수 있게 한다. */
+const rows = (n: number, from = 1) =>
+  Array.from({ length: n }, (_, i) => ({
+    id: `m${from + i}`,
+    role: (from + i) % 2 ? 'user' : 'assistant',
+    content: `말 ${from + i}`
+  }))
+
+/** 요약기를 가로채 **무엇이 요약 대상이 됐는지** 본다. 이것이 이 시험의 핵심 관측점이다. */
+function capturing() {
+  const seen: string[] = []
+  return {
+    seen,
+    summarize: async (content: string) => {
+      seen.push(content)
+      return '요약'
+    }
+  }
+}
+
+it('창으로 읽어 왔으면 밀려난 것이 곧 미반영분이다 — 워터마크로 또 자르지 않는다', async () => {
+  /* m1..m9 가 창(요약 뒤부터)이다. 마지막 5개는 원문 유지, 앞 4개가 새로 밀려났다. */
+  const cap = capturing()
+  const r = await foldHistorySummary({
+    rows: rows(9),
+    rowsStartAfterSummary: true,
+    stored: { text: '앞선 요약', upToMessageId: 'm0-요약에-담긴-것' },
+    maxTurns: MAX_TURNS,
+    threshold: THRESHOLD,
+    summarize: cap.summarize
+  })
+
+  expect(r.patch).toBeTruthy() // '4개가 밀려났고 임계치 3 이상이므로 접는다'
+  expect(r.patch!.summaryUpToMessageId).toBe('m4') // '밀려난 마지막까지 담았다고 기록한다'
+  expect(cap.seen[0]).toMatch(/말 1/) // '창의 첫 메시지가 요약에 들어간다'
+  expect(cap.seen[0]).toMatch(/말 4/)
+  expect(cap.seen[0]).not.toMatch(/말 5/) // '유지분은 원문으로 남으므로 요약에 넣지 않는다'
+  expect(cap.seen[0]).toMatch(/앞선 요약/) // '앞선 요약에 이어 붙인다 — 앞부분을 잃지 않는다'
+})
+
+it('전체를 읽어 왔으면 워터마크로 자른다 — 이미 담은 것을 두 번 담지 않는다', async () => {
+  /* m1..m14 전체. m5 까지 요약에 담겼다 → 미반영분은 m6..m9(마지막 5개는 유지분). */
+  const cap = capturing()
+  const r = await foldHistorySummary({
+    rows: rows(14),
+    stored: { text: '앞선 요약', upToMessageId: 'm5' },
+    maxTurns: MAX_TURNS,
+    threshold: THRESHOLD,
+    summarize: cap.summarize
+  })
+
+  expect(r.patch).toBeTruthy()
+  expect(r.patch!.summaryUpToMessageId).toBe('m9')
+  /* m5 는 이미 요약에 담겼다 — 두 번 담지 않는다. */
+  expect(cap.seen[0]).not.toMatch(/말 5(?!\d)/)
+  expect(cap.seen[0]).toMatch(/말 6/)
+  expect(cap.seen[0]).toMatch(/말 9/)
+})
+
+it('읽는 범위를 바꿔도 요약 대상은 같다 — 성능을 바꾼 것이 내용을 바꾸지 않는다', async () => {
+  /*
+   * 같은 상황을 두 방식으로 읽는다. 전체는 m1..m14 이고 m5 까지 요약됨. 창은 그 뒤인 m6..m14.
+   * 둘의 요약 대상이 다르면, 이 최적화가 사실을 옮긴 것이다.
+   */
+  const whole = capturing()
+  const windowed = capturing()
+
+  const a = await foldHistorySummary({
+    rows: rows(14),
+    stored: { text: '앞선 요약', upToMessageId: 'm5' },
+    maxTurns: MAX_TURNS,
+    threshold: THRESHOLD,
+    summarize: whole.summarize
+  })
+  const b = await foldHistorySummary({
+    rows: rows(9, 6),
+    rowsStartAfterSummary: true,
+    stored: { text: '앞선 요약', upToMessageId: 'm5' },
+    maxTurns: MAX_TURNS,
+    threshold: THRESHOLD,
+    summarize: windowed.summarize
+  })
+
+  expect(whole.seen[0]).toBe(windowed.seen[0]) // '요약에 들어가는 글이 글자까지 같다'
+  expect(a.patch).toEqual(b.patch) // '기록하는 워터마크도 같다'
+})
+
+it('워터마크 행이 사라졌으면 전부 미반영으로 본다 — 빠뜨리지 않는다', () => {
+  /* 삭제·편집으로 그 id 가 이력에 없을 수 있다. 그때 덮은 범위를 알 수 없으므로 전부 다시 본다. */
+  const { dropped } = splitByCap(rows(14), MAX_TURNS)
+  const pending = pendingForSummary(dropped, { text: '앞선 요약', upToMessageId: '지워진-id' })
+
+  expect(pending.length).toBe(dropped.length) // '전부 미반영'
+  expect(pending[0].id).toBe('m1')
+})
+
+it('창이 유지분보다 짧으면 접지 않는다 — 새로 밀려난 것이 없다', async () => {
+  const cap = capturing()
+  const r = await foldHistorySummary({
+    rows: rows(MAX_TURNS),
+    rowsStartAfterSummary: true,
+    stored: { text: '앞선 요약', upToMessageId: 'm0' },
+    maxTurns: MAX_TURNS,
+    threshold: THRESHOLD,
+    summarize: cap.summarize
+  })
+
+  expect(r.patch).toBe(null)
+  expect(r.skipped).toBe('nothing-dropped')
+  expect(cap.seen.length).toBe(0) // 'LLM 을 부르지 않는다'
+})
+
+it('밀려난 것이 임계치 미만이면 접지 않는다 — 매 턴 요약하지 않는다', async () => {
+  const cap = capturing()
+  const r = await foldHistorySummary({
+    rows: rows(MAX_TURNS + THRESHOLD - 1),
+    rowsStartAfterSummary: true,
+    stored: { text: '앞선 요약', upToMessageId: 'm0' },
+    maxTurns: MAX_TURNS,
+    threshold: THRESHOLD,
+    summarize: cap.summarize
+  })
+
+  expect(r.skipped).toBe('below-threshold')
+  expect(cap.seen.length).toBe(0)
+})
+
+/*
+ * ★ 위 ① 을 **가르는** 자리.
+ *
+ * 앞의 「창으로 읽어 왔으면…」 시험은 워터마크 id 가 창에 없는 값이라(`m0-요약에-담긴-것`), 두 갈래가
+ * 같은 답을 낸다 — 워터마크가 안 보이면 전부 미반영으로 보는 규칙 ④ 때문이다. 그래서 창 갈래를 통째로
+ * 지워도 그 시험은 초록이었다(2026-09-18, 옮겨 온 뒤 결함을 심어 보고 알았다).
+ *
+ * 둘이 갈리는 것은 **워터마크 id 가 창 안에 보일 때**다. 그때 맞는 답은 창 쪽이다 — 창은 이미 요약
+ * 뒤부터이므로, 그 안에 같은 id 가 보여도 그것은 아직 요약에 안 담긴 말이다.
+ */
+it('★ 워터마크 id 가 창 안에 보여도 창은 워터마크로 자르지 않는다 — 여기서 두 갈래가 갈린다', async () => {
+  const cap = capturing()
+
+  const r = await foldHistorySummary({
+    rows: rows(9),
+    rowsStartAfterSummary: true,
+    stored: { text: '앞선 요약', upToMessageId: 'm2' },
+    maxTurns: MAX_TURNS,
+    threshold: THRESHOLD,
+    summarize: cap.summarize
+  })
+
+  expect(r.patch).toBeTruthy()
+  /* 창 갈래: m1..m4 가 전부 미반영이다. 전체 갈래였다면 m3..m4 만 담고 m1 · m2 를 잃는다. */
+  expect(cap.seen[0]).toMatch(/말 1/)
+  expect(cap.seen[0]).toMatch(/말 2/)
+})

package/server/service/chat-message/reader-gate.ts

@@ -5,8 +5,7 @@
  * 세션이 private 인지도 여기서 함께 답한다. 리졸버마다 같은 판정을 다시 적으면 한 곳이 빠진 날
  * 그 문으로 샌다.
  */
-import { getAllToolSpecs } from '@things-factory/ai-client-base'
-import { User } from '@things-factory/auth-base'
+import { checkPermission, privilegeOfField } from '@things-factory/auth-base'
 
 import { doorCheck } from './door-access.js'
 import { doorGate, redactByDoors, type DoorReadableRow } from './message-doors.js'
@@ -17,10 +16,13 @@ export function readerGate(context: any): <T extends DoorReadableRow>(rows: read
   const { domain, user } = context.state
   const t = requestTranslator(context)
 
+  const { unsafeIP, prohibitedPrivileges } = context.state
+
   const gate = doorGate(
+    /* 문에서 쓰는 판정을 그대로 쓴다 — 같은 인자, 같은 함수(ADR-0072 결정 5). */
     doorCheck({
-      specs: getAllToolSpecs(),
-      hasPrivilege: privilege => User.hasPrivilege(privilege.privilege, privilege.category, domain, user)
+      lookup: privilegeOfField,
+      permits: fieldGate => checkPermission(fieldGate as any, user, domain, unsafeIP, prohibitedPrivileges)
     })
   )
 

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

@@ -125,6 +125,21 @@ export class ChatSession {
   @Field({ nullable: true, description: 'Timestamp of the last message in this session (denormalized for list ordering and unread comparison — avoids per-session aggregation across the supported DB drivers).' })
   lastMessageAt?: Date
 
+  /**
+   * 어느 대화인가 — `twin.board` · `figure.catalog` 같은 모드의 kind (ADR-0072 결정 3).
+   *
+   * **서버가 적는다.** 클라이언트가 보내는 값이 아니다 — 등록된 모드에서 나온 것만 적힌다(`addressee`
+   * 와 같은 결). 한 대상 위에 대화가 둘 설 수 있게 되면서(A17), 세션이 자기가 어느 대화인지 알아야
+   * 한다. 몰랐을 때 화면에서 이렇게 나왔다: 모드를 바꿔도 같은 세션이 그대로 남아, 「도형 찾기」로
+   * 바꾼 뒤 보낸 말이 앞의 고치기 대화에 붙었다(2026-09-18, Figure 레인 :3300).
+   *
+   * 값이 없는 세션은 이 칸이 서기 전에 난 것이다. 다음 턴에 요청한 kind 로 한 번 찍고, 찍힌 뒤에는
+   * 「요청한 모드와 다르면 거절」 하나만 남는다. 마이그레이션은 만들지 않는다.
+   */
+  @Column({ type: 'varchar', length: 64, nullable: true })
+  @Field({ nullable: true, description: "Which conversation this session is — the registered mode kind. Written by the server, never sent by the client." })
+  kind?: string
+
   /**
    * 이 대화를 도메인 안 누구나 읽는가 — ADR-0073 판정 2.
    *

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

@@ -101,8 +101,17 @@ export function anchorColumns(
  * 여기서도 앵커 이름을 검사한다 — 읽기 경로에서 틀린 이름은 오류가 아니라 **0 행**으로 나오고,
  * 화면은 「대화가 없다」로 그린다. 그 증상으로는 원인을 못 찾는다.
  */
-export function anchorWhere(domainId: string, anchorType: string, anchorId: string): any {
+/**
+ * 이 앵커의 세션을 찾는 조건 — `kind` 를 주면 **그 대화의** 세션만 본다(ADR-0072 결정 3).
+ *
+ * 한 대상 위에 대화가 둘 설 수 있게 되면서(A17), 앵커만으로 찾으면 저작 대화를 찾는 자리에서 운영
+ * 대화가 잡힌다. figure 에서 그것이 화면으로 나왔다 — 모드를 바꿨는데 같은 세션이 그대로 남아 새 말이
+ * 앞 대화에 붙었다(2026-09-18, Figure 레인 :3300).
+ *
+ * `kind` 를 안 주면 앵커의 대화를 모두 본다 — 목록처럼 대화를 가리지 않고 훑는 자리다.
+ */
+export function anchorWhere(domainId: string, anchorType: string, anchorId: string, kind?: string): any {
   const type = assertAnchorType(anchorType, 'anchorWhere')
-  if (type === 'board') return { boardId: anchorId, domain: { id: domainId } }
-  return { anchorType: type, anchorId, domain: { id: domainId } }
+  const where = type === 'board' ? { boardId: anchorId, domain: { id: domainId } } : { anchorType: type, anchorId, domain: { id: domainId } }
+  return kind ? { ...where, kind } : where
 }

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

@@ -19,6 +19,8 @@
 export interface InboxSessionRow {
   id?: string
   name?: string
+  /** 어느 대화인가 — 목록이 대화를 가리지 않으므로, 고른 뒤 화면이 따라갈 수 있게 함께 낸다. */
+  kind?: string
   anchorType?: string
   anchorId?: string
   boardId?: string

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

@@ -0,0 +1,24 @@
+/*
+ * ADR-0072 결정 3 — 세션이 자기 대화를 알고, 다른 대화의 말을 받지 않는다.
+ */
+import { judgeSessionKind } from './session-kind'
+
+describe('session kind', () => {
+  it('같은 대화면 그대로 간다', () => {
+    expect(judgeSessionKind('figure.modeller', 'figure.modeller')).toEqual({ action: 'proceed' })
+  })
+
+  it('★ 칸이 서기 전 세션은 요청한 대화로 한 번 찍는다 — 마이그레이션을 만들지 않는다', () => {
+    expect(judgeSessionKind(null, 'figure.catalog')).toEqual({ action: 'stamp', kind: 'figure.catalog' })
+    expect(judgeSessionKind('', 'figure.catalog')).toEqual({ action: 'stamp', kind: 'figure.catalog' })
+    expect(judgeSessionKind('   ', 'figure.catalog')).toEqual({ action: 'stamp', kind: 'figure.catalog' })
+  })
+
+  it('★ 다른 대화의 세션은 거절한다 — 조용히 섞으면 그 이력이 남의 프롬프트로 들어간다', () => {
+    expect(judgeSessionKind('figure.modeller', 'figure.catalog')).toEqual({
+      action: 'refuse',
+      errorCode: 'session-kind-mismatch',
+      params: { sessionKind: 'figure.modeller', requested: 'figure.catalog' }
+    })
+  })
+})

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

@@ -0,0 +1,32 @@
+/*
+ * 이 세션이 어느 대화인가 — ADR-0072 결정 3.
+ *
+ * 한 대상 위에 대화가 둘 설 수 있게 되면서(A17), 세션이 자기가 어느 대화인지 알아야 한다. 모르면 모드를
+ * 바꿔도 같은 세션이 그대로 남고, 새 말이 앞 대화에 붙는다 — 화면에서는 줄이 사라져 새 대화처럼 보이니
+ * 보낸 사람은 그것을 알 수 없다. 새로 고쳐야 드러난다(2026-09-18, Figure 레인 :3300).
+ *
+ * 답은 셋이다.
+ *   `proceed`  세션의 대화와 요청한 대화가 같다.
+ *   `stamp`    칸이 서기 전에 난 세션이다 — 요청한 대화로 한 번 찍고 진행한다. 찍힌 뒤에는 아래 하나만
+ *              남는다. 마이그레이션은 만들지 않는다.
+ *   `refuse`   다른 대화의 세션이다. **조용히 섞지 않는다** — 섞으면 그 대화의 이력이 다른 대화의
+ *              프롬프트로 들어가고, 읽는 사람은 자기가 무엇에 답하고 있는지 모른다.
+ */
+
+export type SessionKindVerdict =
+  | { action: 'proceed' }
+  | { action: 'stamp'; kind: string }
+  | { action: 'refuse'; errorCode: 'session-kind-mismatch'; params: { sessionKind: string; requested: string } }
+
+export function judgeSessionKind(sessionKind: string | null | undefined, requested: string): SessionKindVerdict {
+  const stored = (sessionKind ?? '').trim()
+
+  if (!stored) return { action: 'stamp', kind: requested }
+  if (stored === requested) return { action: 'proceed' }
+
+  return {
+    action: 'refuse',
+    errorCode: 'session-kind-mismatch',
+    params: { sessionKind: stored, requested }
+  }
+}

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

@@ -34,3 +34,19 @@ describe('session visibility', () => {
     expect(mayReadSession(undefined, false)).toBe(true)
   })
 })
+
+/*
+ * ADR-0073 결정 2 — 대상 없는 개인 질문은 공개 방으로 태어나지 않는다.
+ *
+ * `'none'` 은 저장되는 앵커 종류 목록에 든 글자다(대상이 없다는 것도 행에 적어야 하므로). 「값이 있으면
+ * 앵커가 있다」로 읽으면 그 글자가 앵커 노릇을 하고, `twin.none` 대화가 도메인 안 누구에게나 열린다.
+ */
+describe("'none' is not an anchor", () => {
+  it('★ 대상 없는 대화는 비공개로 시작한다 — 앵커 종류 목록에 그 글자가 있어도', () => {
+    expect(initialVisibility({ anchorType: 'none' })).toBe('private')
+  })
+
+  it('대상이 있는 대화는 그대로 공개다', () => {
+    expect(initialVisibility({ anchorType: 'space' })).toBe('open')
+  })
+})

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

@@ -17,7 +17,15 @@ export const SESSION_VISIBILITIES: readonly SessionVisibility[] = ['open', 'priv
  */
 export function initialVisibility(session: { anchorType?: string | null; copyOf?: string | null }): SessionVisibility {
   if (session.copyOf) return 'private'
-  return session.anchorType ? 'open' : 'private'
+
+  /*
+   * `'none'` 은 **앵커가 아니다.** 저장되는 앵커 종류 목록에 그 글자가 들어 있어서(`session-anchor.ts`
+   * — 대상이 없다는 것도 행에 적어야 하므로), 「값이 있으면 앵커가 있다」로 읽으면 대상 없는 개인 질문이
+   * 공개 방으로 태어난다. ADR-0073 결정 2 가 그것을 `private` 로 못박았다 — 「앵커 없는 세션(`twin.none`
+   * 같은 개인 질문)」.
+   */
+  const anchored = !!session.anchorType && session.anchorType !== 'none'
+  return anchored ? 'open' : 'private'
 }
 
 /** 이 사람이 이 대화를 읽을 수 있나. open 이면 도메인 안 누구나, private 이면 참여자만. */

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

@@ -55,6 +55,10 @@ class ChatSessionInboxEntry {
   @Field({ nullable: true, description: 'User-given session name (tab label).' })
   name?: string
 
+  /** 어느 대화인가 — 목록에서 고른 것이 지금 열린 대화와 다르면 화면이 그 대화로 따라간다. */
+  @Field({ nullable: true, description: 'Which conversation this session is — the registered mode kind.' })
+  kind?: string
+
   @Field({ nullable: true, description: "What the session is anchored to: 'board' | 'space' | 'instance' | 'none'." })
   anchorType?: string
 

package/server/service/index.ts

@@ -24,6 +24,8 @@ export * from './grounding-sources.js'
 export * from './subscribe-auth.js'
 /* 앵커 순수 로직 — 호스트가 앵커 종류를 참조한다(리졸버는 데코레이터 때문에 무겁다). */
 export * from './chat-session/session-anchor.js'
+/* Who may read a conversation — one rule, also asked by doors outside this package (board-ai's revertPatch). */
+export * from './chat-session/session-visibility.js'
 export * from './chat-session/index.js'
 /* 순수 로직들 — 호스트(board-ai 등)가 같은 규칙을 쓰라고 공개한다. 베끼면 한쪽만 고쳐진다. */
 export * from './chat-session/session-inbox.js'

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

@@ -22,10 +22,11 @@ beforeEach(() => {
     name: 'twin-ops',
     guidance: 'call summarizeStatus before describing the line',
     specs: [
-      { kind: 'read', name: 'summarizeStatus', description: 'read the line', schema: {}, builder: async () => ({ line: 3, stopped: true }) },
+      { kind: 'read', name: 'summarizeStatus', doors: ['Query.twinReplay'], description: 'read the line', schema: {}, builder: async () => ({ line: 3, stopped: true }) },
       {
         kind: 'read',
         name: 'proposeAction',
+        doors: ['Query.twinReplay'],
         description: 'propose stopping the line',
         schema: {},
         builder: async () => ({ proposed: true, command: 'stop', instanceId: 'LINE-3', label: '3 라인 정지' })

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

@@ -16,8 +16,8 @@ beforeEach(() => {
     name: 'twin-ops',
     guidance: 'call summarizeStatus before describing the line',
     specs: [
-      { kind: 'read', name: 'summarizeStatus', description: 'read the line', schema: {}, builder: async () => ({ stopped: true }) },
-      { kind: 'write', name: 'stopLine', description: 'stop the line', schema: {}, builder: async () => ({ ok: true }) }
+      { kind: 'read', name: 'summarizeStatus', doors: ['Query.twinReplay'], description: 'read the line', schema: {}, builder: async () => ({ stopped: true }) },
+      { kind: 'write', name: 'stopLine', doors: ['Mutation.twinCommand'], description: 'stop the line', schema: {}, builder: async () => ({ ok: true }) }
     ]
   } as any)
 })
@@ -101,6 +101,8 @@ it('★ a proposal belongs to the turn that asked for it', async () => {
       {
         kind: 'read',
         name: 'proposeSceneEdit',
+        /* 저작 도구는 열린 씬만 본다 — 저장소에 닿지 않으므로 문이 없다. */
+        doors: [],
         description: 'propose placing a component',
         schema: {},
         builder: async () => ({ proposed: true, kind: 'scene-edit', label: 'place EQ-1', ops: [] })

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

@@ -131,6 +131,13 @@ export interface ConversationOptions {
   systemPrompt?: string
   /** Which registered categories this conversation may use. Omitted allows none. */
   toolCategories?: string[]
+  /**
+   * Which doors this script's speaker may pass (ADR-0071 decision 2). A tool is offered when the
+   * caller passes every door it names, so a script that says nothing here is written as someone who
+   * passes them all — the permission axis belongs to `tool-access`, not to a conversation script.
+   * Name the doors to write the other case: a person the tool is not offered to.
+   */
+  toolAccess?: (door: string) => Promise<boolean>
   /** Request state the tools receive (domain, user). */
   state?: any
   /** What the surface is looking at — reaches tools as `ctx.host`, never the model. */
@@ -263,6 +270,7 @@ export function conversation(options: ConversationOptions = {}) {
           messages: buildLlmHistory(rows, {}) as any,
           systemPrompt: options.systemPrompt ?? 'you are a test assistant',
           toolCategories: options.toolCategories,
+          toolAccess: options.toolAccess ?? (async () => true),
           hostContext: options.hostContext,
           state: options.state ?? { domain: { id: 'dom-1' }, user: { id: 'u-1' } },
           requireToolOnFirstTurn: options.requireToolOnFirstTurn

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

@@ -66,6 +66,10 @@ export async function runRegisteredMode(
 
 export interface ModeWording {
   placeholder?: string
+  /** 빈 대화의 제목과 한 줄 — 없으면 공용 대화창이 보드 제품의 글을 낸다. */
+  intro?: { title: string; subtitle: string }
+  /** 빈 대화의 예시 — 이 대화가 실제로 할 수 있는 말. */
+  examples?: Array<{ label: string; items: string[] }>
   slash: { name: string; description: string; template: string }[]
   footerNotice?: string
   stagedNotice?: string
@@ -76,6 +80,8 @@ export function modeWording(kind: string, dictionary: Record<string, string>): M
   const view = assistantModeView(kind, key => dictionary[key] ?? key)
   return {
     placeholder: view.placeholder,
+    intro: view.intro,
+    examples: view.examples,
     slash: view.slashTemplates,
     footerNotice: view.footerNotice,
     stagedNotice: view.stagedNotice
@@ -91,6 +97,15 @@ export function missingWording(kind: string, dictionary: Record<string, string>)
   for (const key of [spec.placeholderKey, spec.footerNoticeKey, spec.stagedNoticeKey]) {
     if (key && !(key in dictionary)) missing.push(key)
   }
+  /* 빈 대화의 말도 사전에 있어야 한다 — 없으면 화면에 키가 그대로 찍힌다. */
+  for (const key of [spec.introKeys?.title, spec.introKeys?.subtitle]) {
+    if (key && !(key in dictionary)) missing.push(key)
+  }
+  for (const group of spec.exampleKeys ?? []) {
+    for (const key of [group.labelKey, ...group.itemKeys]) {
+      if (!(key in dictionary)) missing.push(key)
+    }
+  }
   for (const slash of spec.slashTemplates ?? []) {
     for (const key of [slash.descriptionKey, slash.templateKey]) {
       if (!(key in dictionary)) missing.push(key)

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

@@ -1,48 +1,96 @@
 /*
  * What this guards: a registered tool is asked the same question its GraphQL door asks.
  *
- * The tool declares `{ category, privilege }`; `@privilege` on the door runs `checkPermission`
+ * The tool names the door; AUTH's field table says what that door declares; `checkPermission` runs
  * with the request's user, domain, address safety and prohibited list. If this passed fewer of
  * those — say, dropped `unsafeIP` — the tool would be a softer way into the same door.
+ *
+ * `checkPermission` itself is fixed by auth-base's own tests (`permission-gate.test.ts`), including
+ * the two cases below: a domain owner passes a role-less door from a safe address, and from an
+ * unsafe one ownership counts for nothing and the role decides. What this file fixes is that the
+ * tool gate hands that function everything it needs to answer either way.
  */
 const mockCheckPermission = jest.fn()
-jest.mock('@things-factory/auth-base', () => ({ checkPermission: (...a: any[]) => mockCheckPermission(...a) }))
+const mockPrivilegeOfField = jest.fn()
+jest.mock('@things-factory/auth-base', () => ({
+  checkPermission: (...a: any[]) => mockCheckPermission(...a),
+  privilegeOfField: (...a: any[]) => mockPrivilegeOfField(...a)
+}))
 
 import { toolAccessFor } from './tool-access'
 
 const state = {
   domain: { id: 'dom-1' },
   user: { id: 'u-1' },
-  unsafeIP: true,
+  unsafeIP: false,
   prohibitedPrivileges: [{ category: 'board-import', privilege: 'mutation' }]
 }
 
-beforeEach(() => mockCheckPermission.mockReset())
+/** What plant's five doors declare — `@privilege(category, privilege, domainOwnerGranted: true)`. */
+const OWNER_GRANTED = { category: 'job-order', privilege: 'query', owner: true }
+
+beforeEach(() => {
+  mockCheckPermission.mockReset()
+  mockPrivilegeOfField.mockReset()
+  mockPrivilegeOfField.mockReturnValue({ known: true, gate: OWNER_GRANTED })
+})
 
-it('★ asks checkPermission with the declared privilege and everything the door would pass', async () => {
+it('★ asks checkPermission with the door’s own declaration and everything the door would pass', async () => {
   mockCheckPermission.mockResolvedValue(true)
 
-  const allowed = await toolAccessFor({ state })({ category: 'board-import', privilege: 'mutation', owner: true })
+  const allowed = await toolAccessFor({ state })('Query.jobOrders')
 
   expect(allowed).toBe(true)
-  expect(mockCheckPermission).toHaveBeenCalledWith(
-    { category: 'board-import', privilege: 'mutation', owner: true, super: undefined },
-    state.user,
-    state.domain,
-    true,
-    state.prohibitedPrivileges
-  )
+  expect(mockPrivilegeOfField).toHaveBeenCalledWith('Query', 'jobOrders')
+  expect(mockCheckPermission).toHaveBeenCalledWith(OWNER_GRANTED, state.user, state.domain, false, state.prohibitedPrivileges)
+})
+
+/*
+ * Plant's five doors are all `domainOwnerGranted: true`, so moving the gate onto the doors opens
+ * those five tools to a domain owner holding no privilege row. That is the right answer — the owner
+ * already sees the same numbers on the screen — and it is right only because the address travels
+ * with it. From an unsafe address ownership counts for nothing and the role decides.
+ */
+it('★ the owner-granted door gets the address too, so the answer can differ by where the caller sits', async () => {
+  mockCheckPermission.mockResolvedValue(true)
+  await toolAccessFor({ state })('Query.jobOrders')
+  expect(mockCheckPermission).toHaveBeenLastCalledWith(OWNER_GRANTED, state.user, state.domain, false, state.prohibitedPrivileges)
+
+  /* The same owner, the same door, an unsafe address: auth is asked again with that fact. */
+  mockCheckPermission.mockResolvedValue(false)
+  const fromUnsafe = await toolAccessFor({ state: { ...state, unsafeIP: true } })('Query.jobOrders')
+
+  expect(fromUnsafe).toBe(false)
+  expect(mockCheckPermission).toHaveBeenLastCalledWith(OWNER_GRANTED, state.user, state.domain, true, state.prohibitedPrivileges)
 })
 
 it('a refusal is a refusal', async () => {
   mockCheckPermission.mockResolvedValue(false)
-  expect(await toolAccessFor({ state })({ category: 'board-import', privilege: 'query' })).toBe(false)
+  expect(await toolAccessFor({ state })('Query.jobOrders')).toBe(false)
+})
+
+it('★ a door with no declaration of its own opens as far as that door opens — auth is not asked', async () => {
+  mockPrivilegeOfField.mockReturnValue({ known: true, gate: null })
+
+  expect(await toolAccessFor({ state })('Query.twinReplay')).toBe(true)
+  expect(mockCheckPermission).not.toHaveBeenCalled()
+})
+
+it('★ a door the schema does not have is closed, not open — a typo hides a tool, it does not free it', async () => {
+  mockPrivilegeOfField.mockReturnValue({ known: false })
+
+  expect(await toolAccessFor({ state })('Query.twinRepaly')).toBe(false)
+  expect(mockCheckPermission).not.toHaveBeenCalled()
+})
+
+it('a door name that is not a root field passes nobody', async () => {
+  expect(await toolAccessFor({ state })('jobOrders')).toBe(false)
+  expect(mockPrivilegeOfField).not.toHaveBeenCalled()
 })
 
-it('★ a request with no user or no domain holds no privilege, and auth is not asked', async () => {
-  const privilege = { category: 'board-import', privilege: 'query' }
-  expect(await toolAccessFor({ state: { domain: state.domain } })(privilege)).toBe(false)
-  expect(await toolAccessFor({ state: { user: state.user } })(privilege)).toBe(false)
-  expect(await toolAccessFor(undefined)(privilege)).toBe(false)
+it('★ a request with no user or no domain passes no door, and auth is not asked', async () => {
+  expect(await toolAccessFor({ state: { domain: state.domain } })('Query.jobOrders')).toBe(false)
+  expect(await toolAccessFor({ state: { user: state.user } })('Query.jobOrders')).toBe(false)
+  expect(await toolAccessFor(undefined)('Query.jobOrders')).toBe(false)
   expect(mockCheckPermission).not.toHaveBeenCalled()
 })

package/server/service/tool-access.ts

@@ -2,26 +2,35 @@
  * Who may use a registered tool — the request's answer to `ToolAccessCheck`.
  *
  * `ai-client-base` decides *which* tools a conversation may use but does not know auth, so the
- * conversation doors hand it this. A tool declares the same `{ category, privilege }` its GraphQL
- * door uses (A1, 2026-09-17), and this asks exactly what `@privilege` on that door would ask: the
- * same `checkPermission`, with the request's user, domain, address safety and prohibited list.
- * Asking anything looser here would make the tool a second, softer way into that door.
+ * conversation doors hand it this. A tool names the GraphQL doors it reaches (ADR-0071 decision 2);
+ * this resolves each one against AUTH's field table (`privilegeOfField`, ADR-0072 decision 5) and
+ * asks `checkPermission` exactly what `@privilege` on that field asks — the same user, domain,
+ * address safety and prohibited list. Asking anything looser here would make the tool a second,
+ * softer way into that door.
+ *
+ * **The declaration is the door's, and it is read, not copied.** Until 2026-09-18 a tool carried its
+ * own `{ category, privilege }` and this asked that copy. A copy drifts from the door it mirrors and
+ * the looser of the two wins; the table removed the need for one.
+ *
+ * The three answers of the table are read exactly as the reader's gate reads them (`door-access.ts`)
+ * — an unknown field closes, a field with no declaration opens as far as that field opens.
  */
-import { checkPermission } from '@things-factory/auth-base'
-import type { ToolAccessCheck, ToolPrivilege } from '@things-factory/ai-client-base'
+import { checkPermission, privilegeOfField } from '@things-factory/auth-base'
+import type { ToolAccessCheck } from '@things-factory/ai-client-base'
+
+import { doorCheck } from './chat-message/door-access.js'
 
 export function toolAccessFor(context: { state?: any } | undefined): ToolAccessCheck {
   const { domain, user, unsafeIP, prohibitedPrivileges } = context?.state ?? {}
 
-  return async (privilege: ToolPrivilege) => {
-    /* No caller, no answer — a request without a user or domain holds no privilege. */
+  const passes = doorCheck({
+    lookup: privilegeOfField,
+    permits: gate => checkPermission(gate as any, user, domain, unsafeIP, prohibitedPrivileges)
+  })
+
+  return async (door: string) => {
+    /* No caller, no answer — a request without a user or domain passes no door. */
     if (!user || !domain) return false
-    return !!(await checkPermission(
-      { category: privilege.category, privilege: privilege.privilege, owner: privilege.owner, super: privilege.super },
-      user,
-      domain,
-      unsafeIP,
-      prohibitedPrivileges
-    ))
+    return await passes(door)
   }
 }