@gencow/core 0.1.27 → 0.1.29

package/src/rag-operations-types.ts

@@ -0,0 +1,90 @@
+import type { SearchScope } from "./search-types.js";
+
+export type RagOperationKind = "ingest" | "retrieve" | "answer" | "reindex" | "evaluate";
+export type RagOperationMetricUnit = "ms" | "count" | "tokens" | "usd";
+export type RagIndexHealth = "ready" | "empty" | "degraded" | "failed";
+
+export type RagOperationMetric = {
+  id: string;
+  appId: string;
+  corpus: string;
+  visibility: SearchScope["visibility"];
+  ownerUserId: string | null;
+  operation: RagOperationKind;
+  jobId: string | null;
+  workflowId: string | null;
+  sourceId: string | null;
+  metricName: string;
+  metricValue: number;
+  unit: RagOperationMetricUnit | null;
+  metadata: Record<string, unknown>;
+  recordedAt: string;
+};
+
+export type RagOperationsSummary = {
+  corpus: string;
+  visibility: SearchScope["visibility"];
+  ownerUserId: string | null;
+  sourceCount: number;
+  sectionCount: number;
+  chunkCount: number;
+  jobCounts: Record<string, number>;
+  latestJob: {
+    id: string;
+    status: string;
+    stage: string;
+    updatedAt: string;
+  } | null;
+  recentMetricCounts: Record<string, number>;
+  averageLatencyMs: number | null;
+  indexHealth: RagIndexHealth;
+};
+
+export type RagEvaluationExpectedClaim = {
+  claim: string;
+  verdict: "supported" | "partial" | "unsupported";
+};
+
+export type RagEvaluationFixture = {
+  name: string;
+  scope: SearchScope;
+  query: string;
+  expectedSourceIds?: string[];
+  expectedCitationCountMin?: number;
+  expectedClaims?: RagEvaluationExpectedClaim[];
+};
+
+export type RagEvaluationFixtureResult = {
+  name: string;
+  ok: boolean;
+  failures: string[];
+  matchedSourceIds: string[];
+  citationCount: number;
+  claimStatuses: Array<{
+    claim: string;
+    expected: RagEvaluationExpectedClaim["verdict"];
+    actual: string | null;
+  }>;
+};
+
+export type RagEvaluationRunResult = {
+  ok: boolean;
+  total: number;
+  passed: number;
+  failed: number;
+  results: RagEvaluationFixtureResult[];
+};
+
+export type RagReindexMode = "source-changed" | "section-changed" | "corpus-policy-changed" | "full-rebuild";
+
+export type RagReindexPlan = {
+  corpus: string;
+  visibility: SearchScope["visibility"];
+  ownerUserId: string | null;
+  mode: RagReindexMode;
+  reason: string;
+  sourceIds: string[];
+  sourceCount: number;
+  estimatedChunkCount: number;
+  requiresConfirmation: boolean;
+};

package/src/rag-schema.ts

