@things-factory/ai-assistant 10.1.27 → 10.1.29

package/server/service/assistant-mode/subject-defaults.test.ts

@@ -0,0 +1,86 @@
+/*
+ * 화면이 무엇을 여는가 — ADR-0072 A17 ②.
+ *
+ * 한 subject 종류에 기본 대화가 없거나 둘이면 화면이 여는 대화는 부팅 순서가 정한다. 그것은 화면을
+ * 열어봐야 알 수 있고, 모듈 하나가 늘면 소리 없이 바뀐다. 부팅 보고가 말하게 하고, 여기서 셋 다
+ * 문다.
+ */
+import {
+  assistantModesForSubject,
+  clearAssistantModes,
+  getAssistantModeWarnings,
+  registerAssistantMode
+} from './registry'
+
+const persona = 'you are here'
+
+describe('assistant mode — subjects and defaults', () => {
+  beforeEach(() => clearAssistantModes())
+  afterAll(() => clearAssistantModes())
+
+  it('★ a subject nobody claims as default is a boot warning, not a silent pick', () => {
+    registerAssistantMode({ kind: 'twin.space', systemPrompt: persona, subjects: ['space'] })
+
+    const codes = getAssistantModeWarnings().map(w => w.code)
+    expect(codes).toContain('assistant-mode-subject-without-default')
+  })
+
+  it('★ two defaults on one subject is a boot warning — boot order must not decide it', () => {
+    registerAssistantMode({
+      kind: 'twin.space',
+      systemPrompt: persona,
+      subjects: ['board'],
+      defaultFor: ['board'],
+      labelKey: 'a'
+    })
+    registerAssistantMode({
+      kind: 'twin.authoring',
+      systemPrompt: persona,
+      subjects: ['board'],
+      defaultFor: ['board'],
+      labelKey: 'b'
+    })
+
+    const twice = getAssistantModeWarnings().find(w => w.code === 'assistant-mode-subject-default-twice')
+    expect(twice?.params.kinds).toEqual(['twin.space', 'twin.authoring'])
+  })
+
+  it('★ a conversation offered beside another needs something to call it', () => {
+    registerAssistantMode({
+      kind: 'twin.space',
+      systemPrompt: persona,
+      subjects: ['board'],
+      defaultFor: ['board'],
+      labelKey: 'twin.ai.mode.space'
+    })
+    registerAssistantMode({ kind: 'twin.authoring', systemPrompt: persona, subjects: ['board'] })
+
+    const unnamed = getAssistantModeWarnings().find(w => w.code === 'assistant-mode-offered-without-label')
+    expect(unnamed?.params.kind).toBe('twin.authoring')
+  })
+
+  it('one conversation alone on its subject needs no label — there is nothing to choose between', () => {
+    registerAssistantMode({
+      kind: 'plant.station',
+      systemPrompt: persona,
+      subjects: ['station'],
+      defaultFor: ['station']
+    })
+
+    expect(getAssistantModeWarnings()).toEqual([])
+  })
+
+  it('the default comes first, so a screen can open the list head without knowing the rule', () => {
+    registerAssistantMode({ kind: 'twin.authoring', systemPrompt: persona, subjects: ['board'], labelKey: 'b' })
+    registerAssistantMode({
+      kind: 'twin.space',
+      systemPrompt: persona,
+      subjects: ['board'],
+      defaultFor: ['board'],
+      labelKey: 'a'
+    })
+
+    expect(assistantModesForSubject('board').map(m => m.kind)).toEqual(['twin.space', 'twin.authoring'])
+    expect(assistantModesForSubject('nothing-shows-this')).toEqual([])
+  })
+})

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

