@gencow/core 0.1.27 → 0.1.29

package/dist/rag-schema.js

@@ -0,0 +1,87 @@
+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/dist/reactive-mutation-types.d.ts

@@ -0,0 +1,11 @@
+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/dist/reactive-mutation-types.js

@@ -0,0 +1 @@
+export {};

package/dist/reactive-mutation.d.ts

@@ -0,0 +1,51 @@
+import { type InferArgs } from "./v.js";
+import type { MutationDef, MutationHandler } from "./reactive-mutation-types.js";
+declare global {
+    var __gencow_mutationRegistry: (MutationDef<any, any> & {
+        name: string;
+    })[];
+}
+export declare const mutationRegistry: (MutationDef<any, any> & {
+    name: string;
+})[];
+/**
+ * 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 declare 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>;
+export declare function getRegisteredMutations(): (MutationDef & {
+    name: string;
+})[];

package/dist/reactive-mutation.js

@@ -0,0 +1,75 @@
+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(nameOrInvalidatesOrDef, handlerOrDef, name) {
+    let argsSchema;
+    let actualHandler;
+    let mutName;
+    let isPublic = false;
+    if (typeof nameOrInvalidatesOrDef === "string") {
+        // New primary style: mutation("name", { args?, public?, handler })
+        mutName = nameOrInvalidatesOrDef;
+        const def = handlerOrDef;
+        actualHandler = def.handler;
+        argsSchema = def.args;
+        isPublic = def.public === true;
+    }
+    else if (Array.isArray(nameOrInvalidatesOrDef)) {
+        // Legacy style: mutation([...], handler, "name") — invalidates ignored
+        actualHandler = handlerOrDef;
+        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 = {
+        name: mutName,
+        handler: actualHandler,
+        argsSchema,
+        isPublic,
+    };
+    mutationRegistry.push(def);
+    return def;
+}
+export function getRegisteredMutations() {
+    return [...mutationRegistry];
+}

package/dist/reactive-query-types.d.ts

@@ -0,0 +1,12 @@
+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/dist/reactive-query-types.js

@@ -0,0 +1 @@
+export {};

package/dist/reactive-query.d.ts

@@ -0,0 +1,14 @@
+import { type InferArgs } from "./v.js";
+import type { QueryDef, QueryHandler } from "./reactive-query-types.js";
+declare global {
+    var __gencow_queryRegistry: Map<string, QueryDef<any, any>>;
+}
+export declare const queryRegistry: Map<string, QueryDef<any, any>>;
+export declare 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>;
+export declare function getQueryHandler(key: string): QueryHandler | undefined;
+export declare function getQueryDef(key: string): QueryDef | undefined;
+export declare function getRegisteredQueries(): string[];

package/dist/reactive-query.js

@@ -0,0 +1,28 @@
+if (!globalThis.__gencow_queryRegistry)
+    globalThis.__gencow_queryRegistry = new Map();
+export const queryRegistry = globalThis.__gencow_queryRegistry;
+export function query(key, handlerOrDef) {
+    let handler;
+    let argsSchema;
+    let isPublic = false;
+    if (typeof handlerOrDef === "function") {
+        handler = handlerOrDef;
+    }
+    else {
+        handler = handlerOrDef.handler;
+        argsSchema = handlerOrDef.args;
+        isPublic = handlerOrDef.public === true;
+    }
+    const def = { key, handler, argsSchema, isPublic };
+    queryRegistry.set(key, def);
+    return def;
+}
+export function getQueryHandler(key) {
+    return queryRegistry.get(key)?.handler;
+}
+export function getQueryDef(key) {
+    return queryRegistry.get(key);
+}
+export function getRegisteredQueries() {
+    return Array.from(queryRegistry.keys());
+}

package/dist/reactive-realtime.d.ts

@@ -0,0 +1,48 @@
+import type { WSContext } from "hono/ws";
+import type { GencowCtx, RealtimeCtx, RealtimeNotifyEvent } from "./context.js";
+import type { QueryDef } from "./reactive-query-types.js";
+declare global {
+    var __gencow_subscribers: Map<string, Set<WSContext>>;
+    var __gencow_connectedClients: Set<WSContext>;
+}
+export declare const subscribers: Map<string, Set<WSContext<unknown>>>;
+/**
+ * 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 declare const connectedClients: Set<WSContext<unknown>>;
+/** Stable subscription key for WebSocket / invalidate fanout (also used by crud for query keys). */
+export declare function buildQuerySubscriptionKey(queryKey: string, args?: unknown): string;
+export declare function subscriptionKeyMatchesQueryKey(subscriptionKey: string, queryKey: string): boolean;
+export declare function subscribe(queryKey: string, ws: WSContext): void;
+export declare function unsubscribe(ws: WSContext): void;
+/** Register a raw WS connection without any query subscription (e.g. admin dashboard) */
+export declare function registerClient(ws: WSContext): void;
+export declare function deregisterClient(ws: WSContext): void;
+/**
+ * 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 declare function buildRealtimeCtx(options?: {
+    httpCallback?: (event: RealtimeNotifyEvent) => void;
+    queryMap?: Map<string, QueryDef<any, any>>;
+    buildCtxForRefresh?: () => GencowCtx;
+}): RealtimeCtx & {
+    _hasEmitted: boolean;
+    _pendingRefresh: string[];
+    _flushRefresh: () => Promise<void>;
+};
+export declare function handleWsMessage(ws: WSContext, raw: string | ArrayBuffer): void;

package/dist/reactive-realtime.js

@@ -0,0 +1,236 @@
+import { queryRegistry } from "./reactive-query.js";
+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) {
+    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;
+        const sorted = {};
+        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) {
+    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, args) {
+    const normalized = normalizeForStableJson(args);
+    if (normalized === undefined || isEmptyPlainObject(normalized))
+        return queryKey;
+    return `${queryKey}${SUBSCRIPTION_KEY_SEPARATOR}${JSON.stringify(normalized)}`;
+}
+export function subscriptionKeyMatchesQueryKey(subscriptionKey, queryKey) {
+    return subscriptionKey === queryKey || subscriptionKey.startsWith(`${queryKey}${SUBSCRIPTION_KEY_SEPARATOR}`);
+}
+export function subscribe(queryKey, ws) {
+    connectedClients.add(ws);
+    if (!subscribers.has(queryKey)) {
+        subscribers.set(queryKey, new Set());
+    }
+    subscribers.get(queryKey).add(ws);
+}
+export function unsubscribe(ws) {
+    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) {
+    connectedClients.add(ws);
+}
+export function deregisterClient(ws) {
+    connectedClients.delete(ws);
+    for (const clients of subscribers.values()) {
+        clients.delete(ws);
+    }
+}
+function sendInvalidateToLocalSubscribers(queryKeys) {
+    const targets = new Map();
+    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) {
+    const pendingEmits = new Map();
+    const _pendingRefresh = [];
+    let _hasEmitted = false;
+    return {
+        emit(queryKey, data) {
+            _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) {
+            _hasEmitted = true;
+            const queryKeys = Array.isArray(queryKey) ? [...new Set(queryKey)] : [queryKey];
+            if (options?.httpCallback) {
+                options.httpCallback({ type: "invalidate", queryKeys });
+                return;
+            }
+            sendInvalidateToLocalSubscribers(queryKeys);
+        },
+        refresh(queryKey) {
+            _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?.() ?? {};
+                    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, raw) {
+    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/dist/reactive.d.ts

@@ -2,6 +2,9 @@ import type { WSContext } from "hono/ws";
 import type { Storage } from "./storage.js";
 import type { Scheduler } from "./scheduler.js";
 import { type InferArgs } from "./v.js";
+import type { HybridSearchOptions, SearchOptions, SearchResponse, VectorSearchOptions } from "./search-types.js";
+import type { GencowServicesCtx } from "./document-types.js";
+import type { GroundingRuntime } from "./grounded-answer-types.js";
 export interface UserIdentity {
     id: string;
     email: string;
@@ -30,6 +33,11 @@ export interface RealtimeCtx {
      *   ctx.realtime.emit("tasks.list", freshList);
      */
     emit(queryKey: string, data: unknown): void;
