libre-webui 0.21.2 → 0.22.0

package/backend/dist/services/documentService.js

@@ -14,25 +14,222 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import crypto from 'node:crypto';
+import { Readable } from 'node:stream';
 import { v4 as uuidv4 } from 'uuid';
 import storageService from '../storage.js';
-import embeddingService from './embeddingService.js';
+import { configurePlatformStorageRuntime, getPlatformStorageRuntime, } from '../platform/storage/index.js';
+import { MAX_VECTOR_RECORDS_PER_UPSERT, MAX_VECTOR_RESOURCE_INDEX_ENTRIES, } from '../platform/storage/vectorStore.js';
+import { aggregateDocumentIndexRevision, createDocumentIndexMetadata, DOCUMENT_CHUNKER_VERSION, DOCUMENT_INDEX_METADATA_KEY, DOCUMENT_VECTOR_NAMESPACE, DOCUMENT_VECTOR_VERSION, documentChunkSourceRevision as sourceRevision, documentEmbeddingDimensions as embeddingDimensions, documentIndexMatchesSpec, embeddedDocumentChunks as embeddedChunks, readDocumentIndexMetadata as readDocumentIndexMetadataValue, } from '../platform/storage/documentVectorIndex.js';
+import { getCoordinator } from '../platform/coordination/service.js';
+import { DOCUMENT_INGEST_IDEMPOTENCY_SCOPE } from '../platform/jobs/domainJobContracts.js';
+import { transactionalDocumentIngestionEnqueuer } from '../platform/jobs/documentIngestionEnqueuer.js';
+import { getDurableJobRuntime } from '../platform/jobs/durableJobRuntime.js';
+import { transactionalResourceDeletionEnqueuer } from '../platform/jobs/resourceDeletionEnqueuer.js';
 import preferencesService from './preferencesService.js';
 import { createLogger } from '../utils/logger.js';
+import { throwIfChatGenerationCancelled } from '../utils/chatCancellation.js';
 const logger = createLogger('documents');
-// Utility functions for vector operations
-const cosineSimilarity = (a, b) => {
-    if (a.length !== b.length)
-        return 0;
-    let dotProduct = 0;
-    let normA = 0;
-    let normB = 0;
-    for (let i = 0; i < a.length; i++) {
-        dotProduct += a[i] * b[i];
-        normA += a[i] * a[i];
-        normB += b[i] * b[i];
-    }
-    return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
+const DOCUMENT_BLOB_PURPOSE = 'document.source';
+const DOCUMENT_POST_VECTOR_FAULT_MARKER = 'LIBRE_DOCUMENT_POST_VECTOR_KILL';
+const DOCUMENT_RESOURCE_LEASE_WAIT_MS = 15000;
+const MAX_VECTOR_RESOURCE_FILTERS = 100;
+export class DocumentResourceBusyError extends Error {
+    constructor() {
+        super('Document indexing is already in progress; retry shortly');
+        this.name = 'DocumentResourceBusyError';
+    }
+}
+export class DocumentChunkLimitError extends Error {
+    constructor(chunks) {
+        super(`Document produces ${chunks} chunks; the maximum is ${MAX_VECTOR_RESOURCE_INDEX_ENTRIES}. Increase the embedding chunk size or remove excessive paragraph breaks.`);
+        this.chunks = chunks;
+        this.name = 'DocumentChunkLimitError';
+    }
+}
+class DocumentIndexSupersededError extends Error {
+    constructor() {
+        super('Document disappeared while its vector index was being published');
+        this.name = 'DocumentIndexSupersededError';
+    }
+}
+const resourceLeaseTtlMs = () => {
+    const value = Number.parseInt(process.env.RESOURCE_LEASE_TTL_MS ?? '30000', 10);
+    if (!Number.isSafeInteger(value) || value < 5000 || value > 300000) {
+        throw new Error('RESOURCE_LEASE_TTL_MS must be between 5000 and 300000 milliseconds');
+    }
+    return value;
+};
+const waitForLeaseRetry = (milliseconds, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+        reject(signal.reason ?? new Error('Document indexing was cancelled'));
+        return;
+    }
+    let timer;
+    const abort = () => {
+        clearTimeout(timer);
+        reject(signal?.reason ?? new Error('Document indexing was cancelled'));
+    };
+    timer = setTimeout(() => {
+        signal?.removeEventListener('abort', abort);
+        resolve();
+    }, milliseconds);
+    signal?.addEventListener('abort', abort, { once: true });
+});
+const acquireDocumentResourceLease = async (userId, documentId, signal, waitMs = DOCUMENT_RESOURCE_LEASE_WAIT_MS) => {
+    const coordinator = getCoordinator();
+    const ttlMs = resourceLeaseTtlMs();
+    const deadline = Date.now() + waitMs;
+    let lease = null;
+    do {
+        if (signal?.aborted)
+            throw signal.reason;
+        lease = await coordinator.acquireLease(`resource:${userId}:document:${documentId}`, ttlMs);
+        if (lease)
+            break;
+        if (Date.now() >= deadline)
+            throw new DocumentResourceBusyError();
+        await waitForLeaseRetry(25, signal);
+    } while (!lease);
+    let closed = false;
+    let lost = false;
+    let renewal;
+    const scheduleRenewal = () => {
+        if (closed || lost)
+            return;
+        renewal = setTimeout(async () => {
+            try {
+                if (!(await lease.extend(ttlMs)))
+                    lost = true;
+            }
+            catch {
+                lost = true;
+            }
+            scheduleRenewal();
+        }, Math.max(1000, Math.floor(ttlMs / 3)));
+        renewal.unref?.();
+    };
+    scheduleRenewal();
+    return {
+        async assertHeld() {
+            if (signal?.aborted)
+                throw signal.reason;
+            if (closed || lost)
+                throw new DocumentResourceBusyError();
+            try {
+                if (await lease.extend(ttlMs))
+                    return;
+            }
+            catch {
+                // Report the same safe error for expiry and coordinator outages.
+            }
+            lost = true;
+            throw new DocumentResourceBusyError();
+        },
+        async release() {
+            if (closed)
+                return false;
+            closed = true;
+            if (renewal)
+                clearTimeout(renewal);
+            return lease.release();
+        },
+    };
+};
+const deterministicDocumentChunkId = (documentId, chunkIndex, content) => {
+    const digest = crypto
+        .createHash('sha256')
+        .update('libre-document-chunk-v1\u0000')
+        .update(documentId)
+        .update('\u0000')
+        .update(String(chunkIndex))
+        .update('\u0000')
+        .update(content, 'utf8')
+        .digest();
+    // Preserve the familiar UUID shape while deriving the identity from source
+    // state. Retries therefore overwrite the same SQL/vector record.
+    digest[6] = (digest[6] & 0x0f) | 0x50;
+    digest[8] = (digest[8] & 0x3f) | 0x80;
+    const hex = digest.subarray(0, 16).toString('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+};
+const readDocumentIndexMetadata = (document) => readDocumentIndexMetadataValue(document.metadata);
+const hasValidDocumentIndexMetadata = (document) => readDocumentIndexMetadata(document) !== undefined;
+const exactLocalDocumentIndexProbe = (document, chunks, userId, spec) => {
+    const metadata = readDocumentIndexMetadata(document);
+    if (!documentIndexMatchesSpec(metadata, spec) ||
+        metadata.dimensions === null) {
+        return undefined;
+    }
+    const embedded = embeddedChunks(chunks);
+    if (embedded.length === 0 || embedded.length !== chunks.length) {
+        return undefined;
+    }
+    if (embeddingDimensions(embedded) !== metadata.dimensions ||
+        aggregateDocumentIndexRevision(embedded, spec) !==
+            metadata.aggregateRevision) {
+        return undefined;
+    }
+    return {
+        actor: { userId },
+        namespace: DOCUMENT_VECTOR_NAMESPACE,
+        resourceId: document.id,
+        model: spec.model,
+        dimensions: metadata.dimensions,
+        version: spec.version,
+        entries: embedded.map(chunk => ({
+            id: chunk.id,
+            sourceRevision: sourceRevision(chunk),
+        })),
+    };
+};
+const withDocumentIndexMetadata = (document, chunks, spec) => {
+    const metadata = createDocumentIndexMetadata(chunks, spec);
+    return {
+        ...document,
+        metadata: {
+            ...(document.metadata ?? {}),
+            [DOCUMENT_INDEX_METADATA_KEY]: metadata,
+        },
+    };
+};
+const delayAfterVectorUpsertForRecoveryDrill = async (document, attemptCount, signal) => {
+    if (process.env.LIBRE_ENABLE_TEST_FAULT_INJECTION !== 'true' ||
+        attemptCount !== 1 ||
+        !document.content?.includes(DOCUMENT_POST_VECTOR_FAULT_MARKER)) {
+        return;
+    }
+    const delayMs = Number.parseInt(process.env.LIBRE_TEST_FAULT_DELAY_MS ?? '60000', 10);
+    if (!Number.isSafeInteger(delayMs) || delayMs < 1 || delayMs > 300000) {
+        throw new Error('Invalid recovery-drill fault delay');
+    }
+    await new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason ?? new Error('Document ingestion was cancelled'));
+            return;
+        }
+        let settled = false;
+        let timer;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', abort);
+            if (error === undefined)
+                resolve();
+            else
+                reject(error);
+        };
+        const abort = () => finish(signal?.reason ?? new Error('Document ingestion was cancelled'));
+        timer = setTimeout(finish, delayMs);
+        timer.unref?.();
+        signal?.addEventListener('abort', abort, { once: true });
+    });
+};
+/** Installed by team-mode bootstrap so all replicas share S3 and PGVector. */
+export const configureDocumentPlatformStorage = (storage) => {
+    configurePlatformStorageRuntime(storage);
 };
 // Lazy load pdfjs-dist legacy build for Node.js
 let pdfjsLib = null;