@@ -0,0 +1,121 @@
+/**
+ * What a conversation is, declared by the app server that owns the screen (ADR-0061 decision 7).
+ *
+ * ADR-0058 put these five in one value so they could not fall out of step, but the value lived in
+ * the browser and travelled on every request: the persona, the tool categories, the model and the
+ * limits were the caller's to choose. A caller choosing its own tool categories is a caller
+ * choosing its own authority, so the declaration moved here and the client sends only which one it
+ * is talking in (`kind`) and what about (`target`).
+ */
+
+/** A `/` sentence this mode offers, and what it needs to be answerable. */
+export interface AssistantModeSlash {
+  /** Short name shown in the list. */
+  name: string
+  /** i18n key for the one-line description. The server translates it into the request's locale. */
+  descriptionKey: string
+  /** i18n key for the sentence that lands in the input. */
+  templateKey: string
+  /**
+   * The tools this sentence needs. A mode must not offer work it cannot do (ADR-0058 decision 3),
+   * and a name outside `toolCategories` is reported at boot rather than when a person presses it.
+   */
+  tools?: string[]
+}
+
+export interface AssistantModeSpec {
+  /** `<app>.<surface>` — `twin.space`, `plant.station`, `figure.modeller`. */
+  kind: string
+
+  /**
+   * Which kinds of subject this conversation stands for — `['board', 'space']` (ADR-0072 A17 ①).
+   *
+   * A screen says what it is showing (`context.subject`), and these say which conversations that
+   * subject can carry. It is a list of types and not a predicate on purpose: a list can be counted
+   * at boot and pinned by a test, while a function can only be run.
+   *
+   * On the twin modeller nothing could be asked about operations, because an open board pinned the
+   * authoring conversation and that conversation opens one category. A conversation that also
+   * stands for `board` is how the same screen carries both.
+   */
+  subjects?: string[]
+
+  /**
+   * The conversation a screen opens when the person has not chosen — one per subject type
+   * (ADR-0072 A17 ②).
+   *
+   * Registration order must not decide this: whichever module booted last would silently become
+   * the default. Exactly one mode declares each subject type, and the boot report says so when a
+   * type has none or more than one.
+   */
+  defaultFor?: string[]
+
+  /**
+   * i18n key for what this conversation is called where a person chooses between them —
+   * "이 그림 고치기", "이 현장 지금 어때". A mode a screen may offer needs one.
+   */
+  labelKey?: string
+  /** Who the assistant is here, and what it must not claim to do. The server's, not the caller's. */
+  systemPrompt: string
+  /** Which tool categories this conversation may use. Absent or empty exposes none. */
+  toolCategories?: string[]
+  /** Make the model read before it answers — for surfaces whose subject is live state. */
+  requireToolOnFirstTurn?: boolean
+  /** Model and limits are policy, not a request field. */
+  model?: string
+  temperature?: number
+  maxTokens?: number
+  /** What `/` offers. Declared as keys; the server translates. */
+  slashTemplates?: AssistantModeSlash[]
+  /** What `@` offers. */
+  catalogEntries?: any[]
+  /**
+   * i18n key for the words in the empty input.
+   *
+   * The screen says what this conversation is for, and that differs by mode: figure's modeller had
+   * "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. */
+  stagedNoticeKey?: string
+  /** Follow-up chips for a proposal that arrived without its own. */
+  proposalChoices?: any[]
+}
+
+/** A declaration that registered but is not what the contract asks for. Code + params, not prose. */
+export interface AssistantModeWarning {
+  /**
+   * `assistant-mode-slash-outside-tools` — a `/` sentence needs a tool this mode does not open.
+   * `assistant-mode-subject-without-default` — a subject type no conversation claims as its default.
+   * `assistant-mode-subject-default-twice` — two conversations claim the same subject type.
+   * `assistant-mode-offered-without-label` — a conversation a screen may offer with nothing to call it.
+   */
+  code:
+    | 'assistant-mode-slash-outside-tools'
+    | 'assistant-mode-subject-without-default'
+    | 'assistant-mode-subject-default-twice'
+    | 'assistant-mode-offered-without-label'
+  params: { kind: string; slash?: string; tool?: string; subject?: string; kinds?: string[] }
+  /** For a person reading the boot log; callers act on the code and params. */
+  message: string
+}

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

