@gencow/core 0.1.27 → 0.1.28

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.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;
@@ -101,8 +104,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>;

package/dist/rls-db.d.ts

@@ -1,4 +1,3 @@
-import type { PgAsyncDatabase } from "drizzle-orm/pg-core";
 /**
  * RLS DB wrapper — execution paths for `withRlsConnection`:
  * 1. **Reuse outer Drizzle transaction** (`reuseOuterConnection`): same connection, apply GUCs then run `fn`.
@@ -24,6 +23,13 @@ export type RlsSessionContext = {
      */
     vars?: Record<string, string>;
 };
+type RlsDrizzleDatabaseLike = {
+    session: unknown;
+    _: {
+        session?: unknown;
+    };
+    transaction: (callback: (tx: unknown) => unknown | Promise<unknown>, ...rest: unknown[]) => Promise<unknown>;
+};
 /**
  * pg `Pool.connect()`-style client: BEGIN → apply RLS GUCs → `fn` → COMMIT on success,
  * or ROLLBACK if anything fails (including failed COMMIT). Always `release()` in `finally`.
@@ -44,4 +50,5 @@ export declare function withRlsLeasedConnection<T>(leased: {
  *
  * `db.transaction()` still injects the same variables at the start of the callback transaction.
  */
-export declare function createRlsDb(db: PgAsyncDatabase<any, any, any, any>, rls: RlsSessionContext): PgAsyncDatabase<any, any, any, any>;
+export declare function createRlsDb<TDb extends RlsDrizzleDatabaseLike>(db: TDb, rls: RlsSessionContext): TDb;
+export {};

package/dist/runtime-env-policy.d.ts

@@ -0,0 +1,5 @@
+export declare function isReservedTenantRuntimeEnvKey(key: string): boolean;
+export declare function filterTenantRuntimeEnvVars(vars: Record<string, string>): {
+    allowed: Record<string, string>;
+    rejectedKeys: string[];
+};

package/dist/runtime-env-policy.js

@@ -0,0 +1,56 @@
+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) {
+    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) {
+    const allowed = {};
+    const rejectedKeys = [];
+    for (const [key, value] of Object.entries(vars)) {
+        if (isReservedTenantRuntimeEnvKey(key)) {
+            rejectedKeys.push(key);
+            continue;
+        }
+        allowed[key] = value;
+    }
+    return { allowed, rejectedKeys };
+}

package/dist/search-types.d.ts

@@ -0,0 +1,83 @@
+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";
+    keywordCandidateLimit?: number;
+    vectorCandidateLimit?: number;
+    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/dist/search-types.js

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

package/dist/server.d.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";

package/dist/server.js

@@ -7,4 +7,3 @@
  */
 export { createStorage, storageRoutes } from "./storage.js";
 export { createScheduler, getSchedulerInfo } from "./scheduler.js";
-export { authMiddleware, authRoutes, getUsers } from "./auth.js";

package/dist/storage-shared.d.ts

@@ -0,0 +1,36 @@
+/** 파일 업로드 최대 크기: 50MB (하드코딩 — 사용자가 오버라이드 불가) */
+export declare const MAX_FILE_SIZE: number;
+/** 기본 스토리지 쿼터: 1GB */
+export declare const DEFAULT_STORAGE_QUOTA: number;
+export interface StorageFile {
+    id: string;
+    name: string;
+    size: number;
+    type: string;
+    path: string;
+}
+export interface StoredFile {
+    id: string;
+    name: string;
+    size: number;
+    type: string;
+    buffer: Buffer;
+}
+export interface StorageOptions {
+    rawSql?: (sql: string, params?: unknown[]) => Promise<unknown[]>;
+    storageQuota?: number;
+}
+export interface Storage {
+    store(file: File | Blob, filename?: string): Promise<string>;
+    storeBuffer(buffer: Buffer, filename: string, type?: string): Promise<string>;
+    get(storageId: string): Promise<StoredFile | null>;
+    getUrl(storageId: string): string;
+    getMeta(storageId: string): Promise<StorageFile | null>;
+    delete(storageId: string): Promise<void>;
+}
+export declare function formatBytes(bytes: number): string;
+export declare function loadStorageMeta(params: {
+    storageId: string;
+    dir: string;
+    metaStore: Map<string, StorageFile>;
+}): Promise<StorageFile | null>;

package/dist/storage-shared.js

