@things-factory/ai-assistant 10.1.6

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

@@ -0,0 +1,193 @@
+/**
+ * ChatSession — Board 와 결합되는 AI 협력 세션.
+ *
+ * 한 보드에 여러 세션 가능 — DB 레벨 unique 제약 없음.
+ *
+ * 향후 폭증할 세션 분화 차원 (예: thread / 사용자별 / 컨텍스트별 design vs ops /
+ * archived / forked from clone / agent별) 을 미리 차단하지 않기 위해 구조 자체는 1:N
+ * 으로 열어둠. 단일 세션 정책 (현재 UX) 은 app 레벨 idempotent 로직 — `startBoardAISession`
+ * 이 boardId 매칭 시 기존 세션 반환, `chatSessionByBoard` 가 첫 매칭 반환.
+ *
+ * 미래에 다중 세션 활성화 시 discriminator 컬럼 (kind / name / threadId / creatorId 등)
+ * 을 그때 추가. 마이그레이션 부담 최소화 — 현재는 unique 만 풀어 자리 마련.
+ *
+ * board-service 의 Board 가 owning side 가 될 예정 (ChatSession FK).
+ */
+import {
+  Column,
+  CreateDateColumn,
+  DeleteDateColumn,
+  Entity,
+  Index,
+  ManyToOne,
+  OneToMany,
+  PrimaryGeneratedColumn,
+  RelationId,
+  UpdateDateColumn
+} from 'typeorm'
+import { Field, ID, ObjectType } from 'type-graphql'
+
+import { Domain } from '@things-factory/shell'
+import { User } from '@things-factory/auth-base'
+import { config } from '@things-factory/env'
+
+import { ChatMessage } from '../chat-message/chat-message.js'
+
+const ORMCONFIG = config.get('ormconfig', {})
+const DATABASE_TYPE = ORMCONFIG.type
+
+@Entity()
+// 인덱스는 조회 성능용으로 유지 (chatSessionByBoard 가 [domain, boardId] 로 자주 쿼리).
+// unique 제약은 의도적으로 제거 — 한 보드에 여러 세션을 미래에 허용하기 위함.
+@Index('ix_chat_session_1', (session: ChatSession) => [session.domain, session.boardId])
+// 앵커 조회용 — chatSessionsByAnchor 가 [domain, anchorType, anchorId] 로 질의.
+@Index('ix_chat_session_2', (session: ChatSession) => [session.domain, session.anchorType, session.anchorId])
+@ObjectType({
+  description: 'AI 협력 세션 — Board 와 결합. 한 보드에 여러 세션 가능 (thread / 사용자별 / 컨텍스트별 등 미래 확장).'
+})
+export class ChatSession {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(type => ID, { nullable: true })
+  readonly id?: string
+
+  @ManyToOne(type => Domain)
+  @Field(type => Domain, { nullable: true })
+  domain?: Domain
+
+  @RelationId((session: ChatSession) => session.domain)
+  domainId?: string
+
+  /** Board.id 와 연결. Board 가 owning side 가 될 예정. 1:N — 한 보드에 여러 세션 가능.
+   *
+   * **앵커 일반화 이후에도 유지되는 하위호환 컬럼**이다(제거하지 말 것). 앵커가 board 인 세션은
+   * anchorId 와 함께 이 컬럼에도 같은 값을 쓴다(dual-write) — 기존 조회/인덱스/소비자가 그대로 동작한다. */
+  @Column({ nullable: true })
+  @Field({
+    nullable: true,
+    description:
+      'Connected Board id. Multiple sessions per board allowed (future: threads / per-user / contexts). Kept for backward compatibility — board-anchored sessions dual-write this alongside anchorId.'
+  })
+  boardId?: string
+
+  /**
+   * 대화가 매달린 대상의 **종류**. 세션은 보드에만 매달리지 않는다 —
+   * 저작 대화는 보드에, 운영 대화는 공간(사이트)에 매달린다. 앵커가 대화의 성격과 이력 경계를 정한다.
+   *
+   * 'board' | 'space' | 'instance' | 'none'. 미설정(기존 데이터)은 boardId 가 있으면 board 로 읽는다 —
+   * 백필 마이그레이션 없이 lazy 하위호환(컬럼 추가만).
+   */
+  @Column({ nullable: true })
+  @Field({
+    nullable: true,
+    description:
+      "What this conversation is anchored to: 'board' (authoring a board) | 'space' (a site and the twins running there) | 'instance' | 'none'. Absent on legacy rows — treated as 'board' when boardId is present."
+  })
+  anchorType?: string
+
+  /** 앵커 대상의 id(보드 id · 공간 id · 인스턴스 id). anchorType 과 함께 의미를 갖는다. */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Id of the anchored target (board id / space id / instance id).' })
+  anchorId?: string
+
+  /**
+   * 세션의 사용자 정의 이름 (탭 레이블 / 세션 식별 표시용).
+   *
+   * nullable — 미설정 시 UI 가 fallback 라벨 ("세션 N" 또는 createdAt 기반) 사용. 사용자가
+   * 다중 세션 운영 시 의미 부여 (예: "초기 설계", "운영 시뮬레이션", "사용자A 의 사적 세션").
+   */
+  @Column({ nullable: true, length: 200 })
+  @Field({ nullable: true, description: 'User-given name of this session (tab label / identification).' })
+  name?: string
+
+  @ManyToOne(type => User)
+  @Field(type => User, { nullable: true, description: 'User who created this session.' })
+  creator?: User
+
+  @RelationId((session: ChatSession) => session.creator)
+  creatorId?: string
+
+  @ManyToOne(type => User)
+  @Field(type => User, { nullable: true, description: 'User who last updated this session.' })
+  updater?: User
+
+  @RelationId((session: ChatSession) => session.updater)
+  updaterId?: string
+
+  /** 토큰 절감용 — 오래된 메시지를 LLM 으로 압축한 요약. Phase 2 에서 작성. */
+  /**
+   * 마지막 메시지 시각 — **비정규화**. 목록 정렬(최근 활동순)과 안 읽음 판정의 기준.
+   *
+   * 왜 비정규화인가: 세션마다 메시지를 집계하면(MAX/COUNT + group by) 목록 한 번에 집계 쿼리가 붙고,
+   * 이 프레임워크는 5개 DB 드라이버를 지원해야 한다. 세션 컬럼 하나로 두면 정렬·비교가 값싸게 끝나고
+   * 드라이버 차이가 없다. 메시지를 저장할 때 함께 갱신한다(activityPatch).
+   */
+  @Column({ nullable: true })
+  @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
+
+  /** 목록에 보여줄 마지막 메시지 미리보기 — 목록에서 메시지 테이블을 다시 읽지 않기 위해 짧게 저장. */
+  @Column({ nullable: true, length: 200 })
+  @Field({ nullable: true, description: 'Short preview of the last message, stored so the session list does not need to query messages.' })
+  lastMessagePreview?: string
+
+  @Column({
+    nullable: true,
+    type:
+      DATABASE_TYPE == 'mysql' || DATABASE_TYPE == 'mariadb'
+        ? 'longtext'
+        : DATABASE_TYPE == 'oracle'
+          ? 'clob'
+          : DATABASE_TYPE == 'mssql'
+            ? 'nvarchar'
+            : 'text',
+    length: DATABASE_TYPE == 'mssql' ? 'MAX' : undefined
+  })
+  @Field({ nullable: true, description: 'Compressed summary of older messages (for token saving).' })
+  lastSummary?: string
+
+  /**
+   * `lastSummary` 가 **어디까지 덮는지** — 이 메시지까지 요약에 반영됐다.
+   *
+   * 이게 없으면 누적 요약을 할 수 없다: 매 턴 전체를 다시 요약하거나(비용) 이미 요약한 구간을
+   * 또 이어 붙인다(중복). 이력에서 이 id 를 못 찾으면(삭제·편집) 덮은 범위를 알 수 없으므로
+   * 전부 미반영으로 보고 다시 요약한다 — 빠뜨리는 쪽보다 안전하다.
+   */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Id of the last message folded into lastSummary — enables incremental summarization instead of re-reading the whole history.' })
+  summaryUpToMessageId?: string
+
+  /** 사용 모델 식별 — 'anthropic:claude-sonnet-4-6' 등 */
+  @Column({ nullable: true })
+  @Field({ nullable: true })
+  aiClientId?: string
+
+  @CreateDateColumn()
+  @Field({ nullable: true })
+  createdAt?: Date
+
+  @UpdateDateColumn()
+  @Field({ nullable: true })
+  updatedAt?: Date
+
+  @DeleteDateColumn()
+  deletedAt?: Date
+
+  // ── 관계 (TypeORM 만, GraphQL 노출은 별도 query 통해 페이징) ──
+  @OneToMany(type => ChatMessage, message => message.session)
+  messages?: ChatMessage[]
+
+  /*
+   * ── 보드 패치 관계를 끊었다 (2026-09-10) ──────────────────────────────────
+   * 여기 `@OneToMany(PatchEntry)` 가 있었다. 그래서 **대화 세션이 보드 편집기를 알아야** 했고,
+   * 세션 계열을 중립 패키지로 옮기려는 순간 `ai-assistant → board-ai → ai-assistant` 순환이
+   * 된다.
+   *
+   * 끊어도 잃는 것이 없다 — 이 관계를 **자료로 읽는 자리가 하나도 없었다**(전 저장소에서
+   * `session.patches` 를 읽는 코드 0 건). 유일한 쓰임이 `PatchEntry` 쪽의 역방향 선언 한 줄이었고,
+   * TypeORM 은 역방향 없이도 `@ManyToOne` 을 만든다. 패치는 `sessionId` 로 찾는다
+   * (`chatPatches` 가 이미 그렇게 한다).
+   *
+   * 방향은 남는다: **보드 패치가 세션을 안다. 세션은 보드 패치를 모른다.** 종속이 한쪽이면
+   * 중립 쪽이 옮겨질 수 있다.
+   */
+}

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

