@lemoncat7/dsh-knowledge 1.1.5 → 2.0.0

package/lib/local-provider.js

@@ -1,11 +1,15 @@
 import { dirname, join } from 'node:path';
-import { createHash, randomBytes } from 'node:crypto';
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
 import { mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { DatabaseSync } from 'node:sqlite';
 import { contentHash, DEFAULT_KNOWLEDGE_BASE_ID, newId, normalizeDraft, normalizeKnowledgeBaseDraft, normalizeKnowledgeMountDraft, normalizeKnowledgeSettings, nowIso, } from './domain.js';
 import { renderKnowledgeMarkdown } from './documents/markdown.js';
 import { knowledgeDocumentPath } from './documents/path.js';
 import { KnowledgeDocumentStore } from './documents/store.js';
+import { enqueueDocumentProjection } from './documents/projection-queue.js';
+import { mergeKnowledgeBodies } from './knowledge-merge.js';
+import { NoteStore } from './notes/store.js';
 const ENTRY_COLUMNS = `
   id, knowledge_base_id, title, body, type, tags_json, scope_kind, scope_id, confidence,
   status, document_state, finalized_at, finalization_note, version, source_json, created_at, updated_at
@@ -17,8 +21,10 @@ const JOINED_ENTRY_COLUMNS = `
   e.finalized_at AS finalized_at, e.finalization_note AS finalization_note, e.version AS version,
   e.source_json AS source_json, e.created_at AS created_at, e.updated_at AS updated_at
 `;
+const EXTRACTION_LEASE_MS = 15 * 60 * 1000;
 export class LocalKnowledgeProvider {
     mode = 'local';
+    notes;
     db;
     documentStore;
     documentsReady;
@@ -26,15 +32,19 @@ export class LocalKnowledgeProvider {
     constructor(path) {
         if (path !== ':memory:')
             mkdirSync(dirname(path), { recursive: true });
+        const inMemory = path === ':memory:';
+        this.notes = new NoteStore(inMemory
+            ? join(tmpdir(), `dsh-knowledge-notes-${randomUUID()}`)
+            : join(dirname(path), 'notes'), inMemory);
         this.documentStore = new KnowledgeDocumentStore(join(dirname(path), 'documents'));
         this.db = new DatabaseSync(path);
         this.db.exec('PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON; PRAGMA busy_timeout = 5000;');
         this.migrate();
-        this.documentsReady = this.syncAllDocuments();
+        this.documentsReady = this.enqueueDocumentSync(() => this.syncAllDocuments());
     }
     migrate() {
         let version = Number(this.db.prepare('PRAGMA user_version').get().user_version ?? 0);
-        if (version > 9)
+        if (version > 10)
             throw new Error(`knowledge database schema ${version} is newer than this plugin supports`);
         if (version === 0)
             this.db.exec(`
@@ -243,11 +253,52 @@ export class LocalKnowledgeProvider {
       PRAGMA user_version = 9;
       COMMIT;
     `);
+        if (version <= 8)
+            version = 9;
+        if (version === 9) {
+            this.db.exec('BEGIN IMMEDIATE');
+            try {
+                this.db.exec(`
+          CREATE TABLE knowledge_note_references (
+            knowledge_id TEXT NOT NULL REFERENCES knowledge_entries(id) ON DELETE CASCADE,
+            note_id TEXT NOT NULL,
+            source TEXT NOT NULL CHECK(source IN ('user','agent','legacy')),
+            source_session_id TEXT,
+            created_at TEXT NOT NULL,
+            PRIMARY KEY(knowledge_id, note_id)
+          );
+          CREATE INDEX knowledge_note_references_note ON knowledge_note_references(note_id, created_at DESC);
+        `);
+                this.backfillLegacyNoteReferences();
+                this.db.exec('PRAGMA user_version = 10; COMMIT');
+            }
+            catch (error) {
+                this.db.exec('ROLLBACK');
+                throw error;
+            }
+        }
         // Alpha v2 used a migration note as the default base's routing description.
         // Clear only that exact placeholder so existing user-authored descriptions stay untouched.
         this.db.prepare("UPDATE knowledge_bases SET description='' WHERE id=? AND description=?")
             .run(DEFAULT_KNOWLEDGE_BASE_ID, '由 0.2 版本迁移的知识。');
     }
+    backfillLegacyNoteReferences() {
+        const insert = this.db.prepare(`
+      INSERT OR IGNORE INTO knowledge_note_references(knowledge_id,note_id,source,source_session_id,created_at)
+      VALUES(?,?,'legacy',NULL,?)
+    `);
+        const timestamp = nowIso();
+        const rows = this.db.prepare("SELECT id,body FROM knowledge_entries WHERE body LIKE '%note://note_%'").all();
+        for (const row of rows) {
+            const noteIds = String(row.body).match(/note:\/\/(note_[a-f0-9]{32})/giu) ?? [];
+            for (const reference of new Set(noteIds)) {
+                const noteId = reference.slice('note://'.length).toLocaleLowerCase();
+                const note = this.notes.get(noteId);
+                if (note !== undefined && note.kind !== 'folder')
+                    insert.run(String(row.id), note.id, timestamp);
+            }
+        }
+    }
     assertOpen() {
         if (this.closed)
             throw new Error('knowledge provider is closed');
@@ -301,7 +352,7 @@ export class LocalKnowledgeProvider {
         id,name,description,default_tags_json,extraction_instructions,writeback_policy,writeback_provider,writeback_model,status,created_at,updated_at
       ) VALUES(?,?,?,?,?,?,?,?,'active',?,?)
     `).run(base.id, base.name, base.description, JSON.stringify(base.defaultTags), base.extractionInstructions, base.writebackPolicy, base.writebackProvider ?? null, base.writebackModel ?? null, timestamp, timestamp);
-        await this.syncKnowledgeDocuments(base.id);
+        await this.syncKnowledgeDocumentsQueued(base.id);
         return base;
     }
     async updateKnowledgeBase(id, input) {
@@ -311,13 +362,19 @@ export class LocalKnowledgeProvider {
         if (current === undefined)
             throw notFound('knowledge base', id);
         const draft = normalizeKnowledgeBaseDraft(input);
-        const updated = { ...current, ...draft, updatedAt: nowIso() };
+        const updated = {
+            id: current.id,
+            status: current.status,
+            createdAt: current.createdAt,
+            ...draft,
+            updatedAt: nowIso(),
+        };
         this.db.prepare(`
       UPDATE knowledge_bases SET
         name=?,description=?,default_tags_json=?,extraction_instructions=?,writeback_policy=?,writeback_provider=?,writeback_model=?,updated_at=?
       WHERE id=?
     `).run(updated.name, updated.description, JSON.stringify(updated.defaultTags), updated.extractionInstructions, updated.writebackPolicy, updated.writebackProvider ?? null, updated.writebackModel ?? null, updated.updatedAt, id);
-        await this.syncKnowledgeDocuments(id);
+        await this.syncKnowledgeDocumentsQueued(id);
         return updated;
     }
     async patchKnowledgeBase(id, patch) {
@@ -347,8 +404,10 @@ export class LocalKnowledgeProvider {
         if (current.status === 'archived')
             return current;
         const updated = { ...current, status: 'archived', updatedAt: nowIso() };
-        this.db.prepare("UPDATE knowledge_bases SET status='archived',updated_at=? WHERE id=?").run(updated.updatedAt, id);
-        this.db.prepare('UPDATE knowledge_mounts SET enabled=0,updated_at=? WHERE knowledge_base_id=?').run(updated.updatedAt, id);
+        this.transaction(() => {
+            this.db.prepare("UPDATE knowledge_bases SET status='archived',updated_at=? WHERE id=?").run(updated.updatedAt, id);
+            this.db.prepare('UPDATE knowledge_mounts SET enabled=0,updated_at=? WHERE knowledge_base_id=?').run(updated.updatedAt, id);
+        });
         return updated;
     }
     async restoreKnowledgeBase(id) {
@@ -368,28 +427,37 @@ export class LocalKnowledgeProvider {
         const base = await this.getKnowledgeBase(id);
         if (id === DEFAULT_KNOWLEDGE_BASE_ID)
             throw conflict('the default knowledge base cannot be deleted');
-        this.transaction(() => {
-            const row = this.db.prepare('SELECT status FROM knowledge_bases WHERE id=?').get(id);
-            if (row === undefined)
-                throw notFound('knowledge base', id);
-            if (row.status !== 'archived')
-                throw conflict('knowledge base must be archived before deletion');
-            this.db.prepare(`
-        DELETE FROM knowledge_candidates
-        WHERE json_extract(draft_json, '$.knowledgeBaseId')=?
-           OR target_id IN (SELECT id FROM knowledge_entries WHERE knowledge_base_id=?)
-      `).run(id, id);
-            this.db.prepare(`
-        DELETE FROM knowledge_fts
-        WHERE knowledge_id IN (SELECT id FROM knowledge_entries WHERE knowledge_base_id=?)
-      `).run(id);
-            this.db.prepare('DELETE FROM knowledge_entries WHERE knowledge_base_id=?').run(id);
-            this.db.prepare('DELETE FROM knowledge_mounts WHERE knowledge_base_id=?').run(id);
-            this.db.prepare('DELETE FROM knowledge_documents WHERE knowledge_base_id=?').run(id);
-            this.db.prepare('DELETE FROM knowledge_bases WHERE id=?').run(id);
-        });
-        if (base !== undefined)
-            await this.documentStore.deleteBase(this.documentStore.baseDirectory(base));
+        if (base === undefined)
+            throw notFound('knowledge base', id);
+        if (base.status !== 'archived')
+            throw conflict('knowledge base must be archived before deletion');
+        await this.enqueueDocumentSync(() => this.documentStore.deleteBase(this.documentStore.baseDirectory(base)));
+        try {
+            this.transaction(() => {
+                const row = this.db.prepare('SELECT status FROM knowledge_bases WHERE id=?').get(id);
+                if (row === undefined)
+                    throw notFound('knowledge base', id);
+                if (row.status !== 'archived')
+                    throw conflict('knowledge base must be archived before deletion');
+                this.db.prepare(`
+          DELETE FROM knowledge_candidates
+          WHERE json_extract(draft_json, '$.knowledgeBaseId')=?
+             OR target_id IN (SELECT id FROM knowledge_entries WHERE knowledge_base_id=?)
+        `).run(id, id);
+                this.db.prepare(`
+          DELETE FROM knowledge_fts
+          WHERE knowledge_id IN (SELECT id FROM knowledge_entries WHERE knowledge_base_id=?)
+        `).run(id);
+                this.db.prepare('DELETE FROM knowledge_entries WHERE knowledge_base_id=?').run(id);
+                this.db.prepare('DELETE FROM knowledge_mounts WHERE knowledge_base_id=?').run(id);
+                this.db.prepare('DELETE FROM knowledge_documents WHERE knowledge_base_id=?').run(id);
+                this.db.prepare('DELETE FROM knowledge_bases WHERE id=?').run(id);
+            });
+        }
+        catch (error) {
+            await this.syncKnowledgeDocumentsQueued(id).catch(() => { });
+            throw error;
+        }
     }
     async listDocuments(knowledgeBaseId, query) {
         this.assertOpen();
@@ -409,6 +477,68 @@ export class LocalKnowledgeProvider {
         const sql = `SELECT * FROM knowledge_documents${where.length === 0 ? '' : ` WHERE ${where.join(' AND ')}`} ORDER BY knowledge_base_id, CASE WHEN rel_path='README.md' THEN 0 ELSE 1 END, rel_path`;
         return this.db.prepare(sql).all(...args).map(rowToDocument);
     }
+    async listDocumentIndex(request) {
+        this.assertOpen();
+        await this.documentsReady;
+        const limit = Math.max(1, Math.min(request.limit, 100));
+        const where = [];
+        const args = [];
+        const knowledgeBaseIds = request.knowledgeBaseIds === undefined
+            ? undefined
+            : [...new Set(request.knowledgeBaseIds.map(id => id.trim()).filter(Boolean))];
+        if (knowledgeBaseIds !== undefined && knowledgeBaseIds.length === 0)
+            return { items: [], total: 0 };
+        if (knowledgeBaseIds !== undefined) {
+            where.push(`knowledge_base_id IN (${knowledgeBaseIds.map(() => '?').join(',')})`);
+            args.push(...knowledgeBaseIds);
+        }
+        if (request.activeKnowledgeBasesOnly) {
+            where.push("knowledge_base_id IN (SELECT id FROM knowledge_bases WHERE status='active')");
+        }
+        const query = request.query?.trim();
+        if (query) {
+            const like = `%${escapeSqlLike(query)}%`;
+            where.push(`(title LIKE ? ESCAPE '\\' OR rel_path LIKE ? ESCAPE '\\' OR content LIKE ? ESCAPE '\\')`);
+            args.push(like, like, like);
+        }
+        const sourceWhere = where.length === 0 ? '' : ` WHERE ${where.join(' AND ')}`;
+        const cursorWhere = [];
+        const cursorArgs = [];
+        if (request.cursor !== undefined) {
+            const cursor = decodeDocumentCursor(request.cursor);
+            cursorWhere.push(`(
+        knowledge_base_id > ? OR
+        (knowledge_base_id = ? AND sort_rank > ?) OR
+        (knowledge_base_id = ? AND sort_rank = ? AND rel_path > ?) OR
+        (knowledge_base_id = ? AND sort_rank = ? AND rel_path = ? AND id > ?)
+      )`);
+            cursorArgs.push(cursor.knowledgeBaseId, cursor.knowledgeBaseId, cursor.sortRank, cursor.knowledgeBaseId, cursor.sortRank, cursor.relPath, cursor.knowledgeBaseId, cursor.sortRank, cursor.relPath, cursor.id);
+        }
+        const rows = this.db.prepare(`
+      WITH document_index AS (
+        SELECT
+          id, knowledge_base_id, rel_path, title, entry_count, content_hash,
+          document_state, finalized_at, finalization_note, created_at, updated_at,
+          CASE WHEN rel_path='README.md' THEN 0 ELSE 1 END AS sort_rank
+        FROM knowledge_documents${sourceWhere}
+      )
+      SELECT * FROM document_index
+      ${cursorWhere.length === 0 ? '' : `WHERE ${cursorWhere.join(' AND ')}`}
+      ORDER BY knowledge_base_id, sort_rank, rel_path, id
+      LIMIT ?
+    `).all(...args, ...cursorArgs, limit + 1);
+        const pageRows = rows.slice(0, limit);
+        const items = pageRows.map(rowToDocumentSummary);
+        const last = pageRows.at(-1);
+        const total = Number(this.db.prepare(`SELECT COUNT(*) AS total FROM knowledge_documents${sourceWhere}`).get(...args).total ?? 0);
+        return {
+            items,
+            total,
+            ...rows.length <= limit || last === undefined ? {} : {
+                nextCursor: encodeDocumentCursor(String(last.knowledge_base_id), Number(last.sort_rank), String(last.rel_path), String(last.id)),
+            },
+        };
+    }
     async getDocument(id) {
         this.assertOpen();
         await this.documentsReady;
@@ -615,7 +745,7 @@ export class LocalKnowledgeProvider {
         return rows.map(row => {
             const entry = rowToEntry(row);
             return { entry, score: relevanceScore(entry, text) };
-        });
+        }).sort((left, right) => right.score - left.score || right.entry.updatedAt.localeCompare(left.entry.updatedAt));
     }
     searchByTerms(text, scopeSql, scopeArgs, filterSql, filterArgs, limit) {
         const terms = fallbackTerms(text);
@@ -683,7 +813,7 @@ export class LocalKnowledgeProvider {
         this.assertOpen();
         await this.documentsReady;
         const entry = this.transaction(() => this.insertEntry(draft));
-        await this.syncKnowledgeDocuments(entry.knowledgeBaseId);
+        await this.syncKnowledgeDocumentsQueued(entry.knowledgeBaseId);
         return entry;
     }
     insertEntry(input) {
@@ -713,8 +843,8 @@ export class LocalKnowledgeProvider {
         const current = await this.get(id);
         const entry = this.transaction(() => this.updateEntry(id, draft, 'update'));
         if (current !== undefined && current.knowledgeBaseId !== entry.knowledgeBaseId)
-            await this.syncKnowledgeDocuments(current.knowledgeBaseId);
-        await this.syncKnowledgeDocuments(entry.knowledgeBaseId);
+            await this.syncKnowledgeDocumentsQueued(current.knowledgeBaseId);
+        await this.syncKnowledgeDocumentsQueued(entry.knowledgeBaseId);
         return entry;
     }
     async finalize(id, state, note) {
@@ -750,7 +880,7 @@ export class LocalKnowledgeProvider {
             this.upsertFts(updated);
             return updated;
         });
-        await this.syncKnowledgeDocuments(entry.knowledgeBaseId);
+        await this.syncKnowledgeDocumentsQueued(entry.knowledgeBaseId);
         return entry;
     }
     async reopen(id) {
@@ -782,7 +912,7 @@ export class LocalKnowledgeProvider {
             this.upsertFts(updated);
             return updated;
         });
-        await this.syncKnowledgeDocuments(entry.knowledgeBaseId);
+        await this.syncKnowledgeDocumentsQueued(entry.knowledgeBaseId);
         return entry;
     }
     updateEntry(id, input, changeKind) {
@@ -790,6 +920,9 @@ export class LocalKnowledgeProvider {
         if (currentRow === undefined)
             throw notFound('knowledge entry', id);
         const current = rowToEntry(currentRow);
+        if (current.status !== 'active' && changeKind !== 'restore') {
+            throw conflict(`knowledge document "${current.title}" is archived and cannot be edited`);
+        }
         if (current.documentState !== 'open')
             throw finalizedConflict(current);
         const draft = normalizeDraft(input);
@@ -832,7 +965,7 @@ export class LocalKnowledgeProvider {
             this.db.prepare('DELETE FROM knowledge_fts WHERE knowledge_id = ?').run(id);
             return updated;
         });
-        await this.syncKnowledgeDocuments(entry.knowledgeBaseId);
+        await this.syncKnowledgeDocumentsQueued(entry.knowledgeBaseId);
         return entry;
     }
     async delete(id) {
@@ -846,7 +979,153 @@ export class LocalKnowledgeProvider {
                 throw notFound('knowledge entry', id);
         });
         if (current !== undefined)
-            await this.syncKnowledgeDocuments(current.knowledgeBaseId);
+            await this.syncKnowledgeDocumentsQueued(current.knowledgeBaseId);
+    }
+    async listNotes(request = {}) {
+        this.assertOpen();
+        return this.notes.list(request);
+    }
+    async getNote(id) {
+        this.assertOpen();
+        return this.notes.get(id);
+    }
+    async readNote(id) {
+        this.assertOpen();
+        return this.notes.read(id);
+    }
+    async createNoteFolder(name, parentId = null) {
+        this.assertOpen();
+        return this.notes.createFolder(name, parentId);
+    }
+    async createNoteDocument(name, parentId = null, content = '') {
+        this.assertOpen();
+        return this.notes.createDocument(name, parentId, content);
+    }
+    async updateNoteContent(id, content) {
+        this.assertOpen();
+        return this.notes.updateContent(id, content);
+    }
+    async renameNote(id, name) {
+        this.assertOpen();
+        return this.notes.rename(id, name);
+    }
+    async moveNote(id, parentId) {
+        this.assertOpen();
+        return this.notes.move(id, parentId);
+    }
+    async deleteNote(id) {
+        this.assertOpen();
+        const noteIds = this.notes.subtree(id).filter(node => node.kind !== 'folder').map(node => node.id);
+        const references = this.noteReferencesForNotes(noteIds);
+        if (references.length > 0)
+            throw conflict(`note content is referenced by ${references.length} knowledge document(s)`);
+        await this.notes.delete(id);
+        this.deleteNoteReferences(noteIds);
+    }
+    async searchNotes(query, limit) {
+        this.assertOpen();
+        const value = query.trim();
+        if (value.length === 0)
+            return [];
+        const boundedLimit = Math.max(1, Math.min(Math.trunc(limit), 100));
+        return this.notes.list({ query: value, limit: Math.min(500, boundedLimit * 3) })
+            .filter(node => node.kind !== 'folder')
+            .slice(0, boundedLimit);
+    }
+    async listKnowledgeNoteReferences(knowledgeId) {
+        this.assertOpen();
+        const entry = await this.get(knowledgeId);
+        if (entry === undefined)
+            throw notFound('knowledge entry', knowledgeId);
+        const rows = this.db.prepare(`
+      SELECT knowledge_id,note_id,source,source_session_id,created_at
+      FROM knowledge_note_references
+      WHERE knowledge_id=?
+      ORDER BY created_at,note_id
+    `).all(knowledgeId);
+        return rows.flatMap(row => {
+            const note = this.notes.get(String(row.note_id));
+            if (note === undefined || note.kind === 'folder')
+                return [];
+            return [{
+                    knowledgeId: entry.id,
+                    knowledgeBaseId: entry.knowledgeBaseId,
+                    documentTitle: entry.title,
+                    note,
+                    source: String(row.source),
+                    ...row.source_session_id == null ? {} : { sourceSessionId: String(row.source_session_id) },
+                    createdAt: String(row.created_at),
+                }];
+        });
+    }
+    async addKnowledgeNoteReference(knowledgeId, noteId, source, sourceSessionId) {
+        this.assertOpen();
+        const entry = await this.get(knowledgeId);
+        if (entry === undefined)
+            throw notFound('knowledge entry', knowledgeId);
+        if (entry.status !== 'active')
+            throw conflict('archived knowledge documents cannot change note references');
+        if (entry.documentState !== 'open')
+            throw finalizedConflict(entry);
+        const note = this.notes.get(noteId);
+        if (note === undefined)
+            throw notFound('note node', noteId);
+        if (note.kind === 'folder')
+            throw inputError('knowledge documents can reference note documents or files, not folders');
+        if (source !== 'user' && source !== 'agent' && source !== 'legacy')
+            throw inputError('invalid knowledge note reference source');
+        const sessionId = sourceSessionId?.trim() || undefined;
+        if (sessionId !== undefined && sessionId.length > 200)
+            throw inputError('reference source session id is too long');
+        const createdAt = nowIso();
+        this.db.prepare(`
+      INSERT OR IGNORE INTO knowledge_note_references(knowledge_id,note_id,source,source_session_id,created_at)
+      VALUES(?,?,?,?,?)
+    `).run(entry.id, note.id, source, sessionId ?? null, createdAt);
+        const reference = (await this.listKnowledgeNoteReferences(entry.id)).find(item => item.note.id === note.id);
+        if (reference === undefined)
+            throw new Error('knowledge note reference was not persisted');
+        return reference;
+    }
+    async deleteKnowledgeNoteReference(knowledgeId, noteId) {
+        this.assertOpen();
+        const entry = await this.get(knowledgeId);
+        if (entry === undefined)
+            throw notFound('knowledge entry', knowledgeId);
+        if (entry.status !== 'active')
+            throw conflict('archived knowledge documents cannot change note references');
+        if (entry.documentState !== 'open')
+            throw finalizedConflict(entry);
+        const result = this.db.prepare('DELETE FROM knowledge_note_references WHERE knowledge_id=? AND note_id=?').run(knowledgeId, noteId);
+        if (result.changes === 0)
+            throw notFound('knowledge note reference', `${knowledgeId}/${noteId}`);
+    }
+    noteReferencesForNotes(noteIds) {
+        this.assertOpen();
+        const ids = [...new Set(noteIds)];
+        if (ids.length === 0)
+            return [];
+        const placeholders = ids.map(() => '?').join(',');
+        return this.db.prepare(`
+      SELECT r.note_id,e.knowledge_base_id,e.id AS document_id,e.title AS document_title
+      FROM knowledge_note_references r
+      JOIN knowledge_entries e ON e.id=r.knowledge_id
+      WHERE r.note_id IN (${placeholders})
+      ORDER BY e.updated_at DESC,e.id
+    `).all(...ids).map(row => ({
+            noteId: String(row.note_id),
+            knowledgeBaseId: String(row.knowledge_base_id),
+            documentId: String(row.document_id),
+            documentTitle: String(row.document_title),
+        }));
+    }
+    deleteNoteReferences(noteIds) {
+        this.assertOpen();
+        const ids = [...new Set(noteIds)];
+        if (ids.length === 0)
+            return;
+        const placeholders = ids.map(() => '?').join(',');
+        this.db.prepare(`DELETE FROM knowledge_note_references WHERE note_id IN (${placeholders})`).run(...ids);
     }
     async propose(input, sourceKey) {
         this.assertOpen();
@@ -894,7 +1173,7 @@ export class LocalKnowledgeProvider {
             };
         });
         if (touchedBaseId !== undefined)
-            await this.syncKnowledgeDocuments(touchedBaseId);
+            await this.syncKnowledgeDocumentsQueued(touchedBaseId);
         return result;
     }
     insertCandidate(proposal, sourceKey) {
@@ -1009,10 +1288,7 @@ export class LocalKnowledgeProvider {
                     }
                     if (candidate.targetId === undefined)
                         throw new Error('candidate target is missing');
-                    const targetRow = this.db.prepare(`SELECT ${ENTRY_COLUMNS} FROM knowledge_entries WHERE id = ?`).get(candidate.targetId);
-                    if (targetRow === undefined)
-                        throw notFound('candidate target', candidate.targetId);
-                    const target = rowToEntry(targetRow);
+                    const target = this.activeEntry(candidate.targetId);
                     if (draft.knowledgeBaseId !== target.knowledgeBaseId) {
                         throw conflict('candidate approval cannot move a document between knowledge bases');
                     }
@@ -1058,30 +1334,49 @@ export class LocalKnowledgeProvider {
             return { ...candidate, status, reviewedAt, ...note === undefined ? {} : { reviewNote: note } };
         });
         if (decision.decision === 'approve')
