@gencow/core 0.1.27 → 0.1.28

package/src/grounded-answer-types.ts

@@ -0,0 +1,78 @@
+import type { SearchFilter, SearchScope } from "./search-types.js";
+
+export type CitationCoverage = "direct" | "partial" | "context";
+export type ClaimSupportStatus = "supported" | "partially_supported" | "insufficient_evidence";
+export type GroundedAnswerMode = "qa" | "compare" | "topic";
+
+export type Citation = {
+  sourceId: string;
+  sourceTitle: string;
+  sectionId?: string;
+  sectionPath?: string[];
+  pageStart?: number;
+  pageEnd?: number;
+  chunkIds: string[];
+  snippet: string;
+  coverage: CitationCoverage;
+  confidence: number;
+};
+
+export type ClaimEvidenceMap = {
+  claimId: string;
+  claimText: string;
+  status: ClaimSupportStatus;
+  citations: Citation[];
+  missingEvidenceReasons?: string[];
+};
+
+export type GroundedAnswer = {
+  answer: string;
+  claims: ClaimEvidenceMap[];
+  citations: Citation[];
+  warnings: string[];
+  grounded: boolean;
+};
+
+export type GroundingBudget = {
+  maxVerifyLoops: number;
+  maxResearchQueriesPerLoop: number;
+  maxCitationsPerClaim: number;
+  maxClaimsPerAnswer: number;
+};
+
+export const DEFAULT_GROUNDING_BUDGET: GroundingBudget = {
+  maxVerifyLoops: 2,
+  maxResearchQueriesPerLoop: 3,
+  maxCitationsPerClaim: 3,
+  maxClaimsPerAnswer: 12,
+};
+
+export type GroundedClaimInput = {
+  claimId?: string;
+  claimText: string;
+  requiredTerms?: string[];
+};
+
+export type GroundedCompareInput = {
+  left: string;
+  right: string;
+};
+
+export type GroundedTopicInput = {
+  minDistinctSections?: number;
+};
+
+export type GroundedAnswerInput = {
+  question: string;
+  scope: SearchScope;
+  filters?: SearchFilter;
+  claims?: GroundedClaimInput[];
+  mode?: GroundedAnswerMode;
+  compare?: GroundedCompareInput;
+  topic?: GroundedTopicInput;
+  budget?: Partial<GroundingBudget>;
+};
+
+export type GroundingRuntime = {
+  answer(input: GroundedAnswerInput): Promise<GroundedAnswer>;
+};

package/src/index.ts

@@ -20,6 +20,70 @@ export type {
   AIMessage,
   AIResult,
 } from "./reactive.js";