@@ -0,0 +1,5 @@
+import { ChatSession } from './chat-session.js'
+
+export { ChatSession }
+
+export const entities = [ChatSession]

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

@@ -0,0 +1,57 @@
+/*
+ * 세션 활동 방송 — 순수 로직(토픽·페이로드·필터). 데코레이터·pubsub import 없음 → 단위 테스트 가능.
+ *
+ * ── 왜 메시지 방송(chat-message)과 따로 두는가 ──────────────────────────────
+ * 기존 `chatMessageActivity` 는 **그 세션을 열어 둔** 구독자에게 메시지 본문을 보낸다. 그래서 창을 닫아
+ * 두면 새 메시지를 알 수 없다 — 초대 알림 한 번 받고 나면 이후 대화는 사용자가 스스로 들어와 봐야 안다.
+ *
+ * 이 토픽은 **내가 참여한 모든 세션**의 활동을 알린다. 목적이 배지·목록 갱신이므로 본문을 싣지 않고
+ * 최소 정보(세션·앵커·시각·미리보기)만 보낸다:
+ *   · 열지도 않은 세션들의 본문이 한 채널로 쏟아지는 것을 피한다(대역·주의 낭비).
+ *   · 본문이 필요한 시점은 그 세션을 열 때이고, 그때는 기존 메시지 구독이 담당한다.
+ *
+ * ── 구독자 판정을 필터에서 DB 로 하지 않는다 ────────────────────────────────
+ * 필터는 **구독자 × 메시지마다** 돈다. 여기서 DB 를 읽으면 방송 한 번이 구독자 수만큼의 질의가 된다.
+ * 그래서 발행 시점에 참여자 id 목록을 페이로드에 실어 보내고, 필터는 배열 포함 검사만 한다.
+ * 참여자 조회는 발행당 1회 — 사람 대화 빈도에서 감당 가능한 비용이다.
+ */
+
+/** 세션 활동 방송 토픽. */
+export const SESSION_ACTIVITY_TOPIC = 'board-ai-session-activity'
+
+/** 방송 페이로드 — 필터용 메타(도메인·참여자) + 목록 갱신용 최소 정보. 본문은 싣지 않는다. */
+/**
+ * 활동 종류.
+ *   message — 새 메시지. **안 읽음 배지를 올린다.**
+ *   meta    — 이름 변경·참여자 변동 등 세션 자체의 변화. 목록은 갱신하지만 배지는 올리지 않는다.
+ *             (이름이 바뀐 것을 "새 소식" 으로 알리면 소음이 된다.)
+ */
+export type SessionActivityKind = 'message' | 'meta'
+
+export interface SessionActivityPayload {
+  domainId: string
+  sessionId: string
+  kind: SessionActivityKind
+  /** 이 세션 참여자 user id — 필터가 이 배열로 수신자를 정한다(필터에서 DB 를 읽지 않기 위함). */
+  participantIds: string[]
+  anchorType?: string
+  anchorId?: string
+  /** 활동 시각(ISO) — 클라가 목록 정렬·안 읽음 판정에 쓴다. */
+  at: string
+  /** 한 줄 미리보기(짧게). 본문 전체가 아니다. */
+  preview?: string
+  /** 이 활동을 만든 사용자 — 자기 발신은 배지를 올리지 않도록 클라가 쓴다. */
+  actorId?: string
+}
+
+/**
+ * 같은 도메인 + **내가 참여자인 세션**의 활동만 통과. 도메인 격리가 보안 핵심이고,
+ * 참여자 검사가 "내 것만" 을 성립시킨다(참여하지 않은 대화의 활동을 받지 않는다).
+ */
+export function sessionActivityFilter(domainId: string, userId: string) {
+  return (payload: SessionActivityPayload): boolean =>
+    !!payload &&
+    payload.domainId === domainId &&
+    Array.isArray(payload.participantIds) &&
+    payload.participantIds.includes(userId)
+}

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

