@things-factory/board-ai 10.0.0-beta.108

package/server/service/mention-resolver.test.ts

@@ -0,0 +1,273 @@
+/**
+ * mention-resolver.ts 단위 테스트.
+ *
+ * 핵심 정책 (things-factory 식별자 컨벤션):
+ *   - refid 는 사용자 답변 / 본문 노출 금지 — 시스템 내부 핸들로만
+ *   - # 는 와이드 셀렉터 — name / id / type OR 매칭
+ *   - 본문 #token 은 LITERAL 보존, 매칭 결과는 끝의 mention map 블록으로
+ */
+import {
+  resolveMentions,
+  findMentions,
+  lookupComponents
+} from './mention-resolver'
+
+const make = (components: any[] = []) => ({ width: 1000, height: 600, components })
+
+describe('lookupComponents — 와이드 검색 (name / id / type OR)', () => {
+  const components = [
+    { refid: 1, type: 'rect', name: '경광등1', id: 'motor-1' },
+    { refid: 2, type: 'rect', name: '경광등2', id: 'motor-2' },
+    { refid: 3, type: 'circle', name: '센서', id: 'sensor-A' },
+    { refid: 4, type: 'rect' } // name/id 없음
+  ]
+
+  test('name 정확 일치', () => {
+    const r = lookupComponents('경광등1', components)
+    expect(r).toHaveLength(1)
+    expect(r[0].refid).toBe(1)
+  })
+
+  test('id 정확 일치', () => {
+    const r = lookupComponents('motor-1', components)
+    expect(r).toHaveLength(1)
+    expect(r[0].refid).toBe(1)
+    expect(r[0].id).toBe('motor-1')
+  })
+
+  test('type 정확 일치 — 같은 type 의 모든 컴포넌트', () => {
+    const r = lookupComponents('rect', components)
+    expect(r).toHaveLength(3)
+    expect(r.map(c => c.refid).sort()).toEqual([1, 2, 4])
+  })
+
+  test('case-insensitive (영문)', () => {
+    expect(lookupComponents('MOTOR-1', components)).toHaveLength(1)
+    expect(lookupComponents('Rect', components)).toHaveLength(3)
+  })
+
+  test('한글 case-insensitive 안전 (대소문자 개념 없지만 동작 확인)', () => {
+    expect(lookupComponents('경광등1', components)).toHaveLength(1)
+  })
+
+  test('매칭 없음 → []', () => {
+    expect(lookupComponents('no-such', components)).toEqual([])
+  })
+
+  test('빈 토큰 / 빈 components → []', () => {
+    expect(lookupComponents('', components)).toEqual([])
+    expect(lookupComponents('rect', [])).toEqual([])
+  })
+
+  test('매칭된 컴포넌트의 핵심 식별자 반환 (refid + name + id + type)', () => {
+    const r = lookupComponents('motor-1', components)
+    expect(r[0]).toEqual({
+      refid: 1,
+      type: 'rect',
+      name: '경광등1',
+      id: 'motor-1'
+    })
+  })
+
+  test('동일 refid 두 기준 일치 시 중복 안 됨 (dedup)', () => {
+    // name 'rect' + type 'rect' — 인위적 케이스
+    const cs = [{ refid: 1, type: 'rect', name: 'rect' }]
+    const r = lookupComponents('rect', cs)
+    expect(r).toHaveLength(1) // 중복 X
+  })
+})
+
+describe('resolveMentions — 본문 보존 + mention map 첨부', () => {
+  test('본문은 LITERAL 그대로, 매핑은 끝에 블록으로', () => {
+    const board = make([
+      { refid: 35, type: 'rect', name: '경광등1', id: 'motor-1' }
+    ])
+    const r = resolveMentions('#경광등1 빨갛게', board)
+    // 본문은 그대로 유지 — refid 본문 노출 0
+    expect(r).toContain('#경광등1 빨갛게')
+    expect(r).not.toMatch(/^경광등1\s*\(/m) // '(refid' 같은 inline 변환 없음
+    // mention map 블록 첨부
+    expect(r).toContain('--- mention map')
+    expect(r).toContain('#경광등1 →')
+    expect(r).toContain("name='경광등1'")
+    expect(r).toContain("id='motor-1'")
+    expect(r).toContain("type='rect'")
+    expect(r).toContain('refid=35')
+  })
+
+  test('매칭 0 → 변경 없음 (본문 그대로)', () => {
+    const board = make([{ refid: 1, name: 'A' }])
+    expect(resolveMentions('#NoSuch 어쩌고', board)).toBe('#NoSuch 어쩌고')
+  })
+
+  test('빈 components → 변경 없음', () => {
+    expect(resolveMentions('#anything', make([]))).toBe('#anything')
+    expect(resolveMentions('#anything', null)).toBe('#anything')
+  })
+
+  test('빈 텍스트 안전', () => {
+    expect(resolveMentions('', make([{ refid: 1, name: 'A' }]))).toBe('')
+  })
+
+  test('id 매칭 — 본문 #motor-1 그대로 + map 에 매핑', () => {
+    const board = make([{ refid: 5, type: 'rect', id: 'motor-1' }])
+    const r = resolveMentions('#motor-1 stop', board)
+    expect(r).toContain('#motor-1 stop')
+    expect(r).toContain('#motor-1 →')
+    expect(r).toContain("id='motor-1'")
+    expect(r).toContain('refid=5')
+  })
+
+  test('type 매칭 — 같은 type 모든 컴포넌트가 map 에 나열', () => {
+    const board = make([
+      { refid: 1, type: 'rect', name: 'A' },
+      { refid: 2, type: 'rect', name: 'B' },
+      { refid: 3, type: 'circle' }
+    ])
+    const r = resolveMentions('#rect 모두', board)
+    expect(r).toContain('#rect 모두') // 본문 보존
+    expect(r).toContain('#rect →')
+    expect(r).toContain('refid=1')
+    expect(r).toContain('refid=2')
+    expect(r).not.toContain('refid=3') // circle 제외
+  })
+
+  test('다중 #token — 모두 map 에 등록, 본문 모두 보존', () => {
+    const board = make([
+      { refid: 1, name: 'A' },
+      { refid: 2, name: 'B' }
+    ])
+    const r = resolveMentions('#A 와 #B', board)
+    expect(r).toContain('#A 와 #B')
+    expect(r).toContain('#A →')
+    expect(r).toContain('#B →')
+  })
+
+  test('일부 매칭 일부 실패 — 매칭 성공만 map 에', () => {
+    const board = make([{ refid: 1, name: 'A' }])
+    const r = resolveMentions('#A and #X', board)
+    expect(r).toContain('#A and #X') // 본문 모두 보존
+    expect(r).toContain('#A →')
+    expect(r).not.toContain('#X →') // X 매칭 실패
+  })
+
+  test('refid 가 본문에 등장하는 다른 사용자 텍스트는 영향 없음 (token 외 #refid 표기)', () => {
+    // 사용자가 어쩌다 'refid' 라고 본문에 쓴 경우는 우리가 변환 안 함
+    const board = make([{ refid: 1, name: 'A' }])
+    const r = resolveMentions('#A 의 refid 가 뭐야?', board)
+    expect(r).toContain('#A 의 refid 가 뭐야?')
+  })
+})
+
+describe('findMentions — 매칭 메타 직접 노출 (UI / 디버그)', () => {
+  test('성공 + 실패 모두 반환, 위치 포함', () => {
+    const board = make([
+      { refid: 1, name: 'A' },
+      { refid: 2, name: 'B' }
+    ])
+    const r = findMentions('#A #X #B', board)
+    expect(r).toHaveLength(3)
+    expect(r[0].token).toBe('A')
+    expect(r[0].matched).toHaveLength(1)
+    expect(r[0].matched[0].refid).toBe(1)
+    expect(r[1].token).toBe('X')
+    expect(r[1].matched).toEqual([])
+    expect(r[2].token).toBe('B')
+    expect(r[2].matched[0].refid).toBe(2)
+  })
+
+  test('빈 텍스트 → []', () => {
+    expect(findMentions('', make([]))).toEqual([])
+  })
+
+  test('start/end 위치 정확', () => {
+    const board = make([{ refid: 1, name: 'A' }])
+    const r = findMentions('hello #A world', board)
+    expect(r[0].start).toBe(6)
+    expect(r[0].end).toBe(8)
+  })
+})
+
+describe('picks (popup 명시 선택) — 결정적 매칭', () => {
+  test('pick 의 token + refid → 그 컴포넌트 직접 매칭 (fallback 안 거침)', () => {
+    const board = make([
+      { refid: 35, name: '경광등1', type: 'rect' },
+      { refid: 42, name: '경광등1', type: 'rect' } // 동명이인
+    ])
+    // picks 없으면 둘 다 매칭 (다중)
+    const noPicks = lookupComponents('경광등1', board.components)
+    expect(noPicks).toHaveLength(2)
+    // picks 있으면 그 refid 만
+    const withPicks = lookupComponents('경광등1', board.components, [
+      { token: '경광등1', refid: 35 }
+    ])
+    expect(withPicks).toHaveLength(1)
+    expect(withPicks[0].refid).toBe(35)
+  })
+
+  test('pick 의 refid 가 stale (보드에 없음) → fallback 으로', () => {
+    const board = make([{ refid: 35, name: '경광등1' }])
+    const r = lookupComponents('경광등1', board.components, [
+      { token: '경광등1', refid: 999 } // stale
+    ])
+    expect(r).toHaveLength(1)
+    expect(r[0].refid).toBe(35) // fallback 으로 name 매칭
+  })
+
+  test('pick token 이 텍스트 token 과 다르면 무시 (다른 token 의 pick)', () => {
+    const board = make([
+      { refid: 1, name: 'A' },
+      { refid: 2, name: 'B' }
+    ])
+    const r = lookupComponents('A', board.components, [
+      { token: 'B', refid: 2 } // A 가 아니라 B 의 pick
+    ])
+    expect(r).toHaveLength(1)
+    expect(r[0].refid).toBe(1) // A name 매칭
+  })
+
+  test('resolveMentions options.picks 통과', () => {
+    const board = make([
+      { refid: 35, name: '경광등1' },
+      { refid: 42, name: '경광등1' }
+    ])
+    const r = resolveMentions('#경광등1 빨갛게', board, {
+      picks: [{ token: '경광등1', refid: 42 }]
+    })
+    expect(r).toContain('refid=42')
+    expect(r).not.toContain('refid=35') // pick 결정적 — 35 안 옴
+  })
+
+  test('mention map 에 position 정보 포함 (AI 좌표 인식 보조)', () => {
+    const board = make([
+      { refid: 1, name: 'A', type: 'rect', left: 100, top: 200, width: 80, height: 40 }
+    ])
+    const r = resolveMentions('#A', board)
+    // 중심 좌표 (140, 220)
+    expect(r).toContain('pos=(140,220)')
+  })
+})
+
+describe('refid 정책 회귀 방지', () => {
+  test('"#refidNN" 같은 직접 refid 참조는 더 이상 작동 안 함 (refid 사용자 노출 금지)', () => {
+    const board = make([{ refid: 35, name: '경광등' }])
+    // 과거에는 #refid35 가 직접 참조됐지만 이제는 일반 token 으로만 처리
+    // 'refid35' 라는 name/id/type 가 없으면 매칭 안 됨
+    const r = resolveMentions('#refid35 빨갛게', board)
+    expect(r).toBe('#refid35 빨갛게') // 매칭 0 → 변경 없음
+    expect(r).not.toContain('mention map')
+  })
+
+  test('mention map 블록 안에서만 refid 등장 (본문에는 없음)', () => {
+    const board = make([{ refid: 35, name: '경광등1' }])
+    const r = resolveMentions('#경광등1 빨갛게', board)
+    // 본문 영역 (mention map 블록 전) 에는 refid 단어가 없어야
+    const mapStart = r.indexOf('--- mention map')
+    const bodyPart = r.slice(0, mapStart)
+    expect(bodyPart).not.toMatch(/refid/i)
+    // map 블록 안에는 refid 가 있다 (AI 가 tool 호출에 사용)
+    const mapPart = r.slice(mapStart)
+    expect(mapPart).toMatch(/refid=35/)
+  })
+})
+

package/server/service/mention-resolver.ts

@@ -0,0 +1,264 @@
+/**
+ * `#token` 멘션 해석 (things-factory 식별자 컨벤션 준수).
+ *
+ * things-factory 정책:
+ *   - `#` 은 사용자가 컴포넌트를 가리키는 SELECTOR. things-scene Finder 의
+ *     CSS 셀렉터 컨셉과 같은 맥락 — 와이드 검색 (name / id / type 셋 다 OR).
+ *   - **refid 는 시스템 내부 핸들** — 사용자에게 노출 금지. 사용자가 본 적도
+ *     없는 숫자라 `(refid 35)` 같은 표기는 혼란만 가중.
+ *   - id 는 데이터 바인딩 식별자 (human-readable). unique 제약 없음.
+ *   - name 은 사용자 라벨. 가장 친숙.
+ *
+ * Resolver 정책:
+ *   - 본문의 `#token` 은 LITERAL 보존 (refid 본문 노출 0)
+ *   - 매칭 결과는 본문 끝에 구조화된 "mention map" 블록으로 첨부
+ *   - AI 는 시스템 프롬프트의 안내에 따라 mention map 의 refid 를 tool
+ *     호출 인자로만 사용. 사용자 답변 텍스트에서는 name/id 로 지칭.
+ *
+ * Token 매칭 (모두 시도, OR):
+ *   - name 정확 일치 (case-insensitive)
+ *   - id 정확 일치 (case-insensitive)
+ *   - type 정확 일치 (case-insensitive) — `#rect` 같이 모든 type 가리키기
+ *
+ * 부분 / fuzzy 매칭 안 함 — popup 측에서 사용자가 정확한 식별자 선택.
+ *
+ * Token 정규식: /#([^\s#]+)/g (한글/영문/하이픈/언더스코어/숫자).
+ */
+import type { BoardModel } from '@things-factory/board-import'
+
+const MENTION_PATTERN = /#([^\s#]+)/g
+
+/** 매칭된 컴포넌트의 핵심 정보 — refid 는 시스템 핸들, 나머지는 사용자 친화적 식별.
+ *  things-scene F-Finder 와 동일한 검색 필드 (id/name/type/tag/class/text)
+ *  + position (AI 가 식별 + 조작 좌표 판단에 활용). */
+export interface MentionedComponent {
+  refid: number
+  name?: string
+  id?: string
+  type: string
+  tag?: string
+  class?: string
+  text?: string
+  /** 중심 좌표 (rect: left+w/2, top+h/2 / circle: cx, cy) — 정수 반올림 */
+  position?: { x: number; y: number }
+}
+
+/** popup 에서 사용자가 명시 선택한 컴포넌트 — server 가 정확한 매칭에 사용. */
+export interface MentionPick {
+  /** 사용자 텍스트의 #token 부분 (예: '경광등1') */
+  token: string
+  /** popup 에서 선택된 정확한 refid */
+  refid: number
+}
+
+export interface ResolveMentionsOptions {
+  /** popup 에서 명시 선택된 mentions — 해당 token 은 fallback 매칭 안 거치고 정확한 refid 로 즉시 해석 */
+  picks?: MentionPick[]
+}
+
+export interface MentionMatch {
+  /** 사용자가 입력한 #token 의 token 부분 */
+  token: string
+  /** 토큰 위치 (start: '#' 위치, end: 마지막 글자 다음) */
+  start: number
+  end: number
+  /** name/id/type 매칭으로 발견한 컴포넌트들 */
+  matched: MentionedComponent[]
+}
+
+/**
+ * 텍스트의 모든 #token 을 보드에서 매칭. UI / 디버그 / 테스트용.
+ */
+export function findMentions(
+  text: string,
+  currentBoard: BoardModel | null | undefined,
+  options: ResolveMentionsOptions = {}
+): MentionMatch[] {
+  if (!text || typeof text !== 'string') return []
+  const components = currentBoard?.components ?? []
+  return collectMatches(text, components, options.picks)
+}
+
+
+/**
+ * Token 으로 컴포넌트 매칭 — name/id/type/tag/class/text OR (things-scene F-Finder
+ * 동일 필드 셋). 여러 기준에서 동시 일치하더라도 같은 refid 는 한 번만 반환 (dedup).
+ *
+ * picks 에 해당 token 이 있으면 fallback 안 거치고 그 refid 로 직접 매칭 (popup 에서
+ * 사용자가 명시 선택한 결정적 매핑). 그 refid 가 보드에 없으면 fallback 으로.
+ */
+export function lookupComponents(
+  token: string,
+  components: readonly any[],
+  picks?: readonly MentionPick[]
+): MentionedComponent[] {
+  if (!token || components.length === 0) return []
+
+  // picks 우선 — popup 으로 명시 선택된 token 은 그 refid 로 직접 매칭
+  if (picks) {
+    const pick = picks.find(p => p.token === token)
+    if (pick) {
+      const c = components.find(
+        (x: any) => x && typeof x.refid === 'number' && x.refid === pick.refid
+      )
+      if (c) {
+        const fields = readSearchFields(c)
+        return [
+          {
+            refid: pick.refid,
+            name: fields.name,
+            id: fields.id,
+            type: fields.type,
+            tag: fields.tag,
+            class: fields.cls,
+            text: fields.text,
+            position: extractPosition(c)
+          }
+        ]
+      }
+      // pick 이 stale (refid 가 더 이상 보드에 없음) — fallback 으로 진행
+    }
+  }
+
+  const lower = token.toLowerCase()
+  const out: MentionedComponent[] = []
+  const seen = new Set<number>()
+  for (const c of components) {
+    if (!c || typeof (c as any).refid !== 'number') continue
+    const refid = (c as any).refid
+    if (seen.has(refid)) continue
+    const fields = readSearchFields(c)
+    if (
+      (fields.name && fields.name.toLowerCase() === lower) ||
+      (fields.id && fields.id.toLowerCase() === lower) ||
+      fields.type.toLowerCase() === lower ||
+      (fields.tag && fields.tag.toLowerCase() === lower) ||
+      (fields.cls && fields.cls.toLowerCase() === lower) ||
+      (fields.text && fields.text.toLowerCase() === lower)
+    ) {
+      seen.add(refid)
+      out.push({
+        refid,
+        name: fields.name,
+        id: fields.id,
+        type: fields.type,
+        tag: fields.tag,
+        class: fields.cls,
+        text: fields.text,
+        position: extractPosition(c)
+      })
+    }
+  }
+  return out
+}
+
+/** 컴포넌트 중심 좌표 — rect: left+w/2 / circle: cx,cy. */
+function extractPosition(c: any): { x: number; y: number } | undefined {
+  if (typeof c.cx === 'number' && typeof c.cy === 'number') {
+    return { x: Math.round(c.cx), y: Math.round(c.cy) }
+  }
+  if (typeof c.left === 'number' && typeof c.top === 'number') {
+    const w = typeof c.width === 'number' ? c.width : 0
+    const h = typeof c.height === 'number' ? c.height : 0
+    return { x: Math.round(c.left + w / 2), y: Math.round(c.top + h / 2) }
+  }
+  return undefined
+}
+
+function readSearchFields(c: any): {
+  name?: string
+  id?: string
+  type: string
+  tag?: string
+  cls?: string
+  text?: string
+} {
+  const str = (v: any): string | undefined =>
+    typeof v === 'string' && v.length > 0 ? v : undefined
+  return {
+    name: str(c.name),
+    id: str(c.id),
+    type: typeof c.type === 'string' ? c.type : 'unknown',
+    tag: str(c.tag),
+    cls: str(c.class),
+    text: str(c.text)
+  }
+}
+
+/**
+ * 텍스트의 #token 을 LLM 친화 형태로 변환.
+ *
+ * 본문은 그대로 + 매칭 성공한 토큰의 mention map 을 끝에 첨부:
+ *
+ *   "[원본 본문]
+ *
+ *    --- mention map (자동 첨부 — 사용자가 # 로 지칭한 컴포넌트) ---
+ *    #경광등1 →
+ *      { name='경광등1', id='motor-1', type='rect', refid=35 }
+ *    #펌프 →
+ *      { name='펌프A', id='pump-1', type='rect', refid=42 }
+ *      { name='펌프B', id='pump-2', type='rect', refid=51 }"
+ *
+ * AI 는 system prompt 안내에 따라 refid 를 tool 호출 인자로만 사용. 답변
+ * 텍스트에서는 refid 직접 언급 금지.
+ *
+ * 매칭 0 → 변경 없음 (본문 그대로 반환).
+ */
+export function resolveMentions(
+  text: string,
+  currentBoard: BoardModel | null | undefined,
+  options: ResolveMentionsOptions = {}
+): string {
+  if (!text || typeof text !== 'string') return text
+  const components = currentBoard?.components ?? []
+  if (components.length === 0) return text
+
+  const matches = collectMatches(text, components, options.picks)
+  const resolved = matches.filter(m => m.matched.length > 0)
+  if (resolved.length === 0) return text
+
+  const block: string[] = [
+    '',
+    '--- mention map (자동 첨부 — 사용자가 # 로 지칭한 컴포넌트) ---'
+  ]
+  for (const m of resolved) {
+    block.push(`#${m.token} →`)
+    for (const c of m.matched) {
+      block.push(`  ${formatComponentRef(c)}`)
+    }
+  }
+  return text + '\n' + block.join('\n')
+}
+
+function collectMatches(
+  text: string,
+  components: readonly any[],
+  picks?: readonly MentionPick[]
+): MentionMatch[] {
+  const out: MentionMatch[] = []
+  const pattern = new RegExp(MENTION_PATTERN.source, 'g')
+  let m: RegExpExecArray | null
+  while ((m = pattern.exec(text)) !== null) {
+    const token = m[1]
+    out.push({
+      token,
+      start: m.index,
+      end: m.index + m[0].length,
+      matched: lookupComponents(token, components, picks)
+    })
+  }
+  return out
+}
+
+function formatComponentRef(c: MentionedComponent): string {
+  const parts: string[] = []
+  if (c.name) parts.push(`name='${c.name}'`)
+  if (c.id) parts.push(`id='${c.id}'`)
+  parts.push(`type='${c.type}'`)
+  if (c.tag) parts.push(`tag='${c.tag}'`)
+  if (c.class) parts.push(`class='${c.class}'`)
+  if (c.text) parts.push(`text='${c.text}'`)
+  if (c.position) parts.push(`pos=(${c.position.x},${c.position.y})`)
+  parts.push(`refid=${c.refid}`)
+  return `{ ${parts.join(', ')} }`
+}

package/server/service/patch-entry/board-patch-broadcast.ts

@@ -0,0 +1,24 @@
+/*
+ * board-patch 브로드캐스트 — 순수 로직 (토픽/페이로드/필터). 데코레이터·pubsub import 없음
+ * → 단위테스트 가능. 데코레이터 resolver(board-patch-subscription.ts)와 pubsub 의존
+ * publishBoardPatch 는 별도.
+ */
+import type { PatchEntry } from './patch-entry.js' // type-only — 런타임 import 아님
+
+/** board-patch 브로드캐스트 토픽. */
+export const BOARD_PATCH_TOPIC = 'board-patch'
+
+/** 방송 페이로드 — 구독 필터(domain+board)용 메타 + PatchEntry 본체. */
+export interface BoardPatchPayload {
+  domainId: string
+  boardId?: string
+  patch: PatchEntry
+}
+
+/**
+ * 같은 domain + board 구독자에게만 통과시키는 필터 (도메인 격리 = 보안 핵심).
+ */
+export function boardPatchFilter(domainId: string, boardId: string) {
+  return (payload: BoardPatchPayload): boolean =>
+    !!payload && payload.domainId === domainId && payload.boardId === boardId
+}

package/server/service/patch-entry/board-patch-subscription.test.ts

@@ -0,0 +1,40 @@
+/**
+ * board-patch 브로드캐스트 — 단위 테스트 (순수 로직).
+ *  - boardPatchFilter: domain+board 격리(보안 핵심) — 일치만 통과, 불일치/널/board없음 차단.
+ * (publishBoardPatch / 구독 resolver 는 pubsub·graphql-ws 통합 영역 — 별도 검증.)
+ */
+import { boardPatchFilter, BOARD_PATCH_TOPIC } from './board-patch-broadcast'
+import type { BoardPatchPayload } from './board-patch-broadcast'
+
+const payload = (domainId: string, boardId?: string): BoardPatchPayload => ({
+  domainId,
+  boardId,
+  patch: { id: 'p1' } as any
+})
+
+describe('boardPatchFilter (domain+board 격리)', () => {
+  it('domain+board 모두 일치 → 통과', () => {
+    expect(boardPatchFilter('d1', 'b1')(payload('d1', 'b1'))).toBe(true)
+  })
+
+  it('domain 불일치 → 차단 (도메인 격리)', () => {
+    expect(boardPatchFilter('d1', 'b1')(payload('d2', 'b1'))).toBe(false)
+  })
+
+  it('board 불일치 → 차단', () => {
+    expect(boardPatchFilter('d1', 'b1')(payload('d1', 'b2'))).toBe(false)
+  })
+
+  it('boardId 없는 페이로드 → 차단', () => {
+    expect(boardPatchFilter('d1', 'b1')(payload('d1', undefined))).toBe(false)
+  })
+
+  it('null/undefined 페이로드 안전 → 차단', () => {
+    expect(boardPatchFilter('d1', 'b1')(null as any)).toBe(false)
+    expect(boardPatchFilter('d1', 'b1')(undefined as any)).toBe(false)
+  })
+
+  it('토픽 상수', () => {
+    expect(BOARD_PATCH_TOPIC).toBe('board-patch')
+  })
+})

package/server/service/patch-entry/board-patch-subscription.ts

@@ -0,0 +1,50 @@
+/*
+ * BoardPatchSubscription (Phase Board-AI C1 — op-브로드캐스트 spine).
+ *
+ * PatchEntry(AI 또는 user-direct 편집) 가 생성될 때마다 같은 board 구독자에게 방송 →
+ * 실시간 공동편집의 척추. 클라이언트(C2)가 구독해 원격 patch 를 applyBoardEditPatch 로 적용.
+ *
+ * 전송/패턴은 기존 board-service/board-subscription.ts 복제 (PubSub + graphql-ws, domain 격리).
+ * 순수 로직(토픽/필터)은 board-patch-broadcast.ts (테스트 가능). 여기엔 pubsub 의존만.
+ */
+import { Resolver, Subscription, Root, Arg } from 'type-graphql'
+import { filter, pipe } from 'graphql-yoga'
+import { pubsub } from '@things-factory/shell'
+import { PatchEntry } from './patch-entry.js'
+import { BOARD_PATCH_TOPIC, boardPatchFilter, type BoardPatchPayload } from './board-patch-broadcast.js'
+import { assertDomainSubscribeAllowed } from '../subscribe-auth.js'
+
+export { BOARD_PATCH_TOPIC, boardPatchFilter } from './board-patch-broadcast.js'
+export type { BoardPatchPayload } from './board-patch-broadcast.js'
+
+/**
+ * PatchEntry 생성 직후 호출 — 같은 board 구독자에게 방송.
+ * boardId 없으면(세션 미연결) skip. pubsub 미가용/실패해도 본 흐름(영속 완료)을 막지 않는다.
+ */
+export function publishBoardPatch(payload: BoardPatchPayload): void {
+  if (!payload.boardId) return
+  try {
+    pubsub.publish(BOARD_PATCH_TOPIC, payload)
+  } catch {
+    /* 방송 생략 — 영속은 이미 끝남 */
+  }
+}
+
+@Resolver(PatchEntry)
+export class BoardPatchSubscription {
+  @Subscription({
+    description:
+      'Subscribes to board edit patches (AI or user-direct) for real-time collaboration on a board.',
+    subscribe: async ({ args, context }) => {
+      const { domain, user } = context.state
+      const { boardId } = args
+
+      await assertDomainSubscribeAllowed(domain, user, (d, u) => process.superUserGranted(d, u))
+
+      return pipe(pubsub.subscribe(BOARD_PATCH_TOPIC), filter(boardPatchFilter(domain.id, boardId)))
+    }
+  })
+  boardPatchActivity(@Root() payload: BoardPatchPayload, @Arg('boardId') boardId: string): PatchEntry {
+    return payload.patch
+  }
+}

package/server/service/patch-entry/index.ts

@@ -0,0 +1,12 @@
+import { PatchEntry } from './patch-entry.js'
+
+export { PatchEntry }
+export {
+  BoardPatchSubscription,
+  publishBoardPatch,
+  boardPatchFilter,
+  BOARD_PATCH_TOPIC,
+  type BoardPatchPayload
+} from './board-patch-subscription.js'
+
+export const entities = [PatchEntry]