@@ -0,0 +1,94 @@
+import { bigint, boolean, doublePrecision, integer, jsonb, pgTable, text, timestamp, vector } from "drizzle-orm/pg-core";
+
+function buildScopeColumns() {
+  return {
+    id: text("id").primaryKey(),
+    corpus: text("corpus").notNull(),
+    visibilityScope: text("visibility_scope").notNull(),
+    ownerUserId: text("owner_user_id"),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+    updatedAt: timestamp("updated_at").defaultNow().notNull(),
+  };
+}
+
+export const ragCorpora = pgTable("rag_corpora", {
+  ...buildScopeColumns(),
+  title: text("title").notNull(),
+  description: text("description"),
+  allowExternalProviders: boolean("allow_external_providers").default(false).notNull(),
+  retentionDays: integer("retention_days"),
+  metadata: jsonb("metadata").default({}).notNull(),
+});
+
+export const ragSources = pgTable("rag_sources", {
+  ...buildScopeColumns(),
+  storageId: text("storage_id").notNull(),
+  sourceKey: text("source_key").notNull(),
+  sourceTitle: text("source_title").notNull(),
+  mimeType: text("mime_type").notNull(),
+  byteSize: bigint("byte_size", { mode: "number" }).notNull(),
+  sourceChecksum: text("source_checksum").notNull(),
+  convertProvider: text("convert_provider").notNull(),
+  convertStatus: text("convert_status").notNull(),
+  markdown: text("markdown").notNull(),
+  text: text("text").notNull(),
+  warnings: jsonb("warnings").default([]).notNull(),
+  metadata: jsonb("metadata").default({}).notNull(),
+});
+
+export const ragSections = pgTable("rag_sections", {
+  ...buildScopeColumns(),
+  sourceId: text("source_id").notNull(),
+  sectionIndex: integer("section_index").notNull(),
+  sectionPath: jsonb("section_path").default([]).notNull(),
+  title: text("title"),
+  depth: integer("depth").notNull(),
+  pageStart: integer("page_start"),
+  pageEnd: integer("page_end"),
+  charStart: integer("char_start").notNull(),
+  charEnd: integer("char_end").notNull(),
+});
+
+export const ragChunks = pgTable("rag_chunks", {
+  ...buildScopeColumns(),
+  sourceId: text("source_id").notNull(),
+  sectionId: text("section_id"),
+  chunkIndex: integer("chunk_index").notNull(),
+  chunkText: text("chunk_text").notNull(),
+  lexicalText: text("lexical_text").notNull(),
+  embedding: vector("embedding", { dimensions: 1536 }),
+  pageStart: integer("page_start"),
+  pageEnd: integer("page_end"),
+  chunkChecksum: text("chunk_checksum").notNull(),
+  metadata: jsonb("metadata").default({}).notNull(),
+});
+
+export const ragIngestJobs = pgTable("rag_ingest_jobs", {
+  ...buildScopeColumns(),
+  workflowId: text("workflow_id").notNull(),
+  sourceId: text("source_id").notNull(),
+  status: text("status").notNull(),
+  stage: text("stage").notNull(),
+  providerTrace: jsonb("provider_trace").default({}).notNull(),
+  metrics: jsonb("metrics").default({}).notNull(),
+  error: text("error"),
+  startedAt: timestamp("started_at").defaultNow().notNull(),
+  completedAt: timestamp("completed_at"),
+});
+
+export const ragOperationMetrics = pgTable("rag_operation_metrics", {
+  id: text("id").primaryKey(),
+  appId: text("app_id").notNull(),
+  corpus: text("corpus").notNull(),
+  visibilityScope: text("visibility_scope").notNull(),
+  ownerUserId: text("owner_user_id"),
+  operation: text("operation").notNull(),
+  jobId: text("job_id"),
+  workflowId: text("workflow_id"),
+  sourceId: text("source_id"),
+  metricName: text("metric_name").notNull(),
+  metricValue: doublePrecision("metric_value").notNull(),
+  unit: text("unit"),
+  metadata: jsonb("metadata").default({}).notNull(),
+  recordedAt: timestamp("recorded_at").defaultNow().notNull(),
+});

package/src/reactive-mutation-types.ts

@@ -0,0 +1,13 @@
+import type { InferArgs } from "./v.js";
+import type { GencowCtx } from "./context.js";
+
+export type MutationHandler<TArgs = any, TReturn = any> = (ctx: GencowCtx, args: TArgs) => Promise<TReturn>;
+
+export interface MutationDef<TSchema = any, TReturn = any> {
+  handler: MutationHandler<InferArgs<TSchema>, TReturn>;
+  argsSchema?: TSchema;
+  /** true = 인증 없이 접근 가능, false(기본) = auth 필수 (Secure by Default) */
+  isPublic: boolean;
+  _args?: InferArgs<TSchema>;
+  _return?: TReturn;
+}

package/src/reactive-mutation.ts