@@ -0,0 +1,44 @@
+/*
+ * 세션 활동 발행 — pubsub 의존만(데코레이터 없음). 순수 로직은 session-activity-broadcast.ts.
+ *
+ * 참여자 목록을 여기서 읽어 페이로드에 싣는다 — 필터는 구독자 × 메시지마다 돌기 때문에 거기서 DB 를
+ * 읽으면 방송 한 번이 구독자 수만큼의 질의가 된다. 발행당 1회로 끝낸다.
+ *
+ * best-effort: 실패해도 대화·저장을 막지 않는다(배지가 한 번 늦을 뿐).
+ */
+import { pubsub, getRepository } from '@things-factory/shell'
+
+import { ChatSessionParticipant } from '../chat-session-participant/chat-session-participant.js'
+import { SESSION_ACTIVITY_TOPIC, type SessionActivityPayload, type SessionActivityKind } from './session-activity-broadcast.js'
+
+export async function publishSessionActivity(input: {
+  domainId: string
+  sessionId: string
+  /** message = 새 메시지(배지 올림) · meta = 이름 변경 등(목록만 갱신). 기본 message. */
+  kind?: SessionActivityKind
+  anchorType?: string
+  anchorId?: string
+  at?: Date
+  preview?: string
+  actorId?: string
+}): Promise<void> {
+  try {
+    const participants = await getRepository(ChatSessionParticipant).find({
+      where: { domain: { id: input.domainId } as any, session: { id: input.sessionId } as any }
+    })
+    const payload: SessionActivityPayload = {
+      domainId: input.domainId,
+      sessionId: input.sessionId,
+      kind: input.kind ?? 'message',
+      participantIds: participants.map(p => (p as any).userId).filter(Boolean),
+      anchorType: input.anchorType,
+      anchorId: input.anchorId,
+      at: (input.at ?? new Date()).toISOString(),
+      preview: input.preview,
+      actorId: input.actorId
+    }
+    pubsub.publish(SESSION_ACTIVITY_TOPIC, payload)
+  } catch {
+    /* 방송 실패는 대화를 막지 않는다 */
+  }
+}

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

