@devflow-tools/knowledge-engine 0.17.8 → 0.18.0

package/dist/knowledge-store.js

@@ -6,6 +6,7 @@ import { isPollutedKnowledgeHeading, resolveKnowledgeTitle } from './result-qual
 import { KNOWLEDGE_CHUNK_POLICY_VERSION } from './markdown-converter.js';
 import { createHash } from 'node:crypto';
 import { extractApiIdentifiers, extractCodeBlocks, inferKnowledgeChunkKind } from './markdown-converter.js';
+import { createMiniLmEmbeddingProfile } from '@devflow-tools/sdk';
 const KNOWLEDGE_SCHEMA = `
 CREATE TABLE IF NOT EXISTS knowledge_docs (
   id TEXT PRIMARY KEY,
@@ -31,7 +32,19 @@ CREATE TABLE IF NOT EXISTS knowledge_chunks (
   framework TEXT,
   api_identifiers TEXT NOT NULL DEFAULT '[]',
   source_url TEXT,
-  content_hash TEXT NOT NULL DEFAULT ''
+  content_hash TEXT NOT NULL DEFAULT '',
+  page_id TEXT,
+  project_id TEXT NOT NULL DEFAULT '',
+  heading_breadcrumbs TEXT NOT NULL DEFAULT '[]',
+  embedding_text TEXT NOT NULL DEFAULT '',
+  original_start INTEGER,
+  original_end INTEGER,
+  entities TEXT NOT NULL DEFAULT '[]',
+  symbols TEXT NOT NULL DEFAULT '[]',
+  links TEXT NOT NULL DEFAULT '[]',
+  oversized_atomic INTEGER NOT NULL DEFAULT 0,
+  provenance TEXT NOT NULL DEFAULT '{}',
+  analysis_terms TEXT NOT NULL DEFAULT '[]'
 );
 
 CREATE VIRTUAL TABLE IF NOT EXISTS knowledge_fts USING fts5(
@@ -45,6 +58,15 @@ CREATE VIRTUAL TABLE IF NOT EXISTS knowledge_vec USING vec0(
   embedding FLOAT[384]
 );
 
+CREATE TABLE IF NOT EXISTS knowledge_vector_profiles (
+  id TEXT PRIMARY KEY,
+  profile_hash TEXT NOT NULL,
+  generation INTEGER NOT NULL CHECK(generation > 0),
+  source_content_hash TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_knowledge_vector_profiles_generation
+  ON knowledge_vector_profiles(profile_hash, generation);
+
 CREATE TABLE IF NOT EXISTS knowledge_source_readiness (
   source TEXT PRIMARY KEY,
   expected_version TEXT,
@@ -60,7 +82,7 @@ CREATE TABLE IF NOT EXISTS knowledge_source_readiness (
 `;
 const COMPILED_KNOWLEDGE_SCHEMA = `
 CREATE TABLE IF NOT EXISTS knowledge_project_profiles (
-  project_root TEXT PRIMARY KEY,
+  project_id TEXT PRIMARY KEY,
   profile_hash TEXT NOT NULL,
   profile_json TEXT NOT NULL,
   generated_at INTEGER NOT NULL
@@ -81,7 +103,7 @@ CREATE INDEX IF NOT EXISTS idx_knowledge_source_schemas_source
 
 CREATE TABLE IF NOT EXISTS knowledge_catalog_snapshots (
   id TEXT PRIMARY KEY,
-  project_root TEXT NOT NULL,
+  project_id TEXT NOT NULL,
   profile_hash TEXT NOT NULL,
   source_id TEXT NOT NULL,
   schema_id TEXT NOT NULL,
@@ -90,14 +112,14 @@ CREATE TABLE IF NOT EXISTS knowledge_catalog_snapshots (
   status TEXT NOT NULL CHECK(status IN ('active', 'inactive')),
   created_at INTEGER NOT NULL,
   activated_at INTEGER,
-  UNIQUE(project_root, source_id, content_hash)
+  UNIQUE(project_id, source_id, content_hash)
 );
 CREATE UNIQUE INDEX IF NOT EXISTS idx_knowledge_catalog_active_source
-  ON knowledge_catalog_snapshots(project_root, source_id) WHERE status = 'active';
+  ON knowledge_catalog_snapshots(project_id, source_id) WHERE status = 'active';
 
 CREATE TABLE IF NOT EXISTS knowledge_pages (
   id TEXT PRIMARY KEY,
-  project_root TEXT NOT NULL,
+  project_id TEXT NOT NULL,
   source_id TEXT NOT NULL,
   source_schema_id TEXT NOT NULL,
   title TEXT NOT NULL,
@@ -113,7 +135,7 @@ CREATE TABLE IF NOT EXISTS knowledge_pages (
   compiled_at INTEGER NOT NULL
 );
 CREATE INDEX IF NOT EXISTS idx_knowledge_pages_source
-  ON knowledge_pages(project_root, source_id, status, content_hash);
+  ON knowledge_pages(project_id, source_id, status, content_hash);
 
 CREATE TABLE IF NOT EXISTS knowledge_entity_links (
   page_id TEXT NOT NULL REFERENCES knowledge_pages(id) ON DELETE CASCADE,
@@ -137,7 +159,7 @@ CREATE INDEX IF NOT EXISTS idx_knowledge_symbol_links_lookup
 
 CREATE TABLE IF NOT EXISTS knowledge_refresh_jobs (
   id TEXT PRIMARY KEY,
-  project_root TEXT NOT NULL,
+  project_id TEXT NOT NULL,
   source_id TEXT NOT NULL,
   input_content_hash TEXT NOT NULL,
   previous_snapshot_id TEXT,
@@ -146,14 +168,14 @@ CREATE TABLE IF NOT EXISTS knowledge_refresh_jobs (
   error TEXT,
   created_at INTEGER NOT NULL,
   updated_at INTEGER NOT NULL,
-  UNIQUE(project_root, source_id, input_content_hash)
+  UNIQUE(project_id, source_id, input_content_hash)
 );
 CREATE INDEX IF NOT EXISTS idx_knowledge_refresh_jobs_source
-  ON knowledge_refresh_jobs(project_root, source_id, updated_at DESC);
+  ON knowledge_refresh_jobs(project_id, source_id, updated_at DESC);
 
 CREATE TABLE IF NOT EXISTS knowledge_coverage_gaps (
   id TEXT PRIMARY KEY,
-  project_root TEXT NOT NULL,
+  project_id TEXT NOT NULL,
   source_id TEXT NOT NULL,
   kind TEXT NOT NULL,
   gap_json TEXT NOT NULL,
@@ -161,7 +183,7 @@ CREATE TABLE IF NOT EXISTS knowledge_coverage_gaps (
   resolved_at INTEGER
 );
 CREATE INDEX IF NOT EXISTS idx_knowledge_coverage_gaps_active
-  ON knowledge_coverage_gaps(project_root, source_id, resolved_at, detected_at DESC);
+  ON knowledge_coverage_gaps(project_id, source_id, resolved_at, detected_at DESC);
 
 CREATE TABLE IF NOT EXISTS knowledge_analysis_manifests (
   source_id TEXT NOT NULL,
@@ -174,15 +196,60 @@ CREATE TABLE IF NOT EXISTS knowledge_analysis_manifests (
 );
 
 CREATE TABLE IF NOT EXISTS knowledge_raw_sources (
-  project_root TEXT NOT NULL,
+  project_id TEXT NOT NULL,
   source_id TEXT NOT NULL,
   content_hash TEXT NOT NULL,
   source_uri TEXT NOT NULL,
   source_version TEXT,
   metadata_json TEXT NOT NULL DEFAULT '{}',
   retrieved_at INTEGER NOT NULL,
-  PRIMARY KEY(project_root, source_id, content_hash)
+  PRIMARY KEY(project_id, source_id, content_hash)
+);
+
+CREATE TABLE IF NOT EXISTS knowledge_source_aggregates_v1 (
+  identity_hash TEXT PRIMARY KEY,
+  project_id TEXT NOT NULL,
+  source_id TEXT NOT NULL,
+  state TEXT NOT NULL,
+  revision INTEGER NOT NULL,
+  content_hash TEXT,
+  aggregate_hash TEXT NOT NULL,
+  aggregate_json TEXT NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_knowledge_source_aggregates_scope
+  ON knowledge_source_aggregates_v1(project_id, source_id, updated_at DESC);
+
+CREATE TABLE IF NOT EXISTS knowledge_source_events_v1 (
+  event_id TEXT PRIMARY KEY,
+  identity_hash TEXT NOT NULL REFERENCES knowledge_source_aggregates_v1(identity_hash),
+  sequence INTEGER NOT NULL,
+  transition_json TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  UNIQUE(identity_hash, sequence)
+);
+
+CREATE TABLE IF NOT EXISTS knowledge_claims_v1 (
+  claim_id TEXT PRIMARY KEY,
+  identity_hash TEXT NOT NULL REFERENCES knowledge_source_aggregates_v1(identity_hash),
+  source_id TEXT NOT NULL,
+  page_id TEXT NOT NULL,
+  status TEXT NOT NULL,
+  source_content_hash TEXT NOT NULL,
+  claim_hash TEXT NOT NULL,
+  claim_json TEXT NOT NULL,
+  created_at INTEGER NOT NULL
 );
+CREATE INDEX IF NOT EXISTS idx_knowledge_claims_source
+  ON knowledge_claims_v1(source_id, source_content_hash, status);
+
+CREATE TABLE IF NOT EXISTS knowledge_maintenance_runs (
+  id TEXT PRIMARY KEY,
+  manifest_json TEXT NOT NULL,
+  created_at INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_knowledge_maintenance_runs_created
+  ON knowledge_maintenance_runs(created_at DESC);
 `;
 const FTS_TRIGGERS = `
 CREATE TRIGGER IF NOT EXISTS kchunks_ai AFTER INSERT ON knowledge_chunks BEGIN
@@ -201,8 +268,10 @@ CREATE TRIGGER IF NOT EXISTS kchunks_au AFTER UPDATE ON knowledge_chunks BEGIN
 END;
 `;
 export class KnowledgeStore {
+    embeddingProfile;
     db;
-    constructor(dbPath) {
+    constructor(dbPath, embeddingProfile = createMiniLmEmbeddingProfile('knowledge_retrieval')) {
+        this.embeddingProfile = embeddingProfile;
         const dir = dirname(dbPath);
         if (!existsSync(dir))
             mkdirSync(dir, { recursive: true });
@@ -211,66 +280,49 @@ export class KnowledgeStore {
         this.db.pragma('busy_timeout = 5000');
         this.db.pragma('foreign_keys = ON');
         sqliteVec.load(this.db);
+        this.assertCanonicalSchemaOrEmpty();
         this.db.exec(KNOWLEDGE_SCHEMA);
-        this.migrateQualitySchema();
-        this.migrateCompiledKnowledgeSchema();
-        this.ensureTrigramFts();
+        this.db.exec(COMPILED_KNOWLEDGE_SCHEMA);
         this.db.exec(FTS_TRIGGERS);
     }
-    migrateQualitySchema() {
-        const columns = this.db.pragma('table_info(knowledge_docs)');
-        if (!columns.some(column => column.name === 'chunk_policy_version')) {
-            this.db.exec('ALTER TABLE knowledge_docs ADD COLUMN chunk_policy_version INTEGER NOT NULL DEFAULT 0');
-        }
-        const chunkColumns = this.db.pragma('table_info(knowledge_chunks)');
-        const addChunkColumn = (name, sql) => {
-            if (!chunkColumns.some(column => column.name === name))
-                this.db.exec(sql);
-        };
-        addChunkColumn('chunk_kind', "ALTER TABLE knowledge_chunks ADD COLUMN chunk_kind TEXT NOT NULL DEFAULT 'overview'");
-        addChunkColumn('framework', 'ALTER TABLE knowledge_chunks ADD COLUMN framework TEXT');
-        addChunkColumn('api_identifiers', "ALTER TABLE knowledge_chunks ADD COLUMN api_identifiers TEXT NOT NULL DEFAULT '[]'");
-        addChunkColumn('source_url', 'ALTER TABLE knowledge_chunks ADD COLUMN source_url TEXT');
-        addChunkColumn('content_hash', "ALTER TABLE knowledge_chunks ADD COLUMN content_hash TEXT NOT NULL DEFAULT ''");
-    }
-    migrateCompiledKnowledgeSchema() {
-        this.db.exec(COMPILED_KNOWLEDGE_SCHEMA);
-        const chunkColumns = this.db.pragma('table_info(knowledge_chunks)');
-        const add = (name, sql) => {
-            if (!chunkColumns.some(column => column.name === name))
-                this.db.exec(sql);
-        };
-        add('page_id', 'ALTER TABLE knowledge_chunks ADD COLUMN page_id TEXT');
-        add('project_root', "ALTER TABLE knowledge_chunks ADD COLUMN project_root TEXT NOT NULL DEFAULT ''");
-        add('heading_breadcrumbs', "ALTER TABLE knowledge_chunks ADD COLUMN heading_breadcrumbs TEXT NOT NULL DEFAULT '[]'");
-        add('embedding_text', "ALTER TABLE knowledge_chunks ADD COLUMN embedding_text TEXT NOT NULL DEFAULT ''");
-        add('original_start', 'ALTER TABLE knowledge_chunks ADD COLUMN original_start INTEGER');
-        add('original_end', 'ALTER TABLE knowledge_chunks ADD COLUMN original_end INTEGER');
-        add('entities', "ALTER TABLE knowledge_chunks ADD COLUMN entities TEXT NOT NULL DEFAULT '[]'");
-        add('symbols', "ALTER TABLE knowledge_chunks ADD COLUMN symbols TEXT NOT NULL DEFAULT '[]'");
-        add('links', "ALTER TABLE knowledge_chunks ADD COLUMN links TEXT NOT NULL DEFAULT '[]'");
-        add('oversized_atomic', 'ALTER TABLE knowledge_chunks ADD COLUMN oversized_atomic INTEGER NOT NULL DEFAULT 0');
-        add('provenance', "ALTER TABLE knowledge_chunks ADD COLUMN provenance TEXT NOT NULL DEFAULT '{}'");
-        add('analysis_terms', "ALTER TABLE knowledge_chunks ADD COLUMN analysis_terms TEXT NOT NULL DEFAULT '[]'");
-    }
-    ensureTrigramFts() {
-        const row = this.db.prepare("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'knowledge_fts'").get();
-        if (/tokenize\s*=\s*['\"]?trigram/i.test(row?.sql ?? ''))
+    assertCanonicalSchemaOrEmpty() {
+        const docs = this.tableColumns('knowledge_docs');
+        if (docs.length === 0)
             return;
-        this.db.transaction(() => {
-            this.db.exec(`
-        DROP TRIGGER IF EXISTS kchunks_ai;
-        DROP TRIGGER IF EXISTS kchunks_ad;
-        DROP TRIGGER IF EXISTS kchunks_au;
-        DROP TABLE IF EXISTS knowledge_fts;
-        CREATE VIRTUAL TABLE knowledge_fts USING fts5(
-          id UNINDEXED, heading_path, content, code_blocks,
-          content=knowledge_chunks,
-          tokenize='trigram'
-        );
-        INSERT INTO knowledge_fts(knowledge_fts) VALUES('rebuild');
-      `);
-        })();
+        const requiredColumns = new Map([
+            ['knowledge_docs', ['source', 'url', 'title', 'version', 'content_hash', 'status', 'chunk_policy_version']],
+            ['knowledge_chunks', [
+                    'doc_id', 'chunk_index', 'heading_path', 'content', 'code_blocks', 'token_count',
+                    'chunk_kind', 'framework', 'api_identifiers', 'source_url', 'content_hash', 'page_id',
+                    'project_id', 'heading_breadcrumbs', 'embedding_text', 'original_start', 'original_end',
+                    'entities', 'symbols', 'links', 'oversized_atomic', 'provenance', 'analysis_terms',
+                ]],
+            ['knowledge_vector_profiles', ['profile_hash', 'generation', 'source_content_hash']],
+        ]);
+        const requiredTables = [
+            'knowledge_fts', 'knowledge_vec', 'knowledge_source_readiness', 'knowledge_project_profiles',
+            'knowledge_source_schemas', 'knowledge_catalog_snapshots', 'knowledge_pages',
+            'knowledge_entity_links', 'knowledge_symbol_links', 'knowledge_refresh_jobs',
+            'knowledge_coverage_gaps', 'knowledge_analysis_manifests', 'knowledge_raw_sources',
+            'knowledge_source_aggregates_v1', 'knowledge_source_events_v1', 'knowledge_claims_v1',
+            'knowledge_maintenance_runs',
+        ];
+        const schemaRows = this.db.prepare("SELECT name, sql FROM sqlite_master WHERE type IN ('table', 'view')").all();
+        const tables = new Map(schemaRows.map(row => [row.name, row.sql ?? '']));
+        const invalid = [
+            ...requiredTables.filter(table => !tables.has(table)).map(table => `table:${table}`),
+            ...[...requiredColumns].flatMap(([table, columns]) => {
+                const actual = new Set(this.tableColumns(table));
+                return columns.filter(column => !actual.has(column)).map(column => `column:${table}.${column}`);
+            }),
+            ...(/tokenize\s*=\s*['\"]?trigram/i.test(tables.get('knowledge_fts') ?? '')
+                ? [] : ['table:knowledge_fts.tokenizer']),
+        ];
+        if (invalid.length > 0)
+            throw new Error(`KNOWLEDGE_SCHEMA_UNSUPPORTED:${invalid.join(',')}`);
+    }
+    tableColumns(table) {
+        return this.db.pragma(`table_info(${table})`).map(row => row.name);
     }
     upsertDoc(doc) {
         const title = resolveKnowledgeTitle({
@@ -282,10 +334,10 @@ export class KnowledgeStore {
             throw new Error(`Knowledge document ${doc.id} has no meaningful title`);
         const existing = this.db.prepare('SELECT id FROM knowledge_docs WHERE id = ?').get(doc.id);
         if (existing) {
-            this.db.prepare("UPDATE knowledge_docs SET title=?, version=?, fetched_at=?, content_hash=?, chunk_policy_version=?, status='active' WHERE id=?").run(title, doc.version ?? null, Date.now(), doc.contentHash ?? null, doc.chunkPolicyVersion ?? KNOWLEDGE_CHUNK_POLICY_VERSION, doc.id);
+            this.db.prepare("UPDATE knowledge_docs SET title=?, version=?, fetched_at=?, content_hash=?, chunk_policy_version=?, status='active' WHERE id=?").run(title, doc.version ?? null, doc.fetchedAt ?? Date.now(), doc.contentHash ?? null, doc.chunkPolicyVersion ?? KNOWLEDGE_CHUNK_POLICY_VERSION, doc.id);
         }
         else {
-            this.db.prepare('INSERT INTO knowledge_docs (id, source, url, title, version, fetched_at, content_hash, chunk_policy_version) VALUES (?,?,?,?,?,?,?,?)').run(doc.id, doc.source, doc.url, title, doc.version ?? null, Date.now(), doc.contentHash ?? null, doc.chunkPolicyVersion ?? KNOWLEDGE_CHUNK_POLICY_VERSION);
+            this.db.prepare('INSERT INTO knowledge_docs (id, source, url, title, version, fetched_at, content_hash, chunk_policy_version) VALUES (?,?,?,?,?,?,?,?)').run(doc.id, doc.source, doc.url, title, doc.version ?? null, doc.fetchedAt ?? Date.now(), doc.contentHash ?? null, doc.chunkPolicyVersion ?? KNOWLEDGE_CHUNK_POLICY_VERSION);
         }
     }
     clearChunks(docId) {
@@ -311,8 +363,12 @@ export class KnowledgeStore {
        VALUES (?,?,?,?,?,?,?,?,?,?,?,?)`).run(chunk.id, chunk.docId, chunk.index, headingPath, chunk.content, chunk.codeBlocks ?? null, chunk.tokenCount ?? null, metadata.kind, metadata.framework ?? null, JSON.stringify(metadata.apiIdentifiers), metadata.sourceUrl ?? null, metadata.contentHash);
     }
     insertEmbedding(id, embedding) {
+        this.assertEmbeddingProfile(embedding);
         const buffer = Buffer.from(embedding.buffer, embedding.byteOffset, embedding.byteLength);
-        this.db.prepare('INSERT OR REPLACE INTO knowledge_vec(id, embedding) VALUES (?, ?)').run(id, buffer);
+        this.db.transaction(() => {
+            this.db.prepare('INSERT OR REPLACE INTO knowledge_vec(id, embedding) VALUES (?, ?)').run(id, buffer);
+            this.putEmbeddingProfile(id);
+        })();
     }
     insertEmbeddingBatch(entries) {
         if (entries.length === 0)
@@ -320,7 +376,9 @@ export class KnowledgeStore {
         const insert = this.db.prepare('INSERT OR REPLACE INTO knowledge_vec(id, embedding) VALUES (?, ?)');
         this.db.transaction(() => {
             for (const { id, embedding } of entries) {
+                this.assertEmbeddingProfile(embedding);
                 insert.run(id, Buffer.from(embedding.buffer, embedding.byteOffset, embedding.byteLength));
+                this.putEmbeddingProfile(id);
             }
         })();
     }
@@ -338,14 +396,18 @@ export class KnowledgeStore {
         const insertVector = this.db.prepare('INSERT INTO knowledge_vec(id, embedding) VALUES (?, ?)');
         this.db.transaction(() => {
             this.upsertDoc(normalized.doc);
-            for (const { id } of oldIds)
+            for (const { id } of oldIds) {
                 deleteVector.run(id);
+                this.deleteEmbeddingProfile(id);
+            }
             this.clearChunks(input.doc.id);
             for (let index = 0; index < normalized.chunks.length; index++) {
                 const chunk = normalized.chunks[index];
                 const embedding = input.embeddings[index];
+                this.assertEmbeddingProfile(embedding);
                 insertChunk.run(chunk.id, chunk.docId, chunk.index, chunk.headingPath, chunk.content, chunk.codeBlocks ?? null, chunk.tokenCount ?? null, chunk.kind, chunk.framework ?? null, JSON.stringify(chunk.apiIdentifiers ?? []), chunk.sourceUrl ?? null, chunk.contentHash);
                 insertVector.run(chunk.id, Buffer.from(embedding.buffer, embedding.byteOffset, embedding.byteLength));
+                this.putEmbeddingProfile(chunk.id);
             }
         })();
     }
@@ -359,8 +421,10 @@ export class KnowledgeStore {
        VALUES (?,?,?,?,?,?,?,?,?,?,?,?)`);
         this.db.transaction(() => {
             this.upsertDoc(normalized.doc);
-            for (const { id } of oldIds)
+            for (const { id } of oldIds) {
                 deleteVector.run(id);
+                this.deleteEmbeddingProfile(id);
+            }
             this.clearChunks(input.doc.id);
             for (const chunk of normalized.chunks) {
                 insertChunk.run(chunk.id, chunk.docId, chunk.index, chunk.headingPath, chunk.content, chunk.codeBlocks ?? null, chunk.tokenCount ?? null, chunk.kind, chunk.framework ?? null, JSON.stringify(chunk.apiIdentifiers ?? []), chunk.sourceUrl ?? null, chunk.contentHash);
@@ -432,14 +496,54 @@ export class KnowledgeStore {
         const rows = this.db.prepare(`
       SELECT v.id, vec_distance_cosine(v.embedding, ?) as distance
       FROM knowledge_vec v
+      JOIN knowledge_vector_profiles p ON p.id = v.id
       JOIN knowledge_chunks c ON c.id = v.id
       JOIN knowledge_docs d ON d.id = c.doc_id
       WHERE d.status = 'active'
+      AND p.profile_hash = ? AND p.generation = ?
+      AND p.source_content_hash = c.content_hash
       ${sourceFilter}
       ORDER BY distance LIMIT ?
-    `).all(buffer, ...(sources ?? []), limit);
+    `).all(buffer, this.embeddingProfile.profileHash, this.embeddingProfile.generation, ...(sources ?? []), limit);
         return rows;
     }
+    getEmbeddingProfileState(source) {
+        const total = this.countChunks(source);
+        const sourceJoin = 'JOIN knowledge_vec v ON v.id = p.id JOIN knowledge_chunks c ON c.id = p.id JOIN knowledge_docs d ON d.id = c.doc_id';
+        const sourceWhere = source ? 'AND d.source = ?' : '';
+        const indexed = Number(this.db.prepare(`SELECT COUNT(*) AS count
+      FROM knowledge_vector_profiles p ${sourceJoin}
+      WHERE p.profile_hash = ? AND p.generation = ? AND p.source_content_hash = c.content_hash
+        AND d.status = 'active' ${sourceWhere}`).get(this.embeddingProfile.profileHash, this.embeddingProfile.generation, ...(source ? [source] : [])).count);
+        return {
+            status: this.embeddingProfile.dimension !== 384
+                ? 'dimension_mismatch'
+                : indexed < total ? 'backfill_pending' : 'ready',
+            profileHash: this.embeddingProfile.profileHash,
+            generation: this.embeddingProfile.generation,
+            indexed,
+            total,
+        };
+    }
+    putEmbeddingProfile(id) {
+        const source = this.db.prepare('SELECT content_hash, content FROM knowledge_chunks WHERE id = ?')
+            .get(id);
+        if (!source)
+            throw new Error(`EMBEDDING_SOURCE_MISSING:knowledge:${id}`);
+        const sourceContentHash = source.content_hash
+            || createHash('sha256').update(source.content).digest('hex');
+        this.db.prepare(`INSERT OR REPLACE INTO knowledge_vector_profiles
+      (id, profile_hash, generation, source_content_hash) VALUES (?, ?, ?, ?)`)
+            .run(id, this.embeddingProfile.profileHash, this.embeddingProfile.generation, sourceContentHash);
+    }
+    deleteEmbeddingProfile(id) {
+        this.db.prepare('DELETE FROM knowledge_vector_profiles WHERE id = ?').run(id);
+    }
+    assertEmbeddingProfile(embedding) {
+        if (embedding.length !== this.embeddingProfile.dimension || embedding.length !== 384) {
+            throw new Error(`EMBEDDING_DIMENSION_MISMATCH:${embedding.length}:${this.embeddingProfile.dimension}`);
+        }
+    }
     getChunk(id) {
         return this.db.prepare('SELECT * FROM knowledge_chunks WHERE id = ?').get(id);
     }
@@ -473,8 +577,8 @@ export class KnowledgeStore {
     `).all(...params, limit);
     }
     listMissingEmbeddingChunks(options = {}) {
-        const conditions = ["v.id IS NULL", "d.status = 'active'"];
-        const params = [];
+        const conditions = ["(v.id IS NULL OR p.id IS NULL OR p.source_content_hash <> c.content_hash)", "d.status = 'active'"];
+        const params = [this.embeddingProfile.profileHash, this.embeddingProfile.generation];
         if (options.source) {
             conditions.push('d.source = ?');
             params.push(options.source);
@@ -488,6 +592,8 @@ export class KnowledgeStore {
       FROM knowledge_chunks c
       JOIN knowledge_docs d ON d.id = c.doc_id
       LEFT JOIN knowledge_vec v ON v.id = c.id
+      LEFT JOIN knowledge_vector_profiles p ON p.id = v.id
+        AND p.profile_hash = ? AND p.generation = ?
       WHERE ${conditions.join(' AND ')}
       ORDER BY c.id
       LIMIT ?
@@ -509,14 +615,21 @@ export class KnowledgeStore {
         const row = source
             ? this.db.prepare(`
           SELECT COUNT(*) AS c FROM knowledge_vec v
+          JOIN knowledge_vector_profiles p ON p.id = v.id
           JOIN knowledge_chunks c ON c.id = v.id
-          JOIN knowledge_docs d ON d.id = c.doc_id WHERE d.source = ? AND d.status = 'active'
-        `).get(source)
+          JOIN knowledge_docs d ON d.id = c.doc_id
+          WHERE p.profile_hash = ? AND p.generation = ?
+            AND p.source_content_hash = c.content_hash
+            AND d.source = ? AND d.status = 'active'
+        `).get(this.embeddingProfile.profileHash, this.embeddingProfile.generation, source)
             : this.db.prepare(`
           SELECT COUNT(*) AS c FROM knowledge_vec v
+          JOIN knowledge_vector_profiles p ON p.id = v.id
           JOIN knowledge_chunks c ON c.id = v.id
-          JOIN knowledge_docs d ON d.id = c.doc_id WHERE d.status = 'active'
-        `).get();
+          JOIN knowledge_docs d ON d.id = c.doc_id
+          WHERE p.profile_hash = ? AND p.generation = ?
+            AND p.source_content_hash = c.content_hash AND d.status = 'active'
+        `).get(this.embeddingProfile.profileHash, this.embeddingProfile.generation);
         return row.c;
     }
     getCoverageBySource() {
@@ -530,7 +643,7 @@ export class KnowledgeStore {
     `).all();
         return rows;
     }
-    refreshSourceReadiness(expectedVersions = {}) {
+    refreshSourceReadiness(expectedVersions = {}, operationTimestamp = Date.now()) {
         const rows = this.db.prepare(`
       SELECT d.source,
         COUNT(DISTINCT d.id) AS documents,
@@ -569,7 +682,7 @@ export class KnowledgeStore {
                     : coverage < 0.95
                         ? 'vector_coverage'
                         : row.chunks === 0 ? 'empty_source' : null;
-                upsert.run(row.source, expectedVersions[row.source] ?? null, row.documents, row.chunks, row.vectors, coverage, row.last_refresh, status, failure, Date.now());
+                upsert.run(row.source, expectedVersions[row.source] ?? null, row.documents, row.chunks, row.vectors, coverage, row.last_refresh, status, failure, operationTimestamp);
             }
         })();
     }
@@ -619,21 +732,21 @@ export class KnowledgeStore {
         };
     }
     upsertProjectProfile(profile) {
-        const existing = this.db.prepare('SELECT profile_hash FROM knowledge_project_profiles WHERE project_root = ?').get(profile.projectRoot);
+        const existing = this.db.prepare('SELECT profile_hash FROM knowledge_project_profiles WHERE project_id = ?').get(profile.projectId);
         if (existing?.profile_hash === profile.profileHash)
             return false;
         this.db.prepare(`
-      INSERT INTO knowledge_project_profiles (project_root, profile_hash, profile_json, generated_at)
+      INSERT INTO knowledge_project_profiles (project_id, profile_hash, profile_json, generated_at)
       VALUES (?, ?, ?, ?)
-      ON CONFLICT(project_root) DO UPDATE SET
+      ON CONFLICT(project_id) DO UPDATE SET
         profile_hash = excluded.profile_hash,
         profile_json = excluded.profile_json,
         generated_at = excluded.generated_at
-    `).run(profile.projectRoot, profile.profileHash, JSON.stringify(profile), profile.generatedAt);
+    `).run(profile.projectId, profile.profileHash, JSON.stringify(profile), profile.generatedAt);
         return true;
     }
-    getProjectProfile(projectRoot) {
-        const row = this.db.prepare('SELECT profile_json FROM knowledge_project_profiles WHERE project_root = ?').get(projectRoot);
+    getProjectProfile(projectId) {
+        const row = this.db.prepare('SELECT profile_json FROM knowledge_project_profiles WHERE project_id = ?').get(projectId);
         return row ? JSON.parse(row.profile_json) : null;
     }
     upsertSourceSchema(schema, now = Date.now()) {
@@ -665,7 +778,7 @@ export class KnowledgeStore {
     activateCatalogEntry(input) {
         const activatedAt = input.activatedAt ?? Date.now();
         const snapshotId = `catalog:${createHash('sha256').update([
-            input.projectRoot,
+            input.projectId,
             input.entry.sourceId,
             input.entry.schemaId,
             input.entry.contentHash,
@@ -673,12 +786,12 @@ export class KnowledgeStore {
         return this.db.transaction(() => {
             const existing = this.db.prepare(`
         SELECT id, status, entry_json FROM knowledge_catalog_snapshots
-        WHERE project_root = ? AND source_id = ? AND content_hash = ?
-      `).get(input.projectRoot, input.entry.sourceId, input.entry.contentHash);
+        WHERE project_id = ? AND source_id = ? AND content_hash = ?
+      `).get(input.projectId, input.entry.sourceId, input.entry.contentHash);
             const active = this.db.prepare(`
         SELECT id FROM knowledge_catalog_snapshots
-        WHERE project_root = ? AND source_id = ? AND status = 'active'
-      `).get(input.projectRoot, input.entry.sourceId);
+        WHERE project_id = ? AND source_id = ? AND status = 'active'
+      `).get(input.projectId, input.entry.sourceId);
             if (existing?.status === 'active' && active?.id === existing.id) {
                 const entryJson = JSON.stringify(input.entry);
                 if (existing.entry_json !== entryJson) {
@@ -692,8 +805,8 @@ export class KnowledgeStore {
             }
             this.db.prepare(`
         UPDATE knowledge_catalog_snapshots SET status = 'inactive'
-        WHERE project_root = ? AND source_id = ? AND status = 'active'
-      `).run(input.projectRoot, input.entry.sourceId);
+        WHERE project_id = ? AND source_id = ? AND status = 'active'
+      `).run(input.projectId, input.entry.sourceId);
             if (existing) {
                 this.db.prepare(`
           UPDATE knowledge_catalog_snapshots
@@ -704,19 +817,19 @@ export class KnowledgeStore {
             }
             this.db.prepare(`
         INSERT INTO knowledge_catalog_snapshots
-          (id, project_root, profile_hash, source_id, schema_id, content_hash,
+          (id, project_id, profile_hash, source_id, schema_id, content_hash,
            entry_json, status, created_at, activated_at)
         VALUES (?, ?, ?, ?, ?, ?, ?, 'active', ?, ?)
-      `).run(snapshotId, input.projectRoot, input.profileHash, input.entry.sourceId, input.entry.schemaId, input.entry.contentHash, JSON.stringify(input.entry), activatedAt, activatedAt);
+      `).run(snapshotId, input.projectId, input.profileHash, input.entry.sourceId, input.entry.schemaId, input.entry.contentHash, JSON.stringify(input.entry), activatedAt, activatedAt);
             return { snapshotId, changed: true };
         })();
     }
-    listActiveCatalogEntries(projectRoot) {
+    listActiveCatalogEntries(projectId) {
         return this.db.prepare(`
       SELECT id, entry_json FROM knowledge_catalog_snapshots
-      WHERE project_root = ? AND status = 'active'
+      WHERE project_id = ? AND status = 'active'
       ORDER BY source_id
-    `).all(projectRoot).map(row => ({
+    `).all(projectId).map(row => ({
             ...JSON.parse(row.entry_json),
             activeRevisionId: row.id,
         }));
@@ -724,7 +837,7 @@ export class KnowledgeStore {
     beginRefreshJob(input) {
         const now = input.now ?? Date.now();
         const id = `refresh:${createHash('sha256').update([
-            input.projectRoot,
+            input.projectId,
             input.sourceId,
             input.inputContentHash,
         ].join('\0')).digest('hex').slice(0, 32)}`;
@@ -733,16 +846,16 @@ export class KnowledgeStore {
             return { id, status: 'completed', resumed: false };
         const active = this.db.prepare(`
       SELECT id FROM knowledge_catalog_snapshots
-      WHERE project_root = ? AND source_id = ? AND status = 'active'
-    `).get(input.projectRoot, input.sourceId);
+      WHERE project_id = ? AND source_id = ? AND status = 'active'
+    `).get(input.projectId, input.sourceId);
         this.db.prepare(`
       INSERT INTO knowledge_refresh_jobs
-        (id, project_root, source_id, input_content_hash, previous_snapshot_id,
+        (id, project_id, source_id, input_content_hash, previous_snapshot_id,
          status, created_at, updated_at)
       VALUES (?, ?, ?, ?, ?, 'compiling', ?, ?)
       ON CONFLICT(id) DO UPDATE SET
         status = 'compiling', error = NULL, updated_at = excluded.updated_at
-    `).run(id, input.projectRoot, input.sourceId, input.inputContentHash, active?.id ?? null, now, now);
+    `).run(id, input.projectId, input.sourceId, input.inputContentHash, active?.id ?? null, now, now);
         return { id, status: 'compiling', resumed: existing !== undefined };
     }
     completeRefreshJob(id, outputSnapshotId, now = Date.now()) {
@@ -765,13 +878,13 @@ export class KnowledgeStore {
     recordCoverageGap(gap) {
         const result = this.db.prepare(`
       INSERT INTO knowledge_coverage_gaps
-        (id, project_root, source_id, kind, gap_json, detected_at, resolved_at)
+        (id, project_id, source_id, kind, gap_json, detected_at, resolved_at)
       VALUES (?, ?, ?, ?, ?, ?, ?)
       ON CONFLICT(id) DO UPDATE SET
         gap_json = excluded.gap_json,
         detected_at = excluded.detected_at,
         resolved_at = excluded.resolved_at
-    `).run(gap.id, gap.projectRoot, gap.sourceId, gap.kind, JSON.stringify(gap), gap.detectedAt, gap.resolvedAt ?? null);
+    `).run(gap.id, gap.projectId, gap.sourceId, gap.kind, JSON.stringify(gap), gap.detectedAt, gap.resolvedAt ?? null);
         return result.changes === 1;
     }
     resolveCoverageGap(id, resolvedAt = Date.now()) {
@@ -784,18 +897,18 @@ export class KnowledgeStore {
       UPDATE knowledge_coverage_gaps SET resolved_at = ?, gap_json = ? WHERE id = ?
     `).run(resolvedAt, JSON.stringify(gap), id).changes === 1;
     }
-    listCoverageGaps(projectRoot, options = {}) {
+    listCoverageGaps(projectId, options = {}) {
         const sql = options.includeResolved
-            ? 'SELECT gap_json FROM knowledge_coverage_gaps WHERE project_root = ? ORDER BY detected_at DESC, id'
-            : 'SELECT gap_json FROM knowledge_coverage_gaps WHERE project_root = ? AND resolved_at IS NULL ORDER BY detected_at DESC, id';
-        return this.db.prepare(sql).all(projectRoot).map(row => JSON.parse(row.gap_json));
+            ? 'SELECT gap_json FROM knowledge_coverage_gaps WHERE project_id = ? ORDER BY detected_at DESC, id'
+            : 'SELECT gap_json FROM knowledge_coverage_gaps WHERE project_id = ? AND resolved_at IS NULL ORDER BY detected_at DESC, id';
+        return this.db.prepare(sql).all(projectId).map(row => JSON.parse(row.gap_json));
     }
     upsertNormalizedPage(page) {
         if (page.provenance.contentHash !== page.contentHash || page.provenance.immutable !== true) {
             throw new Error(`Knowledge page ${page.id} has invalid immutable provenance`);
         }
-        const existing = this.db.prepare('SELECT project_root, source_id, content_hash FROM knowledge_pages WHERE id = ?').get(page.id);
-        if (existing && (existing.project_root !== page.projectRoot || existing.source_id !== page.sourceId)) {
+        const existing = this.db.prepare('SELECT project_id, source_id, content_hash FROM knowledge_pages WHERE id = ?').get(page.id);
+        if (existing && (existing.project_id !== page.projectId || existing.source_id !== page.sourceId)) {
             throw new Error(`Knowledge page ${page.id} cannot move across project or source boundaries`);
         }
         if (existing?.content_hash === page.contentHash)
@@ -803,7 +916,7 @@ export class KnowledgeStore {
         this.db.transaction(() => {
             this.db.prepare(`
         INSERT INTO knowledge_pages
-          (id, project_root, source_id, source_schema_id, title, markdown, frontmatter,
+          (id, project_id, source_id, source_schema_id, title, markdown, frontmatter,
            entities, symbols, links, version, content_hash, provenance, status, compiled_at)
         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', ?)
         ON CONFLICT(id) DO UPDATE SET
@@ -819,14 +932,14 @@ export class KnowledgeStore {
           provenance = excluded.provenance,
           status = 'active',
           compiled_at = excluded.compiled_at
-      `).run(page.id, page.projectRoot, page.sourceId, page.sourceSchemaId, page.title, page.markdown, JSON.stringify(page.frontmatter), JSON.stringify(page.entities), JSON.stringify(page.symbols), JSON.stringify(page.links), page.version ?? null, page.contentHash, JSON.stringify(page.provenance), page.compiledAt);
+      `).run(page.id, page.projectId, page.sourceId, page.sourceSchemaId, page.title, page.markdown, JSON.stringify(page.frontmatter), JSON.stringify(page.entities), JSON.stringify(page.symbols), JSON.stringify(page.links), page.version ?? null, page.contentHash, JSON.stringify(page.provenance), page.compiledAt);
             this.replacePageLinks(page);
         })();
         return true;
     }
-    replaceCompiledPage(page, chunks) {
+    replaceCompiledPage(page, chunks, operationTimestamp = page.compiledAt) {
         if (chunks.some(chunk => chunk.pageId !== page.id
-            || chunk.projectRoot !== page.projectRoot
+            || chunk.projectId !== page.projectId
             || chunk.sourceId !== page.sourceId
             || chunk.provenance.contentHash !== page.contentHash)) {
             throw new Error(`Compiled chunks for ${page.id} do not share page provenance`);
@@ -837,7 +950,7 @@ export class KnowledgeStore {
       INSERT INTO knowledge_chunks
         (id, doc_id, chunk_index, heading_path, content, code_blocks, token_count,
          chunk_kind, framework, api_identifiers, source_url, content_hash,
-         page_id, project_root, heading_breadcrumbs, embedding_text, original_start,
+         page_id, project_id, heading_breadcrumbs, embedding_text, original_start,
          original_end, entities, symbols, links, oversized_atomic, provenance, analysis_terms)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `);
@@ -851,9 +964,12 @@ export class KnowledgeStore {
                 version: page.version,
                 contentHash: page.contentHash,
                 chunkPolicyVersion: KNOWLEDGE_CHUNK_POLICY_VERSION,
+                fetchedAt: operationTimestamp,
             });
-            for (const row of oldIds)
+            for (const row of oldIds) {
                 deleteVector.run(row.id);
+                this.deleteEmbeddingProfile(row.id);
+            }
             this.db.prepare('DELETE FROM knowledge_chunks WHERE page_id = ? OR doc_id = ?')
                 .run(page.id, page.id);
             const insertEntity = this.db.prepare(`
@@ -865,7 +981,7 @@ export class KnowledgeStore {
           (page_id, chunk_id, symbol, normalized_symbol) VALUES (?, ?, ?, ?)
       `);
             for (const chunk of chunks) {
-                insert.run(chunk.id, page.id, chunk.index, chunk.headingBreadcrumbs.join(' > '), chunk.content, extractCodeBlocks(chunk.content) || null, estimateStoredTokens(chunk.content), chunk.kind, page.sourceId, JSON.stringify(chunk.symbols), page.provenance.sourceUri, chunk.contentHash, page.id, page.projectRoot, JSON.stringify(chunk.headingBreadcrumbs), chunk.embeddingText, chunk.originalStart, chunk.originalEnd, JSON.stringify(chunk.entities), JSON.stringify(chunk.symbols), JSON.stringify(chunk.links), chunk.oversizedAtomic ? 1 : 0, JSON.stringify(chunk.provenance), JSON.stringify(chunk.analysisTerms));
+                insert.run(chunk.id, page.id, chunk.index, chunk.headingBreadcrumbs.join(' > '), chunk.content, extractCodeBlocks(chunk.content) || null, estimateStoredTokens(chunk.content), chunk.kind, page.sourceId, JSON.stringify(chunk.symbols), page.provenance.sourceUri, chunk.contentHash, page.id, page.projectId, JSON.stringify(chunk.headingBreadcrumbs), chunk.embeddingText, chunk.originalStart, chunk.originalEnd, JSON.stringify(chunk.entities), JSON.stringify(chunk.symbols), JSON.stringify(chunk.links), chunk.oversizedAtomic ? 1 : 0, JSON.stringify(chunk.provenance), JSON.stringify(chunk.analysisTerms));
                 for (const entity of uniqueStrings(chunk.entities)) {
                     insertEntity.run(page.id, chunk.id, entity, normalizeKnowledgeLookupKey(entity));
                 }
@@ -875,7 +991,7 @@ export class KnowledgeStore {
             }
         })();
     }
-    replaceKnowledgeAnalysisManifest(manifest, quarantined) {
+    replaceKnowledgeAnalysisManifest(manifest, quarantined, operationTimestamp = Date.now()) {
         this.db.prepare(`
       INSERT INTO knowledge_analysis_manifests
         (source_id, content_hash, version, manifest_json, quarantined_json, created_at)
@@ -884,38 +1000,38 @@ export class KnowledgeStore {
         version=excluded.version,
         manifest_json=excluded.manifest_json,
         quarantined_json=excluded.quarantined_json
-    `).run(manifest.sourceId, manifest.contentHash, manifest.version, JSON.stringify(manifest), JSON.stringify(quarantined), Date.now());
+    `).run(manifest.sourceId, manifest.contentHash, manifest.version, JSON.stringify(manifest), JSON.stringify(quarantined), operationTimestamp);
     }
     recordImmutableRawSource(input) {
         const metadata = JSON.stringify(input.metadata ?? {});
         const existing = this.db.prepare(`
       SELECT source_uri, source_version, metadata_json, retrieved_at
-      FROM knowledge_raw_sources WHERE project_root = ? AND source_id = ? AND content_hash = ?
-    `).get(input.projectRoot, input.sourceId, input.contentHash);
+      FROM knowledge_raw_sources WHERE project_id = ? AND source_id = ? AND content_hash = ?
+    `).get(input.projectId, input.sourceId, input.contentHash);
         if (existing) {
             if (existing.source_uri !== input.sourceUri || existing.source_version !== (input.sourceVersion ?? null)
-                || existing.metadata_json !== metadata || existing.retrieved_at !== input.retrievedAt) {
+                || existing.metadata_json !== metadata) {
                 throw new Error('KNOWLEDGE_RAW_SOURCE_IMMUTABILITY_CONFLICT');
             }
             return false;
         }
         return this.db.prepare(`
       INSERT INTO knowledge_raw_sources
-        (project_root, source_id, content_hash, source_uri, source_version, metadata_json, retrieved_at)
+        (project_id, source_id, content_hash, source_uri, source_version, metadata_json, retrieved_at)
       VALUES (?, ?, ?, ?, ?, ?, ?)
-    `).run(input.projectRoot, input.sourceId, input.contentHash, input.sourceUri, input.sourceVersion ?? null, metadata, input.retrievedAt).changes === 1;
+    `).run(input.projectId, input.sourceId, input.contentHash, input.sourceUri, input.sourceVersion ?? null, metadata, input.retrievedAt).changes === 1;
     }
     publishCompiledSource(input) {
         this.db.transaction(() => {
-            this.replaceKnowledgeAnalysisManifest(input.manifest, input.quarantined);
-            this.replaceCompiledPage(input.page, input.chunks);
+            this.replaceKnowledgeAnalysisManifest(input.manifest, input.quarantined, input.operationTimestamp);
+            this.replaceCompiledPage(input.page, input.chunks, input.operationTimestamp);
         })();
     }
     getNormalizedPage(id) {
         const row = this.db.prepare("SELECT * FROM knowledge_pages WHERE id = ? AND status = 'active'").get(id);
         return row ? {
             id: row.id,
-            projectRoot: row.project_root,
+            projectId: row.project_id,
             sourceId: row.source_id,
             sourceSchemaId: row.source_schema_id,
             title: row.title,
@@ -930,6 +1046,102 @@ export class KnowledgeStore {
             compiledAt: row.compiled_at,
         } : null;
     }
+    transaction(operation) {
+        return this.db.transaction(operation)();
+    }
+    getSourceAggregate(identityHash) {
+        const row = this.db.prepare('SELECT aggregate_json FROM knowledge_source_aggregates_v1 WHERE identity_hash = ?').get(identityHash);
+        return row ? JSON.parse(row.aggregate_json) : null;
+    }
+    appendSourceTransition(input) {
+        return this.db.transaction(() => {
+            const existingEvent = this.db.prepare('SELECT transition_json FROM knowledge_source_events_v1 WHERE event_id = ?').get(input.transition.eventId);
+            const transitionJson = JSON.stringify(input.transition);
+            if (existingEvent) {
+                if (existingEvent.transition_json !== transitionJson) {
+                    throw new Error('KNOWLEDGE_SOURCE_EVENT_IDEMPOTENCY_CONFLICT');
+                }
+                return { replayed: true };
+            }
+            const current = this.getSourceAggregate(input.aggregate.identity.identityHash);
+            if ((current?.revision ?? 0) + 1 !== input.aggregate.revision
+                || input.transition.sequence !== input.aggregate.revision) {
+                throw new Error('KNOWLEDGE_SOURCE_SEQUENCE_CONFLICT');
+            }
+            this.db.prepare(`
+        INSERT INTO knowledge_source_aggregates_v1
+          (identity_hash, project_id, source_id, state, revision, content_hash,
+           aggregate_hash, aggregate_json, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(identity_hash) DO UPDATE SET
+          state = excluded.state,
+          revision = excluded.revision,
+          content_hash = excluded.content_hash,
+          aggregate_hash = excluded.aggregate_hash,
+          aggregate_json = excluded.aggregate_json,
+          updated_at = excluded.updated_at
+      `).run(input.aggregate.identity.identityHash, input.aggregate.identity.projectId, input.aggregate.identity.sourceId, input.aggregate.state, input.aggregate.revision, input.aggregate.contentHash ?? null, input.aggregate.aggregateHash, JSON.stringify(input.aggregate), input.aggregate.updatedAt);
+            this.db.prepare(`
+        INSERT INTO knowledge_source_events_v1
+          (event_id, identity_hash, sequence, transition_json, created_at)
+        VALUES (?, ?, ?, ?, ?)
+      `).run(input.transition.eventId, input.transition.identityHash, input.transition.sequence, transitionJson, input.transition.createdAt);
+            return { replayed: false };
+        })();
+    }
+    insertKnowledgeClaims(claims) {
+        if (claims.length === 0)
+            return 0;
+        const insert = this.db.prepare(`
+      INSERT OR IGNORE INTO knowledge_claims_v1
+        (claim_id, identity_hash, source_id, page_id, status, source_content_hash,
+         claim_hash, claim_json, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        return this.db.transaction(() => claims.reduce((count, claim) => count + insert.run(claim.claimId, claim.identityHash, claim.sourceId, claim.pageId, claim.status, claim.sourceContentHash, claim.claimHash, JSON.stringify(claim), claim.effectiveAt).changes, 0))();
+    }
+    listKnowledgeClaims(sourceId) {
+        const rows = (sourceId
+            ? this.db.prepare('SELECT claim_json FROM knowledge_claims_v1 WHERE source_id = ? ORDER BY created_at, claim_id').all(sourceId)
+            : this.db.prepare('SELECT claim_json FROM knowledge_claims_v1 ORDER BY created_at, claim_id').all());
+        return rows.map(row => JSON.parse(row.claim_json));
+    }
+    quarantineSourceRevision(input) {
+        const updatedAt = input.updatedAt ?? Date.now();
+        return this.db.transaction(() => ({
+            pagesQuarantined: this.db.prepare(`
+        UPDATE knowledge_pages SET status = 'quarantined'
+        WHERE id = ? AND project_id = ? AND content_hash = ? AND status = 'active'
+      `).run(input.pageId, input.projectId, input.contentHash).changes,
+            documentsDeactivated: this.db.prepare(`
+        UPDATE knowledge_docs SET status = 'inactive'
+        WHERE id = ? AND content_hash = ? AND status = 'active'
+      `).run(input.pageId, input.contentHash).changes,
+            catalogSnapshotsDeactivated: this.db.prepare(`
+        UPDATE knowledge_catalog_snapshots SET status = 'inactive'
+        WHERE project_id = ? AND source_id = ? AND content_hash = ? AND status = 'active'
+      `).run(input.projectId, input.sourceId, input.contentHash).changes,
+            readinessSourcesDegraded: this.db.prepare(`
+        INSERT INTO knowledge_source_readiness
+          (source, expected_version, documents, chunks, vectors, coverage, last_refresh,
+           status, failure_category, updated_at)
+        VALUES (?, ?, 0, 0, 0, 0, NULL, 'degraded', ?, ?)
+        ON CONFLICT(source) DO UPDATE SET
+          status = 'degraded', failure_category = excluded.failure_category,
+          updated_at = excluded.updated_at
+      `).run(input.sourceId, input.expectedVersion ?? null, input.reason.slice(0, 500), updatedAt).changes,
+        }))();
+    }
+    recordKnowledgeMaintenanceRun(input) {
+        this.db.prepare(`
+      INSERT INTO knowledge_maintenance_runs (id, manifest_json, created_at)
+      VALUES (?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET manifest_json = excluded.manifest_json
+    `).run(input.id, JSON.stringify(input.manifest), input.createdAt);
+    }
+    rebuildFullTextIndex() {
+        this.db.prepare("INSERT INTO knowledge_fts(knowledge_fts) VALUES('rebuild')").run();
+    }
     replacePageLinks(page) {
         this.db.prepare('DELETE FROM knowledge_entity_links WHERE page_id = ?').run(page.id);
         this.db.prepare('DELETE FROM knowledge_symbol_links WHERE page_id = ?').run(page.id);