@@ -0,0 +1,115 @@
+import { type InferArgs } from "./v.js";
+import type { MutationDef, MutationHandler } from "./reactive-mutation-types.js";
+
+// ─── mutation registry (globalThis) ─────────────────────
+// globalThis shared singleton — dual-bundle safe (see analysis-dual-module-registry.md).
+
+declare global {
+  var __gencow_mutationRegistry: (MutationDef<any, any> & { name: string })[];
+}
+
+if (!globalThis.__gencow_mutationRegistry) globalThis.__gencow_mutationRegistry = [];
+
+export const mutationRegistry = globalThis.__gencow_mutationRegistry;
+
+let mutationCounter = 0;
+
+/**
+ * mutation — 데이터 변경 함수를 선언적으로 등록합니다.
+ *
+ * 3가지 호출 방식 지원 (query와 동일한 패턴 우선):
+ *
+ * @example
+ * ```typescript
+ * // ✅ 권장: query와 동일한 (name, def) 패턴
+ * mutation("tasks.create", {
+ *     args: { title: v.string() },
+ *     handler: async (ctx, args) => { ... },
+ * });
+ *
+ * // ✅ 객체 스타일 (하위 호환)
+ * mutation({
+ *     name: "tasks.create",
+ *     handler: async (ctx) => { ... },
+ * });
+ *
+ * // ⚠️ Legacy 배열 스타일 (비권장)
+ * mutation(["tasks.list"], handler, "tasks.create");
+ * ```
+ *
+ * @note invalidates 필드는 deprecated — 전달해도 무시됩니다.
+ *       리얼타임 UI 갱신에는 ctx.realtime.emit() 또는 ctx.realtime.refresh()를 사용하세요.
+ */
+export function mutation<TSchema = any, TReturn = any>(
+  nameOrInvalidatesOrDef:
+    | string
+    | string[]
+    | {
+        name?: string;
+        args?: TSchema;
+        public?: boolean;
+        invalidates?: string[];
+        handler: MutationHandler<InferArgs<TSchema>, TReturn>;
+      },
+  handlerOrDef?:
+    | MutationHandler<InferArgs<TSchema>, TReturn>
+    | {
+        invalidates?: string[];
+        args?: TSchema;
+        public?: boolean;
+        handler: MutationHandler<InferArgs<TSchema>, TReturn>;
+      },
+  name?: string,
+): MutationDef<TSchema, TReturn> {
+  let argsSchema: TSchema | undefined;
+  let actualHandler: MutationHandler<InferArgs<TSchema>, TReturn>;
+  let mutName: string;
+  let isPublic = false;
+
+  if (typeof nameOrInvalidatesOrDef === "string") {
+    // New primary style: mutation("name", { args?, public?, handler })
+    mutName = nameOrInvalidatesOrDef;
+    const def = handlerOrDef as {
+      args?: TSchema;
+      public?: boolean;
+      handler: MutationHandler<InferArgs<TSchema>, TReturn>;
+    };
+    actualHandler = def.handler;
+    argsSchema = def.args;
+    isPublic = def.public === true;
+  } else if (Array.isArray(nameOrInvalidatesOrDef)) {
+    // Legacy style: mutation([...], handler, "name") — invalidates ignored
+    actualHandler = handlerOrDef as MutationHandler<InferArgs<TSchema>, TReturn>;
+    mutName = name || `mutation_${++mutationCounter}`;
+  } else {
+    // Object style: mutation({ name?, args?, public?, handler })
+    actualHandler = nameOrInvalidatesOrDef.handler;
+    argsSchema = nameOrInvalidatesOrDef.args;
+    isPublic = nameOrInvalidatesOrDef.public === true;
+    mutName =
+      nameOrInvalidatesOrDef.name ||
+      (typeof name === "string" ? name : "") ||
+      `mutation_${++mutationCounter}`;
+  }
+
+  // 이름 미지정 시 경고 — 디버깅 지원
+  if (mutName.startsWith("mutation_")) {
+    console.warn(
+      `[gencow] mutation registered without explicit name → "${mutName}". ` +
+        `Use mutation("myMutation", { handler }) for better debugging.`,
+    );
+  }
+
+  const def: MutationDef<TSchema, TReturn> & { name: string } = {
+    name: mutName,
+    handler: actualHandler,
+    argsSchema,
+    isPublic,
+  };
+  mutationRegistry.push(def);
+  return def;
+}
+
+export function getRegisteredMutations(): (MutationDef & { name: string })[] {
+  return [...mutationRegistry];
+}

