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

package/src/runtime.ts

@@ -25,7 +25,7 @@ import { MAX_LOG_ITEMS, OperationLog, operationId } from './oplog.js'
 import { ExtractionRunStore, extractionRunId, type ExtractionRunPage, type ExtractionRunRecord, type ExtractionRunSummary } from './extraction-runs.js'
 import { AxisRegistry, normalizeAxisName, type AxisEntity, type AxisGuidance, type AxisGuidanceKind, type AxisKind, type AxisRelation, type AxisResolution, type AxisStatus } from './axis-registry.js'
 import { KNOWLEDGE_STATE_LABEL, KnowledgeStore, type Knowledge, type KnowledgeDocumentImpact, type KnowledgeDocumentRemoval, type KnowledgeFacets, type KnowledgeIngest, type KnowledgeIngestResult, type KnowledgeQuery, type KnowledgeState, type KnowledgeVersion } from './knowledge.js'
-import type { EventEntity, EventSourceRecord } from './events.js'
+import { compositeEventIdentity, eventEntityFromRecords, type EventEntity, type EventSourceRecord } from './events.js'
 import type { TrialAxis, TrialEvent, TrialKnowledge, TrialSource, TrialTokenUsage } from './wiki-trial-types.js'
 import { buildAliasIndex, candidateEntityId, extractCandidates, normalizeCandidates, RELATES_TO, type NormalizedCandidates } from './extract.js'
 import { skeletonBody, type ModelCall } from './extract-model.js'
@@ -44,15 +44,23 @@ import {
   RELATED_METADATA_KEY, type DeadLink, type RelatedEntry,
 } from './wiki-finalize.js'
 import { applyRerank, applyThreshold, evidenceExcerpts, graphBoost, matchOf, noteIndexText, reviewWeight, rrfFuse, tokenSet, type RouteRanking } 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, type CardKnowledgeRow, type Journal as StoreJournal, type SourceOriginal } from './store/knowledge-db.js'
 import { exportKnowledgeTree as exportTree, migrateKnowledgeTree } from './store/migrate.js'
-import { DerivedDb, DERIVED_DB_FILE } from './store/derived.js'
+import { COMPILE_SNAPSHOT, type CompileSnapshot } from './compiler/snapshot.js'
+import { decodeVectorIndex, type LoadedVectorIndex, type VectorManifest } from './retrieval/vector-index.js'
+import { liveGraphKeys, visibleGraph } from './retrieval/visibility.js'
+import { embeddingFingerprint } from './compiler/embedding-identity.js'
+import { DerivedDb, DERIVED_DB_FILE, type DerivedPublication, type FtsHit } from './store/derived.js'
 import { cardVersions as viewCardVersions, documentDetail as viewDocumentDetail, documentList as viewDocumentList, documentVersions as viewDocumentVersions, type ViewHooks } from './store/views.js'
+import { assessKnowledgeEvidence, hasCurrentSupport } from './source-evidence.js'
+import { redirectAxisReferences } from './store/axis-references.js'
 import { unlinkIfExists, writeBufferAtomic, writeTextAtomic } from './fs-atomic.js'
 import { envelopeFailure, envelopeSuccess } from 'dsh-data-contracts/envelope'
 import type { LineageContext, LineageRef } from 'dsh-data-contracts/refs'
 import { analyzeQuery, relationCandidates, type QueryAnalysis } 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`。
 //
@@ -302,34 +310,6 @@ const BIT_COUNTS = Array.from({ length: 256 }, (_, value) => {
   return count
 })
 
-interface VectorItem {
-  unitId: string
-  contentHash: string
-}
-
-interface VectorManifest {
-  version: number
-  createdAt: string
-  provider: KnowledgeConfig['embeddingProvider']
-  model: string
-  /**
-   * 编码实现的指纹（0031）。旧清单没有这个字段 → 视为不兼容，于是修复编码器之后
-   * 一定触发一次真正的重编码，而不是把旧向量按 contentHash 复用回来。
-   */
-  encoder?: string
-  device: string
-  dimension: number
-  quantization: typeof VECTOR_QUANTIZATION
-  itemCount: number
-  items: VectorItem[]
-}
-
-interface LoadedVectorIndex {
-  manifest: VectorManifest
-  binary: Buffer
-  int8: Buffer
-}
-
 interface EmbeddingInput {
   text: string
   image?: string
@@ -586,12 +566,18 @@ function withTitleAlias(metadata: Record<string, unknown>, previousTitle: string
  * 同一句话在上下文里出现很多遍。完整出处在知识接口里。
  */
 function recallKnowledgeOf(row: Knowledge, section: string): RecallKnowledge {
-  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 } : {}),
@@ -1092,51 +1078,6 @@ function withEventReferences(
   return `${base ? `${base}\n\n` : ''}## 关联 Event\n\n${bullets.join('\n')}`
 }
 