+export type {
+  SearchPrimitive,
+  SearchScope,
+  SearchFilter,
+  SearchOptions,
+  VectorSearchOptions,
+  HybridSearchOptions,
+  SearchHit,
+  SearchResponse,
+  SearchTierConfig,
+} from "./search-types.js";
+export type {
+  DocumentVisibility,
+  DocumentConvertMode,
+  DocumentConvertProvider,
+  DocumentResolvedProvider,
+  DocumentConvertInput,
+  DocumentPage,
+  DocumentSection,
+  DocumentProviderTrace,
+  DocumentConvertResult,
+  DocumentCacheArtifact,
+  DocumentCacheKeyInput,
+  GencowServicesCtx,
+  WorkflowDocumentServicesCtx,
+} from "./document-types.js";
+export { buildDocumentCacheKey } from "./document-types.js";
+export type {
+  RagIngestReindexMode,
+  RagIngestInput,
+  RagIngestWorkflowArgs,
+  RagIngestStartResult,
+  RagIngestJobStatus,
+  RagIngestJobRecord,
+} from "./rag-ingest-types.js";
+export type {
+  CitationCoverage,
+  ClaimSupportStatus,
+  GroundedAnswerMode,
+  Citation,
+  ClaimEvidenceMap,
+  GroundedAnswer,
+  GroundingBudget,
+  GroundedClaimInput,
+  GroundedCompareInput,
+  GroundedTopicInput,
+  GroundedAnswerInput,
+  GroundingRuntime,
+} from "./grounded-answer-types.js";
+export { DEFAULT_GROUNDING_BUDGET } from "./grounded-answer-types.js";
+export type {
+  RagOperationKind,
+  RagOperationMetricUnit,
+  RagIndexHealth,
+  RagOperationMetric,
+  RagOperationsSummary,
+  RagEvaluationExpectedClaim,
+  RagEvaluationFixture,
+  RagEvaluationFixtureResult,
+  RagEvaluationRunResult,
+  RagReindexMode,
+  RagReindexPlan,
+} from "./rag-operations-types.js";
+export { ragCorpora, ragSources, ragSections, ragChunks, ragIngestJobs, ragOperationMetrics } from "./rag-schema.js";
 export {
   query,
   mutation,
@@ -36,7 +100,7 @@ export {
   getRegisteredMutations,
   getRegisteredHttpActions,
 } from "./reactive.js";
-export type { Storage } from "./storage.js";
+export type { Storage, StoredFile } from "./storage.js";
 export { createScheduler, getSchedulerInfo } from "./scheduler.js";
 export type {
   Scheduler,
@@ -82,6 +146,7 @@ export { v, parseArgs, GencowValidationError } from "./v.js";
 export type { Validator, Infer, InferArgs } from "./v.js";
 export { withRetry } from "./retry.js";
 export type { RetryOptions } from "./retry.js";
+export { filterTenantRuntimeEnvVars, isReservedTenantRuntimeEnvKey } from "./runtime-env-policy.js";
 export { cronJobs } from "./crons.js";
 export type { CronJobsBuilder, CronJobDef, IntervalOptions, DailyOptions, WeeklyOptions } from "./crons.js";
 export { defineAuth } from "./auth-config.js";

package/src/rag-ingest-types.ts

@@ -0,0 +1,52 @@
+import type { DocumentConvertProvider, DocumentConvertMode, DocumentProviderTrace, DocumentVisibility } from "./document-types.js";
+
+export type RagIngestReindexMode = "if_changed" | "force";
+export type RagIngestJobStatus =
+  | "queued"
+  | "converting"
+  | "chunking"
+  | "embedding"
+  | "upserting"
+  | "completed"
+  | "failed"
+  | "canceled";
+
+export type RagIngestInput = {
+  storageId: string;
+  corpus: string;
+  visibility: DocumentVisibility;
+  ownerUserId?: string;
+  sourceKey?: string;
+  metadata?: Record<string, unknown>;
+  reindexMode?: RagIngestReindexMode;
+  mode?: DocumentConvertMode;
+  provider?: DocumentConvertProvider;
+};
+
+export type RagIngestWorkflowArgs = RagIngestInput & {
+  jobId: string;
+  sourceId: string;
+};
+
+export type RagIngestStartResult = {
+  workflowId: string;
+  jobId: string;
+  sourceId: string;
+  status: "queued";
+};
+
+export type RagIngestJobRecord = {
+  id: string;
+  workflowId: string;
+  sourceId: string;
+  corpus: string;
+  visibility: DocumentVisibility;
+  ownerUserId: string | null;
+  status: RagIngestJobStatus;
+  stage: string;
+  providerTrace: Partial<DocumentProviderTrace> | Record<string, never>;
+  metrics: Record<string, unknown>;
+  error: string | null;
+  startedAt: string;
+  completedAt: string | null;
+};

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.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 Validator, 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";
 
 // ─── GencowCtx — 사용자 함수에 주입되는 컨텍스트 ──────────
 
@@ -107,8 +110,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;
 }
 
 // ─── Types ──────────────────────────────────────────────

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);

package/src/runtime-env-policy.ts

@@ -0,0 +1,66 @@
+const RESERVED_TENANT_RUNTIME_ENV_KEYS = new Set([
+  "PORT",
+  "DATABASE_URL",
+  "GENCOW_DB_URL",
+  "BETTER_AUTH_SECRET",
+  "BETTER_AUTH_URL",
+  "IS_PLATFORM",
+  "GENCOW_PLATFORM_CONFIG_FILE",
+  "GENCOW_PLATFORM_URL",
+  "GENCOW_PLATFORM_DB",
+  "PLATFORM_OPENAI_KEY",
+  "PLATFORM_GOOGLE_KEY",
+  "PLATFORM_INTERNAL_SECRET",
+  "INVITE_ONLY",
+  "RUNNER_TYPE",
+  "PGBOUNCER_PORT",
+  "GENCOW_FUNCTIONS",
+  "GENCOW_STORAGE",
+  "GENCOW_MIGRATIONS",
+  "GENCOW_APP_NAME",
+  "GENCOW_APP_DATA_DIR",
+  "GENCOW_INTERNAL_TOKEN",
+  "GENCOW_CRON_TOKEN",
+  "GENCOW_AI_PROXY_URL",
+  "GENCOW_AI_PROXY_URL_ALT",
+  "GENCOW_AI_PROXY_TOKEN",
+  "GENCOW_METERING_URL",
+  "GENCOW_METERING_URL_ALT",
+  "GENCOW_START_REASON",
+  "GENCOW_RESTART_ID",
+  "GENCOW_SHUTDOWN_MARKER_PATH",
+  "GENCOW_SKIP_MIGRATION",
+  "GENCOW_DB_MAX_CONNECTIONS",
+  "GENCOW_MEMORY_MB",
+  "BUN_JSC_forceRAMSize",
+  "MIMALLOC_PURGE_DELAY",
+  "NODE_PATH",
+]);
+
+const RESERVED_TENANT_RUNTIME_ENV_PREFIXES = ["__GENCOW_", "GENCOW_DOCUMENT_", "GENCOW_WARM_"];
+
+export function isReservedTenantRuntimeEnvKey(key: string): boolean {
+  const normalized = key.trim();
+  return (
+    RESERVED_TENANT_RUNTIME_ENV_KEYS.has(normalized) ||
+    RESERVED_TENANT_RUNTIME_ENV_PREFIXES.some((prefix) => normalized.startsWith(prefix))
+  );
+}
+
+export function filterTenantRuntimeEnvVars(vars: Record<string, string>): {
+  allowed: Record<string, string>;
+  rejectedKeys: string[];
+} {
+  const allowed: Record<string, string> = {};
+  const rejectedKeys: string[] = [];
+
+  for (const [key, value] of Object.entries(vars)) {
+    if (isReservedTenantRuntimeEnvKey(key)) {
+      rejectedKeys.push(key);
+      continue;
+    }
+    allowed[key] = value;
+  }
+
+  return { allowed, rejectedKeys };
+}