@@ -0,0 +1,39 @@
+import * as fs from "fs/promises";
+import * as path from "path";
+/** 파일 업로드 최대 크기: 50MB (하드코딩 — 사용자가 오버라이드 불가) */
+export const MAX_FILE_SIZE = 50 * 1024 * 1024;
+/** 기본 스토리지 쿼터: 1GB */
+export const DEFAULT_STORAGE_QUOTA = 1024 * 1024 * 1024;
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes}B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)}KB`;
+    if (bytes < 1024 * 1024 * 1024)
+        return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+    return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)}GB`;
+}
+export async function loadStorageMeta(params) {
+    const cached = params.metaStore.get(params.storageId);
+    if (cached) {
+        return cached;
+    }
+    const filePath = path.join(params.dir, params.storageId);
+    try {
+        const raw = await fs.readFile(`${filePath}.meta`, "utf-8");
+        const parsed = JSON.parse(raw);
+        const stat = await fs.stat(filePath);
+        const meta = {
+            id: params.storageId,
+            name: typeof parsed.name === "string" ? parsed.name : params.storageId,
+            size: typeof parsed.size === "number" ? parsed.size : stat.size,
+            type: typeof parsed.type === "string" ? parsed.type : "application/octet-stream",
+            path: filePath,
+        };
+        params.metaStore.set(params.storageId, meta);
+        return meta;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/storage.d.ts

@@ -1,28 +1,5 @@
-interface StorageFile {
-    id: string;
-    name: string;
-    size: number;
-    type: string;
-    path: string;
-}
-export interface StorageOptions {
-    /** Raw SQL 실행 함수 — DB 자동 기록 + 쿼터 검증에 필요 */
-    rawSql?: (sql: string, params?: unknown[]) => Promise<unknown[]>;
-    /** 앱별 스토리지 쿼터 (bytes). 0 = 무제한. 기본: 1GB */
-    storageQuota?: number;
-}
-export interface Storage {
-    /** Store a file and return a storageId — Convex의 ctx.storage.store() */
-    store(file: File | Blob, filename?: string): Promise<string>;
-    /** Store from raw buffer */
-    storeBuffer(buffer: Buffer, filename: string, type?: string): Promise<string>;
-    /** Get a serving URL for the file — Convex의 ctx.storage.getUrl() */
-    getUrl(storageId: string): string;
-    /** Get file metadata */
-    getMeta(storageId: string): Promise<StorageFile | null>;
-    /** Delete a stored file — Convex의 ctx.storage.delete() */
-    delete(storageId: string): Promise<void>;
-}
+import type { Storage, StorageOptions } from "./storage-shared.js";
+export type { Storage, StorageFile, StorageOptions, StoredFile } from "./storage-shared.js";
 /**
  * Create a storage instance — Convex storage 패턴 재현
  *
@@ -75,4 +52,3 @@ export declare function storageRoutes(storage: ReturnType<typeof createStorage>,
     json: (data: unknown, status?: number) => Response;
     body: (data: unknown, status: number, headers: Record<string, string>) => Response;
 }) => Promise<Response>;
-export {};

package/dist/storage.js

@@ -2,20 +2,7 @@ import * as fs from "fs/promises";
 import * as fsSync from "fs";
 import * as path from "path";
 import * as crypto from "crypto";
-// ─── Constants ──────────────────────────────────────────
-/** 파일 업로드 최대 크기: 50MB (하드코딩 — 사용자가 오버라이드 불가) */
-const MAX_FILE_SIZE = 50 * 1024 * 1024;
-/** 기본 스토리지 쿼터: 1GB */
-const DEFAULT_STORAGE_QUOTA = 1024 * 1024 * 1024;
-function formatBytes(bytes) {
-    if (bytes < 1024)
-        return `${bytes}B`;
-    if (bytes < 1024 * 1024)
-        return `${(bytes / 1024).toFixed(1)}KB`;
-    if (bytes < 1024 * 1024 * 1024)
-        return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
-    return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)}GB`;
-}
+import { DEFAULT_STORAGE_QUOTA, MAX_FILE_SIZE, formatBytes, loadStorageMeta, } from "./storage-shared.js";
 // ─── Implementation ─────────────────────────────────────
 const metaStore = new Map();
 /**
@@ -166,8 +153,25 @@ export function createStorage(dir = "./uploads", options) {
         getUrl(storageId) {
             return `/api/storage/${storageId}`;
         },
+        async get(storageId) {
+            const meta = await loadStorageMeta({ storageId, dir, metaStore });
+            if (!meta) {
+                return null;
+            }
+            const buffer = await fs.readFile(meta.path).catch(() => null);
+            if (!buffer) {
+                return null;
+            }
+            return {
+                id: meta.id,
+                name: meta.name,
+                size: meta.size,
+                type: meta.type,
+                buffer,
+            };
+        },
         async getMeta(storageId) {
-            return metaStore.get(storageId) || null;
+            return loadStorageMeta({ storageId, dir, metaStore });
         },
         async delete(storageId) {
             const meta = metaStore.get(storageId);

package/dist/workflow-types.d.ts

@@ -1,4 +1,5 @@
 import type { GencowCtx } from "./reactive.js";
+import type { WorkflowDocumentServicesCtx } from "./document-types.js";
 import type { InferArgs } from "./v.js";
 export type WorkflowStatus = "pending" | "running" | "completed" | "failed";
 export type WorkflowDuration = number | string;
@@ -53,9 +54,10 @@ export interface WorkflowSignalResult {
 export interface WorkflowResumePayload {
     workflowId: string;
 }
-export interface WorkflowCtx extends GencowCtx {
+export interface WorkflowCtx extends Omit<GencowCtx, "services"> {
     workflowId: string;
     workflowName: string;
+    services: GencowCtx["services"] & WorkflowDocumentServicesCtx;
     step<TResult>(name: string, run: () => Promise<TResult>): Promise<TResult>;
     sleep(duration: WorkflowDuration): Promise<void>;
     waitForEvent<TPayload = unknown>(name: string, timeout?: WorkflowDuration): Promise<TPayload>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gencow/core",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "description": "Gencow core library — defineQuery, defineMutation, reactive subscriptions",
   "type": "module",
   "main": "dist/index.js",
@@ -21,6 +21,12 @@
     "dist/",
     "src/"
   ],
+  "scripts": {
+    "db:generate:fixture-basic": "drizzle-kit generate --config ./src/__tests__/fixtures/basic/drizzle.config.ts",
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
   "dependencies": {
     "node-cron": "^4.2.1"
   },
@@ -39,10 +45,5 @@
     "hono": "^4.12.0",
     "typescript": "^5.9.3",
     "uuid": "^13.0.0"
-  },
-  "scripts": {
-    "db:generate:fixture-basic": "drizzle-kit generate --config ./src/__tests__/fixtures/basic/drizzle.config.ts",
-    "build": "tsc",
-    "typecheck": "tsc --noEmit"
   }
-}
+}

package/src/document-types.ts

@@ -0,0 +1,95 @@
+export type DocumentVisibility = "private" | "shared" | "public";
+export type DocumentConvertMode =
+  | "auto"
+  | "text-only"
+  | "no-external-provider"
+  | "prefer-external"
+  | "force-external"
+  | "force-ocr";
+export type DocumentConvertProvider = "auto" | "local_text" | "gemini" | "openai" | "ocr" | "custom_vlm";
+export type DocumentResolvedProvider = Exclude<DocumentConvertProvider, "auto">;
+export type DocumentProviderRoute = "local_text" | "vlm" | "ocr_fallback";
+export type DocumentCacheArtifact = "convert" | "embedding" | "summary" | "rerank";
+
+export type DocumentConvertInput = {
+  storageId: string;
+  filename?: string;
+  mimeType?: string;
+  corpus: string;
+  visibility: DocumentVisibility;
+  ownerUserId?: string;
+  mode?: DocumentConvertMode;
+  provider?: DocumentConvertProvider;
+};
+
+export type DocumentPage = {
+  page: number;
+  charStart: number;
+  charEnd: number;
+  previewText?: string;
+};
+
+export type DocumentSection = {
+  id: string;
+  title?: string;
+  depth: number;
+  path: string[];
+  pageStart?: number;
+  pageEnd?: number;
+  charStart: number;
+  charEnd: number;
+};
+
+export type DocumentProviderTrace = {
+  provider: DocumentResolvedProvider;
+  route: DocumentProviderRoute;
+  external: boolean;
+  requestId?: string;
+  durationMs: number;
+  bytes: number;
+};
+
+export type DocumentConvertResult = {
+  text: string;
+  markdown: string;
+  pages: DocumentPage[];
+  sections: DocumentSection[];
+  warnings: string[];
+  providerTrace: DocumentProviderTrace;
+};
+
+export interface GencowServicesCtx {}
+
+export interface WorkflowDocumentServicesCtx {
+  document: {
+    convert(input: DocumentConvertInput): Promise<DocumentConvertResult>;
+  };
+}
+
+export type DocumentCacheKeyInput = {
+  appId: string;
+  ownerUserId?: string | null;
+  corpus: string;
+  sourceKey: string;
+  checksum: string;
+  provider: DocumentResolvedProvider;
+  artifact: DocumentCacheArtifact;
+};
+
+function normalizeCachePart(value: string): string {
+  return value.trim() || "unknown";
+}
+
+export function buildDocumentCacheKey(input: DocumentCacheKeyInput): string {
+  const owner = input.ownerUserId?.trim() ? input.ownerUserId.trim() : "shared";
+
+  return [
+    `app:${normalizeCachePart(input.appId)}`,
+    `user:${normalizeCachePart(owner)}`,
+    `corpus:${normalizeCachePart(input.corpus)}`,
+    `source:${normalizeCachePart(input.sourceKey)}`,
+    `checksum:${normalizeCachePart(input.checksum)}`,
+    `provider:${normalizeCachePart(input.provider)}`,
+    `artifact:${normalizeCachePart(input.artifact)}`,
+  ].join(":");
+}