package/src/reactive-query-types.ts

@@ -0,0 +1,14 @@
+import type { InferArgs } from "./v.js";
+import type { GencowCtx } from "./context.js";
+
+export type QueryHandler<TArgs = any, TReturn = any> = (ctx: GencowCtx, args: TArgs) => Promise<TReturn>;
+
+export interface QueryDef<TSchema = any, TReturn = any> {
+  key: string;
+  handler: QueryHandler<InferArgs<TSchema>, TReturn>;
+  argsSchema?: TSchema;
+  /** true = 인증 없이 접근 가능, false(기본) = auth 필수 (Secure by Default) */
+  isPublic: boolean;
+  _args?: InferArgs<TSchema>;
+  _return?: TReturn;
+}

package/src/reactive-query.ts

@@ -0,0 +1,48 @@
+import { type InferArgs } from "./v.js";
+import type { QueryDef, QueryHandler } from "./reactive-query-types.js";
+
+// ─── query registry (globalThis) ─────────────────────────
+// globalThis shared singleton — dual-bundle safe (see analysis-dual-module-registry.md).
+
+declare global {
+  var __gencow_queryRegistry: Map<string, QueryDef<any, any>>;
+}
+
+if (!globalThis.__gencow_queryRegistry) globalThis.__gencow_queryRegistry = new Map();
+
+export const queryRegistry = globalThis.__gencow_queryRegistry;
+
+export function query<TSchema = any, TReturn = any>(
+  key: string,
+  handlerOrDef:
+    | QueryHandler<InferArgs<TSchema>, TReturn>
+    | { args?: TSchema; public?: boolean; handler: QueryHandler<InferArgs<TSchema>, TReturn> },
+): QueryDef<TSchema, TReturn> {
+  let handler: QueryHandler<InferArgs<TSchema>, TReturn>;
+  let argsSchema: TSchema | undefined;
+  let isPublic = false;
+
+  if (typeof handlerOrDef === "function") {
+    handler = handlerOrDef;
+  } else {
+    handler = handlerOrDef.handler;
+    argsSchema = handlerOrDef.args;
+    isPublic = handlerOrDef.public === true;
+  }
+
+  const def: QueryDef<TSchema, TReturn> = { key, handler, argsSchema, isPublic };
+  queryRegistry.set(key, def);
+  return def;
+}
+
+export function getQueryHandler(key: string): QueryHandler | undefined {
+  return queryRegistry.get(key)?.handler;
+}
+
+export function getQueryDef(key: string): QueryDef | undefined {
+  return queryRegistry.get(key);
+}
+
+export function getRegisteredQueries(): string[] {
+  return Array.from(queryRegistry.keys());
+}

package/src/reactive-realtime.ts