@@ -0,0 +1,80 @@
+/*
+ * What this guards: a client cannot make the assistant say something (ADR-0070 A15 decision ③).
+ *
+ * `appendSessionTurns` used to store whatever role it was handed. A carried conversation could
+ * therefore put words in the assistant's mouth — every participant reads them as the assistant's,
+ * and the model reads them back as its own earlier turn and builds on them.
+ */
+import { CARRIED_TURN_LIMIT, carriedOriginalWhere, planCarriedTurns, quoteCarriedAnswer } from './carried-turns'
+
+it("★ a person's carried words are theirs, and they were said to the room", () => {
+  const rows = planCarriedTurns([{ role: 'user', content: '3 라인이 멈춘 것 같아요' }])
+
+  expect(rows).toEqual([{ role: 'user', content: '3 라인이 멈춘 것 같아요', addressee: 'room' }])
+})
+
+it('★ an assistant turn with no original is a quotation on a system row', () => {
+  const rows = planCarriedTurns([{ role: 'assistant', content: '제가 이미 처리했습니다' }])
+
+  expect(rows[0].role).toBe('system')
+  expect(rows[0].content).toBe(quoteCarriedAnswer('제가 이미 처리했습니다'))
+  expect(rows[0].content).toContain('제가 이미 처리했습니다')
+})
+
+it('★ an assistant turn that names its original is copied from storage, not trusted', () => {
+  const rows = planCarriedTurns([
+    { role: 'assistant', content: 'whatever the caller typed', sourceSessionId: 's-1', sourceMessageId: 'm-9' }
+  ])
+
+  expect(rows[0].role).toBe('assistant')
+  expect(rows[0].copyOf).toEqual({ sessionId: 's-1', messageId: 'm-9' })
+})
+
+it("'ai' is the same as 'assistant' — the same rule applies to both spellings", () => {
+  expect(planCarriedTurns([{ role: 'ai', content: '답' }])[0].role).toBe('system')
+})
+
+/*
+ * 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([])
+})
+
+it('only the last turns are carried — this is context, not an archive', () => {
+  const many = Array.from({ length: CARRIED_TURN_LIMIT + 5 }, (_, i) => ({ role: 'user', content: `줄 ${i}` }))
+
+  const rows = planCarriedTurns(many)
+
+  expect(rows).toHaveLength(CARRIED_TURN_LIMIT)
+  expect(rows[rows.length - 1].content).toBe(`줄 ${CARRIED_TURN_LIMIT + 4}`)
+})
+
+/*
+ * 원본을 찾는 조건 — 문의 설명과 조회가 같은 것을 말해야 한다.
+ *
+ * 설명은 「대화와 메시지로 원본을 댄다」인데 조회가 메시지만 보면, 어긋난 두 인자가 와도 통과한다.
+ * 그때 옮겨 오는 것은 부른 사람이 가리킨 대화의 답이 아니다.
+ */
+describe('carriedOriginalWhere', () => {
+  it('★ 대화를 대면 그 대화 안에서만 찾는다', () => {
+    const where = carriedOriginalWhere('dom-1', { sessionId: 's-1', messageId: 'm-9' })
+
+    expect(where).toEqual({ id: 'm-9', session: { id: 's-1', domain: { id: 'dom-1' } } })
+  })
+
+  it('★ 대화를 대지 않아도 테넌트는 언제나 건다', () => {
+    const where = carriedOriginalWhere('dom-1', { messageId: 'm-9' })
+
+    expect(where).toEqual({ id: 'm-9', session: { domain: { id: 'dom-1' } } })
+  })
+})

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