+    /**
+     * 특정 queryKey 구독자에게 재조회 신호만 보냅니다.
+     * private/RLS query처럼 서버가 안전하게 full payload를 만들 수 없는 경우 기본값입니다.
+     */
+    invalidate(queryKey: string | string[]): void;
     /**
      * 수동 mutation에서 리얼타임 업데이트의 기본 권장 방식.
      * mutation handler 완료 후 서버가 해당 query를 re-run하여 결과를 push합니다.
@@ -48,6 +56,14 @@ export interface RealtimeCtx {
      */
     refresh(queryKey: string): void;
 }
+export type RealtimeNotifyEvent = {
+    type: "emit";
+    queryKey: string;
+    data: unknown;
+} | {
+    type: "invalidate";
+    queryKeys: string[];
+};
 /**
  * 사용자 함수(query/mutation)에 주입되는 컨텍스트.
  * Convex의 ctx 패턴과 동일하게, 이 객체를 통해서만 DB/Storage/Auth에 접근 가능.
@@ -101,8 +117,18 @@ export interface GencowCtx {
     realtime: RealtimeCtx;
     /** 재시도 — ctx.retry(fn, opts) — exponential backoff + jitter */
     retry: <T>(fn: () => Promise<T>, options?: import("./retry.js").RetryOptions) => Promise<T>;