@@ -0,0 +1,67 @@
+/*
+ * MySessionActivitySubscription — **내가 참여한 모든 세션**의 활동 알림.
+ *
+ * 기존 chatMessageActivity 는 그 세션을 열어 둔 구독자에게 본문을 보낸다 → 창을 닫아 두면 새 메시지를
+ * 알 수 없었다. 이 구독은 배지·목록 갱신용으로 최소 정보만 보낸다(본문 없음).
+ *
+ * 도메인 격리는 필터가, "내 것만" 은 참여자 검사가 성립시킨다(session-activity-broadcast.ts).
+ */
+import { Resolver, Subscription, Root, ObjectType, Field } from 'type-graphql'
+import { filter, pipe } from 'graphql-yoga'
+import { pubsub } from '@things-factory/shell'
+
+import { SESSION_ACTIVITY_TOPIC, sessionActivityFilter, type SessionActivityPayload } from './session-activity-broadcast.js'
+import { assertDomainSubscribeAllowed } from '../subscribe-auth.js'
+
+export { publishSessionActivity } from './session-activity-publish.js'
+
+@ObjectType({ description: 'Activity notice for a session the current user participates in — badge/list refresh only, no message body.' })
+export class SessionActivity {
+  @Field({ description: 'Session that had activity.' })
+  sessionId!: string
+
+  @Field({
+    description:
+      "Kind of activity: 'message' (new message — raise the unread badge) or 'meta' (session itself changed, e.g. renamed — refresh the list but do not badge)."
+  })
+  kind!: string
+
+  @Field({ nullable: true, description: "What the session is anchored to: 'board' | 'space' | 'instance' | 'none'." })
+  anchorType?: string
+
+  @Field({ nullable: true, description: 'Id of the anchored target.' })
+  anchorId?: string
+
+  @Field({ description: 'Activity timestamp (ISO).' })
+  at!: string
+
+  @Field({ nullable: true, description: 'One-line preview (not the full body).' })
+  preview?: string
+
+  @Field({ nullable: true, description: 'User who caused the activity — clients skip badging their own.' })
+  actorId?: string
+}
+
+@Resolver(SessionActivity)
+export class MySessionActivitySubscription {
+  @Subscription(() => SessionActivity, {
+    description:
+      'Subscribes to activity in every session the current user participates in, so a closed chat surface can still show unread badges and refresh its list.',
+    subscribe: async ({ context }) => {
+      const { domain, user } = context.state
+      await assertDomainSubscribeAllowed(domain, user, (d, u) => process.superUserGranted(d, u))
+      return pipe(pubsub.subscribe(SESSION_ACTIVITY_TOPIC), filter(sessionActivityFilter(domain.id, user.id)))
+    }
+  })
+  mySessionActivity(@Root() payload: SessionActivityPayload): SessionActivity {
+    return {
+      sessionId: payload.sessionId,
+      kind: payload.kind ?? 'message',
+      anchorType: payload.anchorType,
+      anchorId: payload.anchorId,
+      at: payload.at,
+      preview: payload.preview,
+      actorId: payload.actorId
+    }
+  }
+}

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

