@lemoncat7/dsh-knowledge 2.1.1 → 2.2.0

package/lib/local-provider.js

@@ -8,7 +8,7 @@ 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 { applyKnowledgeTextEdits, 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,
@@ -44,7 +44,7 @@ export class LocalKnowledgeProvider {
     }
     migrate() {
         let version = Number(this.db.prepare('PRAGMA user_version').get().user_version ?? 0);
-        if (version > 10)
+        if (version > 11)
             throw new Error(`knowledge database schema ${version} is newer than this plugin supports`);
         if (version === 0)
             this.db.exec(`
@@ -277,6 +277,25 @@ export class LocalKnowledgeProvider {
                 throw error;
             }
         }
+        if (version <= 9)
+            version = 10;
+        if (version === 10) {
+            this.db.exec('BEGIN IMMEDIATE');
+            try {
+                const candidateTable = this.db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='knowledge_candidates'").get();
+                const candidateColumns = candidateTable === undefined
+                    ? []
+                    : this.db.prepare('PRAGMA table_info(knowledge_candidates)').all();
+                if (candidateTable !== undefined && !candidateColumns.some(column => String(column.name) === 'change_json')) {
+                    this.db.exec('ALTER TABLE knowledge_candidates ADD COLUMN change_json TEXT');
+                }
+                this.db.exec('PRAGMA user_version = 11; 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=?")
@@ -1177,7 +1196,7 @@ export class LocalKnowledgeProvider {
         return result;
     }
     insertCandidate(proposal, sourceKey) {
-        const hash = contentHash(proposal.draft) + `:${proposal.action}:${proposal.targetId ?? ''}`;
+        const hash = contentHash(proposal.draft) + `:${proposal.action}:${proposal.targetId ?? ''}:${JSON.stringify(proposal.change ?? null)}`;
         if (sourceKey !== undefined) {
             const existing = this.db.prepare('SELECT * FROM knowledge_candidates WHERE source_key = ? AND proposal_hash = ?').get(sourceKey, hash);
             if (existing !== undefined)
@@ -1191,9 +1210,9 @@ export class LocalKnowledgeProvider {
             createdAt: nowIso(),
         };
         this.db.prepare(`
-      INSERT INTO knowledge_candidates(id,action,target_id,draft_json,reason,status,source_key,proposal_hash,created_at)
-      VALUES(?,?,?,?,?,'pending',?,?,?)
-    `).run(candidate.id, candidate.action, candidate.targetId ?? null, JSON.stringify(candidate.draft), candidate.reason, sourceKey ?? null, hash, candidate.createdAt);
+      INSERT INTO knowledge_candidates(id,action,target_id,change_json,draft_json,reason,status,source_key,proposal_hash,created_at)
+      VALUES(?,?,?,?,?,?,'pending',?,?,?)
+    `).run(candidate.id, candidate.action, candidate.targetId ?? null, candidate.change === undefined ? null : JSON.stringify(candidate.change), JSON.stringify(candidate.draft), candidate.reason, sourceKey ?? null, hash, candidate.createdAt);
         return candidate;
     }
     resolveDirectProposal(proposal) {
@@ -1209,10 +1228,11 @@ export class LocalKnowledgeProvider {
             if (!sameScope(target.scope, proposal.draft.scope)) {
                 return { outcome: 'conflict', proposal: { ...proposal, action: 'conflict' } };
             }
-            if (potentiallyConflicts(target, proposal.draft)) {
+            const applied = applyCandidateToTarget(target, proposal, true);
+            if (!applied.ok) {
                 return { outcome: 'conflict', proposal: { ...proposal, action: 'conflict' } };
             }
-            const draft = mergeKnowledgeDraft(target, proposal.draft, true);
+            const draft = applied.draft;
             if (contentHash(draft) === contentHash(target))
                 return { outcome: 'duplicate', entry: target };
             return { outcome: 'merged', proposal: { ...proposal, action: 'update', draft } };
@@ -1268,7 +1288,17 @@ export class LocalKnowledgeProvider {
     async listCandidates(status, limit) {
         this.assertOpen();
         return this.db.prepare('SELECT * FROM knowledge_candidates WHERE status = ? ORDER BY created_at DESC LIMIT ?')
-            .all(status, Math.max(1, Math.min(limit, 100))).map(rowToCandidate);
+            .all(status, Math.max(1, Math.min(limit, 100))).map(rowToCandidate).map(candidate => {
+            if (candidate.status !== 'pending' || candidate.targetId === undefined || candidate.change?.kind !== 'revise')
+                return candidate;
+            try {
+                const applied = applyCandidateToTarget(this.activeEntry(candidate.targetId), candidate, true);
+                return applied.ok ? { ...candidate, draft: applied.draft } : candidate;
+            }
+            catch {
+                return candidate;
+            }
+        });
     }
     async review(id, decision) {
         this.assertOpen();
@@ -1282,7 +1312,20 @@ export class LocalKnowledgeProvider {
                 throw conflict(`candidate ${id} was already ${candidate.status}`);
             let draft = decision.draft === undefined ? candidate.draft : normalizeDraft(decision.draft);
             if (decision.decision === 'approve') {
-                if (candidate.action === 'conflict') {
+                if (candidate.action !== 'create' && decision.draft !== undefined) {
+                    if (candidate.action === 'conflict' && decision.resolution !== 'merge') {
+                        throw conflict('conflict candidate requires an explicit merge resolution');
+                    }
+                    if (candidate.targetId === undefined)
+                        throw new Error('candidate target is missing');
+                    const target = this.activeEntry(candidate.targetId);
+                    if (draft.knowledgeBaseId !== target.knowledgeBaseId) {
+                        throw conflict('candidate approval cannot move a document between knowledge bases');
+                    }
+                    assertExpectedReviewVersion(target, decision.expectedVersion);
+                    this.updateEntry(candidate.targetId, editedKnowledgeDraft(target, draft), 'update');
+                }
+                else if (candidate.action === 'conflict') {
                     if (decision.resolution !== 'merge') {
                         throw conflict('conflict candidate requires an explicit merge resolution');
                     }
@@ -1292,12 +1335,16 @@ export class LocalKnowledgeProvider {
                     if (draft.knowledgeBaseId !== target.knowledgeBaseId) {
                         throw conflict('candidate approval cannot move a document between knowledge bases');
                     }
-                    this.updateEntry(candidate.targetId, mergeKnowledgeDraft(target, draft, true), 'update');
+                    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');
                 }
                 else {
                     const resolution = this.resolveDirectProposal({
                         action: candidate.action,
                         ...candidate.targetId === undefined ? {} : { targetId: candidate.targetId },
+                        ...candidate.change === undefined ? {} : { change: candidate.change },
                         draft,
                         reason: candidate.reason,
                     });
@@ -1305,9 +1352,9 @@ export class LocalKnowledgeProvider {
                         const proposal = resolution.proposal;
                         this.db.prepare(`
               UPDATE knowledge_candidates
-              SET action='conflict', target_id=?, draft_json=?, reason=?
+              SET action='conflict', target_id=?, change_json=?, draft_json=?, reason=?
               WHERE id=? AND status='pending'
-            `).run(proposal.targetId ?? null, JSON.stringify(proposal.draft), proposal.reason, id);
+            `).run(proposal.targetId ?? null, proposal.change === undefined ? null : JSON.stringify(proposal.change), JSON.stringify(proposal.draft), proposal.reason, id);
                         return {
                             ...candidate,
                             action: 'conflict',
@@ -1646,12 +1693,14 @@ function rowToCandidate(row) {
     const reviewedAt = row.reviewed_at == null ? undefined : String(row.reviewed_at);
     const reviewNote = row.review_note == null ? undefined : String(row.review_note);
     const draft = JSON.parse(String(row.draft_json));
+    const change = row.change_json == null ? undefined : normalizeCandidateChange(JSON.parse(String(row.change_json)));
     if (draft.knowledgeBaseId === undefined)
         draft.knowledgeBaseId = DEFAULT_KNOWLEDGE_BASE_ID;
     return {
         id: String(row.id),
         action: String(row.action),
         ...targetId === undefined ? {} : { targetId },
+        ...change === undefined ? {} : { change },
         draft,
         reason: String(row.reason),
         status: String(row.status),
@@ -1662,17 +1711,52 @@ function rowToCandidate(row) {
     };
 }
 function normalizeProposal(input) {
+    const change = normalizeCandidateChange(input.change);
     const proposal = {
         action: input.action,
         ...input.targetId === undefined ? {} : { targetId: input.targetId },
+        ...change === undefined ? {} : { change },
         draft: normalizeDraft(input.draft),
         reason: input.reason.trim().slice(0, 2000),
     };
     if (proposal.action !== 'create' && proposal.targetId === undefined) {
         throw new Error(`${proposal.action} candidate requires targetId`);
     }
+    if (proposal.action === 'create' && proposal.change !== undefined) {
+        throw new Error('create candidate cannot contain a document change');
+    }
     return proposal;
 }
+function normalizeCandidateChange(input) {
+    if (input === undefined)
+        return undefined;
+    if (input.kind === 'append')
+        return { kind: 'append' };
+    if (input.kind !== 'revise')
+        throw new Error('unsupported candidate change kind');
+    if (!Number.isSafeInteger(input.baseVersion) || input.baseVersion < 1) {
+        throw new Error('revision baseVersion must be a positive integer');
+    }
+    const baseHash = input.baseHash.trim().toLocaleLowerCase();
+    if (!/^[a-f0-9]{64}$/u.test(baseHash))
+        throw new Error('revision baseHash must be a SHA-256 hash');
+    if (!Array.isArray(input.edits) || input.edits.length < 1 || input.edits.length > 20) {
+        throw new Error('revision must contain 1-20 text edits');
+    }
+    const edits = input.edits.map((edit, index) => {
+        const oldText = edit.oldText.replace(/\r\n?/gu, '\n');
+        const newText = edit.newText.replace(/\r\n?/gu, '\n');
+        if (oldText.length === 0 || oldText.length > 12_000)
+            throw new Error(`revision edit ${index + 1} anchor must contain 1-12000 characters`);
+        if (newText.length > 12_000)
+            throw new Error(`revision edit ${index + 1} replacement must contain at most 12000 characters`);
+        return { oldText, newText };
+    });
+    const append = input.append?.trim();
+    if (append !== undefined && append.length > 12_000)
+        throw new Error('revision append must contain at most 12000 characters');
+    return { kind: 'revise', baseVersion: input.baseVersion, baseHash, edits, ...append ? { append } : {} };
+}
 function mergeKnowledgeDraft(current, incoming, preferIncomingTitle) {
     return normalizeDraft({
         knowledgeBaseId: current.knowledgeBaseId,
@@ -1687,6 +1771,44 @@ function mergeKnowledgeDraft(current, incoming, preferIncomingTitle) {
             : { source: incoming.source },
     });
 }
+function applyCandidateToTarget(current, proposal, preferIncomingTitle) {
+    if (proposal.change?.kind !== 'revise') {
+        if (potentiallyConflicts(current, proposal.draft))
+            return { ok: false, reason: 'candidate contradicts the current document' };
+        return { ok: true, draft: mergeKnowledgeDraft(current, proposal.draft, preferIncomingTitle) };
+    }
+    const revised = applyKnowledgeTextEdits(current.body, proposal.change.edits, proposal.change.append);
+    if (!revised.ok)
+        return revised;
+    return {
+        ok: true,
+        draft: normalizeDraft({
+            knowledgeBaseId: current.knowledgeBaseId,
+            title: preferIncomingTitle ? proposal.draft.title : current.title,
+            body: revised.body,
+            type: current.type,
+            tags: [...current.tags, ...proposal.draft.tags],
+            scope: current.scope,
+            confidence: Math.max(current.confidence, proposal.draft.confidence),
+            ...proposal.draft.source === undefined
+                ? current.source === undefined ? {} : { source: current.source }
+                : { source: proposal.draft.source },
+        }),
+    };
+}
+function editedKnowledgeDraft(current, incoming) {
+    return normalizeDraft({
+        ...incoming,
+        knowledgeBaseId: current.knowledgeBaseId,
+        type: current.type,
+        scope: current.scope,
+    });
+}
+function assertExpectedReviewVersion(current, expectedVersion) {
+    if (expectedVersion !== undefined && current.version !== expectedVersion) {
+        throw conflict(`knowledge changed during review (expected version ${expectedVersion}, current version ${current.version}); reopen the editor and resolve the current document`);
+    }
+}
 function potentiallyConflicts(current, incoming) {
     const currentBody = normalizedBody(current.body);
     const incomingBody = normalizedBody(incoming.body);