-function eventEntityFromRecords(input: {
-  id: string
-  identityKey: string
-  identityType: EventEntity['identityType']
-  records: EventSourceRecord[]
-  createdAt: string
-  updatedAt?: string
-}): EventEntity {
-  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<string, TrialSource>()
-  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: string, incoming: string): string {
   if (!existing) return incoming
@@ -1780,8 +1721,8 @@ export interface WikiSchemaSnapshot {
 /**
  * 解析三个「家当」路径（0029）。
  *
- * 优先级：**配置里显式写的值**（由构造函数处理）> `<agentRoot>/resource/…`（存在时）
- * > 兜底（`python3` / HF 模型名）。
+ * 资源目录内的隔离解释器优先于 DSH_PYTHON；自定义配置路径仍由构造函数处理。
+ * 未准备资源时回退到 DSH_PYTHON、`python3` 或 HF 模型名。
  *
  * `modelId` 把本地模型的**身份**与它的位置解耦，避免同一 Agent 根目录下的
  * resource 目录变化导致向量清单误判为配置不匹配。
@@ -1790,6 +1731,7 @@ function resolveResources(resourceRoot: string | undefined): {
   python: string
   embeddingModel: string
   rerankModel: string
+  embeddingDimension?: number
   modelId: (path: string) => string
 } {
   const root = resourceRoot ? resolve(resourceRoot) : undefined
@@ -1798,15 +1740,22 @@ function resolveResources(resourceRoot: string | undefined): {
     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: string): string => {
     for (const base of [root]) {
       if (!base || !path.startsWith(`${base}${sep}`)) continue
@@ -1815,10 +1764,19 @@ function resolveResources(resourceRoot: string | undefined): {
     }
     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: string | undefined, resourcePython: string): string {
+  const selected = configured?.trim()
+  const hostPython = process.env.DSH_PYTHON?.trim()
+  return selected && selected !== hostPython ? selected : resourcePython
 }
 
 export interface KnowledgeRuntimeOptions {
+  /** Production deployment requires a working Python + embedding + rerank stack. */
+  environmentGuard?: () => Promise<void>
   /**
    * 这一库的「坐标提取备注」（0068），人写的。
    *
@@ -1831,7 +1789,7 @@ export interface KnowledgeRuntimeOptions {
    * 0029：家当目录（`<agentRoot>/resource`）。
    *
    * 配置里那三个路径字段（`python` / `embeddingModel` / `rerankModel`）为空时，
-   * 它们从这里解析。省略时使用系统命令或模型名作为兜底 —— 独立运行时与单元
+   * 它们从这里解析。省略时使用 DSH Python、系统命令或模型名作为兜底 —— 独立运行时与单元
    * 测试不必先造一个根路径。
    */
   resourceRoot?: string
@@ -2042,6 +2000,7 @@ function blankProgress(
 }
 
 export class KnowledgeRuntime {
+  private readonly environmentGuard?: () => Promise<void>
   /** 当前生效的配置。volatile 改动会就地合并进来（见 `updateConfig`），所以它不是只读的。 */
   config: RuntimeKnowledgeConfig
   readonly rootDir: string
@@ -2137,6 +2096,8 @@ export class KnowledgeRuntime {
    */
   private derived: DerivedDb | null | undefined
   private derivedProblem: string | undefined
+  private publication?: DerivedPublication
+  private recallSnapshotCache?: { hash: string; snapshot: CompileSnapshot; vector: LoadedVectorIndex | null }
   /** 段内布局整理是否已经跑过（每个 runtime 一次）。 */
   private segmentsOrganized = false
   /**
@@ -2170,6 +2131,7 @@ export class KnowledgeRuntime {
   private vectorIndex: LoadedVectorIndex | null = null
   private vectorError: string | undefined
   private embeddingWorker: JsonLineWorker | null = null
+  private embeddingWorkerFingerprint?: string
   /** Separate process so a rerank model failure cannot take embeddings down. */
   private rerankWorker: JsonLineWorker | null = null
   /** Cache the first rerank failure; do not respawn a doomed model per recall. */
@@ -2187,7 +2149,8 @@ export class KnowledgeRuntime {
    * 清单里的模型名就对不上，整个向量索引被判成「配置不匹配」而作废，用户会莫名
    * 收到一次全量重编码。清单该记「是哪一个模型」，不是「它在哪」。
    */
-  private readonly embeddingModelId: string
+  private embeddingModelId: string
+  private readonly resourceRoot?: string
   /**
    * 这个知识库的记忆段（0032）。
    *
@@ -2210,9 +2173,12 @@ 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)
@@ -2224,6 +2190,10 @@ export class KnowledgeRuntime {
    * **每次现问**，不是在构造时定死：插件 apply 的时刻早于 `agent-default-model` 挂载，
    * 那时问一次只会得到 undefined，而定死之后就再也不会变（见 `modelCallProvider`）。
    */
+  private embeddingFingerprint(): string {
+    return embeddingFingerprint(this.embeddingModelPath, this.resourceRoot, this.config.embeddingProvider === 'ollama' ? this.config.embeddingBaseUrl : undefined)
+  }
+
   private modelSeamNow(): ModelSeam {
     if (this.modelSeamProvider) return this.modelSeamProvider(this.baseId)
     return this.staticModelCall ? { call: this.staticModelCall } : { why: '运行时没有注入模型接缝' }
@@ -2248,12 +2218,17 @@ export class KnowledgeRuntime {
   updateConfig(patch: Partial<RuntimeKnowledgeConfig>): void {
     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 ||
@@ -2266,15 +2241,17 @@ 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
-    if (patch.embeddingModel !== undefined) this.embeddingModelPath = patch.embeddingModel.trim() || this.embeddingModelPath
-    if (patch.rerankModel !== undefined) this.rerankModelPath = patch.rerankModel.trim() || this.rerankModelPath
+    this.pythonPath = resolveConfiguredPython(this.config.python, resources.python)
+    if (patch.embeddingModel !== undefined) this.embeddingModelPath = patch.embeddingModel.trim() || resources.embeddingModel
+    if (patch.rerankModel !== undefined) this.rerankModelPath = patch.rerankModel.trim() || resources.rerankModel
+    this.embeddingModelId = resources.modelId(this.embeddingModelPath)
   }
 
   // ------------------------------------------------- 固定卡片模板
@@ -2750,22 +2727,9 @@ export class KnowledgeRuntime {
   private async loadVectorIndex(): Promise<LoadedVectorIndex | null> {
     if (this.vectorIndex) return this.vectorIndex
     try {
-      const loaded = (await this.derivedHandle())?.vectorIndex()
-      if (loaded === undefined) return null
-      const manifest = loaded.manifest as VectorManifest
-      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 {
-      return null
-    }
+    } catch { return null }
   }
 
   private vectorWorkerPath(): string {
@@ -2804,6 +2768,13 @@ export class KnowledgeRuntime {
 
   private async encodeEmbeddings(inputs: EmbeddingInput[]): Promise<{ vectors: number[][]; device: string }> {
     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)
@@ -2832,10 +2803,22 @@ export class KnowledgeRuntime {
   }
 
   close(): void {
+    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. */
@@ -2880,13 +2863,15 @@ export class KnowledgeRuntime {
     // 「这份台账派生出了哪些结论」就回到关键词路回答 —— 那本来就是词面问题，不是图问题。
     const titleOf = (sourceId: string): string | undefined => byId.get(sourceId)
     try {
-      await (await this.derivedHandle())?.rebuildFts(
-        units.map(unit => ({
-          unitId: unit.unitId,
-          title: unit.title,
-          content: noteIndexText({ title: unit.title, content: unit.content, sourceRefs: unit.sourceRefs }, titleOf),
-        })),
-      )
+      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'
     } catch (cause) {
@@ -2896,13 +2881,14 @@ export class KnowledgeRuntime {
   }
 
   private async buildVectorIndex(units: KnowledgeUnit[], version: number): Promise<EmbeddingBuildResult> {
+    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) return { status: 'unavailable', count: 0, reused: 0, error: 'embeddingDimension 必须是 8 的倍数，才能进行 binary quantization' }
     const inputs = await this.vectorInputs(units)
     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)
@@ -2951,13 +2937,18 @@ 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: VectorManifest = { 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 })) }
+      const manifest: VectorManifest = { 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 条」的半成品。
        */
-      ;(await this.derivedHandle())?.putVectorIndex(manifest, binary, int8)
-      this.vectorIndex = { manifest, binary, int8 }
+      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 }
     } catch (cause) {
@@ -2973,7 +2964,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) { this.units = notes as KnowledgeUnit[]; break }
+        if (Array.isArray(notes)) { this.units = notes as KnowledgeUnit[]; break }
       } catch { /* the first build has not happened yet */ }
     }
     try {
@@ -3213,7 +3204,10 @@ export class KnowledgeRuntime {
      */
     let compile: ImportCompileReport | null = null
     if (input.compile !== false) {
-      const rebuilt = await this.rebuild('wiki', input.lineage)
+      let rebuilt: Envelope<RebuildReport> | undefined
+      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 ?? '未知原因'}`)
       } else {
@@ -3514,7 +3508,14 @@ export class KnowledgeRuntime {
    *
    * 失败一律返回 `null`，**不抛** —— 「知识库不可用」是一条要显示的结论，不是一个异常。
    */
+  private storeHandleOpening?: Promise<KnowledgeDb | null>
   private async storeHandle(): Promise<KnowledgeDb | null> {
+    if (this.store !== undefined) return this.store
+    this.storeHandleOpening ??= this.openStoreHandle()
+    return this.storeHandleOpening
+  }
+
+  private async openStoreHandle(): Promise<KnowledgeDb | null> {
     if (this.store !== undefined) return this.store
     const sqlite = await loadSqlite()
     if (sqlite === null) {
@@ -3674,7 +3675,14 @@ export class KnowledgeRuntime {
   }
 
   /** 派生库（`<库根>/derived.db`）：编译产物，**可整体删掉重算**。 */
+  private derivedHandleOpening?: Promise<DerivedDb | null>
   private async derivedHandle(): Promise<DerivedDb | null> {
+    if (this.derived !== undefined) return this.derived
+    this.derivedHandleOpening ??= this.openDerivedHandle()
+    return this.derivedHandleOpening
+  }
+
+  private async openDerivedHandle(): Promise<DerivedDb | null> {
     if (this.derived !== undefined) return this.derived
     const sqlite = await loadSqlite()
     if (sqlite === null) { this.derived = null; return null }
@@ -3701,7 +3709,8 @@ export class KnowledgeRuntime {
   private async writeArtifact(name: string, body: string): Promise<void> {
     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)
   }
 
   private async hasArtifact(name: string): Promise<boolean> {
@@ -4095,7 +4104,29 @@ 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: Array<{ row: CardKnowledgeRow; knowledge: Knowledge }> = []
+        for (const row of placements) {
+          const item = await store?.get(row.knowledgeId)
+          if (item) remaining.push({ row, knowledge: item })
+        }
+        const sections = new Map<string, string[]>()
+        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) { cardFailures += 1; if (firstCardFailure === '') firstCardFailure = cause instanceof Error ? cause.message : String(cause) }
     }
@@ -4353,7 +4384,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: CardLayoutRecord = { profile: input.profileId, hash, origin: 'model' }
@@ -4456,7 +4487,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)
@@ -4667,6 +4698,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)
@@ -5036,7 +5068,7 @@ export class KnowledgeRuntime {
   }
 
   /** 1-hop neighbourhood of a set of wiki cards inside the compiled graph. */
-  private oneHopGraph(keys: Set<string>, includeProblem: boolean): ContextGraph {
+  private oneHopGraph(keys: Set<string>, includeProblem: boolean, graph: ContextGraph = this.graph): ContextGraph {
     const visible = (node: Record<string, unknown>) => 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)
@@ -5136,7 +5168,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) return notes as WikiNote[]
+        if (Array.isArray(notes)) return notes as WikiNote[]
       } catch { /* the first build has not happened yet */ }
     }
     return []
@@ -5160,7 +5192,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,
     }))
@@ -5203,7 +5239,7 @@ export class KnowledgeRuntime {
   ): Promise<ExtractionOutcome> {
     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）。
@@ -5214,6 +5250,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 ?? '原因未知'} —— 本次退回规则抽取：`
@@ -5241,9 +5278,9 @@ export class KnowledgeRuntime {
     for (const source of ordered) {
       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
@@ -5257,7 +5294,8 @@ 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) throw cause
         outcome.warnings.push(`来源 ${source.sourceId} 的候选抽取失败，已跳过该来源：${cause instanceof Error ? cause.message : String(cause)}`)
@@ -5284,7 +5322,7 @@ export class KnowledgeRuntime {
      * 的卡片不算「变了」，所以重复编译不会反复写盘。
      */
     const folded = new Map<string, string>()
-    for (const [key, item] of pending) folded.set(key, appendExtracted(item.existing?.content ?? '', [item.content]))
+    for (const [key, item] of pending) folded.set(key, item.content)
     const view: Array<{ key: string; content: string; sourceRefs: string[] }> = []
     for (const [key, card] of byKey) view.push({ key, content: card.content, sourceRefs: card.sourceRefs })
     for (const [key, item] of pending) view.push({ key, content: folded.get(key) ?? '', sourceRefs: item.sourceRefs })
@@ -5358,9 +5396,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
 
@@ -5388,6 +5431,7 @@ 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
       }
@@ -5650,7 +5694,8 @@ export class KnowledgeRuntime {
     knowledgeIds: Record<string, string>,
     compileRunId?: string,
     modelInfo?: ModelSeam,
-  ): Promise<void> {
+  ): Promise<boolean> {
+    let extractionComplete = call === undefined
     // 判重索引要看到「这一轮前面几份来源刚抽出来的卡片」，否则同一实体跨两份文档
     // 会各建一张 —— 而那正是这次改造要修掉的那个 bug。
     const cards = [...byKey.values()]
@@ -5683,6 +5728,9 @@ export class KnowledgeRuntime {
     /** 撞名报了没有 —— 同一个名字被三个坐标撞到时报三次是噪声。 */
     const collisionReported = new Set<string>()
 
+    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))
@@ -5786,9 +5834,10 @@ export class KnowledgeRuntime {
       })
 
       /**
-       * 落轨迹、收知识。两件都**不影响这一次编译成不成** —— 审计与真源是旁路，
-       * 旁路坏了不能把主路一起拖垮（与操作日志同一条纪律）。
+       * 记录抽取轨迹，再写入事实真源。轨迹是审计；事实写入不完整时不能保存成功指纹，
+       * 下一次增量编译必须能够重试。
        */
+      extractionComplete = report.model.ok
       const summary = trialSummary(report)
       await this.recordExtractionRun({
         id: runId, docId: source.sourceId, title: source.title, summary,
@@ -5797,6 +5846,7 @@ export class KnowledgeRuntime {
       if (compileRunId) 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: Awaited<ReturnType<KnowledgeRuntime['ingestTrialEvents']>> = {
@@ -5815,6 +5865,7 @@ 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)
@@ -5832,7 +5883,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 真源`)
@@ -6063,6 +6114,7 @@ export class KnowledgeRuntime {
       ...(outcome.relationsBySource[source.sourceId] ?? []),
       ...ruleNormalized.relations,
     ]
+    return extractionComplete
   }
 
   /**
@@ -6204,7 +6256,7 @@ export class KnowledgeRuntime {
    * 调用点必须在**按卡片去重之后**：先扩展再去重会把邻居与命中混在一起，
    * 而上下文里必须分得清「这是召回来的」还是「这是延伸出来的」。
    */
-  private expandWiki(seedKeys: string[], cardByKey: Map<string, KnowledgeCard>, includeProblems: boolean): RecallExpansion {
+  private expandWiki(seedKeys: string[], cardByKey: Map<string, KnowledgeCard>, includeProblems: boolean, graph: ContextGraph = this.graph): RecallExpansion {
     const seeds = new Set(seedKeys)
     const visible = (card: KnowledgeCard): boolean => includeProblems || card.status !== 'problem'
     const via = new Map<string, string[]>()
@@ -6214,7 +6266,7 @@ export class KnowledgeRuntime {
       via.set(key, bucket)
     }
     const edges: Array<Record<string, unknown>> = []
-    for (const edge of this.graph.edges) {
+    for (const edge of graph.edges) {
       const type = String(edge.type)
       if (type === 'supported_by') continue
       const from = String(edge.from)
@@ -6733,14 +6785,22 @@ export class KnowledgeRuntime {
    * 与抽取轨迹**同一个数据库文件**（`<memoryDir>/knowledge.sqlite`）：它们是同一层
    * （领域实体与它的审计），而解析一条知识要同时读两边 —— 分两个文件只是多一次打开。
    */
+  private axisRegistryOpening?: Promise<AxisRegistry | null>
   async axisRegistry(): Promise<AxisRegistry | null> {
+    this.axisRegistryOpening ??= this.openAxisRegistry()
+    return this.axisRegistryOpening
+  }
+
+  private async openAxisRegistry(): Promise<AxisRegistry | null> {
     if (this.axesReady !== null) return this.axesReady ? this.axesStore : null
     /*
      * 0062 v2：轴注册表与 Knowledge 搬进**知识库文件**（`<库根>/knowledge.db`），不再是
      * 记忆段里那个 `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
@@ -7258,7 +7318,11 @@ export class KnowledgeRuntime {
   /** 并两个实体。被并的那个不删，转成 `merged` 并指向目标。 */
   async mergeAxes(fromId: string, intoId: string): Promise<boolean> {
     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` 空串 = 全局。 */
@@ -7276,14 +7340,22 @@ export class KnowledgeRuntime {
   /**
    * Knowledge 库（0063 §2）：事实真源。
    *
-   * 与轴注册表**同一个文件**（`<memoryDir>/knowledge.sqlite`）、**各自的表**。
+   * 与轴注册表共享经过校验的 `knowledge.db` 连接，使用各自的表。
    * 两个模块互不认识，靠 id 字符串耦合 —— 代价是没有数据库级引用完整性，
    * 收益是「一条知识挂了一个不存在的坐标」会被 §5.7 的坐标核验**报出来**，
    * 而不是被数据库静默拒绝。
    */
+  private knowledgeStoreOpening?: Promise<KnowledgeStore | null>
   async knowledgeStore(): Promise<KnowledgeStore | null> {
+    this.knowledgeStoreOpening ??= this.openKnowledgeStore()
+    return this.knowledgeStoreOpening
+  }
+
+  private async openKnowledgeStore(): Promise<KnowledgeStore | null> {
     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
@@ -7306,13 +7378,12 @@ export class KnowledgeRuntime {
       /*
        * 给每一处出处补上**它依据的是哪一版**（0062 v2）。
        *
-       * 补在这里而不是让每个调用方自己带：抽取与编译那条链路传的是 `documentId`，而
-       * 「现在是第几版」只有存储层知道。漏补的后果不是报错，而是「可追溯」少一半 ——
-       * 来源被人改过之后，没有任何东西能回答那条知识还算不算数。
+       * 抽取链路带实际读取版本；直接写入没有指定版本时，补当前来源版本。
+       * 版本用于追踪证据变化，不能据此裁定 Knowledge 是否失效。
        */
       const db = await this.storeHandle()
       const sources = (input.sources ?? []).map(source => {
-        if (!source.documentId) return source
+        if (!source.documentId || source.toVersion !== undefined) return source
         const version = db?.source(source.documentId)?.version
         return version === undefined ? source : { ...source, toVersion: version }
       })
@@ -7333,7 +7404,11 @@ export class KnowledgeRuntime {
      *
      * 调用方可以显式传 `false` 关掉它（试跑那条链路不需要这个字段）。
      */
-    try { return await store.list({ withCards: true, ...query }) } catch { return null }
+    try {
+      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 }
   }
 
   /** 读一条 Knowledge 的当前内容与版本时间线，供内容侧边栏使用。 */
@@ -7343,7 +7418,8 @@ export class KnowledgeRuntime {
     try {
       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 }
   }
 
@@ -7398,7 +7474,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 个文件」）又把它算成
@@ -7406,7 +7482,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 }
   }
 
@@ -7434,8 +7510,9 @@ export class KnowledgeRuntime {
   }
 
   /**
-   * 还有没有人在引用这个桶 —— 判据是**三处文本里出现过 `_assets/<bucket>/`**：
-   * 来源正文、来源 front matter 的 `metadata.assets`、卡片正文。
+   * 还有没有人在引用这个桶 —— 判据是来源正文、来源 front matter 的 `metadata.assets`、
+   * 卡片正文出现过 `_assets/<bucket>/`，或者它是 `images.publish` 写入的独立图床图片。
+   * 独立图片没有来源/卡片引用是正常状态，必须保留。
    *
    * 为什么三处都要看：桶名是**内容哈希的前 12 位**（`convert/ingest.ts`），不是来源 id。
    * 同一份内容以两个分类导入会共用同一个桶；而卡片正文会把图片引用**复制进去**
@@ -7443,7 +7520,7 @@ export class KnowledgeRuntime {
    *
    * 不看 `03_compiled/`：那是派生物，下一次 `rebuild` 会把指向已删图片的引用一起扔掉。
    */
-  private unreferencedBuckets(names: string[], sources: SourceRaw[], cards: KnowledgeCard[]): string[] {
+  private async unreferencedBuckets(names: string[], sources: SourceRaw[], cards: KnowledgeCard[]): Promise<string[]> {
     const referenced = new Set<string>()
     /**
      * **两种引用形式都算**：`assets/<桶>/`（新写的）与 `_assets/<桶>/`（存量）。
@@ -7462,7 +7539,38 @@ export class KnowledgeRuntime {
       if (Array.isArray(source.metadata.assets)) for (const item of source.metadata.assets) if (typeof item === 'string') collect(item)
     }
     for (const card of cards) collect(card.content)
-    return names.filter(name => !referenced.has(name))
+    const unreferenced: string[] = []
+    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 位作为桶名。
+   */
+  private async isPublishedImageBucket(name: string): Promise<boolean> {
+    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
   }
 
   /**
@@ -7532,7 +7640,7 @@ export class KnowledgeRuntime {
     if (names.length === 0) return { buckets: 0, files: 0, problems: [] }
     const problems: string[] = []
     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) {
@@ -7670,6 +7778,7 @@ export class KnowledgeRuntime {
   async ingestTrialKnowledge(input: {
     runId: string
     knowledge: TrialKnowledge[]
+    sourceVersions?: Record<string, number | undefined>
     objects: TrialAxis[]
     actions: TrialAxis[]
     scenes: TrialAxis[]
@@ -7689,7 +7798,7 @@ export class KnowledgeRuntime {
     ids: Record<string, string>
   }> {
     const store = await this.knowledgeStore()
-    if (store === null) return { saved: 0, merged: 0, skipped: 0, ids: {} }
+    if (store === null) 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
@@ -7700,7 +7809,7 @@ export class KnowledgeRuntime {
       if (usable.length === 0) { skipped += 1; continue }
       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,
@@ -7708,11 +7817,13 @@ 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 saved += 1
         /*
@@ -7901,13 +8012,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 {
         identityKey = 'source:' + input.sourceId + ':' + quoteKeyOf(event, evidence)
@@ -8010,7 +8115,12 @@ export class KnowledgeRuntime {
    */
   async rebuild(only: 'all' | 'schema' | 'wiki' | 'embeddings' = 'all', lineage?: LineageContext, options: { extract?: boolean; forceExtract?: boolean } = {}): Promise<Envelope<RebuildReport>> {
     const runId = newCompileRunId()
-    const result = await this.enqueueCompile(runId, only, lineage, options)
+    let result: Envelope<RebuildReport>
+    try { result = await this.enqueueCompile(runId, only, lineage, options) }
+    catch (cause) {
+      await this.settleProgressFailure(runId, cause)
+      throw cause
+    }
     /*
      * 同步调用方拿的是返回值，但**别人可能在轮询同一条进度记录**（面板正开着编译对话框，
      * 而 Agent 起了这一次）。结论两个出口都要有。
@@ -8108,7 +8218,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}`)
   }
@@ -8162,6 +8272,49 @@ export class KnowledgeRuntime {
    * 它」—— 那两件事分别在 `enqueueCompile()` 与 `rebuild()` / `startCompile()` 里。
    */
   private async compileOnce(runId: string, only: 'all' | 'schema' | 'wiki' | 'embeddings' = 'all', lineage?: LineageContext, options: { extract?: boolean; forceExtract?: boolean } = {}): Promise<Envelope<RebuildReport>> {
+    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: Knowledge[] = []
+        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: CompileSnapshot = 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
+    }
+  }
+
+  private async prepareCompile(runId: string, only: 'all' | 'schema' | 'wiki' | 'embeddings' = 'all', lineage?: LineageContext, options: { extract?: boolean; forceExtract?: boolean } = {}): Promise<Envelope<RebuildReport>> {
     /**
      * 进度记录**先占位**：`runId` 一落下去，这一趟就有了名字 —— 之后无论从哪个出口结束
      * （三种 return，或者抛异常），收口都能认出这条记录属于谁。
@@ -8224,23 +8377,16 @@ export class KnowledgeRuntime {
       this.writeCompileProgress({ ...(this.compileProgress ?? blankProgress(runId, only, startedAt, 'running', queuedAt)), ...patch })
     }
     /**
-     * 收口：四段一起标成完成，并写下一句结论。
-     *
-     * 它在 `rebuild()` 的**每一个** return 之前调用（一共三处出口）。少了任何一处，
-     * 那次编译的进度就会永远停在「进行中」—— 而界面拿它当「正在跑」，于是按钮一直灰着。
+     * 四段准备完成，保存结论。事务发布之前仍是 running；发布成功后由
+     * settleProgressReport 收口，发布失败则由 settleProgressFailure 收口。
      */
     const finishProgress = (outcome: string): void => {
       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,
@@ -8269,7 +8415,7 @@ export class KnowledgeRuntime {
     if (adoption.adopted > 0) this.cards = await this.loadCards()
 
     // ------------------------------------------------ previous build state
-    let previousManifest: { version?: number; builtAt?: string; cardHashes?: Record<string, string>; extractionHashes?: Record<string, string>; embedding?: unknown; diagnosisHash?: string; indexHash?: string } = {}
+    let previousManifest: { version?: number; builtAt?: string; cardHashes?: Record<string, string>; extractionHashes?: Record<string, string>; embedding?: unknown; embeddingIdentity?: string; diagnosisHash?: string; indexHash?: string } = {}
     try {
       previousManifest = JSON.parse(await this.readArtifact('build-manifest.json')) as typeof previousManifest
     } catch { /* first build */ }
@@ -8502,7 +8648,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() : []
       const previousByWiki = new Map<string, WikiNote[]>()
@@ -8574,7 +8721,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 用同一个编号。
@@ -8597,7 +8746,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')
@@ -8668,6 +8817,7 @@ 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} 边`
@@ -8680,7 +8830,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: RebuildReport = {
         runId: compileRunId, compileRunId, version, only,
         cards: this.cards.length, units: this.units.length, notes: this.units.length,
@@ -8732,6 +8882,7 @@ 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', [
@@ -8742,7 +8893,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: RebuildReport = {
       runId: compileRunId, compileRunId, version, only,
       cards: this.cards.length, units: this.units.length, notes: this.units.length,
@@ -8821,6 +8972,7 @@ 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
@@ -8974,13 +9126,13 @@ export class KnowledgeRuntime {
   }
 
   /** 关键词路：FTS5 + BM25（0031）。索引不在时如实降级，不退回旧的计数打分。 */
-  private async ftsRoute(query: string, eligible: WikiNote[], pool: number, threshold: number, titleOf: (sourceId: string) => string | undefined): Promise<{ ranking: RouteRanking[]; rows: Array<RouteRanking & { kept: boolean }>; diagnostic: RecallRouteDiagnostic }> {
+  private async ftsRoute(query: string, eligible: WikiNote[], pool: number, threshold: number, titleOf: (sourceId: string) => string | undefined, captured?: { ready: boolean; hits: FtsHit[] }): Promise<{ ranking: RouteRanking[]; rows: Array<RouteRanking & { kept: boolean }>; diagnostic: RecallRouteDiagnostic }> {
     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()) return { ranking: [], rows: [], diagnostic: { route: 'fts', status: 'degraded', reason: '关键词索引还没建（在 derived.db 里），先编译一次' } }
+    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`）：只蹭到一两个高频单字的命中在这里淘汰，
        * 于是「整批都弱」也能弃答 —— 这是相对阈值做不到的那一半。
@@ -9046,8 +9198,8 @@ export class KnowledgeRuntime {
    * 阈值就完全失去意义（余弦 0 会被映射成 0.5，轻松过线）。原始余弦是绝对量，可以直接
    * 用来判「这段内容和问题到底像不像」—— 弃答主要靠它和重排阈值。
    */
-  private async vectorRoute(query: string, eligibleIds: Set<string>, pool: number, threshold: number, expectedVersion?: number): Promise<{ ranking: RouteRanking[]; rows: Array<RouteRanking & { kept: boolean }>; diagnostic: RecallRouteDiagnostic; health: { ok: boolean; reason?: string }; timings?: { embedMs: number; scanMs: number } }> {
-    const index = await this.loadVectorIndex()
+  private async vectorRoute(query: string, eligibleIds: Set<string>, pool: number, threshold: number, expectedVersion?: number, captured?: LoadedVectorIndex | null): Promise<{ ranking: RouteRanking[]; rows: Array<RouteRanking & { kept: boolean }>; diagnostic: RecallRouteDiagnostic; health: { ok: boolean; reason?: string }; timings?: { embedMs: number; scanMs: number } }> {
+    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 } }
@@ -9059,7 +9211,7 @@ export class KnowledgeRuntime {
     const health = await this.checkEncoder()
     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 {
@@ -9101,10 +9253,10 @@ export class KnowledgeRuntime {
    * 是因为两张图的节点含义不同（一个是卡片，一个是字段级节点），合成一张会让
    * 图谱 Tab 看到一张卡片散成七个点。
    */
-  private diagnosisHits(queryTokens: string[]): Map<string, number> {
+  private diagnosisHits(queryTokens: string[], graph: ContextGraph = this.diagnosisGraph): Map<string, number> {
     const seed = new Map<string, number>()
-    if (this.diagnosisGraph.nodes.length === 0) return seed
-    for (const node of this.diagnosisGraph.nodes) {
+    if (graph.nodes.length === 0) return seed
+    for (const node of graph.nodes) {
       const title = String(node.title ?? '').toLocaleLowerCase()
       const id = String(node.id ?? '').toLocaleLowerCase()
       let score = 0
@@ -9115,7 +9267,7 @@ export class KnowledgeRuntime {
       if (score > 0) 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
@@ -9128,7 +9280,7 @@ export class KnowledgeRuntime {
     if (seed.size === 0) return seed
     const expanded = new Map<string, number>(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) expanded.set(to, Math.max(expanded.get(to) ?? 0, score * 0.5))
@@ -9138,8 +9290,8 @@ export class KnowledgeRuntime {
     return expanded
   }
 
-  private async graphBoostRanking(query: string, eligible: WikiNote[], includeProblems: boolean): Promise<RouteRanking[]> {
-    if (this.graph.nodes.length === 0) return []
+  private async graphBoostRanking(query: string, eligible: WikiNote[], includeProblems: boolean, graph: ContextGraph = this.graph, diagnosisGraph: ContextGraph = this.diagnosisGraph): Promise<RouteRanking[]> {
+    if (graph.nodes.length === 0) return []
     const queryTokens = segment(query)
     if (queryTokens.length === 0) return []
     const byNodeKey = new Map<string, number>()
@@ -9148,9 +9300,9 @@ export class KnowledgeRuntime {
     const nodeKey = (node: Record<string, unknown>): string => `${String(node.type)}:${String(node.id)}`
     /** 卡片级节点 id → 它的 `entity_type`。归因图的节点 id 与卡片 id 相等（§14.1）。 */
     const typeByEntityId = new Map<string, string>()
-    for (const node of this.graph.nodes) typeByEntityId.set(String(node.id), String(node.type))
+    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()
       const id = String(node.id ?? '').toLocaleLowerCase()
@@ -9161,7 +9313,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
@@ -9176,14 +9328,14 @@ 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)
     }
     if (byNodeKey.size === 0) return []
     const expanded = new Map<string, number>(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) expanded.set(to, Math.max(expanded.get(to) ?? 0, score * 0.5))
@@ -9263,7 +9415,7 @@ export class KnowledgeRuntime {
    * 这次召回少一条证据，而正确的答案是换成它被并进的那一条（`mergedInto` 只跳一跳：
    * 并进的目标自己不会再被并 —— 那正是「并」这个动作的定义）。
    */
-  private async attachKnowledge(hits: RecallHit[]): Promise<void> {
+  private async attachKnowledge(hits: RecallHit[], snapshot?: CompileSnapshot): Promise<void> {
     if (hits.length === 0) return
     const store = await this.storeHandle()
     if (store === null) return
@@ -9274,7 +9426,7 @@ export class KnowledgeRuntime {
      * 只取**命中这几张卡**的落位。用 `placements()`（全表）在这里是错的量级：
      * 一次召回十来张卡，而库里可能有上千张。
      */
-    try { placements = store.placementsOf([...new Set(hits.map(hit => hit.entityId))]) } catch { return }
+    try { placements = snapshot?.placements.length ? new Map(snapshot.placements) : store.placementsOf([...new Set(hits.map(hit => hit.entityId))]) } catch { return }
     /**
      * 每条命中要哪几条 Knowledge：以 Card 正文切出的 heading 为准。
      *
@@ -9290,7 +9442,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) as { status: KnowledgeState } | undefined
+          return live ? [[row.id, recallKnowledgeOf(assessKnowledgeEvidence({ ...row, status: live.status }, store), '')] as [string, RecallKnowledge]] : []
+        }))
+      : await this.readKnowledgeRows(knowledge, [...wanted])
     if (rows.size === 0) return
     hits.forEach((hit, index) => {
       const collected = new Map<string, RecallKnowledge>()
@@ -9318,11 +9477,11 @@ export class KnowledgeRuntime {
     const followup = new Map<string, string>()
     for (const row of rows.knowledge) {
       if (row.mergedInto !== '') followup.set(row.mergedInto, row.id)
-      else out.set(row.id, recallKnowledgeOf(row, ''))
+      else 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, ''))
+      for (const row of rows.knowledge) out.set(row.id, recallKnowledgeOf(assessKnowledgeEvidence(row, (await this.storeHandle())!), ''))
       // 目标也没了（例如它的来源被删了）：那条落位就是悬空的，如实**不显示**，
       // 而不是把一条已经不存在的事实塞进上下文。
     }
@@ -9377,25 +9536,59 @@ export class KnowledgeRuntime {
     if (!query?.trim()) return failure(empty(), 'QUERY_REQUIRED', 'query 不能为空', true)
     if (!Number.isInteger(recallTopK) || recallTopK < 1 || recallTopK > 50) 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，再进行召回。')
-      }
-    }
+    try { await this.environmentGuard?.() }
+    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: CompileSnapshot
+    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 = (await this.loadVectorIndex())?.manifest.version
-    let compileRunId: string | undefined
-    let knowledgeIndexVersion: number | undefined
-    try {
-      const manifest = JSON.parse(await this.readArtifact('build-manifest.json')) as { compileRunId?: unknown; version?: unknown }
-      if (typeof manifest.compileRunId === 'string' && manifest.compileRunId.trim()) compileRunId = manifest.compileRunId
-      if (typeof manifest.version === 'number' && Number.isInteger(manifest.version)) knowledgeIndexVersion = manifest.version
-    } catch { /* the first build has not happened yet */ }
-
-    const eligible = this.units.filter(unit => includeProblems || unit.status !== 'problem')
+    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() as Array<{ entity_id: string }> | undefined)?.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: KnowledgeCard[] = 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: string[] = []
     // 一份 SourceRaw 语料，两处要用：关键词路的**查询词覆盖率**必须对着「建索引时那份
@@ -9429,16 +9622,19 @@ export class KnowledgeRuntime {
 
     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: [] as RouteRanking[], rows: [] as Array<RouteRanking & { kept: boolean }>, diagnostic: { route: 'fts' as const, status: 'skipped' as const, 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: [] as RouteRanking[], rows: [] as Array<RouteRanking & { kept: boolean }>, diagnostic: { route: 'vector' as const, status: 'skipped' as const, 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)
@@ -9508,11 +9704,19 @@ export class KnowledgeRuntime {
       rerank = reranked.result
       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）--------------------------------------
@@ -9520,7 +9724,10 @@ 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 让模型编，
@@ -9589,7 +9796,7 @@ 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 is KnowledgeCard => 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 的第二半）。
@@ -9597,7 +9804,7 @@ export class KnowledgeRuntime {
      * 反过来（先扩展再去重）会把邻居与被命中的卡片混在一起，分不清「这是召回来的」
      * 还是「这是邻居」—— 而这两件事在上下文里必须能分开，前者是证据，后者是延伸。
      */
-    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: ContextItem[] = [
@@ -9605,7 +9812,7 @@ export class KnowledgeRuntime {
         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' as const,
         ...(item.notes[0]!.evidence ? { evidence: item.notes[0]!.evidence } : {}),
         ...(item.notes[0]!.knowledge ? { knowledge: item.notes[0]!.knowledge } : {}),
@@ -9618,7 +9825,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' as const,
           ...(from === undefined ? {} : { via: { entityType: from.entityType, entityId: from.entityId, title: from.title, relation: relation ?? '' } }),
         }
@@ -9729,10 +9936,10 @@ export class KnowledgeRuntime {
    * 2. **量纲**：返回**原始余弦**，不再做 `(cos+1)/2` 的映射 —— 那个映射让 `0.15` 这类阈值
    *    失去意义（余弦 0 → 0.5，轻松过线）。原始余弦是绝对量，可以直接用于弃答。
    */
-  private async vectorRecall(query: string, eligibleIds: Set<string>, candidateLimit: number): Promise<{ scores: Map<string, number>; embedMs: number; scanMs: number }> {
-    const index = await this.loadVectorIndex()
+  private async vectorRecall(query: string, eligibleIds: Set<string>, candidateLimit: number, captured?: LoadedVectorIndex): Promise<{ scores: Map<string, number>; embedMs: number; scanMs: number }> {
+    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) throw new Error('VECTOR_INDEX_CONFIG_MISMATCH')
+    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 秒 —— 这一段的
     // 数字就是「测试为什么慢」的答案本身，混进扫描时间里就看不出来了。
     const embedStarted = performance.now()
@@ -9781,6 +9988,35 @@ export class KnowledgeRuntime {
     }
   }
 
+  /** Installed resources become available without restarting the host. */
+  reloadResources(): void {
+    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: 'embedding' | 'rerank'): Promise<{ ok: boolean; message: string }> {
+    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: unknown = 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(): Promise<Envelope<Record<string, unknown>>> {
     const index = await this.loadVectorIndex()
     return success({
@@ -9887,8 +10123,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: ContextGraph = 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: Record<string, unknown>): Record<string, unknown> => eventLineage ? { ...data, lineage: eventLineage } : data
     /** 空图 + 一句为什么空：调用方（尤其是 Agent）不能把「还没编译」读成「这个库没有知识」。 */
     const attachBuild = (data: Record<string, unknown>): Record<string, unknown> => needsBuild ? { ...data, needsBuild: true } : data
@@ -9899,11 +10139,11 @@ export class KnowledgeRuntime {
 
     const includeProblem = options.includeProblem === true
     const visible = (node: Record<string, unknown>) => 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: string | undefined, rawType?: string): string | undefined => {