@@ -0,0 +1,106 @@
+/*
+ * 세션 앵커 순수 로직 — 리졸버와 분리.
+ *
+ * chat-session-resolver 는 type-graphql 의 **매개변수 데코레이터**(@Arg)를 쓰므로 jest 의 babel
+ * 파서가 읽지 못한다. 순수 함수를 여기 두면 단위 테스트가 가능하다(chat-echo-dedup ·
+ * chat-input-builder 와 같은 관례).
+ *
+ * **앵커란**: 대화가 무엇에 매달려 있는지. 저작 대화는 보드에, 운영 대화는 공간(사이트와 그 공간에서
+ * 도는 트윈들)에 매달린다. 앵커가 대화의 성격과 **이력 경계**를 정한다 — 보드 편집 이력에 운영
+ * 문답이 끼지 않아야 하고, 그 반대도 마찬가지다.
+ *
+ * **하위호환**: 기존 행은 앵커 컬럼이 비어 있고 boardId 만 있다. 백필하지 않고 **읽을 때** board
+ * 앵커로 간주한다(컬럼 추가만으로 끝내기 위함). 보드 앵커 세션은 anchorId 와 boardId 를 함께
+ * 쓴다(dual-write) — 기존 조회·인덱스·소비자(operato-board 등)가 그대로 동작한다.
+ *
+ * ── Why this file validates instead of casting (2026-09-09) ──────────────────────
+ * `anchorColumns` used to do `(anchorType || 'none') as SessionAnchorType`. That is a cast, not a
+ * check: the type existed and nothing enforced it, so any string reached a nullable varchar and
+ * was stored. The plant lane was about to add a product and stopped to ask which value to write,
+ * which is the only reason this was noticed — the column would have accepted whatever it sent.
+ *
+ * A wrong value here is not a wrong value in one row. The anchor decides which conversations are
+ * listed together and which history a reply may see, so a typo silently creates a second,
+ * invisible bucket: the session is written, the inbox query for the real anchor does not match
+ * it, and the conversation is simply gone from the list with no error anywhere.
+ *
+ * Two rules follow, and both are refusals rather than defaults:
+ *
+ *   · An unknown anchor type throws. A default of 'none' would be worse than a typo, because it
+ *     turns "you named something that does not exist" into "this conversation is about nothing".
+ *   · Every anchor except 'none' requires an id. An anchor is a pointer; `('space', '')` points
+ *     nowhere, and `anchorWhere` would then look for an empty string while `anchorColumns` stored
+ *     NULL — the lookup misses its own row and every call creates another session.
+ *
+ * 'none' therefore means exactly one thing: **not addressable by anchor.** It is the UI state for
+ * "nothing picked yet" (twin's dock refuses to create a session while it holds 'none'), not a
+ * value a product writes because it has nothing narrower to point at. A product whose subject is
+ * the whole tenant anchors to 'domain' and holds the domain id — that conversation is listable and
+ * has a history boundary, and "unanchored" has neither.
+ *
+ * Adding a value to this set is an architect's call, not a lane's. A new anchor type means a new
+ * kind of subject a conversation can be about, and it is stored — once rows carry it, renaming it
+ * orphans them.
+ */
+
+/**
+ * 대화가 매달릴 수 있는 것. **저장되는 값이므로 늘리는 것은 아키텍트 판단이다.**
+ *
+ *   board     보드 저작 대화 — 그 보드의 편집 이력
+ *   space     공간 운영 대화 — 사이트와 그 공간에서 도는 트윈들
+ *   instance  트윈 하나에 대한 대화
+ *   domain    테넌트 전체가 주제인 대화 — 공장 전체 문답처럼 더 좁게 가리킬 것이 없을 때
+ *   none      앵커로 찾을 수 없는 대화. 「아직 아무것도 고르지 않았다」는 화면 상태다
+ */
+export const SESSION_ANCHOR_TYPES = ['board', 'space', 'instance', 'domain', 'none'] as const
+
+export type SessionAnchorType = (typeof SESSION_ANCHOR_TYPES)[number]
+
+export function isSessionAnchorType(value: unknown): value is SessionAnchorType {
+  return typeof value === 'string' && (SESSION_ANCHOR_TYPES as readonly string[]).includes(value)
+}
+
+function assertAnchorType(anchorType: string | undefined, where: string): SessionAnchorType {
+  const type = anchorType || 'none'
+  if (!isSessionAnchorType(type)) {
+    throw new Error(
+      `[board-ai/session-anchor] ${where}: '${type}' is not an anchor type. ` +
+        `Allowed: ${SESSION_ANCHOR_TYPES.join(' · ')}. ` +
+        'The anchor decides which conversations are listed together and which history a reply may see, ' +
+        'so an unrecognised value would write a session the inbox can never find. ' +
+        'If a new kind of subject is needed, raise it — this set is stored in rows.'
+    )
+  }
+  return type
+}
+
+/** 앵커 → 저장할 컬럼 값. 보드 앵커는 boardId 에도 같은 값을 넣어 기존 조회가 그대로 동작하게 한다. */
+export function anchorColumns(
+  anchorType: string | undefined,
+  anchorId: string | undefined
+): { anchorType: SessionAnchorType; anchorId?: string; boardId?: string } {
+  const type = assertAnchorType(anchorType, 'anchorColumns')
+  const id = anchorId || undefined
+  if (type !== 'none' && !id) {
+    throw new Error(
+      `[board-ai/session-anchor] anchorColumns: anchor '${type}' was given no id. ` +
+        'An anchor is a pointer, so this would store NULL while the lookup searches for the id it was ' +
+        'given — the session would not be found by its own anchor and every call would create another. ' +
+        "Use 'none' for a conversation that is deliberately not addressable by anchor."
+    )
+  }
+  return { anchorType: type, anchorId: id, boardId: type === 'board' ? id : undefined }
+}
+
+/**
+ * 앵커 조회 조건. 보드 앵커는 **앵커 컬럼이 빈 옛 행도 잡아야** 하므로 boardId 로 찾는다
+ * (dual-write 덕분에 신규 행도 같은 조건에 걸린다). 그 밖 앵커는 앵커 컬럼으로 찾는다.
+ *
+ * 여기서도 앵커 이름을 검사한다 — 읽기 경로에서 틀린 이름은 오류가 아니라 **0 행**으로 나오고,
+ * 화면은 「대화가 없다」로 그린다. 그 증상으로는 원인을 못 찾는다.
+ */
+export function anchorWhere(domainId: string, anchorType: string, anchorId: string): any {
+  const type = assertAnchorType(anchorType, 'anchorWhere')
+  if (type === 'board') return { boardId: anchorId, domain: { id: domainId } }
+  return { anchorType: type, anchorId, domain: { id: domainId } }
+}

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