package/src/search-types.ts

@@ -0,0 +1,91 @@
+export type SearchPrimitive = string | number | boolean;
+
+export type SearchScope = {
+  corpus: string;
+  visibility: "private" | "shared" | "public";
+  ownerUserId?: string;
+};
+
+export type SearchFilter = {
+  eq?: Record<string, SearchPrimitive>;
+  in?: Record<string, SearchPrimitive[]>;
+  range?: Record<string, { gte?: string | number; lte?: string | number }>;
+};
+
+export type SearchOptions = {
+  fields: [string, ...string[]];
+  limit?: number;
+  offset?: number;
+  filters?: SearchFilter;
+  scope: SearchScope;
+};
+
+export type VectorSearchTuning = {
+  minScore?: number;
+};
+
+export type VectorSearchOptions = Omit<SearchOptions, "fields"> & {
+  vector: number[];
+  vectorField?: string;
+  tuning?: VectorSearchTuning;
+};
+
+export type HybridSearchFusionTuning = {
+  mode?: "rrf";
+  rrfK?: number;
+  keywordWeight?: number;
+  vectorWeight?: number;
+};
+
+export type HybridSearchTuning = {
+  keywordCandidateLimit?: number;
+  vectorCandidateLimit?: number;
+  minFusedScore?: number;
+  fusion?: HybridSearchFusionTuning;
+};
+
+export type HybridSearchOptions = SearchOptions & {
+  vector: number[];
+  vectorField?: string;
+  fusion?: "rrf"; // legacy top-level compatibility
+  keywordCandidateLimit?: number; // legacy top-level compatibility
+  vectorCandidateLimit?: number; // legacy top-level compatibility
+  tuning?: HybridSearchTuning;
+};
+
+export type SearchHit = {
+  id: string | number;
+  row: Record<string, unknown>;
+  score: number;
+  scores?: {
+    keyword?: number;
+    vector?: number;
+    fused?: number;
+  };
+  matchedBy: Array<"keyword" | "vector">;
+};
+
+export type SearchResponse = {
+  items: SearchHit[];
+  meta: {
+    engine: "tsvector" | "pgroonga";
+    tier: "free" | "pro" | "scale";
+    limit: number;
+    offset: number;
+    nextOffset?: number;
+    fusion?: "rrf";
+    mode?: "keyword" | "vector" | "hybrid";
+  };
+};
+
+export type SearchTierConfig = {
+  plan: "free" | "pro" | "scale";
+  engine: "tsvector" | "pgroonga";
+  hybridSearch: boolean;
+  locale: "english" | "multilingual";
+  extensions: {
+    vector: boolean;
+    pgroonga: boolean;
+  };
+  degradedReason?: string;
+};

package/src/server.ts

@@ -6,6 +6,5 @@
  * bundled into user functions which run in Firecracker.
  */
 export { createStorage, storageRoutes } from "./storage.js";
-export type { StorageImageTierConfig } from "./storage.js";
+export type { StorageImageTierConfig, StoredFile } from "./storage.js";
 export { createScheduler, getSchedulerInfo } from "./scheduler.js";
-export { authMiddleware, authRoutes, getUsers } from "./auth.js";