+    /** 프레임워크 서비스 헬퍼 — workflow 전용 service는 별도 ctx에서 노출 */
+    services: GencowServicesCtx;
     /** AI 헬퍼 */
     ai?: AIContext;
+    /** Full-text / hybrid search helper */
+    search: (table: string, query: string, options: SearchOptions) => Promise<SearchResponse>;
+    /** Vector / semantic search helper */
+    vectorSearch: (table: string, options: VectorSearchOptions) => Promise<SearchResponse>;
+    /** Hybrid search helper (lexical + vector) */
+    hybridSearch: (table: string, query: string, options: HybridSearchOptions) => Promise<SearchResponse>;
+    /** Grounded answer helper over canonical rag_* tables */
+    grounding?: GroundingRuntime;
 }
 type QueryHandler<TArgs = any, TReturn = any> = (ctx: GencowCtx, args: TArgs) => Promise<TReturn>;
 type MutationHandler<TArgs = any, TReturn = any> = (ctx: GencowCtx, args: TArgs) => Promise<TReturn>;
@@ -175,6 +201,8 @@ declare global {
     var __gencow_connectedClients: Set<WSContext>;
     var __gencow_httpActionRegistry: HttpActionDef[];
 }
+export declare function buildQuerySubscriptionKey(queryKey: string, args?: unknown): string;
+export declare function subscriptionKeyMatchesQueryKey(subscriptionKey: string, queryKey: string): boolean;
 export declare function query<TSchema = any, TReturn = any>(key: string, handlerOrDef: QueryHandler<InferArgs<TSchema>, TReturn> | {
     args?: TSchema;
     public?: boolean;
@@ -272,11 +300,7 @@ export declare function deregisterClient(ws: WSContext): void;
  * @param options.buildCtxForRefresh  refresh 시 query handler에 전달할 ctx 생성 함수.
  */
 export declare function buildRealtimeCtx(options?: {
-    httpCallback?: (event: {
-        type: "emit";
-        queryKey: string;
-        data: unknown;
-    }) => void;
+    httpCallback?: (event: RealtimeNotifyEvent) => void;
     queryMap?: Map<string, QueryDef<any, any>>;
     buildCtxForRefresh?: () => GencowCtx;
 }): RealtimeCtx & {