@@ -0,0 +1,267 @@
+import type { WSContext } from "hono/ws";
+import type { GencowCtx, RealtimeCtx, RealtimeNotifyEvent } from "./context.js";
+import { queryRegistry } from "./reactive-query.js";
+import type { QueryDef } from "./reactive-query-types.js";
+
+// ─── WS / subscription + subscription-key helpers (globalThis) ─
+//
+// globalThis 기반 — 서버 번들(인라인)과 node_modules/@gencow/core 양쪽에서
+// 동일한 레지스트리 인스턴스를 공유. Dual-Module Registry 버그 방지.
+// See: docs/analysis/analysis-dual-module-registry.md
+
+declare global {
+  var __gencow_subscribers: Map<string, Set<WSContext>>;
+  var __gencow_connectedClients: Set<WSContext>;
+}
+
+if (!globalThis.__gencow_subscribers) globalThis.__gencow_subscribers = new Map();
+if (!globalThis.__gencow_connectedClients) globalThis.__gencow_connectedClients = new Set();
+
+export const subscribers = globalThis.__gencow_subscribers;
+
+/**
+ * Every WebSocket client that ever establishes a connection is tracked here.
+ * This allows broadcasting invalidation events to clients that never subscribed
+ * to a specific query (e.g. the admin dashboard's raw WebSocket connection).
+ */
+export const connectedClients = globalThis.__gencow_connectedClients;
+
+const SUBSCRIPTION_KEY_SEPARATOR = "::";
+
+function normalizeForStableJson(value: unknown): unknown {
+  if (value === undefined) return undefined;
+  if (value === null) return null;
+  if (value instanceof Date) return value.toISOString();
+  if (Array.isArray(value)) return value.map((item) => normalizeForStableJson(item));
+  if (typeof value === "object") {
+    const source = value as Record<string, unknown>;
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(source).sort()) {
+      const normalized = normalizeForStableJson(source[key]);
+      if (normalized !== undefined) sorted[key] = normalized;
+    }
+    return sorted;
+  }
+  return value;
+}
+
+function isEmptyPlainObject(value: unknown): boolean {
+  return !!value && typeof value === "object" && !Array.isArray(value) && Object.keys(value).length === 0;
+}
+
+/** Stable subscription key for WebSocket / invalidate fanout (also used by crud for query keys). */
+export function buildQuerySubscriptionKey(queryKey: string, args?: unknown): string {
+  const normalized = normalizeForStableJson(args);
+  if (normalized === undefined || isEmptyPlainObject(normalized)) return queryKey;
+  return `${queryKey}${SUBSCRIPTION_KEY_SEPARATOR}${JSON.stringify(normalized)}`;
+}
+
+export function subscriptionKeyMatchesQueryKey(subscriptionKey: string, queryKey: string): boolean {
+  return subscriptionKey === queryKey || subscriptionKey.startsWith(`${queryKey}${SUBSCRIPTION_KEY_SEPARATOR}`);
+}
+
+export function subscribe(queryKey: string, ws: WSContext) {
+  connectedClients.add(ws);
+  if (!subscribers.has(queryKey)) {
+    subscribers.set(queryKey, new Set());
+  }
+  subscribers.get(queryKey)!.add(ws);
+}
+
+export function unsubscribe(ws: WSContext) {
+  connectedClients.delete(ws);
+  for (const clients of subscribers.values()) {
+    clients.delete(ws);
+  }
+}
+
+/** Register a raw WS connection without any query subscription (e.g. admin dashboard) */
+export function registerClient(ws: WSContext) {
+  connectedClients.add(ws);
+}
+
+export function deregisterClient(ws: WSContext) {
+  connectedClients.delete(ws);
+  for (const clients of subscribers.values()) {
+    clients.delete(ws);
+  }
+}
+
+function sendInvalidateToLocalSubscribers(queryKeys: string[]): void {
+  const targets = new Map<WSContext, Set<string>>();
+  for (const queryKey of queryKeys) {
+    for (const [subscriptionKey, clients] of subscribers) {
+      if (!subscriptionKeyMatchesQueryKey(subscriptionKey, queryKey)) continue;
+      for (const ws of clients) {
+        if (!targets.has(ws)) targets.set(ws, new Set());
+        targets.get(ws)!.add(subscriptionKey);
+      }
+    }
+  }
+
+  for (const [ws, keys] of targets) {
+    try {
+      ws.send(JSON.stringify({ type: "invalidate", queries: [...keys] }));
+    } catch {
+      deregisterClient(ws);
+    }
+  }
+}
+
+/**
+ * mutation 실행 시점에 생성되는 RealtimeCtx.
+ * emit(): 데이터를 직접 push (초고빈도 mutation용).
+ * refresh(): queryKey를 pending 큐에 추가, mutation 완료 후 서버가 query re-run하여 push.
+ *
+ * 💡 Batching: 같은 queryKey에 대한 emit이 50ms 내에 여러 번 호출되면
+ * 마지막 데이터만 push하여 불필요한 전송을 방지합니다.
+ *
+ * ⚠️ 매 mutation 호출마다 새로 생성해야 합니다 (debounce timer가 mutation scope에 격리).
+ *
+ * @param options.httpCallback  BaaS 모드: Platform WS Gateway에 HTTP로 emit 전달.
+ *                              설정되면 WS 직접 push 대신 이 콜백을 호출.
+ *                              로컬 dev에서는 미설정 → 기존 WS 직접 push 유지.
+ * @param options.queryMap      query 레지스트리 — refresh()에서 query handler를 찾아 re-run.
+ * @param options.buildCtxForRefresh  refresh 시 query handler에 전달할 ctx 생성 함수.
+ */
+export function buildRealtimeCtx(options?: {
+  httpCallback?: (event: RealtimeNotifyEvent) => void;
+  queryMap?: Map<string, QueryDef<any, any>>;
+  buildCtxForRefresh?: () => GencowCtx;
+}): RealtimeCtx & { _hasEmitted: boolean; _pendingRefresh: string[]; _flushRefresh: () => Promise<void> } {
+  const pendingEmits = new Map<string, { data: unknown; timer: ReturnType<typeof setTimeout> }>();
+  const _pendingRefresh: string[] = [];
+  let _hasEmitted = false;
+
+  return {
+    emit(queryKey: string, data: unknown) {
+      _hasEmitted = true;
+      // 기존 pending timer가 있으면 취소 (debounce)
+      const existing = pendingEmits.get(queryKey);
+      if (existing) clearTimeout(existing.timer);
+
+      const timer = setTimeout(() => {
+        pendingEmits.delete(queryKey);
+
+        // BaaS 모드: Platform WS Gateway에 HTTP callback
+        if (options?.httpCallback) {
+          options.httpCallback({ type: "emit", queryKey, data });
+          return;
+        }
+
+        // 로컬 dev: WS 직접 push (기존 동작)
+        const clients = subscribers.get(queryKey);
+        if (!clients || clients.size === 0) return;
+
+        const message = JSON.stringify({
+          type: "query:updated",
+          query: queryKey,
+          data,
+        });
+        for (const ws of clients) {
+          try {
+            ws.send(message);
+          } catch {
+            clients.delete(ws);
+          }
+        }
+      }, 50); // 50ms batch window
+
+      pendingEmits.set(queryKey, { data, timer });
+    },
+
+    invalidate(queryKey: string | string[]) {
+      _hasEmitted = true;
+      const queryKeys = Array.isArray(queryKey) ? [...new Set(queryKey)] : [queryKey];
+      if (options?.httpCallback) {
+        options.httpCallback({ type: "invalidate", queryKeys });
+        return;
+      }
+      sendInvalidateToLocalSubscribers(queryKeys);
+    },
+
+    refresh(queryKey: string) {
+      _hasEmitted = true; // 경고 억제
+      if (!_pendingRefresh.includes(queryKey)) {
+        _pendingRefresh.push(queryKey);
+      }
+    },
+
+    get _hasEmitted() {
+      return _hasEmitted;
+    },
+    get _pendingRefresh() {
+      return [..._pendingRefresh];
+    },
+
+    async _flushRefresh() {
+      if (_pendingRefresh.length === 0) return;
+
+      // queryMap이 없으면 refresh 동작 불가 (로그 경고)
+      const qMap = options?.queryMap ?? queryRegistry;
+
+      for (const key of _pendingRefresh) {
+        const queryDef = qMap.get(key);
+        if (!queryDef) {
+          console.warn(`[gencow] refresh("${key}"): query not found in registry. Skipping.`);
+          continue;
+        }
+        try {
+          // refresh용 ctx 생성 (mutation ctx와 동일한 DB/auth 스코프)
+          if (!options?.buildCtxForRefresh) {
+            console.warn(
+              `[gencow] ⚠️  refresh("${key}"): buildCtxForRefresh not provided. ` +
+                `Query handler will receive an empty ctx — ctx.db will be undefined. ` +
+                `This is a framework configuration error. ` +
+                `💡 Ensure buildRealtimeCtx() receives a buildCtxForRefresh callback.`,
+            );
+          }
+          const refreshCtx = options?.buildCtxForRefresh?.() ?? ({} as GencowCtx);
+          const result = await queryDef.handler(refreshCtx, {});
+
+          // emit과 동일한 경로로 push
+          if (options?.httpCallback) {
+            options.httpCallback({ type: "emit", queryKey: key, data: result });
+          } else {
+            const clients = subscribers.get(key);
+            if (clients && clients.size > 0) {
+              const message = JSON.stringify({
+                type: "query:updated",
+                query: key,
+                data: result,
+              });
+              for (const ws of clients) {
+                try {
+                  ws.send(message);
+                } catch {
+                  clients.delete(ws);
+                }
+              }
+            }
+          }
+        } catch (e) {
+          console.warn(`[gencow] refresh("${key}") failed:`, e instanceof Error ? e.message : e);
+        }
+      }
+      _pendingRefresh.length = 0;
+    },
+  };
+}
+
+export function handleWsMessage(ws: WSContext, raw: string | ArrayBuffer) {
+  try {
+    const msg = typeof raw === "string" ? JSON.parse(raw) : JSON.parse(raw.toString());
+
+    if (msg.type === "subscribe" && msg.query) {
+      subscribe(msg.query, ws);
+      ws.send(JSON.stringify({ type: "subscribed", query: msg.query }));
+    }
+
+    if (msg.type === "unsubscribe" && msg.query) {
+      const clients = subscribers.get(msg.query);
+      if (clients) clients.delete(ws);
+    }
+  } catch {
+    // ignore malformed messages
+  }
+}

