import "#veryfront/schemas/_test-setup.ts"; import { assert, assertEquals, assertRejects } from "#veryfront/testing/assert.ts"; import { afterEach, describe, it } from "#veryfront/testing/bdd.ts"; import { exists, readTextFile, withTempDir } from "#veryfront/testing/deno-compat.ts"; import { withMockFetch } from "#veryfront/testing/mock-fetch.ts"; import { deleteEnv, setEnv } from "#veryfront/compat/process.ts"; import { join } from "#veryfront/compat/path"; import { VeryfrontError } from "#veryfront/errors"; import { projectKnowledge } from "#veryfront/knowledge/index.ts"; import { runWithRequestContext } from "#veryfront/platform/adapters/fs/veryfront/multi-project-adapter.ts"; import { runWithVeryfrontCloudContext } from "#veryfront/provider/veryfront-cloud/context.ts"; import { withLocalJsonStoreLock } from "./local-json-store-lock.ts"; import { ragStore } from "./rag-store.ts"; import { createVeryfrontCloudRagStore } from "./veryfront-cloud/rag-store.ts"; import { ensureBuiltinLLMProviders } from "#veryfront/extensions/builtin-extensions.ts"; import { clearEmbeddingProviders, registerEmbeddingProvider } from "./resolve.ts"; const CLOUD_ENV_KEYS = [ "VERYFRONT_API_TOKEN", "VERYFRONT_PROJECT_SLUG", "VERYFRONT_RAG_BACKEND", "VERYFRONT_SERVICE_LAYER", ] as const; function clearCloudEnv(): void { for (const key of CLOUD_ENV_KEYS) { try { deleteEnv(key); } catch { // expected: env may already be unset } } } function registerTestEmbeddingProvider(): void { registerEmbeddingProvider("test", () => ({ specificationVersion: "v2", provider: "test", modelId: "test/demo", maxEmbeddingsPerCall: undefined, supportsParallelCalls: true, async doEmbed({ values }: { values: string[] }) { return { embeddings: values.map((value, index) => { const vector = new Array(1536).fill(index); vector[0] = value.length; return vector; }), usage: { tokens: 0 }, rawResponse: undefined, warnings: [], }; }, }) as never); } function registerTestLocalEmbeddingProvider(): void { registerEmbeddingProvider("local", () => ({ specificationVersion: "v2", provider: "local", modelId: "local/test-auto", maxEmbeddingsPerCall: undefined, supportsParallelCalls: true, async doEmbed({ values }: { values: string[] }) { return { embeddings: values.map((value, index) => { const vector = new Array(384).fill(index); vector[0] = value.length; return vector; }), usage: { tokens: 0 }, rawResponse: undefined, warnings: [], }; }, }) as never); } describe("ragStore", () => { afterEach(() => { clearCloudEnv(); clearEmbeddingProviders(); }); it("returns empty uploads when storage file does not exist", async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); const store = ragStore({ model: "local/test-model", storagePath, }); const documents = await store.listDocuments(); assertEquals(documents, []); }); }); it("creates the storage directory during first ingest", async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); const store = ragStore({ model: "local/test-model", storagePath, }); const id = await store.ingest("Doc", "Hello world"); assert(id.length > 0); assertEquals(await exists(storagePath), true); assertEquals((await store.listDocuments()).map((document) => document.id), [id]); }); }); it("treats a missing temp cleanup directory as empty", async () => { await withTempDir(async (tempDir) => { const storageDirectory = join(tempDir, "data"); const storagePath = join(storageDirectory, "index.json"); const store = ragStore({ model: "local/test-model", storagePath, }); const readDirDescriptor = Object.getOwnPropertyDescriptor(Deno, "readDir"); assert(readDirDescriptor !== undefined); const originalReadDir = Deno.readDir.bind(Deno); Object.defineProperty(Deno, "readDir", { ...readDirDescriptor, value: (path: string | URL) => String(path) === storageDirectory ? ({ [Symbol.asyncIterator]() { return { next() { return Promise.reject( new Deno.errors.NotFound("missing storage directory"), ); }, }; }, } satisfies AsyncIterable) : originalReadDir(path), }); try { const id = await store.ingest("Doc", "Hello world"); assert(id.length > 0); assertEquals(await exists(storagePath), true); } finally { Object.defineProperty(Deno, "readDir", readDirDescriptor); } }); }); for (const phase of ["open", "iteration"] as const) { it(`retries when a lock directory disappears during readDir ${phase}`, async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); const lockDirectory = `${storagePath}.veryfront-rag.lock`; await Deno.mkdir(lockDirectory, { recursive: true }); await Deno.writeTextFile( join(lockDirectory, `.owner.recovering.${crypto.randomUUID()}`), `${JSON.stringify({ token: crypto.randomUUID(), createdAtMs: 0 })}\n`, ); const readDirDescriptor = Object.getOwnPropertyDescriptor(Deno, "readDir"); assert(readDirDescriptor !== undefined); const originalReadDir = Deno.readDir.bind(Deno); let changed = false; Object.defineProperty(Deno, "readDir", { ...readDirDescriptor, value: (path: string | URL) => { if (!changed && String(path) === lockDirectory) { changed = true; if (phase === "open") { return { [Symbol.asyncIterator]() { return { async next() { await Deno.remove(lockDirectory, { recursive: true }); throw new Deno.errors.NotFound("lock directory disappeared"); }, }; }, } satisfies AsyncIterable; } const entries = originalReadDir(path); return (async function* () { for await (const entry of entries) { yield entry; await Deno.remove(lockDirectory, { recursive: true }); throw new Deno.errors.NotFound("lock directory disappeared"); } })(); } return originalReadDir(path); }, }); try { await withLocalJsonStoreLock(storagePath, async () => undefined); assertEquals(changed, true); assertEquals(await exists(lockDirectory), false); } finally { Object.defineProperty(Deno, "readDir", readDirDescriptor); } }); }); } it("retries when a listed lock lease disappears before lstat", async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); const lockDirectory = `${storagePath}.veryfront-rag.lock`; const leasePath = join(lockDirectory, `${crypto.randomUUID()}.lease`); await Deno.mkdir(lockDirectory, { recursive: true }); await Deno.writeTextFile(join(lockDirectory, "owner.json"), "{"); await Deno.writeTextFile(leasePath, "live\n"); const lstatDescriptor = Object.getOwnPropertyDescriptor(Deno, "lstat"); assert(lstatDescriptor !== undefined); const originalLstat = Deno.lstat.bind(Deno); let changed = false; Object.defineProperty(Deno, "lstat", { ...lstatDescriptor, value: async (path: string | URL) => { if (!changed && String(path) === leasePath) { changed = true; await Deno.remove(lockDirectory, { recursive: true }); throw new Deno.errors.NotFound("lock lease disappeared"); } return await originalLstat(path); }, }); try { await withLocalJsonStoreLock(storagePath, async () => undefined); assertEquals(changed, true); assertEquals(await exists(lockDirectory), false); } finally { Object.defineProperty(Deno, "lstat", lstatDescriptor); } }); }); it("removes an owner-only lock when the lease write fails", async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); const lockDirectory = `${storagePath}.veryfront-rag.lock`; const writeTextFileDescriptor = Object.getOwnPropertyDescriptor(Deno, "writeTextFile"); assert(writeTextFileDescriptor !== undefined); const originalWriteTextFile = Deno.writeTextFile.bind(Deno); Object.defineProperty(Deno, "writeTextFile", { ...writeTextFileDescriptor, value: ( path: string | URL, data: string, options?: Deno.WriteFileOptions, ) => { if (String(path).endsWith(".lease")) { return Promise.reject(new Error("lease write failed")); } return originalWriteTextFile(path, data, options); }, }); try { await assertRejects( () => withLocalJsonStoreLock(storagePath, async () => undefined), Error, "lease write failed", ); assertEquals(await exists(lockDirectory), false); } finally { Object.defineProperty(Deno, "writeTextFile", writeTextFileDescriptor); } }); }); it("rejects invalid document sizes before local store writes", async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); const store = ragStore({ model: "local/test-model", storagePath, }); for (const size of [-1, 1.5, NaN, Infinity]) { const error = await assertRejects( () => store.ingest("Doc", "Hello world", { size }), VeryfrontError, "RAG document size must be a non-negative integer", ); assert(error instanceof VeryfrontError); assertEquals(error.slug, "invalid-argument"); } assertEquals(await exists(storagePath), false); }); }); it("accepts zero as a local document size", async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); const store = ragStore({ model: "local/test-model", storagePath, }); const id = await store.ingest("Empty file", "Hello world", { size: 0 }); const documents = await store.listDocuments(); assertEquals(documents.length, 1); assertEquals(documents[0]?.id, id); assertEquals(documents[0]?.title, "Empty file"); assertEquals(documents[0]?.size, 0); }); }); it("persists ingest with atomic temp+rename workflow", async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); const store = ragStore({ model: "local/test-model", storagePath, }); const id = await store.ingest("Doc", "Hello world", { source: "upload:test.txt", type: "txt", }); assert(id.length > 0); const documents = await store.listDocuments(); assertEquals(documents.length, 1); assertEquals(documents[0]?.id, id); const persisted = await readTextFile(storagePath); const parsed = JSON.parse(persisted) as { documents: unknown[]; chunks: unknown[]; }; assertEquals(Array.isArray(parsed.documents), true); assertEquals(Array.isArray(parsed.chunks), true); assertEquals(persisted, JSON.stringify(parsed)); assertEquals(await exists(storagePath + ".tmp"), false); }); }); it("preserves the live store when its atomic replacement fails", async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); await Deno.mkdir(join(tempDir, "data"), { recursive: true }); const original = JSON.stringify({ documents: [], chunks: [] }); await Deno.writeTextFile(storagePath, original); const store = ragStore({ model: "local/test-model", storagePath, }); const renameDescriptor = Object.getOwnPropertyDescriptor(Deno, "rename"); assert(renameDescriptor !== undefined); const originalRename = Deno.rename.bind(Deno); Object.defineProperty(Deno, "rename", { ...renameDescriptor, value: (from: string | URL, to: string | URL) => String(to) === storagePath ? Promise.reject(new Error("simulated rename failure")) : originalRename(from, to), }); try { const error = await assertRejects( () => store.ingest("Must not persist", "replacement content"), VeryfrontError, "could not be completed safely", ); assert(error instanceof VeryfrontError); assertEquals(error.slug, "rag-store-unavailable"); assertEquals(error.message.includes(storagePath), false); } finally { Object.defineProperty(Deno, "rename", renameDescriptor); } assertEquals(await readTextFile(storagePath), original); const entries: string[] = []; for await (const entry of Deno.readDir(join(tempDir, "data"))) { entries.push(entry.name); } assertEquals(entries, ["index.json"]); }); }); it("cleans a partially written unique temp file without touching the live store", async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); await Deno.mkdir(join(tempDir, "data"), { recursive: true }); const original = JSON.stringify({ documents: [], chunks: [] }); await Deno.writeTextFile(storagePath, original); const store = ragStore({ model: "local/test-model", storagePath }); const writeDescriptor = Object.getOwnPropertyDescriptor(Deno, "writeTextFile"); assert(writeDescriptor !== undefined); const originalWrite = Deno.writeTextFile.bind(Deno); Object.defineProperty(Deno, "writeTextFile", { ...writeDescriptor, value: async (path: string | URL, data: string, options?: Deno.WriteFileOptions) => { if (String(path).includes(".tmp.")) { await originalWrite(path, "partial", options); throw new Error("simulated partial temp write"); } await originalWrite(path, data, options); }, }); try { const error = await assertRejects( () => store.ingest("Must not persist", "replacement content"), VeryfrontError, "could not be completed safely", ); assert(error instanceof VeryfrontError); assertEquals(error.slug, "rag-store-unavailable"); assertEquals(error.message.includes(storagePath), false); } finally { Object.defineProperty(Deno, "writeTextFile", writeDescriptor); } assertEquals(await readTextFile(storagePath), original); const entries = await Array.fromAsync(Deno.readDir(join(tempDir, "data"))); assertEquals(entries.map((entry) => entry.name), ["index.json"]); }); }); it("cleans an orphaned temp file left by an interrupted process", async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); await Deno.mkdir(join(tempDir, "data"), { recursive: true }); const original = JSON.stringify({ documents: [], chunks: [] }); const orphanPath = `${storagePath}.tmp.${crypto.randomUUID()}`; await Deno.writeTextFile(storagePath, original); await Deno.writeTextFile(orphanPath, "partial"); const store = ragStore({ model: "local/test-model", storagePath }); assertEquals(await store.listDocuments(), []); assertEquals(await readTextFile(storagePath), original); assertEquals(await exists(orphanPath), false); }); }); it("serializes concurrent store instances targeting the same local index", async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); const first = ragStore({ model: "local/test-model", storagePath }); const second = ragStore({ model: "local/test-model", storagePath }); await Promise.all([ first.ingest("First", "first content"), second.ingest("Second", "second content"), ]); const persisted = JSON.parse(await readTextFile(storagePath)) as { documents: Array<{ title: string }>; }; assertEquals(persisted.documents.map((document) => document.title).sort(), [ "First", "Second", ]); }); }); it("keeps writer failures visible when Deno dependency diagnostics are quiet", async () => { const result = await new Deno.Command(Deno.execPath(), { args: [ "eval", "--quiet", 'console.error("writer runtime diagnostic"); throw new Error("writer runtime failure");', ], cwd: Deno.cwd(), stdout: "piped", stderr: "piped", }).output(); const stderr = new TextDecoder().decode(result.stderr); assertEquals(result.success, false); assert(stderr.includes("writer runtime diagnostic")); assert(stderr.includes("writer runtime failure")); }); it("serializes concurrent local-index writers in separate processes", async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); const moduleUrl = new URL("./rag-store.ts", import.meta.url).href; const startAtMs = Date.now() + 250; const commandFor = (title: string) => new Deno.Command(Deno.execPath(), { args: [ "eval", "--quiet", `import { ragStore } from ${JSON.stringify(moduleUrl)};` + `while (Date.now() < ${startAtMs}) await new Promise((resolve) => setTimeout(resolve, 5));` + `await ragStore({backend:"local-json",model:"local/test-model",storagePath:${ JSON.stringify(storagePath) }}).ingest(${JSON.stringify(title)},${JSON.stringify(`${title} content`)});`, ], cwd: Deno.cwd(), stdout: "piped", stderr: "piped", }); const [first, second] = await Promise.all([ commandFor("First process").output(), commandFor("Second process").output(), ]); assertEquals(new TextDecoder().decode(first.stderr), ""); assertEquals(new TextDecoder().decode(second.stderr), ""); assertEquals(first.success, true); assertEquals(second.success, true); const persisted = JSON.parse(await readTextFile(storagePath)) as { documents: Array<{ title: string }>; }; assertEquals(persisted.documents.map((document) => document.title).sort(), [ "First process", "Second process", ]); }); }); it("recovers an expired adjacent store lock before reading", async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); const lockDirectory = `${storagePath}.veryfront-rag.lock`; const token = crypto.randomUUID(); await Deno.mkdir(lockDirectory, { recursive: true }); await Deno.writeTextFile( join(lockDirectory, "owner.json"), `${JSON.stringify({ token, createdAtMs: 1 })}\n`, ); const leasePath = join(lockDirectory, `${token}.lease`); await Deno.writeTextFile(leasePath, "1\n"); await Deno.utime(leasePath, new Date(0), new Date(0)); await Deno.writeTextFile(storagePath, JSON.stringify({ documents: [], chunks: [] })); const store = ragStore({ model: "local/test-model", storagePath }); assertEquals(await store.listDocuments(), []); assertEquals(await exists(lockDirectory), false); assertEquals(await exists(`${lockDirectory}.recovering`), false); }); }); it("recovers a missing lease from immutable owner age without refreshing directory time", async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); const lockDirectory = `${storagePath}.veryfront-rag.lock`; const token = crypto.randomUUID(); await Deno.mkdir(lockDirectory, { recursive: true }); await Deno.writeTextFile( join(lockDirectory, "owner.json"), `${JSON.stringify({ token, createdAtMs: 1 })}\n`, ); const now = new Date(); await Deno.utime(lockDirectory, now, now); await Deno.writeTextFile(storagePath, JSON.stringify({ documents: [], chunks: [] })); const store = ragStore({ model: "local/test-model", storagePath }); assertEquals(await store.listDocuments(), []); assertEquals(await exists(lockDirectory), false); assertEquals(await exists(`${lockDirectory}.recovering`), false); }); }); it("does not fence a fresh lease when owner metadata cannot be trusted", async () => { const ownerCases = [ { name: "malformed JSON", bytes: new TextEncoder().encode("{") }, { name: "invalid UTF-8", bytes: new Uint8Array([0xff]) }, { name: "oversized metadata", bytes: new Uint8Array(4_097).fill(0x61) }, ]; for (const ownerCase of ownerCases) { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, ownerCase.name.replaceAll(" ", "-"), "index.json"); const lockDirectory = `${storagePath}.veryfront-rag.lock`; const leasePath = join(lockDirectory, `${crypto.randomUUID()}.lease`); await Deno.mkdir(lockDirectory, { recursive: true }); await Deno.writeFile(join(lockDirectory, "owner.json"), ownerCase.bytes); await Deno.writeTextFile(leasePath, "live\n"); await Deno.writeTextFile(storagePath, JSON.stringify({ documents: [], chunks: [] })); await Deno.utime(lockDirectory, new Date(0), new Date(0)); const freshTime = new Date(); await Deno.utime(leasePath, freshTime, freshTime); let settled = false; const pendingDocuments = ragStore({ model: "local/test-model", storagePath, }).listDocuments().finally(() => { settled = true; }); await new Promise((resolvePromise) => setTimeout(resolvePromise, 150)); const liveLeaseWasPreserved = await exists(lockDirectory) && await exists(leasePath) && !await exists(`${lockDirectory}.recovering`) && !settled; // Let the pending contender recover naturally after proving that the // fresh lease, rather than the old directory mtime, governed staleness. await Deno.utime(leasePath, new Date(0), new Date(0)); assertEquals(await pendingDocuments, []); assertEquals(liveLeaseWasPreserved, true, ownerCase.name); assertEquals(await exists(lockDirectory), false); assertEquals(await exists(`${lockDirectory}.recovering`), false); }); } }); it("rejects a stale update when the live index changes before publication", async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); await Deno.mkdir(join(tempDir, "data"), { recursive: true }); const original = JSON.stringify({ documents: [], chunks: [] }); const external = JSON.stringify({ documents: [{ id: "external", title: "External", source: "external", type: "txt", createdAt: 1, }], chunks: [], }); await Deno.writeTextFile(storagePath, original); const store = ragStore({ model: "local/test-model", storagePath }); const writeDescriptor = Object.getOwnPropertyDescriptor(Deno, "writeTextFile"); assert(writeDescriptor !== undefined); const originalWrite = Deno.writeTextFile.bind(Deno); Object.defineProperty(Deno, "writeTextFile", { ...writeDescriptor, value: async (path: string | URL, data: string, options?: Deno.WriteFileOptions) => { await originalWrite(path, data, options); if (String(path).includes(".tmp.")) await originalWrite(storagePath, external); }, }); try { const error = await assertRejects( () => store.ingest("Stale", "must not overwrite"), VeryfrontError, "changed while an update was in progress", ); assert(error instanceof VeryfrontError); assertEquals(error.slug, "rag-store-unavailable"); } finally { Object.defineProperty(Deno, "writeTextFile", writeDescriptor); } assertEquals(await readTextFile(storagePath), external); const entries = await Array.fromAsync(Deno.readDir(join(tempDir, "data"))); assertEquals(entries.map((entry) => entry.name), ["index.json"]); }); }); it("compares exact snapshot bytes before publication", async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); await Deno.mkdir(join(tempDir, "data"), { recursive: true }); const original = JSON.stringify({ documents: [], chunks: [] }); const originalBytes = new TextEncoder().encode(original); const externalBytes = new Uint8Array(originalBytes.byteLength + 3); externalBytes.set([0xef, 0xbb, 0xbf]); externalBytes.set(originalBytes, 3); await Deno.writeFile(storagePath, originalBytes); const store = ragStore({ model: "local/test-model", storagePath }); const writeDescriptor = Object.getOwnPropertyDescriptor(Deno, "writeTextFile"); assert(writeDescriptor !== undefined); const originalWrite = Deno.writeTextFile.bind(Deno); Object.defineProperty(Deno, "writeTextFile", { ...writeDescriptor, value: async (path: string | URL, data: string, options?: Deno.WriteFileOptions) => { await originalWrite(path, data, options); if (String(path).includes(".tmp.")) await Deno.writeFile(storagePath, externalBytes); }, }); try { const error = await assertRejects( () => store.ingest("Stale bytes", "must not overwrite"), VeryfrontError, "changed while an update was in progress", ); assert(error instanceof VeryfrontError); assertEquals(error.slug, "rag-store-unavailable"); } finally { Object.defineProperty(Deno, "writeTextFile", writeDescriptor); } assertEquals(await Deno.readFile(storagePath), externalBytes); }); }); it("fences a writer that loses its adjacent lock before publication", async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); const lockDirectory = `${storagePath}.veryfront-rag.lock`; await Deno.mkdir(join(tempDir, "data"), { recursive: true }); const original = JSON.stringify({ documents: [], chunks: [] }); await Deno.writeTextFile(storagePath, original); const store = ragStore({ model: "local/test-model", storagePath }); const writeDescriptor = Object.getOwnPropertyDescriptor(Deno, "writeTextFile"); assert(writeDescriptor !== undefined); const originalWrite = Deno.writeTextFile.bind(Deno); Object.defineProperty(Deno, "writeTextFile", { ...writeDescriptor, value: async (path: string | URL, data: string, options?: Deno.WriteFileOptions) => { await originalWrite(path, data, options); if (!String(path).includes(".tmp.")) return; await Deno.remove(lockDirectory, { recursive: true }); await Deno.mkdir(lockDirectory); const replacementToken = crypto.randomUUID(); await originalWrite( join(lockDirectory, "owner.json"), `${JSON.stringify({ token: replacementToken, createdAtMs: Date.now() })}\n`, ); await originalWrite(join(lockDirectory, `${replacementToken}.lease`), "replacement\n"); }, }); try { const error = await assertRejects( () => store.ingest("Fenced", "must not overwrite"), VeryfrontError, "could not be completed safely", ); assert(error instanceof VeryfrontError); assertEquals(error.slug, "rag-store-unavailable"); } finally { Object.defineProperty(Deno, "writeTextFile", writeDescriptor); } assertEquals(await readTextFile(storagePath), original); const entries = await Array.fromAsync(Deno.readDir(join(tempDir, "data"))); assertEquals( entries.map((entry) => entry.name).filter((name) => name.includes(".tmp.")), [], ); }); }); it("cannot publish after losing the lease in the final check-to-rename gap", async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); const lockDirectory = `${storagePath}.veryfront-rag.lock`; await Deno.mkdir(join(tempDir, "data"), { recursive: true }); const original = JSON.stringify({ documents: [], chunks: [] }); await Deno.writeTextFile(storagePath, original); const store = ragStore({ model: "local/test-model", storagePath }); const renameDescriptor = Object.getOwnPropertyDescriptor(Deno, "rename"); assert(renameDescriptor !== undefined); const originalRename = Deno.rename.bind(Deno); Object.defineProperty(Deno, "rename", { ...renameDescriptor, value: async (from: string | URL, to: string | URL) => { if (String(from).includes(".tmp.") && String(to) === storagePath) { await Deno.remove(lockDirectory, { recursive: true }); await Deno.mkdir(lockDirectory); const replacementToken = crypto.randomUUID(); await Deno.writeTextFile( join(lockDirectory, "owner.json"), `${JSON.stringify({ token: replacementToken, createdAtMs: Date.now() })}\n`, ); await Deno.writeTextFile( join(lockDirectory, `${replacementToken}.lease`), "replacement\n", ); } await originalRename(from, to); }, }); try { const error = await assertRejects( () => store.ingest("Fenced at rename", "must not overwrite"), VeryfrontError, "could not be completed safely", ); assert(error instanceof VeryfrontError); assertEquals(error.slug, "rag-store-unavailable"); assertEquals(error.message.includes(storagePath), false); } finally { Object.defineProperty(Deno, "rename", renameDescriptor); } assertEquals(await readTextFile(storagePath), original); }); }); it("does not delete replacement ownership created in the release gap", async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); const lockDirectory = `${storagePath}.veryfront-rag.lock`; await Deno.mkdir(join(tempDir, "data"), { recursive: true }); await Deno.writeTextFile(storagePath, JSON.stringify({ documents: [], chunks: [] })); const store = ragStore({ model: "local/test-model", storagePath }); const removeDescriptor = Object.getOwnPropertyDescriptor(Deno, "remove"); assert(removeDescriptor !== undefined); const originalRemove = Deno.remove.bind(Deno); const replacementToken = crypto.randomUUID(); const replacementOwner = `${ JSON.stringify({ token: replacementToken, createdAtMs: Date.now(), }) }\n`; let replacementInjected = false; let recursiveLockCleanupAttempted = false; Object.defineProperty(Deno, "remove", { ...removeDescriptor, value: async (path: string | URL, options?: Deno.RemoveOptions) => { const candidate = String(path); if (candidate.startsWith(lockDirectory) && options?.recursive === true) { recursiveLockCleanupAttempted = true; } const generationMarkerWindow = candidate.startsWith( join(lockDirectory, ".owner.releasing."), ); if (!replacementInjected && generationMarkerWindow) { await originalRemove(lockDirectory, { recursive: true }); await Deno.mkdir(lockDirectory); await Deno.writeTextFile( join(lockDirectory, "owner.json"), replacementOwner, ); await Deno.writeTextFile( join(lockDirectory, `${replacementToken}.lease`), "replacement\n", ); replacementInjected = true; } await originalRemove(path, options); }, }); try { assertEquals(await store.listDocuments(), []); } finally { Object.defineProperty(Deno, "remove", removeDescriptor); } assertEquals(replacementInjected, true); assertEquals(recursiveLockCleanupAttempted, false); assertEquals(await readTextFile(join(lockDirectory, "owner.json")), replacementOwner); }); }); it("refreshes an existing local document while preserving its id", async () => { registerTestEmbeddingProvider(); await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); const store = ragStore({ model: "test/demo", storagePath, }); const id = await store.ingest("Deck", "Old slide text", { source: "upload:deck.pptx", type: "pptx", }); await store.search("old"); const embedded = JSON.parse(await readTextFile(storagePath)) as { chunks: Array<{ embedding: number[] }>; }; assertEquals(embedded.chunks[0]?.embedding.length, 1536); const refresh = store.refreshDocument; assert(refresh); await refresh(id, "# New Slide Title\n\nNew body text", { title: "Deck Updated", source: "upload:deck-updated.pptx", type: "pptx", }); const refreshed = JSON.parse(await readTextFile(storagePath)) as { documents: Array< { id: string; title: string; source: string; type: string; createdAt: number } >; chunks: Array<{ documentId: string; text: string; embedding: number[]; index: number }>; }; assertEquals(refreshed.documents.length, 1); assertEquals(refreshed.documents[0]?.id, id); assertEquals(refreshed.documents[0]?.title, "Deck Updated"); assertEquals(refreshed.documents[0]?.source, "upload:deck-updated.pptx"); assertEquals(refreshed.documents[0]?.type, "pptx"); assertEquals(typeof refreshed.documents[0]?.createdAt, "number"); assertEquals(refreshed.chunks.length, 1); assertEquals(refreshed.chunks[0]?.documentId, id); assertEquals(refreshed.chunks[0]?.text, "# New Slide Title\n\nNew body text"); assertEquals(refreshed.chunks[0]?.embedding, []); assertEquals(refreshed.chunks[0]?.index, 0); }); }); it("ranks local chunks by cosine similarity and honors topK and threshold", async () => { // Vectors are keyed off marker substrings so the query ("lookup") stays // distinct from the documents while leaning toward the alpha document. registerEmbeddingProvider("ranking", () => ({ specificationVersion: "v2", provider: "ranking", modelId: "test", maxEmbeddingsPerCall: undefined, supportsParallelCalls: true, async doEmbed({ values }: { values: string[] }) { return { embeddings: values.map((value) => { const vector = new Array(1536).fill(0); const normalized = value.toLowerCase(); const [first, second] = normalized.includes("lookup") ? [1, 0] : normalized.includes("alpha") ? [1, 0.2] : [0.2, 1]; vector[1] = first; vector[2] = second; return vector; }), usage: { tokens: 0 }, rawResponse: undefined, warnings: [], }; }, }) as never); await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); const store = ragStore({ model: "ranking/test", storagePath }); const alphaId = await store.ingest("Alpha Doc", "Alpha body text", { source: "upload:alpha.txt", type: "txt", }); const betaId = await store.ingest("Beta Doc", "Beta body text", { source: "upload:beta.txt", type: "txt", }); const ranked = await store.search("alpha lookup", { topK: 2 }); assertEquals( ranked.map((result) => result.documentId), [alphaId, betaId], "the higher-scoring chunk must sort first", ); assertEquals( ranked.map((result) => result.title), ["Alpha Doc", "Beta Doc"], "the document title must be joined onto each result", ); const topOne = await store.search("alpha lookup", { topK: 1 }); assertEquals(topOne.length, 1, "topK must slice the ranked list"); assertEquals( topOne[0]?.documentId, alphaId, "the single retained result must be the highest-scoring chunk", ); assertEquals( await store.search("alpha lookup", { threshold: 0.99 }), [], "a threshold above the best score must filter every chunk out", ); }); }); it("returns empty results for whitespace-only local queries", async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); const store = ragStore({ model: "local/test-model", storagePath, }); await store.ingest("Doc", "Hello world", { source: "upload:test.txt", type: "txt", }); const results = await store.search(" "); assertEquals(results, []); }); }); it("does not hold the local store lock while embedding the search query", async () => { let releaseQueryEmbedding!: () => void; let signalQueryEmbedding!: () => void; const queryEmbeddingStarted = new Promise((resolve) => { signalQueryEmbedding = resolve; }); const queryEmbeddingReleased = new Promise((resolve) => { releaseQueryEmbedding = resolve; }); registerEmbeddingProvider("slow-query", () => ({ specificationVersion: "v2", provider: "slow-query", modelId: "test", maxEmbeddingsPerCall: undefined, supportsParallelCalls: true, async doEmbed({ values }: { values: string[] }) { if (values.length === 1 && values[0] === "needle") { signalQueryEmbedding(); await queryEmbeddingReleased; } return { embeddings: values.map((value) => { const vector = new Array(1536).fill(0); vector[0] = value.length; return vector; }), usage: { tokens: 0 }, rawResponse: undefined, warnings: [], }; }, }) as never); await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); const store = ragStore({ model: "slow-query/test", storagePath }); await store.ingest("Doc", "Hello world"); await store.search("warm"); const searchPromise = store.search("needle"); await queryEmbeddingStarted; const listDocumentsPromise = store.listDocuments(); let blockedTimer: ReturnType | undefined; let observedDocuments: Awaited> | "blocked"; try { observedDocuments = await Promise.race([ listDocumentsPromise, new Promise<"blocked">((resolve) => { blockedTimer = setTimeout(() => resolve("blocked"), 5_000); }), ]); } finally { if (blockedTimer !== undefined) clearTimeout(blockedTimer); releaseQueryEmbedding(); } let settleTimer: ReturnType | undefined; const documents = await Promise.race([ listDocumentsPromise, new Promise((_, reject) => { settleTimer = setTimeout( () => reject(new Error("listDocuments did not settle after query embedding release")), 5_000, ); }), ]).finally(() => { if (settleTimer !== undefined) clearTimeout(settleTimer); }); await searchPromise; assert(Array.isArray(observedDocuments)); assertEquals(observedDocuments, documents); assertEquals(documents.length, 1); assertEquals(documents[0]?.title, "Doc"); }); }); it("fails safely when embedding persistence repeatedly loses the store race", async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); let embeddingAttempts = 0; registerEmbeddingProvider("contended-persist", () => ({ specificationVersion: "v2", provider: "contended-persist", modelId: "test", maxEmbeddingsPerCall: undefined, supportsParallelCalls: true, async doEmbed({ values }: { values: string[] }) { if (values.length > 1 || values[0] !== "query") { embeddingAttempts++; if (embeddingAttempts > 2) { throw new Error("embedding persistence was retried after exhaustion"); } await Deno.writeTextFile( storagePath, JSON.stringify({ documents: [{ id: "doc", title: `External ${embeddingAttempts}`, source: "external", type: "txt", createdAt: embeddingAttempts, }], chunks: [{ id: "chunk", documentId: "doc", text: "searchable content", embedding: [], index: 0, }], }), ); } return { embeddings: values.map((value) => { const vector = new Array(1536).fill(0); vector[0] = value.length; return vector; }), usage: { tokens: 0 }, rawResponse: undefined, warnings: [], }; }, }) as never); const store = ragStore({ model: "contended-persist/test", storagePath }); await store.ingest("Doc", "searchable content"); const error = await assertRejects( () => store.search("query"), VeryfrontError, "changed repeatedly while embeddings were persisted", ); assert(error instanceof VeryfrontError); assertEquals(error.slug, "rag-store-unavailable"); assertEquals(embeddingAttempts, 2); }); }); it("does not report stored-chunk embedding provider failures as storage failures", async () => { await withTempDir(async (tempDir) => { registerEmbeddingProvider("failing-doc-embed", () => ({ specificationVersion: "v2", provider: "failing-doc-embed", modelId: "test", maxEmbeddingsPerCall: undefined, supportsParallelCalls: true, async doEmbed() { throw new Error("embedding provider timed out"); }, }) as never); const store = ragStore({ model: "failing-doc-embed/test", storagePath: join(tempDir, "data", "index.json"), }); await store.ingest("Doc", "searchable content"); const error = await assertRejects( () => store.search("query"), Error, "embedding provider timed out", ); assert(error instanceof Error); assertEquals( error instanceof VeryfrontError && error.slug === "rag-store-unavailable", false, ); assertEquals(error.message.includes("Check storage and retry"), false); }); }); it("does not report query embedding provider failures as storage failures", async () => { await withTempDir(async (tempDir) => { registerEmbeddingProvider("failing-query-embed", () => ({ specificationVersion: "v2", provider: "failing-query-embed", modelId: "test", maxEmbeddingsPerCall: undefined, supportsParallelCalls: true, async doEmbed({ values }: { values: string[] }) { if (values.length === 1 && values[0] === "query") { throw new Error("embedding provider rate limited"); } return { embeddings: values.map((value) => { const vector = new Array(1536).fill(0); vector[0] = value.length; return vector; }), usage: { tokens: 0 }, rawResponse: undefined, warnings: [], }; }, }) as never); const store = ragStore({ model: "failing-query-embed/test", storagePath: join(tempDir, "data", "index.json"), }); await store.ingest("Doc", "searchable content"); const error = await assertRejects( () => store.search("query"), Error, "embedding provider rate limited", ); assert(error instanceof Error); assertEquals( error instanceof VeryfrontError && error.slug === "rag-store-unavailable", false, ); assertEquals(error.message.includes("Check storage and retry"), false); }); }); it("reuses parsed local store data across searches until storage changes", async () => { registerTestEmbeddingProvider(); await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); const store = ragStore({ model: "test/demo", storagePath, }); await store.ingest("Doc", "Hello world", { source: "upload:test.txt", type: "txt", }); let parseCalls = 0; const originalParse = JSON.parse; JSON.parse = ((text, reviver) => { if (text.includes('"documents"') && text.includes('"chunks"')) parseCalls++; return originalParse(text, reviver); }) as typeof JSON.parse; try { await store.search("hello"); await store.search("hello"); assertEquals( parseCalls <= 1, true, `Expected repeated searches to parse the store at most once, got ${parseCalls}`, ); parseCalls = 0; const previousInfo = await Deno.stat(storagePath); const previousPayload = await readTextFile(storagePath); const externalPayload = previousPayload.replace('"title":"Doc"', '"title":"Alt"'); assertEquals(externalPayload.length, previousPayload.length); await new Promise((resolve) => setTimeout(resolve, 5)); await Deno.writeTextFile(storagePath, externalPayload); if (previousInfo.mtime !== null) { await Deno.utime( storagePath, previousInfo.atime ?? previousInfo.mtime, previousInfo.mtime, ); } const documents = await store.listDocuments(); assertEquals(documents.map((document) => document.title), ["Alt"]); assertEquals(parseCalls, 1); } finally { JSON.parse = originalParse; } }); }); it("migrates legacy upload-store data from data/index.json", async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); await Deno.mkdir(join(tempDir, "data"), { recursive: true }); await Deno.writeTextFile( storagePath, JSON.stringify({ uploads: [{ id: "upload-1", title: "Legacy Doc", source: "upload:legacy.txt", type: "txt", createdAt: 1, }], chunks: [{ id: "chunk-1", uploadId: "upload-1", text: "legacy content", embedding: [], index: 0, }], }), ); const store = ragStore({ model: "local/test-model", storagePath, }); const documents = await store.listDocuments(); assertEquals(documents, [{ id: "upload-1", title: "Legacy Doc", source: "upload:legacy.txt", type: "txt", createdAt: 1, }]); }); }); it("fails closed without overwriting invalid document entries", async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); await Deno.mkdir(join(tempDir, "data"), { recursive: true }); const original = JSON.stringify({ documents: [{ id: 123, title: "Invalid Doc", source: "upload:invalid.txt", type: "txt", createdAt: 1, }], chunks: [], }); await Deno.writeTextFile(storagePath, original); const store = ragStore({ model: "local/test-model", storagePath, }); await assertRejects( () => store.listDocuments(), Error, "failed validation", ); await assertRejects( () => store.ingest("Replacement", "must not overwrite"), Error, "failed validation", ); assertEquals(await readTextFile(storagePath), original); }); }); it("fails closed without overwriting invalid chunk entries", async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); await Deno.mkdir(join(tempDir, "data"), { recursive: true }); const original = JSON.stringify({ documents: [{ id: "doc-1", title: "Valid Doc", source: "upload:valid.txt", type: "txt", createdAt: 1, }], chunks: [{ id: "chunk-1", documentId: "doc-1", text: "content", embedding: ["not-a-number"], index: 0, }], }); await Deno.writeTextFile(storagePath, original); const store = ragStore({ model: "local/test-model", storagePath, }); await assertRejects( () => store.listDocuments(), Error, "failed validation", ); assertEquals(await readTextFile(storagePath), original); }); }); it("fails closed on duplicate document identities before a mutation can discard chunks", async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); await Deno.mkdir(join(tempDir, "data"), { recursive: true }); const original = JSON.stringify({ documents: [ { id: "duplicate", title: "First", source: "first", type: "txt", createdAt: 1 }, { id: "duplicate", title: "Second", source: "second", type: "txt", createdAt: 2 }, ], chunks: [ { id: "chunk-first", documentId: "duplicate", text: "first", embedding: [], index: 0, }, { id: "chunk-second", documentId: "duplicate", text: "second", embedding: [], index: 1, }, ], }); await Deno.writeTextFile(storagePath, original); const store = ragStore({ model: "local/test-model", storagePath }); await assertRejects( () => store.refreshDocument!("duplicate", "replacement"), VeryfrontError, "failed validation", ); assertEquals(await readTextFile(storagePath), original); }); }); it("fails closed on chunks that do not belong to a persisted document", async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); await Deno.mkdir(join(tempDir, "data"), { recursive: true }); const original = JSON.stringify({ documents: [], chunks: [{ id: "orphan", documentId: "missing", text: "orphaned content", embedding: [], index: 0, }], }); await Deno.writeTextFile(storagePath, original); const store = ragStore({ model: "local/test-model", storagePath }); await assertRejects( () => store.removeDocument("missing"), VeryfrontError, "failed validation", ); assertEquals(await readTextFile(storagePath), original); }); }); it("fails closed without overwriting malformed JSON", async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); await Deno.mkdir(join(tempDir, "data"), { recursive: true }); const original = '{"documents":['; await Deno.writeTextFile(storagePath, original); const store = ragStore({ model: "local/test-model", storagePath, }); const error = await assertRejects( () => store.listDocuments(), VeryfrontError, "malformed JSON", ); assert(error instanceof VeryfrontError); assertEquals(error.slug, "rag-store-corrupt"); assertEquals(error.message.includes(storagePath), false); assertEquals(error.context, { storagePath }); await assertRejects( () => store.removeDocument("anything"), Error, "malformed JSON", ); assertEquals(await readTextFile(storagePath), original); }); }); it("fails closed on invalid UTF-8 without replacing persisted bytes", async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); await Deno.mkdir(join(tempDir, "data"), { recursive: true }); const original = new Uint8Array([0xff, 0xfe, 0xfd]); await Deno.writeFile(storagePath, original); const store = ragStore({ model: "local/test-model", storagePath }); const error = await assertRejects( () => store.listDocuments(), VeryfrontError, "not valid UTF-8", ); assert(error instanceof VeryfrontError); assertEquals(error.slug, "rag-store-corrupt"); assertEquals(error.message.includes(storagePath), false); assertEquals(await Deno.readFile(storagePath), original); }); }); it("rejects an oversized index before allocating or parsing its contents", async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); await Deno.mkdir(join(tempDir, "data"), { recursive: true }); const oversizedBytes = 64 * 1024 * 1024 + 1; await Deno.writeFile(storagePath, new Uint8Array([0x7b])); await Deno.truncate(storagePath, oversizedBytes); const store = ragStore({ model: "local/test-model", storagePath }); const error = await assertRejects( () => store.listDocuments(), VeryfrontError, "file exceeds size limit", ); assert(error instanceof VeryfrontError); assertEquals(error.slug, "rag-store-corrupt"); assertEquals(error.message.includes(storagePath), false); assertEquals((await Deno.stat(storagePath)).size, oversizedBytes); }); }); it("rejects a directory store path without deleting matching sibling temps", async () => { await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "index.json"); const siblingTemp = `${storagePath}.tmp.${crypto.randomUUID()}`; await Deno.mkdir(storagePath); await Deno.writeTextFile(siblingTemp, "unrelated sibling bytes"); const store = ragStore({ model: "local/test-model", storagePath, }); const error = await assertRejects( () => store.listDocuments(), VeryfrontError, "must be a regular file or be absent", ); assert(error instanceof VeryfrontError); assertEquals(error.slug, "rag-store-unavailable"); assertEquals(error.message.includes(storagePath), false); assertEquals(error.context, { storagePath }); assertEquals(await readTextFile(siblingTemp), "unrelated sibling bytes"); }); }); it("rejects invalid document sizes before cloud RAG requests", async () => { setEnv("VERYFRONT_API_TOKEN", "vf_test_cloud"); setEnv("VERYFRONT_PROJECT_SLUG", "cloud-project"); let fetchCalls = 0; await withMockFetch( () => { fetchCalls++; throw new Error("fetch should not run for invalid document sizes"); }, async () => { const store = ragStore({ model: "test/demo" }); for (const size of [-1, 1.5, NaN, Infinity]) { const error = await assertRejects( () => store.ingest("Cloud Doc", "Hello cloud world", { size }), VeryfrontError, "RAG document size must be a non-negative integer", ); assert(error instanceof VeryfrontError); assertEquals(error.slug, "invalid-argument"); } }, ); assertEquals(fetchCalls, 0); }); it("rejects invalid document sizes before direct cloud RAG requests", async () => { setEnv("VERYFRONT_API_TOKEN", "vf_test_cloud"); setEnv("VERYFRONT_PROJECT_SLUG", "cloud-project"); let fetchCalls = 0; await withMockFetch( () => { fetchCalls++; throw new Error("fetch should not run for invalid direct cloud document sizes"); }, async () => { const store = createVeryfrontCloudRagStore({ model: "test/demo" }); for (const size of [-1, 1.5, NaN, Infinity]) { const error = await assertRejects( () => store.ingest("Cloud Doc", "Hello cloud world", { size }), VeryfrontError, "RAG document size must be a non-negative integer", ); assert(error instanceof VeryfrontError); assertEquals(error.slug, "invalid-argument"); } }, ); assertEquals(fetchCalls, 0); }); it("auto-upgrades to the veryfront-cloud backend when cloud bootstrap is present", async () => { setEnv("VERYFRONT_API_TOKEN", "vf_test_cloud"); setEnv("VERYFRONT_PROJECT_SLUG", "cloud-project"); registerTestEmbeddingProvider(); const fileChunks = new Map< string, Array<{ id: string; index: number; content: string; metadata?: Record; }> >(); const ragDocuments = new Map; }>(); const embeddingVectors = new Map(); const authHeaders: Array = []; const postContentTypes: Array = []; await withMockFetch( async (input: string | URL | Request, init?: RequestInit) => { const request = input instanceof Request ? input : new Request(input, init); const url = new URL(request.url); const path = url.pathname; if (request.method === "GET" && path.endsWith("/files")) { return Response.json({ data: [...fileChunks.keys()].map((path) => ({ path })), page_info: { next: null }, }); } authHeaders.push(request.headers.get("authorization")); if (request.method === "POST") { postContentTypes.push(request.headers.get("content-type")); } const fileMatch = path.match(/^\/projects\/[^/]+\/branches\/[^/]+\/files\/(.+)\/chunks$/); const filePath = fileMatch ? decodeURIComponent(fileMatch[1]!) : null; // RAG document management routes const ragDocMatch = path.match( /^\/projects\/[^/]+\/knowledge\/retrieval-documents(?:\/(.+))?$/, ); if (ragDocMatch !== null) { const docId = ragDocMatch[1] ? decodeURIComponent(ragDocMatch[1]) : null; if (request.method === "GET" && !docId) { return Response.json({ data: [...ragDocuments.values()].map((document) => ({ ...document, revision: "a".repeat(64), })), page_info: { next: null }, }); } if (request.method === "POST" && !docId) { const body = await request.json() as { id: string; title: string; source: string; type: string; metadata?: Record; }; // Create carries no revision guard; an existing ID is a 409 conflict. assertEquals("expected_revision" in body, false); ragDocuments.set(body.id, { id: body.id, title: body.title, source: body.source, type: body.type, metadata: body.metadata, created_at: new Date().toISOString(), }); return Response.json({ id: body.id }, { status: 201 }); } if (request.method === "DELETE" && docId) { ragDocuments.delete(docId); return Response.json({ id: docId, status: "deleted" }); } } if (request.method === "GET" && filePath) { const chunks = fileChunks.get(filePath); if (!chunks) { return new Response("Not found", { status: 404 }); } return Response.json({ data: chunks, page_info: { next: null }, }); } if (request.method === "DELETE" && filePath) { fileChunks.delete(filePath); return Response.json({ deleted: 1 }); } if (request.method === "POST" && filePath) { const body = await request.json() as { chunks: Array<{ chunk_index: number; content: string; metadata?: Record; }>; }; const stored = body.chunks.map((chunk) => ({ id: `${filePath}:${chunk.chunk_index}`, index: chunk.chunk_index, content: chunk.content, metadata: chunk.metadata, })); fileChunks.set(filePath, stored); return Response.json({ chunks: stored.map(({ id, index }) => ({ id, index })), created: stored.length, updated: 0, }); } if (request.method === "POST" && path.endsWith("/embeddings")) { const body = await request.json() as { chunk_ids: string[]; vectors: number[][]; }; body.chunk_ids.forEach((chunkId, index) => { embeddingVectors.set(chunkId, body.vectors[index]!); }); return Response.json({ embeddings: body.chunk_ids.map((chunkId) => ({ id: `embedding:${chunkId}`, model: "test/demo", status: "ready", created_at: new Date().toISOString(), })), created: body.chunk_ids.length, updated: 0, }); } if (request.method === "POST" && path.endsWith("/search")) { const manifestChunks = fileChunks.get(".veryfront/rag/manifest.json") ?? []; const documentFilePath = [...fileChunks.keys()].find((key) => key.startsWith(".veryfront/rag/documents/") ); const documentChunks = documentFilePath ? (fileChunks.get(documentFilePath) ?? []) : []; return Response.json({ data: [ ...manifestChunks.map((chunk) => ({ chunk: { file_path: ".veryfront/rag/manifest.json", content: chunk.content, metadata: chunk.metadata, }, score: 0.99, })), ...documentChunks.map((chunk) => ({ chunk: { file_path: documentFilePath, content: chunk.content, metadata: chunk.metadata, }, score: 0.91, })), ], }); } return new Response(`Unhandled ${request.method} ${path}`, { status: 404 }); }, async () => { const store = ragStore({ model: "test/demo", }); const id = await store.ingest("Cloud Doc", "Hello cloud world", { source: "upload:cloud.txt", type: "txt", size: 0, }); const documents = await store.listDocuments(); assertEquals(documents.length, 1); assertEquals(documents[0]?.id, id); assertEquals(documents[0]?.size, 0); assertEquals(ragDocuments.get(id)?.metadata?.size, 0); const results = await store.search("cloud", { topK: 1 }); assertEquals(results.length, 1); assertEquals(results[0]?.documentId, id); assertEquals(results[0]?.title, "Cloud Doc"); assertEquals(embeddingVectors.size > 0, true); assertEquals(authHeaders.some((header) => header === "Bearer vf_test_cloud"), true); assertEquals( postContentTypes.every((contentType) => contentType === "application/json"), true, ); await store.removeDocument(id); assertEquals(await store.listDocuments(), []); }, ); }); it("sends cloud semantic scope before ranking and requires acknowledgement", async () => { setEnv("VERYFRONT_API_TOKEN", "vf_test_cloud"); setEnv("VERYFRONT_PROJECT_SLUG", "cloud-project"); registerTestEmbeddingProvider(); await withTempDir(async (projectDir) => { const observedBodies: Record[] = []; await withMockFetch( async (input: string | URL | Request, init?: RequestInit) => { const request = input instanceof Request ? input : new Request(input, init); const url = new URL(request.url); if ( request.method === "POST" && url.pathname === "/projects/cloud-project/branches/preview/search" ) { const observedBody = await request.json() as Record; observedBodies.push(observedBody); const scope = observedBody.document_scope as Record | undefined; if (!scope) { return Response.json({ data: [ ...Array.from({ length: 50 }, (_, index) => ({ chunk: { file_path: `knowledge/private/secret-${index}.md`, content: "denied higher-ranked content", metadata: { document_id: `denied-${index}`, source: `knowledge/private/secret-${index}.md`, title: "Denied", type: "md", }, }, score: 0.99 - index / 1000, })), { chunk: { file_path: "knowledge/allowed/topic.md", content: "allowed scoped content", metadata: { document_id: "allowed", source: "knowledge/allowed/topic.md", title: "Allowed", type: "md", }, }, score: 0.5, }, ], }); } return Response.json({ document_scope_version: 1, data: [{ chunk: { file_path: "knowledge/allowed/topic.md", content: "allowed scoped content", metadata: { document_id: "allowed", source: "knowledge/allowed/topic.md", title: "Allowed", type: "md", }, }, score: 0.5, }], }); } return new Response(`Unexpected ${request.method} ${url.pathname}`, { status: 500 }); }, async () => { const knowledge = projectKnowledge({ backend: "veryfront-cloud", branch: "preview", contentDir: "knowledge", projectDir, model: "test/demo", scope: { "knowledge/allowed/**": true, "knowledge/private/**": false, }, }); const result = await knowledge.retrieve("secret", { topK: 1, threshold: 0 }); assertEquals(result.matches.map((match) => match.source), ["knowledge/allowed/topic.md"]); }, ); const observedBody = observedBodies.at(-1); assert(observedBody !== undefined); assertEquals(observedBody.limit, 75); assertEquals(observedBody.model, { name: "demo", provider: "test" }); const documentScope = observedBody.document_scope as Record | undefined; assertEquals(documentScope?.version, 1); assertEquals(documentScope?.path_flavor, "posix"); assertEquals(documentScope?.include_all, false); assertEquals(documentScope?.includes, ["knowledge/allowed/**"]); assertEquals(documentScope?.excludes, ["knowledge/private/**"]); assertEquals(documentScope?.content_dir, "knowledge"); assertEquals(documentScope?.project_dir, projectDir); assertEquals(documentScope?.resolved_content_dir, `${projectDir}/knowledge`); assertEquals(documentScope?.resolved_project_dir, projectDir); }); }); it("fails closed when cloud semantic scope acknowledgement is missing", async () => { setEnv("VERYFRONT_API_TOKEN", "vf_test_cloud"); setEnv("VERYFRONT_PROJECT_SLUG", "cloud-project"); registerTestEmbeddingProvider(); await withTempDir(async (projectDir) => { await withMockFetch( async (input: string | URL | Request, init?: RequestInit) => { const request = input instanceof Request ? input : new Request(input, init); const url = new URL(request.url); if ( request.method === "POST" && url.pathname === "/projects/cloud-project/branches/preview/search" ) { return Response.json({ data: [] }); } return new Response(`Unexpected ${request.method} ${url.pathname}`, { status: 500 }); }, async () => { const knowledge = projectKnowledge({ backend: "veryfront-cloud", branch: "preview", contentDir: "knowledge", projectDir, model: "test/demo", scope: "knowledge/allowed/**", }); const error = await assertRejects( () => knowledge.retrieve("secret", { topK: 1, threshold: 0 }), VeryfrontError, "did not acknowledge document scope", ); assert(error instanceof VeryfrontError); assertEquals(error.slug, "invalid-argument"); }, ); }); }); it("keeps auto RAG local when service-layer cloud has a token but no project slug", async () => { setEnv("VERYFRONT_API_TOKEN", "vf_test_cloud"); setEnv("VERYFRONT_SERVICE_LAYER", "cloud"); registerTestLocalEmbeddingProvider(); await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); let fetchCalls = 0; await withMockFetch( () => { fetchCalls++; throw new Error("auto RAG without a project slug must not use cloud"); }, async () => { const store = ragStore({ storagePath }); const id = await store.ingest("Local Doc", "hello local document", { source: "upload:local.txt", type: "txt", }); const results = await store.search("hello", { topK: 1 }); assertEquals((await store.listDocuments()).map((document) => document.id), [id]); assertEquals(results.length, 1); assertEquals(results[0]?.documentId, id); assertEquals(fetchCalls, 0); assertEquals(await exists(storagePath), true); }, ); }); }); it("keeps auto RAG local when scoped cloud credentials omit the project slug", async () => { registerTestLocalEmbeddingProvider(); await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); let fetchCalls = 0; await withMockFetch( () => { fetchCalls++; throw new Error("auto RAG without a scoped project slug must not use cloud"); }, async () => { const store = ragStore({ storagePath }); await runWithVeryfrontCloudContext( { apiToken: "vf_scoped_token" }, async () => { const id = await store.ingest("Scoped Local Doc", "hello scoped local document", { source: "upload:scoped-local.txt", type: "txt", }); const results = await store.search("scoped", { topK: 1 }); assertEquals((await store.listDocuments()).map((document) => document.id), [id]); assertEquals(results.length, 1); assertEquals(results[0]?.documentId, id); }, ); assertEquals(fetchCalls, 0); assertEquals(await exists(storagePath), true); }, ); }); }); it("refuses cloud refresh and removal before mutation when the API has no document revision", async () => { setEnv("VERYFRONT_API_TOKEN", "vf_test_cloud"); setEnv("VERYFRONT_PROJECT_SLUG", "cloud-project"); const requests: string[] = []; await withMockFetch((input, init) => { const request = input instanceof Request ? input : new Request(input, init); const path = new URL(request.url).pathname; requests.push(`${request.method} ${path}`); assertEquals(request.method, "GET"); assertEquals(path, "/projects/cloud-project/knowledge/retrieval-documents"); return Promise.resolve(Response.json({ page_info: { next: null }, data: [{ id: "fixture-document", title: "Existing", source: "", type: "txt", created_at: "2026-09-14T00:00:00Z", metadata: { filePath: ".veryfront/rag/documents/fixture-document.txt" }, }], })); }, async () => { const store = ragStore({ model: "test/demo" }); await assertRejects( () => store.refreshDocument!("fixture-document", "replacement"), Error, "document revision is unavailable", ); await assertRejects( () => store.removeDocument("fixture-document"), Error, "document revision is unavailable", ); assertEquals(requests, [ "GET /projects/cloud-project/knowledge/retrieval-documents", "GET /projects/cloud-project/knowledge/retrieval-documents", ]); }); }); it("pages retrieval documents and deletes the record by revision on the canonical routes", async () => { setEnv("VERYFRONT_API_TOKEN", "vf_test_cloud"); setEnv("VERYFRONT_PROJECT_SLUG", "cloud-project"); const requests: string[] = []; const record = (id: string) => ({ id, revision: id === "doc-b" ? "b".repeat(64) : "a".repeat(64), title: id, source: `knowledge/${id}.md`, type: "md", metadata: {}, created_at: "2026-09-14T00:00:00Z", updated_at: "2026-09-14T00:00:00Z", }); await withMockFetch((input, init) => { const request = input instanceof Request ? input : new Request(input, init); const url = new URL(request.url); requests.push(`${request.method} ${url.pathname}${url.search}`); if (url.pathname === "/projects/cloud-project/knowledge/retrieval-documents") { assertEquals(url.searchParams.get("limit"), "100"); const cursor = url.searchParams.get("cursor"); return Promise.resolve(Response.json( cursor === "page-2" ? { data: [record("doc-b")], page_info: { next: null } } : { data: [record("doc-a")], page_info: { next: "page-2" } }, )); } if (url.pathname === "/projects/cloud-project/knowledge/retrieval-documents/doc-b") { assertEquals(request.method, "DELETE"); return Promise.resolve(Response.json({ id: "doc-b", status: "deleted" })); } if (url.pathname.endsWith("/files")) { return Promise.resolve(Response.json({ data: [], page_info: { next: null } })); } if (request.method === "DELETE" && url.pathname.endsWith("/chunks")) { return Promise.resolve(Response.json({ deleted: 1 })); } throw new Error(`Unhandled ${request.method} ${url.pathname}`); }, async () => { const store = ragStore({ model: "test/demo" }); assertEquals((await store.listDocuments()).map((document) => document.id), [ "doc-a", "doc-b", ]); await store.removeDocument("doc-b"); assertEquals(requests.some((request) => request.includes("/rag/documents")), false); assert( requests.includes( `DELETE /projects/cloud-project/knowledge/retrieval-documents/doc-b?expected_revision=${ "b".repeat(64) }`, ), ); }); }); it("fails a retrieval document listing that repeats a cursor", async () => { setEnv("VERYFRONT_API_TOKEN", "vf_test_cloud"); setEnv("VERYFRONT_PROJECT_SLUG", "cloud-project"); await withMockFetch( () => Promise.resolve(Response.json({ data: [], page_info: { next: "same" } })), async () => { const store = ragStore({ model: "test/demo" }); await assertRejects(() => store.listDocuments(), Error, "repeated a cursor"); }, ); }); it("removes discovered orphan parts even when another part cannot be inspected", async () => { setEnv("VERYFRONT_API_TOKEN", "vf_test_cloud"); setEnv("VERYFRONT_PROJECT_SLUG", "cloud-project"); const prefix = ".veryfront/rag/documents/fixture-document."; const deleted: string[] = []; await withMockFetch((input, init) => { const request = input instanceof Request ? input : new Request(input, init); const url = new URL(request.url); if (url.pathname.endsWith("/knowledge/retrieval-documents")) { return Promise.resolve(Response.json({ data: [], page_info: { next: null } })); } if (url.pathname.endsWith("/files")) { assertEquals(url.searchParams.get("fields"), "(path)"); return Promise.resolve( Response.json({ data: [{ path: `${prefix}failed.txt` }, { path: `${prefix}orphan.txt` }], page_info: { next: null }, }), ); } const file = decodeURIComponent(url.pathname.split("/files/")[1]!.replace(/\/chunks$/, "")); if (request.method === "DELETE") { deleted.push(file); return Promise.resolve(Response.json({ deleted: 1 })); } if (file === `${prefix}failed.txt`) { return Promise.resolve(Response.json({ message: "Fixture probe failed" }, { status: 503 })); } return Promise.resolve( Response.json({ data: [{ id: "chunk", index: 0, content: "fixture" }] }), ); }, async () => { const store = ragStore({ model: "test/demo" }); await assertRejects( () => store.removeDocument("fixture-document"), Error, "Fixture probe failed", ); assertEquals(deleted, [`${prefix}failed.txt`, `${prefix}orphan.txt`]); }); }); it("refreshes cloud document chunks and embeddings under the existing id", async () => { setEnv("VERYFRONT_API_TOKEN", "vf_test_cloud"); setEnv("VERYFRONT_PROJECT_SLUG", "cloud-project"); registerTestEmbeddingProvider(); const fileChunks = new Map< string, Array<{ id: string; index: number; content: string; metadata?: Record; }> >([ [ ".veryfront/rag/documents/doc-pptx.pptx", [{ id: "old-chunk", index: 0, content: "Old flat PPTX content", metadata: { kind: "rag-document", document_id: "doc-pptx", title: "Old Deck", source: "upload:old.pptx", type: "pptx", }, }], ], ]); const ragDocuments = new Map; }>([ [ "doc-pptx", { id: "doc-pptx", title: "Old Deck", source: "upload:old.pptx", type: "pptx", created_at: "2026-06-25T00:00:00.000Z", updated_at: "2026-06-25T00:00:00.000Z", metadata: { filePath: ".veryfront/rag/documents/doc-pptx.pptx", size: 24 }, }, ], ]); const embeddingVectors = new Map(); const deletedFilePaths: string[] = []; await withMockFetch( async (input: string | URL | Request, init?: RequestInit) => { const request = input instanceof Request ? input : new Request(input, init); const url = new URL(request.url); const path = url.pathname; if (request.method === "GET" && path.endsWith("/files")) { return Response.json({ data: [...fileChunks.keys()].map((path) => ({ path })), page_info: { next: null }, }); } const ragDocMatch = path.match( /^\/projects\/[^/]+\/knowledge\/retrieval-documents(?:\/(.+))?$/, ); if (ragDocMatch !== null) { const docId = ragDocMatch[1] ? decodeURIComponent(ragDocMatch[1]) : null; if (request.method === "GET" && !docId) { return Response.json({ data: [...ragDocuments.values()].map((document) => ({ ...document, revision: "a".repeat(64), })), page_info: { next: null }, }); } if (request.method === "PUT" && docId) { const body = await request.json() as { title: string; source: string; type: string; metadata?: Record; expected_revision: string; }; assertEquals(body.expected_revision, "a".repeat(64)); assertEquals("id" in body, false); const existing = ragDocuments.get(docId); assert(existing); ragDocuments.set(docId, { id: docId, title: body.title, source: body.source, type: body.type, metadata: body.metadata, created_at: existing.created_at, updated_at: "2026-06-25T01:00:00.000Z", }); return Response.json(ragDocuments.get(docId)); } } const fileMatch = path.match(/^\/projects\/[^/]+\/branches\/[^/]+\/files\/(.+)\/chunks$/); const filePath = fileMatch ? decodeURIComponent(fileMatch[1]!) : null; if (request.method === "DELETE" && filePath) { deletedFilePaths.push(filePath); fileChunks.delete(filePath); return Response.json({ deleted: 1 }); } if (request.method === "POST" && filePath) { const body = await request.json() as { chunks: Array<{ chunk_index: number; content: string; metadata?: Record; }>; }; const stored = body.chunks.map((chunk) => ({ id: `${filePath}:${chunk.chunk_index}`, index: chunk.chunk_index, content: chunk.content, metadata: chunk.metadata, })); fileChunks.set(filePath, stored); return Response.json({ chunks: stored.map(({ id, index }) => ({ id, index })), created: stored.length, updated: 0, }); } if (request.method === "POST" && path.endsWith("/embeddings")) { const body = await request.json() as { chunk_ids: string[]; vectors: number[][]; }; body.chunk_ids.forEach((chunkId, index) => { embeddingVectors.set(chunkId, body.vectors[index]!); }); return Response.json({ embeddings: body.chunk_ids.map((chunkId) => ({ id: `embedding:${chunkId}`, model: "test/demo", status: "ready", created_at: new Date().toISOString(), })), created: body.chunk_ids.length, updated: 0, }); } return new Response(`Unhandled ${request.method} ${path}`, { status: 404 }); }, async () => { const store = ragStore({ model: "test/demo", }); const refresh = store.refreshDocument; assert(refresh); await refresh("doc-pptx", "# Better Deck\n\nBody text", { title: "Better Deck", source: "upload:better.pptx", type: "pptx", }); assertEquals(deletedFilePaths, [".veryfront/rag/documents/doc-pptx.pptx"]); const refreshedDocument = [...ragDocuments.values()][0]; const refreshedFilePath = refreshedDocument?.metadata?.filePath; assertEquals(typeof refreshedFilePath, "string"); assertEquals( (refreshedFilePath as string).startsWith( ".veryfront/rag/documents/doc-pptx.refresh-", ), true, ); assertEquals((refreshedFilePath as string).endsWith(".pptx"), true); assertEquals(refreshedDocument, { id: "doc-pptx", title: "Better Deck", source: "upload:better.pptx", type: "pptx", created_at: "2026-06-25T00:00:00.000Z", updated_at: "2026-06-25T01:00:00.000Z", metadata: { filePath: refreshedFilePath, cleanupFilePaths: [".veryfront/rag/documents/doc-pptx.pptx"], size: 24, }, }); const chunks = fileChunks.get(refreshedFilePath as string) ?? []; assertEquals(chunks.length, 1); assertEquals(chunks[0]?.content, "# Better Deck\n\nBody text"); assertEquals(chunks[0]?.metadata, { kind: "rag-document", document_id: "doc-pptx", title: "Better Deck", source: "upload:better.pptx", type: "pptx", }); assertEquals(embeddingVectors.size, 1); const listedDocuments = await store.listDocuments() as unknown as Array< Record >; assertEquals("filePath" in listedDocuments[0]!, false); assertEquals(listedDocuments[0]?.size, 24); }, ); }); it("keeps old cloud chunks when refresh replacement embedding persistence fails", async () => { setEnv("VERYFRONT_API_TOKEN", "vf_test_cloud"); setEnv("VERYFRONT_PROJECT_SLUG", "cloud-project"); registerTestEmbeddingProvider(); const fileChunks = new Map< string, Array<{ id: string; index: number; content: string; metadata?: Record }> >([ [ ".veryfront/rag/documents/doc-pptx.pptx", [{ id: "old-chunk", index: 0, content: "Old flat PPTX content", metadata: { kind: "rag-document", document_id: "doc-pptx", title: "Old Deck", source: "upload:old.pptx", type: "pptx", }, }], ], ]); const ragDocuments = new Map; }>([ [ "doc-pptx", { id: "doc-pptx", title: "Old Deck", source: "upload:old.pptx", type: "pptx", created_at: "2026-06-25T00:00:00.000Z", updated_at: "2026-06-25T00:00:00.000Z", metadata: { filePath: ".veryfront/rag/documents/doc-pptx.pptx" }, }, ], ]); const deletedFilePaths: string[] = []; await withMockFetch( async (input: string | URL | Request, init?: RequestInit) => { const request = input instanceof Request ? input : new Request(input, init); const url = new URL(request.url); const path = url.pathname; if (request.method === "GET" && path.endsWith("/files")) { return Response.json({ data: [...fileChunks.keys()].map((path) => ({ path })), page_info: { next: null }, }); } const ragDocMatch = path.match( /^\/projects\/[^/]+\/knowledge\/retrieval-documents(?:\/(.+))?$/, ); if (ragDocMatch !== null && request.method === "GET" && !ragDocMatch[1]) { return Response.json({ data: [...ragDocuments.values()].map((document) => ({ ...document, revision: "a".repeat(64), })), page_info: { next: null }, }); } const fileMatch = path.match(/^\/projects\/[^/]+\/branches\/[^/]+\/files\/(.+)\/chunks$/); const filePath = fileMatch ? decodeURIComponent(fileMatch[1]!) : null; if (request.method === "DELETE" && filePath) { deletedFilePaths.push(filePath); fileChunks.delete(filePath); return Response.json({ deleted: 1 }); } if (request.method === "POST" && filePath) { const body = await request.json() as { chunks: Array<{ chunk_index: number; content: string; metadata?: Record; }>; }; const stored = body.chunks.map((chunk) => ({ id: `${filePath}:${chunk.chunk_index}`, index: chunk.chunk_index, content: chunk.content, metadata: chunk.metadata, })); fileChunks.set(filePath, stored); return Response.json({ chunks: stored.map(({ id, index }) => ({ id, index })), created: stored.length, updated: 0, }); } if (request.method === "POST" && path.endsWith("/embeddings")) { return new Response("embedding write failed", { status: 500 }); } return new Response(`Unhandled ${request.method} ${path}`, { status: 404 }); }, async () => { const store = ragStore({ model: "test/demo" }); const refresh = store.refreshDocument; assert(refresh); await assertRejects( () => refresh("doc-pptx", "# Better Deck\n\nBody text"), Error, "embedding write failed", ); assertEquals(deletedFilePaths.includes(".veryfront/rag/documents/doc-pptx.pptx"), false); assertEquals( fileChunks.get(".veryfront/rag/documents/doc-pptx.pptx")?.[0]?.content, "Old flat PPTX content", ); assertEquals(ragDocuments.get("doc-pptx")?.title, "Old Deck"); }, ); }); it("returns empty results for whitespace-only cloud queries without making requests", async () => { setEnv("VERYFRONT_API_TOKEN", "vf_test_cloud"); setEnv("VERYFRONT_PROJECT_SLUG", "cloud-project"); let fetchCalls = 0; await withMockFetch( async () => { fetchCalls++; throw new Error("fetch should not run for whitespace-only queries"); }, async () => { const store = ragStore({ model: "test/demo", }); const results = await store.search(" "); assertEquals(results, []); assertEquals(fetchCalls, 0); }, ); }); it("uses cloudModel for project-scoped cloud inference even with local JSON storage", async () => { setEnv("VERYFRONT_API_TOKEN", "vf_test_cloud"); setEnv("VERYFRONT_PROJECT_SLUG", "cloud-project"); setEnv("VERYFRONT_RAG_BACKEND", "local-json"); ensureBuiltinLLMProviders(); await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); let gatewayEmbeddingUrl: string | undefined; let projectSlugHeader: string | null = null; await withMockFetch( (input: string | URL | Request, init?: RequestInit) => { const request = input instanceof Request ? input : new Request(input, init); const url = new URL(request.url); if ( request.method === "POST" && url.pathname === "/ai/v1beta/models/gemini-embedding-001:embedContent" ) { gatewayEmbeddingUrl = url.toString(); projectSlugHeader = request.headers.get("x-veryfront-project-slug"); return Promise.resolve( Response.json({ embedding: { values: new Array(3072).fill(0.1) } }), ); } return Promise.resolve(new Response("unexpected request", { status: 500 })); }, async () => { const store = ragStore({ storagePath, cloudModel: "veryfront-cloud/google/gemini-embedding-001", }); await store.ingest("Cloud Doc", "cloud model document content", { source: "upload:cloud.txt", type: "txt", }); await store.search("cloud model", { topK: 1 }); }, ); assertEquals( gatewayEmbeddingUrl, "https://api.veryfront.com/ai/v1beta/models/gemini-embedding-001:embedContent", ); assertEquals(projectSlugHeader, "cloud-project"); }); }); it("ignores cloudModel for token-only cloud bootstrap without a project slug", async () => { setEnv("VERYFRONT_API_TOKEN", "vf_test_cloud"); setEnv("VERYFRONT_SERVICE_LAYER", "cloud"); await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); let fetchCalls = 0; await withMockFetch( () => { fetchCalls++; return Promise.resolve(new Response("unexpected request", { status: 500 })); }, async () => { const store = ragStore({ storagePath, cloudModel: "veryfront-cloud/google/gemini-embedding-001", }); assertEquals(await store.listDocuments(), []); }, ); assertEquals(fetchCalls, 0); }); }); it("resolves cloud backend from request-scoped credentials at call time", async () => { registerTestEmbeddingProvider(); const urls: string[] = []; const fileChunks = new Map>(); await withMockFetch( async (input: string | URL | Request, init?: RequestInit) => { const request = input instanceof Request ? input : new Request(input, init); const url = new URL(request.url); urls.push(url.toString()); const fileMatch = url.pathname.match( /^\/projects\/([^/]+)\/branches\/([^/]+)\/files\/(.+)\/chunks$/, ); const filePath = fileMatch ? decodeURIComponent(fileMatch[3] ?? "") : null; if (request.method === "GET" && filePath) { const chunks = fileChunks.get(filePath); if (!chunks) return new Response("Not found", { status: 404 }); return Response.json({ data: chunks, page_info: { next: null } }); } if (request.method === "POST" && filePath) { const body = await request.json() as { chunks: Array<{ chunk_index: number; content: string }>; }; const stored = body.chunks.map((chunk) => ({ id: `${filePath}:${chunk.chunk_index}`, index: chunk.chunk_index, content: chunk.content, })); fileChunks.set(filePath, stored); return Response.json({ chunks: stored.map(({ id, index }) => ({ id, index })), created: stored.length, updated: 0, }); } if (request.method === "POST" && url.pathname.endsWith("/embeddings")) { return Response.json({ embeddings: [{ id: "embedding-1", model: "test/demo", status: "ready" }], created: 1, updated: 0, }); } // RAG document management if (url.pathname.match(/\/knowledge\/retrieval-documents(\/|$)/)) { if (request.method === "POST") { const body = await request.json() as { id: string }; return Response.json({ id: body.id }, { status: 201 }); } return Response.json({ data: [], page_info: { next: null } }); } throw new Error(`Unhandled ${request.method} ${url.pathname}`); }, async () => { const store = ragStore({ model: "test/demo", }); await runWithRequestContext( { projectSlug: "request-project", token: "vf_request_token", }, async () => { await store.ingest("Scoped Doc", "request scoped content", { source: "upload:scoped.txt", type: "txt", }); }, ); // All requests should target the request-scoped project, not any env-based slug assertEquals( urls.every((u) => u.includes("/projects/request-project/")), true, `Expected all URLs to target request-project, got: ${urls[0]}`, ); }, ); }); it("indexes contentDir from published release files in request context", async () => { registerTestEmbeddingProvider(); const ragDocuments = new Map; }>(); const fileChunks = new Map< string, Array<{ id: string; index: number; content: string; metadata?: Record; }> >(); const requestedPaths: string[] = []; await withMockFetch( async (input: string | URL | Request, init?: RequestInit) => { const request = input instanceof Request ? input : new Request(input, init); const url = new URL(request.url); requestedPaths.push(url.pathname); if ( request.method === "GET" && url.pathname === "/projects/cloud-project/releases/rel-abc/files" ) { return Response.json({ data: [ { id: "file-login", version_id: "version-login", path: "knowledge/login-troubleshooting.md", content: "# Login troubleshooting\n\nEscalate blocked SSO login issues.", size: 62, type: "file", updated_at: "2026-06-25T00:00:00.000Z", release_id: "rel-abc", release_version: "0.0.1", }, ], page_info: { next: null }, release_id: "rel-abc", release_version: "0.0.1", }); } const ragDocMatch = url.pathname.match( /^\/projects\/[^/]+\/knowledge\/retrieval-documents(?:\/(.+))?$/, ); if (ragDocMatch !== null) { const docId = ragDocMatch[1] ? decodeURIComponent(ragDocMatch[1]) : null; if (request.method === "GET" && !docId) { return Response.json({ data: [...ragDocuments.values()].map((document) => ({ ...document, revision: "a".repeat(64), })), page_info: { next: null }, }); } if (request.method === "POST" && !docId) { const body = await request.json() as { id: string; title: string; source: string; type: string; metadata?: Record; }; ragDocuments.set(body.id, { id: body.id, title: body.title, source: body.source, type: body.type, metadata: body.metadata, created_at: "2026-06-25T00:00:00.000Z", updated_at: "2026-06-25T00:00:00.000Z", }); return Response.json(ragDocuments.get(body.id), { status: 201 }); } } const fileMatch = url.pathname.match( /^\/projects\/[^/]+\/branches\/[^/]+\/files\/(.+)\/chunks$/, ); const filePath = fileMatch ? decodeURIComponent(fileMatch[1] ?? "") : null; if (request.method === "POST" && filePath) { const body = await request.json() as { chunks: Array<{ chunk_index: number; content: string; metadata?: Record; }>; }; const stored = body.chunks.map((chunk) => ({ id: `${filePath}:${chunk.chunk_index}`, index: chunk.chunk_index, content: chunk.content, metadata: chunk.metadata, })); fileChunks.set(filePath, stored); return Response.json({ chunks: stored.map(({ id, index }) => ({ id, index })), }); } if (request.method === "POST" && url.pathname.endsWith("/embeddings")) { return Response.json({ embeddings: [{ id: "embedding-1", model: "test/demo", status: "ready" }], }); } throw new Error(`Unhandled ${request.method} ${url.pathname}`); }, async () => { const store = ragStore({ contentDir: "knowledge", model: "test/demo", }); await runWithRequestContext( { projectSlug: "cloud-project", token: "vf_request_token", productionMode: true, releaseId: "rel-abc", }, () => store.indexContentDir(), ); const documents = [...ragDocuments.values()]; assertEquals(documents.length, 1); assertEquals(documents[0]?.title, "login-troubleshooting"); assertEquals(documents[0]?.source, "knowledge/login-troubleshooting.md"); assertEquals(fileChunks.size, 1); assertEquals( requestedPaths.includes("/projects/cloud-project/releases/rel-abc/files"), true, ); }, ); }); it("respects VERYFRONT_RAG_BACKEND=local-json as an override", async () => { setEnv("VERYFRONT_API_TOKEN", "vf_test_cloud"); setEnv("VERYFRONT_PROJECT_SLUG", "cloud-project"); setEnv("VERYFRONT_RAG_BACKEND", "local-json"); await withTempDir(async (tempDir) => { const storagePath = join(tempDir, "data", "index.json"); const store = ragStore({ model: "local/test-model", storagePath, }); const id = await store.ingest("Local Doc", "Hello local override", { source: "upload:local.txt", type: "txt", }); const documents = await store.listDocuments(); assertEquals(documents.length, 1); assertEquals(documents[0]?.id, id); assertEquals(await exists(storagePath), true); }); }); });