@@ -0,0 +1,185 @@
+/*
+ * 받은편지함(세션 목록) 검증.
+ *
+ * 무엇을 지키는가:
+ *  ① **최근 활동순** — 대화가 늘면 "어디로 돌아갈지"를 목록에서 찾는다. 활동이 없으면 생성순으로 떨어진다.
+ *  ② **안 읽음 판정** — 세션의 마지막 활동이 내 읽은 지점보다 뒤일 때만. 참여자가 아니면 배지를 띄우지
+ *     않는다(내 것이 아닌 대화에 미읽음을 표시하면 소음이다).
+ *  ③ **같은 시각은 안 읽음이 아니다** — 읽은 직후 같은 밀리초 활동을 미읽음으로 잡으면 방금 읽은 화면에
+ *     배지가 남는다.
+ *  ④ **미리보기 정규화** — 목록 한 줄에 들어가야 하고 컬럼 길이 제한이 있다.
+ *
+ * 집계 쿼리를 쓰지 않는 설계라(5개 DB 드라이버) 판정이 전부 값 비교로 끝난다 — 그래서 순수 테스트가 된다.
+ */
+import { buildInbox, countUnreadSessions, activityPatch, applyHidden, searchInbox } from './session-inbox'
+
+const t = (iso: string) => new Date(iso)
+
+const S = (id: string, lastMessageAt?: string, createdAt = '2026-07-01T00:00:00Z', name?: string) => ({
+  id,
+  name,
+  lastMessageAt: lastMessageAt ? t(lastMessageAt) : null,
+  createdAt: t(createdAt)
+})
+
+describe('정렬', () => {
+  it('최근 활동순 내림차순', () => {
+    const out = buildInbox(
+      [S('a', '2026-07-10T10:00:00Z'), S('b', '2026-07-12T10:00:00Z'), S('c', '2026-07-11T10:00:00Z')],
+      []
+    )
+    expect(out.map(e => e.id)).toEqual(['b', 'c', 'a'])
+  })
+
+  it('활동이 없으면 생성 시각으로 떨어진다 — 빈 대화가 목록 위를 차지하지 않는다', () => {
+    const out = buildInbox(
+      [S('old', undefined, '2026-07-01T00:00:00Z'), S('new', undefined, '2026-07-09T00:00:00Z'), S('active', '2026-07-05T00:00:00Z')],
+      []
+    )
+    expect(out.map(e => e.id)).toEqual(['new', 'active', 'old'])
+  })
+})
+
+describe('안 읽음 판정', () => {
+  it('활동이 읽은 지점보다 뒤면 안 읽음', () => {
+    const out = buildInbox([S('a', '2026-07-12T10:00:00Z')], [{ sessionId: 'a', lastReadAt: t('2026-07-12T09:00:00Z') }])
+    expect(out[0].unread).toBe(true)
+  })
+
+  it('읽은 지점이 활동보다 뒤면 읽음', () => {
+    const out = buildInbox([S('a', '2026-07-12T10:00:00Z')], [{ sessionId: 'a', lastReadAt: t('2026-07-12T11:00:00Z') }])
+    expect(out[0].unread).toBe(false)
+  })
+
+  it('같은 시각은 안 읽음이 아니다 — 방금 읽은 화면에 배지가 남지 않게', () => {
+    const same = '2026-07-12T10:00:00Z'
+    const out = buildInbox([S('a', same)], [{ sessionId: 'a', lastReadAt: t(same) }])
+    expect(out[0].unread).toBe(false)
+  })
+
+  it('참여자인데 한 번도 읽지 않았고 활동이 있으면 안 읽음(초대 직후)', () => {
+    const out = buildInbox([S('a', '2026-07-12T10:00:00Z')], [{ sessionId: 'a', lastReadAt: null }])
+    expect(out[0]).toMatchObject({ participant: true, unread: true })
+  })
+
+  it('참여자가 아니면 안 읽음으로 표시하지 않는다 — 내 것이 아닌 대화에 배지 금지', () => {
+    const out = buildInbox([S('a', '2026-07-12T10:00:00Z')], [])
+    expect(out[0]).toMatchObject({ participant: false, unread: false })
+  })
+
+  it('활동이 없는 빈 세션은 안 읽음이 아니다', () => {
+    const out = buildInbox([S('a')], [{ sessionId: 'a', lastReadAt: null }])
+    expect(out[0].unread).toBe(false)
+  })
+
+  it('문자열 시각(직렬화된 값)도 비교된다', () => {
+    const out = buildInbox(
+      [{ id: 'a', lastMessageAt: '2026-07-12T10:00:00Z', createdAt: '2026-07-01T00:00:00Z' }],
+      [{ sessionId: 'a', lastReadAt: '2026-07-12T09:00:00Z' }]
+    )
+    expect(out[0].unread).toBe(true)
+  })
+})
+
+describe('배지 수', () => {
+  it('안 읽은 **세션 수**를 센다(메시지 개수가 아니다)', () => {
+    const entries = buildInbox(
+      [S('a', '2026-07-12T10:00:00Z'), S('b', '2026-07-12T10:00:00Z'), S('c', '2026-07-12T10:00:00Z')],
+      [
+        { sessionId: 'a', lastReadAt: null },
+        { sessionId: 'b', lastReadAt: t('2026-07-12T11:00:00Z') },
+        { sessionId: 'c', lastReadAt: null }
+      ]
+    )
+    expect(countUnreadSessions(entries)).toBe(2)
+  })
+})
+
+describe('활동 갱신 값', () => {
+  it('미리보기는 개행·연속 공백을 한 칸으로 눌러 한 줄로 만든다', () => {
+    const { lastMessagePreview } = activityPatch('첫 줄\n\n  둘째   줄 ')
+    expect(lastMessagePreview).toBe('첫 줄 둘째 줄')
+  })
+
+  it('미리보기는 200자로 자른다 — 컬럼 길이 제한', () => {
+    const { lastMessagePreview } = activityPatch('가'.repeat(500))
+    expect(lastMessagePreview!.length).toBe(200)
+  })
+
+  it('시각을 주면 그것을 쓴다(테스트·백필 재현성)', () => {
+    const at = t('2026-07-12T10:00:00Z')
+    expect(activityPatch('x', at).lastMessageAt).toBe(at)
+  })
+
+  it('빈 본문도 안전하다', () => {
+    expect(activityPatch('').lastMessagePreview).toBe('')
+  })
+})
+
+describe('applyHidden — 내 목록에서만 숨기기', () => {
+  const entry = (id: string, lastMessageAt?: string): any => ({
+    id,
+    lastMessageAt,
+    unread: false,
+    participant: true
+  })
+
+  it('숨긴 대화는 기본 목록에서 빠진다', () => {
+    const out = applyHidden([entry('a', '2026-07-30T01:00:00Z'), entry('b')], new Map([['a', '2026-07-30T02:00:00Z']]))
+    expect(out.map(e => e.id)).toEqual(['b'])
+  })
+
+  it('숨긴 뒤 새 활동이 생기면 다시 보인다 — 참여 중인 대화에서 조용히 잘려 나가지 않게', () => {
+    const out = applyHidden([entry('a', '2026-07-30T03:00:00Z')], new Map([['a', '2026-07-30T02:00:00Z']]))
+    expect(out.map(e => e.id)).toEqual(['a'])
+    expect(out[0].hidden).toBeUndefined()
+  })
+
+  it('필터를 켜면 숨긴 것도 표시와 함께 돌려준다 — 되돌릴 수 있어야 한다', () => {
+    const out = applyHidden(
+      [entry('a', '2026-07-30T01:00:00Z'), entry('b')],
+      new Map([['a', '2026-07-30T02:00:00Z']]),
+      true
+    )
+    expect(out.map(e => e.id)).toEqual(['a', 'b'])
+    expect(out[0].hidden).toBe(true)
+    expect(out[1].hidden).toBeUndefined()
+  })
+
+  it('숨김 기록이 없으면 아무것도 바꾸지 않는다', () => {
+    const entries = [entry('a'), entry('b')]
+    expect(applyHidden(entries, new Map())).toEqual(entries)
+  })
+})
+
+describe('searchInbox — 대량 목록의 풀텍스트 필터', () => {
+  const rows: any[] = [
+    { id: 'a', name: 'A-DC 포화 원인', lastMessagePreview: '점유율이 92% 입니다', unread: false, participant: true },
+    { id: 'b', name: 'Dock 배치 검토', lastMessagePreview: '입고 도크를 늘리면', unread: false, participant: true },
+    { id: 'c', lastMessagePreview: '이름 없는 대화', unread: false, participant: true }
+  ]
+
+  it('이름으로 찾는다', () => {
+    expect(searchInbox(rows, '포화').map(e => e.id)).toEqual(['a'])
+  })
+
+  it('미리보기 본문으로도 찾는다 — 제목만으로는 돌아갈 대화를 못 찾는다', () => {
+    expect(searchInbox(rows, '입고').map(e => e.id)).toEqual(['b'])
+  })
+
+  it('대소문자를 무시한다', () => {
+    expect(searchInbox(rows, 'dock').map(e => e.id)).toEqual(['b'])
+  })
+
+  it('이름이 없는 대화도 미리보기로 걸린다', () => {
+    expect(searchInbox(rows, '이름 없는').map(e => e.id)).toEqual(['c'])
+  })
+
+  it('빈 검색어는 전체를 그대로 돌려준다(필터 없음)', () => {
+    expect(searchInbox(rows, '   ')).toBe(rows)
+  })
+
+  it('맞는 것이 없으면 빈 목록 — 조용히 전체를 보여주지 않는다', () => {
+    expect(searchInbox(rows, 'zzz')).toEqual([])
+  })
+})