@@ -51,85 +248,177 @@ const getPdfjsLib = async () => {
     }
     return pdfjsLib;
 };
-class DocumentService {
-    constructor() {
-        this.documents = new Map();
-        this.chunks = new Map();
-        this.loadDocuments();
-        this.loadChunks();
+const extractDocumentContent = async (fileBuffer, mimeType, signal) => {
+    if (signal?.aborted)
+        throw signal.reason;
+    if (mimeType === 'text/plain') {
+        return { content: fileBuffer.toString('utf8'), fileType: 'txt' };
     }
-    loadDocuments() {
-        try {
-            const documentsArray = storageService.getAllDocuments();
-            this.documents = new Map(documentsArray.map(doc => [doc.id, doc]));
-            logger.debug(`Loaded ${documentsArray.length} documents from storage`);
+    if (mimeType !== 'application/pdf') {
+        throw new Error(`Unsupported file type: ${mimeType}`);
+    }
+    const pdfLib = await getPdfjsLib();
+    const pdfDocument = await pdfLib.getDocument({
+        data: new Uint8Array(fileBuffer),
+    }).promise;
+    let textContent = '';
+    for (let pageNum = 1; pageNum <= pdfDocument.numPages; pageNum += 1) {
+        if (signal?.aborted)
+            throw signal.reason;
+        const page = await pdfDocument.getPage(pageNum);
+        const pageText = await page.getTextContent();
+        textContent += `${pageText.items
+            .map(item => ('str' in item ? item.str : ''))
+            .join(' ')}\n\n`;
+    }
+    return { content: textContent.trim(), fileType: 'pdf' };
+};
+export class DocumentService {
+    async captureEmbeddingExecutionSpec(userId) {
+        const settings = (await preferencesService.getPreferences(userId))
+            .embeddingSettings;
+        const model = settings.model.trim();
+        if (!model || Buffer.byteLength(model, 'utf8') > 256) {
+            throw new Error('Embedding model must contain 1-256 bytes');
         }
-        catch (error) {
-            logger.error('Failed to load documents:', error);
+        if (!Number.isSafeInteger(settings.chunkSize) ||
+            settings.chunkSize < 1 ||
+            settings.chunkSize > 1000000) {
+            throw new Error('Embedding chunk size must be between 1 and 1000000');
+        }
+        if (!Number.isSafeInteger(settings.chunkOverlap) ||
+            settings.chunkOverlap < 0 ||
+            settings.chunkOverlap >= settings.chunkSize) {
+            throw new Error('Embedding chunk overlap must be non-negative and smaller than the chunk size');
         }
+        if (!Number.isFinite(settings.similarityThreshold) ||
+            settings.similarityThreshold < -1 ||
+            settings.similarityThreshold > 1) {
+            throw new Error('Embedding similarity threshold must be between -1 and 1');
+        }
+        return Object.freeze({
+            enabled: settings.enabled === true,
+            model,
+            version: DOCUMENT_VECTOR_VERSION,
+            chunkerVersion: DOCUMENT_CHUNKER_VERSION,
+            chunkSize: settings.chunkSize,
+            chunkOverlap: settings.chunkOverlap,
+            similarityThreshold: settings.similarityThreshold,
+        });
     }
-    loadChunks() {
-        try {
-            // Load chunks for all documents
-            const documentsArray = Array.from(this.documents.values());
-            for (const doc of documentsArray) {
-                const chunks = storageService.getDocumentChunks(doc.id);
-                if (chunks.length > 0) {
-                    this.chunks.set(doc.id, chunks);
-                }
+    async assertDocumentIndexAuthoritative(documentId, userId, aggregateRevision, expectedSource) {
+        const platform = getPlatformStorageRuntime();
+        const [document, reserved] = await Promise.all([
+            platform.domains.documents.findByOwner(documentId, userId),
+            platform.domains.resourceDeletions.isReserved('document', documentId),
+        ]);
+        if (!document || reserved)
+            throw new DocumentIndexSupersededError();
+        if (aggregateRevision) {
+            const metadata = readDocumentIndexMetadata(document);
+            if (metadata?.aggregateRevision !== aggregateRevision) {
+                throw new DocumentIndexSupersededError();
             }
-            logger.debug(`Loaded chunks for ${this.chunks.size} documents from storage`);
         }
-        catch (error) {
-            logger.error('Failed to load document chunks:', error);
+        if (expectedSource &&
+            ((document.content ?? null) !== expectedSource.content ||
+                (document.fileType ?? null) !== expectedSource.fileType)) {
+            throw new DocumentIndexSupersededError();
         }
+        return document;
     }
-    saveDocuments() {
-        // This method is no longer needed as we save documents individually
-        // through the storage service
-    }
-    saveChunks() {
-        // This method is no longer needed as we save chunks individually
-        // through the storage service
-    }
-    async processDocument(fileName, fileBuffer, mimeType, userId, sessionId) {
+    /**
+     * Persist the private source and publish extraction in the same SQL
+     * transaction as the document placeholder. The object write is compensated
+     * if the SQL transaction cannot commit.
+     */
+    async queueDocumentProcessing(fileName, fileBuffer, mimeType, userId, sessionId, signal) {
+        if (mimeType !== 'text/plain' && mimeType !== 'application/pdf') {
+            throw new Error(`Unsupported file type: ${mimeType}`);
+        }
+        if (signal?.aborted)
+            throw signal.reason;
         const documentId = uuidv4();
-        let content = '';
-        let fileType;
+        const now = Date.now();
+        const document = {
+            id: documentId,
+            filename: fileName,
+            content: '',
+            fileType: mimeType === 'application/pdf' ? 'pdf' : 'txt',
+            size: fileBuffer.length,
+            ...(sessionId ? { sessionId } : {}),
+            uploadedAt: now,
+            createdAt: now,
+            metadata: { processingStatus: 'queued' },
+        };
+        const platform = getPlatformStorageRuntime();
+        const sourceBlob = await platform.blobStore.put({
+            ownerUserId: userId,
+            purpose: DOCUMENT_BLOB_PURPOSE,
+            contentType: mimeType,
+            originalFilename: fileName,
+            expectedSize: fileBuffer.length,
+            metadata: { resourceType: 'document', resourceId: documentId },
+            source: Readable.from(fileBuffer),
+            ...(signal ? { signal } : {}),
+        });
         try {
-            if (mimeType === 'application/pdf') {
-                try {
-                    const pdfLib = await getPdfjsLib();
-                    // Convert Buffer to Uint8Array for pdfjs-dist compatibility
-                    const uint8Array = new Uint8Array(fileBuffer);
-                    const pdfDocument = await pdfLib.getDocument({ data: uint8Array })
-                        .promise;
-                    const numPages = pdfDocument.numPages;
-                    let textContent = '';
-                    for (let pageNum = 1; pageNum <= numPages; pageNum++) {
-                        const page = await pdfDocument.getPage(pageNum);
-                        const pageText = await page.getTextContent();
-                        const pageContent = pageText.items
-                            .map(item => ('str' in item ? item.str : ''))
-                            .join(' ');
-                        textContent += pageContent + '\n\n';
-                    }
-                    content = textContent.trim();
-                    fileType = 'pdf';
+            await platform.domains.documents.upsertWithBlobAndEnqueue(document, userId, {
+                blobId: sourceBlob.id,
+                ownerUserId: userId,
+                resourceType: 'document',
+                resourceId: documentId,
+                purpose: DOCUMENT_BLOB_PURPOSE,
+                createdAt: Date.parse(sourceBlob.createdAt) || now,
+            }, transactionalDocumentIngestionEnqueuer);
+        }
+        catch (error) {
+            // A PostgreSQL COMMIT can succeed even when its acknowledgement is
+            // lost. Resolve that unknown outcome from authoritative state before
+            // compensating the already-durable blob; deleting first would leave a
+            // committed document/reference/job pointing at a missing object.
+            try {
+                const [publishedDocument, publishedReference, publishedJob] = await Promise.all([
+                    platform.domains.documents.findByOwner(documentId, userId),
+                    platform.blobReferences.find('document', documentId, DOCUMENT_BLOB_PURPOSE),
+                    getDurableJobRuntime().service.getByIdempotency(userId, DOCUMENT_INGEST_IDEMPOTENCY_SCOPE, documentId),
+                ]);
+                const committed = publishedDocument !== undefined &&
+                    publishedReference?.blobId === sourceBlob.id &&
+                    publishedReference.ownerUserId === userId &&
+                    publishedJob != null;
+                if (committed && publishedJob) {
+                    return { document, jobId: publishedJob.id };
                 }
-                catch (pdfError) {
-                    logger.error('PDF parsing error:', pdfError);
-                    throw new Error(`Failed to parse PDF: ${pdfError instanceof Error ? pdfError.message : 'Unknown PDF error'}`);
+                const safelyAbsent = publishedDocument === undefined &&
+                    publishedReference === undefined &&
+                    publishedJob == null;
+                if (!safelyAbsent) {
+                    throw new Error('Document ingestion publish outcome is inconsistent; the source blob was retained for recovery');
                 }
             }
-            else if (mimeType === 'text/plain') {
-                content = fileBuffer.toString('utf-8');
-                fileType = 'txt';
-            }
-            else {
-                throw new Error(`Unsupported file type: ${mimeType}`);
+            catch (resolutionError) {
+                logger.error('Document ingestion publish failed and its outcome could not be resolved', error, resolutionError);
+                throw new Error('Could not resolve the document ingestion transaction outcome; the source blob was retained for recovery');
             }
-            const document = {
+            await platform.blobStore
+                .delete({ id: sourceBlob.id, ownerUserId: userId })
+                .catch(cleanupError => {
+                logger.warn('Document source cleanup failed after a rolled-back publish; lifecycle reconciliation will retry it', cleanupError);
+            });
+            throw error;
+        }
+        const job = await getDurableJobRuntime().service.getByIdempotency(userId, DOCUMENT_INGEST_IDEMPOTENCY_SCOPE, documentId);
+        if (!job) {
+            throw new Error('Document ingestion transaction did not publish its job');
+        }
+        return { document, jobId: job.id };
+    }
+    async processDocument(fileName, fileBuffer, mimeType, userId, sessionId) {
+        const documentId = uuidv4();
+        try {
+            const { content, fileType } = await extractDocumentContent(fileBuffer, mimeType);
+            let document = {
                 id: documentId,
                 filename: fileName,
                 content,
@@ -138,15 +427,53 @@ class DocumentService {
                 sessionId,
                 uploadedAt: Date.now(),
             };
-            // Process the document into chunks
-            const chunks = this.chunkDocument(document, userId);
+            const spec = await this.captureEmbeddingExecutionSpec(userId);
+            // Process the document into chunks under one immutable execution spec.
+            const chunks = this.chunkDocument(document, spec);
             // Generate embeddings for chunks if enabled
-            const chunksWithEmbeddings = await this.generateEmbeddingsForChunks(chunks, userId);
-            // Store document and chunks
-            this.documents.set(documentId, document);
-            this.chunks.set(documentId, chunksWithEmbeddings);
-            storageService.saveDocument(document, userId);
-            storageService.saveDocumentChunks(documentId, chunksWithEmbeddings);
+            const chunksWithEmbeddings = await this.generateEmbeddingsForChunks(chunks, userId, spec);
+            document = withDocumentIndexMetadata(document, chunksWithEmbeddings, spec);
+            const platform = getPlatformStorageRuntime();
+            const sourceBlob = await platform.blobStore.put({
+                ownerUserId: userId,
+                purpose: DOCUMENT_BLOB_PURPOSE,
+                contentType: mimeType,
+                originalFilename: fileName,
+                expectedSize: fileBuffer.length,
+                metadata: { resourceType: 'document', resourceId: documentId },
+                source: Readable.from(fileBuffer),
+            });
+            try {
+                await storageService.saveDocument(document, userId);
+                await storageService.saveDocumentChunks(documentId, chunksWithEmbeddings);
+                await platform.blobReferences.attach({
+                    blobId: sourceBlob.id,
+                    ownerUserId: userId,
+                    resourceType: 'document',
+                    resourceId: documentId,
+                    purpose: DOCUMENT_BLOB_PURPOSE,
+                    createdAt: Date.now(),
+                });
+                await this.indexDocumentChunks(document, chunksWithEmbeddings, userId, spec);
+            }
+            catch (error) {
+                await platform.vectorStore
+                    .delete({
+                    actor: { userId },
+                    namespace: DOCUMENT_VECTOR_NAMESPACE,
+                    resourceId: documentId,
+                })
+                    .catch(() => undefined);
+                await platform.blobReferences
+                    .detach('document', documentId, DOCUMENT_BLOB_PURPOSE)
+                    .catch(() => undefined);
+                await platform.blobStore
+                    .delete({ id: sourceBlob.id, ownerUserId: userId })
+                    .catch(() => undefined);
+                await storageService.deleteDocumentChunks(documentId);
+                await storageService.deleteDocument(documentId, userId);
+                throw error;
+            }
             logger.debug(`Processed ${fileType.toUpperCase()} document: ${fileName} (${chunksWithEmbeddings.length} chunks)`);
             return document;
         }
@@ -155,11 +482,16 @@ class DocumentService {
             throw new Error(`Failed to process document: ${error instanceof Error ? error.message : 'Unknown error'}`);
         }
     }
-    chunkDocument(document, userId) {
+    chunkDocument(document, spec) {
         const chunks = [];
-        const preferences = preferencesService.getPreferences(userId);
-        const chunkSize = preferences.embeddingSettings?.chunkSize || 1000; // characters per chunk
-        const overlap = preferences.embeddingSettings?.chunkOverlap || 200; // character overlap between chunks
+        const appendChunk = (chunk) => {
+            if (chunks.length >= MAX_VECTOR_RESOURCE_INDEX_ENTRIES) {
+                throw new DocumentChunkLimitError(chunks.length + 1);
+            }
+            chunks.push(chunk);
+        };
+        const chunkSize = spec.chunkSize;
+        const overlap = spec.chunkOverlap;
         const text = document.content?.trim();
         if (!text)
             return chunks;
@@ -180,10 +512,11 @@ class DocumentService {
                 if (currentChunk.trim()) {
                     const chunkStart = currentOffset - currentChunk.length;
                     const chunkEnd = currentOffset;
-                    chunks.push({
-                        id: uuidv4(),
+                    const content = currentChunk.trim();
+                    appendChunk({
+                        id: deterministicDocumentChunkId(document.id, chunkIndex, content),
                         documentId: document.id,
-                        content: currentChunk.trim(),
+                        content,
                         chunkIndex: chunkIndex++,
                         startChar: Math.max(0, chunkStart),
                         endChar: chunkEnd,
@@ -191,8 +524,12 @@ class DocumentService {
                 }
                 // Start new chunk with overlap from previous chunk
                 const words = currentChunk.split(' ');
-                const overlapWords = words.slice(-calculateOverlapWordCount(overlap));
-                currentChunk = overlapWords.join(' ') + '\n\n' + paragraphText;
+                const overlapWordCount = calculateOverlapWordCount(overlap);
+                const overlapWords = overlapWordCount === 0 ? [] : words.slice(-overlapWordCount);
+                currentChunk =
+                    overlapWords.length === 0
+                        ? paragraphText
+                        : `${overlapWords.join(' ')}\n\n${paragraphText}`;
                 currentOffset += paragraphText.length + 2; // +2 for \n\n
             }
             else {
@@ -211,10 +548,11 @@ class DocumentService {
         if (currentChunk.trim()) {
             const chunkStart = currentOffset - currentChunk.length;
             const chunkEnd = currentOffset;
-            chunks.push({
-                id: uuidv4(),
+            const content = currentChunk.trim();
+            appendChunk({
+                id: deterministicDocumentChunkId(document.id, chunkIndex, content),
                 documentId: document.id,
-                content: currentChunk.trim(),
+                content,
                 chunkIndex: chunkIndex,
                 startChar: Math.max(0, chunkStart),
                 endChar: chunkEnd,
@@ -222,100 +560,317 @@ class DocumentService {
         }
         return chunks;
     }
-    async generateEmbeddingForText(text, userId) {
+    async generateEmbeddingForText(text, userId, spec, signal) {
         try {
-            const preferences = preferencesService.getPreferences(userId);
-            if (!preferences.embeddingSettings.enabled) {
+            if (!spec.enabled)
                 return null;
-            }
+            // Provider/plugin construction is stateful and must happen only after
+            // the selected persistence backend has completed bootstrap.
+            const { default: embeddingService } = await import('./embeddingService.js');
             const response = await embeddingService.generateEmbeddings({
-                model: preferences.embeddingSettings.model,
+                model: spec.model,
                 input: text,
-            }, userId);
+            }, userId, signal);
             return response.embeddings[0] || null;
         }
         catch (error) {
+            if (signal?.aborted)
+                throw error;
             logger.error('Failed to generate embedding:', error);
             return null;
         }
     }
-    async generateEmbeddingsForChunks(chunks, userId) {
-        const preferences = preferencesService.getPreferences(userId);
-        if (!preferences.embeddingSettings.enabled) {
+    async generateEmbeddingsForChunks(chunks, userId, spec, signal, assertSideEffectAllowed) {
+        if (!spec.enabled)
             return chunks;
-        }
         logger.debug(`Generating embeddings for ${chunks.length} chunks...`);
         const chunksWithEmbeddings = [];
         for (const chunk of chunks) {
-            const embedding = await this.generateEmbeddingForText(chunk.content, userId);
+            await assertSideEffectAllowed?.();
+            const embedding = await this.generateEmbeddingForText(chunk.content, userId, spec, signal);
+            if (!embedding) {
+                throw new Error('Embedding generation returned no vector');
+            }
             chunksWithEmbeddings.push({
                 ...chunk,
-                embedding: embedding || undefined,
+                embedding,
             });
         }
+        embeddingDimensions(embeddedChunks(chunksWithEmbeddings));
         logger.debug(`Generated embeddings for ${chunksWithEmbeddings.filter(c => c.embedding).length} chunks`);
         return chunksWithEmbeddings;
     }
-    // Method to regenerate embeddings for all existing documents
-    async regenerateAllEmbeddings(userId) {
-        const preferences = preferencesService.getPreferences(userId);
-        if (!preferences.embeddingSettings.enabled) {
+    /**
+     * Older solo databases stored inline vectors without recording which model
+     * produced them. Presence is therefore only an upgrade signal: rebuild the
+     * authoritative document from text under today's immutable execution spec,
+     * and never copy or relabel the legacy payload.
+     */
+    async upgradeLegacyDocumentIndex(document, userId, spec, signal) {
+        const platform = getPlatformStorageRuntime();
+        if (platform.dialect !== 'sqlite' ||
+            hasValidDocumentIndexMetadata(document) ||
+            !document.content?.trim()) {
+            return undefined;
+        }
+        const legacy = await platform.domains.documents.inspectLegacyChunkEmbeddings(document.id, userId);
+        if (!legacy.present)
+            return undefined;
+        let lease;
+        try {
+            lease = await acquireDocumentResourceLease(userId, document.id, signal, 0);
+            await lease.assertHeld();
+            const current = await this.assertDocumentIndexAuthoritative(document.id, userId);
+            if (hasValidDocumentIndexMetadata(current)) {
+                return {
+                    document: current,
+                    chunks: await this.loadDocumentChunks(current.id),
+                };
+            }
+            if (!current.content?.trim())
+                return undefined;
+            const currentLegacy = await platform.domains.documents.inspectLegacyChunkEmbeddings(current.id, userId);
+            if (!currentLegacy.present)
+                return undefined;
+            if (!currentLegacy.authenticated) {
+                logger.warn(`Legacy inline embeddings for document ${current.id} failed authentication; rebuilding from authoritative text`);
+            }
+            const chunks = this.chunkDocument(current, spec);
+            if (chunks.length === 0) {
+                logger.debug(`Legacy document ${current.id} has no authoritative text to reindex`);
+                return undefined;
+            }
+            const embedded = await this.generateEmbeddingsForChunks(chunks, userId, spec, signal, () => lease.assertHeld());
+            await lease.assertHeld();
+            const latest = await this.assertDocumentIndexAuthoritative(current.id, userId, undefined, {
+                content: current.content ?? null,
+                fileType: current.fileType ?? null,
+            });
+            if (hasValidDocumentIndexMetadata(latest)) {
+                throw new DocumentIndexSupersededError();
+            }
+            const published = withDocumentIndexMetadata(latest, embedded, spec);
+            const embeddingIndex = readDocumentIndexMetadata(published);
+            if (!embeddingIndex) {
+                throw new Error('Document embedding index metadata is invalid');
+            }
+            const completed = await platform.domains.documents.publishEmbeddingIndex(current.id, userId, {
+                content: current.content ?? null,
+                fileType: current.fileType ?? null,
+            }, embeddingIndex, embedded);
+            if (!completed)
+                throw new DocumentIndexSupersededError();
+            await lease.assertHeld();
+            const authoritative = await this.assertDocumentIndexAuthoritative(current.id, userId, embeddingIndex.aggregateRevision, {
+                content: current.content ?? null,
+                fileType: current.fileType ?? null,
+            });
+            await this.indexDocumentChunks(authoritative, embedded, userId, spec, 1, signal, () => lease.assertHeld());
+            return { document: authoritative, chunks: embedded };
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw error;
+            if (!(error instanceof DocumentResourceBusyError) &&
+                !(error instanceof DocumentIndexSupersededError)) {
+                logger.warn(`Could not upgrade legacy document embeddings for ${document.id}; keyword fallback remains available`, error);
+            }
+            return undefined;
+        }
+        finally {
+            await lease?.release().catch(() => false);
+        }
+    }
+    /**
+     * Rebuild every document under one immutable preference snapshot. Each
+     * resource uses the same renewable coordinator lease as ingestion/deletion,
+     * while the relational delete is still allowed to publish its tombstone.
+     * The final authoritative check then removes any vector recreated after that
+     * tombstone committed.
+     */
+    async regenerateAllEmbeddings(userId, signal) {
+        const spec = await this.captureEmbeddingExecutionSpec(userId);
+        const documents = await storageService.getAllDocuments(userId);
+        const result = {
+            documentsTotal: documents.length,
+            documentsRegenerated: 0,
+            documentsSkipped: 0,
+            chunksTotal: 0,
+            chunksEmbedded: 0,
+            model: spec.model,
+            version: spec.version,
+        };
+        if (!spec.enabled) {
+            result.documentsSkipped = documents.length;
             logger.debug('Embeddings are disabled, skipping regeneration');
-            return;
+            return result;
         }
         logger.debug('Starting to regenerate embeddings for all documents...');
-        let processedChunks = 0;
-        let totalChunks = 0;
-        for (const document of storageService.getAllDocuments(userId)) {
-            const documentId = document.id;
-            const chunks = this.loadDocumentChunks(documentId);
-            totalChunks += chunks.length;
-            const chunksWithEmbeddings = await this.generateEmbeddingsForChunks(chunks, userId);
-            this.chunks.set(documentId, chunksWithEmbeddings);
-            storageService.saveDocumentChunks(documentId, chunksWithEmbeddings);
-            processedChunks += chunksWithEmbeddings.filter(c => c.embedding).length;
+        for (const listedDocument of documents) {
+            if (signal?.aborted)
+                throw signal.reason;
+            let lease;
+            try {
+                lease = await acquireDocumentResourceLease(userId, listedDocument.id, signal);
+            }
+            catch (error) {
+                if (error instanceof DocumentResourceBusyError) {
+                    result.documentsSkipped += 1;
+                    continue;
+                }
+                throw error;
+            }
+            try {
+                await lease.assertHeld();
+                const current = await this.assertDocumentIndexAuthoritative(listedDocument.id, userId);
+                const chunks = this.chunkDocument(current, spec);
+                result.chunksTotal += chunks.length;
+                const embedded = await this.generateEmbeddingsForChunks(chunks, userId, spec, signal, () => lease.assertHeld());
+                await lease.assertHeld();
+                const latest = await this.assertDocumentIndexAuthoritative(current.id, userId);
+                if (latest.content !== current.content ||
+                    latest.fileType !== current.fileType) {
+                    throw new DocumentIndexSupersededError();
+                }
+                // Preserve routing/metadata changes published while embedding work was
+                // in flight. The repository merges only embeddingIndex and chunks
+                // under its row/write lock, so an acknowledged collection/session
+                // change can never be replaced by this stale service snapshot.
+                const published = withDocumentIndexMetadata(latest, embedded, spec);
+                const embeddingIndex = readDocumentIndexMetadata(published);
+                if (!embeddingIndex) {
+                    throw new Error('Document embedding index metadata is invalid');
+                }
+                const completed = await getPlatformStorageRuntime().domains.documents.publishEmbeddingIndex(current.id, userId, {
+                    content: current.content ?? null,
+                    fileType: current.fileType ?? null,
+                }, embeddingIndex, embedded);
+                if (!completed)
+                    throw new DocumentIndexSupersededError();
+                await lease.assertHeld();
+                const authoritativePublished = await this.assertDocumentIndexAuthoritative(current.id, userId, embeddingIndex.aggregateRevision, {
+                    content: current.content ?? null,
+                    fileType: current.fileType ?? null,
+                });
+                await this.indexDocumentChunks(authoritativePublished, embedded, userId, spec, 1, signal, () => lease.assertHeld());
+                result.documentsRegenerated += 1;
+                result.chunksEmbedded += embedded.length;
+            }
+            catch (error) {
+                if (error instanceof DocumentIndexSupersededError) {
+                    result.documentsSkipped += 1;
+                    continue;
+                }
+                throw error;
+            }
+            finally {
+                await lease.release().catch(() => false);
+            }
         }
-        logger.debug(`Regenerated embeddings for ${processedChunks}/${totalChunks} chunks`);
+        logger.debug(`Regenerated embeddings for ${result.chunksEmbedded}/${result.chunksTotal} chunks`);
+        return result;
+    }
+    /** Durable extraction/embedding handler entrypoint for an existing source. */
+    async reprocessDocument(documentId, userId, signal, assertSideEffectAllowed, attemptCount = 1) {
+        const spec = await this.captureEmbeddingExecutionSpec(userId);
+        const current = await this.getDocument(documentId, userId);
+        if (!current)
+            throw new Error('Document not found');
+        const source = await this.openDocumentSource(documentId, userId, undefined, signal);
+        if (!source)
+            throw new Error('Document source is unavailable');
+        const buffers = [];
+        let size = 0;
+        for await (const chunk of source.body) {
+            if (signal?.aborted)
+                throw signal.reason;
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            size += buffer.length;
+            if (size > 10 * 1024 * 1024) {
+                throw new Error('Document source exceeds the extraction limit');
+            }
+            buffers.push(buffer);
+        }
+        const extracted = await extractDocumentContent(Buffer.concat(buffers, size), source.descriptor.contentType, signal);
+        let document = {
+            ...current,
+            content: extracted.content,
+            fileType: extracted.fileType,
+            size,
+        };
+        const chunks = this.chunkDocument(document, spec);
+        const embedded = await this.generateEmbeddingsForChunks(chunks, userId, spec, signal, assertSideEffectAllowed);
+        document.metadata = {
+            ...(document.metadata ?? {}),
+            processingStatus: 'completed',
+            processedAt: Date.now(),
+        };
+        document = withDocumentIndexMetadata(document, embedded, spec);
+        await assertSideEffectAllowed?.();
+        const completed = await getPlatformStorageRuntime().domains.documents.completeIngestion(document, userId, embedded);
+        if (!completed)
+            throw new Error('Document was deleted during ingestion');
+        await assertSideEffectAllowed?.();
+        await this.indexDocumentChunks(document, embedded, userId, spec, attemptCount, signal, assertSideEffectAllowed);
+        return {
+            chunks: embedded.length,
+            embedded: embedded.filter(chunk => chunk.embedding?.length).length,
+        };
     }
     // Method to get embedding model information
     async getEmbeddingModelInfo(userId) {
-        const preferences = preferencesService.getPreferences(userId);
+        const spec = await this.captureEmbeddingExecutionSpec(userId);
         let chunksWithEmbeddings = 0;
         let totalChunks = 0;
-        for (const document of storageService.getAllDocuments(userId)) {
-            const chunks = this.loadDocumentChunks(document.id);
+        for (const document of await storageService.getAllDocuments(userId)) {
+            const chunks = await this.loadDocumentChunks(document.id);
             totalChunks += chunks.length;
             chunksWithEmbeddings += chunks.filter(c => c.embedding).length;
         }
         return {
-            available: preferences.embeddingSettings.enabled,
-            model: preferences.embeddingSettings.model,
+            available: spec.enabled,
+            model: spec.model,
             chunksWithEmbeddings,
             totalChunks,
         };
     }
-    getDocument(documentId, userId) {
+    async getDocument(documentId, userId) {
         return storageService.getDocument(documentId, userId);
     }
-    getDocuments(userId, sessionId) {
-        const allDocs = storageService.getAllDocuments(userId);
+    async getDocuments(userId, sessionId) {
+        const allDocs = await storageService.getAllDocuments(userId);
         if (sessionId) {
             return allDocs.filter(doc => doc.sessionId === sessionId);
         }
         return allDocs.sort((a, b) => b.uploadedAt - a.uploadedAt);
     }
-    getDocumentChunks(documentId, userId) {
-        if (!this.getDocument(documentId, userId))
+    async getDocumentChunks(documentId, userId) {
+        if (!(await this.getDocument(documentId, userId)))
             return [];
         return this.loadDocumentChunks(documentId);
     }
-    deleteDocument(documentId, userId) {
-        if (!this.getDocument(documentId, userId))
+    async openDocumentSource(documentId, userId, range, signal) {
+        if (!(await this.getDocument(documentId, userId)))
+            return undefined;
+        const platform = getPlatformStorageRuntime();
+        const reference = await platform.blobReferences.find('document', documentId, DOCUMENT_BLOB_PURPOSE);
+        if (!reference || reference.ownerUserId !== userId)
+            return undefined;
+        return platform.blobStore.open({
+            id: reference.blobId,
+            ownerUserId: userId,
+            ...(range ? { range } : {}),
+            ...(signal ? { signal } : {}),
+        });
+    }
+    async deleteDocument(documentId, userId) {
+        if (!(await this.getDocument(documentId, userId)))
+            return false;
+        const platform = getPlatformStorageRuntime();
+        const relationalDeleted = await platform.domains.documents.deleteAndEnqueue(documentId, userId, transactionalResourceDeletionEnqueuer);
+        if (!relationalDeleted)
             return false;
-        const deleted = this.documents.delete(documentId);
-        this.chunks.delete(documentId);
-        storageService.deleteDocumentChunks(documentId);
-        return storageService.deleteDocument(documentId, userId) || deleted;
+        return true;
     }
     /**
      * A document is searchable for a chat when it belongs to that session or
@@ -337,74 +892,263 @@ class DocumentService {
             document.collectionId &&
             collectionIds.includes(document.collectionId));
     }
+    async indexDocumentChunks(document, chunks, userId, spec, attemptCount = 1, signal, assertSideEffectAllowed) {
+        const executionSpec = spec ?? (await this.captureEmbeddingExecutionSpec(userId));
+        const embedded = embeddedChunks(chunks);
+        embeddingDimensions(embedded);
+        const platform = getPlatformStorageRuntime();
+        const revisions = embedded.map(sourceRevision);
+        const aggregateRevision = aggregateDocumentIndexRevision(embedded, executionSpec);
+        const publishedMetadata = readDocumentIndexMetadata(document);
+        if (publishedMetadata &&
+            publishedMetadata.aggregateRevision !== aggregateRevision) {
+            throw new Error('Document index metadata does not match its embeddings');
+        }
+        const expectedRevision = publishedMetadata?.aggregateRevision;
+        const expectedSource = {
+            content: document.content ?? null,
+            fileType: document.fileType ?? null,
+        };
+        await assertSideEffectAllowed?.();
+        await this.assertDocumentIndexAuthoritative(document.id, userId, expectedRevision, expectedSource);
+        let mutated = false;
+        try {
+            // Replace the resource index rather than only upserting the latest IDs.
+            // Deterministic chunk IDs make a crash after upsert retry-safe, while this
+            // deletion removes records from older document revisions.
+            await platform.vectorStore.delete({
+                actor: { userId },
+                namespace: DOCUMENT_VECTOR_NAMESPACE,
+                resourceId: document.id,
+            });
+            mutated = true;
+            await assertSideEffectAllowed?.();
+            await this.assertDocumentIndexAuthoritative(document.id, userId, expectedRevision, expectedSource);
+            for (let offset = 0; offset < embedded.length; offset += MAX_VECTOR_RECORDS_PER_UPSERT) {
+                await assertSideEffectAllowed?.();
+                await this.assertDocumentIndexAuthoritative(document.id, userId, expectedRevision, expectedSource);
+                const batch = embedded.slice(offset, offset + MAX_VECTOR_RECORDS_PER_UPSERT);
+                await platform.vectorStore.upsert({
+                    actor: { userId },
+                    records: batch.map((chunk, index) => ({
+                        namespace: DOCUMENT_VECTOR_NAMESPACE,
+                        id: chunk.id,
+                        ownerUserId: userId,
+                        resourceId: document.id,
+                        model: executionSpec.model,
+                        dimensions: chunk.embedding.length,
+                        version: executionSpec.version,
+                        sourceRevision: revisions[offset + index],
+                        embedding: chunk.embedding,
+                        attributes: {
+                            chunkIndex: String(chunk.chunkIndex),
+                            ...(document.sessionId ? { sessionId: document.sessionId } : {}),
+                            ...(document.collectionId
+                                ? { collectionId: document.collectionId }
+                                : {}),
+                        },
+                    })),
+                });
+                await assertSideEffectAllowed?.();
+                await this.assertDocumentIndexAuthoritative(document.id, userId, expectedRevision, expectedSource);
+            }
+            await delayAfterVectorUpsertForRecoveryDrill(document, attemptCount, signal);
+            await assertSideEffectAllowed?.();
+            await this.assertDocumentIndexAuthoritative(document.id, userId, expectedRevision, expectedSource);
+        }
+        catch (error) {
+            if (mutated) {
+                await platform.vectorStore
+                    .delete({
+                    actor: { userId },
+                    namespace: DOCUMENT_VECTOR_NAMESPACE,
+                    resourceId: document.id,
+                })
+                    .catch(cleanupError => {
+                    logger.error('Failed to compensate a superseded document vector publication', cleanupError);
+                    return 0;
+                });
+            }
+            throw error;
+        }
+    }
     // Enhanced search with semantic similarity using embeddings
-    async searchDocuments(query, userId, sessionId, limit = 5, collectionIds) {
-        const preferences = preferencesService.getPreferences(userId);
+    async searchDocuments(query, userId, sessionId, limit = 5, collectionIds, signal) {
+        const spec = await this.captureEmbeddingExecutionSpec(userId);
         // Use semantic search if embeddings are enabled
-        if (preferences.embeddingSettings.enabled) {
-            return this.semanticSearchDocuments(query, userId, sessionId, limit, collectionIds);
+        if (spec.enabled) {
+            return this.semanticSearchDocuments(query, userId, sessionId, limit, collectionIds, spec, signal);
         }
         // Fall back to keyword search
-        return this.keywordSearchDocuments(query, userId, sessionId, limit, collectionIds);
+        return this.keywordSearchDocuments(query, userId, sessionId, limit, collectionIds, signal);
     }
-    async semanticSearchDocuments(query, userId, sessionId, limit = 5, collectionIds) {
+    async semanticSearchDocuments(query, userId, sessionId, limit = 5, collectionIds, spec, signal) {
         try {
+            const executionSpec = spec ?? (await this.captureEmbeddingExecutionSpec(userId));
             // Generate embedding for the query
-            const queryEmbedding = await this.generateEmbeddingForText(query, userId);
+            const queryEmbedding = await this.generateEmbeddingForText(query, userId, executionSpec, signal);
             if (!queryEmbedding) {
                 logger.warn('Failed to generate query embedding, falling back to keyword search');
-                return this.keywordSearchDocuments(query, userId, sessionId, limit, collectionIds);
-            }
-            const preferences = preferencesService.getPreferences(userId);
-            const results = [];
-            // Chunks without embeddings (uploaded while embeddings were off, or
-            // whose embedding generation failed) would otherwise be invisible to
-            // semantic search forever — exactly the "only my first document is
-            // used" failure. They compete through keyword scoring instead.
+                return this.keywordSearchDocuments(query, userId, sessionId, limit, collectionIds, signal);
+            }
+            const documents = (await storageService.getAllDocuments(userId)).filter(document => this.documentInScope(document, sessionId, collectionIds));
+            const platform = getPlatformStorageRuntime();
+            const chunksById = new Map();
             const unembedded = [];
-            for (const document of storageService.getAllDocuments(userId)) {
-                const documentChunks = this.loadDocumentChunks(document.id);
-                if (!this.documentInScope(document, sessionId, collectionIds))
-                    continue;
-                for (const chunk of documentChunks) {
-                    if (!chunk.embedding) {
-                        unembedded.push({ chunk, document });
-                        continue;
+            for (const document of documents) {
+                throwIfChatGenerationCancelled(signal);
+                let searchableDocument = document;
+                let documentChunks = await this.loadDocumentChunks(document.id);
+                throwIfChatGenerationCancelled(signal);
+                if (platform.dialect === 'sqlite' &&
+                    !hasValidDocumentIndexMetadata(searchableDocument)) {
+                    const upgraded = await this.upgradeLegacyDocumentIndex(searchableDocument, userId, executionSpec, signal);
+                    if (upgraded) {
+                        searchableDocument = upgraded.document;
+                        documentChunks = upgraded.chunks;
                     }
-                    const similarity = cosineSimilarity(queryEmbedding, chunk.embedding);
-                    // Only include chunks above similarity threshold
-                    if (similarity >= preferences.embeddingSettings.similarityThreshold) {
-                        results.push({ chunk, similarity, document });
+                    else {
+                        // A failed vector publication may still have durably published
+                        // current inline chunks. Reload so the exact-index repair below
+                        // can finish it in this same read; provider/busy failures retain
+                        // the original legacy chunks for keyword fallback.
+                        const latest = await platform.domains.documents.findByOwner(document.id, userId);
+                        if (!latest)
+                            continue;
+                        searchableDocument = latest;
+                        documentChunks = await this.loadDocumentChunks(latest.id);
                     }
                 }
+                // SQLite may contain relationally published embeddings from a prior
+                // process while its local vector table still needs publication. Only
+                // publish a revision whose immutable model metadata proves it belongs
+                // to this query spec, and serialize that mutation with regeneration
+                // and deletion cleanup through the shared document resource lease.
+                // PostgreSQL/team reads never mutate PGVector.
+                const publishedIndex = readDocumentIndexMetadata(searchableDocument);
+                const canProveCurrentEmbeddingModel = documentIndexMatchesSpec(publishedIndex, executionSpec);
+                const localIndexProbe = platform.dialect === 'sqlite'
+                    ? exactLocalDocumentIndexProbe(searchableDocument, documentChunks, userId, executionSpec)
+                    : undefined;
+                let localIndexReady = localIndexProbe !== undefined &&
+                    (await platform.vectorStore.hasExactResourceIndex(localIndexProbe));
+                const needsLazyPublication = localIndexProbe !== undefined && !localIndexReady;
+                if (platform.dialect === 'sqlite' &&
+                    localIndexProbe !== undefined &&
+                    needsLazyPublication) {
+                    let lease;
+                    try {
+                        lease = await acquireDocumentResourceLease(userId, document.id, signal, 0);
+                        await lease.assertHeld();
+                        const latest = await this.assertDocumentIndexAuthoritative(document.id, userId, publishedIndex.aggregateRevision);
+                        const latestChunks = await this.loadDocumentChunks(document.id);
+                        const latestProbe = exactLocalDocumentIndexProbe(latest, latestChunks, userId, executionSpec);
+                        if (!latestProbe)
+                            throw new DocumentIndexSupersededError();
+                        const latestIndexReady = await platform.vectorStore.hasExactResourceIndex(latestProbe);
+                        if (!latestIndexReady) {
+                            await this.indexDocumentChunks(latest, latestChunks, userId, executionSpec, 1, signal, () => lease.assertHeld());
+                        }
+                        localIndexReady = true;
+                        searchableDocument = latest;
+                        documentChunks = latestChunks;
+                    }
+                    catch (error) {
+                        if (!(error instanceof DocumentResourceBusyError) &&
+                            !(error instanceof DocumentIndexSupersededError)) {
+                            throw error;
+                        }
+                        // A writer owns the resource or replaced/deleted this revision.
+                        // Skip the optional lazy publication; keyword fallback remains
+                        // available and the next query reloads authoritative state.
+                    }
+                    finally {
+                        await lease?.release().catch(() => false);
+                    }
+                }
+                for (const chunk of documentChunks) {
+                    // PostgreSQL deliberately keeps embeddings only in PGVector, so a
+                    // relational chunk without an `embedding` property can still be the
+                    // authoritative content for a vector hit. Always make every current
+                    // relational chunk available for hit hydration. Metadata tells us
+                    // whether an absent inline embedding means "stored externally" or
+                    // whether this chunk genuinely needs keyword fallback.
+                    chunksById.set(chunk.id, {
+                        chunk,
+                        document: searchableDocument,
+                    });
+                    const indexedForSemanticQuery = canProveCurrentEmbeddingModel &&
+                        publishedIndex !== undefined &&
+                        publishedIndex.dimensions !== null &&
+                        (platform.dialect === 'postgres' || localIndexReady);
+                    if (!indexedForSemanticQuery) {
+                        unembedded.push({ chunk, document: searchableDocument });
+                    }
+                }
+            }
+            const resourceIds = documents.map(document => document.id);
+            const hits = [];
+            for (let offset = 0; offset < resourceIds.length; offset += MAX_VECTOR_RESOURCE_FILTERS) {
+                throwIfChatGenerationCancelled(signal);
+                hits.push(...(await platform.vectorStore.query({
+                    actor: { userId },
+                    namespace: DOCUMENT_VECTOR_NAMESPACE,
+                    model: executionSpec.model,
+                    dimensions: queryEmbedding.length,
+                    version: executionSpec.version,
+                    embedding: queryEmbedding,
+                    limit,
+                    minScore: executionSpec.similarityThreshold,
+                    resourceIds: resourceIds.slice(offset, offset + MAX_VECTOR_RESOURCE_FILTERS),
+                })));
+                throwIfChatGenerationCancelled(signal);
+            }
+            hits.sort((left, right) => right.score - left.score ||
+                left.ownerUserId.localeCompare(right.ownerUserId) ||
+                left.id.localeCompare(right.id));
+            const top = [];
+            const selectedChunkIds = new Set();
+            for (const hit of hits) {
+                if (top.length >= limit)
+                    break;
+                const match = chunksById.get(hit.id);
+                if (!match ||
+                    match.document.id !== hit.resourceId ||
+                    sourceRevision(match.chunk) !== hit.sourceRevision ||
+                    selectedChunkIds.has(match.chunk.id)) {
+                    continue;
+                }
+                top.push({
+                    ...match.chunk,
+                    filename: match.document.filename,
+                });
+                selectedChunkIds.add(match.chunk.id);
             }
-            const top = results
-                .sort((a, b) => b.similarity - a.similarity)
-                .slice(0, limit)
-                .map(result => ({
-                ...result.chunk,
-                filename: result.document.filename, // Add filename for context
-            }));
             if (top.length < limit && unembedded.length > 0) {
                 const scored = this.scoreChunksByKeywords(query, unembedded);
                 for (const entry of scored) {
                     if (top.length >= limit)
                         break;
+                    if (selectedChunkIds.has(entry.chunk.id))
+                        continue;
                     top.push({
                         ...entry.chunk,
                         filename: entry.document.filename,
                     });
+                    selectedChunkIds.add(entry.chunk.id);
                 }
             }
             if (top.length > 0)
                 return top;
             // Nothing cleared the similarity threshold: keyword search is a
             // better answer than an empty context.
-            return this.keywordSearchDocuments(query, userId, sessionId, limit, collectionIds);
+            return this.keywordSearchDocuments(query, userId, sessionId, limit, collectionIds, signal);
         }
         catch (error) {
+            if (signal?.aborted)
+                throw error;
             logger.error('Semantic search failed, falling back to keyword search:', error);
-            return this.keywordSearchDocuments(query, userId, sessionId, limit, collectionIds);
+            return this.keywordSearchDocuments(query, userId, sessionId, limit, collectionIds, signal);
         }
     }
     /** Term-frequency scores for a set of chunks, best first. */
@@ -427,16 +1171,20 @@ class DocumentService {
         }
         return scored.sort((a, b) => b.score - a.score);
     }
-    keywordSearchDocuments(query, userId, sessionId, limit = 5, collectionIds) {
+    async keywordSearchDocuments(query, userId, sessionId, limit = 5, collectionIds, signal) {
         const candidates = [];
-        for (const document of storageService.getAllDocuments(userId)) {
-            const documentChunks = this.loadDocumentChunks(document.id);
+        throwIfChatGenerationCancelled(signal);
+        for (const document of await storageService.getAllDocuments(userId)) {
+            throwIfChatGenerationCancelled(signal);
+            const documentChunks = await this.loadDocumentChunks(document.id);
+            throwIfChatGenerationCancelled(signal);
             if (!this.documentInScope(document, sessionId, collectionIds))
                 continue;
             for (const chunk of documentChunks) {
                 candidates.push({ chunk, document });
             }
         }
+        throwIfChatGenerationCancelled(signal);
         const results = this.scoreChunksByKeywords(query, candidates);
         return results.slice(0, limit).map(result => ({
             ...result.chunk,
@@ -452,12 +1200,10 @@ class DocumentService {
         });
     }
     // Restore a document from import (used during data import)
-    restoreDocument(document, userId) {
+    async restoreDocument(document, userId) {
         try {
-            // Add to memory
-            this.documents.set(document.id, document);
             // Save to storage
-            storageService.saveDocument(document, userId);
+            await storageService.saveDocument(document, userId);
             // If there are any chunks with this document, they'll be handled separately
             logger.debug(`Restored document: ${document.filename} (${document.id})`);
         }
@@ -466,13 +1212,12 @@ class DocumentService {
             throw new Error(`Failed to restore document: ${error instanceof Error ? error.message : 'Unknown error'}`);
         }
     }
-    loadDocumentChunks(documentId) {
-        const cached = this.chunks.get(documentId);
-        if (cached)
-            return cached;
-        const chunks = storageService.getDocumentChunks(documentId);
-        this.chunks.set(documentId, chunks);
-        return chunks;
+    async loadDocumentChunks(documentId) {
+        // Relational storage is authoritative. In team mode another replica's
+        // durable worker can complete or replace chunks after this process first
+        // observes a queued document; caching [] (or an older revision) forever
+        // makes that completion invisible and can drive a stale vector backfill.
+        return storageService.getDocumentChunks(documentId);
     }
 }
 export default new DocumentService();