dsh-data-domain-knowledge 0.1.0-alpha.11 → 0.1.0-alpha.13

package/lib/types/runtime.js

@@ -13,6 +13,7 @@ import { MAX_LOG_ITEMS, OperationLog, operationId } from './oplog.js';
 import { ExtractionRunStore, extractionRunId } from './extraction-runs.js';
 import { AxisRegistry, normalizeAxisName } from './axis-registry.js';
 import { KNOWLEDGE_STATE_LABEL, KnowledgeStore } from './knowledge.js';
+import { compositeEventIdentity, eventEntityFromRecords } from './events.js';
 import { buildAliasIndex, candidateEntityId, extractCandidates, normalizeCandidates, RELATES_TO } from './extract.js';
 import { skeletonBody } from './extract-model.js';
 import { applyTrialAxisResolution, normalizeKnowledge, runWikiTrial, trialSummary } from './wiki-trial.js';
@@ -22,14 +23,22 @@ import { FTS_FILE, loadSqlite, segment } from './fts.js';
 import { attachImagesToKnowledge, insertImage, planSourceImages } from './source-images.js';
 import { buildWikiIndex, cardKey, deadLinksOf, planRelated, relatedEntriesOf, stripRelatedSection, RELATED_METADATA_KEY, } from './wiki-finalize.js';
 import { applyRerank, applyThreshold, evidenceExcerpts, graphBoost, matchOf, noteIndexText, reviewWeight, rrfFuse, tokenSet } from './recall-rank.js';
-import { ASSETS_DIR, KNOWLEDGE_DB_FILE, SOURCE_RAW_DIR, defaultAgentRoot, knowledgeBaseRoot } from './layout.js';
+import { ASSETS_DIR, KNOWLEDGE_DB_FILE, PUBLISHED_IMAGE_MARKER, SOURCE_RAW_DIR, defaultAgentRoot, knowledgeBaseRoot } from './layout.js';
 import { KnowledgeDb } from './store/knowledge-db.js';
 import { exportKnowledgeTree as exportTree, migrateKnowledgeTree } from './store/migrate.js';
+import { COMPILE_SNAPSHOT } from './compiler/snapshot.js';
+import { decodeVectorIndex } from './retrieval/vector-index.js';
+import { liveGraphKeys, visibleGraph } from './retrieval/visibility.js';
+import { embeddingFingerprint } from './compiler/embedding-identity.js';
 import { DerivedDb, DERIVED_DB_FILE } from './store/derived.js';
 import { cardVersions as viewCardVersions, documentDetail as viewDocumentDetail, documentList as viewDocumentList, documentVersions as viewDocumentVersions } from './store/views.js';
+import { assessKnowledgeEvidence, hasCurrentSupport } from './source-evidence.js';
+import { redirectAxisReferences } from './store/axis-references.js';
 import { unlinkIfExists, writeTextAtomic } from './fs-atomic.js';
 import { envelopeFailure, envelopeSuccess } from 'dsh-data-contracts/envelope';
 import { analyzeQuery, relationCandidates } from './query-analysis.js';
+import { readModelSelection, selectedEmbedding } from './environment/selection.js';
+import { rerankModel as rerankModelOption } from './environment/model-catalog.js';
 // **知识树只有三段**（v1.1 起）：`01_source_raw` / `02_wiki` / `03_compiled`。
 //
 // 撤掉的两段，理由都写在这里，避免下一个人重新加回来：