package/src/rls-db.ts

@@ -1,6 +1,5 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { sql } from "drizzle-orm";
-import type { PgAsyncDatabase } from "drizzle-orm/pg-core";
 
 /**
  * RLS DB wrapper — execution paths for `withRlsConnection`:
@@ -33,6 +32,12 @@ const gucNameRe = /^app\.[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)*$/;
 
 const RESERVED_VARS_KEYS = new Set(["app.current_user_id", "app.current_user_role", "app.tenant_id"]);
 
+type RlsDrizzleDatabaseLike = {
+  session: unknown;
+  _: { session?: unknown };
+  transaction: (callback: (tx: unknown) => unknown | Promise<unknown>, ...rest: unknown[]) => Promise<unknown>;
+};
+
 function assertSafeGucName(key: string): void {
   if (!gucNameRe.test(key)) {
     throw new Error(
@@ -244,10 +249,10 @@ function wrapSession(session: any, rls: RlsSessionContext, reuseOuterConnection:
  *
  * `db.transaction()` still injects the same variables at the start of the callback transaction.
  */
-export function createRlsDb(
-  db: PgAsyncDatabase<any, any, any, any>,
+export function createRlsDb<TDb extends RlsDrizzleDatabaseLike>(
+  db: TDb,
   rls: RlsSessionContext,
-): PgAsyncDatabase<any, any, any, any> {
+): TDb {
   const reuseOuterConnection = isDrizzleTransactionDb(db);
   const baseSession = (db as unknown as { session: any }).session;
   const wrappedSession = wrapSession(baseSession, rls, reuseOuterConnection);