@lemoncat7/dsh-knowledge 2.2.1 → 2.2.8

package/lib/local-provider.js

@@ -4,7 +4,7 @@ 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 { markdownHash, renderKnowledgeMarkdown } from './documents/markdown.js';
 import { knowledgeDocumentPath } from './documents/path.js';
 import { KnowledgeDocumentStore } from './documents/store.js';
 import { enqueueDocumentProjection } from './documents/projection-queue.js';
@@ -33,10 +33,11 @@ export class LocalKnowledgeProvider {
         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'));
+        const storageRoot = inMemory
+            ? join(tmpdir(), `dsh-knowledge-${randomUUID()}`)
+            : dirname(path);
+        this.notes = new NoteStore(inMemory ? storageRoot : join(storageRoot, 'notes'), inMemory);
+        this.documentStore = new KnowledgeDocumentStore(join(storageRoot, 'documents'));
         this.db = new DatabaseSync(path);
         this.db.exec('PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON; PRAGMA busy_timeout = 5000;');
         this.migrate();
@@ -44,7 +45,7 @@ export class LocalKnowledgeProvider {
     }
     migrate() {
         let version = Number(this.db.prepare('PRAGMA user_version').get().user_version ?? 0);
-        if (version > 11)
+        if (version > 13)
             throw new Error(`knowledge database schema ${version} is newer than this plugin supports`);
         if (version === 0)
             this.db.exec(`
@@ -296,6 +297,52 @@ export class LocalKnowledgeProvider {
                 throw error;
             }
         }
+        if (version <= 10)
+            version = 11;
+        if (version === 11)
+            this.db.exec(`
+      BEGIN IMMEDIATE;
+      CREATE INDEX IF NOT EXISTS knowledge_documents_index_order ON knowledge_documents(
+        knowledge_base_id,
+        (CASE WHEN rel_path='README.md' THEN 0 ELSE 1 END),
+        rel_path,
+        id
+      );
+      PRAGMA user_version = 12;
+      COMMIT;
+    `);
+        if (version <= 11)
+            version = 12;
+        if (version === 12) {
+            this.db.exec('BEGIN IMMEDIATE');
+            try {
+                const extractionTable = this.db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='extraction_jobs'").get();
+                if (extractionTable === undefined) {
+                    this.db.exec(`
+            CREATE TABLE extraction_jobs (
+              source_key TEXT PRIMARY KEY,
+              status TEXT NOT NULL CHECK(status IN ('running','completed','failed')),
+              attempts INTEGER NOT NULL,
+              candidate_count INTEGER NOT NULL DEFAULT 0,
+              last_error TEXT,
+              completion_json TEXT,
+              updated_at TEXT NOT NULL
+            )
+          `);
+                }
+                else {
+                    const extractionColumns = this.db.prepare('PRAGMA table_info(extraction_jobs)').all();
+                    if (!extractionColumns.some(column => String(column.name) === 'completion_json')) {
+                        this.db.exec('ALTER TABLE extraction_jobs ADD COLUMN completion_json TEXT');
+                    }
+                }
+                this.db.exec('PRAGMA user_version = 13; 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=?")
@@ -371,7 +418,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.syncKnowledgeDocumentsQueued(base.id);
+        await this.syncKnowledgeBaseManifestQueued(base.id);
         return base;
     }
     async updateKnowledgeBase(id, input) {
@@ -393,7 +440,7 @@ export class LocalKnowledgeProvider {
         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.syncKnowledgeDocumentsQueued(id);
+        await this.syncKnowledgeBaseManifestQueued(id);
         return updated;
     }
     async patchKnowledgeBase(id, patch) {
@@ -642,11 +689,12 @@ export class LocalKnowledgeProvider {
             resolved.set(mount.knowledgeBaseId, { mount, inheritedFrom: 'project' });
         for (const mount of session)
             resolved.set(mount.knowledgeBaseId, { mount });
+        const bases = new Map((await this.listKnowledgeBases()).map(base => [base.id, base]));
         const output = [];
         for (const { mount, inheritedFrom } of resolved.values()) {
             if (!mount.enabled)
                 continue;
-            const base = await this.getKnowledgeBase(mount.knowledgeBaseId);
+            const base = bases.get(mount.knowledgeBaseId);
             if (base === undefined || base.status !== 'active')
                 continue;
             output.push({ ...mount, base, ...inheritedFrom === undefined ? {} : { inheritedFrom } });
@@ -823,6 +871,24 @@ export class LocalKnowledgeProvider {
         const row = this.db.prepare(`SELECT ${ENTRY_COLUMNS} FROM knowledge_entries WHERE id = ?`).get(id);
         return row === undefined ? undefined : rowToEntry(row);
     }
+    /** Management-only bulk lookup used to avoid one HTTP/SQL round trip per review target. */
+    entriesByIds(ids) {
+        this.assertOpen();
+        const uniqueIds = [...new Set(ids.map(id => id.trim()).filter(Boolean))].slice(0, 100);
+        if (uniqueIds.length === 0)
+            return [];
+        const placeholders = uniqueIds.map(() => '?').join(',');
+        const rows = this.db.prepare(`SELECT ${ENTRY_COLUMNS} FROM knowledge_entries WHERE id IN (${placeholders})`)
+            .all(...uniqueIds);
+        const entries = new Map(rows.map(row => {
+            const entry = rowToEntry(row);
+            return [entry.id, entry];
+        }));
+        return uniqueIds.flatMap(id => {
+            const entry = entries.get(id);
+            return entry === undefined ? [] : [entry];
+        });
+    }
     async versions(id) {
         this.assertOpen();
         const rows = this.db.prepare('SELECT * FROM knowledge_versions WHERE knowledge_id = ? ORDER BY version DESC').all(id);
@@ -832,7 +898,7 @@ export class LocalKnowledgeProvider {
         this.assertOpen();
         await this.documentsReady;
         const entry = this.transaction(() => this.insertEntry(draft));
-        await this.syncKnowledgeDocumentsQueued(entry.knowledgeBaseId);
+        await this.syncKnowledgeEntryQueued(entry.id);
         return entry;
     }
     insertEntry(input) {
@@ -859,11 +925,8 @@ export class LocalKnowledgeProvider {
     async update(id, draft) {
         this.assertOpen();
         await this.documentsReady;
-        const current = await this.get(id);
         const entry = this.transaction(() => this.updateEntry(id, draft, 'update'));
-        if (current !== undefined && current.knowledgeBaseId !== entry.knowledgeBaseId)
-            await this.syncKnowledgeDocumentsQueued(current.knowledgeBaseId);
-        await this.syncKnowledgeDocumentsQueued(entry.knowledgeBaseId);
+        await this.syncKnowledgeEntryQueued(entry.id);
         return entry;
     }
     async finalize(id, state, note) {
@@ -899,7 +962,7 @@ export class LocalKnowledgeProvider {
             this.upsertFts(updated);
             return updated;
         });
-        await this.syncKnowledgeDocumentsQueued(entry.knowledgeBaseId);
+        await this.syncKnowledgeEntryQueued(entry.id);
         return entry;
     }
     async reopen(id) {
@@ -931,7 +994,42 @@ export class LocalKnowledgeProvider {
             this.upsertFts(updated);
             return updated;
         });
-        await this.syncKnowledgeDocumentsQueued(entry.knowledgeBaseId);
+        await this.syncKnowledgeEntryQueued(entry.id);
+        return entry;
+    }
+    async moveDocument(id, knowledgeBaseId) {
+        this.assertOpen();
+        await this.documentsReady;
+        let changed = false;
+        const entry = this.transaction(() => {
+            const row = this.db.prepare(`SELECT ${ENTRY_COLUMNS} FROM knowledge_entries WHERE id=?`).get(id);
+            if (row === undefined)
+                throw notFound('knowledge entry', id);
+            const current = rowToEntry(row);
+            if (current.status !== 'active')
+                throw conflict('only active knowledge documents can be moved');
+            if (current.knowledgeBaseId === knowledgeBaseId)
+                return current;
+            if (this.db.prepare("SELECT id FROM knowledge_bases WHERE id=? AND status='active'").get(knowledgeBaseId) === undefined) {
+                throw notFound('active knowledge base', knowledgeBaseId);
+            }
+            const updated = {
+                ...current,
+                knowledgeBaseId,
+                version: current.version + 1,
+                updatedAt: nowIso(),
+            };
+            this.db.prepare(`
+        UPDATE knowledge_entries
+        SET knowledge_base_id=?,version=?,updated_at=?
+        WHERE id=?
+      `).run(knowledgeBaseId, updated.version, updated.updatedAt, id);
+            this.writeVersion(updated, 'update');
+            changed = true;
+            return updated;
+        });
+        if (changed)
+            await this.syncKnowledgeEntryQueued(entry.id);
         return entry;
     }
     updateEntry(id, input, changeKind) {
@@ -984,7 +1082,7 @@ export class LocalKnowledgeProvider {
             this.db.prepare('DELETE FROM knowledge_fts WHERE knowledge_id = ?').run(id);
             return updated;
         });
-        await this.syncKnowledgeDocumentsQueued(entry.knowledgeBaseId);
+        await this.syncKnowledgeEntryQueued(entry.id);
         return entry;
     }
     async delete(id) {
@@ -998,7 +1096,7 @@ export class LocalKnowledgeProvider {
                 throw notFound('knowledge entry', id);
         });
         if (current !== undefined)
-            await this.syncKnowledgeDocumentsQueued(current.knowledgeBaseId);
+            await this.syncKnowledgeEntryQueued(current.id);
     }
     async listNotes(request = {}) {
         this.assertOpen();
@@ -1138,6 +1236,30 @@ export class LocalKnowledgeProvider {
             documentTitle: String(row.document_title),
         }));
     }
+    /** Compatibility path for manually embedded legacy note:// markers. */
+    legacyNoteReferencesForNotes(noteIds) {
+        this.assertOpen();
+        const requested = new Set(noteIds.map(id => id.toLocaleLowerCase()));
+        if (requested.size === 0)
+            return [];
+        const rows = this.db.prepare(`
+      SELECT knowledge_base_id,id,title,content
+      FROM knowledge_documents
+      WHERE content LIKE '%note://note_%'
+      ORDER BY updated_at DESC,id
+    `).all();
+        return rows.flatMap(row => {
+            const references = String(row.content).match(/note:\/\/(note_[a-f0-9]{32})/giu) ?? [];
+            return [...new Set(references.map(value => value.slice('note://'.length).toLocaleLowerCase()))]
+                .filter(noteId => requested.has(noteId))
+                .map(noteId => ({
+                noteId,
+                knowledgeBaseId: String(row.knowledge_base_id),
+                documentId: String(row.id),
+                documentTitle: String(row.title),
+            }));
+        });
+    }
     deleteNoteReferences(noteIds) {
         this.assertOpen();
         const ids = [...new Set(noteIds)];
@@ -1157,7 +1279,7 @@ export class LocalKnowledgeProvider {
     async writeDirect(input, sourceKey) {
         this.assertOpen();
         await this.documentsReady;
-        let touchedBaseId;
+        let touchedEntryId;
         const result = this.transaction(() => {
             const resolution = this.resolveDirectProposal(normalizeProposal(input));
             if (resolution.outcome === 'duplicate')
@@ -1177,7 +1299,7 @@ export class LocalKnowledgeProvider {
                 .run('approved', reviewedAt, resolution.outcome === 'merged'
                 ? 'Automatically merged by direct-write reconciliation.'
                 : 'Automatically approved by direct-write policy.', candidate.id);
-            touchedBaseId = entry.knowledgeBaseId;
+            touchedEntryId = entry.id;
             return {
                 outcome: resolution.outcome,
                 candidate: {
@@ -1191,8 +1313,8 @@ export class LocalKnowledgeProvider {
                 entry,
             };
         });
-        if (touchedBaseId !== undefined)
-            await this.syncKnowledgeDocumentsQueued(touchedBaseId);
+        if (touchedEntryId !== undefined)
+            await this.syncKnowledgeEntryQueued(touchedEntryId);
         return result;
     }
     insertCandidate(proposal, sourceKey) {
@@ -1303,6 +1425,7 @@ export class LocalKnowledgeProvider {
     async review(id, decision) {
         this.assertOpen();
         await this.documentsReady;
+        let touchedEntryId;
         const reviewed = this.transaction(() => {
             const row = this.db.prepare('SELECT * FROM knowledge_candidates WHERE id = ?').get(id);
             if (row === undefined)
@@ -1323,7 +1446,7 @@ export class LocalKnowledgeProvider {
                         throw conflict('candidate approval cannot move a document between knowledge bases');
                     }
                     assertExpectedReviewVersion(target, decision.expectedVersion);
-                    this.updateEntry(candidate.targetId, editedKnowledgeDraft(target, draft), 'update');
+                    touchedEntryId = this.updateEntry(candidate.targetId, editedKnowledgeDraft(target, draft), 'update').id;
                 }
                 else if (candidate.action === 'conflict') {
                     if (decision.resolution !== 'merge') {
@@ -1338,7 +1461,7 @@ export class LocalKnowledgeProvider {
                     const applied = applyCandidateToTarget(target, candidate, true);
                     if (!applied.ok)
                         throw conflict(`${applied.reason}; edit the current document to resolve this conflict`);
-                    this.updateEntry(candidate.targetId, applied.draft, 'update');
+                    touchedEntryId = this.updateEntry(candidate.targetId, applied.draft, 'update').id;
                 }
                 else {
                     const resolution = this.resolveDirectProposal({
@@ -1366,10 +1489,10 @@ export class LocalKnowledgeProvider {
                     if (resolution.outcome === 'finalized')
                         throw finalizedConflict(resolution.entry);
                     if (resolution.outcome !== 'duplicate') {
-                        if (resolution.proposal.action === 'create')
-                            this.insertEntry(resolution.proposal.draft);
-                        else
-                            this.updateEntry(resolution.proposal.targetId, resolution.proposal.draft, 'update');
+                        const entry = resolution.proposal.action === 'create'
+                            ? this.insertEntry(resolution.proposal.draft)
+                            : this.updateEntry(resolution.proposal.targetId, resolution.proposal.draft, 'update');
+                        touchedEntryId = entry.id;
                     }
                 }
             }
@@ -1380,8 +1503,8 @@ export class LocalKnowledgeProvider {
                 .run(status, reviewedAt, note ?? null, id);
             return { ...candidate, status, reviewedAt, ...note === undefined ? {} : { reviewNote: note } };
         });
-        if (decision.decision === 'approve')
-            await this.syncKnowledgeDocumentsQueued(reviewed.draft.knowledgeBaseId);
+        if (touchedEntryId !== undefined)
+            await this.syncKnowledgeEntryQueued(touchedEntryId);
         return reviewed;
     }
     async claimExtraction(sourceKey) {
@@ -1393,7 +1516,7 @@ export class LocalKnowledgeProvider {
       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
+        last_error=NULL, completion_json=NULL, updated_at=excluded.updated_at
       WHERE extraction_jobs.attempts < 3 AND (
         extraction_jobs.status='failed'
         OR (extraction_jobs.status='running' AND extraction_jobs.updated_at < ?)
@@ -1401,12 +1524,13 @@ export class LocalKnowledgeProvider {
     `).run(sourceKey, claimedAt, staleBefore);
         return result.changes === 1;
     }
-    async completeExtraction(sourceKey, candidateCount) {
+    async completeExtraction(sourceKey, value) {
         this.assertOpen();
+        const completion = normalizeExtractionCompletion(value);
         const result = this.db.prepare(`
-      UPDATE extraction_jobs SET status='completed', candidate_count=?, last_error=NULL, updated_at=?
+      UPDATE extraction_jobs SET status='completed', candidate_count=?, last_error=NULL, completion_json=?, updated_at=?
       WHERE source_key=? AND status='running'
-    `).run(candidateCount, nowIso(), sourceKey);
+    `).run(completion.candidateCount, JSON.stringify(completion), nowIso(), sourceKey);
         if (result.changes === 0) {
             const current = await this.extractionJob(sourceKey);
             if (current?.status !== 'completed')
@@ -1427,7 +1551,7 @@ export class LocalKnowledgeProvider {
     }
     async resetExtraction(sourceKey) {
         this.assertOpen();
-        this.db.prepare(`UPDATE extraction_jobs SET status='failed', attempts=0, candidate_count=0, last_error=NULL, updated_at=? WHERE source_key=?`)
+        this.db.prepare(`UPDATE extraction_jobs SET status='failed', attempts=0, candidate_count=0, last_error=NULL, completion_json=NULL, updated_at=? WHERE source_key=?`)
             .run(nowIso(), sourceKey);
     }
     async extractionJob(sourceKey) {
@@ -1542,12 +1666,86 @@ export class LocalKnowledgeProvider {
     syncKnowledgeDocumentsQueued(knowledgeBaseId) {
         return this.enqueueDocumentSync(() => this.syncKnowledgeDocuments(knowledgeBaseId));
     }
+    syncKnowledgeBaseManifestQueued(knowledgeBaseId) {
+        return this.enqueueDocumentSync(async () => {
+            const row = this.db.prepare('SELECT * FROM knowledge_bases WHERE id=?').get(knowledgeBaseId);
+            if (row !== undefined)
+                await this.documentStore.ensureBase(rowToKnowledgeBase(row));
+        });
+    }
+    syncKnowledgeEntryQueued(entryId) {
+        return this.enqueueDocumentSync(() => this.syncKnowledgeEntry(entryId));
+    }
+    /** Keep the derived Markdown projection proportional to one changed entry. */
+    async syncKnowledgeEntry(entryId) {
+        const projected = this.db.prepare(`
+      SELECT id,knowledge_base_id,rel_path FROM knowledge_documents WHERE id=?
+    `).get(entryId);
+        const entryRow = this.db.prepare(`SELECT ${ENTRY_COLUMNS} FROM knowledge_entries WHERE id=?`).get(entryId);
+        if (entryRow === undefined || entryRow.status !== 'active') {
+            if (projected !== undefined)
+                await this.removeProjectedDocument(projected);
+            this.db.prepare('DELETE FROM knowledge_documents WHERE id=?').run(entryId);
+            return;
+        }
+        const entry = rowToEntry(entryRow);
+        const baseRow = this.db.prepare('SELECT * FROM knowledge_bases WHERE id=?').get(entry.knowledgeBaseId);
+        if (baseRow === undefined)
+            return;
+        const base = rowToKnowledgeBase(baseRow);
+        const directory = await this.documentStore.ensureBase(base);
+        const relPath = knowledgeDocumentPath(entry);
+        const markdown = renderEntryMarkdown(entry);
+        const stored = await this.documentStore.writeDocument(directory, relPath, markdown);
+        this.upsertProjectedDocument(entry, relPath, stored.contentHash);
+        if (projected !== undefined && (String(projected.knowledge_base_id) !== entry.knowledgeBaseId
+            || String(projected.rel_path) !== relPath))
+            await this.removeProjectedDocument(projected);
+    }
+    async removeProjectedDocument(projected) {
+        const baseRow = this.db.prepare('SELECT * FROM knowledge_bases WHERE id=?')
+            .get(String(projected.knowledge_base_id));
+        if (baseRow === undefined)
+            return;
+        const directory = this.documentStore.baseDirectory(rowToKnowledgeBase(baseRow));
+        try {
+            await this.documentStore.deleteDocument(directory, String(projected.rel_path));
+        }
+        catch (error) {
+            if (!(error instanceof Error && error.code === 'ENOENT'))
+                throw error;
+        }
+    }
+    upsertProjectedDocument(entry, relPath, projectedHash) {
+        this.db.prepare(`
+      INSERT INTO knowledge_documents(
+        id,knowledge_base_id,rel_path,title,content,entry_count,content_hash,
+        document_state,finalized_at,finalization_note,created_at,updated_at
+      ) VALUES(?,?,?,?,?,?,?,?,?,?,?,?)
+      ON CONFLICT(id) DO UPDATE SET
+        knowledge_base_id=excluded.knowledge_base_id,rel_path=excluded.rel_path,
+        title=excluded.title,content=excluded.content,entry_count=excluded.entry_count,
+        content_hash=excluded.content_hash,document_state=excluded.document_state,
+        finalized_at=excluded.finalized_at,finalization_note=excluded.finalization_note,
+        updated_at=excluded.updated_at
+      WHERE knowledge_documents.knowledge_base_id<>excluded.knowledge_base_id
+         OR knowledge_documents.content_hash<>excluded.content_hash
+         OR knowledge_documents.rel_path<>excluded.rel_path
+         OR knowledge_documents.title<>excluded.title
+         OR knowledge_documents.entry_count<>excluded.entry_count
+         OR knowledge_documents.document_state<>excluded.document_state
+         OR knowledge_documents.finalized_at IS NOT excluded.finalized_at
+         OR knowledge_documents.finalization_note IS NOT excluded.finalization_note
+    `).run(entry.id, entry.knowledgeBaseId, relPath, entry.title, renderEntryContent(entry), 1, projectedHash, entry.documentState, entry.finalizedAt ?? null, entry.finalizationNote ?? null, entry.createdAt, entry.updatedAt);
+    }
     async syncKnowledgeDocuments(knowledgeBaseId) {
         const baseRow = this.db.prepare('SELECT * FROM knowledge_bases WHERE id=?').get(knowledgeBaseId);
         if (baseRow === undefined)
             return;
         const base = rowToKnowledgeBase(baseRow);
         const directory = await this.documentStore.ensureBase(base);
+        const storedDocuments = await this.documentStore.listDocuments(directory);
+        const storedById = new Map(storedDocuments.map(document => [document.metadata.id, document]));
         const entries = this.db.prepare(`
       SELECT ${ENTRY_COLUMNS} FROM knowledge_entries
       WHERE knowledge_base_id=? AND status='active'
@@ -1556,58 +1754,28 @@ export class LocalKnowledgeProvider {
         const desired = new Map();
         for (const entry of entries) {
             const relPath = knowledgeDocumentPath(entry);
-            const markdown = renderKnowledgeMarkdown({
-                metadata: {
-                    id: entry.id,
-                    type: entry.type,
-                    tags: entry.tags,
-                    scope: entry.scope,
-                    confidence: entry.confidence,
-                    status: entry.status,
-                    documentState: entry.documentState,
-                    ...entry.finalizedAt === undefined ? {} : { finalizedAt: entry.finalizedAt },
-                    ...entry.finalizationNote === undefined ? {} : { finalizationNote: entry.finalizationNote },
-                },
-                title: entry.title,
-                body: entry.body,
-            });
-            const stored = await this.documentStore.writeDocument(directory, relPath, markdown);
+            const markdown = renderEntryMarkdown(entry);
+            const current = storedById.get(entry.id);
+            const contentHash = markdownHash(markdown);
+            const stored = current?.relPath === relPath && current.contentHash === contentHash
+                ? current
+                : await this.documentStore.writeDocument(directory, relPath, markdown);
             desired.set(entry.id, {
                 entry,
                 relPath,
-                content: `# ${markdownHeading(entry.title)}\n\n${entry.body.trim()}\n`,
                 contentHash: stored.contentHash,
             });
         }
-        const storedDocuments = await this.documentStore.listDocuments(directory);
         for (const document of storedDocuments) {
             const expected = desired.get(document.metadata.id);
             if (expected === undefined || expected.relPath !== document.relPath) {
                 await this.documentStore.deleteDocument(directory, document.relPath, document.contentHash);
             }
         }
-        const existing = this.db.prepare('SELECT id,rel_path,created_at FROM knowledge_documents WHERE knowledge_base_id=?')
+        const existing = this.db.prepare('SELECT id FROM knowledge_documents WHERE knowledge_base_id=?')
             .all(knowledgeBaseId);
         for (const document of desired.values()) {
-            this.db.prepare(`
-        INSERT INTO knowledge_documents(
-          id,knowledge_base_id,rel_path,title,content,entry_count,content_hash,
-          document_state,finalized_at,finalization_note,created_at,updated_at
-        ) VALUES(?,?,?,?,?,?,?,?,?,?,?,?)
-        ON CONFLICT(id) DO UPDATE SET
-          knowledge_base_id=excluded.knowledge_base_id,rel_path=excluded.rel_path,
-          title=excluded.title,content=excluded.content,entry_count=excluded.entry_count,
-          content_hash=excluded.content_hash,document_state=excluded.document_state,
-          finalized_at=excluded.finalized_at,finalization_note=excluded.finalization_note,
-          updated_at=excluded.updated_at
-        WHERE knowledge_documents.content_hash<>excluded.content_hash
-           OR knowledge_documents.rel_path<>excluded.rel_path
-           OR knowledge_documents.title<>excluded.title
-           OR knowledge_documents.entry_count<>excluded.entry_count
-           OR knowledge_documents.document_state<>excluded.document_state
-           OR knowledge_documents.finalized_at IS NOT excluded.finalized_at
-           OR knowledge_documents.finalization_note IS NOT excluded.finalization_note
-      `).run(document.entry.id, knowledgeBaseId, document.relPath, document.entry.title, document.content, 1, document.contentHash, document.entry.documentState, document.entry.finalizedAt ?? null, document.entry.finalizationNote ?? null, document.entry.createdAt, document.entry.updatedAt);
+            this.upsertProjectedDocument(document.entry, document.relPath, document.contentHash);
         }
         for (const row of existing) {
             if (!desired.has(String(row.id)))
@@ -1615,6 +1783,26 @@ export class LocalKnowledgeProvider {
         }
     }
 }
+function renderEntryMarkdown(entry) {
+    return renderKnowledgeMarkdown({
+        metadata: {
+            id: entry.id,
+            type: entry.type,
+            tags: entry.tags,
+            scope: entry.scope,
+            confidence: entry.confidence,
+            status: entry.status,
+            documentState: entry.documentState,
+            ...entry.finalizedAt === undefined ? {} : { finalizedAt: entry.finalizedAt },
+            ...entry.finalizationNote === undefined ? {} : { finalizationNote: entry.finalizationNote },
+        },
+        title: entry.title,
+        body: entry.body,
+    });
+}
+function renderEntryContent(entry) {
+    return `# ${markdownHeading(entry.title)}\n\n${entry.body.trim()}\n`;
+}
 function markdownHeading(value) {
     return value.replace(/[\r\n]+/g, ' ').replace(/^#+\s*/, '').trim();
 }
@@ -1929,15 +2117,61 @@ function rowToMount(row) {
 }
 function rowToExtractionJob(row) {
     const lastError = row.last_error == null ? undefined : String(row.last_error);
+    const completion = row.completion_json == null
+        ? undefined
+        : normalizeExtractionCompletion(JSON.parse(String(row.completion_json)));
     return {
         sourceKey: String(row.source_key),
         status: String(row.status),
         attempts: Number(row.attempts),
         candidateCount: Number(row.candidate_count),
         ...lastError === undefined ? {} : { lastError },
+        ...completion === undefined ? {} : { completion },
         updatedAt: String(row.updated_at),
     };
 }
+function normalizeExtractionCompletion(value) {
+    if (typeof value === 'number') {
+        const candidateCount = Math.max(0, Math.floor(value));
+        return { outcome: 'completed', candidateCount, directCount: 0, auditCount: candidateCount, destinations: [] };
+    }
+    if (value.outcome !== 'completed' && value.outcome !== 'skipped' && value.outcome !== 'unmounted') {
+        throw new Error('extraction completion outcome is invalid');
+    }
+    const count = (input, field) => {
+        if (!Number.isInteger(input) || input < 0 || input > 10_000)
+            throw new Error(`extraction completion ${field} is invalid`);
+        return input;
+    };
+    if (!Array.isArray(value.destinations) || value.destinations.length > 100) {
+        throw new Error('extraction completion destinations are invalid');
+    }
+    const text = (input, field, limit) => {
+        const normalized = typeof input === 'string' ? input.trim() : '';
+        if (normalized.length === 0 || normalized.length > limit)
+            throw new Error(`extraction completion ${field} is invalid`);
+        return normalized;
+    };
+    return {
+        outcome: value.outcome,
+        candidateCount: count(value.candidateCount, 'candidateCount'),
+        directCount: count(value.directCount, 'directCount'),
+        auditCount: count(value.auditCount, 'auditCount'),
+        destinations: value.destinations.map(destination => {
+            if (destination.disposition !== 'written' && destination.disposition !== 'pending-review') {
+                throw new Error('extraction completion disposition is invalid');
+            }
+            return {
+                knowledgeBaseId: text(destination.knowledgeBaseId, 'knowledgeBaseId', 200),
+                knowledgeBaseName: text(destination.knowledgeBaseName, 'knowledgeBaseName', 200),
+                ...destination.documentId === undefined ? {} : { documentId: text(destination.documentId, 'documentId', 200) },
+                documentTitle: text(destination.documentTitle, 'documentTitle', 500),
+                ...destination.documentPath === undefined ? {} : { documentPath: text(destination.documentPath, 'documentPath', 1000) },
+                disposition: destination.disposition,
+            };
+        }),
+    };
+}
 function rowToToken(row) {
     const lastUsedAt = row.last_used_at == null ? undefined : String(row.last_used_at);
     const revokedAt = row.revoked_at == null ? undefined : String(row.revoked_at);