@@ -405,12 +414,18 @@ function withTitleAlias(metadata, previousTitle, nextTitle) {
  * 同一句话在上下文里出现很多遍。完整出处在知识接口里。
  */
 function recallKnowledgeOf(row, section) {
-    const first = row.sources.find(source => source.quote.trim() !== '') ?? row.sources[0];
+    const first = row.sources.find(source => source.evidenceStatus === 'current' && source.quoteInCurrentVersion)
+        ?? row.sources.find(source => source.quote.trim() !== '') ?? row.sources[0];
     return {
         id: row.id,
         text: row.text,
         state: row.status,
         section,
+        claimVerification: 'unverified',
+        requiresReview: !hasCurrentSupport(row),
+        ...(first?.evidenceStatus ? { evidenceStatus: first.evidenceStatus } : {}),
+        ...(first?.toVersion === undefined ? {} : { sourceVersion: first.toVersion }),
+        ...(first?.currentVersion === undefined ? {} : { currentSourceVersion: first.currentVersion }),
         ...(first?.quote ? { quote: first.quote } : {}),
         ...(first?.documentId ? { sourceId: first.documentId } : {}),
         ...(first && first.headingPath.length > 0 ? { headingPath: first.headingPath } : {}),
@@ -701,42 +716,6 @@ function withEventReferences(content, rawRefs, eventsById) {
     });
     return `${base ? `${base}\n\n` : ''}## 关联 Event\n\n${bullets.join('\n')}`;
 }
-function eventEntityFromRecords(input) {
-    const { id, identityKey, identityType, records } = input;
-    const first = records[0];
-    const firstCoordinate = records.find(record => record.coordinateIds.objectId || record.coordinateIds.actionId || record.coordinateIds.sceneId);
-    const sources = new Map();
-    for (const record of records) {
-        for (const source of record.sources)
-            sources.set(`${source.documentId}\u0001${source.quote}`, source);
-    }
-    return {
-        id,
-        identityKey,
-        identityType,
-        externalId: records.find(record => record.externalId)?.externalId ?? null,
-        title: first?.title ?? id,
-        summary: records.find(record => record.summary.trim())?.summary ?? first?.title ?? id,
-        coordinate: {
-            object: records.find(record => record.coordinate.object)?.coordinate.object ?? null,
-            action: records.find(record => record.coordinate.action)?.coordinate.action ?? null,
-            scene: records.find(record => record.coordinate.scene)?.coordinate.scene ?? null,
-        },
-        coordinateIds: firstCoordinate?.coordinateIds ?? { objectId: '', actionId: '', sceneId: '' },
-        occurredAt: records.find(record => record.occurredAt)?.occurredAt ?? null,
-        symptom: records.find(record => record.symptom)?.symptom ?? null,
-        timeline: records.flatMap(record => record.timeline.map(step => ({ ...step, sourceId: record.sourceId }))),
-        rootCauses: records.flatMap(record => record.rootCause
-            ? [{ text: record.rootCause, status: record.rootCauseStatus, sourceId: record.sourceId }]
-            : []),
-        outcomes: records.flatMap(record => record.outcome ? [{ text: record.outcome, sourceId: record.sourceId }] : []),
-        missing: [...new Set(records.flatMap(record => record.missing))],
-        sources: [...sources.values()],
-        records,
-        createdAt: input.createdAt,
-        updatedAt: input.updatedAt ?? new Date().toISOString(),
-    };
-}
 /** 把 `incoming` 按小节折进 `existing`；结构对不上时整段追加。 */
 function foldBody(existing, incoming) {
     if (!existing)
@@ -1410,8 +1389,8 @@ class JsonLineWorker {
 /**
  * 解析三个「家当」路径（0029）。
  *
- * 优先级：**配置里显式写的值**（由构造函数处理）> `<agentRoot>/resource/…`（存在时）
- * > 兜底（`python3` / HF 模型名）。
+ * 资源目录内的隔离解释器优先于 DSH_PYTHON；自定义配置路径仍由构造函数处理。
+ * 未准备资源时回退到 DSH_PYTHON、`python3` 或 HF 模型名。
  *
  * `modelId` 把本地模型的**身份**与它的位置解耦，避免同一 Agent 根目录下的
  * resource 目录变化导致向量清单误判为配置不匹配。
@@ -1425,15 +1404,22 @@ function resolveResources(resourceRoot) {
         return fallback;
     };
     const python = firstExisting([
+        root && process.platform === 'win32' ? join(root, 'python', 'Scripts', 'python.exe') : undefined,
         root ? join(root, 'python', 'bin', 'python') : undefined,
-    ], 'python3');
+    ], process.env.DSH_PYTHON || 'python3');
+    const selected = selectedEmbedding(root);
+    const selection = root ? readModelSelection(root) : undefined;
+    const selectedRerank = root && selection ? join(root, 'models', rerankModelOption(selection.rerank).directory) : undefined;
     const embeddingModel = firstExisting([
+        selected?.path,
         root ? join(root, 'models', PREFERRED_LOCAL_EMBEDDING_MODEL_DIR) : undefined,
         root ? join(root, 'models', LOCAL_EMBEDDING_MODEL_DIR) : undefined,
     ], FALLBACK_EMBEDDING_MODEL);
     const rerankModel = firstExisting([
+        selectedRerank,
         root ? join(root, 'models', LOCAL_RERANK_MODEL_DIR) : undefined,
     ], FALLBACK_RERANK_MODEL);
+    const embeddingDimension = selected?.path && embeddingModel === selected.path ? selected.dimension : undefined;
     const modelId = (path) => {
         for (const base of [root]) {
             if (!base || !path.startsWith(`${base}${sep}`))
@@ -1443,7 +1429,13 @@ function resolveResources(resourceRoot) {
         }
         return path;
     };
-    return { python, embeddingModel, rerankModel, modelId };
+    return { python, embeddingModel, rerankModel, embeddingDimension, modelId };
+}
+/** An inherited DSH_PYTHON value selects the base interpreter, not the dependency environment. */
+function resolveConfiguredPython(configured, resourcePython) {
+    const selected = configured?.trim();
+    const hostPython = process.env.DSH_PYTHON?.trim();
+    return selected && selected !== hostPython ? selected : resourcePython;
 }
 class CompileTaskCancelledError extends Error {
     constructor() {
@@ -1504,6 +1496,7 @@ function blankProgress(runId, only, startedAt, state = 'running', queuedAt = sta
     };
 }
 export class KnowledgeRuntime {
+    environmentGuard;
     /** 当前生效的配置。volatile 改动会就地合并进来（见 `updateConfig`），所以它不是只读的。 */
     config;
     rootDir;
@@ -1599,6 +1592,8 @@ export class KnowledgeRuntime {
      */
     derived;
     derivedProblem;
+    publication;
+    recallSnapshotCache;
     /** 段内布局整理是否已经跑过（每个 runtime 一次）。 */
     segmentsOrganized = false;
     /**
@@ -1632,6 +1627,7 @@ export class KnowledgeRuntime {
     vectorIndex = null;
     vectorError;
     embeddingWorker = null;
+    embeddingWorkerFingerprint;
     /** Separate process so a rerank model failure cannot take embeddings down. */
     rerankWorker = null;
     /** Cache the first rerank failure; do not respawn a doomed model per recall. */
@@ -1650,6 +1646,7 @@ export class KnowledgeRuntime {
      * 收到一次全量重编码。清单该记「是哪一个模型」，不是「它在哪」。
      */
     embeddingModelId;
+    resourceRoot;
     /**
      * 这个知识库的记忆段（0032）。
      *
@@ -1671,9 +1668,13 @@ export class KnowledgeRuntime {
         this.extractionNoteProvider = options.extractionNote;
         this.memoryDir = options.memoryRoot ? resolve(options.memoryRoot) : join(this.rootDir, '04_memory');
         this.staticModelCall = options.modelCall;
+        this.environmentGuard = options.environmentGuard;
         this.modelSeamProvider = options.modelSeam;
+        this.resourceRoot = options.resourceRoot;
         const resources = resolveResources(options.resourceRoot);
-        this.pythonPath = config.python?.trim() || resources.python;
+        if (!this.config.embeddingModel?.trim() && resources.embeddingDimension)
+            this.config.embeddingDimension = resources.embeddingDimension;
+        this.pythonPath = resolveConfiguredPython(config.python, resources.python);
         this.embeddingModelPath = config.embeddingModel?.trim() || resources.embeddingModel;
         this.rerankModelPath = config.rerankModel?.trim() || resources.rerankModel;
         this.embeddingModelId = resources.modelId(this.embeddingModelPath);
@@ -1684,6 +1685,9 @@ export class KnowledgeRuntime {
      * **每次现问**，不是在构造时定死：插件 apply 的时刻早于 `agent-default-model` 挂载，
      * 那时问一次只会得到 undefined，而定死之后就再也不会变（见 `modelCallProvider`）。
      */
+    embeddingFingerprint() {
+        return embeddingFingerprint(this.embeddingModelPath, this.resourceRoot, this.config.embeddingProvider === 'ollama' ? this.config.embeddingBaseUrl : undefined);
+    }
     modelSeamNow() {
         if (this.modelSeamProvider)
             return this.modelSeamProvider(this.baseId);
@@ -1708,10 +1712,16 @@ export class KnowledgeRuntime {
     updateConfig(patch) {
         const previous = this.config;
         this.config = { ...previous, ...patch };
+        const resources = resolveResources(this.resourceRoot);
+        // A managed model preset owns its output dimension. Custom model paths keep
+        // the advanced dimension setting from the plugin config.
+        if (!this.config.embeddingModel?.trim() && resources.embeddingDimension)
+            this.config.embeddingDimension = resources.embeddingDimension;
         const modelChanged = previous.embeddingProvider !== this.config.embeddingProvider ||
             previous.embeddingModel !== this.config.embeddingModel ||
             previous.embeddingDimension !== this.config.embeddingDimension ||
             previous.embeddingDevice !== this.config.embeddingDevice ||
+            previous.embeddingBaseUrl !== this.config.embeddingBaseUrl ||
             previous.python !== this.config.python;
         const rerankChanged = previous.rerankProvider !== this.config.rerankProvider ||
             previous.rerankModel !== this.config.rerankModel ||
@@ -1722,18 +1732,19 @@ export class KnowledgeRuntime {
             // 旧索引建在旧模型/旧维度下，留着它只会给出没有意义的相似度。
             this.vectorIndex = null;
             this.vectorError = undefined;
+            this.encoderHealth = undefined;
         }
         if (rerankChanged) {
             this.rerankWorker?.close();
             this.rerankWorker = null;
             this.rerankUnavailable = undefined;
         }
-        if (patch.python !== undefined)
-            this.pythonPath = patch.python.trim() || this.pythonPath;
+        this.pythonPath = resolveConfiguredPython(this.config.python, resources.python);
         if (patch.embeddingModel !== undefined)
-            this.embeddingModelPath = patch.embeddingModel.trim() || this.embeddingModelPath;
+            this.embeddingModelPath = patch.embeddingModel.trim() || resources.embeddingModel;
         if (patch.rerankModel !== undefined)
-            this.rerankModelPath = patch.rerankModel.trim() || this.rerankModelPath;
+            this.rerankModelPath = patch.rerankModel.trim() || resources.rerankModel;
+        this.embeddingModelId = resources.modelId(this.embeddingModelPath);
     }
     // ------------------------------------------------- 固定卡片模板
     /** 当前系统固定的卡片模板；不再按知识库维护卡片类型注册表。 */
@@ -2200,22 +2211,7 @@ export class KnowledgeRuntime {
         if (this.vectorIndex)
             return this.vectorIndex;
         try {
-            const loaded = (await this.derivedHandle())?.vectorIndex();
-            if (loaded === undefined)
-                return null;
-            const manifest = loaded.manifest;
-            if (manifest.quantization !== VECTOR_QUANTIZATION || !Number.isInteger(manifest.dimension) || !Array.isArray(manifest.items))
-                return null;
-            // 编码实现换了 → 库里这份索引不是「同一个东西」，当作不存在（于是 recall 会如实降级，
-            // 而不是拿一份用别的编码器算出来的向量去排序）。
-            if (manifest.encoder !== ENCODER_FINGERPRINT)
-                return null;
-            const binary = loaded.binary;
-            const int8 = loaded.int8;
-            const binaryWidth = Math.ceil(manifest.dimension / 8);
-            if (manifest.itemCount !== manifest.items.length || binary.length !== manifest.itemCount * binaryWidth || int8.length !== manifest.itemCount * manifest.dimension)
-                return null;
-            this.vectorIndex = { manifest, binary, int8 };
+            this.vectorIndex = decodeVectorIndex((await this.derivedHandle())?.vectorIndex(), ENCODER_FINGERPRINT);
             return this.vectorIndex;
         }
         catch {
@@ -2261,6 +2257,13 @@ export class KnowledgeRuntime {
     async encodeEmbeddings(inputs) {
         if (this.config.embeddingProvider === 'none')
             throw new Error('EMBEDDING_DISABLED');
+        const fingerprint = this.embeddingFingerprint();
+        if (fingerprint !== this.embeddingWorkerFingerprint) {
+            this.embeddingWorker?.close();
+            this.embeddingWorker = null;
+            this.embeddingWorkerFingerprint = fingerprint;
+            this.encoderHealth = undefined;
+        }
         // Keep each JSON response bounded for large stores. The WeMM process is
         // persistent, so chunking does not reload the 1.8GB model between chunks.
         const chunkSize = Math.max(1, this.config.embeddingBatchSize * 64);
@@ -2289,10 +2292,23 @@ export class KnowledgeRuntime {
         return { vectors, device };
     }
     close() {
+        for (const task of this.compileTasks.values()) {
+            if (['succeeded', 'failed', 'cancelled'].includes(task.progress.state))
+                continue;
+            task.cancelRequested = true;
+            task.pauseRequested = false;
+            task.resume?.();
+        }
         this.embeddingWorker?.close();
         this.embeddingWorker = null;
         this.rerankWorker?.close();
         this.rerankWorker = null;
+        this.oplog?.close();
+        this.extractionRunsStore?.close();
+        this.axesStore?.close();
+        this.knowledgeDb?.close();
+        this.derived?.close();
+        this.store?.close();
     }
     /** Both the encoder and the reranker speak the same JSONL worker protocol. */
     spawnWorker(label = 'EMBEDDING') {
@@ -2333,11 +2349,18 @@ export class KnowledgeRuntime {
         // 「这份台账派生出了哪些结论」就回到关键词路回答 —— 那本来就是词面问题，不是图问题。
         const titleOf = (sourceId) => byId.get(sourceId);
         try {
-            await (await this.derivedHandle())?.rebuildFts(units.map(unit => ({
+            const db = await this.derivedHandle();
+            if (!db)
+                throw new Error('DERIVED_STORE_UNAVAILABLE');
+            const documents = units.map(unit => ({
                 unitId: unit.unitId,
                 title: unit.title,
                 content: noteIndexText({ title: unit.title, content: unit.content, sourceRefs: unit.sourceRefs }, titleOf),
-            })));
+            }));
+            if (this.publication)
+                this.publication.fts = documents;
+            else
+                db.rebuildFts(documents);
             this.ftsError = undefined;
             return 'ready';
         }
@@ -2347,6 +2370,8 @@ export class KnowledgeRuntime {
         }
     }
     async buildVectorIndex(units, version) {
+        if (this.publication)
+            this.publication.vectors = null;
         if (this.config.embeddingProvider === 'none')
             return { status: 'skipped', count: 0, reused: 0 };
         if (this.config.embeddingDimension % 8 !== 0)
@@ -2355,7 +2380,7 @@ export class KnowledgeRuntime {
         if (inputs.length === 0)
             return { status: 'ready', count: 0, reused: 0, dimension: this.config.embeddingDimension, device: 'none' };
         const previous = await this.loadVectorIndex();
-        const compatiblePrevious = previous && previous.manifest.dimension === this.config.embeddingDimension && previous.manifest.provider === this.config.embeddingProvider && previous.manifest.model === this.embeddingModelId && previous.manifest.encoder === ENCODER_FINGERPRINT ? previous : null;
+        const compatiblePrevious = previous && previous.manifest.dimension === this.config.embeddingDimension && previous.manifest.provider === this.config.embeddingProvider && previous.manifest.model === this.embeddingModelId && previous.manifest.modelFingerprint === this.embeddingFingerprint() && previous.manifest.encoder === ENCODER_FINGERPRINT ? previous : null;
         const previousById = new Map((compatiblePrevious?.manifest.items ?? []).map((item, index) => [item.unitId, { item, index }]));
         const binaryWidth = Math.ceil(this.config.embeddingDimension / 8);
         const binary = Buffer.alloc(inputs.length * binaryWidth);
@@ -2408,9 +2433,20 @@ export class KnowledgeRuntime {
                 this.encoderHealth = { ok: false, reason: `编码器退化：${inputs.length} 条 note 只产出 ${distinct.size} 个不同向量` };
                 throw new Error(`EMBEDDING_INDEX_DEGENERATE: ${inputs.length} 条只产出 ${distinct.size} 个不同向量`);
             }
-            const manifest = { version, createdAt: new Date().toISOString(), provider: this.config.embeddingProvider, model: this.embeddingModelId, encoder: ENCODER_FINGERPRINT, device, dimension: this.config.embeddingDimension, quantization: VECTOR_QUANTIZATION, itemCount: inputs.length, items: inputs.map(item => ({ unitId: item.unit.unitId, contentHash: item.contentHash })) };
-            (await this.derivedHandle())?.putVectorIndex(manifest, binary, int8);
-            this.vectorIndex = { manifest, binary, int8 };
+            const manifest = { version, createdAt: new Date().toISOString(), provider: this.config.embeddingProvider, model: this.embeddingModelId, modelFingerprint: this.embeddingFingerprint(), encoder: ENCODER_FINGERPRINT, device, dimension: this.config.embeddingDimension, quantization: VECTOR_QUANTIZATION, itemCount: inputs.length, items: inputs.map(item => ({ unitId: item.unit.unitId, contentHash: item.contentHash })) };
+            /*
+             * 向量、它的量化缓冲与清单**一起**写进派生库：三个东西必须同一次落地，
+             * 分三次写文件时崩在中间会留下「清单说有 40 条、缓冲只有 30 条」的半成品。
+             */
+            const db = await this.derivedHandle();
+            if (!db)
+                throw new Error('DERIVED_STORE_UNAVAILABLE');
+            if (this.publication)
+                this.publication.vectors = { manifest, binary, int8 };
+            else {
+                db.putVectorIndex(manifest, binary, int8);
+                this.vectorIndex = { manifest, binary, int8 };
+            }
             this.vectorError = undefined;
             return { status: 'ready', count: inputs.length, reused, dimension: this.config.embeddingDimension, device };
         }
@@ -2426,7 +2462,7 @@ export class KnowledgeRuntime {
         for (const artifact of [WIKI_NOTES, LEGACY_UNITS]) {
             try {
                 const notes = JSON.parse(await this.readArtifact(artifact));
-                if (Array.isArray(notes) && notes.length > 0) {
+                if (Array.isArray(notes)) {
                     this.units = notes;
                     break;
                 }
@@ -2650,7 +2686,15 @@ export class KnowledgeRuntime {
          */
         let compile = null;
         if (input.compile !== false) {
-            const rebuilt = await this.rebuild('wiki', input.lineage);
+            let rebuilt;
+            try {
+                rebuilt = await this.rebuild('wiki', input.lineage);
+            }
+            catch (cause) {
+                warnings.push(`来源已写入，编译未完成：${cause instanceof Error ? cause.message : String(cause)}`);
+            }
+            if (rebuilt === undefined)
+                return success({ written, failed, attempted: items.length, compile }, warnings);
             if (rebuilt.ok === false) {
                 warnings.push(`来源已写入，但编译失败：${rebuilt.error?.message ?? '未知原因'}`);
             }
@@ -2939,7 +2983,14 @@ export class KnowledgeRuntime {
      *
      * 失败一律返回 `null`，**不抛** —— 「知识库不可用」是一条要显示的结论，不是一个异常。
      */
+    storeHandleOpening;
     async storeHandle() {
+        if (this.store !== undefined)
+            return this.store;
+        this.storeHandleOpening ??= this.openStoreHandle();
+        return this.storeHandleOpening;
+    }
+    async openStoreHandle() {
         if (this.store !== undefined)
             return this.store;
         const sqlite = await loadSqlite();
@@ -3124,7 +3175,14 @@ export class KnowledgeRuntime {
             this.migrationNotes.push(`已把 03_compiled 的 ${imported} 份产物搬进 derived.db`);
     }
     /** 派生库（`<库根>/derived.db`）：编译产物，**可整体删掉重算**。 */
+    derivedHandleOpening;
     async derivedHandle() {
+        if (this.derived !== undefined)
+            return this.derived;
+        this.derivedHandleOpening ??= this.openDerivedHandle();
+        return this.derivedHandleOpening;
+    }
+    async openDerivedHandle() {
         if (this.derived !== undefined)
             return this.derived;
         const sqlite = await loadSqlite();
@@ -3157,7 +3215,10 @@ export class KnowledgeRuntime {
         const db = await this.derivedHandle();
         if (db === null)
             throw new Error('派生库不可用');
-        db.putArtifact(name, body);
+        if (this.publication)
+            this.publication.artifacts.set(name, body);
+        else
+            db.putArtifact(name, body);
     }
     async hasArtifact(name) {
         return (await this.derivedHandle())?.artifact(name) !== undefined;
@@ -3586,7 +3647,31 @@ export class KnowledgeRuntime {
         }
         for (const card of (await this.loadCards()).filter(item => item.sourceRefs.includes(docId))) {
             try {
-                await this.writeCard({ ...card, sourceRefs: card.sourceRefs.filter(ref => ref !== docId), origin: 'internal' });
+                const placements = db.placementsOf([card.entityId]).get(card.entityId) ?? [];
+                const remaining = [];
+                for (const row of placements) {
+                    const item = await store?.get(row.knowledgeId);
+                    if (item)
+                        remaining.push({ row, knowledge: item });
+                }
+                const sections = new Map();
+                for (const { row, knowledge: item } of remaining.sort((a, b) => a.row.ordinal - b.row.ordinal)) {
+                    const heading = row.section || '知识';
+                    const lines = sections.get(heading) ?? [];
+                    lines.push(`${item.text}[^${item.id}]`);
+                    sections.set(heading, lines);
+                }
+                const content = sections.size > 0
+                    ? [...sections].map(([heading, lines]) => `## ${heading}\n\n${lines.join('\n\n')}`).join('\n\n')
+                    : card.content;
+                const updated = await this.writeCard({
+                    ...card, content,
+                    ...(sections.size > 0 ? { summary: remaining[0].knowledge.text, placements: remaining.map(item => item.row) } : {}),
+                    metadata: { ...card.metadata, layout: undefined, citations: undefined, evidence_needs_review: sections.size === 0 },
+                    sourceRefs: card.sourceRefs.filter(ref => ref !== docId), origin: 'internal',
+                });
+                if (!updated.ok)
+                    throw new Error(updated.error.message);
                 cardsDetached += 1;
             }
             catch (cause) {
@@ -3839,7 +3924,7 @@ export class KnowledgeRuntime {
         }));
         const hash = layoutHash({
             knowledgeIds: knowledge.map(item => item.id),
-            knowledgeContext: knowledge.map(item => `${item.id}:${item.sourceHeadings.join('|')}`),
+            knowledgeContext: listed.knowledge.map(item => JSON.stringify({ id: item.id, text: item.text, version: item.version, headings: item.sources.map(source => source.headingPath), coordinate: input.coordinate })),
             profileId: input.profileId,
         });
         const layout = { profile: input.profileId, hash, origin: 'model' };
@@ -3938,7 +4023,7 @@ export class KnowledgeRuntime {
                 raw: raw.trim().replace(/\s+/g, ' ').slice(0, 400),
             });
         }
-        const checked = checkOrganize(plan, context.knowledge.map(item => item.id), { ...(await this.relatedForCard(card)) });
+        const checked = checkOrganize(plan, context.knowledge.map(item => item.id), { knowledge: context.knowledge, ...(await this.relatedForCard(card)) });
         const problems = [...parsed.problems.map(problem => problem.message), ...checked.problems.map(problem => problem.message)];
         const placements = problems.length === 0 ? placementsOf(plan, checked.cited) : [];
         const images = await this.imagesForCard(card);
@@ -4127,6 +4212,7 @@ export class KnowledgeRuntime {
         const problems = [...parsed.problems];
         if (plan !== undefined) {
             const checked = checkOrganize(plan, knowledge.map(item => item.id), {
+                knowledge,
                 ...(input.related === undefined ? {} : { related: input.related }),
             });
             problems.push(...checked.problems);
@@ -4474,7 +4560,7 @@ export class KnowledgeRuntime {
         return notes;
     }
     /** 1-hop neighbourhood of a set of wiki cards inside the compiled graph. */
-    oneHopGraph(keys, includeProblem) {
+    oneHopGraph(keys, includeProblem, graph = this.graph) {
         const visible = (node) => includeProblem || node.status !== 'problem';
         const edges = this.graph.edges.filter(edge => keys.has(String(edge.from)) || keys.has(String(edge.to))).slice(0, 50);
         const ids = new Set(keys);
@@ -4579,7 +4665,7 @@ export class KnowledgeRuntime {
         for (const artifact of [WIKI_NOTES, LEGACY_UNITS]) {
             try {
                 const notes = JSON.parse(await this.readArtifact(artifact));
-                if (Array.isArray(notes) && notes.length > 0)
+                if (Array.isArray(notes))
                     return notes;
             }
             catch { /* the first build has not happened yet */ }
@@ -4603,7 +4689,11 @@ export class KnowledgeRuntime {
         return contentHashOf(JSON.stringify({
             sourceId: source.sourceId,
             content: contentHashOf(source.content),
-            updatedAt: source.updatedAt,
+            title: source.title,
+            compiler: 'knowledge-extract-v2',
+            extractWithModel: this.config.extractWithModel,
+            extractionNote: this.extractionNote(),
+            layoutProfile: this.config.layoutProfileId,
             declared: contentHashOf(JSON.stringify(declared)),
             registry: registryHash,
         }));
@@ -4639,7 +4729,7 @@ export class KnowledgeRuntime {
     onOrganize, runId) {
         const schema = this.wikiSchema();
         const enabledTypes = schema.types.filter(def => def.enabled);
-        const registryHash = contentHashOf(JSON.stringify(enabledTypes.map(def => ({ id: def.id, description: def.description, examples: def.examples }))));
+        const registry = await this.axisRegistry();
         const outcome = this.emptyExtractionOutcome({});
         /**
          * 模型调用**每轮解析一次**，而且解析不到时**如实报出来**（0044）。
@@ -4650,6 +4740,7 @@ export class KnowledgeRuntime {
          */
         const seam = this.config.extractWithModel ? this.modelSeamNow() : {};
         const call = seam.call;
+        const registryHash = contentHashOf(JSON.stringify({ types: enabledTypes, axesRevision: registry?.inputRevision() ?? 0, model: { available: Boolean(call), provider: seam.provider, model: seam.model, reasoningEffort: seam.reasoningEffort } }));
         if (this.config.extractWithModel && !call) {
             outcome.warnings.push(`模型抽取已开启，但取不到可用的模型调用：${seam.why ?? '原因未知'} —— 本次退回规则抽取：`
                 + '卡片正文是按 `##` 小节切下来的原文，判重也只能比字面，同一实体换个标题写法会落成两张卡。');
@@ -4676,9 +4767,9 @@ export class KnowledgeRuntime {
             if (runId)
                 await this.checkpointCompileTask(runId);
             const fingerprint = this.extractionFingerprint(source, registryHash);
-            outcome.extractionHashes[source.sourceId] = fingerprint;
             if (previousHashes[source.sourceId] === fingerprint) {
                 outcome.sourcesSkipped += 1;
+                outcome.extractionHashes[source.sourceId] = fingerprint;
                 const kept = persisted[source.sourceId] ?? [];
                 if (kept.length > 0) {
                     outcome.relationsBySource[source.sourceId] = kept;
@@ -4692,7 +4783,9 @@ export class KnowledgeRuntime {
             try {
                 // 同一轮里后一份来源应当能看到前一份来源刚抽出来的实体，所以判重索引
                 // 每份来源都用「磁盘上的卡片 + 这一轮 pending 的卡片」重建。
-                await this.compileSource(source, byKey, pending, enabledTypes, outcome, call, knowledgeIds, runId, seam);
+                const complete = await this.compileSource(source, byKey, pending, enabledTypes, outcome, call, knowledgeIds, runId, seam);
+                if (complete !== false)
+                    outcome.extractionHashes[source.sourceId] = fingerprint;
             }
             catch (cause) {
                 if (cause instanceof CompileTaskCancelledError)
@@ -4724,7 +4817,7 @@ export class KnowledgeRuntime {
          */
         const folded = new Map();
         for (const [key, item] of pending)
-            folded.set(key, appendExtracted(item.existing?.content ?? '', [item.content]));
+            folded.set(key, item.content);
         const view = [];
         for (const [key, card] of byKey)
             view.push({ key, content: card.content, sourceRefs: card.sourceRefs });
@@ -4801,9 +4894,14 @@ export class KnowledgeRuntime {
             const contentBeforeEvents = preserveModelLayout ? existing.content : content;
             const finalContent = withEventReferences(contentBeforeEvents, item.metadata.event_refs, eventsById);
             const finalSummary = preserveModelLayout ? existing.summary : item.summary;
-            const finalPlacements = preserveModelLayout || item.placements === undefined
+            let finalPlacements = preserveModelLayout || item.placements === undefined
                 ? undefined
                 : translatePlacements(item.placements, knowledgeIds);
+            if (finalPlacements !== undefined && existing) {
+                const db = await this.storeHandle();
+                const previous = db?.placementsOf([existing.entityId]).get(existing.entityId) ?? [];
+                finalPlacements = [...new Map([...previous, ...finalPlacements].map(row => [row.knowledgeId, row])).values()];
+            }
             const titledMetadata = withTitleAlias(metadata, existing?.title, finalTitle);
             const finalMetadata = titledMetadata;
             const unchanged = existing !== undefined
@@ -4831,6 +4929,8 @@ export class KnowledgeRuntime {
                 origin: 'compile',
             });
             if (written.ok === false) {
+                for (const ref of item.sourceRefs)
+                    delete outcome.extractionHashes[ref];
                 outcome.warnings.push(`卡片 ${item.entityId} 写入失败（${written.error.code}）：${written.error.message}`);
                 continue;
             }
@@ -5096,6 +5196,7 @@ export class KnowledgeRuntime {
      * 后一份文档可能把前一份的知识并进去，落位要指活着的那一行。
      */
     knowledgeIds, compileRunId, modelInfo) {
+        let extractionComplete = call === undefined;
         // 判重索引要看到「这一轮前面几份来源刚抽出来的卡片」，否则同一实体跨两份文档
         // 会各建一张 —— 而那正是这次改造要修掉的那个 bug。
         const cards = [...byKey.values()];
@@ -5128,6 +5229,9 @@ export class KnowledgeRuntime {
         }
         /** 撞名报了没有 —— 同一个名字被三个坐标撞到时报三次是噪声。 */
         const collisionReported = new Set();
+        const sourceDb = await this.storeHandle();
+        const sourceHash = createHash('sha256').update(source.content, 'utf8').digest('hex');
+        const sourceVersion = sourceDb?.versions('source', source.sourceId).find(row => row.blobHash === sourceHash)?.version;
         const ruleCandidates = extractCandidates(source, enabledTypes);
         outcome.candidatesExtracted += ruleCandidates.length;
         const ruleNormalized = normalizeCandidates(ruleCandidates, buildAliasIndex(cards));
@@ -5229,9 +5333,10 @@ export class KnowledgeRuntime {
                 }),
             });
             /**
-             * 落轨迹、收知识。两件都**不影响这一次编译成不成** —— 审计与真源是旁路，
-             * 旁路坏了不能把主路一起拖垮（与操作日志同一条纪律）。
+             * 记录抽取轨迹，再写入事实真源。轨迹是审计；事实写入不完整时不能保存成功指纹，
+             * 下一次增量编译必须能够重试。
              */
+            extractionComplete = report.model.ok;
             const summary = trialSummary(report);
             await this.recordExtractionRun({
                 id: runId, docId: source.sourceId, title: source.title, summary,
@@ -5241,6 +5346,7 @@ export class KnowledgeRuntime {
                 await this.checkpointCompileTask(compileRunId);
             const ingested = await this.ingestTrialKnowledge({
                 runId, knowledge: report.knowledge,
+                sourceVersions: { [source.sourceId]: sourceVersion },
                 objects: report.objects, actions: report.actions, scenes: report.scenes,
             });
             let eventIngested = {
@@ -5260,6 +5366,8 @@ export class KnowledgeRuntime {
                 outcome.warnings.push(`Event 没有写入知识库：${cause instanceof Error ? cause.message : String(cause)}`);
             }
             outcome.warnings.push(...eventIngested.warnings);
+            if (ingested.skipped > 0 || eventIngested.skipped > 0)
+                extractionComplete = false;
             // 落位要用库内的 id。这一份报告里每一条知识的映射都并进整轮那一份 ——
             // 后面的来源可能命中同一张卡，那时落位指的行也得是活的。
             Object.assign(knowledgeIds, ingested.ids);
@@ -5276,7 +5384,7 @@ export class KnowledgeRuntime {
             outcome.axesAmbiguous += axes.filter(axis => axis.outcome === 'ambiguous').length;
             outcome.knowledgeMerged += ingested.merged;
             if (ingested.skipped > 0) {
-                outcome.warnings.push(`${ingested.skipped} 条知识没有核对得上的出处，只进了抽取轨迹，没有进真源`);
+                outcome.warnings.push(`${ingested.skipped} 条知识未进入真源（出处核验或写入失败），已保留抽取轨迹，下一次编译会重试`);
             }
             if (eventIngested.skipped > 0) {
                 outcome.warnings.push(`${eventIngested.skipped} 个 Event 没有可核验出处，未进入 Event 真源`);
@@ -5515,6 +5623,7 @@ export class KnowledgeRuntime {
             ...(outcome.relationsBySource[source.sourceId] ?? []),
             ...ruleNormalized.relations,
         ];
+        return extractionComplete;
     }
     /**
      * 把关系候选装配成 wiki↔wiki 的边。
@@ -5645,7 +5754,7 @@ export class KnowledgeRuntime {
      * 调用点必须在**按卡片去重之后**：先扩展再去重会把邻居与命中混在一起，
      * 而上下文里必须分得清「这是召回来的」还是「这是延伸出来的」。
      */
-    expandWiki(seedKeys, cardByKey, includeProblems) {
+    expandWiki(seedKeys, cardByKey, includeProblems, graph = this.graph) {
         const seeds = new Set(seedKeys);
         const visible = (card) => includeProblems || card.status !== 'problem';
         const via = new Map();
@@ -5656,7 +5765,7 @@ export class KnowledgeRuntime {
             via.set(key, bucket);
         };
         const edges = [];
-        for (const edge of this.graph.edges) {
+        for (const edge of graph.edges) {
             const type = String(edge.type);
             if (type === 'supported_by')
                 continue;
@@ -6207,7 +6316,12 @@ export class KnowledgeRuntime {
      * 与抽取轨迹**同一个数据库文件**（`<memoryDir>/knowledge.sqlite`）：它们是同一层
      * （领域实体与它的审计），而解析一条知识要同时读两边 —— 分两个文件只是多一次打开。
      */
+    axisRegistryOpening;
     async axisRegistry() {
+        this.axisRegistryOpening ??= this.openAxisRegistry();
+        return this.axisRegistryOpening;
+    }
+    async openAxisRegistry() {
         if (this.axesReady !== null)
             return this.axesReady ? this.axesStore : null;
         /*
@@ -6215,7 +6329,10 @@ export class KnowledgeRuntime {
          * 记忆段里那个 `knowledge.sqlite`。理由是同一条：它们是**知识**（不可重建的命名决定
          * 与人的裁决），必须跟着知识库一起备份、迁移、删除；而记忆段只装交互记录。
          */
-        const registry = new AxisRegistry(this.safePath(KNOWLEDGE_DB_FILE));
+        const db = await this.storeHandle();
+        if (db === null)
+            return null;
+        const registry = new AxisRegistry(this.safePath(KNOWLEDGE_DB_FILE), db.connection());
         const ok = await registry.open();
         this.axesStore = ok ? registry : null;
         this.axesReady = ok;
@@ -6728,7 +6845,13 @@ export class KnowledgeRuntime {
     /** 并两个实体。被并的那个不删，转成 `merged` 并指向目标。 */
     async mergeAxes(fromId, intoId) {
         const registry = await this.axisRegistry();
-        return registry === null ? false : registry.merge(fromId, intoId);
+        const db = await this.storeHandle();
+        if (!registry || !db)
+            return false;
+        const merged = await registry.merge(fromId, intoId, kind => redirectAxisReferences(db, kind, fromId, intoId));
+        if (merged)
+            this.cards = await this.loadCards();
+        return merged;
     }
     /** 加一个别名。`scopeId` 空串 = 全局。 */
     async addAxisAlias(id, alias, scopeId = '') {
@@ -6743,15 +6866,23 @@ export class KnowledgeRuntime {
     /**
      * Knowledge 库（0063 §2）：事实真源。
      *
-     * 与轴注册表**同一个文件**（`<memoryDir>/knowledge.sqlite`）、**各自的表**。
+     * 与轴注册表共享经过校验的 `knowledge.db` 连接，使用各自的表。
      * 两个模块互不认识，靠 id 字符串耦合 —— 代价是没有数据库级引用完整性，
      * 收益是「一条知识挂了一个不存在的坐标」会被 §5.7 的坐标核验**报出来**，
      * 而不是被数据库静默拒绝。
      */
+    knowledgeStoreOpening;
     async knowledgeStore() {
+        this.knowledgeStoreOpening ??= this.openKnowledgeStore();
+        return this.knowledgeStoreOpening;
+    }
+    async openKnowledgeStore() {
         if (this.knowledgeReady !== null)
             return this.knowledgeReady ? this.knowledgeDb : null;
-        const store = new KnowledgeStore(this.safePath(KNOWLEDGE_DB_FILE));
+        const db = await this.storeHandle();
+        if (db === null)
+            return null;
+        const store = new KnowledgeStore(this.safePath(KNOWLEDGE_DB_FILE), db.connection());
         const ok = await store.open();
         this.knowledgeDb = ok ? store : null;
         this.knowledgeReady = ok;
@@ -6774,13 +6905,12 @@ export class KnowledgeRuntime {
             /*
              * 给每一处出处补上**它依据的是哪一版**（0062 v2）。
              *
-             * 补在这里而不是让每个调用方自己带：抽取与编译那条链路传的是 `documentId`，而
-             * 「现在是第几版」只有存储层知道。漏补的后果不是报错，而是「可追溯」少一半 ——
-             * 来源被人改过之后，没有任何东西能回答那条知识还算不算数。
+             * 抽取链路带实际读取版本；直接写入没有指定版本时，补当前来源版本。
+             * 版本用于追踪证据变化，不能据此裁定 Knowledge 是否失效。
              */
             const db = await this.storeHandle();
             const sources = (input.sources ?? []).map(source => {
-                if (!source.documentId)
+                if (!source.documentId || source.toVersion !== undefined)
                     return source;
                 const version = db?.source(source.documentId)?.version;
                 return version === undefined ? source : { ...source, toVersion: version };
@@ -6806,7 +6936,9 @@ export class KnowledgeRuntime {
          * 调用方可以显式传 `false` 关掉它（试跑那条链路不需要这个字段）。
          */
         try {
-            return await store.list({ withCards: true, ...query });
+            const page = await store.list({ withCards: true, ...query });
+            const db = await this.storeHandle();
+            return db ? { ...page, knowledge: page.knowledge.map(row => assessKnowledgeEvidence(row, db)) } : page;
         }
         catch {
             return null;
@@ -6821,7 +6953,8 @@ export class KnowledgeRuntime {
             const knowledge = await store.get(id);
             if (knowledge === null)
                 return null;
-            return { knowledge, versions: await store.versions(id) };
+            const db = await this.storeHandle();
+            return { knowledge: db ? assessKnowledgeEvidence(knowledge, db) : knowledge, versions: await store.versions(id) };
         }
         catch {
             return null;
@@ -6889,7 +7022,7 @@ export class KnowledgeRuntime {
         const cardOrphans = cards.filter(card => card.sourceRefs.every(ref => !live.has(ref))).length;
         const events = (await this.loadEvents()).filter(event => event.records.some(record => !live.has(record.sourceId))).length;
         /**
-         * 图片也进这张账（2026-10-05）。
+         * 未被引用的来源图片也进这张账（2026-10-05）。`images.publish` 写入的独立图片会被识别并保留。
          *
          * 少了它，「来源与卡片都清完了、只剩一堆没人引用的图」这种状态在界面上**一个字都没有**
          * —— 清理孤儿的入口因此不出现，而用户唯一能看到的读数（「收录 N 个文件」）又把它算成
@@ -6897,7 +7030,7 @@ export class KnowledgeRuntime {
          * 「按一下能清掉几个」是同几个。
          */
         const names = await this.assetBucketNames();
-        const assets = names.length === 0 ? 0 : this.unreferencedBuckets(names, sources, cards).length;
+        const assets = names.length === 0 ? 0 : (await this.unreferencedBuckets(names, sources, cards)).length;
         return { knowledge, cards: cardOrphans, events, assets };
     }
     /** 图片池里的桶名（`01_source_raw/_assets/<bucket>/`）。没有池子就是空的。 */
@@ -6925,8 +7058,9 @@ export class KnowledgeRuntime {
         return [...names];
     }
     /**
-     * 还有没有人在引用这个桶 —— 判据是**三处文本里出现过 `_assets/<bucket>/`**：
-     * 来源正文、来源 front matter 的 `metadata.assets`、卡片正文。
+     * 还有没有人在引用这个桶 —— 判据是来源正文、来源 front matter 的 `metadata.assets`、
+     * 卡片正文出现过 `_assets/<bucket>/`，或者它是 `images.publish` 写入的独立图床图片。
+     * 独立图片没有来源/卡片引用是正常状态，必须保留。
      *
      * 为什么三处都要看：桶名是**内容哈希的前 12 位**（`convert/ingest.ts`），不是来源 id。
      * 同一份内容以两个分类导入会共用同一个桶；而卡片正文会把图片引用**复制进去**
@@ -6934,7 +7068,7 @@ export class KnowledgeRuntime {
      *
      * 不看 `03_compiled/`：那是派生物，下一次 `rebuild` 会把指向已删图片的引用一起扔掉。
      */
-    unreferencedBuckets(names, sources, cards) {
+    async unreferencedBuckets(names, sources, cards) {
         const referenced = new Set();
         /**
          * **两种引用形式都算**：`assets/<桶>/`（新写的）与 `_assets/<桶>/`（存量）。
@@ -6958,7 +7092,44 @@ export class KnowledgeRuntime {
         }
         for (const card of cards)
             collect(card.content);
-        return names.filter(name => !referenced.has(name));
+        const unreferenced = [];
+        for (const name of names) {
+            if (referenced.has(name))
+                continue;
+            if (await this.isPublishedImageBucket(name))
+                continue;
+            unreferenced.push(name);
+        }
+        return unreferenced;
+    }
+    /**
+     * `images.publish` 的图片不需要被来源或卡片引用。新写入的桶有明确标记；同时兼容
+     * 标记加入前已发布的图片：它们以图片自身的 SHA-256 前 12 位作为桶名。
+     */
+    async isPublishedImageBucket(name) {
+        for (const root of this.assetRoots()) {
+            if (existsSync(join(root, name, PUBLISHED_IMAGE_MARKER)))
+                return true;
+        }
+        // 旧版本 images.publish 只会写入知识库根目录的 assets/，因此只在这里做哈希识别。
+        if (!/^[a-f0-9]{12}$/i.test(name))
+            return false;
+        const dir = join(this.rootDir, ASSETS_DIR, name);
+        try {
+            for (const entry of await readdir(dir, { withFileTypes: true })) {
+                if (!entry.isFile() || !/\.(?:png|jpe?g|gif|webp|avif|bmp|svg)$/i.test(entry.name))
+                    continue;
+                const path = join(dir, entry.name);
+                const details = await stat(path);
+                if (details.size > 20 * 1024 * 1024)
+                    continue;
+                const bytes = await readFile(path);
+                if (createHash('sha256').update(bytes).digest('hex').slice(0, 12) === name)
+                    return true;
+            }
+        }
+        catch { /* 桶目录可能在扫描期间被删除 */ }
+        return false;
     }
     /**
      * 回收 `source_raw/` 里**没有人再指向的底稿桶**（0067）。
@@ -7036,7 +7207,7 @@ export class KnowledgeRuntime {
             return { buckets: 0, files: 0, problems: [] };
         const problems = [];
         const cards = this.cards.length > 0 ? this.cards : await this.loadCards();
-        const doomed = this.unreferencedBuckets(names, await this.loadSources(), cards);
+        const doomed = await this.unreferencedBuckets(names, await this.loadSources(), cards);
         let buckets = 0;
         let files = 0;
         for (const name of doomed) {
@@ -7191,7 +7362,7 @@ export class KnowledgeRuntime {
     async ingestTrialKnowledge(input) {
         const store = await this.knowledgeStore();
         if (store === null)
-            return { saved: 0, merged: 0, skipped: 0, ids: {} };
+            return { saved: 0, merged: 0, skipped: input.knowledge.length, ids: {} };
         const axes = { objects: input.objects, actions: input.actions, scenes: input.scenes };
         let saved = 0;
         let merged = 0;
@@ -7205,7 +7376,7 @@ export class KnowledgeRuntime {
             }
             try {
                 const coordinate = coordinateIdsOf(axes, item.object, item.action, item.scene);
-                const result = await store.ingest({
+                const result = await this.ingestKnowledge({
                     text: item.text,
                     objectId: coordinate.objectId,
                     actionId: coordinate.actionId,
@@ -7213,11 +7384,16 @@ export class KnowledgeRuntime {
                     runId: input.runId,
                     sources: usable.map(source => ({
                         documentId: source.documentId,
+                        ...(input.sourceVersions?.[source.documentId] === undefined ? {} : { toVersion: input.sourceVersions[source.documentId] }),
                         quote: source.quote,
                         headingPath: source.headingPath,
                         ...(source.locator ? { locator: source.locator } : {}),
                     })),
                 });
+                if (result === null) {
+                    skipped += 1;
+                    continue;
+                }
                 if (result.merged)
                     merged += 1;
                 else
@@ -7402,13 +7578,7 @@ export class KnowledgeRuntime {
                 }
             }
             else if (preciseTime(event.occurredAt) && hasCompleteCoordinate(coordinateIds) && event.symptom?.trim()) {
-                identityKey = 'composite:' + hash(JSON.stringify([
-                    event.occurredAt,
-                    coordinateIds.objectId,
-                    coordinateIds.actionId,
-                    coordinateIds.sceneId,
-                    normalizeKnowledge(event.symptom),
-                ]));
+                identityKey = compositeEventIdentity(event.occurredAt, coordinateIds, event.symptom);
                 identityType = 'composite';
             }
             else {
@@ -7526,7 +7696,14 @@ export class KnowledgeRuntime {
      */
     async rebuild(only = 'all', lineage, options = {}) {
         const runId = newCompileRunId();
-        const result = await this.enqueueCompile(runId, only, lineage, options);
+        let result;
+        try {
+            result = await this.enqueueCompile(runId, only, lineage, options);
+        }
+        catch (cause) {
+            await this.settleProgressFailure(runId, cause);
+            throw cause;
+        }
         /*
          * 同步调用方拿的是返回值，但**别人可能在轮询同一条进度记录**（面板正开着编译对话框，
          * 而 Agent 起了这一次）。结论两个出口都要有。
@@ -7620,7 +7797,7 @@ export class KnowledgeRuntime {
             queued: false,
             finishedAt: current.finishedAt ?? new Date().toISOString(),
             failed: true,
-            outcome: current.outcome ?? `编译失败：${message}`,
+            outcome: `编译失败：${message}`,
         });
         await this.patchCompileOperation(runId, 'failed', `编译失败：${message}`);
     }
@@ -7676,6 +7853,52 @@ export class KnowledgeRuntime {
      * 它」—— 那两件事分别在 `enqueueCompile()` 与 `rebuild()` / `startCompile()` 里。
      */
     async compileOnce(runId, only = 'all', lineage, options = {}) {
+        await this.environmentGuard?.();
+        this.publication = { artifacts: new Map() };
+        const configAtStart = JSON.stringify({ config: this.config, fingerprint: this.embeddingFingerprint() });
+        try {
+            await this.loadCompiledState();
+            const result = await this.prepareCompile(runId, only, lineage, options);
+            await this.checkpointCompileTask(runId);
+            if (result.ok) {
+                const db = await this.derivedHandle();
+                if (!db)
+                    throw new Error('DERIVED_STORE_UNAVAILABLE');
+                const truth = await this.storeHandle();
+                const knowledge = await this.knowledgeStore();
+                const rows = [];
+                if (knowledge) {
+                    for (let offset = 0;; offset += 500) {
+                        const page = await knowledge.list({ limit: 500, offset });
+                        rows.push(...page.knowledge);
+                        if (offset + page.knowledge.length >= page.total)
+                            break;
+                    }
+                }
+                // Embeddings-only rebuild keeps the published card and knowledge generation.
+                const previous = db.artifact(COMPILE_SNAPSHOT);
+                const snapshot = only === 'embeddings' && previous
+                    ? { ...JSON.parse(previous), version: result.data.version, compileRunId: runId }
+                    : {
+                        version: result.data.version, compileRunId: runId,
+                        cards: this.cards, notes: this.units, graph: this.graph,
+                        diagnosisGraph: this.diagnosisGraph,
+                        placements: [...(truth?.placements() ?? new Map())], knowledge: rows,
+                    };
+                this.publication.artifacts.set(COMPILE_SNAPSHOT, JSON.stringify(snapshot));
+                await this.checkpointCompileTask(runId);
+                if (JSON.stringify({ config: this.config, fingerprint: this.embeddingFingerprint() }) !== configAtStart)
+                    throw new Error('COMPILE_CONFIG_CHANGED: 编译期间设置已变化，请重新编译');
+                db.publish(this.publication);
+                this.vectorIndex = null;
+            }
+            return result;
+        }
+        finally {
+            this.publication = undefined;
+        }
+    }
+    async prepareCompile(runId, only = 'all', lineage, options = {}) {
         /**
          * 进度记录**先占位**：`runId` 一落下去，这一趟就有了名字 —— 之后无论从哪个出口结束
          * （三种 return，或者抛异常），收口都能认出这条记录属于谁。
@@ -7744,24 +7967,17 @@ export class KnowledgeRuntime {
             this.writeCompileProgress({ ...(this.compileProgress ?? blankProgress(runId, only, startedAt, 'running', queuedAt)), ...patch });
         };
         /**
-         * 收口：四段一起标成完成，并写下一句结论。
-         *
-         * 它在 `rebuild()` 的**每一个** return 之前调用（一共三处出口）。少了任何一处，
-         * 那次编译的进度就会永远停在「进行中」—— 而界面拿它当「正在跑」，于是按钮一直灰着。
+         * 四段准备完成，保存结论。事务发布之前仍是 running；发布成功后由
+         * settleProgressReport 收口，发布失败则由 settleProgressFailure 收口。
          */
         const finishProgress = (outcome) => {
             const current = this.compileProgress;
             if (current === null)
                 return;
-            /*
-             * 收口时**立刻存档**，不只写槽位：槽位会被下一趟（排在后面的那一趟）顶掉，
-             * 而存档按编号留着 —— 发起编译的那一方无论何时来读，都读得到自己那一份。
-             */
-            this.rememberCompile({
+            this.writeCompileProgress({
                 ...current,
-                state: 'succeeded',
+                state: 'running',
                 queued: false,
-                finishedAt: new Date().toISOString(),
                 sourcesDone: Math.max(current.sourcesDone, current.sourcesTotal),
                 steps: current.steps.map(step => ({ ...step, state: 'done' })),
                 outcome,
@@ -8023,8 +8239,8 @@ export class KnowledgeRuntime {
          */
         const incremental = only === 'wiki';
         if (only === 'embeddings') {
-            if (this.units.length === 0)
-                await this.loadCompiledState();
+            await this.loadCompiledState();
+            Object.assign(cardHashes, previousHashes);
         }
         else {
             const previousNotes = incremental ? await this.readNotesArtifact() : [];
@@ -8106,7 +8322,9 @@ export class KnowledgeRuntime {
             const diagnosis = await this.diagnosisStore().readGraph();
             const diagnosisHash = contentHashOf(JSON.stringify({ nodes: diagnosis.nodes, edges: diagnosis.edges }));
             const diagnosisChanged = diagnosisHash !== previousManifest.diagnosisHash;
-            const corpusChanged = !incremental || previousVersion === 0 || cardsRecompiled > 0 || cardsRemoved > 0 || diagnosisChanged || derivedRefreshed || indexChanged;
+            const embeddingIdentity = JSON.stringify({ provider: this.config.embeddingProvider, model: this.embeddingModelId, fingerprint: this.embeddingFingerprint(), dimension: this.config.embeddingDimension, encoder: ENCODER_FINGERPRINT, baseUrl: this.config.embeddingBaseUrl });
+            const embeddingChanged = previousManifest.embeddingIdentity !== embeddingIdentity;
+            const corpusChanged = embeddingChanged || !incremental || previousVersion === 0 || cardsRecompiled > 0 || cardsRemoved > 0 || diagnosisChanged || derivedRefreshed || indexChanged;
             if (!corpusChanged) {
                 await this.checkpointCompileTask(runId);
                 // 这一趟的编号是调用方给的（0066）：进度记录、报告、manifest 用同一个编号。
@@ -8129,7 +8347,7 @@ export class KnowledgeRuntime {
                 // 用户刚点了编译却看到上次的统计，会以为按钮没生效。version 不变，所以
                 // 这个写入既不改索引也不让向量缓存失效。extractionHashes 必须跟着更新：
                 // 来源变了但没抽出卡片时，不落新指纹会让下一次又把它重抽一遍。
-                await this.writeArtifact('build-manifest.json', JSON.stringify({ version: previousVersion, builtAt: previousManifest.builtAt, sourceCount: sources.length, cardCount: this.cards.length, noteCount: this.units.length, cardHashes, extractionHashes: extraction.extractionHashes, embedding: previousManifest.embedding, diagnosisHash, indexHash, compileRunId, lastBuild: { only, incremental: true, skipped: true, cardsReused, cardsRecompiled: 0, cardsAdded: 0, cardsRemoved: 0, notesReused, notesRecompiled: 0, ...extractionCounts, ...finalizeCounts, relationsExtracted: 0, relationsDropped: 0 }, ...(lineage ? { lineage } : {}) }, null, 2));
+                await this.writeArtifact('build-manifest.json', JSON.stringify({ version: previousVersion, builtAt: previousManifest.builtAt, sourceCount: sources.length, cardCount: this.cards.length, noteCount: this.units.length, cardHashes, extractionHashes: extraction.extractionHashes, embeddingIdentity: JSON.stringify({ provider: this.config.embeddingProvider, model: this.embeddingModelId, fingerprint: this.embeddingFingerprint(), dimension: this.config.embeddingDimension, encoder: ENCODER_FINGERPRINT, baseUrl: this.config.embeddingBaseUrl }), embedding: previousManifest.embedding, diagnosisHash, indexHash, compileRunId, lastBuild: { only, incremental: true, skipped: true, cardsReused, cardsRecompiled: 0, cardsAdded: 0, cardsRemoved: 0, notesReused, notesRecompiled: 0, ...extractionCounts, ...finalizeCounts, relationsExtracted: 0, relationsDropped: 0 }, ...(lineage ? { lineage } : {}) }, null, 2));
                 const detail = detailOf({ skipped: true, version: previousVersion, cards: { created: [], updated: [], reused: reusedTitles.slice(0, MAX_LOG_ITEMS), removed: [] } });
                 report.detail = detail;
                 await settleOp(detail, `没有变化：复用 ${notesReused} 条召回片段，索引仍为 v${previousVersion}。`, 'done');
@@ -8198,6 +8416,8 @@ export class KnowledgeRuntime {
             await this.writeArtifact(DIAGNOSIS_GRAPH, JSON.stringify({ version, builtAt, nodes: diagnosis.nodes, edges: diagnosis.edges }, null, 2));
             await this.checkpointCompileTask(runId);
             const embeddingResult = await this.buildVectorIndex(this.units, version);
+            if (this.environmentGuard && embeddingResult.status === 'unavailable')
+                throw new Error(`向量索引构建失败：${embeddingResult.error ?? '未知原因'}。请重新自检环境后重试编译`);
             await this.checkpointCompileTask(runId);
             setStep('build', 'done', [
                 `知识图谱 ${this.graph.nodes.length} 节点 / ${this.graph.edges.length} 边`
@@ -8210,7 +8430,7 @@ export class KnowledgeRuntime {
             ]);
             // 这一趟的编号是调用方给的（0066）：进度记录、报告、manifest 用同一个编号。
             const compileRunId = runId;
-            await this.writeArtifact('build-manifest.json', JSON.stringify({ version, builtAt, sourceCount: sources.length, cardCount: this.cards.length, noteCount: this.units.length, cardHashes, extractionHashes: extraction.extractionHashes, embedding: embeddingResult, fts: ftsResult, compileRunId, diagnosisHash, indexHash, diagnosisGraph: { nodes: diagnosis.nodes.length, edges: diagnosis.edges.length }, lastBuild: { only, incremental: cardsReused > 0, skipped: false, cardsReused, cardsRecompiled, cardsAdded, cardsRemoved: removedCount, notesReused, notesRecompiled, ...extractionCounts, ...finalizeCounts, relationsExtracted, relationsDropped }, ...(lineage ? { lineage } : {}) }, null, 2));
+            await this.writeArtifact('build-manifest.json', JSON.stringify({ version, builtAt, sourceCount: sources.length, cardCount: this.cards.length, noteCount: this.units.length, cardHashes, extractionHashes: extraction.extractionHashes, embeddingIdentity: JSON.stringify({ provider: this.config.embeddingProvider, model: this.embeddingModelId, fingerprint: this.embeddingFingerprint(), dimension: this.config.embeddingDimension, encoder: ENCODER_FINGERPRINT, baseUrl: this.config.embeddingBaseUrl }), embedding: embeddingResult, fts: ftsResult, compileRunId, diagnosisHash, indexHash, diagnosisGraph: { nodes: diagnosis.nodes.length, edges: diagnosis.edges.length }, lastBuild: { only, incremental: cardsReused > 0, skipped: false, cardsReused, cardsRecompiled, cardsAdded, cardsRemoved: removedCount, notesReused, notesRecompiled, ...extractionCounts, ...finalizeCounts, relationsExtracted, relationsDropped }, ...(lineage ? { lineage } : {}) }, null, 2));
             const report = {
                 runId: compileRunId, compileRunId, version, only,
                 cards: this.cards.length, units: this.units.length, notes: this.units.length,
@@ -8258,6 +8478,8 @@ export class KnowledgeRuntime {
         const version = previousVersion + 1;
         await this.checkpointCompileTask(runId);
         const embeddingResult = await this.buildVectorIndex(this.units, version);
+        if (this.environmentGuard && embeddingResult.status === 'unavailable')
+            throw new Error(`向量索引构建失败：${embeddingResult.error ?? '未知原因'}。请重新自检环境后重试编译`);
         await this.checkpointCompileTask(runId);
         // 只重建向量这一趟只跑第五段（其余四段在开跑时就标成「本次不涉及」，见 `blankSteps`）。
         setStep('build', 'done', [
@@ -8268,7 +8490,7 @@ export class KnowledgeRuntime {
         ]);
         // 这一趟的编号是调用方给的（0066）：进度记录、报告、manifest 用同一个编号。
         const compileRunId = runId;
-        await this.writeArtifact('build-manifest.json', JSON.stringify({ version, builtAt: new Date().toISOString(), sourceCount: sources.length, cardCount: this.cards.length, noteCount: this.units.length, cardHashes, extractionHashes: extraction.extractionHashes, embedding: embeddingResult, compileRunId, lastBuild: { only, incremental: embeddingResult.reused > 0, skipped: false, notesReused: embeddingResult.reused, notesRecompiled: Math.max(0, embeddingResult.count - embeddingResult.reused), ...extractionCounts, relationsExtracted: 0, relationsDropped: 0 }, ...(lineage ? { lineage } : {}) }, null, 2));
+        await this.writeArtifact('build-manifest.json', JSON.stringify({ ...previousManifest, version, builtAt: new Date().toISOString(), sourceCount: sources.length, cardCount: this.cards.length, noteCount: this.units.length, cardHashes, extractionHashes: extraction.extractionHashes, embeddingIdentity: JSON.stringify({ provider: this.config.embeddingProvider, model: this.embeddingModelId, fingerprint: this.embeddingFingerprint(), dimension: this.config.embeddingDimension, encoder: ENCODER_FINGERPRINT, baseUrl: this.config.embeddingBaseUrl }), embedding: embeddingResult, compileRunId, lastBuild: { only, incremental: embeddingResult.reused > 0, skipped: false, notesReused: embeddingResult.reused, notesRecompiled: Math.max(0, embeddingResult.count - embeddingResult.reused), ...extractionCounts, relationsExtracted: 0, relationsDropped: 0 }, ...(lineage ? { lineage } : {}) }, null, 2));
         const report = {
             runId: compileRunId, compileRunId, version, only,
             cards: this.cards.length, units: this.units.length, notes: this.units.length,
@@ -8347,6 +8569,8 @@ export class KnowledgeRuntime {
                 rightNorm += right[index] * right[index];
             }
             const cosine = dot / (Math.sqrt(leftNorm) * Math.sqrt(rightNorm) || 1);
+            if (leftNorm < 1e-12 || rightNorm < 1e-12)
+                throw new Error('ENCODER_PROBE_ZERO_VECTOR: 编码器返回零向量');
             if (!Number.isFinite(cosine) || cosine > ENCODER_SELF_SIMILARITY_MAX) {
                 this.encoderHealth = { ok: false, reason: `编码器对两段无关文本给出同一个向量（cos = ${cosine.toFixed(4)}），向量路已停用` };
                 return this.encoderHealth;
@@ -8485,15 +8709,15 @@ export class KnowledgeRuntime {
         }
     }
     /** 关键词路：FTS5 + BM25（0031）。索引不在时如实降级，不退回旧的计数打分。 */
-    async ftsRoute(query, eligible, pool, threshold, titleOf) {
+    async ftsRoute(query, eligible, pool, threshold, titleOf, captured) {
         const eligibleIds = new Set(eligible.map(note => note.unitId));
         const derived = await this.derivedHandle();
         if (derived === null)
             return { ranking: [], rows: [], diagnostic: { route: 'fts', status: 'degraded', reason: '当前 Node 没有 node:sqlite（需要 22.5+），关键词路已降级' } };
-        if (!derived.hasFts())
+        if (!(captured?.ready ?? derived.hasFts()))
             return { ranking: [], rows: [], diagnostic: { route: 'fts', status: 'degraded', reason: '关键词索引还没建（在 derived.db 里），先编译一次' } };
         try {
-            const found = derived.searchFts(query, pool).filter(hit => eligibleIds.has(hit.unitId));
+            const found = (captured?.hits ?? derived.searchFts(query, pool)).filter(hit => eligibleIds.has(hit.unitId));
             /**
              * 覆盖率门槛（见 `MIN_QUERY_COVERAGE`）：只蹭到一两个高频单字的命中在这里淘汰，
              * 于是「整批都弱」也能弃答 —— 这是相对阈值做不到的那一半。
@@ -8563,8 +8787,8 @@ export class KnowledgeRuntime {
      * 阈值就完全失去意义（余弦 0 会被映射成 0.5，轻松过线）。原始余弦是绝对量，可以直接
      * 用来判「这段内容和问题到底像不像」—— 弃答主要靠它和重排阈值。
      */
-    async vectorRoute(query, eligibleIds, pool, threshold, expectedVersion) {
-        const index = await this.loadVectorIndex();
+    async vectorRoute(query, eligibleIds, pool, threshold, expectedVersion, captured) {
+        const index = captured === undefined ? await this.loadVectorIndex() : captured;
         if (!index) {
             const reason = '向量索引不存在或损坏，请执行 embeddings 编译重建';
             return { ranking: [], rows: [], diagnostic: { route: 'vector', status: 'degraded', reason }, health: { ok: false, reason } };
@@ -8577,7 +8801,7 @@ export class KnowledgeRuntime {
         if (!health.ok)
             return { ranking: [], rows: [], diagnostic: { route: 'vector', status: 'degraded', reason: health.reason }, health };
         try {
-            const { scores, embedMs, scanMs } = await this.vectorRecall(query, eligibleIds, pool);
+            const { scores, embedMs, scanMs } = await this.vectorRecall(query, eligibleIds, pool, index);
             const ranking = [...scores.entries()].map(([unitId, score]) => ({ unitId, score })).sort((left, right) => right.score - left.score || left.unitId.localeCompare(right.unitId));
             const { kept, dropped, topScore, rows } = applyThreshold(ranking, threshold);
             return {
@@ -8618,11 +8842,11 @@ export class KnowledgeRuntime {
      * 是因为两张图的节点含义不同（一个是卡片，一个是字段级节点），合成一张会让
      * 图谱 Tab 看到一张卡片散成七个点。
      */
-    diagnosisHits(queryTokens) {
+    diagnosisHits(queryTokens, graph = this.diagnosisGraph) {
         const seed = new Map();
-        if (this.diagnosisGraph.nodes.length === 0)
+        if (graph.nodes.length === 0)
             return seed;
-        for (const node of this.diagnosisGraph.nodes) {
+        for (const node of graph.nodes) {
             const title = String(node.title ?? '').toLocaleLowerCase();
             const id = String(node.id ?? '').toLocaleLowerCase();
             let score = 0;
@@ -8636,7 +8860,7 @@ export class KnowledgeRuntime {
                 seed.set(String(node.id), score);
         }
         // 关系词命中：两端各得 1 分。中文提问不会写 `refutes`，所以走 RELATION_QUERY_WORDS。
-        for (const edge of this.diagnosisGraph.edges) {
+        for (const edge of graph.edges) {
             const type = String(edge.kind ?? '');
             const relation = (RELATION_QUERY_WORDS[type] ?? type.toLocaleLowerCase().replace(/_/g, ' ')).toLocaleLowerCase();
             let score = 0;
@@ -8652,7 +8876,7 @@ export class KnowledgeRuntime {
             return seed;
         const expanded = new Map(seed);
         for (const [id, score] of seed) {
-            for (const edge of this.diagnosisGraph.edges) {
+            for (const edge of graph.edges) {
                 const from = String(edge.source);
                 const to = String(edge.target);
                 if (from === id)
@@ -8663,8 +8887,8 @@ export class KnowledgeRuntime {
         }
         return expanded;
     }
-    async graphBoostRanking(query, eligible, includeProblems) {
-        if (this.graph.nodes.length === 0)
+    async graphBoostRanking(query, eligible, includeProblems, graph = this.graph, diagnosisGraph = this.diagnosisGraph) {
+        if (graph.nodes.length === 0)
             return [];
         const queryTokens = segment(query);
         if (queryTokens.length === 0)
@@ -8675,9 +8899,9 @@ export class KnowledgeRuntime {
         const nodeKey = (node) => `${String(node.type)}:${String(node.id)}`;
         /** 卡片级节点 id → 它的 `entity_type`。归因图的节点 id 与卡片 id 相等（§14.1）。 */
         const typeByEntityId = new Map();
-        for (const node of this.graph.nodes)
+        for (const node of graph.nodes)
             typeByEntityId.set(String(node.id), String(node.type));
-        for (const node of this.graph.nodes) {
+        for (const node of graph.nodes) {
             if (!visible(node))
                 continue;
             const title = String(node.title ?? '').toLocaleLowerCase();
@@ -8692,7 +8916,7 @@ export class KnowledgeRuntime {
             if (score > 0)
                 boost(nodeKey(node), score);
         }
-        for (const edge of this.graph.edges) {
+        for (const edge of graph.edges) {
             const type = String(edge.type ?? '');
             const relation = (RELATION_QUERY_WORDS[type] ?? type.toLocaleLowerCase().replace(/_/g, ' ')).toLocaleLowerCase();
             let score = 0;
@@ -8712,7 +8936,7 @@ export class KnowledgeRuntime {
          * 归因图上命中的节点，映射回同 id 的卡片级节点加权 —— **不需要合图**，
          * 因为两张图的节点 id 本来就相等（§14.1）。
          */
-        for (const [id, score] of this.diagnosisHits(queryTokens)) {
+        for (const [id, score] of this.diagnosisHits(queryTokens, diagnosisGraph)) {
             const type = typeByEntityId.get(id);
             if (type)
                 boost(`${type}:${id}`, score);
@@ -8721,7 +8945,7 @@ export class KnowledgeRuntime {
             return [];
         const expanded = new Map(byNodeKey);
         for (const [key, score] of byNodeKey) {
-            for (const edge of this.graph.edges) {
+            for (const edge of graph.edges) {
                 const from = String(edge.from);
                 const to = String(edge.to);
                 if (from === key)
@@ -8804,7 +9028,7 @@ export class KnowledgeRuntime {
      * 这次召回少一条证据，而正确的答案是换成它被并进的那一条（`mergedInto` 只跳一跳：
      * 并进的目标自己不会再被并 —— 那正是「并」这个动作的定义）。
      */
-    async attachKnowledge(hits) {
+    async attachKnowledge(hits, snapshot) {
         if (hits.length === 0)
             return;
         const store = await this.storeHandle();
@@ -8819,7 +9043,7 @@ export class KnowledgeRuntime {
          * 一次召回十来张卡，而库里可能有上千张。
          */
         try {
-            placements = store.placementsOf([...new Set(hits.map(hit => hit.entityId))]);
+            placements = snapshot?.placements.length ? new Map(snapshot.placements) : store.placementsOf([...new Set(hits.map(hit => hit.entityId))]);
         }
         catch {
             return;
@@ -8841,7 +9065,14 @@ export class KnowledgeRuntime {
         const wanted = new Set(perHit.flat().map(row => row.knowledgeId));
         if (wanted.size === 0)
             return;
-        const rows = await this.readKnowledgeRows(knowledge, [...wanted]);
+        const rows = snapshot && snapshot.knowledge.length > 0
+            ? new Map(snapshot.knowledge.filter(row => wanted.has(row.id) && knowledge !== null)
+                .flatMap(row => {
+                // Deleted facts never reappear through a historical snapshot.
+                const live = store.raw('SELECT status FROM knowledge WHERE id = ?').get(row.id);
+                return live ? [[row.id, recallKnowledgeOf(assessKnowledgeEvidence({ ...row, status: live.status }, store), '')]] : [];
+            }))
+            : await this.readKnowledgeRows(knowledge, [...wanted]);
         if (rows.size === 0)
             return;
         hits.forEach((hit, index) => {
@@ -8872,12 +9103,12 @@ export class KnowledgeRuntime {
             if (row.mergedInto !== '')
                 followup.set(row.mergedInto, row.id);
             else
-                out.set(row.id, recallKnowledgeOf(row, ''));
+                out.set(row.id, recallKnowledgeOf(assessKnowledgeEvidence(row, (await this.storeHandle())), ''));
         }
         if (followup.size > 0) {
             rows = await store.list({ ids: [...followup.keys()], limit: 500 });
             for (const row of rows.knowledge)
-                out.set(row.id, recallKnowledgeOf(row, ''));
+                out.set(row.id, recallKnowledgeOf(assessKnowledgeEvidence(row, (await this.storeHandle())), ''));
             // 目标也没了（例如它的来源被删了）：那条落位就是悬空的，如实**不显示**，
             // 而不是把一条已经不存在的事实塞进上下文。
         }
@@ -8927,27 +9158,68 @@ export class KnowledgeRuntime {
             return failure(empty(), 'LIMIT_INVALID', '召回 top_k 必须是 1 到 50 的整数', false);
         if (!Number.isInteger(requestedTopN) || requestedTopN < 1 || (options.contextTopN !== undefined && requestedTopN > recallTopK))
             return failure(empty(), 'CONTEXT_TOP_N_INVALID', `上下文 top_n 必须是 1 到 ${recallTopK} 的整数`, false);
-        if (this.units.length === 0) {
-            await this.loadCompiledState();
-            if (this.units.length === 0) {
-                return failure(empty(), 'INDEX_NOT_READY', '知识索引尚未构建，请先编译知识库', true, '先执行 rebuild_knowledge，再进行召回。');
-            }
-        }
-        const eventLineage = withRun(lineage, 'recall');
-        const indexVersion = (await this.loadVectorIndex())?.manifest.version;
-        let compileRunId;
-        let knowledgeIndexVersion;
         try {
-            const manifest = JSON.parse(await this.readArtifact('build-manifest.json'));
-            if (typeof manifest.compileRunId === 'string' && manifest.compileRunId.trim())
-                compileRunId = manifest.compileRunId;
-            if (typeof manifest.version === 'number' && Number.isInteger(manifest.version))
-                knowledgeIndexVersion = manifest.version;
+            await this.environmentGuard?.();
         }
-        catch { /* the first build has not happened yet */ }
-        const eligible = this.units.filter(unit => includeProblems || unit.status !== 'problem');
+        catch (cause) {
+            return failure(empty(), 'ENVIRONMENT_NOT_READY', cause instanceof Error ? cause.message : String(cause), true, '在 Tita 设置中完成环境准备并重新自检。');
+        }
+        const derived = await this.derivedHandle();
+        const liveCards = await this.loadCards();
+        const liveKeys = new Set(liveCards.map(card => cardKey(card)));
+        const snapshotHash = derived?.artifactHash(COMPILE_SNAPSHOT);
+        const cached = snapshotHash && this.recallSnapshotCache?.hash === snapshotHash ? this.recallSnapshotCache : undefined;
+        const raw = cached ? undefined : derived?.artifact(COMPILE_SNAPSHOT);
+        let snapshot;
+        if (cached)
+            snapshot = cached.snapshot;
+        else if (raw)
+            snapshot = JSON.parse(raw);
+        else {
+            // Upgrade path for stores built before compiled snapshots existed.
+            const manifest = JSON.parse(derived?.artifact('build-manifest.json') ?? '{}');
+            snapshot = {
+                version: manifest.version ?? 0, compileRunId: manifest.compileRunId,
+                notes: JSON.parse(derived?.artifact(WIKI_NOTES) ?? derived?.artifact(LEGACY_UNITS) ?? '[]'),
+                cards: liveCards, graph: JSON.parse(derived?.artifact('knowledge_graph.json') ?? '{"nodes":[],"edges":[]}'),
+                diagnosisGraph: JSON.parse(derived?.artifact(DIAGNOSIS_GRAPH) ?? '{"nodes":[],"edges":[]}'),
+                placements: [], knowledge: [],
+            };
+        }
+        if (snapshot.notes.length === 0)
+            return failure(empty(), 'INDEX_NOT_READY', '知识索引尚未构建，请先编译知识库', true, '先执行 rebuild_knowledge，再进行召回。');
+        const capturedFts = { ready: derived?.hasFts() ?? false, hits: derived?.searchFts(query, candidatePool) ?? [] };
+        const capturedVector = cached ? cached.vector : decodeVectorIndex(derived?.vectorIndex(), ENCODER_FINGERPRINT);
+        if (this.environmentGuard && recallMode !== 'fts' && (!capturedVector
+            || capturedVector.manifest.provider !== this.config.embeddingProvider
+            || capturedVector.manifest.dimension !== this.config.embeddingDimension
+            || capturedVector.manifest.model !== this.embeddingModelId
+            || capturedVector.manifest.modelFingerprint !== this.embeddingFingerprint())) {
+            return failure(empty(), 'INDEX_NOT_READY', '环境已准备，但当前模型的向量索引尚未构建，请重新编译知识库', true, '执行 rebuild_knowledge，完成后再召回。');
+        }
+        if (snapshotHash)
+            this.recallSnapshotCache = { hash: snapshotHash, snapshot, vector: capturedVector };
+        const eventLineage = withRun(lineage, 'recall');
+        const indexVersion = capturedVector?.manifest.version;
+        const compileRunId = snapshot.compileRunId;
+        const knowledgeIndexVersion = snapshot.version;
+        const truthAtRead = await this.storeHandle();
+        const liveSourceIds = new Set(truthAtRead?.raw('SELECT entity_id FROM source').all()?.map(row => row.entity_id) ?? []);
+        const snapshotCardByKey = new Map(snapshot.cards.map(card => [cardKey(card), card]));
+        for (const key of liveKeys) {
+            if (snapshotCardByKey.get(key)?.sourceRefs.some(ref => !liveSourceIds.has(ref)))
+                liveKeys.delete(key);
+        }
+        let publishedGraph = visibleGraph(snapshot.graph, truthAtRead ? liveGraphKeys(truthAtRead) : new Set());
+        const currentByKey = new Map(liveCards.map(card => [cardKey(card), card]));
+        let cards = snapshot.cards.filter(card => liveKeys.has(cardKey(card))).map(card => {
+            const current = currentByKey.get(cardKey(card));
+            return { ...card, status: current.status, annotations: current.annotations, review: current.review,
+                metadata: { ...card.metadata, ...(current.metadata.evidence_needs_review === true ? { evidence_needs_review: true } : {}) } };
+        });
+        const eligible = snapshot.notes.filter(unit => liveKeys.has(`${unit.entityType}:${unit.entityId}`)
+            && (includeProblems || currentByKey.get(`${unit.entityType}:${unit.entityId}`)?.status !== 'problem'));
         const eligibleIds = new Set(eligible.map(unit => unit.unitId));
-        const cards = this.cards.length > 0 ? this.cards : await this.loadCards();
         const queryTerms = [...new Set(segment(query))];
         const warnings = [];
         // 一份 SourceRaw 语料，两处要用：关键词路的**查询词覆盖率**必须对着「建索引时那份
@@ -8977,16 +9249,19 @@ export class KnowledgeRuntime {
         const relationMs = performance.now() - relationStarted;
         const ftsStarted = performance.now();
         const ftsOutcome = useFts
-            ? await this.ftsRoute(query, eligible, candidatePool, this.config.keywordThreshold, titleOf)
+            ? await this.ftsRoute(query, eligible, candidatePool, this.config.keywordThreshold, titleOf, capturedFts)
             : { ranking: [], rows: [], diagnostic: { route: 'fts', status: 'skipped', reason: '当前模式未启用关键词路' } };
         const ftsMs = performance.now() - ftsStarted;
         const vectorStarted = performance.now();
         const vectorOutcome = useVector
-            ? await this.vectorRoute(query, eligibleIds, candidatePool, this.config.vectorThreshold, knowledgeIndexVersion)
+            ? await this.vectorRoute(query, eligibleIds, candidatePool, this.config.vectorThreshold, knowledgeIndexVersion, capturedVector)
             : { ranking: [], rows: [], diagnostic: { route: 'vector', status: 'skipped', reason: '当前模式未启用向量路' }, health: { ok: false, reason: '当前模式未启用向量路' } };
+        if (this.environmentGuard && useVector && vectorOutcome.diagnostic.status === 'degraded') {
+            return failure(empty(), 'ENVIRONMENT_NOT_READY', `向量推理失败：${vectorOutcome.diagnostic.reason ?? '未知原因'}`, true, '在 Tita 设置中重新自检环境后再召回。');
+        }
         const vectorMs = performance.now() - vectorStarted;
         const graphStarted = performance.now();
-        const graphRanking = useGraphBoost ? await this.graphBoostRanking(query, eligible, includeProblems) : [];
+        const graphRanking = useGraphBoost ? await this.graphBoostRanking(query, eligible, includeProblems, publishedGraph, snapshot.diagnosisGraph) : [];
         const graphMs = performance.now() - graphStarted;
         if (coordinateForRecall.diagnostic.status === 'degraded' && coordinateForRecall.diagnostic.reason)
             warnings.push(coordinateForRecall.diagnostic.reason);
@@ -9057,10 +9332,18 @@ export class KnowledgeRuntime {
             if (reranked.warning)
                 warnings.push(reranked.warning);
         }
+        if (this.environmentGuard && rerank.status === 'unavailable') {
+            return failure(empty(), 'ENVIRONMENT_NOT_READY', `重排推理失败：${rerank.error ?? '未知原因'}`, true, '在 Tita 设置中重新自检环境后再召回。');
+        }
         // 重排换的是相关性顺序，评分加权仍然要压在最上面 —— 否则「review 过的排前面一点」
         // 只在关掉重排时成立，而重排默认是开着的。
         hits = [...hits].sort((left, right) => rankKey(right) - rankKey(left) || left.unitId.localeCompare(right.unitId));
         // --- R4 · 证据片段 -----------------------------------------------------
+        const truth = await this.storeHandle();
+        cards = cards.filter(card => truth?.card(card.entityId) !== undefined && card.sourceRefs.every(ref => truth?.source(ref) !== undefined));
+        const finalKeys = new Set(cards.map(card => cardKey(card)));
+        publishedGraph = visibleGraph(publishedGraph, truth ? liveGraphKeys(truth) : new Set());
+        hits = hits.filter(hit => finalKeys.has(`${hit.entityType}:${hit.entityId}`));
         await this.attachEvidence(hits, queryTerms, corpus);
         /**
          * --- R4.5 · 支撑这一段的知识（0069）--------------------------------------
@@ -9068,7 +9351,13 @@ export class KnowledgeRuntime {
          * 排在证据**之后**、去重**之前**：它挂在每条 note 上，按卡片去重时自然跟着
          * 被选中的那一条走（`ContextItem.knowledge` 读的就是 `notes[0].knowledge`）。
          */
-        await this.attachKnowledge(hits);
+        await this.attachKnowledge(hits, snapshot);
+        if (cards.some(card => card.metadata.evidence_needs_review === true))
+            warnings.push('部分卡片缺少知识落位记录，删除来源后无法核对每段正文的归属，需要人工复核。');
+        if (hits.some(hit => hit.knowledge?.some(row => row.requiresReview)))
+            warnings.push('部分知识依据历史或未记录版本的证据，需人工复核；证据变化不表示知识已失效。');
+        if (hits.some(hit => hit.knowledge?.length))
+            warnings.push('引用核验仅检查来源定位；引用完整不代表陈述已通过语义核验。');
         // --- R5 · 弃答 ---------------------------------------------------------
         // 一路都没过阈值 = 这个知识库里没有能回答这个问题的东西。与其凑满 topN 让模型编，
         // 不如明确说「没有」：这是产品诚实性的一部分，也是 eval 里「不应召回」样本的落点。
@@ -9136,21 +9425,21 @@ export class KnowledgeRuntime {
             .map(([key, notes]) => ({ key, notes, card: cardByKey.get(key) }))
             .slice(0, contextTopN);
         const wiki = hitCards.map(item => item.card).filter((card) => card !== undefined);
-        const graph = this.oneHopGraph(new Set(hitCards.map(item => item.key)), includeProblems);
+        const graph = this.oneHopGraph(new Set(hitCards.map(item => item.key)), includeProblems, publishedGraph);
         /**
          * **在去重之后**做 1 跳扩展（0050 的第二半）。
          *
          * 反过来（先扩展再去重）会把邻居与被命中的卡片混在一起，分不清「这是召回来的」
          * 还是「这是邻居」—— 而这两件事在上下文里必须能分开，前者是证据，后者是延伸。
          */
-        const expansion = this.expandWiki(hitCards.map(item => item.key), cardByKey, includeProblems);
+        const expansion = this.expandWiki(hitCards.map(item => item.key), cardByKey, includeProblems, publishedGraph);
         /** 上下文条目：先命中的卡片（带它们的 note），再扩展来的卡片。 */
         const items = [
             ...hitCards.map(item => ({
                 wiki: item.card ?? null,
                 notes: item.notes,
                 note: item.notes[0],
-                graph: this.oneHopGraph(new Set([item.key]), includeProblems),
+                graph: this.oneHopGraph(new Set([item.key]), includeProblems, publishedGraph),
                 reason: 'hit',
                 ...(item.notes[0].evidence ? { evidence: item.notes[0].evidence } : {}),
                 ...(item.notes[0].knowledge ? { knowledge: item.notes[0].knowledge } : {}),
@@ -9163,7 +9452,7 @@ export class KnowledgeRuntime {
                 return {
                     wiki: card,
                     notes: [],
-                    graph: this.oneHopGraph(new Set([key]), includeProblems),
+                    graph: this.oneHopGraph(new Set([key]), includeProblems, publishedGraph),
                     reason: 'expansion',
                     ...(from === undefined ? {} : { via: { entityType: from.entityType, entityId: from.entityId, title: from.title, relation: relation ?? '' } }),
                 };
@@ -9271,11 +9560,11 @@ export class KnowledgeRuntime {
      * 2. **量纲**：返回**原始余弦**，不再做 `(cos+1)/2` 的映射 —— 那个映射让 `0.15` 这类阈值
      *    失去意义（余弦 0 → 0.5，轻松过线）。原始余弦是绝对量，可以直接用于弃答。
      */
-    async vectorRecall(query, eligibleIds, candidateLimit) {
-        const index = await this.loadVectorIndex();
+    async vectorRecall(query, eligibleIds, candidateLimit, captured) {
+        const index = captured ?? await this.loadVectorIndex();
         if (!index || index.manifest.itemCount === 0)
             throw new Error('VECTOR_INDEX_NOT_READY');
-        if (index.manifest.provider !== this.config.embeddingProvider || index.manifest.model !== this.embeddingModelId || index.manifest.dimension !== this.config.embeddingDimension)
+        if (index.manifest.provider !== this.config.embeddingProvider || index.manifest.model !== this.embeddingModelId || index.manifest.modelFingerprint !== this.embeddingFingerprint() || index.manifest.dimension !== this.config.embeddingDimension)
             throw new Error('VECTOR_INDEX_CONFIG_MISMATCH');
         // 查询编码单独计时：模型没加载时这一段是 8 秒，加载之后是 0.3 秒 —— 这一段的
         // 数字就是「测试为什么慢」的答案本身，混进扫描时间里就看不出来了。
@@ -9327,6 +9616,44 @@ export class KnowledgeRuntime {
             embeddingModelId: this.embeddingModelId,
         };
     }
+    /** Installed resources become available without restarting the host. */
+    reloadResources() {
+        this.embeddingWorker?.close();
+        this.embeddingWorker = null;
+        this.rerankWorker?.close();
+        this.rerankWorker = null;
+        this.encoderHealth = undefined;
+        this.rerankUnavailable = undefined;
+        this.updateConfig({ python: this.config.python, embeddingModel: this.config.embeddingModel, rerankModel: this.config.rerankModel });
+    }
+    async environmentProbe(kind) {
+        await mkdir(this.rootDir, { recursive: true });
+        if (kind === 'embedding') {
+            this.encoderHealth = undefined;
+            const health = await this.checkEncoder();
+            return { ok: health.ok, message: health.ok ? `已完成 ${this.config.embeddingDimension} 维向量推理，未发现零向量或相同向量退化` : health.reason ?? '向量推理自检失败' };
+        }
+        if (this.config.rerankProvider === 'none')
+            return { ok: false, message: '重排模型未启用' };
+        try {
+            if (!this.rerankWorker)
+                this.rerankWorker = this.spawnWorker('RERANK');
+            const response = await this.rerankWorker.request({ task: 'rerank', model: this.rerankModelPath, device: this.config.embeddingDevice,
+                query: '销售额按签收时间统计', documents: ['销售额按签收时间统计，签收后计入销售额。', '烹饪意大利面需要煮沸清水并加入面条。'] }, this.config.rerankTimeoutMs);
+            const scores = response?.scores;
+            if (!Array.isArray(scores) || scores.length !== 2 || scores.some(value => typeof value !== 'number' || !Number.isFinite(value)))
+                throw new Error('重排自检返回分数无效');
+            if (Number(response.vocabSize) < 1000 || !Number.isFinite(Number(response.vocabSize)))
+                throw new Error('重排模型分词器词表缺失或退化');
+            if (scores[0] <= scores[1])
+                throw new Error('重排模型未能把直接相关文本排在无关文本前');
+            this.rerankUnavailable = undefined;
+            return { ok: true, message: '分词器与实际重排推理通过自检' };
+        }
+        catch (cause) {
+            return { ok: false, message: cause instanceof Error ? cause.message : String(cause) };
+        }
+    }
     async embeddingHealth() {
         const index = await this.loadVectorIndex();
         return success({
@@ -9437,9 +9764,12 @@ export class KnowledgeRuntime {
          * 「盘上还没有编译产物」（`needsBuild`），要不要编由界面和 Agent 自己决定 ——
          * 与 `recall` 同一条规矩：先读盘，读不到再说。
          */
-        if (this.units.length === 0 && this.graph.nodes.length === 0)
-            await this.loadCompiledState();
-        const needsBuild = this.units.length === 0 && this.graph.nodes.length === 0;
+        const derived = await this.derivedHandle();
+        const snapshot = derived?.artifact(COMPILE_SNAPSHOT);
+        const rawGraph = snapshot ? JSON.parse(snapshot).graph : JSON.parse(derived?.artifact('knowledge_graph.json') ?? '{"nodes":[],"edges":[]}');
+        const truth = await this.storeHandle();
+        const graph = visibleGraph(rawGraph, truth ? liveGraphKeys(truth) : new Set());
+        const needsBuild = !snapshot && graph.nodes.length === 0;
         const attachLineage = (data) => eventLineage ? { ...data, lineage: eventLineage } : data;
         /** 空图 + 一句为什么空：调用方（尤其是 Agent）不能把「还没编译」读成「这个库没有知识」。 */
         const attachBuild = (data) => needsBuild ? { ...data, needsBuild: true } : data;
@@ -9452,11 +9782,11 @@ export class KnowledgeRuntime {
             return success(attachLineage({ types: this.wikiSchema().types.filter(def => def.enabled).map(def => def.id), relationTypes: ['supported_by', RELATES_TO] }));
         const includeProblem = options.includeProblem === true;
         const visible = (node) => includeProblem || node.status !== 'problem';
-        const allNodes = this.graph.nodes
+        const allNodes = graph.nodes
             .filter(visible)
             .filter(node => !options.status || node.status === options.status);
         const nodes = allNodes.filter(node => !entityType || node.type === entityType);
-        const edges = this.graph.edges.filter(edge => allNodes.some(node => `${node.type}:${node.id}` === String(edge.from)) && allNodes.some(node => `${node.type}:${node.id}` === String(edge.to)));
+        const edges = graph.edges.filter(edge => allNodes.some(node => `${node.type}:${node.id}` === String(edge.from)) && allNodes.some(node => `${node.type}:${node.id}` === String(edge.to)));
         if (action === 'list')
             return success(attachLineage(attachBuild({ nodes: nodes.slice(0, limit), edges: edges.slice(0, limit) })));
         const nodeKey = (rawId, rawType) => {