-            await this.syncKnowledgeDocuments(reviewed.draft.knowledgeBaseId);
+            await this.syncKnowledgeDocumentsQueued(reviewed.draft.knowledgeBaseId);
         return reviewed;
     }
     async claimExtraction(sourceKey) {
         this.assertOpen();
+        const claimedAt = nowIso();
+        const staleBefore = new Date(Date.now() - EXTRACTION_LEASE_MS).toISOString();
         const result = this.db.prepare(`
       INSERT INTO extraction_jobs(source_key,status,attempts,candidate_count,updated_at)
       VALUES(?,'running',1,0,?)
       ON CONFLICT(source_key) DO UPDATE SET
         status='running', attempts=extraction_jobs.attempts+1, candidate_count=0,
         last_error=NULL, updated_at=excluded.updated_at
-      WHERE extraction_jobs.status='failed' AND extraction_jobs.attempts < 3
-    `).run(sourceKey, nowIso());
+      WHERE extraction_jobs.attempts < 3 AND (
+        extraction_jobs.status='failed'
+        OR (extraction_jobs.status='running' AND extraction_jobs.updated_at < ?)
+      )
+    `).run(sourceKey, claimedAt, staleBefore);
         return result.changes === 1;
     }
     async completeExtraction(sourceKey, candidateCount) {
         this.assertOpen();
-        this.db.prepare(`UPDATE extraction_jobs SET status='completed', candidate_count=?, last_error=NULL, updated_at=? WHERE source_key=?`)
-            .run(candidateCount, nowIso(), sourceKey);
+        const result = this.db.prepare(`
+      UPDATE extraction_jobs SET status='completed', candidate_count=?, last_error=NULL, updated_at=?
+      WHERE source_key=? AND status='running'
+    `).run(candidateCount, nowIso(), sourceKey);
+        if (result.changes === 0) {
+            const current = await this.extractionJob(sourceKey);
+            if (current?.status !== 'completed')
+                throw conflict(`extraction job "${sourceKey}" is not running`);
+        }
     }
     async failExtraction(sourceKey, error) {
         this.assertOpen();
-        this.db.prepare(`UPDATE extraction_jobs SET status='failed', last_error=?, updated_at=? WHERE source_key=?`)
-            .run(error.slice(0, 4000), nowIso(), sourceKey);
+        const result = this.db.prepare(`
+      UPDATE extraction_jobs SET status='failed', last_error=?, updated_at=?
+      WHERE source_key=? AND status='running'
+    `).run(error.slice(0, 4000), nowIso(), sourceKey);
+        if (result.changes === 0) {
+            const current = await this.extractionJob(sourceKey);
+            if (current?.status !== 'failed')
+                throw conflict(`extraction job "${sourceKey}" is not running`);
+        }
     }
     async resetExtraction(sourceKey) {
         this.assertOpen();
@@ -1111,7 +1406,12 @@ export class LocalKnowledgeProvider {
             .get(tokenHash(token));
         if (row === undefined)
             return undefined;
-        const usedAt = nowIso();
+        const previous = row.last_used_at == null ? undefined : String(row.last_used_at);
+        const now = Date.now();
+        const shouldRefresh = previous === undefined || !Number.isFinite(Date.parse(previous)) || now - Date.parse(previous) >= 60_000;
+        if (!shouldRefresh)
+            return rowToToken(row);
+        const usedAt = new Date(now).toISOString();
         this.db.prepare('UPDATE api_tokens SET last_used_at = ? WHERE id = ?').run(usedAt, String(row.id));
         return rowToToken({ ...row, last_used_at: usedAt });
     }
@@ -1156,6 +1456,7 @@ export class LocalKnowledgeProvider {
         await this.documentsReady;
         this.closed = true;
         this.db.close();
+        await this.notes.close();
     }
     writeVersion(entry, changeKind) {
         const snapshot = {
@@ -1188,6 +1489,12 @@ export class LocalKnowledgeProvider {
         for (const base of bases)
             await this.syncKnowledgeDocuments(String(base.id));
     }
+    enqueueDocumentSync(operation) {
+        return enqueueDocumentProjection(this.documentStore.root, operation);
+    }
+    syncKnowledgeDocumentsQueued(knowledgeBaseId) {
+        return this.enqueueDocumentSync(() => this.syncKnowledgeDocuments(knowledgeBaseId));
+    }
     async syncKnowledgeDocuments(knowledgeBaseId) {
         const baseRow = this.db.prepare('SELECT * FROM knowledge_bases WHERE id=?').get(knowledgeBaseId);
         if (baseRow === undefined)
@@ -1303,6 +1610,21 @@ function rowToDocument(row) {
         updatedAt: String(row.updated_at),
     };
 }
+function rowToDocumentSummary(row) {
+    return {
+        id: String(row.id),
+        knowledgeBaseId: String(row.knowledge_base_id),
+        relPath: String(row.rel_path),
+        title: String(row.title),
+        entryCount: Number(row.entry_count),
+        contentHash: String(row.content_hash),
+        documentState: row.document_state == null ? 'open' : String(row.document_state),
+        ...row.finalized_at == null ? {} : { finalizedAt: String(row.finalized_at) },
+        ...row.finalization_note == null ? {} : { finalizationNote: String(row.finalization_note) },
+        createdAt: String(row.created_at),
+        updatedAt: String(row.updated_at),
+    };
+}
 function rowToVersion(row) {
     const snapshot = JSON.parse(String(row.snapshot_json));
     if (snapshot.knowledgeBaseId === undefined)
@@ -1355,7 +1677,7 @@ function mergeKnowledgeDraft(current, incoming, preferIncomingTitle) {
     return normalizeDraft({
         knowledgeBaseId: current.knowledgeBaseId,
         title: preferIncomingTitle ? incoming.title : current.title,
-        body: mergeBodies(current.body, incoming.body),
+        body: mergeKnowledgeBodies(current.body, incoming.body),
         type: current.type,
         tags: [...current.tags, ...incoming.tags],
         scope: current.scope,
@@ -1365,18 +1687,7 @@ function mergeKnowledgeDraft(current, incoming, preferIncomingTitle) {
             : { source: incoming.source },
     });
 }
-function mergeBodies(current, incoming) {
-    const currentKey = normalizedBody(current);
-    const incomingKey = normalizedBody(incoming);
-    if (currentKey === incomingKey || currentKey.includes(incomingKey))
-        return current.trim();
-    if (incomingKey.includes(currentKey))
-        return incoming.trim();
-    return `${current.trim()}\n\n${incoming.trim()}`;
-}
 function potentiallyConflicts(current, incoming) {
-    if (current.type !== incoming.type)
-        return true;
     const currentBody = normalizedBody(current.body);
     const incomingBody = normalizedBody(incoming.body);
     if (currentBody === incomingBody || currentBody.includes(incomingBody) || incomingBody.includes(currentBody))
@@ -1574,12 +1885,40 @@ function decodeCursor(cursor) {
         throw Object.assign(new Error('invalid pagination cursor'), { code: 'BAD_REQUEST' });
     }
 }
+function encodeDocumentCursor(knowledgeBaseId, sortRank, relPath, id) {
+    return Buffer.from(JSON.stringify({ knowledgeBaseId, sortRank, relPath, id })).toString('base64url');
+}
+function decodeDocumentCursor(cursor) {
+    try {
+        const value = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+        if (typeof value.knowledgeBaseId !== 'string'
+            || (value.sortRank !== 0 && value.sortRank !== 1)
+            || typeof value.relPath !== 'string'
+            || typeof value.id !== 'string')
+            throw new Error();
+        return {
+            knowledgeBaseId: value.knowledgeBaseId,
+            sortRank: value.sortRank,
+            relPath: value.relPath,
+            id: value.id,
+        };
+    }
+    catch {
+        throw Object.assign(new Error('invalid document pagination cursor'), { code: 'BAD_REQUEST', status: 400 });
+    }
+}
+function escapeSqlLike(value) {
+    return value.replaceAll('\\', '\\\\').replaceAll('%', '\\%').replaceAll('_', '\\_');
+}
 function notFound(kind, id) {
     return Object.assign(new Error(`${kind} "${id}" was not found`), { code: 'NOT_FOUND' });
 }
 function conflict(message) {
     return Object.assign(new Error(message), { code: 'CONFLICT' });
 }
+function inputError(message) {
+    return Object.assign(new Error(message), { code: 'BAD_REQUEST', status: 400 });
+}
 function finalizedConflict(entry) {
     const label = entry.documentState === 'resolved' ? 'resolved' : 'collection complete';
     return conflict(`knowledge document "${entry.title}" (${entry.id}) is finalized as ${label}; reopen it before making changes`);