@@ -0,0 +1,112 @@
+/*
+ * A conversation carried in from somewhere else, turned into rows this session can hold.
+ *
+ * ── Why the assistant's turns are not simply written (ADR-0070 A15 decision ③) ──
+ * `appendSessionTurns` took whatever roles the caller sent, so a client could write a row that
+ * reads as the assistant speaking. Every participant then sees a sentence the assistant never
+ * said, and the model reads it back as its own earlier turn. Roles are the server's to write.
+ *
+ * So a carried assistant turn is kept only when its original can be found — the caller names it
+ * (`sourceSessionId` · `sourceMessageId`) and the server copies the stored text. Without an
+ * original it is kept as a quotation on a `system` row: the content is preserved, and nobody is
+ * told the assistant said it here.
+ */
+
+/** One turn as the caller carried it over. */
+export interface CarriedTurn {
+  role?: string
+  content?: string
+  /** Where an assistant turn came from, so the server can read the original instead of trusting it. */
+  sourceSessionId?: string
+  sourceMessageId?: string
+}
+
+export interface PlannedRow {
+  role: 'user' | 'assistant' | 'system'
+  content: string
+  /** People's words are addressed to the room — this door is not the one that asks the assistant. */
+  addressee?: 'room'
+  /** Set when the row must be filled from a stored message before it is written. */
+  copyOf?: { sessionId?: string; messageId: string }
+}
+
+/** How much of a carried conversation is kept — context, not an archive. */
+export const CARRIED_TURN_LIMIT = 40
+export const CARRIED_CONTENT_LIMIT = 4000
+
+/**
+ * What to write, before anything is looked up.
+ *
+ * Pure: the caller resolves `copyOf` against storage and decides what a missing original becomes.
+ */
+export function planCarriedTurns(turns: CarriedTurn[]): PlannedRow[] {
+  const planned: PlannedRow[] = []
+
+  for (const turn of Array.isArray(turns) ? turns : []) {
+    const content = (turn?.content ?? '').trim().slice(0, CARRIED_CONTENT_LIMIT)
+    if (!content) continue
+
+    /*
+     * 이 문은 **사람의 말과 어시스턴트의 답**만 옮긴다(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' })
+      continue
+    }
+
+    if (role === 'assistant') {
+      if (turn?.sourceMessageId) {
+        planned.push({
+          role: 'assistant',
+          content,
+          copyOf: { sessionId: turn.sourceSessionId, messageId: turn.sourceMessageId }
+        })
+      } else {
+        planned.push({ role: 'system', content: quoteCarriedAnswer(content) })
+      }
+      continue
+    }
+  }
+
+  return planned.slice(-CARRIED_TURN_LIMIT)
+}
+
+/**
+ * An answer with no original, kept as a quotation.
+ *
+ * English, like the other lines the model reads (`[system]`, the omission notices): this row is
+ * context for the model first, and a person reading it sees the quoted text either way.
+ */
+export function quoteCarriedAnswer(content: string): string {
+  return `carried from another conversation, quoted — the assistant did not say this here: "${content}"`
+}
+
+/**
+ * 원본을 찾는 조건.
+ *
+ * 문의 설명은 「`sourceSessionId` 와 `sourceMessageId` 로 원본을 댄다」고 말한다. 조회가 메시지 id 와
+ * 테넌트만 보면, 서로 어긋난 두 인자가 와도 설명과 다르게 통과한다 — 설명과 코드가 갈리는 자리다
+ * [수석 아키텍트가 ADR-0070 구현 검토에서 찾음, 2026-09-18].
+ *
+ * 테넌트는 언제나 건다. 대화를 대면 그것도 건다.
+ */
+export function carriedOriginalWhere(domainId: string, copyOf: { sessionId?: string; messageId: string }): any {
+  return {
+    id: copyOf.messageId,
+    session: copyOf.sessionId ? { id: copyOf.sessionId, domain: { id: domainId } } : { domain: { id: domainId } }
+  }
+}

package/server/service/chat-message/chat-message-subscription.ts

@@ -13,12 +13,13 @@
  * 차이: 필터 키가 board 가 아닌 sessionId (채팅은 ChatSession 단위).
  * 순수 로직(토픽/필터)은 chat-message-broadcast.ts (테스트 가능). 여기엔 pubsub 의존만.
  */
-import { Resolver, Subscription, Root, Arg } from 'type-graphql'
+import { Resolver, Subscription, Root, Arg, Ctx } from 'type-graphql'
 import { filter, pipe } from 'graphql-yoga'
 import { pubsub } from '@things-factory/shell'
 import { ChatMessage } from './chat-message.js'
 import { CHAT_MESSAGE_TOPIC, chatMessageFilter, type ChatMessagePayload } from './chat-message-broadcast.js'
 import { assertDomainSubscribeAllowed } from '../subscribe-auth.js'
+import { readerGate } from './reader-gate.js'
 
 // publishChatMessage 는 데코레이터 없는 chat-message-publish.ts 에 분리 (테스트 import 가능).
 export { publishChatMessage } from './chat-message-publish.js'
@@ -27,7 +28,13 @@ export type { ChatMessagePayload } from './chat-message-broadcast.js'
 
 @Resolver(ChatMessage)
 export class ChatMessageSubscription {
-  @Subscription({
+  @Subscription(() => ChatMessage, {
+    /*
+     * 돌려주는 형을 **명시한다**. 이 핸들러가 async 가 되면서(받는 사람마다 가리기 — ADR-0073 판정 1)
+     * 반환형이 `Promise<ChatMessage>` 가 되었고, type-graphql 의 reflection 은 Promise 안을 못 본다.
+     * 빠지면 스키마를 세울 때 NoExplicitTypeError 로 **패키지 적재 자체가 실패한다** — 시험이 아니라
+     * 부팅이 죽는다. plant 레인이 설치본에서 이 오류를 잡아 알려 주었다(2026-09-18).
+     */
     description:
       'Subscribes to chat messages (user / assistant / system) of a session for real-time group chat.',
     subscribe: async ({ args, context }) => {
@@ -39,7 +46,16 @@ export class ChatMessageSubscription {
       return pipe(pubsub.subscribe(CHAT_MESSAGE_TOPIC), filter(chatMessageFilter(domain.id, sessionId)))
     }
   })
-  chatMessageActivity(@Root() payload: ChatMessagePayload, @Arg('sessionId') sessionId: string): ChatMessage {
-    return payload.message
+  /*
+   * 방송도 **받는 사람 기준으로** 가린다 — ADR-0073 판정 1. 저장해 놓고 읽을 때만 가리면, 그 자리에
+   * 앉아 있던 사람은 방송으로 원문을 받는다. 같은 값이 두 길로 나가고 한쪽만 문을 본다.
+   */
+  async chatMessageActivity(
+    @Root() payload: ChatMessagePayload,
+    @Arg('sessionId') sessionId: string,
+    @Ctx() context: any
+  ): Promise<ChatMessage> {
+    const [message] = await readerGate(context)([payload.message])
+    return message as ChatMessage
   }
 }

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

@@ -60,6 +60,50 @@ export class ChatMessage {
   @Field({ description: 'Message content' })
   content!: string
 
+  /**
+   * 이 말이 누구에게 한 말인가 — `'assistant'` · `'room'`(ADR-0070 A15 결정 ①).
+   *
+   * **값은 그 행을 쓴 문이 찍는다.** 어시스턴트에게 묻는 문(`assistantChat`)이 저장한 사람의 행은
+   * `assistant` 이고, 사람끼리의 문(`appendSessionTurns`)이 저장한 행은 `room` 이다. 클라이언트가
+   * 인자로 보내지 않는다 — 인자로 받으면 「어느 문을 불렀나」와 「무엇을 적어 보냈나」 두 사실이
+   * 생기고, 둘은 어긋날 수 있다.
+   *
+   * 사람의 행에만 뜻이 있다. 어시스턴트의 답은 `parentMessage` 로 자기를 부른 턴에 귀속되고,
+   * `system` 행은 누구에게 한 말이 아니다.
+   */
+  @Column({ type: 'varchar', length: 16, nullable: true })
+  @Field({ nullable: true, description: "Who this turn was for: 'assistant' | 'room'. Written by the door that stored it, never sent by the client." })
+  addressee?: string
+
+  /**
+   * 이 행의 값이 지나온 문들 — ADR-0073 판정 1.
+   *
+   * 어시스턴트의 답과 제안 행에만 채워진다. 사람의 말은 빈 목록이다 — 사람이 자기 입으로 한 말에는
+   * 문이 없다. 답을 저장할 때 그 턴에 부른 도구들의 `doors`(ADR-0072)를 합쳐 옮겨 적는다.
+   *
+   * 읽을 때마다 **읽는 사람**이 이 문을 전부 지나는지 보고, 못 지나면 본문 대신 한 줄이 나간다. 그래서
+   * 이 칸은 "누가 볼 수 있나"를 적은 것이고, 저장된 값 자체는 누구에게도 달라지지 않는다.
+   *
+   * 목록이 비면 누구나 읽는다. 등록기가 모르는 도구가 답에 끼면 `unresolved:<도구>` 가 적히고 아무도
+   * 못 지난다 — 모르는 값은 가려지는 쪽으로 넘어뜨린다.
+   */
+  @Column({ type: 'simple-array', nullable: true })
+  @Field(() => [String], {
+    nullable: true,
+    description:
+      'GraphQL doors the tools behind this answer went through. Empty for what people typed. A reader who does not pass all of them gets a one-line notice in place of the content.'
+  })
+  doors?: string[]
+
+  /**
+   * 이 행이 **이 사람에게** 가려져 나갔는가 — 저장하지 않는다.
+   *
+   * 같은 행이 사람마다 다르게 나가므로 칸에 적을 값이 없다. 읽어 나갈 때 채운다. 화면은 이것으로
+   * 자물쇠를 그리고, 본문에 온 한 줄을 어시스턴트의 말로 오해하지 않는다.
+   */
+  @Field({ nullable: true, description: 'True when the content was replaced because this reader does not pass the row doors.' })
+  redacted?: boolean
+
   @Column({ nullable: true })
   @Field({ nullable: true, description: 'PatchEntry.id this message triggered (if any).' })
   relatedPatchId?: string

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

@@ -0,0 +1,65 @@
+/*
+ * 문 → 그 문을 지키는 권한 — ADR-0073 판정 1 의 관문을 세우는 자리.
+ *
+ * ── 정본은 AUTH 의 표다 ───────────────────────────────────────────────────
+ * 행에 적힌 것은 문 이름(`Query.jobOrders`)이고, 사람이 가진 것은 권한(`job-order:query`)이다. 둘을
+ * 잇는 것은 `privilegeOfField(typeName, fieldName)` 이다(ADR-0072 결정 5). 스키마를 지을 때 모든 루트
+ * 필드가 기록되므로, 이 표는 **그 문이 실제로 무엇을 묻는지**를 그대로 답한다.
+ *
+ * 그 전에는 도구 명세가 들고 있는 짝을 베껴 썼다. 베낀 값은 문이 선언을 바꾸면 조용히 어긋나고,
+ * 어긋나면 느슨한 쪽이 이긴다. 표가 서면서 그 사본을 걷었다.
+ *
+ * ── 판정하지 않고 AUTH 에게 묻는다 ────────────────────────────────────────
+ * 표가 주는 gate 는 `checkPermission` 이 받는 넷(category · privilege · owner · super)과 같은 모양이고,
+ * 그대로 `checkPermission` 에 넘긴다. 여기서 「category 가 없으면 소유권만 본다」 같은 규칙을 다시 쓰면
+ * 그 순간 AUTH 와 이 파일이 두 벌이 된다. 문에서 통하는 것이 여기서도 통해야 한다.
+ *
+ * ── 셋 중 둘은 닫는다 ─────────────────────────────────────────────────────
+ *   `{ known: false }`          그런 루트 필드가 없다. 도구가 문 이름을 틀리게 적은 것이다 —
+ *                               **열림으로 읽지 않는다.** 부팅 보고가 따로 말한다.
+ *   `{ known: true, gate: null }`  필드는 있고 선언이 없다. 그 문은 열려 있으므로 이 행도 열린다.
+ *   `{ known: true, gate }`     그 문이 묻는 것을 이 사람이 가졌는지 AUTH 에게 묻는다.
+ *
+ * 스키마를 짓기 전에는 표가 비어 있어 모든 문이 `known: false` 로 답한다 — 가려지는 쪽이다.
+ */
+import type { FieldGate } from '@things-factory/auth-base'
+
+/** `privilegeOfField` 와 같은 모양 — 이 파일은 표를 **읽기만** 하고 어디서 오는지는 모른다. */
+export type FieldLookup = (typeName: string, fieldName: string) => { known: false } | { known: true; gate: FieldGate | null }
+
+export interface DoorCheckDeps {
+  /** 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
+}
+
+/**
+ * 문 하나를 이 사람이 지나는가 — `doorGate` 에 넣을 검사.
+ *
+ * 되풀이 조회를 줄이는 기억은 `doorGate` 가 한다. 여기는 한 번의 판정만 한다.
+ */
+export function doorCheck(deps: DoorCheckDeps): (door: string) => Promise<boolean> {
+  return async (door: string) => {
+    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.permits(asked.gate)
+  }
+}